@alexkroman1/aai-cli 5.14.0 → 6.1.0

package/dist/{_agent-C8Jk-ZcP.mjs → _agent-vGW5SBnX.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as serverOrigin, i as readProjectConfig, n as ensureApiKey, r as readGlobalConfig, t as approveServer } from "./_config-CzwAWOWr.mjs";
+import { a as serverOrigin, i as readProjectConfig, n as ensureApiKey, r as readGlobalConfig, t as approveServer } from "./_config-D_s09e7g.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -100,16 +100,34 @@ async function resolveDeployTarget(cwd, explicitServer) {
 		apiKey: await ensureApiKey()
 	};
 }
+/**
+* The deployed slug a slug-scoped command needs, or the sentence naming
+* `aai publish`.
+*
+* A pulled-but-never-published project has a config without a slug — for
+* slug-scoped commands (secret, storage, delete) that is the same as never
+* deployed. Exported so a command that has ALREADY resolved the target
+* (`aai delete`) can demand the slug without resolving it a second time; one
+* sentence, one place.
+*
+* The slug's SHAPE was already enforced by `resolveDeployTarget`, for every
+* command rather than only the slug-scoped ones — see `assertValidConfigSlug`.
+* Deliberately not re-checked here: two copies of that guard is what let
+* `publish` ship without one.
+*/
+function requireDeployedSlug(config) {
+	if (!config?.slug) throw new Error("This project has no deployed agent — run `aai publish` first");
+	return config.slug;
+}
 /** Like resolveDeployTarget, but requires an existing deployment (project config). */
 async function getServerInfo(cwd, explicitServer) {
 	const { config, serverUrl, apiKey } = await resolveDeployTarget(cwd, explicitServer);
-	if (!config?.slug) throw new Error("This project has no deployed agent — run `aai publish` first");
 	return {
 		serverUrl,
-		slug: config.slug,
+		slug: requireDeployedSlug(config),
 		apiKey,
-		studioProject: config.studioProject
+		studioProject: config?.studioProject
 	};
 }
 //#endregion
-export { resolveServerUrl as a, resolveDeployTarget as i, getServerInfo as n, isDevMode as r, getMonorepoRoot as t };
+export { resolveDeployTarget as a, requireDeployedSlug as i, getServerInfo as n, resolveServerUrl as o, isDevMode as r, getMonorepoRoot as t };

package/dist/_agent.d.ts

@@ -33,6 +33,24 @@ export declare function resolveDeployTarget(cwd: string, explicitServer?: string
     serverUrl: string;
     apiKey: string;
 }>;
