toolroll 0.9.42 → 0.9.44

package/dist/mcp.js

@@ -1,12 +1,9 @@
-import { dirname, join } from 'node:path';
 import { statSync } from 'node:fs';
-import { repositoryContextRead } from './repository-context.js';
-import { ASSIGNMENT_TOOLS, assignmentForCoordinator } from "./assignment-adapters.js";
-import { parseContract, toModelSchema } from "./contracts/contract.js";
-import { GATEWAY_TOOL_INPUTS, GATEWAY_TOOL_OUTPUTS } from "./contracts/gateway-tools.js";
-import { reportToolOutput } from "./contracts/lead-tools.js";
 /**
- * `toolroll mcp` — the MCP stdio server (MCP gateway spec v6).
+ * `toolroll mcp` — the MCP stdio adapter (MCP gateway spec v6). What a
+ * call means lives in the transport-free core (mcp-core.ts); this file owns
+ * the stdio transport, era pinning and the connection's lifecycle.
+ *
  *
  * Zero-dep JSON-RPC 2.0 over stdio, newline-delimited; stdout carries
  * protocol bytes ONLY (logs go to stderr); clean EOF is clean shutdown.
@@ -31,207 +28,9 @@ import { reportToolOutput } from "./contracts/lead-tools.js";
  * refusals are successful `tools/call` results with `isError: true`.
  */
 import { PACKAGE_VERSION } from "./version.js";
