toolroll 0.9.103 → 0.9.105

package/dist/spend.js

@@ -1,27 +1,18 @@
 import { SUBSCRIPTION_CAPABLE, readAuthMode } from "./keys.js";
-/** How a provider's work is billed right now: an API key when Toolroll is set to use one, or when the CLI
- * itself was last seen billing a key (a key helper, a Console login, Bedrock or Vertex, `codex login --with-api-key`);
- * otherwise its plan. `db` supplies what was seen (provider_account); without it, the setting alone. */
 export function billingOf(provider, db) {
     const base = provider.replace(/-(subscription|api)$/, "");
     if (provider.endsWith("-api"))
         return "api-key";
     const setting = provider.endsWith("-subscription") ? "subscription"
-        // An ACP agent's work is metered until its billing declaration says otherwise (that is per run, not here).
         : Object.hasOwn(SUBSCRIPTION_CAPABLE, provider) ? (readAuthMode(provider) === "subscription" ? "subscription" : "api-key") : "api-key";
     if (setting === "api-key" || db === undefined)
         return setting;
     return seenBilling(db, base) ?? setting;
 }
-/** How a provider's CLI was last seen billing (provider_account), or null. */
 export function seenBilling(db, provider) {
     const row = db.prepare("SELECT billing FROM provider_account WHERE provider = ?").get(provider);
     return row?.["billing"] === "api-key" || row?.["billing"] === "subscription" ? row["billing"] : null;
 }
