@microwiseai/snapshot 0.8.0 → 0.9.0

package/dist/commands/install.js

@@ -1,19 +1,22 @@
 import chalk from 'chalk';
-import { execSync } from 'child_process';
+import { execSync, spawn, spawnSync } 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';
 import { saveCurrentSnapshot } from '../lib/snapshot.js';
-import { getLicenseKey, getProxyAuthToken, REGISTRY_PROXY_URL, VENDOR_NAME, STORE_URL, PACKAGE_NAME, getIstCredentials, LICENSE_API_URL, verifyLicenseKey } from '../lib/config.js';
+import { getLicenseKey, getProxyAuthToken, REGISTRY_PROXY_URL, VENDOR_NAME, STORE_URL, PACKAGE_NAME, getIstCredentials, isLoggedIn, LICENSE_API_URL, verifyLicenseKey } from '../lib/config.js';
 import { resolveSnapshotDependencies } from '../lib/package-resolver.js';
-// transitive-resolver removed — npm handles dependency resolution automatically
+// (transitive-resolver deleted — npm resolves dependencies; see git history)
 import { installSkitPackage } from '../lib/skit-adapter.js';
 import { markLicenseChecked } from '@microwiseai/license';
-import { authorizeSession, packagesToSpecs } from '../lib/session.js';
+import { authorizeSession, packagesToSpecs, maskSessionId } from '../lib/session.js';
+import { readGrantMode, readGrantTimeoutMs, requestSnapshotGrant, GrantState, GrantError, checkGrantCoverage, findRootMemberVersion, formatGrantLog, splitSnapshotSpec, resolveInstallVersion, } from '../lib/grant.js';
 import { parallelInstall, recordToEntries } from '@microwiseai/snapshot-parallel';
+import { detectDowngrades, resolveDowngradePolicy, readOneShotOverride, getMachineDowngradeMode, formatDowngradeReport, extractGlobalInstallSpecs, } from '@microwiseai/snapshot-downgrade-guard';
 import { dedupWithReport, dedupInstallBlock, recordInstalledSpecs, recordReferences, computeReplacePlan, applyReplaceHistory, } from '@microwiseai/snapshot-dedup';
 import { createInterface } from 'readline';
+import { timingStart } from '../lib/timing.js';
 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';
@@ -198,27 +201,148 @@ 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;
-function runCommand(command) {
-    lastCommandError = undefined;
-    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;
+// ============================================================
+// Downgrade guard — npm-exec choke point (defense in depth)
+// ============================================================
+// EVERY global install funnels through runCommand / runCommandSync (the spawn
+// wrappers) — including installCommand's batches, a direct installSnapshot()
+// library call, extends recursion, and parallelInstall's per-spec callback.
+// Detecting downgrades HERE, at that single execution boundary, means NO entry
+// point can bypass the guard (closes the lib.ts public-export bypass). This is a
+// SECOND layer; installCommand's earlier pre-install guard stays as-is.
+//
+// Policy threading: installCommand resolves the mode once and publishes it via
+// setActiveDowngradeMode(); this boundary reuses it (no recompute, no duplicate
+// report). With no upstream context (direct library call), the boundary
+// self-resolves from env (SNAPSHOT_ALLOW_LOCAL) + machine config, defaulting to
+// the safe 'refuse'.
+export class DowngradeRefusedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DowngradeRefusedError';
     }
