@agent-deck/cli 1.9.0 → 1.10.1

package/dist/start.js

@@ -15,20 +15,40 @@ const version_1 = require("./version");
 const defaults_1 = require("./defaults");
 const managed_1 = require("./managed");
 const daemon_logs_1 = require("./daemon-logs");
+const shutdown_reason_1 = require("./shutdown-reason");
 const dashboard_open_1 = require("./dashboard-open");
+const backend_runtime_1 = require("./backend-runtime");
+const store_1 = require("./store");
 function formatStartVersionLine(version = (0, version_1.getAgentDeckVersion)()) {
     return `  Version    ${version}`;
 }
 function formatClaudeMcpAddCommand(host, mcpPort) {
     return `claude mcp add --scope user agent-deck -e AGENT_DECK_MCP_PORT=${mcpPort} -e AGENT_DECK_HOST=${host} -- agent-deck mcp-launch`;
 }
+const SHUTDOWN_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
 const children = [];
 let shuttingDown = false;
+/** Only the process that wrote run.json may clear it — an aborted start must not. */
+let ownsRunState = false;
+/** Non-null until the deck is up: names the phase a stop interrupted. */
+let startupPhase = null;
 function isSupervisorMode(options) {
     return options.supervisor === true || process.env.AGENT_DECK_SUPERVISOR === '1';
 }