-import { authenticateCoordinator, fileCoordinatorProposal, statusFor, listTasksFor, taskDetailFor, } from "./coordinator.js";
-import { ISO_STAMP_RULE, decisionOver, decisionsOver, labelRepos, queueOver, recapOver } from "./mate-tools.js";
-import { proposeAsCoordinator } from "./coordinator-proposals.js";
-export const MODERN = "2026-07-28";
-export const LEGACY = "2025-11-25";
-/** The modern revision namespaces its per-request metadata. */
-export const META_VERSION = "io.modelcontextprotocol/protocolVersion";
-export const META_SERVER = "io.modelcontextprotocol/serverInfo";
-export const META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
-/** The revision's own error code for an unsupported protocol version. */
-export const UNSUPPORTED_VERSION = -32022;
-const MAX_REQUEST = 256 * 1024;
-const MAX_DEPTH = 32;
-function depthOf(value) {
-    // The byte cap bounds the work list. Neither nesting nor array width
-    // becomes a JavaScript call stack or a spread argument list.
-    const pending = [{ value, depth: 0 }];
-    let maximum = 0;
-    while (pending.length > 0) {
-        const current = pending.pop();
-        if (current.depth > MAX_DEPTH)
-            return current.depth;
-        maximum = Math.max(maximum, current.depth);
-        if (current.value !== null && typeof current.value === "object") {
-            const children = Array.isArray(current.value) ? current.value : Object.values(current.value);
-            for (const child of children)
-                pending.push({ value: child, depth: current.depth + 1 });
-        }
-    }
-    return maximum;
-}
-const CONTRACT_GUIDE = [
-    "Toolroll MCP contract.",
-    "You hold a coordinator credential: you may read inside your repo allowlist, file proposals, and record assignment ownership and receipt checks. Ownership and receipt checks grant no execution or approval authority.",
-    "A filed proposal is an ordinary unapproved task: it is quarantined from planning, claiming, and running until the operator signs its scope in a password ceremony that shows them who asked. Modes never auto-admit coordinator filings.",
-    "file_proposal requires an idempotency_key (8-64 printable chars, unique per request): replaying the same key+request returns the original task; the same key with a different request refuses. deliverable 'report' files a scout task: a read-only investigation whose only output is a report on the task page, never a branch.",
-    "You are rate-limited per hour and capped on outstanding unapproved filings. Refusals say the limit and the road in words.",
-    "recap, list_decisions, get_decision, and queue are the plane's own read queries (shared with the operator's mate). get_decision shows each option's consequence, never the builder's recommendation.",
-    "propose_next, propose_reserve, propose_hold, propose_unhold, propose_scope, propose_cancel, and propose_answer write a PROPOSAL row and nothing else: an approver confirms it on the console or the CLI, and a stale one refuses there. Proposals share your hourly filing rate and hold at most 20 pending per credential; they expire after seven days.",
-    "Approve, steer, answer, pick, mint, configure, merge: those verbs do not exist on this surface, by construction.",
-    "Claim one assignment, then follow list_assignment_updates with a saved cursor; inspect get_assignment when a current result or decision needs attention. claim_assignment records its lead; acknowledge_assignment records that lead's check of an exact ready receipt. Neither operation grants authority, accepts proof, answers decisions, approves work, publishes, or deploys.",
-].join("\n");
-/** An assignment tool: the adapter reads its call with the same schema `toolroll assignment` does. */
-const assignmentHandler = (operation) => (ctx, args) => {
-    const result = assignmentForCoordinator(ctx.store, ctx.token, operation, args, ctx.now, ctx.evidenceRoot);
-    return result.ok ? { ok: true, body: result.body } : { ok: false, message: `${result.reason}: ${result.message}` };
-};
-const assignmentTool = (name) => {
-    const spec = ASSIGNMENT_TOOLS.find(one => one.name === name);
-    return { description: spec.description, handle: assignmentHandler(spec.operation) };
-};
-/** A propose_* tool: it writes one proposal row through the coordinator door. */
-const proposeTool = (kind, description) => ({
-    description,
-    handle: (ctx, args) => {
-        const outcome = proposeAsCoordinator(ctx.store, ctx.token, kind, args, ctx.now, { readDecisions: ctx.readDecisions });
-        if (!outcome.ok)
-            return { ok: false, message: outcome.message };
-        return { ok: true, body: { proposal: outcome.id, kind: outcome.kind, awaiting: outcome.awaiting } };
-    },
-});
-const HANDLERS = {
-    get_project_context: {
-        description: 'Read bounded source excerpts or advisory static import impact in an admitted project. Falls back to text search without an index.',
-        handle: (ctx, args) => {
-            const repo = args.repo;
-            if (!ctx.who.repos.includes(repo) || ctx.enrolled !== null && !ctx.enrolled.includes(repo))
-                return { ok: false, message: 'That project is outside your access.' };
-            return { ok: true, body: repositoryContextRead({ repo, query: args.query, mode: args.mode === 'impact' ? 'impact' : 'search', audience: 'lead',
-                    ...(ctx.evidenceRoot === undefined ? {} : { cacheRoot: join(dirname(ctx.evidenceRoot), 'repository-context') }) }) };
-        },
-    },
-    get_assignment: assignmentTool("get_assignment"),
-    list_assignment_updates: assignmentTool("list_assignment_updates"),
-    claim_assignment: assignmentTool("claim_assignment"),
-    acknowledge_assignment: assignmentTool("acknowledge_assignment"),
-    get_assignment_brief: assignmentTool("get_assignment_brief"),
-    get_assignment_inbox: assignmentTool("get_assignment_inbox"),
-    acknowledge_assignment_delivery: assignmentTool("acknowledge_assignment_delivery"),
-    status: {
-        description: "The plane's liveness facts over your repo allowlist: what waits on the operator, what runs, what finished in the last 24h.",
-        handle: ctx => ({ ok: true, body: statusFor(ctx.store, ctx.who, ctx.now) }),
-    },
-    list_tasks: {
-        description: "Tasks in your repo allowlist. Filter by state and repo; cursor-paginated, stable order.",
-        handle: (ctx, args) => {
-            const filter = {};
-            if (args.state !== undefined)
-                filter.state = args.state;
-            if (args.repo !== undefined)
-                filter.repo = args.repo;
-            if (args.cursor !== undefined)
-                filter.cursor = args.cursor;
-            if (args.limit !== undefined)
-                filter.limit = args.limit;
-            return { ok: true, body: listTasksFor(ctx.store, ctx.who, filter, ctx.now) };
-        },
-    },
-    get_task: {
-        description: "One task's deliverable (branch or report), scope standing, filer provenance, attempt ledger, and — for a finished scout — the report's title, summary, and follow-ups. A ref outside your allowlist answers not-found.",
-        handle: (ctx, args) => {
-            const detail = taskDetailFor(ctx.store, ctx.who, args.ref, ctx.evidenceRoot, ctx.now);
-            if (detail === null)
-                return { ok: false, message: `not-found: no task \`${args.ref}\` in your repositories` };
-            return { ok: true, body: detail };
-        },
-    },
-    list_repos: {
-        description: "The repositories your credential may see and file into, with their operating-mode standing.",
-        handle: ctx => {
-            // FAIL CLOSED when the project registry cannot be read (round-2
-            // finding 4): answering the full allowlist would claim enrollment
-            // nobody proved.
-            if (ctx.enrolled === null) {
-                return { ok: false, message: "the project registry could not be read — the enrolled set is unknown, so nothing lists" };
-            }
-            return {
-                ok: true,
-                body: {
-                    repos: ctx.who.repos
-                        .filter(repo => ctx.enrolled !== null && ctx.enrolled.includes(repo))
-                        .map(repo => {
-                        const mode = ctx.store.activeMode(repo, ctx.now);
-                        return { repo, mode: mode === null ? "no operating mode — every act is a ceremony" : `mode ${mode.name} signed until ${mode.absoluteExpiry}` };
-                    }),
-                },
-            };
-        },
-    },
-    recap: {
-        description: "How things stand per repository in your allowlist, counts and ids: what waits on the operator (decisions, incidents, scopes awaiting approval), what runs, what is queued, finished, failed. Pass `since` (an ISO timestamp) to count only decisions, incidents, and attempts newer than it, to the hour; queued work and scopes awaiting approval always count.",
-        handle: (ctx, args) => {
-            const since = args.since;
-            if (since !== undefined && (!ISO_STAMP_RULE.test(since) || Number.isNaN(Date.parse(since)))) {
-                return { ok: false, message: "since is an ISO timestamp like 2026-09-02T12:00:00Z" };
-            }
-            return { ok: true, body: labelRepos(recapOver(ctx.store, ctx.who.repos, ctx.now, since ?? null), index => ctx.who.repos[index] ?? "") };
-        },
-    },
-    list_decisions: {
-        description: "Open decisions in your allowlist: id, task, question, options (id, label, reversible), age in hours. Never consequences or recommendations; the operator answers them.",
-        handle: ctx => ({ ok: true, body: labelRepos(decisionsOver(ctx.store, ctx.who.repos, ctx.now), index => ctx.who.repos[index] ?? "") }),
-    },
-    queue: {
-        description: "One repository's queue by column — the shared column, then each worker's reserved column — each in dispatch order.",
-        handle: (ctx, args) => {
-            const repo = args.repo;
-            if (!ctx.who.repos.includes(repo))
-                return { ok: false, message: "not-found: that repository is not in your allowlist" };
-            // The installation-wide revision stays home (slice-2 review, finding
-            // 12): a coordinator cannot move queues, and the counter would tell it
-            // about repos it may not see.
-            const { queueRevision: _revision, ...columns } = queueOver(ctx.store, repo, ctx.now);
-            return { ok: true, body: { repo, ...columns } };
-        },
-    },
-    get_decision: {
-        description: "One open decision in your allowlist in full: question, options with id, label, reversible, and consequence. Never the builder's recommendation.",
-        handle: (ctx, args) => {
-            const found = decisionOver(ctx.store, ctx.who.repos, args.decision, ctx.now);
-            if (found === null)
-                return { ok: false, message: "not-found: no such decision in your repositories" };
-            ctx.readDecisions.add(args.decision);
-            return { ok: true, body: labelRepos(found, index => ctx.who.repos[index] ?? "") };
-        },
-    },
-    propose_next: proposeTool("next", "Propose moving a queued task to the front of its column. An approver confirms; a queue that moved meanwhile refuses."),
-    propose_reserve: proposeTool("reserve", "Propose reserving a queued task for one worker, or releasing it to the shared queue with worker null."),
-    propose_hold: proposeTool("hold", "Propose holding a task's next attempt, with a reason. A running attempt is never interrupted."),
-    propose_unhold: proposeTool("unhold", "Propose lifting the operator's own hold on a task."),
-    propose_scope: proposeTool("scope", "Propose rewriting a task's scope. An approver confirms the rewrite, then approves it with a password — a scope you wrote never seals under a mode."),
-    propose_cancel: proposeTool("cancel", "Propose cancelling a task, with a reason. The approver arms and confirms it on the task itself."),
-    propose_answer: proposeTool("answer", "Propose an answer to an open decision you read with get_decision, with a rationale. The approver confirms where every consequence and the builder's recommendation are shown; an irreversible option needs their explicit confirmation."),
-    get_contract: {
-        description: "This surface's contract: what a coordinator may do, the proposal lifecycle, and the admission promise.",
-        handle: () => ({ ok: true, body: { contract: CONTRACT_GUIDE } }),
-    },
-    file_proposal: {
-        description: "File a task proposal into one of your repositories. It stays quarantined until the operator signs its scope.",
-        handle: (ctx, args) => {
-            // The token, not the pre-verified identity: filing re-authenticates
-            // INSIDE its own transaction (the session's `who` is a courtesy).
-            const outcome = fileCoordinatorProposal(ctx.store, ctx.token, { repo: args.repo, title: args.title, ...(args.intent === undefined ? {} : { intent: args.intent }), ...(args.deliverable === undefined ? {} : { deliverable: args.deliverable }), idempotencyKey: args.idempotency_key }, ctx.now);
-            if (!outcome.ok)
-                return { ok: false, message: outcome.message };
-            return {
-                ok: true,
-                body: {
-                    ref: outcome.id,
-                    replayed: outcome.replayed,
-                    admission: "quarantined until the operator signs its scope — the ceremony shows them your name",
-                },
-            };
-        },
-    },
-};
-/** The gateway's tools in tools/list order, each inputSchema derived from its contract. */
-const TOOLS = Object.keys(GATEWAY_TOOL_INPUTS).map((name) => {
-    const handler = HANDLERS[name];
-    return { name, description: handler.description, inputSchema: toModelSchema(GATEWAY_TOOL_INPUTS[name]), handle: (ctx, args) => handler.handle(ctx, args) };
-});
+import { authenticateCoordinator } from "./coordinator.js";
+import { LEGACY, META_CAPABILITIES, META_SERVER, META_VERSION, MODERN, TOOLS, UNSUPPORTED_VERSION, callCoordinatorTool, capabilitiesShape, readMessage, shapeResult, toolsPayload, } from "./mcp-core.js";
+export { LEGACY, META_CAPABILITIES, META_SERVER, META_VERSION, MODERN, UNSUPPORTED_VERSION } from "./mcp-core.js";
 function fileIdentity(path) {
     if (path === null)
         return null;
@@ -286,16 +85,8 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
     const respond = (id, era, result, cacheable) => {
         if (id !== null && cancelled.has(JSON.stringify(id)))
             return; // suppressed entirely
-        const complete = era === "modern"
-            ? { ...result, resultType: "complete", ...(cacheable ? { ttlMs: 0, cacheScope: "private" } : {}) }
-            : result;
-        io.write(JSON.stringify({ jsonrpc: "2.0", id, result: complete }));
+        io.write(JSON.stringify({ jsonrpc: "2.0", id, result: shapeResult(era, result, cacheable) }));
     };
-    const toolsPayload = () => ({
-        // No outputSchema: MCP output schemas describe structuredContent, and
-        // these tools return text content only (round-2 finding 1).
-        tools: TOOLS.map(tool => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema })),
-    });
     const callTool = (id, era, params) => {
         // A restore or rollback puts a different file at the database's path: this server's connection still reads and
         // writes the one it replaced, so it answers nothing more and exits (the agent starts it again on the new one).
@@ -304,112 +95,23 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
             io.exit(0);
             return;
         }
