@sabaiway/agent-workflow-kit 7.1.0 → 7.2.0

package/CHANGELOG.md

@@ -4,6 +4,59 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 7.2.0 — `.mcp.json` joins the hidden-mode footprint, and a worktree never owns it (AD-111)
+
+7.0.0 taught the kit to register its MCP server. It did not teach hidden mode about the file that
+registration writes — so a hidden deployment that ran `/agent-workflow-kit mcp` left `.mcp.json`
+sitting in `git status`, one `git add -A` away from a commit. That is exactly the leak the footprint
+registry exists to prevent, and it shipped anyway.
+
+- **`/.mcp.json` is in `KIT_OWN_PATHS`.** It joins `/.claude/settings.json` as a SHARED container the
+  kit merges into rather than owns, on the same terms: the tracked→ASK arm means a project that
+  already commits its own registration is asked, never silently un-tracked. Candidacy is
+  unconditional on purpose — the path is CONSIDERED before a later `mcp --apply` writes the file
+  rather than only after it appears, and is then hidden, dropped as already covered by a tracked
+  `.gitignore`, or surfaced as an ASK. That is what removes the follow-up reconcile the bug depended
+  on. The `contracts.md` prose mirror names it.
+- **A worktree is never HANDED one, and never owns one.** The scope is the untracked lanes this tool
+  drives — the registry copy set and `--include`; a TRACKED `.mcp.json` still arrives with
+  `git worktree add`, because that is the checkout, not a copy. One frozen never-provisioned set,
+  read at three sites because each needs it for a different reason: the copy set would hand a
+  satellite a launcher pinned to a path consented for the MAIN checkout; the containment sweep would
+  STOP the whole provision on an escaping symlink at that path (a device-node mask realpaths inside
+  the repo and reaches the later special-file refusal instead); and `registryRoots` decides what
+  `cleanup` may REMOVE. That third one was measured — without the guard, `cleanup` on a landed
+  worktree carrying a satellite's own `.mcp.json` exited 0 and took the file with it. `--include` is
+  refused pre-mutation for the same paths: it is the one door that bypasses the copy set, and it
+  would have recorded the launcher as ours.
+- **A settings copy this tool wrote never enables a server the worktree cannot declare.** The
+  guarantee is exactly that narrow. `.claude/settings.json` rides `REBASE_TARGETS` into a worktree
+  carrying `enabledMcpjsonServers`, which `mcp.md` itself calls a client error on every startup. An
+  untracked copy still equal to MAIN loses our enable and our two derived allow rules — and ONLY
+  those; every foreign server, rule and key survives, as do the file's EOL and the order of its
+  non-index keys (`withoutRegistration`, the token-removal complement of `mergeSettings`, not its
+  exact inverse — a JSON round-trip still hoists integer-like keys, as JS object semantics require).
+  **Where a rewrite would LOSE something the kit does not own, it is refused whole and says why.**
+  Three ways, each detected before anything is written: a number past double precision comes back a
+  different value; a duplicate key at any depth collapses to the last one (both found on the source
+  TEXT, because after the parse the evidence is gone); and invalid UTF-8 would become U+FFFD, so both
+  rewriting lanes — the pin rebase and the token strip — decode with FATAL UTF-8 and refuse
+  separately. The MAIN-equality proof compares BYTES, with the BOM preserved through the decode, so
+  a BOM-carrying original and a BOM-less copy can never pass for the same file.
+  The rewrite is admitted by ONE positive conjunction — untracked, bytes still MAIN's or their
+  rebased form, and a launcher proven ABSENT — so a tracked or user-modified settings file keeps its
+  registration tokens on purpose, as does one standing beside a launcher that is present or that
+  cannot be read. Those states get a neutral line naming the tokens; orphanhood is only CLAIMED where
+  it is proven.
+- **All three output arms name the reconcile.** Applied, masked hand-off, and already-registered —
+  the last one matters most, because a deployment registered under 7.0.0 learns about the reconcile
+  on its next run. A settings write that fails after the entry landed carries the note too: that
+  path never reaches the report, and it strands a standing registration.
+
+**Known residual, stated:** a VISIBLE deployment still commits a launcher carrying an absolute
+machine path. The fix is not symmetric with hidden mode — a visible `.mcp.json` may legitimately hold
+a team's own committable servers — so it is its own queued decision, not a line in this release.
+
 ## 7.1.0 — `fold-scope`: the fold channel gets a checker that refuses a claim whose reference does not resolve (AD-110)
 
 The engine canon now asks every finding to NAME the invariant its fix enforces before the edit

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '7.1.0'
+  version: '7.2.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/contracts.md

