@sabaiway/agent-workflow-kit 6.0.0 → 7.1.0

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

@@ -31,6 +31,9 @@ import { resolveEngineDir, readEngineFragment, PROCEDURES_FRAGMENT_REL } from '.
 // The plan-in-flight detector (AD-038) — imported from the plan-files.mjs LEAF (read-only fs by
 // construction); the WRITER-capable grounding.mjs is only NAMED in rendered text, never imported.
 import { plansInFlight, PLANS_REL } from './plan-files.mjs';
+// The family's ONE shell quoter for a RENDERED command operand (bare when the value is already safe,
+// single-quoted otherwise) — the same leaf eight other command renderers here read through.
+import { shellQuoteArg } from './repo-lex.mjs';
 // The config schema/read core lives in orchestration-config.mjs (the single config contract). procedures
 // is READ-ONLY: it imports the reader + the SHARED slot/recipe validity, never the fs-writer
 // (orchestration-write.mjs) DIRECTLY — the import-split test pins the direct-import rule.
@@ -298,6 +301,24 @@ const autonomyAdvice = (activity, facts) => {
   ];
 };
 
+// The finding-scope block (procedures.md plan-execution step 5) — plan-execution ONLY and
+// UNCONDITIONAL: the rule routes EVERY finding, review-backed or not, so gating it on REVIEW_RECIPES
+// (which gates only the loop economics above) would hide it from every Solo project. The canon
+// section is printed VERBATIM above, so this block never re-states the rule — it carries only what
+// the canon cannot: the POPULATED checker command, and which of the two registers `--queue` names.
+export const FOLD_SCOPE_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'fold-scope-cli.mjs');
+const foldScopeAdvice = (activity, config, plans) => {
+  if (activity !== 'plan-execution') return [];
+  const declared = config?.flow?.debtQueue ?? null;
+  const queue = declared ?? `${PLANS_REL}/queue.md`;
+  const plan = plans.length === 1 ? `${PLANS_REL}/${plans[0]}` : '<plan-file>';
+  return [
+    'Finding scope (procedures.md plan-execution step 5) — the rule is the section above; this is the checker it names:',
+    `  • node ${shellQuoteArg(FOLD_SCOPE_TOOL)} --class '<in-scope|new-invariant|blocking>' --claim '<the invariant>' --plan ${shellQuoteArg(plan)} --queue ${shellQuoteArg(queue)}`,
+    `  • --queue is ${declared ? `${declared}, the declared flow.debtQueue` : `${queue}, the planning lifecycle queue (no flow.debtQueue is declared)`}. Advisory: nothing records that it ran, so a skipped or late call is indistinguishable from a pre-edit declaration.`,
+  ];
+};
+
 // The cost-lane advisory block (cost-tiered execution — orchestration.md §5 canon, paraphrased
 // 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,
@@ -445,7 +466,7 @@ const contractLines = ({ cmd, contract, settings }) => {
   return lines;
 };
 
-const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice }) => {
+const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope }) => {
   const lines = [
     section,
     '',
@@ -464,6 +485,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   if (grounding.length) lines.push('', ...grounding);
   const advice = reviewLoopAdvice(slots, activity);
   if (advice.length) lines.push('', ...advice);
+  if (foldScope.length) lines.push('', ...foldScope);
   lines.push('', ...costLanesAdvice());
   if (declaredPractice.length) lines.push('', ...declaredPractice);
   if (warnings.length) {
@@ -473,7 +495,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   return lines.join('\n');
 };
 
-const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice }) => ({
+const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope }) => ({
   activity,
   section,
   slots: Object.fromEntries(
@@ -486,6 +508,8 @@ const buildJson = ({ activity, section, slots, configSource, warnings, plans, au
   groundingPreStep: groundingPreStepAdvice(activity, slots, plans),
   // ADDITIVE (cost-tiered execution): the unconditional cost-lane advisory, structured.
   costLanes: costLanesAdvice(),
+  // ADDITIVE (the fold channel): the finding-scope block, structured (empty outside plan-execution).
+  foldScope,
   // ADDITIVE (AD-044 Plan 4): the per-activity autonomy block, structured (empty when unresolvable).
   autonomy: autonomyAdvice(activity, autonomy),
   // ADDITIVE (D-17 U1): the SAME composed lines the human render prints — one array, two renders, so
@@ -574,9 +598,10 @@ export const main = (argv, ctx = {}) => {
     const flowProbe = ctx.flowProbe ?? defaultFlowProbe;
     const flowHalves = config?.flow == null ? null : flowHalvesAdvice(config.flow, flowProbe(cwd));
     const declaredPractice = declaredPracticeAdvice(cwd, readFile, lstat);
+    const foldScope = foldScopeAdvice(activity, config, plans);
     const stdout = json
-      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice }), null, 2)
-      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice });
+      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope }), null, 2)
+      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope });
     if (autonomy?.error) {
       return { code: 1, stdout, stderr: `procedures: malformed ${AUTONOMY_REL} — ${autonomy.error}` };
     }

