@humwick/runner 0.0.0-stage → 0.130.1

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

@@ -0,0 +1,414 @@
+// #766/#768 — Claude Code's intrinsic, machine-readable session probe.
+//
+// Claude Code ≥2.1.119 writes `$CLAUDE_CONFIG_DIR/sessions/<pid>.json` and rewrites
+// it on every status transition. It carries an authoritative `status` field
+// (busy|shell|idle|waiting, plus `waitingFor` when waiting) — the very
+// "machine-readable ready/busy signal" the old pane-scrape comment claimed didn't
+// exist. The runner manages the claude pid and its CLAUDE_CONFIG_DIR, so this is a
+// direct keyed read — no enumeration, no cwd/solo-multi disambiguation.
+//
+// This is the single home (DRY) for reading + version-gating + mapping that probe.
+// `probeActivity`, the BusyReconciler backstop, and the monitorless turn-watch all
+// delegate here; the legacy pane-scrape stays only as the graceful fallback for
+// pre-2.1.119 / probe-missing sessions (e.g. a claude-rig host whose real config
+// home the runner can't resolve). Schema is reverse-engineered (pbauermeister/
+// claude-busy-monitor), so we gate on `version`/presence and degrade gracefully if
+// Anthropic ever drifts it.
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isPidAlive } from "@humwick/sdk/process-utils";
+import type { ManagedProcess } from "../adapter";
+import { resolveClaudePanePidAsync } from "./tmux-offload";
+
+/** Raw probe status; "unknown" = absent / unparseable / version-gated out. */
+export type ClaudeProbeStatus = "busy" | "shell" | "idle" | "waiting" | "unknown";
+
+/** The 3-valued activity the reconciler + monitorless turn-watch consume. */
+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";
+
+/**
+ * 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 `busyStale`: the busy verdict
+ * predates a turn-cancelling keystroke relay itself sent (#1621). Age never discredits it (#3026):
+ * Claude writes neither probe nor transcript during a long think, so a frozen busy is held and the
+ * notify-only prolonged-hold watchdog surfaces a turn that really died out of band.
+ */
+export function claudeProbeVerdict(
+  reading: ClaudeSessionReading | undefined,
+  opts: { paneInterruptAt?: number; lastActivityAt?: number } = {},
+): { activity: ClaudeProbeActivity | undefined; busyStale: boolean } {
+  const activity = reading?.available ? claudeProbeActivity(reading.status) : undefined;
+  if (activity !== "busy" || !reading || opts.paneInterruptAt === undefined || reading.updatedAt === null) {
+    return { activity, busyStale: false };
+  }
+  // #1642 — a transcript append after the interrupt means the cancel did not take.
+  const cancelDidNotTake = opts.lastActivityAt !== undefined && opts.lastActivityAt > opts.paneInterruptAt;
+  return { activity, busyStale: reading.updatedAt <= opts.paneInterruptAt && !cancelDidNotTake };
+}
+
+export interface ClaudeSessionReading {
+  /** Raw probe status, or "unknown" when the probe is absent/old/unparseable. */
+  status: ClaudeProbeStatus;
+  /** `waitingFor` reason when status==="waiting" (e.g. "approve Bash"), else null. */
+  waitingFor: string | null;
+  /** Probe `version`, or null when unavailable. */
+  version: string | null;
+  /** `procStart` (process start-time token: `/proc/<pid>/stat` field 22, or UTC `ps` lstart off Linux), or null. */
+  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, sessionId: null, cwd: null, available: false };
+
+/**
+ * Process-liveness seam for the staleness guard (#769 P1-B), injectable in tests.
+ *   procStartOf — the start-time token of a LIVE pid (to compare against the probe's
+ *     `procStart`), or null when the pid is dead/unreadable. Catches both a frozen
+ *     probe from a SIGKILLed claude AND a sub-second pid-reuse window (a reused pid
+ *     has a different start time).
+ *   pidAlive — liveness fallback for probes that predate `procStart`.
+ */
+export interface ClaudeProbeLivenessAsync {
+  procStartOf(pid: number): Promise<string | null>;
+  pidAlive(pid: number): boolean;
+}
+
+/** field 22 (starttime) of a `/proc/<pid>/stat` body; comm (field 2) may hold spaces and ')'. */
+function procStatStartTime(stat: string): string | null {
+  return stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/)[19] ?? null;
+}
+
+// #1838 rows 14/15 — off-loop: the 4s reconciler / 1.5s turn-watch tick never blocks on the read.
+async function readProcStartTimeAsync(pid: number): Promise<string | null> {
+  try {
+    return procStatStartTime(await readFile(`/proc/${pid}/stat`, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// #3151 — off Linux, Claude stamps procStart as `ps -o lstart=` in UTC ("Sun Oct 25 13:01:19 2026").
+const PS_LSTART_TIMEOUT_MS = 5_000;
+const psLstartArgv = (pid: number): string[] => ["ps", "-o", "lstart=", "-p", String(pid)];
+const psLstartEnv = (): Record<string, string | undefined> => ({ ...process.env, TZ: "UTC", LC_ALL: "C" });
+
+/** Whitespace-normalized start-time token; `ps` pads lstart, and pads a one-digit day. */
+function procStartToken(raw: string | null | undefined): string | null {
+  const token = raw?.replace(/\s+/g, " ").trim();
+  return token || null;
+}
+
+export async function readPsLstartUtcAsync(pid: number): Promise<string | null> {
+  try {
+    const child = Bun.spawn(psLstartArgv(pid), { env: psLstartEnv(), stdout: "pipe", stderr: "ignore", timeout: PS_LSTART_TIMEOUT_MS, killSignal: "SIGKILL" });
+    const [stdout, exitCode] = await Promise.all([new Response(child.stdout).text(), child.exited]);
+    return exitCode === 0 ? procStartToken(stdout) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Default liveness. On Linux `procStart` in the probe is `/proc/<pid>/stat` field 22
+// (starttime, clock-ticks since boot) — verified equal live on CC 2.1.193; elsewhere it is UTC `ps` lstart.
+// NB: we deliberately do NOT gate on `updatedAt` freshness — Claude only rewrites
+// the probe on a status *transition*, so a legitimately busy turn keeps a frozen
+// `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. `available` is not
+// time-gated, and neither is the busy verdict (#3026, see claudeProbeVerdict).
+/** The off-loop probe liveness check for `platform`: `/proc` on Linux, UTC `ps` lstart elsewhere. */
+export function claudeProbeLivenessAsync(
+  platform: string = process.platform,
+  lstart: (pid: number) => Promise<string | null> = readPsLstartUtcAsync,
+): ClaudeProbeLivenessAsync {
+  return { procStartOf: platform === "linux" ? readProcStartTimeAsync : lstart, pidAlive: isPidAlive };
+}
+
+const DEFAULT_LIVENESS_ASYNC = claudeProbeLivenessAsync();
+
+/** Whether a probe's recorded procStart names the process that owns `pid` now. */
+function procStartMatches(recorded: string, live: string | null): boolean {
+  return live !== null && procStartToken(recorded) === procStartToken(live);
+}
+
+/**
+ * Stable process-incarnation token for a pane PID. A session probe's own procStart only
+ * proves that probe agrees with whichever process owns the number *now*; monitorless watches
+ * must instead pin the pane incarnation they started with so PID reuse cannot cross sessions.
+ */
+export async function claudeProcessIncarnationAsync(pid: number): Promise<string | undefined> {
+  return (await DEFAULT_LIVENESS_ASYNC.procStartOf(pid)) ?? undefined;
+}
+
+/** The per-session probe path the runner reads directly (keyed by claude's pid). */
+export function claudeSessionProbePath(configHome: string, pid: number): string {
+  return join(configHome, "sessions", `${pid}.json`);
+}
+
+/** Dotted-version compare; true iff `version` >= `min`. Missing/non-numeric → gate closed. */
+export function claudeVersionAtLeast(version: string | null | undefined, min: string): boolean {
+  if (!version) return false;
+  const actual = version.split(".");
+  const wanted = min.split(".");
+  for (let i = 0; i < wanted.length; i++) {
+    const x = Number.parseInt(actual[i] ?? "0", 10);
+    const y = Number.parseInt(wanted[i] ?? "0", 10);
+    if (Number.isNaN(x)) return false; // unparseable build → fall back, don't trust the probe
+    if (x !== y) return x > y;
+  }
+  return true;
+}
+
+function normalizeStatus(value: unknown): ClaudeProbeStatus {
+  switch (value) {
+    case "busy":
+    case "shell":
+    case "idle":
+    case "waiting":
+      return value;
+    default:
+      return "unknown";
+  }
+}
+
+/** Pure: parse a probe JSON body + version-gate it. Malformed / old / unknown status → unavailable. */
+export function parseClaudeSessionProbe(raw: string, minVersion = CLAUDE_PROBE_MIN_VERSION): ClaudeSessionReading {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return UNAVAILABLE;
+  }
+  if (!parsed || typeof parsed !== "object") return UNAVAILABLE;
+  const probe = parsed as Record<string, unknown>;
+  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;
+  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, sessionId, cwd, available: false };
+  const waitingFor = typeof probe.waitingFor === "string" && probe.waitingFor.trim() ? probe.waitingFor : null;
+  return { status, waitingFor, version, procStart, updatedAt, sessionId, cwd, available: true };
+}
+
+/**
+ * Read + parse the probe for `pid` under `configHome`. Missing file (older CC, a config home the
+ * runner can't resolve, or claude not yet started) → unavailable, so the caller falls back to the
+ * pane-scrape. Off-loop (#1838): every caller is a timer tick or the async `/exit` correlator.
+ */
+export async function readClaudeSessionStatusAsync(
+  configHome: string,
+  pid: number,
+  opts: { minVersion?: string; liveness?: ClaudeProbeLivenessAsync } = {},
+): Promise<ClaudeSessionReading> {
+  let raw: string;
+  try {
+    raw = await readFile(claudeSessionProbePath(configHome, pid), "utf8");
+  } catch {
+    return UNAVAILABLE;
+  }
+  const reading = parseClaudeSessionProbe(raw, opts.minVersion ?? CLAUDE_PROBE_MIN_VERSION);
+  if (!reading.available) return reading;
+  // #769 P1-B: a frozen probe from a SIGKILLed claude (or a reused pid) would report a stale
+  // busy/shell forever. Verify the pid still belongs to the same process.
+  const live = opts.liveness ?? DEFAULT_LIVENESS_ASYNC;
+  if (reading.procStart) {
+    if (!procStartMatches(reading.procStart, await live.procStartOf(pid))) return { ...reading, status: "unknown", available: false };
+  } else if (!live.pidAlive(pid)) {
+    return { ...reading, status: "unknown", available: false };
+  }
+  return reading;
+}
+
+export interface ManagedClaudeProbeArgs {
+  pid?: number;
+  tmuxSession?: string;
+  tmuxSocket?: string;
+  configHomeEnv?: string;
+}
+
+/**
+ * The probe-lookup args for a tmux-launched Claude ManagedProcess. One home for the
+ * pid/session/socket/config-home tuple every caller of {@link readManagedClaudeStatusAsync}
+ * needs to assemble — the CLAUDE_CONFIG_DIR dig in particular was already being repeated.
+ */
+export function claudeProbeArgsFor(process: ManagedProcess, tmuxSession: string, tmuxSocket?: string): ManagedClaudeProbeArgs {
+  const env = process.meta?.env as Record<string, string | undefined> | undefined;
+  return { pid: process.pid, tmuxSession, tmuxSocket, configHomeEnv: env?.CLAUDE_CONFIG_DIR };
+}
+
+/**
+ * #2261 — a clear-commit probe reading: Claude's own session UUID together with the pid it was
+ * read for. A committed `/clear` mints a NEW session, so a rotation of `sessionId` OBSERVED FOR
+ * THE SAME PID is machine-readable proof the loaded conversation is gone.
+ */
+export interface ClaudeClearSessionReading { sessionId: string; pid: number }
+
+/**
+ * Read one, or null for every "could not find out" outcome: no resolvable pid, no probe file, a
+ * version-gated-out or liveness-failed reading (`available === false`, which is what rules out a
+ * SIGKILL-frozen probe and a reused pid — #769 P1-B), or a probe carrying no sessionId at all.
+ * Deliberately total (never throws, never distinguishes flavours of absence): its only consumer
+ * treats anything short of a confirmed same-pid rotation as no evidence.
+ */
+export async function readClaudeClearSessionAsync(args: ManagedClaudeProbeArgs): Promise<ClaudeClearSessionReading | null> {
+  try {
+    const managed = await readManagedClaudeStatusAsync(args);
+    if (!managed?.reading.available || !managed.reading.sessionId) return null;
+    return { sessionId: managed.reading.sessionId, pid: managed.pid };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * #2261 — bind a clear-commit reader to ONE pane pid, resolved up front.
+ *
+ * The barrier polls ~50 times inside its 10s budget. Re-resolving the pane pid per poll spawned a
+ * `tmux display-message` each time (the pid is undefined for a tmux launch), and — worse — let the
+ * pid CHANGE mid-wait: a restarted claude whose predecessor's `sessions/<pid>.json` still exists
+ * would surface a different sessionId and read as a rotation. Pinning the pid makes both go away;
+ * `undefined` (no resolvable pid) means no probe evidence is available at all.
+ */
+export async function bindClaudeClearSessionReader(
+  process: ManagedProcess,
+  tmuxSession: string,
+  tmuxSocket?: string,
+): Promise<(() => Promise<ClaudeClearSessionReading | null>) | undefined> {
+  const pid = await resolveClaudePanePidAsync(process.pid, tmuxSession, tmuxSocket);
+  if (pid === undefined) return undefined;
+  const args = { ...claudeProbeArgsFor(process, tmuxSession, tmuxSocket), pid };
+  return () => readClaudeClearSessionAsync(args);
+}
+
+/** What the probe says about whether the `/clear` committed. `unknown` = no usable evidence. */
+export type ClaudeClearSessionVerdict = "rotated" | "unchanged" | "unknown";
+
+/**
+ * #2261 — compare a pre-clear reading against a current one. Both must be present AND describe the
+ * SAME pid; anything else is `unknown`, never a verdict. A `rotated` verdict is positive proof the
+ * clear committed; an `unchanged` one is positive proof it has NOT (yet) — the probe is
+ * authoritative in both directions whenever it is readable on both sides.
+ */
+export function claudeClearSessionVerdict(
+  preClear: ClaudeClearSessionReading | null | undefined,
+  current: ClaudeClearSessionReading | null | undefined,
+): ClaudeClearSessionVerdict {
+  if (!preClear || !current || current.pid !== preClear.pid) return "unknown";
+  return current.sessionId === preClear.sessionId ? "unchanged" : "rotated";
+}
+
+/**
+ * Resolve the managed claude's pid (direct, or the tmux pane pid: the launcher `exec`s claude) and
+ * config home, then read its probe. undefined when the pid can't be resolved.
+ */
+export async function readManagedClaudeStatusAsync(
+  args: ManagedClaudeProbeArgs,
+  liveness?: ClaudeProbeLivenessAsync,
+): Promise<{ reading: ClaudeSessionReading; pid: number; configHome: string } | undefined> {
+  const pid = await resolveClaudePanePidAsync(args.pid, args.tmuxSession, args.tmuxSocket);
+  if (pid === undefined) return undefined;
+  const configHome = claudeConfigHome(args.configHomeEnv);
+  return { reading: await readClaudeSessionStatusAsync(configHome, pid, { liveness }), 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.
+ */
+/** The config home a Claude process uses: its CLAUDE_CONFIG_DIR, the runner's, or the host default. */
+export function claudeConfigHome(configHomeEnv?: string): string {
+  return configHomeEnv || process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+}
+
+export function claudeTranscriptPath(configHome: string, cwd: string, sessionId: string): string {
+  return join(configHome, "projects", cwd.replace(/[^a-zA-Z0-9]/g, "-"), `${sessionId}.jsonl`);
+}
+
+/**
+ * #1642 — the transcript's last-modified time in epoch-ms, or undefined when it can't be read
+ * (absent/old probe with no sessionId+cwd, or the file not yet created). Claude appends to this
+ * JSONL on every turn event, so its mtime is the runner's hookless "events still flowing"
+ * heartbeat — the signal that keeps an actively-streaming turn's frozen busy probe from being
+ * aged out to the pane. A failed stat is silence, never a claim the turn ended: undefined leaves
+ * #1621 untouched.
+ *
+ * #1838 rows 14/15 — the only caller (the busy reconciler / turn watch, via activityFromProbeOrPane)
+ * is now off the event loop, so this is the sole variant and uses `fs/promises`. (The synchronous
+ * version was removed in the #1838 round-3 review: it had no production callers once the hot path
+ * went async — see the critical-loop ratchet note for claude-session-probe.ts.)
+ */
+export async function claudeTranscriptMtimeMsAsync(
+  reading: Pick<ClaudeSessionReading, "sessionId" | "cwd"> | undefined,
+  configHome: string | undefined,
+): Promise<number | undefined> {
+  const sessionId = reading?.sessionId;
+  const cwd = reading?.cwd;
+  if (!sessionId || !cwd || !configHome) return undefined;
+  try {
+    return (await stat(claudeTranscriptPath(configHome, cwd, sessionId))).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 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. undefined when the
+ * probe is absent/old or the pid can't be resolved (graceful degrade: no native capture).
+ */
+export async function resolveManagedClaudeTranscriptPathAsync(args: {
+  pid?: number;
+  tmuxSession?: string;
+  tmuxSocket?: string;
+  configHomeEnv?: string;
+}): Promise<string | undefined> {
+  const managed = await readManagedClaudeStatusAsync(args);
+  if (!managed) return undefined;
+  const { sessionId, cwd } = managed.reading;
+  if (!sessionId || !cwd) return undefined;
+  return claudeTranscriptPath(managed.configHome, cwd, sessionId);
+}
+
+/**
+ * Map the intrinsic probe status to the 3-valued activity. The whole point of #766:
+ *   busy       → busy   — a turn is running, foreground tools included; the old
+ *                         pane-scrape misread it as idle and force-cleared.
+ *   idle/shell → idle   — `shell` is Claude's `idle` while a background local_bash task
+ *                         is alive (2.1.310: `status==="idle" && hasLiveLocalBash`).
+ *                         Relay's own monitor is one, so a managed session at rest
+ *                         reads `shell`, including right after an ESC (#2202).
+ *   waiting    → unknown — a permission/input dialog is a parked (not done) turn, so
+ *                          we neither assert compute-busy nor let the backstop clear
+ *                          the live turn. `waitingFor` is surfaced separately for
+ *                          permission/asking detection.
+ */
+export function claudeProbeActivity(status: ClaudeProbeStatus): ClaudeProbeActivity {
+  switch (status) {
+    case "busy":
+      return "busy";
+    case "idle":
+    case "shell":
+      return "idle";
+    default:
+      return "unknown";
+  }
+}

package/src/adapters/claude-shutdown.ts

@@ -0,0 +1,190 @@
+// #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 { managedTmuxSocketName, prepareTmuxPaneStop, prepareTmuxStop, tmuxHasSession, type PreparedTmuxStop } from "@humwick/sdk/tmux-utils";
+import { tmuxOwnerIdFromEnv } from "../config";
+import type { ManagedProcess, ShutdownOutcome } from "../adapter";
+import { claudeProbeActivity, claudeProbeArgsFor, readManagedClaudeStatusAsync, type ClaudeProbeLivenessAsync } from "./claude-session-probe";
+import { claudePaneIsBusy } from "./claude-status-detectors";
+import { captureTmuxPaneAsync } from "./tmux-offload";
+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 async function observeClaudeExitState(
+  process: ManagedProcess,
+  sessionName: string,
+  socketName: string | undefined,
+  fallbackEpoch: number,
+  seams: { liveness?: ClaudeProbeLivenessAsync; capturePane?: typeof captureTmuxPaneAsync } = {},
+): Promise<ClaudeExitObservation> {
+  // #3152 — the shared off-loop reader, so a macOS `ps` lstart procStart binds this reading too.
+  const managed = await readManagedClaudeStatusAsync(claudeProbeArgsFor(process, sessionName, socketName), seams.liveness);
+  const reading = managed?.reading;
+  // #3186 — a managed Claude at rest reads `shell` (Relay's monitor is a live background task).
+  const probeIdle = reading?.available === true && claudeProbeActivity(reading.status) === "idle";
+  let turn: ClaudeTurnState = probeIdle ? "ended" : reading?.available === true ? "live" : "unknown";
+  if (turn === "ended") {
+    try {
+      if (claudePaneIsBusy(await (seams.capturePane ?? captureTmuxPaneAsync)(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 | Promise<ClaudeExitObservation>;
+  submitExit?: (grant: ClaudeExitGrant) => Promise<unknown>;
+  confirmExit?: (grant: ClaudeExitGrant) => unknown;
+  // #1746 — the reap now returns a terminal outcome (it verifies death, it does not merely
+  // fire a kill-session). Tests that only care that the reap ran may still return void.
+  reap?: (sessionName: string, socketName?: string) => ShutdownOutcome | void | Promise<ShutdownOutcome | void>;
+  sleep?: (ms: number) => Promise<unknown>;
+  prepareStop?: (sessionName: string, socketName?: string) => Promise<PreparedTmuxStop>;
+  preparePaneStop?: typeof prepareTmuxPaneStop;
+}
+
+export async function shutdownClaudeTmux(
+  process: ManagedProcess,
+  sessionName: string,
+  opts: { graceful: boolean; timeoutMs: number },
+  socketName: string | undefined,
+  fallbackEpoch: number,
+  deps: ClaudeShutdownDeps = {},
+): Promise<ShutdownOutcome> {
+  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;
+  const stop = deps.reap
+    ? async () => (await deps.reap!(sessionName, socketName)) ?? "killed"
+    : await prepareClaudeStop(sessionName, socketName, deps);
+
+  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 = await 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) {
+      // Session disappearance still requires verification of the captured descendants.
+      if (!hasSession(sessionName, socketName)) return stop();
+      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, await 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. #1746 — this is now a VERIFIED, escalating
+  // force-kill that returns a terminal outcome, not a fire-and-forget kill-session.
+  return stop();
+}
+
+async function prepareClaudeStop(sessionName: string, socketName: string | undefined, deps: ClaudeShutdownDeps): Promise<() => Promise<ShutdownOutcome>> {
+  const prepare = () => (deps.prepareStop ?? ((name, socket) => prepareTmuxStop({ name, socket,
+    onFailure: (failure) => console.error("[claude] Managed tmux stop failed", JSON.stringify({
+      at: new Date().toISOString(), name, socket, ...failure,
+    })),
+  })))(sessionName, socketName);
+  const preparePane = async () => socketName === managedTmuxSocketName(sessionName)
+    ? (deps.preparePaneStop ?? prepareTmuxPaneStop)({ name: sessionName, socket: socketName, owner: tmuxOwnerIdFromEnv() }).catch(() => undefined)
+    : undefined;
+  let fallback = await preparePane();
+  const stop = await prepare().catch(() => undefined);
+  const capturedGone = () => stop?.verifyCaptured?.() ?? Promise.resolve(true);
+  const paneGone = () => fallback?.gone?.() ?? Promise.resolve(true);
+  return async () => {
+    if (stop && (!fallback || await fallback.matches() || await fallback.gone?.())
+      && await stop() && await capturedGone() && await paneGone()) return "killed";
+    if (!stop || stop.captureComplete === false) {
+      fallback ??= await preparePane();
+      // Fence both sides of the retry: a replacement cannot borrow the failed capture.
+      if (fallback && await fallback.matches()) {
+        const retry = await prepare().catch(() => undefined);
+        if (retry && await fallback.matches() && await retry() && await capturedGone() && await paneGone()) return "killed";
+      }
+    }
+    if (fallback && await fallback.stop() && (!stop || stop.captureComplete === false || await stop())
+      && await capturedGone() && await paneGone()) return "killed";
+    return "failed-to-kill";
+  };
+}
+
+/** Shared portable teardown verifies the pane, descendants, and private tmux server. */
+export async function terminateClaudeTmux(
+  sessionName: string,
+  socketName: string | undefined,
+  deps: ClaudeShutdownDeps = {},
+): Promise<ShutdownOutcome> {
+  return (await prepareClaudeStop(sessionName, socketName, deps))();
+}