@mgiles/perk 3.0.0 → 3.1.0

package/extension/factories/objectiveSave.ts

@@ -15,8 +15,10 @@
 // FAILSAFE invocation of the same seam, keeping the legacy drive-the-session behavior as the
 // no-draft fallback (objectives have no transcript scrape by design).
 
+import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { bindingSuffix } from "../substrate/bindingDelivery.ts";
+import { atomicWriteFileSync, ensureRunScratch } from "../substrate/cache.ts";
 import {
   booleanField,
   type ColdJson,
@@ -34,14 +36,24 @@ import { OBJECTIVE_BUDGET_TYPE } from "./objective.ts";
 import {
   DELIVERY_PARAM_SCHEMA,
   type DeliveryChoice,
+  DREAM_REPORT_PARAM_SCHEMA,
   decodeObjectiveSaveParams,
   ROADMAP_PARAM_SCHEMA,
   readObjectiveDraft,
 } from "./objectiveDraft.ts";
+import { resolveDreamReportGate } from "./objectiveDreamReport.ts";
 
 /** The `objective-save` registry stage id (the objectiveAuthor.ts constant's sibling). */
 export const OBJECTIVE_SAVE_STAGE = "objective-save";
 
+/**
+ * The run-scoped dream-report transfer filename (contracts §8.64) — the extension→door handoff
+ * carrying the reviewed CANONICAL parts. The Python mirror is
+ * `perk.learn.dream_companion.DREAM_REPORT_TRANSFER_FILENAME` (parity-pinned by test), beside
+ * the existing `DREAM_MANIFEST_FILENAME` mirror pair.
+ */
+export const DREAM_REPORT_TRANSFER_FILENAME = "dream-report-transfer.json";
+
 /** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
 export interface ObjectiveSaveOk {
   /** `id` is the opaque string objective id (GitHub "7", Linear "ENG-7") — §8.21. */
@@ -70,6 +82,13 @@ function decodeObjectiveCreate(payload: ColdJson): ObjectiveCreatePayload | null
  * The single save implementation both surfaces call. Delegates the GitHub write to the Python cold
  * door, then links the live session (`active_objective` + budget marker). Returns a soft result
  * (never throws); failures set `details.ok = false` and append no linkage.
+ *
+ * `dream_report` is ONE carrier with two sources (§8.63): the direct tool path supplies
+ * `{input}` and the save stamps `generated_at`; the approval path passes the artifact block
+ * through with its stored stamp AND stored parts — the stored parts are byte-compared against
+ * the freshly re-rendered ones, so run-scratch drift or artifact tamper between draft-write
+ * and save refuses `bad_state` (nothing saved, the gate stays on). The parts do NOT cross to
+ * the Python plane yet — companion persistence is deferred (explicit in §8.63, not silent).
  */
 export async function saveObjective(
   pi: ExtensionAPI,
@@ -80,6 +99,7 @@ export async function saveObjective(
     roadmap?: unknown[];
     base?: string;
     delivery?: DeliveryChoice;
+    dream_report?: { input: unknown; generated_at?: string; parts?: string[] };
   },
 ): Promise<ObjectiveSaveResult> {
   const fail = failFor(ctx, "objective-save");
@@ -91,9 +111,52 @@ export async function saveObjective(
     return fail("roadmap must be a JSON array of nodes", "invalid_input");
   }
 
+  // The §8.63 fail-closed re-validation, before anything reaches the cold door. Presence is
+  // the `opts.dream_report === undefined` boundary — an `{input: undefined}` carrier is never
+  // constructed (the execute wraps only a present decoded value; the approval path passes the
+  // validated artifact block).
+  const generatedAt = opts.dream_report?.generated_at ?? new Date().toISOString();
+  const gate =
+    opts.dream_report === undefined
+      ? resolveDreamReportGate(ctx, undefined, generatedAt)
+      : resolveDreamReportGate(ctx, opts.dream_report.input, generatedAt);
+  if (gate.kind === "refuse") {
+    return fail(gate.detail, gate.errorType);
+  }
+  if (gate.kind === "block" && opts.dream_report?.parts !== undefined) {
+    // The approval path: the reviewed (stored) parts must byte-match the re-render against
+    // freshly recovered context — the same stored `generated_at` stamp keeps the comparison
+    // deterministic.
+    if (JSON.stringify(gate.block.parts) !== JSON.stringify(opts.dream_report.parts)) {
+      return fail(
+        "the reviewed report no longer matches the wave state — re-draft and re-review",
+        "bad_state",
+      );
+    }
+  }
+
   const branch = () => branchOf(ctx);
   const runId = rebuildWorkflowState(branch()).run_id ?? "";
 
+  if (gate.kind === "block") {
+    // The §8.64 transfer write (the dream arm only): the reviewed CANONICAL parts cross to the
+    // Python save door through the run-scoped scratch handoff — written atomically BEFORE the
+    // cold door is invoked. A write failure is the soft `scratch_failed` failure (the
+    // runColdDoor stdin-staging precedent): the cold door is NOT invoked, nothing activates,
+    // and the read-only gate stays on. Non-dream saves write nothing (byte-identical).
+    try {
+      const dir = ensureRunScratch(ctx.cwd, runId);
+      const content = `${JSON.stringify(
+        { schema_version: "1", run_id: runId, parts: gate.block.parts },
+        null,
+        2,
+      )}\n`;
+      atomicWriteFileSync(join(dir, DREAM_REPORT_TRANSFER_FILENAME), content);
+    } catch (err) {
+      return fail(`could not stage the dream-report transfer: ${String(err)}`, "scratch_failed");
+    }
+  }
+
   const args = ["objective", "create", "--json"];
   if (opts.title) args.push("--title", opts.title);
   if (opts.base) args.push("--base", opts.base);
@@ -175,6 +238,9 @@ export async function objectiveApprovalSave(
     roadmap: draft.roadmap,
     base: draft.base,
     delivery: draft.delivery,
+    // The approval path passes the artifact block through whole — stored stamp + stored parts
+    // (the save re-validates and byte-compares, §8.63).
+    ...(draft.dream_report !== undefined ? { dream_report: draft.dream_report } : {}),
   });
   let gateExited = false;
   if (result.details.ok && wasReadOnly) {
@@ -231,6 +297,7 @@ export function registerObjectiveSave(pi: ExtensionAPI, gating: ToolGating): voi
             "Optional target branch for this objective's plans (omit to use the repo default).",
         },
         delivery: DELIVERY_PARAM_SCHEMA,
+        dream_report: DREAM_REPORT_PARAM_SCHEMA,
         roadmap: {
           type: "array",
           description:
@@ -251,7 +318,13 @@ export function registerObjectiveSave(pi: ExtensionAPI, gating: ToolGating): voi
           "bad_input",
         );
       }
