@mgiles/perk 2.3.0 → 3.1.0

package/extension/factories/planReview.ts

@@ -29,13 +29,26 @@
 // 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),
 // so the dialog titles carry the key hints — pi renders no other affordance.
 //
-// THE OBJECTIVE ARM: an objective-author session (read-only, stage
-// `objective-author`) routes through `executeObjectiveReview` instead of the plan path — the
+// THE OBJECTIVE ARM: an objective-authoring session (read-only, stage `objective-author` or
+// `objective-save` — the two stages whose working draft IS the objective draft; neither carries
+// `plan_draft`) routes through `executeObjectiveReview` instead of the plan path — the
 // reviewed bytes are the RENDERED objective draft (`readObjectiveDraft` + `renderObjectiveDraft`,
 // objectiveDraft.ts — never raw JSON, never the `plan` param, never the transcript; no draft
 // soft-skips with `reason: "no_objective_draft"`). Dispatch mirrors the plan path (plannotator
@@ -49,7 +62,11 @@
 // `executeGistReview` the same way — the reviewed bytes are the RENDERED gist draft
 // (`readGistDraft` + `renderGistDraft`, gistDraft.ts), first-party VIEW-ONLY, implement-here
 // never offered, APPROVED → the `gistApprovalSave` seam (gistSave.ts), no draft soft-skips with
-// `reason: "no_gist_draft"`.
+// `reason: "no_gist_draft"`. Plannotator approve-with-Direct-Edits mirrors the objective arm:
+// the save seam re-reads the STRUCTURED gist artifact, so rendered edits cannot be folded back
+// mechanically — the arm SKIPS the save and returns one model-mediated revise round (fold each
+// hunk into the matching `gist_draft` field — title heading → `title`, `Scope:` line → `scope`,
+// prose → `prose` — then re-review to confirm).
 //
 // INVARIANTS HELD: never calls `setActiveTools`, never registers a `tool_call` handler, never
 // restamps `cache.plan-ref.provider`. The door composes the gate AND the save EXCLUSIVELY
@@ -64,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";
@@ -73,9 +91,17 @@ 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 { type ObjectiveApprovalSaveOutcome, objectiveApprovalSave } from "./objectiveSave.ts";
+import {
+  OBJECTIVE_SAVE_STAGE,
+  type ObjectiveApprovalSaveOutcome,
+  objectiveApprovalSave,
+} from "./objectiveSave.ts";
 import { writePlanDraft } from "./planDraft.ts";
 import { type ApprovalSaveOutcome, approvalSave, resolvePlanSource } from "./planSave.ts";
 
@@ -410,9 +436,148 @@ export function implementHereResult(
   };
 }
 
