@alexkroman1/aai-cli 5.9.0 → 5.10.0

package/bin.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// The `aai` bin in BOTH layouts — the source checkout (`pnpm link --global`,
+// where it loads `cli.ts` directly) and the published tarball (where only
+// `dist/` ships, so it loads `dist/cli.mjs`). It used to be the dev bin only,
+// with `publishConfig.bin` pointing straight at `dist/cli.mjs`.
+//
+// One bin for both is what makes the compile cache reachable. The cache only
+// covers modules compiled AFTER the call, and every dependency of the CLI is
+// external (`deps.neverBundle` in tsdown.config.ts), so `dist/cli.mjs` carries
+// hoisted `import` statements for citty, execa and the rest — all evaluated
+// before any statement in that file could run. A banner or a first-line call
+// inside `cli.ts` would therefore cache nothing that costs anything. Loading
+// the entry through a DYNAMIC import from a wrapper is the only ordering that
+// puts the enable genuinely first.
+import { existsSync } from "node:fs";
+import { enableCompileCache } from "node:module";
+import { fileURLToPath } from "node:url";
+
+// Caches V8 bytecode per (Node version, file content) under the user's cache
+// dir, so `aai` pays parse+compile once per version rather than per
+// invocation. Deliberately unguarded: this returns a `{ status }` result and
+// does not throw, so an unwritable cache dir degrades to today's behaviour.
+enableCompileCache();
+
+// Source wins when present: a checkout that has also been built must keep
+// running `cli.ts`, or `pnpm link --global` would silently serve a stale
+// `dist/` instead of the working tree.
+const source = new URL("./cli.ts", import.meta.url);
+const entry = existsSync(fileURLToPath(source))
+  ? source
+  : new URL("./dist/cli.mjs", import.meta.url);
+await import(entry.href);

package/dist/{_agent-BPEXSdWX.mjs → _agent-DS2PUJcl.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as readProjectConfig, i as readGlobalConfig, n as ensureApiKey, o as serverOrigin, t as approveServer } from "./_config-BJm2o795.mjs";
+import { a as serverOrigin, i as readProjectConfig, n as ensureApiKey, r as readGlobalConfig, t as approveServer } from "./_config-DMyolIk9.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/{_bundler-Cjaxa2wi.mjs → _bundler-DC17suWN.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { u as validateAgentExport } from "./_utils-Ch0J4s6a.mjs";
-import { t as buildClient } from "./client-bundler-yiWoXrgb.mjs";
+import { u as validateAgentExport } from "./_utils-8KKw-bzi.mjs";
+import { t as buildClient } from "./client-bundler-DONm-khu.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";

package/dist/{_config-BJm2o795.mjs → _config-DMyolIk9.mjs}

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { t as CliError } from "./_output-CC300DzW.mjs";
-import { a as errorMessage, c as readJson, d as writeJson } from "./_utils-Ch0J4s6a.mjs";
+import { a as errorMessage, c as readJson, d as writeJson } from "./_utils-8KKw-bzi.mjs";
 import { mkdtempSync } from "node:fs";
 import path from "node:path";
+import fs from "node:fs/promises";
+import { setTimeout } from "node:timers/promises";
 import { tmpdir } from "node:os";
 import envPaths from "env-paths";
 import { z } from "zod";
@@ -107,6 +109,87 @@ function serverOrigin(url) {
 	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
 	return parsed.origin;
 }
