@dieulc/workflow 0.6.1 → 0.8.0

package/review-runtime.ts

@@ -32,6 +32,7 @@ import {
   planHash,
   readProviderErrorEvent,
   reviewNeedsVerification,
+  reviewRunLabel,
   truncateErrorText,
   type CreateReviewSessionOptions,
   type CreateReviewSessionResult,
@@ -50,7 +51,7 @@ import {
 } from "./review.ts";
 import { appendProviderAuthHint } from "./review-providers.ts";
 import { createReviewTools } from "./review-tools.ts";
-import { renderReviewContextBlock, type ReviewFinding } from "./utils.ts";
+import { buildPlanDiff, renderReviewContextBlock, type ReviewFinding } from "./utils.ts";
 
 /** Event `type` from a child-session event, or "" for junk. Never throws. */
 function readEventType(event: unknown): string {
@@ -91,6 +92,18 @@ export interface ReviewRuntimeDeps {
   readPlan: () => string | undefined;
   /** Pruned parent context entries (from ctx.sessionManager.getBranch()). */
   contextEntries: () => unknown[];
+  /**
+   * Whether the last Planner manifest carried recon summaries (step 8).
+   * When true the reviewer verifies instead of re-exploring: its explore
+   * budget is 0. Optional — absent means "no recon".
+   */
+  hasRecon?: () => boolean;
+  /**
+   * Planner-context manifest (file inventory + recon) for the pass-1 prompt
+   * (step 8). Optional: when absent the reviewer works from the transcript
+   * block alone, as before.
+   */
+  plannerManifest?: () => string;
   /**
    * Resolved reviewer guidance (review-prompt.md, else the built-in default).
    * A function, not a string: the user can edit the file between rounds.
@@ -129,6 +142,18 @@ export interface RunRoundInput {
   round: number;
   /** Findings from the previous round, so pass 2 can assert they were fixed. */
   previousFindings?: ReviewFinding[];
+  /**
+   * Host abort signal (ESC). When it fires the round stops promptly and the
+   * author's plan is kept — the same outcome as the internal abortRound().
+   * Linked to the round's own controller; detached when the round ends.
+   */
+  signal?: AbortSignal;
+  /**
+   * `/review-resume` is continuing a paused round on the warm session. Only the
+   * transcript label needs this: warmth alone cannot express intent, because a
+   * next round reuses the same session too.
+   */
+  resumed?: boolean;
 }
 
 export interface ReviewRuntime {
@@ -162,6 +187,8 @@ export function buildPass1Prompt(input: {
   planText: string;
   reviewPrompt: string;
   contextBlock: string;
+  /** Planner-context manifest (step 8): inventory + recon, trusted by default. */
+  manifest?: string;
   previousFindings?: ReviewFinding[];
   round: number;
   totalRounds: number;
@@ -178,13 +205,18 @@ export function buildPass1Prompt(input: {
     input.reviewPrompt,
   ];
 
+  if (input.manifest && input.manifest.trim()) {
+    parts.push("", input.manifest.trim());
+  }
+
   if (input.contextBlock.trim()) {
     parts.push(
       "",
-      "## Shared context from Plan Mode",
+      "## Plan Mode transcript (abridged)",
       "",
-      "This is what the author explored and was asked for. It is background, not",
-      "ground truth — verify anything you rely on against the repository.",
+      "The author's own words and tool spew, truncated for size. Prefer the",
+      "shared-context inventory above; re-read anything you rely on with",
+      "read/grep.",
       "",
       input.contextBlock.trim(),
     );
@@ -209,12 +241,18 @@ export function buildPass1Prompt(input: {
       "The author has revised the plan in response. Confirm whether each was",
       "actually addressed, and say so in your findings rather than re-raising it.",
       "",
-      ...input.previousFindings.map(
-        (f) =>
-          `- [${f.disposition}] ${f.summary}${
-            f.file ? ` (${f.file}${f.lineRange ? `:${f.lineRange}` : ""})` : ""
-          }`,
-      ),
+      ...input.previousFindings.map((f) => {
+        const loc = f.file
+          ? ` (${f.file}${f.lineRange ? `:${f.lineRange}` : ""})`
+          : "";
+        // Step 8: carry the rationale so re-review rounds verify instead of
+        // re-discovering (clipped — the full text lives in the changelog).
+        const why = String(f.rationale ?? "")
+          .replace(/\s+/g, " ")
+          .trim();
+        const clipped = why.length > 200 ? `${why.slice(0, 200)}…` : why;
+        return `- [${f.disposition}] ${f.summary}${loc}${clipped ? ` — ${clipped}` : ""}`;
+      }),
     );
   }
 
@@ -241,22 +279,18 @@ export function buildPass2Prompt(input: {
   rewrittenPlan: string;
   findings: ReviewFinding[];
 }): string {
+  // Step 9: pass 2 checks the rewrite against a diff, not two full plans.
+  const diff = buildPlanDiff(input.originalPlan, input.rewrittenPlan);
   return [
     "[REVIEW MODE — PASS 2 of 2: VERIFY YOUR OWN REWRITE]",
     "",
     "You just rewrote the plan and submitted it. Now check your own work. This pass",
     "exists because a rewrite can silently drop a requirement the author cared about.",
     "",
-    "## Original plan (as the author wrote it)",
+    "## What changed (unified diff of your rewrite)",
     "",
-    "```markdown",
-    input.originalPlan,
-    "```",
-    "",
-    "## Your rewrite (currently on disk)",
-    "",
-    "```markdown",
-    input.rewrittenPlan,
+    "```diff",
+    diff,
     "```",
     "",
     "## Findings you reported",
@@ -289,8 +323,10 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
   let state: ReviewState | undefined;
   let transcript: Transcript | undefined;
   let gate: ReviewRoundGate = createReviewRoundGate();
-  let starting: Promise<boolean> | undefined;
+  let starting: Promise<EnsureSessionResult> | undefined;
   let abortController: AbortController | undefined;
+  /** `provider/id/thinking` the live session was created with (step 10). */
+  let sessionModelKey: string | undefined;
   /** True while `runRound` is in flight (gates prompt routing). */
   let roundActive = false;
   /**
@@ -339,6 +375,26 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
     return transcript;
   };
 
+  /**
+   * Emit a runtime-authored status line to the local transcript buffer and the
+   * parent stream. Used for run-start narration, which the child's
+   * `agent_start` cannot describe truthfully (see `reviewRunLabel`).
+   * Display-only: a broken sink must never break a review.
+   */
+  const pushStatus = (text: string): void => {
+    const op: ReviewTranscriptOp = { op: "new", kind: "status", text };
+    try {
+      ensureTranscript().apply(op);
+    } catch {
+      /* ignore */
+    }
+    try {
+      deps.onTranscriptOps?.([op]);
+    } catch {
+      /* ignore */
+    }
+  };
+
   /**
    * Completed reviewer runs (`agent_settled`). A pass is over when either its
    * `review_pass_done` or the end of its run arrives — see `runPass()`.
@@ -512,7 +568,7 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
     if (stop === "timeout") {
       const capMs = Math.max(1000, config().timeoutMs);
       deps.log(
-        `Review Mode pass ${pass} hit its ${Math.round(
+        `pass ${pass} hit its ${Math.round(
           capMs / 1000,
         )}s limit — continuing with ${
           submitted ? "the submitted plan" : "the author's plan"
@@ -528,18 +584,70 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
     };
   }
 
-  async function ensureStarted(): Promise<boolean> {
-    if (session) return true;
+  /** Release the child session and its round state (step 10). Never throws. */
+  async function disposeSession(): Promise<void> {
+    try {
+      abortController?.abort();
+      await session?.abort();
+    } catch {
+      /* ignore */
+    }
+    try {
+      session?.dispose();
+    } catch {
+      /* ignore */
+    }
+    session = undefined;
+    state = undefined;
+    transcript = undefined;
+    sessionModelKey = undefined;
+    gate = createReviewRoundGate();
+    abortController = undefined;
+    try {
+      deps.onState?.(undefined);
+    } catch {
+      /* ignore */
+    }
+  }
+
+  /** Outcome of `ensureSession`: `created` is true only for a fresh boot. */
+  interface EnsureSessionResult {
+    ok: boolean;
+    created: boolean;
+  }
+
+  /**
+   * Idempotent session boot. `created` tells the caller whether THIS call paid
+   * for a new child session, which is what makes the transcript's run label
+   * truthful (fresh boot vs warm resume/next round).
+   */
+  async function ensureSession(): Promise<EnsureSessionResult> {
+    const modelRef = deps.reviewerModel();
+    const modelKey = modelRef
+      ? `${modelRef.provider}/${modelRef.id}/${modelRef.thinking}`
+      : "";
+    if (session) {
+      // Step 10: the session is bound to the model it was created with. A
+      // reviewer switch since then reboots it so the new model audits.
+      if (modelKey && sessionModelKey && modelKey !== sessionModelKey) {
+        deps.log(
+          "reviewer model changed — restarting the reviewer session.",
+          "info",
+        );
+        await disposeSession();
+      } else {
+        return { ok: true, created: false };
+      }
+    }
     if (starting) return starting;
-    starting = (async () => {
+    starting = (async (): Promise<EnsureSessionResult> => {
       const cfg = config();
-      const modelRef = deps.reviewerModel();
       if (!modelRef) {
         deps.log(
-          "Review Mode: no reviewer model configured — run /role set reviewer <provider/model>",
+          "no reviewer model configured — run /role set reviewer <provider/model>",
           "warning",
         );
-        return false;
+        return { ok: false, created: false };
       }
       try {
         // The SDK must be loaded BEFORE building the tools: review_bash is
@@ -553,7 +661,10 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
           cwd: deps.cwd,
           log: deps.log,
           explore: {
-            budget: () => config().exploreBudget,
+            // Step 8: Planner recon rides along in the prompt — when it is
+            // present the reviewer verifies instead of re-exploring.
+            budget: () =>
+              (deps.hasRecon?.() ?? false) ? 0 : config().exploreBudget,
             run: (task, signal) => deps.runExplore(task, signal),
             onUsed: (used) => {
               if (state) state.exploreUsed = used;
@@ -642,22 +753,33 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
 
         if (!created.ok || !created.session) {
           deps.log(
-            `Review Mode unavailable: ${created.error ?? "unknown error"} — the plan will be handed over unreviewed.`,
+            `reviewer unavailable: ${created.error ?? "unknown error"} — the plan will be handed over unreviewed.`,
             cfg.fallbackOnError === "block" ? "error" : "warning",
           );
-          return false;
+          return { ok: false, created: false };
         }
 
         // One line per session, so "the reviewer has no tools" is visible
         // immediately instead of only after a failed pass (see /review-status).
         if (created.activeTools) {
           deps.log(
-            `Review Mode: reviewer tools active — ${created.activeTools.join(", ")}`,
+            `reviewer tools active — ${created.activeTools.join(", ")}`,
             "info",
           );
         }
 
         session = created.session;
+        // Step 10: remember which model this session audits with.
+        sessionModelKey = modelKey;
+        // Config, not round state: report the missing cap once per live
+        // session, so a resume cannot replay it as if the reviewer had just
+        // started. Also avoids the old `Review Mode: Review Mode:` doubling.
+        if (cfg.timeoutMs <= 0) {
+          deps.log(
+            "no time limit configured — each pass ends when the reviewer submits or its run settles.",
+            "info",
+          );
+        }
         ensureTranscript();
         const child = created.session;
         session.subscribe((event) => {
@@ -710,13 +832,13 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
             }, 0);
           }
         });
-        return true;
+        return { ok: true, created: true };
       } catch (e: unknown) {
         deps.log(
-          `Review Mode failed to start: ${e instanceof Error ? e.message : String(e)}`,
+          `failed to start: ${e instanceof Error ? e.message : String(e)}`,
           "warning",
         );
-        return false;
+        return { ok: false, created: false };
       } finally {
         starting = undefined;
       }
@@ -724,11 +846,20 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
     return starting;
   }
 
+  /** Public shape: idempotent, creates the reviewer session if it is not alive. */
+  async function ensureStarted(): Promise<boolean> {
+    return (await ensureSession()).ok;
+  }
+
   async function runRound(input: RunRoundInput): Promise<ReviewRoundResult> {
     const cfg = config();
     const hash = planHash(input.planText);
     const started = Date.now();
     const originalPlan = input.planText;
+    // Declared outside the try: a `let` inside the try block would not be
+    // visible in `finally` (block scoping), and the external listener must
+    // always be detached when the round ends.
+    let detachExternal: (() => void) | undefined;
 
     const fail = (
       reason: string,
@@ -768,10 +899,52 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         return fail("no plan path — the reviewer has nowhere to submit");
       }
 
-      const ready = await ensureStarted();
-      if (!ready || !session) {
+      // A signal that is already aborted means the host turn this round would
+      // belong to is gone (e.g. the planner turn was interrupted). Do not boot
+      // a session, send a prompt or spend a pass on it: report a fast abort.
+      // The caller decides what that means — the automatic handoff skips the
+      // review and hands off unreviewed, while an explicit `/review-resume`
+      // passes no host signal at all (its stop paths are ESC / `/review-abort`).
+      // Crucially, a pre-aborted signal must never become a pause: doing so
+      // re-created `pausedReview` on every resume and parked the handoff
+      // forever (2026-10-25 stall).
+      if (input.signal?.aborted === true) {
+        if (!state || state.planHash !== hash) {
+          state = createReviewState({
+            planHash: hash,
+            planPath: input.planPath,
+            modelLabel: session?.modelLabel ?? "reviewer",
+            round: input.round,
+            now: started,
+          });
+        }
+        state.round = input.round;
+        state.planPath = input.planPath;
+        state.phase = "aborted";
+        state.error =
+          "aborted before start — the host turn was already aborted";
+        state.finishedAt = Date.now();
+        try {
+          deps.onState?.(state);
+        } catch {
+          /* status updates are best-effort */
+        }
+        return {
+          ok: false,
+          fallback: true,
+          planText: originalPlan,
+          planHash: hash,
+          state,
+          reason: "aborted-before-start",
+          abortedBeforeStart: true,
+        };
+      }
+
+      const start = await ensureSession();
+      if (!start.ok || !session) {
         return fail("reviewer session unavailable");
       }
+      const created = start.created;
       const child = session;
 
       if (!state || state.planHash !== hash || state.phase === "done") {
@@ -789,16 +962,33 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
 
       abortController = new AbortController();
       const rc = abortController;
+      // ESC cancels: link the host signal (when the caller threads one
+      // through) to the round's controller, so ESC aborts the pass race,
+      // the settle wait and the send alike. The existing `aborted` branch
+      // below then keeps the session warm and hands back the author's plan.
+      const externalSignal = input.signal;
+      if (externalSignal) {
+        if (externalSignal.aborted) {
+          rc.abort();
+        } else {
+          const onExternalAbort = () => {
+            try {
+              rc.abort();
+            } catch {
+              /* abort is best-effort */
+            }
+          };
+          externalSignal.addEventListener("abort", onExternalAbort, {
+            once: true,
+          });
+          detachExternal = () =>
+            externalSignal.removeEventListener("abort", onExternalAbort);
+        }
+      }
       // 0 (default) = no cap. A configured cap is the outer safety net; the
       // settle race below still ends a silent pass quickly either way.
       const limitMs = cfg.timeoutMs > 0 ? cfg.timeoutMs : undefined;
       const deadline = limitMs !== undefined ? started + limitMs : undefined;
-      if (limitMs === undefined) {
-        deps.log(
-          "Review Mode: no time limit configured — each pass ends when the reviewer submits or its run settles.",
-          "info",
-        );
-      }
 
       // ── Pass 1 ──────────────────────────────────────────────────────
       await settleInFlight(deadline, rc);
@@ -808,16 +998,26 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         planPath: input.planPath,
         planText: originalPlan,
         reviewPrompt: deps.promptText(),
-        contextBlock: renderReviewContextBlock(deps.contextEntries()),
+        contextBlock: renderReviewContextBlock(deps.contextEntries(), {
+          // Step 7 — diet default (settings-overridable).
+          maxChars: config().contextChars,
+        }),
+        // Step 8: inventory + recon so the reviewer verifies, not re-explores.
+        manifest: deps.plannerManifest?.() ?? "",
         previousFindings: input.previousFindings,
         round: input.round,
         totalRounds: cfg.rounds,
         verify: cfg.verify && cfg.passes > 1,
       });
 
-      const p1 = await runPass(1, deadline, rc, () =>
-        child.prompt(pass1Prompt),
-      );
+      const p1 = await runPass(1, deadline, rc, () => {
+        // Pushed inside `send`: an already-aborted pass never sends, so it must
+        // not claim a start either.
+        pushStatus(
+          reviewRunLabel({ created, resumed: input.resumed === true, pass: 1 }),
+        );
+        return child.prompt(pass1Prompt);
+      });
 
       if (p1.stop === "error") {
         await abortChild();
@@ -872,7 +1072,7 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         // The protocol completed, the run did not: stop paying for it, but keep
         // the submission — never discard real work over a slow model.
         deps.log(
-          "Review Mode pass 1 exceeded its time limit after submitting — using the submitted plan.",
+          "pass 1 exceeded its time limit after submitting — using the submitted plan.",
           "warning",
         );
         await abortChild();
@@ -897,9 +1097,10 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
           rewrittenPlan: p1.submitted.planBody,
           findings: state?.findings ?? [],
         });
-        const p2 = await runPass(2, deadline, rc, () =>
-          child.followUp(pass2Prompt),
-        );
+        const p2 = await runPass(2, deadline, rc, () => {
+          pushStatus(reviewRunLabel({ created, pass: 2 }));
+          return child.followUp(pass2Prompt);
+        });
         // Name the provider when the verification pass died on one; pass 2
         // stays best-effort either way — pass 1's plan is never lost to it.
         const p2Provider = lastProviderError
@@ -909,8 +1110,8 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
           // Verification is an enhancement: never lose pass 1's plan over it.
           deps.log(
             p2Provider
-              ? `Review Mode verification pass failed (${p2Provider}; send error: ${errorText(p2.error)}) — keeping pass 1's plan.`
-              : `Review Mode verification pass failed (${errorText(p2.error)}) — keeping pass 1's plan.`,
+              ? `verification pass failed (${p2Provider}; send error: ${errorText(p2.error)}) — keeping pass 1's plan.`
+              : `verification pass failed (${errorText(p2.error)}) — keeping pass 1's plan.`,
             "warning",
           );
         } else if (p2.submitted) {
@@ -919,7 +1120,7 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
           // The run settled without a submission AND a provider error was
           // seen this pass: say why, then keep going with pass 1's rewrite.
           deps.log(
-            `Review Mode verification pass ended without a submission (${p2Provider}) — keeping pass 1's plan.`,
+            `verification pass ended without a submission (${p2Provider}) — keeping pass 1's plan.`,
             "warning",
           );
         }
@@ -949,6 +1150,11 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         `review round failed: ${e instanceof Error ? e.message : String(e)}`,
       );
     } finally {
+      try {
+        detachExternal?.();
+      } catch {
+        /* listener cleanup is best-effort */
+      }
       abortController = undefined;
       roundActive = false;
     }
@@ -1008,27 +1214,7 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
       }
     },
     async teardown() {
-      try {
-        abortController?.abort();
-        await session?.abort();
-      } catch {
-        /* ignore */
-      }
-      try {
-        session?.dispose();
-      } catch {
-        /* ignore */
-      }
-      session = undefined;
-      state = undefined;
-      transcript = undefined;
-      gate = createReviewRoundGate();
-      abortController = undefined;
-      try {
-        deps.onState?.(undefined);
-      } catch {
-        /* ignore */
-      }
+      await disposeSession();
     },
   };
 }

package/review-ui.ts

@@ -50,6 +50,13 @@ export interface ReviewModeBandData {
   round?: number;
   verdict?: string;
   reason?: string;
+  /**
+   * A round that continues a paused one (`/review-resume`). The band renders
+   * `resumed` instead of `sequential audit` so the two flows never look alike.
+   */
+  resumed?: boolean;
+  /** The round stopped for a pause; renders `REVIEW PAUSED`, not `REVIEW DONE`. */
+  paused?: boolean;
 }
 
 /** Payload of a `workflow-review-transcript` chunk entry. */
@@ -103,6 +110,10 @@ export function reviewBandKey(data: ReviewModeBandData | undefined): string {
     data?.modelLabel ?? "",
     data?.verdict ?? "",
     data?.reason ?? "",
+    // A resumed (or paused) band is never the same event as the fresh band it
+    // continues, even when mode/round/model/verdict/reason happen to match.
+    data?.resumed === true ? "resumed" : "",
+    data?.paused === true ? "paused" : "",
   ].join("|");
 }
 
@@ -295,19 +306,28 @@ export function formatReviewModeBand(
   }
   if (mode === "review") {
     const bits: string[] = [];
-    if (typeof data?.round === "number" && data.round > 1) {
+    const resumed = data?.resumed === true;
+    if (resumed) {
+      bits.push("resumed");
+      // Always name the round on a resume: "resumed · round 1" reads as a
+      // continuation, while a bare "resumed" hides which round continues.
+      if (typeof data?.round === "number") bits.push(`round ${data.round}`);
+    } else if (typeof data?.round === "number" && data.round > 1) {
       bits.push(`round ${data.round}`);
     }
     if (typeof data?.modelLabel === "string" && data.modelLabel) {
       bits.push(data.modelLabel);
     }
-    bits.push("sequential audit");
+    // "sequential audit" describes a fresh flow; a resumed round continues the
+    // flow it was paused in.
+    if (!resumed) bits.push("sequential audit");
     const title = theme.fg("accent", theme.bold("▌ REVIEW MODE"));
     return [title + theme.fg("muted", `  ${bits.join(" · ")}`)];
   }
   if (mode === "review-done") {
+    const paused = data?.paused === true;
     const clean = data?.verdict === "approve" && !data?.reason;
-    const color: ThemeColor = clean ? "success" : "warning";
+    const color: ThemeColor = paused || !clean ? "warning" : "success";
     let detail = "";
     if (data?.reason) {
       detail = `  ${data.reason}`;
@@ -315,7 +335,10 @@ export function formatReviewModeBand(
       detail = `  verdict: ${data.verdict}`;
     }
     return [
-      theme.fg(color, theme.bold("▌ REVIEW DONE")) + theme.fg("muted", detail),
+      theme.fg(
+        color,
+        theme.bold(paused ? "▌ REVIEW PAUSED" : "▌ REVIEW DONE"),
+      ) + theme.fg("muted", detail),
     ];
   }
   return [theme.fg("muted", "▌ review")];