toolroll 0.9.104 → 0.9.105

package/dist/chat-messages.js

@@ -1,37 +1,12 @@
-/**
- * The chat core's messages, buttons and deliveries, for any chat app: what an app received (updates, and messages the
- * lead answers, queued, claimed and finished), the reply parts planned before any send and settled on the app's own
- * message id, the one-tap buttons behind decision, proposal, flow and question cards, the sent messages a reply can be
- * about, and each paired person's notification receipts and away-mode digest. Every query names its provider
- * (ChatCore.prepare), so one app's rows never reach another's. Telegram runs on it today through the store's
- * Telegram-named methods (one line each); the adapters keep only their transport.
- *
- * Imports the store's types only (no runtime cycle): the store builds its chats on it.
- */
 import { neverHeld, watchedPing } from "./agent-board.js";
 import { ChatCore } from "./chat-core.js";
 import { unsentPart, unsent } from "./chat-message-states.js";
 import { readChatMessageBody, readChatPart, savedChatEventBody, savedChatPart } from "./contracts/chat-content.js";
 import { isTelegramProgressNotification, proposalTaskOf, readNotification, readNotificationReceipt } from "./notification-rows.js";
-/** v83: a notification for another person, settled for this destination without sending. */
 export const TELEGRAM_SKIPPED_ELSEWHERE = "skipped:for-another-person";
-/** A met promise the lead made on another chat: reported there, settled here without sending. */
 export const TELEGRAM_SKIPPED_OTHER_CHAT = "skipped:for-another-chat";
-/** A fact this person is not messaged about: the lead's work, their own act, or a project they muted. */
 export const TELEGRAM_SKIPPED_QUIET = "skipped:quiet";
-/** A destination receipt (`d` = notification_delivery) that still owes a
- * send: not delivered, and not explicitly skipped as pre-pairing history.
- * Every reader of Telegram receipts that means "undelivered" uses this, so
- * a skip settles the row without ever pretending to be a delivery. */
 export const TELEGRAM_UNSETTLED = "d.delivered_at IS NULL AND (d.receipt IS NULL OR d.receipt NOT LIKE 'skipped:%')";