package/tools/recommendations.mjs

@@ -59,6 +59,13 @@ import { shellQuoteArg } from './review-state.mjs';
 import { isFinalCapableDeclaration } from './run-gates.mjs';
 import { loadDeclaration, canonicalCheckerGates, coverageProducerPrecedes, isKitOwnedCheckerGate, GATES_REL, LCOV_PRODUCER_KEY } from './gates-declaration.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+// The typed channel's READ-ONLY leaf only — never tools/mcp.mjs, which reaches the write core.
+import {
+  MCP_JSON_REL,
+  SERVER_NAME as MCP_SERVER_NAME,
+  STATE as MCP_STATE,
+  readRegistration,
+} from './mcp-registration.mjs';
 import { matchesCoverageProducer, isCoverageProducerGate } from './coverage-producer.mjs';
 // How much of the TRACKED tree the changed-line coverage domain can assess at all — the fact that
 // turns "the checker certifies" into "the checker certifies the assessable minority".
@@ -143,6 +150,13 @@ export const SEVERITIES = Object.freeze({
   'read-lane.stale': SEVERITY_ATTENTION,
   'read-lane.missing': SEVERITY_ATTENTION,
   'state-block': SEVERITY_OPTIONAL,
+  // The typed channel. The base arm is an ordinary offer; `.masked` stays an offer too (nothing is
+  // broken — the kit simply cannot write through a device node, so the remedy is handed over);
+  // `.differing` reports a CONFIGURED declaration that would launch something else, which is the
+  // one state here a maintainer must actually look at.
+  'mcp-channel': SEVERITY_OPTIONAL,
+  'mcp-channel.masked': SEVERITY_OPTIONAL,
+  'mcp-channel.differing': SEVERITY_ATTENTION,
   agents: SEVERITY_OPTIONAL,
   'family-freshness': SEVERITY_ATTENTION,
   'adr-store-migration': SEVERITY_ATTENTION,
@@ -210,6 +224,9 @@ export const WHATS = Object.freeze({
   'read-lane.stale': 'the read-lane is ON but the placed gate hook is stale — an old hook never reads lanes.json, so the lane is silently dark; reseed it',
   'read-lane.missing': 'the gate hook is wired but its placed file is missing — every Bash call errors and the read-lane is dark; re-place it',
   'state-block': 'nothing checks the closing state block — a turn that ends on «nothing needed from you», or on a promise it never started, passes unseen',
+  'mcp-channel': "the kit's read-only MCP server is not registered here — path questions and literal searches stay shell strings",
+  'mcp-channel.masked': '{rel} is a {className} here (a sandbox device mask is the usual cause), so the entry to merge is printed instead',
+  'mcp-channel.differing': 'an "{server}" MCP entry is already declared here and DIFFERS from the registration this kit copy would write',
   agents: '{n} read-only subagent(s) not placed (Claude Code) — no shell-free vehicle for that work; the apply PREVIEWS first',
   'family-freshness': '{parts}',
   'adr-store-migration': 'still on the retired 3-tier ADR layout — {shape}',
@@ -266,6 +283,7 @@ export const BENEFITS = Object.freeze({
   'commit-guard': 'integrity — commits require the ONE green --final receipt at the exact staged fingerprint (consented pre-commit arm)',
   'read-lane': 'velocity — pipes/chains of your seeded read-only commands auto-approve instead of prompting (opt-in, conservatively classified)',
   'state-block': 'no silent stalls — a turn ending on «you are not needed», or on work it never started, warns at once instead of waiting to be spotted',
+  'mcp-channel': 'velocity — path facts and literal searches arrive as typed tool calls whose arguments are JSON fields, never a shell string',
   agents: 'cost and quiet — mechanical work runs on a cheap model, and no vehicle has a shell, so a read-only fan-out cannot flood you with prompts',
   'family-freshness': 'currency — placed family members carry the latest shipped fixes and features',
   'adr-store-migration': 'durability — every decision becomes its own file with a generated navigator, instead of one hand-rotated pile',
@@ -311,6 +329,7 @@ export const OPT_IN_CAPABILITIES = Object.freeze([
   { id: 'commit-guard', mode: 'commit-guard', advisorKey: 'commit-guard' },
   { id: 'state-block', mode: 'state-block-guard', advisorKey: 'state-block' },
   { id: 'sandbox-masks', mode: 'sandbox-masks', advisorKey: 'sandbox-masks' },
+  { id: 'mcp-channel', mode: 'mcp', advisorKey: 'mcp-channel' },
   { id: 'worktrees-dir', mode: 'worktrees', advisorKey: 'worktrees-dir' },
   { id: 'family-freshness', mode: 'upgrade', advisorKey: 'family-freshness' },
   { id: 'adr-store-migration', mode: 'migrate-adr-store', advisorKey: 'adr-store-migration' },
@@ -1189,7 +1208,7 @@ const readReadLaneToggle = (root, deps) => {
 // D3: the risk-marked keys — every key here has a per-item posture note in the mode doc, surfaced
 // at the consent moment; the static contract test asserts EXACT bidirectional coverage
 // (risk-marked keys == mode-doc note keys — a dropped note goes red, not silent).
-export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook']);
+export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel']);
 
 const probeSandboxLane = ({ root, deps, add, skip }) => {
   try {
@@ -1384,6 +1403,75 @@ export const probeAdrStore = ({ root, deps, add, skip }) => {
   }
 };
 
+// The typed-channel item. It asks the READ-ONLY registration leaf and nothing else — importing the
+// writer would pull the atomic-write core into the advisor's graph (read-graph-purity.test.mjs).
+// The rendered apply is the mode's FLAGLESS preview on purpose: registering an MCP server means the
+// client will RUN that command, so the entry is read before it is declared and the `--apply` stays
+// the maintainer's separate step.
+const probeMcpChannel = ({ root, deps, add, skip }) => {
+  try {
+    const registration = readRegistration(root, deps);
+    // A target we could not read is never turned into a verdict about what it contains.
+    const assertReadable = (target) => {
+      if (target.state === MCP_STATE.FOREIGN) throw new Error(`${target.rel} is a ${target.className} — refusing to read through it`);
+      if (target.state === MCP_STATE.MALFORMED) throw new Error(`${target.rel} is ${target.reason}`);
+      if (target.state === MCP_STATE.UNREADABLE) throw new Error(`${target.rel} cannot be read (${target.reason})`);
+    };
+    const preview = `node ${q(toolPath('mcp.mjs'))} --cwd ${q(root)}`;
+    // ORDER: the `.mcp.json` half is judged and REPORTED on its own before anything about the
+    // settings half can end the probe. A differing entry is fully observable, and an unreadable
+    // settings file says nothing about it — returning on the settings mask first hid it.
+    assertReadable(registration.mcpJson);
+    const settingsUsable = registration.settings.state !== MCP_STATE.MASKED
+      && registration.settings.state !== MCP_STATE.FOREIGN
+      && registration.settings.state !== MCP_STATE.UNREADABLE
+      && registration.settings.state !== MCP_STATE.MALFORMED;
+    if (registration.mcpJson.differs) {
+      // The remedy is the maintainer's edit either way; the "then run" tail is dropped where that
+      // command could not succeed, so the item never hands over a line that exits 1.
+      const tail = settingsUsable ? `, then run ${preview}` : '';
+      add(
+        'mcp-channel',
+        fillTemplate(WHATS['mcp-channel.differing'], { server: MCP_SERVER_NAME }),
+        `HAND-APPLY: edit ${q(join(root, MCP_JSON_REL))} → remove or rename the "${MCP_SERVER_NAME}" entry${tail}`,
+        'mcp-channel.differing',
+      );
+      return;
+    }
+    assertReadable(registration.settings);
+    // The HAND-APPLY arm renders the MODE's own preview, so it may fire only where that command can
+    // actually run — and the writer refuses a masked settings.json outright (it can neither write it
+    // nor merge into what it cannot read). A masked settings half is therefore a stated SKIP: the
+    // completeness this item decides on is unknowable, and offering a command that exits 1 is worse
+    // than saying nothing.
+    if (registration.settings.state === MCP_STATE.MASKED) {
+      skip('mcp-channel', new Error(`${registration.settings.rel} is a ${registration.settings.className} here (a sandbox device mask is the usual cause) — the registration cannot be judged or written from in here; verify it outside the sandbox`));
+      return;
+    }
+    if (registration.mcpJson.state === MCP_STATE.MASKED) {
+      // The kit cannot write through the mask either, so the remedy is HAND-APPLY. But when the
+      // settings half is already complete, the registration was almost certainly made from outside
+      // the sandbox: what cannot be observed becomes a stated SKIP (optimality withheld), never the
+      // same offer again on every single upgrade.
+      if (registration.settings.complete) {
+        skip('mcp-channel', new Error(`${registration.mcpJson.rel} is a ${registration.mcpJson.className} here (a sandbox device mask is the usual cause) and the settings half is already complete — verify the entry outside the sandbox`));
+        return;
+      }
+      add(
+        'mcp-channel',
+        fillTemplate(WHATS['mcp-channel.masked'], { rel: registration.mcpJson.rel, className: registration.mcpJson.className }),
+        `HAND-APPLY: ${preview}`,
+        'mcp-channel.masked',
+      );
+      return;
+    }
+    if (registration.registered) return;
+    add('mcp-channel', fillTemplate(WHATS['mcp-channel'], {}), preview);
+  } catch (err) {
+    skip('mcp-channel', err);
+  }
+};
+
 // ── assembly (frozen presentation order) ─────────────────────────────────────────────────────────
 const PROBES = Object.freeze([
   probeVelocityItems,
@@ -1402,6 +1490,7 @@ const PROBES = Object.freeze([
   probeMasksItem,
   probeSandboxLane,
   probeWorktreesDir,
+  probeMcpChannel,
 ]);
 
 export const buildRecommendations = ({ cwd, deps = {} } = {}) => {