toolroll 0.9.104 → 0.9.105

package/dist/subagents.js

@@ -1,21 +1,3 @@
-/**
- * subagents (v92): agents that work a flow's cards the way an employee
- * would, within rules a person wrote for them.
- *
- * A subagent is a soul file: who it is, how it writes, what it knows, what it
- * decides on its own, what it asks about first, and what it never does. It is
- * staffed on zones: a "Person decides" zone it decides (approve, send back,
- * or hand it to a person), or a "Subagent handles it" zone where it picks
- * where the card goes and writes what the next zones send. It never acts
- * itself: each turn answers with one decision as JSON, through Claude with no
- * tools, no repository and no MCP servers, and Toolroll carries it out
- * within the zone's choices. The card is data, never instructions. (v94: it
- * may ask for a project tool call on its turn; Toolroll makes it, or
- * asks a person first, by the rules in subagent-tools.ts.)
- *
- * Subagents do flow work only: they never approve a code task, a merge or
- * spending — those stay with people (or a signed hands-off mode).
- */
 import { inEvalWorld } from "./eval-gate.js";
 import { Buffer } from "node:buffer";
 import { strictJsonParse } from "./converse.js";
@@ -27,9 +9,7 @@ import { readTurnAnswer, TURN_MODEL_SCHEMA } from "./contracts/subagent-turn.js"
 import { LIMITS } from "./decision.js";
 import { overruns, TEXT_LIMITS } from "./text-limits.js";
 export const SOUL_CHARS = 12_000;
-/** A handle from a name: "Maya" → "maya". */
 export const handleOf = (name) => name.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "subagent";
