@mgiles/perk 3.1.0 → 3.3.0

package/extension/{doors/prReviewBrowser.ts → pi/v1/codeReview/browser.ts}

@@ -2,7 +2,7 @@
 // review — plannotator always, no provider dispatch (the surface-named command IS the selection).
 //
 // Three modes, keyed off the arg parse + the active-PR resolution ladder (the parse is IMPORTED
-// from prReviewTerminal.ts — one function ⇒ identical arg semantics by construction):
+// from terminal.ts — one function ⇒ identical arg semantics by construction):
 //   foreign — `/pr-review-browser <pr|url> [focus]`: the detached `perk pr review checkout`, the
 //             browser opened in the background on the PR URL, the async adversarial-reviewer
 //             fan-out with per-angle annotation waves streamed to the local plannotator server.
@@ -17,7 +17,8 @@
 // (plannotator reads `PLANNOTATOR_PORT` at bind time — see plannotatorHandoff.ts), so in the PR
 // modes the handler starts `startPlannotatorBrowser`, injects the mode guidance IMMEDIATELY, and
 // ends its turn — no blocking readiness poll in the handler. The readiness promise is observed
-// in a background task: ready → an info note; timeout / an error-or-unavailable bridge settle →
+// in a background task: ready → an info note + a continuation for pending annotation work;
+// timeout / an error-or-unavailable bridge settle →
 // a loud error plus a degrade notice injected to the model (findings render in-session; posting
 // unchanged) AND the annotation surface cleared. `push_annotations` owns the
 // hold-and-accumulate discipline: a held batch before any door failure notice means "not up
@@ -30,23 +31,31 @@
 //
 // THE COMPANION TOOLS: the reviewer fan-out is the globally registered `start_review_wave` /
 // `collect_review_wave` pair, and the annotation delivery is the globally registered
-// `push_annotations` tool PRIMED BY THIS DOOR (`primeAnnotationSurface` on a PR-mode open,
-// cleared on bridge settle and on the readiness-degrade arm — the model never sees the URL).
+// `push_annotations` tool PRIMED BY THIS DOOR (`primeAnnotationSurface` over the threaded
+// per-activation annotation state on a PR-mode open, cleared on bridge settle and on the
+// readiness-degrade arm — the model never sees the URL).
 // The door still registers NO tools of its own; perk-side posting reuses `submit_pr_review`
-// (registered by `registerSubmitPrReview`). The local (pre-PR) mode never primes.
+// (installed by `installCuratedSubmissionBindings`). The local (pre-PR) mode never primes.
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { bindingSuffix } from "../substrate/bindingDelivery.ts";
-import { runColdDoor } from "../substrate/coldDoor.ts";
-import { registerPerkCommand } from "../substrate/command.ts";
-import { interceptConsoleError } from "../substrate/consoleCapture.ts";
-import { render } from "../substrate/prompts.ts";
-import { type ReportTarget, report } from "../surfaces/report.ts";
-import { clearAnnotationSurface, primeAnnotationSurface } from "./annotationPush.ts";
-import { type CheckoutOk, decodeCheckout } from "./hunkHandoff.ts";
+import { bindingSuffix } from "../../../substrate/bindingDelivery.ts";
+import { runColdDoor } from "../../../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../../../substrate/command.ts";
+import { interceptConsoleError } from "../../../substrate/consoleCapture.ts";
+import { render } from "../../../substrate/prompts.ts";
+import { type ReportTarget, report } from "../../../surfaces/report.ts";
+import type { ActivityHandle } from "../../../surfaces/surfaces.ts";
 import {
+  type AnnotationState,
+  clearAnnotationSurface,
+  primeAnnotationSurface,
+  resumeAnnotationDelivery,
+} from "../providers/annotations.ts";
+import {
+  type CodeReviewOutcome,
   decodePrUrl,
   LOCAL_REVIEW_DIFF_TYPE,
+  type PrUrl,
   plannotatorPresent,
   planRefBaseOf,
   type RespondSink,
@@ -56,8 +65,9 @@ import {
   routePrReviewOutcome,
   type StartedBrowser,
   startPlannotatorBrowser,
-} from "./plannotatorHandoff.ts";
-import { parseReviewDoorArgs } from "./prReviewTerminal.ts";
+} from "../providers/plannotatorHandoff.ts";
+import { type CheckoutOk, decodeCheckout } from "./checkout.ts";
+import { parseReviewDoorArgs } from "./terminal.ts";
 
 /** The door's report scope — also the `command:<id>` binding trigger id. */
 const SCOPE = "pr-review-browser";
