toolroll 0.9.41 → 0.9.43

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.9.43 — 2026-10-06
+
+- **Approve from chat and the CLI.** A plan waiting on you and a flow's
+  approval or choose step get **Approve** and **Send back** buttons in your
+  paired Telegram chat, two taps each, recorded like a console decision. Ask
+  the lead to "approve X" and it answers with those buttons; your tap is
+  still the approval. `toolroll flows card approve <flow> <card>` and
+  `toolroll flows card send-back <flow> <card> --note …` do the same from the
+  terminal with your login.
+- **Chat approval can stay on.** `toolroll chat-approval on|off [--repo <p>]`
+  turns approving from chat on for one project or all of them, with your
+  password to turn it on; off is instant and off for all really is all. It no
+  longer lapses with a weekly mode. Plans that widen permissions, go over a
+  cap or touch protected paths still go to the console.
+- **Old cards point onward.** A card in a past conversation says where the
+  item went and links to it when you can open it.
+- Still to come: Slack, Discord and Teams buttons, a Settings screen for chat
+  approval, and sending a plan back from chat.
+
+## 0.9.42 — 2026-10-06
+
+- **Zod revamp, waves 3 and 4.** What comes into Toolroll from outside and
+  what it reads back from disk now goes through one schema each in
+  `src/contracts/`: console forms and JSON, CLI `--json` output, webhook,
+  GitHub, Linear, email and form payloads, OAuth replies and tool specs,
+  settings, every JSON column in the database, update and recovery journals,
+  and evidence files. All of it is read as leniently as before. Replayed
+  against real data with 0 differences: 655 runs and 984 evidence folders,
+  5,158 database rows, 7 tool connections. Console JSON and CLI `--json` bytes
+  are unchanged. Console API and CLI input are partly done; what remains is
+  listed in `docs/plans/zod-revamp.md`.
+- **Changed on purpose.** Recipe refusals start with the field's path. An
+  unknown provider is refused as `provider: unknown provider`, without
+  repeating what was typed. A sign-in that answers with an empty token says
+  it couldn't be reached instead of crashing. An update journal missing its
+  core fields (no release since 0.8.0 writes one) is refused rather than read.
+
 ## 0.9.41 — 2026-10-06
 
 - **A read-only PostHog connection works for research.** PostHog adds

package/dist/chat-actions.js

@@ -1347,7 +1347,7 @@ function runFlowAction(store, payload, actor, repos, root, now) {
                 return chosen.ok ? { ok: true, said: chosen.said, card: card.id } : { ok: false, message: chosen.message };
             })()
                 : (() => {
-                    const decided = decideFlowCard(store, { card: card.id, decision: payload.operation === "flow_card_approve" ? "approve" : "send-back", note: typeof req["note"] === "string" ? req["note"] : null, actor, repos, ...(root === undefined ? {} : { evidenceRoot: root }) }, now);
+                    const decided = decideFlowCard(store, { card: card.id, decision: payload.operation === "flow_card_approve" ? "approve" : "send-back", note: typeof req["note"] === "string" ? req["note"] : null, actor, repos, where: "Chat", ...(root === undefined ? {} : { evidenceRoot: root }) }, now);
                     return decided.ok ? { ok: true, said: decided.said, card: card.id } : { ok: false, message: decided.message };
                 })();
     if (!acted.ok)

package/dist/chat-approval.d.ts

@@ -0,0 +1,45 @@
+import type { Store } from "./store.js";
+/** The all-projects row's scope. */
+export declare const ALL_PROJECTS = "*";
+export type ChatApprovalLimits = {
+    fullAccess: boolean;
+    capMicrousd: number | null;
+};
+export type ChatApprovalSetting = ChatApprovalLimits & {
+    approver: string;
+    scope: string;
+    enabled: boolean;
+    generation: number;
+    digest: string;
+    updatedBy: string;
+    updatedAt: string;
+};
+/** This person's rows: all projects first, then each project's. */
+export declare function chatApprovalSettings(store: Store, approver: string): ChatApprovalSetting[];
+/** The limits in plain words, said once: what a yes in chat may start. */
+export declare function chatApprovalWords(limits: ChatApprovalLimits): string;
+/** Whether this person's chat may approve on this project now, under their lasting setting: which row, and its limits. */
+export declare function effectiveChatApproval(store: Store, repo: string, approver: string): {
+    ok: true;
+    setting: ChatApprovalSetting;
+    limits: ChatApprovalLimits;
+} | {
+    ok: false;
+    why: string;
+};
+export type ChatApprovalChange = {
+    approver: string;
+    scope: string;
+    enabled: boolean;
+    limits?: ChatApprovalLimits;
+    via: string;
+};
+/** Save and ledger the setting; all-projects off also disables every saved project row for this owner.
+ * The caller has proved who is asking, and for "on" the password. */
+export declare function setChatApproval(store: Store, change: ChatApprovalChange, now: Date): {
+    ok: true;
+    said: string;
+} | {
+    ok: false;
+    message: string;
+};

