@fitchmultz/pi-subagents 0.52.2 → 0.52.3

package/docs/performance.md

@@ -70,13 +70,18 @@ The final version loads that module only when a human opens `/agents`, then
 revalidates the current session owner. These small samples overlap the baseline
 ranges and do not establish a generalized speedup or latency guarantee.
 
-Interactive mains scan at most 50 unfinished or newly discovered metadata rows
-per second. Immutable launches and finished rows are cached; finished history
-does not consume the active refresh budget. Liveness is checked once per active
-conversation per scan, not for completed idle actors. The open watch polls at
-250 ms, reading at most 64 KiB plus a 4 KiB identity header and retaining 80 bounded
-display lines. Those are display limits, not truncation of the native journal.
-Children and print/RPC sessions do not install the watcher.
+Interactive mains process at most 50 unfinished or newly discovered metadata rows
+per scan. Immutable launches and finished rows are cached; finished history does
+not consume that budget. Liveness is checked once per active conversation per
+scan, not for completed idle actors. While work is live or rows are pending, a
+one-second interval schedules scans; relevant filesystem and native events can
+also trigger them.
+
+The open viewer indexes its native journal incrementally, reading at most 256 KiB
+per indexing refresh. Ordinary scheduled display updates are spaced by 250 ms.
+The viewer mounts up to 24 history cards and hydrates text in 32,768-code-point
+pages. These are display mechanics, not truncation of the native journal. Children
+and print/RPC sessions do not install the observer.
 
 ### TypeBox host-instance startup (#234)
 
@@ -186,6 +191,98 @@ an end-to-end model, TUI or fleet CPU speedup claim. The native `park-shells` te
 separately exercises repeated checks, witness death, missing and replaced
 publications, and continuation on official Pi and the maintained fork.
 
