toolroll 0.9.103 → 0.9.105

package/dist/telegram.js

@@ -1,23 +1,3 @@
-/**
- * The Telegram bridge: decisions out, answers back, zero tokens spent.
- *
- * This is channel plumbing — no LLM is anywhere in this path, and everything
- * it renders is deterministic. The security model, in one breath: a chat is
- * not a person, so pairing is a local authenticated act that binds one
- * private chat AND one immutable user id to one approver generation; a
- * button is not a command, so callback_data carries only an opaque one-time
- * token whose meaning lives in this database where a stolen bot token
- * cannot read it; and an answer lands in the same transaction that proves
- * the binding is still live and consumes the token — or it does not land.
- *
- * What a stolen bot token CAN do is stated rather than wished away: read
- * the decision text this installation chose to send through Telegram,
- * repaint the bot's keyboards with deceptive labels, and race our poll for
- * updates. It cannot mint an action token, answer as the operator, or make
- * `answered_by` say anything the pairing did not authorize. Rotating the
- * BotFather token plus `bridge telegram unpair` is the recovery, and both
- * are one command.
- */
 import { recordTypedStart, typedStartCard, typedYes } from "./typed-start.js";
 import { telegramCardMessage } from "./card-render.js";
 import { flowDoneCard } from "./flow-result-card.js";
@@ -50,28 +30,17 @@ import { envValue } from "./names.js";
 import { applyProposalTap, processTelegramConversations, phoneLinkButton, replyContextFor, telegramConversationRepos, telegramRequestId, tooLongText, whichTaskText, } from "./telegram-lead.js";
 import { telegramAck } from "./telegram-live.js";
 import { askOf, parseTelegramUpdate, pickOf, readTelegramButtonData, readTelegramUpdate, telegramButton } from "./contracts/telegram-callback.js";
-/** Read the enrolled project list on demand. No callback means no task data,
- * never an implicit all-database ceiling. Shared by pass and embedded follower. */
-/** A delivery its person began watching after it was claimed: held or settled at the final fence (cockpit §3). */
 const WATCHED_SINCE_CLAIM = "Held: its person is watching this agent now";
-/** The environment name — and therefore the name the builder strips from agents (both names; see names.ts). */
 export { TELEGRAM_TOKEN_ENV as TOKEN_ENV, TELEGRAM_TOKEN_ENVS as TOKEN_ENVS } from "./names.js";
-/** BotFather's shape: numeric bot id, colon, secret. */
 const TOKEN_SHAPE = /^(\d+):[A-Za-z0-9_-]{20,}$/;
 export const PAIRING_TTL_MS = 10 * 60_000;
 export const BRIDGE_LEASE_MS = 2 * 60_000;
 export const DELIVERY_CLAIM_MS = 2 * 60_000;
-/** Telegram's own message ceiling, with room for our part headers. */
 const PART_CAP = 3_900;
-/** Telegram's own limit on one message's text (Bot API sendMessage), less room for the line a tap adds under it. */
 const TELEGRAM_TEXT_MAX = 4_096 - 300;
-/** Pages of getUpdates one pass will read before reporting a backlog. */
 const PAGE_BUDGET = 10;
-// ---- pushed updates (v98) ----------------------------------------------------
-/** Where Telegram pushes this bot's updates: under the public hooks address (Tailscale Funnel covers /hooks). */
 export const TELEGRAM_HOOK_PATH = "/hooks/telegram";
 const HOOK_SECRET_FILE = "telegram-hook-secret";
