toolroll 0.9.16 → 0.9.18

package/dist/mate.js

@@ -11,6 +11,7 @@ import { MATE_MAX_PROPOSALS_PER_TURN, MATE_TOOL_SCHEMAS, executeMateTool, isMate
 import { composeSubscriptionMatePrompt, performSubscriptionMateRequest } from "./subscription-chat.js";
 import { leadContext } from './lead-context.js';
 import { envValue } from "./names.js";
+import { deliverableClaim, deliverableRepair, dropDeliverableClaims, replyCarriesDeliverable } from "./reply-shape.js";
 export const MATE_MESSAGE_MAX_CHARS = 2_000;
 /** Where a promise made this turn is reported: the chat app it arrived on, or this conversation for the console and terminal. */
 function promiseChannelOfTurn(channel) {
@@ -41,6 +42,47 @@ export const MATE_REFUSAL_COPY = {
     "request-changed": "That send was already received with different text or task context. Reload the conversation before sending a new message.",
     channel: "This conversation's connection changed, so the message wasn't sent. Reconnect it, then send again.",
 };
+/** A turn stopped because its chat's standing changed: what happened, what it means, one next step. */
+export const MATE_CHANNEL_COPY = {
+    unpaired: "This chat is no longer connected to your account, so the reply was stopped. Nothing it proposed was kept. Connect the chat again in Settings, then send your message again.",
+    "not-approver": "Your account can no longer approve work here, so the reply was stopped. Nothing it proposed was kept. Ask an owner to restore your access, then send your message again.",
+    "projects-changed": "The projects this chat can see changed while the lead was answering, so the reply was stopped. Nothing it proposed was kept. Send your message again.",
+    "projects-unreadable": "Your project list couldn't be read just now, so the reply was stopped. Nothing it proposed was kept. Send your message again in a minute.",
+    "member-changed": "Your account in this chat app no longer has access, so the reply was stopped. Nothing it proposed was kept. Ask the app's admin to add you back, then send your message again.",
+    "access-changed": "This chat's access changed while the lead was answering, so the reply was stopped. Nothing it proposed was kept. Reconnect the chat, then send your message again.",
+};
+/** Why a reply did not finish, in the same three parts: what happened, what it means, one next step. */
+export const MATE_FAILURE_COPY = {
+    stopped: "This reply was stopped before it finished, from another window or by a newer message. Nothing it proposed was kept. Send your message again if you still need an answer.",
+    ended: "Your sign-in or this conversation ended while the lead was answering. Nothing it proposed was kept. Sign in again or start a new chat, then send your message again.",
+    tooLong: "The reply took too long and was stopped. Nothing it proposed was kept. Send your message again, or ask for less at once.",
+    secretRead: "Something the lead read looked like a password or key, so it stopped before sending it anywhere. Nothing was kept. Remove the password or key from that task or note, then ask again.",
+    secretReply: "The lead's reply contained something that looked like a password or key, so it was thrown away. Nothing was kept. Ask again, without asking for a password or key.",
+    paused: "An earlier reply stopped before its cost was known, so chat is paused. This message wasn't answered. Confirm that earlier reply on the Chat page, then send again.",
+    notStarted: "The reply couldn't be started. Nothing was kept or charged. Send your message again.",
+    notInstalled: "The chat app the lead uses isn't installed on this computer, so it couldn't answer. Nothing was kept. Install it, or choose another provider in Settings → Lead.",
+    unreadable: "The chat provider sent back an answer that couldn't be read, so it was thrown away. Nothing was kept. Send your message again.",
+    signIn: "The chat provider couldn't answer; its sign-in may have expired. Nothing was kept. Sign in to it again on this computer, then send your message again.",
+    refused: "The chat provider turned the request down. Nothing was kept or charged. Try again in a minute; if it keeps happening, check the provider in Settings → Lead.",
+    tooLongUnknownCost: "The reply took too long and was stopped, and its cost isn't known yet, so chat is paused. Nothing it proposed was kept. Confirm the cost on the Chat page to turn chat back on.",
+    lostUnknownCost: "The chat provider stopped responding partway through, and the cost isn't known, so chat is paused. Nothing it proposed was kept. Confirm the cost on the Chat page to turn chat back on.",
+    unreadableUnknownCost: "The chat provider sent back an answer that couldn't be read, and its cost isn't known, so chat is paused. Nothing it proposed was kept. Confirm the cost on the Chat page to turn chat back on.",
+    empty: "The lead sent back an empty answer. Nothing was kept. Send your message again.",
+    unusable: "The lead's answer couldn't be used, so it was thrown away. Nothing was kept. Send your message again.",
+};
+/** A failed turn's saved reason as plain words, for a surface that reads the turn back later (a restart, a delivery retry). */
+export function mateFailureText(reason) {
+    switch (reason) {
+        case "timeout": return MATE_FAILURE_COPY.tooLong;
+        case "malformed-reply": return MATE_FAILURE_COPY.unreadable;
+        case "secret-refused": return MATE_FAILURE_COPY.secretReply;
+        case "latched": return MATE_FAILURE_COPY.paused;
+        case "revoked": return MATE_FAILURE_COPY.ended;
+        case "superseded": return MATE_FAILURE_COPY.stopped;
+        case "provider-error": return MATE_FAILURE_COPY.refused;
+        default: return "The lead's reply didn't finish. Nothing it proposed was kept. Send your message again.";
+    }
+}
 const READ_TOOLS = new Set(["get_brief", "get_project_context", "get_actions", "get_action_status", "get_skills", "get_acceptance_evidence", "recap", "list_repos", "list_tasks", "get_task", "get_result", "get_result_images", "get_controls", "get_agents", "get_project_knowledge", "get_task_conversation", "get_diff", "get_check_log", "get_project_tools", "get_flows", "get_flow_insights", "list_decisions", "get_decision", "queue"]);
 /** The last messages of the thread as provider-neutral history, newest kept first until the byte cap. */
 export function historyFor(store, thread, queuedMessageId) {
@@ -222,6 +264,7 @@ export async function runMateTurn(input) {
     const readDecisions = new Map();
     const readResults = new Map();
     const searchedMemory = new Map();
+    const checkedCapabilities = new Map();
     /** The turn's one question to its owner: shown with the reply only once the turn answers; a failed turn drops it. */
     const ask = (question, options) => store.recordMateAsk({ turn: turnId, thread: thread.id, question, options }, clock());
     let tokensIn = 0;
@@ -256,20 +299,30 @@ export async function runMateTurn(input) {
     // AFTER it resolves, immediately before sending context or using a tool.
     const guard = (channel) => {
         if (!stillOurs())
-            return { ok: false, turn: turnId, failed: "superseded", message: "this turn was ended before its next action", unknownSpend: false };
+            return { ok: false, turn: turnId, failed: "superseded", message: MATE_FAILURE_COPY.stopped, unknownSpend: false };
         if (!channel.ok)
-            return fail("revoked", `this conversation's connection changed (${channel.reason}) — nothing it proposed was kept`, false);
+            return fail("revoked", MATE_CHANNEL_COPY[channel.reason] ?? MATE_CHANNEL_COPY["access-changed"], false);
         const standing = reproveApprover(store, who);
         const liveSession = store.getMateSession(session.id);
         const liveThread = store.getMateThread(thread.id);
         if (!standing.ok || liveSession === null || liveSession.endedAt !== null || liveThread === null || liveThread.closedAt !== null) {
-            return fail("revoked", "your standing or this conversation ended — nothing it proposed was kept", false);
+            return fail("revoked", MATE_FAILURE_COPY.ended, false);
         }
         return null;
     };
     let reply = null;
     let stoppedAtCap = false;
     let lastText = "";
+    /** A page shown this turn (show_control): a reply may say it links one. */
+    let shownControl = false;
+    /** The turn's one repair step for a reply that claims an attachment it does not carry. */
+    let repaired = false;
+    const unbacked = (text) => {
+        const claim = deliverableClaim(text);
+        if (claim === null || shownControl || replyCarriesDeliverable(text) || store.listMateTurnEvidence(turnId).length > 0)
+            return null;
+        return claim;
+    };
     while (steps < maxSteps) {
         const blocked = guard(input.revalidate === undefined ? { ok: true } : await input.revalidate());
         if (blocked !== null)
@@ -277,22 +330,22 @@ export async function runMateTurn(input) {
         now = clock();
         const remainingMs = TURN_WALL_CLOCK_MS - (now.getTime() - turnStartedAt);
         if (remainingMs <= 0)
-            return fail("timeout", "the turn ran out of time before the model finished", false);
+            return fail("timeout", MATE_FAILURE_COPY.tooLong, false);
         const request = direct ? composeDirect(input.key) : composeSubscription();
         // Tool results join the outbound body: scanned again before every dispatch.
         const outbound = typeof request === "string" ? request : request.body;
         if (scanForSecrets(outbound).length > 0) {
-            return fail("secret-refused", "a tool result contained something credential-shaped — the turn stopped before sending it", false);
+            return fail("secret-refused", MATE_FAILURE_COPY.secretRead, false);
         }
         const step = store.openMateStep({ mateTurn: turnId, generation: started.generation, approver: who.name, credentialKey, provider: config.provider, model: config.model, deadlineMs: remainingMs + 10_000 }, now);
         if (!step.ok) {
             if (step.reason === "latched")
-                return fail("latched", "an earlier reply stopped before its cost was known, so chat is paused — acknowledge that reply on the Chat page, then send again", false);
-            return { ok: false, turn: turnId, failed: "superseded", message: "this turn was ended before its next step", unknownSpend: false };
+                return fail("latched", MATE_FAILURE_COPY.paused, false);
+            return { ok: false, turn: turnId, failed: "superseded", message: MATE_FAILURE_COPY.stopped, unknownSpend: false };
         }
         const stepStarted = store.startChatTurn(step.id, now);
         if (!stepStarted.ok)
-            return fail("provider-error", "the step could not be dispatched", false);
+            return fail("provider-error", MATE_FAILURE_COPY.notStarted, false);
         steps++;
         progress({ kind: "step", turn: turnId, step: steps });
         const requestBytes = Buffer.byteLength(outbound, "utf8");
@@ -337,36 +390,36 @@ export async function runMateTurn(input) {
             if (!direct) {
                 finishStep({ state: "failed", failureReason: result.problem === "timeout" ? "timeout" : result.problem === "malformed-reply" ? "malformed-reply" : "provider-error", settledMicrousd: 0 });
                 const message = result.problem === "not-found"
-                    ? "the selected subscription CLI is not installed on this machine"
+                    ? MATE_FAILURE_COPY.notInstalled
                     : result.problem === "timeout"
-                        ? "the subscription turn ran out of time"
+                        ? MATE_FAILURE_COPY.tooLong
                         : result.problem === "malformed-reply"
-                            ? "the subscription provider returned a malformed answer and it was discarded"
-                            : "the subscription provider refused or could not complete the turn — check its login in the terminal";
+                            ? MATE_FAILURE_COPY.unreadable
+                            : MATE_FAILURE_COPY.signIn;
                 return fail(result.problem === "timeout" ? "timeout" : result.problem === "malformed-reply" ? "malformed-reply" : "provider-error", message, false);
             }
             if (result.problem.startsWith("status-")) {
                 // The provider ANSWERED with an error: nothing billed for this step.
                 finishStep({ state: "failed", failureReason: "provider-error", settledMicrousd: 0 });
-                return fail("provider-error", "the provider refused the request — nothing was billed for that step", false);
+                return fail("provider-error", MATE_FAILURE_COPY.refused, false);
             }
             if (result.problem === "timeout") {
                 finishStep({ state: "failed", failureReason: "timeout", settledMicrousd: null, unknownSpend: true });
-                return fail("timeout", "the turn timed out; that step's cost is unknown — the whole reservation is charged and the credential is blocked until you acknowledge it", true);
+                return fail("timeout", MATE_FAILURE_COPY.tooLongUnknownCost, true);
             }
             if (result.problem === "network") {
                 finishStep({ state: "failed", failureReason: "provider-error", settledMicrousd: null, unknownSpend: true });
-                return fail("provider-error", "the provider could not be reached after dispatch; cost unknown — the whole reservation is charged; acknowledge to re-enable chat", true);
+                return fail("provider-error", MATE_FAILURE_COPY.lostUnknownCost, true);
             }
             finishStep({ state: "failed", failureReason: "malformed-reply", settledMicrousd: null, unknownSpend: true });
-            return fail("malformed-reply", "the provider's response was malformed and was discarded; cost unknown — the whole reservation is charged; acknowledge to re-enable chat", true);
+            return fail("malformed-reply", MATE_FAILURE_COPY.unreadableUnknownCost, true);
         }
         const answer = result.answer;
         // Usage that cannot be true — more input tokens than bytes sent — is a
         // malformed reply with unknown cost, never a number to settle by.
         if (direct && answer.tokensIn > requestBytes) {
             finishStep({ state: "failed", failureReason: "malformed-reply", settledMicrousd: null, unknownSpend: true });
-            return fail("malformed-reply", "the provider reported usage that cannot be true; cost unknown — the whole reservation is charged; acknowledge to re-enable chat", true);
+            return fail("malformed-reply", MATE_FAILURE_COPY.unreadableUnknownCost, true);
         }
         // The pinned math, or the provider's own reported charge when HIGHER.
         const stepSettled = direct
@@ -385,15 +438,23 @@ export async function runMateTurn(input) {
             return changed;
         if (answer.calls.length === 0) {
             if (answer.text.trim() === "")
-                return fail("malformed-reply", "the model answered with nothing", false);
-            reply = answer.text;
+                return fail("malformed-reply", MATE_FAILURE_COPY.empty, false);
+            // "Here's the screenshot" with nothing attached or linked: one repair step to attach it or drop the claim; never the claim alone.
+            const claim = unbacked(answer.text);
+            if (claim !== null && !repaired && steps < maxSteps) {
+                repaired = true;
+                history.push({ role: "assistant", text: answer.text, calls: [] });
+                history.push({ role: "operator", text: deliverableRepair(claim) });
+                continue;
+            }
+            reply = claim === null ? answer.text : dropDeliverableClaims(answer.text);
             break;
         }
         if (answer.calls.length > MATE_MAX_CALLS_PER_STEP)
-            return fail("malformed-reply", "the model asked for more tool calls than one step allows", false);
+            return fail("malformed-reply", MATE_FAILURE_COPY.unusable, false);
         for (const call of answer.calls) {
             if (!isMateTool(call.name))
-                return fail("malformed-reply", "the model called a tool that does not exist", false);
+                return fail("malformed-reply", MATE_FAILURE_COPY.unusable, false);
         }
         history.push({ role: "assistant", text: answer.text, calls: answer.calls });
         for (const [index, call] of answer.calls.entries()) {
@@ -403,9 +464,11 @@ export async function runMateTurn(input) {
                     return changed;
             }
             progress({ kind: "tool", turn: turnId, step: steps, label: mateToolLabel(call.name) });
-            const outcome = executeMateTool({ store, who, now: clock(), draft, selectEvidence, step: steps, readDecisions, readResults, searchedMemory, ask, ...(input.integrations === undefined ? {} : { integrations: input.integrations }), thread: thread.id, turn: turnId, ...(promiseChannelOfTurn(input.channel) === undefined ? {} : { channel: promiseChannelOfTurn(input.channel) }), ...(input.evidenceRoot === undefined ? {} : { evidenceRoot: input.evidenceRoot }), ...(input.mediaDelivery === undefined ? {} : { mediaDelivery: input.mediaDelivery }) }, call.name, call.args, view);
+            const outcome = executeMateTool({ store, who, now: clock(), draft, selectEvidence, step: steps, readDecisions, readResults, searchedMemory, checkedCapabilities, ask, ...(input.integrations === undefined ? {} : { integrations: input.integrations }), thread: thread.id, turn: turnId, ...(promiseChannelOfTurn(input.channel) === undefined ? {} : { channel: promiseChannelOfTurn(input.channel) }), ...(input.evidenceRoot === undefined ? {} : { evidenceRoot: input.evidenceRoot }), ...(input.mediaDelivery === undefined ? {} : { mediaDelivery: input.mediaDelivery }) }, call.name, call.args, view);
             if (READ_TOOLS.has(call.name))
                 reads++;
+            if (call.name === "show_control" && outcome.ok)
+                shownControl = true;
             // Opt-in, local diagnostics for end-to-end runs: what the lead asked of each tool and what came back (its start), keys
             // blanked. Each line stays whole JSON so a run can assert on what a tool returned rather than on the model's words.
             if (envValue(process.env, "MATE_TRACE") === "1") {
@@ -419,16 +482,17 @@ export async function runMateTurn(input) {
     }
     if (reply === null) {
         stoppedAtCap = true;
-        reply = `${lastText.trim() === "" ? "" : `${lastText.trim()}\n\n`}(stopped after ${maxSteps} steps${maxSteps < MATE_MAX_STEPS ? " within this conversation’s remaining allowance" : ""})`;
+        const last = lastText.trim() === "" || unbacked(lastText) === null ? lastText.trim() : dropDeliverableClaims(lastText);
+        reply = `${last === "" ? "" : `${last}\n\n`}(I stopped here: this answer needed more steps than ${maxSteps < MATE_MAX_STEPS ? "this conversation's remaining spending allows" : "one reply allows"}. Ask me to carry on.)`;
     }
     // Ruling 11: model text is scanned before it becomes durable.
     if (scanForSecrets(reply).length > 0)
-        return fail("secret-refused", "the model's reply contained something credential-shaped and was discarded", false);
+        return fail("secret-refused", MATE_FAILURE_COPY.secretReply, false);
     now = clock();
     const activity = activitySummary(reads, proposals, steps);
     // One write (finding 12): settle, debit, promote the drafts, append the assistant text.
     const finalized = store.finalizeMateTurn(turnId, started.generation, { state: "answered", settledMicrousd: settled, tokensIn, tokensOut, message: { text: reply, activity } }, now);
     if (!finalized)
-        return { ok: false, turn: turnId, failed: "superseded", message: "this turn was ended before it could be kept", unknownSpend: false };
+        return { ok: false, turn: turnId, failed: "superseded", message: MATE_FAILURE_COPY.stopped, unknownSpend: false };
     return { ok: true, turn: turnId, reply, activity, proposals, steps, stoppedAtCap, settledMicrousd: settled };
 }

package/dist/modes.d.ts

@@ -65,6 +65,12 @@ export type ModeTerms = {
      * `repairAuto` is also true — a mode may sign a cap without signing the
      * authority, but never the reverse. */
     repairMaxAttempts: number;
+    /** Explicit opt-in: the signer's paired Telegram chat may approve this
+     * repository's plans and merge its ready pull requests with two taps,
+     * for the mode's lifetime. A plan that widens permissions, exceeds the
+     * per-attempt budget or touches protected paths still opens Toolroll.
+     * Legacy modes read FALSE — never inherited, only freshly signed. */
+    chatApprove: boolean;
     absoluteExpiry: string;
 };
 export declare const MODE_MAX_DAYS = 7;

package/dist/modes.js

@@ -34,6 +34,7 @@ export function presetTerms(name, absoluteExpiry) {
             allowPaidFallback: false,
             repairAuto: false,
             repairMaxAttempts: 0,
+            chatApprove: false,
             absoluteExpiry,
         }
         : {
@@ -51,6 +52,7 @@ export function presetTerms(name, absoluteExpiry) {
             allowPaidFallback: false,
             repairAuto: false,
             repairMaxAttempts: 0,
+            chatApprove: false,
             absoluteExpiry,
         };
 }
@@ -119,6 +121,7 @@ export function modeTermsFromJson(json) {
         (t["repairAuto"] === undefined || typeof t["repairAuto"] === "boolean") &&
         (t["repairMaxAttempts"] === undefined ||
             (typeof t["repairMaxAttempts"] === "number" && Number.isInteger(t["repairMaxAttempts"]) && t["repairMaxAttempts"] >= 0 && t["repairMaxAttempts"] <= 3)) &&
+        (t["chatApprove"] === undefined || typeof t["chatApprove"] === "boolean") &&
         typeof t["absoluteExpiry"] === "string" &&
         !Number.isNaN(Date.parse(t["absoluteExpiry"]))) {
         return {
@@ -136,6 +139,7 @@ export function modeTermsFromJson(json) {
             allowPaidFallback: t["allowPaidFallback"] === true,
             repairAuto: t["repairAuto"] === true,
             repairMaxAttempts: typeof t["repairMaxAttempts"] === "number" ? t["repairMaxAttempts"] : 0,
+            chatApprove: t["chatApprove"] === true,
             absoluteExpiry: t["absoluteExpiry"],
         };
     }
@@ -179,6 +183,8 @@ export function modeWords(terms) {
             : "automatic fallback never switches to a paid API key on its own; a subscription that runs out stops and waits for you",
         ...(terms.repairAuto
             ? ["historical automatic repair grants are retained on record but no longer schedule work"] : []),
+        ...(terms.chatApprove
+            ? ["your paired Telegram chat may approve this repository's plans and merge its ready pull requests, two taps each, without your password; a plan that widens permissions, exceeds the per-attempt cap above or touches protected paths still opens Toolroll"] : []),
         `everything above ends at ${terms.absoluteExpiry.slice(0, 16).replace("T", " ")} — revoking it earlier is one click, and every act it covered falls back to its own ceremony`,
     ];
 }

package/dist/operate.js

@@ -79,7 +79,7 @@ import { pullRequestLines, runTaskMergeCommand, runTaskOutcomeCommand } from "./
 import { homedir, hostname, tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { releaseStalledUpdate, waitingUpdate } from "./toolroll-update.js";
-import { openStore, openStoreNoMigrate, CONCURRENT_WRITER_WAIT_MS, isDatabaseBusy, databasePath, BUILT_IN, DEFAULT_ACTOR, parseCapabilityKey, verifiedAuthor, contestantProfileOf, isDigestTime, } from "./store.js";
+import { openStore, openStoreNoMigrate, CONCURRENT_WRITER_WAIT_MS, isDatabaseBusy, databasePath, BUILT_IN, DEFAULT_ACTOR, parseCapabilityKey, verifiedAuthor, contestantProfileOf, isDigestTime, RESULT_SCREENSHOTS, } from "./store.js";
 import { randomBytes, randomInt, randomUUID } from "node:crypto";
 import { authorizePlanUnderMode } from "./plan-auto.js";
 import { ghDispatchAdapter, mirrorTaskId, syncPass } from "./sync.js";
@@ -247,6 +247,7 @@ export const OPERATE_HELP = `toolroll — operating the queue
   toolroll notifications [quiet|all]   how chats reach you: only when you're needed (the default), or every step
   toolroll notifications digest <HH:MM>|off   one evening message: what finished, what waits, what failed
   toolroll notifications mute|unmute --repo <p>   no pings for a project; the console and digest keep it
+  toolroll notifications screenshots off|first|all   a result's saved screenshots with its chat message: none, the first one, or up to 4
   toolroll retention show|preview    how long evidence, checkout records, chat and notifications are kept; what the daily sweep would remove
   toolroll retention set <kind> <period>   evidence|checkouts|chat|notifications, 1d|30d|1y|forever (instance operator)
   toolroll backup now|list          back the database up now; list backups and how the last ones went
@@ -647,7 +648,7 @@ export const OPERATE_BOOLEAN_FLAGS = new Set([
     "json", "yes", "all", "local", "history", "latest-watch", "dry-run", "file", "allow-paid-fallback",
     "clear", "follow", "ready", "all-tasks", "inbound-only", "help", "undo", "anyone", "allow-dispatch", "allow-merge", "merge-delete-branch",
     "no-open", "remove", "no-verify", "no-follow", "end", "report", "off", "tmux",
-    "self-heal", "plan-auto", "repair-auto", "review-retry-auto", "no-local",
+    "self-heal", "plan-auto", "chat-approve", "repair-auto", "review-retry-auto", "no-local",
     "html", "csv", "alerts-only",
     // v105: the full export.
     "zip",
@@ -5716,6 +5717,9 @@ async function modeCommand(positional, flags, context) {
     // explicit flag lets an exhausted subscription switch to another account.
     if (flag(flags, "allow-paid-fallback"))
         terms.allowPaidFallback = true;
+    // Approving plans and merges from the signer's paired chat: never a preset default, only this flag.
+    if (flag(flags, "chat-approve"))
+        terms.chatApprove = true;
     // Automerge requires a live merge-capable grant on the repo (D1).
     if (terms.publication === "automerge" && !store.hasMergeCapableGrant(repo, now)) {
         return fail(write, json, "mode set", "no-grant", "automerge needs a merge-capable publication grant on this repo — file one first", EXIT.refused);
@@ -11643,6 +11647,8 @@ async function chatCommand(flags, context) {
         ceilingUsd: ceilingGiven === undefined ? undefined : Number(ceilingGiven),
         ...(context.mateSeams === undefined ? {} : { seams: { ...context.mateSeams, clock: context.mateSeams.clock ?? context.clock } }),
         ...(context.evidenceRoot === undefined ? {} : { evidenceRoot: context.evidenceRoot }),
+        // The console's own address (and its public one): links there read as "the task", "the result", "Settings → Lead".
+        appOrigin: [loadConsoleUrl(process.env, dirname(context.databaseFile)), phoneOrigin(process.env, dirname(context.databaseFile))],
     });
     return result.code;
 }
@@ -12236,8 +12242,9 @@ async function budgetCommand(positional, flags, context) {
     const saved = store.setBudget({ scope: target.scope, key: target.key, limitMicrousd: Math.round(dollars) * 1_000_000, hardStop: !flags.has("alerts-only") }, acting.name, context.clock());
     return succeed(context.write, context.json, command, { budget: saved }, () => [`${budgetLabel(saved).replace(/'s$/, "")}: ${spendUsd(saved.limitMicrousd)} a month${saved.hardStop ? ", API work stops at 100%" : ", alerts only"}.`]);
 }
-/** `notifications [quiet | all | digest <HH:MM> | digest off]`: how chats reach this person — only when they are
- * needed (the default), every step, and an optional evening digest. Each person sets their own. */
+/** `notifications [quiet | all | digest <HH:MM> | digest off | screenshots off|first|all]`: how chats reach this
+ * person — only when they are needed (the default), every step, an optional evening digest, and whether a result's
+ * saved screenshots follow its message. Each person sets their own. */
 async function notificationsCommand(positional, flags, context) {
     const [action, value, ...extra] = positional;
     const command = `notifications${action === undefined ? "" : ` ${action}`}`;
@@ -12246,10 +12253,13 @@ async function notificationsCommand(positional, flags, context) {
     for (const name of flags.keys())
         if (!["as", "token", "token-file", "token-env", "db", "json", ...(muting ? ["repo"] : [])].includes(name))
             return fail(context.write, context.json, command, "usage", `--${name} is not a notifications option.`, EXIT.usage);
-    const usage = "Use notifications quiet, notifications all, notifications digest <HH:MM>|off, or notifications mute|unmute --repo <project>.";
-    if (extra.length > 0 || (action !== undefined && !["quiet", "all", "digest", "mute", "unmute"].includes(action)) || (action === "digest") !== (value !== undefined) || (muting && (value !== undefined || text(flags, "repo") === undefined))) {
+    const usage = "Use notifications quiet, notifications all, notifications digest <HH:MM>|off, notifications screenshots off|first|all, or notifications mute|unmute --repo <project>.";
+    const valued = action === "digest" || action === "screenshots";
+    if (extra.length > 0 || (action !== undefined && !["quiet", "all", "digest", "screenshots", "mute", "unmute"].includes(action)) || valued !== (value !== undefined) || (muting && (value !== undefined || text(flags, "repo") === undefined))) {
         return fail(context.write, context.json, command, "usage", usage, EXIT.usage);
     }
+    if (action === "screenshots" && !RESULT_SCREENSHOTS.includes(value))
+        return fail(context.write, context.json, command, "usage", "Screenshots with results is off, first (the first one) or all (up to 4).", EXIT.usage);
     if (action === "digest" && value !== "off" && !isDigestTime(value))
         return fail(context.write, context.json, command, "usage", "The digest time is HH:MM on a 24-hour clock, like 18:30, or off.", EXIT.usage);
     const acting = await askCredentials(flags, context);
@@ -12272,11 +12282,13 @@ async function notificationsCommand(positional, flags, context) {
     }
     const preference = action === "quiet" || action === "all" ? store.setNotificationPreference(acting.name, { mode: action }, acting.name, now)
         : action === "digest" ? store.setNotificationPreference(acting.name, { digestAt: value === "off" ? null : value }, acting.name, now)
-            : store.notificationPreference(acting.name);
+            : action === "screenshots" ? store.setNotificationPreference(acting.name, { screenshots: value }, acting.name, now)
+                : store.notificationPreference(acting.name);
     const muted = store.mutedProjects(acting.name);
-    return succeed(context.write, context.json, command, { mode: preference.mode, digestAt: preference.digestAt, mutedProjects: muted }, () => [
+    return succeed(context.write, context.json, command, { mode: preference.mode, digestAt: preference.digestAt, screenshots: preference.screenshots, mutedProjects: muted }, () => [
         preference.mode === "quiet" ? "Only when you're needed: one message per task, updated as it moves, and a new one when something needs you." : "Every step: a message for each update.",
         preference.digestAt === null ? "No evening digest." : `Evening digest at ${preference.digestAt}: what finished, what waits and what failed.`,
+        preference.screenshots === "off" ? "Screenshots with results: off." : `Screenshots with results: ${preference.screenshots === "first" ? "the first one" : "up to 4"}.`,
         ...(muted.length === 0 ? [] : [`Muted: ${muted.map(one => basename(one)).join(", ")}.`]),
     ]);
 }

package/dist/phase-routing.d.ts

@@ -234,7 +234,7 @@ export declare function parseOverrides(raw: unknown): RouteOverride[] | null;
  * nobody had overridden anything. */
 export declare function overridesFromJson(json: string | null): RouteOverride[] | null;
 export declare function canonicalOverridesJson(overrides: readonly RouteOverride[]): string | null;
-export type ReadinessLookup = (provider: ProviderId) => Pick<ReadinessObservation, "state" | "reason" | "runner" | "observedAt"> | null;
+export type ReadinessLookup = (provider: ProviderId) => (Pick<ReadinessObservation, "state" | "reason" | "runner" | "observedAt"> & Partial<Pick<ReadinessObservation, "probe">>) | null;
 export type RouteLegProjection = RouteLeg & {
     readiness: ReadinessState;
     readinessReason: string | null;

package/dist/project-delete.js

@@ -228,12 +228,15 @@ function deleteRows(store, repo, d, now) {
     del("telegram_flow_prompt", IN("card"), C);
     del("telegram_question_action", IN("question"), questions);
     del("telegram_question_prompt", IN("question"), questions);
+    del("chat_decide_action", IN("task_id"), K);
+    del("chat_decide_prompt", IN("task_id"), K);
     del("telegram_task_message", `${IN("task_id")} OR ${IN("source_run")}`, K, R);
     del("telegram_conversation_part", `${IN("conversation")} OR ${IN("source_run")} OR ${IN("task_id")}`, conversations, R, K);
     del("telegram_conversation", IN("id"), conversations);
     del("telegram_outbound_message", `project = ? OR ${IN("notification")} OR ${IN("task_ref")} OR ${IN("source_run")}`, repo, notifications, T, R);
     del("chat_card_task", IN("task_ref"), T);
     del("chat_batch_item", IN("task_ref"), T);
+    del("result_shot_sent", IN("run"), R);
     del("push_delivery", IN("notification"), notifications);
     del("notification_actor", IN("notification"), notifications);
     del("notification_delivery", IN("notification"), notifications);

package/dist/provider-auth.d.ts

@@ -34,6 +34,10 @@ export declare function providerName(provider: string): string;
 export declare function signInReason(pause: Pick<AuthPause, "provider" | "authMode">): string;
 /** What to run, as a command. */
 export declare function signInCommand(pause: Pick<AuthPause, "provider" | "authMode">): string;
+/** The same command for a chat message: the phone scrub hides anything shaped
+ * like a path (`/login` included), so a message names Claude's equivalent
+ * `claude auth login`. */
+export declare function messageCommand(pause: Pick<AuthPause, "provider" | "authMode">): string;
 /** One line for status, ready and the console. */
 export declare function signInWords(pause: AuthPause): string;
 /** The open pause for a provider, or null. */

package/dist/provider-auth.js

@@ -44,7 +44,7 @@ export function signInCommand(pause) {
 /** The same command for a chat message: the phone scrub hides anything shaped
  * like a path (`/login` included), so a message names Claude's equivalent
  * `claude auth login`. */
-function messageCommand(pause) {
+export function messageCommand(pause) {
     const command = signInCommand(pause);
     return command === "claude /login" ? "claude auth login" : command;
 }

package/dist/reply-shape.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The lead's voice, enforced: every chat surface (console, terminal, Telegram, Slack, Discord, Teams) runs a reply
+ * through here before it is sent. The contract asks for plain text; this makes it so, without changing what the reply
+ * says. Shaping is channel-neutral and idempotent — it yields a small canonical form (`**anchor**`, `[label](url)`,
+ * `code`) — and each channel renders that form in its own format.
+ *
+ * - Markdown headers become plain lines.
+ * - Bold stays on at most three short anchors; the rest is plain.
+ * - Bare URLs become labelled links, named from their target: "the task", "the result", "Settings → Lead", else the host.
+ * - Internal ids (run #12, digests, r1-style project ids) are removed unless the owner asked for them. When a reply names
+ *   several of one kind (two runs, two projects), they stay: two items must never read the same.
+ * - Runs of blank lines collapse to one.
+ * Code (inline or fenced) is left exactly as written.
+ */
+export type ReplyChannel = "console" | "terminal" | "telegram" | "slack" | "discord" | "teams";
+export type ShapeOptions = {
+    /** The owner's message this reply answers: when it asks for ids, the ids stay. */
+    asked?: string;
+    /** This app's own origin (or origins: the console's address and its public one). Only a link there is named as the
+     * app's page ("the task"); every other link is named by its real host, whatever label the model wrote, so a reply can
+     * never dress a foreign link up as ours. */
+    appOrigin?: string | readonly (string | null)[] | null;
+};
+export declare const BOLD_ANCHORS = 3;
+/** A bold anchor is a few words, not a sentence. */
+export declare const BOLD_ANCHOR_CHARS = 40;
+/** Did the owner ask for ids (an id, a digest, a hash, a run number or a project's r-number)? */
+export declare function askedForIds(asked: string | undefined): boolean;
+/** What a link is called, from where it goes: the app's own task, result and settings pages by name (only on `appOrigin`); anything else by host. */
+export declare function linkLabel(url: string, appOrigin?: ShapeOptions["appOrigin"]): string;
+/**
+ * The canonical shaped reply: plain lines, at most three bold anchors, labelled links, no internal ids unless asked
+ * (or unless several of a kind would otherwise read the same), single blank lines. Idempotent: shaping a shaped reply
+ * changes nothing.
+ */
+export declare function shapeReply(text: string, options?: ShapeOptions): string;
+/**
+ * A long reply split into parts of at most `size` characters, then each part shaped: the cut is made on the reply as
+ * written, at a paragraph or line where possible and never inside code, a link or a bold anchor, so no part carries
+ * half of one. The parts share one bold budget and one rule for ids, as if the reply were shaped whole. `measure` is
+ * how long a shaped part is once the channel renders it (its own link and escape format): a part that renders past
+ * `size` is cut again, smaller. Only a single link longer than a part can exceed it, and it is never cut.
+ */
+export declare function shapeReplyParts(text: string, size: number, options?: ShapeOptions, measure?: (shaped: string) => number): string[];
+export type ReplyPiece = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "bold";
+    text: string;
+} | {
+    kind: "code";
+    text: string;
+} | {
+    kind: "link";
+    label: string;
+    url: string;
+};
+/** A shaped reply as pieces: plain text, bold anchors, inline code and labelled links. Fenced code stays text. */
+export declare function replyPieces(shaped: string): ReplyPiece[];
+/** Discord's presentation syntax, escaped; mentions are broken so nothing pings. */
+export declare const discordPlain: (text: string) => string;
+/** One line of a shaped reply as console HTML (the console lays out paragraphs and lists itself). */
+export declare function replyHtmlInline(shapedLine: string): string;
+/** A shaped reply in a channel's own text format (Telegram's formatting rides entities: see `telegramReply`). */
+export declare function renderReply(shaped: string, channel: ReplyChannel): string;
+export type TelegramEntity = {
+    type: "bold" | "code";
+    offset: number;
+    length: number;
+} | {
+    type: "text_link";
+    offset: number;
+    length: number;
+    url: string;
+};
+/** A shaped reply for Telegram: plain text plus entities (bold anchors, code, labelled links). Offsets are UTF-16, as JS strings are. */
+export declare function telegramReply(shaped: string): {
+    text: string;
+    entities: TelegramEntity[];
+};
+/** Shape and render in one step, for a surface that sends the reply as text. */
+export declare function voiceReply(text: string, channel: ReplyChannel, options?: ShapeOptions): string;
+/**
+ * The words in a reply that say something is being sent or attached ("I've attached the log", "here's the
+ * screenshot"), or null. A claim needs an attachment noun and a send verb; one whose content the reply lists itself
+ * ("I've included the files I changed: a.ts") is not a claim.
+ */
+export declare function deliverableClaim(text: string): string | null;
+/** Does the reply carry the thing itself: a link, or content quoted in a code block? */
+export declare function replyCarriesDeliverable(text: string): boolean;
+export declare const NOTHING_ATTACHED = "I couldn't attach that to this reply.";
+/** The reply without its claims of an attachment, said plainly once; whatever a claim listed stays; never the claim alone. */
+export declare function dropDeliverableClaims(text: string): string;
+/** The one repair step's words to the lead: attach it, or drop the claim. */
+export declare function deliverableRepair(claim: string): string;