@@ -95,8 +105,9 @@ export function prReviewBrowserGuidance(opts: PrReviewBrowserGuidanceOpts): stri
 /**
  * The degrade notice injected when the browser never comes up — the model renders the findings
  * in-session and runs the same triage conversationally; the posting contract is unchanged.
+ * Exported as the `openReviewBrowserCore` default (the stack door supplies its own).
  */
-const DEGRADE_NOTICE =
+export const DEGRADE_NOTICE =
   "The plannotator browser review is unavailable (the review server never became ready) — " +
   "degrade in-session: render the reviewers' reconciled findings as a table in your reply and " +
   "run the same triage loop conversationally. The annotation surface is cleared — " +
@@ -106,8 +117,9 @@ const DEGRADE_NOTICE =
 
 /**
  * Observe the readiness poll in the background (the handler has already injected the guidance
- * and ended): ready → an info note naming the URL; timeout / an error-or-unavailable bridge
- * settle → a loud error report PLUS the degrade notice injected to the model (idle → immediate,
+ * and ended): ready → an info note + an immediate/followUp annotation-delivery continuation
+ * when the still-current surface has held or in-flight work; timeout / an error-or-unavailable
+ * bridge settle → a loud error report PLUS the degrade notice injected to the model (idle → immediate,
  * streaming → followUp). A bridge that settled `handled` (the human finished before the poll saw
  * the server) or `aborted` routes via the respond routing alone — no degrade. Structural param
  * slices keep it offline-testable; exported for the door tests.
@@ -116,10 +128,16 @@ export async function observeBrowserReadiness(
   pi: RespondSink,
   ctx: ReportTarget & Pick<ExtensionContext, "isIdle">,
   started: StartedBrowser,
+  annotations: AnnotationState,
+  opts?: { scope?: string; degradeNotice?: string },
 ): Promise<void> {
+  const scope = opts?.scope ?? SCOPE;
+  const degradeNotice = opts?.degradeNotice ?? DEGRADE_NOTICE;
+  const surface = annotations.surface;
   const state = await started.readiness;
   if (state === "ready") {
-    report(ctx, SCOPE, "info", `plannotator is up at ${started.url} — browser opening`);
+    report(ctx, scope, "info", `plannotator is up at ${started.url} — browser opening`);
+    resumeAnnotationDelivery(annotations, surface, pi, ctx);
     return;
   }
   if (state === "aborted") return; // the turn was interrupted — no-op
@@ -129,85 +147,137 @@ export async function observeBrowserReadiness(
   }
   report(
     ctx,
-    SCOPE,
+    scope,
     "error",
     `the plannotator review server did not become ready at ${started.url} — the browser ` +
       "review is unavailable",
     { alsoLog: true },
   );
   if (ctx.isIdle()) {
-    pi.sendUserMessage(DEGRADE_NOTICE);
+    pi.sendUserMessage(degradeNotice);
   } else {
-    pi.sendUserMessage(DEGRADE_NOTICE, { deliverAs: "followUp" });
+    pi.sendUserMessage(degradeNotice, { deliverAs: "followUp" });
   }
   // Consistent with "render findings in-session": a post-degrade push_annotations refuses
   // loudly (`no_surface`). Idempotent beside the bridge-settle clear.
-  clearAnnotationSurface();
+  clearAnnotationSurface(annotations);
+}
+
+/** The parameterized browser-lifecycle core's options (see `openReviewBrowserCore`). */
+export interface ReviewBrowserCoreOpts {
+  /** The invoking door's report scope. */
+  scope: string;
+  /** The `startPlannotatorBrowser` opts minus `signal`/`activity` (both threaded by the core). */
+  browserOpts: { cwd: string; prUrl?: string; diffType?: string; defaultBranch?: string };
+  /** The fully composed guidance to inject (binding suffix included by the caller). */
+  guidance: string;
+  /** The degrade notice for the browser-never-ready arm (default: the PR-mode notice). */
+  degradeNotice?: string;
+  /** The respond → injection mapper (default: `respondMessage` — the single-PR contract). */
+  respondMessageFor?: (outcome: CodeReviewOutcome) => string | null;
+  /**
+   * Whether the core injects `guidance` as a user message at the end (default true — the warm
+   * doors). The `open_stack_review` tool passes false and returns the guidance as its ok text
+   * instead (the tool result is the seeded session's delivery channel).
+   */
+  injectGuidance?: boolean;
 }
 
 /**
- * The shared PR-mode arm (foreign + active): start the browser open in the background, inject
- * the mode guidance immediately (the URL is deterministic once the port is picked), and return —
- * the readiness observation and the bridge respond both ride background tasks. While plannotator
- * sets up, its in-process `console.error` chatter re-routes through the TUI-safe report() seam
- * (the debounce restores once setup goes quiet, with the `finally` as a backstop).
+ * The full browser-lifecycle core, extracted from the PR-mode arm and parameterized for the
+ * stack door: start the browser open in the background, prime the annotation surface the
+ * moment the port is picked (push_annotations now serves this browser session), observe
+ * readiness in the background (degrade notice on never-ready), route the bridge respond
+ * through the injectable mapper, clear the surface on settle, and inject the guidance
+ * immediately (the URL is deterministic once the port is picked). While plannotator sets up,
+ * its in-process `console.error` chatter re-routes through the TUI-safe report() seam (the
+ * debounce restores once setup goes quiet, with the `finally` as a backstop).
+ *
+ * Accepted stale-clear edge (unchanged from the pre-extraction arm): a second browser door
+ * while this browser is still open re-primes (a new browser session supersedes everything),
+ * and THIS bridge's later settle would clear the second session's surface — rare and loud
+ * (the fixed-port EADDRINUSE caveat, contracts §8.4), noted, not engineered around.
  */
