toolroll 0.9.104 → 0.9.105

package/dist/telegram-lead.js

@@ -4,27 +4,6 @@ import { CHAT_ACTIONS, sharedActionAllowsChallenge, sharedActionPayload } from "
 import { typedStartOf } from "./typed-start.js";
 import { armedQuestion, taskInCeiling, mirrorToTaskChat, couldNotAnswerText, channelRepos as telegramConversationRepos, resolveChannelLead as resolveTelegramLead, NO_PHONE_LINK, NO_TASK_LINK, phoneProposalLink, confirmedLink, startedTaskLink, phoneProposalPreview, proposalOutcomeText, handoffCardText, confirmedCardText } from "./chat-channel.js";
 export { channelRepos as telegramConversationRepos, resolveChannelLead as resolveTelegramLead, tooLongText, whichTaskText, replyContextFor, NO_PHONE_LINK, NO_TASK_LINK, proposalLink, confirmedLink, proposalPreview, proposalOutcomeText, handoffCardText, confirmedCardText, CHAT_ACTION_PARITY as TELEGRAM_ACTION_PARITY, parityGaps } from "./chat-channel.js";
-/**
- * The paired phone as one more way to use the same assistant.
- *
- * Transport only. An ordinary private Telegram message becomes a lead turn
- * through `runLeadTurn` — the same saved thread, proposal rows, confirm
- * doors and result actions the console and `toolroll chat` use —
- * and every act is still a card the operator confirms. This module owns
- * what is specific to the wire: proving the pairing (chat AND immutable
- * sender AND approver generation AND the enrolled ceiling) before any
- * model call and again after every wait; the durable inbound row that
- * precedes polling acknowledgement; the request identity the engine
- * receipts a turn under so a replay or a restart never dispatches the
- * provider twice; concise previews with opaque one-tap tokens; and the
- * honest words for what a phone cannot do (a password, a cancel, a
- * console-only control).
- *
- * Nothing here mints authority: the principal comes from
- * `verifyApproverStanding` against the live binding row, the session is
- * the approver's own compatible one (or one minted under the same terms
- * the console and CLI state), and the door re-proves everything again.
- */
 import { createHash, randomBytes } from "node:crypto";
 import { leadFailureText, runLeadTurn } from "./lead.js";
 import { confirmLeadProposal, confirmTypedStart, dismissLeadProposal, TYPED_START_STARTED } from "./lead-doors.js";
@@ -38,40 +17,16 @@ import { chatResultHref } from "./chat-controls.js";
 import { resultImageFileName, safeResultImageCaption, verifyResultImage } from "./chat-evidence.js";
 import { telegramButton } from "./contracts/telegram-callback.js";
 import { chatOutcome, isAdmittedWait, isLeadWait } from "./chat-message-states.js";
-/** How long one claimed turn may go without a heartbeat before another poller may take it over. */
 export const CONVERSATION_CLAIM_MS = 2 * 60_000;
-/** A busy engine (one turn at a time) defers a queued message this long, up to the age bound below. */
 export const CONVERSATION_RETRY_MS = 5_000;
 export const CONVERSATION_MAX_AGE_MS = 10 * 60_000;
-/** Waiting for the lead itself (it is answering, or earlier messages wait in the person's lead queue) is bounded longer:
- * two hours from the message's arrival, never reset as it moves from waiting behind the queue to waiting on a turn. */
 export const CONVERSATION_WAIT_MAX_AGE_MS = 2 * 3_600_000;
-/** A card's buttons live this long; its armed Yes and Cancel last CONFIRM_TTL_MS. */
 export const CARD_TTL_MS = 24 * 3_600_000;
-/** Telegram's own message ceiling, with room for our part headers (the same bound telegram.ts splits at). */
 export const PART_CAP = 3_900;
-// ---- the ceiling and the principal --------------------------------------------
-/**
- * The phone's project ceiling: the enrolled registry, canonicalized and
- * deduplicated IN ORDER exactly as the console's managed list is, then
- * narrowed to what this approver's account may access. Order matters —
- * `r1..rN` is an index and the ceiling digest hashes the order — so a
- * console session over the same enrollment shares its digest here.
- */
-/** The engine's request identity for one inbound message: exact bot, binding and update, never text. */
 export function telegramRequestId(botId, bindingId, updateId) {
     return createHash("sha256").update(`telegram:${botId}:${bindingId}:${updateId}`).digest("hex").slice(0, 32);
 }
-/** The one channel problem that is transient: the registry could not be read now. Retried, never a refusal. */
 export const UNREADABLE_REGISTRY = "current project access could not be read";
