@mgiles/perk 2.2.0 → 3.0.0

package/extension/index.ts

@@ -4,25 +4,31 @@
 // `session_start` (verified-linkage), rebuild `perk:workflow-state` on `session_start` AND
 // `session_tree` (per-field LWW), and derive a child run_id on fork.
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerPlanAdapterPlannotator } from "./adapters/planAdapterPlannotator.ts";
 import { registerPlanAdapterTombell } from "./adapters/planAdapterTombell.ts";
-import { registerTodoAdapterJuicesharp } from "./adapters/todoAdapterJuicesharp.ts";
-import { registerCheckpoints } from "./checkpoints/checkpoints.ts";
 import { registerAddress } from "./doors/address.ts";
-import { registerAskUser } from "./doors/askUser.ts";
+import { registerAnnotationPushTool } from "./doors/annotationPush.ts";
+import { registerAuditWave } from "./doors/auditWaveTools.ts";
 import { registerCiExecutor } from "./doors/ciExecutor.ts";
 import { registerCommitAndCompact } from "./doors/commitCompact.ts";
+import { registerDraftReviewWaveTools } from "./doors/draftReviewWaveTools.ts";
+import { registerHarvestWave } from "./doors/harvestWaveTools.ts";
 import { registerLand } from "./doors/land.ts";
 import { registerLearn } from "./doors/learn.ts";
 import { CODE_DOOR, DOCS_DOOR, registerLearnFactoryDoor } from "./doors/learnFactory.ts";
 import { registerLifecycleGates } from "./doors/lifecycleGates.ts";
+import { registerObjectiveReviewBrowser } from "./doors/objectiveReviewBrowser.ts";
+import { registerObjectiveStack } from "./doors/objectiveStack.ts";
+import { registerPlanReviewBrowser } from "./doors/planReviewBrowser.ts";
 import { registerPrReview } from "./doors/prReview.ts";
 import { registerPrReviewBrowser } from "./doors/prReviewBrowser.ts";
+import { registerPrReviewDynamic } from "./doors/prReviewDynamic.ts";
 import { registerPrReviewTerminal } from "./doors/prReviewTerminal.ts";
 import { registerReady } from "./doors/ready.ts";
+import { registerReviewWaveTools } from "./doors/reviewWaveTools.ts";
 import { registerSelfcheck } from "./doors/selfcheck.ts";
 import { registerSubmit } from "./doors/submit.ts";
 import { registerSubmitPrReview } from "./doors/submitPrReview.ts";
@@ -39,8 +45,10 @@ import { registerPlanDraft } from "./factories/planDraft.ts";
 import { registerPlanMode } from "./factories/planMode.ts";
 import { registerPlanReview } from "./factories/planReview.ts";
 import { registerPlanSave } from "./factories/planSave.ts";
