toolroll 0.9.62 → 0.9.65

package/dist/lead-tools.js

@@ -1,3 +1,4 @@
+import { sweepLine, sweepTable } from "./lead-sweep.js";
 import { TEXT_LIMITS } from "./text-limits.js";
 import { connectionsOf, oneClickOf } from "./mcp-connect.js";
 import { checkLevelFromWords, isCheckLevel } from "./check-levels.js";
@@ -44,11 +45,12 @@ import { diagnoseTaskDispatch, withDispatchDiagnoses } from "./dispatch.js";
 import { agentChoicesFor, routeOfTask, INSTALLATION_SCOPE } from "./agentconfig.js";
 import { isNewModel, modelWords, priceWords, runtimeStates, seenModels } from "./model-catalog.js";
 import { agentsSummary, chosenWords, PHASES, postureWords, routeProblems, sameSpec, sizeSourceWords, sizeWords, specWords } from "./phase-routing.js";
-import { TOOL_CATALOG, discoverTools, projectToolsOf, secretsSetFor, toolCommandLine, toolStanding } from "./project-tools.js";
+import { TOOL_CATALOG, credentialModeOf, discoverTools, projectToolsOf, secretsSetFor, toolCommandLine, toolSecretStorage, toolStanding } from "./project-tools.js";
 import { deciderOf, durationWords, FLOW_KIND_WORDS, FLOW_TEMPLATES, flowFromSteps, stepsFor, withKeptSteps } from "./flows.js";
 import { parseContract, toModelSchema } from "./contracts/contract.js";
 import { LEAD_TOOL_INPUTS, LEAD_TOOL_READ_INPUTS, LEAD_TOOL_OPTIONS, LEAD_TOOL_OUTPUTS, reportToolOutput } from "./contracts/lead-tools.js";
 import { flowCardHref, flowDefinitionOf } from "./flow-engine.js";
+import { activeUnattendedGrant } from "./flow-unattended.js";
 import { planInChat } from "./chat-decide.js";
 import { flowDecisionAt } from "./telegram-flow.js";
 import { flowPersonOf } from "./flow-send.js";
@@ -371,7 +373,102 @@ export function agentsOver(store, taskId, now) {
         choices: Object.fromEntries(PHASES.filter(phase => phase !== "review").map(phase => [ROLE_WORD[phase], choices[phase].filter(one => one.selectable).map(one => ({ provider: one.provider, model: one.model, current: one.current }))])),
     };
 }
