@humwick/server 0.0.0-stage → 0.130.1

package/runner/src/adapters/claude.ts

@@ -0,0 +1,1097 @@
+import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
+import { claudeSubagentEnv, claudeSubagentPolicy, configureClaudeSubagentLaunch, verifyClaudeSubagentVersion } from "./claude-subagents";
+import { submitClaudeContextCommand } from "./claude-context-command";
+import { scopeClaudeCredentialEnv } from "./claude-credentials";
+import { claudeEffortLaunch, claudeEffortSwitchMeta, switchClaudeEffort } from "./claude-effort";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fireAndForget, sanitizeLaunchBoundary, sanitizeLaunchText, type LivenessSignal, type Message } from "@humwick/sdk";
+import { shellEscape as shellQuote } from "@humwick/sdk/shell-utils";
+import { tmuxCommand, tmuxHasSession } from "@humwick/sdk/tmux-utils";
+import { isPidAlive } from "@humwick/sdk/process-utils";
+import { launchPath } from "@humwick/sdk/runtime-prefix";
+import { spawnSyncBounded } from "../bounded-spawn-sync";
+import { profileAllowsRelayFeature, providerAttachmentLocalPaths, type DeliverResult, type ManagedProcess, type PaneBusyReading, type PaneObservation, type ProviderAdapter, type ProviderConfig, type ProviderDeliverContext, type ProviderSessionTurnContext, type ProviderSessionTurnInput, type ProviderSessionTurnResult, type ProviderStatusUpdate, type PromptOfferOptions, type ProviderTokenUsageReporter, type RunnerSpawnConfig, type ShutdownOutcome, type SpawnArgs } from "../adapter";
+import { computeLivenessSignal, type LivenessInputs } from "../liveness";
+import { hydrateClaudeHostConfig, prepareClaudeProfileHome, readClaudeHostConfig, readClaudeHostSettings } from "../profile-home";
+import { assembleLaunch, materializeLaunchAssembly, sessionStatusLineSettingsArgs, stripSettingsArgs } from "../launch-assembly";
+import { claudeProviderMessageText } from "./claude-delivery";
+import { deliverClaudeByLane } from "./claude-delivery-lanes";
+import { claudeHookPromptMatches } from "./claude-prompt-hook";
+import { bindClaudeClearSessionReader, claudeProcessIncarnationAsync, claudeProbeArgsFor, claudeProbeVerdict, claudeTranscriptMtimeMsAsync, readManagedClaudeStatusAsync, resolveManagedClaudeTranscriptPathAsync, type ClaudeProbeActivity } from "./claude-session-probe";
+import { evaluateClaudePromptGatePane, initialClaudePromptGatePaneState, type ClaudePromptGatePaneState } from "./claude-prompt-gates";
+import { claudeActivityFromProbeAndPane, claudeBypassDialogDisplayGate, claudeBypassPermissionDialog, claudePaneLooksReady, claudePaneIsBusy, claudeRateLimitStatus, claudeConnectionRetryObservation, claudeConnectionRetryClearedObservation, claudeModelUnavailableObservation, debounceClaudeModelUnavailableObservation, initialClaudeModelUnavailableObservationState } from "./claude-status-detectors";
+import { ClaudeSessionCapture, collectClaudeTranscriptArchiveSegment, collectClaudeTranscriptSessionEvents } from "./claude-session-capture";
+import { claudeToolHookPaths, extractLatestContextUsage } from "./claude-transcript";
+import { ClaudeTranscriptTokenUsageCapture } from "./claude-token-usage-capture";
+import { CLAUDE_CLEAR_COMMIT_CAPTURE, CLAUDE_TMUX_READY_TIMEOUT_MS, claudeOneShotExitStatus, confirmClaudeSubmitRecovery, confirmTmuxSessionGone, createLauncherGate, createTmuxSessionWithEnv, releaseClaudeSubmitFence, releaseLauncherGate, seedClaudeInitialPrompt, submitTextToTmux, tmuxEnvKeys, tmuxSessionName, tmuxSessionTargetName, tmuxSocketName, waitForClaudeClearCommitted, waitForClaudeInputReady, writeLauncherScript } from "./claude-tmux";
+import { captureTmuxPaneAsync, captureTmuxVisiblePaneAsync, resolveClaudePanePidAsync, tmuxSessionPresence } from "./tmux-offload";
+import { claudeShutdownGraceMs, shutdownClaudeTmux, type ClaudeShutdownDeps } from "./claude-shutdown";
+import { claudePermissionPromptHandler } from "./claude-permission";
+import { claudeHarnessTrim, claudeProfileDisallowedToolsArgs } from "./claude-tool-policy";
+import { claudeProjectShellEnv } from "./project-shell";
+import { launcherGatePathForSession, stageOneShotPrompt } from "../session-scratch";
+
+type MonitorlessTurnWatchDeps = {
+  resolvePanePid: typeof resolveClaudePanePidAsync;
+  processIncarnation: typeof claudeProcessIncarnationAsync;
+  resolveTranscriptPath: typeof resolveManagedClaudeTranscriptPathAsync;
+  sessionPresence: typeof tmuxSessionPresence;
+  activity: (process: ManagedProcess, session: string, socket?: string) => Promise<ClaudeProbeActivity>;
+  pollMs: number;
+};
+
+export class ClaudeAdapter implements ProviderAdapter {
+  // #2513 — provider-id-dynamic (the id-parameterized OpenCodeAdapter pattern): the
+  // claude-b provider reuses this adapter whole, launching the same binary through the
+  // same wiring under its own id/home/credential. Everything that identified "claude"
+  // flows from this id; the launch assemblies/profile homes key off it the same way.
+  readonly provider: string;
+  readonly statusSourceId: string;
+  private readonly paneSourceId: string;
+  readonly stopObligationPath = "claude-stop";
+  readonly permissionPromptHandler = claudePermissionPromptHandler;
+  readonly compactSupportsInstructions = false;
+  readonly compactReportsSubmission = 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;
+  // #2043 F1 — Claude's /compact and /clear are blind tmux keystrokes with no delivery handshake:
+  // submitted mid-turn they queue behind the live turn and dequeue as literal chat (never parsed as
+  // slash commands), so the compaction silently no-ops. The runner gates the submit on the live
+  // provider turn clearing so the keystrokes always land on an idle prompt. Codex omits this
+  // (awaited app-server handshake — the await is the barrier).
+  readonly awaitsIdleBeforeContextCommand = 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 readonly monitorlessTurnWatch: MonitorlessTurnWatchDeps;
+  private statusCb: (status: ProviderStatusUpdate) => void = () => {};
+  // #1651 — the pane watcher's ONLY outbound channel for anything it inferred from pane text.
+  // Pane observations cannot end work or send input. A startup modal may carry only
+  // a display gate, which the runner publishes as a badge and timeline event.
+  private paneObservationCb: (observation: PaneObservation) => void = () => {};
+  private tmuxWatcher?: Timer; private turnWatcher?: Timer;
+  private turnWatchResume?: { process: ManagedProcess; sessionName: string; socketName?: string };
+  private statusWatchersStopped = false;
+  // #1838 review HIGH-1 — monotonic turn-watch generation. Captured when a monitorless
+  // turn-watch is armed and bumped by stopTurnWatch(); the async setup and every in-flight
+  // tick re-check it after each await and before any state mutation / status emit, so a
+  // shutdown or a replacement invalidates a predecessor's setup AND its outstanding ticks. The
+  // pane watcher fences on Timer identity (`this.tmuxWatcher !== watcher`) instead — the same
+  // guarantee, checked after every await there.
+  private turnWatchGen = 0;
+  // #1838 review MED — the pane pid resolved OFF the loop once per spawn and cached, so the
+  // synchronous resolveBusyPid() (called inline from the runner core on every provider-turn
+  // busy edge) can answer without a blocking tmux display-message spawn. undefined until the
+  // async resolve lands (graceful: the runner falls back to its other liveness signals).
+  private tmuxPanePid?: number;
+  private modelUnavailableObservationState = initialClaudeModelUnavailableObservationState(); private connectionRetryActive = false;
+  private promptGatePaneState: ClaudePromptGatePaneState = initialClaudePromptGatePaneState();
+  private startupReadyObserved = false;
+  private startupBypassDialogActive = false;
+  private startupOpenApproval = false;
+  // #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;
+
+  constructor(opts: { provider?: string; monitorlessTurnWatch?: Partial<MonitorlessTurnWatchDeps> } = {}) {
+    // `stopObligationPath` stays the literal "claude-stop" for every claude-family id:
+    // the bundled plugin's hook curls this exact control-server path (relay-status.sh).
+    this.provider = opts.provider ?? "claude";
+    this.statusSourceId = this.provider;
+    this.paneSourceId = `${this.statusSourceId}-pane`;
+    const injected = opts.monitorlessTurnWatch;
+    this.monitorlessTurnWatch = {
+      resolvePanePid: injected?.resolvePanePid ?? resolveClaudePanePidAsync,
+      processIncarnation: injected?.processIncarnation ?? claudeProcessIncarnationAsync,
+      resolveTranscriptPath: injected?.resolveTranscriptPath ?? resolveManagedClaudeTranscriptPathAsync,
+      sessionPresence: injected?.sessionPresence ?? tmuxSessionPresence,
+      activity: injected?.activity ?? ((process, session, socket) => this.activityFromProbeOrPane(process, session, socket)),
+      pollMs: injected?.pollMs ?? CLAUDE_TURN_POLL_MS,
+    };
+  }
+  private readonly sessionCapture = new ClaudeSessionCapture();
+  private tokenUsageCapture?: ClaudeTranscriptTokenUsageCapture;
+  private tokenUsageReporter?: ProviderTokenUsageReporter;
+  // #2491 — dedupes the empty-pass INFO log to once per turn: a turn's own capture pass (and
+  // any mid-turn permission pre-flush pass) can otherwise post 0 entries repeatedly for the
+  // same turn while its JSONL flush is still in flight.
+  private lastEmptyTokenUsageLogTurnKey?: string;
+  readonly onSessionEvent = this.sessionCapture.onSessionEvent.bind(this.sessionCapture);
+  readonly onSessionEvents = this.sessionCapture.onSessionEvents.bind(this.sessionCapture);
+  readonly handleUserPrompt = this.sessionCapture.handleUserPrompt.bind(this.sessionCapture); readonly handleHookCheck = this.sessionCapture.handleHookCheck.bind(this.sessionCapture); readonly toolHookPaths = claudeToolHookPaths;
+  readonly matchesSubmittedPrompt = claudeHookPromptMatches;
+  readonly drainSessionTrace = this.sessionCapture.drainReasoningTail.bind(this.sessionCapture);
+  readonly settleSessionTraceForToolUse = this.sessionCapture.settlePollForToolUse.bind(this.sessionCapture);
+  readonly stopSessionTrace = this.sessionCapture.stopSessionTrace.bind(this.sessionCapture);
+  readonly collectSessionEvents = collectClaudeTranscriptSessionEvents;
+  readonly collectSessionArchiveSegment = collectClaudeTranscriptArchiveSegment;
+
+  configureTokenUsageReporter(reporter: ProviderTokenUsageReporter): void {
+    this.tokenUsageReporter = reporter;
+    this.tokenUsageCapture = new ClaudeTranscriptTokenUsageCapture({
+      post: reporter.report,
+      debug: reporter.debug,
+    });
+  }
+
+  captureSessionTurn(input: ProviderSessionTurnInput, ctx: ProviderSessionTurnContext): Promise<ProviderSessionTurnResult | void> {
+    const sessionCapture = this.sessionCapture.captureSessionTurn(input, ctx);
+    if (input.transcriptPath && this.tokenUsageCapture) {
+      const transcriptPath = input.transcriptPath;
+      const turnKey = ctx.turnId ?? input.promptId ?? transcriptPath;
+      void this.tokenUsageCapture.capture(transcriptPath).then((postedCount) => {
+        // #2491 — an empty pass previously logged nothing at all; a turn's own one-shot
+        // capture racing the JSONL flush is exactly the condition this fix addresses, so it
+        // must be visible at INFO without flipping log level (see also the reportFailure
+        // wiring in runner-core.ts, moved off DEBUG for the same reason).
+        if (postedCount === 0 && turnKey !== this.lastEmptyTokenUsageLogTurnKey) {
+          this.lastEmptyTokenUsageLogTurnKey = turnKey;
+          ctx.log(`token-usage capture: empty pass for turn ${turnKey} (transcript ${transcriptPath})`);
+        }
+      }).catch((error) => {
+        this.tokenUsageReporter?.reportFailure(error);
+      });
+    }
+    return sessionCapture;
+  }
+
+  async captureSubagentTokenUsage(transcriptPath: string): Promise<void> {
+    if (!this.tokenUsageCapture) throw new Error("Token usage reporter is not configured");
+    await this.tokenUsageCapture.captureSubagent(transcriptPath, true);
+  }
+
+  async captureFinalTokenUsage(transcriptPath: string | undefined, ctx: ProviderSessionTurnContext): Promise<void> {
+    // #2484 round 2 review (MED-1) — this adapter owns the transcript-presence bail now
+    // (previously lived in the shared runner-core seam, which made it Claude-shaped for every
+    // adapter): Claude's capture tails a JSONL transcript file, so it has nothing to settle
+    // without a real path.
+    if (!transcriptPath || !this.tokenUsageCapture) return;
+    await this.tokenUsageCapture.captureWithSettle(transcriptPath, {
+      pollIntervalMs: ctx.settlePollIntervalMs,
+      timeoutMs: ctx.settlePollTimeoutMs,
+    }).catch((error) => this.tokenUsageReporter?.reportFailure(error));
+  }
+
+  onStatusChange(cb: (status: ProviderStatusUpdate) => void): void {
+    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
+  // turn reading as progressing instead of wedged. Transport frames/acks + the server's
+  // lastSeen floor cover long token-silent thinking turns. The fold itself is shared; this
+  // override exists to document and own Claude's progress sources behind the contract.
+  liveness(inputs: LivenessInputs): LivenessSignal {
+    return computeLivenessSignal(inputs);
+  }
+
+  async preloadRunnerConfig(): Promise<Pick<RunnerSpawnConfig, "hostClaudeConfig" | "hostClaudeSettings"> | undefined> {
+    const [hostClaudeConfig, hostClaudeSettings] = await Promise.all([readClaudeHostConfig(this.provider), readClaudeHostSettings(this.provider)]);
+    return hostClaudeConfig || hostClaudeSettings ? { ...(hostClaudeConfig ? { hostClaudeConfig } : {}), ...(hostClaudeSettings ? { hostClaudeSettings } : {}) } : undefined;
+  }
+
+  hydrateSpawnConfig(config: RunnerSpawnConfig): Promise<RunnerSpawnConfig> {
+    return hydrateClaudeHostConfig(config, this.provider);
+  }
+
+  async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
+    // A provider spawn is the adapter incarnation boundary on both tmux/headless and direct
+    // interactive paths. Invalidate predecessor watchers before reopening the new incarnation,
+    // but retain the stopped predecessor's resume descriptor if spawn itself throws: runner-core
+    // will reopen that still-live incarnation rather than leaving its monitorless lane dark.
+    const priorTurnWatchResume = this.turnWatchResume;
+    this.stopTurnWatch();
+    if (this.tmuxWatcher) clearInterval(this.tmuxWatcher);
+    this.tmuxWatcher = undefined;
+    this.statusWatchersStopped = false;
+    try {
+      await verifyClaudeSubagentVersion(config);
+      const hydratedConfig = await this.hydrateSpawnConfig(config); const args = this.buildSpawnArgs(hydratedConfig, hydratedConfig.providerConfig as ProviderConfig);
+      if (hydratedConfig.headless) return this.spawnHeadless(hydratedConfig, args);
+
+      const proc = Bun.spawn([args.command, ...args.args], {
+        cwd: args.cwd,
+        env: args.env,
+        stdin: "inherit",
+        stdout: "inherit",
+        stderr: "inherit",
+      });
+      void proc.exited.then((code) => this.statusCb(code === 0 ? "offline" : "error")).catch(() => this.statusCb("error")).catch(() => {});
+      return { pid: proc.pid, process: proc, meta: { monitor: hydratedConfig.monitor, env: args.env } };
+    } catch (error) { this.turnWatchResume = priorTurnWatchResume; throw error; }
+  }
+
+  async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome> {
+    const tmuxSession = process.meta?.tmuxSession as string | undefined;
+    const tmuxSocket = process.meta?.tmuxSocket as string | undefined;
+    if (tmuxSession) {
+      return this.shutdownTmux(process, tmuxSession, opts, tmuxSocket);
+    }
+    return terminateSingleProcess(process, opts);
+  }
+
+  async compact(process: ManagedProcess, opts?: { instructions?: string; signal?: AbortSignal; onSubmitted?: () => void }): 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 for compact");
+    await submitClaudeContextCommand(session, "/compact", socket, opts?.signal, opts?.onSubmitted);
+    return { method: "tmux-inject", command: "/compact" };
+  }
+
+  setEffort(process: ManagedProcess, effort: string): ReturnType<typeof switchClaudeEffort> { return switchClaudeEffort(process, effort); }
+
+  async clearContext(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 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.
+    // #2261 — VISIBLE screen only. The old `-S -80` capture snapshotted 80 lines of tmux
+    // scrollback too, and `/clear` repaints only the visible screen (it never emits the `ESC[3J`
+    // that would drop history), so the anchor picked out of scrollback was still there after the
+    // clear committed and the barrier below could never confirm it (the #2261 false negative).
+    let preClearPane = "";
+    let preClearCaptured = false;
+    try { preClearPane = await CLAUDE_CLEAR_COMMIT_CAPTURE(session, socket); preClearCaptured = true; } catch {}
+    // #2261 — the PRIMARY, machine-readable clear-commit signal: Claude mints a new session
+    // (new sessionId, new transcript file) the moment `/clear` commits. Snapshot the current one
+    // first, pid-pinned, so the barrier can watch for the rotation. Best-effort: an unavailable
+    // probe (pre-2.1.119, unresolvable config home) just leaves the barrier on its pane heuristic.
+    const readSession = await bindClaudeClearSessionReader(process, session, socket);
+    const preClearSession = readSession ? await readSession() : null;
+    await submitClaudeContextCommand(session, "/clear", socket);
+    // #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, { preClearSession, readSession, preClearCaptured });
+    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. #1621: mark the probe's
+    // pre-cancel busy verdict non-authoritative so the runner's post-interrupt reconcile can see
+    // the idle pane when the cancel writes no probe transition (a `shell` rewrite is idle, #2202).
+    this.paneInterruptAt = Date.now();
+    const result = spawnSyncBounded(tmuxCommand(socket, "send-keys", "-t", session, "Escape"), {
+      stdin: "ignore", stdout: "ignore", stderr: "pipe",
+    });
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.toString().trim();
+      throw new Error(`tmux interrupt failed: ${stderr || (result.signalCode ? `signal ${result.signalCode}` : `exit code ${result.exitCode}`)}`);
+    }
+    return { method: "tmux-escape" };
+  }
+
+  async probeActivity(process: ManagedProcess): Promise<"busy" | "idle" | "unknown"> {
+    const session = process.meta?.tmuxSession as string | undefined;
+    const socket = process.meta?.tmuxSocket as string | undefined;
+    // #1838 row 14 — the busy reconciler drives this every 4s while busy; its has-session
+    // + probe read + pane fallback now run off the event loop. A non-`present` presence
+    // (absent OR an unreadable wedged read) yields "unknown", the safe hold value — the
+    // reconciler treats unknown as non-idle and never clears a live turn on it (#1838 HIGH-2).
+    if (!session || (await tmuxSessionPresence(session, socket)) !== "present") return "unknown";
+    // #1980 U2 — the busy BACKSTOP consumer: when the intrinsic probe is unavailable, a bare
+    // input-ready pane is NOT proof the turn ended (a long foreground tool renders the same box),
+    // so it must read as `unknown` (hold), never `idle` (force-cancel). paneFallbackIsIdle:false
+    // opts this path out of the legacy pane-scrape idle the turn-watch below still relies on.
+    return this.activityFromProbeOrPane(process, session, socket, { paneFallbackIsIdle: false });
+  }
+
+  // #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.
+  // #1838 review MED — this is a SYNCHRONOUS adapter-interface method the runner core calls
+  // inline on every provider-turn `busy` edge, so it must never spawn: the old
+  // resolveClaudePid() shelled out to `tmux display-message` (up to a 10s block on a wedged
+  // socket) on that hot edge. It now returns the direct OS pid when there is one, else the pane
+  // pid resolved OFF the loop at spawn (this.tmuxPanePid). undefined until that async resolve
+  // lands or when it can't be resolved — a graceful degrade: the runner falls back to its other
+  // liveness signals exactly as it does today when the pid is unavailable.
+  resolveBusyPid(process: ManagedProcess): number | undefined {
+    if (typeof process.pid === "number" && process.pid > 0) return process.pid;
+    if (!process.meta?.tmuxSession) return undefined;
+    return this.tmuxPanePid;
+  }
+
+  // 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→busy — the idle-while-working gap the
+  // pane-scrape misread; idle/shell→idle; waiting→unknown, a parked turn the backstop must
+  // not force-clear). Legacy fallback: scrape the tmux pane (pre-2.1.119 / probe missing).
+  private async activityFromProbeOrPane(process: ManagedProcess, session: string, socket?: string, opts: { paneFallbackIsIdle?: boolean } = {}): Promise<ClaudeProbeActivity> {
+    // #1838 rows 14/15 — every subprocess/fs read on this path (pane-pid resolve, probe JSON
+    // read, /proc liveness read, transcript stat, and the pane-scrape fallback) runs off the
+    // event loop now. The verdict logic itself (claudeProbeVerdict / claudeActivityFromProbeAndPane)
+    // is pure and unchanged.
+    const managed = await readManagedClaudeStatusAsync(claudeProbeArgsFor(process, session, socket));
+    // #1621/#3026: a busy probe holds the turn unless relay's own interrupt postdates it; the
+    // transcript mtime (#1642) is only read then, to tell whether that cancel took.
+    const paneInterruptAt = this.paneInterruptAt;
+    const lastActivityAt = paneInterruptAt === undefined ? undefined : await claudeTranscriptMtimeMsAsync(managed?.reading, managed?.configHome);
+    const { activity: probe, busyStale } = claudeProbeVerdict(managed?.reading, { paneInterruptAt, lastActivityAt });
+    if (probe === "busy" && !busyStale) return "busy";
+    let pane: string | undefined;
+    try { pane = await captureTmuxPaneAsync(session, socket); } catch { return probe ?? "unknown"; }
+    return claudeActivityFromProbeAndPane(probe, pane, { probeBusyStale: busyStale, paneFallbackIsIdle: opts.paneFallbackIsIdle ?? true });
+  }
+
+  // #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;
+    // #1838 row 14 — the reconciler's independent pane-busy corroboration read, off the loop.
+    // A wedged-but-live server (presence "unreadable") reports "unreadable" — which the
+    // reconciler already treats as no-evidence and HOLDS on — rather than the false "no-session"
+    // a boolean has-session would have produced (#1838 HIGH-2).
+    if (!session) return "no-session";
+    const presence = await tmuxSessionPresence(session, socket);
+    if (presence === "absent") return "no-session";
+    if (presence === "unreadable") return "unreadable";
+    try {
+      return claudePaneIsBusy(await captureTmuxPaneAsync(session, socket)) ? "busy" : "not-busy";
+    } catch {
+      return "unreadable";
+    }
+  }
+
+  async deliver(process: ManagedProcess, messages: Message[], ctx?: ProviderDeliverContext): Promise<DeliverResult> {
+    const monitor = process.meta?.monitor as { deliver?(messages: Message[]): Promise<number[]> } | undefined;
+    // `monitorless` is set at spawn when the profile disables the relay plugin — then no monitor
+    // will ever connect, so we must not route through it (it would throw "no Claude monitor
+    // connected" forever); we inject via tmux instead. For monitored profiles we keep the monitor
+    // path (and its retry on transient startup races) to avoid double-delivering against a late monitor.
+    if (process.meta?.monitorless === true || !monitor?.deliver) return this.deliverAsUserTurn(process, messages, ctx);
+    // #3415 — human chat goes in as a tmux user turn; without a tmux pane everything stays on Monitor.
+    const userTurn = process.meta?.tmuxSession ? (batch: Message[]) => this.deliverAsUserTurn(process, batch, ctx) : undefined;
+    return deliverClaudeByLane(messages, { userTurn, narrowTurnOpener: ctx?.narrowTurnOpener, monitor: (batch, reportsOffer) => this.deliverViaMonitor(process, monitor.deliver!.bind(monitor), batch, reportsOffer ? ctx : { ...ctx, inputObserver: undefined }) });
+  }
+
+  private async deliverViaMonitor(process: ManagedProcess, deliver: (messages: Message[]) => Promise<number[]>, messages: Message[], ctx?: ProviderDeliverContext): Promise<DeliverResult> {
+    // #1588 F2 edge 2 — for self-resume continuation deliveries, wait for the TUI to be input-ready
+    // first so the continuation never lands into a not-yet-settled post-clear context. The coupled
+    // clearContext clear-aware barrier is the authoritative clear-commit gate; this belt-and-
+    // suspenders settle also protects the SEPARATE relay-backstop inject. Best-effort: a settle
+    // timeout must not fail the delivery — the backstop path already IS the recovery.
+    const session = process.meta?.tmuxSession as string | undefined;
+    const socket = process.meta?.tmuxSocket as string | undefined;
+    // #1838 review — only skip the settle when the session is positively `absent`.
+    if (session && messagesAreSelfResumeContinuation(messages) && (await tmuxSessionPresence(session, socket)) !== "absent") {
+      await waitForClaudeInputReady(session, CLAUDE_TMUX_READY_TIMEOUT_MS, socket).catch(() => {});
+    }
+    // Monitor events are external input, with no correlated user-entry confirmation.
+    ctx?.inputObserver?.offered(Date.now(), false);
+    const acknowledgedIds = await deliver(messages);
+    return { acknowledgedIds };
+  }
+
+  // Type the batch into the interactive tmux session as a real user turn — the transport
+  // deliverInitialPrompt uses. Keeps the agent on interactive Claude (the user's Max quota), never
+  // `claude -p`/API; carries human chat (#3415) and every message of a monitorless profile.
+  private async deliverAsUserTurn(process: ManagedProcess, messages: Message[], ctx?: ProviderDeliverContext): Promise<DeliverResult> {
+    const monitorless = process.meta?.monitorless === true;
+    const { session, socket } = await this.paneReadyForInput(process);
+    // Monitorless = isolated profile with no relay plugin/CLI surface: strip relay interaction
+    // scaffolding (reply reminder, claim-task instruction) — the agent has no way to /reply or /claim.
+    const text = claudeProviderMessageText(messages, { relaySurface: !monitorless }), imagePaths = providerAttachmentLocalPaths(messages);
+    ctx?.recordSubmittedPrompt?.(text, imagePaths);
+    // #1838 Wave 2a — any tmux failure throws and deliver() propagates it unclassified; a tmux
+    // exit 0 is not proof of submission (#1844), which the #2664 submit confirmation settles.
+    await this.submitUserPromptToTmux(process, session, text, socket, imagePaths, ctx?.inputObserver);
+    // Monitorless = no Stop/UserPromptSubmit hooks, so the runner gets no turn
+    // lifecycle and never marks the claimed task done (the way Codex's app-server
+    // status does) — the task lingers until the runtime budget cancels it. Scrape
+    // the tmux pane for the busy→idle transition to synthesize a provider-turn
+    // signal so isolated automation agents reach task "done" like Codex.
+    if (monitorless) await this.beginMonitorlessTurnWatch(process, session, socket);
+    return { acknowledgedIds: messages.map((message) => message.id) };
+  }
+
+  async startLaunchSeededTurn(process: ManagedProcess): Promise<void> {
+    if (process.meta?.monitorless !== true) return;
+    const session = process.meta?.tmuxSession as string | undefined;
+    if (!session) return;
+    await this.beginMonitorlessTurnWatch(process, session, process.meta?.tmuxSocket as string | undefined);
+  }
+
+  private async beginMonitorlessTurnWatch(process: ManagedProcess, sessionName: string, socketName?: string, emitBusy = true): Promise<void> {
+    if (this.statusWatchersStopped) return;
+    this.stopTurnWatch();
+    this.turnWatchResume = { process, sessionName, ...(socketName ? { socketName } : {}) };
+    // #1838 review HIGH-1 — the generation this watch owns. stopTurnWatch() just bumped it; a
+    // later stop/replace bumps it again, so every await below re-checks `gen === this.turnWatchGen`
+    // before touching shared state or emitting a status. A shutdown DURING the async setup, or an
+    // in-flight predecessor tick finishing after a successor is armed, is thereby fenced out.
+    const gen = this.turnWatchGen;
+    // #769 P2-C: feed the resolved claude pid into the provider-turn liveness pids
+    // so #650's pid-liveness reconcile arms for headless/monitorless turns too (the
+    // 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.
+    // #1838 row 15 — the per-turn-start pane-pid resolve + probe read run off the loop.
+    const livenessPid = await this.monitorlessTurnWatch.resolvePanePid(process.pid, sessionName, socketName);
+    // A numeric pid is not a process identity: an unrelated Claude can reuse it after this pane
+    // exits. Pin /proc's start-time incarnation before accepting the asynchronous session probe.
+    const paneIncarnation = livenessPid === undefined ? undefined : await this.monitorlessTurnWatch.processIncarnation(livenessPid);
+    if (gen !== this.turnWatchGen) return;
+    // #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).
+    // Pin this to the pane pid resolved above. Re-resolving the pane on every retry lets a
+    // replacement process borrow this turn's watch; the session probe itself may legitimately
+    // appear only after Claude has passed the launcher gate, so its *contents* must be retried.
+    const transcriptProbeArgs = {
+      pid: livenessPid,
+      tmuxSession: sessionName,
+      tmuxSocket: socketName,
+      configHomeEnv: (process.meta?.env as Record<string, string | undefined> | undefined)?.CLAUDE_CONFIG_DIR,
+    };
+    let transcriptPath = livenessPid === undefined || paneIncarnation === undefined ? undefined : await this.monitorlessTurnWatch.resolveTranscriptPath(transcriptProbeArgs);
+    if (gen !== this.turnWatchGen) return;
+    // `has-session` only says a session NAME exists. Before publishing a path, resolve its pane
+    // again and require the same pid plus incarnation: a replacement pane can retain the name
+    // while the old process/probe is still alive, which must never cross-attribute a transcript.
+    const ownsPinnedPane = async (): Promise<boolean> => {
+      if (livenessPid === undefined || paneIncarnation === undefined) return false;
+      if ((await this.monitorlessTurnWatch.resolvePanePid(undefined, sessionName, socketName)) !== livenessPid) return false;
+      return (await this.monitorlessTurnWatch.processIncarnation(livenessPid)) === paneIncarnation;
+    };
+    if (transcriptPath && !(await ownsPinnedPane())) {
+      this.stopTurnWatch();
+      return;
+    }
+    // A stop/replace during the two awaits above invalidates this setup: do NOT emit `busy` and
+    // do NOT arm the interval (the successor owns the watch now).
+    if (gen !== this.turnWatchGen) return;
+    // A normal arm follows a prompt submission, so synthesize provider-turn busy to let the runner
+    // track completion. A failed-restart resume is only rebuilding observation for an existing
+    // incarnation: its prior claim/status remains authoritative, so do not invent a new busy edge.
+    if (emitBusy) 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;
+    // #1838 row 15 (shares row 14's fix) — the tick's activity read is now off-loop, so the
+    // body is an async IIFE. `inFlight` keeps a slow (now off-loop) probe from stacking a
+    // second concurrent tick on the 1.5s timer.
+    let inFlight = false;
+    this.turnWatcher = setInterval(() => {
+      if (gen !== this.turnWatchGen || inFlight) return;
+      inFlight = true;
+      void fireAndForget("[runner] claude turn watch tick", (async () => {
+        ticks += 1;
+        const presence = await this.monitorlessTurnWatch.sessionPresence(sessionName, socketName);
+        if (gen !== this.turnWatchGen) return; // superseded during the await — do not touch state
+        // #1838 HIGH-2: only a positive `absent` (or the safety cap) ends the watch. An
+        // `unreadable` read (wedged-but-live server) HOLDS — never abandon a live turn on it.
+        if (presence === "unreadable") return;
+        if (presence === "absent" || ticks > CLAUDE_TURN_MAX_TICKS) {
+          // Session ended (the tmux watcher emits offline) or we hit the safety cap;
+          // stop without emitting idle and let budget/server reconcile resolve it.
+          this.stopTurnWatch();
+          return;
+        }
+        // The launch-seeded prompt is already running when spawnHeadless releases its launcher
+        // gate, but Claude creates sessions/<pane-pid>.json asynchronously. Do not permanently
+        // close over that startup miss: retry the same pinned pid until its transcript identity
+        // exists, and publish the late path on the existing busy turn so runner-core can retain it
+        // for terminal token-usage capture even if this is the only/last turn.
+        if (!transcriptPath && livenessPid !== undefined && paneIncarnation !== undefined) {
+          if (!(await ownsPinnedPane())) {
+            this.stopTurnWatch();
+            return;
+          }
+          const resolvedTranscriptPath = await this.monitorlessTurnWatch.resolveTranscriptPath(transcriptProbeArgs);
+          if (gen !== this.turnWatchGen) return;
+          // The probe read itself can race a pane exit/replacement. Re-check both the pinned
+          // incarnation and tmux session continuity before publishing a path to the runner.
+          const currentPresence = await this.monitorlessTurnWatch.sessionPresence(sessionName, socketName);
+          if (gen !== this.turnWatchGen) return;
+          if (currentPresence !== "present" || !(await ownsPinnedPane())) {
+            this.stopTurnWatch();
+            return;
+          }
+          if (currentPresence === "present" && resolvedTranscriptPath) {
+            transcriptPath = resolvedTranscriptPath;
+            this.statusCb({ status: "busy", reason: "provider-turn", id: CLAUDE_TURN_WATCH_ID, ...(livenessPid ? { pids: [livenessPid] } : {}), transcriptPath });
+          }
+        }
+        // #768: drive turn boundaries off the intrinsic probe (busy→busy, idle/shell→idle),
+        // falling back to the pane-scrape when the probe is unavailable. A foreground Bash
+        // gate reads busy; `shell` is a finished turn with a background task alive (#2202).
+        const activity = await this.monitorlessTurnWatch.activity(process, sessionName, socketName);
+        if (gen !== this.turnWatchGen) return; // superseded during the probe await
+        if (activity === "busy") { sawBusy = true; idleStreak = 0; return; }
+        idleStreak = activity === "idle" ? idleStreak + 1 : 0;
+        const confirmedIdle = idleStreak >= CLAUDE_TURN_IDLE_CONFIRM_TICKS;
+        // Require either an observed busy spinner or a grace window, so we never
+        // declare idle in the brief gap before Claude starts rendering the turn.
+        const turnObserved = sawBusy || ticks >= CLAUDE_TURN_QUICK_GRACE_TICKS;
+        if (confirmedIdle && turnObserved) {
+          this.stopTurnWatch();
+          // 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 } : {}) });
+        }
+      })().finally(() => { inFlight = false; }));
+    }, this.monitorlessTurnWatch.pollMs);
+  }
+
+  private stopTurnWatch(): void {
+    // #1838 review HIGH-1 — bump the generation FIRST so any predecessor setup still awaiting,
+    // or an in-flight tick, sees itself invalidated after its next await and neither emits a
+    // status nor tears down a successor. Unconditional (not gated on this.turnWatcher) so a
+    // stop DURING setup (before the interval exists) still invalidates that setup.
+    this.turnWatchGen++;
+    this.turnWatchResume = undefined;
+    if (this.turnWatcher) {
+      clearInterval(this.turnWatcher);
+      this.turnWatcher = undefined;
+    }
+  }
+
+  async deliverInitialPrompt(process: ManagedProcess, prompt: string, options?: PromptOfferOptions): Promise<void> {
+    const { session, socket } = await this.paneReadyForInput(process, options?.readyTimeoutMs);
+    await this.submitUserPromptToTmux(process, session, prompt, socket, options?.imagePaths, options?.inputObserver);
+  }
+
+  // #1838 review — off-loop presence: only a positive `absent` proves there is no session; on
+  // `unreadable` the deadline-bounded waitForClaudeInputReady sorts it out rather than failing spuriously.
+  private async paneReadyForInput(process: ManagedProcess, readyTimeoutMs = CLAUDE_TMUX_READY_TIMEOUT_MS): Promise<{ session: string; socket?: string }> {
+    const session = process.meta?.tmuxSession as string | undefined;
+    const socket = process.meta?.tmuxSocket as string | undefined;
+    if (!session || (await tmuxSessionPresence(session, socket)) === "absent") throw new Error("Claude has no tmux session to type a user turn into");
+    await waitForClaudeInputReady(session, readyTimeoutMs, socket);
+    return { session, socket };
+  }
+
+  async confirmSubmitRecovery(process: ManagedProcess, turnStarted: boolean): Promise<boolean> {
+    const session = process.meta?.tmuxSession as string | undefined;
+    if (!session) return false;
+    return confirmClaudeSubmitRecovery(session, process.meta?.tmuxSocket as string | undefined, turnStarted);
+  }
+
+  releaseSubmitHold(process: ManagedProcess): void { if (typeof process.meta?.tmuxSession === "string") releaseClaudeSubmitFence(process.meta.tmuxSession, process.meta.tmuxSocket as string | undefined); }
+
+  private async submitUserPromptToTmux(process: ManagedProcess, session: string, text: string, socket?: string, imagePaths: string[] = [], inputObserver?: ProviderDeliverContext["inputObserver"]): Promise<void> {
+    const resolveTranscriptPath = () => resolveManagedClaudeTranscriptPathAsync(claudeProbeArgsFor(process, session, socket));
+    // #2664 — the UserPromptSubmit hook confirms the submit; monitorless launches have no hooks.
+    await submitTextToTmux(session, text, socket, { confirmSubmit: true, transcriptPath: await resolveTranscriptPath().catch(() => undefined), resolveTranscriptPath, imagePaths, inputObserver, ...(process.meta?.monitorless === true ? {} : { promptHooks: this.sessionCapture.promptHooks }) });
+  }
+
+  buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
+    // Create + bootstrap + auth-link the isolated config home (host base has none) so the
+    // assembler's materialize step has somewhere to write the provisioned skills/plugins.
+    // #2254 — this also seeds folder trust into whichever config file THIS launch reads,
+    // including the shared host config on a host-base/profile-less spawn.
+    prepareClaudeProfileHome(config, this.provider);
+    // #557 — ONE assembler owns the provisioning/vanilla/instruction launch surface
+    // (--setting-sources, --plugin-dir, --mcp-config, status-line, --append-system-prompt);
+    // profile-projection describes the SAME assembled result, so report == launch. The
+    // adapter only adds the bits the assembler does not own: claude-rig command resolution,
+    // headless permission flags, --model, and the positional prompt. materializeLaunchAssembly
+    // writes the provisioned skills/plugins the assembled args point at.
+    const assembled = assembleLaunch(this.provider, config, providerConfig);
+    materializeLaunchAssembly(this.provider, config);
+    const defaultArgs = assembled.hostDefaultArgs;
+    const isClaudeRig = /claude-rig/.test(providerConfig.command);
+    // Profiled launches run their own CLAUDE_CONFIG_DIR (#3387) and must never route through
+    // claude-rig — claude-rig resolves host rig config and would redirect the assembled home.
+    // Only a profile-less (user-wrapped) session may use claude-rig.
+    const usesClaudeRig = isClaudeRig && !assembled.configHome;
+    const bypassRigDefaults = config.headless && usesClaudeRig && config.approvalMode !== "open";
+    const rigPrefix = usesClaudeRig && !bypassRigDefaults && config.rig ? ["launch", config.rig] : [];
+    const command = !usesClaudeRig || bypassRigDefaults || (!config.rig && !findClaudeRigRC(config.cwd))
+      ? "claude"
+      : providerConfig.command;
+    const providerArgs = config.headless
+      ? claudeLaunchArgs(defaultArgs, config.providerArgs, config.approvalMode)
+      : [...defaultArgs, ...config.providerArgs];
+    // #1096 — when the assembler merged the caller's own `--settings` into relay's (so the
+    // baseline hooks/projectSettings/statusLine survive), drop the caller's now-redundant
+    // `--settings` here so exactly ONE reaches the launch (relay's merged copy in assembled.args).
+    // #2453 — the coding/review profiles' --disallowedTools trim unions in at this single
+    // claude-family launch seam (helpers + per-profile config in ./claude-tool-policy).
+    const args = claudeProfileDisallowedToolsArgs([
+      ...rigPrefix,
+      ...assembled.args,
+      ...(assembled.callerSettingsConsumed ? stripSettingsArgs(providerArgs) : providerArgs),
+    ], config);
+    if (config.model) args.push("--model", config.model);
+    const effortLaunch = claudeEffortLaunch(config.effort, config.env); args.push(...effortLaunch.args);
+    // #352: seed the first turn at launch for ALL sessions; a transient headless oversized brief
+    // runs in Claude print mode and enters as stdin, not a racy tmux paste or system prompt.
+    const oneShot = config.prompt ? seedClaudeInitialPrompt(args, sanitizeLaunchText(String(config.prompt), "initial prompt"), { headless: config.headless, lifecycle: config.lifecycle, scratchDir: relayEnv(config.env, "AGENT_RELAY_SCRATCH_DIR") }) : undefined;
+    const env: Record<string, string> = writeChildEnv({}, {
+      ...config.env,
+      // #557 — the assembler owns the isolated config-home env (CLAUDE_CONFIG_DIR).
+      ...assembled.env,
+      // Plain `claude` (isolated profiles) runs its own CLAUDE_CONFIG_DIR and never
+      // routes through claude-rig, so it never inherits the host's long-lived
+      // CLAUDE_CODE_OAUTH_TOKEN. Without it, claude falls back to the (often stale)
+      // file-based .credentials.json and bails to /login (401). claude-rig launches
+      // inject their own token, so only thread it for the plain-claude path, and
+      // never override an explicit per-launch value.
+      ...(command === "claude" && process.env.CLAUDE_CODE_OAUTH_TOKEN && !config.env?.CLAUDE_CODE_OAUTH_TOKEN
+        ? { CLAUDE_CODE_OAUTH_TOKEN: process.env.CLAUDE_CODE_OAUTH_TOKEN }
+        : {}),
+      // The Claude Code harness reaps long-running background shells under bg-shell
+      // memory pressure, killing detached test/land-gate runs mid-flight (upstream
+      // anthropics/claude-code#92228). Default the pressure-reap OFF for every
+      // claude-family launch; an explicit value inherited through config.env (which
+      // carries a copy of the runner process env) wins, so an operator can still unset.
+      CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP:
+        config.env?.CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP ?? process.env.CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP ?? "1",
+      // Same treatment (T3182 scope expansion): CLAUDE_CODE_SEND_FEEDBACK=0 is the
+      // documented removal of the SendFeedback tool — autonomous agents keep misfiling
+      // humwick bugs to Anthropic with no human to approve the draft. The managed
+      // settings.json additionally carries a permissions.deny belt (launch-assembly).
+      CLAUDE_CODE_SEND_FEEDBACK: config.env?.CLAUDE_CODE_SEND_FEEDBACK ?? process.env.CLAUDE_CODE_SEND_FEEDBACK ?? "0",
+      // #1546 — a mid-fleet CC auto-update re-rendered startup gates on every restart; managed
+      // launches keep the installed version until an operator bump.
+      DISABLE_AUTOUPDATER: config.env?.DISABLE_AUTOUPDATER ?? process.env.DISABLE_AUTOUPDATER ?? "1",
+      // #2615 — prompt suggestions ship conversation context to the provider to generate
+      // follow-up suggestions no Relay-agent human ever sees (pure quota burn). The bundle
+      // gate reads this env first; false outranks settings.json promptSuggestionEnabled.
+      CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION:
+        config.env?.CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION ?? process.env.CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION ?? "false",
+      // #2616 — remote recap forks the FULL cached conversation through an extra model call at
+      // turn end to produce a recap pushed to a claude.ai remote UI (`notifyMetadataChanged({
+      // recap})`); no Relay agent ever renders it. The bundle gate reads
+      // CLAUDE_CODE_ENABLE_REMOTE_RECAP first (env outranks settings/statsig): "false" pins it
+      // off regardless of the remotely-flippable tengu_harbor_moth statsig gate or an attached
+      // CCR surface; "true" still lets an operator force it on.
+      CLAUDE_CODE_ENABLE_REMOTE_RECAP:
+        config.env?.CLAUDE_CODE_ENABLE_REMOTE_RECAP ?? process.env.CLAUDE_CODE_ENABLE_REMOTE_RECAP ?? "false",
+      // #2616 — CLI away summary fires the same recap generator when a pane regains terminal
+      // focus after ≥5min blur and injects the result into the live transcript. Relay panes
+      // routinely sit unfocused far longer than that, so every firing is a model call whose
+      // output no agent reads. The bundle gate reads CLAUDE_CODE_ENABLE_AWAY_SUMMARY before the
+      // settings.awaySummaryEnabled check; any falsey string (including "") wins outright,
+      // "true" forces it on.
+      CLAUDE_CODE_ENABLE_AWAY_SUMMARY:
+        config.env?.CLAUDE_CODE_ENABLE_AWAY_SUMMARY ?? process.env.CLAUDE_CODE_ENABLE_AWAY_SUMMARY ?? "false",
+      // #1222 — a spawned session may not find the humwick CLI in the host login
+      // shell's PATH, so Relay's own bins lead (layout-agnostic for npm and git-checkout
+      // installs, #1305) while the inherited PATH keeps its own order behind them: leading
+      // Homebrew's dirs (#1413) put Homebrew's node ahead of the operator's own on macOS,
+      // and Claude's shell snapshot keeps this PATH, so no rc file restores it (#2705).
+      // #3171 — the profile's harness trim (Artifact, Workflow, bundled skills, Explore/Plan) outranks inherited env.
+      ...claudeHarnessTrim(config).env,
+      ...claudeSubagentEnv(config),
+      PATH: launchPath(config.env?.PATH ?? process.env.PATH),
+      AGENT_RELAY_PROVIDER: this.provider,
+      ...effortLaunch.env,
+      ...claudeProjectShellEnv(config.env),
+    });
+    // #2513 review HIGH-2 — credential isolation. config.env carries a copy of the whole
+    // runner process env, so ambient credentials of the PRIMARY subscription reach every
+    // launch — and each of these env vars OUTRANKS the file credential, so a
+    // second-subscription claude-family provider would silently authenticate as the
+    // primary subscription no matter which home it launches from. For any claude-family
+    // id other than "claude", the ambient credential env must therefore NOT survive: each
+    // key is removed from env AND explicitly unset at the tmux launcher (the pane inherits
+    // the tmux server's environment, so absence from env alone is not enough). The
+    // provider's own values can still ride its per-provider config env (threaded
+    // explicitly here, since runner-core only merges providerConfig.env into host-globals
+    // profiles). Primary subscription tokens survive; a host paid-key file does not. The key set is the SINGLE shared
+    // constant from @humwick/providers (#2513 round-3 MF3) — the orchestrator's auth
+    // preflight scrubs the same list, and a local re-listing is blocked by the
+    // duplication ratchet.
+    const envUnset: string[] = [...effortLaunch.unset, ...(claudeSubagentPolicy(config) ? ["CLAUDE_CODE_AUTO_COMPACT_WINDOW", "DISABLE_AUTO_COMPACT"] : [])];
+    scopeClaudeCredentialEnv(this.provider, providerConfig.env, writeChildEnv(env, {}, envUnset), envUnset);
+    configureClaudeSubagentLaunch(config, { args, env, cwd: config.cwd });
+    return sanitizeLaunchBoundary({
+      command,
+      args,
+      cwd: config.cwd,
+      env,
+      ...(envUnset.length ? { envUnset } : {}),
+      ...(oneShot ? oneShot : {}),
+    });
+  }
+
+  buildTmuxArgs(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): { sessionName: string; socketName: string; args: string[]; launcherScript: string; gateFifo?: string } {
+    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"];
+
+    const envKeys = tmuxEnvKeys(spawnArgs.env, config.providerConfig.env, this.provider);
+    const env: Record<string, string> = {};
+    for (const key of envKeys) if (relayEnv(spawnArgs.env, key) !== undefined) writeChildEnv(env, { [key]: relayEnv(spawnArgs.env, key)! });
+
+    // Only gate the launch behind pipe-pane attachment when there's a log file to
+    // protect (#1317) — no point serializing dev/interactive spawns that never
+    // read AGENT_RELAY_LOG_FILE.
+    const gateFifo = relayEnv(spawnArgs.env, "AGENT_RELAY_LOG_FILE") ? launcherGatePathForSession(sessionName) : undefined;
+
+    // tmux new-session has a hard command-length limit that includes every argv item,
+    // including `-e KEY=value`. The script holds the command; its private FIFO
+    // carries env values without writing credentials to disk or argv.
+    const launcherScript = writeLauncherScript(sessionName, env, shellCmd, gateFifo, spawnArgs.stdinFile, spawnArgs.exitCodeFile, spawnArgs.envUnset);
+    tmuxArgs.push("-c", spawnArgs.cwd, `bash ${shellQuote(launcherScript)}`);
+    return { sessionName, socketName, args: tmuxArgs, launcherScript, gateFifo };
+  }
+
+  private async spawnHeadless(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): Promise<ManagedProcess> {
+    if (spawnArgs.stdinFile && spawnArgs.exitCodeFile && spawnArgs.stdinContents !== undefined) await stageOneShotPrompt(spawnArgs.stdinFile, spawnArgs.exitCodeFile, spawnArgs.stdinContents);
+    const { sessionName, socketName, args: tmuxArgs, launcherScript, gateFifo } = this.buildTmuxArgs(config, spawnArgs);
+    const providerEpoch = ++this.providerEpoch;
+    this.modelUnavailableObservationState = initialClaudeModelUnavailableObservationState();
+    this.connectionRetryActive = false;
+    this.promptGatePaneState = initialClaudePromptGatePaneState(); this.tmuxPanePid = undefined;
+    this.startupReadyObserved = false;
+    this.startupBypassDialogActive = false;
+    this.startupOpenApproval = config.approvalMode === "open";
+
+    // Create the gate FIFO *before* the session exists — the launcher script blocks
+    // on reading it, so no output can be produced until we release it below (#1317).
+    if (gateFifo) createLauncherGate(gateFifo);
+
+    await createTmuxSessionWithEnv(sessionName, socketName, tmuxArgs, launcherScript, spawnArgs.env, config.providerConfig.env, gateFifo, this.provider);
+
+    this.watchTmuxSession(sessionName, socketName, spawnArgs.exitCodeFile);
+    // #1838 review MED — resolve the pane pid OFF the loop now that the session exists and cache
+    // it, so the synchronous resolveBusyPid() never has to shell out on a hot busy edge. Fenced
+    // on providerEpoch so a resolve that lands after a restart can't stamp a stale pid.
+    void resolveClaudePanePidAsync(undefined, sessionName, socketName)
+      .then((pid) => { if (this.providerEpoch === providerEpoch) this.tmuxPanePid = pid; })
+      .catch(() => {});
+    const logFile = relayEnv(spawnArgs.env, "AGENT_RELAY_LOG_FILE");
+    if (logFile) {
+      spawnSyncBounded(tmuxCommand(socketName, "pipe-pane", "-o", "-t", sessionName, `cat >> ${shellQuote(logFile)}`), {
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+    }
+
+    // Release the gate now that pipe-pane is attached (or there's nothing to
+    // protect) — the pane's launcher script was blocked on this since it started.
+    if (gateFifo) await releaseLauncherGate(gateFifo);
+
+    return {
+      pid: undefined, process: undefined, meta: {
+        env: spawnArgs.env,
+        monitor: config.monitor,
+        // When the profile disables the relay plugin, the bundled monitor never
+        // loads, so no monitor will ever connect — deliver() must use tmux injection.
+        monitorless: !profileAllowsRelayFeature(config, "plugins"),
+        tmuxSession: sessionName,
+        tmuxSocket: socketName,
+        launcherScript,
+        ...claudeEffortSwitchMeta(this.provider, config, Boolean(spawnArgs.exitCodeFile)),
+        ...(spawnArgs.exitCodeFile ? { oneShotExitCodeFile: spawnArgs.exitCodeFile } : {}),
+        providerEpoch,
+      },
+    };
+  }
+
+  private watchTmuxSession(sessionName: string, socketName?: string, oneShotExitCodeFile?: string): void {
+    if (this.tmuxWatcher) clearInterval(this.tmuxWatcher);
+    // #1838 row 12 — the highest-frequency blocking site in the runner (every 2s for the
+    // agent's whole lifetime). Its two tmux subprocesses (has-session + capture-pane) now run
+    // OFF the event loop via the offload subprocess runner, so the tick is async. Guard against
+    // overlapping ticks: if a capture is still in flight when the timer fires again — a wedged
+    // socket can hold one up to its 10s deadline — skip rather than stack a second concurrent
+    // probe on the same pane. `this.tmuxWatcher !== watcher` still fences a predecessor tick
+    // whose session was replaced by a respawn.
+    let tickInFlight = false;
+    const watcher = setInterval(() => {
+      if (this.tmuxWatcher !== watcher || tickInFlight) return;
+      tickInFlight = true;
+      void fireAndForget("[runner] claude tmux watch tick", (async () => {
+        const presence = await tmuxSessionPresence(sessionName, socketName);
+        // #1838 HIGH-1: re-fence after every await — a respawn/shutdown that replaced this
+        // watcher mid-await must not let a predecessor tick emit or tear down its successor.
+        if (this.tmuxWatcher !== watcher) return;
+        // #1838 HIGH-2: only a positive `absent` is evidence of death. An `unreadable` read
+        // (wedged-but-live server, deadline SIGKILL) HOLDS this tick — never emit `offline`.
+        if (presence === "unreadable") return;
+        if (presence === "absent") {
+          // The whole tick (including the delayed second confirmation) is serialized by the
+          // in-flight guard, so an off-loop confirm can no longer race a stacked tick. The
+          // confirm itself only returns true when BOTH reads are `absent` (#1838 HIGH-2).
+          const gone = await confirmTmuxSessionGone(sessionName, socketName).catch(() => false);
+          if (this.tmuxWatcher !== watcher || !gone) return;
+          const exitStatus = await claudeOneShotExitStatus(oneShotExitCodeFile);
+          if (this.tmuxWatcher !== watcher) return;
+          clearInterval(watcher); this.tmuxWatcher = undefined; this.publishConfirmedTmuxExit(exitStatus);
+          return;
+        }
+        let pane = "";
+        try {
+          pane = await captureTmuxPaneAsync(sessionName, socketName);
+        } catch {
+          return;
+        }
+        // #1838 HIGH-1: fence again after the capture await, before any observation/status emit.
+        if (this.tmuxWatcher !== watcher) return;
+        // A reused tmux pane can leave an old ready footer in scrollback. Until the
+        // current launch is visibly ready, derive both readiness and modal state
+        // from the visible grid. After that, avoid an extra capture every tick.
+        let livePane = pane;
+        if (this.startupOpenApproval && !this.startupReadyObserved) {
+          try { livePane = await captureTmuxVisiblePaneAsync(sessionName, socketName); } catch { return; }
+          if (this.tmuxWatcher !== watcher) return;
+        }
+        const startupBypassDialog = this.startupOpenApproval && !this.startupReadyObserved && !claudePaneLooksReady(livePane) && claudeBypassPermissionDialog(livePane);
+        if (claudePaneLooksReady(livePane)) this.startupReadyObserved = true;
+        if (this.startupBypassDialogActive && !startupBypassDialog) {
+          this.startupBypassDialogActive = false;
+          this.paneObservationCb({ eventType: "claude.pane_gate_cleared", source: "pane", detectorId: "bypass-permissions-mode", observedAt: Date.now(), sessionName, displayGate: { phase: "clear" } });
+        }
+        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.paneObservationCb(connRetry);
+          }
+        } else if (this.connectionRetryActive) {
+          this.connectionRetryActive = false;
+          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(livePane, this.promptGatePaneState, {
+          sessionName,
+          busy: claudePaneIsBusy(pane),
+          sourceId: this.paneSourceId,
+        });
+        this.promptGatePaneState = promptGate.state;
+        if (promptGate.observation) {
+          if (startupBypassDialog && promptGate.observation.detectorId === "bypass-permissions-mode") {
+            this.startupBypassDialogActive = true;
+            this.paneObservationCb({ ...promptGate.observation, displayGate: claudeBypassDialogDisplayGate(sessionName, promptGate.observation.observedAt) });
+          } else this.paneObservationCb(promptGate.observation);
+        }
+        if (promptGate.status) this.statusCb(promptGate.status);
+      })().finally(() => { tickInFlight = false; }));
+    }, 2000);
+    this.tmuxWatcher = watcher;
+  }
+
+  private publishConfirmedTmuxExit(status: "offline" | "error"): void {
+    // The pane and turn pollers are independent. Invalidate the turn generation BEFORE publishing
+    // the terminal edge so an in-flight incarnation/activity read cannot land a later idle and
+    // resurrect the row with its shutting-down lifecycle pill still latched (#2505).
+    this.stopStatusWatchers();
+    this.statusCb(status);
+  }
+
+  // The tmux presence and monitorless turn pollers can both emit statuses. Terminal publication
+  // must synchronously fence both before any await opens an offline→idle resurrection window.
+  stopStatusWatchers(): void {
+    const turnWatchResume = this.turnWatchResume;
+    this.statusWatchersStopped = true;
+    this.stopTurnWatch();
+    this.turnWatchResume = turnWatchResume;
+    if (this.tmuxWatcher) clearInterval(this.tmuxWatcher);
+    this.tmuxWatcher = undefined;
+  }
+
+  async resumeStatusWatchers(process: ManagedProcess): Promise<void> {
+    const sessionName = process.meta?.tmuxSession as string | undefined;
+    const socketName = process.meta?.tmuxSocket as string | undefined;
+    const turnWatchResume = this.turnWatchResume?.process === process ? this.turnWatchResume : undefined;
+    this.statusWatchersStopped = false;
+    if (sessionName) this.watchTmuxSession(sessionName, socketName, process.meta?.oneShotExitCodeFile as string | undefined);
+    if (turnWatchResume) await this.beginMonitorlessTurnWatch(process, turnWatchResume.sessionName, turnWatchResume.socketName, false);
+  }
+
+  // #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<ShutdownOutcome> {
+    this.stopStatusWatchers();
+    return shutdownClaudeTmux(process, sessionName, opts, socketName, this.providerEpoch, deps);
+  }
+}
+
+// #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, 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, assertTmuxSocketPathFits, tmuxEnvKeys, waitForClaudeClearCommitted } 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;
+const CLAUDE_TURN_IDLE_CONFIRM_TICKS = 3;  // ~4.5s of stable idle before declaring done
+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
+
+// #557 — sessionStatusLineSettingsArgs now lives in ../launch-assembly (the single
+// launch-arg home); re-exported so existing ./claude consumers + tests keep their path.
+export { sessionStatusLineSettingsArgs };
+
+export function claudeLaunchArgs(defaultArgs: string[], providerArgs: string[], approvalMode?: string): string[] {
+  const stripToolArgs = approvalMode === "read-only";
+  return [
+    ...stripClaudePermissionArgs(defaultArgs, stripToolArgs),
+    ...stripClaudePermissionArgs(providerArgs, stripToolArgs),
+    ...claudePermissionModeArgs(approvalMode),
+  ];
+}
+
+export function claudePermissionModeArgs(approvalMode?: string): string[] {
+  if (approvalMode === "open") return ["--dangerously-skip-permissions"];
+  if (approvalMode === "read-only") return ["--permission-mode", "dontAsk", "--tools", "Read,Grep,Glob,LS,Bash"];
+  return ["--permission-mode", "default"];
+}
+
+function stripClaudePermissionArgs(args: string[], stripToolArgs = false): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg) continue;
+    if (
+      arg === "--dangerously-skip-permissions" ||
+      arg === "--allow-dangerously-skip-permissions" ||
+      arg?.startsWith("--permission-mode=")
+    ) {
+      continue;
+    }
+    if (arg === "--permission-mode") {
+      i++;
+      continue;
+    }
+    if (stripToolArgs && /^--(?:tools|allowedTools|allowed-tools|disallowedTools|disallowed-tools)(?:=|$)/.test(arg)) {
+      if (!arg.includes("=")) i++;
+      continue;
+    }
+    result.push(arg);
+  }
+  return result;
+}
+
+// Shared tmux helpers; tmuxHasSession re-exported for ./claude consumers + tests.
+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, claudeConversationAnchor, claudeClearCommitted, claudeRateLimitStatus, claudeConnectionRetryObservation, claudeModelUnavailableObservation, debounceClaudeModelUnavailableObservation, initialClaudeModelUnavailableObservationState } from "./claude-status-detectors";
+
+// Shared shell-quoting; re-exported so `./claude` consumers + tests resolve it.
+export { shellQuote };
+
+export function findClaudeRigRC(cwd: string): string | null {
+  const home = homedir();
+  let dir = resolve(cwd);
+  while (true) {
+    // Stop at $HOME without inspecting it: ~/.claude-rig is the claude-rig tool's
+    // own config home, not a per-project rc marker. Matching it would make every
+    // project under $HOME look like a claude-rig project.
+    if (dir === home) return null;
+    const rc = join(dir, ".claude-rig");
+    if (existsSync(rc)) return rc;
+    const parent = resolve(dir, "..");
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+async function terminateSingleProcess(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome> {
+  const proc = process.process;
+  if (!proc) return "killed"; // nothing to kill — vacuously terminal
+  const pid = proc.pid;
+  try {
+    proc.kill(opts.graceful ? "SIGTERM" : "SIGKILL");
+  } catch {
+    // Already gone (ESRCH) or unsignalable — re-observe rather than trust the throw. (#1746)
+    return pid !== undefined && isPidAlive(pid) ? "failed-to-kill" : "killed";
+  }
+  const timeout = new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), opts.timeoutMs));
+  const result = await Promise.race([proc.exited, timeout]);
+  if (result === "timeout") {
+    try {
+      proc.kill("SIGKILL");
+    } catch {}
+    await proc.exited.catch(() => {});
+  }
+  // Confirm death rather than assume the kill took (#1746).
+  return pid !== undefined && isPidAlive(pid) ? "failed-to-kill" : "killed";
+}