agent-tempo 1.0.1

package/dist/cli/dashboard-command.js

@@ -0,0 +1,241 @@
+"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.dashboardCommand = dashboardCommand;
+/**
+ * `agent-tempo dashboard` — open the packaged web dashboard,
+ * optionally minting a single-use pairing token + QR code for
+ * cross-device access. PR-8 of #340.
+ *
+ * **Critical constraint**: like {@link daemon-command}, this module
+ * must NOT import from `@temporalio/*`, `../workflows/*`, or any
+ * module that pulls in the Temporal SDK. The dashboard verb must
+ * remain operable when Temporal itself is broken (same #157
+ * reasoning: a stranded operator with a running daemon should still
+ * be able to run `agent-tempo dashboard` to see what's going on).
+ *
+ * Flow:
+ *   1. Resolve the daemon's port (port-file or `--port` override)
+ *   2. Probe `GET /v1/health` — if the daemon isn't running, exit 1
+ *      with a hint to run `agent-tempo daemon start`
+ *   3. Print the dashboard URL
+ *   4. If `--pair`: POST `/dashboard/api/pair` (with the operator's
+ *      bearer if any) → render a terminal QR + the URL with the
+ *      `?pair=<token>` fragment. The user scans from their phone.
+ *   5. Unless `--no-open`, spawn the platform browser-opener so the
+ *      dashboard shows up immediately.
+ *
+ * Output modes:
+ *   - default: human-readable colored
+ *   - `--json`: single JSON object on stdout, no banners — for
+ *     scripts and CI
+ */
+const http_1 = require("http");
+const child_process_1 = require("child_process");
+const port_file_1 = require("../http/port-file");
+const out = __importStar(require("./output"));
+const DEFAULT_BIND = '127.0.0.1';
+/**
+ * Public entry point — invoked by the CLI dispatcher. Returns void;
+ * exits the process with code 1 on error, 0 on success.
+ */
+async function dashboardCommand(args) {
+    const port = await resolvePort(args, args.json ?? false);
+    if (port === null)
+        return; // resolvePort already exited
+    const bind = args.bind ?? DEFAULT_BIND;
+    const baseUrl = `http://${bind}:${port}`;
+    const healthy = await probeHealth(baseUrl);
+    if (!healthy) {
+        return emitError(args.json ?? false, {
+            error: 'daemon-not-reachable',
+            hint: `No response from ${baseUrl}/v1/health. Run \`agent-tempo daemon start\` and retry.`,
+        });
+    }
+    const dashboardUrl = `${baseUrl}/dashboard/`;
+    let pairResult = null;
+    if (args.pair) {
+        const minted = await mintPairToken(baseUrl, args.bearer);
+        if (!minted.ok) {
+            return emitError(args.json ?? false, {
+                error: 'pair-mint-failed',
+                hint: minted.reason,
+            });
+        }
+        pairResult = {
+            url: `${dashboardUrl}?pair=${encodeURIComponent(minted.token)}`,
+            expiresAt: minted.expiresAt,
+        };
+    }
+    if (args.json) {
+        const payload = {
+            ok: true,
+            url: dashboardUrl,
+            ...(pairResult ? { pair: pairResult } : {}),
+        };
+        out.log(JSON.stringify(payload));
+        return;
+    }
+    // Human-readable output
+    out.heading('agent-tempo dashboard');
+    out.log(`  ${out.cyan(dashboardUrl)}`);
+    if (pairResult) {
+        out.log('');
+        out.log(`  ${out.bold('Cross-device pair:')}`);
+        out.log(`  ${out.cyan(pairResult.url)}`);
+        out.log(`  ${out.dim(`Token expires at ${new Date(pairResult.expiresAt).toLocaleTimeString()} (single-use, 5-min TTL)`)}`);
+        await renderQr(pairResult.url);
+    }
+    if (!args.noOpen) {
+        openInBrowser(dashboardUrl);
+    }
+    else {
+        out.log('');
+        out.log(`  ${out.dim('--no-open: not launching browser')}`);
+    }
+}
+async function resolvePort(args, json) {
+    if (typeof args.port === 'number' && args.port > 0)
+        return args.port;
+    const fromFile = (0, port_file_1.readPortFile)();
+    if (fromFile !== null)
+        return fromFile;
+    emitError(json, {
+        error: 'no-port',
+        hint: 'No daemon port file. Pass --port <N> or run `agent-tempo daemon start` first.',
+    });
+    return null;
+}
+async function probeHealth(baseUrl) {
+    return new Promise((resolve) => {
+        const req = (0, http_1.request)(`${baseUrl}/v1/health`, { method: 'GET', timeout: 3000 }, (res) => {
+            // Drain to avoid leaving the socket open.
+            res.resume();
+            resolve(res.statusCode === 200);
+        });
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => {
+            req.destroy();
+            resolve(false);
+        });
+        req.end();
+    });
+}
+async function mintPairToken(baseUrl, bearer) {
+    return new Promise((resolve) => {
+        const headers = { 'Content-Length': '0' };
+        if (bearer)
+            headers.Authorization = `Bearer ${bearer}`;
+        const req = (0, http_1.request)(`${baseUrl}/dashboard/api/pair`, { method: 'POST', headers, timeout: 3000 }, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => { body += chunk; });
+            res.on('end', () => {
+                if (res.statusCode === 201) {
+                    try {
+                        const parsed = JSON.parse(body);
+                        return resolve({ ok: true, token: parsed.token, expiresAt: parsed.expiresAt });
+                    }
+                    catch (err) {
+                        return resolve({ ok: false, reason: `malformed pair response: ${err instanceof Error ? err.message : String(err)}` });
+                    }
+                }
+                if (res.statusCode === 401)
+                    return resolve({ ok: false, reason: 'unauthorized — pass --bearer <token> or run on the host without bearer auth' });
+                if (res.statusCode === 400)
+                    return resolve({ ok: false, reason: 'pair flow requires bearer auth (loopback skips this)' });
+                resolve({ ok: false, reason: `unexpected status ${res.statusCode}: ${body}` });
+            });
+        });
+        req.on('error', (err) => resolve({ ok: false, reason: err.message }));
+        req.on('timeout', () => {
+            req.destroy();
+            resolve({ ok: false, reason: 'request timed out' });
+        });
+        req.end();
+    });
+}
+/**
+ * Render a QR code in the terminal. `qrcode-terminal` is loaded
+ * lazily so the require cost only hits operators who pass `--pair`.
+ * The package may not be installed in development checkouts that
+ * skipped optional deps; surface a graceful fallback.
+ */
+async function renderQr(url) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const qrcode = require('qrcode-terminal');
+        await new Promise((resolve) => {
+            qrcode.generate(url, { small: true }, (rendered) => {
+                out.log('');
+                out.log(rendered);
+                resolve();
+            });
+        });
+    }
+    catch {
+        out.warn('qrcode-terminal not available — copy the URL above into your phone instead.');
+    }
+}
+/**
+ * Open `url` in the operator's default browser via the platform's
+ * standard launcher. Best-effort — failures are logged but don't
+ * block the command's success path (the URL is already printed).
+ */
+function openInBrowser(url) {
+    const cmd = process.platform === 'darwin' ? 'open' :
+        process.platform === 'win32' ? 'cmd' :
+            'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    try {
+        const child = (0, child_process_1.spawn)(cmd, args, { detached: true, stdio: 'ignore' });
+        child.unref();
+    }
+    catch (err) {
+        out.warn(`could not launch browser (${err instanceof Error ? err.message : String(err)}); open the URL manually`);
+    }
+}
+function emitError(json, body) {
+    if (json) {
+        const payload = { ok: false, ...body };
+        out.log(JSON.stringify(payload));
+    }
+    else {
+        out.error(body.error);
+        if (body.hint)
+            out.log(`  ${out.dim(body.hint)}`);
+    }
+    process.exit(1);
+}

