toolroll 0.9.63 → 0.9.65

package/dist/lead.js

@@ -4,11 +4,11 @@ import { createHash } from "node:crypto";
 import { leadTimeoutNotice } from "./store.js";
 import { RESULT_IMAGES_PER_TURN_CAP } from "./chat-evidence.js";
 import { isVerifiedApprover, reproveApprover } from "./principal.js";
-import { LEAD_MAX_CALLS_PER_STEP, LEAD_MAX_STEPS, LEAD_TOOL_RESULT_CAP_BYTES, TURN_WALL_CLOCK_MS, composeLeadRequest, credentialKeyOf, isDirectChatProvider, leadWorstCaseForPrice, performLeadRequest, priceForConfig, settleForPrice, subscriptionCredentialKey, } from "./converse.js";
+import { LEAD_MAX_CALLS_PER_STEP, LEAD_MAX_STEPS, LEAD_TOOL_RESULT_CAP_BYTES, TURN_WALL_CLOCK_MS, composeLeadRequest, credentialKeyOf, isDirectChatProvider, leadWorstCaseForPrice, performLeadRequest, priceForConfig, cacheWorstPrice, settleWithCache, subscriptionCredentialKey, } from "./converse.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { redactSecretAssignments } from "./builder.js";
 import { LEAD_CONTRACT } from "./lead-contract.js";
-import { LEAD_MAX_PROPOSALS_PER_TURN, LEAD_TOOL_SCHEMAS, executeLeadTool, isLeadTool, leadViewContextFor, projectLabelForLead, redactForLead, toolResultBytes } from "./lead-tools.js";
+import { LEAD_CORE_TOOLS, LEAD_MAX_PROPOSALS_PER_TURN, LEAD_TOOL_SCHEMAS, executeLeadTool, isLeadTool, leadViewContextFor, projectLabelForLead, redactForLead, toolResultBytes } from "./lead-tools.js";
 import { composeSubscriptionLeadPrompt, performSubscriptionLeadRequest } from "./subscription-chat.js";
 import { LEAD_REPLY_LIMITS, leadContext } from './lead-context.js';
 import { shortenAsk } from './text-limits.js';
