@mgiles/perk 3.2.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,24 +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,
@@ -57,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";
@@ -108,8 +117,9 @@ export 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.
@@ -118,13 +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`);
+    resumeAnnotationDelivery(annotations, surface, pi, ctx);
     return;
   }
   if (state === "aborted") return; // the turn was interrupted — no-op
@@ -147,14 +160,14 @@ export async function observeBrowserReadiness(
   }
   // 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` (the core threads `ctx.signal`). */
+  /** 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;
@@ -188,6 +201,8 @@ export interface ReviewBrowserCoreOpts {
 export async function openReviewBrowserCore(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
+  annotations: AnnotationState,
+  status: ActivityHandle,
   opts: ReviewBrowserCoreOpts,
 ): Promise<boolean> {
   let started: StartedBrowser;
@@ -195,6 +210,7 @@ export async function openReviewBrowserCore(
     started = await startPlannotatorBrowser(pi.events, {
       ...opts.browserOpts,
       signal: ctx.signal,
+      activity: (text) => status.beginActivity(ctx, text),
     });
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
@@ -208,9 +224,9 @@ export async function openReviewBrowserCore(
     return false;
   }
 
-  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 } : {}),
   });
@@ -225,7 +241,7 @@ export async function openReviewBrowserCore(
       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();
     }
   })();
@@ -243,9 +259,11 @@ export async function openReviewBrowserCore(
 async function openBrowserAndGuide(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
+  annotations: AnnotationState,
+  status: ActivityHandle,
   opts: PrReviewBrowserGuidanceOpts,
 ): Promise<void> {
-  await openReviewBrowserCore(pi, ctx, {
+  await openReviewBrowserCore(pi, ctx, annotations, status, {
     scope: SCOPE,
     browserOpts: { prUrl: opts.prUrl, cwd: ctx.cwd },
     guidance: prReviewBrowserGuidance(opts) + bindingSuffix(ctx.cwd, `command:${SCOPE}`),
@@ -254,8 +272,12 @@ async function openBrowserAndGuide(
 
 // ------------------------------------------------------------------------ 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 " +
@@ -317,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,
@@ -328,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(
@@ -355,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). */