-async function waitForHealth(url, attempts = 60) {
+/**
+ * Set once `runStart` knows what it is. The `--_supervisor` flag alone (no env
+ * var) still means stderr *is* supervisor.log, and printing there would write
+ * every line twice.
+ */
+let supervisorProcess = false;
+function isSupervisorProcess() {
+    return supervisorProcess || isSupervisorMode({});
+}
+async function waitForHealth(url, attempts = 60, giveUp) {
     for (let i = 0; i < attempts; i += 1) {
+        if (giveUp?.()) {
+            return false;
+        }
         try {
             const response = await fetch(url);
             if (response.ok) {
@@ -49,11 +69,59 @@ function resolveServiceStdio(label, ioMode) {
     const fd = (0, daemon_logs_1.openDaemonLogFd)(label);
     return ['ignore', fd, fd];
 }
+/**
+ * Copy the child's own last words into supervisor.log. The child already logs
+ * why it died, but the operator reading "backend exited (code 1)" is looking at
+ * a different file — so bring the reason to them.
+ */
+function surfaceChildLogTail(label, ioMode) {
+    if (ioMode !== 'file') {
+        // Inherit mode already printed the child's output to this terminal.
+        return;
+    }
+    for (const line of (0, daemon_logs_1.formatChildLogTail)(label, (0, daemon_logs_1.readDaemonLogTail)(label, 20))) {
+        (0, daemon_logs_1.appendDaemonLogLine)('supervisor', `${new Date().toISOString()} ${line}`);
+    }
+}
+/**
+ * supervisor.log always, the terminal as well unless stderr already *is* that
+ * log. Used by the paths that run outside the ioMode-aware body of `runStart`.
+ */
+function reportSupervisor(lines) {
+    const stamp = new Date().toISOString();
+    for (const line of lines) {
+        try {
+            (0, daemon_logs_1.appendDaemonLogLine)('supervisor', `${stamp} ${line}`);
+        }
+        catch {
+            // A diagnostic never fails on its own bookkeeping.
+        }
+        if (!isSupervisorProcess()) {
+            console.error(line);
+        }
+    }
+}
 function spawnNodeService(label, entry, env, ioMode) {
     const child = (0, node_child_process_1.spawn)(process.execPath, [entry], {
         env: { ...process.env, ...env },
         stdio: resolveServiceStdio(label, ioMode),
     });
+    // A spawn that never starts emits 'error', not 'exit' — and an unhandled
+    // 'error' event would take the supervisor down with Node's default trace and
+    // no record at all, which is the failure mode this ticket is about.
+    child.on('error', (error) => {
+        if (shuttingDown) {
+            return;
+        }
+        const { reason, detail } = (0, shutdown_reason_1.describeCrash)(error);
+        reportSupervisor([
+            `[agent-deck] ${label} failed to spawn: ${reason}`,
+            ...detail.map((frame) => `[agent-deck] ${label} spawn| ${frame}`),
+        ]);
+        if (label === 'backend') {
+            void shutdown(1, `backend failed to spawn: ${reason}`);
+        }
+    });
     child.on('exit', (code, signal) => {
         if (shuttingDown) {
             return;
@@ -66,8 +134,11 @@ function spawnNodeService(label, entry, env, ioMode) {
         else {
             console.error(message);
         }
+        if (signal || (code ?? 1) !== 0) {
+            surfaceChildLogTail(label, ioMode);
+        }
         if (label === 'backend') {
-            void shutdown(code ?? 1);
+            void shutdown(code ?? 1, `backend exited (${detail})`);
             return;
         }
         const mcpWarn = '[agent-deck] MCP stopped; dashboard API remains available. Run `agent-deck stop && agent-deck start` to recover MCP.';
@@ -81,15 +152,45 @@ function spawnNodeService(label, entry, env, ioMode) {
     children.push(child);
     return child;
 }
-async function shutdown(exitCode = 0) {
+/**
+ * @param origin what this supervisor observed (a signal, a child exit, a failed
+ *   start). Enriched with the requester's note when one was left behind, so the
+ *   log names *who* stopped the deck and not just that it stopped.
+ */
+async function shutdown(exitCode = 0, origin = 'origin not recorded') {
     if (shuttingDown) {
         return;
     }
     shuttingDown = true;
-    if (isSupervisorMode({})) {
-        (0, daemon_logs_1.appendDaemonLogLine)('supervisor', `${new Date().toISOString()} [agent-deck] supervisor shutting down (exit ${exitCode})`);
+    const request = (0, shutdown_reason_1.consumeStopRequest)({ supervisorPid: process.pid });
+    const reason = (0, shutdown_reason_1.composeShutdownReason)(origin, request);
+    // Only a process that actually ran the deck may answer "why did it stop?".
+    // A `start` that found one already running, or died in preflight, would
+    // otherwise record a stop for a deck that is still up and serving.
+    const supervised = ownsRunState || children.length > 0;
+    if (supervised) {
+        // supervisor.log answers "why did the deck stop?" for every run, daemon or
+        // not — a Ctrl-C in inherit mode must not be the one stop with no record.
+        reportSupervisor([(0, shutdown_reason_1.formatSupervisorShutdownLine)(exitCode, reason)]);
+        (0, shutdown_reason_1.writeLastStop)({
+            at: new Date().toISOString(),
+            exitCode,
+            reason,
+            supervisorPid: process.pid,
+        });
+    }
+    else if (startupPhase !== null) {
+        // Nothing was ever supervised, so this is a start that did not finish —
+        // "why won't it start?", which keeps its own record.
+        (0, shutdown_reason_1.recordStartFailure)({ reason, exitCode });
+        if (!isSupervisorProcess()) {
+            console.error((0, shutdown_reason_1.formatStartFailureLine)(reason));
+        }
+    }
+    else {
+        reportSupervisor([(0, shutdown_reason_1.formatCommandExitLine)(exitCode, reason)]);
     }
-    (0, runtime_state_1.clearRunState)();
+    clearOwnRunState();
     for (const child of children) {
         if (!child.killed) {
             child.kill('SIGTERM');
@@ -98,6 +199,117 @@ async function shutdown(exitCode = 0) {
     await new Promise((resolve) => setTimeout(resolve, 300));
     process.exit(exitCode);
 }
+/**
+ * A start aborted before `writeRunState` never owned run.json, and deleting the
+ * running instance's state would leave `status` and `stop` blind. A record whose
+ * supervisor is gone is nobody's, though — that one is ours to clean up.
+ */
+function clearOwnRunState() {
+    if (ownsRunState) {
+        (0, runtime_state_1.clearRunState)();
+        return;
+    }
+    const state = (0, runtime_state_1.readRunState)();
+    if (state && (state.cliPid === process.pid || !(0, runtime_state_1.isProcessAlive)(state.cliPid))) {
+        (0, runtime_state_1.clearRunState)();
+    }
+}
+/** A signal that lands mid-startup names the phase it interrupted. */
+function signalShutdownOrigin(signal) {
+    const origin = (0, shutdown_reason_1.describeSignalOrigin)(signal);
+    return startupPhase ? `${origin} while starting (phase: ${startupPhase})` : origin;
+}
+/**
+ * Every way this process can end, routed through one reporting path. Installed
+ * before any startup work — preflight, upgrade checks and port probes all await,
+ * and a stop arriving during them used to take Node's default exit path: no
+ * shutdown line, no last-stop record, no origin.
+ */
+function installSupervisorExitHandlers() {
+    for (const signal of SHUTDOWN_SIGNALS) {
+        process.on(signal, () => void shutdown(0, signalShutdownOrigin(signal)));
+    }
+    // The stop with the worst record of all: Node's default handler prints a
+    // trace to wherever stderr points and exits, leaving no shutdown line and no
+    // last-stop record. Route it through the same reporting as every other stop.
+    for (const [event, kind] of [
+        ['uncaughtException', 'uncaught exception'],
+        ['unhandledRejection', 'unhandled promise rejection'],
+    ]) {
+        process.on(event, (error) => {
+            const { reason, detail } = (0, shutdown_reason_1.describeCrash)(error);
+            reportSupervisor(detail.map((frame) => `[agent-deck] supervisor stack| ${frame}`));
+            void shutdown(1, `supervisor ${kind}: ${reason}`);
+        });
+    }
+}
+/**
+ * `start --daemon` launcher: it owns no run state and no children, so it records
+ * the interrupted start and leaves any supervisor it already spawned running.
+ * Once the deck is up (`startupPhase === null`) this process is only printing —
+ * interrupting it is not a failed start and must not be recorded as one.
+ */
+function installLauncherExitHandlers(getSupervisorPid) {
+    for (const signal of SHUTDOWN_SIGNALS) {
+        process.on(signal, () => {
+            if (startupPhase === null) {
+                process.exit(0);
+            }
+            const supervisorPid = getSupervisorPid();
+            (0, shutdown_reason_1.recordStartFailure)({
+                reason: `${(0, shutdown_reason_1.describeSignalOrigin)(signal)} while starting in background (phase: ${startupPhase})`,
+                detail: survivingSupervisorNote(supervisorPid),
+            });
+            process.exit(1);
+        });
+    }
+    // Same reasoning as the supervisor's crash handlers: the launcher is the only
+    // process watching a background start, so its own throw has to be recorded.
+    for (const [event, kind] of [
+        ['uncaughtException', 'uncaught exception'],
+        ['unhandledRejection', 'unhandled promise rejection'],
+    ]) {
+        process.on(event, (error) => {
+            const { reason, detail } = (0, shutdown_reason_1.describeCrash)(error);
+            const frames = detail.map((frame) => `[agent-deck] launcher stack| ${frame}`);
+            if (startupPhase === null) {
+                // The deck is up and this process was only printing — not a failed
+                // start, so it must not be recorded as one.
+                reportSupervisor([
+                    `[agent-deck] start --daemon ${kind} after the deck was up: ${reason}`,
+                    ...frames,
+                ]);
+                process.exit(1);
+            }
+            console.error(`[agent-deck] start --daemon ${kind}: ${reason}`);
+            (0, shutdown_reason_1.recordStartFailure)({
+                reason: `agent-deck start --daemon ${kind} (phase: ${startupPhase}): ${reason}`,
+                detail: [...frames, ...survivingSupervisorNote(getSupervisorPid())],
+            });
+            process.exit(1);
+        });
+    }
+}
+/** A launcher that gives up has usually left a working supervisor behind. */
+function survivingSupervisorNote(supervisorPid) {
+    return supervisorPid > 0
+        ? [
+            `[agent-deck] background supervisor (pid ${supervisorPid}) was already spawned and keeps running — check agent-deck status`,
+        ]
+        : [];
+}
+/**
+ * Print (unless stderr already *is* supervisor.log) and persist, so the reason
+ * survives in supervisor.log and `agent-deck status`.
+ */
+function failStart(failure, supervisor) {
+    if (!supervisor) {
+        for (const line of failure.lines) {
+            console.error(line);
+        }
+    }
+    return (0, shutdown_reason_1.recordStartFailure)({ reason: failure.reason, detail: failure.lines });
+}
 async function printRunningEndpoints(host, backendPort, mcpPort, backendUrl) {
     console.log('');
     console.log('Agent Deck is running');
@@ -136,25 +348,66 @@ function buildSupervisorArgs(options) {
     }
     return args;
 }
-async function runDaemonLauncher(options) {
+async function runDaemonLauncher(options, onSupervisorSpawned) {
     const backendPort = options.backendPort ?? (0, defaults_1.readCliBackendPort)();
     const mcpPort = options.mcpPort ?? (0, defaults_1.parseCliMcpPort)(process.env.AGENT_DECK_MCP_PORT);
     const host = process.env.AGENT_DECK_HOST ?? '127.0.0.1';
     const backendUrl = `http://${host}:${backendPort}`;
     const supervisorLogFd = (0, daemon_logs_1.openDaemonLogFd)('supervisor');
     const cliEntry = (0, daemon_logs_1.resolveCliEntry)();
+    const launchedAt = Date.now();
     const child = (0, node_child_process_1.spawn)(process.execPath, [cliEntry, ...buildSupervisorArgs(options)], {
         detached: true,
         stdio: ['ignore', supervisorLogFd, supervisorLogFd],
         env: { ...process.env, AGENT_DECK_SUPERVISOR: '1' },
     });
+    onSupervisorSpawned(child.pid ?? 0);
+    // Object, not a `let`: the end arrives from a callback, and the reads below
+    // are all after an await. Holds a phrase, not a code, so a supervisor that
+    // never started reads as plainly as one that exited.
+    const supervisor = { ended: null };
+    child.on('exit', (code, signal) => {
+        supervisor.ended = signal ? `exited (signal ${signal})` : `exited (code ${code ?? 1})`;
+    });
+    // Without this handler a failed spawn throws an unhandled 'error' event and
+    // kills the launcher before it can write any diagnostic.
+    child.on('error', (error) => {
+        supervisor.ended = `failed to spawn (${(0, shutdown_reason_1.describeCrash)(error).reason})`;
+    });
     child.unref();
-    const healthy = await waitForHealth(`${backendUrl}/health`);
+    // Waiting out the full health budget after the supervisor is already gone
+    // only delays the diagnostic it just wrote.
+    const healthy = await waitForHealth(`${backendUrl}/health`, 60, () => supervisor.ended !== null);
     if (!healthy) {
-        console.error('[agent-deck] Daemon supervisor failed health check.');
+        const reason = supervisor.ended
+            ? `daemon supervisor ${supervisor.ended} before the API became healthy`
+            : 'daemon supervisor never passed its API health check';
+        console.error(`[agent-deck] ${reason}`);
+        // The supervisor log already holds the reason (and the child log tail it
+        // copied in) — show it here rather than sending the operator hunting.
+        for (const line of (0, daemon_logs_1.formatChildLogTail)('supervisor', (0, daemon_logs_1.readDaemonLogTail)('supervisor', 20))) {
+            console.error(line);
+        }
         console.error(`[agent-deck] See ${(0, daemon_logs_1.resolveDaemonLogPath)('supervisor')}`);
-        return 1;
-    }
+        // A supervisor that is merely slow is still running and still holding the
+        // ports; saying only "start failed" sends the operator into a port conflict
+        // on their next attempt.
+        const stillRunning = supervisor.ended === null ? survivingSupervisorNote(child.pid ?? 0) : [];
+        for (const line of stillRunning) {
+            console.error(line);
+        }
+        // The supervisor child knows more than "it exited"; keep its record if it
+        // got far enough to write one for this launch.
+        const recorded = (0, shutdown_reason_1.readLastStartFailure)();
+        const supervisorRecorded = recorded !== null && Date.parse(recorded.at) >= launchedAt;
+        return (0, shutdown_reason_1.recordStartFailure)({
+            reason,
+            detail: stillRunning,
+            keepExistingRecord: supervisorRecorded,
+        });
+    }
+    // The deck is up; everything past here is reporting, not starting.
+    startupPhase = null;
     const mcpHealthy = await waitForHealth(`http://${host}:${mcpPort}/health`, 20);
     if (!mcpHealthy) {
         console.warn('[agent-deck] MCP not healthy yet — dashboard API is up.');
@@ -176,34 +429,51 @@ async function runDaemonLauncher(options) {
     }
     return 0;
 }
+function portConflictFailure(port, label, host) {
+    return {
+        reason: `port ${port} (${label}) is held by another program on ${host}`,
+        lines: (0, ports_1.formatPortConflict)(port, label, host, false)
+            .split('\n')
+            .map((line) => `[agent-deck] ${line}`),
+    };
+}
 async function ensurePortsAvailable(host, backendPort, mcpPort, probe) {
     const [backendBusy, mcpBusy] = await Promise.all([
         (0, ports_1.isTcpPortOpen)(host, backendPort),
         (0, ports_1.isTcpPortOpen)(host, mcpPort),
     ]);
     if (backendBusy && !probe.backendUp) {
-        console.error(`[agent-deck] ${(0, ports_1.formatPortConflict)(backendPort, 'API/dashboard', host, false)}`);
-        return 1;
+        return portConflictFailure(backendPort, 'API/dashboard', host);
     }
     if (mcpBusy && !probe.mcpUp) {
-        console.error(`[agent-deck] ${(0, ports_1.formatPortConflict)(mcpPort, 'MCP', host, false)}`);
-        return 1;
+        return portConflictFailure(mcpPort, 'MCP', host);
     }
     return null;
 }
 async function runStart(options = {}) {
-    const nodeError = (0, node_runtime_1.assertSupportedNodeVersion)();
-    if (nodeError !== null) {
-        return nodeError;
+    const supervisor = isSupervisorMode(options);
+    const launcher = options.daemon === true && !supervisor;
+    supervisorProcess = supervisor;
+    // Before the first await: preflight, upgrade checks and port probes all take
+    // time, and a stop landing in that window used to kill this process through
+    // Node's default signal path — no shutdown line, no origin, no record.
+    startupPhase = 'preflight';
+    let daemonSupervisorPid = 0;
+    if (launcher) {
+        installLauncherExitHandlers(() => daemonSupervisorPid);
+    }
+    else {
+        installSupervisorExitHandlers();
     }
-    const sqliteError = (0, node_runtime_1.assertSqliteNative)();
-    if (sqliteError !== null) {
-        return sqliteError;
+    const preflight = (0, node_runtime_1.checkStartPreflight)();
+    if (preflight !== null) {
+        return failStart({ reason: preflight.reason, lines: preflight.message.split('\n') }, supervisor);
     }
+    startupPhase = 'update check';
     await (0, upgrade_1.maybeAutoUpgradeOnStart)();
     await (0, upgrade_1.notifyIfUpdateAvailable)();
-    const supervisor = isSupervisorMode(options);
-    if (options.daemon && !supervisor) {
+    if (launcher) {
+        startupPhase = 'probing for a running instance';
         const backendPort = options.backendPort ?? (0, defaults_1.readCliBackendPort)();
         const mcpPort = options.mcpPort ?? (0, defaults_1.parseCliMcpPort)(process.env.AGENT_DECK_MCP_PORT);
         const host = process.env.AGENT_DECK_HOST ?? '127.0.0.1';
@@ -211,22 +481,29 @@ async function runStart(options = {}) {
         if (probe.backendUp && probe.mcpUp) {
             if (options.force) {
                 console.log('[agent-deck] Restarting existing instance (--force) ...');
-                await (0, stop_1.runStop)();
+                await (0, stop_1.runStop)({ source: 'agent-deck start --force', detail: 'restarting existing instance' });
                 await new Promise((resolve) => setTimeout(resolve, 500));
             }
             else {
+                // Nothing is starting any more — an interrupt from here on is a stopped
+                // printout, not a failed start, and must not be recorded as one.
+                startupPhase = null;
                 await printRunningEndpoints(host, backendPort, mcpPort, `http://${host}:${backendPort}`);
                 console.log('Already running. Use `agent-deck stop` or `agent-deck start --daemon --force` to restart.');
                 await maybeOpenDashboard(`http://${host}:${backendPort}`, options.openBrowser);
                 return 0;
             }
         }
+        startupPhase = 'checking ports';
         const refreshedProbe = options.force ? await (0, ports_1.probeAgentDeck)(host, backendPort, mcpPort) : probe;
         const portError = await ensurePortsAvailable(host, backendPort, mcpPort, refreshedProbe);
         if (portError !== null) {
-            return portError;
+            return failStart(portError, supervisor);
         }
-        return runDaemonLauncher(options);
+        startupPhase = 'launching background supervisor';
+        return runDaemonLauncher(options, (pid) => {
+            daemonSupervisorPid = pid;
+        });
     }
     const ioMode = supervisor ? 'file' : 'inherit';
     const backendPort = options.backendPort ?? (0, defaults_1.readCliBackendPort)();
@@ -234,24 +511,29 @@ async function runStart(options = {}) {
     const host = process.env.AGENT_DECK_HOST ?? '127.0.0.1';
     const backendUrl = `http://${host}:${backendPort}`;
     const uiDist = options.skipUi ? undefined : (0, paths_1.resolveUiDist)();
+    startupPhase = 'probing for a running instance';
     const probe = await (0, ports_1.probeAgentDeck)(host, backendPort, mcpPort);
     if (probe.backendUp && probe.mcpUp) {
         if (options.force) {
             console.log('[agent-deck] Restarting existing instance (--force) ...');
-            await (0, stop_1.runStop)();
+            await (0, stop_1.runStop)({ source: 'agent-deck start --force', detail: 'restarting existing instance' });
             await new Promise((resolve) => setTimeout(resolve, 500));
         }
         else {
+            // As above: past this point this process is only reporting on a deck it
+            // did not start, so it owns neither a stop nor a failed start.
+            startupPhase = null;
             await printRunningEndpoints(host, backendPort, mcpPort, backendUrl);
             console.log('Already running. Use `agent-deck stop` or `agent-deck start --force` to restart.');
             await maybeOpenDashboard(backendUrl, options.openBrowser);
             return 0;
         }
     }
+    startupPhase = 'checking ports';
     const refreshedProbe = options.force ? await (0, ports_1.probeAgentDeck)(host, backendPort, mcpPort) : probe;
     const portError = await ensurePortsAvailable(host, backendPort, mcpPort, refreshedProbe);
     if (portError !== null) {
-        return portError;
+        return failStart(portError, supervisor);
     }
     if (!options.skipUi && !uiDist) {
         const warnUi = '[agent-deck] Dashboard UI bundle not found (static-ui). API and MCP will still start.';
@@ -265,8 +547,17 @@ async function runStart(options = {}) {
             console.warn(warnDist);
         }
     }
-    const backendEntry = (0, paths_1.resolveBackendEntry)('index');
-    const mcpEntry = (0, paths_1.resolveBackendEntry)('mcp-index');
+    startupPhase = 'resolving the backend build';
+    let backendEntry;
+    let mcpEntry;
+    try {
+        backendEntry = (0, paths_1.resolveBackendEntry)('index');
+        mcpEntry = (0, paths_1.resolveBackendEntry)('mcp-index');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return failStart({ reason: message, lines: [`[agent-deck] ${message}`] }, supervisor);
+    }
     const logStart = (line) => {
         if (ioMode === 'file') {
             (0, daemon_logs_1.appendDaemonLogLine)('supervisor', `${new Date().toISOString()} ${line}`);
@@ -275,6 +566,7 @@ async function runStart(options = {}) {
             console.log(line);
         }
     };
+    startupPhase = 'starting backend';
     logStart('[agent-deck] Starting backend ...');
     const backendChild = spawnNodeService('backend', backendEntry, {
         PORT: String(backendPort),
@@ -284,19 +576,33 @@ async function runStart(options = {}) {
         AGENT_DECK_MCP_PORT: String(mcpPort),
         ...(uiDist ? { AGENT_DECK_UI_DIST: uiDist } : {}),
     }, ioMode);
-    const healthy = await waitForHealth(`${backendUrl}/health`);
+    // A backend that exits takes the shutdown path immediately; polling out the
+    // remaining health budget would only postpone this process's own exit.
+    const healthy = await waitForHealth(`${backendUrl}/health`, 60, () => shuttingDown);
     if (!healthy) {
+        if (shuttingDown) {
+            // Something else (the backend's own exit, or a stop) already logged the
+            // cause and is shutting down with its own exit code. Returning here would
+            // race that exit and could report a failure for a requested stop; repeating
+            // the tail would only double it in supervisor.log.
+            await new Promise(() => {
+                // shutdown() exits this process.
+            });
+        }
         const failMsg = '[agent-deck] Backend failed health check (port conflict or crash).';
         if (ioMode === 'file') {
-            (0, daemon_logs_1.appendDaemonLogLine)('supervisor', failMsg);
+            (0, daemon_logs_1.appendDaemonLogLine)('supervisor', `${new Date().toISOString()} ${failMsg}`);
         }
         else {
             console.error(failMsg);
+            console.error(`[agent-deck] See ${(0, daemon_logs_1.resolveDaemonLogPath)('backend')}`);
             console.error('[agent-deck] Run: agent-deck status');
         }
-        await shutdown(1);
+        surfaceChildLogTail('backend', ioMode);
+        await shutdown(1, 'backend failed health check during start');
         return 1;
     }
+    startupPhase = 'starting MCP server';
     logStart('[agent-deck] Starting MCP server ...');
     let mcpPid = 0;
     if (refreshedProbe.mcpUp) {
@@ -315,12 +621,14 @@ async function runStart(options = {}) {
         if (!mcpProbe.mcpUp) {
             const mcpFail = '[agent-deck] MCP server failed to start (port conflict or crash). Dashboard API is still running.';
             if (ioMode === 'file') {
-                (0, daemon_logs_1.appendDaemonLogLine)('supervisor', mcpFail);
+                (0, daemon_logs_1.appendDaemonLogLine)('supervisor', `${new Date().toISOString()} ${mcpFail}`);
             }
             else {
                 console.error(mcpFail);
+                console.error(`[agent-deck] See ${(0, daemon_logs_1.resolveDaemonLogPath)('mcp')}`);
                 console.error('[agent-deck] Run: agent-deck stop && agent-deck start');
             }
+            surfaceChildLogTail('mcp', ioMode);
         }
         else {
             mcpPid = mcpChild.pid ?? 0;
@@ -335,6 +643,9 @@ async function runStart(options = {}) {
         cliPid: process.pid,
         startedAt: new Date().toISOString(),
     });
+    ownsRunState = true;
+    startupPhase = null;
+    (0, shutdown_reason_1.clearLastStartFailure)();
     const dashboardLine = uiDist
         ? (0, dashboard_open_1.formatDashboardStatusLine)()
         : 'Dashboard  (UI bundle missing — use npm run dev:all for dev UI)';
@@ -369,8 +680,6 @@ async function runStart(options = {}) {
             console.warn(`[agent-deck] ${result.message ?? 'Failed to open dashboard'}`);
         }
     }
-    process.on('SIGINT', () => void shutdown(0));
-    process.on('SIGTERM', () => void shutdown(0));
     await new Promise(() => {
         // keep alive until signal
     });
@@ -388,7 +697,7 @@ async function runDoctor() {
         console.error('FAIL: Node.js 20+ required (24 recommended — current OS default)');
         ok = false;
     }
-    else if (![20, 22, 23, 24, 25, 26].includes(nodeMajor)) {
+    else if (!(0, node_runtime_1.isSupportedNodeMajor)(nodeMajor)) {
         console.error('FAIL: Unsupported Node.js major for better-sqlite3 prebuilds');
         console.error('     Use Node 20+; Node 24 is the default target');
         ok = false;
@@ -447,6 +756,21 @@ async function runDoctor() {
     else {
         console.warn('WARN: Agent Deck is not running (agent-deck start)');
     }
+    // A store→sqlite import that failed leaves a healthy-looking backend serving a
+    // stale snapshot, so doctor has to fail on it (NOT-123).
+    const lastReindex = (0, backend_runtime_1.readLastReindex)();
+    const [reindexHeadline, ...reindexDetail] = (0, store_1.formatLastReindex)(lastReindex);
+    if (reindexHeadline) {
+        if (lastReindex?.ok) {
+            console.log(`OK: ${reindexHeadline}`);
+            reindexDetail.forEach((line) => console.log(`    ${line}`));
+        }
+        else {
+            console.error(`FAIL: ${reindexHeadline}`);
+            reindexDetail.forEach((line) => console.error(`      ${line}`));
+            ok = false;
+        }
+    }
     return ok ? 0 : 1;
 }
 //# sourceMappingURL=start.js.map