@@ -34,6 +34,7 @@ export const LEAD_REFUSAL_COPY = {
     "thread-closed": "This conversation is closed. Start a new one to keep going.",
     latched: "An earlier reply stopped before its cost was known, so chat is paused. Acknowledge that reply on the Chat page, then send again.",
     concurrent: "The lead is still answering your last message. Wait for that reply, then send this one.",
+    backlog: "Your earlier messages are still waiting for the lead. This one goes after them.",
     "daily-cap": "You've reached today's limit on chat replies, so this one wasn't sent. Try again tomorrow.",
     "session-exhausted": "This chat has used its spending limit. Start a new chat to keep going.",
     "session-ended": "This chat has ended. Start a new chat to keep going.",
@@ -69,12 +70,25 @@ export const LEAD_FAILURE_COPY = {
     tooLongUnknownCost: leadTimeoutNotice(false, true),
     lostUnknownCost: "The chat provider stopped responding partway through, and the cost isn't known, so chat is paused. Nothing it proposed was kept. Confirm the cost on the Chat page to turn chat back on.",
     unreadableUnknownCost: "The chat provider sent back an answer that couldn't be read, and its cost isn't known, so chat is paused. Nothing it proposed was kept. Confirm the cost on the Chat page to turn chat back on.",
+    overReserved: "This reply reported more use than was set aside for it, so its cost is counted as unknown and chat is paused. Nothing it proposed was kept. Confirm the cost on the Chat page to turn chat back on.",
     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). */
-export function leadFailureText(reason) {
+export function leadFailureText(reason, unknownSpend = false) {
+    // 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.`;
+    }
     switch (reason) {
+        case "over-reservation": return "This reply reported more use than was set aside for it, so it was stopped and its cost counted. Send your message again.";
         case "timeout":
         case "crashed": return LEAD_FAILURE_COPY.tooLong;
         case "malformed-reply": return LEAD_FAILURE_COPY.unreadable;
@@ -98,20 +112,22 @@ function settleBy(work, ms) {
 }
 const READ_TOOLS = new Set(["get_brief", "get_project_context", "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_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) {
-    const rows = store.listLeadMessages(thread, LEAD_HISTORY_MAX_MESSAGES);
+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];
-        // Other teammates may have already queued later messages. They do not
-        // enter model history until admitted, and the current message appears once.
-        if (queuedMessageId !== undefined && (row.id === queuedMessageId || row.role === 'operator' && row.turn === null))
+        // 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");
         if (bytes > LEAD_HISTORY_CAP_BYTES)
             break;
-        const author = queuedMessageId !== undefined && row.role === 'operator' && row.turn !== null ? store.getLeadTurn(row.turn)?.approver : undefined;
+        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.
@@ -120,8 +136,9 @@ export function historyFor(store, thread, queuedMessageId) {
     return kept;
 }
 /** "read 3 · proposed 1 · 2 steps" — counts only, never results (ruling 11). */
-export function activitySummary(reads, proposals, steps) {
-    return [`read ${reads}`, `proposed ${proposals}`, `${steps} step${steps === 1 ? "" : "s"}`].join(" · ");
+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) {
@@ -175,7 +192,12 @@ export async function runLeadTurn(input) {
     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");
-    if (input.queuedMessageId !== undefined && (!sharedThread || !Number.isSafeInteger(input.queuedMessageId) || input.onAdmitted === undefined))
+    // 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;
+    if (input.queuedMessageId !== undefined && ((!sharedThread && !personalQueued) || !Number.isSafeInteger(input.queuedMessageId) || input.onAdmitted === undefined))
         return refuse('invalid-request');
     if (liveSession.endedAt !== null)
         return refuse("session-ended");
@@ -197,18 +219,29 @@ export async function runLeadTurn(input) {
     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 }) });
-    const authoredMessage = input.queuedMessageId === undefined ? message : `From ${who.name}:\n${message}`;
+    // 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), { role: "operator", text: historyMessage }];
-    const composeDirect = (key) => {
+    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)),
+        ...[...findTools.found].map(name => LEAD_TOOL_SCHEMAS.find(one => one.name === name)).filter((one) => one !== undefined),
+    ];
+    const composeDirect = (key, tools) => {
         if (!direct)
             throw new Error("not a direct chat provider");
-        return composeLeadRequest({ provider: directProvider, model: config.model, key, system: LEAD_CONTRACT, dataDocument: document, history, tools: LEAD_TOOL_SCHEMAS });
+        // 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 = () => composeSubscriptionLeadPrompt({ system: LEAD_CONTRACT, dataDocument: document, history, tools: LEAD_TOOL_SCHEMAS });
-    // The exact outbound base is scanned whole. Only direct API traffic needs
-    // a worst-case dollar reservation; subscription traffic records zero.
-    const base = direct ? composeDirect("").body : composeSubscription();
+    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.
@@ -216,7 +249,9 @@ export async function runLeadTurn(input) {
     // Each chosen step retains the same worst-case call/output accounting.
     let maxSteps = LEAD_MAX_STEPS;
     const baseBytes = Buffer.byteLength(base, "utf8");
-    const reserveFor = (steps) => direct ? leadWorstCaseForPrice(price, baseBytes, { steps }) : 0;
+    // 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) {
         const remaining = Math.min(liveSession.ceilingMicrousd - liveSession.spentMicrousd, config.weeklyCeilingMicrousd - store.chatWeeklySpendMicrousd(credentialKey, now));
         while (maxSteps > 1 && reserveFor(maxSteps) > remaining)
@@ -239,6 +274,7 @@ export async function runLeadTurn(input) {
             weeklyCeilingMicrousd: config.weeklyCeilingMicrousd,
             deadlineMs: TURN_WALL_CLOCK_MS + 10_000,
             provider: config.provider,
+            ...(input.queueClaim === undefined ? {} : { queueClaim: input.queueClaim }),
         }, now);
         if (!opened.ok)
             return opened;
@@ -249,7 +285,8 @@ export async function runLeadTurn(input) {
         if (input.queuedMessageId === undefined)
             store.appendLeadMessage({ thread: thread.id, turn: turnId, role: "operator", text: message }, now);
         else {
-            const bound = store.handle.prepare("UPDATE lead_message SET turn=? WHERE id=? AND thread=? AND role='operator' AND turn IS NULL AND text=?")
+            // 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)
                 throw new Error('The queued message changed before admission.');
@@ -281,6 +318,8 @@ export async function runLeadTurn(input) {
     /** 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;
     const draft = (kind, payload) => {
@@ -363,7 +402,10 @@ export async function runLeadTurn(input) {
         const remainingMs = TURN_WALL_CLOCK_MS - (now.getTime() - turnStartedAt);
         if (remainingMs <= 0)
             return timedOut(false);
-        const request = direct ? composeDirect(input.key) : composeSubscription();
+        // This request's advertised tools: fixed for the request; a tool found in its reply is advertised from the next one.
+        const advertised = 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) {
@@ -402,7 +444,7 @@ export async function runLeadTurn(input) {
                 system: LEAD_CONTRACT,
                 dataDocument: document,
                 history,
-                tools: LEAD_TOOL_SCHEMAS,
+                tools: advertised,
                 timeoutMs: remainingMs,
                 signal: controller.signal,
                 // The reply as it is written; text that looks like a secret is
@@ -452,11 +494,24 @@ export async function runLeadTurn(input) {
         }
         // The pinned math, or the provider's own reported charge when HIGHER.
         const stepSettled = direct
-            ? Math.max(settleForPrice(price, answer.tokensIn, answer.tokensOut), answer.reportedCostMicrousd ?? 0)
+            ? Math.max(settleWithCache(price, answer), answer.reportedCostMicrousd ?? 0)
             : 0;
-        finishStep({ state: "answered", tokensIn: answer.tokensIn, tokensOut: answer.tokensOut, settledMicrousd: stepSettled, replyBytes: Buffer.byteLength(answer.text, "utf8") });
+        // 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 });
         tokensIn += answer.tokensIn;
         tokensOut += answer.tokensOut;
+        if (answer.cacheReadTokens === undefined)
+            cacheKnown = false;
+        else
+            cacheRead += answer.cacheReadTokens;
         settled += stepSettled;
         lastText = answer.text;
         // After the wait (finding 5): the row may have been failed under us by
@@ -502,7 +557,11 @@ export async function runLeadTurn(input) {
             // 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) });
-            const outcome = executeLeadTool({ store, who, now: clock(), draft, selectEvidence, step: steps, readDecisions, readResults, searchedMemory, checkedCapabilities, ask, ...(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 }) }, call.name, call.args, view);
+            // 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 outcome = !advertisedNames.has(call.name)
+                ? { ok: false, message: `${call.name} isn't available in this step. Call find_tools with what you want to do; tools it finds can be called from your next step.` }
+                : executeLeadTool({ store, who, now: clock(), draft, selectEvidence, 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 }) }, call.name, call.args, view);
             let displayOutcome = { state: "succeeded" };
             if (!outcome.ok) {
                 const reason = leadToolFailureReason(call.name, outcome.message);
@@ -510,7 +569,8 @@ 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 });
-            if (READ_TOOLS.has(call.name))
+            // 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" && outcome.ok)
                 shownControl = true;
@@ -534,7 +594,7 @@ export async function runLeadTurn(input) {
     if (scanForSecrets(reply).length > 0)
         return fail("secret-refused", LEAD_FAILURE_COPY.secretReply, false);
     now = clock();
-    const activity = activitySummary(reads, proposals, steps);
+    const activity = activitySummary(reads, proposals, steps, cacheKnown && tokensIn > 0 ? Math.min(1, cacheRead / tokensIn) : null);
     // 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)

package/dist/limits-ui.d.ts

@@ -4,7 +4,7 @@
  * costs nothing per run, so its windows are what bind it; budgets bind work
  * billed to an API key. An instance operator's view.
  */
-import type { BrowserLimits } from "./browser-workspace.js";
+import type { BrowserLimits, BrowserUsageChip } from "./browser-workspace.js";
 import { type BudgetState } from "./spend.js";
 import { type Html } from "./html.js";
 /** "in 25 min", "in 2 h 10 min", or a day and hour ("Fri 11 PM") beyond a day. */
@@ -22,6 +22,13 @@ export declare function limitsView(windows: readonly {
     project: (repo: string) => string;
     subagent: (id: number) => string;
 }, now: Date): BrowserLimits | null;
+/**
+ * The usage chip (cockpit §3, R16): the subscription window with the highest use the providers last reported, as
+ * "Claude 5-hour · 82% · resets 3h". A reading older than 30 minutes stays visibly stale ("as of 2h ago"), judged by
+ * the reading's age as the Limits view judges it; a window with no known reset says "resets: unknown". API-key budgets
+ * are not compared here (they stay in the details). An operator's view, as the Limits view is. Null: nothing reported.
+ */
+export declare function usageChipOf(windows: Parameters<typeof limitsView>[0], now: Date): BrowserUsageChip | null;
 /** The same tiles for the page without scripts. */
 export declare function limitsHtml(limits: BrowserLimits | null): Html;
 export declare const LIMITS_CSS: string;

package/dist/limits-ui.js

@@ -48,6 +48,32 @@ export function limitsView(windows, budgets, names, now) {
     }
     return tiles.length === 0 ? null : { tiles };
 }
+/** One short reset: "3h", "25 min", or "Fri 11 PM". */
+const shortReset = (resetsAt, now) => {
+    const minutes = Math.max(1, Math.round((Date.parse(resetsAt) - now.getTime()) / 60_000));
+    return minutes < 60 ? `${minutes} min` : minutes < 24 * 60 ? `${Math.round(minutes / 60)}h` : resetWords(resetsAt, now);
+};
+/**
+ * The usage chip (cockpit §3, R16): the subscription window with the highest use the providers last reported, as
+ * "Claude 5-hour · 82% · resets 3h". A reading older than 30 minutes stays visibly stale ("as of 2h ago"), judged by
+ * the reading's age as the Limits view judges it; a window with no known reset says "resets: unknown". API-key budgets
+ * are not compared here (they stay in the details). An operator's view, as the Limits view is. Null: nothing reported.
+ */
+export function usageChipOf(windows, now) {
+    // A window whose reset has passed since its reading is not measured again yet: it ranks below every current one, and
+    // shows what was last read, as stale — never an inferred 0%.
+    const expired = (one) => one.resetsAt !== null && Date.parse(one.resetsAt) <= now.getTime();
+    const rank = (one) => (expired(one) ? -1_000 : 0) + one.usedPercent + (one.reached && !expired(one) ? 1_000 : 0);
+    const top = [...windows].sort((a, b) => rank(b) - rank(a))[0];
+    if (top === undefined)
+        return null;
+    const old = expired(top);
+    const stale = old || now.getTime() - Date.parse(top.observedAt) > 30 * 60_000;
+    // A window with no known length or reset has no reset to name.
+    const reset = old ? "window reset" : top.resetsAt === null || top.windowMinutes === null ? "resets: unknown" : `resets ${shortReset(top.resetsAt, now)}`;
+    const text = `${PROVIDER_NAMES[top.provider] ?? top.provider} ${windowLabel(top.window, top.windowMinutes)} · ${Math.round(top.usedPercent)}% · ${reset}${stale ? ` · as of ${ago(top.observedAt, now)}` : ""}`;
+    return { text, tone: old ? "neutral" : toneOf(top.usedPercent, top.reached), stale, href: "/work", title: `What the providers last reported: ${text}` };
+}
 /** The same tiles for the page without scripts. */
 export function limitsHtml(limits) {
     if (limits === null)

package/dist/live-bus.d.ts

@@ -85,6 +85,7 @@ export declare class LiveConnection {
     private readonly proofs;
     private readonly timer;
     private closed;
+    private refusing;
     constructor(response: ServerResponse, options?: {
         limitBytes?: number;
         keepAliveMs?: number;
@@ -95,6 +96,10 @@ export declare class LiveConnection {
     get open(): boolean;
     /** An event for one room: its data says which. */
     send(room: string, event: string, data?: Record<string, unknown>): void;
+    /** A room leaves because its proof failed (a sign-out, a revoked or narrowed account): if that departure ends the
+     * connection, the page is told the stream `ended` and stops, rather than reconnecting at once into a request that
+     * can't sign in. Any other close — the page going, a later shutdown, an overflow — says nothing of it. */
+    refuse(leave: () => void): void;
     /** Run when the connection ends; returns the undo for a room that leaves first. */
     onClose(leave: () => void): () => void;
     close(): void;
@@ -120,6 +125,9 @@ export type LiveRoomOptions = {
     bus?: LiveBus | null;
     safetyNetMs?: number;
     minIntervalMs?: number;
+    /** A room whose read is costly reads at most once per this window after a signal; every viewer is still re-proved
+     * the moment a signal arrives (and again at the read). */
+    readSettleMs?: number;
 };
 /**
  * Rooms of open pages that hear the bus. `presence` says who else is here, as

package/dist/live-bus.js

@@ -201,6 +201,7 @@ export class LiveConnection {
     proofs = new Set();
     timer;
     closed = false;
+    refusing = false;
     constructor(response, options = {}) {
         this.response = response;
         this.stream = new LiveStream(response, options.limitBytes, () => this.close());
@@ -222,6 +223,19 @@ export class LiveConnection {
     get open() { return !this.closed && this.stream.open; }
     /** An event for one room: its data says which. */
     send(room, event, data = {}) { this.stream.send(event, { room, ...data }); }
+    /** A room leaves because its proof failed (a sign-out, a revoked or narrowed account): if that departure ends the
+     * connection, the page is told the stream `ended` and stops, rather than reconnecting at once into a request that
+     * can't sign in. Any other close — the page going, a later shutdown, an overflow — says nothing of it. */
+    refuse(leave) {
+        const outer = this.refusing;
+        this.refusing = true;
+        try {
+            leave();
+        }
+        finally {
+            this.refusing = outer;
+        }
+    }
     /** Run when the connection ends; returns the undo for a room that leaves first. */
     onClose(leave) { this.leaves.add(leave); return () => { this.leaves.delete(leave); }; }
     close() {
@@ -233,6 +247,10 @@ export class LiveConnection {
             leave();
         this.leaves.clear();
         this.proofs.clear();
+        if (this.refusing && this.stream.open) {
+            this.response.end("event: ended\ndata: {}\n\n");
+            return;
+        }
         if (!this.response.writableEnded)
             this.response.end();
     }
@@ -251,6 +269,7 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
     const bus = options.bus ?? null;
     const safetyNetMs = options.safetyNetMs ?? SAFETY_NET_MS;
     const minIntervalMs = options.minIntervalMs ?? 0;
+    const readSettleMs = options.readSettleMs ?? 0;
     const rooms = new Map();
     let unsubscribe = null;
     const announce = (key, room) => {
@@ -287,6 +306,8 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
             clearTimeout(room.retry);
         if (room.holding !== null)
             clearTimeout(room.holding);
+        if (room.reading !== null)
+            clearTimeout(room.reading);
         rooms.delete(key);
         if (rooms.size === 0 && unsubscribe !== null) {
             unsubscribe();
@@ -312,7 +333,10 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
                 viewer.connection.send(viewer.room, "gone");
             }
             finally {
-                leave(key, viewer);
+                if (valid)
+                    leave(key, viewer);
+                else
+                    viewer.connection.refuse(() => leave(key, viewer));
             }
             return false;
         }
@@ -366,8 +390,20 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
             deliver(key, room, viewer, "change", { at: room.last, revision: room.revision });
     };
     const heard = (change) => {
-        for (const [key, room] of [...rooms])
-            refresh(key, room, change.revision);
+        for (const [key, room] of [...rooms]) {
+            if (readSettleMs <= 0) {
+                refresh(key, room, change.revision);
+                continue;
+            }
+            // Re-prove now; read once the burst settles.
+            for (const viewer of [...room.viewers.keys()])
+                deliver(key, room, viewer);
+            if (rooms.get(key) !== room || room.reading !== null)
+                continue;
+            room.reading = setTimeout(() => { room.reading = null; if (rooms.get(key) === room)
+                refresh(key, room, null); }, readSettleMs);
+            room.reading.unref();
+        }
     };
     return {
         join(key, viewer) {
@@ -378,7 +414,7 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
                     last = fingerprint(key);
                 }
                 catch { /* the next signal or the safety net reads it */ }
-                const created = { viewers: new Map(), last, timer: setInterval(() => refresh(key, created, null), safetyNetMs), settling: null, retry: null, saidAt: 0, holding: null, revision: null };
+                const created = { viewers: new Map(), last, timer: setInterval(() => refresh(key, created, null), safetyNetMs), settling: null, retry: null, saidAt: 0, holding: null, revision: null, reading: null };
                 created.timer.unref();
                 room = created;
                 rooms.set(key, room);

package/dist/live-detail.d.ts

@@ -0,0 +1,27 @@
+import type { Store } from "./store.js";
+/** The consent a "Show commands" form carries: a single-use nonce minted for this person and these exact terms. */
+export declare const LIVE_VIEW_CONSENT = "live-view";
+export declare function liveViewConsentDigest(repo: string): string;
+export type LiveDetailSetting = {
+    repo: string;
+    commands: boolean;
+    updatedBy: string;
+    updatedAt: string;
+};
+/** Whether this project's live conversations show commands. Unknown or absent is off. */
+export declare function liveCommandsShown(store: Store, repo: string | null): boolean;
+export declare function liveDetailSetting(store: Store, repo: string): LiveDetailSetting | null;
+/** Save the setting and its ledger line in one transaction. The caller has proved who is asking (and, to turn it on, their password). */
+export declare function setLiveCommands(store: Store, change: {
+    repo: string;
+    commands: boolean;
+    by: string;
+    via: string;
+}, now: Date): {
+    said: string;
+};
+/** A run's trusted context for its live file: its own checkout, and its project's setting, read now. */
+export declare function liveLogContext(store: Store, taskRef: number, worktree: string | null): {
+    base: string | null;
+    commands: boolean;
+};

package/dist/live-detail.js

@@ -0,0 +1,57 @@
+/**
+ * A project's "Show commands in the live view" (docs/plans/live-conversation.md):
+ * whether a running agent's command text and command output are written to
+ * its live conversation. Off unless an approver turned it on for the
+ * project with their password; turning it off is one step. Every change is
+ * an action-ledger line.
+ *
+ * The writer reads it once, when it opens a run's live file: what is off
+ * never reaches disk, and a change applies from the next run.
+ */
+import { createHash } from "node:crypto";
+/** The consent a "Show commands" form carries: a single-use nonce minted for this person and these exact terms. */
+export const LIVE_VIEW_CONSENT = "live-view";
+export function liveViewConsentDigest(repo) {
+    return createHash("sha256").update(JSON.stringify(["live-view", repo, "commands-on"])).digest("hex");
+}
+/** Whether this project's live conversations show commands. Unknown or absent is off. */
+export function liveCommandsShown(store, repo) {
+    if (repo === null)
+        return false;
+    try {
+        const row = store.handle.prepare("SELECT commands FROM live_detail_setting WHERE repo = ?").get(repo);
+        return row !== undefined && Number(row["commands"]) === 1;
+    }
+    catch {
+        return false;
+    }
+}
+export function liveDetailSetting(store, repo) {
+    const row = store.handle.prepare("SELECT repo, commands, updated_by, updated_at FROM live_detail_setting WHERE repo = ?").get(repo);
+    if (row === undefined)
+        return null;
+    return { repo: String(row["repo"]), commands: Number(row["commands"]) === 1, updatedBy: String(row["updated_by"]), updatedAt: String(row["updated_at"]) };
+}
+/** Save the setting and its ledger line in one transaction. The caller has proved who is asking (and, to turn it on, their password). */
+export function setLiveCommands(store, change, now) {
+    store.transact(() => {
+        store.handle
+            .prepare(`INSERT INTO live_detail_setting (repo, commands, updated_by, updated_at) VALUES (?,?,?,?)
+        ON CONFLICT (repo) DO UPDATE SET commands = excluded.commands, updated_by = excluded.updated_by, updated_at = excluded.updated_at`)
+            .run(change.repo, change.commands ? 1 : 0, change.by, now.toISOString());
+        store.recordAction({ at: now.toISOString(), actor: change.by, repo: change.repo, taskId: null, runId: null,
+            action: "live view commands", outcome: change.commands ? "on" : "off", source: "request", detail: `via ${change.via}` });
+    });
+    return { said: change.commands ? "Commands now show in the live view for this project, from the next run." : "Commands are hidden in the live view for this project, from the next run." };
+}
+/** A run's trusted context for its live file: its own checkout, and its project's setting, read now. */
+export function liveLogContext(store, taskRef, worktree) {
+    let repo = null;
+    try {
+        repo = store.refForId(taskRef)?.repo ?? null;
+    }
+    catch {
+        repo = null;
+    }
+    return { base: worktree, commands: liveCommandsShown(store, repo) };
+}

package/dist/live-notes.d.ts

@@ -0,0 +1,20 @@
+import type { Store } from "./store.js";
+export declare const RUN_NOTES_SHOWN = 20;
+export type RunNote = {
+    id: number;
+    author: string;
+    /** Whether the person looking wrote it: only then does the view say "You". */
+    mine: boolean;
+    at: string;
+    text: string;
+    standing: string;
+    readAt: string | null;
+};
+/** This run's notes, oldest first: the newest RUN_NOTES_SHOWN, and how many older ones the task page keeps. */
+export declare function runNotes(store: Store, run: {
+    id: number;
+    taskRef: number;
+}, viewer: string, now: Date): {
+    notes: RunNote[];
+    older: number;
+};

package/dist/live-notes.js

@@ -0,0 +1,47 @@
+/**
+ * The steering notes that belong in one run's live conversation
+ * (docs/plans/live-conversation.md §5): every note this run reached —
+ * attached to its brief, mailed into its folder, or read by it, as kept in
+ * steer_note_run when it happened — and, only while this run is the task's
+ * live build, notes still waiting for it. A note never shows on a run it did
+ * not reach, and is credited as read only to the run that read it.
+ */
+import { steerStandingParts } from "./steer-status.js";
+export const RUN_NOTES_SHOWN = 20;
+/** Where a note stands as seen from this run. */
+function standingFor(note, run, live) {
+    if (note.authorshipState === "verified" && note.supersededAt === null && note.deliveredAt === null && !live) {
+        // This run ended (or is not the one reading notes) without reading it: it waits for the next attempt.
+        return { standing: "Not read in this attempt — the next one gets it", readAt: null };
+    }
+    // Once read, a note's attached run is the run that read it (ackSteerNote, settleSteerDelivered).
+    if (note.deliveredAt !== null && note.attachedRun !== run)
+        return { standing: "Read in another attempt", readAt: null };
+    const { words, readAt } = steerStandingParts(note, live);
+    return { standing: words, readAt };
+}
+/** This run's notes, oldest first: the newest RUN_NOTES_SHOWN, and how many older ones the task page keeps. */
+export function runNotes(store, run, viewer, now) {
+    const live = store.steeringLiveBuild(run.taskRef, now) === run.id;
+    const reached = new Map(store.steerNotesReaching(run.id).filter(note => note.taskRef === run.taskRef).map(note => [note.id, note]));
+    if (live) {
+        for (const note of store.listSteerNotes(run.taskRef)) {
+            const waiting = note.authorshipState === "verified" && note.deliveredAt === null && note.supersededAt === null;
+            if (waiting && !reached.has(note.id))
+                reached.set(note.id, note);
+        }
+    }
+    const all = [...reached.values()].sort((a, b) => a.id - b.id);
+    const shown = all.slice(-RUN_NOTES_SHOWN);
+    return {
+        older: all.length - shown.length,
+        notes: shown.map(note => ({
+            id: note.id,
+            author: note.author,
+            mine: note.author === viewer,
+            at: note.createdAt,
+            text: note.note,
+            ...standingFor(note, run.id, live),
+        })),
+    };
+}