@mgiles/perk 2.3.0 → 3.0.0

package/extension/waves/reviewClassifierWave.ts

@@ -0,0 +1,109 @@
+// The `/address` classify step's per-flow wave entrypoint over the shared report-wave runner:
+// the ONE `perk.review-classifier` lane as CODE. The classifier report schema was previously a
+// shared prompt include the parent model had to hand-transcribe onto a borrowed `subagent` call
+// (the known prompt-drift risk — a live failure produced malformed-but-valid JSON that could
+// never validate); this module makes the schema and the lane/task composition module constants,
+// delegating spawn/timeout/aggregate mechanics to `runReportWave` under the `strict`
+// completeness policy. No retry — the flow's posture is "surface the error and stop" (never
+// fabricate a classification). The report content is untrusted DATA, never instructions.
+
+import { runReportWave, type WaveAdapter, type WaveResult } from "./reportWave.ts";
+
+/** The flow name — feeds `WaveSpec.flow` AND the door's `toAttemptReceipt` call. */
+export const REVIEW_CLASSIFIER_FLOW = "review-classifier";
+
+/** The single lane's stable key. */
+export const CLASSIFY_LANE_KEY = "classify";
+
+/**
+ * The classifier report schema (the workflow-level `outputSchema` — the engine injects a
+ * `structured_output` tool and fails the lane on a missing/invalid report): closed shapes,
+ * all four root keys required — `counts` is a ROOT-level required object (the exact block the
+ * motivating transcription failure nested inside `discussion_comments`). Same vocabulary as the
+ * `perk.review-classifier` agent def's report contract (the def↔schema lockstep test).
+ */
+export const REVIEW_CLASSIFIER_REPORT_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["pr", "review_threads", "discussion_comments", "counts"],
+  properties: {
+    pr: { type: "integer" },
+    review_threads: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["thread_id", "classification", "path", "line", "summary"],
+        properties: {
+          thread_id: { type: "string" },
+          classification: {
+            type: "string",
+            enum: ["actionable", "informational", "praise", "question"],
+          },
+          path: { type: ["string", "null"] },
+          line: { type: ["integer", "null"] },
+          summary: { type: "string" },
+        },
+      },
+    },
+    discussion_comments: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["comment_id", "classification", "summary"],
+        properties: {
+          comment_id: { type: "integer" },
+          classification: {
+            type: "string",
+            enum: ["actionable", "informational", "praise", "question"],
+          },
+          summary: { type: "string" },
+        },
+      },
+    },
+    counts: {
+      type: "object",
+      additionalProperties: false,
+      required: ["actionable", "informational", "praise", "question"],
+      properties: {
+        actionable: { type: "integer" },
+        informational: { type: "integer" },
+        praise: { type: "integer" },
+        question: { type: "integer" },
+      },
+    },
+  },
+};
+
+/**
+ * Run the review-classifier wave: ONE fresh-context `perk.review-classifier` lane with the fixed
+ * code-owned task (the child fetches the feedback itself via `perk pr feedback --json` — nothing
+ * model-relayed enters the task), `strict` completeness, no retry, module-default timeout.
+ * Returns the runner's `WaveResult` unchanged — the only projection lives in the door.
+ */
+export async function runReviewClassifierWave(
+  adapter: WaveAdapter,
+  opts: { model?: string; timeoutMs?: number; signal?: AbortSignal } = {},
+): Promise<WaveResult> {
+  return await runReportWave(
+    adapter,
+    {
+      flow: REVIEW_CLASSIFIER_FLOW,
+      lanes: [
+        {
+          key: CLASSIFY_LANE_KEY,
+          label: CLASSIFY_LANE_KEY,
+          agent: "perk.review-classifier",
+          phase: "address",
+          task: "Fetch + classify the review feedback on this plan's PR.",
+        },
+      ],
+      outputSchema: REVIEW_CLASSIFIER_REPORT_SCHEMA,
+      completeness: "strict",
+      ...(opts.model !== undefined ? { model: opts.model } : {}),
+      ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+    },
+    opts.signal,
+  );
+}

package/extension/waves/rpcAdapter.ts

@@ -2,7 +2,8 @@
 // in-process event bus (unit-testable offline with a fake bus + a fake RPC responder, exactly
 // like the plannotator bridge).
 //
