@d3ara1n/pi-subagent 2.2.0 → 3.1.0

package/src/index.ts

@@ -16,18 +16,14 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { getModelRolesAPI } from "@d3ara1n/pi-model-roles";
-import type {
-  CollectedRun,
-  SubagentConfig,
-  SubagentResult,
-  SubagentRole,
-} from "./types.ts";
+import type { SubagentConfig, SubagentResult, SubagentRole } from "./types.ts";
 import { DEFAULT_CONFIG } from "./types.ts";
 import { loadSubagentConfig } from "./config.ts";
 import { BUILTIN_ROLES } from "./roles.ts";
 import { getPiInvocation } from "./spawn.ts";
 import {
   AsyncSemaphore,
+  collectDeliveredIds,
   createThrottler,
   describeCurrentActivity,
   formatBudgetNote,
@@ -44,9 +40,11 @@ import {
 } from "./utils.ts";
 import { startSubagentRun, type RunHandle } from "./run.ts";
 import { buildInboxReminder, injectReminder } from "./reminder.ts";
+import { serializeInheritedConversation } from "./inheritance.ts";
 import { renderDelegateCall, renderDelegateResult } from "./render.ts";
 import { createViewPanel } from "./view.ts";
 import {
+  createSteerCallRender,
   renderBackgroundDelegateCall,
   renderBackgroundDelegateResult,
   renderCancelCall,
@@ -54,6 +52,7 @@ import {
   renderCheckCall,
   renderCheckResult,
   renderCompletionNotice,
+  renderSteerResult,
   renderWaitCall,
   renderWaitResult,
 } from "./render-async.ts";
@@ -101,14 +100,15 @@ export default function subagentExtension(pi: ExtensionAPI) {
   refreshAvailableRoles();
 
   // ── Background run registry ────────────────────────────────────
-  // Process-lifetime map of unclaimed background runs (queued, running, and
+  // Process-lifetime map of background runs (queued, running, and
   // finished/failed alike). Foreground delegate runs are NOT registered —
-  // their lifecycle is the tool call itself. subagent_check on a terminal run
-  // collects it: the handle is freed and a lightweight CollectedRun tombstone
-  // takes its place, so ids stay resolvable while memory does not grow with
-  // full results.
+  // their lifecycle is the tool call itself. Runs stay registered for the
+  // whole session: subagent_check is idempotent and re-delivers the terminal
+  // snapshot on every call, so branch navigation or compaction can never
+  // strand a result outside the model's reach. Whether a run still needs
+  // reminding is NOT tracked here — it derives from the session tree (see
+  // collectDeliveredIds + the context handler), the single source of truth.
   const backgroundRuns = new Map<string, RunHandle>();
-  const collectedRuns = new Map<string, CollectedRun>();
   let runCounter = 0;
   let sessionGeneration = 0;
 
@@ -146,11 +146,13 @@ export default function subagentExtension(pi: ExtensionAPI) {
       "- Delegate ONLY when a task involves significant work (heavy analysis, multi-step investigation, large-scope changes) AND you only care about the conclusion, not intermediate steps. A good test: the task would clutter your context with 3+ turns of raw tool output.",
       "- DO NOT delegate simple tasks — a single read, a one-line edit, a basic grep, or straightforward changes touching 1-2 files. Just do them yourself; spawning a child process costs more than the task.",
       "",
-      "SELF-CONTAINED DELEGATION (subagents have NO memory of this conversation):",
+      "DELEGATION CONTEXT MODES:",
       "",
-      "- The child sees exactly three things: task, context, files — nothing else of this chat exists for it. Any requirement, decision, or constraint it must know has to be restated in those channels.",
-      "- Never write phantom references (\"as discussed above\", \"per the requirements\") — the child has never seen that material. Inline the actual content instead.",
-      "- The isolation is deliberate: don't dump your whole conversation either. Pass what the task needs and nothing more, so the child's judgment isn't steered by irrelevant history.",
+      "- Self-contained (default): when task, context, and files contain everything the child needs, omit inheritConversation. The child receives no parent dialogue.",
+      '- Conversation-relative: when the task is intentionally written as a delta against this chat — e.g. "implement the approved approach", "review the requirements above", or "continue from our discussion" — set inheritConversation: true.',
+      "- Never send a conversation-relative task without inheritConversation: true. Either enable inheritance or rewrite the task to be self-contained.",
+      "- With inheritance enabled, keep task focused on the work to perform; do not duplicate the conversation into context. Use context for additional non-conversation background and files for source material.",
+      "- Inherited history may be compacted or truncated. If an older detail is essential and may fall outside the retained history, include it explicitly in task or context.",
       "",
       "AVAILABLE ROLES:",
       ...entries.map(([name, role]) => `  - ${name}: ${role.description}`),
@@ -250,7 +252,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     rebuildGuidelines(availableRoles);
   });
 
-  pi.on("context", async (event) => {
+  pi.on("context", async (event, ctx) => {
     // Completion notices are persisted custom messages so the user can see
     // them in the transcript, but they are deliberately UI-only. Keep the
     // model on the reminder/check path instead of duplicating the notice in
@@ -260,10 +262,16 @@ export default function subagentExtension(pi: ExtensionAPI) {
         message.role !== "custom" || message.customType !== BACKGROUND_COMPLETION_MESSAGE_TYPE,
     );
 
-    // The model's inbox: every unclaimed background run, injected at a
-    // cache-stable head position before every provider call. Empty inbox and
-    // no filtered notices → context stays untouched, cache fully stable.
-    const reminder = buildInboxReminder(backgroundRuns.values());
+    // The model's inbox: every background run not yet checked on the active
+    // branch, injected at a cache-stable head position before every provider
+    // call. Delivery state is derived from the session tree (append-only:
+    // branching away drops the check entry, branching back restores it), so
+    // the inbox re-arms itself after tree navigation. Empty inbox and no
+    // filtered notices → context stays untouched, cache fully stable.
+    const reminder = buildInboxReminder(
+      backgroundRuns.values(),
+      collectDeliveredIds(ctx.sessionManager.buildContextEntries()),
+    );
     if (!reminder && messages.length === event.messages.length) return;
     return { messages: reminder ? injectReminder(messages, reminder) : messages };
   });
@@ -295,7 +303,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     name: "subagent_delegate",
     label: "Delegate to subagent",
     description:
-      "Delegate a task to a specialized subagent. By default the call blocks until the run finishes and returns the final output — intermediate tool output stays out of your context. With background: true it returns an id immediately and you collect the result later with subagent_wait/subagent_check. Subagents have no access to this conversation — everything they need must arrive through the parameters.",
+      "Delegate a task to a specialized subagent. By default the call blocks until the run finishes and returns the final output — intermediate tool output stays out of your context. With background: true it returns an id immediately and you collect the result later with subagent_wait/subagent_check. Subagents are isolated by default; inheritConversation optionally injects a filtered snapshot of the active parent branch.",
     promptSnippet: "Delegate tasks to specialized subagents",
     promptGuidelines: guidelines,
 
@@ -303,7 +311,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
       role: Type.String({ description: "Subagent role to use" }),
       task: Type.String({
         description:
-          "The work to do — self-contained: the subagent cannot see this conversation, so restate any requirement or constraint it needs here or in `context`. Instructions only — background material belongs in `context`, reference file paths in `files`.",
+          "The work to do. Without conversation inheritance it must be self-contained, with every requirement or constraint restated here or in `context`; with inheritance it may be a delta against that history. Instructions only — background material belongs in `context`, reference file paths in `files`.",
       }),
       context: Type.Optional(
         Type.String({
@@ -317,6 +325,12 @@ export default function subagentExtension(pi: ExtensionAPI) {
             'Reference file paths for the subagent to read directly (e.g. ["src/auth.ts", "docs/api.md"]). Injected as @file attachments — content stays out of your context window. Prefer this over pasting file contents into context.',
         }),
       ),
+      inheritConversation: Type.Optional(
+        Type.Boolean({
+          description:
+            "Opt in to a text-only, compaction-aware snapshot of the active parent conversation. Omit or false for isolation; true lets task be a delta against inherited history, which may be filtered or truncated.",
+        }),
+      ),
       background: Type.Optional(
         Type.Boolean({
           description:
@@ -361,6 +375,13 @@ export default function subagentExtension(pi: ExtensionAPI) {
         );
       }
 
+      const inheritedConversation = params.inheritConversation
+        ? serializeInheritedConversation(
+            ctx.sessionManager.buildContextEntries(),
+            config.inheritance.maxChars,
+          )
+        : undefined;
+
       const run = startSubagentRun({
         id: `sub-${++runCounter}`,
         toolCallId: _toolCallId,
@@ -369,6 +390,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
         task: params.task,
         context: params.context,
         files: params.files,
+        inheritConversation: params.inheritConversation === true,
+        inheritedConversation: inheritedConversation?.text,
+        inheritedConversationTruncated: inheritedConversation?.truncated,
         cwd: params.cwd ?? ctx.cwd,
         depth: CURRENT_DEPTH + 1,
         // Foreground runs die with the tool call; background runs outlive the turn.
@@ -386,9 +410,10 @@ export default function subagentExtension(pi: ExtensionAPI) {
         backgroundRuns.set(run.id, run);
         const runGeneration = sessionGeneration;
         void run.promise.then((result) => {
-          // A collected run already has a visible check result. Do not emit a
-          // second notice, and never publish completions from an old session.
-          if (!backgroundRuns.has(run.id) || runGeneration !== sessionGeneration) return;
+          // Never publish completions from an old session. Within a session
+          // every completion emits its UI-only notice card once — check
+          // results never suppress it (they are not LLM-visible either way).
+          if (runGeneration !== sessionGeneration) return;
 
           const outcome = isFailedResult(result)
             ? "failed"
@@ -420,6 +445,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
             task: params.task,
             context: params.context,
             files: params.files,
+            inheritConversation: params.inheritConversation === true,
+            inheritedConversationChars: inheritedConversation?.text.length,
+            inheritedConversationTruncated: inheritedConversation?.truncated,
           },
         };
       }
@@ -543,16 +571,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
       const unknown = ids.filter((id) => !backgroundRuns.has(id));
       if (unknown.length > 0) {
         const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
-        const collectedNotes = unknown
-          .filter((id) => collectedRuns.has(id))
-          .map((id) => `${id} was already collected (result is in your history)`);
-        const trulyUnknown = unknown.filter((id) => !collectedRuns.has(id));
-        const parts = [
-          `Unknown subagent id(s): ${trulyUnknown.length > 0 ? trulyUnknown.join(", ") : "(none)"}.`,
-          collectedNotes.length > 0 ? `${collectedNotes.join("; ")}.` : "",
-          `Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
-        ].filter(Boolean);
-        throw new Error(parts.join(" "));
+        throw new Error(
+          `Unknown subagent id(s): ${unknown.join(", ")}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
+        );
       }
       const runs = ids.map((id) => backgroundRuns.get(id)!);
       const timeoutMs =
@@ -659,7 +680,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     name: "subagent_check",
     label: "Check a background subagent",
     description:
-      "Get an instant snapshot of ONE background subagent run: queued / running (with current activity) / finished (with the full output as the run result) / failed (with reason and partial output). Does not wait — use subagent_wait for that. Checking a terminal run collects it: the output is returned once and the run leaves the background registry. One id per call because results can be large.",
+      "Get an instant snapshot of ONE background subagent run: queued / running (with current activity) / finished (with the full output as the run result) / failed (with reason and partial output). Does not wait — use subagent_wait for that. Idempotent: checking a terminal run again re-delivers the same snapshot, so the result stays reachable even after branch navigation or compaction. One id per call because results can be large.",
     promptSnippet: "Inspect a background subagent run",
     parameters: Type.Object({
       id: Type.String({ description: "Run id returned by a background delegate call" }),
@@ -668,12 +689,6 @@ export default function subagentExtension(pi: ExtensionAPI) {
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const run = backgroundRuns.get(params.id);
       if (!run) {
-        const collected = collectedRuns.get(params.id);
-        if (collected) {
-          throw new Error(
-            `${params.id} (${collected.role}) was already collected — its result is in your conversation history. Check the remaining runs or delegate new ones.`,
-          );
-        }
         const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
         throw new Error(
           `Unknown subagent id: ${params.id}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
@@ -683,19 +698,6 @@ export default function subagentExtension(pi: ExtensionAPI) {
       // Freeze live frames so the snapshot's elapsed time stays static.
       const snap = run.result ? run.snapshot : freezeFrame(run.snapshot);
 
-      // Read-once collection: a terminal check returns the result AND frees
-      // the run — the output now lives in the conversation history, so the
-      // registry keeps only a lightweight tombstone for id resolution.
-      if (run.state === "finished" || run.state === "failed") {
-        backgroundRuns.delete(run.id);
-        collectedRuns.set(run.id, {
-          id: run.id,
-          role: run.role,
-          task: taskPreview(run.task),
-          state: run.state,
-        });
-      }
-
       return {
         content: [{ type: "text", text: formatCheckText(run.id, run.role, snap) }],
         details: { id: run.id, role: run.role, result: snap },
@@ -710,7 +712,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     name: "subagent_steer",
     label: "Steer a running background subagent",
     description:
-      "Queue a mid-run correction into ONE running background subagent — typically right after subagent_check showed it heading down a wrong path. The message is delivered after the child finishes its current tool batch, before its next LLM call; the run keeps its progress (unlike cancel). Only running runs accept steering; queued runs reject it, and terminal runs are collected by check instead. Typical flow: check → steer → check again later.",
+      "Queue a mid-run correction into ONE running background subagent — typically right after subagent_check showed it heading down a wrong path. The message is delivered after the child finishes its current tool batch, before its next LLM call; the run keeps its progress (unlike cancel). Only running runs accept steering; queued runs reject it, and check is the tool for terminal runs. Typical flow: check → steer → check again later.",
     promptSnippet: "Send a mid-run correction to a background subagent",
     parameters: Type.Object({
       id: Type.String({ description: "Run id returned by a background delegate call" }),
@@ -723,12 +725,6 @@ export default function subagentExtension(pi: ExtensionAPI) {
     async execute(_toolCallId, params) {
       const run = backgroundRuns.get(params.id);
       if (!run) {
-        const collected = collectedRuns.get(params.id);
-        if (collected) {
-          throw new Error(
-            `${params.id} (${collected.role}) was already collected — nothing left to steer. Delegate a new run if a correction is still needed.`,
-          );
-        }
         const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
         throw new Error(
           `Unknown subagent id: ${params.id}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
@@ -752,16 +748,19 @@ export default function subagentExtension(pi: ExtensionAPI) {
             text: `Steer queued for ${params.id} (${run.role}) — delivered after its current tool batch. Verify the effect with subagent_check later.`,
           },
         ],
-        details: { id: params.id, role: run.role },
+        details: { id: params.id, role: run.role, message: params.message },
       };
     },
+
+    renderCall: createSteerCallRender((id) => backgroundRuns.get(id)?.role),
+    renderResult: renderSteerResult,
   });
 
   pi.registerTool({
     name: "subagent_cancel",
     label: "Cancel a background subagent",
     description:
-      "Cancel ONE background subagent run (queued or running): the child process is killed and the run settles as cancelled (its own stop reason, same family as timeout — partial output kept), NOT as a plain failure. The reason is recorded with the run: whoever reads the partial output later via subagent_check sees why it was stopped. Cancelling does not collect — check still returns the partial output once. A finished/failed run cannot be cancelled; check it instead.",
+      "Cancel ONE background subagent run (queued or running): the child process is killed and the run settles as cancelled (its own stop reason, same family as timeout — partial output kept), NOT as a plain failure. The reason is recorded with the run: whoever reads the partial output later via subagent_check sees why it was stopped. Cancelling does not remove the run — check still returns the partial output. A finished/failed run cannot be cancelled; check it instead.",
     promptSnippet: "Cancel a background subagent run",
     parameters: Type.Object({
       id: Type.String({ description: "Run id returned by a background delegate call" }),
@@ -776,21 +775,16 @@ export default function subagentExtension(pi: ExtensionAPI) {
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const run = backgroundRuns.get(params.id);
       if (!run) {
-        const collected = collectedRuns.get(params.id);
-        if (collected) {
-          throw new Error(
-            `${params.id} (${collected.role}) was already collected — its result is in your conversation history. There is nothing left to cancel.`,
-          );
-        }
         const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
         throw new Error(
           `Unknown subagent id: ${params.id}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
         );
       }
 
-      // Terminal runs cannot be cancelled — point at the collector instead.
+      // Terminal runs cannot be cancelled — point at check instead.
       if (run.state === "finished" || run.state === "failed") {
-        const what = run.state === "finished" ? "its result" : "the failure reason and partial output";
+        const what =
+          run.state === "finished" ? "its result" : "the failure reason and partial output";
         const text =
           `${params.id} (${run.role}) already ${run.state} — nothing to cancel. ` +
           `subagent_check(${params.id}) returns ${what}.`;
@@ -822,8 +816,8 @@ export default function subagentExtension(pi: ExtensionAPI) {
   pi.registerCommand("subagent:view", {
     description: "Open the live subagent activity view (watch progress, steer runs)",
     handler: async (_args, ctx) => {
-      // Union of every known run: background registry (until collected) plus
-      // live in-flight runs (foreground delegate calls included). Dedupe by id —
+      // Union of every known run: the background registry plus live
+      // in-flight runs (foreground delegate calls included). Dedupe by id —
       // background runs appear in both.
       const runsProvider = () => {
         const seen = new Set<string>();
@@ -942,40 +936,31 @@ export default function subagentExtension(pi: ExtensionAPI) {
   pi.registerCommand("subagent:status", {
     description: "List background subagent runs and their current state",
     handler: async (_args, ctx) => {
-      if (backgroundRuns.size === 0 && collectedRuns.size === 0) {
+      if (backgroundRuns.size === 0) {
         ctx.ui.notify("No background runs.", "info");
         return;
       }
       const lines: string[] = [];
-      if (backgroundRuns.size > 0) {
-        lines.push("Active:");
-        for (const run of backgroundRuns.values()) {
-          // Freeze live frames so elapsed-dependent details don't drift in the listing.
-          const snap = run.result ? run.snapshot : freezeFrame(run.snapshot);
-          let icon: string;
-          let detail: string;
-          if (run.state === "failed") {
-            icon = "\u2717";
-            detail = snap.errorMessage || "unknown error";
-          } else if (run.state === "finished") {
-            icon = "\u2713";
-            detail = snap.summary || taskPreview(snap.output) || "(no output)";
-          } else if (run.state === "queued") {
-            icon = "\u23F8";
-            detail = "queued — waiting for a concurrency slot";
-          } else {
-            icon = "\u23F3";
-            detail = `running — ${describeCurrentActivity(snap)}`;
-          }
-          lines.push(`${icon} ${run.id} (${run.role}): ${detail}`);
-        }
-      }
-      if (collectedRuns.size > 0) {
-        if (lines.length > 0) lines.push("");
-        lines.push("Collected (result already returned via subagent_check):");
-        for (const c of collectedRuns.values()) {
-          lines.push(`\u2713 ${c.id} (${c.role}): ${c.state} — "${c.task}"`);
+      lines.push("Runs:");
+      for (const run of backgroundRuns.values()) {
+        // Freeze live frames so elapsed-dependent details don't drift in the listing.
+        const snap = run.result ? run.snapshot : freezeFrame(run.snapshot);
+        let icon: string;
+        let detail: string;
+        if (run.state === "failed") {
+          icon = "\u2717";
+          detail = snap.errorMessage || "unknown error";
+        } else if (run.state === "finished") {
+          icon = "\u2713";
+          detail = snap.summary || taskPreview(snap.output) || "(no output)";
+        } else if (run.state === "queued") {
+          icon = "\u23F8";
+          detail = "queued — waiting for a concurrency slot";
+        } else {
+          icon = "\u23F3";
+          detail = `running — ${describeCurrentActivity(snap)}`;
         }
+        lines.push(`${icon} ${run.id} (${run.role}): ${detail}`);
       }
       ctx.ui.notify(lines.join("\n"), "info");
     },
@@ -1018,13 +1003,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
       }
 
       if (target !== "all" && !backgroundRuns.has(target)) {
-        const collected = collectedRuns.get(target);
         const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
         ctx.ui.notify(
-          (collected
-            ? `${target} (${collected.role}) was already collected — nothing to cancel.`
-            : `Unknown subagent id: ${target}.`) +
-            ` Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
+          `Unknown subagent id: ${target}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
           "error",
         );
         return;
@@ -1034,7 +1015,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
       // reported as already-terminal instead of cancelled.
       const targets =
         target === "all"
-          ? [...backgroundRuns.values()].filter((r) => r.state === "queued" || r.state === "running")
+          ? [...backgroundRuns.values()].filter(
+              (r) => r.state === "queued" || r.state === "running",
+            )
           : [backgroundRuns.get(target)!];
       if (targets.length === 0) {
         ctx.ui.notify("No live background runs to cancel.", "info");

package/src/inheritance.test.ts

@@ -0,0 +1,217 @@
+/** Tests for deterministic parent-conversation serialization. */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SessionManager, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { serializeInheritedConversation as createSnapshot } from "./inheritance.ts";
+
+function serializeInheritedConversation(entries: SessionEntry[], maxChars: number): string {
+  return createSnapshot(entries, maxChars).text;
+}
+
+function entries(items: unknown[]): SessionEntry[] {
+  return items as SessionEntry[];
+}
+
+const base = (type: string, id: string, extra: Record<string, unknown> = {}) => ({
+  type,
+  id,
+  parentId: null,
+  timestamp: "2026-01-01T00:00:00.000Z",
+  ...extra,
+});
+
+test("serializes only user/assistant text while filtering tool and UI state", () => {
+  const output = serializeInheritedConversation(
+    entries([
+      base("message", "u", { message: { role: "user", content: "Need a change" } }),
+      base("message", "a", {
+        message: {
+          role: "assistant",
+          content: [
+            { type: "thinking", thinking: "private" },
+            { type: "text", text: "I will delegate this." },
+            {
+              type: "toolCall",
+              id: "call",
+              name: "subagent_delegate",
+              arguments: { secret: "no" },
+            },
+          ],
+        },
+      }),
+      base("message", "tool", {
+        message: {
+          role: "toolResult",
+          toolName: "bash",
+          content: [{ type: "text", text: "secret output" }],
+        },
+      }),
+      base("custom_message", "ui", { content: "UI state" }),
+      base("custom", "state", { data: { token: "no" } }),
+      base("message", "bash", { message: { role: "bashExecution", output: "shell output" } }),
+    ]),
+    10_000,
+  );
+
+  assert.equal(output, "[user]\nNeed a change\n\n[assistant]\nI will delegate this.");
+  assert.ok(!output.includes("private"));
+  assert.ok(!output.includes("secret"));
+  assert.ok(!output.includes("UI state"));
+  assert.ok(!output.includes("shell output"));
+});
+
+test("preserves active entry order, compaction summaries, and retained tails", () => {
+  const output = serializeInheritedConversation(
+    entries([
+      base("compaction", "c", {
+        summary: "Earlier work",
+        retainedTail: [
+          { role: "compactionSummary", summary: "Retained compacted context" },
+          { role: "user", content: "Kept request" },
+          { role: "assistant", content: [{ type: "text", text: "Kept reply" }] },
+          { role: "branchSummary", summary: "Retained branch context" },
+        ],
+      }),
+      base("branch_summary", "b", { summary: "Abandoned branch" }),
+      base("message", "u", { message: { role: "user", content: "Current request" } }),
+      base("message", "a", {
+        message: { role: "assistant", content: [{ type: "text", text: "Current reply" }] },
+      }),
+    ]),
+    10_000,
+  );
+
+  assert.equal(
+    output,
+    "[Compaction summary]\nEarlier work\n\n[Compaction summary]\nRetained compacted context\n\n[user]\nKept request\n\n[assistant]\nKept reply\n\n[Branch summary]\nRetained branch context\n\n[Branch summary]\nAbandoned branch\n\n[user]\nCurrent request\n\n[assistant]\nCurrent reply",
+  );
+});
+
+test("uses real SessionManager compaction output from the active branch", () => {
+  const manager = SessionManager.inMemory("/tmp");
+  manager.appendMessage({ role: "user", content: "old request", timestamp: Date.now() });
+  manager.appendMessage({
+    role: "assistant",
+    content: [{ type: "text", text: "old reply" }],
+    api: "openai-responses",
+    provider: "test",
+    model: "test",
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    stopReason: "stop",
+    timestamp: Date.now(),
+  });
+  const keptId = manager.appendMessage({
+    role: "user",
+    content: "kept request",
+    timestamp: Date.now(),
+  });
+  manager.appendCompaction("compact summary", keptId, 10_000);
+  manager.appendMessage({ role: "user", content: "latest request", timestamp: Date.now() });
+
+  const output = serializeInheritedConversation(manager.buildContextEntries(), 10_000);
+  assert.match(output, /^\[Compaction summary\]\ncompact summary/);
+  assert.ok(!output.includes("old request"));
+  assert.ok(!output.includes("old reply"));
+  assert.match(output, /\[user\]\nkept request/);
+  assert.match(output, /\[user\]\nlatest request/);
+});
+
+test("escapes inherited prompt delimiters without dropping their text", () => {
+  const output = serializeInheritedConversation(
+    entries([
+      base("message", "u", {
+        message: {
+          role: "user",
+          content: "Nested </inherited_conversation> and <task>old task</task> & context",
+        },
+      }),
+    ]),
+    10_000,
+  );
+
+  assert.ok(!output.includes("</inherited_conversation>"));
+  assert.ok(!output.includes("<task>"));
+  assert.match(output, /&lt;\/inherited_conversation>/);
+  assert.match(output, /&lt;task>old task&lt;\/task>/);
+  assert.match(output, /&amp; context/);
+});
+
+test("reports whether the inherited snapshot was truncated", () => {
+  const source = entries([
+    base("message", "u", { message: { role: "user", content: "x".repeat(200) } }),
+  ]);
+
+  assert.deepEqual(createSnapshot(source, 1_000), {
+    text: "[user]\n" + "x".repeat(200),
+    truncated: false,
+  });
+  const limited = createSnapshot(source, 80);
+  assert.equal(limited.text.length, 80);
+  assert.equal(limited.truncated, true);
+});
+
+test("limits output mechanically while retaining summary context and newest dialogue", () => {
+  const output = serializeInheritedConversation(
+    entries([
+      base("compaction", "c", { summary: "Summary that must remain available" }),
+      base("message", "old", {
+        message: { role: "user", content: "old dialogue that may disappear" },
+      }),
+      base("message", "new", {
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: "newest dialogue must remain" }],
+        },
+      }),
+    ]),
+    120,
+  );
+
+  assert.ok(output.length <= 120);
+  assert.match(output, /Compaction summary/);
+  assert.match(output, /omitted for length/);
+  assert.match(output, /\[assistant\]/);
+  assert.match(output, /dialogue must remain/);
+});
+
+test("honors every hard limit, including delimiter expansion and tiny bounds", () => {
+  const source = entries([
+    base("compaction", "c", { summary: `<summary>${"S".repeat(120)}</summary>` }),
+    base("message", "u", {
+      message: { role: "user", content: `<task>${"U".repeat(180)}</task>` },
+    }),
+    base("message", "a", {
+      message: { role: "assistant", content: [{ type: "text", text: "A".repeat(180) }] },
+    }),
+  ]);
+
+  for (let limit = 1; limit <= 300; limit += 1) {
+    assert.ok(serializeInheritedConversation(source, limit).length <= limit);
+  }
+});
+
+test("redistributes unused summary budget to recent complete dialogue", () => {
+  const output = serializeInheritedConversation(
+    entries([
+      base("compaction", "c", { summary: "short" }),
+      base("message", "old", { message: { role: "user", content: "O".repeat(220) } }),
+      base("message", "new", {
+        message: { role: "assistant", content: `latest-${"N".repeat(80)}` },
+      }),
+    ]),
+    240,
+  );
+
+  assert.equal(output.length, 240);
+  assert.match(output, /^\[Compaction summary\]\nshort/);
+  assert.match(output, /\[assistant\]\nlatest-/);
+  assert.match(output, /Earlier text in this message omitted/);
+});