@dieulc/workflow 0.9.2 → 0.11.0

package/index.ts

@@ -14,7 +14,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { AssistantMessage, TextContent } from "@earendil-works/pi-ai";
 import type {
@@ -41,7 +41,6 @@ import {
   type EditorTheme,
   type SelectItem,
   wrapTextWithAnsi,
-  truncateToWidth,
 } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -121,6 +120,49 @@ import {
   type PendingCommitFlow,
   type StepCommitCandidate,
 } from "./commit-policy.ts";
+import {
+  baseFolderRoots,
+  decideFolderGate,
+  describeFolderEvaluation,
+  detectRepoRoot,
+  isBroadGrantRoot,
+  outsideProjectRootForTarget,
+  evaluateFolderTargets,
+  matchSensitivePath,
+  readFolderPolicyConfig,
+  writeFolderPolicyConfig,
+  folderPolicyArgumentCompletions,
+  folderPolicyConfigPaths,
+  DEFAULT_SENSITIVE_PATTERNS,
+  type FolderPolicyConfig,
+  type FolderTarget,
+} from "./folder-policy.ts";
+import { analyzeShellPaths } from "./shell-paths.ts";
+import {
+  buildReadDenyReason,
+  buildReadGuidanceMessage,
+  decideReadGate,
+  parseReadGateChoice,
+  readGateItemFromTarget,
+  readGateItemsKind,
+  readGateOptions,
+  readGateTargetKey,
+  readGateTargetsLabel,
+  readGateTitle,
+  readReadPolicyConfig,
+  sanitizeReadInstruction,
+  writeReadPolicyConfig,
+  readPolicyArgumentCompletions,
+  readPolicyConfigPaths,
+  revokeReadPolicyPath,
+  describeReadPolicy,
+  READ_INSTRUCTION_PROMPT_PLACEHOLDER,
+  READ_INSTRUCTION_PROMPT_TITLE,
+  type ReadGateItem,
+  type ReadPolicyConfig,
+} from "./read-policy.ts";
+import { classifyReadCall } from "./read-policy-tools.ts";
+import { redactToolResult } from "./read-policy-redact.ts";
 import {
   buildWriteDenyReason,
   buildWriteGuidanceMessage,
@@ -128,6 +170,7 @@ import {
   decideWriteGate,
   describeWritePolicyMode,
   isWriteCallAllowed,
+  normalizeWritePath,
   parseWriteGateChoice,
   readWritePolicyConfig,
   sanitizeWriteInstruction,
@@ -143,6 +186,7 @@ import {
   WRITE_INSTRUCTION_PROMPT_TITLE,
   type WriteGateChoice,
   type WriteGateItem,
+  type WriteGateSource,
   type WriteCallClassification,
   type WritePolicyConfig,
   type WritePolicyMode,
@@ -163,6 +207,8 @@ import {
   roleArgumentCompletions,
   saveRoleConfig,
   getRole,
+  userRolesPath,
+  projectRolesPath,
   formatRolesForDisplay,
   formatModelRef,
   parseModelRef,
@@ -185,6 +231,17 @@ import {
   setWorkflowStatus,
   WORKFLOW_STATUS_KEYS,
 } from "./workflow-status.ts";
+import {
+  buildTodoRows,
+  deriveTodoPanel,
+  isTodoListSettled,
+  readPersistedTodoPanel,
+  renderTodoSummary,
+  todoCompletionSignature,
+  todoListKey,
+  type TodoPanelOverride,
+  type TodoPanelState,
+} from "./todo-panel.ts";
 import {
   defaultProfileConfig,
   loadProfilesDetailed,
@@ -204,11 +261,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 {
@@ -232,6 +295,7 @@ import {
 } from "./model-default.ts";
 import {
   applySubmittedPlan,
+  buildReviewerFallbacks,
   classifyReviewExecution,
   createReviewHandoffGate,
   DEFAULT_REVIEW_MODE_CONFIG,
@@ -247,12 +311,16 @@ import {
   reviewModeLockKind,
   reviewModeLockNotice,
   reviewModeLockStatusLine,
+  reviewInputDecision,
+  reviewRoundOwnsTurn,
+  reviewTurnOwns,
   reviewNoticeText,
   reviewPauseIsCurrent,
   reviewResumeGateOutcome,
   reviewResumeNotice,
   reviewResumePlanChoice,
   reviewEscapeAction,
+  reviewElapsedMs,
   reviewHandoffParks,
   reviewResumeSettles,
   reviewStateSummary,
@@ -261,12 +329,14 @@ import {
   writeReviewModeConfig,
   writeReviewPrompt,
   type ReviewFinding,
+  type ReviewFallbackModel,
   type ReviewExecutionResult,
   type ReviewHandoffGate,
   type ReviewSdkLoader,
   type ReviewHandoffPhase,
   type ReviewHandoffResult,
   type ReviewModeLockKind,
+  type ReviewTurnPhase,
   type ReviewState,
   type ReviewTranscriptOp,
   type ReviewTrigger,
@@ -282,12 +352,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 ──────────────────────────────────────────────────────────
 
@@ -415,8 +508,17 @@ async function runSingleAgent(
         shell: false,
         stdio: ["ignore", "pipe", "pipe"],
         // Carry the role into the child so its workflow extension gates bash
-        // with the same policy the parent applies (see permissions.ts).
-        env: subagentEnv(process.env, agent.role),
+        // with the same policy the parent applies (see permissions.ts), and
+        // lock the folder roots so the child cannot expand via a sibling
+        // project's settings.
+        env: {
+          ...subagentEnv(process.env, agent.role),
+          PI_FOLDER_POLICY_LOCKED: "1",
+          PI_FOLDER_POLICY_ROOTS: JSON.stringify([
+            detectRepoRoot(cwd) ?? cwd,
+          ]),
+          PI_FOLDER_POLICY_SOURCE: "parent",
+        },
       },
     );
     // Track for cleanup on session_shutdown — prevents orphaned subagents
@@ -499,6 +601,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(
@@ -569,12 +675,33 @@ export default function workflowExtension(
     null;
   let writeGateTurnSteered = false;
   const writeGateRunDenials = new Map<string, { instruction: string }>();
+  // ── Read-policy gate state (turn-scoped grants, run-scoped denials) ──
+  let readGateBatchCalls: { name: string; args: unknown }[] = [];
+  let readGateBatchCallIds = new Set<string>();
+  const readGateTurnGrantedRoots = new Set<string>();
+  const readGateTurnUncertainAllowed = new Set<string>();
+  let readGateTurnAnswer: {
+    choice: "allow-once" | "always" | "deny";
+    instruction: string;
+  } | null = null;
+  let readGateTurnSteered = false;
+  const readGateRunDenials = new Map<string, { instruction: string }>();
   // ── Reminder throttle + staleness tracking (passive enforcement layer) ──
   let turnsSinceLastTodoWrite = 0;
   let turnsSinceLastReminder = 0;
   let mutatedSinceLastTodoWrite = false;
   let lastRefMisses: { refs: string[] } | undefined;
   let todoStale = false;
+  // ── Todo panel presentation (pinned widget above the editor) ──
+  // The widget can never scroll with the transcript, so it collapses to one
+  // line when the plan settles and hides at the next user prompt. Overrides
+  // are scoped to `todoPanelOverrideKey` (ref/text/group identity), so status
+  // churn keeps the user's choice while a new/renamed list expires it.
+  let todoPanelOverride: TodoPanelOverride = null;
+  let todoPanelOverrideKey: string | null = null;
+  let todoPanelPromptAfterSettle = false;
+  let lastCompletedSignature: string | null = null;
+  let todoPanelAppliedState: TodoPanelState | "unregistered" = "unregistered";
   let footerInjectedThisTurn = false;
   let lastStaleNoticeAt: number | undefined;
   // Path+content hash of the last plan-file reconciliation (skip no-op merges).
@@ -1151,83 +1278,81 @@ export default function workflowExtension(
     todoStale = false;
   }
 
-  /** Display ref for a todo row (stable canonical GLOBAL step). */
-  function todoLabel(it: TodoItem, index: number): string {
-    return todoRef(it) || String(it.step || index + 1);
-  }
-
   /**
-   * Rows for the todo widget: group headers + labelled items, anchored on the
-   * first incomplete item (including its group header), capped for the terminal.
+   * Reconcile the pinned todo widget with the derived presentation state.
+   * Called from `updateStatus` after the footer writes; only re-registers the
+   * component when the state changes (marking a step done repaints through
+   * the host, so the widget is not disposed/rebuilt on every refresh).
    */
-  function buildTodoRows(
-    theme: any,
-    width: number,
-    mode: WorkflowMode | null,
-  ): string[] {
-    if (todoItems.length === 0) return [];
-    const MAX_WIDGET_LINES = 15;
-    const contentWidth = Math.max(1, width - 2);
-    type Row = { group?: string; item?: TodoItem; index: number };
-    const rows: Row[] = [];
-    let lastGroup: string | undefined;
-    todoItems.forEach((item, index) => {
-      if (item.group && item.group !== lastGroup) {
-        rows.push({ group: item.group, index });
-        lastGroup = item.group;
-      }
-      rows.push({ item, index });
+  function refreshTodoPanel(ctx: ExtensionContext) {
+    const view = deriveTodoPanel({
+      items: todoItems,
+      override: todoPanelOverride,
+      overrideKey: todoPanelOverrideKey,
+      promptAfterSettle: todoPanelPromptAfterSettle,
+      stale: todoStale,
     });
-    const firstUndone = todoItems.findIndex(
-      (t) => !isDone(t) && itemStatus(t) !== "cancelled",
-    );
-    const anchorIndex = firstUndone < 0 ? 0 : firstUndone;
-    let startRow = rows.findIndex((r) => r.item && r.index === anchorIndex);
-    if (startRow < 0) startRow = 0;
-    if (startRow > 0 && rows[startRow - 1]?.group) startRow -= 1;
-    const visible = rows.slice(startRow, startRow + MAX_WIDGET_LINES);
-    const rendered = visible.map((row) => {
-      if (row.group) {
-        return truncateToWidth(
-          theme.fg("muted", `── ${row.group}`),
-          contentWidth,
-          "…",
-        );
-      }
-      const item = row.item as TodoItem;
-      const ref = todoLabel(item, row.index);
-      const status = itemStatus(item);
-      const isCurrent = row.index === anchorIndex && !isDone(item);
-      const prefix =
-        isCurrent || status === "in_progress"
-          ? theme.fg("accent", "▶ ")
-          : status === "completed"
-            ? theme.fg("success", "☑ ")
-            : status === "cancelled"
-              ? theme.fg("dim", "✖ ")
-              : theme.fg("dim", "☐ ");
-      const labelPart =
-        item.label !== undefined && String(item.label) !== ref
-          ? theme.fg("muted", ` (${item.label})`)
-          : "";
-      const body = `${ref}. ${item.text}${labelPart}`;
-      let styled: string;
-      if (isDone(item)) {
-        styled = theme.fg("muted", theme.strikethrough(body));
-      } else if (isCurrent && mode === "build") {
-        styled = theme.fg("accent", body);
-      } else if (mode === "plan" || mode === null) {
-        styled = theme.fg("muted", body);
-      } else {
-        styled = body;
+    // A choice made for a different list must not hide a new task.
+    if (todoPanelOverrideKey !== view.listKey) {
+      todoPanelOverride = null;
+      todoPanelOverrideKey = null;
+    }
+    if (!view.settled && todoPanelPromptAfterSettle) {
+      todoPanelPromptAfterSettle = false;
+    }
+    // Reopened list: a later completion may emit its own card again.
+    if (!view.settled && lastCompletedSignature !== null) {
+      lastCompletedSignature = null;
+    }
+    if (view.settled && todoStale) todoStale = false;
+    if (view.state === todoPanelAppliedState) return;
+    todoPanelAppliedState = view.state;
+    try {
+      if (view.state === "hidden") {
+        ctx.ui.setWidget("workflow-todos", undefined);
+        return;
       }
-      return truncateToWidth(`${prefix}${styled}`, contentWidth, "…");
-    });
-    const remaining = rows.length - (startRow + visible.length);
-    if (remaining > 0) {
-      rendered.push(theme.fg("muted", `… +${remaining} more`));
+      ctx.ui.setWidget("workflow-todos", (_tui, theme) => {
+        const render = (w: number) => {
+          // Re-derive so the component always shows live items and the live
+          // mode, even though it was registered for an earlier state.
+          const live = deriveTodoPanel({
+            items: todoItems,
+            override: todoPanelOverride,
+            overrideKey: todoPanelOverrideKey,
+            promptAfterSettle: todoPanelPromptAfterSettle,
+            stale: todoStale,
+          });
+          if (live.state === "hidden") return [];
+          return live.state === "collapsed"
+            ? [renderTodoSummary(theme, w, live)]
+            : buildTodoRows(theme, w, todoItems, workflowMode);
+        };
+        return { render, invalidate: () => {}, dispose: () => {} };
+      });
+    } catch (_e) {
+      void _e;
+    }
+  }
+
+  function setTodoPanelOverride(
+    ctx: ExtensionContext,
+    override: TodoPanelOverride,
+    note?: string,
+  ) {
+    if (!todoItems.length && override === "expanded") {
+      ctx.ui.notify("No todos.", "info");
+      return;
+    }
+    todoPanelOverride = override;
+    todoPanelOverrideKey = override === null ? null : todoListKey(todoItems);
+    updateStatus(ctx);
+    try {
+      persistState();
+    } catch (_e) {
+      void _e;
     }
-    return rendered;
+    if (note) ctx.ui.notify(note, "info");
   }
 
   function updateStatus(ctx: ExtensionContext) {
@@ -1242,6 +1367,7 @@ export default function workflowExtension(
       commitMode = readCommitPolicyConfig(
         (ctx as any).cwd ?? process.cwd(),
         getAgentDir(),
+        { trusted: (ctx as any).isProjectTrusted?.() === true },
       ).config.mode;
     } catch {
       commitMode = "never";
@@ -1255,27 +1381,41 @@ export default function workflowExtension(
       writeMode = readWritePolicyConfig(
         (ctx as any).cwd ?? process.cwd(),
         getAgentDir(),
+        { trusted: (ctx as any).isProjectTrusted?.() === true },
       ).config.mode;
     } catch {
       writeMode = "allow";
     }
+    let folderMode: string | null = null;
+    try {
+      folderMode = readFolderPolicyConfig(
+        (ctx as any).cwd ?? process.cwd(),
+        getAgentDir(),
+        { trusted: (ctx as any).isProjectTrusted?.() === true },
+      ).config.mode;
+    } catch {
+      folderMode = null;
+    }
     const segments = buildWorkflowStatusSegments({
       mode: workflowMode,
-      plannotatorActive,
+      reviewPhase: reviewTurn,
       done: todoItems.filter((t) => isDone(t)).length,
       total: todoItems.length,
-      stale: todoStale,
+      stale: todoStale && !isTodoListSettled(todoItems),
       profileLabel,
       roleLabel,
       commitMode,
       writeMode: workflowMode === null ? writeMode : null,
+      folderMode,
     });
     const modeTone =
-      workflowMode === "build"
+      reviewTurn !== "idle"
         ? "accent"
-        : workflowMode === "plan"
-          ? "warning"
-          : "muted";
+        : workflowMode === "build"
+          ? "accent"
+          : workflowMode === "plan"
+            ? "warning"
+            : "muted";
     setWorkflowStatus(
       ctx.ui,
       WORKFLOW_STATUS_KEYS.mode,
@@ -1292,15 +1432,10 @@ export default function workflowExtension(
       ctx.ui.theme.fg("dim", segments.policy),
     );
     if (todoItems.length > 0) {
-      ctx.ui.setWidget("workflow-todos", (_tui, theme) => {
-        return {
-          render: (w: number) => buildTodoRows(theme, w, workflowMode),
-          invalidate: () => {},
-          dispose: () => {},
-        };
-      });
+      refreshTodoPanel(ctx);
     } else {
       ctx.ui.setWidget("workflow-todos", undefined);
+      todoPanelAppliedState = "hidden";
     }
     // One status owner: every footer refresh (mode switch, model change, round
     // phase, pause) also re-evaluates the review widget. This is what clears a
@@ -1377,6 +1512,15 @@ export default function workflowExtension(
   let activeReview:
     | { planText: string; round: number; controller: AbortController }
     | undefined;
+  /**
+   * The exclusive Review turn (plan 2026-11-14). Unlike the old derived lock,
+   * this also covers the browser/inline handoff, where no child session runs.
+   * In-memory: a reload restores `handoff` from `awaitingDecision`, otherwise
+   * idle (a running round cannot survive the process).
+   */
+  let reviewTurn: ReviewTurnPhase = "idle";
+  /** The next plan turn is the feedback/refine continuation of a Deny. */
+  let reviewFeedbackTurn = false;
   /** Long-lived ESC listener covering a round and the paused window. */
   let detachReviewEscListener: (() => void) | undefined;
   /**
@@ -1428,9 +1572,47 @@ export default function workflowExtension(
       roundActive,
       paused,
       gatePhase,
+      handoff: reviewTurn === "handoff" || awaitingDecision,
+      transition: reviewTurn === "transition",
+    });
+  }
+
+  /** True while a reviewer round or a real pause owns the turn (not handoff). */
+  function reviewRoundInFlight(): boolean {
+    let roundActive = false;
+    try {
+      roundActive = reviewRuntime?.isRoundActive() === true;
+    } catch (_e) {
+      void _e;
+    }
+    return reviewRoundOwnsTurn({
+      roundInFlight: activeReview !== undefined,
+      roundActive,
+      paused: currentPausedReview() !== undefined,
+      gatePhase:
+        reviewGateCycleId === reviewCycleId ? reviewGatePhase : "idle",
     });
   }
 
+  /** One status refresh for every review-turn transition. */
+  function setReviewTurn(phase: ReviewTurnPhase): void {
+    if (reviewTurn === phase) return;
+    reviewTurn = phase;
+    try {
+      if (currentSessionCtx) updateStatus(currentSessionCtx);
+    } catch (_e) {
+      void _e;
+    }
+  }
+
+  function beginReviewTurn(): void {
+    setReviewTurn("running");
+  }
+
+  function endReviewTurn(): void {
+    setReviewTurn("idle");
+  }
+
   /** Refuse a mode transition while a review round or pause owns the turn. */
   function blockModeSwitchDuringReview(
     ctx?: ExtensionContext,
@@ -1517,6 +1699,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
@@ -1927,6 +2151,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
@@ -2043,6 +2268,7 @@ export default function workflowExtension(
     // A gated audit becomes a paused gate (the handoff keeps waiting). A
     // manual review (idle gate) leaves the phase alone.
     if (reviewGatePhase === "auditing") reviewGatePhase = "paused";
+    setReviewTurn("paused");
     refreshReviewPauseUi();
     return true;
   }
@@ -2180,6 +2406,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;
@@ -2251,6 +2480,10 @@ 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…");
+    setReviewTurn("running");
+    // 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);
@@ -2466,6 +2699,17 @@ export default function workflowExtension(
       }
     }
 
+    // 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);
@@ -2634,6 +2878,16 @@ export default function workflowExtension(
     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();
@@ -2736,7 +2990,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) {
@@ -2749,6 +3005,7 @@ export default function workflowExtension(
     }
     reviewRuntime = undefined;
     reviewState = undefined;
+    if (opts.keepHandoff !== true) manualReviewCycle = false;
     lastReviewedPlanHash = undefined;
     reviewRound = 0;
     reviewPreviousFindings = undefined;
@@ -2763,11 +3020,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) {
@@ -2778,6 +3036,7 @@ export default function workflowExtension(
     flushReviewEntries(true);
     resetReviewStream();
     detachReviewEscListenerNow();
+    endReviewTurn();
     try {
       currentSessionCtx?.ui.setStatus(WORKFLOW_STATUS_KEYS.review, undefined);
     } catch (_e) {
@@ -2903,6 +3162,15 @@ export default function workflowExtension(
 
       const scope = scopeFor("global");
       const enable = sub === "on";
+      // Disabling would tear down the review (and its pending handoff) behind
+      // the lock. Abort is the explicit exit while Review owns the turn.
+      if (!enable && reviewTurnOwns(reviewTurn)) {
+        ctx.ui.notify(
+          "Review is active — /review-abort first (or resume/approve in the review tab).",
+          "info",
+        );
+        return;
+      }
 
       const res = writeReviewModeConfig(scope, cwd, agentDir, {
         enabled: enable,
@@ -2954,7 +3222,9 @@ export default function workflowExtension(
           : "global";
 
       if (!sub || sub === "status") {
-        const resolved = readCommitPolicyConfig(cwd, agentDir);
+        const resolved = readCommitPolicyConfig(cwd, agentDir, {
+          trusted: (ctx as any).isProjectTrusted?.() === true,
+        });
         const paths = commitConfigPaths(cwd, agentDir);
         const where =
           resolved.sources.mode === "default"
@@ -3013,8 +3283,9 @@ export default function workflowExtension(
   });
 
   // ── /write-policy: view/set the write permission (workflow.writePolicy) ──
-  // Available in every mode: it only writes settings JSON; the gate itself
-  // lives in tool_call and applies in Default mode only.
+  // Available in every mode: it only writes settings JSON. The write *mode*
+  // applies in Default mode only; the shared folder floor applies in every
+  // mode, Build included.
   pi.registerCommand("write-policy", {
     description:
       "View or set the write permission (what the agent may modify in Default mode): /write-policy allow|ask|never [global|project]",
@@ -3032,7 +3303,9 @@ export default function workflowExtension(
           : "global";
 
       if (!sub || sub === "status") {
-        const resolved = readWritePolicyConfig(cwd, agentDir);
+        const resolved = readWritePolicyConfig(cwd, agentDir, {
+          trusted: (ctx as any).isProjectTrusted?.() === true,
+        });
         const paths = writePolicyConfigPaths(cwd, agentDir);
         const where =
           resolved.sources.mode === "default"
@@ -3041,7 +3314,8 @@ export default function workflowExtension(
         const lines = [
           `Write policy: ${resolved.config.mode} (${where})`,
           `  ${describeWritePolicyMode(resolved.config.mode)}`,
-          "  Applies to Default mode only — Plan mode is read-only already, /build is the execution escape hatch.",
+          "  The write mode applies to Default mode only; the shared folder floor applies in every mode.",
+          "  Plan mode is read-only already; /build is the execution escape hatch.",
         ];
         if (resolved.config.allowedPaths.length > 0) {
           lines.push(
@@ -3115,6 +3389,133 @@ export default function workflowExtension(
   // 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("folder-policy", {
+    description: "Shared folder scope for read/write/commit: repo|cwd|parent|any, outside ask|block, sensitive list",
+    handler: async (args, ctx) => {
+      const cwd = (ctx as any)?.cwd ?? process.cwd();
+      const agentDir = getAgentDir();
+      const trusted = (ctx as any).isProjectTrusted?.() === true;
+      const tokens = String(args || "").trim().split(/\s+/).filter(Boolean);
+      const sub = (tokens[0] || "status").toLowerCase();
+      const second = (tokens[1] || "").toLowerCase();
+      const scope: "global" | "project" = tokens.includes("project")
+        ? "project"
+        : "global";
+      const resolved = readFolderPolicyConfig(cwd, agentDir, { trusted });
+      if (sub === "status") {
+        const paths = folderPolicyConfigPaths(cwd, agentDir);
+        const lines = [
+          `Folder policy: ${resolved.config.mode} (${resolved.sources.mode === "default" ? "default" : resolved.sources.mode + " settings"})`,
+          `  outside: ${resolved.config.outside}; grantScope: ${resolved.config.grantScope}; templates: ${resolved.config.sensitiveTemplates}`,
+          `  base: ${detectRepoRoot(cwd) ?? cwd}`,
+          "  unverifiable writes: not prompted (use /write-policy ask for strictness)",
+          `  sensitive: ${DEFAULT_SENSITIVE_PATTERNS.length} default, ${resolved.config.sensitivePatterns.length} extra, ${resolved.config.sensitiveExemptions.length} exemption(s)`,
+          `Global: ${paths.global}`,
+          `Project: ${paths.project}${resolved.sources.projectIgnored ? " (ignored: project not trusted)" : ""}`,
+          "Usage: /folder-policy repo|cwd|parent|any [global|project] · outside ask|block · grant project|global · templates allow|block · sensitive",
+        ];
+        ctx.ui.notify(lines.join("\n"), "info");
+        return;
+      }
+      if (sub === "sensitive") {
+        ctx.ui.notify(
+          [
+            "Sensitive deny list (always blocked for read/write/commit):",
+            ...DEFAULT_SENSITIVE_PATTERNS.map((p) => `  ${p}`),
+            ...(resolved.config.sensitivePatterns.length
+              ? ["Extra:", ...resolved.config.sensitivePatterns.map((p) => `  ${p}`)]
+              : []),
+            ...(resolved.config.sensitiveExemptions.length
+              ? ["Exemptions (manual):", ...resolved.config.sensitiveExemptions.map((p) => `  ${p}`)]
+              : []),
+          ].join("\n"),
+          "info",
+        );
+        return;
+      }
+      let patch: Record<string, unknown> | undefined;
+      if (["repo", "cwd", "parent", "any"].includes(sub)) patch = { mode: sub };
+      else if (sub === "outside" && ["ask", "block"].includes(second)) patch = { outside: second };
+      else if (sub === "grant" && ["project", "global"].includes(second)) patch = { grantScope: second };
+      else if (sub === "templates" && ["allow", "block"].includes(second)) patch = { sensitiveTemplates: second };
+      if (!patch) {
+        ctx.ui.notify("Usage: /folder-policy repo|cwd|parent|any · outside ask|block · grant project|global · templates allow|block · sensitive", "info");
+        return;
+      }
+      const written = writeFolderPolicyConfig(scope, cwd, agentDir, patch as any);
+      ctx.ui.notify(
+        written.ok
+          ? `Folder policy updated (${scope}): ${written.path}`
+          : `Could not write folder policy: ${written.error ?? "unknown error"}`,
+        written.ok ? "info" : "error",
+      );
+      updateStatus(ctx as any);
+    },
+    getArgumentCompletions: (prefix: string) => folderPolicyArgumentCompletions(prefix),
+  });
+
+  pi.registerCommand("read-policy", {
+    description: "Read permission: grants, shell paths|strict, guarded tools and the shared folder scope",
+    handler: async (args, ctx) => {
+      const cwd = (ctx as any)?.cwd ?? process.cwd();
+      const agentDir = getAgentDir();
+      const trusted = (ctx as any).isProjectTrusted?.() === true;
+      const tokens = String(args || "").trim().split(/\s+/).filter(Boolean);
+      const sub = (tokens[0] || "status").toLowerCase();
+      const readResolved = readReadPolicyConfig(cwd, agentDir, { trusted });
+      const folderResolved = readFolderPolicyConfig(cwd, agentDir, { trusted });
+      const paths = readPolicyConfigPaths(cwd, agentDir);
+      if (sub === "status" || !sub) {
+        ctx.ui.notify(
+          [
+            describeReadPolicy(readResolved.config, folderResolved.config),
+            `  grants: ${readResolved.config.allowedPaths.join(", ") || "none"}`,
+            `  guarded tools: ${readResolved.config.guardedTools.join(", ") || "none"}`,
+            `Global: ${paths.global}`,
+            `Project: ${paths.project}${readResolved.sources.projectIgnored ? " (ignored: project not trusted)" : ""}`,
+            "Usage: /read-policy allow <path> [global|project] · revoke <path> · shell paths|strict · status",
+          ].join("\n"),
+          "info",
+        );
+        return;
+      }
+      const scope: "global" | "project" = tokens.includes("project")
+        ? "project"
+        : "global";
+      if (sub === "shell") {
+        const value = (tokens[1] || "").toLowerCase();
+        if (value !== "paths" && value !== "strict") {
+          ctx.ui.notify("Usage: /read-policy shell paths|strict [global|project]", "info");
+          return;
+        }
+        const written = writeReadPolicyConfig(scope, cwd, agentDir, { shell: value });
+        ctx.ui.notify(written.ok ? `Read shell → ${value} (${scope})` : `Could not save: ${written.error}`, written.ok ? "info" : "error");
+        updateStatus(ctx as any);
+        return;
+      }
+      if (sub === "allow" || sub === "revoke") {
+        const target = tokens.slice(1).find((t) => t !== "global" && t !== "project");
+        if (!target) {
+          ctx.ui.notify(`Usage: /read-policy ${sub} <path> [global|project]`, "info");
+          return;
+        }
+        const result =
+          sub === "allow"
+            ? writeReadPolicyConfig(scope, cwd, agentDir, { allowedPaths: [target] })
+            : revokeReadPolicyPath(scope, cwd, agentDir, target);
+        ctx.ui.notify(
+          result.ok
+            ? `Read grant ${sub === "allow" ? "added" : "removed"} (${scope}): ${target}`
+            : `Could not save read grant: ${result.error}`,
+          result.ok ? "info" : "error",
+        );
+        return;
+      }
+      ctx.ui.notify("Usage: /read-policy status|allow <path>|revoke <path>|shell paths|strict", "info");
+    },
+    getArgumentCompletions: (prefix: string) => readPolicyArgumentCompletions(prefix),
+  });
+
   pi.registerCommand("permissions", {
     description:
       "Explain why a shell command would be allowed or refused: /permissions explain <command>",
@@ -3123,7 +3524,55 @@ export default function workflowExtension(
       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");
+      const lines = describeCommandPolicy(command);
+      if (command.trim()) {
+        const cwd = (ctx as any)?.cwd ?? process.cwd();
+        const trusted = (ctx as any).isProjectTrusted?.() === true;
+        const folderConfig = readFolderPolicyConfig(cwd, getAgentDir(), {
+          trusted,
+        }).config;
+        const writeConfig = readWritePolicyConfig(cwd, getAgentDir(), {
+          trusted,
+        }).config;
+        const readConfig = readReadPolicyConfig(cwd, getAgentDir(), {
+          trusted,
+        }).config;
+        const analysis = analyzeShellPaths(command, cwd);
+        const classification = classifyWriteCall(
+          "bash",
+          { command },
+          writeConfig,
+        );
+        const writeTargets = writeFolderTargetsFor(
+          "bash",
+          { command },
+          classification,
+          cwd,
+        );
+        const evaluation = evaluateFolderTargets(
+          [...analysis.reads, ...writeTargets],
+          {
+            config: folderConfig,
+            grants: [...writeConfig.allowedPaths, ...readConfig.allowedPaths],
+            cwd,
+            action: "write",
+          },
+        );
+        lines.push(
+          "",
+          ...describeFolderEvaluation(
+            evaluation,
+            detectRepoRoot(cwd) ?? cwd,
+          ),
+        );
+        if (analysis.uncertain.length > 0) {
+          lines.push(`  shell analysis: ${analysis.uncertain.join("; ")}`);
+        }
+        lines.push(
+          "  unverifiable writes are not prompted under writePolicy allow/Build; use /write-policy ask for strictness",
+        );
+      }
+      ctx.ui.notify(lines.join("\n"), "info");
     },
     getArgumentCompletions: (prefix: string) =>
       permissionsArgumentCompletions(prefix),
@@ -3179,6 +3628,7 @@ export default function workflowExtension(
             [
               `Review paused at round ${paused.round} (plan hash ${paused.planHash})`,
               "  /review-resume to continue, /review-abort to stop.",
+              pendingHandoffStatusLine(),
               reviewModeLockStatusLine(lockKind),
             ]
               .filter(Boolean)
@@ -3199,6 +3649,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)
@@ -3211,6 +3662,10 @@ 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}` : "",
@@ -3224,6 +3679,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) =>
@@ -3387,6 +3843,9 @@ export default function workflowExtension(
       abortedReviewHash = undefined;
       pausedReview = undefined;
       reviewRound = 0;
+      // Manual /review is a Review turn from the first tick: the mode status,
+      // input gate and mode lock must be active before the child boots.
+      beginReviewTurn();
       const result = await runReviewStep(
         target.text,
         ctx as any,
@@ -3398,6 +3857,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");
     },
   });
@@ -3442,12 +3911,16 @@ 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).
       // A manual pause (idle gate) is unchanged; the runtime/activeReview
       // flags carry that lock.
       reviewGatePhase = reviewGatePhaseOnResume(reviewGatePhase);
+      setReviewTurn("running");
       // A stale quiet-abort marker must not silence this explicit resume.
       quietAbortHash = undefined;
       // If the plan file moved on while paused, review the new revision fresh
@@ -3485,7 +3958,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;
@@ -3510,7 +3991,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");
+      }
     },
   });
 
@@ -3525,6 +4010,46 @@ export default function workflowExtension(
       const active =
         activeReview !== undefined || rt?.isRoundActive() === true;
       const paused = currentPausedReview();
+      // A browser/inline decision can own the turn with no round and no pause.
+      if (!active && !paused && awaitingDecision) {
+        const planPath = pendingHandoffPlanPath ?? currentPlanFile ?? "";
+        const planText =
+          (planPath &&
+            (() => {
+              try {
+                return fs.existsSync(planPath)
+                  ? fs.readFileSync(planPath, "utf8")
+                  : undefined;
+              } catch {
+                return undefined;
+              }
+            })()) ??
+          "";
+        if (pendingHandoffReviewUrl) {
+          setReviewTurn("handoff");
+          ctx.ui.notify(
+            "Review skipped — approve or annotate in the review tab.",
+            "info",
+          );
+          return;
+        }
+        if (planText && planPath) {
+          const handed = await openManualHandoff(
+            { planText, outcome: "aborted", paused: false },
+            planPath,
+            ctx as any,
+          );
+          if (!handed) setReviewTurn("handoff");
+          return;
+        }
+        clearPendingHandoffDecision();
+        setReviewTurn("idle");
+        ctx.ui.notify(
+          `Review skipped — the plan file is ${planPath || "unavailable"}.`,
+          "info",
+        );
+        return;
+      }
       if (!active && !paused) {
         ctx.ui.notify("No review running or paused.", "info");
         return;
@@ -3536,6 +4061,10 @@ export default function workflowExtension(
       // abort lands; falls back to the author's draft when unknown).
       const abortedText =
         paused?.planText ?? activeReview?.planText;
+      const pausedPlanPath = currentPlanFile ?? "";
+      // A parked automatic handoff owns its own presentation: settle the gate
+      // and let `runHandoff` render, never present twice.
+      const gated = reviewGatePhase !== "idle" && !reviewHandoffGate.settled();
       pausedReview = undefined;
       // An aborted revision is not auto-reviewed again until the plan changes.
       if (targetHash) abortedReviewHash = targetHash;
@@ -3558,9 +4087,15 @@ export default function workflowExtension(
           "Review stopped — the author's plan stands unreviewed.",
           "info",
         );
-        // A gated handoff was waiting on this round: hand off the author's
-        // plan through the normal renderer so the plan is always delivered.
-        settleReviewGate({ outcome: "unreviewed", planText: abortedText });
+        if (gated) {
+          setReviewTurn("handoff");
+          settleReviewGate({ outcome: "unreviewed", planText: abortedText });
+          return;
+        }
+        // A manual /review command is awaiting this round; it will present the
+        // aborted plan through `openManualHandoff` (shouldHandoffManualResult
+        // now includes aborted). Keep Review visible until then.
+        setReviewTurn("handoff");
         return;
       }
       flushReviewEntries(true);
@@ -3569,8 +4104,20 @@ export default function workflowExtension(
         "Paused review discarded — the author's plan stands.",
         "info",
       );
-      settleReviewGate({ outcome: "unreviewed", planText: abortedText });
-      // No round will run its finally, so clear the live review line here.
+      if (gated) {
+        setReviewTurn("handoff");
+        settleReviewGate({ outcome: "unreviewed", planText: abortedText });
+        return;
+      }
+      if (abortedText && pausedPlanPath) {
+        await openManualHandoff(
+          { planText: abortedText, outcome: "aborted", paused: false },
+          pausedPlanPath,
+          ctx as any,
+        );
+        return;
+      }
+      setReviewTurn("idle");
       updateStatus(ctx as any);
     },
   });
@@ -3598,6 +4145,12 @@ export default function workflowExtension(
    */
   interface ModeSwitchOptions {
     quiet?: boolean;
+    /**
+     * Internal review-decision exit: the caller already validated the pending
+     * decision and owns the `transition` state, so the full review lock must
+     * not refuse it. Never set this from a user-facing mode switch.
+     */
+    fromReview?: boolean;
   }
 
   /** Pure helper for tests: resolve which RoleModel plan/build will switch to. */
@@ -4014,6 +4567,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
@@ -4023,6 +4586,12 @@ export default function workflowExtension(
       },
       defaultModel,
       lastModeSwitch,
+      todoPanel: {
+        override: todoPanelOverride,
+        overrideKey: todoPanelOverrideKey,
+        promptAfterSettle: todoPanelPromptAfterSettle,
+        completedSignature: lastCompletedSignature,
+      },
     } as any);
     lastPersistedPlanFile = currentPlanFile;
   }
@@ -4039,9 +4608,10 @@ export default function workflowExtension(
       return;
     }
     // A live review owns the turn: no mode transition until it lands, fails,
-    // pauses or is aborted. The post-review approve path enters Build through
-    // `enterBuildModeFromPlan`, which is no longer locked once the gate settles.
-    if (blockModeSwitchDuringReview(ctx)) return;
+    // pauses or is aborted. A validated browser/inline decision passes
+    // `fromReview` because it is the exit, not a competing mode switch.
+    if (opts?.fromReview !== true && blockModeSwitchDuringReview(ctx)) return;
+    if (opts?.fromReview === true && reviewRoundInFlight()) return;
     // Leaving Default mode: remember its model so it can be restored on return.
     if (workflowMode === null) captureDefaultModel(ctx);
     workflowMode = "plan";
@@ -4260,11 +4830,19 @@ export default function workflowExtension(
   async function enterBuildModeFromPlan(
     ctx: ExtensionContext,
     planPath: string,
-  ) {
-    // Defense in depth: the inline/browser approve paths only run after the
-    // gated review resolves, but a stale approve must never switch tools while
-    // a round or pause still owns the turn.
-    if (blockModeSwitchDuringReview(ctx)) return;
+    opts?: { fromReview?: boolean },
+  ): Promise<boolean> {
+    // Defense in depth: a stale approve must never switch tools while a real
+    // reviewer round/pause owns the turn. The handoff itself is consumed by
+    // the caller (fromReview), so only `reviewRoundInFlight()` can refuse it.
+    if (opts?.fromReview === true) {
+      if (reviewRoundInFlight()) {
+        ctx.ui.notify(reviewModeLockNotice("running"), "info");
+        return false;
+      }
+    } else if (blockModeSwitchDuringReview(ctx)) {
+      return false;
+    }
     workflowMode = "build";
     syncLegacyFlags();
     // The plan is being handed to Build; this Plan cycle cannot hand off again.
@@ -4303,6 +4881,7 @@ export default function workflowExtension(
         : `Build mode: ${loaded.count} todos synced from plan (progress kept).`,
       "info",
     );
+    return true;
   }
 
   // ── Plannotator bridge helpers ─────────────────────────────────
@@ -4310,83 +4889,377 @@ export default function workflowExtension(
     return currentSessionCtx;
   }
 
-  function handlePlannotatorApprove(
-    planFilePath: string,
-    planContent: string,
-    feedback: string | undefined,
-    cwd: string | undefined,
-  ) {
-    const ctx = getActiveCtx();
-    if (!ctx) return;
-    if (workflowMode !== "plan") 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;
-    // No prompt means no decision to consume. A fresh prompt/mode switch
-    // clears this, so an old browser tab cannot approve the previous plan.
+  /**
+   * 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;
-    // Resolve plan path (plannotator gives cwd + relative path)
-    let resolvedPlan = planFilePath;
-    try {
-      if (cwd && !path.isAbsolute(planFilePath)) {
-        resolvedPlan = path.join(cwd, planFilePath);
-      } else if (!path.isAbsolute(planFilePath)) {
-        resolvedPlan = path.join(
-          (ctx as any).cwd ?? cwd ?? process.cwd(),
-          planFilePath,
-        );
-      }
-    } catch (_e) {
-      void _e;
+    if (typeof event.reviewId === "string" && event.reviewId) {
+      lastReviewId = event.reviewId;
     }
-    // Correlate the event with the plan the current handoff prompt showed.
-    // A stale browser tab must not approve an older plan after a new task.
-    try {
-      if (
-        !pendingHandoffPlanPath ||
-        path.resolve(resolvedPlan) !== path.resolve(pendingHandoffPlanPath)
-      ) {
-        ctx.ui.notify(
-          "Ignoring a stale browser approval from a previous plan.",
-          "info",
-        );
-        return;
-      }
-    } catch (_e) {
-      void _e;
-      if (!pendingHandoffPlanPath || resolvedPlan !== pendingHandoffPlanPath)
-        return;
+    if (!lastReviewId) return;
+    if (typeof event.url === "string" && event.url) {
+      pendingHandoffReviewUrl = event.url;
     }
-    if (
-      planContent &&
-      pendingHandoffPlanHash &&
-      planHash(planContent) !== pendingHandoffPlanHash
-    ) {
-      ctx.ui.notify(
-        "Ignoring a stale browser approval — the plan content changed.",
+    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",
       );
-      return;
     }
-    // Ensure file exists (fallback write if agent only gave content)
     try {
-      if (!fs.existsSync(resolvedPlan) && planContent) {
-        fs.mkdirSync(path.dirname(resolvedPlan), { recursive: true });
-        fs.writeFileSync(resolvedPlan, planContent, "utf8");
+      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;
+    // Keep the Review mode visible while the browser/inline decision owns the
+    // turn. The reviewer has finished, but prompts and modes stay locked.
+    setReviewTurn("handoff");
+    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;
     }
-    clearPendingHandoffDecision();
-    void enterBuildModeFromPlan(ctx as any, resolvedPlan)
-      .then(() => updateStatus(ctx as any))
-      .catch(() => {
+    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 {
-          updateStatus(ctx as any);
+          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();
+        endReviewTurn();
+        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;
+        setReviewTurn("handoff");
+        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) {
+          await handlePlannotatorApprove(
+            pendingHandoffPlanPath ?? currentPlanFile ?? "",
+            currentFile ?? "",
+            decision.feedback,
+            ctx.cwd,
+          );
+        } else {
+          await handlePlannotatorDeny(
+            decision.feedback || "Plan needs revision.",
+          );
+        }
+        return;
+      }
+      const changed = clearPendingHandoffDecision();
+      if (changed) persistState();
+      endReviewTurn();
+      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;
+  }
+
+  /** One execute handoff: todo list + the Build-starting message. */
+  function sendExecuteMessages(
+    ctx: ExtensionContext,
+    planPath: string,
+    feedback?: string,
+  ): void {
     try {
       const remainingList = formatTodoNumberedList(todoItems);
       const todoListText = formatTodoNumberedList(todoItems, { glyph: true });
@@ -4415,26 +5288,157 @@ export default function workflowExtension(
         at: Date.now(),
         choice: "execute",
         source: "plannotator",
-        planPath: resolvedPlan,
+        planPath,
       });
     } catch (_e) {
       void _e;
     }
   }
 
+  async function handlePlannotatorApprove(
+    planFilePath: string,
+    planContent: string,
+    feedback: string | undefined,
+    cwd: string | undefined,
+  ): Promise<void> {
+    const ctx = getActiveCtx();
+    if (!ctx) 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 reviewer round/pause runs must not clear
+    // the pending decision or send execute. The handoff itself is deliberately
+    // NOT part of this predicate: it is the decision being consumed here.
+    if (reviewRoundInFlight()) {
+      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;
+    // Resolve plan path (plannotator gives cwd + relative path)
+    let resolvedPlan = planFilePath;
+    try {
+      if (cwd && !path.isAbsolute(planFilePath)) {
+        resolvedPlan = path.join(cwd, planFilePath);
+      } else if (!path.isAbsolute(planFilePath)) {
+        resolvedPlan = path.join(
+          (ctx as any).cwd ?? cwd ?? process.cwd(),
+          planFilePath,
+        );
+      }
+    } catch (_e) {
+      void _e;
+    }
+    // Correlate the event with the plan the current handoff prompt showed.
+    // A stale browser tab must not approve an older plan after a new task.
+    try {
+      if (
+        !pendingHandoffPlanPath ||
+        path.resolve(resolvedPlan) !== path.resolve(pendingHandoffPlanPath)
+      ) {
+        ctx.ui.notify(
+          "Ignoring a stale browser approval from a previous plan.",
+          "info",
+        );
+        return;
+      }
+    } catch (_e) {
+      void _e;
+      if (!pendingHandoffPlanPath || resolvedPlan !== pendingHandoffPlanPath)
+        return;
+    }
+    if (
+      planContent &&
+      pendingHandoffPlanHash &&
+      planHash(planContent) !== pendingHandoffPlanHash
+    ) {
+      ctx.ui.notify(
+        "Ignoring a stale browser approval — the plan content changed.",
+        "info",
+      );
+      return;
+    }
+    // Ensure file exists (fallback write if agent only gave content)
+    try {
+      if (!fs.existsSync(resolvedPlan) && planContent) {
+        fs.mkdirSync(path.dirname(resolvedPlan), { recursive: true });
+        fs.writeFileSync(resolvedPlan, planContent, "utf8");
+      }
+    } catch (_e) {
+      void _e;
+    }
+    // Atomic decision exit: stop the reviewer and apply Build BEFORE any
+    // follow-up message. `transition` keeps input/mode gates closed while the
+    // async mode switch runs, so a queued prompt cannot race it.
+    setReviewTurn("transition");
+    if (pendingHandoffSource === "manual") manualReviewCycle = false;
+    clearPendingHandoffDecision();
+    let enteredBuild = false;
+    try {
+      enteredBuild = await enterBuildModeFromPlan(
+        ctx as any,
+        resolvedPlan,
+        { fromReview: true },
+      );
+    } catch (e: any) {
+      ctx.ui.notify(
+        `Could not enter Build mode (${String(e?.message ?? e)}); the plan was not executed.`,
+        "warning",
+      );
+    }
+    if (!enteredBuild) {
+      setReviewTurn("handoff");
+      updateStatus(ctx as any);
+      return;
+    }
+    setReviewTurn("idle");
+    updateStatus(ctx as any);
+    sendExecuteMessages(ctx as any, resolvedPlan, feedback);
+  }
+
   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;
+    // A stale deny while a new reviewer round/pause runs must not inject
+    // feedback under the reviewer. The pending handoff (if any) is the decision
+    // being consumed, so only the round predicate can refuse it.
+    if (reviewRoundInFlight()) {
+      supersedePendingHandoff(
+        "a browser decision arrived while a new review round was running",
+        { force: true },
+      );
+      return;
+    }
     if (!awaitingDecision) return;
+    const manualSource = pendingHandoffSource === "manual";
+    setReviewTurn("transition");
+    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, fromReview: 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.
     await beginReviewCycle({ reason: "deny", keepFindings: true });
+    setReviewTurn("idle");
+    // The feedback turn is not a fresh user prompt: keeping the refine reason
+    // preserves manualReviewCycle, so a manual review with automatic Review
+    // Mode off still re-reviews the revision.
+    reviewFeedbackTurn = true;
     persistState();
     try {
       const todoListText = formatTodoNumberedList(todoItems, { glyph: true });
@@ -4468,6 +5472,91 @@ export default function workflowExtension(
     }
   }
 
+  /**
+   * The browser review closed without a decision. The user must still get a
+   * handoff: present a compact inline Approve/Revise choice with the author's
+   * plan. Reopening the browser here could loop on every close, so this path is
+   * deliberately inline-only. Never leaves Review stuck: cancel/idle clears it.
+   */
+  async function presentClosedHandoff(
+    ctx: ExtensionContext,
+    planPath: string,
+    planText: string,
+  ): Promise<void> {
+    clearPendingHandoffDecision();
+    setReviewTurn("handoff");
+    if (!planText || !planPath) {
+      endReviewTurn();
+      ctx.ui.notify(
+        `Plan review closed — the plan file is ${planPath || "unavailable"}.`,
+        "info",
+      );
+      return;
+    }
+    if ((ctx as any).hasUI !== true) {
+      try {
+        (pi as any).sendMessage?.(
+          {
+            customType: "workflow-handoff-fallback",
+            content: `**Plan ready**\n\nPlan review closed without a decision. The plan is at ${planPath}.\n\nType "Execute the plan" to build, or tell me what to refine.`,
+            display: true,
+          },
+          { triggerTurn: false },
+        );
+      } catch (_e) {
+        void _e;
+      }
+      endReviewTurn();
+      return;
+    }
+    const execute = "Execute the plan in Build Mode";
+    const refine = "Refine the plan in Plan Mode";
+    let choice: string | undefined;
+    try {
+      choice = await (ctx as any).ui.select(
+        "Plan review closed — choose next step",
+        [execute, refine],
+      );
+    } catch {
+      choice = undefined;
+    }
+    if (choice === execute) {
+      setReviewTurn("transition");
+      const ok = await enterBuildModeFromPlan(ctx as any, planPath, {
+        fromReview: true,
+      });
+      if (!ok) {
+        setReviewTurn("handoff");
+        return;
+      }
+      setReviewTurn("idle");
+      sendExecuteMessages(ctx, planPath);
+      return;
+    }
+    if (choice === refine) {
+      setReviewTurn("transition");
+      if (workflowMode !== "plan") {
+        try {
+          await setPlanMode(ctx as any, { quiet: true, fromReview: true });
+        } catch (_e) {
+          void _e;
+        }
+      }
+      await beginReviewCycle({ reason: "refine", keepFindings: true });
+      setReviewTurn("idle");
+      ctx.ui.notify(
+        "Plan review closed — staying in Plan mode. Tell me what to change.",
+        "info",
+      );
+      return;
+    }
+    endReviewTurn();
+    ctx.ui.notify(
+      `Plan review closed — the plan is at ${planPath}.`,
+      "info",
+    );
+  }
+
   function ensurePlannotatorListeners() {
     if (plannotatorListenersRegistered) return;
     try {
@@ -4475,16 +5564,17 @@ export default function workflowExtension(
       if (!bus || typeof bus.on !== "function") return;
       // plan-approved (external executionMode) — direct handoff
       bus.on(PLANNOTATOR_PLAN_APPROVED, (event: any) => {
-        try {
-          handlePlannotatorApprove(
-            event.planFilePath,
-            event.planContent,
-            event.feedback,
-            event.cwd,
+        void handlePlannotatorApprove(
+          event?.planFilePath,
+          event?.planContent,
+          event?.feedback,
+          event?.cwd,
+        ).catch((e: unknown) => {
+          notifyReview(
+            `Plan approval failed: ${e instanceof Error ? e.message : String(e)}`,
+            "error",
           );
-        } catch (_e) {
-          void _e;
-        }
+        });
       });
       // review-result (plan-review shared API) — approve/deny from browser
       bus.on(PLANNOTATOR_REVIEW_RESULT, (event: any) => {
@@ -4504,12 +5594,17 @@ export default function workflowExtension(
             } catch (_e) {
               void _e;
             }
-            handlePlannotatorApprove(
+            void handlePlannotatorApprove(
               planPath,
               content,
               event.feedback,
               (getActiveCtx() as any)?.cwd,
-            );
+            ).catch((e: unknown) => {
+              notifyReview(
+                `Plan approval failed: ${e instanceof Error ? e.message : String(e)}`,
+                "error",
+              );
+            });
           } else {
             void handlePlannotatorDeny(
               event.feedback || "Plan needs revision.",
@@ -4519,6 +5614,74 @@ export default function workflowExtension(
           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;
+          const planPath = pendingHandoffPlanPath ?? currentPlanFile ?? "";
+          let planText = "";
+          try {
+            if (planPath && fs.existsSync(planPath)) {
+              planText = fs.readFileSync(planPath, "utf8");
+            }
+          } catch (_e) {
+            void _e;
+          }
+          const ctx = getActiveCtx();
+          if (!ctx) {
+            supersedePendingHandoff(
+              "the browser review closed without a decision",
+              { force: true },
+            );
+            return;
+          }
+          void presentClosedHandoff(ctx as any, planPath, planText).catch(
+            (e: unknown) => {
+              notifyReview(
+                `Plan handoff after review close failed: ${e instanceof Error ? e.message : String(e)}`,
+                "warning",
+              );
+              endReviewTurn();
+            },
+          );
+        } catch (_e) {
+          void _e;
+        }
+      });
       plannotatorListenersRegistered = true;
       plannotatorActive = true;
       const ctx = getActiveCtx();
@@ -4708,6 +5871,34 @@ export default function workflowExtension(
     void _e;
   }
 
+  // Todo panel toggle: expanded ↔ collapsed, and hidden → expanded.
+  // Ctrl+Alt+T is the Linux default for opening a terminal, so this uses O.
+  try {
+    pi.registerShortcut(Key.ctrlAlt("o"), {
+      description: "Toggle the workflow todo panel",
+      handler: async (ctx: any) => {
+        if (overlayDepth > 0) return;
+        if (todoItems.length === 0) {
+          ctx.ui.notify("No todos.", "info");
+          return;
+        }
+        const view = deriveTodoPanel({
+          items: todoItems,
+          override: todoPanelOverride,
+          overrideKey: todoPanelOverrideKey,
+          promptAfterSettle: todoPanelPromptAfterSettle,
+          stale: todoStale,
+        });
+        setTodoPanelOverride(
+          ctx as any,
+          view.state === "expanded" ? "collapsed" : "expanded",
+        );
+      },
+    });
+  } catch (_e) {
+    void _e;
+  }
+
   // Tab cycles workflow modes (context-aware: not when an overlay is active).
   // WorkflowTabEditor gives Tab back to autocomplete while a suggestion list is
   // visible; this registration remains the no-list path. Single registration to
@@ -4971,7 +6162,10 @@ export default function workflowExtension(
           };
           todoItems.push(item);
           try {
-            if (currentSessionCtx) updateStatus(currentSessionCtx);
+            if (currentSessionCtx) {
+              updateStatus(currentSessionCtx);
+              persistState();
+            }
           } catch (_e) {
             void _e;
           }
@@ -5092,6 +6286,10 @@ export default function workflowExtension(
           const c = todoItems.length;
           todoItems = [];
           todoPlanPath = undefined;
+          todoPanelOverride = null;
+          todoPanelOverrideKey = null;
+          todoPanelPromptAfterSettle = false;
+          lastCompletedSignature = null;
           try {
             if (currentSessionCtx) {
               updateStatus(currentSessionCtx);
@@ -5123,19 +6321,119 @@ export default function workflowExtension(
   });
 
   pi.registerCommand("todos", {
-    description: "Show workflow todos",
-    handler: async (_args, ctx) => {
-      const list = todoItems.length
-        ? `Steps are numbered GLOBALLY 1..${todoItems.length}:
+    description:
+      "Show or control the todo panel: /todos [show|expand|collapse|hide|auto|clear]",
+    handler: async (args, ctx) => {
+      const tokens = String(args || "")
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+      const sub = (tokens[0] || "").toLowerCase();
+      const usage = [
+        "Usage: /todos [show|expand|collapse|hide|auto|clear]",
+        "  (no arg)  list every step with global refs",
+        "  expand    show the full pinned panel",
+        "  collapse  keep one summary line",
+        "  hide      remove the pinned panel (footer keeps progress)",
+        "  auto      follow the automatic collapse/hide sequence",
+        "  clear     delete the todo list (asks first when UI is available)",
+      ].join("\n");
+
+      if (!sub) {
+        const list = todoItems.length
+          ? `Steps are numbered GLOBALLY 1..${todoItems.length}:
 ` +
-          todoItems
-            .map((t) => {
-              const g = t.group ? `[${t.group}] ` : "";
-              return `${g}${formatTodoLine(t)}`;
-            })
-            .join("\n")
-        : "No todos.";
-      ctx.ui.notify(`Todos (${todoItems.length}):\n${list}`, "info");
+            todoItems
+              .map((t) => {
+                const g = t.group ? `[${t.group}] ` : "";
+                return `${g}${formatTodoLine(t)}`;
+              })
+              .join("\n")
+          : "No todos.";
+        ctx.ui.notify(`Todos (${todoItems.length}):\n${list}`, "info");
+        return;
+      }
+
+      if (sub === "show" || sub === "expand") {
+        setTodoPanelOverride(ctx, "expanded");
+        return;
+      }
+      if (sub === "collapse") {
+        setTodoPanelOverride(ctx, "collapsed");
+        return;
+      }
+      if (sub === "hide") {
+        setTodoPanelOverride(ctx, "hidden");
+        return;
+      }
+      if (sub === "auto") {
+        setTodoPanelOverride(ctx, null);
+        return;
+      }
+      if (sub === "clear") {
+        const count = todoItems.length;
+        if (count === 0) {
+          ctx.ui.notify("No todos.", "info");
+          return;
+        }
+        // Headless confirm() resolves false and would silently turn this into
+        // a no-op; the command is explicit, so only ask when there is UI.
+        const confirmed =
+          (ctx as any).hasUI === true
+            ? await ctx.ui.confirm(
+                "Clear todos?",
+                "This resets the list. In Build mode, edits are blocked until a list exists again.",
+              )
+            : true;
+        if (!confirmed) {
+          ctx.ui.notify("Clear cancelled.", "info");
+          return;
+        }
+        todoItems = [];
+        todoPlanPath = undefined;
+        todoPanelOverride = null;
+        todoPanelOverrideKey = null;
+        todoPanelPromptAfterSettle = false;
+        lastCompletedSignature = null;
+        updateStatus(ctx);
+        try {
+          persistState();
+        } catch (_e) {
+          void _e;
+        }
+        onTodoWrite();
+        ctx.ui.notify(
+          `Cleared ${count} todos. In Build mode, edits are blocked until a list exists again (approve a plan or add a step).`,
+          "info",
+        );
+        return;
+      }
+      if (sub === "help") {
+        ctx.ui.notify(usage, "info");
+        return;
+      }
+      ctx.ui.notify(`Unknown /todos action: ${sub}\n${usage}`, "info");
+    },
+    getArgumentCompletions: (prefix: string) => {
+      const raw = String(prefix ?? "");
+      if (/\s/.test(raw.trim())) return null;
+      const lower = raw.trim().toLowerCase();
+      const verbs = [
+        { name: "show", description: "Show the full pinned panel" },
+        { name: "expand", description: "Show the full pinned panel" },
+        { name: "collapse", description: "Keep one summary line" },
+        { name: "hide", description: "Remove the pinned panel" },
+        { name: "auto", description: "Automatic collapse/hide sequence" },
+        { name: "clear", description: "Delete the todo list" },
+        { name: "help", description: "Show usage" },
+      ];
+      const matching = verbs.filter((v) => v.name.startsWith(lower));
+      if (matching.length === 0) return null;
+      return matching.map((v) => ({
+        value: `${v.name} `,
+        label: v.name,
+        description: v.description,
+      }));
     },
   });
 
@@ -5416,7 +6714,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 {
@@ -6827,6 +8126,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(
@@ -8143,6 +9515,20 @@ export default function workflowExtension(
   // command reaches the reviewer now; the write-gate steer guard below stays
   // (a write instruction must never be steered into the reviewer).
   pi.on("input", async (event, _ctx) => {
+    // Review owns the turn: only the explicit controls and model/profile
+    // changes may become a prompt. This is the terminal-Pi half of the lock;
+    // the Desktop store refuses prose before it reaches this hook.
+    if (reviewTurnOwns(reviewTurn)) {
+      const decision = reviewInputDecision(
+        typeof event.text === "string" ? event.text : "",
+        reviewTurn,
+      );
+      if (decision.action === "block") {
+        notifyReview(decision.notice, "info");
+        return { action: "handled" } as any;
+      }
+      return { action: "continue" } as any;
+    }
     if (typeof event.text === "string" && event.text.startsWith("/btw ")) {
       const note = event.text.slice(5).trim();
       if (note) {
@@ -8238,12 +9624,27 @@ export default function workflowExtension(
     // A session boundary owns the session-scoped plan fallback; the restore
     // loop below re-seeds it from the persisted `planFile`.
     resetSessionPlanProvenance();
+    // The branch is the source of truth for the panel's presentation. The
+    // host has cleared every extension widget on a session switch/reload, so
+    // the reconciler must register it again from the restored state.
+    todoPanelOverride = null;
+    todoPanelOverrideKey = null;
+    todoPanelPromptAfterSettle = false;
+    lastCompletedSignature = null;
+    todoPanelAppliedState = "unregistered";
     // A reloaded/forked session must never inherit a stale write denial.
     writeGateRunDenials.clear();
     writeGateTurnAnswer = null;
     writeGateTurnSteered = false;
     writeGateBatchCalls = [];
     writeGateBatchCallIds = new Set();
+    readGateRunDenials.clear();
+    readGateTurnAnswer = null;
+    readGateTurnSteered = false;
+    readGateBatchCalls = [];
+    readGateBatchCallIds = new Set();
+    readGateTurnGrantedRoots.clear();
+    readGateTurnUncertainAllowed.clear();
     // Roles are file-backed; load them up-front so every read path (status,
     // band label, reviewer runtime) sees the real config even in a fresh
     // session that has no persisted workflow entry yet. Profiles likewise.
@@ -8283,6 +9684,15 @@ export default function workflowExtension(
             }
             syncLegacyFlags();
             if (Array.isArray(d.todos)) todoItems = ensureTodoLabels(d.todos);
+            // Entries written before this feature have no `todoPanel`; they
+            // must not erase a value restored from an earlier entry.
+            if (d.todoPanel && typeof d.todoPanel === "object") {
+              const panel = readPersistedTodoPanel(d);
+              todoPanelOverride = panel.override;
+              todoPanelOverrideKey = panel.overrideKey;
+              todoPanelPromptAfterSettle = panel.promptAfterSettle;
+              lastCompletedSignature = panel.completedSignature;
+            }
             todoPlanPath = d.planFile;
             toolsBeforePlanMode = d.toolsBeforePlanMode;
             // An entry without a planFile must not erase a value restored
@@ -8351,31 +9761,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 (
@@ -8601,9 +10019,13 @@ 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();
+    // A reload cannot preserve a running/paused reviewer child. Only a
+    // persisted pending decision survives, and it owns the turn as `handoff`.
+    reviewTurn = awaitingDecision ? "handoff" : "idle";
     currentSessionCtx = ctx as any;
     // Give Tab back to autocomplete while a suggestion list is visible; the raw
     // `tab` shortcut keeps cycling modes otherwise.
@@ -8636,16 +10058,27 @@ 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;
     writeGateTurnSteered = false;
     writeGateBatchCalls = [];
     writeGateBatchCallIds = new Set();
+    readGateRunDenials.clear();
+    readGateTurnAnswer = null;
+    readGateTurnSteered = false;
+    readGateBatchCalls = [];
+    readGateBatchCallIds = new Set();
+    readGateTurnGrantedRoots.clear();
+    readGateTurnUncertainAllowed.clear();
     // Kill any active explore subagents to prevent orphan leaks.
     // Without this, `pi --mode json` children spawned by runSingleAgent
     // (up to 4 concurrent) could survive if VS Code closes the terminal
@@ -8658,11 +10091,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) {
@@ -8674,13 +10113,15 @@ export default function workflowExtension(
     ctx.ui.setStatus(WORKFLOW_STATUS_KEYS.policy, undefined);
     ctx.ui.setStatus(WORKFLOW_STATUS_KEYS.review, undefined);
     ctx.ui.setWidget("workflow-todos", undefined);
+    // The host dropped the widget; a later session_start re-registers it.
+    todoPanelAppliedState = "unregistered";
     // Drop any /commit authorization or flow: a reload/quit must never leave
     // an exemption armed for whatever runs next.
     commitAuthorization = null;
     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;
   });
 
@@ -8689,6 +10130,12 @@ export default function workflowExtension(
     todoItems = [];
     todoPlanPath = undefined;
     btwNotes = [];
+    // A rewind is a branch boundary: the panel choice belongs to the branch.
+    todoPanelOverride = null;
+    todoPanelOverrideKey = null;
+    todoPanelPromptAfterSettle = false;
+    lastCompletedSignature = null;
+    todoPanelAppliedState = "unregistered";
     // A rewind is a branch boundary: no per-run write from the old branch
     // may authorize a handoff or a manual review on the new one.
     resetPlanRunProvenance();
@@ -8699,13 +10146,18 @@ export default function workflowExtension(
     try {
       const branch = ctx.sessionManager.getBranch();
       for (const e of branch as any[]) {
-        if (
-          e.type === "custom" &&
-          e.customType === "workflow" &&
-          Array.isArray(e.data?.todos)
-        ) {
-          todoItems = ensureTodoLabels(e.data.todos);
-          if (e.data.planFile) todoPlanPath = e.data.planFile;
+        if (e.type === "custom" && e.customType === "workflow") {
+          if (Array.isArray(e.data?.todos)) {
+            todoItems = ensureTodoLabels(e.data.todos);
+            if (e.data.planFile) todoPlanPath = e.data.planFile;
+          }
+          if (e.data?.todoPanel && typeof e.data.todoPanel === "object") {
+            const panel = readPersistedTodoPanel(e.data);
+            todoPanelOverride = panel.override;
+            todoPanelOverrideKey = panel.overrideKey;
+            todoPanelPromptAfterSettle = panel.promptAfterSettle;
+            lastCompletedSignature = panel.completedSignature;
+          }
         }
         if (
           e.type === "message" &&
@@ -8745,6 +10197,126 @@ export default function workflowExtension(
    * The decision itself is the pure `decideCommitGate`; this wrapper supplies
    * the runtime inputs and renders the block reasons / ask overlay.
    */
+  function runGitZ(
+    repoRoot: string,
+    args: string[],
+  ): { ok: boolean; paths: string[]; error?: string } {
+    // The Pi host's PATH is not the shell's PATH (Windows especially). Honour
+    // an explicit override so a desktop install without git on PATH can still
+    // run the commit gate's synchronous checks.
+    const gitBinary = process.env.PI_GIT_BIN?.trim() || "git";
+    try {
+      const res = spawnSync(gitBinary, ["-C", repoRoot, ...args], {
+        encoding: "utf8",
+        timeout: 5000,
+        windowsHide: true,
+        maxBuffer: 8 * 1024 * 1024,
+      });
+      if (res.error) {
+        const code = (res.error as NodeJS.ErrnoException).code;
+        const missing =
+          code === "ENOENT" || /\bENOENT\b/.test(res.error.message);
+        return {
+          ok: false,
+          paths: [],
+          error: missing
+            ? `git executable not found (${gitBinary}); set PI_GIT_BIN to the git binary`
+            : res.error.message,
+        };
+      }
+      if (res.status !== 0)
+        return {
+          ok: false,
+          paths: [],
+          error: String(res.stderr ?? "").trim() || `git exited ${res.status}`,
+        };
+      const paths = String(res.stdout ?? "")
+        .split("\0")
+        .map((entry) => entry.replace(/\r?\n$/, ""))
+        .map((entry) => entry.replace(/^..\s+/, ""))
+        .map((entry) => entry.split(" -> ").pop() ?? entry)
+        .filter(Boolean);
+      return { ok: true, paths };
+    } catch (error: unknown) {
+      return {
+        ok: false,
+        paths: [],
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  function resolveCommitRoot(
+    candidate: string,
+    cwd: string,
+  ): { root: string; uncertain: boolean } {
+    const res = runGitZ(candidate, ["rev-parse", "--show-toplevel"]);
+    if (res.ok && res.paths[0]) {
+      return {
+        root: normalizeWritePath(res.paths[0], candidate),
+        uncertain: false,
+      };
+    }
+    const detected = detectRepoRoot(candidate) ?? detectRepoRoot(cwd);
+    return detected
+      ? { root: detected, uncertain: false }
+      : { root: candidate, uncertain: true };
+  }
+
+  function commitSensitiveHit(
+    scope: NonNullable<ReturnType<typeof analyzeShellPaths>["git"]>,
+    folderConfig: FolderPolicyConfig,
+  ): { path: string; pattern: string } | { failed: string } | undefined {
+    const check = (paths: readonly string[]) => {
+      for (const p of paths) {
+        const hit = matchSensitivePath(p, folderConfig, scope.repoRoot);
+        if (hit.sensitive)
+          return { path: p, pattern: hit.pattern ?? "sensitive" };
+      }
+      return undefined;
+    };
+    const explicit = check(scope.explicitPaths);
+    if (explicit) return explicit;
+
+    if (scope.hit === "add" && scope.allPaths) {
+      const status = runGitZ(scope.repoRoot, [
+        "status",
+        "--porcelain=v1",
+        "-z",
+        "--untracked-files=all",
+      ]);
+      if (!status.ok)
+        return { failed: status.error ?? "git status failed" };
+      const hit = check(status.paths);
+      if (hit) return hit;
+    }
+    if (scope.hit === "commit") {
+      const staged = runGitZ(scope.repoRoot, [
+        "diff",
+        "--cached",
+        "--name-only",
+        "-z",
+      ]);
+      if (!staged.ok)
+        return { failed: staged.error ?? "git diff --cached failed" };
+      const hit = check(staged.paths);
+      if (hit) return hit;
+      if (scope.allPaths) {
+        const status = runGitZ(scope.repoRoot, [
+          "status",
+          "--porcelain=v1",
+          "-z",
+          "--untracked-files=all",
+        ]);
+        if (!status.ok)
+          return { failed: status.error ?? "git status failed" };
+        const modified = check(status.paths);
+        if (modified) return modified;
+      }
+    }
+    return undefined;
+  }
+
   async function commitPolicyGate(
     event: any,
     ctx: any,
@@ -8753,7 +10325,54 @@ export default function workflowExtension(
     const cmd = String(event?.input?.command ?? "");
     const hit = gitCommitPolicyHit(cmd);
     if (!hit) return undefined;
-    const policy = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+    const trusted = ctx?.isProjectTrusted?.() === true;
+    const policyConfig = readCommitPolicyConfig(cwd, getAgentDir(), {
+      trusted,
+    }).config;
+    const policy = policyConfig.mode;
+    const folderConfig = readFolderPolicyConfig(cwd, getAgentDir(), {
+      trusted,
+    }).config;
+    const git = analyzeShellPaths(cmd, cwd).git;
+    const gitDir = /\bGIT_DIR=([^\s;&|]+)/.exec(cmd)?.[1];
+    const candidateRoot = gitDir
+      ? normalizeWritePath(gitDir.replace(/^['"]|['"]$/g, ""), cwd)
+      : (git?.repoRoot ?? normalizeWritePath(cwd, cwd));
+    const resolvedRoot = resolveCommitRoot(candidateRoot, cwd);
+    const repoRoot = resolvedRoot.root;
+    const gitScope = git ? { ...git, repoRoot } : undefined;
+    const folderEvaluation = evaluateFolderTargets(
+      [{ path: repoRoot, kind: "dir" }],
+      {
+        config: folderConfig,
+        grants: policyConfig.allowedPaths,
+        cwd,
+        action: "commit",
+      },
+    );
+    if (resolvedRoot.uncertain)
+      folderEvaluation.uncertain.push(repoRoot);
+    const folderOutside = folderEvaluation.outside.length > 0;
+    const baseRoot = baseFolderRoots(folderConfig, cwd)[0] ?? cwd;
+    const folderDecision = decideFolderGate({
+      sensitive: false,
+      outside: folderEvaluation.outside.length > 0,
+      outsideAction: folderConfig.outside,
+      uncertain: folderEvaluation.uncertain.length > 0,
+    });
+    // decideFolderGate already turns uncertainty into ask (outside: ask) or
+    // block (outside: block); there is no "allow" case left to escalate.
+    const sensitiveHit = gitScope
+      ? commitSensitiveHit(gitScope, folderConfig)
+      : undefined;
+    if (sensitiveHit && "failed" in sensitiveHit) {
+      return {
+        block: true,
+        reason:
+          `Commit policy: the sensitive-file check could not run (${sensitiveHit.failed}). ` +
+          "Refusing to commit unverified. Do not retry; ask the user to commit manually or fix git access.",
+      };
+    }
     const now = Date.now();
     const decision = decideCommitGate({
       policy,
@@ -8761,6 +10380,8 @@ export default function workflowExtension(
       hasTodos: todoItems.length > 0,
       auth: commitAuthorization,
       now,
+      folder: folderDecision,
+      sensitive: Boolean(sensitiveHit && !("failed" in sensitiveHit)),
     });
     if (decision === "allow") {
       // Count a granted `git commit` against the authorization, but only when
@@ -8783,6 +10404,25 @@ export default function workflowExtension(
     }
 
     if (decision === "block") {
+      if (sensitiveHit && !("failed" in sensitiveHit)) {
+        return {
+          block: true,
+          reason:
+            `Commit policy: \`${sensitiveHit.path}\` is a sensitive file (${sensitiveHit.pattern}). ` +
+            "Committing it is blocked even when the commit mode is 'allow'. Do not retry; remove it from the index, or ask the user to add a manual sensitiveExemptions entry.",
+        };
+      }
+      if (folderDecision === "block" && policy !== "never") {
+        return {
+          block: true,
+          reason:
+            `Folder policy is 'block' (workflow.folderPolicy): \`git ${hit}\` targets ${repoRoot}, ` +
+            (folderOutside
+              ? `which is outside the permitted folders (${baseRoot}). `
+              : "which could not be verified against the permitted folders. ") +
+            "Do not retry. Ask the user to grant that repository folder or change /folder-policy.",
+        };
+      }
       return {
         block: true,
         reason:
@@ -8803,20 +10443,60 @@ export default function workflowExtension(
       return {
         block: true,
         reason:
-          `Commit policy is 'ask' (workflow.commitPolicy): \`git ${hit}\` needs user approval, ` +
+          `${folderOutside ? "Folder policy is 'ask' (workflow.folderPolicy)" : "Commit policy is 'ask' (workflow.commitPolicy)"}: \`git ${hit}\` needs user approval, ` +
           "but no interactive UI is available. Leave the change uncommitted and let the user decide.",
       };
     }
+    const commitGrant = folderOutside
+      ? (outsideProjectRootForTarget({ path: repoRoot, kind: "dir" }, baseRoot) ??
+        repoRoot)
+      : repoRoot;
     let sel: unknown;
     try {
       sel = await ui.select(
-        `Commit policy 'ask': allow \`git ${hit}\`?`,
-        ["Allow once", "Deny"],
+        `${folderOutside ? "Folder" : "Commit"} policy 'ask': allow \`git ${hit}\`?` +
+          `\nRepository: ${repoRoot}` +
+          (folderOutside ? `\nOutside: ${baseRoot}` : ""),
+        folderOutside
+          ? ["Allow once", "Always allow this repository folder", "Deny"]
+          : ["Allow once", "Deny"],
       );
     } catch {
       sel = undefined;
     }
-    if (String(sel ?? "").startsWith("Allow")) return undefined;
+    const answer = String(sel ?? "");
+    if (answer.startsWith("Always allow")) {
+      if (folderConfig.grantScope === "project" && !trusted) {
+        return {
+          block: true,
+          reason:
+            "Folder policy 'ask': this project is not trusted, so a project-scoped grant would be ignored. " +
+            "Choose Allow once, trust the project first, or set folderPolicy.grantScope to 'global'.",
+        };
+      }
+      const written = writeCommitPolicyConfig(
+        folderConfig.grantScope,
+        cwd,
+        getAgentDir(),
+        { allowedPaths: [commitGrant] },
+      );
+      if (!written.ok) {
+        return {
+          block: true,
+          reason: `Could not save the commit folder grant (${written.error ?? "unknown error"}); the commit was not allowed.`,
+        };
+      }
+      return undefined;
+    }
+    if (answer.startsWith("Allow")) return undefined;
+    if (folderOutside) {
+      return {
+        block: true,
+        reason:
+          `Folder policy 'ask': the user declined \`git ${hit}\` for ${repoRoot}, which is outside ${baseRoot}. ` +
+          "Do not retry — leave the changes uncommitted for the user.",
+      };
+    }
     return {
       block: true,
       reason:
@@ -8833,7 +10513,9 @@ export default function workflowExtension(
   function commitDirectiveLine(ctx: any): string {
     try {
       const cwd = ctx?.cwd ?? process.cwd();
-      const mode = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+      const mode = readCommitPolicyConfig(cwd, getAgentDir(), {
+        trusted: ctx?.isProjectTrusted?.() === true,
+      }).config.mode;
       switch (mode) {
         case "never":
           return (
@@ -8869,16 +10551,90 @@ export default function workflowExtension(
    * part of the list (its arguments may have been rewritten by another
    * extension's tool_call handler after the assistant message was sealed).
    */
+  function writeFolderTargetsFor(
+    toolName: string,
+    input: any,
+    classification: WriteCallClassification,
+    cwd: string,
+  ): FolderTarget[] {
+    if (classification.paths.length > 0) {
+      return classification.paths.map((p) => ({ path: p, kind: "file" as const }));
+    }
+    if (toolName === "bash" || toolName === "powershell") {
+      const command = String(input?.command ?? "");
+      return analyzeShellPaths(command, cwd).writes;
+    }
+    return [];
+  }
+
+  function withFolderGrant(
+    item: WriteGateItem,
+    targets: readonly FolderTarget[],
+    cwd: string,
+    baseRoot: string,
+  ): WriteGateItem {
+    const grantEntries = targets
+      .map((target) => {
+        const exact = normalizeWritePath(target.path, cwd);
+        const outsideRoot = outsideProjectRootForTarget(target, baseRoot);
+        const path = outsideRoot ?? exact;
+        // A dir/repo target (or a glob's static prefix) is granted as a
+        // folder; so is a containing folder computed for an outside file. A
+        // file directly in the common parent is granted as that file alone.
+        const folder =
+          target.kind !== "file" ||
+          (outsideRoot !== undefined && outsideRoot !== exact);
+        return { path, folder };
+      })
+      .filter((entry) => entry.path.length > 0);
+    if (grantEntries.length === 0) return item;
+    const unique = [...new Set(grantEntries.map((entry) => entry.path))].sort();
+    return {
+      ...item,
+      target: unique.join(", "),
+      grantPaths: [...new Set([...(item.grantPaths ?? []), ...unique])],
+      grantKind: grantEntries.every((entry) => entry.folder)
+        ? "folder"
+        : "file",
+      grantCommand: undefined,
+      key: `path:${unique.join("|")}`,
+    };
+  }
+
   function collectWriteGateItems(
     currentEvent: any,
     currentClassification: WriteCallClassification,
     config: WritePolicyConfig,
+    folderConfig: FolderPolicyConfig,
     cwd: string,
+    baseRoot: string,
   ): WriteGateItem[] {
     const items: WriteGateItem[] = [];
     const seen = new Set<string>();
-    const add = (name: string, classification: WriteCallClassification) => {
-      const item = writeGateItemFromClassification(name, classification, cwd);
+    const add = (
+      name: string,
+      classification: WriteCallClassification,
+      input: any,
+    ) => {
+      const targets = writeFolderTargetsFor(
+        name,
+        input,
+        classification,
+        cwd,
+      );
+      const evaluation = evaluateFolderTargets(targets, {
+        config: folderConfig,
+        grants: config.allowedPaths,
+        cwd,
+        action: "write",
+      });
+      const needsFolder = evaluation.outside.length > 0;
+      if (!needsFolder && isWriteCallAllowed(classification, config, cwd))
+        return;
+      const base = writeGateItemFromClassification(name, classification, cwd);
+      const item = needsFolder
+        ? withFolderGrant(base, targets, cwd, baseRoot)
+        : base;
       if (!item.key || seen.has(item.key)) return;
       seen.add(item.key);
       items.push(item);
@@ -8888,8 +10644,6 @@ export default function workflowExtension(
       if (!name) continue;
       const classification = classifyWriteCall(name, call.args, config);
       if (!classification.mutating) continue;
-      // A granted target is not gated — it never reaches a dialog.
-      if (isWriteCallAllowed(classification, config, cwd)) continue;
       // The plan directory stays writable in every mode.
       if (
         classification.paths.length > 0 &&
@@ -8897,9 +10651,9 @@ export default function workflowExtension(
       ) {
         continue;
       }
-      add(name, classification);
+      add(name, classification, call.args);
     }
-    add(String(currentEvent?.toolName ?? ""), currentClassification);
+    add(String(currentEvent?.toolName ?? ""), currentClassification, currentEvent?.input);
     return items;
   }
 
@@ -8944,13 +10698,16 @@ export default function workflowExtension(
   }
 
   /**
-   * Write permission gate (workflow.writePolicy) — Default mode only.
+   * Write permission gate (workflow.writePolicy + the shared folder floor).
    *
    * The Workflow extension's three modes are Plan → Build → Default. Plan
-   * mode is read-only and Build mode is unrestricted by design, but DEFAULT
-   * mode was ALSO unrestricted: `resolveSessionRole()` returns undefined
-   * there, so the tool_call gate has no branch to take and the agent edits
-   * files without asking. This gate is the missing permission knob.
+   * mode is read-only and Build mode is unrestricted *inside the permitted
+   * folders*, but DEFAULT mode was ALSO unrestricted: `resolveSessionRole()`
+   * returns undefined there, so the tool_call gate has no branch to take and
+   * the agent edits files without asking. This gate is the missing permission
+   * knob. The write MODE is Default-only; the folder floor applies in every
+   * mode (Build included) and asks only for proven outside targets, sensitive
+   * files, or an explicit target path that cannot be resolved.
    *
    * It is deliberately INDEPENDENT of the role gate and of the commit
    * policy: those govern *what* a role may do, this governs *whether the
@@ -8970,24 +10727,24 @@ export default function workflowExtension(
     cwd: string,
   ): Promise<{ block: true; reason: string } | undefined> {
     try {
-      // Scope: the top-level Default-mode session only.
-      //  - Plan mode has its own stricter rules (writes only to .pi/plans/).
-      //  - Build mode is the deliberate "go ahead" execution escape hatch.
-      //  - A spawned child carries PI_WORKFLOW_ROLE and is already read-only
-      //    through the role gate (and has no UI to answer a prompt).
-      if (workflowMode !== null) return undefined;
-      if (
-        resolveSessionRole({
-          envRole: process.env[WORKFLOW_ROLE_ENV],
-          workflowMode,
-        }) !== undefined
-      ) {
-        return undefined;
-      }
+      // Scope: the write MODE is a Default-mode knob; the shared FOLDER floor
+      // applies to every mode. Plan mode already restricts writes to
+      // .pi/plans/ (inside the folder root); Build mode is the deliberate
+      // execution path but must still respect the user's folder floor.
+      const gateRole = resolveSessionRole({
+        envRole: process.env[WORKFLOW_ROLE_ENV],
+        workflowMode,
+      });
+      if (gateRole && gateRole !== "builder") return undefined;
+      const defaultMode = workflowMode === null && gateRole === undefined;
 
-      const resolved = readWritePolicyConfig(cwd, getAgentDir());
+      const trusted = ctx?.isProjectTrusted?.() === true;
+      const resolved = readWritePolicyConfig(cwd, getAgentDir(), { trusted });
       const config = resolved.config;
-      if (config.mode === "allow") return undefined;
+      const effectiveWriteMode = defaultMode ? config.mode : "allow";
+      const folderConfig = readFolderPolicyConfig(cwd, getAgentDir(), {
+        trusted,
+      }).config;
 
       const classification = classifyWriteCall(
         event.toolName,
@@ -9005,23 +10762,94 @@ export default function workflowExtension(
         return undefined;
       }
 
+      const folderTargets = writeFolderTargetsFor(
+        String(event.toolName ?? ""),
+        event.input,
+        classification,
+        cwd,
+      );
+      for (const folderTarget of folderTargets) {
+        const hit = matchSensitivePath(folderTarget.path, folderConfig, cwd);
+        if (hit.sensitive) {
+          return {
+            block: true,
+            reason:
+              `Write policy: \`${folderTarget.path}\` is a sensitive file` +
+              (hit.pattern ? ` (${hit.pattern})` : "") +
+              ". This cannot be overridden by a write grant or folder. " +
+              "Do not retry; ask the user to edit the sensitive list in settings.json if this is intentional.",
+          };
+        }
+      }
+
+      const folderEvaluation = evaluateFolderTargets(folderTargets, {
+        config: folderConfig,
+        grants: config.allowedPaths,
+        cwd,
+        action: "write",
+      });
+      const folderDecision = decideFolderGate({
+        sensitive: false,
+        outside: folderEvaluation.outside.length > 0,
+        outsideAction: folderConfig.outside,
+        // Only a concrete target path that cannot be canonicalised is folder
+        // uncertainty. "Mutating but no discovered write target" is NOT: the
+        // shell analyzer cannot see inside `npm run build`, `node script`,
+        // `npx`, `sed`/`awk` programs or `powershell`, and treating that as
+        // "possibly outside" made Build and writePolicy:allow prompt for
+        // ordinary in-repo toolchain commands. The capability policy owns
+        // that case — writePolicy:ask still asks for every mutating call —
+        // and undiscoverable shell writes are the documented residual
+        // (README "Not a sandbox").
+        uncertain: folderEvaluation.uncertain.length > 0,
+      });
       const allowed = isWriteCallAllowed(classification, config, cwd);
       const decision = decideWriteGate({
-        mode: config.mode,
+        mode: effectiveWriteMode,
         mutating: true,
         allowed,
+        folder: folderDecision,
       });
       if (decision === "allow") return undefined;
 
+      // Which policy actually produced this ask. A folder-sourced prompt must
+      // not be labelled "Write policy" — that misattribution is what made the
+      // in-repo toolchain regression look like a write-policy bug.
+      const baseRoot = baseFolderRoots(folderConfig, cwd)[0] ?? cwd;
+      const folderAsk = folderDecision === "ask";
+      const gateSource: WriteGateSource = folderAsk
+        ? effectiveWriteMode === "ask"
+          ? "mixed"
+          : "folder"
+        : "write";
+      const gatePolicyLabel =
+        gateSource === "folder"
+          ? "Folder policy"
+          : gateSource === "mixed"
+            ? "Permission policy"
+            : "Write policy";
+      const gateOutside = gateSource === "folder" ? baseRoot : undefined;
+
       const target =
-        classification.paths.length > 0
-          ? classification.paths.join(", ")
-          : (classification.key ?? String(event.toolName));
+        folderTargets.length > 0
+          ? folderTargets.map((item) => item.path).join(", ")
+          : classification.paths.length > 0
+            ? classification.paths.join(", ")
+            : (classification.key ?? String(event.toolName));
       const why = classification.reason
         ? ` (${classification.reason})`
         : "";
 
       if (decision === "block") {
+        if (folderDecision === "block" && effectiveWriteMode !== "never") {
+          return {
+            block: true,
+            reason:
+              `Folder policy is 'block' (workflow.folderPolicy): the target is outside the permitted folders. ` +
+              "Do not retry. Ask the user to open the project at that folder, grant it, or change /folder-policy. " +
+              `Target: ${target}`,
+          };
+        }
         return {
           block: true,
           reason:
@@ -9047,11 +10875,18 @@ export default function workflowExtension(
       // the answer applies to all of them.
       const ui = ctx?.ui;
       if (!ui || !ctx.hasUI) {
+        const policyName =
+          gateSource === "folder"
+            ? "Folder policy is 'ask' (workflow.folderPolicy)"
+            : gateSource === "mixed"
+              ? "Folder and write policies are 'ask' (workflow.folderPolicy + workflow.writePolicy)"
+              : "Write policy is 'ask' (workflow.writePolicy)";
         return {
           block: true,
           reason:
-            `Write policy is 'ask' (workflow.writePolicy): writing needs user approval${why}, but no interactive UI is available. ` +
+            `${policyName}: writing needs user approval${why}, but no interactive UI is available. ` +
             "Do not retry. Report what you would change and let the user apply it, or tell them to switch to Build mode (/build). " +
+            (gateSource === "folder" ? `Outside: ${baseRoot}. ` : "") +
             `Target: ${target}`,
         };
       }
@@ -9068,12 +10903,23 @@ export default function workflowExtension(
         writeGateBatchCalls = [];
         writeGateBatchCallIds = new Set();
       }
-      const items = collectWriteGateItems(event, classification, config, cwd);
-      const currentItem = writeGateItemFromClassification(
+      const items = collectWriteGateItems(
+        event,
+        classification,
+        config,
+        folderConfig,
+        cwd,
+        baseRoot,
+      );
+      const currentBase = writeGateItemFromClassification(
         String(event.toolName ?? ""),
         classification,
         cwd,
       );
+      const currentItem =
+        folderEvaluation.outside.length > 0
+          ? withFolderGrant(currentBase, folderTargets, cwd, baseRoot)
+          : currentBase;
 
       // (a) The user denied this target earlier in THIS RUN → deny again,
       // silently. The model gets the same sentence; the user is not asked a
@@ -9087,6 +10933,8 @@ export default function workflowExtension(
             target,
             why: classification.reason,
             instruction: remembered.instruction,
+            source: gateSource,
+            outside: gateOutside,
           }),
         };
       }
@@ -9104,6 +10952,8 @@ export default function workflowExtension(
             target,
             why: classification.reason,
             instruction: answer.instruction,
+            source: gateSource,
+            outside: gateOutside,
           }),
         };
       }
@@ -9112,7 +10962,7 @@ export default function workflowExtension(
       const options = writeGateOptions(writeGateItemsKind(items));
       let sel: unknown;
       try {
-        sel = await ui.select(writeGateTitle(items), options);
+        sel = await ui.select(writeGateTitle(items, gateSource, baseRoot), options);
       } catch (_e) {
         void _e;
         sel = undefined;
@@ -9134,14 +10984,23 @@ export default function workflowExtension(
           for (const p of item.grantPaths ?? []) allowedPaths.push(p);
           if (item.grantCommand) allowedCommands.push(item.grantCommand);
         }
-        const written = writeWritePolicyConfig("global", cwd, getAgentDir(), {
+        const grantScope = folderConfig.grantScope;
+        if (grantScope === "project" && !trusted) {
+          return {
+            block: true,
+            reason:
+              `${gatePolicyLabel} 'ask': this project is not trusted, so a project-scoped grant would be ignored. ` +
+              "Choose Allow once, trust the project first, or set folderPolicy.grantScope to 'global'.",
+          };
+        }
+        const written = writeWritePolicyConfig(grantScope, cwd, getAgentDir(), {
           allowedPaths,
           allowedCommands,
         });
         if (written.ok) {
           try {
             (ctx as any).ui?.notify?.(
-              `Write policy: always allowed ${writeGateTargetsLabel(items)}`,
+              `${gatePolicyLabel}: always allowed ${writeGateTargetsLabel(items)}`,
               "info",
             );
           } catch (_e) {
@@ -9155,99 +11014,444 @@ export default function workflowExtension(
         return {
           block: true,
           reason:
-            `Write policy 'ask': could not save the permission grant (${written.error ?? "unknown error"}), so the write was not allowed. ` +
+            `${gatePolicyLabel} 'ask': could not save the permission grant (${written.error ?? "unknown error"}), so the write was not allowed. ` +
             `Target: ${target}`,
         };
       }
 
-      // ── Denial ──
-      // "Deny with instructions…" lets the user say WHY in one sentence
-      // ("only explore and propose a plan, do not edit files yet"), so the
-      // model can change course instead of stopping cold. The sentence
-      // travels through TWO channels:
-      //   1. the block reason (the tool result the model reads right now), and
-      //   2. a USER message (a steer turn the model must obey).
-      // Anthropic shipped the comment-only version and then shipped the bug
-      // where the model ignored it (anthropics/claude-code#89231, #52824):
-      // a tool result is a fact the model may reinterpret, a user turn is an
-      // instruction it must follow.
+      // ── Denial ──
+      // "Deny with instructions…" lets the user say WHY in one sentence
+      // ("only explore and propose a plan, do not edit files yet"), so the
+      // model can change course instead of stopping cold. The sentence
+      // travels through TWO channels:
+      //   1. the block reason (the tool result the model reads right now), and
+      //   2. a USER message (a steer turn the model must obey).
+      // Anthropic shipped the comment-only version and then shipped the bug
+      // where the model ignored it (anthropics/claude-code#89231, #52824):
+      // a tool result is a fact the model may reinterpret, a user turn is an
+      // instruction it must follow.
+      let instruction = "";
+      if (choice === "deny-with-instructions") {
+        const inputFn = (ui as any).input;
+        if (typeof inputFn === "function") {
+          let typed: unknown;
+          try {
+            typed = await inputFn.call(
+              ui,
+              WRITE_INSTRUCTION_PROMPT_TITLE,
+              WRITE_INSTRUCTION_PROMPT_PLACEHOLDER,
+            );
+          } catch (_e) {
+            void _e;
+            typed = undefined;
+          }
+          instruction = sanitizeWriteInstruction(typed);
+        }
+        // No input dialog, a cancelled dialog, or empty text → plain denial
+        // below. A cancel is never an implicit allow.
+      }
+
+      // The answer covers every gated write of this turn.
+      writeGateTurnAnswer = { choice, instruction };
+      // …and the denial is remembered for the REST OF THE RUN, under every
+      // target of this turn: a later retry is auto-denied with the same
+      // sentence instead of asking the user again.
+      for (const item of items) {
+        writeGateRunDenials.set(item.key, { instruction });
+      }
+
+      const reason = buildWriteDenyReason({
+        target: items.length > 1 ? writeGateTargetsLabel(items) : target,
+        why: classification.reason,
+        instruction,
+        source: gateSource,
+        outside: gateOutside,
+      });
+
+      if (instruction) {
+        // Channel 2: a user-role message. `steer` queues it while the agent
+        // is running; it lands after the current tool batch, before the next
+        // model call, as a genuine user turn. ONE per turn, not one per
+        // blocked call.
+        deliverWriteInstruction(items, instruction);
+        // Audit trail — transcript only (appendEntry is never sent to the
+        // LLM). One entry per turn: it records the user's decision, not each
+        // call the decision was applied to.
+        try {
+          pi.appendEntry("workflow-write-denial", {
+            tool: String(event.toolName ?? ""),
+            target,
+            instruction,
+            at: Date.now(),
+            targets: items.map((item) => item.target),
+          });
+        } catch (_e) {
+          void _e;
+        }
+      }
+
+      return {
+        block: true,
+        reason,
+        // NOTE: no `terminate` here. pi consults `terminate` only AFTER the
+        // whole tool batch has run (`executeToolCallsParallel` prepares and
+        // runs every call before `shouldTerminateToolBatch()`), so it cannot
+        // suppress a sibling write in the same batch — it only decides
+        // whether the agent gets ANOTHER LLM turn. With it set, a plain Deny
+        // would end the run with no model acknowledgement at all: a
+        // behaviour change nobody asked for. The guided path gets its next
+        // turn from the queued steer message instead.
+      };
+    } catch (e: unknown) {
+      // Fail closed: a broken policy read must not become an open door.
+      return {
+        block: true,
+        reason:
+          `Write policy (workflow.writePolicy) could not be evaluated (${e instanceof Error ? e.message : String(e)}), so the write was blocked. ` +
+          "Do not retry. Ask the user to switch to Build mode (/build) or to fix the policy with /write-policy.",
+      };
+    }
+  }
+
+  function collectReadGateItems(
+    currentEvent: any,
+    currentClassification: ReturnType<typeof classifyReadCall>,
+    config: ReadPolicyConfig,
+    folderConfig: FolderPolicyConfig,
+    cwd: string,
+    lockedRoots?: readonly string[],
+    baseRoot?: string,
+  ): ReadGateItem[] {
+    const items: ReadGateItem[] = [];
+    const seen = new Set<string>();
+    const add = (
+      name: string,
+      classification: ReturnType<typeof classifyReadCall>,
+    ) => {
+      if (classification.exempt) return;
+      const targets = classification.targets;
+      const evaluation = evaluateFolderTargets(targets, {
+        config: folderConfig,
+        grants: [...config.allowedPaths, ...readGateTurnGrantedRoots],
+        cwd,
+        lockedRoots,
+        action: "read",
+      });
+      for (const target of evaluation.outside) {
+        const item = readGateItemFromTarget(
+          name,
+          target,
+          "outside the folder",
+          baseRoot,
+        );
+        if (seen.has(item.key)) continue;
+        seen.add(item.key);
+        items.push(item);
+      }
+      if (evaluation.outside.length === 0) {
+        for (const reason of classification.uncertain) {
+          const key = `cmd:${reason}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          items.push({
+            tool: name,
+            target: { path: reason, kind: "file" },
+            grantRoot: "",
+            why: reason,
+            key,
+          });
+        }
+      }
+    };
+    for (const call of readGateBatchCalls) {
+      const name = String(call.name ?? "");
+      if (!name) continue;
+      add(name, classifyReadCall(name, call.args, cwd, config));
+    }
+    add(
+      String(currentEvent?.toolName ?? ""),
+      currentClassification,
+    );
+    return items;
+  }
+
+  function deliverReadInstruction(instruction: string, target: string): void {
+    if (!instruction || readGateTurnSteered) return;
+    const rt = reviewRuntime;
+    const wouldRouteToReviewer = shouldRouteInputToReviewer({
+      reviewEnabled: reviewEnabled(),
+      reviewActive: rt?.isRoundActive() === true,
+      hasReviewerSession: rt?.isAlive() === true,
+      manualSessionActive: reviewSessionLive(),
+    });
+    if (!wouldRouteToReviewer) {
+      try {
+        (pi as any).sendUserMessage?.(
+          buildReadGuidanceMessage({ target, instruction }),
+          { deliverAs: "steer" },
+        );
+      } catch (_e) {
+        void _e;
+      }
+    }
+    readGateTurnSteered = true;
+  }
+
+  /**
+   * Read permission gate. Applies in every workflow mode and to every role,
+   * including Build/explorer/reviewer-adjacent calls. The shared folder floor
+   * decides scope; the sensitive list always wins; the dialog is batched once
+   * per assistant turn.
+   */
+  async function readPolicyGate(
+    event: any,
+    ctx: any,
+    cwd: string,
+  ): Promise<{ block: true; reason: string } | undefined> {
+    try {
+      const trusted = ctx?.isProjectTrusted?.() === true;
+      const readResolved = readReadPolicyConfig(cwd, getAgentDir(), {
+        trusted,
+      });
+      const folderResolved = readFolderPolicyConfig(cwd, getAgentDir(), {
+        trusted,
+      });
+      const config = readResolved.config;
+      const folderConfig = folderResolved.config;
+      const classification = classifyReadCall(
+        String(event.toolName ?? ""),
+        event.input,
+        cwd,
+        config,
+      );
+      if (classification.exempt) return undefined;
+      if (
+        classification.targets.length === 0 &&
+        classification.uncertain.length === 0
+      )
+        return undefined;
+
+      const grants = [...config.allowedPaths, ...readGateTurnGrantedRoots];
+      const evaluation = evaluateFolderTargets(classification.targets, {
+        config: folderConfig,
+        grants,
+        cwd,
+        lockedRoots: folderResolved.locked?.roots,
+        action: "read",
+      });
+      if (evaluation.sensitive.length > 0) {
+        const hit = evaluation.sensitive[0];
+        return {
+          block: true,
+          reason: buildReadDenyReason({
+            kind: "sensitive",
+            target: hit.path,
+            pattern: hit.pattern,
+          }),
+        };
+      }
+
+      const outside = evaluation.outside;
+      const uncertain = classification.uncertain;
+      let decision = decideReadGate({
+        sensitive: false,
+        outside: outside.length > 0,
+        outsideAction: folderConfig.outside,
+        granted: false,
+        uncertain:
+          uncertain.length > 0 || evaluation.uncertain.length > 0,
+        shell: config.shell,
+      });
+
+      if (uncertain.length > 0 && config.shell === "strict") {
+        const allowed = uncertain.every((reason) =>
+          readGateTurnUncertainAllowed.has(reason),
+        );
+        if (allowed) decision = "allow";
+      }
+      if (decision === "allow") return undefined;
+      if (decision === "block") {
+        return {
+          block: true,
+          reason: buildReadDenyReason({
+            kind: "blocked",
+            target:
+              outside.length > 0
+                ? outside.map((target) => target.path).join(", ")
+                : uncertain[0] ?? String(event.toolName),
+            outsideAction: folderConfig.outside,
+          }),
+        };
+      }
+
+      const ui = ctx?.ui;
+      if (!ui || !ctx.hasUI) {
+        return {
+          block: true,
+          reason:
+            "Read policy is 'ask' (workflow.folderPolicy): this read needs approval, but no interactive UI is available. " +
+            "Do not retry; report what you need and let the user approve it.",
+        };
+      }
+
+      const callId = String(event.toolCallId ?? "");
+      if (!readGateBatchCallIds.has(callId)) {
+        readGateTurnAnswer = null;
+        readGateTurnSteered = false;
+        readGateBatchCalls = [];
+        readGateBatchCallIds = new Set();
+        readGateTurnGrantedRoots.clear();
+        readGateTurnUncertainAllowed.clear();
+      }
+      const baseRoot = baseFolderRoots(folderConfig, cwd)[0] ?? cwd;
+      const items = collectReadGateItems(
+        event,
+        classification,
+        config,
+        folderConfig,
+        cwd,
+        folderResolved.locked?.roots,
+        baseRoot,
+      );
+      const currentItems = items.filter((item) => {
+        if (outside.length > 0)
+          return outside.some((target) => item.key === readGateTargetKey(target));
+        return uncertain.some((reason) => item.key === `cmd:${reason}`);
+      });
+      const currentItem = currentItems[0];
+      const remembered = currentItem
+        ? readGateRunDenials.get(currentItem.key)
+        : undefined;
+      if (remembered) {
+        return {
+          block: true,
+          reason: buildReadDenyReason({
+            kind: "outside",
+            target: readGateTargetsLabel(currentItems) || "the requested read",
+            instruction: remembered.instruction,
+          }),
+        };
+      }
+      if (readGateTurnAnswer) {
+        if (readGateTurnAnswer.choice === "deny") {
+          return {
+            block: true,
+            reason: buildReadDenyReason({
+              kind: "outside",
+              target: readGateTargetsLabel(currentItems) || "the requested read",
+              instruction: readGateTurnAnswer.instruction,
+            }),
+          };
+        }
+        return undefined;
+      }
+
+      const options = readGateOptions(readGateItemsKind(items));
+      let sel: unknown;
+      try {
+        sel = await ui.select(readGateTitle(items, baseRoot), options);
+      } catch {
+        sel = undefined;
+      }
+      const choice = parseReadGateChoice(sel);
+      if (choice === "allow-once") {
+        for (const item of items) if (item.grantRoot) readGateTurnGrantedRoots.add(item.grantRoot);
+        for (const reason of uncertain) readGateTurnUncertainAllowed.add(reason);
+        readGateTurnAnswer = { choice: "allow-once", instruction: "" };
+        return undefined;
+      }
+      if (choice === "always") {
+        const roots = [
+          ...new Set(items.map((item) => item.grantRoot).filter(Boolean)),
+        ];
+        if (roots.length === 0) {
+          for (const reason of uncertain)
+            readGateTurnUncertainAllowed.add(reason);
+          readGateTurnAnswer = { choice: "always", instruction: "" };
+          return undefined;
+        }
+        const broad = roots.find((root) => isBroadGrantRoot(root));
+        if (broad) {
+          return {
+            block: true,
+            reason:
+              `Read policy: \`${broad}\` is too broad to persist from a dialog. Choose Allow once, or use /folder-policy any deliberately.`,
+          };
+        }
+        if (folderConfig.grantScope === "project" && !trusted) {
+          return {
+            block: true,
+            reason:
+              "Read policy 'ask': this project is not trusted, so a project-scoped grant would be ignored. " +
+              "Choose Allow once, trust the project first, or set folderPolicy.grantScope to 'global'.",
+          };
+        }
+        const written = writeReadPolicyConfig(
+          folderConfig.grantScope,
+          cwd,
+          getAgentDir(),
+          { allowedPaths: roots },
+        );
+        if (!written.ok) {
+          return {
+            block: true,
+            reason: `Read policy 'ask': could not save the permission grant (${written.error ?? "unknown error"}).`,
+          };
+        }
+        for (const root of roots) readGateTurnGrantedRoots.add(root);
+        for (const reason of uncertain) readGateTurnUncertainAllowed.add(reason);
+        readGateTurnAnswer = { choice: "always", instruction: "" };
+        return undefined;
+      }
+
       let instruction = "";
       if (choice === "deny-with-instructions") {
         const inputFn = (ui as any).input;
         if (typeof inputFn === "function") {
-          let typed: unknown;
           try {
-            typed = await inputFn.call(
-              ui,
-              WRITE_INSTRUCTION_PROMPT_TITLE,
-              WRITE_INSTRUCTION_PROMPT_PLACEHOLDER,
+            instruction = sanitizeReadInstruction(
+              await inputFn.call(
+                ui,
+                READ_INSTRUCTION_PROMPT_TITLE,
+                READ_INSTRUCTION_PROMPT_PLACEHOLDER,
+              ),
             );
-          } catch (_e) {
-            void _e;
-            typed = undefined;
+          } catch {
+            instruction = "";
           }
-          instruction = sanitizeWriteInstruction(typed);
         }
-        // No input dialog, a cancelled dialog, or empty text → plain denial
-        // below. A cancel is never an implicit allow.
-      }
-
-      // The answer covers every gated write of this turn.
-      writeGateTurnAnswer = { choice, instruction };
-      // …and the denial is remembered for the REST OF THE RUN, under every
-      // target of this turn: a later retry is auto-denied with the same
-      // sentence instead of asking the user again.
-      for (const item of items) {
-        writeGateRunDenials.set(item.key, { instruction });
       }
-
-      const reason = buildWriteDenyReason({
-        target: items.length > 1 ? writeGateTargetsLabel(items) : target,
-        why: classification.reason,
-        instruction,
-      });
-
-      if (instruction) {
-        // Channel 2: a user-role message. `steer` queues it while the agent
-        // is running; it lands after the current tool batch, before the next
-        // model call, as a genuine user turn. ONE per turn, not one per
-        // blocked call.
-        deliverWriteInstruction(items, instruction);
-        // Audit trail — transcript only (appendEntry is never sent to the
-        // LLM). One entry per turn: it records the user's decision, not each
-        // call the decision was applied to.
-        try {
-          pi.appendEntry("workflow-write-denial", {
-            tool: String(event.toolName ?? ""),
-            target,
-            instruction,
-            at: Date.now(),
-            targets: items.map((item) => item.target),
-          });
-        } catch (_e) {
-          void _e;
-        }
+      readGateTurnAnswer = { choice: "deny", instruction };
+      for (const item of items) readGateRunDenials.set(item.key, { instruction });
+      if (instruction)
+        deliverReadInstruction(
+          instruction,
+          readGateTargetsLabel(items) || "the requested read",
+        );
+      try {
+        pi.appendEntry("workflow-read-denial", {
+          tool: String(event.toolName ?? ""),
+          target: readGateTargetsLabel(items),
+          instruction,
+          at: Date.now(),
+        });
+      } catch (_e) {
+        void _e;
       }
-
       return {
         block: true,
-        reason,
-        // NOTE: no `terminate` here. pi consults `terminate` only AFTER the
-        // whole tool batch has run (`executeToolCallsParallel` prepares and
-        // runs every call before `shouldTerminateToolBatch()`), so it cannot
-        // suppress a sibling write in the same batch — it only decides
-        // whether the agent gets ANOTHER LLM turn. With it set, a plain Deny
-        // would end the run with no model acknowledgement at all: a
-        // behaviour change nobody asked for. The guided path gets its next
-        // turn from the queued steer message instead.
+        reason: buildReadDenyReason({
+          kind: "outside",
+          target: readGateTargetsLabel(items) || "the requested read",
+          instruction,
+        }),
       };
-    } catch (e: unknown) {
-      // Fail closed: a broken policy read must not become an open door.
+    } catch (error: unknown) {
       return {
         block: true,
         reason:
-          `Write policy (workflow.writePolicy) could not be evaluated (${e instanceof Error ? e.message : String(e)}), so the write was blocked. ` +
-          "Do not retry. Ask the user to switch to Build mode (/build) or to fix the policy with /write-policy.",
+          `Read policy could not be evaluated (${error instanceof Error ? error.message : String(error)}), so the read was blocked. ` +
+          "Do not retry; ask the user to fix /read-policy or /folder-policy.",
       };
     }
   }
@@ -9385,15 +11589,19 @@ export default function workflowExtension(
         reason: `${gateRole} role: ${event.toolName} blocked — this role is read-only.`,
       } as any;
     }
-    // ── Write permission gate (workflow.writePolicy) ── Independent of the
-    // role gate and of the commit policy: it governs whether the USER
-    // permits a write at all. It only applies in Default mode — Plan has its
-    // own stricter rules and Build is the approved-execution escape hatch —
-    // and it runs last so it only sees calls nothing else claimed.
-    if (workflowMode === null) {
+    // ── Write permission gate (workflow.writePolicy + shared folder floor) ──
+    // The write MODE is a Default-mode knob; the folder floor applies in every
+    // mode. It runs after the role/commit rules and before the build-todo
+    // guard so a folder/sensitive refusal wins.
+    {
       const writeBlock = await writePolicyGate(event, ctx, cwd);
       if (writeBlock) return writeBlock as any;
     }
+    // ── Read permission gate (workflow.readPolicy + shared folder floor) ──
+    {
+      const readBlock = await readPolicyGate(event, ctx, cwd);
+      if (readBlock) return readBlock as any;
+    }
     // In build mode, ensure todos exist before first real edit
     if (
       (event.toolName === "edit" || event.toolName === "write") &&
@@ -9455,7 +11663,73 @@ export default function workflowExtension(
       seedCommittedStepRefs();
       const completed = uncommittedDoneSteps();
       const dirty = await isDirty(pi as any, cwd);
-      const mode = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+      const trusted = ctx?.isProjectTrusted?.() === true;
+      const commitConfig = readCommitPolicyConfig(cwd, getAgentDir(), {
+        trusted,
+      }).config;
+      const folderConfig = readFolderPolicyConfig(cwd, getAgentDir(), {
+        trusted,
+      }).config;
+      const repoRoot = detectRepoRoot(cwd) ?? cwd;
+      const folder = evaluateFolderTargets(
+        [{ path: repoRoot, kind: "dir" }],
+        {
+          config: folderConfig,
+          grants: commitConfig.allowedPaths,
+          cwd,
+          action: "commit",
+        },
+      );
+      if (folder.outside.length > 0) {
+        ctx?.ui?.notify?.(
+          `Per-step commit skipped: ${repoRoot} is outside the permitted folders (use /folder-policy or grant it first).`,
+          "warning",
+        );
+        return;
+      }
+      const status = runGitZ(repoRoot, [
+        "status",
+        "--porcelain=v1",
+        "-z",
+        "--untracked-files=all",
+      ]);
+      if (!status.ok) {
+        ctx?.ui?.notify?.(
+          `Per-step commit skipped: sensitive-file check could not run (${status.error ?? "git status failed"}).`,
+          "warning",
+        );
+        return;
+      }
+      const sensitive = status.paths
+        .map((p) => matchSensitivePath(p, folderConfig, repoRoot))
+        .find((hit) => hit.sensitive);
+      if (sensitive) {
+        ctx?.ui?.notify?.(
+          `Per-step commit skipped: ${sensitive.path} is sensitive. Remove it from the working tree/index or add a manual sensitiveExemptions entry.`,
+          "warning",
+        );
+        return;
+      }
+      const statusFolder = evaluateFolderTargets(
+        status.paths.map((p) => ({
+          path: path.join(repoRoot, p),
+          kind: "file" as const,
+        })),
+        {
+          config: folderConfig,
+          grants: commitConfig.allowedPaths,
+          cwd,
+          action: "commit",
+        },
+      );
+      if (statusFolder.outside.length > 0 || statusFolder.uncertain.length > 0) {
+        ctx?.ui?.notify?.(
+          `Per-step commit skipped: staged paths leave the permitted folders or could not be verified. Review the working tree and commit manually.`,
+          "warning",
+        );
+        return;
+      }
+      const mode = commitConfig.mode;
       const decision = stepCommitDecision({
         mode,
         hasTodos: todoItems.length > 0,
@@ -9512,6 +11786,44 @@ export default function workflowExtension(
     }
   }
 
+  // Output redaction is defence in depth for channels the tool gate cannot
+  // fully see (grep --hidden, git diff/show, truncated bash output).
+  pi.on("tool_result", async (event, ctx) => {
+    try {
+      const cwd = (ctx as any)?.cwd ?? process.cwd();
+      const folderConfig = readFolderPolicyConfig(cwd, getAgentDir(), {
+        trusted: (ctx as any)?.isProjectTrusted?.() === true,
+      }).config;
+      return redactToolResult(event as any, folderConfig, cwd) as any;
+    } catch (error: unknown) {
+      const tool = String((event as any)?.toolName ?? "");
+      if (
+        [
+          "read",
+          "read_symbol",
+          "read_enclosing",
+          "module_report",
+          "grep",
+          "find",
+          "ls",
+          "bash",
+          "powershell",
+        ].includes(tool)
+      ) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `[read policy redaction failed — output withheld: ${error instanceof Error ? error.message : String(error)}]`,
+            },
+          ],
+          structuredContent: undefined,
+        } as any;
+      }
+      return undefined;
+    }
+  });
+
   pi.on("tool_result", async (_event, ctx) => {
     try {
       const leaf =
@@ -9564,6 +11876,10 @@ export default function workflowExtension(
       writeGateBatchCallIds = callIds;
       writeGateTurnAnswer = null;
       writeGateTurnSteered = false;
+      readGateBatchCalls = calls;
+      readGateBatchCallIds = callIds;
+      readGateTurnAnswer = null;
+      readGateTurnSteered = false;
     } catch (_e) {
       void _e;
     }
@@ -9577,6 +11893,12 @@ export default function workflowExtension(
     writeGateTurnSteered = false;
     writeGateBatchCalls = [];
     writeGateBatchCallIds = new Set();
+    readGateTurnAnswer = null;
+    readGateTurnSteered = false;
+    readGateBatchCalls = [];
+    readGateBatchCallIds = new Set();
+    readGateTurnGrantedRoots.clear();
+    readGateTurnUncertainAllowed.clear();
     // Seed the per-step commit ledger once per session: steps already done
     // (restored sessions, re-executed plans) never trigger a spurious commit.
     try {
@@ -9627,6 +11949,13 @@ export default function workflowExtension(
     writeGateTurnSteered = false;
     writeGateBatchCalls = [];
     writeGateBatchCallIds = new Set();
+    readGateRunDenials.clear();
+    readGateTurnAnswer = null;
+    readGateTurnSteered = false;
+    readGateBatchCalls = [];
+    readGateBatchCallIds = new Set();
+    readGateTurnGrantedRoots.clear();
+    readGateTurnUncertainAllowed.clear();
     // keep persisted CustomEntry for reload, clear in-memory tombstone only on explicit prune; for now no clear to survive fork
   });
 
@@ -9675,12 +12004,47 @@ export default function workflowExtension(
   pi.on("before_agent_start", async (event, ctx) => {
     currentSessionCtx = ctx as any;
     ensurePlannotatorListeners();
+    // Safety valve for a prompt that bypassed `input` (host queue, another
+    // extension): never let a Review turn run concurrently with a plan/build
+    // turn. Stop the reviewer first, then let the queued prompt proceed.
+    if (reviewTurnOwns(reviewTurn) && reviewTurn !== "transition") {
+      // Invalidate the parked handoff BEFORE settling its gate: otherwise the
+      // runHandoff continuation can observe the old cycle token and render the
+      // abandoned plan alongside the new prompt.
+      reviewCycleId += 1;
+      try {
+        await suspendReview();
+      } catch (_e) {
+        void _e;
+      }
+      endReviewTurn();
+      notifyReview(
+        "Review stopped — a prompt was already queued; the plan was not reviewed.",
+        "info",
+      );
+    }
     // Fresh user prompt → reset the passive reminder cadence. Continuation runs
     // (triggerTurn/steer/followUp) do not fire this event, so state survives them.
     turnsSinceLastTodoWrite = 0;
     turnsSinceLastReminder = 0;
     mutatedSinceLastTodoWrite = false;
     footerInjectedThisTurn = false;
+    // A real user prompt means the user has moved on from a finished plan:
+    // hide the one-line todo panel. `custom` runs (triggerTurn) must not do
+    // this — they can be self-initiated while the user is still reading.
+    if (
+      event.messageType === "user" &&
+      isTodoListSettled(todoItems) &&
+      !todoPanelPromptAfterSettle
+    ) {
+      todoPanelPromptAfterSettle = true;
+      updateStatus(ctx);
+      try {
+        persistState();
+      } catch (_e) {
+        void _e;
+      }
+    }
     // A fresh user prompt starts a new handoff/provenance run. It also
     // supersedes any pending browser/inline decision immediately: the user
     // moved on, so a stale tab must not approve the previous plan. Follow-up
@@ -9705,10 +12069,14 @@ export default function workflowExtension(
     }
     // 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.
+    // render after this prompt. A feedback/refine continuation keeps the
+    // manual cycle alive; a genuine user prompt ends it.
+    const feedbackTurn = reviewFeedbackTurn;
+    reviewFeedbackTurn = false;
     try {
+      if (!feedbackTurn) endReviewTurn();
       await beginReviewCycle({
-        reason: "prompt",
+        reason: feedbackTurn ? "refine" : "prompt",
         keepFindings: true,
         planPath: currentPlanFile,
       });
@@ -9895,6 +12263,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;
 
@@ -9919,18 +12306,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;
   }
 
@@ -10232,26 +12689,36 @@ export default function workflowExtension(
       }
       // Build completion
       if (workflowMode === "build" && todoItems.length > 0) {
-        const allDone = todoItems.every(
-          (t) => isDone(t) || itemStatus(t) === "cancelled",
-        );
+        const allDone = isTodoListSettled(todoItems);
         if (allDone) {
-          try {
-            (pi as any).sendMessage?.(
-              {
-                customType: "workflow-complete",
-                content: `**Build Complete! ✓**\n\n${todoItems.map((t) => `~~${todoRef(t)}. ${t.text}~~`).join("\n")}`,
-                display: true,
-              },
-              { triggerTurn: false },
-            );
-          } catch (_e) {
-            void _e;
+          // One card per list revision: a settled list stays settled across
+          // turns, and re-sending the same card on every agent_end buried the
+          // transcript in duplicates. A new/renamed list or changed statuses
+          // produce a new signature and therefore a new card.
+          const signature = todoCompletionSignature(todoItems);
+          if (signature !== lastCompletedSignature) {
+            lastCompletedSignature = signature;
+            try {
+              (pi as any).sendMessage?.(
+                {
+                  customType: "workflow-complete",
+                  content: `**Build Complete! ✓**\n\n${todoItems.map((t) => `~~${todoRef(t)}. ${t.text}~~`).join("\n")}`,
+                  display: true,
+                },
+                { triggerTurn: false },
+              );
+            } catch (_e) {
+              void _e;
+            }
           }
           // keep todos for history but stay in build
           todoStale = false;
           updateStatus(ctx as any);
           persistState();
+        } else if (lastCompletedSignature !== null) {
+          // The list reopened (new step or a reverted status): allow the next
+          // completion to emit its own card. Persisted on the next mutation.
+          lastCompletedSignature = null;
         }
         return;
       }
@@ -10462,17 +12929,21 @@ 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;
+        // Review owns the turn before the reviewer boots. A plan handoff with
+        // Review Mode off never reaches this block (no Review turn).
+        beginReviewTurn();
         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;
@@ -10587,114 +13058,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();