-// ENVELOPE (pinned against pi-subagents 0.43.0, `src/extension/rpc.ts`): requests are emitted on
+// ENVELOPE (pinned against pi-subagents 0.43.0, re-verified at 0.45.0; `src/extension/rpc.ts`):
+// requests are emitted on
 // `subagents:rpc:v1:request` as `{version: 1, requestId, method, params?, source?}`; the reply
 // arrives once on `subagents:rpc:v1:reply:<requestId>` as
 // `{version, requestId, method?, success: true, data} | {…, success: false, error: {code, message}}`.
@@ -12,6 +13,14 @@
 // envelope is for). `pi-subagents` is not an allowed bare import (`bareImportGuard.test.ts`), so
 // its constants/types cannot be imported — the doctor `subagent-compat` probes are the drift
 // tripwire, and every pi-subagents bump warrants an adapter re-verify.
+//
+// COMPLETION PAYLOAD (source-read-derived, 0.45.0 `src/runs/background/result-watcher.ts` +
+// `src/runs/foreground/subagent-executor.ts`): the async-complete event spreads the result-file
+// data plus a normalized per-child `results` array; on workflow rows the `agent` field carries
+// the workflow LANE KEY (the overloaded upstream field — mapped to `WaveChildReceipt.key` here,
+// never exposed). Normalization is defensively output-free: `output`/`summary`/
+// `structuredOutput` never enter a receipt child, unknown fields are ignored, and malformed
+// rows are dropped without failing the wave (receipt absence degrades correlation only).
 
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
@@ -19,6 +28,7 @@ import { join } from "node:path";
 import type {
   WaveAdapter,
   WaveBus,
+  WaveChildReceipt,
   WaveCompletion,
   WavePing,
   WaveRunHandle,
@@ -111,6 +121,49 @@ async function request(
   });
 }
 