package/dist/cli/dev-banner.d.ts

@@ -0,0 +1,107 @@
+import { type ConfigSource } from '../config';
+/**
+ * Render `<homedir>/foo/bar` as `~/foo/bar` for human-readable banner
+ * output. Falls back to the absolute path when it doesn't live under the
+ * user's home dir (e.g. `AGENT_TEMPO_HOME_OVERRIDE=/tmp/scratch`).
+ *
+ * Exported for unit testing — banner output is checked against this
+ * formatter so the test fixtures don't bake in a developer's username.
+ */
+export declare function prettyPath(absPath: string, home?: string): string;
+/** Inputs to {@link formatDevBanner}. Exposed so tests can pin every value. */
+export interface DevBannerInputs {
+    /** Resolved home dir; defaults to `AGENT_TEMPO_HOME`. */
+    home?: string;
+    /** Daemon port; defaults to {@link DEV_DAEMON_PORT}. */
+    port?: number;
+    /** Temporal namespace; defaults to {@link DEV_TEMPORAL_NAMESPACE}. */
+    namespace?: string;
+    /** Source of the namespace value; annotates the banner when provided. */
+    namespaceSource?: ConfigSource;
+    /** Task queue; defaults to {@link DEV_TASK_QUEUE}. */
+    taskQueue?: string;
+    /**
+     * Source of the task queue value. Only `'env'` and `'default'` are
+     * possible today (queue resolution is hardcoded — env var wins, dev/prod
+     * default fills in), but the type widens to {@link ConfigSource} so a
+     * future PR-B carve-out has somewhere to land without a type change.
+     */
+    taskQueueSource?: ConfigSource;
+    /**
+     * Override `homedir()` resolution for path prettification. Tests pass an
+     * explicit value to keep fixtures stable across machines.
+     */
+    homedirOverride?: string;
+}
+/**
+ * Format the single-line `[DEV MODE]` banner. Pure function — no I/O.
+ *
+ *   [DEV MODE] using ~/.agent-tempo-dev · port 8474 · namespace agent-tempo-dev (default) · queue agent-tempo-dev (default)
+ *
+ * After a leak the banner self-narrates the drift:
+ *
+ *   [DEV MODE] using ~/.agent-tempo-dev · port 8474 · namespace default (env) · queue agent-tempo-dev (default)
+ *
+ * The `[DEV MODE]` prefix is rendered with ANSI yellow + bold when stdout
+ * is a TTY (`out.bold`/`out.yellow` handle the `NO_COLOR` / non-TTY
+ * fallback). The remainder is plain text so it greps cleanly out of
+ * `~/.agent-tempo-dev/daemon.log`.
+ *
+ * Production callers go through {@link emitDevBannerIfActive}, which
+ * resolves the inputs from {@link getConfigWithSources}. Tests pin every
+ * input to keep fixtures deterministic.
+ */
+export declare function formatDevBanner(inputs?: DevBannerInputs): string;
+/**
+ * Resolve the runtime inputs the banner should display. Reads from
+ * {@link getConfigWithSources} so the printed values match what the daemon
+ * actually connects to. On any resolution error (e.g. invalid ensemble
+ * name throwing out of `getConfig`'s validator), falls back to the dev
+ * profile's hardcoded constants — the banner is best-effort diagnostics
+ * and must not be load-bearing for daemon startup.
+ *
+ * Exported for unit testing without monkey-patching the config module.
+ *
+ * @internal
+ */
+export declare function resolveDevBannerInputs(): DevBannerInputs;
+/**
+ * Convenience: emit the banner to stderr if `isDevMode()` is true,
+ * otherwise no-op. Stderr (not stdout) so the banner doesn't pollute
+ * commands whose stdout is captured by callers (e.g. `agent-tempo
+ * --dev recall --json …`).
+ *
+ * Resolves the displayed values from {@link getConfigWithSources} so the
+ * banner reflects what the daemon ACTUALLY connects to. The previous
+ * implementation read the dev profile's hardcoded constants directly, so
+ * a `TEMPORAL_NAMESPACE=default` shell export silently disagreed with the
+ * banner (#423).
+ *
+ * Called from:
+ *   - `src/cli.ts` (every dev-mode CLI invocation)
+ *   - `src/cli/daemon-command.ts` (dev daemon start)
+ *   - `src/daemon.ts` (daemon child process startup)
+ */
+export declare function emitDevBannerIfActive(): void;
+/**
+ * Production banner counterpart used only by tests — verifies the negative
+ * case (env var unset → empty string). Production callers always go through
+ * `emitDevBannerIfActive()` which short-circuits when not in dev mode.
+ *
+ * Exported for `tests/cli/dev-banner.test.ts` so the test asserts both
+ * positive ("dev mode renders banner") AND negative ("not in dev mode
+ * renders nothing") branches without duplicating the env-var-toggling
+ * scaffolding.
+ */
+export declare function devBannerOrEmpty(): string;
+/**
+ * Single-line summary of the prod defaults — used by tests to confirm
+ * that the dev banner doesn't accidentally pick up production values.
+ *
+ * @internal
+ */
+export declare const PROD_DEFAULTS_FOR_TESTS: {
+    readonly port: 8473;
+    readonly namespace: "default";
+    readonly taskQueue: "agent-tempo";
+};