+/** Bounded so a stuck lock degrades to the old racy write, never a hang. */
+const CONFIG_LOCK_TIMEOUT_MS = 2e3;
+const CONFIG_LOCK_RETRY_MS = 20;
+/** Older than this and the holder is assumed dead (crashed mid-update). */
+const CONFIG_LOCK_STALE_MS = 1e4;
+/**
+* Serialize a read-modify-write of the global config ACROSS PROCESSES.
+*
+* `writeJson` makes each individual write atomic, so no reader ever sees a
+* torn file — but the read→modify→write SPAN is not atomic, and every writer
+* here replaces the whole document. Two concurrent CLI invocations therefore
+* lose each other's updates: measured on this repo, 8 parallel commands each
+* approving a distinct origin recorded only 5 of them, and — the case that
+* matters — a concurrent `approveServer` straddling the final write of
+* `aai login` DISCARDS THE API KEY the login just reported saving, leaving
+* the next command with `not_logged_in`. That window is wide open in practice:
+* `aai login` polls for up to five minutes while the user approves in the
+* browser, so any other command run in that time can be mid-update when the
+* key lands.
+*
+* The lock is a `wx` (exclusive-create) lockfile — atomic on every platform
+* we target, and the only primitive available across processes without a
+* daemon. Three deliberate properties:
+*
+* - **Acquisition is bounded** (`CONFIG_LOCK_TIMEOUT_MS`). On timeout the
+*   update proceeds UNLOCKED rather than throwing: these are small
+*   convenience files, and failing `aai login` because a lockfile is stuck
+*   would be strictly worse than the lost update the lock exists to prevent.
+* - **A stale lock is broken** (`CONFIG_LOCK_STALE_MS`). A process killed
+*   mid-update leaves the file behind; without this, one crash would make
+*   every later config write take the unlocked path forever.
+* - **Never nest.** Re-entering from inside `fn` would self-deadlock until the
+*   timeout. `executeLogin` calls `approveServer` and the key update in
+*   sequence, not nested — keep it that way.
+*/
+async function withGlobalConfigLock(dir, fn) {
+	const lockPath = path.join(dir, "config.lock");
+	const deadline = Date.now() + CONFIG_LOCK_TIMEOUT_MS;
+	let held = false;
+	for (;;) try {
+		await fs.mkdir(dir, {
+			recursive: true,
+			mode: 448
+		});
+		await (await fs.open(lockPath, "wx", 384)).close();
+		held = true;
+		break;
+	} catch (err) {
+		if (err.code !== "EEXIST") break;
+		if (await fs.stat(lockPath).then((s) => Date.now() - s.mtimeMs).catch(() => 0) > CONFIG_LOCK_STALE_MS) {
+			await fs.rm(lockPath, { force: true }).catch(() => void 0);
+			continue;
+		}
+		if (Date.now() >= deadline) break;
+		await setTimeout(CONFIG_LOCK_RETRY_MS);
+	}
+	try {
+		return await fn();
+	} finally {
+		if (held) await fs.rm(lockPath, { force: true }).catch(() => void 0);
+	}
+}
+/**
+* Apply `update` to the global config under the cross-process lock, re-reading
+* inside it so the merge is against current contents rather than a snapshot
+* taken before the lock was held. Every read-modify-write of the global config
+* must go through this — a direct `readGlobalConfig`/`writeGlobalConfig` pair
+* is the bug this exists to prevent.
+*
+* Returning the argument unchanged skips the write, so the common no-op case
+* (an origin already approved — i.e. most `--server` invocations) costs a read
+* rather than a rewrite plus the lock contention that comes with it.
+*/
+async function updateGlobalConfig(update, configDir) {
+	const dir = configDir ?? getConfigDir();
+	await withGlobalConfigLock(dir, async () => {
+		const current = await readGlobalConfig(dir);
+		const next = update(current);
+		if (next !== current) await writeGlobalConfig(dir, next);
+	});
+}
 /**
 * Record `url`'s origin as user-approved, so later commands in this project
 * may send credentials there without re-passing `--server`.
@@ -114,14 +197,13 @@ function serverOrigin(url) {
 async function approveServer(url, configDir) {
 	const origin = serverOrigin(url);
 	if (!origin) return;
-	const dir = configDir ?? getConfigDir();
-	const config = await readGlobalConfig(dir);
-	const approved = config.approvedServers ?? [];
-	if (approved.includes(origin)) return;
-	await writeGlobalConfig(dir, {
-		...config,
-		approvedServers: [...approved, origin]
-	});
+	await updateGlobalConfig((config) => {
+		const approved = config.approvedServers ?? [];
+		return approved.includes(origin) ? config : {
+			...config,
+			approvedServers: [...approved, origin]
+		};
+	}, configDir);
 }
 async function readGlobalConfig(configDir) {
 	const dir = configDir ?? getConfigDir();
@@ -157,4 +239,4 @@ async function ensureApiKey(configDir) {
 	throw new CliError("not_logged_in", "You're not logged in.", "Run `aai login` to link your account. Non-interactive setups can point AAI_CONFIG_DIR at a config dir holding a logged-in key.");
 }
 //#endregion
-export { readProjectConfig as a, writeGlobalConfig as c, readGlobalConfig as i, writeProjectConfig as l, ensureApiKey as n, serverOrigin as o, getConfigDir as r, updateProjectConfig as s, approveServer as t };
+export { serverOrigin as a, writeProjectConfig as c, readProjectConfig as i, ensureApiKey as n, updateGlobalConfig as o, readGlobalConfig as r, updateProjectConfig as s, approveServer as t };

package/dist/_config.d.ts

@@ -54,6 +54,18 @@ export type GlobalConfig = {
  * were a real origin.
  */
 export declare function serverOrigin(url: string): string | null;
