toolroll 0.9.104 → 0.9.105

package/dist/agent-onboard.js

@@ -1,21 +1,3 @@
-/**
- * `toolroll onboard`: the agent that installed Toolroll becomes its lead.
- *
- * Run inside a repository, it adds that repository as a project (the same
- * registry and project row Projects → add writes), reports which agent
- * CLIs are signed in (the checks Settings → AI providers makes), installs
- * a thin operator skill for the person's own agent, prints the MCP line
- * without running it, and ends with a handoff the agent can relay.
- *
- * Adding the project and writing the skill both need --yes or one yes
- * typed at a terminal. Then it offers the starter flows (flow-starters.ts),
- * each switched on by its own yes at a terminal or by --starter; --yes alone
- * never switches one on. The project is the main checkout (never a linked
- * worktree, the home folder, or one of Toolroll's own worktrees). The skill
- * is replaced by the next onboard and deleted by `onboard --remove` only
- * while it is exactly a version Toolroll wrote; a file of the same name
- * that is not ours, or ours with the person's edits, is never touched.
- */
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, resolve, sep } from "node:path";
@@ -24,8 +6,6 @@ import { connectionWords } from "./control-ui.js";
 import { envelopeJson } from "./envelope.js";
 export const ONBOARD_AGENTS = ["claude", "codex"];
 export const AGENT_NAMES = { claude: "Claude Code", codex: "Codex" };
