@oh-my-pi/pi-coding-agent 16.3.5 → 16.3.7

package/src/internal-urls/memory-protocol.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { getAgentDir, isEnoent } from "@oh-my-pi/pi-utils";
 import { getMemoryRoot } from "../memories";
+import { getMnemopiSessionState, type MnemopiScopedMemoryHit, type MnemopiSessionState } from "../mnemopi/state";
 import { AgentRegistry } from "../registry/agent-registry";
 import { buildDirectoryResource } from "./filesystem-resource";
 import { validateRelativePath } from "./skill-protocol";
@@ -124,6 +125,75 @@ async function tryResolveInRoot(url: InternalUrl, memoryRoot: string): Promise<I
 	};
 }
 
+/**
+ * Snapshot of live mnemopi session states, deduplicated. A mnemopi backend
+ * always keeps its state on the {@link AgentSession} it was initialised for;
+ * subagents alias their parent's state, so different `session` objects can
+ * point at the same underlying banks. The dedupe below picks the
+ * canonical (non-aliased) state per bank set so `memory://<id>` resolves in
+ * one pass regardless of how many subagents are alive.
+ */
+function mnemopiSessionStatesFromRegistry(): MnemopiSessionState[] {
+	const seen = new Set<unknown>();
+	const states: MnemopiSessionState[] = [];
+	for (const ref of AgentRegistry.global().list()) {
+		const session = ref.session;
+		if (!session) continue;
+		const state = getMnemopiSessionState(session);
+		if (!state) continue;
+		const primary = state.aliasOf ?? state;
+		if (seen.has(primary)) continue;
+		seen.add(primary);
+		states.push(primary);
+	}
+	return states;
+}
+
+/**
+ * Look up a mnemopi memory row by id across every live session's scoped banks.
+ * First hit wins; returns `null` when the id is not stored anywhere in scope.
+ */
+function tryResolveMnemopiMemory(id: string): MnemopiScopedMemoryHit | null {
+	for (const state of mnemopiSessionStatesFromRegistry()) {
+		const hit = state?.getScopedMemory(id);
+		if (hit) return hit;
+	}
+	return null;
+}
+
+/**
+ * Render a mnemopi memory row as text/markdown with a small YAML-front-matter
+ * header. The frontmatter carries the metadata an agent needs to reason about
+ * a working vs episodic memory (bank, store, timestamps, importance) without
+ * having to reconstruct it from the recall preview.
+ */
+function renderMnemopiMemory(url: InternalUrl, hit: MnemopiScopedMemoryHit): InternalResource {
+	const { row, bank, store } = hit;
+	const meta = row.metadata == null ? "" : `metadata: ${JSON.stringify(row.metadata)}\n`;
+	const header =
+		"---\n" +
+		`id: ${row.id}\n` +
+		`bank: ${bank}\n` +
+		`store: ${store}\n` +
+		(row.memory_type ? `memory_type: ${row.memory_type}\n` : "") +
+		(row.source ? `source: ${row.source}\n` : "") +
+		(row.timestamp ? `timestamp: ${row.timestamp}\n` : "") +
+		(row.created_at ? `created_at: ${row.created_at}\n` : "") +
+		(row.importance != null ? `importance: ${row.importance}\n` : "") +
+		(row.veracity ? `veracity: ${row.veracity}\n` : "") +
+		(row.session_id ? `session_id: ${row.session_id}\n` : "") +
+		meta +
+		"---\n\n";
+	const content = `${header}${row.content}`;
+	return {
+		url: url.href,
+		content,
+		contentType: "text/markdown",
+		size: Buffer.byteLength(content, "utf-8"),
+		notes: [],
+	};
+}
+
 /**
  * Protocol handler for memory:// URLs.
  *
@@ -136,8 +206,31 @@ export class MemoryProtocolHandler implements ProtocolHandler {
 	readonly immutable = true;
 
 	async resolve(url: InternalUrl): Promise<InternalResource> {
-		const roots = memoryRootsFromRegistry();
+		const namespace = url.rawHost || url.hostname;
+		if (!namespace) {
+			throw new Error("memory:// URL requires a namespace: memory://root or memory://<memory-id>");
+		}
 
+		// Mnemopi rows live in SQLite banks per session, keyed by memory id.
+		// Any host other than the file-backed `root` namespace is treated as a
+		// mnemopi memory id lookup. This is the read counterpart to
+		// `memory_edit update` and lets agents inspect the full content of a
+		// clipped recall preview before overwriting it (issue #4443).
+		if (namespace !== MEMORY_NAMESPACE) {
+			const mnemopiStates = mnemopiSessionStatesFromRegistry();
+			if (mnemopiStates.length === 0) {
+				throw new Error(
+					`Unknown memory namespace: ${namespace}. Supported: ${MEMORY_NAMESPACE} (file-backed memory summary), or a mnemopi memory id when memory.backend=mnemopi is active.`,
+				);
+			}
+			const hit = tryResolveMnemopiMemory(namespace);
+			if (hit) return renderMnemopiMemory(url, hit);
+			throw new Error(
+				`Mnemopi memory ${namespace} not found in any scoped bank. Use \`recall\` to list available ids.`,
+			);
+		}
+
+		const roots = memoryRootsFromRegistry();
 		if (roots.length === 0) {
 			throw new Error(
 				"Memory artifacts are not available for this project yet. Run a session with memories enabled first.",
@@ -167,7 +260,16 @@ export class MemoryProtocolHandler implements ProtocolHandler {
 	}
 
 	async complete(): Promise<UrlCompletion[]> {
-		if (memoryRootsFromRegistry().length === 0) return [];
-		return [{ value: MEMORY_NAMESPACE, description: "Project memory summary" }];
+		const completions: UrlCompletion[] = [];
+		if (memoryRootsFromRegistry().length > 0) {
+			completions.push({ value: MEMORY_NAMESPACE, description: "Project memory summary" });
+		}
+		if (mnemopiSessionStatesFromRegistry().length > 0) {
+			completions.push({
+				value: "<memory-id>",
+				description: "Full mnemopi memory by id (from recall)",
+			});
+		}
+		return completions;
 	}
 }

package/src/lsp/client.ts

@@ -176,6 +176,19 @@ const CLIENT_CAPABILITIES = {
 	},
 };
 
+/** LSP `FileChangeType` values for workspace/didChangeWatchedFiles notifications. */
+export enum FileChangeType {
+	Created = 1,
+	Changed = 2,
+	Deleted = 3,
+}
+
+/** Filesystem change authored by the harness and announced to active LSP clients. */
+export interface WatchedFileChange {
+	filePath: string;
+	type: FileChangeType;
+}
+
 // =============================================================================
 // LSP Message Protocol
 // =============================================================================
