toolroll 0.9.36 → 0.9.38

package/dist/telegram-mate.d.ts

@@ -4,6 +4,7 @@ import { type DoorOptions } from "./mate-doors.js";
 import { type MateAsk, type Store, type TelegramBinding } from "./store.js";
 import type { SubscriptionMateRunner } from "./subscription-chat.js";
 import type { TelegramTransport } from "./telegram.js";
+import { type TelegramCallbackButton, type TelegramUpdate } from "./contracts/telegram-callback.js";
 /** How long one claimed turn may go without a heartbeat before another poller may take it over. */
 export declare const CONVERSATION_CLAIM_MS: number;
 /** A busy engine (one turn at a time) defers a queued message this long, up to the age bound below. */
@@ -74,19 +75,13 @@ export declare function phoneLinkButton(origin: string | null, link: PhoneLink |
 /** The buttons under the lead's question: options two to a row, then "Something else". Each names the turn and the
  * option's place, nothing more; a tap re-proves that the question is still open and is the tapper's own. */
 export declare function askKeyboard(ask: MateAsk): CallbackKeyboard;
-export type InlineButton = {
-    text: string;
-    callback_data: string;
-} | {
+export type InlineButton = TelegramCallbackButton | {
     text: string;
     url: string;
 };
 type Keyboard = InlineButton[][];
 /** What a part persists: callback tokens only. A url is minted at send time, never stored. */
-type CallbackKeyboard = {
-    text: string;
-    callback_data: string;
-}[][];
+type CallbackKeyboard = TelegramCallbackButton[][];
 /** Mint the card's tokens before the send, so a tap can never name a token that does not exist. */
 export declare function mintCardTokens(store: Store, binding: TelegramBinding, proposal: number, now: Date, messageId?: string, chatId?: string): {
     keyboard: CallbackKeyboard;
@@ -111,12 +106,7 @@ export type CardEffect = {
  * ceiling; the door re-proves standing, ceiling, session and the
  * proposal's own terms again inside its transaction.
  */
-export declare function applyProposalTap(store: Store, binding: TelegramBinding, token: string, message: {
-    message_id: number;
-    chat?: {
-        id: number;
-    };
-}, repos: readonly string[] | null, options: TelegramConversationOptions, now: Date): {
+export declare function applyProposalTap(store: Store, binding: TelegramBinding, token: string, message: NonNullable<NonNullable<TelegramUpdate["callback_query"]>["message"]>, repos: readonly string[] | null, options: TelegramConversationOptions, now: Date): {
     effects: CardEffect[];
     confirmed: boolean;
     ignored: boolean;

package/dist/telegram-mate.js

@@ -33,6 +33,7 @@ import { WARM_EMOJI, warmTurn } from "./chat-warmth.js";
 import { TeamLeads } from "./team-leads.js";
 import { chatResultHref } from "./chat-controls.js";
 import { resultImageFileName, safeResultImageCaption, verifyResultImage } from "./chat-evidence.js";
+import { telegramButton } from "./contracts/telegram-callback.js";
 /** How long one claimed turn may go without a heartbeat before another poller may take it over. */
 export const CONVERSATION_CLAIM_MS = 2 * 60_000;
 /** A busy engine (one turn at a time) defers a queued message this long, up to the age bound below. */
@@ -110,8 +111,8 @@ function keyboardWith(callbacks, link) {
 export function askKeyboard(ask) {
     const rows = [];
     for (let at = 0; at < ask.options.length; at += 2)
-        rows.push(ask.options.slice(at, at + 2).map((label, offset) => ({ text: label.slice(0, 60), callback_data: `ask:${ask.turn}:${at + offset}` })));
-    rows.push([{ text: MATE_ASK_OTHER, callback_data: `ask:${ask.turn}:x` }]);
+        rows.push(ask.options.slice(at, at + 2).map((label, offset) => telegramButton(label.slice(0, 60), `ask:${ask.turn}:${at + offset}`)));
+    rows.push([telegramButton(MATE_ASK_OTHER, `ask:${ask.turn}:x`)]);
     return rows;
 }
 /** Mint the card's tokens before the send, so a tap can never name a token that does not exist. */
@@ -121,7 +122,7 @@ export function mintCardTokens(store, binding, proposal, now, messageId, chatId
     for (const [token, phase] of [[confirm, "confirm"], [dismiss, "dismiss"]]) {
         store.createTelegramProposalAction({ token, binding: binding.id, proposal, phase, chatId, ttlMs: CARD_TTL_MS, ...(messageId === undefined ? {} : { messageId }) }, now);
     }
-    return { keyboard: [[{ text: "Confirm", callback_data: confirm }, { text: "Dismiss", callback_data: dismiss }]], tokens: [confirm, dismiss] };
+    return { keyboard: [[telegramButton("Confirm", confirm), telegramButton("Dismiss", dismiss)]], tokens: [confirm, dismiss] };
 }
 /**
  * One tap on a proposal card, applied inside the update's own transaction
@@ -249,15 +250,15 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         if (challenged) {
             ack("confirm it");
             edit(`${body}\n\nThis records that you handled this exact result. Confirm?`, [
-                [{ text: `✓ Yes, ${CHAT_ACTIONS[sharedAction.operation].label.toLowerCase()}`, callback_data: yes }],
-                [{ text: "Cancel", callback_data: cancel }],
+                [telegramButton(`✓ Yes, ${CHAT_ACTIONS[sharedAction.operation].label.toLowerCase()}`, yes)],
+                [telegramButton("Cancel", cancel)],
             ]);
             return;
         }
         ack("irreversible — confirm it");
-        edit(`⚠ This answer is IRREVERSIBLE.\n\n${body}\n\nConfirm?`, [
-            [{ text: "⚠ Yes, answer it", callback_data: yes }],
-            [{ text: "Cancel", callback_data: cancel }],
+        edit(`${body}\n\n⚠ Last step: this answer can't be undone. Confirm?`, [
+            [telegramButton("⚠ Yes, answer it", yes)],
+            [telegramButton("Cancel", cancel)],
         ]);
     };
     if (action.phase === "confirm" && (irreversible || challenged)) {

package/dist/telegram-team.d.ts

@@ -9,6 +9,7 @@
 import type { Store } from "./store.js";
 import { type InlineButton } from "./telegram-mate.js";
 import type { TelegramTransport } from "./telegram.js";
+import type { TelegramMessage } from "./contracts/telegram-callback.js";
 export type TeamCommand = {
     kind: "list";
 } | {
@@ -36,25 +37,7 @@ export type TeamInbound = {
     projects: readonly string[] | null;
     phoneOrigin: (() => string | null) | undefined;
     updateId: number;
-    message: {
-        message_id: number;
-        text?: string;
-        chat?: {
-            id: number;
-            type?: string;
-        };
-        from?: {
-            id: number;
-        };
-        reply_to_message?: {
-            message_id: number;
-        };
-        forward_origin?: unknown;
-        forward_date?: unknown;
-        via_bot?: unknown;
-        sender_chat?: unknown;
-        caption?: string;
-    };
+    message: TelegramMessage;
     /** Queue one reply for after the update's transaction commits. */
     say: (chatId: string, text: string, keyboard?: InlineButton[][]) => void;
 };

package/dist/telegram.d.ts

@@ -37,7 +37,7 @@ export declare function telegramHookSecret(dir: string, make?: boolean): string
 export declare function telegramPushUrl(hooksBase: string | null): string | null;
 /** A push is Telegram's when its secret header matches ours (compared in constant time). */
 export declare function pushedByTelegram(header: unknown, secret: string | null): boolean;
-/** Keep one pushed update for the bridge: a JSON object with a positive integer update_id. */
+/** Keep one pushed update for the bridge. A schema-invalid JSON update is logged and acknowledged, never retried. */
 export declare function keepPushedUpdate(store: Store, botId: string, body: Buffer, now: Date): {
     ok: true;
     kept: boolean;

package/dist/telegram.js

@@ -34,7 +34,7 @@ import { enqueueEveningDigests, finishedView, isTaskFact, joinsBatch, needsPerso
 import { BATCH_MS, chatText, chatTitle, factLinkLabel, mentions, nameTelegramBot } from "./chat-voice.js";
 import { LEAD_SAY_KIND, enqueueLeadLapses, leadSayEarlier, leadSayText, leadSubjectOf } from "./lead-voice.js";
 import { applyTeamInbound, deliverTeamChats, teamCommand } from "./telegram-team.js";
-import { applyFlowChoiceTap, applyFlowReply, applyFlowTap, FLOW_DECIDE_KEY, flowButtons, flowChoiceButtons, flowDecisionAt, flowSendKeyboardRow, flowSentContent } from "./telegram-flow.js";
+import { applyFlowChoiceTap, applyFlowReply, applyFlowTap, FLOW_DECIDE_KEY, flowButtons, flowChoiceButtons, flowChoiceHead, flowDecisionAt, flowDecisionText, flowSendKeyboardRow, flowSentContent } from "./telegram-flow.js";
 import { flowChoiceAt, flowSendTail, FLOW_CHOOSE_KEY, FLOW_SEND_KEY } from "./flow-send.js";
 import { cleanFlowMessage, fitFlowMessage } from "./flow-items.js";
 import { telegramReply } from "./reply-shape.js";
@@ -46,6 +46,7 @@ import { phoneCommand, phoneStatus, phoneTaskView, PHONE_CONSOLE_FOOTER, PHONE_H
 import { MATE_MESSAGE_MAX_CHARS } from "./mate.js";
 import { envValue } from "./names.js";
 import { applyProposalTap, processTelegramConversations, phoneLinkButton, replyContextFor, telegramConversationRepos, telegramRequestId, tooLongText, whichTaskText, } from "./telegram-mate.js";
+import { askOf, parseTelegramUpdate, pickOf, readTelegramButtonData, readTelegramUpdate, telegramButton } from "./contracts/telegram-callback.js";
 /** 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. */
@@ -99,19 +100,21 @@ export function pushedByTelegram(header, secret) {
     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 JSON object with a positive integer update_id. */
+/** 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 update;
+    let raw;
     try {
-        update = JSON.parse(body.toString("utf8"));
+        raw = JSON.parse(body.toString("utf8"));
     }
     catch {
         return { ok: false };
     }
-    const id = update?.update_id;
-    if (update === null || typeof update !== "object" || typeof id !== "number" || !Number.isSafeInteger(id) || id <= 0)
-        return { ok: false };
-    return { ok: true, kept: store.queueTelegramUpdate(botId, id, JSON.stringify(update), now) };
+    const update = readTelegramUpdate(raw);
+    if (!update.ok) {
+        console.warn(`Ignoring a pushed Telegram update: ${update.issues.map(issue => issue.line).join("; ")}`);
+        return { ok: true, kept: false };
+    }
+    return { ok: true, kept: store.queueTelegramUpdate(botId, update.value.update_id, JSON.stringify(raw), now) };
 }
 /**
  * Environment wins, the credential file beside the database otherwise.
@@ -623,7 +626,7 @@ function decideKeyboard(phoneOrigin, rows) {
     catch {
         origin = null;
     }
-    return rows.map(row => row.flatMap((one) => "token" in one ? [{ text: one.label, callback_data: one.token }]
+    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. */
@@ -631,7 +634,7 @@ 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, root) : null;
+    return principal.ok ? decideOffer(store, target, principal.who, now, root, "telegram") : 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) {
@@ -1222,13 +1225,23 @@ 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}`}`];
+        if (offer === null && flowKeys !== null && waiting !== null)
+            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);
-            const head = `${notificationIdentity(notification, title !== undefined && mentions(subject, title) ? undefined : title)}${subject}`;
-            const message = cleanFlowMessage({ head, summary: sent.summary, items: sent.items, tail: flowSendTail(sent) }, words => chatText(words, task));
+            const head = choiceHead !== null ? `${notificationIdentity(notification)}${choiceHead.join("\n")}`
+                : `${notificationIdentity(notification, title !== undefined && mentions(subject, title) ? undefined : title)}${subject}`;
+            const message = cleanFlowMessage({ head, summary: sent.summary, items: sent.items, tail: choiceHead !== null ? choiceTail : flowSendTail(sent) }, words => chatText(words, task));
             const voiced = fitFlowMessage(message, TELEGRAM_TEXT_MAX, shaped => telegramReply(shaped).text.length).map(telegramReply);
             parts = voiced.map(one => one.text);
             entities = voiced.map(one => one.entities);
@@ -1265,24 +1278,11 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
         return { ok: true, receipt: receiptFor(botId, binding.chatId, last) };
     }
     // A decision. Every safety-bearing word goes out before anything tappable
-    // exists: recap, question, and every option's consequence, 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 lines = [
-        `${notificationIdentity(notification)}Decision needed`,
-        "",
-        decision.recap,
-        "",
-        `Q: ${decision.question}`,
-        "",
-        ...decision.options.flatMap(option => [
-            `[${option.id}] ${option.label}${option.id === decision.recommendation ? "  (recommended)" : ""}${option.reversible ? "" : "  — IRREVERSIBLE"}`,
-            `    ${option.consequence}`,
-        ]),
-        ...(decision.deadline === null ? [] : ["", `deadline: ${decision.deadline}`]),
-    ];
-    const parts = split(lines.join("\n"));
+    // 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)
@@ -1311,10 +1311,7 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
         }, clock());
     }
     const keyboard = tokens.map(({ option, token }) => [
-        {
-            text: `${option.label}${option.id === decision.recommendation ? " ✓" : ""}${option.reversible ? "" : " ⚠"}`,
-            callback_data: token,
-        },
+        telegramButton(`${option.label}${option.id === decision.recommendation ? " ✓" : ""}${option.reversible ? "" : " ⚠"}`, token),
     ]);
     const last = parts[parts.length - 1];
     const sent = await sender(last, keyboard);
@@ -1433,12 +1430,22 @@ async function drainUpdates(store, botId, transport, owner, generation, cursor,
             report.problems.push(`getUpdates: ${said}`);
             return;
         }
-        const updates = answer.result ?? [];
+        const updates = Array.isArray(answer.result) ? answer.result : [];
         if (updates.length === 0)
             return;
-        for (const update of updates) {
-            await processUpdate(context, update, owner, generation);
-            offset = update.update_id + 1;
+        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))
+                    return;
+                offset = id + 1;
+                continue;
+            }
+            await processUpdate(context, update.value, owner, generation);
+            offset = update.value.update_id + 1;
         }
     }
     // The budget ran out with Telegram still holding pages: said, not hidden.
