[codex] Retry max-turn exhausted heartbeats (#5096)

## Thinking Path

> - Paperclip orchestrates AI agents for autonomous companies, and
heartbeat execution is the control-plane loop that keeps assigned work
moving.
> - Max-turn exhaustion is a recoverable local-adapter stop condition
for Claude and Gemini agents when a run needs another heartbeat to
continue safely.
> - The previous behavior could leave max-turn continuation details hard
to inspect, and duplicate/stale continuation wakes could keep running
after issue state changed.
> - The adapter layer also needed to avoid trusting arbitrary
stdout/stderr text as scheduler control metadata.
> - This pull request adds bounded max-turn continuation scheduling,
visible retry state, structured stop metadata handling, and
stale/duplicate continuation guards.
> - The benefit is safer automatic continuation after max-turn stops,
clearer operator visibility, and fewer duplicate or stale agent runs.

## What Changed

- Replaces closed PR #4952, whose head repository was deleted.
- Rebases the recovered max-turn continuation branch onto current
`paperclipai/paperclip:master`.
- Adds max-turn continuation scheduling and retry-state plumbing for
heartbeat runs.
- Adds stale/duplicate continuation suppression when issue status,
ownership, or execution locks change.
- Normalizes Claude/Gemini max-turn detection around structured stop
metadata instead of unstructured stdout/stderr text.
- Surfaces max-turn continuation settings and retry visibility in the
board UI.
- Adds focused server, adapter, and UI tests for max-turn stop metadata,
retry scheduling, stale queued-run invalidation, adapter
parsing/execution, run ledger display, and agent config patching.

## Verification

- `pnpm install --no-frozen-lockfile` to refresh local dependencies
after rebasing onto current `master`.
- `pnpm run preflight:workspace-links && pnpm exec vitest run
server/src/__tests__/claude-local-adapter.test.ts
server/src/__tests__/claude-local-execute.test.ts
server/src/__tests__/gemini-local-adapter.test.ts
server/src/__tests__/gemini-local-execute.test.ts
server/src/__tests__/heartbeat-retry-scheduling.test.ts
server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts
server/src/services/heartbeat-stop-metadata.test.ts
ui/src/components/IssueRunLedger.test.tsx
ui/src/lib/agent-config-patch.test.ts ui/src/lib/runRetryState.test.ts
--testTimeout=20000`
- `pnpm --filter @paperclipai/adapter-claude-local typecheck && pnpm
--filter @paperclipai/adapter-gemini-local typecheck && pnpm --filter
@paperclipai/server typecheck && pnpm --filter @paperclipai/ui
typecheck`
- UI screenshot note: the UI changes are limited to config/ledger state
rendering rather than layout changes; component/unit coverage above
verifies the rendered behavior.

## Risks

- Medium behavior risk: heartbeat retry gating now suppresses max-turn
continuations when issue state or execution locks drift, so any callers
that relied on stale continuations running will now see cancellation
instead.
- Low adapter risk: Claude/Gemini unstructured text no longer triggers
max-turn scheduler metadata, so only structured stop signals and Gemini
exit code 53 are trusted.
- No database migrations.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex coding agent, GPT-5-class model, tool-enabled local
repository editing and command execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots (not applicable: state/default rendering only; covered by
component/unit tests)
- [x] I have updated relevant documentation to reflect my changes (not
applicable: no user-facing command or docs contract changed)
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

ui/src/lib/agent-config-patch.test.ts

@@ -108,6 +108,35 @@ describe("buildAgentUpdatePatch", () => {
     expect(patch.adapterConfig).toBeUndefined();
   });
 
+  it("writes max-turn continuation policy under runtimeConfig.heartbeat", () => {
+    const patch = buildAgentUpdatePatch(
+      makeAgent(),
+      makeOverlay({
+        heartbeat: {
+          maxTurnContinuation: {
+            enabled: true,
+            maxAttempts: 3,
+            delayMs: 1000,
+          },
+        },
+      }),
+    );
+
+    expect(patch).toEqual({
+      runtimeConfig: {
+        heartbeat: {
+          enabled: true,
+          intervalSec: 300,
+          maxTurnContinuation: {
+            enabled: true,
+            maxAttempts: 3,
+            delayMs: 1000,
+          },
+        },
+      },
+    });
+  });
+
   it("merges cheap profile changes onto existing runtimeConfig.modelProfiles state", () => {
     const agent = makeAgent();
     agent.runtimeConfig = {

ui/src/lib/runRetryState.test.ts

@@ -5,6 +5,7 @@ describe("runRetryState", () => {
   it("formats internal retry reasons for operators", () => {
     expect(formatRetryReason("transient_failure")).toBe("Transient failure");
     expect(formatRetryReason("issue_continuation_needed")).toBe("Continuation needed");
+    expect(formatRetryReason("max_turns_continuation")).toBe("Max-turn continuation");
     expect(formatRetryReason("custom_reason")).toBe("custom reason");
   });
 
@@ -24,6 +25,22 @@ describe("runRetryState", () => {
     });
   });
 
+  it("describes max-turn continuation retries distinctly", () => {
+    expect(
+      describeRunRetryState({
+        status: "scheduled_retry",
+        retryOfRunId: "run-max-turns",
+        scheduledRetryAttempt: 1,
+        scheduledRetryReason: "max_turns_continuation",
+        scheduledRetryAt: "2026-04-18T20:15:00.000Z",
+      }),
+    ).toMatchObject({
+      kind: "scheduled",
+      badgeLabel: "Continuation scheduled",
+      detail: "Attempt 1 · Max-turn continuation",
+    });
+  });
+
   it("describes exhausted retries", () => {
     expect(
       describeRunRetryState({

ui/src/lib/runRetryState.ts

@@ -24,6 +24,7 @@ const RETRY_REASON_LABELS: Record<string, string> = {
   process_lost: "Process lost",
   assignment_recovery: "Assignment recovery",
   issue_continuation_needed: "Continuation needed",
+  max_turns_continuation: "Max-turn continuation",
 };
 
 function readNonEmptyString(value: unknown) {
@@ -51,6 +52,7 @@ export function describeRunRetryState(run: RetryAwareRun): RunRetryStateSummary
   const retryOfRunId = readNonEmptyString(run.retryOfRunId);
   const exhaustedReason = readNonEmptyString(run.retryExhaustedReason);
   const dueAt = run.scheduledRetryAt ? formatDateTime(run.scheduledRetryAt) : null;
+  const isMaxTurnContinuation = run.scheduledRetryReason === "max_turns_continuation";
   const hasRetryMetadata =
     Boolean(retryOfRunId)
     || Boolean(reasonLabel)
@@ -63,10 +65,12 @@ export function describeRunRetryState(run: RetryAwareRun): RunRetryStateSummary
   if (run.status === "scheduled_retry") {
     return {
       kind: "scheduled",
-      badgeLabel: "Retry scheduled",
+      badgeLabel: isMaxTurnContinuation ? "Continuation scheduled" : "Retry scheduled",
       tone: "border-cyan-500/30 bg-cyan-500/10 text-cyan-700 dark:text-cyan-300",
       detail: joinFragments([attemptLabel, reasonLabel]),
-      secondary: dueAt ? `Next retry ${dueAt}` : "Next retry pending schedule",
+      secondary: dueAt
+        ? `${isMaxTurnContinuation ? "Next continuation" : "Next retry"} ${dueAt}`
+        : `${isMaxTurnContinuation ? "Next continuation" : "Next retry"} pending schedule`,
       retryOfRunId,
     };
   }
@@ -74,7 +78,7 @@ export function describeRunRetryState(run: RetryAwareRun): RunRetryStateSummary
   if (exhaustedReason) {
     return {
       kind: "exhausted",
-      badgeLabel: "Retry exhausted",
+      badgeLabel: isMaxTurnContinuation ? "Continuation exhausted" : "Retry exhausted",
       tone: "border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-300",
       detail: joinFragments([attemptLabel, reasonLabel, "Automatic retries exhausted"]),
       secondary: exhaustedReason.includes("Manual intervention required")
@@ -86,7 +90,7 @@ export function describeRunRetryState(run: RetryAwareRun): RunRetryStateSummary
 
   return {
     kind: "attempted",
-    badgeLabel: "Retried run",
+    badgeLabel: isMaxTurnContinuation ? "Continued run" : "Retried run",
     tone: "border-slate-500/20 bg-slate-500/10 text-slate-700 dark:text-slate-300",
     detail: joinFragments([attemptLabel, reasonLabel]),
     secondary: null,

ui/src/lib/utils.ts

@@ -7,6 +7,20 @@ export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs));
 }
 
+export function asObject(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+export function asBoolean(value: unknown, fallback: boolean) {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+export function asFiniteNumber(value: unknown, fallback: number) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
 export function formatCents(cents: number): string {
   return `$${(cents / 100).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
 }