-/** How a Claude turn was really billed, from its own stream. Only a plan reports its usage windows (Claude Code 2.1
- * does on every turn), so that is the one sign of the plan; a named key source or a cloud model id (Bedrock, Vertex)
- * is a key, and so is "none" without windows (a gateway's bearer token or a cloud provider says "none" too). Null when
- * the stream said nothing. */
 export function claudeBillingFrom(seen) {
     if (seen.keySource !== null && seen.keySource !== "none")
         return "api-key";
@@ -31,14 +22,10 @@ export function claudeBillingFrom(seen) {
         return "subscription";
     return seen.keySource === "none" ? "api-key" : null;
 }
-/** How Claude bills on this computer when Toolroll gives it no key (subagent turns, drafts): as its keyless runs
- * were last seen, and its plan until one has been. */
 export function claudeMachineBilling(db) {
     return seenBilling(db, "claude") ?? "subscription";
 }
-/** Providers whose own output says what a turn cost (Claude's total_cost_usd; OpenRouter's usage.cost). */
 const REPORTS_COST = new Set(["claude", "openrouter", "anthropic-api", "openrouter-api"]);
-/** Whether API work on this provider can be priced: it reports its cost, or the catalogue has its prices. */
 export function canPrice(db, provider) {
     return REPORTS_COST.has(provider) || ceilingPriceFor(db, provider) !== null;
 }
@@ -47,8 +34,6 @@ const catalogSource = (provider) => provider === "claude" || provider === "claud
     : provider === "codex" || provider === "codex-subscription" ? "codex"
         : provider === "gemini" ? "gemini"
             : provider === "openrouter" || provider === "openrouter-api" ? "openrouter" : null;
-/** A model's catalogue price (US dollars per million tokens), or null when the catalogue doesn't list one. A
- * Claude short name ("sonnet") is priced as the newest of its family, as the Claude CLI runs it. */
 export function priceFor(db, provider, model) {
     const source = catalogSource(provider);
     if (source === null || model === null || model === "" || model === "default")
@@ -61,8 +46,6 @@ export function priceFor(db, provider, model) {
     return priced(db.prepare(`SELECT id, input_usd, output_usd FROM model_seen WHERE source = 'claude' AND id LIKE ? AND last_seen_at = (SELECT MAX(last_seen_at) FROM model_seen WHERE source = 'claude')
     ORDER BY COALESCE(released_at, '') DESC, id DESC LIMIT 1`).get(`claude-${model}-%`));
 }
-/** The provider's highest listed price, for API work whose model the catalogue doesn't list (or that ran the CLI's
- * default): a budget that stops work must never see it as free. */
 export function ceilingPriceFor(db, provider) {
     const source = catalogSource(provider);
     if (source === null)
@@ -72,8 +55,6 @@ export function ceilingPriceFor(db, provider) {
     return row === undefined || row["input_usd"] == null || row["output_usd"] == null ? null
         : { inputUsd: Number(row["input_usd"]), outputUsd: Number(row["output_usd"]), model: "highest listed price" };
 }
-/** What a piece of work cost, in micro-dollars: nothing on a subscription; otherwise reported, or tokens at the
- * catalogue price (usd per million tokens times tokens is micro-dollars), or unpriced. */
 export function priceWork(db, work) {
     if (work.billing === "subscription")
         return { microusd: 0, source: "subscription", price: null };
@@ -145,26 +126,20 @@ CREATE INDEX IF NOT EXISTS chat_turn_created ON chat_turn (created_at);
 CREATE INDEX IF NOT EXISTS mate_turn_created ON mate_turn (created_at);
 CREATE INDEX IF NOT EXISTS subagent_turn_at ON subagent_turn (at);
 `;
-/** The calendar month (UTC) `at` falls in: [start, end) as ISO strings, and its name (YYYY-MM). */
 export function monthOf(at) {
     const from = new Date(Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), 1));
     const to = new Date(Date.UTC(at.getUTCFullYear(), at.getUTCMonth() + 1, 1));
     return { from: from.toISOString(), to: to.toISOString(), name: from.toISOString().slice(0, 7) };
 }
-/** A month by its name (YYYY-MM), or null. */
 export function monthNamed(name) {
     if (name === null || !/^\d{4}-(0[1-9]|1[0-2])$/.test(name))
         return null;
     return monthOf(new Date(`${name}-01T00:00:00.000Z`));
 }
-/** The subagent behind a filing: tasks a subagent files are filed as its name ("Maya (AI)", from its soul file), in
- * its project. A later subagent with the same name and project wins, as it would read on the card. */
-/** A subagent's name as its soul file gives it ("Maya"), or null. */
 const soulName = (soul) => {
     const front = /^---\s*\n([\s\S]*?)\n---/.exec(String(soul ?? ""));
     return front === null ? null : /^name:\s*(.+?)\s*$/m.exec(front[1])?.[1] ?? null;
 };
-/** Every subagent's name by id (its handle when its soul file names none). */
 export function subagentNames(db) {
     return new Map(db.prepare("SELECT id, handle, soul FROM subagent").all().map(row => [Number(row["id"]), soulName(row["soul"]) ?? String(row["handle"])]));
 }
@@ -177,8 +152,6 @@ export function subagentFilers(db) {
     }
     return (repo, filedBy, kind) => kind !== "subagent" || repo === null || filedBy === null ? null : byName.get(`${repo}\n${filedBy}`) ?? null;
 }
-/** Who a task's work counts toward: its own filer, or, for a revision filed by automation (an automatic repair), the
- * filer of the task it revises, up its ancestry (bounded). */
 export function filersOf(db) {
     const memo = new Map();
     const read = db.prepare("SELECT id, backend, repo, filed_by, filed_by_kind, revision_of FROM task_ref WHERE id = ?");
@@ -199,8 +172,6 @@ export function filersOf(db) {
         return found;
     };
 }
-/** Every piece of spend in [from, to): runs (by when they started), subagent turns and chat turns. `modeOf` says how
- * a provider bills when a record doesn't (older rows): its current login or key. */
 export function spendItems(db, from, to, modeOf = provider => billingOf(provider, db)) {
     const subagentOf = subagentFilers(db);
     const filerOf = filersOf(db);
@@ -216,7 +187,6 @@ export function spendItems(db, from, to, modeOf = provider => billingOf(provider
             : row["auth_mode"] === "subscription" || row["auth_mode"] === "api-key" ? row["auth_mode"] : modeOf(provider);
         const settled = row["source"] != null;
         const priced = settled ? null : priceWork(db, { provider, model: text(row["model"]), costUsd: count(row["cost_usd"]), tokensIn: count(row["tokens_in"]), tokensOut: count(row["tokens_out"]), billing });
-        // Most tasks name their filer; only an automation-filed revision walks to its source's.
         const filer = row["filed_by"] == null && row["revision_of"] != null ? filerOf(Number(row["task_ref"]))
             : { repo: text(row["repo"]), filedBy: text(row["filed_by"]), kind: text(row["filed_by_kind"]) };
         const kind = filer.kind;
@@ -230,8 +200,6 @@ export function spendItems(db, from, to, modeOf = provider => billingOf(provider
             taskId: String(row["task"]), runId: Number(row["id"]), authMode: billing,
         };
     });
-    // A subagent's own turns get no key from Toolroll (subagents.ts claudeTurnRunner): they bill as this computer's
-    // Claude sign-in was seen billing when the turn ran (a plan, or a Console login, key helper or gateway).
     for (const row of db.prepare(`SELECT t.at, t.subagent, t.model, t.cost_usd, t.tokens_in, t.tokens_out, t.billing, m.repo FROM subagent_turn t JOIN subagent m ON m.id = t.subagent
       WHERE t.at >= ? AND t.at < ? ORDER BY t.id`).all(from, to)) {
         const billing = row["billing"] === "api-key" ? "api-key" : "subscription";
@@ -240,8 +208,6 @@ export function spendItems(db, from, to, modeOf = provider => billingOf(provider
             subagent: Number(row["subagent"]), provider: "claude", model: text(row["model"]),
             tokensIn: count(row["tokens_in"]), tokensOut: count(row["tokens_out"]), taskId: null, runId: null, authMode: billing });
     }
-    // A chat turn that mirrors a project chat's turn is that turn: counted once, as the project chat's. A task's chat
-    // counts toward the task's project.
     for (const row of db.prepare(`SELECT created_at AS at, approver, provider, model, settled_microusd, tokens_in, tokens_out, NULL AS project
       FROM chat_turn WHERE mate_turn IS NULL AND created_at >= ? AND created_at < ?
     UNION ALL SELECT t.created_at, t.approver, COALESCE((SELECT c.provider FROM chat_turn c WHERE c.mate_turn = t.id ORDER BY c.id LIMIT 1), 'lead'),
@@ -255,14 +221,12 @@ export function spendItems(db, from, to, modeOf = provider => billingOf(provider
             project: text(row["project"]), person: text(row["approver"]), subagent: null, provider, model: text(row["model"]),
             tokensIn: count(row["tokens_in"]), tokensOut: count(row["tokens_out"]), taskId: null, runId: null, authMode: subscription ? "subscription" : "api-key" });
     }
-    // A flow's Claude drafts: like a subagent's turns, billed as the sign-in was.
     for (const row of db.prepare("SELECT at, kind, repo, provider, model, cost_usd, billing FROM side_spend WHERE at >= ? AND at < ? ORDER BY id").all(from, to)) {
         const billing = row["billing"] === "api-key" ? "api-key" : "subscription";
         const priced = priceWork(db, { provider: String(row["provider"]), model: text(row["model"]), costUsd: count(row["cost_usd"]), tokensIn: null, tokensOut: null, billing });
         items.push({ at: String(row["at"]), kind: "draft", microusd: priced.microusd, source: priced.source, project: text(row["repo"]), person: null, subagent: null,
             provider: String(row["provider"]), model: text(row["model"]), tokensIn: null, tokensOut: null, taskId: null, runId: null, authMode: billing });
     }
-    // A flow's Sort zone asks Jev on OpenRouter (the key's credit): what it cost is kept with its answer.
     for (const row of db.prepare(`SELECT fs.started_at AS at, json_extract(fs.decision_json, '$.cost') AS cost, json_extract(fs.decision_json, '$.model') AS model, f.repo
       FROM flow_step_run fs JOIN flow_card c ON c.id = fs.card JOIN flow f ON f.id = c.flow
       WHERE fs.kind = 'sort' AND fs.decision_json IS NOT NULL AND fs.started_at >= ? AND fs.started_at < ? ORDER BY fs.started_at`).all(from, to)) {
@@ -272,7 +236,6 @@ export function spendItems(db, from, to, modeOf = provider => billingOf(provider
     }
     return items;
 }
-/** Whether a piece of spend counts toward a budget. */
 export function countsToward(item, budget) {
     if (budget.scope === "installation")
         return true;
@@ -283,7 +246,6 @@ export function countsToward(item, budget) {
     return item.subagent !== null && String(item.subagent) === budget.key;
 }
 const PROVIDER_WORDS = { claude: "Claude", codex: "Codex", gemini: "Gemini", openrouter: "OpenRouter" };
-/** Why work waits on a budget, in words. */
 export function budgetHoldWords(hold, month, subagentName) {
     if (hold.over === null)
         return "";
@@ -292,7 +254,6 @@ export function budgetHoldWords(hold, month, subagentName) {
         ? `${label} budget can't price ${PROVIDER_WORDS[hold.unpricedProvider ?? ""] ?? hold.unpricedProvider} work on a key yet. Open Settings → Models to load prices`
         : `${label} budget is used up for ${month}`;
 }
-/** Each budget's month so far: what counted toward it, and how many pieces of work had no price. */
 export function budgetStates(budgets, items) {
     return budgets.map(budget => {
         const mine = items.filter(item => countsToward(item, budget));
@@ -301,7 +262,6 @@ export function budgetStates(budgets, items) {
             percent: Math.floor((spent / budget.limitMicrousd) * 100) };
     });
 }
-/** A budget in words: "The shop project's", "alex's", "Maya's (subagent)", "The whole installation's". */
 export function budgetLabel(budget, subagentName) {
     if (budget.scope === "installation")
         return "The whole installation's";

package/dist/sqlite-runtime.js

@@ -1,6 +1,4 @@
 import { createRequire } from 'node:module';
-/** Keep native SQLite out of import-only UI/module graphs. Load the real
- * driver only when a database operation needs it, as the main store does. */
 export function sqliteRuntime() {
     return createRequire(import.meta.url)('node:sqlite');
 }

package/dist/sqlite-telemetry.js

@@ -1,5 +1,4 @@
 const states = new WeakMap();
-/** One observation for the entire bounded BEGIN retry, including a failed acquisition. */
 export function measureWriteWait(db, body) {
     const state = states.get(db);
     if (!state || state.measuringWait)
@@ -14,10 +13,6 @@ export function measureWriteWait(db, body) {
         state.telemetry.writeWait.observe((state.telemetry.clock() - started) / 1000);
     }
 }
-/** Preserve SQLite calls, timeouts and transaction semantics. No SQL or parameters leave this wrapper.
- * Native SQLite does not expose busy-handler time for autocommit writes: report their whole duration separately.
- * Runtime explicit IMMEDIATE/EXCLUSIVE transactions report acquisition and hold; startup migrations are excluded.
- */
 export function instrumentDatabase(db, telemetry) {
     const state = { telemetry, measuringWait: false };
     let heldAt = null;
@@ -76,15 +71,11 @@ export function instrumentDatabase(db, telemetry) {
             finish();
         } },
     };
-    // Store.handle also exposes native extensions (for example scalar functions used by work summaries).
-    // Preserve their receivers and getters instead of narrowing the live connection to the minimal test interface.
     const wrapped = preservingNative(db, methods);
     states.set(wrapped, state);
     return wrapped;
 }
 function preservingNative(native, methods) {
-    // Overrides belong to the facade, so a test spy or caller replacing prepare/run never mutates the
-    // native method that the timed implementation calls (and cannot recurse back into itself).
     return new Proxy(methods, {
         get(target, property) {
             if (Object.hasOwn(target, property))

package/dist/sso-settings.js

@@ -1,9 +1,3 @@
-/**
- * Settings → Sign-in (v100): the identity provider this installation trusts,
- * kept in `sign-in.json` beside the database (0600) with its client secret,
- * never in the database. Group rules are ordered: a person's first matching
- * group sets their role and projects.
- */
 import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 const FILE = "sign-in.json";
@@ -17,7 +11,6 @@ const isAddress = (value) => {
         return false;
     }
 };
-/** A name for the button from the issuer, when none is given. */
 export function providerLabel(issuer) {
     const host = (() => { try {
         return new URL(issuer).hostname;
@@ -52,11 +45,6 @@ export function readSsoSettings(dir) {
         return null;
     }
 }
-/**
- * Save what the form sent. The client secret is kept when the field is left
- * blank; rules come as rows (group, role, projects), blank groups dropped.
- * `projects` for a row is "all" or the project paths chosen.
- */
 export function saveSsoSettings(dir, form, previous) {
     const issuer = form.issuer.trim().replace(/\/+$/, "");
     if (!isAddress(issuer))
@@ -94,7 +82,6 @@ export function saveSsoSettings(dir, form, previous) {
 export function removeSsoSettings(dir) {
     rmSync(join(dir, FILE), { force: true });
 }
-/** What changed, for the ledger: never the secret itself, only that it changed. */
 export function ssoChangeWords(before, after) {
     const rules = (settings) => settings.rules.map(rule => `${rule.group}: ${rule.role}${rule.projects === "all" ? ", all projects" : rule.projects.length === 0 ? ", no projects" : `, ${rule.projects.length} project${rule.projects.length === 1 ? "" : "s"}`}`).join("; ");
     const words = (settings) => settings === null ? "off" : `${settings.label} (${settings.issuer}) · ${rules(settings)} · passwords: ${settings.passwords}`;

package/dist/sso-ui.js

@@ -1,9 +1,7 @@
 import { html, joinHtml, postForm } from "./html.js";
 import { acts, btn, codeLine, disclose, formRow, infoLine, input, note, notice, radios, select, settingsSection } from "./server/kit.js";
 import { kitSectionForm, SECRET_OPT_OUTS } from "./settings-kit.js";
-/** The old card look; the page is built from the kit now. Kept for chrome.ts, which still concatenates it. */
 export const SSO_CSS = "";
-/** Whether an address only this computer can open (localhost, 127.x, ::1): a provider can't send people back to it. */
 export function loopbackAddress(address) {
     let host;
     try {

package/dist/staged-runtimes.js

@@ -1,13 +1,3 @@
-/**
- * Staged runtimes (`staged-upgrades/`): each deploy (scripts/deploy-browser.mjs, `browser-*`) and each `toolroll
- * update` (`release-*`) stages a whole runtime, a few hundred MB with its database backup. Oct 4: 9 of them, 2.2 GB.
- *
- * Kept: the current runtime (one the service, a `toolroll` command or this process runs from), the one before it
- * (its journal's way back), the newest stage, a deploy or update still under way (no finished journal) for a week,
- * and a stage holding a database a failed update kept aside. Everything else of those two kinds goes — after a deploy
- * and in the plane's daily storage sweep. `rollback-*` records and anything else in the folder are never touched.
- * With no current runtime found, nothing goes: which one is safe to remove is then unknown.
- */
 import { lstatSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
@@ -16,10 +6,8 @@ import { isDeployed } from "./deploy-phase.js";
 import { quarantine, quarantineEntries, claimQuarantine, releaseQuarantine, restoreQuarantine, deleteQuarantineSync } from "./sweep-quarantine.js";
 import { processCensus } from "./run-closeout.js";
 const DAY_MS = 86_400_000;
-/** A deploy or update that never finished keeps its stage this long (it may be resumed). */
 export const UNFINISHED_KEEP_MS = 7 * DAY_MS;
 export const STAGED_FOLDER = "staged-upgrades";
-/** The canonical path, even of something that doesn't exist (yet): its nearest existing folder, resolved, plus the rest. */
 function real(path) {
     let at = resolve(path);
     const rest = [];
@@ -27,7 +15,7 @@ function real(path) {
         try {
             return join(realpathSync(at), ...rest.reverse());
         }
-        catch { /* not there */ }
+        catch { }
         const up = dirname(at);
         if (up === at)
             break;
@@ -45,7 +33,6 @@ const readJson = (file) => {
         return null;
     }
 };
-/** The `browser-*` and `release-*` stages: real folders directly in staged-upgrades, newest first. */
 export function stagedRuntimes(stateDir) {
     const root = real(join(stateDir, STAGED_FOLDER));
     let names = [];
@@ -97,15 +84,9 @@ function readStage(path, name, fallbackAt) {
     }
     return { path, name, at, finished, prior, keptAside };
 }
-/** Where the CLI links usually are (link.ts, an npm or Homebrew global), on PATH or not: a launchd worker's PATH is short. */
 function linkFolders(home) {
     return [join(home, ".local", "bin"), join(home, "bin"), "/usr/local/bin", "/opt/homebrew/bin"];
 }
-/**
- * Paths a runtime may be running from: the launchd services' definitions, every `toolroll` (or older
- * `standing-orders`) command on PATH, in the usual link folders or under nvm (a link counts by its target), this
- * process, and `extra`.
- */
 export function runtimesInUse(extra = [], home = homedir(), path = process.env["PATH"] ?? "", stateDir) {
     const found = [...extra];
     const agents = join(home, "Library", "LaunchAgents");
@@ -115,27 +96,26 @@ export function runtimesInUse(extra = [], home = homedir(), path = process.env["
                 found.push(match[1]);
         }
     }
-    catch { /* no launch agents here */ }
+    catch { }
     const commands = [...new Set([...path.split(":").filter(Boolean), ...linkFolders(home)])].flatMap(dir => ["toolroll", "standing-orders"].map(bin => join(dir, bin)));
     try {
         for (const version of readdirSync(join(home, ".nvm", "versions", "node")))
             for (const bin of ["toolroll", "standing-orders"])
                 commands.push(join(home, ".nvm", "versions", "node", version, "bin", bin));
     }
-    catch { /* no nvm */ }
+    catch { }
     for (const command of commands) {
         try {
             lstatSync(command);
             found.push(command);
         }
         catch {
-            continue; /* not there */
+            continue;
         }
-        // A link counts by its target, even one that doesn't resolve now.
         try {
             found.push(resolve(dirname(command), readlinkSync(command)));
         }
-        catch { /* not a link */ }
+        catch { }
     }
     if (process.argv[1] !== undefined)
         found.push(process.argv[1]);
@@ -143,9 +123,6 @@ export function runtimesInUse(extra = [], home = homedir(), path = process.env["
         found.push(...runtimeScriptPaths(stateDir));
     return found;
 }
-/** Retain only recognized Toolroll entry scripts in candidate stages, never complete argv. ps is asked only
- * for Node/Toolroll processes; /proc supplies NUL-separated argv on Linux. Fail closed with a fixed message,
- * since an execFileSync exception can otherwise contain private argument text in stdout/stderr. */
 export function runtimeScriptPaths(stateDir, onlyPids, observations = {}) {
     const stages = stagedRuntimes(stateDir);
     const trash = quarantineEntries(real(join(stateDir, STAGED_FOLDER)));
@@ -161,8 +138,6 @@ export function runtimeScriptPaths(stateDir, onlyPids, observations = {}) {
     const collect = (args) => {
         for (const base of bases) {
             const escaped = base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-            // All supported installs: runtime/dist, runtime/node_modules/{toolroll,standing-orders}/dist,
-            // or dist directly under a release stage. Matching a known base handles spaces without logging argv.
             const pattern = new RegExp(`(?:^|[\\s\\0"'])(${escaped}/(?:runtime/)?(?:node_modules/(?:toolroll|standing-orders)/)?dist/(?:cli|bin|storage-sweep-child)\\.js)(?=$|[\\s\\0"'])`, "g");
             for (const match of args.matchAll(pattern))
                 scripts.add(match[1]);
@@ -194,7 +169,6 @@ export function runtimeScriptPaths(stateDir, onlyPids, observations = {}) {
                     }));
                 }
                 catch (error) {
-                    // ps exits 1 when every requested process has just gone. Any other failure keeps stages.
                     if (error.status !== 1)
                         throw error;
                 }
@@ -206,7 +180,6 @@ export function runtimeScriptPaths(stateDir, onlyPids, observations = {}) {
     }
     return [...scripts];
 }
-/** The stage `path` lies in, or null. */
 function stageOf(stages, path) {
     if (path === null || path === undefined || path === "")
         return null;
@@ -219,12 +192,9 @@ function stageOf(stages, path) {
     }
     return null;
 }
-/** What stays and what goes now, and why. */
 export function stagePlan(stateDir, inUse, now) {
     const stages = stagedRuntimes(stateDir);
     const trash = quarantineEntries(real(join(stateDir, STAGED_FOLDER)));
-    // A renamed stage still has its original identity for current/previous/newest protection, including a CLI
-    // symlink switched just before rename. Partial-delete journals retain this identity for the next retry.
     for (const one of trash)
         if (!stages.some(stage => stage.path === one.original)) {
             const facts = one.journal.deleting ? one.journal.data : readStage(one.path, one.journal.name, one.journal.data.at);
@@ -258,10 +228,6 @@ export function stagePlan(stateDir, inUse, now) {
     }
     return { keep: [...keep].map(([path, why]) => ({ path, why })), go: stages.filter(one => !keep.has(one.path)), refused: null };
 }
-/**
- * Remove the stages that go. Right before each goes, the plan is made again (what's in use now), nothing live may use
- * it (`spare`, storage-sweep.ts) and the stage must still be a real folder directly in staged-upgrades.
- */
 export function pruneStagedRuntimes(stateDir, now, options = {}) {
     const inUse = options.inUse ?? (() => runtimesInUse([], undefined, undefined, stateDir));
     const root = real(join(stateDir, STAGED_FOLDER));

package/dist/steer-capabilities.js

@@ -1,5 +1,4 @@
 const ROLE_WORDS = { planner: "planner", scout: "scout", reviewer: "reviewer" };
-/** The attempt a run belongs to: up its parents while they share its claim (a protocol repair, a planner's correction). */
 function ownerOf(store, runId) {
     let at = store.getRun(runId);
     for (let depth = 0; at !== null && at.parentRun !== null && depth < 16; depth++) {
@@ -10,27 +9,24 @@ function ownerOf(store, runId) {
     }
     return at?.id ?? runId;
 }
-/** Whether a Stop of this run would be accepted now — requestRunStop's own rules, read without writing. */
 function stoppable(store, runId, now) {
     const run = store.getRun(runId);
     if (run === null)
         return false;
     if (store.stopOf(runId) !== null)
-        return true; // asking again is the same stop
+        return true;
     if (run.outcome !== null)
         return false;
     if (run.role !== "reviewer" && store.currentLiveLease(run.taskRef, now) !== run.leaseId)
         return false;
     return store.publicationForRun(runId) === null;
 }
-/** The capability of this exact run, now. Null when it is not running. */
 export function steerCapabilityOf(store, runId, now) {
     const run = store.getRun(runId);
     if (run === null || run.outcome !== null || run.finishedAt !== null)
         return null;
     const owner = ownerOf(store, run.id);
     const stopOf = (label) => stoppable(store, owner, now) ? { run: owner, label } : null;
-    // A child of an attempt (a protocol repair, a planner's correction) is part of it: no notes, and Stop names the owner.
     if (owner !== run.id) {
         return { send: null, pause: false, stop: stopOf("Stop this attempt"),
             words: run.role === "repair" ? "It's repairing its handoff and reads no notes now. Stop this attempt to change its course."
@@ -48,12 +44,10 @@ export function steerCapabilityOf(store, runId, now) {
         return { send: "live", pause: true, stop: stopOf("Stop"), words: "Notes reach the agent right away." };
     if (store.steeringLiveBuild(run.taskRef, now) === run.id)
         return { send: "mailbox", pause: false, stop: stopOf("Stop"), words: "It reads notes at its next check." };
-    // Not yet at work: a note filed now is in its brief when it starts. Past its mailbox: none reaches this attempt.
     const state = store.handle.prepare("SELECT phase, steer_opened_at FROM run WHERE id = ?").get(run.id);
     const starting = state !== undefined && state["phase"] == null && state["steer_opened_at"] == null && store.currentLiveLease(run.taskRef, now) === run.leaseId;
     if (starting)
         return { send: "mailbox", pause: false, stop: stopOf("Stop"), words: "It reads notes when it starts working." };
-    // Never given a mailbox (steering off for it), or past it.
     if (state?.["steer_opened_at"] == null)
         return { send: null, pause: false, stop: stopOf("Stop"), words: "It doesn't read notes; anything you send waits for the next attempt." };
     return { send: null, pause: false, stop: stopOf("Stop"), words: "It has stopped reading notes; anything you send now waits for the next attempt." };

package/dist/steer-controls.js

@@ -1,21 +1,12 @@
-/**
- * The composer's facts for one running attempt, for whichever surface shows it (the Agents board, a task page, a flow
- * card's task): what the attempt takes (steer-capabilities.ts), and the exact run each form names. One helper, so every
- * surface offers the same acts for the same attempt (docs/plans/agents-cockpit.md §4).
- */
 import { randomUUID } from "node:crypto";
 import { steerCapabilityOf } from "./steer-capabilities.js";
 const taskHrefOf = (taskId) => `/t/${encodeURIComponent(taskId)}`;
-/** The attempt running for a task now: one under the task's live claim (any role; a child shows as its owner's own),
- * or a review, which runs under its own claim (requestRunStop exempts it from the task's). */
 export function liveAttemptOf(store, taskRef, now) {
     const lease = store.currentLiveLease(taskRef, now);
     const row = store.handle.prepare(`SELECT id FROM run WHERE task_ref = ? AND outcome IS NULL AND finished_at IS NULL
       AND (lease_id = ? OR role = 'reviewer') ORDER BY (lease_id = ?) DESC, id DESC LIMIT 1`).get(taskRef, lease ?? "", lease ?? "");
     return row === undefined ? null : Number(row["id"]);
 }
-/** One running attempt's composer: the note's target (null: it takes none now) and its controls. Null when it is not
- * running, or this person may not act on it (a viewer, the demo). */
 export function steerControlsFor(store, taskId, runId, now, canAct) {
     if (!canAct || store.isDemo())
         return null;
@@ -26,7 +17,6 @@ export function steerControlsFor(store, taskId, runId, now, canAct) {
     const pause = capability.pause ? (() => {
         const state = store.livePauseOf(runId);
         const until = state?.pausedAt == null || state.limitMs === null ? null : new Date(Date.parse(state.pausedAt) + state.limitMs).toISOString();
-        // Each form its own request id, so a repeated submit is the same request and two forms never collide.
         return { action: `${href}/pause`, run: runId, state: state?.state ?? null, requests: [`web-${randomUUID()}`, `web-${randomUUID()}`, `web-${randomUUID()}`], until };
     })() : null;
     return {

package/dist/steer-live.js

@@ -1,35 +1,9 @@
-/**
- * Live steering's dispatcher: the builder runs one tick every half second
- * while its agent works, independent of the 60-second lease pulse.
- *
- * - Every provider: what the agent moved to handled/ is recorded read, and a
- *   note filed since the last tick is written to the steering folder at once
- *   (steer-mailbox.ts). Codex reads it there.
- * - A Claude build with live input (live-input.ts) also gets each note on
- *   stdin as soon as it is in the folder, each Pause as an interrupt and
- *   each Resume as a short continue frame — pauses first, so Pause and steer
- *   stops the turn before the note arrives.
- * - A note the agent has not moved to handled/ is followed up every 90
- *   seconds, up to 3 times, with a short reminder naming its file — never
- *   the note again, so an agent that already acted on it does not redo the
- *   work; 90 seconds after the last one it reads Not picked up. A paused
- *   session is not reminded: only a new note or Resume continues it. Moving
- *   the file is still the only proof of reading, and a note still unread
- *   when the attempt ends reaches the next attempt's brief as before.
- *
- * Every step is bookkeeping: a failure waits for the next tick and never
- * touches the build.
- */
 import { randomUUID } from "node:crypto";
 import { fence } from "./brief-fence.js";
 import { pulseSteerMailbox, STEER_HANDLED, steerNoteName } from "./steer-mailbox.js";
-/** How often the dispatcher looks: a note reaches a running Claude build within about this long. */
 export const LIVE_TICK_MS = 500;
-/** How long an unread note waits before it is sent again. */
 export const LIVE_RESEND_MS = 90_000;
-/** How many times an unread note is sent again before it reads Not picked up. */
 export const LIVE_RESENDS = 3;
-/** The stdin copy of a note: the same fenced text and key as its file, and what to do with the file. */
 export function liveNoteText(box, number, note) {
     const name = steerNoteName(number);
     return [
@@ -38,12 +12,10 @@ export function liveNoteText(box, number, note) {
         `Act on it within the agreed scope, under the brief's rules for steering notes, then move ${box.folder}/${name} into ${box.folder}/${STEER_HANDLED}/ — moving the file is how the operator learns you read it.`,
     ].join("\n");
 }
-/** A re-send: only the note's number and file, and what to do with it. The note itself was sent in full once. */
 export function liveReminderText(box, number) {
     const name = steerNoteName(number);
     return `Steering note ${number} is still unread: ${box.folder}/${name}. Act on it if you have not already, then move it into ${box.folder}/${STEER_HANDLED}/.`;
 }
-/** One tick. `agentRunning`: the agent process is up, so a note written now can be read. */
 export function tickLiveSteer(store, steer, now, agentRunning) {
     const { box, session } = steer;
     pulseSteerMailbox(store, box, now, agentRunning);
@@ -72,7 +44,6 @@ export function tickLiveSteer(store, steer, now, agentRunning) {
             continue;
         const first = note.liveSends === 0;
         if (!first) {
-            // A paused session waits for a new note; an old one sent again would continue it.
             if (session.paused)
                 continue;
             if (note.liveSentAt === null || now.getTime() - Date.parse(note.liveSentAt) < LIVE_RESEND_MS)
@@ -82,8 +53,6 @@ export function tickLiveSteer(store, steer, now, agentRunning) {
                 continue;
             }
         }
-        // The first send is the note itself, under its own identity; a re-send is a fresh frame (the harness may drop a
-        // repeated uuid) that only names the file.
         if (!session.send(first ? liveNoteText(box, number, note) : liveReminderText(box, number), first ? (note.liveUuid ?? randomUUID()) : randomUUID()))
             return;
         store.recordLiveSend(noteId, box.runId, now);