+/**
+ * Apply `update` to the global config under the cross-process lock, re-reading
+ * inside it so the merge is against current contents rather than a snapshot
+ * taken before the lock was held. Every read-modify-write of the global config
+ * must go through this — a direct `readGlobalConfig`/`writeGlobalConfig` pair
+ * is the bug this exists to prevent.
+ *
+ * Returning the argument unchanged skips the write, so the common no-op case
+ * (an origin already approved — i.e. most `--server` invocations) costs a read
+ * rather than a rewrite plus the lock contention that comes with it.
+ */
+export declare function updateGlobalConfig(update: (current: GlobalConfig) => GlobalConfig, configDir?: string): Promise<void>;
 /**
  * Record `url`'s origin as user-approved, so later commands in this project
  * may send credentials there without re-passing `--server`.

package/dist/_dev-env.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The dev server's CONTROL variables — the three things read straight from the
+ * shell rather than from the agent's `.env`.
+ *
+ * That distinction is the reason these live together. `resolveServerEnv` builds
+ * `ctx.env` from `.env`-declared keys only, deliberately, so an agent cannot
+ * come to depend on a shell variable that will not exist after deploy. These
+ * three are not agent config at all — they configure the *dev server process*
+ * (who may connect, where it binds, whether it restarts), so they are read from
+ * the environment on purpose and must never leak into `ctx.env`.
+ *
+ * Split out of `_dev-server.ts` purely to keep that module under the
+ * file-length cap; it is the only consumer.
+ */
+/**
+ * The env handed to `createServer` for host-mode connections: provider
+ * credentials plus the `AAI_ALLOW_HOST` gate read straight from the shell
+ * (it is a control variable, not something an agent declares in `.env`).
+ */
+export declare function hostModeEnv(providerEnv: Record<string, string>): Record<string, string>;
+/**
+ * Explicit bind host for the dev server, or `undefined` to take the
+ * loopback default. An empty `AAI_DEV_HOST` means "unset", not "every
+ * interface" — Node treats `listen(port, "")` as 0.0.0.0, which would quietly
+ * undo the loopback default this exists to guard.
+ */
+export declare function devBindHost(): string | undefined;
+/**
+ * File watching is OPT-IN — `AAI_DEV_WATCH=1` turns it on.
+ *
+ * A restart rebuilds the bundle and replaces the server, which drops nothing
+ * mid-request but does end in-flight voice sessions. That is the right default
+ * while editing an agent and the wrong one while a benchmark is driving the
+ * host for twenty minutes: a stray formatter save, a `.env` touch, or a git
+ * operation restarts the server underneath the run, and the harness reports it
+ * as a provider failure several records deep.
+ */
+export declare function devWatchEnabled(): boolean;

