@sabaiway/agent-workflow-kit 6.0.0 → 7.1.0

package/tools/fold-scope.mjs

@@ -0,0 +1,307 @@
+// The finding-scope rule as a checker — the half prose cannot do (the engine canon: procedures.md,
+// plan-execution step 5). A finding NAMES the invariant its fix enforces BEFORE the edit; WHERE that
+// invariant already lives decides the disposition, and this module REFUSES a claim whose reference
+// does not resolve:
+//
+//   in-scope       the claim matches WITHIN ONE acceptance bullet of the plan -> fold here.
+//   new-invariant  the claim matches NO acceptance bullet AND one OPEN queue row carries the claim in
+//                  its invariant field and all five fields (invariant, origin as file:line, narrow
+//                  fix, proof, residual exposure) with that exposure declared NOT live -> the narrow
+//                  fix ships now, only the generalization defers.
+//   blocking       no correct narrow fix exists -> the phase does not close; there is no queue arm.
+//
+// Markdown is read through the family's ONE block model (references/scripts/markdown-blocks.mjs, the
+// module the archivers already read through): fenced regions, ATX headings at 0-3 columns of indent,
+// CRLF and the backtick-info-string rule are ITS problem, not a second hand-rolled grammar here. A
+// document it refuses is a loud refusal, never a silent empty read.
+//
+// ADVISORY in this slice: nothing records that it ran, so a skipped or late call is
+// indistinguishable from a pre-edit declaration. A fingerprint-bound receipt a gate reads is next.
+//
+// Pure string functions - every input is text; the CLI half (fold-scope-cli.mjs) owns the fs.
+// Dependency-free, Node >= 22.
+
+import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+
+export const CLASSES = ['in-scope', 'new-invariant', 'blocking'];
+export const ROW_FIELDS = ['invariant', 'origin', 'narrow fix', 'proof', 'residual exposure'];
+export const ACCEPTANCE_HEADING = '## Verification';
+// The canon says a deferral row carries "the origin `file:line`". Anchored at the start of the value
+// and a POSITIVE line number, so "file.mjs:12junk" and "file.mjs:0" are not one; trailing context
+// after the token is fine, because the canon asks the row to CARRY a file:line, not to carry nothing
+// else.
+const ORIGIN_SHAPE = /^\S+:[1-9]\d*(\s|$)/;
+// A closed row is not a live deferral. Narrow on purpose: the row TITLE carrying one of these
+// literals refuses fail-closed; the general per-project status grammar is queued, not guessed here.
+const CLOSED_MARKERS = ['DONE', 'CLOSED'];
+const ORIGIN_MISSING = 'origin (the canon requires a file:line)';
+const BULLET = /^-\s+\S/;
+
+const normalize = (s) => String(s ?? '').replace(/\r/g, '').replace(/\s+/g, ' ').trim();
+const contains = (haystack, needle) => normalize(haystack).toLowerCase().includes(needle);
+
+// The ONE bullet scan both readers use, over the block model's lines. A fenced region is a quotation
+// AND a boundary: it closes the block it interrupts, so text past a fence can never join the bullet
+// before it (which would let a far-side literal satisfy a near-side claim). A `-` plus any whitespace
+// run opens a block; a blank or indented line continues it; any other unindented line closes it.
+// Blocks are returned RAW (their own lines) — the queue reader needs the field lines inside them.
+const bulletBlocks = (lines, fencedLines, from, to) => {
+  const blocks = [];
+  let current = null;
+  const close = () => {
+    if (current) blocks.push(current);
+    current = null;
+  };
+  for (let index = from; index < to; index += 1) {
+    if (fencedLines.has(index)) {
+      close();
+      continue;
+    }
+    const line = lines[index];
+    if (BULLET.test(line)) {
+      close();
+      current = [line];
+    } else if (current && (line.trim() === '' || /^\s+\S/.test(line))) {
+      current.push(line);
+    } else {
+      close();
+    }
+  }
+  close();
+  return blocks;
+};
+
+// extractAcceptance(planText) -> the top-level bullets under `## Verification`, each collapsed to one
+// line. Per the planning canon those bullets ARE the acceptance criteria and they are the WHOLE list.
+// ONE heading recognizer decides both ends: the section opens on the block model's `## Verification`
+// heading and closes at the next heading of level 1 or 2, so a level-3 subheading stays INSIDE (which
+// is what "in this section" means) and a 4-space line, being an indented code block rather than a
+// heading, neither opens nor closes it. A Verification with no bullets declares NO criteria.
+export const extractAcceptance = (planText) => {
+  const { lines, headings, fencedLines } = tokenizeMarkdown(String(planText ?? ''), 'the plan');
+  const open = headings.find((heading) => heading.text.trim() === ACCEPTANCE_HEADING);
+  if (!open) return [];
+  const next = headings.find((heading) => heading.index > open.index && heading.level <= 2);
+  return bulletBlocks(lines, fencedLines, open.index + 1, next ? next.index : lines.length)
+    .map((block) => normalize(block.join('\n').replace(/^-\s+/, '')))
+    .filter(Boolean);
+};
+
+// ONE question per pattern: this one asks whether the line CARRIES a label, never whether the value
+// behind it is any good. Requiring a non-empty value here made an empty repeat invisible, so a row
+// could repeat a label and still be admitted; the value is judged downstream, where "" is missing.
+const FIELD_LINE = new RegExp(`^\\s*(?:[-*]\\s+)?(${ROW_FIELDS.map((f) => f.replace(' ', '\\s+')).join('|')})\\s*:\\s*(.*)$`, 'i');
+
+// The labelled fields of one row, folding CONTINUATION lines into the value they belong to (a wrapped
+// invariant read to its first line only would refuse a legitimate deferral). A REPEATED label is
+// recorded and REFUSED, never resolved by keeping the first value: a row saying "not live" and then
+// "live" would otherwise be accepted as not-live, which is the contradiction this fails closed on.
+const parseFields = (block) => {
+  const values = {};
+  let open = null;
+  for (const line of block.split('\n')) {
+    const match = line.match(FIELD_LINE);
+    if (match) {
+      open = match[1].toLowerCase().replace(/\s+/g, ' ');
+      values[open] = [...(values[open] ?? []), match[2].trim()];
+    } else if (open && /^\s+\S/.test(line) && !BULLET.test(line.trim())) {
+      values[open][values[open].length - 1] += ` ${line.trim()}`;
+    } else {
+      open = null;
+    }
+  }
+  const fields = {};
+  for (const label of ROW_FIELDS) fields[label] = values[label]?.[0] ?? null;
+  return { fields, values, duplicates: ROW_FIELDS.filter((label) => (values[label] ?? []).length > 1) };
+};
+
+// The disposition a residual exposure declares. Exactly TWO forms declare the negative: "not live"
+// and "not-live", each a standalone token on both sides — so "not--live", "not - live",
+// "not-live-ish" and "maybe-not-live" declare nothing. EVERY not-live span is removed before the
+// positive is looked for, malformed ones included: the `live` inside a botched negative is not a
+// declaration of the positive, and reading it as one would route the author to blocking over a row
+// that only needs re-wording. A standalone bare `live` then decides, and a row carrying both a
+// declared negative and a real positive is a contradiction that fails closed as live.
+const NEGATIVE_SPAN = /(?<![-\w])not[\s-]*live(?![-\w])/g;
+const DECLARED_NEGATIVE = /(?<![-\w])not(?:\s+|-)live(?![-\w])/;
+const LIVE_TOKEN = /(?<![-\w])live(?![-\w])/;
+const exposureOf = (value) => {
+  const text = String(value ?? '').toLowerCase();
+  const declaredNegative = DECLARED_NEGATIVE.test(text);
+  if (LIVE_TOKEN.test(text.replace(NEGATIVE_SPAN, ' '))) return 'live';
+  return declaredNegative ? 'not-live' : null;
+};
+
+const topLevelRows = (queueText) => {
+  const { lines, fencedLines } = tokenizeMarkdown(String(queueText ?? ''), 'the queue');
+  return bulletBlocks(lines, fencedLines, 0, lines.length).map((block) => block.join('\n'));
+};
+
+const EMPTY_ROW = () => ({ found: false, matches: 0, fields: {}, missing: [...ROW_FIELDS], duplicates: [], exposure: null, closed: null, claimInInvariant: false });
+
+// findDebtRow(queueText, claim) -> the ONE queue row FOR this invariant, its fields and its
+// disposition. Discovery prefers the row whose INVARIANT field carries the claim; the whole-block
+// match is only the fallback, and it exists so a row that carries the claim but no invariant field is
+// still FOUND and its missing field can be named. Zero and several matches are both "not found" with
+// the count: a deferral names ONE row, and guessing which is the unresolved reference this refuses.
+export const findDebtRow = (queueText, claim) => {
+  const needle = normalize(claim).toLowerCase();
+  if (!needle) return EMPTY_ROW();
+  const rows = topLevelRows(queueText).map((block) => ({ block, ...parseFields(block) }));
+  // EVERY recorded value of `invariant` is a candidate key, not just the first: a claim sitting in a
+  // repeated label would otherwise be invisible here and resolve to some OTHER row.
+  const owns = (r) => (r.values.invariant ?? []).some((v) => contains(v, needle));
+  const byInvariant = rows.filter(owns);
+  const hits = byInvariant.length ? byInvariant : rows.filter((r) => contains(r.block, needle));
+  // A candidate that repeats a label cannot be reasoned about at all, so the refusal comes BEFORE the
+  // row is resolved — ahead of the ambiguity count and ahead of every field judgement.
+  const broken = [...new Set(hits.flatMap((r) => r.duplicates))];
+  if (broken.length) return { ...EMPTY_ROW(), matches: hits.length, duplicates: broken };
+  if (hits.length !== 1) return { ...EMPTY_ROW(), matches: hits.length };
+  const { block, fields, duplicates } = hits[0];
+  const missing = ROW_FIELDS.filter((label) => !fields[label]);
+  if (fields.origin && !ORIGIN_SHAPE.test(fields.origin)) missing.push(ORIGIN_MISSING);
+  return {
+    found: true,
+    matches: 1,
+    block,
+    fields,
+    missing,
+    duplicates,
+    exposure: exposureOf(fields['residual exposure']),
+    closed: CLOSED_MARKERS.find((marker) => block.split('\n')[0].includes(marker)) ?? null,
+    claimInInvariant: owns(hits[0]),
+  };
+};
+
+const verdict = (kind, code, exit, claim, lines) => ({
+  verdict: kind,
+  code,
+  exit,
+  lines: [`fold-scope: ${kind} ${code}${claim ? ` — "${claim}"` : ''}`, ...lines],
+});
+const accept = (code, claim, lines) => verdict('ACCEPT', code, 0, claim, lines);
+const refuse = (code, claim, lines, exit = 1) => verdict('REFUSE', code, exit, claim, lines);
+
+const FIVE_FIELDS = ROW_FIELDS.join(', ');
+
+// A document read is the ONE place a throw is expected: the block model REFUSES an unclosed fence and
+// an ambiguous leading `---` rather than guessing, and its message names the file and line.
+const read = (fn) => {
+  try {
+    return { value: fn() };
+  } catch (err) {
+    return { error: (err && err.message) || String(err) };
+  }
+};
+const unreadable = (claim, message) => refuse('document-unreadable', claim, [
+  `  ${message}`,
+  '  a document that cannot be read as markdown is never guessed around — fix it, then re-run.',
+], 2);
+
+// decideFoldScope({ cls, claim, planText, queueText }) -> { verdict, code, exit, lines }.
+// Exit 0 for every ACCEPT, 1 for every matrix REFUSE, 2 for a refusal about the ARGUMENTS themselves
+// (an unknown or absent class, an absent claim, an unreadable document) - the CLI prints the lines
+// and returns the code.
+export const decideFoldScope = ({ cls, claim, planText, queueText } = {}) => {
+  const claimText = normalize(claim);
+  if (!CLASSES.includes(cls)) {
+    return refuse('class-unknown', typeof cls === 'string' ? cls : '', [
+      `  --class must be one of: ${CLASSES.join(', ')} — there is no default arm.`,
+      '  name the invariant the fix would enforce, then say where it already lives.',
+    ], 2);
+  }
+  if (!claimText) {
+    return refuse('claim-absent', '', [
+      '  --claim carries the invariant the fix would enforce, as a literal.',
+      '  a finding with no named invariant has no scope to decide.',
+    ], 2);
+  }
+  if (cls === 'blocking') {
+    return accept('blocking', claimText, [
+      '  no correct narrow fix exists, so the phase does not close.',
+      '  there is no deferral arm here: fix it in this phase, or the phase stays open.',
+    ]);
+  }
+  const criteria = read(() => extractAcceptance(planText));
+  if (criteria.error) return unreadable(claimText, criteria.error);
+  const acceptance = criteria.value;
+  const needle = claimText.toLowerCase();
+  const matched = acceptance.find((bullet) => contains(bullet, needle)) ?? null;
+  if (cls === 'in-scope') {
+    return matched
+      ? accept('in-scope', claimText, [
+          `  matched acceptance bullet: ${matched}`,
+          '  fold here: the invariant is already required by this plan. Fold the finding as a red->green test and re-review.',
+        ])
+      : refuse('in-scope-unmatched', claimText, [
+          `  no acceptance bullet of the plan carries this literal (${acceptance.length} bullet(s) read).`,
+          '  the lane: ship the NARROW fix for the found site (red first, then green); the generalization defers only as',
+          `  --class new-invariant, once a queue row carries ${FIVE_FIELDS}. With no correct narrow fix, --class blocking.`,
+        ]);
+  }
+  if (matched) {
+    return refuse('new-invariant-already-accepted', claimText, [
+      `  the invariant IS an acceptance bullet: ${matched}`,
+      '  route to the fold arm: --class in-scope. Already-required work is never a deferral.',
+    ]);
+  }
+  const found = read(() => findDebtRow(queueText, claimText));
+  if (found.error) return unreadable(claimText, found.error);
+  const row = found.value;
+  if (row.duplicates.length) {
+    return refuse('new-invariant-row-duplicate-field', claimText, [
+      `  a candidate queue row declares more than once: ${row.duplicates.join(', ')}.`,
+      '  a repeated label is not resolved by keeping the first value — a row that says both "not live"',
+      '  and "live" declares a contradiction, and a claim hidden in a repeat would resolve to another row.',
+      '  Delete the duplicate so the row states ONE value per field.',
+    ]);
+  }
+  if (row.matches > 1) {
+    return refuse('new-invariant-row-ambiguous', claimText, [
+      `  ${row.matches} queue rows carry this literal — a deferral names ONE row.`,
+      '  narrow the claim to the invariant statement of the row you mean.',
+    ]);
+  }
+  if (!row.found) {
+    return refuse('new-invariant-row-absent', claimText, [
+      '  no queue row carries this literal.',
+      `  a deferral owes a row carrying all five fields: ${FIVE_FIELDS}, that exposure declared NOT live.`,
+      '  if the exposure IS live, this is not a deferral at all — it is --class blocking.',
+    ]);
+  }
+  if (row.closed) {
+    return refuse('new-invariant-row-closed', claimText, [
+      `  the queue row title carries "${row.closed}" — a closed row is not a live deferral.`,
+      '  re-open that row, or write a new one for the invariant this finding names.',
+    ]);
+  }
+  if (row.missing.length) {
+    return refuse('new-invariant-row-incomplete', claimText, [
+      `  the queue row is missing: ${row.missing.join(', ')}.`,
+      '  a row short of a field is a note, not a deferral — write the field, then re-run.',
+    ]);
+  }
+  if (!row.claimInInvariant) {
+    return refuse('new-invariant-claim-not-invariant', claimText, [
+      `  the row carries this literal, but NOT in its invariant field: ${row.fields.invariant}`,
+      '  a deferral is keyed on the invariant the row states — quote that, or write the row this finding needs.',
+    ]);
+  }
+  if (row.exposure === 'live') {
+    return refuse('new-invariant-exposure-live', claimText, [
+      `  the residual exposure is declared LIVE: ${row.fields['residual exposure']}`,
+      '  a live defect in shipped behaviour is never deferred — route to --class blocking.',
+    ]);
+  }
+  if (row.exposure === null) {
+    return refuse('new-invariant-exposure-undeclared', claimText, [
+      `  the residual exposure declares neither "live" nor "not live": ${row.fields['residual exposure']}`,
+      '  silence is not a declaration — state the disposition in the row.',
+    ]);
+  }
+  return accept('new-invariant', claimText, [
+    `  the queue row carries all five fields and declares its residual exposure NOT live: ${row.fields.origin}`,
+    '  the narrow fix ships in this phase; ONLY the generalization defers.',
+  ]);
+};