package/dist/chat-approval.js

@@ -0,0 +1,81 @@
+/** Approving from chat as a lasting owner setting. An approver turns it on for all their projects or for one, with the
+ * limits they agree to (whether a plan may ask for full access, and the most one attempt may cost); a project's own
+ * row outranks the all-projects one, and an explicit "off" on a project keeps it off there. Turning it off for all
+ * projects also disables that owner's saved project rows. It is off until turned on.
+ *
+ * It never lapses by date, but it ends with the account: a reset password, revoked access or a lost project ends it.
+ * Turning it on or changing its limits takes the password; turning it off is one step. Every change is a ledger line.
+ *
+ * What the setting allows is only that the owner's own two taps in their paired chat count as their yes. Every other
+ * rule still applies at the offer and again at the tap (chat-decide.ts planInChat): protected paths, separation of
+ * duties, organisation policy, written-for-you plans, unresolved routes, and the limits here. */
+import { createHash } from "node:crypto";
+/** The all-projects row's scope. */
+export const ALL_PROJECTS = "*";
+const money = (micro) => `$${(micro / 1_000_000).toFixed(2)}`;
+function digestOf(approver, scope, limits, generation) {
+    return createHash("sha256").update(JSON.stringify({ v: 1, approver, scope, fullAccess: limits.fullAccess, capMicrousd: limits.capMicrousd, generation })).digest("hex");
+}
+function readRow(row) {
+    return {
+        approver: String(row["approver"]), scope: String(row["scope"]), enabled: Number(row["enabled"]) === 1, fullAccess: Number(row["full_access"]) === 1,
+        capMicrousd: row["attempt_cap_microusd"] == null ? null : Number(row["attempt_cap_microusd"]), generation: Number(row["generation"]),
+        digest: String(row["digest"]), updatedBy: String(row["updated_by"]), updatedAt: String(row["updated_at"]),
+    };
+}
+/** This person's rows: all projects first, then each project's. */
+export function chatApprovalSettings(store, approver) {
+    return store.handle.prepare("SELECT * FROM chat_approval_setting WHERE approver = ? ORDER BY scope = '*' DESC, scope").all(approver).map(row => readRow(row));
+}
+/** The limits in plain words, said once: what a yes in chat may start. */
+export function chatApprovalWords(limits) {
+    return `${limits.fullAccess ? "plans may ask for full access" : "plans that ask for full access open in Toolroll"} · ${limits.capMicrousd === null ? "any attempt limit" : `attempts up to ${money(limits.capMicrousd)}`}`;
+}
+/** Whether this person's chat may approve on this project now, under their lasting setting: which row, and its limits. */
+export function effectiveChatApproval(store, repo, approver) {
+    const project = store.handle.prepare("SELECT * FROM chat_approval_setting WHERE approver = ? AND scope = ?").get(approver, repo);
+    const all = store.handle.prepare("SELECT * FROM chat_approval_setting WHERE approver = ? AND scope = ?").get(approver, ALL_PROJECTS);
+    const row = project ?? all;
+    const setting = row === undefined ? null : readRow(row);
+    if (setting === null || !setting.enabled)
+        return { ok: false, why: "Approving from chat isn't turned on for this project." };
+    const account = store.accountOf(approver);
+    if (account === null || account.revokedAt !== null || account.role !== "approver" || account.generation !== setting.generation || !store.accountCanAccess(approver, repo)) {
+        return { ok: false, why: "Your access changed since you turned on approving from chat. Turn it on again in Settings." };
+    }
+    if (setting.digest !== digestOf(setting.approver, setting.scope, setting, setting.generation))
+        return { ok: false, why: "Your chat approval setting can't be read. Turn it on again in Settings." };
+    return { ok: true, setting, limits: { fullAccess: setting.fullAccess, capMicrousd: setting.capMicrousd } };
+}
+/** Save and ledger the setting; all-projects off also disables every saved project row for this owner.
+ * The caller has proved who is asking, and for "on" the password. */
+export function setChatApproval(store, change, now) {
+    const account = store.accountOf(change.approver);
+    if (account === null || account.revokedAt !== null || account.role !== "approver")
+        return { ok: false, message: "Only an approver can approve from chat." };
+    if (change.scope !== ALL_PROJECTS && !store.accountCanAccess(change.approver, change.scope))
+        return { ok: false, message: "That isn't one of your projects." };
+    const limits = change.limits ?? { fullAccess: false, capMicrousd: null };
+    if (limits.capMicrousd !== null && (!Number.isSafeInteger(limits.capMicrousd) || limits.capMicrousd < 0))
+        return { ok: false, message: "Give the attempt limit in dollars, like 5." };
+    const where = change.scope === ALL_PROJECTS ? "all your projects" : change.scope;
+    store.transact(() => {
+        const settings = [{ scope: change.scope, limits }];
+        if (change.scope === ALL_PROJECTS && !change.enabled) {
+            for (const setting of chatApprovalSettings(store, change.approver)) {
+                if (setting.scope !== ALL_PROJECTS)
+                    settings.push({ scope: setting.scope, limits: setting });
+            }
+        }
+        const save = store.handle.prepare(`INSERT INTO chat_approval_setting (approver, scope, enabled, full_access, attempt_cap_microusd, generation, digest, updated_by, updated_at)
+      VALUES (?,?,?,?,?,?,?,?,?) ON CONFLICT (approver, scope) DO UPDATE SET enabled = excluded.enabled, full_access = excluded.full_access,
+      attempt_cap_microusd = excluded.attempt_cap_microusd, generation = excluded.generation, digest = excluded.digest, updated_by = excluded.updated_by, updated_at = excluded.updated_at`);
+        for (const { scope, limits } of settings) {
+            save.run(change.approver, scope, change.enabled ? 1 : 0, limits.fullAccess ? 1 : 0, limits.capMicrousd, account.generation, digestOf(change.approver, scope, limits, account.generation), change.approver, now.toISOString());
+            store.recordAction({ at: now.toISOString(), actor: change.approver, repo: scope === ALL_PROJECTS ? null : scope, taskId: null, runId: null,
+                action: "chat approval setting", outcome: change.enabled ? "on" : "off", source: "request",
+                detail: `${scope === ALL_PROJECTS ? "all projects" : "this project"}${change.enabled ? ` · ${chatApprovalWords(limits)}` : ""} · via ${change.via}` });
+        }
+    });
+    return { ok: true, said: change.enabled ? `Approving from chat is on for ${where}: ${chatApprovalWords(limits)}.` : `Approving from chat is off for ${where}.` };
+}

