agent-relay-runner 0.129.11 → 0.129.13

package/src/adapters/claude-transcript.ts

@@ -10,6 +10,7 @@
 // entry carrying text, not just tool_result blocks). We collect the assistant
 // `text` blocks from that turn — thinking and tool_use are dropped.
 
+import type { ToolCallCategory } from "agent-relay-sdk";
 import { computeContextRatio, type SessionAnalysis, type SessionEvent } from "../session-insights";
 
 interface TranscriptBlock {
@@ -25,6 +26,7 @@ export interface TurnStep {
   type: "narration" | "reasoning" | "tool";
   text: string;
   label?: string;
+  category?: ToolCallCategory;
   occurredAt?: number;
 }
 
@@ -32,6 +34,28 @@ interface TranscriptMessage {
   role?: string;
   content?: string | TranscriptBlock[];
   stop_reason?: string;
+  // Assistant entries carry the model id and the API-reported token usage for
+  // the turn. `usage.{input,cache_creation_input,cache_read_input}_tokens` sum to
+  // the same context-size figure the status-line probe reports — read here so the
+  // runner can keep context stats advancing every turn without the probe (#1512).
+  model?: string;
+  usage?: TranscriptUsage;
+}
+
+interface TranscriptUsage {
+  input_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+  output_tokens?: number;
+}
+
+/** Fresh, per-turn context usage read straight from the transcript (#1512). */
+export interface TranscriptContextUsage {
+  /** input + cache-creation + cache-read tokens — the context size sent this turn. */
+  tokensUsed: number;
+  model?: string;
+  /** Wall-clock ms of the assistant entry, when the transcript stamps one. */
+  occurredAt?: number;
 }
 
 interface TranscriptEntry {
@@ -361,7 +385,7 @@ export class LatestTurnStepAccumulator {
       } else if (b.type === "thinking" && typeof b.thinking === "string" && b.thinking.trim()) {
         this.latestSteps.push({ type: "reasoning", text: b.thinking.trim(), ...(occurredAt ? { occurredAt } : {}) });
       } else if (b.type === "tool_use" && typeof b.name === "string" && b.name) {
-        this.latestSteps.push({ type: "tool", label: b.name, text: summarizeToolUse(b.name, b.input), ...(occurredAt ? { occurredAt } : {}) });
+        this.latestSteps.push({ type: "tool", label: b.name, text: summarizeToolUse(b.name, b.input), category: claudeToolCategory(b.name), ...(occurredAt ? { occurredAt } : {}) });
       }
     }
   }
@@ -392,6 +416,28 @@ export function stepDedupKeys(steps: TurnStep[]): string[] {
   });
 }
 