package/dist/cli/dev-banner.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROD_DEFAULTS_FOR_TESTS = void 0;
+exports.prettyPath = prettyPath;
+exports.formatDevBanner = formatDevBanner;
+exports.resolveDevBannerInputs = resolveDevBannerInputs;
+exports.emitDevBannerIfActive = emitDevBannerIfActive;
+exports.devBannerOrEmpty = devBannerOrEmpty;
+/**
+ * `[DEV MODE]` banner formatter (ADR 0014 §5.4 — gate 4 of production
+ * safety). Single conspicuous header line, printed on every CLI invocation
+ * in dev mode and on every dev daemon startup so logs self-identify.
+ *
+ * Crash-proof: imports only `os` and `../config`. No Temporal, no rxjs.
+ * Safe to call from `src/cli/daemon-command.ts` and `src/cli.ts` without
+ * breaking the #157 isolation guarantee.
+ *
+ * **Load-bearing invariant (#423 PR-A).** The banner output MUST reflect
+ * the daemon's actual resolved config — any divergence is a silent
+ * coordination bug. `formatDevBanner` stays pure (testable) over
+ * caller-injected inputs; `emitDevBannerIfActive` owns the resolution.
+ * Source annotations are uniform across all fields so a leak shows up as
+ * a single-character diff (`(default)` → `(env)`) rather than requiring
+ * the operator to know what "no annotation" means.
+ */
+const os_1 = require("os");
+const config_1 = require("../config");
+const output_1 = require("./output");
+/**
+ * Render `<homedir>/foo/bar` as `~/foo/bar` for human-readable banner
+ * output. Falls back to the absolute path when it doesn't live under the
+ * user's home dir (e.g. `AGENT_TEMPO_HOME_OVERRIDE=/tmp/scratch`).
+ *
+ * Exported for unit testing — banner output is checked against this
+ * formatter so the test fixtures don't bake in a developer's username.
+ */
+function prettyPath(absPath, home = (0, os_1.homedir)()) {
+    if (!home)
+        return absPath;
+    if (absPath === home)
+        return '~';
+    // Always check both `/` and `\` separators regardless of the host OS.
+    // The function is sometimes called on POSIX with Windows-shaped path
+    // strings (e.g. unit tests that fix a fixture homedir of `C:\Users\alice`,
+    // or env-var values that escaped from a Windows shell). Using the
+    // platform's `path.sep` alone would leave half of those cases broken.
+    const trailers = ['/', '\\'];
+    for (const trailer of trailers) {
+        const prefix = home + trailer;
+        if (absPath.startsWith(prefix)) {
+            return '~/' + absPath.slice(prefix.length).replace(/\\/g, '/');
+        }
+    }
+    return absPath;
+}
+/**
+ * Annotate a banner field with its source. Always emits the `(source)`
+ * suffix when a source is provided so the banner is uniformly diagnostic
+ * — every field tells the operator where its value came from. `'none'`
+ * suppresses the annotation (the value couldn't be resolved at all, so
+ * a source label would be misleading).
+ *
+ * The architect's `docs/design/dev-mode-isolation-fix-423.md` example:
+ *
+ *   `namespace agent-tempo-dev (default) · queue agent-tempo-dev (default)`
+ *
+ * After a leak this becomes `namespace default (env)` — operator instantly
+ * sees what changed. If we suppressed `(default)` they'd have to know
+ * what "no annotation" means before they could spot the drift.
+ */
+function annotateField(name, value, source) {
+    if (!source || source === 'none')
+        return `${name} ${value}`;
+    return `${name} ${value} (${source})`;
+}
+/**
+ * Format the single-line `[DEV MODE]` banner. Pure function — no I/O.
+ *
+ *   [DEV MODE] using ~/.agent-tempo-dev · port 8474 · namespace agent-tempo-dev (default) · queue agent-tempo-dev (default)
+ *
+ * After a leak the banner self-narrates the drift:
+ *
+ *   [DEV MODE] using ~/.agent-tempo-dev · port 8474 · namespace default (env) · queue agent-tempo-dev (default)
+ *
+ * The `[DEV MODE]` prefix is rendered with ANSI yellow + bold when stdout
+ * is a TTY (`out.bold`/`out.yellow` handle the `NO_COLOR` / non-TTY
+ * fallback). The remainder is plain text so it greps cleanly out of
+ * `~/.agent-tempo-dev/daemon.log`.
+ *
+ * Production callers go through {@link emitDevBannerIfActive}, which
+ * resolves the inputs from {@link getConfigWithSources}. Tests pin every
+ * input to keep fixtures deterministic.
+ */
+function formatDevBanner(inputs = {}) {
+    const home = inputs.home ?? config_1.AGENT_TEMPO_HOME;
+    const port = inputs.port ?? config_1.DEV_DAEMON_PORT;
+    const namespace = inputs.namespace ?? config_1.DEV_TEMPORAL_NAMESPACE;
+    const taskQueue = inputs.taskQueue ?? config_1.DEV_TASK_QUEUE;
+    const display = prettyPath(home, inputs.homedirOverride);
+    const namespaceField = annotateField('namespace', namespace, inputs.namespaceSource);
+    const queueField = annotateField('queue', taskQueue, inputs.taskQueueSource);
+    return (`${(0, output_1.bold)((0, output_1.yellow)('[DEV MODE]'))} using ${display} · ` +
+        `port ${port} · ${namespaceField} · ${queueField}`);
+}
+/**
+ * Resolve the runtime inputs the banner should display. Reads from
+ * {@link getConfigWithSources} so the printed values match what the daemon
+ * actually connects to. On any resolution error (e.g. invalid ensemble
+ * name throwing out of `getConfig`'s validator), falls back to the dev
+ * profile's hardcoded constants — the banner is best-effort diagnostics
+ * and must not be load-bearing for daemon startup.
+ *
+ * Exported for unit testing without monkey-patching the config module.
+ *
+ * @internal
+ */
+function resolveDevBannerInputs() {
+    // `taskQueue` source isn't tracked by `getConfigWithSources` (queue
+    // resolution lives directly in `getConfig`'s constructor). Compute it
+    // here so the banner annotates it uniformly with the namespace source.
+    const taskQueueSource = process.env[config_1.ENV.TASK_QUEUE] ? 'env' : 'default';
+    try {
+        const { config, sources } = (0, config_1.getConfigWithSources)();
+        return {
+            namespace: config.temporalNamespace,
+            namespaceSource: sources.temporalNamespace,
+            taskQueue: config.taskQueue,
+            taskQueueSource,
+        };
+    }
+    catch (err) {
+        // `getConfigWithSources` validates the ensemble name and may throw
+        // when an operator has e.g. invalid characters in `$AGENT_TEMPO_ENSEMBLE`.
+        // Surface the cause to stderr — the banner stays diagnostic and the
+        // operator sees that the displayed values are dev defaults, not the
+        // actual resolution. The CLI surfaces the same validation error a
+        // moment later, so the duplicate isn't noisy enough to suppress.
+        console.error('[dev-mode] banner falling back to defaults — config resolution failed:', err instanceof Error ? err.message : String(err));
+        return { taskQueueSource };
+    }
+}
+/**
+ * Convenience: emit the banner to stderr if `isDevMode()` is true,
+ * otherwise no-op. Stderr (not stdout) so the banner doesn't pollute
+ * commands whose stdout is captured by callers (e.g. `agent-tempo
+ * --dev recall --json …`).
+ *
+ * Resolves the displayed values from {@link getConfigWithSources} so the
+ * banner reflects what the daemon ACTUALLY connects to. The previous
+ * implementation read the dev profile's hardcoded constants directly, so
+ * a `TEMPORAL_NAMESPACE=default` shell export silently disagreed with the
+ * banner (#423).
+ *
+ * Called from:
+ *   - `src/cli.ts` (every dev-mode CLI invocation)
+ *   - `src/cli/daemon-command.ts` (dev daemon start)
+ *   - `src/daemon.ts` (daemon child process startup)
+ */
+function emitDevBannerIfActive() {
+    if (!(0, config_1.isDevMode)())
+        return;
+    // stderr keeps stdout clean for `--json` / pipe consumers. Same reasoning
+    // as `out.error` / `out.warn`. Ship it via console.error directly so we
+    // don't depend on `out.log` (which writes to stdout).
+    console.error(formatDevBanner(resolveDevBannerInputs()));
+}
+/**
+ * Production banner counterpart used only by tests — verifies the negative
+ * case (env var unset → empty string). Production callers always go through
+ * `emitDevBannerIfActive()` which short-circuits when not in dev mode.
+ *
+ * Exported for `tests/cli/dev-banner.test.ts` so the test asserts both
+ * positive ("dev mode renders banner") AND negative ("not in dev mode
+ * renders nothing") branches without duplicating the env-var-toggling
+ * scaffolding.
+ */
+function devBannerOrEmpty() {
+    return (0, config_1.isDevMode)() ? formatDevBanner(resolveDevBannerInputs()) : '';
+}
+/**
+ * Single-line summary of the prod defaults — used by tests to confirm
+ * that the dev banner doesn't accidentally pick up production values.
+ *
+ * @internal
+ */
+exports.PROD_DEFAULTS_FOR_TESTS = {
+    port: config_1.PROD_DAEMON_PORT,
+    namespace: config_1.PROD_TEMPORAL_NAMESPACE,
+    taskQueue: config_1.PROD_TASK_QUEUE,
+};

