toolroll 0.9.9 → 0.9.11

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.9.11 — 2026-10-02
+
+- **The Telegram bot always answers.** Replies and notifications go out from
+  the service itself, never from inside a build. If it can't answer, it says
+  why in plain words, and a session mix-up starts a fresh conversation instead
+  of refusing.
+
+## 0.9.10 — 2026-10-02
+
+- **Chat reads like a teammate.** Short messages, outcome first, with real
+  choices: Merge or Mark complete, and Look first. Updates within two minutes
+  arrive as one message. You're never told about your own actions, release
+  checks and replaced tasks stay quiet, and a release sends one "is live" line.
+  The Telegram bot is named Toolroll.
+
 ## 0.9.9 — 2026-10-02
 
 - **Faster, lighter tests.** The unit suite runs about three times faster

package/dist/assignment.js

@@ -409,8 +409,10 @@ function acknowledgeCurrent(store, current, receiptDigest, actor, now, root, acc
         store.recordAction({ at: now.toISOString(), actor, repo: current.repo,
             taskId: current.rootId, runId: receipt.runId, action: CHECK_ACTION, outcome: receiptDigest, source: "work" });
         const ref = store.lookupRef(current.rootId);
+        // Whose act this is, even outside a command that named its person: the operator who marked it.
+        const by = currentActor() ?? (actor.startsWith("operator:") ? { account: actor.slice("operator:".length), lead: false } : null);
         if (ref !== null)
-            store.noteTaskAct(ref.id, "completed", now);
+            store.noteTaskAct(ref.id, "completed", now, undefined, by);
         store.bumpWake();
     }
     const assignment = assignmentOf(store, current.rootId, now, access, root);

package/dist/chat-channel.d.ts