@@ -42,7 +42,7 @@ diverge:
 | `/.aider.input.history` | Aider | file | no | input history |
 | `/.continue/` | Continue | dir | no | project config dir |
 
-The kit's OWN footprint (`KIT_OWN_PATHS`) — `AGENTS.md`, `CLAUDE.md`, `docs/ai/` (subsumes the stamp), the added `scripts/*.mjs`, `docs/plans/`, `.claude/settings.local.json`, and `.claude/settings.json` (hidden-only — visible mode commits it) — is always a candidate in hidden mode.
+The kit's OWN footprint (`KIT_OWN_PATHS`) — `AGENTS.md`, `CLAUDE.md`, `docs/ai/` (subsumes the stamp), the added `scripts/*.mjs`, `docs/plans/`, `.claude/settings.local.json`, `.claude/settings.json` (hidden-only — visible mode commits it), and `.mcp.json` (the `mcp` mode's registration; hidden-only for the same reason, and it carries an absolute machine path) — is always a candidate in hidden mode.
 
 Not in this version: a fully-external hidden mode (artifacts relocated outside the repo tree).
 Deferred to a later release + migration.

package/references/modes/mcp.md

@@ -17,6 +17,8 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/mcp.mjs [--dry-run | --apply] [--cwd <dir>]`
 2. **Ask consent** via **`AskUserQuestion` where supported**, the no-change option first: keep the shell lanes, or register the typed channel — presenting the trust posture above in plain language.
 3. **Only on an explicit yes**, re-run with `--apply`. It writes **`.mcp.json` FIRST, then `.claude/settings.json`** — settings that enable a server whose entry is not yet there is a client error on every startup. Both writes are merge-don't-clobber (foreign servers, foreign keys and existing allow rules preserved; a re-apply adds nothing twice) and keep each file's existing EOL. New MCP servers are picked up when the client next starts — unlike the `hook` mode, this is not a hot reload.
 
+4. **Hidden-mode deployments:** after apply, run the hide-footprint reconcile (`node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile`) so the registration stays invisible to `git status` — `/.mcp.json` is in the known-footprint registry; every output arm reminds you.
+
 **The two arms that are not a write:**
 
 - **DIFFERING** — `.mcp.json` already carries an `"agent-workflow"` entry that **structurally differs** from ours (another kit copy, a hand-edited path, an added `env`, a `null`). The comparison is deliberately key-order-independent, so a re-serialized identical entry is the SAME registration, while any real difference in what would be launched is a difference. The run **STOPs unwritten, on both lanes**: silently changing what an MCP server launches is exactly what consent must not slide past. The recovery is named — review that entry, then remove or rename it and re-run. The kit never resolves this for you.

package/references/modes/worktrees.md

@@ -14,10 +14,25 @@ The ONE stored-metadata exception is the PREPARED OID recorded in the handoff: l
 Git ≥ 2.36 is required for NUL-terminated worktree porcelain; an older Git fails closed with its
 own verbatim error through the existing Git-error surface.
 
+**The MCP registration is never HANDED to a worktree, and never owned by one.** The scope is the
+untracked lanes this tool drives — the registry copy set and `--include` (refused pre-mutation, and
+a recorded include from an older handoff is filtered out too); a TRACKED `.mcp.json` still arrives
+with `git worktree add`, because that is the checkout, not a copy. `/.mcp.json` names an absolute
+machine path and its consent is per checkout, so it is excluded from the copy set, from the provision
+containment sweep, and from what `cleanup` may remove — a satellite's own `.mcp.json` therefore stays
+classified as foreign work and blocks cleanup, rather than being deleted as ours. The settings half
+is rewritten only under ONE conjunction of proven facts: untracked, bytes still MAIN's (or their
+rebased form), and a launcher proven ABSENT — then the copy loses our `enabledMcpjsonServers`
+membership and our two derived allow rules and nothing else. Every other state keeps its registration
+TOKENS — not necessarily its bytes, since `rebasePins` may still rewrite absolute pins in that same
+file on its own lane — and, where the settings file is readable, well-formed and actually carries
+tokens, gets a neutral line naming them; orphanhood is claimed only where it is proven.
+
 - `provision <slug> --plan <path> [--as <name>.md] [--dir <path>] [--branch <name>] [--include <path>]... [--install] [--resume]`
   — create a feature worktree (default: the visible sibling `<repoParent>/<repoName>--<slug>`,
   branch `aw/<slug>`) and populate it: the registry-derived footprint copy-if-missing (a tracked
-  file is NEVER overwritten), EXACTLY ONE seeded feature plan, the `handoff-<slug>.md` stub
+  file is NEVER overwritten, and `/.mcp.json` is never copied or owned — see below), EXACTLY ONE seeded
+  feature plan, the `handoff-<slug>.md` stub
   (written at provision — the tool's own record; `list` and `cleanup` read it), a
   `node_modules` symlink when main has one and the link stays ignored — a SHARED MUTABLE cache:
   writes through it hit MAIN's node_modules; for isolation RUN the printed isolated-install

package/references/templates/agent_rules.md

@@ -81,6 +81,7 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
 - **No code-mechanics in the plan.** A ledger row carries its path and anchor, and Verification carries the exact commands (the plan-shape canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
 - **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
 - **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
+- **State table BEFORE the guard — enumerate by PROOF, never by exclusion.** The subtraction rule above fires on a repeat finding, which is a LATE signal: by then the review has paid for each miss. The EARLY signal is structural — a decision whose input has **several independent state dimensions** (is it tracked? do the bytes still match the source? does the neighbouring file exist?). Write the table first, admit the write with **ONE conjunction of proven facts**, and funnel every other cell into a single refusal; the table is then the table-driven test. An exclusion list (`if (bad1) return; if (bad2) return;`) fails **OPEN** on the first state nobody enumerated — and "unreadable" is a state, distinct from "absent". A reviewer cannot save you here: it judges the patch in front of it and can only name the NEXT missing state, one round at a time.
 - **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.
 - **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-row review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
 - **Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY backend the recipe names (nits + a ship verdict is the stop). Folding ≠ convergence — re-review after folding.

package/tools/known-footprint.mjs

@@ -33,7 +33,12 @@ export const stop = (message, fields = {}) =>
 // may have unrelated scripts). `/.claude/settings.json` is carried HIDDEN-ONLY: in hidden mode the
 // kit's own attribution file is a footprint; in visible mode the kit commits it and never runs this
 // tool. It passes the same tracked→ASK classifier, so a project that already commits it gets an ASK,
-// never a silent un-track. `/docs/plans/` + both `.claude/settings*.json` are listed because a pure
+// never a silent un-track. `/.mcp.json` (the `mcp` mode's registration) is the second shared
+// container carried on those terms — the kit merges into it and preserves foreign servers, so the
+// same tracked→ASK arm is what protects a team that commits its own. It is seated here rather than
+// in KNOWN_FOOTPRINT deliberately: KIT_OWN candidacy is unconditional, so the path is in the block
+// BEFORE a later `mcp --apply` writes the file — present-only candidacy would re-open the very
+// follow-up-reconcile gap this entry closes. Never provisioned into a worktree (worktrees.mjs). `/docs/plans/` + both `.claude/settings*.json` are listed because a pure
 // hidden deploy has no tracked `.gitignore`; the classifier drops any candidate a tracked `.gitignore`
 // already covers, so in a repo that DOES track those ignores they are never re-written.
 // The enumeration must cover EVERY file the deploy copies into `scripts/` (bootstrap step 8 copies
@@ -67,6 +72,7 @@ export const KIT_OWN_PATHS = [
   '/docs/plans/',
   '/.claude/settings.local.json',
   '/.claude/settings.json',
+  '/.mcp.json',
 ];
 
 // Every OTHER tool's footprint. `falsePositiveRisk` flags a name generic/ambiguous enough that a

package/tools/mcp-registration.mjs

@@ -183,6 +183,76 @@ export const decideSettingsText = (text, allowRules) => {
   };
 };
 
+// The token-removal COMPLEMENT of mergeSettings (not its exact inverse — merging into an empty file
+// and removing again leaves the managed containers behind), for a settings copy moved away from its `.mcp.json`
+// (a provisioned worktree: it gets no launcher, so a copied enable would be a client error on every
+// client start). Removes ONLY our own tokens — our `SERVER_NAME` membership and our derived allow
+// rules — and preserves every foreign server, foreign rule, foreign key and the file's EOL. Returns
+// `{ text, changed, hasTokens, reason }` (the four outcomes are tabulated at the function); `text`
+// is the input byte-for-byte whenever `changed` is false — this never repairs, and never edits what
+// it did not understand.
+// A JSON round-trip is not content-preserving for everything a file may legally carry, and this
+// function rewrites a file it does NOT own — so each way the trip can lose data is detected and
+// REFUSES the rewrite whole. Two are known and both are checked on the SOURCE TEXT, because after
+// `JSON.parse` the evidence is already gone:
+//   • a number past double precision (9007199254740993 → …992) comes back a different value;
+//   • a duplicate key ({"a":1,"a":2}) collapses to the last one, dropping foreign data silently.
+// String bodies are blanked to `""` first, so a digit run or a colon inside a string is never read
+// as a number or a key. Deliberately strict on numbers: `1.0` and `1e2` are re-spellings rather
+// than losses and are refused too — fail-closed is the correct direction here.
+const blankStrings = (text) => text.replace(/"(?:[^"\\]|\\.)*"/g, '""');
+const JSON_NUMBER = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][-+]?\d+)?/g;
+
+const countKeys = (value) => (Array.isArray(value)
+  ? value.reduce((n, v) => n + countKeys(v), 0)
+  : isPlainObject(value)
+    ? Object.entries(value).reduce((n, [, v]) => n + 1 + countKeys(v), 0)
+    : 0);
+
+// Why a COUNT: a duplicate at any depth makes the source carry more key tokens than the parsed
+// value has keys. No second JSON parser, and nothing depends on where the duplicate sits.
+const roundTripLoss = (text, parsed) => {
+  const blanked = blankStrings(text);
+  const numbers = blanked.match(JSON_NUMBER) ?? [];
+  if (!numbers.every((lit) => String(JSON.parse(lit)) === lit)) return 'a number would not survive the rewrite';
+  const keyTokens = (blanked.match(/""\s*:/g) ?? []).length;
+  if (keyTokens !== countKeys(parsed)) return 'a duplicate key would be collapsed by the rewrite';
+  return null;
+};
+
+// Four outcomes over `{ text, changed, hasTokens, reason }`, and a caller must be able to tell them
+// apart — `changed:false` alone conflates
+// "nothing of ours is here" with "ours is here and the rewrite was REFUSED", and the second one owes
+// the operator a word:
+//   unreadable          → {changed:false, hasTokens:false, reason:'…'}   not JSON of the shape we write
+//   nothing of ours     → {changed:false, hasTokens:false, reason:null}
+//   refused (lossy)     → {changed:false, hasTokens:true,  reason:'…'}   tokens stay, say why
+//   rewritten           → {changed:true,  hasTokens:true,  reason:null}
+export const withoutRegistration = (text, allowRules = allowRulesFor()) => {
+  const keep = (hasTokens, reason) => ({ text, changed: false, hasTokens, reason });
+  const decided = decideSettingsText(text, allowRules);
+  if (decided.state !== STATE.PRESENT) return keep(false, 'not readable as settings JSON');
+  if (!decided.enabled && decided.allowPresent.length === 0) return keep(false, null);
+  const loss = roundTripLoss(text, decided.data);
+  if (loss !== null) return keep(true, loss);
+  const { [ENABLED_KEY]: enabledList, permissions } = decided.data;
+  const keptEnabled = (Array.isArray(enabledList) ? enabledList : []).filter((n) => n !== SERVER_NAME);
+  const keptAllow = (isPlainObject(permissions) && Array.isArray(permissions.allow) ? permissions.allow : [])
+    .filter((rule) => !allowRules.includes(rule));
+  // Only an allow array that ALREADY existed is rewritten — synthesising `allow: []` where the file
+  // had no such key would be adding foreign content under the name of removing ours.
+  const nextPermissions = isPlainObject(permissions) && Array.isArray(permissions.allow)
+    ? { ...permissions, allow: keptAllow }
+    : permissions;
+  // Rebuilt through the original order of the NON-INDEX keys — a settings file the user reads should
+  // not be reordered by a removal it did not ask for. Integer-like keys are the stated exception:
+  // any JSON round-trip hoists them to the front, because JS object semantics say so.
+  const next = Object.fromEntries(Object.entries(decided.data).map(([key, value]) => (
+    key === ENABLED_KEY ? [key, keptEnabled] : key === 'permissions' ? [key, nextPermissions] : [key, value]
+  )));
+  return { text: formatJson(next, decided.eol), changed: true, hasTokens: true, reason: null };
+};
+
 // 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.

package/tools/mcp.mjs

@@ -185,16 +185,35 @@ export const writeMcp = ({ cwd, dryRun = true } = {}, deps = {}) => {
     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 });
+    // A settings failure AFTER the entry landed leaves a STANDING registration on disk that never
+    // reaches formatResult — so the reconcile note has to ride the failure too, or a hidden
+    // deployment is left with a visible `.mcp.json` and no mention of it anywhere.
+    // The catch is around the WRITE, not inside it: a raw fs error (a failing rename) never passes
+    // through the injected stop, and it is exactly the case that strands a standing registration.
+    try {
+      // 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 });
+    } catch (err) {
+      // Reaching here always leaves a STANDING registration on disk — either this run wrote the
+      // entry (`writeMcpJson`) or the preflight found it already current (`matches`), and those two
+      // are exhaustive, so the note is unconditional rather than guarded by a branch nothing can
+      // take. A differing entry never reaches the writer at all; it STOPs in the preflight.
+      throw Object.assign(err, { message: `${err.message}\n${HIDDEN_MODE_LINE}` });
+    }
   }
   return { ...base, wrote: plan.writeMcpJson || plan.writeSettings };
 };
 
 // ── the report ─────────────────────────────────────────────────────────────────────────
 
+// A registration is an AI-tool footprint: `/.mcp.json` is in the known-footprint registry, so a
+// HIDDEN deployment needs the reconcile before `git status` is clean again. Stated conditionally —
+// this mode never detects visibility, and detecting it would widen what it reads.
+const HIDDEN_MODE_LINE =
+  'hidden-mode note: if this deployment is hidden, run the hide-footprint reconcile so the registration stays out of `git status` (the registry carries /.mcp.json).';
+
 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.';
 
@@ -229,6 +248,7 @@ const maskedReport = (result) => {
     `  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,
