@alexkroman1/aai-cli 5.14.0 → 6.1.0

package/dist/{_dev-server-Ch7K8e8i.mjs → _dev-server-DQ1t9sbw.mjs}

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
-import { i as outputSilenced, n as log, r as notify } from "./_ui-u7T4YooX.mjs";
-import { a as errorMessage, r as errorCode } from "./_utils-0DHbcqUb.mjs";
-import { n as fallbackHtmlPlugin } from "./client-bundler-C9qXL8A2.mjs";
-import { buildWorker } from "./worker-bundler.mjs";
-import { n as ensureApiKey } from "./_config-CzwAWOWr.mjs";
-import { n as createWorkerEvaluator } from "./_bundler-BuIyDdvs.mjs";
-import { t as resolveServerEnv } from "./_server-common-61fL__39.mjs";
+import { i as outputSilenced, r as notify } from "./_ui-u7T4YooX.mjs";
+import { i as errorCode, o as errorMessage$1 } from "./_utils-B8QmtFhK.mjs";
+import { n as fallbackHtmlPlugin } from "./client-bundler-B8Q9F8gJ.mjs";
+import { t as DEDUPED_PEERS } from "./_vite-env-BNveawd1.mjs";
+import { n as buildWorkflows, t as buildWorker } from "./worker-bundler-CIdDhZ0c.mjs";
+import { n as ensureApiKey } from "./_config-D_s09e7g.mjs";
+import { n as createWorkerEvaluator } from "./_bundler-BapCUUJN.mjs";
+import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { setTimeout } from "node:timers/promises";
-import { consoleLogger, createRuntime, createServer, requiredProviderEnvVars, withHostCredentialFallback } from "@alexkroman1/aai/runtime";
+import { omitUndefined } from "@alexkroman1/aai/utils";
+import { createCoalescingRunner, sleep } from "@alexkroman1/aai/internal";
+import { WORKFLOW_API_PREFIX, configureWorkflowWorld, consoleLogger, createRuntime, createServer, createWorkflowSurface, handleWorkflowRequest, publishStepEnv, requiredProviderEnvVars, startWorkflowWorldIfDeclared, withHostCredentialFallback } from "@alexkroman1/aai/runtime";
 import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
 import { watch } from "chokidar";
 import getPort, { portNumbers } from "get-port";
