toolroll 0.9.42 → 0.9.44

package/dist/cli-http.js

@@ -0,0 +1,143 @@
+import { contractRow, fileArguments, STEP_UP_MESSAGE } from './remote-command.js';
+/** Inlined file contents, summed as UTF-8 bytes. */
+export const CLI_FILES_BYTES = 256 * 1024;
+/** The whole JSON body: the files plus argv and JSON escaping headroom. */
+export const CLI_REQUEST_BYTES = 2 * CLI_FILES_BYTES;
+const ARGV_MAX = 256;
+const ARG_BYTES = 16 * 1024;
+const FILES_MAX = 16;
+function send(response, status, value) {
+    if (response.destroyed || response.writableEnded)
+        return;
+    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+    response.end(JSON.stringify(value));
+}
+async function body(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.length;
+        if (size > CLI_REQUEST_BYTES)
+            throw new Error('too-large');
+        chunks.push(bytes);
+    }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+}
+/** Decode the request's shape and byte limits. The endpoint checks file references against its command policy. */
+export function cliRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return { problem: 'Send {argv, files}.' };
+    const row = value;
+    if (!Object.keys(row).every(key => key === 'argv' || key === 'files'))
+        return { problem: 'Send only argv and files.' };
+    const argv = row.argv;
+    if (!Array.isArray(argv) || argv.length === 0 || argv.length > ARGV_MAX || !argv.every(one => typeof one === 'string' && Buffer.byteLength(one) <= ARG_BYTES && !one.includes('\0')))
+        return { problem: 'argv must be 1–256 strings.' };
+    const files = row.files ?? {};
+    if (!files || typeof files !== 'object' || Array.isArray(files))
+        return { problem: 'files must map an argument to its contents.' };
+    const entries = Object.entries(files);
+    if (entries.length > FILES_MAX)
+        return { problem: 'Too many files.' };
+    let size = 0;
+    const kept = Object.create(null);
+    for (const [key, content] of entries) {
+        if (typeof content !== 'string' || key === '' || key.includes('\0'))
+            return { problem: 'files must map file paths to text contents.' };
+        size += Buffer.byteLength(content);
+        if (size > CLI_FILES_BYTES)
+            return { problem: 'Files are limited to 256 KiB in total.', tooLarge: true };
+        kept[key] = content;
+    }
+    return { argv: argv, files: kept };
+}
+/** The longest one request may hold the server: the client polls again for longer waits. */
+export const CLI_WAIT_SECONDS = 25;
+function longPollBounded(argv) {
+    const words = argv.filter(one => !one.startsWith('-'));
+    if (words[0] !== 'task' || words[1] !== 'wait')
+        return true;
+    const at = argv.indexOf('--timeout'), given = at < 0 ? NaN : Number(argv[at + 1]);
+    return argv.filter(one => one === '--timeout').length === 1 && Number.isFinite(given) && given >= 0 && given <= CLI_WAIT_SECONDS;
+}
+/** Handles exactly `/api/cli`; false for any other path. */
+export async function handleCliHttp(request, response, options) {
+    const url = new URL(request.url ?? '/', 'http://standing-orders.local');
+    if (url.pathname !== '/api/cli')
+        return false;
+    const reject = (status, code, message) => { send(response, status, { ok: false, code, message }); request.resume(); return true; };
+    if (url.search !== '' || url.username !== '' || url.password !== '')
+        return reject(400, 'credentials-in-url', 'Send the command in the request body; nothing travels in the URL.');
+    if (request.method !== 'POST')
+        return reject(405, 'method-not-allowed', 'Use POST.');
+    // A browser always names its page. The remote CLI never does, so a page can never drive this endpoint.
+    if (request.headers.origin !== undefined)
+        return reject(403, 'browser-origin', 'Remote commands come from the CLI, not a browser.');
+    const names = request.rawHeaders.filter((_value, index) => index % 2 === 0).map(name => name.toLowerCase());
+    const count = names.filter(name => name === 'authorization').length;
+    if (count > 1)
+        return reject(400, 'ambiguous-credentials', 'Send one authorization header.');
+    if (names.includes('cookie'))
+        return reject(400, 'cookie-refused', 'Remote commands sign in with an API token only.');
+    if (!/^Bearer so_\S+$/.test(request.headers.authorization ?? ''))
+        return reject(401, 'unauthenticated', 'Sign in with your API token: toolroll connect <origin> --token-stdin.');
+    if (request.headers['content-type']?.split(';')[0]?.trim() !== 'application/json')
+        return reject(415, 'invalid-content-type', 'Send application/json.');
+    if (Number(request.headers['content-length'] ?? 0) > CLI_REQUEST_BYTES)
+        return reject(413, 'request-too-large', 'Files are limited to 256 KiB in total.');
+    let principal;
+    try {
+        principal = options.authenticate(request);
+    }
+    catch {
+        return reject(503, 'authentication-unavailable', 'Sign-in could not be checked.');
+    }
+    if (!principal)
+        return reject(401, 'unauthenticated', 'This API token is not valid (expired, revoked or its person removed).');
+    let value;
+    try {
+        value = await body(request);
+    }
+    catch (error) {
+        return reject(error instanceof Error && error.message === 'too-large' ? 413 : 400, 'invalid-body', 'Send a valid JSON request; files are limited to 256 KiB in total.');
+    }
+    const parsed = cliRequest(value);
+    if ('problem' in parsed)
+        return reject(parsed.tooLarge ? 413 : 400, 'invalid-request', parsed.problem);
+    const row = (options.modeOf ?? contractRow)(parsed.argv);
+    if (row?.mode === 'step-up')
+        return reject(403, 'step-up', STEP_UP_MESSAGE);
+    if (row?.mode !== 'yes')
+        return reject(403, 'remote-refused', 'This command cannot run remotely.');
+    const paths = fileArguments(parsed.argv, row);
+    if ('problem' in paths)
+        return reject(403, paths.code, paths.problem);
+    const missing = paths.find(path => !Object.hasOwn(parsed.files, path));
+    if (missing !== undefined)
+        return reject(403, 'missing-file', 'Send every input file\'s contents in files; remote commands cannot read a server file.');
+    if (Object.keys(parsed.files).some(path => !paths.includes(path)))
+        return reject(400, 'invalid-request', 'Each file must name a declared input file argument.');
+    if (!longPollBounded(parsed.argv))
+        return reject(400, 'wait-too-long', `A remote task wait holds the server for at most ${CLI_WAIT_SECONDS} seconds; give --timeout ${CLI_WAIT_SECONDS} or less.`);
+    let run;
+    try {
+        run = await options.run();
+    }
+    catch {
+        run = null;
+    }
+    if (run === null)
+        return reject(501, 'remote-unavailable', 'This server cannot run remote commands yet. Update it, or use --local.');
+    // Files stay in memory: runOperateAs reads them by their argument, so nothing is written to disk here.
+    const out = [];
+    let exitCode;
+    try {
+        exitCode = await run([...parsed.argv], { principal, store: options.store, write: line => { out.push(`${line}\n`); }, files: parsed.files, source: 'api' });
+    }
+    catch {
+        return reject(500, 'command-failed', 'The command stopped unexpectedly on the server. Check its state before running it again.');
+    }
+    send(response, 200, { exitCode, stdout: out.join(''), stderr: '' });
+    return true;
+}

