toolroll 0.9.103 → 0.9.105

package/dist/beads.js

@@ -1,40 +1,12 @@
-/**
- * beads, through the `bd` binary already on the machine.
- *
- * Every command here was read out of beads' own documentation rather than
- * guessed at, and the ones that were not are refused instead of attempted.
- * That distinction is the whole design of this file, so it is written down
- * per call:
- *
- *   bd ready --json        confirmed — the ready set, which is the same
- *                          question `list_ready` asks
- *   bd create "<title>"    confirmed
- *   bd close <id>          confirmed
- *   bd dep add <a> <b>     confirmed — native edges, so they are used
- *   bd show <id> --json    the subcommand is confirmed, the --json flag is not
- *   bd update --status     NOT confirmed; only `--claim` appears in the docs
- *
- * Where the flag is unconfirmed the call parses defensively and fails closed
- * with a message naming what could not be established. Writing a plausible
- * flag into somebody's issue tracker and finding out at 3am whether it meant
- * what we hoped is the exact failure this project exists to avoid.
- *
- * Unlike the GitHub adapter, none of this has been exercised against a real
- * installation — `bd` is not present on the machine it was written on. It is
- * built to the documentation, tested against a stubbed runner, and should be
- * treated as unproven until somebody runs it with beads actually installed.
- */
 import { run } from "./exec.js";
 import { ok, no, describeFailure, parseJson, } from "./backend.js";
 const BD = "bd";
