@mgiles/perk 2.3.0 → 3.1.0

package/extension/substrate/cache.ts

@@ -10,9 +10,56 @@
 // 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.
+//
+// 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 {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join, relative } from "node:path";
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, 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;
@@ -67,7 +114,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 -----------------------------------------------------------------------------
@@ -85,6 +132,11 @@ export function runScratchDir(cwd: string, runId: string): string {
   return join(scratchDir(cwd), "runs", runId);
 }
 
+/** The run-owned directory for disposable, non-authoritative model intermediates. */
+export function agentScratchDir(cwd: string, runId: string): string {
+  return join(runScratchDir(cwd, runId), "agent");
+}
+
 /**
  * The session data dir for a run — a dedicated `data/` subdir so
  * run-scoped session artifacts never overlap perk machine records (dispatch.json,
@@ -95,9 +147,91 @@ export function sessionDataDir(cwd: string, runId: string): string {
   return join(runScratchDir(cwd, runId), "data");
 }
 
+/** Reject run ids that could select anything except one child of the shared runs directory. */
+function assertSafeRunId(runId: string): void {
+  if (
+    runId.length === 0 ||
+    runId === "." ||
+    runId === ".." ||
+    runId.includes("/") ||
+    runId.includes("\\") ||
+    runId.includes("\0")
+  ) {
+    throw new Error(`refusing unsafe run id ${JSON.stringify(runId)}`);
+  }
+}
+
+/**
+ * Ensure one checkout-owned path component is a real directory, never a static redirect.
+ * Check-before-create races against a same-UID process are intentionally out of scope.
+ */
+function ensureUnredirectedDirectory(
+  path: string,
+  opts: { createMode: number; rejectGroupWorldWrite: boolean },
+): void {
+  let stat: ReturnType<typeof lstatSync>;
+  try {
+    stat = lstatSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    mkdirSync(path, { mode: opts.createMode });
+    stat = lstatSync(path);
+  }
+  if (stat.isSymbolicLink()) throw new Error(`refusing a symlinked run-scratch path: ${path}`);
+  if (!stat.isDirectory()) throw new Error(`refusing a non-directory run-scratch path: ${path}`);
+  if (opts.rejectGroupWorldWrite && (stat.mode & 0o022) !== 0) {
+    throw new Error(`refusing a group/world-writable run-scratch path: ${path}`);
+  }
+}
+
+/**
+ * Establish a run root beneath this checkout without following redirected checkout content.
+ * Symlinks above `cwd` remain legal; every existing component from `.perk` through the run root
+ * must be a real directory without group/world write permission, and missing components are
+ * created no broader than 0755 even under a permissive umask. Run-id validation happens before
+ * the first filesystem write.
+ */
 export function ensureRunScratch(cwd: string, runId: string): string {
+  assertSafeRunId(runId);
   const dir = runScratchDir(cwd, runId);
-  mkdirSync(dir, { recursive: true });
+  const components = [
+    join(cwd, ".perk"),
+    join(cwd, ".perk", "workflow"),
+    scratchDir(cwd),
+    join(scratchDir(cwd), "runs"),
+    dir,
+  ];
+  for (const component of components) {
+    ensureUnredirectedDirectory(component, {
+      createMode: 0o755,
+      rejectGroupWorldWrite: true,
+    });
+  }
+
+  const expected = join(realpathSync(cwd), relative(cwd, dir));
+  if (realpathSync(dir) !== expected) {
+    throw new Error(`refusing a redirected run-scratch dir: ${dir}`);
+  }
+  return dir;
+}
+
+/**
+ * Create the private run-owned agent directory as 0700 from the outset, then re-apply that mode on
+ * reuse. The mode protects against other OS users; it is not a sandbox from another process running
+ * as the same user.
+ */
+export function ensureAgentScratch(cwd: string, runId: string): string {
+  const runDir = ensureRunScratch(cwd, runId);
+  const dir = agentScratchDir(cwd, runId);
+  ensureUnredirectedDirectory(dir, {
+    createMode: 0o700,
+    rejectGroupWorldWrite: false,
+  });
+  const expected = join(realpathSync(runDir), "agent");
+  if (realpathSync(dir) !== expected) {
+    throw new Error(`refusing a redirected agent scratch dir: ${dir}`);
+  }
+  chmodSync(dir, 0o700);
   return dir;
 }
 
@@ -142,29 +276,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 +320,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/command.ts