-        // ONE snapshot per call (review finding 3): the version check, the
-        // credential re-read, and every data read share a transaction, so a
-        // concurrent migration cannot slip between them; filing's own
-        // BEGIN IMMEDIATE reenters this one. A moved schema refuses in words
-        // and the server exits clean.
-        store.transact(() => {
-            if (!store.schemaCurrent()) {
-                error(id, -32000, "the database schema moved underneath this server — restart it");
-                io.exit(0);
-                return;
-            }
-            const name = typeof params["name"] === "string" ? params["name"] : "";
-            const tool = TOOLS.find(one => one.name === name);
-            if (tool === undefined) {
-                error(id, -32602, `no tool \`${name}\``);
-                return;
-            }
-            // tools/list visibility is presentation — authorization happens HERE,
-            // on every call, against the live credential row.
-            const session = authenticateCoordinator(store, token);
-            if (!session.ok) {
-                error(id, -32000, "this credential no longer stands — the server exits");
-                io.exit(0);
-                return;
-            }
-            // Only an ABSENT `arguments` defaults to empty (round-3 finding 2): an
-            // explicit null is not the optional-object shape MCP defines.
-            const rawArgs = params["arguments"] === undefined ? {} : params["arguments"];
-            if (typeof rawArgs !== "object" || rawArgs === null || Array.isArray(rawArgs)) {
-                // The root of `arguments` is an object BEFORE any schema applies
-                // (round-2 finding 2): 42 or false never passes an empty schema.
-                error(id, -32602, "arguments must be an object");
-                return;
-            }
-            // The call is read by the schema tools/list advertised (review finding
-            // 2): unknown fields, bad types, bad enums, and bound violations are
-            // protocol errors (InvalidParams) naming each path, never tool refusals.
-            const read = parseContract(GATEWAY_TOOL_INPUTS[tool.name], rawArgs);
-            if (!read.ok) {
-                error(id, -32602, read.issues.map(one => one.line).join("; "));
-                return;
-            }
-            const answered = tool.handle({ store, who: session.who, token, enrolled, now: clock(), readDecisions, ...(evidenceRoot === undefined ? {} : { evidenceRoot }) }, read.value);
-            if (!answered.ok) {
-                respond(id, era, { content: [{ type: "text", text: answered.message }], isError: true }, false);
-                return;
-            }
-            // Checked against its output schema before delivery; a disagreement is reported, never refused.
-            reportToolOutput("gateway", tool.name, GATEWAY_TOOL_OUTPUTS[tool.name], answered.body);
-            respond(id, era, { content: [{ type: "text", text: JSON.stringify(answered.body) }] }, false);
-        });
+        // A moved schema or a credential that no longer stands refuses in words and the server exits clean.
+        const outcome = callCoordinatorTool({ store, token, enrolled, clock, readDecisions, ...(evidenceRoot === undefined ? {} : { evidenceRoot }) }, params);
+        if (outcome.kind === "result")
+            return respond(id, era, outcome.result, false);
+        error(id, outcome.code, outcome.message);
+        if (outcome.fatal)
+            io.exit(0);
     };
     io.onLine(line => {
         if (line.trim() === "")
             return;
-        if (Buffer.byteLength(line, "utf8") > MAX_REQUEST) {
-            error(null, -32600, "request over 256 KiB");
-            return;
-        }
-        let message;
-        try {
-            message = JSON.parse(line);
-        }
-        catch {
-            error(null, -32700, "parse error");
-            return;
-        }
-        if (Array.isArray(message)) {
-            // Batching left MCP in 2025-06-18 — neither pinned era accepts it.
-            error(null, -32600, "JSON-RPC batching is not part of MCP — send one request per line");
-            return;
-        }
-        if (message === null || typeof message !== "object" || depthOf(message) > MAX_DEPTH) {
-            error(null, -32600, "invalid request");
-            return;
-        }
-        const request = message;
-        if (request["jsonrpc"] !== "2.0") {
-            error(null, -32600, 'jsonrpc must be "2.0"');
-            return;
-        }
-        // A notification is the message that carries NO id — the method name
-        // never decides (round-3 finding 3): notifications/initialized WITH an
-        // id is a malformed message, not a quiet notification. MCP RequestId is
-        // a string or an INTEGER (round-2 finding 2): floats, null, and object
-        // shapes refuse wherever an id appears.
-        const hasId = "id" in request;
-        const rawId = request["id"];
-        if (hasId && (rawId === null || (typeof rawId !== "string" && !(typeof rawId === "number" && Number.isInteger(rawId))))) {
-            error(null, -32600, "id must be a string or an integer");
-            return;
-        }
-        const method = typeof request["method"] === "string" ? request["method"] : "";
-        if (method.startsWith("notifications/")) {
-            if (hasId) {
-                error(rawId, -32600, "a notification carries no id");
-                return;
-            }
-        }
-        else if (!hasId) {
-            error(null, -32600, "a request carries an id — a string or an integer");
+        const read = readMessage(line);
+        if (!read.ok) {
+            error(read.id, read.code, read.message);
             return;
         }
-        const id = (rawId ?? null);
-        const params = (request["params"] ?? {});
-        const meta = (params["_meta"] ?? {});
+        const { id, method, params, meta } = read;
         // Every method — lifecycle included — refuses on a moved schema
         // (review finding 3): a server that answers discover from one world
         // and tools from another is lying to somebody.
@@ -453,9 +155,6 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
             }));
             return;
         }
