@sabaiway/agent-workflow-kit 5.11.2 → 7.0.0

package/tools/mcp-stdio.mjs

@@ -0,0 +1,229 @@
+// mcp-stdio.mjs — JSON-RPC 2.0 line framing for the kit's stdio MCP server (the transport half).
+//
+// The MCP stdio transport is newline-delimited JSON-RPC over stdin/stdout: one message per line, no
+// embedded newline, UTF-8, nothing on stdout that is not a message. This module owns exactly that and
+// nothing about tools: a bounded line reader, the request/notification/response classification, the
+// lifecycle gate (initialize first, ping any time) and a dispatcher that turns a parsed message into
+// ONE response object or null. Streams are INJECTED so the whole contract is testable without a process.
+//
+// Bounds, stated: a line longer than `maxLineBytes` is answered with -32600 (id null) and the transport
+// then CLOSES — a null-id error cannot be correlated with the request that caused it, so a client would
+// otherwise wait on it forever, while a server that exits is one it can restart. (The line reader itself
+// can resync at the next newline; the transport chooses not to continue.) Bytes are buffered and decoded
+// only per complete line, so a UTF-8 code point split across two chunks is never replaced. Dependency-
+// free, Node >= 22, no side effects on import; no CLI of its own (mcp-server.mjs is the entry point).
+
+export const PROTOCOL_VERSION = '2025-06-18';
+// Newest first. A requested version in this set is echoed; anything else is answered with the newest,
+// as the lifecycle spec prescribes (the client then decides whether to continue).
+export const SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(['2025-06-18', '2025-03-26', '2024-11-05']);
+export const MAX_LINE_BYTES = 4 * 1024 * 1024;
+export const JSONRPC_ERRORS = Object.freeze({
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+});
+
+const JSONRPC_VERSION = '2.0';
+const NEWLINE = 0x0a;
+const CARRIAGE_RETURN = 0x0d;
+const METHOD_INITIALIZE = 'initialize';
+const METHOD_PING = 'ping';
+const PRE_INITIALIZE_METHODS = Object.freeze([METHOD_INITIALIZE, METHOD_PING]);
+
+export const rpcError = (code, message) => Object.assign(new Error(message), { rpcCode: code });
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+// MCP's RequestId is a string or an integer, never null; and a numeric id must survive parse →
+// serialize unchanged, or the answer no longer correlates with the request: only a safe integer does
+// (1.5, 1e400 and friends are refused as invalid requests). The server's OWN null id on an error
+// for an unparseable line is a different thing: a response, not a request.
+const isValidId = (id) => typeof id === 'string' || Number.isSafeInteger(id);
+// A client RESPONSE carries an id and exactly one of result / error; it is the one shape the server
+// never answers. Anything else without a method is an invalid request, answered — never swallowed.
+const isClientResponse = (message) =>
+  'id' in message && (Object.hasOwn(message, 'result') !== Object.hasOwn(message, 'error'));
+
+export const negotiateProtocolVersion = (requested) =>
+  SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSION;
+
+export const isNotification = (message) => typeof message.method === 'string' && !('id' in message);
+
+// One line → { message } or { error: { code, message } } (the error is answered with id null).
+export const parseLine = (line) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return { error: { code: JSONRPC_ERRORS.PARSE_ERROR, message: 'Parse error' } };
+  }
+  if (!isPlainObject(parsed) || parsed.jsonrpc !== JSONRPC_VERSION) {
+    return { error: { code: JSONRPC_ERRORS.INVALID_REQUEST, message: 'Invalid Request: not a JSON-RPC 2.0 object' } };
+  }
+  if ('id' in parsed && !isValidId(parsed.id)) {
+    return { error: { code: JSONRPC_ERRORS.INVALID_REQUEST, message: 'Invalid Request: id must be a string or an integer' } };
+  }
+  if ('method' in parsed && typeof parsed.method !== 'string') {
+    return { error: { code: JSONRPC_ERRORS.INVALID_REQUEST, message: 'Invalid Request: method must be a string' } };
+  }
+  return { message: parsed };
+};
+
+const errorResponse = (id, code, message) => ({ jsonrpc: JSONRPC_VERSION, id, error: { code, message } });
+const resultResponse = (id, result) => ({ jsonrpc: JSONRPC_VERSION, id, result });
+
+// A lossy decode would replace an invalid byte with U+FFFD and the request could then name a DIFFERENT,
+// existing path — the substitution class both readers refuse; a line that is not UTF-8 is a parse error.
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true });
+
+// Bytes in, complete lines out. The pending buffer is capped: past `maxLineBytes` without a newline the
+// reader drops bytes until the next newline, reporting the overflow ONCE, then frames normally again.
+export const createLineReader = ({ maxLineBytes = MAX_LINE_BYTES, onLine, onOverflow, onInvalidUtf8 = () => {} }) => {
+  let pending = [];
+  let pendingBytes = 0;
+  let discarding = false;
+
+  const emit = () => {
+    const buf = Buffer.concat(pending, pendingBytes);
+    pending = [];
+    pendingBytes = 0;
+    const end = buf.length > 0 && buf[buf.length - 1] === CARRIAGE_RETURN ? buf.length - 1 : buf.length;
+    let text;
+    try {
+      text = strictUtf8.decode(buf.subarray(0, end));
+    } catch {
+      onInvalidUtf8();
+      return;
+    }
+    onLine(text);
+  };
+
+  const feed = (chunk) => {
+    let from = 0;
+    for (;;) {
+      const at = chunk.indexOf(NEWLINE, from);
+      const piece = chunk.subarray(from, at === -1 ? chunk.length : at);
+      if (discarding) {
+        if (at === -1) return;
+        discarding = false;
+      } else if (pendingBytes + piece.length > maxLineBytes) {
+        pending = [];
+        pendingBytes = 0;
+        onOverflow();
+        if (at === -1) {
+          discarding = true;
+          return;
+        }
+      } else {
+        if (piece.length > 0) {
+          pending.push(piece);
+          pendingBytes += piece.length;
+        }
+        if (at === -1) return;
+        emit();
+      }
+      from = at + 1;
+      if (from >= chunk.length) return;
+    }
+  };
+
+  // A final line without a trailing newline is still a message; a discarded tail is not.
+  const end = () => {
+    if (!discarding && pendingBytes > 0) emit();
+  };
+
+  return { feed, end };
+};
+
+// handlers: { [method]: (params) => result } for everything beyond initialize/ping. A handler may throw
+// rpcError(code, message) for a typed error; any other throw is an internal error WITH its message.
+export const createDispatcher = ({ handlers = {}, serverInfo, capabilities = { tools: {} }, instructions }) => {
+  let initialized = false;
+
+  const handle = (message) => {
+    if (typeof message.method !== 'string') {
+      if (isClientResponse(message)) return null; // a response to something — never answered
+      return errorResponse(message.id ?? null, JSONRPC_ERRORS.INVALID_REQUEST, 'Invalid Request: neither a request, a notification nor a response');
+    }
+    if (isNotification(message)) return null; // initialized, cancelled, anything: silence
+    const { id, method } = message;
+    if ('params' in message && message.params !== undefined && !isPlainObject(message.params)) {
+      return errorResponse(id, JSONRPC_ERRORS.INVALID_PARAMS, `Invalid params: "${method}" params must be an object`);
+    }
+    if (!initialized && !PRE_INITIALIZE_METHODS.includes(method)) {
+      return errorResponse(id, JSONRPC_ERRORS.INVALID_REQUEST, `Invalid Request: "${method}" before initialize`);
+    }
+    if (method === METHOD_PING) return resultResponse(id, {});
+    if (method === METHOD_INITIALIZE) {
+      // The three required fields are checked BEFORE the state flips: a malformed initialize leaves the
+      // server un-initialized and is answered as invalid params, never served as a handshake.
+      const params = isPlainObject(message.params) ? message.params : null;
+      const client = params !== null && isPlainObject(params.clientInfo) ? params.clientInfo : null;
+      if (params === null || typeof params.protocolVersion !== 'string' || !isPlainObject(params.capabilities) || client === null || typeof client.name !== 'string' || typeof client.version !== 'string') {
+        return errorResponse(id, JSONRPC_ERRORS.INVALID_PARAMS, 'initialize: protocolVersion (string), capabilities (object) and clientInfo { name, version } (strings) are required');
+      }
+      initialized = true;
+      const result = { protocolVersion: negotiateProtocolVersion(params.protocolVersion), capabilities, serverInfo };
+      if (typeof instructions === 'string') result.instructions = instructions;
+      return resultResponse(id, result);
+    }
+    const handler = Object.hasOwn(handlers, method) ? handlers[method] : undefined;
+    if (typeof handler !== 'function') return errorResponse(id, JSONRPC_ERRORS.METHOD_NOT_FOUND, `Method not found: ${method}`);
+    try {
+      return resultResponse(id, handler(isPlainObject(message.params) ? message.params : {}));
+    } catch (err) {
+      if (typeof err?.rpcCode === 'number') return errorResponse(id, err.rpcCode, err.message);
+      return errorResponse(id, JSONRPC_ERRORS.INTERNAL_ERROR, `Internal error: ${err?.message ?? err}`);
+    }
+  };
+
+  return { handle };
+};
+
+// Serve until the input ends. `input` is an async iterable of Buffers (process.stdin, a PassThrough),
+// `output` anything with write(string) — and, when it also has once(), its backpressure is honoured:
+// a write that returns false stops the flush until 'drain', so a run of large answers never piles up
+// unbounded in process memory. Every write is exactly one JSON document plus "\n" — JSON.stringify
+// escapes every newline inside strings, so no message ever embeds one.
+export const serveStdio = async ({ input, output, dispatcher, maxLineBytes = MAX_LINE_BYTES }) => {
+  // The reader only QUEUES framed lines (bounded by the chunk size); each line is dispatched and its
+  // answer written one at a time, with the drain wait BETWEEN lines — so a chunk holding many compact
+  // requests never has all their answers computed and held in memory at once.
+  const pending = [];
+  const reader = createLineReader({
+    maxLineBytes,
+    onOverflow: () => pending.push({ overflow: true }),
+    onInvalidUtf8: () => pending.push({ invalidUtf8: true }),
+    onLine: (line) => pending.push({ line }),
+  });
+  const answerFor = (entry) => {
+    if (entry.overflow) return errorResponse(null, JSONRPC_ERRORS.INVALID_REQUEST, `Invalid Request: line exceeds ${maxLineBytes} byte(s) — the transport is closing; restart the server`);
+    if (entry.invalidUtf8) return errorResponse(null, JSONRPC_ERRORS.PARSE_ERROR, 'Parse error: the line is not valid UTF-8');
+    if (entry.line.trim() === '') return null;
+    const parsed = parseLine(entry.line);
+    if (parsed.error) return errorResponse(null, parsed.error.code, parsed.error.message);
+    return dispatcher.handle(parsed.message);
+  };
+  // Returns true once the transport must close: a null-id overflow error cannot be correlated, so
+  // nothing after it is served — not even the rest of the same chunk.
+  const drainPending = async () => {
+    while (pending.length > 0) {
+      const entry = pending.shift();
+      const response = answerFor(entry);
+      if (response !== null) {
+        const accepted = output.write(`${JSON.stringify(response)}\n`);
+        if (accepted === false && typeof output.once === 'function') await new Promise((resolve) => output.once('drain', resolve));
+      }
+      if (entry.overflow) return true;
+    }
+    return false;
+  };
+  for await (const chunk of input) {
+    reader.feed(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    if (await drainPending()) return;
+  }
+  reader.end();
+  await drainPending();
+};

package/tools/mcp.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+// mcp.mjs — the guarded writer behind `/agent-workflow-kit mcp`: registers the kit's stdio MCP
+// server in ONE project, so the typed readers (`path_inventory`, `repo_search`) reach a deployed
+// project instead of only the repo that built them. It writes exactly two files:
+//   • `.mcp.json` at the project root — the `agent-workflow` stdio entry (command `node`, args = the
+//     RUNNING kit's tools/mcp-server.mjs, absolute);
+//   • `.claude/settings.json` — `enabledMcpjsonServers: ["agent-workflow"]` plus the two allow rules
+//     derived from the server's own SERVER_NAME + TOOLS.
+//
+// Same family writer discipline as gate-hook.mjs, and the same reasons:
+//   • preview-then-mutate — `--dry-run` is the DEFAULT and writes nothing; `--apply` writes;
+//   • the ENTRY is printed BEFORE consent — a registration is a command the client will RUN, so the
+//     exact structured value is on screen at the moment the decision is made, never described in
+//     prose. It is re-serialized for the preview, so it is that VALUE and not those literal bytes;
+//   • `.mcp.json` FIRST, then settings — settings enabling a server whose entry is not yet there
+//     would be a client error on every startup;
+//   • merge-don't-clobber — foreign servers, foreign settings keys and existing allow rules are
+//     preserved; re-apply adds nothing twice; the file's EOL is kept;
+//   • a same-name entry that STRUCTURALLY DIFFERS is REFUSED unwritten (key order is ignored, so a
+//     re-serialized identical entry is the SAME registration) — silently changing what an MCP server
+//     launches is exactly what consent must not slide past; the recovery is named;
+//   • the preflight is READ-ONLY: an absent `.claude/` is a NAMED state, and the dir is created on
+//     `--apply` only (assertCreatableDirSafe mkdirs, so it may not run in a preview);
+//   • a MASKED target (an OS sandbox injects a character device where `.mcp.json` would be — this
+//     repo is exactly that case) is not a failure: the kit hands over both paste-ready fragments,
+//     writes nothing, and exits 0. Where it cannot write, it says precisely what it would have.
+//   • never `settings.local.json`; never commits.
+//
+// The read half lives in mcp-registration.mjs, which the advisor and `uninstall` use — so what is
+// there and what would be written are computed by one module, never by two that can disagree.
+//
+// Exit codes: 0 done / dry-run (incl. the hand-apply masked state); 1 precondition STOP; 2 usage.
+// Dependency-free beyond the kit's own exports, Node >= 22. No side effects on import.
+
+import { lstatSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertCreatableDirSafe, writeContainedFileAtomic } from './atomic-write.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import {
+  CLAUDE_DIR_REL,
+  ENABLED_KEY,
+  MCP_JSON_REL,
+  SERVERS_KEY,
+  SERVER_NAME,
+  SETTINGS_REL,
+  STATE,
+  formatJson,
+  mergeMcpJson,
+  mergeSettings,
+  readRegistration,
+  renderFragments,
+} from './mcp-registration.mjs';
+import { shellQuoteArg } from './review-state.mjs';
+
+const q = shellQuoteArg;
+
+export const MCP_SYMLINK = 'MCP_SYMLINK';
+export const MCP_MALFORMED = 'MCP_MALFORMED';
+export const MCP_DIFFERS = 'MCP_DIFFERS';
+
+const EXIT_OK = 0;
+const EXIT_PRECONDITION = 1;
+const EXIT_USAGE = 2;
+const ERROR_PREFIX = '[agent-workflow-kit]';
+const LF = '\n';
+const JSON_INDENT = 2;
+
+export const MCP_TOOL = fileURLToPath(import.meta.url);
+export const applyMcpCommand = (root) => `node ${q(MCP_TOOL)} --apply --cwd ${q(root)}`;
+
+const USAGE = `usage: mcp [--dry-run | --apply] [--cwd <dir>] [--help]
+
+Registers this kit's stdio MCP server in ONE project: the "${SERVER_NAME}" entry in
+${MCP_JSON_REL}, and "${ENABLED_KEY}" + the two tool allow rules in ${SETTINGS_REL}.
+Default is --dry-run (a preview that prints the exact entry and writes nothing).
+--apply writes: ${MCP_JSON_REL} first, then ${SETTINGS_REL}; merge-don't-clobber, EOL kept.
+
+An existing "${SERVER_NAME}" entry that STRUCTURALLY DIFFERS is refused unwritten (key
+order is ignored). Where ${MCP_JSON_REL} is a device node, FIFO or socket — an OS sandbox
+mask is the usual cause — the entry to merge is printed and nothing is written.
+Never writes settings.local.json; never commits.`;
+
+export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+
+export const makeMcpError = (code, message) =>
+  Object.assign(new Error(`${ERROR_PREFIX} ${message}`), { name: 'McpError', code, exitCode: EXIT_PRECONDITION });
+
+const lstatNoFollow = (path, lstat = lstatSync) => {
+  try {
+    return (lstat ?? lstatSync)(path);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+};
+
+// ── preflight (READ-ONLY — it creates nothing, on either lane) ─────────────────────────
+
+// A target we could not read or parse is never overwritten: a merge over a file whose current
+// content is unknown is a clobber wearing a merge's name.
+//
+// `maskedAllowed` is TRUE for `.mcp.json` alone. That file has a sanctioned handoff — the kit hands
+// over the entry for a human to merge from outside the sandbox — and `settings.json` has none, so a
+// mask there is an ordinary refusal rather than a second, unplanned success path.
+const assertTargetUsable = (target, { maskedAllowed = false } = {}) => {
+  if (target.state === STATE.MASKED) {
+    if (maskedAllowed) return;
+    throw makeMcpError(
+      MCP_SYMLINK,
+      `${target.rel} is a ${target.className} (an OS sandbox device mask is the usual cause) — this mode can neither write it nor merge into what it cannot read`,
+    );
+  }
+  if (target.state === STATE.FOREIGN) {
+    throw makeMcpError(MCP_SYMLINK, `${target.rel} is a ${target.className} — refusing to write through it`);
+  }
+  if (target.state === STATE.MALFORMED) {
+    throw makeMcpError(MCP_MALFORMED, `${target.rel} is ${target.reason} — refusing to overwrite it; fix or remove it, then re-run`);
+  }
+  if (target.state === STATE.UNREADABLE) {
+    throw makeMcpError(MCP_MALFORMED, `${target.rel} cannot be read (${target.reason}) — refusing to overwrite what was never read`);
+  }
+};
+
+export const preflightMcp = ({ cwd }, deps = {}) => {
+  const root = resolve(cwd ?? deps.cwd ?? process.cwd());
+  // The ROOT is judged BEFORE the registration is read, not merely before the first write: reading
+  // first would follow the very link this refuses, which is exactly what the shipped claim denies.
+  const rootStat = lstatNoFollow(root, deps.lstat);
+  // A target that does not exist read as "a project with two absent files", so the preview offered an
+  // apply that could only ENOENT. Both lanes refuse the same way, at the same point.
+  if (rootStat === null) {
+    throw makeMcpError(MCP_SYMLINK, `${root} does not exist — name an existing project directory`);
+  }
+  if (rootStat.isSymbolicLink()) {
+    throw makeMcpError(MCP_SYMLINK, `${root} is a symlink — refusing to register into a symlinked project root`);
+  }
+  if (!rootStat.isDirectory()) {
+    throw makeMcpError(MCP_SYMLINK, `${root} is not a directory — name an existing project directory`);
+  }
+  const registration = readRegistration(root, deps);
+  // ORDER IS THE CONTRACT. Every OBSERVABLE surface is judged first — the container, both targets'
+  // classes, then the entry itself — and only a run that survives all of them may reach the one
+  // handoff this mode has. Taking the handoff early made a mask on ANY surface swallow the refusals
+  // behind it: a differing entry and a malformed settings file both came back as a cheerful exit 0.
+  const dir = registration.claudeDir;
+  if (dir.state === STATE.FOREIGN) {
+    throw makeMcpError(MCP_SYMLINK, `${dir.rel} is a ${dir.className} — refusing to write through it`);
+  }
+  if (dir.state === STATE.UNREADABLE) {
+    throw makeMcpError(MCP_MALFORMED, `${dir.rel} cannot be inspected (${dir.reason}) — refusing to write into it`);
+  }
+  assertTargetUsable(registration.mcpJson, { maskedAllowed: true });
+  assertTargetUsable(registration.settings);
+  if (registration.mcpJson.differs) {
+    throw makeMcpError(
+      MCP_DIFFERS,
+      `${MCP_JSON_REL} already carries an "${SERVER_NAME}" server entry that STRUCTURALLY DIFFERS from this kit copy's registration — refusing to change what it launches; review that entry and remove or rename it, then re-run`,
+    );
+  }
+  const masked = registration.mcpJson.state === STATE.MASKED;
+  return { root, registration, masked, plan: planMcp(registration) };
+};
+
+// The plan is pure over the registration: what is missing, and the exact body each file would get.
+// Both bodies are built even when nothing is written — they ARE the preview and the hand-apply text.
+export const planMcp = (registration) => ({
+  writeMcpJson: !registration.mcpJson.matches,
+  writeSettings: !registration.settings.complete,
+  mcpBody: formatJson(mergeMcpJson(registration), registration.mcpJson.eol),
+  settingsBody: formatJson(mergeSettings(registration), registration.settings.eol),
+});
+
+// ── the writer ─────────────────────────────────────────────────────────────────────────
+
+export const writeMcp = ({ cwd, dryRun = true } = {}, deps = {}) => {
+  const preflight = preflightMcp({ cwd: cwd ?? deps.cwd ?? process.cwd() }, deps);
+  const base = { ...preflight, dryRun, wrote: false };
+  if (preflight.masked) return { ...base, fragments: renderFragments(preflight.registration) };
+  if (dryRun) return base;
+
+  const { root, registration, plan } = preflight;
+  const stop = (message) => makeMcpError(MCP_SYMLINK, message);
+  if (plan.writeMcpJson) {
+    writeContainedFileAtomic(root, registration.mcpJson.abs, plan.mcpBody, deps, { stop, label: MCP_JSON_REL });
+  }
+  if (plan.writeSettings) {
+    // The ONE write the preflight deliberately does not do: creating `.claude/` is a mutation, so it
+    // belongs on the apply lane only — a preview that made a directory would not be a preview.
+    assertCreatableDirSafe(join(root, CLAUDE_DIR_REL), deps, { stop, noun: SETTINGS_REL });
+    writeContainedFileAtomic(root, registration.settings.abs, plan.settingsBody, deps, { stop, label: SETTINGS_REL });
+  }
+  return { ...base, wrote: plan.writeMcpJson || plan.writeSettings };
+};
+
+// ── the report ─────────────────────────────────────────────────────────────────────────
+
+const POSTURE_LINE =
+  'trust posture: the registered server is a READ-ONLY child of your MCP client (path/type/size/line facts and literal search over this project root) — it runs OUTSIDE the Bash sandbox, as the client itself does, and exposes no write or exec API. The two allow rules make its tool calls promptless; nothing else in this project changes.';
+
+const indented = (text) => text.trimEnd().split(LF).map((line) => `    ${line}`).join(LF);
+
+const mcpJsonLine = (result) => {
+  if (!result.plan.writeMcpJson) return `  - ${MCP_JSON_REL}: already current`;
+  const verb = result.dryRun ? 'would add' : 'added';
+  return `  - ${MCP_JSON_REL}: ${verb} the "${SERVER_NAME}" stdio entry`;
+};
+
+const settingsLine = (result) => {
+  const { registration, plan, dryRun } = result;
+  if (!plan.writeSettings) return `  - ${SETTINGS_REL}: already current`;
+  const parts = [];
+  if (!registration.settings.enabled) parts.push(`"${ENABLED_KEY}" += "${SERVER_NAME}"`);
+  if (registration.settings.allowMissing.length > 0) parts.push(`allow += ${registration.settings.allowMissing.join(', ')}`);
+  return `  - ${SETTINGS_REL}: ${dryRun ? 'would set' : 'set'} ${parts.join(' · ')}`;
+};
+
+// The hand-apply text. The two halves are worded differently because the kit KNOWS different things
+// about them: the settings body is a real merge over content it read, while the `.mcp.json` half is
+// the entry ALONE — behind the mask this mode cannot see what that file already declares, and a
+// whole-file body pasted as instructed would delete every server it could not see.
+const maskedReport = (result) => {
+  const target = result.registration.mcpJson;
+  return [
+    // The CLASS is what was observed; the sandbox mask is the usual CAUSE but is not established here.
+    `agent-workflow MCP registration — HAND-APPLY: ${MCP_JSON_REL} is a ${target.className} (an OS sandbox device mask is the usual cause), so nothing was written.`,
+    `  merge this entry into ${MCP_JSON_REL} under "${SERVERS_KEY}", and keep every other server it already declares (this mode cannot read them through the mask):`,
+    indented(`"${SERVER_NAME}": ${result.fragments.mcpEntry.trimEnd()}`),
+    `  merge into ${SETTINGS_REL} (that file was observable — and read where present — so this body already carries what is in it):`,
+    indented(result.fragments.settings),
+    POSTURE_LINE,
+  ].join(LF);
+};
+
+export const formatResult = (result) => {
+  if (result.masked) return maskedReport(result);
+  const nothingToDo = !result.plan.writeMcpJson && !result.plan.writeSettings;
+  if (nothingToDo) {
+    return [`agent-workflow MCP registration — already registered ("${SERVER_NAME}"); nothing to do.`, POSTURE_LINE].join(LF);
+  }
+  const lines = [
+    result.dryRun
+      ? 'agent-workflow MCP registration — DRY RUN (no changes; re-run with --apply)'
+      : 'agent-workflow MCP registration — APPLY',
+    mcpJsonLine(result),
+    settingsLine(result),
+    '  the entry this registration declares (re-serialized here; the same structured value goes into the file):',
+    indented(JSON.stringify(result.registration.entry, null, JSON_INDENT)),
+    POSTURE_LINE,
+  ];
+  if (result.dryRun) lines.push(`  to apply: ${applyMcpCommand(result.root)}`);
+  return lines.join(LF);
+};
+
+// ── CLI ────────────────────────────────────────────────────────────────────────────────
+
+export const parseArgs = (argv) => {
+  const opts = { dryRunFlag: false, apply: false, cwd: undefined, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--dry-run') opts.dryRunFlag = true;
+    else if (arg === '--apply') opts.apply = true;
+    else if (arg === '--cwd') {
+      i += 1;
+      // An EMPTY (or whitespace) value passes both guards above, and `resolve('')` silently means the
+      // process cwd — so an explicit target of "" would write the registration wherever the tool
+      // happened to run. An explicit argument that names nothing is a usage error, never a default.
+      if (argv[i] === undefined || argv[i].startsWith('-') || argv[i].trim() === '') {
+        throw fail(EXIT_USAGE, '--cwd needs a directory argument');
+      }
+      opts.cwd = argv[i];
+    } else {
+      throw fail(EXIT_USAGE, `unknown argument: ${arg}`);
+    }
+  }
+  if (opts.dryRunFlag && opts.apply) throw fail(EXIT_USAGE, '--dry-run and --apply cannot be used together');
+  return { help: opts.help, dryRun: !opts.apply, cwd: opts.cwd };
+};
+
+export const main = (argv = process.argv.slice(2), deps = {}) => {
+  const log = deps.log ?? console.log;
+  const errlog = deps.errlog ?? console.error;
+  try {
+    const args = parseArgs(argv);
+    if (args.help) {
+      log(USAGE);
+      return EXIT_OK;
+    }
+    log(formatResult(writeMcp({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), dryRun: args.dryRun }, deps)));
+    return EXIT_OK;
+  } catch (err) {
+    errlog(err?.message ?? String(err));
+    if (err?.exitCode === EXIT_USAGE) errlog(USAGE);
+    return err?.exitCode ?? EXIT_PRECONDITION;
+  }
+};
+
+if (isDirectRun(import.meta.url)) process.exit(main(process.argv.slice(2)));

