@esso0428/pi-subagents 0.17.34 → 0.17.36

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.36] - 2026-10-05
+
+### Fixed
+- **Legacy session history no longer lists records that cannot be opened**: recovering `subagents:record` entries from older sessions bypassed the `canOpenAgentHistory` check that the this-session list, the project-wide list, and the roster all apply, so entries with no durable transcript were offered and could only ever answer "No agent history." They now clear the same bar, which drops roughly half of what the scan recovers.
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.17.34",
+  "version": "0.17.36",
   "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,46 @@ 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.
+    //
+    // They must clear the same `canOpenAgentHistory` bar as everything else:
+    // most carry no durable transcript, and listing an entry that can only ever
+    // answer "No agent history." is a dead link, not history.
+    const merged = scope === "this-session"
+      ? scoped
+      : mergeLegacyRecords(
+        scoped,
+        (await readLegacySessionRecords(ctx.cwd)).filter(record => canOpenAgentHistory(record, 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;
     }