toolroll 0.9.104 → 0.9.105

package/dist/sync.js

@@ -1,24 +1,3 @@
-/**
- * External dispatch's sync pass (v20; five review rounds are the spec).
- *
- * What this does: pulls a tracker's nominated work into the overlay as
- * ORDINARY local tasks (mirrors), refreshes every known mirror's remote
- * state, verifies the plane marker, and delivers pending write-back
- * intents — all at daemon cadence, zero tokens.
- *
- * What this never does: touch claims or runs (the latch is a write to the
- * mirror row; admission and completion enforce it), import issue BODIES
- * (titles only, through the canonical proposal validator — a tracker
- * anyone can write to is a prompt-injection surface), or treat absence
- * from a capped listing as closure (every known mirror is fetched
- * INDIVIDUALLY; only a COMPLETE pass advances freshness).
- *
- * The plane marker is detection, never a distributed lease: a fixed-name
- * repository label carries this plane's id in its description. A 404 is
- * semantic "missing" only AFTER an authenticated access proof on the
- * repository itself — GitHub 404s private resources the caller cannot
- * see, and that must read as an OPERATIONAL block, fail closed.
- */
 import { createHash } from "node:crypto";
 import { run } from "./exec.js";
 import { describeFailure, parseJson } from "./backend.js";
@@ -26,7 +5,6 @@ import { fileTaskProposal } from "./proposal.js";
 const GH = "gh";
 export const SYNC_TIMEOUT_MS = 20_000;
 export const MARKER_LABEL = "standing-orders-plane";