package/dist/cli/dev-mode-bootstrap.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pre-import side-effect that promotes a top-level `--dev` CLI flag into
+ * `AGENT_TEMPO_DEV_MODE=1` BEFORE any other module loads (ADR 0014 §5.4).
+ *
+ * **Why this file exists**: `src/cli.ts` imports `./config` statically, and
+ * `src/config.ts` evaluates `AGENT_TEMPO_HOME = resolveTempoHome()` at
+ * module load time. By the time the main argv parser runs, that constant
+ * has already been frozen against `~/.agent-tempo/`. The bootstrap mutates
+ * `process.env` early — before the static `./config` import resolves — so
+ * the dev profile lights up everywhere downstream consistently.
+ *
+ * Imported as the very first statement of `src/cli.ts`. Has zero imports
+ * (not even `./config`) so it can run before any other module loads. This
+ * file MUST stay dependency-free; if you find yourself wanting to import
+ * something here, put it in `src/cli/dev-banner.ts` instead.
+ *
+ * Side effects:
+ *   1. If `--dev` appears anywhere in `process.argv`, set
+ *      `process.env.AGENT_TEMPO_DEV_MODE='1'`.
+ *   2. Strip `--dev` from `process.argv` so the main parser doesn't reject
+ *      it as unknown.
+ *
+ * Daemon child processes inherit `AGENT_TEMPO_DEV_MODE` automatically via
+ * `spawn(..., { env: { ...process.env } })` in `src/cli/daemon.ts`. Users
+ * can also bypass the flag entirely by setting `AGENT_TEMPO_DEV_MODE=1`
+ * directly in their shell — useful for MCP server processes that aren't
+ * launched via the CLI.
+ */
+export {};

