@humwick/runner 0.0.0-stage → 0.130.0

package/src/adapters/claude-exit.ts

@@ -0,0 +1,290 @@
+// #1647 — the ONE module allowed to type Claude's exit command, or the Enter that
+// answers its exit-confirmation dialog, into a managed pane.
+//
+// A 13.4h coordinator was destroyed when the runner's graceful-shutdown path typed
+// `/exit` into a pane whose turn was LIVE (a turn had started 18s earlier and never
+// ended), and the shutdown grace loop then pressed Enter on the resulting
+// "Background work is running — 1. Exit anyway" modal. The shutdown request itself
+// was legitimate and audited; what was missing was any correlation between the
+// request and the state of the process it was about to kill.
+//
+// Two structural guarantees live here, and both are enforced at RUNTIME, not by
+// convention:
+//
+//  1. CAPABILITY. Neither writer takes a session name. Both take a ClaudeExitGrant,
+//     and a grant can only come out of `authorizeClaudeGracefulExit`, which in turn
+//     demands a shutdown intent minted by an explicit lifecycle command. Grants are
+//     tracked in a module-private WeakSet, so a forged object literal is rejected —
+//     a detector cannot reach these functions even by fabricating the type.
+//
+//  2. CORRELATION. Authorization requires the observed provider epoch, process
+//     identity, tmux session, provider session id and turn state to match the
+//     intent EXACTLY, with positive evidence the turn has ended. Anything else —
+//     a live turn, an UNKNOWN turn, a stale intent, a re-used intent — is denied.
+//     Fail-closed in every direction: absent evidence is never treated as consent.
+//
+// `claude-exit.guard.test.ts` fails the build if any pane-detector module can reach
+// this file through the import graph.
+import { isClaudeExitConfirmationDialog } from "@humwick/sdk/claude-exit-dialog";
+import { tmuxCommand } from "@humwick/sdk/tmux-utils";
+import { spawnSyncBounded } from "../bounded-spawn-sync";
+import { captureTmuxPane, submitTextToTmux } from "./claude-tmux";
+
+export const CLAUDE_EXIT_COMMAND = "/exit";
+
+// A shutdown intent describes the process the operator asked to stop. It stops
+// being usable once the request is older than this, so a shutdown that queued
+// behind a slow teardown can never fire against a later turn of the same session.
+export const CLAUDE_SHUTDOWN_INTENT_TTL_MS = 60_000;
+
+// What the pane/probe says about the correlated turn. "unknown" is NOT "probably
+// idle" — it is the absence of evidence, and it denies exactly like "live".
+export type ClaudeTurnState = "ended" | "live" | "unknown";
+
+/**
+ * The audited lifecycle request, pinned to the exact process it was issued for.
+ * Minted only from an explicit shutdown/restart command — never from a detector.
+ */
+export interface ClaudeShutdownIntent {
+  /** Runner provider epoch: bumped on every provider spawn, so a post-restart process never matches. */
+  readonly epoch: number;
+  /** OS pid of the managed process at request time (undefined for tmux-managed panes). */
+  readonly pid?: number;
+  /** Claude's own process-start marker from the intrinsic session probe. */
+  readonly procStart: string | null;
+  readonly sessionName: string;
+  /** Claude's session id from the intrinsic probe; null when the probe is unavailable. */
+  readonly providerSessionId: string | null;
+  /**
+   * Identity of the conversation the request was accepted against. Claude's intrinsic
+   * probe exposes no per-turn id, so this is the finest granularity actually available
+   * (see `claudeTurnKey`) and it catches process/session replacement, not turn rollover.
+   * The "don't type into a live turn" guarantee therefore rests on the `turn` gate
+   * below, NOT on this field — stated plainly so nobody reads more safety into it.
+   */
+  readonly turnKey: string;
+  readonly issuedAt: number;
+}
+
+/** Live facts about the pane, sampled at the moment we consider typing `/exit`. */
+export interface ClaudeExitObservation {
+  readonly epoch: number;
+  readonly pid?: number;
+  readonly procStart: string | null;
+  readonly sessionName: string;
+  readonly providerSessionId: string | null;
+  readonly turn: ClaudeTurnState;
+  readonly turnKey: string;
+  readonly now: number;
+}
+
+export type ClaudeExitDenial =
+  | "intent-consumed"
+  | "intent-stale"
+  | "epoch-mismatch"
+  | "process-identity-mismatch"
+  | "session-mismatch"
+  | "provider-session-mismatch"
+  | "provider-session-unknown"
+  | "turn-changed"
+  | "turn-live"
+  | "turn-unknown";
+
+// Denials that no amount of further polling can clear: the request does not describe
+// the process in front of us, or it has already been spent. The shutdown loop stops
+// waiting on these and goes straight to out-of-band termination. Everything else
+// ("turn-live", "turn-unknown", "provider-session-unknown") is a not-yet, so the loop
+// keeps sampling until the grace window closes.
+const PERMANENT_DENIALS: ReadonlySet<ClaudeExitDenial> = new Set([
+  "intent-consumed", "intent-stale", "epoch-mismatch",
+  "process-identity-mismatch", "session-mismatch", "provider-session-mismatch", "turn-changed",
+]);
+
+export function claudeExitDenialIsPermanent(reason: ClaudeExitDenial): boolean {
+  return PERMANENT_DENIALS.has(reason);
+}
+
+export type ClaudeExitDecision =
+  | { readonly authorized: true; readonly grant: ClaudeExitGrant }
+  | { readonly authorized: false; readonly reason: ClaudeExitDenial };
+
+declare const CLAUDE_EXIT_GRANT: unique symbol;
+
+/**
+ * One-shot capability to type `/exit` into one specific pane, and to answer the
+ * ONE dialog that `/exit` raises. Opaque and unforgeable: the brand blocks it at
+ * compile time and the ISSUED registry blocks it at runtime.
+ */
+export interface ClaudeExitGrant {
+  readonly [CLAUDE_EXIT_GRANT]: true;
+  readonly sessionName: string;
+  readonly socketName?: string;
+  readonly authorizedAt: number;
+}
+
+interface GrantState {
+  /** Set once `/exit` has actually been written through this grant. */
+  exitSubmittedAt?: number;
+  /** True when a dialog was already on screen BEFORE our `/exit` — it is not ours to answer. */
+  dialogPredatesExit: boolean;
+  answeredAt?: number;
+}
+
+// Module-private. Nothing outside this file can add to either, which is what makes
+// a fabricated grant object inert rather than merely type-invalid.
+const ISSUED_GRANTS = new WeakSet<ClaudeExitGrant>();
+const GRANT_STATE = new WeakMap<ClaudeExitGrant, GrantState>();
+const CONSUMED_INTENTS = new WeakSet<ClaudeShutdownIntent>();
+
+/** Record the audited lifecycle request. Minting does not authorize anything by itself. */
+export function mintClaudeShutdownIntent(facts: Omit<ClaudeShutdownIntent, "issuedAt"> & { issuedAt?: number }): ClaudeShutdownIntent {
+  return {
+    epoch: facts.epoch,
+    ...(facts.pid === undefined ? {} : { pid: facts.pid }),
+    procStart: facts.procStart,
+    sessionName: facts.sessionName,
+    providerSessionId: facts.providerSessionId,
+    turnKey: facts.turnKey,
+    issuedAt: facts.issuedAt ?? Date.now(),
+  };
+}
+
+/**
+ * The whole policy, as a pure decision over (intent, observation). Kept separate
+ * from grant minting so the rules are unit-testable without touching tmux.
+ */
+export function decideClaudeGracefulExit(
+  intent: ClaudeShutdownIntent,
+  observed: ClaudeExitObservation,
+  consumed: boolean,
+): ClaudeExitDenial | undefined {
+  if (consumed) return "intent-consumed";
+  if (observed.now - intent.issuedAt > CLAUDE_SHUTDOWN_INTENT_TTL_MS) return "intent-stale";
+  if (observed.epoch !== intent.epoch) return "epoch-mismatch";
+  if (observed.sessionName !== intent.sessionName) return "session-mismatch";
+  // pid/procStart: only compare what BOTH sides know. A pid that changed under us is
+  // decisive; a pid nobody recorded cannot be, so it falls through to the turn gate.
+  if (intent.pid !== undefined && observed.pid !== undefined && intent.pid !== observed.pid) return "process-identity-mismatch";
+  if (intent.procStart !== null && observed.procStart !== null && intent.procStart !== observed.procStart) return "process-identity-mismatch";
+  // The provider session id is the strongest identity we have, so absence of it at
+  // exit time is disqualifying rather than ignorable: without it we cannot tell this
+  // session from its successor.
+  if (observed.providerSessionId === null) return "provider-session-unknown";
+  if (intent.providerSessionId !== null && intent.providerSessionId !== observed.providerSessionId) return "provider-session-mismatch";
+  // #1647's actual failure: the pane was mid-stream. Only POSITIVE end-of-turn
+  // evidence authorizes typing into it.
+  if (observed.turn === "live") return "turn-live";
+  if (observed.turn !== "ended") return "turn-unknown";
+  // An "ended" verdict for a DIFFERENT turn than the one we were asked about means a
+  // new turn started and finished since; the request no longer describes reality.
+  if (observed.turnKey !== intent.turnKey) return "turn-changed";
+  return undefined;
+}
+
+/**
+ * Consume the intent and mint a grant, or explain the denial. One-shot: the intent
+ * is burned on the first authorization, so a retry loop cannot type `/exit` twice.
+ */
+export function authorizeClaudeGracefulExit(
+  intent: ClaudeShutdownIntent,
+  observed: ClaudeExitObservation,
+  socketName?: string,
+): ClaudeExitDecision {
+  const denial = decideClaudeGracefulExit(intent, observed, CONSUMED_INTENTS.has(intent));
+  if (denial) return { authorized: false, reason: denial };
+  CONSUMED_INTENTS.add(intent);
+  const grant = {
+    sessionName: intent.sessionName,
+    ...(socketName === undefined ? {} : { socketName }),
+    authorizedAt: observed.now,
+  } as ClaudeExitGrant;
+  ISSUED_GRANTS.add(grant);
+  GRANT_STATE.set(grant, { dialogPredatesExit: false });
+  return { authorized: true, grant };
+}
+
+export interface ClaudeExitWriterDeps {
+  capture?: (sessionName: string, socketName?: string) => string;
+  submit?: (sessionName: string, text: string, socketName?: string) => Promise<void>;
+  sendEnter?: (sessionName: string, socketName?: string) => void;
+}
+
+function grantStateOrThrow(grant: ClaudeExitGrant): GrantState {
+  // The runtime half of the capability check. A detector that fabricates
+  // `{} as ClaudeExitGrant` to satisfy the compiler still lands here and throws.
+  if (!ISSUED_GRANTS.has(grant)) throw new Error("claude exit: grant was not issued by authorizeClaudeGracefulExit");
+  const state = GRANT_STATE.get(grant);
+  if (!state) throw new Error("claude exit: grant has no state");
+  return state;
+}
+
+export type ClaudeExitSubmitResult = "submitted" | "already-submitted" | "dialog-already-open";
+
+/**
+ * Type `/exit` into the granted pane, once.
+ *
+ * Snapshots the pane first: if an exit dialog is ALREADY on screen we neither type
+ * nor later answer it, because a modal we did not cause is not ours to dismiss —
+ * that is the "causally bound" half of the guard.
+ */
+export async function submitClaudeExitCommand(grant: ClaudeExitGrant, deps: ClaudeExitWriterDeps = {}): Promise<ClaudeExitSubmitResult> {
+  const state = grantStateOrThrow(grant);
+  if (state.exitSubmittedAt !== undefined) return "already-submitted";
+  const capture = deps.capture ?? captureTmuxPane;
+  const submit = deps.submit ?? submitTextToTmux;
+  let pane: string | undefined;
+  try {
+    pane = capture(grant.sessionName, grant.socketName);
+  } catch {
+    // Capture failure is not evidence of a clean pane. Fail closed and let the
+    // caller's out-of-band kill-session backstop terminate the process instead.
+    state.dialogPredatesExit = true;
+    return "dialog-already-open";
+  }
+  if (isClaudeExitConfirmationDialog(pane)) {
+    state.dialogPredatesExit = true;
+    return "dialog-already-open";
+  }
+  await submit(grant.sessionName, CLAUDE_EXIT_COMMAND, grant.socketName);
+  state.exitSubmittedAt = Date.now();
+  return "submitted";
+}
+
+export type ClaudeExitConfirmResult = "confirmed" | "no-dialog" | "exit-not-submitted" | "dialog-predates-exit" | "already-answered";
+
+/**
+ * Answer the exit-confirmation dialog raised by OUR `/exit`, once.
+ *
+ * Every non-"confirmed" result means no key was written. In particular the Enter is
+ * unreachable unless this same grant already submitted `/exit` and no dialog was
+ * open beforehand — so it can only ever dismiss the modal it caused.
+ */
+export function confirmClaudeExitDialogUnderGrant(grant: ClaudeExitGrant, deps: ClaudeExitWriterDeps = {}): ClaudeExitConfirmResult {
+  const state = grantStateOrThrow(grant);
+  if (state.dialogPredatesExit) return "dialog-predates-exit";
+  if (state.exitSubmittedAt === undefined) return "exit-not-submitted";
+  if (state.answeredAt !== undefined) return "already-answered";
+  const capture = deps.capture ?? captureTmuxPane;
+  let pane: string;
+  try {
+    pane = capture(grant.sessionName, grant.socketName);
+  } catch {
+    return "no-dialog";
+  }
+  if (!isClaudeExitConfirmationDialog(pane)) return "no-dialog";
+  const sendEnter = deps.sendEnter ?? defaultSendEnter;
+  try {
+    sendEnter(grant.sessionName, grant.socketName);
+  } catch {
+    // Best-effort: the caller's kill-session backstop still guarantees termination.
+    return "no-dialog";
+  }
+  state.answeredAt = Date.now();
+  return "confirmed";
+}
+
+function defaultSendEnter(sessionName: string, socketName?: string): void {
+  spawnSyncBounded(tmuxCommand(socketName, "send-keys", "-t", sessionName, "Enter"), {
+    stdin: "ignore", stdout: "ignore", stderr: "ignore",
+  });
+}

