pi-daddy 0.43.0 → 0.44.0

package/native/provenance.json

@@ -0,0 +1,42 @@
+{
+  "revision": 1,
+  "toolchain": {
+    "version": "0.14.1",
+    "url": "https://ziglang.org/download/0.14.1/zig-x86_64-linux-0.14.1.tar.xz",
+    "sha256": "24aeeec8af16c381934a6cd7d95c807a8cb2cf7df9fa40d359aa884195c4716c",
+    "directory": "zig-x86_64-linux-0.14.1",
+    "target": "x86_64-linux-musl",
+    "flags": [
+      "-std=c11",
+      "-Wall",
+      "-Wextra",
+      "-Werror",
+      "-O2",
+      "-static",
+      "-s",
+      "-fno-ident",
+      "-Wl,--build-id=none"
+    ]
+  },
+  "source": {
+    "path": "native/worker.c",
+    "sha256": "205bacc28f9011c0603fdb95e930e901ba5dbff6f6170cd2adfd39d8ec5c2d6d"
+  },
+  "artifact": {
+    "path": "native/linux-x64/worker",
+    "sha256": "981a45591b1de790501ef531f6b0ccc8299b1e9a2d08a7970ccaeeecb9868798",
+    "bytes": 56360
+  },
+  "licenses": [
+    {
+      "path": "THIRD_PARTY_LICENSES/musl-COPYRIGHT.txt",
+      "sha256": "f9bc4423732350eb0b3f7ed7e91d530298476f8fec0c6c427a1c04ade22655af",
+      "source": "lib/libc/musl/COPYRIGHT"
+    },
+    {
+      "path": "THIRD_PARTY_LICENSES/zig-MIT.txt",
+      "sha256": "5c537d6853e005298a285d508cff9ac7192cea23576c840d485b2b586a7ff177",
+      "source": "LICENSE"
+    }
+  ]
+}

package/native/toolchain.json

@@ -0,0 +1,18 @@
+{
+  "version": "0.14.1",
+  "url": "https://ziglang.org/download/0.14.1/zig-x86_64-linux-0.14.1.tar.xz",
+  "sha256": "24aeeec8af16c381934a6cd7d95c807a8cb2cf7df9fa40d359aa884195c4716c",
+  "directory": "zig-x86_64-linux-0.14.1",
+  "target": "x86_64-linux-musl",
+  "flags": [
+    "-std=c11",
+    "-Wall",
+    "-Wextra",
+    "-Werror",
+    "-O2",
+    "-static",
+    "-s",
+    "-fno-ident",
+    "-Wl,--build-id=none"
+  ]
+}

package/native/worker.c