package/dist/cli/dev-mode-bootstrap.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Pre-import side-effect that promotes a top-level `--dev` CLI flag into
+ * `AGENT_TEMPO_DEV_MODE=1` BEFORE any other module loads (ADR 0014 §5.4).
+ *
+ * **Why this file exists**: `src/cli.ts` imports `./config` statically, and
+ * `src/config.ts` evaluates `AGENT_TEMPO_HOME = resolveTempoHome()` at
+ * module load time. By the time the main argv parser runs, that constant
+ * has already been frozen against `~/.agent-tempo/`. The bootstrap mutates
+ * `process.env` early — before the static `./config` import resolves — so
+ * the dev profile lights up everywhere downstream consistently.
+ *
+ * Imported as the very first statement of `src/cli.ts`. Has zero imports
+ * (not even `./config`) so it can run before any other module loads. This
+ * file MUST stay dependency-free; if you find yourself wanting to import
+ * something here, put it in `src/cli/dev-banner.ts` instead.
+ *
+ * Side effects:
+ *   1. If `--dev` appears anywhere in `process.argv`, set
+ *      `process.env.AGENT_TEMPO_DEV_MODE='1'`.
+ *   2. Strip `--dev` from `process.argv` so the main parser doesn't reject
+ *      it as unknown.
+ *
+ * Daemon child processes inherit `AGENT_TEMPO_DEV_MODE` automatically via
+ * `spawn(..., { env: { ...process.env } })` in `src/cli/daemon.ts`. Users
+ * can also bypass the flag entirely by setting `AGENT_TEMPO_DEV_MODE=1`
+ * directly in their shell — useful for MCP server processes that aren't
+ * launched via the CLI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const DEV_FLAG = '--dev';
+const idx = process.argv.indexOf(DEV_FLAG);
+if (idx !== -1) {
+    process.env.AGENT_TEMPO_DEV_MODE = '1';
+    process.argv.splice(idx, 1);
+}