+/**
+ * The tools every request advertises (docs/plans/lead-deferred-tools.md): the ones most replies use, and every tool a
+ * guard requires read in an earlier step (search_project_memory before any proposal, get_capabilities before work that
+ * needs an agent, get_result before propose_review, get_decision before propose_answer). The rest are found with
+ * find_tools and advertised from the next request of the same reply.
+ */
+export const LEAD_CORE_TOOLS = new Set([
+    "find_tools", "get_brief", "recap", "list_repos", "get_project_context", "search_project_memory", "get_capabilities",
+    "list_tasks", "get_task", "get_result", "get_diff", "get_check_log", "list_decisions", "get_decision",
+    "get_actions", "get_action_status", "propose_action", "propose_task", "propose_scope", "propose_steer",
+    "propose_answer", "propose_review", "remember", "ask_owner", "commit_to",
+    // The lead's queue verbs: basic, and small enough that deferring them saves almost nothing.
+    "queue", "propose_next", "propose_reserve", "propose_hold", "propose_unhold", "propose_cancel",
+    // Task and result acts a reply uses often (links to a control, a result's images and evidence, the task's own acts):
+    // small, so deferral is kept for the large, occasional families (flows, subagents, sweeps, project tools).
+    "show_control", "get_controls", "get_result_images", "get_acceptance_evidence", "offer_approval", "propose_task_action", "propose_agents",
+    "get_agents", "propose_dependency_repair",
+]);
+/** Words a deferred tool is found by, beyond its name and description. */
+const LEAD_TOOL_KEYWORDS = {
+    propose_flow: ["flow", "automation", "workflow", "schedule", "trigger", "every", "when", "email", "inbox", "sort", "follow-up", "nudge"],
+    get_flows: ["flow", "automation", "workflow", "running", "card"],
+    get_flow_insights: ["flow", "insights", "stats", "how flows"],
+    propose_subagent: ["subagent", "assistant", "rep", "support", "sales", "teammate", "rules", "persona"],
+    get_subagents: ["subagent", "assistant", "teammate", "rules"],
+    propose_sweep: ["sweep", "fan-out", "many", "parallel", "batch", "each", "list of"],
+    get_sweep: ["sweep", "fan-out", "batch", "table", "verdict"],
+    propose_sweep_cancel: ["sweep", "cancel", "stop the rest"],
+    get_models: ["model", "models", "provider", "price"],
+    get_project_tools: ["tools", "mcp", "server", "integration", "connect", "stripe", "notion", "linear", "sentry", "jira"],
+    get_integrations: ["integration", "slack", "telegram", "discord", "teams", "email", "connected"],
+    get_skills: ["skill", "skills", "guide"],
+    get_project_knowledge: ["knowledge", "docs", "notes", "memory"],
+    get_task_conversation: ["conversation", "chat", "history", "messages"],
+    release_commitment: ["promise", "commitment", "release", "forget"],
+    get_person: ["person", "people", "who", "member", "teammate"],
+};
+/** At most this many find_tools searches per reply, results per search, and bytes of found tool schemas per reply. */
+export const FIND_TOOLS_PER_TURN = 3;
+export const FIND_TOOLS_MAX_RESULTS = 6;
+export const FIND_TOOLS_SCHEMA_BYTES = 48_000;
+const FIND_TOOLS_NONE = "Nothing matched. The other tools cover flows, subagents, sweeps, agents and models, project tools and integrations, controls and settings pages, holds and the queue, task actions (retry, stop, merge), result images and evidence, people, and promises — search again with one of those words.";
+const MAKE_WORDS = new Set(["make", "add", "create", "set", "draft", "new", "start", "change", "edit", "build", "run", "hold", "cancel", "release", "move", "switch", "turn"]);
+const LOOK_WORDS = new Set(["show", "list", "see", "what", "which", "how", "check", "read", "look", "find", "open", "where"]);
+/** The deferred tools a query finds, best first: an exact name, then words in the name, keywords and description. */
+export function findLeadTools(query) {
+    // A plural matches its singular ("sweeps" finds sweep tools).
+    const words = query.toLowerCase().split(/[^a-z0-9-]+/).filter(one => one.length >= 3).map(one => one.length > 4 && one.endsWith("s") && !one.endsWith("ss") ? one.slice(0, -1) : one);
+    const exact = query.trim().toLowerCase();
+    const scored = LEAD_TOOLS.filter(tool => !LEAD_CORE_TOOLS.has(tool.name)).map(tool => {
+        const name = tool.name.toLowerCase(), keywords = (LEAD_TOOL_KEYWORDS[tool.name] ?? []).join(" ").toLowerCase();
+        const description = tool.description.toLowerCase();
+        let score = name === exact ? 100 : 0;
+        for (const word of words)
+            score += (name.includes(word) ? 5 : 0) + (keywords.includes(word) ? 3 : 0) + (description.includes(word) ? 1 : 0);
+        // What the person wants done leans the match: making or changing something → a proposal; looking → a read.
+        if (score > 0 && words.some(word => MAKE_WORDS.has(word)))
+            score += name.startsWith("propose_") ? 4 : 0;
+        if (score > 0 && words.some(word => LOOK_WORDS.has(word)))
+            score += name.startsWith("get_") || name === "show_control" ? 4 : 0;
+        return { tool, score };
+    }).filter(one => one.score > 0).sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name));
+    return scored.slice(0, FIND_TOOLS_MAX_RESULTS).map(({ tool }) => ({ name: tool.name, summary: summaryLine(tool.description) }));
+}
+/** A description's first sentence, at most 160 characters. */
+function summaryLine(description) {
+    const first = /^(.+?[.!?])(\s|$)/.exec(description)?.[1] ?? description;
+    return first.length <= 160 ? first : `${first.slice(0, 157).trimEnd()}…`;
+}
 const LEAD_TOOL_HANDLERS = {
+    find_tools: {
+        // Counted before the call is read, so an invalid search still uses one of the reply's three.
+        prepare: (ctx, raw) => { if (ctx.findTools !== undefined)
+            ctx.findTools.searches++; return raw; },
+        description: "Find the lead's other tools by what you want to do — flows, subagents, sweeps, agents and models, project tools and integrations, controls and settings pages, holds and the queue, task actions (retry, stop, merge), result images and evidence, people, promises. Search before saying something can't be done. Matching tools become available from your next step in this reply: call them then, not in the same step.",
+        handle: (ctx, args) => {
+            const state = ctx.findTools;
+            if (state === undefined)
+                return { ok: false, message: "find_tools works inside a conversation reply." };
+            if (state.searches > FIND_TOOLS_PER_TURN)
+                return { ok: false, message: `You have searched ${FIND_TOOLS_PER_TURN} times this reply. Use the tools you found, or answer with what you have.` };
+            const bytesOf = (name) => Buffer.byteLength(JSON.stringify(LEAD_TOOL_SCHEMAS.find(one => one.name === name) ?? {}), "utf8");
+            let used = [...state.found].reduce((sum, name) => sum + bytesOf(name), 0);
+            const tools = [];
+            for (const one of findLeadTools(args.query)) {
+                if (!state.found.has(one.name)) {
+                    if (used + bytesOf(one.name) > FIND_TOOLS_SCHEMA_BYTES)
+                        continue;
+                    used += bytesOf(one.name);
+                    state.found.add(one.name);
+                }
+                tools.push(one);
+            }
+            return { ok: true, body: { tools, next: tools.length === 0 ? FIND_TOOLS_NONE : "These are available from your next step in this reply: call one then." } };
+        },
+    },
     get_brief: {
         description: 'Read current tasks, decisions, results and project knowledge from the local database. No model or mutation.',
         handle: (ctx, args) => {
@@ -756,13 +853,14 @@ const LEAD_TOOL_HANDLERS = {
                     rule: "Builds in this project get exactly these tools and nothing else configured on this computer. A tool reaches work approved after it was added; earlier approvals need approving again. Reviewers and this chat never get tools; Gemini builds get none.",
                     tools: tools.map(tool => {
                         const set = secretsSetFor(repo, tool.spec);
-                        return { name: tool.name, about: tool.spec.about, starts: toolCommandLine(tool.spec), standing: toolStanding(tool, set).words,
+                        return { name: tool.name, about: tool.spec.about, starts: toolCommandLine(tool.spec), standing: toolStanding(tool, set).words, credentials: credentialModeOf(tool.spec, set)?.words ?? null,
                             secrets: tool.spec.secrets.map(one => ({ name: one.name, optional: one.optional, set: set.includes(one.name) })),
                             lastTest: tool.lastTest === null ? null : { ok: tool.lastTest.ok, at: tool.lastTest.at, tools: tool.lastTest.tools.slice(0, 40), problem: tool.lastTest.problem } };
                     }),
                     connectBySigningIn: connectionsOf(ctx.store, repo).map(one => ({ service: one.id, label: one.label, about: one.about, state: one.state, connect: `/settings/tools?repo=${encodeURIComponent(repo)}&connect=${one.id}#connect` })),
                     commonTools: TOOL_CATALOG.filter(one => !names.has(one.name) && oneClickOf(one.name) === null).map(one => ({ catalog: one.name, label: one.label, about: one.about, needs: one.secrets.filter(secret => !secret.optional).map(secret => secret.name) })),
                     foundOnThisComputer: found.filter(one => !names.has(one.spec.name)).map(one => ({ name: one.spec.name, source: one.source })),
+                    secretsKept: toolSecretStorage().words,
                     notice: "Never ask for, accept or repeat a secret's value in chat. Name the secret and open the Tools page (show_control tools with this repo).",
                 } };
         },
@@ -837,7 +935,13 @@ const LEAD_TOOL_HANDLERS = {
                             return { trigger: trigger.id, kind: trigger.kind, what: config === null ? "can't be read" : describeTrigger(config, ctx.store),
                                 startsIn: titleOf(config?.zone ?? definition.start), state: trigger.state, lastCheck: trigger.lastOutcome };
                         }),
-                        rule: "Change it with propose_flow. Build and research steps file ordinary tasks under the usual approvals.",
+                        // "Runs on its own" is signed with the owner's password on the flow page, never in chat; revoking is one click there.
+                        runsOnItsOwn: (() => {
+                            const own = activeUnattendedGrant(ctx.store, flow.id, ctx.now);
+                            return own === null || own.terms.flowRevision !== flow.revision ? { on: false, change: `Turn it on (the owner's password) on the flow page: /flows/${flow.id}` }
+                                : { on: true, until: own.absoluteExpiry, change: `Revoke it on the flow page: /flows/${flow.id}` };
+                        })(),
+                        rule: "Change it with propose_flow. Build and research steps file ordinary tasks under the usual approvals, unless runsOnItsOwn is on: then its schedule's cards are approved by the owner's signed grant. Signing or revoking that is on the flow page; send the person there.",
                     } };
             }
             const repo = args["repo"] === undefined ? null : repoPathOf(ctx.who, args["repo"]);
