@agent-plan/pi-adapter 0.2.19-next.20 → 0.2.19-next.22

package/dist/index.js

@@ -9,7 +9,7 @@
  *  - inject context into prompts
  */
 import { Type } from "typebox";
-import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, buildPhaseContextBlock } from "@agent-plan/core";
+import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, buildPhaseContextBlock, checkExplicitTaskStart, recommendNextTask } from "@agent-plan/core";
 import { createChecklistItemId, createFeatureId, createPhaseId, createShortId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, featureNumberOfPhase, validateResolvedTarget } from "@agent-plan/core/naming";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
@@ -131,9 +131,9 @@ const PLANNER_COMMAND_COMPLETIONS = [
     { value: "task checklist-toggle", label: "task checklist-toggle", description: "Tick/untick a step: /planner task checklist-toggle <T00x> <C{n}|title> [on|off]" },
     { value: "handoff list", label: "handoff list", description: "List phases with a handoff" },
     { value: "handoff prepare", label: "handoff prepare", description: "Tell the agent to write the handoff (legacy file-based)" },
-    { value: "handoff show", label: "handoff show [P00x]", description: "Show a phase handoff (default: in-progress phase)" },
-    { value: "handoff write", label: "handoff write [P00x]", description: "Write a phase handoff (default: in-progress phase)" },
-    { value: "handoff clear", label: "handoff clear [P00x]", description: "Clear a phase handoff (default: in-progress phase)" },
+    { value: "handoff show", label: "handoff show [P00x]", description: "Show a phase handoff (phase ref required)" },
+    { value: "handoff write", label: "handoff write [P00x]", description: "Write a phase handoff after confirmation (phase ref required)" },
+    { value: "handoff clear", label: "handoff clear [P00x]", description: "Archive a phase handoff (phase ref required)" },
     { value: "web start", label: "web start", description: "Start the web UI" },
     { value: "web stop", label: "web stop", description: "Stop the web UI" },
     { value: "web status", label: "web status", description: "Show web UI status" },
@@ -144,6 +144,12 @@ const PLANNER_COMMAND_COMPLETIONS = [
     { value: "load", label: "load", description: "Enable planner + start web UI (LAN) and show resume summary" },
     { value: "stop", label: "stop", description: "Disable planner and shut down the web UI" },
 ];
+/** A completed nested command followed by a space is now receiving free-form
+ * arguments (entity refs, titles, etc.), not another command completion. */
+function hasPlannerCommandArgument(prefix) {
+    const normalized = prefix.trimStart().toLowerCase();
+    return PLANNER_COMMAND_COMPLETIONS.some((item) => normalized.startsWith(`${item.value.toLowerCase()} `));
+}
 // ─── Helpers ────────────────────────────────────────────────────────────
 function nowISO() {
     return new Date().toISOString();
@@ -201,7 +207,7 @@ async function maybeHealStatuses(st, ctx) {
 function normalizeLanguagePref(value) {
     return value?.trim() ?? "";
 }
-async function ensureProjectLanguagePreferences(st) {
+async function ensureProjectLanguagePreferences(st, persist = true) {
     const project = await st.loadProject();
     const contentLanguage = normalizeLanguagePref(project.contentLanguage);
     const chatLanguage = normalizeLanguagePref(project.chatLanguage);
@@ -209,7 +215,8 @@ async function ensureProjectLanguagePreferences(st) {
         if (project.contentLanguage !== contentLanguage || project.chatLanguage !== chatLanguage) {
             project.contentLanguage = contentLanguage;
             project.chatLanguage = chatLanguage;
-            await st.saveProject(project);
+            if (persist)
+                await st.saveProject(project);
         }
         return project;
     }
@@ -217,7 +224,8 @@ async function ensureProjectLanguagePreferences(st) {
         const fallback = contentLanguage || chatLanguage;
         project.contentLanguage = contentLanguage || fallback;
         project.chatLanguage = chatLanguage || fallback;
-        await st.saveProject(project);
+        if (persist)
+            await st.saveProject(project);
         return project;
     }
     return project;
@@ -296,7 +304,8 @@ async function buildHandoffMarkdown(st, reason, overrides) {
     const latestTaskUpdate = [...allTasks].sort((left, right) => right.task.updatedAt.localeCompare(left.task.updatedAt))[0] ?? null;
     const latestPhaseUpdate = [...plan.phases].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0] ?? null;
     const latestFeatureUpdate = [...plan.features.features].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0] ?? null;
-    const currentPhase = plan.phases.find((phase) => phase.id === resume.currentPhaseId)
+    const currentPhase = (overrides?.phaseId ? plan.phases.find((phase) => phase.id === overrides.phaseId) : undefined)
+        ?? plan.phases.find((phase) => phase.id === resume.currentPhaseId)
         ?? plan.phases.find((phase) => phase.tasks.some((task) => resume.inProgressTaskIds.includes(task.id)))
         ?? plan.phases.find((phase) => phase.status === "in-progress")
         ?? nonTerminalTasks[0]?.phase
@@ -653,6 +662,9 @@ async function startServer(ctx, requestedPort, visibility = "lan") {
         return;
     const host = visibility === "lan" ? "0.0.0.0" : "127.0.0.1";
     const port = await pickProjectPort(ctx, requestedPort);
+    // A started server must be reflected in the next context block; the cache
+    // may hold a stale "Web UI: not running" block from a stop+prompt pair.
+    contextBlockDirty = true;
     try {
         server = await serve({
             port,
@@ -665,26 +677,26 @@ async function startServer(ctx, requestedPort, visibility = "lan") {
         });
     }
     catch (e) {
-        // EADDRINUSE or other listen failure: retry on a random free port.
-        if (e instanceof Error && /EADDRINUSE|EACCES|EADDRNOTAVAIL/.test(e.message)) {
-            try {
-                server = await serve({
-                    port: 0,
-                    host,
-                    planRoot: resolvePlanRoot(ctx.cwd),
-                    staticDir: resolveStaticDir(),
-                    quiet: true,
-                    uiConfig: readUiConfig(ctx),
-                    isBusy: () => planBusy,
-                });
-                ctx.ui.notify(`Planner web server: port ${port} busy (another planner instance on this project?), started on ${server?.url ?? "?"} instead.`, "info");
-            }
-            catch (e2) {
-                ctx.ui.notify(`Failed to start web server (also retry failed): ${e2 instanceof Error ? e2.message : String(e2)}`, "error");
-            }
+        // Any listen failure at startup is potentially transient — EADDRINUSE from
+        // a racy port scan (another process grabbed the port between our check and
+        // bind), EMFILE/ENFILE under heavy load, EAGAIN, etc. Retry ONCE on a random
+        // free port (port 0) so a planner load never silently ends up with no server.
+        // serve() throws here only during startup binding/serving setup; if the retry
+        // also fails, surface the error to the user.
+        try {
+            server = await serve({
+                port: 0,
+                host,
+                planRoot: resolvePlanRoot(ctx.cwd),
+                staticDir: resolveStaticDir(),
+                quiet: true,
+                uiConfig: readUiConfig(ctx),
+                isBusy: () => planBusy,
+            });
+            ctx.ui.notify(`Planner web server: port ${port} unavailable (${e instanceof Error ? e.message : String(e)}), started on ${server?.url ?? "?"} instead.`, "info");
         }
-        else {
-            ctx.ui.notify(`Failed to start web server: ${e instanceof Error ? e.message : String(e)}`, "error");
+        catch (e2) {
+            ctx.ui.notify(`Failed to start web server (also retry failed): ${e2 instanceof Error ? e2.message : String(e2)}`, "error");
         }
     }
     if (server) {
@@ -717,12 +729,26 @@ async function startServer(ctx, requestedPort, visibility = "lan") {
         catch { }
     }
 }
+function disablePlannerSession() {
+    plannerSessionEnabled = false;
+    startupResumePromptPending = false;
+    startupResumeSummaryPending = false;
+    startupResumeSummaryText = "";
+    if (startupResumeSummaryTimer)
+        clearTimeout(startupResumeSummaryTimer);
+    startupResumeSummaryTimer = null;
+    contextBlockCache = "";
+    contextBlockDirty = true;
+}
 async function stopServer() {
     if (server) {
         await server.close();
         server = null;
     }
     capturedPi?.appendEntry("plan-web-state", { running: false });
+    // The cached context block embeds the web UI address; after stop it must
+    // not keep claiming the dashboard is running (T241 — context invalidation).
+    contextBlockDirty = true;
 }
 // ─── Extension factory ──────────────────────────────────────────────────
 export default function planPiExtension(pi) {
@@ -741,6 +767,9 @@ export default function planPiExtension(pi) {
                     }
                     const argPrefix = match[2];
                     const prefix = argPrefix === undefined ? match[1] : argPrefix;
+                    if (argPrefix !== undefined && hasPlannerCommandArgument(argPrefix)) {
+                        return null;
+                    }
                     const normalized = (argPrefix ?? "").trimStart().toLowerCase();
                     const items = PLANNER_COMMAND_COMPLETIONS
                         .filter((item) => !normalized || item.value.startsWith(normalized))
@@ -965,8 +994,45 @@ export default function planPiExtension(pi) {
     });
     // ── Commands ───────────────────────────────────────────────────────
     // ── Planner handler (reusable from multiple commands) ──────────
+    const plannerInteractionCancelled = Symbol("planner-interaction-cancelled");
+    /**
+     * Pi returns `undefined` when Escape closes an input/editor/select. Treat
+     * that as a transaction-wide cancellation, not as an omitted optional
+     * field: interactive planner commands must never keep prompting or write a
+     * partial edit after Escape.
+     */
+    function withCancellablePlannerUi(ctx) {
+        const cancellableCtx = Object.create(ctx);
+        const ui = new Proxy(ctx.ui, {
+            get(target, property, receiver) {
+                const member = Reflect.get(target, property, receiver);
+                if (typeof member !== "function")
+                    return member;
+                if (property === "input" || property === "editor" || property === "select") {
+                    return async (...args) => {
+                        const result = await member.apply(target, args);
+                        if (result === undefined || result === null)
+                            throw plannerInteractionCancelled;
+                        return result;
+                    };
+                }
+                return member.bind(target);
+            },
+        });
+        Object.defineProperty(cancellableCtx, "ui", { value: ui, enumerable: true });
+        return cancellableCtx;
+    }
     async function handlePlanner(args, ctx) {
-        await withPlanBusy(() => runPlanner(args, ctx));
+        try {
+            await withPlanBusy(() => runPlanner(args, withCancellablePlannerUi(ctx)));
+        }
+        catch (error) {
+            if (error === plannerInteractionCancelled) {
+                ctx.ui.notify("Cancelled — no changes saved.", "info");
+                return;
+            }
+            throw error;
+        }
     }
     async function runPlanner(args, ctx) {
         const parts = args.trim().split(/\s+/).filter(Boolean);
@@ -1012,7 +1078,7 @@ export default function planPiExtension(pi) {
         ];
         const SUB_HELP = "Available: init, show, repair, cleanup-orphans, project, feature, phase, task, discuss, handoff, web, export, export-full, bypass, clear-bypass, load, stop\n" +
             "Try: /planner <TAB>  |  /planner feature list  |  /planner task start  |  /planner cleanup-orphans\n" +
-            "Handoff actions: /planner handoff list | show [P00x] | write [P00x] | clear [P00x] | prepare";
+            "Handoff actions: /planner handoff list | show P00x | write P00x | clear P00x | prepare (prepare proposes a target and asks for confirmation)";
         if (!a) {
             const action = await ctx.ui.select("Planner action", PLANNER_MENU_ACTIONS);
             if (!action) {
@@ -1032,6 +1098,14 @@ export default function planPiExtension(pi) {
                     return;
                 }
                 const oldProject = await st.loadProject();
+                // Collect the replacement metadata before deleting the existing plan;
+                // Escape must leave the old project intact.
+                const name = await ctx.ui.input(`Project title [${oldProject.name}]`);
+                if (!name?.trim()) {
+                    ctx.ui.notify("Aborted", "warning");
+                    return;
+                }
+                const description = await ctx.ui.input(`Short project description [${oldProject.description || ""}]`);
                 ctx.ui.notify("Resetting project... all current plan data will be lost.", "warning");
                 if (server) {
                     ctx.ui.notify("Stopping active web server...", "info");
@@ -1039,12 +1113,6 @@ export default function planPiExtension(pi) {
                     server = null;
                 }
                 await rm(st.root, { recursive: true, force: true });
-                const name = await ctx.ui.input(`Project title [${oldProject.name}]`);
-                if (!name?.trim()) {
-                    ctx.ui.notify("Aborted", "warning");
-                    return;
-                }
-                const description = await ctx.ui.input(`Short project description [${oldProject.description || ""}]`);
                 await st.init(name.trim());
                 const project = await st.loadProject();
                 project.description = description?.trim() ?? oldProject.description;
@@ -1195,23 +1263,6 @@ export default function planPiExtension(pi) {
                 return { ok: false, error: `Ambiguous feature ref: ${raw}. Matches: ${partialName.map((feature) => formatFeatureRef(feature.number)).join(", ")}. Use a specific F00x, shortId, or UUID.` };
             return { ok: false, error: `Feature not found: ${raw}` };
         }
-        function findPhaseByRef(phases, ref) {
-            const normalized = ref.trim().toLowerCase();
-            if (!normalized)
-                return null;
-            const pMatch = normalized.match(/^p(\d+)$/);
-            if (pMatch) {
-                const n = parseInt(pMatch[1], 10);
-                const byNum = phases.find((p) => p.number === n);
-                if (byNum)
-                    return byNum;
-            }
-            return phases.find((phase) => phase.shortId && phase.shortId.toLowerCase() === normalized)
-                ?? phases.find((phase) => phase.id.toLowerCase() === normalized)
-                ?? phases.find((phase) => phase.title.toLowerCase() === normalized)
-                ?? phases.find((phase) => phase.title.toLowerCase().includes(normalized))
-                ?? null;
-        }
         function profile_packageManager(pkg, lockfile) {
             if (pkg?.packageManager)
                 return pkg.packageManager;
@@ -1225,7 +1276,7 @@ export default function planPiExtension(pi) {
                 return "npm";
             return "";
         }
-        async function scanCodebase() {
+        async function scanCodebase(persist = true) {
             const root = ctx.cwd;
             const rootFiles = [];
             const directories = [];
@@ -1307,7 +1358,8 @@ export default function planPiExtension(pi) {
                 tree,
                 ambient,
             };
-            await st.saveCodebaseProfile(profile);
+            if (persist)
+                await st.saveCodebaseProfile(profile);
             return profile;
         }
         // ═══════════════════════════════════════════════════════════════
@@ -1319,8 +1371,8 @@ export default function planPiExtension(pi) {
                 return;
             }
             if (b === "discuss") {
-                const project = await ensureProjectLanguagePreferences(st);
-                const profile = await scanCodebase();
+                const project = await ensureProjectLanguagePreferences(st, false);
+                const profile = await scanCodebase(false);
                 ctx.ui.notify(`Codebase scanned: ${profile.directories.length} dirs, ${profile.rootFiles.length} root files${profile.packageJson?.name ? `, pkg ${profile.packageJson.name}` : ""}.`, "info");
                 ctx.ui.notify("Opening text editors for the initial project profile. These will serve as the foundation for the agent's deep discovery process.", "info");
                 const goal = await ctx.ui.editor("Project goal: What is the main, single-focus objective of this project?", project.goal || "");
@@ -1347,6 +1399,7 @@ export default function planPiExtension(pi) {
                         : project.acceptedDecisions,
                 };
                 await st.saveProject(draftProject);
+                await st.saveCodebaseProfile(profile);
                 await st.writeGenerated();
                 ctx.ui.notify("Initial profile saved. The agent will now take over as Lead Architect to conduct discovery.", "info");
                 if (capturedPi) {
@@ -1638,6 +1691,10 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify("Phase creation cancelled: no feature selected.", "warning");
                     return;
                 }
+                // This belongs to the creation transaction: Escape before the phase
+                // is persisted cancels the whole command rather than creating a phase
+                // and only then abandoning the follow-up question.
+                const startDiscuss = await ctx.ui.input("Start phase discuss now? Type yes to continue");
                 let phase;
                 await withFeatureLock(feature.id, async () => {
                     const phases = await st.loadAllPhases();
@@ -1671,7 +1728,6 @@ export default function planPiExtension(pi) {
                 if (!phase)
                     return;
                 ctx.ui.notify(`Phase created: ${formatPhaseRef(phase.number, feature.number)} — ${title}${phase.shortId ? ` · ${phase.shortId}` : ""} (feature ${feature.name})`, "info");
-                const startDiscuss = await ctx.ui.input("Start phase discuss now? Type yes to continue");
                 if (isYes(startDiscuss)) {
                     await handlePlanner(`phase discuss ${phase.id}`, ctx);
                 }
@@ -1680,7 +1736,7 @@ export default function planPiExtension(pi) {
             if (b === "discuss") {
                 let phase = null;
                 if (subArgs.trim()) {
-                    phase = findPhaseByRef(await st.loadAllPhases(), subArgs.trim());
+                    phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim()) ?? null;
                 }
                 if (!phase) {
                     phase = await pickPhase();
@@ -1692,9 +1748,6 @@ export default function planPiExtension(pi) {
                 if (phase.status !== "draft" && phase.status !== "discovery" && phase.status !== "planned") {
                     ctx.ui.notify(`Phase is already "${phase.status}". Re-discuss works best on draft/discovery/planned phases.`, "info");
                 }
-                phase.status = "discovery";
-                phase.updatedAt = nowISO();
-                await st.savePhase(phase);
                 ctx.ui.notify(`Discovery for ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}…`, "info");
                 // ── Recap: give full context before planning tasks ──
                 const recapPlan = await st.loadAll();
@@ -1766,7 +1819,7 @@ export default function planPiExtension(pi) {
             if (b === "show") {
                 let phase = null;
                 if (subArgs.trim()) {
-                    phase = await st.loadPhase(subArgs.trim()).catch(() => null);
+                    phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim()) ?? null;
                 }
                 if (!phase) {
                     phase = await pickPhase();
@@ -1792,7 +1845,7 @@ export default function planPiExtension(pi) {
             if (b === "delete") {
                 let phase = null;
                 if (subArgs.trim()) {
-                    phase = await st.loadPhase(subArgs.trim()).catch(() => null);
+                    phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim()) ?? null;
                 }
                 if (!phase) {
                     phase = await pickPhase();
@@ -1814,7 +1867,7 @@ export default function planPiExtension(pi) {
             if (b === "update") {
                 let phase = null;
                 if (subArgs.trim()) {
-                    phase = await st.loadPhase(subArgs.trim()).catch(() => null);
+                    phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim()) ?? null;
                 }
                 if (!phase) {
                     phase = await pickPhase();
@@ -1885,6 +1938,9 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify("Aborted", "warning");
                     return;
                 }
+                // Keep the optional follow-up inside the creation transaction so
+                // Escape can still cancel before a task is persisted.
+                const startDiscuss = await ctx.ui.input("Start task discuss now? Type yes to continue");
                 const shortName = clampSlug(title, 30, `task-${Date.now().toString(36)}`);
                 const taskNum = await st.allocTaskNumber();
                 const taskId = createTaskId();
@@ -1910,7 +1966,6 @@ export default function planPiExtension(pi) {
                 await st.savePhase(phase);
                 await st.writeGenerated();
                 ctx.ui.notify(`Task created: ${taskId} — ${title}`, "info");
-                const startDiscuss = await ctx.ui.input("Start task discuss now? Type yes to continue");
                 if (isYes(startDiscuss)) {
                     await handlePlanner(`task discuss ${taskId}`, ctx);
                 }
@@ -1993,7 +2048,7 @@ export default function planPiExtension(pi) {
             if (b === "delete") {
                 let phase = null;
                 if (subArgs.trim()) {
-                    phase = await st.loadPhase(subArgs.trim()).catch(() => null);
+                    phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim()) ?? null;
                 }
                 if (!phase) {
                     phase = await pickPhase();
@@ -2027,7 +2082,7 @@ export default function planPiExtension(pi) {
             if (b === "update") {
                 let phase = null;
                 if (subArgs.trim()) {
-                    phase = await st.loadPhase(subArgs.trim()).catch(() => null);
+                    phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim()) ?? null;
                 }
                 if (!phase) {
                     phase = await pickPhase();
@@ -2069,6 +2124,7 @@ export default function planPiExtension(pi) {
                 task.updatedAt = now;
                 phase.updatedAt = now;
                 await st.savePhase(phase);
+                await st.syncTaskStatusRollup(phase.id);
                 await st.writeGenerated();
                 ctx.ui.notify(`Task updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (${task.status})${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
                 return;
@@ -2101,17 +2157,9 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify(`Task "${task.title}" is already in-progress.`, "info");
                     return;
                 }
-                // Auto-archive the handoff on THIS task's phase (reason: task-started) —
-                // the agent is now actively working, so the captured context is consumed.
-                // Other phases' handoffs are left untouched (informational, non-blocking).
-                if ((phase.handoff ?? "") !== "") {
-                    await st.clearPhaseHandoff(phase.id, "task-started").catch(() => { });
-                    ctx.ui.notify("📦 Archived handoff for this phase (task started) — recover via /planner handoff list + .planner/.local/handoff-archive/.", "info");
-                }
-                const _otherHandoffs = (await st.listHandoffs()).filter((h) => h.phaseId !== phase.id);
-                if (_otherHandoffs.length > 0) {
-                    ctx.ui.notify(`ℹ️  ${_otherHandoffs.length} other phase handoff(s) pending — review with /planner handoff list if relevant.`, "info");
-                }
+                // A pending handoff is context, not a lock: task start RETAINS it.
+                // It is archived only when the phase completes (auto) or the user
+                // explicitly clears it.
                 const now = nowISO();
                 // Record status change in the incremental statusLog.
                 const prevStatus = task.status;
@@ -2128,6 +2176,7 @@ export default function planPiExtension(pi) {
                 task.updatedAt = now;
                 phase.updatedAt = now;
                 await st.savePhase(phase);
+                await st.syncTaskStatusRollup(phase.id);
                 await st.writeGenerated();
                 ctx.ui.notify(`✅ Task started: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (in-progress)${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
                 return;
@@ -2182,9 +2231,9 @@ export default function planPiExtension(pi) {
                 applyTaskLifecycleDates(task, "done", now);
                 task.updatedAt = now;
                 phase.updatedAt = now;
-                await st.savePhase(phase);
+                const clearedRef = await st.syncTaskStatusRollup(phase.id);
                 await st.writeGenerated();
-                ctx.ui.notify(`✅ Task completed: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (done)${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
+                ctx.ui.notify(`✅ Task completed: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (done)${task.shortId ? ` · ${task.shortId}` : ""}${clearedRef ? ` — phase handoff archived (${clearedRef})` : ""}`, "info");
                 return;
             }
             // checklist-add <T00x> <title>  /  checklist-remove <T00x> <C{n}|title>  /  checklist-toggle <T00x> <C{n}|title> [on|off]
@@ -2301,6 +2350,11 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify("No text provided; nothing written.", "info");
                     return;
                 }
+                const confirmed = await ctx.ui.confirm(`Write this handoff on ${r.compositeRef}?`, "Write handoff");
+                if (!confirmed) {
+                    ctx.ui.notify("Handoff write cancelled.", "info");
+                    return;
+                }
                 await st.setPhaseHandoff(r.phase.id, text);
                 ctx.ui.notify(`Wrote handoff on ${r.compositeRef}`, "info");
                 return;
@@ -2310,24 +2364,17 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify("Agent bridge unavailable; use /planner handoff write for an auto-generated handoff.", "warning");
                     return;
                 }
-                const handoffs = await st.listHandoffs();
-                await capturedPi.sendUserMessage("Prepare the canonical session handoff now and write it on the phase the user explicitly identifies as the one just worked on in this session, using the `handoff_write` tool (entity-scoped, stored on phase.handoff — .planner/HANDOFF.md is deprecated).\n\n" +
-                    "Pass a meaningful `title` summarizing the work (e.g. 'P049 — featureId validation: tests + adapter wiring') — it becomes the H1 / first line in handoff lists. Generic titles like 'Handoff' or 'Canonical handoff' are REJECTED.\n\n" +
-                    "WARNING: Do not default to 'current in-progress phase' or a stale resume pointer. If the user just completed P058, write the handoff on P058 (or its continuation P061), not on P031 just because P031 is marked in-progress or has an existing handoff.\n\n" +
-                    "The handoff MUST be a structured markdown document containing at minimum:\n" +
+                await capturedPi.sendUserMessage("Prepare a canonical session handoff proposal. Do not write anything yet. First identify from this conversation and the latest planner lifecycle events the exact feature and phase where the decisions/work belong. Never use the first in-progress phase or a stale resume pointer as a target.\n\n" +
+                    "If the last phase was just completed, do not create an operational handoff for it; its existing handoff must have been archived by the phase-done lifecycle. If another non-done phase is the real continuation, identify that phase explicitly.\n\n" +
+                    "Before calling `handoff_write`, tell the user exactly: `I propose writing this handoff on P00x(F00x) — <phase title>. Confirm?` Wait for an explicit confirmation. Only after confirmation call `handoff_write` with that exact phaseRef. If the target is ambiguous, ask the user to identify the feature and phase instead of guessing.\n\n" +
+                    "After confirmation, the handoff MUST contain at minimum:\n" +
                     "- `Created at:` and `Updated at:` lines (ISO timestamps)\n" +
                     "- `Reason:` why this handoff is being written\n" +
-                    "- `## Current focus`: the current feature (id + name + status), phase (id + title + status) and task (id + title + status). Derive them from the plan data.\n" +
-                    "- `## What was being done`: a concrete 3–10 line narrative of the work in progress, based on our conversation and the current task notes/description.\n" +
-                    "- `## How to resume`: explicit, ordered steps to pick the work back up (next command / tool / file to open / build to run).\n" +
-                    "- `## Files touched`: explicit file paths modified during this session.\n" +
-                    "- `## Blockers`: any open blockers, or `None recorded`.\n" +
-                    "- `## Next steps`: the immediate next steps.\n" +
-                    "- `## Recent decisions`: accepted decisions made this session, if any.\n" +
-                    "- `## Reminder`: note that when the work is fully resumed, the agent should clear the phase handoff using `handoff_clear`.\n\n" +
-                    "The handoff is stored on the phase.handoff field of the current in-progress phase (entity-scoped). " +
-                    (handoffs.length > 0 ? "A previous phase handoff exists; refresh its `Updated at` and merge/replace stale sections. " : "") +
-                    "Once written, confirm to me with a one-line summary.");
+                    "- `## Current focus`: feature, phase and task refs/titles/statuses derived from the confirmed target\n" +
+                    "- `## What was being done`: the concrete decisions/work from this session\n" +
+                    "- `## How to resume`: explicit ordered steps\n" +
+                    "- `## Files touched`, `## Blockers`, `## Next steps`, and `## Recent decisions`\n" +
+                    "Pass a meaningful title beginning with the confirmed phase ref. Generic titles are rejected. Handoffs are stored on phase.handoff; `.planner/HANDOFF.md` is deprecated.");
                 ctx.ui.notify("Instructing the agent to prepare the phase handoff…", "info");
                 return;
             }
@@ -2396,7 +2443,7 @@ export default function planPiExtension(pi) {
             const m = report.migrated;
             const dup = report.integrity.duplicatePhaseIds.length;
             const dang = report.integrity.danglingPhaseIds.length;
-            ctx.ui.notify(`Repair done: renamed ${m.renamed}, repaired ${m.repaired} refs, inferred ${m.inferred}. Integrity: ${dup} duplicate, ${dang} dangling.`, "info");
+            ctx.ui.notify(`Repair done: renamed ${m.renamed}, repaired ${m.repaired} refs, inferred ${m.inferred}, archived ${report.handoffs.archived} stale handoff(s). Integrity: ${dup} duplicate, ${dang} dangling.`, "info");
             return;
         }
         if (a === "cleanup-orphans") {
@@ -2471,6 +2518,10 @@ export default function planPiExtension(pi) {
                 startupResumeSummaryPending = false;
                 startupResumeSummaryTimer = null;
             }, 60000);
+            // Safety timeout must not keep the Node process alive on its own
+            // (relevant for test hosts that load this entrypoint). Inside Pi the
+            // process is long-lived, so unref is a no-op there.
+            startupResumeSummaryTimer.unref?.();
             // Build the recap and embed it in the trigger content. The trigger
             // message is the channel that reliably reaches the agent on a triggered
             // turn (before_agent_start's systemPrompt injection is NOT applied to
@@ -2495,7 +2546,7 @@ export default function planPiExtension(pi) {
             return;
         }
         if (a === "stop" || a === "disable") {
-            plannerSessionEnabled = false;
+            disablePlannerSession();
             await stopServer().catch(() => { });
             try {
                 capturedPi?.appendEntry("plan-web-state", { running: false });
@@ -2511,6 +2562,11 @@ export default function planPiExtension(pi) {
         description: "Grouped planner command. Use /planner <TAB> for subcommands or /planner to open the menu.",
         getArgumentCompletions: (prefix) => {
             const normalized = prefix.trim().toLowerCase();
+            // Once a complete command path is followed by whitespace, the remaining
+            // text is a free-form human ref/title. Returning the fallback menu here
+            // lets Pi select `init` and replace input such as `feature update F001`.
+            if (hasPlannerCommandArgument(prefix))
+                return null;
             const filtered = PLANNER_COMMAND_COMPLETIONS.filter((item) => item.value.startsWith(normalized));
             return filtered.length > 0 ? filtered : PLANNER_COMMAND_COMPLETIONS;
         },
@@ -2813,6 +2869,7 @@ export default function planPiExtension(pi) {
                 `Repair complete.`,
                 `Migration: renamed=${m.renamed}, repaired=${m.repaired} refs, inferred=${m.inferred}.`,
                 `Containment: ${c.changed} phase file${c.changed === 1 ? "" : "s"} rewritten (tasks regrouped by their own phaseId), ${c.tasks} tasks scanned, ${c.orphan} orphan.`,
+                `Handoffs: archived=${report.handoffs.archived} stale completed/canceled handoff(s).`,
                 `Integrity: duplicatePhaseIds=${report.integrity.duplicatePhaseIds.length}, danglingPhaseIds=${report.integrity.danglingPhaseIds.length}.`,
             ];
             if (report.integrity.danglingPhaseIds.length)
@@ -2873,8 +2930,10 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "plan_write_handoff",
         label: "Plan Write Handoff",
-        description: "DEPRECATED — writes to the entity-scoped phase.handoff (not .planner/HANDOFF.md). Prefer handoff_write. Write or refresh the canonical phase handoff. Capture full design context, not just operational resume steps: pass extraSections with locked decisions, architecture (with file:line refs), mode/state flows, plugin/API contracts, data mappings, files touched, and known gaps so a resuming agent doesn't re-discover decisions already made. IMPORTANT: write the handoff on the phase the user explicitly identifies as the one just worked on in this session; do not default to a stale 'current phase' pointer or an existing handoff on a different phase.",
+        description: "DEPRECATED — writes to the entity-scoped phase.handoff (not .planner/HANDOFF.md). Prefer handoff_write. phaseRef is required and must be the exact phase confirmed with the user; never infer a target from current status or resume pointers. Completed/canceled phases reject new handoffs.",
         parameters: Type.Object({
+            phaseRef: Type.String({ description: "Exact confirmed phase ref: P00x | P00x(F00x) | UUID | title." }),
+            confirmed: Type.Boolean({ description: "Set true only after the user explicitly confirms the proposed feature+phase target." }),
             reason: Type.Optional(Type.String({ description: "Why the handoff is being written" })),
             title: Type.Optional(Type.String({ description: "Meaningful handoff title summarizing the work (becomes the H1 / first line in lists). Example: 'P049 — featureId validation: tests + adapter wiring'." })),
             whatWasBeingDone: Type.Optional(Type.String({ description: "Optional override for the current work summary" })),
@@ -2888,7 +2947,13 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const resolved = await resolvePhaseForHandoff(st, params.phaseRef);
+            if (!resolved.ok)
+                return { content: [{ type: "text", text: `⚠️ plan_write_handoff is deprecated (writes to phase.handoff, not .planner/HANDOFF.md). ${resolved.error}` }], details: { deprecated: true, error: resolved.error } };
+            if (!params.confirmed)
+                return { content: [{ type: "text", text: `Proposal only: I would write this handoff on ${resolved.compositeRef}. Ask the user to confirm this exact feature/phase, then retry with confirmed=true.` }], details: { deprecated: true, phaseRef: resolved.compositeRef, confirmationRequired: true } };
             const markdown = await buildHandoffMarkdown(st, params.reason?.trim() || "manual tool handoff", {
+                phaseId: resolved.phase.id,
                 ...(params.title?.trim() ? { title: params.title.trim() } : {}),
                 ...(params.whatWasBeingDone?.trim() ? { whatWasBeingDone: params.whatWasBeingDone.trim() } : {}),
                 ...(params.howToResume?.trim() ? { howToResume: params.howToResume.trim() } : {}),
@@ -2900,23 +2965,20 @@ export default function planPiExtension(pi) {
                     }
                     : {}),
             });
-            const r = await resolvePhaseForHandoff(st, undefined);
-            if (!r.ok)
-                return { content: [{ type: "text", text: `⚠️ plan_write_handoff is deprecated (writes to phase.handoff, not .planner/HANDOFF.md). ${r.error}` }], details: { deprecated: true, error: r.error } };
-            await st.setPhaseHandoff(r.phase.id, markdown);
-            return { content: [{ type: "text", text: `⚠️ plan_write_handoff is deprecated — wrote handoff on ${r.compositeRef} (phase.handoff field) instead of .planner/HANDOFF.md. Prefer the handoff_write tool.` }], details: { deprecated: true, phaseRef: r.compositeRef, phaseId: r.phase.id } };
+            await st.setPhaseHandoff(resolved.phase.id, markdown);
+            return { content: [{ type: "text", text: `⚠️ plan_write_handoff is deprecated — wrote handoff on ${resolved.compositeRef} (phase.handoff field) instead of .planner/HANDOFF.md. Prefer the handoff_write tool.` }], details: { deprecated: true, phaseRef: resolved.compositeRef, phaseId: resolved.phase.id } };
         },
     });
     pi.registerTool({
         name: "plan_delete_handoff",
         label: "Plan Delete Handoff",
-        description: "DEPRECATED — clears the entity-scoped handoff of the current in-progress phase. Prefer handoff_clear.",
-        parameters: Type.Object({}),
-        async execute(_id, _params, _signal, _onUpdate, ctx) {
+        description: "DEPRECATED — clears/archives the entity-scoped handoff of a phase. phaseRef is required. Prefer handoff_clear.",
+        parameters: Type.Object({ phaseRef: Type.String({ description: "Exact phase ref: P00x | P00x(F00x) | UUID | title." }) }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            const r = await resolvePhaseForHandoff(st, undefined);
+            const r = await resolvePhaseForHandoff(st, params.phaseRef);
             if (!r.ok)
                 return { content: [{ type: "text", text: `⚠️ plan_delete_handoff is deprecated — use handoff_clear. ${r.error}` }], details: { deprecated: true, error: r.error } };
             await st.clearPhaseHandoff(r.phase.id, "manual");
@@ -2924,11 +2986,8 @@ export default function planPiExtension(pi) {
         },
     });
     // Resolve a phase for entity-scoped handoff tools. ref = P00x | P00x(F00x) |
-    // UUID | title; omitted -> current in-progress phase (phase.status, or the
-    // phase containing an in-progress task). Returns the phase + its composite ref.
-    // NOTE: callers must NOT treat the resolved phase as a directive; it is a
-    // fallback pointer that may be stale if the agent worked on a different
-    // workstream in this session.
+    // UUID | title. A write target is always explicit: never guess from the
+    // first in-progress phase or a stale resume pointer.
     async function resolvePhaseForHandoff(st, ref) {
         const phases = await st.loadAllPhases();
         const features = (await st.loadFeatures()).features;
@@ -2936,16 +2995,12 @@ export default function planPiExtension(pi) {
         if (ref && ref.trim()) {
             phase = findPhaseByRef(phases, features, ref.trim());
         }
-        else {
-            phase = phases.find((p) => p.status === "in-progress")
-                ?? phases.find((p) => p.tasks.some((t) => t.status === "in-progress"));
-        }
         if (!phase) {
             return {
                 ok: false,
                 error: ref && ref.trim()
                     ? `Phase not found: "${ref.trim()}". Use P00x, P00x(F00x), UUID, or title.`
-                    : "No in-progress phase. Specify a phaseRef (P00x or P00x(F00x)).",
+                    : "A phaseRef is required. First identify the exact feature and phase with the user, then pass P00x or P00x(F00x).",
             };
         }
         const feat = phase.featureId ? features.find((f) => f.id === phase.featureId) : undefined;
@@ -2970,8 +3025,8 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "handoff_show",
         label: "Handoff Show",
-        description: "Read the entity-scoped handoff of a phase. phaseRef accepts P00x, P00x(F00x), UUID, or title. Omit to target the current in-progress phase.",
-        parameters: Type.Object({ phaseRef: Type.Optional(Type.String({ description: "Phase ref: P00x | P00x(F00x) | UUID | title. Default: current in-progress phase." })) }),
+        description: "Read the entity-scoped handoff of a phase. phaseRef is required and accepts P00x, P00x(F00x), UUID, or title. Never infer a phase automatically.",
+        parameters: Type.Object({ phaseRef: Type.String({ description: "Exact phase ref: P00x | P00x(F00x) | UUID | title. Ask the user when the target is ambiguous." }) }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
@@ -2988,10 +3043,11 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "handoff_write",
         label: "Handoff Write",
-        description: "Write/refresh the entity-scoped handoff on a phase. Pass content (or markdown_content) AND a meaningful `title` summarizing the work (e.g. 'P049 — featureId validation: tests + adapter wiring'). The title becomes the H1 and the first line shown in handoff lists; generic titles like 'Handoff' or 'Canonical handoff' are REJECTED. phaseRef optional (default: current in-progress phase). IMPORTANT: defaulting to 'current in-progress phase' is a fallback only; write the handoff on the phase the user explicitly identifies as the one just worked on in this session, and do not update an existing handoff on a different phase unless the user confirms.",
+        description: "Write/refresh the entity-scoped handoff on a phase. phaseRef is required and must be the exact phase selected with the user. Pass content (or markdown_content) AND a meaningful `title` summarizing the work (e.g. 'P049 — featureId validation: tests + adapter wiring'). Never guess the phase from in-progress status or stale context. Completed/canceled phases reject new handoffs.",
         parameters: Type.Object({
-            phaseRef: Type.Optional(Type.String({ description: "Phase ref. Default: current in-progress phase." })),
+            phaseRef: Type.String({ description: "Exact confirmed phase ref: P00x | P00x(F00x) | UUID | title." }),
             title: Type.Optional(Type.String({ description: "Meaningful handoff title summarizing the work (becomes the H1 / first line in lists). REQUIRED if your markdown's first heading is generic. Example: 'P049 — featureId validation: tests + adapter wiring'." })),
+            confirmed: Type.Boolean({ description: "Set true only after the user explicitly confirms the proposed feature+phase target." }),
             content: Type.Optional(Type.String({ description: "Handoff text (plain)." })),
             markdown_content: Type.Optional(Type.String({ description: "Handoff text (markdown). Preferred over content." })),
         }),
@@ -3028,6 +3084,9 @@ export default function planPiExtension(pi) {
             const r = await resolvePhaseForHandoff(st, params.phaseRef);
             if (!r.ok)
                 return { content: [{ type: "text", text: `❌ ${r.error}` }], details: { error: r.error } };
+            if (!params.confirmed) {
+                return { content: [{ type: "text", text: `Proposal only: I would write this handoff on ${r.compositeRef}. Ask the user to confirm this exact feature/phase, then retry with confirmed=true.` }], details: { phaseRef: r.compositeRef, confirmationRequired: true } };
+            }
             await st.setPhaseHandoff(r.phase.id, body);
             return { content: [{ type: "text", text: `✅ Wrote handoff on ${r.compositeRef}.` }], details: { phaseRef: r.compositeRef, phaseId: r.phase.id } };
         },
@@ -3035,8 +3094,8 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "handoff_clear",
         label: "Handoff Clear",
-        description: "Clear the entity-scoped handoff of a phase (sets handoff to empty, keeps handoffUpdatedAt as an audit trail). phaseRef optional (default: current in-progress phase).",
-        parameters: Type.Object({ phaseRef: Type.Optional(Type.String({ description: "Phase ref. Default: current in-progress phase." })) }),
+        description: "Clear the entity-scoped handoff of a phase (archives it and keeps handoffUpdatedAt as an audit trail). phaseRef is required; never infer a phase automatically.",
+        parameters: Type.Object({ phaseRef: Type.String({ description: "Exact phase ref: P00x | P00x(F00x) | UUID | title." }) }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
@@ -3102,7 +3161,7 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "feature_get",
         label: "Feature Get",
-        description: "Show a feature. Compact identity by default (saves tokens); pass full=true to include the description.",
+        description: "Show a feature. Compact identity by default (saves tokens); pass full=true to include the description and derived linked requirements.",
         parameters: Type.Object({
             featureId: Type.String({ description: "Feature ref: F00x, shortId, UUID, or name" }),
             full: Type.Optional(Type.Boolean({ description: "If true, include the feature description. Default: compact identity only." })),
@@ -3113,12 +3172,17 @@ export default function planPiExtension(pi) {
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const features = (await st.loadFeatures()).features;
             const ref = params.featureId.trim();
-            const feature = features.find((f) => formatFeatureRef(f.number) === ref || f.shortId === ref || f.id === ref || f.name.toLowerCase() === ref.toLowerCase());
-            if (!feature)
-                return { content: [{ type: "text", text: `Feature not found: ${ref}` }], details: {} };
+            const resolvedFeature = resolveFeatureRefStrict(features, ref);
+            if (!resolvedFeature.ok)
+                return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
+            const feature = resolvedFeature.feature;
             const phases = (await st.loadAllPhases()).filter((p) => p.featureId === feature.id);
-            const summary = `${feature.name} — ${formatFeatureRef(feature.number)}${feature.shortId ? ` · ${feature.shortId}` : ""} (${feature.status}; ${phases.length} phases)`;
-            return { content: [{ type: "text", text: params.full ? `${summary}\n\n${feature.description || ""}` : summary }], details: {} };
+            const linkedRequirements = await st.linkedRequirementsForFeature(feature.id);
+            const summary = `${feature.name} — ${formatFeatureRef(feature.number)}${feature.shortId ? ` · ${feature.shortId}` : ""} (${feature.status}; ${phases.length} phases${linkedRequirements.length ? `; ${linkedRequirements.length} linked requirement${linkedRequirements.length === 1 ? "" : "s"}` : ""})`;
+            const requirementsBlock = linkedRequirements.length > 0
+                ? `\n\nLinked requirements:\n${linkedRequirements.map((requirement) => `- ${requirement.title} (${requirement.status})`).join("\n")}`
+                : "\n\nLinked requirements:\n- None linked to this feature.";
+            return { content: [{ type: "text", text: params.full ? `${summary}\n\n${feature.description || ""}${requirementsBlock}` : summary }], details: { linkedRequirements } };
         },
     });
     pi.registerTool({
@@ -3248,6 +3312,27 @@ export default function planPiExtension(pi) {
             if (!resolvedFeature.ok)
                 return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
             const featureId = resolvedFeature.feature.id;
+            const mutableFields = [
+                "name",
+                "description",
+                "status",
+                "startDate",
+                "endDate",
+                "workDone",
+                "workRemaining",
+                "priority",
+                "acceptedDecisions",
+            ];
+            const receivedFields = mutableFields.filter((field) => params[field] !== undefined);
+            if (receivedFields.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Not updated — no mutable fields were received. No planner data was changed. If you attempted a large description, it may have exceeded the tool payload limit.",
+                        }],
+                    details: { updated: false, reason: "no-mutable-fields" },
+                };
+            }
             let foundDoc;
             try {
                 foundDoc = await st.updateFeatures((doc) => {
@@ -3293,7 +3378,13 @@ export default function planPiExtension(pi) {
             if (!feature)
                 return { content: [{ type: "text", text: `Feature not found: ${params.featureId}` }], details: {} };
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `✅ Feature updated: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}` }], details: feature };
+            return {
+                content: [{
+                        type: "text",
+                        text: `✅ Feature updated: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.`,
+                    }],
+                details: { ...feature, updated: true, updatedFields: receivedFields },
+            };
         },
     });
     pi.registerTool({
@@ -3563,6 +3654,77 @@ export default function planPiExtension(pi) {
             return { content: [{ type: "text", text: `✅ Phase updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, phaseUpdateFeatures))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}` }], details: phase };
         },
     });
+    pi.registerTool({
+        name: "decision_record",
+        label: "Decision Record",
+        description: "Record a user-agreed decision on both a feature and one of its phases. This is planner metadata work, not a code edit. The decision is appended without overwriting existing history.",
+        parameters: Type.Object({
+            featureId: Type.String({ description: "Parent feature ref: F00x, shortId, UUID, or name" }),
+            phaseId: Type.String({ description: "Active phase ref: P00x, shortId, UUID, or title" }),
+            title: Type.String({ minLength: 1, description: "Short human-readable decision title" }),
+            decision: Type.String({ minLength: 1, description: "The agreed decision" }),
+            rationale: Type.String({ minLength: 1, description: "Why the decision was made" }),
+            implementationNotes: Type.String({ minLength: 1, description: "Concrete follow-up or preservation notes" }),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const features = (await st.loadFeatures()).features;
+            const resolvedFeature = resolveFeatureRefStrict(features, params.featureId);
+            if (!resolvedFeature.ok)
+                return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
+            const resolvedPhase = findPhaseByRef(await st.loadAllPhases(), features, params.phaseId);
+            if (!resolvedPhase)
+                return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
+            if (resolvedPhase.featureId !== resolvedFeature.feature.id) {
+                return { content: [{ type: "text", text: `Phase ${formatPhaseRef(resolvedPhase.number, featureNumberOfPhase(resolvedPhase, features))} does not belong to feature ${formatFeatureRef(resolvedFeature.feature.number)}.` }], details: {} };
+            }
+            const acceptedAt = nowISO();
+            const acceptedDecision = {
+                id: crypto.randomUUID(),
+                title: params.title.trim(),
+                decision: params.decision.trim(),
+                rationale: params.rationale.trim(),
+                implementationNotes: params.implementationNotes.trim(),
+                acceptedAt,
+            };
+            await withFeatureLock(resolvedFeature.feature.id, async () => {
+                let featureWritten = false;
+                try {
+                    await st.updateFeatures((doc) => {
+                        const feature = doc.features.find((entry) => entry.id === resolvedFeature.feature.id);
+                        if (!feature)
+                            throw new Error(`Resolved feature no longer exists: ${resolvedFeature.feature.id}`);
+                        feature.acceptedDecisions = [...(feature.acceptedDecisions ?? []), acceptedDecision];
+                        feature.updatedAt = acceptedAt;
+                        return doc;
+                    });
+                    featureWritten = true;
+                    await st.updatePhase(resolvedPhase.id, (phase) => {
+                        phase.acceptedDecisions = [...(phase.acceptedDecisions ?? []), acceptedDecision];
+                        phase.updatedAt = acceptedAt;
+                        return phase;
+                    });
+                }
+                catch (error) {
+                    // Best-effort compensation keeps a failed dual-write from reporting
+                    // success with a decision persisted only on the feature.
+                    if (featureWritten) {
+                        await st.updateFeatures((doc) => {
+                            const feature = doc.features.find((entry) => entry.id === resolvedFeature.feature.id);
+                            if (feature)
+                                feature.acceptedDecisions = (feature.acceptedDecisions ?? []).filter((entry) => entry.id !== acceptedDecision.id);
+                            return doc;
+                        }).catch(() => { });
+                    }
+                    throw error;
+                }
+            });
+            await st.writeGenerated();
+            return { content: [{ type: "text", text: `✅ Decision recorded on ${formatFeatureRef(resolvedFeature.feature.number)} and ${formatPhaseRef(resolvedPhase.number, resolvedFeature.feature.number)}: ${acceptedDecision.title}` }], details: acceptedDecision };
+        },
+    });
     pi.registerTool({
         name: "phase_delete",
         label: "Phase Delete",
@@ -3780,6 +3942,19 @@ export default function planPiExtension(pi) {
             const hostPhase = found.phase;
             const now = nowISO();
             let updatedTask;
+            // Validate the motivation requirement for restrictive status transitions,
+            // mirroring the MCP adapter and the /planner task update command
+            // (AGENTS.md rule 8 — rejected writes must leave the files unchanged).
+            if (params.status !== undefined &&
+                params.status !== found.task.status &&
+                needsMotivation(found.task.status, params.status)) {
+                if (!params.motivation || !params.motivation.trim()) {
+                    return {
+                        content: [{ type: "text", text: `Status transition "${found.task.status} → ${params.status}" requires a motivation. Provide the "motivation" parameter with a detailed explanation of why this change is needed.` }],
+                        details: {},
+                    };
+                }
+            }
             try {
                 const updatedPhase = await st.updatePhase(hostPhase.id, (phase) => {
                     const task = phase.tasks.find((t) => t.id === found.task.id);
@@ -3830,6 +4005,7 @@ export default function planPiExtension(pi) {
             }
             if (!updatedTask)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
+            await st.syncTaskStatusRollup(found.phase.id);
             await st.writeGenerated();
             return { content: [{ type: "text", text: `Task updated: ${updatedTask.id} (${updatedTask.status})` }], details: updatedTask };
         },
@@ -3860,10 +4036,65 @@ export default function planPiExtension(pi) {
         },
     });
     // ── task start / complete tools ──────────────────────────────────
+    pi.registerTool({
+        name: "task_recommend",
+        label: "Task Recommend",
+        description: "Return the recommended next task without starting work: continue one active task, otherwise choose ready work by feature → phase → task priority. Reports approved deviation/resume context and never blocks an explicit user choice.",
+        parameters: Type.Object({}),
+        async execute(_id, _params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const [features, phases, project] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject()]);
+            const result = recommendNextTask(features.features, phases, project.workDeviations);
+            if (!result.candidate)
+                return { content: [{ type: "text", text: `No task recommendation: ${result.reason}` }], details: result };
+            const { candidate } = result;
+            const reference = `${formatPhaseRef(candidate.phase.number, featureNumberOfPhase(candidate.phase, features.features))}/T${String(candidate.task.number).padStart(3, "0")}`;
+            return {
+                content: [{ type: "text", text: `Recommended (${result.kind}): ${reference} — ${candidate.task.title}\n${result.reason}${result.deviation ? `\nDeviation: ${result.deviation.id}; resume target ${result.deviation.resumeTaskId}.` : ""}` }],
+                details: result,
+            };
+        },
+    });
+    pi.registerTool({
+        name: "task_deviation",
+        label: "Task Deviation",
+        description: "Record a user-approved temporary task deviation. It preserves the recommended/resume task but never starts, pauses, or blocks work; use normal task lifecycle tools for those transitions.",
+        parameters: Type.Object({
+            temporary_task: Type.String({ description: "Temporary task ref" }),
+            resume_task: Type.Optional(Type.String({ description: "Task to resume; defaults to the current recommendation" })),
+            reason: Type.String({ description: "Why this approved temporary deviation is needed" }),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const [features, phases, project] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject()]);
+            const temporary = findTaskByRef(phases, features.features, params.temporary_task.trim());
+            if (!temporary)
+                return { content: [{ type: "text", text: `Task not found: ${params.temporary_task}` }], details: {} };
+            const selected = recommendNextTask(features.features, phases, project.workDeviations);
+            const resume = params.resume_task ? findTaskByRef(phases, features.features, params.resume_task.trim()) : selected.candidate;
+            if (!resume)
+                return { content: [{ type: "text", text: `No resume task is available. Provide resume_task explicitly. ${selected.reason}` }], details: selected };
+            if (temporary.task.id === resume.task.id)
+                return { content: [{ type: "text", text: "A temporary task must differ from its resume target." }], details: {} };
+            if (temporary.task.status !== "planned")
+                return { content: [{ type: "text", text: `Temporary task is not startable: ${temporary.task.status}.` }], details: {} };
+            const timestamp = nowISO();
+            const record = { id: crypto.randomUUID(), recommendedTaskId: selected.candidate?.task.id ?? resume.task.id, temporaryTaskId: temporary.task.id, resumeTaskId: resume.task.id, reason: params.reason, requestedBy: "user", approvedBy: "user", state: "approved", createdAt: timestamp, activatedAt: "", resolvedAt: "" };
+            await st.addWorkDeviation(record);
+            await st.writeGenerated();
+            const tempRef = `${formatPhaseRef(temporary.phase.number, featureNumberOfPhase(temporary.phase, features.features))}/T${String(temporary.task.number).padStart(3, "0")}`;
+            const resumeRef = `${formatPhaseRef(resume.phase.number, featureNumberOfPhase(resume.phase, features.features))}/T${String(resume.task.number).padStart(3, "0")}`;
+            return { content: [{ type: "text", text: `✅ Approved deviation: ${tempRef} temporarily overrides ${resumeRef}. Resume target retained.` }], details: { deviation: record } };
+        },
+    });
     pi.registerTool({
         name: "task_start",
         label: "Task Start",
-        description: "Set a task to in-progress. Use this BEFORE starting implementation work on any task. Sets startedAt timestamp automatically.",
+        description: "Set a task to in-progress. BEFORE calling, read feature_get(full=true) for the parent feature and its linked requirements, then phase_get(full=true) for the parent phase and its linked requirements, then task_get(full=true). Continue an already in-progress task; otherwise select ready work by feature → phase → task priority (lower number first), respecting dependencies and blocked/waiting states. Sets startedAt automatically and returns the ordered feature/phase requirements briefing.",
         parameters: Type.Object({
             taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title to start" }),
         }),
@@ -3880,6 +4111,27 @@ export default function planPiExtension(pi) {
                 return { content: [{ type: "text", text: `Task ${task.id} is already in-progress.` }], details: task };
             if (task.status === "done")
                 return { content: [{ type: "text", text: `Task ${task.id} is done. Use task_update to reopen.` }], details: task };
+            const project = await st.loadProject();
+            const phases = await st.loadAllPhases();
+            const eligibility = checkExplicitTaskStart(features, phases, task.id, project.workDeviations);
+            if (!eligibility.eligible)
+                return { content: [{ type: "text", text: `Task start denied: ${eligibility.reason}` }], details: eligibility };
+            const selection = recommendNextTask(features, phases, project.workDeviations);
+            // Assemble the mandatory parent context before changing task lifecycle state.
+            // The output order is feature + its requirements, then phase + its requirements.
+            const parentFeature = found.phase.featureId ? features.find((f) => f.id === found.phase.featureId) : undefined;
+            const [phaseWithRequirements, featureRequirements] = await Promise.all([
+                st.loadPhaseWithRequirements(found.phase.id),
+                parentFeature ? st.linkedRequirementsForFeature(parentFeature.id) : Promise.resolve([]),
+            ]);
+            const phaseContext = buildPhaseContextBlock(phaseWithRequirements, parentFeature, phaseWithRequirements.linkedRequirements ?? [], featureRequirements);
+            const advisory = selection.kind === "conflict"
+                ? `\n\n⚠️ ${selection.reason} Explicit task request honored; reconcile active work before relying on automatic recommendations.`
+                : selection.candidate && selection.candidate.task.id !== task.id
+                    ? selection.kind === "active"
+                        ? `\n\n⚠️ Active-task advisory: ${formatPhaseRef(selection.candidate.phase.number, featureNumberOfPhase(selection.candidate.phase, features))}/T${String(selection.candidate.task.number).padStart(3, "0")} is already in progress. Explicit task request honored.`
+                        : `\n\n⚠️ Priority advisory: ${formatPhaseRef(selection.candidate.phase.number, featureNumberOfPhase(selection.candidate.phase, features))}/T${String(selection.candidate.task.number).padStart(3, "0")} is the automatic recommendation. Explicit task request honored.`
+                    : "";
             const now = nowISO();
             let startedTask;
             await st.updatePhase(found.phase.id, (phase) => {
@@ -3892,12 +4144,14 @@ export default function planPiExtension(pi) {
                 startedTask = t;
                 return phase;
             });
+            await st.syncTaskStatusRollup(found.phase.id);
+            const approvedDeviation = project.workDeviations.find((deviation) => deviation.temporaryTaskId === task.id && deviation.state === "approved");
+            if (approvedDeviation)
+                await st.setWorkDeviationState(approvedDeviation.id, "active", now);
             await st.writeGenerated();
             if (!startedTask)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
-            const parentFeature = found.phase.featureId ? features.find((f) => f.id === found.phase.featureId) : undefined;
-            const phaseContext = buildPhaseContextBlock(found.phase, parentFeature);
-            return { content: [{ type: "text", text: `✅ Task started: ${startedTask.id} — ${startedTask.title} (in-progress)${phaseContext}` }], details: startedTask };
+            return { content: [{ type: "text", text: `✅ Task started: ${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${String(startedTask.number).padStart(3, "0")} — ${startedTask.title} (in-progress)${startedTask.shortId ? ` · ${startedTask.shortId}` : ""}${phaseContext}${advisory}` }], details: startedTask };
         },
     });
     pi.registerTool({
@@ -3943,10 +4197,16 @@ export default function planPiExtension(pi) {
                 completedTask = t;
                 return phase;
             });
+            const clearedRef = await st.syncTaskStatusRollup(found.phase.id);
+            const completedDeviation = (await st.loadProject()).workDeviations
+                .filter((deviation) => (deviation.state === "approved" || deviation.state === "active") && deviation.temporaryTaskId === task.id)
+                .sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0];
+            if (completedDeviation)
+                await st.setWorkDeviationState(completedDeviation.id, "resolved", now);
             await st.writeGenerated();
             if (!completedTask)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
-            return { content: [{ type: "text", text: `✅ Task completed: ${completedTask.id} — ${completedTask.title} (done)` }], details: completedTask };
+            return { content: [{ type: "text", text: `✅ Task completed: ${completedTask.id} — ${completedTask.title} (done)${clearedRef ? ` — phase handoff archived (${clearedRef})` : ""}` }], details: completedTask };
         },
     });
     pi.registerTool({
@@ -4142,7 +4402,7 @@ export default function planPiExtension(pi) {
         description: "Disable the planner for this project and stop the web dashboard. Alias: planner-disable. Planner operations are NOT code edits.",
         parameters: Type.Object({}),
         async execute(_id, _params, _signal, _onUpdate, _ctx) {
-            plannerSessionEnabled = false;
+            disablePlannerSession();
             await stopServer().catch(() => { });
             try {
                 capturedPi?.appendEntry("plan-web-state", { running: false });
@@ -4313,10 +4573,11 @@ export default function planPiExtension(pi) {
                 "",
                 "Operational rules:",
                 "- Handoffs are context, not locks. Read the relevant handoff with handoff show <ref> before resuming.",
-                "- BEFORE any code edit/write: task_start. AFTER finishing a task: task_complete.",
+                "- BEFORE work: read feature_get(full=true) for the parent feature and its linked requirements, then phase_get(full=true) for the parent phase and its linked requirements, then task_get(full=true); only then call task_start before any code edit/write. AFTER finishing a task: task_complete.",
+                "- Record every new decision or user-agreed modification in both the relevant feature and phase before treating the discussion as complete.",
                 "- Use task_update with motivation for blocked/canceled/rejected/deferred/waiting/planned(from non-planned).",
                 "- Planner ops (status/handoff/planner metadata) are NOT code edits; they are always allowed.",
-                "- Prefer shortId or F00x/P00x/T00x refs. Find via feature_list / phase_list / task_list; read one entity via *_get(full=true).",
+                "- Prioritize work: continue an in-progress task; otherwise choose ready work feature → phase → task by ascending priority, respecting dependencies and blocked/waiting states. Prefer shortId or F00x/P00x/T00x refs. Find via feature_list / phase_list / task_list; read one entity via *_get(full=true).",
                 "- If edit/write guard blocks you, start the right task or use an explicit bypass.",
                 "",
                 `Goal: ${project.goal || "(not set)"}`,