toolroll 0.9.104 → 0.9.105

package/dist/reply-shape.js

@@ -1,32 +1,15 @@
-/**
- * The lead's voice, enforced: every chat surface (console, terminal, Telegram, Slack, Discord, Teams) runs a reply
- * through here before it is sent. The contract asks for plain text; this makes it so, without changing what the reply
- * says. Shaping is channel-neutral and idempotent — it yields a small canonical form (`**anchor**`, `[label](url)`,
- * `code`) — and each channel renders that form in its own format.
- *
- * - Markdown headers become plain lines.
- * - Bold stays on at most three short anchors; the rest is plain.
- * - Bare URLs become labelled links, named from their target: "the task", "the result", "Settings → Lead", else the host.
- * - Internal ids (run #12, digests, r1-style project ids) are removed unless the owner asked for them. When a reply names
- *   several of one kind (two runs, two projects), they stay: two items must never read the same.
- * - Runs of blank lines collapse to one.
- * Code (inline or fenced) is left exactly as written.
- */
 import { html, joinHtml } from "./html.js";
 export const BOLD_ANCHORS = 3;
-/** A bold anchor is a few words, not a sentence. */
 export const BOLD_ANCHOR_CHARS = 40;
 const URL_CHARS = String.raw `https?:\/\/[^\s<>()\[\]"'\`]+`;
 const LINK = new RegExp(String.raw `\[([^\]\n]{1,120})\]\((${URL_CHARS})\)`, "g");
 const PROTECTED = new RegExp(String.raw `\x60\x60\x60[\s\S]*?(?:\x60\x60\x60|$)|\x60[^\x60\n]+\x60|\[[^\]\n]{1,120}\]\(${URL_CHARS}\)|<${URL_CHARS}>|${URL_CHARS}`, "g");
 const HOLD = (index) => `\u0000${index}\u0000`;
-/** Did the owner ask for ids (an id, a digest, a hash, a run number or a project's r-number)? */
 export function askedForIds(asked) {
     if (asked === undefined)
         return false;
     return /\b(?:ids?|identifiers?|digests?|sha(?:256)?|hash(?:es)?|commit|turn\s*(?:#|number)|run\s*(?:#|numbers?|ids?)|r\d{1,3})\b|#\d+/i.test(asked);
 }
-/** Is this link on the app's own origin? Without a known origin, nothing is. */
 function ownLink(url, appOrigin) {
     if (appOrigin === null || appOrigin === undefined)
         return false;
@@ -49,7 +32,6 @@ function ownLink(url, appOrigin) {
         }
     });
 }
