labgate 0.5.43 → 0.5.45

package/dist/lib/container.js

@@ -42,7 +42,9 @@ exports.imageToSifName = imageToSifName;
 exports.isUsableApptainerSif = isUsableApptainerSif;
 exports.ensureSifImage = ensureSifImage;
 exports.resolveSlurmProxyPathToHost = resolveSlurmProxyPathToHost;
+exports.listenOnUnixSocket = listenOnUnixSocket;
 exports.buildCodexOauthPublishSpec = buildCodexOauthPublishSpec;
+exports.describeCliStartupPhase = describeCliStartupPhase;
 exports.buildEntrypoint = buildEntrypoint;
 exports.setupBrowserHook = setupBrowserHook;
 exports.getAgentTokenEnv = getAgentTokenEnv;
@@ -713,6 +715,8 @@ function imageToSifName(image) {
     return `${readable}-${hash}.sif`;
 }
 const APPTAINER_SIF_INSPECT_TIMEOUT_MS = 15_000;
+const SLOW_APPTAINER_SIF_INSPECT_WARN_MS = 5_000;
+const SLOW_IMAGE_PULL_LOCK_WAIT_WARN_MS = 5_000;
 function isUsableApptainerSif(runtime, sifPath) {
     if (!(0, fs_1.existsSync)(sifPath))
         return false;
@@ -731,19 +735,36 @@ function isUsableApptainerSif(runtime, sifPath) {
  * Ensure a SIF image exists in the cache directory.
  * Pulls from docker:// URI if not already cached.
  */
-async function ensureSifImage(runtime, image) {
+async function ensureSifImage(runtime, image, hooks = {}) {
+    const recordTiming = (label, startedAt) => {
+        hooks.onTiming?.(label, Math.max(0, Date.now() - startedAt));
+    };
     const imagesDir = (0, config_js_1.getImagesDir)();
     (0, fs_1.mkdirSync)(imagesDir, { recursive: true });
     const sifPath = (0, path_1.join)(imagesDir, imageToSifName(image));
     const pullLockPath = `${sifPath}.pull.lock`;
-    if (isUsableApptainerSif(runtime, sifPath) && !(0, fs_1.existsSync)(pullLockPath)) {
+    const initialInspectStartedAt = Date.now();
+    const initialCacheHit = isUsableApptainerSif(runtime, sifPath);
+    recordTiming('image_prepare_sif_cache_inspect', initialInspectStartedAt);
+    if (Math.max(0, Date.now() - initialInspectStartedAt) >= SLOW_APPTAINER_SIF_INSPECT_WARN_MS) {
+        hooks.onWarning?.('slow_sif_cache_inspect');
+    }
+    if (initialCacheHit && !(0, fs_1.existsSync)(pullLockPath)) {
         return sifPath;
     }
+    let pullLockTimingRecorded = false;
     try {
         await (0, image_pull_lock_js_1.withImagePullFileLock)(pullLockPath, image, async () => {
-            if (isUsableApptainerSif(runtime, sifPath))
+            const reInspectStartedAt = Date.now();
+            const cacheHitAfterLock = isUsableApptainerSif(runtime, sifPath);
+            recordTiming('image_prepare_sif_cache_reinspect', reInspectStartedAt);
+            if (Math.max(0, Date.now() - reInspectStartedAt) >= SLOW_APPTAINER_SIF_INSPECT_WARN_MS) {
+                hooks.onWarning?.('slow_sif_cache_reinspect');
+            }
+            if (cacheHitAfterLock)
                 return;
             if ((0, fs_1.existsSync)(sifPath)) {
+                hooks.onWarning?.('cached_sif_failed_validation');
                 log.warn(`Cached SIF for ${log.dim(image)} failed validation. Re-pulling image.`);
                 try {
                     (0, fs_1.rmSync)(sifPath, { force: true });
@@ -755,10 +776,19 @@ async function ensureSifImage(runtime, image) {
             const tempSifPath = `${sifPath}.tmp-${process.pid}-${(0, crypto_1.randomBytes)(6).toString('hex')}`;
             log.info(`Pulling image ${log.dim(image)}`);
             try {
+                hooks.onHint?.('sif_pull_required');
+                const pullStartedAt = Date.now();
                 (0, child_process_1.execFileSync)(runtime, ['pull', tempSifPath, `docker://${image}`], {
                     stdio: 'inherit',
                 });
-                if (!isUsableApptainerSif(runtime, tempSifPath)) {
+                recordTiming('image_prepare_sif_pull', pullStartedAt);
+                const validatePulledStartedAt = Date.now();
+                const pulledSifUsable = isUsableApptainerSif(runtime, tempSifPath);
+                recordTiming('image_prepare_sif_pull_validate', validatePulledStartedAt);
+                if (Math.max(0, Date.now() - validatePulledStartedAt) >= SLOW_APPTAINER_SIF_INSPECT_WARN_MS) {
+                    hooks.onWarning?.('slow_sif_pull_validate');
+                }
+                if (!pulledSifUsable) {
                     throw new Error(`Pulled SIF failed validation: ${tempSifPath}`);
                 }
                 (0, fs_1.renameSync)(tempSifPath, sifPath);
@@ -772,6 +802,13 @@ async function ensureSifImage(runtime, image) {
                 }
             }
         }, {
+            onAcquired: ({ waitedMs }) => {
+                pullLockTimingRecorded = true;
+                hooks.onTiming?.('image_prepare_pull_lock_wait', waitedMs);
+                if (waitedMs >= SLOW_IMAGE_PULL_LOCK_WAIT_WARN_MS) {
+                    hooks.onWarning?.('slow_image_pull_lock_wait');
+                }
+            },
             onWait: ({ owner }) => {
                 const ownerLabel = owner && owner !== 'unknown' ? ` (owner: ${owner})` : '';
                 log.step(`Waiting for shared image pull lock for ${log.dim(image)}${ownerLabel}...`);
@@ -789,6 +826,9 @@ async function ensureSifImage(runtime, image) {
         console.error(String(msg).trim().slice(0, 500));
         process.exit(1);
     }
+    if (!pullLockTimingRecorded) {
+        hooks.onTiming?.('image_prepare_pull_lock_wait', 0);
+    }
     return sifPath;
 }
 function ensurePodmanImage(runtime, image) {
@@ -1018,7 +1058,32 @@ function mapSlurmProxyArgsToHost(session, args, containerCwd) {
     }
     return { ok: true, args: mappedArgs };
 }
-function startSlurmHostProxy(session) {
+async function listenOnUnixSocket(server, socketHostPath) {
+    await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            server.off('error', onError);
+            server.off('listening', onListening);
+        };
+        const onError = (err) => {
+            cleanup();
+            reject(err);
+        };
+        const onListening = () => {
+            cleanup();
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        try {
+            server.listen(socketHostPath);
+        }
+        catch (err) {
+            cleanup();
+            reject(err);
+        }
+    });
+}
+async function startSlurmHostProxy(session) {
     const sandboxHome = (0, config_js_1.getSandboxHome)();
     const socketHostDir = (0, path_1.join)(sandboxHome, '.labgate', 'slurm', 'host-proxy');
     const socketHostPath = (0, path_1.join)(socketHostDir, 'slurm.sock');
@@ -1141,10 +1206,14 @@ function startSlurmHostProxy(session) {
         log.warn(`SLURM host proxy server error: ${err?.message ?? String(err)}`);
     });
     try {
-        server.listen(socketHostPath);
+        await listenOnUnixSocket(server, socketHostPath);
     }
     catch (err) {
         log.warn(`Could not start SLURM host proxy: ${err?.message ?? String(err)}`);
+        try {
+            server.close();
+        }
+        catch { /* ignore */ }
         try {
             (0, fs_1.unlinkSync)(socketHostPath);
         }
@@ -1276,7 +1345,9 @@ const DEFAULT_CODEX_OAUTH_CALLBACK_PORT = 1455;
 const CODEX_OAUTH_STARTUP_HEARTBEAT_MS = 10_000;
 const CODEX_OAUTH_STARTUP_HEARTBEAT_MAX_MS = 50_000;
 const CODEX_OAUTH_STARTUP_SPINNER_MS = 125;
-const CODEX_OAUTH_STARTUP_SPINNER_FRAMES = ['|', '/', '-', '\\'];
+const CLI_STARTUP_SPINNER_FRAMES = ['|', '/', '-', '\\'];
+const CLI_STARTUP_SPINNER_MS = 120;
+const CLI_STARTUP_HEARTBEAT_MS = 5_000;
 const DEFERRED_SLURM_PASSTHROUGH_DELAY_MS = 1_500;
 function getCodexOauthCallbackPort() {
     const raw = (process.env.LABGATE_CODEX_OAUTH_CALLBACK_PORT || '').trim();
@@ -1305,6 +1376,64 @@ function buildCodexOauthPublishSpec(port) {
     // Publishing without an explicit host IP gives dual-stack localhost reachability.
     return `${port}:${port}`;
 }
+function describeCliStartupPhase(agent, phase, runtime) {
+    const agentLabel = String(agent || '').trim().toLowerCase() === 'codex' ? 'Codex' : 'Claude';
+    if (phase === 'image') {
+        if (runtime === 'apptainer')
+            return `Preparing ${agentLabel} Apptainer sandbox`;
+        if (runtime === 'podman')
+            return `Preparing ${agentLabel} container sandbox`;
+        return `Preparing ${agentLabel} sandbox`;
+    }
+    return `Launching ${agentLabel} inside sandbox`;
+}
+function startCliStartupHeartbeat(agent, phase, runtime) {
+    const startedAt = Date.now();
+    let stopped = false;
+    let sawOutput = false;
+    let interval = null;
+    let spinnerFrame = 0;
+    let currentPhase = phase;
+    const useSpinner = !!(process.stderr.isTTY && process.stdout.isTTY);
+    const render = () => {
+        const elapsedSeconds = Math.max(1, Math.floor((Date.now() - startedAt) / 1000));
+        const message = describeCliStartupPhase(agent, currentPhase, runtime);
+        if (useSpinner) {
+            const frame = CLI_STARTUP_SPINNER_FRAMES[spinnerFrame];
+            spinnerFrame = (spinnerFrame + 1) % CLI_STARTUP_SPINNER_FRAMES.length;
+            process.stderr.write(`\r\x1b[2K${log.dim('›')} ${message}... ${frame} ${elapsedSeconds}s`);
+            return;
+        }
+        log.step(`${message}... (${elapsedSeconds}s elapsed)`);
+    };
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        if (interval) {
+            clearInterval(interval);
+            interval = null;
+        }
+        if (useSpinner)
+            process.stderr.write('\r\x1b[2K');
+    };
+    const noteOutput = (data) => {
+        if (stopped || sawOutput)
+            return;
+        if (String(data || '').length === 0)
+            return;
+        sawOutput = true;
+        stop();
+    };
+    render();
+    interval = setInterval(() => {
+        if (stopped || sawOutput)
+            return;
+        render();
+    }, useSpinner ? CLI_STARTUP_SPINNER_MS : CLI_STARTUP_HEARTBEAT_MS);
+    interval.unref();
+    return { noteOutput, stop };
+}
 function startCodexOauthStartupHeartbeat() {
     const startedAt = Date.now();
     let stopped = false;
@@ -1316,8 +1445,8 @@ function startCodexOauthStartupHeartbeat() {
     const useSpinner = !!(process.stderr.isTTY && process.stdout.isTTY);
     const renderSpinner = () => {
         const elapsedSeconds = Math.max(1, Math.floor((Date.now() - startedAt) / 1000));
-        const frame = CODEX_OAUTH_STARTUP_SPINNER_FRAMES[spinnerFrame];
-        spinnerFrame = (spinnerFrame + 1) % CODEX_OAUTH_STARTUP_SPINNER_FRAMES.length;
+        const frame = CLI_STARTUP_SPINNER_FRAMES[spinnerFrame];
+        spinnerFrame = (spinnerFrame + 1) % CLI_STARTUP_SPINNER_FRAMES.length;
         process.stderr.write(`\r\x1b[2K${log.dim('›')} Waiting for Codex login output... ${frame} ${elapsedSeconds}s`);
         spinnerActive = true;
     };
@@ -2040,6 +2169,48 @@ function logStartupTimings(entries, totalMs) {
     const prefix = summary ? `${summary}, ` : '';
     log.step(`[labgate] startup timings: ${prefix}total=${formatStartupDuration(totalMs)}`);
 }
+function createStartupReportData(session, runtime, image) {
+    const now = new Date().toISOString();
+    const warnings = [];
+    if (session.uiDetected === false)
+        warnings.push('ui_not_detected');
+    return {
+        schema_version: 2,
+        kind: 'labgate-startup-report',
+        generated_at: now,
+        updated_at: now,
+        startup_completed_at: null,
+        startup_completion: null,
+        pid: process.pid,
+        node: (0, os_1.hostname)(),
+        agent: session.agent,
+        runtime,
+        workdir: session.workdir,
+        image,
+        dry_run: session.dryRun,
+        status: session.dryRun ? 'dry-run' : 'starting',
+        launch_mode: session.dryRun ? 'dry-run' : null,
+        ui_detected: session.uiDetected ?? null,
+        total_ms: 0,
+        session_total_ms: 0,
+        first_output_ms: null,
+        timings_ms: {},
+        cold_start_hints: [],
+        warnings,
+        slurm: {
+            enabled: session.config.slurm.enabled,
+            host_proxy_enabled: null,
+            passthrough_mode: null,
+            host_commands_found: null,
+            staged_commands: null,
+            reused_stage: null,
+        },
+        exit_code: null,
+    };
+}
+function writeStartupReportFile(path, report) {
+    (0, startup_stage_lock_js_1.writeTextFileAtomic)(path, JSON.stringify(report, null, 2) + '\n', { mode: 0o600 });
+}
 // ── Shared session helpers ─────────────────────────────────
 function logSessionStart(session, sessionId) {
     if (!session.config.audit.enabled)
@@ -2137,15 +2308,107 @@ function printSessionInfo(session, sessionId, runtime) {
 async function startSession(session) {
     const startupStartedAt = Date.now();
     const startupTimings = [];
-    const recordStartupTiming = (label, startedAt) => {
-        startupTimings.push([label, Math.max(0, Date.now() - startedAt)]);
-    };
     const preferred = session.config.runtime;
     const runtime = session.dryRun ? getDryRunRuntime(preferred) : (0, runtime_js_1.getRuntime)(preferred);
     const image = session.imageOverride ?? session.config.image;
     const sessionId = (0, crypto_1.randomBytes)(4).toString('hex');
     const footerMode = session.footerMode ?? 'sticky';
     const footerLine = formatStatusFooter(session, runtime, sessionId, image);
+    const startupReport = session.startupReportPath
+        ? createStartupReportData(session, runtime, image)
+        : null;
+    let startupReportWriteFailed = false;
+    const flushStartupReport = () => {
+        if (!startupReport || !session.startupReportPath || startupReportWriteFailed)
+            return;
+        const elapsedMs = Math.max(0, Date.now() - startupStartedAt);
+        startupReport.updated_at = new Date().toISOString();
+        startupReport.session_total_ms = elapsedMs;
+        if (startupReport.startup_completed_at === null) {
+            startupReport.total_ms = elapsedMs;
+        }
+        try {
+            writeStartupReportFile(session.startupReportPath, startupReport);
+        }
+        catch (err) {
+            startupReportWriteFailed = true;
+            log.warn(`Could not write startup report to ${session.startupReportPath}: ${err?.message ?? String(err)}`);
+        }
+    };
+    const noteStartupWarning = (warning) => {
+        if (!startupReport)
+            return;
+        if (!startupReport.warnings.includes(warning)) {
+            startupReport.warnings.push(warning);
+            flushStartupReport();
+        }
+    };
+    const noteColdStartHint = (hint) => {
+        if (!startupReport)
+            return;
+        if (!startupReport.cold_start_hints.includes(hint)) {
+            startupReport.cold_start_hints.push(hint);
+            flushStartupReport();
+        }
+    };
+    const setStartupStatus = (status) => {
+        if (!startupReport)
+            return;
+        startupReport.status = status;
+        flushStartupReport();
+    };
+    const setStartupLaunchMode = (mode) => {
+        if (!startupReport)
+            return;
+        startupReport.launch_mode = mode;
+        flushStartupReport();
+    };
+    const completeStartup = (completion) => {
+        if (!startupReport || startupReport.startup_completed_at !== null)
+            return;
+        startupReport.startup_completed_at = new Date().toISOString();
+        startupReport.startup_completion = completion;
+        startupReport.total_ms = Math.max(0, Date.now() - startupStartedAt);
+        flushStartupReport();
+    };
+    const noteStartupFirstOutput = (data) => {
+        if (!startupReport)
+            return;
+        if (startupReport.first_output_ms !== null)
+            return;
+        if (String(data || '').length === 0)
+            return;
+        const firstOutputMs = Math.max(0, Date.now() - startupStartedAt);
+        startupReport.first_output_ms = firstOutputMs;
+        startupReport.timings_ms.launch_first_output = firstOutputMs;
+        startupReport.status = 'running';
+        completeStartup('first-output');
+        flushStartupReport();
+    };
+    const updateSlurmStartupReport = (payload) => {
+        if (!startupReport)
+            return;
+        if (payload.hostProxyEnabled !== undefined)
+            startupReport.slurm.host_proxy_enabled = payload.hostProxyEnabled;
+        if (payload.passthroughMode !== undefined)
+            startupReport.slurm.passthrough_mode = payload.passthroughMode;
+        if (payload.hostCommandsFound !== undefined)
+            startupReport.slurm.host_commands_found = payload.hostCommandsFound;
+        if (payload.stagedCommands !== undefined)
+            startupReport.slurm.staged_commands = payload.stagedCommands;
+        if (payload.reusedStage !== undefined)
+            startupReport.slurm.reused_stage = payload.reusedStage;
+        flushStartupReport();
+    };
+    const recordStartupTiming = (label, startedAt) => {
+        const elapsedMs = Math.max(0, Date.now() - startedAt);
+        startupTimings.push([label, elapsedMs]);
+        if (startupReport) {
+            startupReport.timings_ms[label] = elapsedMs;
+            flushStartupReport();
+        }
+    };
+    flushStartupReport();
     // Extract agent auth token (CLI flag → env var)
     const tokenEnv = session.dryRun ? [] : getAgentTokenEnv(session.agent, session.apiKey);
     const bridgeCodexOauthForPodman = runtime === 'podman' && shouldBridgeCodexOauthForPodman(session.agent, session.config.network.mode);
@@ -2181,6 +2444,7 @@ async function startSession(session) {
     let cleanupSlurmHostProxy = () => { };
     let cleanupDeferredSlurmPassthrough = () => { };
     let startDeferredSlurmPassthrough = () => { };
+    let startupHeartbeat = null;
     // If the agent isn't installed in the persistent sandbox home yet, warn that first run can be slow.
     if (!session.dryRun) {
         const sandboxHome = (0, config_js_1.getSandboxHome)();
@@ -2188,18 +2452,28 @@ async function startSession(session) {
         const installedBin = (0, path_1.join)(sandboxHome, '.npm-global', 'bin', agentBin);
         try {
             if (!(0, fs_1.existsSync)(installedBin)) {
+                noteColdStartHint('agent_missing_in_sandbox');
                 log.step('First run: preparing sandbox (pulling image + installing agent). This can take a minute...');
             }
         }
         catch { /* ignore */ }
+        if (runtime === 'apptainer') {
+            try {
+                const cachedSifPath = (0, path_1.join)((0, config_js_1.getImagesDir)(), imageToSifName(image));
+                if (!(0, fs_1.existsSync)(cachedSifPath))
+                    noteColdStartHint('sif_cache_missing');
+            }
+            catch { /* ignore */ }
+        }
     }
     // For Apptainer sessions, always try SLURM CLI passthrough so sbatch/squeue
     // can work out of the box when present on the host. Full SLURM tracking/MCP
     // remains controlled by slurm.enabled.
     if (!session.dryRun && runtime === 'apptainer') {
         const hostProxyStartedAt = Date.now();
-        const hostProxy = startSlurmHostProxy(session);
+        const hostProxy = await startSlurmHostProxy(session);
         recordStartupTiming('slurm_host_proxy', hostProxyStartedAt);
+        updateSlurmStartupReport({ hostProxyEnabled: !!hostProxy });
         const trackingEnabled = session.config.slurm.enabled;
         const runSlurmPassthroughStage = (mode) => {
             const stageStartedAt = Date.now();
@@ -2212,8 +2486,15 @@ async function startSession(session) {
                     preferHostProxy: false,
                 });
                 recordStartupTiming(mode === 'startup' ? 'slurm_passthrough_stage' : 'slurm_passthrough_stage_background', stageStartedAt);
+                updateSlurmStartupReport({
+                    passthroughMode: staged.ok ? 'staged' : 'unavailable',
+                    hostCommandsFound: staged.hostCommands.length,
+                    stagedCommands: staged.staged.length,
+                    reusedStage: staged.reused,
+                });
                 if (trackingEnabled) {
                     if (!staged.ok) {
+                        noteStartupWarning('slurm_commands_unavailable');
                         log.warn('SLURM is enabled but no SLURM commands were found on the host PATH. ' +
                             'Inside-sandbox SLURM commands (squeue/sbatch/...) will be unavailable.');
                     }
@@ -2236,6 +2517,13 @@ async function startSession(session) {
             }
             catch (err) {
                 recordStartupTiming(mode === 'startup' ? 'slurm_passthrough_stage' : 'slurm_passthrough_stage_background', stageStartedAt);
+                updateSlurmStartupReport({
+                    passthroughMode: 'unavailable',
+                    reusedStage: false,
+                });
+                noteStartupWarning(mode === 'startup'
+                    ? 'slurm_passthrough_stage_failed'
+                    : 'slurm_passthrough_stage_background_failed');
                 log.warn(mode === 'startup'
                     ? `SLURM passthrough staging failed: ${err?.message ?? String(err)}`
                     : `Deferred SLURM passthrough staging failed: ${err?.message ?? String(err)}`);
@@ -2253,8 +2541,17 @@ async function startSession(session) {
                 preferHostProxy: true,
             });
             recordStartupTiming('slurm_passthrough_stage', stageStartedAt);
+            updateSlurmStartupReport({
+                passthroughMode: staged.ok
+                    ? (staged.mode === 'proxy-only' ? 'proxy-only' : 'staged')
+                    : 'unavailable',
+                hostCommandsFound: staged.hostCommands.length,
+                stagedCommands: staged.staged.length,
+                reusedStage: staged.reused,
+            });
             if (trackingEnabled) {
                 if (!staged.ok) {
+                    noteStartupWarning('slurm_commands_unavailable');
                     log.warn('SLURM is enabled but no SLURM commands were found on the host PATH. ' +
                         'Inside-sandbox SLURM commands (squeue/sbatch/...) will be unavailable.');
                 }
@@ -2275,12 +2572,19 @@ async function startSession(session) {
             }
         }
         else {
+            noteStartupWarning('slurm_host_proxy_unavailable');
             if (trackingEnabled) {
                 log.step('SLURM host proxy unavailable. Staging SLURM passthrough before startup.');
                 runSlurmPassthroughStage('startup');
             }
             else {
                 log.step('SLURM host proxy unavailable. Deferring SLURM passthrough staging until after startup.');
+                updateSlurmStartupReport({
+                    passthroughMode: 'deferred-stage',
+                    hostCommandsFound: null,
+                    stagedCommands: null,
+                    reusedStage: null,
+                });
                 let cancelled = false;
                 let timer = null;
                 let started = false;
@@ -2308,32 +2612,58 @@ async function startSession(session) {
         }
     }
     let args;
-    if (runtime === 'apptainer') {
-        let sifPath;
-        if (session.dryRun) {
-            sifPath = (0, path_1.join)((0, config_js_1.getImagesDir)(), imageToSifName(image));
+    const imagePrepareStartedAt = Date.now();
+    try {
+        if (runtime === 'apptainer') {
+            startupHeartbeat = startCliStartupHeartbeat(session.agent, 'image', runtime);
+            let sifPath;
+            if (session.dryRun) {
+                sifPath = (0, path_1.join)((0, config_js_1.getImagesDir)(), imageToSifName(image));
+            }
+            else {
+                sifPath = await ensureSifImage(runtime, image, {
+                    onTiming: (label, elapsedMs) => {
+                        if (startupReport) {
+                            startupReport.timings_ms[label] = elapsedMs;
+                            flushStartupReport();
+                        }
+                        startupTimings.push([label, elapsedMs]);
+                    },
+                    onWarning: noteStartupWarning,
+                    onHint: noteColdStartHint,
+                });
+            }
+            const buildArgsStartedAt = Date.now();
+            args = buildApptainerArgs(session, sifPath, sessionId, runtimeEnvArgs);
+            recordStartupTiming('image_prepare_build_args', buildArgsStartedAt);
         }
         else {
-            sifPath = await ensureSifImage(runtime, image);
-        }
-        args = buildApptainerArgs(session, sifPath, sessionId, runtimeEnvArgs);
-    }
-    else {
-        if (bridgeCodexOauthForPodman) {
-            const port = getCodexOauthCallbackPort();
-            log.step(`Codex OAuth callback bridge enabled on localhost:${port} ` +
-                '(Podman macOS uses bridge networking for callback compatibility).');
-            if (needsCodexOauthStartupHeartbeat) {
-                log.step('Launching Codex OAuth flow. Login output may take ~30s to appear.');
+            if (bridgeCodexOauthForPodman) {
+                const port = getCodexOauthCallbackPort();
+                log.step(`Codex OAuth callback bridge enabled on localhost:${port} ` +
+                    '(Podman macOS uses bridge networking for callback compatibility).');
+                if (needsCodexOauthStartupHeartbeat) {
+                    log.step('Launching Codex OAuth flow. Login output may take ~30s to appear.');
+                }
             }
+            startupHeartbeat = startCliStartupHeartbeat(session.agent, 'image', runtime);
+            if (!session.dryRun) {
+                ensurePodmanImage(runtime, image);
+            }
+            args = buildPodmanArgs(session, image, sessionId, runtimeEnvArgs, { tty: !!(process.stdout.isTTY && process.stdin.isTTY) });
         }
-        if (!session.dryRun) {
-            ensurePodmanImage(runtime, image);
-        }
-        args = buildPodmanArgs(session, image, sessionId, runtimeEnvArgs, { tty: !!(process.stdout.isTTY && process.stdin.isTTY) });
+    }
+    finally {
+        recordStartupTiming('image_prepare', imagePrepareStartedAt);
+        startupHeartbeat?.stop();
+        startupHeartbeat = null;
     }
     if (session.dryRun) {
+        setStartupLaunchMode('dry-run');
+        setStartupStatus('dry-run');
+        completeStartup('dry-run');
         prettyPrintCommand(runtime, args);
+        flushStartupReport();
         return;
     }
     // Create OAuth URL interceptor as a fallback when BROWSER hook does not fire.
@@ -2372,6 +2702,7 @@ async function startSession(session) {
             sessionSlurmPoller.start();
         }
         catch (err) {
+            noteStartupWarning('slurm_tracking_unavailable');
             log.warn(`SLURM tracking unavailable: ${err?.message ?? String(err)}`);
             cleanupSlurm();
         }
@@ -2389,7 +2720,11 @@ async function startSession(session) {
     const wantsSticky = footerMode === 'sticky';
     const needsOAuthPtyFallback = !!oauthInterceptor;
     const hasTty = !!(process.stdout.isTTY && process.stdin.isTTY);
-    const shouldUsePty = hasTty && (wantsSticky || needsOAuthPtyFallback || needsCodexOauthStartupHeartbeat);
+    const wantsStartupOutputCapture = !!startupReport;
+    const shouldUsePty = hasTty && (wantsSticky
+        || needsOAuthPtyFallback
+        || needsCodexOauthStartupHeartbeat
+        || wantsStartupOutputCapture);
     if (shouldUsePty) {
         const pty = await loadPty();
         if (!pty) {
@@ -2402,6 +2737,10 @@ async function startSession(session) {
             else if (needsCodexOauthStartupHeartbeat) {
                 log.step('Codex startup heartbeat unavailable (node-pty missing).');
             }
+            else if (wantsStartupOutputCapture) {
+                noteStartupWarning('startup_output_capture_unavailable');
+                log.step('Startup output capture unavailable (node-pty missing).');
+            }
         }
         else {
             let runtimePath;
@@ -2419,6 +2758,9 @@ async function startSession(session) {
             const cols = process.stdout.columns || 80;
             const rows = process.stdout.rows || 24;
             let child;
+            const launchHeartbeat = startCliStartupHeartbeat(session.agent, 'launch', runtime);
+            setStartupStatus('launching');
+            setStartupLaunchMode('pty');
             try {
                 child = pty.spawn(runtimePath, args, {
                     name: 'xterm-256color',
@@ -2429,6 +2771,8 @@ async function startSession(session) {
                 });
             }
             catch (err) {
+                launchHeartbeat.stop();
+                noteStartupWarning('pty_spawn_failed');
                 log.step(`PTY spawn failed (${err?.message ?? String(err)}). Falling back to standard spawn.`);
                 // Fall through to standard spawn path below.
                 child = null;
@@ -2452,7 +2796,9 @@ async function startSession(session) {
                     renderStickyFooter(footerLine);
                 }
                 child.onData((data) => {
+                    launchHeartbeat.noteOutput(data);
                     codexOauthHeartbeat?.noteOutput(data);
+                    noteStartupFirstOutput(data);
                     if (oauthInterceptor)
                         oauthInterceptor.feed(data);
                     process.stdout.write(data);
@@ -2475,7 +2821,14 @@ async function startSession(session) {
                 const timeoutHandle = setupSessionTimeout(session, sessionId, runtime, () => exited, () => child.kill('SIGTERM'));
                 child.onExit((event) => {
                     exited = true;
+                    launchHeartbeat.stop();
                     codexOauthHeartbeat?.stop();
+                    if (startupReport) {
+                        completeStartup('process-exit');
+                        startupReport.exit_code = event.exitCode ?? 0;
+                        startupReport.status = 'exited';
+                        flushStartupReport();
+                    }
                     if (timeoutHandle)
                         clearTimeout(timeoutHandle);
                     browserHook?.cleanup();
@@ -2505,17 +2858,35 @@ async function startSession(session) {
     else if (needsOAuthPtyFallback && !hasTty) {
         log.step('OAuth URL fallback interceptor requires a TTY; relying on BROWSER hook only.');
     }
+    else if (wantsStartupOutputCapture && !hasTty) {
+        noteStartupWarning('startup_output_capture_unavailable');
+        log.step('Startup output capture requires a TTY; report will omit first-output timing.');
+    }
     if (footerMode === 'sticky') {
         console.log(footerLine);
     }
+    log.step(`${describeCliStartupPhase(session.agent, 'launch', runtime)}...`);
     console.log('');
     // Spawn path: must use stdio:'inherit' to preserve TTY for Claude Code.
     // OAuth interception relies on the BROWSER hook + file watcher here
     // (the PTY path above uses onData for direct interception).
+    setStartupStatus('launching');
+    setStartupLaunchMode('inherit');
     const child = (0, child_process_1.spawn)(runtime, args, { stdio: 'inherit' });
+    if (startupReport && startupReport.first_output_ms === null) {
+        startupReport.status = 'running';
+        completeStartup('spawn');
+        flushStartupReport();
+    }
     startDeferredSlurmPassthrough();
     const timeoutHandle = setupSessionTimeout(session, sessionId, runtime, () => child.exitCode !== null, () => child.kill('SIGTERM'));
     child.on('close', (code) => {
+        if (startupReport) {
+            completeStartup('process-exit');
+            startupReport.exit_code = code ?? 0;
+            startupReport.status = 'exited';
+            flushStartupReport();
+        }
         if (timeoutHandle)
             clearTimeout(timeoutHandle);
         browserHook?.cleanup();