toolroll 0.9.104 → 0.9.105

package/dist/monitoring-settings.js

@@ -1,18 +1,7 @@
-/**
- * Settings → Monitoring (v104): where Toolroll sends what it does, for
- * the tools a company already watches. Kept in `monitoring.json` beside the
- * database (0600, the agent fence keeps agents out), never in the database:
- * the webhook's signing secret and a collector's header value are secrets.
- *
- * - The audit stream: every sealed ledger entry, in order, to a webhook
- *   (each request signed) and/or a folder of JSON Lines files.
- * - Traces: each finished run as an OpenTelemetry span, to a collector.
- */
 import { randomBytes } from "node:crypto";
 import { closeSync, constants, existsSync, fsyncSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 const FILE = "monitoring.json";
-/** Where an address points, without its path or query (a webhook may carry a key in either). */
 export const origin = (address) => { try {
     return new URL(address).origin;
 }
@@ -20,7 +9,6 @@ catch {
     return "?";
 } };
 export const NO_MONITORING = { webhook: null, folder: null, traces: null };
-/** An address Toolroll may send to: https anywhere, http only to this machine (a collector beside it). */
 export function sendableAddress(value) {
     let url;
     try {
@@ -36,7 +24,6 @@ export function sendableAddress(value) {
         return null;
     return url.toString().replace(/\/+$/, "");
 }
-/** A header name a collector asks for (x-honeycomb-team, DD-API-KEY, Authorization); never one HTTP itself owns. */
 const HEADER_NAME = /^[A-Za-z0-9][A-Za-z0-9-]{0,63}$/;
 const RESERVED_HEADERS = new Set(["host", "content-length", "content-type", "transfer-encoding", "connection", "cookie", "user-agent"]);
 export function readMonitoring(dir) {
@@ -62,7 +49,6 @@ export function readMonitoring(dir) {
 }
 function write(dir, settings) {
     const file = join(dir, FILE);
-    // A fresh name, made here (never a file or link already there), readable by its owner only, then swapped in.
     const next = `${file}.${randomBytes(8).toString("hex")}.tmp`;
     const handle = openSync(next, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
     try {
@@ -80,16 +66,9 @@ function write(dir, settings) {
         throw error;
     }
 }
-/** A fresh signing secret for the webhook (shown once; the receiver keeps it to check each request). */
 export function newSigningSecret() {
     return `whsec_${randomBytes(32).toString("base64url")}`;
 }
-/**
- * Save what the form sent. A blank field turns that destination off; a header value left blank keeps the one
- * saved. A new webhook address, or `rotate`, makes a new signing secret, handed back once as `secret`.
- */
-/** A path as it really is: its nearest existing folder resolved (so /tmp and /private/tmp are one), in one case
- * (macOS folders ignore it). */
 function realish(path) {
     let at = resolve(path), rest = "";
     while (!existsSync(at) && dirname(at) !== at) {
@@ -119,11 +98,10 @@ export function saveMonitoring(dir, form, previous, forbidden = []) {
     if (form.folder.trim() !== "") {
         const path = form.folder.trim();
         if (!isAbsolute(path) || path.length > 500 || /[\u0000-\u001f]/.test(path))
-            return { ok: false, said: "The folder is a full path, like /var/log/standing-orders." };
-        // Never where an agent works or Toolroll keeps its own state: an agent could read the whole stream there.
+            return { ok: false, said: "The folder is a full path, like /var/log/toolroll." };
         const real = realish(path);
         if ([dir, ...forbidden].some(one => within(real, realish(one)) || within(realish(one), real)))
-            return { ok: false, said: "Choose a folder outside Toolroll's own folder and your projects, like /var/log/standing-orders." };
+            return { ok: false, said: "Choose a folder outside Toolroll's own folder and your projects, like /var/log/toolroll." };
         folder = { path };
     }
     let traces = null;
@@ -136,7 +114,6 @@ export function saveMonitoring(dir, form, previous, forbidden = []) {
         if (name !== "") {
             if (!HEADER_NAME.test(name) || RESERVED_HEADERS.has(name.toLowerCase()))
                 return { ok: false, said: "The header name is letters, digits and dashes, like x-honeycomb-team." };
-            // A saved key stays only with the same collector (origin) and header: it never follows the address elsewhere.
             const sameCollector = previous.traces !== null && origin(previous.traces.endpoint) === origin(endpoint) && previous.traces.header?.name === name;
             const value = form.headerValue.trim() !== "" ? form.headerValue.trim() : sameCollector ? previous.traces.header.value : "";
             if (value === "" || value.length > 2000 || /[\u0000-\u001f]/.test(value))
@@ -149,7 +126,6 @@ export function saveMonitoring(dir, form, previous, forbidden = []) {
     write(dir, settings);
     return { ok: true, settings, secret };
 }
-/** The change in words for the ledger: where things go and header names, never a secret or a full address. */
 export function monitoringWords(settings) {
     const parts = [
         settings.webhook === null ? null : `webhook ${origin(settings.webhook.url)}`,
@@ -158,7 +134,6 @@ export function monitoringWords(settings) {
     ].filter((one) => one !== null);
     return parts.length === 0 ? "off" : parts.join("; ");
 }
-/** A change for the ledger: before → after, and what changed that the words alone don't show (never the values). */
 export function monitoringChange(before, after, newSecret) {
     const notes = [
         before.webhook !== null && after.webhook !== null && before.webhook.url !== after.webhook.url && origin(before.webhook.url) === origin(after.webhook.url) ? "webhook address changed" : null,

package/dist/monitoring-ui.js

@@ -1,23 +1,13 @@
-/**
- * Settings → Monitoring (v104): an instance operator points Toolroll at
- * the company's tools. One form, the status of each destination beside it,
- * and how Prometheus reads `/metrics`. The signing secret is shown once.
- * Built from the revamp kit; the Settings frame adds the title.
- */
 import { html, joinHtml } from "./html.js";
 import { targetOf } from "./monitoring.js";
 import { whenUtc } from "./when-html.js";
 import { codeLine, disclose, doc, docHeader, formRow, icon, infoLine, input, note, notice, settingsSection, switchInput } from "./server/kit.js";
 import { kitSectionForm, SECRET_OPT_OUTS } from "./settings-kit.js";
 const when = (at) => whenUtc(at);
-/** The page is kit pieces now; nothing of the old look is left. Kept as an export for the shared stylesheet. */
 export const MONITORING_CSS = "";
-/** How a destination is doing, in one line. */
 function statusLine(view, sink, address) {
-    // An empty field already says it's off.
     if (address === null)
         return "";
-    // A status for another address (it just changed) says nothing about this one yet.
     const one = view.status.find(row => row.sink === sink && row.target === targetOf(address));
     if (one === undefined || (one.lastOkAt === null && one.lastError === null))
         return html `<p class="k-note" data-monitoring="${sink}" data-state="starting">Starting: the first delivery goes out within a few seconds.</p>`;
@@ -33,11 +23,11 @@ export function monitoringHtml(view, said) {
     const audit = settingsSection({ id: "audit-stream", title: "Audit stream", lead: "Every ledger entry with its seal, as it happens, to your log system.",
         body: joinHtml([
             formRow("Webhook", "Blank: off.", input({ id: "monitoring-webhook", name: "webhook", type: "url", value: s.webhook?.url ?? "",
-                attrs: { placeholder: "https://logs.example.com/standing-orders", spellcheck: "false", "aria-label": "Webhook" } })),
+                attrs: { placeholder: "https://logs.example.com/toolroll", spellcheck: "false", "aria-label": "Webhook" } })),
             statusLine(view, "webhook", s.webhook?.url ?? null),
             s.webhook === null ? "" : formRow("Signing secret", "Make a new one. It is shown once, after Save.", switchInput({ id: "monitoring-rotate", name: "rotate", label: "Make a new signing secret", on: false, attrs: { value: "1" } }), "inline"),
             formRow("Folder", "JSON Lines, a file per day. Blank: off.", input({ id: "monitoring-folder", name: "folder", value: s.folder?.path ?? "",
-                attrs: { placeholder: "/var/log/standing-orders", spellcheck: "false", "aria-label": "Folder" } })),
+                attrs: { placeholder: "/var/log/toolroll", spellcheck: "false", "aria-label": "Folder" } })),
             statusLine(view, "folder", s.folder?.path ?? null),
         ]) });
     const traces = settingsSection({ id: "traces", title: "Traces", lead: "Each run as an OpenTelemetry span: timings, model, tokens and cost. Never a prompt or code.",
@@ -55,12 +45,10 @@ export function monitoringHtml(view, said) {
         body: disclose("Example", codeLine(`curl -H "Authorization: Bearer so_…" ${metrics}`)) });
     return joinHtml([
         said.problem ? notice(said.problem) : said.said ? infoLine(said.said) : "",
-        // A new signing secret answers with a page of its own (shown once): post as a navigation.
         kitSectionForm({ proof: "monitoring", action: "/settings/monitoring", id: "monitoring-form", gate: true, native: true, body: joinHtml([audit, traces]) }),
         metricsSection,
     ]);
 }
-/** The webhook's signing secret, once: a focused page with no script. */
 export function signingSecretHtml(url, secret) {
     return doc(docHeader({ title: "Signing secret", back: ["/settings/monitoring", "Monitoring"] }), settingsSection({ id: "signing-secret", title: "Shown once", lead: html `Give this to the receiver at <span class="k-mono">${url}</span>. It isn't shown again.`,
         body: joinHtml([

package/dist/monitoring.js

@@ -1,20 +1,3 @@
-/**
- * Monitoring (v104): what Toolroll does, sent to the tools a company
- * already watches. One loop in `up` makes a pass every few seconds; each
- * destination is sent to by one process at a time (a lease in
- * `monitoring_status`), in ledger order, at least once: its cursor moves only
- * after a delivery lands, so a failure is retried (backing off to five
- * minutes) and nothing is skipped or reordered.
- *
- * - `webhook`: sealed ledger entries, POSTed in batches, each request signed
- *   (`x-standing-orders-signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of
- *   "<t>.<body>" with the signing secret>`). Each batch carries the chain
- *   head, so the receiver keeps its own copy of the checkpoints.
- * - `folder`: the same events as JSON Lines, a file per day.
- * - `traces`: each finished run as an OpenTelemetry span (OTLP/HTTP JSON),
- *   and each completed task as the root span its runs hang under. Model,
- *   tokens, cost and timings; never a prompt, a diff or a file.
- */
 import { createHash, createHmac, randomUUID } from "node:crypto";
 import { closeSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
 import { hostname } from "node:os";
@@ -26,27 +9,23 @@ const BATCH = 200;
 const LEASE_MS = 60_000;
 const TIMEOUT_MS = 10_000;
 const CHECKPOINT_EVERY_MS = 60 * 60_000;
-/** An audit event: the ledger entry and its seal, as the stream sends it. */
 export function auditEvent(entry, instance) {
     return {
         type: "standing-orders.audit", instance, id: entry.id, at: entry.at, actor: entry.actor, project: entry.repo, task: entry.taskId, run: entry.runId,
         action: entry.action, outcome: entry.outcome, source: entry.source, detail: entry.detail, seal: entry.seal,
     };
 }
-/** The signature a receiver recomputes: HMAC-SHA256(secret, "<t>.<body>"), hex. */
 export function signature(secret, timestamp, body) {
     return `t=${timestamp},v1=${createHmac("sha256", secret).update(`${timestamp}.${body}`, "utf8").digest("hex")}`;
 }
 const backoff = (failures) => Math.min(5 * 60_000, 5_000 * 2 ** Math.min(failures, 10));
 const hex = (text, length) => createHash("sha256").update(text, "utf8").digest("hex").slice(0, length);
 const nanos = (at) => `${BigInt(Date.parse(at)) * 1000000n}`;
-/** One pass over every destination that's set up. Returns what it sent, per destination. */
 export async function monitoringPass(store, settings, deps) {
     const sent = {};
     const heads = [];
     const audit = (delivered) => { if (delivered.head !== null)
         heads.push(delivered.head); return delivered.count; };
-    // A new destination gets the whole audit history; traces start from now.
     if (settings.webhook !== null)
         sent.webhook = audit(await deliver(store, "webhook", targetOf(settings.webhook.url), () => 0, deps, entries => postSigned(settings.webhook, entries, store, deps)));
     if (settings.folder !== null)
@@ -56,9 +35,6 @@ export async function monitoringPass(store, settings, deps) {
     checkpointSent(store, heads, (deps.now ?? (() => new Date()))());
     return sent;
 }
-/** The furthest head the audit stream delivered, kept as an automatic checkpoint once the whole chain verifies.
- * Automatic checkpoints write no ledger entry, so recording one gives the stream nothing new to send (and checkpoint)
- * next pass. At most one an hour, so a busy stream neither floods the table nor walks the whole chain every pass. */
 function checkpointSent(store, heads, now) {
     const head = heads.reduce((best, one) => best === null || (one !== null && one.through > best.through) ? one : best, null);
     if (head === null)
@@ -69,12 +45,9 @@ function checkpointSent(store, heads, now) {
     try {
         store.ledgerCheckpoint("system", now, { head });
     }
-    catch { /* a busy database: the next delivery tries again */ }
+    catch { }
 }
-/** A destination's name in its status row: a digest of its address (the address itself may carry a key). */
 export const targetOf = (address) => hex(`standing-orders/monitoring/${address}`, 16);
-/** Send what's due to one destination: hold it, start it over if it now points elsewhere, read after its cursor,
- * hand the batch over, and move the cursor only when it landed and nothing changed meanwhile. */
 async function deliver(store, sink, target, start, deps, send) {
     const now = deps.now ?? (() => new Date());
     const at = now();
@@ -120,9 +93,6 @@ async function postSigned(webhook, entries, store, deps) {
     await post(webhook.url, body, { [SIGNATURE_HEADER]: signature(webhook.secret, timestamp, body), "x-standing-orders-delivery": `${entries[0].id}-${last.id}` }, deps);
     return entries.length;
 }
-/** Append events to the day's file (by each entry's own day), made readable by its owner only. The folder must be
- * a real folder of this user's that nobody else can write to (a link, or a shared folder, could send the stream
- * somewhere else). */
 function appendFolder(folder, entries, instance) {
     mkdirSync(folder, { recursive: true, mode: 0o700 });
     const stat = lstatSync(folder);
@@ -138,8 +108,7 @@ function appendFolder(folder, entries, instance) {
         byDay.set(day, [...(byDay.get(day) ?? []), JSON.stringify(auditEvent(entry, instance))]);
     }
     for (const [day, lines] of byDay) {
-        // Never through a link someone left where the day's file goes: it would append to wherever it points.
-        const handle = openSync(join(folder, `standing-orders-audit-${day}.jsonl`), constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+        const handle = openSync(join(folder, `toolroll-audit-${day}.jsonl`), constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
         try {
             writeSync(handle, `${lines.join("\n")}\n`);
             fsyncSync(handle);
@@ -151,7 +120,6 @@ function appendFolder(folder, entries, instance) {
 }
 const money = (key, value) => value === null ? [] : [{ key, value: { doubleValue: value } }];
 const attr = (key, value) => value === null || value === undefined ? [] : [{ key, value: typeof value === "string" ? { stringValue: value } : Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value } }];
-/** Spans for the batch's finished runs and completed tasks (the rest of the ledger isn't traced; the cursor passes it). */
 export function spansFor(store, entries) {
     const spans = [];
     const rootOf = (taskId) => store.revisionAncestryStatus(taskId).chain[0] ?? taskId;
@@ -175,7 +143,6 @@ export function spansFor(store, entries) {
                     ...attr("gen_ai.system", run.provider), ...attr("gen_ai.request.model", run.model), ...attr("gen_ai.usage.input_tokens", run.tokensIn),
                     ...attr("gen_ai.usage.output_tokens", run.tokensOut), ...money("standing_orders.cost_usd", run.costUsd),
                 ],
-                // The outcome's word only: a run's reason is free text (a path, a provider's message).
                 status: failed ? { code: 2, message: run.outcome ?? "failed" } : { code: 1 },
             });
         }
@@ -207,7 +174,6 @@ async function postTraces(traces, entries, store, deps) {
     await post(url, body, traces.header === null ? {} : { [traces.header.name]: traces.header.value }, deps);
     return spans.length;
 }
-/** This build's version, from its package.json ("unknown" when it can't be read). */
 export function packageVersion() {
     try {
         const parsed = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -217,11 +183,9 @@ export function packageVersion() {
         return "unknown";
     }
 }
-/** Who this process is, for the lease: host, pid and a random part (a restarted pid is a new holder). */
 export function monitoringHolder() {
     return `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`;
 }
-/** The loop `up` runs: a pass every `everyMs`, settings read afresh each time (a change applies at the next pass). */
 export function startMonitoring(options) {
     const holder = monitoringHolder();
     let stopped = false, timer = null;

package/dist/names.js

@@ -1,26 +1,8 @@
-/**
- * The product's internal name, and every older one it still answers to.
- *
- * Toolroll was Standing Orders, which was nightorders. A rename must never
- * orphan an installation: new things use the new name, while a folder,
- * variable, branch, launchd job or skill that already exists under an older
- * name keeps being found. Nothing is moved; the old one is used until one
- * exists under the new name. Strings that feed a hash, a digest or a stored
- * format id are not names in this sense and stay byte-identical.
- */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 export const NAME = "toolroll";
-/** Older names, newest first. */
 export const LEGACY_NAMES = ["standing-orders", "nightorders"];
 export const NAMES = [NAME, ...LEGACY_NAMES];
-/**
- * A file inside the product's folder under `base` (~/.config, ~/.cache, or a
- * home dotfolder when `dot` is set). The first name that already holds the
- * file wins; otherwise the file goes into the folder that holds the database,
- * else the first folder that exists, else a new-name folder — so one install
- * keeps one folder, and a fresh one gets ~/.config/toolroll.
- */
 export function namedPath(base, rest, options = {}) {
     const names = options.names ?? NAMES;
     const folder = (name) => join(base, options.dot ? `.${name}` : name);
@@ -29,71 +11,50 @@ export function namedPath(base, rest, options = {}) {
             return join(folder(name), ...rest);
     return join(namedFolder(base, options), ...rest);
 }
-/** The product's folder under `base`: see namedPath. */
 export function namedFolder(base, options = {}) {
     const names = options.names ?? NAMES;
     const folder = (name) => join(base, options.dot ? `.${name}` : name);
     const chosen = names.find(name => existsSync(join(folder(name), "orders.db"))) ?? names.find(name => existsSync(folder(name))) ?? names[0];
     return folder(chosen);
 }
-/** Every folder under `base` that any name has made, for fencing and cleanup. */
 export function existingFolders(base, options = {}) {
     return NAMES.map(name => join(base, options.dot ? `.${name}` : name)).filter(path => existsSync(path));
 }
-/** ~/.config (or $XDG_CONFIG_HOME). */
 export function configBase(env, home) {
     const xdg = env["XDG_CONFIG_HOME"];
     return xdg !== undefined && xdg !== "" ? xdg : join(home, ".config");
 }
 export const ENV_PREFIX = "TOOLROLL_";
 export const LEGACY_ENV_PREFIX = "STANDING_ORDERS_";
-/**
- * An environment setting by its suffix ("DB" → TOOLROLL_DB). The new name
- * wins whenever it is set; the old STANDING_ORDERS_ one is the fallback.
- */
 export function envValue(env, suffix) {
-    // Empty counts as unset: a blank TOOLROLL_DB must not hide an isolating STANDING_ORDERS_DB.
     const current = env[ENV_PREFIX + suffix];
     return current !== undefined && current !== "" ? current : env[LEGACY_ENV_PREFIX + suffix];
 }
-/** The Telegram bot token's variable, and the name it had before the rename: agents never see either.
- * Kept here, in a module with no imports of its own, so builder.ts can read it at load time. */
 export const TELEGRAM_TOKEN_ENV = `${ENV_PREFIX}TELEGRAM_TOKEN`;
 export const TELEGRAM_TOKEN_ENVS = [TELEGRAM_TOKEN_ENV, `${LEGACY_ENV_PREFIX}TELEGRAM_TOKEN`];
-/** Both names of a setting, for a child the plane starts: older tools read the old one. */
 export function envTwins(suffix, value) {
     return { [ENV_PREFIX + suffix]: value, [LEGACY_ENV_PREFIX + suffix]: value };
 }
-/** True for a variable of either name ("TOOLROLL_DB", "STANDING_ORDERS_DB"). */
 export function isOwnEnv(key) {
     return /^(TOOLROLL|STANDING_ORDERS)_/i.test(key);
 }
-/** New task branches are toolroll/<id>; the plane's older ones stay its own. */
 export const BRANCH_PREFIX = `${NAME}/`;
 export const BRANCH_PREFIXES = [BRANCH_PREFIX, "standing-orders/"];
 export function taskBranch(id) {
     return `${BRANCH_PREFIX}${id}`;
 }
-/** A branch the plane made, under either name. */
 export function isOwnBranch(branch) {
     return BRANCH_PREFIXES.some(prefix => branch.startsWith(prefix));
 }
-/**
- * Whether a head branch is inside a publication grant's prefix. A grant made
- * for the plane's own branches under one name covers the same branches under
- * the other: a standing-orders/ grant still publishes toolroll/<id> work.
- */
 export function headWithin(head, prefix) {
     if (head.startsWith(prefix))
         return true;
     const own = BRANCH_PREFIXES.find(one => prefix.startsWith(one));
     return own !== undefined && BRANCH_PREFIXES.some(one => head.startsWith(one + prefix.slice(own.length)));
 }
-/** Every name a task's own branch may have, newest first. */
 export function taskBranches(id) {
     return BRANCH_PREFIXES.map(prefix => `${prefix}${id}`);
 }
-/** The first candidate branch that already exists (a retry reuses its branch), else the first — the new name. */
 export async function existingOrFirst(candidates, exists) {
     for (const candidate of candidates)
         if (await exists(candidate))

package/dist/needs-you.js

@@ -1,21 +1,6 @@
-/** Every reason a task, result or flow card can wait on a person, in one
- * place: the plain sentence it shows and the one action that resolves it
- * (task-status.ts reads it for every surface). A reason no person can act
- * on is not Needs you: it is a Waiting reason, worded as what it waits for.
- *
- * The words never name the machine's internals; `plainSentence` keeps a
- * recorded reason only when it is free of them. */
-/** The action's code: the WorkAction that owns the act, or one of the acts a surface renders itself. */
-/** The reason a storage hold carries before the check's own words (dispose.ts holdForStorage; dispatch.ts and
- * work-index.ts read it back). */
 export const STORAGE_HOLD_PREFIX = "protected-storage — ";
-/** Where "Connect a builder" and "Start the builder" lead (code `start-worker`): the Start a builder page, which shows
- * the one command to run and the open project's builder state. Every signed-in person can open it, a project-limited
- * one included (System is instance-only). Never the task's own page, which only repeats that nothing is connected. */
 export const START_BUILDER_HREF = "/start-builder";
-/** Start a builder for one task: the page reports that task's own project, whatever project is open. */
 export const startBuilderHref = (taskId) => taskId === null ? START_BUILDER_HREF : `${START_BUILDER_HREF}?task=${encodeURIComponent(taskId)}`;
-/** What starts a builder: run on the machine where the project lives, in the project's folder. */
 export const START_BUILDER_COMMAND = "toolroll up";
 const always = () => true;
 const build = (context) => context.build == null ? "the last build" : `build #${context.build}`;
@@ -25,47 +10,35 @@ export const NEEDS = {
     card: { sentence: () => "This card is waiting for your approval.", action: { code: "approve-card", label: "Approve card" } },
     answer: { sentence: () => "Answer the question so the work can continue.", action: { code: "answer-decision", label: "Answer the question" }, useReason: always },
     questions: { sentence: () => "Too many questions are open. Answer one so this task can start.", action: { code: "inspect-decisions", label: "Answer questions" } },
-    "sign-in": { sentence: context => `${context.provider ?? "Your agent"} needs you to sign in again. The task starts on its own after.`, action: { code: "sign-in", label: "Sign in again" }, useReason: reason => /sign in|API key/i.test(reason) },
-    // Toolroll proves a build stopped itself (stop-proof.ts); nobody is asked to vouch for it. Only when this computer
-    // can't look, or something Toolroll didn't start is using the build's folder, is the work held: the person can close
-    // what's theirs and have it look again, nothing more.
+    "sign-in": { sentence: context => `${context.provider ?? "Your agent"} needs you to sign in again. The task starts on its own after.`, action: { code: "sign-in", label: "Sign in again" }, useReason: reason => /sign(?:ed)? in|API key/i.test(reason) },
     "stop-unproven": { sentence: context => `Toolroll can't prove ${build(context)} stopped from this computer, so the work is held. Close anything of yours that is using its folder, then check again.`, action: { code: "recheck-stopped", label: "Check again" } },
     hold: { sentence: () => "A hold is keeping this task from starting. Review it to release it.", action: { code: "inspect-hold", label: "Review hold" } },
-    // The storage check couldn't finish (protected-storage.ts): its own words say which program macOS may need to allow.
     storage: { sentence: () => "Toolroll couldn't finish checking other apps' data before starting. Allow it in Privacy & Security, then try again.", action: { code: "unhold", label: "Try again" }, useReason: always },
     "choose-project": { sentence: () => "Choose a project so a builder can start.", action: { code: "place-task", label: "Choose a project" } },
     "define-task": { sentence: () => "Say what the task should do so it can be planned.", action: { code: "write-scope", label: "Define the task" } },
     "fix-request": { sentence: () => "The request can't be planned as written. Edit it so the planner can start.", action: { code: "write-scope", label: "Edit the request" },
-        // Its own size and limit say exactly what to shorten.
         useReason: reason => /the planner can carry at most/.test(reason) },
     "choose-agent": { sentence: () => "Choose an agent to build this.", action: { code: "select-agent", label: "Choose an agent" } },
     "fix-dependency": { sentence: () => "A task this one waits on didn't finish. Fix or remove it so this one can start.", action: { code: "repair-dependency", label: "Fix the required task" },
         useReason: reason => /didn't finish|did not finish|before it finished/i.test(reason), withReason: reason => {
-            // A reason that already says what to do is said once.
             const said = reason.replace(/[.\s]*$/, ".");
             return /Fix or remove it so this one can start\.$/.test(said) ? said : `${said} Fix or remove it so this one can start.`;
         } },
     "add-requirement": { sentence: () => "This project is missing something the task needs. Add it so a builder can start.", action: { code: "repair-capability", label: "Add the requirement" } },
     "connect-builder": { sentence: () => "No builder works on this project yet. Connect one so the task can start.", action: { code: "start-worker", label: "Connect a builder" } },
     "start-builder": { sentence: () => "The builder is offline. Start the builder.", action: { code: "start-worker", label: "Start the builder" } },
-    // The same act as before (it opens the build, where Retry is): only the words are plainer.
     vanished: { sentence: context => `${Build(context)} stopped unexpectedly. Retry it.`, action: { code: "reconcile-run", label: "Open the build" } },
     "review-result": { sentence: () => "Check the result, then accept it or send it back.", action: { code: "open-result", label: "Open result" } },
-    // Accepting it would not help: it was built to terms that are no longer the plan.
     rebuild: { sentence: context => `${Build(context)} was made to an earlier plan. Retry it on the current plan.`, action: { code: "retry-task", label: "Retry" } },
-    // The plan was rewritten after the build and not yet approved: the yes comes first, then Build again.
     replan: { sentence: context => `The plan changed after ${build(context)}. Approve the new plan, then retry it.`, action: { code: "approve-scope", label: "Approve plan" } },
     "earlier-version": { sentence: context => context.task == null ? "An earlier version of this task still needs you. Finish it first." : `An earlier version, ${context.task}, still needs you. Finish it first.`,
         action: { code: "inspect-task", label: "Open earlier version" } },
-    // An actionable need, never a quiet Waiting: a person opens it to retry or archive it.
     history: { sentence: () => "Toolroll can't read this task's history. Open it to retry or archive it.", action: { code: "inspect-task", label: "Open the task" } },
-    // A finding the reviewer and the agent couldn't settle (findings.ts): only a person closes it.
     finding: { sentence: () => "A finding has used its rounds. Read both sides and decide.", action: { code: "inspect-findings", label: "Open finding" } },
     other: { sentence: () => "Open the task to see what it needs from you.", action: { code: "inspect-task", label: "Open the task" }, useReason: always },
 };
 export const ASKS = ["decide", "review", "unblock"];
 export const ASK_LABEL = { decide: "Decide", review: "Review", unblock: "Unblock" };
-/** `mismatch`: the saved report doesn't match its changes; `planChanged`: the plan changed after it was built. */
 export function askChipOf(read) {
     if (read.headline === "Failed")
         return "Failed";
@@ -83,6 +56,8 @@ export function askChipOf(read) {
         return "Question";
     if (read.need === "hold")
         return "On hold";
+    if (read.need === "fix-dependency")
+        return "Blocked";
     if (read.need === "vanished" || read.need === "stop-unproven")
         return "Stopped";
     if (read.need === "sign-in")
@@ -131,12 +106,8 @@ export const WAITS = {
     "app-update": () => "Waiting: Toolroll is updating. New work starts after it.",
     "other-task": context => context.task == null ? "Waiting for another task to finish first." : `Waiting for ${context.task} to finish first.`,
 };
-/** Words that name the machine's internals (plain-words.ts, the one table); no Needs you or Waiting sentence carries
- * them, and a recorded reason that does is replaced by the need's own words. */
 export { BANNED_WORDS, PLAIN_WORDS, bannedWordsIn, hasInternalWords } from "./plain-words.js";
 import { hasInternalWords } from "./plain-words.js";
-/** The sentence for a need: its recorded reason when the need keeps one and
- * it reads plainly, otherwise the need's own words. */
 export function needSentence(key, reason, context = {}) {
     const need = NEEDS[key];
     const plain = reason?.trim() || null;
@@ -144,8 +115,6 @@ export function needSentence(key, reason, context = {}) {
         return need.sentence(context);
     return need.withReason === undefined ? plain : need.withReason(plain);
 }
-/** Waits whose words need a fact (when it retries, which task it waits on): without it, a plain recorded reason that
- * already says it is kept. */
 const WAITS_WITH_FACTS = {
     "retry-later": context => context.retry != null, "other-task": context => context.task != null,
 };
@@ -156,9 +125,6 @@ export function waitSentence(key, reason, context = {}) {
         return WAITS_WITH_FACTS[key]?.(context) === false && known !== null ? known : WAITS[key](context);
     return known ?? "Waiting for the work to continue on its own.";
 }
-/** A finished run Toolroll can't yet prove stopped (store.stopQuiescenceFact). Nobody is asked to confirm it:
- * `unprovable` is Toolroll's own check still to run (stop-proof.ts), which settles by itself; `unknown` is that this
- * computer can't look, or something Toolroll didn't start is in the build's folder — held, with nothing to vouch for. */
 export function processNeedOf(fact) {
     if (fact === null)
         return null;
@@ -171,7 +137,6 @@ export function processNeedOf(fact) {
     return { wait: fact.kind === "elsewhere" ? "other-computer" : "build-stopping", build: fact.run };
 }
 export const CODE_READING = {
-    // Plain states: nothing is asked and nothing is waited on by name.
     queued: { stage: "queued" }, ready: { stage: "queued" }, "provider-quota": { stage: "queued" },
     running: { stage: "building" }, reviewing: { stage: "reviewing" }, "review-pending": { stage: "building" }, "checks-running": { stage: "checking" },
     "ready-to-check": { stage: "finished", act: "open-result" }, "ready-to-review": { stage: "finished" }, "report-ready": { stage: "finished" }, "no-change": { stage: "finished" },
@@ -179,21 +144,17 @@ export const CODE_READING = {
     complete: { stage: "complete", act: "open-result" }, cancelled: { stage: "stopped", act: "inspect-task" }, paused: { stage: "stopped" },
     stopped: { stage: "stopped", act: "resume-run" },
     failed: { stage: "failed", act: "retry-task" }, "checks-failed": { stage: "failed" },
-    // The same failure again and again: a need over Retry, its own act, said plainly.
     "waiting-incident": { stage: "failed", act: "retry-task" },
-    // Waits: Toolroll or another task moves these on; no person is asked.
     stopping: { stage: "waiting", wait: "build-stopping" },
     "build-stopping": { stage: "waiting", wait: "build-stopping" }, "other-computer": { stage: "waiting", wait: "other-computer" },
     "planning-ready": { stage: "waiting", wait: "plan-next" }, "scouting-ready": { stage: "waiting", wait: "research-next" },
     "worker-at-capacity": { stage: "waiting", wait: "builders-busy" }, "retry-scheduled": { stage: "waiting", wait: "retry-later" },
     updating: { stage: "waiting", wait: "app-update" }, "waiting-dependency": { stage: "waiting", wait: "other-task" },
-    // Needs, each over the act it has always had.
     "history-problem": { stage: "needs-you", need: "history", act: "inspect-task" },
     "earlier-active": { stage: "needs-you", need: "earlier-version", act: "inspect-task" },
     "waiting-decision": { stage: "needs-you", need: "answer", act: "answer-decision" },
     "finding-held": { stage: "needs-you", need: "finding", act: "inspect-findings" },
     "decision-queue": { stage: "needs-you", need: "questions", act: "inspect-decisions" },
-    // A saved result that can't simply be accepted yet: its own reason (resultHoldUpSentence) is the sentence.
     "result-needs-attention": { stage: "needs-you", need: "other", act: "inspect-run" },
     "process-needs-attention": { stage: "needs-you", need: "stop-unproven", act: "inspect-run" },
     "vanished-run": { stage: "needs-you", need: "vanished", act: "reconcile-run" },
@@ -215,14 +176,10 @@ export const CODE_READING = {
     "evidence-mismatch": { stage: "needs-you", need: "review-result" }, "record-incomplete": { stage: "needs-you", need: "review-result" },
     "evidence-damaged": { stage: "needs-you", need: "review-result" },
 };
-/** A code that waits on Toolroll or another task: no person is asked. */
 export const isWaitCode = (code) => CODE_READING[code]?.stage === "waiting";
-/** Notification kinds that need nothing from a person: they stay in the activity log and never ping a phone. */
 export const ACTIVITY_ONLY_KINDS = new Set(["check-progress"]);
-/** Dispatch and work-index codes that wait on a person, as their need (read from CODE_READING). */
 export const CODE_NEED = Object.fromEntries(Object.entries(CODE_READING)
     .flatMap(([code, reading]) => reading.need === undefined ? [] : [[code, reading.need]]));
-/** A stopped run's recorded reason code, in words (the run record, the thread, a failed task's status). */
 export const RUN_REASON_WORDS = {
     agent: "the agent failed",
     "agent-reported": "the agent reported it could not finish",
@@ -274,9 +231,6 @@ export const RUN_REASON_WORDS = {
     "attempts-exhausted": "it failed too many times in a row",
     "plan-revised": "the plan changed, so a fresh attempt took over",
 };
-/** A run's recorded reason in words. A recorded code is never shown as it is
- * stored: one with no words of its own reads as an unexpected stop; a reason
- * already written as words (it has a space) is said as written. */
 export function runReasonWords(reason) {
     const known = RUN_REASON_WORDS[reason];
     if (known !== undefined)
@@ -285,11 +239,8 @@ export function runReasonWords(reason) {
         return "the agent asked a question";
     return /\s/.test(reason.trim()) ? reason.trim() : "the attempt stopped unexpectedly";
 }
-/** The latest finished build attempt among a task's runs (any order), whatever its outcome: planning and reviewing
- * are not attempts, and an older failure never stands in for a newer attempt. */
 export function latestFinishedAttempt(runs) {
     let latest = null;
-    // Ended means a finish time or an outcome: a reconcile can mark a run failed without stamping finished_at.
     for (const run of runs)
         if ((run.finishedAt !== null || (run.outcome ?? null) !== null) && run.role !== "planner" && run.role !== "reviewer" && (latest === null || run.id > latest.id))
             latest = run;
@@ -297,23 +248,17 @@ export function latestFinishedAttempt(runs) {
 }
 export const NO_REASON_RECORDED = "No reason was recorded for this attempt.";
 export const INTERNAL_ERROR = "The attempt stopped with an internal error.";
-/** About as long as one plain line reads. */
 export const REASON_LINE_LIMIT = 140;
-/** A recorded reason that is machine output, not words: a stack trace, a file path or "Error:" text. Its detail
- * belongs behind a link, never in the line itself. */
 export function isInternalErrorReason(reason) {
     const text = reason?.trim() ?? "";
     if (text === "" || RUN_REASON_WORDS[text] !== undefined)
         return false;
-    return /\b[A-Za-z]*(?:Error|Exception):/.test(text) // Error:, TypeError:, SomeException:
-        || /^\s*at\s+\S+/m.test(text) && /\n/.test(text) // a stack frame below the first line
-        // An absolute path of two or more segments (/Users/…, ~/x/y): plain sentences may name a project file (src/ledger.ts).
+    return /\b[A-Za-z]*(?:Error|Exception):/.test(text)
+        || /^\s*at\s+\S+/m.test(text) && /\n/.test(text)
         || /(?:^|[\s(“"'])~?\/(?:[\w.@-]+\/)+[\w.@-]+/.test(text)
-        || /[A-Za-z]:\\/.test(text) // C:\…
-        || /\.[cm]?[jt]sx?:\d+/.test(text); // ledger.ts:14
+        || /[A-Za-z]:\\/.test(text)
+        || /\.[cm]?[jt]sx?:\d+/.test(text);
 }
-/** A failed attempt in one plain line: its recorded reason in words (first line only, about 140 characters at most),
- * that it stopped with an internal error when the reason is machine output, or that none was recorded. */
 export function failedAttemptSentence(reason) {
     const code = reason?.trim() ?? "";
     if (code === "")
@@ -325,8 +270,6 @@ export function failedAttemptSentence(reason) {
         : `${words.slice(0, REASON_LINE_LIMIT - 1).replace(/\s+\S*$/, "").replace(/[,;:\s]+$/, "")}…`;
     return `${line.charAt(0).toUpperCase()}${line.slice(1)}${line.endsWith("…") ? "" : "."}`;
 }
-/** What to change before the next attempt, by a stopped run's recorded reason: one plain suggestion, the note Retry
- * starts with. A reason with no suggestion of its own gets the general one. */
 const STOP_SUGGESTIONS = {
     acceptance: "Before handing off, check each approved requirement against the changes.",
     timeout: "Split the work into smaller steps, or name the one part to finish first.",
@@ -353,28 +296,22 @@ export function stopSuggestionOf(reason) {
     const code = reason?.trim() ?? "";
     return STOP_SUGGESTIONS[code] ?? GENERAL_SUGGESTION;
 }
-/** A signed requirement in the middle of a sentence: its first letter lowered unless it starts a name or an acronym. */
 function inSentence(statement) {
     const plain = statement.trim().replace(/[.\s]+$/, "");
     return /^[A-Z][a-z]/.test(plain) ? `${plain.charAt(0).toLowerCase()}${plain.slice(1)}` : plain;
 }
-/** The suggestion for a requirement the result missed: make sure of it before handing off. */
 export function missedRequirementSuggestion(statement) {
     return `Before handing off, make sure ${inSentence(statement)}.`;
 }
-/** The suggestion for a check that failed on the result: make it pass, starting with the line it ended on. */
 export function failingCheckSuggestion(line) {
     return `Make the check pass. It ended on: ${line.replace(/[.\s]+$/, "")}.`;
 }
-/** The line for a missed requirement: “Missed: <statement>”, cut to one line. */
 export function missedRequirementLine(statement) {
     const plain = statement.trim().replace(/\s+/g, " ").replace(/[.\s]+$/, "");
     const cut = plain.length <= REASON_LINE_LIMIT - 10 ? plain : `${plain.slice(0, REASON_LINE_LIMIT - 11).replace(/\s+\S*$/, "")}…`;
     return `Missed a requirement: ${cut}${cut.endsWith("…") ? "" : "."}`;
 }
-/** The longest note Retry's field takes. */
 export const RETRY_NOTE_LIMIT = 500;
-/** Retry's note, prefilled with the suggestion: cut to what the field takes, at a word, so the form always posts. */
 export function retryNoteOf(suggestion) {
     const plain = suggestion.trim();
     if (plain.length <= RETRY_NOTE_LIMIT)

package/dist/never-index.js

@@ -1,15 +1,6 @@
-/**
- * Spotlight leaves Toolroll's churn alone: a `.metadata_never_index` file in a folder tells macOS not to index it or
- * what is inside. Toolroll puts one in the folders it fills and empties all day — the checkouts folder and each
- * project's folder in it (never inside a checkout, where a build's `git add -A` would commit it), shared dependency
- * installs, staged runtimes and test temp roots. Measured Oct 4: fseventsd at 15 GB with 107k test temp folders.
- *
- * A marker that can't be written is only noted: it never decides whether anything is removed.
- */
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 export const NEVER_INDEX = ".metadata_never_index";
-/** Put the marker in `dir` (an existing folder). False when it couldn't be written. */
 export function markNeverIndex(dir) {
     try {
         writeFileSync(join(dir, NEVER_INDEX), "", { flag: "a" });