@mgiles/perk 3.0.0 → 3.2.0

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";
@@ -30,6 +35,7 @@ import { registerPrReviewTerminal } from "./doors/prReviewTerminal.ts";
 import { registerReady } from "./doors/ready.ts";
 import { registerReviewWaveTools } from "./doors/reviewWaveTools.ts";
 import { registerSelfcheck } from "./doors/selfcheck.ts";
+import { registerOpenStackReview, registerStackReviewBrowser } from "./doors/stackReviewBrowser.ts";
 import { registerSubmit } from "./doors/submit.ts";
 import { registerSubmitPrReview } from "./doors/submitPrReview.ts";
 import { registerGistAuthor } from "./factories/gistAuthor.ts";
@@ -46,6 +52,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 +84,9 @@ import {
   createPerkStatus,
   installPerkFooter,
   latestCacheHitRate,
+  REPORT_DETAIL_TYPE,
   registerTranscriptRenderer,
+  reportDetailEntryRenderer,
   workflowStateEntryRenderer,
 } from "./surfaces/surfaces.ts";
 import { registerBtw } from "./vendor/btw/btw.ts";
@@ -122,12 +131,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 +171,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 +212,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 +232,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 });
     };
@@ -237,6 +261,21 @@ export default function (pi: ExtensionAPI) {
       if (handoff === null || handoff.run_id !== decision.runId) {
         reportError(`handoff missing or mismatched for run ${decision.runId}`);
       } else {
+        // The objective-plan cold door's handoff_extra carries the node link
+        // (objective_id/node_id): persist it as the objective_node_claim so the implement-here
+        // exits are structurally suppressed in COLD objective-plan sessions too (the warm
+        // `objective_node` tool records the claim; a cold factory session never calls it — the
+        // door marked the node before launch). Blank/absent ids persist nothing; the claim
+        // clears on a successful node-linked save exactly as the warm-recorded one does.
+        const handoffObjective = handoff.objective_id;
+        const handoffNode = handoff.node_id;
+        const nodeClaim =
+          typeof handoffObjective === "string" &&
+          handoffObjective.trim() !== "" &&
+          typeof handoffNode === "string" &&
+          handoffNode.trim() !== ""
+            ? { objective: handoffObjective, node: handoffNode }
+            : undefined;
         const data: WorkflowState = {
           run_id: decision.runId,
           pi_session_id: currentSessionId ?? undefined,
@@ -245,6 +284,7 @@ export default function (pi: ExtensionAPI) {
           // Record the launched stage so the interior can tell e.g. objective-author from plan
           // (both are read-only) and inject the right authoring context (planMode vs objectiveAuthor).
           stage: handoff.stage,
+          ...(nodeClaim !== undefined ? { objective_node_claim: nodeClaim } : {}),
         };
         const okAppend = appendWorkflowState(pi, ctx, {
           data,
@@ -263,8 +303,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 +333,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,
@@ -527,7 +589,9 @@ export default function (pi: ExtensionAPI) {
   registerSubmit(pi);
 
   // The warm `ready` door: the deliberate draft→ready review gate (submit keeps draft).
-  registerReady(pi);
+  // Takes `gating`: the warm ready→reconcile continuation refuses (loudly) to drive the
+  // ready-time pass into a read-only session (contracts.md §8.66).
+  registerReady(pi, gating);
 
   // Warm doors: `land` merges + sets pending-learn; `learn` clears it (TS-only).
   registerLand(pi);
@@ -564,6 +628,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
@@ -584,6 +649,12 @@ export default function (pi: ExtensionAPI) {
   // human's own platform-post from the UI, with `submit_pr_review` for request-changes only.
   registerPrReviewBrowser(pi);
 
+  // The warm `/stack-review-browser` door + its cold-launch twin (`open_stack_review`): the
+  // stacked-PR browser review over the combined base→top diff — one reviewer wave with
+  // `stack: true`, then judgment-routed per-PR posting through `submit_pr_review`.
+  registerStackReviewBrowser(pi);
+  registerOpenStackReview(pi);
+
   // The warm `/plan-review-browser` door: the summonable streaming draft review — the
   // plannotator plan-review browser on the working plan draft, draft reviewers streaming
   // phrase-anchored findings in; APPROVE auto-saves via the approvalSave seam, DENY returns a
@@ -605,9 +676,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