@agent-plan/pi-adapter 0.2.19-next.0 → 0.2.19-next.2

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,iCAAiC,CAAC;AAuzBtF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAg7F9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,iCAAiC,CAAC;AA6uBtF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAg7F9D"}

package/dist/index.js

@@ -9,8 +9,8 @@
  *  - inject context into prompts
  */
 import { Type } from "typebox";
-import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, withFeatureLock, needsMotivation, findPhaseByRef } from "@agent-plan/core";
-import { createChecklistItemId, createFeatureId, createPhaseId, createShortId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef } 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";
@@ -68,6 +68,29 @@ setWriteNotifyHook(() => {
 let previousContextPercent = 0;
 let autoHandoffTriggered = false;
 let plannerSessionEnabled = false;
+// In-process guard bypass (per session, NOT persisted/shared). The edit/write
+// guard is advisory in Pi (warns "NO ACTIVE TASK" but does not block). When a
+// bypass is active the warning is silenced for the window. Lives in memory only:
+// not on disk, not in git, not shared across agents/sessions on the same folder.
+let guardBypassUntil = "";
+function authorizeGuardBypass(durationMinutes = 15) {
+    const until = new Date(Date.now() + durationMinutes * 60_000).toISOString();
+    guardBypassUntil = until;
+    return until;
+}
+function clearGuardBypass() { guardBypassUntil = ""; }
+function isGuardBypassed() {
+    if (!guardBypassUntil)
+        return false;
+    const until = Date.parse(guardBypassUntil);
+    if (!Number.isFinite(until))
+        return false;
+    if (until <= Date.now()) {
+        guardBypassUntil = "";
+        return false;
+    }
+    return true;
+}
 let startupResumePromptPending = false;
 let startupResumeSummaryPending = false;
 let plannerHeavyInitDone = false; // runs migrate/heal/refreshResume once per session, not every turn
@@ -227,106 +250,6 @@ function phaseLabel(phase) {
 function taskLabel(task) {
     return `T${formatSequence(task.number)} — ${task.title}`;
 }
-async function buildStartupResumeSummary(st) {
-    const [plan, resume, handoffs] = await Promise.all([
-        st.loadAll(),
-        st.refreshResume(),
-        st.listHandoffs(),
-    ]);
-    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"))
-        : (handoffs.length > 0
-            ? "leggere l'handoff di fase più recente (handoff show <ref>) e verificarne ordine e stato rispetto al 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.",
-            handoffs.length > 0 ? `- Handoff di fase pendenti (${handoffs.length}):\n${handoffs.map((h, i) => `  [${i + 1}] ${h.compositeRef} — ${h.updatedAt} — "${h.firstLine}"`).join("\n")}` : "- Nessun handoff di fase pendente.",
-            !hasActiveWork && handoffs.length > 0 ? "- Nota: l'handoff di fase è 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.",
-        handoffs.length > 0 ? `- Pending phase handoffs (${handoffs.length}):\n${handoffs.map((h, i) => `  [${i + 1}] ${h.compositeRef} — ${h.updatedAt} — "${h.firstLine}"`).join("\n")}` : "- No pending phase handoffs.",
-        !hasActiveWork && handoffs.length > 0 ? "- Note: the phase 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] = await Promise.all([
         st.loadAll(),
@@ -625,13 +548,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;
         }
     }
@@ -708,7 +641,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");
@@ -736,8 +669,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 { }
@@ -947,6 +885,8 @@ export default function planPiExtension(pi) {
             return; // nothing to enforce yet
         if (guard.inProgressTaskIds.length > 0)
             return; // a task is open → we're good
+        if (isGuardBypassed())
+            return; // user authorized proceeding without a task
         const focusHint = guard.focusTaskId
             ? `Il task più probabile è ${guard.focusTaskId} — ${guard.focusTaskTitle}. Avvialo con: \`/planner task start ${guard.focusTaskId}\``
             : `Scegli un task dal piano e avvialo con \`/planner task start <taskId>\`.`;
@@ -1113,40 +1053,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
@@ -1154,17 +1087,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())
+            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 = parseInt(pick.trim(), 10) - 1;
-            if (isNaN(idx) || idx < 0 || idx >= phase.tasks.length) {
-                ctx.ui.notify("Invalid number", "error");
-                return null;
-            }
-            return phase.tasks[idx];
+            const idx = options.indexOf(chosen);
+            return idx >= 0 ? tasks[idx] : null;
         }
         function parseMultilineList(value) {
             return (value ?? "")
@@ -1183,7 +1112,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;
@@ -1192,7 +1129,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;
@@ -2301,12 +2246,12 @@ export default function planPiExtension(pi) {
             try {
                 if (a === "bypass") {
                     const mins = parseInt(subArgs.trim(), 10);
-                    const until = await st.authorizeGuardBypass(Number.isFinite(mins) && mins > 0 ? mins : 15);
-                    ctx.ui.notify(`Guard bypass authorized until ${until}. edit/write will work without a task in-progress for that window.`, "info");
+                    const until = authorizeGuardBypass(Number.isFinite(mins) && mins > 0 ? mins : 15);
+                    ctx.ui.notify(`Guard bypass authorized until ${until}. edit/write advisory warnings silenced for that window (per-session, not shared).`, "info");
                 }
                 else {
-                    await st.clearGuardBypass();
-                    ctx.ui.notify("Guard bypass revoked. edit/write now requires a task in-progress again.", "info");
+                    clearGuardBypass();
+                    ctx.ui.notify("Guard bypass revoked. edit/write advisory warnings re-enabled.", "info");
                 }
             }
             catch (e) {
@@ -2334,9 +2279,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,
@@ -2837,29 +2796,29 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "plan_authorize_bypass",
         label: "Plan Authorize Guard Bypass",
-        description: "Authorize a temporary guard bypass (default 15 minutes) so edit/write tools can proceed even when no task is in-progress. Use this ONLY after the user explicitly authorizes proceeding without a task. Harness-agnostic: stored in resume.json so all adapters respect it.",
+        description: "Authorize a temporary guard bypass (default 15 minutes) so the edit/write advisory guard stops warning when no task is in-progress. Per-session in-memory: not persisted, not shared across agents. Use ONLY after the user explicitly authorizes proceeding without a task.",
         parameters: Type.Object({
             durationMinutes: Type.Optional(Type.Number({ description: "Bypass window in minutes. Default 15." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
-            const st = await requirePlan(ctx);
-            if (!st)
+            const ok = await requirePlan(ctx);
+            if (!ok)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const mins = params.durationMinutes ?? 15;
-            const until = await st.authorizeGuardBypass(mins);
-            return { content: [{ type: "text", text: `Guard bypass authorized until ${until}. edit/write is allowed without a task in-progress for ${mins} minutes.` }], details: { until } };
+            const until = authorizeGuardBypass(mins);
+            return { content: [{ type: "text", text: `Guard bypass authorized until ${until}. Advisory edit/write warnings silenced for ${mins} minutes (per-session, not shared).` }], details: { until } };
         },
     });
     pi.registerTool({
         name: "plan_clear_bypass",
         label: "Plan Clear Guard Bypass",
-        description: "Revoke any active guard bypass so edit/write again requires a task in-progress.",
+        description: "Revoke the per-session guard bypass so the edit/write advisory warnings resume.",
         parameters: Type.Object({}),
         async execute(_id, _params, _signal, _onUpdate, ctx) {
-            const st = await requirePlan(ctx);
-            if (!st)
+            const ok = await requirePlan(ctx);
+            if (!ok)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            await st.clearGuardBypass();
+            clearGuardBypass();
             return { content: [{ type: "text", text: "Guard bypass revoked." }], details: { cleared: true } };
         },
     });
@@ -3634,16 +3593,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({
@@ -3789,27 +3747,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.",
-                handoffs.length > 0 ? `- PHASE HANDOFFS (${handoffs.length} pending):` : "",
-                ...handoffs.map((h, i) => `  [${i + 1}] ${h.compositeRef} — ${h.updatedAt} — "${h.firstLine}"`),
-                handoffs.length > 0 ? "- Present this numbered list to the user. Recommend the most recent (or the one aligned with the current resume focus)." : "",
-                handoffs.length > 0 ? "- Ask the user to confirm which one to resume. Then run handoff show <ref> (or /planner handoff show <ref>) to read it." : "",
-                handoffs.length > 0 ? "- After reading and confirming the resume, CLEAR that handoff with handoff clear <ref> (or /planner handoff clear) BEFORE starting implementation work — a resumed handoff must not go stale." : "",
-                handoffs.length === 0 ? "- No pending phase handoffs: fall back to the resume.json focus (current in-progress task/phase) above." : "",
-                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 = [
@@ -3827,6 +3774,7 @@ export default function planPiExtension(pi) {
                 "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 ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/pi-adapter",
-  "version": "0.2.19-next.0",
+  "version": "0.2.19-next.2",
   "private": false,
   "description": "Pi agent extension for Agent Plan — structured project planning in .planner/",
   "keywords": [
@@ -28,8 +28,8 @@
   "dependencies": {
     "typebox": "^1.1.24",
     "zod": "^3.24.0",
-    "@agent-plan/core": "0.2.19-next.0",
-    "@agent-plan/server": "0.2.19-next.0"
+    "@agent-plan/core": "0.2.19-next.2",
+    "@agent-plan/server": "0.2.19-next.2"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.74.0",