package/dist/{_dev-server-Cnf4jNzE.mjs → _dev-server-B3ivqyEd.mjs}

@@ -1,26 +1,77 @@
 #!/usr/bin/env node
-import { n as log } from "./_ui-RZmPgrF6.mjs";
-import { a as errorMessage, r as errorCode } from "./_utils-Ch0J4s6a.mjs";
-import { n as fallbackHtmlPlugin } from "./client-bundler-yiWoXrgb.mjs";
+import { n as log, r as notify } from "./_ui-DfwfDbT-.mjs";
+import { a as errorMessage, r as errorCode } from "./_utils-8KKw-bzi.mjs";
+import { n as fallbackHtmlPlugin } from "./client-bundler-DONm-khu.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
-import { n as createWorkerEvaluator } from "./_bundler-Cjaxa2wi.mjs";
-import { n as ensureApiKey } from "./_config-BJm2o795.mjs";
-import { t as resolveServerEnv } from "./_server-common-CnaP_Urf.mjs";
-import { createRequire } from "node:module";
+import { n as createWorkerEvaluator } from "./_bundler-DC17suWN.mjs";
+import { n as ensureApiKey } from "./_config-DMyolIk9.mjs";
+import { t as resolveServerEnv } from "./_server-common-DX8Bfrf5.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { setTimeout } from "node:timers/promises";
 import { createRuntime, createServer, requiredProviderEnvVars, withHostCredentialFallback } from "@alexkroman1/aai/runtime";
+import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
 import { watch } from "chokidar";
 import getPort, { portNumbers } from "get-port";
 import pDebounce from "p-debounce";