package/tools/mcp-registration.mjs

@@ -0,0 +1,283 @@
+// mcp-registration.mjs — the READ-ONLY half of the `mcp` mode: is the kit's stdio MCP server
+// registered in THIS project? It answers for two consumers that must never reach a writer — the
+// `mcp-channel` advisor item and `uninstall`'s report — and the writer (mcp.mjs) composes its bodies
+// from the same merges, so "what is there" and "what would be written" can never drift apart.
+//
+// Split out for the reason bridge-settings-read.mjs was (bridges 2.3.0, D6): a read-only consumer
+// that imports the writer pulls in the atomic-write core, which read-graph-purity.test.mjs forbids.
+// That is also why the two settings-path literals are NOT imported from velocity-profile.mjs (a
+// write module) — the equality is pinned by a test instead.
+//
+// It reads through fs-read-nofollow.mjs rather than velocity's readSettingsFile because that reader
+// follows a symlink: a symlinked `.mcp.json` whose TARGET is a perfect registration would report
+// registered over a file the writer must refuse to touch. Every never-committable dirent class
+// (the sandbox's own device masks, a FIFO, a socket) is a NAMED state, classified by lstat BEFORE
+// any open. Nothing here throws: every failure is a state with its own reason.
+//
+// RESIDUAL, stated as a BOUNDARY. What this module closes is the STATIC case: a symlink, device,
+// FIFO or socket ALREADY at a path is classified, named, and never read — a target decided FOREIGN
+// is never opened. (A target decided REGULAR is of course opened; that is the read.)
+//
+// Against a path that CHANGES under it, this module promises nothing, and the two races are NOT the
+// same shape:
+//   • the LEAF is protected by the shared reader as far as a path-based reader can go — it opens
+//     `O_NOFOLLOW`, fstats the DESCRIPTOR and reads through it, so a swapped SYMLINK cannot be
+//     followed. What it cannot catch is substitution by another REGULAR FILE, which needs the open
+//     bound to an earlier inode observation — inside fs-read-nofollow.mjs, which four consumers
+//     share, so that is the leaf's decision rather than this one's.
+//   • the CONTAINER cannot be closed that way at all: no property of the leaf's descriptor says
+//     anything about the directory the path was resolved through. That needs directory-relative
+//     opening (`openat`), which Node does not expose — so it is a platform limit, not a missing check.
+// Classifying `.claude` before reading inside it closes the STATIC symlinked container — the real and
+// reachable case, where a settings file outside the work tree became a verdict; a container swapped
+// mid-flight is not closed, for the reason above. Earlier drafts of this comment enumerated windows
+// and were corrected three rounds running, each time for being one window too generous. The bar this
+// module meets: no STATIC foreign path is followed or read, and no target decided FOREIGN is opened.
+//
+// Dependency-free, Node >= 22. No writes, no CLI, no side effects on import.
+
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describeNonRegular, lstatNoFollowRead, readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { refuseDirectRun } from './direct-run.mjs';
+import { SERVER_NAME, TOOLS } from './mcp-server.mjs';
+
+export { SERVER_NAME };
+
+export const MCP_JSON_REL = '.mcp.json';
+export const CLAUDE_DIR_REL = '.claude';
+export const SETTINGS_REL = '.claude/settings.json';
+export const SERVERS_KEY = 'mcpServers';
+export const ENABLED_KEY = 'enabledMcpjsonServers';
+// OUT OF SCOPE, deliberately and by name: `disabledMcpjsonServers`. A server listed there is rejected
+// by the client in every mode, so a project can hold our entry, the enable and both rules and still
+// have a dark channel — this mode does NOT detect that, and `registered` therefore means "the three
+// things this mode writes are in place", never "the client will load it".
+//
+// It was implemented during review and then SUBTRACTED. The reason is worth keeping: honouring a veto
+// means reading it from every scope the client merges, and each scope has its own masked, symlinked,
+// malformed and unreadable states — in each of which a hidden deny still yields a confident answer.
+// Three review rounds each closed one such hole and opened the next. A check that is wrong in states
+// it cannot enumerate is worse than a stated limit, so this is the stated limit.
+// The RUNNING kit copy's own server — the args entry a registration must carry to reach THIS kit.
+export const DEFAULT_SERVER_PATH = fileURLToPath(new URL('./mcp-server.mjs', import.meta.url));
+
+export const STATE = Object.freeze({
+  ABSENT: 'absent',
+  MASKED: 'masked',
+  FOREIGN: 'foreign',
+  UNREADABLE: 'unreadable',
+  MALFORMED: 'malformed',
+  PRESENT: 'present',
+});
+
+const LF = '\n';
+const CRLF = '\r\n';
+const JSON_INDENT = 2;
+
+// The two allow rules a client needs, derived from the server's own name + tool list — never a
+// re-typed pair (a renamed tool would otherwise ship a rule nothing grants).
+export const allowRulesFor = (tools = TOOLS) => tools.map((tool) => `mcp__${SERVER_NAME}__${tool.name}`);
+
+export const buildServerEntry = (serverPath) => ({ type: 'stdio', command: 'node', args: [serverPath] });
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// Key-order-independent structural identity: an entry that differs only in key order is the SAME
+// registration, while an extra key, a different command or a different arg is a real difference.
+const stable = (value) => {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'undefined';
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stable(value[k])}`).join(',')}}`;
+};
+
+// The never-committable stat classes (core-evidence's own review-domain rule, re-decided here rather
+// than imported: core-evidence reaches the atomic-write core and this module may not).
+const isMaskStat = (st) => st.isCharacterDevice() || st.isBlockDevice() || st.isFIFO() || st.isSocket();
+
+// lstat FIRST, then read: the classification decides whether an open may happen at all, so a FIFO is
+// never opened and a symlink is never followed.
+const readTarget = (abs, io) => {
+  let st;
+  try {
+    st = lstatNoFollowRead(abs, io.lstat);
+  } catch (err) {
+    return { state: STATE.UNREADABLE, reason: (err && (err.code || err.message)) || 'lstat failed' };
+  }
+  if (st === null) return { state: STATE.ABSENT };
+  if (isMaskStat(st)) return { state: STATE.MASKED, className: describeNonRegular(st) };
+  if (!st.isFile()) return { state: STATE.FOREIGN, className: describeNonRegular(st) };
+  const r = readRegularFileNoFollow(abs, io);
+  if (r.outcome === 'absent') return { state: STATE.ABSENT };
+  if (r.outcome === 'foreign') return { state: STATE.FOREIGN, className: r.className };
+  if (r.outcome !== 'ok') return { state: STATE.UNREADABLE, reason: r.code };
+  return { state: STATE.PRESENT, text: r.content };
+};
+
+const eolOf = (text) => (text.includes(CRLF) ? CRLF : LF);
+
+// A file we cannot parse is MALFORMED with its own reason — never an empty object, which would let a
+// writer clobber a file it never understood.
+const parseJsonText = (text) => {
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch (err) {
+    return { state: STATE.MALFORMED, reason: `not valid JSON (${(err && err.message) || 'parse failed'})` };
+  }
+  if (!isPlainObject(data)) return { state: STATE.MALFORMED, reason: 'the root is not a JSON object' };
+  return { state: STATE.PRESENT, data };
+};
+
+// A MANAGED key of the wrong type is MALFORMED, not "empty". Reading it as an empty container and
+// merging over it DESTROYS whatever it held — the merge-through-clobber `gate-hook.mjs`
+// (assertHooksShape) already refuses for its own `hooks` key. Only the four keys this mode writes are
+// judged; a foreign key of any shape is data, carried over untouched and never inspected.
+const wrongType = (key, expected) => `carrying a "${key}" key that is not ${expected}`;
+
+const NEUTRAL_ENTRY = { hasEntry: false, existing: null, matches: false, differs: false };
+
+// The two decisions over TEXT. Exported because a consumer that already holds the bytes — the
+// uninstaller, which reads every surface through its own injected fs — must answer "is this OUR
+// registration?" by the SAME rule the reader uses, not by a second copy of it.
+export const decideMcpJsonText = (text, entry) => {
+  const parsed = parseJsonText(text);
+  const eol = eolOf(text);
+  if (parsed.state !== STATE.PRESENT) return { ...parsed, eol, ...NEUTRAL_ENTRY };
+  const servers = parsed.data[SERVERS_KEY];
+  if (servers !== undefined && !isPlainObject(servers)) {
+    return { state: STATE.MALFORMED, eol, reason: wrongType(SERVERS_KEY, 'a JSON object'), ...NEUTRAL_ENTRY };
+  }
+  // PRESENCE is hasOwnProperty, never `value !== null`: a key that is THERE is a declaration this
+  // mode may refuse but must never replace — a literal `null` included.
+  const hasEntry = isPlainObject(servers) && Object.prototype.hasOwnProperty.call(servers, SERVER_NAME);
+  const existing = hasEntry ? servers[SERVER_NAME] : null;
+  const matches = hasEntry && stable(existing) === stable(entry);
+  return { ...parsed, eol, hasEntry, existing, matches, differs: hasEntry && !matches };
+};
+
+export const decideSettingsText = (text, allowRules) => {
+  const parsed = parseJsonText(text);
+  const eol = eolOf(text);
+  const neutral = { enabled: false, allowPresent: [], allowMissing: allowRules, complete: false };
+  if (parsed.state !== STATE.PRESENT) return { ...parsed, eol, ...neutral };
+  const malformed = (reason) => ({ state: STATE.MALFORMED, eol, reason, ...neutral });
+  const enabledList = parsed.data[ENABLED_KEY];
+  if (enabledList !== undefined && !Array.isArray(enabledList)) return malformed(wrongType(ENABLED_KEY, 'a JSON array'));
+  const permissions = parsed.data.permissions;
+  if (permissions !== undefined && !isPlainObject(permissions)) return malformed(wrongType('permissions', 'a JSON object'));
+  const allow = isPlainObject(permissions) ? permissions.allow : undefined;
+  if (allow !== undefined && !Array.isArray(allow)) return malformed(wrongType('permissions.allow', 'a JSON array'));
+  const rules = Array.isArray(allow) ? allow : [];
+  const enabled = Array.isArray(enabledList) && enabledList.includes(SERVER_NAME);
+  const allowMissing = allowRules.filter((rule) => !rules.includes(rule));
+  return {
+    ...parsed,
+    eol,
+    enabled,
+    allowPresent: allowRules.filter((rule) => rules.includes(rule)),
+    allowMissing,
+    // "Everything this mode writes is in place" — see the scope note in the header for what that
+    // deliberately does NOT mean.
+    complete: enabled && allowMissing.length === 0,
+  };
+};
+
+// readRegistration(root, io?) → the full registration picture of ONE project. `io.serverPath`
+// overrides the running kit's server path (tests); every fs primitive in `io` is the fs-read-nofollow
+// injection contract. NEVER throws.
+export const readRegistration = (root, io = {}) => {
+  const serverPath = io.serverPath ?? DEFAULT_SERVER_PATH;
+  const entry = buildServerEntry(serverPath);
+  const allowRules = allowRulesFor();
+
+  const mcpAbs = join(root, MCP_JSON_REL);
+  const mcpRead = readTarget(mcpAbs, io);
+  const mcpJson = { rel: MCP_JSON_REL, abs: mcpAbs, eol: LF, ...NEUTRAL_ENTRY, ...mcpRead,
+    ...(mcpRead.state === STATE.PRESENT ? decideMcpJsonText(mcpRead.text, entry) : {}) };
+
+  // The CONTAINER is classified BEFORE the file inside it is read, and the order is load-bearing:
+  // path resolution follows an INTERMEDIATE symlink (O_NOFOLLOW guards the FINAL component only), so
+  // reading first would pull a settings file from outside the work tree into memory — and into a
+  // verdict, and into a rendered merge body — before anything got the chance to refuse it.
+  const claudeDirAbs = join(root, CLAUDE_DIR_REL);
+  const claudeDir = { rel: CLAUDE_DIR_REL, abs: claudeDirAbs, ...classifyDir(claudeDirAbs, io) };
+  const containerUsable = claudeDir.state === STATE.PRESENT || claudeDir.state === STATE.ABSENT;
+
+  // settings.local.json is NOT read at all: this mode never writes it, so counting a rule that lives
+  // only there would report a registration the writer cannot maintain. (Reading it for the deny veto
+  // alone was tried and subtracted — see the scope note in the header.)
+  const settingsAbs = join(root, SETTINGS_REL);
+  const settingsRead = containerUsable
+    ? readTarget(settingsAbs, io)
+    : { state: STATE.UNREADABLE, reason: `${CLAUDE_DIR_REL} is a ${claudeDir.className ?? claudeDir.reason} — refusing to read through it` };
+  const neutralAllow = { enabled: false, allowPresent: [], allowMissing: allowRules, complete: false };
+  const settings = { rel: SETTINGS_REL, abs: settingsAbs, eol: LF, ...neutralAllow, ...settingsRead,
+    ...(settingsRead.state === STATE.PRESENT ? decideSettingsText(settingsRead.text, allowRules) : {}) };
+
+  return {
+    root,
+    serverPath,
+    entry,
+    allowRules,
+    mcpJson,
+    settings,
+    claudeDir,
+    registered: mcpJson.matches && settings.complete,
+  };
+};
+
+// The `.claude/` container: an ABSENT dir is a named state the preflight reports and only `--apply`
+// resolves (creating it here would make a read-only preflight write).
+const classifyDir = (abs, io) => {
+  let st;
+  try {
+    st = lstatNoFollowRead(abs, io.lstat);
+  } catch (err) {
+    return { state: STATE.UNREADABLE, reason: (err && (err.code || err.message)) || 'lstat failed' };
+  }
+  if (st === null) return { state: STATE.ABSENT };
+  if (st.isDirectory()) return { state: STATE.PRESENT };
+  return { state: STATE.FOREIGN, className: describeNonRegular(st) };
+};
+
+// ── the merges (ONE definition, shared by the writer's bodies and the paste-ready fragments) ──
+// Merge-don't-clobber in both: every foreign server, key and allow rule is carried over untouched,
+// and our own entry/rules are added idempotently.
+
+export const mergeMcpJson = (registration) => {
+  const base = isPlainObject(registration.mcpJson.data) ? registration.mcpJson.data : {};
+  const servers = isPlainObject(base[SERVERS_KEY]) ? base[SERVERS_KEY] : {};
+  return { ...base, [SERVERS_KEY]: { ...servers, [SERVER_NAME]: registration.entry } };
+};
+
+export const mergeSettings = (registration) => {
+  const base = isPlainObject(registration.settings.data) ? registration.settings.data : {};
+  const enabled = Array.isArray(base[ENABLED_KEY]) ? base[ENABLED_KEY] : [];
+  const permissions = isPlainObject(base.permissions) ? base.permissions : {};
+  const allow = Array.isArray(permissions.allow) ? permissions.allow : [];
+  return {
+    ...base,
+    [ENABLED_KEY]: enabled.includes(SERVER_NAME) ? enabled : [...enabled, SERVER_NAME],
+    permissions: { ...permissions, allow: [...allow, ...registration.allowRules.filter((rule) => !allow.includes(rule))] },
+  };
+};
+
+export const formatJson = (data, eol) => `${JSON.stringify(data, null, JSON_INDENT).replaceAll(LF, eol)}${eol}`;
+
+// The two hand-apply bodies — the whole output of the MASKED arm.
+//
+// They are deliberately DIFFERENT shapes, because what the kit knows about each file differs. The
+// settings file was OBSERVABLE — and read where present — so its body is a real merge: it already
+// carries every foreign key it had. The masked `.mcp.json` was not observable at all, so a
+// whole-file body would name only our server and, pasted as
+// instructed, would delete every foreign server the mask hid. `mcpEntry` is therefore the ENTRY
+// ALONE, to be merged under `mcpServers` by a human who can see what is actually in that file.
+export const renderFragments = (registration) => ({
+  mcpEntry: formatJson(registration.entry, registration.mcpJson.eol),
+  settings: formatJson(mergeSettings(registration), registration.settings.eol),
+});
+
+// A LIBRARY module the mode doc names by path — so someone can try to run it. A no-op on import;
+// on a direct run it points at the command that acts on what this module only reports.
+refuseDirectRun(import.meta.url);