@asrunjs/asrun 0.13.0 → 0.14.0

package/.claude/skills/exploring-cases/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: exploring-cases
-description: Explores the real pages for one case document (cases/<id>.md) before its spec is generated, for every logged-in profile or only the ones named with --profiles. Checks the case against profiles.yaml and the pages, fixes wording mistakes, records what the pages show, turns unknowns into answerable TODO blocks, and, in an attended run, lets the person do the steps that write data or need a choice while it waits and records a general recipe under that step's `- Recipe:` lines. Also writes a local exploration note (locators and data-call paths) under `.explore/` for `/gen-spec` to verify instead of rediscovering. Ends with RESULT ready or needs-input. Use when asked to explore, review, check, clean up or narrow down a case, or for /explore-case. Its open-question rules are shared with generating-specs.
+description: Explores the real pages for one case document (cases/<id>.md) before its spec is generated, for the profiles named with --profiles or, without it, for at least one logged-in profile per domain. Checks the case against profiles.yaml and the pages, fixes wording mistakes, records what the pages show, turns unknowns into answerable TODO blocks, and, in an attended run, lets the person do the steps that write data or need a choice while it waits and records a general recipe under that step's `- Recipe:` lines. Also writes a local exploration note (locators and data-call paths) under `.explore/` for `/gen-spec` to verify instead of rediscovering. Ends with RESULT ready or needs-input. Use when asked to explore, review, check, clean up or narrow down a case, or for /explore-case. Its open-question rules are shared with generating-specs.
 ---
 
 # Exploring a case document
@@ -54,10 +54,12 @@ one exception is a handoff in an attended run, where waiting for the person is t
   before exploring and report `RESULT: needs-input` ("pass the environment").
 - Optionally `--attended`: a person is at the machine and the browser window is visible, so handoffs may happen.
   Without it nothing waits, and a step that needs a person becomes a `[blocking]` TODO.
-- Optionally `--profiles a,b`: explore only these profiles (ids from `profiles.yaml`, comma-separated). Without it, at
-  least one logged-in profile per domain. The selection is never widened: a profile it leaves out is not opened and
-  nothing about it is written into the case. Runs add up: a later run with other profiles adds their observations and
-  `## Values` entries next to the ones recorded before.
+- Optionally `--profiles a,b`: explore only these profiles (ids from `profiles.yaml`, comma-separated): **every id in
+  the list**. Without it, at least one logged-in profile per domain. A different host is a different domain, even when
+  two profiles serve the same product on another address, so the list is never collapsed into one profile. The
+  selection is never widened: a profile it leaves out is not opened and nothing about it is written into the case.
+  Runs add up: a later run with other profiles adds their observations and `## Values` entries next to the ones
+  recorded before.
 - Optionally `--hints <file>` (or free text after the arguments): what the person knows or wants checked. Read it
   before the static review. It guides this run; after the work, a reusable instruction is written into `## Rules` by
   the gate in `references/case-rules.md`, and a one-off clue stays in the report.
@@ -90,14 +92,21 @@ one exception is a handoff in an attended run, where waiting for the person is t
    in this session at all (no `browser_*` / `generator_*` tool) or the server reports that it failed to start, do not
    fall back to ad-hoc Playwright scripts: stop, tell the user which MCP server is missing and to run `pnpm asrun
    doctor`, make no observations, and end with `RESULT: needs-input`.
-   Explore each profile `--profiles` names that is logged in, and, without `--profiles`, at least one logged-in profile
-   per domain. Never explore a profile the selection leaves out, and never add a profile to fill a gap. Profiles that
+   Explore each profile `--profiles` names that is logged in, and, without `--profiles`, one logged-in profile per
+   domain. Never explore a profile the selection leaves out, and never add a profile to fill a gap. Profiles that
    are selected but not logged in are skipped and named in the report; a human runs `pnpm signin <profile-id>`.
+   **One profile at a time, one session each.** Open it with
+   `generator_setup_page({project: '<profile-id>', seedFile: 'tests/seed.spec.ts', plan: ''})`; never call it without
+   `project` (the MCP then opens whichever project it likes). Before the first read, check that `page.url()` starts
+   with that profile's `baseURL` in `profiles.yaml`: if it does not, the wrong project is open, so open the right one
+   and record nothing from the wrong page. A different host is a different domain even when both profiles serve the
+   same product, so two named profiles mean two sessions, never one. Finish every selected profile before you start
+   writing the case.
    - Do the read-only steps yourself: open, look, read, hover, switch tabs, open and close dialogs and menus.