-/** Local work, so a local bound. */
 export const BEADS_TIMEOUT_MS = 10_000;
 export function beads(options) {
     const { repo, runner = run } = options;
     const call = (args) => runner(BD, args, { cwd: repo, timeoutMs: BEADS_TIMEOUT_MS });
     return {
         name: "beads",
-        // Confirmed native, and the only backend here with edges we can write.
         deps: "native",
         async listReady() {
             const result = await call(["ready", "--json"]);
@@ -55,12 +27,6 @@ export function beads(options) {
             }
             return ok(task);
         },
-        /**
-         * `bd create` is confirmed; what it prints is not. The id is read out of
-         * its output if it is there, and the absence of one is reported rather
-         * than filled in: a caller holding an id we invented would attach claims
-         * and leases to a task that does not exist.
-         */
         async create(spec) {
             const result = await call(["create", spec.title, "--json"]);
             if (result.code !== 0)
@@ -71,11 +37,6 @@ export function beads(options) {
             }
             return ok(id);
         },
-        /**
-         * Only closing is confirmed. Everything else would need `bd update` with a
-         * status flag that this adapter has not established exists, and guessing
-         * at it is how a queue quietly fills with tasks in a state nobody meant.
-         */
         async setState(id, state) {
             if (state !== "done" && state !== "cancelled" && state !== "failed") {
                 return no("unsupported", `beads: only closing is confirmed here, so \`${state}\` is not applied — the flag for it has not been established`);
@@ -85,7 +46,6 @@ export function beads(options) {
                 return no("rejected", describeFailure(result));
             return ok(undefined);
         },
-        /** `bd dep add <child> <parent>`: the child waits for the parent. */
         async addEdge(blocked, blocker) {
             const result = await call(["dep", "add", blocked, blocker]);
             if (result.code !== 0)
@@ -94,7 +54,6 @@ export function beads(options) {
         },
     };
 }
-/** beads ids are its own; only their shape is assumed, never their meaning. */
 function readIssue(record) {
     if (typeof record !== "object" || record === null)
         return null;
@@ -108,12 +67,6 @@ function readIssue(record) {
         state: readState(raw["status"] ?? raw["state"]),
     };
 }
-/**
- * beads' status vocabulary is not documented in full, so this maps the values
- * that are, and treats anything unrecognised as queued rather than inventing a
- * meaning for it. Being wrong toward "still to do" leaves work visible; being
- * wrong toward "done" loses it.
- */
 function readState(value) {
     const text = String(value ?? "").toLowerCase();
     if (text === "closed" || text === "done")
@@ -129,7 +82,6 @@ function readCreatedId(stdout) {
         if (typeof id === "string" || typeof id === "number")
             return String(id);
     }
-    // Falls back to the id-shaped token beads prints in its examples (bd-a1b2).
     const printed = /\b(bd-[a-z0-9]+)\b/i.exec(stdout);
     return printed?.[1] ?? null;
 }

package/dist/bin.js

@@ -1,11 +1,4 @@
 #!/usr/bin/env node
-/**
- * The package bin (install review). Nothing here touches the store: this
- * file exists so the runtime is checked BEFORE `node:sqlite` is imported,
- * and the answer to "why did it die" is one sentence instead of a resolver
- * stack. Bun's runtime has no node:sqlite; `bunx toolroll …`
- * (without --bun) hands the shebang to Node and works.
- */
 const versions = process.versions;
 const [major = 0, minor = 0] = versions.node.split(".").map(Number);
 if (versions.bun !== undefined) {
@@ -17,7 +10,6 @@ if (major < 22 || (major === 22 && minor < 13)) {
     process.stderr.write(`Toolroll needs Node 22.13 or newer (this is ${versions.node}) — it uses node:sqlite.\n`);
     process.exit(2);
 }
-// --version and the top-level usage answer here, before the CLI and its command families load.
 const argv = process.argv.slice(2);
 const { quickAnswer } = await import("./cli-fast.js");
 const quick = quickAnswer(argv);

package/dist/board.js

@@ -1,23 +1,7 @@
-/**
- * The board's lane classifier — one exhaustive precedence order, applied to
- * one database snapshot (Codex board review, findings 1 and 2).
- *
- * Lanes are the pipeline read left to right: attention → queued → waiting →
- * building, with completed work joining from its own query. The chain below
- * is total (the final else is queued) and disjoint (it is an if/else chain),
- * so a task appears on the board exactly once — a parked task is attention,
- * never also "waiting" through the hold its own decision placed.
- */
 import { passFraction } from "./proof.js";
-/** ISO to the minute for chip text — "retrying 14:32". */
 function clockOf(iso) {
     return iso.slice(11, 16);
 }
-/**
- * Plain words for every hold owner — shared with the task page so "who is
- * holding this" reads the same everywhere. An unknown or retired owner
- * degrades to the generic word, never to its raw name.
- */
 export const HOLD_OWNER_WORDS = {
     operator: "held by you",
     decision: "waiting on a question",
@@ -70,9 +54,6 @@ export function classify(facts, now) {
     };
     if (facts.claim !== null) {
         const doing = facts.claim.role === "planner" ? "planning — " : facts.claim.role === "scout" ? "scouting — " : "";
-        // A building card lands on the build itself when one exists — the
-        // pop-in glance should reach the live page in one click. Before the
-        // run starts the task screen remains the destination.
         const liveRunId = facts.liveRunId ?? null;
         return {
             ...base,
@@ -85,8 +66,6 @@ export function classify(facts, now) {
         };
     }
     if (facts.openDecisionId !== null) {
-        // The question is the content — the generic verb only when the
-        // snapshot could not carry it.
         return {
             ...base,
             lane: "attention",
@@ -106,7 +85,6 @@ export function classify(facts, now) {
         };
     }
     if (facts.plan === "drafted" && !facts.approved) {
-        // The planner concluded; the negotiation waits on the operator.
         return { ...base, lane: "attention", reason: "review the plan", stalledSince: facts.updatedAt };
     }
     if (facts.plan !== "requested") {
@@ -118,9 +96,6 @@ export function classify(facts, now) {
         }
     }
     if (facts.state === "running") {
-        // Running with no live claim: the build vanished out from under the
-        // state machine (reaped, or the claim expired mid-flight). A repair
-        // card, not a silent omission (finding 1).
         return { ...base, lane: "attention", reason: "build vanished — needs repair", stalledSince: facts.updatedAt };
     }
     if (facts.hold !== null) {
@@ -133,15 +108,11 @@ export function classify(facts, now) {
                     : until <= now.toISOString()
                         ? "retrying now"
                         : `retrying ${clockOf(until)}`
-                : // A decision or incident hold with no open item
-                    // above it is an orphan — say who holds it in plain words,
-                    // never the internal owner token.
+                :
                     holdOwnerWords(facts.hold.ownerKind);
         return { ...base, lane: "waiting", reason };
     }
     if (facts.unmetDependency !== null) {
-        // A terminal blocker will never clear itself. Say repair instead of
-        // presenting an impossible dependency as ordinary patience.
         if (facts.blockerState === "failed" || facts.blockerState === "cancelled") {
             return {
                 ...base,
@@ -159,12 +130,6 @@ export function classify(facts, now) {
     if (facts.missingRequirement !== null) {
         return { ...base, lane: "waiting", reason: `needs ${facts.missingRequirement}` };
     }
-    // Task-local prerequisites all satisfied. Fleet-wide constraints (worker
-    // capacity, provider quota, the attention budget) are deliberately not
-    // per-card claims — the board cannot know which runner would take this
-    // task, so the queued lane's header speaks for the fleet (finding 6).
-    // The card at this stage IS the promise: show the goal, not "ready" —
-    // unless the promise is still being negotiated, in which case say so.
     if (facts.plan === "requested") {
         return { ...base, lane: "queued", reason: "planning next" };
     }

package/dist/boot-identity.js

@@ -1,38 +1,11 @@
-/**
- * OS boot identity for process custody (OS containment and login recovery).
- *
- * A process witness carries the PID it saw, the host that saw it, and —
- * from v53 — the identity of the OS boot it was born under. After a
- * VERIFIED boot change on the same host, no process of the old boot can
- * survive: a pending stop or recovery that would otherwise wait forever
- * on an incomplete old spawn, or on a PID the new boot has since reused,
- * may settle. Every other case keeps the conservative road the witness
- * already took: a witness with no boot id (legacy), a witness from
- * another host, a boot id this host cannot read or cannot parse, or two
- * identical ids (the same boot, where the PID probe still decides).
- *
- * The identity comes from the kernel's own per-boot token, never from
- * wall-clock arithmetic: a boot time compared to `now` proves nothing
- * across suspended clocks, NTP steps and time-zone edits.
- *
- *   linux   /proc/sys/kernel/random/boot_id — a UUID minted at boot
- *   darwin  sysctl kern.bootsessionuuid    — a UUID minted at boot
- *   win32   no unprivileged per-boot UUID this build trusts → unknown
- */
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { isThisMachine } from "./machine-identity.js";
-/** RFC 4122 shape, any case; the kernel tokens are exactly this. */
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/** Normalize a candidate token: exactly one UUID, lower-cased; anything else is malformed. */
-// Recovery may compare this normalized token only after its host/kernel origin is
-// authenticated; well-formed text alone supplies neither boot identity nor absence.
 export function normalizeBootId(raw) {
     const trimmed = raw.trim();
     return UUID.test(trimmed) ? trimmed.toLowerCase() : null;
 }
-/** Read the running kernel's boot token — never cached here, so a test can
- * construct each answer; production reads it once through bootIdentity(). */
 export function readBootIdentity(readers = {}) {
     const platform = readers.platform ?? process.platform;
     const readFile = readers.readFile ?? ((path) => readFileSync(path, "utf8"));
@@ -61,34 +34,19 @@ export function readBootIdentity(readers = {}) {
     return { ok: true, id, source };
 }
 let cached = null;
-/** This process's boot identity, read once. `null` when it is unknown —
- * every consumer must then take the conservative road. */
 export function bootIdentity() {
     if (cached === null)
         cached = readBootIdentity();
     return cached;
 }
-/** The id to stamp on new custody, or null when the boot is unknown. */
 export function currentBootId() {
     const identity = bootIdentity();
     return identity.ok ? identity.id : null;
 }
-/** Tests only: pin or clear the cached identity for this process. */
 export function injectBootIdentity(identity) {
     cached = identity;
 }
-/**
- * THE ONE RULE (plan §login/reboot recovery): a witnessed process is
- * proven dead by boot change only when the witness names THIS machine (isThisMachine), the
- * witness carries a well-formed boot id, this host's current boot id is
- * well-formed and known, and the two differ. Same boot, a legacy witness
- * without an id, a foreign host, an unknown or malformed current id — each
- * answers false, and the caller keeps its PID probe or its refusal.
- */
 export function provenDeadByBootChange(witness, current = { bootId: currentBootId() }) {
-    // A caller naming the host compares exactly (restart certification, tests); otherwise THIS machine is decided by
-    // its stable id, or for a witness without one by this machine's own names (machine-identity.ts), never by the
-    // network hostname alone: a boot id from another machine always differs from ours.
     if (current.host !== undefined ? witness.host !== current.host : !isThisMachine(witness))
         return false;
     if (witness.bootId === null || current.bootId === null)

package/dist/bounded-spawn.js

@@ -1,30 +1,13 @@
-/**
- * One bounded child process tree, for work on a repository's untrusted bytes (docs/plans/code-map.md §1). What is
- * guaranteed depends on the platform, and the result says which:
- *
- *   Linux with a delegated cgroup, Windows   the OS object (containment.ts, policy `preferred`) holds the memory limit,
- *                                            and dies with the worker. `enforced: "system"`.
- *   macOS, Linux without a cgroup            no hard memory or descendant bound exists. Memory and disk are sampled every
- *                                            250 ms; a burst between samples can pass the limit before the kill, and a
- *                                            helper that left the process group can survive it. `enforced: "checked"`.
- *
- * `RLIMIT_FSIZE` applies to every POSIX spawn. The whole group is killed with SIGKILL on any limit, and again when the
- * root exits, so nothing the root started outlives it.
- */
 import { execFile, execFileSync, spawn } from "node:child_process";
 import { lstatSync, readdirSync, rmSync } from "node:fs";
 import { join, relative, isAbsolute } from "node:path";
 import { createContainer, effectiveContainment, probeContainmentCapability } from "./containment.js";
 const SAMPLE_MS = 250;
 const PIDS = 64;
-/** Applies the file-size limit (bash counts it in 1024-byte blocks, POSIX shells in 512), then becomes the target with
- * argv untouched. */
 const PRELUDE = 'if [ "$1" != none ]; then if [ -n "$BASH_VERSION" ]; then b=$(($1/1024)); else b=$(($1/512)); fi; ulimit -f "$b" 2>/dev/null || exit 126; fi\nshift\nexec "$@"';
 let containment = null;
 const preferred = () => containment ??= effectiveContainment("preferred", probeContainmentCapability());
-/** Tests: forget the probed machine. */
 export function resetBoundedContainmentForTests() { containment = null; }
-/** A process's own start time, as `ps` reports it: what tells a live process from a reused pid. */
 export function processStartedAt(pid) {
     if (process.platform === "win32")
         return null;
@@ -63,7 +46,6 @@ function groupRss(pgid) {
         });
     });
 }
-/** The folder's total size, without following a link. */
 export function folderBytes(folder) {
     let total = 0;
     const walk = (dir) => {
@@ -83,7 +65,7 @@ export function folderBytes(folder) {
                 else
                     total += held.size;
             }
-            catch { /* a temporary pack gone between the list and the look */ }
+            catch { }
         }
     };
     walk(folder);
@@ -92,7 +74,7 @@ export function folderBytes(folder) {
 const killGroup = (pgid) => { try {
     process.kill(-pgid, "SIGKILL");
 }
-catch { /* gone */ } };
+catch { } };
 export const boundedRun = async (file, args, options) => {
     const windows = process.platform === "win32";
     const effective = preferred();
@@ -120,7 +102,7 @@ export const boundedRun = async (file, args, options) => {
             try {
                 child.kill("SIGKILL");
             }
-            catch { /* gone */ }
+            catch { }
         }
     };
     if (pid !== undefined) {
@@ -180,7 +162,6 @@ export const boundedRun = async (file, args, options) => {
         } };
         child.once("error", () => settle(127, null));
         child.once("close", (code, signal) => settle(code, signal));
-        // A helper that left the group can hold the pipes open past the root's exit: the root's exit is the answer.
         child.once("exit", (code, signal) => {
             if (pid !== undefined && !windows)
                 killGroup(pid);
@@ -195,11 +176,6 @@ export const boundedRun = async (file, args, options) => {
     }
     return { code: finished.code, signal: finished.signal, stdout: Buffer.concat(stdout), stderr, killed, enforced, peakBytes };
 };
-/**
- * What a crashed build left: its group is killed only if the leader is still the process recorded (the pid and its start
- * time, so a reused pid isn't killed), and its folder goes if it sits under `root`. On Linux the cgroup janitor has
- * done this already.
- */
 export function cleanupLeftover(record, root) {
     let killed = false, removed = false;
     if (record.pid !== null && record.pgid !== null && record.startedAt !== null && processStartedAt(record.pid) === record.startedAt && processGroupOf(record.pid) === record.pgid) {
@@ -213,7 +189,7 @@ export function cleanupLeftover(record, root) {
                 rmSync(record.folder, { recursive: true, force: true });
                 removed = true;
             }
-            catch { /* the next takeover tries again */ }
+            catch { }
         }
     }
     return { killed, removed };

package/dist/brand-mark.js

@@ -1,48 +1,27 @@
-/**
- * The one mark an integration shows wherever it appears: its logo
- * (brand-icons.ts) in a 32px tile, 28px once the tiles go to their phone
- * layout; a letter in the same tile when it has none (a custom tool, a service
- * without a logo). Ink when connected, muted otherwise. Where a row of plain
- * icons already stands (the Settings home), the logo is drawn as one of them:
- * brandIconHtml, or BrandIcon in React (browser/brand-mark.tsx).
- */
 import { BRAND_ICONS } from "./brand-icons.js";
 import { html } from "./html.js";
-/** Service ids, catalog tool names and integration keys that differ from their icon's id. */
 const ALIASES = {
     atlassian: "jira", "chrome-devtools": "chrome", codex: "openai", "microsoft-teams": "teams", "better-stack": "betterstack",
 };
-/**
- * The icon for a service id, catalog tool name, chat app or integration key
- * ("telegram", "agent:codex", "mcp:<repo>:sentry"), or null for a letter.
- */
 export function brandIconFor(name) {
     const key = name.toLowerCase().replace(/^agent:/, "").replace(/^mcp:.*:/, "");
     if (Object.hasOwn(BRAND_ICONS, key))
         return key;
     return ALIASES[key] ?? null;
 }
-/** The letter a mark without a logo shows. */
 export function brandLetter(label) {
     return (label.trim().match(/[\p{L}\p{N}]/u)?.[0] ?? "?").toUpperCase();
 }
-/** The logo alone, decorative: an svg its surroundings size and colour. */
 export function brandIconHtml(id) {
     const icon = BRAND_ICONS[id];
     return html `<svg viewBox="0 0 24 24" focusable="false" aria-hidden="true"><path fill="currentColor"${icon.evenodd && html ` fill-rule="evenodd"`} d="${icon.path}"/></svg>`;
 }
-/**
- * The mark, decorative (the name always sits beside it). `name` null is a
- * letter whatever the label: a custom tool never borrows a logo by its name.
- */
 export function brandMarkHtml(name, label, connected) {
     const icon = name === null ? null : brandIconFor(name);
     const inside = icon === null ? brandLetter(label) : brandIconHtml(icon);
     return html `<span class="brand-mark" data-connected="${String(connected)}"${icon === null && html ` data-letter`} aria-hidden="true">${inside}</span>`;
 }
-/** Where the integration tiles (Settings → Tools) switch to their phone layout, and the mark with them. */
 export const TILE_PHONE = "@media(max-width:600px)";
-/** The mark's own sizes; `--brand-mark` is its side, for layouts that line up beside it. */
 export const BRAND_MARK_CSS = `:root{--brand-mark:32px}${TILE_PHONE}{:root{--brand-mark:28px}}` +
     `.brand-mark{box-sizing:border-box;flex:0 0 auto;width:var(--brand-mark);height:var(--brand-mark);border-radius:8px;display:inline-grid;place-items:center;background:var(--so-neutral-soft);color:var(--so-muted);font-style:normal;font-weight:600;font-size:15px;line-height:1}` +
     `.brand-mark svg{display:block;width:calc(var(--brand-mark) * .625);height:calc(var(--brand-mark) * .625)}.brand-mark[data-connected="true"]{color:var(--so-ink)}` +

package/dist/brief-fence.js

@@ -1,22 +1,6 @@
-/**
- * One line, prefixed, with nothing that can end the block or start a new rule.
- *
- * Scope text is written by whoever filed the task. A goal containing a newline
- * and a bullet would otherwise read to the agent as another rule in the list,
- * which is how "add a guard" becomes "add a guard, and ignore the rules below".
- * The same quoting wraps a steering note the agent reads from its mailbox.
- */
 export function fence(text) {
-    // Newlines and other control characters collapse to a space: they are the
-    // only way a value can stop being one line and start looking like a new
-    // rule. The visible text is otherwise left exactly as written — mangling
-    // somebody's scope to defend against it would be its own kind of wrong.
     return `| ${text
-        // C0/C1 plus the Unicode line and paragraph separators: everything
-        // that could end this physical line (Codex free-text review, finding 5).
         .replace(/[\u0000-\u001F\u007F-\u009F\u2028\u2029]+/g, " ")
-        // A quoted protocol-shaped name is broken VISIBLY, so untrusted text
-        // can never collide with the real nonce-bearing filename that follows.
         .replace(/STANDING-ORDERS-/g, "NIGHTORDERS[quoted]-")
         .trim()}`;
 }