toolroll 0.9.72 → 0.9.73

package/dist/subagent-tools.d.ts

@@ -56,10 +56,20 @@ export type OfferedTool = {
 export declare function offeredTools(store: Store, mate: SubagentRow): OfferedTool[];
 /** Before a turn: re-list tools whose listing is old (or never happened), so the turn sees what they offer today. A tool that can't be reached keeps its last listing. */
 export declare function refreshGrants(store: Store, mate: SubagentRow, now: Date, io: ToolIo): Promise<void>;
-/** Let a subagent use one of the project's tools. Its actions start at their defaults: reading is free, everything else asks first. */
-export declare function grantTool(store: Store, mate: SubagentRow, tool: string, by: string, now: Date, io?: ToolIo): Promise<Done>;
-/** A grant from what the tool offers (or, not reachable now, the names its last test found). */
-export declare function grantListed(store: Store, mate: SubagentRow, tool: ProjectTool, actions: ToolActionInfo[] | null, by: string, now: Date): Done;
+/** Let a subagent use one of the project's tools. Its actions start at their defaults: reading is free, everything else asks first.
+ * A grant widens what it does unasked, so it takes the person's proof (a password, or a session under Passwordless):
+ * `widening: "proved"` (chat-management.md §0a.3). */
+export declare function grantTool(store: Store, mate: SubagentRow, tool: string, by: string, now: Date, io?: ToolIo, 
+/** `stillProved`: the proof re-checked after the listing's wait, in the same synchronous step as the save. */
+options?: {
+    widening?: "proved";
+    stillProved?: () => boolean;
+}): Promise<Done>;
+/** A grant from what the tool offers (or, not reachable now, the names its last test found). Every road to a grant
+ * comes here: it takes the person's proof, and a tool it already uses keeps its rules (a grant never resets them). */
+export declare function grantListed(store: Store, mate: SubagentRow, tool: ProjectTool, actions: ToolActionInfo[] | null, by: string, now: Date, options?: {
+    widening?: "proved";
+}): Done;
 export declare function revokeTool(store: Store, mate: SubagentRow, tool: string, by: string, now?: Date): Done;
 /** Check one rule: an action the tool offers, a known use, and a limit on one of its number fields. */
 export declare function checkRule(grant: Pick<SubagentGrantRow, "tool" | "actions">, action: string, rule: {
@@ -76,7 +86,11 @@ export declare function checkRule(grant: Pick<SubagentGrantRow, "tool" | "action
     ok: false;
     said: string;
 };
-/** Set the rules for some of a granted tool's actions; the others keep theirs. */
+/** Whether `next` lets the subagent do more unasked than `before` (chat-management.md §0a.3): a higher rank, or a limit
+ * on another number or a higher one. The undo action is never authority. */
+export declare function ruleLoosens(before: ToolRule, next: ToolRule): boolean;
+/** Set the rules for some of a granted tool's actions; the others keep theirs. Loosening any of them takes the
+ * person's proof (a password, or a session under Passwordless): `widening: "proved"`; tightening never does. */
 export declare function setToolRules(store: Store, mate: SubagentRow, tool: string, changes: Record<string, {
     use: unknown;
     limit?: {
@@ -84,7 +98,9 @@ export declare function setToolRules(store: Store, mate: SubagentRow, tool: stri
         over: unknown;
     } | null;
     undo?: unknown;
-}>, by: string, now: Date): Done;
+}>, by: string, now: Date, options?: {
+    widening?: "proved";
+}): Done;
 /**
  * Make one call now: a free one, or one a person approved (exactly as they
  * saw it). What the tool said is kept on the receipt, secrets scrubbed; a

package/dist/subagent-tools.js

@@ -116,7 +116,14 @@ export async function refreshGrants(store, mate, now, io) {
         const listed = await listed_(store, tool, mate.repo, io);
         if (!listed.ok)
             continue;
-        store.saveSubagentGrant({ subagent: mate.id, tool: grant.tool, ...withActions(grant.rules, listed.actions), listedAt: now.toISOString() }, grant.updatedBy, now);
+        // The grant as it is now, after the listing's wait, in one transaction with the save: one taken away meanwhile stays
+        // gone, and only the tool's list of actions is new (rules changed meanwhile, tightened ones included, stand).
+        store.transact(() => {
+            const current = store.subagentGrant(mate.id, grant.tool);
+            if (current === null)
+                return;
+            store.saveSubagentGrant({ subagent: mate.id, tool: grant.tool, ...withActions(current.rules, listed.actions), listedAt: now.toISOString() }, current.updatedBy, now);
+        });
     }
 }
 const listed_ = (store, tool, repo, io) => (io.listTools ?? ((spec, values) => listProjectToolActions(spec, values, { timeoutMs: 60_000, omitEnv: ALL_CREDENTIAL_ENV, server: serverOf(store, repo, io) })))(tool.spec, readToolSecrets(repo, tool.name, io.toolHome));
@@ -124,18 +131,32 @@ const listed_ = (store, tool, repo, io) => (io.listTools ?? ((spec, values) => l
 const serverOf = (store, repo, io) => toolServerFor(store, repo, { ...(io.toolHome === undefined ? {} : { home: io.toolHome }), ...(io.fenceAvailable === undefined ? {} : { available: io.fenceAvailable }) });
 /** Names only, from the tool's last test: what a grant starts with when it can't be listed right now. */
 const namesOnly = (tool) => (tool.lastTest?.tools ?? []).map(name => ({ name, about: "", input: null, readOnly: false }));
-/** Let a subagent use one of the project's tools. Its actions start at their defaults: reading is free, everything else asks first. */
-export async function grantTool(store, mate, tool, by, now, io = {}) {
+/** Let a subagent use one of the project's tools. Its actions start at their defaults: reading is free, everything else asks first.
+ * A grant widens what it does unasked, so it takes the person's proof (a password, or a session under Passwordless):
+ * `widening: "proved"` (chat-management.md §0a.3). */
+export async function grantTool(store, mate, tool, by, now, io = {}, 
+/** `stillProved`: the proof re-checked after the listing's wait, in the same synchronous step as the save. */
+options = {}) {
+    if (options.widening !== "proved")
+        return grantRefused(tool);
     const found = projectToolsOf(store, mate.repo).find(one => one.name === tool);
     if (found === undefined)
         return { ok: false, said: `This project has no tool called ${tool}. Add it on the Tools page first.` };
     if (store.subagentGrant(mate.id, tool) !== null)
         return { ok: true, said: `It can already use ${tool}.` };
     const listed = await listed_(store, found, mate.repo, io);
-    return grantListed(store, mate, found, listed.ok ? listed.actions : null, by, now);
+    if (options.stillProved !== undefined && !options.stillProved())
+        return grantRefused(tool);
+    return grantListed(store, mate, found, listed.ok ? listed.actions : null, by, now, { widening: "proved" });
 }
-/** A grant from what the tool offers (or, not reachable now, the names its last test found). */
-export function grantListed(store, mate, tool, actions, by, now) {
+const grantRefused = (tool) => ({ ok: false, said: `Letting it use ${tool} takes your password. Do it on its page in Toolroll.` });
+/** A grant from what the tool offers (or, not reachable now, the names its last test found). Every road to a grant
+ * comes here: it takes the person's proof, and a tool it already uses keeps its rules (a grant never resets them). */
+export function grantListed(store, mate, tool, actions, by, now, options = {}) {
+    if (options.widening !== "proved")
+        return grantRefused(tool.name);
+    if (store.subagentGrant(mate.id, tool.name) !== null)
+        return { ok: true, said: `It can already use ${tool.name}.` };
     const offered = actions ?? namesOnly(tool);
     if (offered.length === 0)
         return { ok: false, said: `${tool.name} didn't say what it can do. Test it on the Tools page, then try again.` };
@@ -176,8 +197,19 @@ export function checkRule(grant, action, rule) {
         return { ok: false, said: "A limit is a number, 0 or more." };
     return withUndo({ use: "free", limit: { field, over } });
 }
-/** Set the rules for some of a granted tool's actions; the others keep theirs. */
-export function setToolRules(store, mate, tool, changes, by, now) {
+/** How much a rule lets a subagent do unasked: never, ask first, on its own up to a limit, on its own. */
+const ruleRank = (rule) => rule.use === "never" ? 0 : rule.use === "ask" ? 1 : rule.limit !== undefined ? 2 : 3;
+/** Whether `next` lets the subagent do more unasked than `before` (chat-management.md §0a.3): a higher rank, or a limit
+ * on another number or a higher one. The undo action is never authority. */
+export function ruleLoosens(before, next) {
+    const was = ruleRank(before), now = ruleRank(next);
+    if (now !== was)
+        return now > was;
+    return now === 2 && (next.limit.field !== before.limit.field || next.limit.over > before.limit.over);
+}
+/** Set the rules for some of a granted tool's actions; the others keep theirs. Loosening any of them takes the
+ * person's proof (a password, or a session under Passwordless): `widening: "proved"`; tightening never does. */
+export function setToolRules(store, mate, tool, changes, by, now, options = {}) {
     const grant = store.subagentGrant(mate.id, tool);
     if (grant === null)
         return { ok: false, said: `It doesn't use ${tool}. Let it use ${tool} first.` };
@@ -186,6 +218,10 @@ export function setToolRules(store, mate, tool, changes, by, now) {
         const checked = checkRule(grant, action, change);
         if (!checked.ok)
             return { ok: false, said: checked.said };
+        const info = grant.actions.find(one => one.name === action);
+        if (options.widening !== "proved" && ruleLoosens(grant.rules[action] ?? defaultRule(info), checked.rule)) {
+            return { ok: false, said: `Letting it do more with ${action} on its own takes your password. Change the rule on its page in Toolroll.` };
+        }
         rules[action] = checked.rule;
     }
     store.saveSubagentGrant({ subagent: mate.id, tool, actions: grant.actions, rules }, by, now);

package/dist/subagent-work.d.ts

@@ -65,6 +65,8 @@ export declare function answerSubagentQuestion(store: Store, id: number, answer:
     text: string | null;
     by: string;
     via: string;
+    /** The person proved themselves for this answer: only then may accepting a suggested rule loosen it. */
+    widening?: "proved";
 }, now: Date): {
     ok: true;
     said: string;

package/dist/subagent-work.js

@@ -5,7 +5,7 @@ import { claudeTurnRunner, parseSoul, readTurn, subagentActor, subagentLabel, TU
 import { passOn, shortenAsk, TEXT_LIMITS } from "./text-limits.js";
 import { LIMITS } from "./decision.js";
 import { callName, callOutcome, callWords, inputProblem, makeCall, offeredTools, refreshGrants, ruleFor } from "./subagent-tools.js";
-import { answerSuggestion, considerSuggestion, memoriesFor, remember } from "./subagent-memory.js";
+import { ACCEPT, answerSuggestion, considerSuggestion, memoriesFor, remember } from "./subagent-memory.js";
 import { replyToAsker } from "./subagent-desk.js";
 import { claudeMachineBilling } from "./spend.js";
 /** A question waits for its answer this long before the step is due again on its own: never, in practice. */
@@ -275,8 +275,11 @@ export function answerSubagentQuestion(store, id, answer, now) {
         const card = store.getFlowCard(question.card);
         // v95: a rule change it suggested to its manager. Nothing about the card waits on it.
         if (question.suggestion !== null) {
+            // A suggestion loosens a rule: accepted only with the person's proof, on its page (chat-management.md §0a.3).
+            if (choice?.id === ACCEPT && answer.widening !== "proved")
+                return { ok: false, said: "Changing this rule takes your password. Answer it on the subagent's page in Toolroll." };
             const mate = store.getSubagent(question.subagent);
-            const decided = mate === null ? { ok: false, said: "That subagent is off the team." } : answerSuggestion(store, mate, question.suggestion, { choice: choice?.id ?? null, text, by: answer.by }, now);
+            const decided = mate === null ? { ok: false, said: "That subagent is off the team." } : answerSuggestion(store, mate, question.suggestion, { choice: choice?.id ?? null, text, by: answer.by, ...(answer.widening === undefined ? {} : { widening: answer.widening }) }, now);
             store.answerSubagentQuestion(id, { choice: choice?.id ?? null, text, by: answer.by, via: answer.via }, now);
             store.addSubagentEvent({ subagent: question.subagent, card: question.card, entry: question.entry, kind: "answered", said: `${answer.by}: ${[choice?.label, text].filter(Boolean).join(" — ")}`, by: answer.by }, now);
             return decided;

package/dist/subagents-ui.js

@@ -6,7 +6,7 @@ import { MEMORY_CHARS, searchMemories } from "./subagent-memory.js";
 import { deskOf, localZone, routinesOf } from "./subagent-desk.js";
 import { weekOf, weekWords } from "./subagent-week.js";
 import { describeSchedule, parseSchedule } from "./flow-schedule.js";
-import { html, joinHtml, postForm } from "./html.js";
+import { html, joinHtml, postForm, reauth } from "./html.js";
 /** v94: the Tools section's rule rows; a limit's fields show only while "Up to a limit" is chosen. */
 export const SUBAGENT_CSS = `.subagent-tools .tool-grant{border-top:1px solid var(--so-line);padding-top:12px;margin-top:12px}.subagent-tools .tool-grant:first-of-type{border-top:0;margin-top:0;padding-top:0}.subagent-tools h3{font-size:1rem;margin:0 0 4px}.subagent-tools .tool-rule{display:grid;gap:6px;padding:10px 0;border-bottom:1px solid var(--so-line)}.subagent-tools .tool-rule:last-of-type{border-bottom:0}.subagent-tools .tool-rule .meta{display:block}.subagent-tools select,.subagent-tools input{max-width:100%;box-sizing:border-box}.subagent-tools .tool-limit{display:none;flex-wrap:wrap;align-items:center;gap:6px}.subagent-tools .tool-rule:has(option[value="limit"]:checked) .tool-limit{display:flex}.subagent-tools .tool-rule>select{width:auto;min-width:16em}.subagent-tools .tool-limit select{width:auto}.subagent-tools .tool-limit input{width:7em}.subagent-tools .tool-buttons{display:flex;flex-wrap:wrap;gap:8px;margin-top:8px}.subagent-tools button{min-height:44px}.subagent-activity li{overflow-wrap:anywhere}.subagent-memory .memory-tell,.subagent-memory .memory-search{display:flex;flex-wrap:wrap;gap:8px;align-items:flex-end;margin:0 0 12px}.subagent-memory .memory-tell textarea{flex:1 1 280px}.subagent-memory .memory-search input{flex:1 1 220px}.subagent-memory button{min-height:44px}.subagent-memories{list-style:none;padding:0;margin:0}.subagent-memories li{padding:10px 0;border-top:1px solid var(--so-line);overflow-wrap:anywhere}.subagent-memories li:first-child{border-top:0}.subagent-memories .meta{display:block;font-size:.85rem}.subagent-memories details.memory-edit{border:0;padding:0;margin:2px 0 0;background:transparent;box-shadow:none}.memory-edit summary{cursor:pointer;min-height:32px;display:inline-flex;align-items:center;font-size:.85rem;font-weight:400;color:var(--so-muted)}.tool-undo{border:0;padding:0;margin:8px 0;background:transparent;box-shadow:none}.tool-undo summary{cursor:pointer;min-height:36px;display:inline-flex;align-items:center;font-size:.9rem}.tool-undo-row{display:flex;flex-wrap:wrap;gap:6px;align-items:center;margin:6px 0}.tool-undo-row select{width:auto}.subagent-overrides,.subagent-undo{padding-left:18px}.subagent-undo li{margin:6px 0}.subagent-undo form{display:inline}.subagent-week h3{font-size:1rem;margin:14px 0 4px}.subagent-week button{min-height:44px}.subagent-routines{list-style:none;padding:0;margin:8px 0}.subagent-routines li{display:grid;gap:4px;padding:10px 0;border-top:1px solid var(--so-line)}.subagent-routines li:first-child{border-top:0}.routine-buttons{display:flex;flex-wrap:wrap;gap:8px}.routine-buttons button,.routine-add button{min-height:44px}.routine-add{display:flex;flex-wrap:wrap;gap:8px;align-items:flex-end;margin:8px 0}.routine-add label{display:grid;gap:4px;flex:1 1 200px}.routine-add label:first-of-type{flex:0 1 180px}.subagent-actions,.question-options{display:flex;flex-wrap:wrap;gap:8px;margin:8px 0}.subagent-actions form,.question-options form{margin:0}.memory-edit form{display:grid;gap:8px;margin-top:6px}.memory-buttons{display:flex;flex-wrap:wrap;gap:8px}@media(max-width:600px){.subagent-tools select,.subagent-tools input{font-size:16px}}`;
 const USES = [["free", "Do it"], ["limit", "Do it, up to a limit"], ["ask", "Ask first"], ["never", "Never"]];
@@ -38,12 +38,12 @@ function toolsSection(store, mate, canManage) {
         });
         const undoBox = undoing.length > 0 && html `<details class="tool-undo"${grant.actions.some(one => grant.rules[one.name]?.undo !== undefined) && html ` open`}><summary>Undo</summary><p class="meta">When an action has an opposite, a person can press Undo on its receipts: the opposite is called with the same input.</p>${undoing}</details>`;
         return canManage
-            ? html `<div class="tool-grant" data-tool-grant="${grant.tool}">${head}${postForm(`/settings/lead/subagents/${mate.id}/tools`, html `${rows}${undoBox}<div class="tool-buttons"><button name="op" value="rules">Save rules</button><button name="op" value="revoke" class="secondary">Stop using ${grant.tool}</button></div>`, { hidden: { tool: grant.tool } })}</div>`
+            ? html `<div class="tool-grant" data-tool-grant="${grant.tool}">${head}${postForm(`/settings/lead/subagents/${mate.id}/tools`, html `${rows}${undoBox}${reauth(html `<label>Your password <span class="meta">only to let it do more on its own</span><input type="password" name="password" autocomplete="current-password"></label>`)}<div class="tool-buttons"><button name="op" value="rules">Save rules</button><button name="op" value="revoke" class="secondary">Stop using ${grant.tool}</button></div>`, { hidden: { tool: grant.tool } })}</div>`
             : html `<div class="tool-grant" data-tool-grant="${grant.tool}">${head}<ul>${rows}</ul></div>`;
     });
     const open = tools.filter(one => !grants.some(grant => grant.tool === one.name));
     const add = !canManage ? null : tools.length === 0 ? html `<p class="meta">This project has no tools yet. <a href="${toolsPage}">Add one</a>, then let ${name} use it here.</p>`
-        : open.length === 0 ? null : postForm(`/settings/lead/subagents/${mate.id}/tools`, html `<label>Let ${name} use<select name="tool">${open.map(one => html `<option value="${one.name}">${one.name}${one.spec.about === "" ? "" : ` — ${one.spec.about.slice(0, 80)}`}</option>`)}</select></label><button>Add tool</button>`, { attrs: { class: "tool-add" }, hidden: { op: "grant" } });
+        : open.length === 0 ? null : postForm(`/settings/lead/subagents/${mate.id}/tools`, html `<label>Let ${name} use<select name="tool">${open.map(one => html `<option value="${one.name}">${one.name}${one.spec.about === "" ? "" : ` — ${one.spec.about.slice(0, 80)}`}</option>`)}</select></label>${reauth(html `<label>Your password<input type="password" name="password" autocomplete="current-password"></label>`)}<button>Add tool</button>`, { attrs: { class: "tool-add" }, hidden: { op: "grant" } });
     if (grants.length === 0 && add === null)
         return "";
     return html `<section class="card subagent-tools" id="tools"><h2>Tools</h2>${grants.length === 0 && html `<p class="meta">${name} doesn't use any tools yet. Reading starts as “Do it”; everything else asks you first.</p>`}${granted}${add}</section>`;
@@ -110,7 +110,9 @@ export function subagentPageHtml(store, mate, viewer, projectName, canManage, ap
         const flow = card === null ? null : store.getFlow(card.flow);
         const mine = question.askedOf === viewer;
         const cardLink = card === null || flow === null ? "a card" : html `<a href="/flows/${flow.id}?card=${card.id}">${card.title}</a>`;
-        const answer = mine && html `<div class="question-options">${question.options.map(one => postForm(`/settings/lead/subagents/questions/${question.id}/answer`, html `<button>${one.label}</button>`, { hidden: { choice: one.id } }))}</div>${postForm(`/settings/lead/subagents/questions/${question.id}/answer`, html `<label>Or answer in your words<textarea name="text" rows="2" maxlength="2000"></textarea></label><button>Answer</button>`, { attrs: { class: "question-reply" } })}`;
+        const answer = mine && html `<div class="question-options">${question.options.map(one => postForm(`/settings/lead/subagents/questions/${question.id}/answer`, 
+        // Accepting a looser rule it suggested takes the password (chat-management.md §0a.3).
+        question.suggestion !== null && one.id === "accept" ? html `${reauth(html `<input type="password" name="password" autocomplete="current-password" aria-label="Your password" placeholder="Your password">`)}<button>${one.label}</button>` : html `<button>${one.label}</button>`, { hidden: { choice: one.id } }))}</div>${postForm(`/settings/lead/subagents/questions/${question.id}/answer`, html `<label>Or answer in your words<textarea name="text" rows="2" maxlength="2000"></textarea></label><button>Answer</button>`, { attrs: { class: "question-reply" } })}`;
         return html `<article class="card subagent-question" data-question="${question.id}"${question.suggestion !== null && html ` data-suggestion`}><p class="meta">${question.suggestion === null ? html `About ${cardLink}` : "Suggests a rule change"} · ${when(question.createdAt)}${!mine && ` · for ${question.askedOf}`}</p><p><strong>${question.question}</strong></p>${answer}</article>`;
     });
     const zones = zonesOf(store, mate);

package/dist/telegram.d.ts

@@ -94,9 +94,14 @@ more?: readonly TelegramUpload[]) => Promise<{
 export type TelegramUpload = {
     field: "document" | "photo" | `shot${number}`;
     fileName: string;
-    contentType: "image/png" | "image/jpeg";
+    contentType: "image/png" | "image/jpeg" | "text/plain";
     bytes: Buffer;
 };
+/** A release card's full terms (release-card.ts) as the document Telegram sends with it: text this process wrote. */
+export declare const termsUpload: (file: {
+    name: string;
+    text: string;
+}) => TelegramUpload;
 export declare function createTransport(token: string, timeoutMs?: number): TelegramTransport;
 /**
  * Why this process can't reach Telegram the way the service does, or null.

package/dist/telegram.js

@@ -172,6 +172,8 @@ export function redactToken(token) {
 export function scrub(text, token) {
     return token === "" ? text : text.split(token).join(redactToken(token));
 }
+/** A release card's full terms (release-card.ts) as the document Telegram sends with it: text this process wrote. */
+export const termsUpload = (file) => ({ field: "document", fileName: file.name, contentType: "text/plain", bytes: Buffer.from(file.text, "utf8") });
 export function createTransport(token, timeoutMs = 30_000) {
     return async (method, params, signal, upload, more) => {
         const controller = new AbortController();
@@ -763,6 +765,15 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 sentAny = true;
             return answer;
         };
+        /** A release card's terms file (release-card.ts), sent before the card itself. */
+        const fileSender = async (file) => {
+            try {
+                return (await wire("sendDocument", { chat_id: binding.chatId, caption: "Every term of this release" }, undefined, termsUpload(file))).ok === true;
+            }
+            catch {
+                return false;
+            }
+        };
         // `beforeSend`: the fence before a transport call also asks the watch — until something of this delivery went out;
         // the one after a confirmed send never does, so a message Telegram accepted is recorded as delivered.
         const fence = (beforeSend = !sentAny) => {
@@ -984,7 +995,7 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 // A lone update that is not finished work goes out exactly as it always has; a later one edits it in place.
                 const lone = batch.items.length === 1 && batch.items[0].notification !== null;
                 if (batch.message === null && lone) {
-                    const sent = await deliverOne(store, botId, binding, sender, fact, clock, phoneOrigin, evidenceRoot, projects);
+                    const sent = await deliverOne(store, botId, binding, sender, fact, clock, phoneOrigin, evidenceRoot, projects, fileSender);
                     const placed = store.telegramMessageOf(fact.id, fact.destination);
                     if (placed !== null)
                         store.setChatBatchMessage(batch.id, placed, "");
@@ -996,7 +1007,7 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 if (view === null) {
                     if (readyRun !== null)
                         return { ok: true, receipt: receiptFor(botId, binding.chatId, card.messageId) };
-                    return deliverOne(store, botId, binding, sender, fact, clock, phoneOrigin, evidenceRoot, projects);
+                    return deliverOne(store, botId, binding, sender, fact, clock, phoneOrigin, evidenceRoot, projects, fileSender);
                 }
                 // A message about one result, plan, failure or pull request acts in place (chat-decide.ts); its buttons are
                 // minted only when what it offers changed, or its own were spent (Not now), so an unchanged repaint keeps the
@@ -1008,6 +1019,8 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                 let keyboard = own !== null ? [own] : viewKeyboard(phoneOrigin, view);
                 const shown = createHash("sha256").update(JSON.stringify(offer === null ? [view.text, keyboard] : [text, offerFingerprint(offer)])).digest("hex");
                 let tokens = [];
+                // A release card's terms go as a file first, on this road as on a lone delivery: no file accepted, no buttons.
+                const termsFirst = async () => offer?.file === undefined || (fileSender !== undefined && await fileSender(offer.file)) ? null : { ok: false, error: "The release's terms file wasn't accepted" };
                 // Minted unplaced: they ride a message only once it shows them, and until then the old card's buttons work.
                 const mintFor = () => {
                     if (offer === null)
@@ -1024,6 +1037,9 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                     const problem = (await readAccess()) ?? fence();
                     if (problem !== null)
                         return { ok: false, error: problem };
+                    const terms = await termsFirst();
+                    if (terms !== null)
+                        return terms;
                     mintFor();
                     const edited = await editProgress(wire, binding.chatId, batch.message, text, keyboard);
                     if (edited.ok) {
@@ -1044,6 +1060,11 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                         return edited;
                 }
                 // A new message: its buttons are minted for it, never the ones a failed edit was given.
+                if (batch.message === null) {
+                    const terms = await termsFirst();
+                    if (terms !== null)
+                        return terms;
+                }
                 mintFor();
                 const sent = await sender(text, keyboard.length === 0 ? undefined : keyboard, [fact]);
                 const placed = sent.ok ? sent.messageId : store.telegramMessageOf(fact.id, fact.destination);
@@ -1059,7 +1080,7 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
                     dropDecideTokens(store, tokens, clock());
                 return sent.ok ? { ok: true, receipt: receiptFor(botId, binding.chatId, sent.messageId) } : sent;
             }
-            return fact.kind === "acceptance-evidence" ? imageSender(fact) : deliverOne(store, botId, binding, sender, fact, clock, phoneOrigin, evidenceRoot, projects);
+            return fact.kind === "acceptance-evidence" ? imageSender(fact) : deliverOne(store, botId, binding, sender, fact, clock, phoneOrigin, evidenceRoot, projects, fileSender);
         };
         /** The lead's words (lead-voice.ts): one message; a later say within two minutes edits it in place. */
         const leadSayOutcome = async (fact) => {
@@ -1102,7 +1123,7 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             outcome = updated !== null ? updated.ok ? { ok: true, receipt: receiptFor(botId, binding.chatId, updated.messageId) } : updated
                 : rows[0].kind === "acceptance-evidence" ? await imageSender(rows[0]) : batched
                     ? await deliverDigest(botId, binding, sender, rows, digest.lastSentAt, clock, taskId => chatTitle(store, taskId))
-                    : await deliverOne(store, botId, binding, sender, rows[0], clock, phoneOrigin, evidenceRoot, projects);
+                    : await deliverOne(store, botId, binding, sender, rows[0], clock, phoneOrigin, evidenceRoot, projects, fileSender);
         }
         const finalProblem = outcome.ok ? (await readAccess()) ?? fence(false) : null;
         const settled = finalProblem === null ? outcome : { ok: false, error: finalProblem };
@@ -1180,7 +1201,7 @@ async function deliverDigest(botId, binding, sender, rows, since, clock, titleOf
     }
     return { ok: true, receipt: receiptFor(botId, binding.chatId, last) };
 }
-async function deliverOne(store, botId, binding, sender, notification, clock, phoneOrigin, evidenceRoot, projects = []) {
+async function deliverOne(store, botId, binding, sender, notification, clock, phoneOrigin, evidenceRoot, projects = [], fileSender) {
     const decisionId = /^decision:(\d+)$/.exec(notification.dedupeKey);
     const decision = decisionId === null ? null : store.getDecision(Number(decisionId[1]));
     if (decision !== null && (notification.taskRef === null || store.getRun(decision.run)?.taskRef !== notification.taskRef || (notification.run !== null && notification.run !== decision.run))) {
@@ -1272,6 +1293,13 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
         const questionKeys = asked === null ? null : telegramQuestionButtons(store, binding, asked, clock());
         const keys = flowKeys ?? choiceKeys ?? questionKeys;
         let last = null;
+        // A release card: every term goes as a file first, so Continue is offered only once it has arrived.
+        if (offer?.file !== undefined && decided !== null) {
+            if (fileSender === undefined || !await fileSender(offer.file)) {
+                dropDecideTokens(store, decided.tokens, clock());
+                return { ok: false, error: "The release's terms file wasn't accepted" };
+            }
+        }
         for (const [index, part] of parts.entries()) {
             const final = index === parts.length - 1;
             const decideKeys = decided === null ? [] : decideKeyboard(phoneOrigin, decided.rows);
@@ -2309,7 +2337,31 @@ function applyCallback(context, update, effects) {
         if (tapped.ignored === true)
             report.ignored++;
         ack(tapped.ack.slice(0, 190));
-        if (tapped.edit !== undefined)
+        // A release card's terms, as a file, before its Approve is shown (chat-management.md §0a.5): Approve appears only
+        // once Telegram has accepted this file; a refused or failed upload shows the card without it, Continue to try again.
+        if (tapped.file !== undefined && tapped.edit !== undefined && tapped.unsent !== undefined) {
+            const file = tapped.file, edit = tapped.edit, unsent = tapped.unsent;
+            effects.push(async () => {
+                let sent = false;
+                try {
+                    sent = (await transport("sendDocument", { chat_id: binding.chatId, caption: "Every term of this release, read again just now" }, undefined, termsUpload(file))).ok === true;
+                }
+                catch {
+                    sent = false;
+                }
+                const shown = sent ? edit : unsent;
+                dropDecideTokens(store, (sent ? unsent : edit).tokens, clock());
+                await transport("editMessageText", { chat_id: binding.chatId, message_id: message.message_id, text: shown.text.slice(0, 4000), link_preview_options: { is_disabled: true },
+                    reply_markup: { inline_keyboard: decideKeyboard(context.conversation?.phoneOrigin, shown.rows) } });
+            });
+        }
+        else if (tapped.file !== undefined) {
+            // A file without its gate never reaches here (chat-decide pairs them); fail closed: nothing that approves is shown.
+            if (tapped.edit !== undefined)
+                dropDecideTokens(store, tapped.edit.tokens, clock());
+            editText(`${message.text ?? ""}\n\nThis release can't be approved here. Open it in Toolroll.`.trim().slice(0, 4000), []);
+        }
+        else if (tapped.edit !== undefined)
             editText(tapped.edit.text.slice(0, 4000), decideKeyboard(context.conversation?.phoneOrigin, tapped.edit.rows));
         if (tapped.prompt !== undefined) {
             const prompt = tapped.prompt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.72",
+  "version": "0.9.73",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"