-/** A soul file read: its name and role (front matter) and its sections. */
 export function parseSoul(text) {
     const normal = text.replace(/\r\n?/g, "\n").trim();
     if (normal.length > SOUL_CHARS)
@@ -57,7 +37,6 @@ export function parseSoul(text) {
         return { ok: false, problem: "Write at least one section, like “## Who you are”, saying who the subagent is." };
     return { ok: true, soul: { name, role, sections } };
 }
-/** A soul file with one section replaced (by title, any case), or added at the end when it has no such section. */
 export function withSection(soul, title, text) {
     const wanted = title.replace(/^#+\s*/, "").trim();
     const body = text.replace(/\r\n?/g, "\n").trim();
@@ -70,7 +49,6 @@ export function withSection(soul, title, text) {
     return `${parts.join("").trimEnd()}\n`;
 }
 const soul = (name, role, parts) => `---\nname: ${name}\nrole: ${role}\n---\n\n${Object.entries(parts).map(([title, lines]) => `## ${title}\n${lines.join("\n")}`).join("\n\n")}\n`;
-/** Starters to copy and make your own. Every rule is plain words the subagent reads each turn. */
 export const SUBAGENT_TEMPLATES = [
     {
         id: "support", label: "Support rep", about: "Answers customers, handles refunds and replacements within limits, and hands angry or costly cases to you.",
@@ -117,12 +95,7 @@ export const SUBAGENT_TEMPLATES = [
         }),
     },
 ];
-/** Each field's limit, in characters: stated in the prompt before it answers (turnPrompt), and an answer over one is
- * asked once to shorten (subagentTurn); one still over is kept whole, never cut. "text" is what the next zones read;
- * "note" is a decision or send-back note. Not in the turn's schema (src/contracts/subagent-turn.ts): the CLI would
- * refuse an answer a few characters over one whole. */
 export const TURN_LIMITS = { answer: TEXT_LIMITS.subagentAnswer, text: TEXT_LIMITS.stageOutput, note: LIMITS.note, question: TEXT_LIMITS.subagentQuestion, reason: TEXT_LIMITS.subagentReason, remember: TEXT_LIMITS.subagentRemember };
-/** The fields of an answer over their limits. */
 export function turnOverruns(answer) {
     return overruns({ answer: answer.answer, text: answer.text, note: answer.note, question: answer.question, reason: answer.reason, remember: answer.remember }, TURN_LIMITS);
 }
@@ -180,14 +153,7 @@ export function turnPrompt(context) {
         ...(context.shorten === undefined ? [] : ["", "YOUR LAST ANSWER, WHICH IS OVER A LIMIT", context.shorten.answer, "", context.shorten.ask]),
     ].join("\n");
 }
-/** How many options an ask offers, and the longest tool name and input a tool call may give. */
 const ASK_OPTIONS = 4, TOOL_NAME_CHARS = 140, TOOL_INPUT_CHARS = 8000;
-/**
- * A turn's answer, read through its contract (src/contracts/subagent-turn.ts) and then checked against what this zone
- * allows, each refusal naming its path (`action: "route" isn't one this zone allows`). Text is trimmed and kept whole
- * (a field over its limit is asked to shorten, turnOverruns); blank options are dropped, and an ask offers at most 4,
- * each cut to an answer's length, and a tool name is cut to 140, as they always were.
- */
 export function readTurn(value, context) {
     const read = readTurnAnswer(value);
     if (!read.ok)
@@ -201,7 +167,6 @@ export function readTurn(value, context) {
     const refuse = (path, what) => ({ ok: false, issues: [{ path, kind: "bad-value", line: `${path}: ${what}` }] });
     if (!allowed.includes(answer.action))
         return refuse("action", `"${answer.action}" isn't one this zone allows (${allowed.map(one => `"${one}"`).join(", ")})`);
-    // A tool call is checked against the subagent's rules where it's carried out; here only that it names one and fits.
     if (answer.action === "use_tool" && answer.tool === "")
         return refuse("tool", "required for use_tool");
     if (answer.action === "use_tool" && answer.input.length > TOOL_INPUT_CHARS)
@@ -215,10 +180,8 @@ export function readTurn(value, context) {
     return { ok: true, value: answer };
 }
 export const TURN_TIMEOUT_MS = 180_000;
-/** The production runner: Claude through this computer's sign-in, answering in the turn schema (TURN_MODEL_SCHEMA), with no tools, no MCP servers and no repository. */
 export function claudeTurnRunner(runner = run) {
     return request => inScratchDir("standing-orders-subagent-", async (dir) => {
-        // An eval world makes no provider call it can't cap and record (eval-gate.ts).
         if (inEvalWorld())
             return { ok: false, said: "Subagents don't run in an eval world." };
         const started = Date.now();
@@ -242,7 +205,6 @@ export function claudeTurnRunner(runner = run) {
         return inner.ok ? { ok: true, value: inner.value, ms: Date.now() - started, ...cost } : { ok: false, said: "Claude's answer wasn't a decision.", ...cost };
     });
 }
-/** What the CLI says a turn cost, and its tokens (cache reads and writes count as input). */
 function costOf(body) {
     const usage = (body["usage"] ?? {});
     const count = (key) => typeof usage[key] === "number" && Number.isFinite(usage[key]) ? usage[key] : 0;
@@ -250,7 +212,5 @@ function costOf(body) {
     const tokensIn = count("input_tokens") + count("cache_creation_input_tokens") + count("cache_read_input_tokens"), tokensOut = count("output_tokens");
     return { ...(cost === undefined ? {} : { costUsd: cost }), ...(tokensIn > 0 ? { tokensIn } : {}), ...(tokensOut > 0 ? { tokensOut } : {}) };
 }
-/** How a subagent is named to people: "Maya · Support". */
 export const subagentLabel = (soul) => `${soul.name} · ${soul.role}`;
-/** How its acts read in a card's history: "Maya (AI)". */
 export const subagentActor = (soul) => `${soul.name} (AI)`;

package/dist/subscription-chat.js

@@ -1,15 +1,3 @@
-/**
- * Subscription-backed transport for the lead.
- *
- * The direct API transport owns dollar reservations and native function
- * calls. A cached Codex or Claude login has neither an API key nor a
- * truthful dollar meter, so this adapter runs the local harness in a clean
- * temporary directory and asks for the same tool-call envelope as strict
- * structured JSON. The harness receives no repository path, no project
- * instructions, no MCP servers, and no executable tool surface. Tool calls
- * are still interpreted and executed by lead.ts, where every act remains a
- * proposal that needs a human confirmation card.
- */
 import { takeEvalDispatch } from "./eval-gate.js";
 import { Buffer } from "node:buffer";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
@@ -30,8 +18,6 @@ function outputSchema(tools) {
         type: "object",
         properties: {
             text: { type: "string", maxLength: LEAD_STEP_TEXT_CAP_BYTES },
-            // With no tools offered there is nothing to name: an empty enum is not
-            // a valid schema, so the calls array is simply required to be empty.
             calls: tools.length === 0 ? { type: "array", maxItems: 0 } : {
                 type: "array",
                 maxItems: LEAD_MAX_CALLS_PER_STEP,
@@ -51,14 +37,11 @@ function outputSchema(tools) {
         additionalProperties: false,
     };
 }
-/** The model-visible request. Tool results are already redacted by leadView. */
 export function composeSubscriptionLeadPrompt(request) {
     return [
         request.system,
         "SUBSCRIPTION HARNESS PROTOCOL:",
         "Do not use any harness tools or inspect the computer. The only current state is DATA and TOOL RESULTS below.",
-        // The model tried host tools as its own tool calls, which the harness refuses, and sometimes then told the operator the
-        // project search "wasn't available" (gate run, 2026-09-30). Host tools are requested only through calls.
         "Host tools are not tools you can call yourself here: calling one directly always fails. Request one only by listing it in calls of the JSON object you return. Every AVAILABLE HOST TOOL below is available this way; never say one is unavailable. For what a project's files or code say, request get_project_context.",
         "Return the required JSON object. To request a host tool, append {id, name, argumentsJson} to calls; argumentsJson is the JSON serialization of that tool's argument object.",
         "The host validates and runs those calls, then gives you another step. When finished, return a non-empty text and an empty calls array.",
@@ -71,7 +54,6 @@ function exactKeys(value, keys) {
     const actual = Object.keys(value).sort();
     return actual.length === keys.length && [...keys].sort().every((key, index) => actual[index] === key);
 }
-/** Strictly turn the harness's structured output into the provider-neutral answer. */
 export function parseSubscriptionLeadAnswer(text, usage = {}) {
     const parsed = strictJsonParse(Buffer.from(text, "utf8"), RESPONSE_CAP_BYTES, 8);
     if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null || Array.isArray(parsed.value)) {
@@ -112,8 +94,6 @@ export function parseSubscriptionLeadAnswer(text, usage = {}) {
     const tokensOut = typeof usage.tokensOut === "number" && tokenCount(usage.tokensOut) ? usage.tokensOut : 0;
     return { ok: true, answer: { text: body["text"], calls, tokensIn, tokensOut, reportedCostMicrousd: null, ...reportFields(usage.report ?? null) } };
 }
-/** The harness's own report on the answer (v140): every field null when it gave none, cache counts only when it
- * reported them. Never `reportedCostMicrousd`: a subscription's reported cost is usage, not API dollars. */
 function reportFields(report) {
     return {
         modelReported: report?.modelReported ?? null,
@@ -123,8 +103,6 @@ function reportFields(report) {
         ...(report?.cacheWriteTokens == null ? {} : { cacheWriteTokens: report.cacheWriteTokens }),
     };
 }
-/** Input tokens are everything the model read, cache included, when the harness reported every part (usageOf);
- * otherwise its plain input count as before. */
 function tokensInOf(report, plain) {
     return report.tokensIn !== null && tokenCount(report.tokensIn) ? report.tokensIn : plain;
 }
@@ -170,12 +148,8 @@ function codexOutput(stdout) {
             report = codexUsageReport(usage);
         }
     }
-    // A partial answer is not authority to run host tools. Process exit zero
-    // alone is insufficient; the harness must finish this one turn successfully.
     return { text: !invalid && completed === 1 ? text : null, tokensIn: report === null ? tokensIn : tokensInOf(report, tokensIn), tokensOut, report };
 }
-/** The closing `result` (the buffered run's whole output, or the streamed run's last primary result line), with the
- * session's init model when the stream carried one. */
 function claudeOutput(stdout, init) {
     const parsed = strictJsonParse(Buffer.from(stdout, "utf8"), RESPONSE_CAP_BYTES, 12);
     if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null || Array.isArray(parsed.value))
@@ -193,8 +167,6 @@ function claudeOutput(stdout, init) {
         return { text: JSON.stringify(structured), tokensIn, tokensOut, report };
     return { text: typeof body["result"] === "string" ? body["result"] : null, tokensIn, tokensOut, report };
 }
-/** The streamed run's closing `result` event: the same body the buffered
- * `--output-format json` run prints. */
 function lastResultLine(stdout) {
     const lines = stdout.split("\n");
     for (let index = lines.length - 1; index >= 0; index--) {
@@ -203,18 +175,14 @@ function lastResultLine(stdout) {
             continue;
         try {
             const event = JSON.parse(line);
-            // The main query's result, never a subagent's or a background task's (stream-scope.ts).
             if (typeof event === "object" && event !== null && primaryResultEvent(event))
                 return line;
         }
-        catch { /* not an event line */ }
+        catch { }
     }
     return "";
 }
-/** Production runner; injectable so tests never consume a subscription turn. */
 export async function performSubscriptionLeadRequest(request, runner = run) {
-    // An eval world (eval-gate.ts): each request takes one of the attempt's dispatch slots; past the limit nothing is
-    // sent ("status-": nothing billed).
     const evalSlot = takeEvalDispatch(`chat:${request.provider}`);
     if (evalSlot.active && !evalSlot.ok)
         return { ok: false, problem: "status-eval-dispatch-limit" };
@@ -243,8 +211,6 @@ export async function performSubscriptionLeadRequest(request, runner = run) {
         else {
             command = "claude";
             args = [
-                // Streaming (someone is watching): the same answer, delivered as
-                // events whose final `result` line is the whole structured reply.
                 "-p", ...(streaming ? ["--output-format", "stream-json", "--verbose", "--include-partial-messages"] : ["--output-format", "json"]), "--json-schema", JSON.stringify(schema),
                 ...CLAUDE_NO_TOOLS_ARGS, ...claudeModelArgs(request.model),
             ];
@@ -254,22 +220,16 @@ export async function performSubscriptionLeadRequest(request, runner = run) {
             stdin: prompt,
             timeoutMs: request.timeoutMs,
             ...(request.signal === undefined ? {} : { signal: request.signal }),
-            // Events repeat the answer (deltas, the message, the result line).
             maxBuffer: streaming ? RESPONSE_CAP_BYTES * 16 : RESPONSE_CAP_BYTES,
             omitEnv: ALL_CREDENTIAL_ENV,
             processGroup: true,
             ...(streaming ? { onStdout: claudeStreamReader(request.onText) } : {}),
         });
-        // Whether the harness wrote anything at all before its deadline (v158, responsive-chat.md §7.5): a silent one never
-        // started answering; one with output was answering slowly. Recorded, never shown.
         if (result.timedOut)
             return { ok: false, problem: "timeout", quiet: result.stdout.trim() === "" };
         if (result.notFound)
             return { ok: false, problem: "not-found" };
-        // v105: a streamed Claude turn says its plan's usage windows, and (once it answered) how this computer's Claude bills
-        // with no key from us: the chat ran with every key left out. v140: its session's init names the exact model.
         let init = { model: null, conflict: false };
-        // v141: how this request was billed, as its own events said (streamed Claude only); null when they didn't say.
         let billingReported = null;
         if (command === "claude" && streaming) {
             const seen = { keySource: null, model: null, planWindows: false };
@@ -293,7 +253,6 @@ export async function performSubscriptionLeadRequest(request, runner = run) {
                 else if (event["type"] === "system" && event["subtype"] === "init" && topLevelEvent(event)) {
                     seen.keySource = typeof event["apiKeySource"] === "string" ? event["apiKeySource"] : null;
                     seen.model = typeof event["model"] === "string" ? event["model"] : null;
-                    // Every init the session sent names its model; inits that disagree leave it unknown, never chosen.
                     const named = reportedModelOf(event["model"]);
                     if (named !== null)
                         initModels.add(named);

package/dist/summary.js

@@ -1,13 +1,3 @@
-/**
- * A window of runs, tallied — one arithmetic, shared by the CLI brief and
- * the web console so the two can never disagree about what a stretch of
- * unattended work cost.
- *
- * Economics are measured, never asserted: every provider spawn stamps its
- * run before spending, so `invoked` is the complete population; `measured`
- * is the subset whose envelopes actually reported cost, and the gap between
- * them is named by callers instead of summed as zero.
- */
 export function tally(runs) {
     const invoked = runs.filter(one => one.providerStartedAt !== null);
     const measured = invoked.filter(one => one.costUsd !== null);
@@ -24,15 +14,7 @@ export function tally(runs) {
             .reduce((sum, one) => sum + (one.tokensOut ?? 0) + (one.tokensIn ?? 0), 0),
     };
 }
-/**
- * Provider harnesses do not all mean the same thing when they report a
- * dollar figure. Claude Code includes `total_cost_usd` in its result even
- * when it authenticated with a paid membership. In that case the number is
- * useful as an API-price equivalent for comparing work, but it is not API
- * key spend and must never be presented as a separate charge.
- */
 export function runCostWords(run, live = false) {
-    // An ACP agent signs in its own way and reports no price Toolroll trusts.
     if (run.authMode === "agent-login")
         return live ? "the agent's own sign-in · in progress" : "the agent's own sign-in · cost not measured";
     if (run.authMode === "subscription") {
@@ -51,7 +33,6 @@ export function runCostWords(run, live = false) {
             ? "usage in progress"
             : "unmeasured";
 }
-/** The spend line, one wording everywhere. */
 export function spendLine(summary) {
     if (summary.invoked.length === 0)
         return "nothing — no provider was invoked";

package/dist/surface.js

@@ -5,25 +5,7 @@ import { FLAKY_DESCRIPTORS } from "./flaky-cli.js";
 import { MODELS_DESCRIPTORS } from "./models-cli.js";
 import { MAP_DESCRIPTORS } from "./code-map-cli.js";
 import { FLOWS_DESCRIPTORS } from "./flows-cli.js";
-/**
- * The declared command guide (arc 5): the agent-facing surface as data,
- * dumped by `contract --commands`. This is DOCUMENTATION with a stable
- * shape, not authority — legacy verbs do not execute from it,
- * and the runtime envelope remains the truth. Its honest limits ride the
- * envelope itself as SURFACE_NOTES, because a source comment is invisible
- * to consumers (arc-5 review, finding 1).
- *
- * What the tests DO hold to the code: every root here is a routed verb
- * and every routed verb appears here; every declared flag lives in the
- * parser's global vocabulary with the declared arity; the subcommand
- * inventories for task/publish/config/approver match the
- * exported action lists their dispatchers consult; keyed mutations
- * declare --key; notableReasons come from DOCUMENTED_REASONS. What they
- * CANNOT prove — that a given flag is read by a given handler — is why
- * SURFACE_NOTES.flags says "intended".
- */
 import { commandEntries } from './contracts/cli.js';
-/** The guide's limits, stated machine-readably in every dump. */
 export const SURFACE_NOTES = {
     authority: "documentation is not permission; legacy entries remain advisory",
     flags: "flags are intended per command and may use a global parser vocabulary",
@@ -50,7 +32,6 @@ const operatorRead = (invocation, synopsis) => ({
     mutation: "none",
 });
 const GUIDE_ROWS = [
-    // ---- reports (reads) ----
     {
         invocation: "",
         envelopeCommand: "scan",
@@ -67,10 +48,7 @@ const GUIDE_ROWS = [
     { invocation: "graph", synopsis: "report which work graph is already here", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag] },
     { invocation: "repos", synopsis: "list connected repositories", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag] },
     operator("proposals", "what coordinators proposed over the MCP gateway — list, confirm <id> [--yes], dismiss <id>; confirming runs the plane's own door under your password"),
-    // D5: the central team service (connect, the central lead verbs, conversation …) and native coding sessions are
-    // deprecated: they still run this release, with a warning, but are no longer declared here.
     operator("chat", "talk to your lead: one conversation across every project; --say sends one message; --follow enables crew updates and --no-follow pauses them; proposals keep their approval requirements"),
-    // Unkeyed: --remote with a different URL replaces the project's trusted remote (recorded in the action ledger).
     { invocation: "repos add", synopsis: "add a project: a Git repository, in the console at once; the lead adds with its token; --remote records or replaces its trusted remote", audience: "agent", agentMayInvoke: true, mutation: "unkeyed",
         positionals: [{ name: "path", required: false, meaning: "the repository (default: the one you are in)" }],
         flags: [jsonFlag, { name: "token", takesValue: true, meaning: "the lead token (or TOOLROLL_LEAD_TOKEN)" },
@@ -122,13 +100,10 @@ const GUIDE_ROWS = [
     ...MEMORY_DESCRIPTORS.map(spec => ({ invocation: `memory ${spec.action}`, synopsis: spec.synopsis, audience: "audience" in spec ? spec.audience : "agent", agentMayInvoke: !("audience" in spec), mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "query", required: true, meaning: "search text, a decision id, or the decision sentence" }] } : {}) })),
     { invocation: CARD_DESCRIPTOR.invocation, synopsis: CARD_DESCRIPTOR.synopsis, audience: "agent", agentMayInvoke: true, mutation: "none", flags: CARD_DESCRIPTOR.flags, positionals: [{ name: "source", required: true, meaning: "which data to show" }] },
     ...FLAKY_DESCRIPTORS.map(spec => ({ invocation: `flaky ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "identity", required: true, meaning: "a row's key from flaky list" }] } : {}) })),
-    // Flow writes carry an approver's credential: an agent runs them only as the person asked, after showing the preview.
-    // Letting a flow run on its own raises authority: the owner's own password ceremony, never an agent's act.
     ...FLOWS_DESCRIPTORS.map(spec => ({ invocation: `flows ${spec.action}`, synopsis: spec.synopsis, audience: "audience" in spec ? spec.audience : "agent", agentMayInvoke: !("audience" in spec), mutation: spec.mutation, flags: spec.flags,
         ...("positionals" in spec ? { positionals: spec.positionals.map(name => ({ name, required: true, meaning: name === "flow" ? "a flow id from flows list" : name === "card" ? "a card id from flows show" : name === "on|off" ? "on signs the grant, off revokes it" : "a trigger id from flows show, or for trigger add its settings as JSON, a JSON file, or -" })) } : {}) })),
     ...MAP_DESCRIPTORS.map(spec => ({ invocation: spec.action === "" ? "map" : `map ${spec.action}`, synopsis: spec.synopsis, audience: "audience" in spec ? spec.audience : "agent", agentMayInvoke: !("audience" in spec), mutation: spec.mutation, flags: spec.flags, ...(spec.positional === null ? {} : { positionals: [{ name: "target", required: true, meaning: spec.positional }] }) })),
     ...MODELS_DESCRIPTORS.map(spec => ({ invocation: `models ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "target", required: true, meaning: "positional" in spec ? spec.positional : "the CLI to update, or on/off" }] } : {}) })),
-    // ---- the queue (agent surface) ----
     { invocation: "status", synopsis: "running work, queued reasons, results to review, the latest release check and plan windows", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
     { invocation: 'health', synopsis: 'recent server latency, event-loop delay, SQLite writes and live streams from the saved connection; instance operators only', audience: 'agent', agentMayInvoke: true, mutation: 'none', flags: [jsonFlag, { name: 'profile', takesValue: true, meaning: 'saved server connection' }] },
     { invocation: "integrations", synopsis: "every integration as Connected, Not set up or Broken, with its last success and error, what uses it and what to do; --saved skips new checks; never a secret", audience: "agent", agentMayInvoke: true, mutation: "none",
@@ -223,7 +198,6 @@ const GUIDE_ROWS = [
             { name: 'token-file', takesValue: true, meaning: 'scoped coordinator credential file; defaults to selected project reference' },
             ...(action === 'complete' ? [{ name: 'digest', takesValue: true, meaning: 'exact receipt from assignment show; required for JSON or scoped agents' },
                 { name: 'pull-request', takesValue: false, meaning: "also open the result's pull request from that commit, as the console's Complete does; an approver's sign-in (--as/--token), never a scoped credential; refuses with pull-requests-off and the setup command" },
-                // Local-owner slice 1: the terminal UI's Accept, for the laptop's local owner only (no password).
                 { name: 'run', takesValue: true, meaning: "the terminal's local owner: the exact build of the result read; required there with --digest" },
                 { name: 'checked', takesValue: false, meaning: "the terminal's local owner: you checked the result yourself; required when it owes your own check" },
                 { name: 'reason', takesValue: true, meaning: "the terminal's local owner: why you accept a result whose requirement isn't shown; required for an exception" }]
@@ -302,7 +276,6 @@ const GUIDE_ROWS = [
         flags: [jsonFlag, dbFlag, keyFlag,
             { name: "provider", takesValue: true, meaning: "pin which provider plans THIS task (plan phase only)" },
             { name: "model", takesValue: true, meaning: "the pinned plan model, riding --provider" },
-            // Local-owner slice 2: the terminal UI's plan request, for the laptop's local owner only (no password, no pins).
             { name: "digest", takesValue: true, meaning: "the terminal's local owner: the exact planning source read; required there, and --provider/--model are refused" }],
         notableReasons: ["unknown-task"] },
     { invocation: "task hold", synopsis: "park a task with a reason", audience: "agent", agentMayInvoke: true, mutation: "keyed",
@@ -365,7 +338,6 @@ const GUIDE_ROWS = [
         notableReasons: ["usage", "not-an-approver", "empty"] },
     operator("run settle", "have Toolroll check again whether a finished run stopped: it looks at this computer's processes itself, stops only leftovers proven the run's, and settles the run when none is left (nobody vouches; --why is ignored)"),
     operator("task resume", "resume the exact stopped attempt (--run <id>): refuses until it is quiescent, lifts only that stop's hold, approves nothing — the next pass re-proves the scope and inherits the draft with fresh proof"),
-    // ---- leases (runner surface) ----
     { invocation: "claim", synopsis: "take one ready, approved task; answers with a lease", audience: "agent", agentMayInvoke: true, mutation: "keyed",
         positionals: [{ name: "id", required: true, meaning: "the task" }],
         flags: [jsonFlag, dbFlag, keyFlag,
@@ -391,7 +363,6 @@ const GUIDE_ROWS = [
         positionals: [{ name: "id", required: true, meaning: "the task" }],
         flags: [jsonFlag, dbFlag, repoFlag], notableReasons: ["not-leased", "unapproved"] },
     { invocation: "reconcile", synopsis: "recover what the last stretch left behind — safe to repeat", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent", flags: [jsonFlag, dbFlag, repoFlag] },
-    // ---- reads over shared machinery ----
     { invocation: "runner list", synopsis: "registered workers", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
     { invocation: "coordinator list", synopsis: "MCP filing credentials and their limits", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
     { invocation: "approver list", synopsis: "who can say yes (names only)", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
@@ -412,7 +383,6 @@ const GUIDE_ROWS = [
         positionals: [{ name: "name", required: true, meaning: "the template" }], flags: [jsonFlag, dbFlag] },
     { invocation: "webhook status", synopsis: "connected messaging services", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
     { invocation: "publish status", synopsis: "publication and merge-grant state", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
-    // ---- operator ceremonies and infrastructure (listed, detail-free) ----
     operator("approver add", "mint the credential that lets a person say yes"),
     operator("runner register", "register a worker bound to its repositories; its token is shown once"),
     operator("runner retire", "retire a worker"),
@@ -488,61 +458,35 @@ const GUIDE_ROWS = [
     operator("password set", "set this computer's first password, typed twice at your own terminal (never a flag, file or environment variable); every session signs in again and local mode stays on"),
     { ...operatorRead("doctor", "check that Toolroll's service holds no key, token or password a build could read; names what it finds and the steps to fix it, never a value, and changes nothing"), flags: [jsonFlag] },
 ];
-/**
- * Whether each row may run on a central server for a person signed in with their own API token (`runOperateAs` in
- * operate.ts), stated for every row by name. "no" is this machine's own infrastructure, credentials, files and the
- * commands that only make sense beside a checkout (or that the local CLI answers itself); "step-up" is approvals,
- * people and policy, which stay in the console and chat; "yes" runs as the person, within their token's scope and
- * project access. A row missing here fails the contract test, and runs nowhere remotely meanwhile.
- */
 const REMOTE_NO = [
-    // A fast start is a person at this computer (fast-start.ts).
     "task new", "task keep",
-    // Answered by the local CLI, or a client of a central server itself.
     "", "pulls", "graph", "repos", "repos add", "repos remove", "repos add-from-github", "contract", "skills list", "skills get", "skills install",
     "link", "unlink", "update", "release", "demo", "chat",
-    // This machine's checkout, saved profile, credentials and catch-up.
     "project show", "project use", "brief", "lead token", "lead say", "health",
     "assignment show", "assignment updates", "assignment claim", "assignment check", "assignment brief", "assignment inbox", "assignment ack",
-    // Workers, the loop and the services that run here.
     "claim", "heartbeat", "worker release", "reap", "tick", "build", "reconcile",
     "runner register", "runner retire", "runner bind", "runner capacity", "coordinator mint", "coordinator revoke", "mcp", "outbox deliver", "peek",
     "serve", "serve check-public", "watch", "up", "onboard", "daemon", "background on", "background off", "background show", "stop", "open", "welcome", "password set", "doctor", "bridge", "setup show", "setup clear",
-    // Provider keys and model tools on this machine.
     "providers", "keys status", "keys set", "keys clear", "keys verify", "keys auth", "models check", "models update", "models watch",
-    // Result records read with this machine's sign-in: project access, never a token's narrower scope.
     "models results",
-    // Earned rules (results routing): the project's own results, and its rules' doors, with this machine's sign-in; a
-    // remote token never changes which models run (the rule door refuses it in the write too).
     "models suggestions", "models accept", "models dismiss", "models turn-off", "models keep", "models try", "models stop",
-    // The code map's switch, holdout and report: this machine's sign-in, never a token's (code-map-acts.ts refuses one in
-    // the write too).
     "map on", "map off", "map holdout end", "map report",
-    // Publication and release.
     "publish", "publish status", "publish merge", "publish refire", "publish unblock", "publish rearm", "publish grant", "publish revoke",
-    // A repository's authority grants on this machine.
     "enroll", "revoke",
-    // Flow steps that fetch addresses or run checks and scripts here.
     "flows import", "flows trigger check", "flows script save",
-    // Lets a flow script on this machine start Chromium in its sandbox: a person here, with their own password.
     "flows browser",
-    // Reads this machine owner's own Claude and Codex session files (~/.claude, ~/.codex).
     "memory propose",
 ];
 const REMOTE_FOLLOW_THROUGH = [
-    // On the server's machine or in the console: each writes through a verified person, and they read saved model text.
     "task handover", "task before-after", "task failing-first", "finding list", "finding show", "finding send", "finding resend", "finding close",
     "captures list", "captures show", "captures export", "captures mark",
 ];
 const REMOTE_STEP_UP = [
     "proposals", "decide", "task regate", "task approve", "task accept", "task merge", "run settle",
-    // Putting tasks away and restoring them: a person's act, in the console or on the server's machine.
     "task archive", "task restore", "task tidy", "knowledge apply",
-    // Changing project memory: a person's own password, never a token (the lead only proposes it in chat).
     "memory decide", "memory retire", "memory apply", "memory tidy", "memory restore", "memory unmerge",
     "flows card approve", "flows card send-back", "flows script approve", "flows unattended",
     "approver list", "approver add", "people list", "people invite", "people projects", "people revoke",
-    // A person's own API tokens: a password step-up on the server's machine, or the console. Never with a token.
     "tokens create", "tokens list", "tokens revoke", "tokens rotate",
     "mode show", "mode set", "mode revoke", "chat-approval on", "review on", "review off", "config set", "config clear",
     "verify set", "verify clear", "verify level", "project checks", "project check-access", "project concurrency", "intake grant", "intake clear", "webhook primary",
@@ -563,28 +507,18 @@ const REMOTE_YES = [
     "flows trigger remove", "flows card add", "flows archive",
     "models status", "models list",
 ];
-/** Every row's remote policy, by invocation. Exported for the contract test, which holds it to the guide exactly. */
 export const REMOTE_POLICY = new Map([
     ...REMOTE_NO.map(invocation => [invocation, "no"]),
     ...REMOTE_FOLLOW_THROUGH.map(invocation => [invocation, "no"]),
     ...REMOTE_STEP_UP.map(invocation => [invocation, "step-up"]),
     ...REMOTE_YES.map(invocation => [invocation, "yes"]),
 ]);
-/** How many times each invocation was classified — the contract test refuses a row stated twice. */
 export const REMOTE_POLICY_COUNT = REMOTE_NO.length + REMOTE_FOLLOW_THROUGH.length + REMOTE_STEP_UP.length + REMOTE_YES.length;
-/**
- * Easy-start C3: the commands a laptop's local owner may run through the terminal UI (local-owner.ts runAsLocalOwner),
- * each with the act it is; every other row (and every command with no row) is refused to the local owner before any
- * command code runs. Credential, people, policy and infrastructure commands are never here.
- */
 const LOCAL_ALLOW = {
-    // Reads.
     pulls: "read", graph: "read", repos: "read", map: "read", "map area": "read", "map file": "read", "map search": "read", status: "read", ready: "read", gaps: "read", contract: "read", "skills list": "read", "skills get": "read",
     "flaky list": "read", "flaky show": "read", card: "read", "memory review": "read", "memory status": "read", "memory decisions": "read", "memory show": "read",
-    // Learning loops (D3): a lesson note or a clean-up, decided by a person at the laptop (the writers check the act).
     "memory apply": "memory-review", "memory tidy": "memory-review", "memory restore": "memory-review", "memory unmerge": "memory-review",
     "task list": "read", "task show": "read", "task state": "read", "task wait": "read", "check-progress": "read", "review show": "read", welcome: "read",
-    // Acts (plan C1's list).
     "task add": "file-task",
     "task new": "build-now",
     chat: "lead-send",
@@ -598,15 +532,12 @@ const LOCAL_ALLOW = {
     "task continue": "resume-run",
     "task unhold": "resume-run",
     "task complete": "complete-task",
-    // Local-owner slice 2: its own road (operate.ts localPlanCommand); the writer checks this exact act.
     "task plan": "request-plan",
-    // Local-owner slice 3: its own road (operate.ts localRetryCommand); the writer checks this exact act.
     "task requeue": "retry-build",
     "task revise": "request-revision",
     "task archive": "archive-task",
     "task restore": "archive-task",
     "repos add": "add-project",
-    // Results routing: lowering only (route-store.ts proveRuleDoor checks the act is exactly this one).
     "models suggestions": "read",
     "models turn-off": "routing-turn-off",
     "models dismiss": "dismiss-suggestion",
@@ -614,15 +545,9 @@ const LOCAL_ALLOW = {
     "map on": "code-map-switch",
     "map off": "code-map-switch",
 };
-/** Every guide row's local-owner mark, by invocation: `allow` with its act, else `deny`. Exported for the inventory test. */
 export const LOCAL_POLICY = new Map(GUIDE_ROWS.map(row => [row.invocation,
     Object.prototype.hasOwnProperty.call(LOCAL_ALLOW, row.invocation) ? { local: "allow", act: LOCAL_ALLOW[row.invocation] } : { local: "deny" }]));
-/** The invocations LOCAL_ALLOW names, for the inventory test (one naming no row is stale). */
 export const LOCAL_ALLOWED_INVOCATIONS = Object.keys(LOCAL_ALLOW);
-/** Every declared command, in guide order, paired with the schema of its `--json` answer (src/contracts/cli.ts).
- * An unclassified row is "no": nothing runs remotely by omission. */
 export const COMMAND_ENTRIES = commandEntries(GUIDE_ROWS.map(row => ({ ...row, remote: REMOTE_POLICY.get(row.invocation) ?? "no" })));
-/** The invocations the guide states, for the contract test (a classification naming none of them is stale). */
 export const GUIDE_INVOCATIONS = GUIDE_ROWS.map(row => row.invocation);
-/** The guide `contract --commands` dumps: each declared command's row, projected from COMMAND_ENTRIES. */
 export const COMMAND_GUIDE = COMMAND_ENTRIES.map(entry => entry.guide);

package/dist/sweep-gate.js

@@ -1,6 +1,5 @@
 export const SWEEP_FALLBACK_MS = 60_000;
 const cycles = new WeakMap();
-/** Runs `sweep` unless the cycle under `cursorKey` would see what its last start saw. Returns whether it ran. */
 export function sweepIfMoved(store, cursorKey, now, sweep) {
     const seq = store.wakeSeq();
     const startsCycle = store.serviceCursor(cursorKey) === 0;
@@ -11,7 +10,6 @@ export function sweepIfMoved(store, cursorKey, now, sweep) {
     if (startsCycle && last?.seq === seq && elapsed >= 0 && elapsed < SWEEP_FALLBACK_MS)
         return false;
     sweep();
-    // Recorded only once the pass returns: a pass that threw is retried next time.
     if (startsCycle)
         seen.set(cursorKey, { seq, at: now.getTime() });
     return true;

package/dist/sweep-quarantine.js

@@ -1,7 +1,3 @@
-/** Atomic rename before deletion. Trash is never a reusable dependency copy or staged runtime.
- * Its journal survives partial deletion so the next sweep can recheck the original identity and retry.
- * No database write lock spans filesystem work. A live owner keeps its trash; recovery claims a dead
- * owner's folder by renaming it to a fresh, never-reused name, so two recoverers cannot both win. */
 import { randomBytes } from "node:crypto";
 import { existsSync, linkSync, lstatSync, readFileSync, readdirSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
@@ -52,7 +48,7 @@ function write(path, journal, exclusive = false) {
         try {
             unlinkSync(temp);
         }
-        catch { /* renamed */ }
+        catch { }
     }
 }
 export function quarantineEntries(root) {
@@ -73,18 +69,16 @@ export function quarantineEntries(root) {
             return [];
         }
         const journal = read(path);
-        // A crash after unlinking the journal can leave only an empty folder. No resource data remains in it.
         if (journal === null) {
             try {
                 if (readdirSync(path).length === 0)
                     rmdirSync(path);
             }
-            catch { /* next pass */ }
+            catch { }
         }
         return journal === null ? [] : [{ path, original: join(root, journal.name), journal }];
     });
 }
-/** A small marker closes discovery before the atomic rename. It is never published half-written. */
 export function quarantine(original, data) {
     if (!lstatSync(original).isDirectory())
         return null;
@@ -103,7 +97,6 @@ export function quarantine(original, data) {
     renameSync(original, path);
     return { path, original, journal };
 }
-/** Returns null if another sweep owns it (or won recovery). */
 export function claimQuarantine(entry) {
     const seen = read(entry.path);
     if (seen === null || alive(seen))
@@ -111,7 +104,6 @@ export function claimQuarantine(entry) {
     const journal = { ...seen, ...owner() };
     const path = freshPath(dirname(entry.path));
     try {
-        // Mark live before moving. Contenders already reading the old name race the rename; just one wins.
         write(entry.path, journal);
         renameSync(entry.path, path);
         write(path, journal);
@@ -125,7 +117,6 @@ export function releaseQuarantine(entry) {
     if (existsSync(entry.path))
         write(entry.path, { ...entry.journal, pid: 0 });
 }
-/** A partially deleted tree must never become discoverable again. */
 export function restoreQuarantine(entry) {
     if (entry.journal.deleting || existsSync(entry.original))
         return false;
@@ -133,7 +124,6 @@ export function restoreQuarantine(entry) {
     unlinkSync(join(entry.original, QUARANTINE_NOTE));
     return true;
 }
-/** Keep the journal until all potentially large removals succeeded. Recovery never guesses at a half-deleted tree. */
 export async function deleteQuarantine(entry, remove) {
     entry.journal = { ...entry.journal, deleting: true };
     write(entry.path, entry.journal);
@@ -143,7 +133,6 @@ export async function deleteQuarantine(entry, remove) {
     unlinkSync(join(entry.path, QUARANTINE_NOTE));
     rmdirSync(entry.path);
 }
-/** Staged pruning is also called synchronously by update/deploy. */
 export function deleteQuarantineSync(entry, remove) {
     entry.journal = { ...entry.journal, deleting: true };
     write(entry.path, entry.journal);