create-claude-cabinet 0.45.0 → 0.47.0

package/lib/copy.js

@@ -50,17 +50,71 @@ function recordSkip(manifest, key, { identical = false, incomingHash = null } =
   }
 }
 
+/**
+ * Files shipped as STARTER content but owned by the project the moment they
+ * land. The installer seeds them if absent, NEVER overwrites them, and NEVER
+ * records them in the manifest. Manifest presence means "CC-owned", which has
+ * two consequences a project-owned file must avoid: cc-upstream-guard blocks
+ * edits to it, and a `--yes` reinstall silently overwrites it. The recordSkip
+ * "identical → keep tracked" rule is content-based and so still recorded an
+ * UNEDITED seed in the manifest — which false-blocked the very first edit (a
+ * project-owned file is unedited exactly until someone edits it). These files
+ * are project-owned by DECLARATION, not by content divergence.
+ *
+ * Keyed by basename: there is one such seed today and the src→dest relPath
+ * mapping varies by call site, so a basename match is the robust check.
+ * `directives-project.yaml`'s own header says it is "NOT overwritten by the
+ * installer ... extend upstream members with project-specific mandates" —
+ * recording it as CC-owned false-blocked the exact edits it exists to receive
+ * (field incident 2026-06-17, act:2001bf54).
+ */
+const PROJECT_OWNED_SEED_BASENAMES = new Set(['directives-project.yaml']);
+function isProjectOwnedSeed(relPath) {
+  return PROJECT_OWNED_SEED_BASENAMES.has(path.basename(relPath));
+}
+
+/**
+ * The canonical FREEZE rule for an EXISTING file in a frozen module that
+ * differs from the incoming template (act:c1013967). Shared by both copy
+ * paths — copy.js's directory walk and cli.js's single-file branch — so the
+ * "third ownership state" is defined in exactly one place (the recordSkip
+ * precedent).
+ *
+ * Freeze is "CC-owned but temporarily pinned": the file is NOT overwritten,
+ * and — crucially — only a file that is ALREADY CC-owned (present in the prior
+ * manifest) is RETAINED in the new manifest, at its ON-DISK hash. Two reasons
+ * the on-disk hash is the only correct choice:
+ *   - It keeps the file PRESENT in the manifest, so the upstream-cleanup loop
+ *     never lists it for deletion (a frozen file dropped from allManifest would
+ *     be deleted — the exact opposite of freeze).
+ *   - On-disk == recorded keeps the value-comparison consumers green:
+ *     cc-drift-check sees no drift, reset.js classifies it unmodified.
+ *
+ * A frozen-module file that differs but is NOT already CC-owned is
+ * project-owned (project-created or a kept/edited file deliberately omitted
+ * from the manifest). Freeze adds nothing for it — it's already never
+ * overwritten — so it must FALL THROUGH to the normal skip-and-omit path.
+ * RETAINING it would adopt a project-owned file into the manifest and clobber
+ * it on the unfreeze reinstall (violates the recordSkip invariant above).
+ *
+ * @returns {{manifestHash: string}}  retain at on-disk hash (CC-owned)
+ *        | {{omit: true}}            fall through to skip-and-omit (project-owned)
+ */
+function freezeRetain({ existing, isCcOwned }) {
+  return isCcOwned ? { manifestHash: hashContent(existing) } : { omit: true };
+}
+
 /**
  * Recursively copy files from src to dest, surfacing conflicts.
  * Returns { copied: string[], skipped: string[], overwritten: string[] }
  */