+// #1498: Claude's native tool names → the provider-independent category taxonomy. Tools with
+// no dedicated category (Grep, Glob, LS, WebFetch, WebSearch, ...) fall to "generic" rather than
+// being force-fit into a category that doesn't really describe them — the fallback exists
+// precisely so nothing is hidden from the dashboard's activity trace.
+const CLAUDE_TOOL_CATEGORIES: Record<string, ToolCallCategory> = {
+  Bash: "cli-bash",
+  Read: "read",
+  Edit: "edit",
+  Write: "edit",
+  NotebookEdit: "edit",
+  AskUserQuestion: "ask-user-question",
+  ExitPlanMode: "plan",
+  Task: "agent-spawn",
+  ToolSearch: "mcp-tool-search",
+};
+
+/** Map a Claude tool_use name onto the provider-independent tool-call category (#1498). */
+export function claudeToolCategory(name: string): ToolCallCategory {
+  if (name.startsWith("mcp__")) return "mcp-tool-call";
+  return CLAUDE_TOOL_CATEGORIES[name] ?? "generic";
+}
+
 /** Compact one-line summary of a tool invocation for the discreet activity row. */
 export function summarizeToolUse(name: string, input: Record<string, unknown> | undefined): string {
   const str = (key: string): string | undefined => (input && typeof input[key] === "string" ? (input[key] as string) : undefined);
@@ -475,6 +521,54 @@ export function countSubstantiveTurns(jsonl: string): number {
   return turns;
 }
 
+// Walk the transcript from the end and return the most recent root-session
+// assistant turn's token usage (#1512). This is the SAME input+cache token sum
+// the Claude status-line probe reports, but read directly from the transcript —
+// which the Stop hook hands the runner every turn — so context stats keep
+// advancing across compact/clear/native-resume even when the status-line probe
+// goes silent. Sidechain (subagent) entries are skipped so a Task's usage never
+// masquerades as the root session's context size.
+export function extractLatestContextUsage(jsonl: string): TranscriptContextUsage | undefined {
+  const lines = jsonl.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const trimmed = lines[i]?.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (entry.type !== "assistant" || isSidechainEntry(entry)) continue;
+    const usage = entry.message?.usage;
+    if (!usage) continue;
+    const tokensUsed = sumUsageTokens(usage);
+    if (tokensUsed === undefined) continue;
+    const occurredAt = typeof entry.timestamp === "string" ? Date.parse(entry.timestamp) : NaN;
+    return {
+      tokensUsed,
+      ...(typeof entry.message?.model === "string" ? { model: entry.message.model } : {}),
+      ...(Number.isFinite(occurredAt) ? { occurredAt } : {}),
+    };
+  }
+  return undefined;
+}
+
+// Context size == prompt input tokens for the turn: fresh input + newly-cached
+// input + cache-read input. Matches the status-line probe's sum (output tokens
+// are excluded — they are not part of the context window carried forward).
+function sumUsageTokens(usage: TranscriptUsage): number | undefined {
+  let total = 0;
+  let seen = false;
+  for (const value of [usage.input_tokens, usage.cache_creation_input_tokens, usage.cache_read_input_tokens]) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      total += value;
+      seen = true;
+    }
+  }
+  return seen ? total : undefined;
+}
+
 export function extractHookAssistantMessage(content: unknown): string {
   if (typeof content === "string") return content.trim();
   if (!Array.isArray(content)) return "";

package/src/adapters/claude.ts

@@ -5,17 +5,19 @@ import { type Message } from "agent-relay-sdk";
 import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
 import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
 import { runtimePath } from "agent-relay-sdk/runtime-prefix";
-import { profileAllowsRelayFeature, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderStatusUpdate, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
+import { profileAllowsRelayFeature, type ManagedProcess, type PaneBusyReading, type PaneObservation, type ProviderAdapter, type ProviderConfig, type ProviderStatusUpdate, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
 import { computeLivenessSignal, type LivenessInputs } from "../liveness";
 import type { LivenessSignal } from "agent-relay-sdk";
 import { prepareClaudeProfileHome, profileUsesClaudeHostProviderGlobals } from "../profile-home";
 import { assembleLaunch, materializeLaunchAssembly, sessionStatusLineSettingsArgs, stripSettingsArgs } from "../launch-assembly";
 import { claudeProviderMessageText } from "./claude-delivery";
-import { claudeProbeActivity, readManagedClaudeStatus, resolveClaudePid, type ClaudeProbeActivity } from "./claude-session-probe";
+import { claudeProbeVerdict, readManagedClaudeStatus, resolveClaudePid, resolveManagedClaudeTranscriptPath, type ClaudeProbeActivity } from "./claude-session-probe";
 import { evaluateClaudePromptGatePane, initialClaudePromptGatePaneState, type ClaudePromptGatePaneState } from "./claude-prompt-gates";
-import { claudeActivityFromProbeAndPane, claudePaneLooksReady, claudePaneIsBusy, claudeRateLimitStatus, claudeConnectionRetryStatus, claudeModelUnavailableStatus } from "./claude-status-detectors";
+import { claudeActivityFromProbeAndPane, claudePaneLooksReady, claudePaneIsBusy, claudeRateLimitStatus, claudeConnectionRetryObservation, claudeConnectionRetryClearedObservation, claudeModelUnavailableObservation, debounceClaudeModelUnavailableObservation, initialClaudeModelUnavailableObservationState } from "./claude-status-detectors";
 import { ClaudeSessionCapture, collectClaudeTranscriptArchiveSegment, collectClaudeTranscriptSessionEvents } from "./claude-session-capture";
-import { CLAUDE_TMUX_READY_TIMEOUT_MS, captureTmuxPane, confirmTmuxSessionGone, createLauncherGate, createOrReuseTmuxSession, releaseLauncherGate, submitTextToTmux, tmuxEnvKeys, tmuxSessionName, tmuxSocketName, waitForClaudeInputReady, writeLauncherScript } from "./claude-tmux";
+import { extractLatestContextUsage } from "./claude-transcript";
+import { CLAUDE_TMUX_READY_TIMEOUT_MS, captureTmuxPane, confirmTmuxSessionGone, createLauncherGate, createOrReuseTmuxSession, releaseLauncherGate, submitTextToTmux, tmuxEnvKeys, tmuxSessionName, tmuxSessionTargetName, tmuxSocketName, waitForClaudeClearCommitted, waitForClaudeInputReady, writeLauncherScript } from "./claude-tmux";
+import { claudeShutdownGraceMs, shutdownClaudeTmux, type ClaudeShutdownDeps } from "./claude-shutdown";
 import { claudePermissionPromptHandler } from "./claude-permission";
 import { launcherGatePathForSession } from "../session-scratch";
 
@@ -26,15 +28,34 @@ export class ClaudeAdapter implements ProviderAdapter {
   readonly stopObligationPath = "claude-stop";
   readonly permissionPromptHandler = claudePermissionPromptHandler;
   readonly compactSupportsInstructions = true;
+  // #1588 — Claude's clearContext is a fire-and-forget tmux `/clear` keystroke with no structured
+  // completion barrier, so the self-resume continuation MUST be delivered in-process coupled to the
+  // clear command (after waitForClaudeInputReady settles it) instead of via a separate inject that
+  // would race the still-processing async clear. Codex omits this (atomic awaited threadStart).
+  readonly couplesClearInjectContinuation = true;
   // #352: initial prompt is seeded as Claude's positional launch arg (buildSpawnArgs) — reliable,
   // no send-keys/onboarding race; tells the runner to skip the redundant post-launch delivery.
   readonly seedsInitialPromptAtLaunch = true;
   private statusCb: (status: ProviderStatusUpdate) => void = () => {};
+  // #1651 — the pane watcher's ONLY outbound channel for anything it inferred from pane text.
+  // A PaneObservation cannot carry a status, a clear, or a providerState, so routing a
+  // detector here is what makes "advisory-only" structural rather than a promise in a comment.
+  private paneObservationCb: (observation: PaneObservation) => void = () => {};
   private tmuxWatcher?: Timer;
   private turnWatcher?: Timer;
-  private modelUnavailableReported = false;
+  private modelUnavailableObservationState = initialClaudeModelUnavailableObservationState();
   private connectionRetryActive = false;
   private promptGatePaneState: ClaudePromptGatePaneState = initialClaudePromptGatePaneState();
+  // #1621 — when relay LAST typed a turn-cancelling keystroke into the managed pane itself. A
+  // probe whose last write predates this cannot be describing the state after the cancellation,
+  // so its busy verdict stops being authoritative at once. #1651 removed the prompt gate's
+  // auto-Escape, so the sole remaining writer is the explicit `interrupt()` command — a
+  // deliberate, operator/runner-initiated cancel, not something inferred from pane text.
+  private paneInterruptAt?: number;
+  // #1647 — provider epoch: bumped on every spawn, stamped into the ManagedProcess and
+  // into any shutdown intent minted for it. A shutdown request that outlives a restart
+  // therefore cannot authorize typing `/exit` into the replacement session.
+  private providerEpoch = 0;
   private readonly sessionCapture = new ClaudeSessionCapture();
   readonly onSessionEvent = this.sessionCapture.onSessionEvent.bind(this.sessionCapture);
   readonly onSessionEvents = this.sessionCapture.onSessionEvents.bind(this.sessionCapture);
@@ -50,6 +71,10 @@ export class ClaudeAdapter implements ProviderAdapter {
     this.statusCb = cb;
   }
 
+  onPaneObservation(cb: (observation: PaneObservation) => void): void {
+    this.paneObservationCb = cb;
+  }
+
   // §4.1 contract verdict (#746). Claude reference (#713): Claude is token-silent during
   // native compaction, but the runner publishes a `compacting` timeline transition while it
   // runs — so `timelineEvent.timestamp` (folded into lastProgressAt) keeps a compacting Opus
@@ -74,7 +99,7 @@ export class ClaudeAdapter implements ProviderAdapter {
       stdout: "inherit",
       stderr: "inherit",
     });
-    void proc.exited.then((code) => this.statusCb(code === 0 ? "offline" : "error"));
+    void proc.exited.then((code) => this.statusCb(code === 0 ? "offline" : "error")).catch(() => this.statusCb("error")).catch(() => {});
     return { pid: proc.pid, process: proc, meta: { monitor: config.monitor, env: args.env } };
   }
 
@@ -82,7 +107,7 @@ export class ClaudeAdapter implements ProviderAdapter {
     const tmuxSession = process.meta?.tmuxSession as string | undefined;
     const tmuxSocket = process.meta?.tmuxSocket as string | undefined;
     if (tmuxSession) {
-      await this.shutdownTmux(tmuxSession, opts, tmuxSocket);
+      await this.shutdownTmux(process, tmuxSession, opts, tmuxSocket);
       return;
     }
     await terminateSingleProcess(process, opts);
@@ -101,16 +126,44 @@ export class ClaudeAdapter implements ProviderAdapter {
     const session = process.meta?.tmuxSession as string | undefined;
     const socket = process.meta?.tmuxSocket as string | undefined;
     if (!session || !tmuxHasSession(session, socket)) throw new Error("no active tmux session for clear");
+    // #1588 — snapshot the pane BEFORE submitting `/clear` so the clear-aware barrier can detect
+    // the loaded conversation body disappearing (positive clear-commit evidence), not just the
+    // ever-present footer. Best-effort: a capture failure just yields no anchor → clearConfirmed
+    // falls to false → backstop covers.
+    let preClearPane = "";
+    try { preClearPane = captureTmuxPane(session, socket); } catch {}
     await submitTextToTmux(session, "/clear", socket);
-    return { method: "tmux-inject", command: "/clear" };
+    // #1588 — `/clear` is async in the Claude TUI: submitTextToTmux returns as soon as the keys
+    // are typed, before the conversation is actually cleared. The self-resume continuation used to
+    // race this still-processing clear (a separate command, ~8ms later, on a different transport)
+    // and get swallowed — a silent mind-wipe. The OLD barrier (waitForClaudeInputReady) accepted
+    // the first persistent-footer match, which is present on the STILL-UNCLEARED pane too — so it
+    // could return before the clear committed. Use the CLEAR-AWARE barrier instead: it requires
+    // positive evidence the clear committed (pane idle + input-ready + the pre-clear conversation
+    // anchor gone). `clearConfirmed` is surfaced to the coupled deliver: only a genuine confirmation
+    // permits continuationDelivered:true; a timeout/uncertain settle → false → the relay's #1023
+    // backstop re-injects. Never throws (the clear already ran); uncertainty resolves to false.
+    const clearConfirmed = await waitForClaudeClearCommitted(session, preClearPane, CLAUDE_TMUX_READY_TIMEOUT_MS, socket);
+    return { method: "tmux-inject", command: "/clear", clearConfirmed };
   }
 
+  // #1512: Claude reports context only through its out-of-band status-line probe,
+  // which freezes after an in-process compact/clear/native-resume. The transcript
+  // (handed to the runner every turn by the Stop hook) carries the same per-turn
+  // token usage, so the runner reads it here as a probe-independent fallback that
+  // keeps context stats advancing across those in-process generation bumps.
+  readonly contextUsageFromTranscript = extractLatestContextUsage;
+
   async interrupt(process: ManagedProcess): Promise<Record<string, unknown>> {
     const session = process.meta?.tmuxSession as string | undefined;
     const socket = process.meta?.tmuxSocket as string | undefined;
     if (!session || !tmuxHasSession(session, socket)) throw new Error("no active tmux session to interrupt");
     // The same ESC the web terminal's aux key sends: cancels the in-flight turn
-    // and drops Claude back to its input box without ending the session.
+    // and drops Claude back to its input box without ending the session. #1621: mark the probe's
+    // pre-cancel busy verdict non-authoritative so the runner's post-interrupt reconcile can
+    // actually see the idle pane (a cancel writes no probe transition, so without this the
+    // reconcile read the frozen `busy`/`shell` and left the claim standing).
+    this.paneInterruptAt = Date.now();
     const result = Bun.spawnSync(tmuxCommand(socket, "send-keys", "-t", session, "Escape"), {
       stdin: "ignore", stdout: "ignore", stderr: "pipe",
     });
@@ -128,6 +181,19 @@ export class ClaudeAdapter implements ProviderAdapter {
     return this.activityFromProbeOrPane(process, session, socket);
   }
 
+  // #1138: a tmux-launched Claude session's ManagedProcess carries no direct OS pid
+  // (process.pid is undefined — only the tmux session/socket), so the runner's #650
+  // pid-liveness fallback had nothing to check for an ordinary hook-driven turn. Resolve
+  // the tmux pane's real pid so a long, quiet (no subagents, no compaction) busy turn can
+  // prove it is still alive instead of being force-healed to idle by the runner's
+  // stale-progress backstop purely because 10 minutes passed with no interim signal.
+  resolveBusyPid(process: ManagedProcess): number | undefined {
+    const session = process.meta?.tmuxSession as string | undefined;
+    if (!session) return undefined;
+    const socket = process.meta?.tmuxSocket as string | undefined;
+    return resolveClaudePid(process.pid, session, socket);
+  }
+
   // Shared probe-primary / pane-fallback activity read (#766/#768), used by both the
   // reconciler-facing probeActivity and the monitorless turn-watch. Primary: Claude
   // Code's intrinsic session probe (busy/shell→busy — the idle-while-working gap the
@@ -140,27 +206,33 @@ export class ClaudeAdapter implements ProviderAdapter {
       tmuxSocket: socket,
       configHomeEnv: (process.meta?.env as Record<string, string | undefined> | undefined)?.CLAUDE_CONFIG_DIR,
     });
-    const probe = managed?.reading.available ? claudeProbeActivity(managed.reading.status) : undefined;
-    if (probe === "busy") return "busy";
+    // #1621: a busy probe that hasn't been rewritten inside its trust window may be describing a
+    // turn that was already cancelled out of band (no transition → no rewrite). It keeps the fast
+    // path (no pane capture) only while fresh; once stale it has to face the pane.
+    const { activity: probe, busyStale } = claudeProbeVerdict(managed?.reading, Date.now(), { paneInterruptAt: this.paneInterruptAt });
+    if (probe === "busy" && !busyStale) return "busy";
     let pane: string | undefined;
     try { pane = captureTmuxPane(session, socket); } catch { return probe ?? "unknown"; }
-    return claudeActivityFromProbeAndPane(probe, pane);
+    return claudeActivityFromProbeAndPane(probe, pane, { probeBusyStale: busyStale });
   }
 
-  // #769 P1-A: an independent pane-busy read, consumed ONLY as a veto on the busy
-  // backstop's force-clear (BusyReconciler) — a probe-`idle` must never clear a live
-  // turn while the pane spinner still reads busy (a connection-retry/529 can write
-  // status:idle mid-turn without tripping the rate-limit pane detector — the #769
-  // gap). probeActivity stays probe-primary; this is a clear-time veto-toward-busy
-  // only. false on no session / capture failure (no veto).
-  async probePaneBusy(process: ManagedProcess): Promise<boolean> {
+  // #769 P1-A: an independent pane-busy read consumed by the busy backstop — a probe-`idle`
+  // must never clear a live turn while the pane spinner still reads busy (a connection-retry/529
+  // can write status:idle mid-turn without tripping the rate-limit pane detector — the #769 gap).
+  // probeActivity stays probe-primary; this is a corroboration channel only.
+  //
+  // #1656: this used to answer `false` for all three of "captured, no spinner", "no tmux session"
+  // and "capture threw", and the backstop read that single `false` as permission to clear a live
+  // turn. A read that failed is a fact about the read, not about the provider — it is reported as
+  // such now, and the backstop refuses to act on it.
+  async probePaneBusy(process: ManagedProcess): Promise<PaneBusyReading> {
     const session = process.meta?.tmuxSession as string | undefined;
     const socket = process.meta?.tmuxSocket as string | undefined;
-    if (!session || !tmuxHasSession(session, socket)) return false;
+    if (!session || !tmuxHasSession(session, socket)) return "no-session";
     try {
-      return claudePaneIsBusy(captureTmuxPane(session, socket));
+      return claudePaneIsBusy(captureTmuxPane(session, socket)) ? "busy" : "not-busy";
     } catch {
-      return false;
+      return "unreadable";
     }
   }
 
@@ -175,6 +247,20 @@ export class ClaudeAdapter implements ProviderAdapter {
     // transient startup races) to avoid double-delivering against a late monitor.
     const monitorless = process.meta?.monitorless === true;
     if (!monitorless && monitor?.deliver) {
+      // #1588 F2 edge 2 — the monitor deliver path had NO settle re-check (unlike the tmux
+      // fallback below), so a self-resume continuation delivered via the monitor (the victim
+      // coordinator's exact profile) could land into a not-yet-settled post-clear context. For
+      // self-resume continuation deliveries, wait for the TUI to be input-ready first. The coupled
+      // clearContext clear-aware barrier is the authoritative clear-commit gate; this belt-and-
+      // suspenders settle also protects the SEPARATE relay-backstop inject (which does NOT run
+      // through clearContext) so it too lands into a ready pane. Best-effort: a settle timeout must
+      // not fail the delivery — the backstop path already IS the recovery, and the coupled path's
+      // continuationDelivered truthfulness is decided by the clearContext barrier, not here.
+      const session = process.meta?.tmuxSession as string | undefined;
+      const socket = process.meta?.tmuxSocket as string | undefined;
+      if (session && messagesAreSelfResumeContinuation(messages) && tmuxHasSession(session, socket)) {
+        await waitForClaudeInputReady(session, CLAUDE_TMUX_READY_TIMEOUT_MS, socket).catch(() => {});
+      }
       await monitor.deliver(messages);
       return;
     }
@@ -208,10 +294,21 @@ export class ClaudeAdapter implements ProviderAdapter {
     // process itself isn't tracked here — pid is undefined for tmux-managed claude).
     // A dead pid means the turn is definitively over, so this can't falsely clear.
     const livenessPid = resolveClaudePid(process.pid, sessionName, socketName);
+    // #1235 — monitorless workers have no Stop/UserPromptSubmit hooks, so the transcript
+    // reasoning tail is never hook-triggered and chat stays empty. Resolve the live transcript
+    // path from the intrinsic session probe (sessionId + cwd) and hand it to the runner on the
+    // turn edges so it can drive the SAME reasoning tail natively. undefined on an old/absent
+    // probe → runner skips native capture (graceful degrade to the prior no-chat behavior).
+    const transcriptPath = resolveManagedClaudeTranscriptPath({
+      pid: process.pid,
+      tmuxSession: sessionName,
+      tmuxSocket: socketName,
+      configHomeEnv: (process.meta?.env as Record<string, string | undefined> | undefined)?.CLAUDE_CONFIG_DIR,
+    });
     // We just submitted a prompt, so a turn is starting. Emit a synthetic
     // provider-turn busy now so the runner arms task-claim completion; the claim
     // for this delivery is already registered before deliver() runs.
-    this.statusCb({ status: "busy", reason: "provider-turn", id: CLAUDE_TURN_WATCH_ID, ...(livenessPid ? { pids: [livenessPid] } : {}) });
+    this.statusCb({ status: "busy", reason: "provider-turn", id: CLAUDE_TURN_WATCH_ID, ...(livenessPid ? { pids: [livenessPid] } : {}), ...(transcriptPath ? { transcriptPath } : {}) });
     let ticks = 0;
     let idleStreak = 0;
     let sawBusy = false;
@@ -239,7 +336,9 @@ export class ClaudeAdapter implements ProviderAdapter {
       const turnObserved = sawBusy || ticks >= CLAUDE_TURN_QUICK_GRACE_TICKS;
       if (confirmedIdle && turnObserved) {
         this.stopTurnWatch();
-        this.statusCb({ status: "idle", reason: "provider-turn", id: CLAUDE_TURN_WATCH_ID });
+        // Carry the transcript path on the idle edge too (#1235) so the runner can capture the
+        // turn's final assistant response natively before it tears down the reasoning tail.
+        this.statusCb({ status: "idle", reason: "provider-turn", id: CLAUDE_TURN_WATCH_ID, ...(transcriptPath ? { transcriptPath } : {}) });
       }
     }, CLAUDE_TURN_POLL_MS);
   }
@@ -328,8 +427,12 @@ export class ClaudeAdapter implements ProviderAdapter {
   }
 
   buildTmuxArgs(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): { sessionName: string; socketName: string; args: string[]; launcherScript: string; gateFifo?: string } {
-    const sessionName = config.tmuxSession || tmuxSessionName(config.providerConfig.headless.tmuxPrefix, config.instanceId, config.label);
-    const socketName = tmuxSocketName(sessionName);
+    const requestedSessionName = config.tmuxSession || tmuxSessionName(config.providerConfig.headless.tmuxPrefix, config.instanceId, config.label);
+    // Keep the socket derived from the orchestrator's stable identity, but carry
+    // tmux's rendered session name everywhere we later target the pane. Without
+    // this, `opus-4.8` is created as `opus-4_8` and every watcher/restart lookup
+    // immediately misses it.
+    const socketName = tmuxSocketName(requestedSessionName); const sessionName = tmuxSessionTargetName(requestedSessionName);
     const shellCmd = [spawnArgs.command, ...spawnArgs.args].map(shellQuote).join(" ");
     const tmuxArgs = ["new-session", "-d", "-s", sessionName, "-x", "200", "-y", "50"];
 
@@ -352,7 +455,8 @@ export class ClaudeAdapter implements ProviderAdapter {
 
   private async spawnHeadless(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): Promise<ManagedProcess> {
     const { sessionName, socketName, args: tmuxArgs, launcherScript, gateFifo } = this.buildTmuxArgs(config, spawnArgs);
-    this.modelUnavailableReported = false;
+    const providerEpoch = ++this.providerEpoch;
+    this.modelUnavailableObservationState = initialClaudeModelUnavailableObservationState();
     this.connectionRetryActive = false;
     this.promptGatePaneState = initialClaudePromptGatePaneState();
 
@@ -389,6 +493,7 @@ export class ClaudeAdapter implements ProviderAdapter {
         tmuxSession: sessionName,
         tmuxSocket: socketName,
         launcherScript,
+        providerEpoch,
       },
     };
   }
@@ -409,86 +514,89 @@ export class ClaudeAdapter implements ProviderAdapter {
           clearInterval(watcher);
           this.tmuxWatcher = undefined;
           this.statusCb("offline");
-        });
+        }).catch(() => { goneConfirmationPending = false; });
         return;
       }
