toolroll 0.9.104 → 0.9.105

package/dist/up-processes.js

@@ -1,18 +1,3 @@
-/**
- * `toolroll up` as two processes (docs/plans/isolated-checks.md, stage 1): the console (HTTP: serving, reading and the
- * person's ceremonies) and the worker (the watch loops: builds, checks, batch checks, follow-ups, reconcilers, the
- * storage sweep and checkout sizing). `up` itself keeps the identities it minted (the approver's login, the runner and
- * its token), supervises both with controller-supervisor, and relays between them. Nothing here grants authority:
- * each role is handed only what it needs, by message, never on a command line or in the environment.
- *
- * What each holds:
- *   console  the database, the console's own session and sign-in secrets, the attach (instance) secret, push keys, the
- *            port. Never the runner token: it can't claim, lease or build.
- *   worker   the database and the runner name and token, for the watch leases and claims. It opens no port and mints
- *            no console session or attach secret.
- * Both are the same user on the same database folder, so files beside the database (the saved login, tool secrets)
- * are reachable by either: the split keeps secrets out of each other's memory and messages, not out of the folder.
- */
 import { createHash, randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 const MAX_TEXT = 16_384;
@@ -23,7 +8,6 @@ const nonEmpty = (value, max = MAX_TEXT) => text(value, max) && value !== "" &&
 const texts = (value) => Array.isArray(value) && value.length <= MAX_LIST && value.every(one => nonEmpty(one));
 const whole = (value, min = 0, max = 2_147_483_647) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= max;
 const orNull = (value, check) => value === null || check(value);
-/** The parent's word to a role, checked before anything acts on it. */
 export function parentMessage(value) {
     if (!isObject(value))
         return null;
@@ -34,7 +18,6 @@ export function parentMessage(value) {
         case "sign-in-link": {
             if (!whole(value["id"]))
                 return null;
-            // Exactly one of two shapes: a kind this build doesn't name, or a local request carrying an account, is no request.
             if (value["kind"] === "full")
                 return nonEmpty(value["account"], 256) ? { type: "sign-in-link", id: value["id"], kind: "full", account: value["account"] } : null;
             if (value["kind"] === "local")
@@ -44,7 +27,6 @@ export function parentMessage(value) {
         default: return null;
     }
 }
-/** A role's word to the parent, checked before the parent relays or acts on it. */
 export function roleMessage(value, role) {
     if (!isObject(value))
         return null;
@@ -54,7 +36,6 @@ export function roleMessage(value, role) {
                 return null;
             if (!orNull(value["url"], (one) => nonEmpty(one, 2_048)) || !orNull(value["port"], (one) => whole(one, 1, 65_535)))
                 return null;
-            // Only the console serves: a worker that names an address is not a worker.
             if (role === "worker" && (value["url"] !== null || value["port"] !== null))
                 return null;
             if (role === "console" && (value["url"] === null || value["port"] === null))
@@ -70,7 +51,6 @@ export function roleMessage(value, role) {
         default: return null;
     }
 }
-/** The start message a role child waits for. The console's config carries no runner token; anything else refuses. */
 export function startMessage(value) {
     if (!isObject(value) || value["type"] !== "start" || !nonEmpty(value["databaseFile"], 4_096) || !orNull(value["containment"], (one) => nonEmpty(one, 64)) || !nonEmpty(value["build"], 512))
         return null;
@@ -103,12 +83,10 @@ export function startMessage(value) {
     }
     return null;
 }
-/** Two ends of an in-memory channel: one process composing both roles (tests and the desktop host), same messages. */
 export function memoryChannel(role) {
     const toParent = [];
     const toRole = [];
     const stops = [];
-    // Delivered on a later turn, as IPC would be, and through the same checks: a role can't lean on synchronous replies.
     const later = (fn) => { queueMicrotask(fn); };
     return {
         port: {
@@ -128,42 +106,25 @@ export function memoryChannel(role) {
         },
     };
 }
-/** A build identity: the version and the exact code of the module that composes `up`. Both roles must report the
- * parent's own, or the parent stops rather than run a console and a worker from different builds. */
 export function buildIdentity(version, moduleFile) {
     let digest = `unreadable-${randomUUID()}`;
     try {
         digest = createHash("sha256").update(readFileSync(moduleFile)).digest("hex").slice(0, 16);
     }
-    catch { /* unique: never equal to any other identity */ }
+    catch { }
     return `${version}+${digest}`;
 }
-/** How many replacements in a row may end before becoming ready, with no refusal said, before `up` stops. */
 export const ROLE_NOT_READY_REPLACEMENTS = 3;
-/**
- * One supervised role's generations (Codex review round 1, finding 5): readiness is per generation, not for the role's
- * whole life. When a generation ends, the verdict is:
- * - `fail-start`: the role never became ready at all; the start fails as one, as before the split;
- * - `restart`: this generation was ready and crashed afterwards (the supervisor starts it again);
- * - `end`: a replacement refused to start (another build, another database, a start refused) — permanent, so the whole
- *   `up` stops rather than loop — or ROLE_NOT_READY_REPLACEMENTS replacements in a row ended before readiness.
- */
 export class RoleGenerations {
     everReady = false;
     generationReady = false;
     refusal = null;
     notReadyStreak = 0;
-    /** A new generation was spawned: nothing about it is known yet. */
     spawned() { this.generationReady = false; this.refusal = null; }
-    /** This generation became ready; true when it is the role's first readiness ever. */
     ready() { const first = !this.everReady; this.everReady = true; this.generationReady = true; return first; }
-    /** This generation refused its start for good (it said why, or its build is another). */
     refused(detail) { this.refusal = detail; }
-    /** What this generation said when it refused, if it did. */
     refusedWith() { return this.refusal; }
-    /** Whether any generation ever became ready. */
     wasReady() { return this.everReady; }
-    /** This generation ended (not stopped by `up`): what happens next. */
     ended() {
         if (!this.everReady)
             return "fail-start";

package/dist/up-role-child.js

@@ -1,14 +1,8 @@
-/**
- * Started only by `toolroll up` (up-processes.ts): one of its two roles, the console or the worker, in a process of
- * its own. It takes its whole start from the parent over the IPC channel (never from arguments or the environment, so
- * the runner token is in no process listing), and stops when the parent says so or goes away.
- */
 import { parentMessage, startMessage } from "./up-processes.js";
 if (process.send === undefined || !process.connected) {
     process.stderr.write("This process is started by `toolroll up`; run `toolroll up` instead.\n");
     process.exit(2);
 }
-// node:sqlite still says it is experimental; the CLI hushes exactly that notice, and so does a role.
 const emitWarning = process.emitWarning.bind(process);
 process.emitWarning = ((warning, ...rest) => {
     const type = typeof rest[0] === "string" ? rest[0] : rest[0]?.type;
@@ -29,18 +23,14 @@ const port = {
         try {
             process.send?.(message);
         }
-        catch { /* the parent is gone; its loss stops this role */ }
+        catch { }
     } },
     onMessage: handler => { handlers.push(handler); },
     onStop: handler => { stops.push(handler); if (stopRequested)
         handler(false); },
 };
-// A terminal's Ctrl-C reaches the whole process group: the parent decides what a signal means (drain, then a hard
-// stop on the second), so a role never acts on SIGINT itself. SIGTERM (the supervisor's stop) drains, once.
 process.on("SIGINT", () => { });
 process.on("SIGTERM", () => stop(false));
-// The parent gone (its channel closed): drain, as a stop would. The worker's own grace timer bounds it; past a minute
-// with nobody left to stop it, the role stops its work outright and ends, never running on as an orphan.
 process.once("disconnect", () => {
     stop(false);
     setTimeout(() => { stop(true); setTimeout(() => process.exit(1), 5_000).unref(); }, 60_000).unref();
@@ -50,7 +40,6 @@ const start = await new Promise(resolve => {
     process.once("message", value => { clearTimeout(timer); resolve(value); });
 });
 const checked = startMessage(start);
-// The role named on the command line (for a process listing) and the one started must be the same.
 if (checked === null || checked.role !== process.argv[2]) {
     process.stderr.write("The start message from `toolroll up` was not understood.\n");
     process.exit(2);
@@ -74,7 +63,6 @@ try {
 catch (error) {
     port.send({ type: "fatal", detail: error instanceof Error ? error.message : String(error) });
 }
-// Everything this role owned is closed; leave promptly even if a stray handle lingers.
 if (process.connected)
     process.disconnect?.();
 setTimeout(() => process.exit(code), 200).unref();

package/dist/update-notice.js

@@ -1,4 +1,3 @@
-/** The update notice's words, shared by the server page and the console. Plain text; callers escape. */
 export function updateNoticeWords(notice) {
     return notice.security ? `Toolroll ${notice.version} is available, with security fixes` : `Toolroll ${notice.version} is available`;
 }

package/dist/vanished-retry.js

@@ -1,39 +1,16 @@
-/**
- * A build that vanished: its process died with its runner, so no one settled it (docs/plans/plain-toolroll.md P2.1).
- *
- * Every recovery road (a dead runner, a takeover, a superseded watch) ends here, in its own transaction. The vanished
- * attempt is charged one strike, once, whoever recovers it: `vanished_charge` is keyed by the run, so a second recoverer
- * or a later pass charges nothing, and restarting can no longer evade MAX_STRIKES.
- *
- * Toolroll retries by itself only inside an episode (`retry_episode`: the automatic retries and reserved spend since the
- * last person act), at most RETRY_LIMIT retries and RETRY_SPEND_TIMES the plan's budget, each claim reserving its whole
- * budget against that ceiling. A vanished attempt's spend is unknown, so its reservation is never given back. A plan
- * with no budget bounds nothing and gets no automatic retry. A prepared candidate runs a machine check and no agent, so
- * it spends nothing and needs no budget; it still counts its attempts.
- *
- * Stop, hold, archive and approval standing are re-read here, and each keeps the retry from dispatching: the task stays
- * in the queue where that gate holds it, as a person's stop always has, reserving nothing, until a person acts. A
- * process not yet proven stopped holds the task until it is (retryVanishedWhenStopped, every sweep): the retry never
- * starts beside the old attempt.
- */
 import { authorityStandsSql } from "./approval-authority.js";
 import { stopFactOf } from "./store.js";
 import { refArchived } from "./task-archive.js";
 import { moveTask } from "./task-moves.js";
-/** The automatic-retry limits, in one place. */
 export const RETRY_LIMIT = 3;
 export const RETRY_SPEND_TIMES = 2;
-/** claim.ts MAX_STRIKES (store.ts loads this file, so the claim road isn't imported here; a test pins them equal). */
 export const VANISHED_MAX_STRIKES = 3;
-/** The newest attempt that spends: repair children ride their parent's attempt, and a reviewer has no task claim. */
 function attemptOf(store, taskRef) {
     const row = store.handle.prepare("SELECT id, role, outcome, reason FROM run WHERE task_ref = ? AND role IN ('builder', 'scout', 'planner') ORDER BY id DESC LIMIT 1").get(taskRef);
-    // A planner spends no approved budget and has its own strikes: it goes back to the queue as it always has.
     if (row === undefined || String(row["role"]) === "planner")
         return null;
     return { id: Number(row["id"]), outcome: row["outcome"] === null ? null : String(row["outcome"]), reason: row["reason"] === null ? null : String(row["reason"]) };
 }
-/** Whether any run of this task still has a process no record proves stopped. */
 function processUnsettled(store, taskRef) {
     for (const run of store.runsFor(taskRef)) {
         const fact = stopFactOf(store, run.id);
@@ -42,7 +19,6 @@ function processUnsettled(store, taskRef) {
     }
     return false;
 }
-/** dispatch.ts scopeApprovedForDispatch, read here because store.ts loads this file. */
 function approvalStands(store, taskRef, now) {
     const stamp = now.toISOString();
     return store.handle.prepare(`SELECT 1 AS hit FROM task_scope JOIN task_ref ON task_ref.id = ? AND task_scope.task_id = task_ref.external_id
@@ -72,13 +48,7 @@ function stopFor(store, input) {
     }, input.now);
     return "stopped";
 }
-/** The custody wait's hold: nothing starts beside a process no record proves stopped, and it never lapses by itself. */
 const waitHold = (taskRef) => `vanished:${taskRef}`;
-/**
- * The one recovery decision, once per run. The caller has proved the runner gone; this re-reads everything else. A
- * task a tick claimed never left `queued`, so releasing its lease alone would dispatch it again: what stops a retry here
- * is the state or hold this writes, in this transaction. Safe to call again: the run is charged once, decided once.
- */
 export function settleVanished(store, taskRef, now) {
     return store.transact(() => {
         if (store.currentLiveLease(taskRef, now) !== null)
@@ -91,14 +61,10 @@ export function settleVanished(store, taskRef, now) {
         if (task === null)
             return "none";
         const attempt = attemptOf(store, taskRef);
-        // No attempt, or one a real outcome already settled: nothing vanished here, and recovery only unsticks the task.
         if (attempt === null || (attempt.outcome !== null && attempt.reason !== "interrupted"))
             return requeue(store, taskId, now) ? "queued" : "none";
-        // Still open: its recoverer closes it and comes back here, in the same transaction. Nothing is decided on a run that
-        // may not be over.
         if (attempt.outcome === null)
             return requeue(store, taskId, now) ? "queued" : "none";
-        // A person's stop isn't a vanish: nothing is charged, and its hold keeps the task where the stop always has.
         if (store.handle.prepare("SELECT 1 AS hit FROM run_stop WHERE run = ?").get(attempt.id) !== undefined)
             return requeue(store, taskId, now) ? "queued" : "none";
         const stamp = now.toISOString();
@@ -114,8 +80,6 @@ export function settleVanished(store, taskRef, now) {
             settled();
             return "none";
         }
-        // Blocked by something a person holds: back to the queue, where that gate keeps it. Nothing is reserved, because
-        // nothing starts until that person acts.
         const held = store.handle.prepare("SELECT 1 AS hit FROM hold WHERE task_ref = ? AND owner_kind <> 'backoff' AND (until IS NULL OR until > ?) LIMIT 1").get(taskRef, stamp);
         if (held !== undefined || refArchived(store, taskRef) || !approvalStands(store, taskRef, now)) {
             settled();
@@ -146,7 +110,6 @@ export function settleVanished(store, taskRef, now) {
         return "queued";
     });
 }
-/** Each sweep: a charged run whose old process wasn't yet proven stopped gets its decision now. */
 export function retryVanishedWhenStopped(store, now) {
     const waiting = store.handle.prepare("SELECT DISTINCT task_ref FROM vanished_charge WHERE settled_at IS NULL").all();
     let moved = 0;
@@ -159,16 +122,13 @@ export function retryVanishedWhenStopped(store, now) {
         store.bumpWake();
     return moved;
 }
-/** A person acted, so a new episode starts. The strikes are theirs to clear on their own road. */
 export function clearRetryEpisode(store, taskRef) {
     store.handle.prepare("DELETE FROM retry_episode WHERE task_ref = ?").run(taskRef);
 }
-/** Why Toolroll stopped retrying this task, or null: it reads as a need until a person acts. */
 export function vanishedStopOf(store, taskRef) {
     const row = store.handle.prepare("SELECT stopped, stopped_run FROM retry_episode WHERE task_ref = ? AND stopped IS NOT NULL").get(taskRef);
     return row === undefined ? null : { why: String(row["stopped"]), run: Number(row["stopped_run"]) };
 }
-/** The need's words: the first stop on a plan with no budget, or a limit reached. */
 export function vanishedStopSentence(stop) {
     const build = stop.run === null ? "This build" : `Build #${stop.run}`;
     return stop.why === "no-budget" ? `${build} stopped unexpectedly. Retry it.` : `${build} keeps stopping. Retry, or change the plan.`;

package/dist/verification-evidence.js

@@ -1,8 +1,4 @@
-// Verified-build assignment completion reuses these gate checks.
 import { observationBrief, readObservationEvidence } from "./observations.js";
-/** Machine verification receipts use the existing sealed artifact store (schema
- * 60). Verbose output is independently bounded; no agent-authored check claim
- * can create or replace this receipt. */
 import { createHash } from "node:crypto";
 import { adjudicate } from "./proof.js";
 import { parseReviewContext, reviewContextCustodyProblem } from "./review-context.js";
@@ -18,18 +14,11 @@ export const VERIFICATION_RECEIPT_CAPTURE = "machine verification receipt v1";
 const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
 const binding = (a) => ({ artifactId: a.id, sha256: a.sha256, bytesStored: a.bytesStored, bytesOriginal: a.bytesOriginal, truncated: a.truncated, redacted: a.redacted, captureStatus: a.captureStatus });
 export const isVerificationReceipt = (a) => a.kind === "structured-output" && (a.capture === VERIFICATION_RECEIPT_CAPTURE || a.capture === "machine verification reuse v1");
-/** Whether a coverage lets a check pass: only full or composed (absent: a check that isn't a release check). */
 export const coveragePasses = (coverage) => coverage === undefined || coverage === "full" || coverage === "composed";
-/**
- * THE one place a release check's coverage meets its outcome (security review): a check whose coverage is partial or
- * identity-removed is a failed attempt for every reader — the verdict, the run's check, the receipt's `result`, reuse,
- * follow-ups, the deploy gates — whatever its command exited with. The raw exit is kept in the receipt's `check`.
- */
 export function effectiveCheckFacts(raw, facts) {
     if (facts === null || coveragePasses(facts.coverage))
         return { result: raw, facts };
     const exitCode = raw.configured && raw.ran ? raw.exitCode : null;
-    // A check that stopped before it could report keeps its own failure (it timed out, Toolroll stopped it): that is why.
     if (facts.coverage === "no-result" && raw.configured && !raw.ran)
         return { result: raw, facts };
     return { result: { configured: true, ran: false, attemptFailed: true, failure: facts.coverage === "no-result" ? "no-result" : "coverage-incomplete" }, facts: { ...facts, check: { ...facts.check, exitCode } } };
@@ -48,16 +37,10 @@ export function sealVerificationReceipt(store, root, runId, head, command, resul
     const checked = readVerificationReceipt(receipt);
     if (!checked.ok)
         throw new Error(`The verification receipt does not match its contract: ${checked.issues.map(issue => issue.line).join("; ")}`);
-    // Sealed in the writer's own key order, as every receipt before the schema: its bytes and digests stay comparable.
     const raw = JSON.stringify(receipt, null, 1);
     const hits = scanForSecrets(raw);
     storeEvidence(store, root, runId, "structured-output", "verification-receipt.json", Buffer.from(hits.length ? redactSecretLines(raw, hits) : raw), reusedFrom === undefined ? VERIFICATION_RECEIPT_CAPTURE : "machine verification reuse v1", now, { captureStatus: "ok", redacted: hits.length > 0 });
 }
-/** Read and bind existing evidence, never backfill historical receipts. A legacy
- * single-attempt machine header is sufficient only with its exact approved grant
- * and sealed candidate endpoints. Recovery logs without a receipt stay explicit. */
-// Recovery reads this existing receipt binding, then requires an actually executed
-// v1 passing gate. This reader does not rerun checks or transfer a prior approval.
 export function verificationEvidence(store, root, runId) {
     const fail = (problem) => ({ ok: false, problem });
     const source = store.getRun(runId);
@@ -68,10 +51,8 @@ export function verificationEvidence(store, root, runId) {
     const receipts = artifacts.filter(isVerificationReceipt);
     const machine = store.proofVerdictFor(runId);
     const verified = (machine?.machineVerdict ?? machine?.verdict) === "verified";
-    // A run whose checks were Off recorded no check; that is not a gap.
     if (!receipts.length && !verified && runCheckLevel(store, runId) === "off")
         return { ok: true, bytes: null, digest: hash(null) };
-    // A Quick run is bound to the project's approved quick command, a Full one to the full command.
     const command = repo ? sealedCommandKey(root, receipts) === quickVerifyKey(repo) ? liveQuickCommand(store, repo) : store.liveVerifyCommand(repo) : null;
     if (!command && !receipts.length && !verified)
         return { ok: true, bytes: null, digest: hash(null) };
@@ -100,8 +81,6 @@ export function verificationEvidence(store, root, runId) {
         catch {
             return fail("The verification receipt cannot be read.");
         }
-        // The schema checks the shape; the bindings below check it against the store. The receipt itself stays exactly
-        // as sealed: its bytes are this view's bytes and part of its digest.
         const read = readVerificationReceipt(receipt);
         if (!read.ok)
             return fail(`The verification receipt is malformed: ${read.issues.map(issue => issue.line).join("; ")}`);
@@ -134,8 +113,6 @@ export function verificationEvidence(store, root, runId) {
         }
         else if (checked.reusedFrom !== undefined || checked.executedHere !== undefined)
             return fail("The gate reuse receipt has an unsupported version.");
-        // Version 3, a release check (release-once.md): its attempt, sealed before it ran, and its sealed artifacts must be
-        // the ones it names; a composed one has every link proved again from sealed artifacts and the store.
         if (receipt.version === 3) {
             if (checked.coverage === undefined || checked.check === undefined)
                 return fail("The release check receipt names no coverage.");
@@ -145,8 +122,6 @@ export function verificationEvidence(store, root, runId) {
             const sha = (capture) => { const found = artifacts.filter(a => a.kind === "structured-output" && a.capture === capture); return found.length === 1 ? found[0].sha256 : null; };
             if (sha(CHECK_REPORT_CAPTURE) !== checked.check.report || sha(CHECK_INVENTORY_CAPTURE) !== checked.check.inventory)
                 return fail("The release check's sealed report or inventory changed.");
-            // Their bytes too, not only their records (eval-harness review 1, finding 3): a report or inventory the receipt
-            // names that is missing, cut short or changed on disk no longer verifies.
             for (const capture of [CHECK_REPORT_CAPTURE, CHECK_INVENTORY_CAPTURE]) {
                 const one = artifacts.find(a => a.kind === "structured-output" && a.capture === capture);
                 if (one === undefined)
@@ -156,7 +131,6 @@ export function verificationEvidence(store, root, runId) {
             }
             if ((checked.coverage === "composed") !== (checked.composed !== undefined))
                 return fail("The release check's coverage and its links disagree.");
-            // A check that didn't cover what it owed can never read as a pass.
             if (!coveragePasses(checked.coverage) && checked.result.configured && checked.result.ran && checked.result.exitCode === 0)
                 return fail("The release check reads as passed, but its coverage fell short.");
             if (checked.composed !== undefined) {
@@ -217,12 +191,9 @@ export function verificationEvidence(store, root, runId) {
         const view = { version: 1, source: LEGACY_GATE_SOURCE, run: runId, head: source.headRevision, base: source.baseRevision, scopeDigest: source.scopeDigest, command, result: { configured: true, ran: true, exitCode }, log: binding(log), candidate: binding(stat[0]) };
         receipt = view;
     }
-    // The view preserves shortened/redacted status and does not claim the omitted
-    // output exists. Its fingerprint is re-proved before every turn and ingestion.
     const bytes = JSON.stringify(receipt);
     return { ok: true, bytes, digest: hash({ receipt, receipts }) };
 }
-/** The grant key a run's single sealed receipt names, read without trusting it further. */
 function sealedCommandKey(root, receipts) {
     if (receipts.length !== 1)
         return null;
@@ -237,10 +208,6 @@ function sealedCommandKey(root, receipts) {
         return null;
     }
 }
-/** Only a sealed failed check can start unattended diagnosis. Lost custody,
- * changed approvals/trees and incomplete evidence still need attention; they
- * must not become another code-writing attempt. Keep the log out of the small
- * revision artifact and re-read it when the repair builder starts. */
 export function failedVerificationEvidence(store, root, runId) {
     if (!store.artifactsFor(runId).some(isVerificationReceipt))
         return { kind: "none" };
@@ -265,10 +232,6 @@ export function failedVerificationEvidence(store, root, runId) {
         return { kind: "unavailable", problem: "The failed-check log no longer verifies." };
     return { kind: "failed", digest: verified.digest, receipt: verified.bytes, log: read.content.toString("utf8") };
 }
-/** A fresh review may assess a pre-upgrade result which stopped solely because
- * no builder proof was written. Read original sealed facts; never run checks,
- * backfill receipts, rewrite artifacts, or reuse a different candidate's gate.
- * Called inside review ingestion, after its exact bindings have been proved. */
 export function assessmentFromSavedEvidence(store, root, runId) {
     const previous = store.proofVerdictFor(runId);
     if (previous?.verdict !== "short" || previous.reasons.length !== 1 || previous.reasons[0] !== "no proof was written" ||
@@ -317,8 +280,6 @@ export function assessmentFromSavedEvidence(store, root, runId) {
         return null;
     }
 }
-/** Reuse is exclusive to a machine-authored observation revision, with its
- * own current approval and complete new observations. Never synthesize a pass. */
 export function reuseObservationVerification(store, root, runId, now) {
     const run = store.getRun(runId);
     if (!run)

package/dist/version.js

@@ -1,5 +1,4 @@
 import { readFileSync } from "node:fs";
-/** The package's own version, read from package.json beside dist/ or src/ — one source, never a literal. */
 export const PACKAGE_VERSION = (() => {
     try {
         return String(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0");

package/dist/wake-hub.js

@@ -1,29 +1,9 @@
-/**
- * One shared wake poller per process (docs/plans/live-wakeups.md, slice 3).
- *
- * Every dispatch loop and build lane used to doze by reading `wakeSeq()` from SQLite every 50 ms on its own, so a
- * service with twelve projects and eight lanes made hundreds of reads a second while idle. The hub keeps ONE timer
- * per store: it runs only while something waits, reads the counter once per beat, and resolves each waiter whose
- * baseline the counter has passed.
- *
- * - A waiter resolves with why: "wake" (the counter moved past its baseline), "deadline" (its time came), or "poke"
- *   (its `until` became true, or someone poked it directly: a stop, a lost lease, a recovered reconciliation).
- * - No lost wakeup. The counter only ever moves forward, so a bump that lands after the caller read its baseline and
- *   before it registered is seen on the very next read. Registration is synchronous; nothing yields in between.
- * - Every waiter is checked on every beat (50 ms, well inside the one-second floor the plan asks for), including its
- *   `until`, which must be cheap and in-memory: it never reads the database.
- * - The hub only gives promptness, never permission: claim and spawn fences re-prove everything after a wake.
- * - Nothing here watches files or listens to commits. The timer is cleared as soon as nobody waits, so a stopped
- *   worker (or a finished test) keeps no timer alive.
- */
-/** Something a caller can poke to end the waits registered with it, now (a stop, a lost lease, a recovery). */
 export class WakePoker {
     listeners = new Set();
     poke() {
         for (const listener of [...this.listeners])
             listener();
     }
-    /** @internal */
     listen(listener) {
         this.listeners.add(listener);
         return () => { this.listeners.delete(listener); };
@@ -46,7 +26,6 @@ export class WakeHub {
         this.setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
         this.clearTimer = options.clearTimer ?? (handle => clearTimeout(handle));
     }
-    /** Wait until the counter passes `baseline`, the deadline comes, or the waiter is poked. */
     changed(waiter) {
         return new Promise((resolve, reject) => {
             let unlisten = () => { };
@@ -70,7 +49,6 @@ export class WakeHub {
             this.waiters.add(entry);
             if (waiter.poker !== undefined)
                 unlisten = waiter.poker.listen(() => entry.settle("poke"));
-            // Already true (a stop that landed before the wait, a deadline in the past): no beat needed.
             if (waiter.until?.() === true) {
                 entry.settle("poke");
                 return;
@@ -82,16 +60,12 @@ export class WakeHub {
             this.arm();
         });
     }
-    /** End every wait in this process now (the service's stop signal). */
     poke() {
         for (const entry of [...this.waiters])
             entry.settle("poke");
     }
-    /** How many waits are open (tests and diagnostics). */
     waiting() { return this.waiters.size; }
-    /** Whether the beat timer is running (tests). */
     running() { return this.timer !== null; }
-    /** How many counter reads the hub has made (tests: one per beat, whatever the number of waiters). */
     reads() { return this.readsMade; }
     arm() {
         if (this.timer !== null || this.waiters.size === 0)
@@ -114,7 +88,6 @@ export class WakeHub {
             seq = this.read();
         }
         catch (error) {
-            // A read that fails reaches every waiter, as the loops' own read used to: nothing is silently swallowed.
             for (const entry of [...this.waiters])
                 entry.fail(error);
             return;
@@ -140,7 +113,6 @@ export class WakeHub {
     }
 }
 const hubs = new WeakMap();
-/** The one hub for this store (one per process under `up`, which shares a store across project loops). */
 export function wakeHubFor(store) {
     let hub = hubs.get(store);
     if (hub === undefined) {

package/dist/webhook-limits.js

@@ -1,10 +1,7 @@
-/** At most this many unproven deliveries per address a minute; over it, further ones are answered 429 and do nothing. */
 export const UNPROVEN_PER_MINUTE = 60;
 const WINDOW_MS = 60_000;
-/** Addresses that match no trigger share one count. */
 export const UNKNOWN_ADDRESS = "unknown";
 const counters = new WeakMap();
-/** Count one unproven delivery to `address` at `now`. Whether it is over the minute's limit, and when to try again. */
 export function countUnproven(store, address, now) {
     let counter = counters.get(store);
     if (counter === undefined) {
@@ -14,9 +11,7 @@ export function countUnproven(store, address, now) {
     const at = now.getTime();
     const recent = (counter.get(address) ?? []).filter(one => one > at - WINDOW_MS);
     recent.push(at);
-    // Keep at most one over the limit: the count only needs to know it is over, and memory stays bounded per address.
     counter.set(address, recent.slice(-(UNPROVEN_PER_MINUTE + 1)));
-    // Bounded across addresses too: the oldest addresses are forgotten first.
     if (counter.size > 10_000)
         counter.delete(counter.keys().next().value);
     if (recent.length <= UNPROVEN_PER_MINUTE)
@@ -24,7 +19,5 @@ export function countUnproven(store, address, now) {
     const oldest = recent[recent.length - UNPROVEN_PER_MINUTE - 1];
     return { over: true, retryAfterSeconds: Math.max(1, Math.ceil((oldest + WINDOW_MS - at) / 1000)) };
 }
-/** At most this many cards a trigger makes in a rolling hour (counted when each card is made). */
 export const CARDS_PER_HOUR = 30;
-/** At most this many signed deliveries a trigger holds while it waits for room; beyond it, deliveries are turned away. */
 export const HELD_AT_MOST = 200;

package/dist/webhook-readers.js

@@ -1,26 +1,12 @@
-/**
- * What a proven webhook delivery says, read by its sender's reader (docs/plans/webhook-tasks.md §2). A signature proves
- * who sent a delivery, not that it belongs in this flow: Sentry's and Vercel's readers check its shape, its action and
- * the configured scope first, and only then give it an identity. Anything else is ignored, with why, and claims no
- * identity. The generic senders pick their fields by dot-paths. Every outside value is screened for secrets before it
- * is used anywhere (a key, a held item, a card, a task), and every link is made safe before it is kept.
- */
 import { scanForSecrets } from "./evidence.js";
 const HIDDEN = /[\u0000-\u001f\u007f​-‏‪-‮⁦-⁩]/;
 const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
 const pick = (body, path) => path.split(".").reduce((node, part) => record(node)[part], body);
 const text = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : null;
-/** A string or a safe integer, as an identity's words exactly as sent; anything else isn't one. */
 const idWords = (value) => typeof value === "string" ? value : typeof value === "number" && Number.isSafeInteger(value) ? String(value) : null;
-/** Whether outside words could hold a key or password (the same check cards' words get). */
 export const looksSecret = (value) => scanForSecrets(value).length > 0;
 export const SENTRY_HOSTS = [{ host: "sentry.io", subdomains: true }];
 export const VERCEL_HOSTS = [{ host: "vercel.com", subdomains: false }];
-/**
- * A link kept from a delivery: absolute https, at most 2,000 characters, no user information, and with its query and
- * fragment dropped (where tokens travel). `hosts` narrows it to a sender's own site (and its subdomains). Null when it
- * isn't one, or when what is left could still hold a secret.
- */
 export function safeLink(value, hosts) {
     if (typeof value !== "string" || value.length > 2000 || HIDDEN.test(value))
         return null;
@@ -37,10 +23,8 @@ export function safeLink(value, hosts) {
     if (hosts !== null && !hosts.some(one => host === one.host || (one.subdomains && host.endsWith(`.${one.host}`))))
         return null;
     const kept = `${url.origin}${url.pathname}`;
-    // Judged as it will be kept: an address that only normalises past 2,000 characters (escaped non-ASCII) isn't kept.
     if (kept.length > 2000)
         return null;
-    // Screened as kept and as read: a token spelled with percent-escapes is the same token. A path that won't decode isn't kept.
     let decoded;
     try {
         decoded = decodeURIComponent(url.pathname);
@@ -50,39 +34,31 @@ export function safeLink(value, hosts) {
     }
     return looksSecret(kept) || looksSecret(decoded) || HIDDEN.test(decoded) ? null : kept;
 }
-/** The identity words a key may carry: at most 120 characters, nothing hidden, and nothing that looks like a secret. */
 export function identityOf(value) {
     const sent = idWords(value);
     if (sent === null || sent.trim() === "")
         return { ok: false, why: "its identity is missing" };
-    // Judged as sent, before anything is trimmed: padding, hidden characters or length make it unusable, never another id.
     if (sent.length > 120 || HIDDEN.test(sent) || sent !== sent.trim())
         return { ok: false, why: "its identity isn't usable" };
     if (looksSecret(sent))
         return { ok: false, why: "it looked like it held a key or password" };
     return { ok: true, id: sent };
 }
-/** Sentry's API address for an event names its project's slug (…/api/0/projects/<org>/<project>/events/<id>/): read
- * only from that exact shape on Sentry's own host. */
 function sentrySlugOf(value) {
     const link = typeof value === "string" ? value : "";
     const match = /^https:\/\/(?:[a-z0-9-]+\.)?sentry\.io\/api\/0\/projects\/[a-z0-9_-]+\/([a-z0-9_-]+)\/events\/[A-Za-z0-9-]+\/?$/.exec(link);
     return match?.[1] ?? null;
 }
-/** Sentry: an issue alert (action "triggered", with the event) or a new issue (action "created", with the issue). */
 function readSentry(body, settings) {
     const action = text(record(body)["action"]);
     const data = record(record(body)["data"]);
     const alert = action === "triggered" && Object.keys(record(data["event"])).length > 0;
     const created = action === "created" && Object.keys(record(data["issue"])).length > 0;
-    // A fixed reason: nothing the sender wrote is kept for an event Toolroll doesn't take.
     if (!alert && !created)
         return { kind: "ignored", why: "not an issue alert or a new issue" };
     const thing = record(alert ? data["event"] : data["issue"]);
-    // Scope from the body alone (the resource header isn't signed): the project's id or slug, as Sentry sends it.
     if (settings.project !== null) {
         const project = record(thing["project"]);
-        // An alert's event names its project by number, and by slug only in its API address; a new issue names both.
         const names = [idWords(thing["project"]), idWords(project["id"]), text(project["slug"]), sentrySlugOf(thing["url"])].filter((one) => one !== null);
         if (!names.some(one => one.toLowerCase() === settings.project.toLowerCase()))
             return { kind: "ignored", why: "from another Sentry project" };
@@ -94,7 +70,6 @@ function readSentry(body, settings) {
     const culprit = text(thing["culprit"]);
     return { kind: "item", identity: identity.id, url: safeLink(thing["web_url"], SENTRY_HOSTS), title, description: culprit === null ? "From a Sentry issue." : `From a Sentry issue, in ${culprit}.`, label: "Sentry issue" };
 }
-/** Vercel: a failed deployment only, from the configured project and team. */
 function readVercel(body, settings) {
     const type = text(record(body)["type"]);
     if (type !== "deployment.error")
@@ -112,13 +87,11 @@ function readVercel(body, settings) {
     return { kind: "item", identity: identity.id, url: safeLink(record(payload["links"])["deployment"], VERCEL_HOSTS), title: name === null ? settings.title : `${name} failed to deploy`,
         description: "From a failed Vercel deployment.", label: "Vercel deployment" };
 }
-/** Any JSON: the trigger's own paths, then the usual names; shown whole when they find no text. */
 function readGeneric(body, settings) {
     const at = (path) => path === null ? undefined : pick(body, path);
     let identity = null;
     if (settings.idField !== null) {
         const read = identityOf(at(settings.idField));
-        // A configured identity that can't be used makes nothing: it never falls back to some other identity.
         if (!read.ok)
             return { kind: "skip", why: read.why };
         identity = read.id;
@@ -129,10 +102,7 @@ function readGeneric(body, settings) {
         title: typeof title === "string" && title.trim() !== "" ? title : settings.title,
         description: `From a webhook:\n\n${typeof details === "string" ? details : JSON.stringify(body, null, 2)}`.slice(0, 4000), label: "Webhook" };
 }
-/** Whether each provider's reader has read a real, captured delivery (test/fixtures/webhooks/*.captured.json), or only
- * its sender's documented examples so far: the panel says which until a captured one is in the suite. */
 export const READER_CAPTURED = { sentry: false, vercel: false };
-/** What a proven delivery says, by its sender's reader. */
 export function readDelivery(body, settings) {
     return settings.sender === "sentry" ? readSentry(body, settings) : settings.sender === "vercel" ? readVercel(body, settings) : readGeneric(body, settings);
 }