toolroll 0.9.41 → 0.9.43

package/dist/desktop-update.js

@@ -12,6 +12,7 @@ import { activeUpdateWork, freezeUpdateGate, installUpdateGate, removeUpdateGate
 import { currentDesktopAccess } from "./desktop-access.js";
 import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists, releaseStaleCodingOwner } from "./coding-update.js";
 import { processMayBeAlive } from "./process-liveness.js";
+import { readDesktopRecoveryView, readDesktopUpdateJournal, supervisorPidsOf, updateRequestIs } from "./contracts/update-journal.js";
 /** Loaded on first use (as backup.ts and store.ts do), so modules that only import this one (the console,
  * and tests that load it in a browser-like environment) never need `node:sqlite` itself. */
 function sqlite() {
@@ -60,13 +61,40 @@ function privateFile(file) {
     if (!stat.isFile() || stat.isSymbolicLink() || (process.platform !== "win32" && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())))
         throw Error("The update record must be an owner-only regular file.");
 }
+/** The refusal the hand-written reader gave for the field a saved journal first gets wrong, so callers and people read
+ * the same words; fields it never checked read as an invalid record. */
+function journalRefusal(issue) {
+    const [field, inner] = issue.path.split(/[.[]/);
+    switch (field) {
+        case "old":
+            if (inner === undefined || inner === "path")
+                return "The saved update record is invalid. Preserve it and the app backups; nothing was changed.";
+            return "The saved update paths or build identities are invalid. Nothing was changed.";
+        case "next":
+        case "databaseFile":
+        case "configHash":
+        case "wasRunning":
+        case "backupPath":
+        case "backupHash":
+            return "The saved update paths or build identities are invalid. Nothing was changed.";
+        case "replacementOccurred": return "The recorded replacement state is invalid. Nothing was changed.";
+        case "codingCatalogExpected": return "The recorded coding catalog presence is invalid. Nothing was changed.";
+        case "stoppedPids": return "The recorded service processes are invalid. Nothing was changed.";
+        case "codingBackupPath":
+        case "codingBackupHash": return "The retained coding backup paths or identity are invalid. Nothing was changed.";
+        default: return "The saved update record is invalid. Preserve it and the app backups; nothing was changed.";
+    }
+}
 export function readUpdateJournal(stateDir, retainedReceipt) {
     const file = retainedReceipt ?? journalPath(stateDir);
     if (!existsSync(file))
         return null;
     privateFile(file);
-    const j = JSON.parse(readFileSync(file, "utf8"));
-    if (j.version !== 1 || !/^[a-f0-9-]{36}$/.test(j.id) || j.stateDir !== resolve(stateDir) || !isAbsolute(j.old?.path ?? "") || j.workDir !== join(dirname(j.old.path), ".standing-orders-updates", j.id) || !/^[a-zA-Z0-9.-]+$/.test(j.label) || !["install", "restore"].includes(j.intended) || !["prepared", "draining", "backing-up", "stopping", "installing", "verifying", "rolling-back", "releasing", "complete", "restored", "cancelled", "needs-attention"].includes(j.phase))
+    const read = readDesktopUpdateJournal(JSON.parse(readFileSync(file, "utf8")));
+    if (!read.ok)
+        throw Error(`${journalRefusal(read.issues[0])} (${read.issues.map(issue => issue.line).join("; ")})`);
+    const j = read.value;
+    if (!/^[a-f0-9-]{36}$/.test(j.id) || j.stateDir !== resolve(stateDir) || !isAbsolute(j.old?.path ?? "") || j.workDir !== join(dirname(j.old.path), ".standing-orders-updates", j.id) || !/^[a-zA-Z0-9.-]+$/.test(j.label) || !["install", "restore"].includes(j.intended) || !["prepared", "draining", "backing-up", "stopping", "installing", "verifying", "rolling-back", "releasing", "complete", "restored", "cancelled", "needs-attention"].includes(j.phase))
         throw Error("The saved update record is invalid. Preserve it and the app backups; nothing was changed.");
     if (retainedReceipt && retainedReceipt !== join(j.workDir, "receipt.json"))
         throw Error("The retained recovery receipt is at the wrong path.");
@@ -374,7 +402,7 @@ export function desktopUpdateStatus(stateDir) {
     let recovery = null;
     try {
         privateFile(join(j.workDir, "recovery.json"));
-        recovery = JSON.parse(readFileSync(join(j.workDir, "recovery.json"), "utf8"));
+        recovery = readDesktopRecoveryView(JSON.parse(readFileSync(join(j.workDir, "recovery.json"), "utf8")));
     }
     catch { /* A legacy/manual update has no guardian. */ }
     const wantsAutomatic = recovery?.id === j.id && ["armed", "running", "backoff"].includes(recovery.state ?? "") && !terminal(j.phase);
@@ -389,8 +417,7 @@ export function updateStopRequested(j) {
     if (!existsSync(file))
         return false;
     privateFile(file);
-    const request = JSON.parse(readFileSync(file, "utf8"));
-    if (request.id !== j.id || request.action !== "stop")
+    if (!updateRequestIs(JSON.parse(readFileSync(file, "utf8")), j.id, "stop"))
         throw Error("The saved stop request is invalid. Automatic starts are refused.");
     return true;
 }
@@ -410,7 +437,9 @@ export function requestUpdateRestore(stateDir) {
 function restoreRequested(j) {
     try {
         const request = JSON.parse(readFileSync(join(j.workDir, "request.json"), "utf8"));
-        return request.id === j.id && request.action === "restore";
+        if (request === null)
+            throw Error("The saved restore request is invalid.");
+        return updateRequestIs(request, j.id, "restore");
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -543,8 +572,7 @@ function assertDesktopCodingStopped(j, db) {
 /** The service's own processes, from its supervisor's status file: read before the stop, never after. */
 function servicePids(stateDir) {
     try {
-        const status = JSON.parse(readFileSync(join(stateDir, "controller-supervisor.json"), "utf8"));
-        return [status.supervisorPid, status.controllerPid].filter((pid) => Number.isSafeInteger(pid) && Number(pid) > 1);
+        return supervisorPidsOf(JSON.parse(readFileSync(join(stateDir, "controller-supervisor.json"), "utf8")));
     }
     catch {
         return [];

package/dist/evidence.d.ts

@@ -16,6 +16,7 @@
 import { type ParsedReport, type ReportImage } from "./scout-report.js";
 import { type ParsedProof } from "./proof.js";
 import { type HandoffArtifact } from "./contracts/handoff.js";
+import type { DiffStat } from "./contracts/diff-stat.js";
 export type { HandoffArtifact } from "./contracts/handoff.js";
 import type { Artifact, Store } from "./store.js";
 import type { ExecResult } from "./exec.js";
@@ -229,25 +230,8 @@ export declare function quarantineMailboxes(worktree: string, root: string | nul
 export declare function captureParkEvidence(store: Store, git: (file: string, args: readonly string[], options?: {
     cwd?: string;
 }) => Promise<ExecResult>, worktree: string, baseRevision: string | null, root: string, runId: number, now: Date): Promise<number[]>;
-/** One file's row in the terminal diff-stat. null adds/dels = binary. */
-export type DiffStatFile = {
-    path: string;
-    additions: number | null;
-    deletions: number | null;
-    renamedFrom?: string;
-};
-export type DiffStat = {
-    schema: 1;
-    base: string;
-    head: string;
-    fileCount: number;
-    additions: number;
-    deletions: number;
-    binaryCount: number;
-    files: DiffStatFile[];
-    /** True when the file list was cut to fit the cap — counts stay complete. */
-    filesTruncated: boolean;
-};
+/** The terminal diff-stat and its file rows: src/contracts/diff-stat.ts. */
+export type { DiffStat, DiffStatFile } from "./contracts/diff-stat.js";
 /**
  * Parse `git diff --numstat -z` output. NUL-delimited, so filenames are never
  * guessed out of patch headers (Codex roadmap review, scope cut A.3): plain

package/dist/flow-engine.d.ts

@@ -74,4 +74,6 @@ export declare function decideFlowCard(store: Store, input: {
     entry?: number;
     /** v92: the AI teammate (by handle) deciding a zone it staffs; `actor` is then how it reads in history. */
     teammate?: string;
+    /** Where the decision was made, for its ledger line: "the console", "the command line", "Telegram". */
+    where?: string;
 }, now: Date): FlowDecision;

package/dist/flow-engine.js

@@ -485,6 +485,9 @@ export function decideFlowCard(store, input, now) {
     // v102: a protected project's decisions are a person's, never an AI teammate's.
     if (input.teammate !== undefined && store.approvalRules(flow.repo).protectProject)
         return { ok: false, message: "This project is protected: a person decides here." };
+    // Every decision is one ledger line, the same wherever it was made; only `via` says where.
+    const ledger = (outcome) => store.recordAction({ at: now.toISOString(), actor: input.actor, repo: flow.repo, taskId: card.primaryTask, runId: null,
+        action: "flow decision", outcome, source: "request", detail: `${flow.name} · card ${card.id} · ${stage.title}${input.teammate === undefined ? "" : ` · teammate ${input.teammate}`} · via ${input.where ?? "Toolroll"}` });
     if (input.decision === "approve") {
         // An edited draft replaces the one Claude wrote, so the steps after this send what the person approved.
         const draft = draftFor(definition, stage);
@@ -498,9 +501,12 @@ export function decideFlowCard(store, input, now) {
         }
         if (stage.next === null) {
             store.updateFlowCard(card.id, { state: "done", waiting: null }, now);
+            ledger("approved");
             return { ok: true, said: "Approved. The card is done." };
         }
-        store.moveFlowCard(card.id, { to: stage.next, outcome: "approved", actor: input.actor, note: input.note, expectEntry: card.entry }, now);
+        if (!store.moveFlowCard(card.id, { to: stage.next, outcome: "approved", actor: input.actor, note: input.note, expectEntry: card.entry }, now))
+            return { ok: false, message: "That card has moved on since; nothing was changed." };
+        ledger("approved");
         const title = definition.stages.find(one => one.id === stage.next)?.title ?? stage.next;
         if (card.owner !== null)
             notifyPeople(store, card, [card.owner], input.actor, { key: `approved:${card.entry}`, subject: `${input.actor} approved “${card.title}”`, body: `${stage.title}: approved. It moves to ${title}.${input.note === null || input.note.trim() === "" ? "" : `\n\n${input.note.trim()}`}` }, now);
@@ -512,7 +518,9 @@ export function decideFlowCard(store, input, now) {
         return { ok: false, message: "Say what should change." };
     const target = definition.stages.find(one => one.id === stage.onFail);
     const revision = revisionWithNote(store, card, target, input.note.trim(), input.actor, input.repos, input.evidenceRoot, now);
-    store.moveFlowCard(card.id, { to: stage.onFail, outcome: "sent-back", actor: input.actor, note: input.note.trim(), ...(revision === null ? {} : { task: revision }), expectEntry: card.entry }, now);
+    if (!store.moveFlowCard(card.id, { to: stage.onFail, outcome: "sent-back", actor: input.actor, note: input.note.trim(), ...(revision === null ? {} : { task: revision }), expectEntry: card.entry }, now))
+        return { ok: false, message: "That card has moved on since; nothing was changed." };
+    ledger("sent-back");
     if (card.owner !== null)
         notifyPeople(store, card, [card.owner], input.actor, { key: `sent-back:${card.entry}`, subject: `${input.actor} sent “${card.title}” back`, body: `Sent back to ${target?.title ?? stage.onFail}:\n\n${input.note.trim()}`, attention: true }, now);
     return { ok: true, said: revision === null ? `Sent back to ${target?.title ?? stage.onFail} with your note.` : `Sent back to ${target?.title ?? stage.onFail}: a revision was made with your note.` };

package/dist/flow-triggers.js

@@ -42,6 +42,7 @@ import { mailboxAccess, mailCursorOf, mailCursorText, readThroughImap } from "./
 import { readFlowSecrets } from "./flow-secrets.js";
 import { tmpdir } from "node:os";
 import { envValue } from "./names.js";
+import { linearLabelNames, readFormSubmission, readGithubEvent, readGithubIssue, readGithubIssueEventList, readGithubIssueList, readGithubRun, readGithubRunList, readInboundMail, readLinearAnswer, readLinearEvent, readLinearIssue, readWebhookPayload } from "./contracts/trigger-payloads.js";
 export { FLOW_TRIGGER_KINDS };
 export const CHAT_APP_NAMES = { slack: "Slack", discord: "Discord", teams: "Teams", telegram: "Telegram" };
 /** What each kind is called on the canvas. */
@@ -771,7 +772,7 @@ async function fetchMail(store, config, trigger, io, now) {
     if (!read.ok)
         return { ok: false, problem: read.said };
     const own = signed.address.toLowerCase();
-    const items = read.mails.filter(mail => mailMatches(config, mail)).map(mail => {
+    const items = read.mails.map(readInboundMail).filter(mail => mailMatches(config, mail)).map(mail => {
         const key = `mail:${read.at.validity}:${mail.uid}`, at = mailCursorText({ validity: read.at.validity, uid: mail.uid });
         const label = `Email from ${mail.from || "an unknown sender"}`.slice(0, 120);
         // Machines and this account itself never start cards: a flow that answers mail mustn't answer them.
@@ -793,44 +794,42 @@ async function fetchMail(store, config, trigger, io, now) {
         : read.renumbered ? "The mail server renumbered this folder; watching it from now." : undefined;
     return { ok: true, items, cursor: mailCursorText(read.at), more: read.more, ...(said === undefined ? {} : { said }) };
 }
-const text = (value) => typeof value === "string" ? value : "";
-const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
 /** A GitHub issue or pull request as a card, or why it is left out; null when it doesn't match. */
 export function githubItem(config, raw, what) {
-    const item = record(raw);
-    const number = Number(item["number"]);
+    const item = readGithubIssue(raw);
+    const number = Number(item.number);
     if (!Number.isSafeInteger(number))
         return null;
-    if (what === "issue" && item["pull_request"] !== undefined)
+    if (what === "issue" && item.pull_request !== undefined)
         return null;
-    if (what === "pull" && item["draft"] === true)
+    if (what === "pull" && item.draft === true)
         return null;
-    const labels = Array.isArray(item["labels"]) ? item["labels"].map(one => text(record(one)["name"]).toLowerCase()) : [];
+    const labels = (item.labels ?? []).map(one => (one.name ?? "").toLowerCase());
     if (config.label !== null && !labels.includes(config.label.toLowerCase()))
         return null;
     const label = what === "issue" ? `GitHub issue #${number}` : `Pull request #${number}`;
-    const key = `${what}:${number}`, at = text(item["updated_at"]) || null;
-    if (config.from === "team" && !TEAM.has(text(item["author_association"])))
+    const key = `${what}:${number}`, at = item.updated_at || null;
+    if (config.from === "team" && !TEAM.has(item.author_association ?? ""))
         return { key, skip: "opened by someone without write access", label, at };
-    const login = text(record(item["user"])["login"]) || "someone";
-    const branches = what === "pull" ? ` (${text(record(item["head"])["ref"])} → ${text(record(item["base"])["ref"])})` : "";
-    return { key, at, title: text(item["title"]) || label,
-        description: `From ${what === "issue" ? "GitHub issue" : "pull request"} #${number} by @${login}${branches}:\n\n${text(item["body"])}`.trim().slice(0, 4000),
-        source: { kind: "github", label, url: text(item["html_url"]) || null } };
+    const login = item.user?.login || "someone";
+    const branches = what === "pull" ? ` (${item.head?.ref ?? ""} → ${item.base?.ref ?? ""})` : "";
+    return { key, at, title: item.title || label,
+        description: `From ${what === "issue" ? "GitHub issue" : "pull request"} #${number} by @${login}${branches}:\n\n${item.body ?? ""}`.trim().slice(0, 4000),
+        source: { kind: "github", label, url: item.html_url || null } };
 }
 /** A failed workflow run as a card: one card per failing commit on the watched branch. */
 export function githubRunItem(config, raw) {
-    const run = record(raw);
-    if (text(run["conclusion"]) !== "failure" || (config.branch !== null && text(run["head_branch"]) !== config.branch))
+    const run = readGithubRun(raw);
+    if (run.conclusion !== "failure" || (config.branch !== null && (run.head_branch ?? "") !== config.branch))
         return null;
-    const sha = text(run["head_sha"]);
+    const sha = run.head_sha ?? "";
     if (sha === "")
         return null;
-    const name = text(run["name"]) || "Checks";
-    const commit = text(run["display_title"]);
-    return { key: `checks:${sha}`, at: text(run["created_at"]) || null, title: `Checks failed on ${config.branch}: ${name}`,
-        description: `From GitHub: “${name}” failed on ${config.branch} at ${sha.slice(0, 7)}${commit === "" ? "" : ` (${commit})`}.\nRun: ${text(run["html_url"])}`,
-        source: { kind: "github", label: `Failed check on ${config.branch}`, url: text(run["html_url"]) || null } };
+    const name = run.name || "Checks";
+    const commit = run.display_title ?? "";
+    return { key: `checks:${sha}`, at: run.created_at || null, title: `Checks failed on ${config.branch}: ${name}`,
+        description: `From GitHub: “${name}” failed on ${config.branch} at ${sha.slice(0, 7)}${commit === "" ? "" : ` (${commit})`}.\nRun: ${run.html_url ?? ""}`,
+        source: { kind: "github", label: `Failed check on ${config.branch}`, url: run.html_url || null } };
 }
 async function fetchGitHub(config, trigger, gh) {
     const since = trigger.cursor ?? trigger.createdAt;
@@ -861,20 +860,19 @@ async function fetchGitHub(config, trigger, gh) {
     }
     const created = Date.parse(trigger.createdAt);
     if (config.watch === "checks") {
-        const runs = (Array.isArray(record(body)["workflow_runs"]) ? record(body)["workflow_runs"] : []).filter(one => Date.parse(text(record(one)["created_at"])) > created);
+        const runs = (readGithubRunList(body).workflow_runs ?? []).filter(one => Date.parse(one.created_at ?? "") > created);
         const items = runs.reverse().map(one => githubRunItem(config, one)).filter((one) => one !== null);
         return { ok: true, items: unique(items), cursor: trigger.cursor };
     }
-    const list = Array.isArray(body) ? body : [];
     if (labelEvents) {
-        const labeled = list.filter(one => text(record(one)["event"]) === "labeled" && text(record(record(one)["label"])["name"]).toLowerCase() === config.label.toLowerCase()
-            && Date.parse(text(record(one)["created_at"])) > Date.parse(since)).reverse();
-        const items = labeled.map(one => { const item = githubItem(config, record(one)["issue"], "issue"); return item === null ? null : { ...item, at: text(record(one)["created_at"]) || null }; }).filter((one) => one !== null);
-        return { ok: true, items: unique(items), cursor: labeled.map(one => text(record(one)["created_at"])).at(-1) ?? trigger.cursor };
+        const labeled = readGithubIssueEventList(body).filter(one => one.event === "labeled" && (one.label?.name ?? "").toLowerCase() === config.label.toLowerCase()
+            && Date.parse(one.created_at ?? "") > Date.parse(since)).reverse();
+        const items = labeled.map(one => { const item = githubItem(config, one.issue, "issue"); return item === null ? null : { ...item, at: one.created_at || null }; }).filter((one) => one !== null);
+        return { ok: true, items: unique(items), cursor: labeled.map(one => one.created_at ?? "").at(-1) ?? trigger.cursor };
     }
     // New issues and pull requests: opened after the trigger was added, oldest first; the key keeps each to one card.
     const what = config.watch === "pulls" ? "pull" : "issue";
-    const items = list.filter(one => Date.parse(text(record(one)["created_at"])) > created).reverse().map(one => githubItem(config, one, what)).filter((one) => one !== null);
+    const items = readGithubIssueList(body).filter(one => Date.parse(one.created_at ?? "") > created).reverse().map(one => githubItem(config, one, what)).filter((one) => one !== null);
     return { ok: true, items, cursor: trigger.cursor };
 }
 const unique = (items) => items.filter((item, index) => items.findIndex(one => one.key === item.key) === index);
@@ -882,21 +880,20 @@ export const LINEAR_URL = "https://api.linear.app/graphql";
 export const LINEAR_QUERY = "query FlowTrigger($filter: IssueFilter) { issues(filter: $filter, first: 50, orderBy: updatedAt) { nodes { identifier title description url updatedAt state { name } team { key } labels { nodes { name } } } } }";
 /** A Linear issue as a card; null when it doesn't match the trigger. */
 export function linearItem(config, raw) {
-    const issue = record(raw);
-    const identifier = text(issue["identifier"]);
+    const issue = readLinearIssue(raw);
+    const identifier = issue.identifier ?? "";
     if (identifier === "")
         return null;
-    const labelNodes = Array.isArray(issue["labels"]) ? issue["labels"] : Array.isArray(record(issue["labels"])["nodes"]) ? record(issue["labels"])["nodes"] : [];
-    const labels = labelNodes.map(one => text(record(one)["name"]).toLowerCase());
-    if (config.team !== null && text(record(issue["team"])["key"]).toUpperCase() !== config.team)
+    const labels = linearLabelNames(issue).map(one => one.toLowerCase());
+    if (config.team !== null && (issue.team?.key ?? "").toUpperCase() !== config.team)
         return null;
-    if (config.state !== null && text(record(issue["state"])["name"]).toLowerCase() !== config.state.toLowerCase())
+    if (config.state !== null && (issue.state?.name ?? "").toLowerCase() !== config.state.toLowerCase())
         return null;
     if (config.label !== null && !labels.includes(config.label.toLowerCase()))
         return null;
-    return { key: `linear:${identifier}`, at: text(issue["updatedAt"]) || null, title: text(issue["title"]) || identifier,
-        description: `From Linear ${identifier}:\n\n${text(issue["description"])}`.trim().slice(0, 4000),
-        source: { kind: "linear", label: `Linear ${identifier}`, url: text(issue["url"]) || null } };
+    return { key: `linear:${identifier}`, at: issue.updatedAt || null, title: issue.title || identifier,
+        description: `From Linear ${identifier}:\n\n${issue.description ?? ""}`.trim().slice(0, 4000),
+        source: { kind: "linear", label: `Linear ${identifier}`, url: issue.url || null } };
 }
 async function fetchLinear(config, trigger, io) {
     const key = readLinearKey(io.dir);
@@ -917,22 +914,22 @@ async function fetchLinear(config, trigger, io) {
     catch {
         return { ok: false, problem: "Couldn't reach Linear." };
     }
-    let body;
+    let raw;
     try {
-        body = record(await response.json());
+        raw = await response.json();
     }
     catch {
         return { ok: false, problem: `Linear answered ${response.status} and it couldn't be read.` };
     }
-    const errors = Array.isArray(body["errors"]) ? body["errors"].map(one => text(record(one)["message"])) : [];
+    const body = readLinearAnswer(raw);
+    const errors = (body.errors ?? []).map(one => one.message ?? "");
     if (response.status === 401 || errors.some(one => /authenticat|api key/i.test(one)))
         return { ok: false, problem: "Linear didn't accept the key. Add a new one on this flow's Triggers panel." };
     if (!response.ok || errors.length > 0)
         return { ok: false, problem: `Linear said: ${(errors[0] ?? `status ${response.status}`).slice(0, 160)}` };
-    const nodes = record(record(record(body["data"])["issues"]))["nodes"];
-    const issues = (Array.isArray(nodes) ? nodes : []).sort((a, b) => text(record(a)["updatedAt"]).localeCompare(text(record(b)["updatedAt"])));
+    const issues = (body.data?.issues?.nodes ?? []).sort((a, b) => (a.updatedAt ?? "").localeCompare(b.updatedAt ?? ""));
     const items = issues.map(one => linearItem(config, one)).filter((one) => one !== null);
-    return { ok: true, items, cursor: issues.map(one => text(record(one)["updatedAt"])).filter(one => one !== "").at(-1) ?? trigger.cursor };
+    return { ok: true, items, cursor: issues.map(one => one.updatedAt ?? "").filter(one => one !== "").at(-1) ?? trigger.cursor };
 }
 const header = (delivery, name) => { const value = delivery.headers[name]; return Array.isArray(value) ? value[0] ?? "" : value ?? ""; };
 function sameHex(expected, given) {
@@ -963,8 +960,8 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
         const signature = header(delivery, "x-hub-signature-256");
         if (secret === null || !sameHex(`sha256=${createHmac("sha256", secret).update(delivery.body).digest("hex")}`, signature))
             return { status: 401, said: "Signature doesn't match." };
-        const event = header(delivery, "x-github-event"), body = record(payload), action = text(body["action"]);
-        const repository = text(record(body["repository"])["full_name"]);
+        const event = header(delivery, "x-github-event"), body = readGithubEvent(payload), action = body.action ?? "";
+        const repository = body.repository?.full_name ?? "";
         if (event === "ping") {
             note("GitHub connected.");
             return { status: 200, said: "Connected." };
@@ -972,10 +969,10 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
         if (repository.toLowerCase() !== config.repo.toLowerCase())
             return { status: 202, said: "Not this repository." };
         // A label trigger takes the moment its label is added (or an issue opened with it); a plain one takes new issues.
-        const labeledNow = action === "labeled" && config.label !== null && text(record(body["label"])["name"]).toLowerCase() === config.label.toLowerCase();
-        const found = config.watch === "issues" && event === "issues" && (action === "opened" || labeledNow) ? githubItem(config, body["issue"], "issue")
-            : config.watch === "pulls" && event === "pull_request" && ["opened", "ready_for_review", "labeled", "reopened"].includes(action) ? githubItem(config, body["pull_request"], "pull")
-                : config.watch === "checks" && event === "workflow_run" && action === "completed" ? githubRunItem(config, body["workflow_run"]) : null;
+        const labeledNow = action === "labeled" && config.label !== null && (body.label?.name ?? "").toLowerCase() === config.label.toLowerCase();
+        const found = config.watch === "issues" && event === "issues" && (action === "opened" || labeledNow) ? githubItem(config, body.issue, "issue")
+            : config.watch === "pulls" && event === "pull_request" && ["opened", "ready_for_review", "labeled", "reopened"].includes(action) ? githubItem(config, body.pull_request, "pull")
+                : config.watch === "checks" && event === "workflow_run" && action === "completed" ? githubRunItem(config, body.workflow_run) : null;
         items = found === null ? [] : [found];
     }
     else if (config.kind === "linear") {
@@ -984,23 +981,26 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
             return { status: 401, said: "Paste Linear's signing secret on the flow's Triggers panel first." };
         if (!sameHex(createHmac("sha256", secret).update(delivery.body).digest("hex"), header(delivery, "linear-signature")))
             return { status: 401, said: "Signature doesn't match." };
-        const body = record(payload), sent = Number(body["webhookTimestamp"]);
+        const body = readLinearEvent(payload), sent = Number(body.webhookTimestamp);
         if (!Number.isFinite(sent) || Math.abs(now.getTime() - sent) > 5 * 60_000)
             return { status: 401, said: "Too old." };
-        if (text(body["type"]) !== "Issue" || !["create", "update"].includes(text(body["action"])))
+        if (body.type !== "Issue" || !["create", "update"].includes(body.action ?? ""))
             return { status: 202, said: "Ignored." };
         // A state trigger fires when the issue arrives in that state, not on every later edit there.
-        const moved = text(body["action"]) === "create" || record(body["updatedFrom"])["stateId"] !== undefined || config.state === null;
-        const found = moved ? linearItem(config, body["data"]) : null;
+        const moved = body.action === "create" || body.updatedFrom?.stateId !== undefined || config.state === null;
+        const found = moved ? linearItem(config, body.data) : null;
         items = found === null ? [] : [found];
     }
     else if (config.kind === "webhook") {
-        const pick = (path) => path === null ? null : path.split(".").reduce((node, part) => record(node)[part], payload);
+        // Any JSON, kept as sent: the trigger's own paths are picked from it, and it is shown whole when they find no text.
+        const body = readWebhookPayload(payload);
+        const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+        const pick = (path) => path === null ? null : path.split(".").reduce((node, part) => record(node)[part], body);
         const title = pick(config.titleField ?? "title") ?? pick("summary") ?? pick("message");
         const bodyText = pick(config.bodyField ?? "description") ?? pick("body") ?? pick("text");
         const id = header(delivery, "x-request-id") || header(delivery, "x-delivery-id") || header(delivery, "idempotency-key") || createHash("sha256").update(delivery.body).digest("hex");
         items = [{ key: `hook:${id.slice(0, 120)}`, at: null, title: typeof title === "string" && title.trim() !== "" ? title : config.title,
-                description: `From a webhook:\n\n${typeof bodyText === "string" ? bodyText : JSON.stringify(payload, null, 2)}`.slice(0, 4000),
+                description: `From a webhook:\n\n${typeof bodyText === "string" ? bodyText : JSON.stringify(body, null, 2)}`.slice(0, 4000),
                 source: { kind: "webhook", label: "Webhook", url: null } }];
     }
     if (items.length === 0)
@@ -1081,13 +1081,14 @@ export function receiveFlowForm(store, token, fields, now) {
     const again = `<p><a href="${esc(FORM_PATH + token)}">Send another</a></p>`;
     const thanks = formHtml(config.label, `<p>Thanks — it's been sent.</p>${again}`);
     // A filled trap, or a page posted faster than a person could, gets thanks and makes nothing.
-    const shown = Number(fields.get("t"));
-    if ((fields.get("website") ?? "") !== "" || !Number.isFinite(shown) || now.getTime() - shown < 2000 || now.getTime() - shown > 86_400_000)
+    const form = readFormSubmission(fields, config.questions.length);
+    const shown = Number(form.t);
+    if ((form.website ?? "") !== "" || !Number.isFinite(shown) || now.getTime() - shown < 2000 || now.getTime() - shown > 86_400_000)
         return { status: 200, html: thanks };
     const recent = store.handle.prepare("SELECT COUNT(*) AS n FROM flow_trigger_event WHERE trigger = ? AND key LIKE 'form:%' AND at > ?").get(trigger.id, new Date(now.getTime() - 3_600_000).toISOString());
     if (Number(recent?.["n"] ?? 0) >= FORM_CARDS_PER_HOUR)
         return { status: 429, html: formHtml(config.label, `<p>Too many sent in the last hour. Try again later.</p>`) };
-    const answers = config.questions.map((_question, index) => (fields.get(`a${index}`) ?? "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "").trim().slice(0, index === 0 ? 200 : 3000));
+    const answers = form.answers.map((answer, index) => (answer ?? "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "").trim().slice(0, index === 0 ? 200 : 3000));
     if (answers[0] === "")
         return { status: 400, html: formHtml(config.label, `<p>Answer “${esc(config.questions[0])}” first.</p>${again}`) };
     const details = config.questions.slice(1).map((question, index) => answers[index + 1] === "" ? null : `${question}\n${answers[index + 1]}`).filter(one => one !== null).join("\n\n");

package/dist/flows-cli.d.ts

@@ -188,6 +188,34 @@ export declare const FLOWS_DESCRIPTORS: readonly [{
         readonly takesValue: true;
         readonly meaning: 'a zone id or name';
     }];
+}, {
+    readonly action: 'card approve';
+    readonly synopsis: "approve a card waiting at a Person decides step (or pick --option at a Person chooses step), as the console's Approve does";
+    readonly mutation: 'identity-idempotent';
+    readonly positionals: readonly ['flow', 'card'];
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        readonly name: 'option';
+        readonly takesValue: true;
+        readonly meaning: "at a Person chooses step: the option's words or its number";
+    }];
+}, {
+    readonly action: 'card send-back';
+    readonly synopsis: "send a waiting card back with a note, as the console's Send back (or a reply at a Person chooses step) does";
+    readonly mutation: 'identity-idempotent';
+    readonly positionals: readonly ['flow', 'card'];
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        readonly name: 'note';
+        readonly takesValue: true;
+        readonly meaning: 'what should change';
+    }];
 }, {
     readonly action: 'export';
     readonly synopsis: 'write a flow as a *.toolroll-flow.json file: zones, paths, trigger settings and scripts; never secrets, webhook addresses, names or cards';

package/dist/flows-cli.js

@@ -10,7 +10,8 @@
 import { readFileSync, statSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { envelopeJson } from './envelope.js';
-import { addCardToFlow, advanceFlows, crossProjectProblem, flowDefinitionOf } from './flow-engine.js';
+import { addCardToFlow, advanceFlows, crossProjectProblem, decideFlowCard, flowDefinitionOf } from './flow-engine.js';
+import { chooseFlowCard } from './flow-send.js';
 import { saveScript } from './flow-scripts.js';
 import { exportFlow, fetchFlowFile, FLOW_FILE_MAX_BYTES, FlowFileError, importFlow, parseFlowFile, planFlowImport } from './flow-share.js';
 import { STARTER_FLOWS, starterFlowOf, starterOf, startersFor, starterTerms, switchOnStarter } from './flow-starters.js';
@@ -51,6 +52,10 @@ export const FLOWS_DESCRIPTORS = [
             { name: 'title', takesValue: true, meaning: "the card's title" },
             { name: 'description', takesValue: true, meaning: 'its details' },
             { name: 'zone', takesValue: true, meaning: 'a zone id or name' }] },
+    { action: 'card approve', synopsis: "approve a card waiting at a Person decides step (or pick --option at a Person chooses step), as the console's Approve does", mutation: 'identity-idempotent', positionals: ['flow', 'card'], flags: [...write,
+            { name: 'option', takesValue: true, meaning: "at a Person chooses step: the option's words or its number" }] },
+    { action: 'card send-back', synopsis: "send a waiting card back with a note, as the console's Send back (or a reply at a Person chooses step) does", mutation: 'identity-idempotent', positionals: ['flow', 'card'], flags: [...write,
+            { name: 'note', takesValue: true, meaning: 'what should change' }] },
     { action: 'export', synopsis: 'write a flow as a *.toolroll-flow.json file: zones, paths, trigger settings and scripts; never secrets, webhook addresses, names or cards', mutation: 'none', positionals: ['flow'], flags: [...read,
             { name: 'out', takesValue: true, meaning: 'write the file here (default: print it)' }] },
     { action: 'import', synopsis: 'make a flow from a flow file or a gist/GitHub https address; previews in plain words until --yes; triggers arrive off and scripts wait for approval', mutation: 'unkeyed', positionals: ['file'], flags: [...write, yes, repo,
@@ -407,6 +412,43 @@ export async function runFlowsCommand(positional, flags, context) {
         const card = store.getFlowCard(added.card);
         return ok({ applied: true, card: card === null ? { id: added.card } : cardOf(definition, card), said: added.said }, [`${added.said} Card #${added.card}.`]);
     }
+    if (action === 'card approve' || action === 'card send-back') {
+        // The console's own doors (decideFlowCard, chooseFlowCard): the same decider, visit and project checks, and the same card history.
+        const approving = action === 'card approve';
+        const note = text('note')?.trim() ?? null;
+        if (args[1] === undefined || (!approving && (note === null || note === '')))
+            return fail('usage', approving ? 'Use flows card approve <flow> <card> [--option <words|number>].' : 'Use flows card send-back <flow> <card> --note "<what should change>".', EXIT.usage);
+        const card = /^[1-9][0-9]{0,9}$/.test(args[1]) ? store.getFlowCard(Number(args[1])) : null;
+        if (card === null || card.flow !== flow.id)
+            return refuse(flow.repo, 'unknown-card', `Flow #${flow.id} has no card #${args[1]}. toolroll flows show ${flow.id} lists its cards.`);
+        const stage = definition.stages.find(one => one.id === card.stage);
+        let decided;
+        if (stage?.kind === 'choose') {
+            if (approving) {
+                const given = text('option')?.trim() ?? '';
+                const options = stage.options ?? [];
+                const choice = /^[1-9]$/.test(given) && Number(given) <= options.length ? Number(given) - 1 : options.findIndex(one => one.label.toLowerCase() === given.toLowerCase());
+                if (given === '' || choice < 0)
+                    return refuse(flow.repo, 'choose-option', `${stage.title} asks for a choice: give --option with one of ${options.map((one, at) => `${at + 1} “${one.label}”`).join(', ')}.`, EXIT.usage);
+                decided = chooseFlowCard(store, { card: card.id, entry: card.entry, choice, label: options[choice].label, note: null, actor: who, where: 'the command line', repos: reachable, evidenceRoot: context.evidenceRoot }, now);
+            }
+            else
+                decided = chooseFlowCard(store, { card: card.id, entry: card.entry, choice: null, note, actor: who, where: 'the command line', repos: reachable, evidenceRoot: context.evidenceRoot }, now);
+        }
+        else if (stage?.kind === 'approval') {
+            if (text('option') !== null)
+                return fail('usage', '--option is for a Person chooses step; this card waits for a decision.', EXIT.usage);
+            decided = decideFlowCard(store, { card: card.id, decision: approving ? 'approve' : 'send-back', note, actor: who, repos: reachable, evidenceRoot: context.evidenceRoot, entry: card.entry, where: 'the command line' }, now);
+        }
+        else
+            return refuse(flow.repo, 'not-waiting', card.state === 'active' ? `Card #${card.id} isn't waiting for a decision; it's in ${stage?.title ?? card.stage}.` : `Card #${card.id} is ${card.state}; nothing is waiting on it.`);
+        if (!decided.ok)
+            return refuse(flow.repo, 'refused', decided.message);
+        record(flow.repo, 'accepted', `flow #${flow.id} card #${card.id} · ${stage.title}`);
+        settle(flow.repo);
+        const after = store.getFlowCard(card.id);
+        return ok({ applied: true, card: after === null ? { id: card.id } : cardOf(definition, after), said: decided.said }, [decided.said]);
+    }
     if (action === 'trigger add') {
         if (args[1] === undefined)
             return fail('usage', 'Use flows trigger add <flow> <json|file|->, like \'{"kind":"schedule","schedule":"daily 09:00","title":"Standup"}\'.', EXIT.usage);

package/dist/guides.js

@@ -141,6 +141,8 @@ applies the console's rules exactly.
   \`flows trigger pause|resume|remove|check <id> <trigger>\`; \`flows script
   save --repo PATH --name <n> (--file <path in project> | --body <file>)
   --about "<line>"\`; \`flows card add <id> --title <t> [--zone <z>]\`;
+  \`flows card approve <id> <card>\` and \`flows card send-back <id> <card>
+  --note <text>\` only when the person asked for that decision;
   \`flows archive <id>\`.
 - create, edit, archive and trigger add answer with a preview
   (\`applied: false\`, \`terms\`) until \`--yes\`. Show the person the terms

package/dist/mate-contract.js

@@ -16,7 +16,7 @@ export const MATE_CONTRACT = [
     "Investigate before reporting a limitation: when a tool refuses or something looks unsupported, read get_capabilities and the relevant skill (get_skills, then that skill's instructions) before telling the owner it can't be done. Then say what you checked, what is missing, and the one next step.",
     "Ask rarely: only when the answer changes the work and you cannot settle it from tools or project memory. Then use ask_owner: one question, 2-4 short options (Something else is added), shown as buttons after your reply; the tapped option comes back as the owner's next message. Keep your reply to one short line leading into it, and do not repeat the options in your text.",
     "propose_* drafts, never completes. Confirmation and execution approvals still apply. Never request credentials in chat. Read get_task currentExecution before acting; revisions retain task identity and old cards retain exact targets.",
-    "The operator talks plainly and names work by what it is about ('the login page', 'that payout fix'), rarely by id. Use the current task when there is one; otherwise find it with list_tasks search, and if several fit, ask which by title. When they want work moved forward, read get_task and draft its next step: changes to a result still waiting on them → propose_review revise; guidance for work in progress → propose_steer; stopped → resume and failed → retry with propose_task_action; waiting for approval → show_control approval; new work, or more on something already completed → propose_task in the same project, naming the earlier task in its goal.",
+    "The operator talks plainly and names work by what it is about ('the login page', 'that payout fix'), rarely by id. Use the current task when there is one; otherwise find it with list_tasks search, and if several fit, ask which by title. When they want work moved forward, read get_task and draft its next step: changes to a result still waiting on them → propose_review revise; guidance for work in progress → propose_steer; stopped → resume and failed → retry with propose_task_action; waiting for approval, or 'approve X' → offer_approval for exactly that plan or flow card, which sends its own Approve buttons to the owner's chat (their tap approves it; you never do), and only when it says why not, say that in one line and show_control approval; new work, or more on something already completed → propose_task in the same project, naming the earlier task in its goal.",
     "Talk like a colleague in everyday words: task titles, 'the changes', 'the checks', 'try again'. Never say execution, run, scope, digest, dispatch or lane to the operator; say what happens next and what they can do.",
     "Read get_result for the exact execution/run; page nextFeedbackOffset. propose_review revise requests changes; note saves feedback. Use read notes only; clarify ambiguous intent. Ready is a saved result, not a reviewer stage. Historical missing assessments never require rerunning work. Failed checks and missing files remain visible; completion never deploys or changes checks.",
     "For screenshots, call get_result_images for that exact execution and run. On Telegram say they follow, never that they were delivered; elsewhere name result and image count. Limit 8/reply. If nextImageOffset exists, name remaining count; call it again with that offset or with the image ids it listed when asked. Select a newer revision explicitly; never describe unselected images or expose paths.",