-      if (this.modelUnavailableReported) return;
       let pane = "";
       try {
         pane = captureTmuxPane(sessionName, socketName);
       } catch {
         return;
       }
-      const status = claudeModelUnavailableStatus(pane, sessionName);
-      if (status) {
-        this.modelUnavailableReported = true;
-        this.statusCb(status);
-        return;
-      }
-      // #769: connection-retry banner detection. Emits a transient blocked hold while the
-      // pane shows the retry footer; clears to idle when the banner disappears (API recovered).
-      const connRetryStatus = claudeConnectionRetryStatus(pane, sessionName);
-      if (connRetryStatus) {
+      const modelUnavailable = debounceClaudeModelUnavailableObservation(
+        claudeModelUnavailableObservation(pane, sessionName), this.modelUnavailableObservationState,
+      );
+      this.modelUnavailableObservationState = modelUnavailable.state;
+      if (modelUnavailable.observation) this.paneObservationCb(modelUnavailable.observation);
+      // #769/#1651: connection-retry banner detection, advisory. BOTH edges are diagnostics.
+      // Appearance used to publish an idle + blocked hold, which the runner reads as the
+      // provider turn ENDING — completing the task claims of a turn that was still running.
+      // Disappearance used to publish a bare `idle`, an unconditional turn-end with no evidence
+      // behind it at all. Neither edge touches statusCb now; the flag exists only to keep the
+      // diagnostic edge-triggered rather than repeating every 2s tick.
+      const connRetry = claudeConnectionRetryObservation(pane, sessionName);
+      if (connRetry) {
         if (!this.connectionRetryActive) {
           this.connectionRetryActive = true;
-          this.statusCb(connRetryStatus);
+          this.paneObservationCb(connRetry);
         }
       } else if (this.connectionRetryActive) {
         this.connectionRetryActive = false;
-        this.statusCb("idle");
+        this.paneObservationCb(claudeConnectionRetryClearedObservation(sessionName));
       }
       // #663: prompt-gate fallback. Known gates should be prevented before launch;
       // this catches missed/new blocking panes with the same #655 debounce + busy
       // guard used for rate-limit holds.
+      // #1651: it NOTICES, it does not act. The five startup/modal gates are advisory and
+      // return no status at all, so the only thing this branch can do for them is publish a
+      // diagnostic. `status` is present solely for the usage-limit gate.
       const promptGate = evaluateClaudePromptGatePane(pane, this.promptGatePaneState, {
         sessionName,
         busy: claudePaneIsBusy(pane),
         sourceId: this.paneSourceId,
       });
       this.promptGatePaneState = promptGate.state;
-      if (promptGate.action) {
-        this.sendPromptGateKeystroke(sessionName, promptGate.action.keystroke, socketName);
-        if (promptGate.status) this.statusCb(promptGate.status);
-      }
+      if (promptGate.observation) this.paneObservationCb(promptGate.observation);
+      if (promptGate.status) this.statusCb(promptGate.status);
     }, 2000);
     this.tmuxWatcher = watcher;
   }
 
