toolroll 0.9.103 → 0.9.105

package/dist/run-efficiency.js

@@ -1,19 +1,8 @@
-/**
- * How a run went (docs/plans/run-efficiency.md): derived from the run's own records, display only. It never changes a
- * completion, an approval, a charge or a check verdict, and it claims nothing its sources don't hold — an unreported
- * number is unknown (null, shown as a dash), never zero.
- *
- * Sources, and what each can say: the run row (wall times, tokens, the provider's raw usage with its cache counts, the
- * agent's turns where reported) is kept with the run; the live records (`<evidence>/live/<run>.jsonl`, display-only,
- * kept 24 hours) are read once, bounded, through the descriptor-safe live reader, for step counts and observed step
- * times. No command text is ever stored here: repeats are counted, never quoted.
- */
 import { runLiveCommands } from "./store.js";
 import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
 import { join } from "node:path";
 import { LIVE_RETAIN_MS, legacyLiveLogPath, liveLogPath, liveWindowRecords } from "./live.js";
 export const RUN_EFFICIENCY_VERSION = 3;
-/** Budgets for one derivation: never more than the live file's own cap, and a bounded record count. */
 export const EFFICIENCY_READ_BYTES = 4 * 1024 * 1024;
 export const EFFICIENCY_RECORDS = 20_000;
 const LONGEST = 5;
@@ -24,7 +13,6 @@ const msBetween = (from, to) => {
     const ms = Date.parse(to) - Date.parse(from);
     return Number.isFinite(ms) && ms >= 0 ? ms : null;
 };