+/**
+ * Narrow one completion-payload `results` row's `artifactPaths` to its string-valued own
+ * properties; when none survive, fall back to the watcher-normalized `artifactPath` as
+ * `{ outputPath }`. Undefined when neither yields a path.
+ */
+function narrowArtifactPaths(row: Record<string, unknown>): Record<string, string> | undefined {
+  if (isRecord(row.artifactPaths)) {
+    const paths: Record<string, string> = {};
+    for (const [key, value] of Object.entries(row.artifactPaths)) {
+      if (typeof value === "string") paths[key] = value;
+    }
+    if (Object.keys(paths).length > 0) return paths;
+  }
+  if (typeof row.artifactPath === "string" && row.artifactPath !== "") {
+    return { outputPath: row.artifactPath };
+  }
+  return undefined;
+}
+
+/**
+ * Narrow one `results` row into an output-free receipt child; null ⇒ the row is dropped (a
+ * malformed row never fails the wave). The upstream `agent` field carries the workflow lane key
+ * — it becomes `key`; `agent` is deliberately left unset (enriched from Perk-owned lane specs
+ * upstream). `output`/`summary`/`structuredOutput` and unknown fields are NEVER copied.
+ */
+function narrowReceiptChild(row: unknown): WaveChildReceipt | null {
+  if (!isRecord(row)) return null;
+  const key = row.agent;
+  if (typeof key !== "string" || key === "") return null;
+  const artifactPaths = narrowArtifactPaths(row);
+  return {
+    key,
+    ...(typeof row.runId === "string" && row.runId !== "" ? { runId: row.runId } : {}),
+    ...(typeof row.success === "boolean" ? { success: row.success } : {}),
+    ...(row.outputState === "present" ||
+    row.outputState === "absent" ||
+    row.outputState === "unknown"
+      ? { outputState: row.outputState }
+      : {}),
+    ...(artifactPaths !== undefined ? { artifactPaths } : {}),
+  };
+}
+
 /** Narrow a ping reply to the advertised async-complete channel; any miss ⇒ null (unavailable). */
 function narrowPing(data: unknown): WavePing | null {
   if (!isRecord(data)) return null;
@@ -166,10 +219,20 @@ export function createRpcWaveAdapter(bus: WaveBus): WaveAdapter {
       return bus.on(advertised.asyncCompleteEvent, (data) => {
         if (!isRecord(data)) return;
         // The payload spreads the result-file data: `id` is the async run id; `asyncDir` the
-        // durable run directory. At least one is present on real payloads.
+        // durable run directory. At least one is present on real payloads. The observability
+        // fields (state/success/results) are optional — identity-only payloads stay valid.
+        const children = Array.isArray(data.results)
+          ? data.results.flatMap((row) => {
+              const child = narrowReceiptChild(row);
+              return child === null ? [] : [child];
+            })
+          : undefined;
         handler({
           ...(typeof data.id === "string" ? { asyncId: data.id } : {}),
           ...(typeof data.asyncDir === "string" ? { asyncDir: data.asyncDir } : {}),
+          ...(typeof data.state === "string" && data.state !== "" ? { state: data.state } : {}),
+          ...(typeof data.success === "boolean" ? { success: data.success } : {}),
+          ...(children !== undefined ? { children } : {}),
         });
       });
     },

package/extension/worker/readOnlySession.ts

@@ -19,7 +19,7 @@
 // loading perk's own extension into the child). The `no*` flags keep perk's machinery out of the
 // child and keep the path offline/deterministic. A custom loader is reloaded by the caller.
 
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Api, Model } from "@earendil-works/pi-ai";
@@ -30,7 +30,7 @@ import {
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
-import { runScratchDir, scratchDir } from "../substrate/cache.ts";
+import { atomicWriteFileSync, runScratchDir, scratchDir } from "../substrate/cache.ts";
 
 /**
  * The SDK-level read-only allowlist (no `bash`; stricter than the in-session READ_ONLY_TOOLS).
@@ -267,7 +267,7 @@ export async function runReadOnlyChild(
 
     // write → verify → pass-path: persist the full result, then confirm it landed.
     const scratchPath = resolveScratchPath(opts.cwd, opts.runId, opts.step);
-    writeFileSync(scratchPath, output, "utf8");
+    atomicWriteFileSync(scratchPath, output);
     if (!existsSync(scratchPath)) {
       return failure("read-only child: scratch write could not be verified.", "scratch-verify");
     }

package/extension/worker/worker.ts

@@ -32,19 +32,17 @@ import { env } from "node:process";
 // re-export a thinking-level type (only `ThinkingLevelChangeEntry`).
 import type { Api, Model, ModelThinkingLevel as ThinkingLevel } from "@earendil-works/pi-ai";
 import {
-  AuthStorage,
   type CreateAgentSessionRuntimeFactory,
   createAgentSessionFromServices,
   createAgentSessionRuntime,
   createAgentSessionServices,
-  ModelRegistry,
+  ModelRuntime,
   resolveCliModel,
   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 { captureSessionPointer } from "../substrate/sessionPointers.ts";
 import { rebuildWorkflowState } from "../substrate/workflowState.ts";
@@ -94,10 +92,14 @@ export interface RunOutcome {
  * 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.
+ * `RunOutcome.budget.elapsed_ms`). Future nodes may add variants/fields; existing ones keep
+ * meaning — including deprecated variants that are no longer emitted (see `step_marker`).
  */
 export type RunEvent =
   | { kind: "run_started"; seq: number; t: number; run_id: string; stage: DriveStage }
+  // DEPRECATED — never emitted: the `[WIP:n]`/`[DONE:n]` marker protocol died with the
+  // checkpoints removal. Kept for additive-stable grammar — historical `events.ndjson` files
+  // may carry the variant (contracts §8.12).
   | { kind: "step_marker"; seq: number; t: number; marker: "wip" | "done"; step: number }
   | {
       kind: "tool_outcome";
@@ -137,8 +139,8 @@ export interface DriveStageOptions {
    * `undefined` ⇒ the SDK's settings-default resolution — unchanged behavior.
    */
   thinkingLevel?: ThinkingLevel;
-  authStorage?: AuthStorage;
-  modelRegistry?: ModelRegistry;
+  /** The canonical model/auth runtime (pi 0.84 `ModelRuntime`); default-created when absent. */
+  modelRuntime?: ModelRuntime;
   budget: DriveBudget;
   /** External cancellation; OR'd with the budget watchdog. */
   signal?: AbortSignal;
@@ -176,8 +178,6 @@ export interface DriveEvent {
      * sum: adding it would double-count.
      */
     usage?: { input?: number; output?: number; reasoning?: number };
-    /** Assistant text/content blocks (where `[WIP:n]`/`[DONE:n]` markers live). */
-    content?: unknown;
   };
 }
 
@@ -207,13 +207,14 @@ export interface DriveRuntimeLike {
 export interface DriveCounters {
   turns: number;
   tokens: number;
+  /** Latest submit-bearing evidence (standalone submit or the nested finalizer submit). */
   submitDetails: Record<string, unknown> | null;
-  resolveDetails: Record<string, unknown> | null;
+  finalizeDetails: Record<string, unknown> | null;
   modelError: { message: string } | null;
 }
 
 export function freshCounters(): DriveCounters {
-  return { turns: 0, tokens: 0, submitDetails: null, resolveDetails: null, modelError: null };
+  return { turns: 0, tokens: 0, submitDetails: null, finalizeDetails: null, modelError: null };
 }
 
 /** The natural-idle terminal classification (before watchdog/abort overrides). */
@@ -239,7 +240,7 @@ function detailsOf(result: unknown): Record<string, unknown> | 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
+ * /`finalize_address` terminal tool details, and records a post-acceptance model error
  * (assistant `message_end` with `stopReason:"error"`, surfaced with retry off — audit §B #4).
  *
  * The token sum is `input + output` ONLY: `usage.reasoning` is a subset of `output` on every
@@ -255,8 +256,19 @@ export function applyEvent(counters: DriveCounters, event: DriveEvent): void {
   }
   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);
+    else if (event.toolName === "finalize_address") {
+      const details = detailsOf(event.result);
+      counters.finalizeDetails = details;
+      // A finalizer carries the submit that immediately preceded resolution. Recording it into the
+      // same latest-evidence slot means a later standalone submit naturally supersedes it after a
+      // conflict-resolver re-drive.
+      const nestedSubmit = details?.submit;
+      if (nestedSubmit && typeof nestedSubmit === "object" && !Array.isArray(nestedSubmit)) {
+        // The finalizer only exposes this nested block after submit succeeded; restore the
+        // success marker stripped from its nested public shape so a later failed standalone
+        // submit cannot accidentally satisfy the address completion predicate.
+        counters.submitDetails = { ok: true, ...(nestedSubmit as Record<string, unknown>) };
+      }
     }
     return;
   }
@@ -276,13 +288,14 @@ export function budgetTripped(counters: DriveCounters, budget: DriveBudget): boo
  * 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;
+ *  - address: `finalize_address` ok, `last_review_batch` appended, and the latest submit-bearing
+ *    evidence is successful and not definitively unmergeable → 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;
+  finalizeDetails: Record<string, unknown> | null;
   lastReviewBatchPresent: boolean;
   modelError: { message: string } | null;
 }): TerminalVerdict {
@@ -331,8 +344,20 @@ export function evaluateTerminal(args: {
     };
   }
 
-  // address
-  if (args.resolveSucceeded && args.lastReviewBatchPresent) {
+  // address. `applyEvent` keeps submitDetails as the latest submit-bearing evidence: the nested
+  // finalizer submit first, then a later standalone submit from the conflict-resolution re-drive.
+  const nestedSubmit = args.finalizeDetails?.submit;
+  const fallbackSubmit: Record<string, unknown> | null =
+    nestedSubmit && typeof nestedSubmit === "object" && !Array.isArray(nestedSubmit)
+      ? { ok: true, ...(nestedSubmit as Record<string, unknown>) }
+      : null;
+  const effectiveSubmit = args.submitDetails ?? fallbackSubmit;
+  if (
+    args.finalizeDetails?.ok === true &&
+    args.lastReviewBatchPresent &&
+    effectiveSubmit?.ok === true &&
+    effectiveSubmit.mergeable !== false
+  ) {
     return {
       status: "completed",
       terminal_signal: "address_resolved",
@@ -346,18 +371,20 @@ export function evaluateTerminal(args: {
     terminal_signal: "agent_idle_incomplete",
     pr: null,
     errorType: "incomplete",
-    errorMessage: "address drive went idle without resolving feedback (no last_review_batch).",
+    errorMessage:
+      "address drive went idle without fully finalizing feedback " +
+      "(publication, thread resolution, and last_review_batch are required).",
   };
 }
 
 /**
  * The post-bind preflight rule (pure): the stage's terminating perk tool must be registered —
- * `implement` → `submit`, `address` → `resolve_review_threads`. Returns the required tool name
+ * `implement` → `submit`, `address` → `finalize_address`. Returns the required tool name
  * when absent, else `null`. Deliberately does NOT require the `subagent` tool for `address` — the
  * subagent-under-worker live smoke stays the §8.11 carried risk.
  */
 export function missingTerminatingTool(stage: DriveStage, toolNames: string[]): string | null {
-  const required = stage === "implement" ? "submit" : "resolve_review_threads";
+  const required = stage === "implement" ? "submit" : "finalize_address";
   return toolNames.includes(required) ? null : required;
 }
 
@@ -406,39 +433,6 @@ export function assembleOutcome(args: {
 
 // --- 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`.
@@ -524,14 +518,11 @@ export function defaultEventSink(worktree: string, runId: string): RunEventSink
  *
  * 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.
+ * (preview is a warm/cold flag only), so it always renders the action body. The classify step is
+ * the `classify_review_feedback` tool, which reads the configured classifier model at execute
+ * time — nothing model-shaped rides the prompt.
  */
-export function initialPromptFor(
-  stage: DriveStage,
-  planRef: PlanRef | null,
-  classifierModel?: string,
-): string | null {
+export function initialPromptFor(stage: DriveStage, planRef: PlanRef | null): string | null {
   if (planRef === null) return null;
   const provider = String(planRef.provider ?? "");
   const prId = String(planRef.pr_id ?? "");
@@ -541,15 +532,7 @@ export function initialPromptFor(
     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 [models.subagents] review-classifier model)`
-    : "";
-  return render("stages/address/action.md", {
-    provider,
-    pr_id: prId,
-    url,
-    model_clause: modelClause,
-  });
+  return render("stages/address/action.md", { provider, pr_id: prId, url });
 }
 
 // --- bind / subscribe management (Gap 1) --------------------------------------------------------
@@ -619,9 +602,8 @@ async function defaultCreateRuntime(
     const services = await createAgentSessionServices({
       cwd: factoryOpts.cwd,
       agentDir: factoryOpts.agentDir,
-      authStorage: resolved.authStorage,
       settingsManager,
-      modelRegistry: resolved.modelRegistry,
+      modelRuntime: resolved.modelRuntime,
     });
     const result = await createAgentSessionFromServices({
       services,
@@ -660,24 +642,23 @@ async function defaultCreateRuntime(
 // --- model/auth resolution (Gap 5) --------------------------------------------------------------
 
 export interface ResolvedAuth {
-  authStorage: AuthStorage;
-  modelRegistry: ModelRegistry;
+  modelRuntime: ModelRuntime;
   /** The EXPLICIT model only; `undefined` defers the pick to the SDK at session creation. */
   model: Model<Api> | undefined;
 }
 
 /**
- * Resolve auth; returns null (never throws) when no model is available at all. The model is NOT
- * pre-pinned from the registry: an `undefined` model lets `createAgentSession` run its own
- * initial-model resolution (settings `defaultModel` → pi's curated per-provider defaults → first
- * available), which picks a current-generation model instead of the registry's
- * alphabetically-first (= oldest) entry.
+ * Resolve auth; returns null (never throws a domain error) when no model is available at all.
+ * The model is NOT pre-pinned from the runtime: an `undefined` model lets `createAgentSession`
+ * run its own initial-model resolution (settings `defaultModel` → pi's curated per-provider
+ * defaults → first available), which picks a current-generation model instead of the catalogue's
+ * alphabetically-first (= oldest) entry. Async because pi 0.84's `ModelRuntime.create` is async
+ * (the default creation stays offline — `allowModelNetwork` defaults false).
  */
-export function resolveAuth(opts: DriveStageOptions): ResolvedAuth | null {
-  const authStorage = opts.authStorage ?? AuthStorage.create();
-  const modelRegistry = opts.modelRegistry ?? ModelRegistry.create(authStorage);
-  if (!opts.model && modelRegistry.getAvailable().length === 0) return null;
-  return { authStorage, modelRegistry, model: opts.model };
+export async function resolveAuth(opts: DriveStageOptions): Promise<ResolvedAuth | null> {
+  const modelRuntime = opts.modelRuntime ?? (await ModelRuntime.create());
+  if (!opts.model && modelRuntime.getAvailableSnapshot().length === 0) return null;
+  return { modelRuntime, model: opts.model };
 }
 
 /** What an explicit `--model` flag resolves to (a thin projection of `ResolveCliModelResult`). */
@@ -700,12 +681,12 @@ export interface ResolvedWorkerModel {
  */
 export function resolveWorkerModel(
   raw: string | undefined,
-  modelRegistry: ModelRegistry,
+  modelRuntime: ModelRuntime,
 ): ResolvedWorkerModel {
   if (!raw) {
     return { model: undefined, thinkingLevel: undefined, warning: undefined, error: undefined };
   }
-  const result = resolveCliModel({ cliModel: raw, modelRegistry });
+  const result = resolveCliModel({ cliModel: raw, modelRuntime });
   if (result.model === undefined && result.error === undefined) {
     return {
       model: undefined,
@@ -753,7 +734,9 @@ export async function driveStage(
     return outcome;
   };
 
-  const resolved = resolveAuth(opts);
+  // Auth/model resolution is a production-path concern only: with an injected runtime factory
+  // (tests) the drive never touches the default `ModelRuntime.create` (no host file reads).
+  const resolved = deps.createRuntime ? null : await 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 });
@@ -772,10 +755,6 @@ export async function driveStage(
   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);
@@ -908,7 +887,7 @@ function classify(
   return evaluateTerminal({
     stage: opts.stage,
     submitDetails: counters.submitDetails,
-    resolveSucceeded: counters.resolveDetails?.ok === true,
+    finalizeDetails: counters.finalizeDetails,
     lastReviewBatchPresent,
     modelError: counters.modelError,
   });
@@ -916,6 +895,5 @@ function classify(
 
 /** 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);
+  return initialPromptFor(stage, readPlanRef(worktree));
 }

package/extension/workerMain.ts

@@ -9,7 +9,7 @@
 // stderr), and exits 0 on `completed` else non-zero. Runs as `.ts` under node 22 type-stripping.
 
 import { argv, env, exit, stderr, stdout } from "node:process";
-import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { runEventsPath, workflowDir } from "./substrate/cache.ts";
 import {
   type DriveBudget,
@@ -99,9 +99,8 @@ async function main(): Promise<number> {
   // pi's CLI semantics (fuzzy matching, `provider/pattern`, a `:thinking` suffix —
   // `resolveWorkerModel`), else the SDK's default resolution at session creation (settings
   // default → pi's per-provider defaults → first available) — the deferral is unchanged.
-  const authStorage = AuthStorage.create();
-  const modelRegistry = ModelRegistry.create(authStorage);
-  const resolved = resolveWorkerModel(parsed.model, modelRegistry);
+  const modelRuntime = await ModelRuntime.create();
+  const resolved = resolveWorkerModel(parsed.model, modelRuntime);
   if (resolved.error) {
     stderr.write(`perk worker: ${resolved.error}\n`);
     return 2;
@@ -121,8 +120,7 @@ async function main(): Promise<number> {
       initialPrompt,
       model: resolved.model,
       thinkingLevel: resolved.thinkingLevel,
-      authStorage,
-      modelRegistry,
+      modelRuntime,
       budget: parsed.budget,
       signal: controller.signal,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgiles/perk",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "description": "perk Pi extension (session interior) for the plan-oriented workflow.",
   "license": "MIT",
   "repository": {
@@ -29,10 +29,18 @@
       "./extension/index.ts"
     ]
   },
+  "workspaces": [
+    "docs/site"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "biome check extension",
-    "format": "biome format --write extension"
+    "lint": "biome check extension docs/site tools",
+    "format": "biome format --write extension docs/site tools",
+    "docs:dev": "npm run dev --workspace docs/site",
+    "docs:build": "npm run build --workspace docs/site",
+    "docs:preview": "npm run preview --workspace docs/site",
+    "docs:typecheck": "npm run typecheck --workspace docs/site",
+    "docs:check": "npm run check --workspace docs/site"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -42,10 +50,12 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
-    "@earendil-works/pi-ai": "0.80.5",
-    "@earendil-works/pi-coding-agent": "0.80.5",
+    "@earendil-works/pi-ai": "0.84.1",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.1",
     "@types/node": "22.19.19",
     "diff": "8.0.4",
+    "typebox": "1.3.7",
     "typescript": "6.0.3",
     "yaml": "2.9.0"
   },