-  // Best-effort: a failed auto-dismiss must not wedge the pane watcher.
-  private sendPromptGateKeystroke(sessionName: string, keystroke: string, socketName?: string): void {
-    try {
-      Bun.spawnSync(tmuxCommand(socketName, "send-keys", "-t", sessionName, keystroke), { stdin: "ignore", stdout: "ignore", stderr: "ignore" });
-    } catch {
-      // ignore; the timeline/status still publishes, and the next watcher tick can observe whether the pane moved.
-    }
-  }
-
-  private async shutdownTmux(sessionName: string, opts: { graceful: boolean; timeoutMs: number }, socketName?: string): Promise<void> {
+  // #1647 — the shutdown sequence (observe → correlate → maybe /exit) lives in
+  // ./claude-shutdown. Only the watcher teardown is the adapter's own business.
+  async shutdownTmux(
+    process: ManagedProcess,
+    sessionName: string,
+    opts: { graceful: boolean; timeoutMs: number },
+    socketName?: string,
+    deps: ClaudeShutdownDeps = {},
+  ): Promise<void> {
     this.stopTurnWatch();
     if (this.tmuxWatcher) {
       clearInterval(this.tmuxWatcher);
       this.tmuxWatcher = undefined;
     }
-    if (opts.graceful && tmuxHasSession(sessionName, socketName)) {
-      await submitTextToTmux(sessionName, CLAUDE_EXIT_COMMAND, socketName);
-
-      const deadline = Date.now() + claudeShutdownGraceMs(opts.timeoutMs);
-      while (Date.now() < deadline) {
-        if (!tmuxHasSession(sessionName, socketName)) return;
-        await Bun.sleep(200);
-      }
-    }
-
-    Bun.spawnSync(tmuxCommand(socketName, "kill-session", "-t", sessionName), {
-      stdin: "ignore", stdout: "ignore", stderr: "ignore",
-    });
+    await shutdownClaudeTmux(process, sessionName, opts, socketName, this.providerEpoch, deps);
   }
 }
 
