@esso0428/pi-subagents 0.17.34 → 0.17.35

package/CHANGELOG.md

@@ -7,6 +7,18 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.17.34",
+  "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;
     }