-/** What a link is called, from where it goes: the app's own task, result and settings pages by name (only on `appOrigin`); anything else by host. */
 export function linkLabel(url, appOrigin) {
     let parsed;
     try {
@@ -75,12 +57,10 @@ export function linkLabel(url, appOrigin) {
     }
     return parsed.hostname.replace(/^www\./, "");
 }
-/** Trailing sentence punctuation (and an unmatched closing bracket) belongs to the prose, not the URL. */
 function splitUrl(raw) {
     const match = /[.,;:!?'"]+$/.exec(raw);
     return match === null ? { url: raw, rest: "" } : { url: raw.slice(0, match.index), rest: match[0] };
 }
-/** One sentence-cased "the run" for an id-bearing mention of it. */
 function theRun(match) {
     return /^[A-Z]/.test(match) ? "The run" : "the run";
 }
@@ -88,7 +68,6 @@ const RUN_ID = /\b(run|turn)\s*#\s*(\d+)\b/gi;
 const PROJECT_ID = /(?:^|[\s(])(r\d{1,3})\b(?![-\w/]|\.\w)/g;
 const NAMED_DIGEST = /\b(?:digest|sha(?:256)?|hash|commit|revision|build)\b[ \t:=]*\b((?=[0-9a-f]*\d)[0-9a-f]{7,64})\b/gi;
 const BARE_DIGEST = /\b((?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{16,64})\b/g;
-/** The kinds of id a reply names more than one of: those stay, so two runs (or projects, or digests) never read the same. */
 function severalIds(text) {
     const distinct = (pattern, key) => new Set([...text.matchAll(pattern)].map(key)).size;
     const several = new Set();
@@ -103,26 +82,20 @@ function severalIds(text) {
 }
 function dropIds(text, keep) {
     let body = text;
-    // "(run #12)", "(r1)", "(digest 4f2a…)" — an aside that only carries the id goes entirely.
     if (!keep.has("run"))
         body = body
             .replace(/[ \t]*\((?:run|turn)\s*#\s*\d+\)/gi, "")
-            // "the run #12", "run #12" → "the run".
             .replace(/\b(?:the\s+)?run\s*#\s*\d+\b/gi, theRun);
     if (!keep.has("digest"))
         body = body
             .replace(/[ \t]*\((?:(?:digest|sha(?:256)?|hash)?[\s:=]*[0-9a-f]{12,64})\)/gi, "")
-            // "digest 4f2a…", "commit 4f2a…" — the thing stays named, its value goes: "the digest".
             .replace(/\b(?:the\s+)?(digest|sha(?:256)?|hash|commit|revision|build)\b[ \t:=]*\b(?=[0-9a-f]*\d)[0-9a-f]{7,64}\b/gi, (match, noun) => `${/^[A-Z]/.test(match) ? "The" : "the"} ${noun.toLowerCase()}`)
-            // A bare long hex value with digits and letters is a digest.
             .replace(/[ \t]*\b(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{16,64}\b/g, "");
     if (!keep.has("project"))
         body = body
             .replace(/[ \t]*\(r\d{1,3}\)/gi, "")
-            // "project r1", "r1" → "the project".
             .replace(/\b(?:the\s+)?project\s+r\d{1,3}\b(?![-\w/]|\.\w)/gi, match => /^[A-Z]/.test(match) ? "The project" : "the project")
             .replace(/(^|[\s(])r\d{1,3}\b(?![-\w/]|\.\w)/g, (_, before) => `${before}the project`);
-    // Tidy what a removal left behind.
     return body
         .replace(/[ \t]+([,.;:!?)])/g, "$1")
         .replace(/[ \t]{2,}/g, " ");
@@ -138,10 +111,8 @@ function limitBold(text, state) {
     };
     return text
         .replace(/\*\*([^*\n]+?)\*\*/g, (_, inner) => anchor(inner))
-        // Single-asterisk emphasis reads as bold in some apps: plain here.
         .replace(/(^|[^*\w])\*(?![\s*])([^*\n]*?[^\s*])\*(?![*\w])/g, "$1$2");
 }
-/** Code and links held aside so no rule rewrites inside them; a bare URL is labelled as it is held. */
 function holdAside(text, options) {
     const held = [];
     const body = text.replace(/\r\n?/g, "\n").replace(PROTECTED, (match) => {
@@ -157,7 +128,6 @@ function holdAside(text, options) {
                 return HOLD(held.length - 1);
             }
             const { url, rest } = splitUrl(link[2]);
-            // The model's own words may name only our own pages; a foreign link always shows its real host.
             const label = /^https?:\/\//.test(link[1].trim()) || !ownLink(url, options.appOrigin) ? linkLabel(url, options.appOrigin) : link[1].trim();
             held.push(`[${label}](${url})`);
             return HOLD(held.length - 1) + rest;
@@ -175,12 +145,10 @@ function shapeWith(text, options, state) {
     const aside = holdAside(text, options);
     const held = aside.held;
     let body = aside.body;
-    // Headers become plain lines: ATX ("## Next steps") and setext underlines.
     body = body
         .replace(/^[ \t]{0,3}#{1,6}[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/gm, "$1")
         .replace(/^[ \t]{0,3}#{1,6}[ \t]*$/gm, "")
         .replace(/^([^\n]*\S[^\n]*)\n[ \t]{0,3}=+[ \t]*$/gm, "$1")
-        // A "* " bullet reads the same as "- ", and never as emphasis.
         .replace(/^([ \t]*)\*[ \t]+/gm, "$1- ");
     body = limitBold(body, state);
     if (state.keepIds !== "all")
@@ -191,24 +159,12 @@ function shapeWith(text, options, state) {
         .trim();
     return body.replace(/\u0000(\d+)\u0000/g, (_, index) => held[Number(index)] ?? "");
 }
-/**
- * The canonical shaped reply: plain lines, at most three bold anchors, labelled links, no internal ids unless asked
- * (or unless several of a kind would otherwise read the same), single blank lines. Idempotent: shaping a shaped reply
- * changes nothing.
- */
 export function shapeReply(text, options = {}) {
     return shapeWith(text, options, stateFor(text, options));
 }
-/**
- * A reply still being written, shaped with the final reply's presentation policy (docs/plans/responsive-chat.md §2.2),
- * except that ids are dropped unless the owner asked for them: whether a reply names several of a kind isn't known
- * until it ends, so a prefix never keeps them on that ground. Presentation, not redaction.
- */
 export function shapeReplyPrefix(text, options = {}) {
     return shapeWith(text, options, { boldLeft: BOLD_ANCHORS, keepIds: askedForIds(options.asked) ? "all" : new Set() });
 }
-/** Where a long reply may be cut: never inside code, a link, a URL or a bold anchor; best at a paragraph, then a line,
- * then a space. Always past `from`, and never between the two halves of an emoji. */
 function cutAt(text, from, size) {
     const limit = from + Math.max(1, size);
     if (limit >= text.length)
@@ -227,8 +183,6 @@ function cutAt(text, from, size) {
         if (best > from)
             return best;
     }
-    // No gap: cut before the token that crosses the limit. A link or URL longer than a whole part stays whole (cut, it
-    // would no longer go where it says); only code or plain text longer than a part is cut at the limit itself.
     const crossing = tokens.find(token => token.start < limit && limit < token.end);
     if (crossing !== undefined && crossing.start > from)
         return crossing.start;
@@ -239,18 +193,9 @@ function cutAt(text, from, size) {
         end = end - 1 > from ? end - 1 : end + 1;
     return end;
 }
-/** The first window of a shaped text of at most `size` characters, cut where a part would be (never inside code, a link,
- * a bold anchor or an emoji's two halves). A single link longer than the window stays whole, so the caller measures. */
 export function shapedWindow(shaped, size) {
     return shaped.slice(0, cutAt(shaped, 0, size));
 }
-/**
- * A long reply split into parts of at most `size` characters, then each part shaped: the cut is made on the reply as
- * written, at a paragraph or line where possible and never inside code, a link or a bold anchor, so no part carries
- * half of one. The parts share one bold budget and one rule for ids, as if the reply were shaped whole. `measure` is
- * how long a shaped part is once the channel renders it (its own link and escape format): a part that renders past
- * `size` is cut again, smaller. Only a single link longer than a part can exceed it, and it is never cut.
- */
 export function shapeReplyParts(text, size, options = {}, measure = shaped => shaped.length) {
     const state = stateFor(text, options);
     const normal = text.replace(/\r\n?/g, "\n");
@@ -270,7 +215,6 @@ export function shapeReplyParts(text, size, options = {}, measure = shaped => sh
         const before = state.boldLeft;
         const shaped = shapeWith(part, options, state);
         const length = measure(shaped);
-        // A labelled link or the channel's escapes can lengthen a part: cut that part again, smaller, and shape the pieces.
         if (length > size && part.length > 1) {
             const smaller = pieces(part, Math.max(1, Math.floor(part.length * size / length) - 1));
             if (smaller.length > 1) {
@@ -284,7 +228,6 @@ export function shapeReplyParts(text, size, options = {}, measure = shaped => sh
     }
     return parts;
 }
-/** A shaped reply as pieces: plain text, bold anchors, inline code and labelled links. Fenced code stays text. */
 export function replyPieces(shaped) {
     const pieces = [];
     const pattern = new RegExp(String.raw `(\x60\x60\x60[\s\S]*?(?:\x60\x60\x60|$))|\x60([^\x60\n]+)\x60|\*\*([^*\n]+?)\*\*|\[([^\]\n]{1,120})\]\((${URL_CHARS})\)`, "g");
@@ -308,17 +251,14 @@ export function replyPieces(shaped) {
     return pieces;
 }
 const slack = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
-/** Discord's presentation syntax, escaped; mentions are broken so nothing pings. */
 export const discordPlain = (text) => text.replace(/([\\`*_~|>#\[\]])/g, "\\$1").replace(/@/g, "@\u200b");
 const teams = (value) => value.replace(/([\\`*_\[\]<>#])/g, "\\$1");
-/** One line of a shaped reply as console HTML (the console lays out paragraphs and lists itself). */
 export function replyHtmlInline(shapedLine) {
     return joinHtml(replyPieces(shapedLine).map(piece => piece.kind === "text" ? piece.text
         : piece.kind === "bold" ? html `<strong>${piece.text}</strong>`
             : piece.kind === "code" ? html `<code>${piece.text}</code>`
                 : html `<a href="${piece.url}" rel="noopener noreferrer" target="_blank">${piece.label}</a>`));
 }
-/** A shaped reply in a channel's own text format (Telegram's formatting rides entities: see `telegramReply`). */
 export function renderReply(shaped, channel) {
     const pieces = replyPieces(shaped);
     switch (channel) {
@@ -335,7 +275,6 @@ export function renderReply(shaped, channel) {
                     : piece.kind === "code" ? `\`${piece.text}\``
                         : `[${discordPlain(piece.label)}](${piece.url})`).join("");
         case "teams":
-            // Teams' markdown keeps a single newline only as a paragraph break.
             return pieces.map(piece => piece.kind === "text" ? teams(piece.text).replace(/\n+/g, "\n\n")
                 : piece.kind === "bold" ? `**${teams(piece.text)}**`
                     : piece.kind === "code" ? `\`${piece.text}\``
@@ -345,7 +284,6 @@ export function renderReply(shaped, channel) {
             return pieces.map(piece => piece.kind === "link" ? `${piece.label} (${piece.url})` : piece.kind === "code" ? `\`${piece.text}\`` : piece.text).join("");
     }
 }
-/** A shaped reply for Telegram: plain text plus entities (bold anchors, code, labelled links). Offsets are UTF-16, as JS strings are. */
 export function telegramReply(shaped) {
     let text = "";
     const entities = [];
@@ -361,34 +299,22 @@ export function telegramReply(shaped) {
     }
     return { text, entities };
 }
-/** Shape and render in one step, for a surface that sends the reply as text. */
 export function voiceReply(text, channel, options = {}) {
     return renderReply(shapeReply(text, options), channel);
 }
-// ---- deliverables: a reply never claims an attachment the turn did not attach ----------------------------------
 const DETERMINER = String.raw `(?:(?:the|a|an|your|my|this|that|these|those|both|two|three|\d+|new|latest|full|updated|requested|fresh|final)\s+){0,2}`;
-/** Things that can only arrive attached: a reply's text can never be them. */
 const ATTACHMENT_ONLY = String.raw `(?:screenshots?|screen\s?shots?|images?|pictures?|photos?|recordings?|videos?|pdfs?|zips?|attachments?|spreadsheets?|csvs?)`;
-/** Things a reply can also list in its text (file names, log lines, a report's points). */
 const LISTABLE = String.raw `(?:files?|logs?|reports?|diffs?|documents?|links?)`;
 const NOUN = String.raw `(?:${ATTACHMENT_ONLY}|${LISTABLE})`;
-/** Presented ("here's the …") these need an attachment or a link: a reply's text can never be one. */
 const PRESENTED = String.raw `(?:${ATTACHMENT_ONLY}|links?|files?)`;
 const SEND = String.raw `(?:\bi(?:'ve|’ve|\s+have)\s+(?:just\s+)?(?:attached|included|shared|uploaded|sent|enclosed)|\bi(?:'m|’m|\s+am)\s+(?:now\s+)?(?:attaching|sending|sharing|uploading|enclosing)|\bi(?:'ll|’ll|\s+will)\s+(?:now\s+)?(?:attach|send|share|upload|enclose)|^\s*(?:attaching|sending|sharing|uploading|enclosing))\s+(?:you\s+)?`;
-/** A claim is an attachment noun plus a send verb, in one sentence. */
 const CLAIMS = [
-    // "I've attached the report", "I'm sending you the log", "I'll share the link", "Sending the file now".
     new RegExp(String.raw `${SEND}${DETERMINER}(${NOUN})\b`, "i"),
-    // "The screenshot is attached", "Logs attached", "the report is enclosed".
     new RegExp(String.raw `\b(${NOUN})\s+(?:(?:is|are|was|were)\s+)?(?:attached|enclosed|uploaded|included\s+below)\b`, "i"),
-    // "Here's the screenshot (of the payout page).", "Here's the link to the result.", "Below is the log file." — presenting
-    // something only a link or attachment can carry, with nothing listed after it. A bare "Here's the report." can be the
-    // reply's own text, so it is not one.
     new RegExp(String.raw `^\s*(?:here(?:'s|’s|\s+is|\s+are)|(?:attached|below)\s+(?:is|are))\s+${DETERMINER}(?:[\w-]+\s+)?(${PRESENTED})(?:\s+(?:of|for|to|from|showing)\s+[^:]+?)?[.!:]?\s*$`, "i"),
 ];
 const SENTENCE = /(?<=[.!?])\s+/;
 const LIST_LINE = /^\s*(?:[-*•]|\d{1,3}[.)])\s+\S|^\s*```/;
-/** One sentence's claim, if it makes one: the words, and whether its noun is something the text could list. */
 function claimOf(sentence) {
     for (const claim of CLAIMS) {
         const found = claim.exec(sentence);
@@ -399,12 +325,10 @@ function claimOf(sentence) {
     }
     return null;
 }
-/** The content a claim sentence lists itself: text after its colon ("…the files I changed: a.ts, b.ts"). */
 function listedAfterColon(tail) {
     const colon = /:\s*(\S[\s\S]*)$/.exec(tail);
     return colon === null ? null : colon[1];
 }
-/** Every claim in a reply, with whether the reply lists what it names (after a colon, or as the list that follows). */
 function claimsIn(text) {
     const lines = text.split("\n");
     const out = [];
@@ -421,20 +345,13 @@ function claimsIn(text) {
     });
     return out;
 }
-/**
- * The words in a reply that say something is being sent or attached ("I've attached the log", "here's the
- * screenshot"), or null. A claim needs an attachment noun and a send verb; one whose content the reply lists itself
- * ("I've included the files I changed: a.ts") is not a claim.
- */
 export function deliverableClaim(text) {
     return claimsIn(text).find(one => !one.listed)?.words ?? null;
 }
-/** Does the reply carry the thing itself: a link, or content quoted in a code block? */
 export function replyCarriesDeliverable(text) {
     return new RegExp(URL_CHARS).test(text) || /```[\s\S]+?```/.test(text);
 }
 export const NOTHING_ATTACHED = "I couldn't attach that to this reply.";
-/** The reply without its claims of an attachment, said plainly once; whatever a claim listed stays; never the claim alone. */
 export function dropDeliverableClaims(text) {
     const claims = claimsIn(text).filter(one => !one.listed);
     let said = false;
@@ -442,7 +359,6 @@ export function dropDeliverableClaims(text) {
         const claim = claims.find(one => one.line === lineIndex && one.sentence === sentenceIndex);
         if (claim === undefined)
             return sentence;
-        // Listed content is never dropped: it follows the plain words instead of the claim.
         const listed = listedAfterColon(claim.tail);
         if (listed !== null) {
             said = true;
@@ -459,7 +375,6 @@ export function dropDeliverableClaims(text) {
     }).filter(sentence => sentence !== "").join(" "));
     return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim() || NOTHING_ATTACHED;
 }
-/** The one repair step's words to the lead: attach it, or drop the claim. */
 export function deliverableRepair(claim) {
     return `Check before sending: your reply says "${claim.slice(0, 80)}", but nothing is attached or linked this turn. Attach it now with the right tool (get_result_images for screenshots, show_control for a page), or rewrite the reply without saying it is attached. Reply with the corrected message.`;
 }

package/dist/reply-voice.js

@@ -1,11 +1,5 @@
-/**
- * How a lead reply reads (docs/plans/lead-voice.md, V3): its length, its sentences, the internal words it says and
- * whether it opens by describing its own steps. Measured on the shaped text a person sees, never the raw reply.
- * A measure for the lead-answer eval's report; nothing gates on it and no reply is rewritten from it.
- */
 import { PLAIN_WORDS } from "./plain-words.js";
 import { shapeReply } from "./reply-shape.js";
-/** A reply longer than this is counted as long in the eval's report. */
 export const LONG_REPLY_CHARACTERS = 320;
 const CODE = /```[\s\S]*?(?:```|$)|`[^`\n]+`/g;
 const OWNER_AS_ADDRESS = /(?<![\w-])the\s+owner(?![\w-])/i;
@@ -23,7 +17,6 @@ export function replyVoice(reply) {
         narratedOpening: NARRATED_OPENING.test(shaped.trimStart()),
     };
 }
-/** One model's answers, summed up for the report. */
 export function summarizeVoice(voices) {
     const sorted = voices.map(one => one.characters).sort((a, b) => a - b);
     const mid = Math.floor(sorted.length / 2);

package/dist/report-summary.js

@@ -1,6 +1,4 @@
 import { readVerifiedReport } from "./evidence.js";
-/** The report a scout delivered, for get_task: title, summary, follow-ups —
- * verified before it is read; the document itself stays on the task page. */
 export function reportSummaryFor(store, evidenceRoot, taskRef) {
     if (store.latestReportArtifact(taskRef) === null)
         return null;
@@ -13,10 +11,7 @@ export function reportSummaryFor(store, evidenceRoot, taskRef) {
         return { problem: view.problem };
     return { title: view.report.title, summary: view.report.summary, followUps: view.report.followUps };
 }
-/** The longest full report a later flow step is given through {{stage.<id>.report}}. */
 export const REPORT_FILL_LIMIT = 20_000;
-/** What a report zone gives the zones after it besides its summary: its items as a numbered list (title, why, URL)
- * and the report's markdown, capped. Empty strings when it has neither. */
 export function reportFillIns(report) {
     const items = report.items.map((one, index) => `${index + 1}. ${one.title}\n   ${one.why.replace(/\s*\n\s*/g, " ")}\n   ${one.url}`).join("\n");
     const document = report.report.length <= REPORT_FILL_LIMIT ? report.report : `${report.report.slice(0, REPORT_FILL_LIMIT)}\n… (the rest of the report is on its task)`;

package/dist/reported-usage.js

@@ -1,31 +1,15 @@
-/**
- * What a provider itself reported about one call (docs/plans/evals-nightly.md, part B1): the exact model, its turn
- * count, its reported cost and its cache usage. Read only from the provider's own events and response bodies (Claude's
- * session `system`/`init` and primary `result`, Codex's `turn.completed`, an API's response body), never from text an
- * agent or a candidate wrote. Anything unreported or malformed is unknown (null), never 0.
- *
- * Three amounts are kept apart and never summed into one number: API dollars (work billed by use, with a reported or
- * priced cost), subscription usage (the provider's own reported cost of work a plan covers: not billed), and unknown.
- */
 import { usageOf } from "./run-efficiency.js";
-/** A model id as a provider reports it: printable ASCII with no spaces, at most 200 characters. Anything else is
- * unknown, never trimmed into something that could read as a different model. */
 const MODEL_ID = /^[\x21-\x7e]{1,200}$/;
-/** Several reported models are kept as their sorted ids joined by this (it has spaces, so no one id can equal it):
- * a run whose calls ran different models never reads as any one of them. */
 export const MODELS_JOIN = " + ";
 export function reportedModelOf(value) {
     return typeof value === "string" && MODEL_ID.test(value) ? value : null;
 }
-/** The one model a Claude result's `modelUsage` names; null when it names none, several, or anything malformed. */
 export function soleReportedModel(modelUsage) {
     if (typeof modelUsage !== "object" || modelUsage === null || Array.isArray(modelUsage))
         return null;
     const keys = Object.keys(modelUsage);
     return keys.length === 1 ? reportedModelOf(keys[0]) : null;
 }
-/** Two reports of the same piece of work (a resumed turn, a second init): unknown if either is, the model when they
- * agree, otherwise every model named, sorted (never one chosen). */
 export function combineReportedModels(a, b) {
     if (a === null || b === null)
         return null;
@@ -39,9 +23,6 @@ export function providerTurnsOf(value) {
 export function reportedCostUsdOf(value) {
     return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
 }
-/** A Claude primary `result` (streamed or buffered `--output-format json`), with what the session's inits named. The
- * init's model is the session's own; inits that disagree leave it unknown; with no init naming one, the result's
- * `modelUsage` counts only when it names exactly one model. */
 export function claudeResultReport(result, init = { model: null, conflict: false }) {
     const usage = usageOf({ provider: "claude", model: null, tokensIn: null, tokensOut: null, usageJson: usageJsonOf(result["usage"]) });
     return {
@@ -53,8 +34,6 @@ export function claudeResultReport(result, init = { model: null, conflict: false
         cacheWriteTokens: usage.cacheWrite,
     };
 }
-/** Codex's `turn.completed` usage: its input already counts what came from cache; it reports no cache writes, no
- * model and no cost in `exec --json`, so those stay unknown. */
 export function codexUsageReport(usage) {
     const read = usageOf({ provider: "codex", model: null, tokensIn: null, tokensOut: null, usageJson: usageJsonOf(usage) });
     return { modelReported: null, providerTurns: null, reportedCostUsd: null, tokensIn: read.in, cacheReadTokens: read.cacheRead, cacheWriteTokens: null };
@@ -62,10 +41,6 @@ export function codexUsageReport(usage) {
 function usageJsonOf(usage) {
     return typeof usage === "object" && usage !== null && !Array.isArray(usage) ? JSON.stringify(usage) : null;
 }
-/** A run's amount, from its fixed billing and its priced spend (run_spend). Subscription work reads its provider's
- * reported cost as usage, never as dollars; billed work without a reported or priced cost is unknown. v141 (Codex
- * round 1 #4, #10): billing this computer's default guessed (`basis` not evidence) is unknown, and so is a run whose
- * cost the provider never reported (its `cost_usd` then holds a conservative charge, never a measurement). */
 export function runAmountOf(run) {
     if (run.basis !== undefined && run.basis !== "evidence")
         return { kind: "unknown" };
@@ -79,11 +54,6 @@ export function runAmountOf(run) {
     return { kind: "unknown" };
 }
 const SUBSCRIPTION_CHAT = new Set(["claude-subscription", "codex-subscription"]);
-/** A chat request's amount: a subscription chat's reported cost is usage; an API chat's settled charge is dollars,
- * unless its spend is unknown (then the amount is, whatever was settled against the reservation). v141 (Codex round 1
- * #4): a subscription harness's request is subscription usage only when its own events said it was billed to the plan
- * (`billingReported`); one they said used a key is API dollars at its reported cost; one they said nothing of is
- * unknown. Absent `billingReported` keeps the older reading for callers that predate it. */
 export function chatTurnAmountOf(turn) {
     if (SUBSCRIPTION_CHAT.has(turn.provider)) {
         if (turn.billingReported === undefined || turn.billingReported === "subscription")

package/dist/repos.js

@@ -1,15 +1,3 @@
-/**
- * Which repositories the operator has actually committed to.
- *
- * Discovery is total and costs nothing, so it stays the way you find things.
- * Enrollment is the smaller, deliberate list: what gets reported by default,
- * and later what may be written to. Keeping the two separate is what lets the
- * first run need no configuration while the tenth run stays quiet.
- *
- * The file is plain JSON in a conventional location because someone will want
- * to edit it by hand or check it into their dotfiles — which also means it is
- * untrusted input and gets validated like any other.
- */
 import { closeSync as closeFd, constants as fsConstants, fstatSync, openSync as openFd, readSync, renameSync as renameFile, writeFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
@@ -18,8 +6,6 @@ import { sleep } from "./sleep.js";
 export const CONFIG_VERSION = 2;
 const FILE_NAME = "repos.json";
 export function configPath(env, home) {
-    // Rename continuity: an enrolled list under an older name keeps working
-    // until one exists under the new one.
     return namedPath(configBase(env, home), [FILE_NAME]);
 }
 export async function loadProjectRegistry(file) {
@@ -28,9 +14,6 @@ export async function loadProjectRegistry(file) {
         text = await readFile(file, "utf8");
     }
     catch (cause) {
-        // ONLY the missing file is the ordinary first-run state (round-3
-        // finding 6): a permission or I/O failure is an unreadable registry,
-        // never an empty one — the MCP gateway fails closed on it.
         if (cause.code === "ENOENT")
             return { repos: [], roots: [] };
         return { error: `${file} could not be read (${String(cause.message)})` };
@@ -48,7 +31,6 @@ export async function loadProjectRegistry(file) {
     }
     return { repos: sortUnique(registry.repos), roots: sortUnique(registry.roots) };
 }
-/** Compatibility view for reports, CLI enrollment, and the MCP surface. */
 export async function loadRepos(file) {
     const loaded = await loadProjectRegistry(file);
     return "error" in loaded ? loaded : { repos: loaded.repos };
@@ -58,19 +40,6 @@ export async function saveRepos(file, repos) {
     const config = { version: CONFIG_VERSION, repos: sortUnique(repos), roots: [] };
     await writeFile(file, `${JSON.stringify(config, null, 2)}\n`, "utf8");
 }
-/**
- * The ONE locked registry update (onboarding findings 9/17/19/25/29/30):
- * every writer — CLI add/remove, the console, up's enrollment — goes
- * through here. The lock is an exclusive-create file whose body carries
- * {pid, token, at}; a LIVE owner's lock is never touched; stale recovery
- * runs only after kill(pid, 0) proves the owner dead, serialized through
- * a second exclusive reaper lock that re-reads the exact snapshot it
- * observed before unlinking. The owner releases only while its hold is
- * under 25s — past that it abandons WITHOUT unlinking and reports so; the
- * deadline is checked BEFORE publication, so a committed rename is never
- * reported as failed. Reads: only ENOENT means an empty registry —
- * malformed JSON, wrong shape, EACCES, and I/O errors REFUSE.
- */
 export async function updateRepos(file, transform) {
     const updated = await updateProjectRegistry(file, current => ({
         ...current,
@@ -78,7 +47,6 @@ export async function updateRepos(file, transform) {
     }));
     return updated.ok ? { ok: true, repos: updated.registry.repos } : updated;
 }
-/** Atomically update repositories and roots without either writer erasing the other. */
 export async function updateProjectRegistry(file, transform) {
     const { openSync, closeSync, writeSync, readFileSync, unlinkSync, existsSync: exists, mkdirSync, renameSync } = await import("node:fs");
     const { randomBytes } = await import("node:crypto");
@@ -88,9 +56,6 @@ export async function updateProjectRegistry(file, transform) {
     const token = randomBytes(16).toString("hex");
     const body = JSON.stringify({ pid: process.pid, token, at: Date.now() });
     const tryReap = () => {
-        // Recovery only for PROVEN-dead owners, serialized by the reaper lock,
-        // which re-reads the exact snapshot before unlinking (finding 29). An
-        // orphaned reaper lock is itself reaped by the same dead-pid rule.
         let snapshot = null;
         try {
             snapshot = JSON.parse(readFileSync(lockPath, "utf8"));
@@ -102,10 +67,9 @@ export async function updateProjectRegistry(file, transform) {
             return;
         try {
             process.kill(snapshot.pid, 0);
-            return; // alive: never touched
+            return;
         }
         catch {
-            // ESRCH — dead; continue under the reaper lock
         }
         try {
             const before = readFileSync(reaperPath, "utf8");
@@ -113,30 +77,27 @@ export async function updateProjectRegistry(file, transform) {
             if (typeof parsed?.pid === "number") {
                 try {
                     process.kill(parsed.pid, 0);
-                    return; // a live reaper is working
+                    return;
                 }
                 catch {
                     try {
                         unlinkSync(reaperPath);
                     }
-                    catch { /* raced */ }
+                    catch { }
                 }
             }
         }
         catch {
-            // no reaper lock — proceed to claim it
         }
         let reaperFd;
         try {
             reaperFd = openSync(reaperPath, "wx");
         }
         catch {
-            return; // another reaper won
+            return;
         }
         try {
             writeSync(reaperFd, JSON.stringify({ pid: process.pid }));
-            // Re-read and require the EXACT observed snapshot + a repeated
-            // dead-pid proof before unlinking (finding 29).
             const now = readFileSync(lockPath, "utf8");
             const again = JSON.parse(now);
             if (again?.pid === snapshot.pid && again?.token === snapshot.token) {
@@ -147,19 +108,18 @@ export async function updateProjectRegistry(file, transform) {
                     try {
                         unlinkSync(lockPath);
                     }
-                    catch { /* raced */ }
+                    catch { }
                 }
             }
         }
         catch {
-            // lock vanished or changed — nothing to do
         }
         finally {
             closeSync(reaperFd);
             try {
                 unlinkSync(reaperPath);
             }
-            catch { /* already gone */ }
+            catch { }
         }
     };
     let held = false;
@@ -183,7 +143,7 @@ export async function updateProjectRegistry(file, transform) {
     try {
         let current;
         if (!exists(file)) {
-            current = { repos: [], roots: [] }; // ONLY the missing-file case is an empty registry
+            current = { repos: [], roots: [] };
         }
         else {
             let text;
@@ -208,14 +168,10 @@ export async function updateProjectRegistry(file, transform) {
         }
         const transformed = transform({ repos: [...current.repos], roots: [...current.roots] });
         const next = { repos: sortUnique(transformed.repos), roots: sortUnique(transformed.roots) };
-        // Deadline BEFORE publication (finding 30): a rename past the hold
-        // window would commit while the lock may already be reaped.
         if (acquiredAt() > 20_000) {
-            held = false; // abandon: no unlink, no publication
+            held = false;
             return { ok: false, reason: "abandoned", message: "the registry lock aged out before the update could publish — nothing changed; try again" };
         }
-        // Each line this update removes counts one more removal, written BEFORE the list is published: whoever holds a
-        // start's authority for a saved line (upDeferredRetry) sees that it was removed, even if it was saved again since.
         const gone = current.repos.filter(one => !next.repos.includes(one));
         if (gone.length > 0)
             bumpRegistryRemovals(file, gone, `${process.pid}.${token.slice(0, 8)}`);
@@ -232,11 +188,10 @@ export async function updateProjectRegistry(file, transform) {
             try {
                 unlinkSync(lockPath);
             }
-            catch { /* reaped despite liveness rules */ }
+            catch { }
         }
     }
 }
-/** Strict shape for the locked path (finding 36): non-string entries REFUSE. */
 function readProjectRegistryStrict(parsed) {
     if (typeof parsed !== "object" || parsed === null)
         return null;
@@ -256,7 +211,6 @@ export function removeRepos(existing, targets) {
     const unwanted = new Set(targets);
     return existing.filter(repo => !unwanted.has(repo));
 }
-/** null when the shape is wrong; non-string entries are dropped, not trusted. */
 function readProjectRegistry(parsed) {
     if (typeof parsed !== "object" || parsed === null)
         return null;
@@ -273,14 +227,9 @@ function readProjectRegistry(parsed) {
 function sortUnique(repos) {
     return [...new Set(repos)].sort();
 }
-/** Beside the saved list: how many times each line has been removed from it (written under its lock). */
 export function registryRemovalsFile(file) {
     return `${file}.removals.json`;
 }
-/**
- * How many times each saved line has been removed, as recorded under the saved list's lock. A file that can't be read
- * as one answers null: its caller treats every line as changed (fail closed).
- */
 export function registryRemovals(file) {
     let fd;
     try {
@@ -313,10 +262,8 @@ export function registryRemovals(file) {
         closeFd(fd);
     }
 }
-/** One more removal for each of `lines`, written whole and renamed into place. Called only under the list's lock. */
 function bumpRegistryRemovals(file, lines, tag) {
     const kept = registryRemovals(file);
-    // An unreadable record starts again from the clock, so no count read before can come round again.
     const counts = kept ?? {};
     for (const line of lines)
         counts[line] = kept === null ? Date.now() : (counts[line] ?? 0) + 1;