@@ -94,36 +96,41 @@ const LISTEN_RETRY_DELAY_MS = 250;
 * the built server (or {@link RestartSupervisor.close} on startup failure).
 */
 function createRestartSupervisor(ops) {
-	const wait = ops.sleep ?? setTimeout;
-	let restarting = true;
-	let pendingRestart = false;
+	const wait = ops.sleep ?? sleep;
+	let booting = true;
+	let queuedDuringBoot = false;
 	let closed = false;
 	let current;
 	let cleanupPromise;
+	/**
+	* At most one rebuild in flight; every change landing during one collapses
+	* into a SINGLE trailing rebuild started after it settles.
+	*
+	* That is exactly the repo's `createCoalescingRunner` contract, and this
+	* module used to re-derive it with a `restarting` flag, a `pendingRestart`
+	* flag and a `do/while` loop. Coalescing is the right policy for the same
+	* reason it is there: a rebuild reads the files as they are WHEN IT RUNS, so
+	* N queued rebuilds would do the trailing one's work N times, while dropping
+	* the trigger outright would leave the newest save unserved (or, when the
+	* in-flight rebuild died on a mid-edit syntax error, leave the server down).
+	*/
+	const rebuilds = createCoalescingRunner(() => restartOnce());
 	function request() {
-		if (restarting) {
-			pendingRestart = true;
+		if (booting) {
+			queuedDuringBoot = true;
 			return;
 		}
-		restarting = true;
-		restart().catch((err) => {
-			ops.notify("error", `Restart failed: ${errorMessage(err)}`);
-		}).finally(() => {
-			restarting = false;
+		rebuilds.trigger().catch((err) => {
+			ops.notify("error", `Restart failed: ${errorMessage$1(err)}`);
 		});
 	}
-	async function restart() {
-		do {
-			pendingRestart = false;
-			await restartOnce();
-		} while (pendingRestart && !closed);
-	}
 	async function restartOnce() {
+		if (closed) return;
 		let newServer;
 		try {
 			newServer = await ops.build();
 		} catch (err) {
-			ops.notify("error", `Restart failed: ${errorMessage(err)} (previous server still running)`);
+			ops.notify("error", `Restart failed: ${errorMessage$1(err)} (previous server still running)`);
 			return;
 		}
 		if (closed) {
@@ -138,7 +145,7 @@ function createRestartSupervisor(ops) {
 		try {
 			await listenWithRetry(newServer);
 		} catch (err) {
-			ops.notify("error", `Restart failed: ${errorMessage(err)} — dev server is down; save a file to retry.`);
+			ops.notify("error", `Restart failed: ${errorMessage$1(err)} — dev server is down; save a file to retry.`);
 			await closeQuietly(newServer);
 			return;
 		}
@@ -174,8 +181,8 @@ function createRestartSupervisor(ops) {
 		request,
 		adopt(server) {
 			current = server;
-			restarting = false;
-			if (pendingRestart) request();
+			booting = false;
+			if (queuedDuringBoot) request();
 		},
 		current: () => current,
 		close() {
@@ -229,7 +236,7 @@ async function resolveAgentEnv(root, agentDef) {
 	const required = requiredProviderEnvVars(agentDef);
 	const hasShellKey = Boolean(process.env.ASSEMBLYAI_API_KEY);
 	if (required.includes("ASSEMBLYAI_API_KEY") && !env.ASSEMBLYAI_API_KEY && !hasShellKey) env.ASSEMBLYAI_API_KEY = await ensureApiKey();
-	for (const warning of agentEnvWarnings(agentDef, env)) log.warn(warning);
+	for (const warning of agentEnvWarnings(agentDef, env)) notify("warn", warning);
 	return env;
 }
 /**
@@ -244,9 +251,19 @@ async function resolveAgentEnv(root, agentDef) {
 * errors in the agent's code propagate — the restart loop reports them and
 * keeps the old server. Evaluation goes through the memoizing evaluator so
 * a no-op save doesn't leak another module into the ESM registry.
+*
+* The project's `workflows/` directory is compiled by the same pass deploy
+* runs (`buildWorkflows`) and rides the bundle as two string exports, which is
+* how `aai dev` serves a workflow at all: nothing here hands the bundle to a
+* guest, so the CLI is both ends of that contract locally. A project with no
+* `workflows/` directory pays nothing — `buildWorkflows` resolves `undefined`
+* without starting a builder.
 */
-async function loadAgentDef(cwd, evaluate) {
-	return evaluate(await buildWorker(cwd, { runtime: false }));
+async function loadWorker(cwd, evaluate) {
+	return evaluate(await buildWorker(cwd, {
+		runtime: false,
+		workflows: await buildWorkflows(cwd)
+	}));
 }
 /**
 * True for paths that should never trigger a restart: anything inside
@@ -310,11 +327,11 @@ function watchDirectory(dir, onChange) {
 	});
 	watcher.on("error", (err) => {
 		const hint = errorCode(err) === "ENOSPC" ? " The inotify watch limit was reached — raise the fs.inotify max_user_watches sysctl." : "";
-		notify("error", `File watcher error: ${errorMessage(err)}.${hint} Auto-restart on file changes may have stopped; restart \`aai dev\` after fixing.`);
+		notify("error", `File watcher error: ${errorMessage$1(err)}.${hint} Auto-restart on file changes may have stopped; restart \`aai dev\` after fixing.`);
 	});
 	watcher.on("all", () => {
 		debouncedChange().catch((err) => {
-			notify("error", `Watch handler failed: ${errorMessage(err)}`);
+			notify("error", `Watch handler failed: ${errorMessage$1(err)}`);
 		});
 	});
 	return watcher;
@@ -324,25 +341,48 @@ function watchDirectory(dir, onChange) {
 * is unit-testable: `/websocket` MUST proxy with `ws: true` or `aai dev`
 * with a `client.tsx` serves a page whose WebSocket never connects.
 *
+* **This table is the whole agent API as the browser can see it**, which is
+* the thing to hold in mind before adding a route to `createServer`. Vite owns
+* the port the user is told to open and answers everything not listed here
+* itself — with a bare 404 carrying none of the agent server's headers, so the
+* failure looks like a missing route rather than a missing proxy entry.
+*
+* `/workflows` is why that matters beyond voice. A WORKFLOW APP
+* (`workflowApp()`) has no session and no socket: `page()` mounts a
+* form and every single thing it does — listing workflows, starting a run,
+* polling it, streaming its events — is a same-origin `fetch` under that
+* prefix. Unproxied, the two workflow-app templates were dead on arrival under
+* `aai dev` (`404 POST /workflows/runs` the instant the form is submitted)
+* while the backend served the API correctly one port over. A string key
+* prefix-matches, so this one entry covers `/runs`, `/runs/:id` and the
+* `/runs/:id/events` SSE stream.
+*
 * `strictPort` because the reported URL is `http://localhost:<port>` —
 * without it, Vite silently binds port+N when the port is busy and the
 * printed/JSON-returned URL points at whatever else was listening.
+*
+* `AAI_DEV_HOST` reaches BOTH servers. Binding only the backend left Vite —
+* the port the user is told to open — on loopback, i.e. failing exactly the
+* case that variable exists for (`aai dev` in a container, reached from the host).
 */
 function viteDevConfig(cwd, vitePort, backendPort) {
 	const target = `http://localhost:${backendPort}`;
 	return {
 		root: cwd,
 		plugins: [fallbackHtmlPlugin(cwd)],
+		resolve: { dedupe: DEDUPED_PEERS },
 		server: {
 			port: vitePort,
 			strictPort: true,
+			...omitUndefined({ host: devBindHost() }),
 			proxy: {
 				"/health": target,
 				"/client-config": target,
 				"/websocket": {
 					target,
 					ws: true
-				}
+				},
+				[WORKFLOW_API_PREFIX]: target
 			}
 		}
 	};
@@ -360,22 +400,38 @@ async function startDevServer(opts) {
 	const clientDirOpt = hasClient ? {} : { clientDir: defaultClientDir() };
 	const evaluateWorker = createWorkerEvaluator();
 	const devLogger = createDevLogger(outputSilenced());
+	let workflowWorldStarted = false;
 	/** Full build sequence, shared by initial startup and every restart. */
 	async function buildServer() {
-		const agentDef = await loadAgentDef(cwd, evaluateWorker);
+		const worker = await loadWorker(cwd, evaluateWorker);
+		const agentDef = worker.agent;
 		const env = await resolveAgentEnv(cwd, agentDef);
+		const world = configureWorkflowWorld({
+			databaseUrl: env.DATABASE_URL,
+			port: backendPort,
+			dataDir: path.join(cwd, ".workflow-data")
+		});
+		publishStepEnv(env);
+		const workflows = await createWorkflowSurface(worker.workflowCode, worker.stepCode);
+		if (workflows && !workflowWorldStarted) {
+			workflowWorldStarted = true;
+			await startWorkflowWorldIfDeclared(true, world);
+		}
 		const providerEnv = withHostCredentialFallback(env);
 		return createServer({
 			runtime: createRuntime({
 				agent: agentDef,
 				env,
 				providerEnv,
-				logger: devLogger
+				logger: devLogger,
+				publicUrl: process.env.PUBLIC_URL?.trim() || `http://localhost:${backendPort}`
 			}),
 			name: agentDef.name,
 			env: hostModeEnv(providerEnv),
 			hostBaseAgent: agentDef,
 			greeting: agentDef.greeting,
+			...omitUndefined({ page: agentDef.page }),
+			request: (req, res, url, method) => handleWorkflowRequest(workflows, req, res, url, method),
 			...clientDirOpt
 		});
 	}
@@ -402,7 +458,7 @@ async function startDevServer(opts) {
 			viteServer = await createViteServer(viteDevConfig(cwd, vitePort, backendPort));
 			await viteServer.listen();
 			viteServer.httpServer?.on("error", (err) => {
-				notify("error", `Vite dev server error: ${errorMessage(err)}`);
+				notify("error", `Vite dev server error: ${errorMessage$1(err)}`);
 			});
 		}
 		supervisor.adopt(initialServer);

package/dist/_dev-server.d.ts

@@ -9,6 +9,7 @@
 import type { AgentDef } from "@alexkroman1/aai";
 import { type Logger } from "@alexkroman1/aai/runtime";
 import { type FSWatcher } from "chokidar";
+import { type EvaluatedWorker } from "./_bundler.ts";
 /**
  * Warnings about the agent's credentials, computed against the `.env`-derived
  * env and the shell. Pure so it is directly testable; `resolveAgentEnv` logs
@@ -22,7 +23,7 @@ import { type FSWatcher } from "chokidar";
  *   it at all: custom keys never fall back to the shell, so a shell export
  *   can't mask one that would be missing both here and after deploy.
  */
-export declare function agentEnvWarnings(agentDef: Pick<AgentDef, "stt" | "llm" | "tts" | "s2s" | "requiredEnv">, env: Record<string, string>, shellEnv?: Record<string, string | undefined>): string[];
+export declare function agentEnvWarnings(agentDef: Pick<AgentDef, "stt" | "llm" | "tts" | "s2s" | "requiredEnv" | "page">, env: Record<string, string>, shellEnv?: Record<string, string | undefined>): string[];
 /**
  * Load the agent definition by bundling agent.ts (and all its local imports)
  * into a single ESM file, then importing that. A raw `import(agent.ts?t=...)`
@@ -35,8 +36,15 @@ export declare function agentEnvWarnings(agentDef: Pick<AgentDef, "stt" | "llm"
  * errors in the agent's code propagate — the restart loop reports them and
  * keeps the old server. Evaluation goes through the memoizing evaluator so
  * a no-op save doesn't leak another module into the ESM registry.
+ *
+ * The project's `workflows/` directory is compiled by the same pass deploy
+ * runs (`buildWorkflows`) and rides the bundle as two string exports, which is
+ * how `aai dev` serves a workflow at all: nothing here hands the bundle to a
+ * guest, so the CLI is both ends of that contract locally. A project with no
+ * `workflows/` directory pays nothing — `buildWorkflows` resolves `undefined`
+ * without starting a builder.
  */
-export declare function loadAgentDef(cwd: string, evaluate: (code: string) => Promise<AgentDef>): Promise<AgentDef>;
+export declare function loadWorker(cwd: string, evaluate: (code: string) => Promise<EvaluatedWorker>): Promise<EvaluatedWorker>;
 /**
  * True for paths that should never trigger a restart: anything inside
  * `node_modules/` and any dot-entry (`.git/`, `.aai/`, `.DS_Store`, …).
@@ -78,9 +86,29 @@ export type DevServerOptions = {
  * is unit-testable: `/websocket` MUST proxy with `ws: true` or `aai dev`
  * with a `client.tsx` serves a page whose WebSocket never connects.
  *
+ * **This table is the whole agent API as the browser can see it**, which is
+ * the thing to hold in mind before adding a route to `createServer`. Vite owns
+ * the port the user is told to open and answers everything not listed here
+ * itself — with a bare 404 carrying none of the agent server's headers, so the
+ * failure looks like a missing route rather than a missing proxy entry.
+ *
+ * `/workflows` is why that matters beyond voice. A WORKFLOW APP
+ * (`workflowApp()`) has no session and no socket: `page()` mounts a
+ * form and every single thing it does — listing workflows, starting a run,
+ * polling it, streaming its events — is a same-origin `fetch` under that
+ * prefix. Unproxied, the two workflow-app templates were dead on arrival under
+ * `aai dev` (`404 POST /workflows/runs` the instant the form is submitted)
+ * while the backend served the API correctly one port over. A string key
+ * prefix-matches, so this one entry covers `/runs`, `/runs/:id` and the
+ * `/runs/:id/events` SSE stream.
+ *
  * `strictPort` because the reported URL is `http://localhost:<port>` —
  * without it, Vite silently binds port+N when the port is busy and the
  * printed/JSON-returned URL points at whatever else was listening.
+ *
+ * `AAI_DEV_HOST` reaches BOTH servers. Binding only the backend left Vite —
+ * the port the user is told to open — on loopback, i.e. failing exactly the
+ * case that variable exists for (`aai dev` in a container, reached from the host).
  */
 export declare function viteDevConfig(cwd: string, vitePort: number, backendPort: number): import("vite").InlineConfig;
 /**

package/dist/_e2e-test-utils.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared helpers for the e2e test suites (e2e*.test.ts): CLI build, mock
+ * registry setup, dependency installation, and process/server utilities.
+ * Each e2e suite performs its own setup/teardown using these helpers.
+ */
+import type { ChildProcess } from "node:child_process";
+import type { MockRegistry } from "./_mock-registry.ts";
+export declare const dir: string;
+export declare const packagesDir: string;
+export declare const pm: "pnpm" | "npm" | "yarn";
+export declare function aaiEnv(): NodeJS.ProcessEnv;
+export declare function aai(aaiBin: string, args: string[], cwd: string, timeoutMs?: number): void;
+/**
+ * Build the CLI and return the path to the built binary.
+ *
+ * Runs the package's own `build` script rather than bare `tsdown`, because
+ * the build is two steps now: tsdown, then `bundle-templates.mjs` copying the
+ * templates into `dist/`. Calling the bundler directly produced a `dist/`
+ * that no published tarball ever looks like — one with no templates in it.
+ */
+export declare function buildCli(): string;
+/**
+ * Copy a built `dist/` somewhere with no pnpm-workspace.yaml above it, so the
+ * CLI resolves templates the way an npm-installed copy does.
+ *
+ * `getMonorepoRoot()` keys off the *module's* location, so a build run from
+ * `packages/aai-cli/dist` always finds the workspace root and takes the
+ * monorepo branch — no test running in-tree can reach the bundled branch,
+ * which is the only one real users hit.
+ */
+export declare function detachedCli(aaiBin: string, into: string): string;
+/**
+ * Start a mock npm registry and publish workspace packages to it.
+ * Packages are built + published inside startMockRegistry, so consumers
+ * (npm/pnpm/yarn install) resolve them exactly as they would from the real registry.
+ */
+export declare function startRegistry(): Promise<MockRegistry>;
+/** Poll a health endpoint, capturing child stderr for diagnostics on timeout. */
+export declare function waitForHealth(url: string, child?: ChildProcess, timeoutMs?: number): Promise<void>;
+/** Wait for a child process to exit (for clean teardown). */
+export declare function waitForExit(child: ChildProcess, timeoutMs?: number): Promise<void>;
+/**
+ * Install dependencies using the mock registry.
+ *
+ * **`ignore-scripts` is set HERE and nowhere else, and that placement is
+ * load-bearing.** It exists to stop a linked package's `postinstall` running
+ * during THIS install — but `npm_config_ignore_scripts` is read by every npm
+ * invocation, so while it sat in `aaiEnv()` it silently suppressed every
+ * lifecycle script in every spawned command. That took out `npm start`'s
+ * `prestart`, i.e. the build the self-hosted entrypoint cannot boot without: the
+ * child printed `> start` with no `> prestart` above it and died on the missing
+ * artifact, naming a project file rather than the env var that skipped the step.
+ *
+ * The trap generalizes past this repo — an install-time protection that is
+ * really a global one — and the second half is worse than the failure: had the
+ * artifact happened to exist from an earlier build, the test would have PASSED
+ * while never running the script it exists to exercise.
+ */
+/**
+ * Whether a failed install may be excused as the mock registry's npmjs
+ * passthrough failing rather than as a real dependency-resolution break.
+ *
+ * **`AAI_REQUIRE_REGISTRY` turns every excuse off**, and CI sets it — the same
+ * shape as `AAI_REQUIRE_PG`, for the same reason. A skip predicate over ERROR TEXT
+ * is a guess, and this tier is where a broken `exports` map surfaces: with three
+ * of four tests able to self-skip, a genuine break whose message happens to
+ * contain a matched substring would report green in the one job that could have
+ * caught it. Locally the excuse stays, because a developer behind a proxy has no
+ * way to make the passthrough work and a hard failure there is just noise.
+ *
+ * The predicate itself is narrowed to TRANSPORT-level failures. `fetch failed`
+ * and `network` are gone: both are substrings a real 404 can carry, which made
+ * them the two patterns most likely to excuse the thing this suite exists to
+ * find. verdaccio maps a failed upstream fetch to a plain 404, so
+ * `ERR_PNPM_FETCH_*` on a THIRD-PARTY package still counts — but never one naming
+ * our own scope, since those live in verdaccio's local storage and failing to
+ * resolve one means the published packages are actually broken.
+ */
+export declare function isRegistryProxyFailure(err: unknown): boolean;
+export declare function installDeps(registry: MockRegistry, projectDir: string): void;

package/dist/_fault-mode.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Fault mode: run a test's dev server as a child that gets HARD-KILLED and
+ * restarted at declared points, so a suite can be run against a process that
+ * keeps dying under it.
+ *
+ * `AAI_FAULT_PROFILE=<name>` turns it on for every test that boots its server
+ * through {@link startSupervisedDevServer}; unset, the helper is an ordinary
+ * spawn and nothing about a suite changes. That is the whole shape of the
+ * feature: one env var covers the suite, and the off path has no supervisor in
+ * it at all.
+ *
+ * ## Why the kill is a SIGKILL, and why that is the only faithful option
+ *
+ * A graceful stop lets graphile-worker's runner release the queue locks it
+ * holds. That is exactly the difference that decides whether an in-flight step
+ * is redelivered, so a fault mode built on SIGTERM would exercise the recovery
+ * path that already works and never the one that does not. Measured: one hard
+ * kill of the process (or of its Postgres) strands every locked step until
+ * graphile-worker's own `interval '4 hours'` reclaim, with the run sitting
+ * `running` and a page showing "Working…" forever.
+ *
+ * ## Why there is no seed and no PRNG
+ *
+ * "Consistent fault mode" is the requirement, and the cheapest way to be
+ * consistent is to have nothing to reproduce: a profile is an ORDERED LIST of
+ * fault points keyed on logical events, so the Nth kill lands after the same
+ * observed event on every machine at every speed. Wall-clock kills are what
+ * `tmp/transcribe-load/chaos.mjs` does, and they are why its runs cannot be
+ * compared to each other.
+ *
+ * Randomized exploration is a different job with a different tool: this repo
+ * drives every randomized suite with fast-check (see "Property tests run on
+ * fast-check" in the root guide) precisely so nobody hand-rolls a seventh PRNG.
+ * A fault mode that grew a seed would be that seventh. If the fault SCHEDULE
+ * should be explored rather than declared, that belongs in a fast-check
+ * property over this module's plan type, not in an env var here.
+ *
+ * ## Triggers are log lines, and the plan is CHECKED
+ *
+ * A fault point names a pattern the server writes and which occurrence to fire
+ * on. Keying on log output couples this to strings the server happens to print,
+ * which is a real cost and is accepted for one reason: the alternative is a
+ * fault hook in production code, and a test-only mechanism should not be able to
+ * fire in production at all.
+ *
+ * The cost is paid down by {@link SupervisedServer.assertPlanConsumed}, which
+ * THROWS when a declared fault point never fired. Without it a renamed log line
+ * turns the entire mode into a no-op and the suite passes "under faults" having
+ * injected none — the failure this repo keeps paying for (a gate that reports
+ * success while checking nothing). Call it before asserting anything else.
+ */
+/**
+ * One kill, described by what the server DID rather than by when — the two
+ * kinds being a line it printed and a boot it completed.
+ *
+ * `downMs` holds the process down before the restart on either. The default is
+ * 0, i.e. restart immediately, because the fault under test is the DEATH rather
+ * than the downtime.
+ *
+ * Both kinds exist because a log trigger cannot reach the boot. `aai dev`
+ * announces itself through `log.success`, which JSON mode SILENCES — and JSON
+ * mode is what the e2e suite runs (and what a pipe auto-selects), so a
+ * boot-level profile keyed on a startup line matched nothing and the mode
+ * injected no faults at all. Workflow lines are unaffected: the agent server's
+ * logger writes straight to stderr rather than through `log`, so
+ * `"Workflow run started"` survives JSON mode. `afterHealthy` needs no log at
+ * all, which makes it the right kind for anything about the process lifecycle.
+ */
+export type FaultPoint = {
+    /** A substring of the log line to fire after. */
+    after: string;
+    /** Which occurrence of `after` to fire on. 1-based; defaults to the first. */
+    nth?: number;
+    /** Milliseconds to stay down. Defaults to 0. */
+    downMs?: number;
+    afterHealthy?: never;
+} | {
+    /**
+     * Fire once the server has answered `/health` this many times — the first
+     * boot is 1, the generation after one restart is 2.
+     */
+    afterHealthy: number;
+    downMs?: number;
+    after?: never;
+    nth?: never;
+};
+export type FaultProfile = {
+    description: string;
+    points: readonly FaultPoint[];
+};
+/**
+ * The declared profiles.
+ *
+ * Named scenarios rather than knobs, so a suite run says what it exercised and
+ * a failure names something a reader can picture. Add one here rather than
+ * assembling a plan at a call site — a plan that lives in one test cannot be
+ * run across the suite, which is the point of the mode.
+ */
+export declare const FAULT_PROFILES: Readonly<Record<string, FaultProfile>>;
+/**
+ * The profile `AAI_FAULT_PROFILE` names, or undefined when the mode is off.
+ *
+ * An unknown name THROWS naming the declared set rather than degrading to off:
+ * a typo would otherwise produce a green run that injected nothing, which is
+ * indistinguishable from a healthy one and is the failure this whole module is
+ * careful about.
+ */
+export declare function resolveFaultProfile(name?: string | undefined): FaultProfile | undefined;
+export type SupervisedServer = {
+    /** Origin the server answers on, stable across restarts (the port is fixed). */
+    url: string;
+    /**
+     * How many times the process has been killed and is BACK — incremented once
+     * the replacement answers `/health`, so polling this to `n` means the nth
+     * replacement is serving.
+     */
+    restarts: () => number;
+    /**
+     * Resolve once every declared fault point has fired AND the surviving
+     * generation answers `/health`.
+     *
+     * This is the point a test should assert from: it is the only moment at which
+     * "the faults happened and the server is back" is true, and without it a
+     * request races the restart window — so every test would have to be written
+     * retry-aware to survive a profile it does not know about. Resolves
+     * immediately when the mode is off.
+     *
+     * Throws on timeout, naming the points that never fired — the same shortfall
+     * {@link assertPlanConsumed} reports, surfaced at the moment a test waited for
+     * it rather than at teardown.
+     */
+    awaitSettled: (timeoutMs?: number) => Promise<void>;
+    /**
+     * Throw unless every declared fault point fired.
+     *
+     * For a test whose SUBJECT is the profile. A test merely running under one
+     * should call {@link awaitSettled} instead — a profile whose triggers that
+     * test never produces (a step-level trigger in a test that runs no workflow)
+     * would otherwise fail it for something that is not a bug.
+     */
+    assertPlanConsumed: () => void;
+    /** Every line the server wrote, across all generations. */
+    lines: () => readonly string[];
+    stop: () => Promise<void>;
+};
+export type SupervisedDevServerOptions = {
+    /** Absolute path to the CLI entry (`bin.mjs`). */
+    aaiBin: string;
+    /** The project directory to run in. */
+    cwd: string;
+    /** A fixed port: the URL has to survive a restart. */
+    port: number;
+    env: NodeJS.ProcessEnv;
+    /** Extra `aai dev` arguments. */
+    args?: readonly string[];
+    /** Defaults to `resolveFaultProfile()`. Pass one to drive the mode from a test. */
+    profile?: FaultProfile | undefined;
+    /**
+     * How long a restarted server has to answer `/health`. Defaults to
+     * {@link HEALTH_TIMEOUT_MS}.
+     *
+     * A test seam, and one worth having: the ONLY way to exercise "the server did
+     * not survive a kill this mode inflicted" is to let that wait expire, and at
+     * the shipped 60s that is a minute of wall clock per assertion.
+     */
+    healthTimeoutMs?: number | undefined;
+};
+/**
+ * Boot `aai dev` as a child and, under a fault profile, keep killing it.
+ *
+ * With no profile this is a plain spawn plus a health wait — the same thing the
+ * e2e suite did inline — so converting a test to it changes nothing until the
+ * env var is set.
+ */
+export declare function startSupervisedDevServer(opts: SupervisedDevServerOptions): Promise<SupervisedServer>;

package/dist/{_init-CbkrE2wq.mjs → _init-CpISqoR8.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { c as readJson, d as writeJson, s as isEexist } from "./_utils-0DHbcqUb.mjs";
-import { r as isDevMode, t as getMonorepoRoot } from "./_agent-C8Jk-ZcP.mjs";
-import { REPO_URL, downloadAndMergeTemplate } from "./_templates-B1kt3BGt.mjs";
+import { c as isEexist, l as readJson, p as writeJson } from "./_utils-B8QmtFhK.mjs";
+import { r as isDevMode, t as getMonorepoRoot } from "./_agent-vGW5SBnX.mjs";
+import { REPO_URL, downloadAndMergeTemplate } from "./_templates-iDGjGiPf.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
 //#region _init.ts

package/dist/{_output-CC300DzW.mjs → _output-CKkmWs7i.mjs}

@@ -45,7 +45,14 @@ function ok(data) {
 		data
 	};
 }
-/** Create an error result. */
+/**
+* Create an error result.
+*
+* `CommandResult<never>`, not `CommandResult<T>`: a failure carries no `data`,
+* so the parameter was inferred as `unknown` at all ten call sites and named
+* a type this value can never hold. `never` widens into any `CommandResult<T>`
+* the caller declares, so `return fail(...)` still type-checks everywhere.
+*/
 function fail(code, error, hint) {
 	return hint ? {
 		ok: false,

package/dist/_output.d.ts

@@ -40,8 +40,15 @@ export declare function writeLine(line: string): Promise<void>;
 export declare function installStdoutGuard(stream?: NodeJS.WriteStream): void;
 /** Create an ok result. */
 export declare function ok<T>(data: T): CommandResult<T>;
-/** Create an error result. */
-export declare function fail<T>(code: string, error: string, hint?: string): CommandResult<T>;
+/**
+ * Create an error result.
+ *
+ * `CommandResult<never>`, not `CommandResult<T>`: a failure carries no `data`,
+ * so the parameter was inferred as `unknown` at all ten call sites and named
+ * a type this value can never hold. `never` widens into any `CommandResult<T>`
+ * the caller declares, so `return fail(...)` still type-checks everywhere.
+ */
+export declare function fail(code: string, error: string, hint?: string): CommandResult<never>;
 /** Typed CLI error that carries a structured error code and optional hint. */
 export declare class CliError extends Error {
     readonly code: string;

package/dist/{_server-common-61fL__39.mjs → _server-common-6e0QI4mq.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as errorCode } from "./_utils-0DHbcqUb.mjs";
+import { i as errorCode } from "./_utils-B8QmtFhK.mjs";
 import path from "node:path";
 import { parseEnv } from "node:util";
 import fs from "node:fs/promises";

package/dist/{_slug-api-D30zPmsn.mjs → _slug-api-D2heILuC.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { n as getServerInfo } from "./_agent-C8Jk-ZcP.mjs";
-import { n as apiRequest, t as HINT_NOT_DEPLOYED } from "./_api-client-BX8Qv51n.mjs";
+import { n as getServerInfo } from "./_agent-vGW5SBnX.mjs";
+import { n as apiRequest, t as HINT_NOT_DEPLOYED } from "./_api-client-LgLksMhN.mjs";
 //#region _slug-api.ts
 /**
 * Authenticated request against a deployed agent's slug-scoped resource

package/dist/{_studio-D2ciIhbi.mjs → _studio-zAJycZ8j.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { n as apiRequest } from "./_api-client-BX8Qv51n.mjs";
+import { a as isStringArray, i as checkedResponse, n as apiRequest } from "./_api-client-LgLksMhN.mjs";
 import path from "node:path";
-import { MAX_SLUG_LENGTH, PREVIEW_SLUG_SUFFIX, VALID_SLUG_RE } from "@alexkroman1/aai/utils";
+import { MAX_SLUG_LENGTH, PREVIEW_SLUG_SUFFIX, VALID_SLUG_RE, isRecord } from "@alexkroman1/aai/utils";
 import { slugifyName } from "@alexkroman1/aai/slugify";
 import { isLocalOnlyFile, snapshotWorkspaceFiles } from "@alexkroman1/aai/workspace-files";
 //#region _studio.ts
@@ -61,7 +61,7 @@ function listStudioProjects(serverUrl, apiKey) {
 	return apiRequest(`${serverUrl}/studio/projects`, {
 		apiKey,
 		action: "list"
-	}).then((res) => res.projects);
+	}).then((res) => checkedResponse(res, (value) => isRecord(value) && isStringArray(value.projects), `the studio project list at ${serverUrl}`).projects);
 }
 /** Fetch a project, or null when it doesn't exist (the push existence probe). */
 function fetchStudioProject(serverUrl, apiKey, project) {