agent-relay-runner 0.129.11 → 0.129.12

package/src/adapters/claude-prompt-gates.ts

@@ -1,7 +1,6 @@
 import { resolve } from "node:path";
-import { isRecord, type ProviderState } from "agent-relay-sdk";
-import type { ProviderStatusUpdate, RunnerSpawnConfig } from "../adapter";
-import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-limit";
+import { isRecord } from "agent-relay-sdk";
+import type { PaneObservation, RunnerSpawnConfig } from "../adapter";
 
 export interface ClaudeConfigPromptGatePrevention {
   id: string;
@@ -15,16 +14,28 @@ export interface ClaudeLaunchPromptGatePrevention {
   apply(config: RunnerSpawnConfig): { strictMcpConfig?: boolean };
 }
 
-type PaneGateMatch = { message?: string; resetAt?: number; kind?: "usage_limit" | "transient_overload"; errorType?: string };
+type PaneGateMatch = { message?: string };
+
+/**
+ * #1651 — how much authority a pane match is allowed to carry.
+ *
+ * `advisory` is the only correct value for a gate detected purely from TUI geometry. It
+ * produces a {@link PaneObservation} and NOTHING else: no keystroke (the concept no longer
+ * exists in this file), no ProviderStatusUpdate, hence no status, no `clear`, no
+ * providerState. #1611/#1615/#1621/#1637/#1642 each tried to make one of these gates safe by
+ * tightening its string matcher; the matcher was never the problem — granting a string match
+ * the authority to mutate state was.
+ *
+ * The retired usage-limit pane gate (#1664) is deliberately not represented here: provider
+ * state comes from structured provider failures, never a pane scrape.
+ */
 
 interface ClaudePanePromptGate {
   id: string;
   label: string;
   policy: string;
-  keystroke: string;
   minDetections: number;
-  match(text: string, nowMs?: number): PaneGateMatch | null;
-  providerState?(match: PaneGateMatch, context: ClaudePromptGatePaneContext): ProviderState;
+  match(text: string): PaneGateMatch | null;
 }
 
 export interface ClaudePromptGatePaneState {
@@ -40,17 +51,11 @@ export interface ClaudePromptGatePaneContext {
   sourceId?: string;
 }
 
-export interface ClaudePromptGateAction {
-  gateId: string;
-  label: string;
-  policy: string;
-  keystroke: string;
-  source: string;
-}
-
 export interface ClaudePromptGatePaneResult {
-  action?: ClaudePromptGateAction;
-  status?: ProviderStatusUpdate;
+  /** #1651 — always present when a gate reached minDetections. Diagnostic only. */
+  observation?: PaneObservation;
+  /** Kept for callers which assert absence; `never` makes a status impossible to emit. */
+  status?: never;
   state: ClaudePromptGatePaneState;
 }
 
@@ -101,28 +106,23 @@ export const claudeLaunchPromptGatePreventions: ClaudeLaunchPromptGatePrevention
 ];
 
 const panePromptGates: ClaudePanePromptGate[] = [
-  {
-    id: "usage-limit",
-    label: "Usage limit",
-    policy: "wait-for-reset",
-    keystroke: "Escape",
-    minDetections: 2,
-    match: (text, nowMs) => parseClaudeRateLimitPane(text, nowMs),
-    providerState(match, context) {
-      return buildRateLimitProviderState({
-        errorType: match.errorType ?? "session_limit",
-        kind: match.kind ?? "usage_limit",
-        ...(match.resetAt ? { resetAt: match.resetAt } : {}),
-        message: match.message,
-        source: paneSource(context),
-      });
-    },
-  },
+  // #1651 — the five gates below are ADVISORY. Each used to type a key into a live pane the
+  // instant `claudePaneIsBusy` happened to read false, then publish a fabricated
+  // idle + clear:["subagent"]. Two independent hazards, both realized:
+  //   - the four Enter gates SUBMIT whatever text is already sitting in the composer;
+  //   - project-mcp-discovery's Escape CANCELS a live turn.
+  // Neither needed the matcher to be wrong. `claudePaneIsBusy` is a last-ten-lines scrape
+  // whose only busy witness sits on the very last budgeted line, so one extra row of bottom
+  // chrome (a wrapped advisory, a two-line composer, one more trailing blank) flips it to
+  // false ON A LIVE TURN — measured on CC 2.1.220. A persistent ready-looking footer is not
+  // an authorization boundary, so none of these may hold one.
+  // Real startup modals are already prevented structurally, before launch, by
+  // claudeConfigPromptGatePreventions / claudeLaunchPromptGatePreventions above; these
+  // entries are the backstop that NOTICES a prevention missed, not a second actuator.
   {
     id: "workspace-trust",
     label: "Workspace trust",
     policy: "accept-trusted-workspace",
-    keystroke: "Enter",
     minDetections: 2,
     match: (text) => /do you trust (?:the files in )?(?:this folder|this project|this directory)/i.test(text)
       && /\b(?:yes|proceed|trust|continue)\b/i.test(text)
@@ -133,7 +133,6 @@ const panePromptGates: ClaudePanePromptGate[] = [
     id: "bypass-permissions-mode",
     label: "Bypass permissions mode",
     policy: "accept-configured-open-approval",
-    keystroke: "Enter",
     minDetections: 2,
     match: (text) => /bypass permissions mode/i.test(text) && /\b(?:accept|proceed|continue|yes)\b/i.test(text)
       ? { message: lineMatching(text, /bypass permissions mode/i) }
@@ -143,7 +142,6 @@ const panePromptGates: ClaudePanePromptGate[] = [
     id: "project-mcp-discovery",
     label: "Project MCP discovery",
     policy: "reject-ambient-project-mcp",
-    keystroke: "Escape",
     minDetections: 2,
     match: (text) => /\bnew MCP servers? found\b/i.test(text) && /\b(?:select|enable|servers?)\b/i.test(text)
       ? { message: lineMatching(text, /new MCP servers? found/i) }
@@ -153,7 +151,6 @@ const panePromptGates: ClaudePanePromptGate[] = [
     id: "theme-selection",
     label: "Theme selection",
     policy: "accept-default-theme",
-    keystroke: "Enter",
     minDetections: 2,
     match: (text) => /choose (?:the )?(?:text style|theme).*Claude Code/i.test(text) && /\b(?:dark|light) mode\b/i.test(text)
       ? { message: lineMatching(text, /choose/i) }
@@ -163,12 +160,22 @@ const panePromptGates: ClaudePanePromptGate[] = [
     id: "first-run-onboarding",
     label: "First-run onboarding",
     policy: "accept-onboarding",
-    keystroke: "Enter",
     minDetections: 2,
     match: (text) => /welcome to Claude Code/i.test(text) && /\b(?:let'?s get started|continue|get started)\b/i.test(text)
       ? { message: lineMatching(text, /welcome to Claude Code/i) }
       : null,
   },
+  // #1514 (review finding 3) — the "Exit anyway / Move to background / Stay"
+  // confirmation is deliberately NOT a live pane-watcher gate. Auto-pressing Enter
+  // on a session that did NOT initiate shutdown is unsafe: it could submit stray
+  // input or dismiss an unrelated modal on an attached/live session. This dialog is
+  // only ever the right thing to answer under an explicit Relay shutdown, so it is
+  // handled solely by the runner's shutdown grace loop (confirmClaudeExitDialogUnderGrant
+  // in claude-exit.ts) — which runs only after this runner sent `/exit` under a one-shot
+  // grant. #1647 made that structural rather than advisory: this file cannot even import
+  // the exit writers (claude-exit.guard.test.ts fails the build if it ever does). The
+  // orphan safety net for a session already wedged mid-shutdown is the orchestrator's
+  // wedged-session reaper, not a keypress into a live pane.
 ];
 
 export function applyClaudeConfigPromptGatePreventions(
@@ -196,7 +203,7 @@ export function evaluateClaudePromptGatePane(
   state: ClaudePromptGatePaneState,
   context: ClaudePromptGatePaneContext = {},
 ): ClaudePromptGatePaneResult {
-  const detected = firstDetectedPaneGate(text, context.nowMs);
+  const detected = firstDetectedPaneGate(text);
   if (!detected) return { state: initialClaudePromptGatePaneState() };
   if (context.busy) {
     return { state: { ...state, currentGateId: undefined, consecutiveDetections: 0 } };
@@ -213,16 +220,18 @@ export function evaluateClaudePromptGatePane(
   };
   if (consecutiveDetections < detected.entry.minDetections) return { state: nextState };
 
-  const action: ClaudePromptGateAction = {
-    gateId: detected.entry.id,
-    label: detected.entry.label,
-    policy: detected.entry.policy,
-    keystroke: detected.entry.keystroke,
-    source: paneSource(context),
+  const observedAt = context.nowMs ?? Date.now();
+  const observation: PaneObservation = {
+    eventType: "claude.pane_gate_candidate",
+    source: "pane",
+    detectorId: detected.entry.id,
+    observedAt,
+    ...(context.sessionName ? { sessionName: context.sessionName } : {}),
+    ...(detected.match.message ? { message: detected.match.message } : {}),
+    detail: { label: detected.entry.label, policy: detected.entry.policy, paneSource: paneSource(context) },
   };
   return {
-    action,
-    status: promptGateStatus(detected.entry, detected.match, action, context),
+    observation,
     state: { ...nextState, handledGateId: detected.entry.id },
   };
 }
@@ -232,43 +241,14 @@ function paneSource(context: ClaudePromptGatePaneContext): string {
   return context.sessionName ? `${source}:${context.sessionName}` : source;
 }
 
-function firstDetectedPaneGate(text: string, nowMs?: number): { entry: ClaudePanePromptGate; match: PaneGateMatch } | null {
+function firstDetectedPaneGate(text: string): { entry: ClaudePanePromptGate; match: PaneGateMatch } | null {
   for (const entry of panePromptGates) {
-    const match = entry.match(text, nowMs);
+    const match = entry.match(text);
     if (match) return { entry, match };
   }
   return null;
 }
 
-function promptGateStatus(
-  entry: ClaudePanePromptGate,
-  match: PaneGateMatch,
-  action: ClaudePromptGateAction,
-  context: ClaudePromptGatePaneContext,
-): ProviderStatusUpdate {
-  const metadata = {
-    eventType: "claude.prompt_gate.auto_handled",
-    gateId: action.gateId,
-    policy: action.policy,
-    keystroke: action.keystroke,
-    source: action.source,
-    ...(context.sessionName ? { sessionName: context.sessionName } : {}),
-  };
-  return {
-    status: "idle",
-    clear: ["subagent"],
-    ...(entry.providerState ? { providerState: entry.providerState(match, context) } : {}),
-    timeline: {
-      status: "claude.prompt_gate.auto_handled",
-      id: `claude-prompt-gate-${entry.id}-${Date.now()}`,
-      timestamp: Date.now(),
-      title: "Claude prompt gate auto-handled",
-      body: match.message ?? `${entry.label} dismissed with ${entry.keystroke}`,
-      metadata,
-    },
-  };
-}
-
 function lineMatching(text: string, pattern: RegExp): string | undefined {
   return text.split(/\r?\n/).map((line) => line.trim()).find((line) => pattern.test(line));
 }

package/src/adapters/claude-session-capture.ts

@@ -176,6 +176,7 @@ export class ClaudeSessionCapture {
           ...(step.occurredAt ? { occurredAt: step.occurredAt } : {}),
           ...(turnId ? { turnId } : {}),
           ...(step.label ? { label: step.label } : {}),
+          ...(step.category ? { category: step.category } : {}),
         });
         if (step.type === "narration") emittedNarrationKeys.add(sig);
       }
@@ -187,9 +188,18 @@ export class ClaudeSessionCapture {
       pendingPoll = next.catch(() => {});
       return next;
     };
-    this.reasoningTail = { emittedNarrationKeys, poll, timer: setInterval(() => { void poll(); }, REASONING_POLL_MS) };
+    // The serialized pendingPoll deliberately catches so later polls may continue, but poll()
+    // still returns the original rejection to its caller. Both timer-driven calls below have no
+    // caller, so catch them here rather than turning a rotating transcript into a process-fatal
+    // unhandled rejection.
+    const pollInBackground = (): void => {
+      void poll().catch((error) => {
+        try { ctx.log(`reasoning tail poll failed: ${errMessage(error)}`); } catch {}
+      });
+    };
+    this.reasoningTail = { emittedNarrationKeys, poll, timer: setInterval(pollInBackground, REASONING_POLL_MS) };
     ctx.log(`reasoning tail started (turn ${turnIdAtStart ?? "?"})`);
-    void poll();
+    pollInBackground();
   }
 
   private rememberEmittedStepKey(sig: string): void {
@@ -232,6 +242,7 @@ export function providerSessionEventToMessageSession(event: ProviderSessionEvent
     origin: event.origin ?? "provider",
     ...(event.turnId ? { turnId: event.turnId } : {}),
     ...(event.label ? { label: event.label } : {}),
+    ...(event.category ? { toolCategory: event.category } : {}),
     ...(event.status ? { status: event.status } : {}),
     ...(event.streaming !== undefined ? { streaming: event.streaming } : {}),
     ...(event.stepId ? { stepId: event.stepId } : {}),

package/src/adapters/claude-session-probe.ts

@@ -19,6 +19,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { isPidAlive } from "agent-relay-sdk/process-utils";
 import { tmuxCommand } from "agent-relay-sdk/tmux-utils";
+import { claudeProbeBusyStaleMsFromEnv } from "../config";
 
 /** Raw probe status; "unknown" = absent / unparseable / version-gated out. */
 export type ClaudeProbeStatus = "busy" | "shell" | "idle" | "waiting" | "unknown";
@@ -29,6 +30,56 @@ export type ClaudeProbeActivity = "busy" | "idle" | "unknown";
 /** First Claude Code version that writes the session probe. Below this → fallback. */
 export const CLAUDE_PROBE_MIN_VERSION = "2.1.119";
 
+/**
+ * #1621 — True when a probe's `busy`/`shell` assertion is too old to be trusted on its own.
+ *
+ * Claude Code writes this file only on a status TRANSITION, so a cancellation that produces no
+ * transition (an ESC typed into the pane by a human, or relay's OWN prompt-gate Escape) freezes it
+ * on the pre-cancel status. `busy` then becomes an unfalsifiable assertion: the busy backstop
+ * (BusyReconciler) resets its idle streak on every 4s poll and the provider-turn claim is never
+ * cleared — observed live at 2h25m and counting, ended only by a human.
+ *
+ * This is a TRUST window, not a busy timeout: past it the probe is merely no longer allowed to
+ * overrule an input-ready pane (claudeActivityFromProbeAndPane). Long single-tool turns
+ * legitimately hold a frozen probe for many minutes and keep reading busy because the pane keeps
+ * rendering its activity footer — the #766 protection is the pane, not the clock.
+ *
+ * A probe that predates `updatedAt` (older schema) can't be aged, so it keeps today's
+ * unconditional trust: uncertainty resolves toward holding the turn, never toward clearing it.
+ */
+export function claudeProbeBusyIsStale(
+  reading: ClaudeSessionReading,
+  nowMs: number = Date.now(),
+  thresholdMs: number = claudeProbeBusyStaleMsFromEnv(),
+): boolean {
+  if (!reading.available || reading.updatedAt === null) return false;
+  return nowMs - reading.updatedAt >= thresholdMs;
+}
+
+/**
+ * The probe half of an activity read: the mapped 3-valued activity (undefined when the probe is
+ * absent/old/unparseable → the caller falls back to the pane) plus whether a `busy` verdict has
+ * aged out of its trust window (#1621). Returned together because the two are always consumed
+ * together — `busyStale` is meaningless for anything but a busy verdict.
+ */
+export function claudeProbeVerdict(
+  reading: ClaudeSessionReading | undefined,
+  nowMs: number = Date.now(),
+  opts: { paneInterruptAt?: number } = {},
+): { activity: ClaudeProbeActivity | undefined; busyStale: boolean } {
+  const activity = reading?.available ? claudeProbeActivity(reading.status) : undefined;
+  if (activity !== "busy" || !reading) return { activity, busyStale: false };
+  // #1621 — the precise form of the same staleness question, for the case relay CAUSED: relay
+  // typed a turn-cancelling keystroke into the pane (the prompt gate's Escape) and the probe has
+  // not been rewritten since. That is not a guess about elapsed time — it is a busy assertion that
+  // demonstrably predates the cancellation, so it stops being authoritative immediately instead of
+  // after the whole trust window. The pane still has to corroborate the idle read either way.
+  const predatesInterrupt = opts.paneInterruptAt !== undefined
+    && reading.updatedAt !== null
+    && reading.updatedAt <= opts.paneInterruptAt;
+  return { activity, busyStale: predatesInterrupt || claudeProbeBusyIsStale(reading, nowMs) };
+}
+
 export interface ClaudeSessionReading {
   /** Raw probe status, or "unknown" when the probe is absent/old/unparseable. */
   status: ClaudeProbeStatus;
@@ -40,11 +91,15 @@ export interface ClaudeSessionReading {
   procStart: string | null;
   /** `updatedAt` epoch-ms of the last probe write, or null. */
   updatedAt: number | null;
+  /** Claude's own session UUID (#1235) — names the transcript file. Null when absent. */
+  sessionId: string | null;
+  /** The session's cwd (#1235) — slugified into the transcript's project dir. Null when absent. */
+  cwd: string | null;
   /** True iff a present, parseable, version-gated probe produced `status`. */
   available: boolean;
 }
 
-const UNAVAILABLE: ClaudeSessionReading = { status: "unknown", waitingFor: null, version: null, procStart: null, updatedAt: null, available: false };
+const UNAVAILABLE: ClaudeSessionReading = { status: "unknown", waitingFor: null, version: null, procStart: null, updatedAt: null, sessionId: null, cwd: null, available: false };
 
 /**
  * Process-liveness seam for the staleness guard (#769 P1-B), injectable in tests.
@@ -66,7 +121,10 @@ export interface ClaudeProbeLiveness {
 // `updatedAt` for its whole duration (verified: a 90s+ busy turn never rewrote it).
 // A staleness threshold would force a long busy turn back to the pane-scrape and
 // reintroduce the #766 idle-while-working bug; pid-liveness + procStart cover the
-// SIGKILL-frozen and pid-reuse cases without that hazard.
+// SIGKILL-frozen and pid-reuse cases without that hazard. (#1621 does age the busy
+// VERDICT out of authority — see claudeProbeBusyIsStale — but never the reading
+// itself, and only ever in favour of a positively input-ready pane. This invariant
+// stands: `available` is not time-gated.)
 const DEFAULT_LIVENESS: ClaudeProbeLiveness = {
   procStartOf: readProcStartTime,
   pidAlive: isPidAlive,
@@ -129,11 +187,13 @@ export function parseClaudeSessionProbe(raw: string, minVersion = CLAUDE_PROBE_M
   const version = typeof probe.version === "string" ? probe.version : null;
   const procStart = typeof probe.procStart === "string" ? probe.procStart : null;
   const updatedAt = typeof probe.updatedAt === "number" ? probe.updatedAt : null;
-  if (!claudeVersionAtLeast(version, minVersion)) return { ...UNAVAILABLE, version, procStart, updatedAt };
+  const sessionId = typeof probe.sessionId === "string" && probe.sessionId.trim() ? probe.sessionId : null;
+  const cwd = typeof probe.cwd === "string" && probe.cwd.trim() ? probe.cwd : null;
+  if (!claudeVersionAtLeast(version, minVersion)) return { ...UNAVAILABLE, version, procStart, updatedAt, sessionId, cwd };
   const status = normalizeStatus(probe.status);
-  if (status === "unknown") return { status: "unknown", waitingFor: null, version, procStart, updatedAt, available: false };
+  if (status === "unknown") return { status: "unknown", waitingFor: null, version, procStart, updatedAt, sessionId, cwd, available: false };
   const waitingFor = typeof probe.waitingFor === "string" && probe.waitingFor.trim() ? probe.waitingFor : null;
-  return { status, waitingFor, version, procStart, updatedAt, available: true };
+  return { status, waitingFor, version, procStart, updatedAt, sessionId, cwd, available: true };
 }
 
 /**
@@ -195,11 +255,42 @@ export function readManagedClaudeStatus(args: {
   tmuxSession?: string;
   tmuxSocket?: string;
   configHomeEnv?: string;
-}): { reading: ClaudeSessionReading; pid: number } | undefined {
+}): { reading: ClaudeSessionReading; pid: number; configHome: string } | undefined {
   const pid = resolveClaudePid(args.pid, args.tmuxSession, args.tmuxSocket);
   if (pid === undefined) return undefined;
   const configHome = args.configHomeEnv || process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
-  return { reading: readClaudeSessionStatus(configHome, pid), pid };
+  return { reading: readClaudeSessionStatus(configHome, pid), pid, configHome };
+}
+
+/**
+ * The transcript JSONL path Claude Code writes for a session (#1235). Claude stores
+ * per-cwd transcripts at `<configHome>/projects/<cwd-slug>/<sessionId>.jsonl`, where
+ * the slug replaces every non-alphanumeric char in the absolute cwd with `-` (verified
+ * live on CC 2.1.205: `/home/u/p/.agent-relay/x` → `-home-u-p--agent-relay-x`). This is
+ * the hookless path the monitorless turn-watch feeds to the transcript reasoning tail so
+ * isolated/lean Claude workers (no Stop/UserPromptSubmit hooks) still mirror chat.
+ */
+export function claudeTranscriptPath(configHome: string, cwd: string, sessionId: string): string {
+  return join(configHome, "projects", cwd.replace(/[^a-zA-Z0-9]/g, "-"), `${sessionId}.jsonl`);
+}
+
+/**
+ * Resolve the live transcript path for the managed claude via its session probe (#1235):
+ * the probe carries `sessionId` + `cwd`, and the runner knows the config home. Returns
+ * undefined when the probe is absent/old (no sessionId/cwd) or the pid can't be resolved,
+ * which leaves the caller with no native capture (graceful degrade to today's behavior).
+ */
+export function resolveManagedClaudeTranscriptPath(args: {
+  pid?: number;
+  tmuxSession?: string;
+  tmuxSocket?: string;
+  configHomeEnv?: string;
+}): string | undefined {
+  const managed = readManagedClaudeStatus(args);
+  if (!managed) return undefined;
+  const { sessionId, cwd } = managed.reading;
+  if (!sessionId || !cwd) return undefined;
+  return claudeTranscriptPath(managed.configHome, cwd, sessionId);
 }
 
 /**

package/src/adapters/claude-shutdown.ts

@@ -0,0 +1,149 @@
+// #1647 — the Claude tmux shutdown sequence: observe, correlate, and only then
+// (maybe) exit gracefully. Split out of ./claude at the #300 ratchet; the adapter
+// keeps the watcher teardown and delegates the rest here.
+//
+// The policy itself lives in ./claude-exit. This module is the caller that samples
+// live state and drives the loop.
+import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
+import type { ManagedProcess } from "../adapter";
+import { readManagedClaudeStatus } from "./claude-session-probe";
+import { claudePaneIsBusy } from "./claude-status-detectors";
+import { captureTmuxPane } from "./claude-tmux";
+import { authorizeClaudeGracefulExit, claudeExitDenialIsPermanent, confirmClaudeExitDialogUnderGrant, mintClaudeShutdownIntent, submitClaudeExitCommand } from "./claude-exit";
+import type { ClaudeExitGrant, ClaudeExitObservation, ClaudeTurnState } from "./claude-exit";
+
+export function claudeShutdownGraceMs(timeoutMs: number): number {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return 10_000;
+  return Math.min(timeoutMs, 10_000);
+}
+
+// The turn identity a shutdown intent is correlated against. Claude's intrinsic probe
+// has no turn id, so the pair (sessionId, procStart) is the finest-grained identity
+// available: it changes on any restart or session swap, which is exactly the
+// "different process than the one you asked me to stop" case the token must catch.
+export function claudeTurnKey(sessionId: string | null, procStart: string | null): string {
+  return `${sessionId ?? "?"}:${procStart ?? "?"}`;
+}
+
+/**
+ * Sample the facts a graceful exit must correlate against.
+ *
+ * Turn state is deliberately fail-closed: it reads "ended" ONLY on positive evidence
+ * from the intrinsic probe (Claude's own status file, which also carries the sessionId
+ * and procStart that bind this reading to this exact process). The pane scrape is kept
+ * as a VETO — it can turn "ended" into "live", never the reverse — because
+ * `claudePaneIsBusy` alone is exactly what false-negatived while the killed coordinator
+ * was mid-stream. No probe, no exit.
+ */
+export function observeClaudeExitState(
+  process: ManagedProcess,
+  sessionName: string,
+  socketName: string | undefined,
+  fallbackEpoch: number,
+): ClaudeExitObservation {
+  const managed = readManagedClaudeStatus({
+    pid: process.pid,
+    tmuxSession: sessionName,
+    tmuxSocket: socketName,
+    configHomeEnv: (process.meta?.env as Record<string, string | undefined> | undefined)?.CLAUDE_CONFIG_DIR,
+  });
+  const reading = managed?.reading;
+  const probeIdle = reading?.available === true && reading.status === "idle";
+  let turn: ClaudeTurnState = probeIdle ? "ended" : reading?.available === true ? "live" : "unknown";
+  if (turn === "ended") {
+    try {
+      if (claudePaneIsBusy(captureTmuxPane(sessionName, socketName))) turn = "live";
+    } catch {
+      turn = "unknown"; // A pane we cannot read is not a pane we may type into.
+    }
+  }
+  return {
+    epoch: (process.meta?.providerEpoch as number | undefined) ?? fallbackEpoch,
+    ...(process.pid === undefined ? {} : { pid: process.pid }),
+    procStart: reading?.procStart ?? null,
+    sessionName,
+    providerSessionId: reading?.sessionId ?? null,
+    turn,
+    turnKey: claudeTurnKey(reading?.sessionId ?? null, reading?.procStart ?? null),
+    now: Date.now(),
+  };
+}
+
+// Injectable seams so the shutdown loop (which otherwise only talks to a live tmux
+// server) is unit-testable — same pattern as ClaudeClearCommitDeps.
+export interface ClaudeShutdownDeps {
+  hasSession?: (sessionName: string, socketName?: string) => boolean;
+  observe?: (process: ManagedProcess, sessionName: string, socketName?: string) => ClaudeExitObservation;
+  submitExit?: (grant: ClaudeExitGrant) => Promise<unknown>;
+  confirmExit?: (grant: ClaudeExitGrant) => unknown;
+  reap?: (sessionName: string, socketName?: string) => void;
+  sleep?: (ms: number) => Promise<unknown>;
+}
+
+export async function shutdownClaudeTmux(
+  process: ManagedProcess,
+  sessionName: string,
+  opts: { graceful: boolean; timeoutMs: number },
+  socketName: string | undefined,
+  fallbackEpoch: number,
+  deps: ClaudeShutdownDeps = {},
+): Promise<void> {
+  const hasSession = deps.hasSession ?? tmuxHasSession;
+  const observe = deps.observe ?? ((p, s, k) => observeClaudeExitState(p, s, k, fallbackEpoch));
+  const submitExit = deps.submitExit ?? submitClaudeExitCommand;
+  const confirmExit = deps.confirmExit ?? confirmClaudeExitDialogUnderGrant;
+  const sleep = deps.sleep ?? Bun.sleep;
+
+  if (opts.graceful && hasSession(sessionName, socketName)) {
+    // The audited lifecycle request, pinned to the process it was issued against.
+    // Everything below is gated on it; nothing here can be reached from a detector.
+    const observed = observe(process, sessionName, socketName);
+    const intent = mintClaudeShutdownIntent({
+      epoch: observed.epoch,
+      ...(observed.pid === undefined ? {} : { pid: observed.pid }),
+      procStart: observed.procStart,
+      sessionName,
+      providerSessionId: observed.providerSessionId,
+      turnKey: observed.turnKey,
+    });
+
+    let grant: ClaudeExitGrant | undefined;
+    const deadline = Date.now() + claudeShutdownGraceMs(opts.timeoutMs);
+    while (Date.now() < deadline) {
+      if (!hasSession(sessionName, socketName)) return;
+      if (!grant) {
+        // #1647 — the guard that would have saved the coordinator. A turn that is live
+        // (or that we cannot positively confirm has ended) authorizes nothing, so we
+        // keep waiting and let the out-of-band reap below terminate the process if the
+        // turn never settles.
+        const decision = authorizeClaudeGracefulExit(intent, observe(process, sessionName, socketName), socketName);
+        if (decision.authorized) {
+          grant = decision.grant;
+          await submitExit(grant);
+        } else if (claudeExitDenialIsPermanent(decision.reason)) {
+          // Nothing this loop can observe later will change the verdict — waiting out
+          // the grace window would only delay the reap. Terminate out of band now.
+          break;
+        }
+      } else {
+        // `/exit` while a background task is running raises Claude's "Exit anyway /
+        // Move to background / Stay" confirmation (#1514). Answering it is allowed ONLY
+        // through the same grant that submitted that `/exit`, and only for a dialog that
+        // was not already on screen beforehand.
+        confirmExit(grant);
+      }
+      await sleep(200);
+    }
+  }
+
+  // The out-of-band backstop, and the path #1647 prefers: it terminates the process
+  // without typing anything into the pane, so it is always reached when the guard above
+  // declines to authorize a graceful exit.
+  (deps.reap ?? reapTmuxSession)(sessionName, socketName);
+}
+
+function reapTmuxSession(sessionName: string, socketName?: string): void {
+  Bun.spawnSync(tmuxCommand(socketName, "kill-session", "-t", sessionName), {
+    stdin: "ignore", stdout: "ignore", stderr: "ignore",
+  });
+}