toolroll 0.9.96 → 0.9.97

package/dist/telegram-lead.js

@@ -31,7 +31,7 @@ import { ceilingDigestOf, verifyApproverStanding } from "./principal.js";
 import { LEAD_ASK_OTHER } from "./store.js";
 import { phoneText } from "./telegram-status.js";
 import { shapeReplyParts, telegramReply } from "./reply-shape.js";
-import { WARM_EMOJI, warmTurn } from "./chat-warmth.js";
+import { createTelegramLiveDraft, forgetWaitingDraft, telegramAck, telegramWaitingDraft } from "./telegram-live.js";
 import { TeamLeads } from "./team-leads.js";
 import { chatResultHref } from "./chat-controls.js";
 import { resultImageFileName, safeResultImageCaption, verifyResultImage } from "./chat-evidence.js";
@@ -373,8 +373,26 @@ const ANSWERED_SENDING = "answered:sending";
  */
 async function runTelegramConversation(row, args) {
     const { store, botId, transport, owner, clock, readProjects, options, report, only } = args;
-    const finish = (result) => store.finishTelegramConversation(row.id, owner, result, clock());
+    /** The row's live binding as it arrived (pairing alone: a reaction or a waiting draft carries no project data). */
+    const stillPaired = () => {
+        const live = store.liveTelegramBindingById(row.binding);
+        return live !== null && live.botId === botId && live.approverGeneration === row.approverGeneration && store.accountOf(live.approver)?.role === "approver";
+    };
+    const finish = (result) => {
+        const done = store.finishTelegramConversation(row.id, owner, result, clock());
+        // Answered (every part sent) or failed (its notice tried): the 👀 comes off, after what was delivered. Never awaited.
+        if (done && (result.state === "done" || result.state === "failed")) {
+            forgetWaitingDraft(botId, row.id);
+            void telegramAck({ store, botId, transport, clock, chatId: row.chatId, messageId: row.messageId, on: false, paired: stillPaired, ...(options.liveTiming?.ackGapMs === undefined ? {} : { gapMs: options.liveTiming.ackGapMs }) });
+        }
+        return done;
+    };
     const held = () => store.renewTelegramConversation(row.id, owner, CONVERSATION_CLAIM_MS, clock());
+    /** The claim, read (a draft never renews it: only the turn's own heartbeat and durable steps do). */
+    const claimed = () => {
+        const now = store.getTelegramConversation(row.id);
+        return now !== null && now.claimOwner === owner && now.claimExpiresAt !== null && now.claimExpiresAt > clock().toISOString();
+    };
     const ageMs = clock().getTime() - Date.parse(row.createdAt);
     const requeue = async (outcome) => {
         // A turn already admitted for it waits for that turn's own outcome (bounded by the turn's deadline); waiting for the
@@ -390,6 +408,10 @@ async function runTelegramConversation(row, args) {
         // Behind the person's own earlier messages: said once, then it waits quietly.
         if (outcome === "backlog" && row.outcome !== "backlog")
             await notify("Queued behind your earlier messages. It goes to the lead once they're answered.");
+        // Waiting for the lead: a draft that says so, refreshed while it waits (never over this chat's running turn).
+        if (outcome === "busy" || outcome === "backlog") {
+            await telegramWaitingDraft({ store, botId, transport, clock, chatId: row.chatId, binding: row.binding, draftId: row.id, allowed: () => stillPaired() && claimed(), ...(options.liveTiming === undefined ? {} : { timing: options.liveTiming }) });
+        }
         finish({ state: "queued", outcome, nextAttemptAt: new Date(clock().getTime() + CONVERSATION_RETRY_MS).toISOString() });
     };
     // 1. The exact binding the message arrived under must still be the live one.
@@ -677,7 +699,7 @@ async function runTelegramConversation(row, args) {
             return;
         }
         if (turn.state !== "answered") {
-            await notify(leadFailureText(turn.failureReason, store.leadTurnCostUnconfirmed(turn.id)));
+            await notify(leadFailureText(turn.failureReason, store.leadTurnCostUnconfirmed(turn.id), turn.failureDetail ?? null));
             finish({ state: "failed", outcome: `replayed:${turn.failureReason ?? "failed"}` });
             report.refused++;
             return;
@@ -777,10 +799,41 @@ async function runTelegramConversation(row, args) {
     // crash gets the original turn back, never a second dispatch.
     const heartbeat = setInterval(() => { held(); }, 30_000);
     heartbeat.unref?.();
-    // Once the turn reaches a tool step: a 👍 on the owner's message, and "typing…" while the lead works.
-    const warm = warmTurn({
-        react: () => transport("setMessageReaction", { chat_id: chatId, message_id: Number(row.messageId), reaction: [{ type: "emoji", emoji: WARM_EMOJI }] }),
-        typing: () => transport("sendChatAction", { chat_id: chatId, action: "typing" }),
+    // The live reply: one draft in this private chat with the status line and the reply as it is written
+    // (telegram-live.ts). A draft with words goes out only after the full fence: this exact binding, approver and the
+    // ceiling the turn opened under (the registry read at most every 5 s), the turn still running under the generation it
+    // first ran with, and this row's claim, re-checked after the read.
+    let draftGeneration = null;
+    let draftRegistry = null;
+    const turnStillRunning = (turnId) => {
+        const turn = store.getLeadTurn(turnId);
+        if (turn === null || turn.state !== "running" || turn.session !== session.id || turn.thread !== thread.id)
+            return false;
+        draftGeneration ??= turn.generation;
+        return turn.generation === draftGeneration;
+    };
+    const draftStanding = async (turnId) => {
+        if (!turnStillRunning(turnId) || !claimed())
+            return false;
+        if (draftRegistry === null || clock().getTime() - draftRegistry.at > 5_000) {
+            try {
+                draftRegistry = { at: clock().getTime(), repos: await readProjects() };
+            }
+            catch {
+                draftRegistry = null;
+                return false;
+            }
+        }
+        const read = draftRegistry.repos;
+        const problem = await telegramChannelProblem(store, { botId, bindingId: binding.id, approverGeneration: binding.approverGeneration, repos: who.repos }, async () => read);
+        return problem === null && turnStillRunning(turnId) && claimed();
+    };
+    const live = createTelegramLiveDraft({
+        store, botId, transport, clock, chatId, binding: binding.id, draftId: row.id,
+        // Shaped as the final reply is: for this message, with the phone's own trusted origin.
+        shape: { asked: row.text, appOrigin: options.phoneOrigin?.() ?? null },
+        standing: draftStanding, paired: () => pairingProblem() === null,
+        ...(options.liveTiming === undefined ? {} : { timing: options.liveTiming }),
     });
     const replyImage = row.replyTo === null ? undefined : store.telegramMessageBindings(binding, row.replyTo).find(one => one.taskId === row.taskId && one.run === row.sourceRun && one.image !== undefined)?.image;
     let outcome;
@@ -790,12 +843,13 @@ async function runTelegramConversation(row, args) {
             ...(row.context === null ? {} : { context: row.context }),
             ...(replyImage === undefined ? {} : { replyImage }),
             ...(options.subscriptionRunner === undefined ? {} : { subscriptionRunner: options.subscriptionRunner }),
-            clock, evidenceRoot: options.evidenceRoot, revalidate, mediaDelivery: "documents", channel: "telegram", onProgress: warm.onProgress,
+            clock, evidenceRoot: options.evidenceRoot, revalidate, mediaDelivery: "documents", channel: "telegram", onProgress: live.onProgress,
         });
     }
     finally {
         clearInterval(heartbeat);
-        warm.stop();
+        // Closed, and its draft in flight settled, before anything durable: no draft can land after the answer or a notice.
+        await live.close();
     }
     const receipt = store.leadRequestReceipt(session.id, row.request);
     if (receipt !== null)

package/dist/telegram-live.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The paired phone's live reply (docs/plans/responsive-chat.md §3.1): a 👀 on the owner's message as soon as it is
+ * saved, and while the lead works one Bot API message draft (`sendMessageDraft`, private chats only) that shows the
+ * status line and the reply as it is written.
+ *
+ * Nothing here is durable or authoritative. A draft is Telegram's "temporary 30-second preview": it disappears when the
+ * bot sends a message or when it is not refreshed, so a draft that is never replaced is harmless. The answer itself is
+ * still the planned, receipted `sendMessage` parts (telegram-lead.ts), sent only after this turn's sender has closed.
+ * Drafts carry words only: no keyboard, no card, no token. Every draft that carries more than Telegram's own empty
+ * "Thinking…" placeholder is sent only after the caller's full standing check (live pairing, approver, the project
+ * ceiling the turn opened under, the turn still running under its generation, the row's claim).
+ *
+ * Rate: Telegram's own retry_after is shared with every other send (`telegramRetryAt` / `deferTelegram`). While it
+ * holds, an ack waits and a draft is dropped (the answer and failure notices go first, acks next, drafts last); a
+ * draft that is asked to pause widens this turn's spacing.
+ */
+import type { LeadProgress } from "./lead-progress.js";
+import { type LiveView } from "./live-reply.js";
+import { type ShapeOptions, type TelegramEntity } from "./reply-shape.js";
+import type { Store } from "./store.js";
+import type { TelegramTransport } from "./telegram.js";
+/** The acknowledgement on the owner's message: "seen, working on it". Removed once the answer or the failure notice is
+ * delivered; never replaced by a "done" mark (an answer isn't finished work). */
+export declare const ACK_EMOJI = "\uD83D\uDC40";
+/** At most one reaction change per chat this often; a burst waits its turn, in order. */
+export declare const ACK_GAP_MS = 1000;
+/** Drafts start this far apart and widen (doubling, up to the cap) whenever Telegram asks for a pause. */
+export declare const DRAFT_SPACING_MS = 1200;
+/** Telegram keeps a draft about 30 seconds: one that has not changed is sent again after this long. */
+export declare const DRAFT_KEEPALIVE_MS = 25000;
+/** Telegram's message limit, counted after entities (UTF-16 units, as JS strings are). */
+export declare const TELEGRAM_TEXT_MAX = 4096;
+/** Test seams for the timings above (production uses the defaults). */
+export type TelegramLiveTiming = {
+    ackGapMs?: number;
+    draftSpacingMs?: number;
+    keepAliveMs?: number;
+};
+export type DraftEntity = TelegramEntity | {
+    type: "italic";
+    offset: number;
+    length: number;
+};
+export type DraftPayload = {
+    text: string;
+    entities: DraftEntity[];
+};
+/** The body of a writing draft within `budget` characters once rendered: cut at a safe place in the shaped text first
+ * (never inside code, a link, a bold anchor or an emoji), rendered, measured, and cut smaller if it still doesn't fit.
+ * A body that can't fit (a single link longer than the budget) shows nothing. */
+export declare function draftBody(shaped: string, budget: number): DraftPayload;
+/**
+ * One live view as a draft: the status line in italics, then (once text exists) the partial reply as text plus
+ * entities, never Markdown. Plain "Thinking…" is Telegram's own empty-text placeholder. Closed views send nothing.
+ */
+export declare function telegramDraftOf(view: LiveView): DraftPayload | null;
+/**
+ * Put 👀 on the owner's message (`on`) or take it off. Best effort and never awaited by the caller's durable work: a
+ * missing pairing, a failure or a long pause skips it silently. `paired` is re-checked at the moment of sending; a
+ * reaction carries no project data, so the pairing alone fences it. Resolves once this change was tried.
+ */
+export declare function telegramAck(args: {
+    store: Store;
+    botId: string;
+    transport: TelegramTransport;
+    clock: () => Date;
+    chatId: string;
+    messageId: string;
+    on: boolean;
+    paired: () => boolean;
+    gapMs?: number;
+}): Promise<void>;
+export type TelegramLiveDraft = {
+    /** The turn's progress listener (runLeadTurn's `onProgress`). */
+    onProgress: (event: LeadProgress) => void;
+    /** Stop: nothing more is sent, and the draft in flight has settled when this resolves. Durable delivery comes after. */
+    close: () => Promise<void>;
+    /** The turn the drafts follow, once it started. */
+    readonly turn: number | null;
+};
+/**
+ * One running turn's draft. `standing` is the caller's full proof for a draft that carries words (it may await; the
+ * close is re-checked after it); `paired` is enough for Telegram's empty "Thinking…". A draft Telegram refuses outright
+ * (not a pause, not a lost answer) turns this turn's drafts off; previews are best effort.
+ */
+export declare function createTelegramLiveDraft(args: {
+    store: Store;
+    botId: string;
+    transport: TelegramTransport;
+    clock: () => Date;
+    chatId: string;
+    binding: number;
+    draftId: number;
+    shape: ShapeOptions;
+    standing: (turn: number) => Promise<boolean>;
+    paired: () => boolean;
+    timing?: TelegramLiveTiming;
+}): TelegramLiveDraft;
+/**
+ * A message waiting for the lead (busy, or behind the owner's earlier messages): "Waiting for your earlier messages…"
+ * as a draft, refreshed only after the keep-alive interval, and never while this chat's running turn has its own
+ * draft. Carries no project data: the pairing and the claim fence it.
+ */
+export declare function telegramWaitingDraft(args: {
+    store: Store;
+    botId: string;
+    transport: TelegramTransport;
+    clock: () => Date;
+    chatId: string;
+    binding: number;
+    draftId: number;
+    allowed: () => boolean;
+    timing?: TelegramLiveTiming;
+}): Promise<void>;
+/** The message is answered or failed: its waiting draft is forgotten. */
+export declare function forgetWaitingDraft(botId: string, draftId: number): void;

package/dist/telegram-live.js

@@ -0,0 +1,224 @@
+import { createLiveReply, createLiveSender, LIVE_STATUS } from "./live-reply.js";
+import { shapedWindow, telegramReply } from "./reply-shape.js";
+/** The acknowledgement on the owner's message: "seen, working on it". Removed once the answer or the failure notice is
+ * delivered; never replaced by a "done" mark (an answer isn't finished work). */
+export const ACK_EMOJI = "👀";
+/** At most one reaction change per chat this often; a burst waits its turn, in order. */
+export const ACK_GAP_MS = 1_000;
+/** A reaction change that meets Telegram's pause waits it out when it is this short; a longer pause skips it. */
+const ACK_MAX_WAIT_MS = 30_000;
+/** Drafts start this far apart and widen (doubling, up to the cap) whenever Telegram asks for a pause. */
+export const DRAFT_SPACING_MS = 1_200;
+const DRAFT_MAX_SPACING_MS = 10_000;
+/** Telegram keeps a draft about 30 seconds: one that has not changed is sent again after this long. */
+export const DRAFT_KEEPALIVE_MS = 25_000;
+/** Telegram's message limit, counted after entities (UTF-16 units, as JS strings are). */
+export const TELEGRAM_TEXT_MAX = 4_096;
+/** The body of a writing draft within `budget` characters once rendered: cut at a safe place in the shaped text first
+ * (never inside code, a link, a bold anchor or an emoji), rendered, measured, and cut smaller if it still doesn't fit.
+ * A body that can't fit (a single link longer than the budget) shows nothing. */
+export function draftBody(shaped, budget) {
+    if (budget <= 0)
+        return { text: "", entities: [] };
+    let size = budget;
+    for (let attempt = 0; attempt < 8 && size >= 1; attempt += 1) {
+        const window = shapedWindow(shaped, size);
+        const cut = window.length < shaped.length;
+        const rendered = telegramReply(cut ? window.trimEnd() : window);
+        const text = cut ? `${rendered.text} …` : rendered.text;
+        if (text.length <= budget)
+            return { text, entities: rendered.entities };
+        size = Math.min(size - 1, Math.floor(size * budget / text.length) - 2);
+    }
+    return { text: "", entities: [] };
+}
+/**
+ * One live view as a draft: the status line in italics, then (once text exists) the partial reply as text plus
+ * entities, never Markdown. Plain "Thinking…" is Telegram's own empty-text placeholder. Closed views send nothing.
+ */
+export function telegramDraftOf(view) {
+    if (view.phase === "closed")
+        return null;
+    if (view.phase === "queued")
+        return { text: LIVE_STATUS.queued, entities: [{ type: "italic", offset: 0, length: LIVE_STATUS.queued.length }] };
+    if (view.phase === "working") {
+        if (view.status === LIVE_STATUS.thinking)
+            return { text: "", entities: [] };
+        return { text: view.status, entities: [{ type: "italic", offset: 0, length: view.status.length }] };
+    }
+    const head = view.status;
+    const gap = "\n\n";
+    const body = draftBody(view.text, TELEGRAM_TEXT_MAX - head.length - gap.length);
+    if (body.text === "")
+        return { text: head, entities: [{ type: "italic", offset: 0, length: head.length }] };
+    const shift = head.length + gap.length;
+    return {
+        text: `${head}${gap}${body.text}`,
+        entities: [{ type: "italic", offset: 0, length: head.length }, ...body.entities.map(one => ({ ...one, offset: one.offset + shift }))],
+    };
+}
+/** One draft on the wire, under the shared pause. A retry_after is recorded for every sender of this bot. */
+async function sendDraft(store, botId, transport, clock, chatId, draftId, payload) {
+    if (store.telegramRetryAt(botId) > clock().toISOString())
+        return "paused";
+    let answer;
+    try {
+        answer = await transport("sendMessageDraft", { chat_id: Number(chatId), draft_id: draftId, text: payload.text, ...(payload.entities.length === 0 ? {} : { entities: payload.entities }) });
+    }
+    catch {
+        return "lost";
+    }
+    if (answer.ok)
+        return "sent";
+    const retry = answer.parameters?.retry_after;
+    if (typeof retry === "number" && Number.isFinite(retry) && retry > 0) {
+        store.deferTelegram(botId, new Date(clock().getTime() + Math.ceil(retry) * 1_000).toISOString());
+        return "paused";
+    }
+    return answer.uncertain === true ? "lost" : "refused";
+}
+// ---- the 👀 acknowledgement ----------------------------------------------------------
+/** One lane per chat: reaction changes go out in order (an ack never lands after its own removal), spaced. */
+const ackLanes = new Map();
+const pause = (ms) => new Promise(resolve => { const timer = setTimeout(resolve, ms); timer.unref?.(); });
+/**
+ * Put 👀 on the owner's message (`on`) or take it off. Best effort and never awaited by the caller's durable work: a
+ * missing pairing, a failure or a long pause skips it silently. `paired` is re-checked at the moment of sending; a
+ * reaction carries no project data, so the pairing alone fences it. Resolves once this change was tried.
+ */
+export function telegramAck(args) {
+    const key = `${args.botId}:${args.chatId}`;
+    const lane = ackLanes.get(key) ?? { tail: Promise.resolve(), lastAt: Number.NEGATIVE_INFINITY };
+    ackLanes.set(key, lane);
+    const gap = args.gapMs ?? ACK_GAP_MS;
+    // Never throws: a store closed meanwhile (a stop) or anything else skips the change.
+    const run = () => change().catch(() => undefined);
+    const change = async () => {
+        const spaced = lane.lastAt + gap - Date.now();
+        if (spaced > 0)
+            await pause(spaced);
+        const held = Date.parse(args.store.telegramRetryAt(args.botId)) - args.clock().getTime();
+        if (Number.isFinite(held) && held > 0) {
+            if (held > ACK_MAX_WAIT_MS)
+                return;
+            await pause(held);
+        }
+        if (!args.paired())
+            return;
+        lane.lastAt = Date.now();
+        try {
+            const answer = await args.transport("setMessageReaction", {
+                chat_id: Number(args.chatId), message_id: Number(args.messageId), reaction: args.on ? [{ type: "emoji", emoji: ACK_EMOJI }] : [],
+            });
+            const retry = answer.ok ? undefined : answer.parameters?.retry_after;
+            if (typeof retry === "number" && Number.isFinite(retry) && retry > 0)
+                args.store.deferTelegram(args.botId, new Date(args.clock().getTime() + Math.ceil(retry) * 1_000).toISOString());
+        }
+        catch { /* skipped silently */ }
+    };
+    const done = lane.tail.then(run, run);
+    lane.tail = done;
+    // A finished lane is forgotten; the next change starts a fresh one (spacing restarts from now).
+    void done.then(() => { if (ackLanes.get(key) === lane && lane.tail === done && Date.now() - lane.lastAt >= gap)
+        ackLanes.delete(key); });
+    return done;
+}
+// ---- the draft --------------------------------------------------------------------------
+/** Chats (bot:binding) whose turn has a live draft in this process: a waiting message's draft never covers it. */
+const liveChats = new Set();
+/** When each waiting message last had its "Waiting for your earlier messages…" draft (bot:row). */
+const waitingDrafts = new Map();
+/**
+ * One running turn's draft. `standing` is the caller's full proof for a draft that carries words (it may await; the
+ * close is re-checked after it); `paired` is enough for Telegram's empty "Thinking…". A draft Telegram refuses outright
+ * (not a pause, not a lost answer) turns this turn's drafts off; previews are best effort.
+ */
+export function createTelegramLiveDraft(args) {
+    const reply = createLiveReply(args.shape);
+    const keepAlive = args.timing?.keepAliveMs ?? DRAFT_KEEPALIVE_MS;
+    const base = args.timing?.draftSpacingMs ?? DRAFT_SPACING_MS;
+    const chat = `${args.botId}:${args.binding}`;
+    let spacing = base;
+    let lastSentAt = Date.now();
+    let off = false;
+    liveChats.add(chat);
+    /** What the draft shows now: a preview closed as a possible password or key keeps only the status line. */
+    const current = () => {
+        const view = reply.view();
+        if (view.phase !== "closed")
+            return view;
+        return view.why === "blocked" ? { phase: "working", status: LIVE_STATUS.held } : null;
+    };
+    const sender = createLiveSender({
+        spacingMs: () => spacing,
+        send: async (view) => {
+            if (off)
+                return;
+            const payload = telegramDraftOf(view);
+            const turn = reply.turn;
+            if (payload === null || turn === null)
+                return;
+            const allowed = payload.text === "" ? args.paired() : await args.standing(turn);
+            if (!allowed || sender.closed)
+                return;
+            const outcome = await sendDraft(args.store, args.botId, args.transport, args.clock, args.chatId, args.draftId, payload);
+            if (outcome === "sent")
+                lastSentAt = Date.now();
+            else if (outcome === "paused")
+                spacing = Math.min(DRAFT_MAX_SPACING_MS, spacing * 2);
+            else if (outcome === "refused")
+                off = true;
+        },
+    });
+    const timer = setInterval(() => {
+        if (sender.closed || Date.now() - lastSentAt < keepAlive)
+            return;
+        const view = current();
+        if (view !== null)
+            sender.offer(view);
+    }, Math.max(50, Math.min(keepAlive, 5_000)));
+    timer.unref?.();
+    return {
+        get turn() { return reply.turn; },
+        onProgress: event => {
+            // The first event names the turn: Telegram's "Thinking…" shows at once, even before the view changes.
+            const first = reply.turn === null;
+            if (!reply.push(event) && !first)
+                return;
+            const view = current();
+            if (view !== null)
+                sender.offer(view);
+        },
+        close: async () => {
+            clearInterval(timer);
+            liveChats.delete(chat);
+            await sender.close();
+        },
+    };
+}
+/**
+ * A message waiting for the lead (busy, or behind the owner's earlier messages): "Waiting for your earlier messages…"
+ * as a draft, refreshed only after the keep-alive interval, and never while this chat's running turn has its own
+ * draft. Carries no project data: the pairing and the claim fence it.
+ */
+export async function telegramWaitingDraft(args) {
+    const key = `${args.botId}:${args.draftId}`;
+    if (liveChats.has(`${args.botId}:${args.binding}`))
+        return;
+    const last = waitingDrafts.get(key);
+    if (last !== undefined && Date.now() - last < (args.timing?.keepAliveMs ?? DRAFT_KEEPALIVE_MS))
+        return;
+    if (!args.allowed())
+        return;
+    const payload = telegramDraftOf({ phase: "queued" });
+    if (await sendDraft(args.store, args.botId, args.transport, args.clock, args.chatId, args.draftId, payload) !== "sent")
+        return;
+    waitingDrafts.set(key, Date.now());
+    // Bounded: the oldest entries go first.
+    while (waitingDrafts.size > 500)
+        waitingDrafts.delete(waitingDrafts.keys().next().value);
+}
+/** The message is answered or failed: its waiting draft is forgotten. */
+export function forgetWaitingDraft(botId, draftId) {
+    waitingDrafts.delete(`${botId}:${draftId}`);
+}

package/dist/telegram.d.ts

@@ -258,3 +258,5 @@ export declare function digestText(rows: readonly Notification[], since: string
  */
 /** At most this many of a chat's messages wait for the lead at once (the personal lead queue's bound). */
 export declare const TELEGRAM_MAX_WAITING = 10;
+/** 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 declare function wakeTelegramBridge(botId: string): void;

package/dist/telegram.js

@@ -47,6 +47,7 @@ import { phoneCommand, phoneStatus, phoneTaskView, PHONE_CONSOLE_FOOTER, PHONE_H
 import { LEAD_MESSAGE_MAX_CHARS } from "./lead.js";
 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. */
@@ -119,7 +120,11 @@ export function keepPushedUpdate(store, botId, body, now) {
         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) };
+    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.
@@ -387,6 +392,21 @@ 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();
+        let wake = () => { };
+        const woken = new Promise(resolve => { wake = resolve; });
+        const wakers = bridgeWakers.get(botId) ?? new Set();
+        bridgeWakers.set(botId, wakers);
+        wakers.add(wake);
+        return Promise.race([wait(ms), woken]).finally(() => {
+            wakers.delete(wake);
+            if (wakers.size === 0 && bridgeWakers.get(botId) === wakers)
+                bridgeWakers.delete(botId);
+        });
+    };
     const total = { cycles: 0, sent: 0, answered: 0, paired: 0, ignored: 0, problems: [] };
     let commandsListed = false;
     let failures = 0;
@@ -568,7 +588,8 @@ export async function followBridge(store, options) {
             // 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;
             if (!signal.aborted && report.sent === 0 && report.answered === 0 && (report.chatAnswered ?? 0) === 0 && took < floor) {
-                await wait(floor - took);
+                // While Telegram pushes, a push kept by this process's hook ends the idle at once.
+                await (pushing() ? idle(floor - took) : wait(floor - took));
             }
         }
     }
@@ -1886,6 +1907,19 @@ function applyConversation(context, update, effects) {
         request: telegramRequestId(botId, binding.id, update.update_id), text, context: context_, taskId, sourceRun,
     }, 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({
+            store, botId, transport, clock, chatId: binding.chatId, messageId: String(message.message_id), on: true, ...(gapMs === undefined ? {} : { gapMs }),
+            paired: () => {
+                const live = store.liveTelegramBindingById(binding.id);
+                return live !== null && live.approverGeneration === binding.approverGeneration && store.accountOf(live.approver)?.role === "approver";
+            },
+        });
+    });
 }
 /** 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
@@ -2605,3 +2639,17 @@ function expiredDraftGuard(store, binding, decisionId, now) {
     store.setNoteDraftState(Number(expired["id"]), "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) {
+        bridgeWokenEarly.add(botId);
+        return;
+    }
+    for (const wake of wakers)
+        wake();
+}

package/dist/toolroll-update.js

@@ -43,6 +43,7 @@ import { V151_ADDED_COLUMNS } from "./storage.js";
 import { orphanKey, updateSafeSchema, V117_RENAMED_COLUMNS, V117_RENAMED_TABLES, V118_MERGED_TABLES, V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS, V134_ADDED_COLUMNS, V135_ADDED_COLUMNS, V138_ADDED_COLUMNS, V143_ADDED_COLUMNS, V147_ADDED_COLUMNS, V148_ADDED_COLUMNS, V150_ADDED_COLUMNS } from "./store.js";
 import { V152_ADDED_COLUMNS } from "./code-map-store.js";
 import { V153_ADDED_COLUMNS } from "./plain-schema.js";
+import { V158_ADDED_COLUMNS } from "./lead-latency-schema.js";
 import { isNewer, REGISTRY } from "./releases.js";
 import { markNeverIndex } from "./never-index.js";
 import { readRuntimeUpdateJournal, RUNTIME_PHASES, RUNTIME_UPDATE_STEPS, stagedStartedAt, updaterStartingOf } from "./contracts/update-journal.js";
@@ -429,7 +430,9 @@ const HISTORY_RULES = {
     // v154 adds a table only (check_stamp): no saved row changes, so no rule is needed for it.
     // v155 adds tables only (fleet-schema.ts): no saved row changes, so no rule is needed for it.
     // v156 adds tables only (fallback chains): likewise.
-    ...Object.fromEntries(Object.entries(addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS, V134_ADDED_COLUMNS, V135_ADDED_COLUMNS, V138_ADDED_COLUMNS, V143_ADDED_COLUMNS, V147_ADDED_COLUMNS, V148_ADDED_COLUMNS, V150_ADDED_COLUMNS, V151_ADDED_COLUMNS, V152_ADDED_COLUMNS, V153_ADDED_COLUMNS))
+    // v158 (after v157's chat-app tables): a saved lead step reads no tool names and no failure detail, and a saved reply no route and no failure detail
+    // (NULL); the quick-answer switch is a new table.
+    ...Object.fromEntries(Object.entries(addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS, V134_ADDED_COLUMNS, V135_ADDED_COLUMNS, V138_ADDED_COLUMNS, V143_ADDED_COLUMNS, V147_ADDED_COLUMNS, V148_ADDED_COLUMNS, V150_ADDED_COLUMNS, V151_ADDED_COLUMNS, V152_ADDED_COLUMNS, V153_ADDED_COLUMNS, V158_ADDED_COLUMNS))
         .map(([table, rule]) => [table, { ...EARLIER_RULES[table], ...rule }])),
 };
 /** The tables a migration may remove whole (v115's removed features). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.96",
+  "version": "0.9.97",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"