toolroll 0.9.36 → 0.9.38

package/dist/browser-crew.js

@@ -38,6 +38,10 @@ export function browserCrewFromIndex(page, conversationId) {
     const link = (href) => conversationId && href.startsWith('/chat?') ? href + '&conversation=' + encodeURIComponent(conversationId) : href;
     const rows = page.items.map(summary => {
         const status = summary.status;
+        // Keep the server's sentence intact; ignore only empty or repeated badge words.
+        const words = (text) => text.trim().replace(/\s+/g, ' ').replace(/[.!?]+$/, '').toLowerCase();
+        const detail = ['Waiting', 'Failed', 'Needs you'].includes(status.label)
+            && words(status.detail) !== '' && words(status.detail) !== words(status.label) ? status.detail : undefined;
         const resultHref = summary.resultRunId === null || summary.resultTaskId === null || (summary.resultOutcome !== 'built' && summary.resultOutcome !== 'no-change')
             ? null : chatResultHref(summary.resultTaskId, summary.resultRunId);
         const href = chatControlHref('task', summary.rootId);
@@ -48,6 +52,7 @@ export function browserCrewFromIndex(page, conversationId) {
             state: summary.assignmentState, label: status.label, tone: status.tone, href: link(href), resultHref: resultHref === null ? null : link(resultHref),
             action: action === null || actionHref === null ? null : { label: action.label, href: link(actionHref) },
             updatedAt: summary.updatedAt,
+            ...(detail === undefined ? {} : { detail }),
             ...(summary.lead === undefined ? {} : { lead: summary.lead }),
         };
         return { item, rank: status.rank };

package/dist/browser-workspace.d.ts

@@ -49,6 +49,8 @@ export type BrowserCrewItem = {
     } | null;
     /** When the task family last changed (the index's own sort time), shown as the row's age. */
     updatedAt: string;
+    /** The server's status detail, when Waiting, Failed or Needs you adds to its badge. */
+    detail?: string;
     /** "<name> is on it.": the person's own lead took it on, by the name they gave it. */
     lead?: string;
 };

package/dist/build-review.d.ts

@@ -1,6 +1,6 @@
 import type { Store } from "./store.js";
 import type { Runner } from "./builder.js";
-import type { BuildFinding } from "./review-switch.js";
+import { type BuildFinding } from "./contracts/review-findings.js";
 export { buildReviewOf, buildReviewHeadline, buildReviewLines, findingWords, type BuildReviewView } from "./review-switch.js";
 export declare const AUTOMATIC_REVIEWER = "automatic review";
 /**

package/dist/build-review.js

@@ -29,6 +29,7 @@ import { runCheckLevel } from "./check-levels.js";
 import { requestResultChanges } from "./result-actions.js";
 import { revisionSourceOf } from "./result-review.js";
 import { parseBuildFindings, REVIEW_PATCH_NAME } from "./reviewer.js";
+import { FINDINGS_VERSION } from "./contracts/review-findings.js";
 import { heartbeat as runnerHeartbeat } from "./runner.js";
 import { TELEGRAM_TOKEN_ENVS } from "./names.js";
 import { CLAUDE_LIMITS } from "./scope.js";
@@ -90,7 +91,7 @@ function queueLocked(store, repo, runId, root, now) {
 }
 function settle(store, runId, state, fields, now) {
     store.handle.prepare("UPDATE build_review SET state = ?, findings_json = ?, reason = ?, sent_back_as = ?, finished_at = ? WHERE run = ? AND state = 'pending'")
-        .run(state, fields.findings === undefined ? null : JSON.stringify({ version: 1, findings: fields.findings }), fields.reason ?? null, fields.sentBackAs ?? null, now.toISOString(), runId);
+        .run(state, fields.findings === undefined ? null : JSON.stringify({ version: FINDINGS_VERSION, findings: fields.findings }), fields.reason ?? null, fields.sentBackAs ?? null, now.toISOString(), runId);
     store.bumpWake();
 }
 /** Only the first automatic send-back in a task family: its revision's HIGH goes to the person. */

package/dist/chat-acceptance.d.ts

@@ -39,7 +39,7 @@ export declare function readAcceptanceEvidence(store: Store, who: VerifiedApprov
             requirement: string | null;
             state: string;
             details: (string | null)[];
-            requiredEvidence: readonly import("./scope.js").EvidenceKind[];
+            requiredEvidence: readonly ("changed-path" | "check" | "manual-review" | "screenshot")[];
             reviewer: {
                 judgement: import("./proof.js").CriterionJudgementWord;
                 note: string | null;

package/dist/chat-actions.d.ts

@@ -1,5 +1,7 @@
 import { type Store } from "./store.js";
 import { type VerifiedApprover } from "./principal.js";
+import { CHAT_ACTION_FIELDS, type SharedAction } from "./contracts/chat-actions.js";
+export { CHAT_ACTION_FIELDS, type SharedAction };
 export declare const CHAT_ACTIONS: {
     readonly skill_import: {
         readonly label: "Add skill";
@@ -235,20 +237,11 @@ export declare const CHALLENGE_ACTIONS: ReadonlySet<ChatAction>;
 /** Actions about the person themselves, in no project: their card carries no project (repo ""). */
 export declare const OWNER_ACTIONS: ReadonlySet<ChatAction>;
 export declare function isChatAction(value: unknown): value is ChatAction;
-export type SharedAction = {
-    operation: ChatAction;
-    request: Record<string, unknown>;
-    repo: string;
-    title: string;
-    terms: string[];
-    stamp: string;
-    state: Record<string, unknown>;
-};
-export declare const CHAT_ACTION_FIELDS: Record<ChatAction, readonly string[]>;
 /** No writes, including at preview. Store-derived snapshots are never accepted
  * from a model. Rebuilding the same request before execution catches changes. */
 export declare function prepareSharedAction(store: Store, who: VerifiedApprover, operation: ChatAction, input: Record<string, unknown>, root?: string, now?: Date): SharedAction;
-export declare function sharedActionPayload(value: Record<string, unknown>): SharedAction | null;
+/** A saved proposal's action, read by its schema (contracts/chat-actions.ts); null when it can't be read. */
+export declare function sharedActionPayload(value: unknown): SharedAction | null;
 export declare function sharedActionNeedsReview(action: SharedAction): boolean;
 /** Whether a paired phone may confirm this protected action behind its own
  * explicit challenge: the action is on the challenge list, needs no
@@ -256,7 +249,20 @@ export declare function sharedActionNeedsReview(action: SharedAction): boolean;
 export declare function sharedActionAllowsChallenge(action: SharedAction): boolean;
 export declare function sharedActionReviewPath(id: number): string;
 export declare function mintSharedActionReview(store: Store, who: VerifiedApprover, id: number, root: string, now: Date): {
-    payload: SharedAction;
+    payload: {
+        version: 1;
+        operation: "decision_record" | "decision_retire" | "flow_card_add" | "flow_card_approve" | "flow_card_assign" | "flow_card_cancel" | "flow_card_choose" | "flow_card_comment" | "flow_card_move" | "flow_card_send_back" | "flow_card_watch" | "flow_create" | "flow_edit" | "flow_script_save" | "flow_starter" | "flow_trigger_add" | "flow_trigger_pause" | "flow_trigger_remove" | "flow_trigger_resume" | "kit_setup" | "knowledge_instructions" | "knowledge_remove" | "knowledge_restore" | "knowledge_save" | "lead_about_you" | "result_accept" | "scope_approve" | "skill_disable" | "skill_enable" | "skill_import" | "skill_restore" | "skill_test" | "task_cancel" | "task_resume" | "teammate_answer" | "teammate_create" | "teammate_memory" | "teammate_note" | "teammate_routine" | "teammate_soul" | "teammate_state" | "teammate_tools" | "teammate_undo" | "tool_add" | "tool_remove";
+        request: {
+            [x: string]: unknown;
+        };
+        repo: string;
+        title: string;
+        terms: string[];
+        stamp: string;
+        state: {
+            [x: string]: unknown;
+        };
+    };
     nonce: string;
 };
 export type SharedActionOptions = {

package/dist/chat-actions.js

@@ -35,6 +35,8 @@ import { starterFlowOf, starterOf, startersFor, starterTerms, STARTER_FLOWS, swi
 import { answerTeammateQuestion } from "./teammate-work.js";
 import { callWords, checkRule, defaultRule, grantListed, revokeTool, ruleWords, setToolRules } from "./teammate-tools.js";
 import { aboutYouOf, checkAboutYouLine, saveAboutYou, withAboutYouLine } from "./lead-about.js";
+import { CHAT_ACTION_FIELDS, readChatActionRequest, readSharedAction, SHARED_ACTION_VERSION } from "./contracts/chat-actions.js";
+export { CHAT_ACTION_FIELDS };
 /** A tool from the lead's card: a common tool by its id, or the operator's own program or address. */
 function toolSpecFromRequest(input) {
     if (input["catalog"] !== undefined) {
@@ -118,6 +120,9 @@ export const CHAT_ACTIONS = {
     task_cancel: { label: "Cancel task", protected: true, password: false },
     task_resume: { label: "Resume task", protected: true, password: true },
 };
+// Every action has a schema (contracts/chat-actions.ts) and every schema an action: a mismatch fails to compile.
+const SAME_ACTIONS = true;
+void SAME_ACTIONS;
 /** Protected actions a paired phone may confirm behind its own explicit
  * yes/cancel challenge instead of the console's secure screen. Password
  * actions and long or redacted terms never qualify. */
@@ -128,53 +133,6 @@ export function isChatAction(value) {
     return typeof value === "string" && Object.hasOwn(CHAT_ACTIONS, value);
 }
 const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-export const CHAT_ACTION_FIELDS = {
-    skill_import: ["repo", "content", "files"],
-    skill_enable: ["repo", "version"],
-    skill_disable: ["repo", "version"],
-    skill_restore: ["repo", "restore"],
-    skill_test: ["repo", "version", "sample", "nonce"],
-    knowledge_instructions: ["repo", "instructions"],
-    knowledge_save: ["repo", "title", "content", "id"],
-    knowledge_remove: ["repo", "id"],
-    knowledge_restore: ["repo", "restore"],
-    tool_add: ["repo", "catalog", "name", "command", "args", "url", "secrets", "about"],
-    tool_remove: ["repo", "name"],
-    flow_create: ["repo", "name", "definition", "trigger"],
-    flow_starter: ["repo", "starter"],
-    flow_edit: ["flow", "name", "definition"],
-    flow_card_add: ["flow", "title", "description", "zone"],
-    flow_card_move: ["card", "zone"],
-    flow_card_approve: ["card", "note"],
-    flow_card_send_back: ["card", "note"],
-    flow_card_choose: ["card", "choice", "note"],
-    flow_card_cancel: ["card"],
-    flow_card_comment: ["card", "note"],
-    flow_card_assign: ["card", "owner"],
-    flow_card_watch: ["card", "watching"],
-    flow_script_save: ["repo", "script"],
-    flow_trigger_add: ["flow", "trigger"],
-    flow_trigger_pause: ["trigger"],
-    flow_trigger_resume: ["trigger"],
-    flow_trigger_remove: ["trigger"],
-    teammate_create: ["repo", "template", "name", "soul"],
-    teammate_soul: ["teammate", "soul"],
-    teammate_state: ["teammate", "state"],
-    teammate_note: ["teammate", "note"],
-    teammate_answer: ["question", "choice", "text"],
-    teammate_tools: ["teammate", "tool", "change", "action", "use", "limitField", "limitOver", "undoWith"],
-    teammate_memory: ["teammate", "memory", "change", "text"],
-    teammate_routine: ["teammate", "change", "routine", "schedule", "text"],
-    teammate_undo: ["teammate", "call"],
-    kit_setup: ["repo", "kit"],
-    decision_record: ["repo", "claim", "why", "supersedes", "source"],
-    decision_retire: ["repo", "decision", "reason"],
-    lead_about_you: ["line", "replaces"],
-    scope_approve: ["task"],
-    result_accept: ["task", "run"],
-    task_cancel: ["task"],
-    task_resume: ["task", "run"],
-};
 const nonceHash = (value) => createHash("sha256").update(value).digest("hex");
 function requireActor(store, who, repo, operation) {
     if (!store.schemaCurrent())
@@ -277,9 +235,11 @@ const quoted = (value) => `“${value}”`;
 export function prepareSharedAction(store, who, operation, input, root, now = new Date()) {
     if (!isChatAction(operation))
         throw Error("Choose an available action.");
-    const allowed = CHAT_ACTION_FIELDS[operation];
-    if (Object.keys(input).some((key) => !allowed.includes(key)))
-        throw Error("This action contains an unsupported field.");
+    // The action's own schema: its fields and their kinds, refused by path. The request itself is used as given, so a
+    // confirmation rebuilds the same stamp from the same bytes.
+    const read = readChatActionRequest(operation, input);
+    if (!read.ok)
+        throw Error(`This action can't be read — ${read.issues.map(issue => issue.line).join("; ")}.`);
     if (operation === "lead_about_you") {
         // The owner's own note: the card shows the line, and the line it replaces beside it.
         const checked = checkAboutYouLine(input["line"]);
@@ -300,7 +260,7 @@ export function prepareSharedAction(store, who, operation, input, root, now = ne
         const state = replaces === 0 ? {} : { was: lines[replaces - 1] };
         const title = replaces === 0 ? "Remember about you" : "Update what your lead knows about you";
         const stamp = hash({ operation, request, repo: "", state, terms, actor: who.name, generation: who.generation, ceiling: who.ceilingDigest });
-        return { operation, request, repo: "", title, terms, stamp, state };
+        return { version: SHARED_ACTION_VERSION, operation, request, repo: "", title, terms, stamp, state };
     }
     const task = operation.startsWith("skill_") || operation.startsWith("knowledge_") || operation.startsWith("decision_") || operation.startsWith("tool_") || operation.startsWith("flow_") || operation.startsWith("teammate_") || operation.startsWith("kit_")
         ? null
@@ -965,22 +925,12 @@ export function prepareSharedAction(store, who, operation, input, root, now = ne
         generation: who.generation,
         ceiling: who.ceilingDigest,
     });
-    return { operation, request, repo, title, terms, stamp, state };
+    return { version: SHARED_ACTION_VERSION, operation, request, repo, title, terms, stamp, state };
 }
+/** A saved proposal's action, read by its schema (contracts/chat-actions.ts); null when it can't be read. */
 export function sharedActionPayload(value) {
-    return isChatAction(value["operation"]) &&
-        typeof value["stamp"] === "string" &&
-        typeof value["repo"] === "string" &&
-        typeof value["title"] === "string" &&
-        Array.isArray(value["terms"]) &&
-        value["terms"].every((t) => typeof t === "string") &&
-        value["request"] !== null &&
-        typeof value["request"] === "object" &&
-        !Array.isArray(value["request"]) &&
-        value["state"] !== null &&
-        typeof value["state"] === "object"
-        ? value
-        : null;
+    const read = readSharedAction(value);
+    return read.ok ? read.value : null;
 }
 /** A shortened or redacted preview is not complete consent. This rule lives
  * in the shared door, so a forged transport callback cannot bypass it. */

package/dist/chat-ask.js

@@ -1,4 +1,4 @@
-import { chatHash } from "./chat-delivery-state.js";
+import { chatHash, partContent, savedChatPart } from "./chat-delivery-state.js";
 import { MATE_ASK_OTHER } from "./store.js";
 /** The question as text with its options, where no buttons are drawn. */
 export function chatAskText(ask) {
@@ -10,7 +10,7 @@ export function chatAskButtons(state, part, now) {
     const row = state.prepare("SELECT p.payload,e.channel,b.channel AS own FROM chat_part p JOIN chat_event e ON e.id=p.event JOIN chat_binding b ON b.id=e.binding WHERE p.id=?").get(part);
     if (row === undefined)
         return [];
-    const content = JSON.parse(String(row["payload"]));
+    const content = partContent(String(row["payload"]));
     if ((content.channel ?? row["channel"]) !== row["own"])
         return [];
     const options = content.ask?.options ?? [];
@@ -32,9 +32,9 @@ function repaint(state, part, event, line, now) {
         state.plan(event.id, [{ text: line }], now);
         return;
     }
-    const before = JSON.parse(String(row["payload"]));
+    const before = partContent(String(row["payload"]));
     const content = { text: `${before.text}\n\n${line}`.slice(0, 3400), edit: event.ts, ...(before.channel === undefined ? {} : { channel: before.channel }) };
-    state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE id=?").run(JSON.stringify(content), part);
+    state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE id=?").run(savedChatPart(content), part);
     state.finish(event.id);
 }
 /** A tapped ask button, inside the action's transaction; false when the token isn't one. */
@@ -84,7 +84,7 @@ export function applyChatAskTap(options, event, binding, token, now) {
     state.enqueue({
         id: chatHash(`${state.channel}:ask:${event.id}`).slice(0, 32), installation: event.installation, binding: binding.id, kind: "message",
         channel: event.channel, member: event.member, ts: event.ts, thread: event.thread,
-        payload: JSON.stringify({ text: option, originalLength: option.length }), created: now.toISOString(),
+        payload: { text: option, originalLength: option.length }, created: now.toISOString(),
     });
     repaint(state, part, event, `You chose: ${option}`, now);
     return true;

package/dist/chat-channel.js

@@ -273,16 +273,27 @@ export function proposalPreview(store, proposal, repos, channel = null) {
             : undefined;
         return path === undefined ? id : projectLabel(path);
     })();
+    // Telegram's card leads with the action and what confirming does, then the exact terms; its buttons say the rest.
+    const phone = channel === "telegram";
     const card = (headline, body = [], consequence = null) => ({
-        text: [
-            headline,
-            ...body,
-            ...(consequence === null ? [] : ["", consequence]),
-            "",
-            "Confirm or Dismiss below. Nothing changes until you confirm.",
-        ].join("\n"),
+        text: (phone
+            ? [
+                headline,
+                ...(consequence === null ? [] : [consequence]),
+                ...(body.length === 0 ? [] : ["", ...body]),
+                "",
+                "Nothing changes until you confirm.",
+            ]
+            : [
+                headline,
+                ...body,
+                ...(consequence === null ? [] : ["", consequence]),
+                "",
+                "Confirm or Dismiss below. Nothing changes until you confirm.",
+            ]).join("\n"),
         buttons: true,
     });
+    const lasting = phone ? " ⚠ can't be undone" : " — IRREVERSIBLE";
     // A handoff's text is origin-free on purpose: it is persisted before the
     // send, and the button or the missing-setup line joins it at send time.
     const handoff = (headline, body = []) => ({
@@ -361,11 +372,11 @@ export function proposalPreview(store, proposal, repos, channel = null) {
                 ? ["(the decision is gone)"]
                 : [
                     `Q: ${phoneText(decision.question, 400)}`,
-                    ...decision.options.map((one) => `${one.id === pick ? "→" : " "} ${phoneText(one.label, 120)}${one.reversible ? "" : " — IRREVERSIBLE"}${one.id === decision.recommendation ? " (the builder recommends this)" : ""}: ${phoneText(one.consequence, 300)}`),
+                    ...decision.options.map((one) => `${one.id === pick ? "→" : " "} ${phoneText(one.label, 120)}${one.reversible ? "" : lasting}${one.id === decision.recommendation ? " (the builder recommends this)" : ""}: ${phoneText(one.consequence, 300)}`),
                     ...(t("rationale") === "" ? [] : [`Why: ${t("rationale", 300)}`]),
                 ];
             return card(`Answer decision #${String(id ?? "?")} on ${taskName} with "${t("optionLabel", 120) || pick}"`, body, irreversible
-                ? "⚠ This choice is irreversible. Confirming asks you once more."
+                ? phone ? "⚠ This choice can't be undone. Confirming asks you once more." : "⚠ This choice is irreversible. Confirming asks you once more."
                 : null);
         }
         case "task_action": {

package/dist/chat-decide.d.ts

@@ -1,9 +1,22 @@
+/** Decisions finish in the chat app. A pushed card about a result, a failed task, a plan waiting for approval or a
+ * pull request ready to merge carries buttons that act in place: Accept and finish, Request changes, Retry,
+ * Approve & start, Merge. Every act that changes something asks twice ("Accept and finish 'X'? [Yes] [Cancel]"),
+ * and each button is one opaque token bound to the exact result, receipt, plan or commit the card showed: a card a
+ * newer result, a finished task or a changed plan has overtaken says so and acts on nothing.
+ *
+ * Approving a plan or merging needs the password, which never goes in chat, so they act in chat only under a
+ * repository's signed mode that carries the chatApprove term, for the signer's own chat; otherwise, and for a plan
+ * that widens permissions, exceeds the mode's budget or touches protected paths, the card keeps its link.
+ *
+ * Channel-agnostic: Telegram renders these today, and Slack, Discord and Teams reach the same acts through the same
+ * tokens (the `channel` column). Every act runs through the door the console uses. */
+import { DECIDE_ACTS } from "./contracts/chat-callback-rows.js";
 import { type ModeTerms } from "./modes.js";
 import { type VerifiedApprover } from "./principal.js";
 import type { Scope } from "./scope.js";
 import type { Store } from "./store.js";
 /** The tokens live in chat_decide_action and the open "What should change?" in chat_decide_prompt (store.ts). */
-export type DecideAct = "accept" | "changes" | "retry" | "approve" | "not-now" | "merge";
+export type DecideAct = (typeof DECIDE_ACTS)[number];
 export type DecideTarget = {
     kind: "result";
     taskId: string;
@@ -95,11 +108,12 @@ export declare function mergeInChat(store: Store, taskId: string, run: number, a
     ok: false;
     why: string;
 };
-/** The plan card: title, goal in two lines, what changes, done when, and what the yes allows. */
-export declare function planCardText(store: Store, taskId: string, scope: Scope, root?: string): string;
+/** The plan card: title, goal in two lines, what changes, done when, and what the yes allows. On Telegram the yes's
+ * terms come second, under the title, and the steps are fewer: the full plan is behind Edit. */
+export declare function planCardText(store: Store, taskId: string, scope: Scope, root?: string, channel?: DecideChannel): string;
 /** The acts a card about this target can take in chat right now, or null when none can (the card keeps its own
  * link). Reads only; nothing is minted. */
-export declare function decideOffer(store: Store, target: DecideTarget, who: VerifiedApprover, now: Date, root?: string): DecideOffer | null;
+export declare function decideOffer(store: Store, target: DecideTarget, who: VerifiedApprover, now: Date, root?: string, channel?: DecideChannel): DecideOffer | null;
 /** One fingerprint of what the card offers, without its tokens: a repaint with the same offer keeps its buttons. */
 export declare function offerFingerprint(offer: DecideOffer): string;
 /** The card's buttons, minted now (message unknown until it is sent: `placeDecideTokens` puts them on it). */

package/dist/chat-decide.js

@@ -10,6 +10,7 @@
  *
  * Channel-agnostic: Telegram renders these today, and Slack, Discord and Teams reach the same acts through the same
  * tokens (the `channel` column). Every act runs through the door the console uses. */
+import { DECIDE_ACTS, readDecideActionRow } from "./contracts/chat-callback-rows.js";
 import { createHash, randomBytes } from "node:crypto";
 import { acceptAndCompleteAsOperator, assignmentOf, owedAcceptance } from "./assignment.js";
 import { chatControlHref, chatResultHref } from "./chat-controls.js";
@@ -154,8 +155,9 @@ export function mergeInChat(store, taskId, run, approver, now) {
         return mode;
     return { ok: true, modeDigest: mode.digest, head: publication.headSha };
 }
-/** The plan card: title, goal in two lines, what changes, done when, and what the yes allows. */
-export function planCardText(store, taskId, scope, root) {
+/** The plan card: title, goal in two lines, what changes, done when, and what the yes allows. On Telegram the yes's
+ * terms come second, under the title, and the steps are fewer: the full plan is behind Edit. */
+export function planCardText(store, taskId, scope, root, channel) {
     const ref = store.lookupRef(taskId);
     const artifact = ref === null ? null : store.latestPlanArtifact(ref.id);
     let milestones = [];
@@ -175,6 +177,19 @@ export function planCardText(store, taskId, scope, root) {
     const goal = scope.goal.split("\n").filter(one => one.trim() !== "").slice(0, 2).map(one => phoneText(one, 160));
     const allowing = [permissionPlainWords(scope.profile), scope.budgetMicrousd === null ? "no attempt limit" : `up to ${money(scope.budgetMicrousd)} per attempt`]
         .filter((one) => one !== null);
+    if (channel === "telegram") {
+        return [
+            `Plan ready: ${title(store, taskId)}`,
+            `Starting allows: ${allowing.join(" · ")}`,
+            "",
+            ...goal,
+            ...(scope.touches.length > 0 ? [`Only in: ${scope.touches.slice(0, 6).map(one => phoneText(one, 80)).join(", ")}${scope.touches.length > 6 ? ", …" : ""}`] : ["Any file in the project."]),
+            "",
+            "Done when:",
+            ...(scope.acceptance.length > 0 ? bullets(scope.acceptance.map(one => one.statement), 5) : ["You decide when you review the result."]),
+            ...(milestones.length > 0 ? ["", "Steps:", ...bullets(milestones, 3)] : []),
+        ].join("\n");
+    }
     return [
         `Plan ready: ${title(store, taskId)}`,
         "",
@@ -193,7 +208,7 @@ export function planCardText(store, taskId, scope, root) {
 // ---- what a card offers ---------------------------------------------------------------
 /** The acts a card about this target can take in chat right now, or null when none can (the card keeps its own
  * link). Reads only; nothing is minted. */
-export function decideOffer(store, target, who, now, root) {
+export function decideOffer(store, target, who, now, root, channel) {
     const ref = store.lookupRef(target.taskId);
     if (ref === null || ref.repo === null || !who.repos.includes(ref.repo))
         return null;
@@ -221,7 +236,7 @@ export function decideOffer(store, target, who, now, root) {
             const plan = planInChat(store, target.taskId, who.name, now, root);
             if (!plan.ok)
                 return null;
-            return { text: planCardText(store, target.taskId, plan.scope, root),
+            return { text: planCardText(store, target.taskId, plan.scope, root, channel),
                 rows: [[{ act: "approve", run: null, digest: plan.digest }], [{ label: DECIDE_LABELS.edit, path: chatControlHref("approval", target.taskId) }, { act: "not-now", run: null, digest: plan.digest }]] };
         }
         case "merge": {
@@ -258,11 +273,12 @@ function retryStamp(store, taskId, who) {
 export function offerFingerprint(offer) {
     return sha(JSON.stringify(offer));
 }
-function readAction(row) {
-    return { token: String(row["token"]), channel: String(row["channel"]), binding: Number(row["binding"]), chat: String(row["chat"]),
-        message: row["message"] == null ? null : String(row["message"]), act: String(row["act"]), phase: String(row["phase"]),
-        taskId: String(row["task_id"]), run: row["run"] == null ? null : Number(row["run"]), digest: String(row["digest"]),
-        expiresAt: String(row["expires_at"]), consumedAt: row["consumed_at"] == null ? null : String(row["consumed_at"]) };
+function readAction(raw) {
+    const read = readDecideActionRow(raw);
+    if (!read.ok)
+        return read;
+    const { task_id: taskId, expires_at: expiresAt, consumed_at: consumedAt, created_at: _created, ...row } = read.value;
+    return { ok: true, value: { ...row, taskId, expiresAt, consumedAt } };
 }
 function mint(store, seat, message, spec, taskId, phase, now) {
     const token = `d:${randomBytes(12).toString("hex")}`;
@@ -378,7 +394,11 @@ export function applyDecideTap(store, seat, input) {
     const raw = input.token.startsWith("d:") ? store.handle.prepare("SELECT * FROM chat_decide_action WHERE token = ?").get(input.token) : undefined;
     if (raw === undefined)
         return null;
-    const row = readAction(raw);
+    const read = readAction(raw);
+    // A saved button that can't be read acts on nothing, and says why.
+    if (!read.ok)
+        return { ack: `That button can't be read (${read.issues.map(issue => issue.line).join("; ")}). Nothing was done.`, ignored: true };
+    const row = read.value;
     const { now } = input;
     if (row.channel !== seat.channel || row.binding !== seat.binding || row.chat !== seat.chat || (row.message !== null && row.message !== input.message))
         return { ack: "That button isn't for this chat.", ignored: true };
@@ -408,7 +428,7 @@ export function applyDecideTap(store, seat, input) {
     }
     if (row.phase === "cancel") {
         spend();
-        const offer = decideOffer(store, target, who, now, input.root);
+        const offer = decideOffer(store, target, who, now, input.root, seat.channel);
         if (offer === null)
             return { ack: "Cancelled.", edit: { text: body, rows: linksFor(target), tokens: [] } };
         const minted = mintDecideButtons(store, seat, target, offer, now, input.message);

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

@@ -1,4 +1,8 @@
 import { type Store } from "./store.js";
+import { chatSchema, chatTables } from "./contracts/chat-tables.js";
+import { savedChatPart, type ChatContent, type ChatEventBody } from "./contracts/chat-content.js";
+export { savedChatPart, type ChatContent, type ChatEventBody };
+export { chatSchema, chatTables };
 export type ChatIdentity = {
     installation: string;
     team?: string;
@@ -57,72 +61,6 @@ export type ChatRoom = {
     binding: number;
     cursor: number;
 };
-export type ChatContent = {
-    text: string;
-    /** Where the part is sent when not the binding's own DM: a room's channel. */
-    channel?: string;
-    proposal?: number;
-    image?: {
-        taskId: string;
-        run: number;
-        artifact: number;
-        sha256: string;
-    };
-    /** A screenshot sent with a result (result-shots.ts): it follows that result's message part, in its thread when
-     * the app allows; a refused upload becomes one plain line, and one removed by retention goes quietly. */
-    shot?: {
-        follows: number | null;
-    };
-    task?: string;
-    run?: number;
-    edit?: string;
-    phase?: "armed";
-    link?: {
-        label: string;
-        path: string;
-    };
-    /** More link buttons after `link`: [Look first] beside [Merge] or [Accept and finish]. */
-    also?: Array<{
-        label: string;
-        path: string;
-    }>;
-    /** A flow decision's buttons ride this part (v88): minted when it is planned. */
-    flow?: {
-        card: number;
-        entry: number;
-        actions: Array<"approve" | "edit" | "send-back">;
-    };
-    /** A flow's "Person chooses" buttons ride this part: minted when it is planned. */
-    choose?: {
-        card: number;
-        entry: number;
-        options: Array<{
-            choice: number;
-            label: string;
-        }>;
-    };
-    /** "Use this as your note?" Yes / No about the person's message `held` (an event id), for one choice's visit. */
-    note?: {
-        card: number;
-        entry: number;
-        held: string;
-    };
-    /** A teammate's question's buttons ride this part (v93): each option, then one to answer in words (choice null). */
-    question?: {
-        id: number;
-        choices: Array<{
-            choice: string | null;
-            label: string;
-        }>;
-    };
-    /** The lead's question to its owner rides this part: its options, then "Something else". */
-    ask?: {
-        turn: number;
-        options: string[];
-    };
-    /** The lead's own reply, already shaped (reply-shape.ts): the channel renders its bold anchors and labelled links in its own format. */
-    voice?: true;
-};
 export declare const chatHash: (text: string) => string;
 export declare class ChatState {
     readonly store: Store;
@@ -170,7 +108,10 @@ export declare class ChatState {
     revoke(installation: string, now?: Date): void;
     pairing(installation: string, approver: string, generation: number, now?: Date): string;
     pair(identity: ChatIdentity, hash: string, member: string, channel: string, now: Date): ChatBinding | null;
-    enqueue(event: Omit<ChatEvent, "session" | "state" | "next_at">): boolean;
+    /** Save a received event with its body (contracts/chat-content.ts), versioned. */
+    enqueue(event: Omit<ChatEvent, "session" | "state" | "next_at" | "payload"> & {
+        payload: ChatEventBody;
+    }): boolean;
     event(id: string): ChatEvent | null;
     next(installation: string, now: Date): ChatEvent | null;
     defer(event: string, problem: string, until: Date): void;
@@ -181,11 +122,12 @@ export declare class ChatState {
     lease(installation: string, owner: string, now: Date): boolean;
     owns(installation: string, owner: string, now?: Date): boolean;
 }
-export declare const chatSchema: (channel: "slack" | "discord" | "teams") => string;
-export declare const chatTables: (channel: "slack" | "discord" | "teams") => string[];
+/** A saved part's content. One that can't be read is a delivery problem that names the field, never a guess. */
+export declare function partContent(payload: string): ChatContent;
 export declare class ChatDeliveryError extends Error {
     readonly code: string;
     readonly retryMs: number;
     readonly uncertain: boolean;
-    constructor(code: string, retryMs?: number, uncertain?: boolean);
+    readonly permanent: boolean;
+    constructor(code: string, retryMs?: number, uncertain?: boolean, permanent?: boolean);
 }