@@ -944,6 +957,63 @@ export async function notifySaved(client: LspClient, filePath: string, signal?:
 	client.lastActivity = Date.now();
 }
 
+function isPathInsideWorkspace(filePath: string, workspace: string): boolean {
+	const relative = path.relative(workspace, path.resolve(filePath));
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+/** Budget for the one-way watched-files notification: a wedged server that
+ *  stops draining stdin must never hang the filesystem mutation that
+ *  triggered it. Failures degrade to a debug log below. */
+const WATCHED_FILES_NOTIFY_TIMEOUT_MS = 2_000;
+
+/**
+ * Announce harness-authored filesystem changes to active LSP clients for `cwd`.
+ *
+ * This covers sibling files that are not open text documents, such as generated
+ * CSS modules or type files that another edited document imports immediately.
+ *
+ * The underlying stdin flush is self-bounded by
+ * {@link WATCHED_FILES_NOTIFY_TIMEOUT_MS}; only an abort of the caller's
+ * `signal` rejects.
+ */
+export async function notifyWorkspaceWatchedFiles(
+	cwd: string,
+	changes: readonly WatchedFileChange[],
+	signal?: AbortSignal,
+): Promise<void> {
+	throwIfAborted(signal);
+	if (changes.length === 0) return;
+
+	const workspace = path.resolve(cwd);
+	const activeClients = Array.from(clients.values()).filter(
+		client => client.status === "ready" && path.resolve(client.cwd) === workspace,
+	);
+	if (activeClients.length === 0) return;
+
+	const timeoutSignal = AbortSignal.timeout(WATCHED_FILES_NOTIFY_TIMEOUT_MS);
+	const sendSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+	const results = await Promise.allSettled(
+		activeClients.map(async client => {
+			const clientChanges = changes
+				.filter(change => isPathInsideWorkspace(change.filePath, workspace))
+				.map(change => {
+					const uri = fileToUri(change.filePath);
+					client.diagnostics.delete(uri);
+					return { uri, type: change.type };
+				});
+			if (clientChanges.length === 0) return;
+			await sendNotification(client, "workspace/didChangeWatchedFiles", { changes: clientChanges }, sendSignal);
+		}),
+	);
+	throwIfAborted(signal);
+	for (const result of results) {
+		if (result.status === "rejected") {
+			logger.debug("LSP watched-files notification failed", { cwd, error: String(result.reason) });
+		}
+	}
+}
+
 /**
  * Refresh a file in the LSP client.
  * Increments version, sends didChange and didSave notifications.

package/src/lsp/index.ts

@@ -18,10 +18,12 @@ import { ToolAbortError, ToolError, throwIfAborted } from "../tools/tool-errors"
 import { clampTimeout } from "../tools/tool-timeouts";
 import {
 	ensureFileOpen,
+	FileChangeType,
 	getActiveClients,
 	getOrCreateClient,
 	type LspServerStatus,
 	notifySaved,
+	notifyWorkspaceWatchedFiles,
 	refreshFile,
 	sendNotification,
 	sendRequest,
@@ -946,6 +948,7 @@ interface PendingWritethrough {
 	dst: string;
 	content: string;
 	file?: BunFile;
+	changeType: FileChangeType;
 }
 
 interface LspWritethroughBatchRequest {
@@ -1139,6 +1142,7 @@ async function runLspWritethrough(
 	content: string,
 	cwd: string,
 	options: ResolvedWritethroughOptions,
+	changeType: FileChangeType,
 	signal?: AbortSignal,
 	file?: BunFile,
 	deferred?: {
@@ -1147,16 +1151,42 @@ async function runLspWritethrough(
 	},
 ): Promise<FileDiagnosticsResult | undefined> {
 	const { enableFormat, enableDiagnostics } = options;
+
+	let finalContent = content;
+	const writeContent = async (value: string) => (file ? file.write(value) : Bun.write(dst, value));
+	const getWritePromise = once(() => writeContent(finalContent));
+	let writeNotified = false;
+	const notifyWriteCommitted = async (notifySignal: AbortSignal | undefined = signal) => {
+		if (writeNotified) return;
+		writeNotified = true;
+		try {
+			await notifyWorkspaceWatchedFiles(cwd, [{ filePath: dst, type: changeType }], notifySignal);
+		} catch (error) {
+			if (notifySignal?.aborted && !signal?.aborted) {
+				// The operation budget died mid-notify while the caller is still
+				// live: allow the post-write retry below to re-announce with the
+				// caller's signal (didChangeWatchedFiles is idempotent).
+				writeNotified = false;
+				return;
+			}
+			throw error;
+		}
+	};
+	if (!enableFormat && !enableDiagnostics) {
+		await getWritePromise();
+		await notifyWriteCommitted();
+		return undefined;
+	}
+
 	const config = getConfig(cwd);
 	const servers = getServersForFile(config, dst);
+
 	if (servers.length === 0) {
-		return writethroughNoop(dst, content, signal, file);
+		await getWritePromise();
+		await notifyWriteCommitted();
+		return undefined;
 	}
 	const { lspServers, customLinterServers } = splitServers(servers);
-
-	let finalContent = content;
-	const writeContent = async (value: string) => (file ? file.write(value) : Bun.write(dst, value));
-	const getWritePromise = once(() => writeContent(finalContent));
 	const useCustomFormatter = enableFormat && customLinterServers.length > 0;
 
 	// Capture diagnostic versions BEFORE syncing to detect stale diagnostics
@@ -1169,6 +1199,7 @@ async function runLspWritethrough(
 	let diagnostics: FileDiagnosticsResult | undefined;
 	let timedOut = false;
 	let synced = false;
+	let operationSignal: AbortSignal | undefined;
 	try {
 		const timeoutSignal = AbortSignal.timeout(5_000);
 		timeoutSignal.addEventListener(
@@ -1178,7 +1209,7 @@ async function runLspWritethrough(
 			},
 			{ once: true },
 		);
-		const operationSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+		operationSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
 		await untilAborted(operationSignal, async () => {
 			if (useCustomFormatter) {
 				// Custom linters (e.g. Biome CLI) require on-disk input.
@@ -1186,6 +1217,7 @@ async function runLspWritethrough(
 				finalContent = await formatContent(dst, content, cwd, customLinterServers, operationSignal);
 				formatter = finalContent !== content ? FileFormatResult.FORMATTED : FileFormatResult.UNCHANGED;
 				await writeContent(finalContent);
+				await notifyWriteCommitted(operationSignal);
 				await syncFileContent(dst, finalContent, cwd, lspServers, operationSignal);
 			} else {
 				// 1. Sync original content to LSP servers
@@ -1204,6 +1236,7 @@ async function runLspWritethrough(
 
 				// 4. Write to disk
 				await getWritePromise();
+				await notifyWriteCommitted(operationSignal);
 			}
 
 			if (enableDiagnostics) {
@@ -1232,6 +1265,10 @@ async function runLspWritethrough(
 			}
 		}
 		await getWritePromise();
+		// The write above committed even though the operation budget elapsed:
+		// announce it on the caller's signal — the dead `operationSignal` would
+		// abort the notify before it ever reaches the server.
+		await notifyWriteCommitted();
 	}
 
 	if (synced && enableDiagnostics) {
@@ -1279,7 +1316,16 @@ async function flushWritethroughBatch(
 				onDeferredDiagnostics: bundle.onDeferredDiagnostics,
 				signal: bundle.signal,
 			} as const);
-		const diag = await runLspWritethrough(entry.dst, entry.content, cwd, options, signal, entry.file, deferredInner);
+		const diag = await runLspWritethrough(
+			entry.dst,
+			entry.content,
+			cwd,
+			options,
+			entry.changeType,
+			signal,
+			entry.file,
+			deferredInner,
+		);
 		bundle?.finalize(diag);
 		results.push(diag);
 	}
@@ -1293,9 +1339,6 @@ export function createLspWritethrough(cwd: string, options?: WritethroughOptions
 		enableDiagnostics: options?.enableDiagnostics ?? false,
 		transformDiagnostics: options?.transformDiagnostics,
 	};
-	if (!resolvedOptions.enableFormat && !resolvedOptions.enableDiagnostics) {
-		return writethroughNoop;
-	}
 	return async (
 		dst: string,
 		content: string,
@@ -1304,6 +1347,7 @@ export function createLspWritethrough(cwd: string, options?: WritethroughOptions
 		batch?: LspWritethroughBatchRequest,
 		getDeferred?: (dst: string) => WritethroughDeferredHandle | undefined,
 	) => {
+		const changeType = (await Bun.file(dst).exists()) ? FileChangeType.Changed : FileChangeType.Created;
 		if (!batch) {
 			const bundle = getDeferred?.(dst);
 			const deferredInner =
@@ -1312,13 +1356,22 @@ export function createLspWritethrough(cwd: string, options?: WritethroughOptions
 					onDeferredDiagnostics: bundle.onDeferredDiagnostics,
 					signal: bundle.signal,
 				} as const);
-			const diagnostics = await runLspWritethrough(dst, content, cwd, resolvedOptions, signal, file, deferredInner);
+			const diagnostics = await runLspWritethrough(
+				dst,
+				content,
+				cwd,
+				resolvedOptions,
+				changeType,
+				signal,
+				file,
+				deferredInner,
+			);
 			bundle?.finalize(diagnostics);
 			return diagnostics;
 		}
 
 		const state = getOrCreateWritethroughBatch(batch.id, resolvedOptions);
-		state.entries.set(dst, { dst, content, file });
+		state.entries.set(dst, { dst, content, file, changeType });
 
 		if (!batch.flush) {
 			await writethroughNoop(dst, content, signal, file);

package/src/main.ts

@@ -806,11 +806,13 @@ async function buildSessionOptions(
 
 	// Auto-discover SYSTEM.md if no CLI system prompt provided
 	const systemPromptSource = parsed.systemPrompt ?? discoverSystemPromptFile();
-	const resolvedSystemPrompt = await resolvePromptInput(systemPromptSource, "system prompt");
 	const appendPromptSource = parsed.appendSystemPrompt ?? discoverAppendSystemPromptFile();
-	const resolvedAppendPrompt = await resolvePromptInput(appendPromptSource, "append system prompt");
 	const titleSystemPromptSource = discoverTitleSystemPromptFile();
-	const titleSystemPrompt = await resolvePromptInput(titleSystemPromptSource, "title system prompt");
+	const [resolvedSystemPrompt, resolvedAppendPrompt, titleSystemPrompt] = await Promise.all([
+		resolvePromptInput(systemPromptSource, "system prompt"),
+		resolvePromptInput(appendPromptSource, "append system prompt"),
+		resolvePromptInput(titleSystemPromptSource, "title system prompt"),
+	]);
 
 	if (sessionManager) {
 		options.sessionManager = sessionManager;

package/src/markit/converters/pdf/extract.ts

@@ -398,12 +398,13 @@ function extractSegmentsFromContentStream(raw: string, pageNumber: number): Segm
 
 /**
  * Fast tokenizer for PDF content streams.
- * Splits on whitespace, skipping comments and string literals.
+ * Splits on whitespace, skipping comments, string literals, and inline image payloads.
  */
 function tokenizeContentStream(raw: string): string[] {
 	const tokens: string[] = [];
 	const len = raw.length;
 	let i = 0;
+	let inInlineImage = false;
 	while (i < len) {
 		const ch = raw.charCodeAt(i);
 		// Skip whitespace
@@ -449,6 +450,12 @@ function tokenizeContentStream(raw: string): string[] {
 			i += 2;
 			continue;
 		}
+		// Skip stray closing delimiters from malformed streams. They cannot start
+		// a token, so leaving i unchanged would spin forever.
+		if (ch === 41 || ch === 62) {
+			i++;
+			continue;
+		}
 		// Regular token: read until whitespace or delimiter
 		const start = i;
 		while (i < len) {
@@ -457,7 +464,24 @@ function tokenizeContentStream(raw: string): string[] {
 			i++;
 		}
 		if (i > start) {
-			tokens.push(raw.substring(start, i));
+			const token = raw.substring(start, i);
+			tokens.push(token);
+			if (token === "BI") {
+				inInlineImage = true;
+			} else if (token === "ID" && inInlineImage) {
+				while (i < len && raw.charCodeAt(i) <= 32) i++;
+				while (i < len) {
+					const c = raw.charCodeAt(i);
+					const prev = i === 0 ? 32 : raw.charCodeAt(i - 1);
+					const next = i + 2 >= len ? 32 : raw.charCodeAt(i + 2);
+					if (c === 69 && raw.charCodeAt(i + 1) === 73 && prev <= 32 && next <= 32) {
+						i += 2;
+						break;
+					}
+					i++;
+				}
+				inInlineImage = false;
+			}
 		}
 	}
 	return tokens;

package/src/mnemopi/state.ts

@@ -114,8 +114,41 @@ export interface MnemopiMemoryEditResult {
 }
 
 interface MnemopiStoredMemoryRow {
+	id?: unknown;
+	content?: unknown;
+	source?: unknown;
+	timestamp?: unknown;
+	importance?: unknown;
+	veracity?: unknown;
+	created_at?: unknown;
 	memory_store?: unknown;
+	memory_type?: unknown;
 	session_id?: unknown;
+	metadata?: unknown;
+	metadata_json?: unknown;
+}
+
+/**
+ * Full-row lookup result produced by {@link MnemopiSessionState.getScopedMemory}.
+ * Mirrors the shape stored in mnemopi's working/episodic tables, tagged with
+ * the scoped bank that actually held the row so callers can render it with
+ * meaningful context.
+ */
+export interface MnemopiScopedMemoryHit {
+	bank: string;
+	store: "working" | "episodic";
+	row: {
+		id: string;
+		content: string;
+		source: string | null;
+		timestamp: string | null;
+		importance: number | null;
+		veracity: string | null;
+		created_at: string | null;
+		session_id: string | null;
+		memory_type: string | null;
+		metadata: unknown;
+	};
 }
 
 type MnemopiRetentionMessage = { role: string; content: string };
@@ -201,6 +234,49 @@ export class MnemopiSessionState {
 		return this.scoped.retain;
 	}
 
+	/**
+	 * Read counterpart to {@link editScopedMemory}: fetch a memory row by id
+	 * from any bank this session recalls from (retain, recall, global). First
+	 * hit wins in the same order {@link editScopedMemory} would touch, so the
+	 * shape matches what an `update`/`forget`/`invalidate` on the same id will
+	 * see. Returns `null` when the id is not found anywhere in scope.
+	 *
+	 * Backs the coding-agent `memory://<id>` URL so agents can inspect the
+	 * FULL content of a recall preview (recall clips content — see
+	 * {@link RecallResult.truncated}) before issuing a wholesale
+	 * `memory_edit update` that would otherwise overwrite unseen bytes
+	 * (issue #4443).
+	 */
+	getScopedMemory(id: string): MnemopiScopedMemoryHit | null {
+		const targets = dedupeScopedTargets([
+			this.scoped.retain,
+			...this.scoped.recall,
+			...(this.scoped.global ? [this.scoped.global] : []),
+		]);
+		for (const target of targets) {
+			const raw = target.memory.get(id) as MnemopiStoredMemoryRow | null;
+			if (!raw) continue;
+			const store: MnemopiScopedMemoryHit["store"] = raw.memory_store === "episodic" ? "episodic" : "working";
+			return {
+				bank: target.bank,
+				store,
+				row: {
+					id: typeof raw.id === "string" ? raw.id : id,
+					content: typeof raw.content === "string" ? raw.content : "",
+					source: typeof raw.source === "string" ? raw.source : null,
+					timestamp: typeof raw.timestamp === "string" ? raw.timestamp : null,
+					importance: typeof raw.importance === "number" ? raw.importance : null,
+					veracity: typeof raw.veracity === "string" ? raw.veracity : null,
+					created_at: typeof raw.created_at === "string" ? raw.created_at : null,
+					session_id: typeof raw.session_id === "string" ? raw.session_id : null,
+					memory_type: typeof raw.memory_type === "string" ? raw.memory_type : null,
+					metadata: raw.metadata ?? raw.metadata_json ?? null,
+				},
+			};
+		}
+		return null;
+	}
+
 	editScopedMemory(
 		op: MnemopiMemoryEditOperation,
 		id: string,

package/src/modes/acp/acp-agent.ts

@@ -1823,6 +1823,10 @@ export class AcpAgent implements Agent {
 			output: usage.output,
 			cacheRead: usage.cacheRead,
 			cacheWrite: usage.cacheWrite,
+			totalTokens: usage.totalTokens,
+			orchestrationInput: usage.orchestrationInput,
+			orchestrationOutput: usage.orchestrationOutput,
+			orchestrationCacheRead: usage.orchestrationCacheRead,
 			premiumRequests: usage.premiumRequests,
 			cost: usage.cost,
 		};
@@ -1833,7 +1837,7 @@ export class AcpAgent implements Agent {
 		const outputTokens = Math.max(0, current.output - previous.output);
 		const cachedReadTokens = Math.max(0, current.cacheRead - previous.cacheRead);
 		const cachedWriteTokens = Math.max(0, current.cacheWrite - previous.cacheWrite);
-		const totalTokens = inputTokens + outputTokens + cachedReadTokens + cachedWriteTokens;
+		const totalTokens = Math.max(0, current.totalTokens - previous.totalTokens);
 
 		if (totalTokens === 0) {
 			return undefined;

package/src/modes/components/agent-hub.ts

@@ -68,16 +68,23 @@ function statusBadge(status: AgentStatus): string {
 	}
 }
 
-function registerPersistedSubagents(registry: AgentRegistry, sessionFile: string | null | undefined): void {
+async function registerPersistedSubagents(
+	registry: AgentRegistry,
+	sessionFile: string | null | undefined,
+): Promise<void> {
 	if (!sessionFile?.endsWith(".jsonl")) return;
 	const root = sessionFile.slice(0, -6);
-	registerPersistedSubagentsFromDir(registry, root, undefined);
+	await registerPersistedSubagentsFromDir(registry, root, undefined);
 }
 
-function registerPersistedSubagentsFromDir(registry: AgentRegistry, dir: string, parentId: string | undefined): void {
+async function registerPersistedSubagentsFromDir(
+	registry: AgentRegistry,
+	dir: string,
+	parentId: string | undefined,
+): Promise<void> {
 	let entries: fs.Dirent[];
 	try {
-		entries = fs.readdirSync(dir, { withFileTypes: true });
+		entries = await fs.promises.readdir(dir, { withFileTypes: true });
 	} catch {
 		return;
 	}
@@ -126,7 +133,7 @@ function registerPersistedSubagentsFromDir(registry: AgentRegistry, dir: string,
 				status: "parked",
 			});
 		}
-		registerPersistedSubagentsFromDir(registry, path.join(dir, id), id);
+		await registerPersistedSubagentsFromDir(registry, path.join(dir, id), id);
 	}
 }
 
@@ -192,6 +199,8 @@ export class AgentHubOverlayComponent extends Container {
 	#unsubscribers: Array<() => void> = [];
 	#ageTimer: NodeJS.Timeout | undefined;
 	#remote: AgentHubRemote | undefined;
+	/** Resolves after persisted historical subagents have been registered and rows refreshed. */
+	readonly persistedSubagentsReady: Promise<void>;
 
 	// Table state
 	#rows: AgentRef[] = [];
@@ -247,14 +256,23 @@ export class AgentHubOverlayComponent extends Container {
 		this.#ageTimer = setInterval(() => this.#requestRender(), AGE_TICK_MS);
 		this.#ageTimer.unref?.();
 
-		if (!this.#remote) registerPersistedSubagents(this.#registry, deps.sessionFile);
+		this.persistedSubagentsReady = this.#remote
+			? Promise.resolve()
+			: registerPersistedSubagents(this.#registry, deps.sessionFile)
+					.catch((error: unknown) => {
+						logger.warn("Failed to register persisted subagents", { error });
+					})
+					.then(() => {
+						this.#refreshRows();
+					})
+					.finally(() => this.#requestRender());
 		this.#refreshRows();
 	}
 
 	/**
-	 * Whether the table view has no agents to show (every registered agent except
-	 * Main, after the persisted-subagent scan in the constructor). The double-←
-	 * gesture reads this to stay inert when there is nothing to open.
+	 * Whether the current table view has no agents to show (every registered agent
+	 * except Main). Persisted historical rows may arrive later; callers that need
+	 * those included must wait for {@link persistedSubagentsReady} first.
 	 */
 	get isEmpty(): boolean {
 		return this.#rows.length === 0;