@esso0428/pi-subagents 0.15.1 → 0.15.3

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.3] - 2026-09-11
+
+### Added
+- **Reload-safe transcript history.** Agents now keep a project-local copy under `.pi-subagents/agent-transcripts/`; terminal records persist a relative locator and `/agents`/FleetView can open a read-only history viewer after reload. The shared `.pi-subagents/.gitignore` is created with `*` to keep private transcripts out of git.
+
+## [0.15.2] - 2026-09-10
+
+### Added
+- **Completed subagent records survive session reloads.** On `session_start`, the extension now reconstructs validated terminal records persisted as `subagents:record` entries. Restored records retain their result and status for `get_subagent_result`, but never pretend to have a live child session; running and queued records are ignored, and duplicate IDs use the newest branch entry.
+
 ## [0.15.1] - 2026-09-10
 
 ### Added

package/README.md

@@ -140,7 +140,7 @@ Individual agent results render Claude Code-style in the conversation:
 
 Completed results can be expanded (ctrl+o in pi) to show the agent output inline with Markdown formatting. Expanded output is capped at 50 rendered lines (background notification results at 30 lines) and ends with a marker when more output is available; use `get_subagent_result` for the complete result.
 
-By default, foreground and background agents each stream their full conversation to a per-subagent transcript — a JSON-lines file at `<os-tmpdir>/pi-subagents-<uid>/<cwd>/<session>/tasks/<agent-id>.output` (owner-only `0700`, cleared on reboot). Set `output_transcript: false` on a custom agent to write no transcript path or file for it, or set `outputTranscript: false` in `subagents.json` to make transcripts opt-in for the whole project (frontmatter overrides the project default). This governs **only** the transcript: it is independent of `persist_session` (the pi session on disk), and it does not affect `isolation: worktree` (which commits the agent's work to a git branch) or `memory:` (durable files) — set those accordingly if the goal is to keep a run off disk entirely. Background agent completion notifications render as styled boxes:
+By default, foreground and background agents stream their full conversation to two per-subagent transcripts: the existing temporary JSON-lines file at `<os-tmpdir>/pi-subagents-<uid>/<cwd>/<session>/tasks/<agent-id>.output` (owner-only `0700`, cleared on reboot), plus a durable copy at `<cwd>/.pi-subagents/agent-transcripts/<agent-id>_<agent-type>_transcript.jsonl`. The project-local `.pi-subagents/.gitignore` contains `*` so these private transcripts are not accidentally uploaded to git. After `/reload`, terminal records use the durable locator to open a read-only history viewer. Set `output_transcript: false` on a custom agent, or `outputTranscript: false` in `subagents.json`, to suppress both transcript files. This governs **only** the transcript: it is independent of `persist_session` (the pi session on disk), and it does not affect `isolation: worktree` or `memory:`. Background agent completion notifications render as styled boxes:
 
 ```
 ✓ Find auth files completed
@@ -222,7 +222,7 @@ All fields are optional — sensible defaults for everything.
 | `thinking` | inherit | off, minimal, low, medium, high, xhigh, max — actual availability depends on your pi version and model; pi clamps unsupported levels down |
 | `max_turns` | unlimited | Max agentic turns before graceful shutdown. `0` or omit for unlimited |
 | `persist_session` | `false` | Persist this subagent as a normal pi session instead of keeping the session in memory only. The subagent's `.output` transcript is still written either way unless `output_transcript: false` |
-| `output_transcript` | `true` (or `subagents.json` `outputTranscript`) | Write this subagent's `.output` transcript; when set, overrides the `subagents.json` `outputTranscript` default. Set `false` to write no transcript file or path. Governs only the transcript — independent of `persist_session`, `isolation: worktree`, and `memory:` |
+| `output_transcript` | `true` (or `subagents.json` `outputTranscript`) | Write the temporary `.output` transcript and durable `.pi-subagents/agent-transcripts/` copy; when set, overrides the `subagents.json` `outputTranscript` default. Set `false` to write neither. Governs only the transcript — independent of `persist_session`, `isolation: worktree`, and `memory:` |
 | `session_dir` | pi default | Optional session directory when `persist_session: true`; omitted uses pi's normal session location, and relative paths resolve from the agent cwd |
 | `prompt_mode` | `replace` | `replace`: body is the full system prompt (no AGENTS.md / CLAUDE.md inheritance). `append`: body appended to parent's prompt (agent acts as a "parent twin" — inherits parent's AGENTS.md / CLAUDE.md) |
 | `inherit_context` | `false` | Fork parent conversation into agent |
@@ -508,7 +508,7 @@ Runtime tuning values set via `/agents` → Settings (max concurrency, default m
 
 **Disable defaults** (`disableDefaultAgents`, default `false`): when on, the three built-in agents (general-purpose, Explore, Plan) are not registered — only your project/global custom agents are advertised and spawnable. User-defined agents are unaffected, including ones that override a default by name. The Agent tool's type list updates on the next pi session (the tool schema is registered at startup).
 
-**Output transcript** (`outputTranscript`, default `true`): the project/global default for writing each subagent's `.output` transcript. Toggle via `/agents → Settings → Output transcript`, or set `false` in `subagents.json` to make transcripts opt-in project-wide — useful when run transcripts shouldn't sit on disk for backup or DLP tooling to pick up. A custom agent's `output_transcript` frontmatter overrides this per agent. Applied live at spawn time. Governs only the transcript, not `persist_session`, worktree commits, or memory files.
+**Output transcript** (`outputTranscript`, default `true`): the project/global default for writing each subagent's temporary `.output` transcript and durable project-local history copy under `.pi-subagents/agent-transcripts/`. Toggle via `/agents → Settings → Output transcript`, or set `false` in `subagents.json` to make both transcripts opt-in project-wide. A custom agent's `output_transcript` frontmatter overrides this per agent. Applied live at spawn time. Governs only the transcript, not `persist_session`, worktree commits, or memory files.
 
 **Tool description** (`toolDescriptionMode`, default `"full"`): which Agent tool description the LLM sees. `"full"` is the rich Claude Code-style prompt (~1,400 tokens with the default agents); `"compact"` is ~75% smaller — one-line agent type list, terse usage notes — for small/local models where tool-spec tokens are expensive. Per-option details stay in the parameter descriptions in every mode (the parameter schema is never customizable). Applies on the next pi session.
 

package/dist/agent-history.d.ts

@@ -0,0 +1,22 @@
+/** Durable, project-local transcript storage for subagents. */
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+/**
+ * Ensure project-local subagent artifacts are ignored by git.
+ *
+ * The rule is appended instead of rewriting the file. This preserves any
+ * existing user-owned rules and makes concurrent callers harmless (duplicate
+ * `*` rules are semantically equivalent).
+ */
+export declare function ensureSubagentsGitignore(cwd: string): string;
+/** Return the durable transcript path for an agent. */
+export declare function createAgentHistoryPath(cwd: string, agentId: string, agentType?: string): string;
+/** Return the project-relative path stored in the parent session record. */
+export declare function agentHistoryLocator(cwd: string, historyPath: string): string;
+/** Resolve only paths in this package's project-local transcript namespace. */
+export declare function resolveAgentHistoryPath(cwd: string, locator: string): string | undefined;
+/**
+ * Read persisted transcript entries into the message shape used by the live
+ * conversation viewer. Malformed lines and unknown records are skipped so one
+ * damaged entry cannot hide the rest of a history.
+ */
+export declare function readAgentHistory(cwd: string, locator: string): AgentSession["messages"] | undefined;

package/dist/agent-history.js

@@ -0,0 +1,98 @@
+"use strict";
+/** Durable, project-local transcript storage for subagents. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureSubagentsGitignore = ensureSubagentsGitignore;
+exports.createAgentHistoryPath = createAgentHistoryPath;
+exports.agentHistoryLocator = agentHistoryLocator;
+exports.resolveAgentHistoryPath = resolveAgentHistoryPath;
+exports.readAgentHistory = readAgentHistory;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const SUBAGENTS_DIR = ".pi-subagents";
+const TRANSCRIPTS_DIR = "agent-transcripts";
+const MAX_HISTORY_BYTES = 20 * 1024 * 1024;
+/**
+ * Ensure project-local subagent artifacts are ignored by git.
+ *
+ * The rule is appended instead of rewriting the file. This preserves any
+ * existing user-owned rules and makes concurrent callers harmless (duplicate
+ * `*` rules are semantically equivalent).
+ */
+function ensureSubagentsGitignore(cwd) {
+    const directory = (0, node_path_1.join)(cwd, SUBAGENTS_DIR);
+    (0, node_fs_1.mkdirSync)(directory, { recursive: true });
+    const path = (0, node_path_1.join)(directory, ".gitignore");
+    let content = "";
+    try {
+        content = (0, node_fs_1.readFileSync)(path, "utf8");
+    }
+    catch {
+        // The append below also creates a missing file.
+    }
+    if (!content.split(/\r?\n/).some((line) => line.trim() === "*")) {
+        const separator = content.length > 0 && !/[\r\n]$/.test(content) ? "\n" : "";
+        (0, node_fs_1.appendFileSync)(path, `${separator}*\n`, "utf8");
+    }
+    return path;
+}
+/** Return the durable transcript path for an agent. */
+function createAgentHistoryPath(cwd, agentId, agentType = "agent") {
+    ensureSubagentsGitignore(cwd);
+    const directory = (0, node_path_1.join)(cwd, SUBAGENTS_DIR, TRANSCRIPTS_DIR);
+    (0, node_fs_1.mkdirSync)(directory, { recursive: true });
+    const safeId = agentId.replace(/[^A-Za-z0-9._-]+/g, "-") || "agent";
+    const safeType = agentType.replace(/[^A-Za-z0-9._-]+/g, "-") || "agent";
+    return (0, node_path_1.join)(directory, `${safeId}_${safeType}_transcript.jsonl`);
+}
+/** Return the project-relative path stored in the parent session record. */
+function agentHistoryLocator(cwd, historyPath) {
+    return (0, node_path_1.relative)(cwd, historyPath).split(node_path_1.sep).join("/");
+}
+/** Resolve only paths in this package's project-local transcript namespace. */
+function resolveAgentHistoryPath(cwd, locator) {
+    if (!locator || (0, node_path_1.isAbsolute)(locator))
+        return undefined;
+    const root = (0, node_path_1.resolve)(cwd, SUBAGENTS_DIR, TRANSCRIPTS_DIR);
+    const candidate = (0, node_path_1.resolve)(cwd, locator);
+    if (candidate !== root && !candidate.startsWith(`${root}${node_path_1.sep}`))
+        return undefined;
+    return candidate;
+}
+/**
+ * Read persisted transcript entries into the message shape used by the live
+ * conversation viewer. Malformed lines and unknown records are skipped so one
+ * damaged entry cannot hide the rest of a history.
+ */
+function readAgentHistory(cwd, locator) {
+    const path = resolveAgentHistoryPath(cwd, locator);
+    if (!path)
+        return undefined;
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    if (raw.length > MAX_HISTORY_BYTES)
+        raw = raw.slice(0, MAX_HISTORY_BYTES);
+    const messages = [];
+    for (const line of raw.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            const message = entry.message;
+            if (!message || typeof message !== "object")
+                continue;
+            const role = message.role;
+            if (typeof role !== "string")
+                continue;
+            messages.push(message);
+        }
+        catch {
+            // Ignore malformed/truncated JSONL records.
+        }
+    }
+    return messages.length > 0 ? messages : undefined;
+}

package/dist/agent-manager.d.ts

@@ -121,6 +121,14 @@ export declare class AgentManager {
      */
     steer(id: string, message: string): boolean;
     getRecord(id: string): AgentRecord | undefined;
+    /**
+     * Restore terminal records persisted in a parent session.
+     *
+     * Restored records deliberately have no live session, promise, or abort
+     * controller. Invalid data is ignored because session entries are persisted
+     * extension data and may have been written by an older version.
+     */
+    restoreCompleted(records: readonly unknown[]): void;
     listAgents(): AgentRecord[];
     abort(id: string): boolean;
     /** Dispose a record's session and remove it from the map. */

package/dist/agent-manager.js

@@ -16,6 +16,13 @@ const usage_js_1 = require("./usage.js");
 const worktree_js_1 = require("./worktree.js");
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "steered",
+    "aborted",
+    "stopped",
+    "error",
+]);
 /**
  * Validate a caller-supplied SpawnOptions.cwd. `undefined`/`null` mean "unset"
  * (parent cwd). Anything else must be an absolute path to an existing
@@ -39,6 +46,36 @@ function assertValidSpawnCwd(cwd) {
         throw new Error(`SpawnOptions.cwd is not a directory: "${cwd}"`);
     }
 }
+const RESTORABLE_STATUSES = new Set([
+    "completed",
+    "steered",
+    "aborted",
+    "stopped",
+    "error",
+]);
+function isRestorableRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    const transcriptPath = record.transcriptPath;
+    const validTranscriptPath = transcriptPath === undefined ||
+        (typeof transcriptPath === "string" &&
+            transcriptPath.startsWith(".pi-subagents/agent-transcripts/") &&
+            !transcriptPath.includes("..") &&
+            !transcriptPath.includes("\\"));
+    return (typeof record.id === "string" &&
+        record.id.length > 0 &&
+        typeof record.type === "string" &&
+        typeof record.description === "string" &&
+        RESTORABLE_STATUSES.has(record.status) &&
+        typeof record.startedAt === "number" &&
+        Number.isFinite(record.startedAt) &&
+        typeof record.completedAt === "number" &&
+        Number.isFinite(record.completedAt) &&
+        (record.result === undefined || typeof record.result === "string") &&
+        (record.error === undefined || typeof record.error === "string") &&
+        validTranscriptPath);
+}
 class AgentManager {
     agents = new Map();
     cleanupInterval;
@@ -425,6 +462,41 @@ class AgentManager {
     getRecord(id) {
         return this.agents.get(id);
     }
+    /**
+     * Restore terminal records persisted in a parent session.
+     *
+     * Restored records deliberately have no live session, promise, or abort
+     * controller. Invalid data is ignored because session entries are persisted
+     * extension data and may have been written by an older version.
+     */
+    restoreCompleted(records) {
+        const restoredIds = new Set();
+        // getBranch() is chronological; newest persisted state wins on duplicate IDs.
+        for (const value of [...records].reverse()) {
+            if (!isRestorableRecord(value))
+                continue;
+            if (restoredIds.has(value.id) || this.agents.has(value.id))
+                continue;
+            restoredIds.add(value.id);
+            this.agents.set(value.id, {
+                id: value.id,
+                type: value.type,
+                description: value.description,
+                status: value.status,
+                result: value.result,
+                error: value.error,
+                transcriptPath: value.transcriptPath,
+                toolUses: 0,
+                startedAt: value.startedAt,
+                completedAt: value.completedAt,
+                lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+                compactionCount: 0,
+                // Historical records have no inline tool surface and should remain
+                // visible in the background widget.
+                isBackground: true,
+            });
+        }
+    }
     listAgents() {
         return [...this.agents.values()].sort((a, b) => b.startedAt - a.startedAt);
     }

package/dist/index.js

@@ -27,6 +27,7 @@ const enabled_models_js_1 = require("./enabled-models.js");
 const group_join_js_1 = require("./group-join.js");
 const invocation_config_js_1 = require("./invocation-config.js");
 const model_resolver_js_1 = require("./model-resolver.js");
+const agent_history_js_1 = require("./agent-history.js");
 const output_file_js_1 = require("./output-file.js");
 const schedule_js_1 = require("./schedule.js");
 const schedule_store_js_1 = require("./schedule-store.js");
@@ -410,11 +411,14 @@ function default_1(pi) {
         else {
             pi.events.emit("subagents:completed", eventData);
         }
-        // Persist final record for cross-extension history reconstruction
+        // Persist final record for cross-extension history reconstruction. Keep
+        // the transcript body in a project-local file rather than inflating the
+        // parent session JSONL; only its project-relative locator is persisted.
         pi.appendEntry("subagents:record", {
             id: record.id, type: record.type, description: record.description,
             status: record.status, result: record.result, error: record.error,
             startedAt: record.startedAt, completedAt: record.completedAt,
+            transcriptPath: record.transcriptPath,
         });
         // Skip notification if result was already consumed via get_subagent_result
         if (record.resultConsumed) {
@@ -511,7 +515,23 @@ function default_1(pi) {
     // bound session_start, so a filtered-out activation never advertises (#142).
     pi.on("session_start", async (_event, ctx) => {
         currentCtx = ctx;
+        try {
+            (0, agent_history_js_1.ensureSubagentsGitignore)(ctx.cwd);
+        }
+        catch (err) {
+            console.warn("[pi-subagents] Failed to protect project-local history:", err);
+        }
         manager.clearCompleted(true);
+        const historicalRecords = ctx.sessionManager
+            .getBranch()
+            .filter((entry) => entry?.type === "custom" && entry.customType === "subagents:record")
+            .map((entry) => entry.data);
+        manager.restoreCompleted(historicalRecords);
+        // Bind the UI here as well as on tool execution so rehydrated terminal
+        // records are immediately visible and openable from FleetView after reload.
+        widget.setUICtx(ctx.ui);
+        fleet.setUICtx(ctx.ui);
+        fleet.update();
         // Guard mirrors the `!scheduler.isActive()` pattern below: session_start
         // fires once per activation, but a double-bind must not leak listeners.
         if (!rpcHandle) {
@@ -564,7 +584,7 @@ function default_1(pi) {
     const widget = new agent_widget_js_1.AgentWidget(manager, agentActivity, getWidgetMode);
     function setWidgetMode(m) { widgetMode = m; widget.update(); }
     // Claude Code-style FleetView: navigable list of main + subagents below the editor.
-    const fleet = new fleet_list_js_1.FleetList(manager, agentActivity);
+    const fleet = new fleet_list_js_1.FleetList(manager, agentActivity, () => currentCtx?.cwd);
     let fleetViewEnabled = true;
     function isFleetViewEnabled() { return fleetViewEnabled; }
     function setFleetViewEnabled(b) { fleetViewEnabled = b; fleet.setEnabled(b); }
@@ -1034,6 +1054,19 @@ Terse command-style prompts produce shallow, generic work.
                     return;
                 rec.outputFile = (0, output_file_js_1.createOutputFilePath)(ctx.cwd, agentId, ctx.sessionManager.getSessionId());
                 (0, output_file_js_1.writeInitialEntry)(rec.outputFile, agentId, params.prompt, ctx.cwd);
+                // Keep the existing /tmp output for compatibility, while also writing a
+                // durable project-local copy for reload-safe, read-only history viewing.
+                try {
+                    rec.historyFile = (0, agent_history_js_1.createAgentHistoryPath)(ctx.cwd, agentId, subagentType);
+                    rec.transcriptPath = (0, agent_history_js_1.agentHistoryLocator)(ctx.cwd, rec.historyFile);
+                    (0, output_file_js_1.writeInitialEntry)(rec.historyFile, agentId, params.prompt, ctx.cwd);
+                }
+                catch (err) {
+                    // History is best effort; never disable the existing output transcript.
+                    rec.historyFile = undefined;
+                    rec.transcriptPath = undefined;
+                    console.warn("[pi-subagents] Failed to create durable transcript:", err);
+                }
             };
             const parentModelId = ctx.model?.id;
             const effectiveModelId = model?.id;
@@ -1134,7 +1167,7 @@ Terse command-style prompts produce shallow, generic work.
                     origBgOnSession(session);
                     const rec = manager.getRecord(id);
                     if (rec?.outputFile) {
-                        rec.outputCleanup = (0, output_file_js_1.streamToOutputFile)(session, rec.outputFile, id, ctx.cwd);
+                        rec.outputCleanup = (0, output_file_js_1.streamToOutputFile)(session, rec.outputFile, id, ctx.cwd, rec.historyFile);
                     }
                 };
                 try {
@@ -1240,7 +1273,7 @@ Terse command-style prompts produce shallow, generic work.
                 if (fgId) {
                     const rec = manager.getRecord(fgId);
                     if (rec?.outputFile) {
-                        rec.outputCleanup = (0, output_file_js_1.streamToOutputFile)(session, rec.outputFile, fgId, ctx.cwd);
+                        rec.outputCleanup = (0, output_file_js_1.streamToOutputFile)(session, rec.outputFile, fgId, ctx.cwd, rec.historyFile);
                     }
                 }
             };
@@ -1611,15 +1644,25 @@ Terse command-style prompts produce shallow, generic work.
             ctx.ui.notify(`Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`, "info");
             return;
         }
-        const { ConversationViewer, VIEWPORT_HEIGHT_PCT } = await import("./ui/conversation-viewer.js");
-        const session = record.session;
+        const { ConversationViewer, VIEWPORT_HEIGHT_PCT, createStaticConversationSource } = await import("./ui/conversation-viewer.js");
+        const session = record.session ?? (record.transcriptPath
+            ? (() => {
+                const messages = (0, agent_history_js_1.readAgentHistory)(ctx.cwd, record.transcriptPath);
+                return messages ? createStaticConversationSource(messages) : undefined;
+            })()
+            : undefined);
+        if (!session) {
+            ctx.ui.notify(`Agent is ${record.status === "queued" ? "queued" : "expired"} — no history available.`, "info");
+            return;
+        }
         const activity = agentActivity.get(record.id);
+        const isLive = record.session !== undefined;
         await ctx.ui.custom((tui, theme, keybindings, done) => {
-            return new ConversationViewer(tui, session, record, activity, theme, done, () => {
+            return new ConversationViewer(tui, session, record, activity, theme, done, isLive ? () => {
                 if (manager.abort(record.id)) {
                     ctx.ui.notify(`Stopped "${record.description}".`, "info");
                 }
-            }, keybindings, (message) => manager.steer(record.id, message));
+            } : undefined, keybindings, isLive ? (message) => manager.steer(record.id, message) : undefined);
         }, {
             overlay: true,
             overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },

package/dist/output-file.d.ts

@@ -21,4 +21,4 @@ export declare function writeInitialEntry(path: string, agentId: string, prompt:
  * Subscribe to session events and flush new messages to the output file on each turn_end.
  * Returns a cleanup function that does a final flush and unsubscribes.
  */
-export declare function streamToOutputFile(session: AgentSession, path: string, agentId: string, cwd: string): () => void;
+export declare function streamToOutputFile(session: AgentSession, path: string, agentId: string, cwd: string, historyPath?: string): () => void;

package/dist/output-file.js

@@ -60,7 +60,8 @@ function writeInitialEntry(path, agentId, prompt, cwd) {
  * Subscribe to session events and flush new messages to the output file on each turn_end.
  * Returns a cleanup function that does a final flush and unsubscribes.
  */
-function streamToOutputFile(session, path, agentId, cwd) {
+function streamToOutputFile(session, path, agentId, cwd, historyPath) {
+    const outputPaths = historyPath && historyPath !== path ? [path, historyPath] : [path];
     let writtenCount = 1; // initial user prompt already written
     const flush = () => {
         const messages = session.messages;
@@ -74,10 +75,12 @@ function streamToOutputFile(session, path, agentId, cwd) {
                 timestamp: new Date().toISOString(),
                 cwd,
             };
-            try {
-                (0, node_fs_1.appendFileSync)(path, JSON.stringify(entry) + "\n", "utf-8");
+            for (const outputPath of outputPaths) {
+                try {
+                    (0, node_fs_1.appendFileSync)(outputPath, JSON.stringify(entry) + "\n", "utf-8");
+                }
+                catch { /* ignore write errors */ }
             }
-            catch { /* ignore write errors */ }
             writtenCount++;
         }
     };

package/dist/types.d.ts

@@ -103,6 +103,10 @@ export interface AgentRecord {
     toolCallId?: string;
     /** Path to the streaming output transcript file. */
     outputFile?: string;
+    /** Absolute path to the durable project-local transcript while live. */
+    historyFile?: string;
+    /** Project-relative durable transcript path persisted in the parent session. */
+    transcriptPath?: string;
     /** Cleanup function for the output file stream subscription. */
     outputCleanup?: () => void;
     /**

package/dist/ui/conversation-viewer.d.ts

@@ -12,6 +12,9 @@ import { type AgentActivity } from "./agent-widget.js";
 import { type ViewerKeybindings } from "./viewer-keys.js";
 /** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
 export declare const VIEWPORT_HEIGHT_PCT = 70;
+/** The live fields needed by the viewer; historical viewers use a static source. */
+export type ConversationSource = Pick<AgentSession, "messages" | "subscribe">;
+export declare function createStaticConversationSource(messages: AgentSession["messages"]): ConversationSource;
 export declare class ConversationViewer implements Component {
     private tui;
     private session;
@@ -33,7 +36,7 @@ export declare class ConversationViewer implements Component {
     private keys;
     /** Steering composer — present while the user is typing a message to the agent. */
     private composer;
-    constructor(tui: TUI, session: AgentSession, record: AgentRecord, activity: AgentActivity | undefined, theme: Theme, done: (result: undefined) => void, 
+    constructor(tui: TUI, session: ConversationSource, record: AgentRecord, activity: AgentActivity | undefined, theme: Theme, done: (result: undefined) => void, 
     /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
     onStop?: (() => void) | undefined, 
     /** User keybindings from `ctx.ui.custom()`. Omitted → hardcoded defaults. */

package/dist/ui/conversation-viewer.js

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConversationViewer = exports.VIEWPORT_HEIGHT_PCT = void 0;
+exports.createStaticConversationSource = createStaticConversationSource;
 const pi_tui_1 = require("@earendil-works/pi-tui");
 const context_js_1 = require("../context.js");
 const usage_js_1 = require("../usage.js");
@@ -17,6 +18,9 @@ const CHROME_LINES_BASE = 6;
 const MIN_VIEWPORT = 3;
 /** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
 exports.VIEWPORT_HEIGHT_PCT = 70;
+function createStaticConversationSource(messages) {
+    return { messages, subscribe: () => () => { } };
+}
 class ConversationViewer {
     tui;
     session;

package/dist/ui/fleet-list.d.ts

@@ -44,6 +44,7 @@ export declare function formatFleetTokens(count: number): string;
 export declare class FleetList {
     private manager;
     private agentActivity;
+    private getCwd;
     private ui;
     private tui;
     private inputUnsub;
@@ -57,7 +58,7 @@ export declare class FleetList {
     /** Set while a conversation overlay is open; calling it closes the overlay. */
     private viewerClose;
     private viewingAgentId;
-    constructor(manager: AgentManager, agentActivity: Map<string, AgentActivity>);
+    constructor(manager: AgentManager, agentActivity: Map<string, AgentActivity>, getCwd?: () => string | undefined);
     setEnabled(enabled: boolean): void;
     /** Capture the UI context and (re)register the global input handler. */
     setUICtx(ui: FleetUICtx): void;

package/dist/ui/fleet-list.js

@@ -15,7 +15,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FleetList = void 0;
 exports.formatFleetElapsed = formatFleetElapsed;
 exports.formatFleetTokens = formatFleetTokens;
+const node_fs_1 = require("node:fs");
 const pi_tui_1 = require("@earendil-works/pi-tui");
+const agent_history_js_1 = require("../agent-history.js");
 const usage_js_1 = require("../usage.js");
 const agent_widget_js_1 = require("./agent-widget.js");
 const conversation_viewer_js_1 = require("./conversation-viewer.js");
@@ -57,6 +59,7 @@ function rightAlign(left, right, width) {
 class FleetList {
     manager;
     agentActivity;
+    getCwd;
     ui;
     tui;
     inputUnsub;
@@ -70,9 +73,10 @@ class FleetList {
     /** Set while a conversation overlay is open; calling it closes the overlay. */
     viewerClose;
     viewingAgentId;
-    constructor(manager, agentActivity) {
+    constructor(manager, agentActivity, getCwd = () => undefined) {
         this.manager = manager;
         this.agentActivity = agentActivity;
+        this.getCwd = getCwd;
     }
     // ---- Lifecycle ----
     setEnabled(enabled) {
@@ -172,9 +176,17 @@ class FleetList {
     agentRecords() {
         const now = Date.now();
         return this.manager.listAgents()
-            .filter(a => a.session && (a.status === "running" || a.status === "queued"
-            || a.id === this.viewingAgentId
-            || (a.completedAt != null && now - a.completedAt < FINISHED_LINGER_MS)))
+            .filter(a => {
+            const live = a.session && (a.status === "running" || a.status === "queued"
+                || a.id === this.viewingAgentId
+                || (a.completedAt != null && now - a.completedAt < FINISHED_LINGER_MS));
+            const cwd = this.getCwd();
+            const historyPath = cwd && a.transcriptPath
+                ? (0, agent_history_js_1.resolveAgentHistoryPath)(cwd, a.transcriptPath)
+                : undefined;
+            const history = !!historyPath && (0, node_fs_1.existsSync)(historyPath);
+            return !!live || history;
+        })
             .sort((a, b) => a.startedAt - b.startedAt);
     }
     roster() {
@@ -275,19 +287,25 @@ class FleetList {
         const record = entry.record;
         if (!this.ui)
             return;
-        if (!record.session) {
-            this.ui.notify(`Agent is ${record.status} — no session available.`, "info");
+        const session = record.session ?? (record.transcriptPath && this.getCwd()
+            ? (() => {
+                const messages = (0, agent_history_js_1.readAgentHistory)(this.getCwd(), record.transcriptPath);
+                return messages ? (0, conversation_viewer_js_1.createStaticConversationSource)(messages) : undefined;
+            })()
+            : undefined);
+        if (!session) {
+            this.ui.notify(`Agent is ${record.status} — no history available.`, "info");
             return;
         }
-        const session = record.session;
         const activity = this.agentActivity.get(record.id);
+        const isLive = record.session !== undefined;
         this.viewingAgentId = record.id;
         void this.ui.custom((tui, theme, keybindings, done) => {
             this.viewerClose = () => done(undefined);
-            return new conversation_viewer_js_1.ConversationViewer(tui, session, record, activity, theme, done, () => {
+            return new conversation_viewer_js_1.ConversationViewer(tui, session, record, activity, theme, done, isLive ? () => {
                 if (this.manager.abort(record.id))
                     this.ui?.notify(`Stopped "${record.description}".`, "info");
-            }, keybindings, (message) => this.manager.steer(record.id, message));
+            } : undefined, keybindings, isLive ? (message) => this.manager.steer(record.id, message) : undefined);
         }, {
             overlay: true,
             overlayOptions: { anchor: "center", width: "90%", maxHeight: `${conversation_viewer_js_1.VIEWPORT_HEIGHT_PCT}%` },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.15.1",
+  "version": "0.15.3",
   "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.ts

@@ -0,0 +1,100 @@
+/** Durable, project-local transcript storage for subagents. */
+
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+
+const SUBAGENTS_DIR = ".pi-subagents";
+const TRANSCRIPTS_DIR = "agent-transcripts";
+const MAX_HISTORY_BYTES = 20 * 1024 * 1024;
+
+/**
+ * Ensure project-local subagent artifacts are ignored by git.
+ *
+ * The rule is appended instead of rewriting the file. This preserves any
+ * existing user-owned rules and makes concurrent callers harmless (duplicate
+ * `*` rules are semantically equivalent).
+ */
+export function ensureSubagentsGitignore(cwd: string): string {
+  const directory = join(cwd, SUBAGENTS_DIR);
+  mkdirSync(directory, { recursive: true });
+  const path = join(directory, ".gitignore");
+
+  let content = "";
+  try {
+    content = readFileSync(path, "utf8");
+  } catch {
+    // The append below also creates a missing file.
+  }
+
+  if (!content.split(/\r?\n/).some((line) => line.trim() === "*")) {
+    const separator = content.length > 0 && !/[\r\n]$/.test(content) ? "\n" : "";
+    appendFileSync(path, `${separator}*\n`, "utf8");
+  }
+  return path;
+}
+
+/** Return the durable transcript path for an agent. */
+export function createAgentHistoryPath(
+  cwd: string,
+  agentId: string,
+  agentType = "agent",
+): string {
+  ensureSubagentsGitignore(cwd);
+  const directory = join(cwd, SUBAGENTS_DIR, TRANSCRIPTS_DIR);
+  mkdirSync(directory, { recursive: true });
+  const safeId = agentId.replace(/[^A-Za-z0-9._-]+/g, "-") || "agent";
+  const safeType = agentType.replace(/[^A-Za-z0-9._-]+/g, "-") || "agent";
+  return join(directory, `${safeId}_${safeType}_transcript.jsonl`);
+}
+
+/** Return the project-relative path stored in the parent session record. */
+export function agentHistoryLocator(cwd: string, historyPath: string): string {
+  return relative(cwd, historyPath).split(sep).join("/");
+}
+
+/** Resolve only paths in this package's project-local transcript namespace. */
+export function resolveAgentHistoryPath(cwd: string, locator: string): string | undefined {
+  if (!locator || isAbsolute(locator)) return undefined;
+  const root = resolve(cwd, SUBAGENTS_DIR, TRANSCRIPTS_DIR);
+  const candidate = resolve(cwd, locator);
+  if (candidate !== root && !candidate.startsWith(`${root}${sep}`)) return undefined;
+  return candidate;
+}
+
+/**
+ * Read persisted transcript entries into the message shape used by the live
+ * conversation viewer. Malformed lines and unknown records are skipped so one
+ * damaged entry cannot hide the rest of a history.
+ */
+export function readAgentHistory(
+  cwd: string,
+  locator: string,
+): AgentSession["messages"] | undefined {
+  const path = resolveAgentHistoryPath(cwd, locator);
+  if (!path) return undefined;
+
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+  if (raw.length > MAX_HISTORY_BYTES) raw = raw.slice(0, MAX_HISTORY_BYTES);
+
+  const messages: AgentSession["messages"] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const entry = JSON.parse(line) as { message?: unknown };
+      const message = entry.message;
+      if (!message || typeof message !== "object") continue;
+      const role = (message as { role?: unknown }).role;
+      if (typeof role !== "string") continue;
+      messages.push(message as AgentSession["messages"][number]);
+    } catch {
+      // Ignore malformed/truncated JSONL records.
+    }
+  }
+  return messages.length > 0 ? messages : undefined;
+}

package/src/agent-manager.ts

@@ -23,6 +23,13 @@ export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; toke
 
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
+const TERMINAL_STATUSES = new Set<AgentRecord["status"]>([
+  "completed",
+  "steered",
+  "aborted",
+  "stopped",
+  "error",
+]);
 
 /**
  * Validate a caller-supplied SpawnOptions.cwd. `undefined`/`null` mean "unset"
@@ -97,6 +104,45 @@ interface SpawnOptions {
   onCompaction?: (info: CompactionInfo) => void;
 }
 
+const RESTORABLE_STATUSES = new Set<AgentRecord["status"]>([
+  "completed",
+  "steered",
+  "aborted",
+  "stopped",
+  "error",
+]);
+
+type PersistedAgentRecord = Pick<
+  AgentRecord,
+  "id" | "type" | "description" | "status" | "result" | "error" | "startedAt" | "completedAt" | "transcriptPath"
+>;
+
+function isRestorableRecord(value: unknown): value is PersistedAgentRecord {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  const transcriptPath = record.transcriptPath;
+  const validTranscriptPath =
+    transcriptPath === undefined ||
+    (typeof transcriptPath === "string" &&
+      transcriptPath.startsWith(".pi-subagents/agent-transcripts/") &&
+      !transcriptPath.includes("..") &&
+      !transcriptPath.includes("\\"));
+  return (
+    typeof record.id === "string" &&
+    record.id.length > 0 &&
+    typeof record.type === "string" &&
+    typeof record.description === "string" &&
+    RESTORABLE_STATUSES.has(record.status as AgentRecord["status"]) &&
+    typeof record.startedAt === "number" &&
+    Number.isFinite(record.startedAt) &&
+    typeof record.completedAt === "number" &&
+    Number.isFinite(record.completedAt) &&
+    (record.result === undefined || typeof record.result === "string") &&
+    (record.error === undefined || typeof record.error === "string") &&
+    validTranscriptPath
+  );
+}
+
 export class AgentManager {
   private agents = new Map<string, AgentRecord>();
   private cleanupInterval: ReturnType<typeof setInterval>;
@@ -510,6 +556,41 @@ export class AgentManager {
     return this.agents.get(id);
   }
 
+  /**
+   * Restore terminal records persisted in a parent session.
+   *
+   * Restored records deliberately have no live session, promise, or abort
+   * controller. Invalid data is ignored because session entries are persisted
+   * extension data and may have been written by an older version.
+   */
+  restoreCompleted(records: readonly unknown[]): void {
+    const restoredIds = new Set<string>();
+    // getBranch() is chronological; newest persisted state wins on duplicate IDs.
+    for (const value of [...records].reverse()) {
+      if (!isRestorableRecord(value)) continue;
+      if (restoredIds.has(value.id) || this.agents.has(value.id)) continue;
+      restoredIds.add(value.id);
+
+      this.agents.set(value.id, {
+        id: value.id,
+        type: value.type,
+        description: value.description,
+        status: value.status,
+        result: value.result,
+        error: value.error,
+        transcriptPath: value.transcriptPath,
+        toolUses: 0,
+        startedAt: value.startedAt,
+        completedAt: value.completedAt,
+        lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+        compactionCount: 0,
+        // Historical records have no inline tool surface and should remain
+        // visible in the background widget.
+        isBackground: true,
+      });
+    }
+  }
+
   listAgents(): AgentRecord[] {
     return [...this.agents.values()].sort(
       (a, b) => b.startedAt - a.startedAt,

package/src/index.ts

@@ -24,6 +24,7 @@ import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabl
 import { GroupJoinManager } from "./group-join.js";
 import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
+import { agentHistoryLocator, createAgentHistoryPath, readAgentHistory, ensureSubagentsGitignore } from "./agent-history.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
@@ -462,11 +463,14 @@ export default function (pi: ExtensionAPI) {
       pi.events.emit("subagents:completed", eventData);
     }
 
-    // Persist final record for cross-extension history reconstruction
+    // Persist final record for cross-extension history reconstruction. Keep
+    // the transcript body in a project-local file rather than inflating the
+    // parent session JSONL; only its project-relative locator is persisted.
     pi.appendEntry("subagents:record", {
       id: record.id, type: record.type, description: record.description,
       status: record.status, result: record.result, error: record.error,
       startedAt: record.startedAt, completedAt: record.completedAt,
+      transcriptPath: record.transcriptPath,
     });
 
     // Skip notification if result was already consumed via get_subagent_result
@@ -570,7 +574,22 @@ export default function (pi: ExtensionAPI) {
   // bound session_start, so a filtered-out activation never advertises (#142).
   pi.on("session_start", async (_event, ctx) => {
     currentCtx = ctx;
+    try {
+      ensureSubagentsGitignore(ctx.cwd);
+    } catch (err) {
+      console.warn("[pi-subagents] Failed to protect project-local history:", err);
+    }
     manager.clearCompleted(true);
+    const historicalRecords = ctx.sessionManager
+      .getBranch()
+      .filter((entry: any) => entry?.type === "custom" && entry.customType === "subagents:record")
+      .map((entry: any) => entry.data);
+    manager.restoreCompleted(historicalRecords);
+    // Bind the UI here as well as on tool execution so rehydrated terminal
+    // records are immediately visible and openable from FleetView after reload.
+    widget.setUICtx(ctx.ui as UICtx);
+    fleet.setUICtx(ctx.ui as unknown as FleetUICtx);
+    fleet.update();
     // Guard mirrors the `!scheduler.isActive()` pattern below: session_start
     // fires once per activation, but a double-bind must not leak listeners.
     if (!rpcHandle) {
@@ -625,7 +644,7 @@ export default function (pi: ExtensionAPI) {
   function setWidgetMode(m: WidgetMode): void { widgetMode = m; widget.update(); }
 
   // Claude Code-style FleetView: navigable list of main + subagents below the editor.
-  const fleet = new FleetList(manager, agentActivity);
+  const fleet = new FleetList(manager, agentActivity, () => currentCtx?.cwd);
   let fleetViewEnabled = true;
   function isFleetViewEnabled(): boolean { return fleetViewEnabled; }
   function setFleetViewEnabled(b: boolean): void { fleetViewEnabled = b; fleet.setEnabled(b); }
@@ -1156,6 +1175,19 @@ Terse command-style prompts produce shallow, generic work.
         if (!rec || !outputTranscript) return;
         rec.outputFile = createOutputFilePath(ctx.cwd, agentId, ctx.sessionManager.getSessionId());
         writeInitialEntry(rec.outputFile, agentId, params.prompt, ctx.cwd);
+
+        // Keep the existing /tmp output for compatibility, while also writing a
+        // durable project-local copy for reload-safe, read-only history viewing.
+        try {
+          rec.historyFile = createAgentHistoryPath(ctx.cwd, agentId, subagentType);
+          rec.transcriptPath = agentHistoryLocator(ctx.cwd, rec.historyFile);
+          writeInitialEntry(rec.historyFile, agentId, params.prompt, ctx.cwd);
+        } catch (err) {
+          // History is best effort; never disable the existing output transcript.
+          rec.historyFile = undefined;
+          rec.transcriptPath = undefined;
+          console.warn("[pi-subagents] Failed to create durable transcript:", err);
+        }
       };
 
       const parentModelId = ctx.model?.id;
@@ -1265,7 +1297,7 @@ Terse command-style prompts produce shallow, generic work.
           origBgOnSession(session);
           const rec = manager.getRecord(id);
           if (rec?.outputFile) {
-            rec.outputCleanup = streamToOutputFile(session, rec.outputFile, id, ctx.cwd);
+            rec.outputCleanup = streamToOutputFile(session, rec.outputFile, id, ctx.cwd, rec.historyFile);
           }
         };
 
@@ -1381,7 +1413,7 @@ Terse command-style prompts produce shallow, generic work.
         if (fgId) {
           const rec = manager.getRecord(fgId);
           if (rec?.outputFile) {
-            rec.outputCleanup = streamToOutputFile(session, rec.outputFile, fgId, ctx.cwd);
+            rec.outputCleanup = streamToOutputFile(session, rec.outputFile, fgId, ctx.cwd, rec.historyFile);
           }
         }
       };
@@ -1788,17 +1820,30 @@ Terse command-style prompts produce shallow, generic work.
       return;
     }
 
-    const { ConversationViewer, VIEWPORT_HEIGHT_PCT } = await import("./ui/conversation-viewer.js");
-    const session = record.session;
+    const { ConversationViewer, VIEWPORT_HEIGHT_PCT, createStaticConversationSource } = await import("./ui/conversation-viewer.js");
+    const session = record.session ?? (record.transcriptPath
+      ? (() => {
+          const messages = readAgentHistory(ctx.cwd, record.transcriptPath!);
+          return messages ? createStaticConversationSource(messages) : undefined;
+        })()
+      : undefined);
+    if (!session) {
+      ctx.ui.notify(`Agent is ${record.status === "queued" ? "queued" : "expired"} — no history available.`, "info");
+      return;
+    }
     const activity = agentActivity.get(record.id);
+    const isLive = record.session !== undefined;
 
     await ctx.ui.custom<undefined>(
       (tui, theme, keybindings, done) => {
-        return new ConversationViewer(tui, session, record, activity, theme, done, () => {
-          if (manager.abort(record.id)) {
-            ctx.ui.notify(`Stopped "${record.description}".`, "info");
-          }
-        }, keybindings, (message: string) => manager.steer(record.id, message));
+        return new ConversationViewer(tui, session, record, activity, theme, done,
+          isLive ? () => {
+            if (manager.abort(record.id)) {
+              ctx.ui.notify(`Stopped "${record.description}".`, "info");
+            }
+          } : undefined,
+          keybindings,
+          isLive ? (message: string) => manager.steer(record.id, message) : undefined);
       },
       {
         overlay: true,

package/src/output-file.ts

@@ -63,7 +63,9 @@ export function streamToOutputFile(
   path: string,
   agentId: string,
   cwd: string,
+  historyPath?: string,
 ): () => void {
+  const outputPaths = historyPath && historyPath !== path ? [path, historyPath] : [path];
   let writtenCount = 1; // initial user prompt already written
 
   const flush = () => {
@@ -78,9 +80,11 @@ export function streamToOutputFile(
         timestamp: new Date().toISOString(),
         cwd,
       };
-      try {
-        appendFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
-      } catch { /* ignore write errors */ }
+      for (const outputPath of outputPaths) {
+        try {
+          appendFileSync(outputPath, JSON.stringify(entry) + "\n", "utf-8");
+        } catch { /* ignore write errors */ }
+      }
       writtenCount++;
     }
   };

package/src/types.ts

@@ -105,6 +105,10 @@ export interface AgentRecord {
   toolCallId?: string;
   /** Path to the streaming output transcript file. */
   outputFile?: string;
+  /** Absolute path to the durable project-local transcript while live. */
+  historyFile?: string;
+  /** Project-relative durable transcript path persisted in the parent session. */
+  transcriptPath?: string;
   /** Cleanup function for the output file stream subscription. */
   outputCleanup?: () => void;
   /**

package/src/ui/conversation-viewer.ts

@@ -20,6 +20,15 @@ const MIN_VIEWPORT = 3;
 /** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
 export const VIEWPORT_HEIGHT_PCT = 70;
 
+/** The live fields needed by the viewer; historical viewers use a static source. */
+export type ConversationSource = Pick<AgentSession, "messages" | "subscribe">;
+
+export function createStaticConversationSource(
+  messages: AgentSession["messages"],
+): ConversationSource {
+  return { messages, subscribe: () => () => {} };
+}
+
 export class ConversationViewer implements Component {
   private scrollOffset = 0;
   private autoScroll = true;
@@ -34,7 +43,7 @@ export class ConversationViewer implements Component {
 
   constructor(
     private tui: TUI,
-    private session: AgentSession,
+    private session: ConversationSource,
     private record: AgentRecord,
     private activity: AgentActivity | undefined,
     private theme: Theme,

package/src/ui/fleet-list.ts

@@ -11,12 +11,14 @@
  * can `consume` keys — gated on `getEditorText() === ""` so normal typing is untouched.
  */
 
+import { existsSync } from "node:fs";
 import { Editor, isKeyRelease, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { AgentManager } from "../agent-manager.js";
+import { readAgentHistory, resolveAgentHistoryPath } from "../agent-history.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal } from "../usage.js";
 import { type AgentActivity, getDisplayName, type Theme } from "./agent-widget.js";
-import { ConversationViewer, VIEWPORT_HEIGHT_PCT } from "./conversation-viewer.js";
+import { ConversationViewer, createStaticConversationSource, VIEWPORT_HEIGHT_PCT } from "./conversation-viewer.js";
 
 /** Widget key for the below-editor fleet list. */
 const FLEET_KEY = "fleet";
@@ -93,6 +95,7 @@ export class FleetList {
   constructor(
     private manager: AgentManager,
     private agentActivity: Map<string, AgentActivity>,
+    private getCwd: () => string | undefined = () => undefined,
   ) {}
 
   // ---- Lifecycle ----
@@ -188,11 +191,19 @@ export class FleetList {
   private agentRecords(): AgentRecord[] {
     const now = Date.now();
     return this.manager.listAgents()
-      .filter(a => a.session && (
-        a.status === "running" || a.status === "queued"
-        || a.id === this.viewingAgentId
-        || (a.completedAt != null && now - a.completedAt < FINISHED_LINGER_MS)
-      ))
+      .filter(a => {
+        const live = a.session && (
+          a.status === "running" || a.status === "queued"
+          || a.id === this.viewingAgentId
+          || (a.completedAt != null && now - a.completedAt < FINISHED_LINGER_MS)
+        );
+        const cwd = this.getCwd();
+        const historyPath = cwd && a.transcriptPath
+          ? resolveAgentHistoryPath(cwd, a.transcriptPath)
+          : undefined;
+        const history = !!historyPath && existsSync(historyPath);
+        return !!live || history;
+      })
       .sort((a, b) => a.startedAt - b.startedAt);
   }
 
@@ -287,12 +298,18 @@ export class FleetList {
     }
     const record = entry.record;
     if (!this.ui) return;
-    if (!record.session) {
-      this.ui.notify(`Agent is ${record.status} — no session available.`, "info");
+    const session = record.session ?? (record.transcriptPath && this.getCwd()
+      ? (() => {
+          const messages = readAgentHistory(this.getCwd()!, record.transcriptPath!);
+          return messages ? createStaticConversationSource(messages) : undefined;
+        })()
+      : undefined);
+    if (!session) {
+      this.ui.notify(`Agent is ${record.status} — no history available.`, "info");
       return;
     }
-    const session = record.session;
     const activity = this.agentActivity.get(record.id);
+    const isLive = record.session !== undefined;
     this.viewingAgentId = record.id;
 
     void this.ui.custom<undefined>(
@@ -305,11 +322,11 @@ export class FleetList {
           activity,
           theme,
           done,
-          () => {
+          isLive ? () => {
             if (this.manager.abort(record.id)) this.ui?.notify(`Stopped "${record.description}".`, "info");
-          },
+          } : undefined,
           keybindings,
-          (message: string) => this.manager.steer(record.id, message),
+          isLive ? (message: string) => this.manager.steer(record.id, message) : undefined,
         );
       },
       {

package/test/agent-history.test.ts

@@ -0,0 +1,59 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  agentHistoryLocator,
+  createAgentHistoryPath,
+  ensureSubagentsGitignore,
+  readAgentHistory,
+  resolveAgentHistoryPath,
+} from "../src/agent-history.js";
+import { writeInitialEntry } from "../src/output-file.js";
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+  for (const directory of tempDirectories.splice(0)) {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+function tempProject(): string {
+  const path = mkdtempSync(join(tmpdir(), "pi-subagents-history-test-"));
+  tempDirectories.push(path);
+  return path;
+}
+
+describe("project-local subagent history", () => {
+  it("creates a gitignore rule and preserves existing rules", () => {
+    const cwd = tempProject();
+    const root = join(cwd, ".pi-subagents");
+    const gitignore = join(root, ".gitignore");
+    const path = ensureSubagentsGitignore(cwd);
+
+    expect(path).toBe(gitignore);
+    expect(readFileSync(gitignore, "utf8")).toBe("*\n");
+
+    writeFileSync(gitignore, "keep-this\n", "utf8");
+    ensureSubagentsGitignore(cwd);
+    ensureSubagentsGitignore(cwd);
+    expect(readFileSync(gitignore, "utf8")).toBe("keep-this\n*\n");
+  });
+
+  it("creates a bounded project-relative transcript locator", () => {
+    const cwd = tempProject();
+    const historyPath = createAgentHistoryPath(cwd, "agent-1", "Explore");
+    const locator = agentHistoryLocator(cwd, historyPath);
+
+    expect(locator).toBe(".pi-subagents/agent-transcripts/agent-1_Explore_transcript.jsonl");
+    expect(resolveAgentHistoryPath(cwd, locator)).toBe(historyPath);
+    expect(resolveAgentHistoryPath(cwd, ".pi-subagents/other.jsonl")).toBeUndefined();
+    expect(resolveAgentHistoryPath(cwd, ".pi-subagents/agent-transcripts/../other.jsonl")).toBeUndefined();
+
+    writeInitialEntry(historyPath, "agent-1", "hello", cwd);
+    const messages = readAgentHistory(cwd, locator);
+    expect(messages).toHaveLength(1);
+    expect(messages?.[0]).toMatchObject({ role: "user", content: "hello" });
+  });
+});

package/test/agent-manager-history.test.ts

@@ -0,0 +1,87 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { AgentManager } from "../src/agent-manager.js";
+
+type PersistedRecord = {
+  id: string;
+  type: string;
+  description: string;
+  status: string;
+  result?: unknown;
+  error?: unknown;
+  startedAt: number;
+  completedAt: number;
+  transcriptPath?: string;
+};
+
+function persisted(overrides: Partial<PersistedRecord> = {}): PersistedRecord {
+  return {
+    id: "agent-1",
+    type: "general-purpose",
+    description: "history test",
+    status: "completed",
+    result: "restored result",
+    startedAt: 100,
+    completedAt: 200,
+    ...overrides,
+  };
+}
+
+describe("AgentManager.restoreCompleted", () => {
+  let manager: AgentManager | undefined;
+
+  afterEach(() => {
+    manager?.dispose();
+    manager = undefined;
+  });
+
+  it("restores terminal records without creating live runtime state", () => {
+    manager = new AgentManager();
+
+    manager.restoreCompleted([
+      persisted(),
+      persisted({ id: "agent-error", status: "error", error: "failed", transcriptPath: ".pi-subagents/agent-transcripts/agent-error.jsonl" }),
+      persisted({ id: "agent-running", status: "running" }),
+      persisted({ id: "agent-queued", status: "queued" }),
+      persisted({ id: "agent-invalid", completedAt: Number.NaN }),
+      persisted({ id: "agent-unsafe", transcriptPath: ".pi-subagents/../private.jsonl" }),
+    ]);
+
+    expect(manager.listAgents().map((record) => record.id).sort()).toEqual([
+      "agent-1",
+      "agent-error",
+    ]);
+    const restored = manager.getRecord("agent-1");
+    expect(restored).toMatchObject({
+      status: "completed",
+      result: "restored result",
+      toolUses: 0,
+      lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+      compactionCount: 0,
+      isBackground: true,
+      transcriptPath: undefined,
+    });
+    expect(restored?.session).toBeUndefined();
+    expect(restored?.promise).toBeUndefined();
+    expect(restored?.abortController).toBeUndefined();
+  });
+
+  it("uses the newest branch entry when an id appears more than once", () => {
+    manager = new AgentManager();
+
+    manager.restoreCompleted([
+      persisted({ result: "old", completedAt: 200 }),
+      persisted({ result: "new", completedAt: 300 }),
+    ]);
+
+    expect(manager.getRecord("agent-1")?.result).toBe("new");
+  });
+
+  it("does not overwrite a record already held by the manager", () => {
+    manager = new AgentManager();
+
+    manager.restoreCompleted([persisted({ result: "first" })]);
+    manager.restoreCompleted([persisted({ result: "second" })]);
+
+    expect(manager.getRecord("agent-1")?.result).toBe("first");
+  });
+});