@alexkroman1/aai-cli 10.0.0 → 11.0.0

package/dist/{client-bundler-CWnG42cU.mjs → client-bundler-j5c46x0G.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { o as errorMessage$1, s as fileExists } from "./_utils-B8QmtFhK.mjs";
-import { n as withPreservedNodeEnv, t as DEDUPED_PEERS } from "./_vite-env-BNveawd1.mjs";
+import { n as withPreservedNodeEnv, t as DEDUPED_PEERS } from "./_vite-env-D9Qj6KPX.mjs";
 import { existsSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { omitUndefined } from "@alexkroman1/aai/utils";
@@ -82,7 +82,8 @@ const DEFAULT_OUT_DIR = ".aai/client";
 * API and not covered by semver.
 */
 async function buildClient(cwd, opts = {}) {
-	if (!await fileExists(path.join(cwd, "client.tsx"))) return {};
+	const clientEntry = path.join(cwd, "client.tsx");
+	if (!await fileExists(clientEntry)) return {};
 	const outDir = opts.outDir ?? DEFAULT_OUT_DIR;
 	const clientDir = path.join(cwd, outDir);
 	let cleanupHtml = () => {};

package/dist/client-bundler.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { t as buildClient } from "./client-bundler-CWnG42cU.mjs";
+import { t as buildClient } from "./client-bundler-j5c46x0G.mjs";
 export { buildClient };

package/dist/{deploy-CchW5pmw.mjs → deploy-BzZ-r4iM.mjs}

@@ -3,10 +3,11 @@ import { a as ok } from "./_output-CKkmWs7i.mjs";
 import { n as log, r as notify, t as fmtUrl } from "./_ui-u7T4YooX.mjs";
 import { o as errorMessage$1 } from "./_utils-B8QmtFhK.mjs";
 import { s as updateProjectConfig } from "./_config-CmJOFsAP.mjs";
-import { i as evalWorkerConfig, t as buildAgentBundle } from "./_bundler-B31MqYaD.mjs";
+import { i as evalWorkerConfig, t as buildAgentBundle } from "./_bundler-C31rlcYz.mjs";
 import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
 import { a as resolveDeployTarget } from "./_agent-BTwZJu4P.mjs";
 import { assertTypechecks } from "./_typecheck-gate-BXvUNnfs.mjs";
+import { n as scanWorkflowDeterminism, t as determinismWarnings } from "./_workflow-determinism-f9J-5Zlj.mjs";
 import { d as apiTestSeam, f as checkedResponse, i as projectNameFromDir, u as apiRequest } from "./_studio-B1waXMuR.mjs";
 import { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { gzipSync } from "node:zlib";
@@ -19,7 +20,7 @@ async function runDeploy(opts) {
 		worker: opts.bundle.worker,
 		clientFiles: opts.bundle.clientFiles
 	}));
-	return checkedResponse(await apiRequest(`${opts.url}/deploy`, {
+	const data = await apiRequest(`${opts.url}/deploy`, {
 		method: "POST",
 		body,
 		headers: {
@@ -31,7 +32,8 @@ async function runDeploy(opts) {
 		hints: { 413: "Your bundle is too large. Try reducing dependencies or splitting your agent." },
 		...opts.slug ? {} : { retry: 0 },
 		...apiTestSeam(opts)
-	}), (value) => isRecord(value) && typeof value.slug === "string", `the deploy route at ${opts.url}`);
+	});
+	return checkedResponse(data, (value) => isRecord(value) && typeof value.slug === "string", `the deploy route at ${opts.url}`);
 }
 //#endregion
 //#region deploy.ts
@@ -49,7 +51,7 @@ async function executeDeploy(opts) {
 	const { missingCredentialMessage, missingCredentials } = await preflightModule;
 	const config = await evalWorkerConfig(bundle.worker);
 	const missing = config ? missingCredentials(config, uploadEnv) : [];
-	const warnings = missing.length > 0 ? [missingCredentialMessage(missing)] : [];
+	const warnings = [...missing.length > 0 ? [missingCredentialMessage(missing)] : [], ...determinismWarnings(await scanWorkflowDeterminism(cwd))];
 	for (const warning of warnings) notify("warn", warning);
 	log.step(`Deploying${slug ? ` ${slug}` : ""}…`);
 	const deployed = await runDeploy({

package/dist/{dev-BfVl1uBA.mjs → dev-BDykFvcc.mjs}

@@ -12,7 +12,7 @@ import { styleText } from "node:util";
 async function executeDev(opts) {
 	const port = parsePort(opts.port);
 	const agentName = path.basename(path.resolve(opts.cwd));
-	const { startDevServer } = await import("./_dev-server-Bo5dSBzQ.mjs");
+	const { startDevServer } = await import("./_dev-server-DWvkNoIS.mjs");
 	let cleanup;
 	let shuttingDown = false;
 	const onSignal = () => {

package/dist/{eval-DwNwdqmS.mjs → eval-0qEOdm0l.mjs}

@@ -2,7 +2,7 @@
 import { a as ok, n as fail } from "./_output-CKkmWs7i.mjs";
 import { n as log } from "./_ui-u7T4YooX.mjs";
 import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
-import { classifyVitestError, runVitest } from "./test-CvwgeVSQ.mjs";
+import { classifyVitestError, runVitest } from "./test-CiLab-AA.mjs";
 //#region eval.ts
 /**
 * `aai eval` — run the agent's behaviour evals via vitest.

package/dist/{init-BRfoc2EK.mjs → init-BtJI306C.mjs}

@@ -106,7 +106,7 @@ function collectWarnings() {
 }
 /** Publish after init and return deploy metadata if successful. */
 async function tryPublish(cwd, server, warn) {
-	const { executePublish } = await import("./studio-wVWNLREn.mjs");
+	const { executePublish } = await import("./studio-BxAS_FQQ.mjs");
 	try {
 		const result = await executePublish({
 			cwd,

package/dist/{login-BBuM1sxH.mjs → login-DeUETobb.mjs}

@@ -32,7 +32,10 @@ const LINK_POLL_INTERVAL_MS = 2e3;
 const LINK_TIMEOUT_MS = 3e5;
 async function jsonBody(res, what) {
 	const body = await res.json().catch(() => null);
-	if (!res.ok) throw new CliError("login_failed", `${what} failed: ${body?.error ?? body?.msg ?? `HTTP ${res.status}`}`);
+	if (!res.ok) {
+		const detail = body?.error ?? body?.msg ?? `HTTP ${res.status}`;
+		throw new CliError("login_failed", `${what} failed: ${detail}`);
+	}
 	if (body === null) throw new CliError("login_failed", `${what} returned an invalid response`);
 	return body;
 }

package/dist/scaffold/CLAUDE.md

@@ -428,7 +428,10 @@ export async function digestFlow(input: { url: string }, ctx: WorkflowCtx) {
 
   // Suspended, not blocked: the container is free to exit here and the run
   // resumes when it comes due. Six hours works the same as ten seconds.
-  await ctx.sleep(10_000);
+  //
+  // The first argument NAMES the wait, exactly as a step's name does, and for
+  // the same reason: it is the wait's identity in the journal.
+  await ctx.sleep("settle", 10_000);
 
   const filedAt = await ctx.step("file", () => file(digest));
   return { ...digest, filedAt };
@@ -455,8 +458,10 @@ them:
 
 - **The body replays from the top on every resume**, so it holds no live handle
   and makes no undurable decision — no `Date.now()`, no `Math.random()`, no
-  `crypto.randomUUID()`, no `fetch`. Those go inside a `ctx.step`, whose result
-  is journaled and returned unchanged on replay.
+  `crypto.randomUUID()`, no `fetch`. The three commonest have methods of their
+  own (`ctx.now()`, `ctx.random()`, `ctx.uuid()` — see below); anything else goes
+  inside a `ctx.step`, whose result is journaled and returned unchanged on
+  replay.
 - **A step's arguments and return value cross a queue**, so they must be
   JSON-shaped and small. Put bytes in storage and pass the key.
 - **A step gets no tool context.** There is no `ctx.db` and no `ctx.generate`
@@ -481,6 +486,66 @@ const digest = await ctx.step("summarize", () => summarize(input.url), {
 });
 ```
 
+**And a step body can read which attempt it is on**, so a step may degrade rather
+than fail — a smaller model on the last try beats a failed run:
+
+```ts
+import { stepInfo } from "@alexkroman1/aai/step";
+
+declare function callModel(url: string, model: string): Promise<string>;
+
+export async function summarize(url: string) {
+  const step = stepInfo();
+  // `undefined` outside a run — a spec calling this directly — which reads as
+  // "not retrying", the same branch a first attempt takes.
+  const model = step?.isLastAttempt === true ? "small" : "large";
+  return await callModel(url, model);
+}
+```
+
+Read `isLastAttempt` rather than comparing `attempt` against a number you have
+written down: the ceiling lives at the `ctx.step` call site, and a body that
+restates it degrades early on every run once the two disagree — silently, since
+it still returns an answer. `stubStepInfo` from `@alexkroman1/aai/testing` is how
+a test reaches the retry branch.
+
+### A clock, a random number and a uuid: `ctx.now`, `ctx.random`, `ctx.uuid`
+
+The three undurable reads a body most often wants, each journaled — read once at
+the first reach, and the same value on every later walk:
+
+```ts
+import type { WorkflowCtx } from "@alexkroman1/aai";
+
+declare function charge(amount: number, idempotencyKey: string, jitter: number): Promise<void>;
+
+export async function chargeFlow(input: { amount: number }, ctx: WorkflowCtx) {
+  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
+
+  await ctx.step("charge", () => charge(input.amount, idempotencyKey, jitter));
+  return { elapsedMs: (await ctx.now()) - startedAt };
+}
+```
+
+`ctx.uuid()` is what an idempotency key for a downstream API wants: minted once,
+and the same value after a resume, so a retried request is recognisably the same
+request rather than a second one. `ctx.random()` draws one float per CALL, so a
+loop is correct as written; a BULK draw belongs in a step
+(`ctx.step("jitter", () => Array.from({ length: 1000 }, Math.random))`), which is
+one journal entry instead of a thousand.
+
+Two rules:
+
+- **Call them from the BODY, never inside a `ctx.step`** — the engine refuses one
+  there and the message names the fix. Inside a step there is nothing to fix: a
+  step's internals are not replayed, only its result, so a plain `Date.now()` in
+  a step body is already durable and is what to write.
+- **A `ctx.uuid()` is not a hook TOKEN.** `ctx.waitFor`'s token has to be
+  DERIVED from the run's own input, because whoever signals is usually a tool and
+  a tool cannot see the body's local variables. See below.
+
 ### Waiting: `ctx.sleep` and `ctx.waitFor`
 
 Both SUSPEND the run — the body stops, the container is free, and the engine
@@ -493,8 +558,8 @@ process. Under `aai dev` without a `DATABASE_URL` the store is memory, so a wait
 lives only as long as the dev server. The boot line reports which one is in play.
 
 ```ts no-check
-// A duration in milliseconds, or an absolute Date.
-await ctx.sleep(6 * 60 * 60 * 1000, { correlationId: "review-window" });
+// A label, then a duration in milliseconds or an absolute Date.
+await ctx.sleep("review-window", 6 * 60 * 60 * 1000, { correlationId: "review" });
 
 // Until somebody outside the run answers, via `ctx.workflows.signal(token, …)`
 // from a tool, or by a delivery to `publicWebhookUrl` — both hops reach the
@@ -505,8 +570,15 @@ const approval = await ctx.waitFor<{ approved: boolean }>(approvalToken(input.id
 if (approval === undefined) return { published: false, reason: "nobody approved" };
 ```
 
-Four things worth knowing:
+Five things worth knowing:
 
+- **A wait's NAME is its identity, exactly like a step's.** A sleep's `label` and
+  a `waitFor`'s token are what the journal keys the wait on
+  (`sleep!<label>#<occurrence>`, `hook!<token>#<occurrence>`), so make a label a
+  string literal, give two call sites two labels, and let a loop reuse one — the
+  occurrence count separates the iterations. This is what makes a wait behind an
+  `if` safe: the body can reach a different NUMBER of waits on two walks and each
+  one still finds its own record.
 - **A hook's token must be DERIVED, not random.** Whoever signals is usually a
   tool, and a tool cannot see the body's local variables — so export one function
   that computes the token from the run's own input and import it in both places.
@@ -516,10 +588,15 @@ Four things worth knowing:
 - **`timeoutMs` resolves `undefined` when the window closes unanswered.** A
   closing window is an outcome to branch on, not a failure, and the engine closes
   the hook as it shuts so a late answer cannot change what already happened.
-- **Do NOT race the two.** `Promise.race([ctx.waitFor(t), ctx.sleep(ms)])` does
-  not work: both suspend, and a suspend unwinds the stack, so the race stops the
-  body before the other side has been reached. That is why the deadline is a
-  parameter.
+- **Racing the two WORKS, and is still not how to put a deadline on a wait.** A
+  wait no longer unwinds the stack — it hands back a promise that never settles
+  — so the body reaches every wait a `race` or an `all` puts in front of it and
+  the run suspends once, on the earliest deadline among them. Reach for a race
+  when the two waits are genuinely independent (a review window beside a retry
+  backoff). For a deadline ON a wait, use `timeoutMs`: it is journaled WITH the
+  hook, so one decision fixes the window, and its timeout arm CLOSES the hook
+  before the body continues — a race has no such moment, and a signal landing
+  just after it would make the next replay answer a window this one timed out.
 - **`ctx.workflows.wakeUp(runId, { correlationIds: [id] })`** ends a sleep early,
   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
@@ -574,6 +651,75 @@ trap somebody has already paid for:
   pnpm dev` is what makes it reachable. Until you set it, treat local runs as
   coverage of the backstop only.
 
+### Testing a workflow body
+
+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
+`@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";
+
+const ctx = createWorkflowCtx({ runSteps: false });
+await digestFlow({ url: "https://example.com/a" }, ctx);
+
+expect(ctx.steps.map((s) => s.name)).toEqual(["fetchArticle", "summarize", "file"]);
+expect(ctx.steps.find((s) => s.name === "summarize")?.maxAttempts).toBe(6);
+expect(ctx.slept).toEqual([{ until: 10_000 }]);
+```
+
+**"Is the run actually durable?"** — `runWorkflow` from
+`@alexkroman1/aai-runtime/testing`. It starts the declared workflow on the real
+replay engine over an in-memory journal, one delivery at a time, with a
+suspension RECORDED rather than waited out. So a body that sleeps six hours
+costs a spec nothing, and the run really suspends, really resumes off its
+journal, and really survives a restart.
+
+```ts no-check
+import { runWorkflow } from "@alexkroman1/aai-runtime/testing";
+import { digest } from "./agent.ts";
+
+// Parks on the wait instead of blocking, with the work before it journaled.
+const run = await runWorkflow(digest, { url: "https://example.com/a" }, {
+  name: "digest",
+});
+expect(run.status).toBe("running");
+expect(run.wakeAt).toBeGreaterThan(Date.now());
+expect(run.steps.map((s) => s.name)).toEqual(["fetchArticle", "summarize"]);
+
+// Ends the wait the way `ctx.workflows.wakeUp` does, and the body continues.
+await run.advanceSleep();
+expect(run.status).toBe("completed");
+expect(run.deliveries).toBe(2);
+```
+
+Three more things it can do, each the thing a durable body is written for:
+
+- `run.signal(token, payload)` answers a `ctx.waitFor`, so an approval gate is
+  testable without a second process.
+- `{ crashAt: "summarize" }` kills the first delivery that reaches that step,
+  before its body runs — a worker that died mid-run. `await run.restart()` then
+  boots a fresh engine over the same journal, and only the step that never
+  settled runs again.
+- `{ journal }` shares one store between runs, so a spec can assert what a
+  second run sees.
+
+Stub the steps' collaborators at the seams they really use — a step's HTTP goes
+through the published `stepFetch` slot, so a model call and a page fetch are BOTH
+answered there. `stubGatewayRoute` composes the two:
+
+```ts no-check
+import { stubGatewayRoute } from "@alexkroman1/aai/testing";
+import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
+
+const model = stubGatewayRoute('{"headline":"H","points":["a"]}');
+installStubStepFetch((request) => model.route(request) ?? { body: PAGE_HTML });
+```
+
 ### A step's env, and calling a model from one
 
 A step has no `ctx`, so the two things tool code takes for granted come from
@@ -1712,7 +1858,7 @@ safe from a `workflows/*.ts` module and from a browser bundle:
 | `formatBytes`, `formatDuration`, `countWords`, `plural` | Narration. Each returns ONE fixed shape, so a step's progress line and the page rendering the same run cannot disagree — they did, one template printing `1:04:09` from its workflow and `64:09` from its page |
 | `pushCapped(list, item, max)` | An append that keeps the last N, for a log a session accumulates |
 | `isRecord(x)`, `omitUndefined(obj)` | The object guard and the spread-free way to drop undefined fields |
-| `decodeHtmlEntities(text)` | Scraped text on its way to a model |
+| `decodeHtmlEntities(text)` | Six entities, no dependency. Enough for a `client.tsx`; for a page or a feed see `/html` below |
 | `createKeyedLock()` / `withLock(lock, key, work)` | Serializing async work per key |
 
 **`createKeyedLock` is the one an agent most needs and least expects to.** The
@@ -1722,6 +1868,39 @@ that case — `slot.update`'s window is synchronous — so reach for the lock wh
 the thing being mutated is outside the session. `withLock` takes an optional
 acquire deadline and throws `KeyedLockTimeoutError` when it runs out.
 
+## Reading a page or a feed — `@alexkroman1/aai/html`
+
+A step that fetches somebody else's markup gets a real parse rather than a
+regex. Node-only (it pulls two parsers), so import it from `workflows/*.ts` or a
+tool, never from `client.tsx`:
+
+```ts
+import { htmlToText, pageMetadata, parseFeed } from "@alexkroman1/aai/html";
+
+declare const html: string;
+declare const xml: string;
+
+// A page, reduced to the prose worth putting in a prompt. `<script>` and
+// `<style>` bodies never survive, and `maxChars` caps what crosses the wire.
+const article = htmlToText(html, { maxChars: 20_000 });
+
+// `og:title` when the page declares one, else its `<title>` element.
+const { title, description, feedUrls } = pageMetadata(html);
+
+// RSS, Atom and RDF alike. `published` is ISO whatever the feed wrote, and
+// titles come back as TEXT — feeds wrap HTML in CDATA as a matter of course.
+const feed = parseFeed(xml);
+const episodes = feed?.items.filter((item) => item.enclosureUrl !== undefined) ?? [];
+```
+
+**Reach for this rather than writing the patterns.** Both are cheap to get
+wrong in ways that only show up on real pages: `<[^>]+>` cuts a tag whose
+attribute contains a `>`, `<script[^>]*>[\s\S]*?<\/script>` leaves the whole
+script in your prompt when the page was truncated mid-tag, and
+`indexOf("<title>")` finds an entry's title rather than a channel's. The
+`link-digest` and `podcast-digest` templates each shipped a version of those
+before this subpath existed.
+
 ## Persisting data — bring your own client
 
 **There is no `ctx.db`.** It was a SQL handle on the tool context, backed first

package/dist/scaffold/package.json

@@ -14,9 +14,9 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^10.0.0",
-    "@alexkroman1/aai-runtime": "^10.0.0",
-    "@alexkroman1/aai-ui": "^10.0.0",
+    "@alexkroman1/aai": "^11.0.0",
+    "@alexkroman1/aai-runtime": "^11.0.0",
+    "@alexkroman1/aai-ui": "^11.0.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.0.0",
@@ -24,7 +24,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^10.0.0",
+    "@alexkroman1/aai-cli": "^11.0.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",

package/dist/{studio-wVWNLREn.mjs → studio-BxAS_FQQ.mjs}

@@ -97,7 +97,10 @@ async function pushProject(opts) {
 	const { files, warnings } = await collectSourceFiles(opts.cwd);
 	for (const warning of warnings) log.warn(warning);
 	if (Object.keys(files).length === 0) throw new Error("Nothing to push — this directory has no project files.");
-	if (!files["agent.ts"] && existsSync(path.join(opts.cwd, "agent.ts"))) throw new CliError("entry_not_synced", warnings.find((w) => w.startsWith("agent.ts ")) ?? "agent.ts exists locally but was not synced.", "The entry file must sync to deploy — reduce its size or fix its encoding.");
+	if (!files["agent.ts"] && existsSync(path.join(opts.cwd, "agent.ts"))) {
+		const reason = warnings.find((w) => w.startsWith("agent.ts "));
+		throw new CliError("entry_not_synced", reason ?? "agent.ts exists locally but was not synced.", "The entry file must sync to deploy — reduce its size or fix its encoding.");
+	}
 	let project = config?.studioProject;
 	let baseHash = config?.studioSourceHash;
 	let slug = config?.slug;

package/dist/templates/call-audit/agent.test.ts

@@ -21,12 +21,18 @@
  * argv they will run, and the classification of a failure — which is where a
  * mistake is silent, since a `timeout` called fatal is a run that gives up on work
  * that would have finished.
+ *
+ * The last block adds a third: the ENGINE's half of that classification, on a
+ * real run. `runWorkflow` starts this desk's declared workflow on the replay
+ * engine, and with no ffmpeg the first step fails fatally — which is exactly the
+ * case worth asserting, because `FatalError` exists to stop the engine spending
+ * the six attempts this call site asks for on a file that will never convert.
  */
 
 import { readdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { FatalError, RetryableError } from "@alexkroman1/aai/step-errors";
-import { createWorkflowCtx, stubSpeech } from "@alexkroman1/aai/testing";
+import { createWorkflowCtx, stubSpeech, WORKFLOW_CTX_NOW } from "@alexkroman1/aai/testing";
 import {
   installStubGateway,
   installStubReporter,
@@ -34,12 +40,12 @@ import {
   installStubTranscribe,
   installStubUploads,
 } from "@alexkroman1/aai/testing/vitest";
+import { runWorkflow } from "@alexkroman1/aai-runtime/testing";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import agentDef, { audit } from "./agent.ts";
 import {
   auditFlow,
   joinSegments,
-  now,
   SEGMENT_CONCURRENCY,
   transcribeSegment,
 } from "./workflows/audit.ts";
@@ -732,20 +738,6 @@ describe("classifying a failure", () => {
   });
 });
 
-describe("the run's clock", () => {
-  test("is a STEP, so a replay does not re-measure it", async () => {
-    // A `Date.now()` in the body returns a different value on every replay, and
-    // every duration derived from it would be a different duration.
-    vi.useFakeTimers();
-    try {
-      vi.setSystemTime(1_700_000_000_000);
-      await expect(now()).resolves.toBe(1_700_000_000_000);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-});
-
 describe("the mastered narration", () => {
   test("is not driven here, and the spec says why rather than pretending", () => {
     // `narrate` speaks, writes a temp file, spawns ffmpeg and stores the result. A
@@ -821,6 +813,18 @@ describe("the ffmpeg steps, up to the spawn", () => {
 });
 
 describe("the body's step policy", () => {
+  /**
+   * A `ctx.now` that answers each reach from `samples`, in order.
+   *
+   * The last value repeats rather than running out: a spec naming two reads
+   * should fail on the DURATION if the body grows a third, not on an
+   * `undefined` from the fake.
+   */
+  const clockReads = (...samples: readonly number[]) => {
+    let reach = 0;
+    return () => samples[Math.min(reach++, samples.length - 1)] ?? 0;
+  };
+
   /**
    * A `ctx` that walks the whole body without running a single step.
    *
@@ -831,9 +835,13 @@ describe("the body's step policy", () => {
   const walkedCtx = () =>
     createWorkflowCtx({
       runSteps: false,
+      // The body reads the clock at both ends with `ctx.now()`, which the engine
+      // journals under `now!0` and `now!1`. A PRODUCER here rather than a fixed
+      // number, so the two reaches differ and `elapsedMs` is assertable — based
+      // on `WORKFLOW_CTX_NOW`, the instant the fake otherwise freezes at, rather
+      // than on a second arbitrary epoch nobody can relate to the first.
+      now: clockReads(WORKFLOW_CTX_NOW, WORKFLOW_CTX_NOW + 3000),
       results: {
-        clockStart: 1000,
-        clockEnd: 4000,
         ingestRecording: {
           audio: "upl_pcm",
           source: "call.wav",
@@ -867,23 +875,94 @@ describe("the body's step policy", () => {
     // other half of the claim: a raised budget is a decision about ONE step.
     // Asserted as PRESENT-with-no-budget rather than as `get(…) === undefined`,
     // which a step the body never reached at all would also satisfy.
-    for (const name of ["clockStart", "summarize"]) {
+    for (const name of ["narrate", "summarize"]) {
       expect(budgets.has(name)).toBe(true);
       expect(budgets.get(name)).toBeUndefined();
     }
   });
 
-  test("reads the clock at each end under its own name, so a run's history is legible", async () => {
-    // `(name, occurrence)` would tell two `now` calls apart on its own
-    // (`now#0`, `now#1`); distinct names are for the person reading the history.
+  test("reads the clock with `ctx.now()` at each end, and subtracts in the body", async () => {
+    // Two reaches of one method, keyed `now!0` and `now!1` and journaled
+    // separately by the engine. This used to be two NAMED steps over an exported
+    // one-line clock read, and the names existed only so a person reading the
+    // run's history could tell the ends apart; the affordance journals the read
+    // itself. What is left to assert is that the body subtracts two journaled
+    // values rather than re-reading a clock, which is what makes a replay report
+    // the same elapsed.
     const ctx = walkedCtx();
 
     const output = await auditFlow({ recording: UPLOAD_ID }, ctx);
 
-    expect(ctx.steps[0]?.name).toBe("clockStart");
-    expect(ctx.steps.at(-1)?.name).toBe("clockEnd");
-    // Subtracted in the BODY from two journaled values, so a replay reports the
-    // same elapsed rather than re-reading a clock.
     expect(output.elapsedMs).toBe(3000);
+    // And the clock is no longer a step, which is the other half of the claim: a
+    // name here would mean the migration left one behind.
+    expect(ctx.steps.map((step) => step.name)).not.toContain("clockStart");
+  });
+});
+
+/**
+ * `auditFlow` on the real replay engine — as far as this tier can take it.
+ *
+ * The block above drives the body through `createWorkflowCtx` with
+ * `runSteps: false` and a journaled result per step, which is what makes it
+ * affordable: `ingestRecording` runs ffmpeg, and this repo's test environment
+ * has none — the `ingestRecording` and `narrate` specs above assert the
+ * `FatalError` that produces, unconditionally.
+ *
+ * So a whole run of this desk is not reachable here and this file does not
+ * pretend otherwise; `aai-cli`'s `dev-workflow.scenario.test.ts` is the tier
+ * with a built project. What IS reachable, and what nothing else asserts, is the
+ * ENGINE's half of the fatal/retryable contract: a step that throws a
+ * `FatalError` must fail its run on the first attempt rather than spending the
+ * six this body asks for. The step specs above assert the class; only a real
+ * engine can assert what the class is FOR.
+ */
+describe("the run is DURABLE, as far as ffmpeg allows", () => {
+  beforeEach(() => {
+    installStubUploads({
+      [UPLOAD_ID]: { bytes: new Uint8Array(2048), name: "call.m4a", type: "audio/mp4" },
+    });
+    installStubReporter();
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "test-key");
+  });
+
+  test("a FatalError in the first step fails the run on ONE attempt, not six", async () => {
+    const run = await runWorkflow(audit, { recording: UPLOAD_ID }, { name: "audit" });
+
+    expect(run.status).toBe("failed");
+    expect(run.error).toMatch(/ffmpeg/i);
+    const ingest = run.steps.find((step) => step.name === "ingestRecording");
+    // The whole point of `FatalError`: `maxAttempts: 6` is the budget this call
+    // site asks for, and a failure that cannot change must not spend it. A step
+    // that burned all six here would delay the real error by minutes in
+    // production and cost five more conversions of a file that is not going to
+    // convert.
+    expect(ingest?.status).toBe("failed");
+    expect(ingest?.attempts).toBe(1);
+  });
+
+  test("the failure is DURABLE: a redelivery reports it rather than trying again", async () => {
+    const run = await runWorkflow(audit, { recording: UPLOAD_ID }, { name: "audit" });
+    expect(run.status).toBe("failed");
+
+    // A terminal run is done, and a redelivery of one is ordinary rather than an
+    // error — the platform's queue acks on a 200, so any delivery whose ack was
+    // lost arrives again after the run finished.
+    await run.restart();
+    expect(run.status).toBe("failed");
+    expect(run.steps.filter((step) => step.name === "ingestRecording")).toHaveLength(1);
+    expect(run.deliveries).toBe(2);
+  });
+
+  test("the clock is journaled BEFORE the step that fails, so the run's start survives", async () => {
+    // `ctx.now()` and the ingest are issued together in one `Promise.all`, so a
+    // failing ingest must not lose the clock read that went out beside it. It is
+    // journaled through the same append a step is, into a key space of its own —
+    // which is why it reads back off `reads` rather than `steps`.
+    const run = await runWorkflow(audit, { recording: UPLOAD_ID }, { name: "audit" });
+
+    const clock = run.reads.find((read) => read.key === "now!0");
+    expect(clock?.kind).toBe("now");
+    expect(typeof clock?.value).toBe("number");
   });
 });