+//#region _dev-env.ts
+/**
+* The dev server's CONTROL variables — the three things read straight from the
+* shell rather than from the agent's `.env`.
+*
+* That distinction is the reason these live together. `resolveServerEnv` builds
+* `ctx.env` from `.env`-declared keys only, deliberately, so an agent cannot
+* come to depend on a shell variable that will not exist after deploy. These
+* three are not agent config at all — they configure the *dev server process*
+* (who may connect, where it binds, whether it restarts), so they are read from
+* the environment on purpose and must never leak into `ctx.env`.
+*
+* Split out of `_dev-server.ts` purely to keep that module under the
+* file-length cap; it is the only consumer.
+*/
+/**
+* The env handed to `createServer` for host-mode connections: provider
+* credentials plus the `AAI_ALLOW_HOST` gate read straight from the shell
+* (it is a control variable, not something an agent declares in `.env`).
+*/
+function hostModeEnv(providerEnv) {
+	const gate = process.env.AAI_ALLOW_HOST;
+	return gate === void 0 ? providerEnv : {
+		...providerEnv,
+		AAI_ALLOW_HOST: gate
+	};
+}
+/**
+* Explicit bind host for the dev server, or `undefined` to take the
+* loopback default. An empty `AAI_DEV_HOST` means "unset", not "every
+* interface" — Node treats `listen(port, "")` as 0.0.0.0, which would quietly
+* undo the loopback default this exists to guard.
+*/
+function devBindHost() {
+	const host = process.env.AAI_DEV_HOST?.trim();
+	return host ? host : void 0;
+}
+/**
+* File watching is OPT-IN — `AAI_DEV_WATCH=1` turns it on.
+*
+* A restart rebuilds the bundle and replaces the server, which drops nothing
+* mid-request but does end in-flight voice sessions. That is the right default
+* while editing an agent and the wrong one while a benchmark is driving the
+* host for twenty minutes: a stray formatter save, a `.env` touch, or a git
+* operation restarts the server underneath the run, and the harness reports it
+* as a provider failure several records deep.
+*/
+function devWatchEnabled() {
+	return /^(1|true|yes|on)$/i.test(process.env.AAI_DEV_WATCH?.trim() ?? "");
+}
+//#endregion
 //#region _dev-server.ts
 /**
 * Dev server for directory-based agents.
 *
 * Imports agent.ts directly for the full agent definition,
-* builds a runtime, and starts an HTTP+WebSocket server. Watches for
-* file changes and restarts automatically. Optionally runs Vite for
+* builds a runtime, and starts an HTTP+WebSocket server. File watching is
+* opt-in via `AAI_DEV_WATCH=1` (see devWatchEnabled). Optionally runs Vite for
 * client SPA HMR.
 */
 /**
@@ -58,28 +109,6 @@ async function resolveAgentEnv(root, agentDef) {
 	return env;
 }
 /**
-* The env handed to `createServer` for host-mode connections: provider
-* credentials plus the `AAI_ALLOW_HOST` gate read straight from the shell
-* (it is a control variable, not something an agent declares in `.env`).
-*/
-function hostModeEnv(providerEnv) {
-	const gate = process.env.AAI_ALLOW_HOST;
-	return gate === void 0 ? providerEnv : {
-		...providerEnv,
-		AAI_ALLOW_HOST: gate
-	};
-}
-/**
-* Explicit bind host for the dev server, or `undefined` to take the
-* loopback default. An empty `AAI_DEV_HOST` means "unset", not "every
-* interface" — Node treats `listen(port, "")` as 0.0.0.0, which would quietly
-* undo the loopback default this exists to guard.
-*/
-function devBindHost() {
-	const host = process.env.AAI_DEV_HOST?.trim();
-	return host ? host : void 0;
-}
-/**
 * 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=...)`
 * only cache-busts agent.ts itself — transitive imports (./tools.ts, etc.)
@@ -120,7 +149,7 @@ function isIgnoredPath(dir, filePath) {
 */
 function watchDirectory(dir, onChange) {
 	const debouncedChange = pDebounce(() => {
-		log.info("File change detected, restarting...");
+		notify("info", "File change detected, restarting...");
 		onChange();
 	}, 300);
 	const watcher = watch(dir, {
@@ -130,26 +159,15 @@ 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." : "";
-		log.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(err)}.${hint} Auto-restart on file changes may have stopped; restart \`aai dev\` after fixing.`);
 	});
 	watcher.on("all", () => {
 		debouncedChange().catch((err) => {
-			log.error(`Watch handler failed: ${errorMessage(err)}`);
+			notify("error", `Watch handler failed: ${errorMessage(err)}`);
 		});
 	});
 	return watcher;
 }
-/** Locate the pre-built default aai-ui client (served when no custom client.tsx). */
-function resolveDefaultClientDir() {
-	const require = createRequire(import.meta.url);
-	let pkgPath;
-	try {
-		pkgPath = require.resolve("@alexkroman1/aai-ui/package.json");
-	} catch (err) {
-		throw new Error(`Could not locate the default client UI (${errorMessage(err)}) — is @alexkroman1/aai-ui installed? Try reinstalling dependencies (pnpm install).`, { cause: err });
-	}
-	return path.join(path.dirname(pkgPath), "dist", "default-client");
-}
 /**
 * Vite dev-server config for the client SPA. Extracted so the proxy wiring
 * is unit-testable: `/websocket` MUST proxy with `ws: true` or `aai dev`
@@ -188,7 +206,7 @@ async function startDevServer(opts) {
 	const hasClient = existsSync(path.join(cwd, "client.tsx"));
 	const backendPort = hasClient ? await getPort({ port: portNumbers(port + 1, port + 100) }) : port;
 	const vitePort = port;
-	const clientDirOpt = hasClient ? {} : { clientDir: resolveDefaultClientDir() };
+	const clientDirOpt = hasClient ? {} : { clientDir: defaultClientDir() };
 	const evaluateWorker = createWorkerEvaluator();
 	/** Full build sequence, shared by initial startup and every restart. */
 	async function buildServer() {
@@ -219,12 +237,12 @@ async function startDevServer(opts) {
 		}
 		restarting = true;
 		restart().catch((err) => {
-			log.error(`Restart failed: ${errorMessage(err)}`);
+			notify("error", `Restart failed: ${errorMessage(err)}`);
 		}).finally(() => {
 			restarting = false;
 		});
 	}