-export const CLAUDE_EXIT_COMMAND = "/exit";
+// #1588 — a self-resume continuation delivery carries the resumeInjection/selfResume markers the
+// runner stamps in injectContext. Used to scope the monitor-path settle re-check to ONLY those
+// deliveries so ordinary message delivery is unchanged.
+function messagesAreSelfResumeContinuation(messages: Message[]): boolean {
+  return messages.some((message) => {
+    const payload = message.payload as Record<string, unknown> | undefined;
+    return payload?.resumeInjection === true || Boolean(payload?.selfResume);
+  });
+}
+
+// #1647 — the exit command and its two writers now live in ./claude-exit, behind the
+// one-shot grant. Re-exported so existing `./claude` consumers + tests keep their path.
+export { CLAUDE_EXIT_COMMAND } from "./claude-exit";
+export { claudeShutdownGraceMs, shutdownClaudeTmux, observeClaudeExitState, type ClaudeShutdownDeps } from "./claude-shutdown";
 // tmux transport plumbing moved to ./claude-tmux (#300 ratchet); re-exported so
 // existing `./claude` consumers + tests keep their import paths.
-export { CLAUDE_TMUX_SUBMIT_DELAY_MS, CLAUDE_TMUX_SUBMIT_KEY, CLAUDE_TMUX_READY_TIMEOUT_MS, tmuxSessionName, tmuxSocketName, tmuxSocketPath, assertTmuxSocketPathFits, tmuxEnvKeys, waitForClaudeInputReady, submitTextToTmux } from "./claude-tmux";
+export { CLAUDE_TMUX_SUBMIT_DELAY_MS, CLAUDE_TMUX_SUBMIT_KEY, CLAUDE_TMUX_READY_TIMEOUT_MS, CLAUDE_CLEAR_COMMIT_POLL_MS, tmuxSessionName, tmuxSocketName, tmuxSocketPath, assertTmuxSocketPathFits, tmuxEnvKeys, waitForClaudeInputReady, waitForClaudeClearCommitted, submitTextToTmux } from "./claude-tmux";
 // Monitorless turn detection (Fix: isolated agents reach task "done" like Codex).
 const CLAUDE_TURN_WATCH_ID = "tmux-turn";
 const CLAUDE_TURN_POLL_MS = 1500;
