@alexkroman1/aai-cli 9.2.0 → 10.0.0

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

@@ -13,19 +13,25 @@
  * The workflow BODY is not tested here: it is only durable once the Workflow
  * DevKit's build has transformed it, so a unit test of it would exercise a plain
  * async function and prove nothing about replay. Its STEPS are, and directly —
- * imported with no bundler in the path a `"use step"` function is an ordinary
+ * a step is an ordinary exported async function, so
  * async function, so its HTML handling, its JSON contract with the model and its
  * `FatalError` guards are all testable.
  */
 
-import { schemaInputIssues } from "@alexkroman1/aai/testing";
+import { createWorkflowCtx, schemaInputIssues } from "@alexkroman1/aai/testing";
 import {
   installStubStepFetch,
   installStubGateway as stubGateway,
 } from "@alexkroman1/aai/testing/vitest";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import agentDef, { digest } from "./agent.ts";
-import { extractText, extractTitle, fetchArticle, summarize } from "./workflows/digest.ts";
+import {
+  digestFlow,
+  extractText,
+  extractTitle,
+  fetchArticle,
+  summarize,
+} from "./workflows/digest.ts";
 
 describe("the agent declares itself a workflow app", () => {
   test("under the name the page starts a run by", () => {
@@ -208,7 +214,21 @@ describe("summarize", () => {
     await expect(summarize(ARTICLE)).rejects.toThrow(/ASSEMBLYAI_API_KEY/);
   });
 
-  test("retries beyond the default, because a rate limit and a bad format both happen", () => {
-    expect(summarize.maxRetries).toBeGreaterThan(3);
+  test("is called with more attempts than the default, because a rate limit and a bad format both happen", async () => {
+    // The retry policy is an argument to `ctx.step` now, not a `maxRetries`
+    // property on the function — so the assertion is about the BODY's call,
+    // which is the only place the policy is observable at all. `runSteps: false`
+    // because the subject is the declared policy rather than the work: the steps
+    // would otherwise need a page and a model.
+    const ctx = createWorkflowCtx({ runSteps: false });
+    await digestFlow({ url: "https://example.com/a" }, ctx);
+
+    const summarizeStep = ctx.steps.find((step) => step.name === "summarize");
+    expect(summarizeStep?.maxAttempts).toBeGreaterThan(3);
+    // The order is the body's, and it is worth pinning beside the policy: the
+    // fetch is separate from the model call precisely so a rate-limited
+    // summarize replays the fetch from the journal instead of hitting a
+    // stranger's server again.
+    expect(ctx.steps.map((step) => step.name)).toEqual(["fetchArticle", "summarize", "file"]);
   });
 });

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

@@ -9,8 +9,30 @@
  *
  * What replaces `useSession()` is `useWorkflowSubmit()`: it starts the run,
  * follows its STATUS, and hands back the controls bound to it — `wake`, `cancel`
- * and `reset`. The API is durable, so the `runId` is the whole state — it
- * survives a reload, a different device, or `curl`.
+ * and `reset`.
+ *
+ * ## The run survives a reload; the run ID does not
+ *
+ * A `runId` names a run for as long as anything is holding it, and this page
+ * holds it in React state — so a refresh loses it while the run carries on
+ * without it. That is the wrong half of durability to leave to the reader: the
+ * page used to promise "the run continues without it" and then had no way back
+ * to the run it was promising about.
+ *
+ * `key` is the handle that survives, and `recover` is what reads it back. Two
+ * lines of wiring, one decision:
+ *
+ * - **The key is OPAQUE and lives in `sessionStorage`.** It names nothing about
+ *   the person or the link — `useRunKey()` is the SDK's, and its module argues
+ *   what that rules out (a key derived from the URL being digested, a `?key=`
+ *   parameter) and why. Six templates had written those twenty lines each.
+ * - **`recover: true`** makes the hook ask `find("digest", key)` as it mounts
+ *   and follow whatever run comes back, so a reload lands back on the same
+ *   headline, the same progress log and the same buttons.
+ *
+ * Deployed, this needs the correlation-key index, which is a `DATABASE_URL`
+ * away — `agent.ts` says what happens without one (the runs are still durable;
+ * the index that finds them by key is in memory).
  *
  * ## The FORM here is still written by hand, deliberately
  *
@@ -31,13 +53,16 @@
  * cheap: one stream each, ended by the agent when there is nothing left to say.
  *
  * Progress also REPLAYS — chunks are retained with the run — so a reload mid-run
- * catches up rather than starting from whatever arrives next. `lines={1}` is
+ * catches up rather than starting from whatever arrives next. That only pays off
+ * because the reload can name its run again: `<WorkflowProgress runId>` is handed
+ * `run?.runId`, so before `recover` a refresh replayed a log for nobody.
+ * `lines={1}` is
  * what narrows it to the newest line, because on a page this small that is the
  * whole of what a status wants; `transcription-workflow` renders the full log,
  * where a fan-out makes the history worth seeing.
  */
 
-import { page, useWorkflowSubmit, WorkflowProgress } from "@alexkroman1/aai-ui";
+import { page, useRunKey, useWorkflowSubmit, WorkflowProgress } from "@alexkroman1/aai-ui";
 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/
@@ -45,20 +70,52 @@ import "@alexkroman1/aai-ui/styles.css";
 import { useState } from "react";
 import type { digest } from "./agent.ts";
 
+/**
+ * What the page says while something is in flight — three situations, one line
+ * each, and none of them the sentence this page used to print.
+ *
+ * That one was "You can close this tab — the run continues without it": true
+ * about the run and false about the page, which is the worst shape a reassurance
+ * can have. The run did continue and the tab could never find it again. Now it
+ * can, so the promise gets stronger and the reload case gets its own words —
+ * somebody who did not press the button is owed an explanation for the work
+ * appearing in front of them.
+ */
+function pendingNote(startedHere: boolean, found: boolean): string {
+  if (startedHere)
+    return "You can close this tab or reload it — this page will find the run again.";
+  if (!found) return "Looking for a digest this tab started earlier…";
+  return "Still working on the digest this tab started earlier. Reloading is safe.";
+}
+
 export function App() {
   const [url, setUrl] = useState("");
+  // This tab's handle on its own runs — minted once and remembered, which is
+  // what a later load produces to find the run again.
+  const key = useRunKey();
+  // Did THIS load start the run? A reload cannot have, and that is the only way
+  // the page can tell "working on what you just submitted" from "picking up
+  // where you left off" — 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, which is better copy than anything this page could write, and
   // `wake` is bound to whatever run the hook is following — the whole reason this
   // page no longer holds a `createWorkflowApi()` of its own.
-  const { submit, run, pending, error, wake } = useWorkflowSubmit<typeof digest>("digest");
+  const { submit, run, pending, error, wake } = useWorkflowSubmit<typeof digest>("digest", {
+    // Recorded with the run, and read back on the next load. Neither half is
+    // useful alone: without the key there is nothing to find the run by, and
+    // without `recover` the key is only ever written.
+    key,
+    recover: true,
+  });
 
   // `submit()` resolves as soon as the run exists — deliberately not when it
   // finishes. That is the whole mechanism: the digest sleeps for a while, and
   // this page is free to be closed in the meantime.
   const onSubmit = (event: React.FormEvent) => {
     event.preventDefault();
+    setStartedHere(true);
     void submit({ url });
   };
 
@@ -90,8 +147,9 @@ export function App() {
 
       {/* A run that has not settled says so. `pending` is not derivable from the
           snapshot alone — an id the agent never knew leaves `run` undefined,
-          which would otherwise read as "still waiting" forever. */}
-      {pending && <p>You can close this tab — the run continues without it.</p>}
+          which would otherwise read as "still waiting" forever, and on a reload
+          it is also true while the run is being looked up by key. */}
+      {pending && <p>{pendingNote(startedHere, run !== undefined)}</p>}
 
       {/* The run's own narration, newest line only. `lines={1}` is the window;
           everything else — the replay, and the "serves no stream" case that is

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

@@ -1,7 +1,7 @@
 // Copyright 2026 the AAI authors. MIT license.
 /**
- * The durable half of the link digest: a `"use workflow"` body and its steps,
- * and the steps really read the page and really call a model.
+ * The durable half of the link digest: a workflow body and its steps, and the
+ * steps really read the page and really call a model.
  *
  * The rules are the same ones `research-workflow/workflows/research.ts` spells out
  * — the body is replayed from the top on every resume, so it holds no live
@@ -24,14 +24,19 @@
  * fetched text crosses a queue between them, which is what the cap on it is for.
  */
 
+import type { WorkflowCtx } from "@alexkroman1/aai";
 import { report } from "@alexkroman1/aai/step";
-import { stepFetchOk, stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
+import { FatalError, stepFetchOk, stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
 import { decodeHtmlEntities } from "@alexkroman1/aai/utils";
-import { FatalError, sleep } from "workflow";
 import { z } from "zod";
 
-/** How long the digest sits before it is filed, so the wait is visible in dev. */
-const SETTLE = "10 seconds";
+/**
+ * How long the digest sits before it is filed, so the wait is visible in dev.
+ *
+ * Milliseconds. `ctx.sleep` takes a number or a `Date` and no duration STRING —
+ * one more parser to own, and no call site in the repo passed one.
+ */
+export const SETTLE_MS = 10_000;
 
 /**
  * Characters of article text carried between the two steps.
@@ -86,31 +91,36 @@ export type Article = {
  * literally the page's render model, and `WorkflowOutputOf<typeof digest>` in
  * `client.tsx` is that type, derived rather than restated.
  */
-export async function digestFlow(input: { url: string }) {
-  "use workflow";
-
-  const article = await fetchArticle(input.url);
-  const digest = await summarize(article);
+export async function digestFlow(input: { url: string }, ctx: WorkflowCtx) {
+  const article = await ctx.step("fetchArticle", () => fetchArticle(input.url));
+  // `maxAttempts: 6` was `summarize.maxRetries = 5` — five retries AFTER the
+  // first attempt, so six in all. The retry policy moved from a property on the
+  // function to the CALL, which is where it belongs: the same function called
+  // from two places may deserve different patience, and a property could not say
+  // so. A rate limit and a model that ignored the format are both expected here.
+  const digest = await ctx.step("summarize", () => summarize(article), { maxAttempts: 6 });
 
   // Suspended, not blocked: the sandbox is free to exit here and the run
-  // resumes when it comes due. Nothing about the code changes if it is
-  // `"6 hours"` — which is the interesting version, and the one that makes an
+  // resumes when it comes due. Nothing about the code changes if it is six
+  // hours — which is the interesting version, and the one that makes an
   // overnight digest a digest rather than a slow request.
-  await sleep(SETTLE);
+  await ctx.sleep(SETTLE_MS);
 
-  return { ...digest, filedAt: await file(digest) };
+  const filedAt = await ctx.step("file", () => file(digest));
+  return { ...digest, filedAt };
 }
 
 /**
  * Read the page.
  *
- * A step, so it runs once per successful execution and its result is journaled;
- * a replay returns that result instead of fetching again — which matters here
- * more than usual, because the far side is somebody else's web server.
+ * An ORDINARY exported async function — what makes it a step is the
+ * `ctx.step("fetchArticle", …)` that calls it, so it runs once per successful
+ * execution and its result is journaled; a replay returns that result instead of
+ * fetching again, which matters here more than usual because the far side is
+ * somebody else's web server. Being ordinary is also what lets `agent.test.ts`
+ * call it directly with no engine in the path.
  */
 export async function fetchArticle(url: string): Promise<Article> {
-  "use step";
-
   const { hostname } = new URL(url);
   await report(`Reading ${hostname}…`);
 
@@ -124,7 +134,7 @@ export async function fetchArticle(url: string): Promise<Article> {
   // `stepFetchOk` rather than `stepFetch` + an `ok` check: it makes the
   // retryable/terminal split for us — a 404 or a 403 answers the same way on
   // the fourth attempt, while a rate limit is exactly what retries are for, and
-  // its `Retry-After` reaches the DevKit's schedule instead of the default
+  // its `Retry-After` reaches the engine's schedule instead of the default
   // backoff. It also puts the server's own error text in the message.
   const response = await stepFetchOk(url, {
     // Some sites answer a bare request with a challenge page; asking for HTML
@@ -156,8 +166,6 @@ export async function fetchArticle(url: string): Promise<Article> {
  * whole Node runtime is available here, unlike in the body.
  */
 export async function summarize(article: Article): Promise<Digest> {
-  "use step";
-
   await report("Pulling out the claims worth keeping.");
 
   // `stepGenerateJsonClassified` unwraps the fence a model puts around JSON,
@@ -183,9 +191,6 @@ export async function summarize(article: Article): Promise<Digest> {
   };
 }
 
-/** A rate limit — and a model that ignored the format — are both expected here. */
-summarize.maxRetries = 5;
-
 /**
  * File the digest.
  *
@@ -193,11 +198,16 @@ summarize.maxRetries = 5;
  * replays the expensive half for free and re-issues only the cheap one.
  * Returning the timestamp rather than reading a clock in the BODY is the same
  * rule — a step's result is journaled and therefore stable across replays,
- * where `Date.now()` in the body would change on every one.
+ * where the same read in the body would change on every one.
+ *
+ * The `new Date()` below is therefore a BASELINED occurrence of
+ * `guard-invariants` rule 30, and this is the reason: it is inside a step, not
+ * inside a body. The rule bans a clock read anywhere in a shipped `workflows/`
+ * file because the `ctx.step` callback boundary is not decidable from a line;
+ * `digestFlow` is what reaches this one, as `ctx.step("file", () =>
+ * file(digest))`. Anything at BODY level is the bug, not an exception.
  */
 export async function file(_digest: Digest): Promise<string> {
-  "use step";
-
   await report("Filing the digest.");
   // A real desk would write the digest to its database here. The stub writes
   // nothing, which is what the `_` says — and it is a stub because `ctx.db` is

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

@@ -32,7 +32,7 @@
 //
 // WHAT NO EVAL HERE COVERS: durability — which for THIS template is most of
 // what it is for. Imported through vitest with no bundler in the path, a
-// `"use workflow"` body is an ordinary async function, so the multi-day
+// workflow body is an ordinary async function, so the multi-day
 // suspension that makes a digest arrive tomorrow is not exercised; the sleep is
 // RECORDED and skipped. `run.slept` below is that admission written as an
 // assertion, and it is the only way to check a seven-day schedule without
@@ -43,7 +43,7 @@ import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
 import { describeWorkflowEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import agentDef, { dailyDigest } from "./agent.ts";
-import { MAX_POLL_ATTEMPTS, POLL_DELAY, scheduleIntervalMs } from "./workflows/digest.ts";
+import { MAX_POLL_ATTEMPTS, POLL_DELAY_MS, scheduleIntervalMs } from "./workflows/digest.ts";
 
 /** The feed every case reads. Not a real host — nothing here leaves the process. */
 const FEED_URL = "https://feeds.example.test/rebuild.xml";
@@ -320,9 +320,9 @@ describeWorkflowEval(agentDef, (test) => {
     expect(world.calls.filter((call) => call.url.includes("/v2/transcript/"))).toHaveLength(5);
     // Three waits for four rounds — asked for, and recorded rather than taken.
     expect(run.slept).toEqual([
-      { duration: POLL_DELAY },
-      { duration: POLL_DELAY },
-      { duration: POLL_DELAY },
+      { duration: POLL_DELAY_MS },
+      { duration: POLL_DELAY_MS },
+      { duration: POLL_DELAY_MS },
     ]);
 
     // And the digest is in PUBLICATION order, not completion order. The feed is

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

@@ -10,7 +10,7 @@
  * - The DECLARATION — the config a deploy validates and the schema a `start()`
  *   is checked against.
  * - The PURE helpers, pulled out of the flow for exactly this reason.
- * - The STEPS, directly. Imported with no bundler in the path a `"use step"`
+ * - The STEPS, directly. A step is an ordinary exported async function, so one
  *   function is an ordinary async function, so its HTTP handling, its
  *   partial-failure policy and its `FatalError` guards are all reachable —
  *   `installStubStepFetch` answers the network and `stubGateway` answers the model.
@@ -21,7 +21,7 @@
  * that fails to transcribe taking the whole digest down with it.
  */
 
-import { parseSchemaInput, schemaInputIssues } from "@alexkroman1/aai/testing";
+import { createWorkflowCtx, parseSchemaInput, schemaInputIssues } from "@alexkroman1/aai/testing";
 import {
   installStubStepFetch,
   installStubGateway as stubGateway,
@@ -29,7 +29,9 @@ import {
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import agentDef, { dailyDigest } from "./agent.ts";
 import {
+  dailyDigestFlow,
   formatScheduleInterval,
+  POLL_DELAY_MS,
   pollTranscript,
   scheduleIntervalMs,
   submitTranscript,
@@ -714,3 +716,107 @@ describe("posting the digest", () => {
     expect((err as Error).name).not.toBe("FatalError");
   });
 });
+
+describe("the body — the run that IS the schedule", () => {
+  /**
+   * The body driven end to end with no I/O.
+   *
+   * `runSteps: false` plus a skeleton of results: what this pins is the body's
+   * own logic — the digest loop, the shrinking pending set in
+   * `waitForTranscripts`, and the sleep between digests — none of which any
+   * per-step spec can see, and all of which is the template's actual subject.
+   */
+  function driveTwoDigests(pollResults: unknown) {
+    const ctx = createWorkflowCtx({
+      runSteps: false,
+      results: {
+        discoverEpisodes: [EPISODE],
+        submitTranscript: { id: EPISODE.id, transcriptId: "t_1" },
+        pollTranscript: pollResults,
+        summarizeTranscript: EPISODE,
+        postDigest: { ok: true },
+        timestamp: "2026-08-21T00:00:00.000Z",
+      },
+    });
+    return { ctx };
+  }
+
+  test("sends one digest per interval and sleeps BETWEEN them, never after the last", async () => {
+    // A run that has delivered everything it owes should end, not sleep for a
+    // day and then end.
+    const { ctx } = driveTwoDigests({
+      id: EPISODE.id,
+      transcriptStatus: "completed",
+      transcript: "words",
+    });
+
+    const output = await dailyDigestFlow(
+      {
+        ...VALID,
+        slackWorkflowTextParam: "text",
+        daysToRun: 2,
+        maxEpisodesPerDigest: 1,
+        intervalEvery: 2,
+        intervalUnit: "hours",
+      },
+      ctx,
+    );
+
+    expect(output.digestsSent).toBe(2);
+    expect(output.digestsScheduled).toBe(2);
+    // Two digests, ONE sleep.
+    expect(ctx.slept).toHaveLength(1);
+    expect(ctx.slept[0]?.until).toBe(scheduleIntervalMs(2, "hours"));
+    expect(ctx.steps.filter((step) => step.name === "postDigest")).toHaveLength(2);
+  });
+
+  test("reports the last digest it actually sent", async () => {
+    const { ctx } = driveTwoDigests({
+      id: EPISODE.id,
+      transcriptStatus: "completed",
+      transcript: "words",
+    });
+
+    const output = await dailyDigestFlow(
+      {
+        ...VALID,
+        slackWorkflowTextParam: "text",
+        daysToRun: 1,
+        maxEpisodesPerDigest: 1,
+        intervalEvery: 1,
+        intervalUnit: "days",
+      },
+      ctx,
+    );
+
+    expect(output.lastDigest).toMatchObject({
+      sentAt: "2026-08-21T00:00:00.000Z",
+      episodes: [EPISODE],
+    });
+    expect(ctx.slept).toEqual([]);
+  });
+
+  test("gives up on an episode that never finishes rather than failing the digest", async () => {
+    // Running out of poll rounds is NOT an error: a partial digest beats none,
+    // and the reason is printed where a reader will see it. The poll answers
+    // `submitted` forever, so the loop exhausts its rounds.
+    const { ctx } = driveTwoDigests({ id: EPISODE.id, transcriptStatus: "submitted" });
+
+    const output = await dailyDigestFlow(
+      {
+        ...VALID,
+        slackWorkflowTextParam: "text",
+        daysToRun: 1,
+        maxEpisodesPerDigest: 1,
+        intervalEvery: 1,
+        intervalUnit: "days",
+      },
+      ctx,
+    );
+
+    expect(output.digestsSent).toBe(1);
+    // Every round slept except the last, which is what bounds the wait.
+    expect(ctx.slept.length).toBeGreaterThan(0);
+    for (const sleep of ctx.slept) expect(sleep.until).toBe(POLL_DELAY_MS);
+  });
+});

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

@@ -5,9 +5,46 @@
  *
  * Mounted with `page()` rather than `client()`: 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. The API
- * is durable, so the `runId` is the whole state — it survives a reload, another
- * device, or `curl`.
+ * the run, follows its STATUS, and hands back the controls bound to it.
+ *
+ * ## The `runId` is durable; the PAGE holding it was not
+ *
+ * This doc used to say the run id "survives a reload, another device, or
+ * `curl`", and every word of that is true of the id and none of it was true of
+ * this page: the id lived in React state, so a refresh dropped it while a
+ * schedule that may run for a month carried on posting. That is the worst case
+ * in `templates/` for losing a handle — the other workflow apps lose a wait of
+ * minutes, this one loses the only Stop button a thirty-digest commitment has,
+ * and the run is invisible from then on to everything but `curl`.
+ *
+ * `key` is the handle that survives and `recover: true` is what reads it back,
+ * so a later load lands on the same count, the same newest line, and the same
+ * Wake and Cancel buttons bound to the same run.
+ *
+ * **The key is `useRunKey({ storage: "local" })`, and this is the one workflow
+ * app that passes that option.** Its siblings take the default,
+ * `sessionStorage`, which dies with the tab and covers exactly the interruption
+ * they have — a reload, a same-tab navigation, a crashed tab. A schedule
+ * outlives all of that by design: closing the browser on Tuesday and coming
+ * back on Friday to stop it is the ordinary case here, not an edge one, and a
+ * tab-scoped key would answer that with an empty form beside a run still
+ * posting to somebody's Slack. So the handle is scoped to the BROWSER, which is
+ * as far as it can go without a login (`find` has no per-user filtering; the
+ * key is the whole scoping mechanism) — and no further:
+ *
+ * - **Not the page's own URL.** A `?key=` parameter is pasted into chats,
+ *   copied into referrers and kept in history, and what a leaked one buys here
+ *   is not just reading the digest: it is `cancel()` on somebody's schedule,
+ *   and a completed run's output NAMES the delivery target it has been posting
+ *   to.
+ * - **Not derived from the feeds or the webhook.** Two people watching the same
+ *   show would recover each other's schedules, and a key derived from a webhook
+ *   URL would carry a credential into a lookup token — which is why the
+ *   platform stopped writing keys to the operator's log.
+ *
+ * A real app with accounts passes the account's own id instead, and then the
+ * schedule follows the person to a new device — a promise only a login can
+ * keep.
  *
  * ## The form is DECLARED, not written
  *
@@ -51,6 +88,7 @@ import {
   Form,
   page,
   SubmitButton,
+  useRunKey,
   useWorkflowSubmit,
   WorkflowFields,
   WorkflowProgress,
@@ -59,18 +97,54 @@ 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 })`. */
 const WORKFLOW = "dailyDigest";
 
+/**
+ * What the page says while a schedule is live — three situations, one line
+ * each, and none of them the sentence this page used to print.
+ *
+ * That one was "You can close this tab — the run continues without it": true
+ * about the run and false about the page, which is the worst shape a
+ * reassurance can have. The run did continue, for up to a month, and nothing
+ * could name it again. Now the promise can be stronger AND narrower — this
+ * browser, not any tab anywhere — and the load that did not press the button
+ * gets its own words, because a schedule appearing in front of somebody is owed
+ * an explanation.
+ */
+function pendingNote(startedHere: boolean, found: boolean): string {
+  if (startedHere)
+    return "You can close this tab — the digest keeps posting, and this browser will find it again.";
+  if (!found) return "Looking for a schedule this browser started earlier…";
+  return "This is a schedule this browser started earlier. It is still posting.";
+}
+
 export function App() {
+  // This BROWSER's handle on its schedules — minted once and kept for as long
+  // as storage lives for this origin, which is the option this template exists
+  // to argue for. See the module doc.
+  const key = useRunKey({ storage: "local" });
+  // 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.
-  const { submitForm, run, pending, error, wake, cancel } =
-    useWorkflowSubmit<typeof dailyDigest>(WORKFLOW);
+  const { submitForm, run, pending, error, wake, cancel } = useWorkflowSubmit<typeof dailyDigest>(
+    WORKFLOW,
+    {
+      // Recorded with the run, and read back on the next load. Neither half is
+      // useful alone: without the key there is nothing to find the run by, and
+      // without `recover` the key is only ever written.
+      key,
+      recover: true,
+    },
+  );
 
   return (
     <main className="mx-auto flex max-w-2xl flex-col gap-6 p-8">
@@ -78,7 +152,13 @@ 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={submitForm} error={error}>
+      <Form
+        onSubmit={(values) => {
+          setStartedHere(true);
+          return submitForm(values);
+        }}
+        error={error}
+      >
         <WorkflowFields workflow={WORKFLOW} />
         <SubmitButton pending={pending}>
           {pending ? "Digest scheduled" : "Start digest"}
@@ -87,8 +167,9 @@ export function App() {
 
       {/* A run that has not settled says so. `pending` is not derivable from the
           snapshot alone — an id the agent never knew leaves `run` undefined,
-          which would otherwise read as "still waiting" forever. */}
-      {pending && <p>You can close this tab — the run continues without it.</p>}
+          which would otherwise read as "still waiting" forever, and on a later
+          load it is also true while the schedule is being looked up by key. */}
+      {pending && <p>{pendingNote(startedHere, run !== undefined)}</p>}
 
       {/* The run's own narration, newest line only. `lines={1}` is the window;
           everything else — the replay, and the "serves no stream" case that is