@alexkroman1/aai-cli 12.0.0 → 13.0.0

package/dist/scaffold/package.json

@@ -14,24 +14,24 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^12.0.0",
-    "@alexkroman1/aai-runtime": "^12.0.0",
-    "@alexkroman1/aai-ui": "^12.0.0",
+    "@alexkroman1/aai": "^13.0.0",
+    "@alexkroman1/aai-runtime": "^13.0.0",
+    "@alexkroman1/aai-ui": "^13.0.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.0.0",
-    "xstate": "^5.32.5",
-    "zod": "^4.4.3"
+    "xstate": "^5.32.6",
+    "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^12.0.0",
+    "@alexkroman1/aai-cli": "^13.0.0",
     "@tailwindcss/vite": "^4.3.3",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.1",
     "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.4",
-    "@vitejs/plugin-react": "^6.0.5",
+    "@types/react-dom": "^19.2.5",
+    "@vitejs/plugin-react": "^6.1.1",
     "typescript": "^7.0.2",
-    "vite": "^8.2.1",
-    "vitest": "^4.1.10"
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11"
   }
 }

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

@@ -321,8 +321,31 @@ describe("reading the loudness measurement", () => {
     expect(() => parseLoudness(missing)).toThrow(/input_tp/);
   });
 
+  test("names the KEY when the value is unreadable, and QUOTES what came", () => {
+    // The other half of the case above: the key is there and holds something no
+    // number can be read out of — `"n/a"`, which is ffmpeg's own spelling for a
+    // value it could not measure, or a type that was never a number. Terminal
+    // either way, and the message has to carry the value, which is why the
+    // object gate and the value schema are two parses rather than one.
+    expect(() => parseLoudness(LOUDNORM_STDERR.replace('"-7.42"', '"n/a"'))).toThrow(
+      /input_tp.*got "n\/a"/,
+    );
+    expect(() => parseLoudness(LOUDNORM_STDERR.replace('"-7.42"', "[1,2]"))).toThrow(/input_tp/);
+  });
+
+  test("coerces exactly as `Number(…)` does, corners included", () => {
+    // Every value is a STRING on the wire, so the read has always been a
+    // coercion — and `Number(null)` is 0, not `NaN`. Pinned rather than
+    // tightened: the schema replaced a hand-written reader, so its corners are
+    // the ones that reader had, and narrowing them is a change to make on
+    // purpose rather than a side effect of declaring a schema.
+    const nulled = LOUDNORM_STDERR.replace('"0.13"', "null");
+    expect(parseLoudness(nulled).targetOffset).toBe(0);
+  });
+
   test("refuses a block that is not JSON at all", () => {
     expect(() => parseLoudness("[loudnorm] {not json}")).toThrow(MediaAnalysisError);
+    expect(() => parseLoudness("[loudnorm] {not json}")).toThrow(/not JSON/);
   });
 });
 

package/dist/templates/call-audit/workflows/media.ts

@@ -59,7 +59,7 @@
  */
 
 import type { PcmFormat } from "@alexkroman1/aai/step";
-import { isRecord } from "@alexkroman1/aai/utils";
+import { z } from "zod";
 
 /**
  * The format every recording is converted to before anything measures it.
@@ -255,9 +255,9 @@ export function measureLoudnessArgs(input: string): string[] {
  * `{…}` in the text — last because a re-run's block would follow an earlier one,
  * and because nothing else ffmpeg logs at info level is brace-delimited.
  *
- * Every value arrives as a STRING (`"input_i" : "-16.19"`), which is ffmpeg's
- * shape and not a quirk of one version; a numeric coercion that silently yields
- * `NaN` is what a missing key would otherwise become, so each one is checked.
+ * Both halves of the read are declared below — {@link LoudnessBlock} for "is it
+ * an object", {@link LoudnessValues} for the five values, every one of which
+ * arrives as a STRING and has to coerce without silently yielding `NaN`.
  */
 export function parseLoudness(stderr: string): Loudness {
   const open = stderr.lastIndexOf("{");
@@ -268,23 +268,68 @@ export function parseLoudness(stderr: string): Loudness {
         "loses `-loglevel info`, since `print_format=json` writes through ffmpeg's log.",
     );
   }