@@ -1227,7 +1331,8 @@ const LEAD_TOOL_HANDLERS = {
             const thread = ctx.store.liveLeadThreadFor(ctx.who.name, { kind: "task", key: root });
             if (thread === null || thread.ceilingDigest !== ctx.who.ceilingDigest)
                 return { ok: true, body: { task: root, messages: [], notice: "No conversation about this task yet." } };
-            const messages = ctx.store.listLeadMessages(thread.id, limit).map(one => ({ from: one.role === "operator" ? "operator" : "lead", text: one.text.length > 1_200 ? `${one.text.slice(0, 1_200)}…` : one.text, at: one.createdAt }));
+            // What the lead reads of a task's conversation is what it has been told: admitted messages only (v128).
+            const messages = ctx.store.listLeadHistory(thread.id, limit).map(one => ({ from: one.role === "operator" ? "operator" : "lead", text: one.text.length > 1_200 ? `${one.text.slice(0, 1_200)}…` : one.text, at: one.createdAt }));
             return { ok: true, body: { task: root, title: family?.root.title ?? null, messages, notice: messages.length === limit ? "Only the most recent messages are shown." : null } };
         },
     },
@@ -1632,6 +1737,60 @@ const LEAD_TOOL_HANDLERS = {
             return { ok: true, body: { proposal: id, kind: "task", repo: args["repo"], deliverable: report ? "report" : "branch", planning: report ? "not needed for a scout" : planning, awaiting: "the operator's confirmation" } };
         },
     },
