@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/templates/pizza-ordering/tools/add_pizza.ts

@@ -1,5 +1,6 @@
+import { formatMoney } from "@alexkroman1/aai/utils";
 import { z } from "zod";
-import { CRUSTS, calculateTotal, formatPrice, orderSlot, type Pizza, SIZES } from "../shared.ts";
+import { CRUSTS, calculateTotal, orderSlot, type Pizza, SIZES } from "../shared.ts";
 
 export default orderSlot.updateTool({
   description: "Add a pizza to the order. Use when the customer has decided on a pizza.",
@@ -24,7 +25,7 @@ export default orderSlot.updateTool({
 
     return {
       added: pizza,
-      orderTotal: formatPrice(calculateTotal(order.pizzas)),
+      orderTotal: formatMoney(calculateTotal(order.pizzas)),
       itemCount: order.pizzas.length,
     };
   },

package/dist/templates/pizza-ordering/tools/place_order.ts

@@ -1,5 +1,6 @@
 import { toolFailure } from "@alexkroman1/aai";
-import { calculateTotal, formatPrice, orderSlot, resetOrder } from "../shared.ts";
+import { formatMoney } from "@alexkroman1/aai/utils";
+import { calculateTotal, orderSlot, resetOrder } from "../shared.ts";
 
 export default orderSlot.updateTool({
   description:
@@ -9,7 +10,7 @@ export default orderSlot.updateTool({
     if (pizzas.length === 0) return toolFailure("Cannot place an empty order.");
 
     const customerName = order.customerName ?? "Guest";
-    const total = formatPrice(calculateTotal(pizzas));
+    const total = formatMoney(calculateTotal(pizzas));
     const orderNumber = Math.floor(1000 + Math.random() * 9000);
 
     const estimatedMinutes = 15 + pizzas.length * 5;

package/dist/templates/pizza-ordering/tools/remove_pizza.ts

@@ -1,6 +1,7 @@
 import { toolFailure } from "@alexkroman1/aai";
+import { formatMoney } from "@alexkroman1/aai/utils";
 import { z } from "zod";
-import { calculateTotal, formatPrice, orderSlot } from "../shared.ts";
+import { calculateTotal, orderSlot } from "../shared.ts";
 
 export default orderSlot.updateTool({
   description: "Remove a pizza from the order by its ID.",
@@ -15,7 +16,7 @@ export default orderSlot.updateTool({
 
     return {
       removed,
-      orderTotal: formatPrice(calculateTotal(order.pizzas)),
+      orderTotal: formatMoney(calculateTotal(order.pizzas)),
       itemCount: order.pizzas.length,
     };
   },

package/dist/templates/pizza-ordering/tools/update_pizza.ts

@@ -1,6 +1,7 @@
 import { toolFailure } from "@alexkroman1/aai";
+import { formatMoney } from "@alexkroman1/aai/utils";
 import { z } from "zod";
-import { CRUSTS, calculateTotal, formatPrice, orderSlot, type Pizza, SIZES } from "../shared.ts";
+import { CRUSTS, calculateTotal, orderSlot, type Pizza, SIZES } from "../shared.ts";
 
 export default orderSlot.updateTool({
   description: "Update an existing pizza in the order. Only provided fields are changed.",
@@ -23,6 +24,6 @@ export default orderSlot.updateTool({
 
     order.pizzas[idx] = pizza;
 
-    return { updated: pizza, orderTotal: formatPrice(calculateTotal(order.pizzas)) };
+    return { updated: pizza, orderTotal: formatMoney(calculateTotal(order.pizzas)) };
   },
 });

package/dist/templates/pizza-ordering/tools/view_order.ts

@@ -1,4 +1,5 @@
-import { calculateTotal, formatPrice, orderSlot } from "../shared.ts";
+import { formatMoney } from "@alexkroman1/aai/utils";
+import { calculateTotal, orderSlot } from "../shared.ts";
 
 export default orderSlot.tool({
   description: "View the current order summary with all pizzas and total price.",
@@ -15,7 +16,7 @@ export default orderSlot.tool({
         toppings: p.toppings,
         quantity: p.quantity,
       })),
-      orderTotal: formatPrice(calculateTotal(pizzas)),
+      orderTotal: formatMoney(calculateTotal(pizzas)),
     };
   },
 });

package/dist/templates/plan-and-execute/agent.test.ts

@@ -1,7 +1,12 @@
 /** The def a DEPLOYED agent runs: authored, plus what `tools/` declares. */
 import agentDef from "virtual:aai/agent";
 import type { ToolContext } from "@alexkroman1/aai";
-import { createToolContext, okPosition, stubGenerate, toolRunner } from "@alexkroman1/aai/testing";
+import {
+  createToolContext,
+  expectDialogOk,
+  stubGenerate,
+  toolRunner,
+} from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 
 import { executeStep, MAX_STEP_SEARCHES, normalizeAct, planNode } from "./procedure.ts";
@@ -216,7 +221,7 @@ describe("work_next_step", () => {
     const ctx = createToolContext({ generate });
     await run("start_plan", { objective: "a weekend in Lisbon" }, ctx);
 
-    const first = okPosition<{
+    const first = expectDialogOk<{
       finished: boolean;
       step: string;
       result: string;
@@ -243,7 +248,7 @@ describe("work_next_step", () => {
     });
     const ctx = createToolContext({ generate });
     await run("start_plan", { objective: "a weekend in Lisbon" }, ctx);
-    const answered = okPosition<{ finished: boolean; response: string }>(
+    const answered = expectDialogOk<{ finished: boolean; response: string }>(
       await run("work_next_step", ctx),
     );
 
@@ -327,7 +332,7 @@ describe("revise_plan", () => {
     await run("work_next_step", ctx);
     expect(stateOf(ctx).response).not.toBeNull();
 
-    const revised = okPosition<{ finished: boolean; remaining: string[] }>(
+    const revised = expectDialogOk<{ finished: boolean; remaining: string[] }>(
       await run("revise_plan", { instruction: "make it Porto instead" }, ctx),
     );
     expect(revised.result.finished).toBe(false);
@@ -362,7 +367,7 @@ describe("revise_plan", () => {
     });
     const ctx = createToolContext({ generate });
     await run("start_plan", { objective: "a weekend in Lisbon" }, ctx);
-    const revised = okPosition<{ finished: boolean }>(
+    const revised = expectDialogOk<{ finished: boolean }>(
       await run("revise_plan", { instruction: "never mind, it is booked" }, ctx),
     );
     expect(revised.result.finished).toBe(true);

package/dist/templates/plan-and-execute/client.tsx

@@ -1,5 +1,5 @@
 import "@alexkroman1/aai-ui/styles.css";
-import { AutoScroll, client, useAgentState } from "@alexkroman1/aai-ui";
+import { AutoScroll, mountClient, useAgentState } from "@alexkroman1/aai-ui";
 import { planProjection } from "./shared.ts";
 
 /**
@@ -90,7 +90,7 @@ function PlanSidebar() {
   );
 }
 
-client({
+mountClient({
   name: "Planning Desk",
   sidebar: PlanSidebar,
   theme: {

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

@@ -11,7 +11,7 @@
  *   HTTP handling, its partial-failure policy and its `FatalError` guards are
  *   all reachable — `installStubStepFetch` answers the network and
  *   `stubGateway` answers the model.
- * - The BODY, twice. `createWorkflowCtx` records what it asked for (the digest
+ * - The BODY, twice. `createWorkflowContext` records what it asked for (the digest
  *   loop, the shrinking pending set, the sleep BETWEEN digests and never after
  *   the last), and `runWorkflow` runs it on the real replay engine — which is
  *   what this file used to say a unit test could not do, on the ground that a
@@ -26,8 +26,9 @@
 
 import { type FeedItem, parseFeed } from "@alexkroman1/aai/html";
 import {
-  createWorkflowCtx,
+  createWorkflowContext,
   parseSchemaInput,
+  routeStepFetch,
   schemaInputIssues,
   stubGatewayRoute,
 } from "@alexkroman1/aai/testing";
@@ -422,12 +423,20 @@ const THREE_EPISODES = feedXml(
  * the thing that forgets, and a step fetch left published reaches the next file.
  */
 function stubRoutes(routes: Record<string, { status?: number; body?: unknown }>) {
-  return installStubStepFetch((request) => {
-    for (const [fragment, answer] of Object.entries(routes)) {
-      if (request.url.includes(fragment)) return answer;
-    }
-    return { status: 404, body: `no route for ${request.url}` };
-  });
+  return installStubStepFetch(
+    routeStepFetch(
+      Object.entries(routes).map(
+        ([fragment, answer]) =>
+          (request) =>
+            request.url.includes(fragment) ? answer : undefined,
+      ),
+      // A 404 rather than the default throw, and this one is deliberate: several
+      // cases below are ABOUT a feed the run cannot reach, and they express that
+      // by leaving it out of `routes`. Where an unrecognised request would be a
+      // finding instead, the default is what says so at the call.
+      { unmatched: "notFound" },
+    ),
+  );
 }
 
 describe("discoverEpisodes", () => {
@@ -837,7 +846,7 @@ describe("posting the digest", () => {
   });
 
   /**
-   * The 4xx/5xx split is the reason this is not a one-line `stepFetchOk`: a
+   * The 4xx/5xx split is the reason this is not a one-line `stepFetchOrFail`: a
    * revoked webhook answers 4xx identically on every retry, so retrying it
    * burns the DevKit's attempts and delays the real error by minutes.
    */
@@ -876,7 +885,7 @@ describe("the body — the run that IS the schedule", () => {
    * per-step spec can see, and all of which is the template's actual subject.
    */
   function driveTwoDigests(pollResults: unknown) {
-    const ctx = createWorkflowCtx({
+    const ctx = createWorkflowContext({
       runSteps: false,
       results: {
         discoverEpisodes: [EPISODE],
@@ -973,7 +982,7 @@ describe("the body — the run that IS the schedule", () => {
 /**
  * The schedule, on the real replay engine.
  *
- * The block above drives the same body through `createWorkflowCtx`, which
+ * The block above drives the same body through `createWorkflowContext`, which
  * RECORDS a sleep rather than taking one and replays nothing — right for the
  * loop's logic, and silent about the property this template is: a run that
  * sleeps for a day between digests and comes back. `runWorkflow`

package/dist/templates/podcast-digest/client.tsx

@@ -3,7 +3,7 @@
  * The browser half — a form that starts a run, and a panel that watches one
  * that may outlive the browser by a week.
  *
- * Mounted with `page()` rather than `client()`: there is no session to build, so
+ * Mounted with `mountPage()` rather than `mountClient()`: there is no session to build, so
  * no socket, no audio graph, no microphone request. `useWorkflowSubmit()` starts
  * the run, follows its STATUS, and hands back the controls bound to it.
  *
@@ -86,8 +86,9 @@
  */
 
 import {
+  BulletList,
   Form,
-  page,
+  mountPage,
   SubmitButton,
   useRunKey,
   useWorkflowSubmit,
@@ -98,7 +99,6 @@ import "@alexkroman1/aai-ui/styles.css";
 // ERASED at build time, so naming the agent's own type costs the browser bundle
 // nothing — and it is what stops this file restating a shape `workflows/
 // digest.ts` already declares.
-import { useState } from "react";
 import type { dailyDigest } from "./agent.ts";
 
 /** The workflow this page drives. Matches the key in `workflowApp({ workflows })`. */
@@ -131,17 +131,15 @@ export function App() {
   // Did THIS load start the schedule? A later load cannot have, and that is the
   // only way the page can tell "scheduled just now" from "still running from
   // Tuesday" — the hook reports the run, not who asked for it.
-  const [startedHere, setStartedHere] = useState(false);
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
   // `run.output` instead of `unknown`. `error` is the agent's own sentence for a
   // rejected input — better copy than anything this page could write, and the
   // reason there is no `try`/`catch` here.
   // The key REPLACES the tab-scoped one the hook would mint; the lookup that
   // reads it back on the next load happens either way.
-  const { submitForm, run, pending, error, wake, cancel } = useWorkflowSubmit<typeof dailyDigest>(
-    WORKFLOW,
-    { key },
-  );
+  const { submitForm, run, pending, error, wake, cancel, startedHere } = useWorkflowSubmit<
+    typeof dailyDigest
+  >(WORKFLOW, { key });
 
   return (
     <main className="mx-auto flex max-w-2xl flex-col gap-6 p-8">
@@ -149,13 +147,7 @@ export function App() {
 
       {/* `submit()` resolves as soon as the run EXISTS — deliberately not when it
           finishes, which here could be a month away. */}
-      <Form
-        onSubmit={(values) => {
-          setStartedHere(true);
-          return submitForm(values);
-        }}
-        error={error}
-      >
+      <Form onSubmit={(values) => submitForm(values)} error={error}>
         <WorkflowFields workflow={WORKFLOW} />
         <SubmitButton pending={pending}>
           {pending ? "Digest scheduled" : "Start digest"}
@@ -195,7 +187,13 @@ export function App() {
         </div>
       )}
 
-      {run?.status === "failed" && <p className="text-red-600">That run failed: {run.error}</p>}
+      {/* `role="alert"`, the same contract `<Form>` gives the submit error
+          above: a digest that fails does so days later, with nobody watching. */}
+      {run?.status === "failed" && (
+        <p role="alert" className="text-red-600">
+          That run failed: {run.error}
+        </p>
+      )}
       {run?.status === "cancelled" && <p>Cancelled — no further digests will be posted.</p>}
 
       {run?.status === "completed" && (
@@ -213,11 +211,7 @@ export function App() {
                 </a>
               </h2>
               <p>{episode.summary}</p>
-              <ul className="flex list-disc flex-col gap-1 pl-5 text-sm">
-                {episode.keyPoints.map((point) => (
-                  <li key={point}>{point}</li>
-                ))}
-              </ul>
+              <BulletList items={episode.keyPoints} size="sm" />
             </section>
           ))}
         </article>
@@ -226,4 +220,4 @@ export function App() {
   );
 }
 
-page({ name: "Podcast Digest", component: App });
+mountPage({ name: "Podcast Digest", component: App });

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

@@ -49,13 +49,13 @@
  * @module digest
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
-import { mapConcurrent, report, TRANSCRIBE_API } from "@alexkroman1/aai/step";
+import type { WorkflowContext } from "@alexkroman1/aai";
+import { mapConcurrent, stepReport, TRANSCRIBE_API } from "@alexkroman1/aai/step";
 import {
   FatalError,
-  stepGenerateJsonClassified,
-  stepTranscribePollClassified,
-  stepTranscribeSubmitClassified,
+  stepGenerateJsonOrFail,
+  stepTranscribePollOrFail,
+  stepTranscribeSubmitOrFail,
 } from "@alexkroman1/aai/step-errors";
 import { errorMessage } from "@alexkroman1/aai/utils";
 import type { WorkflowInputOf } from "@alexkroman1/aai/workflow-api";
@@ -160,7 +160,7 @@ export type DailyDigestOutput = {
   } | null;
 };
 
-/** What the model must answer with, and what `stepGenerateJsonClassified` enforces. */
+/** What the model must answer with, and what `stepGenerateJsonOrFail` enforces. */
 const SummaryReply = z.object({
   summary: z.string().trim().min(1),
   keyPoints: z.array(z.string().trim().min(1)).min(1).max(5),
@@ -178,7 +178,7 @@ const SummaryReply = z.object({
  */
 export async function dailyDigestFlow(
   input: DigestInput,
-  ctx: WorkflowCtx,
+  ctx: WorkflowContext,
 ): Promise<DailyDigestOutput> {
   // No `??` fallbacks: {@link DigestInput} is the schema's OUTPUT, so every
   // `.default()` has already run by the time a run reaches this line. The
@@ -269,7 +269,7 @@ export async function dailyDigestFlow(
  */
 async function waitForTranscripts(
   jobs: TranscriptJob[],
-  ctx: WorkflowCtx,
+  ctx: WorkflowContext,
 ): Promise<TranscriptState[]> {
   let pending = jobs;
   // Keyed by episode id rather than appended, and that is what keeps the digest
@@ -287,17 +287,19 @@ async function waitForTranscripts(
     if (pending.length > 0) await ctx.sleep("poll", POLL_DELAY_MS);
   }
 
-  for (const job of pending) settled.set(job.id, gaveUpOn(job));
   // The list `jobs` arrived in, which `discoverEpisodes` sorted newest first.
+  // A job still pending is absent from `settled`, so the `??` IS the
+  // give-up path — `pollTranscript` returns the job unchanged while it is
+  // submitted, so the value given up on is the one that went in.
   return jobs.map((job) => settled.get(job.id) ?? gaveUpOn(job));
 }
 
 /**
  * One episode the run is done waiting for.
  *
- * Its own function because {@link waitForTranscripts} needs it in two places —
- * the jobs still pending when the budget ran out, and the unreachable fallback
- * the ordered rebuild above needs for a lookup that cannot miss.
+ * Its own function because {@link waitForTranscripts} reaches it from the
+ * ordered rebuild, for every job whose budget ran out while it was still
+ * submitted and which is therefore absent from `settled`.
  */
 function gaveUpOn(job: TranscriptJob): TranscriptState {
   return {
@@ -322,7 +324,7 @@ function gaveUpOn(job: TranscriptJob): TranscriptState {
  * an `unavailable` VALUE rather than a throw, because one bad episode must not
  * sink a digest of five.
  *
- * The verdict itself is the SDK's: `stepTranscribeSubmitClassified` reads
+ * The verdict itself is the SDK's: `stepTranscribeSubmitOrFail` reads
  * `TranscribeError`'s own `retryable` AND its `retryAfter`, and throws a
  * `FatalError` or a `RetryableError` accordingly. The hand-written
  * `err instanceof TranscribeError && err.retryable` this replaces read only the
@@ -330,9 +332,9 @@ function gaveUpOn(job: TranscriptJob): TranscriptState {
  * one-second default instead.
  */
 export async function submitTranscript(episode: Episode): Promise<TranscriptJob> {
-  await report(`Submitting ${episode.title} for transcription.`);
+  await stepReport(`Submitting ${episode.title} for transcription.`);
   try {
-    const { id } = await stepTranscribeSubmitClassified(episode.audioUrl, {
+    const { id } = await stepTranscribeSubmitOrFail(episode.audioUrl, {
       // A digest quotes nobody, so who spoke costs time for nothing.
       params: { speaker_labels: false },
     });
@@ -356,12 +358,12 @@ export async function pollTranscript(job: TranscriptJob): Promise<TranscriptStat
   if (job.transcriptStatus === "unavailable") return job;
 
   try {
-    const progress = await stepTranscribePollClassified(job.transcriptId);
+    const progress = await stepTranscribePollOrFail(job.transcriptId);
     // Branch on `done`, never on a status string: a vocabulary this body does
     // not own would otherwise read as "not finished yet" forever.
     if (!progress.done) return job;
 
-    await report(`Transcribed ${job.title}.`);
+    await stepReport(`Transcribed ${job.title}.`);
     return {
       ...job,
       transcriptStatus: "done",
@@ -391,8 +393,8 @@ export async function summarizeTranscript(state: TranscriptState): Promise<Episo
     };
   }
 
-  await report(`Summarizing ${state.title}.`);
-  const parsed = await stepGenerateJsonClassified(
+  await stepReport(`Summarizing ${state.title}.`);
+  const parsed = await stepGenerateJsonOrFail(
     [
       `Podcast: ${state.podcastTitle}`,
       `Episode: ${state.title}`,

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

@@ -64,9 +64,9 @@
  * parsing. It is the section below's subject, not this one's.
  */
 
-import { type FeedItem, pageMetadata, parseFeed } from "@alexkroman1/aai/html";
-import { report } from "@alexkroman1/aai/step";
-import { FatalError, stepFetchOk } from "@alexkroman1/aai/step-errors";
+import { type FeedItem, type ParsedFeed, pageMetadata, parseFeed } from "@alexkroman1/aai/html";
+import { mapConcurrent, stepReport } from "@alexkroman1/aai/step";
+import { FatalError, stepFetchOrFail } from "@alexkroman1/aai/step-errors";
 import { isRecord, omitUndefined, safeJsonParse } from "@alexkroman1/aai/utils";
 import { z } from "zod";
 
@@ -74,19 +74,32 @@ import { z } from "zod";
 const REQUEST_TIMEOUT_MS = 30_000;
 
 /**
- * A show, reduced to what the rest of the run needs — plus the body, when
- * resolving it already had to download one.
+ * How many pasted links are resolved at once.
  *
- * `xml` is the difference between one request per feed and two. Both web paths
- * fetch the feed to decide whether it IS a feed (`looksLikePodcastFeed`), and
- * without somewhere to put that body the reader downloads the identical
- * document a second time. The Apple and Spotify paths resolve a URL without
- * ever reading the feed, so they leave it unset and the reader fetches once.
+ * Small because the far side is Apple and Spotify, who rate-limit, and because
+ * a digest is a handful of shows rather than a fan-out — the win is turning N
+ * sequential round trips into a couple of overlapped ones, not saturating a
+ * link.
+ */
+const RESOLVE_CONCURRENCY = 4;
+
+/**
+ * A show, reduced to what the rest of the run needs — plus the PARSE, when
+ * resolving it already had to do one.
+ *
+ * `parsed` is the difference between one request per feed and two, and between
+ * one parse and three. Both web paths fetch the feed to decide whether it IS a
+ * feed, and without somewhere to put the result the reader downloads and
+ * re-parses the identical document. Re-parsing is the more expensive half:
+ * `parseFeed` builds a DOM and runs `htmlToText` over every item's title AND
+ * description, and a podcast feed routinely carries 300+ entries of HTML show
+ * notes. The Apple and Spotify paths resolve a URL without ever reading the
+ * feed, so they leave it unset and the reader fetches once.
  */
 export type PodcastFeed = {
   feedUrl: string;
   title: string;
-  xml?: string;
+  parsed?: ParsedFeed;
 };
 
 /** One episode with audio attached — the unit everything downstream works on. */
@@ -114,12 +127,17 @@ export async function discoverEpisodes(
   podcastChannels: string,
   maxEpisodes: number,
 ): Promise<Episode[]> {
-  await report("Finding recent podcast episodes.");
+  await stepReport("Finding recent podcast episodes.");
   const links = parsePodcastChannels(podcastChannels);
   if (links.length === 0) throw new FatalError("Add at least one podcast link.");
 
-  const feeds: PodcastFeed[] = [];
-  for (const url of links) feeds.push(await resolvePodcastFeed(url));
+  // Overlapped, not sequential: each resolution is one to three HTTP round
+  // trips with a 30s ceiling, and the links are independent. Bounded rather
+  // than a bare `Promise.all` because Apple and Spotify both rate-limit — and
+  // legal here because this whole function is a STEP BODY (`ctx.step` wraps it
+  // in `digest.ts`), so the journal's name+occurrence rule does not apply to
+  // what happens inside it.
+  const feeds = await mapConcurrent(links, RESOLVE_CONCURRENCY, resolvePodcastFeed);
 
   const episodes = (await Promise.all(feeds.map((feed) => readPodcastFeed(feed))))
     .flat()
@@ -154,7 +172,10 @@ async function resolvePodcastFeed(url: string): Promise<PodcastFeed> {
  */
 async function resolveWebPodcastFeed(url: string): Promise<PodcastFeed> {
   const body = await fetchText(url);
-  if (looksLikePodcastFeed(body)) return feedFrom(url, body);
+  // Parsed ONCE and carried: the "is this a feed" test, the channel title and
+  // the item list are three reads of one parse, not three parses.
+  const direct = parseFeed(body);
+  if (carriesAudio(direct)) return feedFrom(url, direct);
 
   const discovered = discoverFeedUrl(body, url);
   if (!discovered) {
@@ -167,9 +188,9 @@ async function resolveWebPodcastFeed(url: string): Promise<PodcastFeed> {
   // The advertised URL is verified rather than trusted: plenty of pages point
   // `application/rss+xml` at a blog feed with no audio in it, and finding that
   // out here names the page, where finding it out later names an empty digest.
-  // The body is carried forward rather than re-fetched — see `PodcastFeed.xml`.
-  const verified = await fetchText(discovered);
-  if (!looksLikePodcastFeed(verified)) {
+  // The parse is carried forward rather than redone — see `PodcastFeed.parsed`.
+  const verified = parseFeed(await fetchText(discovered));
+  if (!carriesAudio(verified)) {
     throw new FatalError(`The feed at ${discovered} does not look like a podcast RSS feed.`);
   }
   return feedFrom(discovered, verified);
@@ -236,8 +257,9 @@ async function resolveSpotifyPodcastFeed(url: string): Promise<PodcastFeed> {
 
 /** Every item in the feed that has audio attached, newest first by the caller. */
 async function readPodcastFeed(feed: PodcastFeed): Promise<Episode[]> {
-  const xml = feed.xml ?? (await fetchText(feed.feedUrl));
-  const parsed = parseFeed(xml);
+  // Already parsed on the web paths; the Apple and Spotify paths resolve a URL
+  // without ever reading the feed, so this is where those two download it.
+  const parsed = feed.parsed ?? parseFeed(await fetchText(feed.feedUrl));
   // `parsed.title` is the CHANNEL's, which is the whole reason to parse: the
   // `indexOf` read this replaces took the first `<title>` at any depth.
   const podcastTitle = parsed?.title ?? feed.title;
@@ -393,17 +415,23 @@ export function titleMatchesSpotify(
   );
 }
 
-/** A feed document that actually carries audio — both halves are required. */
-export function looksLikePodcastFeed(xml: string): boolean {
-  const parsed = parseFeed(xml);
-  // `parseFeed` answering at all is the "is this a feed" half, and it is
-  // stricter than the `<rss` test it replaces in the direction that matters:
-  // an HTML page mentioning `<rss` in prose is not a feed. It is also wider
-  // where being wide is right — an Atom podcast feed has no `<rss` root and
-  // was refused outright.
+/**
+ * A parse that actually carries audio — both halves are required.
+ *
+ * `parseFeed` answering at all is the "is this a feed" half, and it is stricter
+ * than the `<rss` test it replaces in the direction that matters: an HTML page
+ * mentioning `<rss` in prose is not a feed. It is also wider where being wide is
+ * right — an Atom podcast feed has no `<rss` root and was refused outright.
+ */
+function carriesAudio(parsed: ParsedFeed | undefined): parsed is ParsedFeed {
   return parsed?.items.some((item) => item.enclosureUrl !== undefined) ?? false;
 }
 
+/** {@link carriesAudio} over a document that has not been parsed yet. */
+export function looksLikePodcastFeed(xml: string): boolean {
+  return carriesAudio(parseFeed(xml));
+}
+
 /** The first feed a page advertises, resolved against the page's own URL. */
 export function discoverFeedUrl(html: string, pageUrl: string): string | undefined {
   // `pageMetadata` reads `<link>` off a parse, so attribute ORDER stops
@@ -441,11 +469,11 @@ function publishedAt(episode: Episode): number {
   return Number.isNaN(parsed) ? 0 : parsed;
 }
 
-function feedFrom(feedUrl: string, body: string): PodcastFeed {
+function feedFrom(feedUrl: string, parsed: ParsedFeed): PodcastFeed {
   return {
     feedUrl,
-    title: parseFeed(body)?.title ?? hostOf(feedUrl),
-    xml: body,
+    title: parsed.title ?? hostOf(feedUrl),
+    parsed,
   };
 }
 
@@ -529,7 +557,7 @@ function appleResults(body: unknown): AppleResult[] {
 /**
  * Every outbound call in this file, with one timeout and one failure policy.
  *
- * `stepFetchOk` is `stepFetch` plus the non-2xx branch — see its own doc. Three
+ * `stepFetchOrFail` is `stepFetch` plus the non-2xx branch — see its own doc. Three
  * things come with it that a bare `fetch` here would each have to re-derive:
  * HTTP/1.1 (so a rate limit arrives as a `503` with `Retry-After` rather than
  * an h2 stream reset carrying no status), the transient/terminal verdict the
@@ -537,7 +565,7 @@ function appleResults(body: unknown): AppleResult[] {
  * the iTunes endpoints is the difference between "403" and a sentence.
  */
 async function fetchText(url: string): Promise<string> {
-  const response = await stepFetchOk(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+  const response = await stepFetchOrFail(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
   return await response.text();
 }