@agent-plan/pi-adapter 0.2.18 → 0.2.19-next.1

package/dist/index.js

@@ -9,8 +9,8 @@
  *  - inject context into prompts
  */
 import { Type } from "typebox";
-import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, withFeatureLock, needsMotivation } from "@agent-plan/core";
-import { createChecklistItemId, createFeatureId, createPhaseId, createTaskId, clampSlug, normalizeSlug } from "@agent-plan/core/naming";
+import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, withFeatureLock, needsMotivation, findPhaseByRef, buildRecap } from "@agent-plan/core";
+import { createChecklistItemId, createFeatureId, createPhaseId, createShortId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, featureNumberOfPhase } from "@agent-plan/core/naming";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
@@ -101,10 +101,11 @@ const PLANNER_COMMAND_COMPLETIONS = [
     { value: "task delete", label: "task delete", description: "Delete a task" },
     { value: "task start", label: "task start", description: "Mark a task in-progress" },
     { value: "task complete", label: "task complete", description: "Mark a task done" },
-    { value: "handoff prepare", label: "handoff prepare", description: "Tell the agent to create/update the handoff" },
-    { value: "handoff show", label: "handoff show", description: "Show the current handoff" },
-    { value: "handoff write", label: "handoff write", description: "Write handoff directly from planner data" },
-    { value: "handoff clear", label: "handoff clear", description: "Delete the current handoff" },
+    { 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: "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" },
@@ -157,11 +158,17 @@ function resetState() {
     editedThisTurn = false;
     taskCompleteReminderSaidThisTurn = false;
 }
-async function maybeHealStatuses(st) {
+async function maybeHealStatuses(st, ctx) {
     if (healedStatusRoots.has(st.root))
         return;
-    await st.syncStatuses();
+    const cleared = await st.syncStatuses();
     healedStatusRoots.add(st.root);
+    if (cleared.length > 0 && ctx?.ui?.notify) {
+        try {
+            ctx.ui.notify(`ℹ️  Handoff auto-cleared (phase completed): ${cleared.join(", ")}`, "info");
+        }
+        catch { }
+    }
 }
 function normalizeLanguagePref(value) {
     return value?.trim() ?? "";
@@ -220,114 +227,13 @@ function phaseLabel(phase) {
 function taskLabel(task) {
     return `T${formatSequence(task.number)} — ${task.title}`;
 }
-async function buildStartupResumeSummary(st) {
-    const [plan, resume, handoff] = await Promise.all([
-        st.loadAll(),
-        st.refreshResume(),
-        st.loadHandoff(),
-    ]);
-    const phaseById = new Map(plan.phases.map((phase) => [phase.id, phase]));
-    const orderedPhases = [
-        ...plan.features.features.flatMap((feature) => {
-            const linked = feature.phaseIds.map((id) => phaseById.get(id)).filter((phase) => Boolean(phase));
-            const linkedIds = new Set(linked.map((phase) => phase.id));
-            const inferred = plan.phases
-                .filter((phase) => phase.featureId === feature.id && !linkedIds.has(phase.id))
-                .sort((left, right) => left.number - right.number || left.createdAt.localeCompare(right.createdAt));
-            return [...linked, ...inferred];
-        }),
-        ...plan.phases
-            .filter((phase) => !phase.featureId)
-            .sort((left, right) => left.number - right.number || left.createdAt.localeCompare(right.createdAt)),
-    ];
-    const allTasks = orderedPhases.flatMap((phase) => [...phase.tasks]
-        .sort((left, right) => left.number - right.number || left.createdAt.localeCompare(right.createdAt))
-        .map((task) => ({ phase, task })));
-    const totalFeatures = plan.features.features.length;
-    const doneFeatures = plan.features.features.filter((feature) => feature.status === "done").length;
-    const activeFeatures = plan.features.features.filter((feature) => feature.status === "in-progress").length;
-    const totalPhases = plan.phases.length;
-    const donePhases = plan.phases.filter((phase) => phase.status === "done").length;
-    const activePhases = plan.phases.filter((phase) => phase.status === "in-progress" || phase.status === "discovery").length;
-    const totalTasks = allTasks.length;
-    const doneTasks = allTasks.filter(({ task }) => task.status === "done").length;
-    const activeTasks = allTasks.filter(({ task }) => task.status === "in-progress").length;
-    const hasActiveWork = activeFeatures > 0 || activePhases > 0 || activeTasks > 0;
-    const currentPhase = hasActiveWork
-        ? orderedPhases.find((phase) => phase.id === resume.currentPhaseId && (phase.status === "in-progress" || phase.tasks.some((task) => resume.inProgressTaskIds.includes(task.id))))
-            ?? orderedPhases.find((phase) => phase.tasks.some((task) => resume.inProgressTaskIds.includes(task.id)))
-            ?? orderedPhases.find((phase) => phase.status === "in-progress")
-            ?? null
-        : null;
-    const currentTask = hasActiveWork
-        ? ([...(currentPhase?.tasks ?? [])]
-            .sort((left, right) => left.number - right.number || left.createdAt.localeCompare(right.createdAt))
-            .find((task) => resume.inProgressTaskIds.includes(task.id))
-            ?? [...(currentPhase?.tasks ?? [])]
-                .sort((left, right) => left.number - right.number || left.createdAt.localeCompare(right.createdAt))
-                .find((task) => task.status === "in-progress")
-            ?? allTasks.find(({ task }) => task.status === "in-progress")?.task
-            ?? null)
-        : null;
-    const currentFeature = hasActiveWork
-        ? (currentPhase?.featureId
-            ? plan.features.features.find((feature) => feature.id === currentPhase.featureId) ?? null
-            : plan.features.features.find((feature) => feature.status === "in-progress") ?? null)
-        : null;
-    const nextActivity = hasActiveWork
-        ? (resume.nextSteps[0]
-            ?? (currentTask
-                ? `riprendere il task ${currentTask.id} — ${taskLabel(currentTask)}`
-                : currentPhase
-                    ? `riprendere la fase ${currentPhase.id} — ${phaseLabel(currentPhase)}`
-                    : "riprendere il lavoro attivo corrente"))
-        : (handoff?.updatedAt
-            ? "leggere l'handoff e verificare ordine, dipendenze e stato reale del piano prima di scegliere il prossimo task"
-            : "rivedere il piano e scegliere il prossimo task concreto");
-    const chatLanguage = (plan.project.chatLanguage || "").toLowerCase();
-    const italian = chatLanguage.includes("ital");
-    const localUrl = server?.localUrl ?? server?.url ?? "";
-    const lanUrl = server?.lanUrl ?? "";
-    const webUrl = lanUrl ? `${localUrl} (LAN: ${lanUrl})` : localUrl;
-    if (italian || !chatLanguage) {
-        return [
-            "### Summary di ripresa planner",
-            `- Progresso: ${doneFeatures}/${totalFeatures} feature completate (${activeFeatures} attive), ${donePhases}/${totalPhases} fasi completate (${activePhases} attive), ${doneTasks}/${totalTasks} task completati (${activeTasks} attivi).`,
-            currentFeature ? `- Focus feature: ${currentFeature.id} — ${featureLabel(currentFeature)} (${currentFeature.status}).` : "- Focus feature: nessuna feature attiva chiara.",
-            currentPhase ? `- Focus fase: ${currentPhase.id} — ${phaseLabel(currentPhase)} (${currentPhase.status}).` : "- Focus fase: nessuna fase attiva chiara.",
-            currentTask ? `- Focus task: ${currentTask.id} — ${taskLabel(currentTask)} (${currentTask.status}).` : "- Focus task: nessun task attivo in questo momento.",
-            handoff?.updatedAt ? `- Handoff letto da .planner/HANDOFF.md (aggiornato ${handoff.updatedAt}).` : "- Nessun handoff strutturato disponibile.",
-            !hasActiveWork && handoff?.updatedAt ? "- Nota: l'handoff è un suggerimento della sessione precedente; con 0 task/fasi attivi va validato contro stato e dipendenze correnti prima di riprendere un task specifico." : "",
-            `- Prossima attività consigliata: ${nextActivity}.`,
-            "",
-            "Vuoi che riprendiamo da qui?",
-            "",
-            webUrl ? `🌐 Web UI: ${webUrl}${lastKnownWebPort ? ` (port ${lastKnownWebPort})` : ""}` : "🌐 Web UI: not running — avvia con /planner load",
-        ].filter(Boolean).join("\n");
-    }
-    return [
-        "### Planner resume summary",
-        `- Progress: ${doneFeatures}/${totalFeatures} features done (${activeFeatures} active), ${donePhases}/${totalPhases} phases done (${activePhases} active), ${doneTasks}/${totalTasks} tasks done (${activeTasks} active).`,
-        currentFeature ? `- Feature focus: ${currentFeature.id} — ${featureLabel(currentFeature)} (${currentFeature.status}).` : "- Feature focus: no clear active feature.",
-        currentPhase ? `- Phase focus: ${currentPhase.id} — ${phaseLabel(currentPhase)} (${currentPhase.status}).` : "- Phase focus: no clear active phase.",
-        currentTask ? `- Task focus: ${currentTask.id} — ${taskLabel(currentTask)} (${currentTask.status}).` : "- Task focus: no active task right now.",
-        handoff?.updatedAt ? `- Handoff loaded from .planner/HANDOFF.md (updated ${handoff.updatedAt}).` : "- No structured handoff found.",
-        !hasActiveWork && handoff?.updatedAt ? "- Note: the handoff is only a previous-session hint; with 0 active tasks/phases it must be validated against current planner state and dependencies before resuming a specific task." : "",
-        `- Recommended next activity: ${nextActivity}.`,
-        "",
-        "Do you want to resume from here?",
-        "",
-        webUrl ? `🌐 Web UI: ${webUrl}${lastKnownWebPort ? ` (port ${lastKnownWebPort})` : ""}` : "🌐 Web UI: not running — start with /planner load",
-    ].filter(Boolean).join("\n");
-}
 async function buildHandoffMarkdown(st, reason, overrides) {
-    const [plan, resume, activity, existingHandoff] = await Promise.all([
+    const [plan, resume, activity] = await Promise.all([
         st.loadAll(),
         st.refreshResume(),
         st.loadActivityLog(),
-        st.loadHandoff(),
     ]);
-    const createdAt = existingHandoff?.createdAt || nowISO();
+    const createdAt = nowISO();
     const updatedAt = nowISO();
     const allTasks = plan.phases.flatMap((phase) => phase.tasks.map((task) => ({ phase, task })));
     const nonTerminalTasks = allTasks.filter(({ task }) => task.status !== "done" && task.status !== "canceled");
@@ -412,7 +318,7 @@ async function buildHandoffMarkdown(st, reason, overrides) {
                 : currentPhase
                     ? `1. Open phase ${currentPhase.id} (${currentPhase.title}).`
                     : "1. Open the planner dashboard and inspect the latest feature/phase state.",
-            "2. Read `.planner/HANDOFF.md` and compare it with the latest planner data.",
+            "2. Run handoff show <ref> (or /planner handoff show <ref>) to read the phase handoff and compare it with the latest planner data.",
             currentTask && currentTask.status !== "in-progress"
                 ? `3. Before implementation work, run /planner task start ${currentTask.id} (or call task_start).`
                 : "3. Confirm whether the current task is already in-progress before doing implementation work.",
@@ -420,11 +326,10 @@ async function buildHandoffMarkdown(st, reason, overrides) {
         ].join("\n");
     const filesTouched = [
         ".planner/project.json",
-        ".planner/features.json",
+        ".planner/features/",
         currentPhase ? `.planner/phases/${currentPhase.id}.json` : "",
         latestPhaseUpdate && latestPhaseUpdate.id !== currentPhase?.id ? `.planner/phases/${latestPhaseUpdate.id}.json` : "",
         ".planner/resume.json",
-        ".planner/HANDOFF.md",
         ".planner/generated/PLAN.md",
     ].filter(Boolean);
     const recentActivityLines = recentActivity.length > 0
@@ -488,12 +393,19 @@ async function buildHandoffMarkdown(st, reason, overrides) {
         ...recentActivityLines,
         "",
         "## Reminder",
-        "- When work is fully resumed and this handoff is no longer needed, delete `.planner/HANDOFF.md`.",
+        "- When work is fully resumed and this handoff is no longer needed, clear the phase handoff with handoff clear <ref> (or /planner handoff clear).",
     ].join("\n");
 }
 async function writeProjectHandoff(st, reason, overrides) {
+    // Entity-scoped: write the auto-handoff on the current in-progress phase
+    // (not the deprecated .planner/HANDOFF.md file). If no in-progress phase,
+    // skip silently — the resume flow falls back to resume.json.
+    const phases = await st.loadAllPhases();
+    const phase = phases.find((p) => p.status === "in-progress") ?? null;
+    if (!phase)
+        return;
     const markdown = await buildHandoffMarkdown(st, reason, overrides);
-    await st.saveHandoff(markdown);
+    await st.setPhaseHandoff(phase.id, markdown);
 }
 function compactShortcut(spec) {
     return {
@@ -613,13 +525,23 @@ async function pickProjectPort(ctx, explicitPort) {
         await st.saveProject(project);
         return explicitPort;
     }
-    if (project.webPort > 0) {
+    // Reuse the persisted port if it's still free (stable port across restarts,
+    // lets subagents notify the server via HTTP).
+    if (project.webPort > 0 && (await isPortAvailable(project.webPort))) {
         return project.webPort;
     }
+    // Persisted port busy (another planner instance on this project) or first run:
+    // scan for a free port. Persist ONLY on first run (canonical); when falling
+    // back from a busy persisted port, return transient so we don't hijack the
+    // primary session's canonical port (prevents port thrashing).
     for (let port = 3030; port <= 3999; port += 1) {
+        if (port === project.webPort)
+            continue;
         if (await isPortAvailable(port)) {
-            project.webPort = port;
-            await st.saveProject(project);
+            if (project.webPort <= 0) {
+                project.webPort = port;
+                await st.saveProject(project);
+            }
             return port;
         }
     }
@@ -696,7 +618,7 @@ async function startServer(ctx, requestedPort, visibility = "lan") {
                     uiConfig: readUiConfig(ctx),
                     isBusy: () => planBusy,
                 });
-                ctx.ui.notify(`Planner web server: requested port ${port} busy, started on ${server?.url ?? "?"} instead.`, "info");
+                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");
@@ -724,8 +646,13 @@ async function startServer(ctx, requestedPort, visibility = "lan") {
             const st = ensureStore(ctx);
             const project = await st.loadProject().catch(() => null);
             if (project) {
-                project.webPort = realPort;
-                await st.saveProject(project);
+                // Persist only the canonical port (first run, or realPort matches the
+                // existing canonical). Never persist a transient fallback port — that
+                // hijacks the primary session's port when two instances share a .planner.
+                if (project.webPort <= 0 || project.webPort === realPort) {
+                    project.webPort = realPort;
+                    await st.saveProject(project);
+                }
             }
         }
         catch { }
@@ -802,11 +729,11 @@ export default function planPiExtension(pi) {
                 ctx.ui.notify("Planner detected in this project. Run '/planner load' to enable the planner and start the web UI (LAN).", "info");
             }
             plannerSessionEnabled = enablePlanner;
-            // Proactive check for leftover handoff files.
+            // Proactive review hint: surface pending phase handoffs (entity-scoped).
             if (plannerSessionEnabled) {
-                const handoffPath = join(st.root, "HANDOFF.md");
-                if (existsSync(handoffPath)) {
-                    ctx.ui.notify("🚨 HANDOFF DETECTED: Read and delete .planner/HANDOFF.md immediately to avoid state conflicts.", "warning");
+                const handoffs = await st.listHandoffs().catch(() => []);
+                if (handoffs.length > 0) {
+                    ctx.ui.notify(`ℹ️  ${handoffs.length} phase handoff(s) pending — review with /planner handoff list.`, "info");
                 }
             }
             // If the user declined enablement, skip EVERYTHING (no web prompt, no migration, no summary).
@@ -929,7 +856,7 @@ export default function planPiExtension(pi) {
         const st = loadStore(ctx);
         if (!(await st.exists().catch(() => false)))
             return;
-        await maybeHealStatuses(st).catch(() => { });
+        await maybeHealStatuses(st, ctx).catch(() => { });
         const guard = await getPlannerExecutionGuard(st).catch(() => null);
         if (!guard || guard.totalTasks === 0)
             return; // nothing to enforce yet
@@ -1018,7 +945,7 @@ export default function planPiExtension(pi) {
         ];
         const SUB_HELP = "Available: init, show, repair, 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 export-full\n" +
-            "Handoff actions: /planner handoff prepare | show | write | clear";
+            "Handoff actions: /planner handoff list | show [P00x] | write [P00x] | clear [P00x] | prepare";
         if (!a) {
             const action = await ctx.ui.select("Planner action", PLANNER_MENU_ACTIONS);
             if (!action) {
@@ -1101,40 +1028,33 @@ export default function planPiExtension(pi) {
         //  Helper: pick a feature interactively
         // ═══════════════════════════════════════════════════════════════
         async function pickFeature() {
-            const features = (await st.loadFeatures().catch(() => ({ features: [] }))).features;
+            const features = (await st.loadFeatures().catch(() => ({ features: [] }))).features
+                .slice()
+                .sort((a, b) => a.number - b.number);
             if (features.length === 0)
                 return null;
-            const list = features.map((f, i) => `  ${i + 1}. ${statusIcon(f.status)} ${f.name} (${f.id})`).join("\n");
-            ctx.ui.notify(`Pick a feature:\n${list}`, "info");
-            const pick = await ctx.ui.input("Enter feature number");
-            if (!pick?.trim())
-                return null;
-            const idx = parseInt(pick.trim(), 10) - 1;
-            if (isNaN(idx) || idx < 0 || idx >= features.length) {
-                ctx.ui.notify("Invalid number", "error");
+            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;
-            }
-            return features[idx];
+            const idx = options.indexOf(chosen);
+            return idx >= 0 ? features[idx] : null;
         }
         // ═══════════════════════════════════════════════════════════════
         //  Helper: pick a phase interactively
         // ═══════════════════════════════════════════════════════════════
         async function pickPhase() {
-            const phases = await st.loadAllPhases().catch(() => []);
+            const phases = (await st.loadAllPhases().catch(() => [])).slice().sort((a, b) => a.number - b.number);
             if (phases.length === 0) {
                 return null;
             }
-            const list = phases.map((p, i) => `  ${i + 1}. ${statusIcon(p.status)} ${p.title} (${p.id})`).join("\n");
-            ctx.ui.notify(`Pick a phase:\n${list}`, "info");
-            const pick = await ctx.ui.input("Enter phase number");
-            if (!pick?.trim())
-                return null;
-            const idx = parseInt(pick.trim(), 10) - 1;
-            if (isNaN(idx) || idx < 0 || idx >= phases.length) {
-                ctx.ui.notify("Invalid number", "error");
+            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;
-            }
-            return phases[idx];
+            const idx = options.indexOf(chosen);
+            return idx >= 0 ? phases[idx] : null;
         }
         // ═══════════════════════════════════════════════════════════════
         //  Helper: pick a task interactively from a phase
@@ -1142,17 +1062,13 @@ export default function planPiExtension(pi) {
         async function pickTask(phase) {
             if (phase.tasks.length === 0)
                 return null;
-            const list = phase.tasks.map((t, i) => `  ${i + 1}. ${statusIcon(t.status)} ${t.title} (${t.id})`).join("\n");
-            ctx.ui.notify(`Pick a task from "${phase.title}":\n${list}`, "info");
-            const pick = await ctx.ui.input("Enter task number");
-            if (!pick?.trim())
-                return null;
-            const idx = parseInt(pick.trim(), 10) - 1;
-            if (isNaN(idx) || idx < 0 || idx >= phase.tasks.length) {
-                ctx.ui.notify("Invalid number", "error");
+            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;
-            }
-            return phase.tasks[idx];
+            const idx = options.indexOf(chosen);
+            return idx >= 0 ? tasks[idx] : null;
         }
         function parseMultilineList(value) {
             return (value ?? "")
@@ -1171,7 +1087,15 @@ export default function planPiExtension(pi) {
             const normalized = ref.trim().toLowerCase();
             if (!normalized)
                 return null;
-            return features.find((feature) => feature.id.toLowerCase() === normalized)
+            const fMatch = normalized.match(/^f(\d+)$/);
+            if (fMatch) {
+                const n = parseInt(fMatch[1], 10);
+                const byNum = features.find((f) => f.number === n);
+                if (byNum)
+                    return byNum;
+            }
+            return features.find((feature) => feature.shortId && feature.shortId.toLowerCase() === normalized)
+                ?? features.find((feature) => feature.id.toLowerCase() === normalized)
                 ?? features.find((feature) => feature.name.toLowerCase() === normalized)
                 ?? features.find((feature) => feature.name.toLowerCase().includes(normalized))
                 ?? null;
@@ -1180,7 +1104,15 @@ export default function planPiExtension(pi) {
             const normalized = ref.trim().toLowerCase();
             if (!normalized)
                 return null;
-            return phases.find((phase) => phase.id.toLowerCase() === normalized)
+            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;
@@ -1403,9 +1335,13 @@ export default function planPiExtension(pi) {
                 }
                 const now = nowISO();
                 const featureNumber = (await st.loadFeatures()).features.length + 1;
+                const shortId = createShortId(await st.assignedShortIds());
+                const priority = await st.nextPriority("feature");
                 const feature = {
                     id: createFeatureId(),
                     number: featureNumber,
+                    shortId,
+                    priority,
                     name: nameInput.trim(),
                     description: description?.trim() ?? "",
                     status: status,
@@ -1588,11 +1524,14 @@ export default function planPiExtension(pi) {
                     const number = featurePhases.reduce((max, p) => Math.max(max, p.number), 0) + 1;
                     const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
                     const id = createPhaseId();
+                    const shortId = createShortId(await st.assignedShortIds());
+                    const priority = await st.nextPriority("phase", feature.id);
                     phase = {
-                        id, number, slug, title, featureId: feature.id, status: "draft", discussedAt: "", contextReady: false, contextReadyReason: "", summary: "", description: "", notes: "",
+                        id, number, shortId, priority, slug, title, featureId: feature.id, status: "draft", discussedAt: "", contextReady: false, contextReadyReason: "", summary: "", description: "", notes: "",
                         goals: [], nonGoals: [], dependencies: [], dependsOn: [], risks: [],
                         openQuestions: [], decisions: [], acceptedDecisions: [], completionCriteria: [], taskIds: [], tasks: [],
                         createdAt: nowISO(), updatedAt: nowISO(),
+                        handoff: "", handoffUpdatedAt: "",
                     };
                     await st.savePhase(phase);
                     await st.updateFeatures((doc) => {
@@ -1825,9 +1764,11 @@ export default function planPiExtension(pi) {
                 const shortName = clampSlug(title, 30, `task-${Date.now().toString(36)}`);
                 const taskNum = phase.tasks.length + 1;
                 const taskId = createTaskId();
+                const shortId = createShortId(await st.assignedShortIds());
+                const priority = await st.nextPriority("task", phase.id);
                 const now = nowISO();
                 const task = {
-                    id: taskId, phaseId: phase.id, number: taskNum, shortName,
+                    id: taskId, phaseId: phase.id, number: taskNum, shortId, priority, shortName,
                     title: title.trim(), status: "planned",
                     description: "",
                     notes: "",
@@ -1994,8 +1935,8 @@ export default function planPiExtension(pi) {
                         ctx.ui.notify(`Invalid status. Use: ${valid.join(", ")}`, "error");
                         return;
                     }
-                    if (normalizedStatus === "in-progress" && existsSync(join(st.root, "HANDOFF.md"))) {
-                        ctx.ui.notify("ℹ️  A handoff exists at .planner/HANDOFF.md — read it for context, then delete it with /planner handoff clear (or plan_delete_handoff) when no longer needed. Proceeding with the status change.", "info");
+                    if (normalizedStatus === "in-progress" && (await st.listHandoffs()).length > 0) {
+                        ctx.ui.notify("ℹ️  One or more phases have a pending handoff — if relevant to this task, read it with /planner handoff show <ref>, then clear with /planner handoff clear. Proceeding with the status change.", "info");
                     }
                     applyTaskLifecycleDates(task, normalizedStatus, now);
                 }
@@ -2040,8 +1981,8 @@ export default function planPiExtension(pi) {
                 // block task_start — the handoff is a captured-context artifact, not a
                 // lock (a small modification after writing a handoff should start without
                 // forcing deletion, which would lose context).
-                if (existsSync(join(st.root, "HANDOFF.md"))) {
-                    ctx.ui.notify("ℹ️  A handoff exists at .planner/HANDOFF.md — read it for context, then delete it with /planner handoff clear (or plan_delete_handoff) when no longer needed. Proceeding with task start.", "info");
+                if ((await st.listHandoffs()).length > 0) {
+                    ctx.ui.notify("ℹ️  One or more phases have a pending handoff — if relevant to the task you're starting, read it with /planner handoff show <ref>, then clear with /planner handoff clear. Proceeding with task start.", "info");
                 }
                 const now = nowISO();
                 // Record status change in the incremental statusLog.
@@ -2129,60 +2070,80 @@ export default function planPiExtension(pi) {
         // ── handoff ──
         if (a === "handoff") {
             const action = b || "show";
+            const phaseRef = parts[2]?.trim();
             if (!(await st.exists())) {
                 ctx.ui.notify("No .planner/ found.", "warning");
                 return;
             }
+            if (action === "list") {
+                const list = await st.listHandoffs();
+                if (list.length === 0) {
+                    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");
+                return;
+            }
             if (action === "show") {
-                const handoff = await st.loadHandoff();
-                if (!handoff) {
-                    ctx.ui.notify("No .planner/HANDOFF.md present.", "info");
+                const r = await resolvePhaseForHandoff(st, phaseRef);
+                if (!r.ok) {
+                    ctx.ui.notify(r.error, "warning");
                     return;
                 }
-                ctx.ui.notify(handoff.content, "info");
+                const content = await st.getPhaseHandoff(r.phase.id);
+                ctx.ui.notify(content.trim() ? `Handoff ${r.compositeRef}:\n${content}` : `No handoff set on ${r.compositeRef}.`, "info");
                 return;
             }
-            if (action === "prepare" || action === "write") {
-                if (action === "prepare") {
-                    if (!capturedPi) {
-                        ctx.ui.notify("Agent bridge unavailable; use /planner handoff write for an auto-generated handoff.", "warning");
-                        return;
-                    }
-                    const handoff = await st.loadHandoff();
-                    await capturedPi.sendUserMessage("Prepare the canonical session handoff now and write it to `.planner/HANDOFF.md` using the `plan_write_handoff` tool.\n\n" +
-                        "The handoff MUST be a structured markdown document containing 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 must delete `.planner/HANDOFF.md` using `plan_delete_handoff`.\n\n" +
-                        "Do NOT write the handoff to `.pi/`. The canonical path is `.planner/HANDOFF.md`. " +
-                        (handoff?.content ? "A previous handoff exists; refresh its `Updated at` and merge/replace stale sections. " : "") +
-                        "Once written, confirm to me with a one-line summary.");
-                    ctx.ui.notify("Instructing the agent to prepare .planner/HANDOFF.md…", "info");
+            if (action === "write") {
+                const r = await resolvePhaseForHandoff(st, phaseRef);
+                if (!r.ok) {
+                    ctx.ui.notify(r.error, "warning");
                     return;
                 }
-                // action === "write": auto-generate from plan data without agent narrative.
-                const whatWasBeingDone = await ctx.ui.input("What was being done? (optional override)");
-                const howToResume = await ctx.ui.input("How should the next agent resume? (optional override)");
-                await writeProjectHandoff(st, "manual on-demand handoff", {
-                    ...(whatWasBeingDone?.trim() ? { whatWasBeingDone: whatWasBeingDone.trim() } : {}),
-                    ...(howToResume?.trim() ? { howToResume: howToResume.trim() } : {}),
-                });
-                ctx.ui.notify("Wrote .planner/HANDOFF.md", "info");
+                const text = await ctx.ui.input(`Handoff text for ${r.compositeRef}`);
+                if (!text?.trim()) {
+                    ctx.ui.notify("No text provided; nothing written.", "info");
+                    return;
+                }
+                await st.setPhaseHandoff(r.phase.id, text);
+                ctx.ui.notify(`Wrote handoff on ${r.compositeRef}`, "info");
+                return;
+            }
+            if (action === "prepare") {
+                if (!capturedPi) {
+                    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 current in-progress phase using the `handoff_write` tool (entity-scoped, stored on phase.handoff — .planner/HANDOFF.md is deprecated).\n\n" +
+                    "The handoff MUST be a structured markdown document containing 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.");
+                ctx.ui.notify("Instructing the agent to prepare the phase handoff…", "info");
                 return;
             }
             if (action === "clear" || action === "delete") {
-                await st.deleteHandoff();
-                ctx.ui.notify("Deleted .planner/HANDOFF.md", "info");
+                const r = await resolvePhaseForHandoff(st, phaseRef);
+                if (!r.ok) {
+                    ctx.ui.notify(r.error, "warning");
+                    return;
+                }
+                await st.clearPhaseHandoff(r.phase.id);
+                ctx.ui.notify(`Cleared handoff on ${r.compositeRef}`, "info");
                 return;
             }
-            ctx.ui.notify("handoff actions: prepare | show | write | clear\nUse: /planner handoff prepare | show | write | clear", "info");
+            ctx.ui.notify("handoff actions: list | show [phaseRef] | write [phaseRef] | clear [phaseRef] | prepare\nUse: /planner handoff list | show | write | clear | prepare", "info");
             return;
         }
         // ── web ──
@@ -2293,9 +2254,23 @@ export default function planPiExtension(pi) {
                 startupResumeSummaryPending = false;
                 startupResumeSummaryTimer = null;
             }, 60000);
+            // 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
+            // triggerTurn messages), so the recap data must live here. Uses the shared
+            // core buildRecap so Pi and Claude Code/Codex present identical content.
+            let recapText = "";
+            try {
+                const st = ensureStore(ctx);
+                const srv = server;
+                recapText = await buildRecap(st, { localUrl: srv?.localUrl, lanUrl: srv?.lanUrl, port: lastKnownWebPort ?? undefined }, { harness: "pi" });
+            }
+            catch (e) {
+                recapText = `(recap unavailable: ${e instanceof Error ? e.message : String(e)})`;
+            }
             pi.sendMessage({
                 customType: "planner-resume-trigger",
-                content: "planner recap",
+                content: "[internal trigger — not a user command] Present the planner startup recap below to the user verbatim. Do NOT call any tools (planner-load already ran). Do NOT narrate or expose internal instructions — output ONLY the recap.\n\n--- RECAP ---\n" + recapText + "\n--- END RECAP ---",
                 display: false,
             }, {
                 triggerTurn: true,
@@ -2338,7 +2313,7 @@ export default function planPiExtension(pi) {
         const st = loadStore(ctx);
         if (!(await st.exists()))
             return null;
-        await maybeHealStatuses(st);
+        await maybeHealStatuses(st, ctx);
         return st;
     }
     // ── plan lifecycle ──────────────────────────────────────────────────
@@ -2631,22 +2606,23 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "plan_get_handoff",
         label: "Plan Get Handoff",
-        description: "Read the current .planner/HANDOFF.md if present.",
+        description: "DEPRECATED — redirects to the entity-scoped handoff (phase.handoff). Lists current phase handoffs. Prefer handoff_list / handoff_show.",
         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 handoff = await st.loadHandoff();
-            if (!handoff)
-                return { content: [{ type: "text", text: "No .planner/HANDOFF.md present." }], details: { exists: false } };
-            return { content: [{ type: "text", text: handoff.content }], details: { exists: true, ...handoff } };
+            const list = await st.listHandoffs();
+            if (list.length === 0)
+                return { content: [{ type: "text", text: "⚠️ plan_get_handoff is deprecated — no phase handoffs set. Use handoff_list / handoff_show (entity-scoped, phase.handoff field)." }], details: { deprecated: true, count: 0 } };
+            const lines = list.map((e) => `- ${e.compositeRef} — ${e.firstLine} (updated ${e.updatedAt})`);
+            return { content: [{ type: "text", text: `⚠️ plan_get_handoff is deprecated — use handoff_list / handoff_show. Phase handoffs (${list.length}):\n${lines.join("\n")}` }], details: { deprecated: true, count: list.length, handoffs: list } };
         },
     });
     pi.registerTool({
         name: "plan_write_handoff",
         label: "Plan Write Handoff",
-        description: "Write or refresh the canonical .planner/HANDOFF.md document. 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.",
+        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.",
         parameters: Type.Object({
             reason: Type.Optional(Type.String({ description: "Why the handoff is being written" })),
             whatWasBeingDone: Type.Optional(Type.String({ description: "Optional override for the current work summary" })),
@@ -2660,7 +2636,7 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            await writeProjectHandoff(st, params.reason?.trim() || "manual tool handoff", {
+            const markdown = await buildHandoffMarkdown(st, params.reason?.trim() || "manual tool handoff", {
                 ...(params.whatWasBeingDone?.trim() ? { whatWasBeingDone: params.whatWasBeingDone.trim() } : {}),
                 ...(params.howToResume?.trim() ? { howToResume: params.howToResume.trim() } : {}),
                 ...(params.extraSections && params.extraSections.length > 0
@@ -2671,21 +2647,125 @@ export default function planPiExtension(pi) {
                     }
                     : {}),
             });
-            const handoff = await st.loadHandoff();
-            return { content: [{ type: "text", text: "Wrote .planner/HANDOFF.md" }], details: handoff ?? {} };
+            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 } };
         },
     });
     pi.registerTool({
         name: "plan_delete_handoff",
         label: "Plan Delete Handoff",
-        description: "Delete .planner/HANDOFF.md after the resume has been fully consumed.",
+        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) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            await st.deleteHandoff();
-            return { content: [{ type: "text", text: "Deleted .planner/HANDOFF.md" }], details: { deleted: true } };
+            const r = await resolvePhaseForHandoff(st, undefined);
+            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);
+            return { content: [{ type: "text", text: `⚠️ plan_delete_handoff is deprecated — cleared handoff on ${r.compositeRef} (phase.handoff). Prefer handoff_clear.` }], details: { deprecated: true, phaseRef: r.compositeRef, phaseId: r.phase.id } };
+        },
+    });
+    // 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.
+    async function resolvePhaseForHandoff(st, ref) {
+        const phases = await st.loadAllPhases();
+        const features = (await st.loadFeatures()).features;
+        let phase;
+        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)).",
+            };
+        }
+        const feat = phase.featureId ? features.find((f) => f.id === phase.featureId) : undefined;
+        return { ok: true, phase, compositeRef: formatPhaseRef(phase.number, feat?.number) };
+    }
+    pi.registerTool({
+        name: "handoff_list",
+        label: "Handoff List",
+        description: "List all phases with a non-empty entity-scoped handoff (phase.handoff field). Returns composite refs (P00x / P00x(F00x)) with the first line and last-updated time.",
+        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 list = await st.listHandoffs();
+            if (list.length === 0)
+                return { content: [{ type: "text", text: "No phase handoffs set." }], details: { count: 0 } };
+            const lines = list.map((e) => `- ${e.compositeRef} — ${e.firstLine} (updated ${e.updatedAt})`);
+            return { content: [{ type: "text", text: `Phase handoffs (${list.length}):\n${lines.join("\n")}` }], details: { count: list.length, handoffs: list } };
+        },
+    });
+    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." })) }),
+        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, params.phaseRef);
+            if (!r.ok)
+                return { content: [{ type: "text", text: `❌ ${r.error}` }], details: { error: r.error } };
+            const content = await st.getPhaseHandoff(r.phase.id);
+            if (!content.trim())
+                return { content: [{ type: "text", text: `No handoff set on ${r.compositeRef}.` }], details: { phaseRef: r.compositeRef, empty: true } };
+            return { content: [{ type: "text", text: `Handoff for ${r.compositeRef}:\n\n${content}` }], details: { phaseRef: r.compositeRef, phaseId: r.phase.id } };
+        },
+    });
+    pi.registerTool({
+        name: "handoff_write",
+        label: "Handoff Write",
+        description: "Write/refresh the entity-scoped handoff on a phase. Pass content (or markdown_content). phaseRef optional (default: current in-progress phase). Captures design context for a resuming agent on that phase.",
+        parameters: Type.Object({
+            phaseRef: Type.Optional(Type.String({ description: "Phase ref. Default: current in-progress phase." })),
+            content: Type.Optional(Type.String({ description: "Handoff text (plain)." })),
+            markdown_content: Type.Optional(Type.String({ description: "Handoff text (markdown). Preferred over content." })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const body = (params.markdown_content ?? params.content ?? "").trim();
+            if (!body)
+                return { content: [{ type: "text", text: "❌ Provide the handoff text (content or markdown_content)." }], details: { error: "empty text" } };
+            const r = await resolvePhaseForHandoff(st, params.phaseRef);
+            if (!r.ok)
+                return { content: [{ type: "text", text: `❌ ${r.error}` }], details: { error: r.error } };
+            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 } };
+        },
+    });
+    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." })) }),
+        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, params.phaseRef);
+            if (!r.ok)
+                return { content: [{ type: "text", text: `❌ ${r.error}` }], details: { error: r.error } };
+            await st.clearPhaseHandoff(r.phase.id);
+            return { content: [{ type: "text", text: `✅ Cleared handoff on ${r.compositeRef}. (handoffUpdatedAt preserved as audit)` }], details: { phaseRef: r.compositeRef, phaseId: r.phase.id } };
         },
     });
     pi.registerTool({
@@ -2771,9 +2851,13 @@ export default function planPiExtension(pi) {
             const now = nowISO();
             const status = params.status ?? "planned";
             const currentFeatures = (await st.loadFeatures()).features;
+            const shortId = createShortId(await st.assignedShortIds());
+            const priority = await st.nextPriority("feature");
             const feature = {
                 id: createFeatureId(),
                 number: currentFeatures.length + 1,
+                shortId,
+                priority,
                 name: params.name,
                 description: params.description ?? "",
                 status,
@@ -2813,6 +2897,7 @@ export default function planPiExtension(pi) {
             endDate: Type.Optional(Type.String({ description: "End date (YYYY-MM-DD)" })),
             workDone: Type.Optional(Type.String({ description: "Notes on work done" })),
             workRemaining: Type.Optional(Type.String({ description: "Notes on remaining work" })),
+            priority: Type.Optional(Type.Number({ description: "Display order within the project (lower = higher). Tiebreak by number then createdAt." })),
             acceptedDecisions: Type.Optional(Type.Array(Type.Object({
                 id: Type.String(),
                 title: Type.String(),
@@ -2844,6 +2929,8 @@ export default function planPiExtension(pi) {
                         feature.startDate = params.startDate;
                     if (params.endDate !== undefined)
                         feature.endDate = params.endDate;
+                    if (params.priority !== undefined)
+                        feature.priority = params.priority;
                     if (params.acceptedDecisions !== undefined)
                         feature.acceptedDecisions = params.acceptedDecisions;
                     if (params.status !== undefined) {
@@ -2970,9 +3057,11 @@ export default function planPiExtension(pi) {
                 const featurePhases = phases.filter((p) => p.featureId === params.featureId);
                 const number = featurePhases.reduce((max, p) => Math.max(max, p.number), 0) + 1;
                 const id = createPhaseId();
+                const shortId = createShortId(await st.assignedShortIds());
+                const priority = await st.nextPriority("phase", params.featureId);
                 const now = nowISO();
                 phase = {
-                    id, number, slug: normalizeSlug(params.title), title: params.title,
+                    id, number, shortId, priority, slug: normalizeSlug(params.title), title: params.title,
                     featureId: params.featureId,
                     status: params.status ?? "draft",
                     discussedAt: "",
@@ -2982,6 +3071,7 @@ export default function planPiExtension(pi) {
                     goals: [], nonGoals: [], dependencies: [], dependsOn: [], risks: [],
                     openQuestions: [], decisions: [], acceptedDecisions: [], completionCriteria: [], taskIds: [], tasks: [],
                     createdAt: now, updatedAt: now,
+                    handoff: "", handoffUpdatedAt: "",
                 };
                 await st.savePhase(phase);
                 // Atomic: serialize concurrent phase_create linking to the same feature.
@@ -3011,6 +3101,7 @@ export default function planPiExtension(pi) {
             summary: Type.Optional(Type.String({ description: "New summary" })),
             description: Type.Optional(Type.String({ description: "New description" })),
             featureId: Type.Optional(Type.String({ description: "Link/unlink phase to a feature. Use empty string to unlink." })),
+            priority: Type.Optional(Type.Number({ description: "Display order within the feature (lower = higher)" })),
             goals: Type.Optional(Type.Array(Type.String(), { description: "Replace goals list" })),
             nonGoals: Type.Optional(Type.Array(Type.String(), { description: "Replace non-goals list" })),
             dependencies: Type.Optional(Type.Array(Type.String(), { description: "Replace dependencies list" })),
@@ -3049,6 +3140,8 @@ export default function planPiExtension(pi) {
                 phase.summary = params.summary;
             if (params.description !== undefined)
                 phase.description = params.description;
+            if (params.priority !== undefined)
+                phase.priority = params.priority;
             if (params.goals !== undefined)
                 phase.goals = params.goals;
             if (params.nonGoals !== undefined)
@@ -3185,11 +3278,13 @@ export default function planPiExtension(pi) {
             }
             const shortName = clampSlug(params.shortName ?? params.title, 30, `task-${Date.now().toString(36)}`); // clamp+strip trailing dash; never empty
             const taskId = createTaskId();
+            const shortId = createShortId(await st.assignedShortIds());
+            const priority = await st.nextPriority("task", params.phaseId);
             const now = nowISO();
             const initialStatus = params.status ?? "planned";
             const existingPhase = await st.loadPhase(params.phaseId);
             const task = {
-                id: taskId, phaseId: params.phaseId, number: existingPhase.tasks.length + 1, shortName,
+                id: taskId, phaseId: params.phaseId, number: existingPhase.tasks.length + 1, shortId, priority, shortName,
                 title: params.title,
                 status: initialStatus,
                 description: params.description ?? "",
@@ -3235,6 +3330,7 @@ export default function planPiExtension(pi) {
                 implementationNotes: Type.String(),
                 acceptedAt: Type.String(),
             }), { description: "Replace accepted decisions list" })),
+            priority: Type.Optional(Type.Number({ description: "Display order within the phase (lower = higher)" })),
             checklist: Type.Optional(Type.Array(Type.String(), { description: "Replace checklist (plain strings). For interactive toggling use the web UI." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
@@ -3255,6 +3351,8 @@ export default function planPiExtension(pi) {
                         return phase;
                     if (params.title !== undefined)
                         task.title = params.title;
+                    if (params.priority !== undefined)
+                        task.priority = params.priority;
                     if (params.description !== undefined)
                         task.description = params.description;
                     if (params.notes !== undefined)
@@ -3470,16 +3568,15 @@ export default function planPiExtension(pi) {
             if (!server) {
                 await startServer(ctx, undefined, "lan").catch(() => { });
             }
+            const srv = server;
             let recap = "";
             try {
-                recap = await buildStartupResumeSummary(st);
+                recap = await buildRecap(st, { localUrl: srv?.localUrl, lanUrl: srv?.lanUrl, port: lastKnownWebPort ?? undefined }, { harness: "pi" });
             }
             catch (e) {
                 recap = `(recap unavailable: ${e instanceof Error ? e.message : String(e)})`;
             }
-            const srv = server;
-            const webLine = srv ? `\n🌐 Web UI: ${srv.localUrl}${lastKnownWebPort ? ` (port ${lastKnownWebPort})` : ""}${srv.lanUrl ? ` — LAN: ${srv.lanUrl}` : ""}` : "\n🌐 Web UI: not running";
-            return { content: [{ type: "text", text: `${recap}${webLine}` }], details: { enabled: true, running: Boolean(srv), localUrl: srv?.localUrl, lanUrl: srv?.lanUrl, port: lastKnownWebPort } };
+            return { content: [{ type: "text", text: recap }], details: { enabled: true, running: Boolean(srv), localUrl: srv?.localUrl, lanUrl: srv?.lanUrl, port: lastKnownWebPort } };
         },
     });
     pi.registerTool({
@@ -3510,8 +3607,9 @@ export default function planPiExtension(pi) {
             // add seconds of latency on every turn if run unconditionally.
             if (!plannerHeavyInitDone) {
                 await migrateToUuids(st);
+                await st.ensureShortIdsAndPriority().catch(() => null);
                 await ensureProjectLanguagePreferences(st).catch(() => null);
-                await maybeHealStatuses(st);
+                await maybeHealStatuses(st, ctx);
                 await st.refreshResume();
                 plannerHeavyInitDone = true;
             }
@@ -3542,7 +3640,7 @@ export default function planPiExtension(pi) {
             const resume = await st.loadResume().catch(() => null) ?? await st.refreshResume();
             const activity = await st.loadActivityLog();
             const recentActivity = activity.entries.slice(-8).reverse();
-            const handoff = await st.loadHandoff();
+            const handoffs = await st.listHandoffs();
             const phaseById = new Map(plan.phases.map((phase) => [phase.id, phase]));
             const orderedPhases = [
                 ...plan.features.features.flatMap((feature) => {
@@ -3593,8 +3691,8 @@ export default function planPiExtension(pi) {
             const nextActivity = hasActiveWork
                 ? (resume.nextSteps[0]
                     ?? (currentTask ? `Resume task ${currentTask.id} — ${taskLabel(currentTask)}` : currentPhase ? `Resume phase ${currentPhase.id} — ${phaseLabel(currentPhase)}` : "Resume the active work stream"))
-                : (handoff?.updatedAt
-                    ? "Read the handoff, then validate current plan ordering and dependencies before picking the next task."
+                : (handoffs.length > 0
+                    ? "Read the most recent phase handoff (handoff show <ref>), validate it against current plan ordering and dependencies, then pick the next task."
                     : "Review the current plan and choose the next task.");
             const webServer = server;
             const webLocalUrl = webServer?.localUrl ?? webServer?.url ?? "";
@@ -3624,22 +3722,16 @@ export default function planPiExtension(pi) {
             const ambientSummary = ambient
                 ? `node=${ambient.nodeVersion || "?"} pm=${ambient.packageManager || "?"} lockfile=${ambient.lockfile || "none"} scripts=${Object.entries(ambient.scripts).map(([k, v]) => `${k}="${v}"`).join(", ") || "none"}`
                 : "(not scanned)";
+            // NOTE: the recap DATA is delivered via the /planner load trigger message
+            // content (buildRecap), not via this system-prompt protocol — before_agent_start's
+            // systemPrompt injection is not applied to triggerTurn messages. This protocol
+            // is kept as a lightweight anti-narration guard for any normal recap turn.
             const startupResumeProtocol = isRecapTurn ? [
                 "",
-                "STARTUP RESUME PROTOCOL (first reply of the session — mandatory):",
-                "- You are resuming a planner-backed project session.",
-                "- Respond DIRECTLY with the summary. Do NOT narrate (no 'The user wants me to...', 'Let me check...', 'I\'ll emit...'). Do NOT run any tools (bash/read/grep/ls) before responding. Output ONLY the summary text.",
-                "- FIRST give the user a concise summary of progress so far.",
-                `- Mention progress counts: ${doneFeaturesCount}/${plan.features.features.length} features done, ${activeFeaturesCount} active; ${donePhasesCount}/${plan.phases.length} phases done, ${activePhasesCount} active; ${doneTasksCount}/${totalTasksCount} tasks done.`,
-                currentFeature ? `- Mention current feature ONLY because it is actually active: ${currentFeature.id} — ${featureLabel(currentFeature)} (${currentFeature.status}).` : "- Mention that no current feature is active.",
-                currentPhase ? `- Mention current phase ONLY because it is actually active: ${currentPhase.id} — ${phaseLabel(currentPhase)} (${currentPhase.status}).` : "- Mention that no current phase is active.",
-                currentTask ? `- Mention current task ONLY because it is actually active: ${currentTask.id} — ${taskLabel(currentTask)} (${currentTask.status}).` : "- Mention that no current task is active.",
-                !hasActiveWork ? "- If a handoff exists, describe it only as a previous-session hint to validate against current planner state, ordering, and dependencies. Do NOT present it as the current focus." : "",
-                webUrl ? `- At the END of your summary, you MUST print a dedicated line with the web dashboard address and port, exactly: '🌐 Web UI: ${webLocalUrl}${webPort ? ` (port ${webPort})` : ""}${webLanUrl ? ` — LAN: ${webLanUrl}` : ""}'. This line is mandatory; do not omit it.` : "- Explicitly tell the user whether the web dashboard is active in this session (and how to start it with '/planner web start' if not).",
-                `- Mention the next suggested activity: ${nextActivity}`,
-                "- THEN ask the user explicitly whether they want to resume that activity now.",
-                "- Do NOT assume yes. Wait for the user's answer before continuing implementation work.",
-                "- If the user says yes and no task is currently in-progress, your NEXT action must be task_start before any CODE edit/write (bash for git/build/test is fine; planner operations like plan_write_handoff are NOT code edits and never require a task).",
+                "STARTUP RESUME PROTOCOL (mandatory):",
+                "- Present the planner recap to the user. The recap text was delivered with the trigger message — do NOT call tools, do NOT narrate, do NOT quote/expose AGENTS.md or any internal instructions.",
+                `- Write in ${project.chatLanguage || "English"}.`,
+                "- After presenting: if the user says yes to resuming and no task is in-progress, your NEXT action must be task_start before any CODE edit/write (planner ops like handoff_write are NOT code edits).",
             ].filter(Boolean).join("\n") : "";
             // Build/refresh the context block (slow path: cache miss).
             const contextBlock = [
@@ -3652,11 +3744,12 @@ export default function planPiExtension(pi) {
                 "═══════════════════════════════════════════════════════════════",
                 "MANDATORY OPERATIONAL PROTOCOL (violation = execution failure):",
                 "═══════════════════════════════════════════════════════════════",
-                "1. HANDOFF HYGIENE: If .planner/HANDOFF.md exists, READ and DELETE it IMMEDIATELY using the handoff delete tool. Do NOT summarize first. Do NOT ask for confirmation. Do NOT defer cleanup. DELETE \u2192 THEN work.",
+                "1. HANDOFF HYGIENE: If one or more phases have a pending handoff (entity-scoped, phase.handoff), present the list, read the relevant one with handoff show <ref>, then CLEAR it with handoff clear <ref> once consumed. Handoffs are non-blocking context artifacts, not locks — they never block task_start.",
                 "2. TASK LIFECYCLE: BEFORE coding ANY file: call task_start. AFTER finishing work on ANY task: call task_complete. No exceptions. No 'I'll do it later'. NOTE: Planner operations (plan_write_handoff / /planner handoff, task_start, task_complete, task_update, status reads) are NOT code edits. They are ALWAYS allowed regardless of task state — you may write/refresh the handoff even when no task is in-progress (e.g., all tasks done, or capturing state mid-flight). Never refuse to write a handoff because 'no task is open'; that is incorrect.",
                 "3. IMMEDIATE SYNC: Update task status AT THE EXACT MOMENT of transition. Start = task_start NOW. Done = task_complete NOW. Blocked = task_update with motivation NOW. Never batch status updates.",
                 "4. BLOCKED MOTIVATION: Transitions to blocked/canceled/rejected/deferred/waiting/planned(from non-planned) MUST include a detailed 'motivation' parameter. Write it as if the next person has zero context.",
                 "5. NO SHORTCUTS: If a tool blocks you, follow the protocol. Bypasses are for emergencies only, not for convenience.",
+                "6. ENTITY REFERENCES: When you mention a feature/phase/task in chat, use its composite ID (F00x / P00x / T00x, e.g. T003(P002/F001)) or its 5-char shortId (e.g. UUXD1) — NEVER a raw UUID like bd6ed366. Tool responses already show these refs (compositeRef, shortId); reuse them.",
                 "═══════════════════════════════════════════════════════════════",
                 "",
                 // ── Project details ──
@@ -3727,11 +3820,12 @@ export default function planPiExtension(pi) {
                 "- Before your final answer after implementation work, either call task_complete if the task is finished, or explicitly tell the user the task remains in-progress.",
                 "- Use task_complete with force=true only if you have a good reason to skip the checklist check.",
                 "- To reopen a completed task, use task_start (recommended) or task_update.",
-                handoff?.content ? "Handoff detected at `.planner/HANDOFF.md`. Read it as previous-session context, but validate it against the current planner state, ordering, and dependencies before treating any target as the next task." : "",
-                handoff?.content ? "If planner state shows no task/phase in-progress, do NOT present the handoff target as the current focus; present it only as a candidate to validate." : "",
-                handoff?.content ? "When the handoff has been fully consumed and work is safely resumed, delete `.planner/HANDOFF.md` using the dedicated handoff delete command/tool." : "",
-                handoff?.content ? handoff.content : "",
-                "Plan tools available: project_set_language_preferences, plan_init, project_update, requirement_list, requirement_create, requirement_update, requirement_delete, plan_get, feature_list, feature_get, feature_create, feature_update, feature_delete, phase_list, phase_get, phase_create, phase_update, phase_delete, task_list, task_get, task_create, task_update, task_delete, task_start, task_complete, plan_render, plan_get_handoff, plan_write_handoff, plan_delete_handoff, plan_authorize_bypass, plan_clear_bypass",
+                handoffs.length > 0 ? `Pending phase handoffs (${handoffs.length}):` : "",
+                ...handoffs.map((h, i) => `  [${i + 1}] ${h.compositeRef} — ${h.updatedAt} — "${h.firstLine}"`),
+                handoffs.length > 0 ? "Read the relevant one with handoff show <ref> (or /planner handoff show <ref>) as previous-session context, but validate it against the current planner state, ordering, and dependencies before treating any target as the next task." : "",
+                handoffs.length > 0 ? "If planner state shows no task/phase in-progress, do NOT present a handoff target as the current focus; present it only as a candidate to validate." : "",
+                handoffs.length > 0 ? "Once a handoff is fully consumed and work is safely resumed, clear it with handoff clear <ref> (or /planner handoff clear)." : "",
+                "Plan tools available: project_set_language_preferences, plan_init, project_update, requirement_list, requirement_create, requirement_update, requirement_delete, plan_get, feature_list, feature_get, feature_create, feature_update, feature_delete, phase_list, phase_get, phase_create, phase_update, phase_delete, task_list, task_get, task_create, task_update, task_delete, task_start, task_complete, plan_render, plan_get_handoff, plan_write_handoff, plan_delete_handoff, handoff_list, handoff_show, handoff_write, handoff_clear, plan_authorize_bypass, plan_clear_bypass",
             ].filter(Boolean).join("\n");
             contextBlockCache = contextBlock;
             contextBlockDirty = false;