package/dist/cli.d.ts

@@ -13,6 +13,7 @@
 import { previewGithubRepo, cloneGithubRepo } from "./onboard.js";
 import { type SessionCliOptions } from "./session-cli.js";
 import { type TeamCliOptions } from "./team-cli.js";
+import { type RemoteExecOptions } from "./remote-exec.js";
 import { type UpdateCliDeps } from "./toolroll-update-cli.js";
 import { type OperateOptions } from "./operate.js";
 export type CliOptions = {
@@ -54,6 +55,8 @@ export type MainOptions = {
     operate?: OperateOptions;
     session?: SessionCliOptions;
     team?: TeamCliOptions;
+    /** Injected by tests: the remote CLI's profile, fetch and output streams (defaults to `team`'s profile seams). */
+    remote?: RemoteExecOptions;
     /** Injected by tests: the gh-facing halves of `repos add-from-github` —
      * the verb's parsing, gating, and enrollment are what CLI tests prove;
      * gh itself is proved by onboard.test.ts. */

package/dist/cli.js

@@ -27,6 +27,7 @@ import { run as execRun } from "./exec.js";
 import { COMMAND_GUIDE, SURFACE_NOTES, SURFACE_SCHEMA_VERSION } from "./surface.js";
 import { runSessionCommand, SESSION_CLI_ACTIONS } from "./session-cli.js";
 import { maybeRunTeamCommand, TEAM_CLI_ACTIONS } from "./team-cli.js";
+import { maybeRunRemoteCommand } from "./remote-exec.js";
 import { discover, inspectAll } from "./discover.js";
 import { readPulls } from "./pulls.js";
 import { detectGraphs, chooseBackend, setupOptions, LABELS as GRAPH_LABELS, } from "./graph.js";
@@ -253,7 +254,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",
@@ -375,6 +376,12 @@ export async function main(argv, write = line => console.log(line), mainOptions
     return code;
 }
 async function dispatch(argv, write, mainOptions) {
+    // A saved API token sends commands marked remote to the central server, before anything local opens.
+    const central = await maybeRunRemoteCommand(argv, mainOptions.remote ?? mainOptions.team);
+    if (typeof central === "number")
+        return central;
+    if (central !== null)
+        argv = central.local;
     const team = await maybeRunTeamCommand(argv, write, mainOptions.team);
     if (team !== null)
         return team;

package/dist/contracts/cli.d.ts

@@ -25,6 +25,9 @@ export declare const commandFlagSchema: z.ZodReadonly<z.ZodObject<{
     meaning: z.ZodString;
 }, z.core.$loose>>;
 export type CommandFlag = z.infer<typeof commandFlagSchema>;
+/** The remote policy every command row states; see `remote` below. */
+export declare const REMOTE_POLICIES: readonly ["yes", "no", "step-up"];
+export type RemotePolicy = typeof REMOTE_POLICIES[number];
 export declare const commandRowSchema: z.ZodReadonly<z.ZodObject<{
     invocation: z.ZodString;
     envelopeCommand: z.ZodOptional<z.ZodString>;
@@ -82,6 +85,11 @@ export declare const commandRowSchema: z.ZodReadonly<z.ZodObject<{
             const?: number;
         }>;
     }>>;
+    remote: z.ZodEnum<{
+        no: "no";
+        "step-up": "step-up";
+        yes: "yes";
+    }>;
 }, z.core.$loose>>;
 export type CommandRow = z.infer<typeof commandRowSchema>;
 /**
@@ -157,6 +165,11 @@ export declare const COMMAND_OUTPUTS: {
                     const?: number;
                 }>;
             }>>;
+            remote: z.ZodEnum<{
+                no: "no";
+                "step-up": "step-up";
+                yes: "yes";
+            }>;
         }, z.core.$loose>>>;
     }, z.core.$loose>, z.ZodObject<{
         envelopeVersion: z.ZodLiteral<1>;

package/dist/contracts/cli.js

@@ -35,6 +35,8 @@ function answers(command, shape) {
 }
 // ---- the declared command guide, as `contract --commands` dumps it ----
 export const commandFlagSchema = z.looseObject({ name: str, takesValue: z.boolean(), meaning: str }).readonly();
+/** The remote policy every command row states; see `remote` below. */
+export const REMOTE_POLICIES = ["yes", "no", "step-up"];
 /** A session operation's executable input schema, as session-contract.ts states it. */
 const sessionInputSchema = z.custom(value => typeof value === "object" && value !== null && !Array.isArray(value));
 export const commandRowSchema = z.looseObject({
@@ -61,6 +63,11 @@ export const commandRowSchema = z.looseObject({
     notableReasons: z.array(str).readonly().optional(),
     /** Session schemas are executable input contracts, not a grant of authority. */
     inputSchema: sessionInputSchema.optional(),
+    /** Whether a person signed in to a central server with their own API token may run it there (`runOperateAs`):
+     *  yes — runs as that person, within their token's scope and project access.
+     *  no — this machine's own infrastructure, credentials or files; never run for a remote caller.
+     *  step-up — approvals, people and policy: a person's act in the console or chat, never a token's. */
+    remote: z.enum(REMOTE_POLICIES),
 }).readonly();
 // ---- the commands that describe their fields ----
 const taskSchema = z.looseObject({ id: str, title: str, state: z.enum(LISTED_TASK_STATES), createdAt: str, updatedAt: str, priority: z.number() });

package/dist/contracts/console-api.d.ts

@@ -102,6 +102,7 @@ export declare const CONSOLE_FORMS: {
     readonly learningChange: FormContract<"action" | "identity" | "lesson" | "repo" | "revision" | "sha" | "version">;
     readonly projectSetup: FormContract<"command" | "fingerprint" | "model" | "nonce" | "provider" | "repo" | "seconds" | "token">;
     readonly slack: FormContract<"app-token" | "bot-token" | "password">;
+    readonly chatApproval: FormContract<"cap-usd" | "digest" | "full-access" | "nonce" | "scope" | "token">;
     readonly telegramPair: FormContract<"password">;
     readonly teams: FormContract<"app-id" | "password" | "secret" | "tenant">;
     readonly discord: FormContract<"bot-token" | "password">;

package/dist/contracts/console-api.js

@@ -111,6 +111,7 @@ export const CONSOLE_FORMS = {
     learningChange: formContract("POST /settings/learning/change", ["repo", "action", "identity", "revision", "lesson", "version", "sha"]),
     projectSetup: formContract("POST /control/setup-preview, /control/setup-approve, /control/instructions-preview, /control/instructions-approve", ["repo", "nonce", "fingerprint", "token", "provider", "model", "command", "seconds"]),
     slack: formContract("POST /settings/slack/<connect|pair|unpair|disconnect|alerts>", ["password", "app-token", "bot-token"]),
+    chatApproval: formContract("POST /settings/chat-approval/confirm, /settings/chat-approval/save, /settings/chat-approval/off", ["scope", "full-access", "cap-usd", "nonce", "digest", "token"]),
     telegramPair: formContract("POST /settings/telegram/pair, /settings/telegram/unpair", ["password"]),
     teams: formContract("POST /settings/teams/<connect|pair|unpair|disconnect|alerts>", ["password", "app-id", "tenant", "secret"]),
     discord: formContract("POST /settings/discord/<connect|pair|unpair|disconnect|alerts>", ["password", "bot-token"]),

package/dist/contracts/gateway-tools.d.ts

@@ -372,3 +372,85 @@ export declare const GATEWAY_TOOL_OUTPUTS: {
     }, z.core.$loose>;
 };
 export type GatewayToolOutput<N extends GatewayToolName> = z.infer<(typeof GATEWAY_TOOL_OUTPUTS)[N]>;
+export declare const PERSON_TOOL_INPUTS: {
+    readonly status: z.ZodObject<{}, z.core.$strict>;
+    readonly list_tasks: z.ZodObject<{
+        state: z.ZodOptional<z.ZodEnum<{
+            cancelled: "cancelled";
+            done: "done";
+            failed: "failed";
+            queued: "queued";
+            running: "running";
+        }>>;
+        repo: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodInt>;
+        limit: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    readonly task_show: z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strict>;
+    readonly task_review: z.ZodObject<{
+        ref: z.ZodString;
+        run: z.ZodOptional<z.ZodInt>;
+        all: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    readonly review_findings: z.ZodObject<{
+        run: z.ZodInt;
+    }, z.core.$strict>;
+    readonly file_task: z.ZodObject<{
+        repo: z.ZodString;
+        title: z.ZodString;
+        idempotency_key: z.ZodString;
+        deliverable: z.ZodOptional<z.ZodEnum<{
+            branch: "branch";
+            report: "report";
+        }>>;
+    }, z.core.$strict>;
+};
+export type PersonToolName = keyof typeof PERSON_TOOL_INPUTS;
+export type PersonToolInput<N extends PersonToolName> = z.infer<(typeof PERSON_TOOL_INPUTS)[N]>;
+export declare const PERSON_TOOL_OUTPUTS: {
+    readonly status: z.ZodObject<{
+        envelopeVersion: z.ZodLiteral<1>;
+        ok: z.ZodBoolean;
+        command: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    readonly list_tasks: z.ZodObject<{
+        envelopeVersion: z.ZodLiteral<1>;
+        ok: z.ZodBoolean;
+        command: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    readonly task_show: z.ZodObject<{
+        envelopeVersion: z.ZodLiteral<1>;
+        ok: z.ZodBoolean;
+        command: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    readonly task_review: z.ZodObject<{
+        envelopeVersion: z.ZodLiteral<1>;
+        ok: z.ZodBoolean;
+        command: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    readonly review_findings: z.ZodObject<{
+        envelopeVersion: z.ZodLiteral<1>;
+        ok: z.ZodBoolean;
+        command: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    readonly file_task: z.ZodObject<{
+        envelopeVersion: z.ZodLiteral<1>;
+        ok: z.ZodBoolean;
+        command: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+};

package/dist/contracts/gateway-tools.js

@@ -10,6 +10,7 @@
  */
 import { z } from "zod";
 import { TEXT_LIMITS } from "../text-limits.js";
+import { envelopeSchema } from "./cli.js";
 import { catchUpOutput, decisionOutput, decisionsOutput, LISTED_TASK_STATES, queueColumnsOutput, recapOutput, repositoryContextOutput, scopeText, touches } from "./lead-tools.js";
 const text = (key) => z.string().max(TEXT_LIMITS[key]);
 const ref = z.string().min(1).max(TEXT_LIMITS.taskRef);
@@ -92,3 +93,35 @@ export const GATEWAY_TOOL_OUTPUTS = {
     get_contract: z.looseObject({ contract: str }),
     file_proposal: z.looseObject({ ref: str, replayed: z.boolean(), admission: str }),
 };
+// ------------------------------------------------------------- a person's tools
+/**
+ * The tools a PERSON's API token sees over the HTTP gateway (mcp-person.ts). Each call becomes the exact `toolroll`
+ * command line the same person could type, run on the server under their own principal (operate.ts `runOperateAs`):
+ * the command's own authorization, project grants and attribution apply, and its `--json` envelope is the answer.
+ * Two reads keep the coordinator's names and arguments; the rest are new. Every value that lands in a command line
+ * may not begin with "-", so an argument can never be read as a flag.
+ */
+const notFlag = (schema) => schema.regex(/^[^-]/, { error: "must not begin with -" });
+const taskRef = notFlag(ref);
+const runId = z.int().min(1);
+export const PERSON_TOOL_INPUTS = {
+    status: GATEWAY_TOOL_INPUTS.status,
+    list_tasks: GATEWAY_TOOL_INPUTS.list_tasks,
+    task_show: z.strictObject({ ref: taskRef }),
+    task_review: z.strictObject({ ref: taskRef, run: runId.optional(), all: z.boolean().optional() }),
+    review_findings: z.strictObject({ run: runId }),
+    file_task: z.strictObject({
+        repo: notFlag(gatewayRepo), title: notFlag(text("taskTitle").min(1)), idempotency_key: notFlag(text("idempotencyKey").min(8)),
+        deliverable: z.enum(["branch", "report"]).optional(),
+    }),
+};
+/** The command's `--json` envelope (contracts/cli.ts); a refusal is `ok: false` with its stable reason. */
+const envelope = envelopeSchema;
+export const PERSON_TOOL_OUTPUTS = {
+    status: envelope,
+    list_tasks: envelope,
+    task_show: envelope,
+    task_review: envelope,
+    review_findings: envelope,
+    file_task: envelope.extend({ id: str.optional() }),
+};

package/dist/contracts/lead-tools.d.ts

@@ -88,6 +88,10 @@ export declare const LEAD_TOOL_INPUTS: {
         repo: z.ZodOptional<z.ZodString>;
         run: z.ZodOptional<z.ZodInt>;
     }, z.core.$strict>;
+    readonly offer_approval: z.ZodObject<{
+        task: z.ZodOptional<z.ZodString>;
+        card: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
     readonly get_result: z.ZodObject<{
         task: z.ZodString;
         run: z.ZodOptional<z.ZodInt>;
@@ -777,6 +781,10 @@ export declare const LEAD_TOOL_READ_INPUTS: {
         repo: z.ZodOptional<z.ZodString>;
         run: z.ZodOptional<z.ZodInt>;
     }, z.core.$strict>;
+    readonly offer_approval: z.ZodObject<{
+        task: z.ZodOptional<z.ZodString>;
+        card: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
     readonly get_result: z.ZodObject<{
         task: z.ZodString;
         run: z.ZodOptional<z.ZodInt>;
@@ -1535,6 +1543,9 @@ export declare const LEAD_TOOL_OUTPUTS: {
         label: z.ZodString;
         action: z.ZodString;
     }, z.core.$loose>;
+    readonly offer_approval: z.ZodObject<{
+        offered: z.ZodBoolean;
+    }, z.core.$loose>;
     readonly get_result: z.ZodObject<{
         task: z.ZodString;
         root: z.ZodString;

package/dist/contracts/lead-tools.js

@@ -65,6 +65,7 @@ export const LEAD_TOOL_INPUTS = {
     propose_task_action: z.strictObject({ task: taskRef, operation: enumOf(Object.keys(CHAT_TASK_ACTIONS)), dependency: taskRef.optional(), run: id.optional() }),
     get_controls: z.strictObject({}),
     show_control: z.strictObject({ control: enumOf(Object.keys(CHAT_CONTROLS)), task: taskRef.optional(), repo: repoId.optional(), run: id.optional() }),
+    offer_approval: z.strictObject({ task: taskRef.optional(), card: id.optional() }),
     get_result: z.strictObject({ task: taskRef, run: id.optional(), feedback_offset: offset.optional() }),
     get_diff: z.strictObject({ task: taskRef, run: id.optional(), file: text("diffPath").min(1).optional(), offset: offset.optional() }),
     get_check_log: z.strictObject({ task: taskRef, run: id.optional(), search: text("logSearch").min(2).optional(), offset: offset.optional() }),
@@ -189,6 +190,7 @@ export const LEAD_TOOL_OUTPUTS = {
     propose_task_action: z.looseObject({ proposal: int, action: str, awaiting: str }),
     get_controls: z.looseObject({ confirmedInChat: z.array(str), existingControls: rows({ id: str, label: str, needsTask: z.boolean(), needsProject: z.boolean() }), rule: str }),
     show_control: z.looseObject({ card: int, label: str, action: str }),
+    offer_approval: z.looseObject({ offered: z.boolean() }),
     get_result: z.looseObject({
         task: str, root: str, currentExecution: str, run: int, title: str, feedback: list, feedbackTotal: int, nextFeedbackOffset: nullable(int),
         changes: str, changesShortened: z.boolean(), verification: str, accepted: z.boolean(), evidenceTool: str, canRevise: z.boolean(),

package/dist/desktop-update.d.ts

@@ -28,6 +28,8 @@ export declare const updateTerminal: (phase: string) => boolean;
 /** Durable receipts are private and independent of the app being replaced. */
 export declare function durableJson(file: string, value: unknown): void;
 export declare function readUpdateJournal(stateDir: string, retainedReceipt?: string): UpdateJournal | null;
+/** Which settled schema versions a caller works on: the desktop update, which never migrates, only this build's own. */
+export type SchemaAccepted = (version: number | null) => boolean;
 /** A finished run whose end Toolroll cannot show yet: in plain words, with the one command that clears it when a
  * person can. */
 export type LingeringRun = {
@@ -135,7 +137,7 @@ export declare function pauseUpdateRecovery(stateDir: string, id: string, detail
  * reservation so no writer slips in between the snapshot and the copy. The
  * copy drops the update's own admission pause. `inside` runs before the
  * reservation is released, `after` once it is; returns the copy's hash. */
-export declare function verifiedDatabaseBackup(databaseFile: string, backupPath: string, gateId: string, inside?: () => Promise<void>, after?: () => void): Promise<string>;
+export declare function verifiedDatabaseBackup(databaseFile: string, backupPath: string, gateId: string, inside?: () => Promise<void>, after?: () => void, accepts?: SchemaAccepted): Promise<string>;
 /** A SQLite OS lock releases on updater death. Each irreversible step has a
  * preceding durable intent; recovery determines the actual side by hashes. */
 export declare function runDesktopUpdate(stateDir: string, hooks?: UpdateHooks): Promise<void>;

package/dist/desktop-update.js

@@ -116,13 +116,14 @@ export function readUpdateJournal(stateDir, retainedReceipt) {
     }
     return j;
 }
-function connect(file, readOnly = false) {
+const currentSchemaOnly = version => version === SCHEMA_VERSION;
+function connect(file, readOnly = false, accepts = currentSchemaOnly) {
     if (!existsSync(file) || lstatSync(file).isSymbolicLink())
         throw Error("The task database is missing or linked. It was not recreated.");
     const db = new (sqlite().DatabaseSync)(file, { readOnly });
     db.exec("PRAGMA busy_timeout=1000");
     const schema = readSchemaVersion(db);
-    if (!schema.ok || schema.version !== SCHEMA_VERSION) {
+    if (!schema.ok || !accepts(schema.version)) {
         db.close();
         throw Error("This update needs the current database schema. Use the separate verified migration procedure; the installed app is unchanged.");
     }
@@ -515,13 +516,13 @@ async function verifiedBackup(j) {
  * reservation so no writer slips in between the snapshot and the copy. The
  * copy drops the update's own admission pause. `inside` runs before the
  * reservation is released, `after` once it is; returns the copy's hash. */
-export async function verifiedDatabaseBackup(databaseFile, backupPath, gateId, inside = async () => { }, after = () => { }) {
-    const db = connect(databaseFile);
+export async function verifiedDatabaseBackup(databaseFile, backupPath, gateId, inside = async () => { }, after = () => { }, accepts = currentSchemaOnly) {
+    const db = connect(databaseFile, false, accepts);
     try {
         db.exec("BEGIN IMMEDIATE");
         // The write reservation prevents a concurrent writer; a separate read
         // connection is required because SQLite cannot back up a write transaction.
-        const source = connect(databaseFile, true);
+        const source = connect(databaseFile, true, accepts);
         let before;
         try {
             before = snapshot(source);
@@ -531,7 +532,7 @@ export async function verifiedDatabaseBackup(databaseFile, backupPath, gateId, i
             source.close();
         }
         chmodSync(backupPath, 0o600);
-        const copied = connect(backupPath);
+        const copied = connect(backupPath, false, accepts);
         try {
             if (copied.prepare("PRAGMA integrity_check").get()?.integrity_check !== "ok" || copied.prepare("PRAGMA foreign_key_check").all().length !== 0 || snapshot(copied) !== before)
                 throw Error("Backup verification failed. The installed app is unchanged.");

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/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';