@microwiseai/snapshot 0.5.0 → 0.5.2

package/dist/commands/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/commands/install.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAiBjE,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAkeD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,KAAK,GAAE,MAAU,EACjB,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAM,EACtD,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;CAAE,CAAC,CA8VjF;AA4FD,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAoLD,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAuZrG"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/commands/install.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAwBjE,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAsmBD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,KAAK,GAAE,MAAU,EACjB,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAM,EACtD,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;CAAE,CAAC,CA8VjF;AA4FD,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAoLD,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CA0brG"}

package/dist/commands/install.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
-import { execSync } from 'child_process';
-import { writeFileSync, existsSync, readFileSync, unlinkSync } from 'fs';
+import { execSync, spawn } from 'child_process';
+import { writeFileSync, existsSync, readFileSync, unlinkSync, mkdirSync } from 'fs';
 import { homedir, platform, arch } from 'os';
 import { join } from 'path';
 import { fetchSnapshotFromRepo, snapshotNameToRepoName } from '../lib/gitlab.js';
@@ -14,6 +14,12 @@ 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 });
 // CLI version — dynamically read from package.json (SSOT)
 import { createRequire } from 'module';
 const _require = createRequire(import.meta.url);
@@ -194,27 +200,74 @@ 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;
-    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;
-    }
+    // 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);
+        });
+    });
 }
 /**
  * Check if a skit package is already installed with the specified version
@@ -247,6 +300,71 @@ 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 사용
@@ -257,6 +375,10 @@ async function installSkitPackages(packages, snapshotName, indent, sessionId) {
     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 ===`));
@@ -269,7 +391,14 @@ 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,
@@ -321,7 +450,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 {
@@ -354,7 +483,7 @@ 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 = runCommand(batchCommand);
+            const success = await runCommand(batchCommand);
             if (success) {
                 for (const spec of specs) {
                     console.log(`${indent}${chalk.blue('batch')} ${spec}...${chalk.green(' ✓')}`);
@@ -369,7 +498,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);
                     if (ok) {
                         console.log(`${indent}${chalk.blue('fallback')} ${pkgSpec}...${chalk.green(' ✓')}`);
                         result.installed.push(pkgSpec);
@@ -387,7 +516,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 = runCommand(command);
+            const success = await runCommand(command);
             return { success, error: success ? undefined : `Command failed: ${command}` };
         }, {
             concurrency: 4,
@@ -562,7 +691,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 {
@@ -596,7 +725,7 @@ 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 = runCommand(batchCommand);
+                    const success = await runCommand(batchCommand);
                     if (success) {
                         for (const spec of specs) {
                             console.log(`${indent}${chalk.blue('batch')} ${spec}...${chalk.green(' ✓')}`);
@@ -611,7 +740,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);
                             if (ok) {
                                 console.log(`${indent}${chalk.blue('fallback')} ${pkgSpec}...${chalk.green(' ✓')}`);
                                 result.installed.push(pkgSpec);
@@ -629,7 +758,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 = runCommand(command);
+                    const success = await runCommand(command);
                     return { success, error: success ? undefined : `Command failed: ${command}` };
                 }, {
                     concurrency: 4,
@@ -659,7 +788,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 {
@@ -677,7 +806,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 = runCommand(command);
+                const success = await runCommand(command);
                 return { success, error: success ? undefined : `Command failed: ${command}` };
             }, {
                 concurrency: 4,
@@ -888,7 +1017,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);
         }
@@ -949,6 +1078,10 @@ 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                        ║
@@ -982,6 +1115,7 @@ 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';
@@ -998,13 +1132,16 @@ 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
@@ -1019,6 +1156,7 @@ 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}`));
@@ -1051,6 +1189,10 @@ export async function installCommand(name, options = {}) {
     // the authToken injection point (IST_SESSION_TOKEN env / getProxyAuthToken).
     const istCredentials = getIstCredentials();
     // --- 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) {
@@ -1097,8 +1239,10 @@ 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
@@ -1134,8 +1278,10 @@ 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;
@@ -1155,6 +1301,7 @@ 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
@@ -1192,6 +1339,8 @@ export async function installCommand(name, options = {}) {
     // ========== 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);
     if (npmEntries.length > 0) {
@@ -1209,9 +1358,10 @@ 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 = runCommand(npmCommand);
+            const batchSuccess = await runCommand(npmCommand);
             if (batchSuccess) {
                 for (const spec of specs) {
                     console.log(`  ${chalk.blue('batch')} ${spec}...${chalk.green(' ✓')}`);
@@ -1227,7 +1377,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);
                     if (ok) {
                         console.log(`  ${chalk.blue('fallback')} ${pkgSpec}...${chalk.green(' ✓')}`);
                     }
@@ -1241,11 +1391,13 @@ 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' });
     try {
         // Auto-detect 모드: snapshot.install이 없으면 자동 판별
         const autoDetect = !snapshot.install;
@@ -1260,6 +1412,11 @@ export async function installCommand(name, options = {}) {
         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.
@@ -1268,6 +1425,7 @@ 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);
     }
@@ -1314,6 +1472,9 @@ 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();
     // Send telemetry (fire and forget)
     sendInstallTelemetry({
         package: snapshot.name,