package/src/adapters/claude-headless-mirror.ts

@@ -0,0 +1,88 @@
+import { isRecord, type ContextState } from "@humwick/sdk";
+import type { ProviderSessionEvent } from "../adapter";
+import { freshContextState, providerContextState } from "../transcript-context";
+import { claudeAssistantSteps, claudeToolResults, sumUsageTokens, turnStepEvent, type TranscriptMessage, type TurnStep } from "./claude-transcript";
+
+/**
+ * Turns the root session's stream-json events into session-mirror steps and context usage (#2771).
+ * A tool row opens `running` on its tool_use and settles in place (stepId = tool_use id) on its tool_result.
+ */
+export class ClaudeHeadlessMirror {
+  private readonly openTools = new Map<string, TurnStep>();
+  private readonly contextWindows = new Map<string, number>();
+  private usage?: { tokensUsed: number; model?: string; at: number };
+  private clearedAt?: number;
+
+  observe(event: Record<string, unknown>, turnId: string | undefined): ProviderSessionEvent[] {
+    // Subagent events carry their parent's tool_use id; like transcript sidechains they stay out of the root mirror.
+    if (event.parent_tool_use_id) return [];
+    const message = isRecord(event.message) ? event.message as TranscriptMessage : undefined;
+    const occurredAt = typeof event.timestamp === "string" ? Date.parse(event.timestamp) || undefined : undefined;
+    if (event.type === "assistant") {
+      this.noteUsage(message, occurredAt);
+      // Claude's synthetic API-error message is a transcript row, not model output.
+      const diagnostic = event.is_api_error_message === true;
+      return claudeAssistantSteps(message, occurredAt).map((step) => {
+        if (step.type !== "tool" || !step.toolUseId) return stepEvent(step, turnId, undefined, diagnostic);
+        this.openTools.set(step.toolUseId, step);
+        return stepEvent(step, turnId, "running");
+      });
+    }
+    if (event.type === "user") {
+      return claudeToolResults(message).flatMap(({ toolUseId, isError }) => {
+        const step = this.openTools.get(toolUseId);
+        if (!step) return [];
+        this.openTools.delete(toolUseId);
+        return [stepEvent(step, turnId, isError ? "failed" : "completed")];
+      });
+    }
+    if (event.type !== "result") return [];
+    if (isRecord(event.modelUsage)) {
+      for (const [model, usage] of Object.entries(event.modelUsage)) {
+        if (isRecord(usage) && typeof usage.contextWindow === "number" && usage.contextWindow > 0) this.contextWindows.set(model, usage.contextWindow);
+      }
+    }
+    // A tool with no result by the turn's end was cut off (interrupt or abort).
+    const cut = [...this.openTools.values()].map((step) => stepEvent(step, turnId, "cancelled"));
+    this.openTools.clear();
+    return cut;
+  }
+
+  /** Context after a compaction: its reported post size, or unknown until the next turn. */
+  resetContext(tokensUsed?: number): void {
+    this.usage = tokensUsed && tokensUsed > 0 ? { tokensUsed, model: this.usage?.model, at: Date.now() } : undefined;
+    this.clearedAt = undefined;
+  }
+
+  /** After a clear the context is explicitly empty; omitting it would leave the card on the old usage. */
+  clearContext(): void {
+    this.usage = undefined;
+    this.clearedAt = Date.now();
+  }
+
+  context(): ContextState | undefined {
+    const usage = this.usage;
+    const onlyWindow = this.contextWindows.size === 1 ? [...this.contextWindows.values()][0] : undefined;
+    if (!usage) return this.clearedAt ? freshContextState(this.clearedAt, onlyWindow) : undefined;
+    const window = (usage.model ? this.contextWindows.get(usage.model) : undefined) ?? onlyWindow;
+    return window ? providerContextState(usage.tokensUsed, window, usage.at) : undefined;
+  }
+
+  private noteUsage(message: TranscriptMessage | undefined, occurredAt: number | undefined): void {
+    const tokensUsed = message?.usage ? sumUsageTokens(message.usage) : undefined;
+    // A synthetic API-error message reports zero usage; that is no reading, not an empty context.
+    if (!tokensUsed) return;
+    this.usage = { tokensUsed, model: typeof message?.model === "string" ? message.model : undefined, at: occurredAt ?? Date.now() };
+    this.clearedAt = undefined;
+  }
+}
+
+function stepEvent(step: TurnStep, turnId: string | undefined, status?: ProviderSessionEvent["status"], diagnostic = false): ProviderSessionEvent {
+  return {
+    ...turnStepEvent(step, turnId),
+    ...(status ? { status } : {}),
+    ...(status === "running" ? { streaming: true } : {}),
+    ...(step.toolUseId ? { stepId: step.toolUseId } : {}),
+    ...(diagnostic ? { diagnostic: true } : {}),
+  };
+}

