archgen-skill 0.0.6 → 0.1.0

package/lib/doctor.js

@@ -3,13 +3,13 @@
 // Verifies a project install: canonical store integrity, version stamp,
 // claude link resolution, managed blocks (exactly once each), and manifest
 // entry resolution. Safe issues are repaired in place unless --check is given
-// (report-only). Advisory FAIL rows (broken states only a human can fix) are
-// reported and counted in the summary but do NOT fail the run: the process
-// exits non-zero only when a repair operation itself throws.
+// (report-only). A FAIL row is a broken state a human must fix: it is
+// reported AND it fails the run (the process exits non-zero whenever any
+// FAIL row was produced).
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, readlinkSync, symlinkSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve, sep } from 'node:path';
 import { globalTargets } from './install.js';
 import {
   END,
@@ -22,7 +22,7 @@ import {
   upsertManagedFile,
 } from './block.js';
 import { resolveSkillSource } from './init.js';
-import { CLAUDE_LINK_REL, DEV_ONLY_RELPATHS, MANIFEST_REL, STORE_REL, VERSION_FILE, cliVersion, findObsolete, hashDir, loadManifest, pruneDevOnly, pruneObsolete, saveManifest } from './store.js';
+import { CLAUDE_LINK_REL, DEV_ONLY_RELPATHS, MANIFEST_REL, STORE_REL, VERSION_FILE, assertNotSymlink, assertWithinRoot, cliVersion, findObsolete, hashDir, loadManifest, pruneDevOnly, pruneObsolete, saveManifest } from './store.js';
 import { compareSemver, parseSemver } from './version.js';
 import { readStamp, writeStamp } from './version-stamp.js';
 import { mcpDoctor } from './mcp-server.js';
@@ -48,8 +48,7 @@ function relJoin(rel) {
  *   mutations; home overrides the homedir scanned for global installs (tests)
  * @returns {{root: string, checks: {status: 'OK'|'FIXED'|'WOULD-FIX'|'WARN'|'FAIL', msg: string}[],
  *            tally: Record<string, number>, failures: number}} `failures` counts
- *   repair operations that THEMSELVES threw — advisory FAIL rows are reported
- *   but never fail the run.
+ *   the FAIL rows — a broken state a human must fix always fails the run.
  */
 export function doctorProject(projectDir, packageRoot, opts = {}) {
   const root = resolve(projectDir);
@@ -57,16 +56,20 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
   const homeDir = opts.home ?? homedir();
   const version = cliVersion(packageRoot);
   const checks = [];
-  const add = (status, msg) => checks.push({ status, msg });
-  let opFailures = 0;
+  let failures = 0;
+  // A FAIL row is a broken state a human must fix, so it MUST fail the run:
+  // the counter below is what the CLI turns into a non-zero exit code.
+  const add = (status, msg) => {
+    checks.push({ status, msg });
+    if (status === 'FAIL') failures++;
+  };
   // Run one repair step; a throw becomes a FAIL row instead of aborting the
-  // whole doctor pass (and is the only thing that flips the exit code).
+  // whole doctor pass.
   const attempt = (fn, okStatus, okMsg, failLabel) => {
     try {
       fn();
       add(okStatus, okMsg);
     } catch (e) {
-      opFailures++;
       add('FAIL', `${failLabel}: ${e.message} - fix manually`);
     }
   };
@@ -93,9 +96,27 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
     })();
     if (packaged) {
       // --check reports WITHOUT mutating; repair mode prunes.
-      const obsolete = checkOnly ? findObsolete(storeAbs, packaged) : pruneObsolete(storeAbs, packaged);
-      for (const rel of obsolete) {
-        add(checkOnly ? 'WOULD-FIX' : 'FIXED', `store carried the obsolete ${rel}/ tree (pre-MCP layout) -> ${checkOnly ? 'would prune' : 'pruned'}`);
+      const obsolete = findObsolete(storeAbs, packaged);
+      if (obsolete.length > 0) {
+        if (checkOnly) {
+          for (const rel of obsolete) {
+            add('WOULD-FIX', `store carried the obsolete ${rel}/ tree (pre-MCP layout) -> would prune`);
+          }
+        } else {
+          // Pruning DELETES inside the store: refuse when the store (or one of
+          // its parents) is a symlink — the prune would otherwise reach
+          // outside the project through the link.
+          try {
+            assertNotSymlink(storeAbs);
+            assertWithinRoot(root, storeAbs);
+            pruneObsolete(storeAbs, packaged);
+            for (const rel of obsolete) {
+              add('FIXED', `store carried the obsolete ${rel}/ tree (pre-MCP layout) -> pruned`);
+            }
+          } catch (e) {
+            add('FAIL', `cannot prune the obsolete store tree: ${e.message} - fix manually`);
+          }
+        }
       }
     }
     const missingCore = ['references'].filter((d) => !existsSync(join(storeAbs, d)));
@@ -124,7 +145,12 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
       if (checkOnly) {
         add('WOULD-FIX', `store carries dev-only ${devOnlyPresent.join(', ')} -> pruned`);
       } else {
-        attempt(() => pruneDevOnly(storeAbs), 'FIXED',
+        // Same rule as the obsolete prune: never delete through a symlink.
+        attempt(() => {
+          assertNotSymlink(storeAbs);
+          assertWithinRoot(root, storeAbs);
+          pruneDevOnly(storeAbs);
+        }, 'FIXED',
           `dev-only ${devOnlyPresent.join(', ')} pruned from store`, 'cannot prune dev-only artifacts');
       }
     }
@@ -152,6 +178,10 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
       return;
     }
     try {
+      // Escape check FIRST, exactly as init does: a symlinked .claude/
+      // .claude/skills parent must not redirect the recreated link outside
+      // the project root.
+      assertWithinRoot(root, dirname(claudeAbs));
       try { unlinkSync(claudeAbs); } catch { /* absent */ }
       mkdirSync(dirname(claudeAbs), { recursive: true });
       symlinkSync('../../.agents/skills/archgen', claudeAbs);
@@ -184,60 +214,66 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
         'AGENTS.md created with managed block', 'cannot create AGENTS.md managed block');
     }
   } else {
-    let raw = readFileSync(agentsAbs, 'utf8');
-    const starts = countOccurrences(raw, START);
-    const ends = countOccurrences(raw, END);
-    if (starts === 0 && ends === 0) {
-      if (checkOnly) add('WOULD-FIX', 'AGENTS.md has no archgen block -> added');
-      else {
-        attempt(() => upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')), 'FIXED',
-          'AGENTS.md managed block added', 'cannot add AGENTS.md managed block');
-      }
-    } else if (starts > 1 || ends > 1) {
-      add('FAIL', `AGENTS.md has ${starts} start / ${ends} end markers - fix manually`);
-    } else if (starts === 0 || ends === 0 || raw.indexOf(START) > raw.indexOf(END)) {
-      // Orphan/inverted markers: repairing through upsertBlock would throw, so
-      // classify as FAIL instead of attempting the write.
-      add('FAIL', 'AGENTS.md has broken archgen markers - fix manually');
-    } else {
-      // Block-format currency: an unversioned or older-stamped managed block is
-      // upgraded in place through the normal upsert path (everything outside the
-      // markers survives byte-for-byte by design). Newer stamps are left alone.
-      const det = detectBlockVersion(raw);
-      const parsed = det.version ? parseSemver(det.version) : null;
-      const stale = !det.present || !parsed || compareSemver(det.version, version) < 0;
-      if (stale) {
-        const from = det.version ? 'v' + det.version : 'unversioned';
-        if (checkOnly) {
-          add('WOULD-FIX', `WOULD-UPGRADE: AGENTS.md block ${from} -> v${version}`);
-        } else {
-          let upgraded = false;
-          attempt(() => { upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')); upgraded = true; },
-            'FIXED', `UPGRADED: AGENTS.md block ${from} -> v${version}`, 'cannot upgrade AGENTS.md block');
-          if (upgraded) raw = readFileSync(agentsAbs, 'utf8');
-        }
-      }
-      const fsCount = countOccurrences(raw, FEATURES_START);
-      const feCount = countOccurrences(raw, FEATURES_END);
-      const fsIdx = raw.indexOf(FEATURES_START);
-      const feIdx = raw.indexOf(FEATURES_END);
-      if (fsCount === 1 && feCount === 1 && fsIdx < feIdx) {
-        add('OK', 'AGENTS.md block + features registry present');
-      } else if (fsCount === 1 && feCount === 1) {
-        // Counts are right but ORDER is inverted (end before start): any
-        // registry write would throw (upsertFeaturesRegistry requires
-        // end > start), so flag the state instead of blessing it as OK.
-        if (checkOnly) add('WOULD-FIX', 'AGENTS.md archgen:features markers are reversed -> swap them');
-        else add('FAIL', 'AGENTS.md archgen:features markers are reversed - fix manually');
-      } else if (fsCount === 0 && feCount === 0) {
-        if (checkOnly) add('WOULD-FIX', 'AGENTS.md missing features registry -> inserted');
+    // An unreadable managed file is a FAIL row, not a reason to abort the
+    // whole doctor pass.
+    try {
+      let raw = readFileSync(agentsAbs, 'utf8');
+      const starts = countOccurrences(raw, START);
+      const ends = countOccurrences(raw, END);
+      if (starts === 0 && ends === 0) {
+        if (checkOnly) add('WOULD-FIX', 'AGENTS.md has no archgen block -> added');
         else {
-          attempt(() => upsertFeaturesRegistry(agentsAbs, []), 'FIXED',
-            'AGENTS.md features registry inserted', 'cannot insert AGENTS.md features registry');
+          attempt(() => upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')), 'FIXED',
+            'AGENTS.md managed block added', 'cannot add AGENTS.md managed block');
         }
+      } else if (starts > 1 || ends > 1) {
+        add('FAIL', `AGENTS.md has ${starts} start / ${ends} end markers - fix manually`);
+      } else if (starts === 0 || ends === 0 || raw.indexOf(START) > raw.indexOf(END)) {
+        // Orphan/inverted markers: repairing through upsertBlock would throw, so
+        // classify as FAIL instead of attempting the write.
+        add('FAIL', 'AGENTS.md has broken archgen markers - fix manually');
       } else {
-        add('FAIL', 'AGENTS.md has broken archgen:features markers - fix manually');
+        // Block-format currency: an unversioned or older-stamped managed block is
+        // upgraded in place through the normal upsert path (everything outside the
+        // markers survives byte-for-byte by design). Newer stamps are left alone.
+        const det = detectBlockVersion(raw);
+        const parsed = det.version ? parseSemver(det.version) : null;
+        const stale = !det.present || !parsed || compareSemver(det.version, version) < 0;
+        if (stale) {
+          const from = det.version ? 'v' + det.version : 'unversioned';
+          if (checkOnly) {
+            add('WOULD-FIX', `WOULD-UPGRADE: AGENTS.md block ${from} -> v${version}`);
+          } else {
+            let upgraded = false;
+            attempt(() => { upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')); upgraded = true; },
+              'FIXED', `UPGRADED: AGENTS.md block ${from} -> v${version}`, 'cannot upgrade AGENTS.md block');
+            if (upgraded) raw = readFileSync(agentsAbs, 'utf8');
+          }
+        }
+        const fsCount = countOccurrences(raw, FEATURES_START);
+        const feCount = countOccurrences(raw, FEATURES_END);
+        const fsIdx = raw.indexOf(FEATURES_START);
+        const feIdx = raw.indexOf(FEATURES_END);
+        if (fsCount === 1 && feCount === 1 && fsIdx < feIdx) {
+          add('OK', 'AGENTS.md block + features registry present');
+        } else if (fsCount === 1 && feCount === 1) {
+          // Counts are right but ORDER is inverted (end before start): any
+          // registry write would throw (upsertFeaturesRegistry requires
+          // end > start), so flag the state instead of blessing it as OK.
+          if (checkOnly) add('WOULD-FIX', 'AGENTS.md archgen:features markers are reversed -> swap them');
+          else add('FAIL', 'AGENTS.md archgen:features markers are reversed - fix manually');
+        } else if (fsCount === 0 && feCount === 0) {
+          if (checkOnly) add('WOULD-FIX', 'AGENTS.md missing features registry -> inserted');
+          else {
+            attempt(() => upsertFeaturesRegistry(agentsAbs, []), 'FIXED',
+              'AGENTS.md features registry inserted', 'cannot insert AGENTS.md features registry');
+          }
+        } else {
+          add('FAIL', 'AGENTS.md has broken archgen:features markers - fix manually');
+        }
       }
+    } catch (e) {
+      add('FAIL', 'cannot read AGENTS.md: ' + e.message + ' - fix manually');
     }
   }
 
@@ -249,18 +285,44 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
         'CLAUDE.md created with @AGENTS.md bridge', 'cannot create CLAUDE.md bridge');
     }
   } else {
-    const raw = readFileSync(claudeMdAbs, 'utf8');
-    const body = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
-    const imports = body.split(/\r?\n/).some((l) => l.trim() === '@AGENTS.md');
-    const starts = countOccurrences(raw, START);
-    const ends = countOccurrences(raw, END);
-    if (imports && starts <= 1 && ends <= 1) add('OK', 'CLAUDE.md bridges to AGENTS.md');
-    else if (starts > 1 || ends > 1) add('FAIL', 'CLAUDE.md has multiple archgen blocks - fix manually');
-    else if (starts !== ends) add('FAIL', 'CLAUDE.md has broken archgen markers - fix manually');
-    else if (checkOnly) add('WOULD-FIX', 'CLAUDE.md missing @AGENTS.md bridge -> written');
-    else {
-      attempt(() => upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]), 'FIXED',
-        'CLAUDE.md @AGENTS.md bridge written', 'cannot write CLAUDE.md bridge');
+    // An unreadable managed file is a FAIL row, not a reason to abort the
+    // whole doctor pass.
+    let raw = null;
+    try {
+      raw = readFileSync(claudeMdAbs, 'utf8');
+    } catch (e) {
+      add('FAIL', 'cannot read CLAUDE.md: ' + e.message + ' - fix manually');
+    }
+    if (raw !== null) {
+      const body = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+      const imports = body.split(/\r?\n/).some((l) => l.trim() === '@AGENTS.md');
+      const starts = countOccurrences(raw, START);
+      const ends = countOccurrences(raw, END);
+      if (starts > 1 || ends > 1) add('FAIL', 'CLAUDE.md has multiple archgen blocks - fix manually');
+      else if (starts !== ends) add('FAIL', 'CLAUDE.md has broken archgen markers - fix manually');
+      else if (starts === 1) {
+        // The managed block is ours: keep its provenance stamp current, the
+        // same way the AGENTS.md block is kept current.
+        const det = detectBlockVersion(raw);
+        const parsed = det.version ? parseSemver(det.version) : null;
+        const stale = !det.present || !parsed || compareSemver(det.version, version) < 0;
+        if (stale) {
+          const from = det.version ? 'v' + det.version : 'unversioned';
+          if (checkOnly) {
+            add('WOULD-FIX', `WOULD-UPGRADE: CLAUDE.md block ${from} -> v${version}`);
+          } else {
+            attempt(() => upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]), 'FIXED',
+              `UPGRADED: CLAUDE.md block ${from} -> v${version}`, 'cannot upgrade CLAUDE.md block');
+          }
+        } else {
+          add('OK', 'CLAUDE.md bridges to AGENTS.md');
+        }
+      } else if (imports) add('OK', 'CLAUDE.md bridges to AGENTS.md');
+      else if (checkOnly) add('WOULD-FIX', 'CLAUDE.md missing @AGENTS.md bridge -> written');
+      else {
+        attempt(() => upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]), 'FIXED',
+          'CLAUDE.md @AGENTS.md bridge written', 'cannot write CLAUDE.md bridge');
+      }
     }
   }
 
