toolroll 0.9.104 → 0.9.105

package/dist/lead.js

@@ -17,14 +17,11 @@ import { shortenAsk } from './text-limits.js';
 import { envValue } from "./names.js";
 import { deliverableClaim, deliverableRepair, dropDeliverableClaims, replyCarriesDeliverable } from "./reply-shape.js";
 export const LEAD_MESSAGE_MAX_CHARS = 2_000;
-/** Where a promise made this turn is reported: the chat app it arrived on, or this conversation for the console and terminal. */
 function promiseChannelOfTurn(channel) {
     return channel === undefined ? undefined : channel === "console" || channel === "terminal" ? "chat" : channel;
 }
-/** The thread's recent history the model sees, most recent first until the cap. */
 export const LEAD_HISTORY_CAP_BYTES = 16_384;
 export const LEAD_HISTORY_MAX_MESSAGES = 40;
-/** What happened, what it means, and one next step: plain words a person can act on, never internal terms. */
 export const LEAD_REFUSAL_COPY = {
     "empty-message": `That message was empty or too long, so it wasn't sent. Write 1 to ${LEAD_MESSAGE_MAX_CHARS} characters and send it again.`,
     "secret-in-message": "That message looks like it contains a password or key, so it wasn't sent or saved. Remove it and send the message again.",
@@ -47,7 +44,6 @@ export const LEAD_REFUSAL_COPY = {
     "request-changed": "That send was already received with different text or task context. Reload the conversation before sending a new message.",
     channel: "This conversation's connection changed, so the message wasn't sent. Reconnect it, then send again.",
 };
-/** A turn stopped because its chat's standing changed: what happened, what it means, one next step. */
 export const LEAD_CHANNEL_COPY = {
     unpaired: "This chat is no longer connected to your account, so the reply was stopped. Nothing it proposed was kept. Connect the chat again in Settings, then send your message again.",
     "not-approver": "Your account can no longer approve work here, so the reply was stopped. Nothing it proposed was kept. Ask an owner to restore your access, then send your message again.",
@@ -56,7 +52,6 @@ export const LEAD_CHANNEL_COPY = {
     "member-changed": "Your account in this chat app no longer has access, so the reply was stopped. Nothing it proposed was kept. Ask the app's admin to add you back, then send your message again.",
     "access-changed": "This chat's access changed while the lead was answering, so the reply was stopped. Nothing it proposed was kept. Reconnect the chat, then send your message again.",
 };
-/** Why a reply did not finish, in the same three parts: what happened, what it means, one next step. */
 export const LEAD_FAILURE_COPY = {
     stopped: "This reply was stopped before it finished, from another window or by a newer message. Nothing it proposed was kept. Send your message again if you still need an answer.",
     ended: "Your sign-in or this conversation ended while the lead was answering. Nothing it proposed was kept. Sign in again or start a new chat, then send your message again.",
@@ -76,17 +71,12 @@ export const LEAD_FAILURE_COPY = {
     empty: "The lead sent back an empty answer. Nothing was kept. Send your message again.",
     unusable: "The lead's answer couldn't be used, so it was thrown away. Nothing was kept. Send your message again.",
 };
-/** A failed turn's saved reason as plain words, for a surface that reads the turn back later (a restart, a delivery retry).
- * Its saved detail (v158), when known, names the exact cause the person saw live ("not installed", "sign-in expired"). */
 export function leadFailureText(reason, unknownSpend = false, detail = null) {
-    // A turn whose cost is unknown paused chat: say what happened (its reason's first sentence), then that the person must
-    // confirm the cost before chat runs again — never "send it again", which would only meet the pause.
     if (unknownSpend) {
         if (reason === "malformed-reply")
             return LEAD_FAILURE_COPY.unreadableUnknownCost;
         if (reason === "over-reservation")
             return LEAD_FAILURE_COPY.overReserved;
-        // Whether proposals were kept depends on how it ended (a timeout keeps what it drafted): this says nothing about them.
         const happened = /^[^.]*\./.exec(leadFailureText(reason))?.[0] ?? "The lead's reply didn't finish.";
         return `${happened} Its cost isn't known, so chat is paused. Confirm the cost on the Chat page to turn chat back on.`;
     }
@@ -107,28 +97,20 @@ export function leadFailureText(reason, unknownSpend = false, detail = null) {
         default: return "The lead's reply didn't finish. Nothing it proposed was kept. Send your message again.";
     }
 }
-/** How long a provider that ignored its abort at the turn's deadline is waited for before the turn ends without it.
- * Its process group was already killed at the deadline; this only bounds the wait for the transport to say so. */
 export const LEAD_ABORT_GRACE_MS = 5_000;
 const LATE = Symbol("late");
-/** The work's own result, or LATE once `ms` passes: the turn's clock, not the work, decides when the person hears back. */
 function settleBy(work, ms) {
     let timer;
     const late = new Promise(resolve => { timer = setTimeout(() => resolve(LATE), Math.max(0, ms)); });
     return Promise.race([work, late]).finally(() => clearTimeout(timer));
 }
 const READ_TOOLS = new Set(["get_brief", "get_project_context", "get_code_map", "get_project_activity", "get_actions", "get_action_status", "get_skills", "get_acceptance_evidence", "recap", "list_repos", "list_tasks", "get_task", "get_result", "get_result_images", "get_controls", "get_agents", "get_project_knowledge", "get_flaky_tests", "get_task_conversation", "get_diff", "get_check_log", "get_project_tools", "get_flows", "get_flow_insights", "list_decisions", "get_decision", "queue"]);
-/** The last messages of the thread as provider-neutral history, newest kept first until the byte cap. */
 export function historyFor(store, thread, queuedMessageId, named = queuedMessageId !== undefined) {
-    // Admitted messages only (v128): a queued message — this one, a teammate's, or one removed while waiting — never
-    // reaches the model before its own turn takes it.
     const rows = store.listLeadHistory(thread, LEAD_HISTORY_MAX_MESSAGES);
     const kept = [];
     let bytes = 0;
     for (let index = rows.length - 1; index >= 0; index--) {
         const row = rows[index];
-        // The current message appears once (it is added after the history). Messages still waiting — a teammate's or this
-        // person's — are already left out by listLeadHistory (pending); a mirrored channel question is history like any other.
         if (row.id === queuedMessageId)
             continue;
         bytes += Buffer.byteLength(row.text, "utf8");
@@ -137,17 +119,13 @@ export function historyFor(store, thread, queuedMessageId, named = queuedMessage
         const author = named && row.role === 'operator' && row.turn !== null ? store.getLeadTurn(row.turn)?.approver : undefined;
         kept.unshift(row.role === "operator" ? { role: "operator", text: author ? `From ${author}:\n${row.text}` : row.text } : { role: "assistant", text: row.text, calls: [] });
     }
-    // A history must open with the operator: a leading assistant reply without its question is dropped.
     while (kept[0]?.role === "assistant")
         kept.shift();
     return kept;
 }
-/** "read 3 · proposed 1 · 2 steps" — counts only, never results (ruling 11). */
 export function activitySummary(reads, proposals, steps, cacheShare = null) {
-    // How much of what it read came from the provider's cache, when every request reported it (docs/plans/run-efficiency.md).
     return [`read ${reads}`, `proposed ${proposals}`, `${steps} step${steps === 1 ? "" : "s"}`, ...(cacheShare === null ? [] : [`${Math.round(cacheShare * 100)}% cached`])].join(" · ");
 }
-/** A tool result as the model sees it, measured as embedded; over the cap it becomes a typed refusal. */
 function capped(value) {
     const text = JSON.stringify(value);
     if (toolResultBytes(text) <= LEAD_TOOL_RESULT_CAP_BYTES)
@@ -162,16 +140,12 @@ export async function runLeadTurn(input) {
     const message = input.message.trim();
     if (message === "" || message.length > LEAD_MESSAGE_MAX_CHARS)
         return refuse("empty-message");
-    // Secrets refuse BEFORE any row or request exists — nothing stored, nothing sent.
     if (scanForSecrets(message).length > 0)
         return refuse("secret-in-message");
-    // Ruling 3 + 10: a minted, intact principal, re-proved against the current row.
     if (!isVerifiedApprover(who) || !reproveApprover(store, who).ok || who.generation !== session.approverGeneration)
         return refuse("standing");
-    // Ruling 9: the session and the thread are bound to the ceiling this surface holds.
     if (session.ceilingDigest !== who.ceilingDigest || thread.ceilingDigest !== who.ceilingDigest)
         return refuse("ceiling-changed");
-    // Sprint 8: the lead and project chats run on a provider and model the organisation policy allows, or not at all.
     const disallowed = store.agentPolicyRefusal(config.provider, config.model);
     if (disallowed !== null)
         return { ok: false, refused: "policy", message: disallowed };
@@ -183,24 +157,17 @@ export async function runLeadTurn(input) {
         return refuse("unpriced");
     if (direct && input.key === null)
         return refuse("unpriced");
-    // API accounting binds to the secret credential. A subscription has no
-    // API credential or dollar ledger, but changing harness still ends the
-    // old session through a stable provider-specific identity.
     const credentialKey = direct
         ? credentialKeyOf(directProvider, input.key)
         : subscriptionCredentialKey(subscriptionProvider);
     const request = input.requestId;
     if (request !== undefined && !/^[a-f0-9]{32}$/.test(request))
         return refuse("invalid-request");
-    // Replays are read-only, but still require today's authority, not the
-    // session/thread snapshots supplied by a previous browser page.
     const liveSession = store.getLeadSession(session.id);
     const liveThread = store.getLeadThread(thread.id);
     const sharedThread = liveThread !== null && store.canUseTeamMateThread(who.name, who.generation, liveThread.id);
     if (liveSession?.approver !== who.name || (liveThread?.approver !== who.name && !sharedThread) || liveSession.credentialKey !== credentialKey)
         return refuse("not-yours");
-    // A queued message binds only from a shared team thread, or as the exact personal queue claim of this person's own
-    // thread (its row is this approver's, in this thread, claimed under that runner and generation).
     const personalQueued = input.queueClaim !== undefined && input.queueClaim.message === input.queuedMessageId &&
         store.handle.prepare("SELECT 1 FROM lead_queue WHERE message = ? AND approver = ? AND thread = ? AND status = 'running' AND runner = ? AND generation = ? AND turn_id IS NULL")
             .get(input.queueClaim.message, who.name, thread.id, input.queueClaim.runner, input.queueClaim.generation) !== undefined;
@@ -216,11 +183,8 @@ export async function runLeadTurn(input) {
     const receipt = request === undefined ? null : store.leadRequestReceipt(session.id, request);
     if (receipt !== null)
         return receipt.digest === digest ? { ok: true, replayed: true, turn: receipt.turn } : refuse("request-changed");
-    // The channel's standing, proved before anything is admitted or sent.
     if (input.revalidate !== undefined && !(await input.revalidate()).ok)
         return refuse("channel");
-    // Which model answers (responsive-chat.md §8), decided once, before the turn: the faster one only for a plain read
-    // question with quick answers on; everything else on the configured model, as before.
     const quickOn = leadQuickAnswersOn(store);
     const quickModel = quickOn ? quickLeadModel(store) : config.model;
     let route = quickRoute({ enabled: quickOn, provider: config.provider, mainModel: config.model, message,
@@ -229,16 +193,12 @@ export async function runLeadTurn(input) {
     let now = clock();
     store.sweepStaleLeadTurns(now);
     const view = leadViewContextFor(store, who);
-    // Names in the bundle are deliberate (the lead's, the person's first name, project labels); everything else is scrubbed.
     const document = leadContext(store, who.repos, now, { owner: who.name, thread: thread.id, redact: text => redactForLead(text, view),
         projectName: (path, index) => projectLabelForLead(path, index, view.names),
         ...(input.evidenceRoot === undefined ? {} : { evidenceRoot: input.evidenceRoot }), ...(input.channel === undefined ? {} : { channel: input.channel }), ...(input.leadName === undefined ? {} : { leadName: input.leadName }) });
-    // A team room names who wrote each message; a person's own queued message is just theirs.
     const authoredMessage = input.queuedMessageId === undefined || personalQueued ? message : `From ${who.name}:\n${message}`;
     const historyMessage = input.context === undefined ? authoredMessage : `${redactForLead(input.context, view)}\n\n${authoredMessage}`;
     const history = [...historyFor(store, thread.id, input.queuedMessageId, input.queuedMessageId !== undefined && !personalQueued), { role: "operator", text: historyMessage }];
-    // Tools on demand (docs/plans/lead-deferred-tools.md): a request advertises the core tools, then the ones find_tools
-    // found earlier in this reply, in that order (so the core prefix stays the same as tools are found).
     const findTools = { searches: 0, found: new Set() };
     const advertisedTools = () => [
         ...LEAD_TOOL_SCHEMAS.filter(one => LEAD_CORE_TOOLS.has(one.name)),
@@ -247,23 +207,15 @@ export async function runLeadTurn(input) {
     const composeDirect = (key, tools) => {
         if (!direct)
             throw new Error("not a direct chat provider");
-        // Anthropic prompt caching: the core tools (always first) end the first breakpoint (docs/plans/lead-deferred-tools.md).
         const cache = directProvider === "anthropic-api" ? { coreTools: tools.filter(one => LEAD_CORE_TOOLS.has(one.name)).length } : undefined;
         return composeLeadRequest({ provider: directProvider, model: config.model, key, system: LEAD_CONTRACT, dataDocument: document, history, tools, ...(cache === undefined ? {} : { cache }) });
     };
     const composeSubscription = (tools) => composeSubscriptionLeadPrompt({ system: LEAD_CONTRACT, dataDocument: document, history, tools });
-    // The reservation-only base: the FULL registry, serialized as a request would be, so any tool found later in this
-    // reply is already covered by the worst case. What is sent each round is smaller (the advertised set) and is scanned
-    // whole before every dispatch. Only direct API traffic needs a dollar reservation; subscription traffic records zero.
     const base = direct ? composeDirect("", LEAD_TOOL_SCHEMAS).body : composeSubscription(LEAD_TOOL_SCHEMAS);
     if (scanForSecrets(base).length > 0)
         return refuse("secret-in-context");
-    // Fit the bounded tool loop to the already-authorized remaining allowance.
-    // Context/history growth must not demand a larger budget for a simple reply.
-    // Each chosen step retains the same worst-case call/output accounting.
     let maxSteps = LEAD_MAX_STEPS;
     const baseBytes = Buffer.byteLength(base, "utf8");
-    // With prompt caching on (Anthropic), the worst case reserves every input token at the cache-write rate (the dearest).
     const reservePrice = direct && directProvider === "anthropic-api" ? cacheWorstPrice(price) : price;
     const reserveFor = (steps) => direct ? leadWorstCaseForPrice(reservePrice, baseBytes, { steps }) : 0;
     if (direct) {
@@ -300,7 +252,6 @@ export async function runLeadTurn(input) {
         if (input.queuedMessageId === undefined)
             store.appendLeadMessage({ thread: thread.id, turn: turnId, role: "operator", text: message }, now);
         else {
-            // Binding admits it: the same statement clears pending, so it joins history exactly when its turn exists (v128).
             const bound = store.handle.prepare("UPDATE lead_message SET turn=?, pending=0 WHERE id=? AND thread=? AND role='operator' AND turn IS NULL AND text=?")
                 .run(turnId, input.queuedMessageId, thread.id, message);
             if (Number(bound.changes) !== 1)
@@ -321,9 +272,8 @@ export async function runLeadTurn(input) {
     const progress = (event) => { try {
         input.onProgress?.(event);
     }
-    catch { /* a watcher never breaks the turn */ } };
+    catch { } };
     progress({ kind: "started", turn: turnId });
-    /** Text that looked like a secret was held back: every preview closes, once (responsive-chat.md §2.1). */
     let blockedSaid = false;
     const blockPreview = () => { if (!blockedSaid) {
         blockedSaid = true;
@@ -336,10 +286,8 @@ export async function runLeadTurn(input) {
     const readResults = new Map();
     const searchedMemory = new Map();
     const checkedCapabilities = new Map();
-    /** The turn's one question to its owner: shown with the reply only once the turn answers; a failed turn drops it. */
     const ask = (question, options) => store.recordLeadAsk({ turn: turnId, thread: thread.id, question, options }, clock());
     let tokensIn = 0;
-    // What its requests read from the provider's cache; known only while every request reported it.
     let cacheRead = 0, cacheKnown = true;
     let tokensOut = 0;
     let settled = 0;
@@ -349,22 +297,18 @@ export async function runLeadTurn(input) {
         proposals++;
         return store.draftLeadProposal({ thread: thread.id, turn: turnId, kind, payload, ceilingDigest: who.ceilingDigest }, clock());
     };
-    /** The screenshots a tool selected, kept under THIS turn: a failed turn deletes them with its drafts; a channel plans sends only from an answered turn. */
     const selectEvidence = (rows) => {
         store.recordLeadTurnEvidence(turnId, rows, RESULT_IMAGES_PER_TURN_CAP, clock());
         if (store.getLeadTurn(turnId)?.state !== "running")
             return [];
         return store.listLeadTurnEvidence(turnId).map(one => one.artifact);
     };
-    /** The turn ends failed: its drafts are deleted, its cost settled — the whole reservation when any of it is unknown. */
     const fail = (failed, message, unknownSpend, failureDetail = null) => {
         now = clock();
         store.finalizeLeadTurn(turnId, started.generation, { state: "failed", settledMicrousd: settled, unknownSpend, tokensIn, tokensOut, failureReason: failed, failureDetail }, now);
         store.dropLeadAsk(turnId);
         return { ok: false, turn: turnId, failed, message, unknownSpend };
     };
-    /** The turn stopped at its deadline: the notice is saved in the thread with whatever its completed tool calls proposed, in
-     * the same write that ends the turn, so a refresh, another device or a restart shows the same outcome. */
     const timedOut = (unknownSpend, failureDetail = null) => {
         now = clock();
         const message = leadTimeoutNotice(proposals > 0, unknownSpend);
@@ -375,15 +319,11 @@ export async function runLeadTurn(input) {
         return { ok: false, turn: turnId, failed: "timeout", message, unknownSpend, saved: true };
     };
     const deadlineLeft = () => TURN_WALL_CLOCK_MS - (clock().getTime() - turnStartedAt);
-    /** The channel's standing, bounded by the turn's deadline: a lookup that never answers cannot hold the turn open. */
     const revalidated = async () => input.revalidate === undefined ? { ok: true } : settleBy(input.revalidate(), deadlineLeft() + LEAD_ABORT_GRACE_MS);
-    /** The turn's own row, re-read: still running under our generation, or someone ended it under us. */
     const stillOurs = () => {
         const row = store.getLeadTurn(turnId);
         return row !== null && row.state === "running" && row.generation === started.generation;
     };
-    // The channel lookup can await external state. Re-read all local authority
-    // AFTER it resolves, immediately before sending context or using a tool.
     const guard = (channel) => {
         if (!stillOurs())
             return { ok: false, turn: turnId, failed: "superseded", message: LEAD_FAILURE_COPY.stopped, unknownSpend: false };
@@ -402,13 +342,9 @@ export async function runLeadTurn(input) {
     let reply = null;
     let stoppedAtCap = false;
     let lastText = "";
-    /** A page shown this turn (show_control): a reply may say it links one. */
     let shownControl = false;
-    /** The turn's one repair step for a reply that claims an attachment it does not carry. */
     let repaired = false;
-    /** The turn's one shorten step for a reply over its channel's message limit (LEAD_REPLY_LIMITS); still over, it is split. */
     let shortened = false;
-    /** Why the next step runs, when it re-asks about the reply itself (repair or shorten): the live status says so. */
     let nextReason;
     const replyLimit = input.channel === undefined ? null : LEAD_REPLY_LIMITS[input.channel];
     const unbacked = (text) => {
@@ -425,14 +361,11 @@ export async function runLeadTurn(input) {
         const remainingMs = TURN_WALL_CLOCK_MS - (now.getTime() - turnStartedAt);
         if (remainingMs <= 0)
             return timedOut(false);
-        // This request's advertised tools: fixed for the request; a tool found in its reply is advertised from the next one.
-        // A quick step (§8) advertises the reads, and find_tools as its way to ask for more, on the faster model.
         const quick = route === "fast";
         const stepModel = quick ? quickModel : config.model;
         const advertised = quick ? LEAD_TOOL_SCHEMAS.filter(one => quickAdvertises(one.name)) : advertisedTools();
         const advertisedNames = new Set(advertised.map(one => one.name));
         const request = direct ? composeDirect(input.key, advertised) : composeSubscription(advertised);
-        // Tool results join the outbound body: scanned again before every dispatch.
         const outbound = typeof request === "string" ? request : request.body;
         if (scanForSecrets(outbound).length > 0) {
             return fail("secret-refused", LEAD_FAILURE_COPY.secretRead, false);
@@ -451,13 +384,9 @@ export async function runLeadTurn(input) {
         nextReason = undefined;
         const requestBytes = Buffer.byteLength(outbound, "utf8");
         let result;
-        // The turn owns its deadline (lead-stall, release check 2438): at the deadline the request is aborted, which ends a
-        // harness's whole process group, and a provider that still has not settled LEAD_ABORT_GRACE_MS later is left behind.
-        // Whatever it says after that is never read; the turn has already ended with its notice.
         const controller = new AbortController();
         const abortAt = setTimeout(() => controller.abort(), remainingMs);
         const settle = (work) => settleBy(work, remainingMs + LEAD_ABORT_GRACE_MS)
-            // A harness that ended at the deadline still says whether it had written anything (recorded, never shown).
             .then(value => value === LATE ? { ok: false, problem: "timeout" } : controller.signal.aborted
             ? { ok: false, problem: "timeout", ...(!value.ok && "quiet" in value && typeof value.quiet === "boolean" ? { quiet: value.quiet } : {}) } : value)
             .finally(() => clearTimeout(abortAt));
@@ -476,8 +405,6 @@ export async function runLeadTurn(input) {
                 tools: advertised,
                 timeoutMs: remainingMs,
                 signal: controller.signal,
-                // The reply as it is written; text that looks like a secret is
-                // never shown (the finished reply is scanned again before saving).
                 ...(input.onProgress === undefined ? {} : { onText: (text) => { if (controller.signal.aborted)
                         return; if (scanForSecrets(text).length === 0)
                         progress({ kind: "text", turn: turnId, step: steps, text });
@@ -489,7 +416,6 @@ export async function runLeadTurn(input) {
         const finishStep = (outcome) => store.finalizeChatTurn(step.id, stepStarted.generation, outcome, now);
         if (!result.ok) {
             if (!direct) {
-                // The exact cause, saved (v158): what a later reader shows, and what the next timeout diagnosis reads.
                 const quiet = "quiet" in result ? result.quiet : undefined;
                 const detail = result.problem === "timeout" ? (quiet === true ? "timeout-silent" : quiet === false ? "timeout-output" : null)
                     : result.problem === "not-found" ? "not-installed" : result.problem === "malformed-reply" ? null : "sign-in";
@@ -506,7 +432,6 @@ export async function runLeadTurn(input) {
                 return fail(result.problem === "malformed-reply" ? "malformed-reply" : "provider-error", message, false, detail);
             }
             if (result.problem.startsWith("status-")) {
-                // The provider ANSWERED with an error: nothing billed for this step.
                 finishStep({ state: "failed", failureReason: "provider-error", settledMicrousd: 0, failureDetail: "refused" });
                 return fail("provider-error", LEAD_FAILURE_COPY.refused, false, "refused");
             }
@@ -522,37 +447,27 @@ export async function runLeadTurn(input) {
             return fail("malformed-reply", LEAD_FAILURE_COPY.unreadableUnknownCost, true);
         }
         const answer = result.answer;
-        // The streamed reply's finished text, once, secret-checked whole: only now may its last word show live.
         if (!direct && input.onProgress !== undefined && !controller.signal.aborted && answer.text !== "") {
             if (scanForSecrets(answer.text).length === 0)
                 progress({ kind: "text", turn: turnId, step: steps, text: answer.text, final: true });
             else
                 blockPreview();
         }
-        // Usage that cannot be true — more input tokens than bytes sent — is a
-        // malformed reply with unknown cost, never a number to settle by.
         if (direct && answer.tokensIn > requestBytes) {
             finishStep({ state: "failed", failureReason: "malformed-reply", settledMicrousd: null, unknownSpend: true });
             return fail("malformed-reply", LEAD_FAILURE_COPY.unreadableUnknownCost, true);
         }
-        // The pinned math, or the provider's own reported charge when HIGHER.
         const stepSettled = direct
             ? Math.max(settleWithCache(price, answer), answer.reportedCostMicrousd ?? 0)
             : 0;
-        // The reservation is the bound: a step whose reported usage would settle past what this reply reserved (the
-        // estimate counts a token per three bytes; a provider may report more) ends the turn with its cost unknown, which
-        // settles the whole reservation and pauses chat until the cost is confirmed — never a debit past the reservation
-        // or the session's ceiling.
         if (direct && settled + stepSettled > reserved) {
             finishStep({ state: "failed", failureReason: "over-budget", settledMicrousd: null, unknownSpend: true });
             return fail("over-reservation", LEAD_FAILURE_COPY.overReserved, true);
         }
         finishStep({ state: "answered", tokensIn: answer.tokensIn, tokensOut: answer.tokensOut, settledMicrousd: stepSettled, replyBytes: Buffer.byteLength(answer.text, "utf8"),
             cacheReadTokens: answer.cacheReadTokens ?? null, cacheWriteTokens: answer.cacheWriteTokens ?? null,
-            // v140: what the provider itself reported for this request (absent: unreported, kept NULL).
             modelReported: answer.modelReported ?? null, providerTurns: answer.providerTurns ?? null, reportedCostUsd: answer.reportedCostUsd ?? null,
             billingReported: answer.billingReported ?? null,
-            // v158: the tools this step asked for, names only (responsive-chat.md §7.2), so the next latency call is data-driven.
             tools: answer.calls.map(one => one.name) });
         tokensIn += answer.tokensIn;
         tokensOut += answer.tokensOut;
@@ -562,14 +477,9 @@ export async function runLeadTurn(input) {
             cacheRead += answer.cacheReadTokens;
         settled += stepSettled;
         lastText = answer.text;
-        // After the wait (finding 5): the row may have been failed under us by
-        // a revocation or the sweep — then nothing the model said runs; and the
-        // approver must still stand before any tool runs as them.
         const changed = guard(await revalidated());
         if (changed !== null)
             return changed;
-        // A quick step that asked for more than a read (§8): its calls are discarded unrun, and the configured model takes the
-        // reply over from the same history, for this step and every later one. Steps and the turn's deadline still bind.
         if (route === "fast" && quickStepEscalates(answer.calls)) {
             route = "escalated";
             setLeadTurnRoute(store, turnId, started.generation, route);
@@ -579,7 +489,6 @@ export async function runLeadTurn(input) {
         if (answer.calls.length === 0) {
             if (answer.text.trim() === "")
                 return fail("malformed-reply", LEAD_FAILURE_COPY.empty, false);
-            // "Here's the screenshot" with nothing attached or linked: one repair step to attach it or drop the claim; never the claim alone.
             const claim = unbacked(answer.text);
             if (claim !== null && !repaired && steps < maxSteps) {
                 repaired = true;
@@ -612,16 +521,9 @@ export async function runLeadTurn(input) {
                 if (changed !== null)
                     return changed;
             }
-            // Position within this turn is unique even if a provider reuses call ids.
             const progressId = `${turnId}:${steps}:${index}`;
             progress({ kind: "tool", turn: turnId, step: steps, id: progressId, label: leadToolLabel(call.name) });
-            // A registered tool this request did not advertise is refused before it is read or run (the only production
-            // caller of executeLeadTool): the model learns the road (find_tools, then the next step) and the reply goes on.
             const toolContext = () => ({ store, who, now: clock(), draft, selectEvidence, ...(input.replyImage === undefined ? {} : { replyImage: input.replyImage }), step: steps, readDecisions, readResults, searchedMemory, checkedCapabilities, ask, findTools, ...(input.integrations === undefined ? {} : { integrations: input.integrations }), thread: thread.id, turn: turnId, ...(promiseChannelOfTurn(input.channel) === undefined ? {} : { channel: promiseChannelOfTurn(input.channel) }), ...(input.evidenceRoot === undefined ? {} : { evidenceRoot: input.evidenceRoot }), ...(input.mediaDelivery === undefined ? {} : { mediaDelivery: input.mediaDelivery }) });
-            // propose_start (docs/plans/one-step-chat.md C3), after the advertisement gate: its input is validated first (so
-            // invalid input never reaches the classifier), then Toolroll prepares this call's own preview in this turn (up to
-            // the classifier's budget), then the person's standing and the thread are re-proved after that wait, and only then
-            // does the tool run, with the preview in this call's own context. The model's arguments never name it.
             let startPrepared;
             if (call.name === "propose_start" && advertisedNames.has(call.name)) {
                 const checked = startInputOf(toolContext(), call.args);
@@ -642,14 +544,11 @@ export async function runLeadTurn(input) {
                         ? reason : `That step didn't work (${leadToolLabel(call.name)}).` };
             }
             progress({ kind: "tool-result", turn: turnId, step: steps, id: progressId, outcome: displayOutcome });
-            // A call refused because this request did not advertise it read nothing.
             if (READ_TOOLS.has(call.name) && advertisedNames.has(call.name))
                 reads++;
             if ((call.name === "show_control" || call.name === "show_card") && outcome.ok)
                 shownControl = true;
-            // Opt-in, local diagnostics for end-to-end runs: what the lead asked of each tool and what came back (its start), keys
-            // blanked. Each line stays whole JSON so a run can assert on what a tool returned rather than on the model's words.
-            if (envValue(process.env, "LEAD_TRACE") === "1" || envValue(process.env, "MATE_TRACE") === "1") { // MATE_TRACE: the name before D5
+            if (envValue(process.env, "LEAD_TRACE") === "1" || envValue(process.env, "MATE_TRACE") === "1") {
                 const blanked = (_, value) => typeof value === "string" ? redactSecretAssignments(redactSecretLines(value, scanForSecrets(value))) : value;
                 const args = JSON.stringify(call.args, blanked).slice(0, 1500);
                 const result = JSON.stringify(outcome.ok ? outcome.body : null, blanked)?.slice(0, 2000) ?? null;
@@ -663,7 +562,6 @@ export async function runLeadTurn(input) {
         const last = lastText.trim() === "" || unbacked(lastText) === null ? lastText.trim() : dropDeliverableClaims(lastText);
         reply = `${last === "" ? "" : `${last}\n\n`}(I stopped here: this answer needed more steps than ${maxSteps < LEAD_MAX_STEPS ? "this conversation's remaining spending allows" : "one reply allows"}. Ask me to carry on.)`;
     }
-    // Ruling 11: model text is scanned before it becomes durable.
     if (scanForSecrets(reply).length > 0) {
         blockPreview();
         return fail("secret-refused", LEAD_FAILURE_COPY.secretReply, false);
@@ -671,7 +569,6 @@ export async function runLeadTurn(input) {
     now = clock();
     const routed = routeWords(route, quickModel, config.model);
     const activity = `${activitySummary(reads, proposals, steps, cacheKnown && tokensIn > 0 ? Math.min(1, cacheRead / tokensIn) : null)}${routed === null ? "" : ` · ${routed}`}`;
-    // One write (finding 12): settle, debit, promote the drafts, append the assistant text.
     const finalized = store.finalizeLeadTurn(turnId, started.generation, { state: "answered", settledMicrousd: settled, tokensIn, tokensOut, message: { text: reply, activity } }, now);
     if (!finalized)
         return { ok: false, turn: turnId, failed: "superseded", message: LEAD_FAILURE_COPY.stopped, unknownSpend: false };

package/dist/learning-child.js

@@ -1,9 +1,3 @@
-/**
- * Started only by learning-look.ts: one project's learning recovery (project-learning.ts acceptedIdentities and
- * recoverLearning) in a process of its own, so its synchronous reads of the project's Git folder can never hold the
- * console's thread. It opens the database without migrating, does that one project, and ends; the console kills it
- * at its deadline. Its one argument is JSON naming the database, the evidence folder and the project.
- */
 import { acceptedIdentities, recoverLearning } from "./project-learning.js";
 import { openStoreNoMigrate } from "./store.js";
 const input = JSON.parse(process.argv[2] ?? "null");

package/dist/learning-look.js

@@ -1,19 +1,9 @@
-/**
- * Work that reads a project's own folder synchronously, run in a process of its own and killed at a deadline, so a
- * folder that doesn't answer (a disconnected drive, an iCloud folder macOS is holding) costs that one piece of work,
- * never the console's thread: learning recovery (learning-child.ts) and Chat's first-task suggestions
- * (first-tasks-child.ts).
- */
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import {} from "./first-run.js";
-/** How long one project's recovery may take before it is stopped (the next pass tries again). */
 export const LEARNING_LOOK_MS = 60_000;
-/** How long reading one project's first-task suggestions may take. */
 export const FIRST_TASKS_LOOK_MS = 20_000;
-/** Only what git and gh need from the environment (no NODE_OPTIONS, no other secrets). */
 const CHILD_ENV = ["PATH", "HOME", "TMPDIR", "LANG", "USER", "XDG_CONFIG_HOME", "GH_TOKEN", "GITHUB_TOKEN", "GH_HOST", "GH_CONFIG_DIR"];
-/** One of this build's own child entries, given `input` as JSON, killed at the deadline. Its stdout, bounded. */
 function ownChild(name, input, deadlineMs) {
     return new Promise(resolveOutcome => {
         const source = import.meta.url.endsWith(".ts");
@@ -45,9 +35,7 @@ function ownChild(name, input, deadlineMs) {
         child.once("close", code => settle(code === 0 ? "done" : "failed"));
     });
 }
-/** The production learning runner: learning-child in its own process. */
 export const learningChild = async (input, deadlineMs) => (await ownChild("learning-child", input, deadlineMs)).outcome;
-/** Recover learning for each project in turn, each in its own bounded process. */
 export async function recoverLearningOffThread(input, options = {}) {
     const outcomes = new Map();
     for (const repo of input.repos) {
@@ -55,8 +43,6 @@ export async function recoverLearningOffThread(input, options = {}) {
     }
     return outcomes;
 }
-/** One project's first-task suggestions (first-run.ts findFirstTasks: its issues through gh, its TODOs through the
- * hardened git) read in a process of its own. Rejects when it failed or didn't answer: the caller keeps the generic ones. */
 export async function firstTasksOffThread(repo, deadlineMs = FIRST_TASKS_LOOK_MS) {
     const ran = await ownChild("first-tasks-child", { repo }, deadlineMs);
     if (ran.outcome !== "done")

package/dist/ledger-chain.js

@@ -1,21 +1,3 @@
-/**
- * v103: the action ledger as a hash chain. Every entry is sealed, in id
- * order, with a fingerprint of its own fields and the previous entry's
- * fingerprint; changing, removing or slipping in an entry breaks the chain
- * from that point, and `verifyLedgerChain` names the first place it breaks.
- *
- * The ledger itself is append-only (its triggers refuse UPDATE and DELETE);
- * the chain is what still shows it when someone with the database file drops
- * those triggers. It has no secret key: someone who can rewrite the file can
- * also drop seals and let the next pass reseal, so what proves history is a
- * checkpoint's head copied off the machine (and, from sprint 6, streamed to
- * the customer's log system), plus a running console noticing that a head it
- * already walked to has changed.
- *
- * Entries are sealed shortly after they're written (by the worker, and
- * before anything reads, verifies or exports the chain), so the triggers
- * that write the ledger stay plain SQL any build can run.
- */
 import { createHash } from "node:crypto";
 export const LEDGER_CHAIN_SCHEMA = `
 CREATE TABLE IF NOT EXISTS ledger_seal (
@@ -39,25 +21,17 @@ BEGIN SELECT RAISE(ABORT, 'ledger checkpoints are append-only'); END;
 CREATE TRIGGER IF NOT EXISTS ledger_checkpoint_no_delete BEFORE DELETE ON ledger_checkpoint
 BEGIN SELECT RAISE(ABORT, 'ledger checkpoints are append-only'); END;
 `;
-/** Where the chain starts: the previous fingerprint of the first entry. */
 export const LEDGER_GENESIS = createHash("sha256").update("standing-orders/action-ledger/v103", "utf8").digest("hex");
 const FIELDS = ["id", "at", "actor", "repo", "task_id", "run_id", "action", "outcome", "source", "detail"];
-/** A whole number column as JavaScript can hold it: one past 2^53 (only a hand edit puts one there) reads as its text,
- * which `rowProblem` names, instead of failing the read. */
 export const safeWhole = (column, as = column) => `CASE WHEN typeof(${column}) = 'integer' AND ${column} NOT BETWEEN -9007199254740991 AND 9007199254740991 THEN CAST(${column} AS TEXT) ELSE ${column} END AS ${as}`;
-/** The fields a seal covers, read safely. */
 const SEALED = FIELDS.map(name => name === "id" || name === "run_id" ? safeWhole(name) : name).join(", ");
-/** An entry's fingerprint: the previous one and the entry's own fields, in a fixed order. */
 export function entryHash(prev, row) {
     const fields = FIELDS.map(name => { const value = row[name]; return value === undefined ? null : typeof value === "bigint" ? Number(value) : value; });
     return createHash("sha256").update(`${prev}\n${JSON.stringify(fields)}`, "utf8").digest("hex");
 }
-/** The largest entry number a seal can name (JavaScript's safe integers); anything outside 1..LARGEST was put there by hand. */
 const LARGEST = Number.MAX_SAFE_INTEGER;
 export const IN_RANGE = `BETWEEN 1 AND ${LARGEST}`;
-/** Outside it, written so SQLite finds such rows by key rather than reading every row. */
 const OUTSIDE = (column) => `${column} < 1 OR ${column} > ${LARGEST}`;
-/** Why a row can't be an entry the ledger wrote: each field is exactly the kind of value its writers store. */
 export function rowProblem(row) {
     const whole = (value) => typeof value === "number" && Number.isSafeInteger(value);
     const text = (value) => typeof value === "string";
@@ -73,7 +47,6 @@ export function rowProblem(row) {
             return `a ${name} the ledger never writes`;
     return null;
 }
-/** Seal every entry written since the last seal, in id order. Returns how many were sealed. Call inside a write transaction. */
 export function sealLedger(db) {
     const last = db.prepare(`SELECT id, hash FROM ledger_seal WHERE id ${IN_RANGE} ORDER BY id DESC LIMIT 1`).get();
     let prevId = last === undefined ? 0 : Number(last["id"]);
@@ -95,7 +68,6 @@ export function sealLedger(db) {
     }
 }
 const PAGE = 1000;
-/** Rows of a keyset query (`WHERE id > ? ... ORDER BY id LIMIT n`), a page at a time. */
 function* pages(db, sql, from) {
     const statement = db.prepare(sql);
     let after = from;
@@ -107,13 +79,9 @@ function* pages(db, sql, from) {
         after = Number(page[page.length - 1]["id"]);
     }
 }
-/** Walk the chain: every entry sealed, every seal an entry, each fingerprint right and linked to the one before,
- * and every checkpoint still matching. With `from`, the walk starts at a head verified earlier, after checking that
- * the head is still there (a chain rebuilt since doesn't match it). Reads only; call inside one read transaction. */
 export function verifyLedgerChain(db, from, checkedAt = null) {
     let prev = from?.head ?? LEDGER_GENESIS, entries = from?.entries ?? 0, through = from?.through ?? null, kept = 0;
     const report = (problem, unsealed = 0) => ({ ok: problem === null, entries, through, head: prev, unsealed, checkpoints: kept, problem, checkedAt });
-    // Entries, seals and checkpoints are numbered from 1 up to what a seal can name; anything outside was put there by hand.
     const outside = db.prepare(`SELECT CAST(id AS TEXT) AS id FROM action_ledger WHERE ${OUTSIDE("id")} LIMIT 1`).get();
     if (outside !== undefined)
         return report({ id: null, what: `entry #${String(outside["id"])} was added outside the sealed history` });
@@ -159,7 +127,6 @@ export function verifyLedgerChain(db, from, checkedAt = null) {
         entries++;
         row = rows.next();
     }
-    // Every checkpoint row, each on its own: a later row for the same entry can't cover for an earlier one.
     const sealedAt = db.prepare("SELECT hash FROM ledger_seal WHERE id = ?");
     for (const checkpoint of checkpoints) {
         const walked = reached.get(checkpoint.through) ?? (from !== undefined && checkpoint.through <= from.through ? sealedAt.get(checkpoint.through)?.["hash"] : undefined);
@@ -171,7 +138,6 @@ export function verifyLedgerChain(db, from, checkedAt = null) {
         unsealed++;
     return report(null, unsealed);
 }
-/** Whether the chain still ends at a head someone copied off the machine (`<through>:<hash>`). */
 export function matchesOutsideCheckpoint(db, checkpoint) {
     const match = /^(\d+):([a-f0-9]{64})$/.exec(checkpoint.trim());
     if (match === null)

package/dist/ledger-csv.js

@@ -1,5 +1,3 @@
-// Quotes and CR/LF survive a CSV round trip. Prefix spreadsheet formulas
-// with an apostrophe, including formulas hidden behind whitespace.
 export function csvCell(value) {
     const raw = value === null ? "" : String(value);
     const safe = /^[\s\uFEFF]*[=+@-]/u.test(raw) || /^[\t\r\n]/u.test(raw) ? "'" + raw : raw;

package/dist/ledger-view.js

@@ -2,7 +2,6 @@ import { projectName } from "./project.js";
 import { exactWhenHtml } from "./when-html.js";
 import { html, postForm } from "./html.js";
 import { acts, btn, disclose, empty, infoLine, note, notice, pageHeader, select } from "./server/kit.js";
-/** The ledger's kinds of event, as the filter names them. */
 const EVENT_KINDS = [["work", "Work"], ["request", "Requests"], ["access", "Access"], ["sign-in", "Sign-ins"], ["policy", "Policy changes"]];
 function chainHtml(chain) {
     const status = chain.ok
@@ -17,8 +16,6 @@ function chainHtml(chain) {
 <div class="k-acts">${btn("Download", { sm: true, type: "submit" })}</div></form>${note("Every entry in the range with its seal, and a full record for each task it names. JSON.")}`);
     return html `<section class="h-chain" aria-label="Audit log integrity">${status}${latest}${make}${exportForm}</section>`;
 }
-/** The audit log (`/ledger`): what people and tokens did, newest first, as quiet timed rows, with the filters, the CSV
- * and the sealed export. A kit list page: the top bar, then rows between hairlines. */
 export function ledgerBody(rows, projects, params, chain) {
     const more = rows.length > 50;
     const shown = rows.slice(0, 50);