+### Resident child usage accounting
+
+A child records each run's usage from its native journal. A resident child now
+keeps the IDs and billing fields of the records it validated and parses only
+records appended after its previous LF boundary. A cold actor, a restored parked
+child and the parent's pending-accounting repair still parse from byte 0 once.
+
+On macOS arm64 with Node 24.22.1, a read-only replay over one real 152.5 MB child
+journal with 11 saved runs compared release 0.52.2 (`1a088c6`) with this change,
+using the same inherited baseline and terminal for each run. Both returned
+identical contributions (1,129 in total), matching every saved result. The fresh
+reader read 1,068,938,072 bytes across the 11 runs; one resident index read
+152,966,603 bytes. The replay assumes one actor stayed resident for every run; a
+restart or restore between runs pays one full read. No latency change is claimed.
+
+The native `usage` test runs a second continuation in the resident actor on
+official Pi and the maintained fork. It read 773 bytes of a 41,605-byte official
+journal and 773 bytes of a 42,439-byte fork journal. Release 0.52.2 read the whole
+journal from byte 0 in the same test on both hosts.
+
+### Host SDK reuse on first delegation
+
+In a production-only install, Pi's loader gives the extension the running host's
+SDK. The extension now keeps that module when its factory runs. The SDK adapter
+returns it for the selected Pi package when the module's `getPackageDir()` resolves
+to that package and `PI_PACKAGE_DIR` is unset. The first delegation, `/agents` and
+parked-history restore therefore no longer import a second, unbundled copy of the
+same SDK from disk. Before, each parent process paid that load once, and later
+calls reused the second copy. The adapter still imports the selected package's
+`dist/index.js` everywhere else. That covers a set `PI_PACKAGE_DIR`, which replaces
+every copy's `getPackageDir()` answer, and a package-local SDK copy, such as a full
+development install or one removed by a later refresh. Detached children also keep
+the import.
+
+On macOS arm64 with Node v24.22.1, five alternating before/after pairs per host
+and scenario ran the real bundled print-mode CLI. The package was installed through
+`settings.packages` in a private HOME and agent directory. Each run used offline
+mode, disabled telemetry, `PI_TIMING=1` and a local faux provider, with no network
+or paid model calls. The hosts were the maintained fork at `581b5c18` (bundled CLI
+SHA-256 `f3960fd2e951ac0a47725af534f55b28122553aa56d143ad546dace094fc1d77`) and
+official Pi 1.4.0 (`e79626f2dd6f94aa45d30f3fa63cd84319a6eefcd150b353cfaf274366926774`).
+Before was the packed 0.52.2 tree at `1a088c6`; after was the same tree plus this
+change. The machine was busy, with load averages of 17–39 at the start and end of
+each set, so ranges are wide.
+
+| Metric (median; observed range)     | Fork before         | Fork after          | Official before     | Official after      |
+| ----------------------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
+| First `delegate` call, ms           | 1410 (672–1682)     | 115 (93–176)        | 1874 (796–6190)     | 104 (48–2339)       |
+| Parent RSS growth in that call, MiB | 66.3 (62.6–67.5)    | 0.4 (0.4–0.5)       | 84.5 (83.5–85.5)    | 0.4 (0.4–0.5)       |
+| `/agents` viewer module load, ms    | 361 (345–439)       | 35 (27–37)          | 523 (510–583)       | 28 (25–30)          |
+| RSS growth in that load, MiB        | 65.5 (65.2–66.0)    | 1.9 (1.5–2.3)       | 82.8 (82.4–84.5)    | 4.5 (4.3–5.2)       |
+| Extension import, `PI_TIMING`, ms   | 370 (217–465)       | 395 (88–556)        | 94 (75–193)         | 100 (85–143)        |
+| RSS at `session_start`, MiB         | 162.5 (145.6–170.4) | 163.3 (153.4–170.2) | 170.2 (169.7–171.2) | 171.4 (168.9–173.0) |
+
+The `delegate` time runs from the parent's tool start to its receipt; RSS growth is
+the parent's `process.memoryUsage().rss` difference across the same window. The
+table combines the startup and `/agents` sets of one campaign (40 runs) with the
+delegate set of a later campaign (20 runs). That delegate harness held the parent's
+turn until Pi's once-per-second completion scan could deliver the child's notice.
+All 60 runs exited 0 with zero errors. Every child finished, its completion resumed
+the parent, and every `/agents` load returned the viewer.
+
+Two earlier delegate sets did not hold the parent's turn, so the print run could end
+before that scan. That happened to one official run with the change in each set. The
+first harness counted it as an error without recording which check failed; its child
+finished. In the second, the completion did not resume the parent before exit. Their
+delegate timings remain valid because the window ends at the receipt. The second set
+gave medians of 554 to 46 ms on the fork and 1735 to 98 ms on official Pi, with the
+same memory pattern. Across it and the table's set, the change was faster in all 10
+fork pairs and in 9 of 10 official pairs. In the exception, during a load spike, the
+after run took 2339 ms against 1874 ms before. Official latency is therefore noisy,
+and its magnitude is inconclusive under this load; the memory result held in every
+pair. Child startup time and RSS showed no consistent change, because children keep
+the absolute import. Startup showed no measurable difference: Jiti's debug log lists
+the same native, transpiled and virtual loads, plus one more lookup in its existing
+virtual SDK table.
+
+A CPU profile of one fork pair splits the 678 ms before window into Node internals
+(336 ms), native work without a script location (203 ms) and second-copy package code
+(115 ms). Node's module-loading code accounts for 251 ms of those internals, led by
+source-text module compilation (109 ms). File opens, stats, reads and closes account
+for 152 ms of the native work. The 93 ms after window contains no second-copy code.
+Single fallback probes still imported from disk with `PI_PACKAGE_DIR` set (69 MiB
+growth during delegation). With a full development install under the fork host, they
+loaded the exact fork package (55 MiB), not the checkout's official copy.
+
+The package smoke's bundled RPC CLI checks both production-only layouts. There, the
+adapter must return the host's `SessionManager`, the class delegation uses to create
+the child session. The baseline adapter returned a separate class on both hosts. This
+is a first-call and memory measurement on one machine. It is not a cold-cache,
+interactive TUI, model-latency or fleet claim.
+
 ## Necessary costs
 
 - Native Pi owns context loading and model execution. The extension cannot remove

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.52.2",
+  "version": "0.52.3",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",

package/scripts/native-package-smoke.mjs

