toolroll 0.9.103 → 0.9.105

package/dist/commit-extract.js

@@ -1,30 +1,15 @@
-/**
- * The approved commit's files, written by Toolroll itself from a repository's object store (docs/plans/approval-policy.md
- * §1.7): the release runs the deployment script from what this writes, never from the candidate's checkout.
- *
- * No conversion of any kind: `git cat-file --batch` hands back each object's stored bytes, and this code hashes the
- * commit, every tree and every blob itself against the ids that name them and parses the trees itself, so no filter, smudge, textconv, export-subst, export-ignore or other attribute (from the repository's
- * config, `info/attributes` or the tree's own `.gitattributes`) can change or add a byte. Before any read the
- * repository's own config is refused if it names a command or includes another file (teardown-git.ts), and git runs
- * with no system or global config, no replacement objects, no lazy fetch, no hooks and no fsmonitor. Only regular
- * files are written (mode 644, or 755 when the tree says executable), each at a normalized path inside the folder;
- * symlinks, submodules and any other entry refuse the whole extraction.
- */
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { commandSetting, viewedGitSync } from "./teardown-git.js";
 const MAX_BYTES = 1024 * 1024 * 1024;
 export const EXTRACTION_LIMITS = Object.freeze({ bytes: MAX_BYTES, files: 50_000, entries: 200_000, depth: 64 });
-/** A tree path that stays where it says: relative, no empty, `.` or `..` part, no backslash or control character. */
 export function normalizedTreePath(path) {
     if (path === "" || path.startsWith("/") || /[\u0000-\u001f\\]/.test(path))
         return false;
     return path.split("/").every(part => part !== "" && part !== "." && part !== "..");
 }
-/** The object id Git gives `<type> <size>\0<bytes>` in this repository's object format. */
 export const objectIdOf = (format, type, bytes) => createHash(format).update(`${type} ${bytes.length}\0`).update(bytes).digest("hex");
-/** A tree object's entries, parsed from its verified bytes: `<mode> <name>\0<raw id>` each. Null when malformed. */
 export function parseTree(bytes, idBytes) {
     const entries = [];
     let at = 0;
@@ -37,11 +22,6 @@ export function parseTree(bytes, idBytes) {
     }
     return entries;
 }