@@ -1,14 +1,16 @@
 // The single chokepoint that gives every perk command a uniform, immediate "running…"
 // acknowledgement at entry. pi does not echo the invoked command and handlers only report() at the
 // end, so without this a command's async work (cold-door subprocess calls, GitHub round-trips) is
-// dead air between Enter and completion. registerPerkCommand wraps the handler to emit one transient
-// entry toast through the headless-safe report() seam (no cleanup state, headless-fail-safe for
-// free) before awaiting the original handler. The toast fires synchronously before the first await,
-// so it lands before any cold-door work, sendUserMessage drive, or gate transition; the wrapper does
-// not try/catch, so errors propagate exactly as before.
+// dead air between Enter and completion. registerPerkCommand attaches the command's durable report-
+// detail sink to the exact context object, then emits one transient entry toast through report()
+// before awaiting the original handler. The toast fires synchronously before the first await, so it
+// lands before any cold-door work, sendUserMessage drive, or gate transition; the wrapper does not
+// try/catch, so errors propagate exactly as before. The WeakMap attachment deliberately survives the
+// handler for background work launched with the same context.
 
 import type { ExtensionAPI, RegisteredCommand } from "@earendil-works/pi-coding-agent";
-import { report } from "../surfaces/report.ts";
+import { attachReportDetailSink, report } from "../surfaces/report.ts";
+import { createReportDetailSink } from "../surfaces/surfaces.ts";
 
 export function registerPerkCommand(
   pi: ExtensionAPI,
@@ -18,6 +20,7 @@ export function registerPerkCommand(
   pi.registerCommand(name, {
     ...options,
     handler: async (args, ctx) => {
+      attachReportDetailSink(ctx, createReportDetailSink(pi));
       report(ctx, name, "info", "running…");
       await options.handler(args, ctx);
     },

package/extension/substrate/config.ts

@@ -48,11 +48,16 @@ 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`, `review-angle-selector`). Each configured
+   * `learn-analyst`, `adversarial-reviewer`, `review-angle-selector`, `draft-reviewer`,
+   * `harvest-analyst` — consumed by `run_harvest_wave` at execute time — `dream-analyst` and
+   * `dream-reducer` — consumed by `run_dream_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/<name>.md`) is the default.
+   * /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 injection is the mechanism.)
    * A value may carry a `:thinking` suffix (`"anthropic/claude-sonnet-4-5:high"`) or be the
@@ -69,6 +74,11 @@ export interface PerkConfig {
     "learn-analyst"?: string;
     "adversarial-reviewer"?: string;
     "review-angle-selector"?: string;
+    "draft-reviewer"?: string;
+    "harvest-analyst"?: string;
+    "dream-analyst"?: string;
+    "dream-reducer"?: string;
+    "session-auditor"?: string;
   };
   /**
    * Optional `[compaction] objective_threshold` — the context-usage fraction (0,1] that triggers
@@ -86,8 +96,6 @@ export interface PerkConfig {
    */
   providers: {
     plan?: string;
-    todo?: string;
-    askuser?: string;
     footer?: string;
     web?: string;
   };
@@ -268,6 +276,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.
@@ -289,6 +315,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",
@@ -298,6 +327,12 @@ const SUBAGENT_KEYS = [
   "learn-analyst",
   "adversarial-reviewer",
   "review-angle-selector",
+  "draft-reviewer",
+  "harvest-analyst",
+  "dream-analyst",
+  "dream-reducer",
+  // Dev-only: the perk-dev session-audit judgment wave's auditor (dormant in consumer repos).
+  "session-auditor",
 ] as const;
 
 /**
@@ -316,24 +351,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

@@ -3,6 +3,8 @@
 // Node builtins only (so it loads cleanly under `node --test`); shells `git` via `execFileSync`,
 // never with a shell. Fail-open by design: every failure degrades to the caller's `cwd` (or null
 // where stated) rather than throwing — the carriers that use this must never wedge a session.
+// The ONE deliberate fail-closed composition is `revalidationBracket` (documented there): a
+// snapshot proof must treat an unprovable probe as drift, never as "unchanged".
 
 import { execFileSync } from "node:child_process";
 import { isAbsolute, resolve } from "node:path";
@@ -48,6 +50,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;
 
@@ -105,9 +117,90 @@ export function worktreeDirty(cwd: string): boolean | null {
 }
 
 /**
- * The `git log --oneline <fromSha>..HEAD` listing of commits made since `fromSha` — or every
+ * Whether the index carries `assume-unchanged` (a lowercase `git ls-files -v` tag) or
+ * `skip-worktree` (`S`/`s` — sparse checkouts) entries. Either bit hides worktree edits from
+ * `git status --porcelain`, so a status-based cleanliness proof over a flagged index is not a
+ * proof. **Fail-open to null** on any failure (not a repo, git missing) — callers must NOT
+ * conflate null with "no flags". Own `execFileSync` rather than the `git()` helper: `git()`
+ * conflates empty output (an empty index — meaningful here) with failure.
+ */
+export function indexHidesChanges(cwd: string): boolean | null {
+  try {
+    const out = execFileSync("git", ["ls-files", "-v"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return out.split("\n").some((line) => {
+      const tag = line[0];
+      return tag !== undefined && (tag === "S" || (tag >= "a" && tag <= "z"));
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The dream-snapshot revalidation bracket (contracts.md §8.65) — the module's ONE deliberately
+ * **fail-closed** composition (a documented exception to the fail-open charter above): it exists
+ * to PROVE the repository still matches a stamped snapshot, so an unprovable probe must read as
+ * drift, never as "unchanged". The claim is END-STATE equality only — HEAD unchanged, the
+ * working tree clean, and no assume-unchanged/skip-worktree index flags (which would hide edits
+ * from the status probe) at the moment of the check — never mid-window byte immutability (a
+ * transient modify-and-restore inside the window is invisible by design; §8.65's accepted
+ * residuals). `probes` defaults to the real `headSha`/`worktreeDirty`/`indexHidesChanges` and
+ * exists so tests can pin each fail-closed arm independently (from a non-repo fixture the HEAD
+ * arm returns first, making the later null arms reachable only through the seam).
+ */
+export function revalidationBracket(
+  cwd: string,
+  expectedSha: string,
+  probes?: {
+    head?: (cwd: string) => string | null;
+    dirty?: (cwd: string) => boolean | null;
+    flags?: (cwd: string) => boolean | null;
+  },
+): { ok: boolean; detail: string | null } {
+  const head = probes?.head ?? headSha;
+  const dirty = probes?.dirty ?? worktreeDirty;
+  const flags = probes?.flags ?? indexHidesChanges;
+  const actual = head(cwd);
+  if (actual === null) {
+    return {
+      ok: false,
+      detail: "HEAD could not be resolved — cannot prove the snapshot is unchanged",
+    };
+  }
+  if (actual !== expectedSha) {
+    return { ok: false, detail: `HEAD moved from ${expectedSha} to ${actual}` };
+  }
+  const isDirty = dirty(cwd);
+  if (isDirty === null) {
+    return { ok: false, detail: "working-tree cleanliness could not be verified" };
+  }
+  if (isDirty) {
+    return { ok: false, detail: "the working tree is no longer clean" };
+  }
+  const hidden = flags(cwd);
+  if (hidden === null) {
+    return { ok: false, detail: "index flag state could not be verified" };
+  }
+  if (hidden) {
+    return {
+      ok: false,
+      detail:
+        "the index carries assume-unchanged/skip-worktree flag(s) — worktree cleanliness " +
+        "cannot be proven against the snapshot",
+    };
+  }
+  return { ok: true, detail: null };
+}
+
+/**
+ * The `git log --oneline <fromSha>..HEAD` listing of commits now ahead of `fromSha` — or every
  * commit (`git log --oneline HEAD`) when `fromSha` is null (HEAD was unborn at capture time).
- * **Fail-open**: null on failure or when the range is empty.
+ * This is range evidence, not proof that this command created every listed commit. **Fail-open**:
+ * null on failure or when the range is empty.
  */
 export function commitsSince(cwd: string, fromSha: string | null): string | null {
   const range = fromSha === null ? "HEAD" : `${fromSha}..HEAD`;

package/extension/substrate/providers.ts

@@ -2,13 +2,12 @@
 //
 // Twin of perk/substrate/providers.py: both planes parse the SAME bundled file (no codegen). This is the
 // THIRD parsed cross-plane contract (after registry.yaml and bindings.yaml). It is the SUPPORTED
-// SET — the catalog of plan/todo/askuser/footer/web providers perk knows how to wire —
+// SET — the catalog of plan/footer/web providers perk knows how to wire —
 // distinct from the per-repo SELECTION (the flat `[providers]` table in .perk/config.toml).
 //
 // The Python CLI is the authoritative validator (perk/substrate/providers.py); this side does a thin
 // structural parse only — no deep content validation here. `resolveProviders` is CONSUMED by
-// `planMode` (plan-seam registration-time vacating when a foreign plan provider is selected); the
-// todo-seam runtime deferral is likewise live.
+// `planMode` (plan-seam registration-time vacating when a foreign plan provider is selected).
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -24,12 +23,10 @@ export interface Provider {
   packageFilter?: Record<string, unknown>;
 }
 
-export const PROVIDER_SEAMS = ["plan", "todo", "askuser", "footer", "web"] as const;
+export const PROVIDER_SEAMS = ["plan", "footer", "web"] as const;
 
 /** The bundled reference provider ids (the behavior-preserving no-config defaults per seam). */
 export const PERK_PLAN_PROVIDER_ID = "perk-plan";
-export const PERK_CHECKPOINTS_PROVIDER_ID = "perk-checkpoints";
-export const PERK_ASK_USER_PROVIDER_ID = "perk-ask-user";
 export const PERK_FOOTER_PROVIDER_ID = "perk-footer";
 
 /** The foreign `@tombell/pi-plan` plan-provider id. */
@@ -38,12 +35,6 @@ export const TOMBELL_PLAN_PROVIDER_ID = "tombell-plan";
 /** The foreign `@plannotator/pi-extension` plan-provider id (augment-posture adapter selection check). */
 export const PLANNOTATOR_PLAN_PROVIDER_ID = "plannotator-plan";
 
-/** The foreign `@juicesharp/rpiv-todo` todo-provider id. */
-export const JUICESHARP_TODO_PROVIDER_ID = "juicesharp-todo";
-
-/** The foreign `@juicesharp/rpiv-ask-user-question` askuser-provider id (vacate-only interface seam). */
-export const JUICESHARP_ASK_USER_PROVIDER_ID = "juicesharp-ask-user";
-
 /** The foreign `pi-powerline-footer` footer-provider id (vacate-only interface seam). */
 export const POWERLINE_FOOTER_PROVIDER_ID = "powerline-footer";
 
@@ -106,8 +97,6 @@ export function loadProviders(): Provider[] {
  */
 export interface ResolvedProviders {
   plan: Provider;
-  todo: Provider;
-  askuser: Provider;
   footer: Provider;
   web: Provider;
   issues: string[];
@@ -124,20 +113,6 @@ export interface ResolvedProviders {
  */
 const REFERENCE_FALLBACKS: Record<(typeof PROVIDER_SEAMS)[number], Provider> = {
   plan: { id: PERK_PLAN_PROVIDER_ID, seam: "plan", package: null, adapter: null, default: true },
-  todo: {
-    id: PERK_CHECKPOINTS_PROVIDER_ID,
-    seam: "todo",
-    package: null,
-    adapter: null,
-    default: true,
-  },
-  askuser: {
-    id: PERK_ASK_USER_PROVIDER_ID,
-    seam: "askuser",
-    package: null,
-    adapter: null,
-    default: true,
-  },
   footer: {
     id: PERK_FOOTER_PROVIDER_ID,
     seam: "footer",
@@ -183,8 +158,6 @@ function byId(set: Provider[]): Map<string, Provider> {
 export function resolveProviders(
   selection: {
     plan?: string;
-    todo?: string;
-    askuser?: string;
     footer?: string;
     web?: string;
   },
@@ -205,7 +178,7 @@ export function resolveProviders(
     return def;
   };
 
-  const resolveSeam = (seam: "plan" | "todo" | "askuser" | "footer" | "web"): Provider => {
+  const resolveSeam = (seam: "plan" | "footer" | "web"): Provider => {
     const selected = selection[seam];
     if (selected == null) return requireDefault(seam);
     const provider = ids.get(selected);
@@ -222,8 +195,6 @@ export function resolveProviders(
 
   return {
     plan: resolveSeam("plan"),
-    todo: resolveSeam("todo"),
-    askuser: resolveSeam("askuser"),
     footer: resolveSeam("footer"),
     web: resolveSeam("web"),
     issues,

package/extension/substrate/resources.ts

@@ -39,3 +39,14 @@ export function perkVersion(): string {
     return "0.0.0";
   }
 }
+
+/**
+ * The vintage-stamp filter over a perkVersion() value: the version, or undefined for the
+ * "0.0.0" failure sentinel. A `perk_version` stamp claims an EXACT session vintage
+ * (contracts §8.3 — the session-audit read side treats it as the exact basis), so the
+ * self-confessed-unknown sentinel must not masquerade as one; omitting the stamp leaves the
+ * session on the honest timestamp-estimate arm.
+ */
+export function versionStamp(version: string): string | undefined {
+  return version === "0.0.0" ? undefined : version;
+}