@@ -416,7 +416,9 @@ try {
 import { writeFileSync } from "node:fs";
 import { Type } from "typebox";
 import { Assert } from "typebox/value";
+import * as PiSDK from "@earendil-works/pi-coding-agent";
 import { Type as AgentType, Assert as AgentAssert } from ${JSON.stringify(pathToFileURL(join(packageRoot, "dist/agent/typebox.js")).href)};
+import { loadSDK, packageRoot as selectedRoot } from ${JSON.stringify(pathToFileURL(join(packageRoot, "dist/agent/host.js")).href)};
 export default function(pi) {
   // Native development graphs can resolve local peers before Jiti runs.
   // Production-only installs must instead reuse the bundled host's virtual modules.
@@ -424,8 +426,11 @@ export default function(pi) {
     assert.equal(AgentType, Type, "extension schemas reuse Pi's TypeBox instance");
     assert.equal(AgentAssert, Assert, "extension validation reuses Pi's TypeBox instance");
   }
-  pi.on("session_start", (_event, ctx) => {
-    writeFileSync(${JSON.stringify(marker)}, JSON.stringify(pi.getActiveTools()));
+  pi.on("session_start", async (_event, ctx) => {
+    // Delegation, /agents and parked history load the SDK through this adapter. Jiti wraps
+    // each importer's namespace, so compare the session class delegation constructs.
+    const sdkReused = (await loadSDK(selectedRoot())).SessionManager === PiSDK.SessionManager;
+    writeFileSync(${JSON.stringify(marker)}, JSON.stringify({ tools: pi.getActiveTools(), sdkReused }));
     ctx.shutdown();
   });
 }`,
@@ -468,7 +473,11 @@ export default function(pi) {
       "",
     );
     assert.doesNotMatch(output, /Failed to load extension|ERR_INTERNAL_ASSERTION|Extension error/);
-    assert.deepEqual(JSON.parse(readFileSync(marker, "utf8")).sort(), expectedTools);
+    const cli = JSON.parse(readFileSync(marker, "utf8"));
+    assert.deepEqual(cli.tools.sort(), expectedTools);
+    if (!existsSync(join(packageRoot, "node_modules/@earendil-works/pi-coding-agent"))) {
+      assert.equal(cli.sdkReused, true, "production-only installs reuse Pi's loaded SDK");
+    }
   } finally {
     await cliProcesses.stop();
   }

package/src/agent/child-runtime.ts

@@ -15,13 +15,11 @@ function guard(pi: ExtensionAPI, directory: string, token: string): void {
     if (event.toolName === "delegate" || event.toolName === "agent_runs") {
       return { block: true, reason: "Only a main session may delegate or control children." };
     }
+    if (event.toolName !== "bash" || typeof event.input.command !== "string") {
+      return;
+    }
     const owner = pi.getAllTools().find((tool) => tool.name === "bash")?.sourceInfo;
-    if (
-      event.toolName === "bash" &&
-      typeof event.input.command === "string" &&
-      owner &&
-      (owner.source === "builtin" || localCwdOwner(owner))
-    ) {
+    if (owner && (owner.source === "builtin" || localCwdOwner(owner))) {
       // Preserve the selected local owner's cwd/env and leave remote/custom tools alone.
       const input = event.input;
       input.command = shellCommand(event.input.command, directory, token);

package/src/agent/host.ts

@@ -85,7 +85,22 @@ export function packageRoot(): string {
   }
   return path.dirname(manifest);
 }
+// Pi's resolution of this extension's SDK import: the running host in production installs,
+// possibly a package-local copy in development checkouts.
+let resolvedSDK: HostSDK | undefined;
+export function rememberSDK(sdk: HostSDK): void {
+  resolvedSDK = sdk;
+}
 export async function loadSDK(root: string): Promise<HostSDK> {
+  // Reuse it only as the selected root. PI_PACKAGE_DIR replaces getPackageDir()'s own
+  // location, so only an unset override proves that identity.
+  if (
+    resolvedSDK !== undefined &&
+    (process.env.PI_PACKAGE_DIR ?? "") === "" &&
+    fs.realpathSync(resolvedSDK.getPackageDir()) === fs.realpathSync(root)
+  ) {
+    return resolvedSDK;
+  }
   // Selected host SDK, not a second package-local runtime hidden behind Jiti aliases.
   // oxlint-disable-next-line typescript/no-unsafe-assignment
   const sdk: HostSDK = await import(pathToFileURL(path.join(root, "dist/index.js")).href);

package/src/agent/index.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
+import * as loadedSDK from "@earendil-works/pi-coding-agent";
 import type {
   ExtensionAPI,
   ExtensionContext,
@@ -16,7 +17,7 @@ import {
   signalProcess,
   stopChildren,
 } from "./process.ts";
-import { isChild, errorText } from "./host.ts";
+import { isChild, errorText, rememberSDK } from "./host.ts";
 import { serveParked } from "./parking.ts";
 import {
   resultSchema,
@@ -509,5 +510,7 @@ class AgentRuntime {
   }
 }
 export default function agents(pi: ExtensionAPI): void {
+  // Delegation, /agents and parked history then avoid importing a second SDK graph.
+  rememberSDK(loadedSDK);
   new AgentRuntime(pi).register();
 }

package/src/agent/observe-card.ts

@@ -188,7 +188,7 @@ export class Card implements Component {
     if (this.arguments !== value.args) {
       this.tool.updateArgs(projected(value.args) ?? {});
       this.arguments = value.args;
-      this.invalidate();
+      this.cache = undefined;
     }
   }
   updateTool(value: ViewedTool, options: CardOptions, preparing: boolean): void {
@@ -207,7 +207,7 @@ export class Card implements Component {
       this.phase = phase;
       this.value = source.result;
       this.ended = ended;
-      this.invalidate();
+      this.cache = undefined;
     }
   }
   private preview(value: unknown, isError: boolean, partial: boolean): void {
@@ -245,7 +245,7 @@ export class Card implements Component {
     this.status?.setText(message.ended ? "Awaiting journal publication" : "In progress");
     this.blocks = message.blocks.slice();
     this.ended = message.ended;
-    this.invalidate();
+    this.cache = undefined;
   }
   invalidate(): void {
     this.cache = undefined;

package/src/agent/observe.ts

@@ -21,6 +21,7 @@ import type { ObserverRow } from "./observe-chrome.ts";
 const STATUS_KEY = "agent-observer";
 type Roots = Map<string, ReturnType<typeof actor>>;
 type Commit = (live: ReadonlyMap<string, boolean>) => void;
+type WidgetSnapshot = { status: string; rows: readonly ObserverRow[]; more: number; error: string };
 
 class Observer {
   private ctx?: ExtensionContext;
@@ -36,7 +37,7 @@ class Observer {
   private watcher?: fs.FSWatcher;
   private widgetVisible = false;
   private widgetSignature = "";
-  private widgetRender?: () => void;
+  private widgetRender?: (snapshot: WidgetSnapshot) => void;
   private readonly launches = new Map<string, Launch>();
   private readonly finished = new Set<string>();
   private pending: string[] = [];
@@ -185,6 +186,7 @@ class Observer {
     const scanning = this.update()
       .catch((error: unknown) => {
         this.error = plainText(errorText(error));
+        this.widget();
       })
       .finally(() => {
         if (this.scanning !== scanning) {
@@ -278,23 +280,24 @@ class Observer {
       this.widgetSignature = "";
       return;
     }
-    const signature = JSON.stringify([this.status(), rows.slice(0, 4), rows.length]);
+    const visible = rows.slice(0, 4);
+    const more = rows.length - visible.length;
+    const snapshot = { status: this.status(), rows: visible, more, error: this.error };
+    const signature = JSON.stringify(snapshot);
     if (signature === this.widgetSignature) {
       return;
     }
     this.widgetSignature = signature;
     if (this.widgetVisible) {
-      this.widgetRender?.();
+      this.widgetRender?.(snapshot);
       return;
     }
     this.widgetVisible = true;
     ctx.ui.setWidget(
       STATUS_KEY,
       (tui, theme) => {
-        this.widgetRender = () => {
-          tui.requestRender();
-        };
         const content = new Container();
+        let shown: WidgetSnapshot = snapshot;
         const open = (id: string) => {
           if (ctx !== this.ctx) {
             return;
@@ -303,39 +306,38 @@ class Observer {
             ctx.ui.notify(errorText(error), "error");
           });
         };
+        const build = () => {
+          content.clear();
+          content.addChild(actionText(theme.fg("accent", shown.status), () => open("")));
+          for (const row of shown.rows) {
+            const glyph = row.live ? "●" : "○";
+            const color = row.live ? "accent" : "warning";
+            content.addChild(
+              actionText(
+                `${theme.fg(color, glyph)} ${theme.bold(row.name)} · ${row.activity ?? row.status}`,
+                () => open(row.id),
+              ),
+            );
+          }
+          if (shown.more > 0) {
+            content.addChild(
+              actionText(theme.fg("dim", `+${shown.more} more · /agents`), () => open("")),
+            );
+          }
+          if (shown.error.length > 0) {
+            content.addChild(new TruncatedText(theme.fg("warning", shown.error), 0, 0));
+          }
+        };
+        build();
+        this.widgetRender = (next) => {
+          shown = next;
+          build();
+          tui.requestRender();
+        };
         return {
-          render: (width) => {
-            const strip = this.strip();
-            const visible = strip.slice(0, 4);
-            content.clear();
-            content.addChild(actionText(theme.fg("accent", this.status()), () => open("")));
-            for (const row of visible) {
-              const glyph = row.live ? "●" : "○";
-              const color = row.live ? "accent" : "warning";
-              content.addChild(
-                actionText(
-                  `${theme.fg(color, glyph)} ${theme.bold(row.name)} · ${row.activity ?? row.status}`,
-                  () => open(row.id),
-                ),
-              );
-            }
-            if (strip.length > visible.length) {
-              content.addChild(
-                actionText(
-                  theme.fg("dim", `+${strip.length - visible.length} more · /agents`),
-                  () => open(""),
-                ),
-              );
-            }
-            if (this.error.length > 0) {
-              content.addChild(new TruncatedText(theme.fg("warning", this.error), 0, 0));
-            }
-            return content.render(width);
-          },
+          render: (width) => content.render(width),
           handleMouse: (event) => content.handleMouse(event),
-          invalidate: () => {
-            // Render reads current rows, expansion and theme on every frame.
-          },
+          invalidate: build,
         };
       },
       { placement: "aboveEditor" },

package/src/agent/parking.ts

@@ -85,8 +85,20 @@ async function cut(
   return undefined;
 }
 const PARK_AFTER_MS = 5 * 60_000;
-const digest = (file: string): string =>
-  createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+/** SHA-256 of every state byte through one reused chunk, like the native state reader. */
+function digest(file: string): string {
+  const hash = createHash("sha256");
+  const fd = fs.openSync(file, "r");
+  try {
+    const chunk = Buffer.allocUnsafe(64 * 1024);
+    for (let count = fs.readSync(fd, chunk); count > 0; count = fs.readSync(fd, chunk)) {
+      hash.update(chunk.subarray(0, count));
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return hash.digest("hex");
+}
 
 /** Parked authority names this session and exactly the saved generation's state bytes. */
 function exact(

package/src/agent/runner.ts

@@ -7,7 +7,7 @@ import { launchAt, missing, read, runDirectory, write } from "./storage.ts";
 import { ownIdentity, ParentCheck, shells, signalProcess } from "./process.ts";
 import { errorText, loadSDK } from "./host.ts";
 import { Parking, type Runtime } from "./parking.ts";
-import { childUsage } from "./usage.ts";
+import { UsageIndex } from "./usage.ts";
 import { initializeCwd } from "./cwd.ts";
 import { childRuntime } from "./child-runtime.ts";
 import { ActorObservation, type ObservationStats } from "./observation.ts";
@@ -53,6 +53,8 @@ class Actor {
   private readonly started = new Set<string>();
   // Actor-local validation metadata only; never retain command prompts or receipt authority.
   private readonly validated = new Map<string, { identity: string; id: string }>();
+  // Every run of this conversation shares one native journal; later runs read only its suffix.
+  private readonly accounting = new UsageIndex();
   private session?: AgentSession;
   private observation?: ActorObservation;
   private context?: { pi: ExtensionAPI; ctx: ExtensionContext };
@@ -111,7 +113,7 @@ class Actor {
     terminal?: string,
   ): Pick<Result, "contributions" | "accountingError" | "accountingPending"> {
     try {
-      return { contributions: childUsage(launch, baseline, terminal) };
+      return { contributions: this.accounting.read(launch, baseline, terminal) };
     } catch (error) {
       return {
         accountingError: errorText(error),

package/src/agent/usage.ts

@@ -1,9 +1,9 @@
 import * as path from "node:path";
 import * as fs from "node:fs";
-import { journalStamp } from "../shared/native-journal.ts";
+import { journalStamp, nativeAppend } from "../shared/native-journal.ts";
 import { nativeProjection } from "../shared/journal-projections.ts";
 import { scanJournal } from "../shared/journal-frames.ts";
-import { isRecord } from "../shared/unknown.ts";
+import { isRecord, type UnknownRecord } from "../shared/unknown.ts";
 import { Assert } from "./typebox.ts";
 import {
   contributionsSchema,
@@ -14,7 +14,8 @@ import {
 } from "./contracts.ts";
 import { read, runDirectory, write } from "./storage.ts";
 
-function billing(entry: Record<string, unknown>) {
+/** Billing evidence of one native entry. Missing required usage is an error only outside a baseline. */
+function billing(entry: UnknownRecord): UnknownRecord | "missing" | undefined {
   if (entry.checkpoint === true) {
     return;
   }
@@ -25,13 +26,13 @@ function billing(entry: Record<string, unknown>) {
   ) {
     return;
   }
-  const required = entry.type === "usage" || message.role === "assistant";
-  if (required && message.usage === undefined) {
-    throw new Error("Required native usage is unavailable.");
+  if (message.usage === undefined) {
+    return entry.type === "usage" || message.role === "assistant" ? "missing" : undefined;
   }
-  return message.usage === undefined ? undefined : message;
+  const { role, provider, model, responseModel, usage } = message;
+  return { role, provider, model, responseModel, usage };
 }
-function attribution(message: Record<string, unknown>, launch: Launch) {
+function attribution(message: UnknownRecord, launch: Launch) {
   if (message.role === "toolResult") {
     return { provider: launch.provider, model: launch.model };
   }
@@ -44,63 +45,118 @@ function attribution(message: Record<string, unknown>, launch: Launch) {
     model: typeof model === "string" ? model : launch.model,
   };
 }
-export function childUsage(
-  launch: Launch,
-  baseline: ReadonlySet<string>,
-  terminal?: string,
-): Contribution[] {
-  const values: unknown[] = [];
-  const observed = { header: false, ended: false };
-  const reachedTerminal = new Error("Native terminal boundary reached.");
-  const fd = fs.openSync(launch.sessionFile, "r");
-  try {
-    const stamp = journalStamp(fs.fstatSync(fd, { bigint: true }));
+interface Entry {
+  readonly id: string;
+  readonly billing: UnknownRecord | "missing" | undefined;
+}
+/** Accounting metadata of the validated LF-published journal records before `end`. */
+interface Prefix {
+  stat: fs.BigIntStats;
+  end: number;
+  header?: UnknownRecord;
+  readonly entries: Entry[];
+}
+function identify(header: UnknownRecord, launch: Launch): void {
+  if (header.type !== "session" || header.id !== launch.sessionId) {
+    throw new Error("Foreign native usage journal identity.");
+  }
+}
+/** An unchanged or native v3 appended journal keeps its prefix; any other change rebuilds it. */
+function reusable(cached: Prefix | undefined, stat: fs.BigIntStats): Prefix {
+  return cached !== undefined &&
+    (journalStamp(cached.stat) === journalStamp(stat) ||
+      nativeAppend(cached.stat, stat, cached.header))
+    ? cached
+    : { stat, end: 0, entries: [] };
+}
+/**
+ * Child usage of one physical native journal. A retained index parses only records after its last
+ * accepted LF boundary. Baselines, required usage and attribution apply to each read.
+ */
+export class UsageIndex {
+  private prefix?: Prefix;
+  read(launch: Launch, baseline: ReadonlySet<string>, terminal?: string): Contribution[] {
+    const values: unknown[] = [];
+    const reachedTerminal = new Error("Native terminal boundary reached.");
+    const charge = (entry: Entry): void => {
+      const billed = baseline.has(entry.id) ? undefined : entry.billing;
+      if (billed === "missing") {
+        throw new Error("Required native usage is unavailable.");
+      }
+      if (billed !== undefined) {
+        values.push({
+          id: `${launch.sessionId}:${entry.id}`,
+          ...attribution(billed, launch),
+          usage: billed.usage,
+        });
+      }
+      if (entry.id === terminal) {
+        throw reachedTerminal;
+      }
+    };
+    const cached = this.prefix;
+    // Only a completed read is retained.
+    this.prefix = undefined;
+    const fd = fs.openSync(launch.sessionFile, "r");
     try {
-      scanJournal(
-        fd,
-        nativeProjection,
-        ({ value }) => {
-          if (!observed.header) {
-            if (value.type !== "session" || value.id !== launch.sessionId) {
-              throw new Error("Foreign native usage journal identity.");
+      const stat = fs.fstatSync(fd, { bigint: true });
+      const prefix = reusable(cached, stat);
+      let ended = false;
+      try {
+        if (prefix.header !== undefined) {
+          identify(prefix.header, launch);
+        }
+        for (const entry of prefix.entries) {
+          charge(entry);
+        }
+        scanJournal(
+          fd,
+          nativeProjection,
+          ({ value, end }) => {
+            if (prefix.header === undefined) {
+              identify(value, launch);
+              prefix.header = value;
+              prefix.end = end;
+              return;
+            }
+            if (typeof value.id !== "string" || typeof value.type !== "string") {
+              throw new Error("Missing native usage entry identity.");
             }
-            observed.header = true;
-            return;
-          }
-          if (typeof value.id !== "string" || typeof value.type !== "string") {
-            throw new Error("Missing native usage entry identity.");
-          }
-          const message = baseline.has(value.id) ? undefined : billing(value);
-          if (message) {
-            values.push({
-              id: `${launch.sessionId}:${value.id}`,
-              ...attribution(message, launch),
-              usage: message.usage,
-            });
-          }
-          if (value.id === terminal) {
-            observed.ended = true;
-            throw reachedTerminal;
-          }
-        },
-        { policy: "live", requireNewline: true },
-      );
-    } catch (error) {
-      if (error !== reachedTerminal) {
-        throw error;
+            const entry = { id: value.id, billing: billing(value) };
+            prefix.entries.push(entry);
+            prefix.end = end;
+            charge(entry);
+          },
+          { policy: "live", requireNewline: true, start: prefix.end },
+        );
+      } catch (error) {
+        if (error !== reachedTerminal) {
+          throw error;
+        }
+        ended = true;
       }
+      if (journalStamp(fs.fstatSync(fd, { bigint: true })) !== journalStamp(stat)) {
+        throw new Error("Native usage journal changed while reading.");
+      }
+      if (prefix.header === undefined || (terminal !== undefined && !ended)) {
+        throw new Error("Native terminal or session identity is not LF-published.");
+      }
+      Assert(contributionsSchema, values);
+      prefix.stat = stat;
+      this.prefix = prefix;
+      return values;
+    } finally {
+      fs.closeSync(fd);
     }
-    if (journalStamp(fs.fstatSync(fd, { bigint: true })) !== stamp) {
-      throw new Error("Native usage journal changed while reading.");
-    }
-  } finally {
-    fs.closeSync(fd);
-  }
-  if (!observed.header || (terminal !== undefined && !observed.ended)) {
-    throw new Error("Native terminal or session identity is not LF-published.");
   }
-  Assert(contributionsSchema, values);
-  return values;
+}
+/** A fresh read for callers without an owner lifetime. */
+export function childUsage(
+  launch: Launch,
+  baseline: ReadonlySet<string>,
+  terminal?: string,
+): Contribution[] {
+  return new UsageIndex().read(launch, baseline, terminal);
 }
 export function readCanonicalResult(base: string, launch: Launch): Result | undefined {
   const file = path.join(runDirectory(base, launch.id), "result.json");