+import { createHunkFeedbackReceiver } from "./hunkFeedback/receiver.ts";
 import { registerBindingDelivery } from "./substrate/bindingDelivery.ts";
 import {
+  atomicWriteFileSync,
   ensureRunScratch,
   markHandoffConsumed,
   readHandoff,
@@ -49,7 +57,7 @@ import {
   workflowDir,
 } from "./substrate/cache.ts";
 import { loadRegistry, type Registry, stageConsumesPlanRef } from "./substrate/registry.ts";
-import { perkVersion, sharedDir } from "./substrate/resources.ts";
+import { perkVersion, sharedDir, versionStamp } from "./substrate/resources.ts";
 import { mintRunId } from "./substrate/runId.ts";
 import { captureSessionPointer } from "./substrate/sessionPointers.ts";
 import { registerToolGating } from "./substrate/toolGating.ts";
@@ -87,7 +95,7 @@ function writeT3Sentinel(
   try {
     const dir = workflowDir(cwd);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    writeFileSync(
+    atomicWriteFileSync(
       join(dir, ".perk-t3.json"),
       `${JSON.stringify({
         source,
@@ -101,7 +109,6 @@ function writeT3Sentinel(
         pi_session_id: state.pi_session_id ?? null,
         active_plan_ref: state.active_plan_ref ?? null,
       })}\n`,
-      "utf8",
     );
   } catch {
     // never throw from a probe
@@ -178,21 +185,25 @@ export default function (pi: ExtensionAPI) {
   }
   const registryOk = registryStages > 0;
 
-  // The composed `perk` status handle (charter D2): one slot, ordered objective →
-  // checkpoints segments. Created once here (no hidden module state) and threaded into the two
-  // segment publishers below; the footer reads it back via get/subscribe.
+  // The single-value `perk` status handle (charter D2): one slot carrying the objective
+  // segment. Created once here (no hidden module state) and threaded into the objective
+  // publisher below; the footer reads it back via get/subscribe.
   const perkStatus = createPerkStatus();
 
-  // Install the perk-owned footer once per session (charter D2/D7). Once-only: pi's
-  // dispose contract for a REPLACED footer factory is unverified, so re-installing on every
-  // session_start (reload) could leak the previous handle subscription.
-  let footerInstalled = false;
-
   // Transcript marker for `perk:workflow-state` deltas (audit §2.3): the renderer body lives in
   // surfaces.ts, this registration is wiring, and the seam carries the typeof feature-detect
   // (pre-0.80.4 hosts stay inert). One registration covers every workflow-state appender.
   registerTranscriptRenderer(pi, WORKFLOW_STATE_TYPE, workflowStateEntryRenderer);
 
+  // The hunk watch feedback receiver controller (contracts §8.58) — factory-scoped (no module
+  // globals). Synced from session_start/session_tree below; closed on session_shutdown so the
+  // consumer lease releases with the session. A stale /reload predecessor instance is retired
+  // by the lease fencing (fresh token per same-identity reacquire + verify-before-inject).
+  const feedbackReceiver = createHunkFeedbackReceiver(pi);
+  pi.on("session_shutdown", async () => {
+    feedbackReceiver.close();
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     const branchEntries = () => branchOf(ctx);
     const sessionFile = ctx.sessionManager.getSessionFile();
@@ -210,6 +221,11 @@ export default function (pi: ExtensionAPI) {
       cwd: ctx.cwd,
     });
 
+    // The session-audit exact-vintage stamp (§8.3), recorded by every run-identity arm below
+    // (claim/fork/adopt/mint); undefined on the perkVersion() failure sentinel, which drops the
+    // key on serialize and leaves the session on the timestamp-estimate arm.
+    const stamp = versionStamp(version);
+
     // `claim`/`adopt` carry no prior branch state (adopt's is written by its arm below).
     let resolved: WorkflowState =
       decision.action === "claim" || decision.action === "adopt" ? {} : decision.state;
@@ -225,6 +241,7 @@ export default function (pi: ExtensionAPI) {
           run_id: decision.runId,
           pi_session_id: currentSessionId ?? undefined,
           mode: handoff.mode,
+          perk_version: stamp,
           // Record the launched stage so the interior can tell e.g. objective-author from plan
           // (both are read-only) and inject the right authoring context (planMode vs objectiveAuthor).
           stage: handoff.stage,
@@ -253,6 +270,7 @@ export default function (pi: ExtensionAPI) {
         pi_session_id: currentSessionId ?? undefined,
         predecessor: decision.parentRunId,
         mode: decision.state.mode,
+        perk_version: stamp,
       };
       pi.appendEntry(WORKFLOW_STATE_TYPE, data);
       resolved = data;
@@ -269,6 +287,7 @@ export default function (pi: ExtensionAPI) {
         pi_session_id: currentSessionId ?? undefined,
         predecessor: decision.parentRunId,
         mode: decision.mode,
+        perk_version: stamp,
       };
       pi.appendEntry(WORKFLOW_STATE_TYPE, data);
       resolved = data;
@@ -278,7 +297,11 @@ export default function (pi: ExtensionAPI) {
       // dirs are the accessor's job; provenance is recorded separately. A failed cold claim above never
       // falls here (claim stays a loud unclaimed error).
       const runId = mintRunId();
-      const data: WorkflowState = { run_id: runId, pi_session_id: currentSessionId ?? undefined };
+      const data: WorkflowState = {
+        run_id: runId,
+        pi_session_id: currentSessionId ?? undefined,
+        perk_version: stamp,
+      };
       const okAppend = appendWorkflowState(pi, ctx, {
         data,
         field: "run_id",
@@ -376,6 +399,20 @@ export default function (pi: ExtensionAPI) {
       });
     }
 
+    // The hunk watch feedback receiver (§8.58): sync strictly AFTER the run-identity claim and
+    // the plan-ref reconciliation above, so an unclaimed or mislinked session never touches the
+    // outbox. Eligibility (interactive TUI + implement stage + non-adopted + settled identity +
+    // plan-ref match against one fresh cache read) is evaluated inside sync; every ineligible
+    // shape closes any open inbox. Never throws (the controller contains its own failures).
+    feedbackReceiver.sync(ctx, {
+      stage: implStage,
+      adopted: decision.action === "adopt",
+      runId: resolved.run_id ?? null,
+      piSessionId: currentSessionId,
+      activePlanRef: resolved.active_plan_ref ?? null,
+      mode: ctx.mode ?? null,
+    });
+
     // Soft version-parity drift signal: pi can lazy-install / load a stale `npm:@mgiles/perk`, so the
     // extension actually running may differ from the `perk` CLI that launched it. The local launch
     // seam injects PERK_CLI_VERSION; compare it against this extension's own `perkVersion()`. Soft +
@@ -396,11 +433,16 @@ export default function (pi: ExtensionAPI) {
     // Charter D7: perk identity is standing footer state, not a transition — the
     // `v<version> loaded` toast (and its headless stderr mirror) is retired. D5 is rescinded:
     // perk keeps pi's default working indicator (no setWorkingIndicator call anywhere).
+    // Install on EVERY headful session_start: pi ≥ 0.84's `setExtensionFooter` explicitly
+    // disposes a replaced footer factory (verified at 0.84.1), and `resetExtensionUI` restores
+    // the built-in footer on /reload and before session replacement — both paths also re-run
+    // this extension factory, so repeated installs leak nothing and each install's deps
+    // closures capture the current event's ctx.
     // Footer-seam install-site vacating: under a foreign `[providers] footer` selection perk does
     // NOT install its own footer, leaving the foreign footer (`pi-powerline-footer` / `pi-bar`) as
-    // the sole footer surface. perk's objective/checkpoints progress still reaches it via the
-    // composed `perk` setStatus slot. Fail-safe: any config-read error resolves to install.
-    if (ctx.hasUI && !footerInstalled && isPerkFooterReferenceSelected(ctx.cwd)) {
+    // the sole footer surface. perk's objective progress still reaches it via the
+    // single-value `perk` setStatus slot. Fail-safe: any config-read error resolves to install.
+    if (ctx.hasUI && isPerkFooterReferenceSelected(ctx.cwd)) {
       installPerkFooter(ctx, {
         identity: `perk v${version}`,
         status: perkStatus,
@@ -412,7 +454,6 @@ export default function (pi: ExtensionAPI) {
           return usage ? { percent: usage.percent, contextWindow: usage.contextWindow } : null;
         },
       });
-      footerInstalled = true;
     }
 
     if (process.env.PERK_SELFCHECK) {
@@ -420,7 +461,7 @@ export default function (pi: ExtensionAPI) {
         const dir = workflowDir(ctx.cwd);
         if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
         // The gate sentinel (unchanged — those gates parse this line).
-        writeFileSync(
+        atomicWriteFileSync(
           join(dir, ".perk-loaded"),
           `perk ${version} loaded; shared=${sharedOk ? "ok" : "miss"}; ` +
             `registry=${registryOk ? "ok" : "miss"} stages=${registryStages}; hasUI=${ctx.hasUI}\n`,
@@ -443,6 +484,17 @@ export default function (pi: ExtensionAPI) {
     } catch (error) {
       console.error(`perk: tool-gating sync failed on session_tree — ${error}`);
     }
+    // Re-sync the feedback receiver from the LWW-rebuilt state (§8.58). `adopted: false` is
+    // right here: an env-adopted child's fresh branch carries no stage, so the stage gate
+    // alone keeps it inert on tree navigation.
+    feedbackReceiver.sync(ctx, {
+      stage: state.stage ?? null,
+      adopted: false,
+      runId: state.run_id ?? null,
+      piSessionId: state.pi_session_id ?? null,
+      activePlanRef: state.active_plan_ref ?? null,
+      mode: ctx.mode ?? null,
+    });
     if (process.env.PERK_SELFCHECK) {
       writeT3Sentinel(ctx.cwd, "tree", state, ctx.mode ?? null);
     }
@@ -468,11 +520,6 @@ export default function (pi: ExtensionAPI) {
   // The `gist_draft` working-gist file tool (the third draft carve-out).
   registerGistDraft(pi);
 
-  // The universal `ask_user_question` tool: lets a model interactively ask the human a
-  // clarifying question (free-text or multiple-choice). Registered in the factory so it exists
-  // before the gate snapshots tools; its name is in READ_ONLY_TOOLS so it survives plan mode.
-  registerAskUser(pi);
-
   // Lifecycle gates: the dirty-repo switch/fork guard + the guard-only `/implement`.
   registerLifecycleGates(pi);
 
@@ -486,19 +533,48 @@ export default function (pi: ExtensionAPI) {
   registerLand(pi);
   registerLearn(pi);
 
-  // The warm `/address` review loop: the `resolve_review_threads` tool + `/address`
+  // The warm stacked-delivery surface (§8.51): `/objective-stack` (read) +
+  // `/objective-sync`/`/objective-recover` (drives) + the four typed stack tools. Takes
+  // `gating` for the driving commands' gate-on soft refusal (stack sync/recovery mutates
+  // published branches; the stack tools never join READ_ONLY_TOOLS).
+  registerObjectiveStack(pi, gating);
+
+  // The warm `/address` review loop: the submit-then-resolve `finalize_address` tool + `/address`
   // command. Classify-then-act (the verbose feedback fetch + classification runs in an isolated
-  // spawned child; the parent fixes actionable items and batch-resolves the threads).
+  // spawned child; the parent fixes actionable items and finalizes the committed repairs).
   registerAddress(pi);
 
   // The warm `/pr-review` door: automated code review in a FRESH, isolated subagent that
   // POSTS its review to the PR (the deliberate departure from /address's read-only-child rule).
   registerPrReview(pi);
 
+  // The EXPERIMENTAL warm `/pr-review-dynamic` door: the selector-driven sibling — angle
+  // selection delegated to a fresh perk.review-angle-selector lane, normalized in
+  // module-rendered code; posting shares /pr-review's post_pr_review + clean guard. The
+  // baseline /pr-review stays canonical; promotion/retire is a later dogfood's call.
+  registerPrReviewDynamic(pi);
+
   // The warm `submit_pr_review` tool: the human-gated curated-posting surface both review
   // doors ride (contracts §8.4) — neither door registers tools of its own.
   registerSubmitPrReview(pi);
 
+  // The flow-scoped review-wave pair (`start_review_wave`/`collect_review_wave`) both human
+  // review doors drive: non-blocking adversarial-review launch + the typed collect, flow-scoped
+  // via the session's pending-wave guard.
+  registerReviewWaveTools(pi);
+  registerAuditWave(pi);
+  registerHarvestWave(pi);
+
+  // The flow-scoped draft-review-wave pair (`start_draft_review_wave`/
+  // `collect_draft_review_wave`) the draft-review door drives: non-blocking draft-review
+  // launch over the door-primed context + the typed collect.
+  registerDraftReviewWaveTools(pi);
+
+  // The door-primed browser annotation tool (`push_annotations`): the browser door primes the
+  // surface handle on open and clears it on settle/degrade — the tool refuses outside a
+  // door-opened flow.
+  registerAnnotationPushTool(pi);
+
   // The warm `/pr-review-terminal` door: the terminal review entry — hunk always, no provider
   // dispatch (the command IS the selection); posting rides `submit_pr_review` above.
   registerPrReviewTerminal(pi);
@@ -508,26 +584,22 @@ export default function (pi: ExtensionAPI) {
   // human's own platform-post from the UI, with `submit_pr_review` for request-changes only.
   registerPrReviewBrowser(pi);
 
+  // The warm `/plan-review-browser` door: the summonable streaming draft review — the
+  // plannotator plan-review browser on the working plan draft, draft reviewers streaming
+  // phrase-anchored findings in; APPROVE auto-saves via the approvalSave seam, DENY returns a
+  // model-mediated revision round.
+  registerPlanReviewBrowser(pi, gating);
+
+  // The warm `/objective-review-browser` door: the summonable streaming objective-draft review
+  // — the plannotator plan-review browser on the RENDERED working objective draft, draft
+  // reviewers streaming phrase-anchored findings in; APPROVE auto-saves via the
+  // objectiveApprovalSave seam, Direct Edits = a model-mediated revise round (never auto-saved).
+  registerObjectiveReviewBrowser(pi, gating);
+
   // The read-only CI executor: the `run_ci` tool + `/ci` command + `--allow-project-ci`
   // flag. Runs the project's `[ci]` named checks deterministically and reports (never fixes/loops).
   registerCiExecutor(pi);
 
-  // perk-owned checkpoints: seed from the plan body's `## Steps`, advance on `[DONE:n]`.
-  // Inert when no step list is present (perk plans are prose). Own `session_start`/`session_tree`/
-  // `turn_end` handlers (coexist with the others; pi.on supports multiple handlers per event).
-  // Todo-seam deferral: perk is the reference todo provider (`perk-checkpoints`); these
-  // runtime surfaces step aside when a foreign `[providers] todo` is selected (the todo-seam mirror
-  // of planMode's plan-seam deferral) — silent on the event handlers, announced on `/checkpoints`.
-  registerCheckpoints(pi, perkStatus);
-
-  // The FIRST 3rd-party todo adapter (the todo-seam mirror of registerPlanAdapterTombell).
-  // Injection-only: inert unless `[providers] todo = "juicesharp-todo"` is selected AND the session
-  // is an active workflow. It carries perk's implement-progress discipline onto `@juicesharp/rpiv-
-  // todo`'s checklist overlay (perk's own checkpoints deferred). No `gating` argument —
-  // the shim NEVER arbitrates tools (Invariant 1); no registration-time vacating (no command-name
-  // collision on the todo seam, unlike the plan seam); never writes `perk:checkpoint`.
-  registerTodoAdapterJuicesharp(pi);
-
   // The objective substrate: `/objective` set/clear, budget accounting, threshold
   // compaction, all keyed off the now-live `active_objective`. Inert when no objective is active.
   // (The deterministic objective mechanics live in the Python plane: `perk objective …`.)

package/extension/substrate/cache.ts

@@ -10,10 +10,54 @@
 // the read-only gate engages. The Python twins (src/perk/state/cache.py) deliberately keep
 // RAISING `CacheError` (exterior plane, launch-time fail-loud) — the cross-plane contract is
 // the *files*, not error semantics.
-
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+//
+// Write discipline (contracts.md §8.1): every `.perk/workflow/` write goes through
+// `atomicWriteFileSync` (temp file in the same directory + atomic rename) so a concurrent
+// writer can never tear a file — a reader sees either the old bytes or the new bytes, never a
+// mix (guard-tested by writeGuard.test.ts). The exemptions are the append-only NDJSON streams
+// — the worker's `events.ndjson` (worker/worker.ts) and the §8.58 hunk-watch `outbox.ndjson` /
+// `delivered.ndjson` (hunkFeedback/perkFeedback.ts / hunkFeedback/store.ts) — where O_APPEND
+// appends cannot truncate-tear and whole-file replace would introduce a read-modify-write race
+// between independent processes. Atomicity is not mutual exclusion — whole-file
+// last-writer-wins between concurrent writers is the accepted residual.
+
+import { randomBytes } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 
+/**
+ * Atomically replace `path` with `content` (the interior atomic-write seam).
+ *
+ * Writes a temp file in the same directory (so the rename never crosses filesystems) then swaps
+ * it into place; a concurrent reader sees either the old bytes or the new bytes, never a torn
+ * mix. On failure the temp file is best-effort removed and the error re-thrown. Precondition:
+ * the parent directory exists (same contract as `writeFileSync`; call sites mkdir first).
+ * Deliberately no fsync — crash durability is out of scope; the target is inter-process tearing
+ * of regenerable, gitignored workflow state.
+ */
+export function atomicWriteFileSync(path: string, content: string): void {
+  const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  try {
+    writeFileSync(tmp, content, "utf8");
+    renameSync(tmp, path);
+  } catch (error) {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {
+      // best-effort cleanup — a cleanup failure must never mask the original write/rename error
+    }
+    throw error;
+  }
+}
+
 export interface Handoff {
   run_id: string;
   consumed: boolean;
@@ -67,7 +111,7 @@ export function markHandoffConsumed(
   if (data === null) return;
   data.consumed = true;
   if (opts.piSessionId !== undefined) data.pi_session_id = opts.piSessionId;
-  writeFileSync(handoffPath(cwd, runId), `${JSON.stringify(data, null, 2)}\n`, "utf8");
+  atomicWriteFileSync(handoffPath(cwd, runId), `${JSON.stringify(data, null, 2)}\n`);
 }
 
 // --- scratch -----------------------------------------------------------------------------
@@ -142,29 +186,37 @@ export function readPlanRef(cwd: string): PlanRef | null {
 
 export function writePlanRef(cwd: string, ref: PlanRef): void {
   mkdirSync(workflowDir(cwd), { recursive: true });
-  writeFileSync(planRefPath(cwd), `${JSON.stringify(ref, null, 2)}\n`, "utf8");
+  atomicWriteFileSync(planRefPath(cwd), `${JSON.stringify(ref, null, 2)}\n`);
 }
 
-// --- plan body cache (`cache.plan`) ------------------------------------------------------
+// --- hunk-watch: the watch-feedback bridge family (contracts.md §8.58) ---------------------
+//
+// Worktree-local, disposable: append-only NDJSON streams plus the single-consumer lease dir.
+// This module is the INTERIOR construction site for the family; the hunk-plane twin is the
+// self-contained bundled publisher (extension/hunkFeedback/perkFeedback.ts), pinned to these
+// helpers by a path-parity test.
 
-/**
- * The materialized plan-body cache (`cache.plan`, contracts §8.1). Written by the Python cold door
- * (`perk implement` → `launch.materialize_plan_body`) when it positions the worktree; read here so
- * in-session checkpoints seed from its `## Steps` list (inert when absent).
- */
-export function planBodyPath(cwd: string): string {
-  return join(workflowDir(cwd), "plan.md");
+export function hunkWatchDir(cwd: string): string {
+  return join(workflowDir(cwd), "hunk-watch");
 }
 
-export function readPlanBody(cwd: string): string | null {
-  const path = planBodyPath(cwd);
-  if (!existsSync(path)) return null;
-  try {
-    return readFileSync(path, "utf8");
-  } catch (error) {
-    console.error(`perk: unreadable plan body at ${path} — treating as absent (${error})`);
-    return null;
-  }
+/** Append-only feedback records (the Hunk publisher writes; the Pi receiver reads). */
+export function hunkOutboxPath(cwd: string): string {
+  return join(hunkWatchDir(cwd), "outbox.ndjson");
+}
+
+/** Append-only delivery acknowledgements (the Pi receiver writes). */
+export function hunkDeliveredPath(cwd: string): string {
+  return join(hunkWatchDir(cwd), "delivered.ndjson");
+}
+
+/** The single-consumer lease dir (atomic mkdir is the acquisition primitive). */
+export function hunkConsumerLockDir(cwd: string): string {
+  return join(hunkWatchDir(cwd), "consumer.lock");
+}
+
+export function hunkLeasePath(cwd: string): string {
+  return join(hunkConsumerLockDir(cwd), "lease.json");
 }
 
 // --- markers (existence-only) ------------------------------------------------------------
@@ -178,7 +230,8 @@ export function markerPath(cwd: string, name: string): string {
 
 export function setMarker(cwd: string, name: string): void {
   mkdirSync(join(workflowDir(cwd), "markers"), { recursive: true });
-  writeFileSync(markerPath(cwd, name), "", "utf8");
+  // Routed through the atomic seam for uniformity (empty content is trivially safe either way).
+  atomicWriteFileSync(markerPath(cwd, name), "");
 }
 
 export function hasMarker(cwd: string, name: string): boolean {

package/extension/substrate/coldDoor.ts

@@ -14,10 +14,9 @@
 //   });
 //   if (!r.ok) return fail(r.message, r.errorType);
 
-import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { ExecOptions, ExecResult } from "@earendil-works/pi-coding-agent";
-import { ensureRunScratch } from "./cache.ts";
+import { atomicWriteFileSync, ensureRunScratch } from "./cache.ts";
 import { type BranchSource, branchOf, rebuildWorkflowState } from "./workflowState.ts";
 
 /** Minimal exec surface — `ExtensionAPI` satisfies it (compile-checked in the test); tests fake it. */
@@ -134,7 +133,7 @@ export async function runColdDoor<T>(
     try {
       const dir = ensureRunScratch(ctx.cwd, activeRunId(ctx));
       const path = join(dir, opts.stdin.filename);
-      writeFileSync(path, opts.stdin.content, "utf8");
+      atomicWriteFileSync(path, opts.stdin.content);
       fullArgv = [...argv, opts.stdin.flag, path];
     } catch (err) {
       return {

package/extension/substrate/config.ts

@@ -48,14 +48,20 @@ export interface PerkConfig {
   /**
    * The agent-keyed `[models.subagents]` table: a per-agent model override for each perk-owned
    * project agent (`pr-reviewer`, `review-classifier`, `objective-explorer`, `conflict-resolver`,
-   * `learn-analyst`, `adversarial-reviewer`). Each configured
-   * value is injected as a per-call inline `model` override on that agent's `subagent` spawn; when
-   * a key is absent the agent's frontmatter `model` (in `.pi/agents/<name>.md`) is the default.
+   * `learn-analyst`, `adversarial-reviewer`, `review-angle-selector`, `draft-reviewer`,
+   * `harvest-analyst` — consumed by `run_harvest_wave` at execute time — and the
+   * dev-only `session-auditor`, whose def is repo-local to perk's own repository
+   * (`.pi/agents/perk-dev/session-auditor.md`, never delivered by `perk init`), so the key is
+   * dormant in consumer repos). Each configured
+   * value is injected as the top-level workflow-level `model` on that agent's one `subagent`
+   * workflowScript call — a default flowing onto every lane, single-child runs included (as
+   * /pr-review does); when a key is absent the agent's frontmatter `model` (in
+   * `.pi/agents/perk/<name>.md`; the session-auditor's in its repo-local def) is the default.
    * (`subagents.agentOverrides` does NOT reach project agents — `pi-subagents`'
-   * `applyBuiltinOverrides` applies only to builtins — so this inline override is the mechanism.)
+   * `applyBuiltinOverrides` applies only to builtins — so this inline injection is the mechanism.)
    * A value may carry a `:thinking` suffix (`"anthropic/claude-sonnet-4-5:high"`) or be the
    * `"inherit"` sentinel (child inherits the parent session's model) — both resolved by
-   * pi-subagents on the inline override (the last-colon segment counts as thinking only when it
+   * pi-subagents on the injected value (the last-colon segment counts as thinking only when it
    * is a pi level, so ollama-style tags stay part of the model id).
    * Always-present object; absent keys omitted (mirror of `providers`).
    */
@@ -66,6 +72,10 @@ export interface PerkConfig {
     "conflict-resolver"?: string;
     "learn-analyst"?: string;
     "adversarial-reviewer"?: string;
+    "review-angle-selector"?: string;
+    "draft-reviewer"?: string;
+    "harvest-analyst"?: string;
+    "session-auditor"?: string;
   };
   /**
    * Optional `[compaction] objective_threshold` — the context-usage fraction (0,1] that triggers
@@ -83,8 +93,6 @@ export interface PerkConfig {
    */
   providers: {
     plan?: string;
-    todo?: string;
-    askuser?: string;
     footer?: string;
     web?: string;
   };
@@ -265,6 +273,24 @@ export function loadPerkConfig(cwd: string): PerkConfig {
   };
 }
 
+/**
+ * Resolve one `[models.subagents]` model at execute time — the flow-tool read for sessions that
+ * may run inside a linked worktree. Committed `.perk/config.toml` is read from `cwd` (the
+ * worktree's committed semantics), but the gitignored `.perk/local.toml` lives only in the MAIN
+ * checkout when `cwd` is a linked worktree (worktrees never materialize it), so the local
+ * overlay is additionally anchored via `mainCheckoutRoot` — a user's session-transient model
+ * override survives the cold worktree launch. A worktree-local `local.toml`, if one exists,
+ * still wins (most specific last); in the main checkout the two local reads are the same file
+ * (byte-identical behavior). Fail-open like everything here — missing/malformed files are empty.
+ */
+export function subagentModel(cwd: string, agent: SubagentKey): string | undefined {
+  const merged = overlay(
+    overlay(readTomlFile(configFile(cwd)), readTomlFile(localConfigFile(mainCheckoutRoot(cwd)))),
+    readTomlFile(localConfigFile(cwd)),
+  );
+  return parseSubagentsSelection(merged.tables["models.subagents"])[agent];
+}
+
 /**
  * Read the `[[ci.checks]]` array-of-tables into an ordered `CiCheck[]`. A row is kept only when
  * both `name` and `command` are non-blank strings; `glob` is kept only when a non-blank string.
@@ -286,6 +312,9 @@ export function parseCiChecks(rows: Array<Record<string, TomlScalar>>): CiCheck[
   return checks;
 }
 
+/** One perk-owned project agent name configurable via the `[models.subagents]` table. */
+export type SubagentKey = (typeof SUBAGENT_KEYS)[number];
+
 /** The perk-owned project agents configurable via the `[models.subagents]` table. */
 const SUBAGENT_KEYS = [
   "pr-reviewer",
@@ -294,6 +323,11 @@ const SUBAGENT_KEYS = [
   "conflict-resolver",
   "learn-analyst",
   "adversarial-reviewer",
+  "review-angle-selector",
+  "draft-reviewer",
+  "harvest-analyst",
+  // Dev-only: the perk-dev session-audit judgment wave's auditor (dormant in consumer repos).
+  "session-auditor",
 ] as const;
 
 /**
@@ -312,24 +346,18 @@ function parseSubagentsSelection(
   return selection;
 }
 
-/** Read the flat `[providers]` table into a `{plan?, todo?, askuser?, footer?, web?}` selection (string values only). A retired `review` key is silently ignored (the TS fail-safe posture; the Python plane's tripwire is the loud surface). */
+/** Read the flat `[providers]` table into a `{plan?, footer?, web?}` selection (string values only). Retired keys (`review`, `askuser`, `todo`) are silently ignored (the TS fail-safe posture; the Python plane's tripwire is the loud surface). */
 function parseProvidersSelection(table: Record<string, TomlScalar> | undefined): {
   plan?: string;
-  todo?: string;
-  askuser?: string;
   footer?: string;
   web?: string;
 } {
   const selection: {
     plan?: string;
-    todo?: string;
-    askuser?: string;
     footer?: string;
     web?: string;
   } = {};
   if (typeof table?.plan === "string") selection.plan = table.plan;
-  if (typeof table?.todo === "string") selection.todo = table.todo;
-  if (typeof table?.askuser === "string") selection.askuser = table.askuser;
   if (typeof table?.footer === "string") selection.footer = table.footer;
   if (typeof table?.web === "string") selection.web = table.web;
   return selection;

package/extension/substrate/git.ts

@@ -48,6 +48,16 @@ function git(cwd: string, args: string[], timeout?: number): string | null {
   }
 }
 
+/**
+ * Tracked files under `pathspec` (repo-relative names), [] when none or on ANY failure (not a
+ * repo, git missing — the module's fail-open style). Callers deciding trust on the result must
+ * treat [] as "nothing PROVEN tracked", not proof of cleanliness.
+ */
+export function lsFiles(cwd: string, pathspec: string): string[] {
+  const out = git(cwd, ["ls-files", "--", pathspec]);
+  return out === null ? [] : out.split("\n").filter((line) => line !== "");
+}
+
 /** The bounded best-effort `git fetch` budget (ms) — see `sinceBaseSha` step 2. */
 const FETCH_TIMEOUT_MS = 15_000;