-      return saveObjective(pi, ctx, decoded);
+      // The direct tool path wraps ONLY a present decoded value as the `{input}` carrier (the
+      // save stamps generated_at); no stored parts, so no byte-compare on this path.
+      const { dream_report, ...rest } = decoded;
+      return saveObjective(pi, ctx, {
+        ...rest,
+        ...(dream_report !== undefined ? { dream_report: { input: dream_report } } : {}),
+      });
     },
   });
 

package/extension/factories/planReview.ts

@@ -29,6 +29,18 @@
 // is always explicit) / backend-unavailable all soft-skip so plan authoring never wedges — those
 // arms keep the present-the-plan + human-`/plan-save` discipline (the manual failsafe).
 //
+// THE LAUNCH CHOOSER (plannotator arms only, §8.23): on an eligible round (injected `WaveLaunch`
+// deps present, plannotator loaded, the review source a validated draft artifact) the tool first
+// asks the human — "Browser review + reviewer wave" vs "Browser review only" — before anything
+// launches. The wave choice collects an optional trimmed custom angle, delegates to the door's
+// guidance-returning open core (openPlanReviewSurface / openObjectiveReviewSurface, injected —
+// never imported: doors value-import this module), and returns the NON-terminating
+// `wave_launched` result carrying the door guidance verbatim; the browser decision then routes
+// through the door's background decision task. Esc ⇒ the plain flavor (never a cancel); abort
+// outranks every dialog result AND the awaited opener (an interrupted turn never reports a
+// launched wave); a null opener return (synchronous port-pick failure, loudly reported in the
+// core) falls open to the plain blocking review in the same call.
+//
 // `ctx.ui.editor` takes NO AbortSignal (unlike select/confirm/input) — `signal?.aborted` is
 // checked between dialogs; an in-flight editor dialog survives a turn abort and its result is
 // discarded (the aborted arm wins). Enter submits in the editor dialog (Shift+Enter = newline),