-/** Bounded forward scan: pages of 100, at most this many pages per pass. */
 export const MAX_FORWARD_PAGES = 10;
 const operational = (message) => ({ ok: false, kind: "operational", message });
 export function ghDispatchAdapter(runner = run, timeoutMs = SYNC_TIMEOUT_MS) {
@@ -53,7 +31,6 @@ export function ghDispatchAdapter(runner = run, timeoutMs = SYNC_TIMEOUT_MS) {
                     return operational("gh returned something that is not a list");
                 for (const raw of parsed) {
                     const issue = readRemoteIssue(raw);
-                    // The issues API interleaves pull requests; a PR is not a task.
                     if (issue !== null && !(typeof raw === "object" && raw !== null && "pull_request" in raw)) {
                         issues.push(issue);
                     }
@@ -66,8 +43,6 @@ export function ghDispatchAdapter(runner = run, timeoutMs = SYNC_TIMEOUT_MS) {
         async getIssue(remoteRepo, number) {
             const result = await call(["api", `repos/${remoteRepo}/issues/${number}`]);
             if (result.code !== 0) {
-                // The caller has ALREADY proved authenticated access this pass, so a
-                // 404 here is the issue itself being gone.
                 return /404|Not Found/i.test(result.stderr) ? { ok: true, found: null } : operational(describeFailure(result));
             }
             const issue = readRemoteIssue(parseJson(result.stdout));
@@ -118,23 +93,14 @@ function readRemoteIssue(record) {
         state: String(raw["state"]).toLowerCase() === "closed" ? "closed" : "open",
     };
 }
-/** ghi-<owner>-<name>-<n>-<hash8>: collision-resistant across long slugs. */
 export function mirrorTaskId(remoteRepo, remoteId) {
     const hash = createHash("sha256").update(`${remoteRepo}#${remoteId}`).digest("hex").slice(0, 8);
     const slug = remoteRepo.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 30);
     return `ghi-${slug}-${remoteId}-${hash}`;
 }
-/**
- * One pass over one dispatch grant. Order is the spec's: access proof →
- * marker verdict → forward scan → reverse sweep (every known mirror,
- * individually) → intent delivery → ledger close. Only a pass in which
- * EVERY step succeeded closes `complete` and advances freshness.
- */
 export async function syncPass(store, grant, adapter, now) {
     const remoteRepo = grant.remoteRepo;
     const report = { remoteRepo, outcome: "failed", detail: null, candidates: 0, mirrored: 0, latched: 0, delivered: 0 };
-    // 1. Authenticated access proof — WITHOUT it, every 404 downstream is
-    //    operational, and dispatch blocks immediately (no grace window).
     const access = await adapter.repoAccess(remoteRepo);
     if (!access.ok) {
         store.setDispatchBlocked(grant.repo, grant.backend, "unreachable", now(), access.message);
@@ -142,7 +108,6 @@ export async function syncPass(store, grant, adapter, now) {
         report.detail = access.message;
         return report;
     }
-    // 2. The marker verdict — semantic states only from a complete response.
     const marker = await adapter.readMarker(remoteRepo);
     if (!marker.ok) {
         store.setDispatchBlocked(grant.repo, grant.backend, "unreachable", now(), marker.message);
@@ -168,18 +133,12 @@ export async function syncPass(store, grant, adapter, now) {
         report.detail = "foreign plane";
         return report;
     }
-    // A VERIFIED matching marker clears any standing block — transient or
-    // semantic — because verification is exactly what a block awaited. The
-    // LIVE row is read here; the caller's copy may predate the block.
     const live = store.grantFor(grant.repo, grant.backend);
     if (live?.dispatchBlocked != null) {
         store.setDispatchBlocked(grant.repo, grant.backend, null, now());
     }
     const pass = store.openSyncPass(grant.backend, remoteRepo, now());
     let capped = false;
-    // 3. Forward: candidates. Only selector=all ESTABLISHES from the scan —
-    //    'ours' mirrors are established at creation/intake, never nominated
-    //    by a listing (provenance is a record, not a label).
     const listing = await adapter.listAllOpen(remoteRepo);
     if (!listing.ok) {
         store.closeSyncPass(pass.id, "failed", { candidates: 0, mirrored: 0 }, now(), listing.message);
@@ -215,13 +174,9 @@ export async function syncPass(store, grant, adapter, now) {
         });
         if (filed.ok)
             report.mirrored += 1;
-        // A title the validator refuses is NOT mirrored — the pass records it
-        // in detail and stays honest about the count.
         else if (report.detail === null)
             report.detail = `refused: ${filed.message}`;
     }
-    // 4. Reverse: every known mirror, individually — absence from a listing
-    //    proves nothing (finding 2).
     let reverseFailed = null;
     for (const mirror of store.externalMirrors(grant.backend, remoteRepo)) {
         const seen = await adapter.getIssue(remoteRepo, mirror.remoteId);
@@ -246,8 +201,6 @@ export async function syncPass(store, grant, adapter, now) {
         report.detail = reverseFailed;
         return report;
     }
-    // 5. Intents, under the grant's classes exactly — a denial is a typed
-    //    refusal on the intent's own ledger, never a run rewrite.
     for (const intent of store.pendingExternalIntents()) {
         const mirror = store.mirrorByTask(intent.mirror);
         if (mirror === null || mirror.remoteRepo !== remoteRepo || mirror.backend !== grant.backend)

package/dist/tailnet.js

@@ -1,15 +1,7 @@
-/**
- * This computer's own names on its tailnet, when Tailscale is up: the console
- * answers to them on its port without an --allow-host, and the phone card
- * names the address to type. Read with `tailscale status --json`, which
- * spends nothing and changes nothing; any failure means no tailnet.
- */
 import { existsSync } from "node:fs";
 import { run } from "./exec.js";
-/** The Mac app ships its command line inside the app bundle. */
 const MAC_APP_CLI = "/Applications/Tailscale.app/Contents/MacOS/Tailscale";
 const NAME = /^[a-z0-9]([a-z0-9-]{0,62})(\.[a-z0-9]([a-z0-9-]{0,62}))*$/;
-/** The full MagicDNS name first (machine.tailnet.ts.net), then its short form (machine). Empty when Tailscale isn't running. */
 export function tailnetNamesOf(statusJson) {
     let status;
     try {
@@ -40,7 +32,6 @@ export async function readTailnetNames(runner = run, platform = process.platform
                 return tailnetNamesOf(answer.stdout);
         }
         catch {
-            // No Tailscale here: no tailnet names.
         }
     }
     return [];

package/dist/tamper-scan.js

@@ -1,13 +1,3 @@
-/**
- * A heuristic over changed code (docs/plans/trusted-release-reports.md, H4): the expressions that could reach the test
- * runner, compared whole. Round 1 of the plan counted these forms, and Codex's finding 5 was that a count misses an
- * edit: `process.exit(1)` becoming `process.exit(0)` counts the same. So this keeps each expression's text, its
- * arguments included, and each binding that aliases a runner object, and reports what the candidate has that the base
- * doesn't.
- *
- * It decides nothing. It isn't wired to any approval: it makes tampering visible, can't make it impossible, and the
- * rate at which it flags honest work is measured first (scripts/tamper-measure.mjs).
- */
 import { createRequire } from "node:module";
 let compiler;
 const typescript = () => compiler ??= createRequire(import.meta.url)("typescript-parser");
@@ -18,14 +8,12 @@ const IMPORTS = /^(?:node:)?process$|^@vitest\/|^vitest\/(?!config$)|^tinypool$|
 const HARNESS_WORDS = /node_modules\/|\/proc\/|RUNNER_|ACTIONS_|TOOLROLL_CHECK|shard-report|NODE_OPTIONS|\bsudo\b|__vitest/;
 const TEST_ENV = /^(?:VITEST.*|TOOLROLL_TEST.*|CI|NODE_ENV)$/;
 const TEST_FILE = /\.test\.[cm]?[jt]sx?$/;
-/** Every expression in `text` that could reach the runner, with its arguments, spaces collapsed. */
 export function runnerExpressions(path, text) {
     const tsc = typescript();
     const source = tsc.createSourceFile(path, text, tsc.ScriptTarget.Latest, true, /x$/.test(path) ? tsc.ScriptKind.TSX : tsc.ScriptKind.TS);
     const found = [];
     const said = (node) => found.push(node.getText(source).replace(/\s+/g, " ").slice(0, 200));
     const named = (node, names) => tsc.isIdentifier(node) && names.has(node.text);
-    // The call or assignment a member is part of, so what it is called with or set to counts.
     const whole = (node) => (tsc.isCallExpression(node.parent) && node.parent.expression === node) || (tsc.isBinaryExpression(node.parent) && node.parent.left === node) ? node.parent : node;
     const visit = (node) => {
         if (tsc.isImportDeclaration(node) && tsc.isStringLiteral(node.moduleSpecifier) && IMPORTS.test(node.moduleSpecifier.text))
@@ -58,12 +46,10 @@ export function runnerExpressions(path, text) {
         else if (tsc.isCallExpression(node) && tsc.isPropertyAccessExpression(node.expression) && node.expression.name.text === "defineProperty" && node.arguments[0] !== undefined
             && (named(node.arguments[0], TEST_GLOBALS) || named(node.arguments[0], RUNNER_OBJECTS)))
             said(node);
-        // A binding: another name for a runner object, or pieces taken out of one.
         else if (tsc.isVariableDeclaration(node) && node.initializer !== undefined && named(node.initializer, RUNNER_OBJECTS))
             said(node);
         else if (tsc.isStringLiteralLike(node) && HARNESS_WORDS.test(node.text))
             said(node);
-        // Product code telling a test from the real thing.
         if (!TEST_FILE.test(path) && tsc.isPropertyAccessExpression(node) && TEST_ENV.test(node.name.text) && tsc.isPropertyAccessExpression(node.expression) && node.expression.name.text === "env")
             said(node);
         if (!TEST_FILE.test(path) && tsc.isElementAccessExpression(node) && tsc.isStringLiteralLike(node.argumentExpression) && TEST_ENV.test(node.argumentExpression.text) && tsc.isPropertyAccessExpression(node.expression) && node.expression.name.text === "env")
@@ -73,7 +59,6 @@ export function runnerExpressions(path, text) {
     visit(source);
     return found;
 }
-/** What the candidate has that the base doesn't, as a multiset: an edited argument is a new expression, a moved one isn't. */
 export function tamperFindings(path, base, candidate) {
     const left = new Map();
     for (const one of base === null ? [] : runnerExpressions(path, base))

package/dist/task-activity.js

@@ -1,20 +1,7 @@
-/**
- * What a running agent did last, recorded and read (live tasks).
- *
- * The recorder sits beside the live log on the agent's stream and keeps one
- * row per run: a fixed kind from live.ts's vocabulary and when. No text, no
- * tool names, no arguments are ever kept, so nothing here can leak a secret.
- * The reader picks the newer of that row and the run's latest progress
- * checkpoint, and asks the runner's heartbeat whether the worker still
- * answers. Neither side reads or stats a live-log file.
- */
 import { ACTIVITY_WORDS } from "./activity-line.js";
 import { liveActivityKind } from "./live.js";
 import { isAlive } from "./runner.js";
-/** At most one write per run this often while the kind stays the same: the age is in seconds, not milliseconds. */
 const SAME_KIND_EVERY_MS = 5_000;
-/** Watch a run's stream for what the agent does, alongside its live log (which may be null). Fail-soft: a write
- * that fails never touches the run. */
 export function withRunActivity(liveLog, store, run, clock) {
     let last = null;
     return {
@@ -30,13 +17,11 @@ export function withRunActivity(liveLog, store, run, clock) {
                 store.recordRunActivity(run, kind, now);
                 last = { kind, at: now.getTime() };
             }
-            catch { /* display state: the next event tries again */ }
+            catch { }
         },
         close() { liveLog?.close(); },
     };
 }
-/** A live run's last activity: the newer of its recorded kind and its latest progress checkpoint, else when it
- * started; and "offline" only when its registered worker's heartbeat has lapsed. */
 export function runActivityOf(store, run, now) {
     const recorded = store.runActivity(run.id);
     let what = ACTIVITY_WORDS["started"], at = run.startedAt;

package/dist/task-aliases.js

@@ -1,7 +1,4 @@
-/** People's names for task commands (docs/plans/plain-toolroll.md P1.3): each is exactly the command it names, read
- * before anything else looks at the command, so a remote, local-owner or contract rule sees only the original. */
 export const TASK_ALIASES = { "send-back": "revise", retry: "requeue", recheck: "regate" };
-/** `task <alias> …` as the command it names; anything else unchanged. */
 export function withTaskAlias(argv) {
     if (argv[0] !== "task" || argv[1] === undefined || !Object.prototype.hasOwnProperty.call(TASK_ALIASES, argv[1]))
         return argv;

package/dist/task-archive.js

@@ -1,21 +1,14 @@
-/** Whether this task version is put away. Every door that dispatches, claims or approves asks this (fail closed: a
- * row means no). */
 export function refArchived(store, taskRef) {
     return store.handle.prepare("SELECT 1 FROM task_archive WHERE task_ref = ?").get(taskRef) !== undefined;
 }
-/** Whether the built-in task with this id is put away. */
 export function taskArchived(store, taskId) {
     return store.handle.prepare(`SELECT 1 FROM task_archive a JOIN task_ref r ON r.id = a.task_ref
     WHERE r.backend = 'built-in' AND r.external_id = ?`).get(taskId) !== undefined;
 }
-/** Whether a flow card's work is put away: its current task or its first build task (a later stage keeps the first
- * and may clear the current one). Read from the card's own row now, so a put away that committed first holds it. */
 export function cardTaskArchived(store, cardId) {
     return store.handle.prepare(`SELECT 1 FROM flow_card c JOIN task_ref r ON r.backend = 'built-in' AND r.external_id IN (c.task, c.primary_task)
     JOIN task_archive a ON a.task_ref = r.id WHERE c.id = ?`).get(cardId) !== undefined;
 }
-/** Whether the built-in task with this id is cancelled. Every door that approves, seals or carries a release asks
- * this beside the put-away check: a cancelled task takes no new yes (fail closed), by any road. */
 export function taskCancelled(store, taskId) {
     return store.handle.prepare("SELECT 1 FROM task WHERE id = ? AND state = 'cancelled'").get(taskId) !== undefined;
 }

package/dist/task-base.js

@@ -1,14 +1,6 @@
-/**
- * Where a task's work starts, against current main (fresh base): one view for
- * the task page and `task show`. The base is saved run lineage — a builder
- * branch's pinned origin, or the newest plan's base — and the behind count is
- * read from Git now. Reads only.
- */
 import { viewedGitSync } from "./teardown-git.js";
 export const readGit = (cwd, args) => {
     try {
-        // Every git version through a frozen read view, bounded (eval-harness review 1, finding 7): a partial clone, an
-        // include or a command-naming key is refused from the config git then runs with.
         const ran = viewedGitSync(cwd, args, { timeoutMs: 5_000, maxBuffer: 65_536 });
         return ran.status === 0 ? ran.stdout.trim() : null;
     }
@@ -17,18 +9,12 @@ export const readGit = (cwd, args) => {
     }
 };
 const commits = (count) => `${count} commit${count === 1 ? "" : "s"}`;
-/** The base line on its own, for surfaces that label it already: `9d087efe · Behind main by 2 commits`. */
 export function baseStandingWords(view) {
     const short = view.base.slice(0, 8);
     if (view.main === null || view.behind === null)
         return short;
     return view.behind === 0 ? `${short} · Up to date with ${view.main}` : `${short} · Behind ${view.main} by ${commits(view.behind)}`;
 }
-/**
- * The lease's fresh-base request for one attempt on `branch`, or nothing when the task's start is pinned elsewhere: a
- * revision keeps the head of the attempt it revises, and a prepared candidate or coding review keeps the base its
- * candidate was proved against.
- */
 export function freshBaseFor(store, taskId, branch, main) {
     const ref = store.lookupRef(taskId);
     if (ref === null || ref.revisionOf !== null || store.getScope(taskId)?.candidate != null || store.filedViaOf(taskId)?.startsWith("coding:") === true)
@@ -43,7 +29,6 @@ export function taskBaseOf(store, taskId, git = readGit) {
     if (latest === undefined || latest.branch === null || latest.baseRevision === null)
         return null;
     const branch = latest.branch;
-    // A move to current main newer than the latest attempt is where the next one starts.
     const move = store.latestBranchBaseMove(ref.id, branch);
     const base = move !== null && move.afterRun >= latest.id ? move.to : store.recordedBranchBase(ref.id, branch) ?? latest.baseRevision;
     const main = git(ref.repo, ["symbolic-ref", "--short", "-q", "HEAD"]) || null;
@@ -52,9 +37,6 @@ export function taskBaseOf(store, taskId, git = readGit) {
     const view = { base, branch, main: behind === null ? null : main, behind };
     return { ...view, words: `Base ${baseStandingWords(view)}` };
 }
-/** `git`'s answers kept for `ttlMs` (at most `entries` of them), for a page that shows the base line on every refresh:
- * each read still goes through the same frozen view when it runs; only its answer is reused for a moment. Display only —
- * never for a decision. */
 export function recentGitReads(git = readGit, ttlMs = 15_000, entries = 64, now = Date.now) {
     const kept = new Map();
     return (cwd, args) => {

package/dist/task-composer.js

@@ -1,4 +1,3 @@
-/** UI choices translate into the same digest-bound schedules as the CLI. */
 import { parseSchedule, scheduleText, validTimezone } from "./flow-schedule.js";
 import { html, joinHtml } from "./html.js";
 export function composerSchedule(fields) {
@@ -30,7 +29,6 @@ export function scheduleFields(schedule) {
     }
     return { repeat: schedule.kind, time: schedule.hhmm, timezone: schedule.timezone ?? "UTC", ...(schedule.kind === "weekly" ? { weekday: String(schedule.day) } : {}) };
 }
-/** A normal form works without JavaScript; enhancement only folds unused fields. */
 export function scheduleEditorHtml(raw, submitted) {
     const parsed = raw === null ? null : parseSchedule(raw);
     const fields = submitted?.has("repeat") ? Object.fromEntries(submitted) : parsed === null ? {} : scheduleFields(parsed);

package/dist/task-control.js

@@ -1,43 +1,12 @@
-/**
- * Safe task stop and resume (v52): the ONE domain API every surface — the
- * CLI, the authenticated console, the focused chat — speaks, and the fences
- * every execution road consults.
- *
- * The contract, in the operator's words: a stop names one exact active
- * attempt. The first answer is "stop requested", never "stopped" — the
- * request is durable before any process is signalled, and the attempt is
- * SETTLED only once all owned runs ended and retained process witnesses
- * establish exit. A dead worker can leave live subprocesses; recovery
- * keeps that stop pending. Other tasks keep running. The task stays
- * paused across restarts under a hold this stop owns, beside — never over —
- * any hold that already stood. Resume names the same exact attempt, refuses
- * until it is quiescent, lifts only that hold, approves nothing, and lets
- * the next pass re-prove the signed scope, take a fresh claim, and inherit
- * the preserved draft with fresh proof.
- *
- * Nothing here is a second engine: the stop rides the existing run, claim,
- * hold, recovery, and invocation-gateway machinery. This
- * module only names the door and the fence.
- */
 import { existsSync } from "node:fs";
 import { ownedProcessCount, runOwnerTag, terminateOwnedProcesses } from "./exec.js";
 import { diagnoseTaskDispatch } from "./dispatch.js";
-/** How often a running attempt re-reads its stop row while a child runs.
- * A stop is observed within this bound even when the console that filed
- * it lives in another process on the same database. */
 export const STOP_WATCH_MS = 1_500;
-/**
- * The stop fence, as a predicate: an operator stop applies to the run (its
- * own, or an owning ancestor's), or the caller's own watch-level stop says
- * so. Every road that used to ask `shouldStop?.()` asks this instead.
- */
 export function stopRequestedFor(store, runId, also) {
     if (also?.() === true)
         return true;
     return store.applicableStopFor(runId) !== null;
 }
-/** The words a road records when a stop wins: who asked, and where the
- * work stays. */
 export function stopWords(store, runId, worktree, fallback) {
     const stop = store.applicableStopFor(runId);
     if (stop === null)
@@ -45,30 +14,15 @@ export function stopWords(store, runId, worktree, fallback) {
     const where = worktree === null ? "its evidence is on record" : `the work is preserved in ${worktree}`;
     return `stopped by ${stop.requestedBy} (run #${stop.run}) — ${where}`;
 }
-/**
- * End every live child THIS process holds for one attempt and its owned
- * descendants — the exact-attempt handle, never a pid read from durable
- * state. Returns how many process groups were signalled.
- */
 export function terminateStoppedAttempt(store, runId) {
     let terminated = 0;
     for (const owned of store.ownedRunsOf(runId))
         terminated += terminateOwnedProcesses(runOwnerTag(store, owned));
     return terminated;
 }
-/** Whether this process still tracks a live child for the attempt or any
- * run it owns — the in-process half of "quiescent". */
 export function attemptHasLiveChildren(store, runId) {
     return store.ownedRunsOf(runId).some(owned => ownedProcessCount(runOwnerTag(store, owned)) > 0);
 }
-/**
- * Run a child-bearing step under the stop watch: while `body` runs, the
- * run's stop row is re-read every `intervalMs`; the moment a stop applies
- * the run's owned children are killed through their handles and the
- * caller's `onStop` fires once. The body's own settlement then observes
- * the stop through `stopRequestedFor` and seals the attempt as
- * interrupted — this watch never writes an outcome itself.
- */
 export async function underStopWatch(store, runId, body, options = {}) {
     let fired = false;
     const look = () => {
@@ -77,15 +31,11 @@ export async function underStopWatch(store, runId, body, options = {}) {
             applies = store.applicableStopFor(runId) !== null;
         }
         catch {
-            // A read that cannot reach the database proves nothing; the next
-            // beat asks again, and settlement asks one last time.
             return;
         }
         if (!applies)
             return;
         terminateStoppedAttempt(store, runId);
-        // A later asynchronous step may have spawned since the previous beat.
-        // Keep stopping children; only the notification is one-shot.
         if (fired)
             return;
         fired = true;
@@ -93,7 +43,6 @@ export async function underStopWatch(store, runId, body, options = {}) {
             options.onStop?.();
         }
         catch {
-            // The watch's job is the kill; a listener's throw is its own.
         }
     };
     look();
@@ -106,13 +55,6 @@ export async function underStopWatch(store, runId, body, options = {}) {
         clearInterval(timer);
     }
 }
-/**
- * The shared stop door. Records the durable request first (one fenced
- * transaction: exact run, still open, this task's current claim, no
- * admitted publication), THEN signals every child this
- * process holds for the attempt. A worker in another process observes the
- * same row through its stop watch within STOP_WATCH_MS.
- */
 export function requestTaskStop(store, request, now) {
     const ref = store.lookupRef(request.taskId);
     if (ref === null || store.getTask(request.taskId) === null) {
@@ -131,16 +73,6 @@ export function requestTaskStop(store, request, now) {
         signal();
     return { ok: true, stop: asked.stop, repeated: asked.repeated, terminated, taskId: request.taskId };
 }
-/**
- * The shared resume door. Refuses in words until the exact stopped attempt
- * is quiescent — settled, every owned run ended, no live claim, its
- * workspace not held by any process this machine can still see — then
- * lifts exactly this stop's hold. `gate` reports what still keeps the
- * next pass from starting work (an approval that must be signed again, a
- * worker that is offline), so a resume that cannot yet start is never
- * mistaken for one that did. A stopped review is refused here and pointed
- * at the explicit bounded review-retry door.
- */
 export function resumeTaskStop(store, request, now) {
     const ref = store.lookupRef(request.taskId);
     if (ref === null || store.getTask(request.taskId) === null) {
@@ -162,9 +94,6 @@ export function resumeTaskStop(store, request, now) {
     const gate = diagnoseTaskDispatch(store, request.taskId, now);
     return { ok: true, stop: resumed.stop, taskId: request.taskId, gate: gate === null || gate.condition === "running" ? null : gate };
 }
-/** The head of a lease group: a run whose parent (if any) ran under a
- * different lease — a builder, a planner, a scout, a recovered-draft
- * successor, a warm park resume; never a repair turn or a correction. */
 function isAttemptRoot(store, run) {
     if (run.role === "reviewer")
         return run.reviewAttempt !== null && run.reviewAttempt !== undefined;
@@ -185,8 +114,6 @@ export function taskControlOf(store, taskRef, now) {
         if (stop === null)
             return { kind: "stop", run: live.id, role: live.role };
     }
-    // A stop recorded but unsettled on a run that already ended is still
-    // "stopping" — visibly needing attention, never silently paused.
     const pending = store.stopsForTask(taskRef).find(stop => stop.settledAt === null) ?? null;
     if (pending !== null) {
         const run = store.getRun(pending.run);
@@ -197,7 +124,6 @@ export function taskControlOf(store, taskRef, now) {
         const stop = store.stopOf(newest.id);
         if (stop !== null && stop.settledAt !== null && stop.resumedAt === null) {
             return { kind: "paused", run: newest.id, role: newest.role, stop, outcome: newest.outcome, committed: newest.committed === true,
-                // A folder idle cleanup removed held nothing uncommitted: a later run makes it again from the branch.
                 worktree: newest.worktree !== null && existsSync(newest.worktree) ? newest.worktree : null };
         }
     }

package/dist/task-live.js

@@ -1,28 +1,7 @@
-/**
- * The live task page (live tasks): a task open in several browsers stays the
- * same in all of them, and each shows who else has it open. The same design
- * as the live canvas (flow-live.ts):
- *
- * - A change nudge. When the live bus says the workspace was written
- *   (live-bus.ts), one indexed read keyed by the task family's root takes
- *   the family's fingerprint (its versions' states, runs, decisions,
- *   progress checkpoints, what the agent did last, and whether each live
- *   run's worker still answers); when it changed, every open page hears
- *   "change" and reads the task again the usual way. The nudge carries no
- *   task data. With nothing written, an open page costs no reads; a
- *   30-second check heals a missed signal (and notices a lapsed worker).
- * - Who's here. Everyone else with the task open, by name, one line per
- *   person however many pages they have. Memory only; it goes when the page
- *   closes or hides.
- *
- * Streams are refresh hints only: nothing here writes, and a page that can't
- * keep one open reads itself on its usual beat.
- */
 import { createHash } from "node:crypto";
 import { createLiveRooms } from "./live-bus.js";
 import { DEFAULT_LIVENESS_MS } from "./runner.js";
 import { BUILT_IN } from "./store.js";
-/** What changes when anything on the task page changes: one read over the family, kept short and opaque. */
 export function taskFingerprint(store, root, now, livenessMs = DEFAULT_LIVENESS_MS) {
     const row = store.handle.prepare(`WITH RECURSIVE family(ref, ext, depth) AS (
       SELECT id, external_id, 0 FROM task_ref WHERE backend = ?3 AND external_id = ?1
@@ -40,8 +19,6 @@ export function taskFingerprint(store, root, now, livenessMs = DEFAULT_LIVENESS_
     WHERE EXISTS (SELECT 1 FROM family)`).get(root, new Date(now.getTime() - livenessMs).toISOString(), BUILT_IN);
     return row === undefined ? null : createHash("sha256").update(Object.values(row).map(String).join("|")).digest("hex").slice(0, 16);
 }
-/** Rooms keyed by the task family's root. With a bus, a write reaches every open page at once; without one, only the safety net. */
 export function createTaskRooms(fingerprint, options = {}) {
-    // Everyone on the task but you, once each, by name.
     return createLiveRooms(fingerprint, (viewers, me) => [...new Set(viewers.map(one => one.name).filter(name => name !== me))].sort((a, b) => a.localeCompare(b)), options);
 }

package/dist/task-moves.js

@@ -1,34 +1,20 @@
 const ALL_BUT_CANCELLED = ["queued", "running", "done", "failed"];
 export const TASK_MOVES = {
-    /** Back to the queue from a running attempt that ended without finishing (stop, service stop, sign-in expired,
-     * vanished builder, move to a fallback agent). */
     requeue: { to: "queued", from: ["running"] },
-    /** An unfinished task that cannot go on (retries stopped, fallback agent signed out). */
     giveUp: { to: "failed", from: ["queued", "running"] },
-    /** A person's Retry. */
     retry: { to: "queued", from: ["failed", "queued", "done"] },
-    /** The tracker item was opened again. */
     reopen: { to: "queued", from: ["cancelled", "failed", "queued"] },
-    /** The fenced completion of an attempt. Wide today: a late result still writes over a closed task. */
     complete: { to: ["done", "failed"], from: "any" },
-    /** Strikes used up (build and scouting). Only an open task: one a person already closed keeps its state
-     * (docs/plans/closed-task-claims.md, decision B). */
     exhaust: { to: "failed", from: ["queued", "running"] },
-    /** The CLI `claim`: taking a task makes it running, in the grant's own transaction. `running` is listed because
-     * taking over an expired claim on a task a CLI runner left running keeps it running. */
     claim: { to: "running", from: ["queued", "running"] },
-    /** Store.setTaskState (the state verb, backend.setState, release and others). Wide by design: it is the
-     * general-purpose write; cancelled goes through applyCancellation instead. */
     set: { to: ALL_BUT_CANCELLED, from: "any" },
 };
-/** The SQL for one move: the guard is built from the table's own constants, never from caller input. */
 function moveSql(rule) {
     const base = "UPDATE task SET state = ?, updated_at = ? WHERE id = ?";
     if (rule.from === "any")
         return base;
     return `${base} AND state IN (${rule.from.map(state => `'${state}'`).join(", ")})`;
 }
-/** The state a move writes; throws on a call that does not fit the table (a programming error, not a refusal). */
 function targetOf(name, rule, to) {
     if (to === "cancelled")
         throw new Error("moveTask never writes cancelled: use applyCancellation");
@@ -43,11 +29,6 @@ function targetOf(name, rule, to) {
         throw new Error(`the ${name} move cannot write ${to}`);
     return to;
 }
-/**
- * Move one task. One statement: the from-check and the write together. True when the row changed (false when the
- * task does not exist or is not in one of the move's from-states). `to` is required for complete and set, and
- * refused for every other move.
- */
 export function moveTask(db, id, move, now, to) {
     const rule = Object.hasOwn(TASK_MOVES, move) ? TASK_MOVES[move] : undefined;
     if (rule === undefined)
@@ -55,14 +36,5 @@ export function moveTask(db, id, move, now, to) {
     const state = targetOf(move, rule, to);
     return Number(db.prepare(moveSql(rule)).run(state, now.toISOString(), id).changes) > 0;
 }
-/**
- * SQL condition, true while a runner holds a live claim on the task: the claim is not released, has not expired, and
- * is the newest generation for its task. It needs the `claim` table in scope under that name, and binds one
- * parameter: the current time as an ISO string. This is ownership, not proof that a process is alive.
- */
 export const claimedNowSql = "claim.released_at IS NULL AND claim.expires_at > ? AND claim.lease_generation = (SELECT MAX(newest.lease_generation) FROM claim AS newest WHERE newest.task_ref = claim.task_ref)";
-/**
- * SQL condition, true when the task's stored state is running (the `task` table in scope under that name). A task
- * can be marked running with no live claim (see claimedNowSql), so the two can count differently.
- */
 export const markedRunningSql = "task.state = 'running'";