toolroll 0.9.43 → 0.9.44

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.9.44 — 2026-10-07
+
+- **Work from your own laptop.** `toolroll connect https://… --token so_…`
+  and allowed commands run on the server as you, with the same output and
+  exit codes. Approvals, people, policy and anything touching the server's
+  files stay in the console and chat.
+- **Agents connect over HTTPS.** `claude mcp add --transport http toolroll
+  https://<host>/mcp --header "Authorization: Bearer so_…"`. Tools cover only
+  that person's projects.
+- **Every remote action is on the record**: who, whether it came from the CLI
+  or an agent, and the token's name. A revoked token stops on its next call.
+  Other projects' tasks and runs answer "not found".
+- **For now, people limited to some projects** can't run the commands that
+  list across projects (`status`, `task list`) or choose a task's `--id`;
+  they're refused rather than shown a partial list. Filtered views are next.
+- Still to come: token management in the CLI, rate limits, an audit view, a
+  real domain with TLS, and sign-in for agents.
+
 ## 0.9.43 — 2026-10-06
 
 - **Approve from chat and the CLI.** A plan waiting on you and a flow's

package/dist/action-ledger.d.ts

@@ -1,6 +1,7 @@
 import type { Database } from "./store.js";
-/** v99: sign-ins (and refusals, lockouts, sign-outs) and policy changes are their own kinds of event. */
-export declare const LEDGER_SOURCES: readonly ["work", "request", "access", "sign-in", "policy"];
+/** v99: sign-ins (and refusals, lockouts, sign-outs) and policy changes are their own kinds of event.
+ * v110: commands a person ran on this server with their API token, from the CLI ('api') or their agent ('mcp'). */
+export declare const LEDGER_SOURCES: readonly ["work", "request", "access", "sign-in", "policy", "api", "mcp"];
 export type LedgerSource = typeof LEDGER_SOURCES[number];
 export type LedgerEntry = {
     id: number;
@@ -18,6 +19,8 @@ export type LedgerEntry = {
 /** The table as v54 made it: the one earlier shape the v99 rebuild accepts. */
 export declare const LEDGER_V54_TABLE: (name: string) => string;
 export declare const LEDGER_V54_COLUMNS: readonly ["id", "at", "actor", "repo", "task_id", "run_id", "action", "outcome", "source"];
+/** The table as v99 made it: the v110 rebuild accepts this shape and v54's. */
+export declare const LEDGER_V99_TABLE: (name: string) => string;
 export declare const LEDGER_TABLE: (name: string) => string;
 export declare const LEDGER_SCHEMA: string;
 /** Installed after all table migrations. Work events commit with the work,

package/dist/action-ledger.js

@@ -1,5 +1,6 @@
-/** v99: sign-ins (and refusals, lockouts, sign-outs) and policy changes are their own kinds of event. */
-export const LEDGER_SOURCES = ["work", "request", "access", "sign-in", "policy"];
+/** v99: sign-ins (and refusals, lockouts, sign-outs) and policy changes are their own kinds of event.
+ * v110: commands a person ran on this server with their API token, from the CLI ('api') or their agent ('mcp'). */
+export const LEDGER_SOURCES = ["work", "request", "access", "sign-in", "policy", "api", "mcp"];
 /** The table as v54 made it: the one earlier shape the v99 rebuild accepts. */
 export const LEDGER_V54_TABLE = (name) => `CREATE TABLE ${name} (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -9,7 +10,8 @@ export const LEDGER_V54_TABLE = (name) => `CREATE TABLE ${name} (
   source TEXT NOT NULL CHECK (source IN ('work','request','access'))
 )`;
 export const LEDGER_V54_COLUMNS = ["id", "at", "actor", "repo", "task_id", "run_id", "action", "outcome", "source"];
-export const LEDGER_TABLE = (name) => `CREATE TABLE ${name} (
+/** The table as v99 made it: the v110 rebuild accepts this shape and v54's. */
+export const LEDGER_V99_TABLE = (name) => `CREATE TABLE ${name} (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   at TEXT NOT NULL, actor TEXT NOT NULL, repo TEXT,
   task_id TEXT, run_id INTEGER,
@@ -17,6 +19,14 @@ export const LEDGER_TABLE = (name) => `CREATE TABLE ${name} (
   source TEXT NOT NULL CHECK (source IN ('work','request','access','sign-in','policy')),
   detail TEXT
 )`;
+export const LEDGER_TABLE = (name) => `CREATE TABLE ${name} (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  at TEXT NOT NULL, actor TEXT NOT NULL, repo TEXT,
+  task_id TEXT, run_id INTEGER,
+  action TEXT NOT NULL, outcome TEXT NOT NULL,
+  source TEXT NOT NULL CHECK (source IN ('work','request','access','sign-in','policy','api','mcp')),
+  detail TEXT
+)`;
 export const LEDGER_SCHEMA = `
 ${LEDGER_TABLE("IF NOT EXISTS action_ledger")};
 CREATE INDEX IF NOT EXISTS action_ledger_project ON action_ledger(repo, id DESC);

package/dist/cli-http.d.ts

@@ -0,0 +1,64 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Store } from './store.js';
+import { type RemoteCommandLookup } from './remote-command.js';
+/**
+ * `POST /api/cli` (remote CLI, Phase 1): a teammate's laptop sends the argv it would have run locally, and the central
+ * server runs that same command as that person. There is no per-resource API here and no second policy: the transport
+ * authenticates one API token, checks the shared command contract and transport arguments, and hands the argv to
+ * `runOperateAs`, which owns scope, project grants and attribution.
+ *
+ * Only `Authorization: Bearer so_…` is accepted — never a password, cookie or the owner's saved login — and a request
+ * carrying a browser Origin is refused, so a page can never drive it.
+ */
+/** Who a remote command runs as. The shared seam with operate.ts (remote-principal). */
+export type Principal = {
+    kind: 'person';
+    account: string;
+    generation: number;
+    scope: 'read' | 'act';
+    tokenId: string;
+    projects: string[] | null;
+};
+export type RunOperateAs = (argv: string[], opts: {
+    principal: Principal;
+    store: Store;
+    write: (s: string) => void;
+    files?: Record<string, string>;
+    source?: 'api' | 'mcp';
+}) => Promise<number>;
+export type CliRequest = {
+    argv: string[];
+    files: Record<string, string>;
+};
+export type CliReply = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export type CliFailure = {
+    ok: false;
+    code: string;
+    message: string;
+};
+/** Inlined file contents, summed as UTF-8 bytes. */
+export declare const CLI_FILES_BYTES: number;
+/** The whole JSON body: the files plus argv and JSON escaping headroom. */
+export declare const CLI_REQUEST_BYTES: number;
+export type CliHttpOptions = {
+    /** The live API token's person, or null. Only called for a single, well-formed `Bearer so_…` header. */
+    authenticate: (request: IncomingMessage) => Principal | null;
+    /** The shared command boundary; null when this server cannot run remote commands. */
+    run: () => Promise<RunOperateAs | null>;
+    /** Tests: command policy while the parallel command contract is not yet available. Defaults to COMMAND_GUIDE. */
+    modeOf?: RemoteCommandLookup | undefined;
+    store: Store;
+};
+/** Decode the request's shape and byte limits. The endpoint checks file references against its command policy. */
+export declare function cliRequest(value: unknown): CliRequest | {
+    problem: string;
+    tooLarge?: true;
+};
+/** The longest one request may hold the server: the client polls again for longer waits. */
+export declare const CLI_WAIT_SECONDS = 25;
+/** Handles exactly `/api/cli`; false for any other path. */
+export declare function handleCliHttp(request: IncomingMessage, response: ServerResponse, options: CliHttpOptions): Promise<boolean>;

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";
@@ -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/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/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.");