toolroll 0.9.17 → 0.9.19

package/dist/chat-quiet.js

@@ -12,6 +12,7 @@ import { asksToFinish, batchLine, chatText, chatTitle, factLinkLabel, mentions,
 import { phoneText, projectLabel } from "./telegram-status.js";
 import { isLifecycleNotification } from "./store.js";
 import { leadSubjectOf } from "./lead-voice.js";
+import { decideFallbackLink, decideTargetOf } from "./chat-decide.js";
 /** What always makes a new message, even in quiet mode: a question or approval waiting, a failure or other
  * attention fact, a result Ready for review, a security alert or release, and anything addressed to one person
  * (a sign-in or plan-limit pause, an evening digest). */
@@ -132,7 +133,8 @@ function lineOf(store, item, now, root, viewer) {
         const subject = leadSubjectOf(store, row, viewer);
         const words = chatText(phoneText(row.body === "" ? subject : `${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 },
+        const target = decideTargetOf(row);
+        return { also: [], target, link: decideFallbackLink(target) ?? (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);
@@ -156,6 +158,7 @@ function lineOf(store, item, now, root, viewer) {
     // 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") }],
+            target: pullRequest ? { kind: "merge", taskId: ref.externalId, run: run.id } : { kind: "result", taskId: ref.externalId, run: run.id },
             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: [] };
 }
@@ -168,7 +171,8 @@ export function finishedView(store, batch, now, root, viewer) {
     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 }) };
+    const target = lines[0].target ?? null;
+    return { text, entities: [], link: lines[0].link, ...(lines[0].also.length === 0 ? {} : { also: lines[0].also }), ...(target === null ? {} : { target }) };
 }
 // ---- the evening digest ----------------------------------------------------------
 const FAILURE = /fail|exhausted|fenced/;

package/dist/desktop-update.d.ts

@@ -125,6 +125,7 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
+    version?: never;
     active: boolean;
     phase: string;
     detail: string;
@@ -138,7 +139,6 @@ export declare function desktopUpdateStatus(stateDir: string): {
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
-    version?: never;
     buildId?: never;
     workDir?: never;
 } | {

package/dist/discord-api.d.ts

@@ -11,6 +11,8 @@ export type DiscordApi = (method: "GET" | "POST" | "PATCH" | "PUT", path: string
 }) => Promise<Record<string, unknown>>;
 export declare class DiscordError extends ChatDeliveryError {
 }
+/** Discord's 403: the bot may not do this here (for a file, no Attach Files permission). */
+export declare const DISCORD_REFUSED = "Discord refused access. Check the app and direct-message permissions.";
 export declare function discordApi(token: string, fetcher?: typeof fetch): DiscordApi;
 export declare const discordCredentialFile: (dir: string) => string;
 export declare function loadDiscordCredentials(dir: string): DiscordCredentials | null;

package/dist/discord-api.js

@@ -8,6 +8,8 @@ export { object };
 export const discordId = (v) => typeof v === "string" && /^[1-9][0-9]{16,19}$/.test(v);
 export class DiscordError extends ChatDeliveryError {
 }
+/** Discord's 403: the bot may not do this here (for a file, no Attach Files permission). */
+export const DISCORD_REFUSED = "Discord refused access. Check the app and direct-message permissions.";
 export function discordApi(token, fetcher = fetch) {
     return async (method, path, body, file) => {
         // Only relative API routes; never send the bot credential to supplied URLs.
@@ -56,7 +58,7 @@ export function discordApi(token, fetcher = fetch) {
             const message = response.status === 401
                 ? "Discord access expired. Disconnect and reconnect with the current bot token."
                 : response.status === 403
-                    ? "Discord refused access. Check the app and direct-message permissions."
+                    ? DISCORD_REFUSED
                     : response.status === 404
                         ? "The Discord message or conversation is unavailable. Open the saved chat."
                         : response.status === 413

package/dist/discord-chat.js

@@ -2,6 +2,7 @@
 import { chatQuestionButtons } from "./teammate-question.js";
 import { chatAskButtons } from "./chat-ask.js";
 import { chatFlowButtons } from "./chat-flow.js";
+import { refuseResultShots, resultShotsPruned, shotWaitsUntil } from "./result-shots.js";
 import { channelInbox } from "./chat-inbox.js";
 import { roomCommand } from "./chat-rooms.js";
 import { ChatState, ChatDeliveryError, chatHash, } from "./chat-delivery-state.js";
@@ -12,7 +13,7 @@ import { discordPlain, renderReply } from "./reply-shape.js";
 import { WARM_EMOJI } from "./chat-warmth.js";
 import { proposalPreview, proposalLink, proposalOutcomeText, armedCardText, armedYesLabel, } from "./chat-channel.js";
 import { resultImageFileName, safeResultImageCaption, verifyResultImage, } from "./chat-evidence.js";
-import { discordId, discordMember, DiscordError, } from "./discord-api.js";
+import { discordId, discordMember, DiscordError, DISCORD_REFUSED, } from "./discord-api.js";
 export const discordDelivery = (options) => ({
     ...options,
     state: new ChatState(options.store, "discord"),
@@ -205,6 +206,18 @@ export async function deliverDiscordPart(options) {
             !repos.includes(store.lookupRef(content.task)?.repo ?? ""))
             throw new DiscordError("Connected projects changed");
         let text = content.text, buttons = [], file;
+        if (content.image && content.shot && resultShotsPruned(options.evidenceRoot, content.image.run)) {
+            state.prepare("UPDATE chat_part SET state='dropped',problem='Removed by retention' WHERE id=?").run(row.id);
+            return true;
+        }
+        // A screenshot sent with a result replies to that result's message once it is placed, and waits until then.
+        const result = content.shot?.follows == null ? undefined : state.prepare("SELECT message,state,next_at FROM chat_part WHERE id=?").get(content.shot.follows);
+        if (result !== undefined && !discordId(result["message"]) && result["state"] === "pending") {
+            state.prepare("UPDATE chat_part SET next_at=? WHERE id=?").run(shotWaitsUntil(result["next_at"], now), row.id);
+            return true;
+        }
+        const follows = result?.["message"];
+        const thread = discordId(follows) ? String(follows) : event.thread;
         if (content.image) {
             const image = verifyResultImage(store, options.evidenceRoot, repos, content.image);
             if (!image.ok)
@@ -359,9 +372,9 @@ export async function deliverDiscordPart(options) {
         if (!target) {
             args.nonce = nonce;
             args.enforce_nonce = true;
-            if (discordId(event.thread))
+            if (discordId(thread))
                 args.message_reference = {
-                    message_id: event.thread,
+                    message_id: thread,
                     channel_id: destination,
                     fail_if_not_exists: false,
                 };
@@ -385,6 +398,12 @@ export async function deliverDiscordPart(options) {
         return true;
     }
     catch (error) {
+        // No permission to attach files here: one plain line instead of the result's screenshots.
+        const content = JSON.parse(row.payload);
+        if (content.image && content.shot && error instanceof DiscordError && error.code === DISCORD_REFUSED) {
+            refuseResultShots(state, store, row, content, "Discord", options.clock?.() ?? new Date());
+            return true;
+        }
         const problem = error instanceof ChatDeliveryError
             ? error
             : new DiscordError("Discord delivery is waiting to retry", 15_000, true);

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);
@@ -12238,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}`}`;
@@ -12248,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);
@@ -12274,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/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/result-shots.d.ts

@@ -0,0 +1,53 @@
+import { type Notification, type ResultScreenshots, type Store } from "./store.js";
+import type { ChatContent, ChatState } from "./chat-delivery-state.js";
+/** "Up to 4": the most screenshots one result ever sends. */
+export declare const RESULT_SHOTS_MAX = 4;
+/** The choices in the order Settings and the CLI show them. */
+export declare const RESULT_SHOT_CHOICES: readonly (readonly [ResultScreenshots, string])[];
+export declare function resultShotLimit(choice: ResultScreenshots): number;
+export type ResultShot = {
+    artifact: number;
+    sha256: string;
+    bytes: Buffer;
+    format: "png" | "jpeg";
+    fileName: string;
+    /** Plain words: the first screenshot's carry the task ("Is the site current? · the home page on a phone"). */
+    caption: string;
+    /** Within Telegram's photo limits, so it shows an inline preview. */
+    photo: boolean;
+};
+export type ResultShotsPlan = 
+/** Nothing to send and nothing to say: off, pruned by retention, none saved, or all already sent. */
+{
+    kind: "none";
+    why: "off" | "pruned" | "none" | "sent";
+}
+/** One plain line instead of any screenshot. */
+ | {
+    kind: "line";
+    text: string;
+} | {
+    kind: "send";
+    taskId: string;
+    run: number;
+    shots: ResultShot[];
+};
+/**
+ * What one person's screenshots row may send now, to a chat that reaches
+ * `repos`. `sent`: screenshots this destination already has, never sent again.
+ * Every byte returned was verified this instant; a channel uploads them with
+ * no wait in between, or asks again.
+ */
+export declare function resultShotsFor(store: Store, evidenceRoot: string | undefined, repos: readonly string[], row: Pick<Notification, "kind" | "recipient" | "taskId" | "taskRef" | "run">, sent?: ReadonlySet<number>): ResultShotsPlan;
+/** A screenshot whose result message is not posted yet waits for that message's own next try (at least a second). */
+export declare function shotWaitsUntil(resultNextAt: unknown, now: Date): string;
+/** Retention removed this result's files: its screenshots go quietly, never as a complaint. */
+export declare function resultShotsPruned(evidenceRoot: string, run: number): boolean;
+/**
+ * The chat app refused the upload (no file permission there): this part becomes one plain line and the result's
+ * other screenshots in the same message are dropped, so the person reads one line, not one per screenshot.
+ */
+export declare function refuseResultShots(state: Pick<ChatState, "prepare">, store: Store, part: {
+    id: number;
+    event: string;
+}, content: ChatContent, app: string, now: Date): void;

package/dist/result-shots.js

@@ -0,0 +1,124 @@
+/**
+ * Screenshots with results: a person can choose to get a result's saved
+ * screenshots in their chat app right after its "ready" (or failed) message —
+ * Off (the default), the first one, or up to four.
+ *
+ * The store records one row per result and person (`RESULT_SHOTS_KIND`) when
+ * the result message is made; every transport asks here, at send time, what
+ * that row may carry. The checks are the acceptance-evidence sender's: the
+ * task is in the projects this chat may reach now, the result is still the
+ * task's current one, and each file verifies against its recorded sha256
+ * under the evidence root. A failure is one plain line and nothing else; a
+ * result whose files retention already removed sends nothing and says
+ * nothing. The choice is read again here, so turning it off stops what has
+ * not gone yet, and never more than it allows is sent.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { imageDimensions, readVerifiedProofForRun, RETENTION_NOTE } from "./evidence.js";
+import { resultImageFileName, verifyResultImage } from "./chat-evidence.js";
+import { publicChatText } from "./chat-display.js";
+import { chatTitle } from "./chat-voice.js";
+import { RESULT_SHOTS_KIND } from "./store.js";
+/** "Up to 4": the most screenshots one result ever sends. */
+export const RESULT_SHOTS_MAX = 4;
+/** The choices in the order Settings and the CLI show them. */
+export const RESULT_SHOT_CHOICES = [["off", "Off"], ["first", "First one"], ["all", "Up to 4"]];
+export function resultShotLimit(choice) {
+    return choice === "first" ? 1 : choice === "all" ? RESULT_SHOTS_MAX : 0;
+}
+/** Telegram's own photo limits (Bot API sendPhoto, checked 2026-10-03): over them, a screenshot goes as a document. */
+const PHOTO_MAX_BYTES = 10 * 1024 * 1024;
+const PHOTO_MAX_SIDES = 10_000;
+const PHOTO_MAX_RATIO = 20;
+const SCREENSHOT_CAPTURE = /^agent-claimed screenshot at (.+) \(validated (?:png|jpeg)\)/;
+/** A screenshot's own caption from the result's proof, in plain words; null when it has none fit to show. */
+function ownCaptions(store, root, run) {
+    const proof = readVerifiedProofForRun(store, root, run);
+    const captions = new Map();
+    if (proof === null || !proof.ok)
+        return captions;
+    for (const shot of proof.proof.screenshots) {
+        const words = publicChatText(shot.caption, 200).trim();
+        if (words !== "" && !words.includes("[sensitive text hidden]"))
+            captions.set(shot.path, words);
+    }
+    return captions;
+}
+function isPhoto(bytes, format) {
+    const size = imageDimensions(bytes, format);
+    if (size === null || size.width === 0 || size.height === 0)
+        return false;
+    return bytes.length <= PHOTO_MAX_BYTES && size.width + size.height <= PHOTO_MAX_SIDES
+        && Math.max(size.width, size.height) / Math.min(size.width, size.height) <= PHOTO_MAX_RATIO;
+}
+/**
+ * What one person's screenshots row may send now, to a chat that reaches
+ * `repos`. `sent`: screenshots this destination already has, never sent again.
+ * Every byte returned was verified this instant; a channel uploads them with
+ * no wait in between, or asks again.
+ */
+export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()) {
+    if (row.kind !== RESULT_SHOTS_KIND || row.recipient === null || row.taskId === null || row.taskRef === null || row.run === null)
+        return { kind: "none", why: "none" };
+    const limit = resultShotLimit(store.notificationPreference(row.recipient).screenshots);
+    if (limit === 0)
+        return { kind: "none", why: "off" };
+    const title = chatTitle(store, row.taskId);
+    const line = (why) => ({ kind: "line", text: `Screenshots for ${title} weren't sent: ${why}.` });
+    if (evidenceRoot === undefined)
+        return line("saved files can't be read from here");
+    // Retention removed this result's files: nothing to show, and nothing worth saying.
+    if (existsSync(join(evidenceRoot, String(row.run), RETENTION_NOTE)))
+        return { kind: "none", why: "pruned" };
+    const ref = store.lookupRef(row.taskId);
+    if (ref?.repo == null || !repos.includes(ref.repo))
+        return line("the result is outside your connected projects now");
+    const family = store.taskFamilyOf(row.taskId, repos, false);
+    const latest = store.runsFor(row.taskRef).find(one => one.finishedAt !== null && ["builder", "repair", "scout"].includes(one.role));
+    if (family?.current.id !== row.taskId || latest?.id !== row.run)
+        return line("a newer result replaced this one");
+    const chosen = store.artifactsFor(row.run).filter(one => one.kind === "screenshot").slice(0, limit);
+    if (chosen.length === 0)
+        return { kind: "none", why: "none" };
+    const captions = ownCaptions(store, evidenceRoot, row.run);
+    const shots = [];
+    for (const [index, artifact] of chosen.entries()) {
+        const verified = verifyResultImage(store, evidenceRoot, repos, { taskId: row.taskId, run: row.run, artifact: artifact.id, sha256: artifact.sha256 });
+        if (!verified.ok) {
+            // Removed by retention between the check above and now: still nothing to say.
+            if (existsSync(join(evidenceRoot, String(row.run), RETENTION_NOTE)))
+                return { kind: "none", why: "pruned" };
+            return line(verified.problem);
+        }
+        const own = captions.get(SCREENSHOT_CAPTURE.exec(artifact.capture)?.[1] ?? "") ?? null;
+        shots.push({
+            artifact: artifact.id, sha256: artifact.sha256, bytes: verified.bytes, format: verified.format,
+            fileName: resultImageFileName(row.taskId, row.run, artifact.id, verified.format),
+            caption: index === 0 ? (own === null ? title : `${title} · ${own}`) : own ?? `${title} · screenshot ${index + 1}`,
+            photo: isPhoto(verified.bytes, verified.format),
+        });
+    }
+    const remaining = shots.filter(one => !sent.has(one.artifact));
+    return remaining.length === 0 ? { kind: "none", why: "sent" } : { kind: "send", taskId: row.taskId, run: row.run, shots: remaining };
+}
+/** A screenshot whose result message is not posted yet waits for that message's own next try (at least a second). */
+export function shotWaitsUntil(resultNextAt, now) {
+    const soonest = new Date(now.getTime() + 1_000).toISOString();
+    return typeof resultNextAt === "string" && resultNextAt > soonest ? resultNextAt : soonest;
+}
+/** Retention removed this result's files: its screenshots go quietly, never as a complaint. */
+export function resultShotsPruned(evidenceRoot, run) {
+    return existsSync(join(evidenceRoot, String(run), RETENTION_NOTE));
+}
+/**
+ * The chat app refused the upload (no file permission there): this part becomes one plain line and the result's
+ * other screenshots in the same message are dropped, so the person reads one line, not one per screenshot.
+ */
+export function refuseResultShots(state, store, part, content, app, now) {
+    const title = chatTitle(store, content.image?.taskId ?? content.task ?? "");
+    const line = { text: `Screenshots for ${title} weren't sent: the ${app} app isn't allowed to upload files here.`,
+        ...(content.task === undefined ? {} : { task: content.task }), ...(content.run === undefined ? {} : { run: content.run }) };
+    state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL,problem=NULL,file=NULL,uploaded=0,uncertain=0,created=? WHERE id=?").run(JSON.stringify(line), now.toISOString(), part.id);
+    state.prepare("UPDATE chat_part SET state='dropped',problem='Uploads are not allowed here' WHERE event=? AND id<>? AND state='pending'").run(part.event, part.id);
+}

package/dist/serve.js

@@ -93,6 +93,7 @@ import { DISCLOSURE_CSS } from "./disclosure.js";
 import { styleAsset } from "./style-asset.js";
 import { MOBILE_VIEWPORT_SCRIPT } from "./mobile-viewport.js";
 import { authorizePlanUnderMode, applyModeToNewFiling, planAutoPending } from "./plan-auto.js";
+import { permissionPlainWords } from "./chat-decide.js";
 import { LEDGER_CSV_HEADER, ledgerCsvRows } from "./ledger-csv.js";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
@@ -188,7 +189,8 @@ import { dirname } from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { loadOrCreateVapidKeys, validatePushEndpoint } from "./push.js";
 import { parseGithubRepo, previewGithubRepo, cloneGithubRepo, listGithubRepos, isLargeRepo } from "./onboard.js";
-import { verifiedAuthor, LEAD_THREAD, isDigestTime, MATE_ASK_OTHER } from "./store.js";
+import { verifiedAuthor, LEAD_THREAD, isDigestTime, RESULT_SCREENSHOTS, MATE_ASK_OTHER } from "./store.js";
+import { RESULT_SHOT_CHOICES } from "./result-shots.js";
 import { digestTimes } from "./digest-times.js";
 import { updateRepos, addRepos, removeRepos } from "./repos.js";
 import { run as execRun } from "./exec.js";
@@ -2648,6 +2650,10 @@ export function createDecisionServer(options) {
                         `<option value="0">wait for my approval</option>` +
                         `<option value="1">auto-approve plans that preserve my filed contract</option>` +
                         `</select><span class="meta">Requires automatic filing approval. File the goal, paths, and acceptance criteria upfront. Changed scope and unanswered questions still pause.</span></label>`,
+                    `<label>From my chat app<select name="chat-approve">` +
+                        `<option value="">approve plans and merges here, with my password (the default)</option>` +
+                        `<option value="1">approve plans and merge ready pull requests from my paired chat, two taps each</option>` +
+                        `</select><span class="meta">Plans that widen permissions, exceed the attempt cap or touch protected paths still open Toolroll.</span></label>`,
                     `<label>If a subscription runs out<select name="allow-paid-fallback">` +
                         `<option value="">never switch to a paid API key on its own (the default, every preset)</option>` +
                         `<option value="1">allow the approved fallback — spend moves to that account</option>` +
@@ -4231,7 +4237,7 @@ export function createDecisionServer(options) {
                 return at === null || since === null ? null : firstResultWords(since, at);
             })(), (() => {
                 const chosen = store.notificationPreference(who.name);
-                return { mode: chosen.mode, digestAt: chosen.digestAt, projects: notificationProjects(store, who.name) };
+                return { mode: chosen.mode, digestAt: chosen.digestAt, screenshots: chosen.screenshots, projects: notificationProjects(store, who.name) };
             })()));
         }
         if (url.pathname === "/push/key") {
@@ -8236,16 +8242,21 @@ export function createDecisionServer(options) {
         }
         if (url.pathname === "/settings/notifications") {
             // Each person's own choice: a closed list of modes and a 24-hour HH:MM, or off.
-            const mode = body.get("mode"), time = (body.get("digest") ?? "").trim();
+            const mode = body.get("mode"), time = (body.get("digest") ?? "").trim(), shots = body.get("screenshots");
             if (mode !== null && mode !== "quiet" && mode !== "all")
                 return refuse(response, who, 400, "choose Only when I'm needed or Every step", "/settings");
             if (time !== "" && time !== "off" && !isDigestTime(time))
                 return refuse(response, who, 400, "the evening digest time is HH:MM, or off", "/settings");
+            if (shots !== null && !RESULT_SCREENSHOTS.includes(shots))
+                return refuse(response, who, 400, "choose Off, First one or Up to 4", "/settings");
             const before = store.notificationPreference(who.name);
-            const after = store.setNotificationPreference(who.name, { ...(mode === null ? {} : { mode }), ...(time === "" ? {} : { digestAt: time === "off" ? null : time }) }, who.name, now);
+            const after = store.setNotificationPreference(who.name, { ...(mode === null ? {} : { mode }), ...(time === "" ? {} : { digestAt: time === "off" ? null : time }),
+                ...(shots === null ? {} : { screenshots: shots }) }, who.name, now);
             const said = after.mode !== before.mode
                 ? after.mode === "quiet" ? "Chats now message you only when you're needed." : "Chats now message you at every step."
-                : after.digestAt === null ? "Evening digest off." : `Evening digest at ${after.digestAt}.`;
+                : after.screenshots !== before.screenshots
+                    ? after.screenshots === "off" ? "Results arrive without screenshots." : `Results arrive with ${after.screenshots === "first" ? "their first screenshot" : "up to 4 screenshots"}.`
+                    : after.digestAt === null ? "Evening digest off." : `Evening digest at ${after.digestAt}.`;
             return redirect(response, `/settings?said=${encodeURIComponent(said)}`);
         }
         if (url.pathname === "/settings/notifications/mute") {
@@ -8712,6 +8723,8 @@ export function createDecisionServer(options) {
                 // attempt cap it carries is meaningless without it.
                 repairAuto: false,
                 repairMaxAttempts: 0,
+                // Approving from the paired chat: only the explicit choice grants it.
+                chatApprove: body.get("chat-approve") === "1",
                 publication: body.get("publication") === "automerge" ? "automerge" : "notify",
             };
             if (["review-auto", "review-retry-auto", "repair-auto"].some(field => body.get(field) === "1")) {
@@ -8733,7 +8746,7 @@ export function createDecisionServer(options) {
                     `<input type="hidden" name="csrf" value="${escape(who.session.csrf)}">` +
                     `<input type="hidden" name="nonce" value="${escape(nonce)}">` +
                     `<input type="hidden" name="digest" value="${escape(digest)}">` +
-                    ["name", "days", "publication", "auto-approve", "plan-auto", "allow-paid-fallback"]
+                    ["name", "days", "publication", "auto-approve", "plan-auto", "chat-approve", "allow-paid-fallback"]
                         .map(field => `<input type="hidden" name="${field}" value="${escape(body.get(field) ?? "")}">`)
                         .join("") +
                     `<input type="hidden" name="expiry" value="${escape(expiry)}">` +
@@ -12543,7 +12556,7 @@ function approvalSheetHtml(input) {
     // What the yes allows, in plain words, right above it: the agent's
     // permissions, the per-attempt limit, and an earlier version still running.
     const allowing = [];
-    const allowed = permissionPlainWordsOf(scope.profile);
+    const allowed = permissionPlainWords(scope.profile);
     if (allowed !== null)
         allowing.push(allowed);
     if (raceTerms === null)
@@ -12694,20 +12707,6 @@ class PermissionsWouldChange extends Error {
 }
 /** Evidence kinds in plain words, for the signed criteria in Details. */
 const EVIDENCE_PLAIN = { check: "the project check", screenshot: "screenshots", "changed-path": "changed files", "manual-review": "your own check" };
-/** What an agent may do on its own, in a few plain words. */
-function permissionPlainWordsOf(profile) {
-    if (profile === null || profile === undefined)
-        return null;
-    const full = "full access, nothing asks first";
-    if (profile.provider === "claude") {
-        return profile.permissionArgv === "bypassPermissions" ? full
-            : profile.permissionArgv === "auto" ? "file edits and routine commands; anything risky stops"
-                : "file edits only; commands are refused";
-    }
-    if (profile.provider === "gemini")
-        return profile.approvalArgv === "yolo" ? full : "file edits only; other tools are refused";
-    return profile.sandboxMode === "danger-full-access" ? full : "file edits and commands inside the project only";
-}
 /** The permission choice a sealed profile carries, as the scope form names it. */
 function permissionModeOfProfile(profile) {
     if (profile === null || profile === undefined)
@@ -23941,6 +23940,9 @@ function settingsPage(chrome, existing, hasEnv, csrf, problem, messaging = null,
                 digestTimes(chatNotices.digestAt).map(([value, label]) => `<option value="${value}"${value === (chatNotices.digestAt ?? "off") ? " selected" : ""}>${label}</option>`).join("") +
                 `</select></label>`,
             `<p class="meta">One message: what finished, what waits, what failed.</p>`,
+            `<label>Screenshots with results<select name="screenshots">` +
+                RESULT_SHOT_CHOICES.map(([value, label]) => `<option value="${value}"${value === (chatNotices.screenshots ?? "off") ? " selected" : ""}>${label}</option>`).join("") +
+                `</select></label>`,
             `<button type="submit">Save</button>`,
             `</form>`,
             ...((chatNotices.projects ?? []).length === 0 ? [] : [