toolroll 0.9.42 → 0.9.44

package/dist/flows-cli.js

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

package/dist/guides.js

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

package/dist/mate-contract.js

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

package/dist/mate-tools.js

@@ -48,7 +48,9 @@ import { TOOL_CATALOG, discoverTools, projectToolsOf, secretsSetFor, toolCommand
 import { deciderOf, durationWords, FLOW_KIND_WORDS, FLOW_TEMPLATES, flowFromSteps, stepsFor, withKeptSteps } from "./flows.js";
 import { parseContract, toModelSchema } from "./contracts/contract.js";
 import { LEAD_TOOL_INPUTS, LEAD_TOOL_READ_INPUTS, LEAD_TOOL_OPTIONS, LEAD_TOOL_OUTPUTS, reportToolOutput } from "./contracts/lead-tools.js";
-import { flowDefinitionOf } from "./flow-engine.js";
+import { flowCardHref, flowDefinitionOf } from "./flow-engine.js";
+import { planInChat } from "./chat-decide.js";
+import { flowDecisionAt } from "./telegram-flow.js";
 import { flowPersonOf } from "./flow-send.js";
 import { flowInsights } from "./flow-insights.js";
 import { describeTrigger, FLOW_TRIGGER_KINDS, triggerConfigOf } from "./flow-triggers.js";
@@ -491,6 +493,46 @@ const MATE_TOOL_HANDLERS = {
             return id === null ? tooMany() : { ok: true, body: { card: id, label: entry.label, action: "open existing control; nothing changed" } };
         },
     },