-  // `isRecord` from the SDK rather than a hand-written
-  // `typeof x === "object" && x !== null` — this repo's rule (`guard-invariants`
-  // rule 17). It also NARROWS, so nothing below needs the
-  // `as Record<string, unknown>` the open-coded version required.
-  const parsed = safeJson(stderr.slice(open, close + 1));
-  if (!isRecord(parsed)) {
+  // Two parses, one per sentence this function can say. The block being an
+  // OBJECT and the five values being readable are different failures with
+  // different remedies, and the second message quotes the value ffmpeg actually
+  // printed — which needs the block still in hand, so the gate cannot be folded
+  // into the schema below.
+  const block = LoudnessBlock.safeParse(safeJson(stderr.slice(open, close + 1)));
+  if (!block.success) {
     throw new MediaAnalysisError("The loudness pass printed a block that is not JSON.");
   }
+
+  const values = LoudnessValues.safeParse(block.data);
+  if (!values.success) {
+    // Zod reports issues in the schema's own field order, so the first one names
+    // the same key the first per-key read named — and there is always a key,
+    // the object gate above having already passed.
+    const key = String(values.error.issues[0]?.path[0]);
+    throw new MediaAnalysisError(
+      `The loudness pass reported no usable \`${key}\` (got ${JSON.stringify(block.data[key])}).`,
+    );
+  }
+
   return {
-    inputLufs: numberAt(parsed, "input_i"),
-    inputTruePeak: numberAt(parsed, "input_tp"),
-    inputRange: numberAt(parsed, "input_lra"),
-    inputThreshold: numberAt(parsed, "input_thresh"),
-    targetOffset: numberAt(parsed, "target_offset"),
+    inputLufs: values.data.input_i,
+    inputTruePeak: values.data.input_tp,
+    inputRange: values.data.input_lra,
+    inputThreshold: values.data.input_thresh,
+    targetOffset: values.data.target_offset,
   };
 }
 
+/**
+ * Is the found `{…}` an object at all?
+ *
+ * The reachable failure is {@link safeJson} answering `undefined` — a brace pair
+ * found in ffmpeg's chatter with something other than JSON between them — and
+ * that is a different sentence from a value being unreadable, which is why this
+ * gate exists at all rather than being folded into {@link LoudnessValues}.
+ *
+ * `looseObject`, not `object`: it asks the ONE question and says nothing about
+ * keys, which matters because ffmpeg prints ten and the schema below reads five.
+ */
+const LoudnessBlock = z.looseObject({});
+
+/**
+ * The five numbers, in the order {@link parseLoudness} reports them missing.
+ *
+ * `z.coerce.number()` is the load-bearing choice: every value arrives as a
+ * STRING (`"input_i" : "-16.19"`), which is ffmpeg's shape and not a quirk of
+ * one version, so the schema has to coerce exactly as `Number(…)` did. What it
+ * adds is the check — zod 4's `z.number()` refuses `NaN` and both infinities,
+ * so a key ffmpeg stopped printing fails HERE with its name attached instead of
+ * flowing into pass two's argv as the literal text `NaN` and coming back as an
+ * ffmpeg option-parsing error about a filter.
+ */
+const LoudnessValues = z.object({
+  input_i: z.coerce.number(),
+  input_tp: z.coerce.number(),
+  input_lra: z.coerce.number(),
+  input_thresh: z.coerce.number(),
+  target_offset: z.coerce.number(),
+});
+
 /**
  * Pass two: apply the measurement, find the pauses, and write the audio.
  *
@@ -616,22 +661,3 @@ function safeJson(text: string): unknown {
     return undefined;
   }
 }
-
-/**
- * One of `loudnorm`'s values, as a number.
- *
- * Checked rather than coerced: every value arrives as a string, so `Number(…)` on
- * a key ffmpeg stopped printing yields `NaN`, which then flows into the second
- * pass's argv as the literal text `NaN` and makes ffmpeg reject the filter with a
- * message about option parsing. Naming the key here is what turns that into a
- * sentence about the analysis.
- */
-function numberAt(raw: Record<string, unknown>, key: string): number {
-  const parsed = Number(raw[key]);
-  if (!Number.isFinite(parsed)) {
-    throw new MediaAnalysisError(
-      `The loudness pass reported no usable \`${key}\` (got ${JSON.stringify(raw[key])}).`,
-    );
-  }
-  return parsed;
-}

package/dist/templates/podcast-digest/agent.test.ts

@@ -512,6 +512,72 @@ describe("discoverEpisodes", () => {
     expect(episodes[0]?.podcastTitle).toBe("Example Show");
   });
 