-async function openBrowserAndGuide(
+export async function openReviewBrowserCore(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
-  opts: PrReviewBrowserGuidanceOpts,
-): Promise<void> {
+  annotations: AnnotationState,
+  status: ActivityHandle,
+  opts: ReviewBrowserCoreOpts,
+): Promise<boolean> {
   let started: StartedBrowser;
   try {
     started = await startPlannotatorBrowser(pi.events, {
-      prUrl: opts.prUrl,
-      cwd: ctx.cwd,
+      ...opts.browserOpts,
       signal: ctx.signal,
+      activity: (text) => status.beginActivity(ctx, text),
     });
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     report(
       ctx,
-      SCOPE,
+      opts.scope,
       "error",
       `could not pick a free local port for the plannotator review server: ${detail}`,
       { alsoLog: true },
     );
-    return;
+    return false;
   }
 
-  // Prime the annotation surface the moment the port is picked (the URL is deterministic — see
-  // the background-open header note): push_annotations now serves this browser session. Accepted
-  // stale-clear edge: a second /pr-review-browser while this browser is still open re-primes (a
-  // new browser session supersedes everything), and THIS bridge's later settle would clear the
-  // second session's surface — the overlap is already rare and loud (the fixed-port EADDRINUSE
-  // caveat, contracts §8.4), so it is noted, not engineered around.
-  primeAnnotationSurface({ mode: "review", url: started.url });
+  primeAnnotationSurface(annotations, { mode: "review", url: started.url });
 
-  void observeBrowserReadiness(pi, ctx, started);
+  void observeBrowserReadiness(pi, ctx, started, annotations, {
+    scope: opts.scope,
+    ...(opts.degradeNotice !== undefined ? { degradeNotice: opts.degradeNotice } : {}),
+  });
 
   void (async () => {
-    const interceptor = interceptConsoleError((line) => report(ctx, SCOPE, "info", line), {
+    const interceptor = interceptConsoleError((line) => report(ctx, opts.scope, "info", line), {
       // plannotator can pause up to ~4s between setup lines — keep the quiet window above that.
       quietMs: 6000,
     });
     try {
       const out = await started.bridgePromise;
-      routeBrowserRespond(pi, ctx, out, SCOPE);
+      routeBrowserRespond(pi, ctx, out, opts.scope, opts.respondMessageFor);
     } finally {
       // The browser session is over — drop the surface so a later push refuses (`no_surface`).
-      clearAnnotationSurface();
+      clearAnnotationSurface(annotations);
       interceptor.restore();
     }
   })();
 
-  pi.sendUserMessage(prReviewBrowserGuidance(opts) + bindingSuffix(ctx.cwd, `command:${SCOPE}`));
+  if (opts.injectGuidance !== false) pi.sendUserMessage(opts.guidance);
+  return true;
+}
+
+/**
+ * The shared PR-mode arm (foreign + active): the extracted core with this door's values —
+ * PR-mode browser opts, the mode guidance + binding suffix, and the default degrade notice /
+ * respond mapper (the byte-stability of the pre-extraction behavior is proven by this door's
+ * untouched tests).
+ */
+async function openBrowserAndGuide(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  annotations: AnnotationState,
+  status: ActivityHandle,
+  opts: PrReviewBrowserGuidanceOpts,
+): Promise<void> {
+  await openReviewBrowserCore(pi, ctx, annotations, status, {
+    scope: SCOPE,
+    browserOpts: { prUrl: opts.prUrl, cwd: ctx.cwd },
+    guidance: prReviewBrowserGuidance(opts) + bindingSuffix(ctx.cwd, `command:${SCOPE}`),
+  });
 }
 
 // ------------------------------------------------------------------------ registration
 
-/** Register the warm `/pr-review-browser` command (no tools — posting rides submit_pr_review). */
-export function registerPrReviewBrowser(pi: ExtensionAPI): void {
+/** Install the warm `/pr-review-browser` command (no tools — posting rides submit_pr_review). */
+export function installPrReviewBrowserBindings(
+  pi: ExtensionAPI,
+  annotations: AnnotationState,
+  status: ActivityHandle,
+): void {
   registerPerkCommand(pi, SCOPE, {
     description:
       "Review a PR human-in-the-loop in the plannotator browser UI: no arg reviews the active " +
@@ -269,7 +339,7 @@ export function registerPrReviewBrowser(pi: ExtensionAPI): void {
             ? `PR #${parsed.pr} → adversarial reviewers (focus: ${parsed.directive}) → plannotator browser triage → you post from the browser`
             : `PR #${parsed.pr} → adversarial reviewers → plannotator browser triage → you post from the browser`,
         );
-        await openBrowserAndGuide(pi, ctx, {
+        await openBrowserAndGuide(pi, ctx, annotations, status, {
           mode: "foreign",
           pr: parsed.pr,
           prUrl: checkout.data.url,
@@ -280,12 +350,10 @@ export function registerPrReviewBrowser(pi: ExtensionAPI): void {
       }
 
       // The active arm: resolve the worktree's own PR via the shared ladder.
-      const r = await runColdDoor<{ number: number; url: string }>(
-        pi,
-        ctx,
-        ["pr", "url", "--json"],
-        { label: "perk pr url", decode: decodePrUrl },
-      );
+      const r = await runColdDoor<PrUrl>(pi, ctx, ["pr", "url", "--json"], {
+        label: "perk pr url",
+        decode: decodePrUrl,
+      });
       const target = resolveReviewTarget(r, planRefBaseOf(ctx.cwd));
       if (target.mode === "fail") {
         report(
@@ -307,7 +375,7 @@ export function registerPrReviewBrowser(pi: ExtensionAPI): void {
             ? `PR #${target.number} (active worktree) → adversarial reviewers (focus: ${parsed.directive}) → plannotator browser triage → you post from the browser`
             : `PR #${target.number} (active worktree) → adversarial reviewers → plannotator browser triage → you post from the browser`,
         );
-        await openBrowserAndGuide(pi, ctx, {
+        await openBrowserAndGuide(pi, ctx, annotations, status, {
           mode: "active",
           pr: target.number,
           prUrl: target.prUrl,

package/extension/{doors/hunkHandoff.ts → pi/v1/codeReview/checkout.ts}

@@ -1,14 +1,18 @@
-// The hunk terminal-review substrate serving `/pr-review-terminal`: the strict
+// The neutral shared checkout/PR-token substrate serving the code-review doors: the strict
 // `perk pr review checkout` decode, the `hunk --version` presence probe, and the R7 launch
 // handoff (clipboard copy + terminal auto-launch raced against a soft deadline) — plus the
 // door-common PR-token arg grammar (`parseReviewArgs`) that `/pr-review-browser` also consumes
-// via `parseReviewDoorArgs`. Re-homing the door-common pieces to a neutral module is a deferred
-// residual (accepted — no code moves yet).
-
-import { copyToClipboard } from "../substrate/clipboard.ts";
-import { type ColdJson, type ExecHost, numberField, stringField } from "../substrate/coldDoor.ts";
-import { LAUNCH_SURFACE, launchInTerminal } from "../substrate/terminalLaunch.ts";
-import { type ReportTarget, report } from "../surfaces/report.ts";
+// via `parseReviewDoorArgs`. Its only consumers are the `pi/v1/codeReview/` siblings.
+
+import { copyToClipboard } from "../../../substrate/clipboard.ts";
+import {
+  type ColdJson,
+  type ExecHost,
+  numberField,
+  stringField,
+} from "../../../substrate/coldDoor.ts";
+import { LAUNCH_SURFACE, launchInTerminal } from "../../../substrate/terminalLaunch.ts";
+import { type ReportTarget, report } from "../../../surfaces/report.ts";
 
 /** The install hint for the absent hunk binary — the exact `HUNK_INSTALL_HINT` wording
  * (src/perk/convergence/init/review_cli.py). */