@microwiseai/snapshot 0.5.2 → 0.7.0

package/dist/commands/install.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
-import { execSync, spawn } from 'child_process';
-import { writeFileSync, existsSync, readFileSync, unlinkSync, mkdirSync } from 'fs';
+import { execSync } from 'child_process';
+import { writeFileSync, existsSync, readFileSync, unlinkSync } from 'fs';
 import { homedir, platform, arch } from 'os';
 import { join } from 'path';
 import { fetchSnapshotFromRepo, snapshotNameToRepoName } from '../lib/gitlab.js';
@@ -14,12 +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 { createInstallTimeline } from '../lib/install-timeline.js';
-// Install-timeline instrumentation (investigation only, env opt-in). A disabled
-// no-op is the default so module-level callers (runCommand, installSkitPackages)
-// always have a valid handle; installCommand() reassigns a live instance when
-// SNAPSHOT_INSTALL_TIMELINE is set. Adds zero behavior — only measurement.
-let activeTimeline = createInstallTimeline({ enabled: false });
+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);
@@ -200,74 +198,27 @@ function commandExists(cmd) {
 // Captures the failure reason of the most recent runCommand() call so callers
 // can surface it (debugging visibility). Undefined when the last call succeeded.
 let lastCommandError;
-// Bound the captured-stderr buffer so a chatty command can't grow it without
-// limit; on overflow we keep the tail (where the actual failure usually is).
-const MAX_STDERR_CAPTURE = 64 * 1024;
-// Runs a shell command, streaming its output live while still capturing stderr
-// for failure diagnostics.
-//
-// Why spawn (async) instead of execSync: long installs (e.g. `npm install -g`
-// of the whole pre-install batch) push their live progress to STDERR. execSync
-// with a piped stderr hid that progress entirely — the terminal sat silent for
-// minutes, then dumped a summary. Here stderr is piped so we can BOTH tee it to
-// our own stderr in real time (visible progress) AND accumulate it, so the raw
-// reason is still available via lastCommandError when the command fails.
-//
-// stdout stays inherited (live, unbuffered). shell:true preserves the previous
-// execSync parsing of the full command string.
 function runCommand(command) {
     lastCommandError = undefined;
-    // Instrumentation only: the timeline sanitizes the command label internally,
-    // so tokens are never recorded. No effect when the timeline is disabled.
-    const span = activeTimeline.start(command, { category: 'command' });
-    return new Promise((resolve) => {
-        const child = spawn(command, {
-            shell: true,
-            stdio: ['inherit', 'inherit', 'pipe'],
-        });
-        let stderrBuf = '';
-        child.stderr?.on('data', (chunk) => {
-            // Live streaming: echo the command's progress as it happens.
-            process.stderr.write(chunk);
-            // Capture (bounded) for failure diagnostics.
-            stderrBuf += chunk.toString();
-            if (stderrBuf.length > MAX_STDERR_CAPTURE) {
-                stderrBuf = stderrBuf.slice(-MAX_STDERR_CAPTURE);
-            }
-        });
-        // 'error' (spawn failed) and 'close' (process exited) are mutually exclusive
-        // in practice, but guard against a double-resolve just in case.
-        let settled = false;
-        const finish = (ok) => {
-            if (settled)
-                return;
-            settled = true;
-            resolve(ok);
-        };
-        child.on('error', (err) => {
-            // Spawn-level failure (e.g. shell missing) — no exit code available.
-            lastCommandError = `spawn error — ${err.message}`;
-            span.end({ success: false, exitReason: 'spawn error' });
-            console.log(chalk.red(`  Command failed to start: ${command}`));
-            console.log(chalk.red(err.message));
-            finish(false);
-        });
-        child.on('close', (code) => {
-            if (code === 0) {
-                span.end({ success: true });
-                finish(true);
-                return;
-            }
-            const detail = stderrBuf.trim() || 'unknown error';
-            lastCommandError = `exit code ${code ?? 'unknown'} — ${detail}`;
-            span.end({ success: false, exitReason: `exit code ${code ?? 'unknown'}` });
-            // stderr was already streamed live above, so we don't re-print the full
-            // detail here (that would duplicate it). Callers surface lastCommandError
-            // where they want a compact "Reason:" line.
-            console.log(chalk.red(`  Command failed (exit code ${code ?? 'unknown'}): ${command}`));
-            finish(false);
-        });
-    });
+    try {
+        // Keep stdout visible live, but capture stderr so we can surface the raw
+        // error reason instead of swallowing it on failure.
+        execSync(command, { stdio: ['inherit', 'inherit', 'pipe'] });
+        return true;
+    }
+    catch (err) {
+        const exitCode = err?.status;
+        const stderr = err?.stderr?.toString().trim();
+        const message = err?.message ? String(err.message).trim() : undefined;
+        const detail = stderr || message || 'unknown error';
+        lastCommandError = `exit code ${exitCode ?? 'unknown'} — ${detail}`;
+        // Surface the raw failure (stderr is no longer shown live since it is piped).
+        console.log(chalk.red(`  Command failed (exit code ${exitCode ?? 'unknown'}): ${command}`));
+        if (detail) {
+            console.log(chalk.red(detail));
+        }
+        return false;
+    }
 }
 /**
  * Check if a skit package is already installed with the specified version
@@ -300,85 +251,16 @@ function isNpmGlobalInstalled(name, version) {
         return false;
     }
 }
-// Preflight is a diagnostic: it runs once per process and warns loudly, but
-// does NOT abort — skit still tries, so any real error path stays intact.
-let istWritabilityChecked = false;
-/**
- * Verify the current user can actually write into ~/.ist before skit installs.
- *
- * Motivation: when ~/.ist is mounted as a root:root Docker named volume and the
- * process runs as a non-root user, skit's writes fail with EACCES. skit swallows
- * that into an opaque "Error: undefined" and the install silently under-counts
- * (e.g. 7/12). This surfaces the real cause up front with a concrete fix.
- *
- * Detection is a real write probe (create+delete a temp file), which is more
- * reliable than fs.accessSync(W_OK) — the latter can misreport under root/ACLs.
- * Missing directories are created first (that itself exercises writability of
- * the parent). Never throws; a probe failure just flags the directory.
- */
-function checkIstWritable() {
-    if (istWritabilityChecked)
-        return;
-    istWritabilityChecked = true;
-    const istRoot = join(homedir(), '.ist');
-    // Directories skit writes into: the root itself (installed-kits.json lives
-    // here), global prompts, and profiles.
-    const targets = [
-        istRoot,
-        join(istRoot, 'prompts', 'global'),
-        join(istRoot, 'profiles'),
-    ];
-    const notWritable = [];
-    for (const dir of targets) {
-        try {
-            if (!existsSync(dir)) {
-                // Creating the dir also proves the parent is writable. If this throws
-                // (EACCES on a root-owned volume), the dir is not usable → flag it.
-                mkdirSync(dir, { recursive: true });
-            }
-            const probe = join(dir, `.snapshot-write-probe-${process.pid}`);
-            writeFileSync(probe, '');
-            unlinkSync(probe);
-        }
-        catch {
-            notWritable.push(dir);
-        }
-    }
-    // installed-kits.json may already exist with restrictive ownership even when
-    // its directory is writable — probe the file directly if present.
-    const kitsFile = join(istRoot, 'installed-kits.json');
-    if (existsSync(kitsFile)) {
-        try {
-            writeFileSync(kitsFile, readFileSync(kitsFile));
-        }
-        catch {
-            notWritable.push(kitsFile);
-        }
-    }
-    if (notWritable.length > 0) {
-        console.log('');
-        console.log(chalk.yellow('⚠ ~/.ist is not writable by current user (owned by root?) — skit installs will fail.'));
-        for (const p of notWritable) {
-            console.log(chalk.gray(`    not writable: ${p}`));
-        }
-        console.log(chalk.gray('  Fix directory ownership: chown -R $(whoami) ~/.ist'));
-        console.log('');
-    }
-}
 /**
  * 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) {
         return result;
     }
-    // Diagnostic preflight (once/process): if ~/.ist isn't writable by the current
-    // user, skit installs fail opaquely ("Error: undefined", under-counted total).
-    // Warn with the concrete fix before we start the skit loop.
-    checkIstWritable();
     const total = packageEntries.length;
     console.log('');
     console.log(chalk.yellow(`${indent}=== ${snapshotName}: ${total} skits ===`));
@@ -391,14 +273,7 @@ async function installSkitPackages(packages, snapshotName, indent, sessionId) {
         if (isSkitInstalled(entry.name, entry.version)) {
             return { success: true, skipped: true };
         }
-        // Per-package timing (investigation only) — surfaces individual skit
-        // hotspots (e.g. infra-kit/mwd-kit) under the install-snapshot phase.
-        const pkgSpan = activeTimeline.start(`${entry.name}@${entry.version}`, {
-            category: 'package',
-            meta: { installer: 'skit' },
-        });
         const installResult = await installSkitPackage(entry.name, entry.version, skitOptions);
-        pkgSpan.end({ success: installResult.success });
         return {
             success: installResult.success,
             error: installResult.error,
@@ -421,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) {
@@ -434,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) {
@@ -450,7 +333,7 @@ async function installPackagesByType(packages, installerName, installers, snapsh
     if (!commandExists(cmdName)) {
         console.log(chalk.yellow(`${indent}${installerName} not found. Attempting auto-install...`));
         console.log(chalk.gray(`${indent}  Running: ${installerConfig.hint}`));
-        if (await runCommand(installerConfig.hint)) {
+        if (runCommand(installerConfig.hint)) {
             console.log(chalk.green(`${indent}  ✓ ${installerName} installed successfully`));
         }
         else {
@@ -483,7 +366,15 @@ async function installPackagesByType(packages, installerName, installers, snapsh
             const specs = toInstall.map(e => `${e.name}@${e.version}`);
             const batchCommand = installerConfig.command.replace('{pkg}', specs.join(' '));
             console.log(chalk.gray(`${indent}  Running batch: npm install -g (${specs.length} packages)`));
-            const success = await runCommand(batchCommand);
+            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(' ✓')}`);
@@ -498,7 +389,14 @@ async function installPackagesByType(packages, installerName, installers, snapsh
                 for (const entry of toInstall) {
                     const pkgSpec = `${entry.name}@${entry.version}`;
                     const command = installerConfig.command.replace('{pkg}', pkgSpec);
-                    const ok = await runCommand(command);
+                    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);
@@ -516,7 +414,7 @@ async function installPackagesByType(packages, installerName, installers, snapsh
         const parallelResult = await parallelInstall(entries, async (entry) => {
             const pkgSpec = `${entry.name}@${entry.version}`;
             const command = installerConfig.command.replace('{pkg}', pkgSpec);
-            const success = await runCommand(command);
+            const success = runCommand(command);
             return { success, error: success ? undefined : `Command failed: ${command}` };
         }, {
             concurrency: 4,
@@ -533,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) {
@@ -641,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);
         }
@@ -672,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;
@@ -691,7 +639,7 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
             if (!commandExists(cmdName)) {
                 console.log(chalk.yellow(`${indent}${installerName} not found. Attempting auto-install...`));
                 console.log(chalk.gray(`${indent}  Running: ${installerConfig.hint}`));
-                if (await runCommand(installerConfig.hint)) {
+                if (runCommand(installerConfig.hint)) {
                     console.log(chalk.green(`${indent}  ✓ ${installerName} installed successfully`));
                 }
                 else {
@@ -725,7 +673,15 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
                     const specs = toInstall.map(e => `${e.name}@${e.version}`);
                     const batchCommand = installCfg.command.replace('{pkg}', specs.join(' '));
                     console.log(chalk.gray(`${indent}  Running batch: npm install -g (${specs.length} packages)`));
-                    const success = await runCommand(batchCommand);
+                    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(' ✓')}`);
@@ -740,7 +696,14 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
                         for (const entry of toInstall) {
                             const pkgSpec = `${entry.name}@${entry.version}`;
                             const command = installCfg.command.replace('{pkg}', pkgSpec);
-                            const ok = await runCommand(command);
+                            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);
@@ -758,7 +721,7 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
                 const parallelResult = await parallelInstall(installEntries, async (entry) => {
                     const pkgSpec = `${entry.name}@${entry.version}`;
                     const command = installCfg.command.replace('{pkg}', pkgSpec);
-                    const success = await runCommand(command);
+                    const success = runCommand(command);
                     return { success, error: success ? undefined : `Command failed: ${command}` };
                 }, {
                     concurrency: 4,
@@ -775,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',
+                });
             }
         }
     }
@@ -788,7 +759,7 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
         if (!commandExists(cmdName)) {
             console.log(chalk.yellow(`${indent}glpkg not found. Attempting auto-install...`));
             console.log(chalk.gray(`${indent}  Running: ${installerConfig.hint}`));
-            if (await runCommand(installerConfig.hint)) {
+            if (runCommand(installerConfig.hint)) {
                 console.log(chalk.green(`${indent}  ✓ glpkg installed successfully`));
             }
             else {
@@ -806,7 +777,7 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
             const parallelResult = await parallelInstall(legacyEntries, async (entry) => {
                 const pkgSpec = `${entry.name}@${entry.version}`;
                 const command = legacyCfg.command.replace('{pkg}', pkgSpec);
-                const success = await runCommand(command);
+                const success = runCommand(command);
                 return { success, error: success ? undefined : `Command failed: ${command}` };
             }, {
                 concurrency: 4,
@@ -823,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);
     }
@@ -887,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) {
@@ -1017,7 +996,7 @@ async function runReplaceMode(snapshotName, newSet, options, installers) {
             continue;
         }
         console.log(chalk.gray(`  Removing ${item.name}...`));
-        if (await runCommand(cmd)) {
+        if (runCommand(cmd)) {
             console.log(`    ${item.name}${chalk.green(' ✓ removed')}`);
             removed.push(item);
         }
@@ -1078,10 +1057,6 @@ async function previewInstall(snapshot, options) {
     console.log(chalk.gray('Dry-run complete: no installs, no uninstalls, no .npmrc or history changes.'));
 }
 export async function installCommand(name, options = {}) {
-    // Install-timeline instrumentation: live instance when SNAPSHOT_INSTALL_TIMELINE
-    // is set, otherwise a zero-overhead no-op. Purely additive — never alters the
-    // install path or its output when disabled.
-    activeTimeline = createInstallTimeline();
     console.log(chalk.blue.bold(`
 ╔══════════════════════════════════════════════════════════════╗
 ║                    Snapshot Installer                        ║
@@ -1115,7 +1090,6 @@ export async function installCommand(name, options = {}) {
     //
     // License key CANNOT be used as Bearer token for registry-proxy — they are
     // distinct: AuthN (uid via IST JWT) vs AuthZ (entitlement via license key).
-    const authSpan = activeTimeline.start('auth-token', { category: 'phase' });
     const licenseKey = getLicenseKey();
     let authToken = null;
     let authType = 'anonymous';
@@ -1132,16 +1106,13 @@ export async function installCommand(name, options = {}) {
         console.log(chalk.yellow('⚠') + ' No auth token — anonymous access');
     }
     const useProxy = true;
-    authSpan.end({ authType });
     // Fetch snapshot first — access check depends on snapshot.json content
     console.log(chalk.gray('Fetching snapshot...'));
-    const fetchSpan = activeTimeline.start('fetch-snapshot', { category: 'phase' });
     let snapshot;
     try {
         snapshot = await fetchSnapshotFromRepo(name, authToken);
     }
     catch (error) {
-        fetchSpan.end({ success: false });
         const errMsg = error instanceof Error ? error.message : String(error);
         if (options.dryRun) {
             // Pure preview: a fetch failure (offline / no auth) is not fatal — we just
@@ -1156,7 +1127,6 @@ export async function installCommand(name, options = {}) {
         console.log(chalk.yellow('Check the snapshot name and version, e.g. snapshot install @scope/name@version'));
         process.exit(1);
     }
-    fetchSpan.end({ success: true });
     console.log(chalk.green('✓') + ` Snapshot: ${snapshot.name} v${snapshot.version}`);
     if (snapshot.description) {
         console.log(chalk.gray(`  ${snapshot.description}`));
@@ -1174,30 +1144,62 @@ 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) ==========
-    // snapshot is a general installer. Access is simplified to two tiers:
-    //   - access: "public"                        → no license required
+    // Determine access type from snapshot.json:
+    //   - access: "public"                      → no login/license required
+    //   - access: "authenticated"               → IST login required, no license needed
     //   - access: { type: "licensed", productId } → license required
-    //   - anything else / absent                  → access decided SERVER-side
-    //     (registry-proxy / license API are authoritative; a 401/403 fails loud).
-    // No client-side login gate: access control is backend-authoritative.
+    //   - access field absent                    → treated as licensed (requires license)
     const accessField = snapshot.access;
     const isPublicAccess = accessField === 'public';
+    const isAuthenticatedAccess = accessField === 'authenticated';
     const isLicensedAccess = !!accessField && typeof accessField === 'object' && accessField.type === 'licensed';
-    // Optional identity for telemetry only (anonymous when absent). NOT a gate.
-    // A wrapper (e.g. ist-setup) may layer a login system on top of snapshot via
-    // the authToken injection point (IST_SESSION_TOKEN env / getProxyAuthToken).
+    // --- IST Login Check ---
     const istCredentials = getIstCredentials();
+    if (istCredentials?.userId) {
+        console.log(chalk.green('✓') + ' IST login verified');
+    }
+    else if (isPublicAccess) {
+        console.log(chalk.yellow('⚠') + ' No IST login - installing public package');
+    }
+    else {
+        console.log(chalk.red('⛔ IST login required for non-public packages'));
+        console.log(chalk.gray('   Run: ist auth login'));
+        console.log(chalk.gray('   Or install a public snapshot first (no login required)'));
+        process.exit(1);
+    }
     // --- License Check ---
-    const accessSpan = activeTimeline.start('access-license', {
-        category: 'phase',
-        meta: { access: isPublicAccess ? 'public' : isLicensedAccess ? 'licensed' : 'server-decided' },
-    });
     const storedLicenseKey = getLicenseKey();
     let licenseValid = false;
-    if (isPublicAccess) {
-        // Public snapshots — skip license check entirely
-        console.log(chalk.green('✓') + ' Public snapshot - no license required');
+    if (isPublicAccess || isAuthenticatedAccess) {
+        // Public and authenticated snapshots — skip license check entirely
+        const label = isAuthenticatedAccess ? 'Authenticated' : 'Public';
+        console.log(chalk.green('✓') + ` ${label} snapshot - no license required`);
     }
     else if (storedLicenseKey) {
         try {
@@ -1239,10 +1241,8 @@ export async function installCommand(name, options = {}) {
         }
         console.log(chalk.green('✓') + ` License verified for ${productId}`);
     }
-    accessSpan.end({ licenseValid });
     // =======================================================================
     // ========== Authorize Session with Registry Proxy ==========
-    const authorizeSpan = activeTimeline.start('authorize-session', { category: 'phase' });
     let sessionId;
     if (authToken) {
         // Collect all packages for session authorization
@@ -1278,10 +1278,8 @@ export async function installCommand(name, options = {}) {
             }
         }
     }
-    authorizeSpan.end({ sessionAuthorized: sessionId !== undefined });
     // =============================================================
     // Collect all packages from entire extends chain to determine scopes
-    const configureSpan = activeTimeline.start('configure-npmrc', { category: 'phase' });
     const allPackages = await collectAllPackages(snapshot);
     // Configure .npmrc for proxy (with or without auth token)
     let npmrcBackup = null;
@@ -1301,7 +1299,6 @@ export async function installCommand(name, options = {}) {
             }
         }
     }
-    configureSpan.end({ packageCount: Object.keys(allPackages).length });
     // Guarantee .npmrc restoration even on ^C. A try/finally only covers thrown
     // errors and normal returns — it does NOT run on SIGINT/SIGTERM, so an
     // interrupt during the pre-install batch or the main install would leave a
@@ -1336,13 +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 batchSpan = activeTimeline.start('npm-batch-preinstall', { category: 'phase' });
-    let batchSpecs = [];
     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...`));
@@ -1358,10 +1366,18 @@ export async function installCommand(name, options = {}) {
         }
         if (toInstall.length > 0) {
             const specs = toInstall.map(e => `${e.name}@${e.version}`);
-            batchSpecs = specs;
             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 = await runCommand(npmCommand);
+            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(' ✓')}`);
@@ -1377,7 +1393,14 @@ export async function installCommand(name, options = {}) {
                 for (const entry of toInstall) {
                     const pkgSpec = `${entry.name}@${entry.version}`;
                     const cmd = DEFAULT_INSTALLERS['npm-proxy'].command.replace('{pkg}', pkgSpec);
-                    const ok = await runCommand(cmd);
+                    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(' ✓')}`);
                     }
@@ -1391,13 +1414,19 @@ export async function installCommand(name, options = {}) {
             console.log(chalk.green('✓ All npm packages already installed'));
         }
     }
-    batchSpan.end({ specs: batchSpecs, npmDeclared: npmEntries.length, npmToInstall: batchSpecs.length });
     // =============================================================================
     // Install (handles extends recursively)
     // installSnapshot's internal isNpmGlobalInstalled checks will skip already-installed packages
     let installError = null;
     let result = { installed: [], failed: [] };
-    const installSpan = activeTimeline.start('install-snapshot', { category: 'phase' });
+    // 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;
@@ -1405,18 +1434,56 @@ 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));
     }
     finally {
-        installSpan.end({
-            installed: result.installed.length,
-            failed: result.failed.length,
-            success: installError === null,
-        });
         // Restore .npmrc + clear the session-token env (idempotent: a SIGINT/SIGTERM
         // handler may have already run this). Then drop the signal handlers we
         // registered, so they don't leak across multiple installs in one process.
@@ -1425,7 +1492,6 @@ export async function installCommand(name, options = {}) {
         process.removeListener('SIGTERM', onSignal);
     }
     if (installError) {
-        activeTimeline.finalize();
         console.log(chalk.red(`Error during installation: ${installError.message}`));
         process.exit(1);
     }
@@ -1436,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:'));
@@ -1456,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.
@@ -1472,9 +1643,18 @@ export async function installCommand(name, options = {}) {
             await runReplaceMode(snapshot.name, allPackages, options, effectiveInstallers);
         }
     }
-    // Emit the install timeline (investigation only; no-op unless opted-in) before
-    // the fire-and-forget telemetry so the summary/JSONL reflect the whole run.
-    activeTimeline.finalize();
+    // Post-install: run doctor to check prerequisites
+    console.log('');
+    const { checkPrerequisites, MINIMAL_PREREQUISITES } = await import('../lib/prerequisites.js');
+    const prereqResults = checkPrerequisites(MINIMAL_PREREQUISITES);
+    const missingPrereqs = prereqResults.filter(r => !r.installed);
+    if (missingPrereqs.length > 0) {
+        console.log(chalk.yellow(`\n⚠ ${missingPrereqs.length} prerequisite(s) not satisfied:`));
+        for (const r of missingPrereqs) {
+            console.log(`  ${chalk.red('❌')} ${r.name} — required by ${r.requiredBy.join(', ')}`);
+        }
+        console.log(chalk.gray(`\nRun 'snapshot setup' to install, or 'snapshot doctor' for details.`));
+    }
     // Send telemetry (fire and forget)
     sendInstallTelemetry({
         package: snapshot.name,