@agent-plan/pi-adapter 0.2.20 → 0.2.22-next.0

package/dist/index.js

@@ -9,7 +9,8 @@
  *  - inject context into prompts
  */
 import { Type } from "typebox";
-import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, buildPhaseContextBlock, checkExplicitTaskStart, recommendNextTask } from "@agent-plan/core";
+import { paginatedSelect, paginatedNotify } from "./ui/paginate.js";
+import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, buildPhaseContextBlock, checkExplicitTaskStart, recommendNextTask, buildResumeRequiredProposal, packageVersionFromModule, resolvedPackageVersion, markFeatureRead, markPhaseRead, markTaskRead, hasReadParents, parentReadAdvisory, hasReadRequirements, requirementReadAdvisory, markRequirementRead, invalidateReads } from "@agent-plan/core";
 import { createChecklistItemId, createFeatureId, createPhaseId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, featureNumberOfPhase, validateResolvedTarget } from "@agent-plan/core/naming";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
@@ -21,6 +22,9 @@ import { serve } from "@agent-plan/server/serve";
 // ─── State (module-level) ───────────────────────────────────────────────
 const PI_CONFIG_DIR_NAME = ".pi";
 const PLAN_DIR_NAME = ".planner";
+const PI_ADAPTER_PACKAGE = packageVersionFromModule(import.meta.url, "@agent-plan/pi-adapter");
+const CORE_PACKAGE = resolvedPackageVersion("@agent-plan/core", import.meta.url);
+const SERVER_PACKAGE = resolvedPackageVersion("@agent-plan/server", import.meta.url);
 let capturedPi = null;
 let store = null;
 let server = null;
