@esso0428/pi-subagents 0.17.33 → 0.17.35

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.35] - 2026-10-05
+
+### Added
+- **Scope agent history and the roster to the current session**: agent records now carry the session that spawned them, so `/agents` offers `Agent history this session` alongside `Agent history all sessions`, and the above-editor roster shows only this session's agents. Records restored from a session branch are stamped with the current session — a fork continues its parent's context, so those agents count as present here — while records reloaded from project checkpoints keep their own stamp, because those files mix every session that ran in the directory.
+- **Legacy session history**: `/agents` → `Agent history all sessions` also recovers `subagents:record` entries written by earlier builds, so history from before durable checkpoints stayed reachable. Nothing writes those entries any more, and the scan is scoped to the project's own session directory.
+
+### Changed
+- **Stopped appending `subagents:record` to the session branch on completion**: durable checkpoints supersede it. They survive reboot, record the owning session, and do not grow the parent session file. The entry is still read for backward compatibility.
+
+### Fixed
+- **Orphaned nested rows keep their place**: a nested child whose parent record was removed keeps its original indent and says its parent is gone, instead of being promoted to a top-level row.
+
+## [0.17.34] - 2026-10-05
+
+### Added
+- **Documented nested subagents**: README now carries the feature entry, the `allowed_subagents` frontmatter row, and a `### Nested subagents` section covering the allowlist as a privilege boundary, depth cap, ownership scoping, pool behaviour, transcript durability, and how this fork diverges from upstream by rendering children as a navigable subtree. Also records that the mechanism is hand-authored and deliberately absent from the tool description, so a model never grants itself delegation.
+
 ## [0.17.33] - 2026-10-05
 
 ### Fixed

package/README.md

@@ -17,6 +17,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Agents panel UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, colored status icons, and one focus-gated navigator. It shows every agent by default; press `↓` at an empty prompt to activate the panel, `↑`/`↓` to select, `Enter` to open a live or read-only history viewer, and `Esc` to return. Long rosters reserve a right-hand track/thumb scrollbar and show `↑ N more` or `↓ N more` at the clipped edge. Configure via `/agents → Settings → Widget`: `all`, `background`, or `off`
 - **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause). The main viewer reserves a right-hand scrollbar rail for the transcript and exposes a `[preview]` header action for the focused tool. Steer a running agent inline by pressing `e` to open a Pi-native composer, typing, then `Enter` to send (`Esc` or an empty submit returns); the follow-up appears as a muted/gray USER message and redirects the agent after its current tool. `Alt+Up` (`a-up`/`alt+up`) recalls submitted follow-up drafts. Read-only tool previews replace the viewer in place, use the larger viewport with the same right-hand track/thumb scrollbar and top/bottom hidden-line affordances, and return with `Esc`, `q`, or the close control. Stop a still-running agent by pressing `x` (then `x` again to confirm) — both work for background agents too
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` or `.agents/agents/<name>.md` (project) or globally, with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
+- **Nested subagents** — opt-in, default-off delegation: an agent whose frontmatter sets `allowed_subagents` gets its own ownership-scoped `Agent`, a blocking `wait_for_nested_agent`, and a scoped `steer_subagent`, depth-capped from the main session (default 2). Unlike upstream, nested children are **not** hidden — the agents roster renders them as an indented subtree you can navigate into. The allowlist is a privilege boundary, so it is set by hand in the agent file and never enabled automatically
 - **Mid-run steering** — inject messages into running agents to redirect their work without restarting
 - **Session resume** — pick up where an agent left off, preserving full conversation context
 - **Durable interruption recovery** — catchable shutdowns preserve running/queued metadata and partial transcripts so interrupted agents remain indexed after reload; abrupt `SIGKILL` termination cannot be checkpointed
@@ -246,6 +247,7 @@ All fields are optional — sensible defaults for everything.
 | `skills` | `true` | Inherit skills from parent. Can be a comma-separated list of skill names to preload (see [Skill Preloading](#skill-preloading) for discovery locations) |
 | `memory` | — | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents |
 | `disallowed_tools` | — | Comma-separated tools to deny even if extensions provide them |
+| `allowed_subagents` | none | Opt in to scoped nested `Agent`, `wait_for_nested_agent`, and `steer_subagent` tools. Omitted / empty / `none` / `false` = no nesting; `all` (or `"*"` / `true`) = any enabled agent; comma-separated list = only those agent types |
 | `isolation` | — | Set to `worktree` to run in an isolated git worktree |
 | `model` | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`). Resolved tolerantly (`.`/`-` and a trailing date stamp are interchangeable) and falls back to the same model under another provider if the named one doesn't have it |
 | `thinking` | inherit | off, minimal, low, medium, high, xhigh, max — actual availability depends on your pi version and model; pi clamps unsupported levels down |