-/**
- * Why a commit's file paths can't all be written as separate regular files, or null: a `.git` part, a path twice, two
- * paths that are one on a case-insensitive or Unicode-normalizing file system (macOS), or a path that is both a file
- * and a folder. scripts/deploy-git.mjs writtenPathsProblem keeps the same rules (held equal by test).
- */
 export function writtenPathsProblem(paths) {
     const folded = new Map();
     for (const path of paths) {
@@ -65,14 +45,9 @@ export function writtenPathsProblem(paths) {
     }
     return null;
 }
-/** Write commit `sha` of the repository whose Git directory is `gitDir` (a realpath Toolroll took from its own
- * records) into `dest`, an empty folder this process made. Every object on the way — the commit, each tree, each
- * blob — is hashed here and must be the id that names it: Git's own answer about an id is never taken on trust, so a
- * corrupted or replaced object in a store a build could write to refuses the extraction. */
 export function extractCommit(gitDir, sha, dest, limits = EXTRACTION_LIMITS) {
     const refuse = (message) => ({ ok: false, message });
     const git = protectedGit(gitDir, {}, []);
-    // The repository's own config, read without includes, must name no command and include nothing.
     const config = git(["config", "--list", "--no-includes", "--show-scope", "-z"]);
     if (config.refused !== null)
         return refuse(`The project's Git directory can't be read safely: ${config.refused}.`);
@@ -86,7 +61,6 @@ export function extractCommit(gitDir, sha, dest, limits = EXTRACTION_LIMITS) {
     const hexLength = format === "sha1" ? 40 : 64;
     if (!new RegExp(`^[0-9a-f]{${hexLength}}$`).test(sha))
         return refuse(`${sha} isn't a full commit id.`);
-    /** Objects by id, each read raw (`cat-file --batch`: "<id> <type> <size>\n<bytes>\n") and hashed here. */
     const read = (ids) => {
         const batch = git(["cat-file", "--batch"], Buffer.from(ids.map(id => `${id}\n`).join(""), "utf8"));
         if (batch.status !== 0)
@@ -120,7 +94,6 @@ export function extractCommit(gitDir, sha, dest, limits = EXTRACTION_LIMITS) {
     const treeLine = new RegExp(`^tree ([0-9a-f]{${hexLength}})\n`).exec(commitObject.bytes.toString("utf8"));
     if (treeLine === null)
         return refuse("The approved commit names no tree.");
-    // Walk the trees from their verified bytes, level by level; collect every file.
     const files = [];
     let level = [{ id: treeLine[1], prefix: "" }];
     let depth = 0, walked = 0;
@@ -170,7 +143,6 @@ export function extractCommit(gitDir, sha, dest, limits = EXTRACTION_LIMITS) {
     const blobs = read([...new Set(files.map(one => one.id))]);
     if (typeof blobs === "string")
         return refuse(`The approved commit couldn't be verified: ${blobs}.`);
-    // What would be written, every path counted (a blob shared by many paths is written once per path).
     let total = 0;
     for (const file of files) {
         total += blobs.get(file.id).bytes.length;
@@ -187,7 +159,6 @@ export function extractCommit(gitDir, sha, dest, limits = EXTRACTION_LIMITS) {
             return refuse(`The path ${file.path} leaves the folder.`);
         try {
             mkdirSync(join(target, ".."), { recursive: true, mode: 0o755 });
-            // "wx": never over anything already there (no file twice, no file where a folder is).
             writeFileSync(target, blob.bytes, { flag: "wx", mode: file.mode === "100755" ? 0o755 : 0o644 });
         }
         catch (error) {
@@ -196,17 +167,8 @@ export function extractCommit(gitDir, sha, dest, limits = EXTRACTION_LIMITS) {
     }
     return { ok: true, files: files.length };
 }
-/**
- * How the protected readers run git on the project's Git directory (eval-harness review 1, finding 5): never a fetch.
- * Every command, on every git version, runs through a frozen view of the repository (teardown-git.ts viewedGitSync,
- * findings 5 and 7): its config read once into a folder of the plane's own and inspected there — an include, a key that
- * names a command, every `protocol.*` key and (on a git without `--no-lazy-fetch`) a partial clone refused — which is
- * the config git then runs with, bounded in time. Every run also denies every transport (`protocol.allow=never`) and,
- * on git 2.45+, takes `--no-lazy-fetch`; nothing leans on GIT_NO_LAZY_FETCH, which 2.41.0 ignores.
- */
 function protectedGit(gitDir, runner, extra) {
     const base = ["--no-replace-objects", "-c", "protocol.allow=never", ...extra];
-    // The view is of a checkout: the project's own `.git` folder, as Toolroll records it.
     const checkout = basename(gitDir) === ".git" ? dirname(gitDir) : null;
     return (args, input) => {
         if (checkout === null)
@@ -220,13 +182,9 @@ function protectedGit(gitDir, runner, extra) {
         }
     };
 }
-/** A reader over the project's object store that hashes every object it hands back, or why it can't be one. */
 function verifiedReader(gitDir, runner = {}) {
     const refuse = (message) => ({ ok: false, message });
-    // The commit-graph file is a cache a build can write: parents come from the objects themselves, never from it.
     const git = protectedGit(gitDir, runner, ["-c", "core.commitGraph=false"]);
-    // History a build could have rewritten around the objects: a shallow boundary, grafts, or replacement refs. Each is
-    // refused outright, so no reader here ever has to decide whether to believe one.
     if (existsSync(join(gitDir, "shallow")))
         return refuse("The project's history is shallow, so the commits between the approval and this one can't all be read.");
     if (existsSync(join(gitDir, "info", "grafts")))
@@ -279,7 +237,6 @@ function verifiedReader(gitDir, runner = {}) {
     };
     return { ok: true, value: { format, hexLength, read, git } };
 }
-/** Parse a commit from its verified bytes: tree, parents, message. Null when malformed. */
 function parseCommit(id, bytes, hexLength) {
     const text = bytes.toString("utf8");
     const split = text.indexOf("\n\n");
@@ -297,7 +254,6 @@ function parseCommit(id, bytes, hexLength) {
     }
     return { id, tree: tree[1], parents, message: split < 0 ? "" : text.slice(split + 2) };
 }
-/** One commit, hashed here and parsed from its own bytes. */
 export function readVerifiedCommit(gitDir, sha) {
     const reader = verifiedReader(gitDir);
     if (!reader.ok)
@@ -314,11 +270,6 @@ function readCommitWith(reader, sha) {
     const commit = parseCommit(sha, object.bytes, reader.hexLength);
     return commit === null ? { ok: false, message: `Commit ${sha.slice(0, 7)} couldn't be read.` } : { ok: true, value: commit };
 }
-/**
- * The commits from `from` back to `until` along first parents, newest first, `until` itself left out. Refuses when
- * `until` isn't reached within `max` commits (it isn't an ancestor, or too much lies between), and hands back each
- * commit's full parent list so a caller can refuse merges.
- */
 export function verifiedFirstParentWalk(gitDir, from, until, max = 200) {
     const reader = verifiedReader(gitDir);
     if (!reader.ok)
@@ -339,8 +290,6 @@ export function verifiedFirstParentWalk(gitDir, from, until, max = 200) {
     }
     return { ok: true, value: commits };
 }
-/** Every entry of a verified tree at its full path, symlinks and submodules included (a caller decides on them). An
- * unnormalized path, or one a tree lists twice, refuses the whole read. */
 export function verifiedTreeEntries(gitDir, tree, limits = EXTRACTION_LIMITS) {
     const reader = verifiedReader(gitDir);
     if (!reader.ok)
@@ -391,16 +340,12 @@ function treeEntriesWith(reader, root, limits) {
     }
     return { ok: true, value: entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) };
 }
-/** Whether bytes look binary: a NUL in the first 8000 bytes, as Git judges. */
 export const looksBinary = (bytes) => bytes.subarray(0, 8000).includes(0);
-/** The lines added and deleted from `before` to `after`, by the shortest edit (Myers): each counted once, stopped at
- * `cap` total edits (the counts then add up to more than `cap`, which every limit here refuses). */
 export function lineChanges(before, after, cap = 100_000) {
     const split = (bytes) => { const text = bytes.toString("utf8"); if (text === "")
         return []; const lines = text.split("\n"); if (lines[lines.length - 1] === "")
         lines.pop(); return lines; };
     const a = split(before), b = split(after);
-    // Trim the common start and end first: most changes are small.
     let start = 0;
     while (start < a.length && start < b.length && a[start] === b[start])
         start++;
@@ -430,14 +375,8 @@ export function lineChanges(before, after, cap = 100_000) {
             }
         }
     }
-    // Past the cap: report everything as changed, which is more than any limit allows.
     return { added: m, deleted: n };
 }
-/**
- * What differs between two verified trees, path by path (no rename pairing: a moved file is a deletion and an
- * addition). Text files get their added and deleted lines; a binary side, a symlink or a submodule is marked so a caller
- * can refuse it.
- */
 export function verifiedTreeDiff(gitDir, beforeTree, afterTree) {
     const reader = verifiedReader(gitDir);
     if (!reader.ok)
@@ -475,8 +414,6 @@ export function verifiedTreeDiff(gitDir, beforeTree, afterTree) {
     }
     return { ok: true, value: changes };
 }
-/** The ids of verified blobs at these paths of a tree (absent paths left out): a digest's inputs, read without
- * running anything. */
 export function verifiedBlobs(gitDir, tree, paths) {
     const reader = verifiedReader(gitDir);
     if (!reader.ok)
@@ -490,13 +427,6 @@ export function verifiedBlobs(gitDir, tree, paths) {
         return { ok: false, message: `A file couldn't be verified: ${blobs}.` };
     return { ok: true, value: new Map(wanted.map(one => [one.path, { id: one.id, bytes: blobs.get(one.id).bytes }])) };
 }
-/**
- * The commits reachable from `to` and not from `from`, as Git lists them (newest first), each read from its own verified
- * bytes: what a release card says changed (release-card.ts). Git only names them. Each is hashed here and its parents
- * checked against Git's listing; every commit the range stops at (a parent outside it) must be reached from `from`
- * through verified parents within `reach` commits, so history a build rewrote around the objects can't shorten the
- * list. A shallow boundary, grafts or replacement refs refuse (verifiedReader), as does a range longer than `max`.
- */
 export function verifiedRange(gitDir, from, to, options = {}) {
     const { max = 1_000, reach = 5_000 } = options;
     const reader = verifiedReader(gitDir, options);
@@ -506,7 +436,6 @@ export function verifiedRange(gitDir, from, to, options = {}) {
     const id = new RegExp(`^[0-9a-f]{${hexLength}}$`);
     if (!id.test(from) || !id.test(to))
         return { ok: false, message: "A commit id isn't a full id." };
-    /** Git's listing: each line's commit (`-` marks a boundary) and the parents it names. */
     const listing = (args) => {
         const listed = git(["rev-list", "--parents", ...args]);
         if (listed.status !== 0)
@@ -533,7 +462,6 @@ export function verifiedRange(gitDir, from, to, options = {}) {
         const commit = object.type === "commit" ? parseCommit(row.id, object.bytes, hexLength) : null;
         if (commit === null)
             return { ok: false, message: `${row.id.slice(0, 7)} isn't a commit.` };
-        // Git's parents must be the commit's own, and each one inside the range or where it stops.
         if (commit.parents.join(" ") !== row.parents.join(" "))
             return { ok: false, message: `Git's history of ${row.id.slice(0, 7)} isn't its own.` };
         if (commit.parents.some(parent => !listed.has(parent) && !stops.has(parent)))
@@ -542,8 +470,6 @@ export function verifiedRange(gitDir, from, to, options = {}) {
     }
     if (inside.length > 0 && !listed.has(to))
         return { ok: false, message: `${to.slice(0, 7)} isn't in its own range.` };
-    // Where the range stops: each must be `from` or one of its verified ancestors. An empty range says `to` is already in
-    // the last release: that too is proved, never taken from Git's listing.
     const wanted = [...stops, ...(inside.length === 0 ? [to] : [])].filter(one => one !== from);
     if (wanted.length === 0)
         return { ok: true, value: commits };
@@ -567,21 +493,12 @@ export function verifiedRange(gitDir, from, to, options = {}) {
     const unreached = wanted.find(one => !reached.has(one));
     return unreached === undefined ? { ok: true, value: commits } : { ok: false, message: `${unreached.slice(0, 7)} isn't verified as part of the last release's history.` };
 }
-/**
- * Whether `until` lies on `from`'s first-parent history, within a deadline (nightly-github.ts): "yes" when the walk
- * reaches it; "no" only when it is PROVEN not to — `until` is itself a readable, verified commit and every commit from
- * `from` back to the root was read and verified without meeting it; "unknown" for anything less certain (an object
- * missing or unreadable, `max` commits walked, the deadline reached). Every git call is bounded by what is left of
- * the deadline, at most `callMs`.
- */
 export function verifiedFirstParentAncestry(gitDir, from, until, options) {
     const now = options.now ?? Date.now;
     const left = () => options.deadline - now();
-    // Every answer is checked against the deadline as it is given: nothing past it is ever "yes" or "no".
     const answer = (value) => left() > 0 ? value : "unknown";
     if (left() <= 0)
         return "unknown";
-    // The absolute deadline goes down to every subprocess (setup included); each call is also held to `callMs`.
     const reader = verifiedReader(gitDir, { timeoutMs: options.callMs ?? 10_000, deadline: options.deadline });
     if (!reader.ok)
         return "unknown";

package/dist/connect-cli.js

@@ -1,8 +1,3 @@
-/**
- * `toolroll connect`: saves a central server's origin and your API token in a private profile file. Remote commands
- * (remote-exec.ts) and `toolroll health` sign in with it; nothing here opens the local database except to find the
- * existing local sign-in for --local-login.
- */
 import { constants, closeSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -21,8 +16,6 @@ const HELP = `toolroll connect <HTTPS-origin> --as <account> --token-stdin
   Optional: --profile <name> (saved as the active profile).`;
 export class UsageError extends Error {
 }
-/** Credentials are never sent to a URL with embedded authority, an API path, query, fragment or an insecure remote
- * host. Fetch cannot follow redirects. */
 export function serviceOrigin(raw) {
     let url;
     try {
@@ -44,7 +37,6 @@ const strings = (input) => Array.isArray(input) && input.every(one => typeof one
 const accountValid = (input) => !!input && input.length <= 200 && !/[\s:\x00-\x1f\x7f]/.test(input);
 const tokenValid = (input) => !!input && input.length <= 8192 && !/[\s\x00-\x1f\x7f]/.test(input);
 const profilePath = (options) => options.profileFile ?? namedPath(configBase(options.env ?? process.env, options.home ?? homedir()), ['remote', 'profiles.json']);
-/** Open the file itself without following a symlink; nonblocking also rejects FIFOs safely. */
 function privateFile(path, limit) {
     let fd;
     try {
@@ -67,7 +59,6 @@ function privateFile(path, limit) {
 }
 function profiles(options) {
     const path = profilePath(options);
-    // lstat distinguishes a dangling symlink from a missing profile.
     try {
         lstatSync(path);
     }
@@ -121,12 +112,8 @@ function saveProfile(options, name, profile) {
             unlinkSync(temporary);
     }
 }
-/** An API token (so_…) is sent bare; an older saved sign-in keeps its account:secret form. */
 export const bearerOf = (profile) => parseApiToken(profile.token) !== null ? `Bearer ${profile.token}` : `Bearer ${profile.account}:${profile.token}`;
-/** The saved central profile remote commands use: the named one (or the active one), and whether it holds an API token.
- * null when nothing is saved. Reads only the private profile file — never a local login or the database. */
 export function hasCentralProfile(options) {
-    // An unreadable or invalid profile file still names a central service: the caller refuses rather than run locally.
     try {
         return profiles(options) !== null;
     }
@@ -217,7 +204,6 @@ function parse(argv) {
 function isMessage(one) {
     return record(one) && Number.isSafeInteger(one.id) && typeof one.author === 'string' && ['operator', 'assistant'].includes(String(one.role)) && typeof one.text === 'string' && ['queued', 'running', 'answered', 'failed', 'cancelled', 'uncertain'].includes(String(one.status)) && Number.isSafeInteger(one.revision) && typeof one.createdAt === 'string' && (one.requestId === null || typeof one.requestId === 'string') && (one.turnId === null || Number.isSafeInteger(one.turnId)) && (one.error === null || typeof one.error === 'string');
 }
-/** The listing a central service answers `list` with; a reply without a well-formed one is no proof of a service. */
 function isSnapshot(one) {
     if (!record(one) || !Array.isArray(one.leads) || !one.leads.every(lead => record(lead) && typeof lead.id === 'string' && typeof lead.name === 'string') || !Array.isArray(one.conversations) || !one.conversations.every(conversation => record(conversation) && typeof conversation.id === 'string' && typeof conversation.leadId === 'string' && typeof conversation.title === 'string') || !(one.selected === null || record(one.selected) && typeof one.selected.id === 'string' && typeof one.selected.leadId === 'string' && typeof one.selected.title === 'string') || !Array.isArray(one.participants) || !one.participants.every(participant => record(participant) && typeof participant.account === 'string' && ['viewer', 'contributor', 'manager'].includes(String(participant.role)) && typeof participant.active === 'boolean') || !Array.isArray(one.messages) || !one.messages.every(isMessage) || typeof one.canManage !== 'boolean' || typeof one.canSend !== 'boolean' || !Number.isSafeInteger(one.cursor) || typeof one.truncated !== 'boolean' || !strings(one.projects) || !strings(one.accounts))
         return false;
@@ -235,8 +221,6 @@ function isSnapshot(one) {
         return false;
     return true;
 }
-/** The server must accept the credential before it is saved: one read of POST /api/team, never retried. A success
- * proves itself with a well-formed listing, as the central `list` it is. */
 async function verify(profile, options) {
     const unconfirmed = { version: 1, ok: false, code: 'service-unavailable', message: 'The service response could not be read.' };
     try {
@@ -260,7 +244,6 @@ async function verify(profile, options) {
         return unconfirmed;
     }
 }
-/** `toolroll connect …`; null for every other command. Nothing here opens a database. */
 export async function maybeRunConnectCommand(argv, write, options = {}) {
     if (argv[0] !== 'connect')
         return null;
@@ -268,12 +251,10 @@ export async function maybeRunConnectCommand(argv, write, options = {}) {
     let secret = '';
     const stderr = (line) => (options.stderr ?? (line => process.stderr.write(`${line}\n`)))(text(secret ? line.replaceAll(secret, '[redacted]') : line));
     const emit = (reply) => {
-        // A server's words can echo the credential it was sent: every string it says is redacted before it is shown.
         const safe = JSON.parse(JSON.stringify(reply, (_key, one) => typeof one === 'string' && secret ? one.replaceAll(secret, '[redacted]') : one));
         write(json ? envelopeJson({ ...safe, command: 'team connect' }) : text(safe.message));
     };
     try {
-        // D5: `connect` belongs to the deprecated central team service; it still saves the profile remote commands use.
         stderr(deprecationWarning('connect', 'team'));
         if (argv.includes('--help')) {
             write(HELP);

package/dist/console-chrome.js

@@ -1,39 +1,22 @@
-/**
- * The console's shared chrome (the sidebar's project states, the Tasks count, the crew list): computed at most once
- * per workspace revision for one reader's exact access, and readable on a read worker (read-executor.ts) as well as on
- * the request thread. Cache metadata only: nothing here grants access. Every entry's key carries every authorization
- * input its computation reads (the reader, their admitted projects, whether they see unplaced work, the projects their
- * sidebar may list), so a value read for one scope is never served to another.
- */
 import { createHash } from "node:crypto";
 import { NO_COUNTS, projectStates, STATE_WORDS } from "./agent-state.js";
 import { boundProjectSummary } from "./browser-workspace.js";
 import { WORK_INDEX_MAX_LIMIT, workIndexPage } from "./work-index.js";
-/** Tasks the rail lists under a project; the rest are a count that links to the project's tasks. */
 const RAIL_TASKS = 6;
-/** Asks a project names for the chime (its count is complete beyond them). */
 const ASKS_PER_PROJECT = 100;
-/** The sidebar's projects with their states (agent-state.ts) for one reader: the page's first read and the summary
- * room's snapshots are this one function, so the two never disagree. Never marks anything seen. Work with no project
- * yet is its own entry when this reader may see it and something counts there. */
 export function projectSummaryOf(store, now, access, actor, projects, evidenceRoot) {
     const states = new Map(projectStates(store, access, actor, now, evidenceRoot, projects.map(one => one.path)).map(one => [one.repo, one]));
-    // A row that needs a person or failed says what the Tasks list says it needs (its own next step); a row at work says
-    // what its agent did last; a finished one says Done.
     const asking = [...states.values()].flatMap(one => one.families.slice(0, RAIL_TASKS)).filter(one => one.state === "needs-you" || one.state === "failed").map(one => one.rootId);
     const needWords = new Map();
     if (asking.length > 0) {
         try {
-            // Every row the rail may list, in pages the index allows.
             for (let at = 0; at < asking.length; at += WORK_INDEX_MAX_LIMIT)
                 for (const item of workIndexPage(store, now, access, { roots: asking.slice(at, at + WORK_INDEX_MAX_LIMIT), limit: WORK_INDEX_MAX_LIMIT, ...(evidenceRoot === undefined ? {} : { root: evidenceRoot }) }).items)
                     needWords.set(item.rootId, item.status.detail !== "" ? item.status.detail : item.status.label);
         }
-        catch { /* the rows keep their state's words */ }
+        catch { }
     }
-    // The chime's subjects: an opaque key per obligation and version, scoped to this reader (no words, no ids in it).
     const keyOf = (...parts) => createHash("sha256").update([actor, ...parts].join("\u0000")).digest("base64url").slice(0, 22);
-    // Newest first, so a new ask always has a key however many older ones wait (those were heard when they were new).
     const asksOf = (state) => [
         ...(state?.families ?? []).flatMap(one => one.ask === undefined ? [] : [{ at: one.ask.at, ask: { key: keyOf("task", one.rootId, one.ask.version), task: one.rootId, run: one.ask.run, at: one.ask.at } }]),
         ...(state?.flowAsks ?? []).map(one => ({ at: one.at, ask: { key: keyOf("flow", one.card, one.stage, one.entry), task: null, run: null, at: one.at } })),
@@ -56,8 +39,6 @@ export function projectSummaryOf(store, now, access, actor, projects, evidenceRo
         rows.push({ path: null, name: "No project", href: "/tasks", state: unplaced.state, counts: unplaced.counts, ...railOf(unplaced) });
     return boundProjectSummary(rows);
 }
-/** One access, canonically and in full (every field it has, so a field added later keys too): the same reader and
- * scope always spell the same key, whatever order its projects came in. */
 export function accessKey(access) {
     const record = access;
     return JSON.stringify(Object.keys(record).sort().map(name => {
@@ -65,13 +46,6 @@ export function accessKey(access) {
         return [name, Array.isArray(value) ? [...new Set(value.map(String))].sort() : value === undefined ? null : value];
     }));
 }
-/**
- * Values read from the database, each kept while the workspace revision (workspace-revision.ts: every meaningful
- * commit, from any process, moves it) is the one it was read at, and never past the revision's own clock boundary
- * (a lease or liveness window ending) or `maxAgeMs`, whichever is first — time alone (an agent going quiet) shows
- * within that bound. A value is stored under the revision read before it was computed, so a commit that lands while it
- * is computed only makes it miss sooner. Callers must not change a value they were handed.
- */
 export class RevisionCache {
     #entries = new Map();
     #revision;
@@ -84,7 +58,6 @@ export class RevisionCache {
         this.#maxEntries = options.maxEntries ?? 128;
         this.#maxAgeMs = options.maxAgeMs ?? 30_000;
     }
-    /** The value for `key` at the current revision, or undefined. */
     peek(key) {
         const entry = this.#entries.get(key);
         if (entry === undefined)
@@ -102,7 +75,6 @@ export class RevisionCache {
         }
         return entry.value;
     }
-    /** The cached value, or `compute()` now (stored for the next reader). Errors are never cached. */
     read(key, compute) {
         const hit = this.peek(key);
         if (hit !== undefined)
@@ -113,8 +85,6 @@ export class RevisionCache {
             this.#store(key, started, value);
         return value;
     }
-    /** The cached value, or one read asynchronously (a read worker) and stored. A failure answers undefined and leaves
-     * the key empty, so the request thread computes it as before. */
     async fill(key, compute) {
         const hit = this.peek(key);
         if (hit !== undefined)
@@ -129,8 +99,6 @@ export class RevisionCache {
         catch {
             return undefined;
         }
-        // A worker can finish after an approval changed or a lease expired. Its caller must not pin that old answer
-        // into a request even though the shared cache would reject it on the next lookup.
         try {
             if (this.#revision.current() !== started.revision || this.#clock().getTime() >= started.expiresAt)
                 return undefined;
@@ -157,7 +125,6 @@ export class RevisionCache {
         this.#entries.set(key, { ...started, value });
     }
 }
-/** The keys the console's chrome reads are kept under (serve.ts and its read-worker prefetch spell them the same). */
 export const countsKey = (access) => `counts\u0000${accessKey(access)}`;
 export const summaryKey = (actor, access, projects) => `summary\u0000${actor}\u0000${accessKey(access)}\u0000${JSON.stringify(projects.map(one => [one.path, one.name]))}`;
 export const indexKey = (access, options) => {