@alexkroman1/aai-cli 13.2.0 → 14.0.0

package/dist/scaffold/CLAUDE.md

@@ -77,7 +77,8 @@ The fast loop: edit → `pnpm dev` (browser, talk to it) →
    you stopped talking, barge-in, two sentences merging into one turn. Those
    need `pnpm dev` and your own voice.
 4. **Run `pnpm build` before declaring done** — bundles `agent.ts`,
-   type-checks, and validates the manifest. Catches issues `dev` won't.
+   type-checks, validates the manifest, and runs the WHOLE spec suite first.
+   Catches issues `dev` won't.
 5. **Make small, focused changes** — verify each one before stacking the
    next.
 6. **Look at templates before writing custom code** — the CLI ships working
@@ -109,6 +110,7 @@ npx @alexkroman1/aai-cli init             # Scaffold a new agent
 npx @alexkroman1/aai-cli templates        # List available templates
 npx @alexkroman1/aai-cli dev              # Start local dev server
 npx @alexkroman1/aai-cli test             # Run agent.test.ts via vitest
+npx @alexkroman1/aai-cli test --all       # ...or every spec in the project
 npx @alexkroman1/aai-cli eval             # Run agent.eval.test.ts against a model
 npx @alexkroman1/aai-cli build            # Bundle and validate
 npx @alexkroman1/aai-cli deploy           # Deploy to production
@@ -122,6 +124,13 @@ The scaffold's `package.json` exposes `dev`, `build`, `test`, `eval` and
 `deploy` as `pnpm <name>` shortcuts. Other commands (`init`, `templates`,
 `delete`, `secret`) are CLI-only.
 