+    offer_approval: {
+        description: "When the owner asks to approve one thing (a plan waiting on them, or a flow card waiting at a Person decides step), send that item's own Approve and Send back buttons to their paired chat right away. Their tap there is the approval (two taps, as on any decision card); you never approve. Give task for a plan, or card for a flow card (its number from get_flows). When it can't be approved in chat, the answer says why: say that in one line and open show_control approval (a plan) or the flow, never that you can't approve.",
+        handle: (ctx, args) => {
+            const pairedHere = ctx.channel === "telegram";
+            const paired = ctx.store.handle.prepare("SELECT 1 FROM telegram_binding WHERE approver = ? AND approver_generation = ? AND revoked_at IS NULL LIMIT 1")
+                .get(ctx.who.name, ctx.store.accountOf(ctx.who.name)?.generation ?? -1) !== undefined;
+            const stamp = ctx.now.getTime();
+            if (args["card"] !== undefined) {
+                const cardId = Number(args["card"]);
+                const card = Number.isSafeInteger(cardId) ? ctx.store.getFlowCard(cardId) : null;
+                const flow = card === null ? null : ctx.store.getFlow(card.flow);
+                if (card === null || flow === null || !ctx.who.repos.includes(flow.repo))
+                    return { ok: false, message: "not-found: no such flow card in your projects" };
+                const waiting = flowDecisionAt(ctx.store, card.id, card.entry);
+                const href = flowCardHref(flow.id, card.id);
+                if (waiting === null)
+                    return { ok: true, body: { offered: false, why: card.state === "active" ? "That card isn't waiting for a decision now." : "That card isn't waiting any more.", open: href } };
+                const decider = deciderOf(waiting.stage, waiting.flow);
+                if (decider !== null && decider !== ctx.who.name)
+                    return { ok: true, body: { offered: false, why: `Only ${decider} decides here.`, open: href } };
+                if (!pairedHere || !paired)
+                    return { ok: true, body: { offered: false, why: pairedHere ? "Your chat isn't paired for decisions." : "Buttons go to your paired chat; here, approve it on the card.", open: href } };
+                ctx.store.enqueueNotification({ dedupeKey: `flow-decide:${card.id}:${card.entry}:ask:${stamp}`, kind: "flow-decision", pushClass: "attention", recipient: ctx.who.name,
+                    subject: `${flow.name}: ${card.title} needs your decision`.slice(0, 200), body: `${waiting.stage.title}: approve it, or send it back with a note.`, link: href, source: { project: flow.repo } }, ctx.now);
+                return { ok: true, body: { offered: true, item: `flow card ${card.id}`, shown: "Approve and Send back buttons follow your reply in this chat; the owner's tap decides it" } };
+            }
+            const task = taskIdOf(args);
+            if (task === null || admittedRef(ctx, task) === null)
+                return notFound();
+            const current = ctx.store.taskFamilyOf(task, ctx.who.repos, false)?.current.id ?? task;
+            const plan = planInChat(ctx.store, current, ctx.who.name, ctx.now, ctx.evidenceRoot);
+            if (!plan.ok)
+                return { ok: true, body: { offered: false, task: current, why: plan.why, control: "approval" } };
+            if (!pairedHere || !paired)
+                return { ok: true, body: { offered: false, task: current, why: pairedHere ? "Your chat isn't paired for decisions." : "Buttons go to your paired chat; here, approve it on its card.", control: "approval" } };
+            ctx.store.enqueueNotification({ dedupeKey: `plan-ready:${current}:ask:${stamp}`, kind: "plan-ready", recipient: ctx.who.name, subject: `${current}: plan ready for review`,
+                body: "Approve it here, or open it to edit first.", source: { taskRef: ctx.store.lookupRef(current).id } }, ctx.now);
+            return { ok: true, body: { offered: true, item: `plan for ${current}`, task: current, shown: "Approve & start follows your reply in this chat; the owner's two taps approve it" } };
+        },
+    },
     get_result: {
         description: "Read exact execution/run and feedback. Use get_task currentExecution; page nextFeedbackOffset.",
         handle: (ctx, args) => {

package/dist/mcp-core.d.ts

@@ -0,0 +1,110 @@
+import { type GatewayToolName } from "./contracts/gateway-tools.js";
+import type { Store } from "./store.js";
+import { type VerifiedCoordinator } from "./coordinator.js";
+export declare const MODERN = "2026-07-28";
+export declare const LEGACY = "2025-11-25";
+/** The modern revision namespaces its per-request metadata. */
+export declare const META_VERSION = "io.modelcontextprotocol/protocolVersion";
+export declare const META_SERVER = "io.modelcontextprotocol/serverInfo";
+export declare const META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+/** The revision's own error code for an unsupported protocol version. */
+export declare const UNSUPPORTED_VERSION = -32022;
+export declare const MAX_REQUEST: number;
+export declare const MAX_DEPTH = 32;
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export declare function depthOf(value: unknown): number;
+/** One handler per tool; its input is GATEWAY_TOOL_INPUTS[name]
+ * (src/contracts/gateway-tools.ts) — THE source for parsing and inputSchema.
+ * Output is built field-by-field; spreading a database row into a result is
+ * forbidden in this module (arch-tested). */
+export type ToolContext = {
+    store: Store;
+    who: VerifiedCoordinator;
+    /** The installation's enrolled repos (repos.json), when the launcher
+     * knows them — list_repos answers allowlist ∩ enrolled. null = the
+     * launcher could not read the registry; the allowlist alone answers. */
+    enrolled: readonly string[] | null;
+    /** The raw credential, per-SERVER closure state — never module state:
+     * two serveMcp instances in one process must not cross credentials
+     * (implementation review, finding 5). Filing re-authenticates with it
+     * inside its own transaction. */
+    token: string;
+    now: Date;
+    /** Decisions this connection read with get_decision — propose_answer needs one. */
+    readDecisions: Set<number>;
+    /** Where evidence lives, when the launcher knows — get_task reads a scout's report from here. */
+    evidenceRoot?: string;
+};
+export type Answer = {
+    ok: true;
+    body: Json;
+} | {
+    ok: false;
+    message: string;
+};
+type Tool = {
+    name: GatewayToolName;
+    description: string;
+    inputSchema: Json;
+    handle: (ctx: ToolContext, args: Record<string, unknown>) => Answer;
+};
+/** The gateway's tools in tools/list order, each inputSchema derived from its contract. */
+export declare const TOOLS: Tool[];
+/** The tools/list payload for a registry. No outputSchema: MCP output schemas describe structuredContent, and these
+ * tools return text content only (round-2 finding 1). */
+export declare const toolsPayload: (tools: readonly {
+    name: string;
+    description: string;
+    inputSchema: Json;
+}[]) => {
+    tools: Json;
+};
+/** A modern result is schema-complete; a cacheable one (tools/list, discover) carries `ttlMs: 0` and the narrowest scope. */
+export declare function shapeResult(era: "modern" | "legacy", result: Record<string, Json>, cacheable: boolean): Record<string, Json>;
+/** One JSON-RPC message, read and checked before any method applies. */
+export type ReadMessage = {
+    ok: true;
+    hasId: boolean;
+    id: Json;
+    method: string;
+    params: Record<string, unknown>;
+    meta: Record<string, unknown>;
+} | {
+    ok: false;
+    id: Json;
+    code: number;
+    message: string;
+};
+/** Read one message's text: size, JSON, no batching, depth, `jsonrpc`, and the id rules. A notification is the message
+ * that carries NO id — the method name never decides (round-3 finding 3). MCP RequestId is a string or an INTEGER
+ * (round-2 finding 2): floats, null, and object shapes refuse wherever an id appears. */
+export declare function readMessage(text: string): ReadMessage;
+/** ClientCapabilities is an OBJECT shape (round-3 finding 5): an array is not a capabilities declaration. */
+export declare const capabilitiesShape: (value: unknown) => boolean;
+/** What a tools/call came to: a JSON-RPC error (`fatal` = the stdio server must exit after it) or a tool result. */
+export type CallOutcome = {
+    kind: "error";
+    code: number;
+    message: string;
+    fatal: boolean;
+} | {
+    kind: "result";
+    result: Record<string, Json>;
+};
+/** The `arguments` of a call: only an ABSENT value defaults to empty (round-3 finding 2), and the root is an object
+ * BEFORE any schema applies (round-2 finding 2): 42 or false never passes an empty schema. */
+export declare function callArguments(params: Record<string, unknown>): Record<string, unknown> | null;
+/** A handler's answer as a tools/call result: a refusal is `isError`, never a protocol error. */
+export declare function answerResult(answered: Answer): Record<string, Json>;
+/**
+ * One coordinator tools/call. 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. tools/list visibility is presentation — authorization happens HERE, on every call, against the
+ * live credential row.
+ */
+export declare function callCoordinatorTool(call: Omit<ToolContext, "who" | "now"> & {
+    clock: () => Date;
+}, params: Record<string, unknown>): CallOutcome;
+export {};

package/dist/mcp-core.js

@@ -0,0 +1,311 @@
+/**
+ * The MCP gateway's transport-free core (MCP gateway spec v6): protocol
+ * constants and limits, message reading, the coordinator tool registry and
+ * its per-call authorization. The stdio adapter (mcp.ts) and the HTTP adapter
+ * (mcp-http.ts) each own their transport and lifecycle; neither re-implements
+ * what a call means.
+ *
+ * Protocol errors are JSON-RPC errors; tool-level refusals are successful
+ * `tools/call` results with `isError: true`.
+ */
+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";
+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;
+export const MAX_REQUEST = 256 * 1024;
+export const MAX_DEPTH = 32;
+export 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. */
+export 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) };
+});
+/** The tools/list payload for a registry. No outputSchema: MCP output schemas describe structuredContent, and these
+ * tools return text content only (round-2 finding 1). */
+export const toolsPayload = (tools) => ({
+    tools: tools.map(tool => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema })),
+});
+/** A modern result is schema-complete; a cacheable one (tools/list, discover) carries `ttlMs: 0` and the narrowest scope. */
+export function shapeResult(era, result, cacheable) {
+    return era === "modern" ? { ...result, resultType: "complete", ...(cacheable ? { ttlMs: 0, cacheScope: "private" } : {}) } : result;
+}
+/** Read one message's text: size, JSON, no batching, depth, `jsonrpc`, and the id rules. A notification is the message
+ * that carries NO id — the method name never decides (round-3 finding 3). MCP RequestId is a string or an INTEGER
+ * (round-2 finding 2): floats, null, and object shapes refuse wherever an id appears. */
+export function readMessage(text) {
+    if (Buffer.byteLength(text, "utf8") > MAX_REQUEST)
+        return { ok: false, id: null, code: -32600, message: "request over 256 KiB" };
+    let message;
+    try {
+        message = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, id: null, code: -32700, message: "parse error" };
+    }
+    // Batching left MCP in 2025-06-18 — neither pinned era accepts it.
+    if (Array.isArray(message))
+        return { ok: false, id: null, code: -32600, message: "JSON-RPC batching is not part of MCP — send one request per line" };
+    if (message === null || typeof message !== "object" || depthOf(message) > MAX_DEPTH)
+        return { ok: false, id: null, code: -32600, message: "invalid request" };
+    const request = message;
+    if (request["jsonrpc"] !== "2.0")
+        return { ok: false, id: null, code: -32600, message: 'jsonrpc must be "2.0"' };
+    const hasId = "id" in request;
+    const rawId = request["id"];
+    if (hasId && (rawId === null || (typeof rawId !== "string" && !(typeof rawId === "number" && Number.isInteger(rawId))))) {
+        return { ok: false, id: null, code: -32600, message: "id must be a string or an integer" };
+    }
+    const method = typeof request["method"] === "string" ? request["method"] : "";
+    if (method.startsWith("notifications/")) {
+        if (hasId)
+            return { ok: false, id: rawId, code: -32600, message: "a notification carries no id" };
+    }
+    else if (!hasId) {
+        return { ok: false, id: null, code: -32600, message: "a request carries an id — a string or an integer" };
+    }
+    const params = (request["params"] ?? {});
+    const meta = (params["_meta"] ?? {});
+    return { ok: true, hasId, id: (rawId ?? null), method, params, meta };
+}
+/** ClientCapabilities is an OBJECT shape (round-3 finding 5): an array is not a capabilities declaration. */
+export const capabilitiesShape = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The `arguments` of a call: only an ABSENT value defaults to empty (round-3 finding 2), and the root is an object
+ * BEFORE any schema applies (round-2 finding 2): 42 or false never passes an empty schema. */
+export function callArguments(params) {
+    const raw = params["arguments"] === undefined ? {} : params["arguments"];
+    return typeof raw !== "object" || raw === null || Array.isArray(raw) ? null : raw;
+}
+/** A handler's answer as a tools/call result: a refusal is `isError`, never a protocol error. */
+export function answerResult(answered) {
+    return answered.ok ? { content: [{ type: "text", text: JSON.stringify(answered.body) }] } : { content: [{ type: "text", text: answered.message }], isError: true };
+}
+/**
+ * One coordinator tools/call. 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. tools/list visibility is presentation — authorization happens HERE, on every call, against the
+ * live credential row.
+ */
+export function callCoordinatorTool(call, params) {
+    const { store, token, clock, ...rest } = call;
+    return store.transact(() => {
+        if (!store.schemaCurrent())
+            return { kind: "error", code: -32000, message: "the database schema moved underneath this server — restart it", fatal: true };
+        const name = typeof params["name"] === "string" ? params["name"] : "";
+        const tool = TOOLS.find(one => one.name === name);
+        if (tool === undefined)
+            return { kind: "error", code: -32602, message: `no tool \`${name}\``, fatal: false };
+        const session = authenticateCoordinator(store, token);
+        if (!session.ok)
+            return { kind: "error", code: -32000, message: "this credential no longer stands — the server exits", fatal: true };
+        const rawArgs = callArguments(params);
+        if (rawArgs === null)
+            return { kind: "error", code: -32602, message: "arguments must be an object", fatal: false };
+        // 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)
+            return { kind: "error", code: -32602, message: read.issues.map(one => one.line).join("; "), fatal: false };
+        const answered = tool.handle({ store, token, who: session.who, now: clock(), ...rest }, read.value);
+        // Checked against its output schema before delivery; a disagreement is reported, never refused.
+        if (answered.ok)
+            reportToolOutput("gateway", tool.name, GATEWAY_TOOL_OUTPUTS[tool.name], answered.body);
+        return { kind: "result", result: answerResult(answered) };
+    });
+}

