agent-tempo 1.0.1

package/dist/cli/sa-preflight.d.ts

@@ -0,0 +1,99 @@
+/** Single source of truth — must match `SEARCH_ATTRIBUTES` in `src/cli/startup.ts`. */
+export declare const REQUIRED_SEARCH_ATTRIBUTES: ReadonlyArray<{
+    name: string;
+    type: 'Keyword' | 'Bool';
+}>;
+export interface SearchAttributePreflightOpts {
+    temporalAddress: string;
+    temporalNamespace: string;
+    /**
+     * Optional test seam — given a namespace, return the set of search
+     * attribute names that ARE currently registered. Defaults to
+     * {@link defaultProbeRegisteredAttributes} which shells out to
+     * `temporal operator search-attribute list`.
+     */
+    probe?: (opts: {
+        temporalAddress: string;
+        temporalNamespace: string;
+    }) => Promise<Set<string>>;
+}
+export interface SearchAttributePreflightResult {
+    ok: boolean;
+    /** Subset of `REQUIRED_SEARCH_ATTRIBUTES` that the probe couldn't find. */
+    missing: ReadonlyArray<typeof REQUIRED_SEARCH_ATTRIBUTES[number]>;
+    /** Formatted, paste-friendly error message — populated when `ok === false`. */
+    message?: string;
+    /** Probe error, if the call failed entirely (e.g. `temporal` CLI not on PATH). */
+    probeError?: string;
+}
+/**
+ * Default probe — shells out to `temporal operator search-attribute list`.
+ * Returns an empty set on any error so callers fall through to the
+ * "missing all" branch with an explanatory `probeError` in the result.
+ */
+export declare function defaultProbeRegisteredAttributes(opts: {
+    temporalAddress: string;
+    temporalNamespace: string;
+}): Promise<Set<string>>;
+/**
+ * Format the missing-SA error message. Paste-friendly: operators copy the
+ * `temporal operator search-attribute create` block verbatim.
+ */
+export declare function formatPreflightError(missing: ReadonlyArray<typeof REQUIRED_SEARCH_ATTRIBUTES[number]>, namespace: string, probeError?: string): string;
+/**
+ * Verify all {@link REQUIRED_SEARCH_ATTRIBUTES} are registered on the
+ * given namespace. Returns a structured result — callers decide whether
+ * to log+continue (boot bootstrap step) or exit non-zero (daemon start).
+ */
+export declare function verifySearchAttributes(opts: SearchAttributePreflightOpts): Promise<SearchAttributePreflightResult>;
+/**
+ * Outcome of a single `temporal operator search-attribute create` invocation.
+ *
+ * Pre-#605 the two registration call sites (`commands.ts:registerSearchAttributes`
+ * and `startup.ts:stepSearchAttrs`) ran the create command with `stdio: 'ignore'`
+ * and swallowed every non-zero exit as "already exists". That hid the
+ * SQLite dev-server's 10-Keyword-per-namespace cap (and any other genuine
+ * failure) until a downstream workflow start crashed with the confusing
+ * `INVALID_ARGUMENT: search attribute "..." is not defined` — hours later
+ * and miles away from the real cause.
+ */
+export type RegistrationStatus = 'created' | 'already-exists' | 'failed';
+export interface RegistrationResult {
+    attr: typeof REQUIRED_SEARCH_ATTRIBUTES[number];
+    status: RegistrationStatus;
+    /** stderr from the temporal CLI, populated when `status === 'failed'`. */
+    detail?: string;
+}
+/**
+ * Pure classifier — turn a temporal CLI exit into a {@link RegistrationStatus}.
+ * Extracted from {@link registerSearchAttribute} so the matching rules can
+ * be unit-tested without mocking `child_process`.
+ *
+ * Rules:
+ *   - exit code 0                  → `created`
+ *   - stderr/stdout matches the    → `already-exists` (idempotent)
+ *     standard Temporal markers
+ *   - anything else                → `failed` (with detail for the operator)
+ */
+export declare function classifyRegistrationOutput(exitCode: number | null, output: string, errorMessage?: string): {
+    status: RegistrationStatus;
+    detail?: string;
+};
+/**
+ * Register one search attribute. Captures stderr so callers can
+ * distinguish "already-exists" (idempotent expected case) from real
+ * failures (CLI missing, server unreachable, namespace cap exceeded, …).
+ */
+export declare function registerSearchAttribute(attr: typeof REQUIRED_SEARCH_ATTRIBUTES[number], temporalAddress: string, namespace: string): RegistrationResult;
+/**
+ * Hard variant for the daemon boot path — verify, and if missing, write the
+ * actionable error to stderr and exit non-zero. Returns when all attributes
+ * are present; never returns in the failure branch.
+ *
+ * The caller hands in a `processExit` injectable so tests can assert the
+ * call without crashing the test runner.
+ */
+export declare function assertSearchAttributesOrExit(opts: SearchAttributePreflightOpts & {
+    processExit?: (code: number) => never;
+    log?: (line: string) => void;
+}): Promise<void>;

