toolroll 0.9.63 → 0.9.65

package/dist/lead-sweep.d.ts

@@ -0,0 +1,67 @@
+import { type AssignmentSnapshot } from "./assignment.js";
+import { type Store } from "./store.js";
+import { type StopRequest } from "./task-control.js";
+export declare const SWEEP_VERDICTS: readonly ["fixed", "not reproducible", "blocked", "done"];
+export type SweepVerdict = typeof SWEEP_VERDICTS[number];
+/** The line every sweep child's brief asks for, appended to the shared rules. */
+export declare const VERDICT_RULE = "Start your handoff's conclusion with one line: `Verdict: fixed`, `Verdict: not reproducible`, `Verdict: blocked` or `Verdict: done`, then ` \u2014 ` and one sentence why (the root cause, what you tried, or what blocks it).";
+/** A conclusion's verdict line, read strictly. */
+export declare function verdictOf(conclusion: string | null | undefined): {
+    verdict: SweepVerdict;
+    why: string;
+} | null;
+export type SweepRow = {
+    ordinal: number;
+    label: string;
+    /** The child's family root: its identity in the sweep. */
+    task: string;
+    /** The task the family is on now (a revision of the child, after one): what an act on this row acts on. */
+    active: string;
+    state: AssignmentSnapshot["state"] | "missing";
+    detail: string;
+    verdict: {
+        verdict: SweepVerdict;
+        why: string;
+    } | null;
+    /** The child's result, when it has one. */
+    result: {
+        taskId: string;
+        runId: number;
+    } | null;
+};
+export type SweepTable = {
+    id: number;
+    title: string;
+    repo: string;
+    maxParallel: number;
+    rows: SweepRow[];
+    counts: {
+        settled: number;
+        working: number;
+        total: number;
+        byVerdict: Partial<Record<SweepVerdict, number>>;
+    };
+};
+/** A sweep as its table shows it; null when there is no such sweep or this reader may not see its project. */
+export declare function sweepTable(store: Store, id: number, now: Date, repos: readonly string[], root?: string): SweepTable | null;
+/** "8 of 11 settled — 5 fixed, 2 not reproducible, 1 blocked": the sweep in one line. */
+export declare function sweepLine(table: SweepTable): string;
+/** Not ready yet: working, being checked, or waiting on a decision — what "cancel the rest" acts on. */
+export declare const SWEEP_OPEN: ReadonlySet<SweepRow["state"]>;
+/** One open item exactly as it stands now: its active task, state, attempt (a running build to stop) and last change. */
+export type SweepOpenItem = {
+    label: string;
+    task: string;
+    state: string;
+    run: number | null;
+    at: string | null;
+    scope: string | null;
+};
+/** Exactly what "cancel the rest" would act on now; any change makes a card or a form for it stale. */
+export declare function sweepOpen(store: Store, table: SweepTable, now: Date): SweepOpenItem[];
+export declare const sweepOpenDigest: (open: readonly SweepOpenItem[]) => string;
+/**
+ * Cancel the rest: a running build is stopped through the ordinary stop (process-exit safeguards and all); anything
+ * else is cancelled. Every refusal is said, never swallowed. The caller has proved `open` is what stands now.
+ */
+export declare function cancelSweepRest(store: Store, actor: string, open: readonly SweepOpenItem[], now: Date, via: StopRequest["via"]): string;

package/dist/lead-sweep.js

