@humwick/runner 0.0.0-stage → 0.130.0

package/src/adapters/claude-headless.ts

@@ -0,0 +1,617 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import { verifyClaudeSubagentVersion } from "./claude-subagents";
+import { isRecord, providerArgsSelectStreamJson, type LaunchMode, type Message, type ProviderState } from "@humwick/sdk";
+import { terminateProviderProcesses } from "../provider-processes";
+import { createInterface } from "node:readline";
+import { Readable } from "node:stream";
+import type { DeliverResult, ManagedProcess, PromptOfferOptions, ProviderAdapter, ProviderConfig, ProviderDeliverContext, ProviderSessionEvent, ProviderSessionTurnContext, ProviderStatusUpdate, ProviderTokenUsageReporter, RunnerSpawnConfig, ShutdownOutcome, SpawnArgs } from "../adapter";
+import { deliveredBatchReplyRoute } from "../reply-obligation-cache";
+import { ClaudeAdapter } from "./claude";
+import { claudeEffortSwitchMeta } from "./claude-effort";
+import { claudeProviderMessageText } from "./claude-delivery";
+import { ClaudeHeadlessMirror } from "./claude-headless-mirror";
+import { claudeApiErrorOf, claudeRefusalHold, claudeResultFailure, claudeTurnError } from "./claude-headless-refusal";
+import { claudePermissionPromptHandler } from "./claude-permission";
+import { collectClaudeTranscriptArchiveSegment, collectClaudeTranscriptSessionEvents } from "./claude-session-capture";
+import { claudeConfigHome, claudeTranscriptPath } from "./claude-session-probe";
+import { ClaudeTranscriptTokenUsageCapture } from "./claude-token-usage-capture";
+import { ProviderSubmitFailure } from "../provider-submit-failure";
+import { claudeToolHookPaths } from "./claude-transcript";
+
+interface HeadlessState {
+  child: Bun.Subprocess<"pipe", "pipe", "pipe">;
+  turnId?: string;
+  /** The turn the latest submit minted; a delivery reads it on resuming, after the turn may already have ended. */
+  submittedTurnId?: string;
+  replyRoute?: ProviderSessionEvent["replyRoute"];
+  /** Relay ids the runner already took as delivered for the live turn; a later refusal names them so the runner re-parks them. */
+  acked?: { turnId: string; ids: number[] };
+  stopping: boolean;
+  initialized: boolean;
+  submitConfirmed: boolean;
+  lastActivityAt: number;
+  unknown?: { since: number; timeoutMs: number };
+  receipt?: { resolve(): void; reject(error: Error): void; ready(): void; retrying(delayMs: number): void };
+  /** Pending stream-json control_request receipts, keyed by request_id. */
+  controlRequests: Map<string, (error?: Error, response?: Record<string, unknown>) => void>;
+  contextCommand?: ContextCommand;
+  interruptedTurnId?: string;
+  sessionId?: string;
+  /** Claude's own cwd and config home, from which its session transcript path follows. */
+  cwd?: string;
+  configHome: string;
+  mirror: ClaudeHeadlessMirror;
+  /** Context commands released by the watchdog; their late native results are not turn results. */
+  abandonedCommands: Set<string>;
+  /** The live turn's API-error class, from the synthetic error message that precedes its error result. */
+  apiError?: string;
+  /** Turn the provider refused under a rate-limit/quota/overload hold (#2771). */
+  refusedTurnId?: string;
+  /** Resolves a delivery waiting for the turn's first outcome: true if it was refused. */
+  refusalWatch?: { turnId: string; settle(refused: boolean): void };
+}
+
+/** A `/compact` or `/clear` slash command; only a native boundary event settles it as done. */
+interface ContextCommand {
+  kind: "compact" | "clear";
+  uuid: string;
+  boundary?: Record<string, unknown>;
+  failure?: string;
+  sessionId?: string;
+  timedOut?: boolean;
+  /** The provider refused the command under a rate-limit/quota/overload wall. */
+  hold?: ProviderState;
+  settle(error?: Error): void;
+}
+
+const CONTROL_RECEIPT_TIMEOUT_MS = 10_000;
+// Compaction is a full model summarization pass; large contexts take minutes.
+const COMPACT_BOUNDARY_TIMEOUT_MS = 600_000;
+const CLEAR_BOUNDARY_TIMEOUT_MS = 60_000;
+// A refusal's synthetic error and result follow the input receipt within milliseconds; a later one reports through status only.
+const REFUSAL_GRACE_MS = 400;
+// After a boundary timeout the command is interrupted; this bounds how long input stays fenced for it to settle.
+const CONTEXT_COMMAND_RECOVERY_MS = 30_000;
+
+export function createClaudeTransportAdapter(provider: string, args: string[], launchMode?: LaunchMode): ProviderAdapter {
+  const rawStreamJson = providerArgsSelectStreamJson(args);
+  // The explicit launch mode wins; raw stream-json providerArgs remain the legacy way to select headless.
+  if (launchMode === "interactive" && rawStreamJson) throw new Error("launchMode=interactive conflicts with --input-format stream-json providerArgs");
+  const streaming = launchMode ? launchMode === "headless" : rawStreamJson;
+  return streaming ? new ClaudeHeadlessAdapter(provider) : new ClaudeAdapter({ provider });
+}
+
+/** Persistent native Claude print-mode transport (#2754, #2771). */
+export class ClaudeHeadlessAdapter implements ProviderAdapter {
+  readonly statusSourceId: string;
+  readonly permissionPromptHandler = claudePermissionPromptHandler;
+  readonly toolHookPaths = claudeToolHookPaths;
+  readonly compactSupportsInstructions = true;
+  readonly reportsContextResets = true;
+  // Stream-json input sent mid-turn queues behind the live turn, so context commands wait for idle.
+  readonly awaitsIdleBeforeContextCommand = true;
+  // clearContext resolves only on Claude's conversation_reset boundary (clearConfirmed), so the
+  // continuation is delivered in the same command, before any queued inbox message.
+  readonly couplesClearInjectContinuation = true;
+  private readonly launch: ClaudeAdapter;
+  private status: (event: ProviderStatusUpdate) => void = () => {};
+  private response: (event: ProviderSessionEvent) => void = () => {};
+  private state?: HeadlessState;
+  private watching = true;
+  private tokenUsage?: { capture: ClaudeTranscriptTokenUsageCapture; reporter: ProviderTokenUsageReporter };
+  // Instance-scoped so tests can shorten the bounds.
+  private readonly refusalGraceMs = REFUSAL_GRACE_MS;
+  private readonly contextTimeouts = { compact: COMPACT_BOUNDARY_TIMEOUT_MS, clear: CLEAR_BOUNDARY_TIMEOUT_MS, recovery: CONTEXT_COMMAND_RECOVERY_MS };
+  readonly collectSessionEvents = collectClaudeTranscriptSessionEvents;
+  readonly collectSessionArchiveSegment = collectClaudeTranscriptArchiveSegment;
+
+  constructor(readonly provider: string = "claude") {
+    this.statusSourceId = provider;
+    this.launch = new ClaudeAdapter({ provider });
+  }
+
+  preloadRunnerConfig() { return this.launch.preloadRunnerConfig(); }
+  hydrateSpawnConfig(config: RunnerSpawnConfig) { return this.launch.hydrateSpawnConfig(config); }
+  onStatusChange(cb: (event: ProviderStatusUpdate) => void) { this.status = cb; }
+  onSessionEvent(cb: (event: ProviderSessionEvent) => void) { this.response = cb; }
+  stopStatusWatchers() { this.watching = false; }
+  resumeStatusWatchers() { this.watching = true; }
+
+  configureTokenUsageReporter(reporter: ProviderTokenUsageReporter): void {
+    this.tokenUsage = { reporter, capture: new ClaudeTranscriptTokenUsageCapture({ post: reporter.report, debug: reporter.debug }) };
+  }
+
+  async captureSubagentTokenUsage(transcriptPath: string): Promise<void> {
+    if (!this.tokenUsage) throw new Error("Token usage reporter is not configured");
+    await this.trackTokenUsageCapture(transcriptPath, () => this.tokenUsage!.capture.captureSubagent(transcriptPath, true));
+  }
+
+  async captureFinalTokenUsage(transcriptPath: string | undefined, ctx: ProviderSessionTurnContext): Promise<void> {
+    const path = transcriptPath ?? (this.state && this.transcriptPath(this.state));
+    await this.trackTokenUsageCapture(path, () => path && this.tokenUsage
+      ? this.tokenUsage.capture.captureWithSettle(path, { pollIntervalMs: ctx.settlePollIntervalMs, timeoutMs: ctx.settlePollTimeoutMs })
+      : Promise.resolve(0), false).catch((error) => this.tokenUsage?.reporter.reportFailure(error));
+  }
+
+  buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
+    if (!config.headless) throw new Error("Claude stream-json transport requires --headless");
+    // Use the existing provisioning, permission policy and credential-isolation seam.
+    // Prompts enter through stdin only; no positional/one-shot prompt at launch.
+    const args = this.launch.buildSpawnArgs({ ...config, prompt: undefined, rig: undefined }, { ...providerConfig, command: "claude" });
+    const transportArgs: string[] = [];
+    for (let i = 0; i < args.args.length; i++) {
+      const arg = args.args[i]!;
+      if (arg === "--input-format" || arg === "--output-format") {
+        if (args.args[++i] !== "stream-json") throw new Error("Claude headless transport requires stream-json input and output");
+        continue;
+      }
+      if (/^--(?:input|output)-format=/.test(arg)) {
+        if (!arg.endsWith("=stream-json")) throw new Error("Claude headless transport requires stream-json input and output");
+        continue;
+      }
+      transportArgs.push(arg);
+    }
+    return { ...args, args: [...transportArgs, "--print", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose", "--replay-user-messages"],
+      env: writeChildEnv({}, { ...args.env, AGENT_RELAY_CLAUDE_TRANSPORT: "stream-json" }) };
+  }
+
+  async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
+    await verifyClaudeSubagentVersion(config);
+    const args = this.buildSpawnArgs(config, config.providerConfig);
+    this.watching = true;
+    const child = Bun.spawn([args.command, ...args.args], {
+      cwd: args.cwd,
+      env: args.env,
+      stdin: "pipe", stdout: "pipe", stderr: "pipe",
+    });
+    const state: HeadlessState = { child, stopping: false, initialized: false, submitConfirmed: false, lastActivityAt: Date.now(), controlRequests: new Map(),
+      configHome: claudeConfigHome(args.env.CLAUDE_CONFIG_DIR), mirror: new ClaudeHeadlessMirror(), abandonedCommands: new Set() };
+    this.state = state;
+    // Drain stderr continuously: a full pipe must never wedge the provider.
+    void this.readLines(child.stderr, (line) => console.error(`[${this.provider} headless] ${line}`)).catch(() => {});
+    const stdout = this.readLines(child.stdout, (line) => {
+      if (state !== this.state || state.stopping) return;
+      let event: Record<string, unknown>;
+      try { event = JSON.parse(line); } catch {
+        console.error(`[${this.provider} headless] skipping non-JSON stdout line`);
+        return;
+      }
+      if (!event || typeof event !== "object" || typeof event.type !== "string") {
+        console.error(`[${this.provider} headless] skipping non-event stdout JSON`);
+        return;
+      }
+      state.lastActivityAt = Date.now();
+      if (event.type === "control_response") return this.onControlResponse(state, event);
+      if (state.contextCommand && !state.contextCommand.timedOut) this.observeContextCommand(state, state.contextCommand, event);
+      else this.observeUnwaitedReset(state, event);
+      if (state.contextCommand?.timedOut) this.observeContextCommand(state, state.contextCommand, event);
+      if (event.type === "system" && event.subtype === "init" && !state.initialized) {
+        state.initialized = true;
+        state.receipt?.ready();
+      }
+      if (event.type === "system" && event.subtype === "init" && typeof event.session_id === "string") {
+        state.sessionId = event.session_id;
+        if (typeof event.cwd === "string") state.cwd = event.cwd;
+        // The runner learns the transcript path from busy/idle edges; a first turn that fails has no later one.
+        if (state.turnId || state.contextCommand) this.emitStatus({ status: "busy", reason: "provider-turn", ...(state.turnId ? { id: state.turnId } : {}), ...this.transcriptStatus(state) });
+      }
+      // Claude replays the input once the API answers, so a throttled request keeps its replay behind every internal retry.
+      if (event.type === "system" && event.subtype === "api_retry" && state.turnId && !state.contextCommand) {
+        state.submitConfirmed = true;
+        state.unknown = undefined;
+        state.receipt?.retrying(typeof event.retry_delay_ms === "number" ? event.retry_delay_ms : 0);
+      }
+      // Native start confirms consumption before API prefill/thinking can delay the user replay.
+      if ((event.type === "command_lifecycle" && event.state === "started" && event.command_uuid === state.turnId)
+        || (event.type === "user" && event.uuid === state.turnId)) {
+        state.submitConfirmed = true;
+        state.unknown = undefined;
+        state.receipt?.resolve();
+      }
+      if (event.type === "assistant" && !event.parent_tool_use_id) {
+        const apiError = claudeApiErrorOf(event);
+        if (apiError) state.apiError = apiError;
+        else state.refusalWatch?.settle(false);
+      }
+      if (event.type === "result" && typeof event.user_message_uuid === "string" && state.abandonedCommands.delete(event.user_message_uuid)) return;
+      if (this.watching) for (const step of state.mirror.observe(event, state.turnId)) this.response(step);
+      if (event.type === "result") { if (state.turnId) this.captureTokenUsage(state); this.onNativeResult(event); }
+      const nativeHold = event.type === "result" ? this.nativeResultHold(event) : undefined;
+      if (event.type !== "result" || !state.turnId) { if (nativeHold) this.emitStatus({ status: "idle", providerState: nativeHold }); return; }
+      const turnId = state.turnId;
+      const replyRoute = state.replyRoute;
+      state.replyRoute = undefined;
+      state.submitConfirmed = true;
+      state.unknown = undefined;
+      state.turnId = undefined;
+      const apiError = state.apiError;
+      state.apiError = undefined;
+      if (event.is_error !== false || event.subtype !== "success") {
+        if (state.interruptedTurnId === turnId) {
+          // Our own interrupt ended the turn (error_during_execution); it ends idle, not failed.
+          state.interruptedTurnId = undefined;
+          state.refusalWatch?.settle(false);
+          this.emitStatus({ status: "idle", reason: "provider-turn", clear: ["provider-turn"], id: turnId, ...this.transcriptStatus(state) });
+          return;
+        }
+        // A throttle, quota wall or overload refusal is neither delivered nor failed: hold, then resume (#2619).
+        const turnError = claudeTurnError(event, apiError);
+        const hold = nativeHold ?? (turnError && claudeRefusalHold(turnError, this.statusSourceId));
+        if (hold) {
+          state.refusedTurnId = turnId;
+          state.refusalWatch?.settle(true);
+          // Input acknowledged before the refusal landed was never answered: the runner parks it again to replay after the hold.
+          const refusedInputIds = state.acked?.turnId === turnId ? state.acked.ids : undefined;
+          this.emitStatus({ status: "idle", reason: "provider-turn", clear: ["provider-turn"], id: turnId, providerState: hold, ...(refusedInputIds ? { refusedInputIds } : {}), ...this.transcriptStatus(state) });
+          return;
+        }
+        state.refusalWatch?.settle(false);
+        // Do not turn an error result into a successful report-up.
+        this.emitStatus({ status: "error", clear: ["provider-turn"], id: turnId, ...this.transcriptStatus(state), metadata: claudeResultFailure(event) });
+        return;
+      }
+      state.refusalWatch?.settle(false);
+      // Stopped watchers intentionally drop finals during teardown; resume cannot replay them.
+      if (this.watching && typeof event.result === "string" && event.result.trim()) {
+        this.response({ type: "response", body: event.result, origin: "provider", turnId, final: true,
+          confidence: "definitive", endedBy: "completed", replyToUserObligation: true, replyRoute });
+      }
+      this.emitStatus({ status: "idle", reason: "provider-turn", clear: ["provider-turn"], id: turnId, ...this.transcriptStatus(state) });
+    }).catch((error) => {
+      if (state !== this.state || state.stopping) return;
+      console.error(`[${this.provider} headless] ${error}`);
+      this.abandonPending(state, "Claude headless stream failed", error);
+      this.emitStatus("error");
+      child.kill("SIGKILL");
+    });
+    const nativeExit = child.exited.then(async (code) => {
+      // The final result can still be buffered when the process exits (#3314).
+      await stdout;
+      await this.onNativeExit(child, code, state.stopping);
+      this.abandonPending(state, "Claude exited");
+      if (state === this.state && !state.stopping) this.emitStatus(code === 0 ? "offline" : "error");
+    }).catch((error) => {
+      if (state !== this.state || state.stopping) return;
+      console.error(`[${this.provider} headless] exit observation failed: ${error}`);
+      this.abandonPending(state, "Claude exit observation failed", error);
+      this.emitStatus("error");
+    });
+    return { pid: child.pid, process: child, meta: { headlessState: state, nativeExit, env: args.env, transport: "stream-json", getContext: () => state.mirror.context(),
+      ...claudeEffortSwitchMeta(this.provider, config, false) } };
+  }
+
+  async setEffort(process: ManagedProcess, effort: string): Promise<{ effort: string }> {
+    const state = this.getState(process);
+    await this.controlRequest(state, { subtype: "apply_flag_settings", settings: { effortLevel: effort } });
+    const { receipt } = await this.controlRequest(state, { subtype: "get_settings" });
+    const applied = isRecord(receipt) && isRecord(receipt.applied) ? receipt.applied.effort : undefined;
+    if (applied !== effort) throw new Error(`Claude headless effort verification failed: requested ${effort}, applied ${String(applied)}`);
+    return { effort };
+  }
+
+  async deliver(process: ManagedProcess, messages: Message[], ctx?: ProviderDeliverContext): Promise<number[] | DeliverResult> {
+    const state = this.getState(process);
+    if (state.turnId || state.contextCommand || ctx?.isRecipientMidTurn?.()) return [];
+    if (!messages.length) return [];
+    state.replyRoute = deliveredBatchReplyRoute(messages);
+    let outcome: void | "held";
+    try { outcome = await this.deliverInitialPrompt(process, claudeProviderMessageText(messages)); }
+    catch (error) { state.replyRoute = undefined; throw error; }
+    const turnId = state.submittedTurnId;
+    const ids = messages.map((message) => message.id);
+    // Judged synchronously on resuming: native events can have been read since the submit settled, however stdout was batched.
+    // Refused under a provider hold: not acknowledged, parked by the runner until a turn goes through again.
+    if (outcome === "held" || (turnId && state.refusedTurnId === turnId)) return { acknowledgedIds: [], providerHeldIds: ids };
+    if (turnId && state.turnId === turnId) state.acked = { turnId, ids };
+    return ids;
+  }
+
+  async deliverInitialPrompt(process: ManagedProcess, prompt: string, options?: PromptOfferOptions): Promise<void | "held"> {
+    const state = this.getState(process);
+    if (state.unknown) throw new ProviderSubmitFailure("Claude headless input is still unconfirmed", false);
+    if (state.turnId) throw new Error("Claude headless turn already in progress");
+    if (state.contextCommand) throw new Error(`Claude headless ${state.contextCommand.kind} is in progress`);
+    const turnId = crypto.randomUUID();
+    state.turnId = state.submittedTurnId = turnId;
+    state.apiError = undefined;
+    state.submitConfirmed = false;
+    this.emitStatus({ status: "busy", reason: "provider-turn", id: turnId, pids: [state.child.pid], ...this.transcriptStatus(state) });
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let timeoutMs = state.initialized ? options?.readyTimeoutMs ?? 30_000 : Math.max(options?.readyTimeoutMs ?? 0, 120_000);
+    const receipt = new Promise<void>((resolve, reject) => {
+      const arm = (extraMs = 0) => {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => reject(new ProviderSubmitFailure("Claude headless input receipt timed out", false)), timeoutMs + extraMs);
+      };
+      state.receipt = { resolve, reject, ready: () => { timeoutMs = options?.readyTimeoutMs ?? 30_000; arm(); }, retrying: (delayMs) => arm(delayMs) };
+      arm();
+    });
+    // Attach the rejection handler before flushing stdin (exit/read errors may race it).
+    void receipt.catch(() => {});
+    try {
+      await this.writeUserInput(state, turnId, prompt);
+      await receipt;
+    } catch (error) {
+      state.replyRoute = undefined;
+      // Ambiguous pipe failure: never silently retry an assignment that may have started.
+      if (!state.submitConfirmed) state.unknown = { since: Date.now(), timeoutMs };
+      this.emitStatus("error");
+      throw new ProviderSubmitFailure("Claude headless stdin submission could not be confirmed", false, error);
+    } finally { if (timer) clearTimeout(timer); state.receipt = undefined; }
+    if (await this.refusedWithinGrace(state, turnId) || state.refusedTurnId === turnId) return "held";
+  }
+
+  /** Whether the turn just submitted was refused under a provider hold, judged only on its first outcome. */
+  private refusedWithinGrace(state: HeadlessState, turnId: string): Promise<boolean> {
+    if (state.refusedTurnId === turnId) return Promise.resolve(true);
+    if (state.turnId !== turnId) return Promise.resolve(false);
+    return new Promise((resolve) => {
+      const settle = (refused: boolean) => {
+        clearTimeout(timer);
+        if (state.refusalWatch?.turnId === turnId) state.refusalWatch = undefined;
+        resolve(refused);
+      };
+      const timer = setTimeout(() => settle(false), this.refusalGraceMs);
+      state.refusalWatch = { turnId, settle };
+    });
+  }
+
+  async probeActivity(process: ManagedProcess): Promise<"busy" | "idle" | "unknown"> {
+    const state = process.meta?.headlessState as HeadlessState | undefined;
+    if (!state || state !== this.state || state.stopping || state.child.exitCode !== null) return "unknown";
+    this.expireUnknownSubmit(state);
+    if (state.unknown) return "unknown";
+    return state.turnId || state.contextCommand ? "busy" : "idle";
+  }
+
+  async compact(process: ManagedProcess, opts?: { instructions?: string }): Promise<Record<string, unknown>> {
+    const command = opts?.instructions?.trim() ? `/compact ${opts.instructions.trim()}` : "/compact";
+    const done = await this.runContextCommand(process, "compact", command, this.contextTimeouts.compact);
+    const state = process.meta?.headlessState as HeadlessState | undefined;
+    state?.mirror.resetContext(typeof done.boundary?.post_tokens === "number" ? done.boundary.post_tokens : undefined);
+    this.emitStatus({ status: "idle", reason: "provider-turn", timeline: { status: "compacted", timestamp: Date.now() }, metadata: { compactTrigger: "manual" }, ...this.transcriptStatus(state) });
+    return { method: "stream-json", command: "/compact", boundary: done.boundary };
+  }
+
+  async clearContext(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const previousSessionId = (process.meta?.headlessState as HeadlessState | undefined)?.sessionId;
+    const done = await this.runContextCommand(process, "clear", "/clear", this.contextTimeouts.clear);
+    const state = process.meta?.headlessState as HeadlessState | undefined;
+    state?.mirror.clearContext();
+    this.emitStatus({ status: "idle", reason: "provider-turn", clear: ["subagent"],
+      timeline: { status: "context-cleared", timestamp: Date.now() }, ...this.transcriptStatus(state) });
+    return { method: "stream-json", command: "/clear", clearConfirmed: true, previousSessionId, sessionId: done.sessionId };
+  }
+
+  async interrupt(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const state = this.getState(process);
+    const turnId = state.turnId;
+    if (!turnId) throw new Error("no active Claude headless turn to interrupt");
+    state.interruptedTurnId = turnId;
+    try {
+      return { method: "stream-json-interrupt", turnId, ...await this.controlRequest(state, { subtype: "interrupt" }) };
+    } catch (error) {
+      if (state.interruptedTurnId === turnId) state.interruptedTurnId = undefined;
+      throw error;
+    }
+  }
+
+  async confirmSubmitRecovery(process: ManagedProcess): Promise<boolean> {
+    const state = this.getState(process);
+    return state.submitConfirmed;
+  }
+
+  releaseSubmitHold(process: ManagedProcess): void {
+    const state = this.getState(process);
+    state.replyRoute = undefined;
+    if (state.unknown) { state.unknown = undefined; state.turnId = undefined; }
+  }
+
+  async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome> {
+    const state = process.meta?.headlessState as HeadlessState | undefined;
+    if (!state) return "killed";
+    state.stopping = true;
+    this.abandonPending(state, "Claude headless transport stopped");
+    return terminateProviderProcesses([state.child], opts, () => state.child.stdin.end());
+  }
+
+  private transcriptPath(state: HeadlessState): string | undefined {
+    return state.sessionId && state.cwd ? claudeTranscriptPath(state.configHome, state.cwd, state.sessionId) : undefined;
+  }
+
+  /** The runner keys transcript archive, insights and terminal token settling off this path. */
+  private transcriptStatus(state: HeadlessState | undefined): { transcriptPath?: string } {
+    const transcriptPath = state && this.transcriptPath(state);
+    return transcriptPath ? { transcriptPath } : {};
+  }
+
+  private captureTokenUsage(state: HeadlessState): void {
+    const path = this.transcriptPath(state);
+    this.trackTokenUsageCapture(path, () => path && this.tokenUsage ? this.tokenUsage.capture.capture(path) : Promise.resolve(0))
+      .catch((error) => this.tokenUsage?.reporter.reportFailure(error));
+  }
+
+  private async trackTokenUsageCapture(path: string | undefined, read: () => Promise<number>, pending = true): Promise<void> {
+    const reporter = this.tokenUsage?.reporter;
+    if (!reporter) return;
+    if (reporter.capture) await reporter.capture(`claude-transcript:${path ?? "unresolved"}`, read, pending);
+    else await read();
+  }
+
+  private getState(process: ManagedProcess): HeadlessState {
+    const state = process.meta?.headlessState as HeadlessState | undefined;
+    if (!state || state !== this.state || state.stopping || state.child.exitCode !== null) throw new Error("Claude headless process is unavailable");
+    this.expireUnknownSubmit(state);
+    return state;
+  }
+
+  private expireUnknownSubmit(state: HeadlessState): void {
+    if (!state.unknown || Date.now() - Math.max(state.unknown.since, state.lastActivityAt) < 2 * state.unknown.timeoutMs) return;
+    const turnId = state.turnId;
+    state.unknown = undefined;
+    state.turnId = undefined;
+    state.replyRoute = undefined;
+    // Silence releases activity only: the runner's non-retry-safe delivery hold remains.
+    console.error(`[${this.provider} headless] unconfirmed input expired without activity; delivery remains held`);
+    this.emitStatus({ status: "idle", reason: "provider-turn", clear: ["provider-turn"], id: turnId, metadata: { submitDisposition: "held" } });
+  }
+
+  /** Submit a slash command and resolve only on its native boundary. A timeout fails the command and starts {@link recoverContextCommand}. */
+  private async runContextCommand(process: ManagedProcess, kind: ContextCommand["kind"], text: string, timeoutMs: number): Promise<ContextCommand> {
+    const state = this.getState(process);
+    if (state.turnId || state.unknown || state.contextCommand) throw new Error(`Claude headless ${kind} refused: provider input is not idle`);
+    let resolve!: (command: ContextCommand) => void, reject!: (error: Error) => void, settled = false;
+    const done = new Promise<ContextCommand>((res, rej) => { resolve = res; reject = rej; });
+    void done.catch(() => {});
+    const command: ContextCommand = { kind, uuid: crypto.randomUUID(), settle: (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) reject(error); else resolve(command);
+    } };
+    const timer = setTimeout(() => {
+      command.timedOut = true;
+      command.settle(new Error(`Claude headless ${kind} boundary timed out after ${timeoutMs}ms`));
+      this.recoverContextCommand(state, command);
+    }, timeoutMs);
+    state.contextCommand = command;
+    state.apiError = undefined;
+    this.emitStatus({ status: "busy", reason: "provider-turn", timeline: { status: kind === "compact" ? "compacting" : "clearing-context", timestamp: Date.now() } });
+    try {
+      await this.writeUserInput(state, command.uuid, text);
+      return await done;
+    } catch (error) {
+      if (state.contextCommand === command && !command.timedOut) state.contextCommand = undefined;
+      // A dying child reports its own terminal status; only a live, unfenced provider returns to idle.
+      if (state === this.state && !state.stopping && state.child.exitCode === null && !state.contextCommand) {
+        this.emitStatus({ status: "idle", reason: "provider-turn", ...(command.hold ? { providerState: command.hold } : {}) });
+      }
+      throw error;
+    }
+  }
+
+  /** Interrupt the stuck command; if Claude still never settles it, release the input fence with a visible error. */
+  private recoverContextCommand(state: HeadlessState, command: ContextCommand): void {
+    if (state.contextCommand !== command) return;
+    void this.controlRequest(state, { subtype: "interrupt" }).catch(() => {});
+    setTimeout(() => {
+      if (state.contextCommand !== command || state !== this.state || state.stopping || state.child.exitCode !== null) return;
+      state.contextCommand = undefined;
+      state.abandonedCommands.add(command.uuid);
+      const body = `Claude headless /${command.kind} did not settle within ${this.contextTimeouts.recovery}ms of its timeout; input released.`;
+      console.error(`[${this.provider} headless] ${body}`);
+      if (this.watching) this.response({ type: "narration", origin: "provider", diagnostic: true, body });
+      this.emitStatus({ status: "idle", reason: "provider-turn" });
+    }, this.contextTimeouts.recovery);
+  }
+
+  /** #3398 — a reset no live command waits for (a timed-out or abandoned one, or Claude's own) is still a reset. */
+  private observeUnwaitedReset(state: HeadlessState, event: Record<string, unknown>): void {
+    const compacted = event.type === "system" && event.subtype === "compact_boundary";
+    if (!compacted && event.type !== "conversation_reset") return;
+    if (compacted) state.mirror.resetContext(isRecord(event.compact_metadata) && typeof event.compact_metadata.post_tokens === "number" ? event.compact_metadata.post_tokens : undefined);
+    else state.mirror.clearContext();
+    const timeline = { status: compacted ? "compacted" : "context-cleared", timestamp: Date.now() };
+    const trigger = compacted && isRecord(event.compact_metadata) && typeof event.compact_metadata.trigger === "string" ? event.compact_metadata.trigger : undefined;
+    const busy = state.turnId || state.contextCommand;
+    this.emitStatus({ status: busy ? "busy" : "idle", reason: "provider-turn", ...(state.turnId ? { id: state.turnId } : {}), timeline,
+      ...(trigger ? { metadata: { compactTrigger: trigger } } : {}), ...this.transcriptStatus(state) });
+  }
+
+  private observeContextCommand(state: HeadlessState, command: ContextCommand, event: Record<string, unknown>): void {
+    if (command.kind === "compact" && event.type === "system") {
+      if (event.subtype === "status" && event.compact_result === "failed") command.failure = String(event.compact_error ?? "compaction failed");
+      if (event.subtype === "compact_boundary") command.boundary = isRecord(event.compact_metadata) ? event.compact_metadata : {};
+    }
+    if (command.kind === "clear" && event.type === "conversation_reset" && event.user_message_uuid === command.uuid) {
+      command.boundary = { conversationId: event.new_conversation_id };
+    }
+    if (command.kind === "clear" && command.boundary && event.type === "system" && event.subtype === "init" && typeof event.session_id === "string") {
+      command.sessionId = event.session_id;
+    }
+    if (event.type !== "result" || (event.user_message_uuid !== undefined && event.user_message_uuid !== command.uuid)) return;
+    state.contextCommand = undefined;
+    const apiError = state.apiError;
+    state.apiError = undefined;
+    if (event.is_error === true) {
+      const turnError = claudeTurnError(event, apiError);
+      command.hold = turnError && claudeRefusalHold(turnError, this.statusSourceId);
+    }
+    if (command.timedOut) {
+      // The caller already failed; Claude has now settled the command, so release the input fence.
+      this.emitStatus({ status: "idle", reason: "provider-turn" });
+      return;
+    }
+    if (command.boundary && !command.failure && event.is_error !== true) command.settle();
+    else command.settle(new Error(`Claude headless ${command.kind} completed without a ${command.kind === "compact" ? "compact_boundary" : "conversation_reset"}: ${command.failure ?? String(event.subtype ?? "no boundary")}`));
+  }
+
+  private controlRequest(state: HeadlessState, request: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const requestId = `relay-${crypto.randomUUID()}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => settle(new Error(`Claude headless ${String(request.subtype)} receipt timed out`)), CONTROL_RECEIPT_TIMEOUT_MS);
+      const settle = (error?: Error, response?: Record<string, unknown>) => {
+        clearTimeout(timer);
+        state.controlRequests.delete(requestId);
+        if (error) reject(error); else resolve({ requestId, receipt: response ?? {} });
+      };
+      state.controlRequests.set(requestId, settle);
+      const failed = (error: unknown) => settle(new Error(`Claude headless control request write failed: ${error}`));
+      try {
+        state.child.stdin.write(JSON.stringify({ type: "control_request", request_id: requestId, request }) + "\n");
+        Promise.resolve(state.child.stdin.flush()).catch(failed);
+      } catch (error) { failed(error); }
+    });
+  }
+
+  private onControlResponse(state: HeadlessState, event: Record<string, unknown>): void {
+    const response = isRecord(event.response) ? event.response : undefined;
+    const settle = typeof response?.request_id === "string" ? state.controlRequests.get(response.request_id) : undefined;
+    if (!response || !settle) return;
+    if (response.subtype === "success") settle(undefined, isRecord(response.response) ? response.response : {});
+    else settle(new Error(`Claude headless control request failed: ${String(response.error ?? response.subtype)}`));
+  }
+
+  private abandonPending(state: HeadlessState, cause: string, error?: unknown): void {
+    state.receipt?.reject(new ProviderSubmitFailure(`${cause} before input receipt`, false, error));
+    state.refusalWatch?.settle(false);
+    for (const settle of [...state.controlRequests.values()]) settle(new Error(`${cause} before the control receipt`));
+    state.contextCommand?.settle(new Error(`${cause} before the ${state.contextCommand.kind} boundary`));
+  }
+
+  private async writeUserInput(state: HeadlessState, uuid: string, content: string): Promise<void> {
+    state.child.stdin.write(JSON.stringify({ type: "user", uuid, session_id: "", parent_tool_use_id: null, message: { role: "user", content } }) + "\n");
+    await state.child.stdin.flush();
+  }
+
+  protected onNativeResult(_event: Record<string, unknown>): void {}
+  protected nativeResultHold(_event: Record<string, unknown>): ProviderState | undefined { return undefined; }
+  protected nativeSessionId(process: ManagedProcess): string | undefined { return (process.meta?.headlessState as HeadlessState | undefined)?.sessionId; }
+  protected retireAtBoundary(process: ManagedProcess): void { (process.meta!.headlessState as HeadlessState).stopping = true; }
+
+  /** Replace an idle native process while keeping the runner's handle and reply routing. */
+  protected async replaceAtBoundary(process: ManagedProcess, config: RunnerSpawnConfig): Promise<void> {
+    const state = process.meta?.headlessState as HeadlessState;
+    if (state.turnId || state.contextCommand || state.unknown) throw new Error("Claude rollover requires a confirmed turn boundary");
+    if (await ClaudeHeadlessAdapter.prototype.shutdown.call(this, process, { graceful: true, timeoutMs: 1_000 }) === "failed-to-kill") throw new Error("Claude rollover could not stop the previous native process");
+    const next = await ClaudeHeadlessAdapter.prototype.spawn.call(this, config);
+    const nextState = next.meta!.headlessState as HeadlessState;
+    nextState.replyRoute = state.replyRoute;
+    nextState.mirror = state.mirror;
+    Object.assign(process, next);
+  }
+  protected async onNativeExit(_child: Bun.Subprocess, _code: number, _retired: boolean): Promise<void> {}
+
+  protected emitStatus(event: ProviderStatusUpdate) { if (this.watching) this.status(event); }
+  private async readLines(stream: ReadableStream<Uint8Array>, receive: (line: string) => void) {
+    const input = Readable.fromWeb(stream as unknown as Parameters<typeof Readable.fromWeb>[0]);
+    const lines = createInterface({ input });
+    try {
+      for await (const line of lines) if (line.trim()) {
+        // Consumer failures are not pipe failures and must not kill a healthy child.
+        try { receive(line); } catch (error) { console.error(`[${this.provider} headless] event handler failed: ${error}`); }
+      }
+    }
+    finally { lines.close(); }
+  }
+}