agent-tempo 1.0.1

package/dist/cli/startup.js

@@ -0,0 +1,641 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCache = readCache;
+exports.writeCache = writeCache;
+exports.isCacheFresh = isCacheFresh;
+exports.classifyVersion = classifyVersion;
+exports.bootstrap = bootstrap;
+/**
+ * Auto-provisioning bootstrap state machine (#289 / S7 of #285).
+ *
+ * Bare `agent-tempo` invocation runs this on the way to the TUI. Six steps
+ * get the user from "nothing installed" → "ready for the TUI home view";
+ * each step is idempotent and cached where safe so a warm system completes
+ * in <50ms (steps 1–5) and a cold system stays under ~200ms.
+ *
+ * Step 7 is the caller's TUI handoff (`src/cli.ts` default path) — this
+ * module only produces the `BootstrapResult` that the TUI consumes as
+ * initial props.
+ *
+ * Per-step caching (`~/.agent-tempo/.bootstrap-cache.json`) is keyed by
+ * `schemaVersion` + `binaryVersion` so an upgrade wipes the cache and the
+ * new binary re-validates everything. Steps with volatile state (daemon
+ * liveness, orphan count) are never cached.
+ *
+ * No auto-resume on bare invocation (#289 pin item 1) — the home view is
+ * responsible for letting the user pick a parked ensemble to restore. Step
+ * 6 prefetches the ensemble list so the TUI renders instantly.
+ */
+const perf_hooks_1 = require("perf_hooks");
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const semver = __importStar(require("semver"));
+const client_1 = require("@temporalio/client");
+const config_1 = require("../config");
+const connection_1 = require("../connection");
+const mcp_1 = require("./mcp");
+const daemon_1 = require("./daemon");
+const orphans_1 = require("../reconcile/orphans");
+const client_2 = require("../client");
+const os_1 = require("os");
+const git_info_1 = require("../git-info");
+const legacy_migration_1 = require("./legacy-migration");
+// ─────────────────────────────────────────────────────────────────────────
+// Cache (schema v1)
+// ─────────────────────────────────────────────────────────────────────────
+const CACHE_SCHEMA_VERSION = 1;
+const CACHE_FILENAME = '.bootstrap-cache.json';
+function defaultCache(binaryVersion) {
+    return { schemaVersion: CACHE_SCHEMA_VERSION, binaryVersion, steps: {} };
+}
+/** Read the cache, validating schema + binary version. Any failure returns
+ *  a fresh empty cache — malformed / upgrade-mismatched files are treated
+ *  as a cache miss, the caller just does a cold bootstrap. */
+function readCache(cacheDir, binaryVersion) {
+    const cachePath = path.join(cacheDir, CACHE_FILENAME);
+    try {
+        const raw = fs.readFileSync(cachePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.schemaVersion !== CACHE_SCHEMA_VERSION)
+            return defaultCache(binaryVersion);
+        if (parsed.binaryVersion !== binaryVersion)
+            return defaultCache(binaryVersion);
+        if (!parsed.steps || typeof parsed.steps !== 'object')
+            return defaultCache(binaryVersion);
+        return {
+            schemaVersion: CACHE_SCHEMA_VERSION,
+            binaryVersion,
+            steps: parsed.steps,
+        };
+    }
+    catch {
+        // Missing / unreadable / malformed — treat as cold.
+        return defaultCache(binaryVersion);
+    }
+}
+/** Best-effort cache write; never throws (a cache failure must not break bootstrap). */
+function writeCache(cacheDir, cache) {
+    const cachePath = path.join(cacheDir, CACHE_FILENAME);
+    try {
+        fs.mkdirSync(cacheDir, { recursive: true });
+        fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2));
+    }
+    catch { /* non-fatal — next run will re-fill */ }
+}
+/** Decide if a cached step is fresh enough to skip. `undefined` entry or
+ *  `lastSuccess` older than `ttlMs` → stale. */
+function isCacheFresh(entry, ttlMs, now) {
+    if (!entry?.lastSuccess)
+        return false;
+    const last = Date.parse(entry.lastSuccess);
+    if (!Number.isFinite(last))
+        return false;
+    return now - last < ttlMs;
+}
+const TTL_24H = 24 * 60 * 60 * 1000;
+const TTL_60S = 60 * 1000;
+// ─────────────────────────────────────────────────────────────────────────
+// Search-attribute list — imported from sa-preflight.ts so commands.ts,
+// startup.ts, and the daemon-boot preflight all share one source of truth
+// (#605 consolidated the two duplicated literals).
+// ─────────────────────────────────────────────────────────────────────────
+const sa_preflight_1 = require("./sa-preflight");
+// ─────────────────────────────────────────────────────────────────────────
+// Semver-aware outdated-version badge rendering (#289 pin item 4)
+// ─────────────────────────────────────────────────────────────────────────
+/** Decide the outdated-version badge shape per the policy table:
+ *  - major/minor behind → badge with severity
+ *  - patch-only → silent
+ *  - prerelease vs stable mismatches → silent (respect release channel)
+ */
+function classifyVersion(installed, latest) {
+    const i = semver.parse(installed);
+    const l = semver.parse(latest);
+    if (!i || !l)
+        return undefined;
+    if (semver.gte(i, l))
+        return undefined;
+    const iPrerelease = i.prerelease.length > 0;
+    const lPrerelease = l.prerelease.length > 0;
+    // Channel respect: never nudge prerelease→stable downgrade or stable→prerelease.
+    if (iPrerelease && !lPrerelease)
+        return undefined;
+    if (!iPrerelease && lPrerelease)
+        return undefined;
+    // Prerelease iteration of the same minor — beta iteration is expected.
+    if (iPrerelease && lPrerelease && i.major === l.major && i.minor === l.minor) {
+        return undefined;
+    }
+    const diff = semver.diff(installed, latest);
+    if (diff === 'major' || diff === 'premajor')
+        return { latest, severity: 'major' };
+    if (diff === 'minor' || diff === 'preminor')
+        return { latest, severity: 'minor' };
+    // 'patch', 'prepatch', 'prerelease' → silent
+    return undefined;
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Step helpers
+// ─────────────────────────────────────────────────────────────────────────
+async function timed(fn) {
+    const start = perf_hooks_1.performance.now();
+    const result = await fn();
+    return { result, durationMs: perf_hooks_1.performance.now() - start };
+}
+/** Fetch the latest published version from npm with a hard timeout. Never
+ *  throws — returns `null` on any network / timeout / parse error so the
+ *  caller can silently proceed (spec pin item 3). */
+async function defaultFetchLatestVersion(pkgName, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${pkgName}/latest`, {
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        const body = await res.json();
+        return typeof body.version === 'string' ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Bounded tail-read budget. Long-running daemons can accumulate multi-MB
+ *  logs; reading the entire file on every bootstrap is wasteful. Seek back
+ *  from EOF by at most this many bytes — 32 KiB comfortably covers the last
+ *  few hundred log lines without loading the full file. */
+const DAEMON_LOG_TAIL_BYTES = 32 * 1024;
+/** Read the last ~200 ERROR-tagged lines from the daemon log. Returns at
+ *  most 3 samples. Bounded-tail read (see {@link DAEMON_LOG_TAIL_BYTES}). */
+function daemonLogErrorTail(logPath) {
+    let fd;
+    try {
+        const stat = fs.statSync(logPath);
+        const size = stat.size;
+        if (size === 0)
+            return undefined;
+        const start = Math.max(0, size - DAEMON_LOG_TAIL_BYTES);
+        const length = size - start;
+        const buf = Buffer.alloc(length);
+        fd = fs.openSync(logPath, 'r');
+        fs.readSync(fd, buf, 0, length, start);
+        const content = buf.toString('utf8');
+        const lines = content.split(/\r?\n/);
+        // If we seeked mid-file, the first line may be a partial — discard it.
+        const tail = start > 0 ? lines.slice(1) : lines;
+        const errors = tail.filter((l) => /\bERROR\b/i.test(l));
+        if (errors.length === 0)
+            return undefined;
+        return { count: errors.length, sample: errors.slice(-3), logPath };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* ignore */ }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Individual steps
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Default step-0 implementation — invokes the one-shot legacy home migration
+ * (`~/.agent-tempo/` → `~/.agent-tempo/`). Idempotent: re-runs are
+ * `'skipped'` once the marker is in place. Failure is recorded but never
+ * blocks bootstrap (PR-2 brief).
+ */
+async function defaultLegacyHomeMigrationStep() {
+    const t0 = perf_hooks_1.performance.now();
+    try {
+        const result = await (0, legacy_migration_1.migrateLegacyHome)();
+        const durationMs = perf_hooks_1.performance.now() - t0;
+        const detail = (0, legacy_migration_1.formatMigrationResult)(result);
+        switch (result.status) {
+            case 'no-legacy':
+            case 'already-migrated':
+                return { status: 'skipped', durationMs, detail };
+            case 'migrated':
+                return { status: 'action-taken', durationMs, detail };
+            case 'skipped':
+                return { status: 'skipped', durationMs, detail };
+            case 'failed':
+                return { status: 'failed', durationMs, detail };
+        }
+    }
+    catch (err) {
+        return {
+            status: 'failed',
+            durationMs: perf_hooks_1.performance.now() - t0,
+            detail: `legacy-migration crashed: ${err.message}`,
+        };
+    }
+}
+async function stepPreflight(cache, now) {
+    if (isCacheFresh(cache.steps.preflight, TTL_24H, now)) {
+        return { status: 'skipped', durationMs: 0 };
+    }
+    const { result, durationMs } = await timed(() => {
+        const errors = [];
+        const major = parseInt(process.version.slice(1), 10);
+        if (major < 20)
+            errors.push(`Node.js 20+ required, found ${process.version}`);
+        // No `claude` binary probe here: the user's default agent may be
+        // `copilot`, and spawn-time errors are more actionable than a startup
+        // preflight block. CI environments without claude installed also need
+        // bootstrap to succeed so the TUI can render diagnostics. A future
+        // TUI badge can surface "claude not found" when the agent requires it.
+        try {
+            fs.mkdirSync(config_1.AGENT_TEMPO_HOME, { recursive: true });
+            fs.accessSync(config_1.AGENT_TEMPO_HOME, fs.constants.W_OK);
+        }
+        catch {
+            errors.push(`${config_1.AGENT_TEMPO_HOME} is not writable. Check permissions or set $HOME.`);
+        }
+        return errors;
+    });
+    if (result.length > 0) {
+        return { status: 'failed', durationMs, detail: result.join('; ') };
+    }
+    cache.steps.preflight = { lastSuccess: new Date(now).toISOString() };
+    return { status: 'ok', durationMs };
+}
+async function stepMcpConfig(cache, cwd, now) {
+    const cached = cache.steps.mcpConfig;
+    let configMtime;
+    try {
+        const projectMcp = path.join(cwd, '.mcp.json');
+        if (fs.existsSync(projectMcp)) {
+            configMtime = fs.statSync(projectMcp).mtime.toISOString();
+        }
+    }
+    catch { /* ignore — no-mtime path */ }
+    if (isCacheFresh(cached, TTL_24H, now) &&
+        cached?.configMtime === configMtime) {
+        return { status: 'skipped', durationMs: 0 };
+    }
+    const { result: outcome, durationMs } = await timed(() => {
+        if ((0, mcp_1.isMcpConfigured)(cwd)) {
+            return { status: 'ok', durationMs: 0 };
+        }
+        // Install into global user scope (matches current `init` behavior).
+        if (!(0, mcp_1.isGlobalMcpRegistered)() && (0, mcp_1.addGlobalMcp)()) {
+            return { status: 'action-taken', durationMs: 0, detail: 'registered agent-tempo in user MCP scope' };
+        }
+        return { status: 'failed', durationMs: 0, detail: 'Could not register agent-tempo MCP. Run `agent-tempo init` manually.' };
+    });
+    if (outcome.status !== 'failed') {
+        cache.steps.mcpConfig = {
+            lastSuccess: new Date(now).toISOString(),
+            ...(configMtime !== undefined ? { configMtime } : {}),
+        };
+    }
+    return { ...outcome, durationMs };
+}
+async function stepTemporalReach(cache, config, now, reachableProbe) {
+    if (isCacheFresh(cache.steps.temporalReach, TTL_60S, now)) {
+        return { status: 'skipped', durationMs: 0 };
+    }
+    const { result: outcome, durationMs } = await timed(async () => {
+        const reachable = await reachableProbe(config);
+        if (reachable)
+            return { status: 'ok', durationMs: 0 };
+        // Auto-start only when the address is local. Remote failures surface
+        // an actionable error; we don't try to spawn a remote server.
+        if (!isLocalAddress(config.temporalAddress)) {
+            return {
+                status: 'failed',
+                durationMs: 0,
+                detail: `Cannot reach remote Temporal at ${config.temporalAddress}. Check TEMPORAL_ADDRESS + network.`,
+            };
+        }
+        if (!hasTemporalCli()) {
+            return {
+                status: 'failed',
+                durationMs: 0,
+                detail: 'temporal CLI not found on PATH. Install from https://docs.temporal.io/cli and re-run.',
+            };
+        }
+        const started = await startTemporalDevServer(config, reachableProbe);
+        if (started) {
+            return { status: 'action-taken', durationMs: 0, detail: `started temporal dev server at ${config.temporalAddress}` };
+        }
+        return {
+            status: 'failed',
+            durationMs: 0,
+            detail: `temporal dev server did not become reachable at ${config.temporalAddress}`,
+        };
+    });
+    if (outcome.status !== 'failed') {
+        cache.steps.temporalReach = { lastSuccess: new Date(now).toISOString() };
+    }
+    return { ...outcome, durationMs };
+}
+async function stepSearchAttrs(cache, config, now) {
+    if (isCacheFresh(cache.steps.searchAttrs, TTL_24H, now)) {
+        return { status: 'skipped', durationMs: 0 };
+    }
+    const { result: outcome, durationMs } = await timed(() => {
+        // Per-attr classification via `registerSearchAttribute` (#605) —
+        // distinguishes `already-exists` (idempotent expected case) from real
+        // failures. Pre-#605 every non-zero exit was swallowed as "already
+        // registered", masking the SQLite dev-server's 10-Keyword-per-namespace
+        // cap and other genuine errors until a downstream workflow start failed
+        // with the confusing `INVALID_ARGUMENT: search attribute ... is not
+        // defined`.
+        const failures = [];
+        for (const attr of sa_preflight_1.REQUIRED_SEARCH_ATTRIBUTES) {
+            const r = (0, sa_preflight_1.registerSearchAttribute)(attr, config.temporalAddress, config.temporalNamespace);
+            if (r.status === 'failed') {
+                failures.push(`${attr.name}: ${r.detail ?? 'unknown error'}`);
+            }
+        }
+        if (failures.length > 0) {
+            return {
+                status: 'failed',
+                durationMs: 0,
+                detail: `Failed to register ${failures.length} search attribute(s):\n  ${failures.join('\n  ')}`,
+            };
+        }
+        return { status: 'ok', durationMs: 0 };
+    });
+    if (outcome.status !== 'failed') {
+        cache.steps.searchAttrs = { lastSuccess: new Date(now).toISOString() };
+    }
+    return { ...outcome, durationMs };
+}
+async function stepDaemonBootAsync(config) {
+    const start = perf_hooks_1.performance.now();
+    if ((0, daemon_1.isDaemonRunning)()) {
+        // Cheap authoritative check: heartbeat file mtime must be within 2×
+        // the interval — otherwise the daemon is hung.
+        try {
+            const age = Date.now() - fs.statSync(daemon_1.DAEMON_HEARTBEAT_PATH).mtimeMs;
+            if (age > daemon_1.HEARTBEAT_INTERVAL_MS * daemon_1.HEARTBEAT_STALE_MULTIPLIER) {
+                return {
+                    status: 'failed',
+                    durationMs: perf_hooks_1.performance.now() - start,
+                    detail: `daemon heartbeat stale (${Math.round(age / 1000)}s). Check ${daemon_1.DAEMON_LOG_PATH}.`,
+                };
+            }
+        }
+        catch { /* no heartbeat file yet — daemon is fresh, treat as ok */ }
+        return { status: 'skipped', durationMs: perf_hooks_1.performance.now() - start };
+    }
+    try {
+        const pid = await (0, daemon_1.startDaemon)(config);
+        return {
+            status: 'action-taken',
+            durationMs: perf_hooks_1.performance.now() - start,
+            detail: `started daemon (pid ${pid})`,
+        };
+    }
+    catch (err) {
+        return {
+            status: 'failed',
+            durationMs: perf_hooks_1.performance.now() - start,
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+async function stepBadgeCollection(config, cache, now, binaryVersion, fetchLatest, reachableProbe) {
+    const start = perf_hooks_1.performance.now();
+    let orphanCount = 0;
+    let ensembles = [];
+    let outdatedVersion;
+    const hostname = (0, os_1.hostname)();
+    // Sub-A: orphan count + ensembles list — Temporal connect runs through the
+    // injected `reachableProbe` first so a stale `temporalAddress` can't block
+    // the TUI. Hard 3s wall-clock budget on the actual connect + queries.
+    let connection;
+    try {
+        if (!(await reachableProbe(config)))
+            throw new Error('unreachable');
+        connection = await Promise.race([
+            (0, connection_1.createTemporalConnection)(config),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 3000)),
+        ]);
+        const client = new client_1.Client({ connection, namespace: config.temporalNamespace });
+        const tempo = (0, client_2.createTempoClient)(client);
+        const [orphans, summaries] = await Promise.all([
+            (0, orphans_1.queryOrphanedSessions)(client, { hostname }).catch(() => []),
+            tempo.discoverEnsembles().catch(() => []),
+        ]);
+        orphanCount = orphans.length;
+        ensembles = summaries;
+    }
+    catch { /* degraded — bootstrap still returns, TUI shows connection error */ }
+    finally {
+        if (connection)
+            try {
+                await connection.close();
+            }
+            catch { /* ignore */ }
+    }
+    // Sub-B: npm-version check — 24h cached, 500ms AbortController timeout,
+    // silent fallback on network failure (pin items 2 + 3).
+    const cachedNpm = cache.steps.npmVersionCheck;
+    let latest = null;
+    if (isCacheFresh(cachedNpm, TTL_24H, now) && cachedNpm?.result) {
+        latest = cachedNpm.result.latest;
+    }
+    else {
+        latest = await fetchLatest('agent-tempo', 500);
+        if (latest) {
+            cache.steps.npmVersionCheck = {
+                lastSuccess: new Date(now).toISOString(),
+                result: { latest },
+            };
+        }
+        // If fetch returned null (timeout / offline), do NOT update the cache —
+        // next bootstrap will try again immediately.
+    }
+    if (latest) {
+        outdatedVersion = classifyVersion(binaryVersion, latest);
+    }
+    // Sub-C: daemon log error tail. Cheap, always runs.
+    const daemonLogErrors = daemonLogErrorTail(daemon_1.DAEMON_LOG_PATH);
+    return {
+        badges: {
+            orphanCount,
+            ...(outdatedVersion ? { outdatedVersion } : {}),
+            ...(daemonLogErrors ? { daemonLogErrors } : {}),
+        },
+        ensembles,
+        outcome: { status: 'ok', durationMs: perf_hooks_1.performance.now() - start },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Plumbing helpers (Temporal reachability probe + dev-server spawn)
+// ─────────────────────────────────────────────────────────────────────────
+async function isTemporalReachable(config, timeoutMs = 3000) {
+    try {
+        const conn = await Promise.race([
+            (0, connection_1.createTemporalConnection)(config),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeoutMs)),
+        ]);
+        try {
+            const client = new client_1.Client({ connection: conn, namespace: config.temporalNamespace });
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            for await (const _ of client.workflow.list({ query: 'WorkflowId = "__readiness_probe__"' })) {
+                break;
+            }
+        }
+        finally {
+            await conn.close();
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isLocalAddress(address) {
+    const host = address.split(':')[0] || '';
+    return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '';
+}
+function hasTemporalCli() {
+    const cmd = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        (0, child_process_1.execFileSync)(cmd, ['temporal'], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function startTemporalDevServer(config, reachableProbe) {
+    fs.mkdirSync(config_1.AGENT_TEMPO_HOME, { recursive: true });
+    const port = config.temporalAddress.split(':')[1] || '7233';
+    const dbPath = path.join(config_1.AGENT_TEMPO_HOME, 'temporal-data.db');
+    const child = (0, child_process_1.spawn)('temporal', ['server', 'start-dev', '--port', port, '--db-filename', dbPath], {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+    for (let i = 0; i < 20; i++) {
+        await new Promise((r) => setTimeout(r, 500));
+        if (await reachableProbe(config))
+            return true;
+    }
+    return false;
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Public entry point
+// ─────────────────────────────────────────────────────────────────────────
+/** Read the installed package version. Cached behind a function so tests
+ *  can override via `BootstrapArgs.binaryVersion`. */
+function readBinaryVersion() {
+    try {
+        const pkg = require('../../package.json');
+        return pkg.version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/**
+ * Run the 7-step auto-provisioning sequence. Returns a `BootstrapResult`
+ * the caller feeds to the TUI; step 7 (TUI launch) is the caller's
+ * handoff — this function does NOT spawn UI processes.
+ */
+async function bootstrap(args) {
+    const start = perf_hooks_1.performance.now();
+    const cwd = args.cwd ?? process.cwd();
+    const now = (args.now ?? (() => Date.now()))();
+    const cacheDir = args.cacheDir ?? config_1.AGENT_TEMPO_HOME;
+    const binaryVersion = args.binaryVersion ?? readBinaryVersion();
+    const fetchLatest = args.fetchLatestVersion ?? defaultFetchLatestVersion;
+    const cache = readCache(cacheDir, binaryVersion);
+    const reachableProbe = args.isTemporalReachable ?? ((c) => isTemporalReachable(c, 3000));
+    // Step 0: legacy home migration (`~/.agent-tempo/` → `~/.agent-tempo/`)
+    // — PR-2 of the v1.0 rebrand. Runs before preflight so subsequent steps
+    // (cache read, MCP config write, daemon boot) all see the new home.
+    // MUST NOT block bootstrap — failure becomes a `'failed'` step with
+    // `detail`, and we keep going.
+    const legacyHomeMigration = await (args.legacyHomeMigration ?? defaultLegacyHomeMigrationStep)();
+    // Steps 1–5: fail-fast on step 1 so we don't try to register MCP on an
+    // incompatible Node. Each step mutates the cache in-place.
+    const preflight = await stepPreflight(cache, now);
+    // Steps 2 + 3 are independent (MCP config is local fs/shell; Temporal
+    // reachability is network), so run them in parallel — up to ~300ms
+    // cold-path savings when the claude-mcp-list shell-out is slow.
+    const [mcpConfig, temporalReach] = preflight.status === 'failed'
+        ? [
+            { status: 'skipped', durationMs: 0 },
+            { status: 'skipped', durationMs: 0 },
+        ]
+        : await Promise.all([
+            stepMcpConfig(cache, cwd, now),
+            stepTemporalReach(cache, args.config, now, reachableProbe),
+        ]);
+    const searchAttrs = temporalReach.status === 'failed'
+        ? { status: 'skipped', durationMs: 0, detail: 'skipped — temporal unreachable' }
+        : await stepSearchAttrs(cache, args.config, now);
+    const daemonBoot = preflight.status === 'failed'
+        ? { status: 'skipped', durationMs: 0 }
+        : await (args.daemonBoot ?? stepDaemonBootAsync)(args.config);
+    // Step 6: badges + ensembles prefetch. Runs even on partial-failure paths
+    // so the TUI can render something meaningful; Temporal-connect failure
+    // degrades to zeros / empty lists rather than throwing.
+    const badgeStep = await stepBadgeCollection(args.config, cache, now, binaryVersion, fetchLatest, reachableProbe);
+    // Persist cache after all steps — one write per bootstrap.
+    writeCache(cacheDir, cache);
+    return {
+        durationMs: perf_hooks_1.performance.now() - start,
+        steps: {
+            legacyHomeMigration,
+            preflight,
+            mcpConfig,
+            temporalReach,
+            searchAttrs,
+            daemonBoot,
+            badgeCollection: badgeStep.outcome,
+        },
+        badges: badgeStep.badges,
+        ensembles: badgeStep.ensembles,
+        cwd,
+        cwdGitRoot: (0, git_info_1.getGitInfo)(cwd).gitRoot ?? null,
+    };
+}

package/dist/cli/upgrade-command.d.ts

@@ -0,0 +1,5 @@
+import { CliOverrides } from '../config';
+export interface UpgradeOpts extends CliOverrides {
+    version?: string;
+}
+export declare function upgrade(opts: UpgradeOpts): Promise<void>;