@microwiseai/snapshot 0.6.0 → 0.7.0

package/dist/commands/install.js

@@ -14,6 +14,10 @@ import { authorizeSession, packagesToSpecs } from '../lib/session.js';
 import { parallelInstall, recordToEntries } from '@microwiseai/snapshot-parallel';
 import { dedupWithReport, dedupInstallBlock, recordInstalledSpecs, recordReferences, computeReplacePlan, applyReplaceHistory, } from '@microwiseai/snapshot-dedup';
 import { createInterface } from 'readline';
+import { StepRecorder, buildLedger, writeLedger, queryDependencyTree, } from '../lib/ledger.js';
+import { coreFloorAssert, formatCoreFloorOffenders, DEFAULT_CORE_FLOOR_PKG, DEFAULT_CORE_FLOOR_MIN_VERSION, } from '../lib/core-floor.js';
+import { verifyInstallMap, runConverge, readInstalledNpmVersion, formatVerificationFailure, } from '../lib/install-verify.js';
+import { parsePins, applyPinOverrides, unmatchedOverrides, PinParseError, } from '../lib/pin-override.js';
 // CLI version — dynamically read from package.json (SSOT)
 import { createRequire } from 'module';
 const _require = createRequire(import.meta.url);
@@ -251,7 +255,7 @@ function isNpmGlobalInstalled(name, version) {
  * Skit 패키지 설치 (lib 우선, CLI fallback)
  * @ist/skit lib가 있으면 직접 호출, 없으면 CLI 사용
  */
-async function installSkitPackages(packages, snapshotName, indent, sessionId) {
+async function installSkitPackages(packages, snapshotName, indent, sessionId, recorder) {
     const result = { installed: [], failed: [] };
     const packageEntries = Object.entries(packages);
     if (packageEntries.length === 0) {
@@ -292,12 +296,20 @@ async function installSkitPackages(packages, snapshotName, indent, sessionId) {
     });
     result.installed.push(...parallelResult.installed);
     result.failed.push(...parallelResult.failed);
+    // S3 — record the skit install as one ordered step.
+    recorder?.record({
+        phase: 'skit',
+        installer: 'skit',
+        command: `skit install (${entries.length} skits)`,
+        specs: entries.map((e) => `${e.name}@${e.version}`),
+        result: result.failed.length > 0 ? 'failed' : 'ok',
+    });
     return result;
 }
 /**
  * 타입별 패키지 설치 (non-skit)
  */
-async function installPackagesByType(packages, installerName, installers, snapshotName, indent, typeLabel, sessionId) {
+async function installPackagesByType(packages, installerName, installers, snapshotName, indent, typeLabel, sessionId, recorder) {
     const result = { installed: [], failed: [] };
     const packageEntries = Object.entries(packages);
     if (packageEntries.length === 0) {
@@ -305,7 +317,7 @@ async function installPackagesByType(packages, installerName, installers, snapsh
     }
     // Skit packages use dedicated function
     if (installerName === 'skit') {
-        return installSkitPackages(packages, snapshotName, indent, sessionId);
+        return installSkitPackages(packages, snapshotName, indent, sessionId, recorder);
     }
     const installerConfig = installers[installerName] || DEFAULT_INSTALLERS[installerName];
     if (!installerConfig) {
@@ -355,6 +367,14 @@ async function installPackagesByType(packages, installerName, installers, snapsh
             const batchCommand = installerConfig.command.replace('{pkg}', specs.join(' '));
             console.log(chalk.gray(`${indent}  Running batch: npm install -g (${specs.length} packages)`));
             const success = runCommand(batchCommand);
+            // S3 — record the batch step (ok, or 'fallback' if it failed → retried below).
+            recorder?.record({
+                phase: 'layer-batch',
+                installer: installerName,
+                command: batchCommand,
+                specs,
+                result: success ? 'ok' : 'fallback',
+            });
             if (success) {
                 for (const spec of specs) {
                     console.log(`${indent}${chalk.blue('batch')} ${spec}...${chalk.green(' ✓')}`);
@@ -370,6 +390,13 @@ async function installPackagesByType(packages, installerName, installers, snapsh
                     const pkgSpec = `${entry.name}@${entry.version}`;
                     const command = installerConfig.command.replace('{pkg}', pkgSpec);
                     const ok = runCommand(command);
+                    recorder?.record({
+                        phase: 'layer-fallback',
+                        installer: installerName,
+                        command,
+                        specs: [pkgSpec],
+                        result: ok ? 'ok' : 'failed',
+                    });
                     if (ok) {
                         console.log(`${indent}${chalk.blue('fallback')} ${pkgSpec}...${chalk.green(' ✓')}`);
                         result.installed.push(pkgSpec);
@@ -404,15 +431,65 @@ async function installPackagesByType(packages, installerName, installers, snapsh
         });
         result.installed.push(...parallelResult.installed);
         result.failed.push(...parallelResult.failed);
+        // S3 — record the whole parallel (non-npm) install as one step.
+        recorder?.record({
+            phase: 'layer-parallel',
+            installer: installerName,
+            command: installerConfig.command.replace('{pkg}', '<each>'),
+            specs: entries.map((e) => `${e.name}@${e.version}`),
+            result: parallelResult.failed.length > 0 ? 'failed' : 'ok',
+        });
     }
     return result;
 }
+/**
+ * FB — rewrite a snapshot's install/packages maps so any package with a pin
+ * override uses the override version. Returns a new snapshot (input untouched);
+ * only keys already present are overridden (no injection of undeclared pkgs).
+ */
+function applySnapshotOverrides(snapshot, overrides) {
+    if (!overrides || Object.keys(overrides).length === 0)
+        return snapshot;
+    const next = { ...snapshot };
+    if (snapshot.install) {
+        const install = {};
+        for (const [installer, pkgs] of Object.entries(snapshot.install)) {
+            install[installer] = applyPinOverrides(pkgs, overrides);
+        }
+        next.install = install;
+    }
+    if (snapshot.packages) {
+        next.packages = applyPinOverrides(snapshot.packages, overrides);
+    }
+    return next;
+}
+/**
+ * FB — the subset of pin overrides that actually apply to this install (i.e. the
+ * overridden package IS declared in the effective npm map). These are the
+ * packages we targeted-converge so a --pin always holds even without a global
+ * --converge. Overrides for packages not in the snapshot are dropped (already
+ * warned via unmatchedOverrides). Returns name → override version.
+ */
+export function overrideConvergeTargets(effectiveNpmMap, overrides) {
+    const targets = {};
+    for (const [name, version] of Object.entries(overrides)) {
+        if (name in effectiveNpmMap)
+            targets[name] = version;
+    }
+    return targets;
+}
 export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}, options = {}) {
     const indent = '  '.repeat(depth);
     const result = {
         installed: [],
         failed: [],
     };
+    // FB — apply pin overrides to THIS layer's install/packages maps before doing
+    // anything, so both this layer and the extends recursion (which carries the
+    // same options.overrides) install the override version, never the original pin.
+    if (options.overrides) {
+        snapshot = applySnapshotOverrides(snapshot, options.overrides);
+    }
     // Merge installers: snapshot + parent (parent takes precedence for overrides like npm-proxy)
     let installers = { ...DEFAULT_INSTALLERS };
     if (snapshot.installers) {
@@ -512,21 +589,21 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
         const resolved = await resolveSnapshotDependencies(snapshot, { skipRegistry: true });
         // skit 패키지 설치 (skit-adapter 사용: lib 우선, CLI fallback)
         if (Object.keys(resolved.skit).length > 0) {
-            const skitResult = await installSkitPackages(resolved.skit, snapshot.name, indent, options.sessionId);
+            const skitResult = await installSkitPackages(resolved.skit, snapshot.name, indent, options.sessionId, options.recorder);
             result.installed.push(...skitResult.installed);
             result.failed.push(...skitResult.failed);
         }
         // npm 패키지 설치 (proxy 사용 시 npm-proxy, 아니면 glpkg)
         if (Object.keys(resolved.npm).length > 0) {
             const npmInstaller = options.useProxy ? 'npm-proxy' : 'glpkg';
-            const npmResult = await installPackagesByType(resolved.npm, npmInstaller, installers, snapshot.name, indent, 'npm packages', options.sessionId);
+            const npmResult = await installPackagesByType(resolved.npm, npmInstaller, installers, snapshot.name, indent, 'npm packages', options.sessionId, options.recorder);
             result.installed.push(...npmResult.installed);
             result.failed.push(...npmResult.failed);
         }
         // generic 패키지 설치 (glpkg)
         if (Object.keys(resolved.generic).length > 0) {
             const genericInstaller = options.useProxy ? 'npm-proxy' : 'glpkg';
-            const genericResult = await installPackagesByType(resolved.generic, genericInstaller, installers, snapshot.name, indent, 'packages', options.sessionId);
+            const genericResult = await installPackagesByType(resolved.generic, genericInstaller, installers, snapshot.name, indent, 'packages', options.sessionId, options.recorder);
             result.installed.push(...genericResult.installed);
             result.failed.push(...genericResult.failed);
         }
@@ -543,7 +620,7 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
                 continue;
             // Skit packages: use skit-adapter (lib 우선, CLI fallback)
             if (installerName === 'skit') {
-                const skitResult = await installSkitPackages(packages, snapshot.name, indent, options.sessionId);
+                const skitResult = await installSkitPackages(packages, snapshot.name, indent, options.sessionId, options.recorder);
                 result.installed.push(...skitResult.installed);
                 result.failed.push(...skitResult.failed);
                 continue;
@@ -597,6 +674,14 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
                     const batchCommand = installCfg.command.replace('{pkg}', specs.join(' '));
                     console.log(chalk.gray(`${indent}  Running batch: npm install -g (${specs.length} packages)`));
                     const success = runCommand(batchCommand);
+                    // S3 — record the batch step (ok, or 'fallback' if it failed → retried below).
+                    options.recorder?.record({
+                        phase: 'layer-batch',
+                        installer: installerName,
+                        command: batchCommand,
+                        specs,
+                        result: success ? 'ok' : 'fallback',
+                    });
                     if (success) {
                         for (const spec of specs) {
                             console.log(`${indent}${chalk.blue('batch')} ${spec}...${chalk.green(' ✓')}`);
@@ -612,6 +697,13 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
                             const pkgSpec = `${entry.name}@${entry.version}`;
                             const command = installCfg.command.replace('{pkg}', pkgSpec);
                             const ok = runCommand(command);
+                            options.recorder?.record({
+                                phase: 'layer-fallback',
+                                installer: installerName,
+                                command,
+                                specs: [pkgSpec],
+                                result: ok ? 'ok' : 'failed',
+                            });
                             if (ok) {
                                 console.log(`${indent}${chalk.blue('fallback')} ${pkgSpec}...${chalk.green(' ✓')}`);
                                 result.installed.push(pkgSpec);
@@ -646,6 +738,14 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
                 });
                 result.installed.push(...parallelResult.installed);
                 result.failed.push(...parallelResult.failed);
+                // S3 — record the whole parallel (non-npm) install as one step.
+                options.recorder?.record({
+                    phase: 'layer-parallel',
+                    installer: installerName,
+                    command: installCfg.command.replace('{pkg}', '<each>'),
+                    specs: installEntries.map((e) => `${e.name}@${e.version}`),
+                    result: parallelResult.failed.length > 0 ? 'failed' : 'ok',
+                });
             }
         }
     }
@@ -694,11 +794,19 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
             });
             result.installed.push(...parallelResult.installed);
             result.failed.push(...parallelResult.failed);
+            // S3 — record the legacy glpkg parallel install as one step.
+            options.recorder?.record({
+                phase: 'layer-parallel',
+                installer: 'glpkg',
+                command: legacyCfg.command.replace('{pkg}', '<each>'),
+                specs: legacyEntries.map((e) => `${e.name}@${e.version}`),
+                result: parallelResult.failed.length > 0 ? 'failed' : 'ok',
+            });
         }
     }
     // Legacy: skits (use skit-adapter: lib 우선, CLI fallback)
     if (snapshot.skits && Object.keys(snapshot.skits).length > 0) {
-        const skitResult = await installSkitPackages(snapshot.skits, snapshot.name, indent, options.sessionId);
+        const skitResult = await installSkitPackages(snapshot.skits, snapshot.name, indent, options.sessionId, options.recorder);
         result.installed.push(...skitResult.installed);
         result.failed.push(...skitResult.failed);
     }
@@ -758,7 +866,7 @@ async function collectAllNpmPackages(snapshot, useProxy = true) {
  * This ensures .npmrc is configured with ALL scopes before installation begins,
  * including scopes from base snapshots (e.g., @microwiseai from @ist/minimal).
  */
-async function collectAllPackages(snapshot) {
+export async function collectAllPackages(snapshot) {
     const allPackages = {};
     // Collect from current snapshot
     if (snapshot.packages) {
@@ -1036,6 +1144,31 @@ export async function installCommand(name, options = {}) {
         await previewInstall(snapshot, options);
         return;
     }
+    // ========== FB — parse pin overrides (--pin) ==========
+    // Malformed specs are fail-loud (exit 1) BEFORE any install side effect. The
+    // top snapshot's maps are rewritten now so downstream session authorization,
+    // scope collection, the pre-install batch AND installSnapshot all see the
+    // override version. The extends chain is covered via options.overrides.
+    let overrides = {};
+    try {
+        overrides = parsePins(options.pin);
+    }
+    catch (err) {
+        if (err instanceof PinParseError) {
+            console.log(chalk.red(`⛔ Invalid --pin: ${err.message}`));
+            console.log(chalk.gray('   Expected form: --pin @scope/name@exact-version (e.g. --pin @ist/sesh@0.4.0)'));
+            process.exit(1);
+        }
+        throw err;
+    }
+    if (Object.keys(overrides).length > 0) {
+        snapshot = applySnapshotOverrides(snapshot, overrides);
+        console.log('');
+        console.log(chalk.cyan('► FB pin overrides:'));
+        for (const [name, version] of Object.entries(overrides)) {
+            console.log(chalk.cyan(`    ⇄ ${name} → ${version}`));
+        }
+    }
     // ========== Access Check (based on snapshot.json access field) ==========
     // Determine access type from snapshot.json:
     //   - access: "public"                      → no login/license required
@@ -1200,11 +1333,24 @@ export async function installCommand(name, options = {}) {
         effectiveInstallers['glpkg'] = DEFAULT_INSTALLERS['npm-proxy'];
         effectiveInstallers['gitlab-install'] = DEFAULT_INSTALLERS['npm-proxy'];
     }
+    // S3 — one step recorder for the whole install, threaded through the
+    // pre-install batch AND installSnapshot (via options.recorder), so the ledger
+    // captures the ordered install steps.
+    const recorder = new StepRecorder();
     // ========== Pre-install: batch all npm packages from extends chain ==========
     // Collect all npm-type packages across the entire extends chain and install
     // them in a single `npm install -g` call, instead of one per snapshot layer.
     const allNpmPackages = await collectAllNpmPackages(snapshot, useProxy);
-    const npmEntries = Object.entries(allNpmPackages);
+    // FB — flatten overrides across the whole chain. `snapshot` was already
+    // rewritten, but base layers fetched inside collectAllNpmPackages were not, so
+    // apply once more to the flattened map. This is the "expected" pin set (what
+    // SHOULD be on disk) used for the pre-install batch AND verification.
+    const effectiveNpmMap = applyPinOverrides(allNpmPackages, overrides);
+    const unmatched = unmatchedOverrides(allNpmPackages, overrides);
+    if (unmatched.length > 0) {
+        console.log(chalk.yellow(`⚠ --pin ignored for package(s) not in this snapshot: ${unmatched.join(', ')}`));
+    }
+    const npmEntries = Object.entries(effectiveNpmMap);
     if (npmEntries.length > 0) {
         console.log('');
         console.log(chalk.cyan(`► Pre-installing ${npmEntries.length} npm packages from entire extends chain...`));
@@ -1223,6 +1369,15 @@ export async function installCommand(name, options = {}) {
             const npmCommand = DEFAULT_INSTALLERS['npm-proxy'].command.replace('{pkg}', specs.join(' '));
             console.log(chalk.gray(`  Running single batch: npm install -g (${specs.length} packages)`));
             const batchSuccess = runCommand(npmCommand);
+            // S3 — record the up-front batch (the single step where the beta npm tree
+            // is actually resolved). 'fallback' means it failed and we retried below.
+            recorder.record({
+                phase: 'pre-install-batch',
+                installer: 'npm-proxy',
+                command: npmCommand,
+                specs,
+                result: batchSuccess ? 'ok' : 'fallback',
+            });
             if (batchSuccess) {
                 for (const spec of specs) {
                     console.log(`  ${chalk.blue('batch')} ${spec}...${chalk.green(' ✓')}`);
@@ -1239,6 +1394,13 @@ export async function installCommand(name, options = {}) {
                     const pkgSpec = `${entry.name}@${entry.version}`;
                     const cmd = DEFAULT_INSTALLERS['npm-proxy'].command.replace('{pkg}', pkgSpec);
                     const ok = runCommand(cmd);
+                    recorder.record({
+                        phase: 'pre-install-fallback',
+                        installer: 'npm-proxy',
+                        command: cmd,
+                        specs: [pkgSpec],
+                        result: ok ? 'ok' : 'failed',
+                    });
                     if (ok) {
                         console.log(`  ${chalk.blue('fallback')} ${pkgSpec}...${chalk.green(' ✓')}`);
                     }
@@ -1257,6 +1419,14 @@ export async function installCommand(name, options = {}) {
     // installSnapshot's internal isNpmGlobalInstalled checks will skip already-installed packages
     let installError = null;
     let result = { installed: [], failed: [] };
+    // S1 — post-install verification verdict (disk vs manifest pins). Computed
+    // inside the try BELOW so it runs while the registry-proxy .npmrc + session
+    // token are still active (runConverge issues `npm install -g`).
+    let verification;
+    // ★ Convergence is ON BY DEFAULT (owner decision). `--no-converge` opts out
+    // for a raw/fast install (commander sets options.converge=false). Programmatic
+    // lib callers get the default (true) unless they pass converge:false.
+    const converge = options.converge !== false;
     try {
         // Auto-detect 모드: snapshot.install이 없으면 자동 판별
         const autoDetect = !snapshot.install;
@@ -1264,8 +1434,51 @@ export async function installCommand(name, options = {}) {
             useProxy,
             autoDetect,
             sessionId,
+            recorder,
+            overrides,
         });
         result = installResult.result;
+        // ===== S1/FB — verify (and optionally converge) BEFORE cleanup =====
+        // SSOT enforcement: the manifest pins (with FB overrides applied) are the
+        // truth. Check the disk actually matches. This MUST run before the finally
+        // restores .npmrc, because re-pinning via `npm install -g` needs the
+        // registry-proxy config + token still in place.
+        if (Object.keys(effectiveNpmMap).length > 0) {
+            // Re-pin one package to an exact version and record it as a ledger step.
+            const repin = (phase) => (name, version) => {
+                const spec = `${name}@${version}`;
+                const cmd = `npm install -g ${spec}`;
+                const ok = runCommand(cmd);
+                recorder.record({ phase, installer: 'npm-proxy', command: cmd, specs: [spec], result: ok ? 'ok' : 'failed' });
+            };
+            if (converge) {
+                // Default: re-pin EVERY package that diverged from its pin (self-healing).
+                console.log('');
+                console.log(chalk.cyan('► Verifying & converging install to manifest pins...'));
+                verification = runConverge(allNpmPackages, overrides, {
+                    install: repin('converge'),
+                    readVersion: readInstalledNpmVersion,
+                    maxRounds: 3,
+                });
+            }
+            else {
+                // --no-converge (raw/fast): do NOT auto-repair general divergence. But a
+                // --pin must STILL hold (npm dedup can revert it), so converge JUST the
+                // overridden packages (targeted), then take the final verdict over the
+                // full map. Non-overridden divergences fail-loud (see below).
+                const pinTargets = overrideConvergeTargets(effectiveNpmMap, overrides);
+                if (Object.keys(pinTargets).length > 0) {
+                    console.log('');
+                    console.log(chalk.cyan(`► Holding ${Object.keys(pinTargets).length} pinned package(s) to the override version...`));
+                    runConverge(pinTargets, {}, {
+                        install: repin('pin-converge'),
+                        readVersion: readInstalledNpmVersion,
+                        maxRounds: 3,
+                    });
+                }
+                verification = verifyInstallMap(effectiveNpmMap, { readVersion: readInstalledNpmVersion });
+            }
+        }
     }
     catch (err) {
         installError = err instanceof Error ? err : new Error(String(err));
@@ -1289,6 +1502,16 @@ export async function installCommand(name, options = {}) {
     console.log(chalk.yellow('═══════════════════════════════════'));
     const total = result.installed.length + result.failed.length;
     console.log(`Installed: ${chalk.green(result.installed.length)}/${total}`);
+    // S1 — promote "Installed N/N" to the real health signal: "verified N/N"
+    // (disk actually matches the manifest pins), not just "npm exited 0".
+    if (verification) {
+        if (verification.ok) {
+            console.log(`Verified:  ${chalk.green(verification.verifiedCount)}/${verification.total} ${chalk.gray('(disk matches manifest pins)')}`);
+        }
+        else {
+            console.log(`Verified:  ${chalk.red(verification.verifiedCount)}/${verification.total} ${chalk.red('(disk diverged from manifest pins)')}`);
+        }
+    }
     if (result.failed.length > 0) {
         console.log('');
         console.log(chalk.red('Failed:'));
@@ -1309,6 +1532,101 @@ export async function installCommand(name, options = {}) {
         console.log('');
         console.log(chalk.green('✓') + ' Snapshot info saved');
     }
+    // ========== S3: install ledger (provenance + step order) ==========
+    // Record where every declared npm package's on-disk version came from
+    // (resolved version, tarball URL, resolution source, install-step order),
+    // so "이 버전이 어디서 왔나" is answerable from the ledger ALONE (AC3.1).
+    // Written on every install with npm packages, best-effort — a ledger failure
+    // must never fail the install itself.
+    // AC1.4 — core-floor verdict (computed inside the ledger block, folded in +
+    // used for fail-loud below). undefined when there are no npm packages.
+    let coreFloor;
+    if (Object.keys(allNpmPackages).length > 0) {
+        try {
+            // ★ DEEP, nested-visible tree (NOT --depth=0). Scope to the install's npm
+            // packages + the singleton so an OLD @ist/adapters-core buried under
+            // another package (which re-fragments the S2 registry) is surfaced.
+            const deepNames = Array.from(new Set([...Object.keys(effectiveNpmMap), DEFAULT_CORE_FLOOR_PKG]));
+            const dependencyTreeRaw = queryDependencyTree(deepNames);
+            // AC1.4 (R-A) — no copy of @ist/adapters-core (top-level OR nested) may be
+            // below the 0.4.2 floor; an old nested copy silently re-breaks codex.
+            coreFloor = coreFloorAssert(dependencyTreeRaw); // defaults: @ist/adapters-core >= 0.4.2
+            const ledger = buildLedger({
+                snapshotName: snapshot.name,
+                snapshotVersion: snapshot.version,
+                cliVersion: CLI_VERSION,
+                registry: REGISTRY_PROXY_URL,
+                // "expected" = the pins we intended to land = manifest pins with FB
+                // overrides applied. This is what verification checks against too.
+                expected: effectiveNpmMap,
+                installer: 'npm-proxy',
+                steps: recorder.getSteps(),
+                overrides, // FB pin overrides (name → version); {} when no --pin
+                dependencyTreeRaw, // deep tree (nested-visible) — provenance + AC1.4
+            }, new Date().toISOString());
+            // S1 — fold the verification verdict into the ledger (single artifact for
+            // provenance + verdict). VerificationResult is structurally the ledger's
+            // verification shape { ok, verifiedCount, total, mismatches[{name,expected,got}] }.
+            if (verification)
+                ledger.verification = verification;
+            // AC1.4 — fold the core-floor verdict too.
+            ledger.coreFloor = {
+                ok: coreFloor.ok,
+                pkg: DEFAULT_CORE_FLOOR_PKG,
+                minVersion: DEFAULT_CORE_FLOOR_MIN_VERSION,
+                offenders: coreFloor.offenders,
+            };
+            if (writeLedger(ledger)) {
+                console.log(chalk.green('✓') + ' Install ledger written (see: snapshot current --json)');
+            }
+        }
+        catch {
+            // Ledger is diagnostic-only — swallow any failure.
+        }
+    }
+    // ========== Divergence handling — S1 verify + AC1.4 core-floor ==========
+    // Owner decision: NO "green on broken". Any residual divergence is a hard
+    // fail-loud (exit 1), in BOTH modes:
+    //   • core-floor offenders → ALWAYS exit 1 (convergence cannot repair an old
+    //     NESTED @ist/adapters-core copy; AC1.4 / R-A).
+    //   • verify divergence → exit 1 in both modes. The only difference: default
+    //     (converge) mode ATTEMPTED auto-repair first and still couldn't reconcile
+    //     (e.g. an unpublished pin), whereas --no-converge (strict/raw) never
+    //     attempted repair. The ledger persisted the full evidence either way.
+    const verifyFailed = !!(verification && !verification.ok);
+    const floorFailed = !!(coreFloor && !coreFloor.ok);
+    if (floorFailed) {
+        console.log('');
+        console.log(chalk.red(formatCoreFloorOffenders(coreFloor.offenders)));
+        console.log(chalk.gray(`  Every ${DEFAULT_CORE_FLOOR_PKG} copy (incl. nested) must be >= ${DEFAULT_CORE_FLOOR_MIN_VERSION} for the S2 singleton to hold.`));
+    }
+    if (verifyFailed) {
+        console.log('');
+        if (!converge) {
+            // strict (--no-converge): no auto-repair was attempted.
+            console.log(chalk.red(formatVerificationFailure(verification.mismatches)));
+            if (Object.keys(overrides).length > 0) {
+                // --pin packages were held via targeted convergence; the divergences
+                // above are OTHER packages — don't suggest re-pinning what's pinned.
+                console.log(chalk.gray('  The pinned package(s) are held; the divergence(s) above are other packages — drop --no-converge to auto-repair them.'));
+            }
+            else {
+                console.log(chalk.gray('  Drop --no-converge to auto-repair, or --pin <pkg>@<version> to force a specific version.'));
+            }
+        }
+        else {
+            // default (converge ON): repair was attempted but couldn't reconcile → still
+            // a hard failure (no silent green-on-broken).
+            console.log(chalk.red('✗ Converge could not reconcile the disk to the manifest pins after 3 rounds:'));
+            console.log(chalk.red(formatVerificationFailure(verification.mismatches)));
+            console.log(chalk.gray('  The above may be unpublished/unavailable versions. See: snapshot current --json (ledger has full evidence).'));
+        }
+    }
+    // No green-on-broken: exit non-zero on ANY core-floor offender OR verify
+    // divergence, in both converge and --no-converge modes.
+    if (floorFailed || verifyFailed) {
+        process.exit(1);
+    }
     // Record references for the ENTIRE declared set (installed + dedup-skipped),
     // so replace mode has accurate referencedBy data (ADR 001 §c). This runs on
     // every install, not just --replace, to build up the reference graph.