+/**
+ * The deployed slug a slug-scoped command needs, or the sentence naming
+ * `aai publish`.
+ *
+ * A pulled-but-never-published project has a config without a slug — for
+ * slug-scoped commands (secret, storage, delete) that is the same as never
+ * deployed. Exported so a command that has ALREADY resolved the target
+ * (`aai delete`) can demand the slug without resolving it a second time; one
+ * sentence, one place.
+ *
+ * The slug's SHAPE was already enforced by `resolveDeployTarget`, for every
+ * command rather than only the slug-scoped ones — see `assertValidConfigSlug`.
+ * Deliberately not re-checked here: two copies of that guard is what let
+ * `publish` ship without one.
+ */
+export declare function requireDeployedSlug(config: {
+    slug?: string | undefined;
+} | null): string;
 /** Like resolveDeployTarget, but requires an existing deployment (project config). */
 export declare function getServerInfo(cwd: string, explicitServer?: string): Promise<{
     serverUrl: string;

package/dist/{_api-client-BX8Qv51n.mjs → _api-client-LgLksMhN.mjs}

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { omitUndefined } from "@alexkroman1/aai/utils";
+import { t as CliError } from "./_output-CKkmWs7i.mjs";
+import { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { FetchError, ofetch } from "ofetch";
 //#region _api-client.ts
 /**
@@ -13,6 +14,17 @@ const HINT_INVALID_API_KEY = "Your API key may be invalid. Run `aai` to re-enter
 /** 404 hint for requests scoped to a deployed agent's slug. */
 const HINT_NOT_DEPLOYED = "The agent may not be deployed. Check `.aai/project.json` for the correct slug.";
 /**
+* {@link ApiTestSeam} as request options, with absent entries OMITTED rather
+* than passed as `undefined` (which `exactOptionalPropertyTypes` refuses and
+* which would override `apiRequest`'s own defaults with nothing).
+*/
+function apiTestSeam(opts) {
+	return omitUndefined({
+		fetch: opts.fetch,
+		retryDelay: opts.retryDelay
+	});
+}
+/**
 * Send an authenticated request to the platform API and return the parsed
 * JSON response. Throws a descriptive error with status-specific hints on
 * failure (the 401 hint is always included; pass more via `hints`).
@@ -36,6 +48,32 @@ async function apiRequest(url, opts) {
 	}
 }
 /**
+* A 2xx body CHECKED against the shape the caller was promised, rather than
+* cast to it.
+*
+* `apiRequest<T>` is a cast: `T` describes what the platform sends and nothing
+* verifies it, so a 200 from something that is not our server — an intercepting
+* proxy, a captive portal, a mismatched or half-deployed backend — flows on as
+* a fully-typed object whose fields are `undefined`. That is not hypothetical
+* and not merely cosmetic: a deploy whose response lacked `slug` printed
+* `Deployed https://server/undefined` and wrote `slug: undefined` into
+* `.aai/project.json`, where `JSON.stringify` DROPS it — so the next deploy saw
+* no slug, minted a fresh one, and orphaned the running agent. `aai publish`
+* grew a hand-written guard for exactly that (`studio.ts`); this is that guard
+* with a name, so the next response shape gets it without the incident first.
+*
+* The predicate is the caller's because the shape is: this only owns the
+* failure, whose code and hint are the same wherever it fires.
+*/
+function checkedResponse(value, isExpected, what) {
+	if (isExpected(value)) return value;
+	throw new CliError("bad_response", `Unexpected response from ${what}.`, "Check that --server points at an aai platform server, then try again.");
+}
+/** True when every element of `value` is a string (an empty array qualifies). */
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+/**
 * Collapse `{"error": "..."}` payloads embedded in a message into their own
 * text. Studio Publish runs the real `aai deploy` inside the sandbox, so its
 * failures arrive wrapped twice and stringifying them produced a
@@ -57,11 +95,10 @@ function unwrapEmbeddedErrors(message, depth = 0) {
 /** The messages of a Zod issue tree, deduped and flattened. */
 function zodIssueMessages(value) {
 	if (Array.isArray(value)) return value.flatMap(zodIssueMessages);
-	if (value === null || typeof value !== "object") return [];
-	const node = value;
-	const nested = zodIssueMessages(node.issues);
+	if (!isRecord(value)) return [];
+	const nested = zodIssueMessages(value.issues);
 	if (nested.length > 0) return nested;
-	return typeof node.message === "string" ? [node.message] : [];
+	return typeof value.message === "string" ? [value.message] : [];
 }
 /**
 * A human-readable one-liner for a server error body.
@@ -74,10 +111,10 @@ function zodIssueMessages(value) {
 */
 function describeErrorBody(data) {
 	if (typeof data === "string") return data;
-	if (data === null || typeof data !== "object") return JSON.stringify(data ?? "");
+	if (!isRecord(data)) return JSON.stringify(data ?? "");
 	const error = data.error;
 	if (typeof error === "string") return unwrapEmbeddedErrors(error);
-	if (error !== null && typeof error === "object") {
+	if (isRecord(error)) {
 		const { message } = error;
 		if (typeof message === "string") {
 			try {
@@ -102,4 +139,4 @@ function toApiError(err, url, opts) {
 	return new Error(`${opts.action} failed: could not reach ${url}\n  ${hint}`, { cause });
 }
 //#endregion
-export { apiRequest as n, HINT_NOT_DEPLOYED as t };
+export { isStringArray as a, checkedResponse as i, apiRequest as n, apiTestSeam as r, HINT_NOT_DEPLOYED as t };

package/dist/_api-client.d.ts

@@ -35,12 +35,51 @@ export type ApiRequestOptions = {
      */
     allow404?: boolean;
 };
+/**
+ * The two options a caller only ever supplies from a TEST — a fetch
+ * implementation and a zeroed retry delay.
+ *
+ * ONE declaration, so a wrapper around `apiRequest` (`runDeploy`, `runDelete`)
+ * says "plus the test seam" instead of restating both fields and both doc
+ * comments. They were written out three times, and the two copies were already
+ * spelled differently from each other.
+ */
+export type ApiTestSeam = Pick<ApiRequestOptions, "fetch" | "retryDelay">;
+/**
+ * {@link ApiTestSeam} as request options, with absent entries OMITTED rather
+ * than passed as `undefined` (which `exactOptionalPropertyTypes` refuses and
+ * which would override `apiRequest`'s own defaults with nothing).
+ */
+export declare function apiTestSeam(opts: ApiTestSeam): ApiTestSeam;
 /**
  * Send an authenticated request to the platform API and return the parsed
  * JSON response. Throws a descriptive error with status-specific hints on
  * failure (the 401 hint is always included; pass more via `hints`).
  */
 export declare function apiRequest<T = unknown>(url: string, opts: ApiRequestOptions): Promise<T>;
+/**
+ * A 2xx body CHECKED against the shape the caller was promised, rather than
+ * cast to it.
+ *
+ * `apiRequest<T>` is a cast: `T` describes what the platform sends and nothing
+ * verifies it, so a 200 from something that is not our server — an intercepting
+ * proxy, a captive portal, a mismatched or half-deployed backend — flows on as
+ * a fully-typed object whose fields are `undefined`. That is not hypothetical
+ * and not merely cosmetic: a deploy whose response lacked `slug` printed
+ * `Deployed https://server/undefined` and wrote `slug: undefined` into
+ * `.aai/project.json`, where `JSON.stringify` DROPS it — so the next deploy saw
+ * no slug, minted a fresh one, and orphaned the running agent. `aai publish`
+ * grew a hand-written guard for exactly that (`studio.ts`); this is that guard
+ * with a name, so the next response shape gets it without the incident first.
+ *
+ * The predicate is the caller's because the shape is: this only owns the
+ * failure, whose code and hint are the same wherever it fires.
+ */
+export declare function checkedResponse<T>(value: unknown, isExpected: (value: unknown) => value is T, 
+/** The route, named as a human would say it — "the deploy route at <url>". */
+what: string): T;
+/** True when every element of `value` is a string (an empty array qualifies). */
+export declare function isStringArray(value: unknown): value is string[];
 /**
  * A human-readable one-liner for a server error body.
  *

package/dist/{_bundler-BuIyDdvs.mjs → _bundler-BapCUUJN.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { u as validateAgentExport } from "./_utils-0DHbcqUb.mjs";
-import { t as buildClient } from "./client-bundler-C9qXL8A2.mjs";
-import { buildWorker } from "./worker-bundler.mjs";
+import { f as validateAgentExport } from "./_utils-B8QmtFhK.mjs";
+import { t as buildClient } from "./client-bundler-B8Q9F8gJ.mjs";
+import { n as buildWorkflows, t as buildWorker } from "./worker-bundler-CIdDhZ0c.mjs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
@@ -17,10 +17,14 @@ import { hash } from "node:crypto";
 * config and evaluates nothing, so every read of one happens here.
 */
 async function buildAgentBundle(cwd, opts = {}) {
-	const [worker, clientFiles] = await Promise.all([buildWorker(cwd, opts), buildClient(cwd)]);
+	const [workflows, clientFiles] = await Promise.all([buildWorkflows(cwd), buildClient(cwd)]);
 	return {
-		worker,
-		clientFiles
+		worker: await buildWorker(cwd, {
+			...opts,
+			workflows
+		}),
+		clientFiles,
+		...workflows && { workflows }
 	};
 }
 /**
@@ -47,6 +51,26 @@ async function evalWorkerBundle(code) {
 	validateAgentExport(agentDef);
 	return agentDef;
 }
+/**
+* {@link evalWorkerBundle}, keeping the workflow exports the AgentDef cannot
+* carry.
+*
+* A separate function rather than a wider return from `evalWorkerBundle`,
+* because every other caller wants the agent and nothing else — and the two
+* strings are ~76 KB that a deploy path has no use for.
+*/
+async function evalWorkerWithWorkflows(code) {
+	const mod = await importWorkerModule(code);
+	const agentDef = mod.default ?? mod;
+	validateAgentExport(agentDef);
+	const workflowCode = mod.__aaiWorkflowCode;
+	const stepCode = mod.__aaiStepCode;
+	return {
+		agent: agentDef,
+		workflowCode: typeof workflowCode === "string" ? workflowCode : void 0,
+		stepCode: typeof stepCode === "string" ? stepCode : void 0
+	};
+}
 /** Import a built worker from a temp file. See {@link evalWorkerBundle}. */
 async function importWorkerModule(code) {
 	const dir = await mkdtemp(path.join(tmpdir(), "aai-worker-"));
@@ -78,23 +102,27 @@ async function evalWorkerConfig(code) {
 	return (await importWorkerModule(code)).__aaiConfig;
 }
 /**
-* Memoizing wrapper around `evalWorkerBundle` for long-lived callers (the
-* dev server): byte-identical worker code returns the previously evaluated
-* AgentDef without touching the ESM registry. No-op saves and formatter
+* Memoizing wrapper around `evalWorkerWithWorkflows` for long-lived callers
+* (the dev server): byte-identical worker code returns the previously
+* evaluated result without touching the ESM registry. No-op saves and formatter
 * churn are the common watcher events, so this caps the registry leak (see
 * `evalWorkerBundle`) to genuinely-new bundles — the residual one-module-per-
 * distinct-build leak is accepted for the reasons documented there.
+*
+* It evaluates the WORKFLOW-carrying variant because its one caller is
+* `aai dev`, which has no guest to re-read the bundle: dropping the two strings
+* here is what left the dev server unable to serve a workflow at all.
 */
 function createWorkerEvaluator() {
 	let lastHash;
-	let lastAgentDef;
+	let lastWorker;
 	return async (code) => {
 		const codeHash = hash("sha256", code);
-		if (lastAgentDef && codeHash === lastHash) return lastAgentDef;
-		const agentDef = await evalWorkerBundle(code);
+		if (lastWorker && codeHash === lastHash) return lastWorker;
+		const worker = await evalWorkerWithWorkflows(code);
 		lastHash = codeHash;
-		lastAgentDef = agentDef;
-		return agentDef;
+		lastWorker = worker;
+		return worker;
 	};
 }
 //#endregion

package/dist/_bundler.d.ts

@@ -1,11 +1,21 @@
 import type { AgentDef } from "@alexkroman1/aai";
 import { type BuildWorkerOptions } from "./worker-bundler.ts";
-/** Output from the bundler: worker ESM + client files. */
+import { type WorkflowBundleOutput } from "./workflow-bundler.ts";
+/** Output from the bundler: worker ESM + client files + workflow artifacts. */
 export type DirectoryBundleOutput = {
     /** ESM bundle of agent.ts (tool execute functions + hook handlers). */
     worker: string;
     /** Static client files from Vite build. Empty if no client.tsx. */
     clientFiles: Record<string, string>;
+    /**
+     * The project's durable workflows, or undefined when it declares none.
+     *
+     * Built here rather than in the guest because the transform is per TENANT: the
+     * guest image is baked once and serves many agents, so there is no
+     * `workflows/` directory in existence when it is built. See
+     * `workflow-bundler.ts`.
+     */
+    workflows?: WorkflowBundleOutput;
 };
 /**
  * Bundle an agent directory: build agent.ts into worker ESM + client files.
@@ -35,6 +45,30 @@ export declare function buildAgentBundle(cwd: string, opts?: BuildWorkerOptions)
  * experimental.
  */
 export declare function evalWorkerBundle(code: string): Promise<AgentDef>;
+/**
+ * The agent plus the compiled workflow surface a worker carries.
+ *
+ * `evalWorkerBundle` returns only the `AgentDef`, which is all a deploy needs —
+ * the guest re-reads the bundle itself. `aai dev` never hands the bundle to a
+ * guest, so this is the only path by which the workflow code reaches a running
+ * server locally, and dropping it is why `aai dev` served no workflows at first.
+ */
+export type EvaluatedWorker = {
+    agent: AgentDef;
+    /** `__aaiWorkflowCode` — the flow bundle, for `workflowEntrypoint`. */
+    workflowCode: string | undefined;
+    /** `__aaiStepCode` — evaluated to register the project's step functions. */
+    stepCode: string | undefined;
+};
+/**
+ * {@link evalWorkerBundle}, keeping the workflow exports the AgentDef cannot
+ * carry.
+ *
+ * A separate function rather than a wider return from `evalWorkerBundle`,
+ * because every other caller wants the agent and nothing else — and the two
+ * strings are ~76 KB that a deploy path has no use for.
+ */
+export declare function evalWorkerWithWorkflows(code: string): Promise<EvaluatedWorker>;
 /**
  * The config a built worker describes about itself — its `__aaiConfig`
  * export, generated by `buildWorker`'s wrapper entry (`toAgentConfig(def)`
@@ -50,11 +84,15 @@ export declare function evalWorkerBundle(code: string): Promise<AgentDef>;
  */
 export declare function evalWorkerConfig(code: string): Promise<unknown>;
 /**
- * Memoizing wrapper around `evalWorkerBundle` for long-lived callers (the
- * dev server): byte-identical worker code returns the previously evaluated
- * AgentDef without touching the ESM registry. No-op saves and formatter
+ * Memoizing wrapper around `evalWorkerWithWorkflows` for long-lived callers
+ * (the dev server): byte-identical worker code returns the previously
+ * evaluated result without touching the ESM registry. No-op saves and formatter
  * churn are the common watcher events, so this caps the registry leak (see
  * `evalWorkerBundle`) to genuinely-new bundles — the residual one-module-per-
  * distinct-build leak is accepted for the reasons documented there.
+ *
+ * It evaluates the WORKFLOW-carrying variant because its one caller is
+ * `aai dev`, which has no guest to re-read the bundle: dropping the two strings
+ * here is what left the dev server unable to serve a workflow at all.
  */
-export declare function createWorkerEvaluator(): (code: string) => Promise<AgentDef>;
+export declare function createWorkerEvaluator(): (code: string) => Promise<EvaluatedWorker>;

package/dist/_cli-common.d.ts

@@ -1,4 +1,4 @@
-import type { ArgsDef, CommandDef } from "citty";
+import { type ArgsDef, type CommandDef, type CommandMeta, type ParsedArgs } from "citty";
 import { type CommandResult, type OutputMode } from "./_output.ts";
 /** Shared arg definitions for citty commands. */
 export declare const sharedArgs: {
@@ -33,6 +33,17 @@ export declare function findUnknownFlags(rawArgs: string[], argsDef: ArgsDef): s
  * reads `subCommands` and `args`, and the concrete generics differ per command.
  */
 type AnyCommandDef = CommandDef<ArgsDef>;
+/**
+ * `aai secret put` for a subcommand, `aai` for the root — the name to put in
+ * front of `--help` when telling someone which usage to read.
+ *
+ * Beside {@link resolve} because it is the same job: `meta` is a `Resolvable`,
+ * so only the plain-object form carries a name synchronously and anything else
+ * degrades to the binary name rather than blocking an error path on a resolve.
+ * This module owns citty's `Resolvable` handling; `cli.ts` had its own copy of
+ * the narrowing.
+ */
+export declare function commandPath<T extends ArgsDef>(cmd: CommandDef<T>, parent?: CommandDef<T>): string;
 /**
  * Unknown flags in `argv` for whichever (possibly nested) subcommand it
  * selects — `[]` when everything is declared.
@@ -56,10 +67,63 @@ export declare function setup(opts?: {
  *   key, and commands with no platform traffic never prompt at all.
  *
  * A thrown error and a returned `fail(...)` converge here on one emitter:
- * human mode logs the message, JSON mode writes exactly one result line,
- * and both exit 1.
+ * human mode logs the message and the hint, JSON mode writes exactly one
+ * result line, and both exit 1.
+ *
+ * That convergence is the whole contract and it was HALF TRUE for a long
+ * time: only the `catch` printed anything, so a body that RETURNED a failure
+ * fell straight through to the JSON check and `process.exit(1)`. In human
+ * mode that is a bare exit 1 with an empty terminal — `aai test` with no
+ * runner binary on PATH (message and "is it on your PATH?" both discarded),
+ * every `aai workflow` verb against a booting sandbox (the agent's own
+ * sentence plus `HINT_BROKER` discarded), `aai secret put` with an empty
+ * value, and `aai storage disable`'s "re-run with --force". Nine paths, all
+ * silent. Emitting is therefore driven by the RESULT rather than by which
+ * arm produced it.
  */
 export declare function runCommand(args: {
     json?: boolean | undefined;
 }, fn: (mode: OutputMode) => Promise<CommandResult<unknown>>): Promise<void>;
+/**
+ * What a command needs from the working directory, stated rather than
+ * re-derived:
+ *
+ * - `"agent"` — an agent project. Refuses a directory with no `agent.ts`.
+ * - `"any"` — the working directory, whatever is in it.
+ * - `"none"` — no directory policy; the body resolves whatever it needs.
+ */
+export type CwdPolicy = "agent" | "any" | "none";
+/** `undefined` under `"none"`, so a body cannot read a cwd it never asked for. */
+type CwdFor<P extends CwdPolicy> = P extends "none" ? undefined : string;
+/** Everything a command body gets, in one argument. */
+export type ExecContext<T extends ArgsDef, P extends CwdPolicy> = {
+    args: ParsedArgs<T>;
+    mode: OutputMode;
+    cwd: CwdFor<P>;
+};
+/**
+ * Define a citty command whose body is an EXECUTOR — the shape all
+ * twenty-four of this CLI's leaf commands have.
+ *
+ * Written longhand, each one restates the same four lines (`async run({ args
+ * })`, `await runCommand(args, async (mode) => …)`, a cwd resolution, a lazy
+ * `await import`) and, in the middle of them, DECIDES the working-directory
+ * policy — which is the part that is not boilerplate and the part that has
+ * been wrong in production: `aai test` shipped calling `setup()` bare instead
+ * of `setup({ agent: true })`, so in a directory with no `agent.ts` it found
+ * no test file, reported `{ passed: true, skipped: true }` and exited 0. A
+ * green result for a project that is not there reads, in CI, exactly like a
+ * passing suite.
+ *
+ * `cwd` is a required field of the spec, so that decision is stated once per
+ * command in the one place a reader looks for it, and "forgot to pass
+ * `{ agent: true }`" stops being a representable mistake — the alternative
+ * spelling is a policy name that does not exist.
+ */
+export declare function defineExec<const T extends ArgsDef, P extends CwdPolicy>(spec: {
+    meta: CommandMeta;
+    args: T;
+    cwd: P;
+    run: (ctx: ExecContext<T, P>) => Promise<CommandResult<unknown>>;
+}): CommandDef<T>;
 export {};

package/dist/{_config-CzwAWOWr.mjs → _config-D_s09e7g.mjs}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { t as CliError } from "./_output-CC300DzW.mjs";
-import { a as errorMessage, c as readJson, d as writeJson } from "./_utils-0DHbcqUb.mjs";
+import { t as CliError } from "./_output-CKkmWs7i.mjs";
+import { c as isEexist, l as readJson, o as errorMessage, p as writeJson } from "./_utils-B8QmtFhK.mjs";
 import { mkdtempSync } from "node:fs";
 import path from "node:path";
 import fs from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { setTimeout } from "node:timers/promises";
+import { sleep } from "@alexkroman1/aai/internal";
 import envPaths from "env-paths";
 import { z } from "zod";
 //#region _config.ts
@@ -146,32 +146,50 @@ const CONFIG_LOCK_STALE_MS = 1e4;
 */
 async function withGlobalConfigLock(dir, fn) {
 	const lockPath = path.join(dir, "config.lock");
+	const held = await acquireConfigLock(dir, lockPath);
+	try {
+		return await fn();
+	} finally {
+		if (held) await fs.rm(lockPath, { force: true }).catch(() => void 0);
+	}
+}
+/** True when this process created the lockfile; false means "proceed unlocked". */
+async function acquireConfigLock(dir, lockPath) {
 	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;
+		return true;
 	} 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);
+		if (!isEexist(err)) return false;
+		if (!await contendForLock(lockPath, deadline)) return false;
 	}
 }
 /**
+* One turn of the contention loop: break the lock if it is stale, otherwise
+* wait a beat. False means STOP — the deadline passed, or the lock cannot be
+* broken at all.
+*
+* That second case is the one worth naming. `fs.rm`'s `force` masks only
+* ENOENT and there is no `recursive`, so an entry that is not an ordinary file
+* — a `config.lock` DIRECTORY, an immutable or permission-denied file — makes
+* the removal throw every time. Swallowing that throw and looping restarted
+* the loop ABOVE the deadline check, so `aai login` (and every `--server`
+* invocation) spun in a tight async loop with no output and no exit: bounded
+* acquisition, the contract stated above, held in every case except the one
+* where breaking the lock is impossible. The removal's OUTCOME is what decides
+* whether looping is progress.
+*/
+async function contendForLock(lockPath, deadline) {
+	if (await fs.stat(lockPath).then((s) => Date.now() - s.mtimeMs).catch(() => 0) > CONFIG_LOCK_STALE_MS) return await fs.rm(lockPath, { force: true }).then(() => true, () => false) && Date.now() < deadline;
+	if (Date.now() >= deadline) return false;
+	await sleep(CONFIG_LOCK_RETRY_MS);
+	return true;
+}
+/**
 * 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

package/dist/_deploy.d.ts

@@ -1,5 +1,6 @@
+import { type ApiTestSeam } from "./_api-client.ts";
 import type { DirectoryBundleOutput } from "./_bundler.ts";
-export type DeployOpts = {
+export type DeployOpts = ApiTestSeam & {
     url: string;
     bundle: DirectoryBundleOutput;
     /** Env var values from .env to send to the server. */
@@ -14,10 +15,6 @@ export type DeployOpts = {
      * by the studio's own in-guest deploy, not by ordinary users.
      */
     allowPreviewSlug?: boolean;
-    /** Retry delay override for tests (0 = no real sleeps on retry paths). */
-    retryDelay?: number;
-    /** Optional fetch implementation for testing. Defaults to globalThis.fetch. */
-    fetch?: typeof globalThis.fetch;
 };
 export type DeployResult = {
     slug: string;

package/dist/_dev-restart.d.ts

@@ -31,7 +31,12 @@ export type RestartOps<S> = {
      * swallowed so one leak can't strand the others.
      */
     teardown?: () => Promise<void>;
-    /** Injectable so retry specs don't sleep real wall-clock. */
+    /**
+     * Injectable so retry specs need neither wall-clock nor fake timers. The
+     * default is the repo's one `sleep`, which virtual time CAN drive — this seam
+     * predates it and existed because `node:timers/promises` cannot be driven at
+     * all (see `aai/sdk/sleep.ts`).
+     */
     sleep?: (ms: number) => Promise<void>;
 };
 export type RestartSupervisor<S> = {