@mgiles/perk 2.3.0 → 3.0.0

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;
+}

package/extension/substrate/result.ts

@@ -55,18 +55,26 @@ export function ok<D extends object>(
  * `failFor(ctx, scope, label)` when the content label differs from the report scope). Each call
  * reports loudly (`report(ctx, scope, "error", message, { alsoLog: true })`) and returns the
  * canonical soft failure: content `"<label> failed: <message>"`, details
- * `{ ok: false, error: message, error_type: errorType }`, no `terminate`.
+ * `{ ok: false, error: message, error_type: errorType }`, no `terminate`. `X` is the
+ * `FailDetails` extras hook: `failFor<X>(…)` lets a call attach module-specific fail details
+ * (spread AFTER `error`/`error_type`) — e.g. the learn wave's attempt receipts. Extras stay
+ * optional, so existing extras-free call sites are unchanged.
  */
-export function failFor(
+export function failFor<X extends object = Record<never, never>>(
   target: ReportTarget,
   scope: string,
   label: string = scope,
-): (message: string, errorType: string) => FailResult {
-  return (message, errorType) => {
+): (message: string, errorType: string, extras?: X) => FailResult<X> {
+  return (message, errorType, extras) => {
     report(target, scope, "error", message, { alsoLog: true });
     return {
       content: [{ type: "text", text: `${label} failed: ${message}` }],
-      details: { ok: false, error: message, error_type: errorType },
+      details: {
+        ok: false,
+        error: message,
+        error_type: errorType,
+        ...(extras ?? {}),
+      } as FailDetails<X>,
     };
   };
 }

package/extension/substrate/sessionData.ts

@@ -33,10 +33,10 @@
 // loadable under `node --test`; accepts a minimal structural ctx (`BranchSource & { cwd }`).
 
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import type { ReportTarget } from "../surfaces/report.ts";
-import { sessionDataDir } from "./cache.ts";
+import { atomicWriteFileSync, sessionDataDir } from "./cache.ts";
 import {
   appendWorkflowState,
   type BranchSource,
@@ -115,7 +115,7 @@ export function writeSessionData(
   if (dir === null) return null;
   const path = join(dir, name);
   try {
-    writeFileSync(path, content, "utf8");
+    atomicWriteFileSync(path, content);
   } catch (error) {
     console.error(`perk: warning: could not write session data ${path}: ${error}`);
     return null;

package/extension/substrate/sessionPointers.ts

@@ -13,9 +13,9 @@
 // wedge the save/launch/drive it rides on. Node builtins + cache.ts + git.ts only (loads under
 // `node --test`).
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { runScratchDir } from "./cache.ts";
+import { atomicWriteFileSync, runScratchDir } from "./cache.ts";
 import { mainCheckoutRoot } from "./git.ts";
 
 export const SESSION_POINTERS_FILE = "session-pointers.json";
@@ -121,7 +121,7 @@ export function recordSessionPointer(
     record[klass][site] = pointer;
     const dir = runScratchDir(root, runId);
     mkdirSync(dir, { recursive: true });
-    writeFileSync(sessionPointersPath(root, runId), serialize(record), "utf8");
+    atomicWriteFileSync(sessionPointersPath(root, runId), serialize(record));
     return true;
   } catch (error) {
     console.error(`perk: warning: could not record session pointer (${klass}.${site}): ${error}`);

package/extension/substrate/structuredOutput.ts

@@ -2,16 +2,19 @@
 //
 // pi-ai has no dedicated JSON-mode; structured output is done via tool calling. This module wraps
 // that idiom into two pure, dependency-light, NEVER-throwing helpers:
-//   - `resolveModelAuth(ctx)` reuses the session's configured + authenticated model (the sanctioned
-//     `ModelRegistry.getApiKeyAndHeaders` path), and
-//   - `completeStructured(opts)` builds a single-tool `Context`, calls `complete`, and validates the
-//     returned tool-call arguments against a TypeBox schema.
+//   - `resolveModelAuth(ctx)` reuses the session's configured + authenticated model (the compat
+//     `ModelRegistry.getApiKeyAndHeaders` path — the fallback for hosts without registry
+//     dispatch), and
+//   - `completeStructured(opts)` builds a single-tool `Context`, completes it (via the injected
+//     registry `dispatch` when the host provides one, else the compat `complete`), and validates
+//     the returned tool-call arguments against a TypeBox schema.
 // Both report failure via a soft `{ ok:false, error }` outcome — no throws ever reach the caller, so
 // every consumer can stay fail-safe with a deterministic fallback. The first consumer is
 // `extension/factories/planTitle.ts` (LLM-generated plan-issue titles).
 
 import {
   type Api,
+  type AssistantMessage,
   type Context,
   type Model,
   type Static,
@@ -24,21 +27,54 @@ import {
 // keeps the types. Pi's extension loader aliases both the root and /compat to the compat entry.
 import { complete } from "@earendil-works/pi-ai/compat";
 
-/** Structurally-minimal slice of `ExtensionContext` needed to reuse the session's model + auth. */
+/**
+ * Registry dispatch (mirrors pi ≥ 0.84's `ModelRegistry.complete`): pi owns final request
+ * assembly — resolved auth, nullable headers, credential-resolved `baseUrl`, provider `env` —
+ * end to end. Feature-detect it (`typeof … === "function"`); absent on older hosts.
+ */
+export type ModelDispatch = (
+  model: Model<Api>,
+  context: Context,
+  options: { signal?: AbortSignal; timeoutMs?: number },
+) => Promise<AssistantMessage>;
+
+/**
+ * Structurally-minimal slice of `ExtensionContext` needed to reuse the session's model + auth.
+ * Header values mirror pi-ai's `ProviderHeaders` (`string | null` — null is a header-deletion
+ * marker); `baseUrl`/`env` mirror pi 0.84's `ResolvedRequestAuth`.
+ */
 export interface ModelAuthContext {
   model: Model<Api> | undefined;
   modelRegistry: {
-    getApiKeyAndHeaders(
-      model: Model<Api>,
-    ): Promise<
-      { ok: true; apiKey?: string; headers?: Record<string, string> } | { ok: false; error: string }
+    getApiKeyAndHeaders(model: Model<Api>): Promise<
+      | {
+          ok: true;
+          apiKey?: string;
+          headers?: Record<string, string | null>;
+          baseUrl?: string;
+          env?: Record<string, string>;
+        }
+      | { ok: false; error: string }
     >;
+    /** pi ≥ 0.84 registry dispatch; absent on older hosts (feature-detected, never assumed). */
+    complete?(
+      model: Model<Api>,
+      context: Context,
+      options?: { signal?: AbortSignal; timeoutMs?: number },
+    ): Promise<AssistantMessage>;
   };
 }
 
 /** Resolved model + auth, or a soft failure (no model / unresolved auth). */
 export type ResolvedModelAuth =
-  | { ok: true; model: Model<Api>; apiKey?: string; headers?: Record<string, string> }
+  | {
+      ok: true;
+      model: Model<Api>;
+      apiKey?: string;
+      headers?: Record<string, string | null>;
+      baseUrl?: string;
+      env?: Record<string, string>;
+    }
   | { ok: false; error: string };
 
 /** The generic structured-output outcome — soft success/failure, never a throw. */
@@ -60,7 +96,14 @@ export async function resolveModelAuth(ctx: ModelAuthContext): Promise<ResolvedM
   try {
     const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
     if (!auth.ok) return { ok: false, error: auth.error };
-    return { ok: true, model, apiKey: auth.apiKey, headers: auth.headers };
+    return {
+      ok: true,
+      model,
+      apiKey: auth.apiKey,
+      headers: auth.headers,
+      baseUrl: auth.baseUrl,
+      env: auth.env,
+    };
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : String(err) };
   }
@@ -79,8 +122,17 @@ export interface CompleteStructuredOptions<S extends TSchema> {
   instruction: string;
   /** The payload (e.g. the document to summarize/classify). */
   input: string;
+  /**
+   * Registry dispatch (pi ≥ 0.84). When present it REPLACES the compat `complete` +
+   * apiKey/headers assembly below — pi owns auth end to end, including the credential-resolved
+   * `baseUrl` the fallback path cannot carry.
+   */
+  dispatch?: ModelDispatch;
   apiKey?: string;
-  headers?: Record<string, string>;
+  /** `string | null` mirrors pi-ai's `ProviderHeaders` — a null value deletes a default header. */
+  headers?: Record<string, string | null>;
+  /** Provider-scoped environment values (pi 0.84 `ResolvedRequestAuth.env`), fallback path only. */
+  env?: Record<string, string>;
   signal?: AbortSignal;
   timeoutMs?: number;
 }
@@ -114,14 +166,21 @@ export async function completeStructured<S extends TSchema>(
     tools: [tool],
   };
 
-  let msg: Awaited<ReturnType<typeof complete>>;
+  // Primary: registry dispatch (pi ≥ 0.84 owns auth/headers/baseUrl/env). Fallback: the compat
+  // `complete` with caller-resolved auth — it forwards apiKey/headers/env but has NO `baseUrl`
+  // option, so a credential-resolved endpoint is silently dropped on old hosts (the fallback's
+  // named, pre-existing limitation; the dispatch path is the fix).
+  let msg: AssistantMessage;
   try {
-    msg = await complete(opts.model, context, {
-      apiKey: opts.apiKey,
-      headers: opts.headers,
-      signal: opts.signal,
-      timeoutMs: opts.timeoutMs,
-    });
+    msg = opts.dispatch
+      ? await opts.dispatch(opts.model, context, { signal: opts.signal, timeoutMs: opts.timeoutMs })
+      : await complete(opts.model, context, {
+          apiKey: opts.apiKey,
+          headers: opts.headers,
+          env: opts.env,
+          signal: opts.signal,
+          timeoutMs: opts.timeoutMs,
+        });
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : String(err) };
   }

package/extension/substrate/toolGating.ts

@@ -89,8 +89,9 @@ export const LINEAR_MUTATING_TOOLS: readonly string[] = [
  * (≈830 schema chars — accepted, documented, test-pinned). A later `session_tree` re-apply
  * filters over the original snapshot (which lacks the late names), so a tree navigation drops
  * them — the pre-existing snapshot behavior, unchanged. Child-side tools (`contact_supervisor`,
- * `structured_output`) are out of scope: spawned children are unscoped by design (§8.40
- * adopt-never-impersonates).
+ * `structured_output`) are out of scope for the STAGE census — spawned children stay
+ * stage-unscoped by design (§8.40 adopt-never-impersonates) — but they DO ride READ_ONLY_TOOLS,
+ * because the read-only gate IS inherited by adopted children (see SUBAGENT_CHILD_TOOLS).
  */
 export const SUBAGENT_TOOLS: readonly string[] = [
   "subagent",
@@ -99,6 +100,31 @@ export const SUBAGENT_TOOLS: readonly string[] = [
   "intercom",
 ];
 
+/**
+ * pi-subagents' CHILD-side engine tools. `structured_output` and `contact_supervisor` register
+ * only inside spawned child sessions (the env-keyed prompt-runtime registration — never in
+ * parents, so those names are inert in every gated parent session; `setActiveTools` ignores
+ * unknown names). `subagent_wait` is ALSO registered by the top-level parent extension
+ * (pi-subagents 0.45.1's `registerWaitTool`) — the accepted widening: a wait-only,
+ * non-repo-mutating tool active in gated parents. A gated ADOPTED child (mode inherited via the
+ * `adopt` arm, contracts.md §8.3) must keep them active:
+ *  - `structured_output` is the engine-REQUIRED completion call when the launch carries an
+ *    `outputSchema` — stripping it makes the child physically unable to finish and fails the
+ *    run with `structuredOutputFailed`;
+ *  - `contact_supervisor` is the child→parent intercom door;
+ *  - `subagent_wait` is the fanout-child wait door.
+ * None mutates the repo (`structured_output` writes only the engine's capture file under
+ * `.pi-subagents/` scratch). Census decision, recorded: these names deliberately join NEITHER
+ * PERK_TOOLS nor BORROWED_TOOLS — the stage-filter universe never sees them because children
+ * are stage-unscoped by design (adopt never impersonates a stage), so gate membership is their
+ * only governance surface.
+ */
+export const SUBAGENT_CHILD_TOOLS: readonly string[] = [
+  "structured_output",
+  "contact_supervisor",
+  "subagent_wait",
+];
+
 /**
  * @ff-labs/pi-fff's search tools. BOTH mode name-sets are enumerated (static names, inert
  * when absent — the code_search version-tolerance precedent): warm sessions run pi-fff's
@@ -131,9 +157,12 @@ export const FFF_SEARCH_TOOLS: readonly string[] = [
  *    stage set over a foreign restriction. Pre-existing interplay, recorded, not re-engineered.
  *  - Zero-tool packages: @tombell/pi-diff (commands only), the footer providers, and the hunk
  *    review CLI (not a Pi package) register nothing — nothing to enumerate.
- *  - Single-governance rule: `ask_user_question` must stay OUT of this census — the
- *    @juicesharp/rpiv-ask-user-question provider registers the IDENTICAL name perk does, so the
- *    name-keyed PERK_TOOLS entry already governs both registrations (hygiene-tested).
+ *  - Single-governance rule: a name is governed ONCE — it lives in exactly one census. perk
+ *    registers no same-named `ask_user_question` anymore (the first-party tool is deleted), so
+ *    the name lives HERE, in the borrowed census, not in PERK_TOOLS (hygiene-tested).
+ *    Registration timing nuance: @juicesharp/rpiv-ask-user-question registers the tool at load
+ *    time, then a `hasUI`-keyed reconcile strips/restores it — headless sessions carry no
+ *    `ask_user_question` schema at all.
  *  - @ff-labs/pi-fff (FFF_SEARCH_TOOLS): registration timing load-time (both modes); no
  *    `setFooter` (only a keyed optional-chained `setStatus`); zero bundled skills.
  */
@@ -143,7 +172,12 @@ export const BORROWED_TOOLS: readonly string[] = [
   ...LINEAR_MUTATING_TOOLS,
   ...SUBAGENT_TOOLS,
   ...FFF_SEARCH_TOOLS,
-  "todo", // @juicesharp/rpiv-todo (the juicesharp-todo provider) — load-time
+  // @juicesharp/rpiv-todo (required borrow) — registers at load; its checklist overlay is
+  // `hasUI`-gated (headless-safe).
+  "todo",
+  // @juicesharp/rpiv-ask-user-question (required borrow) — registers at load; strips itself
+  // headlessly (!hasUI reconcile).
+  "ask_user_question",
   // @plannotator/pi-extension: perk never drives its plan phases (the adapter bridges
   // `plan_review` to its event API), so the submit tool is dead weight in stage sessions.
   "plannotator_submit_plan",
@@ -189,23 +223,52 @@ export const READ_ONLY_TOOLS = [
   // FFF local search belongs in read-only exploration (the override names find/grep are
   // already present above; these are the additive tools-and-ui names + multi_grep).
   ...FFF_SEARCH_TOOLS,
-  // The delegation carve-in: the gated objective-plan seed/guidance names the
-  // `perk.objective-explorer` spawn, so `subagent`/`wait` (+ the parent supervisor pair, which
-  // already leaks active into cold-door gated sessions via late registration — keeping
-  // warm-entered gates consistent, and letting the parent answer child `contact_supervisor`
-  // asks) must be reachable while gated. ACCEPTED LENIENCY, deliberately documented: spawned
-  // children are unscoped by design (§8.40 adopt-never-impersonates). The explorer's agent def
-  // is structurally write-blocked (`tools: read, grep, find, ls, bash` frontmatter in
-  // agents/objective-explorer.md), but the `subagent` tool itself can spawn ad-hoc read-write
+  // The delegation carve-in: `subagent`/`wait` (+ the parent supervisor pair, which already
+  // leaks active into cold-door gated sessions via late registration — keeping warm-entered
+  // gates consistent, and letting the parent answer child `contact_supervisor` asks) stay
+  // reachable while gated for the other delegation flows (the gated objective-plan guidance now
+  // names the `explore_objective_node` tool below, not a direct spawn). ACCEPTED LENIENCY,
+  // deliberately documented: spawned children are unscoped by design (§8.40
+  // adopt-never-impersonates), and the `subagent` tool itself can spawn ad-hoc read-write
   // children — a posture choice with NO agent-allowlist backstop, consistent with the arg-blind
   // `curl`/`agent-browser` precedents (contracts.md §8.3).
   ...SUBAGENT_TOOLS,
+  // The explorer-wave carve-in: the gated objective-plan session's OPTIONAL explore step is the
+  // `explore_objective_node` tool — it spawns the read-only `perk.objective-explorer` child over
+  // the already-carved-in SUBAGENT tools (the draft-review-wave precedent) and writes nothing to
+  // the worktree.
+  "explore_objective_node",
+  // The child-side carve-in: gated adopt-children must keep the engine's injected tools — see
+  // SUBAGENT_CHILD_TOOLS.
+  ...SUBAGENT_CHILD_TOOLS,
+  // The draft-review-door carve-in: plan-authoring sessions run GATED, so the
+  // /plan-review-browser companions must be reachable while read-only. `push_annotations` only
+  // POSTs findings to the door-primed local plannotator server (no worktree writes — the
+  // fetch_content cache-write precedent class); the wave pair spawns the read-only
+  // `perk.draft-reviewer` over the already-carved-in SUBAGENT_TOOLS/SUBAGENT_CHILD_TOOLS.
+  "push_annotations",
+  "start_draft_review_wave",
+  "collect_draft_review_wave",
+  // The audit-wave carve-in: the seeded `perk-dev audit judge` session runs GATED (the `audit`
+  // stage is read-only), so `run_audit_wave` must be reachable while read-only. Its one write
+  // (`<bundle>/verdicts.json`) is structurally bound to the cold door's workflow-state
+  // `audit_bundle_dir` — the tool takes NO parameters, so no caller-supplied path exists and a
+  // gated session cannot aim the writer anywhere (contracts.md §8.50).
+  "run_audit_wave",
+  // The harvest-wave carve-in: the seeded learn-harvest session runs GATED (the read-only
+  // objective-author borrow), so `run_harvest_wave` must be reachable while read-only. Its
+  // manifest read is structurally bound to the session's claimed run-scoped scratch path (the
+  // `manifest_path` param is verified against it and any other path refused — the
+  // `run_audit_wave` no-aimable-writer posture, read-side), it spawns the read-only
+  // `perk.harvest-analyst` over the already-carved-in SUBAGENT_TOOLS/SUBAGENT_CHILD_TOOLS, and
+  // it writes nothing to the worktree (contracts.md §8.48).
+  "run_harvest_wave",
 ];
 
 /**
  * Every tool perk itself registers (contracts.md §8.40). Name-keyed: `setActiveTools` ignores
- * unknown names, so a vacated registration (e.g. `ask_user_question` under a foreign
- * `[providers] askuser` selection registers the IDENTICAL name) or an absent tool is inert.
+ * unknown names, so an absent tool is inert (e.g. a borrowed census name whose package stripped
+ * or never registered it — `ask_user_question` in a headless session — has nothing to enable).
  * Stage scoping filters the scoped universe `PERK_TOOLS ∪ BORROWED_TOOLS` — builtins and
  * un-enumerated foreign names pass through untouched (fail-open).
  */
@@ -222,16 +285,33 @@ export const PERK_TOOLS: readonly string[] = [
   "gist_save",
   "learn",
   "run_learn_wave",
-  "ask_user_question",
+  "run_audit_wave",
+  "run_harvest_wave",
   "land",
   "post_pr_review",
   "ready",
-  "resolve_review_threads",
+  "classify_review_feedback",
+  "finalize_address",
+  "explore_objective_node",
   "run_pr_review_wave",
   "run_pr_review_dynamic_wave",
   "submit_pr_review",
+  "start_review_wave",
+  "collect_review_wave",
+  "push_annotations",
+  "start_draft_review_wave",
+  "collect_draft_review_wave",
   "run_ci",
   "submit",
+  // The stacked-delivery warm surface (contracts.md §8.51/§8.56): read + control tools over
+  // the cold `objective stack` workers. Never in READ_ONLY_TOOLS — sync/adopt/recover/land
+  // mutate published branches and PRs; the gated posture is the driving commands' soft
+  // refusal.
+  "objective_stack_status",
+  "objective_stack_sync",
+  "objective_stack_adopt",
+  "objective_stack_recover",
+  "objective_stack_land",
 ];
 
 /**
@@ -253,7 +333,7 @@ const RESEARCH_TOOLS: readonly string[] = [
  * the post-land reconcile drive — `/land` auto-drives `/objective-reconcile` in-session, whose
  * guidance names the reconcile trio, so the trio must be active in every worktree stage). The
  * headless worker also REQUIRES the model-invoked `submit` (implement) /
- * `resolve_review_threads` (address) to reach its completion bar. Borrowed additions: delegation
+ * `finalize_address` (address) to reach its completion bar. Borrowed additions: delegation
  * (SUBAGENT_TOOLS — the `/pr-review`/`/address`/`/submit`-conflict/`/learn` orchestration flows)
  * and `todo` (the foreign checklist overlay the implement-progress discipline rides) are
  * worktree-family only.
@@ -266,17 +346,34 @@ const WORKTREE_STAGE_TOOLS: readonly string[] = [
   "land",
   "learn",
   "run_learn_wave",
-  "resolve_review_threads",
+  "classify_review_feedback",
+  "finalize_address",
   "post_pr_review",
   "run_pr_review_wave",
   "run_pr_review_dynamic_wave",
   "submit_pr_review",
+  // The human review doors' companion tools (/pr-review-terminal, /pr-review-browser): the
+  // review-wave pair + the door-primed annotation push. The plan-stage widening landed via the
+  // draft-review door (/plan-review-browser): the plan-family stage lists carry the draft-wave
+  // pair + push_annotations.
+  "start_review_wave",
+  "collect_review_wave",
+  "push_annotations",
   // The reconcile trio: `/land` auto-drives the objective-reconcile pass inside the CURRENT
   // worktree session (driveReconcileAfterLand), and the manual `/objective-reconcile` gesture is
   // registered globally — both inject guidance naming these three tools.
   "reconcile_objective",
   "add_objective_node",
   "objective_node",
+  // The stacked-delivery quintet: `/objective-sync`/`/objective-recover`/`/objective-land`
+  // drive worktree sessions (post-amend sync from implement/address; recovery and the atomic
+  // landing from anywhere in the PR loop), so their guidance-named tools must be active
+  // across the whole family.
+  "objective_stack_status",
+  "objective_stack_sync",
+  "objective_stack_adopt",
+  "objective_stack_recover",
+  "objective_stack_land",
   ...RESEARCH_TOOLS,
   ...SUBAGENT_TOOLS,
   "todo",
@@ -286,7 +383,8 @@ const WORKTREE_STAGE_TOOLS: readonly string[] = [
  * Per-stage active perk tools for gate-OFF sessions (contracts.md §8.40). Keys = the registry
  * stage ids; an unknown/absent stage id is fail-open (no filtering — version-skew safety).
  * Rationale pins:
- *  - `ask_user_question` is universal (every stage list carries it).
+ *  - `ask_user_question` is universal (every stage list carries it); the name is BORROWED now
+ *    (the @juicesharp questionnaire, via BORROWED_TOOLS — headless sessions carry no schema).
  *  - `plan`/`save` cover the plan-family stage borrowers (`plan from`/`plan replan`/
  *    `learn docs`/`learn code` borrow `plan`; `skills create/refine` borrow `save`).
  *  - `objective-author`/`objective-save` cover `objective replan` + `objective author --from`.
@@ -296,6 +394,12 @@ const WORKTREE_STAGE_TOOLS: readonly string[] = [
  *    three objective stages (the post-save `/objective-reconcile` gesture) AND the worktree
  *    family (the post-land `driveReconcileAfterLand` drive + the manual `/objective-reconcile`
  *    gesture — its guidance names all three).
+ *  - the draft-review companions (`start_draft_review_wave`/`collect_draft_review_wave`/
+ *    `push_annotations`) also ride the two objective stages (§8.23's
+ *    `/objective-review-browser` — gate-OFF coverage: after `objectiveApprovalSave` exits the
+ *    gate mid-flow, late collects/pushes must not dead-end), and `plan_review` rides them
+ *    because the door guidance names it (in both objective stages it routes to the objective
+ *    review arm; the drive-coverage guard forces both the moment the guidance names them).
  */
 export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
   "gist-author": ["ask_user_question", "gist_draft", "gist_save", ...RESEARCH_TOOLS],
@@ -307,6 +411,13 @@ export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
     "reconcile_objective",
     "add_objective_node",
     "objective_node",
+    // The /objective-review-browser companions (gate-OFF coverage: after objectiveApprovalSave
+    // exits the gate mid-flow, late collects/pushes must not dead-end) + plan_review (the door
+    // guidance names it; it routes to the objective review arm here).
+    "start_draft_review_wave",
+    "collect_draft_review_wave",
+    "push_annotations",
+    "plan_review",
     ...RESEARCH_TOOLS,
   ],
   "objective-save": [
@@ -316,6 +427,11 @@ export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
     "reconcile_objective",
     "add_objective_node",
     "objective_node",
+    // The /objective-review-browser companions + plan_review (see the objective-author note).
+    "start_draft_review_wave",
+    "collect_draft_review_wave",
+    "push_annotations",
+    "plan_review",
     ...RESEARCH_TOOLS,
   ],
   "objective-plan": [
@@ -324,17 +440,48 @@ export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
     "plan_review",
     "plan_save",
     "objective_node",
+    "explore_objective_node",
     "reconcile_objective",
     "add_objective_node",
+    // The /plan-review-browser companions (gate-OFF coverage: after approvalSave exits the gate
+    // mid-flow, late collects/pushes must not dead-end — the drive-coverage guard forces this
+    // the moment the guidance names them).
+    "start_draft_review_wave",
+    "collect_draft_review_wave",
+    "push_annotations",
+    ...RESEARCH_TOOLS,
+  ],
+  plan: [
+    "ask_user_question",
+    "plan_draft",
+    "plan_review",
+    "plan_save",
+    // The /plan-review-browser companions (see the objective-plan note).
+    "start_draft_review_wave",
+    "collect_draft_review_wave",
+    "push_annotations",
+    ...RESEARCH_TOOLS,
+  ],
+  save: [
+    "ask_user_question",
+    "plan_draft",
+    "plan_review",
+    "plan_save",
+    // The /plan-review-browser companions (see the objective-plan note).
+    "start_draft_review_wave",
+    "collect_draft_review_wave",
+    "push_annotations",
     ...RESEARCH_TOOLS,
   ],
-  plan: ["ask_user_question", "plan_draft", "plan_review", "plan_save", ...RESEARCH_TOOLS],
-  save: ["ask_user_question", "plan_draft", "plan_review", "plan_save", ...RESEARCH_TOOLS],
   implement: WORKTREE_STAGE_TOOLS,
   submit: WORKTREE_STAGE_TOOLS,
   address: WORKTREE_STAGE_TOOLS,
   land: WORKTREE_STAGE_TOOLS,
   learn: WORKTREE_STAGE_TOOLS,
+  // The dev-only session-audit orchestrator (`perk-dev audit judge`). The session runs GATED
+  // (read-only mode), where this list is inert; it exists for the keys≡registry pin and the
+  // defensive gate-off arm.
+  audit: ["ask_user_question", "run_audit_wave", ...RESEARCH_TOOLS],
 };
 
 /** The read-only marker / custom-message type injected into context while active. */