@@ -271,8 +333,23 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
   if (!manifest) {
     if (existsSync(storeAbs)) add('WARN', `no install manifest at ${MANIFEST_REL} (re-run init to regenerate)`);
     else add('OK', 'no manifest (nothing installed)');
+  } else if (!Array.isArray(manifest.entries)) {
+    // A manifest without an entries array is malformed: report it instead of
+    // crashing the whole doctor pass on it.
+    add('FAIL', `manifest ${MANIFEST_REL} has no entries array - fix manually`);
   } else {
-    const resolves = (e) => e && typeof e.path === 'string' && existsSync(join(root, ...e.path.split('/')));
+    // An entry only "resolves" when its path stays inside the project root:
+    // a manifest path like `../../etc/passwd` must never count as resolved.
+    const entryAbs = (rel) => {
+      if (typeof rel !== 'string' || rel === '') return null;
+      const abs = resolve(root, ...rel.split('/'));
+      if (abs !== root && !abs.startsWith(root + sep)) return null;
+      return abs;
+    };
+    const resolves = (e) => {
+      const abs = entryAbs(e && e.path);
+      return abs !== null && existsSync(abs);
+    };
     const stale = manifest.entries.filter((e) => !resolves(e));
     if (stale.length === 0) {
       add('OK', `manifest: all ${manifest.entries.length} entr${manifest.entries.length === 1 ? 'y' : 'ies'} resolve`);
@@ -286,9 +363,9 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
 
   // 7. Version-stamp inventory — every archgen skill tree visible from this
   //    project/machine, one line each, for tools that probe
-  //    <skillRoot>/.archgen-version (the VS Code extension reads it to warn
-  //    "skill outdated"). Report-only: doctor repairs the project stamp in
-  //    section 2, never global installs.
+  //    <skillRoot>/.archgen-version (the MCP server reads it to report the
+  //    installed skill's version). Report-only: doctor repairs the project
+  //    stamp in section 2, never global installs.
   const seen = new Set();
   const installs = [];
   const noteInstall = (p) => {
@@ -341,5 +418,5 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
 
   const tally = { OK: 0, FIXED: 0, 'WOULD-FIX': 0, WARN: 0, FAIL: 0 };
   for (const c of checks) tally[c.status]++;
-  return { root, checks, tally, failures: opFailures };
+  return { root, checks, tally, failures };
 }

package/lib/global-server.js

@@ -0,0 +1,154 @@
+// global-server.js — ONE archgen MCP server for every harness, kept current.
+//
+// WHY A GLOBAL INSTALL.
+//
+// The harness configs name the server's executable by ABSOLUTE PATH, so the
+// path has to keep working. The npx fallback points into npm's npx CACHE
+// (~/.npm/_npx/<hash>/…), which `npm cache clean --force` removes — and the
+// harness then fails to start a server that was wired minutes earlier.
+//
+// A global install (`npm install -g archgen-mcp`) puts the binary in the
+// npm prefix's bin directory: one copy, shared by every harness, at a path
+// that does not move when the registry publishes a new version.
+//
+// THE UPGRADE.
+//
+// The CLI and the server are released TOGETHER, so the CLI knows exactly
+// which server version it was tested against. An installed server that is
+// OLDER is refreshed to that version; one that is NEWER (a dev build, or a
+// version published after this CLI) is left alone — downgrading it would
+// break a working setup.
+//
+// The install is BEST EFFORT. A machine without a writable npm prefix, an
+// offline machine, or a user who does not want a global package must still
+// get a working skill install: the npx fallback covers all of them, and the
+// OLD server keeps working until it is replaced.
+import { spawnSync } from 'node:child_process';
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { npmInvocation, whichOnPath } from './spawn-npm.js';
+import { compareSemver } from './version.js';
+
+export const MCP_PACKAGE = 'archgen-mcp';
+
+/**
+ * The version of the server this CLI ships with.
+ *
+ * The CLI and the server are released together, so the installer can ask for
+ * exactly the version it was tested against instead of "whatever is latest".
+ *
+ * @param {string} packageRoot the CLI's own package root
+ * @returns {string}
+ */
+export function serverVersion(packageRoot) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : 'latest';
+  } catch {
+    return 'latest';
+  }
+}
+
+/**
+ * The version of an INSTALLED server, read from its own package.
+ *
+ * The binary is a symlink into the global package's bin directory, so the
+ * package root is one level above the script's directory.
+ *
+ * @param {string} bin the resolved executable
+ * @returns {string|null} the version, or null when it cannot be read
+ */
+export function installedServerVersion(bin) {
+  try {
+    const real = realpathSync(bin);
+    const pkg = JSON.parse(readFileSync(join(dirname(real), '..', 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Make sure `archgen-mcp` is installed globally, at the right version.
+ *
+ * @param {{env?: Record<string, string|undefined>, version?: string}} opts
+ * @returns {{installed: boolean, bin: string|null, upgraded: boolean,
+ *   note: string, detail?: string}}
+ */
+export function ensureGlobalServer(opts = {}) {
+  const { env = process.env, version = 'latest' } = opts;
+
+  const onPath = whichOnPath(MCP_PACKAGE, env);
+  if (onPath) {
+    const installed = installedServerVersion(onPath);
+    if (installed === version) {
+      return {
+        installed: true,
+        bin: onPath,
+        upgraded: false,
+        note: `already installed at ${onPath} (v${installed})`,
+      };
+    }
+    if (installed && version !== 'latest' && compareSemver(installed, version) > 0) {
+      // A newer server is already there — a dev build, or a release published
+      // after this CLI. Downgrading it would break a working setup.
+      return {
+        installed: true,
+        bin: onPath,
+        upgraded: false,
+        note: `installed v${installed} is newer than this CLI's v${version} — left as it is`,
+      };
+    }
+    const refreshed = installGlobal(version, env);
+    if (refreshed.installed) {
+      return {
+        installed: true,
+        bin: refreshed.bin,
+        upgraded: true,
+        note: `upgraded the archgen MCP server to v${version} at ${refreshed.bin}`,
+      };
+    }
+    // The upgrade failed — the OLD server still works, so keep it and say so.
+    return {
+      installed: true,
+      bin: onPath,
+      upgraded: false,
+      note: `could not upgrade the archgen MCP server to v${version} — the installed v${installed} stays`,
+      detail: refreshed.detail,
+    };
+  }
+
+  const fresh = installGlobal(version, env);
+  return {
+    installed: fresh.installed,
+    bin: fresh.bin,
+    upgraded: false,
+    note: fresh.installed
+      ? `installed the archgen MCP server globally at ${fresh.bin}`
+      : `could not install the archgen MCP server globally — the npx fallback will be used`,
+    detail: fresh.detail,
+  };
+}
+
+/** `npm install -g archgen-mcp@<version>`. */
+function installGlobal(version, env) {
+  const spec = version === 'latest' ? MCP_PACKAGE : `${MCP_PACKAGE}@${version}`;
+  const inv = npmInvocation(['install', '-g', spec], env);
+  const r = spawnSync(inv.command, inv.args, {
+    encoding: 'utf8',
+    timeout: 300000,
+    env,
+    shell: inv.shell,
+  });
+  if (r.status !== 0) {
+    const detail = (r.stderr || r.stdout || '').trim().split('\n').pop();
+    return { installed: false, bin: null, detail: detail || `npm exited ${r.status}` };
+  }
+  // npm succeeded — but the install only COUNTS if the binary is now
+  // findable. A prefix that is not on PATH, or a package that shipped no
+  // bin, would otherwise be reported as a success.
+  const bin = whichOnPath(MCP_PACKAGE, env);
+  return bin
+    ? { installed: true, bin, detail: undefined }
+    : { installed: false, bin: null, detail: 'npm reported success but the binary is not on PATH' };
+}

package/lib/init.js

@@ -20,7 +20,7 @@
 import { cpSync, existsSync, lstatSync, mkdirSync, readlinkSync, renameSync, rmSync, symlinkSync, unlinkSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
-import { importsAgents, renderBlock, START, END, upsertManagedFile } from './block.js';
+import { importsAgents, hasManagedBlock, renderBlock, START, END, upsertManagedFile } from './block.js';
 import { CLAUDE_LINK_REL, STORE_REL, VERSION_FILE, appendEntry, assertNotSymlink, assertWithinRoot, cliVersion, hashDir, moveToBackup, pruneDevOnly } from './store.js';
 import { writeStamp } from './version-stamp.js';
 import { bootstrapServers } from './bootstrap.js';
@@ -57,6 +57,12 @@ function relJoin(rel) {
 function installClaudeAdapter(root, source, warnings) {
   const claudeAbs = join(root, relJoin(CLAUDE_LINK_REL));
   const storeAbs = join(root, relJoin(STORE_REL));
+
+  // Escape check FIRST — before anything is removed or created: a symlinked
+  // .claude/.claude/skills parent must not redirect the adapter (nor the
+  // removal of a legacy copy) outside the project root.
+  assertWithinRoot(root, dirname(claudeAbs));
+
   const st = lstatSafe(claudeAbs);
   let migrating = false;
 
@@ -81,9 +87,6 @@ function installClaudeAdapter(root, source, warnings) {
     return 'kept-divergent';
   }
 
-  // Escape check: a symlinked .claude/.claude/skills parent must not redirect
-  // the adapter creation outside the project root.
-  assertWithinRoot(root, claudeAbs);
   try {
     mkdirSync(dirname(claudeAbs), { recursive: true });
     symlinkSync('../../.agents/skills/archgen', claudeAbs);
@@ -134,21 +137,44 @@ export function initProject(projectDir, packageRoot, opts = {}) {
 
   // 1. Canonical store — fingerprint before mutating (ownership check).
   const prev = lstatSafe(storeAbs);
-  if (prev) {
-    const identical = prev.isDirectory() && !prev.isSymbolicLink()
-      && hashDir(storeAbs, { ignore: [VERSION_FILE] }) === hashDir(source);
-    if (!identical) backups.push(moveToBackup(root, STORE_REL));
-  }
+  const identical = !!(prev && prev.isDirectory() && !prev.isSymbolicLink()
+    && hashDir(storeAbs, { ignore: [VERSION_FILE] }) === hashDir(source));
 
-  // Atomic install: build in a temp sibling dir, then rename into place.
+  // Atomic install: build in a temp sibling dir, then swap it into place.
+  // The current store is renamed aside (identical) or moved into the backup
+  // vault (divergent) so the swap can be undone: a failed swap puts the old
+  // store back, and a failed copy never leaves an orphan temp directory.
   const skillsParent = dirname(storeAbs);
   mkdirSync(skillsParent, { recursive: true });
   const tmp = join(skillsParent, '.archgen-tmp-' + randomBytes(6).toString('hex'));
-  cpSync(source, tmp, { recursive: true });
-  pruneDevOnly(tmp); // dev-only artifacts (scripts/test) never reach the installed store
-  writeStamp(tmp, version);
-  rmSync(storeAbs, { recursive: true, force: true });
-  renameSync(tmp, storeAbs);
+  const aside = join(skillsParent, '.archgen-old-' + randomBytes(6).toString('hex'));
+  let asideUsed = false;
+  try {
+    cpSync(source, tmp, { recursive: true });
+    pruneDevOnly(tmp); // dev-only artifacts (scripts/test) never reach the installed store
+    writeStamp(tmp, version);
+    if (lstatSafe(storeAbs)) {
+      if (identical) {
+        renameSync(storeAbs, aside);
+        asideUsed = true;
+      } else {
+        backups.push(moveToBackup(root, STORE_REL));
+      }
+    }
+    renameSync(tmp, storeAbs);
+  } catch (e) {
+    if (asideUsed) {
+      // Put the previous store back: a failed swap must never leave the
+      // project without a store.
+      try {
+        renameSync(aside, storeAbs);
+        asideUsed = false;
+      } catch { /* keep it aside rather than deleting the user's data */ }
+    }
+    rmSync(tmp, { recursive: true, force: true });
+    throw e;
+  }
+  if (asideUsed) rmSync(aside, { recursive: true, force: true });
   appendEntry(root, 'dir', STORE_REL);
 
   // 2. Claude adapter — relative symlink, never a second copy.
@@ -159,7 +185,10 @@ export function initProject(projectDir, packageRoot, opts = {}) {
   const createdContextFiles = [];
   for (const name of CONTEXT_FILES) {
     const abs = join(root, name);
-    if (name === 'CLAUDE.md' && importsAgents(abs)) {
+    // A hand-written `@AGENTS.md` import is the user's — leave it alone. A
+    // managed block is ours: refresh it so its provenance stamp tracks the
+    // running CLI instead of freezing at the first-ever install.
+    if (name === 'CLAUDE.md' && !hasManagedBlock(abs) && importsAgents(abs)) {
       warnings.push('CLAUDE.md already imports @AGENTS.md - skipped (already-imports)');
       continue;
     }
@@ -176,10 +205,17 @@ export function initProject(projectDir, packageRoot, opts = {}) {
   //    harness AND ensure CodeGraph (its CLI, its MCP entry, the project
   //    index). Non-fatal by design: an offline machine still gets the skill
   //    installed.
+  //
+  //    The wiring is GLOBAL by default: the server is one binary for every
+  //    harness, and the harness configs live in the user's home. A project
+  //    that carries its own `.mcp.json`, `.codex/` and `.gemini/` is a
+  //    project that has to be re-wired in every clone. `--location project`
+  //    opts into the per-project wiring.
   if (codegraphAllowed || mcpAllowed) {
     const r = bootstrapServers({
       projectDir: root,
-      location: 'both',
+      packageRoot: packageRoot,
+      location: opts.location ?? 'global',
       log,
       env: opts.env,
       noCodegraph: !codegraphAllowed,