toolroll 0.9.63 → 0.9.67

package/dist/lead-queue.js

@@ -0,0 +1,187 @@
+/**
+ * The personal lead queue (docs/plans/lead-message-queue.md): a message sent while one of its author's personal lead
+ * turns runs (or while earlier ones wait) waits here and runs one turn per message, in order — the same machinery
+ * shared team conversations use (team-leads.ts), for the person's own threads (/chat, a task's or a project's chat).
+ *
+ * The row's words are its lead_message (pending until the engine's admission binds it, which clears pending in the
+ * same statement). Admission itself is the engine's (runLeadTurn with queuedMessageId + onAdmitted): this module only
+ * decides queue-or-run at send, claims the backlog's oldest row, binds, finishes, defers, removes and expires.
+ */
+import { createHash } from "node:crypto";
+/** At most this many messages wait per person, and this many characters in all; a waiting message expires after 7 days. */
+export const LEAD_QUEUE_MAX_MESSAGES = 10;
+export const LEAD_QUEUE_MAX_CHARS = 20_000;
+export const LEAD_QUEUE_EXPIRY_MS = 7 * 86_400_000;
+/** The identity of a send: the same request with the same words and context is the same message. */
+export function leadQueuePayloadHash(thread, text, context) {
+    return createHash("sha256").update(JSON.stringify([thread, text, context === null ? null : canonical(context)])).digest("hex");
+}
+const canonical = (context) => Object.fromEntries(Object.entries(context).filter(([, value]) => value !== undefined).sort(([a], [b]) => a.localeCompare(b)));
+const readRow = (row) => ({
+    message: Number(row["message"]), thread: Number(row["thread"]), approver: String(row["approver"]), approverGeneration: Number(row["approver_generation"]),
+    session: Number(row["session"]), ceilingDigest: String(row["ceiling_digest"]), requestId: String(row["request_id"]), payloadHash: String(row["payload_hash"]),
+    context: row["context_json"] === null ? null : JSON.parse(String(row["context_json"])), status: String(row["status"]),
+    revision: Number(row["revision"]), generation: Number(row["generation"]), runner: row["runner"] === null ? null : String(row["runner"]),
+    turnId: row["turn_id"] === null ? null : Number(row["turn_id"]), error: row["error"] === null ? null : String(row["error"]),
+    createdAt: String(row["created_at"]), text: String(row["text"] ?? ""),
+});
+const SELECT = "SELECT q.*, m.text FROM lead_queue q JOIN lead_message m ON m.id = q.message";
+export class PersonalQueue {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    get db() { return this.store.handle; }
+    /** The approver's backlog: rows waiting or claimed but not yet bound to a turn, oldest first. */
+    backlog(approver) {
+        return this.db.prepare(`${SELECT} WHERE q.approver = ? AND (q.status = 'queued' OR (q.status = 'running' AND q.turn_id IS NULL)) ORDER BY q.message`).all(approver).map(readRow);
+    }
+    /** Every queue row of a thread (what the thread shows next to its messages). */
+    forThread(thread) {
+        return this.db.prepare(`${SELECT} WHERE q.thread = ? ORDER BY q.message`).all(thread).map(readRow);
+    }
+    get(message) {
+        const row = this.db.prepare(`${SELECT} WHERE q.message = ?`).get(message);
+        return row === undefined ? null : readRow(row);
+    }
+    /**
+     * Send: run now, or wait — in ONE transaction, so a turn ending between the check and the insert can't strand a
+     * message. A request already saved with the same words and context is that message (never a second send, never a
+     * removed one resurrected); with different ones it conflicts. Busy means a personal lead turn of this person is
+     * queued or running, or something of theirs already waits.
+     */
+    sendOrQueue(input, now) {
+        return this.store.transact(() => {
+            const hash = leadQueuePayloadHash(input.thread, input.text, input.context);
+            const seen = this.db.prepare(`${SELECT} WHERE q.session = ? AND q.request_id = ?`).get(input.session, input.requestId);
+            if (seen !== undefined)
+                return String(seen["payload_hash"]) === hash ? { kind: "queued", row: readRow(seen), already: true } : { kind: "conflict" };
+            const live = this.db.prepare(`SELECT 1 FROM mate_turn WHERE approver = ? AND state IN ('queued','running')
+        AND NOT EXISTS (SELECT 1 FROM team_conversation tc WHERE tc.thread = mate_turn.thread) LIMIT 1`).get(input.approver);
+            const waiting = this.backlog(input.approver);
+            if (live === undefined && waiting.length === 0)
+                return { kind: "run" };
+            if (waiting.length >= LEAD_QUEUE_MAX_MESSAGES)
+                return { kind: "full", message: `${LEAD_QUEUE_MAX_MESSAGES} messages are already waiting. Remove one, or wait for a reply.` };
+            if (waiting.reduce((sum, one) => sum + one.text.length, 0) + input.text.length > LEAD_QUEUE_MAX_CHARS) {
+                return { kind: "full", message: "The messages waiting are already long. Remove one, or wait for a reply." };
+            }
+            const message = this.store.appendLeadMessage({ thread: input.thread, turn: null, role: "operator", text: input.text, pending: true }, now);
+            this.db.prepare(`INSERT INTO lead_queue (message, thread, approver, approver_generation, session, ceiling_digest, request_id, payload_hash, context_json, status, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'queued', ?)`).run(message, input.thread, input.approver, input.approverGeneration, input.session, input.ceilingDigest, input.requestId, hash, input.context === null ? null : JSON.stringify(canonical(input.context)), now.toISOString());
+            return { kind: "queued", row: this.get(message), already: false };
+        });
+    }
+    /**
+     * The next message to run: per person, only the oldest of their backlog, only while none of theirs runs, and only when
+     * `eligible` agrees (the runtime's admission stamp). Claiming keeps it in the backlog until its turn binds it.
+     */
+    claimNext(runner, now, eligible = () => true) {
+        return this.store.transact(() => {
+            // An uncertain row does not hold the person's later messages (unlike a team room): its outcome is shown on it, and
+            // an unknown cost already pauses chat through its own latch.
+            const heads = this.db.prepare(`${SELECT} WHERE q.status = 'queued'
+        AND NOT EXISTS (SELECT 1 FROM lead_queue r WHERE r.approver = q.approver AND r.status = 'running')
+        AND NOT EXISTS (SELECT 1 FROM lead_queue e WHERE e.approver = q.approver AND e.status = 'queued' AND e.message < q.message)
+        ORDER BY q.message LIMIT 50`).all().map(readRow);
+            for (const row of heads) {
+                if (!eligible(row))
+                    continue;
+                const changed = this.db.prepare("UPDATE lead_queue SET status = 'running', generation = generation + 1, runner = ?, claimed_at = ? WHERE message = ? AND status = 'queued'")
+                    .run(runner, now.toISOString(), row.message);
+                if (Number(changed.changes) !== 1)
+                    continue;
+                return { ...row, status: "running", runner, generation: row.generation + 1 };
+            }
+            return null;
+        });
+    }
+    /** The claim still stands: running, this runner, this generation and revision, unbound or bound to `turn`. */
+    current(claim) {
+        return this.db.prepare("SELECT 1 FROM lead_queue WHERE message = ? AND status = 'running' AND runner = ? AND generation = ? AND revision = ?")
+            .get(claim.message, claim.runner, claim.generation, claim.revision) !== undefined;
+    }
+    /** Inside the engine's admission transaction (onAdmitted): the claim binds to the turn that took it, exactly once. */
+    bindTurn(claim, turnId) {
+        if (!this.current(claim))
+            return false;
+        const turn = this.store.getLeadTurn(turnId);
+        if (turn === null || turn.thread !== claim.thread || turn.approver !== claim.approver)
+            return false;
+        return Number(this.db.prepare("UPDATE lead_queue SET turn_id = ? WHERE message = ? AND turn_id IS NULL AND status = 'running' AND generation = ?")
+            .run(turnId, claim.message, claim.generation).changes) === 1;
+    }
+    /** The claim ends: answered (its turn's reply is in the thread), failed or cancelled (words kept as the error), or
+     * uncertain (an outcome that can't be confirmed — never sent again). A message that never got a turn loses its words. */
+    finish(claim, result, now) {
+        return this.store.transact(() => {
+            const row = this.db.prepare("SELECT turn_id FROM lead_queue WHERE message = ? AND status = 'running' AND runner = ? AND generation = ?").get(claim.message, claim.runner, claim.generation);
+            if (row === undefined)
+                return false;
+            if (result.turnId !== undefined && row["turn_id"] !== null && Number(row["turn_id"]) !== result.turnId)
+                return false;
+            this.db.prepare("UPDATE lead_queue SET status = ?, error = ?, turn_id = COALESCE(turn_id, ?), revision = revision + 1, settled_at = ? WHERE message = ?")
+                .run(result.status, result.error ?? null, result.turnId ?? null, now.toISOString(), claim.message);
+            if (row["turn_id"] === null && result.turnId === undefined)
+                this.forgetWords(claim.message);
+            return true;
+        });
+    }
+    /** A refusal before admission (a cap, a budget, a latch, another turn): back to waiting with the words to show. */
+    defer(claim, error) {
+        return Number(this.db.prepare(`UPDATE lead_queue SET status = 'queued', generation = generation + 1, revision = revision + 1, runner = NULL, claimed_at = NULL, error = ?
+      WHERE message = ? AND status = 'running' AND turn_id IS NULL AND runner = ? AND generation = ?`).run(error, claim.message, claim.runner, claim.generation).changes) === 1;
+    }
+    /** Remove a waiting message (its author only, while it still waits): its words are forgotten, its request kept. */
+    remove(approver, message, now) {
+        return this.store.transact(() => {
+            const row = this.db.prepare("SELECT status FROM lead_queue WHERE message = ? AND approver = ?").get(message, approver);
+            if (row === undefined)
+                return "not-found";
+            if (row["status"] !== "queued")
+                return "started";
+            this.db.prepare("UPDATE lead_queue SET status = 'cancelled', error = 'Removed.', revision = revision + 1, settled_at = ? WHERE message = ?").run(now.toISOString(), message);
+            this.forgetWords(message);
+            return "removed";
+        });
+    }
+    /** Settle rows whose bound turn ended (by its recorded state), expire week-old waiting rows, and mark a claim that
+     * never bound by its turn deadline uncertain (the binding is the proof; elapsed time never resends). */
+    reconcile(now, turnDeadlineMs) {
+        return this.store.transact(() => {
+            let changed = 0;
+            for (const row of this.db.prepare(`SELECT q.message, t.state, t.failure_reason FROM lead_queue q JOIN mate_turn t ON t.id = q.turn_id
+        WHERE q.status = 'running' AND t.state IN ('answered','failed')`).all()) {
+                const uncertain = this.store.leadTurnCostUnconfirmed(Number(this.db.prepare("SELECT turn_id FROM lead_queue WHERE message = ?").get(Number(row["message"]))["turn_id"]));
+                const status = row["state"] === "answered" ? "answered" : uncertain ? "uncertain" : "failed";
+                changed += Number(this.db.prepare("UPDATE lead_queue SET status = ?, error = ?, revision = revision + 1, settled_at = ? WHERE message = ? AND status = 'running'")
+                    .run(status, status === "answered" ? null : String(row["failure_reason"] ?? "failed"), now.toISOString(), Number(row["message"])).changes);
+            }
+            const stale = new Date(now.getTime() - turnDeadlineMs).toISOString();
+            changed += Number(this.db.prepare("UPDATE lead_queue SET status = 'uncertain', error = 'Delivery could not be confirmed. Nothing was sent again.', revision = revision + 1, settled_at = ? WHERE status = 'running' AND turn_id IS NULL AND claimed_at < ?")
+                .run(now.toISOString(), stale).changes);
+            const old = new Date(now.getTime() - LEAD_QUEUE_EXPIRY_MS).toISOString();
+            for (const row of this.db.prepare("SELECT message FROM lead_queue WHERE status = 'queued' AND created_at < ?").all(old)) {
+                this.db.prepare("UPDATE lead_queue SET status = 'failed', error = 'Not sent: it waited too long.', revision = revision + 1, settled_at = ? WHERE message = ?").run(now.toISOString(), Number(row["message"]));
+                this.forgetWords(Number(row["message"]));
+                changed++;
+            }
+            return changed;
+        });
+    }
+    /** End every waiting message sent under a session (it ended, or its person's chat was revoked). */
+    cancelForSession(session, why, now) {
+        return this.store.transact(() => {
+            const rows = this.db.prepare("SELECT message FROM lead_queue WHERE session = ? AND status = 'queued'").all(session);
+            for (const row of rows) {
+                this.db.prepare("UPDATE lead_queue SET status = 'cancelled', error = ?, revision = revision + 1, settled_at = ? WHERE message = ?").run(why, now.toISOString(), Number(row["message"]));
+                this.forgetWords(Number(row["message"]));
+            }
+            return rows.length;
+        });
+    }
+    /** A message that never ran keeps no words, context or search copy (it stays pending, so never history). */
+    forgetWords(message) {
+        this.store.forgetQueuedLeadMessage(message);
+    }
+}

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>;