@@ -0,0 +1,99 @@
+/**
+ * Lead fan-out (docs/plans/lead-fan-out.md): a sweep's table and verdicts, read from facts — never a model.
+ *
+ * Each row is a child's assignment (the same state words the board uses), its verdict, and its result. The verdict is
+ * the first line of the child's conclusion, `Verdict: fixed | not reproducible | blocked | done — why`, which the
+ * sweep's brief asks for. It is read strictly: anything else reads as no verdict, never a guess.
+ */
+import { createHash } from "node:crypto";
+import { withActor } from "./actor.js";
+import { assignmentOf } from "./assignment.js";
+import { chatTaskRun } from "./chat-task-actions.js";
+import { verifiedAuthor } from "./store.js";
+import { requestTaskStop } from "./task-control.js";
+export const SWEEP_VERDICTS = ["fixed", "not reproducible", "blocked", "done"];
+/** The line every sweep child's brief asks for, appended to the shared rules. */
+export const VERDICT_RULE = "Start your handoff's conclusion with one line: `Verdict: fixed`, `Verdict: not reproducible`, `Verdict: blocked` or `Verdict: done`, then ` — ` and one sentence why (the root cause, what you tried, or what blocks it).";
+/** A conclusion's verdict line, read strictly. */
+export function verdictOf(conclusion) {
+    if (typeof conclusion !== "string")
+        return null;
+    const first = conclusion.split("\n", 1)[0].trim();
+    const match = /^Verdict:\s*(fixed|not reproducible|not-reproducible|blocked|done)\s*(?:—|–|-|:)\s*(.{1,300})$/i.exec(first);
+    if (match === null)
+        return null;
+    const verdict = match[1].toLowerCase().replace("-", " ");
+    return SWEEP_VERDICTS.includes(verdict) ? { verdict, why: match[2].trim() } : null;
+}
+const SETTLED = new Set(["ready-to-check", "complete", "cancelled", "needs-decision", "missing"]);
+/** A sweep as its table shows it; null when there is no such sweep or this reader may not see its project. */
+export function sweepTable(store, id, now, repos, root) {
+    const sweep = store.getSweep(id);
+    if (sweep === null || !repos.includes(sweep.repo))
+        return null;
+    const rows = store.sweepTasks(id).map(child => {
+        const assignment = assignmentOf(store, child.rootTask, now, { principal: "operator", repos }, root);
+        const run = assignment?.receipt?.runId ?? null;
+        const resultTask = assignment?.receipt?.taskId ?? null;
+        const conclusion = run === null ? null : store.getRun(run)?.handoff ?? null;
+        return {
+            ordinal: child.ordinal, label: child.label, task: child.rootTask, active: assignment?.activeTaskId ?? child.rootTask,
+            state: assignment?.state ?? "missing", detail: assignment?.detail ?? "This task is gone.",
+            verdict: verdictOf(conclusion),
+            result: run === null || resultTask === null ? null : { taskId: resultTask, runId: run },
+        };
+    });
+    const byVerdict = {};
+    for (const row of rows)
+        if (row.verdict !== null)
+            byVerdict[row.verdict.verdict] = (byVerdict[row.verdict.verdict] ?? 0) + 1;
+    const settled = rows.filter(row => SETTLED.has(row.state)).length;
+    return { id, title: sweep.title, repo: sweep.repo, maxParallel: sweep.maxParallel, rows,
+        counts: { settled, working: rows.length - settled, total: rows.length, byVerdict } };
+}
+/** "8 of 11 settled — 5 fixed, 2 not reproducible, 1 blocked": the sweep in one line. */
+export function sweepLine(table) {
+    const verdicts = SWEEP_VERDICTS.filter(one => (table.counts.byVerdict[one] ?? 0) > 0).map(one => `${table.counts.byVerdict[one]} ${one}`);
+    return `${table.counts.settled} of ${table.counts.total} settled${verdicts.length === 0 ? "" : ` — ${verdicts.join(", ")}`}`;
+}
+/** Not ready yet: working, being checked, or waiting on a decision — what "cancel the rest" acts on. */
+export const SWEEP_OPEN = new Set(["working", "checking", "needs-decision"]);
+/** Exactly what "cancel the rest" would act on now; any change makes a card or a form for it stale. */
+export function sweepOpen(store, table, now) {
+    return table.rows.filter(row => SWEEP_OPEN.has(row.state)).map(row => ({
+        label: row.label, task: row.active, state: row.state, run: chatTaskRun(store, row.active, "stop", now), at: store.getTask(row.active)?.updatedAt ?? null,
+        // The scope's identity too: a goal rewritten in between makes a card or form for it stale (Codex sweep r2).
+        scope: store.getScope(row.active)?.digest ?? null,
+    }));
+}
+export const sweepOpenDigest = (open) => createHash("sha256").update(JSON.stringify(open)).digest("hex");
+/**
+ * Cancel the rest: a running build is stopped through the ordinary stop (process-exit safeguards and all); anything
+ * else is cancelled. Every refusal is said, never swallowed. The caller has proved `open` is what stands now.
+ */
+export function cancelSweepRest(store, actor, open, now, via) {
+    let cancelled = 0, stopping = 0;
+    const refused = [];
+    for (const item of open) {
+        if (item.run !== null) {
+            const stop = requestTaskStop(store, { taskId: item.task, runId: item.run, by: verifiedAuthor(actor), via }, now);
+            if (stop.ok)
+                stopping += 1;
+            else
+                refused.push(`${item.label} (${stop.detail})`);
+            continue;
+        }
+        const result = withActor({ account: actor, lead: false }, () => store.cancelTask(item.task, now));
+        if (result.ok)
+            cancelled += 1;
+        else
+            refused.push(`${item.label} (${String(result.reason ?? "refused")})`);
+    }
+    const parts = [`Cancelled ${cancelled} item${cancelled === 1 ? "" : "s"}.`];
+    if (stopping > 0)
+        parts.push(`Stop requested for ${stopping} running build${stopping === 1 ? "" : "s"}: ${stopping === 1 ? "it stops" : "they stop"} at the next safe point; cancel ${stopping === 1 ? "it" : "them"} from the task page once stopped.`);
+    if (refused.length > 0)
+        parts.push(`Not cancelled: ${refused.join("; ")}.`);
+    parts.push("Finished results stay.");
+    return parts.join(" ");
+}

