toolroll 0.9.104 → 0.9.105

package/dist/agentconfig.js

@@ -1,24 +1,3 @@
-/**
- * Phase-agent resolution: which provider and model a phase runs on, layer
- * by layer, with the layers written down (Codex provider review, Q8).
- *
- *   pinned task agent  — stamped by a fire transaction; NOTHING overrides it
- *   explicit flags     — this pass's operator, per field
- *   project override   — phase_config row scoped to the canonical repo
- *   installation       — phase_config row scoped 'installation'
- *   review inheritance — when review is unset, the planner's complete pair
- *   default            — claude, harness default model
- *
- * Config rows are COMPLETE pairs (provider required, model optional), so a
- * partial override cannot marry a codex model to an inherited claude
- * provider. Flags are per-field with one stated rule: `--model` alone
- * rides whatever provider resolves; `--provider` alone runs that
- * provider's default model — a lower layer's model never crosses onto a
- * flag-chosen provider it was not written for.
- *
- * The resolved pair is validated before anything is claimed or spent, and
- * the caller snapshots it into the run row.
- */
 import { PROJECT_NETWORK_DEFAULT, repositoryEcosystems, resolveNetwork } from "./egress.js";
 import { WRITES_DEFAULT } from "./writes-mode.js";
 import { checkAccessHere } from "./check-access.js";
@@ -28,16 +7,7 @@ import { ACP_LIMITS, CLAUDE_LIMITS, CODEX_SHAPED_LIMITS, GEMINI_LIMITS } from ".
 import { ACP_AGENTS, isAcpProvider } from "./acp-agents.js";
 import { exactModelId, legOf, PHASES, recommendRoute, routeFromJson, routeProblems, sameSpec } from "./phase-routing.js";
 export const INSTALLATION_SCOPE = "installation";