-        // ClientCapabilities is an OBJECT shape (round-3 finding 5): an array
-        // is not a capabilities declaration.
-        const capabilitiesShape = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
         if (method === "initialize") {
             if (pinnedEra === "modern") {
                 error(id, -32600, "this connection speaks the modern era — initialize belongs to the handshake era");
@@ -489,7 +188,7 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
                 supportedVersions: [MODERN, LEGACY],
                 capabilities: { tools: {} },
                 _meta: { [META_SERVER]: { name: "toolroll", version: PACKAGE_VERSION } },
-                ...toolsPayload(),
+                ...toolsPayload(TOOLS),
             }, true);
             return;
         }
@@ -523,7 +222,7 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
             return;
         }
         if (method === "tools/list") {
-            respond(id, era, toolsPayload(), true);
+            respond(id, era, toolsPayload(TOOLS), true);
             return;
         }
         if (method === "tools/call") {

package/dist/operate-remote-arguments.d.ts

@@ -0,0 +1,36 @@
+/** The audited remote argument vocabulary. Unlisted flags and extra positionals never dispatch.
+ * Keep scalar inputs explicit: adding a resource argument requires classifying it here first.
+ * Indices below are relative to the command row (after `task review`, `flows trigger add`, etc.). */
+import type { Store } from './store.js';
+type Kind = 'value' | 'task' | 'run' | 'review' | 'flow' | 'trigger' | 'trigger-json' | 'steps' | 'refused' | 'step-up';
+type Argument = {
+    name: string;
+    kind: Kind;
+    optional: boolean;
+    rest: boolean;
+};
+export type RemoteArguments = {
+    positionals: readonly Argument[];
+    flags: ReadonlyMap<string, Kind>;
+};
+/** All remotely allowed rows, including those with no resource references. Credentials and file-output
+ * flags are refused by the outer boundary. `source` on memory is provenance text; on revise it is a scope
+ * digest. Neither dereferences a conversation, task or proposal. Creation IDs are never looked up. */
+export declare const REMOTE_ARGUMENTS: ReadonlyMap<string, RemoteArguments>;
+export declare const REMOTE_NOT_FOUND: {
+    readonly ok: false;
+    readonly reason: 'not-found';
+    readonly message: 'Not found.';
+};
+type Result = {
+    ok: true;
+    repo: string | null;
+    taskId: string | null;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+/** Read-only authorization of every supplied reference, before the handler can disclose or mutate it. */
+export declare function remoteArgumentsOf(store: Store, allows: (repo: string | null) => boolean, invocation: string, positional: readonly string[], flags: ReadonlyMap<string, string | true>, named: string | null, files: Readonly<Record<string, string>>): Result;
+export {};

package/dist/operate-remote-arguments.js

@@ -0,0 +1,185 @@
+const args = (positionals = '', values = '', references = {}) => ({
+    positionals: positionals.split(' ').filter(Boolean).map(word => {
+        const [name = '', type = 'value'] = word.split(':');
+        return { name: name.replace(/[?*]$/, ''), kind: type, optional: name.endsWith('?'), rest: name.endsWith('*') };
+    }),
+    flags: new Map([...['json', 'help', 'repo', ...values.split(' ').filter(Boolean)].map(name => [name, 'value']), ...Object.entries(references)]),
+});
+/** All remotely allowed rows, including those with no resource references. Credentials and file-output
+ * flags are refused by the outer boundary. `source` on memory is provenance text; on revise it is a scope
+ * digest. Neither dereferences a conversation, task or proposal. Creation IDs are never looked up. */
+export const REMOTE_ARGUMENTS = new Map([
+    ...['status', 'ready', 'grants', 'gaps', 'sync', 'runner list', 'coordinator list', 'incident list',
+        'routine list', 'intake show', 'intake run', 'template list', 'webhook status', 'webhook test', 'review show',
+        'chat-approval show', 'chat-approval off'].map(row => [row, args()]),
+    ['integrations', args('', 'saved')],
+    ['outbox list', args('', 'all')],
+    ['task add', args('title*', 'key report checks', { id: 'refused', replaces: 'task' })],
+    ['task ask', args('id:task', 'person why')],
+    ['task checks', args('task:task', 'level')],
+    ['task add-tests', args('task:task')],
+    ['task list', args('', 'state view limit cursor')],
+    ['task show', args('id:task')],
+    ['task wait', args('id:task', 'timeout')],
+    ['task complete', args('task:task', 'digest', { run: 'run', 'pull-request': 'refused' })],
+    ['task revise', args('task:task', 'feedback source key', { run: 'run' })],
+    ['task state', args('id:task state', 'key reason', { 'replaced-by': 'task' })],
+    ['task block', args('id:task', 'key', { on: 'task' })],
+    ['task unblock', args('id:task', 'key', { on: 'task' })],
+    ['task next', args('id:task', 'key undo')],
+    ['task steer', args('id:task', 'note')],
+    ['task assign', args('id:task', 'key runner anyone')],
+    ['task scope', args('id:task', 'key goal not touches budget-usd risk acceptance candidate compare model provider race race-count race-per-usd race-total-usd repair-model')],
+    ['task plan', args('id:task', 'key provider model')],
+    ['task hold', args('id:task', 'key reason until')],
+    ['task unhold', args('id:task', 'key')],
+    ['task require', args('id:task', 'key cap require')],
+    ['task requeue', args('id:task')],
+    ['task review', args('id:review', 'brief all', { run: 'run' })],
+    ['task repair', args('run:run', '', { yes: 'step-up' })],
+    ['task route', args('id:task', 'risk phase provider model clear-phase digest size risky')],
+    ['task reopen', args('id:task')],
+    ['task stop', args('id:task', '', { run: 'run' })],
+    ['task resume', args('id:task', '', { run: 'run' })],
+    ['check-progress', args('run:run')],
+    ['cap list', args()], ['cap add', args('name', 'kind probe expires')],
+    // These objects are installation-scoped at the outer boundary; only an all-project principal reaches them.
+    ['incident resolve', args('incident')],
+    ['routine show', args('id')],
+    ['routine add', args('name', 'goal schedule acceptance ceiling budget-usd not touches require')],
+    ...['refresh', 'pause', 'resume', 'run-now'].map(action => [`routine ${action}`, args('name')]),
+    ['config show', args('phase?')], ['verify show', args()],
+    ['intake preview', args()], ['intake pr-comments', args('', 'limit')],
+    ['template show', args('name')],
+    ['contest show', args('id')], ['contest exclude', args('contest ordinal')],
+    ...['search', 'impact'].map(action => [`knowledge ${action}`, args('query', 'base')]),
+    ['knowledge refresh', args('', 'base')],
+    // Decision reads and supersession are already project-bound in project-memory.ts. Proposal IDs are
+    // accepted only by memory apply (step-up), never by the listing commands below.
+    ...['search', 'decisions', 'show', 'decide', 'retire', 'review', 'status'].map(action => [`memory ${action}`,
+        args(['search', 'decide'].includes(action) ? 'query*' : ['show', 'retire'].includes(action) ? 'query' : '', 'why reason supersedes source all decision sessions no-local')]),
+    ['flows list', args()],
+    ['flows show', args('flow:flow')], ['flows export', args('flow:flow')],
+    ['flows create', args('', 'yes name template', { steps: 'steps' })],
+    ['flows edit', args('flow:flow', 'yes name', { steps: 'steps' })],
+    ['flows trigger add', args('flow:flow trigger:trigger-json', 'yes')],
+    ...['pause', 'resume', 'remove'].map(action => [`flows trigger ${action}`, args('flow:flow trigger:trigger')]),
+    ['flows card add', args('flow:flow', 'title description zone')],
+    ['flows archive', args('flow:flow', 'yes')],
+    ['models status', args('', 'provider')], ['models list', args('', 'provider')],
+]);
+export const REMOTE_NOT_FOUND = { ok: false, reason: 'not-found', message: 'Not found.' };
+const positiveId = (value) => /^[1-9][0-9]*$/.test(value) && Number.isSafeInteger(Number(value));
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Read-only authorization of every supplied reference, before the handler can disclose or mutate it. */
+export function remoteArgumentsOf(store, allows, invocation, positional, flags, named, files) {
+    const audit = REMOTE_ARGUMENTS.get(invocation);
+    if (audit === undefined)
+        return REMOTE_NOT_FOUND;
+    const values = positional.slice(invocation.split(' ').length - 1);
+    const resolved = [];
+    const admit = (repo) => typeof repo === 'string' && allows(repo) && (named === null || named === repo);
+    const input = (value) => {
+        const raw = value.trim().startsWith('{') || value.trim().startsWith('[') ? value
+            : Object.prototype.hasOwnProperty.call(files, value) ? files[value] : undefined;
+        if (raw === undefined)
+            return undefined;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const check = (kind, value) => {
+        if (kind === 'value')
+            return true;
+        if (kind === 'review')
+            return check(flags.has('brief') ? 'task' : 'run', value);
+        if (kind === 'task' || kind === 'run') {
+            if (kind === 'task' && (!value || value.length > 64 || /[\x00-\x1f\x7f]/.test(value)))
+                return false;
+            if (kind === 'run' && !positiveId(value))
+                return false;
+            const run = kind === 'run' ? store.getRun(Number(value)) : null;
+            const ref = kind === 'run' ? run === null ? null : store.refById(run.taskRef) : store.lookupRef(value);
+            if (ref === null || !admit(ref.repo) || store.lookupRef(ref.externalId)?.id !== ref.id || store.getTask(ref.externalId) === null)
+                return false;
+            resolved.push({ repo: ref.repo, taskId: ref.externalId, taskRef: ref.id, kind });
+            return true;
+        }
+        if (kind === 'flow' || kind === 'trigger') {
+            if (!positiveId(value) || value.length > 10)
+                return false;
+            const trigger = kind === 'trigger' ? store.getFlowTrigger(Number(value)) : null;
+            const flow = kind === 'flow' ? store.getFlow(Number(value)) : trigger === null ? null : store.getFlow(trigger.flow);
+            if (flow === null || flow.state !== 'active' || !admit(flow.repo) || trigger?.state === 'removed')
+                return false;
+            resolved.push({ repo: flow.repo, taskId: null, ...(kind === 'flow' ? { flow: flow.id } : { parentFlow: trigger.flow }), kind });
+            return true;
+        }
+        if (kind === 'trigger-json') {
+            const config = input(value);
+            // Invalid/unavailable input cannot reach a resource lookup; the handler reports its existing file/JSON error.
+            if (!object(config))
+                return true;
+            return config['kind'] !== 'flow' || (typeof config['flow'] === 'number' && check('flow', String(config['flow'])));
+        }
+        if (kind === 'steps') {
+            const config = input(value), steps = object(config) ? config['steps'] : config;
+            if (!Array.isArray(steps))
+                return true;
+            // Build steps can name another project. Check the token ceiling as well as the owner's account grants.
+            return steps.every(step => !object(step) || step['repo'] === undefined ||
+                typeof step['repo'] === 'string' && store.knownRepos().includes(step['repo']) && allows(step['repo']));
+        }
+        return false;
+    };
+    for (const [name, value] of flags) {
+        const kind = audit.flags.get(name);
+        if (kind === 'step-up')
+            return { ok: false, reason: 'step-up', message: 'approve in the console or chat' };
+        if (kind === 'refused')
+            return { ok: false, reason: 'not-remote', message: 'That option is not available remotely.' };
+        if (kind === undefined)
+            return { ok: false, reason: 'usage', message: 'That option is not available for this remote command.' };
+        // Resolve positionals first below so the primary ledger target is stable regardless of flag order.
+        if (kind !== 'value' && typeof value !== 'string')
+            return REMOTE_NOT_FOUND;
+    }
+    for (let i = 0; i < audit.positionals.length; i++) {
+        const arg = audit.positionals[i];
+        const value = values[i];
+        if (value === undefined) {
+            if (arg.optional)
+                continue;
+            return REMOTE_NOT_FOUND;
+        }
+        if (!check(arg.kind, value))
+            return REMOTE_NOT_FOUND;
+    }
+    if (values.length > audit.positionals.length && !audit.positionals.at(-1)?.rest)
+        return REMOTE_NOT_FOUND;
+    for (const [name, value] of flags)
+        if (!check(audit.flags.get(name), String(value)))
+            return REMOTE_NOT_FOUND;
+    const task = resolved.find(ref => ref.kind === 'task');
+    for (const ref of resolved) {
+        if (ref.kind === 'run' && task !== undefined && ref.taskRef !== task.taskRef) {
+            // Review/revise accept a saved result from the same revision family. Stop/resume name an exact attempt.
+            const runFamily = store.taskFamilyOf(ref.taskId, [ref.repo], false);
+            const taskFamily = store.taskFamilyOf(task.taskId, [task.repo], false);
+            if (!['task review', 'task revise'].includes(invocation) || ref.repo !== task.repo || runFamily === null || taskFamily === null ||
+                runFamily.root.id !== taskFamily.root.id)
+                return REMOTE_NOT_FOUND;
+        }
+        if (ref.parentFlow !== undefined && ref.parentFlow !== resolved.find(one => one.kind === 'flow')?.flow)
+            return REMOTE_NOT_FOUND;
+    }
+    if (invocation === 'task repair') {
+        const draft = store.repairChainFor(Number(values[0]))?.draftTask;
+        if (draft != null && (!check('task', draft) || resolved.at(-1)?.repo !== resolved[0]?.repo))
+            return REMOTE_NOT_FOUND;
+    }
+    return { ok: true, repo: resolved[0]?.repo ?? named, taskId: resolved[0]?.taskId ?? null };
+}