+  /**
+   * The three degradation cases of the iTunes payload, which is third-party
+   * JSON reached without an API key — so every one of them is a shape a live
+   * run really meets, and NONE of them may fail the run. A schema parsed with a
+   * throwing `parse` fails all three.
+   */
+  test("keeps the usable hit when a neighbouring entry is not even an object", async () => {
+    stub({
+      "itunes.apple.com/lookup": {
+        body: {
+          results: [
+            "no results",
+            7,
+            null,
+            { feedUrl: "https://show.test/feed.xml", collectionName: "Example Show" },
+          ],
+        },
+      },
+      "show.test/feed.xml": { body: THREE_EPISODES },
+    });
+
+    const episodes = await discoverEpisodes("https://podcasts.apple.com/us/podcast/x/id123", 1);
+
+    expect(episodes[0]?.podcastTitle).toBe("Example Show");
+  });
+
+  test("reads a malformed lookup payload as no hits, and takes the other route", async () => {
+    // An interstitial, a rate-limit body, a schema change: `results` is not an
+    // array, so there is nothing to search — which is what the page fallback
+    // below this exists for, and is a normal outcome rather than a failed run.
+    stub({
+      "itunes.apple.com/lookup": { body: { results: "temporarily unavailable" } },
+      "podcasts.apple.com": {
+        body:
+          '<script id="serialized-server-data">' +
+          '{"d":[{"model":{"adamId":"123","feedUrl":"https://show.test/feed.xml"}}]}' +
+          "</script>",
+      },
+      "show.test/feed.xml": { body: THREE_EPISODES },
+    });
+
+    expect(await discoverEpisodes("https://podcasts.apple.com/us/podcast/x/id123", 1)).toHaveLength(
+      1,
+    );
+  });
+
+  test("falls back to the feed's host when the hit names the show unusably", async () => {
+    // `collectionName` of the wrong type and no `trackName` behind it is the
+    // same case as neither field being there: the hit still carries the one
+    // field the caller came for, so it is used, and the title falls back to the
+    // feed's host. The feed here has no `<title>` of its own, which is what
+    // makes that fallback observable at all.
+    stub({
+      "itunes.apple.com/lookup": {
+        body: { results: [{ feedUrl: "https://show.test/feed.xml", collectionName: 42 }] },
+      },
+      "show.test/feed.xml": {
+        body: `<?xml version="1.0"?><rss><channel>${itemXml("only", "Tue, 01 Jan 2030 00:00:00 GMT")}</channel></rss>`,
+      },
+    });
+
+    const episodes = await discoverEpisodes("https://podcasts.apple.com/us/podcast/x/id123", 1);
+
+    expect(episodes[0]?.podcastTitle).toBe("show.test");
+  });
+
   test("falls back to Apple's own page when the lookup omits the feed", async () => {
     stub({
       "itunes.apple.com/lookup": { body: { results: [{ collectionName: "Example Show" }] } },

package/dist/templates/podcast-digest/workflows/feeds.ts

@@ -68,6 +68,7 @@ import { type FeedItem, pageMetadata, parseFeed } from "@alexkroman1/aai/html";
 import { report } from "@alexkroman1/aai/step";
 import { FatalError, stepFetchOk } from "@alexkroman1/aai/step-errors";
 import { isRecord, omitUndefined, safeJsonParse } from "@alexkroman1/aai/utils";
+import { z } from "zod";
 
 /** How long any one of these lookups may take before it is a failure. */
 const REQUEST_TIMEOUT_MS = 30_000;
@@ -463,27 +464,64 @@ function normalizeTitle(value: string): string {
     .trim();
 }
 
+/** One iTunes hit, reduced to the three fields this file reads. */
+type AppleResult = { feedUrl?: string; title?: string; artist?: string };
+
 /**
- * The iTunes payload, reduced to the three fields this file reads.
+ * One entry of an iTunes `results` array, reduced on the way through.
+ *
+ * Every field is `.catch(undefined)`, which is this schema's whole subject: the
+ * caller is looking for a hit with a `feedUrl` on it, so a neighbouring entry
+ * that spells `collectionName` as a number is a hit that does not match, never
+ * a reason to abandon the search. The reduction rides in the `transform` for
+ * the same reason the fields are declared here rather than at the call site —
+ * `collectionName ?? trackName` is a fact about iTunes' payload, and this is
+ * the module that is allowed to know vendor facts.
  *
  * `omitUndefined` rather than a conditional spread per field: under
  * `exactOptionalPropertyTypes` an absent field and a field set to `undefined`
  * are different types, and this is the SDK's one spelling for the difference.
+ * It is still needed after a schema, because a field the `.catch` above turned
+ * into `undefined` is PRESENT in zod's output holding `undefined` (only an
+ * absent field stays absent).
  */
-function appleResults(body: unknown): Array<{ feedUrl?: string; title?: string; artist?: string }> {
-  if (!(isRecord(body) && Array.isArray(body.results))) return [];
-  return body.results.filter(isRecord).map((result) =>
-    omitUndefined({
-      feedUrl: asString(result.feedUrl),
-      title: asString(result.collectionName) ?? asString(result.trackName),
-      artist: asString(result.artistName),
-    }),
-  );
-}
+const AppleResultEntry = z
+  .object({
+    feedUrl: z.string().optional().catch(undefined),
+    collectionName: z.string().optional().catch(undefined),
+    trackName: z.string().optional().catch(undefined),
+    artistName: z.string().optional().catch(undefined),
+  })
+  .transform(
+    (result): AppleResult =>
+      omitUndefined({
+        feedUrl: result.feedUrl,
+        title: result.collectionName ?? result.trackName,
+        artist: result.artistName,
+      }),
+  )
+  // An entry that is not an object at all — the one shape the fields above
+  // cannot absorb — becomes `null` and is dropped below, rather than taking the
+  // whole array down with it. That is the `.filter(isRecord)` this replaces.
+  .nullable()
+  .catch(null);
+
+/** The iTunes lookup and search payloads, which share the one field read here. */
+const AppleResponse = z.object({ results: z.array(AppleResultEntry) });
 
-/** A JSON field, when the far side really did send a string. */
-function asString(value: unknown): string | undefined {
-  return typeof value === "string" ? value : undefined;
+/**
+ * The hits in an iTunes response, and NOTHING is an ordinary answer.
+ *
+ * `safeParse`, never `parse`: both callers treat an empty list as "no match
+ * found" and already have a sentence for it, so a body that is not an object,
+ * or one whose `results` is not an array, must degrade rather than fail the
+ * run. These are live third-party endpoints reached without an API key — a
+ * throw here would turn a rate-limit interstitial into a failed durable run.
+ */
+function appleResults(body: unknown): AppleResult[] {
+  const parsed = AppleResponse.safeParse(body);
+  if (!parsed.success) return [];
+  return parsed.data.results.filter((result) => result !== null);
 }
 
 // ---- HTTP -------------------------------------------------------------------

package/dist/templates/recap-workflow/agent.test.ts

@@ -554,6 +554,33 @@ describe("checkTranscript", () => {
     stubProvider({ status: "transcribing" });
     await expect(checkTranscript("t_1")).rejects.toThrow(/unknown transcript status/);
   });
+
+  test("drops a field of the wrong type rather than failing the poll", async () => {
+    // THE degradation rule, and the test that fails against a schema parsed
+    // with a throwing `parse`: the job is running and `status` says so, so a
+    // `text` the provider sent as a number is one unusable field — not a reason
+    // to end a run that has already paid for the transcription. Each optional
+    // field carries its own `.catch(undefined)` for exactly this.
+    stubProvider({ status: "processing", text: 42, error: [], audio_duration: "254" });
+    expect(await checkTranscript("t_1")).toEqual({ status: "processing" });
+  });
+
+  test("drops a non-finite duration, which `Math.round(x / 60)` cannot use", async () => {
+    // JSON cannot spell `Infinity`, so this arrives as a string or a null and
+    // has to be refused the same way — `z.number()` refuses both, which is the
+    // `Number.isFinite` test the hand-written reader carried.
+    stubProvider({ status: "completed", text: "Hello.", audio_duration: null });
+    expect(await checkTranscript("t_1")).toEqual({ status: "completed", text: "Hello." });
+  });
+
+  test("names an unreadable body as `undefined` rather than throwing twice", async () => {
+    // Valid JSON that is not this endpoint's object — a proxy that answered
+    // with a list, say. There is no status to report, so the sentence says
+    // exactly that rather than the report itself failing on the body it was
+    // sent to describe.
+    stubProvider([{ status: "completed" }]);
+    await expect(checkTranscript("t_1")).rejects.toThrow(/unknown transcript status: undefined/);
+  });
 });
 
 describe("discardTranscript — the compensation", () => {

package/dist/templates/recap-workflow/workflows/recap.ts

@@ -120,7 +120,7 @@ import {
   stepTranscribeSubmitClassified,
   toStepError,
 } from "@alexkroman1/aai/step-errors";
-import { errorMessage, isRecord, omitUndefined } from "@alexkroman1/aai/utils";
+import { errorMessage, omitUndefined } from "@alexkroman1/aai/utils";
 import { z } from "zod";
 import { retentionToken, transcriptToken } from "./tokens.ts";
 
@@ -278,6 +278,58 @@ export type TranscriptState = {
   audioDuration?: number;
 };
 
+/**
+ * The four statuses this desk knows how to act on.
+ *
+ * Declared as a schema rather than checked with a `!==` chain because the union
+ * IS the provider's contract with this template — see {@link checkTranscript},
+ * which reads it as a value the saga branches on — and a schema is the one
+ * spelling that both narrows the type and names the four in the error.
+ */
+const TranscriptStatus = z.enum(["queued", "processing", "completed", "error"]);
+
+/**
+ * The poll response, as much of it as this desk reads.
+ *
+ * **The three optional fields DEGRADE and the status does not**, which is the
+ * whole reason each one is spelled differently. A provider that answers
+ * `"text": null` on a job still running, or drops `audio_duration` from a
+ * failed one, is describing a job this desk can still act on — so a field of
+ * the wrong type is `undefined` (`.catch`) and an absent one stays absent. A
+ * status outside the four is the opposite: nothing downstream knows what to do
+ * with it, and polling to the bound and failing with the wrong reason is worse
+ * than stopping here. So a bad status fails the parse and
+ * {@link checkTranscript} turns that into a sentence.
+ *
+ * `audio_duration` is `z.number()` rather than a coercion, and zod 4's
+ * `z.number()` refuses `NaN` and both infinities — the `Number.isFinite` test
+ * the hand-written reader carried, which is what stops a non-finite duration
+ * reaching `Math.round(… / 60)` in {@link summarize}.
+ */
+const TranscriptBody = z.object({
+  status: TranscriptStatus,
+  text: z.string().optional().catch(undefined),
+  error: z.string().optional().catch(undefined),
+  audio_duration: z.number().optional().catch(undefined),
+});
+
+/**
+ * The status to NAME when {@link TranscriptBody} refused the body.
+ *
+ * Reporting the value is the job, so nothing here may throw a second time while
+ * reporting the first. `.catch({})` absorbs every shape that is not "an object
+ * with a string status" — a body that is not an object at all, a `status` that
+ * is a number — and each then arrives in the sentence as the word "undefined",
+ * which is a truthful "the provider sent something this desk cannot read" and
+ * the same thing the per-field read this replaced said. That `.catch` is also
+ * what makes `.parse` legal at the one call site: there is no input left for it
+ * to throw on.
+ */
+const ReportedStatus = z
+  .object({ status: z.string().optional() })
+  .catch({})
+  .transform((body) => body.status);
+
 /**
  * One undo, and the name it goes by when it fails.
  *
@@ -636,26 +688,31 @@ export function callbackUrl(token: string): string | undefined {
 export async function checkTranscript(id: string): Promise<TranscriptState> {
   const response = await request(`${TRANSCRIPT_ENDPOINT}/${id}`);
   const body = await response.json();
-  const status = readString(body, "status");
-  if (
-    status !== "queued" &&
-    status !== "processing" &&
-    status !== "completed" &&
-    status !== "error"
-  )
-    throw new Error(`The provider reported an unknown transcript status: ${String(status)}`);
-
-  await report(`Transcript ${status}.`);
+  // `safeParse`, not `parse`: the only shape this desk refuses is an
+  // unrecognised status, and it owes that a sentence naming what arrived rather
+  // than a zod issue about an enum.
+  const parsed = TranscriptBody.safeParse(body);
+  if (!parsed.success) {
+    throw new Error(
+      `The provider reported an unknown transcript status: ${String(ReportedStatus.parse(body))}`,
+    );
+  }
+
+  await report(`Transcript ${parsed.data.status}.`);
   return {
-    status,
+    status: parsed.data.status,
     // `omitUndefined` rather than a spread-ternary per field: under
     // `exactOptionalPropertyTypes` an absent field and a field set to
     // `undefined` are different types, and this is the SDK's one spelling for
-    // the difference.
+    // the difference. Still needed after the schema, and for a reason worth
+    // knowing: an ABSENT field is absent from zod's output too, but a field
+    // whose value the schema `.catch`-ed to `undefined` is PRESENT and holding
+    // `undefined` — and this result crosses a queue, where such a key does not
+    // survive the trip.
     ...omitUndefined({
-      text: readString(body, "text"),
-      error: readString(body, "error"),
-      audioDuration: readNumber(body, "audio_duration"),
+      text: parsed.data.text,
+      error: parsed.data.error,
+      audioDuration: parsed.data.audio_duration,
     }),
   };
 }
@@ -744,7 +801,7 @@ export async function note(line: string): Promise<void> {
   await report(line);
 }
 
-// ---- HTTP and parsing -------------------------------------------------------
+// ---- HTTP -------------------------------------------------------------------
 
 /**
  * One authenticated request to the pre-recorded API, with this desk's retry
@@ -776,15 +833,3 @@ async function request(
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
   });
 }
-
-/** A string field of a JSON body, when it really is one. */
-function readString(body: unknown, key: string): string | undefined {
-  const value = isRecord(body) ? body[key] : undefined;
-  return typeof value === "string" ? value : undefined;
-}
-
-/** A number field of a JSON body, when it really is one. */
-function readNumber(body: unknown, key: string): number | undefined {
-  const value = isRecord(body) ? body[key] : undefined;
-  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
-}

package/dist/templates/transcription-workflow/agent.test.ts

@@ -1615,10 +1615,14 @@ describe("nextPollDelay", () => {
   });
 
   test("clamps to the floor rather than spinning when the bytes are already there", () => {
-    // The segment is stored but the loop reached the sleep anyway (it is waiting on
-    // `complete`). A poll is cheap and not free — this must not become a spin.
+    // A remainder of zero, which the `Math.max` below the estimate answers with the
+    // floor — there is no arm of its own for it, and the one that used to be there
+    // was unreachable from the body anyway (a stored segment goes in `ready` and
+    // the loop `continue`s past the sleep). What the floor is FOR is that the body
+    // must not poll faster than the round trip its own sleep costs, which is why it
+    // is 1000ms and not the 250ms that could not sleep at all.
     const delay = nextPollDelay(view(60_000, 2000), view(10_000, 1000), planAt(30_000), new Set());
-    expect(delay).toBe(250);
+    expect(delay).toBe(1000);
   });
 
   test("waits for the HEADER window before there is a plan to aim at", () => {
@@ -1664,15 +1668,21 @@ describe("nextPollDelay", () => {
     // body plans when `at.size >= HEADER_PROBE_BYTES`, so a delay derived from
     // `stored` is answering a different question than the one the loop asks. A
     // megabyte has landed in later windows and the header has not arrived.
-    // 100 bytes/ms against the whole 64 KiB probe window is 656ms; measured
+    // 50 bytes/ms against the whole 64 KiB probe window is 1311ms; measured
     // against `stored` the remainder is negative and the answer is the floor.
+    //
+    // The rate is half what this case used to carry, and deliberately: at 100
+    // bytes/ms the answer is 656ms, which is UNDER `MIN_POLL_INTERVAL_MS` and
+    // therefore the same 1000 a broken remainder would give — the case would
+    // still pass while measuring nothing. Every case below keeps its answer
+    // clear of both bounds for that reason.
     const delay = nextPollDelay(
-      detached(100_000, 0, 2000),
+      detached(100_000, 0, 3000),
       detached(0, 0, 1000),
       undefined,
       new Set(),
     );
-    expect(delay).toBe(656);
+    expect(delay).toBe(1311);
   });
 
   /**
@@ -1722,15 +1732,15 @@ describe("nextPollDelay", () => {
     // saturates the ceiling and gives back the flat 5000ms interval this
     // function replaced, once per segment, for the entire recording.
     //
-    // Two 8 MiB windows have landed contiguously from byte zero, at ~932
+    // Two 8 MiB windows have landed contiguously from byte zero, at ~466
     // bytes/ms; the segment ends 866,384 bytes past them.
     const delay = nextPollDelay(
-      landed([{ start: 0, end: 2 * PART_BYTES }], 10_000),
+      landed([{ start: 0, end: 2 * PART_BYTES }], 19_000),
       landed([{ start: 0, end: PART_BYTES }], 1000),
       planOver([0, 17_643_600]),
       new Set(),
     );
-    expect(delay).toBe(930);
+    expect(delay).toBe(1860);
   });
 
   test("wakes for the segment CLOSEST to ready, which need not be the earliest", () => {
@@ -1739,13 +1749,13 @@ describe("nextPollDelay", () => {
     // has not done. Segment 0 has nothing covering its start and needs the whole
     // 20 MB prefix; segment 1 sits inside a window that is 500,000 bytes short.
     const delay = nextPollDelay(
-      landed([{ start: 16_000_000, end: 35_500_000 }], 10_000),
+      landed([{ start: 16_000_000, end: 35_500_000 }], 19_000),
       landed([{ start: 16_000_000, end: 27_111_608 }], 1000),
       planOver([0, 20_000_000], [16_000_000, 36_000_000]),
       new Set(),
     );
-    // 932 bytes/ms against the 500,000 still missing from segment 1's window.
-    expect(delay).toBe(537);
+    // 466 bytes/ms against the 500,000 still missing from segment 1's window.
+    expect(delay).toBe(1073);
   });
 
   test("falls back to the prefix for a window that does not cover the segment's START", () => {

package/dist/templates/transcription-workflow/workflows/stream.ts

@@ -215,22 +215,43 @@ const POLL_INTERVAL_MS = 5000;
  * A poll is one cheap step (the body's own note above the `continue` says so), but
  * it is not free — it is a journal write and, on the platform, a step execution —
  * so a rate estimate that comes out near zero must not turn the loop into a spin.
- * 250ms is under the latency of any single segment's transcription, so nothing is
- * waiting on this.
+ *
+ * **The comparison that decides this number is the ROUND TRIP of the machinery
+ * that implements the sleep, not the latency of a segment's transcription.** It
+ * was 250ms on the second reading, which made it DEAD: `ctx.sleep`'s deadline is
+ * computed before its journal write is issued and tested after that write comes
+ * back, so on the platform — where one journal call was measured at ~558ms mean,
+ * p50 ranging 164-796ms — a 250ms sleep has already expired by the time its own
+ * write answers. It did not sleep at all, and the loop then polled as fast as the
+ * journal would let it. A floor under the round trip is not a floor.
+ *
+ * 1000ms is above every one of those readings and still an order of magnitude
+ * under a single segment's transcription, so nothing is waiting on it.
  */
-const MIN_POLL_INTERVAL_MS = 250;
+const MIN_POLL_INTERVAL_MS = 1000;
 
 /**
  * Consecutive polls with NO new bytes before the run gives up.
  *
  * An upload that died stays incomplete forever, so without a bound the run polls for
- * as long as the world will replay it. At {@link POLL_INTERVAL_MS} this is five minutes
- * of silence — far longer than any stall a live uplink produces, and short enough
- * that the failure reaches whoever is watching.
+ * as long as the world will replay it.
+ *
+ * **What one poll COSTS is a delivery, not an interval, and this doc said
+ * otherwise.** It read "at {@link POLL_INTERVAL_MS} this is five minutes of
+ * silence", which counts the sleep and nothing else. A poll that sleeps also
+ * suspends the run, so the wall clock between two polls is the sleep plus a
+ * queue round trip plus the next delivery's opening reads — measured on a
+ * deployed run at 11-40 seconds. Sixty of those is **20 to 40 minutes**, not
+ * five.
+ *
+ * That is longer than intended and is left as it is: what the bound has to
+ * outlast is a stall a live uplink really produces, and erring long costs an
+ * abandoned upload some idle deliveries where erring short fails a healthy
+ * recording. The number to write down is the honest one.
  *
  * It resets on every byte, so a slow upload is bounded by its own quietest gap
  * rather than by its total length: a two-hour recording on a bad connection is fine
- * as long as something arrives every five minutes.
+ * as long as something arrives inside that window.
  */
 const MAX_IDLE_POLLS = 60;
 
@@ -266,8 +287,9 @@ export type UploadProgressView = {
    * When this view was taken, as the step that took it saw the clock.
    *
    * Journaled, which is the only reason the body may read a clock at all: the
-   * sleep below is derived from the RATE between two of these, and a value the
-   * body sampled itself would make that derivation diverge on a replay. Same rule
+   * sleep below is derived from the RATE between the run's FIRST view and this
+   * one, and a value the body sampled itself would make that derivation diverge
+   * on a replay. Same rule
    * as every other field here — see the body's own note on why its state is legal.
    */
   observedAt: number;
@@ -304,10 +326,20 @@ export async function transcribeStreamFlow(input: { recording: string }, ctx: Wo
   // stopped from one whose prefix has not caught up yet.
   let lastStored = -1;
   /**
-   * The previous poll, so {@link nextPollDelay} has two journaled samples to take
-   * a rate from. Body state for the same reason the rest is: it came out of a step.
+   * The FIRST poll, so {@link nextPollDelay} has a baseline to take an AVERAGE
+   * rate from. Body state for the same reason the rest is: it came out of a step.
+   *
+   * It used to be the PREVIOUS poll, and a two-sample difference is not a
+   * throughput here: the store publishes bytes an `UPLOAD_PART_BYTES` window at a
+   * time, so consecutive polls see either no change at all — which reads as a
+   * stall and gives back the flat ceiling — or one whole 8 MiB window, an
+   * instantaneous burst rate tens of times the real average that collapses the
+   * sleep to its floor. The distribution is bimodal and neither mode is the
+   * number the estimate wants. A baseline that never moves measures exactly what
+   * the arithmetic below claims to: bytes delivered per millisecond, over the
+   * upload so far.
    */
-  let previous: UploadProgressView | undefined;
+  let baseline: UploadProgressView | undefined;
 
   for (;;) {
     const at = await ctx.step("probeUpload", () => probeUpload(input.recording));
@@ -315,6 +347,11 @@ export async function transcribeStreamFlow(input: { recording: string }, ctx: Wo
     // on a `complete` view, whose prefix is the whole file. Updating it inside a
     // branch is how it used to end up describing whichever poll last had work.
     lastSize = at.size;
+    // HERE, not after the sleep below, and that placement is the whole bug the
+    // baseline replaced: the `continue` on a batch of ready segments skipped the
+    // old `previous = at`, so the next rate was computed against a view taken
+    // before the batch. Set once, before any branch can be taken.
+    baseline ??= at;
 
     // The header has to be present before anything can be planned, and it is the
     // first thing to arrive. `complete` also qualifies, for a recording shorter
@@ -381,8 +418,7 @@ export async function transcribeStreamFlow(input: { recording: string }, ctx: Wo
     // Sleep until the next segment should HAVE landed, rather than for a fixed
     // interval — see `nextPollDelay`. Both arguments are journaled step results,
     // so a replay computes the same delay from the same two samples.
-    await ctx.sleep("poll", nextPollDelay(at, previous, plan, done));
-    previous = at;
+    await ctx.sleep("poll", nextPollDelay(at, baseline, plan, done));
   }
 
   const finished = plan;
@@ -429,8 +465,16 @@ export async function probeUpload(id: string): Promise<UploadProgressView> {
  * The flat {@link POLL_INTERVAL_MS} this replaced is wrong in both directions on a
  * slow uplink: too long when a segment is seconds away, and equally too long when
  * it is a minute away, so the run discovers work late and then asks again pointlessly.
- * Two consecutive polls give a byte RATE, the plan gives the byte offset the next
- * un-transcribed segment needs, and the difference is a wait with a reason.
+ * The run's FIRST poll and its latest one give a byte RATE, the plan gives the byte
+ * offset the next un-transcribed segment needs, and the difference is a wait with a
+ * reason.
+ *
+ * **`baseline` is the first poll of the run and never moves**, so what this reads is
+ * the AVERAGE throughput rather than a first difference between two adjacent polls.
+ * That is not a refinement: bytes are published an `UPLOAD_PART_BYTES` window at a
+ * time, so a two-sample difference is 0 or one whole 8 MiB window and never the
+ * rate — see the body's own note where the baseline is set. The arithmetic below is
+ * unchanged, which is why it is the CALLER that had the bug.
  *
  * Every input is a journaled step result — both views, and a plan derived from one —
  * so a replay computes the identical delay. That is the whole reason
@@ -445,15 +489,16 @@ export async function probeUpload(id: string): Promise<UploadProgressView> {
  */
 export function nextPollDelay(
   at: UploadProgressView,
-  previous: UploadProgressView | undefined,
+  baseline: UploadProgressView | undefined,
   plan: StreamPlan | undefined,
   done: ReadonlySet<number>,
 ): number {
-  // No previous sample, or a clock that did not advance: nothing to derive a rate
-  // from. The first sleep of every run takes this arm.
-  const elapsedMs = previous ? at.observedAt - previous.observedAt : 0;
-  if (!previous || elapsedMs <= 0) return POLL_INTERVAL_MS;
-  const bytesPerMs = (at.stored - previous.stored) / elapsedMs;
+  // No baseline, or a clock that has not advanced past it: nothing to derive a
+  // rate from. The first sleep of every run takes this arm, the baseline BEING
+  // that poll.
+  const elapsedMs = baseline ? at.observedAt - baseline.observedAt : 0;
+  if (!baseline || elapsedMs <= 0) return POLL_INTERVAL_MS;
+  const bytesPerMs = (at.stored - baseline.stored) / elapsedMs;
   // A stalled or shrinking upload has no arrival to predict. `MAX_IDLE_POLLS` is
   // what ends that run; this only declines to guess about it.
   if (bytesPerMs <= 0) return POLL_INTERVAL_MS;
@@ -476,7 +521,13 @@ export function nextPollDelay(
   // Every segment is already stored: the loop is waiting on `complete`, which is a
   // flag the uploader sets rather than bytes to extrapolate.
   if (remaining === undefined) return POLL_INTERVAL_MS;
-  if (remaining <= 0) return MIN_POLL_INTERVAL_MS;
+  // There is no `remaining <= 0` arm, and there used to be one returning the
+  // floor. It was UNREACHABLE from the body — `bytesUntilStored` answers 0 only
+  // when `segmentStored` does, which would have put the segment in `ready` and
+  // taken the `continue` above, and the no-plan arm is only taken while
+  // `at.size < HEADER_PROBE_BYTES` — and REDUNDANT besides: `Math.ceil` of a
+  // non-positive quotient is non-positive, so the `Math.max` below already
+  // answers the floor for it. Deleting it changes no answer for any input.
   return Math.min(
     POLL_INTERVAL_MS,
     Math.max(MIN_POLL_INTERVAL_MS, Math.ceil(remaining / bytesPerMs)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "12.0.0",
+  "version": "13.0.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -50,18 +50,18 @@
     "ofetch": "^1.5.1",
     "p-debounce": "^5.1.0",
     "p-timeout": "^7.0.1",
-    "vite": "^8.2.1",
-    "zod": "^4.4.3",
-    "@alexkroman1/aai-runtime": "12.0.0",
-    "@alexkroman1/aai": "12.0.0",
-    "@alexkroman1/aai-ui": "12.0.0"
+    "vite": "^8.2.2",
+    "zod": "^4.5.4",
+    "@alexkroman1/aai": "13.0.0",
+    "@alexkroman1/aai-runtime": "13.0.0",
+    "@alexkroman1/aai-ui": "13.0.0"
   },
   "devDependencies": {
     "playwright": "^1.62.1",
     "tsdown": "^0.22.14",
-    "verdaccio": "^6.9.2",
-    "vitest": "^4.1.10",
-    "aai-templates": "0.3.9"
+    "verdaccio": "^6.10.1",
+    "vitest": "^4.1.11",
+    "aai-templates": "0.3.10"
   },
   "peerDependencies": {
     "vitest": "^4.1.10"