+// ------------------------------------------------------ the plannotator Direct-Edits apply
+
+/**
+ * The shared plannotator APPROVE mechanical-apply path (contracts.md §8.23): inspect an
+ * APPROVED outcome's feedback for a `# Direct Edits` section and mechanically apply the
+ * reviewer's diff to the exact bytes reviewed (`basePlan`), writing the patched bytes back to
+ * the draft (reviewed bytes == artifact bytes == saved bytes). Consumed by `executePlanReview`'s
+ * plannotator arm AND the `/plan-review-browser` door — one apply path, byte-identical
+ * semantics:
+ *
+ * - only an `approved` outcome WITH feedback is inspected (anything else passes through
+ *   verbatim);
+ * - a clean extract + apply + write-back swaps `reviewedPlan` to the patched bytes, sets
+ *   `edited: true`, and strips the applied section from the returned outcome's feedback (only
+ *   the annotation remainder survives — the applied diff must never render as "apply these
+ *   exact changes" guidance);
+ * - a seen-but-unhonorable heading (or a failed apply / write-back) sets
+ *   `directEditsFailed: true` with the plan left verbatim (the caller renders the loud warning;
+ *   the diff stays in the surfaced feedback for a manual follow-up).
+ */
+export function applyPlannotatorDirectEdits(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  outcome: Extract<ReviewOutcome, { status: "completed" }>,
+  basePlan: string,
+): {
+  outcome: Extract<ReviewOutcome, { status: "completed" }>;
+  reviewedPlan: string;
+  edited: boolean;
+  directEditsFailed: boolean;
+} {
+  if (!outcome.approved || outcome.feedback === undefined) {
+    return { outcome, reviewedPlan: basePlan, edited: false, directEditsFailed: false };
+  }
+  const section = extractDirectEdits(outcome.feedback);
+  if (section !== null) {
+    const patched = applyUnifiedDiff(basePlan, section.diff);
+    if (patched !== null && writePlanDraft(pi, ctx, patched).details.ok) {
+      return {
+        outcome: { ...outcome, feedback: section.remainder },
+        reviewedPlan: patched,
+        edited: true,
+        directEditsFailed: false,
+      };
+    }
+    return { outcome, reviewedPlan: basePlan, edited: false, directEditsFailed: true };
+  }
+  if (hasDirectEditsHeading(outcome.feedback)) {
+    return { outcome, reviewedPlan: basePlan, edited: false, directEditsFailed: true };
+  }
+  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 askUser.ts recipe). */
+/** The minimal structural `ctx.ui` subset the first-party review needs (the ciExecutor.ts pure-core + injected-fakes recipe). */
 export interface PlanReviewUI {
   editor(title: string, prefill?: string): Promise<string | undefined>;
   select(
@@ -444,7 +609,7 @@ const REVIEW_EDITOR_TITLE =
 const DENY_FEEDBACK_TITLE = "Deny feedback (optional) — Enter to send";
 
 /**
- * The first-party in-TUI review core, pure over injected seams (the askUser.ts recipe) — fully
+ * The first-party in-TUI review core, pure over injected seams (the ciExecutor.ts pure-core + injected-fakes recipe) — fully
  * offline-testable. Flow: (1) display the plan in the editor dialog (Esc = dismissed; the human
  * may edit, incl. via Ctrl+G/$EDITOR); (2) a non-blank edit differing from the displayed plan is
  * written back to the draft BEFORE the verdict (reviewed bytes == artifact bytes == saved bytes;
@@ -588,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) {
@@ -613,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
@@ -669,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.
@@ -721,7 +917,12 @@ export function approvedGistSaveResult(
  * run VIEW-ONLY (edits are never written back; deny+feedback is the change channel); the
  * implement-here verdict is never offered (a gist is not implementable — it has no strategy).
  * An APPROVED outcome wires into the `gistApprovalSave` seam (re-read the artifact → `saveGist`
- * → D1a gate exit → terminating); every other outcome maps via `gistReviewOutcomeResult`.
+ * → D1a gate exit → terminating); every other outcome maps via `gistReviewOutcomeResult`. ONE
+ * carve-out (plannotator only, mirroring the objective arm): an approval whose feedback opens a
+ * Direct Edits section SKIPS the save — rendered edits cannot be folded back into the
+ * structured draft mechanically — and returns a NON-terminating revise round with the gate
+ * untouched (fold each hunk into the matching `gist_draft` field, re-review to confirm); perk
+ * never saves a gist the reviewer explicitly edited away from.
  */
 export async function executeGistReview(
   pi: ExtensionAPI,
@@ -762,6 +963,42 @@ export async function executeGistReview(
   let outcome: ReviewOutcome;
   if (isPlannotatorPlanSelected(ctx.cwd)) {
     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; mirrors the objective arm): the
+    // save seam re-reads the STRUCTURED artifact, so rendered edits cannot be folded back
+    // without model judgment. Skip the save, keep the gate read-only, and route ONE revise
+    // round: the model folds each hunk into the matching `gist_draft` field, then re-reviews
+    // to confirm. The heading check suffices (extraction success is irrelevant here — the diff
+    // goes to the model verbatim either way).
+    if (
+      outcome.status === "completed" &&
+      outcome.approved &&
+      outcome.feedback !== undefined &&
+      hasDirectEditsHeading(outcome.feedback)
+    ) {
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              "gist APPROVED with direct browser edits — these cannot be auto-applied to the " +
+              "structured draft, so nothing was saved. Fold each Direct Edits hunk below into " +
+              "the matching gist_draft field (a `# <title>` heading hunk → title, a `Scope:` " +
+              "line hunk → scope, prose hunks → prose), then call plan_review again to " +
+              `confirm.\n\nReviewer feedback:\n${outcome.feedback}`,
+          },
+        ],
+        details: {
+          ok: true,
+          status: "revise",
+          reason: "direct_edits",
+          approved: true,
+          feedback: outcome.feedback,
+          reviewId: outcome.reviewId,
+          subject: "gist",
+        },
+      };
+    }
   } else {
     const fp = await runFirstPartyReview({
       ui: ctx.ui,
@@ -790,8 +1027,9 @@ export async function executeGistReview(
 /**
  * The `plan_review` execute core, extracted pure-over-its-seams (the bridge, the gating, the
  * ctx) so the resolution + dispatch + approved-save paths are unit-testable offline. Arm order:
- * param decode → the objective-author arm (`executeObjectiveReview` — the rendered objective
- * draft is the review subject there) → headless skip → file-first resolution → backend
+ * param decode → the objective arm (`executeObjectiveReview` — the rendered objective draft is
+ * the review subject in BOTH objective-authoring stages) → headless skip → file-first
+ * resolution → backend
  * dispatch (plannotator-selected → the event-bus bridge; ANY other selection → the first-party
  * in-TUI editor review) → approved → `approvalSave`.
  */
@@ -802,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
@@ -825,12 +1064,15 @@ export async function executePlanReview(
       },
     };
   }
-  // 1. Objective-author session → the objective review arm: the rendered
-  //    objective draft is the sole review source; a well-typed `plan` param is ignored here.
-  //    A gist-author session likewise routes to the gist arm (the rendered gist draft).
+  // 1. An objective-authoring session (objective-author OR objective-save — both stages'
+  //    working draft is the objective draft, and neither carries `plan_draft`) → the objective
+  //    review arm: the rendered objective draft is the sole review source; a well-typed `plan`
+  //    param is ignored here — the plan-arm fallthrough could otherwise review/save an
+  //    unrelated plan param from an objective session. A gist-author session likewise routes to
+  //    the gist arm (the rendered gist draft).
   const launchedStage = rebuildWorkflowState(branchOf(ctx)).stage;
-  if (launchedStage === OBJECTIVE_AUTHOR_STAGE) {
-    return executeObjectiveReview(pi, ctx, gating, bridge, signal ?? ctx.signal);
+  if (launchedStage === OBJECTIVE_AUTHOR_STAGE || launchedStage === OBJECTIVE_SAVE_STAGE) {
+    return executeObjectiveReview(pi, ctx, gating, bridge, signal ?? ctx.signal, wave);
   }
   if (launchedStage === GIST_AUTHOR_STAGE) {
     return executeGistReview(pi, ctx, gating, bridge, signal ?? ctx.signal);
@@ -867,31 +1109,41 @@ 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 to the exact bytes reviewed, write it back to the draft (reviewed bytes ==
-    // artifact bytes == saved bytes — the first-party pre-verdict write-back, replayed here
-    // post-verdict because the bridge only reports the diff), and save the EDITED bytes. Every
-    // rung fails open to the verbatim path: no section → untouched; a heading that cannot be
-    // parsed / applied / written back → verbatim save + a loud warning (never save bytes the
-    // artifact doesn't carry). DENY stays model-mediated — the feedback (diff included) passes
-    // through for the plan_draft rewrite.
-    if (outcome.status === "completed" && outcome.approved && outcome.feedback !== undefined) {
-      const section = extractDirectEdits(outcome.feedback);
-      if (section !== null) {
-        const patched = applyUnifiedDiff(src.plan, section.diff);
-        if (patched !== null && writePlanDraft(pi, ctx, patched).details.ok) {
-          reviewedPlan = patched;
-          edited = true;
-          // The applied diff must NOT survive into the result as "apply these exact changes"
-          // guidance — only the annotation remainder (when any) stays reviewer feedback.
-          outcome = { ...outcome, feedback: section.remainder };
-        } else {
-          directEditsFailed = true;
-        }
-      } else if (hasDirectEditsHeading(outcome.feedback)) {
-        directEditsFailed = true;
-      }
+    // reviewer's diff via the shared helper (the first-party pre-verdict write-back, replayed
+    // here post-verdict because the bridge only reports the diff), and save the EDITED bytes.
+    // Every rung fails open to the verbatim path (never save bytes the artifact doesn't carry).
+    // DENY stays model-mediated — the feedback (diff included) passes through for the
+    // plan_draft rewrite.
+    if (outcome.status === "completed") {
+      const applied = applyPlannotatorDirectEdits(pi, ctx, outcome, src.plan);
+      outcome = applied.outcome;
+      reviewedPlan = applied.reviewedPlan;
+      edited = applied.edited;
+      directEditsFailed = applied.directEditsFailed;
     }
   } else {
     // The 4th verdict (implement-here, the no-save exit) is offered UNLESS this is an
@@ -937,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({
@@ -949,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",
@@ -973,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/factories/planTitle.ts

@@ -92,16 +92,35 @@ export async function generatePlanTitle(
 ): Promise<string | null> {
   if (!llmTitlesEnabled()) return null;
 
-  let auth: Awaited<ReturnType<typeof resolveModelAuth>>;
-  try {
-    auth = await resolveModelAuth(ctx);
-  } catch {
-    return null;
+  const model = ctx.model;
+  if (!model) return null; // silent: no model configured (fail-safe).
+
+  // Primary path (pi ≥ 0.84): registry dispatch — pi owns final request assembly (resolved auth,
+  // nullable headers, credential-resolved baseUrl, provider env). Feature-detected: the method is
+  // absent on older hosts, where the widened resolveModelAuth fallback keeps the old shape.
+  const registry = ctx.modelRegistry;
+  const registryComplete = registry.complete;
+  let authOptions: Pick<
+    Parameters<typeof completeStructured>[0],
+    "dispatch" | "apiKey" | "headers" | "env"
+  >;
+  if (typeof registryComplete === "function") {
+    authOptions = {
+      dispatch: (m, context, options) => registryComplete.call(registry, m, context, options),
+    };
+  } else {
+    let auth: Awaited<ReturnType<typeof resolveModelAuth>>;
+    try {
+      auth = await resolveModelAuth(ctx);
+    } catch {
+      return null;
+    }
+    if (!auth.ok) return null; // silent: no auth configured (fail-safe).
+    authOptions = { apiKey: auth.apiKey, headers: auth.headers, env: auth.env };
   }
-  if (!auth.ok) return null; // silent: no model / no auth configured (fail-safe).
 
   const outcome = await completeStructured({
-    model: auth.model,
+    model,
     schema: PlanTitleSchema,
     toolName: "set_plan_title",
     toolDescription: "Provide the chosen title and category for the plan.",
@@ -110,8 +129,7 @@ export async function generatePlanTitle(
       "Read this implementation plan and choose a title and category. The title must be a concise, " +
       "imperative phrase, at most ~70 characters, with no trailing period and no markdown.",
     input: planMarkdown.slice(0, TITLE_INPUT_CHAR_CAP),
-    apiKey: auth.apiKey,
-    headers: auth.headers,
+    ...authOptions,
     signal,
   });
   if (!outcome.ok || !outcome.value) {