@@ -104,6 +108,7 @@ const healedStatusRoots = new Set();
 const PLANNER_COMMAND_COMPLETIONS = [
     { value: "init", label: "init", description: "Initialize planner in this project" },
     { value: "show", label: "show", description: "Show planner overview" },
+    { value: "version", label: "version", description: "Show loaded Agent Plan package versions" },
     { value: "repair", label: "repair", description: "Repair planner integrity" },
     { value: "cleanup-orphans", label: "cleanup-orphans", description: "List and remove orphan phase files" },
     { value: "project discuss", label: "project discuss", description: "Run project discovery" },
@@ -239,10 +244,11 @@ async function getPlannerExecutionGuard(st) {
         ? allTasks.find(({ task }) => task.id === resume.inProgressTaskIds[0])
         : undefined;
     const focusFromCurrentPhase = resume?.currentPhaseId
-        ? allTasks.find(({ phase, task }) => phase.id === resume.currentPhaseId && task.status !== "done" && task.status !== "canceled")
+        ? allTasks.find(({ phase, task }) => phase.id === resume.currentPhaseId && task.status !== "done" && task.status !== "canceled" && task.status !== "rejected")
         : undefined;
-    const fallbackFocus = allTasks.find(({ task }) => task.status === "planned" || task.status === "blocked")
-        ?? allTasks.find(({ task }) => task.status !== "done" && task.status !== "canceled");
+    const fallbackFocus = allTasks.find(({ task }) => task.pauseSnapshot)
+        ?? allTasks.find(({ task }) => task.status === "planned" || task.status === "blocked" || task.status === "waiting")
+        ?? allTasks.find(({ task }) => task.status !== "done" && task.status !== "canceled" && task.status !== "rejected");
     const focus = focusFromResume ?? focusFromCurrentPhase ?? fallbackFocus;
     return {
         totalTasks,
@@ -313,7 +319,8 @@ async function buildHandoffMarkdown(st, reason, overrides) {
         ?? null;
     const currentTask = currentPhase?.tasks.find((task) => resume.inProgressTaskIds.includes(task.id))
         ?? currentPhase?.tasks.find((task) => task.status === "in-progress")
-        ?? [...(currentPhase?.tasks ?? [])].filter((task) => task.status !== "done" && task.status !== "canceled").sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0]
+        ?? currentPhase?.tasks.find((task) => task.pauseSnapshot)
+        ?? [...(currentPhase?.tasks ?? [])].filter((task) => task.status !== "done" && task.status !== "canceled" && task.status !== "rejected").sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0]
         ?? latestTaskUpdate?.task
         ?? null;
     const currentFeature = currentPhase?.featureId
@@ -551,6 +558,7 @@ function statusIcon(status) {
     const icons = {
         draft: "📄", discovery: "🔍", planned: "📋",
         "in-progress": "🚧", done: "✅", blocked: "🚫", canceled: "❌",
+        rejected: "❌", deferred: "⏳", waiting: "⏱️",
     };
     return icons[status] ?? "❓";
 }
@@ -622,10 +630,32 @@ function resolveStaticDir() {
         const adapterDir = dirname(adapterFile);
         // When installed as Pi package: node_modules/@agent-plan/pi-adapter/web-ui-dist/
         const pkgWebUi = join(adapterDir, "..", "web-ui-dist");
-        if (existsSync(pkgWebUi))
-            return pkgWebUi;
-        // Fallback: monorepo dev — packages/plan-web-ui/dist/
-        return join(adapterDir, "..", "..", "plan-web-ui", "dist");
+        // Monorepo dev: packages/plan-web-ui/dist/ (rebuilt by `pnpm build:web-ui`)
+        const devWebUi = join(adapterDir, "..", "..", "plan-web-ui", "dist");
+        const candidates = [pkgWebUi, devWebUi].filter((d) => {
+            try {
+                return existsSync(join(d, "index.html"));
+            }
+            catch {
+                return false;
+            }
+        });
+        if (candidates.length === 0)
+            return undefined;
+        if (candidates.length === 1)
+            return candidates[0];
+        // Prefer the most recently built bundle so a fresh `pnpm build:web-ui`
+        // (or copy-web-ui.sh) is picked up in dev instead of a stale vendored
+        // snapshot. Deterministic: compare index.html mtimes, newest wins.
+        const mtime = (d) => {
+            try {
+                return statSync(join(d, "index.html")).mtimeMs;
+            }
+            catch {
+                return 0;
+            }
+        };
+        return [...candidates].sort((a, b) => mtime(b) - mtime(a))[0];
     }
     catch {
         return undefined;
@@ -1041,6 +1071,7 @@ export default function planPiExtension(pi) {
         const PLANNER_MENU_ACTIONS = [
             "init",
             "show",
+            "version",
             "repair",
             "cleanup-orphans",
             "project discuss",
@@ -1076,7 +1107,7 @@ export default function planPiExtension(pi) {
             "load",
             "stop",
         ];
-        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" +
+        const SUB_HELP = "Available: init, show, version, 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 (prepare proposes a target and asks for confirmation)";
         if (!a) {
@@ -1088,6 +1119,15 @@ export default function planPiExtension(pi) {
             await runPlanner(action, ctx);
             return;
         }
+        if (a === "version") {
+            ctx.ui.notify([
+                "Agent Plan runtime versions",
+                `${PI_ADAPTER_PACKAGE.name}: ${PI_ADAPTER_PACKAGE.version}`,
+                `${CORE_PACKAGE.name}: ${CORE_PACKAGE.version}`,
+                `${SERVER_PACKAGE.name}: ${SERVER_PACKAGE.version}`,
+            ].join("\n"), "info");
+            return;
+        }
         const st = ensureStore(ctx);
         // ── init ──
         if (a === "init") {
@@ -1168,12 +1208,12 @@ export default function planPiExtension(pi) {
                 .sort((a, b) => a.number - b.number);
             if (features.length === 0)
                 return null;
-            const options = features.map((f) => `  ${formatFeatureRef(f.number)} ${statusIcon(f.status)} ${f.name}${f.shortId ? ` · ${f.shortId}` : ""}`);
-            const chosen = await ctx.ui.select("Pick a feature", options);
-            if (chosen == null)
-                return null;
-            const idx = options.indexOf(chosen);
-            return idx >= 0 ? features[idx] : null;
+            return paginatedSelect(ctx, {
+                title: "Pick a feature",
+                items: features,
+                render: (f) => `  ${formatFeatureRef(f.number)} ${statusIcon(f.status)} ${f.name}${f.shortId ? ` · ${f.shortId}` : ""}`,
+                pageSize: 10,
+            });
         }
         // ═══════════════════════════════════════════════════════════════
         //  Helper: pick a phase interactively
@@ -1184,12 +1224,12 @@ export default function planPiExtension(pi) {
                 return null;
             }
             const features = (await st.loadFeatures().catch(() => ({ features: [] }))).features;
-            const options = phases.map((p) => `  ${formatPhaseRef(p.number, featureNumberOfPhase(p, features))} ${statusIcon(p.status)} ${p.title}${p.shortId ? ` · ${p.shortId}` : ""}`);
-            const chosen = await ctx.ui.select("Pick a phase", options);
-            if (chosen == null)
-                return null;
-            const idx = options.indexOf(chosen);
-            return idx >= 0 ? phases[idx] : null;
+            return paginatedSelect(ctx, {
+                title: "Pick a phase",
+                items: phases,
+                render: (p) => `  ${formatPhaseRef(p.number, featureNumberOfPhase(p, features))} ${statusIcon(p.status)} ${p.title}${p.shortId ? ` · ${p.shortId}` : ""}`,
+                pageSize: 10,
+            });
         }
         // ═══════════════════════════════════════════════════════════════
         //  Helper: pick a task interactively from a phase
@@ -1198,12 +1238,12 @@ export default function planPiExtension(pi) {
             if (phase.tasks.length === 0)
                 return null;
             const tasks = phase.tasks.slice().sort((a, b) => a.number - b.number);
-            const options = tasks.map((t) => `  T${String(t.number).padStart(3, "0")} ${statusIcon(t.status)} ${t.title}${t.shortId ? ` · ${t.shortId}` : ""}`);
-            const chosen = await ctx.ui.select(`Pick a task from "${phase.title}"`, options);
-            if (chosen == null)
-                return null;
-            const idx = options.indexOf(chosen);
-            return idx >= 0 ? tasks[idx] : null;
+            return paginatedSelect(ctx, {
+                title: `Pick a task from "${phase.title}"`,
+                items: tasks,
+                render: (t) => `  T${String(t.number).padStart(3, "0")} ${statusIcon(t.status)} ${t.title}${t.shortId ? ` · ${t.shortId}` : ""}`,
+                pageSize: 10,
+            });
         }
         function parseMultilineList(value) {
             return (value ?? "")
@@ -1447,11 +1487,12 @@ export default function planPiExtension(pi) {
                     return;
                 }
                 const phases = await st.loadAllPhases();
-                ctx.ui.notify(features.map((feature) => {
+                const lines = features.map((feature) => {
                     const featurePhases = phases.filter((phase) => phase.featureId === feature.id);
                     const taskCount = featurePhases.reduce((total, phase) => total + phase.tasks.length, 0);
                     return `${statusIcon(feature.status)} ${feature.name} (${feature.id}) — ${featurePhases.length} phases, ${taskCount} tasks`;
-                }).join("\n"), "info");
+                });
+                await paginatedNotify(ctx, { title: "features", lines, pageSize: 10 });
                 return;
             }
             if (b === "add") {
@@ -1957,6 +1998,7 @@ export default function planPiExtension(pi) {
                     acceptedDecisions: [],
                     checklist: [], subtasks: [],
                     dependsOn: [],
+                    pauseSnapshot: null, pauseHistory: [],
                     startedAt: "", completedAt: "",
                     createdAt: now, updatedAt: now,
                 };
@@ -2153,6 +2195,18 @@ export default function planPiExtension(pi) {
                         return;
                     }
                 }
+                if (phase && !hasReadParents(phase.featureId, phase.id)) {
+                    ctx.ui.notify("⚠️ READ REQUIRED before proceeding: read the parent feature and phase (full=true) for this task before starting it.", "warning");
+                }
+                if (phase) {
+                    const linkedRequirementIds = [
+                        ...(await st.linkedRequirementsForPhase(phase.id)).map((r) => r.id),
+                        ...(phase.featureId ? (await st.linkedRequirementsForFeature(phase.featureId)).map((r) => r.id) : []),
+                    ];
+                    if (linkedRequirementIds.length > 0 && !hasReadRequirements(linkedRequirementIds)) {
+                        ctx.ui.notify("⚠️ REQUIREMENTS READ REQUIRED: read the requirements linked to this phase (and feature) before starting the task.", "warning");
+                    }
+                }
                 if (task.status === "in-progress") {
                     ctx.ui.notify(`Task "${task.title}" is already in-progress.`, "info");
                     return;
@@ -2326,7 +2380,11 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify("No phase handoffs set.", "info");
                     return;
                 }
-                ctx.ui.notify(list.map((e) => `• ${e.compositeRef} — ${e.firstLine} (updated ${e.updatedAt})`).join("\n"), "info");
+                await paginatedNotify(ctx, {
+                    title: "phase handoffs",
+                    lines: list.map((e) => `• ${e.compositeRef} — ${e.firstLine} (updated ${e.updatedAt})`),
+                    pageSize: 10,
+                });
                 return;
             }
             if (action === "show") {
@@ -2732,6 +2790,7 @@ export default function planPiExtension(pi) {
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const requirements = await st.loadRequirements();
+            requirements.requirements.forEach((req) => markRequirementRead(req.id));
             return {
                 content: [{ type: "text", text: requirements.requirements.map((req) => `- ${req.id} — ${req.title} (${req.status})`).join("\n") || "No requirements" }],
                 details: requirements,
@@ -2752,15 +2811,21 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const title = params.title?.trim();
+            if (!title)
+                return { content: [{ type: "text", text: "title required" }], details: {} };
+            const links = await resolveRequirementPhaseRefs(st, params.linkedPhaseIds);
+            if (!links.ok)
+                return { content: [{ type: "text", text: links.error }], details: {} };
             const requirements = await st.loadRequirements();
             const now = nowISO();
             const requirement = {
                 id: createRequirementId(),
-                title: params.title.trim(),
+                title,
                 description: params.description?.trim() ?? "",
                 status: params.status?.trim() ?? "planned",
                 macroTasks: [],
-                linkedPhaseIds: (params.linkedPhaseIds ?? []).map((entry) => entry.trim()).filter(Boolean),
+                linkedPhaseIds: links.linkedPhaseIds,
                 createdAt: now,
                 updatedAt: now,
             };
@@ -2789,14 +2854,22 @@ export default function planPiExtension(pi) {
             const requirement = requirements.requirements.find((entry) => entry.id === params.requirementId);
             if (!requirement)
                 return { content: [{ type: "text", text: `Requirement not found: ${params.requirementId}` }], details: {} };
-            if (params.title !== undefined)
-                requirement.title = params.title.trim();
+            if (params.title !== undefined) {
+                const title = params.title.trim();
+                if (!title)
+                    return { content: [{ type: "text", text: "title required" }], details: {} };
+                requirement.title = title;
+            }
             if (params.description !== undefined)
                 requirement.description = params.description.trim();
             if (params.status !== undefined)
                 requirement.status = params.status.trim();
-            if (params.linkedPhaseIds !== undefined)
-                requirement.linkedPhaseIds = params.linkedPhaseIds.map((entry) => entry.trim()).filter(Boolean);
+            if (params.linkedPhaseIds !== undefined) {
+                const links = await resolveRequirementPhaseRefs(st, params.linkedPhaseIds);
+                if (!links.ok)
+                    return { content: [{ type: "text", text: links.error }], details: {} };
+                requirement.linkedPhaseIds = links.linkedPhaseIds;
+            }
             requirement.updatedAt = nowISO();
             await st.saveRequirements(requirements);
             await st.writeGenerated();
@@ -3006,6 +3079,23 @@ export default function planPiExtension(pi) {
         const feat = phase.featureId ? features.find((f) => f.id === phase.featureId) : undefined;
         return { ok: true, phase, compositeRef: formatPhaseRef(phase.number, feat?.number) };
     }
+    async function resolveRequirementPhaseRefs(st, refs) {
+        if (!Array.isArray(refs) || refs.length === 0) {
+            return { ok: false, error: "linkedPhaseIds must contain at least one phase" };
+        }
+        const trimmed = refs.map((entry) => entry.trim()).filter(Boolean);
+        if (trimmed.length === 0) {
+            return { ok: false, error: "linkedPhaseIds must contain non-empty phase references" };
+        }
+        const phases = await st.loadAllPhases();
+        const features = (await st.loadFeatures()).features;
+        const resolved = trimmed.map((ref) => findPhaseByRef(phases, features, ref));
+        const missingIndex = resolved.findIndex((phase) => !phase);
+        if (missingIndex !== -1) {
+            return { ok: false, error: `linked phase not found: ${trimmed[missingIndex]}` };
+        }
+        return { ok: true, linkedPhaseIds: [...new Set(resolved.map((phase) => phase.id))] };
+    }
     pi.registerTool({
         name: "handoff_list",
         label: "Handoff List",
@@ -3062,11 +3152,13 @@ export default function planPiExtension(pi) {
             // Derive the current first non-empty line (H1) of the supplied body.
             const firstLine = body.split(/\r?\n/).find((l) => l.trim().length > 0) ?? "";
             const firstHeadingText = firstLine.replace(/^#+\s*/, "").trim();
-            const isGeneric = !firstHeadingText || /^(handoff|canonical handoff|session handoff)$/i.test(firstHeadingText);
-            if (!title && isGeneric) {
+            const genericTitlePattern = /^(handoff|canonical handoff|session handoff)$/i;
+            const effectiveHeadingText = (title && title.length > 0) ? title : firstHeadingText;
+            const isGeneric = !effectiveHeadingText || genericTitlePattern.test(effectiveHeadingText);
+            if (isGeneric) {
                 return {
                     content: [{ type: "text", text: "❌ Generic handoff title. Provide a meaningful `title` (or start your markdown with a descriptive H1) summarizing the work — e.g. 'P049 — featureId validation: tests + adapter wiring'. Generic titles like 'Handoff' or 'Canonical handoff' are not accepted." }],
-                    details: { error: "generic title", firstHeadingText },
+                    details: { error: "generic title", firstHeadingText: effectiveHeadingText || firstHeadingText },
                 };
             }
             // Normalize: if a title is provided, replace or prepend the H1 so the first line is the title.
@@ -3176,6 +3268,7 @@ export default function planPiExtension(pi) {
             if (!resolvedFeature.ok)
                 return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
             const feature = resolvedFeature.feature;
+            markFeatureRead(feature.id);
             const phases = (await st.loadAllPhases()).filter((p) => p.featureId === feature.id);
             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"}` : ""})`;
@@ -3474,6 +3567,7 @@ export default function planPiExtension(pi) {
             const phase = findPhaseByRef(await st.loadAllPhases(), features, params.phaseId.trim());
             if (!phase)
                 return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
+            markPhaseRead(phase.id, phase.featureId);
             const linkedRequirements = await st.linkedRequirementsForPhase(phase.id);
             const reqCount = linkedRequirements.length;
             const summary = `${phase.title} — ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}${phase.shortId ? ` · ${phase.shortId}` : ""} (${phase.status}; ${phase.tasks.length} tasks${reqCount ? `; ${reqCount} linked requirement${reqCount === 1 ? "" : "s"}` : ""})`;
@@ -3498,6 +3592,9 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const title = params.title?.trim();
+            if (!title)
+                return { content: [{ type: "text", text: "title required" }], details: {} };
             if (!params.featureId?.trim())
                 return { content: [{ type: "text", text: "featureId is required: a phase must belong to a feature." }], details: {} };
             const createPhaseFeatures = (await st.loadFeatures()).features;
@@ -3518,7 +3615,7 @@ export default function planPiExtension(pi) {
                 const priority = await st.nextPriority("phase", featureId);
                 const now = nowISO();
                 phase = {
-                    id, number: identity.number, shortId: identity.shortId, priority, slug: normalizeSlug(params.title), title: params.title,
+                    id, number: identity.number, shortId: identity.shortId, priority, slug: normalizeSlug(title), title,
                     featureId,
                     status: params.status ?? "draft",
                     discussedAt: "",
@@ -3808,10 +3905,10 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "task_get",
         label: "Task Get",
-        description: "Show a task. Compact identity by default (saves tokens); pass full=true to include the description + statusLog.",
+        description: "Show a task. Compact identity by default (saves tokens); pass full=true to include the description, resume checkpoint/advisory, and statusLog.",
         parameters: Type.Object({
             taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title" }),
-            full: Type.Optional(Type.Boolean({ description: "If true, include the task description + statusLog. Default: compact identity only." })),
+            full: Type.Optional(Type.Boolean({ description: "If true, include the task description, resume checkpoint/advisory, and statusLog. Default: compact identity only." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -3821,11 +3918,36 @@ export default function planPiExtension(pi) {
             const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId.trim());
             if (!found)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
+            markTaskRead(found.task.id, found.phase.id, found.phase.featureId);
             const summary = `${found.task.title} — ${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${pad(found.task.number)}${found.task.shortId ? ` · ${found.task.shortId}` : ""} (${found.task.status})`;
             if (!params.full)
                 return { content: [{ type: "text", text: summary }], details: {} };
+            const project = await st.loadProject();
+            const pendingDeviation = found.task.status === "done" || found.task.status === "canceled" || found.task.status === "rejected"
+                ? undefined
+                : project.workDeviations
+                    .filter((deviation) => deviation.resumeTaskId === found.task.id
+                    && (deviation.state === "resume-required" || deviation.state === "resolved"))
+                    .sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0];
+            const snapshot = found.task.pauseSnapshot ?? pendingDeviation?.snapshot ?? null;
             const log = (found.task.statusLog ?? []).map((e) => `  - ${e.date.slice(0, 10)} ${e.title}`).join("\n");
-            return { content: [{ type: "text", text: `${summary}\n\n${found.task.description || ""}${log ? `\n\nStatus log:\n${log}` : ""}` }], details: {} };
+            const sections = [summary];
+            if (found.task.description?.trim())
+                sections.push(found.task.description.trim());
+            if (snapshot || pendingDeviation) {
+                sections.push([
+                    pendingDeviation
+                        ? "Resume advisory: this task has a saved checkpoint that should be evaluated before selecting other work."
+                        : "Resume checkpoint:",
+                    snapshot ? `Checkpoint reason: ${snapshot.reason}` : "",
+                    snapshot ? `Work checkpoint: ${snapshot.whatWasBeingDone}` : "",
+                    snapshot ? `Resume from: ${snapshot.resumeLocation}` : "",
+                    snapshot ? `How to resume: ${snapshot.howToResume}` : "",
+                ].filter(Boolean).join("\n"));
+            }
+            if (log)
+                sections.push(`Status log:\n${log}`);
+            return { content: [{ type: "text", text: sections.join("\n\n") }], details: {} };
         },
     });
     pi.registerTool({
@@ -3845,6 +3967,9 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const title = params.title?.trim();
+            if (!title)
+                return { content: [{ type: "text", text: "title required" }], details: {} };
             if (!params.featureId?.trim())
                 return { content: [{ type: "text", text: "featureId is required: a task must belong to a feature." }], details: {} };
             const features = (await st.loadFeatures()).features;
@@ -3871,15 +3996,18 @@ export default function planPiExtension(pi) {
             const existingPhase = await st.loadPhase(phaseId);
             if (!existingPhase)
                 return { content: [{ type: "text", text: `Resolved phase ${phaseId} no longer exists. Refusing to create task.` }], details: {} };
-            const shortName = clampSlug(params.shortName ?? params.title, 30, `task-${Date.now().toString(36)}`); // clamp+strip trailing dash; never empty
+            const shortName = clampSlug(params.shortName ?? title, 30, `task-${Date.now().toString(36)}`); // clamp+strip trailing dash; never empty
             const taskId = createTaskId();
             const identity = await st.allocateEntityIdentity("task", taskId);
             const priority = await st.nextPriority("task", phaseId);
             const now = nowISO();
             const initialStatus = params.status ?? "planned";
+            if (initialStatus === "paused") {
+                return { content: [{ type: "text", text: "A task cannot be created paused without an in-progress checkpoint. Create it planned, then use task_pause/task_switch." }], details: {} };
+            }
             const task = {
                 id: taskId, phaseId, number: identity.number, shortId: identity.shortId, priority, shortName,
-                title: params.title,
+                title,
                 status: initialStatus,
                 description: params.description ?? "",
                 descriptionUpdatedAt: now,
@@ -3892,6 +4020,8 @@ export default function planPiExtension(pi) {
                     : [],
                 subtasks: [],
                 dependsOn: [],
+                pauseSnapshot: null,
+                pauseHistory: [],
                 startedAt: initialStatus === "in-progress" || initialStatus === "done" ? now : "",
                 completedAt: initialStatus === "done" ? now : "",
                 createdAt: now, updatedAt: now,
@@ -3947,6 +4077,12 @@ export default function planPiExtension(pi) {
             // 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 (found.task.pauseSnapshot && params.status === "in-progress" && params.status !== found.task.status) {
+                return {
+                    content: [{ type: "text", text: "Resume checkpoint lifecycle transitions require task_start so the checkpoint and return stack remain consistent." }],
+                    details: {},
+                };
+            }
             if (params.status !== undefined &&
                 params.status !== found.task.status &&
                 needsMotivation(found.task.status, params.status)) {
@@ -4085,7 +4221,12 @@ export default function planPiExtension(pi) {
             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: "" };
+            const record = {
+                id: crypto.randomUUID(), recommendedTaskId: selected.candidate?.task.id ?? resume.task.id,
+                temporaryTaskId: temporary.task.id, resumeTaskId: resume.task.id, reason: params.reason, snapshot: null,
+                requestedBy: "user", approvedBy: "user", state: "approved",
+                createdAt: timestamp, activatedAt: "", resumeRequiredAt: "", resolvedAt: "", resumedAt: "",
+            };
             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")}`;
@@ -4093,10 +4234,206 @@ export default function planPiExtension(pi) {
             return { content: [{ type: "text", text: `✅ Approved deviation: ${tempRef} temporarily overrides ${resumeRef}. Resume target retained.` }], details: { deviation: record } };
         },
     });
+    pi.registerTool({
+        name: "task_pause",
+        label: "Task Pause",
+        description: "Pause an in-progress task with a mandatory durable checkpoint: why work stopped, what was underway, the exact resume location, and how to continue.",
+        parameters: Type.Object({
+            taskId: Type.String({ description: "Task ref to pause" }),
+            reason: Type.String({ description: "Why work is being paused" }),
+            what_was_being_done: Type.String({ description: "Concrete work underway at the checkpoint" }),
+            resume_location: Type.String({ description: "Exact file, symbol, command, or location from which to continue" }),
+            how_to_resume: Type.String({ description: "Actionable instructions for resuming" }),
+            paused_by: Type.Optional(Type.String({ description: "Agent/session identifier" })),
+        }),
+        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 found = findTaskByRef(await st.loadAllPhases(), features, params.taskId.trim());
+            if (!found)
+                return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
+            if (found.task.status !== "in-progress")
+                return { content: [{ type: "text", text: `Task pause denied: task is ${found.task.status}, not in-progress.` }], details: found.task };
+            const snapshot = {
+                id: crypto.randomUUID(), reason: params.reason.trim(), whatWasBeingDone: params.what_was_being_done.trim(),
+                resumeLocation: params.resume_location.trim(), howToResume: params.how_to_resume.trim(), relatedTaskId: "",
+                pausedAt: nowISO(), pausedBy: params.paused_by?.trim() ?? "",
+            };
+            invalidateReads();
+            const checkpointed = await st.pauseTask(found.phase.id, found.task.id, snapshot);
+            await st.syncTaskStatusRollup(found.phase.id);
+            const activeDeviation = (await st.loadProject()).workDeviations
+                .filter((deviation) => (deviation.state === "approved" || deviation.state === "active")
+                && deviation.temporaryTaskId === found.task.id)
+                .sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0];
+            if (activeDeviation)
+                await st.setWorkDeviationState(activeDeviation.id, "resume-required", snapshot.pausedAt);
+            const resume = activeDeviation
+                ? findTaskByRef(await st.loadAllPhases(), features, activeDeviation.resumeTaskId)
+                : undefined;
+            await st.writeGenerated();
+            const reference = `${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${String(checkpointed.number).padStart(3, "0")}`;
+            const resumeRef = resume
+                ? `${formatPhaseRef(resume.phase.number, featureNumberOfPhase(resume.phase, features))}/T${String(resume.task.number).padStart(3, "0")}`
+                : "";
+            return {
+                content: [{ type: "text", text: [
+                            `💾 Resume checkpoint saved: ${reference} — ${checkpointed.title}`,
+                            `Why: ${snapshot.reason}`,
+                            `Checkpoint: ${snapshot.whatWasBeingDone}`,
+                            `Resume from: ${snapshot.resumeLocation}`,
+                            `How to resume: ${snapshot.howToResume}`,
+                            resume ? `↩️ RESUME REQUIRED: ${resumeRef} — ${resume.task.title}` : "",
+                        ].filter(Boolean).join("\n") }],
+                details: { task: checkpointed, snapshot, ...(resume ? { resumeRequired: { taskId: resume.task.id } } : {}) },
+            };
+        },
+    });
+    pi.registerTool({
+        name: "task_switch",
+        label: "Task Switch",
+        description: "Switch from active work to a temporary task, even outside priority order. Atomically snapshots/pauses the source, starts the target, and pushes a durable LIFO return target.",
+        parameters: Type.Object({
+            from_task: Type.String({ description: "Currently in-progress task ref" }),
+            to_task: Type.String({ description: "Temporary task ref to start" }),
+            reason: Type.String({ description: "Why this temporary switch is necessary" }),
+            what_was_being_done: Type.String({ description: "Concrete work underway in the source task" }),
+            resume_location: Type.String({ description: "Exact source resume location" }),
+            how_to_resume: Type.String({ description: "Actionable source resume instructions" }),
+            switched_by: Type.Optional(Type.String({ description: "Agent/session identifier" })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const [featuresDoc, phases, project] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject()]);
+            const features = featuresDoc.features;
+            const source = findTaskByRef(phases, features, params.from_task.trim());
+            const target = findTaskByRef(phases, features, params.to_task.trim());
+            if (!source)
+                return { content: [{ type: "text", text: `Task not found: ${params.from_task}` }], details: {} };
+            if (!target)
+                return { content: [{ type: "text", text: `Task not found: ${params.to_task}` }], details: {} };
+            if (source.task.id === target.task.id)
+                return { content: [{ type: "text", text: "Source and temporary task must differ." }], details: {} };
+            if (source.task.status !== "in-progress" && !source.task.pauseSnapshot) {
+                return { content: [{ type: "text", text: `Task switch denied: source is ${source.task.status}; only in-progress or checkpointed work can be switched.` }], details: {} };
+            }
+            const eligibility = checkExplicitTaskStart(features, phases, target.task.id, project.workDeviations);
+            if (!eligibility.eligible)
+                return { content: [{ type: "text", text: `Task switch denied: ${eligibility.reason}` }], details: eligibility };
+            const timestamp = nowISO();
+            const snapshot = {
+                id: crypto.randomUUID(), reason: params.reason.trim(), whatWasBeingDone: params.what_was_being_done.trim(),
+                resumeLocation: params.resume_location.trim(), howToResume: params.how_to_resume.trim(),
+                relatedTaskId: target.task.id, pausedAt: timestamp, pausedBy: params.switched_by?.trim() ?? "",
+            };
+            const selection = recommendNextTask(features, phases, project.workDeviations);
+            const record = {
+                id: crypto.randomUUID(), recommendedTaskId: selection.candidate?.task.id ?? source.task.id,
+                temporaryTaskId: target.task.id, resumeTaskId: source.task.id, reason: snapshot.reason, snapshot,
+                requestedBy: "agent", approvedBy: params.switched_by?.trim() || "explicit task_switch",
+                state: "active", createdAt: timestamp, activatedAt: timestamp,
+                resumeRequiredAt: "", resolvedAt: "", resumedAt: "",
+            };
+            const sourceWasActive = source.task.status === "in-progress";
+            let sourceCheckpointed = false;
+            let targetStarted = false;
+            try {
+                if (sourceWasActive) {
+                    await st.pauseTask(source.phase.id, source.task.id, snapshot);
+                }
+                else {
+                    await st.updatePhase(source.phase.id, (phase) => {
+                        const task = phase.tasks.find((entry) => entry.id === source.task.id);
+                        if (!task)
+                            throw new Error(`Checkpointed source task disappeared: ${params.from_task}`);
+                        task.pauseSnapshot = snapshot;
+                        task.pauseHistory = [...task.pauseHistory, snapshot];
+                        task.updatedAt = timestamp;
+                        return phase;
+                    });
+                }
+                sourceCheckpointed = true;
+                if (target.task.pauseSnapshot) {
+                    await st.resumeTask(target.phase.id, target.task.id, timestamp);
+                }
+                else {
+                    await st.updatePhase(target.phase.id, (phase) => {
+                        const task = phase.tasks.find((entry) => entry.id === target.task.id);
+                        if (!task)
+                            throw new Error(`Temporary task disappeared: ${params.to_task}`);
+                        const previousStatus = task.status;
+                        applyTaskLifecycleDates(task, "in-progress", timestamp);
+                        task.statusLog = [...task.statusLog, {
+                                id: createChecklistItemId(task.id, task.statusLog.length + 1, `${previousStatus}-in-progress`),
+                                date: timestamp, fromStatus: previousStatus, toStatus: "in-progress",
+                                title: `${previousStatus} → in-progress`, description: `Temporary switch from ${source.task.title}.`,
+                            }];
+                        task.updatedAt = timestamp;
+                        phase.updatedAt = timestamp;
+                        return phase;
+                    });
+                }
+                targetStarted = true;
+                await st.addWorkDeviation(record);
+                if (target.task.pauseSnapshot) {
+                    const resumedDeviation = project.workDeviations
+                        .filter((deviation) => deviation.resumeTaskId === target.task.id
+                        && (deviation.state === "resume-required" || deviation.state === "resolved"))
+                        .sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0];
+                    if (resumedDeviation)
+                        await st.setWorkDeviationState(resumedDeviation.id, "resumed", timestamp);
+                }
+            }
+            catch (error) {
+                if (targetStarted) {
+                    await st.updatePhase(target.phase.id, (phase) => {
+                        phase.tasks = phase.tasks.map((task) => task.id === target.task.id ? target.task : task);
+                        return phase;
+                    }).catch(() => { });
+                }
+                if (sourceCheckpointed) {
+                    if (sourceWasActive)
+                        await st.resumeTask(source.phase.id, source.task.id, nowISO()).catch(() => { });
+                    else
+                        await st.updatePhase(source.phase.id, (phase) => {
+                            phase.tasks = phase.tasks.map((task) => task.id === source.task.id ? source.task : task);
+                            return phase;
+                        }).catch(() => { });
+                }
+                throw error;
+            }
+            await st.syncTaskStatusRollup(source.phase.id);
+            if (target.phase.id !== source.phase.id)
+                await st.syncTaskStatusRollup(target.phase.id);
+            await st.writeGenerated();
+            const sourceRef = `${formatPhaseRef(source.phase.number, featureNumberOfPhase(source.phase, features))}/T${String(source.task.number).padStart(3, "0")}`;
+            const targetRef = `${formatPhaseRef(target.phase.number, featureNumberOfPhase(target.phase, features))}/T${String(target.task.number).padStart(3, "0")}`;
+            const targetReadAdvisory = parentReadAdvisory(target.phase.featureId, target.phase.id);
+            const targetRequirementAdvisory = requirementReadAdvisory([
+                ...(await st.linkedRequirementsForPhase(target.phase.id)).map((r) => r.id),
+                ...(target.phase.featureId ? (await st.linkedRequirementsForFeature(target.phase.featureId)).map((r) => r.id) : []),
+            ]);
+            return {
+                content: [{ type: "text", text: [
+                            `🔀 Task switched: ${sourceRef} → ${targetRef}`,
+                            `Resume checkpoint: ${snapshot.whatWasBeingDone}`,
+                            `Return target: ${sourceRef} from ${snapshot.resumeLocation}`,
+                            "Normal priority was deliberately overridden; completing the temporary task will emit RESUME REQUIRED.",
+                            ...(targetReadAdvisory ? [targetReadAdvisory.trimStart()] : []),
+                            ...(targetRequirementAdvisory ? [targetRequirementAdvisory.trimStart()] : []),
+                        ].join("\n") }],
+                details: { deviation: record, snapshot, resumeTaskId: source.task.id, temporaryTaskId: target.task.id, ...(targetReadAdvisory || targetRequirementAdvisory ? { readRequired: true } : {}) },
+            };
+        },
+    });
     pi.registerTool({
         name: "task_start",
         label: "Task Start",
-        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.",
+        description: "Set a task to in-progress or resume checkpointed work. BEFORE calling, read feature_get(full=true), phase_get(full=true), then task_get(full=true). A different active task must first be suspended through task_switch. Otherwise follow active/pending-resume/feature → phase → task priority guidance.",
         parameters: Type.Object({
             taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title to start" }),
         }),
@@ -4119,6 +4456,35 @@ export default function planPiExtension(pi) {
             if (!eligibility.eligible)
                 return { content: [{ type: "text", text: `Task start denied: ${eligibility.reason}` }], details: eligibility };
             const selection = recommendNextTask(features, phases, project.workDeviations);
+            if (selection.kind === "conflict") {
+                return { content: [{ type: "text", text: `${selection.reason} Pause/reconcile active tasks before starting another task.` }], details: selection };
+            }
+            if (selection.kind === "active" && selection.candidate?.task.id !== task.id) {
+                const activeRef = `${formatPhaseRef(selection.candidate.phase.number, featureNumberOfPhase(selection.candidate.phase, features))}/T${String(selection.candidate.task.number).padStart(3, "0")}`;
+                return { content: [{ type: "text", text: `Task start denied: ${activeRef} is active. Use task_switch to snapshot and pause it before starting another task.` }], details: selection };
+            }
+            let resumeProposal;
+            if (selection.kind === "resume" && selection.candidate && selection.candidate.task.id !== task.id) {
+                // Advisory only: a pending resume must be surfaced loudly, but it must
+                // not hard-block an explicit start of a different task. Capture a
+                // structured proposal so the resume-first guidance is explicit and
+                // machine-readable for the host/agent.
+                const resumeTask = selection.candidate;
+                const resumeRef = `${formatPhaseRef(resumeTask.phase.number, featureNumberOfPhase(resumeTask.phase, features))}/T${String(resumeTask.task.number).padStart(3, "0")}`;
+                const resumeSnapshot = resumeTask.task.pauseSnapshot
+                    ?? project.workDeviations.find((deviation) => deviation.resumeTaskId === resumeTask.task.id
+                        && (deviation.state === "resume-required" || deviation.state === "resolved"))?.snapshot
+                    ?? null;
+                resumeProposal = buildResumeRequiredProposal({
+                    ref: resumeRef,
+                    title: resumeTask.task.title,
+                    taskId: resumeTask.task.id,
+                    phaseId: resumeTask.phase.id,
+                    snapshot: resumeSnapshot
+                        ? { reason: resumeSnapshot.reason, resumeLocation: resumeSnapshot.resumeLocation, howToResume: resumeSnapshot.howToResume }
+                        : null,
+                });
+            }
             // 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;
@@ -4127,33 +4493,58 @@ export default function planPiExtension(pi) {
                 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 advisory = selection.candidate && selection.candidate.task.id !== task.id
+                ? selection.kind === "resume"
+                    ? `\n\n${resumeProposal ? resumeProposal.text : `⚠️ Resume advisory: ${formatPhaseRef(selection.candidate.phase.number, featureNumberOfPhase(selection.candidate.phase, features))}/T${String(selection.candidate.task.number).padStart(3, "0")} has a saved checkpoint. Evaluate its resume context before continuing with this explicit task request. 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) => {
-                const t = phase.tasks.find((x) => x.id === found.task.id);
-                if (!t)
+            if (task.pauseSnapshot) {
+                startedTask = await st.resumeTask(found.phase.id, found.task.id, now);
+            }
+            else {
+                await st.updatePhase(found.phase.id, (phase) => {
+                    const t = phase.tasks.find((x) => x.id === found.task.id);
+                    if (!t)
+                        return phase;
+                    const previousStatus = t.status;
+                    applyTaskLifecycleDates(t, "in-progress", now);
+                    t.statusLog = [...t.statusLog, {
+                            id: createChecklistItemId(t.id, t.statusLog.length + 1, `${previousStatus}-in-progress`),
+                            date: now, fromStatus: previousStatus, toStatus: "in-progress",
+                            title: `${previousStatus} → in-progress`, description: "",
+                        }];
+                    t.updatedAt = now;
+                    phase.updatedAt = now;
+                    startedTask = t;
                     return phase;
-                applyTaskLifecycleDates(t, "in-progress", now);
-                t.updatedAt = now;
-                phase.updatedAt = now;
-                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);
+            const resumedDeviation = project.workDeviations
+                .filter((deviation) => deviation.resumeTaskId === task.id
+                && (deviation.state === "resume-required" || deviation.state === "resolved"))
+                .sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0];
+            if (resumedDeviation)
+                await st.setWorkDeviationState(resumedDeviation.id, "resumed", now);
             await st.writeGenerated();
             if (!startedTask)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
-            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 };
+            const readAdvisory = parentReadAdvisory(parentFeature?.id, found.phase.id);
+            const requirementAdvisory = requirementReadAdvisory([
+                ...(phaseWithRequirements.linkedRequirements ?? []).map((r) => r.id),
+                ...featureRequirements.map((r) => r.id),
+            ]);
+            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}${readAdvisory}${requirementAdvisory}` }],
+                details: startedTask,
+                ...(resumeProposal ? { resumeRequired: resumeProposal.structured } : {}),
+                ...(readAdvisory || requirementAdvisory ? { readRequired: true } : {}),
+            };
         },
     });
     pi.registerTool({
@@ -4176,6 +4567,8 @@ export default function planPiExtension(pi) {
             const task = found.task;
             if (task.status === "done")
                 return { content: [{ type: "text", text: `Task ${task.id} is already done.` }], details: task };
+            if (task.pauseSnapshot)
+                return { content: [{ type: "text", text: "Task completion denied: resume checkpointed work with task_start before completing it, or cancel it explicitly with motivation." }], details: task };
             const unchecked = task.checklist.filter((item) => !item.checked);
             if (unchecked.length > 0 && !params.force) {
                 return {
@@ -4189,7 +4582,13 @@ export default function planPiExtension(pi) {
                 const t = phase.tasks.find((x) => x.id === found.task.id);
                 if (!t)
                     return phase;
+                const previousStatus = t.status;
                 applyTaskLifecycleDates(t, "done", now);
+                t.statusLog = [...t.statusLog, {
+                        id: createChecklistItemId(t.id, t.statusLog.length + 1, `${previousStatus}-done`),
+                        date: now, fromStatus: previousStatus, toStatus: "done",
+                        title: `${previousStatus} → done`, description: "",
+                    }];
                 if (params.description_update) {
                     const sep = t.description ? "\n\n---\n**Completion summary:**\n" : "**Completion summary:**\n";
                     t.description = t.description + sep + params.description_update;
@@ -4204,11 +4603,33 @@ export default function planPiExtension(pi) {
                 .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.setWorkDeviationState(completedDeviation.id, "resume-required", 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)${clearedRef ? ` — phase handoff archived (${clearedRef})` : ""}` }], details: completedTask };
+            let resumeNotice = "";
+            let resumeRequired;
+            if (completedDeviation) {
+                const resume = findTaskByRef(await st.loadAllPhases(), features, completedDeviation.resumeTaskId);
+                if (resume) {
+                    const snapshot = resume.task.pauseSnapshot ?? completedDeviation.snapshot;
+                    const resumeRef = `${formatPhaseRef(resume.phase.number, featureNumberOfPhase(resume.phase, features))}/T${String(resume.task.number).padStart(3, "0")}`;
+                    resumeNotice = [
+                        "",
+                        `↩️ RESUME REQUIRED: ${resumeRef} — ${resume.task.title}`,
+                        snapshot ? `Checkpoint reason: ${snapshot.reason}` : "Return to the preserved task before selecting new priority work.",
+                        snapshot ? `Resume from: ${snapshot.resumeLocation}` : "",
+                        snapshot ? `How to resume: ${snapshot.howToResume}` : "",
+                        `Next action: task_start ${resumeRef}`,
+                    ].filter(Boolean).join("\n");
+                    resumeRequired = { taskId: resume.task.id, phaseId: resume.phase.id, snapshot };
+                }
+            }
+            const completedRef = `${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${String(completedTask.number).padStart(3, "0")}`;
+            return {
+                content: [{ type: "text", text: `✅ Task completed: ${completedRef} — ${completedTask.title} (done)${clearedRef ? ` — phase handoff archived (${clearedRef})` : ""}${resumeNotice}` }],
+                details: resumeRequired ? { task: completedTask, resumeRequired } : completedTask,
+            };
         },
     });
     pi.registerTool({