@mgiles/perk 1.0.1

package/extension/worker/worker.ts

@@ -0,0 +1,765 @@
+// The headless stage-drive primitive (`driveStage`).
+//
+// Drives ONE read-write stage (`implement`/`address`) end-to-end on an already-prepared worktree,
+// running the SAME `@mgiles/perk` extension package, with a locked resource set, auto-compaction and
+// auto-retry off, and a budget/timeout watchdog. It seeds the stage's initial prompt, lets the
+// model work (calling perk's real tools), detects the stage's terminal signal, and returns a
+// structured `RunOutcome`. This implements the contract locked in
+// `docs/design/headless-worker.md` §B — the event-stream substrate and the e2e
+// harness consume.
+//
+// Scope here is the in-process drive primitive only. Positioning (worktree create, handoff/plan-ref
+// /plan-body materialization, `run_id` mint) is the cold-door/runner's job and is a PREPARED-
+// WORKTREE input (audit Gap 7): the worker inherits `PERK_RUN_ID` from the env and never re-mints.
+//
+// Inverse of `extension/worker/readOnlySession.ts`: that builds a fully-isolated READ-ONLY child (loads
+// nothing, `["read","grep","find","ls"]`); the worker is the OPPOSITE — read-write defaults + the
+// real perk extension loaded from the worktree's `.pi/settings.json` (cwd-discovery), with the
+// user-global tier locked out via a throwaway `agentDir`.
+
+import { appendFileSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { env } from "node:process";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import {
+  AuthStorage,
+  type CreateAgentSessionRuntimeFactory,
+  type CreateAgentSessionServicesOptions,
+  createAgentSessionFromServices,
+  createAgentSessionRuntime,
+  createAgentSessionServices,
+  ModelRegistry,
+  SessionManager,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { planReadInstruction } from "../doors/lifecycleGates.ts";
+import { ensureRunScratch, type PlanRef, readPlanRef, runEventsPath } from "../substrate/cache.ts";
+import { loadPerkConfig } from "../substrate/config.ts";
+import { render } from "../substrate/prompts.ts";
+import { rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { capForModel } from "./readOnlySession.ts";
+
+// --- contract types (additive-stable; §B of docs/design/headless-worker.md) ---------------------
+
+/** The two read-write stages with `doors.cold_remote: true` (shared/registry.yaml). */
+export type DriveStage = "implement" | "address";
+
+/** Terminal run status (audit §B outcome shape). */
+export type RunStatus = "completed" | "failed" | "aborted" | "budget_exhausted";
+
+/** The first-of terminal signal that ended the drive (audit §B). */
+export type TerminalSignal =
+  | "submit_tool"
+  | "address_resolved"
+  | "agent_idle_incomplete"
+  | "budget"
+  | "external_abort"
+  | "model_error";
+
+/** The budget/timeout watchdog inputs (Gap 2). */
+export interface DriveBudget {
+  maxTurns: number;
+  maxTokens: number;
+  wallClockMs: number;
+}
+
+/**
+ * The structured run outcome (audit §B). **Additive-stable**: later fields may be added; existing
+ * fields keep their meaning. Never thrown — `driveStage` always resolves with one of these.
+ */
+export interface RunOutcome {
+  run_id: string;
+  stage: DriveStage;
+  status: RunStatus;
+  terminal_signal: TerminalSignal;
+  pr: { number: number; url: string } | null;
+  budget: { turns: number; tokens: number; elapsed_ms: number };
+  error: { type: string; message: string; summary: string } | null;
+}
+
+// --- structured run-event stream (§8.12) ----------------------------------------------
+
+/**
+ * The structured run-event stream (contracts §8.12). A small, JSON-serializable,
+ * **additive-stable** discriminated union keyed on `kind` (distinct from `DriveEvent.type`). Every
+ * event carries a monotonic `seq` (0-based) and `t` (elapsed ms, same basis as
+ * `RunOutcome.budget.elapsed_ms`). Future nodes may add variants/fields; existing ones keep meaning.
+ */
+export type RunEvent =
+  | { kind: "run_started"; seq: number; t: number; run_id: string; stage: DriveStage }
+  | { kind: "step_marker"; seq: number; t: number; marker: "wip" | "done"; step: number }
+  | {
+      kind: "tool_outcome";
+      seq: number;
+      t: number;
+      tool: string;
+      ok: boolean;
+      summary: string | null;
+    }
+  | { kind: "run_finished"; seq: number; t: number; outcome: RunOutcome };
+
+/** The injectable delivery seam: default = a run-scoped NDJSON file sink; tests inject an array. */
+export type RunEventSink = (event: RunEvent) => void;
+
+/** Distributive `Omit` so each `RunEvent` variant keeps its own fields when `seq`/`t` are stamped. */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+type RunEventInput = DistributiveOmit<RunEvent, "seq" | "t">;
+
+/** Per-event free-text cap (route-don't-relay): events carry the narrative, not raw tool payloads. */
+export const EVENT_SUMMARY_CAP = 2 * 1024;
+
+export interface DriveStageOptions {
+  /** Absolute path to the already-positioned worktree (Gap 7). */
+  worktree: string;
+  stage: DriveStage;
+  /** The seeded first prompt (see `initialPromptFor`). */
+  initialPrompt: string;
+  /** Explicit model; else the first available from the registry (Gap 5). */
+  model?: Model<Api>;
+  authStorage?: AuthStorage;
+  modelRegistry?: ModelRegistry;
+  budget: DriveBudget;
+  /** External cancellation; OR'd with the budget watchdog. */
+  signal?: AbortSignal;
+}
+
+/**
+ * The offline seam (mirrors `readOnlySession.test.ts`'s `runTask` injection). `createRuntime`
+ * overrides the production runtime factory so tests drive synthetic sessions; `resourceLoaderOptions`
+ * tunes the project-tier load; `now` injects the clock for deterministic `elapsed_ms`.
+ */
+export interface DriveStageDeps {
+  createRuntime?: (opts: DriveStageOptions) => Promise<DriveRuntimeLike>;
+  resourceLoaderOptions?: CreateAgentSessionServicesOptions["resourceLoaderOptions"];
+  now?: () => number;
+  /** The structured run-event sink. Absent ⇒ the default run-scoped NDJSON file sink. */
+  eventSink?: RunEventSink;
+}
+
+// --- structural shapes (kept minimal so pure helpers stay offline-testable) ---------------------
+
+/** The slice of an agent session event the worker reads (structural — see agent-session.d.ts). */
+export interface DriveEvent {
+  type: string;
+  toolName?: string;
+  result?: unknown;
+  isError?: boolean;
+  message?: {
+    role?: string;
+    stopReason?: string;
+    errorMessage?: string;
+    usage?: { input?: number; output?: number };
+    /** Assistant text/content blocks (where `[WIP:n]`/`[DONE:n]` markers live). */
+    content?: unknown;
+  };
+}
+
+/** The session surface the worker drives (structurally satisfied by pi's `AgentSession`). */
+export interface DriveSessionLike {
+  bindExtensions(bindings: unknown): Promise<void>;
+  subscribe(listener: (event: DriveEvent) => void): () => void;
+  prompt(text: string): Promise<void>;
+  abort(): Promise<void>;
+  dispose(): void;
+  sessionManager: { getBranch(): unknown[] };
+}
+
+/** The runtime surface (structurally satisfied by pi's `AgentSessionRuntime`). */
+export interface DriveRuntimeLike {
+  readonly session: DriveSessionLike;
+  dispose(): Promise<void> | void;
+}
+
+/** Mutable counters/captures the subscribe listener accumulates over the drive. */
+export interface DriveCounters {
+  turns: number;
+  tokens: number;
+  submitDetails: Record<string, unknown> | null;
+  resolveDetails: Record<string, unknown> | null;
+  modelError: { message: string } | null;
+}
+
+export function freshCounters(): DriveCounters {
+  return { turns: 0, tokens: 0, submitDetails: null, resolveDetails: null, modelError: null };
+}
+
+/** The natural-idle terminal classification (before watchdog/abort overrides). */
+export interface TerminalVerdict {
+  status: RunStatus;
+  terminal_signal: TerminalSignal;
+  pr: { number: number; url: string } | null;
+  errorType: string | null;
+  errorMessage: string | null;
+}
+
+// --- pure helpers (offline-testable) ------------------------------------------------------------
+
+/** Extract a tool's `details` object from a captured `tool_execution_end.result`; null if absent. */
+function detailsOf(result: unknown): Record<string, unknown> | null {
+  if (result && typeof result === "object" && "details" in result) {
+    const details = (result as { details: unknown }).details;
+    if (details && typeof details === "object") return details as Record<string, unknown>;
+  }
+  return null;
+}
+
+/**
+ * Fold one agent-session event into the running counters (pure). Counts `turn_end` turns, sums
+ * assistant token usage (the `sumAssistantTokens` pattern in objective.ts), captures the `submit`
+ * /`resolve_review_threads` terminal tool details, and records a post-acceptance model error
+ * (assistant `message_end` with `stopReason:"error"`, surfaced with retry off — audit §B #4).
+ */
+export function applyEvent(counters: DriveCounters, event: DriveEvent): void {
+  if (event.type === "turn_end") {
+    counters.turns += 1;
+    const usage = event.message?.usage;
+    if (usage) counters.tokens += Math.max(0, usage.input ?? 0) + Math.max(0, usage.output ?? 0);
+    return;
+  }
+  if (event.type === "tool_execution_end") {
+    if (event.toolName === "submit") counters.submitDetails = detailsOf(event.result);
+    else if (event.toolName === "resolve_review_threads") {
+      counters.resolveDetails = detailsOf(event.result);
+    }
+    return;
+  }
+  if (event.type === "message_end") {
+    if (event.message?.role === "assistant" && event.message.stopReason === "error") {
+      counters.modelError = { message: event.message.errorMessage ?? "model error" };
+    }
+  }
+}
+
+/** True when the budget watchdog should trip from the current counters. */
+export function budgetTripped(counters: DriveCounters, budget: DriveBudget): boolean {
+  return counters.turns >= budget.maxTurns || counters.tokens >= budget.maxTokens;
+}
+
+/**
+ * Classify a natural-idle terminal from the captured state (pure). `modelError` wins (post-
+ * acceptance error, §B #4); else the stage success predicate:
+ *  - implement: a successful `submit` carrying a `pr` → completed/submit_tool;
+ *  - address: `resolve_review_threads` ok AND `last_review_batch` appended → completed/address_resolved;
+ *  - otherwise the agent went idle without completing the stage → failed/agent_idle_incomplete.
+ */
+export function evaluateTerminal(args: {
+  stage: DriveStage;
+  submitDetails: Record<string, unknown> | null;
+  resolveSucceeded: boolean;
+  lastReviewBatchPresent: boolean;
+  modelError: { message: string } | null;
+}): TerminalVerdict {
+  if (args.modelError !== null) {
+    return {
+      status: "failed",
+      terminal_signal: "model_error",
+      pr: null,
+      errorType: "model_error",
+      errorMessage: args.modelError.message,
+    };
+  }
+
+  if (args.stage === "implement") {
+    const pr = extractPr(args.submitDetails);
+    if (args.submitDetails?.ok === true && pr !== null) {
+      // Completion additionally requires the submit to be mergeable: a definitively-
+      // unmergeable PR (merge conflicts unresolved) is NOT done. `mergeable === true`/`null`/
+      // absent all allow completion (fail-open); only a definitive `false` blocks it. On the
+      // happy path the resolver follow-up turns re-submit, overwriting submitDetails with a
+      // mergeable result, so the natural-idle classification then passes.
+      if (args.submitDetails.mergeable === false) {
+        return {
+          status: "failed",
+          terminal_signal: "agent_idle_incomplete",
+          pr: null,
+          errorType: "incomplete",
+          errorMessage:
+            "implement drive went idle with an unmergeable PR (merge conflicts unresolved).",
+        };
+      }
+      return {
+        status: "completed",
+        terminal_signal: "submit_tool",
+        pr,
+        errorType: null,
+        errorMessage: null,
+      };
+    }
+    return {
+      status: "failed",
+      terminal_signal: "agent_idle_incomplete",
+      pr: null,
+      errorType: "incomplete",
+      errorMessage: "implement drive went idle without an opened PR (no successful submit).",
+    };
+  }
+
+  // address
+  if (args.resolveSucceeded && args.lastReviewBatchPresent) {
+    return {
+      status: "completed",
+      terminal_signal: "address_resolved",
+      pr: null,
+      errorType: null,
+      errorMessage: null,
+    };
+  }
+  return {
+    status: "failed",
+    terminal_signal: "agent_idle_incomplete",
+    pr: null,
+    errorType: "incomplete",
+    errorMessage: "address drive went idle without resolving feedback (no last_review_batch).",
+  };
+}
+
+/** Pull a `{ number, url }` PR from a captured `submit` details block; null when malformed. */
+function extractPr(
+  details: Record<string, unknown> | null,
+): { number: number; url: string } | null {
+  if (!details || typeof details.pr !== "object" || details.pr === null) return null;
+  const pr = details.pr as { number?: unknown; url?: unknown };
+  if (typeof pr.number === "number" && typeof pr.url === "string") {
+    return { number: pr.number, url: pr.url };
+  }
+  return null;
+}
+
+/**
+ * Compose the final `RunOutcome` (pure). `run_id` is read from `PERK_RUN_ID` (inherited from
+ * positioning, Gap 7), overridable for tests. On a non-completed status the `error` block carries a
+ * capped `error.summary` (route-don't-relay discipline); a completed status has `error: null`.
+ */
+export function assembleOutcome(args: {
+  stage: DriveStage;
+  verdict: TerminalVerdict;
+  budget: { turns: number; tokens: number; elapsed_ms: number };
+  runId?: string;
+}): RunOutcome {
+  const { verdict } = args;
+  const error =
+    verdict.status === "completed" || verdict.errorMessage === null
+      ? null
+      : {
+          type: verdict.errorType ?? "error",
+          message: verdict.errorMessage,
+          summary: capForModel(verdict.errorMessage).shown,
+        };
+  return {
+    run_id: args.runId ?? env.PERK_RUN_ID ?? "",
+    stage: args.stage,
+    status: verdict.status,
+    terminal_signal: verdict.terminal_signal,
+    pr: verdict.pr,
+    budget: args.budget,
+    error,
+  };
+}
+
+// --- run-event helpers (offline-testable) ---------------------------------------------
+
+/**
+ * Extract `[WIP:n]`/`[DONE:n]` markers from assistant text in **textual appearance order** (pure).
+ * A single combined, case-insensitive regex so interleaved markers (`[WIP:2]` before `[DONE:1]` in
+ * the same message) emit in that order — unlike checkpoints.ts's separate `extractWip/DoneSteps`
+ * lists, which lose cross-marker order. Returns `[]` when there are no markers.
+ */
+export function extractStepMarkers(text: string): { marker: "wip" | "done"; step: number }[] {
+  const out: { marker: "wip" | "done"; step: number }[] = [];
+  for (const m of text.matchAll(/\[(WIP|DONE):(\d+)\]/gi)) {
+    const step = Number(m[2]);
+    if (Number.isFinite(step)) {
+      out.push({ marker: (m[1] ?? "").toLowerCase() === "done" ? "done" : "wip", step });
+    }
+  }
+  return out;
+}
+
+/** Flatten a `DriveEvent`'s assistant `message.content` (string | `{type:'text',text}[]`) to text. */
+export function assistantText(event: DriveEvent): string {
+  const content = event.message?.content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((b) => {
+        const block = b as { type?: string; text?: string };
+        return block.type === "text" && typeof block.text === "string" ? block.text : "";
+      })
+      .filter(Boolean)
+      .join("\n");
+  }
+  return "";
+}
+
+/**
+ * Compute a `tool_outcome` `{ tool, ok, summary }` from a `tool_execution_end` `DriveEvent` (pure).
+ * `ok` = `details.ok === true` when the result carries a `details.ok` boolean, else `!isError`.
+ * `summary` is `null` on success and, on failure, a capped (route-don't-relay) synthesis of the
+ * tool's error message — never the raw tool result.
+ */
+export function toolOutcomeOf(event: DriveEvent): {
+  tool: string;
+  ok: boolean;
+  summary: string | null;
+} {
+  const details = detailsOf(event.result);
+  const ok = typeof details?.ok === "boolean" ? details.ok === true : !event.isError;
+  let summary: string | null = null;
+  if (!ok) {
+    const raw = toolErrorMessage(event);
+    summary = capForModel(raw, EVENT_SUMMARY_CAP).shown;
+  }
+  return { tool: event.toolName ?? "", ok, summary };
+}
+
+/** Best-effort error text for a failed tool (details.error | result string | a generic fallback). */
+function toolErrorMessage(event: DriveEvent): string {
+  const details = detailsOf(event.result);
+  if (details && typeof details.error === "string" && details.error) return details.error;
+  if (typeof event.result === "string" && event.result) return event.result;
+  return `tool ${event.toolName ?? ""} failed`;
+}
+
+/**
+ * The run-event emitter: owns the monotonic `seq` counter and stamps `t = max(0, now() - startMs)`
+ * (same basis as `RunOutcome.budget.elapsed_ms`). Fail-soft: a throwing injected sink is caught and
+ * swallowed so a broken sink never aborts the drive.
+ */
+export function createEventEmitter(sink: RunEventSink, now: () => number, startMs: number) {
+  let seq = 0;
+  return {
+    emit(event: RunEventInput): void {
+      const full = { ...event, seq: seq++, t: Math.max(0, now() - startMs) } as RunEvent;
+      try {
+        sink(full);
+      } catch (err) {
+        console.error(`perk worker: run-event sink threw — ${String(err)}`);
+      }
+    },
+  };
+}
+
+/**
+ * The default run-event sink: a fail-soft NDJSON appender to `runEventsPath(worktree, runId)`. A
+ * **no-op when `runId` is empty** (keeps the offline drive tests, which set no `PERK_RUN_ID`,
+ * write-free). Each append is wrapped so a write error logs and is swallowed.
+ */
+export function defaultEventSink(worktree: string, runId: string): RunEventSink {
+  if (!runId) return () => {};
+  let ensured = false;
+  const path = runEventsPath(worktree, runId);
+  return (event: RunEvent): void => {
+    try {
+      if (!ensured) {
+        ensureRunScratch(worktree, runId);
+        ensured = true;
+      }
+      appendFileSync(path, `${JSON.stringify(event)}\n`, "utf8");
+    } catch (err) {
+      console.error(`perk worker: run-event sink write failed — ${String(err)}`);
+    }
+  };
+}
+
+/**
+ * Re-derive the stage's initial prompt from the plan-ref — the TS twin of
+ * `perk/run/launch.py._implement_prompt`/`_address_prompt`. INVARIANT: textual parity with the Python
+ * plane (asserted reciprocally in `worker.test.ts` + `tests/test_worker_prompt_parity.py`); the
+ * resolved skill-binding suffix is delivered by the cold door, not here. Returns
+ * `null` when there is no plan-ref (nothing to prime).
+ *
+ * The implement primer's wording lives in the canonical template `prompts/stages/implement.md`,
+ * rendered by the shared seam (contracts.md §8.31); branching stays in code — only the `read_cmd`
+ * var differs. This implement output is byte-identical to the warm `implementHandoffPrompt`.
+ *
+ * The `address` wording lives in the shared canonical template `prompts/stages/address/action.md`
+ * rendered via the cross-plane render seam (contracts.md §8.31); the worker has no preview path
+ * (preview is a warm/cold flag only), so it always renders the action body. The classifier
+ * present/absent split builds the `model_clause` render var in code.
+ */
+export function initialPromptFor(
+  stage: DriveStage,
+  planRef: PlanRef | null,
+  classifierModel?: string,
+): string | null {
+  if (planRef === null) return null;
+  const provider = String(planRef.provider ?? "");
+  const prId = String(planRef.pr_id ?? "");
+  const url = String(planRef.url ?? "");
+  if (stage === "implement") {
+    const readCmd = planReadInstruction(provider, prId, url);
+    return render("stages/implement.md", { provider, pr_id: prId, url, read_cmd: readCmd });
+  }
+  // address
+  const modelClause = classifierModel
+    ? `, passing \`model: "${classifierModel}"\` on that call (the configured [subagents] review-classifier model)`
+    : "";
+  return render("stages/address/action.md", {
+    provider,
+    pr_id: prId,
+    url,
+    model_clause: modelClause,
+  });
+}
+
+// --- bind / subscribe management (Gap 1) --------------------------------------------------------
+
+/** The binding the worker applies to every (re)bound session: headless (`hasUI === false`). */
+export function headlessBinding(): {
+  uiContext: undefined;
+  mode: "json";
+  onError: (err: unknown) => void;
+} {
+  return {
+    uiContext: undefined,
+    mode: "json",
+    onError: (err: unknown) => console.error(`perk worker: extension error — ${String(err)}`),
+  };
+}
+
+/**
+ * Manage the bind+subscribe lifecycle across session replacement (Gap 1). `bind(target)` binds the
+ * perk extension and attaches the terminal/budget listener; calling it again (after a runtime
+ * replacement) unsubscribes the prior listener first so events are never double-counted. A mid-drive
+ * replacement is not expected on the happy path (the prompt instructs `/submit`, never `/implement`;
+ * `lifecycleGates.newSession` is `hasUI`-guarded; objective compaction is inert with no active
+ * objective) — so an observed `rebind()` is a loud structured-log error.
+ */
+export function createBindManager(binding: unknown, listener: (event: DriveEvent) => void) {
+  let unsubscribe: (() => void) | null = null;
+  return {
+    async bind(target: DriveSessionLike): Promise<void> {
+      if (unsubscribe) unsubscribe();
+      await target.bindExtensions(binding);
+      unsubscribe = target.subscribe(listener);
+    },
+    dispose(): void {
+      if (unsubscribe) {
+        unsubscribe();
+        unsubscribe = null;
+      }
+    },
+  };
+}
+
+// --- the production runtime factory -------------------------------------------------------------
+
+/**
+ * Build the asymmetric runtime: `cwd = worktree` (project tier — perk's `@mgiles/perk` extension via the
+ * managed `.pi/settings.json`, the managed `AGENTS.md`/`APPEND_SYSTEM.md`) and `agentDir = throwaway`
+ * (user-global tier OUT), compaction-off + retry-off settings, env-var/registry auth+model (Gap 5).
+ * No `tools` allowlist — read-write defaults + extension tools. The `createAgentSessionServices`
+ * factory builds the `DefaultResourceLoader` internally from `cwd`/`agentDir` (recipe correction #1).
+ */
+async function defaultCreateRuntime(
+  opts: DriveStageOptions,
+  deps: DriveStageDeps,
+  resolved: { authStorage: AuthStorage; modelRegistry: ModelRegistry; model: Model<Api> },
+): Promise<DriveRuntimeLike> {
+  const agentDir = mkdtempSync(join(tmpdir(), "perk-worker-agent-"));
+  const settingsManager = SettingsManager.inMemory({
+    compaction: { enabled: false },
+    retry: { enabled: false },
+  });
+  const factory: CreateAgentSessionRuntimeFactory = async (factoryOpts) => {
+    const services = await createAgentSessionServices({
+      cwd: factoryOpts.cwd,
+      agentDir: factoryOpts.agentDir,
+      authStorage: resolved.authStorage,
+      settingsManager,
+      modelRegistry: resolved.modelRegistry,
+      resourceLoaderOptions: deps.resourceLoaderOptions,
+    });
+    const result = await createAgentSessionFromServices({
+      services,
+      sessionManager: factoryOpts.sessionManager,
+      sessionStartEvent: factoryOpts.sessionStartEvent,
+      model: resolved.model,
+    });
+    return { ...result, services, diagnostics: services.diagnostics };
+  };
+  const runtime = await createAgentSessionRuntime(factory, {
+    cwd: opts.worktree,
+    agentDir,
+    sessionManager: SessionManager.create(opts.worktree),
+  });
+  return runtime as unknown as DriveRuntimeLike;
+}
+
+// --- model/auth resolution (Gap 5) --------------------------------------------------------------
+
+interface ResolvedAuth {
+  authStorage: AuthStorage;
+  modelRegistry: ModelRegistry;
+  model: Model<Api>;
+}
+
+/** Resolve auth + model; returns null (never throws) when no model is available. */
+function resolveAuth(opts: DriveStageOptions): ResolvedAuth | null {
+  const authStorage = opts.authStorage ?? AuthStorage.create();
+  const modelRegistry = opts.modelRegistry ?? ModelRegistry.create(authStorage);
+  const model = opts.model ?? modelRegistry.getAvailable()[0];
+  if (!model) return null;
+  return { authStorage, modelRegistry, model };
+}
+
+// --- the drive primitive ------------------------------------------------------------------------
+
+/**
+ * Drive one stage to terminal and return a structured `RunOutcome` — never throws (fail-soft like
+ * `submitPr`). Seeds `initialPrompt`, races the driving `prompt()` against the budget watchdog and
+ * the external `signal`, classifies the terminal at idle, and disposes the runtime in `finally`.
+ */
+export async function driveStage(
+  opts: DriveStageOptions,
+  deps: DriveStageDeps = {},
+): Promise<RunOutcome> {
+  const now = deps.now ?? Date.now;
+  const startMs = now();
+  const counters = freshCounters();
+  const elapsed = (): number => Math.max(0, now() - startMs);
+
+  // Structured run-event stream: resolve the sink + run_id once, build the emitter, and
+  // route every terminal exit through `finish` so exactly one `run_finished` is emitted per drive.
+  const runId = env.PERK_RUN_ID ?? "";
+  const sink = deps.eventSink ?? defaultEventSink(opts.worktree, runId);
+  const emitter = createEventEmitter(sink, now, startMs);
+  const finish = (verdict: TerminalVerdict): RunOutcome => {
+    const outcome = assembleOutcome({
+      stage: opts.stage,
+      verdict,
+      budget: { turns: counters.turns, tokens: counters.tokens, elapsed_ms: elapsed() },
+    });
+    emitter.emit({ kind: "run_finished", outcome });
+    return outcome;
+  };
+
+  const resolved = resolveAuth(opts);
+  if (resolved === null && !deps.createRuntime) {
+    // A zero-turn run is still observable: emit a `run_started` + `run_finished` pair.
+    emitter.emit({ kind: "run_started", run_id: runId, stage: opts.stage });
+    return finish({
+      status: "failed",
+      terminal_signal: "model_error",
+      pr: null,
+      errorType: "no_model",
+      errorMessage: "no model available — set an API key (e.g. ANTHROPIC_API_KEY) or pass a model.",
+    });
+  }
+
+  let terminationReason: "natural" | "budget" | "abort" = "natural";
+  let settled = false;
+  let runtime: DriveRuntimeLike | null = null;
+  const bindManager = createBindManager(headlessBinding(), (event) => {
+    applyEvent(counters, event);
+    if (event.type === "turn_end") {
+      // Emit this turn's `[WIP:n]`/`[DONE:n]` markers in textual appearance order (one event each).
+      for (const m of extractStepMarkers(assistantText(event))) {
+        emitter.emit({ kind: "step_marker", marker: m.marker, step: m.step });
+      }
+      if (budgetTripped(counters, opts.budget)) trip("budget");
+    } else if (event.type === "tool_execution_end") {
+      const o = toolOutcomeOf(event);
+      emitter.emit({ kind: "tool_outcome", tool: o.tool, ok: o.ok, summary: o.summary });
+    }
+  });
+
+  function trip(reason: "budget" | "abort"): void {
+    if (settled) return;
+    if (terminationReason === "natural") terminationReason = reason;
+    if (runtime) void runtime.session.abort();
+  }
+
+  const onSignal = (): void => trip("abort");
+
+  try {
+    runtime = deps.createRuntime
+      ? await deps.createRuntime(opts)
+      : // biome-ignore lint/style/noNonNullAssertion: resolved is non-null on the production path.
+        await defaultCreateRuntime(opts, deps, resolved!);
+
+    let boundSession = runtime.session;
+    await bindManager.bind(boundSession);
+    emitter.emit({ kind: "run_started", run_id: runId, stage: opts.stage });
+
+    // Budget/abort wiring (Gap 2): wall-clock timer + external signal both trip → session.abort().
+    const timer = setTimeout(() => trip("budget"), opts.budget.wallClockMs);
+    if (opts.signal) {
+      if (opts.signal.aborted) onSignal();
+      else opts.signal.addEventListener("abort", onSignal, { once: true });
+    }
+
+    try {
+      await runtime.session.prompt(opts.initialPrompt);
+    } finally {
+      clearTimeout(timer);
+      opts.signal?.removeEventListener("abort", onSignal);
+      settled = true;
+    }
+
+    // Defensive rebind (Gap 1): the happy path never replaces the session; a replacement is loud.
+    if (runtime.session !== boundSession) {
+      console.error("perk worker: unexpected mid-drive session replacement — rebinding listener.");
+      boundSession = runtime.session;
+      await bindManager.bind(boundSession);
+    }
+
+    const verdict = classify(opts, counters, terminationReason, boundSession);
+    return finish(verdict);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return finish({
+      status: "failed",
+      terminal_signal: "model_error",
+      pr: null,
+      errorType: "drive_error",
+      errorMessage: `headless drive failed: ${message}`,
+    });
+  } finally {
+    bindManager.dispose();
+    if (runtime) await runtime.dispose();
+  }
+}
+
+/** Pick the terminal verdict: watchdog/abort override the natural-idle classification. */
+function classify(
+  opts: DriveStageOptions,
+  counters: DriveCounters,
+  terminationReason: "natural" | "budget" | "abort",
+  session: DriveSessionLike,
+): TerminalVerdict {
+  if (terminationReason === "budget") {
+    return {
+      status: "budget_exhausted",
+      terminal_signal: "budget",
+      pr: null,
+      errorType: "budget",
+      errorMessage: "budget exhausted (turns/tokens/wall-clock) — drive aborted.",
+    };
+  }
+  if (terminationReason === "abort") {
+    return {
+      status: "aborted",
+      terminal_signal: "external_abort",
+      pr: null,
+      errorType: "external_abort",
+      errorMessage: "drive aborted by external signal.",
+    };
+  }
+  const lastReviewBatchPresent =
+    rebuildWorkflowState(session.sessionManager.getBranch() as never).last_review_batch != null;
+  return evaluateTerminal({
+    stage: opts.stage,
+    submitDetails: counters.submitDetails,
+    resolveSucceeded: counters.resolveDetails?.ok === true,
+    lastReviewBatchPresent,
+    modelError: counters.modelError,
+  });
+}
+
+/** Convenience: re-derive the initial prompt for a prepared worktree (reads its `cache.plan-ref`). */
+export function initialPromptForWorktree(worktree: string, stage: DriveStage): string | null {
+  const classifierModel = loadPerkConfig(worktree).subagents["review-classifier"];
+  return initialPromptFor(stage, readPlanRef(worktree), classifierModel);
+}