toolroll 0.9.96 → 0.9.98

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-status.js

@@ -8,6 +8,8 @@ import { familyCompleted } from "./result-completion.js";
 import { approvedCheckOf, approvedCheckStateOf, assignmentStatusFacts, checksFactOf, plainReasonOf, stageOfDispatch, taskStatusOf } from "./task-status.js";
 import { assignmentChecksForRun, assignmentOf } from "./assignment.js";
 import { CHAT_CONTROLS, chatControlHref, chatResultHref } from "./chat-controls.js";
+import { homeFiguresLine, homeFiguresOf } from "./home-groups.js";
+import { workIndexPage } from "./work-index.js";
 export function phoneCommand(text) {
     // Slash forms everywhere; the bare words too, because Slack and Discord
     // keep unregistered slash text for themselves. Only a whole message that
@@ -106,10 +108,13 @@ function nextStep(d) {
  * history. This snapshot is intentionally bounded and advertises that bound. */
 export function phoneStatus(store, repos, now, focused = null, root) {
     if (repos.length === 0)
-        return "No connected projects are available to this bridge. Add a project in Toolroll, then send /status again.";
+        return "No projects are connected here yet. Add a project in Toolroll, then send /status again.";
     return store.transact(() => {
         const snapshot = withDispatchDiagnoses(store, store.chatSnapshot(repos, now), now);
-        const lines = [...(focused === null ? [] : [`Talking about: ${focused} · /lead to switch back`, ""]), "Recent work", `As of ${now.toISOString().replace("T", " ").slice(0, 19)} UTC · ${repos.length} project(s)`, ""];
+        // It opens with Home's figures, from the work index totals over these projects (the Tasks lists' own counts);
+        // the groups below are dispatch diagnoses, which are not the work index's families, so they keep their headings.
+        const figures = homeFiguresOf(workIndexPage(store, now, { principal: "operator", repos, includeUnplaced: false }, { limit: 1, ...(root === undefined ? {} : { root }) }).totals);
+        const lines = [homeFiguresLine(figures), "", ...(focused === null ? [] : [`Talking about: ${focused} · /lead to switch back`, ""]), "Recent work", `As of ${now.toISOString().replace("T", " ").slice(0, 19)} UTC · ${repos.length} project(s)`, ""];
         if (snapshot.tasksSaturated)
             lines.push("Newest 60 tasks only — older work may still need attention.", "");
         if (snapshot.tasks.length === 0)
@@ -126,7 +131,7 @@ export function phoneStatus(store, repos, now, focused = null, root) {
                 lines.push(`  +${rows.length - 2} more in the console`);
             lines.push("");
         }
-        lines.push("Send /tasks to pick one, or /task <name> for its next step. Status is a snapshot, not a promise that the next attempt will succeed.");
+        lines.push("Send /tasks to pick one, or /task <name> for its next step. This is how things stand right now.");
         return lines.join("\n");
     });
 }
@@ -251,7 +256,7 @@ export function phoneTaskView(store, repos, id, now, root) {
                 lines.push(`Attempt ended: ${plain(latest.finishedAt, 40)}`);
             else if (d.condition === "running") {
                 const checkpoint = store.latestCheckpointForRun(latest.id);
-                lines.push(checkpoint === null ? "No milestone progress has been recorded for this attempt." : `Latest agent-reported milestone update: ${plain(checkpoint.createdAt, 40)} (not independent proof).`);
+                lines.push(checkpoint === null ? "No milestone progress has been recorded for this attempt." : `Latest update from the agent, not verified: ${plain(checkpoint.createdAt, 40)}.`);
             }
         }
         let link = null;

package/dist/telegram.d.ts

@@ -148,6 +148,8 @@ export type BridgeReport = {
     contention?: number;
     /** v98: Telegram answered that it pushes this bot's updates to a webhook. */
     webhookActive?: boolean;
+    /** The long poll was ended on purpose because a message was due to go out (live-wakeups.md): not a failure. */
+    deliveryWake?: boolean;
     /** v98: pushed updates applied this pass. */
     pushed?: number;
 };
@@ -242,6 +244,8 @@ export declare function followBridge(store: Store, options: {
     } | null;
     /** v98: how often to check Telegram still pushes to us (tests shorten it). */
     pushCheckMs?: number;
+    /** While a long poll is open, how often to look for a message due to go out (tests shorten it). */
+    deliveryCheckMs?: number;
 }): Promise<FollowReport>;
 /** 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.
@@ -258,3 +262,11 @@ 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;
+/**
+ * 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 declare function telegramOutboxDue(store: Store, botId: string, mark: number, now: Date): boolean;

package/dist/telegram.js

@@ -18,6 +18,7 @@
  * 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";
 import { applyTelegramQuestionReply, applyTelegramQuestionTap, openQuestionOf, telegramQuestionButtons } from "./subagent-question.js";
@@ -47,6 +48,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 +121,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.
@@ -347,6 +353,8 @@ export const MAX_POLL_SECONDS = 25;
 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;
@@ -387,6 +395,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;
@@ -512,6 +535,8 @@ export async function followBridge(store, options) {
             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);
@@ -527,7 +552,43 @@ export async function followBridge(store, options) {
                 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.
-                await drainUpdates(store, botId, transport, owner, lease.generation, lease.cursor, clock, report, inFlight === null ? pollSeconds : 1, signal, options.readProjects, options.conversation);
+                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)
+                    poll.abort();
+                else
+                    signal.addEventListener("abort", endPoll, { once: true });
+                let woke = false;
+                const checker = options.deliver !== false && seconds > 1
+                    ? setInterval(() => {
+                        if (woke || poll.signal.aborted)
+                            return;
+                        let due = false;
+                        try {
+                            due = telegramOutboxDue(store, botId, deliveredThrough, clock());
+                        }
+                        catch {
+                            due = false;
+                        }
+                        if (!due)
+                            return;
+                        woke = true;
+                        poll.abort();
+                    }, options.deliveryCheckMs ?? DELIVERY_CHECK_MS)
+                    : null;
+                checker?.unref?.();
+                try {
+                    await drainUpdates(store, botId, transport, owner, lease.generation, lease.cursor, clock, report, seconds, poll.signal, options.readProjects, options.conversation, () => woke && !signal.aborted);
+                }
+                finally {
+                    if (checker !== null)
+                        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);
@@ -567,8 +628,10 @@ export async function followBridge(store, options) {
             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;
-            if (!signal.aborted && report.sent === 0 && report.answered === 0 && (report.chatAnswered ?? 0) === 0 && took < floor) {
-                await wait(floor - took);
+            // 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));
             }
         }
     }
@@ -1463,7 +1526,9 @@ 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) {
+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) {
     const context = { store, botId, transport, clock, report, readProjects, conversation, projects: null };
     let offset = cursor + 1;
     for (let page = 0; page < PAGE_BUDGET; page++) {
@@ -1474,6 +1539,12 @@ async function drainUpdates(store, botId, transport, owner, generation, cursor,
             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
@@ -1702,7 +1773,14 @@ function applyMessage(context, update, effects) {
             return;
         // Replies to decisions retain their existing note meaning, even if the
         // note starts with a slash. New read commands are direct messages only.
-        if (message.reply_to_message === undefined && applyPhoneRead(context, update, effects))
+        // 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
@@ -1881,11 +1959,33 @@ function applyConversation(context, update, effects) {
         report.ignored++;
         return;
     }
-    store.enqueueTelegramConversation({
-        binding, updateId: update.update_id, messageId: String(message.message_id), replyTo,
-        request: telegramRequestId(botId, binding.id, update.update_id), text, context: context_, taskId, sourceRun,
-    }, clock());
+    // 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({
+            binding, updateId: update.update_id, messageId: String(message.message_id), replyTo,
+            request: telegramRequestId(botId, binding.id, update.update_id), text, context: context_, taskId, sourceRun,
+        }, clock());
+        if (typed !== null)
+            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({
+            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 +2705,35 @@ 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();
+}
+/** 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)
+        return false;
+    if (store.telegramRetryAt(botId) > now.toISOString())
+        return false;
+    return store.handle.prepare(`SELECT 1 AS hit FROM notification WHERE id > ? AND resolved_at IS NULL
+      AND (recipient IS NULL OR recipient IN (SELECT value FROM json_each(?))) LIMIT 1`).get(mark, JSON.stringify(approvers)) !== undefined;
+}