@@ -69,6 +81,7 @@ import {
   isPlannotatorPlanSelected,
 } from "../adapters/planAdapterPlannotator.ts";
 import type { Result } from "../substrate/result.ts";
+import { readSessionArtifact } from "../substrate/sessionData.ts";
 import type { ToolGating } from "../substrate/toolGating.ts";
 import { paramsOf, stringParam } from "../substrate/toolParams.ts";
 import { applyUnifiedDiff } from "../substrate/unifiedDiff.ts";
@@ -78,7 +91,11 @@ import { readGistDraft, renderGistDraft } from "./gistDraft.ts";
 import { type GistApprovalSaveOutcome, gistApprovalSave } from "./gistSave.ts";
 import { implementHereExit, implementHereGuidance } from "./implementHere.ts";
 import { OBJECTIVE_AUTHOR_STAGE } from "./objectiveAuthor.ts";
-import { readObjectiveDraft, renderObjectiveDraft } from "./objectiveDraft.ts";
+import {
+  OBJECTIVE_DRAFT_ARTIFACT,
+  readObjectiveDraft,
+  renderObjectiveDraft,
+} from "./objectiveDraft.ts";
 import { readNodeClaim } from "./objectivePlan.ts";
 import {
   OBJECTIVE_SAVE_STAGE,
@@ -472,6 +489,92 @@ export function applyPlannotatorDirectEdits(
   return { outcome, reviewedPlan: basePlan, edited: false, directEditsFailed: false };
 }
 
+// ------------------------------------------------------ the launch chooser (the wave arm)
+
+/**
+ * The injected wave-launch deps (composed in index.ts from the door exports — structural on
+ * purpose: this module imports NOTHING from door modules, avoiding the value-import cycle;
+ * `planReviewBrowser.ts` already value-imports this module). `present` is the plannotator
+ * presence probe (`plannotatorPresent(pi)` at the call site); `plan`/`objective` are the
+ * guidance-returning door open cores (`openPlanReviewSurface` / `openObjectiveReviewSurface`) —
+ * one open path, byte-identical door semantics (contracts.md §8.23). `null` from an opener is
+ * the synchronous port-pick failure (already loudly reported inside the core) — the caller
+ * falls open to the plain blocking review.
+ */
+export interface WaveLaunch {
+  present(): boolean;
+  plan(ctx: ExtensionContext, opts: { draft: string; custom?: string }): Promise<string | null>;
+  objective(
+    ctx: ExtensionContext,
+    opts: { rendered: string; artifactRaw: string; custom?: string },
+  ): Promise<string | null>;
+}
+
+/** The minimal structural `ctx.ui` subset the launch chooser needs (both dialogs signal-aware). */
+export interface ReviewLaunchUI {
+  select(
+    title: string,
+    options: string[],
+    opts?: { signal?: AbortSignal },
+  ): Promise<string | undefined>;
+  input(
+    title: string,
+    placeholder?: string,
+    opts?: { signal?: AbortSignal },
+  ): Promise<string | undefined>;
+}
+
+/** The launch chooser's outcome: the review flavor (never a cancel), or the aborted turn. */
+export type ReviewLaunchChoice =
+  | { launch: "plain" }
+  | { launch: "wave"; custom?: string }
+  | { launch: "aborted" };
+
+const LAUNCH_WAVE = "Browser review + reviewer wave";
+const LAUNCH_PLAIN = "Browser review only";
+const CUSTOM_ANGLE_TITLE = "Custom review angle (optional — Enter to skip)";
+
+/**
+ * The launch chooser (pure over the injected ui slice — offline-testable): every eligible
+ * plannotator round asks the human whether the browser review launches WITH the streamed
+ * reviewer wave; the wave choice then asks for an optional custom review angle. Esc/dismiss
+ * anywhere selects a FLAVOR, never cancels the review (Esc at the chooser ⇒ plain; Esc/blank at
+ * the angle input ⇒ wave with no custom lane — the input is `.trim()`'d before blank detection,
+ * the door handlers' exact discipline). ABORT OUTRANKS EVERYTHING: `signal?.aborted` is checked
+ * at entry and re-checked immediately after each awaited dialog, BEFORE interpreting its result
+ * (the `runFirstPartyReview` discipline) — a conforming caller can never launch a browser or
+ * enter a blocking review after the turn was interrupted. No other return paths exist.
+ */
+export async function chooseReviewLaunch(
+  ui: ReviewLaunchUI,
+  subjectNoun: string,
+  signal?: AbortSignal,
+): Promise<ReviewLaunchChoice> {
+  if (signal?.aborted) return { launch: "aborted" };
+  const picked = await ui.select(`${subjectNoun} review launch`, [LAUNCH_WAVE, LAUNCH_PLAIN], {
+    signal,
+  });
+  if (signal?.aborted) return { launch: "aborted" }; // abort outranks Esc AND any selection
+  if (picked !== LAUNCH_WAVE) return { launch: "plain" }; // Esc/dismiss = the plain flavor
+  const raw = await ui.input(CUSTOM_ANGLE_TITLE, undefined, { signal });
+  if (signal?.aborted) return { launch: "aborted" }; // abort outranks the input result too
+  const custom = (raw ?? "").trim();
+  return custom.length > 0 ? { launch: "wave", custom } : { launch: "wave" };
+}
+
+/**
+ * The NON-terminating wave-launched result: the door core's guidance rides back verbatim as the
+ * tool text (same templates, same binding suffix — the model behaves identically whether the
+ * human summoned the door or chose the wave inside `plan_review`), and the human's browser
+ * decision routes through the door's background decision task — never through this call.
+ */
+function waveLaunchedResult(subject: ReviewSubject, guidance: string): ToolResult {
+  return {
+    content: [{ type: "text", text: guidance }],
+    details: { ok: true, status: "wave_launched", ...subject.detailsExtra },
+  };
+}
+
 // ----------------------------------------------------------------- the first-party review core
 
 /** The minimal structural `ctx.ui` subset the first-party review needs (the ciExecutor.ts pure-core + injected-fakes recipe). */
@@ -650,10 +753,19 @@ export async function executeObjectiveReview(
   gating: ToolGating,
   bridge: { review(plan: string, signal?: AbortSignal): Promise<ReviewOutcome> },
   signal?: AbortSignal,
+  wave?: WaveLaunch,
 ): Promise<ToolResult> {
   // 1. Headless → soft skip (fail-open; never wedges CI/supervisor runs on an interactive UI).
   if (!ctx.hasUI) return skipResult();
-  // 2. The draft artifact is the sole review source — no draft → soft skip with the
+  // 2. The wave arm's stale-guard baseline is captured BEFORE the validated read below (the
+  //    objective door's fail-closed ordering): the rendered bytes always derive from a read at
+  //    or after this baseline, so a concurrent objective_draft write between the two reads makes
+  //    the browsed render NEWER than the baseline and routeObjectiveReviewDecision's existing
+  //    guard refuses the approval — the reverse order would fail open (approve unreviewed
+  //    bytes). Raw artifact bytes on purpose: the save-authoritative surface catches
+  //    render-invisible changes.
+  const baseline = readSessionArtifact(ctx, OBJECTIVE_DRAFT_ARTIFACT);
+  // 3. The draft artifact is the sole review source — no draft → soft skip with the
   //    objective_draft redirect.
   const draft = readObjectiveDraft(ctx);
   if (draft === null) {
@@ -675,13 +787,35 @@ export async function executeObjectiveReview(
       },
     };
   }
-  // 3. The reviewed bytes are the RENDERED markdown (prose + roadmap table) — never raw JSON.
+  // 4. The reviewed bytes are the RENDERED markdown (prose + roadmap table) — never raw JSON.
   const rendered = renderObjectiveDraft(draft);
-  // 4. Backend dispatch (mirrors the plan path): plannotator-selected → the bridge; ANY other
+  // 5. Backend dispatch (mirrors the plan path): plannotator-selected → the bridge; ANY other
   //    selection → the first-party editor, view-only.
   const sig = signal ?? ctx.signal;
   let outcome: ReviewOutcome;
   if (isPlannotatorPlanSelected(ctx.cwd)) {
+    // The launch chooser (contracts.md §8.23): every eligible round the human picks with/without
+    // the streamed reviewer wave BEFORE anything launches. Eligibility is drafts-only — the wave
+    // door stale-guards the raw artifact baseline, so a null baseline keeps the plain path
+    // (silently: there is no forced mode to warn about).
+    if (wave?.present() && baseline !== null) {
+      const choice = await chooseReviewLaunch(ctx.ui, "Objective", sig);
+      if (choice.launch === "aborted") return objectiveReviewOutcomeResult({ status: "aborted" });
+      if (choice.launch === "wave") {
+        const guidance = await wave.objective(ctx, {
+          rendered,
+          artifactRaw: baseline.content,
+          ...(choice.custom !== undefined ? { custom: choice.custom } : {}),
+        });
+        // Abort outranks the opener result too: a turn interrupted during the awaited open must
+        // never report a successful launch (the door's own bridge abort handling settles the
+        // background tasks and clears the primed surfaces).
+        if (sig?.aborted) return objectiveReviewOutcomeResult({ status: "aborted" });
+        if (guidance !== null) return waveLaunchedResult(OBJECTIVE_SUBJECT, guidance);
+        // null = the synchronous port-pick failure (already loudly reported inside the core) —
+        // fall open to the plain blocking review in the same call: the review never wedges.
+      }
+    }
     outcome = await bridge.review(rendered, sig);
     // APPROVE + Direct Edits (browser edits of the RENDERED markdown), checked BEFORE the
     // approved-save routing (the approved-first discipline): the save seam re-reads the
@@ -731,7 +865,7 @@ export async function executeObjectiveReview(
     });
     outcome = fp.outcome;
   }