-/** Tokens and cache from the provider's own usage report, read per provider (their counts mean different things). */
 export function usageOf(run) {
     let raw = {};
     try {
@@ -37,24 +25,17 @@ export function usageOf(run) {
     }
     const base = { provider: run.provider, model: run.model ?? null, out: num(raw["output_tokens"]) ?? run.tokensOut ?? null };
     if (run.provider === "claude") {
-        // Claude's input_tokens leave out what was read from or written to the cache: the three add up to what it read, so
-        // all three must be reported before a total or a share is claimed (a missing one is unknown, never zero).
         const input = num(raw["input_tokens"]), read = num(raw["cache_read_input_tokens"]), write = num(raw["cache_creation_input_tokens"]);
         const total = input === null || read === null || write === null ? null : input + read + write;
         return { ...base, in: total, cacheRead: read, cacheWrite: write, cacheShare: total === null || total === 0 ? null : read / total };
     }
     if (run.provider === "codex") {
-        // Codex's input_tokens already include what came from its cache: both reported, or no share.
         const input = num(raw["input_tokens"]), read = num(raw["cached_input_tokens"]);
         return { ...base, in: input ?? run.tokensIn ?? null, cacheRead: read, cacheWrite: null,
             cacheShare: read === null || input === null || input === 0 || read > input ? null : read / input };
     }
     return { ...base, in: run.tokensIn ?? null, cacheRead: null, cacheWrite: null, cacheShare: null };
 }
-/** The live records' steps, bounded: counts by kind, failures, observed times and repeats (never their words). */
-/** `measured`: the recorder saw this provider's steps start and end as they happened (Claude's stream does); for the
- * others their times are partly made up (Codex reports a step when it completes, ACP agents may report late), so no
- * duration is claimed for them. */
 export function stepsOf(records, truncated, measured = true) {
     let detail = "base";
     const open = new Map();
@@ -78,8 +59,6 @@ export function stepsOf(records, truncated, measured = true) {
             open.delete(record.id);
             if (record.ok === false)
                 failed++;
-            // Not a measured time: a provider whose times the recorder can't see as they happen, a start and end made up
-            // together (`once`), a step the recorder closed itself when the run ended (outcome unknown), or no time between.
             const ms = !measured || started.once || record.ok === null ? null : msBetween(started.at || null, record.at || null);
             if (ms === null || ms === 0) {
                 unknown++;
@@ -91,10 +70,7 @@ export function stepsOf(records, truncated, measured = true) {
                 longest.pop();
         }
     }
-    // Steps that never closed (the run ended, or the file was cut) have no measured time.
     unknown += open.size;
-    // Repeats are never claimed: the step records keep a display form of each step (a file name, a host, a command with
-    // its shell wrapper taken off), so two different steps can read alike. Said, not guessed.
     const repeatsReason = detail === "commands"
         ? "Repeats can't be told apart: the step records keep a short form of each step, not its whole input."
         : "Repeats can't be told apart: this project doesn't record step details.";
@@ -102,10 +78,6 @@ export function stepsOf(records, truncated, measured = true) {
     return { state: truncated === null ? "complete" : "truncated", reason: truncated, total, failed, unknownDuration: unknown, byKind, longest, repeats, repeatsReason };
 }
 const noSteps = (state, reason) => ({ state, reason, total: null, failed: null, unknownDuration: null, byKind: {}, longest: [], repeats: null, repeatsReason: null });
-/** Read the run's live records once, strictly bounded: its own descriptor (no link followed, in a real live
- * directory), measured once, and never more than the budget read whatever the file does meanwhile; then parsed line by
- * line. A file over the budget, in the older text format, with lines that don't read, or cut or capped while the agent
- * ran, says its steps are incomplete. Null when there is no step file at all. */
 function readRecords(evidenceRoot, runId, commands) {
     try {
         const dir = lstatSync(join(evidenceRoot, "live"));
@@ -122,7 +94,6 @@ function readRecords(evidenceRoot, runId, commands) {
     catch (error) {
         if (error.code !== "ENOENT")
             return { unreadable: "The step records couldn't be read." };
-        // No records file: an older run's plain text file has no step detail; with neither, there is nothing.
         try {
             lstatSync(legacyLiveLogPath(evidenceRoot, runId));
             return { unreadable: "This run's steps were recorded in an older format that has no step detail." };
@@ -138,7 +109,6 @@ function readRecords(evidenceRoot, runId, commands) {
             return { unreadable: "The step records aren't a plain file, so they weren't read." };
         if (stat.size > EFFICIENCY_READ_BYTES)
             return { unreadable: "The step records are larger than they can be read here." };
-        // At most what it measured, and never past the budget: growth after the measure is not read.
         const buffer = Buffer.alloc(stat.size);
         let at = 0;
         while (at < buffer.length) {
@@ -147,7 +117,6 @@ function readRecords(evidenceRoot, runId, commands) {
                 break;
             at += got;
         }
-        // Less than it measured: the file changed under the read.
         short = at < buffer.length;
         text = buffer.subarray(0, at).toString("utf8");
     }
@@ -158,16 +127,13 @@ function readRecords(evidenceRoot, runId, commands) {
         closeSync(fd);
     }
     const lines = text.split("\n");
-    // The last line may be unfinished (the agent's final write): it is read when it parses, never counted as a loss.
     const unfinished = lines.at(-1) ?? "";
     const whole = lines.slice(0, -1).filter(line => line.trim() !== "");
     if (whole.length > EFFICIENCY_RECORDS)
         whole.length = EFFICIENCY_RECORDS;
     const keys = { inKey: false };
-    // One record per line: a whole line that doesn't read is a record lost.
     const read = liveWindowRecords({ text: whole.length === 0 ? "" : `${whole.join("\n")}\n`, format: "records" }, commands, keys);
     const lost = whole.length - read.length;
-    // A finished run's last line without its newline is read like any other; one that doesn't read is a record lost.
     const tail = unfinished.trim() === "" ? [] : liveWindowRecords({ text: `${unfinished}\n`, format: "records" }, commands, keys);
     const records = [...read, ...tail];
     const lostAll = lost + (unfinished.trim() !== "" && tail.length === 0 ? 1 : 0);
@@ -181,7 +147,6 @@ function readRecords(evidenceRoot, runId, commands) {
                         : null;
     return { records, truncated };
 }
-/** Derive a finished run's How it ran from its records, read under the run's own captured "Show commands" answer. */
 export function deriveRunEfficiency(run, evidenceRoot, now, commands = false) {
     const finished = run.finishedAt;
     const read = readRecords(evidenceRoot, run.id, commands);
@@ -197,11 +162,6 @@ export function deriveRunEfficiency(run, evidenceRoot, now, commands = false) {
         steps,
     };
 }
-/**
- * A finished run's How it ran: the saved one when it was derived by this version, else derived now and saved (once:
- * a row whose steps were complete or have expired is final). An unfinished run is derived but never saved, and
- * nothing is saved when `save` is false (a page read ahead of its link writes nothing).
- */
 export function runEfficiencyOf(store, evidenceRoot, runId, now, save = true) {
     const run = store.getRun(runId);
     if (run === null)
@@ -222,12 +182,10 @@ export function runEfficiencyOf(store, evidenceRoot, runId, now, save = true) {
         try {
             return JSON.parse(String(saved["payload_json"]));
         }
-        catch { /* derived again below */ }
+        catch { }
     }
     const derived = deriveRunEfficiency(full, evidenceRoot, now, commands);
     const payload = JSON.stringify(derived);
-    // A row too large for its column (it can't be: the counts are bounded) is shown, never saved.
-    // Saving is a convenience: a store that can't take the row (read-only, busy) still shows what was derived.
     if (save && payload.length <= 16_384) {
         try {
             store.handle.prepare(`INSERT INTO run_efficiency (run, parser_version, steps, steps_reason, payload_json, derived_at) VALUES (?, ?, ?, ?, ?, ?)
@@ -235,7 +193,7 @@ export function runEfficiencyOf(store, evidenceRoot, runId, now, save = true) {
           payload_json = excluded.payload_json, derived_at = excluded.derived_at`)
                 .run(runId, RUN_EFFICIENCY_VERSION, derived.steps.state, derived.steps.reason, payload, now.toISOString());
         }
-        catch { /* shown, not saved: derived again next time */ }
+        catch { }
     }
     return derived;
 }

package/dist/run-ending.js

@@ -1,19 +1,6 @@
-/**
- * How a run ended, asked one way.
- *
- * "Interrupted" is stored in two spellings. Every ending written today is the outcome `failed` with the reason
- * `interrupted`. Rows written between schema 25 and 114 carry the outcome `interrupted` itself (a held session cut
- * down mid-flight) and still read. A check that knows only one spelling treats the same event two ways, so every check
- * asks here.
- */
 export function wasInterrupted(run) {
     return run.outcome === "interrupted" || (run.outcome === "failed" && run.reason === "interrupted");
 }
-/**
- * The spelling written today, and only it. The roads that hand an interrupted attempt's draft to the next attempt
- * (salvage in the checkout, the recovery grant, the check a run never reached) ask this one: they were built for the
- * runs that write it, and reading the old spelling there would widen what they recover.
- */
 export function endedInterrupted(run) {
     return run.outcome === "failed" && run.reason === "interrupted";
 }

package/dist/runner-process.js

@@ -1,25 +1,9 @@
-/**
- * Which processes hold a runner's credential, kept beside the plane's database so a later `up` can prove the previous
- * holder is gone (docs: the 2026-10-29 deploy incident). `toolroll up` registers its runner, then records itself and
- * every role child it hands the token to, each by process id AND start time, before the child receives the token.
- *
- * A fresh `up` whose runner name is still held (its heartbeat looks fresh, or its watch lease has not lapsed) asks
- * this record whether that holder is gone: the record must be for exactly the registration the plane holds (name,
- * host, registration time and credential), and every process in it must have exited, each proved by identity (no
- * such process, or a process with that id started at a different time). Then the plane retires the stale holder in
- * the same transaction that proved it (runner.ts registerRunnerIfIdle). Anything missing, unreadable or ambiguous
- * proves nothing, and the door keeps refusing until the heartbeat ages out, exactly as before.
- *
- * The record is the plane's own state (the folder that holds the database). It grants nothing by itself: it can
- * only let a name whose every recorded holder has exited be taken over early.
- */
 import { sameMachineHost } from "./machine-identity.js";
 import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { closeSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, renameSync, rmSync, writeFileSync, fsyncSync, constants } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 export const RUNNER_PROCESS_DIR = "runner-processes";
-/** The namespace is created before builds launch and denied by name, including in a shared state folder. */
 export function ensureRunnerProcessFolder(folder) {
     try {
         mkdirSync(folder, { mode: 0o700 });
@@ -40,7 +24,6 @@ export function sealRunnerProcessRecord(record, credentialHash) {
 const MAX_RECORD = 64 * 1024;
 const MAX_PROCESSES = 64;
 const ROLES = new Set(["up", "console", "worker"]);
-/** Where a runner's record lives: beside the database, under a name derived from the runner's (never the name itself). */
 export function runnerProcessFile(databaseFile, runner) {
     let database = databaseFile;
     try {
@@ -52,12 +35,10 @@ export function runnerProcessFile(databaseFile, runner) {
     }
     return join(realpathSync(dirname(database)), RUNNER_PROCESS_DIR, `${createHash("sha256").update(runner, "utf8").digest("hex").slice(0, 32)}.json`);
 }
-/** The incarnation's name in a record: a digest of the stored credential hash, so the record never holds that hash. */
 export function credentialDigest(credentialHash) {
     return createHash("sha256").update(`runner-process:${credentialHash}`, "utf8").digest("hex").slice(0, 32);
 }
 const LSTART = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{1,2}) (\d{2}:\d{2}:\d{2}) (\d{4})$/;
-/** `ps -o lstart=` (LC_ALL=C, TZ=UTC) as an ISO second, or null when it isn't exactly that shape. */
 export function parseProcessStart(raw) {
     const match = LSTART.exec(raw.trim().replace(/ +/g, " "));
     if (match === null)
@@ -68,7 +49,6 @@ export function parseProcessStart(raw) {
         return null;
     return new Date(at).toISOString();
 }
-/** When a process started (whole seconds), or null when there is no such process or it can't be read. */
 export function processStart(pid) {
     if (!Number.isSafeInteger(pid) || pid <= 1 || process.platform === "win32")
         return null;
@@ -96,7 +76,6 @@ export const realProcessProbe = {
     },
     start: processStart,
 };
-/** Proved gone: no process has this id, or the one that has it started at another time (the id was reused). */
 export function processGone(entry, probe = realProcessProbe) {
     const exists = probe.exists(entry.pid);
     if (exists === "absent")
@@ -108,7 +87,6 @@ export function processGone(entry, probe = realProcessProbe) {
         return probe.exists(entry.pid) === "absent";
     return started !== entry.started;
 }
-/** A record read strictly: a regular private file of bounded size, every field its exact type, or null. */
 export function readRunnerProcessRecord(file) {
     let fd = null;
     try {
@@ -166,7 +144,6 @@ function parseRecord(value) {
     return { v: 1, runner: v["runner"], host: v["host"], registeredAt: v["registeredAt"], credential: v["credential"], processes,
         ...(typeof v["signature"] === "string" ? { signature: v["signature"] } : {}) };
 }
-/** Replace the record atomically: a private temp file in a private folder, renamed into place. */
 export function writeRunnerProcessRecord(file, record) {
     ensureRunnerProcessFolder(dirname(file));
     const temp = `${file}.${randomUUID()}.tmp`;
@@ -185,10 +162,6 @@ export function writeRunnerProcessRecord(file, record) {
         rmSync(temp, { force: true });
     }
 }
-/**
- * Whether the plane's current holder of a runner name is proved gone: the record is for exactly that registration,
- * on this host, and every process it names has exited (by identity). `detail` says which processes, for the ledger.
- */
 export function holderProvedGone(record, holder, host, probe = realProcessProbe) {
     if (record === null)
         return { gone: false, why: "no readable record of its processes" };
@@ -207,7 +180,6 @@ export function holderProvedGone(record, holder, host, probe = realProcessProbe)
         return { gone: false, why: `process ${left.map(one => one.pid).join(", ")} is still running` };
     return { gone: true, detail: `${record.runner}: process ${record.processes.map(one => `${one.pid} (${one.role})`).join(", ")} proved gone` };
 }
-/** Re-read after observing exit: an up may append a child between the first read and its own exit. */
 export function recordedHolderProvedGone(file, holder, host, probe = realProcessProbe) {
     const record = readRunnerProcessRecord(file);
     const proof = holderProvedGone(record, holder, host, probe);
@@ -218,11 +190,6 @@ export function recordedHolderProvedGone(file, holder, host, probe = realProcess
         return { gone: false, why: "its process record changed during the exit proof" };
     return proof;
 }
-/**
- * Whether a record is authentic for exactly this registration on this host (the checks holderProvedGone makes before
- * it looks at any process): sealed with the stored credential hash, for this runner, host, registration and
- * credential. Null when it stands; otherwise why not. It says nothing about which processes still run.
- */
 export function recordStandsFor(record, holder, host) {
     if (record === null)
         return "no readable record of its processes";