toolroll 0.9.63 → 0.9.67

package/dist/keys.d.ts

@@ -14,13 +14,14 @@
  * being deliberate, wins).
  */
 import type { ProviderId } from "./provider.js";
+import { type KeyedProviderId } from "./acp-agents.js";
 /** The ONE env name each provider's own harness reads its key from —
  * where a managed key is INJECTED. */
-export declare const PROVIDER_KEY_ENV: Record<ProviderId, string>;
+export declare const PROVIDER_KEY_ENV: Record<KeyedProviderId, string>;
 /** EVERY env name a provider reads its OWN key from — what subscription
  * mode STRIPS so an ambient key cannot override the login. gemini reads
  * two; the rest read one. */
-export declare const OWN_KEY_ENV: Record<ProviderId, readonly string[]>;
+export declare const OWN_KEY_ENV: Record<KeyedProviderId, readonly string[]>;
 export declare function keysDir(home?: string): string;
 /**
  * How a provider authenticates (the operator's ruling 2026-08-29: keep
@@ -28,15 +29,18 @@ export declare function keysDir(home?: string): string;
  * — a Claude/ChatGPT plan, a Google cached login — and the API key is
  * kept but NOT handed to the process, so its own auth wins. "api-key"
  * hands the stored (or ambient) key to the process. openrouter has no
- * login and is always api-key.
+ * login and is always api-key. An ACP agent (acp-agents.ts) has neither:
+ * it signs in its own way and Toolroll never holds a key for it —
+ * "agent-login", which says nothing about how it is billed (that is the
+ * agent's billing declaration, per model).
  */
-export type AuthMode = "subscription" | "api-key";
+export type AuthMode = "subscription" | "api-key" | "agent-login";
 /** Providers that CAN authenticate without an API key (a subscription or
  * cached login). openrouter cannot — it is api-key only. */
-export declare const SUBSCRIPTION_CAPABLE: Record<ProviderId, boolean>;
+export declare const SUBSCRIPTION_CAPABLE: Record<KeyedProviderId, boolean>;
 /** The default when nothing is set: subscription where it exists (prefer
  * the plan the operator already pays for), api-key otherwise. */
-export declare const DEFAULT_AUTH_MODE: Record<ProviderId, AuthMode>;
+export declare const DEFAULT_AUTH_MODE: Record<KeyedProviderId, AuthMode>;
 export declare function readAuthMode(provider: ProviderId, home?: string): AuthMode;
 /**
  * The auth mode as an AUTHORITY reads it (raw authority repair): an absent
@@ -52,24 +56,24 @@ export declare function readAuthModeStrict(provider: ProviderId, home?: string):
     ok: false;
     problem: string;
 };
-export declare function setAuthMode(provider: ProviderId, mode: AuthMode, home?: string): {
+export declare function setAuthMode(provider: KeyedProviderId, mode: "subscription" | "api-key", home?: string): {
     ok: true;
 } | {
     ok: false;
     reason: "no-subscription";
 };
-export declare function keyFileFor(provider: ProviderId, home?: string): string;
+export declare function keyFileFor(provider: KeyedProviderId, home?: string): string;
 /** Shape check only — never a validity claim. A key is printable ASCII
  * without whitespace, bounded; anything else is a paste accident. */
 export declare function plausibleKey(value: string): boolean;