package/tools/procedures.mjs

@@ -208,8 +208,8 @@ const backendSetLabel = (backends) =>
       : ` → ${backends[0]}`;
 
 // The review-loop economics block (M1 + M6's firing half) — printed when the activity engages a review
-// backend (a slot resolving reviewed | council) and OMITTED for solo. It paraphrases the §9 +
-// orchestration §4 canon (no rival rule): the ≤2-round architecture cap, the bar met by RAISING a
+// backend (a slot resolving reviewed | council) and OMITTED for solo. It paraphrases the procedures.md
+// Fold + loop step + orchestration §4 canon (no rival rule): the ≤2-round architecture cap, the bar met by RAISING a
 // surviving major to an acceptance invariant (not exhausting prose), backend divergence = the crossover
 // stop, the thin-plan/diff-review carve-out, a self-consistency read before every re-review, and the
 // REQUIRED per-round structured emission {round N · finding-origin tally · per-backend verdict}. Only a
@@ -221,7 +221,7 @@ const REVIEW_RECIPES = new Set(['reviewed', 'council']);
 const reviewLoopAdvice = (slots, activity) =>
   slots.some((s) => REVIEW_RECIPES.has(s.recipe))
     ? [
-        'Review-loop economics (planning.md §9 · orchestration.md §4) — the review this recipe runs:',
+        'Review-loop economics (procedures.md Fold + loop · orchestration.md §4) — the review this recipe runs:',
         '  • Cap architecture plan-review at ≤2 rounds; the bar is met by RAISING a surviving major to an acceptance invariant (or handing it to Execute/diff-review), never by exhausting the strictest backend.',
         '  • Backend divergence (one backend grounded-ships while another keeps revising mechanics) IS the crossover stop.',
         '  • Route an all-mechanics/CI or prose-only artifact to a thin plan + diff-review; run a self-consistency read before every re-review.',
@@ -299,7 +299,7 @@ const autonomyAdvice = (activity, facts) => {
 };
 
 // The cost-lane advisory block (cost-tiered execution — orchestration.md §5 canon, paraphrased
-// at the point of use like reviewLoopAdvice paraphrases §9/§4). Rendered UNCONDITIONALLY for
+// at the point of use like reviewLoopAdvice paraphrases procedures.md Fold + loop / orchestration §4). Rendered UNCONDITIONALLY for
 // every activity — the lanes route EVERY step, review-backed or not (unlike reviewLoopAdvice,
 // which fires only when a review backend engages). It may name the kit's own GENERIC L0
 // surfaces (the gate runner, the rotation checks, the cheap-agents vehicles) — point-of-use
@@ -368,9 +368,9 @@ const flowHalvesAdvice = (flow, probe) => {
 };
 
 // ── the declared source-size practice (D-17 U1) ────────────────────────────────────
-// A practice the agent meets only when a gate refuses is a practice learned too late: the caps, their
-// reason and the plan-time rung ride EVERY named-activity render, so the layout is cut to them while
-// the plan is being written. Composed from the project's live declaration, never from constants here.
+// A practice the agent meets only when a gate refuses is a practice learned too late: the caps and
+// their reason ride EVERY named-activity render, so the plan's Module ledger is cut to them while the
+// plan is being written. Composed from the project's live declaration, never from constants here.
 // Each config state speaks as itself: ABSENT renders NOTHING (a project that declares no practice must
 // not be handed invented limits); AUTHORED and INCOMPLETE render the declared caps plus the honest
 // "nothing is recorded yet" line — both are pre-mint states, and treating INCOMPLETE as MINTED would
@@ -406,7 +406,6 @@ const declaredPracticeAdvice = (cwd, readFile, lstat) => {
       ? `  recorded: ${facts.recordedFiles} file(s) carry a recorded size (debt, not permission) · aggregate ${facts.aggregateLines} line(s), EXACT — growth takes a reasoned bump, never free headroom.`
       : unmintedRecord,
     `  why: ${SOURCE_SIZE_WHY}`,
-    '  at plan time: every Step that CREATES a file names the file and its single responsibility, and the planned layout fits these caps — the gate is the backstop, never the teacher.',
   ];
 };