@@ -0,0 +1,209 @@
+/* Trusted-development Linux worker owner. Built and packaged; never compiled at runtime.
+ * Direct children stay waitable until this single-threaded helper reaps them, preventing PID reuse
+ * between children-list observation and pidfd_open. Detached descendants are adopted by subreaper.
+ * SIGKILL of this helper is explicitly NOT a successful settlement: no receipt can be written.
+ */
+#define _GNU_SOURCE
+#include <errno.h>
+#include <fcntl.h>
+#include <limits.h>
+#include <poll.h>
+#include <signal.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/prctl.h>
+#include <sys/stat.h>
+#include <sys/syscall.h>
+#include <sys/types.h>
+#include <sys/wait.h>
+#include <time.h>
+#include <unistd.h>
+
+static volatile sig_atomic_t requested_signal;
+static void on_signal(int signo) { requested_signal = signo; }
+static long long monotonic_ms(void) {
+  struct timespec now; clock_gettime(CLOCK_MONOTONIC, &now);
+  return (long long)now.tv_sec * 1000 + now.tv_nsec / 1000000;
+}
+static void quoted(FILE *out, const char *s) {
+  fputc('"', out);
+  for (; *s; s++) {
+    unsigned char c = (unsigned char)*s;
+    if (c == '"' || c == '\\') { fputc('\\', out); fputc(c, out); }
+    else if (c < 32) fprintf(out, "\\u%04x", c);
+    else fputc(c, out);
+  }
+  fputc('"', out);
+}
+static int read_text(const char *path, char *out, size_t size) {
+  int fd = open(path, O_RDONLY | O_CLOEXEC); if (fd < 0) return -1;
+  ssize_t n = read(fd, out, size - 1); close(fd); if (n <= 0) return -1;
+  out[n] = 0; out[strcspn(out, "\r\n")] = 0; return 0;
+}
+static int self_start(char *out, size_t size) {
+  char data[4096]; if (read_text("/proc/self/stat", data, sizeof(data)) < 0) return -1;
+  char *end = strrchr(data, ')'); if (!end) return -1;
+  char *save = NULL, *part = strtok_r(end + 2, " ", &save);
+  for (int field = 3; part; field++, part = strtok_r(NULL, " ", &save)) {
+    if (field == 22) { snprintf(out, size, "%s", part); return 0; }
+  }
+  return -1;
+}
+struct identity {
+  const char *execution, *nonce, *root, *hash, *directory;
+  char boot[80], ns[80], start[40], ownership[PATH_MAX], receipt[PATH_MAX];
+  struct stat workspace;
+  pid_t worker;
+};
+static void identity_json(FILE *out, const struct identity *id) {
+  fprintf(out, "{\"revision\":1,\"executionId\":"); quoted(out, id->execution);
+  fprintf(out, ",\"nonce\":"); quoted(out, id->nonce);
+  fprintf(out, ",\"root\":"); quoted(out, id->root);
+  fprintf(out, ",\"rootDevice\":\"%llu\",\"rootInode\":\"%llu\"", (unsigned long long)id->workspace.st_dev, (unsigned long long)id->workspace.st_ino);
+  fprintf(out, ",\"bootId\":"); quoted(out, id->boot);
+  fprintf(out, ",\"pidNamespace\":"); quoted(out, id->ns);
+  fprintf(out, ",\"helperPid\":%d,\"helperStartTicks\":", getpid()); quoted(out, id->start);
+  fprintf(out, ",\"helperSha256\":"); quoted(out, id->hash);
+  fprintf(out, ",\"workerPid\":%d,\"ownershipPath\":", id->worker); quoted(out, id->ownership);
+  fprintf(out, ",\"receiptPath\":"); quoted(out, id->receipt); fprintf(out, "}");
+}
+static int durable(const struct identity *id, int settled, int worker_status, const char *reason) {
+  const char *path = settled ? id->receipt : id->ownership;
+  char temp[PATH_MAX]; if (snprintf(temp, sizeof(temp), "%s.tmp", path) >= (int)sizeof(temp)) return -1;
+  int fd = open(temp, O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW | O_CLOEXEC, 0600); if (fd < 0) return -1;
+  FILE *out = fdopen(fd, "w"); if (!out) { close(fd); return -1; }
+  fprintf(out, "{\"state\":\"%s\",\"identity\":", settled ? "settled" : "ready"); identity_json(out, id);
+  if (settled) {
+    fprintf(out, ",\"workerCode\":"); if (WIFEXITED(worker_status)) fprintf(out, "%d", WEXITSTATUS(worker_status)); else fprintf(out, "null");
+    fprintf(out, ",\"workerSignal\":%d,\"reason\":", WIFSIGNALED(worker_status) ? WTERMSIG(worker_status) : 0); quoted(out, reason);
+    fprintf(out, ",\"reapedAll\":true");
+  }
+  fprintf(out, "}\n");
+  int ok = fflush(out) == 0 && fsync(fd) == 0;
+  if (fclose(out) != 0) ok = 0;
+  if (!ok || link(temp, path) < 0 || unlink(temp) < 0) return -1;
+  int dir = open(id->directory, O_RDONLY | O_DIRECTORY | O_CLOEXEC);
+  if (dir < 0) return -1;
+  ok = fsync(dir) == 0; close(dir); return ok ? 0 : -1;
+}
+static int milliseconds(const char *text, long maximum, long *value) {
+  if (!*text) return -1;
+  for (const char *p = text; *p; p++) if (*p < '0' || *p > '9') return -1;
+  char *end; errno = 0; long parsed = strtol(text, &end, 10);
+  if (errno || *end || parsed < 0 || parsed > maximum) return -1;
+  *value = parsed; return 0;
+}
+static int validate_channel(int fd, int writing) {
+  struct stat info; int flags = fcntl(fd, F_GETFL);
+  if (flags < 0 || fstat(fd, &info) < 0 || (!S_ISFIFO(info.st_mode) && !S_ISSOCK(info.st_mode))) return -1;
+  if ((writing && (flags & O_ACCMODE) == O_RDONLY) || (!writing && (flags & O_ACCMODE) == O_WRONLY)) return -1;
+  return writing ? 0 : fcntl(fd, F_SETFL, flags | O_NONBLOCK);
+}
+/* A direct child cannot reuse its PID before our waitpid. Forget its signal record only after reaping. */
+struct signalled_child { pid_t pid; int signo; };
+static struct signalled_child *signalled;
+static size_t signalled_count;
+static void forget_child(pid_t pid) {
+  for (size_t i = 0; i < signalled_count; i++) if (signalled[i].pid == pid) {
+    signalled[i] = signalled[--signalled_count]; return;
+  }
+}
+/* Signal only this helper's direct children. No process-name, cwd, PID-group or global enumeration. */
+static int signal_children(int signo) {
+  char path[100]; snprintf(path, sizeof(path), "/proc/self/task/%d/children", getpid());
+  FILE *children = fopen(path, "r"); if (!children) return -1;
+  int pid, ok = 0, scanned;
+  while ((scanned = fscanf(children, "%d", &pid)) == 1) {
+    if (pid <= 0) { ok = -1; break; }
+    size_t index = 0;
+    while (index < signalled_count && signalled[index].pid != pid) index++;
+    if (signo && index < signalled_count && signalled[index].signo == signo) continue;
+    int pfd = (int)syscall(SYS_pidfd_open, pid, 0);
+    if (pfd < 0) { if (errno != ESRCH) ok = -1; continue; }
+    if (syscall(SYS_pidfd_send_signal, pfd, signo, NULL, 0) < 0 && errno != ESRCH) ok = -1;
+    close(pfd);
+    if (signo && ok == 0) {
+      if (index == signalled_count) {
+        void *next = realloc(signalled, (signalled_count + 1) * sizeof(*signalled));
+        if (!next) { ok = -1; break; }
+        signalled = next; signalled_count++; signalled[index].pid = pid;
+      }
+      signalled[index].signo = signo;
+    }
+  }
+  if (scanned != EOF || ferror(children)) ok = -1;
+  fclose(children); return ok;
+}
+int main(int argc, char **argv) {
+  /* execution nonce canonical-root helper-sha ownership-dir grace-ms cleanup-ms -- command args */
+  if (argc < 10 || strcmp(argv[8], "--")) return 64;
+  struct identity id = { .execution=argv[1], .nonce=argv[2], .root=argv[3], .hash=argv[4], .directory=argv[5] };
+  long grace, ceiling;
+  if (milliseconds(argv[6], 60000, &grace) < 0 || milliseconds(argv[7], 120000, &ceiling) < 0 || ceiling < grace) return 64;
+  if (validate_channel(3, 0) < 0 || validate_channel(4, 1) < 0) return 65;
+  if (stat(id.root, &id.workspace) < 0 || !S_ISDIR(id.workspace.st_mode)) return 65;
+  if (read_text("/proc/sys/kernel/random/boot_id", id.boot, sizeof(id.boot)) < 0 || self_start(id.start, sizeof(id.start)) < 0) return 65;
+  ssize_t n = readlink("/proc/self/ns/pid", id.ns, sizeof(id.ns)-1); if (n < 0) return 65; id.ns[n] = 0;
+  if (snprintf(id.ownership, sizeof(id.ownership), "%s/ownership.json", id.directory) >= (int)sizeof(id.ownership) ||
+      snprintf(id.receipt, sizeof(id.receipt), "%s/receipt.json", id.directory) >= (int)sizeof(id.receipt)) return 65;
+  if (prctl(PR_SET_CHILD_SUBREAPER, 1) < 0) return 65;
+  int probe = (int)syscall(SYS_pidfd_open, getpid(), 0); if (probe < 0) return 65; close(probe);
+  if (signal_children(0) < 0) return 65; /* Probe /proc children support before admitting work. */
+  signal(SIGPIPE, SIG_IGN); signal(SIGTERM, on_signal); signal(SIGINT, on_signal); signal(SIGHUP, on_signal);
+  int gate[2]; if (pipe2(gate, O_CLOEXEC) < 0) return 65;
+  id.worker = fork(); if (id.worker < 0) return 65;
+  if (id.worker == 0) {
+    close(gate[1]); close(3); close(4); close(5);
+    signal(SIGTERM, SIG_DFL); signal(SIGINT, SIG_DFL); signal(SIGHUP, SIG_DFL); signal(SIGPIPE, SIG_DFL);
+    char release; if (read(gate[0], &release, 1) != 1 || release != 'S') _exit(125);
+    close(gate[0]); if (chdir(id.root) < 0) _exit(126);
+    execvp(argv[9], &argv[9]); _exit(errno == ENOENT ? 127 : 126);
+  }
+  close(gate[0]);
+  int ready = durable(&id, 0, 0, "ready") == 0;
+  if (ready) {
+    FILE *status = fdopen(dup(4), "w");
+    if (status) { identity_json(status, &id); fputc('\n', status); if (ferror(status)) ready = 0; if (fclose(status) != 0) ready = 0; }
+    else ready = 0;
+  }
+  long long stopping = ready ? 0 : monotonic_ms();
+  const char *reason = ready ? "worker-exit" : "ownership-write-failed";
+  int started = 0, worker_status = 0, worker_reaped = 0, control_open = 1;
+  for (;;) {
+    int status; pid_t reaped;
+    while ((reaped = waitpid(-1, &status, WNOHANG)) > 0) {
+      forget_child(reaped);
+      if (reaped == id.worker) { worker_status=status; worker_reaped=1; if (!stopping) stopping=monotonic_ms(); }
+    }
+    if (reaped < 0 && errno == ECHILD) {
+      if (!worker_reaped) return 74;
+      if (durable(&id, 1, worker_status, reason) < 0) return 74;
+      close(gate[1]); return 0;
+    }
+    if (requested_signal && !stopping) { stopping=monotonic_ms(); reason="helper-signal"; }
+    char control[32]; ssize_t received = control_open ? read(3, control, sizeof(control)) : -1;
+    if (control_open && (received == 0 || (received < 0 && errno != EAGAIN && errno != EWOULDBLOCK))) { control_open=0; if (!stopping) { stopping=monotonic_ms(); reason="owner-loss"; } }
+    if (received > 0) for (ssize_t i=0;i<received;i++) {
+      if (control[i] == 'K') {
+        if (!stopping) { stopping=monotonic_ms(); reason="cancelled"; }
+        long long immediate = monotonic_ms()-grace;
+        if (stopping > immediate) stopping=immediate; /* Escalate without rewriting the original cause. */
+      }
+      if (control[i] == 'C' && !stopping) { stopping=monotonic_ms(); reason="cancelled"; }
+      if (control[i] == 'S' && ready && !started && !stopping) { started=1; if (write(gate[1], "S", 1) != 1) { stopping=monotonic_ms(); reason="start-failed"; } }
+    }
+    if (stopping) {
+      long long elapsed = monotonic_ms()-stopping;
+      if (signal_children(elapsed >= grace ? SIGKILL : SIGTERM) < 0) return 74;
+      if (elapsed >= ceiling) return 74; /* Missing receipt preserves uncertainty. */
+    }
+    struct pollfd pfd = { .fd=control_open ? 3 : -1, .events=POLLIN | POLLHUP };
+    int polled = poll(&pfd, 1, 10);
+    if ((polled < 0 && errno != EINTR) || (polled > 0 && (pfd.revents & POLLNVAL))) {
+      control_open=0;
+      if (!stopping) { stopping=monotonic_ms(); reason="owner-loss"; }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
   "keywords": [
     "pi-package",
@@ -45,7 +45,8 @@
     "THIRD_PARTY_NOTICES.md",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "native"
   ],
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
@@ -55,7 +56,8 @@
     "test:integration:ci": "node --test test-integration/approval.it.ts test-integration/governance.it.ts test-integration/activity.it.ts",
     "contracts:generate": "node scripts/generate-ledger-record-contract.ts",
     "prepack": "npm run build",
-    "test:smoke": "node scripts/smoke-installed.mjs"
+    "test:smoke": "node scripts/smoke-installed.mjs",
+    "build:worker": "node scripts/build-worker.ts"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -65,16 +67,22 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.83.0",
     "@types/node": ">=22",
-    "typebox": ">=1.0.0"
+    "typebox": ">=1.0.0",
+    "@earendil-works/pi-coding-agent": "1.0.4"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.83.0",
+    "@earendil-works/pi-coding-agent": "1.0.4",
     "typebox": ">=1.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0"
-  }
+  },
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ]
 }

