create-claude-cabinet 0.46.0 → 0.48.0

package/lib/copy.js

@@ -50,17 +50,145 @@ 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 };
+}
+
+/**
+ * Pure ownership classifier for a SINGLE incoming template file — the
+ * non-interactive install cascade in one place (elegance-0002, act:a6377c82).
+ *
+ * The rule cascade below is the same one the walkAndCopy directory walk runs
+ * inline; cli.js's single-file install branch had hand-inlined a copy of it
+ * and the copy had already drifted — it was MISSING the project-owned-seed
+ * guard (step 1), so the single-file path could adopt/clobber a consumer
+ * overlay. Making cli.js delegate to this function removes that "kept in step
+ * by comments" fragility for the single-file path; the shared RULES
+ * (isProjectOwnedSeed, freezeRetain, recordSkip's omission semantics) already
+ * live in one place and are reused here.
+ *
+ * Order matches walkAndCopy exactly: seed → customized-phase → identical →
+ * frozen-hold → skipConflicts(manifest-driven) → interactive-prompt. Purely a
+ * decision — the caller performs all I/O, counter, and logging side effects.
+ *
+ * @returns {{ action: string, manifest: 'omit'|'identical'|'frozen'|'hash'|null, manifestHash?: string }}
+ *   action ∈ 'seed' | 'preserve-phase' | 'skip-identical' | 'freeze-hold' |
+ *            'freeze-hold-new' | 'overwrite' | 'skip-omit' | 'copy-new' | 'prompt'
+ */
+function classifyFileOwnership({
+  relPath,
+  destExists,
+  existingContent,
+  incoming,
+  isPhaseFile = false,
+  isInstructionPhase = false,
+  frozen = false,
+  isCcOwned = false,
+  skipConflicts = false,
+}) {
+  // 1. Project-owned seed — before any existsSync branch (act:2001bf54).
+  if (isProjectOwnedSeed(relPath)) {
+    return { action: 'seed', manifest: 'omit' };
+  }
+  if (destExists) {
+    // 2. Customized phase file → preserve (independent of skipPhases). Ahead
+    //    of the identical check to match the walk; behavior-identical since
+    //    identical content never trips this guard.
+    if (
+      isPhaseFile &&
+      !isInstructionPhase &&
+      existingContent.trim() !== '' &&
+      existingContent.trim() !== incoming.trim()
+    ) {
+      return { action: 'preserve-phase', manifest: 'omit' };
+    }
+    // 3. Byte-identical → skip, recorded as CC-owned-unchanged.
+    if (existingContent === incoming) {
+      return { action: 'skip-identical', manifest: 'identical' };
+    }
+    // 4. Frozen module (act:c1013967): hold a CC-owned file at its on-disk
+    //    hash; a project-owned file falls through.
+    if (frozen) {
+      const decision = freezeRetain({ existing: existingContent, isCcOwned });
+      if (decision.manifestHash) {
+        return { action: 'freeze-hold', manifest: 'frozen', manifestHash: decision.manifestHash };
+      }
+    }
+    // 5. Non-interactive install (--yes / existing-install): manifest-driven.
+    if (skipConflicts) {
+      return isCcOwned
+        ? { action: 'overwrite', manifest: 'hash' }
+        : { action: 'skip-omit', manifest: 'omit' };
+    }
+    // 6. Interactive → the caller prompts.
+    return { action: 'prompt', manifest: null };
+  }
+  // New file (dest absent): a frozen module holds it back; else copy.
+  if (frozen) return { action: 'freeze-hold-new', manifest: null };
+  return { action: 'copy-new', manifest: 'hash' };
+}
+
 /**
  * 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 +208,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 +261,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 +344,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 +391,4 @@ function showDiff(existing, incoming, relPath) {
   console.log('');
 }
 
-module.exports = { copyTemplates, recordSkip };
+module.exports = { copyTemplates, recordSkip, isProjectOwnedSeed, freezeRetain, classifyFileOwnership };

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

@@ -20,7 +20,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const crypto = require('crypto');
+const { sha256, compareVersions } = require('./installer-gate');
 
 const CC_HOME = path.join(os.homedir(), '.claude-cabinet');
 const GLOBAL_MANIFEST_PATH = path.join(CC_HOME, 'global-manifest.json');
@@ -42,22 +42,6 @@ const DATA_DIRS = [
   path.join(INSTALL_DIR, 'migrations'),
 ];
 
-function sha256(content) {
-  return crypto.createHash('sha256').update(content).digest('hex');
-}
-
-function compareVersions(a, b) {
-  const pa = a.split('.').map(Number);
-  const pb = b.split('.').map(Number);
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const va = pa[i] || 0;
-    const vb = pb[i] || 0;
-    if (va > vb) return 1;
-    if (va < vb) return -1;
-  }
-  return 0;
-}
-
 function readGlobalManifest() {
   if (!fs.existsSync(GLOBAL_MANIFEST_PATH)) return { files: {} };
   try {

package/lib/engagement-setup.js

@@ -177,7 +177,7 @@ function setupEngagement({ dryRun, projectDir } = {}) {
           target_fid    TEXT,
           packet_id     TEXT,
           kind          TEXT NOT NULL
-                          CHECK(kind IN ('client_feedback','status_push','delegation','approval','note','packet_sent','packet_opened')),
+                          CHECK(kind IN ('client_feedback','status_push','delegation','approval','note','packet_sent')),
           author        TEXT NOT NULL,
           verdict       TEXT CHECK(verdict IS NULL OR verdict IN ('approve','object','comment','none')),
           body          TEXT CHECK(body IS NULL OR length(body) <= 10000),

package/lib/installer-gate.js

@@ -0,0 +1,135 @@
+/**
+ * installer-gate.js — the SINGLE source of truth for the version/hash gate
+ * logic shared by CC's five runtime installers (mux, watchtower,
+ * engagement-server, verify, site-audit).
+ *
+ * Before this helper, `sha256()` was copy-pasted three times,
+ * `compareVersions()` twice, and the equal-version "don't hard-skip, fall
+ * through and copy only what changed" fix (act:df1a1dc3) was applied twice
+ * to the per-file-manifest installers while the two tarball installers
+ * (verify, site-audit) still hard-skipped on an equal version — so a
+ * template edit without a package.json bump never propagated. This module
+ * unifies all of it so the rule lives in one place ("one concept, one
+ * place"; technical-debt-0003, act:a6377c82).
+ *
+ * Two installer shapes delegate here:
+ *   - Per-file manifest (mux, watchtower, engagement-server): use `sha256`
+ *     + `compareVersions`; equal version falls through to a per-file
+ *     hash-compare in the caller.
+ *   - Tarball (verify, site-audit): npm-pack a runtime source dir into a
+ *     versioned tarball. `tarballIsStale` gives them the equal-version
+ *     fall-through — re-pack when the runtime SOURCE content changed even
+ *     though the version is identical, instead of hard-skipping.
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+/** SHA-256 hex digest of a string or Buffer. */
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Compare two dotted numeric version strings.
+ * @returns 1 if a > b, -1 if a < b, 0 if equal.
+ */
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const va = pa[i] || 0;
+    const vb = pb[i] || 0;
+    if (va > vb) return 1;
+    if (va < vb) return -1;
+  }
+  return 0;
+}
+
+/**
+ * Deterministic content hash of a source directory tree: every file's
+ * relative path + bytes, in a stable sorted order. Two trees with identical
+ * file contents hash identically regardless of readdir order. node_modules
+ * and .git are ignored (build/VCS artifacts, not source).
+ */
+function hashSourceDir(dir, { ignore = ['node_modules', '.git'] } = {}) {
+  const entries = [];
+  const walk = (d, rel) => {
+    const names = fs.readdirSync(d, { withFileTypes: true });
+    for (const ent of names) {
+      if (ignore.includes(ent.name)) continue;
+      const full = path.join(d, ent.name);
+      const r = rel ? `${rel}/${ent.name}` : ent.name;
+      if (ent.isDirectory()) walk(full, r);
+      else if (ent.isFile()) entries.push([r, fs.readFileSync(full)]);
+    }
+  };
+  walk(dir, '');
+  entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  const hash = crypto.createHash('sha256');
+  for (const [r, buf] of entries) {
+    hash.update(r);
+    hash.update('\0');
+    hash.update(buf);
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+const SOURCE_HASH_FILE = '.source-hash';
+
+/** Read the stored runtime-source hash sidecar from an install dir (or null). */
+function readSourceHash(installDir) {
+  try {
+    return fs.readFileSync(path.join(installDir, SOURCE_HASH_FILE), 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Persist the runtime-source hash sidecar next to the packed tarball. */
+function writeSourceHash(installDir, hash) {
+  fs.mkdirSync(installDir, { recursive: true });
+  fs.writeFileSync(path.join(installDir, SOURCE_HASH_FILE), hash, 'utf8');
+}
+
+/**
+ * Equal-version fall-through decision for the TARBALL installers.
+ *
+ * A tarball is stale (must re-pack) when it is missing/truncated OR when the
+ * runtime source content changed since it was last packed (the sidecar hash
+ * differs / is absent). Otherwise it is fresh and the caller may skip. This
+ * is what stops verify/site-audit from hard-skipping a same-version reinstall
+ * that carries a real template change.
+ *
+ * @returns {{ stale: boolean, sourceHash: string, reason: string }}
+ */
+function tarballIsStale({ tarballPath, installDir, runtimeSourceDir, minSize = 1024 }) {
+  const sourceHash = hashSourceDir(runtimeSourceDir);
+  let size = 0;
+  try {
+    size = fs.statSync(tarballPath).size;
+  } catch {
+    size = 0;
+  }
+  if (size <= minSize) {
+    return { stale: true, sourceHash, reason: size === 0 ? 'missing' : 'truncated' };
+  }
+  const stored = readSourceHash(installDir);
+  if (!stored) return { stale: true, sourceHash, reason: 'no-source-hash' };
+  if (stored !== sourceHash) return { stale: true, sourceHash, reason: 'source-changed' };
+  return { stale: false, sourceHash, reason: 'unchanged' };
+}
+
+module.exports = {
+  sha256,
+  compareVersions,
+  hashSourceDir,
+  readSourceHash,
+  writeSourceHash,
+  tarballIsStale,
+  SOURCE_HASH_FILE,
+};

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,
+};