-  // 5. An APPROVED decision (either backend) wires into the objectiveApprovalSave seam (the
+  // 6. An APPROVED decision (either backend) wires into the objectiveApprovalSave seam (the
   //    STRUCTURED artifact is re-read at save time — never the rendered bytes; auto-save → D1a
   //    gate exit → terminating result); everything else maps via objectiveReviewOutcomeResult.
   //    Approved-first routing: objectiveReviewOutcomeResult's completed case renders DENIED.
@@ -906,6 +1040,7 @@ export async function executePlanReview(
   bridge: { review(plan: string, signal?: AbortSignal): Promise<ReviewOutcome> },
   params: unknown,
   signal?: AbortSignal,
+  wave?: WaveLaunch,
 ): Promise<ToolResult> {
   // Tool-boundary decode, in this tool's native fail-open vocabulary: a MISTYPED
   // `plan` (or non-object params) skip-shapes (`reason: "bad_input"`) without reviewing; an
@@ -937,7 +1072,7 @@ export async function executePlanReview(
   //    the gist arm (the rendered gist draft).
   const launchedStage = rebuildWorkflowState(branchOf(ctx)).stage;
   if (launchedStage === OBJECTIVE_AUTHOR_STAGE || launchedStage === OBJECTIVE_SAVE_STAGE) {
-    return executeObjectiveReview(pi, ctx, gating, bridge, signal ?? ctx.signal);
+    return executeObjectiveReview(pi, ctx, gating, bridge, signal ?? ctx.signal, wave);
   }
   if (launchedStage === GIST_AUTHOR_STAGE) {
     return executeGistReview(pi, ctx, gating, bridge, signal ?? ctx.signal);
@@ -974,6 +1109,28 @@ export async function executePlanReview(
   let edited = false;
   let directEditsFailed = false;
   if (isPlannotatorPlanSelected(ctx.cwd)) {
+    // The launch chooser (contracts.md §8.23): every eligible round the human picks with/without
+    // the streamed reviewer wave BEFORE anything launches. Eligibility is drafts-only — the wave
+    // door reviews and stale-guards the validated artifact, so a param-tier source keeps the
+    // plain path (silently: there is no forced mode to warn about; the `wave === undefined` arm
+    // is defensive/test-only and behaves identically).
+    if (wave?.present() && src.source === "plan-draft") {
+      const choice = await chooseReviewLaunch(ctx.ui, "Plan", sig);
+      if (choice.launch === "aborted") return reviewOutcomeResult({ status: "aborted" });
+      if (choice.launch === "wave") {
+        const guidance = await wave.plan(ctx, {
+          draft: src.plan,
+          ...(choice.custom !== undefined ? { custom: choice.custom } : {}),
+        });
+        // Abort outranks the opener result too: a turn interrupted during the awaited open must
+        // never report a successful launch (the door's own bridge abort handling settles the
+        // background tasks and clears the primed surfaces).
+        if (sig?.aborted) return reviewOutcomeResult({ status: "aborted" });
+        if (guidance !== null) return waveLaunchedResult(PLAN_SUBJECT, guidance);
+        // null = the synchronous port-pick failure (already loudly reported inside the core) —
+        // fall open to the plain blocking review in the same call: the review never wedges.
+      }
+    }
     outcome = await bridge.review(src.plan, sig);
     // APPROVE + Direct Edits (browser plan edits, contracts.md §8.23): mechanically apply the
     // reviewer's diff via the shared helper (the first-party pre-verdict write-back, replayed
@@ -1032,8 +1189,10 @@ export async function executePlanReview(
  * Register `plan_review` — perk's universal review door. In READ_ONLY_TOOLS so it is callable
  * INSIDE plan mode (the whole point — review happens before the gate ever comes off). Fail-open
  * everywhere: headless / dismissed / backend-unavailable all soft-skip so authoring never wedges.
+ * `wave` is the injected wave-launch deps (index.ts composes them from the door open cores);
+ * absent ⇒ the chooser never appears and every path is byte-stable.
  */
-export function registerPlanReview(pi: ExtensionAPI, gating: ToolGating): void {
+export function registerPlanReview(pi: ExtensionAPI, gating: ToolGating, wave?: WaveLaunch): void {
   const bridge = createPlannotatorBridge(pi.events);
 
   pi.registerTool({
@@ -1044,14 +1203,18 @@ export function registerPlanReview(pi: ExtensionAPI, gating: ToolGating): void {
       "selected, otherwise perk's in-TUI editor review — and wait for the human decision. " +
       "Reviews the validated plan-draft artifact (keep it current with plan_draft); on approval " +
       "the plan is auto-saved and the turn terminates. On deny, revise per the returned " +
-      "feedback, rewrite the draft with plan_draft, and call again. No-op skip when the session " +
-      "is headless or the review is dismissed.",
+      "feedback, rewrite the draft with plan_draft, and call again. On the Plannotator surface " +
+      "the human may first opt into a streamed reviewer wave — the call then returns immediately " +
+      'with wave guidance (status "wave_launched") to follow in the same turn, and the browser ' +
+      "decision routes back automatically. No-op skip when the session is headless or the " +
+      "review is dismissed.",
     promptSnippet: "Request a human review of the working plan draft",
     promptGuidelines: [
       "Keep the working draft current with plan_draft — the validated plan-draft artifact is what plan_review reviews AND auto-saves; the plan param is only a fallback when no draft exists.",
       "Call plan_review only when the plan is decision-complete.",
       "On a DENIED review, revise per the feedback, rewrite the draft with plan_draft, then call plan_review again.",
       "On an APPROVED plan_review, the plan is auto-saved and the turn ends — never re-dump the plan as a final message and never tell the user to run /plan-save; relay the save outcome instead.",
+      "On a wave_launched result (the human opted into the reviewer wave), follow the returned guidance in the same turn — launch the wave and relay its findings; the human's browser decision routes back automatically, so never re-call plan_review while that browser review is open.",
       "If plan_review reports it was skipped or unavailable (headless, dismissed), fall back to presenting the complete plan; the human runs /plan-save (the manual failsafe).",
     ],
     executionMode: "sequential",
@@ -1068,7 +1231,7 @@ export function registerPlanReview(pi: ExtensionAPI, gating: ToolGating): void {
       },
     },
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      return executePlanReview(pi, ctx, gating, bridge, params, signal);
+      return executePlanReview(pi, ctx, gating, bridge, params, signal, wave);
     },
   });
 }

package/extension/index.ts

@@ -15,14 +15,19 @@ 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 { registerDreamWave } from "./doors/dreamWaveTools.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 {
+  openObjectiveReviewSurface,
+  registerObjectiveReviewBrowser,
+} from "./doors/objectiveReviewBrowser.ts";
 import { registerObjectiveStack } from "./doors/objectiveStack.ts";
-import { registerPlanReviewBrowser } from "./doors/planReviewBrowser.ts";
+import { plannotatorPresent } from "./doors/plannotatorHandoff.ts";
+import { openPlanReviewSurface, registerPlanReviewBrowser } from "./doors/planReviewBrowser.ts";
 import { registerPrReview } from "./doors/prReview.ts";
 import { registerPrReviewBrowser } from "./doors/prReviewBrowser.ts";
 import { registerPrReviewDynamic } from "./doors/prReviewDynamic.ts";
@@ -46,6 +51,7 @@ 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 { createAgentScratchProvisioner, registerAgentScratch } from "./substrate/agentScratch.ts";
 import { registerBindingDelivery } from "./substrate/bindingDelivery.ts";
 import {
   atomicWriteFileSync,
@@ -77,7 +83,9 @@ import {
   createPerkStatus,
   installPerkFooter,
   latestCacheHitRate,
+  REPORT_DETAIL_TYPE,
   registerTranscriptRenderer,
+  reportDetailEntryRenderer,
   workflowStateEntryRenderer,
 } from "./surfaces/surfaces.ts";
 import { registerBtw } from "./vendor/btw/btw.ts";
@@ -122,12 +130,18 @@ export default function (pi: ExtensionAPI) {
   // both session_start AND session_tree below. enter/exit are the surface the gated stages consume.
   const gating = registerToolGating(pi);
 
+  // Run-owned disposable scratch guidance for every eligible write-capable model turn. One
+  // activation-scoped provisioner shares retry/warning suppression with the isolated /btw side
+  // session; no model tool or process-global temp environment is introduced.
+  const agentScratch = createAgentScratchProvisioner();
+  registerAgentScratch(pi, agentScratch);
+
   // Vendored `btw`: a `/btw` human-only side-chat popover backed by an isolated in-memory
   // AgentSession. Takes `gating` for the gate-mirror — its side-session toolset + cache key follow
   // perk's read-only gate (`sideSessionTools`), so the isolated session never bypasses the read-only
   // guarantee. Its `ctx.ui.custom` overlay is the ONE sanctioned charter exception (§6 D6): human-
   // invoked only, `hasUI`-gated, no model tool, not a stage/door — never machine-reachable.
-  registerBtw(pi, gating);
+  registerBtw(pi, gating, agentScratch);
 
   // Vendored `whimsical`: flavors pi's default working-message label with a random phrase per
   // turn, via the headless-no-op `setWorkingMessage` surfaces seam. Always on, no config toggle.
@@ -156,8 +170,15 @@ export default function (pi: ExtensionAPI) {
   // `plan_review`, perk's UNIVERSAL review door: plannotator-selected → the event-bus
   // bridge; ANY other selection → the first-party in-TUI editor review. It takes `gating` only to
   // COMPOSE the approvalSave seam on an APPROVED review (auto-save → D1a gate exit) — Invariant 1
-  // holds: the door composes the gate through the seam, never owns it.
-  registerPlanReview(pi, gating);
+  // holds: the door composes the gate through the seam, never owns it. The injected wave-launch
+  // deps power the plannotator launch chooser (§8.23): the presence probe + the two door open
+  // cores are composed HERE so planReview.ts imports nothing from door modules (the value-import
+  // cycle break — planReviewBrowser.ts already value-imports planReview.ts).
+  registerPlanReview(pi, gating, {
+    present: () => plannotatorPresent(pi),
+    plan: (ctx, opts) => openPlanReviewSurface(pi, ctx, gating, opts),
+    objective: (ctx, opts) => openObjectiveReviewSurface(pi, ctx, gating, opts),
+  });
 
   // Objective-author context injection (the objective mirror of plan mode's authoring
   // half). Keyed off (read-only gate AND stage === objective-author); planMode defers to it.
@@ -190,9 +211,10 @@ export default function (pi: ExtensionAPI) {
   // publisher below; the footer reads it back via get/subscribe.
   const perkStatus = createPerkStatus();
 
-  // 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.
+  // The generic full report-detail entry and the `perk:workflow-state` transition marker. Renderer
+  // bodies live in surfaces.ts; registration is wiring through the pre-0.80.4-safe seam. The report
+  // family is appended by command-attached sinks; one workflow registration covers every appender.
+  registerTranscriptRenderer(pi, REPORT_DETAIL_TYPE, reportDetailEntryRenderer);
   registerTranscriptRenderer(pi, WORKFLOW_STATE_TYPE, workflowStateEntryRenderer);
 
   // The hunk watch feedback receiver controller (contracts §8.58) — factory-scoped (no module
@@ -209,7 +231,8 @@ export default function (pi: ExtensionAPI) {
     const sessionFile = ctx.sessionManager.getSessionFile();
     const currentSessionId = sessionFile ? basename(sessionFile) : null;
 
-    // Headless-safe linkage failure: loud (notify if UI + stderr), non-fatal, leaves unclaimed.
+    // Terminal-safe linkage failure: managed headline when headful, complete stderr when headless
+    // (plus the explicit RPC mirror); non-fatal and leaves the run unclaimed.
     const reportError = (message: string) => {
       report(ctx, "workflow-state linkage error", "error", message, { alsoLog: true });
     };
@@ -263,8 +286,20 @@ export default function (pi: ExtensionAPI) {
         }
       }
     } else if (decision.action === "fork") {
-      // Inherited a run_id from a different session file → isolate the child's scratch.
-      ensureRunScratch(ctx.cwd, decision.childRunId);
+      // Inherited a run_id from a different session file → isolate the child's scratch. A static
+      // redirect or filesystem failure is loud but does not prevent the derived workflow identity
+      // from settling; later eligible turns retry through the agent-scratch resolver.
+      try {
+        ensureRunScratch(ctx.cwd, decision.childRunId);
+      } catch (error) {
+        report(
+          ctx,
+          "run scratch",
+          "warning",
+          `could not create fork run root for ${decision.childRunId}: ${String(error)}`,
+          { alsoLog: true },
+        );
+      }
       const data: WorkflowState = {
         run_id: decision.childRunId,
         pi_session_id: currentSessionId ?? undefined,
@@ -281,7 +316,17 @@ export default function (pi: ExtensionAPI) {
       // the launched session: never re-consume the handoff (its pi_session_id keeps the true
       // claimer), no `stage` (no stage impersonation / stage-binding injection), and no
       // implementation/main pointer capture (resolveRunStage stays null for adopt).
-      ensureRunScratch(ctx.cwd, decision.childRunId);
+      try {
+        ensureRunScratch(ctx.cwd, decision.childRunId);
+      } catch (error) {
+        report(
+          ctx,
+          "run scratch",
+          "warning",
+          `could not create adopted run root for ${decision.childRunId}: ${String(error)}`,
+          { alsoLog: true },
+        );
+      }
       const data: WorkflowState = {
         run_id: decision.childRunId,
         pi_session_id: currentSessionId ?? undefined,
@@ -564,6 +609,7 @@ export default function (pi: ExtensionAPI) {
   registerReviewWaveTools(pi);
   registerAuditWave(pi);
   registerHarvestWave(pi);
+  registerDreamWave(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
@@ -605,9 +651,10 @@ export default function (pi: ExtensionAPI) {
   // (The deterministic objective mechanics live in the Python plane: `perk objective …`.)
   registerObjective(pi, perkStatus);
 
-  // The warm `/commit-and-compact` utility door: drive a commit of the work so far, then
-  // compact the session once HEAD has actually advanced (clean/read-only trees compact
-  // immediately; no commit → compaction skipped, loudly). Human-only — no tool twin.
+  // The warm `/commit-and-compact` utility door: drive a commit of the work so far, compact once
+  // a successful outcome is known, then completion-gate an automatic evidence-first continuation
+  // (clean/read-only trees compact immediately; no commit → no compaction or continuation).
+  // Human-only — no tool twin.
   registerCommitAndCompact(pi, gating);
 
   // The warm `objective_save` door: the `objective_save` tool + `/objective-save` command