@@ -300,6 +302,69 @@ A few rules the examples don't make obvious:
 - `exclude_extensions:` is **not a sandbox**: excluded extensions' factory code still executes once during loading. Exclusion suppresses their tools and their bound lifecycle hooks (`pi.on` handlers like `session_start` only fire for extensions bound to the session), but not other load-time side effects — a factory that subscribes directly to the shared `pi.events` bus stays live. Don't rely on it to contain an untrusted extension.
 - Array and string forms are equivalent: `[a, b]` == `"a, b"`.
 
+### Nested subagents
+
+Nested delegation is default-off and hand-authored. An agent that owns a real
+fan-out responsibility opts in by setting `allowed_subagents` in its own
+frontmatter:
+
+```yaml
+# .pi/agents/support-coordinator.md
+---
+name: support-coordinator
+description: Coordinates support-triage work across several areas
+allowed_subagents: support-file-finder, support-callsite-tracer
+tools: read, grep, find, ls
+---
+```
+
+Omitted, empty, `none`, or `false` means no nested tools are injected at all.
+`all` (or `"*"` / `true`) allows any enabled agent; a comma-separated list
+restricts nesting to exactly those types. Unknown, disabled, and out-of-list
+types are **rejected**, never fallen back to — a configured fallback agent
+cannot hand a nested caller something outside its allowlist.
+
+**The allowlist is a privilege boundary.** A nested child runs with its own tool
+set, so choose it as carefully as you would `tools:`. It is set by hand in the
+agent file and is never enabled automatically; no skill or tool description
+teaches a model to grant itself delegation.
+
+A nested child receives an ownership-scoped `Agent`, a `wait_for_nested_agent`
+that always blocks until that child finishes, and a `steer_subagent` scoped to
+its own children. Result, resume, and steer are ownership-checked, so a parent
+cannot read, steer, or resume a foreign child. `maxSubagentDepth` caps how deep
+nesting goes (default 2: main session 0, its subagents 1, nested children 2);
+an agent already at the cap receives no nested tools at all — not even
+`wait_for_nested_agent` — since it can never own a child. Change it project-wide
+via `maxSubagentDepth` in `subagents.json` or `/agents` → Settings → Nested
+depth. Nested children occupy no concurrency slot: their parent already holds
+one, and queueing a child behind its own parent would deadlock.
+
+Nested children consume **no** concurrency slot and are never reported to the
+main session as top-level agents — their completion surfaces inside the parent,
+and their token usage folds into every ancestor's total. Each still writes its
+own durable transcript.
+
+### How nested children are shown
+
+Upstream hides nested children from every surface. This fork keeps the same
+reporting semantics but makes the hierarchy visible: the agents roster renders
+children as an indented subtree, each with its own spinner and activity line,
+token counts marked `(in parent)` so totals are not double-counted, and a
+`nested blocked: …` note when the allowlist or depth cap refuses a dispatch.
+`↑`/`↓` move across every visible row regardless of depth and `Enter` opens that
+level's conversation viewer. Because the lookup is case-insensitive, an override
+named `Explore` also changes what a lowercase `explore` request resolves to.
+
+The `parentAgentId` and `depth` of a nested child are recorded in its recovery
+checkpoint, so a reload rebuilds the same subtree rather than flattening it. If
+a parent record is ever removed before its child, the child keeps its indent and
+says its parent is gone.
+
+`subagents.agentOverrides` applies to nested dispatch exactly as it does at
+top level, including the project-over-global precedence described in
+[Priority Chain](#priority-chain).
+
 ## `npm:pi-subagents`-Style JSON Agent Overrides
 
 This fork adds the ability to configure — and even create — agents entirely through JSON,

package/ROADMAP.md

@@ -12,6 +12,18 @@
 - v0.17.6 的 ConversationViewer baseline（scrollbar rail、`[preview]`/`[Esc]`、`w` preview、in-place read-only Tool Output、鍵盤與 wheel scroll）不可被改寫
 - 資源安全政策不因功能恢復而撤回：Vitest / E2E / build 在此裝置需明確授權
 
+## 未來：讓模型知道 nested 怎麼用
+
+`allowed_subagents` 目前只能由人手寫進 agent 檔案。上游刻意如此 — 它的 `Agent` 工具描述、`promptGuidelines`、`skills/`、範例 agent 檔全都沒有提 nested，所以模型不會自己開自己的權限。這是對的安全立場，不是缺陷。
+
+若要改善可用性，安全作法是**只教模型怎麼「建議」**，不給它自己開的權限：
+
+- 在建立/編輯 agent 檔案的流程裡提示 `allowed_subagents` 的存在與語意（`all` / 逗號清單 / 省略 = 不開）
+- 明確標示這是授權邊界，該由人確認，不接受模型自行套用
+- 不在 `Agent` 工具描述或 `promptGuidelines` 中指示模型對既有 agent 開啟巢狀
+
+設計前提未定：這段提示該放哪（工具描述、skill、`/agents` 建立精靈的表單、還是 agent 檔的模板註解），以及如何避免模型把「建議」當成「已授權」。
+
 ## 交付 B：Workflow
 
 上游規模約 6,200 行：`src/workflow/**` 11 檔約 4,458 行（`runtime.ts` 1,219 + `worker-source.ts` 781 為骨幹）、`ui/workflow-*.ts` 3 檔約 1,778 行（`workflow-dialog.ts` 1,115 最大）。含 `node:vm` sandbox、worker thread、journal，是新的執行模型而非 UI，風險等級與 nested 不同，不與其他交付合併。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.17.33",
+  "version": "0.17.35",
   "description": "A pi extension that brings smart Claude Code-style autonomous sub-agents to pi, with npm:pi-subagents-style JSON agent overrides.",
   "author": "ESSO0428",
   "repository": {

package/src/agent-history-list.ts

@@ -82,10 +82,18 @@ export function formatAgentHistoryOption(record: AgentRecord, now: number): stri
 export function buildAgentStatusMenuEntries(
   records: readonly AgentRecord[],
   cwd: string | undefined,
+  sessionId?: string,
 ): string[] {
   const { active, history } = splitAgentRecords(records, cwd);
+  // This-session history is what you almost always want, so it is the default
+  // entry. Project-wide history stays one keystroke away for the occasional
+  // "which agent was that, two sessions ago" lookup. Records restored from a
+  // branch or checkpoint are stamped with the current session, so an inherited
+  // agent counts as present here rather than disappearing into the other bucket.
+  const inSession = sessionId ? history.filter((record) => record.sessionId === sessionId) : [];
   return [
     ...(active.length > 0 ? [`Running agents (${active.length})`] : []),
-    ...(history.length > 0 ? [`Agent history (${history.length})`] : []),
+    ...(inSession.length > 0 ? [`Agent history this session (${inSession.length})`] : []),
+    ...(history.length > 0 ? [`Agent history all sessions (${history.length})`] : []),
   ];
 }

package/src/agent-manager.ts

@@ -159,6 +159,8 @@ interface SpawnArgs {
 }
 
 export interface SpawnOptions extends Partial<Omit<NestedSpawnOptions, "description" | "signal" | "onAssistantUsage" | "onSessionCreated">> {
+  /** Overrides the session stamp applied at spawn (used by restore paths). */
+  sessionId?: string;
   description: string;
   model?: Model<any>;
   maxTurns?: number;
@@ -284,6 +286,7 @@ export class AgentManager {
       // flattens, because nothing on disk records the nesting.
       ...(record.parentAgentId !== undefined && { parentAgentId: record.parentAgentId }),
       ...(record.depth !== undefined && { depth: record.depth }),
+      ...(record.sessionId !== undefined && { sessionId: record.sessionId }),
     };
     return checkpoint;
   }
@@ -341,6 +344,10 @@ export class AgentManager {
         this.recoveryCwds.set(checkpoint.id, cwd);
         continue;
       }
+      // No session stamp here: these files are project-level and mix every
+      // session that ever ran in this directory. Re-stamping them would make
+      // "this session" mean "everything", which is the thing the scope exists to
+      // avoid. Records with no stamp stay reachable under the all-sessions entry.
       this.agents.set(checkpoint.id, this.createRestoredRecord({
         ...checkpoint,
         status,
@@ -391,6 +398,7 @@ export class AgentManager {
       parentDescription: options.parentAgentId ? this.agents.get(options.parentAgentId)?.description : undefined,
       maxSubagentDepth: options.maxSubagentDepth,
       rootSessionId: options.rootSessionId ?? ctx.sessionManager?.getSessionId?.(),
+      sessionId: options.sessionId ?? ctx.sessionManager?.getSessionId?.(),
       liveActivity: {
         activeTools: new Map(),
         responseText: "",
@@ -780,11 +788,16 @@ export class AgentManager {
   }
 
   /** Restore terminal records persisted by a parent branch without runtime handles. */
-  restoreCompleted(records: readonly unknown[]): void {
+  /**
+   * Restore terminal records carried by a parent branch. A fork continues its
+   * parent's context, so those agents count as present in this session and are
+   * stamped with the current session id rather than the one that spawned them.
+   */
+  restoreCompleted(records: readonly unknown[], sessionId?: string): void {
     const latest = new Map<string, ReturnType<typeof this.createRestoredRecord>>();
     for (const value of records) {
       if (isRestorableAgentRecord(value)) {
-        latest.set(value.id, this.createRestoredRecord(value));
+        latest.set(value.id, this.createRestoredRecord({ ...value, sessionId }));
       }
     }
 
@@ -811,6 +824,7 @@ export class AgentManager {
     compactionCount?: number;
     parentAgentId?: string;
     depth?: number;
+    sessionId?: string;
   }): AgentRecord {
     return {
       id: record.id,
@@ -830,6 +844,7 @@ export class AgentManager {
       compactionCount: record.compactionCount ?? 0,
       parentAgentId: record.parentAgentId,
       depth: record.depth,
+      sessionId: record.sessionId,
     };
   }
 

package/src/agent-recovery.ts

@@ -36,6 +36,13 @@ export interface AgentRecoveryCheckpoint {
   parentAgentId?: string;
   /** Nesting depth of a nested child; absent on top-level agents. */
   depth?: number;
+  /**
+   * Session this record was spawned in. Absent on older checkpoints, and
+   * re-stamped with the *current* session when a branch or checkpoint restore
+   * brings the record forward, so "this session" means "present in this session"
+   * rather than "originally spawned here".
+   */
+  sessionId?: string;
 }
 
 function isSafeString(value: unknown, maxLength: number): value is string {
@@ -104,6 +111,7 @@ export function isAgentRecoveryCheckpoint(value: unknown): value is AgentRecover
     || (checkpoint.compactionCount as number) < 0) return false;
 
   if (checkpoint.parentAgentId !== undefined && !isSafeString(checkpoint.parentAgentId, 256)) return false;
+  if (checkpoint.sessionId !== undefined && !isSafeString(checkpoint.sessionId, 256)) return false;
   if (checkpoint.depth !== undefined && (!Number.isInteger(checkpoint.depth) || (checkpoint.depth as number) < 0)) return false;
 
   const status = checkpoint.status as AgentRecoveryStatus;

package/src/index.ts

@@ -26,6 +26,7 @@ import { loadCustomAgents } from "./custom-agents.js";
 import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
 import { GroupJoinManager } from "./group-join.js";
 import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
+import { readLegacySessionRecords } from "./legacy-session-records.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { isScopeModelsEnabled, setScopeModelsEnabled } from "./model-scope.js";
 import { getMaxSubagentDepth, setMaxSubagentDepth } from "./nested-tools.js";
@@ -443,21 +444,10 @@ export default function (pi: ExtensionAPI) {
       pi.events.emit("subagents:completed", eventData);
     }
 
-    // Persist final record for cross-extension history reconstruction
-    pi.appendEntry("subagents:record", {
-      id: record.id, type: record.type, description: record.description,
-      status: record.status,
-      // Durable transcripts are the source of truth for full output. Avoid
-      // copying a potentially large result into the parent session branch;
-      // get_subagent_result reloads it on demand after cleanup/restart.
-      result: record.transcriptPath ? undefined : record.result,
-      error: record.error,
-      startedAt: record.startedAt, completedAt: record.completedAt,
-      toolUses: record.toolUses,
-      lifetimeUsage: record.lifetimeUsage,
-      invocation: record.invocation,
-      transcriptPath: record.transcriptPath,
-    });
+    // Durable checkpoints replaced this entry: they survive reboot, carry the
+    // owning session, and do not bloat the parent session branch. It is still
+    // read for sessions recorded before that change, so history written by an
+    // older build stays reachable.
 
     // Explicit wait-group members never emit individual notifications. Result
     // consumption does not remove membership; the sealed group still delivers
@@ -590,10 +580,11 @@ export default function (pi: ExtensionAPI) {
     resetAgentMenuSelections();
     currentCtx = ctx;
     manager.clearCompleted(true);
+    const sessionId = ctx.sessionManager?.getSessionId?.();
     const branch = ctx.sessionManager?.getBranch?.() ?? [];
     manager.restoreCompleted(branch
       .filter((entry: any) => entry?.type === "custom" && entry?.customType === "subagents:record")
-      .map((entry: any) => entry.data));
+      .map((entry: any) => entry.data), sessionId);
     // Checkpoint files cover agents whose parent session never got a terminal
     // branch entry (shutdown, session switch, or a process restart).
     manager.restoreRecovered(ctx.cwd);
@@ -666,6 +657,7 @@ export default function (pi: ExtensionAPI) {
         const ctx = currentCtx;
         if (ctx) void viewAgentConversation(ctx as ExtensionCommandContext, record, mode);
       },
+      getSessionId: () => currentCtx?.sessionManager?.getSessionId?.(),
     },
   );
 
@@ -1709,7 +1701,7 @@ Terse command-style prompts produce shallow, generic work.
     // Keep active agents and terminal history in separate menu entries.
     const records = manager.listAgents();
     const { active, history } = splitAgentRecords(records, ctx.cwd);
-    options.push(...buildAgentStatusMenuEntries(records, ctx.cwd));
+    options.push(...buildAgentStatusMenuEntries(records, ctx.cwd, ctx.sessionManager?.getSessionId?.()));
 
     // Agent types list
     if (allNames.length > 0) {
@@ -1742,8 +1734,11 @@ Terse command-style prompts produce shallow, generic work.
     if (choice.startsWith("Running agents (")) {
       await showRunningAgents(ctx);
       await showAgentsMenu(ctx);
-    } else if (choice.startsWith("Agent history (")) {
-      await showAgentHistory(ctx);
+    } else if (choice.startsWith("Agent history this session (")) {
+      await showAgentHistory(ctx, "this-session");
+      await showAgentsMenu(ctx);
+    } else if (choice.startsWith("Agent history all sessions (")) {
+      await showAgentHistory(ctx, "all-sessions");
       await showAgentsMenu(ctx);
     } else if (choice.startsWith("Agent types (")) {
       await showAllAgentsList(ctx);
@@ -1922,21 +1917,39 @@ Terse command-style prompts produce shallow, generic work.
     await showRunningAgents(ctx);
   }
 
-  async function showAgentHistory(ctx: ExtensionCommandContext) {
+  async function showAgentHistory(ctx: ExtensionCommandContext, scope: "this-session" | "all-sessions" = "all-sessions") {
     const { history } = splitAgentRecords(manager.listAgents(), ctx.cwd);
-    if (history.length === 0) {
-      ctx.ui.notify("No agent history.", "info");
+    const sessionId = ctx.sessionManager?.getSessionId?.();
+    const scoped = scope === "this-session" && sessionId
+      ? history.filter((record) => record.sessionId === sessionId)
+      : history;
+    if (scoped.length === 0) {
+      ctx.ui.notify(scope === "this-session" ? "No agent history in this session." : "No agent history.", "info");
       return;
     }
 
-    const pairs = history.map((record) => ({ record, label: formatAgentHistoryOption(record, Date.now()) }));
+    // Sessions recorded before durable checkpoints only exist as
+    // `subagents:record` entries in their session file. They are merged here for
+    // the project-wide view; the this-session view never needs the scan.
+    const merged = scope === "this-session"
+      ? scoped
+      : mergeLegacyRecords(scoped, await readLegacySessionRecords(ctx.cwd));
+    const pairs = merged.map((record) => ({ record, label: formatAgentHistoryOption(record, Date.now()) }));
     makeUniqueAgentOptionLabels(pairs);
-    const record = await selectAgentFromReadOnlyList(ctx, "Agent history", pairs, historyAgentSelection);
+    const title = scope === "this-session" ? "Agent history — this session" : "Agent history — all sessions";
+    const record = await selectAgentFromReadOnlyList(ctx, title, pairs, historyAgentSelection);
     if (!record) return;
 
     await viewAgentConversation(ctx, record, "history");
     // Back-navigation: re-show the list at the previously selected agent.
-    await showAgentHistory(ctx);
+    await showAgentHistory(ctx, scope);
+  }
+
+  /** In-memory records win; legacy session entries only fill genuine gaps. */
+  function mergeLegacyRecords(current: readonly AgentRecord[], legacy: readonly AgentRecord[]): AgentRecord[] {
+    const known = new Set(current.map((record) => record.id));
+    return [...current, ...legacy.filter((record) => !known.has(record.id))]
+      .sort((a, b) => b.startedAt - a.startedAt);
   }
 
   async function viewAgentConversation(

package/src/legacy-session-records.ts

@@ -0,0 +1,159 @@
+import { createReadStream, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { encodeCwd } from "./output-file.js";
+import type { AgentInvocation, AgentRecord } from "./types.js";
+
+/**
+ * Reads `subagents:record` entries out of session files.
+ *
+ * Older builds appended one such entry per finished agent to the parent session
+ * branch. Durable checkpoints superseded that: they survive reboot, carry the
+ * owning session, and do not bloat the session file. This reader exists purely
+ * so history written before that change stays reachable from `/agents`; nothing
+ * writes these entries any more.
+ *
+ * Session files can be very large, so each is streamed line by line and only
+ * lines mentioning the entry type are parsed.
+ */
+
+const RECORD_MARKER = '"subagents:record"';
+const SESSION_EXTENSION = ".jsonl";
+
+/** `<timestamp>_<sessionId>.jsonl` — the sessionId is the part after the first underscore. */
+function sessionIdFromFile(name: string): string | undefined {
+  if (!name.endsWith(SESSION_EXTENSION)) return undefined;
+  const base = name.slice(0, -SESSION_EXTENSION.length);
+  const separator = base.indexOf("_");
+  if (separator < 0) return undefined;
+  const id = base.slice(separator + 1);
+  return /^[0-9a-f-]{8,}$/i.test(id) ? id : undefined;
+}
+
+function isRecordLike(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object") return false;
+  const entry = value as Record<string, unknown>;
+  if (typeof entry.id !== "string" || entry.id.length === 0) return false;
+  return typeof entry.type === "string" && typeof entry.description === "string";
+}
+
+function toRecord(entry: Record<string, unknown>, sessionId: string): AgentRecord {
+  const startedAt = typeof entry.startedAt === "number" ? entry.startedAt : 0;
+  const transcriptPath = typeof entry.transcriptPath === "string" ? entry.transcriptPath : undefined;
+  return {
+    id: entry.id as string,
+    type: entry.type as string,
+    description: entry.description as string,
+    status: (typeof entry.status === "string" ? entry.status : "completed") as AgentRecord["status"],
+    startedAt,
+    completedAt: typeof entry.completedAt === "number" ? entry.completedAt : startedAt,
+    result: typeof entry.result === "string" ? entry.result : undefined,
+    error: typeof entry.error === "string" ? entry.error : undefined,
+    toolUses: typeof entry.toolUses === "number" ? entry.toolUses : 0,
+    compactionCount: 0,
+    lifetimeUsage: (entry.lifetimeUsage as AgentRecord["lifetimeUsage"]) ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    invocation: entry.invocation as AgentInvocation | undefined,
+    transcriptPath,
+    historyFile: transcriptPath,
+    sessionId,
+  };
+}
+
+/** Yield the parsed JSON value of each line that carries the marker. */
+async function* matchingLines(path: string): AsyncGenerator<unknown> {
+  const stream = createReadStream(path, { encoding: "utf-8" });
+  let buffer = "";
+  for await (const chunk of stream) {
+    buffer += chunk;
+    let newline = buffer.indexOf("\n");
+    while (newline >= 0) {
+      const line = buffer.slice(0, newline);
+      buffer = buffer.slice(newline + 1);
+      if (line.includes(RECORD_MARKER)) {
+        try {
+          yield JSON.parse(line);
+        } catch { /* a malformed line must not hide the rest of the session */ }
+      }
+      newline = buffer.indexOf("\n");
+    }
+  }
+  if (buffer.includes(RECORD_MARKER)) {
+    try {
+      yield JSON.parse(buffer);
+    } catch { /* ignore trailing partial line */ }
+  }
+}
+
+function collectEntries(parsed: unknown, out: Record<string, unknown>[]): void {
+  if (Array.isArray(parsed)) {
+    for (const item of parsed) collectEntries(item, out);
+    return;
+  }
+  if (!parsed || typeof parsed !== "object") return;
+  const node = parsed as Record<string, unknown>;
+  if (node.customType === "subagents:record" && isRecordLike(node.data)) {
+    out.push(node.data);
+  }
+  for (const value of Object.values(node)) {
+    if (value && typeof value === "object") collectEntries(value, out);
+  }
+}
+
+/**
+ * Agent records this extension wrote into session files before durable
+ * checkpoints. Sessions whose directory does not exist simply contribute none.
+ */
+export async function readLegacySessionRecords(cwd: string, agentDir: string = getAgentDir()): Promise<AgentRecord[]> {
+  const directory = join(agentDir, "sessions");
+  let files: string[];
+  try {
+    files = readdirSync(directory).filter((name) => name.endsWith(SESSION_EXTENSION));
+  } catch {
+    return [];
+  }
+
+  const records: AgentRecord[] = [];
+  const seen = new Set<string>();
+  void files;
+
+  // pi scopes sessions by project: <sessions>/--<encoded-cwd>--/<file>. Without
+  // this filter every project's agents would show up in every other project.
+  const projectDir = `--${encodeCwd(cwd)}--`;
+  const entriesIn: string[] = [];
+  try {
+    for (const name of readdirSync(directory, { withFileTypes: true })) {
+      if (name.isDirectory() && name.name === projectDir) entriesIn.push(name.name);
+    }
+  } catch {
+    return [];
+  }
+  if (entriesIn.length === 0) return records;
+
+  // Session files live one directory deeper: <sessions>/<encoded-cwd>/<file>.
+  for (const name of entriesIn.map((entryName) => ({ isDirectory: () => true, name: entryName }))) {
+    let sessionFiles: string[];
+    try {
+      sessionFiles = readdirSync(join(directory, name.name));
+    } catch {
+      continue;
+    }
+    for (const sessionFile of sessionFiles) {
+      const sessionId = sessionIdFromFile(sessionFile);
+      if (!sessionId) continue;
+      const entries: Record<string, unknown>[] = [];
+      try {
+        for await (const parsed of matchingLines(join(directory, name.name, sessionFile))) {
+          collectEntries(parsed, entries);
+        }
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (seen.has(entry.id as string)) continue;
+        seen.add(entry.id as string);
+        records.push(toRecord(entry, sessionId));
+      }
+    }
+  }
+  return records;
+}

package/src/types.ts

@@ -140,6 +140,8 @@ export interface AgentRecord {
   depth?: number;
   /** Parent agent ID for ownership-scoped nested controls. */
   parentAgentId?: string;
+  /** Session this record belongs to; re-stamped on restore. */
+  sessionId?: string;
   /** Parent description shown in a nested conversation viewer. */
   parentDescription?: string;
   /** Effective inherited nesting cap for this branch. */

package/src/ui/agent-widget.ts

@@ -57,6 +57,13 @@ export type AgentWidgetOpenCallback = (record: AgentRecord, mode: AgentWidgetOpe
 export type AgentWidgetOptions = {
   canOpenHistory: (record: AgentRecord) => boolean;
   onOpen: AgentWidgetOpenCallback;
+  /**
+   * Current session id. The roster shows only agents belonging to it, so a
+   * long-lived project directory does not fill the widget with work from other
+   * sessions. Read live — the session id is only known once pi has started.
+   * Nested children carry their parent's session id, so trees stay intact.
+   */
+  getSessionId?: () => string | undefined;
 };
 /** @deprecated Use AgentWidgetOpenMode. */
 export type AgentOpenMode = AgentWidgetOpenMode;
@@ -307,6 +314,7 @@ export class AgentWidget {
     private options: AgentWidgetOptions = {
       canOpenHistory: (record) => record.session !== undefined || record.completedAt !== undefined,
       onOpen: () => {},
+      getSessionId: () => undefined,
     },
   ) {}
 
@@ -322,9 +330,15 @@ export class AgentWidget {
    *   - `all`: every agent.
    */
   private widgetAgents() {
-    const all = this.manager.listAgents();
+    if (this.mode() === "off") return [];
+    // Scope to this session before the mode filter. Restored records from other
+    // sessions are still openable through `/agents` history; they just do not
+    // clutter the roster sitting under the editor.
+    const sessionId = this.options.getSessionId?.();
+    const all = sessionId
+      ? this.manager.listAgents().filter(record => record.sessionId === sessionId)
+      : this.manager.listAgents();
     switch (this.mode()) {
-      case "off": return [];
       case "background": return all.filter(a => a.parentAgentId !== undefined || a.isBackground !== false);
       default: return all;
     }