-	const watcher = watchDirectory(cwd, kickRestart);
+	const watcher = devWatchEnabled() ? watchDirectory(cwd, kickRestart) : void 0;
 	let viteServer;
 	try {
 		currentServer = await buildServer();
@@ -234,11 +252,11 @@ async function startDevServer(opts) {
 			viteServer = await createViteServer(viteDevConfig(cwd, vitePort, backendPort));
 			await viteServer.listen();
 			viteServer.httpServer?.on("error", (err) => {
-				log.error(`Vite dev server error: ${errorMessage(err)}`);
+				notify("error", `Vite dev server error: ${errorMessage(err)}`);
 			});
 		}
 	} catch (err) {
-		await watcher.close().catch(() => void 0);
+		await watcher?.close().catch(() => void 0);
 		await viteServer?.close().catch(() => void 0);
 		throw err;
 	}
@@ -255,7 +273,7 @@ async function startDevServer(opts) {
 		try {
 			newServer = await buildServer();
 		} catch (err) {
-			log.error(`Restart failed: ${errorMessage(err)} (previous server still running)`);
+			notify("error", `Restart failed: ${errorMessage(err)} (previous server still running)`);
 			return;
 		}
 		if (closed) {
@@ -272,9 +290,9 @@ async function startDevServer(opts) {
 				await newServer.close().catch(() => void 0);
 				return;
 			}
-			log.success("Restarted");
+			notify("success", "Restarted");
 		} catch (err) {
-			log.error(`Restart failed: ${errorMessage(err)} — dev server is down; save a file to retry.`);
+			notify("error", `Restart failed: ${errorMessage(err)} — dev server is down; save a file to retry.`);
 			await newServer.close().catch(() => void 0);
 		}
 	}
