@dieulc/workflow 0.8.0 → 0.9.0

package/index.ts

@@ -57,6 +57,8 @@ import {
   todoKey,
   isPlanWritePath,
   findPlanWritePathInMessages,
+  findLatestPlanWriteInBranch,
+  choosePlanPath,
   shouldHandoffPlan,
   getUtcDatePrefix,
   normalizePlanPath,
@@ -82,6 +84,7 @@ import {
   type TodoStatus,
   type TodoItem,
   type TodoUpdateEntry,
+  type PlanPathSource,
 } from "./utils.ts";
 import {
   WORKFLOW_ROLE_ENV,
@@ -164,12 +167,21 @@ import {
   roleIcon,
   BUILT_IN_ROLES,
   REVIEW_ROLE_NAME,
-  VALID_THINKING_LEVELS,
   type RoleConfig,
   type Role,
   type RoleModel,
   type ThinkingLevel,
 } from "./roles.ts";
+import {
+  clampThinkingForModel,
+  thinkingLevelsForModel,
+  thinkingLevelsForPair,
+} from "./thinking-levels.ts";
+import {
+  buildWorkflowStatusSegments,
+  setWorkflowStatus,
+  WORKFLOW_STATUS_KEYS,
+} from "./workflow-status.ts";
 import {
   defaultProfileConfig,
   loadProfilesDetailed,
@@ -247,6 +259,7 @@ import {
   type ReviewFinding,
   type ReviewExecutionResult,
   type ReviewHandoffGate,
+  type ReviewSdkLoader,
   type ReviewHandoffPhase,
   type ReviewHandoffResult,
   type ReviewModeLockKind,
@@ -475,7 +488,19 @@ function getFinalOutput(messages: any[]): string {
 
 // ── Main Extension ───────────────────────────────────────────────────
 
-export default function workflowExtension(pi: ExtensionAPI) {
+/**
+ * Optional seams for tests. Production callers (Pi) pass only `pi`, so the
+ * default remains byte-for-byte the shipped extension; tests inject a fake
+ * reviewer SDK to exercise `/review` and the handoff without a provider.
+ */
+export interface WorkflowExtensionDeps {
+  loadSdk?: ReviewSdkLoader;
+}
+
+export default function workflowExtension(
+  pi: ExtensionAPI,
+  deps: WorkflowExtensionDeps = {},
+) {
   // Review Mode streams the reviewer's output into the main transcript as
   // display-only entries. Registering once here keeps /reload idempotent.
   registerReviewEntryRenderers(pi);
@@ -557,6 +582,8 @@ export default function workflowExtension(pi: ExtensionAPI) {
     | { provider: string; id: string; thinking?: string }
     | undefined;
   let currentPlanFile: string | undefined;
+  /** Last plan path written into a persisted `workflow` entry. */
+  let lastPersistedPlanFile: string | undefined;
   let awaitingDecision = false;
   let lastHandoffAt: number | undefined;
   let handoffInFlight: Promise<void> | null = null;
@@ -1026,9 +1053,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
         if (found) {
           await withPersistSuppressed(async () => {
             await (pi as any).setModel?.(found);
-            if (m.thinking && isValidThinkingLevel(m.thinking)) {
-              (pi as any).setThinkingLevel?.(m.thinking);
-            }
+            applyThinkingForModel(ctx, found, m.thinking, "Default mode");
           });
           if (!opts?.quiet) {
             ctx.ui.notify(
@@ -1205,8 +1230,6 @@ export default function workflowExtension(pi: ExtensionAPI) {
     // Profile prefix (⚡ name) when one is active, then the role label.
     const profileLabel = activeProfileLabel();
     const roleLabel = activeRoleLabel();
-    const statusParts = [profileLabel, roleLabel].filter(Boolean);
-    const suffix = statusParts.length ? ` | ${statusParts.join(" | ")}` : "";
     // Commit-policy surfacing (workflow.commitPolicy): always visible so the
     // user can see at a glance what the agent may do to git history. Read
     // live so /commit-policy changes show up without a reload.
@@ -1219,7 +1242,6 @@ export default function workflowExtension(pi: ExtensionAPI) {
     } catch {
       commitMode = "never";
     }
-    const policy = ` · commits:${commitMode}`;
     // Write-policy surfacing (workflow.writePolicy): the active file-write
     // permission, visible at a glance like the commit policy. Read live so a
     // /write-policy change shows up without a reload. It only applies in
@@ -1233,67 +1255,38 @@ export default function workflowExtension(pi: ExtensionAPI) {
     } catch {
       writeMode = "allow";
     }
-    const writePolicy =
-      workflowMode === null ? ` · writes:${writeMode}` : "";
-    const staleMarker = todoStale ? " ⚠" : "";
-    // Review segment (plan 2026-10-23 follow-up): one footer owner — the
-    // round already shows `reviewStateSummary` in its widget, so the footer
-    // composes the same string instead of opening a second status key.
-    let reviewSegment = "";
-    try {
-      if (
-        reviewStatusVisible({
-          roundInFlight: activeReview !== undefined,
-          roundActive: reviewRuntime?.isRoundActive() === true,
-          paused: pausedReview !== undefined,
-        })
-      ) {
-        const seg = reviewFooterSegment(
-          reviewState,
-          pausedReview !== undefined,
-        );
-        if (seg) reviewSegment = ` · ${seg}`;
-      }
-      // Lock marker is independent of `reviewState`: it must show during the
-      // cold boot (before the first phase event) and while the gated handoff
-      // audit has returned but not yet rendered.
-      const lockFooter = reviewModeLockFooter(reviewModeLockKindNow());
-      if (lockFooter) reviewSegment += ` · ${lockFooter}`;
-    } catch (_e) {
-      void _e;
-      reviewSegment = "";
-    }
-    const done = todoItems.filter((t) => isDone(t)).length;
-    const total = todoItems.length;
-    if (workflowMode === "build") {
-      const label =
-        total > 0
-          ? `▶ build ${done}/${total}${staleMarker}${suffix}${policy}${writePolicy}${reviewSegment}`
-          : `▶ build${suffix}${policy}${writePolicy}${reviewSegment}`;
-      ctx.ui.setStatus("workflow", ctx.ui.theme.fg("accent", label));
-    } else if (workflowMode === "plan") {
-      const base = plannotatorActive
-        ? "⏸ plan — reviewing in browser"
-        : "⏸ plan";
-      const label =
-        total > 0
-          ? `${base} ${done}/${total}${staleMarker}${suffix}${policy}${writePolicy}${reviewSegment}`
-          : `${base}${suffix}${policy}${writePolicy}${reviewSegment}`;
-      ctx.ui.setStatus("workflow", ctx.ui.theme.fg("warning", label));
-    } else if (total > 0) {
-      ctx.ui.setStatus(
-        "workflow",
-        ctx.ui.theme.fg(
-          "muted",
-          `◦ ${done}/${total}${staleMarker}${suffix}${policy}${writePolicy}${reviewSegment}`,
-        ),
-      );
-    } else {
-      ctx.ui.setStatus(
-        "workflow",
-        ctx.ui.theme.fg("muted", `◦ commits:${commitMode}${writePolicy}${reviewSegment}`),
-      );
-    }
+    const segments = buildWorkflowStatusSegments({
+      mode: workflowMode,
+      plannotatorActive,
+      done: todoItems.filter((t) => isDone(t)).length,
+      total: todoItems.length,
+      stale: todoStale,
+      profileLabel,
+      roleLabel,
+      commitMode,
+      writeMode: workflowMode === null ? writeMode : null,
+    });
+    const modeTone =
+      workflowMode === "build"
+        ? "accent"
+        : workflowMode === "plan"
+          ? "warning"
+          : "muted";
+    setWorkflowStatus(
+      ctx.ui,
+      WORKFLOW_STATUS_KEYS.mode,
+      ctx.ui.theme.fg(modeTone, segments.mode),
+    );
+    setWorkflowStatus(
+      ctx.ui,
+      WORKFLOW_STATUS_KEYS.profile,
+      segments.profile ? ctx.ui.theme.fg("muted", segments.profile) : "",
+    );
+    setWorkflowStatus(
+      ctx.ui,
+      WORKFLOW_STATUS_KEYS.policy,
+      ctx.ui.theme.fg("dim", segments.policy),
+    );
     if (todoItems.length > 0) {
       ctx.ui.setWidget("workflow-todos", (_tui, theme) => {
         return {
@@ -1601,8 +1594,6 @@ export default function workflowExtension(pi: ExtensionAPI) {
     reviewTruncationNoted = false;
   }
 
-  const REVIEW_STATUS_WIDGET = "workflow-review-status";
-
   function reviewAgentDir(): string {
     try {
       return getAgentDir();
@@ -1635,6 +1626,121 @@ export default function workflowExtension(pi: ExtensionAPI) {
     }
   }
 
+  interface ReviewPlanTarget {
+    abs: string;
+    text: string;
+    source: PlanPathSource;
+    display: string;
+  }
+
+  type ReviewPlanResolution =
+    | { kind: "ok"; target: ReviewPlanTarget }
+    | { kind: "no-plan"; recent: string[] }
+    | { kind: "error"; message: string };
+
+  /** Newest `.pi/plans/*.md` files, relative to cwd, newest first. */
+  function listRecentPlanFiles(cwd: string, limit = 3): string[] {
+    try {
+      const dir = path.join(cwd, CONFIG_DIR_NAME, "plans");
+      return fs
+        .readdirSync(dir)
+        .filter((f) => f.toLowerCase().endsWith(".md"))
+        .map((f) => {
+          const abs = path.join(dir, f);
+          return { abs, mtime: fs.statSync(abs).mtimeMs };
+        })
+        .sort((a, b) => b.mtime - a.mtime)
+        .slice(0, limit)
+        .map((r) => path.relative(cwd, r.abs) || r.abs);
+    } catch (_e) {
+      void _e;
+      return [];
+    }
+  }
+
+  /**
+   * Resolve the plan a manual `/review` should audit.
+   *
+   * Priority (plan 2026-10-31): explicit path → this run's write → the
+   * session's last write → the handoff target → the newest write in the
+   * session branch. A candidate that no longer exists or is empty is skipped.
+   * An explicit path is authoritative: if it is unreadable or outside
+   * `.pi/plans/`, the command reports that instead of silently falling back
+   * to a different file.
+   */
+  function resolveReviewTarget(
+    ctx: any,
+    explicitArg: string | undefined,
+  ): ReviewPlanResolution {
+    const cwd = (ctx as any)?.cwd ?? process.cwd();
+    const display = (abs: string) => path.relative(cwd, abs) || abs;
+    const candidates: Array<{ path: string; source: PlanPathSource }> = [];
+    const push = (raw: string | null | undefined, source: PlanPathSource) => {
+      if (typeof raw !== "string" || raw.length === 0) return;
+      candidates.push({
+        path: path.isAbsolute(raw) ? raw : path.join(cwd, raw),
+        source,
+      });
+    };
+    if (explicitArg) {
+      const abs = path.isAbsolute(explicitArg)
+        ? explicitArg
+        : path.join(cwd, explicitArg);
+      if (!isPlanWritePath(abs, cwd)) {
+        return {
+          kind: "error",
+          message: `Review only reads plans under ${path.join(CONFIG_DIR_NAME, "plans")}${path.sep} — got ${explicitArg}`,
+        };
+      }
+      push(abs, "explicit");
+    } else {
+      push(planWritePathThisRun, "run");
+      push(lastPlanWritePath, "session");
+      push(currentPlanFile, "handoff");
+      try {
+        const branch = (ctx as any)?.sessionManager?.getBranch?.() ?? [];
+        push(findLatestPlanWriteInBranch(branch, cwd), "branch");
+      } catch (_e) {
+        void _e;
+      }
+    }
+    const read = (abs: string): string | undefined => {
+      try {
+        if (!fs.statSync(abs).isFile()) return undefined;
+        const text = fs.readFileSync(abs, "utf8");
+        return text.length > 0 ? text : undefined;
+      } catch {
+        return undefined;
+      }
+    };
+    const chosen = choosePlanPath(candidates, (abs) => read(abs) !== undefined);
+    if (!chosen) {
+      if (explicitArg) {
+        return {
+          kind: "error",
+          message: `Plan file not readable: ${explicitArg}`,
+        };
+      }
+      return { kind: "no-plan", recent: listRecentPlanFiles(cwd) };
+    }
+    const text = read(chosen.path);
+    if (text === undefined) {
+      return {
+        kind: "error",
+        message: `Plan file not readable: ${display(chosen.path)}`,
+      };
+    }
+    return {
+      kind: "ok",
+      target: {
+        abs: chosen.path,
+        text,
+        source: chosen.source,
+        display: display(chosen.path),
+      },
+    };
+  }
+
   function reviewConfigNow() {
     try {
       return readReviewModeConfig(reviewCwd(), reviewAgentDir());
@@ -1711,26 +1817,23 @@ export default function workflowExtension(pi: ExtensionAPI) {
         roundActive,
         paused,
       });
-      // The widget is a LIVE review indicator, not a result holder: the last
+      // The review status is a LIVE indicator, not a result holder: the last
       // round's state stays for `/review-status` and the REVIEW SUMMARY band,
-      // but the editor line must disappear as soon as the round ends. While
+      // but the footer segment must disappear as soon as the round ends. While
       // paused it shows the paused form (never the terminal "aborted" summary).
-      const text = visible ? reviewFooterSegment(reviewState, paused) : "";
-      if (!visible || !text) {
-        ctx.ui.setWidget(REVIEW_STATUS_WIDGET, undefined);
-        return;
+      const reviewText = visible ? reviewFooterSegment(reviewState, paused) : "";
+      let lockText = "";
+      try {
+        lockText = reviewModeLockFooter(reviewModeLockKindNow());
+      } catch (_e) {
+        void _e;
       }
-      ctx.ui.setWidget(REVIEW_STATUS_WIDGET, (_tui: any, theme: any) => ({
-        render: (w: number) => [
-          truncateToWidth(
-            theme.fg("muted", text),
-            Math.max(10, Number(w) || 40),
-            "…",
-          ),
-        ],
-        invalidate: () => {},
-        dispose: () => {},
-      }));
+      const text = [reviewText, lockText].filter(Boolean).join(" · ");
+      setWorkflowStatus(
+        ctx.ui,
+        WORKFLOW_STATUS_KEYS.review,
+        text ? ctx.ui.theme.fg("muted", text) : "",
+      );
     } catch (_e) {
       void _e;
     }
@@ -1873,6 +1976,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
         }
       },
       onTranscriptOps: (ops) => pushReviewOps(ops),
+      ...(deps.loadSdk ? { loadSdk: deps.loadSdk } : {}),
     });
     return reviewRuntime;
   }
@@ -2496,7 +2600,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
     resetReviewStream();
     detachReviewEscListenerNow();
     try {
-      currentSessionCtx?.ui.setWidget(REVIEW_STATUS_WIDGET, undefined);
+      currentSessionCtx?.ui.setStatus(WORKFLOW_STATUS_KEYS.review, undefined);
     } catch (_e) {
       void _e;
     }
@@ -2932,14 +3036,34 @@ export default function workflowExtension(pi: ExtensionAPI) {
 
   pi.registerCommand("review", {
     description:
-      "Run a one-shot Review round now; works whether Review Mode is on or off (mode stays OFF); /review say <msg> talks to the in-flight reviewer",
+      "Run a one-shot Review round now: /review [path] works whether Review Mode is on or off (mode stays OFF); /review say <msg> talks to the in-flight reviewer",
+    getArgumentCompletions: (prefix: string) => {
+      const cwd = (currentSessionCtx as any)?.cwd ?? process.cwd();
+      const items = [
+        {
+          value: "say",
+          label: "say",
+          description: "Send a message to the in-flight reviewer",
+        },
+        ...listRecentPlanFiles(cwd, 8).map((p) => ({
+          value: p,
+          label: p,
+          description: "Review this plan",
+        })),
+      ];
+      const p = prefix.trim();
+      const filtered = items.filter(
+        (i) => i.value.startsWith(p) || i.label.startsWith(p),
+      );
+      return filtered.length ? filtered : null;
+    },
     handler: async (args, ctx) => {
       // Explicit reviewer steering (plan 2026-10-23, step 3): the only path
       // that delivers user text into an in-flight review round. Plain chat
       // stays with the plan agent (see the `input` handler).
       const raw = (args || "").trim();
-      if (/^say\b/i.test(raw)) {
-        const message = raw.replace(/^say\b/i, "").trim();
+      if (/^say(?:\s|$)/i.test(raw)) {
+        const message = raw.replace(/^say(?:\s|$)/i, "").trim();
         if (!message) {
           ctx.ui.notify(
             "Usage: /review say <message> — send a message to the in-flight reviewer.",
@@ -2978,27 +3102,45 @@ export default function workflowExtension(pi: ExtensionAPI) {
       // Manual one-shot review: works whether or not Review Mode is on.
       // No `enabled` check here — readReviewModeConfig never throws and
       // runReviewStep("manual") supplies defaults when unreadable.
-      const planPath = currentPlanFile;
-      if (!planPath) {
+      //
+      // The plan is resolved independently of handoff eligibility: a run that
+      // started in Default and switched to Plan, or a plan written before a
+      // mode switch, must still be auditable (plan 2026-10-31).
+      const cwd = (ctx as any)?.cwd ?? process.cwd();
+      let explicit: string | undefined = raw.length
+        ? raw.replace(/^(["'])(.*)\1$/, "$2").trim()
+        : undefined;
+      if (explicit) {
+        const abs = path.isAbsolute(explicit)
+          ? explicit
+          : path.join(cwd, explicit);
+        // Mirror the write-path auto-correction: a mistyped UTC date prefix
+        // should resolve to the file the extension actually wrote.
+        const normalized = normalizePlanPath(abs, cwd, getUtcDatePrefix());
+        explicit =
+          normalized.corrected &&
+          fs.existsSync(normalized.path) &&
+          !fs.existsSync(abs)
+            ? normalized.path
+            : abs;
+      }
+      const resolution = resolveReviewTarget(ctx, explicit);
+      if (resolution.kind === "no-plan") {
+        const recent = resolution.recent;
+        const hint = recent.length
+          ? `\nRecent plans:\n${recent.map((r) => `  /review ${r}`).join("\n")}`
+          : "";
         ctx.ui.notify(
-          "No plan file yet — write one to .pi/plans/ first.",
+          `No plan file found for this session — run /review <path> with a file under .pi/plans/.${hint}`,
           "warning",
         );
         return;
       }
-      let text: string | undefined;
-      try {
-        const abs = path.isAbsolute(planPath)
-          ? planPath
-          : path.join((ctx as any).cwd ?? process.cwd(), planPath);
-        text = fs.existsSync(abs) ? fs.readFileSync(abs, "utf8") : undefined;
-      } catch (_e) {
-        void _e;
-      }
-      if (!text) {
-        ctx.ui.notify(`Plan file not readable: ${planPath}`, "warning");
+      if (resolution.kind === "error") {
+        ctx.ui.notify(resolution.message, "warning");
         return;
       }
+      const target = resolution.target;
       // The gated handoff owns the reviewer while it is open: a fresh round
       // here would race the handoff it is about to render. Steer the running
       // round with `/review say`, pause with ESC, or stop it with
@@ -3031,12 +3173,21 @@ export default function workflowExtension(pi: ExtensionAPI) {
           void _e;
         }
       }
+      // The reviewer writes through `currentPlanFile`; point it at the file
+      // `/review` actually read before the round starts. A fallback source is
+      // announced so the user can see which plan is being audited.
+      if (target.source !== "run" && target.source !== "explicit") {
+        notifyReview(`Reviewing ${target.display}`, "info");
+      }
+      currentPlanFile = target.abs;
+      lastPlanWritePath = target.abs;
+      persistState();
       lastReviewedPlanHash = undefined; // force a fresh review
       abortedReviewHash = undefined;
       pausedReview = undefined;
       reviewRound = 0;
       const result = await runReviewStep(
-        text,
+        target.text,
         ctx as any,
         (ctx as any).signal as AbortSignal | undefined,
         "manual",
@@ -3316,9 +3467,12 @@ export default function workflowExtension(pi: ExtensionAPI) {
     ) {
       await withPersistSuppressed(async () => {
         try {
-          if (m.thinking && isValidThinkingLevel(m.thinking)) {
-            (pi as any).setThinkingLevel?.(m.thinking);
-          }
+          applyThinkingForModel(
+            ctx,
+            current,
+            m.thinking,
+            `Workflow ${workflowMode ?? "mode"}`,
+          );
         } catch (_e) {
           void _e;
         }
@@ -3353,9 +3507,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
     }
     await withPersistSuppressed(async () => {
       try {
-        if (m.thinking && isValidThinkingLevel(m.thinking)) {
-          (pi as any).setThinkingLevel?.(m.thinking);
-        }
+        applyThinkingForModel(ctx, found, m.thinking, `Workflow ${workflowMode ?? "mode"}`);
       } catch (_e) {
         void _e;
       }
@@ -3417,12 +3569,12 @@ export default function workflowExtension(pi: ExtensionAPI) {
       current.id === defaultModel.id
     ) {
       try {
-        if (
-          defaultModel.thinking &&
-          isValidThinkingLevel(defaultModel.thinking)
-        ) {
-          (pi as any).setThinkingLevel?.(defaultModel.thinking);
-        }
+        applyThinkingForModel(
+          ctx,
+          current,
+          defaultModel.thinking as ThinkingLevel | undefined,
+          "Default mode",
+        );
       } catch (_e) {
         void _e;
       }
@@ -3438,12 +3590,12 @@ export default function workflowExtension(pi: ExtensionAPI) {
     if (!found) return; // registry no longer has it — keep current model
     try {
       await (pi as any).setModel?.(found);
-      if (
-        defaultModel.thinking &&
-        isValidThinkingLevel(defaultModel.thinking)
-      ) {
-        (pi as any).setThinkingLevel?.(defaultModel.thinking);
-      }
+      applyThinkingForModel(
+        ctx,
+        found,
+        defaultModel.thinking as ThinkingLevel | undefined,
+        "Default mode",
+      );
       if (!opts?.quiet) {
         ctx.ui.notify(
           `Default mode: model → ${defaultModel.provider}/${defaultModel.id}${defaultModel.thinking ? ` (${defaultModel.thinking})` : ""}`,
@@ -3605,6 +3757,31 @@ export default function workflowExtension(pi: ExtensionAPI) {
     }
   }
 
+  /**
+   * Apply a role/default thinking level, clamped to the model Pi will actually
+   * use. The role config is shared with terminal Pi and may predate the model's
+   * current `thinkingLevelMap`; clamping here keeps the live session valid.
+   *
+   * The clamp is **silent**: the host already shows the live thinking level, and
+   * notifying on every mode switch buried the transcript and toasts in the same
+   * advisory (2026-10-31 plan). Explicit `/role set` validation still warns
+   * because that is a direct user edit.
+   */
+  function applyThinkingForModel(
+    _ctx: ExtensionContext | null,
+    model: any,
+    level: ThinkingLevel | undefined,
+    _label: string,
+  ): void {
+    if (!level || !isValidThinkingLevel(level)) return;
+    const clamped = clampThinkingForModel(model, level);
+    try {
+      (pi as any).setThinkingLevel?.(clamped);
+    } catch (_e) {
+      void _e;
+    }
+  }
+
   /**
    * Read the persisted default from disk. Pure: it never mutates the in-memory
    * `defaultModel`, because precedence is resolved in one place at session
@@ -3645,6 +3822,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
       defaultModel,
       lastModeSwitch,
     } as any);
+    lastPersistedPlanFile = currentPlanFile;
   }
 
   async function setPlanMode(
@@ -3666,9 +3844,11 @@ export default function workflowExtension(pi: ExtensionAPI) {
     if (workflowMode === null) captureDefaultModel(ctx);
     workflowMode = "plan";
     syncLegacyFlags();
-    // Entering Plan starts a new handoff cycle. Old plan/todos stay as
-    // reference, but only the next fresh prompt can make a run eligible.
-    resetPlanRunProvenance();
+    // Do NOT reset per-run provenance here. A fresh prompt already does it at
+    // run start; preserving a plan write made earlier in THIS run is what lets
+    // `/review` (and the "Plan file ready" notice) see it after a mid-run
+    // switch. The mode-at-write flag keeps a Default-written plan from being
+    // auto-handoffed unless the write itself happened under Plan.
     clearPendingHandoffDecision();
     if (toolsBeforePlanMode === undefined)
       toolsBeforePlanMode = pi.getActiveTools();
@@ -4853,21 +5033,28 @@ export default function workflowExtension(pi: ExtensionAPI) {
           }
           thinking = thinkingRaw.toLowerCase() as any;
         }
-        // validate against registry (warn-only — model may be added later)
+        // Validate against the registry. A missing model is warn-only (it may be
+        // added later), but a known model clamps the stored level to its map.
+        let found: any;
         try {
-          const reg = (ctx as any)?.modelRegistry;
-          if (
-            reg &&
-            typeof reg.find === "function" &&
-            !reg.find(provider, id)
-          ) {
+          found = (ctx as any)?.modelRegistry?.find?.(provider, id);
+        } catch (_e) {
+          void _e;
+        }
+        if (!found) {
+          ctx.ui.notify(
+            `Warning: ${provider}/${id} not in model registry — saved anyway.`,
+            "warning",
+          );
+        } else {
+          const pair = thinkingLevelsForPair(found, thinking);
+          if (pair.level !== thinking) {
             ctx.ui.notify(
-              `Warning: ${provider}/${id} not in model registry — saved anyway.`,
+              `Thinking ${thinking} is not supported by ${provider}/${id}; using ${pair.level}.`,
               "warning",
             );
           }
-        } catch (_e) {
-          void _e;
+          thinking = pair.level;
         }
         role.model = { provider, id, thinking };
         const saved = saveAndSync(
@@ -5736,12 +5923,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
         const buildModelItems = (): FilterableItem[] =>
           modelPickerItems(showAll ? catalog.all : catalog.scoped);
         const modelLists = new Map<string, FilterableList>();
-        const thinkingList = new FilterableList({
-          items: VALID_THINKING_LEVELS.map((t) => ({ value: t, label: t })),
-          maxVisible: Math.min(VALID_THINKING_LEVELS.length, 8),
-          theme: themeList,
-          noMatchText: "No matching thinking levels",
-        });
+        const thinkingLists = new Map<string, FilterableList>();
         const getModelList = (roleName: string): FilterableList => {
           let list = modelLists.get(roleName);
           if (!list) {
@@ -5760,6 +5942,26 @@ export default function workflowExtension(pi: ExtensionAPI) {
           }
           return list;
         };
+        /** One list per model: the supported set differs per role/default tab. */
+        const getThinkingList = (roleName: string): FilterableList => {
+          let list = thinkingLists.get(roleName);
+          if (!list) {
+            const st = staged.get(roleName)!;
+            const levels = thinkingLevelsForModel(
+              registryModel(ctx, st.provider, st.id),
+            );
+            const idx = levels.indexOf(st.thinking);
+            list = new FilterableList({
+              items: levels.map((t) => ({ value: t, label: t })),
+              maxVisible: Math.min(levels.length, 8),
+              theme: themeList,
+              initialIndex: Math.max(0, idx),
+              noMatchText: "No matching thinking levels",
+            });
+            thinkingLists.set(roleName, list);
+          }
+          return list;
+        };
         // Ctrl+O re-scopes the rows: keep each tab's query and re-filter instead
         // of rebuilding the lists from scratch.
         const rebuildModelLists = () => {
@@ -5768,11 +5970,14 @@ export default function workflowExtension(pi: ExtensionAPI) {
         };
         const syncThinkingCursor = (roleName: string) => {
           const st = staged.get(roleName)!;
-          // Clear first: the shared list may still be filtered from a previous
-          // visit, and the index refers to the full VALID_THINKING_LEVELS order.
-          thinkingList.clearFilter();
-          const idx = VALID_THINKING_LEVELS.indexOf(st.thinking);
-          thinkingList.setSelectedIndex(idx >= 0 ? idx : 0);
+          const list = getThinkingList(roleName);
+          // Clear first: the list may still be filtered from a previous visit.
+          list.clearFilter();
+          const levels = thinkingLevelsForModel(
+            registryModel(ctx, st.provider, st.id),
+          );
+          const idx = levels.indexOf(st.thinking);
+          list.setSelectedIndex(idx >= 0 ? idx : 0);
         };
         const commitModelSelection = (roleName: string) => {
           const sel = getModelList(roleName).getSelectedItem();
@@ -5780,11 +5985,23 @@ export default function workflowExtension(pi: ExtensionAPI) {
           const { provider, id } = parseModelRef(sel.value);
           if (!provider || !id) return false;
           const st = staged.get(roleName)!;
-          staged.set(roleName, { ...st, provider, id });
+          // A new model can drop the staged level (DeepSeek has no `medium`).
+          const pair = thinkingLevelsForPair(
+            registryModel(ctx, provider, id),
+            st.thinking,
+          );
+          staged.set(roleName, {
+            ...st,
+            provider,
+            id,
+            thinking: pair.level,
+          });
+          // The old list belongs to the old model; rebuild on the next visit.
+          thinkingLists.delete(roleName);
           return true;
         };
         const commitThinkingSelection = (roleName: string) => {
-          const sel = thinkingList.getSelectedItem();
+          const sel = getThinkingList(roleName).getSelectedItem();
           if (!sel || !isValidThinkingLevel(sel.value)) return false;
           const st = staged.get(roleName)!;
           staged.set(roleName, { ...st, thinking: sel.value });
@@ -5842,7 +6059,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
           // (thinking → model) or cancels the editor.
           if (matchesKey(data, Key.escape)) {
             const activeList =
-              phase === "model" ? getModelList(roleName) : thinkingList;
+              phase === "model" ? getModelList(roleName) : getThinkingList(roleName);
             if (activeList.handleInput(data)) {
               cached = undefined;
               tui.requestRender();
@@ -5871,7 +6088,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
             return;
           }
           const activeList =
-            phase === "model" ? getModelList(roleName) : thinkingList;
+            phase === "model" ? getModelList(roleName) : getThinkingList(roleName);
           activeList.handleInput(data);
           cached = undefined;
           tui.requestRender();
@@ -5899,7 +6116,8 @@ export default function workflowExtension(pi: ExtensionAPI) {
           const chips: string[] = [];
           for (let i = 0; i < tabIds.length; i++) {
             const roleName = tabIds[i];
-            const st = staged.get(roleName)!;
+            const st = staged.get(roleName);
+            if (!st) continue;
             const base =
               roleName === "default"
                 ? existing?.defaultModel
@@ -5952,7 +6170,8 @@ export default function workflowExtension(pi: ExtensionAPI) {
             );
             lines.push("");
             for (const roleName of tabIds) {
-              const st = staged.get(roleName)!;
+              const st = staged.get(roleName);
+              if (!st) continue;
               lines.push(
                 ...wrap(
                   `  ${theme.fg("muted", `${roleIcon(roleName)} ${roleName}: `)}${theme.fg(
@@ -5966,8 +6185,9 @@ export default function workflowExtension(pi: ExtensionAPI) {
             }
           } else {
             const roleName = tabIds[currentTab];
-            const st = staged.get(roleName)!;
-            const meta = roleMeta.get(roleName)!;
+            const st = staged.get(roleName);
+            const meta = roleMeta.get(roleName);
+            if (!st || !meta) return cached ?? lines;
             lines.push(
               ...wrap(
                 ` ${theme.fg("text", `${roleIcon(roleName)} ${roleName} — ${meta.description}`)}`,
@@ -6025,9 +6245,10 @@ export default function workflowExtension(pi: ExtensionAPI) {
               lines.push(
                 ...wrap(` ${theme.fg("accent", "Thinking level:")}`),
               );
-              for (const l of thinkingList.renderQuery(Math.max(1, W - 2)))
+              const list = getThinkingList(roleName);
+              for (const l of list.renderQuery(Math.max(1, W - 2)))
                 lines.push(` ${l}`);
-              for (const l of thinkingList.renderList(Math.max(1, W - 2)))
+              for (const l of list.renderList(Math.max(1, W - 2)))
                 lines.push(` ${l}`);
             }
           }
@@ -6063,21 +6284,30 @@ export default function workflowExtension(pi: ExtensionAPI) {
       );
       return "cancelled";
     }
-    // Validate against registry (warn-only, matching /role set).
+    // Validate against registry (warn-only, matching /role set). A known model
+    // also clamps its staged thinking level so this save cannot write a pair
+    // the model does not support.
     try {
       const reg = (ctx as any)?.modelRegistry;
       if (reg && typeof reg.find === "function") {
         for (const [roleName, st] of saved.staged) {
-          if (
-            st.provider &&
-            st.id &&
-            typeof reg.find === "function" &&
-            !reg.find(st.provider, st.id)
-          )
+          if (!st.provider || !st.id) continue;
+          const model = reg.find(st.provider, st.id);
+          if (!model) {
             ctx.ui.notify(
               `Warning: ${st.provider}/${st.id} (${roleName}) not in model registry — saved anyway.`,
               "warning",
             );
+            continue;
+          }
+          const pair = thinkingLevelsForPair(model, st.thinking);
+          if (pair.level !== st.thinking) {
+            ctx.ui.notify(
+              `Thinking ${st.thinking} → ${pair.level} for ${roleName} (${st.provider}/${st.id} does not support ${st.thinking}).`,
+              "warning",
+            );
+            st.thinking = pair.level;
+          }
         }
       }
     } catch (_e) {
@@ -6611,15 +6841,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
           const buildModelItems = (): FilterableItem[] =>
             modelPickerItems(showAll ? catalog.all : catalog.scoped);
           const modelLists = new Map<string, FilterableList>();
-          const thinkingList = new FilterableList({
-            items: VALID_THINKING_LEVELS.map((t) => ({
-              value: t,
-              label: t,
-            })),
-            maxVisible: Math.min(VALID_THINKING_LEVELS.length, 8),
-            theme: listTheme,
-            noMatchText: "No matching thinking levels",
-          });
+          const thinkingLists = new Map<string, FilterableList>();
           const getModelList = (role: Role): FilterableList => {
             let list = modelLists.get(role.name);
             if (!list) {
@@ -6638,6 +6860,26 @@ export default function workflowExtension(pi: ExtensionAPI) {
             }
             return list;
           };
+          /** One list per role: the supported set follows that role's model. */
+          const getThinkingList = (role: Role): FilterableList => {
+            let list = thinkingLists.get(role.name);
+            if (!list) {
+              const st = staged.get(role.name)!;
+              const levels = thinkingLevelsForModel(
+                registryModel(ctx, st.provider, st.id),
+              );
+              const idx = levels.indexOf(st.thinking);
+              list = new FilterableList({
+                items: levels.map((t) => ({ value: t, label: t })),
+                maxVisible: Math.min(levels.length, 8),
+                theme: listTheme,
+                initialIndex: Math.max(0, idx),
+                noMatchText: "No matching thinking levels",
+              });
+              thinkingLists.set(role.name, list);
+            }
+            return list;
+          };
           // Ctrl+O re-scopes the rows: keep each tab's query and re-filter
           // instead of rebuilding the lists from scratch.
           const rebuildModelLists = () => {
@@ -6646,11 +6888,14 @@ export default function workflowExtension(pi: ExtensionAPI) {
           };
           const syncThinkingCursor = (role: Role) => {
             const st = staged.get(role.name)!;
-            // Clear first: the shared list may still be filtered from a previous
-            // visit, and the index refers to the full VALID_THINKING_LEVELS order.
-            thinkingList.clearFilter();
-            const idx = VALID_THINKING_LEVELS.indexOf(st.thinking);
-            thinkingList.setSelectedIndex(idx >= 0 ? idx : 0);
+            const list = getThinkingList(role);
+            // Clear first: the list may still be filtered from a previous visit.
+            list.clearFilter();
+            const levels = thinkingLevelsForModel(
+              registryModel(ctx, st.provider, st.id),
+            );
+            const idx = levels.indexOf(st.thinking);
+            list.setSelectedIndex(idx >= 0 ? idx : 0);
           };
           const isSubmitTab = () => currentTab === tabs.length;
 
@@ -6660,13 +6905,22 @@ export default function workflowExtension(pi: ExtensionAPI) {
             const { provider, id } = parseModelRef(sel.value);
             if (!provider || !id) return false;
             const st = staged.get(role.name)!;
-            staged.set(role.name, { ...st, provider, id });
-            // If the chosen model is unknown to the registry, keep it —
-            // save path warns, matching /role set behavior.
+            const pair = thinkingLevelsForPair(
+              registryModel(ctx, provider, id),
+              st.thinking,
+            );
+            staged.set(role.name, {
+              ...st,
+              provider,
+              id,
+              thinking: pair.level,
+            });
+            // The old list belongs to the old model; rebuild on the next visit.
+            thinkingLists.delete(role.name);
             return true;
           };
           const commitThinkingSelection = (role: Role) => {
-            const sel = thinkingList.getSelectedItem();
+            const sel = getThinkingList(role).getSelectedItem();
             if (!sel || !isValidThinkingLevel(sel.value)) return false;
             const st = staged.get(role.name)!;
             staged.set(role.name, { ...st, thinking: sel.value });
@@ -6723,7 +6977,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
             // (thinking → model) or cancels the picker.
             if (matchesKey(data, Key.escape)) {
               const activeList =
-                phase === "model" ? getModelList(role) : thinkingList;
+                phase === "model" ? getModelList(role) : getThinkingList(role);
               if (activeList.handleInput(data)) {
                 cached = undefined;
                 tui.requestRender();
@@ -6752,7 +7006,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
               return;
             }
             const activeList =
-              phase === "model" ? getModelList(role) : thinkingList;
+              phase === "model" ? getModelList(role) : getThinkingList(role);
             activeList.handleInput(data);
             cached = undefined;
             tui.requestRender();
@@ -6895,9 +7149,10 @@ export default function workflowExtension(pi: ExtensionAPI) {
                 lines.push(
                   ...wrap(` ${theme.fg("accent", "Thinking level:")}`),
                 );
-                for (const l of thinkingList.renderQuery(Math.max(1, W - 2)))
+                const list = getThinkingList(role);
+                for (const l of list.renderQuery(Math.max(1, W - 2)))
                   lines.push(` ${l}`);
-                for (const l of thinkingList.renderList(Math.max(1, W - 2)))
+                for (const l of list.renderList(Math.max(1, W - 2)))
                   lines.push(` ${l}`);
               }
             }
@@ -6931,16 +7186,28 @@ export default function workflowExtension(pi: ExtensionAPI) {
       ctx.ui.notify("Role picker cancelled.", "info");
       return;
     }
-    // Validate against registry (warn-only, matching /role set) then save.
+    // Validate against registry (warn-only, matching /role set) and clamp each
+    // staged thinking level to the model it will run on.
     try {
       const reg = (ctx as any)?.modelRegistry;
       if (reg && typeof reg.find === "function") {
         for (const [name, st] of saved) {
-          if (!reg.find(st.provider, st.id))
+          const model = reg.find(st.provider, st.id);
+          if (!model) {
             ctx.ui.notify(
               `Warning: ${st.provider}/${st.id} (${name}) not in model registry — saved anyway.`,
               "warning",
             );
+            continue;
+          }
+          const pair = thinkingLevelsForPair(model, st.thinking);
+          if (pair.level !== st.thinking) {
+            ctx.ui.notify(
+              `Thinking ${st.thinking} → ${pair.level} for ${name} (${st.provider}/${st.id} does not support ${st.thinking}).`,
+              "warning",
+            );
+            st.thinking = pair.level;
+          }
         }
       }
     } catch (_e) {
@@ -7750,6 +8017,9 @@ export default function workflowExtension(pi: ExtensionAPI) {
   // ── Session & Agent lifecycle ────────────────────────────────────
 
   pi.on("session_start", async (event, ctx) => {
+    // A session boundary owns the session-scoped plan fallback; the restore
+    // loop below re-seeds it from the persisted `planFile`.
+    resetSessionPlanProvenance();
     // A reloaded/forked session must never inherit a stale write denial.
     writeGateRunDenials.clear();
     writeGateTurnAnswer = null;
@@ -7797,7 +8067,11 @@ export default function workflowExtension(pi: ExtensionAPI) {
             if (Array.isArray(d.todos)) todoItems = ensureTodoLabels(d.todos);
             todoPlanPath = d.planFile;
             toolsBeforePlanMode = d.toolsBeforePlanMode;
-            currentPlanFile = d.planFile;
+            // An entry without a planFile must not erase a value restored
+            // from an earlier entry (the entry shape has changed over time).
+            if (typeof d.planFile === "string" && d.planFile) {
+              currentPlanFile = d.planFile;
+            }
             // restore role state (file config is source of truth for roles;
             // session entry carries the latest activeRole) and the session's
             // own profile activation
@@ -8041,12 +8315,12 @@ export default function workflowExtension(pi: ExtensionAPI) {
             await withPersistSuppressed(async () => {
               const ok = await (pi as any)?.setModel?.(found);
               if (ok === false) throw new Error("setModel returned false");
-              if (
-                effectiveDefault.thinking &&
-                isValidThinkingLevel(effectiveDefault.thinking)
-              ) {
-                (pi as any).setThinkingLevel?.(effectiveDefault.thinking);
-              }
+              applyThinkingForModel(
+                ctx as any,
+                found,
+                effectiveDefault.thinking,
+                "Session start",
+              );
             });
           } catch (e: any) {
             // Auth missing or the provider rejected the switch: keep Pi's pick.
@@ -8107,6 +8381,8 @@ export default function workflowExtension(pi: ExtensionAPI) {
     // pending browser correlation. The persisted awaitingDecision recovery
     // above is kept for a recent modal; the first fresh prompt supersedes it.
     resetPlanRunProvenance();
+    lastPlanWritePath = currentPlanFile ?? null;
+    lastPersistedPlanFile = currentPlanFile;
     pendingHandoffPlanPath = null;
     pendingHandoffPlanHash = null;
     lastReviewId = null;
@@ -8167,6 +8443,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
     // Ensure a handoff decision/provenance does not persist stale across restart
     const clearedAtShutdown = clearPendingHandoffDecision();
     resetPlanRunProvenance();
+    resetSessionPlanProvenance();
     if (clearedAtShutdown) {
       try {
         persistState();
@@ -8174,7 +8451,10 @@ export default function workflowExtension(pi: ExtensionAPI) {
         void _e;
       }
     }
-    ctx.ui.setStatus("workflow", undefined);
+    ctx.ui.setStatus(WORKFLOW_STATUS_KEYS.mode, undefined);
+    ctx.ui.setStatus(WORKFLOW_STATUS_KEYS.profile, undefined);
+    ctx.ui.setStatus(WORKFLOW_STATUS_KEYS.policy, undefined);
+    ctx.ui.setStatus(WORKFLOW_STATUS_KEYS.review, undefined);
     ctx.ui.setWidget("workflow-todos", undefined);
     // Drop any /commit authorization or flow: a reload/quit must never leave
     // an exemption armed for whatever runs next.
@@ -8191,6 +8471,10 @@ export default function workflowExtension(pi: ExtensionAPI) {
     todoItems = [];
     todoPlanPath = undefined;
     btwNotes = [];
+    // 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();
+    clearPendingHandoffDecision();
     // A rewind must not preserve a /commit exemption across branches.
     commitAuthorization = null;
     pendingCommitFlow = null;
@@ -8214,6 +8498,11 @@ export default function workflowExtension(pi: ExtensionAPI) {
           todoItems = ensureTodoLabels(e.message.details.todos);
         }
       }
+      // Re-derive the plan from the branch we rewound to. Keeping the old
+      // value would let `/review` audit a plan that no longer exists here.
+      const latest = findLatestPlanWriteInBranch(branch, ctx.cwd);
+      currentPlanFile = latest;
+      lastPlanWritePath = latest ?? null;
     } catch (_e) {
       void _e;
     }
@@ -9179,24 +9468,18 @@ export default function workflowExtension(pi: ExtensionAPI) {
     // moved on, so a stale tab must not approve the previous plan. Follow-up
     // runs keep the current run's provenance.
     try {
-      const fw =
-        (event as any).followUp === true ||
-        (event as any).deliverAs === "followUp";
-      if (!fw) {
-        const age = lastHandoffAt ? Date.now() - lastHandoffAt : Infinity;
-        const cleared = clearPendingHandoffDecision();
-        resetPlanRunProvenance();
-        handoffEligibleThisRun = workflowMode === "plan";
-        if (cleared) {
-          persistState();
-          try {
-            pi.appendEntry("workflow-handoff-reset-before-start", {
-              at: Date.now(),
-              age,
-            });
-          } catch (_e) {
-            void _e;
-          }
+      const age = lastHandoffAt ? Date.now() - lastHandoffAt : Infinity;
+      const cleared = clearPendingHandoffDecision();
+      resetPlanRunProvenance();
+      if (cleared) {
+        persistState();
+        try {
+          pi.appendEntry("workflow-handoff-reset-before-start", {
+            at: Date.now(),
+            age,
+          });
+        } catch (_e) {
+          void _e;
         }
       }
     } catch (_e) {
@@ -9365,23 +9648,40 @@ export default function workflowExtension(pi: ExtensionAPI) {
   });
 
   // Plan file detection + full render + decision gate
+  //
+  // Two lifetimes (plan 2026-10-31):
+  // - per-run: `planWritten*` / `planWritePathThisRun` decide the automatic
+  //   handoff for THIS run and reset on every fresh prompt/mode switch;
+  // - session: `lastPlanWritePath` is the manual `/review` fallback and must
+  //   survive mode switches and fresh prompts. Only a session boundary clears
+  //   it. (`currentPlanFile` is the reviewer/Build target and is kept too.)
   let lastPlanWritePath: string | null = null;
-  /** This user run started in Plan mode; a Build-originated run never hands off. */
-  let handoffEligibleThisRun = false;
   /** This run wrote/edited a plan file under .pi/plans/. */
   let planWrittenThisRun = false;
+  /** This run wrote a plan while Plan mode was active (a mid-run switch counts). */
+  let planWrittenInPlanModeThisRun = false;
   /** Absolute path of this run's last plan write. */
   let planWritePathThisRun: string | null = null;
   /** Plan path/hash the currently rendered handoff prompt belongs to. */
   let pendingHandoffPlanPath: string | null = null;
   let pendingHandoffPlanHash: string | null = null;
+  /** Last path announced by the suppressed-handoff notice (per run). */
+  let lastPlanReadyNoticeKey: string | null = null;
 
-  /** Clear per-run handoff provenance (fresh prompt / mode switch / session boundary). */
+  /** Clear per-run handoff provenance (fresh prompt / mode switch / run end). */
   function resetPlanRunProvenance(): void {
-    handoffEligibleThisRun = false;
     planWrittenThisRun = false;
+    planWrittenInPlanModeThisRun = false;
     planWritePathThisRun = null;
+    lastPlanReadyNoticeKey = null;
+    // Deliberately NOT lastPlanWritePath: a mode switch or a new prompt must
+    // not make the plan the user just wrote unreachable to `/review`.
+  }
+
+  /** Clear the session-scoped plan fallback (session start/shutdown only). */
+  function resetSessionPlanProvenance(): void {
     lastPlanWritePath = null;
+    lastPersistedPlanFile = undefined;
   }
 
   /**
@@ -9466,11 +9766,20 @@ export default function workflowExtension(pi: ExtensionAPI) {
           // handoff. `lastPlanWritePath` alone is session-lifetime stale.
           planWritePathThisRun = abs;
           planWrittenThisRun = true;
+          // The reviewer's `review_submit_plan` writes this path; a manual
+          // `/review` must also audit the file the user just wrote.
+          currentPlanFile = abs;
+          // A run that starts in Default/Build and switches into Plan mid-run
+          // still qualifies: what matters is the mode at write time.
+          if (workflowMode === "plan") planWrittenInPlanModeThisRun = true;
         } catch (_e) {
           void _e;
-          lastPlanWritePath = String(p);
-          planWritePathThisRun = String(p);
+          const raw = String(p);
+          lastPlanWritePath = raw;
+          planWritePathThisRun = raw;
           planWrittenThisRun = true;
+          currentPlanFile = raw;
+          if (workflowMode === "plan") planWrittenInPlanModeThisRun = true;
         }
         try {
           pi.appendEntry("workflow-handoff-resolve", {
@@ -9538,16 +9847,59 @@ export default function workflowExtension(pi: ExtensionAPI) {
             : path.join(cwd, found);
           lastPlanWritePath = planWritePathThisRun;
           planWrittenThisRun = true;
+          // The fallback only scans THIS run and we are in Plan mode now, so
+          // this current-run write is attributable to the Plan cycle.
+          planWrittenInPlanModeThisRun = true;
         }
       }
+      // Persist the plan target once per run, in every mode, before the
+      // eligibility gate. A plan written in Default/Build still needs to be
+      // reachable by `/review` and by a later resume.
+      if (planWritePathThisRun) {
+        const cwd = (ctx as any)?.cwd ?? process.cwd();
+        const abs = path.isAbsolute(planWritePathThisRun)
+          ? planWritePathThisRun
+          : path.join(cwd, planWritePathThisRun);
+        currentPlanFile = abs;
+        lastPlanWritePath = abs;
+        // Persist once per run even when the tool_result handler already set
+        // the in-memory target: resume must find the plan without a mode
+        // switch or a todo update happening to persist it first.
+        if (currentPlanFile !== lastPersistedPlanFile) persistState();
+      }
       if (workflowMode === "plan") {
         const eligible = shouldHandoffPlan({
           mode: workflowMode,
-          runStartedInPlan: handoffEligibleThisRun,
           planWrittenThisRun,
+          planWrittenInPlanMode: planWrittenInPlanModeThisRun,
         });
         if (!eligible) {
-          if (!planWrittenThisRun) clearPendingHandoffDecision();
+          if (planWrittenThisRun) {
+            // The plan is real and current, but it was written before this
+            // run entered Plan mode. Do not hand it off automatically; make
+            // the manual path discoverable instead.
+            const cwd = (ctx as any)?.cwd ?? process.cwd();
+            const abs = planWritePathThisRun
+              ? path.isAbsolute(planWritePathThisRun)
+                ? planWritePathThisRun
+                : path.join(cwd, planWritePathThisRun)
+              : undefined;
+            const key = abs ?? planWritePathThisRun;
+            if (key && key !== lastPlanReadyNoticeKey) {
+              lastPlanReadyNoticeKey = key;
+              const rel = abs ? path.relative(cwd, abs) || abs : key;
+              try {
+                ctx.ui.notify(
+                  `Plan file ready: ${rel}. Run /review to audit it.`,
+                  "info",
+                );
+              } catch (_e) {
+                void _e;
+              }
+            }
+          } else {
+            clearPendingHandoffDecision();
+          }
           return;
         }
       }
@@ -10667,6 +11019,10 @@ export default function workflowExtension(pi: ExtensionAPI) {
             }
             toolsBeforePlanMode = undefined;
           }
+          // Leaving Plan starts a new cycle; entering Plan preserves a plan
+          // written earlier in this run (see setPlanMode).
+          if (!state.active) resetPlanRunProvenance();
+          clearPendingHandoffDecision();
           // Find a ctx to update status — use a no-op if none
           // Status will be refreshed on next session_start/turn anyway
           persistState();