-async function copyTemplates(src, dest, { dryRun = false, skipConflicts = false, skipPhases = false, projectRoot = null, existingManifest = {}, instructionPhases = new Set() } = {}) {
-  const results = { copied: [], skipped: [], overwritten: [], manifest: {} };
-  await walkAndCopy(src, dest, src, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest, instructionPhases);
+async function copyTemplates(src, dest, { dryRun = false, skipConflicts = false, skipPhases = false, projectRoot = null, existingManifest = {}, instructionPhases = new Set(), frozen = false } = {}) {
+  const results = { copied: [], skipped: [], overwritten: [], manifest: {}, frozen: [] };
+  await walkAndCopy(src, dest, src, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest, instructionPhases, frozen);
   return results;
 }
 
-async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest, instructionPhases) {
+async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest, instructionPhases, frozen) {
   const entries = fs.readdirSync(currentSrc, { withFileTypes: true });
 
   for (const entry of entries) {
@@ -80,11 +134,32 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
       if (!dryRun && !fs.existsSync(destPath)) {
         fs.mkdirSync(destPath, { recursive: true });
       }
-      await walkAndCopy(srcRoot, destRoot, srcPath, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest, instructionPhases);
+      await walkAndCopy(srcRoot, destRoot, srcPath, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest, instructionPhases, frozen);
     } else {
       const incoming = fs.readFileSync(srcPath, 'utf8');
       const incomingHash = hashContent(incoming);
 
+      // Project-owned seed (act:2001bf54): seed if absent, never overwrite,
+      // and ALWAYS omit from the manifest — recording it would let
+      // cc-upstream-guard block edits and a --yes reinstall clobber the
+      // consumer's content. Runs before any existsSync branch so neither the
+      // byte-identical path (which would re-record an unedited seed) nor the
+      // manifest-driven overwrite path can reach it.
+      if (isProjectOwnedSeed(relPath)) {
+        if (!fs.existsSync(destPath)) {
+          if (!dryRun) {
+            const dir = path.dirname(destPath);
+            if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+            fs.copyFileSync(srcPath, destPath);
+          }
+          results.copied.push(relPath);
+        } else {
+          results.skipped.push(relPath);
+        }
+        recordSkip(results.manifest, relPath); // omit — project-owned by declaration
+        continue;
+      }
+
       if (fs.existsSync(destPath)) {
         const existing = fs.readFileSync(destPath, 'utf8');
 
@@ -112,6 +187,24 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
           continue;
         }
 
+        // Frozen module (act:c1013967): the file differs and is past the
+        // identical + seed + customized-phase guards, so it is a CC-managed
+        // file that WOULD be overwritten. Hold it instead. Only a file already
+        // CC-owned (in the prior manifest) is retained at its on-disk hash; a
+        // project-owned file falls through to the normal skip-and-omit path.
+        if (frozen) {
+          const manifestKey = projectRoot ? path.relative(projectRoot, destPath) : relPath;
+          const decision = freezeRetain({ existing, isCcOwned: Boolean(existingManifest[manifestKey]) });
+          if (decision.manifestHash) {
+            results.skipped.push(relPath);
+            results.frozen.push(relPath);
+            results.manifest[relPath] = decision.manifestHash;
+            console.log(`  ❄ Frozen (held): ${displayPath}`);
+            continue;
+          }
+          // decision.omit → project-owned; fall through.
+        }
+
         if (skipConflicts) {
           // Check if file is upstream-managed (in the old manifest).
           // If so, overwrite — it can't be customized (hook enforces this).
@@ -177,6 +270,15 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
           recordSkip(results.manifest, relPath);
         }
       } else {
+        // New file in a frozen module: hold it back so the on-disk module
+        // stays internally consistent at its pinned version. Report only — no
+        // manifest entry (there's no on-disk content to hash; a phantom entry
+        // would break cc-drift-check/cleanup). On unfreeze this branch creates it.
+        if (frozen) {
+          results.frozen.push(relPath);
+          console.log(`  ❄ Frozen (held new): ${displayPath}`);
+          continue;
+        }
         if (!dryRun) {
           const dir = path.dirname(destPath);
           if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -215,4 +317,4 @@ function showDiff(existing, incoming, relPath) {
   console.log('');
 }
 
-module.exports = { copyTemplates, recordSkip };
+module.exports = { copyTemplates, recordSkip, isProjectOwnedSeed, freezeRetain };

package/lib/db-setup.js

@@ -1,46 +1,151 @@
 const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const metadata = require('./metadata');
+
+// Substrings that identify a better-sqlite3 native-module ABI mismatch —
+// the compiled .node binary was built under a different Node than the one
+// running `pib-db.mjs init`. Node surfaces this as an ERR_DLOPEN_FAILED
+// with a NODE_MODULE_VERSION line; field reports during consumer walks
+// also showed the shorter "native module version mismatch" phrasing.
+const ABI_MISMATCH_SIGNATURES = [
+  'NODE_MODULE_VERSION',
+  'different Node.js version',
+  'was compiled against',
+  'native module version mismatch',
+  'ERR_DLOPEN_FAILED',
+];
+
+function isAbiMismatch(text) {
+  const s = String(text || '');
+  return ABI_MISMATCH_SIGNATURES.some((sig) => s.includes(sig));
+}
+
+// Read the bundled pib-db schema version from the (already-copied)
+// pib-db-lib.mjs as TEXT — never by importing it, so learning the version
+// does not itself load better-sqlite3. Returns a number, or null when the
+// file is missing or the constant can't be parsed.
+function readBundledSchemaVersion(scriptsDir) {
+  try {
+    const src = fs.readFileSync(path.join(scriptsDir, 'pib-db-lib.mjs'), 'utf8');
+    const m = src.match(/SCHEMA_VERSION\s*=\s*(\d+)/);
+    return m ? Number(m[1]) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Lazy-init gate: a reinstall whose recorded schema version already matches
+// the bundled one (and whose pib.db exists) needs no migration, so the init
+// step can be skipped entirely — and a skipped init never loads the
+// (possibly stale) native module. Conservative by construction: any
+// missing/unequal input returns false, so we only skip when certain there
+// is nothing to migrate.
+function shouldSkipInit({ dbExists, recordedVersion, bundledVersion }) {
+  return Boolean(
+    dbExists &&
+    bundledVersion != null &&
+    recordedVersion != null &&
+    recordedVersion === bundledVersion
+  );
+}
 
 /**
  * Set up the PIB database in the target project.
- * - Copies pib-db.mjs and schema to scripts/
+ * - Copies are already in place (scripts/ copied by the main install loop)
  * - Runs npm init if no package.json
- * - Installs better-sqlite3
- * - Runs pib-db init
+ * - Installs better-sqlite3 if absent
+ * - Initializes/migrates the database, UNLESS the schema is already current
+ *   (lazy-init), and self-heals an ABI-mismatched native binary.
+ *
+ * Returns { results: string[], schemaVersion: number|null }. schemaVersion
+ * is the applied (or confirmed-current) schema version when init succeeded
+ * or was correctly skipped, and null when init could not complete (ABI
+ * mismatch with no working rebuild) — so the caller never records a false
+ * "schema current" claim in .ccrc.json.
+ *
+ * `opts.exec` and `opts.log` are injectable for testing; they default to
+ * execSync and console.log.
  */
-function setupDb(projectDir) {
+function setupDb(projectDir, opts = {}) {
+  const exec = opts.exec || ((cmd, o) => execSync(cmd, o));
+  const log = opts.log || console.log;
   const scriptsDir = path.join(projectDir, 'scripts');
   const results = [];
 
   // Check if package.json exists; if not, init
   const pkgPath = path.join(projectDir, 'package.json');
   if (!fs.existsSync(pkgPath)) {
-    console.log('  Initializing package.json...');
-    execSync('npm init -y', { cwd: projectDir, stdio: 'pipe' });
+    log('  Initializing package.json...');
+    exec('npm init -y', { cwd: projectDir, stdio: 'pipe' });
     results.push('Created package.json');
   }
 
   // pib-db.mjs uses ESM imports — .mjs extension lets Node treat it as ESM
   // regardless of the project's package.json type field
+  const dbScript = path.join(scriptsDir, 'pib-db.mjs');
+  const dbPath = path.join(projectDir, 'pib.db');
+  const bundledVersion = readBundledSchemaVersion(scriptsDir);
+
+  // Lazy-init: skip when the schema is already current. This is the common
+  // reinstall case; skipping means a no-migration release never loads
+  // better-sqlite3, so a stale native binary can't wall the install with an
+  // ABI-mismatch error it never needed to risk.
+  const existingMeta = metadata.read(projectDir) || {};
+  if (
+    shouldSkipInit({
+      dbExists: fs.existsSync(dbPath),
+      recordedVersion: existingMeta.dbSchemaVersion,
+      bundledVersion,
+    })
+  ) {
+    results.push(`Database schema already current (v${bundledVersion}) — skipped init`);
+    return { results, schemaVersion: bundledVersion };
+  }
 
-  // Install better-sqlite3 if not already installed
+  // Install better-sqlite3 if not already installed. A pre-existing but
+  // stale binary is left for the rebuild path below to heal — a plain
+  // reinstall wouldn't change an already-satisfied semver.
   const nodeModules = path.join(projectDir, 'node_modules', 'better-sqlite3');
   if (!fs.existsSync(nodeModules)) {
-    console.log('  Installing better-sqlite3...');
-    execSync('npm install better-sqlite3', { cwd: projectDir, stdio: 'pipe' });
+    log('  Installing better-sqlite3...');
+    exec('npm install better-sqlite3', { cwd: projectDir, stdio: 'pipe' });
     results.push('Installed better-sqlite3');
   }
 
-  // Initialize the database
-  const dbScript = path.join(scriptsDir, 'pib-db.mjs');
-  if (fs.existsSync(dbScript)) {
-    console.log('  Initializing database...');
-    execSync(`node ${dbScript} init`, { cwd: projectDir, stdio: 'pipe' });
-    results.push('Initialized pib.db');
+  if (!fs.existsSync(dbScript)) {
+    return { results, schemaVersion: null };
   }
 
-  return results;
+  log('  Initializing database...');
+  try {
+    exec(`node ${dbScript} init`, { cwd: projectDir, stdio: 'pipe' });
+    results.push('Initialized pib.db');
+    return { results, schemaVersion: bundledVersion };
+  } catch (err) {
+    const detail = `${String(err.stderr || '')}\n${String(err.message || '')}`;
+    // Non-ABI failures keep their old handling — propagate to the caller's
+    // existing "Database setup failed" catch.
+    if (!isAbiMismatch(detail)) throw err;
+
+    // ABI mismatch: rebuild the native binary once and retry. If that
+    // works, the install self-heals. If it doesn't, fall back to a single
+    // actionable line — never a stack trace, never a silent skip.
+    log('  better-sqlite3 built for a different Node — rebuilding once and retrying...');
+    try {
+      exec('npm rebuild better-sqlite3', { cwd: projectDir, stdio: 'pipe' });
+      exec(`node ${dbScript} init`, { cwd: projectDir, stdio: 'pipe' });
+      results.push('Rebuilt better-sqlite3 (ABI mismatch) and initialized pib.db');
+      return { results, schemaVersion: bundledVersion };
+    } catch {
+      results.push(
+        'DB step skipped: better-sqlite3 was built for a different Node. Run ' +
+          '`npm rebuild better-sqlite3` then `node scripts/pib-db.mjs init` in ' +
+          'this project — your existing pib.db is untouched.'
+      );
+      return { results, schemaVersion: null };
+    }
+  }
 }
 
-module.exports = { setupDb };
+module.exports = { setupDb, isAbiMismatch, readBundledSchemaVersion, shouldSkipInit };

package/lib/engagement-server-setup.js

@@ -9,7 +9,10 @@
  *
  * Version semantics:
  *   - First install: copy all managed files, create data dir, write .cc-version
- *   - Same version: skip with log
+ *   - Same version: fall through to the SHA256 manifest hash-compare and
+ *     copy only files whose hashes differ (dogfood-from-source changes
+ *     templates without a version bump — equal-version must still
+ *     propagate; the manifest check makes this cheap and idempotent)
  *   - Newer CC version: upgrade managed files, preserve data dir
  *   - Older CC version than installed: skip (don't downgrade)
  */
@@ -23,6 +26,7 @@ const CC_HOME = path.join(os.homedir(), '.claude-cabinet');
 const GLOBAL_MANIFEST_PATH = path.join(CC_HOME, 'global-manifest.json');
 const INSTALL_DIR = path.join(CC_HOME, 'engagement-server');
 const VERSION_FILE = path.join(INSTALL_DIR, '.cc-version');
+const TEMPLATE_DIR = path.resolve(__dirname, '..', 'templates', 'engagement-server');
 
 const MANAGED_FILES = [
   'server.mjs',
@@ -99,7 +103,7 @@ function setupEngagementServer(opts = {}) {
   const results = [];
 
   const ccVersion = require('../package.json').version;
-  const templateDir = path.resolve(__dirname, '..', 'templates', 'engagement-server');
+  const templateDir = TEMPLATE_DIR;
 
   if (!fs.existsSync(templateDir)) {
     throw new Error(`engagement-server-setup: ${templateDir} not found.`);
@@ -109,15 +113,19 @@ function setupEngagementServer(opts = {}) {
 
   if (installedVersion) {
     const cmp = compareVersions(ccVersion, installedVersion);
-    if (cmp === 0) {
-      results.push(`engagement-server ${installedVersion} already installed — skipping`);
-      return { results, status: 'skipped' };
-    }
     if (cmp < 0) {
       results.push(`engagement-server ${installedVersion} is newer than CC ${ccVersion} — skipping (won't downgrade)`);
       return { results, status: 'skipped' };
     }
-    results.push(`Upgrading engagement-server from ${installedVersion} to ${ccVersion}`);
+    // Equal version (cmp === 0): do NOT early-return. Fall through to the
+    // SHA256 manifest hash-compare below — it copies only changed files,
+    // so a dogfood-from-source template edit propagates even without a
+    // package.json version bump. The hash-compare makes this idempotent.
+    if (cmp === 0) {
+      results.push(`engagement-server ${installedVersion} already installed — checking for changed files`);
+    } else {
+      results.push(`Upgrading engagement-server from ${installedVersion} to ${ccVersion}`);
+    }
   } else {
     results.push(`Installing engagement-server ${ccVersion}`);
   }
@@ -187,7 +195,24 @@ function setupEngagementServer(opts = {}) {
     results.push(`  Re-deploy: cd ${INSTALL_DIR} && railway up --detach`);
   }
 
-  return { results, status: installedVersion ? 'upgraded' : 'installed' };
+  let status;
+  if (!installedVersion) {
+    status = 'installed';
+  } else if (copiedCount > 0) {
+    status = 'upgraded';
+  } else {
+    // Equal-or-newer version, manifest already current — nothing to do.
+    status = 'unchanged';
+  }
+  return { results, status };
 }
 
-module.exports = { setupEngagementServer };
+// MANAGED_FILES, INSTALL_DIR, and TEMPLATE_DIR are exported for the
+// version-gate test so it can seed a faithful, complete global manifest
+// (single source of truth — the test never re-derives the file list).
+module.exports = {
+  setupEngagementServer,
+  MANAGED_FILES,
+  INSTALL_DIR,
+  TEMPLATE_DIR,
+};

package/lib/metadata.js

@@ -44,7 +44,7 @@ function merge(projectDir, partial) {
   return data;
 }
 
-function create(projectDir, { modules, skipped, version, manifest = {} }) {
+function create(projectDir, { modules, skipped, version, manifest = {}, dbSchemaVersion } = {}) {
   // Read existing first so unknown top-level keys (e.g.
   // `migrated_from_omega` set by --migrate-memory) survive the
   // install/upgrade rewrite. Only the install-specific fields below
@@ -60,6 +60,13 @@ function create(projectDir, { modules, skipped, version, manifest = {} }) {
     manifest,
   };
 
+  // Record the applied pib-db schema version when this install confirmed
+  // one (init ran or was skipped as already-current). When it didn't
+  // (--no-db, dry-run, or an unhealed ABI mismatch), `dbSchemaVersion` is
+  // undefined and any prior value rides through via `...existing` — we
+  // never claim "schema current" off the back of a skipped/failed init.
+  if (dbSchemaVersion != null) data.dbSchemaVersion = dbSchemaVersion;
+
   for (const mod of modules) {
     data.modules[mod] = true;
   }
@@ -71,4 +78,46 @@ function create(projectDir, { modules, skipped, version, manifest = {} }) {
   return data;
 }
 
-module.exports = { read, write, merge, create, metadataPath, METADATA_FILE };
+/**
+ * Read the project's frozen-module list from `.ccrc.json`. Returns a
+ * normalized, deduped `string[]` of module keys the operator has pinned
+ * (the temporary, manifest-RETAINING third ownership state — act:c1013967).
+ *
+ * Defensive by construction: a non-array `frozenModules` (shape drift) reads
+ * as "nothing frozen" rather than throwing, and a genuinely-absent `.ccrc.json`
+ * returns `[]`. It deliberately does NOT swallow a JSON parse error — `read()`
+ * throws on a malformed `.ccrc.json`, which HALTS the reinstall. That fail-
+ * closed behavior is the point: when the freeze state can't be read, the
+ * installer must stop, never proceed as if nothing were frozen (which would
+ * silently rewrite the very files a freeze exists to protect).
+ */
+function readFrozenModules(projectDir) {
+  const m = read(projectDir);
+  const raw = m && m.frozenModules;
+  if (!Array.isArray(raw)) return [];
+  return [...new Set(raw.filter((x) => typeof x === 'string'))];
+}
+
+/**
+ * Persist the frozen-module list, shallow-merged into `.ccrc.json` so every
+ * other field (manifest, modules, dbSchemaVersion, …) rides through. Input is
+ * normalized to a deduped string[]. Returns the written array.
+ */
+function setFrozenModules(projectDir, mods) {
+  const normalized = Array.isArray(mods)
+    ? [...new Set(mods.filter((x) => typeof x === 'string'))]
+    : [];
+  merge(projectDir, { frozenModules: normalized });
+  return normalized;
+}
+
+module.exports = {
+  read,
+  write,
+  merge,
+  create,
+  metadataPath,
+  METADATA_FILE,
+  readFrozenModules,
+  setFrozenModules,
+};

package/lib/migrate-from-omega.js

@@ -82,6 +82,13 @@ function stripUserPrefix(raw, homeDir) {
     const segs = tail.split('/');
     return segs.slice(1).join('/');
   }
+  // Omega project keys are historical strings recorded on whatever machine
+  // wrote them — a DB carried from a Mac to a Linux box (or exercised on a
+  // Linux CI runner) still holds /Users/<name>/... paths that the current
+  // machine's home root won't match. Recognize the conventional home roots
+  // structurally so cross-machine migrations classify instead of crashing.
+  const foreignHome = raw.match(/^\/(?:Users|home)\/[^/]+\/(.+)$/);
+  if (foreignHome) return foreignHome[1];
   return raw;
 }
 
@@ -100,7 +107,12 @@ function canonicalizeProjectKey(raw, ctx = {}) {
   const slugPath = stripUserPrefix(work, ctx.homeDir);
   const topSlug = slugPath.split('/')[0];
 
-  return { canonical: topSlug || null, kind: 'project' };
+  // kind 'project' with a null canonical is an incoherent contract — the
+  // bucketing consumer would key a cross-project map on null and crash on
+  // slug derivation. An unclassifiable key is unscoped, not a null project.
+  if (!topSlug) return { canonical: null, kind: 'unscoped' };
+
+  return { canonical: topSlug, kind: 'project' };
 }
 
 function resolveCurrentProject(cwd, homeDir) {

package/lib/mux-setup.js

@@ -8,7 +8,10 @@
  *
  * Version semantics:
  *   - First install: copy all managed files, write .cc-version
- *   - Same version: skip with log
+ *   - Same version: fall through to the SHA256 manifest hash-compare and
+ *     copy only files whose hashes differ (dogfood-from-source changes
+ *     templates without a version bump — equal-version must still
+ *     propagate; the manifest check makes this cheap and idempotent)
  *   - Newer CC version: upgrade managed files, preserve data dirs
  *   - Older CC version than installed: skip (don't downgrade)
  */
@@ -21,6 +24,7 @@ const crypto = require('crypto');
 const CC_HOME = path.join(os.homedir(), '.claude-cabinet');
 const GLOBAL_MANIFEST_PATH = path.join(CC_HOME, 'global-manifest.json');
 const MUX_VERSION_FILE = path.join(os.homedir(), '.config', 'mux', '.cc-version');
+const TEMPLATE_DIR = path.resolve(__dirname, '..', 'templates', 'mux');
 
 const MANAGED_FILES = [
   { src: 'bin/mux', dest: path.join(os.homedir(), '.local', 'bin', 'mux'), mode: 0o755 },
@@ -122,7 +126,7 @@ function setupMux(opts = {}) {
   const results = [];
 
   const ccVersion = require('../package.json').version;
-  const templateDir = path.resolve(__dirname, '..', 'templates', 'mux');
+  const templateDir = TEMPLATE_DIR;
 
   if (!fs.existsSync(templateDir)) {
     throw new Error(`mux-setup: ${templateDir} not found.`);
@@ -132,15 +136,19 @@ function setupMux(opts = {}) {
 
   if (installedVersion) {
     const cmp = compareVersions(ccVersion, installedVersion);
-    if (cmp === 0) {
-      results.push(`mux ${installedVersion} already installed — skipping`);
-      return { results, status: 'skipped' };
-    }
     if (cmp < 0) {
       results.push(`mux ${installedVersion} is newer than CC ${ccVersion} — skipping (won't downgrade)`);
       return { results, status: 'skipped' };
     }
-    results.push(`Upgrading mux from ${installedVersion} to ${ccVersion}`);
+    // Equal version (cmp === 0): do NOT early-return. Fall through to the
+    // SHA256 manifest hash-compare below — it copies only changed files,
+    // so a dogfood-from-source template edit propagates even without a
+    // package.json version bump. The hash-compare makes this idempotent.
+    if (cmp === 0) {
+      results.push(`mux ${installedVersion} already installed — checking for changed files`);
+    } else {
+      results.push(`Upgrading mux from ${installedVersion} to ${ccVersion}`);
+    }
   } else {
     results.push(`Installing mux ${ccVersion}`);
   }
@@ -200,7 +208,16 @@ function setupMux(opts = {}) {
     setupDarwinIntegration({ dryRun, results });
   }
 
-  return { results, status: installedVersion ? 'upgraded' : 'installed' };
+  let status;
+  if (!installedVersion) {
+    status = 'installed';
+  } else if (copiedCount > 0) {
+    status = 'upgraded';
+  } else {
+    // Equal-or-newer version, manifest already current — nothing to do.
+    status = 'unchanged';
+  }
+  return { results, status };
 }
 
 /**
@@ -308,4 +325,11 @@ function setupDarwinIntegration({ dryRun, results }) {
   }
 }
 
-module.exports = { setupMux };
+// MANAGED_FILES and TEMPLATE_DIR are exported for the version-gate test so it
+// can seed a faithful, complete global manifest (single source of truth — the
+// test never re-derives the file list).
+module.exports = {
+  setupMux,
+  MANAGED_FILES,
+  TEMPLATE_DIR,
+};