-/**
- * Why the store itself holds a Telegram delivery back: authority,
- * provenance, ordering, a switched-off channel, or a wait it imposed. A
- * row held for one of these is waiting on policy, not failing on the wire.
- * Every other error recorded on a receipt came from an actual send, and
- * THAT is delivery trouble (`pendingForAttention`). One table, so the
- * fences and the tally can never disagree about the words.
- */
 export const TELEGRAM_HOLD_REASONS = Object.freeze({
     authority: "Telegram pairing or actor authorization changed",
     destination: "Telegram destination changed",
@@ -45,16 +20,13 @@ export const TELEGRAM_HOLD_REASONS = Object.freeze({
     order: "Earlier task notification is still undelivered",
     disabled: "Telegram delivery is disabled",
 });
-/** A Telegram message the lead answers is its event m<update id>, read with the pairing it came from. */
 const TELEGRAM_CONVERSATION_SELECT = `SELECT e.*, b.approver AS paired_approver, b.generation AS paired_generation
   FROM chat_event e JOIN chat_binding b ON b.provider = e.provider AND b.id = e.binding
   WHERE e.provider = :provider AND e.kind = 'message'`;
-/** In update order. */
 const TELEGRAM_CONVERSATION_ORDER = "CAST(substr(e.id, 2) AS INTEGER)";
 function readTelegramConversation(row) {
     const text = (key) => (row[key] === null || row[key] === undefined ? null : String(row[key]));
     const int = (key) => (row[key] === null || row[key] === undefined ? null : Number(row[key]));
-    // A message dropped when its chat was unpaired keeps no words.
     const read = readChatMessageBody(String(row["payload"]));
     const body = read.ok ? read.value : {};
     const update = Number(String(row["id"]).slice(1));
@@ -89,7 +61,6 @@ function readTelegramConversation(row) {
         finishedAt: text("finished"),
     };
 }
-/** One planned part of a Telegram reply (chat_part, its content by contracts/chat-content.ts). */
 function readTelegramConversationPart(row, conversation) {
     const text = (key) => (row[key] === null || row[key] === undefined ? null : String(row[key]));
     const read = readChatPart(String(row["payload"]));
@@ -103,7 +74,6 @@ function readTelegramConversationPart(row, conversation) {
         kind,
         text: content.text,
         replyTo: content.replyTo ?? null,
-        // A card's proposal, while it exists (a deleted one reads as gone).
         proposal: content.proposal !== undefined && Number(row["proposal_live"] ?? 1) === 1 ? content.proposal : null,
         keyboard: content.keyboard === undefined ? null : content.keyboard.map(line => line.map(button => ({ ...button, text: button.text, callback_data: button.callback_data }))),
         state: String(row["state"]),
@@ -155,22 +125,18 @@ export class ChatMessages extends ChatCore {
          VALUES (:provider, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
             .run(action.token, action.binding, action.chatId, action.messageId ?? null, action.decision, action.optionId, action.phase, now.toISOString(), action.ttlMs === undefined ? null : new Date(now.getTime() + action.ttlMs).toISOString(), action.noteDigest ?? null);
     }
-    /** Which decision an outbound Telegram message carried. Recorded after the
-     * send returns its id; a send whose record was lost routes nothing. */
     recordDecisionMessage(binding, chatId, messageId, decision, now) {
         this
             .prepare(`INSERT OR IGNORE INTO chat_message_ref (provider, binding, chat, message, kind, decision, created)
          VALUES (:provider, ?, ?, ?, 'decision', ?, ?)`)
             .run(binding, chatId, messageId, decision, now.toISOString());
     }
-    /** The decision behind an exact replied-to message, or nothing. Never "the latest". */
     decisionForMessage(binding, chatId, messageId) {
         const row = this
             .prepare("SELECT decision FROM chat_message_ref WHERE provider = :provider AND kind = 'decision' AND binding = ? AND chat = ? AND message = ?")
             .get(binding, chatId, messageId);
         return row === undefined ? null : Number(row["decision"]);
     }
-    /** The one live, unexpired draft for a decision, if any. */
     liveNoteDraft(binding, decision, now) {
         const row = this
             .prepare(`SELECT id, note, event, state FROM chat_note_draft
@@ -180,13 +146,6 @@ export class ChatMessages extends ChatCore {
             ? null
             : { id: Number(row["id"]), note: String(row["note"]), updateId: Number(row["event"]), state: String(row["state"]) };
     }
-    /**
-     * Persist a validated note as the live draft. A newer update SUPERSEDES
-     * the old draft — drafts are immutable, and only a GREATER update_id may
-     * replace one, so out-of-order delivery cannot resurrect an older note
-     * (Codex free-text review, state machine). Returns false when an older
-     * or equal update tried.
-     */
     saveNoteDraft(draft, now, ttlMs = 10 * 60_000) {
         return this.store.transact(() => {
             const chat = this;
@@ -205,8 +164,6 @@ export class ChatMessages extends ChatCore {
             return true;
         });
     }
-    /** Move a draft to `to`, only from one of the states in `from` (the check and the write are one statement). True when
-     * it moved; false when the draft was in none of them. The caller owns the transaction story. */
     setNoteDraftState(id, from, to) {
         return Number(this.prepare("UPDATE chat_note_draft SET state = ? WHERE provider = :provider AND id = ? AND state IN (SELECT value FROM json_each(?))")
             .run(to, id, JSON.stringify(from)).changes) === 1;
@@ -231,7 +188,6 @@ export class ChatMessages extends ChatCore {
         for (const token of tokens)
             place.run(messageId, token);
     }
-    /** Retire every button (and prompt) for one visit of a card, in every chat app: it was decided, or its draft replaced. */
     retireFlowVisit(card, entry, now) {
         const stamp = now.toISOString();
         this.db.prepare("UPDATE chat_flow_action SET consumed = ? WHERE card = ? AND entry = ? AND consumed IS NULL").run(stamp, card, entry);
@@ -243,7 +199,6 @@ export class ChatMessages extends ChatCore {
         chat.prepare("INSERT INTO chat_flow_prompt (provider, id, chat, message, binding, card, entry, mode, created, expires) VALUES (:provider, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
             .run(chat.nextId("chat_flow_prompt"), prompt.chatId, prompt.messageId, prompt.binding, prompt.card, prompt.entry, prompt.mode, now.toISOString(), new Date(now.getTime() + hours * 3_600_000).toISOString());
     }
-    /** The live prompt a message replies to, if any. */
     flowPrompt(chatId, messageId, now) {
         const row = this.prepare("SELECT * FROM chat_flow_prompt WHERE provider = :provider AND chat = ? AND message = ? AND consumed IS NULL AND expires > ?").get(chatId, messageId, now.toISOString());
         if (row === undefined)
@@ -290,7 +245,6 @@ export class ChatMessages extends ChatCore {
         for (const token of tokens)
             place.run(messageId, token);
     }
-    /** Retire every button and prompt for a question, in every chat app: it was answered (anywhere). */
     retireQuestion(question, now) {
         const stamp = now.toISOString();
         this.db.prepare("UPDATE chat_question_action SET consumed = ? WHERE question = ? AND consumed IS NULL").run(stamp, question);
@@ -310,17 +264,11 @@ export class ChatMessages extends ChatCore {
         const row = this.prepare("SELECT * FROM chat_action WHERE provider = :provider AND token = ? AND decision IS NOT NULL").get(token);
         return row === undefined ? null : readTelegramAction(row);
     }
-    /**
-     * Kill every live confirm/cancel challenge on a decision. Cancel means
-     * cancelled: a confirm that survived its own cancellation would be an
-     * irreversible choice still armed after the person said stop.
-     */
     consumeChallenges(decision, now) {
         this
             .prepare("UPDATE chat_action SET consumed = ? WHERE provider = :provider AND decision = ? AND phase IN ('confirm','cancel') AND consumed IS NULL")
             .run(now.toISOString(), decision);
     }
-    /** Consume once. False means somebody already did, or it expired — either way, no. */
     consumeDecisionAction(token, now) {
         const stamp = now.toISOString();
         const { changes } = this
@@ -328,15 +276,11 @@ export class ChatMessages extends ChatCore {
             .run(stamp, token, stamp);
         return Number(changes) > 0;
     }
-    /** Stamp the message a choose-action's keyboard actually landed on. */
     placeDecisionActions(tokens, messageId) {
         const place = this.prepare("UPDATE chat_action SET message = ? WHERE provider = :provider AND token = ?");
         for (const token of tokens)
             place.run(messageId, token);
     }
-    /** A Telegram message this bot sent that showed one task (v79): a reply to
-     * it is about that task (and that result, when it showed one). A message
-     * edited to show something else forgets it. */
     recordTaskMessage(binding, messageId, taskId, run, now) {
         const chat = this;
         if (taskId === null) {
@@ -347,23 +291,18 @@ export class ChatMessages extends ChatCore {
       ON CONFLICT (provider, binding, chat, message, kind) WHERE kind <> 'notification' DO UPDATE SET task_id = excluded.task_id, run = excluded.run, created = excluded.created`)
             .run(binding.id, binding.chatId, messageId, taskId, run, now.toISOString());
     }
-    /** v98: an update Telegram pushed, kept (queued, with its body) until the bridge applies it; false when it's already kept or applied. */
     queueUpdate(botId, updateId, payload, now) {
         return Number(this.prepare(`INSERT OR IGNORE INTO chat_event (provider, id, installation, kind, channel, member, ts, thread, payload, created, state)
       VALUES (:provider, ?, ?, 'update', '', '', '', '', ?, ?, 'queued')`).run(String(updateId), botId, payload, now.toISOString()).changes) === 1;
     }
-    /** v98: pushed updates waiting for the bridge, oldest first. */
     inbox(botId, limit) {
         return this.prepare(`SELECT id, payload FROM chat_event WHERE provider = :provider AND kind = 'update' AND state = 'queued' AND installation = ?
       ORDER BY CAST(id AS INTEGER) LIMIT ?`).all(botId, limit)
             .map(row => ({ updateId: Number(row["id"]), payload: String(row["payload"]) }));
     }
-    /** A pushed update the bridge is done with: applied (then its receipt stays), or unreadable (then it is gone). */
     dropInbox(updateId) {
         this.prepare("DELETE FROM chat_event WHERE provider = :provider AND id = ? AND kind = 'update' AND state = 'queued'").run(String(updateId));
     }
-    /** True if this update has not been applied before. The (provider, id) key is the idempotency; a pushed update waiting
-     * in the inbox is applied in place. A receipt names only its update, as it always has. */
     markUpdateApplied(updateId, result, now) {
         const { changes } = this
             .prepare(`INSERT INTO chat_event (provider, id, installation, kind, channel, member, ts, thread, payload, created, state, result)
@@ -373,7 +312,6 @@ export class ChatMessages extends ChatCore {
             .run(String(updateId), now.toISOString(), result);
         return Number(changes) > 0;
     }
-    /** Persist one ordinary message before its update is acknowledged (event m<update id>). The caller's transaction also marks the update applied. */
     enqueueMessage(row, now) {
         const body = { text: row.text, request: row.request, ...(row.context === null ? {} : { context: row.context }),
             ...(row.taskId === null ? {} : { about: { task: row.taskId, run: row.sourceRun } }) };
@@ -383,11 +321,9 @@ export class ChatMessages extends ChatCore {
             .run(`m${row.updateId}`, row.binding.botId, row.binding.id, row.binding.chatId, row.binding.userId, row.messageId, row.replyTo ?? "", savedChatEventBody(body), now.toISOString());
         return row.updateId;
     }
-    /** How many of this chat's messages wait for, or are being answered by, the lead (the lead queue's bound per chat). */
     messagesWaiting(binding) {
         return Number(this.prepare("SELECT COUNT(*) AS n FROM chat_event WHERE provider = :provider AND kind = 'message' AND binding = ? AND state IN ('queued', 'running')").get(binding)?.["n"] ?? 0);
     }
-    /** Whether a message from this chat is already waiting on, or being answered from, this bot message (a tapped question). */
     messageWaitingOn(binding, messageId) {
         return this.prepare("SELECT 1 AS hit FROM chat_event WHERE provider = :provider AND kind = 'message' AND binding = ? AND ts = ? AND state IN ('queued', 'running') LIMIT 1").get(binding, messageId) !== undefined;
     }
@@ -398,15 +334,9 @@ export class ChatMessages extends ChatCore {
     listMessages(botId) {
         return this.prepare(`${TELEGRAM_CONVERSATION_SELECT} AND e.installation = ? ORDER BY ${TELEGRAM_CONVERSATION_ORDER}`).all(botId).map(readTelegramConversation);
     }
-    /**
-     * Claim the oldest message that still needs a turn: queued, or running
-     * under a claim that lapsed (a crash mid-turn), and not deferred past now.
-     * One at a time per bot — the lead runs one turn per approver anyway.
-     */
     claimMessage(botId, owner, ttlMs, now, only) {
         return this.store.transact(() => {
             const chat = this, stamp = now.toISOString();
-            // "turns": still needs the assistant; "replies": the reply is planned and only sending remains.
             const planned = "EXISTS (SELECT 1 FROM chat_part p WHERE p.provider = e.provider AND p.event = e.id)";
             const which = only === "turns" ? `AND NOT ${planned}` : only === "replies" ? `AND ${planned}` : "";
             const row = chat
@@ -426,40 +356,24 @@ export class ChatMessages extends ChatCore {
             return this.getMessage(Number(String(row["id"]).slice(1)));
         });
     }
-    /** Extend a held claim; false means it lapsed and somebody else may hold the row. */
     renewMessage(id, owner, ttlMs, now) {
         const { changes } = this
             .prepare("UPDATE chat_event SET claim_until = ? WHERE provider = :provider AND id = ? AND claim_owner = ? AND claim_until > ? AND state = 'running'")
             .run(new Date(now.getTime() + ttlMs).toISOString(), `m${id}`, owner, now.toISOString());
         return Number(changes) === 1;
     }
-    /**
-     * Bind the session a turn is about to be dispatched under, BEFORE the
-     * dispatch: the engine receipts the request inside that session, so a
-     * later attempt — after a crash, even after the session was ended and
-     * replaced from the console — reads the receipt where it was written
-     * instead of resolving today's session and finding nothing there.
-     */
     bindMessageSession(id, owner, session) {
         const { changes } = this
             .prepare("UPDATE chat_event SET session = ? WHERE provider = :provider AND id = ? AND claim_owner = ? AND state = 'running'")
             .run(session, `m${id}`, owner);
         return Number(changes) === 1;
     }
-    /** Bind the admitted turn to its row as soon as the engine's receipt names it. */
     bindMessageTurn(id, owner, session, turn) {
         const { changes } = this
             .prepare("UPDATE chat_event SET session = ?, turn = ? WHERE provider = :provider AND id = ? AND claim_owner = ?")
             .run(session, turn, `m${id}`, owner);
         return Number(changes) === 1;
     }
-    /**
-     * Settle a claimed row: done or failed with its outcome word, or back to
-     * queued for a later attempt (a busy engine). Only the claim holder may;
-     * a lapsed claim settles nothing, so a reclaimer's outcome stands.
-     * Telegram writes done here only once every part of the reply was sent
-     * or dropped; what done means on each app is in chat-message-states.ts.
-     */
     finishMessage(id, owner, result, now) {
         const stamp = now.toISOString(), chat = this;
         const { changes } = result.state === "queued"
@@ -474,12 +388,6 @@ export class ChatMessages extends ChatCore {
                 .run(result.state, result.outcome, result.replyMessageId ?? null, stamp, `m${id}`, owner, stamp);
         return Number(changes) === 1;
     }
-    /**
-     * Replies the assistant wrote that still have not reached the person
-     * `since` ago or longer (status and the console show them with a Retry):
-     * the message's row, whose it is, when the oldest unsent part was
-     * written, and the last send error.
-     */
     unsentReplies(botId, approver, since) {
         return this
             .prepare(`SELECT c.id, b.approver, MIN(p.created) AS since,
@@ -491,7 +399,6 @@ export class ChatMessages extends ChatCore {
             .all(botId, botId, approver, approver, since.toISOString())
             .map(row => ({ conversation: Number(String(row["id"]).slice(1)), approver: String(row["approver"]), since: String(row["since"]), error: row["error"] === null ? null : String(row["error"]) }));
     }
-    /** Send unsent replies on the next bridge pass instead of waiting out their backoff; returns how many. */
     retryReplies(approver, now) {
         const { changes } = this
             .prepare(`UPDATE chat_event SET next_at = ?
@@ -501,13 +408,6 @@ export class ChatMessages extends ChatCore {
             .run(now.toISOString(), approver, approver);
         return Number(changes);
     }
-    /**
-     * Persist the whole outbound half of a turn — every reply part and every
-     * card, with the cards' tokens already minted — in one transaction, BEFORE
-     * any send. Only the claim holder may, and only once: a row that already
-     * has parts keeps them (a retry resumes, never re-plans). The turn's
-     * identity rides the row too, so the parts answer to exactly that turn.
-     */
     planReplyParts(id, owner, turn, parts, now) {
         return this.store.transact(() => {
             const chat = this, stamp = now.toISOString(), event = `m${id}`;
@@ -538,14 +438,6 @@ export class ChatMessages extends ChatCore {
         FROM chat_part p WHERE p.provider = :provider AND p.event = ? ORDER BY p.ordinal`)
             .all(`m${conversation}`).map(row => readTelegramConversationPart(row, conversation));
     }
-    /**
-     * Settle one send attempt under the row's claim. A confirmed message id
-     * is the only success: the part is sent, and a reply part's id becomes
-     * the row's reply id. Anything else leaves the part pending with its
-     * attempt counted, its error named, its next attempt scheduled, and —
-     * when the answer was lost rather than refused — its uncertainty counted.
-     * A lapsed claim settles nothing, so a reclaimer's outcome stands.
-     */
     settleReplyPart(conversation, ordinal, owner, outcome, now) {
         return this.store.transact(() => {
             const chat = this, stamp = now.toISOString(), event = `m${conversation}`;
@@ -573,7 +465,6 @@ export class ChatMessages extends ChatCore {
             return true;
         });
     }
-    /** A card whose proposal no longer waits (confirmed or dismissed from another surface, or gone) is moot: dropped with the reason, never sent. */
     dropReplyPart(conversation, ordinal, owner, reason, now) {
         const chat = this, stamp = now.toISOString(), event = `m${conversation}`;
         const held = chat
@@ -586,11 +477,6 @@ export class ChatMessages extends ChatCore {
             .run(reason, event, ordinal);
         return Number(changes) === 1;
     }
-    /** The exact task/run bindings of one outbound message this bot sent: a
-     * plain fact names one, a digest part may name several, (v64) a confirmed
-     * result image names its exact task and run, the lead's reply names the
-     * task its turn was about, a card names its task, and (v79) a status
-     * message names the task it showed. */
     messageBindings(binding, messageId) {
         const chat = this;
         const facts = chat
@@ -603,7 +489,6 @@ export class ChatMessages extends ChatCore {
             run: row["run"] === null ? null : (this.progressRun({ taskRef: row["task_ref"] === null ? null : Number(row["task_ref"]), run: Number(row["run"]) })?.id ?? Number(row["run"])),
             project: row["project"] === null ? null : String(row["project"]),
         }));
-        // Every sent part of this bot's replies on that message, oldest first: images, the lead's replies and its cards.
         const parts = chat
             .prepare(`SELECT p.*, c.payload AS asked, EXISTS (SELECT 1 FROM lead_proposal mp WHERE mp.id = json_extract(p.payload, '$.proposal')) AS proposal_live
           FROM chat_part p JOIN chat_event c ON c.provider = p.provider AND c.id = p.event
@@ -616,8 +501,6 @@ export class ChatMessages extends ChatCore {
             const ref = this.store.lookupRef(taskId);
             return { taskId, taskRef: ref?.id ?? null, run: part.run, project: ref?.repo ?? null, ...(part.run === null || part.artifact === null || part.sha256 === null ? {} : { image: { run: part.run, artifact: part.artifact, sha256: part.sha256 } }) };
         });
-        // The lead's own messages: a reply from a turn that was about one task,
-        // and a card, which names its task (or, once it filed one, the new task).
         const lead = parts.filter(one => one.part.kind !== "image").map(({ part, asked }) => part.kind === "card"
             ? proposalTaskOf(part.proposal === null ? null : this.store.getLeadProposal(part.proposal))
             : asked.ok && asked.value.about !== undefined ? { task: asked.value.about.task, run: asked.value.about.run } : null);
@@ -643,7 +526,6 @@ export class ChatMessages extends ChatCore {
         const row = this.prepare("SELECT * FROM chat_action WHERE provider = :provider AND token = ? AND proposal IS NOT NULL").get(token);
         return row === undefined ? null : readTelegramProposalAction(row);
     }
-    /** Consume once. False means somebody already did, or it expired. */
     consumeProposalAction(token, now) {
         const stamp = now.toISOString();
         const { changes } = this
@@ -651,14 +533,12 @@ export class ChatMessages extends ChatCore {
             .run(stamp, token, stamp);
         return Number(changes) > 0;
     }
-    /** Kill every live token on a proposal — after it resolves, or when a challenge is cancelled. */
     consumeProposalActions(proposal, now, phases) {
         const filter = phases === undefined ? "" : ` AND phase IN (${phases.map(() => "?").join(",")})`;
         this
             .prepare(`UPDATE chat_action SET consumed = ? WHERE provider = :provider AND proposal = ? AND consumed IS NULL${filter}`)
             .run(now.toISOString(), proposal, ...(phases ?? []));
     }
-    /** Stamp the message a card's keyboard actually landed on. */
     placeProposalActions(tokens, messageId) {
         const place = this.prepare("UPDATE chat_action SET message = ? WHERE provider = :provider AND token = ?");
         for (const token of tokens)
@@ -667,17 +547,12 @@ export class ChatMessages extends ChatCore {
     destination(binding) {
         return `telegram:${binding.botId}:${binding.chatId}:${binding.id}:${binding.approverGeneration}`;
     }
-    /** A progress card belongs to one builder result, including its root review.
-     * Do not combine planners, correction children, or separate build attempts. */
     progressRun(row) {
         const source = row.run === null ? null : this.store.getRun(row.run);
         const result = source?.role === "reviewer" && source.reviewAttempt != null && source.parentRun !== null
             ? this.store.getRun(source.parentRun) : source;
         return result?.role === "builder" && result.taskRef === row.taskRef && source?.taskRef === row.taskRef ? result : null;
     }
-    /** Reuse a confirmed message in this exact destination. A mixed digest,
-     * decision, image, or message naming another attempt is never editable. The
-     * outbound history survives a restart even if the final receipt was lost. */
     progressMessage(binding, result) {
         const chat = this, destination = this.destination(binding);
         const messages = chat.prepare(`SELECT DISTINCT message FROM chat_message_ref
@@ -694,26 +569,20 @@ export class ChatMessages extends ChatCore {
         }
         return null;
     }
-    /** The existing outbox, with a separate receipt for this exact pairing. */
     claimDeliveries(binding, owner, ttlMs, now, only = "all") {
         return this.store.transact(() => {
             const destination = this.destination(binding);
             this.db.prepare(`INSERT OR IGNORE INTO notification_delivery (notification, destination)
         SELECT id, ? FROM notification WHERE resolved_at IS NULL`).run(destination);
-            // Someone else's notification is settled here as skipped, never sent —
-            // and never left unsettled, where it would fence that task's later rows.
             this.db.prepare(`UPDATE notification_delivery SET receipt = '${TELEGRAM_SKIPPED_ELSEWHERE}'
         WHERE destination = ? AND delivered_at IS NULL AND receipt IS NULL
           AND notification IN (SELECT id FROM notification WHERE recipient IS NOT NULL AND recipient <> ?)`).run(destination, binding.approver);
-            // A promise the lead made on another chat is reported there (lead-commitments.ts), not here.
             this.db.prepare(`UPDATE notification_delivery SET receipt = '${TELEGRAM_SKIPPED_OTHER_CHAT}'
         WHERE destination = ? AND delivered_at IS NULL AND receipt IS NULL
           AND notification IN (SELECT id FROM notification WHERE dedupe_key LIKE 'lead-promise:%' AND dedupe_key NOT LIKE 'lead-promise:telegram:%')`).run(destination);
-            // Pings follow responsibility (the lead's work, this person's own act, a muted project): settled here, unsent.
             for (const raw of this.db.prepare(`SELECT n.* FROM notification n JOIN notification_delivery d ON d.notification = n.id AND d.destination = ?
           WHERE n.resolved_at IS NULL AND d.delivered_at IS NULL AND d.receipt IS NULL AND (d.claim_owner IS NULL OR d.claim_expires_at <= ?)`).all(destination, now.toISOString())) {
                 const row = readNotification(raw);
-                // A ping about a run this person is watching stays unsettled until the watch lapses, then is decided again.
                 const watched = this.store.pingAllowed(row, binding.approver) ? watchedPing(this.store, row, binding.approver, now) : "skip";
                 if (watched === "skip") {
                     this.db.prepare(`UPDATE notification_delivery SET receipt = '${TELEGRAM_SKIPPED_QUIET}' WHERE notification = ? AND destination = ?`).run(row.id, destination);
@@ -743,7 +612,6 @@ export class ChatMessages extends ChatCore {
             });
         });
     }
-    /** Synchronous final fence, called AFTER each asynchronous enrollment read. */
     deliveryProblem(row, binding, owner, projects, now, batch = [row.id]) {
         const live = this.store.liveTelegramBindingById(binding.id);
         if (live === null || live.approverGeneration !== binding.approverGeneration ||
@@ -761,7 +629,6 @@ export class ChatMessages extends ChatCore {
         if (row.scope === "unknown")
             return TELEGRAM_HOLD_REASONS.provenance;
         if (row.scope === "installation") {
-            // One addressed to this person (their own budget, v105) reaches them; the rest of the installation's are an operator's.
             if (!this.store.isInstanceOperator(binding.approver) && current["recipient"] !== binding.approver)
                 return TELEGRAM_HOLD_REASONS.installation;
         }
@@ -775,16 +642,11 @@ export class ChatMessages extends ChatCore {
                     return TELEGRAM_HOLD_REASONS.task;
             }
         }
-        // A security alert never waits behind its task's earlier pings (one may be held while its person watches the agent).
         if (row.taskRef !== null && !neverHeld(String(current["kind"]))) {
-            // Skipped history never fences what follows it: it is settled.
             const earlier = this.db.prepare(`SELECT n.*, d.next_attempt_at AS held_until, d.last_error AS held_error FROM notification n
         LEFT JOIN notification_delivery d ON d.notification = n.id AND d.destination = ?
         WHERE n.task_ref = ? AND n.id < ? AND n.resolved_at IS NULL AND ${TELEGRAM_UNSETTLED}`)
                 .all(row.destination, row.taskRef, row.id);
-            // One a watch is holding (cockpit §3) keeps nothing behind it: it goes when the watch ends, and what followed
-            // it about another attempt is not that watch's to delay.
-            // Held: deferred by a watch (a future next attempt with no failure behind it), or watched right now.
             const held = (one) => (one["held_until"] != null && String(one["held_until"]) > now.toISOString() && one["held_error"] == null)
                 || typeof watchedPing(this.store, readNotification(one), binding.approver, now) === "object";
             if (earlier.some(one => !batch.includes(Number(one["id"])) && !held(one)))
@@ -792,11 +654,6 @@ export class ChatMessages extends ChatCore {
         }
         return null;
     }
-    /**
-     * The watch at the final fence (cockpit §3, R11): right before the network, a person who has since opened the
-     * agent this ping is about holds it — the claim is released with the watch's end as its next attempt, no attempt
-     * spent — and news about a finished run they have now seen settles quietly. "send": nothing changed.
-     */
     watchFence(row, binding, owner, now) {
         const current = this.db.prepare("SELECT * FROM notification WHERE id = ?").get(row.id);
         if (current === undefined)
@@ -819,8 +676,6 @@ export class ChatMessages extends ChatCore {
       AND claim_owner = ? AND claim_generation = ? AND claim_expires_at > ? AND delivered_at IS NULL`)
             .get(row.id, row.destination, owner, row.claimGeneration, now.toISOString()) !== undefined;
     }
-    /** A confirmed network message remains history even if authority changed
-     * while it was in flight. It only binds the OLD destination, never new work. */
     recordMessage(row, binding, messageId, now) {
         if (row.destination !== this.destination(binding))
             throw new Error("Telegram message destination mismatch");
@@ -829,7 +684,6 @@ export class ChatMessages extends ChatCore {
       VALUES (:provider, ?, ?, ?, 'notification', ?, ?, ?, ?, ?, ?, ?)`)
             .run(binding.id, binding.chatId, messageId, row.id, row.destination, row.project, row.taskRef, row.taskId, row.run, now.toISOString());
     }
-    /** The newest confirmed message this notification became at one destination, if any. */
     messageOf(notification, destination) {
         const row = this.prepare("SELECT message FROM chat_message_ref WHERE provider = :provider AND kind = 'notification' AND notification = ? AND destination = ? ORDER BY CAST(message AS INTEGER) DESC LIMIT 1").get(notification, destination);
         return row === undefined ? null : String(row["message"]);
@@ -840,9 +694,6 @@ export class ChatMessages extends ChatCore {
                 return false;
             if (outcome.ok && (this.store.liveTelegramBindingById(binding.id) === null || this.store.accountOf(binding.approver)?.role !== "approver"))
                 return false;
-            // A `skipped:` receipt settles the row without a delivery: nothing
-            // reached the phone, so delivered_at stays empty exactly as it does
-            // for the pairing skip (TELEGRAM_UNSETTLED treats both as settled).
             const skipped = outcome.ok && outcome.receipt !== null && outcome.receipt.startsWith("skipped:");
             this.db.prepare(`UPDATE notification_delivery SET attempts = attempts + 1, last_attempt_at = ?,
         delivered_at = ?, receipt = ?, last_error = ?, next_attempt_at = ?, claim_owner = NULL, claim_expires_at = NULL
@@ -851,13 +702,11 @@ export class ChatMessages extends ChatCore {
             return true;
         });
     }
-    /** The notifications this pairing holds, each with its delivery state there. */
     deliveries(binding) {
         return this.db.prepare(`SELECT n.*, d.attempts, d.last_attempt_at, d.last_error, d.delivered_at, d.receipt
       FROM notification n JOIN notification_delivery d ON d.notification = n.id WHERE d.destination = ? ORDER BY n.id`)
             .all(this.destination(binding)).map(readNotificationReceipt);
     }
-    /** The digest cadence: null everyMs = off. */
     digest() {
         const row = this.prepare("SELECT every_ms, set_by, set_at, last_sent_at FROM chat_digest WHERE provider = :provider").get();
         return {
@@ -867,8 +716,6 @@ export class ChatMessages extends ChatCore {
             lastSentAt: row?.["last_sent_at"] === null || row?.["last_sent_at"] === undefined ? null : String(row["last_sent_at"]),
         };
     }
-    /** Set (or clear, with null) the cadence. Turning it on starts the
-     * window NOW — nothing held before the choice is dumped at once. */
     setDigest(everyMs, by, now) {
         const chat = this;
         chat.prepare("INSERT OR IGNORE INTO chat_digest (provider) VALUES (:provider)").run();