@dieulc/workflow 0.9.1 → 0.10.0

package/index.ts

@@ -56,6 +56,7 @@ import {
   normalizeStepText,
   todoKey,
   isPlanWritePath,
+  samePlanPath,
   findPlanWritePathInMessages,
   findLatestPlanWriteInBranch,
   choosePlanPath,
@@ -88,8 +89,10 @@ import {
 } from "./utils.ts";
 import {
   WORKFLOW_ROLE_ENV,
+  describeCommandPolicy,
   explainCommandRefusal,
   gitCommitPolicyHit,
+  permissionsArgumentCompletions,
   policyForRole,
   resolveSessionRole,
   subagentEnv,
@@ -160,6 +163,8 @@ import {
   roleArgumentCompletions,
   saveRoleConfig,
   getRole,
+  userRolesPath,
+  projectRolesPath,
   formatRolesForDisplay,
   formatModelRef,
   parseModelRef,
@@ -201,11 +206,17 @@ import {
   PROFILE_ROLES,
   modelPickerItems,
   profileActionClosesPicker,
+  userProfilesPath,
+  projectProfilesPath,
   type ProfileFlowOutcome,
   type ProfileConfig,
   type Profile,
   type ProfileRoleName,
 } from "./profiles.ts";
+import {
+  formatRetargetResult,
+  retargetProviderFiles,
+} from "./provider-retarget.ts";
 import { FilterableList, type FilterableItem } from "./picker.ts";
 import { QUESTIONNAIRE_OVERLAY_MAX_HEIGHT } from "./questionnaire-layout.ts";
 import {
@@ -229,6 +240,7 @@ import {
 } from "./model-default.ts";
 import {
   applySubmittedPlan,
+  buildReviewerFallbacks,
   classifyReviewExecution,
   createReviewHandoffGate,
   DEFAULT_REVIEW_MODE_CONFIG,
@@ -238,25 +250,28 @@ import {
   planHash,
   readReviewModeConfig,
   resolveReviewPrompt,
-  reviewFooterSegment,
+  nextReviewRound,
   reviewGatePhaseOnResume,
   reviewModeLockFooter,
   reviewModeLockKind,
   reviewModeLockNotice,
   reviewModeLockStatusLine,
   reviewNoticeText,
+  reviewPauseIsCurrent,
   reviewResumeGateOutcome,
   reviewResumeNotice,
   reviewResumePlanChoice,
   reviewEscapeAction,
+  reviewElapsedMs,
   reviewHandoffParks,
   reviewResumeSettles,
   reviewStateSummary,
-  reviewStatusVisible,
+  reviewStatusText,
   shouldRouteInputToReviewer,
   writeReviewModeConfig,
   writeReviewPrompt,
   type ReviewFinding,
+  type ReviewFallbackModel,
   type ReviewExecutionResult,
   type ReviewHandoffGate,
   type ReviewSdkLoader,
@@ -278,12 +293,35 @@ import {
   type ReviewLineBuffer,
   type ReviewModeBandData,
 } from "./review-ui.ts";
+import {
+  pendingHandoffIsStale,
+  reviewHandoffRecovery,
+  shouldHandoffManualResult,
+  type ReviewHandoffSource,
+} from "./review-handoff.ts";
 import { seedPromptHistory, WorkflowTabEditor } from "./tab-editor.ts";
 
 // ── Plannotator Bridge ───────────────────────────────────────────────
 const PLANNOTATOR_REQUEST = "plannotator:request" as const;
 const PLANNOTATOR_REVIEW_RESULT = "plannotator:review-result" as const;
 const PLANNOTATOR_PLAN_APPROVED = "plannotator:plan-approved" as const;
+const PLANNOTATOR_SESSION_OPENED = "plannotator:session-opened" as const;
+const PLANNOTATOR_SESSION_CLOSED = "plannotator:session-closed" as const;
+
+/** Structural shape of the optional Plannotator lifecycle events. */
+interface PlannotatorSessionEventLike {
+  id?: string;
+  action?: string;
+  url?: string;
+  reviewId?: string;
+  requestId?: string;
+  outcome?: "approved" | "submitted" | "closed";
+  closedBy?: string;
+}
+
+type PlanReviewRequestOutcome =
+  | { status: "handled"; reviewId?: string; url?: string }
+  | { status: "timeout" | "error" | "unavailable"; reason: string };
 
 // ── Helpers ──────────────────────────────────────────────────────────
 
@@ -495,6 +533,10 @@ function getFinalOutput(messages: any[]): string {
  */
 export interface WorkflowExtensionDeps {
   loadSdk?: ReviewSdkLoader;
+  /** Test seam: how long a plan-review request waits for Plannotator. */
+  plannotatorRequestTimeoutMs?: number;
+  /** Test seam: how long a reload recovery status query waits. */
+  plannotatorRecoveryTimeoutMs?: number;
 }
 
 export default function workflowExtension(
@@ -1322,6 +1364,16 @@ export default function workflowExtension(
   let lastReviewedPlanHash: string | undefined;
   /** 1-based round within the current user-feedback cycle. */
   let reviewRound = 0;
+  /**
+   * Monotonic cycle token. A fresh prompt, an explicit refine/deny, or Build
+   * entry starts a new cycle; async handoffs capture it so a superseded cycle
+   * can never render, apply todos, or clear a newer gate.
+   */
+  let reviewCycleId = 0;
+  /** Plan target the current review cycle belongs to (absolute, or null). */
+  let reviewCyclePlanPath: string | null = null;
+  /** Cycle that owns the parked gate; `0` when no gate is owned. */
+  let reviewGateCycleId = 0;
   /** Findings carried into the next round so the reviewer can verify fixes. */
   let reviewPreviousFindings: ReviewFinding[] | undefined;
   /**
@@ -1343,9 +1395,22 @@ export default function workflowExtension(
         fileHashAtPause?: string;
         round: number;
         previousFindings: ReviewFinding[] | undefined;
+        /** Cycle that recorded the pause; stale cycles are ignored. */
+        cycleId: number;
         at: number;
       }
     | undefined;
+
+  /** The pause only counts while it belongs to the current review cycle. */
+  function currentPausedReview(): typeof pausedReview {
+    if (!pausedReview) return undefined;
+    return reviewPauseIsCurrent({
+      pauseCycle: pausedReview.cycleId,
+      currentCycle: reviewCycleId,
+    })
+      ? pausedReview
+      : undefined;
+  }
   /** In-flight round input (set while `runRound` awaits) — the pause source. */
   let activeReview:
     | { planText: string; round: number; controller: AbortController }
@@ -1384,8 +1449,10 @@ export default function workflowExtension(
    */
   function reviewModeLockKindNow(): ReviewModeLockKind | undefined {
     const roundInFlight = activeReview !== undefined;
-    const paused = pausedReview !== undefined;
-    const gatePhase = reviewGatePhase;
+    const paused = currentPausedReview() !== undefined;
+    // A gate from a superseded cycle must not keep the modes locked.
+    const gatePhase =
+      reviewGateCycleId === reviewCycleId ? reviewGatePhase : "idle";
     let roundActive = false;
     try {
       roundActive = reviewRuntime?.isRoundActive() === true;
@@ -1488,6 +1555,48 @@ export default function workflowExtension(
     }
   }
 
+  /**
+   * Automatic provider-recovery chain: the parent model that just planned,
+   * then the base reviewer and planner roles from roles.json (ignoring the
+   * active profile). Deduped and thinking-clamped through the parent registry.
+   */
+  function reviewFallbackModels(): ReviewFallbackModel[] {
+    try {
+      ensureRoleConfig(reviewCwd());
+      ensureProfilesConfig(reviewCwd());
+      const parent = currentSessionCtx?.model;
+      const parentThinking = currentSessionCtx?.thinkingLevel;
+      const baseReviewer = getRole(roleConfig, REVIEW_ROLE_NAME)?.model;
+      const basePlanner = getRole(roleConfig, "planner")?.model;
+      return buildReviewerFallbacks({
+        ...(parent
+          ? {
+              parentModel: {
+                provider: parent.provider,
+                id: parent.id,
+                thinking: parentThinking ?? "high",
+              },
+            }
+          : {}),
+        ...(baseReviewer ? { baseReviewer } : {}),
+        ...(basePlanner ? { basePlanner } : {}),
+        clampThinking: (model) => {
+          const found = (currentSessionCtx as any)?.modelRegistry?.find?.(
+            model.provider,
+            model.id,
+          );
+          return clampThinkingForModel(
+            found,
+            isValidThinkingLevel(model.thinking) ? model.thinking : "high",
+          );
+        },
+      });
+    } catch (_e) {
+      void _e;
+      return [];
+    }
+  }
+
   /** Reviewer model label for the mode band (best-effort). */
   function reviewModelLabel(): string {
     // While a round runs, the band names the snapshotted model — the one
@@ -1805,23 +1914,24 @@ export default function workflowExtension(
    */
   function updateReviewStatus(ctx: ExtensionContext): void {
     try {
-      const paused = pausedReview !== undefined;
+      const paused = currentPausedReview() !== undefined;
       let roundActive = false;
       try {
         roundActive = reviewRuntime?.isRoundActive() === true;
       } catch (_e) {
         void _e;
       }
-      const visible = reviewStatusVisible({
+      // The review status is a LIVE indicator, not a result holder: the last
+      // round's state stays for `/review-status` and the REVIEW SUMMARY band,
+      // but the footer segment must disappear as soon as the round ends. A
+      // retained terminal phase is not painted during a new round's cold boot,
+      // and a pause from an old cycle is ignored by `currentPausedReview`.
+      const reviewText = reviewStatusText({
+        state: reviewState,
         roundInFlight: activeReview !== undefined,
         roundActive,
         paused,
       });
-      // The review status is a LIVE indicator, not a result holder: the last
-      // round's state stays for `/review-status` and the REVIEW SUMMARY band,
-      // but the footer segment must disappear as soon as the round ends. While
-      // paused it shows the paused form (never the terminal "aborted" summary).
-      const reviewText = visible ? reviewFooterSegment(reviewState, paused) : "";
       let lockText = "";
       try {
         lockText = reviewModeLockFooter(reviewModeLockKindNow());
@@ -1897,6 +2007,7 @@ export default function workflowExtension(
         if (reviewModelSnapshot) return reviewModelSnapshot;
         return resolveReviewerModel();
       },
+      fallbackReviewerModels: () => reviewFallbackModels(),
       findModel: (provider: string, id: string) =>
         (currentSessionCtx as any)?.modelRegistry?.find?.(provider, id),
       // Structural probe of the live parent context, evaluated at reviewer
@@ -1996,7 +2107,7 @@ export default function workflowExtension(
     previousFindings: ReviewFinding[] | undefined;
   }): boolean {
     const hash = planHash(input.planText);
-    if (pausedReview?.planHash === hash) return false;
+    if (currentPausedReview()?.planHash === hash) return false;
     // Snapshot the file as well as the text: the reviewer may already have
     // written its rewrite, and that must not look like an author edit later.
     const currentFile = readCurrentPlanText(reviewCwd());
@@ -2007,6 +2118,7 @@ export default function workflowExtension(
         currentFile !== undefined ? planHash(currentFile) : undefined,
       round: input.round,
       previousFindings: input.previousFindings,
+      cycleId: reviewCycleId,
       at: Date.now(),
     };
     // A gated audit becomes a paused gate (the handoff keeps waiting). A
@@ -2059,7 +2171,7 @@ export default function workflowExtension(
             roundActive:
               activeReview !== undefined ||
               reviewRuntime?.isRoundActive() === true,
-            paused: pausedReview !== undefined,
+            paused: currentPausedReview() !== undefined,
             gatedPause: reviewGatePhase === "paused",
           });
           if (action === "pause") {
@@ -2149,6 +2261,9 @@ export default function workflowExtension(
     try {
       const ctx = currentSessionCtx;
       if (!ctx || !(ctx as any).hasUI) return;
+      if (message !== undefined) {
+        (ctx as any).ui?.setWorkingVisible?.(true);
+      }
       (ctx as any).ui?.setWorkingMessage?.(message);
     } catch (_e) {
       void _e;
@@ -2173,6 +2288,7 @@ export default function workflowExtension(
       // The parked handoff only awaits the gate; it does not re-read the phase
       // after this point.
       reviewGatePhase = "idle";
+      reviewGateCycleId = 0;
     } catch (_e) {
       void _e;
     }
@@ -2219,6 +2335,9 @@ export default function workflowExtension(
     // follow `reviewState`; the spinner row needs an explicit message while
     // the child session streams off the main turn.
     setReviewWorkingMessage("🔍 Reviewing plan…");
+    // Paint the live review line now, not after the child session's first
+    // state event: a manual `/review` must look alive from the first tick.
+    updateStatus(ctx as any);
     // One long-lived listener covers this round AND the paused window (see
     // ensureReviewEscListener for why it is no longer attached per round).
     ensureReviewEscListener(ctx);
@@ -2254,17 +2373,18 @@ export default function workflowExtension(
       // `review_submit_plan` that landed in that window changed the file after
       // the snapshot, so refresh it: otherwise `/review-resume` would read the
       // reviewer's own late write as an author edit and start a fresh round.
-      if (pausedReview?.planHash === hash) {
+      const pausedNow = currentPausedReview();
+      if (pausedNow?.planHash === hash) {
         const currentFile = readCurrentPlanText(reviewCwd());
         if (currentFile !== undefined) {
-          pausedReview.fileHashAtPause = planHash(currentFile);
+          pausedNow.fileHashAtPause = planHash(currentFile);
         }
       }
       reviewState = res.state;
       updateStatus(ctx);
       // The snapshot is the ONLY pause signal. A pre-aborted host signal or a
       // host abort without this snapshot is an abort, never a pause.
-      const pausedHere = pausedReview?.planHash === hash;
+      const pausedHere = pausedNow?.planHash === hash;
       if (res.ok) {
         lastReviewedPlanHash = res.planHash;
         abortedReviewHash = undefined;
@@ -2363,7 +2483,7 @@ export default function workflowExtension(
       detachHostSignal = undefined;
       // A pause keeps its own working message (pauseReviewRound sets it
       // after the abort lands); every other exit restores the default.
-      if (!(pausedReview && pausedReview.planHash === hash)) {
+      if (!(currentPausedReview()?.planHash === hash)) {
         setReviewWorkingMessage(undefined);
       }
       // Ownership ended: refresh both surfaces now that `activeReview` is
@@ -2422,6 +2542,32 @@ export default function workflowExtension(
       };
     }
 
+    // A fresh automatic round supersedes any paused one. Even when this
+    // decision is skipped below, no stale pause/line may survive it.
+    if (trigger === "auto" && pausedReview !== undefined) {
+      pausedReview = undefined;
+      try {
+        if (currentSessionCtx) updateStatus(currentSessionCtx);
+      } catch (_e) {
+        void _e;
+      }
+    }
+
+    // A new round can never inherit an older browser gate: the old tab's
+    // decision would otherwise suppress this round's handoff after it lands.
+    if (awaitingDecision) {
+      supersedePendingHandoff(
+        trigger === "manual"
+          ? "a manual /review started"
+          : "a new review round started",
+        { force: true, nextPlanHash: hash, nextCycleId: reviewCycleId },
+      );
+    }
+
+    // A different plan file is a new target even inside one user run: reset the
+    // budget/hashes/findings before the dedupe gates below.
+    const cycleChanged = notePlanTargetForReviewCycle(currentPlanFile);
+
     // Already reviewed this exact revision — do not re-review on re-emit.
     if (hash === lastReviewedPlanHash) {
       return {
@@ -2441,8 +2587,13 @@ export default function workflowExtension(
       };
     }
 
-    reviewRound += 1;
-    if (reviewRound > cfg.rounds) {
+    const budget = nextReviewRound({
+      round: reviewRound,
+      maxRounds: cfg.rounds,
+      newCycle: cycleChanged,
+    });
+    reviewRound = budget.round;
+    if (!budget.allowed) {
       // Round cap reached: hand over with the outstanding findings visible.
       const unresolved = (reviewState?.findings ?? []).filter(
         (f) => f.disposition !== "rejected",
@@ -2481,6 +2632,11 @@ export default function workflowExtension(
 
     // A fresh round supersedes any paused one (resume uses its own path).
     pausedReview = undefined;
+    try {
+      if (currentSessionCtx) updateStatus(currentSessionCtx);
+    } catch (_e) {
+      void _e;
+    }
 
     try {
       return await executeReviewRound({
@@ -2549,6 +2705,137 @@ export default function workflowExtension(
     if (currentSessionCtx) updateStatus(currentSessionCtx);
   }
 
+  type ReviewCycleReason =
+    | "prompt"
+    | "refine"
+    | "deny"
+    | "build"
+    | "session";
+
+  /**
+   * Start a new review cycle: one plan-authoring/feedback sequence.
+   *
+   * Every fresh prompt, explicit refine/deny, and Build entry owns a cycle.
+   * The cycle token invalidates an old `runHandoff` continuation, the budget
+   * restarts, and an abandoned pause/gate is cancelled (D2) so it cannot keep
+   * the footer line, lock the modes, or short-circuit the next `agent_end`.
+   * Findings survive a same-plan refinement and are cleared for a new file.
+   * Never throws: a broken review surface must not block the prompt.
+   */
+  async function beginReviewCycle(opts: {
+    reason: ReviewCycleReason;
+    keepFindings?: boolean;
+    planPath?: string | null;
+  }): Promise<void> {
+    const hadActive = activeReview !== undefined;
+    const hadPause = currentPausedReview() !== undefined;
+    const hadGate = reviewGatePhase !== "idle";
+    // Synchronously first: any old handoff continuation is stale from here on.
+    reviewCycleId += 1;
+    if (
+      opts.reason === "prompt" ||
+      opts.reason === "build" ||
+      opts.reason === "session"
+    ) {
+      supersedePendingHandoff(`a new ${opts.reason} cycle started`, {
+        force: true,
+      });
+      manualReviewCycle = false;
+    }
+    if (hadActive || pausedReview !== undefined || hadGate) {
+      try {
+        await suspendReview();
+      } catch (_e) {
+        void _e;
+      }
+    }
+    reviewRound = 0;
+    lastReviewedPlanHash = undefined;
+    abortedReviewHash = undefined;
+    if (!hadActive) quietAbortHash = undefined;
+
+    const rawNext = opts.planPath ?? currentPlanFile ?? null;
+    let next: string | null = null;
+    if (rawNext) {
+      try {
+        next = path.isAbsolute(rawNext)
+          ? rawNext
+          : path.join(reviewCwd(), rawNext);
+      } catch (_e) {
+        void _e;
+        next = rawNext;
+      }
+    }
+    const pathChanged =
+      reviewCyclePlanPath !== null &&
+      next !== null &&
+      !samePlanPath(next, reviewCyclePlanPath, reviewCwd());
+    if (pathChanged || opts.keepFindings === false) {
+      reviewPreviousFindings = undefined;
+    }
+    reviewCyclePlanPath = next;
+    reviewGateCycleId = 0;
+
+    if (hadPause || hadGate) {
+      notifyReview(
+        "Paused review abandoned — new work started; the paused round will not resume.",
+        "info",
+      );
+    }
+    try {
+      if (currentSessionCtx) updateStatus(currentSessionCtx);
+    } catch (_e) {
+      void _e;
+    }
+    try {
+      if (reviewEnabled() || hadActive || hadPause || hadGate || reviewState) {
+        pi.appendEntry("workflow-review-cycle", {
+          reason: opts.reason,
+          cycleId: reviewCycleId,
+          planPath: reviewCyclePlanPath,
+          at: Date.now(),
+        });
+      }
+    } catch (_e) {
+      void _e;
+    }
+  }
+
+  /**
+   * A different plan file is a new review target even inside one user run.
+   * Resets the cycle budget and prior findings, but not the cycle token: the
+   * handoff that owns this run must stay current.
+   */
+  function notePlanTargetForReviewCycle(
+    rawPath: string | null | undefined,
+  ): boolean {
+    if (!rawPath) return false;
+    const cwd = reviewCwd();
+    let next: string;
+    try {
+      next = path.isAbsolute(rawPath) ? rawPath : path.join(cwd, rawPath);
+    } catch (_e) {
+      void _e;
+      next = rawPath;
+    }
+    if (reviewCyclePlanPath === null) {
+      reviewCyclePlanPath = next;
+      return false;
+    }
+    if (samePlanPath(next, reviewCyclePlanPath, cwd)) return false;
+    reviewCyclePlanPath = next;
+    reviewRound = 0;
+    lastReviewedPlanHash = undefined;
+    abortedReviewHash = undefined;
+    reviewPreviousFindings = undefined;
+    try {
+      if (currentSessionCtx) updateStatus(currentSessionCtx);
+    } catch (_e) {
+      void _e;
+    }
+    return true;
+  }
+
   /**
    * Stop the reviewer and clear all Review Mode state. Never throws.
    *
@@ -2557,7 +2844,9 @@ export default function workflowExtension(
    * they are not guarded. Clearing the review state releases the derived
    * mode-switch lock (plan 2026-10-25).
    */
-  async function teardownReview(): Promise<void> {
+  async function teardownReview(
+    opts: { keepHandoff?: boolean } = {},
+  ): Promise<void> {
     try {
       activeReview?.controller.abort();
     } catch (_e) {
@@ -2570,6 +2859,7 @@ export default function workflowExtension(
     }
     reviewRuntime = undefined;
     reviewState = undefined;
+    if (opts.keepHandoff !== true) manualReviewCycle = false;
     lastReviewedPlanHash = undefined;
     reviewRound = 0;
     reviewPreviousFindings = undefined;
@@ -2584,11 +2874,12 @@ export default function workflowExtension(
     activeReview = undefined;
     abortedReviewHash = undefined;
     quietAbortHash = undefined;
-    // A teardown ends any pending handoff decision/correlation and the
-    // per-run provenance; a reload cannot inherit either.
-    const clearedDecision = clearPendingHandoffDecision();
+    // A reload/resume keeps the browser correlation so the next session_start
+    // can recover it; every other teardown ends the decision and provenance.
+    const clearedDecision =
+      opts.keepHandoff === true ? false : clearPendingHandoffDecision();
     resetPlanRunProvenance();
-    if (clearedDecision) {
+    if (clearedDecision || opts.keepHandoff === true) {
       try {
         persistState();
       } catch (_e) {
@@ -2930,6 +3221,26 @@ export default function workflowExtension(
       writePolicyArgumentCompletions(prefix),
   });
 
+  // ── /permissions: explain a command's verdict (diagnostics) ────────
+  //
+  // Answers "why was that blocked?" (or "would it be?") without touching a
+  // gate: it reads the same analyzeCommand/explainCommandRefusal the gates
+  // use, so the explanation cannot describe a policy the gate no longer
+  // enforces. Read-only, so it is safe in every mode.
+  pi.registerCommand("permissions", {
+    description:
+      "Explain why a shell command would be allowed or refused: /permissions explain <command>",
+    handler: async (args, ctx) => {
+      const raw = String(args ?? "").trim();
+      const first = raw.split(/\s+/)[0]?.toLowerCase() ?? "";
+      // `/permissions explain <cmd>` and `/permissions <cmd>` both work.
+      const command = first === "explain" ? raw.slice("explain".length).trim() : raw;
+      ctx.ui.notify(describeCommandPolicy(command).join("\n"), "info");
+    },
+    getArgumentCompletions: (prefix: string) =>
+      permissionsArgumentCompletions(prefix),
+  });
+
   pi.registerCommand("review-prompt", {
     description:
       "Edit the reviewer's guidance (framework alignment / best practice) used by Review Mode",
@@ -2974,11 +3285,13 @@ export default function workflowExtension(
       const s = reviewState;
       const lockKind = reviewModeLockKindNow();
       if (!s) {
-        if (pausedReview) {
+        const paused = currentPausedReview();
+        if (paused) {
           ctx.ui.notify(
             [
-              `Review paused at round ${pausedReview.round} (plan hash ${pausedReview.planHash})`,
+              `Review paused at round ${paused.round} (plan hash ${paused.planHash})`,
               "  /review-resume to continue, /review-abort to stop.",
+              pendingHandoffStatusLine(),
               reviewModeLockStatusLine(lockKind),
             ]
               .filter(Boolean)
@@ -2999,6 +3312,7 @@ export default function workflowExtension(
             reviewEnabled()
               ? "Review Mode is enabled but no review has run yet."
               : `Review Mode is OFF — automatic review disabled (/review-mode on to enable).${cfgLine} /review runs a one-shot review.`,
+            pendingHandoffStatusLine(),
             reviewModeLockStatusLine(lockKind),
           ]
             .filter(Boolean)
@@ -3011,12 +3325,16 @@ export default function workflowExtension(
         reviewStateSummary(s),
         `  phase   : ${s.phase}   round: ${s.round}   pass: ${s.pass}`,
         `  model   : ${s.modelLabel}`,
+        `  attempt : ${s.recoveryAttempts?.length ? s.recoveryAttempts.join(" → ") : "single model"}`,
+        `  elapsed : ${Math.round(reviewElapsedMs(s) / 1000)}s${
+          s.providerError ? `   provider: ${s.providerError.slice(0, 200)}` : ""
+        }`,
         `  plan    : ${s.planPath ?? "(unknown)"}  hash ${s.planHash}`,
         `  explore : ${s.exploreUsed} subagent(s)   tokens≈${s.tokenEstimate ?? "n/a"}`,
         s.verdict ? `  verdict : ${s.verdict}` : "",
         s.error ? `  error   : ${s.error}` : "",
-        pausedReview
-          ? `  paused  : round ${pausedReview.round} — /review-resume to continue, /review-abort to stop`
+        currentPausedReview()
+          ? `  paused  : round ${currentPausedReview()!.round} — /review-resume to continue, /review-abort to stop`
           : "",
         abortedReviewHash
           ? `  note    : revision ${abortedReviewHash} was aborted — it will not be auto-reviewed until the plan changes`
@@ -3024,6 +3342,7 @@ export default function workflowExtension(
         reviewRuntime?.isRoundActive()
           ? "  live    : round in flight — /role and /profile switches apply next round; /review say <msg> to steer"
           : "",
+        pendingHandoffStatusLine(),
         reviewModeLockStatusLine(lockKind),
         ...s.findings.map(
           (f) =>
@@ -3181,6 +3500,7 @@ export default function workflowExtension(
       }
       currentPlanFile = target.abs;
       lastPlanWritePath = target.abs;
+      notePlanTargetForReviewCycle(target.abs);
       persistState();
       lastReviewedPlanHash = undefined; // force a fresh review
       abortedReviewHash = undefined;
@@ -3197,6 +3517,16 @@ export default function workflowExtension(
       const offSuffix = reviewEnabled()
         ? ""
         : " (Review Mode stays OFF — /review-mode on for automatic review.)";
+      if (
+        await openManualHandoff(
+          result,
+          target.abs,
+          ctx as any,
+          offSuffix,
+        )
+      ) {
+        return;
+      }
       ctx.ui.notify(`${reviewResumeNotice(result)}${offSuffix}`, "info");
     },
   });
@@ -3209,7 +3539,7 @@ export default function workflowExtension(
       // Gate only on round ownership below — no `enabled` check here.
       if (!activeReview) {
         ctx.ui.notify(
-          pausedReview
+          currentPausedReview()
             ? "Review is already paused — /review-resume to continue, /review-abort to stop."
             : "No review round running.",
           "info",
@@ -3229,7 +3559,7 @@ export default function workflowExtension(
     handler: async (_args, ctx) => {
       // Manual control: resume works whether or not Review Mode is on.
       // Gate only on paused-session state below — no `enabled` check here.
-      const paused = pausedReview;
+      const paused = currentPausedReview();
       if (!paused) {
         ctx.ui.notify("No paused review — nothing to resume.", "info");
         return;
@@ -3241,6 +3571,9 @@ export default function workflowExtension(
         ctx.ui.notify("A review round is already running.", "warning");
         return;
       }
+      // A gated resume is settled by its parked runHandoff; a manual pause
+      // (idle gate) opens its own browser handoff after the round lands.
+      const gatedResume = reviewGatePhase !== "idle";
       // A resumed gated review is auditing again. Without this, the parked
       // handoff keeps `reviewGatePhase === "paused"` for the whole round and
       // the lock/footer report the wrong state (plan 2026-10-25 follow-up).
@@ -3284,7 +3617,15 @@ export default function workflowExtension(
             planText: result.planText,
           });
         }
-        ctx.ui.notify(reviewResumeNotice(result), "info");
+        if (!gatedResume && reviewResumeSettles(result)) {
+          await openManualHandoff(
+            result,
+            currentPlanFile ?? "",
+            ctx as any,
+          );
+        } else {
+          ctx.ui.notify(reviewResumeNotice(result), "info");
+        }
         return;
       }
       pausedReview = undefined;
@@ -3309,7 +3650,11 @@ export default function workflowExtension(
           planText: result.planText,
         });
       }
-      ctx.ui.notify(reviewResumeNotice(result), "info");
+      if (!gatedResume && reviewResumeSettles(result)) {
+        await openManualHandoff(result, currentPlanFile ?? "", ctx as any);
+      } else {
+        ctx.ui.notify(reviewResumeNotice(result), "info");
+      }
     },
   });
 
@@ -3323,17 +3668,18 @@ export default function workflowExtension(
       const rt = reviewRuntime;
       const active =
         activeReview !== undefined || rt?.isRoundActive() === true;
-      if (!active && !pausedReview) {
+      const paused = currentPausedReview();
+      if (!active && !paused) {
         ctx.ui.notify("No review running or paused.", "info");
         return;
       }
       const targetHash =
-        pausedReview?.planHash ??
+        paused?.planHash ??
         (activeReview ? planHash(activeReview.planText) : undefined);
       // Text the gate hands off when one is open (resolved below after the
       // abort lands; falls back to the author's draft when unknown).
       const abortedText =
-        pausedReview?.planText ?? activeReview?.planText;
+        paused?.planText ?? activeReview?.planText;
       pausedReview = undefined;
       // An aborted revision is not auto-reviewed again until the plan changes.
       if (targetHash) abortedReviewHash = targetHash;
@@ -3812,6 +4158,16 @@ export default function workflowExtension(
       planFile: currentPlanFile,
       awaitingDecision,
       awaitingDecisionAt: awaitingDecision ? lastHandoffAt : undefined,
+      // Full correlation: a restored gate must know which browser review it
+      // belongs to, or it can only suppress the next handoff.
+      lastReviewId: awaitingDecision ? lastReviewId : null,
+      pendingHandoffPlanPath: awaitingDecision ? pendingHandoffPlanPath : null,
+      pendingHandoffPlanHash: awaitingDecision ? pendingHandoffPlanHash : null,
+      pendingHandoffRequestId: awaitingDecision ? pendingHandoffRequestId : null,
+      pendingHandoffSource: awaitingDecision ? pendingHandoffSource : null,
+      pendingHandoffCycleId: awaitingDecision ? pendingHandoffCycleId : 0,
+      pendingHandoffReviewUrl: awaitingDecision ? pendingHandoffReviewUrl : null,
+      manualReviewCycle,
       role: {
         activeRole: roleConfig.activeRole,
         // Session-scoped profile activation (see setActiveProfile): explicit
@@ -3920,8 +4276,14 @@ export default function workflowExtension(
     updateStatus(ctx);
     persistState();
     // Tab-to-Build leaves Plan behind; suspend review activity but keep the
-    // reviewer session warm for the next round (step 10).
+    // reviewer session warm for the next round (step 10). End the review cycle
+    // so its budget/findings cannot leak into the next Plan round.
     await suspendReview();
+    try {
+      await beginReviewCycle({ reason: "build", keepFindings: false });
+    } catch (_e) {
+      void _e;
+    }
   }
 
   async function setDefaultMode(
@@ -4067,6 +4429,15 @@ export default function workflowExtension(
     // user just approved (step 10).
     await suspendReview();
     currentPlanFile = planPath;
+    try {
+      await beginReviewCycle({
+        reason: "build",
+        keepFindings: false,
+        planPath,
+      });
+    } catch (_e) {
+      void _e;
+    }
     pi.setActiveTools(
       toolsBeforePlanMode ?? getBuildTools(pi.getActiveTools()),
     );
@@ -4093,6 +4464,365 @@ export default function workflowExtension(
     return currentSessionCtx;
   }
 
+  /**
+   * Adopt the review id/url Plannotator announced. This is the only place the
+   * transcript handoff entry is written, so a `respond` callback and a
+   * `session-opened` event for the same review cannot duplicate it.
+   */
+  function adoptPlannotatorSession(event: PlannotatorSessionEventLike): void {
+    if (!awaitingDecision) return;
+    if (typeof event.reviewId === "string" && event.reviewId) {
+      lastReviewId = event.reviewId;
+    }
+    if (!lastReviewId) return;
+    if (typeof event.url === "string" && event.url) {
+      pendingHandoffReviewUrl = event.url;
+    }
+    if (recordedHandoffReviewId !== lastReviewId) {
+      recordedHandoffReviewId = lastReviewId;
+      try {
+        pi.appendEntry("workflow-handoff-plannotator", {
+          at: Date.now(),
+          planPath: pendingHandoffPlanPath ?? currentPlanFile,
+          reviewId: lastReviewId,
+          ...(pendingHandoffReviewUrl
+            ? { reviewUrl: pendingHandoffReviewUrl }
+            : {}),
+          planTextLen: pendingHandoffPlanTextLen,
+          source: pendingHandoffSource ?? "auto",
+        });
+      } catch (_e) {
+        void _e;
+      }
+      notifyReview(
+        "Plan opened in browser for review. Approve or annotate there.",
+        "info",
+      );
+    }
+    try {
+      persistState();
+    } catch (_e) {
+      void _e;
+    }
+    try {
+      if (currentSessionCtx) updateStatus(currentSessionCtx);
+    } catch (_e) {
+      void _e;
+    }
+  }
+
+  /** Settle the one in-flight plan-review request exactly once. */
+  function settlePlanReviewRequest(outcome: PlanReviewRequestOutcome): boolean {
+    const pending = pendingPlanReviewRequest;
+    if (!pending || pending.settled) return false;
+    pending.settled = true;
+    pendingPlanReviewRequest = undefined;
+    pending.finish(outcome);
+    return true;
+  }
+
+  /**
+   * Ask Plannotator to open a plan review and wait for its lifecycle.
+   *
+   * The `respond` callback is the fast path; `plannotator:session-opened` is
+   * the authoritative one (it carries the URL and survives a slow handler).
+   * A timeout clears the gate so the caller can render its own fallback; it
+   * never retries, because a late event would then open a duplicate review.
+   */
+  async function requestPlanReview(input: {
+    planText: string;
+    planPath: string;
+    source: ReviewHandoffSource;
+    ctx: ExtensionContext;
+    cycleId?: number;
+  }): Promise<{ ok: true; reviewId?: string } | { ok: false; reason: string }> {
+    const bus: any = (pi as any).events;
+    if (!plannotatorActive || !bus || typeof bus.emit !== "function") {
+      return { ok: false, reason: "Plannotator is not available in this session" };
+    }
+    if (!input.planText.trim() || !input.planPath) {
+      return { ok: false, reason: "the reviewed plan has no file to hand off" };
+    }
+    // A second request supersedes the first waiter without opening a race.
+    settlePlanReviewRequest({
+      status: "error",
+      reason: "superseded by a newer handoff",
+    });
+    const requestId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    awaitingDecision = true;
+    lastHandoffAt = Date.now();
+    pendingHandoffPlanPath = input.planPath;
+    pendingHandoffPlanHash = planHash(input.planText);
+    pendingHandoffPlanTextLen = input.planText.length;
+    pendingHandoffRequestId = requestId;
+    pendingHandoffSource = input.source;
+    pendingHandoffCycleId = input.cycleId ?? reviewCycleId;
+    pendingHandoffReviewUrl = null;
+    lastReviewId = null;
+    recordedHandoffReviewId = null;
+    persistState();
+    const timeoutMs = Math.max(50, deps.plannotatorRequestTimeoutMs ?? 15_000);
+    const response = await new Promise<PlanReviewRequestOutcome>((resolve) => {
+      let settled = false;
+      const settle = (outcome: PlanReviewRequestOutcome): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (pendingPlanReviewRequest?.requestId === requestId) {
+          pendingPlanReviewRequest = undefined;
+        }
+        resolve(outcome);
+      };
+      const timer = setTimeout(() => {
+        settle({
+          status: "timeout",
+          reason: `Plannotator did not answer within ${Math.round(timeoutMs / 1000)}s`,
+        });
+      }, timeoutMs);
+      pendingPlanReviewRequest = {
+        requestId,
+        settled: false,
+        finish: settle,
+      };
+      try {
+        bus.emit(PLANNOTATOR_REQUEST, {
+          requestId,
+          action: "plan-review",
+          payload: {
+            planContent: input.planText,
+            planFilePath: input.planPath,
+            reviewPending: false,
+            reviewSummary: reviewState
+              ? {
+                  modelLabel: reviewState.modelLabel,
+                  round: reviewState.round,
+                  verdict: reviewState.verdict,
+                  findings: reviewState.findings.length,
+                }
+              : undefined,
+          },
+          respond: (res: any) => {
+            if (
+              res &&
+              res.status === "handled" &&
+              typeof res.result?.reviewId === "string"
+            ) {
+              settle({
+                status: "handled",
+                reviewId: res.result.reviewId,
+              });
+            } else {
+              settle({
+                status: "error",
+                reason: `Plannotator answered ${String(res?.status ?? "nothing")}`,
+              });
+            }
+          },
+        });
+      } catch (e: any) {
+        settle({
+          status: "error",
+          reason: `Plannotator request failed: ${String(e?.message ?? e)}`,
+        });
+      }
+    });
+    if (response.status === "handled") {
+      adoptPlannotatorSession({
+        ...(response.reviewId ? { reviewId: response.reviewId } : {}),
+        ...(response.url ? { url: response.url } : {}),
+      });
+      return { ok: true, ...(response.reviewId ? { reviewId: response.reviewId } : {}) };
+    }
+    const changed = clearPendingHandoffDecision();
+    if (changed) persistState();
+    try {
+      pi.appendEntry("workflow-handoff-plannotator-failed", {
+        at: Date.now(),
+        reason: response.reason,
+        source: input.source,
+        planPath: input.planPath,
+      });
+    } catch (_e) {
+      void _e;
+    }
+    notifyReview(`Plannotator handoff unavailable — ${response.reason}.`, "warning");
+    return { ok: false, reason: response.reason };
+  }
+
+  /** Ask Plannotator for the durable status of one review. */
+  async function queryPlannotatorReviewStatus(reviewId: string): Promise<{
+    status: "pending" | "completed" | "missing";
+    approved?: boolean;
+    feedback?: string;
+    savedPath?: string;
+  }> {
+    const bus: any = (pi as any).events;
+    if (!plannotatorActive || !bus || typeof bus.emit !== "function") {
+      return { status: "missing" };
+    }
+    const timeoutMs = Math.max(50, deps.plannotatorRecoveryTimeoutMs ?? 3_000);
+    return await new Promise((resolve) => {
+      let settled = false;
+      const finish = (value: any): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(
+          value &&
+            (value.status === "pending" ||
+              value.status === "completed" ||
+              value.status === "missing")
+            ? value
+            : { status: "missing" },
+        );
+      };
+      const timer = setTimeout(() => finish({ status: "missing" }), timeoutMs);
+      try {
+        bus.emit(PLANNOTATOR_REQUEST, {
+          requestId: `${Date.now()}-status`,
+          action: "review-status",
+          payload: { reviewId },
+          respond: (res: any) => {
+            if (res?.status === "handled" && res.result) finish(res.result);
+            else finish({ status: "missing" });
+          },
+        });
+      } catch {
+        finish({ status: "missing" });
+      }
+    });
+  }
+
+  /**
+   * Recover the one pending browser handoff after a session reload/resume.
+   *
+   * `startup`/`new` cannot own the old loopback server, so they clear. For a
+   * reload/resume/fork, Plannotator's durable `review-status` decides: pending
+   * keeps the gate (when the plan hash still matches), completed applies the
+   * recorded decision, and missing/changed clears with a visible reason.
+   */
+  async function recoverPendingHandoff(
+    ctx: ExtensionContext,
+    reason: string,
+  ): Promise<void> {
+    if (recoveryInFlight) return recoveryInFlight;
+    recoveryInFlight = (async () => {
+      const record = (action: string, detail: Record<string, unknown> = {}) => {
+        try {
+          pi.appendEntry("workflow-handoff-recovery", {
+            action,
+            reason,
+            at: Date.now(),
+            ...detail,
+          });
+        } catch (_e) {
+          void _e;
+        }
+      };
+      if (!awaitingDecision) return;
+      if (reason === "startup" || reason === "new" || !lastReviewId) {
+        const changed = clearPendingHandoffDecision();
+        if (changed) persistState();
+        record("clear", { why: "no restorable review" });
+        return;
+      }
+      const currentFile = readCurrentPlanText(reviewCwd());
+      const status = await queryPlannotatorReviewStatus(lastReviewId);
+      const decision = reviewHandoffRecovery({
+        status: status.status,
+        approved: status.approved,
+        feedback: status.feedback,
+        savedPath: status.savedPath,
+        pendingHash: pendingHandoffPlanHash ?? undefined,
+        currentHash:
+          currentFile !== undefined ? planHash(currentFile) : undefined,
+      });
+      if (decision.action === "keep") {
+        if (pendingHandoffSource === "manual") manualReviewCycle = true;
+        record("keep", {
+          reviewId: lastReviewId,
+          ...(pendingHandoffReviewUrl
+            ? { reviewUrl: pendingHandoffReviewUrl }
+            : {}),
+        });
+        notifyReview(
+          `Browser review still open${pendingHandoffReviewUrl ? `: ${pendingHandoffReviewUrl}` : ""} — approve or annotate there.`,
+          "info",
+        );
+        updateStatus(ctx as any);
+        return;
+      }
+      if (decision.action === "apply") {
+        record("apply", {
+          reviewId: lastReviewId,
+          approved: decision.approved,
+        });
+        if (decision.approved) {
+          handlePlannotatorApprove(
+            pendingHandoffPlanPath ?? currentPlanFile ?? "",
+            currentFile ?? "",
+            decision.feedback,
+            ctx.cwd,
+          );
+        } else {
+          await handlePlannotatorDeny(
+            decision.feedback || "Plan needs revision.",
+          );
+        }
+        return;
+      }
+      const changed = clearPendingHandoffDecision();
+      if (changed) persistState();
+      record("clear", { why: decision.reason, reviewId: lastReviewId ?? "" });
+      notifyReview(
+        `Previous browser review could not be recovered — ${decision.reason}.`,
+        "warning",
+      );
+      updateStatus(ctx as any);
+    })();
+    try {
+      await recoveryInFlight;
+    } finally {
+      recoveryInFlight = null;
+    }
+  }
+
+  /**
+   * Open the browser handoff for a settled manual `/review` or resume.
+   * Returns true when the browser owns the decision (or the result is not
+   * handoff-eligible); false when the round paused/aborted and the caller
+   * should show its normal resume notice.
+   */
+  async function openManualHandoff(
+    result: ReviewExecutionResult,
+    planPath: string,
+    ctx: ExtensionContext,
+    suffix = "",
+  ): Promise<boolean> {
+    if (!shouldHandoffManualResult(result)) return false;
+    const previousManualCycle = manualReviewCycle;
+    manualReviewCycle = true;
+    const handoff = await requestPlanReview({
+      planText: result.planText,
+      planPath,
+      source: "manual",
+      ctx,
+    });
+    if (handoff.ok) {
+      ctx.ui.notify(
+        "Plan opened in browser for review. Approve or annotate there." + suffix,
+        "info",
+      );
+      return true;
+    }
+    manualReviewCycle = previousManualCycle;
+    ctx.ui.notify(
+      `Manual review finished, but Plannotator is unavailable (${handoff.reason}). The reviewed plan is at ${planPath}.`,
+      "warning",
+    );
+    return true;
+  }
+
   function handlePlannotatorApprove(
     planFilePath: string,
     planContent: string,
@@ -4101,10 +4831,18 @@ export default function workflowExtension(
   ) {
     const ctx = getActiveCtx();
     if (!ctx) return;
-    if (workflowMode !== "plan") return;
+    // A manual `/review` handoff may be approved from Default/Build; an
+    // automatic handoff only exists in Plan mode.
+    if (workflowMode !== "plan" && pendingHandoffSource !== "manual") return;
     // A stale browser approve while a review runs must not clear the pending
     // decision or send the execute messages: the plan is still being audited.
-    if (blockModeSwitchDuringReview(ctx as any)) return;
+    if (blockModeSwitchDuringReview(ctx as any)) {
+      supersedePendingHandoff(
+        "a browser decision arrived while a new review round was running",
+        { force: true },
+      );
+      return;
+    }
     // No prompt means no decision to consume. A fresh prompt/mode switch
     // clears this, so an old browser tab cannot approve the previous plan.
     if (!awaitingDecision) return;
@@ -4160,6 +4898,7 @@ export default function workflowExtension(
     } catch (_e) {
       void _e;
     }
+    if (pendingHandoffSource === "manual") manualReviewCycle = false;
     clearPendingHandoffDecision();
     void enterBuildModeFromPlan(ctx as any, resolvedPlan)
       .then(() => updateStatus(ctx as any))
@@ -4205,20 +4944,39 @@ export default function workflowExtension(
     }
   }
 
-  function handlePlannotatorDeny(feedback: string) {
+  async function handlePlannotatorDeny(feedback: string) {
     const ctx = getActiveCtx();
     if (!ctx) return;
     // Not a mode transition, but while a review owns the turn every browser
     // decision is stale: injecting feedback here would mutate the plan under
     // the reviewer. A legitimate deny only arrives after the gate resolves.
-    if (blockModeSwitchDuringReview(ctx as any)) return;
+    if (blockModeSwitchDuringReview(ctx as any)) {
+      supersedePendingHandoff(
+        "a browser decision arrived while a new review round was running",
+        { force: true },
+      );
+      return;
+    }
     if (!awaitingDecision) return;
+    const manualSource = pendingHandoffSource === "manual";
+    if (manualSource && workflowMode !== "plan") {
+      // A manual review can be launched from Default/Build. Its feedback is a
+      // plan revision, so switch to Plan before the follow-up turn starts.
+      try {
+        await setPlanMode(ctx as any, { quiet: true });
+      } catch (_e) {
+        void _e;
+      }
+      notifyReview(
+        "Review feedback — switched to Plan mode for the revision.",
+        "info",
+      );
+    }
     clearPendingHandoffDecision();
     // Feedback cycle: the next plan revision gets a fresh review round, and the
     // outstanding findings are carried forward so the reviewer can confirm they
     // were actually addressed rather than re-raising them.
-    reviewRound = 0;
-    lastReviewedPlanHash = undefined;
+    await beginReviewCycle({ reason: "deny", keepFindings: true });
     persistState();
     try {
       const todoListText = formatTodoNumberedList(todoItems, { glyph: true });
@@ -4295,12 +5053,60 @@ export default function workflowExtension(
               (getActiveCtx() as any)?.cwd,
             );
           } else {
-            handlePlannotatorDeny(event.feedback || "Plan needs revision.");
+            void handlePlannotatorDeny(
+              event.feedback || "Plan needs revision.",
+            );
           }
         } catch (_e) {
           void _e;
         }
       });
+      // session-opened is authoritative: it carries the review id and URL even
+      // when the request's respond callback is slow or lost. It can arrive
+      // before or after respond; both paths settle the same waiter once.
+      bus.on(PLANNOTATOR_SESSION_OPENED, (event: any) => {
+        try {
+          if (!event || typeof event !== "object") return;
+          const matchesWaiting =
+            typeof event.requestId === "string" &&
+            event.requestId === pendingPlanReviewRequest?.requestId;
+          const matchesCurrent =
+            typeof event.requestId === "string" &&
+            event.requestId === pendingHandoffRequestId;
+          if (!matchesWaiting && !matchesCurrent) return;
+          adoptPlannotatorSession({
+            reviewId: event.reviewId,
+            url: event.url,
+          });
+          if (matchesWaiting) {
+            settlePlanReviewRequest({
+              status: "handled",
+              reviewId:
+                typeof event.reviewId === "string" ? event.reviewId : undefined,
+              url: typeof event.url === "string" ? event.url : undefined,
+            });
+          }
+        } catch (_e) {
+          void _e;
+        }
+      });
+      // A review closed without a decision must not leave a phantom gate that
+      // suppresses the next round. approved/submitted decisions still flow
+      // through review-result (and, after a reload, review-status).
+      bus.on(PLANNOTATOR_SESSION_CLOSED, (event: any) => {
+        try {
+          if (!event || typeof event !== "object") return;
+          if (event.outcome !== "closed") return;
+          if (!lastReviewId || event.reviewId !== lastReviewId) return;
+          if (!awaitingDecision) return;
+          supersedePendingHandoff(
+            "the browser review closed without a decision",
+            { force: true },
+          );
+        } catch (_e) {
+          void _e;
+        }
+      });
       plannotatorListenersRegistered = true;
       plannotatorActive = true;
       const ctx = getActiveCtx();
@@ -5198,7 +6004,8 @@ export default function workflowExtension(
     "Usage: /profile (picker) | /profile list | /profile show <name> | " +
     "/profile use <name|none> | /profile create <name> | /profile edit <name> | " +
     "/profile rename <old> <new> | /profile delete <name> | " +
-    "/profile default [name|none] [global|project]";
+    "/profile default [name|none] [global|project] | " +
+    "/profile retarget-provider <old> <new> [global|project] [--apply]";
 
   /** Effective workflow.defaultProfile for display (never throws). */
   function currentDefaultProfileName(cwd?: string): string | undefined {
@@ -6609,6 +7416,79 @@ export default function workflowExtension(
         return;
       }
 
+      if (sub === "retarget-provider" || sub === "retarget") {
+        const [oldProvider, newProvider, ...flags] = rest;
+        if (!oldProvider || !newProvider) {
+          ctx.ui.notify(
+            "Usage: /profile retarget-provider <old> <new> [global|project] [--apply]\n" +
+              "Rewrite every role/profile model ref from one provider to another. " +
+              "Without --apply it only prints the planned changes.",
+            "info",
+          );
+          return;
+        }
+        if (oldProvider === newProvider) {
+          ctx.ui.notify(
+            `Provider is already "${oldProvider}" — nothing to retarget.`,
+            "info",
+          );
+          return;
+        }
+        const apply = flags.some((flag) => {
+          const value = flag.toLowerCase();
+          return value === "--apply" || value === "apply";
+        });
+        const scope = flags.some((flag) => flag.toLowerCase() === "project")
+          ? "project"
+          : "global";
+        const targetCwd = cwd ?? (ctx as any).cwd ?? process.cwd();
+        const result = retargetProviderFiles({
+          profilesPath:
+            scope === "project"
+              ? projectProfilesPath(targetCwd)
+              : userProfilesPath(),
+          rolesPath:
+            scope === "project"
+              ? projectRolesPath(targetCwd)
+              : userRolesPath(),
+          oldProvider,
+          newProvider,
+          dryRun: !apply,
+        });
+        const summary = formatRetargetResult(result);
+        if (
+          result.profiles.status === "invalid" ||
+          result.roles.status === "invalid"
+        ) {
+          ctx.ui.notify(summary, "error");
+          return;
+        }
+        if (!apply) {
+          ctx.ui.notify(
+            `${summary}\n\nScope: ${scope}. A malformed file blocks both writes.`,
+            "info",
+          );
+          return;
+        }
+        // The files changed underneath the cached configs. Force a reload so
+        // the active profile/role resolves the new provider immediately.
+        roleConfigLoadedFor = undefined;
+        profilesLoadedFor = undefined;
+        invalidateEffectiveRoles();
+        ensureRoleConfig(targetCwd);
+        ensureProfilesConfig(targetCwd);
+        updateStatus(ctx as any);
+        if (workflowMode) {
+          try {
+            await applyModeModel(ctx as any);
+          } catch (_e) {
+            void _e;
+          }
+        }
+        ctx.ui.notify(`${summary}\n\nScope: ${scope}.`, "info");
+        return;
+      }
+
       if (sub === "default") {
         // /profile default [name|none] [global|project]
         const target = rest.find(
@@ -8133,31 +9013,39 @@ export default function workflowExtension(
               typeof d.awaitingDecisionAt === "number"
                 ? d.awaitingDecisionAt
                 : undefined;
-            // Stale guard: if awaitingDecision was persisted >60s ago (crash while modal open), reset
-            if (
-              awaitingDecision &&
-              lastHandoffAt &&
-              Date.now() - lastHandoffAt > 60_000
-            ) {
-              awaitingDecision = false;
-              lastHandoffAt = undefined;
-              try {
-                (ctx as any).ui?.notify?.(
-                  "Recovered stale handoff gate — showing again",
-                  "info",
-                );
-              } catch (_e) {
-                void _e;
-              }
-              try {
-                pi.appendEntry("workflow-handoff-stale-reset", {
-                  at: Date.now(),
-                  lastHandoffAt,
-                });
-              } catch (_e) {
-                void _e;
-              }
-            }
+            // Restore the whole correlation, not just the boolean: recovery
+            // and stale-browser correlation both need the review identity.
+            lastReviewId =
+              typeof (d as any).lastReviewId === "string"
+                ? (d as any).lastReviewId
+                : null;
+            pendingHandoffPlanPath =
+              typeof (d as any).pendingHandoffPlanPath === "string"
+                ? (d as any).pendingHandoffPlanPath
+                : null;
+            pendingHandoffPlanHash =
+              typeof (d as any).pendingHandoffPlanHash === "string"
+                ? (d as any).pendingHandoffPlanHash
+                : null;
+            pendingHandoffRequestId =
+              typeof (d as any).pendingHandoffRequestId === "string"
+                ? (d as any).pendingHandoffRequestId
+                : null;
+            pendingHandoffSource =
+              (d as any).pendingHandoffSource === "manual"
+                ? "manual"
+                : (d as any).pendingHandoffSource === "auto"
+                  ? "auto"
+                  : null;
+            pendingHandoffCycleId =
+              typeof (d as any).pendingHandoffCycleId === "number"
+                ? (d as any).pendingHandoffCycleId
+                : 0;
+            pendingHandoffReviewUrl =
+              typeof (d as any).pendingHandoffReviewUrl === "string"
+                ? (d as any).pendingHandoffReviewUrl
+                : null;
+            manualReviewCycle = (d as any).manualReviewCycle === true;
           }
         }
         if (
@@ -8383,9 +9271,10 @@ export default function workflowExtension(
     resetPlanRunProvenance();
     lastPlanWritePath = currentPlanFile ?? null;
     lastPersistedPlanFile = currentPlanFile;
-    pendingHandoffPlanPath = null;
-    pendingHandoffPlanHash = null;
-    lastReviewId = null;
+    // The pending correlation is restored above. Recovery (step 15) decides
+    // whether it survives; do not null it here, or a restored gate can only
+    // suppress the next handoff.
+    if (!awaitingDecision) clearPendingHandoffDecision();
     currentSessionCtx = ctx as any;
     // Give Tab back to autocomplete while a suggestion list is visible; the raw
     // `tab` shortcut keeps cycling modes otherwise.
@@ -8418,10 +9307,14 @@ export default function workflowExtension(
     } catch (_e) {
       void _e;
     }
+    // Recovery is asynchronous (it may query Plannotator); session start must
+    // not wait up to the status timeout. The gate is restored/cleared before
+    // the next user turn.
+    void recoverPendingHandoff(ctx as ExtensionContext, event.reason);
     updateStatus(ctx as any);
   });
 
-  pi.on("session_shutdown", async (_event, ctx) => {
+  pi.on("session_shutdown", async (event, ctx) => {
     // A write denial is run-scoped; the session is going away, so drop it.
     writeGateRunDenials.clear();
     writeGateTurnAnswer = null;
@@ -8440,11 +9333,17 @@ export default function workflowExtension(
       }
     }
     activeSubagents.clear();
-    // Ensure a handoff decision/provenance does not persist stale across restart
-    const clearedAtShutdown = clearPendingHandoffDecision();
+    // A reload/resume/fork can recover a browser review in the replacement
+    // session; quitting or starting a new session cannot own the old server.
+    const keepPending =
+      event.reason === "reload" ||
+      event.reason === "resume" ||
+      event.reason === "fork";
+    const clearedAtShutdown =
+      keepPending === true ? false : clearPendingHandoffDecision();
     resetPlanRunProvenance();
     resetSessionPlanProvenance();
-    if (clearedAtShutdown) {
+    if (clearedAtShutdown || keepPending === true) {
       try {
         persistState();
       } catch (_e) {
@@ -8462,7 +9361,7 @@ export default function workflowExtension(
     pendingCommitFlow = null;
     // Release the reviewer session (and its custom tools) on shutdown so a
     // reload or quit never leaves an orphaned in-process session behind.
-    await teardownReview();
+    await teardownReview({ keepHandoff: keepPending });
     currentSessionCtx = null;
   });
 
@@ -9485,6 +10384,18 @@ export default function workflowExtension(
     } catch (_e) {
       void _e;
     }
+    // Every fresh prompt is a new review cycle: reset the round budget, cancel
+    // an abandoned pause/gate, and tag the cycle so an old handoff cannot
+    // render after this prompt.
+    try {
+      await beginReviewCycle({
+        reason: "prompt",
+        keepFindings: true,
+        planPath: currentPlanFile,
+      });
+    } catch (_e) {
+      void _e;
+    }
     // Capture header for next checkpoint commit message (first line of prompt)
     try {
       const raw = String((event as any).prompt ?? (event as any).text ?? "");
@@ -9665,6 +10576,25 @@ export default function workflowExtension(
   /** Plan path/hash the currently rendered handoff prompt belongs to. */
   let pendingHandoffPlanPath: string | null = null;
   let pendingHandoffPlanHash: string | null = null;
+  let pendingHandoffRequestId: string | null = null;
+  let pendingHandoffSource: ReviewHandoffSource | null = null;
+  let pendingHandoffCycleId = 0;
+  let pendingHandoffReviewUrl: string | null = null;
+  let pendingHandoffPlanTextLen = 0;
+  /** The one in-flight `plannotator:request` waiter; settles exactly once. */
+  let pendingPlanReviewRequest:
+    | {
+        requestId: string;
+        settled: boolean;
+        finish: (outcome: PlanReviewRequestOutcome) => void;
+      }
+    | undefined;
+  /** The review id already recorded in the transcript (one entry per review). */
+  let recordedHandoffReviewId: string | null = null;
+  /** A manual `/review` owns the following feedback cycle (even when auto is off). */
+  let manualReviewCycle = false;
+  /** One reload recovery at a time (session_start may re-enter). */
+  let recoveryInFlight: Promise<void> | null = null;
   /** Last path announced by the suppressed-handoff notice (per run). */
   let lastPlanReadyNoticeKey: string | null = null;
 
@@ -9689,18 +10619,88 @@ export default function workflowExtension(
    * switch supersedes it; stale browser events must not approve the old plan.
    * Returns true when persisted state changed so the caller can persist once.
    */
+  /** One `/review-status` row for a browser handoff awaiting a decision. */
+  function pendingHandoffStatusLine(): string {
+    if (!awaitingDecision) return "";
+    const age = lastHandoffAt
+      ? Math.max(0, Math.round((Date.now() - lastHandoffAt) / 1000))
+      : 0;
+    return `  handoff : browser pending — ${lastReviewId ?? "review id unknown"}${
+      pendingHandoffReviewUrl ? ` @ ${pendingHandoffReviewUrl}` : ""
+    } (${pendingHandoffSource ?? "auto"}, ${age}s)`;
+  }
+
   function clearPendingHandoffDecision(): boolean {
     const changed =
       awaitingDecision === true ||
       lastHandoffAt !== undefined ||
       lastReviewId !== null ||
       pendingHandoffPlanPath !== null ||
-      pendingHandoffPlanHash !== null;
+      pendingHandoffPlanHash !== null ||
+      pendingHandoffRequestId !== null ||
+      pendingHandoffSource !== null ||
+      pendingHandoffCycleId !== 0 ||
+      pendingHandoffReviewUrl !== null;
     awaitingDecision = false;
     lastHandoffAt = undefined;
     lastReviewId = null;
     pendingHandoffPlanPath = null;
     pendingHandoffPlanHash = null;
+    pendingHandoffRequestId = null;
+    pendingHandoffSource = null;
+    pendingHandoffCycleId = 0;
+    pendingHandoffReviewUrl = null;
+    pendingHandoffPlanTextLen = 0;
+    recordedHandoffReviewId = null;
+    return changed;
+  }
+
+  /**
+   * Drop a gate that cannot belong to the round/plan about to start.
+   *
+   * A new automatic round, a manual `/review`, or a browser decision arriving
+   * while another round runs all supersede the old gate. A duplicate event for
+   * the same plan outside a new round must not clear a legitimate pending
+   * prompt, so the pure `pendingHandoffIsStale` predicate decides.
+   */
+  function supersedePendingHandoff(
+    reason: string,
+    opts: {
+      force?: boolean;
+      nextCycleId?: number;
+      nextPlanHash?: string;
+    } = {},
+  ): boolean {
+    if (
+      !pendingHandoffIsStale({
+        awaiting: awaitingDecision,
+        force: opts.force,
+        pendingCycleId:
+          pendingHandoffCycleId > 0 ? pendingHandoffCycleId : undefined,
+        currentCycleId: opts.nextCycleId ?? reviewCycleId,
+        pendingPlanHash: pendingHandoffPlanHash ?? undefined,
+        nextPlanHash: opts.nextPlanHash,
+      })
+    ) {
+      return false;
+    }
+    const changed = clearPendingHandoffDecision();
+    if (changed) {
+      notifyReview(`Plan handoff superseded — ${reason}.`, "info");
+      try {
+        pi.appendEntry("workflow-handoff-superseded", {
+          reason,
+          at: Date.now(),
+        });
+      } catch (_e) {
+        void _e;
+      }
+      try {
+        persistState();
+      } catch (_e) {
+        void _e;
+      }
+    }
     return changed;
   }
 
@@ -9769,6 +10769,7 @@ export default function workflowExtension(
           // The reviewer's `review_submit_plan` writes this path; a manual
           // `/review` must also audit the file the user just wrote.
           currentPlanFile = abs;
+          notePlanTargetForReviewCycle(abs);
           // A run that starts in Default/Build and switches into Plan mid-run
           // still qualifies: what matters is the mode at write time.
           if (workflowMode === "plan") planWrittenInPlanModeThisRun = true;
@@ -9779,6 +10780,7 @@ export default function workflowExtension(
           planWritePathThisRun = raw;
           planWrittenThisRun = true;
           currentPlanFile = raw;
+          notePlanTargetForReviewCycle(raw);
           if (workflowMode === "plan") planWrittenInPlanModeThisRun = true;
         }
         try {
@@ -9799,17 +10801,29 @@ export default function workflowExtension(
     // (Checked before the mutex: awaiting the in-flight handoff would block
     // for the whole review instead of short-circuiting.)
     if (reviewGatePhase !== "idle") {
-      try {
-        ctx.ui.notify(
-          reviewGatePhase === "paused"
-            ? "Review paused — /review-resume to continue, /review-abort to hand off the plan as-is."
-            : "Review running — ESC pauses it, /review-abort hands off the plan as-is.",
-          "info",
-        );
-      } catch (_e) {
-        void _e;
+      // A gate from a superseded cycle must not swallow this run's handoff.
+      // Settle it with the old pause text (the old runHandoff already holds the
+      // author's plan) and continue as if it were idle.
+      if (reviewGateCycleId !== reviewCycleId) {
+        settleReviewGate({
+          outcome: "unreviewed",
+          planText: currentPausedReview()?.planText,
+        });
+        reviewGatePhase = "idle";
+        reviewGateCycleId = 0;
+      } else {
+        try {
+          ctx.ui.notify(
+            reviewGatePhase === "paused"
+              ? "Review paused — /review-resume to continue, /review-abort to hand off the plan as-is."
+              : "Review running — ESC pauses it, /review-abort hands off the plan as-is.",
+            "info",
+          );
+        } catch (_e) {
+          void _e;
+        }
+        return;
       }
-      return;
     }
     // Mutex: serialize concurrent agent_end handoffs (bus may emit Promise.all)
     if (handoffInFlight) {
@@ -9831,6 +10845,10 @@ export default function workflowExtension(
       }
     }
     const runHandoff = async () => {
+      // Capture the cycle that owns this handoff. A fresh prompt/refine/deny
+      // increments `reviewCycleId`; every later continuation must stop instead
+      // of rendering or applying a superseded plan.
+      const handoffCycle = reviewCycleId;
       // Per-run handoff gate (plan 2026-10-25 follow-up): a Plan-mode run
       // that wrote no plan this run must not reconcile, review, or hand off
       // an older plan. This runs before the reviewer prefetch so a new task
@@ -9862,6 +10880,7 @@ export default function workflowExtension(
           : path.join(cwd, planWritePathThisRun);
         currentPlanFile = abs;
         lastPlanWritePath = abs;
+        notePlanTargetForReviewCycle(abs);
         // Persist once per run even when the tool_result handler already set
         // the in-memory target: resume must find the plan without a mode
         // switch or a todo update happening to persist it first.
@@ -10213,17 +11232,20 @@ export default function workflowExtension(
           void _e;
         }
       };
-      if (planTextForRender && reviewEnabled()) {
+      const reviewThisCycle = reviewEnabled() || manualReviewCycle;
+      if (planTextForRender && reviewThisCycle) {
         const authorPlan: string = planTextForRender;
         reviewHandoffGate.reset();
         reviewGatePhase = "auditing";
+        reviewGateCycleId = handoffCycle;
         try {
           const reviewed = await runReviewStep(
             authorPlan,
             ctx as ExtensionContext,
             (ctx as any).signal as AbortSignal | undefined,
-            "auto",
+            manualReviewCycle ? "manual" : "auto",
           );
+          if (handoffCycle !== reviewCycleId) return;
           const reviewedText = reviewed.planText;
           // Fresh read: the phase may have moved to "paused" (ESC /
           // /review-pause) while the round was returning. The `as` widens
@@ -10233,7 +11255,7 @@ export default function workflowExtension(
           if (
             reviewHandoffParks({
               phase: phaseAfterRound,
-              paused: pausedReview !== undefined,
+              paused: currentPausedReview() !== undefined,
               settled: reviewHandoffGate.settled(),
             })
           ) {
@@ -10246,6 +11268,7 @@ export default function workflowExtension(
             const res = await reviewHandoffGate.wait(
               (ctx as any).signal as AbortSignal | undefined,
             );
+            if (handoffCycle !== reviewCycleId) return;
             if (res === undefined) {
               // Host abort while parked: stop the reviewer, drop the pause,
               // do not auto-review this revision again, and hand the author's
@@ -10290,11 +11313,15 @@ export default function workflowExtension(
         } catch (_e) {
           void _e;
         } finally {
-          reviewGatePhase = "idle";
+          if (reviewGateCycleId === handoffCycle) {
+            reviewGatePhase = "idle";
+            reviewGateCycleId = 0;
+          }
         }
         // A mode switch mid-gate (e.g. Tab-to-Build) already left plan mode:
         // the gate settled as skipped, so there is nothing to hand off.
         if (workflowMode !== "plan") return;
+        if (handoffCycle !== reviewCycleId) return;
       }
       // Fallback when hasUI is false: still show handoff via followUp message (Claude Code parity for headless)
       if (!hasUI && planTextForRender && !awaitingDecision) {
@@ -10331,114 +11358,15 @@ export default function workflowExtension(
       if (planTextForRender && hasUI && !awaitingDecision) {
         // ── Plannotator webview branch (browser review) ──────────
         if (plannotatorActive) {
-          awaitingDecision = true;
-          lastHandoffAt = Date.now();
-          pendingHandoffPlanPath = planPath;
-          pendingHandoffPlanHash = planHash(planTextForRender);
-          persistState();
-          try {
-            const bus: any = (pi as any).events;
-            const requestId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-            const response: any = await new Promise((resolve) => {
-              let settled = false;
-              const timer = setTimeout(() => {
-                if (!settled) {
-                  settled = true;
-                  resolve({ status: "timeout" });
-                }
-              }, 5000);
-              try {
-                bus.emit(PLANNOTATOR_REQUEST, {
-                  requestId,
-                  action: "plan-review",
-                  payload: {
-                    planContent: planTextForRender!,
-                    planFilePath: planPath,
-                    // The handoff only renders after the gated review
-                    // resolves, so a pending review is impossible here;
-                    // the field stays for the external browser app.
-                    reviewPending: false,
-                    // Provenance so the browser/inline view can show that this
-                    // plan was independently reviewed (and by what).
-                    reviewSummary: reviewState
-                      ? {
-                          modelLabel: reviewState.modelLabel,
-                          round: reviewState.round,
-                          verdict: reviewState.verdict,
-                          findings: reviewState.findings.length,
-                        }
-                      : undefined,
-                  },
-                  respond: (res: any) => {
-                    if (!settled) {
-                      settled = true;
-                      clearTimeout(timer);
-                      resolve(res);
-                    }
-                  },
-                });
-              } catch (e) {
-                if (!settled) {
-                  settled = true;
-                  clearTimeout(timer);
-                  resolve({ status: "error", error: String(e) });
-                }
-              }
-            });
-            if (
-              response &&
-              response.status === "handled" &&
-              response.result &&
-              response.result.reviewId
-            ) {
-              lastReviewId = response.result.reviewId;
-              try {
-                pi.appendEntry("workflow-handoff-plannotator", {
-                  at: Date.now(),
-                  planPath,
-                  reviewId: lastReviewId,
-                  planTextLen: planTextForRender!.length,
-                  source: planSource,
-                });
-              } catch (_e) {
-                void _e;
-              }
-              try {
-                currentSessionCtx = ctx as any;
-                (ctx as any).ui?.notify?.(
-                  "Plan opened in browser for review. Approve or annotate there.",
-                  "info",
-                );
-                updateStatus(ctx as any);
-              } catch (_e) {
-                void _e;
-              }
-              return; // plannotator owns the review — result arrives via plannotator:review-result / plan-approved events
-            }
-            if (response && response.status !== "timeout") {
-              try {
-                (ctx as any).ui?.notify?.(
-                  `Plannotator unavailable (${response.status}), falling back to inline review`,
-                  "warning",
-                );
-              } catch (_e) {
-                void _e;
-              }
-            }
-          } catch (e) {
-            try {
-              (ctx as any).ui?.notify?.(
-                `Plannotator request failed, falling back to inline: ${String(e).slice(0, 80)}`,
-                "warning",
-              );
-            } catch (_e) {
-              void _e;
-            }
-          }
-          // Browser branch failed — clear gate so inline can show
-          clearPendingHandoffDecision();
-          persistState();
-          // fall through to inline handoff below
+          const handoff = await requestPlanReview({
+            planText: planTextForRender,
+            planPath,
+            source: "auto",
+            ctx: ctx as ExtensionContext,
+            cycleId: handoffCycle,
+          });
+          if (handoff.ok) return;
+          // The helper already cleared the gate; fall through to inline.
         }
         awaitingDecision = true;
         lastHandoffAt = Date.now();
@@ -10750,6 +11678,14 @@ export default function workflowExtension(
                   "",
                 );
                 if (refinement?.trim()) {
+                  try {
+                    await beginReviewCycle({
+                      reason: "refine",
+                      keepFindings: true,
+                    });
+                  } catch (_e) {
+                    void _e;
+                  }
                   const todoListText = formatTodoNumberedList(todoItems, {
                     glyph: true,
                   });