toolroll 0.9.62 → 0.9.65

package/dist/quick-start.js

@@ -0,0 +1,127 @@
+/**
+ * BARE `toolroll` IN A REPOSITORY (docs/plans/agents-cockpit.md B1): the two-action start.
+ *
+ * Inside a git repository, `toolroll` with nothing else (or only --json) either starts the console for it (`up`), or —
+ * when this installation's console is already running and PROVES it is (console-instance.ts: a fresh challenge on the
+ * discovery socket and on its HTTP listener, answered with the secret in the database this CLI opened itself) —
+ * adds the repository through the ordinary project admission and opens that proved console. Under an agent, or with
+ * --json, it starts nothing and changes nothing: it says what it would do. Outside a repository, it scans as before
+ * (the scan is also `toolroll scan`).
+ */
+import { lstatSync, realpathSync } from "node:fs";
+import { proveLiveConsole } from "./console-instance.js";
+import { underAgent } from "./prompt.js";
+import { envelopeJson } from "./envelope.js";
+import { createRequire } from "node:module";
+import { openStoreReadOnly, readSchemaVersion, SCHEMA_VERSION } from "./store.js";
+const EXIT = { ok: 0, refused: 3 };
+/** Whether argv is a bare `toolroll` (nothing, or only --json). */
+export const isBareInvocation = (argv) => argv.every(one => one === "--json");
+/** The database's schema version by the store's own strict reader, read without changing anything. */
+function schemaOf(file) {
+    try {
+        // Loaded only here, as the store loads it: the CLI's other commands never pay for (or warn about) it.
+        const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite");
+        const db = new DatabaseSync(file, { readOnly: true });
+        try {
+            const read = readSchemaVersion(db);
+            return read.ok ? read : { ok: false };
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** Whether the database file is there: "absent" only when the system says so (ENOENT), never for a path it won't show. */
+function databasePresence(file) {
+    try {
+        lstatSync(file);
+        return "present";
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? "absent" : "unknown";
+    }
+}
+async function prove(seams) {
+    // Read only, never created or migrated, never cleaned up: proving changes nothing. "None" only when nothing of this
+    // build can be running on it (no database yet, or one older than this build, which `up` brings up to date); a
+    // database that can't be read, is mid-upgrade or is newer than this build can't be checked, so it is refused.
+    const none = { ok: false, state: "none", message: "no console is running" };
+    const unverifiable = (why) => ({ ok: false, state: "refused", message: `${why}, so a running console can't be checked — run \`toolroll up\` to see what's wrong` });
+    const presence = databasePresence(seams.databaseFile);
+    if (presence === "absent")
+        return none;
+    if (presence === "unknown")
+        return unverifiable("Toolroll's database can't be reached");
+    const schema = schemaOf(seams.databaseFile);
+    if (!schema.ok)
+        return unverifiable("Toolroll's database can't be read");
+    if (schema.version === null || (schema.version > 0 && schema.version < SCHEMA_VERSION))
+        return none;
+    if (schema.version !== SCHEMA_VERSION)
+        return unverifiable("Toolroll's database is being upgraded");
+    const store = openStoreReadOnly(seams.databaseFile);
+    if (store === null)
+        return unverifiable("Toolroll's database can't be read");
+    try {
+        return await proveLiveConsole(seams.databaseFile, store, seams.build, seams.attach ?? {});
+    }
+    catch {
+        return unverifiable("the running console couldn't be checked");
+    }
+    finally {
+        store.close();
+    }
+}
+/** null: not this command (outside a repository) — the caller scans as before. */
+export async function runQuickStart(argv, write, seams) {
+    const found = await seams.findRepo(seams.cwd);
+    if (found === null)
+        return null;
+    let repo = found;
+    try {
+        repo = realpathSync(found);
+    }
+    catch { /* as found */ }
+    const json = argv.includes("--json");
+    const dry = json || (seams.underAgent ?? underAgent(seams.env));
+    const proof = await prove(seams);
+    const enrolled = await seams.enrolled(repo);
+    const would = proof.ok ? (enrolled ? "open" : "add-and-open") : proof.state === "none" ? "start" : "refuse";
+    if (dry) {
+        // Nothing starts, nothing is added, nothing opens: what a person would get, in words or one envelope.
+        const words = would === "start" ? `Would start Toolroll for ${repo} (toolroll up).`
+            : would === "refuse" ? `Would refuse: ${proof.message}.`
+                : `Would ${would === "add-and-open" ? `add ${repo} and ` : ""}open the running console at ${proof.url}.`;
+        if (json)
+            write(envelopeJson({ ok: would !== "refuse", command: "toolroll", repo, would, ...(proof.ok ? { url: proof.url } : { console: proof.state, message: proof.message }), dryRun: true }));
+        else
+            write(words);
+        return would === "refuse" ? EXIT.refused : EXIT.ok;
+    }
+    if (!proof.ok && proof.state === "refused") {
+        write(`Toolroll can't attach: ${proof.message}.`);
+        return EXIT.refused;
+    }
+    if (!proof.ok)
+        return seams.startUp();
+    if (!enrolled) {
+        const admitted = await seams.admit(repo);
+        if (admitted !== 0)
+            return admitted;
+    }
+    // Whatever happened since the first proof (reading the registry, adding the project), the console is proved again,
+    // on both channels, right before its address is shown or opened — never a listener that took the port meanwhile.
+    const again = await prove(seams);
+    if (!again.ok || again.url !== proof.url || again.pid !== proof.pid) {
+        write(`Toolroll can't attach: ${again.ok ? "the console changed while the project was being added" : again.message} — run \`toolroll up\`.`);
+        return EXIT.refused;
+    }
+    write(`Toolroll is on ${proof.url}`);
+    if (seams.terminal)
+        await seams.openBrowser(proof.url);
+    return EXIT.ok;
+}

package/dist/release.d.ts

@@ -226,10 +226,13 @@ export type ReleaseJournal = {
         by: string;
         at: string;
     } | null;
+    /** The passing result: its run, receipt and checkout, and the commit it built (`head`), which a prepared candidate
+     * records as a commit of its own with exactly the candidate's tree (absent in a journal from before that was known). */
     check: {
         run: number;
         receipt: string;
         worktree: string;
+        head?: string;
     } | null;
     completion: {
         actor: string;

package/dist/release.js

@@ -213,9 +213,11 @@ export async function runRelease(options, adapters) {
             if (gate.result.check !== "passed")
                 throw new Stop("check-failed", `The Full release check of ${j.candidate.sha.slice(0, 7)} did not pass (run ${gate.result.run}: ${gate.result.check}). It stays as it is: fix the branch and release the new commit with --new.`);
         };
+        /** The commit the passing build recorded: what the deployed runtime is stamped with. */
+        const builtHead = () => j.check?.head ?? j.candidate.sha;
         const checked = (gate) => {
             approved(gate);
-            if (gate.result?.head !== j.candidate.sha || gate.result?.receipt !== j.check?.receipt)
+            if (gate.result?.head !== builtHead() || gate.result?.receipt !== j.check?.receipt)
                 throw new Stop("drift", `Task ${j.task.id}'s result changed since its check passed.`);
             fullCheck(gate);
         };
@@ -268,12 +270,16 @@ export async function runRelease(options, adapters) {
                             throw new Stop("check-failed", `The release build of ${j.task.id} failed: ${gate.failed}. Fix it and release the new commit with --new.`);
                         if (gate.result === null || gate.result.check === "running" || gate.result.check === "pending")
                             return null;
-                        if (gate.result.head !== j.candidate.sha)
-                            throw new Stop("drift", `The release result is for ${gate.result.head?.slice(0, 7) ?? "no commit"}, not ${j.candidate.sha.slice(0, 7)}.`);
+                        // The build records a prepared candidate as a commit of its own (its message names the task): it must hold
+                        // exactly the candidate's tree, or it isn't the release.
+                        const head = gate.result.head;
+                        if (head === null || (head !== j.candidate.sha && await adapters.repo.tree(head) !== await adapters.repo.tree(j.candidate.sha))) {
+                            throw new Stop("drift", `The release result is for ${head?.slice(0, 7) ?? "no commit"}, which doesn't hold exactly ${j.candidate.sha.slice(0, 7)}'s files.`);
+                        }
                         fullCheck(gate);
                         if (gate.result.worktree === null)
                             throw new Stop("worktree", `Run ${gate.result.run} names no checkout to deploy from.`);
-                        return { run: gate.result.run, receipt: gate.result.receipt, worktree: gate.result.worktree };
+                        return { run: gate.result.run, receipt: gate.result.receipt, worktree: gate.result.worktree, head };
                     });
                     j.check = result;
                     say(`  run ${result.run} passed on ${j.candidate.sha.slice(0, 7)}`);
@@ -310,7 +316,7 @@ export async function runRelease(options, adapters) {
                     await recoverDeploy();
                     checked(await adapters.toolroll.gate(j.task.id));
                     // A deployment that finished but whose answer was lost: the services already run a runtime of this commit.
-                    let runtime = await served(adapters, j.candidate.sha);
+                    let runtime = await served(adapters, builtHead());
                     if (runtime === null) {
                         await pinned();
                         j.deployAttempt = { stage: join(options.stateDir, "staged-upgrades", `browser-${j.candidate.sha.slice(0, 7)}-${randomUUID()}`) };
@@ -326,7 +332,7 @@ export async function runRelease(options, adapters) {
                         save();
                     }
                     const want = runtime;
-                    await waitFor("deploy", `the console and worker to run the gated commit from ${want}`, async () => (await served(adapters, j.candidate.sha)) === want ? true : null);
+                    await waitFor("deploy", `the console and worker to run the gated commit from ${want}`, async () => (await served(adapters, builtHead())) === want ? true : null);
                     j.deploy = { runtime: want, at: j.deploy?.runtime === want ? j.deploy.at : adapters.now().toISOString() };
                     j.deployAttempt = null;
                     delete j.intents.deploy;
@@ -336,7 +342,7 @@ export async function runRelease(options, adapters) {
                 }
                 case "link": {
                     const runtime = j.deploy.runtime;
-                    if (await served(adapters, j.candidate.sha) !== runtime)
+                    if (await served(adapters, builtHead()) !== runtime)
                         throw new Stop("drift", `The console and worker no longer run ${runtime}; the CLI names were not moved.`);
                     if (j.links === undefined || j.links === null) {
                         j.links = await adapters.toolroll.cliLinks();
@@ -348,7 +354,7 @@ export async function runRelease(options, adapters) {
                     catch (error) {
                         throw new Stop("link", `The CLI names were not moved to ${runtime} (they point where they did): ${error.message}. The service already runs the new build; rerun to try again.`);
                     }
-                    const everywhere = await deployed(adapters, j.candidate.sha);
+                    const everywhere = await deployed(adapters, builtHead());
                     if (everywhere !== runtime)
                         throw new Stop("mixed-runtime", `After relinking, the console, worker and both CLI names don't all run ${runtime} at ${j.candidate.sha.slice(0, 7)}.`);
                     say(`  toolroll and standing-orders run ${join(runtime, "bin.js")}`);

package/dist/remote-main.d.ts

@@ -1,6 +1,10 @@
 import { type ExecResult } from "./exec.js";
 import type { Store } from "./store.js";
 import type { Runner } from "./worktree.js";
+/** What the private directory's git may see of this process's environment: nothing that names a repository, an
+ * object store or config. The fixed settings below go on top. Teardown git (teardown-git.ts) uses the same. */
+export declare const ENV_ALLOWLIST: string[];
+export declare const ENV: Record<string, string>;
 /** The only credential helper https may use: the system keychain on macOS; elsewhere none, so a private https remote
  * fails closed instead of asking. */
 export declare const CREDENTIAL_HELPER: string;

package/dist/remote-main.js

@@ -21,9 +21,9 @@ const REMOTE_MAIN = "refs/toolroll/remote-main";
 const SHA = /^[0-9a-f]{40}$/;
 const FETCH_TIMEOUT_MS = 120_000;
 /** What the private directory's git may see of this process's environment: nothing that names a repository, an
- * object store or config. The fixed settings below go on top. */
-const ENV_ALLOWLIST = ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL", "SSH_AUTH_SOCK", "HTTPS_PROXY", "https_proxy", "NO_PROXY", "no_proxy"];
-const ENV = {
+ * object store or config. The fixed settings below go on top. Teardown git (teardown-git.ts) uses the same. */
+export const ENV_ALLOWLIST = ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL", "SSH_AUTH_SOCK", "HTTPS_PROXY", "https_proxy", "NO_PROXY", "no_proxy"];
+export const ENV = {
     GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_NO_REPLACE_OBJECTS: "1", GIT_TERMINAL_PROMPT: "0",
     GIT_ASKPASS: "", SSH_ASKPASS: "", GIT_SSH_COMMAND: "ssh -o BatchMode=yes",
 };

package/dist/request-budget-ui.js

@@ -1,4 +1,4 @@
-import { html, postForm } from "./html.js";
+import { html, postForm, reauth } from "./html.js";
 import { effectiveLimits, limitOverrides, PER_DAY_MAX, PER_MINUTE_MAX, REQUEST_BUDGET_DEFAULTS } from "./request-budget.js";
 const n = (value) => value.toLocaleString("en-US");
 export const REQUEST_LIMITS_CSS = `.credentials .limits{display:grid;gap:14px}.credentials .limits form{display:grid;gap:10px}.credentials .limits label{display:grid;gap:6px}` +
@@ -14,7 +14,7 @@ export function requestLimitsHtml(db, tokens, now) {
     const overrides = limitOverrides(db);
     const everyone = overrides.get("*") ?? { readPerMinute: null, actPerMinute: null, perDay: null };
     const field = (name, label, value, placeholder, max) => html `<label>${label}<input type="number" name="${name}" min="1" max="${max}" step="1" inputmode="numeric" value="${value === null ? "" : value}" placeholder="${placeholder}"></label>`;
-    const password = html `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password"></label>`;
+    const password = html `${reauth(html `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password"></label>`)}`;
     const buttons = html `<div class="actions"><button name="action" value="save">Save limits</button><button class="secondary" name="action" value="clear">Use defaults</button></div>`;
     const live = tokens.filter(one => one.revokedAt === null && Date.parse(one.expiresAt) > now);
     const installation = postForm("/settings/request-limits", html `\

package/dist/result-review.d.ts

@@ -149,7 +149,7 @@ export declare const RESULT_FACT_KEYS: readonly ["run", "head", "base", "head-so
 export declare function resultFactsFromHtml(html: string): Record<string, string>[];
 /** Where a result form may send its reader back: the review cockpit's
  * own deep link, the chat's result detail, the page of a task named in
- * `tasks` (the run's own), or the run page. Anything else lands on the run
+ * `tasks` (the run's own) or its Result tab at this run, or the run page. Anything else lands on the run
  * page. Matched exactly — never a bare open redirect. */
 export declare function resultReturnTarget(raw: string | null | undefined, runId: number, tasks?: readonly string[]): string;
 /** A form's own request token, minted per render — the same shape the

package/dist/result-review.js

@@ -147,7 +147,7 @@ export function resultFactsFromHtml(html) {
 }
 /** Where a result form may send its reader back: the review cockpit's
  * own deep link, the chat's result detail, the page of a task named in
- * `tasks` (the run's own), or the run page. Anything else lands on the run
+ * `tasks` (the run's own) or its Result tab at this run, or the run page. Anything else lands on the run
  * page. Matched exactly — never a bare open redirect. */
 export function resultReturnTarget(raw, runId, tasks = []) {
     if (raw !== null && raw !== undefined) {
@@ -160,6 +160,10 @@ export function resultReturnTarget(raw, runId, tasks = []) {
         // The run's own task page, which offered Run checks in place; never another task's.
         if (tasks.some(task => raw === `/t/${encodeURIComponent(task)}`))
             return raw;
+        // That task page's Result tab at this run (docs/plans/one-page-task-and-agent.md), its version and view kept.
+        const tab = /^\/t\/([A-Za-z0-9._~%-]{1,200})\?(?:version=[A-Za-z0-9._~%-]{1,200}&)?tab=result&run=([0-9]{1,15})(?:&section=(?:summary|changes|checks))?$/.exec(raw);
+        if (tab !== null && Number(tab[2]) === runId && tasks.some(task => tab[1] === encodeURIComponent(task)))
+            return raw;
     }
     return `/r/${runId}`;
 }
@@ -240,6 +244,8 @@ export const RESULT_REVIEW_SCRIPT = String.raw `
   var user=panel?panel.getAttribute('data-result-user')||'':'';
   var task=panel?panel.getAttribute('data-result-task')||'':'';
   var run=panel?panel.getAttribute('data-result-run')||'':'';
+  // The address parameter that holds the result's own view: 'tab' on its page, 'section' on a task page's Result tab.
+  var viewParam=panel&&panel.getAttribute('data-result-param')==='section'?'section':'tab';
   var draftPrefix='standing-orders:review-draft:',scrollPrefix='standing-orders:result-scroll:';
   var day=86400000,storage=true,rememberPosition=null;
   function read(key){try{return JSON.parse(sessionStorage.getItem(key)||'null');}catch(e){return null;}}
@@ -262,7 +268,7 @@ export const RESULT_REVIEW_SCRIPT = String.raw `
       tab.addEventListener('click',function(ev){
         if(ev.metaKey||ev.ctrlKey||ev.shiftKey||ev.altKey||ev.button!==0)return;
         ev.preventDefault();var name=tab.getAttribute('data-result-tab');show(name);
-        try{var url=new URL(location.href);url.searchParams.set('tab',name);url.hash='';history.replaceState(history.state,'',url.toString());}catch(e){}
+        try{var url=new URL(location.href);url.searchParams.set(viewParam,name);url.hash='';history.replaceState(history.state,'',url.toString());}catch(e){}
         if(rememberPosition)rememberPosition();
       });
       tab.addEventListener('keydown',function(ev){
@@ -383,7 +389,7 @@ export const RESULT_REVIEW_SCRIPT = String.raw `
   // view the URL now names.
   var returnKey=scrollPrefix+user+':'+task+':return';
   function scrollKeyFor(){var url=null;try{url=new URL(location.href);}catch(e){}
-    return scrollPrefix+user+':'+task+':'+(url?(url.searchParams.get('result')||run)+':'+(url.searchParams.get('tab')||'summary'):run);}
+    return scrollPrefix+user+':'+task+':'+(url?(url.searchParams.get('result')||run)+':'+(url.searchParams.get(viewParam)||'summary'):run);}
   // Once a navigation has begun (pageswap / beforeunload) the document's
   // scroll is no longer the reader's — a cross-document transition can
   // move it to the top while it is captured — so remembering stops.

package/dist/retention-ui.js

@@ -3,7 +3,7 @@
  * the next daily sweep would remove. An instance operator's page; changes
  * take a step-up.
  */
-import { html, postForm } from "./html.js";
+import { html, postForm, reauth } from "./html.js";
 import { bytesWords } from "./storage.js";
 import { RETENTION_KINDS, countWords, periodChoices, periodLabel } from "./retention.js";
 export const RETENTION_CSS = `.retention{max-width:720px;min-width:0}.retention-next{margin:0 0 16px}` +
@@ -31,5 +31,5 @@ export function retentionHtml(view, notice) {
         return html `<div class="kind" data-kind="${kind}"><label class="name" for="keep-${kind}">${label}</label><p class="meta">${detail}</p><select id="keep-${kind}" name="${kind}">${options}</select></div>`;
     });
     const last = view.lastSweep === null ? "" : ` Last sweep ${view.lastSweep.slice(0, 10)}.`;
-    return html `<article class="retention">${note}<p class="retention-next" data-retention-next>${nextWords(view)}${last}</p>${postForm("/settings/retention", html `${rows}<label class="step-up">Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label><button type="submit">Save</button>`)}<p class="meta">Never removed: the action ledger, and anything a task still needs (unfinished tasks, results Ready for review, anything on hold).</p></article>`;
+    return html `<article class="retention">${note}<p class="retention-next" data-retention-next>${nextWords(view)}${last}</p>${postForm("/settings/retention", html `${rows}${reauth(html `<label class="step-up">Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label>`)}<button type="submit">Save</button>`)}<p class="meta">Never removed: the action ledger, and anything a task still needs (unfinished tasks, results Ready for review, anything on hold).</p></article>`;
 }

package/dist/retention.js

@@ -24,6 +24,10 @@ import { RETENTION_NOTE } from "./evidence.js";
 import { COMPLETION_ACTION } from "./result-completion.js";
 import { bytesWords, treeBytes } from "./storage.js";
 import { RETENTION_DAYS, retentionDaysSchema, retentionKindSchema } from "./contracts/retention.js";
+/** A personal lead-queue row the sweep keeps (with its message): one still waiting, running or uncertain, and any of a
+ * conversation that is still open — its request id is the tombstone that stops a removed message being sent again. */
+const KEPT_QUEUE_ROW = (message) => `lead_queue lq WHERE lq.message = ${message}
+  AND (lq.status IN ('queued', 'running', 'uncertain') OR EXISTS (SELECT 1 FROM lead_session ls WHERE ls.id = lq.session AND ls.ended_at IS NULL))`;
 const RETENTION_TABLE = (name) => `
 CREATE TABLE IF NOT EXISTS ${name} (
   kind       TEXT PRIMARY KEY CHECK (kind IN ('evidence', 'checkouts', 'chat', 'notifications')),
@@ -177,6 +181,7 @@ export function retentionPlan(store, evidenceRoot, now, periods = store.retentio
         const rows = db.prepare(`SELECT m.id AS id, length(m.text) + COALESCE(length(m.activity), 0) + 64 AS bytes FROM lead_message m JOIN lead_thread th ON th.id = m.thread
       WHERE m.created_at < ?
         AND NOT EXISTS (SELECT 1 FROM team_message tm WHERE tm.message = m.id AND tm.status IN ('queued', 'running', 'uncertain'))
+        AND NOT EXISTS (SELECT 1 FROM ${KEPT_QUEUE_ROW("m.id")})
         AND NOT EXISTS (SELECT 1 FROM mate_turn turn WHERE turn.id = m.turn AND turn.state IN ('queued', 'running'))
         AND NOT (th.scope_kind = 'task' AND NOT EXISTS (SELECT 1 FROM task_ref r WHERE r.external_id = th.scope_key AND ${finishedTask("r")}))
       ORDER BY m.id LIMIT ?`).all(cutoff(now, periods.chat), SWEEP_BATCH + 1);
@@ -263,14 +268,18 @@ export function sweepRetention(store, evidenceRoot, now, actor = "worker") {
         }
         if (periods.chat !== null) {
             const team = db.prepare("DELETE FROM team_message WHERE message = ? AND status NOT IN ('queued', 'running', 'uncertain')");
-            const message = db.prepare("DELETE FROM lead_message WHERE id = ? AND NOT EXISTS (SELECT 1 FROM team_message WHERE message = ?)");
+            const message = db.prepare(`DELETE FROM lead_message WHERE id = ? AND NOT EXISTS (SELECT 1 FROM team_message WHERE message = ?)
+        AND NOT EXISTS (SELECT 1 FROM ${KEPT_QUEUE_ROW("lead_message.id")})`);
             const asked = db.prepare("SELECT turn FROM lead_message WHERE id = ? AND role = 'assistant' AND turn IS NOT NULL");
+            const searchCopy = db.prepare("DELETE FROM memory_search WHERE kind = 'conversation' AND ref = ?");
             // The lead's question goes with the reply that asked it; its buttons then say it expired.
             const ask = db.prepare("DELETE FROM lead_ask WHERE turn = ? AND NOT EXISTS (SELECT 1 FROM lead_message WHERE turn = ? AND role = 'assistant')");
             for (const one of plan.items.chat) {
                 team.run(one.id);
                 const turn = asked.get(one.id)?.["turn"];
                 if (Number(message.run(one.id, one.id).changes) === 1) {
+                    // Its search copy goes with it (search never shows words the store no longer keeps).
+                    searchCopy.run(`message:${one.id}`);
                     done.chat.count++;
                     done.chat.bytes += one.bytes;
                     if (turn !== undefined && turn !== null)

package/dist/run-efficiency.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 type { Run, Store } from "./store.js";
+import type { LiveActivityKind, LiveRecord } from "./live-records.js";
+export declare const RUN_EFFICIENCY_VERSION = 3;
+/** Budgets for one derivation: never more than the live file's own cap, and a bounded record count. */
+export declare const EFFICIENCY_READ_BYTES: number;
+export declare const EFFICIENCY_RECORDS = 20000;
+export type StepsState = "complete" | "truncated" | "expired" | "absent";
+export type RunEfficiency = {
+    version: number;
+    /** Waiting to start (claimed → provider started) and the agent (provider started → finished); null when unrecorded. */
+    time: {
+        waitMs: number | null;
+        agentMs: number | null;
+    };
+    turns: number | null;
+    /** Tokens in counts everything the model read (cached included); `cacheShare` is read-from-cache ÷ that, 0–1. */
+    usage: {
+        in: number | null;
+        out: number | null;
+        cacheRead: number | null;
+        cacheWrite: number | null;
+        cacheShare: number | null;
+        provider: string;
+        model: string | null;
+    };
+    steps: {
+        state: StepsState;
+        reason: string | null;
+        total: number | null;
+        failed: number | null;
+        unknownDuration: number | null;
+        byKind: Partial<Record<LiveActivityKind, number>>;
+        longest: {
+            kind: LiveActivityKind;
+            ms: number;
+        }[];
+        /** Repeated activity: the same step (kind and its full recorded input) at least three times. Null when the inputs
+         * can't be compared (command detail off, or a target hidden or shortened) — said, never guessed. */
+        repeats: {
+            kind: LiveActivityKind;
+            count: number;
+        }[] | null;
+        repeatsReason: string | null;
+    };
+};
+/** Tokens and cache from the provider's own usage report, read per provider (their counts mean different things). */
+export declare function usageOf(run: Pick<Run, "provider" | "model" | "tokensIn" | "tokensOut"> & {
+    usageJson?: string | null;
+}): RunEfficiency["usage"];
+/** 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 declare function stepsOf(records: Iterable<LiveRecord>, truncated: string | null, measured?: boolean): RunEfficiency["steps"];
+/** Derive a finished run's How it ran from its records. */
+export declare function deriveRunEfficiency(run: Run & {
+    usageJson?: string | null;
+}, evidenceRoot: string, now: Date): RunEfficiency;
+/**
+ * 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.
+ */
+export declare function runEfficiencyOf(store: Store, evidenceRoot: string, runId: number, now: Date): RunEfficiency | null;