package/src/adapters/claude-headless-refusal.ts

@@ -0,0 +1,51 @@
+import type { ProviderState } from "@humwick/sdk";
+import { buildProviderRefusalHold, isProviderOverload, isProviderThrottle, isProviderUsageLimit, isProxyAuthFailure, parseClaudeRateLimitPane } from "../rate-limit";
+
+/** What Claude's native error result says about a refused turn (#2771). */
+export interface ClaudeTurnError {
+  /** The synthetic API-error assistant message's `error` class (rate_limit, overloaded, ...). */
+  error?: string;
+  status?: number;
+  text: string;
+}
+
+// The classes the interactive StopFailure hook holds on (stop-failure.sh); anything else stays a terminal error.
+const HOLD_ERRORS = new Set(["rate_limit", "overloaded", "server_error", "api_error"]);
+
+/** The native error an assistant event carries when the API refused the request. */
+export function claudeApiErrorOf(event: Record<string, unknown>): string | undefined {
+  return event.type === "assistant" && event.is_api_error_message === true && typeof event.error === "string" ? event.error : undefined;
+}
+
+/** Error text is authoritative even when Claude omits its API-error metadata (#3544). */
+export function claudeTurnError(result: Record<string, unknown>, error: string | undefined): ClaudeTurnError | undefined {
+  if (result.is_error !== true && result.terminal_reason !== "api_error" && typeof result.api_error_status !== "number" && error === undefined) return undefined;
+  const text = typeof result.result === "string" ? result.result : "";
+  const textStatus = /^API Error:\s*(\d{3})\b/i.exec(text);
+  const status = typeof result.api_error_status === "number" ? result.api_error_status : textStatus ? Number(textStatus[1]) : undefined;
+  return { error: error ?? (/\boverload(?:ed)?\b/i.test(text) ? "overloaded" : undefined), status, text };
+}
+
+/**
+ * The provider-neutral rate-limit hold for a refused turn (throttle, quota wall or overload), or
+ * undefined for an error a hold cannot clear (auth, billing, invalid request).
+ */
+export function claudeRefusalHold(turn: ClaudeTurnError, source: string): ProviderState | undefined {
+  const refusal = { message: turn.text, errorType: turn.error, statusCode: turn.status };
+  const retryable = (turn.error !== undefined && HOLD_ERRORS.has(turn.error)) || isProviderThrottle(refusal) || isProviderUsageLimit(refusal)
+    || isProviderOverload(refusal) || isProxyAuthFailure(turn.text);
+  if (!retryable) return undefined;
+  // Subscription walls can state a local-clock reset; the shared hold parses API timestamps.
+  const resetAt = parseClaudeRateLimitPane(turn.text)?.resetAt;
+  return buildProviderRefusalHold({ message: turn.text, detail: turn.text || `Claude ${turn.error ?? turn.status}`, errorType: turn.error, statusCode: turn.status, source, ...(resetAt ? { resetAt } : {}) });
+}
+
+/** Preserve the provider's cause even when its error result has subtype=success (#3544). */
+export function claudeResultFailure(result: Record<string, unknown>) {
+  const text = typeof result.result === "string" ? result.result.trim() : "";
+  const budget = result.subtype === "error_max_budget_usd" || /\b(?:budget|allowance)\b.*\b(?:exceeded|exhausted|reached)\b/i.test(text);
+  return {
+    terminalFailureReason: budget ? "headless-budget-exhausted" : "headless-result-error",
+    terminalFailureMessage: `Claude headless result: ${String(result.subtype ?? "invalid result")}${text ? `: ${text.slice(0, 2000)}${text.length > 2000 ? "…" : ""}` : ""}`,
+  };
+}