package/dist/chat-channel.js

@@ -556,6 +556,11 @@ export const CHAT_ACTION_PARITY = {
         how: "Shared read-only acceptance packet: exact result, criterion states, gate, reviewer findings, caveats and recorded human acceptance. Screenshot files use get_result_images; marking complete is a propose_action result_accept confirmed behind the phone's own yes/cancel challenge or on the signed-in console.",
         gap: "A physical-phone completion has not been exercised.",
     },
+    offer_approval: {
+        support: "direct",
+        how: "Pushes the plan's or flow card's own decision card to the owner's paired chat: Approve arms Yes and Cancel, and only the owner's Yes decides, through sealScopeApproval (as a chat-origin approval) or decideFlowCard. Outside the owner's chat-approval setting or a decision's rules it answers why, and the lead opens the console control.",
+        gap: "A flow card's Send back, Edit and a Person chooses step act from the pushed card; a plan's Send back stays in the console. Fixture proof only, no physical-phone rendering.",
+    },
     show_control: {
         support: "handoff",
         how: "The card names the control and the task, with one url button to that exact console control when a trusted https console-url is configured; the button opens the signed-in console and acts on nothing.",

package/dist/chat-decide.d.ts

@@ -4,14 +4,15 @@
  * 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.
+ * Approving a plan or merging needs the password, which never goes in chat, so they act in chat only where the owner
+ * turned approving from chat on (their lasting setting, chat-approval.ts, or a signed mode's chatApprove term), for
+ * their own chat; otherwise, and for a plan that widens permissions, exceeds the limit 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 ChatApprovalLimits } from "./chat-approval.js";
 import { type VerifiedApprover } from "./principal.js";
 import type { Scope } from "./scope.js";
 import type { Store } from "./store.js";
@@ -77,11 +78,14 @@ export type DecideOffer = {
     text: string | null;
     rows: Array<Array<ActSpec | DecideLink>>;
 };
-/** The live mode on this repository, when it lets this person's chat approve: the term signed, by them. */
+/** What lets this person's chat approve on this repository now: their lasting chat-approval setting (chat-approval.ts),
+ * or else a live signed mode carrying the chatApprove term, signed by them. `digest` names that authority for the
+ * ledger; the yes itself is the person's tap and is sealed as theirs, so it doesn't lapse when the authority does. */
 export declare function chatApproveMode(store: Store, repo: string | null, approver: string, now: Date): {
     ok: true;
     digest: string;
-    terms: ModeTerms;
+    limits: ChatApprovalLimits;
+    source: "setting" | "mode";
 } | {
     ok: false;
     why: string;
@@ -93,6 +97,7 @@ export declare function permissionPlainWords(profile: Scope["profile"] | null |
 export declare function planInChat(store: Store, taskId: string, approver: string, now: Date, root?: string): {
     ok: true;
     modeDigest: string;
+    source: "setting" | "mode";
     digest: string;
     scope: Scope;
 } | {
@@ -103,6 +108,7 @@ export declare function planInChat(store: Store, taskId: string, approver: strin
 export declare function mergeInChat(store: Store, taskId: string, run: number, approver: string, now: Date): {
     ok: true;
     modeDigest: string;
+    source: "setting" | "mode";
     head: string;
 } | {
     ok: false;
@@ -160,6 +166,12 @@ export type ChatMerge = {
 };
 /** The links a card keeps once its acts are spent or stale: where to look, never a token. */
 export declare function linksFor(target: DecideTarget): DecideButton[][];
+/** Where a plan card's task is now, for a card whose buttons no longer act: the family's current version, named only
+ * inside this person's projects, and linked only while it still waits on them. Never a live button. */
+export declare function planWhereNow(store: Store, taskId: string, who: VerifiedApprover, now: Date, root?: string): {
+    said: string;
+    rows: DecideButton[][];
+};
 /**
  * One tap on a decide button, inside the caller's transaction. Null: not this module's token. The seat must be the
  * token's own (person, chat, message); a spent, expired or foreign button acts on nothing.

package/dist/chat-decide.js

@@ -4,9 +4,10 @@
  * 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.
+ * Approving a plan or merging needs the password, which never goes in chat, so they act in chat only where the owner
+ * turned approving from chat on (their lasting setting, chat-approval.ts, or a signed mode's chatApprove term), for
+ * their own chat; otherwise, and for a plan that widens permissions, exceeds the limit 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. */
@@ -17,6 +18,7 @@ import { chatControlHref, chatResultHref } from "./chat-controls.js";
 import { applyChatTaskAction, chatTaskStamp } from "./chat-task-actions.js";
 import { chatTitle } from "./chat-voice.js";
 import { readVerifiedArtifact } from "./evidence.js";
+import { effectiveChatApproval } from "./chat-approval.js";
 import { modeTermsFromJson } from "./modes.js";
 import { parseExecutionPlanDocument } from "./plan.js";
 import { verifyApproverStanding } from "./principal.js";
@@ -45,15 +47,22 @@ const sha = (text) => createHash("sha256").update(text).digest("hex");
 const isAct = (one) => "act" in one;
 const title = (store, taskId) => phoneText(chatTitle(store, taskId), 60);
 // ---- the chatApprove term ----------------------------------------------------------
-/** The live mode on this repository, when it lets this person's chat approve: the term signed, by them. */
+/** What lets this person's chat approve on this repository now: their lasting chat-approval setting (chat-approval.ts),
+ * or else a live signed mode carrying the chatApprove term, signed by them. `digest` names that authority for the
+ * ledger; the yes itself is the person's tap and is sealed as theirs, so it doesn't lapse when the authority does. */
 export function chatApproveMode(store, repo, approver, now) {
-    const mode = repo === null ? null : store.activeMode(repo, now);
+    if (repo === null)
+        return { ok: false, why: "Approving from chat isn't turned on for this project." };
+    const setting = effectiveChatApproval(store, repo, approver);
+    if (setting.ok)
+        return { ok: true, digest: setting.setting.digest, limits: setting.limits, source: "setting" };
+    const mode = store.activeMode(repo, now);
     const terms = mode === null ? null : modeTermsFromJson(mode.termsJson);
     if (mode === null || terms === null || !terms.chatApprove)
-        return { ok: false, why: "Approving from chat isn't turned on for this project." };
+        return setting;
     if (mode.signedBy !== approver || !store.accountCanAccess(approver, repo))
         return { ok: false, why: "Only the person who signed this project's mode can approve from chat." };
-    return { ok: true, digest: mode.digest, terms };
+    return { ok: true, digest: mode.digest, limits: { fullAccess: terms.permissionDefault === "escalated", capMicrousd: terms.perAttemptBudgetMicrousd }, source: "mode" };
 }
 /** What a plan's yes allows an agent to do, in a few plain words (the approval sheet's "You're allowing"). */
 export function permissionPlainWords(profile) {
@@ -102,11 +111,12 @@ export function planInChat(store, taskId, approver, now, root) {
         return { ok: false, why: "Agents compete on this task, so you approve it in Toolroll." };
     if (scope.profileState === "unresolved" || scope.routeEra == null || (scope.termsProblem ?? null) !== null)
         return { ok: false, why: "This plan can't say exactly which agents run, so you approve it in Toolroll." };
-    if (fullAccess(scope.profile) && mode.terms.permissionDefault !== "escalated")
-        return { ok: false, why: "This plan asks for more access than your mode allows." };
-    const cap = mode.terms.perAttemptBudgetMicrousd;
+    const yours = mode.source === "setting" ? "your chat approval setting" : "your mode";
+    if (fullAccess(scope.profile) && !mode.limits.fullAccess)
+        return { ok: false, why: `This plan asks for more access than ${yours} allows.` };
+    const cap = mode.limits.capMicrousd;
     if (cap !== null && (scope.budgetMicrousd === null || scope.budgetMicrousd > cap))
-        return { ok: false, why: `This plan has ${scope.budgetMicrousd === null ? "no attempt limit" : `a ${money(scope.budgetMicrousd)} attempt limit`}, more than your mode's ${money(cap)}.` };
+        return { ok: false, why: `This plan has ${scope.budgetMicrousd === null ? "no attempt limit" : `a ${money(scope.budgetMicrousd)} attempt limit`}, more than ${yours === "your mode" ? "your mode's" : "your chat approval limit of"} ${money(cap)}.` };
     if (store.approvalGate(taskId, approver, "mode").verdict !== "seal")
         return { ok: false, why: "This plan touches protected work, so two people approve it in Toolroll." };
     if (store.scopePolicyRefusal(taskId) !== null)
@@ -137,7 +147,7 @@ export function planInChat(store, taskId, approver, now, root) {
         if (!verified)
             return { ok: false, why: "The saved plan can't be verified here, so you approve it in Toolroll." };
     }
-    return { ok: true, modeDigest: mode.digest, scope, digest: sha(`${scope.digest}:${plan?.sha256 ?? ""}`) };
+    return { ok: true, modeDigest: mode.digest, source: mode.source, scope, digest: sha(`${scope.digest}:${plan?.sha256 ?? ""}`) };
 }
 /** A ready pull request this person's chat may merge now, bound to the exact commit. */
 export function mergeInChat(store, taskId, run, approver, now) {
@@ -153,7 +163,7 @@ export function mergeInChat(store, taskId, run, approver, now) {
     const mode = chatApproveMode(store, ref.repo, approver, now);
     if (!mode.ok)
         return mode;
-    return { ok: true, modeDigest: mode.digest, head: publication.headSha };
+    return { ok: true, modeDigest: mode.digest, source: mode.source, head: publication.headSha };
 }
 /** 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. */
@@ -380,6 +390,27 @@ export function linksFor(target) {
         case "failed": return [[{ label: "Open task", link: { label: "Open task", path: chatControlHref("task", target.taskId) } }]];
     }
 }
+/** Where a plan card's task is now, for a card whose buttons no longer act: the family's current version, named only
+ * inside this person's projects, and linked only while it still waits on them. Never a live button. */
+export function planWhereNow(store, taskId, who, now, root) {
+    const family = store.taskFamilyOf(taskId, who.repos, false);
+    if (family === null)
+        return { said: "It has moved on.", rows: [] };
+    const current = family.current.id;
+    const name = title(store, current);
+    const state = store.getTask(current)?.state;
+    if (state === "done" || state === "cancelled") {
+        const assignment = assignmentOf(store, current, now, { principal: "operator", repos: who.repos }, root);
+        if (assignment?.state !== "ready-to-check")
+            return { said: state === "cancelled" ? `"${name}" was cancelled.` : `"${name}" is finished.`, rows: [] };
+        return { said: `"${name}" has a result waiting for you.`, rows: [[{ label: "Open the task", link: { label: "Open the task", path: chatControlHref("task", current) } }]] };
+    }
+    const scope = store.getScope(current);
+    if (scope !== null && !(scope.approvedDigest != null && scope.approvedDigest === scope.digest) && store.lookupRef(current)?.plan !== "requested") {
+        return { said: `"${name}" waits for your approval${current === taskId ? "" : " (a newer version)"}.`, rows: [[{ label: "Review & start", link: { label: "Review & start", path: chatControlHref("approval", current) } }]] };
+    }
+    return { said: `"${name}" is under way.`, rows: [] };
+}
 const QUESTION_STARTS = ["Accept and finish \"", "Retry \"", "Approve and start \"", "Merge \""];
 /** The card's words without a question this module appended. */
 function cardBody(shown) {
@@ -417,14 +448,16 @@ export function applyDecideTap(store, seat, input) {
         store.handle.prepare("UPDATE chat_decide_action SET consumed_at = ? WHERE token = ? AND consumed_at IS NULL").run(now.toISOString(), row.token);
         retireDecideTokens(store, seat.channel, seat.chat, input.message, now);
     };
+    // A plan's card names where its task is now (its newest version, or finished), and links it only while it waits.
+    const here = target.kind === "plan" ? planWhereNow(store, row.taskId, who, now, input.root) : null;
     const stale = (why) => {
         spend();
-        return { ack: why, edit: { text: `${body}\n\n${why} Nothing was done.`, rows: linksFor(target), tokens: [] } };
+        return { ack: why, edit: { text: `${body}\n\n${why} Nothing was done.${here === null || here.rows.length > 0 && why.startsWith("The plan changed") ? "" : ` ${here.said}`}`, rows: here?.rows ?? linksFor(target), tokens: [] } };
     };
-    // An expired button: the card says so and keeps its links, so it is never a dead end.
+    // An expired button: the card says so and where the work is now, so it is never a dead end; the old button never acts.
     if (row.expiresAt <= now.toISOString()) {
         spend();
-        return { ack: "That button expired.", edit: { text: `${body}\n\nThat button expired. Nothing was done.`, rows: linksFor(target), tokens: [] } };
+        return { ack: "That button expired.", edit: { text: `${body}\n\nThat button expired. Nothing was done.${here === null ? "" : ` ${here.said}`}`, rows: here?.rows ?? linksFor(target), tokens: [] } };
     }
     if (row.phase === "cancel") {
         spend();
@@ -475,17 +508,18 @@ export function applyDecideTap(store, seat, input) {
             const plan = planInChat(store, row.taskId, who.name, now, input.root);
             if (!plan.ok)
                 return notDone(plan.why);
-            if (!store.sealScopeApproval(row.taskId, who.name, now, {}, { kind: "mode", modeDigest: plan.modeDigest }))
+            // The owner's own yes, sealed as theirs ("chat"), never as a mode's: it stands like the console's after the mode or setting ends.
+            if (!store.sealScopeApproval(row.taskId, who.name, now, {}, { kind: "chat", modeDigest: plan.modeDigest }))
                 return notDone("the plan couldn't be approved from chat. Open it in Toolroll.");
             store.recordAction({ at: now.toISOString(), actor: who.name, repo: ref.repo, taskId: row.taskId, runId: null, action: "plan approved in chat", outcome: "approved",
-                source: "request", detail: `via ${seat.channel} · chat binding #${seat.binding} · mode ${plan.modeDigest}` });
-            return done("✓ Approved under your chat approval mode. Work starts when a worker is free.");
+                source: "request", detail: `via ${seat.channel} · chat binding #${seat.binding} · ${plan.source} ${plan.modeDigest}` });
+            return done("✓ Approved. Work starts when a worker is free.");
         }
         case "merge": {
             const merge = mergeInChat(store, row.taskId, row.run ?? 0, who.name, now);
             if (!merge.ok)
                 return notDone(merge.why);
-            const via = `via ${seat.channel} · chat binding #${seat.binding} · mode ${merge.modeDigest} · ${merge.head.slice(0, 12)}`;
+            const via = `via ${seat.channel} · chat binding #${seat.binding} · ${merge.source} ${merge.modeDigest} · ${merge.head.slice(0, 12)}`;
             // The approval is ledgered with the tap, so a bridge that stops before GitHub answers still leaves it on record;
             // what GitHub then did is its own line (recordChatMerge).
             store.recordAction({ at: now.toISOString(), actor: who.name, repo: ref.repo, taskId: row.taskId, runId: row.run ?? null, action: "merge approved in chat", outcome: "approved",

package/dist/chat-flow.js

@@ -190,7 +190,7 @@ export function applyChatFlowTap(options, event, binding, token, repos, now) {
     }
     const kind = String(action["action"]);
     if (kind === "approve") {
-        const decided = decideFlowCard(store, { card, decision: "approve", note: null, actor: binding.approver, repos, entry }, now);
+        const decided = decideFlowCard(store, { card, decision: "approve", note: null, actor: binding.approver, repos, entry, where: options.label }, now);
         if (!decided.ok) {
             say(decided.message);
             return true;
@@ -441,7 +441,7 @@ export function answerChatFlowPrompt(options, event, binding, input, repos, now)
             state.plan(event.id, decisionParts(`${waiting.flow.name}: your version of the draft for “${waiting.card.title}”\n\n${kept}\n\nApprove to send it as written.`, { card, entry, actions: actionsFor(fresh) }, { label: "Open", path: flowCardHref(waiting.flow.id, card) }), now);
             return true;
         }
-        const decided = decideFlowCard(store, { card, decision: "send-back", note: said, actor: binding.approver, repos, entry }, now);
+        const decided = decideFlowCard(store, { card, decision: "send-back", note: said, actor: binding.approver, repos, entry, where: options.label }, now);
         if (!decided.ok) {
             close();
             say(decided.message);

package/dist/cli.js

@@ -17,7 +17,9 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { configPath, loadRepos } from "./repos.js";
 import { addedWords, admitProject, commandLineActor, consoleRunning, proveProjectRoot, registryBeside, releaseProject } from "./project-admission.js";
 import { envValue } from "./names.js";
-import { CAPABILITIES, ENVELOPE_VERSION, capturedEnvelope, envelopeJson, onEnvelopeCaptured, resetCapturedEnvelope } from "./envelope.js";
+import { CAPABILITIES, ENVELOPE_VERSION, capturedEnvelope, onEnvelopeCaptured, resetCapturedEnvelope } from "./envelope.js";
+// Every envelope is checked against its command's schema (logged, never refused), then serialized unchanged.
+import { checkedEnvelopeJson as envelopeJson } from "./contracts/cli.js";
 import { applyClaudeCodeInstall, applyInstall, contextBlock, defaultClaudeCodeSkillDir, planClaudeCodeInstall, planInstall, } from "./skills.js";
 import { GUIDES, guideNamed } from "./guides.js";
 import { parseGithubRepo, previewGithubRepo, cloneGithubRepo, isLargeRepo } from "./onboard.js";
@@ -251,7 +253,7 @@ export const OPERATE_COMMANDS = new Set([
     "run",
     "routine",
     "flows",
-    "config", "chat", "proposals", "mode", "people", "keys",
+    "config", "chat", "proposals", "mode", "chat-approval", "people", "keys",
     "setup",
     "verify",
     "intake",

package/dist/coding-types.d.ts

@@ -1,29 +1,7 @@
 export type { CodingSession, CodingStatus } from './contracts/coding-workspace.js';
 import type { CodingSession } from './contracts/coding-workspace.js';
-export type CodingItem = {
-    id: string;
-    type: string;
-    text: string;
-    status: string | null;
-    clientId?: string;
-};
-export type CodingQuestion = {
-    id: string;
-    header: string;
-    question: string;
-    options: {
-        label: string;
-        description: string;
-    }[];
-};
-export type CodingRequest = {
-    id: string;
-    kind: 'command' | 'files' | 'questions';
-    method: string;
-    title: string;
-    detail: string;
-    questions: CodingQuestion[];
-};
+export type { CodingItem, CodingQuestion, CodingRequest } from './contracts/coding-activity.js';
+import type { CodingItem, CodingRequest } from './contracts/coding-activity.js';
 export type CodingSnapshot = {
     session: CodingSession;
     items: CodingItem[];

package/dist/coding-workspace.js

@@ -10,6 +10,7 @@ import { processMayBeAlive } from './process-liveness.js';
 import { createCodexCodingProvider } from './coding-provider.js';
 import { verifyCodingContext } from './coding-context.js';
 import { codingSessionDocument, parseCodingSessionDocument } from './contracts/coding-workspace.js';
+import { readCodingCustodyWitness, readCodingItem, readCodingRequest, readCodingRpcId } from './contracts/coding-activity.js';
 export class CodingActionError extends Error {
     delivery;
     sessionId;
@@ -163,8 +164,8 @@ export class CodingWorkspace {
     }
     snapshot(id, actor) {
         const session = this.get(id, actor);
-        const items = this.db.prepare('SELECT payload FROM coding_item WHERE session=? ORDER BY position').all(id).map(row => JSON.parse(String(row['payload'])));
-        const requests = this.db.prepare("SELECT payload FROM coding_request WHERE session=? AND status='pending' ORDER BY rowid").all(id).map(row => JSON.parse(String(row['payload'])));
+        const items = this.db.prepare('SELECT payload FROM coding_item WHERE session=? ORDER BY position').all(id).map(row => readCodingItem(String(row['payload'])));
+        const requests = this.db.prepare("SELECT payload FROM coding_request WHERE session=? AND status='pending' ORDER BY rowid").all(id).map(row => readCodingRequest(String(row['payload'])));
         const revision = Number(this.db.prepare('SELECT revision FROM coding_session WHERE id=?').get(id)?.['revision']);
         return { session, items, requests, revision };
     }
@@ -174,8 +175,8 @@ export class CodingWorkspace {
         const session = this.get(id, actor);
         const itemRows = this.db.prepare('SELECT payload FROM coding_item WHERE session=? ORDER BY position DESC LIMIT 101').all(id);
         const requestRows = this.db.prepare("SELECT payload FROM coding_request WHERE session=? AND status='pending' ORDER BY rowid LIMIT 51").all(id);
-        const items = itemRows.slice(0, 100).reverse().map(row => JSON.parse(String(row['payload'])));
-        const requests = requestRows.slice(0, 50).map(row => JSON.parse(String(row['payload'])));
+        const items = itemRows.slice(0, 100).reverse().map(row => readCodingItem(String(row['payload'])));
+        const requests = requestRows.slice(0, 50).map(row => readCodingRequest(String(row['payload'])));
         const revision = Number(this.db.prepare('SELECT revision FROM coding_session WHERE id=?').get(id)?.['revision']);
         return { session, items, requests, revision, truncated: itemRows.length > items.length || requestRows.length > requests.length };
     }
@@ -373,7 +374,7 @@ export class CodingWorkspace {
         }
         else if (event.method === 'item/agentMessage/delta') {
             const id = string(p['itemId']), key = `${session.id}:${id}`;
-            const prior = this.pendingItems.get(key)?.item ?? (() => { const row = this.db.prepare('SELECT payload FROM coding_item WHERE session=? AND id=?').get(session.id, id); return row ? JSON.parse(String(row['payload'])) : { id, type: 'agentMessage', text: '', status: 'inProgress' }; })();
+            const prior = this.pendingItems.get(key)?.item ?? (() => { const row = this.db.prepare('SELECT payload FROM coding_item WHERE session=? AND id=?').get(session.id, id); return row ? readCodingItem(String(row['payload'])) : { id, type: 'agentMessage', text: '', status: 'inProgress' }; })();
             prior.text += string(p['delta']);
             if (prior.text.length > 100_000)
                 prior.text = prior.text.slice(0, 100_000);
@@ -524,8 +525,8 @@ export class CodingWorkspace {
         if (!row)
             return false;
         try {
-            const c = JSON.parse(String(row['payload']));
-            if (c.host !== hostname() || !Array.isArray(c.descendants) || typeof c.observationUnknown !== 'boolean')
+            const c = readCodingCustodyWitness(String(row['payload']));
+            if (c === null || c.host !== hostname())
                 return false;
             if (provenDeadByBootChange(c))
                 return true;
@@ -688,8 +689,8 @@ export class CodingWorkspace {
         if (!session.nativeThreadId || !session.turnId || !busy.has(session.status))
             throw new CodingActionError('There is no running turn to stop.', 'rejected', id);
         for (const row of this.db.prepare("SELECT token,rpc_id,payload FROM coding_request WHERE session=? AND status='pending'").all(id)) {
-            const request = JSON.parse(String(row['payload']));
-            this.native().respond(JSON.parse(String(row['rpc_id'])), request.kind === 'questions' ? { answers: {} } : { decision: 'cancel' });
+            const request = readCodingRequest(String(row['payload']));
+            this.native().respond(readCodingRpcId(String(row['rpc_id'])), request.kind === 'questions' ? { answers: {} } : { decision: 'cancel' });
             this.db.prepare("UPDATE coding_request SET status='withdrawn' WHERE token=?").run(String(row['token']));
         }
         this.save({ ...session, status: 'stopping' });
@@ -700,11 +701,11 @@ export class CodingWorkspace {
         const row = this.db.prepare("SELECT * FROM coding_request WHERE session=? AND token=? AND status='pending'").get(id, token);
         if (!row || session.status !== 'needs-input' || !this.loaded.has(id))
             throw Error('This request is no longer waiting for an answer.');
-        const request = JSON.parse(String(row['payload']));
+        const request = readCodingRequest(String(row['payload']));
         if (!['accept', 'decline', 'cancel'].includes(decision))
             throw Error('Choose an available decision.');
         const result = request.kind === 'questions' ? { answers: decision === 'accept' ? this.validateAnswers(request, answers) : {} } : { decision };
-        this.native().respond(JSON.parse(String(row['rpc_id'])), result);
+        this.native().respond(readCodingRpcId(String(row['rpc_id'])), result);
         this.db.prepare("UPDATE coding_request SET status='answered' WHERE token=?").run(token);
         const remaining = this.db.prepare("SELECT 1 FROM coding_request WHERE session=? AND status='pending'").get(id);
         this.save({ ...session, status: remaining ? 'needs-input' : 'working' });