-    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));
+}
+let activeDowngradeMode;
+/**
+ * Publish (or clear) the downgrade policy resolved upstream by installCommand so
+ * the exec boundary reuses it. Exported as a test seam.
+ */
+export function setActiveDowngradeMode(mode) {
+    activeDowngradeMode = mode;
+}
+/**
+ * Enforce the downgrade policy for a global-install command about to execute.
+ * No-op unless the command is a global install carrying versioned specs AND at
+ * least one spec would downgrade an already-installed global package. On a
+ * 'refuse' verdict it throws DowngradeRefusedError BEFORE spawn (zero partial
+ * install); 'warn' logs and proceeds; 'allow' proceeds silently. Pure detection
+ * is delegated to @microwiseai/snapshot-downgrade-guard.
+ */
+function assertNoRefusedDowngrade(command) {
+    const specs = extractGlobalInstallSpecs(command);
+    if (Object.keys(specs).length === 0)
+        return;
+    const { wouldDowngrade, offenders } = detectDowngrades(specs, {
+        readVersion: readInstalledNpmVersion,
+    });
+    if (!wouldDowngrade)
+        return;
+    // Reuse the upstream-resolved mode when present (installCommand path); else
+    // self-resolve for the context-free direct library-call path.
+    const threaded = activeDowngradeMode !== undefined;
+    const mode = threaded
+        ? activeDowngradeMode
+        : resolveDowngradePolicy({
+            override: readOneShotOverride({ env: process.env }),
+            machine: getMachineDowngradeMode(),
+            // snapshot.json policy is not available at this boundary; the default
+            // 'refuse' keeps the direct-call path on the safe side.
+        });
+    if (mode === 'refuse') {
+        // Only the self-resolved (direct-call) path reports here — the installCommand
+        // path already printed upstream and cannot reach a refuse at this boundary
+        // (it exits during pre-install), so this avoids duplicate output.
+        if (!threaded) {
+            console.log('');
+            console.log(chalk.red(formatDowngradeReport(offenders, mode)));
         }
+        throw new DowngradeRefusedError(formatDowngradeReport(offenders, mode));
+    }
+    if (mode === 'warn' && !threaded) {
+        console.log('');
+        console.log(chalk.yellow(formatDowngradeReport(offenders, mode)));
+    }
+    // mode === 'allow' → proceed.
+}
+/**
+ * Run a command with FULLY LIVE output (spawn, async).
+ *
+ * Why spawn+async (not execSync): npm writes its progress bar to STDERR, and the
+ * previous `execSync(stdio:['inherit','inherit','pipe'])` piped stderr — which
+ * (a) hid npm's live progress (looked "frozen" for tens of seconds) and
+ * (b) blocked the event loop so no JS spinner could ever turn. Inheriting all
+ * three streams lets npm's own progress render live to the terminal while the
+ * event loop stays free. See install-speed-visibility work (B).
+ *
+ * On failure we can no longer capture the stderr text (it went straight to the
+ * terminal, so the user already SAW it) — `lastCommandError` carries the exit
+ * code instead.
+ */
+// Exported as a test seam (unit-tested in install.runcommand.test.ts).
+export function runCommand(command) {
+    // Depth-defense: abort BEFORE spawn if this global install would downgrade and
+    // policy is refuse. Throws DowngradeRefusedError (no partial install).
+    assertNoRefusedDowngrade(command);
+    lastCommandError = undefined;
+    return new Promise((resolve) => {
+        // shell:true so the plain command string (e.g. "npm install -g a@1 b@2")
+        // is parsed exactly as it was under execSync.
+        const child = spawn(command, { stdio: 'inherit', shell: true });
+        child.on('error', (err) => {
+            lastCommandError = `spawn error — ${err.message}`;
+            console.log(chalk.red(`  Command failed to start: ${command}`));
+            console.log(chalk.red(err.message));
+            resolve(false);
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve(true);
+                return;
+            }
+            lastCommandError = `exit code ${code ?? 'unknown'}`;
+            console.log(chalk.red(`  Command failed (exit code ${code ?? 'unknown'}): ${command}`));
+            resolve(false);
+        });
+    });
+}
+/**
+ * Synchronous streaming variant — used ONLY by the converge re-pin callback,
+ * which is invoked from the pure/sync `runConverge` (lib/install-verify.ts).
+ * Keeping this sync avoids making `runConverge` async (which would ripple into
+ * its unit-test suite and break its pure-function contract). `spawnSync` with
+ * inherited stdio still streams npm's live progress to the terminal (the child
+ * writes directly to the inherited fd), so the converge phase no longer looks
+ * frozen either — it only blocks the JS event loop for its (batched, rare)
+ * duration.
+ */
+// Exported as a test seam (unit-tested in install.runcommand.test.ts).
+export function runCommandSync(command) {
+    // Depth-defense: abort BEFORE spawn if this global install would downgrade and
+    // policy is refuse. Throws DowngradeRefusedError (no partial install).
+    assertNoRefusedDowngrade(command);
+    lastCommandError = undefined;
+    const res = spawnSync(command, { stdio: 'inherit', shell: true });
+    if (res.error) {
+        lastCommandError = `spawn error — ${res.error.message}`;
+        console.log(chalk.red(`  Command failed to start: ${command}`));
+        console.log(chalk.red(res.error.message));
         return false;
     }
+    if (res.status === 0)
+        return true;
+    lastCommandError = `exit code ${res.status ?? 'unknown'}`;
+    console.log(chalk.red(`  Command failed (exit code ${res.status ?? 'unknown'}): ${command}`));
+    return false;
 }
 /**
  * Check if a skit package is already installed with the specified version
@@ -264,8 +388,23 @@ async function installSkitPackages(packages, snapshotName, indent, sessionId, re
     const total = packageEntries.length;
     console.log('');
     console.log(chalk.yellow(`${indent}=== ${snapshotName}: ${total} skits ===`));
-    // Prepare install options with sessionId if available
-    const skitOptions = sessionId ? { sessionId } : {};
+    // Prepare install options with sessionId if available. Forward onProgress so
+    // the skit lib's live install messages reach the terminal (skit-adapter.ts
+    // already forwards options.onProgress into lib.installSkit) — otherwise each
+    // skit install is silent until it completes.
+    // grant-unify P1: a function source is read PER KIT, right before the skit
+    // call, so a re-issued grant token is picked up (grant mode passes the istsg_
+    // token as the skit session → X-Session-Id on the kit tarball download).
+    // A plain string (legacy authorizeSession id) behaves exactly as before.
+    const skitOptionsFor = () => {
+        const sid = typeof sessionId === 'function' ? sessionId() : sessionId;
+        return {
+            ...(sid ? { sessionId: sid } : {}),
+            onProgress: (message) => {
+                console.log(chalk.gray(`${indent}  ${message}`));
+            },
+        };
+    };
     // Install packages in parallel using snapshot-parallel
     const entries = recordToEntries(packages);
     const parallelResult = await parallelInstall(entries, async (entry) => {
@@ -273,7 +412,11 @@ async function installSkitPackages(packages, snapshotName, indent, sessionId, re
         if (isSkitInstalled(entry.name, entry.version)) {
             return { success: true, skipped: true };
         }
-        const installResult = await installSkitPackage(entry.name, entry.version, skitOptions);
+        // Per-skit start log so a slow single install doesn't look frozen.
+        console.log(chalk.gray(`${indent}  installing ${entry.name}@${entry.version}…`));
+        const endKit = timingStart(`kit ${entry.name}@${entry.version}`);
+        const installResult = await installSkitPackage(entry.name, entry.version, skitOptionsFor());
+        endKit();
         return {
             success: installResult.success,
             error: installResult.error,
@@ -333,7 +476,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 (runCommand(installerConfig.hint)) {
+        if (await runCommand(installerConfig.hint)) {
             console.log(chalk.green(`${indent}  ✓ ${installerName} installed successfully`));
         }
         else {
@@ -353,6 +496,7 @@ async function installPackagesByType(packages, installerName, installers, snapsh
     if (isNpmInstaller) {
         // Batch install: collect all not-yet-installed packages and run a single npm install -g
         const toInstall = [];
+        const endProbe = timingStart(`layer already-installed probes (${entries.length})`);
         for (const entry of entries) {
             if (isNpmGlobalInstalled(entry.name, entry.version)) {
                 console.log(`${indent}${chalk.gray('skip')} ${entry.name}@${entry.version}${chalk.green(' (already installed)')}`);
@@ -362,11 +506,12 @@ async function installPackagesByType(packages, installerName, installers, snapsh
                 toInstall.push(entry);
             }
         }
+        endProbe();
         if (toInstall.length > 0) {
             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 = runCommand(batchCommand);
+            const success = await runCommand(batchCommand);
             // S3 — record the batch step (ok, or 'fallback' if it failed → retried below).
             recorder?.record({
                 phase: 'layer-batch',
@@ -389,7 +534,7 @@ 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 = runCommand(command);
+                    const ok = await runCommand(command);
                     recorder?.record({
                         phase: 'layer-fallback',
                         installer: installerName,
@@ -410,14 +555,18 @@ async function installPackagesByType(packages, installerName, installers, snapsh
         }
     }
     else {
-        // Non-npm installer: use parallel install as before
+        // Non-npm installer: run SERIALLY (concurrency 1). runCommand now spawns with
+        // stdio:'inherit', so concurrent children would interleave output on the same
+        // terminal AND race the module-global lastCommandError (mis-attributing the
+        // failure reason). Before the B change this path used sync execSync and was
+        // therefore effectively serial; concurrency:1 restores that (zero regression).
         const parallelResult = await parallelInstall(entries, async (entry) => {
             const pkgSpec = `${entry.name}@${entry.version}`;
             const command = installerConfig.command.replace('{pkg}', pkgSpec);
-            const success = runCommand(command);
+            const success = await runCommand(command);
             return { success, error: success ? undefined : `Command failed: ${command}` };
         }, {
-            concurrency: 4,
+            concurrency: 1,
             onProgress: (event) => {
                 const { result: r, current, total: t } = event;
                 const progress = `[${current}/${t}]`;
@@ -463,6 +612,32 @@ function applySnapshotOverrides(snapshot, overrides) {
     }
     return next;
 }
+// ============================================================
+// Grant transport token (grant-unify P1, SNAPSHOT_GRANT_MODE)
+// ============================================================
+// When a snapshot grant is active, EVERY registry-proxy snapshot fetch (incl.
+// extends bases) carries the istsg_ grant token explicitly — it takes precedence
+// over the license key / IST token resolution inside fetchSnapshotFromRepo.
+// null (always, in SNAPSHOT_GRANT_MODE=off) → the legacy call shape is kept.
+let activeGrantToken = null;
+/** Fetch an extends base snapshot (grant token when a grant is active). */
+function fetchBaseSnapshot(spec) {
+    return activeGrantToken ? fetchSnapshotFromRepo(spec, activeGrantToken) : fetchSnapshotFromRepo(spec);
+}
+/**
+ * Collect the extends chain of a snapshot as exact {name, version} specs (the
+ * ancestor generics). Grant mode only — used for the closure coverage check.
+ */
+async function collectExtendsChain(snapshot) {
+    const chain = [];
+    let cur = snapshot;
+    for (let depth = 0; cur.extends && depth < 16; depth++) {
+        const base = await fetchBaseSnapshot(cur.extends);
+        chain.push({ name: base.name, version: base.version });
+        cur = base;
+    }
+    return chain;
+}
 /**
  * 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
@@ -502,7 +677,7 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
         console.log('');
         console.log(chalk.cyan(`${indent}► Extends: ${snapshot.extends}`));
         try {
-            const baseSnapshot = await fetchSnapshotFromRepo(snapshot.extends);
+            const baseSnapshot = await fetchBaseSnapshot(snapshot.extends);
             console.log(chalk.gray(`${indent}  Installing base snapshot...`));
             const baseResult = await installSnapshot(baseSnapshot, depth + 1, installers, options);
             result.installed.push(...baseResult.result.installed);
@@ -589,21 +764,22 @@ 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, options.recorder);
+            await options.beforePhase?.(`kit:${snapshot.name}`);
+            const skitResult = await installSkitPackages(resolved.skit, snapshot.name, indent, (options.skitSessionId ?? 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, options.recorder);
+            const npmResult = await installPackagesByType(resolved.npm, npmInstaller, installers, snapshot.name, indent, 'npm packages', (options.skitSessionId ?? 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, options.recorder);
+            const genericResult = await installPackagesByType(resolved.generic, genericInstaller, installers, snapshot.name, indent, 'packages', (options.skitSessionId ?? options.sessionId), options.recorder);
             result.installed.push(...genericResult.installed);
             result.failed.push(...genericResult.failed);
         }
@@ -620,7 +796,8 @@ 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, options.recorder);
+                await options.beforePhase?.(`kit:${snapshot.name}`);
+                const skitResult = await installSkitPackages(packages, snapshot.name, indent, (options.skitSessionId ?? options.sessionId), options.recorder);
                 result.installed.push(...skitResult.installed);
                 result.failed.push(...skitResult.failed);
                 continue;
@@ -639,7 +816,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 (runCommand(installerConfig.hint)) {
+                if (await runCommand(installerConfig.hint)) {
                     console.log(chalk.green(`${indent}  ✓ ${installerName} installed successfully`));
                 }
                 else {
@@ -660,6 +837,7 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
             if (isNpmType) {
                 // Batch install: collect all not-yet-installed packages and run a single npm install -g
                 const toInstall = [];
+                const endProbe = timingStart(`layer already-installed probes (${installEntries.length})`);
                 for (const entry of installEntries) {
                     if (isNpmGlobalInstalled(entry.name, entry.version)) {
                         console.log(`${indent}${chalk.gray('skip')} ${entry.name}@${entry.version}${chalk.green(' (already installed)')}`);
@@ -669,11 +847,12 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
                         toInstall.push(entry);
                     }
                 }
+                endProbe();
                 if (toInstall.length > 0) {
                     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 = runCommand(batchCommand);
+                    const success = await runCommand(batchCommand);
                     // S3 — record the batch step (ok, or 'fallback' if it failed → retried below).
                     options.recorder?.record({
                         phase: 'layer-batch',
@@ -696,7 +875,7 @@ 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 = runCommand(command);
+                            const ok = await runCommand(command);
                             options.recorder?.record({
                                 phase: 'layer-fallback',
                                 installer: installerName,
@@ -717,14 +896,16 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
                 }
             }
             else {
-                // Non-npm installer: use parallel install as before
+                // Non-npm installer: run SERIALLY (concurrency 1) — see rationale above:
+                // spawn(stdio:'inherit') children would interleave terminal output and
+                // race the global lastCommandError. Restores the pre-B serial behavior.
                 const parallelResult = await parallelInstall(installEntries, async (entry) => {
                     const pkgSpec = `${entry.name}@${entry.version}`;
                     const command = installCfg.command.replace('{pkg}', pkgSpec);
-                    const success = runCommand(command);
+                    const success = await runCommand(command);
                     return { success, error: success ? undefined : `Command failed: ${command}` };
                 }, {
-                    concurrency: 4,
+                    concurrency: 1,
                     onProgress: (event) => {
                         const { result: r, current, total: t } = event;
                         const progress = `[${current}/${t}]`;
@@ -759,7 +940,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 (runCommand(installerConfig.hint)) {
+            if (await runCommand(installerConfig.hint)) {
                 console.log(chalk.green(`${indent}  ✓ glpkg installed successfully`));
             }
             else {
@@ -774,13 +955,15 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
         else {
             const legacyEntries = recordToEntries(snapshot.packages);
             const legacyCfg = installerConfig; // capture for closure
+            // Legacy glpkg packages: run SERIALLY (concurrency 1) — see rationale above
+            // (spawn:'inherit' output interleave + global lastCommandError race).
             const parallelResult = await parallelInstall(legacyEntries, async (entry) => {
                 const pkgSpec = `${entry.name}@${entry.version}`;
                 const command = legacyCfg.command.replace('{pkg}', pkgSpec);
-                const success = runCommand(command);
+                const success = await runCommand(command);
                 return { success, error: success ? undefined : `Command failed: ${command}` };
             }, {
-                concurrency: 4,
+                concurrency: 1,
                 onProgress: (event) => {
                     const { result: r, current, total: t } = event;
                     const progress = `[${current}/${t}]`;
@@ -806,7 +989,8 @@ export async function installSnapshot(snapshot, depth = 0, parentInstallers = {}
     }
     // 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, options.recorder);
+        await options.beforePhase?.(`kit:${snapshot.name}`);
+        const skitResult = await installSkitPackages(snapshot.skits, snapshot.name, indent, (options.skitSessionId ?? options.sessionId), options.recorder);
         result.installed.push(...skitResult.installed);
         result.failed.push(...skitResult.failed);
     }
@@ -846,7 +1030,7 @@ async function collectAllNpmPackages(snapshot, useProxy = true) {
     // Recurse into extends chain
     if (snapshot.extends) {
         try {
-            const baseSnapshot = await fetchSnapshotFromRepo(snapshot.extends);
+            const baseSnapshot = await fetchBaseSnapshot(snapshot.extends);
             const baseNpmPackages = await collectAllNpmPackages(baseSnapshot, useProxy);
             // Base packages: don't override current snapshot's versions
             for (const [name, version] of Object.entries(baseNpmPackages)) {
@@ -883,7 +1067,7 @@ export async function collectAllPackages(snapshot) {
     // Recurse into extends chain
     if (snapshot.extends) {
         try {
-            const baseSnapshot = await fetchSnapshotFromRepo(snapshot.extends);
+            const baseSnapshot = await fetchBaseSnapshot(snapshot.extends);
             const basePackages = await collectAllPackages(baseSnapshot);
             Object.assign(allPackages, basePackages);
         }
@@ -996,7 +1180,7 @@ async function runReplaceMode(snapshotName, newSet, options, installers) {
             continue;
         }
         console.log(chalk.gray(`  Removing ${item.name}...`));
-        if (runCommand(cmd)) {
+        if (await runCommand(cmd)) {
             console.log(`    ${item.name}${chalk.green(' ✓ removed')}`);
             removed.push(item);
         }
@@ -1057,6 +1241,9 @@ 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 = {}) {
+    // Start from a clean downgrade-policy context; the pre-install guard publishes
+    // the resolved mode below, and cleanup() clears it on every exit path.
+    setActiveDowngradeMode(undefined);
     console.log(chalk.blue.bold(`
 ╔══════════════════════════════════════════════════════════════╗
 ║                    Snapshot Installer                        ║
@@ -1106,11 +1293,90 @@ export async function installCommand(name, options = {}) {
         console.log(chalk.yellow('⚠') + ' No auth token — anonymous access');
     }
     const useProxy = true;
+    // ========== Snapshot grant (grant-unify P1, SNAPSHOT_GRANT_MODE) ==========
+    // off (default): nothing below runs (grant stays null) — legacy path.
+    // prefer/require: request ONE istsg_ grant BEFORE fetching snapshot.json, since
+    // the root generic itself is a closure member the proxy may gate. The grant is
+    // always for an EXACT version: none/'latest' is resolved first with the proxy
+    // rule (highest stable, prereleases ignored — same as the legacy path's
+    // 'latest'); license-api's own 'latest' (= newest upload) is never used. prefer drops
+    // the grant on any grant failure and runs the whole install on the legacy
+    // path; require is fail-loud. dry-run + prefer skips the grant (zero side
+    // effects); dry-run + require still needs it to fetch the snapshot.
+    activeGrantToken = null;
+    const grantMode = readGrantMode(process.env, (m) => console.log(chalk.yellow('⚠ ' + m)));
+    const { name: snapshotBaseName, version: requestedVersion } = splitSnapshotSpec(name);
+    let grant = null;
+    let grantEnvActive = false;
+    /** Grant failure policy: require → exit 1; prefer → warn, drop grant, legacy path. */
+    const onGrantFailure = (err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (grantMode === 'require') {
+            console.log(chalk.red(`⛔ Snapshot grant failed (SNAPSHOT_GRANT_MODE=require): ${msg}`));
+            process.exit(1);
+        }
+        console.log(chalk.yellow(`⚠ Snapshot grant unavailable — continuing on the legacy path: ${msg}`));
+        grant = null;
+        activeGrantToken = null;
+    };
+    if (grantMode !== 'off' && !(options.dryRun && grantMode === 'prefer')) {
+        const timeoutMs = readGrantTimeoutMs();
+        let grantVersion = null;
+        try {
+            grantVersion = await resolveInstallVersion(snapshotBaseName, requestedVersion, {
+                registryUrl: REGISTRY_PROXY_URL,
+                timeoutMs,
+            });
+        }
+        catch (err) {
+            onGrantFailure(err);
+        }
+        if (grantVersion) {
+            grant = new GrantState({ snapshot: snapshotBaseName, version: grantVersion, authToken }, {
+                request: (req) => requestSnapshotGrant(req, { licenseApiUrl: LICENSE_API_URL, timeoutMs }),
+                onToken: (token) => {
+                    activeGrantToken = token;
+                    if (grantEnvActive)
+                        process.env.IST_SESSION_TOKEN = token;
+                },
+            });
+            console.log(chalk.gray(`Requesting snapshot grant (${grantMode}) for ${snapshotBaseName}@${grantVersion}...`));
+            try {
+                const g = await grant.issue();
+                // The closure root (when present) must be exactly the version we asked for.
+                const rootVersion = findRootMemberVersion(g.members, snapshotBaseName);
+                if (rootVersion && rootVersion !== grantVersion) {
+                    throw new GrantError('version-mismatch', `grant closure root ${snapshotBaseName}@${rootVersion} differs from the requested ${grantVersion}`);
+                }
+                console.log(chalk.green('✓') + ' ' + formatGrantLog(grantMode, g));
+            }
+            catch (err) {
+                onGrantFailure(err);
+            }
+        }
+    }
+    // ==========================================================================
     // Fetch snapshot first — access check depends on snapshot.json content
     console.log(chalk.gray('Fetching snapshot...'));
     let snapshot;
     try {
-        snapshot = await fetchSnapshotFromRepo(name, authToken);
+        if (grant) {
+            // Grant mode: fetch exactly the granted version with the grant token.
+            const grantVersion = grant.version;
+            try {
+                snapshot = await fetchSnapshotFromRepo(`${snapshotBaseName}@${grantVersion}`, activeGrantToken);
+                if (snapshot.version !== grantVersion) {
+                    throw new GrantError('version-mismatch', `snapshot ${snapshotBaseName}@${snapshot.version} does not match the granted version ${grantVersion}`);
+                }
+            }
+            catch (err) {
+                onGrantFailure(err);
+                snapshot = await fetchSnapshotFromRepo(name, authToken);
+            }
+        }
+        else {
+            snapshot = await fetchSnapshotFromRepo(name, authToken);
+        }
     }
     catch (error) {
         const errMsg = error instanceof Error ? error.message : String(error);
@@ -1180,8 +1446,13 @@ export async function installCommand(name, options = {}) {
     const isAuthenticatedAccess = accessField === 'authenticated';
     const isLicensedAccess = !!accessField && typeof accessField === 'object' && accessField.type === 'licensed';
     // --- IST Login Check ---
-    const istCredentials = getIstCredentials();
-    if (istCredentials?.userId) {
+    // Single auth verdict: isLoggedIn() = the same credential SSOT that resolved
+    // authToken above (env IST_SESSION_TOKEN or ~/.ist/credentials.json .token,
+    // locally unexpired) and that the 'IST Credentials' prerequisite uses. The old
+    // check read credentials.json .userId, so a token-authenticated install could
+    // print "✓ Auth: IST token" AND "⚠ No IST login" in the same run.
+    const istCredentials = getIstCredentials(); // telemetry identity only (userId/email)
+    if (isLoggedIn()) {
         console.log(chalk.green('✓') + ' IST login verified');
     }
     else if (isPublicAccess) {
@@ -1242,9 +1513,39 @@ export async function installCommand(name, options = {}) {
         console.log(chalk.green('✓') + ` License verified for ${productId}`);
     }
     // =======================================================================
+    // ========== Grant closure coverage (grant mode only) ==========
+    // members[] is the ALLOWED set: every exact pin we will install (flattened
+    // across the extends chain, --pin applied) plus the extends ancestors must be
+    // a closure member, or the proxy would 401 mid-install. A --pin outside the
+    // closure is refused up front (both modes, logged in or not). A manifest pin
+    // outside it is a grant/index inconsistency: prefer → legacy path, require → exit.
+    if (grant) {
+        const g = grant.current;
+        const expectedPins = applyPinOverrides(await collectAllPackages(snapshot), overrides);
+        let ancestors = [];
+        try {
+            ancestors = await collectExtendsChain(snapshot);
+        }
+        catch (err) {
+            onGrantFailure(err);
+        }
+        if (grant) {
+            const coverage = checkGrantCoverage([...Object.entries(expectedPins).map(([n, v]) => ({ name: n, version: v })), ...ancestors], g.members);
+            if (!coverage.ok) {
+                const pinViolations = coverage.missing.filter((spec) => Object.entries(overrides).some(([n, v]) => spec === `${n}@${v}`));
+                if (pinViolations.length > 0) {
+                    console.log(chalk.red(`⛔ --pin outside the snapshot grant closure: ${pinViolations.join(', ')}`));
+                    console.log(chalk.gray('   A pinned version must be part of this snapshot version\'s frozen closure.'));
+                    process.exit(1);
+                }
+                onGrantFailure(new GrantError('invalid-response', `grant closure does not cover ${coverage.missing.length} manifest pin(s): ${coverage.missing.join(', ')}`));
+            }
+        }
+    }
     // ========== Authorize Session with Registry Proxy ==========
     let sessionId;
-    if (authToken) {
+    // Grant mode: the istsg_ grant replaces authorizeSession (one transport token).
+    if (authToken && !grant) {
         // Collect all packages for session authorization
         const sessionPackages = [];
         // From snapshot.install
@@ -1268,7 +1569,7 @@ export async function installCommand(name, options = {}) {
             console.log(chalk.gray(`  Auth type: ${authType}`));
             try {
                 sessionId = await authorizeSession(authToken, name, sessionPackages);
-                console.log(chalk.green('✓') + ' Session authorized: ' + sessionId);
+                console.log(chalk.green('✓') + ' Session authorized: ' + maskSessionId(sessionId));
             }
             catch (error) {
                 const errMsg = error instanceof Error ? error.message : String(error);
@@ -1286,7 +1587,15 @@ export async function installCommand(name, options = {}) {
     if (useProxy) {
         const scopes = extractScopes(allPackages);
         if (scopes.length > 0) {
-            if (authToken) {
+            if (grant) {
+                // Grant mode: the istsg_ token is the proxy transport token for npm and
+                // skit (kit npm deps read ${IST_SESSION_TOKEN}). Re-issues update it.
+                process.env.IST_SESSION_TOKEN = grant.current.token;
+                grantEnvActive = true;
+                console.log(chalk.gray(`Configuring registry-proxy (snapshot grant) for scopes: ${scopes.join(', ')}`));
+                npmrcBackup = configureNpmrcForProxy(scopes);
+            }
+            else if (authToken) {
                 // 환경변수에 설정 (npm이 .npmrc의 ${IST_SESSION_TOKEN}을 해석)
                 process.env.IST_SESSION_TOKEN = authToken;
                 console.log(chalk.gray(`Configuring registry-proxy for scopes: ${scopes.join(', ')}`));
@@ -1316,6 +1625,11 @@ export async function installCommand(name, options = {}) {
             console.log(chalk.gray('Restored .npmrc'));
         }
         delete process.env.IST_SESSION_TOKEN;
+        activeGrantToken = null;
+        grantEnvActive = false;
+        // Clear the threaded downgrade mode so it never leaks to a later install
+        // (the exec boundary self-resolves again when no context is published).
+        setActiveDowngradeMode(undefined);
     };
     const onSignal = (signal) => {
         console.log(chalk.yellow(`\nReceived ${signal} — restoring .npmrc before exit...`));
@@ -1326,6 +1640,28 @@ export async function installCommand(name, options = {}) {
     };
     process.once('SIGINT', onSignal);
     process.once('SIGTERM', onSignal);
+    // grant-unify P1 — re-issue the snapshot grant before a long phase when its
+    // remaining TTL is low (GrantState.ensureFresh). The new token reaches npm and
+    // skit through IST_SESSION_TOKEN (onToken). A re-issue failure: require →
+    // throw (fail-loud; callers inside the install try/finally clean up), prefer →
+    // warn and keep the current token. No-op without an active grant (off mode).
+    const refreshGrant = async (phase) => {
+        if (!grant)
+            return;
+        const st = grant;
+        try {
+            if (await st.ensureFresh()) {
+                console.log(chalk.gray(`  ↻ Grant re-issued before ${phase}: ${formatGrantLog(grantMode, st.current)}`));
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (grantMode === 'require') {
+                throw new Error(`Snapshot grant re-issue failed before ${phase}: ${msg}`);
+            }
+            console.log(chalk.yellow(`  ⚠ Snapshot grant re-issue failed before ${phase} — keeping the current grant: ${msg}`));
+        }
+    };
     // Determine which installers to use
     const effectiveInstallers = { ...DEFAULT_INSTALLERS };
     if (useProxy) {
@@ -1351,11 +1687,56 @@ export async function installCommand(name, options = {}) {
         console.log(chalk.yellow(`⚠ --pin ignored for package(s) not in this snapshot: ${unmatched.join(', ')}`));
     }
     const npmEntries = Object.entries(effectiveNpmMap);
+    // ========== Downgrade guard (dev-isolation) ==========
+    // A snapshot bundles OLDER stable versions. On a dev machine whose global
+    // tooling is already NEWER, installing would `npm i -g {pkg}@{pinned}` and
+    // DOWNGRADE it, breaking the environment. Detect at THIS boundary — the map is
+    // now flattened across the whole extends chain (effectiveNpmMap), and NO npm
+    // exec has happened yet (the pre-install batch is below). A clean Docker
+    // sandbox has nothing installed globally → zero offenders → auto-pass, no
+    // config needed. Policy precedence (highest wins): CLI --allow-downgrade / env
+    // SNAPSHOT_ALLOW_LOCAL=1 → machine config → snapshot.policy.onDowngrade →
+    // default 'refuse'. Side effects live in @microwiseai/snapshot-downgrade-guard
+    // via injection (readVersion), keeping that package pure.
+    {
+        const { wouldDowngrade, offenders } = detectDowngrades(effectiveNpmMap, {
+            readVersion: readInstalledNpmVersion,
+        });
+        // Resolve the policy ONCE with full context (incl. snapshot.json policy) and
+        // publish it so the downstream npm-exec boundary (runCommand/runCommandSync)
+        // REUSES it instead of recomputing — one decision for the whole install, and
+        // the boundary won't re-report the same downgrade.
+        const mode = resolveDowngradePolicy({
+            override: readOneShotOverride({
+                env: process.env,
+                allowDowngradeFlag: options.allowDowngrade === true,
+            }),
+            machine: getMachineDowngradeMode(),
+            snapshot: snapshot.policy?.onDowngrade,
+        });
+        setActiveDowngradeMode(mode);
+        if (wouldDowngrade) {
+            if (mode === 'refuse') {
+                // Nothing installed yet — restore .npmrc / unset token, then fail-loud
+                // with a non-zero exit and ZERO partial install.
+                cleanup();
+                console.log('');
+                console.log(chalk.red(formatDowngradeReport(offenders, mode)));
+                process.exit(1);
+            }
+            else if (mode === 'warn') {
+                console.log('');
+                console.log(chalk.yellow(formatDowngradeReport(offenders, mode)));
+            }
+            // mode === 'allow' → proceed silently.
+        }
+    }
     if (npmEntries.length > 0) {
         console.log('');
         console.log(chalk.cyan(`► Pre-installing ${npmEntries.length} npm packages from entire extends chain...`));
         // Filter out already-installed packages
         const toInstall = [];
+        const endProbe = timingStart(`pre-install already-installed probes (${npmEntries.length})`);
         for (const [name, version] of npmEntries) {
             if (isNpmGlobalInstalled(name, version)) {
                 console.log(`  ${chalk.gray('skip')} ${name}@${version}${chalk.green(' (already installed)')}`);
@@ -1364,11 +1745,23 @@ export async function installCommand(name, options = {}) {
                 toInstall.push({ name, version });
             }
         }
+        endProbe();
         if (toInstall.length > 0) {
             const specs = toInstall.map(e => `${e.name}@${e.version}`);
             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);
+            try {
+                await refreshGrant('pre-install batch');
+            }
+            catch (err) {
+                // Outside the install try/finally: restore .npmrc / token, then fail loud.
+                cleanup();
+                console.log(chalk.red(`⛔ ${err instanceof Error ? err.message : String(err)}`));
+                process.exit(1);
+            }
+            const endBatch = timingStart(`pre-install batch (${specs.length})`);
+            console.log(chalk.cyan(`  ► Installing ${specs.length} npm package(s) in one batch… (수십초 걸릴 수 있음, npm 진행이 아래에 표시됩니다)`));
+            const batchSuccess = await runCommand(npmCommand);
+            endBatch();
             // 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({
@@ -1393,7 +1786,7 @@ 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 = runCommand(cmd);
+                    const ok = await runCommand(cmd);
                     recorder.record({
                         phase: 'pre-install-fallback',
                         installer: 'npm-proxy',
@@ -1430,33 +1823,44 @@ export async function installCommand(name, options = {}) {
     try {
         // Auto-detect 모드: snapshot.install이 없으면 자동 판별
         const autoDetect = !snapshot.install;
+        const endLayers = timingStart('installSnapshot (layers + kits)');
         const installResult = await installSnapshot(snapshot, 0, effectiveInstallers, {
             useProxy,
             autoDetect,
             sessionId,
             recorder,
             overrides,
+            ...(grant ? { beforePhase: refreshGrant, skitSessionId: () => activeGrantToken ?? undefined } : {}),
         });
         result = installResult.result;
+        endLayers();
         // ===== 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' });
+            // Re-pin ALL diverged packages in a round with a SINGLE `npm install -g`
+            // (batched) and record it as one ledger step carrying every spec. This
+            // collapses N sequential global installs per round into one npm spawn.
+            const repinMany = (phase) => (pkgs) => {
+                if (pkgs.length === 0)
+                    return;
+                const specs = pkgs.map((p) => `${p.name}@${p.version}`);
+                const cmd = `npm install -g ${specs.join(' ')}`;
+                console.log(chalk.gray(`  ► Re-pinning ${specs.length} package(s) in one batch (npm install -g … — 수십초 걸릴 수 있음)`));
+                // Sync streaming: invoked from the pure/sync runConverge callback.
+                const ok = runCommandSync(cmd);
+                recorder.record({ phase, installer: 'npm-proxy', command: cmd, specs, result: ok ? 'ok' : 'failed' });
             };
+            await refreshGrant('verify/converge');
+            const endVerify = timingStart('verify/converge');
             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'),
+                    installMany: repinMany('converge'),
                     readVersion: readInstalledNpmVersion,
                     maxRounds: 3,
                 });
@@ -1471,13 +1875,14 @@ export async function installCommand(name, options = {}) {
                     console.log('');
                     console.log(chalk.cyan(`► Holding ${Object.keys(pinTargets).length} pinned package(s) to the override version...`));
                     runConverge(pinTargets, {}, {
-                        install: repin('pin-converge'),
+                        installMany: repinMany('pin-converge'),
                         readVersion: readInstalledNpmVersion,
                         maxRounds: 3,
                     });
                 }
                 verification = verifyInstallMap(effectiveNpmMap, { readVersion: readInstalledNpmVersion });
             }
+            endVerify();
         }
     }
     catch (err) {
@@ -1569,6 +1974,16 @@ export async function installCommand(name, options = {}) {
             // verification shape { ok, verifiedCount, total, mismatches[{name,expected,got}] }.
             if (verification)
                 ledger.verification = verification;
+            // grant-unify P1 — grant provenance (no token). Absent in off mode.
+            if (grant) {
+                const st = grant;
+                ledger.grant = {
+                    mode: grantMode,
+                    closureHash: st.current.closureHash.slice(0, 8),
+                    memberCount: st.current.members.length,
+                    reissues: st.reissues,
+                };
+            }
             // AC1.4 — fold the core-floor verdict too.
             ledger.coreFloor = {
                 ok: coreFloor.ok,