-/** The secret Telegram sends with every push (its header), kept beside the database; made once when asked to. */
 export function telegramHookSecret(dir, make = false) {
     const file = join(dir, HOOK_SECRET_FILE);
     try {
@@ -79,7 +48,7 @@ export function telegramHookSecret(dir, make = false) {
         if (/^[A-Za-z0-9_-]{32,256}$/.test(saved))
             return saved;
     }
-    catch { /* none yet */ }
+    catch { }
     if (!make)
         return null;
     const made = randomBytes(32).toString("base64url");
@@ -87,7 +56,6 @@ export function telegramHookSecret(dir, make = false) {
     chmodSync(file, 0o600);
     return made;
 }
-/** The address Telegram pushes to: the public hooks address (https only) and /hooks/telegram; null without one. */
 export function telegramPushUrl(hooksBase) {
     if (hooksBase === null)
         return null;
@@ -99,14 +67,12 @@ export function telegramPushUrl(hooksBase) {
         return null;
     }
 }
-/** A push is Telegram's when its secret header matches ours (compared in constant time). */
 export function pushedByTelegram(header, secret) {
     if (secret === null || typeof header !== "string")
         return false;
     const given = Buffer.from(header), wanted = Buffer.from(secret);
     return given.length === wanted.length && timingSafeEqual(given, wanted);
 }
-/** Keep one pushed update for the bridge. A schema-invalid JSON update is logged and acknowledged, never retried. */
 export function keepPushedUpdate(store, botId, body, now) {
     let raw;
     try {
@@ -121,17 +87,10 @@ export function keepPushedUpdate(store, botId, body, now) {
         return { ok: true, kept: false };
     }
     const kept = store.queueTelegramUpdate(botId, update.value.update_id, JSON.stringify(raw), now);
-    // The bridge in this process (if any) stops idling and drains it now; elsewhere it waits at most one cycle.
     if (kept)
         wakeTelegramBridge(botId);
     return { ok: true, kept };
 }
-/**
- * Environment wins, the credential file beside the database otherwise.
- * The file is how the CLI and the web settings card set it (0600, owner
- * only); the env var is how people who already run keychain tooling keep
- * it out of files entirely.
- */
 export function loadBotToken(env, file) {
     const fromEnv = envValue(env, "TELEGRAM_TOKEN");
     if (fromEnv !== undefined && fromEnv.trim() !== "") {
@@ -148,7 +107,6 @@ export function loadBotToken(env, file) {
     const parsed = TOKEN_SHAPE.exec(raw);
     return parsed === null ? null : { token: raw, botId: parsed[1], source: "file" };
 }
-/** Write the credential file, owner-only. Refuses a string that is not a bot token. */
 export function saveBotToken(file, token) {
     if (!TOKEN_SHAPE.test(token.trim())) {
         return {
@@ -157,8 +115,6 @@ export function saveBotToken(file, token) {
         };
     }
     writeFileSync(file, `${token.trim()}\n`, { mode: 0o600 });
-    // writeFileSync applies the mode only on creation; an existing file keeps
-    // whatever it had, so the permission is asserted rather than assumed.
     chmodSync(file, 0o600);
     return { ok: true };
 }
@@ -171,15 +127,12 @@ export function clearBotToken(file) {
         return false;
     }
 }
-/** The last four characters are enough to recognize a token without holding it. */
 export function redactToken(token) {
     return `…${token.slice(-4)}`;
 }
-/** Scrub a token out of any text on its way to a log, an error, or a row. */
 export function scrub(text, token) {
     return token === "" ? text : text.split(token).join(redactToken(token));
 }
-/** A release card's full terms (release-card.ts) as the document Telegram sends with it: text this process wrote. */
 export const termsUpload = (file) => ({ field: "document", fileName: file.name, contentType: "text/plain", bytes: Buffer.from(file.text, "utf8") });
 export function createTransport(token, timeoutMs = 30_000) {
     return async (method, params, signal, upload, more) => {
@@ -193,17 +146,11 @@ export function createTransport(token, timeoutMs = 30_000) {
                 signal.addEventListener("abort", onAbort, { once: true });
         }
         try {
-            // A JSON call stays byte for byte what it was. A multipart call lets
-            // fetch mint the boundary and the content-type: scalars ride as
-            // fields, objects (reply_parameters, reply_markup) as their JSON, and
-            // the verified bytes as one Blob under the file name given.
             const request = upload === undefined
                 ? { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(params), signal: controller.signal }
                 : { method: "POST", body: multipartOf(params, upload, ...(more ?? [])), signal: controller.signal };
             const response = await fetch(`https://api.telegram.org/bot${token}/${method}`, request);
             const body = (await response.json());
-            // A missing or malformed acknowledgement does not prove a send failed.
-            // Only Telegram's explicit rejection is a definite failed delivery.
             if (body === null || typeof body !== "object" || Array.isArray(body) || typeof body.ok !== "boolean" || (body.ok && !response.ok)) {
                 return { ok: false, description: "Telegram returned an invalid acknowledgement", uncertain: true };
             }
@@ -211,7 +158,6 @@ export function createTransport(token, timeoutMs = 30_000) {
                 ok: body.ok === true,
                 result: body.result,
                 ...(body.parameters === undefined ? {} : { parameters: body.parameters }),
-                // Whatever Telegram said, the token must not be in what we keep.
                 ...(typeof body.description !== "string" ? {} : { description: scrub(body.description, token) }),
             };
         }
@@ -228,15 +174,6 @@ export function createTransport(token, timeoutMs = 30_000) {
         }
     };
 }
-/**
- * Why this process can't reach Telegram the way the service does, or null.
- * A coding agent's sandbox fences the network: Codex says so in its own
- * variables, and Claude Code's sandbox routes traffic through a proxy on
- * this computer, which curl uses and Node's fetch does not — so sends fail
- * "fetch failed" while curl works (Oct 2). Builds, checks and agents also
- * get a database of their own, so none of them can hold the live bridge;
- * this keeps an agent-launched `watch` or `bridge` from holding it either.
- */
 export function networkFence(env) {
     const set = (name) => (env[name] ?? "") !== "";
     if (set("CODEX_SANDBOX_NETWORK_DISABLED") || set("CODEX_SANDBOX"))
@@ -255,11 +192,9 @@ export function networkFence(env) {
     });
     return agent && loopbackProxy ? "a Claude Code sandbox" : null;
 }
-/** The plain line a fenced process says instead of polling or sending. */
 export function networkFenceLine(reason) {
     return `Telegram: not connecting from here — this process runs inside ${reason}, which blocks its network. Replies and notifications go out from the Toolroll service.`;
 }
-/** fetch's own message ("fetch failed") with the reason under it, e.g. "fetch failed (EMFILE: too many open files)". */
 export function transportError(error) {
     const message = error instanceof Error ? error.message : String(error);
     const cause = error instanceof Error ? error.cause : undefined;
@@ -270,7 +205,6 @@ export function transportError(error) {
     const why = code !== null && !detail.includes(code) ? `${code}: ${detail}` : detail;
     return why === "" || why === message ? message : `${message} (${why.slice(0, 160)})`;
 }
-/** The multipart body: every param a field (objects as JSON), the file last. Exported for the adapter's own test only. */
 export function multipartOf(params, upload, ...more) {
     const form = new FormData();
     for (const [key, value] of Object.entries(params)) {
@@ -282,20 +216,12 @@ export function multipartOf(params, upload, ...more) {
         form.append(one.field, new Blob([new Uint8Array(one.bytes)], { type: one.contentType }), one.fileName);
     return form;
 }
-// ---- pairing ---------------------------------------------------------------
 export function hashPairingCode(code) {
     return createHash("sha256").update(code, "utf8").digest("hex");
 }
-/** 128 bits, hex — pasteable, and not guessable inside any code's lifetime. */
 export function mintPairingCode() {
     return randomBytes(16).toString("hex");
 }
-/**
- * One bridge pass: claim and send what the outbox holds, then read one
- * budgeted window of updates and apply each in its own transaction. Cron
- * calls this; running it twice concurrently loses the lease race and does
- * nothing, which is the design working.
- */
 export async function bridgePass(store, options) {
     const clock = options.clock ?? (() => new Date());
     const owner = options.owner ?? randomBytes(8).toString("hex");
@@ -314,15 +240,11 @@ export async function bridgePass(store, options) {
             await deliverOutbox(store, botId, transport, owner, clock, report, options.readProjects, options.canDeliver, options.conversation?.phoneOrigin, options.conversation?.evidenceRoot);
             await deliverTeam(store, botId, transport, clock, report, options.readProjects, options.canDeliver, options.conversation?.phoneOrigin);
         }
-        // v98: updates Telegram pushed to the console apply first; asking for more only works while it isn't pushing.
         const pushed = await drainInbox({ store, botId, transport, clock, report, readProjects: options.readProjects, conversation: options.conversation, projects: null }, owner, lease.generation);
         if (pushed > 0)
             report.pushed = pushed;
         await drainUpdates(store, botId, transport, owner, lease.generation, lease.cursor, clock, report, 0, undefined, options.readProjects, options.conversation);
         if (options.conversation !== undefined && options.readProjects !== undefined) {
-            // The queued turns, outside any transaction. A model turn can outlive
-            // the poll lease, so the lease is renewed under the same owner while
-            // they run — the follower's own fenced renewal, reused.
             const renew = setInterval(() => { store.acquireBridgeLease(botId, owner, BRIDGE_LEASE_MS, clock()); }, 30_000);
             renew.unref?.();
             try {
@@ -334,45 +256,15 @@ export async function bridgePass(store, options) {
         }
     }
     finally {
-        // Handed back so the next cron firing is not told busy for the rest of
-        // this pass's TTL. A crash skips this and the lease expires instead —
-        // which is exactly what the TTL is for.
         store.releaseBridgeLease(botId, owner, clock());
     }
     return { ok: true, report };
 }
-// ---- the follower ----------------------------------------------------------
-/**
- * The longest long poll the follower may ask for. `createTransport`'s HTTP
- * timeout is 30s and must outlive the poll window, or the client would abort
- * a poll Telegram is still honestly holding open.
- */
 export const MAX_POLL_SECONDS = 25;
-/** Reconnect backoff: starts here, doubles per consecutive failure, capped. */
 const FOLLOW_BACKOFF_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000];
-/** A cycle that returned instantly with nothing is padded to this — a scripted or broken server must not spin the loop hot. */
 const FOLLOW_IDLE_FLOOR_MS = 1_000;
-/** While a long poll is open, how often the follower looks for a message due to go out (live-wakeups.md). */
 const DELIVERY_CHECK_MS = 1_000;
-/** v98: how often the bridge checks Telegram still pushes to us; how long pushes may keep failing before it asks
- * for updates itself; and how long it asks before trying pushes again. */
 const PUSH_CHECK_MS = 60_000, PUSH_GIVE_UP_MS = 5 * 60_000, PUSH_RETRY_MS = 15 * 60_000, PUSH_IDLE_MS = 2_000;
-/**
- * The follower (§M4): one actor that holds the poll lease and stays on the
- * wire, so an answer tapped on a phone reaches the store in seconds, not at
- * the next cron firing. `bridge telegram --follow` runs it standalone;
- * watch embeds the same actor — the poll lease guarantees only one is
- * live, and a cron pass overlapping it simply loses the lease race.
- *
- * Each cycle re-acquires the lease under the same owner — that is the
- * fenced renewal: same generation while held, and if the lease lapsed
- * mid-poll (a stall longer than the TTL), the re-acquire takes the next
- * generation and the cursor rides it, so nothing this follower stamped
- * with the old generation can move state afterwards. Transport failures
- * back off exponentially and are counted, not hidden; cancellation aborts
- * the in-flight long poll instead of waiting it out.
- */
-/** What Telegram lists when the person taps "/". */
 export const TELEGRAM_COMMANDS = [
     { command: "tasks", description: "Pick a task to talk about" },
     { command: "status", description: "Recent work across your projects" },
@@ -394,7 +286,6 @@ export async function followBridge(store, options) {
             }
             signal.addEventListener("abort", finish, { once: true });
         }));
-    /** The push idle: the ordinary wait, ended early when this process keeps a push for this bot. */
     const idle = (ms) => {
         if (bridgeWokenEarly.delete(botId))
             return Promise.resolve();
@@ -412,14 +303,6 @@ export async function followBridge(store, options) {
     const total = { cycles: 0, sent: 0, answered: 0, paired: 0, ignored: 0, problems: [] };
     let commandsListed = false;
     let failures = 0;
-    // Queued turns run BESIDE the poll, never inside a cycle: a long model
-    // turn must not stall the long poll, and each cycle's lease re-acquire is
-    // the renewal that keeps this the only live poller meanwhile. One
-    // processor at a time; its counts land on the totals when it finishes.
-    // It only persists the reply: the cycle sends it, in the same slot as
-    // notifications, so a reply never needs a connection of its own beside
-    // the long poll (Oct 2: replies failed "fetch failed" for minutes while
-    // notifications from the same process went out).
     let inFlight = null;
     const kick = () => {
         if (inFlight !== null || options.conversation === undefined || options.readProjects === undefined)
@@ -438,12 +321,6 @@ export async function followBridge(store, options) {
                 options.onCycle?.(report);
         });
     };
-    // v98: pushed updates. With a public address, Telegram pushes each update to
-    // /hooks/telegram and the console keeps it for us; while it does, nobody can
-    // ask Telegram for this bot's updates — no other program can take them. Every
-    // minute we check the address is still ours (a framework starting up elsewhere
-    // may delete it); if pushes keep failing we ask for updates ourselves for a
-    // while, then try pushes again.
     const push = options.push ?? null;
     const pushCheckMs = options.pushCheckMs ?? PUSH_CHECK_MS;
     let pushMode = push === null ? "poll" : "push";
@@ -495,7 +372,6 @@ export async function followBridge(store, options) {
             return;
         }
         pushRegistered = true;
-        // Telegram couldn't deliver lately and updates are waiting: the address isn't reachable.
         const failing = (hook.pending_update_count ?? 0) > 0 && typeof hook.last_error_date === "number" && now / 1000 - hook.last_error_date < 180;
         if (!failing) {
             pushFailingSince = null;
@@ -513,48 +389,34 @@ export async function followBridge(store, options) {
         while (!signal.aborted) {
             const lease = store.acquireBridgeLease(botId, owner, BRIDGE_LEASE_MS, clock());
             if (!lease.ok) {
-                // A cron pass (or a rival follower) holds the poll. Not an error —
-                // wait our turn and try again.
                 await wait(FOLLOW_BACKOFF_MS[Math.min(failures, FOLLOW_BACKOFF_MS.length - 1)]);
                 failures = Math.min(failures + 1, FOLLOW_BACKOFF_MS.length - 1);
                 continue;
             }
-            // The "/" menu in Telegram, once, by the poller that holds the lease:
-            // the picker first. Best effort; typed commands work either way.
             if (!commandsListed && options.conversation !== undefined) {
                 commandsListed = true;
-                // Both carry the stop signal: a stop never waits on a slow Bot API for them.
                 try {
                     await transport("setMyCommands", { commands: TELEGRAM_COMMANDS }, signal);
                 }
-                catch { /* typed commands still work */ }
-                // After an upgrade, a bot still called StandingOrders becomes Toolroll, once per start; any other name is kept.
+                catch { }
                 await nameTelegramBot(transport, "upgrade", signal);
             }
             const startedAt = Date.now();
             const report = { sent: 0, answered: 0, paired: 0, ignored: 0, backlog: false, problems: [] };
             await managePush(report);
-            // What this cycle's delivery below covers: anything newer may end the long poll early.
             const deliveredThrough = newestNotificationIdOf(store);
             if (options.deliver !== false) {
                 await deliverOutbox(store, botId, transport, owner, clock, report, options.readProjects, options.canDeliver, options.conversation?.phoneOrigin, options.conversation?.evidenceRoot);
                 await deliverTeam(store, botId, transport, clock, report, options.readProjects, options.canDeliver, options.conversation?.phoneOrigin);
             }
-            // Replies the turn worker has planned go out here, like notifications.
             if (options.conversation !== undefined && options.readProjects !== undefined) {
                 await processConversations(store, botId, transport, owner, clock, report, options.readProjects, options.conversation, signal, "replies");
             }
-            // Pushed updates first (some may wait from before a fall back), then — only while
-            // Telegram isn't pushing — ask for more.
             const pushed = await drainInbox({ store, botId, transport, clock, report, readProjects: options.readProjects, conversation: options.conversation, projects: null }, owner, lease.generation);
             if (pushed > 0)
                 report.pushed = pushed;
             if (!pushing()) {
-                // While a turn is running, poll briefly so its reply is sent within a second or two of being written.
                 const seconds = inFlight === null ? pollSeconds : 1;
-                // A DELIVERY WAKE (live-wakeups.md): while the long poll is open, a message written for this bot since this
-                // cycle began delivering ends the poll, once per cycle, so it goes out now instead of after the poll. Same
-                // owner, same generation, one connection; the cursor moves only past updates already processed.
                 const poll = new AbortController();
                 const endPoll = () => poll.abort();
                 if (signal.aborted)
@@ -588,7 +450,6 @@ export async function followBridge(store, options) {
                         clearInterval(checker);
                     signal.removeEventListener("abort", endPoll);
                 }
-                // A push address nobody here wants any more (the public address was removed): take it down, so asking works again.
                 if (report.webhookActive === true && push === null)
                     await transport("deleteWebhook", { drop_pending_updates: false }, signal);
             }
@@ -613,7 +474,6 @@ export async function followBridge(store, options) {
                 options.onCycle?.(report);
             }
             if (report.problems.length > 0 && report.sent === 0 && report.answered === 0 && (report.chatAnswered ?? 0) === 0) {
-                // The wire is down. Back off; the counter resets on the first clean cycle.
                 if (!signal.aborted) {
                     await wait(FOLLOW_BACKOFF_MS[Math.min(failures, FOLLOW_BACKOFF_MS.length - 1)]);
                 }
@@ -621,25 +481,16 @@ export async function followBridge(store, options) {
                 continue;
             }
             failures = 0;
-            // A healthy cycle's wait IS the long poll. A cycle that came back
-            // instantly and empty (scripted transport, misbehaving server) gets
-            // padded so the loop cannot spin hot.
             const took = Date.now() - startedAt;
-            // While Telegram pushes (v98) there is no long poll to wait on: a pushed update waits at most this long.
             const floor = pushing() ? PUSH_IDLE_MS : FOLLOW_IDLE_FLOOR_MS;
-            // A delivery wake goes straight back round to send: no padding.
             if (!signal.aborted && report.deliveryWake !== true && report.sent === 0 && report.answered === 0 && (report.chatAnswered ?? 0) === 0 && took < floor) {
-                // While Telegram pushes, a push kept by this process's hook ends the idle at once.
                 await (pushing() ? idle(floor - took) : wait(floor - took));
             }
         }
     }
     finally {
-        // A turn in flight finishes on its own bounds (the engine's wall clock);
-        // its reply is fenced on the claim and the channel like every other part.
         if (inFlight !== null) {
             await inFlight;
-            // Its reply was written for the cycle that will not come: send it now, while the lease is still ours.
             if (options.conversation !== undefined && options.readProjects !== undefined) {
                 const report = { sent: 0, answered: 0, paired: 0, ignored: 0, backlog: false, problems: [] };
                 await processConversations(store, botId, transport, owner, clock, report, options.readProjects, options.conversation, undefined, "replies").catch(() => { });
@@ -652,7 +503,6 @@ export async function followBridge(store, options) {
     }
     return total;
 }
-/** The queued turns for one bot, counted onto the pass's report. */
 async function processConversations(store, botId, transport, owner, clock, report, readProjects, conversation, signal, only) {
     const chat = { answered: 0, refused: 0, problems: [] };
     await processTelegramConversations({ store, botId, transport, owner, clock, readProjects, options: conversation, report: chat, ...(signal === undefined ? {} : { signal }), ...(only === undefined ? {} : { only }) });
@@ -662,7 +512,6 @@ async function processConversations(store, botId, transport, owner, clock, repor
         report.chatRefused = (report.chatRefused ?? 0) + chat.refused;
     report.problems.push(...chat.problems);
 }
-/** A fact's own next-action button row under the trusted origin read now; none without one. */
 function factButton(phoneOrigin, link) {
     try {
         return phoneLinkButton(phoneOrigin?.() ?? null, { label: factLinkLabel(link), path: link });
@@ -671,7 +520,6 @@ function factButton(phoneOrigin, link) {
         return null;
     }
 }
-/** A view's buttons on one row: its link, then any others ([Merge] [Look first]); none without a trusted origin. */
 function viewKeyboard(phoneOrigin, view) {
     try {
         const origin = phoneOrigin?.() ?? null;
@@ -682,11 +530,9 @@ function viewKeyboard(phoneOrigin, view) {
         return [];
     }
 }
-/** Where a paired person taps: their binding and private chat. */
 function decideSeat(binding) {
     return { channel: "telegram", binding: binding.id, chat: binding.chatId, approver: binding.approver, generation: binding.approverGeneration };
 }
-/** Decide buttons as Telegram draws them: an act's opaque token, or a link under the trusted origin read now (none without one). */
 function decideKeyboard(phoneOrigin, rows) {
     let origin = null;
     try {
@@ -698,14 +544,12 @@ function decideKeyboard(phoneOrigin, rows) {
     return rows.map(row => row.flatMap((one) => "token" in one ? [telegramButton(one.label, one.token)]
         : phoneLinkButton(origin, one.link) ?? [])).filter(row => row.length > 0);
 }
-/** What this card may act on in the chat now, for this person under their current ceiling; null keeps its link. */
 function decideOfferFor(store, binding, target, projects, now, root) {
     if (target === null || target === undefined)
         return null;
     const principal = verifyApproverStanding(store, binding.approver, binding.approverGeneration, telegramConversationRepos(store, binding.approver, projects));
     return principal.ok ? decideOffer(store, target, principal.who, now, "telegram", root) : null;
 }
-/** Team-conversation traffic to the chats that follow one — after the outbox, under the same delivery switch, never a problem to raise when nothing follows anything. */
 async function deliverTeam(store, botId, transport, clock, report, readProjects, canDeliver, phoneOrigin) {
     if (store.listTelegramTeamChats(botId).length === 0)
         return;
@@ -732,38 +576,27 @@ async function deliverTeam(store, botId, transport, clock, report, readProjects,
 async function deliverOutbox(store, botId, transport, owner, clock, report, readProjects, canDeliver, phoneOrigin, evidenceRoot) {
     const bindings = store.liveTelegramBindings(botId);
     if (bindings.length === 0) {
-        // Routine progress facts are not a problem to fix: a first pairing
-        // starts from now and settles them as history. Anything else pending
-        // is named, once per pass, as before.
         if (store.listNotifications("pending").some(row => !isLifecycleNotification(row) && !isShotsKind(row.kind)))
             report.problems.push("outbox rows are pending but no chat is paired — `toolroll bridge telegram pair`");
         return;
     }
     const digest = store.telegramDigest();
     const now = clock();
-    // An evening digest someone asked for is due: record it as their own notification, delivered below.
     try {
         enqueueEveningDigests(store, now, evidenceRoot);
     }
     catch {
         report.problems.push("evening digest could not be prepared");
     }
-    // A lead claim that went two hours quiet repaints its owner's card back to the task's real state.
     enqueueLeadLapses(store, now);
     const digestDue = digest.everyMs === null || digest.lastSentAt === null || now.getTime() >= new Date(digest.lastSentAt).getTime() + digest.everyMs;
-    // Every paired person is a destination of their own: each binding claims
-    // and settles its own rows under its own ceiling, in turn.
     for (const binding of bindings)
         await deliverOutboxTo(store, botId, binding, transport, owner, clock, report, digest, digestDue, readProjects, canDeliver, phoneOrigin, evidenceRoot);
 }
 async function deliverOutboxTo(store, botId, binding, transport, owner, clock, report, digest, digestDue, readProjects, canDeliver, phoneOrigin, evidenceRoot) {
     const now = clock();
-    // Only when I'm needed (the default): a task's facts edit its one card and only what needs this person makes a
-    // new message, so the installation's routine-fact cadence does not apply. Every step keeps today's behaviour.
     const quiet = store.notificationPreference(binding.approver).mode === "quiet";
     const claimed = store.claimTelegramDeliveries(binding, owner, DELIVERY_CLAIM_MS, now, quiet || digestDue ? "all" : "urgent");
-    // Preserve ID order, flushing earlier routine facts before an urgent task
-    // update. An earlier failed/retrying row also fences later rows for that task.
     const groups = [];
     for (const row of claimed) {
         const last = groups[groups.length - 1];
@@ -794,15 +627,10 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             return null;
         };
         const retryAt = () => [store.telegramRetryAt(botId), new Date(clock().getTime() + 1_000).toISOString()].sort().at(-1);
-        // Partition before anything is sent: a row without live authority is
-        // retained with its reason, and the rows that ARE eligible go out now
-        // rather than waiting on it. Walking in ID order with the eligible set
-        // as the batch keeps a task's later facts behind its blocked earlier one.
         const rows = [];
         const blocked = [];
         const preflight = (await readAccess()) ?? channelProblem();
         for (const row of group) {
-            // Watched since the claim (cockpit §3): held for later or settled quietly, never sent now, never a failure.
             if (preflight === null && store.telegramWatchFence(row, binding, owner, clock()) !== "send")
                 continue;
             const problem = preflight ?? store.telegramDeliveryProblem(row, binding, owner, projects, clock(), [...rows.map(one => one.id), row.id]);
@@ -820,8 +648,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
         if (rows.length === 0)
             continue;
         const ids = rows.map(row => row.id);
-        // Once any part of this delivery has reached Telegram it is committed: a watch opening between its parts never
-        // releases it (that would send the parts already accepted again). Every transport call below goes through `wire`.
         let sentAny = false;
         const wire = async (...args) => {
             const answer = await transport(...args);
@@ -829,7 +655,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 sentAny = true;
             return answer;
         };
-        /** A release card's terms file (release-card.ts), sent before the card itself. */
         const fileSender = async (file) => {
             try {
                 return (await wire("sendDocument", { chat_id: binding.chatId, caption: "Every term of this release" }, undefined, termsUpload(file))).ok === true;
@@ -838,8 +663,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 return false;
             }
         };
-        // `beforeSend`: the fence before a transport call also asks the watch — until something of this delivery went out;
-        // the one after a confirmed send never does, so a message Telegram accepted is recorded as delivered.
         const fence = (beforeSend = !sentAny) => {
             const channel = channelProblem();
             if (channel !== null)
@@ -848,15 +671,12 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 const problem = store.telegramDeliveryProblem(row, binding, owner, projects, clock(), ids);
                 if (problem !== null)
                     return problem;
-                // The watch, at the last moment before the network: a held row's claim is released (its finalize is then a
-                // no-op), so nothing is spent on it.
                 if (beforeSend && store.telegramWatchFence(row, binding, owner, clock()) !== "send")
                     return WATCHED_SINCE_CLAIM;
             }
             return null;
         };
         const sender = async (text, keyboard, messageRows = rows, entities, silent) => {
-            // Finish every await before the synchronous fence and transport call.
             const problem = (await readAccess()) ?? fence();
             if (problem !== null)
                 return { ok: false, error: problem };
@@ -870,7 +690,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 return { ok: false, error: "Telegram returned no confirmed message identity" };
             for (const row of messageRows)
                 store.recordTelegramMessage(row, binding, sent.messageId, clock());
-            // Keep the old message's history but never acknowledge a replaced pairing.
             const after = (await readAccess()) ?? fence(false);
             return after === null ? sent : { ok: false, error: after };
         };
@@ -891,13 +710,10 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 const sent = await sender(`A screenshot for result #${row.run} could not be sent: ${verified.problem}. Inspect the result before accepting.`);
                 return sent.ok ? { ok: true, receipt: receiptFor(botId, binding.chatId, sent.messageId) } : sent;
             }
-            // Already sent with its result (result-shots.ts): the same screenshot is not sent again.
             const artifact = Number(match[2]);
             if (store.resultShotsSent(row.destination, row.run).has(artifact))
                 return { ok: true, receipt: "skipped:screenshot-sent" };
-            // Marked while it goes, so the screenshots sent with the result skip it; any failure unmarks it for the retry.
             store.markResultShotsSent(row.destination, row.run, [artifact], clock());
-            // No await between the access fence, file validation and upload.
             let answer;
             try {
                 answer = await wire("sendDocument", { chat_id: binding.chatId, caption: `${resultTaskLabel(row.taskId)} · result #${row.run} · screenshot for acceptance` }, undefined, {
@@ -919,8 +735,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             const after = (await readAccess()) ?? fence(false);
             return after === null ? { ok: true, receipt: receiptFor(botId, binding.chatId, String(messageId)) } : { ok: false, error: after };
         };
-        /** Screenshots with a result (result-shots.ts): photos, several as one album, re-proved before every call. Each is
-         * marked sent before it goes, so an unconfirmed send is never repeated; only Telegram's outright refusal unmarks it. */
         const shotsSender = async (row) => {
             let receipt = null;
             for (let call = 0; call <= 4; call++) {
@@ -934,7 +748,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                     const sent = await sender(plan.text, undefined, [row]);
                     return sent.ok ? { ok: true, receipt: receiptFor(botId, binding.chatId, sent.messageId) } : sent;
                 }
-                // No await between the access fence, the files' verification and the upload.
                 const photos = plan.shots.filter(one => one.photo);
                 const batch = photos.length >= 2 ? photos : [plan.shots[0]];
                 const upload = (one, field) => ({ field, fileName: one.fileName, contentType: one.format === "png" ? "image/png" : "image/jpeg", bytes: one.bytes });
@@ -959,7 +772,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 }
                 const messages = (Array.isArray(answer.result) ? answer.result : [answer.result])
                     .map(one => one?.message_id).filter((one) => Number.isSafeInteger(one));
-                // An unconfirmed send stays marked: it may have arrived, so it is never sent again.
                 if (!answer.ok || messages.length === 0)
                     report.problems.push(`notification ${row.id}: Telegram did not confirm the screenshots; they are not sent again`);
                 for (const one of messages)
@@ -986,7 +798,7 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             try {
                 button = phoneLinkButton(phoneOrigin?.() ?? null, card.link);
             }
-            catch { /* No trusted origin. */ }
+            catch { }
             const keyboard = button === null ? [] : [button];
             if (messageId === null)
                 return sender(card.text, keyboard, rows, card.entities);
@@ -994,8 +806,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             if (!edited.ok) {
                 if (edited.retryAfter !== undefined)
                     store.deferTelegram(botId, new Date(clock().getTime() + edited.retryAfter * 1000).toISOString());
-                // Only Telegram's definitive missing/uneditable response permits a
-                // replacement. Timeouts, rate limits and uncertain edits retry in place.
                 if (!onlyExisting && edited.replace)
                     return sender(card.text, keyboard, rows, card.entities);
                 return edited;
@@ -1005,7 +815,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             const after = (await readAccess()) ?? fence(false);
             return after === null ? edited : { ok: false, error: after };
         };
-        /** Quiet mode: the task's one card (or its group's), created silently and then only ever edited. */
         const updateCard = async (fact) => {
             const problem = (await readAccess()) ?? fence();
             if (problem !== null)
@@ -1018,7 +827,7 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             try {
                 button = phoneLinkButton(phoneOrigin?.() ?? null, view.link);
             }
-            catch { /* No trusted origin. */ }
+            catch { }
             const keyboard = button === null ? [] : [button];
             const shown = createHash("sha256").update(JSON.stringify([view.text, view.entities, keyboard])).digest("hex");
             if (card.message !== null && card.digest === shown) {
@@ -1035,12 +844,10 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 }
                 if (edited.retryAfter !== undefined)
                     store.deferTelegram(botId, new Date(clock().getTime() + edited.retryAfter * 1000).toISOString());
-                // Only Telegram's definitive missing/uneditable answer permits a replacement card.
                 if (!edited.replace)
                     return edited;
             }
             const sent = await sender(view.text, keyboard, [fact], view.entities, true);
-            // A card that reached the chat is kept even if a later fence refused the acknowledgement: never a second card.
             const placed = sent.ok ? sent.messageId : store.telegramMessageOf(fact.id, fact.destination);
             if (placed !== null)
                 store.setChatCardMessage(card.id, placed, shown);
@@ -1054,9 +861,7 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 return { ok: true, receipt: receiptFor(botId, binding.chatId, card.messageId) };
             const readyRun = fact.kind === "run-finished" ? store.telegramProgressRun(fact) : null;
             if (readyRun !== null || (fact.kind !== "run-finished" && joinsBatch(fact))) {
-                // Any update for this person joins their open batch: one message, edited in place while it grows.
                 const batch = store.chatBatchFor(fact.destination, fact.taskRef, readyRun?.id ?? store.telegramProgressRun(fact)?.id ?? null, clock(), BATCH_MS, readyRun !== null ? null : fact.id);
-                // A lone update that is not finished work goes out exactly as it always has; a later one edits it in place.
                 const lone = batch.items.length === 1 && batch.items[0].notification !== null;
                 if (batch.message === null && lone) {
                     const sent = await deliverOne(store, botId, binding, sender, fact, clock, phoneOrigin, evidenceRoot, projects, fileSender);
@@ -1066,26 +871,18 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                     return sent;
                 }
                 const view = finishedView(store, batch, clock(), evidenceRoot, binding.approver);
-                // Nothing in the batch reads as a line. Finished work left out on purpose (a release check, a replaced task,
-                // the reader's own completion) stays quiet; any other update that needs this person still reaches them alone.
                 if (view === null) {
                     if (readyRun !== null)
                         return { ok: true, receipt: receiptFor(botId, binding.chatId, card.messageId) };
                     return deliverOne(store, botId, binding, sender, fact, clock, phoneOrigin, evidenceRoot, projects, fileSender);
                 }
-                // A message about one result, plan, failure or pull request acts in place (chat-decide.ts); its buttons are
-                // minted only when what it offers changed, or its own were spent (Not now), so an unchanged repaint keeps the
-                // ones already in the chat.
                 const offer = decideOfferFor(store, binding, view.target, projects, clock(), evidenceRoot);
                 const text = offer?.text ?? view.text;
-                // While a lone update is still the only item, its edit keeps that update's own action button.
                 const own = offer === null && lone && fact.link !== null ? factButton(phoneOrigin, fact.link) : null;
                 let keyboard = own !== null ? [own] : viewKeyboard(phoneOrigin, view);
                 const shown = createHash("sha256").update(JSON.stringify(offer === null ? [view.text, keyboard] : [text, offerFingerprint(offer)])).digest("hex");
                 let tokens = [];
-                // A release card's terms go as a file first, on this road as on a lone delivery: no file accepted, no buttons.
                 const termsFirst = async () => offer?.file === undefined || (fileSender !== undefined && await fileSender(offer.file)) ? null : { ok: false, error: "The release's terms file wasn't accepted" };
-                // Minted unplaced: they ride a message only once it shows them, and until then the old card's buttons work.
                 const mintFor = () => {
                     if (offer === null)
                         return;
@@ -1107,7 +904,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                     mintFor();
                     const edited = await editProgress(wire, binding.chatId, batch.message, text, keyboard);
                     if (edited.ok) {
-                        // The repaint landed: the old words' buttons retire and the new ones ride the message.
                         retireDecideTokens(store, "telegram", binding.chatId, batch.message, clock());
                         placeDecideTokens(store, tokens, batch.message);
                         store.setChatBatchMessage(batch.id, batch.message, shown);
@@ -1115,15 +911,12 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                         const after = (await readAccess()) ?? fence(false);
                         return after === null ? { ok: true, receipt: receiptFor(botId, binding.chatId, batch.message) } : { ok: false, error: after };
                     }
-                    // A failed edit: the buttons it carried never act, and the card's old ones keep working.
                     dropDecideTokens(store, tokens, clock());
                     if (edited.retryAfter !== undefined)
                         store.deferTelegram(botId, new Date(clock().getTime() + edited.retryAfter * 1000).toISOString());
-                    // Only Telegram's definitive missing/uneditable answer permits a new message.
                     if (!edited.replace)
                         return edited;
                 }
-                // A new message: its buttons are minted for it, never the ones a failed edit was given.
                 if (batch.message === null) {
                     const terms = await termsFirst();
                     if (terms !== null)
@@ -1135,7 +928,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 if (placed !== null)
                     store.setChatBatchMessage(batch.id, placed, shown);
                 if (sent.ok && sent.messageId !== null) {
-                    // The new card replaces the old one: only its buttons act.
                     if (batch.message !== null)
                         retireDecideTokens(store, "telegram", binding.chatId, batch.message, clock());
                     placeDecideTokens(store, tokens, sent.messageId);
@@ -1146,7 +938,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             }
             return fact.kind === "acceptance-evidence" ? imageSender(fact) : deliverOne(store, botId, binding, sender, fact, clock, phoneOrigin, evidenceRoot, projects, fileSender);
         };
-        /** The lead's words (lead-voice.ts): one message; a later say within two minutes edits it in place. */
         const leadSayOutcome = async (fact) => {
             const words = leadSayText(store, fact, binding.approver);
             const button = fact.link === null ? null : factButton(phoneOrigin, fact.link);
@@ -1164,7 +955,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 }
                 if (edited.retryAfter !== undefined)
                     store.deferTelegram(botId, new Date(clock().getTime() + edited.retryAfter * 1000).toISOString());
-                // Only Telegram's definitive missing/uneditable answer permits a new message.
                 if (!edited.replace)
                     return edited;
             }
@@ -1179,8 +969,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
         else if (quiet && rows.length === 1 && isTaskFact(row))
             outcome = await quietOutcome(row);
         else {
-            // A failure or decision still gets its own alert. Refresh an existing
-            // card first so it does not keep saying the build is running.
             if (!progress && progressRun !== null)
                 await updateProgress(true);
             const updated = progress ? await updateProgress(false) : null;
@@ -1191,7 +979,6 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
         }
         const finalProblem = outcome.ok ? (await readAccess()) ?? fence(false) : null;
         const settled = finalProblem === null ? outcome : { ok: false, error: finalProblem };
-        // A skipped screenshot settles its row but nothing reached the phone.
         const skipped = settled.ok && settled.receipt !== null && settled.receipt.startsWith("skipped:");
         const finalized = store.transact(() => {
             let count = 0;
@@ -1214,18 +1001,12 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             report.problems.push("Telegram delivery claim expired before acknowledgement; retry may duplicate a message");
     }
 }
-/** What pages singly whatever the cadence: a decision, or an attention-class fact. */
 function isUrgent(notification) {
     return /^decision:\d+$/.test(notification.dedupeKey) || notification.pushClass === "attention" || notification.kind === "acceptance-evidence" || notification.kind === "acceptance-ready";
 }
-/** A routine fact the digest may carry. Screenshots are never urgent (they follow their result message, which the
- * task's order fence holds them behind) and never a digest line: they go as their own photos once it has gone. */
 function joinsDigest(notification) {
     return !isUrgent(notification) && !isShotsKind(notification.kind);
 }
-/** The digest text: a header with the count and the window, then one
- * fact per entry — its subject, then its body's first line, indented.
- * Plain text, no buttons: nothing in a digest is tappable. */
 export function digestText(rows, since, now, titleOf) {
     const window = since === null ? "" : ` since ${since.slice(0, 16).replace("T", " ")}`;
     const lines = [`digest — ${rows.length} routine fact(s)${window} (as of ${now.toISOString().slice(0, 16).replace("T", " ")})`, ""];
@@ -1244,8 +1025,6 @@ function digestEntry(row, titleOf) {
 }
 async function deliverDigest(botId, binding, sender, rows, since, clock, titleOf) {
     const text = digestText(rows, since, clock(), titleOf);
-    // Track the exact rows represented by each text part. A split row may bind
-    // several messages; a digest message may bind several rows.
     let offset = text.indexOf("\n\n") + 2;
     const spans = rows.map(row => {
         const length = digestEntry(row, titleOf).length;
@@ -1272,11 +1051,6 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
         return { ok: false, error: "Decision does not match notification provenance" };
     }
     if (decision === null || decision.state === "answered") {
-        // A plain fact, or a decision settled before the bridge got to it: the
-        // text is the message. Its one next-action button — the fact's
-        // machine-minted link under the trusted origin read now, never a token
-        // and never persisted — rides the LAST part only, exactly as `/task`'s
-        // does; with no trusted origin the words stand alone.
         const alreadyAccepted = notification.kind === "acceptance-ready" && notification.run !== null && store.proofAcceptance(notification.run) !== null;
         let body = alreadyAccepted ? "This result already has recorded human acceptance. No further acceptance is needed." : notification.body;
         let current = true;
@@ -1296,12 +1070,9 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
             else
                 body = `${packet.text}\n\n${notification.body}`;
         }
-        // A short title, never the task's id or a "— revision" suffix (chat-voice.ts).
         const title = notification.taskId === null ? undefined : chatTitle(store, notification.taskId);
         const task = notification.taskId === null ? [] : [{ id: notification.taskId, ...(title === undefined ? {} : { title }) }];
         const words = chatText(`${alreadyAccepted ? "Acceptance recorded" : leadSubjectOf(store, notification, binding.approver)}${body === "" ? "" : `\n\n${body}`}`, task);
-        // The task's title once: in front, unless the words already name it.
-        // A result, plan, failure or ready pull request acts in place (chat-decide.ts); otherwise its one link.
         const target = alreadyAccepted || !current ? null : decideTargetOf(notification);
         const offer = decideOfferFor(store, binding, target, projects, clock(), evidenceRoot);
         const decided = offer === null ? null : mintDecideButtons(store, decideSeat(binding), target, offer, clock());
@@ -1314,11 +1085,9 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
             return null;
         } })()
             : offer === null && notification.link !== null && !alreadyAccepted && current ? factButton(phoneOrigin, notification.link) : null;
-        // A flow card waiting on a decision (v86): Approve, Edit, Send back on the last part, for this visit only.
         const visit = FLOW_DECIDE_KEY.exec(notification.dedupeKey);
         const waiting = visit === null ? null : flowDecisionAt(store, Number(visit[1]), Number(visit[2]));
         const flowKeys = waiting === null ? null : flowButtons(store, binding, waiting, clock());
-        // A flow's "Send to me" or "Person chooses" (flow-send.ts): its links as buttons, and a choice's options above them.
         const sentVisit = FLOW_SEND_KEY.exec(notification.dedupeKey) ?? FLOW_CHOOSE_KEY.exec(notification.dedupeKey);
         const sent = sentVisit === null ? null : flowSentContent(store, Number(sentVisit[1]), Number(sentVisit[2]));
         const choosing = sent === null || !FLOW_CHOOSE_KEY.test(notification.dedupeKey) || notification.recipient !== binding.approver ? null : flowChoiceAt(store, Number(sentVisit[1]), Number(sentVisit[2]));
@@ -1331,8 +1100,6 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
         } })();
         if (sentRow !== null)
             button = sentRow.length === 0 ? null : sentRow;
-        // A flow decision or choice for this person leads with what to do and where each button takes the card
-        // (telegram-flow.ts); the flow and zone close it. The saved notice keeps its own words for every other place.
         const pull = sent === null ? [] : sent.links.flatMap(one => "url" in one ? [`${one.label}: ${one.url}`] : []).slice(0, 1);
         const choiceHead = choosing === null || sent === null ? null : flowChoiceHead(choosing, sent);
         const choiceTail = choosing === null ? [] : [...pull, `${choosing.flow.name}${sent?.from === undefined ? "" : ` · after ${sent.from}`}`];
@@ -1340,8 +1107,6 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
             parts = split(`${notificationIdentity(notification)}${chatText(flowDecisionText(waiting, notification.body), task)}`);
         else if (offer === null && choiceHead !== null && sent !== null)
             parts = split(`${notificationIdentity(notification)}${chatText([...choiceHead, "", sent.summary, "", ...choiceTail.flatMap((line, index) => index === 0 ? [line] : ["", line])].join("\n"), task)}`);
-        // After research (flow-items.ts): each item numbered under the summary, its words cleaned as the rest of the message's
-        // are, within Telegram's limit with every link kept — one message, unless head, links and tail alone overflow it.
         let entities = [];
         if (sent?.items !== undefined && sent.items.length > 0 && offer === null) {
             const subject = chatText(leadSubjectOf(store, notification, binding.approver), task);
@@ -1352,21 +1117,17 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
             parts = voiced.map(one => one.text);
             entities = voiced.map(one => one.entities);
         }
-        // A flow's result as a card (flow-result-card.ts): one more message, its tables as monospaced text.
         const resultCard = offer === null ? sent?.card ?? flowDoneCard(store, notification, clock()) : null;
         if (resultCard != null) {
             const message = telegramCardMessage(resultCard);
             entities = [...parts.map((_, at) => entities[at] ?? []), message.entities];
             parts = [...parts, message.text];
         }
-        // Its links stay on the words: the card follows them.
         const keyedPart = parts.length - (resultCard != null ? 2 : 1);
-        // A subagent's question (v93): its options and "Answer in words", for the person it asks.
         const asked = flowKeys === null && choiceKeys === null ? openQuestionOf(store, notification.dedupeKey) : null;
         const questionKeys = asked === null ? null : telegramQuestionButtons(store, binding, asked, clock());
         const keys = flowKeys ?? choiceKeys ?? questionKeys;
         let last = null;
-        // A release card: every term goes as a file first, so Continue is offered only once it has arrived.
         if (offer?.file !== undefined && decided !== null) {
             if (fileSender === undefined || !await fileSender(offer.file)) {
                 dropDecideTokens(store, decided.tokens, clock());
@@ -1389,7 +1150,6 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
             store.placeTelegramFlowActions(flowKeys.tokens, last);
         if (choiceKeys !== null && last !== null) {
             store.placeTelegramFlowChoices(choiceKeys.tokens, last);
-            // A reply to this message, instead of a tap, is the person's note (applyFlowReply).
             if (sent?.reply === true)
                 store.recordTelegramFlowPrompt({ chatId: binding.chatId, messageId: last, binding: binding.id, card: choosing.card.id, entry: choosing.card.entry, mode: "send-back" }, clock(), 7 * 24);
         }
@@ -1399,25 +1159,15 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
             placeDecideTokens(store, decided.tokens, last);
         return { ok: true, receipt: receiptFor(botId, binding.chatId, last) };
     }
-    // A decision. Every safety-bearing word goes out before anything tappable
-    // exists: the question and every option's consequence first, then the
-    // recap, split across as many plain messages as they need — a button whose
-    // warning was truncated away is a trap, so the keyboard rides the LAST part
-    // only, and only if every earlier part arrived.
     const parts = split([`${notificationIdentity(notification)}${decisionAsk(decision)}`, "", `Background: ${decision.recap}`].join("\n"));
     for (const part of parts.slice(0, -1)) {
         const sent = await sender(part);
         if (!sent.ok)
             return { ok: false, error: sent.error };
-        // Every part is a message somebody may REPLY to with a note: each id
-        // routes to this decision, exactly (Codex free-text review, finding 1).
         if (sent.messageId !== null) {
             store.recordTelegramDecisionMessage(binding.id, binding.chatId, sent.messageId, decision.id, clock());
         }
     }
-    // The buttons: one opaque token per option, minted before the send so a
-    // tap can never arrive for a token that does not exist, placed onto the
-    // message afterwards so a tap on any OTHER message proves itself stale.
     const tokens = decision.options.map(option => ({
         option,
         token: randomBytes(16).toString("hex"),
@@ -1446,8 +1196,6 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
     return { ok: true, receipt: receiptFor(botId, binding.chatId, sent.messageId) };
 }
 async function send(transport, chatId, text, keyboard, entities, silent) {
-    // No markup parsing. Only machine-selected heading ranges may be bold;
-    // agent text remains literal and URLs never trigger link previews.
     let answer;
     try {
         answer = await transport("sendMessage", {
@@ -1455,7 +1203,6 @@ async function send(transport, chatId, text, keyboard, entities, silent) {
             text,
             ...(entities === undefined ? {} : { entities }),
             link_preview_options: { is_disabled: true },
-            // A new quiet card arrives without a sound; only a ping should buzz.
             ...(silent === true ? { disable_notification: true } : {}),
             ...(keyboard === undefined ? {} : { reply_markup: { inline_keyboard: keyboard } }),
         });
@@ -1479,8 +1226,6 @@ async function editProgress(transport, chatId, messageId, text, keyboard, entiti
     catch {
         return { ok: false, error: "Telegram progress update is unconfirmed; it will retry in place" };
     }
-    // The retry may be repainting the same bytes after an acknowledgement was
-    // lost. Telegram's explicit unchanged response confirms this target state.
     if (!answer.ok && !answer.uncertain && /^Bad Request: message is not modified\b/i.test(answer.description ?? ""))
         return { ok: true, messageId };
     if (!answer.ok) {
@@ -1492,7 +1237,6 @@ async function editProgress(transport, chatId, messageId, text, keyboard, entiti
     const confirmed = answer.result?.message_id;
     return String(confirmed) === messageId ? { ok: true, messageId } : { ok: false, error: "Telegram did not confirm the progress message identity" };
 }
-/** A tapped message's own formatting, read back for its edit: only bold and links that still fall inside the text. */
 function keptEntities(raw, length) {
     return (raw ?? []).flatMap((one) => {
         if (typeof one !== "object" || one === null)
@@ -1525,34 +1269,25 @@ function taskOf(store, decision) {
     const run = store.getRun(decision.run);
     return run === null ? "?" : store.externalIdFor(run.taskRef) ?? "?";
 }
-async function drainUpdates(store, botId, transport, owner, generation, cursor, clock, report, pollSeconds = 0, signal, readProjects, conversation, 
-/** True when the poll was ended on purpose for a delivery: an answer that failed then is that abort, not the wire. */
-deliveryWake) {
+async function drainUpdates(store, botId, transport, owner, generation, cursor, clock, report, pollSeconds = 0, signal, readProjects, conversation, deliveryWake) {
     const context = { store, botId, transport, clock, report, readProjects, conversation, projects: null };
     let offset = cursor + 1;
     for (let page = 0; page < PAGE_BUDGET; page++) {
         const answer = await transport("getUpdates", {
             offset,
-            // Only the first page long-polls; a backlog drains at full speed.
             timeout: page === 0 ? pollSeconds : 0,
             allowed_updates: ["message", "callback_query"],
         }, signal);
         if (!answer.ok) {
-            // Ended on purpose so a due message goes out now: no problem, no backoff; the next cycle asks again from the
-            // same cursor, so nothing is lost.
             if (deliveryWake?.() === true) {
                 report.deliveryWake = true;
                 return;
             }
             const said = answer.description ?? "failed";
-            // v98: another program asked Telegram for this bot's updates, and Telegram ended our
-            // request in its favour. Nothing is lost: an update is only gone once someone
-            // confirms it, and the next request asks again. Not a problem to report.
             if (/terminated by other getUpdates/i.test(said)) {
                 report.contention = (report.contention ?? 0) + 1;
                 return;
             }
-            // Telegram is pushing this bot's updates to a webhook: polling isn't how they arrive now.
             if (/webhook is active/i.test(said)) {
                 report.webhookActive = true;
                 return;
@@ -1566,7 +1301,6 @@ deliveryWake) {
         for (const raw of updates) {
             const update = readTelegramUpdate(raw);
             if (!update.ok) {
-                // Telegram's own update in a shape this bridge doesn't read: said, and passed over so the next one is read.
                 const id = raw?.update_id;
                 report.problems.push(`an update Telegram sent couldn't be read: ${update.issues.map(issue => issue.line).join("; ")}`);
                 if (typeof id !== "number" || !Number.isSafeInteger(id))
@@ -1578,24 +1312,11 @@ deliveryWake) {
             offset = update.value.update_id + 1;
         }
     }
-    // The budget ran out with Telegram still holding pages: said, not hidden.
     report.backlog = true;
 }
-/**
- * One update, polled or pushed (v98): the projects it may read, applied in
- * its own transaction (once: applyUpdate refuses an update id it has seen),
- * its Telegram-side effects, and the cursor moved past it.
- */
 async function processUpdate(context, update, owner, generation) {
-    // A proposal tap confirms as a principal minted against the CURRENT
-    // enrolled ceiling, and the registry is a file read: it happens
-    // before the update's transaction, and only once the envelope has
-    // proved the exact paired sender and chat — a stranger reads nothing.
     context.projects = update.message !== undefined ? await enrolledForMessage(context, update) : await projectsForTap(context, update);
     const effects = applyUpdate(context, update);
-    // Effects are Telegram-side conveniences — acks, edits, replies. They
-    // retry-or-drop; they never decide whether the cursor moves, because
-    // an unreachable edit must not make the bridge re-apply an answer.
     for (const effect of effects) {
         try {
             await effect();
@@ -1606,7 +1327,6 @@ async function processUpdate(context, update, owner, generation) {
     }
     context.store.advanceBridgeCursor(context.botId, owner, generation, update.update_id, context.clock());
 }
-/** v98: updates Telegram pushed to /hooks/telegram, applied in order through the same door as polled ones. */
 async function drainInbox(context, owner, generation) {
     let applied = 0;
     for (const queued of context.store.telegramInbox(context.botId, PAGE_BUDGET * 100)) {
@@ -1620,17 +1340,10 @@ async function drainInbox(context, owner, generation) {
     }
     return applied;
 }
-/** The enrolled registry, read before a message is applied: the team layer
- * scopes leads and conversations to it (each person's own access is checked
- * inside the domain). Unreadable reads as null, and the personal paths stay
- * exactly as they were. */
 async function enrolledForMessage(context, update) {
     const message = update.message;
     if (message?.chat === undefined || message.from === undefined || message.text === undefined || context.readProjects === undefined)
         return null;
-    // An untrusted envelope reads nothing: the sender must be paired, the
-    // text plain and direct, and the chat either that person's own private
-    // chat or a group that follows (or is being pointed at) a conversation.
     if (message.forward_origin !== undefined || message.forward_date !== undefined || message.via_bot !== undefined || message.sender_chat !== undefined || message.caption !== undefined)
         return null;
     const binding = context.store.liveTelegramBindingFor(context.botId, String(message.from.id));
@@ -1652,17 +1365,14 @@ async function enrolledForMessage(context, update) {
 }
 async function projectsForTap(context, update) {
     const callback = update.callback_query;
-    // Flow decision buttons (v86) work with or without the lead's conversation on this phone.
     const flowTap = callback !== undefined && (context.store.getTelegramFlowAction(callback.data ?? "") !== null || context.store.getTelegramFlowChoice(callback.data ?? "") !== null
         || flowConfirmOf(context.store, callback.data ?? "") !== null);
-    // So do a result's, plan's or pull request's own buttons (chat-decide.ts).
     const decideTap = callback !== undefined && isDecideToken(context.store, callback.data ?? "");
     if (callback === undefined || context.readProjects === undefined || (context.conversation === undefined && !flowTap && !decideTap))
         return null;
     const binding = callback.from === undefined ? null : context.store.liveTelegramBindingFor(context.botId, String(callback.from.id));
     if (binding === null || callback.from === undefined ||
         callback.message?.chat === undefined ||
-        // Proposal cards and task picks read the chat's project ceiling.
         (context.store.getTelegramProposalAction(callback.data ?? "") === null && !flowTap && !decideTap && !(callback.data ?? "").startsWith("pick:")))
         return null;
     const chat = callback.message.chat;
@@ -1677,18 +1387,10 @@ async function projectsForTap(context, update) {
         return null;
     }
 }
-/**
- * Apply one update in one transaction; return the Telegram-side effects to
- * attempt afterwards. Everything suspicious lands in the same place:
- * `ignored`, silently — an unbound stranger learns nothing, including
- * whether there was anything to learn.
- */
 function applyUpdate(context, update) {
     const effects = [];
     context.store.transact(() => {
         if (!context.store.markTelegramUpdateApplied(update.update_id, "seen", context.clock())) {
-            // Already applied by an earlier pass. The local mutation happened;
-            // the edits were attempted then; nothing repeats.
             return;
         }
         if (update.message !== undefined) {
@@ -1703,7 +1405,6 @@ function applyUpdate(context, update) {
     });
     return effects;
 }
-/** A group message that connects the group to a flow, or that the group's flow takes as a card. False: not for an inbox. */
 function applyGroupInbox(context, message, effects) {
     const { store, botId, transport, clock } = context;
     const chatId = String(message.chat.id), text = message.text ?? "";
@@ -1733,7 +1434,6 @@ function applyGroupInbox(context, message, effects) {
     const trigger = watchedChannel(store, "telegram", botId, chatId);
     if (trigger === null)
         return false;
-    // Forwards, other bots and channel posts don't become cards: only people writing in the group.
     if (message.forward_origin !== undefined || message.forward_date !== undefined || message.via_bot !== undefined || message.sender_chat !== undefined) {
         context.report.ignored++;
         return true;
@@ -1752,13 +1452,9 @@ function applyMessage(context, update, effects) {
     const chat = message.chat;
     const from = message.from;
     const pair = /^\/pair\s+([0-9a-f]{32})\s*$/.exec(message.text ?? "");
-    // A group as a flow's inbox (v89): "/flow 12" from a paired approver connects it; after that its messages are cards.
     if (pair === null && chat !== undefined && from !== undefined && (chat.type === "group" || chat.type === "supergroup") && typeof message.text === "string" && applyGroupInbox(context, message, effects))
         return;
     if (pair === null && chat !== undefined && from !== undefined) {
-        // The team layer first: `/team` anywhere, everything in a followed
-        // group, and a private chat that chose a conversation. Its replies ride
-        // the same post-commit effects as every other answer.
         const consumed = applyTeamInbound({
             store, botId, now: clock(), report, projects: context.projects, phoneOrigin: context.conversation?.phoneOrigin, updateId: update.update_id, message,
             say: (chatId, text, keyboard) => {
@@ -1770,23 +1466,13 @@ function applyMessage(context, update, effects) {
         });
         if (consumed)
             return;
-        // Replies to decisions retain their existing note meaning, even if the
-        // note starts with a slash. New read commands are direct messages only.
-        // A bare "start" as the very next message after a Start card is that card's yes (docs/plans/one-step-chat.md C5),
-        // not the help command. Only the routing is decided here, by the same ids the message path reads again when it
-        // records the yes; "/start", and "start" anywhere else, stay help.
         const yesSeat = message.reply_to_message === undefined && chat.type === "private" && typeof message.text === "string" && typedYes(message.text)
             && context.conversation !== undefined && context.readProjects !== undefined ? store.liveTelegramBindingFor(botId, String(from.id)) : null;
         const answersStartCard = yesSeat !== null && String(chat.id) === yesSeat.chatId
             && typedStartCard(store, { binding: yesSeat.id, chatId: yesSeat.chatId, approver: yesSeat.approver }, { id: String(message.message_id), replyTo: null }) !== null;
         if (message.reply_to_message === undefined && !answersStartCard && applyPhoneRead(context, update, effects))
             return;
-        // A reply to a decision message this bot sent is a note, exactly as
-        // before. Everything else that is ordinary text talks to the shared
-        // assistant when a conversation is configured; otherwise silence.
         const binding = store.liveTelegramBindingFor(botId, String(from.id));
-        // A reply to an Edit or Send back prompt (v86): the new draft, or the note it goes back with.
-        // A reply to a subagent's "Answer in words" prompt (v93): the answer.
         const questionPrompt = binding !== null && message.reply_to_message !== undefined && String(chat.id) === binding.chatId
             ? store.telegramQuestionPrompt(binding.chatId, String(message.reply_to_message.message_id), clock()) : null;
         if (binding !== null && questionPrompt !== null) {
@@ -1811,8 +1497,6 @@ function applyMessage(context, update, effects) {
             }
             return;
         }
-        // After Request changes asked "What should change?": the person's next message in their own chat is the feedback.
-        // A reply to some other message (a decision, a result) keeps its own meaning.
         const decidePrompt = binding !== null && chat.type === "private" && String(chat.id) === binding.chatId && typeof message.text === "string" && message.text.trim() !== "" && !message.text.startsWith("/")
             ? openPromptFor(store, { channel: "telegram", binding: binding.id, chat: binding.chatId }, clock()) : null;
         if (binding !== null && decidePrompt !== null && answersPrompt(decidePrompt, message.reply_to_message === undefined ? null : String(message.reply_to_message.message_id))) {
@@ -1831,7 +1515,6 @@ function applyMessage(context, update, effects) {
             });
             return;
         }
-        // D5: a message naming a subagent ("@rosa …") goes to the lead like any other, which asks the subagent with a card.
         const repliedDecision = binding !== null && message.reply_to_message !== undefined
             ? store.decisionForTelegramMessage(binding.id, binding.chatId, String(message.reply_to_message.message_id))
             : null;
@@ -1842,9 +1525,6 @@ function applyMessage(context, update, effects) {
         applyNote(context, update, effects);
         return;
     }
-    // Only /pair, only in a private chat, only with the sender on the record.
-    // A group is exactly where "the chat" and "the person" diverge, which is
-    // why a group cannot pair at all.
     if (pair === null || chat === undefined || chat.type !== "private" || from === undefined) {
         report.ignored++;
         return;
@@ -1857,8 +1537,6 @@ function applyMessage(context, update, effects) {
         updateId: update.update_id,
     }, clock());
     if (!consumed.ok) {
-        // A wrong code gets the same silence as everything else wrong: replying
-        // "no such code" to a guesser is an oracle.
         report.ignored++;
         return;
     }
@@ -1866,27 +1544,14 @@ function applyMessage(context, update, effects) {
     const chatId = String(chat.id);
     const approver = consumed.binding.approver;
     effects.push(async () => {
-        // At-least-once across a crash-after-send window, by design: a repeated
-        // "paired" line is annoying; a paired chat that never heard so is worse.
         await transport("sendMessage", {
             chat_id: chatId,
             text: `paired: this chat now answers as ${approver}\n\nSend /status to check recent work, /task <id> for one task, or /help for your options.`,
             link_preview_options: { is_disabled: true },
         });
-        // The bot is Toolroll in every chat list from here on (best effort; pairing never waits on it).
         await nameTelegramBot(transport, "pairing");
     });
 }
-/**
- * An ordinary message from the paired person: persisted for the shared
- * assistant in THIS transaction — before the cursor moves — with the exact
- * binding, sender, update, message and the request identity the engine
- * receipts its turn under. Two things are answered here and now without a
- * model: text over the engine's bound (never truncated), and a reply to a
- * message that carried several tasks (never guessed). Everything hostile is
- * silence, as for every other inbound shape.
- */
-/** At most this many of a chat's messages wait for the lead at once (the personal lead queue's bound). */
 export const TELEGRAM_MAX_WAITING = 10;
 function applyConversation(context, update, effects) {
     const { store, botId, transport, clock, report } = context;
@@ -1923,8 +1588,6 @@ function applyConversation(context, update, effects) {
         report.chatRefused = (report.chatRefused ?? 0) + 1;
         return;
     }
-    // A reply binds to what the replied-to message carried: exactly one task
-    // (and its run) pins the turn; several ask which; none is a plain turn.
     let context_ = null;
     let taskId = null;
     let sourceRun = null;
@@ -1943,8 +1606,6 @@ function applyConversation(context, update, effects) {
             context_ = replyContextFor(taskId, sourceRun, bindings.find(one => one.image !== undefined)?.image);
         }
     }
-    // No reply target: the task this chat chose to talk about, if any. The
-    // turn re-proves it; a task no longer in reach reads as a plain message.
     if (taskId === null) {
         const focused = store.chatFocus("telegram", binding.id);
         if (focused !== null) {
@@ -1952,16 +1613,11 @@ function applyConversation(context, update, effects) {
             context_ = focusContextFor(focused);
         }
     }
-    // The lead queue's bound, per chat: ten messages wait at most; the next is answered at once instead of queued.
     if (store.telegramMessagesWaiting(binding.id) >= TELEGRAM_MAX_WAITING) {
         say(`${TELEGRAM_MAX_WAITING} messages are already waiting for the lead. Wait for a reply, then send this again.`);
         report.ignored++;
         return;
     }
-    // A typed yes to a Start card (docs/plans/one-step-chat.md C5) is read here, before any model runs, and recorded with
-    // the message in the same transaction: the fixed words only, tied to one exact card by message ids and Toolroll's own
-    // delivery record. The worker acts on it (confirmTypedStart) and no lead turn runs for it. Anything else is queued for
-    // the lead exactly as before.
     store.transact(() => {
         const typed = typedYes(text) ? typedStartCard(store, { binding: binding.id, chatId: binding.chatId, approver: binding.approver }, { id: String(message.message_id), replyTo }) : null;
         store.enqueueTelegramConversation({
@@ -1972,9 +1628,6 @@ function applyConversation(context, update, effects) {
             recordTypedStart(store, `m${update.update_id}`, typed, clock());
     });
     report.chatQueued = (report.chatQueued ?? 0) + 1;
-    // Saved: 👀 on the owner's message right away (docs/plans/responsive-chat.md §3.1), once this update's transaction
-    // has committed. It comes off when the answer or the failure notice is delivered. Never awaited: a burst of messages
-    // waits its turn on the chat's own lane, not the drain.
     const gapMs = context.conversation?.liveTiming?.ackGapMs;
     effects.push(async () => {
         void telegramAck({
@@ -1986,9 +1639,6 @@ function applyConversation(context, update, effects) {
         });
     });
 }
-/** The picker's buttons: one task per row (its title and where it stands),
- * carried by the task's numeric reference so the data fits Telegram's 64
- * bytes; a tap re-proves the task against the ceiling. */
 function pickKeyboard(store, choices, focused) {
     const rows = [];
     for (const one of choices) {
@@ -2000,7 +1650,6 @@ function pickKeyboard(store, choices, focused) {
         rows.push([telegramButton("Back to the lead", "pick:lead")]);
     return rows;
 }
-/** The title of the task this Telegram chat chose to talk about, if any. */
 function focusedTitle(store, binding) {
     const id = store.chatFocus("telegram", binding.id);
     return id === null ? null : { id, title: phoneText(store.getTask(id)?.title ?? id, 64) };
@@ -2020,8 +1669,6 @@ function applyPhoneRead(context, update, effects) {
         report.ignored++;
         return true;
     }
-    // Like decision-message edits, a read reply is best-effort after the update
-    // was consumed. A crash or send failure cannot turn replay into a new action.
     effects.push(async () => {
         const stillPaired = () => {
             const live = store.liveTelegramBindingById(binding.id);
@@ -2030,12 +1677,8 @@ function applyPhoneRead(context, update, effects) {
         if (!stillPaired())
             return;
         let response = PHONE_HELP;
-        // `/task` may carry ONE url button to the exact recorded task or result:
-        // minted from the trusted origin read now, never persisted, never a token.
         let button = null;
-        // `/tasks` and an ambiguous `/task <name>` offer tasks as buttons.
         let keyboard = null;
-        // The one task (and saved result) a `/task` reply shows: a reply to it is about that task.
         let shown = null;
         if (command.kind === "lead") {
             store.setChatFocus("telegram", binding.id, null, clock());
@@ -2043,9 +1686,6 @@ function applyPhoneRead(context, update, effects) {
         }
         else if (command.kind !== "help") {
             try {
-                // The registry, then — after the await — the pairing again and the
-                // account's OWN ceiling over it: a project this approver was never
-                // given, or lost since, is not read, named or linked from here.
                 const registry = await context.readProjects?.() ?? [];
                 if (!stillPaired())
                     return;
@@ -2072,22 +1712,17 @@ function applyPhoneRead(context, update, effects) {
                         const view = phoneTaskView(store, repos, pick.view, clock(), context.conversation?.evidenceRoot);
                         shown = { task: pick.view, run: view.run };
                         button = phoneLinkButton(context.conversation?.phoneOrigin?.() ?? null, view.link);
-                        // A destination with no trusted origin to carry it: the words say where instead.
                         response = phoneFocusText(button === null && view.link !== null ? `${view.text}\n\n${PHONE_CONSOLE_FOOTER}` : view.text);
                     }
                 }
             }
             catch {
-                // No registry paths, SQLite errors, credentials, or stale snapshots
-                // leave on the failure road. A new request can try again.
                 response = "I couldn't read the current project status. No tasks were changed. Try /status again; if it persists, check Toolroll on the computer.";
                 report.problems.push("phone status could not read the current project records");
             }
         }
         if (!stillPaired())
             return;
-        // Each view fits one message. Fail visibly if a future change violates
-        // that contract, rather than cutting off the important next action.
         if (response.length > PART_CAP) {
             response = "This status is too large for one phone message. Open the console for the full view, or send /task <id> for one task.";
             report.problems.push("phone status exceeded its message bound");
@@ -2105,24 +1740,14 @@ function applyPhoneRead(context, update, effects) {
             report.problems.push(`phone status reply failed for update ${update.update_id}; send a new command to retry`);
         const sentId = sent.ok ? sent.result?.message_id : undefined;
         if (shown !== null && typeof sentId === "number" && Number.isSafeInteger(sentId) && sentId > 0) {
-            // Best effort: without it a reply still reaches the chosen task through the focus.
             try {
                 store.recordTelegramTaskMessage(binding, String(sentId), shown.task, shown.run, clock());
             }
-            catch { /* the focus still holds */ }
+            catch { }
         }
     });
     return true;
 }
-/**
- * A free-text note, accepted only as an AUTHENTICATED REPLY to a recorded
- * decision message (Codex free-text review, prescribed design): live
- * binding, private chat, exact chat AND user, a reply_to that maps to
- * exactly one decision this bot sent, the decision still unanswered, and
- * direct initial plain text — no forwards, media, captions, bots, or
- * channel identities. Everything else is silence: a reply naming what was
- * wrong is an oracle. Choice stays TAP-ONLY; prose never selects an option.
- */
 function applyNote(context, update, effects) {
     const { store, botId, transport, clock, report } = context;
     const message = update.message;
@@ -2155,8 +1780,6 @@ function applyNote(context, update, effects) {
     }
     const decisionId = store.decisionForTelegramMessage(binding.id, binding.chatId, String(message.reply_to_message.message_id));
     if (decisionId === null) {
-        // A reply to something that never carried a decision — including a
-        // send whose record was lost: fail closed, never guess by recency.
         report.ignored++;
         return;
     }
@@ -2185,16 +1808,11 @@ function applyNote(context, update, effects) {
         note: valid.note,
     }, clock());
     if (!saved) {
-        // An older or equal update raced in late: the newer note stands.
         report.ignored++;
         return;
     }
-    // A new note voids any ARMED irreversible confirmation: what it showed
-    // is no longer what would travel (Codex free-text review, finding 3).
     store.consumeTelegramChallenges(decision.id, clock());
     report.noted = (report.noted ?? 0) + 1;
-    // The echo IS the ceremony: the exact captured text, line-prefixed, so a
-    // later edit of the operator's own message cannot rewrite the audit.
     say([
         `noted for ${taskOf(store, decision)}:`,
         ...valid.note.split("\n").map((line) => `| ${line}`),
@@ -2234,15 +1852,9 @@ function applyCallback(context, update, effects) {
             });
         });
     };
-    // The person, the chat, and the message must all be the paired ones. A
-    // callback with no accessible message (inline mode, too-old messages) is
-    // out; so is a tap from anyone but the exact paired user id — usernames
-    // change hands, immutable ids do not.
     const binding = from === undefined ? null : store.liveTelegramBindingFor(botId, String(from.id));
     const tapChat = message?.chat === undefined ? null : String(message.chat.id);
     const followedGroup = tapChat !== null && binding !== null && tapChat !== binding.chatId && store.telegramTeamChat(botId, tapChat)?.kind === "group";
-    // A result's, plan's, failure's or pull request's own buttons act only in the paired person's own chat; a tap
-    // anywhere else is still answered, so the button never just spins.
     if (isDecideToken(store, token) && (binding === null || tapChat === null || tapChat !== binding.chatId)) {
         report.ignored++;
         ack(binding === null ? "These buttons work only for the person they were sent to. Nothing was done."
@@ -2257,16 +1869,12 @@ function applyCallback(context, update, effects) {
         report.ignored++;
         return;
     }
-    // The paired person, in their chat: a button whose data isn't one Toolroll makes is answered with why, and does nothing.
     const data = readTelegramButtonData(callback.data);
     if (!data.ok) {
         report.ignored++;
         ack(`That button couldn't be read (${data.issues.map(issue => issue.line).join("; ")}). Nothing was done.`.slice(0, 190));
         return;
     }
-    // A task picked from /tasks: this private chat now talks about it (or,
-    // "Back to the lead", about everything again). The task is re-proved
-    // against the chat's ceiling at the tap.
     const pick = pickOf(token);
     if (pick !== null) {
         if (tapChat !== binding.chatId) {
@@ -2297,7 +1905,6 @@ function applyCallback(context, update, effects) {
         editText(phoneFocusText(view.text), [[telegramButton("Back to the lead", "pick:lead")]]);
         return;
     }
-    // A subagent's question (v93): an option answers it; "Answer in words" asks for a reply.
     const questionAction = store.getTelegramQuestionAction(token);
     if (questionAction !== null) {
         if (questionAction.binding !== binding.id || questionAction.chatId !== tapChat || (questionAction.messageId !== null && questionAction.messageId !== String(message.message_id))) {
@@ -2320,13 +1927,11 @@ function applyCallback(context, update, effects) {
         }
         return;
     }
-    // A flow decision's repaint: its buttons (fresh ones stamped on this message) or links under the console.
     const flowEdit = (effect) => {
         if (effect.place !== undefined && effect.place.length > 0)
             store.placeTelegramFlowActions(effect.place, String(message.message_id));
         editText(effect.text, decideKeyboard(context.conversation?.phoneOrigin, effect.keyboard ?? []));
     };
-    // The Yes or Cancel a flow Approve armed (telegram-flow.ts): on the message it was armed on, by the person it was armed for.
     const flowConfirm = flowConfirmOf(store, token);
     if (flowConfirm !== null) {
         if (flowConfirm.binding !== binding.id || flowConfirm.chatId !== tapChat || flowConfirm.messageId !== String(message.message_id)) {
@@ -2358,7 +1963,6 @@ function applyCallback(context, update, effects) {
                 flowEdit(effect);
             else
                 effects.push(async () => {
-                    // A reply box: whatever they send back as a reply to this prompt is the new draft, or the note.
                     const answer = await transport("sendMessage", { chat_id: binding.chatId, text: effect.text, link_preview_options: { is_disabled: true },
                         reply_parameters: { message_id: message.message_id }, reply_markup: { force_reply: true, input_field_placeholder: effect.placeholder } });
                     const id = answer.result?.message_id;
@@ -2368,7 +1972,6 @@ function applyCallback(context, update, effects) {
         }
         return;
     }
-    // A "Person chooses" option (flow-send.ts): the card goes where it leads, or is ignored.
     const choiceAction = store.getTelegramFlowChoice(token);
     if (choiceAction !== null) {
         if (choiceAction.binding !== binding.id || choiceAction.chatId !== tapChat || (choiceAction.messageId !== null && choiceAction.messageId !== String(message.message_id))) {
@@ -2380,13 +1983,11 @@ function applyCallback(context, update, effects) {
         for (const effect of applyFlowChoiceTap(store, binding, choiceAction, { text: message.text ?? "" }, repos, clock())) {
             if (effect.kind === "ack")
                 ack(effect.text);
-            // An item list's message (flow-items.ts) keeps its bold titles and labelled links under what was chosen; any other stays plain.
             else if (effect.kind === "edit")
                 editText(effect.text, undefined, listed ? keptEntities(message.entities, effect.text.length) : undefined);
         }
         return;
     }
-    // The lead's question to its owner: an option is sent as their next message; "Something else" asks them to type it.
     const askTap = askOf(token);
     if (askTap !== null) {
         if (tapChat !== binding.chatId || context.conversation === undefined) {
@@ -2430,7 +2031,6 @@ function applyCallback(context, update, effects) {
         editText(`${message.text ?? ask.question}\n\nYou chose: ${option}`.slice(0, 4000));
         return;
     }
-    // A result's, plan's, failure's or pull request's own buttons (chat-decide.ts): in the person's own chat only.
     if (isDecideToken(store, token)) {
         const repos = context.projects === null ? null : telegramConversationRepos(store, binding.approver, context.projects);
         if (repos === null) {
@@ -2447,8 +2047,6 @@ function applyCallback(context, update, effects) {
         if (tapped.ignored === true)
             report.ignored++;
         ack(tapped.ack.slice(0, 190));
-        // A release card's terms, as a file, before its Approve is shown (chat-management.md §0a.5): Approve appears only
-        // once Telegram has accepted this file; a refused or failed upload shows the card without it, Continue to try again.
         if (tapped.file !== undefined && tapped.edit !== undefined && tapped.unsent !== undefined) {
             const file = tapped.file, edit = tapped.edit, unsent = tapped.unsent;
             effects.push(async () => {
@@ -2466,7 +2064,6 @@ function applyCallback(context, update, effects) {
             });
         }
         else if (tapped.file !== undefined) {
-            // A file without its gate never reaches here (chat-decide pairs them); fail closed: nothing that approves is shown.
             if (tapped.edit !== undefined)
                 dropDecideTokens(store, tapped.edit.tokens, clock());
             editText(`${message.text ?? ""}\n\nThis release can't be approved here. Open it in Toolroll.`.trim().slice(0, 4000), []);
@@ -2485,7 +2082,6 @@ function applyCallback(context, update, effects) {
         }
         if (tapped.merge !== undefined) {
             const merge = tapped.merge, shown = tapped.edit?.text ?? message.text ?? "";
-            // GitHub is a network call: after the tap's transaction, then the card says how it went.
             effects.push(async () => {
                 let merged;
                 try {
@@ -2495,9 +2091,7 @@ function applyCallback(context, update, effects) {
                 catch {
                     merged = { ok: false, message: "GitHub couldn't be reached just now. Try again from the task." };
                 }
-                // The ledger says what happened, failure included, once GitHub has answered.
                 recordChatMerge(store, merge, merged.ok ? { ok: true } : { ok: false, message: merged.message }, clock());
-                // A merge that didn't land keeps a way to the task.
                 await transport("editMessageText", { chat_id: binding.chatId, message_id: message.message_id, text: mergedText(shown, merged.ok ? { ok: true } : { ok: false, message: merged.message }).slice(0, 4000),
                     link_preview_options: { is_disabled: true }, reply_markup: { inline_keyboard: merged.ok ? [] : decideKeyboard(context.conversation?.phoneOrigin, linksFor({ kind: "merge", taskId: merge.taskId, run: merge.runId })) } });
             });
@@ -2506,9 +2100,6 @@ function applyCallback(context, update, effects) {
     }
     const action = store.getTelegramAction(token);
     if (action === null && context.conversation !== undefined && store.getTelegramProposalAction(token) !== null) {
-        // A proposal card's button: the shared confirm door, inside this
-        // update's transaction, with the stop's process signal deferred to
-        // after its commit (the door's own ordering, preserved from here).
         const tapped = applyProposalTap(store, binding, token, message, context.projects, context.conversation, clock());
         for (const effect of tapped.effects) {
             if (effect.kind === "ack")
@@ -2528,7 +2119,6 @@ function applyCallback(context, update, effects) {
         action.binding !== binding.id ||
         action.chatId !== binding.chatId ||
         (action.messageId !== null && action.messageId !== String(message.message_id))) {
-        // Bound person, dead or foreign button: acknowledged, not acted on.
         ack("that button is stale — toolroll decide shows what still waits");
         report.ignored++;
         return;
@@ -2551,8 +2141,6 @@ function applyCallback(context, update, effects) {
             return;
         }
         if (expiredDraftGuard(store, binding, decision.id, clock())) {
-            // The token is NOT consumed: the same button answers on the next tap,
-            // now that the operator knows the note is gone.
             ack("your note expired — tap again to answer without it, or reply with a fresh note first");
             return;
         }
@@ -2561,16 +2149,9 @@ function applyCallback(context, update, effects) {
             return;
         }
         if (!option.reversible) {
-            // The arm. Nothing is answered here: two fresh one-time tokens make a
-            // real challenge — a stolen bot token can repaint a keyboard, but it
-            // cannot mint a row in this table, so a tap on a forged "confirm"
-            // lands in the stale-button branch above.
             const confirm = randomBytes(16).toString("hex");
             const cancel = randomBytes(16).toString("hex");
             const placedOn = String(message.message_id);
-            // The confirmation binds the EXACT answer tuple: option AND the note
-            // it displays (its digest; null when none). A note that changes,
-            // expires, or is cancelled strands this challenge (finding 3).
             const draft = store.liveNoteDraft(binding.id, decision.id, clock());
             const digest = draft === null ? undefined : noteDigestOf(draft.note);
             if (draft !== null)
@@ -2592,15 +2173,11 @@ function applyCallback(context, update, effects) {
             ack("that confirmation expired — start again from the option");
             return;
         }
-        // Re-proved at the moment of commitment, not remembered from the arm.
         const option = decision.options.find(one => one.id === action.optionId);
         if (option === undefined) {
             ack("that option no longer exists");
             return;
         }
-        // The tuple the challenge displayed must still be the tuple that
-        // travels: the CURRENT live draft's digest (or none) must equal what
-        // was armed. Anything else strands the yes (finding 3).
         const current = store.liveNoteDraft(binding.id, decision.id, clock());
         const currentDigest = current === null ? null : noteDigestOf(current.note);
         if ((action.noteDigest ?? null) !== currentDigest) {
@@ -2611,9 +2188,6 @@ function applyCallback(context, update, effects) {
         answerNow(context, decision, option.id, binding, ack, editText);
         return;
     }
-    // cancel: consume it, kill its sibling confirm, discard the note draft
-    // (cancel means cancelled — the note it displayed dies with it), and
-    // restore the choices.
     store.consumeTelegramAction(token, clock());
     store.consumeTelegramChallenges(decision.id, clock());
     {
@@ -2626,7 +2200,6 @@ function applyCallback(context, update, effects) {
         store.createTelegramAction({ token: choose, binding: binding.id, decision: decision.id, optionId: option.id, phase: "choose", chatId: binding.chatId, messageId: String(message.message_id) }, clock());
     }
     ack("cancelled");
-    // The card again, within one message; a decision too long for one keeps the consequences its earlier parts show.
     const ask = decisionAsk(decision);
     editText(ask.length <= PART_CAP ? ask : `Decide: ${decision.question}`, fresh.map(({ option, token: choose }) => [
         telegramButton(`${option.label}${option.id === decision.recommendation ? " ✓" : ""}${option.reversible ? "" : " ⚠"}`, choose),
@@ -2634,9 +2207,6 @@ function applyCallback(context, update, effects) {
 }
 function answerNow(context, decision, choice, binding, ack, editText) {
     const { store, clock, report } = context;
-    // The live draft is the note that travels — consumed WITH the answer in
-    // the same transaction the whole update already holds; a CAS loss
-    // discards it (Codex free-text review, finding 4: never choose-then-note).
     const draft = store.liveNoteDraft(binding.id, decision.id, clock());
     const answered = store.answerDecisionLocked({ id: decision.id, choice, by: binding.approver, via: "telegram", ...(draft === null ? {} : { note: draft.note }) }, clock());
     if (answered.ok) {
@@ -2658,7 +2228,6 @@ function answerNow(context, decision, choice, binding, ack, editText) {
     }
     ack(`could not answer: ${answered.reason}`);
 }
-/** A decision's card, action first: the question, then each option with what it does, then its deadline. */
 function decisionAsk(decision) {
     return [
         `Decide: ${decision.question}`,
@@ -2666,7 +2235,6 @@ function decisionAsk(decision) {
         ...(decision.deadline === null ? [] : [`Decide by ${decision.deadline.slice(0, 16).replace("T", " ")} UTC`]),
     ].join("\n");
 }
-/** The armed confirm of an option that can't be undone: what it is and what it does, then the note that travels. */
 function armedDecisionText(option, note) {
     return [
         `${option.label}? ⚠ This can't be undone.`,
@@ -2681,19 +2249,12 @@ function answeredText(store, decision) {
     return [
         `✓ Answered: ${chosen}`,
         `${taskOf(store, decision)} · by ${decision.answeredBy ?? "?"} via ${decision.answeredVia ?? "?"}`,
-        // Line-prefixed, never inline: a multiline note must not be able to
-        // draw fake status lines (Codex free-text review, finding 7).
         ...(decision.note === null ? [] : ["with note:", ...decision.note.split("\n").map(line => `| ${line}`)]),
     ].join("\n");
 }
 function noteDigestOf(note) {
     return createHash("sha256").update(note, "utf8").digest("hex").slice(0, 32);
 }
-/**
- * A pending draft that ALREADY EXPIRED must never silently drop: the tap
- * proceeds only after the operator is told (Codex free-text review, state
- * machine — "never silently answer without the expected note").
- */
 function expiredDraftGuard(store, binding, decisionId, now) {
     const expired = store.telegramChat()
         .prepare(`SELECT id FROM chat_note_draft
@@ -2704,11 +2265,8 @@ function expiredDraftGuard(store, binding, decisionId, now) {
     store.setNoteDraftState(Number(expired["id"]), ["pending", "armed"], "discarded");
     return true;
 }
-/** Bridges in this process waiting out their push idle, by bot: a kept push ends the wait early. */
 const bridgeWakers = new Map();
-/** Bots with a push kept while no bridge idled (it was mid-cycle): the next idle doesn't wait. */
 const bridgeWokenEarly = new Set();
-/** A pushed update was kept for this bot: wake its bridge if it runs in this process (docs/plans/responsive-chat.md §3.1). */
 export function wakeTelegramBridge(botId) {
     const wakers = bridgeWakers.get(botId);
     if (wakers === undefined || wakers.size === 0) {
@@ -2718,15 +2276,9 @@ export function wakeTelegramBridge(botId) {
     for (const wake of wakers)
         wake();
 }
-/** The newest notification id now: a follower cycle's mark for what its delivery covers. */
 function newestNotificationIdOf(store) {
     return Number(store.handle.prepare("SELECT COALESCE(MAX(id), 0) AS id FROM notification").get()?.["id"] ?? 0);
 }
-/**
- * Whether a message for this bot was written after `mark` and is still due: unresolved, addressed to everyone or to a
- * person paired with this bot, and the bot not held back by Telegram's rate limit. Read-only; delivery itself still
- * decides each row under its own fences.
- */
 export function telegramOutboxDue(store, botId, mark, now) {
     const approvers = [...new Set(store.liveTelegramBindings(botId).map(binding => binding.approver))];
     if (approvers.length === 0)