-/**
- * Fail-closed (not a fallback to claude — a refusal): gemini's own
- * `.gemini/` config loads hooks and MCP servers unconditionally
- * (provider.ts's geminiArgv), a leak claude and codex both now close for
- * review with a dedicated isolation argv. Until gemini earns the same, it
- * is not eligible to run the reviewer phase at all — however it got
- * resolved: pinned, flagged, or configured.
- */
 function reviewEligible(phase, spec) {
-    // An ACP agent works with full access inside the fence: it builds and repairs, and never reviews or plans.
     if ((phase === "review" || phase === "plan") && isAcpProvider(spec.provider)) {
         return `${ACP_AGENTS[spec.provider].name} builds and repairs only — pin ${phase === "review" ? "review" : "planning"} to claude or codex`;
     }
@@ -45,11 +15,7 @@ function reviewEligible(phase, spec) {
         ? "gemini has no isolation posture for the review phase yet (its own config can load hooks and MCP servers) — pin review to claude or codex"
         : null;
 }
-export function resolvePhaseAgent(store, phase, repo, flags, 
-/** The task being dispatched, when one is — its pin is authoritative. */
-ref) {
-    // The pin: a firing resolved under approved terms must not be re-routed
-    // by anything later, flags included (Codex provider review, critical 1).
+export function resolvePhaseAgent(store, phase, repo, flags, ref) {
     if (ref !== undefined && ref.agentProvider !== null) {
         if (!isProviderId(ref.agentProvider)) {
             return { ok: false, problem: `the task is pinned to unknown provider \`${ref.agentProvider}\`` };
@@ -74,9 +40,6 @@ ref) {
     }
     const directProject = repo === null ? null : store.phaseConfig(repo, phase);
     const directInstallation = store.phaseConfig(INSTALLATION_SCOPE, phase);
-    // Planning and review benefit from the same high-judgment model, while
-    // execution can use a different provider. An explicit review row always
-    // wins; only an unset review inherits the planner's complete pair.
     const inheritedProject = phase === "review" && directProject === null && directInstallation === null && repo !== null
         ? store.phaseConfig(repo, "plan")
         : null;
@@ -87,15 +50,10 @@ ref) {
     const installation = directInstallation ?? inheritedInstallation;
     const row = project ?? installation;
     const source = project !== null ? "project" : installation !== null ? "installation" : "default";
-    // A misconfigured row REFUSES instead of silently rerouting to claude
-    // (foundations finding 3c): the operator wrote a provider; running a
-    // different one is not a fallback, it is a substitution.
     if (row !== null && !isProviderId(row.provider)) {
         return { ok: false, problem: `the ${source} configuration names unknown provider \`${row.provider}\` — fix it with \`config set\`` };
     }
     const provider = row !== null && isProviderId(row.provider) ? row.provider : "claude";
-    // --model alone rides the resolved provider; otherwise the pair comes
-    // whole from the row that named the provider.
     const model = flags.model ?? (row !== null ? row.model : null);
     const spec = { provider, model };
     const ineligible = reviewEligible(phase, spec);
@@ -145,10 +103,6 @@ export function resolveScopeProfile(store, repo, ref, flags, platform = process.
         ? {
             provider,
             model,
-            // Auto mode is designed for headless work: routine repository
-            // commands and edits proceed, while risky acts still stop at the
-            // provider's permission classifier. Full access is an explicit
-            // installation or task choice and is sealed into this profile.
             permissionArgv: permissionMode,
             maxTurns: CLAUDE_LIMITS.maxTurns,
             repairMaxTurns: CLAUDE_LIMITS.repairMaxTurns,
@@ -161,8 +115,6 @@ export function resolveScopeProfile(store, repo, ref, flags, platform = process.
             ? {
                 provider,
                 model,
-                // The cross-provider choice resolves to Gemini's own real argv:
-                // auto_edit for Auto, yolo for Full access.
                 approvalArgv: permissionMode === "bypassPermissions" ? "yolo" : "auto_edit",
                 maxTurns: "unsupported",
                 repairMaxTurns: "unsupported",
@@ -175,7 +127,6 @@ export function resolveScopeProfile(store, repo, ref, flags, platform = process.
                 ? {
                     provider,
                     model,
-                    // Full access inside the OS fence is the only posture an ACP agent has (scope.ts AcpProfile).
                     permission: "full",
                     maxTurns: "unsupported",
                     repairMaxTurns: "unsupported",
@@ -196,25 +147,15 @@ export function resolveScopeProfile(store, repo, ref, flags, platform = process.
                     repairTimeoutSeconds: CODEX_SHAPED_LIMITS.repairTimeoutSeconds,
                     repairModel,
                 };
-    // What the build may reach (egress.ts): resolved now, from the project's setting, the provider's own hosts and the
-    // registries the repository's own HEAD names, and sealed with the rest of the profile.
     const network = resolveNetwork(provider, repo === null ? PROJECT_NETWORK_DEFAULT : store.projectNetwork(repo), repo === null ? [] : repositoryEcosystems(repo));
-    // Where the build may write (writes-mode.ts): the project's setting, sealed likewise.
     const writes = repo === null ? WRITES_DEFAULT : store.projectWrites(repo);
-    // How far its checks reach (check-access.ts): the project's setting as checks can get it (sign-ins, off for now,
-    // seal as sandboxed: an approval never claims what its checks won't get), sealed only when wider than sandboxed.
     const checkAccess = repo === null ? "sandboxed" : checkAccessHere(store.projectCheckAccess(repo), platform);
-    // The fence policy (sandbox parity, docs/plans/sandbox-parity.md §1.5): every new scope is v2; and the project's
-    // sandbox settings (project-sandbox.ts), sealed when it lists any.
     const sandbox = repo === null ? PROJECT_SANDBOX_DEFAULT : store.projectSandbox(repo);
     return { ok: true, profile: { ...profile, network, writes, ...(checkAccess === "sandboxed" ? {} : { checkAccess }), fencePolicy: 2,
             ...(sandbox.readDeny.length === 0 ? {} : { readDeny: [...sandbox.readDeny] }), ...(sandbox.machLookup.length === 0 ? {} : { machLookup: [...sandbox.machLookup] }) }, provenance: { resolvedFrom: build.source, repairFrom } };
 }
 const PHASE_NOUN = { plan: "planner", build: "builder", repair: "repair", review: "reviewer" };
 export function resolveRouteCandidates(store, repo, pins = {}) {
-    // The LIGHT tier (v2): the operator's named fast builder, project over
-    // installation, never inherited and never inferred. Only the build phase
-    // has one: a small change makes no plan, and repairs resume the builder.
     const lightOf = (phase) => {
         const project = repo === null ? null : store.phaseTierConfig(repo, phase, "light");
         const row = project ?? store.phaseTierConfig(INSTALLATION_SCOPE, phase, "light");
@@ -229,7 +170,6 @@ export function resolveRouteCandidates(store, repo, pins = {}) {
             return { ok: false, problem: `the ${source} ${PHASE_NOUN[phase]}: ${valid.problem}` };
         return { ok: true, light: { provider: row.provider, model: row.model, source } };
     };
-    // Alternates (v2): one more candidate per provider on a tier, project over installation.
     const alternatesOf = (phase, tier) => {
         const project = repo === null ? [] : store.phaseTierAlternates(repo, phase, tier);
         const rows = project.length > 0 ? project : store.phaseTierAlternates(INSTALLATION_SCOPE, phase, tier);
@@ -267,10 +207,6 @@ export function resolveRouteCandidates(store, repo, pins = {}) {
         if (!routine.ok)
             return { ok: false, problem: routine.problem };
         if (routine.spec.model === null || routine.spec.model === "") {
-            // A PINNED exact pair (an approved standing order's frozen profile, a plan
-            // request's pin) is the phase's agent whatever the configuration
-            // says — it stands in as the candidate when nothing exact is
-            // configured, so a firing never depends on today's config.
             const pin = phase === "plan" ? pins.plan ?? null : phase === "build" ? pins.build ?? null : null;
             if (pin !== null)
                 return { ok: true, routine: { provider: pin.provider, model: pin.model, source: "the pinned agent" } };
@@ -285,8 +221,6 @@ export function resolveRouteCandidates(store, repo, pins = {}) {
     for (const phase of ["plan", "build", "review"]) {
         const routine = exact(phase);
         const strong = strongOf(phase);
-        // Retain the historical four-leg encoding, but retired reviewer settings
-        // cannot prevent a new task from planning or building. This leg never runs.
         if (phase === "review" && (!routine.ok || !strong.ok)) {
             out.review = out.plan;
             continue;
@@ -302,7 +236,6 @@ export function resolveRouteCandidates(store, repo, pins = {}) {
             out.review = { routine: routine.routine, strong: strong.strong };
             continue;
         }
-        // A tier's candidates on other providers (`--also`), one per provider.
         const alternates = {};
         let primary = { light: light.light, strong: strong.strong };
         for (const tier of (phase === "build" ? ["light", "routine", "strong"] : ["routine", "strong"])) {
@@ -310,7 +243,6 @@ export function resolveRouteCandidates(store, repo, pins = {}) {
             if (!read.ok)
                 return { ok: false, phase, problem: read.problem };
             const own = tier === "routine" ? routine.routine : primary[tier];
-            // With no candidate of its own, a tier's first alternate stands as it.
             const list = own === null ? read.alternates.slice(1) : read.alternates.filter(one => one.provider !== own.provider);
             if (own === null && read.alternates[0] !== undefined)
                 primary = { ...primary, [tier]: read.alternates[0] };
@@ -324,9 +256,6 @@ export function resolveRouteCandidates(store, repo, pins = {}) {
             ...(Object.keys(alternates).length === 0 ? {} : { alternates }),
         };
     }
-    // Repair: the configured row is optional (inherit is the law when none
-    // exists), but a row that EXISTS must be exact — a provider the policy
-    // can hold against the build's, and a model id.
     const repairProject = repo === null ? null : store.phaseConfig(repo, "repair");
     const repairRow = repairProject ?? store.phaseConfig(INSTALLATION_SCOPE, "repair");
     const repairSource = repairProject !== null ? "project" : "installation";
@@ -346,8 +275,6 @@ export function resolveRouteCandidates(store, repo, pins = {}) {
     out.repair = { routine: repairRoutine, strong: repairStrong.strong };
     return { ok: true, candidates: out };
 }
-/** A task's pinned pair as an EXACT spec, or the words for why it cannot
- * route: a pin with no model id binds nothing exact. */
 export function exactPinOf(provider, model, phase) {
     if (provider === null)
         return { ok: true, pin: null };
@@ -356,9 +283,6 @@ export function exactPinOf(provider, model, phase) {
     if (model === null || model === "") {
         return { ok: false, problem: phase === "plan" ? `the plan pin names ${provider} with no exact model — \`task plan <id> --provider ${provider} --model <model>\` names one` : `the task's build pin names ${provider} with no exact model — approvals bind exact routing` };
     }
-    // An exact pin is an exact ID: a stored model that is not argv-safe (a
-    // leading dash, whitespace, a control byte) files the scope unresolved
-    // in words rather than riding into a route or a spawn.
     if (!exactModelId(model)) {
         return { ok: false, problem: `the task's ${phase} pin names ${provider} with a model that is not an exact id — re-pin it with an exact model id` };
     }
@@ -422,9 +346,6 @@ export function resolveAgentAuthority(store, repo, acceptance, now) {
         return { ok: false, problem: problems.join("; ") };
     const build = legOf(route, "build");
     const repair = legOf(route, "repair");
-    // The repair model rides as a flag only when the leg says more than
-    // "the build's own model" — an inheriting repair stays the stable
-    // literal "inherit" (= the exact build model), as saveScope files it.
     const inheriting = candidates.candidates.repair.routine === null && repair.chosen === "recommended" && repair.tier === "routine" && repair.model === build.model;
     const resolved = resolveScopeProfile(store, repo, undefined, { provider: build.provider, model: build.model, ...(inheriting ? {} : { repairModel: repair.model }) });
     if (!resolved.ok)
@@ -435,25 +356,6 @@ export function resolveAgentAuthority(store, repo, acceptance, now) {
     }
     return { ok: true, route, profile: resolved.profile };
 }
-/**
- * THE ROLE'S CONFIGURED CHOICES (v48), simple and role-specific: for each
- * role, exactly the exact pairs the active configuration names FOR THAT
- * ROLE — its everyday agent and its strong agent — and nothing borrowed
- * from another role. Repair runs only the build leg's provider (repairs
- * resume the builder's session): its choices are the configured repair
- * rows on that provider plus the build role's own configured agents on
- * it, so an operator can keep repairs on the builder without naming a
- * repair row. Gemini never reviews. Nothing is typed free-hand and
- * nothing unconfigured is selectable: an approval binds an exact agent
- * the operator named once, in configuration.
- *
- * The role's CURRENT leg rides along marked `current`; when the
- * configuration no longer names it (a stale override, a routine's pin)
- * it is display-only — `selectable: false` — so a surface can say what
- * runs today without offering to re-pick it. Empty when the
- * configuration cannot make exact candidates at all; the surface then
- * says so instead of guessing.
- */
 export function agentChoicesFor(store, repo, route) {
     const empty = { plan: [], build: [], repair: [], review: [] };
     const candidates = resolveRouteCandidates(store, repo);

package/dist/agents-board.js

@@ -1,12 +1,3 @@
-/**
- * The Agents board's projection (one place to check on running agents): each
- * task's newest build attempt from the last day, in the viewer's admitted
- * projects, grouped Needs you, Working, Stuck, Done (not viewed yet), Idle.
- * A protocol repair never takes the row: while one runs, its parent's row says
- * "Fixing the handoff" and keeps the parent's transcript, changes and link.
- * Saved facts only (agent-board.ts, the run, its activity and its sealed diff
- * stats); nothing here verifies evidence or grants an action.
- */
 import { quietSince, stuckSince } from "./agent-board.js";
 import { activityLine } from "./activity-line.js";
 import { readVerifiedArtifact } from "./evidence.js";
@@ -22,7 +13,6 @@ export const AGENT_GROUPS = [
     { key: "done", label: "Done" },
     { key: "idle", label: "Idle" },
 ];
-/** Finished attempts stay on the board this long; unread Done and Needs you stay three days. */
 const RECENT_MS = 24 * 60 * 60_000;
 const KEPT_MS = 3 * RECENT_MS;
 const BOARD_LIMIT = 80;
@@ -58,23 +48,16 @@ function readFacts(row) {
         question, seen: Number(row["seen"]) === 1,
     };
 }
-/**
- * The board's candidate builds, through the partial indexes (agent_board_open, agent_board_recent): open ones and
- * those finished since $kept, one per task (its newest), never a scan of every run. A candidate a newer build of the
- * same task has replaced is dropped by an indexed probe, so the row is still the task's newest build.
- */
 export const BOARD_CANDIDATES = `WITH candidate AS (
     SELECT task_ref, id FROM run WHERE role = 'builder' AND outcome IS NULL
     UNION ALL
     SELECT task_ref, id FROM run WHERE role = 'builder' AND outcome IS NOT NULL AND finished_at >= $kept
   ), newest AS (SELECT task_ref, MAX(id) AS id FROM candidate GROUP BY task_ref)`;
-/** The board's candidate attempts: each task's newest build, open or recently finished, in the admitted projects. */
 export function agentFacts(store, now, access, account) {
     return store.handle.prepare(agentFactsSql())
         .all({ $account: account, $kept: new Date(now.getTime() - KEPT_MS).toISOString(), $all: access.repos === null ? 1 : 0, $repos: JSON.stringify(access.repos ?? []) })
         .map(readFacts);
 }
-/** The board's query, exported for its query-plan test. */
 export function agentFactsSql() {
     return `${BOARD_CANDIDATES}
     ${FACTS.replace("FROM run r", "FROM newest c JOIN run r ON r.id = c.id")}
@@ -83,9 +66,6 @@ export function agentFactsSql() {
       AND ($all = 1 OR tr.repo IN (SELECT value FROM json_each($repos)))
     ORDER BY r.id DESC LIMIT ${BOARD_LIMIT}`;
 }
-/** One exact build attempt, whatever its age (the opened row), in the admitted projects: a repair opens as its parent. */
-/** One attempt opened by its run: a build (a protocol repair opens as its build), or a planner, scout or reviewer —
- * the board lists builds, but any running agent can be opened to see it and what it takes (cockpit §4). */
 const OPENED_FACTS = FACTS.replace("WHERE r.role = 'builder'", "WHERE r.role IN ('builder', 'planner', 'scout', 'reviewer')");
 export function agentFactsFor(store, run, access, account) {
     const row = store.handle.prepare(`${OPENED_FACTS} AND r.id = (SELECT CASE WHEN role = 'repair' AND parent_run IS NOT NULL THEN parent_run ELSE id END FROM run WHERE id = $run) AND ($all = 1 OR tr.repo IN (SELECT value FROM json_each($repos)))`)
@@ -94,8 +74,6 @@ export function agentFactsFor(store, run, access, account) {
 }
 const FINISHED_WELL = new Set(["built", "no-change"]);
 const SETTLED_TASK = new Set(["done", "cancelled"]);
-/** Where an attempt sits on the board, and its one state word. Stuck is worked out from the facts now, so fresh
- * transcript or activity clears it at once (the pulse's saved mark only tells open boards it crossed). */
 export function agentGroupOf(facts, activityAt, now) {
     if (facts.outcome === null) {
         if (facts.question !== null)
@@ -109,12 +87,10 @@ export function agentGroupOf(facts, activityAt, now) {
         if (facts.turn === "busy" && stuckSince({ state: "busy", stateAt: facts.stateAt ?? facts.startedAt, transcriptAt: facts.transcriptAt ?? facts.startedAt, toolAt: facts.toolAt }, activityAt, now) !== null) {
             return { group: "stuck", label: "Stuck" };
         }
-        // Its turn has its result, but the build is still capturing and checking it: still at work, not idle.
         return { group: "working", label: "Working" };
     }
     if (FINISHED_WELL.has(facts.outcome)) {
         const label = facts.outcome === "built" ? "Done" : "No changes";
-        // Unread only for attempts the board saw start: a run from before it never counts as news.
         return { group: facts.seen || facts.legacy ? "idle" : "done", label };
     }
     if (SETTLED_TASK.has(facts.taskState))
@@ -122,7 +98,6 @@ export function agentGroupOf(facts, activityAt, now) {
     return { group: "needs-you", label: facts.outcome === "parked" ? "Needs a decision" : wasInterrupted(facts) ? "Stopped" : facts.outcome === "refused" ? "Not started" : "Failed" };
 }
 const sealed = new Map();
-/** A finished attempt's sealed diff stats (cached by artifact: sealed bytes never change). */
 export function sealedDiffOf(store, root, run) {
     if (root === undefined)
         return null;
@@ -151,7 +126,6 @@ export function sealedDiffOf(store, root, run) {
     return summary;
 }
 const files = (count) => `${count} ${count === 1 ? "file" : "files"}`;
-/** A row's diff size: the sealed stats once finished, the pulse's count while it runs. */
 export function diffWords(facts, diff) {
     if (facts.outcome !== null) {
         if (diff === null)
@@ -165,10 +139,8 @@ export function diffWords(facts, diff) {
     return facts.diffFiles === 0 ? "No changes yet" : `${files(facts.diffFiles)} changed`;
 }
 const SETTLING_PHASES = new Set(["validating-handoff", "capturing-evidence", "committing", "verifying-proof", "correcting-proof"]);
-/** Reasons whose words only restate the Failed chip: the row shows the agent's own last word instead, or nothing. */
 const RESTATES_FAILED = new Set(["agent"]);
 const minutes = (ms) => Math.max(1, Math.floor(ms / 60_000));
-/** A finished attempt's one line: never the state again (the chip says it), only why. */
 function endedLine(facts) {
     const own = facts.said === "blocked" || facts.said === "done" ? facts.saidNote : null;
     if (FINISHED_WELL.has(facts.outcome ?? ""))
@@ -179,7 +151,6 @@ function endedLine(facts) {
         return own;
     return failedAttemptSentence(facts.reason);
 }
-/** One board row. */
 export function agentRowOf(store, facts, now, root) {
     const activity = facts.outcome === null ? runActivityOf(store, { id: facts.runId, runner: facts.runner, startedAt: facts.startedAt }, now) : null;
     const { group, label } = agentGroupOf(facts, activity?.at ?? null, now);
@@ -209,7 +180,6 @@ export function agentRowOf(store, facts, now, root) {
         diff: diffWords(facts, facts.outcome === null ? null : sealedDiffOf(store, root, facts.runId)), agent: providerName(facts.provider),
     };
 }
-/** The whole board: groups in order, rows newest first within each; empty groups dropped. */
 export function agentsBoardOf(store, now, access, account, root) {
     const recent = new Date(now.getTime() - RECENT_MS).toISOString();
     const rows = agentFacts(store, now, access, account).map(facts => ({ facts, row: agentRowOf(store, facts, now, root) }))
@@ -217,7 +187,6 @@ export function agentsBoardOf(store, now, access, account, root) {
         .map(({ row }) => row);
     return AGENT_GROUPS.map(group => ({ ...group, rows: rows.filter(row => row.group === group.key) })).filter(group => group.rows.length > 0);
 }
-/** A board fingerprint for one exact build: what its open view shows moved, its repairs included. */
 export function agentRunFingerprint(store, run) {
     const row = store.handle.prepare(`SELECT r.outcome, r.finished_at, r.phase, n.state, n.state_at, n.transcript_bytes, n.stuck_at, n.said_at, n.diff_files, n.tool_at, n.question_note,
       (SELECT count(*) || ':' || coalesce(max(id), 0) || ':' || coalesce(sum(closed_at IS NULL), 0) FROM agent_question WHERE run = r.id) AS asks,
@@ -227,13 +196,8 @@ export function agentRunFingerprint(store, run) {
     FROM run r LEFT JOIN agent_now n ON n.run = r.id AND n.attempt_key = r.attempt_key WHERE r.id = ?`).get(run);
     return row === undefined ? null : Object.values(row).map(value => String(value)).join("|");
 }
-/** The timeline's windows, all rolling (so no server time zone decides what "today" means); two hours by default. */
 export const LANE_WINDOWS = [{ key: "30m", label: "30m" }, { key: "2h", label: "2h" }, { key: "24h", label: "24h" }];
-/** Rows the timeline shows: twenty running tasks read as twelve rows and a count, not a wall. */
 export const LANE_ROWS = 12;
-/** Runs are found by their start back this far; a builder that finished in the window is also found by its finish
- * (agent_board_recent), however long it ran. A planner, review, scout or repair run that lasted over a day and ended
- * in the window is the one case left out: finding it would need a finish-time index over every role. */
 const LANE_LOOKBACK_MS = 24 * 60 * 60_000;
 const WINDOW_MS = { "30m": 30 * 60_000, "2h": 2 * 60 * 60_000, "24h": 24 * 60 * 60_000 };
 const LANE_ROLES = "('planner', 'builder', 'repair', 'reviewer', 'scout')";
@@ -243,10 +207,6 @@ export function laneWindowOf(value) {
 export function laneSinceOf(window, now) {
     return new Date(now.getTime() - WINDOW_MS[window]);
 }
-/** The window's tasks, one row each with whether a run is live and when it was last active, newest activity first,
- * and the total and running counts over all of them. The candidates come from bounded index ranges (run_started;
- * work_unfinished and agent_board_recent, named so SQLite never walks every run) and drive the join (CROSS JOIN), so no
- * task's history is walked; the admitted projects only. */
 export function agentLanesSql() {
     return `WITH candidate AS (
       SELECT DISTINCT id FROM (
@@ -267,32 +227,21 @@ export function agentLanesSql() {
     SELECT a.*, (SELECT count(*) FROM active) AS total, (SELECT coalesce(sum(live), 0) FROM active) AS running
     FROM active a ORDER BY a.live DESC, a.last_at DESC, a.last_run DESC LIMIT $rows`;
 }
-/** Segments one row keeps: its newest runs, so a task retried all day stays one readable row. */
 export const LANE_SEGMENTS = 40;
-/** One chosen task's live runs: all of them, through work_unfinished, so no cap can hide one. */
 export function laneLiveRunsSql() {
     return `SELECT id, role, provider, outcome, started_at, finished_at FROM run INDEXED BY work_unfinished
     WHERE task_ref = $ref AND outcome IS NULL AND role IN ${LANE_ROLES}`;
 }
-/** Rows one task's lookups read at most, newest first: a task with thousands of runs costs the same as one with a few. */
 export const LANE_TASK_READ = 2000;
-/** One chosen task's runs that finished in the window: a seek on its own runs from its first finished run in the
- * window (lead_status_task_run), reading at most LANE_TASK_READ of its newest runs; the newest LANE_SEGMENTS. */
 export function laneRunsSql() {
     return `SELECT id, role, provider, outcome, started_at, finished_at FROM (
       SELECT id, role, provider, outcome, started_at, finished_at FROM run WHERE task_ref = $ref AND id >= $from ORDER BY id DESC LIMIT ${LANE_TASK_READ}
     ) WHERE outcome IS NOT NULL AND finished_at >= $since AND role IN ${LANE_ROLES}
     ORDER BY id DESC LIMIT ${LANE_SEGMENTS}`;
 }
-/** A task's newest build, whenever it ran, among its newest 500 runs: the row's state comes from it even when it
- * finished before the window. A task with more runs than that since its last build reads as planning or idle. */
 export function laneNewestBuildSql() {
     return `SELECT id FROM (SELECT id, role FROM run WHERE task_ref = $ref ORDER BY id DESC LIMIT 500) WHERE role = 'builder' LIMIT 1`;
 }
-/** The timeline: one row per task that ran in the window, running ones first, then the most recently active, the
- * first LANE_ROWS of them; the counts cover every task in the window. A row's state is worked out from its own
- * newest build as the board would (planning while only a planner runs, otherwise idle). With nothing in the window but something in the last day,
- * the timeline stays (empty) so its window choice does too; with nothing in a day it is null. */
 export function agentLanesOf(store, now, access, account, window, path = "/agents") {
     const read = (since, rows) => store.handle.prepare(agentLanesSql()).all({
         $lookback: new Date(since.getTime() - LANE_LOOKBACK_MS).toISOString(), $since: since.toISOString(), $now: now.toISOString(),
@@ -313,12 +262,9 @@ export function agentLanesOf(store, now, access, account, window, path = "/agent
             return {
                 runId: Number(run["id"]), role: role === "repair" ? "builder" : role, agent: providerName(String(run["provider"] ?? "claude")),
                 startedAt: String(run["started_at"]), endedAt: str(run, "finished_at"), outcome: str(run, "outcome"),
-                // Every role opens in the agent view (planners, scouts and reviewers too): what it is doing and what it takes.
                 href: `/agents?run=${Number(run["id"])}`,
             };
         });
-        // The row's state from the task's own newest build, as the board would place it (never the board's capped list),
-        // even when that build finished before the window.
         const build = newestBuildOf.get({ $ref: ref });
         const facts = build === undefined ? null : agentFactsFor(store, Number(build["id"]), access, account);
         const group = facts !== null ? agentGroupOf(facts, facts.outcome === null ? runActivityOf(store, { id: facts.runId, runner: facts.runner, startedAt: facts.startedAt }, now).at : null, now).group
@@ -333,13 +279,7 @@ export function agentLanesOf(store, now, access, account, window, path = "/agent
         running: tasks.length === 0 ? 0 : Number(tasks[0]["running"]),
     };
 }
-/** The word a running planner, scout or reviewer wears on the Agents list (a build keeps its own state word). */
 const ROLE_WORDS = { planner: "Planning", scout: "Investigating", reviewer: "Reviewing" };
-/**
- * The Agents list's every live agent, not only builds (UI revamp wave B): the build board's groups, with each running
- * planner, scout and reviewer in the admitted projects added under Working (or Needs you when it asks). Reads the
- * open leases only (store.liveRuns), then each run through the same admitted read the opened view uses.
- */
 export function agentsListOf(store, now, access, account, root) {
     const groups = agentsBoardOf(store, now, access, account, root);
     const shown = new Set(groups.flatMap(group => group.rows.map(row => row.runId)));

package/dist/agents-live.js

@@ -1,15 +1,8 @@
-/**
- * The Agents view's Live grid (docs/plans/agents-view.md §1, §2.5): which agents are running now (every role) and
- * which ended in the last ten minutes, with the facts a tile shows. Store facts only — it verifies nothing, grants
- * nothing, and reads no live file; visibility is proved by the caller's `canSee` for each run.
- */
 import { attemptKeyOf, agentNowForRun, openAgentQuestions } from "./agent-board.js";
 import { agentsLiveRuns } from "./store.js";
 import { wasInterrupted } from "./run-ending.js";
-/** An ended agent stays on the grid this long, then leaves (it remains on the List). */
 export const LIVE_ENDED_KEEP_MS = 10 * 60_000;
 const stateOf = (run) => run.outcome === null ? "working" : run.outcome === "built" || run.outcome === "no-change" ? "done" : run.outcome === "parked" ? "parked" : wasInterrupted(run) ? "stopped" : "failed";
-/** The grid's tiles for one viewer: `canSee` is the caller's proof (ceiling and account access) for each run. */
 export function agentsLiveOf(store, now, viewer) {
     const tiles = [];
     for (const run of agentsLiveRuns(store, new Date(now.getTime() - LIVE_ENDED_KEEP_MS))) {
@@ -28,7 +21,7 @@ export function agentsLiveOf(store, now, viewer) {
                     quietSince = facts.stuckAt;
                 }
             }
-            catch { /* display state: no word yet */ }
+            catch { }
             if (why !== null)
                 state = "needs-you";
         }

package/dist/api-tokens.js

@@ -1,24 +1,11 @@
-/**
- * Machine credentials (D7, v118): one codec and one table (`credential`) for every kind. A person's API token is
- * what scripts and CI use instead of a password on each request: it belongs to one person, reads or acts (never
- * more than the person may), always expires (a year at most), is shown once, and only its hash is kept.
- * `Authorization: Bearer so_<id>_<secret>`. A lead token (`lt_<id>_<secret>`) is an agent acting for its owner; a
- * coordinator's secret (no prefix, hashed whole) files proposals over MCP. Each kind keeps its own policy.
- *
- * A token never passes a step-up: approvals and other password ceremonies
- * stay a person's act in the console.
- */
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 export const MCP_ROTATION_REFUSAL = "Reconnect the MCP client to renew this token. You can still revoke it here.";
-/** Missing purpose is an old ordinary token; an unrecognised stored purpose is never treated as ordinary. */
 export const tokenPurpose = (value) => value === undefined || value === "api" ? "api" : "mcp";
 export const tokenRotationProblem = (token) => token.purpose === "api" ? null : MCP_ROTATION_REFUSAL;
 export const TOKEN_DAYS = [30, 90, 365];
-/** The prefixed shapes: so_ (a person's API token) and lt_ (a lead token), each `<prefix>_<12 hex>_<43 base64url>`. */
 const PRESENTED = /^(so|lt)_([a-f0-9]{12})_([A-Za-z0-9_-]{43})$/;
 const PREFIX = { person: "so", lead: "lt" };
 const CID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
-/** A new credential of `kind`: its id, the secret shown once, and the only thing kept, its hash. */
 export function mintCredential(kind) {
     const secret = randomBytes(32).toString("base64url");
     if (kind === "coordinator") {
@@ -31,7 +18,6 @@ export function mintCredential(kind) {
     return { id, secret, token: `${PREFIX[kind]}_${id}_${secret}`, hash: hashSecret(secret) };
 }
 export const hashSecret = (secret) => createHash("sha256").update(secret, "utf8").digest("hex");
-/** Read a presented credential's kind and parts; null for nothing at all. A lead token may carry surrounding space. */
 export function parseCredential(presented) {
     if (presented === "")
         return null;
@@ -42,50 +28,37 @@ export function parseCredential(presented) {
 }
 export const mintApiToken = () => mintCredential("person");
 export const mintLeadToken = () => mintCredential("lead");
-/** The id and secret of something shaped like an API token, or null. */
 export function parseApiToken(presented) {
     const parsed = parseCredential(presented);
     return parsed?.kind === "person" && PRESENTED.test(presented) ? { id: parsed.id, secret: parsed.secret } : null;
 }
-/** The id and secret of something shaped like a lead token, or null. */
 export function parseLeadToken(presented) {
     const parsed = parseCredential(presented);
     return parsed?.kind === "lead" ? { id: parsed.id, secret: parsed.secret } : null;
 }
-/** Whether the secret is the one whose hash was kept, in constant time. */
 export function secretMatches(secret, keptHash) {
     const a = Buffer.from(hashSecret(secret), "hex"), b = Buffer.from(keptHash, "hex");
     return a.length === b.length && timingSafeEqual(a, b);
 }
-/** v111: how long a rotated token keeps working beside its replacement, by default and at most. */
 export const ROTATION_OVERLAP_MINUTES = 10;
 export const ROTATION_OVERLAP_MAX_MINUTES = 60;
-/** v111: the person is told this many days before a token expires, once each. */
 export const EXPIRY_NOTICE_DAYS = [7, 1];
-/** Whether a token signs anyone in at `now`: unrevoked, unexpired, and (once replaced) inside its overlap. */
 export function tokenLive(token, now) {
     if (token.revokedAt !== null || !(Date.parse(token.expiresAt) > now))
         return false;
     return token.overlapUntil === null || Date.parse(token.overlapUntil) > now;
 }
-/**
- * The projects a token's person may use through it now: the person's current access, narrowed by the token's limit.
- * Null is every project. A limit never widens access, and a project the person has lost stays lost.
- */
 export function tokenProjects(account, token) {
     if (token === null)
         return account === null ? null : [...account];
     return token.filter(repo => account === null || account.includes(repo));
 }
-/** Whether `projects` (a principal's) stays inside the token's limit. A limited token never stands for every project. */
 export function withinTokenLimit(projects, limit) {
     if (limit === null)
         return true;
     return projects !== null && projects.every(repo => limit.includes(repo));
 }
-/** Whole days until a token expires, rounded up (0 once it has). */
 export const daysLeft = (expiresAt, now) => Math.max(0, Math.ceil((Date.parse(expiresAt) - now) / 86_400_000));
-/** The expiry notice a token is due at `now` (7 or 1 days), or null. Replaced and revoked tokens get none. */
 export function expiryNoticeDue(token, now) {
     if (token.replacedBy !== null || !tokenLive(token, now))
         return null;