@@ -1473,15 +1480,11 @@ async function processUpdate(context, update, owner, generation) {
 async function drainInbox(context, owner, generation) {
     let applied = 0;
     for (const queued of context.store.telegramInbox(context.botId, PAGE_BUDGET * 100)) {
-        let update = null;
-        try {
-            update = JSON.parse(queued.payload);
-        }
-        catch {
-            update = null;
-        }
-        if (update !== null && update.update_id === queued.updateId)
-            await processUpdate(context, update, owner, generation);
+        const update = parseTelegramUpdate(queued.payload);
+        if (update.ok && update.value.update_id === queued.updateId)
+            await processUpdate(context, update.value, owner, generation);
+        else if (!update.ok)
+            context.report.problems.push(`a pushed update couldn't be read: ${update.issues.map(issue => issue.line).join("; ")}`);
         context.store.dropTelegramInbox(queued.updateId);
         applied++;
     }
@@ -1843,10 +1846,10 @@ function pickKeyboard(store, choices, focused) {
     for (const one of choices) {
         const ref = store.lookupRef(one.id);
         if (ref !== null)
-            rows.push([{ text: `${one.title} · ${one.label}`.slice(0, 60), callback_data: `pick:${ref.id}` }]);
+            rows.push([telegramButton(`${one.title} · ${one.label}`.slice(0, 60), `pick:${ref.id}`)]);
     }
     if (focused)
-        rows.push([{ text: "Back to the lead", callback_data: "pick:lead" }]);
+        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. */
@@ -2106,23 +2109,30 @@ 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.
-    if (token.startsWith("pick:")) {
+    const pick = pickOf(token);
+    if (pick !== null) {
         if (tapChat !== binding.chatId) {
             report.ignored++;
             return;
         }
-        if (token === "pick:lead") {
+        if (pick.ref === null) {
             store.setChatFocus("telegram", binding.id, null, clock());
             store.recordTelegramTaskMessage(binding, String(message.message_id), null, null, clock());
             ack("Back to the lead");
             editText(PHONE_BACK_TO_LEAD);
             return;
         }
-        const refId = /^pick:([1-9][0-9]{0,14})$/.exec(token)?.[1];
-        const taskId = refId === undefined ? null : store.externalIdFor(Number(refId));
+        const taskId = store.externalIdFor(pick.ref);
         const repos = context.projects === null ? null : telegramConversationRepos(store, binding.approver, context.projects);
         if (taskId === null || repos === null || !taskInCeiling(store, taskId, repos)) {
             ack("That task isn't available here now.");
@@ -2136,7 +2146,7 @@ function applyCallback(context, update, effects) {
         const current = store.taskFamilyOf(taskId, repos, false)?.current.id ?? id;
         const view = phoneTaskView(store, repos, current, clock());
         store.recordTelegramTaskMessage(binding, String(message.message_id), current, view.run, clock());
-        editText(phoneFocusText(view.text), [[{ text: "Back to the lead", callback_data: "pick:lead" }]]);
+        editText(phoneFocusText(view.text), [[telegramButton("Back to the lead", "pick:lead")]]);
         return;
     }
     // A teammate's question (v93): an option answers it; "Answer in words" asks for a reply.
@@ -2206,13 +2216,13 @@ function applyCallback(context, update, effects) {
         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 = /^ask:([1-9][0-9]{0,14}):([0-3]|x)$/.exec(token);
+    const askTap = askOf(token);
     if (askTap !== null) {
         if (tapChat !== binding.chatId || context.conversation === undefined) {
             report.ignored++;
             return;
         }
-        const turn = Number(askTap[1]);
+        const turn = askTap.turn;
         const found = store.getMateTurn(turn)?.approver === binding.approver ? store.mateAskState(turn, clock()) : { state: "expired" };
         if (found.state !== "open") {
             const line = found.state === "answered" ? "That question was already answered." : "That question expired. Send your answer as a message.";
@@ -2225,11 +2235,11 @@ function applyCallback(context, update, effects) {
             ack("Your answer is on its way.");
             return;
         }
-        if (askTap[2] === "x") {
+        if (askTap.option === "x") {
             ack("Type your answer as a message.");
             return;
         }
-        const option = ask.options[Number(askTap[2])];
+        const option = ask.options[askTap.option];
         if (option === undefined) {
             ack("That option is no longer there.");
             return;
@@ -2369,9 +2379,9 @@ function applyCallback(context, update, effects) {
             store.createTelegramAction({ token: confirm, binding: binding.id, decision: decision.id, optionId: option.id, phase: "confirm", chatId: binding.chatId, messageId: placedOn, ttlMs: CONFIRM_TTL_MS, ...(digest === undefined ? {} : { noteDigest: digest }) }, clock());
             store.createTelegramAction({ token: cancel, binding: binding.id, decision: decision.id, optionId: option.id, phase: "cancel", chatId: binding.chatId, messageId: placedOn, ttlMs: CONFIRM_TTL_MS }, clock());
             ack("irreversible — confirm it");
-            editText(`⚠ ${option.label} is IRREVERSIBLE.\n${option.consequence}\n${draft === null ? "" : `\nWith your note:\n${draft.note.split("\n").map(line => `| ${line}`).join("\n")}\n`}\nConfirm?`, [
-                [{ text: `⚠ Yes, ${option.label}`, callback_data: confirm }],
-                [{ text: "Cancel", callback_data: cancel }],
+            editText(armedDecisionText(option, draft?.note ?? null), [
+                [telegramButton(`⚠ Yes, ${option.label}`, confirm)],
+                [telegramButton("Cancel", cancel)],
             ]);
             return;
         }
@@ -2417,11 +2427,10 @@ 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");
-    editText(`Q: ${decision.question}`, fresh.map(({ option, token: choose }) => [
-        {
-            text: `${option.label}${option.id === decision.recommendation ? " ✓" : ""}${option.reversible ? "" : " ⚠"}`,
-            callback_data: choose,
-        },
+    // 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),
     ]));
 }
 function answerNow(context, decision, choice, binding, ack, editText) {
@@ -2450,10 +2459,27 @@ 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}`,
+        ...decision.options.map(option => `• ${option.label}${option.id === decision.recommendation ? " (recommended)" : ""}${option.reversible ? "" : " ⚠ can't be undone"}: ${option.consequence}`),
+        ...(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.`,
+        option.consequence,
+        ...(note === null ? [] : ["", "With your note:", ...note.split("\n").map(line => `| ${line}`)]),
+    ].join("\n");
+}
 function answeredText(store, decision) {
+    const chosen = decision.options.find(one => one.id === decision.choice)?.label ?? decision.choice ?? "?";
     return [
-        `✓ ${taskOf(store, decision)} — answered: ${decision.choice ?? "?"}`,
-        `by ${decision.answeredBy ?? "?"} via ${decision.answeredVia ?? "?"}`,
+        `✓ 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}`)]),

package/dist/text-limits.d.ts

@@ -79,6 +79,18 @@ export declare const TEXT_LIMITS: {
     readonly flowScriptInline: 1600;
     /** A research report's summary, in UTF-8 bytes. */
     readonly reportSummary: 2500;
+    /** A scout's whole report file (src/contracts/scout-report.ts), in UTF-8 bytes. */
+    readonly reportPayloadBytes: number;
+    /** A report's document (markdown), in UTF-8 bytes. */
+    readonly reportDocumentBytes: number;
+    /** A report's title, and a follow-up's or an item's title, in UTF-8 bytes. */
+    readonly reportTitleBytes: 200;
+    /** Why an item fits, in UTF-8 bytes. */
+    readonly reportWhyBytes: 1000;
+    /** A web address a report cites, in UTF-8 bytes. */
+    readonly reportUrlBytes: 2000;
+    /** A screenshot's caption and its file name, in UTF-8 bytes. */
+    readonly reportCaptionBytes: 300;
     /** What one flow step passes on to the steps after it. */
     readonly stageOutput: 12000;
     /** The planner's whole handoff file, in UTF-8 bytes. */
@@ -91,6 +103,10 @@ export declare const TEXT_LIMITS: {
     readonly planItem: 600;
     /** One path a plan expects to touch. */
     readonly planTouch: 200;
+    /** How many paths a task's scope may say it touches (a plan says at most 32 of them). A count, not a length. */
+    readonly scopeTouches: 50;
+    /** Why a task was sized as it was, as its sealed route keeps it. */
+    readonly sizeReason: 300;
     /** A planner's amendment note: why the filed contract must change. */
     readonly planAmendment: 1000;
     /** An acceptance criterion's id, statement and advisory how, in UTF-8 bytes. */
@@ -106,6 +122,131 @@ export declare const TEXT_LIMITS: {
     /** One proof line — a criterion statement, evidence ref, check command or summary, changed path, caveat, or
      * screenshot path or caption — in UTF-8 bytes. */
     readonly proofLineBytes: 300;
+    /** The task sizing classifier's reason (src/contracts/task-sizing.ts). */
+    readonly sizingReason: 160;
+    /** A review comment's or build-review finding's path, and its note or failure scenario (src/contracts/review-findings.ts). */
+    readonly reviewPath: 300;
+    readonly reviewNote: 500;
+    /** A parked decision (src/contracts/decision.ts): its recap and question, an option's id, label and consequence, and who it is for. */
+    readonly decisionRecap: 2000;
+    readonly decisionQuestion: 2000;
+    readonly decisionOptionId: 40;
+    /** A decision's recommendation: an option's id, optionally followed by ": " and why. */
+    readonly decisionRecommendation: 500;
+    readonly decisionLabel: 120;
+    readonly decisionConsequence: 500;
+    readonly decisionAssignee: 120;
+    /** A teammate's turn (src/contracts/teammate-turn.ts): the answer it picks (and each option it offers), its question, its reason and what it remembers. */
+    readonly teammateAnswer: 60;
+    readonly teammateQuestion: 600;
+    readonly teammateReason: 400;
+    readonly teammateRemember: 300;
+    /** The lead's tools and the MCP gateway (src/contracts/lead-tools.ts, gateway-tools.ts): a task's id as a tool names
+     * it, a task's title and one path it touches, and a project's path as the gateway names it (an assignment brief or
+     * project context, and the rest of the gateway). */
+    readonly taskRef: 64;
+    readonly taskTitle: 200;
+    readonly taskTouch: 200;
+    readonly projectPath: 4096;
+    readonly gatewayRepo: 800;
+    /** A project-context query, a check-log search, a memory search, a task search and a changed file's path. */
+    readonly contextQuery: 1000;
+    readonly logSearch: 120;
+    readonly memorySearch: 300;
+    readonly taskSearch: 200;
+    readonly diffPath: 300;
+    /** A hold's or cancel's reason, an answer's rationale and option, a worker's name, an agent change's reason, a
+     * provider and model name, how a task's checks were asked for, and an ISO time a recap counts from. */
+    readonly proposalReason: 200;
+    readonly answerRationale: 400;
+    readonly answerOption: 64;
+    readonly workerName: 60;
+    readonly agentWhy: 400;
+    readonly agentProvider: 20;
+    readonly agentModel: 120;
+    readonly checksWords: 80;
+    readonly recapSince: 30;
+    /** A shared action's fields as the lead proposes them (propose_action). */
+    readonly actionSample: 800;
+    readonly actionContent: 12000;
+    readonly actionTitle: 120;
+    readonly actionName: 40;
+    readonly actionCommand: 400;
+    readonly actionUrl: 500;
+    readonly actionSecret: 64;
+    readonly actionAbout: 240;
+    /** A teammate change (propose_teammate): a soul section's title, a routine's schedule, a tool, an action, a limit's
+     * field, a name, a soul file, a note, a choice and text. */
+    readonly teammateSection: 60;
+    readonly teammateSchedule: 80;
+    readonly teammateTool: 40;
+    readonly teammateAction: 64;
+    readonly teammateName: 40;
+    readonly teammateSoul: 12000;
+    readonly teammateNote: 300;
+    readonly teammateChoice: 60;
+    readonly teammateText: 2000;
+    /** A project knowledge reference id, a promise and why it is released, what the lead remembers (its text, a
+     * decision's reason and source), a person's name, and a question to the owner with its options. */
+    readonly knowledgeReference: 20;
+    readonly promise: 240;
+    readonly rememberText: 240;
+    readonly rememberWhy: 2000;
+    readonly rememberSource: 200;
+    readonly personName: 80;
+    readonly ownerQuestion: 200;
+    readonly ownerOption: 40;
+    /** A gateway filing's idempotency key. */
+    readonly idempotencyKey: 64;
+    /** The lead's catch-up bundle (src/contracts/lead-context.ts), in UTF-8 bytes, and the lines it clips: an open promise,
+     * a confirmed correction, the end of changed instructions a correction shows, and what an open proposal is about. */
+    readonly leadContextBytes: 8000;
+    readonly leadPromise: 160;
+    readonly leadCorrection: 300;
+    readonly leadCorrectionInstructions: 240;
+    readonly leadProposalAbout: 120;
+    /** Project knowledge (src/contracts/project-knowledge.ts), in UTF-8 bytes: the instructions (also the memory pass's
+     * budget for them), a reference's title, path and text, the context a run gets, the decision lines in it, and the
+     * repository excerpts added when at least the minimum is left. */
+    readonly knowledgeInstructionsBytes: 4000;
+    readonly knowledgeTitleBytes: 120;
+    readonly knowledgePathBytes: 300;
+    readonly knowledgeReferenceBytes: 12000;
+    readonly knowledgeContextBytes: 24000;
+    readonly knowledgeDecisionsBytes: 1500;
+    readonly knowledgeRepositoryBytes: 6000;
+    readonly knowledgeRepositoryMinBytes: 3000;
+    /** A project decision (src/contracts/project-memory.ts), in UTF-8 bytes: the choice, why, who decided, where it came
+     * from, and why it was retired. */
+    readonly decisionClaimBytes: 240;
+    readonly decisionWhyBytes: 2000;
+    readonly decisionByBytes: 80;
+    readonly decisionSourceBytes: 200;
+    readonly decisionRetireBytes: 500;
+    /** A skill package (src/contracts/project-skills.ts): its name, description, requirements and source in UTF-8 bytes,
+     * a file's path, SKILL.md, one file, the package and the enabled selection in bytes; a test's sample request and
+     * feedback in characters and bytes. */
+    readonly skillNameBytes: 64;
+    readonly skillDescriptionBytes: 1024;
+    readonly skillRequirementsBytes: 500;
+    readonly skillSourceBytes: 500;
+    readonly skillPath: 240;
+    readonly skillBodyBytes: number;
+    readonly skillFileBytes: number;
+    readonly skillPackageBytes: number;
+    readonly skillSelectionBytes: number;
+    readonly skillSample: 800;
+    readonly skillSampleBytes: 4000;
+    readonly skillFeedback: 500;
+    readonly skillFeedbackBytes: 2000;
+    /** The memory pass (src/contracts/memory-pass.ts): one session's trace, and in its verdict an effect, a mistake and
+     * the instruction it proposes. */
+    readonly memoryTrace: 40000;
+    readonly memoryEffect: 300;
+    readonly memoryMistake: 300;
+    readonly memoryInstruction: 240;
+    /** A Telegram button's callback_data, in UTF-8 bytes: Telegram refuses a button with more. */
+    readonly telegramCallbackDataBytes: 64;
 };
 export type TextLimitKey = keyof typeof TEXT_LIMITS;
 /** One chat message on each platform. Longer text is split across messages, never cut. Teams: the text one Adaptive Card
@@ -118,7 +259,7 @@ export declare const PLATFORM_LIMITS: {
 };
 export type Platform = keyof typeof PLATFORM_LIMITS;
 /** The line a model reads before it writes a field with a limit. */
-export declare function limitRule(what: string, limit: number, unit?: "characters" | "bytes"): string;
+export declare function limitRule(what: string, limit: number, unit?: "characters" | "bytes", shorten?: boolean): string;
 /** One field over its limit: what it is, its limit, and how long it came back. */
 export type Overrun = {
     field: string;