toolroll 0.5.0

package/dist/telegram-progress.d.ts

@@ -0,0 +1,14 @@
+import { type PhoneTaskLink } from "./telegram-status.js";
+import type { Run, Store } from "./store.js";
+/** Offsets are UTF-16, as required by Telegram. Only our two headings are bold;
+ * user text stays literal, including angle brackets and Markdown characters. */
+export type ProgressEntity = {
+    type: "bold";
+    offset: number;
+    length: number;
+};
+export declare function telegramProgressCard(store: Store, run: Run, taskId: string, project: string, now?: Date, root?: string): {
+    text: string;
+    entities: ProgressEntity[];
+    link: PhoneTaskLink;
+};

package/dist/telegram-progress.js

@@ -0,0 +1,129 @@
+/** A compact projection of saved work, never a percentage or an ETA. The
+ * words come from the same assignment record the console and the CLI show:
+ * a finished build is Ready once its saved result can be inspected, and
+ * Complete once the lead or a person has marked that exact result. No model
+ * reviewer is waited for or announced. */
+import { manualReviewOnly } from "./proof.js";
+import { assignmentOf } from "./assignment.js";
+import { chatResultHref, chatControlHref } from "./chat-controls.js";
+import { phoneText, projectLabel } from "./telegram-status.js";
+/** The saved assignment for this exact result, or null when the run is not
+ * the family's current result (an older attempt keeps its own plain words). */
+function assignmentFor(store, run, taskId, project, now, root) {
+    try {
+        const assignment = assignmentOf(store, taskId, now, { principal: "operator", repos: [project] }, root);
+        return assignment !== null && assignment.receipt?.runId === run.id ? assignment : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function telegramProgressCard(store, run, taskId, project, now = new Date(), root) {
+    const proof = store.proofVerdictFor(run.id);
+    const rows = proof?.matrix ?? [];
+    const direct = rows.length > 0 && rows.every(row => row.assessment !== undefined);
+    const passed = rows.filter(row => row.state === "pass").length;
+    const human = manualReviewOnly(proof);
+    const accepted = store.proofAcceptance(run.id) !== null;
+    const built = run.finishedAt !== null && (run.outcome === "built" || run.outcome === "no-change");
+    const assignment = built ? assignmentFor(store, run, taskId, project, now, root) : null;
+    const checksFailed = assignment?.receipt?.checks.status === "failed";
+    let status = "Working";
+    let icon = "⏳";
+    let next = "";
+    let build = built ? "✓ Build saved" : "● Build in progress";
+    let checks = rows.length ? `${passed === rows.length ? "✓" : "○"} Checks · ${passed}/${rows.length} requirements` : "○ Checks pending";
+    if (direct)
+        checks = proof?.machineVerdict === "verified" ? "✓ Checks passed" : proof?.machineVerdict === "attested" ? "○ Checks not configured" : "! Checks need attention";
+    let label = built ? "Open result" : "Open task";
+    if (run.outcome === null && run.phase !== null && run.phase !== "agent-running") {
+        status = "Checking the result";
+        build = "✓ Draft prepared";
+        checks = "● Checks in progress";
+    }
+    if (built) {
+        status = run.committed === false ? "Finished without a commit" : "Result saved";
+        if (proof === null)
+            checks = "○ Checks not recorded";
+        const recorded = assignment?.receipt?.checks;
+        if (recorded !== undefined && recorded.status !== "unavailable") {
+            checks = recorded.status === "passed" ? "✓ Checks passed"
+                : recorded.status === "failed" ? `! Checks failed${recorded.exitCode === null ? "" : ` (exit ${recorded.exitCode})`}`
+                    : "○ Checks did not run";
+        }
+        if (assignment?.state === "ready-to-check") {
+            status = "Ready";
+            icon = checksFailed ? "⚠️" : "✅";
+            next = checksFailed ? "Next: inspect the failed check, then mark it complete or request changes." : "Next: open the result, then mark it complete or request changes.";
+        }
+        else if (assignment?.state === "complete") {
+            status = "Complete";
+            icon = "✅";
+            next = phoneText(assignment.detail, 200);
+        }
+        else if (assignment?.state === "needs-decision") {
+            status = "Needs your decision";
+            icon = "💬";
+            next = phoneText(assignment.detail, 200);
+        }
+        else if (assignment?.state === "cancelled") {
+            status = "Cancelled";
+            icon = "⏹";
+        }
+        else if (assignment !== null) {
+            next = phoneText(assignment.detail, 200);
+        }
+        else if (run.committed !== false) {
+            next = "Open the task for its current status.";
+        }
+    }
+    else if (run.outcome !== null) {
+        status = run.outcome === "parked" ? "Decision needed" : run.outcome === "interrupted" || run.reason === "interrupted" ? "Stopped" : "Build needs attention";
+        icon = run.outcome === "parked" ? "💬" : "⏸";
+        build = "! Build unfinished";
+        next = "Next: inspect the blocker.";
+        label = "Open task";
+    }
+    const stop = store.stopOf(run.id);
+    if (run.outcome === null && stop !== null && stop.resumedAt === null) {
+        status = stop.settledAt === null ? "Stopping" : "Stopped";
+        icon = "⏸";
+        build = stop.settledAt === null ? "● Build stopping" : "! Build stopped";
+        next = stop.settledAt === null ? "Waiting for the running process to stop." : "Next: inspect the saved work, then resume.";
+    }
+    const holds = store.activeHolds(run.taskRef, now);
+    const operatorHold = holds.find(hold => hold.ownerKind === "operator");
+    const accessBlocked = run.reason === "retryable-infra" && /^could not re-read (?:the branch|HEAD) in /i.test(run.handoff ?? "");
+    if (accessBlocked) {
+        status = "Worker needs project access";
+        icon = "⏸";
+        next = "Next: restore the worker’s folder access, then resume.";
+        label = "Open task";
+    }
+    if (operatorHold) {
+        icon = "⏸";
+        if (!accessBlocked) {
+            status = run.outcome === null ? "Working · Next attempt paused" : "Paused";
+            next = phoneText(operatorHold.reason, 150);
+        }
+        label = "Open task";
+    }
+    else if (accessBlocked && holds.some(hold => hold.ownerKind === "backoff")) {
+        next = "The worker will retry after a short pause. Check its folder access.";
+    }
+    const checkProgress = store.checkProgress(run.id);
+    if (checkProgress !== null)
+        checks = checkProgress.line;
+    const publication = store.publicationForRun(run.id);
+    const delivery = publication?.remoteState === "MERGED" ? "Merged · Installation not confirmed" : publication?.remoteState === "CLOSED" ? "Pull request closed without merging" : publication?.state === "opened" ? "Pull request open · Not merged" : publication?.state === "pushed" ? "Branch pushed · Pull request pending" : publication?.state === "intended" ? "Publication queued" : publication?.state === "failed" ? "Publication failed · Local result preserved" : built ? "Saved locally · Not published" : null;
+    const acceptance = accepted ? (human ? "Accepted by a person · Recorded checks unchanged" : "Accepted with an exception · Recorded checks unchanged") : null;
+    const title = phoneText(store.getTask(taskId)?.title ?? taskId, 88);
+    const heading = `${icon} ${status}`;
+    const text = [title, heading, "", build, checks,
+        ...(next ? ["", next] : []),
+        ...(acceptance === null ? [] : [acceptance]),
+        ...(delivery === null ? [] : ["", delivery]), "", `${projectLabel(project)} · #${run.id}`].join("\n");
+    return { text, entities: [{ type: "bold", offset: 0, length: title.length }, { type: "bold", offset: title.length + 1, length: heading.length }],
+        link: { label, path: operatorHold || accessBlocked || (!built && run.outcome !== null)
+                ? chatControlHref("recovery", taskId) : built ? chatResultHref(taskId, run.id, checksFailed ? "checks" : "summary") : chatControlHref("task", taskId) } };
+}

package/dist/telegram-settings.d.ts

@@ -0,0 +1,9 @@
+/** The person's own Telegram pairing, from the console: one private chat per
+ * teammate with the installation's bot (v72). The bot token itself stays on
+ * the settings page; this card only mints or revokes the signed-in person's
+ * pairing, never anyone else's. */
+import type { Store } from "./store.js";
+export declare function telegramSettingsHtml(store: Store, botId: string | null, who: string, csrf: string, options?: {
+    code?: string;
+    problem?: string;
+}): string;

package/dist/telegram-settings.js

@@ -0,0 +1,36 @@
+const escape = (text) => text
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+export function telegramSettingsHtml(store, botId, who, csrf, options = {}) {
+    const hidden = `<input type="hidden" name="csrf" value="${escape(csrf)}">`;
+    const password = '<label>Your Toolroll password<input style="min-height:44px" type="password" name="password" autocomplete="current-password" required></label>';
+    const post = (action, content) => `<form method="post" action="/settings/telegram/${action}" class="card">${hidden}${content}</form>`;
+    let content = "";
+    if (botId === null) {
+        content = '<p>No Telegram bot is connected yet. An installation approver saves the bot token on the <a href="/settings">settings page</a> first.</p>';
+    }
+    else {
+        const bindings = store.liveTelegramBindings(botId);
+        const mine = bindings.filter(binding => binding.approver === who);
+        const others = bindings.length - mine.length;
+        content = `<p><strong>${mine.length > 0 ? "Your phone is paired." : "Your phone is not paired."}</strong> ${others === 0 ? "No teammates are paired yet." : `${others} teammate${others === 1 ? " is" : "s are"} paired.`}</p>`;
+        if (options.code !== undefined) {
+            content +=
+                "<h2>Pair your phone</h2><p>Send this to the bot in a private Telegram chat within 10 minutes:</p>" +
+                    `<pre class="pairing-code">/pair ${escape(options.code)}</pre>` +
+                    '<p class="meta">The code works once. That chat then answers as you, so treat it like your sign-in.</p>';
+        }
+        else if (mine.length === 0) {
+            content += post("pair", password + '<button type="submit">Pair my phone</button>');
+        }
+        else {
+            content += post("unpair", password + '<p class="meta">This phone will lose access. Its existing Telegram buttons will stop working.</p><button type="submit" class="danger">Unpair my phone</button>');
+        }
+    }
+    if (options.problem !== undefined)
+        content = `<p role="status">${escape(options.problem)}</p>` + content;
+    return `<h1>Telegram</h1>${content}<p class="meta">Each teammate pairs their own private chat. To connect a group, a conversation manager sends <code>/team</code> there and chooses a conversation. Everyone in the group can read its replies.</p>`;
+}

package/dist/telegram-status.d.ts

@@ -0,0 +1,75 @@
+import { publicChatText } from './chat-display.js';
+import type { Notification, Store } from "./store.js";
+export type PhoneCommand = {
+    kind: "status";
+} | {
+    kind: "help";
+} | {
+    kind: "task";
+    id: string;
+} | {
+    kind: "tasks";
+} | {
+    kind: "lead";
+};
+export declare function phoneCommand(text: string): PhoneCommand | null;
+export declare const PHONE_HELP: string;
+/** The same display scrub for every phone-bound string a person or a model authored. */
+export declare const phoneText: typeof publicChatText;
+export declare function projectLabel(repo: string): string;
+/** repos is the transport's explicit enrollment ceiling, never opened-project
+ * history. This snapshot is intentionally bounded and advertises that bound. */
+export declare function phoneStatus(store: Store, repos: readonly string[], now: Date, focused?: string | null): string;
+/** One task a person can pick to talk about from a chat app. */
+export type PhoneTaskChoice = {
+    id: string;
+    title: string;
+    label: string;
+    group: string;
+};
+/** The tasks a paired chat can pick from: what needs the person first,
+ * then work in progress, waiting work and recent results; one entry per
+ * task (its revisions share it), optionally narrowed by words in the id or
+ * title. Bounded, within the chat's own project ceiling. */
+export declare function phoneTaskChoices(store: Store, repos: readonly string[], now: Date, query?: string | null, limit?: number): PhoneTaskChoice[];
+/** `id` keys the chat's choice (the task's first version, where its chat
+ * lives); `view` is what to show: the exact version named, else the current one. */
+export type PhoneTaskPick = {
+    kind: "one";
+    id: string;
+    view: string;
+    title: string;
+} | {
+    kind: "many";
+    choices: PhoneTaskChoice[];
+} | {
+    kind: "none";
+};
+/** `/task <what>`: an exact task id, a number from the /tasks list, or
+ * words from a title — one match is chosen, several are offered. */
+export declare function resolvePhoneTask(store: Store, repos: readonly string[], now: Date, query: string): PhoneTaskPick;
+/** The picker as text, for chat apps without buttons. */
+export declare function phoneTaskListText(choices: readonly PhoneTaskChoice[], focused: string | null): string;
+/** Said under a task's status when a chat app chooses it. */
+export declare const PHONE_FOCUS_LINE = "Talking about this task now: ask anything or say what to change. Reply to this message later to come back to it; /lead goes back to the lead.";
+/** A chosen task's status, then the line that says the chat now talks about it. */
+export declare function phoneFocusText(view: string): string;
+export declare const PHONE_NO_MATCH = "No such task in your connected projects. Send /tasks to pick one.";
+export declare const PHONE_BACK_TO_LEAD = "Back to the lead. Your messages here are about all your work again.";
+/** A fixed console destination for one task, named beside its label; the origin joins it only on the wire. */
+export type PhoneTaskLink = {
+    label: string;
+    path: string;
+};
+/** Where the rest lives when no button can say so: the closing line of an unlinked `/task`. */
+export declare const PHONE_CONSOLE_FOOTER = "Read-only status. Saved files and full actions are in the console.";
+export declare function phoneTask(store: Store, repos: readonly string[], id: string, now: Date): string;
+/** One task's status for a chat app: the words, its one console link, and
+ * the saved result it shows (a reply to it is about that result). */
+export declare function phoneTaskView(store: Store, repos: readonly string[], id: string, now: Date): {
+    text: string;
+    link: PhoneTaskLink | null;
+    run: number | null;
+};
+/** Concise display only: authorization uses the stored full project identity. */
+export declare function notificationIdentity(row: Pick<Notification, "project" | "taskId">): string;

package/dist/telegram-status.js

@@ -0,0 +1,265 @@
+import { publicChatText } from './chat-display.js';
+import { manualReviewOnly } from "./proof.js";
+/** Read-only phone views over the same dispatch and proof records as chat.
+ * No provider calls, repository access, new workflow state, or inferred success. */
+import { diagnoseTaskDispatch, withDispatchDiagnoses } from "./dispatch.js";
+import { CHAT_CONTROLS, chatControlHref, chatResultHref } from "./chat-controls.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
+    // is exactly the command counts — prose never is.
+    const t = text.trim();
+    if (/^\/?(?:help|start)$/i.test(t))
+        return { kind: "help" };
+    if (/^\/?status$/i.test(t))
+        return { kind: "status" };
+    // The picker: /tasks (or /task alone) lists them to choose from; /lead
+    // goes back to the lead conversation.
+    if (/^\/?tasks?$/i.test(t))
+        return { kind: "tasks" };
+    if (/^\/?lead$/i.test(t))
+        return { kind: "lead" };
+    // An id, a number from the list, or words from the title.
+    const task = /^\/?task\s+([A-Za-z0-9][A-Za-z0-9 ._'-]{0,63})$/i.exec(t);
+    if (task !== null)
+        return { kind: "task", id: task[1].trim() };
+    // A mistyped slash command gets help, but arbitrary prose is not a command.
+    return /^\/(?:status|tasks?|lead|help|start)(?:\s|$)/i.test(t) ? { kind: "help" } : null;
+}
+export const PHONE_HELP = [
+    "Toolroll in chat",
+    "",
+    "Say what you want in plain words: ask how something is going, ask for a change, or describe new work. The lead answers here and shows a card before anything changes; nothing changes until you act.",
+    "",
+    "Reply to any message about a task (an update, a result, a status or the lead's answer) to talk about that task.",
+    "",
+    "/tasks — pick a task to talk about",
+    "/task <name or number> — the same, by a word from its name",
+    "/lead — back to talking about everything",
+    "/status — what's happening across your projects",
+    "/team — team conversations; /team <number> to talk in one, /team off to leave",
+    "/help — this message",
+    "",
+    "To answer an agent's question, tap its buttons; reply to the question to add a note. Approvals that need your password, cancelling and publishing finish in the Toolroll console, and a console button only takes you there. The computer must be awake and connected to reply.",
+].join("\n");
+/** A third-party transport receives a small display copy, not logs, paths,
+ * credentials, or arbitrary markup. Scan BEFORE truncation/normalization. */
+const plain = publicChatText;
+/** The same display scrub for every phone-bound string a person or a model authored. */
+export const phoneText = plain;
+export function projectLabel(repo) {
+    return plain(repo.split(/[\\/]/).filter(Boolean).pop() ?? "project", 48);
+}
+function groupOf(d) {
+    if (d.condition === "running")
+        return "Working";
+    if (d.code === "cancelled")
+        return "Cancelled";
+    if (d.code === "complete")
+        return "Finished";
+    if (d.code === "review-pending" || d.action === null)
+        return "Waiting / next up";
+    return "Needs attention";
+}
+function nextStep(d) {
+    if (d.code === "review-pending")
+        return "An older review request is on record; nothing runs for it. Open the saved result in the console.";
+    switch (d.action) {
+        case "open-result": return "Open this task's result in the console, inspect it, then mark it complete or request changes.";
+        case "retry-task": return "Open this task in the console, review why it stopped, and use the available retry action.";
+        case "place-task": return "Choose a project for this task in the console.";
+        case "write-scope": return "Describe the goal and success checks in the console, or ask the planner to draft them.";
+        case "select-agent": return "Open this task in the console and check its agent settings or provider availability.";
+        case "approve-scope": return "Read the proposed work in the console and approve it if it is right.";
+        case "answer-decision": return "Answer the waiting question using its decision buttons or the console.";
+        case "unhold": return "Open this task in the console and release its hold when you want it to continue.";
+        case "inspect-hold": return "Open this task in the console to see what must change before it can continue.";
+        case "repair-dependency": return "Open this task in the console. Retry the required task, choose a different task to wait for, or explicitly stop waiting for it.";
+        case "repair-capability": return "Open this task's requirements in the console and fix the named setup issue.";
+        case "start-worker": return "Reopen Toolroll on the computer and finish any project-access setup. Approved work can resume when the builder reconnects.";
+        case "retry-review": return "Open the saved result in the console. Nothing reruns a review; mark the result complete or request changes.";
+        case "resume-run": return "Open this task in the console and choose Resume after its stopped attempt has finished stopping.";
+        case null: return d.condition === "running" ? "No action needed from you right now." : d.code === "cancelled" ? "Nothing else will run for this task." : "Toolroll can reconsider this task when its waiting condition clears.";
+    }
+}
+/** repos is the transport's explicit enrollment ceiling, never opened-project
+ * history. This snapshot is intentionally bounded and advertises that bound. */
+export function phoneStatus(store, repos, now, focused = null) {
+    if (repos.length === 0)
+        return "No connected projects are available to this bridge. 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)`, ""];
+        if (snapshot.tasksSaturated)
+            lines.push("Newest 60 tasks only — older work may still need attention.", "");
+        if (snapshot.tasks.length === 0)
+            lines.push("No tasks are recorded in these projects.");
+        for (const group of ["Needs attention", "Working", "Waiting / next up", "Finished", "Cancelled"]) {
+            const rows = snapshot.tasks.filter(t => t.dispatch !== null && t.dispatch !== undefined && groupOf(t.dispatch) === group);
+            if (rows.length === 0)
+                continue;
+            lines.push(`${group} · ${rows.length}${snapshot.tasksSaturated ? " in this snapshot" : ""}`);
+            for (const task of rows.slice(0, 2)) {
+                lines.push(`${plain(task.id, 64)} · ${projectLabel(repos[task.repoIndex])}`, `  ${plain(task.title, 64)} — ${plain(task.dispatch.summary, 80)}`);
+            }
+            if (rows.length > 2)
+                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.");
+        return lines.join("\n");
+    });
+}
+const PICK_GROUPS = ["Needs attention", "Working", "Waiting / next up", "Finished"];
+/** The tasks a paired chat can pick from: what needs the person first,
+ * then work in progress, waiting work and recent results; one entry per
+ * task (its revisions share it), optionally narrowed by words in the id or
+ * title. Bounded, within the chat's own project ceiling. */
+export function phoneTaskChoices(store, repos, now, query = null, limit = 8) {
+    if (repos.length === 0)
+        return [];
+    return store.transact(() => {
+        const snapshot = withDispatchDiagnoses(store, store.chatSnapshot(repos, now), now);
+        const words = query === null ? [] : query.toLowerCase().split(/\s+/).filter(Boolean);
+        const rows = snapshot.tasks
+            .filter(one => one.dispatch !== null && one.dispatch !== undefined && PICK_GROUPS.includes(groupOf(one.dispatch)))
+            .sort((a, b) => PICK_GROUPS.indexOf(groupOf(a.dispatch)) - PICK_GROUPS.indexOf(groupOf(b.dispatch)) || a.ageHours - b.ageHours);
+        const seen = new Set();
+        const choices = [];
+        for (const row of rows) {
+            const id = row.rootId ?? row.id;
+            if (seen.has(id) || !words.every(word => `${id} ${row.title}`.toLowerCase().includes(word)))
+                continue;
+            seen.add(id);
+            choices.push({ id, title: plain(row.title, 64), label: plain(row.dispatch.summary, 48), group: groupOf(row.dispatch) });
+            if (choices.length >= limit)
+                break;
+        }
+        return choices;
+    });
+}
+/** `/task <what>`: an exact task id, a number from the /tasks list, or
+ * words from a title — one match is chosen, several are offered. */
+export function resolvePhoneTask(store, repos, now, query) {
+    const ref = store.lookupRef(query);
+    if (ref?.repo != null && repos.includes(ref.repo)) {
+        const root = store.taskFamilyOf(query, repos, false)?.root ?? null;
+        return { kind: "one", id: root?.id ?? query, view: query, title: plain(root?.title ?? store.getTask(query)?.title ?? query, 64) };
+    }
+    const chosen = (one) => ({ kind: "one", id: one.id, view: store.taskFamilyOf(one.id, repos, false)?.current.id ?? one.id, title: one.title });
+    if (/^\d{1,2}$/.test(query)) {
+        const pick = phoneTaskChoices(store, repos, now)[Number(query) - 1];
+        return pick === undefined ? { kind: "none" } : chosen(pick);
+    }
+    const matches = phoneTaskChoices(store, repos, now, query);
+    return matches.length === 0 ? { kind: "none" } : matches.length === 1 ? chosen(matches[0]) : { kind: "many", choices: matches };
+}
+/** The picker as text, for chat apps without buttons. */
+export function phoneTaskListText(choices, focused) {
+    if (choices.length === 0)
+        return "No open or recent tasks in your connected projects. Describe what you want done and the lead will draft one.";
+    return [
+        ...(focused === null ? [] : [`Talking about: ${focused}`, ""]),
+        "Your tasks",
+        ...choices.map((one, index) => `${index + 1}. ${one.title} — ${one.label}`),
+        "",
+        "Send /task <number or name> to talk about one. /lead goes back to the lead.",
+    ].join("\n");
+}
+/** Said under a task's status when a chat app chooses it. */
+export const PHONE_FOCUS_LINE = "Talking about this task now: ask anything or say what to change. Reply to this message later to come back to it; /lead goes back to the lead.";
+/** A chosen task's status, then the line that says the chat now talks about it. */
+export function phoneFocusText(view) {
+    return `${view}\n\n${PHONE_FOCUS_LINE}`;
+}
+export const PHONE_NO_MATCH = "No such task in your connected projects. Send /tasks to pick one.";
+export const PHONE_BACK_TO_LEAD = "Back to the lead. Your messages here are about all your work again.";
+/** Where the rest lives when no button can say so: the closing line of an unlinked `/task`. */
+export const PHONE_CONSOLE_FOOTER = "Read-only status. Saved files and full actions are in the console.";
+/**
+ * Where `/task`'s one button goes, from the recorded diagnosis: the exact
+ * saved result's checks (a recorded verdict) or changes (none yet) for a
+ * finished task; the approval control while the scope waits; the task's
+ * own page for retry, hold, dependency and resume ceremonies; the task lens
+ * otherwise (a worker that must be started is not a browser step, and the
+ * lens says so). Only a task inside the phone's ceiling gets here.
+ */
+function taskLinkFor(id, d, result) {
+    const control = (name) => ({ label: CHAT_CONTROLS[name].label, path: chatControlHref(name, id) });
+    if (result !== null)
+        return result.verdict ? { label: "Open checks", path: chatResultHref(id, result.run, "checks") } : { label: "Open changes", path: chatResultHref(id, result.run, "changes") };
+    switch (d.action) {
+        case "approve-scope": return control("approval");
+        case "retry-task":
+        case "unhold":
+        case "inspect-hold":
+        case "repair-dependency":
+        case "retry-review":
+        case "resume-run": return control("recovery");
+        default: return control("task");
+    }
+}
+export function phoneTask(store, repos, id, now) {
+    return phoneTaskView(store, repos, id, now).text;
+}
+/** One task's status for a chat app: the words, its one console link, and
+ * the saved result it shows (a reply to it is about that result). */
+export function phoneTaskView(store, repos, id, now) {
+    return store.transact(() => {
+        const ref = store.lookupRef(id);
+        // Check admission before reading a title, run, proof, or diagnosis.
+        const task = ref?.repo != null && repos.includes(ref.repo) ? store.getTask(id) : null;
+        if (task === null || ref?.repo == null)
+            return { text: "No such task in your connected projects. Send /status for task IDs.", link: null, run: null };
+        const d = diagnoseTaskDispatch(store, id, now);
+        if (d === null)
+            return { text: "This task's status is unavailable. Open it in the console before retrying.", link: null, run: null };
+        const lines = [plain(task.title, 140), `${plain(id, 64)} · ${projectLabel(ref.repo)}`, `As of ${now.toISOString().replace("T", " ").slice(0, 19)} UTC`, "", plain(d.summary, 160)];
+        const blocker = d.blockerTaskId === null ? null : store.lookupRef(d.blockerTaskId);
+        const hiddenDependency = blocker !== null && (blocker.repo === null || !repos.includes(blocker.repo));
+        lines.push(hiddenDependency ? "A required task outside this phone view has not finished. Open the dependency in the console." : plain(d.detail, 650));
+        if (d.nextAt !== null)
+            lines.push(`Earliest recorded wake: ${plain(d.nextAt, 40)} (a connected worker is still required).`);
+        const runs = store.runsFor(ref.id);
+        const result = task.state === "done" ? runs.find(r => (r.role === "builder" || r.role === "scout") && (r.outcome === "built" || r.outcome === "no-change") && r.finishedAt !== null) : undefined;
+        const latest = result ?? runs[0];
+        if (latest !== undefined) {
+            lines.push("", `${result === undefined ? "Latest recorded attempt" : "Saved result"}: #${latest.id} · ${plain(latest.provider, 40)}${latest.model === null ? "" : ` / ${plain(latest.model, 80)}`}`);
+            // Terminal status wins; a leftover internal phase must never read as activity.
+            if (latest.finishedAt !== null)
+                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).`);
+            }
+        }
+        let link = null;
+        if (result !== undefined) {
+            const proof = store.proofVerdictFor(result.id);
+            link = taskLinkFor(id, d, { run: result.id, verdict: proof !== null });
+            const accepted = store.proofAcceptance(result.id) !== null;
+            const proofWords = { verified: "Checks passed at completion", attested: "Checks reported by the agent, not run by Toolroll", short: "Required saved material is missing", refuted: "The saved result conflicts with the approved scope" };
+            lines.push(`Checks: ${proof === null ? "No completion record saved" : manualReviewOnly(proof) ? accepted ? "Accepted by a person; the recorded checks are unchanged" : "A person must inspect this result; no recorded check failed" : proofWords[proof.verdict]}.`);
+            if (manualReviewOnly(proof) && !accepted)
+                lines.push('Reply “Send the result summary” for the checks, notes and screenshots.');
+            if (proof !== null && proof.matrix.length > 0)
+                lines.push(`Requirements: ${proof.matrix.filter(row => row.state === "pass").length}/${proof.matrix.length} satisfied in the saved record.`);
+            if (accepted && !manualReviewOnly(proof))
+                lines.push("An operator accepted this result; that does not change its recorded checks.");
+            const publication = store.publicationForRun(result.id);
+            const delivery = publication?.remoteState === "MERGED" ? "Merge observed on GitHub" : publication?.remoteState === "CLOSED" ? "Pull request closed, not merged" : publication?.state === "opened" ? `Pull request #${publication.prNumber ?? "?"} opened; not recorded as merged` : publication?.state === "pushed" ? "Branch pushed; pull request not yet recorded" : publication?.state === "intended" ? "Publication queued; not yet confirmed" : publication?.state === "failed" ? "Publication failed; the local result is preserved" : result.role === "scout" ? "Report saved locally" : "Result saved locally; no publication recorded";
+            lines.push(`Delivery: ${delivery}.`);
+        }
+        if (result === undefined)
+            link = taskLinkFor(id, d, null);
+        // Said once: the button is where; the sender adds the closing line when no button can ride.
+        lines.push("", `Next: ${nextStep(d)}`);
+        return { text: lines.join("\n"), link, run: result?.id ?? null };
+    });
+}
+/** Concise display only: authorization uses the stored full project identity. */
+export function notificationIdentity(row) {
+    if (row.project === null)
+        return "";
+    return `${projectLabel(row.project)}${row.taskId === null ? "" : ` / ${plain(row.taskId, 64)}`} · `;
+}

package/dist/telegram-team.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Telegram inside the shared team conversations (v72): a group follows one
+ * team conversation, a private chat may select one, and every message a
+ * paired teammate sends there is saved through the same team operation the
+ * browser and CLI use — same queue, same single writer, same permissions and
+ * spending consent. Replies and teammates' messages come back through a
+ * per-chat cursor read on every bridge cycle. No model runs here.
+ */
+import type { Store } from "./store.js";
+import { type InlineButton } from "./telegram-mate.js";
+import type { TelegramTransport } from "./telegram.js";
+export type TeamCommand = {
+    kind: "list";
+} | {
+    kind: "select";
+    index: number;
+} | {
+    kind: "off";
+};
+/** `/team` lists, `/team <n>` chooses, `/team off` (or `private`) leaves. Any other slash text is not ours. */
+export declare function teamCommand(text: string): TeamCommand | null;
+export declare const PAIR_FIRST = "Pair your phone first: open Settings \u2192 Telegram in Toolroll, then send the code here in a private chat.";
+type Counts = {
+    ignored: number;
+    chatQueued?: number;
+    chatRefused?: number;
+    statusReplies?: number;
+    problems: string[];
+};
+export type TeamInbound = {
+    store: Store;
+    botId: string;
+    now: Date;
+    report: Counts;
+    /** The enrolled ceiling read for this update; null when unreadable. */
+    projects: readonly string[] | null;
+    phoneOrigin: (() => string | null) | undefined;
+    updateId: number;
+    message: {
+        message_id: number;
+        text?: string;
+        chat?: {
+            id: number;
+            type?: string;
+        };
+        from?: {
+            id: number;
+        };
+        reply_to_message?: {
+            message_id: number;
+        };
+        forward_origin?: unknown;
+        forward_date?: unknown;
+        via_bot?: unknown;
+        sender_chat?: unknown;
+        caption?: string;
+    };
+    /** Queue one reply for after the update's transaction commits. */
+    say: (chatId: string, text: string, keyboard?: InlineButton[][]) => void;
+};
+/**
+ * Handle one inbound message that belongs to the team layer. Returns true
+ * when it was consumed here (a `/team` command in any chat, any message in
+ * a group, or a private message while a conversation is selected); false
+ * hands the update to the older personal paths untouched.
+ */
+export declare function applyTeamInbound(input: TeamInbound): boolean;
+/** The request identity a Telegram message carries into the team queue: the chat and the update, so the same update never saves twice and delivery can tell its own messages apart. */
+export declare function teamRequestId(chatId: string, updateId: number): string;
+type TeamDeliveryReport = {
+    sent: number;
+    problems: string[];
+};
+/**
+ * Carry new conversation messages to every chat that follows one: the
+ * lead's replies, teammates' messages (never this chat's own), and each
+ * reply's pending cards. Read from the cursor on every cycle; a failed send
+ * leaves the cursor where it was, so the next cycle retries the same
+ * message rather than skipping it.
+ */
+export declare function deliverTeamChats(store: Store, botId: string, transport: TelegramTransport, clock: () => Date, report: TeamDeliveryReport, projects: readonly string[], phoneOrigin?: () => string | null, options?: {
+    readProjects?: () => Promise<readonly string[]>;
+    canDeliver?: () => boolean;
+}): Promise<void>;
+export {};