package/dist/cli/dev-verbs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Dev-mode scriptable CLI verbs (#432).
+ *
+ * Five thin shell-scriptable wrappers over the MCP tool surface, available
+ * only when `--dev` / `AGENT_TEMPO_DEV_MODE=1` is active. Production CLI
+ * was collapsed to TUI/MCP-only in #288; this module restores
+ * shell-scriptable access for autonomous E2E validation harnesses without
+ * re-introducing the public surface that #288 retired.
+ *
+ * ## Allowlist discipline
+ *
+ * `DEV_VERBS` is an explicit `ReadonlySet<string>`, NOT derived from
+ * `REMOVED_VERBS` keys. Promoting a removed verb to a dev-mode verb must
+ * be a deliberate, code-reviewed action. The mechanical-enforcement test
+ * in `test/cli-dev-verbs.test.ts` asserts the DEV_VERBS ↔ REMOVED_VERBS
+ * ↔ `cli.ts` switch invariants.
+ *
+ * ## NOT crash-proof
+ *
+ * This module touches Temporal directly. It is deliberately excluded from
+ * `test/cli-crash-proof-isolation.test.ts`'s `CRASH_PROOF_MODULES` allowlist
+ * — dev mode requires Temporal anyway.
+ */
+import { CliOverrides } from '../config';
+/** Allowlist of verbs accepted in dev mode. Single source of truth. */
+export declare const DEV_VERBS: ReadonlySet<string>;
+/**
+ * Subset of {@link import('../cli').ParsedArgs} consumed by the dispatcher.
+ * Kept narrow so this module doesn't import `../cli` (would be cyclic).
+ */
+export interface DevVerbArgs extends CliOverrides {
+    /** All non-flag tokens, including `args.positional[0] === args.command`. */
+    positional: string[];
+    /** Resolved ensemble (positional override / env fallback). */
+    ensemble: string;
+}
+/**
+ * Dispatch a dev-mode verb. Caller (`cli.ts`) gates on `isDevMode()` +
+ * `DEV_VERBS.has(verb)` before calling. Throws `Error` for unknown verbs
+ * — the mechanical test in `cli-dev-verbs.test.ts` asserts that this
+ * is unreachable in practice.
+ */
+export declare function dispatchDevVerb(verb: string, args: DevVerbArgs): Promise<void>;