pi-legion 3.0.3 → 4.0.0

package/src/extension/spawn-render.ts

@@ -0,0 +1,183 @@
+/**
+ * TUI renderer for the `subagent` / `vexillatio` tool results.
+ *
+ * Pi never renders a tool result's `details` on its own: `renderResult` is the
+ * only consumer, and a tool registered without one falls back to the plain
+ * `content` text. So the arbitrated `spawnMode` (#209) stays invisible until a
+ * renderer names it — that is all this file does.
+ *
+ * The summary line is derived from `details`, never from `content`: `content`
+ * is model-facing, `details` is TUI-facing (`docs/design.md:258`). Keeping the
+ * line out of `content` keeps it out of the LLM context.
+ *
+ * Renderers are called on every repaint, so nothing here may throw: the host
+ * swallows a throwing renderer and falls back to the default block, silently
+ * erasing the very fact this file exists to show. Every `details` read is
+ * therefore optional-chained and shape-checked, AND both entry points are
+ * wrapped in `try/catch`: a shape check is no defence against a getter or a
+ * Proxy trap that throws (host: `tool-execution.js` catch → fallback card).
+ */
+
+import { Text } from "@earendil-works/pi-tui";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
+
+/** How many `content` lines a collapsed card keeps before the expand hint. */
+const COLLAPSED_LINES = 10;
+
+const SPAWN_MODES = new Set(["rpc", "inprocess"]);
+
+/**
+ * Binary control bytes that must never reach the terminal renderer.
+ *
+ * Same set as the host fallback (`shell.js:sanitizeBinaryOutput`, used by
+ * `render-utils.js:getTextOutput`): TAB, LF and CR are excluded on purpose —
+ * the carriage return is a line break here, see {@link resultLines}.
+ */
+const BINARY_CONTROL = /[\x00-\x08\x0B\x0C\x0E-\x1F\uFFF9-\uFFFB]/g;
+
+export interface SpawnRenderOptions {
+	expanded: boolean;
+	isPartial: boolean;
+}
+
+function isSpawnMode(value: unknown): value is "rpc" | "inprocess" {
+	return typeof value === "string" && SPAWN_MODES.has(value);
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === "object" && value !== null
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+/** One `name=mode` entry from a `spawns[]` array (launch-family details). */
+function entryFromSpawn(value: unknown): string | undefined {
+	const spawn = asRecord(value);
+	if (!spawn) return undefined;
+	const name = spawn.name;
+	const mode = spawn.spawnMode;
+	if (typeof name !== "string" || !name) return undefined;
+	// An unknown/absent mode is skipped, never printed as a guess: a legacy
+	// handle must render as "no fact", not as `rpc`.
+	if (!isSpawnMode(mode)) return undefined;
+	return `${name}=${mode}`;
+}
+
+/** One `name=mode` entry from a `handles[]` object (vexillatio details). */
+function entryFromHandle(value: unknown): string | undefined {
+	const handle = asRecord(value);
+	if (!handle) return undefined;
+	return entryFromSpawn(handle);
+}
+
+/**
+ * `spawn: scout-0=inprocess` or `spawn: worker-0=rpc, scout-1=inprocess`.
+ *
+ * Reads both documented detail shapes defensively:
+ * - launch family: `details.spawns[]` (`{ name, agent, spawnMode }`)
+ * - vexillatio:    `details.handles[]` (`{ name, agent, sessionFile, spawnMode? }`)
+ *
+ * One entry per child, first occurrence wins: a result that carries the same
+ * handle in both arrays must not print `w=rpc, w=rpc`.
+ *
+ * Returns `undefined` when nothing survives — no details, wrong shape, or every
+ * entry's mode unknown. Unknown modes are omitted rather than defaulted.
+ *
+ * Never throws: a `details` object with a throwing getter (or a Proxy) would
+ * otherwise take the whole card down, because the host swallows renderer
+ * exceptions and paints its fallback instead.
+ */
+export function spawnModeSummary(details: unknown): string | undefined {
+	try {
+		const record = asRecord(details);
+		if (!record) return undefined;
+		const entries: string[] = [];
+		const seen = new Set<string>();
+		const push = (entry: string | undefined): void => {
+			if (!entry || seen.has(entry)) return;
+			seen.add(entry);
+			entries.push(entry);
+		};
+		const spawns = record.spawns;
+		if (Array.isArray(spawns)) {
+			for (const spawn of spawns) push(entryFromSpawn(spawn));
+		}
+		// `handles` may be a `string[]` (launch-family) or an object array
+		// (vexillatio); string entries simply never match, so both shapes pass.
+		const handles = record.handles;
+		if (Array.isArray(handles)) {
+			for (const handle of handles) push(entryFromHandle(handle));
+		}
+		if (entries.length === 0) return undefined;
+		return `spawn: ${entries.join(", ")}`;
+	} catch {
+		// A hostile/throwing getter is not a rendering failure: no fact, no line.
+		return undefined;
+	}
+}
+
+/**
+ * The model-facing text of a result, normalized the way it will be painted.
+ *
+ * Line counting has to happen on the text that actually renders, so
+ * normalizing runs BEFORE the split: a carriage return is how a progress
+ * stream redraws one line, not 20 rows — but `Text` treats `\r` as a line
+ * break, so leaving it in lets 20 segments paint 20 rows and bypass
+ * {@link COLLAPSED_LINES} with no hint. `\r` therefore becomes `\n` (so all
+ * 20 segments stay readable instead of being concatenated into one blob) and
+ * binary control bytes are dropped, matching the host fallback's intent
+ * (`render-utils.js:40` sanitizes binary output and removes raw `\r`).
+ */
+function resultLines(result: AgentToolResult<unknown> | undefined): string[] {
+	const content = result?.content;
+	if (!Array.isArray(content)) return [];
+	const text = content
+		.flatMap((part) => {
+			if (asRecord(part)?.type !== "text") return [];
+			const value = asRecord(part)?.text;
+			return typeof value === "string" ? [value] : [];
+		})
+		.join("\n");
+	const normalized = stripTerminalSequences(text)
+		.replace(/\r\n/g, "\n")
+		.replace(/\r/g, "\n")
+		.replace(BINARY_CONTROL, "");
+	return normalized.split("\n");
+}
+
+/**
+ * Build the card: the spawn summary line (when known) followed by the result
+ * text, capped at {@link COLLAPSED_LINES} lines until `ctrl+o` expands it.
+ *
+ * Never throws by design; see the file comment.
+ */
+export function renderSpawnResult(
+	result: AgentToolResult<unknown>,
+	opts: SpawnRenderOptions,
+	_theme: Theme,
+) {
+	const lines: string[] = [];
+	// Double insurance: `spawnModeSummary` is already total, but this call site
+	// must not depend on the callee's implementation staying that way (the host
+	// silences a throw and drops the card). The `details` READ is inside the
+	// guard too — a Proxy can throw on the property access itself.
+	let summary: string | undefined;
+	try {
+		summary = spawnModeSummary(result?.details);
+	} catch {
+		summary = undefined;
+	}
+	if (summary) lines.push(summary);
+	lines.push(...resultLines(result));
+	// `opts` is host-supplied; optional-chained so a partial/absent options
+	// object degrades to the collapsed view instead of throwing.
+	if (opts?.expanded || lines.length <= COLLAPSED_LINES) {
+		return new Text(lines.join("\n"), 0, 0);
+	}
+	const hidden = lines.length - COLLAPSED_LINES;
+	const visible = lines.slice(0, COLLAPSED_LINES);
+	visible.push(`... (${hidden} more lines, ctrl+o to expand)`);
+	return new Text(visible.join("\n"), 0, 0);
+}

package/src/extension/summary.ts

@@ -617,7 +617,7 @@ export function formatSubagentDetail(input: SummaryDetailInput): string {
 	if (child.thinking !== undefined) stateBits.push(`thinking: ${child.thinking}`);
 	const lines = [title, `  ${stateBits.join(" · ")}`];
 
-	const runBits = [`run: ${run.runId}`, `supervisor: ${run.herdr.supervisor ?? "legacy"}`];
+	const runBits = [`run: ${run.runId}`, `supervisor: ${run.herdr.supervisor ?? "unknown"}`];
 	lines.push(`  ${runBits.join(" · ")}`);
 
 	const startedAtMs = parseTimestamp(child.spawnedAt);

package/src/legion/db.ts

@@ -5,6 +5,24 @@ import { createRequire } from "node:module";
 export const LEGION_DB_USER_VERSION = 1;
 export const LEGION_DB_BUSY_TIMEOUT_MS = 5_000;
 
+/**
+ * Bound on one connection's compiled-statement cache.
+ *
+ * The ledger has ~29 distinct static SQL texts behind the 46 `prepare()` call
+ * sites (many sites share a text), plus a handful of dynamically-shaped
+ * families — `usage.ts`'s chunked `IN (?,?,…)` (stable chunk length at runtime)
+ * and `hygiene.ts`'s retention `NOT IN (…)` lists. 64 holds everything a
+ * connection reuses with 2x headroom, while an unbounded map keyed on SQL text
+ * would grow with every distinct chunk size ever requested.
+ */
+export const LEGION_STMT_CACHE_LIMIT = 64;
+
+/**
+ * `exec()` texts that can change the schema and therefore invalidate compiled
+ * statements. Deliberately matched anywhere in the text (see `attachStatementCache`).
+ */
+const SCHEMA_MUTATION_PATTERN = /\b(?:ALTER|CREATE|DROP|REINDEX|VACUUM)\b/i;
+
 export type SqliteBindValue = string | number | bigint | null | Uint8Array;
 export type SqliteRow = Record<string, string | number | bigint | null | Uint8Array>;
 
@@ -41,6 +59,7 @@ const SQLITE_DRIVERS: readonly SqliteDriver[] = [
 ];
 let cachedSqliteConstructor: SqliteDatabaseConstructor | null | undefined;
 const transactionDepth = new WeakMap<DatabaseSync, number>();
+const statementCaches = new WeakMap<DatabaseSync, Map<string, LegionStatementSync>>();
 let savepointSequence = 0;
 
 const SCHEMA_V1 = `
@@ -99,6 +118,10 @@ CREATE TABLE messages (
   created_at   INTEGER NOT NULL
 );
 CREATE INDEX idx_messages_inbox ON messages(to_node, delivered, id);
+-- Serves the per-sender rate-limit COUNT that sendMail runs inside its write
+-- transaction (mail.ts): without it that COUNT is a full SCAN of messages, which
+-- degrades monotonically because messages has no retention policy.
+CREATE INDEX idx_messages_rate ON messages(from_node, created_at);
 `;
 
 /**
@@ -109,6 +132,54 @@ export function sqliteHasRow(row: SqliteRow | null | undefined): boolean {
 	return row != null;
 }
 
+/**
+ * The journal mode the ledger must actually run in (contract §4.1).
+ */
+export const LEGION_DB_REQUIRED_JOURNAL_MODE = "wal";
+
+/**
+ * Refuse a connection whose journal mode is not the one the ledger assumes.
+ *
+ * `PRAGMA journal_mode = WAL` is a *query*: it returns the mode now in effect,
+ * and that mode need not be `wal` — SQLite is entitled to answer with the mode
+ * it settled on rather than to fail, which is how a connection ends up on a
+ * rollback journal while the caller believes WAL is live. (Mounts without
+ * working shared memory and read-only media are the usual causes; probing
+ * `node:sqlite` here, those conditions happened to raise instead, and a
+ * conflicting lock raised too — so the silent path is not something this
+ * repository can reproduce on demand, which is exactly why the check is a
+ * precondition on the returned value rather than a test fixture.)
+ *
+ * Every durability argument the ledger makes (single-writer serialisation,
+ * readers that never block the writer, the WAL checkpoint that
+ * `runStartupHygiene` performs on each ledger it sweeps at startup, and the one
+ * `stopLegionRuntime` folds in before close) assumes WAL is actually live, so
+ * the reported value is treated as a precondition rather than a best effort.
+ * Failing at `openLegionDb` surfaces it at startup instead of as data loss.
+ *
+ * `:memory:` is the one deliberate exemption: SQLite does not implement WAL for
+ * in-memory databases and reports `memory` forever, which is correct there
+ * because the database cannot outlive the process. `memoryDatabase` is what
+ * distinguishes that benign case from a *file* that reported `memory` (a real
+ * failure — it means no rollback journal and no WAL).
+ */
+export function assertLegionJournalMode(
+	mode: unknown,
+	memoryDatabase: boolean,
+	database: string = "legion.db",
+): void {
+	const observed = typeof mode === "string" ? mode : String(mode);
+	if (memoryDatabase && observed === "memory") return;
+	if (observed === LEGION_DB_REQUIRED_JOURNAL_MODE) return;
+	throw new Error(
+		`${database} is not in WAL mode: PRAGMA journal_mode = WAL reported "${observed}" ` +
+			`(expected "${LEGION_DB_REQUIRED_JOURNAL_MODE}"). WAL is a precondition of the ledger's ` +
+			"durability and reader/writer isolation, so this connection is refused rather than " +
+			"silently running on a rollback journal. A mount without working shared-memory " +
+			"support, or read-only media, is the usual cause.",
+	);
+}
+
 /** Resolve the tree ledger location specified by contract §4.1. */
 export function legionDbPath(rootRunDir: string): string {
 	if (typeof rootRunDir !== "string" || rootRunDir.trim().length === 0) {
@@ -120,6 +191,11 @@ export function legionDbPath(rootRunDir: string): string {
 /**
  * Open one supervisor's connection to the shared tree ledger. SQLite is loaded
  * lazily so importing the extension does not require a driver until v2 is used.
+ *
+ * The WAL switch is — unusually for a PRAGMA — a request, not a command, so its
+ * returned mode is verified rather than assumed; see
+ * {@link assertLegionJournalMode}. A file database that cannot reach `wal`
+ * throws here, at startup, instead of quietly running on a rollback journal.
  */
 export function openLegionDb(dbPath: string): DatabaseSync {
 	if (typeof dbPath !== "string" || dbPath.trim().length === 0) {
@@ -131,9 +207,13 @@ export function openLegionDb(dbPath: string): DatabaseSync {
 	const Database = sqliteDatabaseConstructor();
 	const db = new Database(dbPath);
 	try {
+		// Compiled statements are reused for every one of the call sites above.
+		attachStatementCache(db);
 		db.exec(`PRAGMA busy_timeout = ${LEGION_DB_BUSY_TIMEOUT_MS};`);
 		db.exec("PRAGMA foreign_keys = ON;");
-		db.exec("PRAGMA journal_mode = WAL;");
+		// One query both requests WAL and reports the mode that actually resulted.
+		const journalMode = db.prepare("PRAGMA journal_mode = WAL;").get()?.journal_mode;
+		assertLegionJournalMode(journalMode, isMemoryLegionDb(db), dbPath);
 		migrate(db);
 		return db;
 	} catch (error) {
@@ -142,6 +222,76 @@ export function openLegionDb(dbPath: string): DatabaseSync {
 	}
 }
 
+/**
+ * Serve every `prepare()` on this connection from a bounded per-connection LRU.
+ *
+ * The cache sits *inside* `prepare` rather than at the call sites: each call
+ * still enters the data layer (so instrumentation that counts
+ * `prepare(sql)` keeps counting), and all call sites get the reuse for free.
+ *
+ * Statements are keyed on the exact SQL text: two texts that differ only in
+ * whitespace are deliberately two entries, because SQL text is the only
+ * identity SQLite offers.
+ *
+ * Reuse is safe for data changes — `.get()`/`.all()`/`.run()` re-execute with
+ * the new bindings, so a cached statement always sees committed rows. It is NOT
+ * safe across a schema change: after `ALTER TABLE ... ADD COLUMN`, a cached
+ * `SELECT *` executed with `.all()` keeps reporting the schema it compiled
+ * against (`.get()` happens to refresh, which makes the hazard easy to miss).
+ * Any `exec()` whose text mentions a schema-mutating keyword therefore drops
+ * every cached statement, so the next `prepare()` recompiles against the new
+ * schema. That covers `migrate()`'s `SCHEMA_V1` (`CREATE TABLE/INDEX`),
+ * `hygiene.ts`'s `VACUUM`, and any future `ALTER`/`DROP`. `rebuild.ts` only
+ * issues `DELETE FROM`, which is a data change, so it needs no invalidation.
+ *
+ * Invalidation protects future `prepare()` calls; a handle the caller already
+ * holds stays live with the schema it compiled against, as it would without
+ * this cache.
+ */
+function attachStatementCache(db: DatabaseSync): void {
+	if (statementCaches.has(db)) return;
+	const prepare = db.prepare as (sql: string, ...rest: unknown[]) => LegionStatementSync;
+	const exec = db.exec as (sql: string, ...rest: unknown[]) => void;
+	const close = db.close as (...rest: unknown[]) => void;
+	const cache = new Map<string, LegionStatementSync>();
+	statementCaches.set(db, cache);
+	db.prepare = (sql: string, ...rest: unknown[]): LegionStatementSync => {
+		const cached = cache.get(sql);
+		if (cached) {
+			// Re-insert so Map order stays least-recently-used first.
+			cache.delete(sql);
+			cache.set(sql, cached);
+			return cached;
+		}
+		const statement = prepare.call(db, sql, ...rest);
+		cache.set(sql, statement);
+		if (cache.size > LEGION_STMT_CACHE_LIMIT) {
+			const oldest = cache.keys().next();
+			if (!oldest.done) cache.delete(oldest.value);
+		}
+		return statement;
+	};
+	db.exec = (sql: string, ...rest: unknown[]): void => {
+		// Match anywhere in the text: `exec` runs multi-statement SQL (SCHEMA_V1)
+		// and over-matching only costs a recompile, while under-matching would
+		// serve statements compiled against a schema that no longer exists.
+		if (SCHEMA_MUTATION_PATTERN.test(sql)) cache.clear();
+		exec.call(db, sql, ...rest);
+	};
+	db.close = (...rest: unknown[]): void => {
+		// Drop our references before the driver finalizes them, so the cache
+		// cannot outlive the connection and nothing is released twice.
+		cache.clear();
+		statementCaches.delete(db);
+		close.call(db, ...rest);
+	};
+}
+
+/** Compiled statements a connection currently holds; 0 once it is closed. */
+export function legionStatementCacheSize(db: DatabaseSync): number {
+	return statementCaches.get(db)?.size ?? 0;
+}
+
 /** Run a short synchronous write transaction. Nested ledger helpers use savepoints. */
 export function withTransaction<T>(db: DatabaseSync, run: () => T): T {
 	const depth = transactionDepth.get(db) ?? 0;
@@ -236,6 +386,20 @@ function sqliteDatabaseConstructor(): SqliteDatabaseConstructor {
 	throw new AggregateError(failures, "no supported synchronous SQLite driver is available");
 }
 
+/**
+ * True when this connection's `main` database lives in memory rather than on
+ * disk. `PRAGMA database_list` reports an empty `file` for `:memory:` and for
+ * the `file::memory:` URIs, and the resolved path for a real file — asking
+ * SQLite beats pattern-matching the path the caller passed, because the driver
+ * is what decides. A missing row means we cannot tell, so it is treated as a
+ * file: the WAL check then applies and the failure is loud rather than silent.
+ */
+function isMemoryLegionDb(db: DatabaseSync): boolean {
+	const row = db.prepare("PRAGMA database_list;").get();
+	if (row == null) return false;
+	return String(row.file ?? "").length === 0;
+}
+
 function readUserVersion(db: DatabaseSync): number {
 	const row = db.prepare("PRAGMA user_version;").get();
 	return Number(row?.user_version ?? 0);

package/src/legion/events.ts

@@ -7,6 +7,12 @@ export const LEGION_EVENT_TYPES = [
 	"node_retired",
 	"node_resumed",
 	"node_blocked",
+	/**
+	 * Written by hygiene's `markAbandoned` (#233). It was missing from this set
+	 * while both the writer and `RETAINED_EVENT_TYPES` already treated it as a
+	 * real event, so `mapEvent` threw on read and froze the db event cursor.
+	 */
+	"node_abandoned",
 	"phase_change",
 	"phase_timeout",
 	"mail_sent",
@@ -36,6 +42,13 @@ export interface ReadEventsOptions {
 	limit?: number;
 }
 
+export interface ReadEventRowsOptions {
+	nodeId?: string;
+	limit?: number;
+	/** Called for a row that cannot be decoded; the row is skipped, not thrown. */
+	onInvalidRow?: (error: unknown, rowId: number) => void;
+}
+
 export function appendEvent<T>(
 	db: DatabaseSync,
 	nodeId: string,
@@ -73,23 +86,28 @@ export function readEventsAfter(
 	cursor: number,
 	options: ReadEventsOptions = {},
 ): LegionEvent[] {
-	assertCursor(cursor);
-	const limit = options.limit ?? 1_000;
-	if (!Number.isSafeInteger(limit) || limit < 1) {
-		throw new TypeError("event limit must be a positive safe integer");
+	return selectEventRows(db, cursor, options).map(mapEvent);
+}
+
+/**
+ * Per-row tolerant read: an undecodable row is reported through `onInvalidRow` and
+ * skipped instead of throwing, so one poisoned row cannot stall an event consumer.
+ * `readEventsAfter` stays strict for callers that must fail loudly.
+ */
+export function readEventsAfterTolerant(
+	db: DatabaseSync,
+	cursor: number,
+	options: ReadEventRowsOptions = {},
+): LegionEvent[] {
+	const events: LegionEvent[] = [];
+	for (const row of selectEventRows(db, cursor, options)) {
+		try {
+			events.push(mapEvent(row));
+		} catch (error) {
+			options.onInvalidRow?.(error, Number(row.id));
+		}
 	}
-	const rows = options.nodeId
-		? db
-				.prepare(
-					"SELECT id, node_id, type, data, ts FROM events WHERE id > ? AND node_id = ? ORDER BY id LIMIT ?",
-				)
-				.all(cursor, options.nodeId, limit)
-		: db
-				.prepare(
-					"SELECT id, node_id, type, data, ts FROM events WHERE id > ? ORDER BY id LIMIT ?",
-				)
-				.all(cursor, limit);
-	return rows.map(mapEvent);
+	return events;
 }
 
 export function getEventById(db: DatabaseSync, id: number): LegionEvent | null {
@@ -102,6 +120,30 @@ export function getEventById(db: DatabaseSync, id: number): LegionEvent | null {
 	return row ? mapEvent(row) : null;
 }
 
+/**
+ * Highest persisted event id, or `0` for an empty log.
+ *
+ * #238: a caller that attaches to a ledger it did not just write uses this to
+ * seed `createDbEventSource`'s `cursor` at the current tail, so attach does not
+ * replay the whole history. The SQL deliberately does NOT begin with the
+ * `SELECT id, node_id, type, data, ts FROM events WHERE id > ?` prefix: the
+ * instrumented `DatabaseSync` doubles in `test/unit/legion-event-bus.test.ts`
+ * count event SELECTs by that exact prefix and assert exact counts, so a
+ * differently-shaped statement must stay outside that counter.
+ */
+export function maxEventId(db: DatabaseSync): number {
+	const value = Number(
+		db.prepare("SELECT COALESCE(MAX(id), 0) AS id FROM events").get()?.id ?? 0,
+	);
+	// Only two shapes can reach here: 0 (empty log) or a positive safe integer.
+	// The column is an INTEGER PRIMARY KEY, a non-numeric write is refused with
+	// "datatype mismatch", and `node:sqlite` refuses to return an id it cannot
+	// represent exactly as a JS number ("Value is too large to be represented as a
+	// JavaScript number"). So this is a narrowing, not a recovery path — and a seed
+	// of 0 is safe regardless, because it only means "no history to skip".
+	return Number.isSafeInteger(value) && value > 0 ? value : 0;
+}
+
 /** PRAGMA data_version changes only when another connection commits. */
 export function getDataVersion(db: DatabaseSync): number {
 	return Number(db.prepare("PRAGMA data_version;").get()?.data_version ?? 0);
@@ -143,6 +185,29 @@ function mapEvent(row: SqliteRow): LegionEvent {
 	};
 }
 
+function selectEventRows(
+	db: DatabaseSync,
+	cursor: number,
+	options: ReadEventsOptions,
+): SqliteRow[] {
+	assertCursor(cursor);
+	const limit = options.limit ?? 1_000;
+	if (!Number.isSafeInteger(limit) || limit < 1) {
+		throw new TypeError("event limit must be a positive safe integer");
+	}
+	return options.nodeId
+		? db
+				.prepare(
+					"SELECT id, node_id, type, data, ts FROM events WHERE id > ? AND node_id = ? ORDER BY id LIMIT ?",
+				)
+				.all(cursor, options.nodeId, limit)
+		: db
+				.prepare(
+					"SELECT id, node_id, type, data, ts FROM events WHERE id > ? ORDER BY id LIMIT ?",
+				)
+				.all(cursor, limit);
+}
+
 function assertCursor(cursor: number): void {
 	if (!Number.isSafeInteger(cursor) || cursor < 0) {
 		throw new TypeError("event cursor must be a non-negative safe integer");

package/src/legion/nodes.ts

@@ -366,12 +366,23 @@ export function updateNode(
 	return updated;
 }
 
+/**
+ * Touch only `updated_at` for a live child. Empty-patch heartbeats must not
+ * run the full `updateNode` CASE ladder or a `SELECT *` read-back — orphan
+ * detection / `staleNodeHours` only need the timestamp (#236 P1).
+ */
 export function heartbeatNode(
 	db: DatabaseSync,
 	id: string,
 	now: () => number = () => Date.now(),
-): LegionNode {
-	return updateNode(db, id, {}, now);
+): { id: string; updatedAt: number } {
+	const timestamp = now();
+	assertTimestamp(timestamp, "clock");
+	const result = db
+		.prepare("UPDATE nodes SET updated_at = ? WHERE id = ?")
+		.run(timestamp, id);
+	if (Number(result.changes) === 0) throw new Error(`node not found: ${id}`);
+	return { id, updatedAt: timestamp };
 }
 
 export function listNodesByStatus(

package/src/legion/rebuild.ts

@@ -305,6 +305,7 @@ function collectSources(
 		for (const child of run.children) {
 			try {
 				const childSource = sourceFromChild(currentId, child, file, run, clock);
+				if (!childSource) continue;
 				const nestedRun = runs.find((entry) => nodeIdFromPath(entry.run.path) === childSource.id);
 				if (nestedRun) {
 					childSource.runId = nestedRun.run.runId;
@@ -336,7 +337,12 @@ function sourceFromChild(
 	runFile: string,
 	parentRun: RunRecord,
 	clock: () => number,
-): NodeSource {
+): NodeSource | undefined {
+	// #266 D3/§4.4: a `queued` child was never started — it has no ledger row, no
+	// run directory and only a placeholder session path. Rebuilding it into the
+	// tree would invent a node (and a phantom leaf) for a launch that may still be
+	// waiting or may have been dropped with the previous process.
+	if (child.state === "queued") return undefined;
 	const slug = sanitizeNodeSlug(child.name);
 	const id = nodeIdForChild(parentId, slug);
 	let status: NodeSource["status"] = "settled";

package/src/legion/usage.ts

@@ -16,6 +16,13 @@ export interface UpsertUsageInput {
 	costUsd?: number;
 }
 
+/**
+ * Chunk size for `WHERE node_id IN (...)` in {@link attachUsageTotals}.
+ * Stays under the common `SQLITE_MAX_VARIABLE_NUMBER` of 999 (some builds use
+ * 32766); contract trees are far smaller, but `getSubtree` is unbounded.
+ */
+export const USAGE_IN_CHUNK = 500;
+
 export function upsertUsage(
 	db: DatabaseSync,
 	input: UpsertUsageInput,
@@ -61,23 +68,70 @@ export function usageTotalTokens(db: DatabaseSync, nodeId: string): number {
 	return usage ? usage.tokensIn + usage.tokensOut : 0;
 }
 
+/**
+ * Annotate a node snapshot with per-node usage totals (#235).
+ *
+ * Signature and output shape are unchanged from the previous N+1 path:
+ * - `root` is never annotated (even if a usage row exists)
+ * - `tokensTotal` / `tokensOut` appear only when strictly > 0
+ * - the input array / objects are not mutated
+ *
+ * Implementation: one (or chunked) `WHERE node_id IN (...)` query + Map lookup,
+ * instead of one `getUsage` prepare/execute per node.
+ */
 export function attachUsageTotals<T extends { id: string }>(
 	db: DatabaseSync,
 	nodes: T[],
 ): Array<T & { tokensTotal?: number; tokensOut?: number }> {
+	type Annotated = T & { tokensTotal?: number; tokensOut?: number };
+	if (nodes.length === 0) return [];
+
+	const ids: string[] = [];
+	const seen = new Set<string>();
+	for (const node of nodes) {
+		if (node.id === "root") continue;
+		assertNodeId(node.id);
+		if (seen.has(node.id)) continue;
+		seen.add(node.id);
+		ids.push(node.id);
+	}
+
+	const usageById = loadUsageByNodeIds(db, ids);
+
 	return nodes.map((node) => {
-		if (node.id === "root") return { ...node } as T & { tokensTotal?: number; tokensOut?: number };
-		const usage = getUsage(db, node.id);
-		if (!usage) return { ...node } as T & { tokensTotal?: number; tokensOut?: number };
+		if (node.id === "root") return { ...node } as Annotated;
+		const usage = usageById.get(node.id);
+		if (!usage) return { ...node } as Annotated;
 		const total = usage.tokensIn + usage.tokensOut;
 		return {
 			...node,
 			...(total > 0 ? { tokensTotal: total } : {}),
 			...(usage.tokensOut > 0 ? { tokensOut: usage.tokensOut } : {}),
-		} as T & { tokensTotal?: number; tokensOut?: number };
+		} as Annotated;
 	});
 }
 
+/** Batch-load usage rows for the given node ids (chunked for SQLite bind limits). */
+function loadUsageByNodeIds(db: DatabaseSync, ids: string[]): Map<string, UsageSnapshot> {
+	const usageById = new Map<string, UsageSnapshot>();
+	if (ids.length === 0) return usageById;
+
+	for (let i = 0; i < ids.length; i += USAGE_IN_CHUNK) {
+		const chunk = ids.slice(i, i + USAGE_IN_CHUNK);
+		const placeholders = chunk.map(() => "?").join(",");
+		const rows = db
+			.prepare(
+				`SELECT node_id, tokens_in, tokens_out, cost_usd, updated_at FROM usage WHERE node_id IN (${placeholders})`,
+			)
+			.all(...chunk);
+		for (const row of rows) {
+			const usage = mapUsage(row);
+			usageById.set(usage.nodeId, usage);
+		}
+	}
+	return usageById;
+}
+
 function mapUsage(row: SqliteRow): UsageSnapshot {
 	return {
 		nodeId: String(row.node_id),