toolroll 0.9.63 → 0.9.65

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

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);
+    }
+}