-/**
- * Is the channel still what a turn opened under? The live binding must be
- * the SAME row and generation, its approver still an approver, and the
- * enrolled ceiling (reloaded now) still the exact list the principal
- * holds — or, for a reply recovered after a restart, the ceiling digest
- * its session was minted under. A string names what changed; null means
- * nothing did.
- */
 export async function telegramChannelProblem(store, expected, readProjects) {
     let registry;
     try {
@@ -93,27 +48,20 @@ export async function telegramChannelProblem(store, expected, readProjects) {
         return "the connected projects changed";
     return null;
 }
-// ---- words ---------------------------------------------------------------------
 export function phoneLinkButton(origin, link) {
     if (origin === null || link === null)
         return null;
     return [{ text: link.label, url: `${origin}${link.path}` }];
 }
-/** Why a card that wanted a link carries none — null when it carries one. */
 function linkNote(origin, link) {
     if (origin === null)
         return NO_PHONE_LINK;
     return link === null ? NO_TASK_LINK : null;
 }
-/** The keyboard as sent: the persisted callback rows, then the link row minted now. */
 function keyboardWith(callbacks, link) {
     const rows = [...(callbacks ?? []), ...(link === null ? [] : [link])];
     return rows.length === 0 ? undefined : rows;
 }
-// ---- proposal cards on the wire ------------------------------------------------------
-/** One inline button: an opaque callback token (a real in-chat act) or a url (navigation, never authority). */
-/** The buttons under the lead's question: options two to a row, then "Something else". Each names the turn and the
- * option's place, nothing more; a tap re-proves that the question is still open and is the tapper's own. */
 export function askKeyboard(ask) {
     const rows = [];
     for (let at = 0; at < ask.options.length; at += 2)
@@ -121,35 +69,21 @@ export function askKeyboard(ask) {
     rows.push([telegramButton(LEAD_ASK_OTHER, `ask:${ask.turn}:x`)]);
     return rows;
 }
-/** Mint the card's tokens before the send, so a tap can never name a token that does not exist. */
 export function mintCardTokens(store, binding, proposal, now, messageId, chatId = binding.chatId) {
     const confirm = randomBytes(16).toString("hex");
     const dismiss = randomBytes(16).toString("hex");
     for (const [token, phase] of [[confirm, "confirm"], [dismiss, "dismiss"]]) {
         store.createTelegramProposalAction({ token, binding: binding.id, proposal, phase, chatId, ttlMs: CARD_TTL_MS, ...(messageId === undefined ? {} : { messageId }) }, now);
     }
-    // A Start card's button says what it does: the card's last line tells the person to tap it (or reply yes).
     const saved = store.getLeadProposal(proposal);
     const label = saved?.kind === "action" && sharedActionPayload(saved.payload)?.operation === "task_start" ? "Start work" : "Confirm";
     return { keyboard: [[telegramButton(label, confirm), telegramButton("Dismiss", dismiss)]], tokens: [confirm, dismiss] };
 }
-/**
- * One tap on a proposal card, applied inside the update's own transaction
- * by the bridge (which already proved the live binding, the exact sender
- * and the exact chat). Returns what to tell Telegram afterwards. The
- * principal is minted from the binding row against the CURRENT enrolled
- * ceiling; the door re-proves standing, ceiling, session and the
- * proposal's own terms again inside its transaction.
- */
 export function applyProposalTap(store, binding, token, message, repos, options, now) {
     const effects = [];
     const ack = (text) => { effects.push({ kind: "ack", text }); };
     const edit = (text, keyboard) => { effects.push({ kind: "edit", text, ...(keyboard === undefined ? {} : { keyboard }) }); };
     const action = store.getTelegramProposalAction(token);
-    // The tap must land where the card was placed. In a paired private chat
-    // that is the tapper's own binding; in a group that follows a team
-    // conversation any paired member may tap, and the door then proves that
-    // person's own membership and consent.
     const tapChatId = message.chat === undefined ? binding.chatId : String(message.chat.id);
     const selected = store.telegramTeamChat(binding.botId, tapChatId);
     const groupCard = tapChatId !== binding.chatId && selected?.kind === "group";
@@ -167,9 +101,6 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         edit("This card no longer exists.");
         return { effects, confirmed: false, ignored: true };
     }
-    // A card belongs to the selected conversation, not merely the same
-    // Telegram group. Check the tapper before rendering even an outcome or a
-    // challenge: a paired outsider must learn none of the proposal's details.
     let actionRepos = repos;
     const shared = store.handle.prepare("SELECT id FROM team_conversation WHERE thread = ?").get(proposal.thread);
     if (groupCard || shared !== undefined) {
@@ -185,7 +116,7 @@ export function applyProposalTap(store, binding, token, message, repos, options,
                     allowed = groupCard ? audience.conversation.visibility === "team" : grant.id === binding.id;
                 }
             }
-            catch { /* Refuse without disclosing a proposal outside current access. */ }
+            catch { }
         }
         if (!allowed) {
             ack("that button is no longer available in this conversation");
@@ -193,15 +124,12 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         }
     }
     if (proposal.state !== "pending") {
-        // Already acted on — here, on the console, or from the terminal. The
-        // card shows the recorded outcome; nothing runs twice.
         store.consumeTelegramProposalActions(proposal.id, now);
         ack(proposal.state === "confirmed" ? "already done" : proposal.state === "dismissed" ? "already dismissed" : "already acted on");
         edit(proposalOutcomeText(proposal));
         return { effects, confirmed: false, ignored: true };
     }
     if (actionRepos === null) {
-        // The registry could not be read: the token stays live for a retry.
         ack("project access could not be read — tap again in a moment");
         return { effects, confirmed: false, ignored: true };
     }
@@ -231,7 +159,6 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         return { effects, confirmed: false, ignored: !done };
     }
     if (action.phase === "cancel") {
-        // Cancel means cancelled: the armed yes dies with it and the card is restored.
         store.consumeTelegramProposalAction(token, now);
         store.consumeTelegramProposalActions(proposal.id, now, ["yes", "cancel"]);
         const fresh = mintCardTokens(store, binding, proposal.id, now, String(message.message_id), tapChatId);
@@ -240,8 +167,6 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         return { effects, confirmed: false, ignored: false };
     }
     if (!preview.buttons) {
-        // A forged keyboard on a handoff card: nothing acts; the card is
-        // repainted with its current link (or the honest absence of one).
         store.consumeTelegramProposalActions(proposal.id, now);
         const wanted = phoneProposalLink(store, proposal, actionRepos, "telegram");
         const link = phoneLinkButton(origin, wanted);
@@ -252,8 +177,6 @@ export function applyProposalTap(store, binding, token, message, repos, options,
     const irreversible = proposal.kind === "answer" && proposal.payload["reversible"] === false;
     const sharedAction = proposal.kind === "action" ? sharedActionPayload(proposal.payload) : null;
     const challenged = sharedAction !== null && sharedActionAllowsChallenge(sharedAction, "telegram");
-    // The arm: two fresh one-time tokens make a real challenge, exactly as a
-    // decision button does. Nothing is answered or recorded here.
     const arm = () => {
         store.consumeTelegramProposalActions(proposal.id, now, ["yes", "cancel"]);
         const yes = randomBytes(16).toString("hex");
@@ -289,7 +212,6 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         return { effects, confirmed: false, ignored: true };
     }
     const outcome = confirmLeadProposal(store, who, proposal.id, now, {
-        // The paired phone speaks for its account's full authority (pairing is a full session's act).
         authority: "full",
         via: "telegram",
         binding: binding.id,
@@ -298,7 +220,6 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         deferSignal: signal => effects.push({ kind: "signal", run: signal }),
     });
     if (!outcome.ok && outcome.reason === "needs-confirm") {
-        // Not armed yet (a card drafted without the reversible mark): arm now, the tap is not lost.
         arm();
         return { effects, confirmed: false, ignored: false };
     }
@@ -309,9 +230,7 @@ export function applyProposalTap(store, binding, token, message, repos, options,
     edit(confirmedCardText(store, outcome, proposal, linkNote(origin, wanted)), keyboardWith(null, link));
     return { effects, confirmed: outcome.ok, ignored: false };
 }
-/** A part's next attempt after a failed send: bounded backoff by attempt, or Telegram's own retry_after when it named a longer one. */
 export const PART_RETRY_MS = [5_000, 15_000, 60_000, 300_000];
-/** Unsent parts are retried this long after the message arrived (the card's own lifetime); then the row fails, explicitly unsent. */
 export const DELIVERY_MAX_AGE_MS = CARD_TTL_MS;
 export function splitParts(text) {
     if (text.length <= PART_CAP)
@@ -326,18 +245,6 @@ export function splitParts(text) {
     }
     return parts;
 }
-/**
- * Run every claimable queued message for this bot, one at a time, each
- * outside any SQLite transaction. The caller holds the poll lease and
- * renews it; the row's own claim is renewed here. Bounded per call so a
- * flood cannot pin one pass forever.
- *
- * `only` splits the work for the follower: "turns" runs the model and
- * persists the reply but leaves the sending to the bridge's own cycle,
- * which calls back with "replies" — so a reply goes out from the same
- * place, in the same order and over the same connection as notifications,
- * never beside a long poll. Absent, a row is answered and sent in one go.
- */
 export async function processTelegramConversations(args) {
     const limit = args.limit ?? 20;
     for (let count = 0; count < limit && args.signal?.aborted !== true; count++) {
@@ -348,7 +255,6 @@ export async function processTelegramConversations(args) {
             await runTelegramConversation(row, args);
         }
         catch (error) {
-            // The claim lapses on its own; the receipt and the persisted parts make the retry safe.
             args.report.problems.push(`telegram chat for update ${row.updateId}: ${error instanceof Error ? error.message : String(error)}`);
             return;
         }
@@ -356,31 +262,14 @@ export async function processTelegramConversations(args) {
 }
 class PlanRefused extends Error {
 }
-/**
- * One claimed message, in order of what is already known about it:
- *
- * 1. Unsent parts exist — the turn already answered; send what remains.
- *    No registry resolution beyond the fence, no model, no proposal.
- * 2. A session was bound before a dispatch — read the engine's receipt
- *    THERE. A receipt names the original turn: recover its outcome, even
- *    if that session has since been ended and replaced from the console.
- * 3. Otherwise resolve the session and thread, bind the session to the
- *    row BEFORE dispatching, run the turn, persist its reply and cards
- *    as parts in one transaction, then send them.
- *
- * Every outgoing part is fenced on the row's claim, the live pairing and
- * the ceiling the turn opened under; only a confirmed message id counts.
- */
 async function runTelegramConversation(row, args) {
     const { store, botId, transport, owner, clock, readProjects, options, report, only } = args;
-    /** The row's live binding as it arrived (pairing alone: a reaction or a waiting draft carries no project data). */
     const stillPaired = () => {
         const live = store.liveTelegramBindingById(row.binding);
         return live !== null && live.botId === botId && live.approverGeneration === row.approverGeneration && store.accountOf(live.approver)?.role === "approver";
     };
     const finish = (result) => {
         const done = store.finishTelegramConversation(row.id, owner, result, clock());
-        // Answered (every part sent) or failed (its notice tried): the 👀 comes off, after what was delivered. Never awaited.
         if (done && (result.state === "done" || result.state === "failed")) {
             forgetWaitingDraft(botId, row.id);
             void telegramAck({ store, botId, transport, clock, chatId: row.chatId, messageId: row.messageId, on: false, paired: stillPaired, ...(options.liveTiming?.ackGapMs === undefined ? {} : { gapMs: options.liveTiming.ackGapMs }) });
@@ -388,15 +277,12 @@ async function runTelegramConversation(row, args) {
         return done;
     };
     const held = () => store.renewTelegramConversation(row.id, owner, CONVERSATION_CLAIM_MS, clock());
-    /** The claim, read (a draft never renews it: only the turn's own heartbeat and durable steps do). */
     const claimed = () => {
         const now = store.getTelegramConversation(row.id);
         return now !== null && now.claimOwner === owner && now.claimExpiresAt !== null && now.claimExpiresAt > clock().toISOString();
     };
     const ageMs = clock().getTime() - Date.parse(row.createdAt);
     const requeue = async (outcome) => {
-        // A turn already admitted for it waits for that turn's own outcome (bounded by the turn's deadline); waiting for the
-        // lead gets two hours from arrival; anything else, ten minutes.
         const limit = isAdmittedWait(outcome) ? Number.POSITIVE_INFINITY : isLeadWait(outcome) ? CONVERSATION_WAIT_MAX_AGE_MS : CONVERSATION_MAX_AGE_MS;
         if (ageMs > limit) {
             await notify(couldNotAnswerText(outcome === "registry-unavailable" ? "your projects couldn't be read" : "the assistant stayed busy with another message"));
@@ -404,16 +290,13 @@ async function runTelegramConversation(row, args) {
             report.refused++;
             return;
         }
-        // Behind the person's own earlier messages: said once, then it waits quietly.
         if (outcome === "backlog" && row.outcome !== "backlog")
             await notify("Queued behind your earlier messages. It goes to the lead once they're answered.");
-        // Waiting for the lead: a draft that says so, refreshed while it waits (never over this chat's running turn).
         if (isLeadWait(outcome)) {
             await telegramWaitingDraft({ store, botId, transport, clock, chatId: row.chatId, binding: row.binding, draftId: row.id, allowed: () => stillPaired() && claimed(), ...(options.liveTiming === undefined ? {} : { timing: options.liveTiming }) });
         }
         finish({ state: "queued", outcome, nextAttemptAt: new Date(clock().getTime() + CONVERSATION_RETRY_MS).toISOString() });
     };
-    // 1. The exact binding the message arrived under must still be the live one.
     const binding = store.liveTelegramBindingById(row.binding);
     if (binding === null || binding.botId !== botId || binding.approverGeneration !== row.approverGeneration || store.accountOf(binding.approver)?.role !== "approver") {
         finish({ state: "failed", outcome: "unpaired" });
@@ -429,7 +312,6 @@ async function runTelegramConversation(row, args) {
             return "the paired account is no longer an approver";
         return null;
     };
-    /** A notice that carries no project data — "this changed, nothing happened" — sent once, best effort, under the pairing fence alone. */
     const notify = async (text, keyboard) => {
         if (pairingProblem() !== null || !held())
             return;
@@ -445,9 +327,7 @@ async function runTelegramConversation(row, args) {
             report.problems.push(`telegram chat notice for update ${row.updateId} could not be sent: Telegram transport failed`);
         }
     };
-    /** The outbound half: send every pending part in order, each fenced; done only when every part is sent or moot. */
     const deliver = async (outcomeWord) => {
-        // The row as it is NOW: the session was bound after this claim read it.
         const bound = store.getTelegramConversation(row.id)?.session ?? null;
         const session = bound === null ? null : store.getLeadSession(bound);
         if (session === null) {
@@ -467,14 +347,11 @@ async function runTelegramConversation(row, args) {
             if (part.kind === "card") {
                 const proposal = part.proposal === null ? null : store.getLeadProposal(part.proposal);
                 if (proposal === null || proposal.state !== "pending") {
-                    // Confirmed or dismissed from the console or the terminal before the card went out: moot, not lost.
                     if (!store.dropTelegramConversationPart(row.id, part.ordinal, owner, proposal === null ? "the proposal is gone" : `the proposal was already ${proposal.state}`, now))
                         return;
                     continue;
                 }
             }
-            // A day from when this part was planned (its card's tokens were minted then), not from the message's arrival: an
-            // answer that waited out a registry outage still gets its full day to go out.
             if (now.getTime() - Date.parse(part.createdAt) > DELIVERY_MAX_AGE_MS) {
                 report.problems.push(`telegram chat reply for update ${row.updateId} was not sent within a day: ${part.lastError ?? "unsent"}`);
                 await notify(couldNotAnswerText("my reply couldn't be sent for a day"));
@@ -482,13 +359,11 @@ async function runTelegramConversation(row, args) {
                 report.refused++;
                 return;
             }
-            // Telegram's own retry_after, shared with the outbox: nothing goes out while it holds.
             const limitedUntil = store.telegramRetryAt(botId);
             if (limitedUntil > now.toISOString()) {
                 defer(new Date(limitedUntil), "Telegram asked for a pause");
                 return;
             }
-            // The channel the reply was composed under, re-proved after ONE registry read; then the claim.
             let registry = null;
             try {
                 registry = await readProjects();
@@ -515,31 +390,13 @@ async function runTelegramConversation(row, args) {
             const backoff = new Date(clock().getTime() + PART_RETRY_MS[Math.min(part.attempts, PART_RETRY_MS.length - 1)]);
             let send;
             let method;
-            /** What Telegram's confirmed message id makes of the part: sent (the reply, a card, an image), or dropped (an image whose refusal notice is now confirmed). */
             let confirm = messageId => store.settleTelegramConversationPart(row.id, part.ordinal, owner, { ok: true, messageId }, clock());
             if (part.kind === "image") {
-                // The image, re-proved NOW — after the registry await, under the
-                // held claim, immediately before the upload, on every attempt: the
-                // task still in this phone's projects, the run still its own, the
-                // artifact row still the one planned from, the bytes read again and
-                // still a bounded PNG/JPEG. Anything less is refused in plain words
-                // and never sent; the exact result is one button away when a
-                // trusted origin can carry it. The original bytes travel untouched.
                 const image = part.taskId === null || part.run === null || part.artifact === null || part.sha256 === null
                     ? { ok: false, problem: "the saved file's record changed" }
                     : verifyResultImage(store, options.evidenceRoot, repos, { taskId: part.taskId, run: part.run, artifact: part.artifact, sha256: part.sha256 });
-                // The caption as persisted, checked again on every attempt: a row
-                // that carries a credential-shaped task id is rebuilt from its typed
-                // identity before a word of it reaches Telegram.
                 const caption = safeResultImageCaption(part.text, part.taskId ?? "", part.run ?? 0);
                 if (!image.ok) {
-                    // The refusal is the part's own message now: it rides the same
-                    // pending row, retry schedule and uncertain count as the upload
-                    // it replaces, and the part is dropped only once Telegram confirms
-                    // the notice. A lost or failed notice is retried after a restart
-                    // like any part; the image is re-verified first each time, so a
-                    // file repaired meanwhile is sent and one still wrong is refused
-                    // again. The row is never done while the notice is unconfirmed.
                     report.problems.push(`telegram chat image for update ${row.updateId} was not sent: ${image.problem}`);
                     const link = part.taskId !== null && part.run !== null && taskInCeiling(store, part.taskId, repos) ? { label: "Open result", path: chatResultHref(part.taskId, part.run) } : null;
                     const button = phoneLinkButton(options.phoneOrigin?.() ?? null, link);
@@ -566,24 +423,16 @@ async function runTelegramConversation(row, args) {
                 }
             }
             else {
-                // A card's link is minted NOW, from the persisted proposal and the
-                // origin configured at this moment: a retry after the setting changed
-                // or went away carries the current truth, never a stored URL.
                 const proposal = part.kind === "card" && part.proposal !== null ? store.getLeadProposal(part.proposal) : null;
                 const origin = proposal === null ? null : options.phoneOrigin?.() ?? null;
                 const wanted = proposal === null ? null : phoneProposalLink(store, proposal, repos);
-                // A typed yes that started a task (one-step-chat.md C5): Toolroll's reply carries the task's link, as a tapped
-                // card does. From the record and the origin read now, like every link.
                 const yes = part.kind === "reply" ? typedStartOf(store, "telegram", `m${row.id}`) : null;
                 const started = yes !== null && yes.outcome === "started" && yes.taskId !== null ? phoneLinkButton(options.phoneOrigin?.() ?? null, startedTaskLink(store, yes.taskId, repos)) : null;
                 const keyboard = keyboardWith(part.keyboard, started ?? phoneLinkButton(origin, wanted));
-                // A Toolroll card: read again now, shown only where every project behind it is still reachable. An unreadable
-                // one goes out as its saved plain words.
                 const isCard = proposal !== null && isCardProposal(proposal);
                 const rich = isCard ? cardOfProposal(proposal) : null;
                 const shown = rich !== null && cardWithin(rich, repos) ? telegramCardMessage(rich) : null;
                 const links = rich === null ? [] : rich.buttons.flatMap(one => phoneLinkButton(origin, one) ?? []).map(one => [one]);
-                // The lead's own words carry their bold anchors and labelled links as entities, never as Markdown characters.
                 const voiced = part.kind === "reply" ? telegramReply(part.text) : null;
                 const text = isCard ? shown?.text ?? (rich === null ? part.text : "This card's projects changed, so it wasn't sent.")
                     : proposal !== null && part.keyboard === null ? handoffCardText(part.text, linkNote(origin, wanted)) : voiced?.text ?? part.text;
@@ -599,9 +448,6 @@ async function runTelegramConversation(row, args) {
                     ...(buttons === undefined ? {} : { reply_markup: { inline_keyboard: buttons } }),
                 });
             }
-            // The first time the answer itself fails to go out, the person hears so once,
-            // in plain words; the reply itself keeps being retried and shows as
-            // unsent in status and the console after two minutes.
             const firstFailure = part.kind === "reply" && store.listTelegramConversationParts(row.id).every(one => one.attempts <= (one.state === "sent" ? 1 : 0));
             const failed = async (until, error, uncertain) => {
                 if (!store.settleTelegramConversationPart(row.id, part.ordinal, owner, { ok: false, error, uncertain, retryAt: until.toISOString() }, clock()))
@@ -615,7 +461,6 @@ async function runTelegramConversation(row, args) {
                 answer = await send();
             }
             catch {
-                // The answer was lost: Telegram may or may not have the message. Said so, retried, counted.
                 await failed(backoff, "Telegram transport failed; delivery may be uncertain", true);
                 return;
             }
@@ -642,28 +487,23 @@ async function runTelegramConversation(row, args) {
             const messageId = String(id);
             if (!confirm(messageId))
                 return;
-            // Placement names the persisted callback tokens only; a url row is not a token.
             if (part.keyboard !== null)
                 store.placeTelegramProposalActions(part.keyboard.flat().map(one => one.callback_data), messageId);
         }
         if (finish({ state: "done", outcome: outcomeWord }))
             report.answered++;
     };
-    /** The reply, one image per screenshot the ANSWERED turn selected (typed identity only — bytes are read and re-verified at send time), and one card per pending proposal, persisted with the cards' tokens in ONE transaction before any send. */
     const plan = (session, turn, reply, proposals, repos) => {
         try {
             return store.transact(() => {
                 const now = clock();
                 const parts = shapeReplyParts(reply, PART_CAP, { asked: row.text, appOrigin: options.phoneOrigin?.() ?? null }, shaped => telegramReply(shaped).text.length).map((text, index) => ({ kind: "reply", text, replyTo: index === 0 ? row.messageId : null }));
-                // The lead's question to its owner: one tap per option, then "Something else".
                 const ask = store.leadAsk(turn);
                 if (ask !== null)
                     parts.push({ kind: "reply", text: phoneText(ask.question, 1_000), keyboard: askKeyboard(ask) });
-                // Only a turn that answered may have its selection sent: a failed or revoked turn's rows were deleted with its drafts, and the state is read again here.
                 const selected = store.getLeadTurn(turn)?.state === "answered" ? store.listLeadTurnEvidence(turn) : [];
                 for (const image of selected)
                     parts.push({ kind: "image", text: image.caption, taskId: image.taskId, run: image.run, artifact: image.artifact, sha256: image.sha256 });
-                // Cards first, so what a card leads to sits right under it. A card mints no tokens: it confirms nothing.
                 for (const proposal of cardsFirst(proposals)) {
                     if (isCardProposal(proposal)) {
                         parts.push({ kind: "card", text: cardPlainOf(proposal), proposal: proposal.id, keyboard: null });
@@ -673,7 +513,6 @@ async function runTelegramConversation(row, args) {
                     const keyboard = preview.buttons ? mintCardTokens(store, binding, proposal.id, now).keyboard : null;
                     parts.push({ kind: "card", text: preview.text, proposal: proposal.id, keyboard });
                 }
-                // A lapsed claim (or parts already planned by another claimant) keeps nothing minted here.
                 if (!store.planTelegramConversationParts(row.id, owner, { session, turn }, parts, now))
                     throw new PlanRefused();
                 return true;
@@ -685,10 +524,7 @@ async function runTelegramConversation(row, args) {
             throw error;
         }
     };
-    /** The recorded turn's outcome — nothing dispatched — from the session it was receipted under. */
     const recover = async (session, turnId, repos) => {
-        // A turn that died past its deadline is swept to failed first, so a
-        // restart reports the truth instead of waiting on a ghost.
         store.sweepStaleLeadTurns(clock());
         const turn = store.getLeadTurn(turnId);
         if (turn === null) {
@@ -713,7 +549,6 @@ async function runTelegramConversation(row, args) {
             return;
         await sendOrHandOff("replayed");
     };
-    /** Send now, or — for the follower's turn worker — leave it to the bridge's cycle, which sends it next. */
     const sendOrHandOff = async (outcomeWord) => {
         if (only !== "turns") {
             await deliver(outcomeWord);
@@ -721,13 +556,10 @@ async function runTelegramConversation(row, args) {
         }
         finish({ state: "queued", outcome: outcomeWord === "answered" ? "answered:sending" : "delivering", nextAttemptAt: clock().toISOString() });
     };
-    // 2. Parts already planned: the turn answered; only the sending remains.
     if (store.listTelegramConversationParts(row.id).length > 0) {
         await deliver(row.outcome === "answered:sending" ? "answered" : "replayed");
         return;
     }
-    // 3. A turn already admitted for it and still working: wait for that turn's own outcome. Nothing here needs the
-    // project records, so a registry that can't be read never fails a message whose turn is running.
     if (row.session !== null) {
         const admitted = store.leadRequestReceipt(row.session, row.request);
         if (admitted !== null) {
@@ -740,45 +572,33 @@ async function runTelegramConversation(row, args) {
             }
         }
     }
-    // The ceiling, reloaded now.
     let registry;
     try {
         registry = await readProjects();
     }
     catch {
         report.problems.push("telegram chat could not read the current project records");
-        // A turn already took it (its receipt is in the bound session): its answer exists or will, and is delivered once
-        // the projects can be read again — never abandoned to the outage.
         const admitted = row.session !== null && store.leadRequestReceipt(row.session, row.request) !== null;
         await requeue(admitted ? "registry-unavailable:admitted" : "registry-unavailable");
         return;
     }
     const repos = telegramConversationRepos(store, binding.approver, registry);
-    // A typed yes to a Start card (docs/plans/one-step-chat.md C5), recorded when the message arrived: Toolroll acts on it
-    // here and no lead turn runs for it. Its outcome and Toolroll's own reply are written in ONE transaction (the claim
-    // fences the reply; a lapsed claim takes the whole act back), then sent like any reply. A settled record returns its
-    // first outcome, so a redelivery or a crash starts nothing more.
     const typed = typedStartOf(store, "telegram", `m${row.id}`);
     if (typed !== null) {
         const verified = verifyApproverStanding(store, binding.approver, binding.approverGeneration, repos);
-        // The card's turn is gone when the chat was ended (its proposals are deleted) or its project deleted: there is then
-        // no session to send a reply under, and nothing can have started. Toolroll says so itself. The yes is never passed on.
         const unanchored = { said: null };
         try {
             store.transact(() => {
                 const now = clock();
                 const answered = confirmTypedStart(store, verified.ok ? verified.who : null, { provider: "telegram", event: typed.event }, now, { binding: binding.id, evidenceRoot: options.evidenceRoot });
-                // The reply is fenced on the session the card was composed under.
                 const card = store.getLeadProposal(typed.proposal);
                 const turn = card === null ? null : store.getLeadTurn(card.turn);
                 if (turn === null) {
-                    // A start without its card can't happen (the door re-reads the card); if it ever did, take it back.
                     if (answered.ok)
                         throw new PlanRefused();
                     unanchored.said = answered.said;
                     return;
                 }
-                // The card is answered: its buttons are spent with it.
                 if (answered.ok)
                     store.consumeTelegramProposalActions(typed.proposal, now);
                 if (!store.planTelegramConversationParts(row.id, owner, { session: turn.session, turn: turn.id }, [{ kind: "reply", text: answered.said, replyTo: row.messageId }], now))
@@ -796,8 +616,6 @@ async function runTelegramConversation(row, args) {
             report.refused++;
             return;
         }
-        // The card it answered is repainted as a tap's would be, best effort: its buttons are already spent, and the
-        // reply below says the same words with the same link.
         const settled = typedStartOf(store, "telegram", typed.event);
         if (settled?.outcome === "started" && settled.taskId !== null && pairingProblem() === null && held()) {
             const link = phoneLinkButton(options.phoneOrigin?.() ?? null, startedTaskLink(store, settled.taskId, repos));
@@ -805,13 +623,11 @@ async function runTelegramConversation(row, args) {
                 await transport("editMessageText", { chat_id: chatId, message_id: Number(typed.cardMessage), text: `✓ ${TYPED_START_STARTED}`, link_preview_options: { is_disabled: true },
                     reply_markup: { inline_keyboard: link === null ? [] : [link] } });
             }
-            catch { /* the reply below still says it */ }
+            catch { }
         }
         await sendOrHandOff("typed-start");
         return;
     }
-    // 4. A session bound before an earlier dispatch: the receipt lives there,
-    // whatever session is live today.
     if (row.session !== null) {
         const receipt = store.leadRequestReceipt(row.session, row.request);
         if (receipt !== null) {
@@ -819,13 +635,10 @@ async function runTelegramConversation(row, args) {
             return;
         }
     }
-    // It waited (for the lead, or behind earlier messages), was never admitted, and is past the wait from its arrival:
-    // it is never sent this late, even when the lead is free now.
     if (isLeadWait(row.outcome) && ageMs > CONVERSATION_WAIT_MAX_AGE_MS) {
         await requeue(row.outcome);
         return;
     }
-    // 5. The session and thread — shared with the console and the CLI.
     const resolved = resolveTelegramLead(store, binding, repos, clock());
     if (!resolved.ok && resolved.reason === "busy") {
         await requeue("busy");
@@ -849,19 +662,10 @@ async function runTelegramConversation(row, args) {
                     : problem === "the connected projects changed" ? "projects-changed" : "access-changed";
         return { ok: false, reason };
     };
-    // Bound BEFORE the dispatch, under the claim: a crash from here on finds
-    // the receipt in this session, not in whichever session is live later.
     if (!store.bindTelegramConversationSession(row.id, owner, session.id))
         return;
-    // 6. The turn. The claim is renewed while the model works; the poll lease
-    // is the caller's. The request id is the receipt: a second pass after a
-    // crash gets the original turn back, never a second dispatch.
     const heartbeat = setInterval(() => { held(); }, 30_000);
     heartbeat.unref?.();
-    // The live reply: one draft in this private chat with the status line and the reply as it is written
-    // (telegram-live.ts). A draft with words goes out only after the full fence: this exact binding, approver and the
-    // ceiling the turn opened under (the registry read at most every 5 s), the turn still running under the generation it
-    // first ran with, and this row's claim, re-checked after the read.
     let draftGeneration = null;
     let draftRegistry = null;
     const turnStillRunning = (turnId) => {
@@ -889,7 +693,6 @@ async function runTelegramConversation(row, args) {
     };
     const live = createTelegramLiveDraft({
         store, botId, transport, clock, chatId, binding: binding.id, draftId: row.id,
-        // Shaped as the final reply is: for this message, with the phone's own trusted origin.
         shape: { asked: row.text, appOrigin: options.phoneOrigin?.() ?? null },
         standing: draftStanding, paired: () => pairingProblem() === null,
         ...(options.liveTiming === undefined ? {} : { timing: options.liveTiming }),
@@ -907,7 +710,6 @@ async function runTelegramConversation(row, args) {
     }
     finally {
         clearInterval(heartbeat);
-        // Closed, and its draft in flight settled, before anything durable: no draft can land after the answer or a notice.
         await live.close();
     }
     const receipt = store.leadRequestReceipt(session.id, row.request);
@@ -924,8 +726,6 @@ async function runTelegramConversation(row, args) {
         return;
     }
     if (!outcome.ok) {
-        // Truthful: what failed, that nothing was kept, and that a new message
-        // is a new turn. A failed turn's drafts are already gone.
         await notify(phoneText(outcome.message, 1_000));
         finish({ state: "failed", outcome: chatOutcome.failed(outcome.failed) });
         report.refused++;
@@ -937,7 +737,6 @@ async function runTelegramConversation(row, args) {
     }
     if (row.taskId !== null)
         mirrorToTaskChat(store, who, row.taskId, "Telegram", row.text, outcome.reply, clock());
-    // 7. The reply and its cards: durable first, then sent.
     const proposals = store.listLeadProposals(thread.id, ["pending"]).filter(one => one.turn === outcome.turn);
     if (!plan(session.id, outcome.turn, outcome.reply, proposals, who.repos) && store.listTelegramConversationParts(row.id).length === 0)
         return;