+    HIDDEN_MODE_LINE,
   ].join(LF);
 };
 
@@ -236,7 +256,7 @@ 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);
+    return [`agent-workflow MCP registration — already registered ("${SERVER_NAME}"); nothing to do.`, POSTURE_LINE, HIDDEN_MODE_LINE].join(LF);
   }
   const lines = [
     result.dryRun
@@ -247,6 +267,7 @@ export const formatResult = (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,
+    HIDDEN_MODE_LINE,
   ];
   if (result.dryRun) lines.push(`  to apply: ${applyMcpCommand(result.root)}`);
   return lines.join(LF);

package/tools/worktrees.mjs

@@ -16,6 +16,7 @@ import { join, dirname, basename, resolve, relative, isAbsolute, sep } from 'nod
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
+import { MCP_JSON_REL, SERVER_NAME, SETTINGS_REL, withoutRegistration } from './mcp-registration.mjs';
 import {
   KIT_OWN_PATHS, KNOWN_FOOTPRINT, expandGlob, normalizeSlashes, isDirPattern, isGlobPattern,
   patternToProbe,
@@ -65,6 +66,9 @@ const EXCLUDED_BASENAMES = new Set([
 ]);
 // Registry entries provision seeds by its own rules instead of copying wholesale.
 const SEEDED_SEPARATELY = new Set([`/${PLANS_REL}/`]);
+// Never copied AND never owned — unlike SEEDED_SEPARATELY, whose members cleanup may still remove.
+// A satellite's own `.mcp.json` must stay FOREIGN or an ordinary cleanup deletes what we never placed.
+const NEVER_PROVISIONED = new Set(['/.mcp.json']);
 // Copied files whose absolute main-root pins are rebased onto the worktree root.
 const REBASE_TARGETS = Object.freeze(['docs/ai/gates.json', '.claude/settings.json', '.claude/settings.local.json']);
 const TRACKED_PIN_DECLARATION =
@@ -192,6 +196,12 @@ const readFileNoFollow = (fs, abs) => {
   }
 };
 
+// Fatal UTF-8: a lossy decode would let invalid bytes become U+FFFD and pass for text we may rewrite.
+// `ignoreBOM: true` KEEPS a leading BOM in the string — the default STRIPS it, which would make a
+// BOM-carrying file and a BOM-less one decode identically and defeat a byte-faithful comparison.
+const UTF8_STRICT = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const decodeUtf8Strict = (buf) => { try { return UTF8_STRICT.decode(buf); } catch { return null; } };
+
 const NOFOLLOW_WRITE = fsC.O_WRONLY | fsC.O_CREAT | fsC.O_EXCL | (fsC.O_NOFOLLOW ?? 0);
 const COPY_BUFFER_BYTES = 64 * 1024;
 
@@ -650,7 +660,7 @@ export const provisionCopySet = (root, deps = {}) => {
   const fs = fsOf(deps);
   const out = [];
   for (const pattern of KIT_OWN_PATHS) {
-    if (SEEDED_SEPARATELY.has(pattern)) continue;
+    if (SEEDED_SEPARATELY.has(pattern) || NEVER_PROVISIONED.has(pattern)) continue;
     if (isPresent(root, pattern, fs)) out.push(pattern);
   }
   for (const entry of KNOWN_FOOTPRINT) {
@@ -902,7 +912,7 @@ export const rebaseAbsolutePins = (text, mainRoot, wtRoot) => {
 const assertProvisionSourcesContained = ({ root, rootReal, fs, statFollow }) => {
   const rels = [];
   for (const pattern of [...KIT_OWN_PATHS, ...KNOWN_FOOTPRINT.map((e) => e.pattern)]) {
-    if (SEEDED_SEPARATELY.has(pattern)) continue;
+    if (SEEDED_SEPARATELY.has(pattern) || NEVER_PROVISIONED.has(pattern)) continue;
     if (isGlobPattern(pattern)) {
       rels.push(...expandGlob(pattern, { dir: root, readdir: fs.readdir, stat: statFollow }).map((p) => patternToProbe(p)));
       continue;
@@ -2057,7 +2067,13 @@ const rebasePins = ({ root, wtRoot, git, fs, report, journal = NO_JOURNAL }) =>
     }
     const tracked = git(['ls-files', '--', target], wtRoot);
     if (tracked.status !== 0) throw stop(`git ls-files failed for ${target}: ${(tracked.stderr || tracked.stdout).trim()}`);
-    const text = String(cur.bytes);
+    // Fatal decode BEFORE any rewrite: `String(buffer)` turns invalid bytes into U+FFFD, so a
+    // rebase would silently destroy them in a file this lane only means to re-point.
+    const text = decodeUtf8Strict(cur.bytes);
+    if (text === null) {
+      report.push(`  ${target}: not valid UTF-8 — left untouched, pins not rebased`);
+      continue;
+    }
     const { text: rebased, changes } = rebaseAbsolutePins(text, root, wtRoot);
     if (tracked.stdout.trim() !== '') {
       if (changes.length > 0) report.push(`  ${target}: ${TRACKED_PIN_DECLARATION}`);
@@ -2065,7 +2081,7 @@ const rebasePins = ({ root, wtRoot, git, fs, report, journal = NO_JOURNAL }) =>
     }
     if (changes.length === 0) continue;
     const main = readFileNoFollow(fs, join(root, target));
-    const mainText = main.bytes ? String(main.bytes) : null;
+    const mainText = main.bytes ? decodeUtf8Strict(main.bytes) : null;
     const rebasedMain = mainText === null ? null : rebaseAbsolutePins(mainText, root, wtRoot).text;
     if (mainText !== null && (text === mainText || text === rebasedMain)) {
       writeContainedFileAtomic(wtRoot, wtAbs, rebasedMain, fs, { stop: (m) => stop(m) });
@@ -2163,6 +2179,13 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
     // Overlap refusal (pre-mutation): an include rel that another provision lane also populates
     // (the frozen registry footprint, the seeded plan, the handoff) — or another include root —
     // would meet the copy-if-missing kept-exit and skip the identity door entirely.
+    // A NEVER_PROVISIONED path is absent from reservedRels precisely because provision skips it, so
+    // the overlap arm below cannot see it — and an --include would copy it AND record it as owned,
+    // which is the never-owned half of the rule defeated through the one door that bypasses the set.
+    const neverProvisioned = [...NEVER_PROVISIONED].find((p) => includeRelsOverlap(rel, patternToProbe(p).replace(/\/$/, '')));
+    if (neverProvisioned !== undefined) {
+      throw stop(`--include names a path a worktree never gets and never owns (${neverProvisioned}): ${inc} — an MCP registration is machine-local and its consent is per checkout; register the satellite itself instead`);
+    }
     const reserved = reservedRels.find((r) => includeRelsOverlap(rel, r));
     if (reserved !== undefined) {
       throw stop(`--include overlaps a path provision itself populates (${reserved}): ${inc} — the footprint, the seeded plan, and the handoff are copied by provision; drop the --include`);
@@ -2239,6 +2262,69 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
   }
 };
 
+// The worktree gets no `.mcp.json`, so a settings enable carried over would name a server it does
+// not declare. Eligibility is decided LIVE by the same two questions rebasePins asks — is the file
+// tracked, and is it still MAIN's bytes (before or after the pin rebase)? — never by a run-local
+// copy log, which a --resume turns into `kept` and silently skips. Anything else is user work: the
+// registration TOKENS stay — the bytes may still move, since rebasePins rewrites absolute pins on
+// its own lane — and the tokens are REPORTED rather than quietly left. Scope note: this is the
+// untracked provision lane; a TRACKED `.mcp.json` arrives with `git worktree add`, not with us.
+//
+// SCOPE, stated: this speaks only about a settings file that is readable, well-formed and actually
+// carries tokens of ours. An absent, unreadable or non-JSON one is not this lane's business and
+// returns silently — `rebasePins` above already reports the unreadable case in its own words.
+const dropMcpRegistration = ({ root, wtRoot, git, fs, report }) => {
+  const wtAbs = join(wtRoot, SETTINGS_REL);
+  const cur = readFileNoFollow(fs, wtAbs);
+  if (!cur.bytes) return;
+  // STRICT decode, and the MAIN comparison below is on BYTES: `String(buffer)` replaces invalid
+  // UTF-8 with U+FFFD, so two DIFFERENT byte sequences can decode to the same string — which would
+  // let a file that is not MAIN's satisfy the "matches MAIN" proof and be rewritten.
+  const text = decodeUtf8Strict(cur.bytes);
+  if (text === null) {
+    report.push(`  ${SETTINGS_REL}: not valid UTF-8 — left untouched, and no registration claim is made about it`);
+    return;
+  }
+  const removal = withoutRegistration(text);
+  if (!removal.hasTokens) return; // nothing of ours in it, or not readable as ours
+  if (removal.reason !== null) {
+    // Tokens ARE here and the rewrite was refused to protect foreign data — never a silent skip.
+    report.push(`  ${SETTINGS_REL}: carries registration tokens for "${SERVER_NAME}" but ${removal.reason}; left untouched`);
+    return;
+  }
+  // ONE conjunction of PROVEN facts admits the write; every other state — including every state a
+  // read cannot settle — takes the single report branch below. Stated as a positive proof rather
+  // than a list of exclusions on purpose: three review rounds each found one more launcher/copy
+  // sub-state an exclusion list had not enumerated, and an unenumerated state failed OPEN.
+  const tracked = git(['ls-files', '--', SETTINGS_REL], wtRoot);
+  if (tracked.status !== 0) throw stop(`git ls-files failed for ${SETTINGS_REL}: ${(tracked.stderr || tracked.stdout).trim()}`);
+  const main = readFileNoFollow(fs, join(root, SETTINGS_REL));
+  const mainText = main.bytes ? decodeUtf8Strict(main.bytes) : null;
+  // Byte equality, and it is NOT interchangeable with string equality: a decoder that strips the BOM
+  // maps a BOM-carrying file and a BOM-less one to the same string. Only the DIRECT branch is
+  // independent of that policy — the rebased branch rebuilds the expected bytes FROM `mainText`, so
+  // it holds only because `ignoreBOM: true` kept the BOM in the decode.
+  const isMainCopy = mainText !== null
+    && (cur.bytes.equals(main.bytes)
+      || cur.bytes.equals(Buffer.from(rebaseAbsolutePins(mainText, root, wtRoot).text, 'utf8')));
+  // ABSENT is the only launcher state that proves the tokens are orphaned. Unreadable, symlinked,
+  // device-masked and present-with-an-entry all mean "a declaration may be live" — never strip.
+  const launcherAbsent = readFileNoFollow(fs, join(wtRoot, MCP_JSON_REL)).absent === true;
+  // The admission is ONE positive conjunction; the chain below only NAMES which proof was missing.
+  const canStrip = tracked.stdout.trim() === '' && isMainCopy && launcherAbsent;
+  const why = canStrip ? null
+    : tracked.stdout.trim() !== '' ? 'tracked'
+      // NOT "user-modified": the same arm covers a MAIN settings file that is absent or unreadable.
+      : !isMainCopy ? 'not proven to match MAIN'
+        : `a ${MCP_JSON_REL} is present or unreadable`;
+  if (!canStrip) {
+    report.push(`  ${SETTINGS_REL}: ${why} — carries registration tokens for "${SERVER_NAME}"; left untouched, remove them by hand if this worktree declares no server`);
+    return;
+  }
+  writeContainedFileAtomic(wtRoot, wtAbs, removal.text, fs, { stop: (m) => stop(m) });
+  report.push(`  ${SETTINGS_REL}: dropped our registration tokens (this worktree declares no ${MCP_JSON_REL})`);
+};
+
 const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed, includeSources, provisionSet, git, deps, fs, report, log }) => {
   // THIS run's proof set: every lane journals the leaf it placed or kept, and nothing else is ever
   // examined by the resume verify — the session's own work is out of scope by construction.
@@ -2261,6 +2347,9 @@ const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed
   const vscodeMode = provisionVscode({ root, wtRoot: targetPath, slug, git, fs, report, journal });
 
   rebasePins({ root, wtRoot: targetPath, git, fs, report, journal });
+  // AFTER the rebase: stripping first makes the copy differ from MAIN, and rebasePins would then
+  // read it as user work and skip the pins it exists to fix.
+  dropMcpRegistration({ root, wtRoot: targetPath, git, fs, report });
 
   const inFlight = plansInFlight(targetPath, fs.readdir);
   if (inFlight.length !== 1 || inFlight[0] !== seed.name) {
@@ -2877,6 +2966,7 @@ const headEntry = (git, cwd, head, path) => {
 const registryRoots = () => {
   const roots = [];
   for (const pattern of [...KIT_OWN_PATHS, ...KNOWN_FOOTPRINT.map((entry) => entry.pattern)]) {
+    if (NEVER_PROVISIONED.has(pattern)) continue; // on the RAW pattern — normalizing first never matches
     const normalized = normalizeSlashes(pattern).replace(/^\//, '').replace(/\/$/, '');
     if (normalized) roots.push(normalized);
   }
@@ -2891,10 +2981,20 @@ const safeRecordedPath = (path) => {
   return normalized;
 };
 
+// Ownership has TWO sources — the registry and the record's own includes — and BOTH must honour
+// NEVER_PROVISIONED. A record written before the --include refusal existed still names the path, and
+// without this filter that legacy record hands cleanup a registration it may delete. The comparison
+// is includeRelsOverlap, the SAME predicate the refusal uses. Stated honestly: on POSIX that is
+// indistinguishable from an exact match here (a recorded DESCENDANT covers nothing at this path, and
+// case is significant); what it buys is the backslash-platform case fold, already pinned on the
+// predicate itself (worktrees-include-identity.test.mjs) rather than claimed by a test run here.
+const NEVER_PROVISIONED_RELS = [...NEVER_PROVISIONED].map((p) => patternToProbe(p).replace(/\/$/, ''));
+const isNeverProvisionedRel = (rel) => NEVER_PROVISIONED_RELS.some((p) => includeRelsOverlap(rel, p));
+
 const provisionKnownRoots = (identity) => {
   const roots = [
     ...registryRoots(),
-    ...identity.record.includes.map(safeRecordedPath),
+    ...identity.record.includes.map(safeRecordedPath).filter((rel) => !isNeverProvisionedRel(rel)),
     PLANS_REL,
   ];
   if (identity.record.vscode === 'written') roots.push('.vscode/settings.json');