@@ -496,11 +604,6 @@ const CLAUDE_TURN_IDLE_CONFIRM_TICKS = 3;  // ~4.5s of stable idle before declar
 const CLAUDE_TURN_QUICK_GRACE_TICKS = 8;   // ~12s fallback when the spinner was never caught
 const CLAUDE_TURN_MAX_TICKS = 3600;        // ~90min safety cap so the timer never leaks
 
-export function claudeShutdownGraceMs(timeoutMs: number): number {
-  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return 10_000;
-  return Math.min(timeoutMs, 10_000);
-}
-
 // #557 — sessionStatusLineSettingsArgs now lives in ../launch-assembly (the single
 // launch-arg home); re-exported so existing ./claude consumers + tests keep their path.
 export { sessionStatusLineSettingsArgs };
@@ -551,7 +654,7 @@ export { tmuxHasSession };
 
 // Re-export pane-status detectors (moved to ./claude-status-detectors) so existing
 // import paths (including claude.test.ts) continue to resolve via this module.
-export { claudeActivityFromProbeAndPane, claudePaneLooksReady, claudePaneIsBusy, claudeRateLimitStatus, claudeConnectionRetryStatus, claudeModelUnavailableStatus } from "./claude-status-detectors";
+export { claudeActivityFromProbeAndPane, claudePaneLooksReady, claudePaneIsBusy, claudeConversationAnchor, claudeClearCommitted, claudeRateLimitStatus, claudeConnectionRetryObservation, claudeConnectionRetryClearedObservation, claudeModelUnavailableObservation, debounceClaudeModelUnavailableObservation, initialClaudeModelUnavailableObservationState } from "./claude-status-detectors";
 
 // Shared shell-quoting; re-exported so `./claude` consumers + tests resolve it.
 export { shellQuote };