@@ -12,18 +12,18 @@ export type ResolvedMate = {
     };
 } | {
     ok: false;
-    reason: "unpaired" | "unconfigured" | "direct-api" | "no-projects" | "session-mismatch" | "thread-mismatch";
+    reason: "unpaired" | "unconfigured" | "direct-api" | "no-projects" | "busy" | "no-session";
     said: string | null;
 };
 /**
  * The session and thread a paired phone speaks in: the approver's live
  * session when it is compatible (same generation, same membership
- * credential, same ceiling), else one minted under the very terms the
- * console and CLI state for membership chat (no dollar ceiling, this
- * ceiling digest) — and only when NO session is live, because minting
- * ends the previous one and an unrelated console conversation is not
- * this phone's to end. The same rule for the thread: reused when its
- * ceiling matches, never closed from here.
+ * credential, same ceiling), else a fresh one minted under the very terms
+ * the console and CLI state for membership chat (no dollar ceiling, this
+ * ceiling digest). An incompatible session or thread left open on the
+ * computer is replaced rather than refused, so a message from the phone
+ * always gets an answer — except while a turn is still running there,
+ * which is "busy": the message waits its turn instead of ending it.
  */
 export declare function resolveChannelMate(store: Store, binding: {
     approver: string;
@@ -34,6 +34,8 @@ export declare function resolveChannelMate(store: Store, binding: {
  * chat as well, so the task shows everything asked of it wherever it was
  * asked. Best effort: the phone conversation never depends on it. */
 export declare function mirrorToTaskChat(store: Store, who: VerifiedApprover, taskId: string, surface: string, message: string, reply: string, now: Date): void;
+/** The one short message a person gets when their question could not be answered. */
+export declare function couldNotAnswerText(reason: string): string;
 export declare function tooLongText(length: number): string;
 /** A reply to a message about several tasks is never guessed: it names them and says how to choose. */
 export declare function whichTaskText(titles: readonly string[]): string;

package/dist/chat-channel.js

@@ -25,12 +25,12 @@ export function channelRepos(store, approver, registry) {
 /**
  * The session and thread a paired phone speaks in: the approver's live
  * session when it is compatible (same generation, same membership
- * credential, same ceiling), else one minted under the very terms the
- * console and CLI state for membership chat (no dollar ceiling, this
- * ceiling digest) — and only when NO session is live, because minting
- * ends the previous one and an unrelated console conversation is not
- * this phone's to end. The same rule for the thread: reused when its
- * ceiling matches, never closed from here.
+ * credential, same ceiling), else a fresh one minted under the very terms
+ * the console and CLI state for membership chat (no dollar ceiling, this
+ * ceiling digest). An incompatible session or thread left open on the
+ * computer is replaced rather than refused, so a message from the phone
+ * always gets an answer — except while a turn is still running there,
+ * which is "busy": the message waits its turn instead of ending it.
  */
 export function resolveChannelMate(store, binding, repos, now) {
     const config = store.getChatConfig();
@@ -60,18 +60,17 @@ export function resolveChannelMate(store, binding, repos, now) {
         return { ok: false, reason: "unpaired", said: null };
     const who = verified.who;
     const credentialKey = subscriptionCredentialKey(config.provider);
-    const mismatch = "Your open chat session on the computer covers different projects or another provider. Finish or end it there, then message here again. Nothing was changed.";
     let session = store.activeMateSession(who.name);
-    if (session !== null &&
+    const liveThread = store.liveMateThreadFor(who.name);
+    const sessionMismatch = session !== null &&
         (session.approverGeneration !== who.generation ||
             session.credentialKey !== credentialKey ||
-            session.ceilingDigest !== who.ceilingDigest)) {
-        return { ok: false, reason: "session-mismatch", said: mismatch };
-    }
-    const liveThread = store.liveMateThreadFor(who.name);
-    if (liveThread !== null && liveThread.ceilingDigest !== who.ceilingDigest)
-        return { ok: false, reason: "thread-mismatch", said: mismatch };
-    if (session === null) {
+            session.ceilingDigest !== who.ceilingDigest);
+    const threadMismatch = liveThread !== null && liveThread.ceilingDigest !== who.ceilingDigest;
+    // Replacing either would end a turn still running on the computer.
+    if ((sessionMismatch || threadMismatch) && store.liveMateTurnFor(who.name) !== null)
+        return { ok: false, reason: "busy", said: null };
+    if (session === null || sessionMismatch) {
         const termsDigest = createHash("sha256")
             .update(`0\n${who.ceilingDigest}`)
             .digest("hex");
@@ -85,9 +84,12 @@ export function resolveChannelMate(store, binding, repos, now) {
         }, now);
         session = store.getMateSession(id);
         if (session === null)
-            return { ok: false, reason: "session-mismatch", said: mismatch };
+            return { ok: false, reason: "no-session", said: couldNotAnswerText("a new chat session couldn't be started") };
     }
-    const thread = liveThread ?? store.openMateThread(who.name, who.ceilingDigest, now).thread;
+    // openMateThread closes a thread kept under another ceiling.
+    const thread = threadMismatch || liveThread === null
+        ? store.openMateThread(who.name, who.ceilingDigest, now).thread
+        : liveThread;
     return {
         ok: true,
         who,
@@ -113,6 +115,10 @@ export function mirrorToTaskChat(store, who, taskId, surface, message, reply, no
         // The task chat is a copy; the phone's own conversation already has it.
     }
 }
+/** The one short message a person gets when their question could not be answered. */
+export function couldNotAnswerText(reason) {
+    return `I couldn't answer that just now: ${reason}. Ask again, or open the console.`;
+}
 export function tooLongText(length) {
     return `That message is ${length.toLocaleString("en-US")} characters; chat takes up to ${MATE_MESSAGE_MAX_CHARS.toLocaleString("en-US")}. Nothing was sent to the assistant. Send it in shorter parts, or say which part matters most.`;
 }

package/dist/chat-delivery-state.d.ts

@@ -76,6 +76,11 @@ export type ChatContent = {
         label: string;
         path: string;
     };
+    /** More link buttons after `link`: [Look first] beside [Merge] or [Mark complete]. */
+    also?: Array<{
+        label: string;
+        path: string;
+    }>;
     /** A flow decision's buttons ride this part (v88): minted when it is planned. */
     flow?: {
         card: number;

package/dist/chat-delivery.js

@@ -9,7 +9,8 @@ import { answerChatFlowPrompt, applyChatFlowTap, flowDecisionParts } from "./cha
 import { connectChannel, FLOW_WORDS, takeChannelMessage, watchedChannel } from "./chat-inbox.js";
 import { triggerConfigOf } from "./flow-triggers.js";
 import { telegramProgressCard } from "./telegram-progress.js";
-import { enqueueEveningDigests, isTaskFact, needsPerson, quietCardView, readyPingView } from "./chat-quiet.js";
+import { enqueueEveningDigests, finishedView, isTaskFact, joinsBatch, needsPerson, quietCardView } from "./chat-quiet.js";
+import { BATCH_MS, chatText, chatTitle } from "./chat-voice.js";
 import { phoneText, PHONE_HELP, phoneCommand, phoneStatus, phoneTaskView, phoneTaskChoices, phoneTaskListText, resolvePhoneTask, phoneFocusText, PHONE_NO_MATCH, PHONE_BACK_TO_LEAD } from "./telegram-status.js";
 import { applyRoomInbound, conversationRow, roomCardApprover, roomCommand, roomGrantAllowed, roomMessagesAfter, roomMessageText, teamDomain } from "./chat-rooms.js";
 import { isTelegramProgressNotification, proposalTaskOf } from "./store.js";
@@ -201,6 +202,10 @@ export async function processChatEvent(options) {
                 return true;
             }
             const resolved = resolveChannelMate(store, { approver: binding.approver, approverGeneration: binding.generation }, repos, now);
+            if (!resolved.ok && resolved.reason === "busy") {
+                state.defer(event.id, "Assistant is answering another message", new Date(now.getTime() + 5000));
+                return true;
+            }
             if (!resolved.ok) {
                 state.plan(event.id, [
                     {
@@ -582,7 +587,7 @@ function planQuietCard(options, binding, notification, now) {
     if (notification.taskRef === null || notification.taskId === null)
         return;
     const card = store.chatCardFor(`${state.channel}:${binding.id}`, notification.taskRef, store.getTask(notification.taskId)?.createdAt ?? notification.createdAt, now);
-    const view = quietCardView(store, card.tasks, now, options.evidenceRoot);
+    const view = quietCardView(store, card.tasks, now, options.evidenceRoot, binding.approver);
     if (view === null)
         return;
     const content = { text: view.text, link: view.link, ...(card.tasks.length === 1 ? { task: notification.taskId } : {}) };
@@ -602,6 +607,37 @@ function planQuietCard(options, binding, notification, now) {
     if (part !== undefined)
         store.setChatCardMessage(card.id, String(part.id), shown);
 }
+/** Any update for this person joins their open batch (two minutes from its first), and the batch's one message
+ * is planned once, then repainted in place as more updates land. `notification`: an update that is not a finished
+ * result (null for one that is). False when nothing in the batch reads as a line, so the update goes out on its own. */
+function planFinished(options, binding, taskRef, run, now, notification = null) {
+    const { state, store, identity } = options;
+    const batch = store.chatBatchFor(`${state.channel}:${binding.id}`, taskRef, run, now, BATCH_MS, notification);
+    const view = finishedView(store, batch, now, options.evidenceRoot, binding.approver);
+    if (view === null)
+        return false;
+    // A single update keeps its task and run, so a reply to it names that work.
+    const single = batch.items.length === 1 ? batch.items[0] : null;
+    const task = single === null ? null : store.refById(single.taskRef)?.externalId ?? null;
+    const content = { text: view.text, link: view.link, ...(view.also === undefined ? {} : { also: view.also }),
+        ...(task === null ? {} : { task }), ...(single?.run == null ? {} : { run: single.run }) };
+    const shown = chatHash(JSON.stringify(content));
+    if (batch.message !== null) {
+        if (batch.digest === shown)
+            return true;
+        state.prepare("UPDATE chat_part SET payload=?,state='pending',created=?,next_at=NULL WHERE id=? AND state!='dropped'").run(JSON.stringify(content), now.toISOString(), Number(batch.message));
+        store.setChatBatchMessage(batch.id, batch.message, shown);
+        return true;
+    }
+    const id = chatHash(`${state.channel}:batch:${binding.id}:${batch.id}`);
+    state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
+        ts: "", thread: "", payload: "{}", created: now.toISOString() });
+    state.plan(id, [content], now);
+    const part = state.prepare("SELECT id FROM chat_part WHERE event=?").get(id);
+    if (part !== undefined)
+        store.setChatBatchMessage(batch.id, String(part.id), shown);
+    return true;
+}
 /** One progress card per exact result; separate urgent facts retain their own review link. */
 export async function planChatNotifications(options) {
     const state = options.state, { store, identity } = options, bindings = state.bindings(identity.installation).filter(one => state.live(one));
@@ -645,15 +681,19 @@ export async function planChatNotifications(options) {
                         if (!needsPerson(notification))
                             return;
                         if (notification.kind === "run-finished" && run) {
-                            const ping = readyPingView(store, store.getRun(run.id), notification.taskId, notification.project, now, options.evidenceRoot);
-                            state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
-                                ts: "", thread: "", payload: "{}", created: now.toISOString() });
-                            state.plan(id, [{ text: ping.text, task: notification.taskId, run: run.id, link: ping.link }], now);
+                            // Finished work goes out only as the batch line; one left out on purpose (a release check, a replaced
+                            // task, the reader's own completion) stays quiet rather than falling through to another message.
+                            planFinished(options, binding, notification.taskRef, run.id, now);
                             return;
                         }
+                        // Every other update for this person within two minutes joins the same one message.
+                        else if (notification.kind !== "run-finished" && joinsBatch(notification)) {
+                            if (planFinished(options, binding, notification.taskRef, run?.id ?? null, now, notification.id))
+                                return;
+                        }
                     }
                     if (!quiet && run && notification.taskId && notification.project !== null && isTelegramProgressNotification(notification)) {
-                        const card = telegramProgressCard(store, store.getRun(run.id), notification.taskId, notification.project, now, options.evidenceRoot);
+                        const card = telegramProgressCard(store, store.getRun(run.id), notification.taskId, notification.project, now, options.evidenceRoot, binding.approver);
                         const content = {
                             text: card.text,
                             task: notification.taskId,
@@ -726,7 +766,8 @@ export async function planChatNotifications(options) {
                         });
                         state.plan(id, [
                             {
-                                text: phoneText(`${notification.subject}\n\n${notification.body}`, 2500),
+                                // Never the task's id or a "— revision" suffix (chat-voice.ts).
+                                text: chatText(phoneText(notification.body === "" ? notification.subject : `${notification.subject}\n\n${notification.body}`, 2500), notification.taskId === null ? [] : [{ id: notification.taskId, title: chatTitle(store, notification.taskId) }]),
                                 ...(notification.taskId ? { task: notification.taskId } : {}),
                                 ...(run ? { run: run.id } : {}),
                                 ...(notification.link

package/dist/chat-quiet.d.ts

@@ -1,10 +1,12 @@
 import { type ProgressEntity } from "./telegram-progress.js";
 import { type PhoneTaskLink } from "./telegram-status.js";
-import { type Notification, type Run, type Store } from "./store.js";
+import { type ChatBatch, type Notification, type Store } from "./store.js";
+/** `also`: more buttons after `link`, such as [Look first] beside [Merge]. */
 export type QuietView = {
     text: string;
     entities: ProgressEntity[];
     link: PhoneTaskLink;
+    also?: PhoneTaskLink[];
 };
 export declare function needsPerson(row: Pick<Notification, "dedupeKey" | "kind" | "pushClass" | "recipient">): boolean;
 /** A fact about one placed task: in quiet mode it lands on that task's card. */
@@ -14,9 +16,13 @@ export declare function isTaskFact(row: Pick<Notification, "taskRef" | "taskId"
     project: string;
 };
 /** The card's words now: one task's progress card, or one line per task when several were filed together. */
-export declare function quietCardView(store: Store, taskRefs: readonly number[], now: Date, root?: string): QuietView | null;
-/** The one ping for a Ready result: its state and title, what to do next, and a link to that exact result. */
-export declare function readyPingView(store: Store, run: Run, taskId: string, project: string, now: Date, root?: string): QuietView;
+export declare function quietCardView(store: Store, taskRefs: readonly number[], now: Date, root?: string, viewer?: string): QuietView | null;
+/** Whether this update for a person joins their two-minute batch: anything about one task that needs them,
+ * except a fact that must stand alone. */
+export declare function joinsBatch(row: Pick<Notification, "dedupeKey" | "kind" | "pushClass" | "recipient" | "taskRef">): boolean;
+/** One person's update message: one task says what happened with its next step; several updates within two
+ * minutes become "4 tasks finished: …" (or "3 updates: …") with one Open button. Null when none can be read. */
+export declare function finishedView(store: Store, batch: Pick<ChatBatch, "items">, now: Date, root?: string, viewer?: string): QuietView | null;
 /** This computer's local day and time, which is what a person means by "the evening". */
 export declare function localDay(now: Date): string;
 export declare function localTime(now: Date): string;

package/dist/chat-quiet.js

@@ -5,9 +5,10 @@
  * Delivery receipts, claims and retries stay with each transport; the
  * console's activity keeps every fact whatever a chat showed. */
 import { assignmentOf } from "./assignment.js";
-import { chatControlHref } from "./chat-controls.js";
+import { chatControlHref, chatResultHref } from "./chat-controls.js";
 import { telegramProgressCard } from "./telegram-progress.js";
-import { assignmentStatusFacts, headlineEmoji, replacedWords, taskStatusOf } from "./task-status.js";
+import { assignmentStatusFacts, headlineEmoji, taskStatusOf } from "./task-status.js";
+import { asksToFinish, batchLine, chatText, chatTitle, factLinkLabel, mentions, READY_ACTIONS } from "./chat-voice.js";
 import { phoneText, projectLabel } from "./telegram-status.js";
 import { isLifecycleNotification } from "./store.js";
 /** What always makes a new message, even in quiet mode: a question or approval waiting, a failure or other
@@ -49,25 +50,27 @@ const BEFORE_RUN = {
     "task-requeued": before("Queued"),
     "task-cancelled": before("Stopped"),
 };
-function taskLine(store, taskRef, now, root) {
+function taskLine(store, taskRef, now, root, viewer) {
     const ref = store.refById(taskRef);
     if (ref === null || ref.repo === null)
         return null;
     const task = store.getTask(ref.externalId);
-    const title = phoneText(task?.title ?? ref.externalId, 88);
-    // Replaced, never "Cancelled": the card names its successor and links to it.
+    // A short human title: never "— revision" or an id (chat-voice.ts).
+    const title = chatTitle(store, ref.externalId);
+    // Replaced, never "Cancelled": the card says a newer task took over and links to it, without either id.
     const successor = task?.state === "cancelled" ? store.replacementOf(ref.externalId) : null;
     if (successor !== null) {
-        const heading = `${headlineEmoji("Stopped")} ${replacedWords(successor)}`;
-        const text = [title, heading, "", `${projectLabel(ref.repo)} · ${ref.externalId}`].join("\n");
-        return { title, icon: headlineEmoji("Stopped"), status: replacedWords(successor), project: ref.repo, view: {
+        const words = "Replaced by a newer task";
+        const heading = `${headlineEmoji("Stopped")} ${words}`;
+        const text = [title, heading, "", projectLabel(ref.repo)].join("\n");
+        return { title, icon: headlineEmoji("Stopped"), status: words, project: ref.repo, view: {
                 text, entities: [{ type: "bold", offset: 0, length: title.length }, { type: "bold", offset: title.length + 1, length: heading.length }],
-                link: { label: `Open ${phoneText(successor, 40)}`, path: chatControlHref("task", successor) },
+                link: { label: "Open the new task", path: chatControlHref("task", successor) },
             } };
     }
     const run = cardRun(store, taskRef);
     if (run !== null) {
-        const view = telegramProgressCard(store, run, ref.externalId, ref.repo, now, root);
+        const view = telegramProgressCard(store, run, ref.externalId, ref.repo, now, root, viewer);
         const heading = view.entities[1] === undefined ? "" : view.text.slice(view.entities[1].offset, view.entities[1].offset + view.entities[1].length);
         const split = heading.indexOf(" ");
         return { title, icon: heading.slice(0, split), status: heading.slice(split + 1), project: ref.repo, view };
@@ -75,15 +78,15 @@ function taskLine(store, taskRef, now, root) {
     const fact = store.latestTaskFact(taskRef);
     const words = task?.state === "cancelled" ? BEFORE_RUN["task-cancelled"] : BEFORE_RUN[fact?.kind ?? ""] ?? BEFORE_RUN["task-filed"];
     const heading = `${words.icon} ${words.status}`;
-    const text = [title, heading, "", `${projectLabel(ref.repo)} · ${ref.externalId}`].join("\n");
+    const text = [title, heading, "", projectLabel(ref.repo)].join("\n");
     return { title, icon: words.icon, status: words.status, project: ref.repo, view: {
             text, entities: [{ type: "bold", offset: 0, length: title.length }, { type: "bold", offset: title.length + 1, length: heading.length }],
             link: { label: "Open task", path: chatControlHref("task", ref.externalId) },
         } };
 }
 /** The card's words now: one task's progress card, or one line per task when several were filed together. */
-export function quietCardView(store, taskRefs, now, root) {
-    const lines = taskRefs.map(ref => taskLine(store, ref, now, root)).filter((one) => one !== null);
+export function quietCardView(store, taskRefs, now, root, viewer) {
+    const lines = taskRefs.map(ref => taskLine(store, ref, now, root, viewer)).filter((one) => one !== null);
     if (lines.length === 0)
         return null;
     if (lines.length === 1)
@@ -93,14 +96,76 @@ export function quietCardView(store, taskRefs, now, root) {
     const text = [heading, ...lines.map(one => `${one.icon} ${phoneText(one.title, 60)} · ${one.status}`), "", projects.join(", ")].join("\n");
     return { text, entities: [{ type: "bold", offset: 0, length: heading.length }], link: { label: "Open tasks", path: "/tasks" } };
 }
-/** The one ping for a Ready result: its state and title, what to do next, and a link to that exact result. */
-export function readyPingView(store, run, taskId, project, now, root) {
-    const card = telegramProgressCard(store, run, taskId, project, now, root);
-    const [title = "", shown = ""] = card.entities.map(one => card.text.slice(one.offset, one.offset + one.length));
-    const heading = shown;
-    const next = card.next;
-    const first = `${heading} · ${title}`;
-    return { text: next === "" ? first : `${first}\n${next}`, entities: [{ type: "bold", offset: 0, length: heading.length }], link: card.link };
+/** Facts that carry their own controls or must stand alone (a security alert, a decision, a flow card, a
+ * screenshot, an acceptance packet) are never folded into a batch. */
+const OWN_MESSAGE_KINDS = new Set(["security-release", "secret-detected", "flow-decision", "flow-card", "acceptance-ready", "acceptance-evidence"]);
+/** Whether this update for a person joins their two-minute batch: anything about one task that needs them,
+ * except a fact that must stand alone. */
+export function joinsBatch(row) {
+    return row.taskRef !== null && row.recipient === null && needsPerson(row) && !OWN_MESSAGE_KINDS.has(row.kind) && !/^decision:\d+$/.test(row.dedupeKey);
+}
+/** A few words for an update in a list, and how it counts: "has a plan to review", "failed". */
+function updatePhrase(row) {
+    if (row.kind === "plan-ready")
+        return { phrase: "has a plan to review", headline: "Needs you" };
+    if (row.kind === "report-ready")
+        return { phrase: "has a report to read", headline: "Update" };
+    if (row.kind === "stale-approval" || row.kind === "approval-withdrawn")
+        return { phrase: "needs a fresh approval", headline: "Needs you" };
+    if (row.pushClass === "merge" || row.kind === "pull-request-ready")
+        return { phrase: "is ready to merge", headline: "Update" };
+    if (/fail|exhausted|stalled|fenced/.test(row.kind))
+        return { phrase: "failed", headline: "Failed" };
+    return { phrase: "needs you", headline: "Needs you" };
+}
+/** One task's line in a batch: a finished result in a person's words with its real next step, or another
+ * update in its own words with its own link. */
+function lineOf(store, item, now, root, viewer) {
+    const ref = store.refById(item.taskRef);
+    if (ref === null || ref.repo === null)
+        return null;
+    const summary = chatTitle(store, ref.externalId);
+    const row = item.notification === null ? null : store.notificationById(item.notification);
+    if (row !== null && row.kind !== "run-finished") {
+        // Never the task's id or a "— revision" suffix; the title once, in front unless the words already name it.
+        const words = chatText(phoneText(row.body === "" ? row.subject : `${row.subject}\n\n${row.body}`, 2500), [{ id: ref.externalId, title: summary }]);
+        const { phrase, headline } = updatePhrase(row);
+        return { also: [], link: row.link === null ? { label: "Open task", path: chatControlHref("task", ref.externalId) } : { label: factLinkLabel(row.link), path: row.link },
+            fact: { summary, headline, checks: null, report: false, completedBy: null, update: { words: mentions(words, summary) ? words : `${summary} · ${words}`, phrase } } };
+    }
+    const run = item.run === null ? null : store.getRun(item.run);
+    if (run === null)
+        return null;
+    const card = telegramProgressCard(store, run, ref.externalId, ref.repo, now, root, viewer);
+    const checks = card.facts.checks ?? null;
+    const pullRequest = card.facts.pullRequest?.state === "open";
+    const fact = {
+        summary,
+        headline: card.status.headline,
+        checks: checks === null ? null : checks.level === "off" && checks.status !== "passed" ? "off"
+            : checks.status === "passed" || checks.status === "failed" || checks.status === "not-run" ? checks.status : null,
+        report: card.facts.report === true,
+        completedBy: card.facts.completedBy ?? null,
+        pullRequest,
+        // The lead speaks as "I" for what it did: the work it filed or approved, or the completion it recorded.
+        lead: card.status.headline === "Complete" ? card.completedByLead : store.leadWorkOf(item.taskRef) !== null,
+    };
+    // A result ready for a person offers its real next step, then a look first.
+    if (asksToFinish(fact))
+        return { fact, also: [{ label: READY_ACTIONS.look, path: chatResultHref(ref.externalId, run.id, "changes") }],
+            link: pullRequest ? { label: READY_ACTIONS.merge, path: `/t/${encodeURIComponent(ref.externalId)}#merge` } : { label: READY_ACTIONS.complete, path: chatResultHref(ref.externalId, run.id) } };
+    return { fact, link: card.link, also: [] };
+}
+/** One person's update message: one task says what happened with its next step; several updates within two
+ * minutes become "4 tasks finished: …" (or "3 updates: …") with one Open button. Null when none can be read. */
+export function finishedView(store, batch, now, root, viewer) {
+    const lines = batch.items.map(one => lineOf(store, one, now, root, viewer)).filter((one) => one !== null);
+    if (lines.length === 0)
+        return null;
+    const text = batchLine(lines.map(one => one.fact));
+    if (lines.length > 1)
+        return { text, entities: [], link: { label: "Open", path: "/tasks" } };
+    return { text, entities: [], link: lines[0].link, ...(lines[0].also.length === 0 ? {} : { also: lines[0].also }) };
 }
 // ---- the evening digest ----------------------------------------------------------
 const FAILURE = /fail|exhausted|fenced/;
@@ -118,7 +183,7 @@ export function eveningDigestText(store, account, now, root) {
     const since = new Date(now.getTime() - 86_400_000).toISOString();
     const recent = new Date(now.getTime() - 14 * 86_400_000).toISOString();
     const visible = (row) => row.project !== null && store.accountCanAccess(account, row.project);
-    const title = (taskId) => phoneText(store.getTask(taskId)?.title ?? taskId, 80);
+    const title = (taskId) => chatTitle(store, taskId);
     const finished = new Map(), failed = new Map(), waits = new Map();
     const facts = store.taskFactsSince(recent).filter(visible);
     for (const row of facts) {

package/dist/chat-voice.d.ts

@@ -0,0 +1,68 @@
+/** How chat sounds: a teammate talking. One or two short sentences, outcome
+ * first, plain words, one action at most. Every chat (Telegram, Slack,
+ * Discord, Teams) takes its titles and its finished-work lines from here, so a
+ * task id, a "— revision" suffix or a person's own act never reaches a chat.
+ * The console keeps every exact name and fact. */
+import type { TelegramTransport } from "./telegram.js";
+import type { Store } from "./store.js";
+/** The bot's display name in every chat app. */
+export declare const BOT_NAME = "Toolroll";
+/** Updates for one person landing within this window become one message, edited in place as it grows. */
+export declare const BATCH_MS: number;
+export declare const SHORT_TITLE_MAX = 60;
+/** A short human summary of a task's title, at most 60 characters: no "— revision", and no task ids. Only the
+ * task's own id and tokens `isTaskId` names as real tasks are dropped; `node-20` and `utf-8` stay. */
+export declare function shortTitle(title: string | null | undefined, taskId?: string | null, isTaskId?: (token: string) => boolean): string;
+/** A task's title as every chat says it: short, with its own id and any other real task's id dropped. */
+export declare function chatTitle(store: Pick<Store, "getTask">, taskId: string): string;
+/** A title inside a sentence or list: "faster tests", but "API keys" and "iOS" keep their capitals. */
+export declare function inSentence(summary: string): string;
+/** The facts one line of a chat update is made of, read from the shared task status. */
+export type FinishedFact = {
+    summary: string;
+    headline: string;
+    checks: "passed" | "failed" | "not-run" | "off" | null;
+    report: boolean;
+    completedBy: string | null;
+    /** An open pull request carries this result: the ask is "Merge it?" rather than "Mark it complete?". */
+    pullRequest?: boolean;
+    /** The lead did this (built it, or marked it complete), so the lead says "I". */
+    lead?: boolean;
+    /** Not a finished result but another update about the task: its own words when it stands alone, and a few
+     * words for a list ("has a plan to review"). */
+    update?: {
+        words: string;
+        phrase: string;
+    } | null;
+};
+/** The two buttons under a result ready for a person: the real next step, then a look first. */
+export declare const READY_ACTIONS: {
+    readonly merge: "Merge";
+    readonly complete: "Mark complete";
+    readonly look: "Look first";
+};
+/** Whether this line asks for the result's next step, so it carries [Merge] or [Mark complete] and [Look first]. */
+export declare function asksToFinish(fact: FinishedFact): boolean;
+/** One update, said plainly: what happened, then what happens next. The lead says "I" for what it did. */
+export declare function finishedLine(fact: FinishedFact): string;
+/** Several updates in one message: "4 tasks finished: faster tests, cleanup, …" (or "3 updates: …" when not all of
+ * them are finished work), then what broke and what happens next. */
+export declare function batchLine(facts: readonly FinishedFact[]): string;
+/**
+ * Name the Telegram bot Toolroll. On pairing it always becomes Toolroll; on upgrade only a bot still called
+ * StandingOrders is renamed, so a name a person chose later is kept. Best effort: a refused or failed call
+ * leaves the old name and never blocks pairing or delivery. Returns whether a rename was sent and accepted.
+ */
+export declare function nameTelegramBot(transport: TelegramTransport, when: "pairing" | "upgrade"): Promise<boolean>;
+/** The last word on any pushed chat text: a task's own id (bare or in brackets), a "— revision" suffix and a
+ * "Replaced by <id>" never reach a chat, whatever words the fact was recorded with. A bare id reads as the
+ * task's short title when one is given, else "this task". */
+export declare function chatText(text: string, tasks?: readonly (string | null | undefined | {
+    id: string;
+    title?: string;
+})[]): string;
+/** The one button a plain fact may carry: its label names where its machine-minted console path goes; nothing in
+ * it comes from the fact's text. */
+export declare function factLinkLabel(path: string): string;
+/** Whether the words already name this title as a whole phrase (so it need not be said twice). */
+export declare function mentions(text: string, title: string): boolean;