package/dist/cli/sa-preflight.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIRED_SEARCH_ATTRIBUTES = void 0;
+exports.defaultProbeRegisteredAttributes = defaultProbeRegisteredAttributes;
+exports.formatPreflightError = formatPreflightError;
+exports.verifySearchAttributes = verifySearchAttributes;
+exports.classifyRegistrationOutput = classifyRegistrationOutput;
+exports.registerSearchAttribute = registerSearchAttribute;
+exports.assertSearchAttributesOrExit = assertSearchAttributesOrExit;
+/**
+ * Search-attribute preflight (PR-3 of the v1.0 rebrand).
+ *
+ * After the wire-level rename from `ClaudeTempo*` to `AgentTempo*`, every
+ * Temporal namespace agent-tempo / agent-tempo touches needs the new
+ * search attributes registered before workflows can start. Self-hosted
+ * Temporal makes registration a privileged one-shot operator action — the
+ * daemon can't do it itself, but it CAN refuse to boot with an actionable
+ * error so operators don't see a confusing
+ * `INVALID_ARGUMENT: search attribute "AgentTempoEnsemble" is not defined`
+ * deep in workflow-start RPC failures hours later.
+ *
+ * This module is dependency-injected over a `searchAttributesPresent`
+ * probe so tests can simulate every namespace-state branch without
+ * touching a real Temporal server.
+ *
+ * Wiring:
+ *   - `src/cli/startup.ts` `searchAttrs` step uses the verify-or-instruct
+ *     output to surface the actionable error in the TUI bootstrap surface.
+ *   - `src/daemon.ts` boot path calls {@link verifySearchAttributes}
+ *     directly to fail fast on `agent-tempo daemon start` before the worker
+ *     tries to register workflows.
+ */
+const child_process_1 = require("child_process");
+/** Single source of truth — must match `SEARCH_ATTRIBUTES` in `src/cli/startup.ts`. */
+exports.REQUIRED_SEARCH_ATTRIBUTES = Object.freeze([
+    { name: 'AgentTempoHostname', type: 'Keyword' },
+    { name: 'AgentTempoGitRoot', type: 'Keyword' },
+    { name: 'AgentTempoEnsemble', type: 'Keyword' },
+    { name: 'AgentTempoPlayerId', type: 'Keyword' },
+    { name: 'AgentTempoPlayerType', type: 'Keyword' },
+    { name: 'AgentTempoIsConductor', type: 'Bool' },
+    { name: 'AgentTempoAttachedHost', type: 'Keyword' },
+    { name: 'AgentTempoAttachmentState', type: 'Keyword' },
+    { name: 'AgentTempoAttachmentId', type: 'Keyword' },
+]);
+/**
+ * Default probe — shells out to `temporal operator search-attribute list`.
+ * Returns an empty set on any error so callers fall through to the
+ * "missing all" branch with an explanatory `probeError` in the result.
+ */
+async function defaultProbeRegisteredAttributes(opts) {
+    const args = [
+        'operator', 'search-attribute', 'list',
+        '--address', opts.temporalAddress,
+        '--namespace', opts.temporalNamespace,
+    ];
+    const raw = (0, child_process_1.execFileSync)('temporal', args, {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    // The CLI prints a human table; we only need the leading column. Each row
+    // starts with the attribute name as the first whitespace-delimited token.
+    // Header row (and blank lines) are filtered by the AgentTempo prefix /
+    // alphanumeric guard below.
+    const names = new Set();
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const first = trimmed.split(/\s+/, 1)[0];
+        if (/^[A-Za-z][A-Za-z0-9_]*$/.test(first))
+            names.add(first);
+    }
+    return names;
+}
+/**
+ * Format the missing-SA error message. Paste-friendly: operators copy the
+ * `temporal operator search-attribute create` block verbatim.
+ */
+function formatPreflightError(missing, namespace, probeError) {
+    const lines = [];
+    lines.push(`Required search attributes not registered on namespace '${namespace}'.`);
+    if (probeError) {
+        lines.push(`(Could not probe namespace state: ${probeError})`);
+    }
+    lines.push('');
+    lines.push('Run these commands once per Temporal namespace, then restart the daemon:');
+    lines.push('');
+    for (const attr of missing) {
+        lines.push(`  temporal operator search-attribute create ` +
+            `--name ${attr.name} --type ${attr.type} --namespace ${namespace}`);
+    }
+    lines.push('');
+    lines.push('(See docs/ops/v1.0-migration.md for the full upgrade walkthrough.)');
+    return lines.join('\n');
+}
+/**
+ * Verify all {@link REQUIRED_SEARCH_ATTRIBUTES} are registered on the
+ * given namespace. Returns a structured result — callers decide whether
+ * to log+continue (boot bootstrap step) or exit non-zero (daemon start).
+ */
+async function verifySearchAttributes(opts) {
+    const probe = opts.probe ?? defaultProbeRegisteredAttributes;
+    let registered;
+    let probeError;
+    try {
+        registered = await probe({
+            temporalAddress: opts.temporalAddress,
+            temporalNamespace: opts.temporalNamespace,
+        });
+    }
+    catch (err) {
+        probeError = err instanceof Error ? err.message : String(err);
+        registered = new Set();
+    }
+    const missing = exports.REQUIRED_SEARCH_ATTRIBUTES.filter((a) => !registered.has(a.name));
+    if (missing.length === 0 && !probeError) {
+        return { ok: true, missing: [] };
+    }
+    return {
+        ok: false,
+        missing,
+        probeError,
+        message: formatPreflightError(missing, opts.temporalNamespace, probeError),
+    };
+}
+/**
+ * Pure classifier — turn a temporal CLI exit into a {@link RegistrationStatus}.
+ * Extracted from {@link registerSearchAttribute} so the matching rules can
+ * be unit-tested without mocking `child_process`.
+ *
+ * Rules:
+ *   - exit code 0                  → `created`
+ *   - stderr/stdout matches the    → `already-exists` (idempotent)
+ *     standard Temporal markers
+ *   - anything else                → `failed` (with detail for the operator)
+ */
+function classifyRegistrationOutput(exitCode, output, errorMessage) {
+    if (exitCode === 0)
+        return { status: 'created' };
+    if (/already\s*exists/i.test(output) || /AlreadyExists/.test(output)) {
+        return { status: 'already-exists' };
+    }
+    const detail = output.trim() || errorMessage || `temporal CLI exited ${exitCode ?? 'with no status'}`;
+    return { status: 'failed', detail };
+}
+/**
+ * Register one search attribute. Captures stderr so callers can
+ * distinguish "already-exists" (idempotent expected case) from real
+ * failures (CLI missing, server unreachable, namespace cap exceeded, …).
+ */
+function registerSearchAttribute(attr, temporalAddress, namespace) {
+    const result = (0, child_process_1.spawnSync)('temporal', [
+        'operator', 'search-attribute', 'create',
+        '--address', temporalAddress,
+        '--namespace', namespace,
+        '--name', attr.name,
+        '--type', attr.type,
+    ], { encoding: 'utf8' });
+    const classified = classifyRegistrationOutput(result.status, (result.stderr || '') + (result.stdout || ''), result.error?.message);
+    return { attr, ...classified };
+}
+/**
+ * Hard variant for the daemon boot path — verify, and if missing, write the
+ * actionable error to stderr and exit non-zero. Returns when all attributes
+ * are present; never returns in the failure branch.
+ *
+ * The caller hands in a `processExit` injectable so tests can assert the
+ * call without crashing the test runner.
+ */
+async function assertSearchAttributesOrExit(opts) {
+    const result = await verifySearchAttributes(opts);
+    if (result.ok)
+        return;
+    const log = opts.log ?? ((line) => process.stderr.write(line + '\n'));
+    log('ERROR: ' + result.message);
+    const exit = opts.processExit ?? ((code) => {
+        process.exit(code);
+        // Unreachable, but satisfies the `never` return.
+        throw new Error(`process.exit(${code}) failed`);
+    });
+    exit(1);
+}

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

@@ -0,0 +1,6 @@
+/** Surface used by `src/cli.ts`'s `--dev scenarios` verb. */
+export declare function scenariosCommand(args: {
+    subcommand?: string;
+    name?: string;
+    json?: boolean;
+}): Promise<void>;

package/dist/cli/scenarios-command.js

@@ -0,0 +1,167 @@
+"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.scenariosCommand = scenariosCommand;
+/**
+ * `agent-tempo --dev scenarios <list|show> [name]` — discoverability surface
+ * for the mock-adapter scenario library shipped at the package's repo-root
+ * `scenarios/` directory (ADR 0014 §4.8).
+ *
+ * Crash-proof: imports only `fs`, `path`, the scenario parser, and the
+ * shared CLI output helpers. No Temporal, no rxjs — lives in the same
+ * "always-importable" tier as `help-text.ts` and `daemon-command.ts`. A
+ * conductor can `agent-tempo --dev scenarios list` to enumerate the
+ * library before the dev daemon is even running.
+ *
+ * Resolution rules mirror `MockAttachment.resolveScenarioPath`:
+ *
+ *   1. Absolute path — used verbatim.
+ *   2. Bare name (no separators) — `<package-root>/scenarios/<name>.yaml`.
+ *   3. Relative path — `process.cwd()`-relative.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const scenario_1 = require("../adapters/mock/scenario");
+const out = __importStar(require("./output"));
+/** Walk up from this file's compiled location to the package root. */
+function packageRoot() {
+    // dist/cli/scenarios-command.js → dist/cli → dist → <root>
+    return path.resolve(__dirname, '..', '..');
+}
+function shippedScenariosDir() {
+    return path.join(packageRoot(), 'scenarios');
+}
+/** Surface used by `src/cli.ts`'s `--dev scenarios` verb. */
+async function scenariosCommand(args) {
+    const sub = args.subcommand ?? 'list';
+    switch (sub) {
+        case 'list':
+            await listScenarios(Boolean(args.json));
+            return;
+        case 'show':
+            if (!args.name) {
+                out.error('Usage: agent-tempo --dev scenarios show <name>');
+                process.exit(1);
+            }
+            await showScenario(args.name);
+            return;
+        default:
+            out.error(`Unknown scenarios subcommand "${sub}". Available: list, show.`);
+            process.exit(1);
+    }
+}
+async function listScenarios(asJson) {
+    const dir = shippedScenariosDir();
+    if (!fs.existsSync(dir)) {
+        if (asJson) {
+            out.log(JSON.stringify({ scenarios: [], scenariosDir: dir }));
+            return;
+        }
+        out.warn(`No scenarios directory found at ${dir}.`);
+        out.warn('This agent-tempo install may have been built without dev-mode artifacts.');
+        return;
+    }
+    const entries = fs.readdirSync(dir)
+        .filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'))
+        .sort();
+    const items = entries.map((file) => {
+        const abs = path.join(dir, file);
+        try {
+            const yamlText = fs.readFileSync(abs, 'utf8');
+            const scenario = (0, scenario_1.parseScenario)(yamlText);
+            return {
+                name: scenario.name,
+                file: path.basename(file, path.extname(file)),
+                description: (scenario.description ?? '').split('\n').map((l) => l.trim()).filter(Boolean).join(' '),
+                ruleCount: scenario.rules.length,
+            };
+        }
+        catch (err) {
+            return {
+                name: '(invalid)',
+                file: path.basename(file, path.extname(file)),
+                description: `parse error: ${err?.message ?? err}`,
+                ruleCount: 0,
+            };
+        }
+    });
+    if (asJson) {
+        out.log(JSON.stringify({ scenarios: items, scenariosDir: dir }, null, 2));
+        return;
+    }
+    if (items.length === 0) {
+        out.log(`No scenarios found in ${dir}.`);
+        return;
+    }
+    out.log(`Mock-adapter scenarios in ${dir}:\n`);
+    for (const item of items) {
+        out.log(`  ${item.file}  (${item.ruleCount} rule${item.ruleCount === 1 ? '' : 's'})`);
+        if (item.description) {
+            out.log(`    ${item.description}`);
+        }
+    }
+    out.log('\nUse with: agent-tempo --dev recruit <name> --agent mock --mockMode scripted --mockScenario <name>');
+}
+async function showScenario(reference) {
+    const abs = resolveCliReference(reference);
+    if (!fs.existsSync(abs)) {
+        out.error(`Scenario file not found: ${abs}`);
+        process.exit(1);
+    }
+    const yamlText = fs.readFileSync(abs, 'utf8');
+    // Validate while displaying so users get an immediate "this YAML is fine"
+    // signal alongside the printed body. Show the raw YAML even on parse
+    // failure so operators can spot the offending line.
+    try {
+        (0, scenario_1.parseScenario)(yamlText);
+    }
+    catch (err) {
+        out.error(`(scenario validation failed: ${err?.message ?? err})`);
+        out.error('Showing raw YAML below regardless:\n');
+    }
+    out.log(`# ${abs}\n`);
+    out.log(yamlText.replace(/\n$/, ''));
+}
+function resolveCliReference(reference) {
+    if (path.isAbsolute(reference))
+        return reference;
+    if (!reference.includes('/') && !reference.includes(path.sep)) {
+        const stem = reference.endsWith('.yaml') || reference.endsWith('.yml')
+            ? reference
+            : `${reference}.yaml`;
+        return path.join(shippedScenariosDir(), stem);
+    }
+    return path.resolve(process.cwd(), reference);
+}

package/dist/cli/startup.d.ts

@@ -0,0 +1,112 @@
+import { Config } from '../config';
+import type { EnsembleSummary } from '../client/interface';
+export type StepName = 'legacyHomeMigration' | 'preflight' | 'mcpConfig' | 'temporalReach' | 'searchAttrs' | 'daemonBoot' | 'badgeCollection';
+/** Structured per-step result. `ok` = ran successfully; `skipped` = cache hit;
+ *  `action-taken` = needed repair (e.g. started daemon, registered MCP);
+ *  `failed` = non-fatal failure recorded for the TUI to surface. */
+export interface StepOutcome {
+    status: 'ok' | 'skipped' | 'action-taken' | 'failed';
+    durationMs: number;
+    detail?: string;
+}
+export interface OutdatedVersionBadge {
+    latest: string;
+    severity: 'major' | 'minor';
+}
+export interface DaemonLogErrorsBadge {
+    count: number;
+    /** Up to 3 most recent ERROR lines from the daemon log tail. */
+    sample: string[];
+    logPath: string;
+}
+export interface BootstrapResult {
+    durationMs: number;
+    steps: Record<StepName, StepOutcome>;
+    badges: {
+        /** Orphan count from `queryOrphanedSessions` on this host. Always fresh. */
+        orphanCount: number;
+        /** Undefined = up-to-date, patch-only, or npm-check offline / timed out. */
+        outdatedVersion?: OutdatedVersionBadge;
+        /** Undefined = clean daemon-log tail. */
+        daemonLogErrors?: DaemonLogErrorsBadge;
+    };
+    /** Pre-fetched for HomeView's first render; TUI re-polls every 10s. */
+    ensembles: EnsembleSummary[];
+    cwd: string;
+    /** `null` when not in a git dir. */
+    cwdGitRoot: string | null;
+}
+export interface BootstrapArgs {
+    config: Config;
+    cwd?: string;
+    /** Injectable clock for tests. */
+    now?: () => number;
+    /** Injectable cache-path override for tests. Default: `AGENT_TEMPO_HOME`. */
+    cacheDir?: string;
+    /** Injectable npm-version fetcher for tests. Default: live registry fetch. */
+    fetchLatestVersion?: (pkgName: string, timeoutMs: number) => Promise<string | null>;
+    /** Binary version (defaults to `require('../../package.json').version`). Tests pin. */
+    binaryVersion?: string;
+    /**
+     * Inject step-5 daemon-boot. Default spawns the real daemon via
+     * `startDaemon` (up to 30s wait). Tests should always override to avoid
+     * spawning a real daemon process from the test harness. Returning
+     * `'skipped'` simulates "daemon already running"; `'action-taken'`
+     * simulates a successful start; `'failed'` + `detail` simulates failure.
+     */
+    daemonBoot?: (config: Config) => Promise<StepOutcome>;
+    /**
+     * PR-2 of the v1.0 rebrand — one-shot copy of `~/.agent-tempo/` →
+     * `~/.agent-tempo/`. Runs once on first boot of the new binary; idempotent
+     * thereafter. Tests should override to avoid touching real $HOME.
+     *
+     * Failure here MUST NOT block the boot path — record `'failed'` with a
+     * detail string and let the rest of bootstrap proceed.
+     */
+    legacyHomeMigration?: () => Promise<StepOutcome>;
+    /**
+     * Inject the Temporal reachability probe (steps 3 + 6). Tests override
+     * to avoid real network I/O — default performs `createTemporalConnection`
+     * with a 3s timeout. Returning `false` simulates unreachable;
+     * `true` simulates reachable (step 3 caches success, step 6 still
+     * attempts connect but is tolerant of failure).
+     */
+    isTemporalReachable?: (config: Config) => Promise<boolean>;
+}
+type CacheStepKey = 'preflight' | 'mcpConfig' | 'temporalReach' | 'searchAttrs' | 'npmVersionCheck';
+interface CacheStepEntry {
+    lastSuccess: string;
+    /** MCP config file mtime snapshot at last success — `mcpConfig` only. */
+    configMtime?: string;
+    /** Cached npm-registry result — `npmVersionCheck` only. */
+    result?: {
+        latest: string;
+    };
+}
+interface BootstrapCache {
+    schemaVersion: number;
+    binaryVersion: string;
+    steps: Partial<Record<CacheStepKey, CacheStepEntry>>;
+}
+/** 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. */
+export declare function readCache(cacheDir: string, binaryVersion: string): BootstrapCache;
+/** Best-effort cache write; never throws (a cache failure must not break bootstrap). */
+export declare function writeCache(cacheDir: string, cache: BootstrapCache): void;
+/** Decide if a cached step is fresh enough to skip. `undefined` entry or
+ *  `lastSuccess` older than `ttlMs` → stale. */
+export declare function isCacheFresh(entry: CacheStepEntry | undefined, ttlMs: number, now: number): boolean;
+/** 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)
+ */
+export declare function classifyVersion(installed: string, latest: string): OutdatedVersionBadge | undefined;
+/**
+ * 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.
+ */
+export declare function bootstrap(args: BootstrapArgs): Promise<BootstrapResult>;
+export {};