archgen-mcp 0.0.7 → 0.1.0

package/src/core/brief-scope.mjs

@@ -0,0 +1,218 @@
+// brief-scope.mjs — derive the artifact space a dispatch brief is written
+// against, and derive EVERY path the brief carries from ONE source.
+//
+// WHY THIS EXISTS — two defects, one cause (paths were assembled by hand
+// instead of resolved):
+//
+//   1. The brief action demanded `slug` even when the caller had already
+//      passed the absolute `tasks.yaml`. That path IS `.archgen/<slug>/
+//      tasks.yaml` — the slug is derivable — so the tool asked for the same
+//      fact twice in two different shapes, and a caller that omitted `slug`
+//      got "needs tasks.yaml, plans dir, slug dir — pass slug" for a brief
+//      it had already given everything for.
+//
+//   2. The emitted brief mixed path vocabularies: `tasks.yaml` was ABSOLUTE
+//      while `slug dir` and `plans dir` were PROJECT-RELATIVE. A brief is
+//      handed to a sub-agent whose working directory may be a worktree or
+//      another repo root; `ctx.contain()` resolves a relative path against
+//      the SERVER's project root, so the relative paths in the brief
+//      silently pointed at a different tree. A brief whose paths only work
+//      from one cwd is a broken brief.
+//
+// Every path in a brief is now absolute, and every one of them comes from the
+// single scope resolved here.
+import { realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { resolveSlugInput, ScopeError } from './scope.mjs';
+import { invalidInput } from './errors.mjs';
+
+// The slug is a directory name, never a path: a slug of "../../etc" must not
+// be able to steer the brief's paths out of the artifact space.
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * The REAL path of a path that may not exist yet.
+ *
+ * The scope gate proves paths by realpath, so the brief's paths are real
+ * paths. When the leaf does not exist yet — a brief written before the plan
+ * lands — the deepest EXISTING ancestor is realpath'd and the remaining
+ * segments are re-appended. The result is the path the file WILL have, not
+ * a different spelling of the same place.
+ *
+ * Without this, the same plan produced two different prefixes depending on
+ * whether tasks.yaml happened to exist: `/var/...` from the lexical
+ * fallback and `/private/var/...` from the realpath branch.
+ *
+ * @param {string} abs
+ * @returns {string}
+ */
+function realpathNearest(abs) {
+  const tail = [];
+  let cur = resolve(abs);
+  for (;;) {
+    try {
+      const real = realpathSync(cur);
+      return tail.length ? join(real, ...tail.slice().reverse()) : real;
+    } catch {
+      const parent = dirname(cur);
+      if (parent === cur) return resolve(abs);
+      tail.push(basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+/**
+ * Derive the slug directory from a `tasks.yaml` path WITHOUT touching the
+ * filesystem — used when the file does not exist yet (a brief can be written
+ * before the plan lands) or when it cannot be realpath-resolved.
+ *
+ * The shape is EXACTLY the shape `resolveSlugInput` returns — `{root, slug}` —
+ * so the two branches cannot disagree about the field names. They did once,
+ * and the fallback silently produced `slugDir: undefined`.
+ *
+ * @param {string} p
+ * @returns {{root: string, slug: string}|null}
+ */
+function deriveFromTasksPath(p) {
+  if (basename(p) !== 'tasks.yaml') return null;
+  const slugDir = dirname(p);
+  const slug = basename(slugDir);
+  if (!SLUG_RE.test(slug)) return null;
+  if (basename(dirname(slugDir)) !== '.archgen') return null;
+  return { root: realpathNearest(slugDir), slug };
+}
+
+/**
+ * Derive the slug directory from a `plans` directory path.
+ *
+ * @param {string} p
+ * @returns {{root: string, slug: string}|null}
+ */
+function deriveFromPlansPath(p) {
+  if (basename(p) !== 'plans') return null;
+  const slugDir = dirname(p);
+  const slug = basename(slugDir);
+  if (!SLUG_RE.test(slug)) return null;
+  if (basename(dirname(slugDir)) !== '.archgen') return null;
+  return { root: realpathNearest(slugDir), slug };
+}
+
+/**
+ * Resolve the artifact space a brief is written against.
+ *
+ * The caller may name the space in any of three ways; they are equivalent and
+ * are reconciled here:
+ *
+ *   - `tasksYaml` — the absolute path to `<slugDir>/tasks.yaml` (strongest:
+ *     it names a real file, so the scope is proven, not assumed);
+ *   - `planDir`   — the absolute path to `<slugDir>/plans`;
+ *   - `slug`      — the slug name alone.
+ *
+ * @param {{
+ *   tasksYaml?: string|null,
+ *   planDir?: string|null,
+ *   slug?: string|null,
+ *   projectRoot: string,
+ * }} opts
+ * @returns {{slug: string, slugDir: string, plansDir: string, tasksYaml: string, source: 'tasksYaml'|'planDir'|'slug'}}
+ */
+export function resolveBriefScope(opts) {
+  const { tasksYaml = null, planDir = null, slug = null, projectRoot } = opts;
+  if (!projectRoot) throw invalidInput('brief scope needs a project root', {});
+
+  let slugDir = null;
+  let resolvedSlug = null;
+  let tasksFile = null;
+  let source = null;
+
+  if (tasksYaml) {
+    let scoped = null;
+    try {
+      scoped = resolveSlugInput(tasksYaml, projectRoot);
+    } catch (e) {
+      if (e instanceof ScopeError) {
+        throw invalidInput(`tasks.yaml must live in .archgen/<slug>/ — ${tasksYaml} does not`, { file: tasksYaml });
+      }
+      // The file may not exist yet. The path SHAPE still proves the scope.
+      scoped = deriveFromTasksPath(tasksYaml);
+      if (!scoped) {
+        throw invalidInput(`cannot read ${tasksYaml} (missing or unreadable)`, { file: tasksYaml });
+      }
+    }
+    slugDir = scoped.root;
+    resolvedSlug = scoped.slug;
+    // The tasks file is taken from the RESOLVED slug dir, not from the raw
+    // path the caller typed. `resolveSlugInput` realpath-resolves, so this is
+    // the same file — but it shares one prefix with the slug dir and the
+    // plans dir. A brief whose three paths carry two different prefixes
+    // (`/var/...` vs `/private/var/...` — the macOS symlink) reads as three
+    // different locations to anything comparing them.
+    tasksFile = join(slugDir, 'tasks.yaml');
+    source = 'tasksYaml';
+  } else if (planDir) {
+    const scoped = deriveFromPlansPath(planDir);
+    if (!scoped) {
+      throw invalidInput(`plans dir must live in .archgen/<slug>/plans — ${planDir} does not`, { file: planDir });
+    }
+    slugDir = scoped.root;
+    resolvedSlug = scoped.slug;
+    tasksFile = join(slugDir, 'tasks.yaml');
+    source = 'planDir';
+  } else if (slug) {
+    if (!SLUG_RE.test(slug)) {
+      throw invalidInput(`slug '${slug}' is not a valid slug (lowercase, dash-separated)`, { slug });
+    }
+    slugDir = realpathNearest(join(projectRoot, '.archgen', slug));
+    resolvedSlug = slug;
+    tasksFile = join(slugDir, 'tasks.yaml');
+    source = 'slug';
+  } else {
+    throw invalidInput('brief needs tasks.yaml, a plans dir, or a slug — pass one of them', {
+      action: 'brief',
+      missing: ['tasks.yaml', 'slug'],
+    });
+  }
+
+  // The two spellings must agree. A caller that passes a tasks.yaml from one
+  // slug and the name of another has made a mistake the brief would
+  // otherwise paper over.
+  if (slug && resolvedSlug && slug !== resolvedSlug) {
+    throw invalidInput(`slug '${slug}' does not match the artifact space '${resolvedSlug}'`, {
+      slug,
+      actual: resolvedSlug,
+    });
+  }
+
+  return {
+    slug: resolvedSlug,
+    slugDir,
+    plansDir: join(slugDir, 'plans'),
+    tasksYaml: tasksFile,
+    source,
+  };
+}
+
+/**
+ * The template variables a brief is rendered with.
+ *
+ * Every path is ABSOLUTE. The relative forms are gone: they resolved against
+ * whatever cwd the reading agent happened to have.
+ *
+ * @param {{slug: string, slugDir: string, plansDir: string, tasksYaml: string}} scope
+ * @param {{featureRequest?: string|null, topic?: string|null, round?: number|string|null}} extra
+ * @returns {Record<string, string>}
+ */
+export function briefVars(scope, extra = {}) {
+  const vars = {
+    slug: scope.slug,
+    'slug dir': scope.slugDir,
+    'plans dir': scope.plansDir,
+    'tasks.yaml': scope.tasksYaml,
+  };
+  if (extra.featureRequest) vars['feature request'] = extra.featureRequest;
+  else vars['feature request'] = scope.slug;
+  if (extra.topic) vars.topic = extra.topic;
+  if (extra.round !== undefined && extra.round !== null && extra.round !== '') vars.round = String(extra.round);
+  return vars;
+}

package/src/core/briefs.mjs

@@ -42,11 +42,15 @@ export function loadBrief(briefsDir, kind, vars = {}) {
  * A dispatched brief must not carry a placeholder: a worker told to read
  * `<slug dir>` looks for a directory with that literal name.
  *
+ * The matcher is CASE-INSENSITIVE on the first letter. It used to require a
+ * lowercase first character, so `<Domain>` — the literal placeholder that
+ * shipped in every worker prompt — was invisible to it.
+ *
  * @param {string} text
  * @returns {string[]}
  */
 export function remainingPlaceholders(text) {
-  return [...new Set([...String(text ?? '').matchAll(/<([a-z][a-z. ]*)>/g)].map((m) => m[1]))];
+  return [...new Set([...String(text ?? '').matchAll(/<([A-Za-z][A-Za-z. ]*)>/g)].map((m) => m[1]))];
 }
 
 /**
@@ -58,3 +62,107 @@ export function loadAllBriefs(briefsDir) {
   for (const kind of BRIEF_KINDS) out[kind] = loadBrief(briefsDir, kind).brief;
   return out;
 }
+
+/**
+ * The context block every dispatch brief carries — the EVIDENCE map, the
+ * pre-rendered tool results, and the rules that keep the sub-agent from
+ * re-deriving what the brief already says.
+ *
+ * WHY THIS IS RENDERED BY THE TOOL AND NOT WRITTEN INTO EACH TEMPLATE:
+ *
+ *   1. EVIDENCE. The verifier used to be told to "read plans + tasks.yaml" —
+ *      whole files, every round. The brief now carries the FILE LIST and the
+ *      SECTION ANCHORS, so the agent reads the sections that matter instead
+ *      of re-reading the plan. A map, not a copy: the agent decides what to
+ *      open, and the map is what lets it decide.
+ *
+ *   2. PRE-RENDERED RESULTS. The review brief used to say "attach the
+ *      mermaid graph and the docs-validate result" — which cost the
+ *      orchestrator two extra tool calls per round, one of which (the graph)
+ *      failed on every plan. The tool renders them once, into the brief.
+ *
+ *   3. THE FORBIDDEN LIST. Without it, a sub-agent reads the archgen skill
+ *      and its references (the orchestrator's protocol, not its) and runs the
+ *      archgen tool suite to re-derive what it was just handed. That is a
+ *      second and third reading of the same facts — pure cost, and a chance
+ *      to drift from the protocol the orchestrator is following.
+ *
+ * @param {{
+ *   scope?: {slug?: string, slugDir?: string, plansDir?: string, tasksYaml?: string}|null,
+ *   evidence?: {files: Array<{path: string, sections: Array<{slug: string, title: string}>}>, fileCount: number}|null,
+ *   graph?: string|null,
+ *   docsValidation?: {valid: boolean, broken: unknown[], warnings: unknown[]}|null,
+ *   allowedCalls?: string[],
+ * }} ctx
+ * @returns {string}
+ */
+export function renderBriefContext(ctx = {}) {
+  const out = [];
+
+  out.push('## CONTEXT — read this first');
+  out.push('');
+  out.push(
+    'Everything you need is in this brief. Do NOT read the archgen skill, its references, or any ' +
+      'protocol document — they are the ORCHESTRATOR\'s, and reading them re-derives context you were ' +
+      'already given.',
+  );
+  const allowed = ctx.allowedCalls ?? [];
+  out.push(
+    allowed.length
+      ? `Do NOT run the archgen tool suite beyond these calls: ${allowed.join(', ')}.`
+      : 'Do NOT run the archgen tool suite at all.',
+  );
+  out.push(
+    'Read ONLY the files in EVIDENCE, and only the sections named. Do not read whole documents when a ' +
+      'section is named.',
+  );
+  out.push('');
+
+  if (ctx.scope) {
+    out.push('## EVIDENCE — the plan under review');
+    out.push('');
+    if (ctx.scope.tasksYaml) out.push(`- tasks: ${ctx.scope.tasksYaml}`);
+    if (ctx.scope.plansDir) out.push(`- plans: ${ctx.scope.plansDir}`);
+    if (ctx.scope.slugDir) out.push(`- artifacts: ${ctx.scope.slugDir}`);
+    out.push('');
+  }
+
+  if (ctx.evidence?.files?.length) {
+    out.push('### Section index — pull the section, never the file');
+    out.push('');
+    for (const f of ctx.evidence.files) {
+      out.push(`- ${f.path}`);
+      for (const s of f.sections) out.push(`  - § ${s.slug} — ${s.title}`);
+    }
+    out.push('');
+  }
+
+  if (ctx.graph) {
+    out.push('### Dependency graph (rendered for you — do not re-fetch)');
+    out.push('');
+    out.push('```mermaid');
+    out.push(ctx.graph);
+    out.push('```');
+    out.push('');
+  }
+
+  if (ctx.docsValidation) {
+    const broken = ctx.docsValidation.broken?.length ?? 0;
+    const warned = ctx.docsValidation.warnings?.length ?? 0;
+    out.push('### Reference-integrity result (rendered for you — do not re-fetch)');
+    out.push('');
+    out.push(`- valid: ${ctx.docsValidation.valid === true}`);
+    out.push(`- broken references: ${broken}`);
+    out.push(`- warnings: ${warned}`);
+    if (broken > 0) {
+      out.push('');
+      out.push('Broken references (each BLOCKS approval):');
+      for (const b of ctx.docsValidation.broken) {
+        out.push(`- ${b.file ?? ''}${b.line ? `:${b.line}` : ''} — ${b.kind ?? 'broken'}: ${b.ref ?? ''}`);
+      }
+    }
+    out.push('');
+  }
+
+  return out.join('\n');
+}

package/src/core/codegraph-manager.mjs

@@ -228,6 +228,18 @@ export async function manageCodegraph(opts) {
         report.cli.action = 'would-install';
         return { bin: null, version: null };
       }
+      // NOT APPROVED — do not install.
+      //
+      // A global `npm install -g` is a write to the user's machine, exactly
+      // like a config write, and the tool documents the opposite of what the
+      // code used to do: "Without `approve: true` the tool prints its plan
+      // and writes nothing." The code installed a global program anyway.
+      // The gate now covers the install, so an unapproved call is a plan.
+      if (!approved) {
+        report.cli.action = 'would-install';
+        report.cli.detail = `not installed — pass approve:true to install ${CODEGRAPH_PACKAGE} globally`;
+        return { bin: null, version: null };
+      }
       // Official install path; always the latest published release.
       const inv = npmInvocation(['install', '-g', CODEGRAPH_PACKAGE], env);
       const r = await runAsync(inv.command, inv.args, { timeout: 600000, shell: inv.shell, env });

package/src/core/doc-navigator.mjs

@@ -445,44 +445,128 @@ export function docIndex(input, opts = {}) {
 
   if (mode === 'section') {
     if (!sectionRef) throw invalidInput('section mode requires a path', {});
+
     const hash = sectionRef.indexOf('#');
     const filePart = hash === -1 ? sectionRef : sectionRef.slice(0, hash);
     const anchor = hash === -1 ? null : sectionRef.slice(hash + 1);
-    const candidates = [join(repoRoot, filePart), join(slugDir, filePart)];
-    const hit = candidates.find((p) => {
+
+    // The ref may name a FILE, a file#anchor, or a bare SECTION SLUG.
+    //
+    // The bare-slug form is not a convenience — it is REQUIRED for the
+    // digest -> section round trip to work. `digest` hands out
+    // `sections[].slug` (the GitHub-exact heading slug), so the obvious next
+    // call is `section: "<slug>"`. That call used to fail on EVERY plan,
+    // because the whole ref was treated as a FILE path and no file is named
+    // after a heading. The agent had to re-join `path` + '#' + `slug` by
+    // hand, and nothing — not the digest, not the schema, not archgen_help —
+    // said so.
+    const fileCandidates = [];
+    if (filePart) fileCandidates.push(join(repoRoot, filePart), join(slugDir, filePart));
+    if (fileScopeArg) fileCandidates.push(join(repoRoot, fileScopeArg), join(slugDir, fileScopeArg));
+
+    const hit = fileCandidates.find((p) => {
       try {
         return statSync(p).isFile();
       } catch {
         return false;
       }
     });
-    if (!hit) throw notFound(`cannot read section ${sectionRef} (missing or not a file)`, { section: sectionRef });
-    let hitReal;
-    try {
-      hitReal = realpathSync(hit);
-    } catch {
-      hitReal = resolve(hit);
+
+    if (hit) {
+      let hitReal;
+      try {
+        hitReal = realpathSync(hit);
+      } catch {
+        hitReal = resolve(hit);
+      }
+      if (!hitReal.startsWith(slugDir + sep)) {
+        throw invalidInput(`section ${sectionRef} is outside ${input}`, { section: sectionRef });
+      }
+      const doc = parsedDocAt(hit);
+      if (!doc) throw notFound(`cannot read section ${sectionRef} (unreadable)`, { section: sectionRef });
+      if (anchor) {
+        const section = findSection(doc, anchor);
+        if (!section) {
+          throw notFound(`section ${sectionRef}: no section '${anchor}' in ${filePart}`, {
+            section: sectionRef,
+            file: relFromRoot(hit),
+            available: buildSections(doc).map((s) => s.slug),
+          });
+        }
+        return {
+          mode,
+          data: {
+            path: relFromRoot(hit),
+            anchor: section.slug,
+            line: section.line,
+            endLine: section.endLine,
+            text: section.body,
+          },
+        };
+      }
+      return { mode, data: { path: relFromRoot(hit), text: doc.lines.join('\n') } };
     }
-    if (!hitReal.startsWith(slugDir + sep)) {
-      throw invalidInput(`section ${sectionRef} is outside ${input}`, { section: sectionRef });
+
+    // No file matched: the ref is a SECTION SLUG (possibly with a '#anchor'
+    // whose file part was empty). Resolve it against the documents.
+    const wanted = anchor && !filePart ? anchor : filePart;
+    if (!wanted) {
+      throw notFound(`cannot read section ${sectionRef} (missing or not a file)`, { section: sectionRef });
     }
-    const doc = parsedDocAt(hit);
-    if (!doc) throw notFound(`cannot read section ${sectionRef} (unreadable)`, { section: sectionRef });
-    if (anchor) {
-      const section = findSection(doc, anchor);
-      if (!section) throw notFound(`section ${sectionRef}: no section '${anchor}' in ${filePart}`, { section: sectionRef });
+
+    const { docs } = collectDocs();
+    const hits = [];
+    for (const doc of docs) {
+      const section = findSection(doc, wanted);
+      if (section) hits.push({ doc, section });
+    }
+
+    if (hits.length === 1) {
+      const { doc, section } = hits[0];
       return {
         mode,
         data: {
-          path: relFromRoot(hit),
+          path: relFromRoot(doc.abs),
           anchor: section.slug,
+          title: section.title,
           line: section.line,
           endLine: section.endLine,
           text: section.body,
         },
       };
     }
-    return { mode, data: { path: relFromRoot(hit), text: doc.lines.join('\n') } };
+
+    if (hits.length > 1) {
+      // Ambiguous: report the candidates, never guess. A wrong guess costs
+      // the agent a whole extra read cycle.
+      return {
+        mode,
+        data: {
+          ambiguous: true,
+          ref: wanted,
+          matches: hits.map(({ doc, section }) => ({
+            path: relFromRoot(doc.abs),
+            section: section.slug,
+            title: section.title,
+            line: section.line,
+            endLine: section.endLine,
+          })),
+          hint: 'the section slug matches more than one document — fetch it as path#anchor, e.g. demo/docs/prd.md#install',
+        },
+      };
+    }
+
+    // Nothing matched: name the available vocabulary, so one failed call is
+    // enough to recover — the same courtesy archgen_refs already gives.
+    const available = [];
+    for (const doc of docs) {
+      for (const s of buildSections(doc)) available.push(`${relFromRoot(doc.abs)}#${s.slug}`);
+    }
+    throw notFound(`no section '${wanted}' under ${slug}`, {
+      section: sectionRef,
+      available: available.slice(0, 50),
+      availableCount: available.length,
+    });
   }
 
   if (mode === 'map') {

package/src/core/errors.mjs

@@ -46,7 +46,7 @@ export const ownershipConflict = (message, details) => new ArchgenError('OWNERSH
 export const conflict = (message, details) => new ArchgenError('CONFLICT', message, details);
 /** A write was refused by a safety guard (symlink, outside-root, no approval). */
 export const permissionDenied = (message, details) => new ArchgenError('PERMISSION_DENIED', message, details);
-/** A required external actor is absent (extension not running, binary missing). */
+/** A required external actor is absent (a binary is missing, a service is down). */
 export const unavailable = (message, details) => new ArchgenError('UNAVAILABLE', message, details);
 /** An operation exceeded its deadline. */
 export const timeout = (message, details) => new ArchgenError('TIMEOUT', message, details);

package/src/core/harness-wiring.mjs

@@ -21,6 +21,7 @@ import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve, sep } from 'node:path';
 import { assertNotSymlink, assertWithinRoot, withFileLock, writeFileAtomic } from './fs-safety.mjs';
+import { mergeEntry, parseJsonc, removeEntry } from './jsonc-config.mjs';
 import { invalidInput } from './errors.mjs';
 
 /**
@@ -129,16 +130,40 @@ export function buildEntry(entries, npxEntries, entryKey, binPath, fallbackComma
   return entry;
 }
 
-/** Read + parse a JSON config; null when absent, {error} when unparseable. */
+/**
+ * Read + parse a JSON config; null when absent, {error} when unparseable.
+ *
+ * JSONC is accepted: opencode and Zed keep their settings as JSON-with-
+ * comments, and a config the writer cannot even read is a config it can
+ * never wire.
+ */
 export function readJsonConfig(abs) {
   if (!existsSync(abs)) return { data: null, existed: false };
   try {
-    return { data: JSON.parse(readFileSync(abs, 'utf8')), existed: true };
+    const { data, error } = parseJsonc(readFileSync(abs, 'utf8'));
+    if (error) return { data: null, existed: true, error };
+    return { data, existed: true };
   } catch (e) {
     return { data: null, existed: true, error: e.message };
   }
 }
 
+/**
+ * The nested object for a new config file.
+ *
+ * The key may be a DOTTED PATH: opencode keeps its servers at
+ * `mcp.servers.<id>`, so a flat `{ "mcp.servers": … }` would put the entry
+ * where opencode never looks — the server would be installed and invisible.
+ */
+function nestedConfig(key, serverId, entry) {
+  const parts = key.split('.');
+  let value = { [serverId]: entry };
+  for (let i = parts.length - 1; i >= 0; i--) {
+    value = { [parts[i]]: value };
+  }
+  return value;
+}
+
 /**
  * Merge a server entry into a JSON MCP config.
  *
@@ -167,27 +192,36 @@ export function writeJsonConfig(abs, key, serverId, entry, opts) {
 /** The merge itself. Runs with the config file's lock held. */
 function mergeJsonConfig(abs, key, serverId, entry, opts) {
   const { approved, dryRun = false, root } = opts;
-  const { data, existed, error } = readJsonConfig(abs);
-  if (error) {
-    // A file we cannot parse is never rewritten.
-    return { status: 'skipped', detail: `not valid JSON (${error}) — left untouched`, path: abs };
+  const existed = existsSync(abs);
+  let raw = '';
+  if (existed) {
+    try {
+      raw = readFileSync(abs, 'utf8');
+    } catch (e) {
+      // An unreadable config is reported, never rewritten.
+      return { status: 'skipped', detail: `cannot read the config (${e.message}) — left untouched`, path: abs };
+    }
+  }
+  // A config that does not exist yet starts life as plain strict JSON; an
+  // existing one is merged in place, so a JSONC file keeps its comments.
+  const result = existed
+    ? mergeEntry(raw, key, serverId, entry)
+    : { text: JSON.stringify(nestedConfig(key, serverId, entry), null, 2) + '\n', changed: true };
+  if (result.reason) {
+    // A file we cannot merge into is never rewritten.
+    return { status: 'skipped', detail: `${result.reason} — left untouched`, path: abs };
   }
-  const obj = data && typeof data === 'object' && !Array.isArray(data) ? data : {};
-  const bucket = obj[key] && typeof obj[key] === 'object' && !Array.isArray(obj[key]) ? obj[key] : {};
-  const existing = bucket[serverId];
-  if (existing && JSON.stringify(existing) === JSON.stringify(entry)) {
+  if (!result.changed) {
     return { status: 'unchanged', path: abs };
   }
   // Approval gate: without approval nothing is written.
   if (dryRun || !approved) {
     return { status: 'planned', detail: dryRun ? 'would write (dry-run)' : 'would write (needs approval)', path: abs };
   }
-  bucket[serverId] = entry;
-  obj[key] = bucket;
   try {
     if (root) assertWithinRoot(root, abs);
     assertNotSymlink(abs);
-    writeFileAtomic(abs, JSON.stringify(obj, null, 2) + '\n', { root });
+    writeFileAtomic(abs, result.text, { root });
   } catch (e) {
     return { status: 'error', detail: e.message, path: abs };
   }
@@ -450,21 +484,30 @@ export function removeWiring(projectRoot, serverId, home = homedir(), location =
         }
         let next = start + 1;
         while (next < lines.length && !/^\s*\[/.test(lines[next])) next++;
-        writeFileAtomic(abs, [...lines.slice(0, start), ...lines.slice(next)].join('\n'), { root: projectRoot });
+        // A global config lives under the home directory, not the project —
+        // the same rule the JSON branch uses. With the project root here, the
+        // containment check REFUSED to uninstall a global Codex config.
+        const root = pathIsWithin(abs, projectRoot) ? projectRoot : home;
+        writeFileAtomic(abs, [...lines.slice(0, start), ...lines.slice(next)].join('\n'), { root });
         removed.push(abs);
       } else {
-        const { data } = readJsonConfig(abs);
-        if (!data || typeof data !== 'object') {
-          skipped.push(`${abs} (unreadable)`);
+        // The removal is textual for a JSONC config: re-serializing the
+        // parsed document would delete the user's comments.
+        let raw;
+        try {
+          raw = readFileSync(abs, 'utf8');
+        } catch (e) {
+          skipped.push(`${abs} (${e.message})`);
           continue;
         }
-        const bucket = data[entry.key];
-        if (!bucket || typeof bucket !== 'object' || !(serverId in bucket)) {
-          skipped.push(`${abs} (entry not found)`);
+        const result = removeEntry(raw, entry.key, serverId);
+        if (!result.changed) {
+          skipped.push(`${abs} (${result.reason ?? 'entry not found'})`);
           continue;
         }
-        delete bucket[serverId];
-        writeFileAtomic(abs, JSON.stringify(data, null, 2) + '\n', { root: projectRoot });
+        // A global config lives under the home directory, not the project.
+        const root = pathIsWithin(abs, projectRoot) ? projectRoot : home;
+        writeFileAtomic(abs, result.text, { root });
         removed.push(abs);
       }
     } catch (e) {