-   - **A step that writes or needs a choice is done by the person**, per `references/user-handoff.md`: announce it,
-     name the finish condition, run the wait loop (the card records what the person does), then write down what
-     happened from its `recorded` result. In a run that is not attended, write a `TODO [blocking]` under the step
-     instead.
+   - **A step that writes or needs a choice is done by the person**, per `references/user-handoff.md`: announce it
+     with one sentence plus one action per entry of `steps` and the finish condition in `finish`, run the wait loop
+     (the card records what the person does), then write down what happened from its `recorded` result. In a run that
+     is not attended, write a `TODO [blocking]` under the step instead.
    - Close any modal that opens by itself without confirming it (for example the follow-up modal that opens after
      publishing: close it and confirm nothing).
    - When a confirm dialog appears while closing an email composer, choose "Discard" (see `AGENTS.md`).
@@ -157,6 +166,12 @@ one exception is a handoff in an attended run, where waiting for the person is t
    line of every profile you explored must say `fresh`), and fix every FAIL. If
    `case:check` fails with a sandbox error (`listen EPERM`), run
    `node --import tsx <framework>/scripts/check-cases.ts` instead; it checks the same thing.
+   **A selected profile that is logged in gets its own note.** The note, the target card's `Reference
+   <profile-id>` and at least one observation marked with that profile id are the proof: before you report, compare the
+   selection with `.explore/notes/<case-id>/` and with the profile ids the case now names. A profile with no note that
+   was not skipped for its login was not explored: write a `TODO [blocking]` under the first step it affects (a person
+   re-runs `/explore-case` with that profile) and say so in the report; never report a run as complete for a profile
+   that was not opened. A profile skipped because it is not logged in gets no note and is named as skipped instead.
 9. **Report** in the user's language: what was changed (wording fixes, observations added, TODOs closed or narrowed),
    what was explored (profile ids), which profiles `--profiles` left out (and that a run with them covers the rest),
    which steps the person did and what was recorded for them, what the exploration note covers (and what it does not),

package/.claude/skills/exploring-cases/references/handoff-card.js

@@ -4,8 +4,25 @@ async (page) => {
   const ctx = page.context();
   const cfg = ctx.__handoffCfg || {};
   const message = cfg.message || 'Do the step, then press Done';
+  // The steps are the person's actions, one per line and numbered by the card: a handoff that needs several things
+  // never becomes one sentence nobody can follow (see user-handoff.md, "Before the handoff").
+  const steps = (Array.isArray(cfg.steps) ? cfg.steps : [])
+    .filter((step) => typeof step === 'string' && step.trim())
+    .map((step) => step.trim());
   const copy = Array.isArray(cfg.copy) ? cfg.copy : [];
   const doneText = cfg.doneText || null;
+  // The finish condition gets its own block. `doneText` is the same promise as a text the card can watch for, so an
+  // older handoff that only set it still says when the step is done.
+  const finish = typeof cfg.finish === 'string' && cfg.finish.trim()
+    ? cfg.finish.trim()
+    : doneText ? `"${doneText}" appears` : null;
+  // The finish condition usually quotes the text it waits for ("Unfavorite Article"). A handoff that left `doneText`
+  // out gets that text as its signal, so the card ends by itself; the check below drops it when the page already shows
+  // it, because a condition that holds before the person acts must never end the handoff at once.
+  const quoted = finish
+    ? ((finish.match(/["“]([^"”]{2,})["”]/) || finish.match(/'([^']{2,})'/)) || [])[1]
+    : undefined;
+  let watchedText = doneText || (quoted ? quoted.trim() : null);
   const maxMs = cfg.maxMs || 600000;
   await ctx.grantPermissions(['clipboard-read', 'clipboard-write']).catch(() => {});
 
@@ -55,7 +72,18 @@ async (page) => {
     }
   }
 
-  const paint = (p) => p.evaluate(({message, copy}) => {
+  /** True when the page's own text holds `text`: the card's text is never part of it (it quotes the condition). */
+  const pageHasText = (p, text) => p.evaluate((needle) => {
+    const lower = needle.toLowerCase();
+    if (!document.body) return false;
+    if (document.body.innerText.toLowerCase().includes(lower)) return true;
+    // Sites that render inside their own shadow roots are not in innerText.
+    return Array.from(document.querySelectorAll('*')).some((el) =>
+      el.id !== '__ASRUN_panel' && el.shadowRoot &&
+      el.shadowRoot.textContent.toLowerCase().includes(lower));
+  }, text).catch(() => false);
+
+  const paint = (p) => p.evaluate(({message, steps, finish, copy, autoEnd}) => {
     if (document.getElementById('__ASRUN_panel')) return;
     const KEY = '__ASRUN_panel_state';
     let state = {minimized: false, left: null, top: null};
@@ -74,24 +102,55 @@ async (page) => {
     host.style.cssText = 'all:initial;position:fixed;z-index:2147483647;left:16px;bottom:16px';
     const root = host.attachShadow({mode: 'open'});
     root.innerHTML = '<style>' +
-      '.card{width:300px;max-width:calc(100vw - 32px);background:#1e3340;color:#fff;font:13px/1.4 system-ui,sans-serif;border-radius:8px;box-shadow:0 6px 20px rgba(0,0,0,.35);overflow:hidden}' +
+      '.card{width:340px;max-width:calc(100vw - 32px);background:#1e3340;color:#fff;font:13px/1.4 system-ui,sans-serif;border-radius:8px;box-shadow:0 6px 20px rgba(0,0,0,.35);overflow:hidden}' +
       '.card.min{width:auto}.card.ok{background:#15803d}' +
       '.bar{display:flex;align-items:center;gap:8px;padding:7px 8px 7px 12px;background:#b45309;cursor:grab;user-select:none;touch-action:none}' +
       '.ok .bar{background:#166534;align-items:flex-start;padding-top:9px}.bar b{flex:1;min-width:0;font-size:12px;letter-spacing:.04em;white-space:nowrap}.ok .bar b{white-space:normal;line-height:1.35}.grip{display:inline-flex;opacity:.8}' +
       'button{all:unset;box-sizing:border-box;cursor:pointer;display:inline-flex;align-items:center;justify-content:center;gap:4px;padding:3px 8px;border-radius:4px;background:rgba(255,255,255,.18);color:#fff;font:600 12px system-ui,sans-serif}' +
       'button:hover{background:rgba(255,255,255,.3)}' +
-      '.body{padding:10px 12px 12px;display:flex;flex-direction:column;gap:8px}.min .body,.ok .body{display:none}' +
+      // The steps scroll on their own: a long list never pushes the finish condition or the buttons out of the card.
+      '.body{display:flex;flex-direction:column}.min .body,.ok .body{display:none}' +
+      '.content{display:flex;flex-direction:column;gap:9px;padding:10px 12px 0}' +
+      '.summary{font-weight:600;white-space:pre-wrap;overflow-wrap:anywhere}' +
+      '.steps{margin:0;padding:0 2px 0 1.6em;display:flex;flex-direction:column;gap:6px;max-height:min(30vh,240px);overflow:auto;scrollbar-width:thin;scrollbar-color:rgba(255,255,255,.35) transparent}' +
+      '.steps li{padding-left:2px;overflow-wrap:anywhere}.steps li::marker{color:#fbbf24;font-weight:700}' +
+      // A list longer than its box fades out at the bottom instead of cutting a line in half, so nobody reads it as the end.
+      '.steps.scrolly{-webkit-mask-image:linear-gradient(to bottom,#000 calc(100% - 16px),transparent);mask-image:linear-gradient(to bottom,#000 calc(100% - 16px),transparent)}' +
+      '.finish{margin:9px 12px 0;border-left:4px solid #22c55e;background:rgba(34,197,94,.18);border-radius:4px;padding:7px 10px;display:flex;flex-direction:column;gap:3px}' +
+      '.finish .label{font-size:10px;font-weight:700;letter-spacing:.1em;color:#86efac}' +
+      '.finish .cond{font-weight:600;line-height:1.35;overflow-wrap:anywhere}' +
+      '.finish .also{font-size:11px;opacity:.8}' +
       '.mini-done{display:none}.min .mini-done{display:inline-flex}' +
       '.chip{display:flex;align-items:center;gap:6px;background:rgba(0,0,0,.28);padding:4px 4px 4px 8px;border-radius:4px}' +
       '.chip span{flex:1;font:12px ui-monospace,Menlo,monospace;word-break:break-all;user-select:all}' +
-      '.row{display:flex;gap:8px}.row .primary{background:#15803d}.row .primary:hover{background:#16a34a}' +
+      '.row{display:flex;gap:8px;padding:12px}.row .primary{background:#15803d}.row .primary:hover{background:#16a34a}' +
       '</style>' +
       '<div class="card" id="card"><div class="bar" id="bar" title="Drag to move"><span class="grip">' + ICON.move + '</span><b id="title">YOUR TURN</b>' +
       '<button class="mini-done" data-a="done" aria-label="AsRun handoff: done">Done</button><button id="toggle" title="Minimize or expand" aria-label="AsRun handoff: minimize or expand"></button></div>' +
-      '<div class="body"><div id="msg"></div><div id="chips"></div><div class="row">' +
+      '<div class="body"><div class="content"><div id="msg" class="summary"></div><ol id="steps" class="steps"></ol><div id="chips"></div></div>' +
+      '<div id="finish" class="finish" style="display:none"><div class="label">DONE WHEN</div><div id="cond" class="cond"></div>' +
+      '<div id="also" class="also"></div></div>' +
+      '<div class="row">' +
       '<button class="primary" data-a="done" aria-label="AsRun handoff: done">Done</button><button data-a="skip" aria-label="AsRun handoff: cannot do this">Cannot do this</button></div></div></div>';
     const card = root.getElementById('card'), bar = root.getElementById('bar'), toggle = root.getElementById('toggle');
+    // Every text goes in through `textContent`: the message comes from an agent, never from the site under test.
     root.getElementById('msg').textContent = message;
+    const list = root.getElementById('steps');
+    if (steps.length) {
+      for (const step of steps) {
+        const item = document.createElement('li');
+        item.textContent = step;
+        list.appendChild(item);
+      }
+    } else list.style.display = 'none';
+    if (finish) {
+      root.getElementById('cond').textContent = finish;
+      // Say which way the wait can end: a card that can never notice the condition must not suggest that it will.
+      root.getElementById('also').textContent = autoEnd
+        ? 'The card ends by itself when this shows. Done also works.'
+        : 'Press Done when you are finished.';
+      root.getElementById('finish').style.display = 'flex';
+    }
     const chips = root.getElementById('chips');
     chips.style.cssText = 'display:' + (copy.length ? 'flex' : 'none') + ';flex-direction:column;gap:6px';
     for (const text of copy) {
@@ -115,6 +174,10 @@ async (page) => {
       card.classList.toggle('min', state.minimized);
       toggle.innerHTML = state.minimized ? ICON.up : ICON.down;
       root.getElementById('title').textContent = state.minimized ? 'YOUR TURN' : 'YOUR TURN: control is yours';
+      // The minimized pill hides the steps and the finish condition: keep both one hover away, so nothing is missed.
+      const hidden = state.minimized ? [message, ...steps, ...(finish ? ['Done when: ' + finish] : [])].join('\n') : null;
+      bar.title = hidden || 'Drag to move';
+      bar.setAttribute('aria-label', hidden || 'AsRun handoff: drag to move');
     };
     const place = () => {
       if (state.left === null) return;
@@ -147,10 +210,21 @@ async (page) => {
     apply();
     document.documentElement.appendChild(host);
     place();
+    // Only a list longer than its box gets the fade; a short one must not look cut off. Measured after the card is in
+    // the document: before that every height is zero. The fade goes away at the end of the list, where nothing is left.
+    const markScroll = () =>
+      list.classList.toggle('scrolly', list.scrollHeight - list.clientHeight - list.scrollTop > 1);
+    list.addEventListener('scroll', markScroll);
+    markScroll();
     if (!document.title.startsWith('YOUR TURN | ')) document.title = 'YOUR TURN | ' + document.title;
-  }, {message, copy}).catch(() => {});
+  }, {message, steps, finish, copy, autoEnd: Boolean(watchedText)}).catch(() => {});
 
   for (const p of ctx.pages()) await p.evaluate(() => { window.__handoff = null; }).catch(() => {});
+  // A text the handoff only implies (from its finish condition) is dropped when the page already shows it: it would
+  // end the handoff before the person does anything. An explicit `doneText` keeps its meaning as the agent gave it.
+  if (!doneText && watchedText) {
+    for (const p of ctx.pages()) if (await pageHasText(p, watchedText)) { watchedText = null; break; }
+  }
   const started = Date.now();
   let outcome = null;
   try {
@@ -159,7 +233,7 @@ async (page) => {
         await paint(p);
         const flag = await p.evaluate(() => window.__handoff || null).catch(() => null);
         if (flag) outcome = flag;
-        else if (doneText && await p.getByText(doneText).first().isVisible().catch(() => false)) outcome = 'condition';
+        else if (watchedText && await pageHasText(p, watchedText)) outcome = 'condition';
       }
       if (!outcome) await page.waitForTimeout(500);
     }

package/.claude/skills/exploring-cases/references/open-questions.md

@@ -45,8 +45,8 @@ Rules for writing it:
   It needs no TODO block. See "Marker or question, never both" below.
 
 ## Where the block hangs
-The parent line is the sentence the question is about: the panel shows it on its own, next to "The text above this
-question", so it has to make sense without the rest of the document.
+The parent line is the sentence the question is about: the panel shows it on its own, under "The case says", so it
+has to make sense without the rest of the document.
 - **The immediate line, not an ancestor.** Hang the block under the one sentence that makes the claim. Under a
   nested bullet, indent it under that bullet, not under the top-level one above it; when the claim only makes sense
   with an umbrella sentence, write the claim itself as a top-level bullet and hang the block there.

package/.claude/skills/exploring-cases/references/readiness.md

@@ -136,6 +136,12 @@ in the same `browser_run_code_unsafe` call that waits for the download), run
 images** and say in the card where the logo really is on each page, which pages have it and which do not, and what the
 text shows. The rendered pages are the card's `Reference`. If the logo is not where the case says, that is a question.
 
+When `pnpm pdf:render` itself fails, the install is broken — a PDF check would fail the same way once the spec runs, so
+there is nothing to explore: end with `needs-input` and name the error (`pnpm asrun doctor` says which part is
+missing). **Never substitute another renderer** (Ghostscript, an image converter, a preview from the browser): the
+baseline a spec compares against is produced by `expectPdf` and pdf.js, so a page drawn by anything else is not a
+`Reference` and the card would describe a picture that never appears again.
+
 While exploring, do the same by hand: click, wait for the download event, see the file finish, read its size and its first
 bytes. Record "(observed: <file name>, <size>, valid <kind>)".
 

package/.claude/skills/exploring-cases/references/user-handoff.md

@@ -23,15 +23,19 @@ perform this step; run /explore-case with --attended") and goes on with the rest
 that nobody watches.
 
 ## Before the handoff
-1. Say what the user has to do and when it is finished, in one or two sentences ("Fill in the form, pick two
-   items, then press Done"). Name the finish condition first (below).
-2. Put every text the user has to type into `copy` (the name of a document, a title), so it can be
+1. Say in one sentence what the handoff is about (`message`), and put what to do in `steps`, **one action per entry, in
+   the order the person does it**. The card numbers them. Never chain actions in one entry ("pick items, then press
+   Next"): a step is one thing to click, type or choose. More than about five steps is two handoffs, not one long card.
+2. Name the finish condition in `finish`, in the words of the page ("'Published' appears at the top of the page",
+   without a closing full stop), and keep it out of the steps: the card puts it in its own highlighted "DONE WHEN"
+   block. `doneText` is the same condition as a text the card can watch for (see "Finish condition").
+3. Put every text the user has to type into `copy` (the name of a document, a title), so it can be
    copied with one click. Build a created name with the project's test-data prefix (default `[asrun]`, printed by
    `pnpm asrun rules`) and a run stamp: `<prefix> <base> (<YYYY-MM-DD HH-mm-ss>, UTC)`, the same shape
    `testDataName()` builds. The stamp is chosen now, not recorded in the recipe.
-3. Never ask the user to send email (production: never; other environments: only when `email` is `true` for the
+4. Never ask the user to send email (production: never; other environments: only when `email` is `true` for the
    profile). Never ask for login or 2FA. Name everything the user creates `<prefix> <something> (<run stamp>)`.
-4. Do not start a recording yourself: the card starts and stops it (see "Recording"). Never call
+5. Do not start a recording yourself: the card starts and stops it (see "Recording"). Never call
    `browser_start_recording` or `browser_stop_recording`: the `playwright-test` MCP lists them but cannot run them
    (`devtools` tools; see `tools.md`).
 
@@ -39,9 +43,14 @@ that nobody watches.
 Run it with one `browser_run_code_unsafe` call. A single call may wait for minutes (verified: 150 s without a
 timeout), so no polling from outside is needed. The loop:
 
-- **Shows a small floating card, not a bar.** It sits in the bottom-left corner and only the card takes clicks, so
-  nothing of the page is covered or blocked. The user can **drag** it by its title bar and **minimize** it to a small
-  pill that still has a Done button. Position and minimized state survive a page reload (kept in `sessionStorage`).
+- **Shows a small floating card, not a bar.** It reads top to bottom: one sentence about the handoff, the steps as a
+  numbered list, a line per text to copy, and the finish condition in its own green "DONE WHEN" block at the bottom,
+  with a line under it that says whether the card ends by itself. A list longer than its box scrolls (and fades at the
+  edge), while the finish condition and the buttons stay in view.
+  It sits in the bottom-left corner and only the card takes clicks, so nothing of the page is covered or blocked. The
+  user can **drag** it by its title bar and **minimize** it to a small pill that still has a Done button (its tooltip
+  keeps the steps and the finish condition). Position and minimized state survive a page reload (kept in
+  `sessionStorage`).
 - **Click to copy.** Every text in `copy` (for example the `<prefix> <name> (<run stamp>)` the user has to type) is shown on its
   own line with a copy icon; one click puts it on the clipboard and the icon shows "Copied". Pass only text that the
   case says to type; leave `copy` empty when there is none.
@@ -72,9 +81,14 @@ badge, no count in the tab title and no notification (a HINT in the job log says
    // browser_run_code_unsafe({intent: 'set the handoff card options', code: ...})
    async (page) => {
      page.context().__handoffCfg = {
-       message: '<what the user does, one sentence>',
+       message: '<what this handoff is for, one sentence>',
+       steps: [                   // one action per entry, in order: the card numbers them
+         '<first thing to do>',
+         '<next thing to do>',
+       ],
+       finish: '<what the page shows when it is done, in the page\'s own words, no full stop>',
        copy: [],                  // texts to type, e.g. ['[autotest] published document (2026-11-09 12-34-56)']
-       doneText: null,            // text that appears when finished, or null
+       doneText: '<the exact text that appears when it is done>', // so the card ends by itself (see below)
        maxMs: 600000,
      };
      return 'cfg set';
@@ -89,26 +103,44 @@ badge, no count in the tab title and no notification (a HINT in the job log says
    the recording was unavailable (`recording: false`; `recordingError` says why).
 
 Check once, after the card shows, that it looks right: take a screenshot and see a title bar with a move icon, a
-chevron button at its right and, when `copy` is not empty, a line per text with a copy icon. Playwright's own recording
-toolbar at the top of the page is expected and is not part of the card. If the card is not right, stop and report it;
-do not hand off with a broken card.
-
-Tell the user in the chat (the terminal or the UI job log) as well: "Your turn in the browser window: <task>. Press
-Done on the card (bottom-left; drag it if it is in the way) when you finish." When the run was started from the web
-UI, the UI notices the handoff by itself (it sees the `__handoffCfg` call and the `handoff-card.js` call, whether the
-browser tool is called directly or through the CLI's code mode, as OpenCode's `execute` tool does) and shows the
-"Your turn" badge, a count in the tab title and, if the person switched notifications on, a browser notification;
-this is why the message in `__handoffCfg` must be a plain string literal. A macOS notification is a bonus and may
-fail in a sandbox: `osascript -e 'display notification "<task>" with title "AsRun" sound name "Glass"'`. If it
-fails, go on.
+chevron button at its right, the message as one line, the steps numbered, the finish condition in its own green
+"DONE WHEN" block saying "The card ends by itself when this shows", and, when `copy` is not empty, a line per text
+with a copy icon. The Done button must be visible without scrolling. Playwright's own recording toolbar at the top of
+the page is expected and is not part of the card. If the card is not right (or says "Press Done when you are
+finished"), fix `doneText` before you hand the step over.
+
+Tell the user in the chat (the terminal or the UI job log) as well: "Your turn in the browser window: <task>. Done
+when <finish condition>. Press Done on the card (bottom-left; drag it if it is in the way) when you finish." Name the
+finish condition there too, not only on the card. When the run was started from the web UI, the UI notices the handoff
+by itself (it sees the `__handoffCfg` call and the `handoff-card.js` call, whether the browser tool is called directly
+or through the CLI's code mode, as OpenCode's `execute` tool does) and shows the "Your turn" badge, a count in the tab
+title and a desktop notification saying what to do and when it is done — this is why the message and the finish
+condition in `__handoffCfg` must be plain string literals. The UI server shows that notification itself; **never send
+one yourself** (`osascript`, `notify-send`, a toast): a CLI that refuses a shell call leaves a failed call in the job
+log, and the person gets nothing either way.
 
 ## Finish condition
-Pick one that the page can show, before the handoff, and write it into the message of the card:
+Pick one that the page can show, before the handoff, and write it into `finish`, where the card shows it alone:
 - a text that appears (a "Saved" toast, the title of the next step) or one that goes away;
 - a URL that the page reaches;
 - an element that appears or disappears (an editor that closes).
 
-The Done button is always there (also on the minimized card) as the fallback, and "Cannot do this" lets the user give up a step.
+**Also give `doneText`: the exact text that is not on the page yet and shows up when the step is done** (the new
+button label, the toast, the heading of the next screen). Without it the card cannot notice the condition and waits for
+the person to press Done, which is the one thing a handoff must not need every time. Only a condition that carries no
+text at all (a URL, an empty editor) may leave it out.
+
+- Both must agree: nobody should read "DONE WHEN ..." on the card while `doneText` watches for something else.
+- Quote the *new* text, not the one that is already there: `doneText: 'Unfavorite Article'`, never `'Favorite Article'`
+  when the button already reads that.
+- If `finish` quotes a text and `doneText` is missing, the card uses that quoted text as its signal — but only when the
+  page did not show it when the card appeared, so a condition that already held can never end the handoff at once.
+  Relying on that is a mistake: set `doneText` yourself.
+- The block says which way the wait ends: "The card ends by itself when this shows. Done also works." when the card can
+  notice the condition, "Press Done when you are finished." when it cannot. Read that line on the screenshot: a
+  handoff that will never end by itself is a handoff to fix, not to run.
+- The Done button is always there (also on the minimized card) as the fallback, and "Cannot do this" lets the user give
+  up a step.
 
 ## After the handoff
 - The card turns green and says control is back ("Done: control is back with Playwright. Do not touch the page.")
@@ -116,9 +148,10 @@ The Done button is always there (also on the minimized card) as the fallback, an
 - `outcome: 'timeout'` or `'skip'`: do not guess. Write a `TODO [blocking]` under the step and go on with what does
   not depend on it.
 - Take a snapshot, write down what the user did from the card's `recorded` (see "Recording"), then continue read-only.
-- At the end of the exploration hand off once more when the user created data: "Delete the test items you
-  created (they start with <the project's prefix> and carry this run's timestamp), then press Done". The case must
-  clean up after itself, and so must the exploration.
+- At the end of the exploration hand off once more when the user created data, with the same shape as any other
+  handoff: `message` "Clean up the test items this run created", `steps` = "Open the list", "Delete the items that
+  start with <prefix> and carry this run's timestamp", `finish` = "the list holds no item of this run any more". The
+  case must clean up after itself, and so must the exploration.
 
 ## Recording
 The card records what the person does: it starts the recording when it shows and stops it on every way out (Done,

package/AGENTS.md

@@ -77,8 +77,9 @@ These apply to every agent that drives a browser to explore pages for cases or s
 - **B1 — Read-only for the agent.** Open, look, read, hover, switch tabs, open and close dialogs and menus.
   Everything that writes is the person's (see F3).
 - **B2 — Waiting for a person.** Only in an attended run. Announce the task in the browser window (a small draggable
-  card with a Done button and click-to-copy for texts to type), name the finish condition, wait, and tell the person
-  when control is back. The card starts and stops the recording itself and returns `recorded`; never call
+  card that lists the steps as a numbered list, shows the finish condition in its own block, has a Done button and
+  click-to-copy for texts to type), wait, and tell the person when control is back. The card starts and stops the
+  recording itself and returns `recorded`; never call
   `browser_start_recording` or `browser_stop_recording`: the `playwright-test` MCP lists many browser tools it cannot
   run (`devtools`, `storage`, `network`, `pdf`, `vision`, and the `skillOnly` ones such as `browser_network_clear`),
   and the substitutes for each are in `<framework>/.claude/skills/exploring-cases/references/tools.md`. Record what

package/README.md

@@ -29,7 +29,7 @@ AsRun is a devDependency, not a service. Your profiles, cases, specs and baselin
 
 ## Requirements
 
-- **Node.js 22+** and **pnpm**.
+- **Node.js 22.13+** and **pnpm**.
 - **ffmpeg** to join the recordings of one test into a video. `pnpm go` installs it with Homebrew or winget; on Linux
   run `sudo apt install ffmpeg`. When it is missing, `pnpm go` / `pnpm asrun init` install the bundled `ffmpeg-static`
   into the workspace; if neither works, the report lists the videos separately.

package/dist/lib/desktop-notify.d.ts

@@ -0,0 +1,38 @@
+/** One notification, already reduced to what a person reads at a glance. */
+export interface DesktopNotification {
+    title: string;
+    body: string;
+    /** Ask for the platform's attention sound. Ignored where the platform has none. */
+    sound?: boolean;
+}
+/** The command that shows a notification: spawned directly, never through a shell. */
+export interface NotifyCommand {
+    file: string;
+    args: string[];
+}
+/** What came of one attempt, for `pnpm asrun notify-test` and for the hint a failure leaves in a job log. */
+export interface NotifyOutcome {
+    /** The command, as a person would type it; null when this platform has no notifier at all. */
+    command: string | null;
+    ok: boolean;
+    /** Why nothing was shown, when it was not. */
+    reason?: string;
+}
+/**
+ * The command one notification runs on this platform. Pure: the text is escaped here, so a message with quotes,
+ * Chinese or a colon cannot break the command. Null only for a platform with no notifier.
+ */
+export declare function notificationCommand(platform: NodeJS.Platform, notification: DesktopNotification): NotifyCommand | null;
+/** A command as a person would type it, cut short: a toast script is hundreds of characters long. */
+export declare function describeCommand(command: NotifyCommand): string;
+/**
+ * Shows one notification and waits for the command to end. Used by `pnpm asrun notify-test`, which has to report
+ * whether the operating system took it; the server uses `notifyDesktop` instead.
+ */
+export declare function sendNotification(notification: DesktopNotification): Promise<NotifyOutcome>;
+/**
+ * Shows one notification without waiting for it. The same text is sent once per few seconds, so two events of one
+ * handoff (the options call and the card) do not ring twice. `onError` says why nothing was shown, for a hint in the
+ * job log; it is never called on success.
+ */
+export declare function notifyDesktop(notification: DesktopNotification, onError?: (reason: string) => void): void;

package/dist/lib/desktop-notify.js

@@ -0,0 +1,158 @@
+import { spawn } from 'node:child_process';
+import { spawnTarget } from './command.js';
+/** A notification holds a line or two; the rest would be cut by the desktop anyway. */
+const MAX_TEXT = 240;
+/** The same notification twice in a row (a handoff reported by two events) is shown once. */
+const DEDUPE_MS = 5_000;
+/** A notifier that has not finished by now is a broken one, not a slow one. */
+const TIMEOUT_MS = 10_000;
+/** What went out recently, so the same text is not shown again by the next event of the same handoff. */
+const recent = new Map();
+/** A notification's text is one line: a line break in the body is read as the end of the notification. */
+function oneLine(value) {
+    return value
+        .replace(/[\r\n\t\f\v]+/g, ' ')
+        .replace(/ {2,}/g, ' ')
+        .trim()
+        .slice(0, MAX_TEXT);
+}
+/** A string in an AppleScript literal: a backslash escapes, so both it and the quote have to be escaped themselves. */
+const appleScriptText = (value) => value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+/** XML text of a Windows toast: the five characters that would end the element early. */
+const xmlText = (value) => value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+/** A PowerShell single-quoted literal: only a single quote is special inside it, and it is doubled. */
+const powerShellText = (value) => value.replace(/'/g, "''");
+/**
+ * Windows toast through Windows PowerShell (not pwsh: it has no WinRT). The app id is the one Windows PowerShell
+ * itself registers, so an unregistered toast does not silently disappear on a machine with nothing else installed.
+ */
+function toastScript(title, body, sound) {
+    const toast = '<toast><visual><binding template="ToastGeneric">' +
+        `<text>${xmlText(title)}</text><text>${xmlText(body)}</text>` +
+        '</binding></visual>' +
+        (sound ? '<audio src="ms-winsoundevent:Notification.Reminder"/>' : '<audio silent="true"/>') +
+        '</toast>';
+    return [
+        "$ErrorActionPreference='Stop'",
+        '[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime] > $null',
+        '[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType=WindowsRuntime] > $null',
+        '$xml=New-Object Windows.Data.Xml.Dom.XmlDocument',
+        `$xml.LoadXml('${powerShellText(toast)}')`,
+        '$toast=[Windows.UI.Notifications.ToastNotification]::new($xml)',
+        "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier(" +
+            "'{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe').Show($toast)",
+    ].join(';');
+}
+/**
+ * The command one notification runs on this platform. Pure: the text is escaped here, so a message with quotes,
+ * Chinese or a colon cannot break the command. Null only for a platform with no notifier.
+ */
+export function notificationCommand(platform, notification) {
+    const title = oneLine(notification.title) || 'AsRun';
+    const body = oneLine(notification.body);
+    if (platform === 'darwin') {
+        const script = `display notification "${appleScriptText(body)}" with title "${appleScriptText(title)}"` +
+            (notification.sound ? ' sound name "Glass"' : '');
+        return { file: 'osascript', args: ['-e', script] };
+    }
+    if (platform === 'win32') {
+        return {
+            file: 'powershell',
+            args: ['-NoProfile', '-NonInteractive', '-Command', toastScript(title, body, notification.sound === true)],
+        };
+    }
+    if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd') {
+        return { file: 'notify-send', args: ['-a', 'AsRun', title, body] };
+    }
+    return null;
+}
+/** One argument as it would be typed in a shell, for the line `notify-test` prints (never used to run anything). */
+const quote = (value) => (/^[\w@=,.:/~+-]+$/.test(value) ? value : JSON.stringify(value));
+/** A command as a person would type it, cut short: a toast script is hundreds of characters long. */
+export function describeCommand(command) {
+    const line = [command.file, ...command.args.map(quote)].join(' ');
+    return line.length > 200 ? `${line.slice(0, 197)}...` : line;
+}
+/**
+ * Shows one notification and waits for the command to end. Used by `pnpm asrun notify-test`, which has to report
+ * whether the operating system took it; the server uses `notifyDesktop` instead.
+ */
+export async function sendNotification(notification) {
+    const command = notificationCommand(process.platform, notification);
+    if (!command)
+        return { command: null, ok: false, reason: `${process.platform} has no desktop notification` };
+    const display = describeCommand(command);
+    const target = spawnTarget(command.file, command.args);
+    if (!target)
+        return { command: display, ok: false, reason: `${command.file} was not found on PATH` };
+    return await new Promise((resolve) => {
+        let stderr = '';
+        let settled = false;
+        let timer;
+        const done = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(outcome);
+        };
+        let child;
+        try {
+            child = spawn(target.file, target.args, {
+                stdio: ['ignore', 'ignore', 'pipe'],
+                windowsHide: true,
+                ...(target.throughShell && { windowsVerbatimArguments: true }),
+            });
+        }
+        catch (error) {
+            resolve({ command: display, ok: false, reason: error.message });
+            return;
+        }
+        timer = setTimeout(() => {
+            child.kill();
+            done({ command: display, ok: false, reason: `no answer after ${TIMEOUT_MS / 1000} s` });
+        }, TIMEOUT_MS);
+        timer.unref();
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on('error', (error) => done({ command: display, ok: false, reason: error.message }));
+        child.on('close', (code) => {
+            const detail = stderr.trim().split('\n').filter(Boolean).at(-1);
+            done(code === 0
+                ? { command: display, ok: true }
+                : { command: display, ok: false, reason: detail ?? `exit code ${code}` });
+        });
+    });
+}
+/**
+ * Shows one notification without waiting for it. The same text is sent once per few seconds, so two events of one
+ * handoff (the options call and the card) do not ring twice. `onError` says why nothing was shown, for a hint in the
+ * job log; it is never called on success.
+ */
+export function notifyDesktop(notification, onError) {
+    const key = `${notification.title}\u0000${notification.body}`;
+    const now = Date.now();
+    for (const [seen, at] of recent)
+        if (now - at > DEDUPE_MS)
+            recent.delete(seen);
+    if (recent.has(key))
+        return;
+    recent.set(key, now);
+    void sendNotification(notification).then((outcome) => {
+        if (outcome.ok || !onError)
+            return;
+        try {
+            onError(outcome.reason ?? 'the notification command failed');
+        }
+        catch {
+            // A caller that cannot report the failure is not worth failing the notification for.
+        }
+    });
+}