+**`aai test` targets `agent.test.ts` and nothing else**, which `--all` widens.
+What matters is that a narrowed run does not report itself as a pass: when the
+project holds spec files the run did not cover, it FAILS and names them rather
+than printing a green line that says nothing about `tools/*.test.ts`. `pnpm
+test` (the scaffold's own script) already runs the whole suite, and so does the
+gate in front of `aai build`.
+
 ## Running it yourself (`npm start`)
 
 `server.mjs` serves this agent from a plain Node process — no platform
@@ -416,14 +425,14 @@ below.
 
 ### Workflow bodies live in `workflows/`
 
-A body is an ordinary exported async function of its input and a `WorkflowCtx`.
+A body is an ordinary exported async function of its input and a `WorkflowContext`.
 There is no directive and no compile step of its own — the agent bundle compiles
 `workflows/` like any other source file — and durability is a method call:
 
 ```ts
-import type { WorkflowCtx } from "@alexkroman1/aai";
+import type { WorkflowContext } from "@alexkroman1/aai";
 
-export async function digestFlow(input: { url: string }, ctx: WorkflowCtx) {
+export async function digestFlow(input: { url: string }, ctx: WorkflowContext) {
   const digest = await ctx.step("summarize", () => summarize(input.url));
 
   // Suspended, not blocked: the container is free to exit here and the run
@@ -515,11 +524,11 @@ The three undurable reads a body most often wants, each journaled — read once
 the first reach, and the same value on every later walk:
 
 ```ts
-import type { WorkflowCtx } from "@alexkroman1/aai";
+import type { WorkflowContext } from "@alexkroman1/aai";
 
 declare function charge(amount: number, idempotencyKey: string, jitter: number): Promise<void>;
 
-export async function chargeFlow(input: { amount: number }, ctx: WorkflowCtx) {
+export async function chargeFlow(input: { amount: number }, ctx: WorkflowContext) {
   const startedAt = await ctx.now(); // epoch ms, decided once
   const idempotencyKey = await ctx.uuid(); // still the same id after a crash
   const jitter = await ctx.random(); // one float in [0, 1), journaled per call
@@ -601,6 +610,22 @@ Five things worth knowing:
   which is how a "send it now" tool cuts a scheduled wait short. Naming no ids
   wakes every outstanding SLEEP and deliberately not a `waitFor` deadline, so
   cutting a schedule short cannot also close an approval window.
+- **A SUSPEND is not free, so `ctx.sleep` is not a `setTimeout`.** A wait costs
+  a journal write to record it, a queued delivery to bring the run back, and a
+  fresh WALK of the body — measured on a deployed agent at roughly a second of
+  overhead around the sleep itself, on top of whatever you asked for. There is a
+  cliff at the bottom of the range worth knowing about: a sleep shorter
+  than the round trip that records it never suspends AT ALL — `ctx.sleep("beat",
+  100)` and `ctx.sleep("beat", 0)` are both simply free — while anything longer
+  pays the whole cost. Measured, `nap(100)` and `nap(0)` came back within 30 ms
+  of each other on a run whose total was 2.1 s.
+
+  So a sub-second pause is not what this is for. For a short backoff inside a
+  step, use an ordinary timer (`sleep` from `@alexkroman1/aai/internal`) — a step
+  body may not call `ctx.sleep` anyway, and the engine refuses one that does. Use
+  `ctx.sleep` for a wait you want to SURVIVE the process, which is the thing a
+  timer cannot do. A body that polls in a loop pays the suspend per iteration,
+  which is the strongest argument for the next section: park on the callback.
 
 #### A third-party callback is an OPTIMIZATION over a reconciling read
 
@@ -656,15 +681,15 @@ trap somebody has already paid for:
 Steps are ordinary exported functions, so a spec imports and calls them. The
 BODY needs an engine, and there are two, for two different questions.
 
-**"What did the body ask for?"** — `createWorkflowCtx` from
+**"What did the body ask for?"** — `createWorkflowContext` from
 `@alexkroman1/aai/testing`. It runs the steps and records the names, the retry
 policies and the sleeps, over one walk with no journal. Nothing replays, so a
 spec built on it must not claim to test durability.
 
 ```ts no-check
-import { createWorkflowCtx } from "@alexkroman1/aai/testing";
+import { createWorkflowContext } from "@alexkroman1/aai/testing";
 
-const ctx = createWorkflowCtx({ runSteps: false });
+const ctx = createWorkflowContext({ runSteps: false });
 await digestFlow({ url: "https://example.com/a" }, ctx);
 
 expect(ctx.steps.map((s) => s.name)).toEqual(["fetchArticle", "summarize", "file"]);
@@ -729,7 +754,7 @@ root barrel would drag the whole SDK into that bundle.
 
 ```ts
 import { stepEnv } from "@alexkroman1/aai/step";
-import { stepGenerateClassified } from "@alexkroman1/aai/step-errors";
+import { stepGenerateOrFail } from "@alexkroman1/aai/step-errors";
 
 async function summarize(text: string) {
   // The agent's env by name — the same values a tool reads from `ctx.env`.
@@ -737,7 +762,7 @@ async function summarize(text: string) {
   const style = stepEnv("DIGEST_STYLE") ?? "plain";
 
   // One model call, on the agent's own ASSEMBLYAI_API_KEY and default model.
-  return await stepGenerateClassified(`${style} summary of:\n\n${text}`, {
+  return await stepGenerateOrFail(`${style} summary of:\n\n${text}`, {
     system: "Reply with two sentences and nothing else.",
   });
 }
@@ -749,9 +774,9 @@ before and after a deploy. List what you read in `requiredEnv` and a deploy
 checks it for you. And **`stepGenerate` is not `ctx.generate`**: it is one
 request to the AssemblyAI LLM Gateway, with no tools and no structured output,
 because bundling the AI SDK into a step artifact costs megabytes on every
-deploy. Use `stepGenerateJsonClassified` with a Zod `schema` if you need a shape.
+deploy. Use `stepGenerateJsonOrFail` with a Zod `schema` if you need a shape.
 
-### From a step, reach for the `Classified` call
+### From a step, reach for the `OrFail` call
 
 `@alexkroman1/aai/step-errors` publishes a wrapper for every `/step` call that
 can fail against a remote service, and **inside a step the wrapper is the one to
@@ -759,14 +784,14 @@ use**:
 
 | Raw, on `@alexkroman1/aai/step` | Use this instead, on `@alexkroman1/aai/step-errors` |
 | --- | --- |
-| `stepGenerate` | `stepGenerateClassified` |
-| `stepGenerateJson` | `stepGenerateJsonClassified` |
-| `stepFetch` | `stepFetchOk` |
-| `stepTranscribeSync` | `stepTranscribeSyncClassified` |
-| `stepTranscribeUpload` / `Submit` / `Poll` | the matching `*Classified` |
-| `sendToChannel` (`/channels`) | `sendToChannelClassified` |
-
-`stepFetchOk` is the one that is not spelled `*Classified`, and the name is the
+| `stepGenerate` | `stepGenerateOrFail` |
+| `stepGenerateJson` | `stepGenerateJsonOrFail` |
+| `stepFetch` | `stepFetchOrFail` |
+| `stepTranscribeSync` | `stepTranscribeSyncOrFail` |
+| `stepTranscribeUpload` / `Submit` / `Poll` | the matching `*OrFail` |
+| `sendToChannel` (`/channels`) | `sendToChannelOrFail` |
+
+`stepFetchOrFail` is the one that is not spelled `*OrFail`, and the name is the
 difference: the others turn an already-thrown failure into a classified one,
 while this also turns a NON-2XX RESPONSE into a throw — `stepFetch` resolves
 with a `404` rather than raising it. Two changes, so two names.
@@ -804,7 +829,7 @@ bundling rule as `/step` — import them there, never through the root barrel:
   recording, or `stepTranscribeUpload` → `stepTranscribeSubmit` →
   `stepTranscribePoll` for a long one, plus `Transcript`, `TranscribeError` and
   the `TRANSCRIBE_*` limits. (There is no `/transcribe` subpath; transcription
-  lives on `/step` with the other step primitives.) Use the `Classified`
+  lives on `/step` with the other step primitives.) Use the `OrFail`
   wrappers above: a provider refusal — a container it will not read, a
   recording with no speech — arrives
   with `retryable: false`, and unclassified a step re-uploads the same bytes
@@ -841,19 +866,19 @@ export async function measure(uploadId: string) {
 
 A run that finishes while nobody is on the line needs somewhere to put the
 result. `slackChannel({ webhookUrl })` names a destination and
-`sendToChannelClassified(channel, message)` posts to it:
+`sendToChannelOrFail(channel, message)` posts to it:
 
 ```ts no-check
 import { type ChannelMessage, slackChannel } from "@alexkroman1/aai/channels";
 import { requireStepEnv } from "@alexkroman1/aai/step";
-import { sendToChannelClassified } from "@alexkroman1/aai/step-errors";
+import { sendToChannelOrFail } from "@alexkroman1/aai/step-errors";
 
 export async function announce(headline: string, points: string[]) {
   const message: ChannelMessage = {
     text: headline,
     sections: points.map((point) => ({ text: point })),
   };
-  return await sendToChannelClassified(slackChannel({ webhookUrl: requireStepEnv("SLACK_WEBHOOK_URL") }), message);
+  return await sendToChannelOrFail(slackChannel({ webhookUrl: requireStepEnv("SLACK_WEBHOOK_URL") }), message);
 }
 ```
 
@@ -862,7 +887,7 @@ it with `aai secret put`. A channel's credential is its DESTINATION and is
 passed in, which is why no channel reads an env var of its own. `ChannelMessage`
 is rendered per platform, so the same message is legal on a channel kind added
 later; `isSlackWebhookUrl` / `isSlackWorkflowTriggerUrl` validate a pasted URL
-before a run depends on it, and `channelAdvice` turns a refusal into a sentence
+before a run depends on it, and `explainChannelFailure` turns a refusal into a sentence
 a person can act on. `podcast-digest` is the worked example.
 
 ### A step's HTTP: use `stepFetch`, not `fetch`
@@ -941,11 +966,11 @@ Both are on `@alexkroman1/aai/step`, and `spoken-summary` is the template that
 shows the whole round trip.
 
 ```ts
-import { stepSpeak, writeUpload } from "@alexkroman1/aai/step";
+import { stepSpeak, stepWriteUpload } from "@alexkroman1/aai/step";
 
 export async function narrate(script: string) {
   const spoken = await stepSpeak(script, { voice: "jane" });
-  const stored = await writeUpload(spoken.audio, { name: "summary.wav", type: "audio/wav" });
+  const stored = await stepWriteUpload(spoken.audio, { name: "summary.wav", type: "audio/wav" });
   return { audio: stored.id, durationMs: spoken.durationMs };
 }
 ```
@@ -962,11 +987,13 @@ opens and produces silence rather than an error. The `AssemblyAITtsVoice` type
 gives you autocomplete over it and nothing more: it accepts any string, so that
 a voice the service adds after this release still compiles.
 
-**`writeUpload` is `readUpload`'s other direction, and you need it.** A run's
-output is read back as JSON, so audio cannot travel in one — the same rule that
-keeps an uploaded recording's bytes out of a run's INPUT, arriving at the other
-end of the run. Store the bytes, return the **id**, and let the page fetch it
-with `api.download(id)`.
+**`stepWriteUpload` is `stepReadUpload`'s other direction, and you need it.** A
+run's output is read back as JSON, so audio cannot travel in one — the same rule
+that keeps an uploaded recording's bytes out of a run's INPUT, arriving at the
+other end of the run. Store the bytes, return the **id**, and let the page fetch
+it with `api.download(id)`. A step that wants the record rather than the bytes
+reads it with `stepUploadInfo(id)`, which answers an `UploadInfo` — the name,
+the size stored so far, and whether that is all of it.
 
 Three rules come with it:
 
@@ -1020,12 +1047,13 @@ naming a shape is what asks the compiler to make you handle the failure.
 
 ### The page
 
-A workflow app's `client.tsx` mounts with `page()` rather than `client()` —
-there is no session to build, so no socket, no audio graph and no microphone
-request. Everything else is the same file, React and Tailwind included.
+A workflow app's `client.tsx` mounts with `mountPage()` rather than
+`mountClient()` — there is no session to build, so no socket, no audio graph
+and no microphone request. Everything else is the same file, React and
+Tailwind included.
 
 ```tsx no-check
-import { createWorkflowApi, page, useWorkflowRun } from "@alexkroman1/aai-ui";
+import { createWorkflowApi, mountPage, useWorkflowRun } from "@alexkroman1/aai-ui";
 import "@alexkroman1/aai-ui/styles.css";
 import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import { useState } from "react";
@@ -1053,7 +1081,7 @@ export function App() {
   );
 }
 
-page({ name: "Link Digest", component: App });
+mountPage({ name: "Link Digest", component: App });
 ```
 
 `api.start()` resolves as soon as the RUN EXISTS, not when it finishes — that
@@ -1172,7 +1200,7 @@ statement about pipeline mode, not about the SDK.
 ### Answering a phone call
 
 A deployed voice agent already serves carrier media streams — there is nothing
-to switch on. `createServer` mounts `WS /phone` whenever the agent is a voice
+to switch on. `createRuntimeServer` mounts `WS /phone` whenever the agent is a voice
 agent (`telephony` defaults to `true`, and to `false` for a `page: "static"`
 workflow app, which has no stages to put on a call). Point the carrier at it
 with a `carrier` query parameter naming who is dialling:
@@ -1188,7 +1216,7 @@ the bridge transcodes in both directions, so the agent, its tools and its slots
 behave exactly as they do in the browser — a phone call is a transport, not a
 mode. Nothing about `agent.ts` changes to support one.
 
-Turn the route off with `telephony: false` on `createServer`. If you are
+Turn the route off with `telephony: false` on `createRuntimeServer`. If you are
 embedding the runtime yourself rather than deploying, the pieces are
 `createTelephonyBridge`, `startTelephonySession`, `TELEPHONY_PATH` and
 `carrierByName`, all on `@alexkroman1/aai-runtime`.
@@ -1268,12 +1296,12 @@ API keys require it; the US endpoints reject them. Example:
 | Factory         | SDK package         | Env var                        |
 | --------------- | ------------------- | ------------------------------ |
 | `anthropicLlm`  | `@ai-sdk/anthropic` | `ANTHROPIC_API_KEY`            |
-| `openaiLlm`     | `@ai-sdk/openai`    | `OPENAI_API_KEY`               |
+| `openAILlm`     | `@ai-sdk/openai`    | `OPENAI_API_KEY`               |
 | `googleLlm`     | `@ai-sdk/google`    | `GOOGLE_GENERATIVE_AI_API_KEY` |
 | `mistralLlm`    | `@ai-sdk/mistral`   | `MISTRAL_API_KEY`              |
-| `xaiLlm`        | `@ai-sdk/xai`       | `XAI_API_KEY`                  |
+| `xAILlm`        | `@ai-sdk/xai`       | `XAI_API_KEY`                  |
 | `groqLlm`       | `@ai-sdk/groq`      | `GROQ_API_KEY`                 |
-| `openrouterLlm` | `@ai-sdk/openai`    | `OPENROUTER_API_KEY`           |
+| `openRouterLlm` | `@ai-sdk/openai`    | `OPENROUTER_API_KEY`           |
 | `gatewayLlm`    | `ai` (built in)     | `AI_GATEWAY_API_KEY`           |
 | `assemblyAILlm` | `@ai-sdk/openai`    | `ASSEMBLYAI_API_KEY`           |
 
@@ -1283,10 +1311,10 @@ shared by all of them except `assemblyAILlm`. Example:
 because a third-party vendor's catalog is not this SDK's to default from;
 `assemblyAILlm()` is the one bare call, since it has a default model.
 
-`openrouterLlm` routes through [OpenRouter](https://openrouter.ai) — an
+`openRouterLlm` routes through [OpenRouter](https://openrouter.ai) — an
 OpenAI-compatible endpoint fronting hundreds of models addressed as
 `"creator/model"`, e.g.
-`openrouterLlm({ model: "meta-llama/llama-3.3-70b-instruct" })`. It needs
+`openRouterLlm({ model: "meta-llama/llama-3.3-70b-instruct" })`. It needs
 no extra SDK install (it reuses the `@ai-sdk/openai` client).
 
 `gatewayLlm` routes through the [Vercel AI
@@ -1947,7 +1975,7 @@ Those three cover almost everything an agent wants. A database is for data that
 must outlive a session AND be queryable: a ledger, filed records, cross-session
 saves.
 
-## Custom UI — `client()`
+## Custom UI — `mountClient()`
 
 File: `client.tsx` alongside `agent.ts`. Uses **React** (not Preact).
 Always import `"@alexkroman1/aai-ui/styles.css"` first.
@@ -1957,9 +1985,9 @@ Always import `"@alexkroman1/aai-ui/styles.css"` first.
 ```tsx
 /// <reference types="vite/client" />
 import "@alexkroman1/aai-ui/styles.css";
-import { client } from "@alexkroman1/aai-ui";
+import { mountClient } from "@alexkroman1/aai-ui";
 
-client({ name: "My Agent" });
+mountClient({ name: "My Agent" });
 ```
 
 ### Tier 1 with sidebar
@@ -1967,7 +1995,7 @@ client({ name: "My Agent" });
 ```tsx
 /// <reference types="vite/client" />
 import "@alexkroman1/aai-ui/styles.css";
-import { client, useEvent } from "@alexkroman1/aai-ui";
+import { mountClient, useEvent } from "@alexkroman1/aai-ui";
 import { useState } from "react";
 
 function Sidebar() {
@@ -1982,7 +2010,7 @@ function Sidebar() {
   );
 }
 
-client({ name: "My Agent", sidebar: Sidebar });
+mountClient({ name: "My Agent", sidebar: Sidebar });
 ```
 
 ### Tier 2 — full custom component
@@ -1990,7 +2018,7 @@ client({ name: "My Agent", sidebar: Sidebar });
 ```tsx
 /// <reference types="vite/client" />
 import "@alexkroman1/aai-ui/styles.css";
-import { client, useSession } from "@alexkroman1/aai-ui";
+import { mountClient, useSession } from "@alexkroman1/aai-ui";
 
 function MyApp() {
   const { messages, userTranscript, started, running, start, toggle, end } =
@@ -2011,10 +2039,10 @@ function MyApp() {
   );
 }
 
-client({ component: MyApp });
+mountClient({ component: MyApp });
 ```
 
-### `client()` config
+### `mountClient()` config
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -2172,7 +2200,7 @@ Property 'children' is missing` build error:
 ```tsx
 /// <reference types="vite/client" />
 import "@alexkroman1/aai-ui/styles.css";
-import { ChatView, client, StartScreen } from "@alexkroman1/aai-ui";
+import { ChatView, mountClient, StartScreen } from "@alexkroman1/aai-ui";
 
 function PizzaApp() {
   return (
@@ -2182,7 +2210,7 @@ function PizzaApp() {
   );
 }
 
-client({ component: PizzaApp });
+mountClient({ component: PizzaApp });
 ```
 
 ## Styling
@@ -2190,7 +2218,7 @@ client({ component: PizzaApp });
 - **Tailwind CSS v4** — compiled at bundle time, configured via CSS.
   Do NOT create `tailwind.config.js` — it will be ignored.
 - Use Tailwind classes for layout, `useTheme()` for dynamic colors.
-- Set theme: `client({ theme: { bg, primary, text, surface, border } })`.
+- Set theme: `mountClient({ theme: { bg, primary, text, surface, border } })`.
 - Override CSS custom properties for extra tokens:
   `--color-aai-*`, `--radius-aai`, `--font-aai`.
 - Always import `"@alexkroman1/aai-ui/styles.css"` at the top of `client.tsx`.

package/dist/scaffold/package.json

@@ -9,14 +9,15 @@
     "prestart": "aai build --skip-tests",
     "start": "node server.mjs",
     "build": "aai build",
-    "test": "aai test",
+    "test": "vitest run --exclude \"**/*.eval.test.*\"",
+    "test:agent": "aai test",
     "eval": "aai eval",
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^13.2.0",
-    "@alexkroman1/aai-runtime": "^13.2.0",
-    "@alexkroman1/aai-ui": "^13.2.0",
+    "@alexkroman1/aai": "^14.0.0",
+    "@alexkroman1/aai-runtime": "^14.0.0",
+    "@alexkroman1/aai-ui": "^14.0.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.0.0",
@@ -24,7 +25,7 @@
     "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^13.2.0",
+    "@alexkroman1/aai-cli": "^14.0.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.4.1",
     "@types/react": "^19.2.18",

package/dist/scaffold/server.mjs

@@ -122,6 +122,71 @@ function resolveClientDir() {
   return defaultClientDir();
 }
 
+/**
+ * The error classes that mean a DEFECT in this code rather than a mistake in
+ * the configuration.
+ *
+ * Everything below turns a boot failure into two lines and a non-zero exit,
+ * which is right for "ASSEMBLYAI_API_KEY is not set" and wrong for a
+ * `TypeError`, where the traceback is the only thing that can locate the bug.
+ * Those are re-thrown untouched.
+ */
+const BUG_ERRORS = [TypeError, ReferenceError, RangeError, SyntaxError];
+
+/**
+ * Every distinct message on an error and its `cause` chain, outermost first.
+ *
+ * A driver failure states the useful half one hop down — `connect to database
+ * failed: getaddrinfo ENOTFOUND db` — so printing only the top message is how a
+ * tidy envelope ends up less informative than the stack it replaced.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function errorText(err) {
+  /** @type {string[]} */
+  const messages = [];
+  /** @type {unknown} */
+  let cursor = err;
+  while (cursor instanceof Error) {
+    if (cursor.message !== "" && !messages.includes(cursor.message)) messages.push(cursor.message);
+    cursor = cursor.cause;
+  }
+  return messages.length > 0 ? messages.join(": ") : String(err);
+}
+
+/**
+ * Run one step of BOOT, and answer a failure the way this file already answers
+ * a missing build artifact: what is wrong, then what to do, then exit 1.
+ *
+ * Without this, a missing provider key — the commonest way a first `npm start`
+ * fails — killed the process with a ten-frame traceback pointing into
+ * `node_modules/@alexkroman1/aai-runtime/dist/host-env-*.js`. The MESSAGE was
+ * already good ("AssemblyAI LLM: missing API key. Set ASSEMBLYAI_API_KEY in the
+ * agent env."); what it arrived wrapped in was a crash report about somebody
+ * else's bundle, in a container that then restarted and did it again.
+ *
+ * Exiting is deliberate rather than binding anyway and serving an unhealthy
+ * `/health`: a process that stays up tells an orchestrator it started, and a
+ * misconfigured deployment that reports itself healthy is worse than one that
+ * refuses to run. The non-zero exit is what a supervisor, a `docker run`, and
+ * CI all already read.
+ *
+ * @template T
+ * @param {string} fix - What the operator should change, in one sentence.
+ * @param {() => T | Promise<T>} work
+ * @returns {Promise<T>}
+ */
+async function bootOrExit(fix, work) {
+  try {
+    return await work();
+  } catch (err) {
+    if (BUG_ERRORS.some((kind) => err instanceof kind)) throw err;
+    console.error(`Cannot start the agent: ${errorText(err)}\n${fix}`);
+    process.exit(1);
+  }
+}
+
 const env = await resolveAgentEnv();
 
 /**
@@ -152,38 +217,77 @@ const publicUrl = process.env.PUBLIC_URL?.trim();
  * Best-effort: if a real migration already created them and this role may not
  * CREATE, it warns and the server starts anyway.
  */
-if (env.DATABASE_URL) {
-  await ensureSessionStateSchema({ url: env.DATABASE_URL, logger: console });
-  // And the durable-run journal's, which is a separate set of tables owned by
-  // the same deployment. Without it a project with a `DATABASE_URL` boots
-  // claiming durable runs and fails on the first one.
-  await ensureWorkflowJournalSchema({ url: env.DATABASE_URL, logger: console });
+// Read into a const: `env.DATABASE_URL` is a record lookup, so its narrowing
+// does not survive into the callback below.
+const databaseUrl = env.DATABASE_URL;
+if (databaseUrl) {
+  await bootOrExit(
+    "Check DATABASE_URL: this server has to reach that database at boot to create the tables it owns.",
+    async () => {
+      await ensureSessionStateSchema({ url: databaseUrl, logger: console });
+      // And the durable-run journal's, which is a separate set of tables owned
+      // by the same deployment. Without it a project with a `DATABASE_URL`
+      // boots claiming durable runs and fails on the first one.
+      await ensureWorkflowJournalSchema({ url: databaseUrl, logger: console });
+    },
+  );
+} else {
+  /**
+   * Say that this process is the only place the state lives, because the next
+   * thing an operator does with a container is run two of them.
+   *
+   * Session state (slots, the event log) is keyed by session id and held in
+   * memory here — the boot line below reports it as `sessionState: { backend:
+   * 'memory', durable: false }`, which is true and easy to read as being about
+   * restarts alone. It is also about REPLICAS: the browser reconnects with
+   * `?sessionId=<id>`, so a reconnect that lands on a different process resumes
+   * a session that process has never heard of and the agent's context is gone
+   * mid-call. One replica has no such problem, which is exactly why nothing
+   * catches this until the deployment grows a second one.
+   */
+  console.warn(
+    "No DATABASE_URL: session state and durable runs live in THIS process's memory.\n" +
+      "One replica is fine. Behind a load balancer, enable sticky sessions so a reconnect " +
+      "(the client re-dials with ?sessionId=) reaches the same process — or set DATABASE_URL " +
+      "and let every replica share the state.",
+  );
 }
 
-const server = createAgentServer({
-  agent,
-  env,
-  // Provider credentials may ALSO arrive straight from the environment without
-  // being declared, and without becoming ctx.env — the ordinary way to hand
-  // ASSEMBLYAI_API_KEY to a container. Anything in `env` still wins.
-  providerEnv: withHostCredentialFallback(env),
-  clientDir: resolveClientDir(),
-  ...(publicUrl ? { publicUrl } : {}),
-  // Durable workflows need nothing passed here. A `DATABASE_URL` in `env` puts
-  // the runs in Postgres and they survive a restart; without one they live in a
-  // per-process directory and do not, which is the same trade `aai dev` makes.
-  //
-  // Two options used to sit here — the compiled workflow surface, carried on the
-  // bundle as `__aaiWorkflowCode`/`__aaiStepCode` because a `"use workflow"` body
-  // had to go through a compiler at BUILD time. The engine reads the agent's own
-  // `workflows` declaration instead, so there is no artifact to hand over.
-});
+const server = await bootOrExit(
+  // The commonest first-run failure, and the one whose stack this replaces: a
+  // provider credential that is not there. `.env` is what `aai dev` reads too,
+  // so the fix is the same one in both places.
+  "Set the missing value in .env, or pass it as a real environment variable (`docker run -e NAME=value`), then start again.",
+  () =>
+    createAgentServer({
+      agent,
+      env,
+      // Provider credentials may ALSO arrive straight from the environment without
+      // being declared, and without becoming ctx.env — the ordinary way to hand
+      // ASSEMBLYAI_API_KEY to a container. Anything in `env` still wins.
+      providerEnv: withHostCredentialFallback(env),
+      clientDir: resolveClientDir(),
+      ...(publicUrl ? { publicUrl } : {}),
+      // Durable workflows need nothing passed here. A `DATABASE_URL` in `env` puts
+      // the runs in Postgres and they survive a restart; without one they live in a
+      // per-process directory and do not, which is the same trade `aai dev` makes.
+      //
+      // Two options used to sit here — the compiled workflow surface, carried on the
+      // bundle as `__aaiWorkflowCode`/`__aaiStepCode` because a `"use workflow"` body
+      // had to go through a compiler at BUILD time. The engine reads the agent's own
+      // `workflows` declaration instead, so there is no artifact to hand over.
+    }),
+);
 
 // Loopback by default: this server has no request authentication of its own,
 // so exposing it is a deliberate act. Set HOST=0.0.0.0 to bind every interface
 // behind your own proxy or auth. An empty HOST means unset, not "everything".
 const host = process.env.HOST?.trim() || undefined;
-await server.listen(Number(process.env.PORT ?? 3000), host);
+const port = Number(process.env.PORT ?? 3000);
+await bootOrExit(
+  `Nothing is listening yet — port ${port} is in use, or this process may not bind it. Set PORT to a free one.`,
+  () => server.listen(port, host),
+);
 console.log(`${agent.name} listening on http://${host ?? "127.0.0.1"}:${server.port}`);
 
 for (const signal of ["SIGINT", "SIGTERM"]) {