package/dist/mcp-http.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The MCP gateway over streamable HTTP, served at /mcp by the console (serve.ts). Stateless: one JSON-RPC message per
+ * POST, answered with one JSON body (a notification gets 202 and no body); there is no session and no event stream.
+ * The modern revision carries its version in `_meta` as on stdio; a handshake-era client may initialize, and because
+ * nothing is kept between requests its tools work without the stdio lifecycle.
+ *
+ * Every POST signs in again. The caller is a coordinator credential (the coordinator registry, exactly as on stdio) or
+ * a person's own API token `so_…` (mcp-person.ts: their role, project grants and token scope). A password
+ * (`name:password`) and cookies sign in nothing here, a request carrying a browser Origin is refused, and the console's
+ * Host check runs before this route. A revoked or expired token answers 401 on its next request.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Store } from "./store.js";
+import { type RunOperateAs } from "./mcp-person.js";
+export type McpHttpOptions = {
+    store: Store;
+    clock: () => Date;
+    /** The enrolled projects: a coordinator's list_repos answers allowlist ∩ enrolled. */
+    enrolled: () => readonly string[] | null;
+    evidenceRoot?: string;
+    /** The console's own sign-in for an `so_` bearer: the address's tries, expiry, revocation, a removed account. */
+    signedIn: (request: IncomingMessage) => boolean;
+    /** Runs a person's command on the server (operate.ts); resolved from operate.ts when not injected. */
+    runAs?: RunOperateAs;
+};
+export declare function createMcpHttp(options: McpHttpOptions): (request: IncomingMessage, response: ServerResponse) => Promise<void>;