+    propose_sweep: {
+        description: "Several independent items under ONE shared rule set (a bug sweep, a batch of small fixes): 2-20 items, each becomes its own task in its own worktree, started with one approval, at most max_parallel (default 3) at once, each reporting a verdict into one table. brief holds the shared rules every item gets (e.g. reproduce first; 'not reproducible' is a valid result; prove the fix); each item is only its own report. Not for one task, and not for steps that depend on each other.",
+        handle: (ctx, args) => {
+            const repo = repoPathOf(ctx.who, args["repo"]);
+            if (repo === null)
+                return { ok: false, message: "repo must be one of the ids from list_repos" };
+            const items = Array.isArray(args["items"]) ? args["items"] : [];
+            for (const one of [{ title: args["title"], goal: args["brief"] }, ...items.map(item => ({ title: item["title"], goal: item["item"] }))]) {
+                if (typeof one.title !== "string" || typeof one.goal !== "string")
+                    return { ok: false, message: "each title, the brief and each item are text" };
+                const bad = validateTaskText({ title: one.title, goal: one.goal, outOfScope: null });
+                if (bad !== null)
+                    return { ok: false, message: bad.message };
+                if ([one.title, one.goal].some(text => typeof text === "string" && scanForSecrets(text).length > 0))
+                    return { ok: false, message: "Task text cannot contain credentials." };
+            }
+            const acceptance = readAcceptanceArg(args["acceptance"]);
+            if (acceptance === null)
+                return { ok: false, message: "acceptance is required: at least one criterion with an id, statement, and evidence kinds (shared by every item)" };
+            try {
+                const action = prepareSharedAction(ctx.store, ctx.who, "sweep_file", { repo, title: args["title"], brief: args["brief"], items: items.map(item => ({ title: item["title"], item: item["item"] })),
+                    acceptance, maxParallel: typeof args["max_parallel"] === "number" ? args["max_parallel"] : 3 }, ctx.evidenceRoot, ctx.now);
+                const id = ctx.draft("action", { ...action });
+                return id === null ? tooMany() : { ok: true, body: { proposal: id, label: action.title, awaiting: "human review in the secure confirmation screen", executed: false } };
+            }
+            catch (error) {
+                return { ok: false, message: error instanceof Error ? error.message : "That sweep couldn't be drafted." };
+            }
+        },
+    },
+    get_sweep: {
+        description: "A sweep's table as facts: each item's state, its verdict (fixed, not reproducible, blocked, done, or none yet) and its result, plus the one-line count. Read this, don't poll each task.",
+        handle: (ctx, args) => {
+            const table = sweepTable(ctx.store, Number(args["sweep"]), ctx.now, ctx.who.repos, ctx.evidenceRoot);
+            if (table === null)
+                return { ok: false, message: "No such sweep in your projects." };
+            return { ok: true, body: { sweep: table.id, title: table.title, line: sweepLine(table), table: `/sweeps/${table.id}`, maxParallel: table.maxParallel,
+                    items: table.rows.map(row => ({ item: row.ordinal + 1, label: row.label, task: row.task, state: row.state, detail: row.detail.slice(0, 300),
+                        verdict: row.verdict?.verdict ?? null, why: row.verdict?.why ?? null, result: row.result })) } };
+        },
+    },
+    propose_sweep_cancel: {
+        description: "Cancel every item of a sweep that isn't ready yet (finished results stay); one confirmation. To steer, cancel or retry ONE item, use that task's own actions.",
+        handle: (ctx, args) => {
+            try {
+                const action = prepareSharedAction(ctx.store, ctx.who, "sweep_cancel_rest", { sweep: Number(args["sweep"]) }, ctx.evidenceRoot, ctx.now);
+                const id = ctx.draft("action", { ...action });
+                return id === null ? tooMany() : { ok: true, body: { proposal: id, label: action.title, awaiting: "human confirmation", executed: false } };
+            }
+            catch (error) {
+                return { ok: false, message: error instanceof Error ? error.message : "That couldn't be drafted." };
+            }
+        },
+    },
     propose_next: {
         description: "Move a task to its queue column front; intervening queue changes invalidate confirmation.",
         handle: (ctx, args) => {

package/dist/lead.d.ts

@@ -27,6 +27,13 @@ export type LeadTurnInput = {
     queuedMessageId?: number;
     /** Called inside turn admission. A failed queue fence rolls admission back. */
     onAdmitted?: (turn: number) => void;
+    /** A personal queue claim (lead-queue.ts) this turn runs: with `queuedMessageId`, the queued message of the person's
+     * own thread this turn binds; admission lets it through the person's backlog (store.openLeadTurn). */
+    queueClaim?: {
+        message: number;
+        runner: string;
+        generation: number;
+    };
     /** Safe, server-authored context for this turn only. Kept out of the
      * visible thread so a task-scoped composer still reads like a normal
      * conversation. */
@@ -67,8 +74,8 @@ export type LeadTurnInput = {
 };
 /** Why a chat's standing changed under a turn: each has its own plain words (LEAD_CHANNEL_COPY). */
 export type LeadChannelProblem = "unpaired" | "not-approver" | "projects-changed" | "projects-unreadable" | "member-changed" | "access-changed";
-export type LeadRefusal = "empty-message" | "secret-in-message" | "secret-in-context" | "standing" | "unpriced" | "ceiling-changed" | "not-yours" | "thread-closed" | "latched" | "concurrent" | "daily-cap" | "session-exhausted" | "session-ended" | "over-budget" | "monthly-budget" | "policy" | "invalid-request" | "request-changed" | "channel";
-export type LeadFailure = "provider-error" | "timeout" | "malformed-reply" | "secret-refused" | "latched" | "revoked" | "superseded";
+export type LeadRefusal = "empty-message" | "secret-in-message" | "secret-in-context" | "standing" | "unpriced" | "ceiling-changed" | "not-yours" | "thread-closed" | "latched" | "concurrent" | "backlog" | "daily-cap" | "session-exhausted" | "session-ended" | "over-budget" | "monthly-budget" | "policy" | "invalid-request" | "request-changed" | "channel";
+export type LeadFailure = "provider-error" | "timeout" | "malformed-reply" | "secret-refused" | "latched" | "revoked" | "superseded" | "over-reservation";
 export type LeadTurnOutcome = {
     ok: true;
     replayed?: false;
@@ -115,16 +122,17 @@ export declare const LEAD_FAILURE_COPY: {
     readonly tooLongUnknownCost: string;
     readonly 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.";
     readonly 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.";
+    readonly 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.";
     readonly empty: "The lead sent back an empty answer. Nothing was kept. Send your message again.";
     readonly 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 declare function leadFailureText(reason: string | null): string;
+export declare function leadFailureText(reason: string | null, unknownSpend?: boolean): string;
 /** 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 declare const LEAD_ABORT_GRACE_MS = 5000;
 /** The last messages of the thread as provider-neutral history, newest kept first until the byte cap. */
-export declare function historyFor(store: Store, thread: number, queuedMessageId?: number): LeadHistoryMessage[];
+export declare function historyFor(store: Store, thread: number, queuedMessageId?: number, named?: boolean): LeadHistoryMessage[];
 /** "read 3 · proposed 1 · 2 steps" — counts only, never results (ruling 11). */
-export declare function activitySummary(reads: number, proposals: number, steps: number): string;
+export declare function activitySummary(reads: number, proposals: number, steps: number, cacheShare?: number | null): string;
 export declare function runLeadTurn(input: LeadTurnInput): Promise<LeadTurnOutcome>;

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)