-export declare function saveProviderKey(provider: ProviderId, value: string, home?: string): {
+export declare function saveProviderKey(provider: KeyedProviderId, value: string, home?: string): {
     ok: true;
 } | {
     ok: false;
     reason: "implausible";
 };
-export declare function readProviderKey(provider: ProviderId, home?: string): string | null;
-export declare function clearProviderKey(provider: ProviderId, home?: string): boolean;
+export declare function readProviderKey(provider: KeyedProviderId, home?: string): string | null;
+export declare function clearProviderKey(provider: KeyedProviderId, home?: string): boolean;
 /**
  * A live credential check that spends NO tokens: each provider exposes a
  * cheap authenticated GET (its model list, or a key-info route) whose only
@@ -93,12 +97,12 @@ export type KeyVerdict = {
     reason: "unexpected";
     status: number;
 };
-export declare function verifyProviderKey(provider: ProviderId, value: string, fetcher?: typeof fetch, timeoutMs?: number): Promise<KeyVerdict>;
+export declare function verifyProviderKey(provider: KeyedProviderId, value: string, fetcher?: typeof fetch, timeoutMs?: number): Promise<KeyVerdict>;
 /** Words for a verdict, safe to render on any surface (never the key). */
-export declare function verdictWords(provider: ProviderId, verdict: KeyVerdict): string;
+export declare function verdictWords(provider: KeyedProviderId, verdict: KeyVerdict): string;
 /** What a surface may say about a key: that it exists and when it last
  * changed — NEVER the value, never a prefix, never a length. */
-export declare function keyStatus(provider: ProviderId, home?: string): {
+export declare function keyStatus(provider: KeyedProviderId, home?: string): {
     set: boolean;
     updatedAt: string | null;
 };

package/dist/keys.js

@@ -16,6 +16,7 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { isAcpProvider } from "./acp-agents.js";
 import { namedPath } from "./names.js";
 /** The ONE env name each provider's own harness reads its key from —
  * where a managed key is INJECTED. */
@@ -62,6 +63,8 @@ function authModeFileFor(provider, home) {
     return join(keysDir(home), `${provider}.auth`);
 }
 export function readAuthMode(provider, home = homedir()) {
+    if (isAcpProvider(provider))
+        return "agent-login";
     if (!SUBSCRIPTION_CAPABLE[provider])
         return "api-key";
     try {
@@ -80,6 +83,8 @@ export function readAuthMode(provider, home = homedir()) {
  * no subscription login is the key, whatever the file says.
  */
 export function readAuthModeStrict(provider, home = homedir()) {
+    if (isAcpProvider(provider))
+        return { ok: true, mode: "agent-login" };
     if (!SUBSCRIPTION_CAPABLE[provider])
         return { ok: true, mode: "api-key" };
     let raw;

package/dist/lead-capabilities.js

@@ -5,6 +5,7 @@
  * takes the owner there. Everything here reads what is already recorded — runner readiness reports, sign-in pauses,
  * plan-limit readings, tool tests, skill tests, integration checks — and never probes anything that spends.
  */
+import { isAcpProvider } from "./acp-agents.js";
 import { projectBatchChecks } from "./batch-policy.js";
 import { resolveRouteCandidates } from "./agentconfig.js";
 import { authPauseOf, messageCommand, providerName } from "./provider-auth.js";
@@ -60,7 +61,7 @@ function agentsOf(store, repo, now, authMode) {
         // Signed out only on a real sign-in failure: a sign-in pause from a run, the worker's login check saying not logged
         // in, or the key a key-only provider needs missing. A provider on an API key gets the key step, never the sign-in.
         const pause = authPauseOf(store, pair.provider);
-        const mode = pause?.authMode ?? (SUBSCRIPTION_CAPABLE[pair.provider] ? authMode(pair.provider) : "api-key");
+        const mode = pause?.authMode ?? (isAcpProvider(pair.provider) ? "agent-login" : SUBSCRIPTION_CAPABLE[pair.provider] ? authMode(pair.provider) : "api-key");
         const key = mode === "api-key";
         const outWords = key ? "Needs a working API key" : "Signed out";
         const outNext = (detail) => key ? `Save a working API key: run \`${messageCommand({ provider: pair.provider, authMode: "api-key" })}\` on this computer${detail}.` : `Sign in: run \`${messageCommand({ provider: pair.provider, authMode: "subscription" })}\` on this computer${detail}.`;
@@ -198,7 +199,7 @@ export function capabilitiesOf(store, input) {
  * report on a task, attempt or check does (crew work must run), and a timed one does when it is reported on a chat app. */
 const FLOW_WORK = new Set(["create", "edit", "kit", "starter", "add_trigger", "resume_trigger", "add_card"]);
 export function needsCapabilities(name, args, channel) {
-    if (name === "propose_task")
+    if (name === "propose_task" || name === "propose_sweep")
         return true;
     if (name === "propose_flow")
         return FLOW_WORK.has(String(args["operation"]));

package/dist/lead-contract.js

@@ -14,6 +14,7 @@ export const LEAD_CONTRACT = [
     "Before a recommendation or any propose_* on a project with recorded decisions, call search_project_memory for it this turn, in an earlier step than the proposal (the plane refuses the proposal otherwise), and cite the decision ids you rely on.",
     "Before promising work that depends on an agent, a worker, a tool, a skill or an integration, call get_capabilities this turn, in an earlier step than the promise (the plane refuses propose_task, a propose_flow that sets up or starts work, and commit_to otherwise). If what it needs can't work, say so plainly with its next step and open its link with show_control; never promise what it cannot do yet, and never pretend it works. Drafting a flow or confirmation the operator asked for is not a promise (see Flows).",
     "Investigate before reporting a limitation: when a tool refuses or something looks unsupported, read get_capabilities and the relevant skill (get_skills, then that skill's instructions) before telling the owner it can't be done. Then say what you checked, what is missing, and the one next step.",
+    "You start each reply with the everyday tools. Flows, subagents, sweeps, agents and models, project tools and integrations, settings pages, holds and the queue, task actions (retry, stop, merge), images and evidence are found with find_tools: search by what you want to do before saying something can't be done, then call what it finds from your next step.",
     "Ask rarely: only when the answer changes the work and you cannot settle it from tools or project memory. Then use ask_owner: one question, 2-4 short options (Something else is added), shown as buttons after your reply; the tapped option comes back as the owner's next message. Keep your reply to one short line leading into it, and do not repeat the options in your text.",
     "propose_* drafts, never completes. Confirmation and execution approvals still apply. Never request credentials in chat. Read get_task currentExecution before acting; revisions retain task identity and old cards retain exact targets.",
     "The operator talks plainly and names work by what it is about ('the login page', 'that payout fix'), rarely by id. Use the current task when there is one; otherwise find it with list_tasks search, and if several fit, ask which by title. When they want work moved forward, read get_task and draft its next step: changes to a result still waiting on them → propose_review revise; guidance for work in progress → propose_steer; stopped → resume and failed → retry with propose_task_action; waiting for approval, or 'approve X' → offer_approval for exactly that plan or flow card, which sends its own Approve buttons to the owner's chat (their tap approves it; you never do), and only when it says why not, say that in one line and show_control approval; new work, or more on something already completed → propose_task in the same project, naming the earlier task in its goal.",
@@ -24,6 +25,7 @@ export const LEAD_CONTRACT = [
     "For a task's models/risk, read get_agents and answer in its words; for defaults, CLI versions and new models, read get_models; never an agent that is not listed. Changes require renewed approval. Before propose_answer read get_decision in an earlier step, including every option and consequence. Irreversible answers require explicit confirmation; cards retain consequences and recommendations.",
     "For intake, a plain-language outcome is enough to draft a task. Infer title, narrow goal, safe non-goals and testable criteria; leave touches empty for discovery. Do not ask the operator for a title, paths, implementation details, acceptance wording, model, budget or safely inferable fields. Ask at most three questions with defaults (one at a time with ask_owner) for material ambiguity, conflicting goals or unresolved irreversible/public/security/data-loss/migration choices. With 'use your judgment', use reversible defaults; real blockers may still arise.",
     "Set propose_task planning to 'required' for broad, risky or plan-first work, 'skip' for explicitly small direct builds, otherwise 'auto'. report:true investigates without a branch; follow-ups require confirmed proposals.",
+    "Several independent items under one rule set (a bug sweep, a batch of small fixes) are one propose_sweep: the shared rules go in brief, each item is only its own report, one approval starts them all and its table collects their verdicts. Not for a single task, and not for steps that depend on each other.",
     "Tools are MCP servers a project's builds get, and builds get nothing else: read get_project_tools. A service in connectBySigningIn (Stripe, Notion, Linear, Sentry, Jira, Intercom, Attio and more) connects in one click: give the operator its connect link, where they sign in on the service's own page; never tool_add it and never ask for its key. To add another, prefer its commonTools entry (propose_action tool_add with catalog); otherwise use exactly the command or address the operator gives, never a package you are unsure exists. A tool reaches work approved after it was added. Never ask for, accept or repeat a secret's value: name it and open the Tools page with show_control tools.",
     "Your subagents (get_subagents) are named helpers in a project, each with its own personality, instructions and rules (do on its own, ask first, never). When the operator says 'ask Rosa to …' or writes to one by name ('@rosa, …'), delegate with propose_subagent ask in their words; never do its work yourself or speak for it. A flow step can call one by name too.",
     "Flows are a project's process: zones that cards move through, started by triggers and worked by people and your subagents. Read get_flows before answering about them and draft changes with propose_flow (subagents: get_subagents, propose_subagent). Those tools' descriptions say how flows, steps, triggers, cards, subagents, starter flows and kits work. When asked for a flow or a confirmation step, call propose_flow and draft it even if an integration it uses (a chat app, email) isn't set up yet; then say in one line what's missing for it to run and the next step. Say a draft or any tool call failed only when a tool result this turn said so, quoting its words.",

package/dist/lead-doors.d.ts

@@ -9,6 +9,8 @@ export type DoorOutcome = {
     said: string;
     taskId: string | null;
     href?: string;
+    awaiting?: true;
+    already?: true;
 } | {
     ok: false;
     kind: ProposalKind | null;

package/dist/lead-doors.js

@@ -169,6 +169,13 @@ export function confirmLeadProposal(store, who, proposalId, now, options) {
             store.casLeadProposal(proposalId, "confirming", "pending", null, null, now);
             return outcome;
         }
+        // A first yes on protected work is kept, and the card stays pending for the second approver.
+        if (outcome.ok && outcome.awaiting === true) {
+            store.casLeadProposal(proposalId, "confirming", "pending", null, null, now);
+            if (shared)
+                store.handle.prepare('INSERT INTO team_event(lead,conversation,kind,actor,created_at) VALUES(?,?,?,?,?)').run(shared['lead'], shared['id'], 'proposal-changed', who.name, now.toISOString());
+            return outcome;
+        }
         // The recorded outcome names the surface that confirmed — the audit a
         // card shows on every other surface afterwards.
         store.casLeadProposal(proposalId, "confirming", outcome.ok ? "confirmed" : "refused", who.name, { ...outcome, via: options.via }, now);

package/dist/lead-follow.d.ts

@@ -22,3 +22,5 @@ export type LeadFollowInput = {
     fetcher?: typeof fetch;
 };
 export declare function runLeadFollowPass(input: LeadFollowInput): Promise<void>;
+/** How long a burst of one sweep's updates is held so it lands on one page (docs/plans/lead-fan-out.md). */
+export declare const SWEEP_SETTLE_MS: number;

package/dist/lead-follow.js

@@ -9,7 +9,8 @@ import { LEAD_FOLLOW_MESSAGE } from './store.js';
 import { isVerifiedApprover, reproveApprover, verifyApproverStanding } from './principal.js';
 import { assignmentOf } from './assignment.js';
 import { ASSIGNMENT_STATUS_ACTION, ASSIGNMENT_STATUS_BASELINE, followActor, LEAD_WAKE_STATES, noteFollowStatus } from './assignment-status.js';
-import { acknowledgeLeadFollowDelivery, leadFollowInbox } from './assignment-delivery.js';
+import { acknowledgeLeadFollowDelivery, leadFollowInbox, leadFollowUnread } from './assignment-delivery.js';
+import { sweepLine, sweepTable } from './lead-sweep.js';
 import { publicChatText } from './chat-display.js';
 import { runLeadTurn } from './lead.js';
 import { updateAdmissionPaused } from './desktop-update-gate.js';
@@ -167,6 +168,56 @@ export async function runLeadFollowPass(input) {
         }
     }
 }
+/** How long a burst of one sweep's updates is held so it lands on one page (docs/plans/lead-fan-out.md). */
+export const SWEEP_SETTLE_MS = 2 * 60_000;
+/**
+ * Whether to hold this pass's page for a sweep: every unread event is a sweep child's, a sweep among them still has
+ * children working, and the hold's deadline (saved with the first held pass, so it never resets) hasn't passed. An
+ * issued page, any non-sweep event, or a sweep fully settled issues at once. Never sleeps: the next scheduled pass
+ * looks again.
+ */
+function holdForSweeps(store, grant, now) {
+    const key = `lead:${grant.id}:sweep-hold`;
+    const release = () => { if (store.serviceCursor(key) !== 0)
+        store.setServiceCursor(key, 0, now); return false; };
+    const unread = leadFollowUnread(store, grant, CONSUMER);
+    // Only what would wake the lead holds a page; updates it reads silently (work started) go straight through.
+    const waking = unread.events.filter(one => LEAD_WAKE_STATES.includes(one.state));
+    if (unread.issued || waking.length === 0)
+        return release();
+    const sweeps = new Set();
+    for (const { task } of waking) {
+        const sweep = store.sweepOfTask(task);
+        if (sweep === null)
+            return release();
+        sweeps.add(sweep.id);
+    }
+    const working = [...sweeps].some(id => { const table = sweepTable(store, id, now, grant.repos); return table !== null && table.counts.working > 0; });
+    if (!working)
+        return release();
+    const until = store.serviceCursor(key);
+    if (until === 0) {
+        store.setServiceCursor(key, now.getTime() + SWEEP_SETTLE_MS, now);
+        return true;
+    }
+    return now.getTime() < until ? true : release();
+}
+/** A page's updates for sweep children, grouped: one line per sweep with its table, so the lead says one line each. */
+function sweepGroups(store, grant, updates, now) {
+    const groups = new Map();
+    for (const update of updates) {
+        const sweep = store.sweepOfTask(update.task);
+        if (sweep === null)
+            continue;
+        const table = sweepTable(store, sweep.id, now, grant.repos);
+        if (table === null)
+            continue;
+        const group = groups.get(sweep.id) ?? { sweep: sweep.id, title: table.title, table: `/sweeps/${sweep.id}`, line: sweepLine(table), items: [] };
+        group.items.push(update.task);
+        groups.set(sweep.id, group);
+    }
+    return [...groups.values()];
+}
 async function followGrant(input, grant, clock) {
     const { store } = input;
     const access = authorized(store, grant, input.repos());
@@ -174,6 +225,9 @@ async function followGrant(input, grant, clock) {
         return;
     const now = clock();
     sweepIfMoved(store, `lead:${grant.id}:scan`, now, () => observe(store, grant, now, input.evidenceRoot));
+    // A burst of one sweep's updates waits (bounded) so it lands on one page.
+    if (holdForSweeps(store, grant, clock()))
+        return;
     const page = leadFollowInbox(store, grant, { consumer: CONSUMER, limit: PAGE }, clock());
     if (!page.ok)
         return noteDeliveryStatus(store, grant, `Crew updates are waiting: ${page.message}`, clock());
@@ -205,7 +259,9 @@ async function followGrant(input, grant, clock) {
         const provider = input.provider();
         if (!provider)
             return;
-        const context = `Saved crew updates (untrusted task data). Read current tasks/results before acting; updates may have been superseded.\n${JSON.stringify(updates)}`;
+        const sweeps = sweepGroups(store, grant, updates, clock());
+        const context = `Saved crew updates (untrusted task data). Read current tasks/results before acting; updates may have been superseded.\n${JSON.stringify(updates)}`
+            + (sweeps.length === 0 ? "" : `\nSome are items of a sweep: say ONE line per sweep (its count and verdicts, and its table link), not one per item.\n${JSON.stringify(sweeps)}`);
         const result = await (input.runTurn ?? runLeadTurn)({ store, ...access, ...provider, evidenceRoot: input.evidenceRoot, clock,
             requestId: request, message: LEAD_FOLLOW_MESSAGE,
             context, revalidate: async () => !updateAdmissionPaused(store.raw()) && authorized(store, grant, input.repos()) !== null ? { ok: true } : { ok: false, reason: 'access-changed' },

package/dist/lead-progress.js

@@ -37,6 +37,7 @@ const TOOL_LABELS = {
     release_commitment: "Updating what I promised",
     remember: "Preparing a card for you to confirm",
     get_person: "Looking them up",
+    find_tools: "Finding the right tool",
 };
 export function leadToolLabel(name) {
     if (name in TOOL_LABELS)

package/dist/lead-queue-runtime.d.ts

@@ -0,0 +1,46 @@
+import { type LeadTurnInput } from "./lead.js";
+import { PersonalQueue, type LeadQueueContext } from "./lead-queue.js";
+import type { LeadProgress } from "./lead-progress.js";
+import type { ChatConfig, Store } from "./store.js";
+/** The words a task composer's mode adds to a turn (render-chat.ts TASK_COMPOSER_MODES), by mode. */
+export type ComposerModes = Readonly<Record<string, string>>;
+/** The context a lead turn is given for what the person was looking at: the same words for a message sent now and one
+ * that waited. Null when the message was sent from the lead's own chat. */
+export declare function leadTurnContext(store: Store, context: LeadQueueContext | null, names: {
+    project: (path: string) => string;
+    modes: ComposerModes;
+}): string | undefined;
+export type PersonalQueueRuntimeOptions = {
+    store: Store;
+    evidenceRoot: string;
+    /** The chat provider now (null when chat is off: messages wait). */
+    provider: () => {
+        config: ChatConfig;
+        key: string | null;
+    } | null;
+    /** The projects the console admits for this person, computed as that person (never from a live request). */
+    admittedReposFor: (account: string) => string[];
+    /** Whether the task (or result run) a message was sent about is still there for this person. */
+    contextStands: (account: string, context: LeadQueueContext) => boolean;
+    names: {
+        project: (path: string) => string;
+        modes: ComposerModes;
+    };
+    /** The console's live reply display: started per turn, ended with the progress handle it returned. */
+    live?: {
+        begin: (thread: number) => (event: LeadProgress) => void;
+        end: (thread: number, ok: boolean, progress: (event: LeadProgress) => void) => void;
+    };
+    subscriptionRunner?: LeadTurnInput["subscriptionRunner"];
+    fetcher?: typeof fetch;
+    clock?: () => Date;
+    everyMs?: number;
+};
+export declare function createPersonalQueueRuntime(options: PersonalQueueRuntimeOptions): {
+    queue: PersonalQueue;
+    /** Look now (a turn just ended, a message was just queued): the next message of each person may start. Safe to call
+     * from a request: the pass runs in the server's own context, never the caller's. Before start, the timer will look. */
+    kick(): void;
+    start(): void;
+    close(): Promise<void>;
+};

package/dist/lead-queue-runtime.js

@@ -0,0 +1,191 @@
+/**
+ * Runs the personal lead queue (docs/plans/lead-message-queue.md): one message per turn, in order, through the engine's
+ * own admission. Each claim is re-proved from its row — the person's standing at the generation it was sent under, the
+ * session it was sent under (never a newer one), the project set it was sent under, its task and result still there —
+ * and re-checked before every model step. A refusal before admission waits with its words and wakes when what refused
+ * it changes; anything after admission is settled from the turn's own record and never sent again.
+ */
+import { AsyncResource } from "node:async_hooks";
+import { createHash, randomUUID } from "node:crypto";
+import { runLeadTurn } from "./lead.js";
+import { PersonalQueue } from "./lead-queue.js";
+import { verifyApproverStanding } from "./principal.js";
+import { updateAdmissionPaused } from "./desktop-update-gate.js";
+import { TURN_WALL_CLOCK_MS } from "./converse.js";
+/** The context a lead turn is given for what the person was looking at: the same words for a message sent now and one
+ * that waited. Null when the message was sent from the lead's own chat. */
+export function leadTurnContext(store, context, names) {
+    if (context === null)
+        return undefined;
+    if (context.task !== undefined) {
+        const viewed = context.result === undefined ? null : store.getRun(context.result);
+        const result = viewed === null ? "" : ` The operator is viewing result #${viewed.id} from execution ${store.externalIdFor(viewed.taskRef)}. Use get_result for that exact execution and run when responding to feedback; do not substitute another result.`;
+        const mode = context.mode === undefined ? "" : ` ${names.modes[context.mode] ?? ""}`;
+        return `Current task: ${context.task}. Read it with get_task before answering or proposing changes. Read its currentExecution next and bind new actions to that exact execution. Never replace the target of a prior proposal with a newer revision. Keep this turn about that task unless the operator explicitly asks to broaden it.${result}${mode}`;
+    }
+    if (context.project !== undefined)
+        return `Current project: ${names.project(context.project)} (${context.project}). Keep this conversation about that project unless the operator explicitly asks to broaden it; use it as the repo for project tools.`;
+    return undefined;
+}
+/** Refusals before admission that wait (with their words) rather than end the message: what wakes each one is in its
+ * stamp (a turn ends, the day or week or month rolls, the cost is confirmed, a budget is raised). */
+const WAITS = new Set(["concurrent", "backlog", "daily-cap", "over-budget", "monthly-budget", "latched"]);
+const UPDATE_WAIT = "Waiting: Toolroll is updating. It runs once the update is done.";
+export function createPersonalQueueRuntime(options) {
+    const { store } = options, clock = options.clock ?? (() => new Date());
+    const queue = new PersonalQueue(store);
+    const runner = `personal:${process.pid}:${randomUUID()}`;
+    /** A deferred message's admission stamp: it is not tried again until something that refused it changes. */
+    const waiting = new Map();
+    let timer = null, closed = false, passing = false;
+    /** The server's own async context, captured at start (no request in it). A wake from inside a browser request runs
+     * its pass from here, so no request's session facts (its actor, form token or Passwordless session) ever reach a
+     * queued turn — the queue re-proves each message's person itself. */
+    let detached = null;
+    const active = new Set();
+    /** What openLeadTurn checks for this person, and the chat configuration (its caps and budget), with a minute bucket
+     * as the belt for what is not named here (weekly and monthly spend roll over within it): a change wakes a waiting message. */
+    function stamp(row) {
+        const now = clock();
+        const live = store.handle.prepare("SELECT id, state FROM mate_turn WHERE approver = ? AND state IN ('queued','running') ORDER BY id").all(row.approver);
+        const liveChat = store.handle.prepare("SELECT id, state FROM chat_turn WHERE approver = ? AND state IN ('queued','running') ORDER BY id").all(row.approver);
+        const session = store.getLeadSession(row.session);
+        const latched = store.handle.prepare("SELECT COUNT(*) AS n FROM chat_turn WHERE approver = ? AND unknown_spend = 1 AND acknowledged_at IS NULL").get(row.approver);
+        return createHash("sha256").update(JSON.stringify([live, liveChat, store.chatTurnsToday(row.approver, now), session?.spentMicrousd ?? null,
+            session?.ceilingMicrousd ?? null, latched?.["n"] ?? 0, updateAdmissionPaused(store.raw()), options.provider()?.config ?? null, Math.floor(now.getTime() / 60_000)])).digest("hex");
+    }
+    /** The person as the row was sent: same generation, same session (live, theirs), same projects. Null: it can't run. */
+    function standing(row) {
+        const session = store.getLeadSession(row.session);
+        if (session === null || session.endedAt !== null || session.approver !== row.approver)
+            return { ok: false, why: "Not sent: this conversation ended before it ran." };
+        const verified = verifyApproverStanding(store, row.approver, row.approverGeneration, options.admittedReposFor(row.approver));
+        if (!verified.ok)
+            return { ok: false, why: "Not sent: your access changed before it ran." };
+        if (verified.who.ceilingDigest !== row.ceilingDigest || session.ceilingDigest !== row.ceilingDigest)
+            return { ok: false, why: "Not sent: your projects changed before it ran." };
+        const thread = store.getLeadThread(row.thread);
+        if (thread === null || thread.closedAt !== null)
+            return { ok: false, why: "Not sent: this conversation was closed before it ran." };
+        if (row.context !== null && !options.contextStands(row.approver, row.context))
+            return { ok: false, why: "Not sent: the task it was about is no longer available." };
+        return { ok: true, who: verified.who };
+    }
+    const verifiedWho = (who) => who;
+    async function run(claim) {
+        let progress;
+        let outcome;
+        try {
+            const proof = standing(claim);
+            if (!proof.ok) {
+                queue.finish(claim, { status: "failed", error: proof.why }, clock());
+                return;
+            }
+            const provider = options.provider();
+            if (provider === null) {
+                if (queue.defer(claim, "Waiting: chat is off. It runs once chat is on again."))
+                    waiting.set(claim.message, stamp(claim));
+                return;
+            }
+            // An update is being installed (or the console is stopping): the message waits for the next start, words kept.
+            const holding = () => closed || updateAdmissionPaused(store.raw());
+            if (holding()) {
+                if (queue.defer(claim, UPDATE_WAIT))
+                    waiting.set(claim.message, stamp(claim));
+                return;
+            }
+            let held = false;
+            const session = store.getLeadSession(claim.session), thread = store.getLeadThread(claim.thread);
+            const context = leadTurnContext(store, claim.context, options.names);
+            outcome = await runLeadTurn({
+                store, who: proof.who, session, thread, config: provider.config, key: provider.key, message: claim.text, requestId: claim.requestId,
+                queuedMessageId: claim.message, queueClaim: { message: claim.message, runner: claim.runner, generation: claim.generation },
+                // The live reply display starts only once this message holds the turn: a refused attempt never blanks the display
+                // of a turn that is still running in the same conversation.
+                onAdmitted: turn => {
+                    if (!queue.bindTurn(claim, turn))
+                        throw new Error("The queued message changed before admission.");
+                    progress = options.live?.begin(claim.thread);
+                },
+                ...(context === undefined ? {} : { context }), channel: "console", clock, evidenceRoot: options.evidenceRoot,
+                ...(options.live === undefined ? {} : { onProgress: (event) => progress?.(event) }),
+                // Before every step: still this claim, still this person at this generation and session, still the same projects.
+                revalidate: async () => {
+                    if (holding()) {
+                        held = true;
+                        return { ok: false, reason: "access-changed" };
+                    }
+                    return queue.current(claim) && standing(claim).ok ? { ok: true } : { ok: false, reason: "access-changed" };
+                },
+                ...(options.fetcher === undefined ? {} : { fetcher: options.fetcher }),
+                ...(options.subscriptionRunner === undefined ? {} : { subscriptionRunner: options.subscriptionRunner }),
+            });
+            if (outcome.ok) {
+                queue.finish(claim, { status: "answered", turnId: outcome.turn }, clock());
+                return;
+            }
+            if ("refused" in outcome) {
+                // Refused before admission because an update paused it: that is a wait too (the words stay; the pause ending wakes it).
+                if (outcome.refused === "channel" && held) {
+                    if (queue.defer(claim, UPDATE_WAIT))
+                        waiting.set(claim.message, stamp(claim));
+                }
+                else if (WAITS.has(outcome.refused)) {
+                    if (queue.defer(claim, `Waiting: ${outcome.message}`))
+                        waiting.set(claim.message, stamp(claim));
+                }
+                else
+                    queue.finish(claim, { status: "failed", error: `Not sent: ${outcome.message}` }, clock());
+                return;
+            }
+            // After admission: settled from the turn's record; an unknown outcome is never sent again.
+            queue.finish(claim, { status: "unknownSpend" in outcome && outcome.unknownSpend ? "uncertain" : "failed", error: outcome.message, ...("turn" in outcome ? { turnId: outcome.turn } : {}) }, clock());
+        }
+        catch {
+            queue.finish(claim, { status: "uncertain", error: "Delivery could not be confirmed. Nothing was sent again." }, clock());
+        }
+        finally {
+            if (progress !== undefined)
+                options.live?.end(claim.thread, outcome?.ok === true, progress);
+        }
+    }
+    async function pass() {
+        if (closed || passing || store.isDemo())
+            return;
+        passing = true;
+        try {
+            queue.reconcile(clock(), TURN_WALL_CLOCK_MS + 60_000);
+            for (;;) {
+                const claim = queue.claimNext(runner, clock(), row => waiting.get(row.message) !== stamp(row));
+                if (claim === null)
+                    break;
+                waiting.delete(claim.message);
+                const work = run(claim);
+                active.add(work);
+                void work.finally(() => active.delete(work)).catch(() => undefined);
+            }
+        }
+        finally {
+            passing = false;
+        }
+    }
+    return {
+        queue,
+        /** Look now (a turn just ended, a message was just queued): the next message of each person may start. Safe to call
+         * from a request: the pass runs in the server's own context, never the caller's. Before start, the timer will look. */
+        kick() {
+            const scope = detached;
+            if (scope === null || closed)
+                return;
+            scope.runInAsyncScope(() => { setImmediate(() => { void pass(); }); });
+        },
+        start() {
+            if (timer !== null || closed)
+                return;
+            detached = new AsyncResource("lead-queue-runtime");
+            detached.runInAsyncScope(() => { timer = setInterval(() => { void pass(); }, options.everyMs ?? 2_000); timer.unref(); });
+        },
+        async close() { closed = true; if (timer !== null)
+            clearInterval(timer); timer = null; await Promise.allSettled([...active]); },
+    };
+}

package/dist/lead-queue.d.ts

@@ -0,0 +1,104 @@
+import type { Store } from "./store.js";
+/** At most this many messages wait per person, and this many characters in all; a waiting message expires after 7 days. */
+export declare const LEAD_QUEUE_MAX_MESSAGES = 10;
+export declare const LEAD_QUEUE_MAX_CHARS = 20000;
+export declare const LEAD_QUEUE_EXPIRY_MS: number;
+/** What a queued message was sent with: resolved and validated at send, re-validated before its turn. */
+export type LeadQueueContext = {
+    task?: string;
+    result?: number;
+    mode?: string;
+    project?: string;
+};
+export type LeadQueueStatus = "queued" | "running" | "answered" | "failed" | "cancelled" | "uncertain";
+export type LeadQueueRow = {
+    message: number;
+    thread: number;
+    approver: string;
+    approverGeneration: number;
+    session: number;
+    ceilingDigest: string;
+    requestId: string;
+    payloadHash: string;
+    context: LeadQueueContext | null;
+    status: LeadQueueStatus;
+    revision: number;
+    generation: number;
+    runner: string | null;
+    turnId: number | null;
+    error: string | null;
+    createdAt: string;
+    text: string;
+};
+/** A claimed row: the fence every later step re-proves (status running, this runner, this generation and revision). */
+export type LeadQueueClaim = LeadQueueRow & {
+    runner: string;
+    status: "running";
+};
+/** The identity of a send: the same request with the same words and context is the same message. */
+export declare function leadQueuePayloadHash(thread: number, text: string, context: LeadQueueContext | null): string;
+export type SendDecision = {
+    kind: "run";
+} | {
+    kind: "queued";
+    row: LeadQueueRow;
+    already: boolean;
+} | {
+    kind: "conflict";
+} | {
+    kind: "full";
+    message: string;
+};
+export declare class PersonalQueue {
+    private readonly store;
+    constructor(store: Store);
+    private get db();
+    /** The approver's backlog: rows waiting or claimed but not yet bound to a turn, oldest first. */
+    backlog(approver: string): LeadQueueRow[];
+    /** Every queue row of a thread (what the thread shows next to its messages). */
+    forThread(thread: number): LeadQueueRow[];
+    get(message: number): LeadQueueRow | null;
+    /**
+     * 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: {
+        approver: string;
+        approverGeneration: number;
+        session: number;
+        ceilingDigest: string;
+        thread: number;
+        text: string;
+        requestId: string;
+        context: LeadQueueContext | null;
+    }, now: Date): SendDecision;
+    /**
+     * 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: string, now: Date, eligible?: (row: LeadQueueRow) => boolean): LeadQueueClaim | null;
+    /** The claim still stands: running, this runner, this generation and revision, unbound or bound to `turn`. */
+    current(claim: LeadQueueClaim): boolean;
+    /** Inside the engine's admission transaction (onAdmitted): the claim binds to the turn that took it, exactly once. */
+    bindTurn(claim: LeadQueueClaim, turnId: number): boolean;
+    /** 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: LeadQueueClaim, result: {
+        status: "answered" | "failed" | "cancelled" | "uncertain";
+        error?: string;
+        turnId?: number;
+    }, now: Date): boolean;
+    /** A refusal before admission (a cap, a budget, a latch, another turn): back to waiting with the words to show. */
+    defer(claim: LeadQueueClaim, error: string): boolean;
+    /** Remove a waiting message (its author only, while it still waits): its words are forgotten, its request kept. */
+    remove(approver: string, message: number, now: Date): "removed" | "started" | "not-found";
+    /** 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: Date, turnDeadlineMs: number): number;
+    /** End every waiting message sent under a session (it ended, or its person's chat was revoked). */
+    cancelForSession(session: number, why: string, now: Date): number;
+    /** A message that never ran keeps no words, context or search copy (it stays pending, so never history). */
+    private forgetWords;
+}