-/** Each agent's user-level home: where its skills folder lives. A relative CODEX_HOME is under the home folder, never
- * wherever onboard happens to run. */
 export function agentHome(agent, home, env) {
     if (agent === "codex") {
         const codexHome = env["CODEX_HOME"];
@@ -38,16 +18,13 @@ export function agentHome(agent, home, env) {
 export function operatorSkillPath(agent, home, env) {
     return join(agentHome(agent, home, env), "skills", "toolroll", "SKILL.md");
 }
-/** The agents this person uses: those whose home folder exists, else Claude Code. */
 export function detectAgents(home, env) {
     const found = ONBOARD_AGENTS.filter(agent => existsSync(agentHome(agent, home, env)));
     return found.length > 0 ? found : ["claude"];
 }
-/** The line that adds Toolroll as tools, for every project. Printed, never run. */
 export function mcpLine(agent) {
     return agent === "claude" ? "claude mcp add --scope user toolroll -- toolroll mcp" : `${agent} mcp add toolroll -- toolroll mcp`;
 }
-/** The thin skill: when to reach for Toolroll, and where the real guides are. */
 export function operatorSkillContent(version) {
     return `---
 name: toolroll
@@ -76,21 +53,15 @@ Approving work and answering decisions belong to the person. Never read out or r
 }
 const escapedMark = OPERATOR_SKILL_MARK.replace(/[.*+?^$()|[\]\\{}]/g, "\\$&");
 const WRITTEN_BY = new RegExp(`^(${escapedMark} · written by toolroll )(\\S+?)(\\. \`toolroll onboard)`, "m");
-/** A skill's fingerprint with the version it names set aside: every release writes the same words. */
 export function skillFingerprint(content) {
     return createHash("sha256").update(content.replace(WRITTEN_BY, "$1*$3")).digest("hex");
 }
-/** Every SKILL.md a release has generated at this path (skillFingerprint): the operator skill, and `skills install
- * --claude-code`'s. Kept, never replaced, when the words change: a skill an earlier release wrote is still ours. A
- * test fails until this build's own fingerprints are listed. */
 export const RELEASED_SKILLS = [
-    "6ff9b4458f332636b6c5968c416bee4770564ef0190d62ec8640e84051fb7f60", // skills install --claude-code
-    "3fb6741eec6d394a0a41604cae321da05d85c74f440424b740151c131f125742", // the operator skill
-    "448fc51dc200b4d46c53bf191fd7ecee7c4f7487413bf4dbfb1f984a3b401993", // skills install --claude-code, with the release guide
+    "6ff9b4458f332636b6c5968c416bee4770564ef0190d62ec8640e84051fb7f60",
+    "3fb6741eec6d394a0a41604cae321da05d85c74f440424b740151c131f125742",
+    "448fc51dc200b4d46c53bf191fd7ecee7c4f7487413bf4dbfb1f984a3b401993",
 ];
 const KNOWN_SKILLS = new Set([...RELEASED_SKILLS, ...[operatorSkillContent("0.0.0"), claudeCodeSkillContent()].map(skillFingerprint)]);
-/** SHA-256 of every guide copy (console.md, operating.md, runner.md, release.md) an earlier `skills install --claude-code` wrote
- * beside SKILL.md, and of this build's. Only an exact one of these is removed: an edited copy is the person's. */
 const RELEASED_GUIDES = [
     "a5aa20f93d803fd49bbac2908e46353a4f90c95c2bb57993ee724770c28adb0b", "65fc1774c4d6dd99e71a7cfb245a61148ac74889765477ddd5066703cd28f55c", "01604f373b92de737ae7f75804c7f7f09dd690ed96a3e676be75f71358819f23",
     "1e1ee5c46c84b65c931e86c005802478415ec026b6240367e7f12a8d66d608eb", "e5270e70eb09f202980a236a0ae36ac2e1c3df91840c24d40a6a8bd4c0d47fe8", "969dd5e97b63f27dc559889a551f4392bcf289f2b47ce802338868f06e05f1c9",
@@ -100,7 +71,6 @@ const RELEASED_GUIDES = [
 ];
 const guideHash = (content) => createHash("sha256").update(content).digest("hex");
 const KNOWN_GUIDES = new Set([...RELEASED_GUIDES, ...CLAUDE_CODE_GUIDES.map(name => guideHash(claudeCodeGuideContent(name)))]);
-/** ours: exactly a version Toolroll wrote. edited: ours, with the person's changes. foreign: not ours at all. */
 function skillOwnership(path) {
     const entry = lstatSync(path);
     if (entry.isSymbolicLink() || !entry.isFile() || entry.size > 2_000_000)
@@ -111,7 +81,6 @@ function skillOwnership(path) {
         return "foreign";
     return KNOWN_SKILLS.has(skillFingerprint(content)) ? "ours" : "edited";
 }
-/** Guide copies an older `skills install --claude-code` left beside SKILL.md, exactly as it wrote them. */
 function oldGuideCopies(folder) {
     return CLAUDE_CODE_GUIDES.map(name => join(folder, `${name}.md`)).filter(path => {
         try {
@@ -123,7 +92,6 @@ function oldGuideCopies(folder) {
         }
     });
 }
-/** What install (or --remove) would do, without writing anything. */
 export function planOperatorSkill(agents, options) {
     return agents.map(agent => {
         const path = operatorSkillPath(agent, options.home, options.env);
@@ -154,7 +122,6 @@ export function planOperatorSkill(agents, options) {
 function lstatExists(path) {
     return lstatSync(path, { throwIfNoEntry: false }) !== undefined;
 }
-/** Carry out a plan. Steps that are not ours, current, or absent change nothing. */
 export function applyOperatorSkill(steps, version) {
     const wrote = [];
     const removed = [];
@@ -192,21 +159,22 @@ export function buildHandoff(input) {
         next: NEXT_THINGS,
     };
 }
-export function handoffLines(handoff) {
-    const login = handoff.login === null
-        ? "no account yet; `toolroll up` creates one"
-        : handoff.login.file === null
-            ? `${handoff.login.account ?? "your account"} — sign in with your password`
-            : `${handoff.login.account ?? "the account"} — the password is in ${handoff.login.file}`;
+export function handoffLines(handoff, how = {}) {
+    const login = how.local === true
+        ? "none on this computer: run `toolroll` at its terminal, and it opens signed in"
+        : handoff.login === null
+            ? "no account yet; `toolroll up` creates one"
+            : handoff.login.file === null
+                ? `${handoff.login.account ?? "your account"} — sign in with your password`
+                : `${handoff.login.account ?? "the account"} — the password is in ${handoff.login.file}`;
     return [
         "Toolroll is ready.",
         `  console   ${handoff.console}`,
         `  login     ${login}`,
-        `  phone     ${handoff.phone}`,
+        ...how.local === true ? [] : [`  phone     ${handoff.phone}`],
         `  say next  ${handoff.next.map(one => `"${one}"`).join(" · ")}`,
     ];
 }
-/** The account name from a saved login file, never its password. */
 export function loginAccount(file) {
     try {
         const raw = readFileSync(file, "utf8").trim();
@@ -220,7 +188,6 @@ export function loginAccount(file) {
 export function agentReport(agent, connection) {
     return { agent, name: AGENT_NAMES[agent], state: connection.state, words: connectionWords(connection), ...(connection.plan === undefined ? {} : { plan: connection.plan }) };
 }
-/** Offer each starter flow: switch on the ones --starter names, or ask one yes each at a terminal. */
 async function offerStarters(io, repo) {
     if (io.starters === undefined)
         return [];
@@ -271,7 +238,6 @@ const real = (path) => {
     }
 };
 const within = (path, folder) => path === folder || path.startsWith(folder.endsWith(sep) ? folder : `${folder}${sep}`);
-/** Why a found repository cannot be the project, or null when it can. */
 export function projectRefusal(found, where) {
     const worktrees = real(where.worktrees);
     if ([where.cwd, found.top, found.main].some(path => within(real(path), worktrees))) {
@@ -283,7 +249,6 @@ export function projectRefusal(found, where) {
     }
     return null;
 }
-/** Returns the exit code: 0 done, 2 usage, 3 a refusal to answer. */
 export async function runOnboard(io) {
     const command = "onboard";
     const refuse = (reason, message, code, extra = {}) => {
@@ -301,12 +266,10 @@ export async function runOnboard(io) {
     else {
         agents = detectAgents(io.home, io.env);
     }
-    // The skill: validate every file first.
     const steps = planOperatorSkill(agents, { home: io.home, env: io.env, version: io.version, remove: io.remove });
     const changes = steps.filter(step => step.action === "create" || step.action === "replace" || step.action === "remove");
     const foreign = steps.filter(step => step.action === "not-ours" || step.action === "edited");
     const skillChanges = foreign.length === 0 && changes.length > 0;
-    // The project: the main checkout of the repository onboard runs in, never --remove's business.
     let project = { state: "none" };
     if (!io.remove) {
         const found = await io.findRepo(io.cwd);
@@ -319,7 +282,6 @@ export async function runOnboard(io) {
         }
     }
     const projectChange = project.state === "needs-yes";
-    // Then ask once for everything that writes, then write.
     let consent = false;
     if (skillChanges || projectChange) {
         const parts = [

package/dist/agent-pulse.js

@@ -1,30 +1,11 @@
-/**
- * The Agents board on the build's existing minute pulse (agent-board.ts):
- * the agent's status file, the live transcript's size, the changed-file
- * count and the four-minute Stuck mark. No model and no tokens: files the
- * plane already owns, read with the same discipline as every protocol file.
- *
- * The status file is the agent's: one JSON object per line, appended.
- *   {"status":"working","note":"…"}
- *   {"status":"needs-decision","key":"short-key","question":"…"}
- *   {"status":"blocked","note":"…"}
- *   {"status":"done","note":"…"}
- * It is read forward from a saved offset, only through complete lines, never
- * past its caps, opened O_NOFOLLOW as a regular file; a line that is not one
- * of these shapes is skipped, and every word goes through the live view's
- * sanitizer (a credential-shaped line is replaced whole).
- */
 import { closeSync, constants, fstatSync, openSync, readSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { ingestStatus, markStuck, noteDiff, noteTranscript, NOTE_MAX, pageQuestions, QUESTION_KEY, QUESTION_MAX, QUESTIONS_OPEN_MAX, QUESTIONS_PER_ATTEMPT } from "./agent-board.js";
 import { readVerifiedArtifact } from "./evidence.js";
 import { legacyLiveLogPath, liveLogPath, sanitizeTranscriptLine } from "./live.js";
 import { observeWorktree, parseBaseTreeSnapshot, PEEK_LIMITS } from "./peek.js";
-/** The whole file may grow this far; past it, nothing more is read. */
 export const STATUS_FILE_CAP = 256 * 1024;
-/** At most this much is read per beat. */
 const STATUS_WINDOW = 64 * 1024;
-/** A line longer than this is skipped, never cut. */
 const STATUS_LINE_CAP = 4 * 1024;
 const clean = (value, cap) => {
     if (typeof value !== "string")
@@ -34,7 +15,6 @@ const clean = (value, cap) => {
         return null;
     return one.length > cap ? `${one.slice(0, cap - 1).trimEnd()}…` : one;
 };
-/** One status line, strictly: a known status and its fields, or null. */
 export function parseStatusLine(line) {
     if (line.trim() === "" || Buffer.byteLength(line, "utf8") > STATUS_LINE_CAP)
         return null;
@@ -58,7 +38,6 @@ export function parseStatusLine(line) {
         return { status, note: clean(record["note"], NOTE_MAX) };
     return null;
 }
-/** The complete lines after `from`, and where the next read starts. */
 export function readStatusFile(path, from) {
     if (!Number.isSafeInteger(from) || from < 0)
         return { ok: false, reason: "unreadable" };
@@ -92,7 +71,6 @@ export function readStatusFile(path, from) {
         const chunk = buffer.subarray(0, got);
         const lastLf = chunk.lastIndexOf(0x0a);
         if (lastLf === -1) {
-            // One line longer than the whole window is never going to parse: step past it.
             return { ok: true, read: { lines: [], nextOffset: got >= STATUS_WINDOW ? from + got : from } };
         }
         const lines = chunk.subarray(0, lastLf).toString("utf8").split("\n").map(parseStatusLine).filter((one) => one !== null);
@@ -105,7 +83,6 @@ export function readStatusFile(path, from) {
         closeSync(fd);
     }
 }
-/** Create the attempt's empty status file (created here, never adopted); null when it cannot be. */
 export function openStatusFile(worktree, name) {
     const path = join(worktree, name);
     try {
@@ -122,9 +99,8 @@ export function removeStatusFile(path) {
     try {
         unlinkSync(path);
     }
-    catch { /* already gone */ }
+    catch { }
 }
-/** The brief's few lines: where to write, what each status means, and how a reply arrives. */
 export function statusBrief(name, steerFolder) {
     return [
         "",
@@ -143,7 +119,6 @@ export function statusBrief(name, steerFolder) {
         "",
     ].join("\n");
 }
-/** The run's verified base snapshot, as the live peek reads it; null when it was not captured cleanly. */
 export function baseEntriesOf(store, root, run) {
     const artifact = store.artifactsFor(run).find(one => one.kind === "base-tree");
     if (artifact === undefined || artifact.captureStatus !== "ok" || artifact.truncated)
@@ -154,21 +129,14 @@ export function baseEntriesOf(store, root, run) {
     const snapshot = parseBaseTreeSnapshot(read.content.toString("utf8"));
     return snapshot === null || snapshot.run !== run ? null : snapshot.entries;
 }
-/** What a look at the checkout found: changed, deleted and new files together; null when it could not look. */
 export async function changedFileCount(worktree, base) {
     const seen = await observeWorktree(worktree, base, { ...PEEK_LIMITS, deadlineMs: 1_500 });
     if (!seen.ok)
         return null;
     return seen.rows.filter(one => one.kind === "changed" || one.kind === "deleted").length + seen.newPaths.length;
 }
-/**
- * One beat for the board. Each part is its own fail-soft step: a status file
- * that cannot be read, or a checkout that cannot be looked at, costs only
- * its own line on the board, never the build.
- */
 export function pulseAgentBoard(store, state, now) {
     try {
-        // The records file every run writes now, else a legacy text file.
         let bytes;
         try {
             bytes = statSync(liveLogPath(state.root, state.run)).size;
@@ -178,7 +146,7 @@ export function pulseAgentBoard(store, state, now) {
         }
         noteTranscript(store, state.run, state.attemptKey, bytes, now);
     }
-    catch { /* no live log: the activity row still counts */ }
+    catch { }
     if (state.status !== null) {
         try {
             const from = store.handle.prepare("SELECT status_offset FROM agent_now WHERE run = ? AND attempt_key = ?").get(state.run, state.attemptKey);
@@ -188,17 +156,16 @@ export function pulseAgentBoard(store, state, now) {
                     ingestStatus(store, state.run, state.attemptKey, read.read, now);
             }
         }
-        catch { /* the next beat reads from the same offset */ }
-        // Questions asked inside the page window go out once it ends, with or without a new line.
+        catch { }
         try {
             pageQuestions(store, state.run, state.attemptKey, now);
         }
-        catch { /* the next beat */ }
+        catch { }
     }
     try {
         markStuck(store, state.run, state.attemptKey, now);
     }
-    catch { /* the next beat */ }
+    catch { }
     if (state.looking)
         return;
     if (state.base === undefined) {

package/dist/agent-state-words.js

@@ -1,20 +1,12 @@
-/**
- * The agent states' words, tones and counts (docs/plans/agents-cockpit.md §1), with nothing the browser can't load:
- * agent-state.ts derives the states; the console's pages and the sidebar say them with these.
- */
-/** The display states, strongest first: a roll-up takes the first one any member has. */
 export const DISPLAY_STATES = ["needs-you", "failed", "stuck", "paused", "working", "waiting", "done", "idle"];
 export const STATE_WORDS = {
     "needs-you": "Needs you", failed: "Failed", stuck: "Stuck", paused: "Paused", working: "Working", waiting: "Waiting", done: "Done", idle: "Idle",
 };
-/** For someone who may not act on it: the obligation is still there, and still counts. */
 export const NEEDS_SOMEONE = "Needs someone";
-/** Each state's tone, for the console's one palette (attention, problem, live, ready, done, muted). */
 export const STATE_TONE = {
     "needs-you": "attention", failed: "problem", stuck: "problem", paused: "muted", working: "live", waiting: "muted", done: "ready", idle: "muted",
 };
 export const NO_COUNTS = Object.freeze({ "needs-you": 0, failed: 0, stuck: 0, paused: 0, working: 0, waiting: 0, done: 0, idle: 0 });
-/** The strongest state among counts, and the counts themselves. Nothing counted is idle. */
 export function rollUp(counts) {
     return { state: DISPLAY_STATES.find(state => state !== "idle" && counts[state] > 0) ?? "idle", counts };
 }

package/dist/agent-state.js

@@ -1,9 +1,3 @@
-/**
- * One set of agent states (docs/plans/agents-cockpit.md §1): what a person sees at a glance for an attempt, a task, a
- * flow or a project. A display state is derived from four separate facts — what the agent is doing, how it ended, what
- * someone must do, and whether this person has seen it — and never stored as one. Looking clears only `done`: a failure,
- * an approval or a result to accept stays until it is dealt with. The words and colours of each state live here only.
- */
 import { agentFactsFor, agentGroupOf } from "./agents-board.js";
 import { stuckSince } from "./agent-board.js";
 import { wasInterrupted } from "./run-ending.js";
@@ -13,11 +7,9 @@ import { workStateRows } from "./work-index.js";
 import { assignmentChecksForRun } from "./assignment.js";
 import { DISPLAY_STATES, NO_COUNTS, rollUp } from "./agent-state-words.js";
 export { DISPLAY_STATES, NEEDS_SOMEONE, NO_COUNTS, rollUp, STATE_TONE, STATE_WORDS } from "./agent-state-words.js";
-/** The one glance a set of facts gives. */
 export function displayStateOf(facts) {
     if (facts.obligation)
         return "needs-you";
-    // A failure leads until it is dealt with (a retry, a revision, a stop, a cancel): looking never clears it.
     if ((facts.outcome === "failed" || facts.outcome === "checks-failed") && facts.activity === "finished" && facts.newerRunning !== true)
         return "failed";
     if (facts.activity === "stuck")
@@ -28,51 +20,30 @@ export function displayStateOf(facts) {
         return "working";
     if (facts.activity === "queued" || facts.activity === "waiting")
         return "waiting";
-    // Only a good finish is news to be read; looking clears it, and nothing else does.
     if (facts.activity === "finished" && (facts.outcome === "built" || facts.outcome === "no-change") && facts.unread)
         return "done";
     return "idle";
 }
-/** The four facts of one build attempt, from what the Agents board reads (agents-board.ts): its own record only — a
- * stopped or cancelled attempt is not a failure, a parked one is a decision only while it is unanswered and its task is open, and one being
- * repaired is at work, not stuck. */
 export function factsOfAttempt(facts, activityAt, paused, now, decisionOpen) {
     const settled = facts.taskState === "done" || facts.taskState === "cancelled";
     if (facts.outcome === null) {
         const { group } = agentGroupOf(facts, activityAt, now);
         const stuck = !facts.repairing && facts.turn === "busy"
             && stuckSince({ state: "busy", stateAt: facts.stateAt ?? facts.startedAt, transcriptAt: facts.transcriptAt ?? facts.startedAt, toolAt: facts.toolAt }, activityAt, now) !== null;
-        // An open run asking, crashed or blocked is an obligation (the board's "needs you"), whatever else it is doing.
         return { activity: paused ? "paused" : stuck ? "stuck" : "running", outcome: "none", obligation: group === "needs-you", unread: false };
     }
     const unread = !(facts.seen || facts.legacy);
     if (facts.outcome === "built" || facts.outcome === "no-change")
         return { activity: "finished", outcome: facts.outcome, obligation: false, unread };
-    // Stopped by a person or a restart, in either spelling (a legacy outcome, or a failure whose reason is the interruption).
     if (wasInterrupted(facts) || facts.outcome === "refused")
         return { activity: "stopped", outcome: "none", obligation: false, unread };
-    // A parked attempt asks only while its decision is unanswered (when known) and its task is open.
     if (facts.outcome === "parked")
         return { activity: "finished", outcome: "none", obligation: !settled && decisionOpen !== false, unread };
-    // A failure on a task since settled (done another way, or cancelled) no longer leads.
     return { activity: "finished", outcome: settled ? "none" : "failed", obligation: false, unread };
 }
-/** A family's display state from the Tasks list's own classification (work-index.ts): failures that lead, what waits
- * on a person (a result to accept included), work waiting its turn; a complete result is news only until this person
- * has seen it. Running work is counted by its attempts instead. The Tasks list's rules are the rules here — where it
- * says a task waits on a person, so does this — so the two never disagree. */
 const WAITING_CODES = new Set(["queued", "planning-ready", "scouting-ready", "updating", "retry-scheduled", "waiting-dependency", "worker-at-capacity"]);
-/** Codes whose family is at work: its attempts say how. */
 const AT_WORK = new Set(["running", "stopping"]);
-/** Flow cards named per flow in a project's asks; the count stays complete beyond them. */
 const FLOW_ASKS = 50;
-/**
- * A project's states for one person: complete counts over every task family they may see, with the Tasks list's own
- * admission (never a page or the board's rows). Each family counts once for what it needs or how it ended; each live
- * attempt counts once for what it is doing (working, stuck, paused); an attempt that itself needs a person (crashed,
- * asking) counts there unless its family already does. Flow cards at a person's decision count too. Every visible
- * project is present, idle when nothing counts. Its cost is the Tasks list's own read, plus open runs.
- */
 export function projectStates(store, access, account, now, root, flowRepos) {
     const counts = new Map();
     const strongest = new Map();
@@ -94,20 +65,15 @@ export function projectStates(store, access, account, now, root, flowRepos) {
         counts.set(repo, { ...NO_COUNTS });
     const families = workStateRows(store, now, access);
     const refs = families.flatMap(row => row.members);
-    // Every live attempt of these families, every role, in one read.
     const open = refs.length === 0 ? [] : store.handle.prepare(`SELECT r.id, r.task_ref, r.role, r.runner, r.started_at FROM run r
       WHERE r.outcome IS NULL AND r.role IN ('planner','builder','scout','reviewer','repair') AND r.task_ref IN (SELECT value FROM json_each(?))`).all(JSON.stringify(refs));
     const paused = new Set(open.length === 0 ? [] : store.handle.prepare(`SELECT run FROM run_pause WHERE run IN (SELECT value FROM json_each(?))
       AND paused_at IS NOT NULL AND resumed_at IS NULL AND ended_at IS NULL`).all(JSON.stringify(open.map(row => Number(row["id"])))).map(row => Number(row["run"])));
-    // Complete results that are news to this person: recorded since seeing was (a keyed attempt), and not yet seen.
     const completed = JSON.stringify(families.flatMap(row => row.code === "complete" && row.resultRun !== null ? [row.resultRun] : []));
     const unseen = new Set(store.handle.prepare(`SELECT r.id FROM run r WHERE r.id IN (SELECT value FROM json_each(?)) AND r.attempt_key IS NOT NULL
       AND NOT EXISTS (SELECT 1 FROM agent_seen s WHERE s.account = ? AND s.run = r.id)`).all(completed, account).map(row => Number(row["id"])));
-    // A result's outcome and its recorded check, for the families whose result is waiting on a person.
     const resultFacts = new Map(store.handle.prepare(`SELECT r.id, r.outcome, (SELECT c.status FROM run_check c WHERE c.run = r.id) AS recorded FROM run r
       WHERE r.id IN (SELECT value FROM json_each(?))`).all(JSON.stringify(families.flatMap(row => row.resultRun ?? []))).map(row => [Number(row["id"]), row]));
-    // The result's checks as the result reads them (follow-up checks included); the recorded check only when nothing
-    // else was read, so a passing follow-up clears an earlier failure.
     const checksFailed = (run) => {
         const status = assignmentChecksForRun(store, root, run, now).status;
         if (status === "failed" || status === "passed")
@@ -121,8 +87,6 @@ export function projectStates(store, access, account, now, root, flowRepos) {
     const attempting = new Set(open.map(run => familyOf.get(Number(run["task_ref"]))?.rootId));
     const needing = new Set();
     for (const row of families) {
-        // At work: its attempts are counted below; a stop whose run has ended but whose process is not yet confirmed gone
-        // is still at work.
         if (AT_WORK.has(row.code)) {
             if (!attempting.has(row.rootId))
                 bump(row.repo, "working", row.rootId);
@@ -133,18 +97,15 @@ export function projectStates(store, access, account, now, root, flowRepos) {
             bump(row.repo, "failed", row.rootId);
             continue;
         }
-        // Waiting its turn, as the Tasks list ranks it: confirmations another computer owes included.
         if (row.waits) {
             bump(row.repo, "waiting", row.rootId);
             continue;
         }
-        // A result waiting on a person is a failure when it failed or its checks failed (as its headline reads).
         const asks = row.code === "ready-to-check" || row.code === "result-needs-attention";
         if (asks && (result?.["outcome"] === "failed" || (row.resultRun !== null && checksFailed(row.resultRun)))) {
             bump(row.repo, "failed", row.rootId);
             continue;
         }
-        // A family the person's lead has taken on waits on nobody (the Tasks list's rule); a failure still leads, above.
         if (row.leadClaim) {
             bump(row.repo, "waiting", row.rootId);
             continue;
@@ -162,13 +123,11 @@ export function projectStates(store, access, account, now, root, flowRepos) {
         if (row.code === "complete" && row.resultRun !== null && unseen.has(row.resultRun))
             bump(row.repo, "done", row.rootId);
     }
-    // Each live attempt: paused, stuck or at work; one that needs a person counts there, unless its family already does.
     for (const run of open) {
         const family = familyOf.get(Number(run["task_ref"]));
         if (family === undefined)
             continue;
         const id = Number(run["id"]);
-        // What the agent did last, in the task page's own words: the rail's line for this family.
         const activity = runActivityOf(store, { id, runner: String(run["runner"]), startedAt: String(run["started_at"]) }, now);
         const line = activity.what === "" ? null : activity.what;
         if (paused.has(id)) {
@@ -178,7 +137,7 @@ export function projectStates(store, access, account, now, root, flowRepos) {
         if (run["role"] !== "builder") {
             bump(family.repo, "working", family.rootId, line);
             continue;
-        } // only builds are watched for quiet
+        }
         const facts = agentFactsFor(store, id, { repos: null }, account);
         if (facts === null || facts.outcome !== null) {
             bump(family.repo, "working", family.rootId, line);
@@ -198,11 +157,8 @@ export function projectStates(store, access, account, now, root, flowRepos) {
         }
         bump(family.repo, state === "stuck" ? "stuck" : "working", family.rootId, line);
     }
-    // Flow cards waiting at a person's decision (an approval or a choice), in the flows this person may see: one uncapped
-    // count per flow over its deciding zones.
     const repos = flowRepos ?? (access.repos ?? store.listProjects().map(one => one.path));
     const deciding = store.handle.prepare("SELECT COUNT(*) AS n FROM flow_card WHERE flow = ? AND state = 'active' AND stage IN (SELECT value FROM json_each(?))");
-    // A card's visit began when it entered its stage (its newest arrival there): fixed for the visit, unlike updated_at.
     const namedCards = store.handle.prepare(`SELECT c.id, c.stage, c.entry, COALESCE((SELECT MAX(e.at) FROM flow_event e WHERE e.card = c.id AND e.to_stage = c.stage), c.created_at) AS entered_at
     FROM flow_card c WHERE c.flow = ? AND c.state = 'active' AND c.stage IN (SELECT value FROM json_each(?)) ORDER BY entered_at DESC, c.id DESC LIMIT ?`);
     for (const flow of store.listFlows(repos)) {

package/dist/agent-turns.js

@@ -1,18 +1,13 @@
 import { topLevelEvent } from "./stream-scope.js";
-/** What one stream event says about the turn; null when it says nothing. */
 export function turnSignalOf(event) {
     const type = typeof event["type"] === "string" ? event["type"] : "";
-    // A subagent's events are not the parent's turn: its result never marks the parent idle or clears its open tools,
-    // and its init or words never mark it busy (stream-scope.ts).
     if (!topLevelEvent(event))
         return null;
     switch (type) {
-        // Claude stream-json: the session starts, the assistant speaks or calls a tool, a tool answers; then one result.
         case "system": return event["subtype"] === "init" ? "busy" : null;
         case "assistant":
         case "user": return "busy";
         case "result": return "idle";
-        // Codex --json: a thread and its turns start, items run; a turn completes or fails.
         case "thread.started":
         case "turn.started":
         case "item.started":
@@ -20,7 +15,6 @@ export function turnSignalOf(event) {
         case "item.completed": return "busy";
         case "turn.completed":
         case "turn.failed": return "idle";
-        // Gemini stream-json, which the same live log reads.
         case "init":
         case "tool_use":
         case "tool_call":
@@ -28,13 +22,11 @@ export function turnSignalOf(event) {
         default: return null;
     }
 }
-/** At most this many open calls are tracked; past it, a new one is not (the oldest still holds the long threshold). */
 export const OPEN_TOOLS_CAP = 64;
 const CODEX_TOOL_ITEMS = new Map([["command_execution", "command"], ["mcp_tool_call", "tool"], ["web_search", "tool"], ["file_change", "tool"]]);
 const COMMAND_TOOLS = new Set(["Bash", "BashOutput"]);
 const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 const callId = (value) => typeof value === "string" && value !== "" && value.length <= 200 ? value : null;
-/** The tool calls one stream event opens and closes, by id: only Claude's and Codex's known shapes. */
 export function toolCallsOf(event) {
     const opened = [], closed = [];
     const type = event["type"];
@@ -64,11 +56,6 @@ export function toolCallsOf(event) {
     }
     return { opened, closed };
 }
-/**
- * Watch a run's stream for turn changes, beside its live log (which may be
- * null), and for the oldest tool call still open (recordTool hears it move;
- * a turn that leaves busy closes them all, and its own record clears them).
- */
 export function withAgentTurns(inner, record, clock, recordTool = () => { }) {
     let state = null;
     let spoke = false;
@@ -85,7 +72,7 @@ export function withAgentTurns(inner, record, clock, recordTool = () => { }) {
         try {
             record(next, clock());
         }
-        catch { /* display state: the next change tries again */ }
+        catch { }
     };
     const tools = (event) => {
         const calls = toolCallsOf(event);
@@ -104,7 +91,7 @@ export function withAgentTurns(inner, record, clock, recordTool = () => { }) {
         try {
             recordTool(first, at);
         }
-        catch { /* display state: the next change tries again */ }
+        catch { }
     };
     return {
         observe(event) {
@@ -126,14 +113,13 @@ export function withAgentTurns(inner, record, clock, recordTool = () => { }) {
                 try {
                     tools(event);
                 }
-                catch { /* an unreadable call: the turn's result closes it */ }
+                catch { }
             }
         },
         close() { inner?.close(); },
         ended() {
             if (state === "crashed")
                 return;
-            // A process that never spoke, or whose last turn never reported its result, ended without one.
             if (!spoke || state !== "idle")
                 move("crashed");
         },