@@ -299,7 +317,7 @@ async function startDevServer(opts) {
 	return () => {
 		cleanupPromise ??= (async () => {
 			closed = true;
-			await watcher.close().catch(() => void 0);
+			await watcher?.close().catch(() => void 0);
 			await viteServer?.close().catch(() => void 0);
 			await currentServer.close().catch(() => void 0);
 		})();

package/dist/_dev-server.d.ts

@@ -2,8 +2,8 @@
  * Dev server for directory-based agents.
  *
  * Imports agent.ts directly for the full agent definition,
- * builds a runtime, and starts an HTTP+WebSocket server. Watches for
- * file changes and restarts automatically. Optionally runs Vite for
+ * builds a runtime, and starts an HTTP+WebSocket server. File watching is
+ * opt-in via `AAI_DEV_WATCH=1` (see devWatchEnabled). Optionally runs Vite for
  * client SPA HMR.
  */
 import type { AgentDef } from "@alexkroman1/aai";

package/dist/{_init-DVNeyGSl.mjs → _init-CYLvYU-B.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { c as readJson, d as writeJson, s as isEexist } from "./_utils-Ch0J4s6a.mjs";
-import { r as isDevMode, t as getMonorepoRoot } from "./_agent-BPEXSdWX.mjs";
-import { REPO_URL, downloadAndMergeTemplate } from "./_templates-DDx08LIG.mjs";
+import { c as readJson, d as writeJson, s as isEexist } from "./_utils-8KKw-bzi.mjs";
+import { r as isDevMode, t as getMonorepoRoot } from "./_agent-DS2PUJcl.mjs";
+import { REPO_URL, downloadAndMergeTemplate } from "./_templates-BWJOiWOO.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
 //#region _init.ts

package/dist/{_server-common-CnaP_Urf.mjs → _server-common-DX8Bfrf5.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as errorCode } from "./_utils-Ch0J4s6a.mjs";
+import { r as errorCode } from "./_utils-8KKw-bzi.mjs";
 import path from "node:path";
 import { parseEnv } from "node:util";
 import fs from "node:fs/promises";

package/dist/{_slug-api-CQw1YGR5.mjs → _slug-api-fRNNR8tz.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as getServerInfo } from "./_agent-BPEXSdWX.mjs";
+import { n as getServerInfo } from "./_agent-DS2PUJcl.mjs";
 import { n as apiRequest, t as HINT_NOT_DEPLOYED } from "./_api-client-B-upMGkc.mjs";
 //#region _slug-api.ts
 /**

package/dist/{_templates-DDx08LIG.mjs → _templates-BWJOiWOO.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { a as errorMessage } from "./_utils-Ch0J4s6a.mjs";
-import { t as getMonorepoRoot } from "./_agent-BPEXSdWX.mjs";
+import { a as errorMessage } from "./_utils-8KKw-bzi.mjs";
+import { t as getMonorepoRoot } from "./_agent-DS2PUJcl.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import fs from "node:fs/promises";

package/dist/{_typecheck-gate-BT4iPz7A.mjs → _typecheck-gate-DB-PY0A3.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { t as CliError } from "./_output-CC300DzW.mjs";
-import { n as log } from "./_ui-RZmPgrF6.mjs";
+import { n as log } from "./_ui-DfwfDbT-.mjs";
 import { typecheckProject } from "./typecheck.mjs";
 //#region _typecheck-gate.ts
 /**

package/dist/{_ui-RZmPgrF6.mjs → _ui-DfwfDbT-.mjs}

@@ -13,6 +13,31 @@ function silenceOutput() {
 	silenced = true;
 }
 /**
+* Emit a message that must survive JSON mode — human mode gets the normal
+* clack styling, JSON mode gets a plain line on STDERR.
+*
+* `silenceOutput` no-ops every `log` method so that JSON mode's contract
+* ("exactly one result line on stdout") holds. That is right for
+* request/response commands, and wrong for LONG-RUNNING ones: `aai dev`
+* writes its single JSON line at startup and then keeps running, so every
+* later message — a failed rebuild, an unhandled rejection, "the dev server
+* is down; save a file to retry" — was silenced for the rest of the process.
+* And JSON mode is AUTO-DETECTED on a pipe, so that is the normal case:
+* `aai dev > dev.log`, a process supervisor, or a container all hid every
+* build failure, leaving the old agent served with nothing to say why edits
+* had stopped taking effect.
+*
+* stderr keeps the stdout contract intact — a script still parses one JSON
+* line — while a human tailing the log sees what happened.
+*/
+function notify(level, message) {
+	if (!silenced) {
+		log[level](message);
+		return;
+	}
+	process.stderr.write(`${message}\n`);
+}
+/**
 * Unwrap a clack prompt result, exiting cleanly if the user cancelled.
 * `message` lets the caller name what was cancelled (e.g. "Setup cancelled").
 */
@@ -40,4 +65,4 @@ function parsePort(raw) {
 	return port;
 }
 //#endregion
-export { unwrapCancel as a, silenceOutput as i, log as n, parsePort as r, fmtUrl as t };
+export { silenceOutput as a, parsePort as i, log as n, unwrapCancel as o, notify as r, fmtUrl as t };

package/dist/_ui.d.ts

@@ -4,6 +4,25 @@ type Log = typeof p.log;
 export declare const log: Log;
 /** Replace all log methods with no-ops. Call once in JSON mode. */
 export declare function silenceOutput(): void;
+/**
+ * Emit a message that must survive JSON mode — human mode gets the normal
+ * clack styling, JSON mode gets a plain line on STDERR.
+ *
+ * `silenceOutput` no-ops every `log` method so that JSON mode's contract
+ * ("exactly one result line on stdout") holds. That is right for
+ * request/response commands, and wrong for LONG-RUNNING ones: `aai dev`
+ * writes its single JSON line at startup and then keeps running, so every
+ * later message — a failed rebuild, an unhandled rejection, "the dev server
+ * is down; save a file to retry" — was silenced for the rest of the process.
+ * And JSON mode is AUTO-DETECTED on a pipe, so that is the normal case:
+ * `aai dev > dev.log`, a process supervisor, or a container all hid every
+ * build failure, leaving the old agent served with nothing to say why edits
+ * had stopped taking effect.
+ *
+ * stderr keeps the stdout contract intact — a script still parses one JSON
+ * line — while a human tailing the log sees what happened.
+ */
+export declare function notify(level: "error" | "warn" | "info" | "success", message: string): void;
 /**
  * Unwrap a clack prompt result, exiting cleanly if the user cancelled.
  * `message` lets the caller name what was cancelled (e.g. "Setup cancelled").

package/dist/{_utils-Ch0J4s6a.mjs → _utils-8KKw-bzi.mjs}

@@ -72,8 +72,15 @@ async function readJson(filePath) {
 * torn config.json fails `JSON.parse`, reads back as `{}`, and the next
 * read-modify-write silently wipes fields like `approvedServers`. Rename on
 * the same filesystem is atomic, so readers only ever see a complete file.
-* Two concurrent CLI processes can still lose each other's *updates*
-* (last rename wins) — acceptable for these small user-config files.
+*
+* Atomic per WRITE is not atomic per read-modify-write: two concurrent CLI
+* processes still lose each other's *updates* (last rename wins). That was
+* long documented here as acceptable "for these small user-config files",
+* and it is — for `.aai/project.json`, which is per-directory. It is NOT
+* acceptable for the GLOBAL config, where it dropped the API key a
+* successful `aai login` had just reported saving. Every global-config
+* update therefore goes through `updateGlobalConfig` in `_config.ts`, which
+* holds a cross-process lock around the read and the write.
 *
 * `mode` restricts the file's permissions (the rename carries the temp
 * file's mode to the destination, so an existing world-readable file is

package/dist/_utils.d.ts

@@ -35,8 +35,15 @@ export declare function readJson(filePath: string): Promise<unknown>;
  * torn config.json fails `JSON.parse`, reads back as `{}`, and the next
  * read-modify-write silently wipes fields like `approvedServers`. Rename on
  * the same filesystem is atomic, so readers only ever see a complete file.
- * Two concurrent CLI processes can still lose each other's *updates*
- * (last rename wins) — acceptable for these small user-config files.
+ *
+ * Atomic per WRITE is not atomic per read-modify-write: two concurrent CLI
+ * processes still lose each other's *updates* (last rename wins). That was
+ * long documented here as acceptable "for these small user-config files",
+ * and it is — for `.aai/project.json`, which is per-directory. It is NOT
+ * acceptable for the GLOBAL config, where it dropped the API key a
+ * successful `aai login` had just reported saving. Every global-config
+ * update therefore goes through `updateGlobalConfig` in `_config.ts`, which
+ * holds a cross-process lock around the read and the write.
  *
  * `mode` restricts the file's permissions (the rename carries the temp
  * file's mode to the destination, so an existing world-readable file is

package/dist/{build-WdGtFsSx.mjs → build-CACFbdQ4.mjs}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { a as ok, t as CliError } from "./_output-CC300DzW.mjs";
-import { n as log } from "./_ui-RZmPgrF6.mjs";
-import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-Cjaxa2wi.mjs";
-import { assertTypechecks } from "./_typecheck-gate-BT4iPz7A.mjs";
-import { classifyVitestError, runVitest } from "./test-CkXvfcpq.mjs";
+import { n as log } from "./_ui-DfwfDbT-.mjs";
+import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-DC17suWN.mjs";
+import { assertTypechecks } from "./_typecheck-gate-DB-PY0A3.mjs";
+import { classifyVitestError, runVitest } from "./test-C-V98oC-.mjs";
 //#region build.ts
 /**
 * `aai build` — bundle the agent without deploying, behind the same gates