package/dist/lead-tools.d.ts

@@ -48,6 +48,12 @@ export type LeadToolContext = {
     checkedCapabilities?: Map<string, number>;
     /** Records this turn's one question to its owner; false when it already asked one. Absent: this surface cannot ask. */
     ask?: (question: string, options: readonly string[]) => boolean;
+    /** This turn's tool discovery (find_tools): how many searches it made and which deferred tools it found, which the
+     * conversation loop advertises from its next request. Absent (a direct call outside a turn): nothing to add to. */
+    findTools?: {
+        searches: number;
+        found: Set<string>;
+    };
 };
 export type LeadToolResult = {
     ok: true;
@@ -105,6 +111,22 @@ export declare const ISO_STAMP_RULE: RegExp;
  * through a confirmed card into the one authenticated edit transaction.
  */
 export declare function agentsOver(store: Store, taskId: string, now: Date): Record<string, unknown> | null;
+/**
+ * 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 declare const LEAD_CORE_TOOLS: ReadonlySet<string>;
+/** At most this many find_tools searches per reply, results per search, and bytes of found tool schemas per reply. */
+export declare const FIND_TOOLS_PER_TURN = 3;
+export declare const FIND_TOOLS_MAX_RESULTS = 6;
+export declare const FIND_TOOLS_SCHEMA_BYTES = 48000;
+/** The deferred tools a query finds, best first: an exact name, then words in the name, keywords and description. */
+export declare function findLeadTools(query: string): {
+    name: string;
+    summary: string;
+}[];
 /** The lead's tools, in the order the model is shown them: each one's inputSchema is its contract, derived. */
 export declare const LEAD_TOOLS: LeadTool[];
 /** A unified diff, file by file, with each file's added and removed lines. */

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";
@@ -372,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) => {
@@ -1235,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 } };
         },
     },
@@ -1640,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>;