agent-relay-server 0.122.0 → 0.122.1

package/runner/src/adapters/claude.ts

@@ -0,0 +1,672 @@
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { type Message } from "agent-relay-sdk";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
+import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
+import { profileAllowsRelayFeature, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderStatusUpdate, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
+import { computeLivenessSignal, type LivenessInputs } from "../liveness";
+import type { LivenessSignal } from "agent-relay-sdk";
+import { collectClaudeSessionEvents } from "./claude-transcript";
+import type { SessionEvent } from "../session-insights";
+import { prepareClaudeProfileHome, profileUsesClaudeHostProviderGlobals } from "../profile-home";
+import { assembleLaunch, materializeLaunchAssembly, sessionStatusLineSettingsArgs } from "../launch-assembly";
+import { claudeProviderMessageText } from "./claude-delivery";
+import { claudeProbeActivity, readManagedClaudeStatus, resolveClaudePid, type ClaudeProbeActivity } from "./claude-session-probe";
+import { evaluateClaudePromptGatePane, initialClaudePromptGatePaneState, type ClaudePromptGatePaneState } from "../claude-prompt-gates";
+import { claudePaneLooksReady, claudePaneIsBusy, claudeRateLimitStatus, claudeConnectionRetryStatus, claudeModelUnavailableStatus } from "./claude-status-detectors";
+import { launcherScriptPathForSession } from "../session-scratch";
+
+export class ClaudeAdapter implements ProviderAdapter {
+  readonly provider = "claude";
+  readonly compactSupportsInstructions = true;
+  // #352: initial prompt is seeded as Claude's positional launch arg (buildSpawnArgs) — reliable,
+  // no send-keys/onboarding race; tells the runner to skip the redundant post-launch delivery.
+  readonly seedsInitialPromptAtLaunch = true;
+  private statusCb: (status: ProviderStatusUpdate) => void = () => {};
+  private tmuxWatcher?: Timer;
+  private turnWatcher?: Timer;
+  private modelUnavailableReported = false;
+  private connectionRetryActive = false;
+  private promptGatePaneState: ClaudePromptGatePaneState = initialClaudePromptGatePaneState();
+
+  onStatusChange(cb: (status: ProviderStatusUpdate) => void): void {
+    this.statusCb = 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 spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
+    const args = this.buildSpawnArgs(config, config.providerConfig as ProviderConfig);
+
+    if (config.headless) {
+      return this.spawnHeadless(config, 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"));
+    return { pid: proc.pid, process: proc, meta: { monitor: config.monitor, env: args.env } };
+  }
+
+  async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
+    const tmuxSession = process.meta?.tmuxSession as string | undefined;
+    const tmuxSocket = process.meta?.tmuxSocket as string | undefined;
+    if (tmuxSession) {
+      await this.shutdownTmux(tmuxSession, opts, tmuxSocket);
+      return;
+    }
+    await terminateSingleProcess(process, opts);
+  }
+
+  async compact(process: ManagedProcess, opts?: { instructions?: string }): 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");
+    const command = opts?.instructions ? `/compact ${opts.instructions}` : "/compact";
+    await submitTextToTmux(session, command, socket);
+    return { method: "tmux-inject", command };
+  }
+
+  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");
+    await submitTextToTmux(session, "/clear", socket);
+    return { method: "tmux-inject", command: "/clear" };
+  }
+
+  // #183/#184: parse the full Claude transcript into the shared SessionEvent stream. The
+  // runner slices per-segment, so we return the whole transcript's events each call.
+  async collectSessionEvents(_process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<SessionEvent[] | null> {
+    if (!ctx.transcriptPath) return null;
+    let jsonl: string;
+    try {
+      jsonl = await readFile(ctx.transcriptPath, "utf8");
+    } catch {
+      return null;
+    }
+    return collectClaudeSessionEvents(jsonl);
+  }
+
+  async collectSessionArchiveSegment(_process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<string | null> {
+    if (!ctx.transcriptPath) return null;
+    try {
+      return await readFile(ctx.transcriptPath, "utf8");
+    } catch {
+      return null;
+    }
+  }
+
+  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.
+    const result = Bun.spawnSync(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 || `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;
+    if (!session || !tmuxHasSession(session, socket)) return "unknown";
+    return this.activityFromProbeOrPane(process, session, socket);
+  }
+
+  // Shared probe-primary / pane-fallback activity read (#766/#768), used by both the
+  // reconciler-facing probeActivity and the monitorless turn-watch. Primary: Claude
+  // Code's intrinsic session probe (busy/shell→busy — the idle-while-working gap the
+  // pane-scrape misread; idle→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 activityFromProbeOrPane(process: ManagedProcess, session: string, socket?: string): ClaudeProbeActivity {
+    const managed = readManagedClaudeStatus({
+      pid: process.pid,
+      tmuxSession: session,
+      tmuxSocket: socket,
+      configHomeEnv: (process.meta?.env as Record<string, string | undefined> | undefined)?.CLAUDE_CONFIG_DIR,
+    });
+    if (managed?.reading.available) return claudeProbeActivity(managed.reading.status);
+    let pane: string;
+    try { pane = captureTmuxPane(session, socket); } catch { return "unknown"; }
+    if (claudePaneIsBusy(pane)) return "busy";
+    if (claudePaneLooksReady(pane)) return "idle";
+    return "unknown";
+  }
+
+  // #769 P1-A: an independent pane-busy read, consumed ONLY as a veto on the busy
+  // backstop's force-clear (BusyReconciler) — a probe-`idle` must never clear a live
+  // turn while the pane spinner still reads busy (a connection-retry/529 can write
+  // status:idle mid-turn without tripping the rate-limit pane detector — the #769
+  // gap). probeActivity stays probe-primary; this is a clear-time veto-toward-busy
+  // only. false on no session / capture failure (no veto).
+  async probePaneBusy(process: ManagedProcess): Promise<boolean> {
+    const session = process.meta?.tmuxSession as string | undefined;
+    const socket = process.meta?.tmuxSocket as string | undefined;
+    if (!session || !tmuxHasSession(session, socket)) return false;
+    try {
+      return claudePaneIsBusy(captureTmuxPane(session, socket));
+    } catch {
+      return false;
+    }
+  }
+
+  async deliver(process: ManagedProcess, messages: Message[]): Promise<void> {
+    const monitor = process.meta?.monitor as { deliver?(messages: Message[]): Promise<number[]> } | undefined;
+    // A monitor object always exists for headless claude (it proxies to the runner
+    // control server), so its presence says nothing about whether a monitor process
+    // is actually connected. `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.
+    const monitorless = process.meta?.monitorless === true;
+    if (!monitorless && monitor?.deliver) {
+      await monitor.deliver(messages);
+      return;
+    }
+    // Inject straight into the interactive tmux session via send-keys — the same
+    // transport deliverInitialPrompt uses. Keeps the agent on interactive Claude (the
+    // user's Max quota), never `claude -p`/API, and lets isolated automation agents
+    // receive their task (a claimable message) and any mid-session messages (e.g. the
+    // budget "wrap up" warning) that a launch --prompt can't carry.
+    const session = process.meta?.tmuxSession as string | undefined;
+    const socket = process.meta?.tmuxSocket as string | undefined;
+    if (!session || !tmuxHasSession(session, socket)) {
+      throw new Error("Claude monitor delivery is unavailable and no tmux session for fallback");
+    }
+    await waitForClaudeInputReady(session, CLAUDE_TMUX_READY_TIMEOUT_MS, socket);
+    // 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, so it's just confusing noise in a clean-room run.
+    await submitTextToTmux(session, claudeProviderMessageText(messages, { deliveryCount: 1, relaySurface: !monitorless }), socket);
+    // 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) this.beginMonitorlessTurnWatch(process, session, socket);
+  }
+
+  private beginMonitorlessTurnWatch(process: ManagedProcess, sessionName: string, socketName?: string): void {
+    this.stopTurnWatch();
+    // #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.
+    const livenessPid = resolveClaudePid(process.pid, sessionName, socketName);
+    // We just submitted a prompt, so a turn is starting. Emit a synthetic
+    // provider-turn busy now so the runner arms task-claim completion; the claim
+    // for this delivery is already registered before deliver() runs.
+    this.statusCb({ status: "busy", reason: "provider-turn", id: CLAUDE_TURN_WATCH_ID, ...(livenessPid ? { pids: [livenessPid] } : {}) });
+    let ticks = 0;
+    let idleStreak = 0;
+    let sawBusy = false;
+    this.turnWatcher = setInterval(() => {
+      ticks += 1;
+      if (!tmuxHasSession(sessionName, socketName) || 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;
+      }
+      // #768: drive turn boundaries off the intrinsic probe (busy/shell→busy,
+      // idle→idle), falling back to the pane-scrape when the probe is unavailable.
+      // shell→busy means a Bash gate no longer reads as a finished turn.
+      const activity = this.activityFromProbeOrPane(process, sessionName, socketName);
+      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();
+        this.statusCb({ status: "idle", reason: "provider-turn", id: CLAUDE_TURN_WATCH_ID });
+      }
+    }, CLAUDE_TURN_POLL_MS);
+  }
+
+  private stopTurnWatch(): void {
+    if (this.turnWatcher) {
+      clearInterval(this.turnWatcher);
+      this.turnWatcher = undefined;
+    }
+  }
+
+  async deliverInitialPrompt(process: ManagedProcess, prompt: string, options?: { readyTimeoutMs?: number }): Promise<void> {
+    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 initial prompt");
+    await waitForClaudeInputReady(session, options?.readyTimeoutMs ?? CLAUDE_TMUX_READY_TIMEOUT_MS, socket);
+    await submitTextToTmux(session, prompt, socket);
+  }
+
+  buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
+    // Create + bootstrap + auth-link the isolated config home (no-op for host base) so the
+    // assembler's materialize step has somewhere to write the provisioned skills/plugins.
+    prepareClaudeProfileHome(config);
+    const defaultArgs = profileUsesClaudeHostProviderGlobals(config) ? providerConfig.defaultArgs : [];
+    // #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("claude", config, providerConfig);
+    materializeLaunchAssembly("claude", config);
+    const isClaudeRig = /claude-rig/.test(providerConfig.command);
+    // Isolated profiles run their own CLAUDE_CONFIG_DIR and must never route through
+    // claude-rig — claude-rig resolves host rig config (and a bare `claude-rig` with no
+    // rig key just errors out). Only host-base profiles may use claude-rig.
+    const usesClaudeRig = isClaudeRig && profileUsesClaudeHostProviderGlobals(config);
+    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];
+    const args = [
+      ...rigPrefix,
+      ...assembled.args,
+      ...providerArgs,
+    ];
+    if (config.model) args.push("--model", config.model);
+    // #352: seed the prompt as Claude's positional arg for ALL launches (headless included) —
+    // `claude "<prompt>"` seeds the first turn via Claude's own input handling, immune to the
+    // send-keys/onboarding race that silently dropped headless spawns. Long/special-char briefs
+    // are shell-safe (shellEscape + launcher-script externalization in buildTmuxArgs).
+    if (config.prompt) args.push(String(config.prompt));
+    return {
+      command,
+      args,
+      cwd: config.cwd,
+      env: {
+        ...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 }
+          : {}),
+        AGENT_RELAY_PROVIDER: "claude",
+        ...(config.effort ? { CLAUDE_CODE_EFFORT_LEVEL: config.effort } : {}),
+      },
+    };
+  }
+
+  buildTmuxArgs(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): { sessionName: string; socketName: string; args: string[]; launcherScript: string } {
+    const sessionName = config.tmuxSession || tmuxSessionName(config.providerConfig.headless.tmuxPrefix, config.instanceId, config.label);
+    const socketName = tmuxSocketName(sessionName);
+    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);
+    const env: Record<string, string> = {};
+    for (const key of envKeys) if (spawnArgs.env[key] !== undefined) env[key] = spawnArgs.env[key]!;
+
+    // tmux new-session has a hard command-length limit that includes every argv item,
+    // including `-e KEY=value`. Keep tmux argv bounded by putting both env payloads
+    // (profile JSON, tokens, etc.) and the provider command/prompt in a session script.
+    const launcherScript = writeLauncherScript(sessionName, env, shellCmd);
+    tmuxArgs.push("-c", spawnArgs.cwd, `bash ${shellQuote(launcherScript)}`);
+    return { sessionName, socketName, args: tmuxArgs, launcherScript };
+  }
+
+  private async spawnHeadless(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): Promise<ManagedProcess> {
+    const { sessionName, socketName, args: tmuxArgs, launcherScript } = this.buildTmuxArgs(config, spawnArgs);
+    this.modelUnavailableReported = false;
+    this.connectionRetryActive = false;
+    this.promptGatePaneState = initialClaudePromptGatePaneState();
+
+    Bun.spawnSync(tmuxCommand(socketName, "kill-session", "-t", sessionName), {
+      stdin: "ignore", stdout: "ignore", stderr: "ignore",
+    });
+
+    const result = Bun.spawnSync(tmuxCommand(socketName, ...tmuxArgs), {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.toString().trim();
+      throw new Error(`tmux session creation failed: ${stderr || `exit code ${result.exitCode}`}`);
+    }
+
+    this.watchTmuxSession(sessionName, socketName);
+    const logFile = spawnArgs.env.AGENT_RELAY_LOG_FILE;
+    if (logFile) {
+      Bun.spawnSync(tmuxCommand(socketName, "pipe-pane", "-o", "-t", sessionName, `cat >> ${shellQuote(logFile)}`), {
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+    }
+
+    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,
+      },
+    };
+  }
+
+  private watchTmuxSession(sessionName: string, socketName?: string): void {
+    if (this.tmuxWatcher) clearInterval(this.tmuxWatcher);
+    this.tmuxWatcher = setInterval(() => {
+      if (!tmuxHasSession(sessionName, socketName)) {
+        clearInterval(this.tmuxWatcher!);
+        this.tmuxWatcher = undefined;
+        this.statusCb("offline");
+        return;
+      }
+      if (this.modelUnavailableReported) return;
+      let pane = "";
+      try {
+        pane = captureTmuxPane(sessionName, socketName);
+      } catch {
+        return;
+      }
+      const status = claudeModelUnavailableStatus(pane, sessionName);
+      if (status) {
+        this.modelUnavailableReported = true;
+        this.statusCb(status);
+        return;
+      }
+      // #769: connection-retry banner detection. Emits a transient blocked hold while the
+      // pane shows the retry footer; clears to idle when the banner disappears (API recovered).
+      const connRetryStatus = claudeConnectionRetryStatus(pane, sessionName);
+      if (connRetryStatus) {
+        if (!this.connectionRetryActive) {
+          this.connectionRetryActive = true;
+          this.statusCb(connRetryStatus);
+        }
+      } else if (this.connectionRetryActive) {
+        this.connectionRetryActive = false;
+        this.statusCb("idle");
+      }
+      // #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.
+      const promptGate = evaluateClaudePromptGatePane(pane, this.promptGatePaneState, {
+        sessionName,
+        busy: claudePaneIsBusy(pane),
+      });
+      this.promptGatePaneState = promptGate.state;
+      if (promptGate.action) {
+        this.sendPromptGateKeystroke(sessionName, promptGate.action.keystroke, socketName);
+        if (promptGate.status) this.statusCb(promptGate.status);
+      }
+    }, 2000);
+  }
+
+  // Best-effort: a failed auto-dismiss must not wedge the pane watcher.
+  private sendPromptGateKeystroke(sessionName: string, keystroke: string, socketName?: string): void {
+    try {
+      Bun.spawnSync(tmuxCommand(socketName, "send-keys", "-t", sessionName, keystroke), { stdin: "ignore", stdout: "ignore", stderr: "ignore" });
+    } catch {
+      // ignore; the timeline/status still publishes, and the next watcher tick can observe whether the pane moved.
+    }
+  }
+
+  private async shutdownTmux(sessionName: string, opts: { graceful: boolean; timeoutMs: number }, socketName?: string): Promise<void> {
+    this.stopTurnWatch();
+    if (this.tmuxWatcher) {
+      clearInterval(this.tmuxWatcher);
+      this.tmuxWatcher = undefined;
+    }
+
+    if (opts.graceful && tmuxHasSession(sessionName, socketName)) {
+      await submitTextToTmux(sessionName, CLAUDE_EXIT_COMMAND, socketName);
+
+      const deadline = Date.now() + claudeShutdownGraceMs(opts.timeoutMs);
+      while (Date.now() < deadline) {
+        if (!tmuxHasSession(sessionName, socketName)) return;
+        await Bun.sleep(200);
+      }
+    }
+
+    Bun.spawnSync(tmuxCommand(socketName, "kill-session", "-t", sessionName), {
+      stdin: "ignore", stdout: "ignore", stderr: "ignore",
+    });
+  }
+}
+
+export const CLAUDE_EXIT_COMMAND = "/exit";
+export const CLAUDE_TMUX_SUBMIT_DELAY_MS = 250;
+export const CLAUDE_TMUX_SUBMIT_KEY = "C-m";
+export const CLAUDE_TMUX_READY_TIMEOUT_MS = 10_000;
+// 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
+
+export function claudeShutdownGraceMs(timeoutMs: number): number {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return 10_000;
+  return Math.min(timeoutMs, 10_000);
+}
+
+// #557 — sessionStatusLineSettingsArgs now lives in ../launch-assembly (the single
+// launch-arg home); re-exported so existing ./claude consumers + tests keep their path.
+export { sessionStatusLineSettingsArgs };
+
+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;
+}
+
+
+export function tmuxSessionName(prefix: string, instanceId: string, label?: string): string {
+  if (label) return `${prefix}-${sanitizeFsName(label, { replacement: "-", collapse: false, lowercase: true })}`;
+  return `${prefix}-${instanceId.slice(0, 8)}`;
+}
+
+export function tmuxSocketName(sessionName: string): string {
+  return sanitizeFsName(`agent-relay-${sessionName}`, { replacement: "-", collapse: false, lowercase: true });
+}
+
+// Shared tmux helpers; tmuxHasSession re-exported for ./claude consumers + tests.
+export { tmuxHasSession };
+
+function captureTmuxPane(sessionName: string, socketName?: string): string {
+  const result = Bun.spawnSync(tmuxCommand(socketName, "capture-pane", "-p", "-t", sessionName, "-S", "-80"), {
+    stdin: "ignore", stdout: "pipe", stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    throw new Error(`tmux capture-pane failed: ${stderr || `exit code ${result.exitCode}`}`);
+  }
+  return result.stdout.toString();
+}
+
+// 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 { claudePaneLooksReady, claudePaneIsBusy, claudeRateLimitStatus, claudeConnectionRetryStatus, claudeModelUnavailableStatus } from "./claude-status-detectors";
+
+async function waitForClaudeInputReady(sessionName: string, timeoutMs = CLAUDE_TMUX_READY_TIMEOUT_MS, socketName?: string): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!tmuxHasSession(sessionName, socketName)) throw new Error("tmux session exited before Claude became ready");
+    if (claudePaneLooksReady(captureTmuxPane(sessionName, socketName))) return;
+    await Bun.sleep(200);
+  }
+  throw new Error(`Claude input was not ready within ${timeoutMs}ms`);
+}
+
+function pasteTextIntoTmux(sessionName: string, text: string, socketName?: string): void {
+  const bufferName = `agent-relay-${crypto.randomUUID()}`;
+  const setResult = Bun.spawnSync(tmuxCommand(socketName, "set-buffer", "-b", bufferName, text), {
+    stdin: "ignore", stdout: "ignore", stderr: "pipe",
+  });
+  if (setResult.exitCode !== 0) {
+    const stderr = setResult.stderr.toString().trim();
+    throw new Error(`tmux set-buffer failed: ${stderr || `exit code ${setResult.exitCode}`}`);
+  }
+  try {
+    const pasteResult = Bun.spawnSync(tmuxCommand(socketName, "paste-buffer", "-b", bufferName, "-t", sessionName), {
+      stdin: "ignore", stdout: "ignore", stderr: "pipe",
+    });
+    if (pasteResult.exitCode !== 0) {
+      const stderr = pasteResult.stderr.toString().trim();
+      throw new Error(`tmux paste-buffer failed: ${stderr || `exit code ${pasteResult.exitCode}`}`);
+    }
+  } finally {
+    Bun.spawnSync(tmuxCommand(socketName, "delete-buffer", "-b", bufferName), {
+      stdin: "ignore", stdout: "ignore", stderr: "ignore",
+    });
+  }
+}
+
+async function submitTextToTmux(sessionName: string, text: string, socketName?: string): Promise<void> {
+  pasteTextIntoTmux(sessionName, text, socketName);
+  await Bun.sleep(CLAUDE_TMUX_SUBMIT_DELAY_MS);
+  const result = Bun.spawnSync(tmuxCommand(socketName, "send-keys", "-t", sessionName, CLAUDE_TMUX_SUBMIT_KEY), {
+    stdin: "ignore", stdout: "ignore", stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    throw new Error(`tmux submit failed: ${stderr || `exit code ${result.exitCode}`}`);
+  }
+}
+
+function writeLauncherScript(sessionName: string, env: Record<string, string>, shellCmd: string): string {
+  const scriptPath = launcherScriptPathForSession(sessionName);
+  const launcherDir = dirname(scriptPath); mkdirSync(launcherDir, { recursive: true, mode: 0o700 }); chmodSync(launcherDir, 0o700);
+  const exports = Object.entries(env)
+    .map(([key, value]) => `export ${shellEnvKey(key)}=${shellQuote(value)}`)
+    .join("\n");
+  writeFileSync(scriptPath, `#!/usr/bin/env bash\n${exports ? `${exports}\n` : ""}exec ${shellCmd}\n`, { mode: 0o700 });
+  return scriptPath;
+}
+
+function shellEnvKey(key: string): string {
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) return key;
+  throw new Error(`invalid environment variable name for Claude launcher: ${key}`);
+}
+
+export function tmuxEnvKeys(env: Record<string, string>, providerEnv: Record<string, string>): string[] {
+  const keys = new Set<string>();
+  for (const key of Object.keys(env)) {
+    if (key.startsWith("AGENT_RELAY_") || key.startsWith("CLAUDE_")) {
+      keys.add(key);
+    }
+  }
+  for (const key of Object.keys(providerEnv)) {
+    keys.add(key);
+  }
+  return [...keys].sort();
+}
+
+// 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<void> {
+  const proc = process.process;
+  if (!proc) return;
+  try {
+    proc.kill(opts.graceful ? "SIGTERM" : "SIGKILL");
+  } catch {
+    return;
+  }
+  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(() => {});
+  }
+}