@gotgenes/pi-subagents 17.4.0 → 18.0.0

package/docs/retro/0463-file-snapshot-source-evicted-agents.md

@@ -0,0 +1,103 @@
+---
+issue: 463
+issue_title: "pi-subagents: add file-snapshot source to /subagent-sessions for evicted agents"
+---
+
+# Retro: #463 — pi-subagents: add file-snapshot source to /subagent-sessions for evicted agents
+
+## Stage: Planning (2026-06-23T00:00:00Z)
+
+### Session summary
+
+Produced a 4-step plan for the Phase 19 Step 4b file-snapshot source: implement `fileSnapshotSource(outputFile, readFile)` in the pure `session-navigation.ts`, broaden the `/subagent-sessions` candidate set to evicted agents, and dual-source the handler by `NavigationEntry.kind`.
+The central design fork — how evicted agents enter the picker — was resolved with the operator via `ask_user`.
+
+### Observations
+
+- **Eviction is memory management.**
+  The cleanup sweep's `disposeSession()` frees the in-memory message history; the transcript survives only on disk.
+  So rendering an evicted agent *always* reads the file (`fileSnapshotSource`) regardless of candidate-set strategy — the strategy only affects the picker *label*.
+- **Persisted child sessions carry no `type`/`description`.**
+  The JSONL has only the conversation plus a header (`id`, `timestamp`, `cwd`, `parentSession`).
+  A directory scan (the issue's literal wording) would therefore produce degraded labels and parse every file per open.
+- **Decision: manager-retained descriptors over directory scan.**
+  The manager stashes a tiny no-messages `EvictedSubagent` descriptor in `cleanup()` before `removeRecord`, cleared in `clearCompleted()`/`dispose()`.
+  Rich labels identical to live entries, bounded memory, no per-open parse.
+  Coverage is limited to in-session evictions — which are the sweep's only targets, since a fresh manager per session never reloads prior-process subagents.
+  Operator confirmed; an `(evicted)` snapshot marker was also chosen for the label.
+- **`NavigationEntry` becomes a discriminated union** (`live` | `evicted`); this breaks the handler, the `index.ts` call site, and both UI test files, so step 3 folds all of them into one commit.
+- **SDK-runtime call kept direct.** `fileSnapshotSource` calls `parseSessionEntries` / `buildSessionContext` directly rather than injecting them — the injected `readFile` already provides the unit-test seam, and there is no `no-restricted-imports` rule.
+- **Transient dead-code risk noted:** `fileSnapshotSource` and `listEvicted()` have no caller until step 3; flagged not to ship before step 3 lands (CI/`fallow` gate the pushed tip).
+- Release: independent (Phase 19 Step 4b roadmap tag).
+
+## Stage: Implementation — TDD (2026-06-23T13:00:00Z)
+
+### Session summary
+
+Executed all 4 plan steps in order: (1) `fileSnapshotSource` in the pure `session-navigation.ts`, (2) manager-retained `EvictedSubagent` descriptors (`cleanup` capture, `listEvicted`, `clearCompleted`/`dispose` clear), (3) the breaking `NavigationEntry` discriminated union + handler dual-source + `index.ts` wiring + all test updates in one commit, (4) architecture/ADR doc updates.
+Test count went from 1088 to 1099 (+11); full suite, `check`, root `lint`, and `fallow dead-code` all green.
+
+### Observations
+
+- **No deviations from the plan.**
+  All steps landed as written; Module-Level Changes matched the touched files exactly.
+- **Exploratory probe paid off.**
+  A disposable script confirmed `buildSessionContext` auto-detects the leaf with no `leafId`, the `type !== "session"` filter drops the header, and empty entries yield `[]` — validating the `fileSnapshotSource` shape before writing the test.
+- **Two ESLint auto-fixes during commit hooks:** a stray `!` non-null assertion in the manager test (step 2) and four `entry?.kind` optional chains on a non-nullish destructured `entry` (`@typescript-eslint/no-unnecessary-condition`, step 3).
+  Both fixed and re-committed; `check` + tests confirmed green after.
+- **Transient dead code** between steps 1–2 and 3 (predicted in the plan) cleared at the step-3 tip; final `fallow dead-code` is clean.
+- **Pre-completion reviewer: PASS** — deterministic checks, code design, test artifacts, Mermaid render, and all three cross-step invariants (no inbound core call, read-only overlay, renderer parity) verified; no follow-ups deferred.
+
+## Stage: Final Retrospective (2026-06-23T17:43:05Z)
+
+### Session summary
+
+Single continuous session carried #463 from planning through ship: a 4-step plan, TDD implementation (+11 tests, 1088→1099), pre-completion PASS, and release of `pi-subagents` v17.5.0.
+The defining moment was planning: an `ask_user` design gate plus operator Socratic pushback diverged the candidate-set design from the issue's literal "directory scan" wording to manager-retained descriptors.
+Execution was notably clean — no rework, no plan deviations, two auto-fixed lint nits.
+
+### Observations
+
+#### What went well
+
+- **The `ask_user` gate caught a real design fork the issue body got wrong.**
+  The issue's "Proposed change" said "enumerate persisted child-session JSONL files" (a directory scan).
+  Exploration revealed the persisted session carries no subagent `type`/`description`, so a scan yields degraded labels.
+  The gate surfaced descriptors-vs-scan-vs-hybrid; the operator's "why are we evicting at all?"
+  and "tell me more about how the labels degrade" drove a better-grounded decision (descriptors).
+  This is the `/plan-issue` "treat Proposed change as a hypothesis" contract working as intended — novel because the divergence was the *enumeration mechanism*, not a surface ambiguity.
+- **Exploratory probe before the first TDD test.**
+  A disposable script (`explore-session.mjs`, deleted after) confirmed `buildSessionContext` auto-detects the leaf with no `leafId` and the `type !== "session"` filter drops the header — validating the `fileSnapshotSource` shape before any test was written (the `testing` skill's "inspect the actual runtime shape first" rule).
+- **The plan predicted transient dead code and sequenced to clear it.**
+  `fileSnapshotSource` and `listEvicted()` had no caller until step 3; the plan flagged this and ordered the integration step to close it, so the final `fallow dead-code` gate passed with no surprise suppressions.
+- **Pre-completion reviewer ran on `claude-sonnet-4-6`** — model appropriate for the judgment-heavy invariant/design checklist; returned PASS.
+
+#### What caused friction (agent side)
+
+- `other` — the first `ask_user` led with the enumeration mechanism (descriptors/scan/hybrid) before establishing *why eviction creates the problem*.
+  The operator's first reply was "Why are we 'evicting' subagents in the first place?", i.e. asking for the framing I already held but had not front-loaded.
+  Impact: two extra `ask_user` round-trips before the decision — but they produced a better-understood outcome, so net-positive; no rework.
+- `other` (lint nit) — four `entry?.kind` optional chains on a destructured array element tripped `@typescript-eslint/no-unnecessary-condition`, and a stray `!` tripped `no-unnecessary-type-assertion`; both surfaced via the pre-commit hook.
+  Impact: two re-commits during steps 2–3, auto-fixed, zero rework.
+
+#### What caused friction (user side)
+
+- None.
+  The operator's Socratic questions mid-`ask_user` were the session's highest-value input — they converted a plausible-but-degraded design (scan) into the right one (descriptors).
+  If anything, this is a model for how the gate should be used.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the `pre-completion-reviewer` subagent ran on `anthropic/claude-sonnet-4-6` (judgment-heavy review): appropriate, no mismatch.
+  Main-thread `model_change` events included a `deepseek-v4-flash` variant; no quality degradation was observed in any artifact (plan, code, tests all clean), so no actionable correlation.
+- **Escalation-delay tracking** — no `rabbit-hole` points; longest same-error streak was the two lint auto-fixes, each resolved in one re-commit.
+- **Unused-tool detection** — exploration used `colgrep`, `grep`, and a disposable runtime probe; no missed-tool opportunities.
+- **Feedback-loop gap analysis** — verification ran incrementally: `pnpm run check` after the shared-interface steps (2 and 3), per-file `vitest` on each red/green cycle, and the full suite + lint + `fallow` before the docs commit.
+  No end-only verification.
+
+### Changes made
+
+1. Appended this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0463-file-snapshot-source-evicted-agents.md`.
+
+No `AGENTS.md` or prompt changes — the session's friction was net-positive (the `ask_user` round-trips) or auto-fixed with zero rework (the lint nits).
+Two candidate changes were considered and rejected as noise (a `code-design` note on `entry?.kind` optional chaining; an `ask-user` "why-before-mechanism" guidance already covered by the skill).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "17.4.0",
+  "version": "18.0.0",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -8,10 +8,9 @@
  *   steer_subagent       — LLM-callable: send a steering message to a running agent
  *
  * Commands:
- *   /agents                 — Interactive agent management menu
  */
 
-import { join } from "node:path";
+import { readFileSync } from "node:fs";
 import {
   createAgentSession,
   DefaultResourceLoader,
@@ -26,7 +25,6 @@ import { InterruptHandler, SessionLifecycleHandler, ToolStartHandler } from "#sr
 import { createChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { ConcurrencyLimiter } from "#src/lifecycle/concurrency-limiter";
 import { createSubagentSession, type SubagentSessionDeps } from "#src/lifecycle/create-subagent-session";
-import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { SubagentManager } from "#src/lifecycle/subagent-manager";
 import { CompositeSubagentObserver } from "#src/observation/composite-subagent-observer";
 import { type NotificationDetails, NotificationManager } from "#src/observation/notification";
@@ -44,8 +42,6 @@ import { SettingsManager } from "#src/settings";
 import { AgentTool } from "#src/tools/agent-tool";
 import { GetResultTool } from "#src/tools/get-result-tool";
 import { SteerTool } from "#src/tools/steer-tool";
-import { FsAgentFileOps } from "#src/ui/agent-file-ops";
-import { AgentsMenuHandler } from "#src/ui/agent-menu";
 import { AgentWidget } from "#src/ui/agent-widget";
 import { SessionNavigatorHandler } from "#src/ui/session-navigator";
 import { SubagentsSettingsHandler } from "#src/ui/subagents-settings";
@@ -161,47 +157,32 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerTool(new SteerTool(manager, pi.events).toToolDefinition());
 
-  // ---- /agents interactive menu ----
-
-  const agentsMenu = new AgentsMenuHandler(
-    manager,
-    registry,
-    settings,
-    new FsAgentFileOps(),
-    join(getAgentDir(), "agents"),
-    join(process.cwd(), ".pi", "agents"),
-  );
-
-  pi.registerCommand("agents", {
-    description: "Manage agents",
-    handler: async (_args, ctx) => {
-      await agentsMenu.handle({
-        ui: ctx.ui,
-        modelRegistry: ctx.modelRegistry,
-        parentSnapshot: buildParentSnapshot(ctx),
-      });
-    },
-  });
-
-  // ---- /subagents-settings command ----
+  // ---- /subagents:settings command ----
 
   const subagentsSettings = new SubagentsSettingsHandler(settings);
 
-  pi.registerCommand("subagents-settings", {
+  pi.registerCommand("subagents:settings", {
     description: "Configure subagent settings (concurrency, turn limits)",
     handler: async (_args, ctx) => {
       await subagentsSettings.handle({ ui: ctx.ui });
     },
   });
 
-  // ---- /subagent-sessions command ----
+  // ---- /subagents:sessions command ----
 
   const sessionNavigator = new SessionNavigatorHandler();
 
-  pi.registerCommand("subagent-sessions", {
+  pi.registerCommand("subagents:sessions", {
     description: "View a subagent's session transcript (read-only)",
     handler: async (_args, ctx) => {
-      await sessionNavigator.handle({ ui: ctx.ui, agents: manager.listAgents(), registry, cwd: ctx.cwd });
+      await sessionNavigator.handle({
+        ui: ctx.ui,
+        agents: manager.listAgents(),
+        evicted: manager.listEvicted(),
+        registry,
+        cwd: ctx.cwd,
+        readFile: (path) => readFileSync(path, "utf8"),
+      });
     },
   });
 }

package/src/lifecycle/subagent-manager.ts

@@ -14,12 +14,31 @@ import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { Subagent, type SubagentLifecycleObserver } from "#src/lifecycle/subagent";
 import type { SubagentSession } from "#src/lifecycle/subagent-session";
-import { SubagentState } from "#src/lifecycle/subagent-state";
+import { SubagentState, type SubagentStatus } from "#src/lifecycle/subagent-state";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 
 import type { RunConfig } from "#src/runtime";
 import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
+/**
+ * A lightweight snapshot of a subagent evicted by the 10-minute cleanup sweep.
+ *
+ * The sweep frees the heavy in-memory session (its message history included);
+ * this descriptor retains only the fields the session navigator needs to label
+ * the agent in the picker, plus the persisted `outputFile` to source its
+ * transcript from disk. Carries no messages, so memory stays bounded.
+ */
+export interface EvictedSubagent {
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly status: SubagentStatus;
+  readonly startedAt: number;
+  readonly completedAt: number | undefined;
+  readonly toolUses: number;
+  readonly outputFile: string;
+}
+
 /** Observer interface for agent lifecycle notifications. */
 export interface SubagentManagerObserver {
   onSubagentStarted(record: Subagent): void;
@@ -65,6 +84,8 @@ export interface AgentSpawnConfig {
 
 export class SubagentManager {
   private agents = new Map<string, Subagent>();
+  /** Descriptors of agents removed by the cleanup sweep, keyed by id — navigable from disk. */
+  private readonly evicted = new Map<string, EvictedSubagent>();
   private cleanupInterval: ReturnType<typeof setInterval>;
   private readonly observer?: SubagentManagerObserver;
   private readonly createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
@@ -220,6 +241,11 @@ export class SubagentManager {
     );
   }
 
+  /** Descriptors of agents evicted by the cleanup sweep, most recent first. */
+  listEvicted(): EvictedSubagent[] {
+    return [...this.evicted.values()].sort((a, b) => b.startedAt - a.startedAt);
+  }
+
   abort(id: string): boolean {
     const record = this.agents.get(id);
     if (!record) return false;
@@ -245,6 +271,9 @@ export class SubagentManager {
     for (const [id, record] of this.agents) {
       if (record.status === "running" || record.status === "queued") continue;
       if ((record.completedAt ?? 0) >= cutoff) continue;
+      // Retain a navigable descriptor before freeing the heavy session. Only an
+      // agent with a persisted file can be sourced from disk after eviction.
+      if (record.outputFile) this.evicted.set(id, toEvictedSubagent(record, record.outputFile));
       this.removeRecord(id, record);
     }
   }
@@ -258,6 +287,8 @@ export class SubagentManager {
       if (record.status === "running" || record.status === "queued") continue;
       this.removeRecord(id, record);
     }
+    // Evicted descriptors belong to the session that swept them — a new session starts empty.
+    this.evicted.clear();
   }
 
   /** Whether any agents are still running or queued. */
@@ -314,5 +345,20 @@ export class SubagentManager {
       record.disposeSession();
     }
     this.agents.clear();
+    this.evicted.clear();
   }
 }
+
+/** Capture an evicted agent's navigable fields from its record. */
+function toEvictedSubagent(record: Subagent, outputFile: string): EvictedSubagent {
+  return {
+    id: record.id,
+    type: record.type,
+    description: record.description,
+    status: record.status,
+    startedAt: record.startedAt,
+    completedAt: record.completedAt,
+    toolUses: record.toolUses,
+    outputFile,
+  };
+}

package/src/ui/session-navigation.ts

@@ -1,7 +1,7 @@
 /**
  * session-navigation.ts — Pure selection and transcript-sourcing for native session navigation.
  *
- * Splits the unit-testable core of the `/subagent-sessions` command from its TUI
+ * Splits the unit-testable core of the `/subagents:sessions` command from its TUI
  * wiring (`session-navigator.ts`): which subagents are navigable and how a picked
  * agent's transcript is sourced (live, in this slice).
  *
@@ -12,8 +12,9 @@
  * components require a `TUI`, `cwd`, and markdown theme.
  */
 
-import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { buildSessionContext, parseSessionEntries, type SessionEntry, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { EvictedSubagent } from "#src/lifecycle/subagent-manager";
 import type { SubagentStatus } from "#src/lifecycle/subagent-state";
 import type { AgentSessionEvent, SessionMessage, SubagentType } from "#src/types";
 import { formatDuration, getDisplayName } from "#src/ui/display";
@@ -37,10 +38,24 @@ export interface NavigableSubagent {
   getToolDefinition(name: string): ToolDefinition | undefined;
 }
 
-/** A navigable entry: a record plus the label shown in the picker. */
-export interface NavigationEntry {
-  readonly record: NavigableSubagent;
-  readonly label: string;
+/**
+ * A navigable entry plus the label shown in the picker.
+ *
+ * A `live` entry sources its transcript from the in-memory record; an `evicted`
+ * entry sources it from the persisted session file (the record is gone).
+ */
+export type NavigationEntry =
+  | { readonly kind: "live"; readonly label: string; readonly record: NavigableSubagent }
+  | { readonly kind: "evicted"; readonly label: string; readonly outputFile: string };
+
+/** The fields `buildLabel` reads — shared by a live record and an evicted descriptor. */
+interface LabelFields {
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly status: SubagentStatus;
+  readonly startedAt: number;
+  readonly completedAt: number | undefined;
+  readonly toolUses: number;
 }
 
 /** Running-agent streaming state, surfaced by a live source. */
@@ -61,14 +76,52 @@ export interface TranscriptSource {
   getToolDefinition(name: string): ToolDefinition | undefined;
 }
 
-/** Filter the agents to those with a viewable session and label each for the picker. */
+/**
+ * Label every navigable subagent for the picker: live records with a viewable
+ * session, then agents evicted by the cleanup sweep (deduped against live ids).
+ */
 export function listNavigableAgents(
   agents: readonly NavigableSubagent[],
+  evicted: readonly EvictedSubagent[],
   registry: AgentConfigLookup,
 ): NavigationEntry[] {
-  return agents
+  const live = agents
     .filter((record) => record.isSessionReady())
-    .map((record) => ({ record, label: buildLabel(record, registry) }));
+    .map((record): NavigationEntry => ({ kind: "live", record, label: buildLabel(record, registry) }));
+  const liveIds = new Set(agents.map((record) => record.id));
+  const evictedEntries = evicted
+    .filter((descriptor) => !liveIds.has(descriptor.id))
+    .map((descriptor): NavigationEntry => ({
+      kind: "evicted",
+      outputFile: descriptor.outputFile,
+      label: buildLabel(descriptor, registry, true),
+    }));
+  return [...live, ...evictedEntries];
+}
+
+/**
+ * Source a transcript from a persisted child-session JSONL snapshot.
+ *
+ * For an agent evicted from the manager's map by the 10-minute cleanup sweep:
+ * the in-memory record (and its message history) is gone, but the session file
+ * survives on disk. Reads the file, drops the `SessionHeader`, and resolves the
+ * message list via Pi's own parser. A static snapshot — no subscription, no
+ * streaming, no live tool registry. `readFile` is injected so this module makes
+ * no `fs` calls.
+ */
+export function fileSnapshotSource(
+  outputFile: string,
+  readFile: (path: string) => string,
+): TranscriptSource {
+  const entries = parseSessionEntries(readFile(outputFile));
+  const sessionEntries = entries.filter((entry): entry is SessionEntry => entry.type !== "session");
+  const { messages } = buildSessionContext(sessionEntries);
+  return {
+    getMessages: () => messages,
+    subscribe: () => undefined,
+    streaming: () => undefined,
+    getToolDefinition: () => undefined,
+  };
 }
 
 /** Source a transcript live from an in-memory record (this slice's only source). */
@@ -84,8 +137,9 @@ export function liveSource(record: NavigableSubagent): TranscriptSource {
   };
 }
 
-function buildLabel(record: NavigableSubagent, registry: AgentConfigLookup): string {
-  const name = getDisplayName(record.type, registry);
-  const duration = formatDuration(record.startedAt, record.completedAt);
-  return `${name} (${record.description}) · ${record.toolUses} tools · ${record.status} · ${duration}`;
+function buildLabel(fields: LabelFields, registry: AgentConfigLookup, evicted = false): string {
+  const name = getDisplayName(fields.type, registry);
+  const duration = formatDuration(fields.startedAt, fields.completedAt);
+  const marker = evicted ? " · evicted (snapshot)" : "";
+  return `${name} (${fields.description}) · ${fields.toolUses} tools · ${fields.status} · ${duration}${marker}`;
 }

package/src/ui/session-navigator.ts

@@ -1,5 +1,5 @@
 /**
- * session-navigator.ts — The `/subagent-sessions` command: pick a subagent and
+ * session-navigator.ts — The `/subagents:sessions` command: pick a subagent and
  * read its transcript through Pi's own per-entry session components.
  *
  * SDK/TUI consumer half of native session navigation. The unit-testable core
@@ -38,9 +38,10 @@ import {
   visibleWidth,
 } from "@earendil-works/pi-tui";
 import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { EvictedSubagent } from "#src/lifecycle/subagent-manager";
 import type { SessionMessage } from "#src/types";
 import { describeActivity, type Theme } from "#src/ui/display";
-import { listNavigableAgents, liveSource, type NavigableSubagent, type TranscriptSource } from "#src/ui/session-navigation";
+import { fileSnapshotSource, listNavigableAgents, liveSource, type NavigableSubagent, type TranscriptSource } from "#src/ui/session-navigation";
 
 // ─────────────────────────────────────────────────────────────────────────────
 
@@ -64,13 +65,17 @@ export interface SessionNavigatorUI {
   custom<R>(component: OverlayComponentFactory<R>, options?: unknown): Promise<R>;
 }
 
-/** Parameters for one `/subagent-sessions` invocation. */
+/** Parameters for one `/subagents:sessions` invocation. */
 export interface SessionNavigatorParams {
   ui: SessionNavigatorUI;
   agents: readonly NavigableSubagent[];
+  /** Descriptors of agents evicted by the cleanup sweep, sourced from disk when picked. */
+  evicted: readonly EvictedSubagent[];
   registry: AgentConfigLookup;
   /** Working directory for tool-call rendering (relative path display). */
   cwd: string;
+  /** Reads a persisted session file for the file-snapshot source. */
+  readFile: (path: string) => string;
 }
 
 /** Options for the read-only transcript overlay. */
@@ -84,15 +89,15 @@ export interface TranscriptOverlayOptions {
 }
 
 /**
- * Handler for the `/subagent-sessions` slash command.
+ * Handler for the `/subagents:sessions` slash command.
  *
  * Lists navigable subagents, lets the operator pick one, and opens its transcript
  * read-only. Receives the agent snapshot (`manager.listAgents()`) rather than the
  * manager, so it stays a reactive consumer with no inbound call into the core.
  */
 export class SessionNavigatorHandler {
-  async handle({ ui, agents, registry, cwd }: SessionNavigatorParams): Promise<void> {
-    const entries = listNavigableAgents(agents, registry);
+  async handle({ ui, agents, evicted, registry, cwd, readFile }: SessionNavigatorParams): Promise<void> {
+    const entries = listNavigableAgents(agents, evicted, registry);
     if (entries.length === 0) {
       ui.notify("No subagent sessions to view.", "info");
       return;
@@ -105,7 +110,13 @@ export class SessionNavigatorHandler {
     const entry = entries.find((candidate) => candidate.label === choice);
     if (!entry) return;
 
-    const source = liveSource(entry.record);
+    let source: TranscriptSource;
+    try {
+      source = entry.kind === "live" ? liveSource(entry.record) : fileSnapshotSource(entry.outputFile, readFile);
+    } catch {
+      ui.notify("Could not read the session transcript file.", "error");
+      return;
+    }
     const markdownTheme = getMarkdownTheme();
     await ui.custom<undefined>(
       (tui, theme, _keybindings, done) =>

package/src/ui/subagents-settings.ts

@@ -1,6 +1,6 @@
 // ---- Narrow interfaces ----
 
-/** Narrow settings interface required by the subagents-settings command. */
+/** Narrow settings interface required by the subagents:settings command. */
 export interface SubagentsSettingsManager {
   readonly maxConcurrent: number;
   readonly defaultMaxTurns: number | undefined;
@@ -20,7 +20,7 @@ export interface SubagentsSettingsUI {
 // ---- Class ----
 
 /**
- * Handler for the `/subagents-settings` slash command.
+ * Handler for the `/subagents:settings` slash command.
  *
  * Call `handle({ ui })` from the Pi command registration to open the interactive
  * settings list. Lifted from `AgentsMenuHandler.showSettings`.