package/src/cli.ts

@@ -17,6 +17,7 @@ import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { relative, resolve as resolvePath } from "node:path";
 import { pathToFileURL } from "node:url";
+import { BoundedReadCleanupError } from "./kernel/bounded-read.ts";
 import { UnsafeGrantError } from "./kernel/grant-env.ts";
 import {
   applyInit,
@@ -26,7 +27,7 @@ import {
   GITIGNORE_REINCLUDE_LINES,
   settingsIgnoredByGit,
 } from "./governance/init.ts";
-import { registeredWorkspaceIds } from "./kernel/workspace.ts";
+import { registeredWorkspaceIds, loadWorkspaceRegistry } from "./kernel/workspace.ts";
 import { explainDoubledNamespace } from "./kernel/catalog.ts";
 import type { Capability } from "./kernel/resolve.ts";
 import {
@@ -178,7 +179,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
 }
 
 /** Report a plan and what came of applying it. Returns the process exit code. */
-async function init(cwd: string, force: boolean): Promise<number> {
+async function init(cwd: string, force: boolean, loadRegistry: typeof loadWorkspaceRegistry): Promise<number> {
   const packages = await discoverSkillPackages(cwd);
   if (packages.length === 0) {
     // Names BOTH roots it looked in, and offers pi's own install command first. The previous message named
@@ -204,13 +205,19 @@ async function init(cwd: string, force: boolean): Promise<number> {
     plan = planInit(
       packages,
       cwd,
-      await registeredWorkspaceIds(undefined, (reason) =>
-        console.error(`pi-daddy init: workspace registry unreadable, scaffolding none — ${reason}`),
+      await registeredWorkspaceIds(
+        undefined,
+        (reason) => console.error(`pi-daddy init: workspace registry unreadable, scaffolding none — ${reason}`),
+        loadRegistry,
       ),
     );
   } catch (error) {
     // R-78's backstop reaching the surface. Nothing is written: a grant that could mean something to a
     // shell is not a grant, and half-scaffolding a project would be worse than scaffolding none of it.
+    if (error instanceof BoundedReadCleanupError) {
+      console.error(`pi-daddy init: cleanup failed — ${error.message}; no scaffolding applied.`);
+      throw error;
+    }
     if (error instanceof UnsafeGrantError) {
       console.error(`pi-daddy init: ${error.message}`);
       return 1;
@@ -352,7 +359,10 @@ async function report(plan: InitPlan): Promise<void> {
   );
 }
 
-export async function main(argv: string[]): Promise<number> {
+export async function main(
+  argv: string[],
+  loadRegistry: typeof loadWorkspaceRegistry = loadWorkspaceRegistry,
+): Promise<number> {
   const adoptedLegacy = adoptLegacyEnvironment(process.env);
   if (adoptedLegacy.length > 0) console.error(legacyEnvironmentWarning(adoptedLegacy));
   const parsed = parseArgs(argv);
@@ -475,7 +485,7 @@ export async function main(argv: string[]): Promise<number> {
   // `--dir` made that comparison false for every entry: every declared skill of every package was reported
   // "declared but unreadable", nothing was copied, a degenerate grants.env was written anyway, and the exit
   // code was 0 — while the message blamed the package for a defect in this line.
-  return init(resolvePath(parsed.dir ?? process.cwd()), parsed.force);
+  return init(resolvePath(parsed.dir ?? process.cwd()), parsed.force, loadRegistry);
 }
 
 /**

package/src/executors/activity-session.ts

@@ -8,9 +8,9 @@
  * already carries `--session` (native-session retention), that file is the probe; otherwise a private temporary
  * file is allocated for the run and removed afterwards.
  */
-import { createReadStream } from "node:fs";
 import { mkdtemp, readdir, rm, stat } from "node:fs/promises";
-import { createInterface } from "node:readline";
+import { SessionManager, type FileEntry } from "@earendil-works/pi-coding-agent";
+import { BoundedReadCleanupError, readBoundedBytes } from "../kernel/bounded-read.ts";
 import type { ChildUsageTotals } from "../governance/ledger-events.ts";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -74,7 +74,7 @@ export async function activitySessionFor(planArgs: string[], executionId: string
       args: planArgs,
       path: dir,
       probe: probeDirectory(dir),
-      usage: () => readChildUsage(newestSessionFile(dir)),
+      usage: () => readChildUsage(exactSessionFile(dir, planArgs[planArgs.indexOf("--session-id") + 1])),
       dispose: async () => undefined,
     };
   }
@@ -114,14 +114,11 @@ export async function activitySessionFor(planArgs: string[], executionId: string
   };
 }
 
-async function newestSessionFile(directory: string): Promise<string | undefined> {
+async function exactSessionFile(directory: string, id: string | undefined): Promise<string | undefined> {
+  if (!id || !/^[a-zA-Z0-9-]+$/.test(id)) return undefined;
   try {
-    const entries = await Promise.all(
-      (await readdir(directory))
-        .filter((name) => name.endsWith(".jsonl"))
-        .map(async (name) => ({ path: join(directory, name), modified: (await stat(join(directory, name))).mtimeMs })),
-    );
-    return entries.sort((a, b) => b.modified - a.modified)[0]?.path;
+    const names = (await readdir(directory)).filter((name) => name.endsWith(`_${id}.jsonl`));
+    return names.length === 1 ? join(directory, names[0]) : undefined;
   } catch {
     return undefined;
   }
@@ -130,82 +127,138 @@ async function newestSessionFile(directory: string): Promise<string | undefined>
 const TOKEN_FIELDS = ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const;
 const COST_FIELDS = ["input", "output", "cacheRead", "cacheWrite", "total"] as const;
 
+// Match final capture's bound; oversized or damaged accounting stays unknown, never a partial total.
+const MAX_USAGE_SESSION_BYTES = 64 * 1024 * 1024;
+const ENTRY_TYPES = new Set([
+  "message",
+  "model_change",
+  "thinking_level_change",
+  "usage",
+  "compaction",
+  "branch_summary",
+  "custom",
+  "label",
+  "session_info",
+  "custom_message",
+  "context_edit",
+]);
+function activeUsageBranch(source: string) {
+  if (!source.endsWith("\n")) throw new Error("incomplete session record");
+  const entries = source
+    .slice(0, -1)
+    .split("\n")
+    .map((line) => JSON.parse(line));
+  const header = object(entries[0]);
+  if (
+    !header ||
+    header.type !== "session" ||
+    header.version !== 3 ||
+    typeof header.id !== "string" ||
+    !header.id ||
+    typeof header.cwd !== "string" ||
+    !header.cwd
+  )
+    throw new Error("invalid canonical session header");
+  const seen = new Set<string>();
+  for (const value of entries.slice(1)) {
+    const entry = object(value);
+    if (
+      !entry ||
+      !ENTRY_TYPES.has(String(entry.type)) ||
+      typeof entry.id !== "string" ||
+      !entry.id ||
+      seen.has(entry.id) ||
+      typeof entry.timestamp !== "string" ||
+      (entry.parentId !== null && (typeof entry.parentId !== "string" || !seen.has(entry.parentId)))
+    )
+      throw new Error("ambiguous canonical session tree");
+    if (entry.type === "message" && !object(entry.message)) throw new Error("invalid session message");
+    seen.add(entry.id);
+  }
+  // This public SDK seam reads already bounded in-memory bytes; it never reopens the path or scans other branches.
+  return SessionManager.inMemory(header.cwd, undefined, entries as FileEntry[]).getBranch();
+}
+
 async function readChildUsage(path: string | Promise<string | undefined>): Promise<ChildUsageObservation> {
   const resolved = await path;
   if (!resolved) return { unavailable: "session-missing" };
   const totals = emptyUsage();
-  let found = false;
-  let reasoning = 0;
-  let sawReasoning = false;
+  let found = false,
+    incomplete = false,
+    reasoning = 0,
+    sawReasoning = false;
   let resolvedModel: ChildUsageObservation["resolvedModel"];
   let effectiveThinkingLevel: string | undefined;
   let compactionCount = 0;
   try {
-    const lines = createInterface({ input: createReadStream(resolved, { encoding: "utf8" }), crlfDelay: Infinity });
-    for await (const line of lines) {
-      let entry: unknown;
-      try {
-        entry = JSON.parse(line);
-      } catch {
-        return { unavailable: "session-invalid" };
-      }
-      const parsed = object(entry);
-      if (
-        parsed?.type === "model_change" &&
-        typeof parsed.provider === "string" &&
-        typeof parsed.modelId === "string"
-      ) {
-        resolvedModel = { provider: parsed.provider, modelId: parsed.modelId };
+    const read = await readBoundedBytes(resolved, { maxBytes: MAX_USAGE_SESSION_BYTES, timeoutMs: 3000 });
+    if (!read.ok)
+      return { unavailable: "code" in read && read.code === "ENOENT" ? "session-missing" : "session-invalid" };
+    const source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(read.bytes);
+    const branch = activeUsageBranch(source);
+    const userIndex = branch.findLastIndex((entry) => entry.type === "message" && entry.message.role === "user");
+    for (const [index, entry] of branch.entries()) {
+      if (entry.type === "model_change") {
+        if (typeof entry.provider !== "string" || typeof entry.modelId !== "string")
+          return { unavailable: "session-invalid" };
+        resolvedModel = { provider: entry.provider, modelId: entry.modelId };
         continue;
       }
-      if (parsed?.type === "thinking_level_change" && typeof parsed.thinkingLevel === "string") {
-        effectiveThinkingLevel = parsed.thinkingLevel;
+      if (entry.type === "thinking_level_change") {
+        if (typeof entry.thinkingLevel !== "string") return { unavailable: "session-invalid" };
+        effectiveThinkingLevel = entry.thinkingLevel;
         continue;
       }
-      if (parsed?.type === "compaction") {
-        compactionCount += 1;
-        continue;
-      }
-      const message = object(parsed?.message);
-      if (!message) continue;
-      if (message.role === "user") {
-        Object.assign(totals, emptyUsage());
-        found = false;
-        reasoning = 0;
-        sawReasoning = false;
-        compactionCount = 0;
-        continue;
-      }
-      if (message.role !== "assistant" && message.role !== "toolResult") continue;
-      if (message.role === "assistant" && typeof message.provider === "string" && typeof message.model === "string") {
-        resolvedModel = { provider: message.provider, modelId: message.model };
-      }
-      const usage = object(message.usage);
-      if (message.role === "toolResult" && !usage) continue;
+      // Current-turn accounting excludes both inherited prior turns and abandoned branch work.
+      if (userIndex < 0 || index <= userIndex) continue;
+      if (entry.type === "compaction") compactionCount += 1;
+      let usage: Record<string, unknown> | undefined;
+      if (entry.type === "message") {
+        const message = object(entry.message)!;
+        if (message.role !== "assistant" && message.role !== "toolResult") continue;
+        if (message.role === "assistant" && typeof message.provider === "string" && typeof message.model === "string")
+          resolvedModel = { provider: message.provider, modelId: message.model };
+        usage = object(message.usage);
+        if (message.role === "toolResult" && !usage) continue;
+      } else if (["usage", "compaction", "branch_summary"].includes(entry.type)) {
+        usage = object((entry as unknown as Record<string, unknown>).usage);
+        if (!usage) {
+          incomplete = true;
+          continue;
+        }
+      } else continue;
       const cost = object(usage?.cost);
-      if (!usage || !cost) return { unavailable: "session-invalid" };
-      if (!TOKEN_FIELDS.every((field) => nonNegative(usage[field]))) return { unavailable: "session-invalid" };
-      if (!COST_FIELDS.every((field) => nonNegative(cost[field]))) return { unavailable: "session-invalid" };
-      if (usage.reasoning !== undefined && !nonNegative(usage.reasoning)) return { unavailable: "session-invalid" };
+      if (
+        !usage ||
+        !cost ||
+        !TOKEN_FIELDS.every((field) => nonNegative(usage[field])) ||
+        !COST_FIELDS.every((field) => nonNegative(cost[field])) ||
+        (usage.reasoning !== undefined && !nonNegative(usage.reasoning))
+      )
+        return { unavailable: "session-invalid" };
       for (const field of TOKEN_FIELDS) totals[field] += usage[field] as number;
       for (const field of COST_FIELDS) totals.cost[field] += cost[field] as number;
       if (usage.reasoning !== undefined) {
         reasoning += usage.reasoning as number;
         sawReasoning = true;
       }
+      if (
+        !TOKEN_FIELDS.every((field) => nonNegative(totals[field])) ||
+        !COST_FIELDS.every((field) => nonNegative(totals.cost[field])) ||
+        !nonNegative(reasoning)
+      )
+        return { unavailable: "session-invalid" };
       found = true;
     }
-    if (!found)
-      return {
-        unavailable: "usage-missing",
-        ...(resolvedModel ? { resolvedModel } : {}),
-        ...(effectiveThinkingLevel ? { effectiveThinkingLevel } : {}),
-        compactionCount,
-      };
-    return {
-      usage: { ...totals, ...(sawReasoning ? { reasoning } : {}) },
+    const metadata = {
       ...(resolvedModel ? { resolvedModel } : {}),
       ...(effectiveThinkingLevel ? { effectiveThinkingLevel } : {}),
+      compactionCount,
+    };
+    if (!found || incomplete) return { unavailable: "usage-missing", ...metadata };
+    return {
+      usage: { ...totals, ...(sawReasoning ? { reasoning } : {}) },
+      ...metadata,
       tokenDetail: {
         inputTokens: positiveOrNull(totals.input),
         outputTokens: positiveOrNull(totals.output),
@@ -213,10 +266,11 @@ async function readChildUsage(path: string | Promise<string | undefined>): Promi
         cacheWriteTokens: positiveOrNull(totals.cacheWrite),
         reasoningTokens: sawReasoning ? positiveOrNull(reasoning) : null,
       },
-      compactionCount,
     };
-  } catch {
-    return { unavailable: "session-missing" };
+  } catch (error) {
+    // Preserve the exact retained descriptor capability for the initiating execution/session owner.
+    if (error instanceof BoundedReadCleanupError) throw error;
+    return { unavailable: "session-invalid" };
   }
 }