@asrunjs/asrun 0.13.0 → 0.14.0

package/dist/lib/paths.d.ts

@@ -30,7 +30,14 @@ export declare const EXPLORE_DIR: string;
 export declare const TEMPLATES_DIR: string;
 export declare const SKILLS_DIR: string;
 /**
- * The `node_modules/<package>` folder of the framework's own install, or the workspace's (a hoisted or linked
- * install). Tools that need a package folder rather than a module (vite's config, pdfjs assets) use this.
+ * The folder of a package the framework needs at run time: the framework's own dependency, or the workspace's (a
+ * hoisted or linked install). Tools that need a package folder rather than a module (vite's config, pdfjs assets) use
+ * this.
+ *
+ * Node's own resolution comes first, because it is the same one every `import` in this package goes through: the
+ * folder and the module that is loaded can then never disagree. A hand-built path could not promise that — under
+ * pnpm's virtual store the framework sits in `<store>/node_modules/@asrunjs/asrun`, so the folder that holds its
+ * dependencies is one `node_modules`, not two, and appending a second one named the wrong folder and made every PDF
+ * check fail with "pdfjs-dist is not installed" while the package was installed.
  */
 export declare function packageDir(packageName: string): string;

package/dist/lib/paths.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 /**
  * Where the framework's own code and assets live: the package folder (`node_modules/@asrunjs/asrun`). The compiled files sit in
  * `dist/lib`, so one level up from there is the package root again.
@@ -87,13 +88,39 @@ export const EXPLORE_DIR = path.join(ROOT, '.explore');
 export const TEMPLATES_DIR = path.join(FRAMEWORK_ROOT, 'templates');
 export const SKILLS_DIR = path.join(FRAMEWORK_ROOT, '.claude', 'skills');
 /**
- * The `node_modules/<package>` folder of the framework's own install, or the workspace's (a hoisted or linked
- * install). Tools that need a package folder rather than a module (vite's config, pdfjs assets) use this.
+ * The folder of a package the framework needs at run time: the framework's own dependency, or the workspace's (a
+ * hoisted or linked install). Tools that need a package folder rather than a module (vite's config, pdfjs assets) use
+ * this.
+ *
+ * Node's own resolution comes first, because it is the same one every `import` in this package goes through: the
+ * folder and the module that is loaded can then never disagree. A hand-built path could not promise that — under
+ * pnpm's virtual store the framework sits in `<store>/node_modules/@asrunjs/asrun`, so the folder that holds its
+ * dependencies is one `node_modules`, not two, and appending a second one named the wrong folder and made every PDF
+ * check fail with "pdfjs-dist is not installed" while the package was installed.
  */
 export function packageDir(packageName) {
-    // The package's own install, the pnpm virtual store that holds its dependencies, or a hoisted install in the workspace.
-    for (const base of [FRAMEWORK_ROOT, path.dirname(path.dirname(FRAMEWORK_ROOT)), ROOT]) {
-        const dir = path.join(base, 'node_modules', packageName);
+    // A bare name resolves to the package's entry point only; asking for the manifest is the portable way to its folder.
+    try {
+        const dir = path.dirname(createRequire(import.meta.url).resolve(`${packageName}/package.json`));
+        if (fs.existsSync(path.join(dir, 'package.json')))
+            return dir;
+    }
+    catch {
+        // Not resolvable from here (an `exports` map without "./package.json", or a package installed elsewhere): the
+        // folders that can hold an install answer instead.
+    }
+    // pnpm's virtual store already keeps a package's dependencies inside a `node_modules`, next to its scope folder;
+    // every other layout nests that folder inside the install root.
+    const store = path.dirname(path.dirname(FRAMEWORK_ROOT));
+    const candidates = [
+        // This package's own nested dependencies (an install strategy that nests instead of hoisting).
+        path.join(FRAMEWORK_ROOT, 'node_modules', packageName),
+        // The dependencies next to it: pnpm's store, or the root of a hoisted install.
+        path.basename(store) === 'node_modules' ? path.join(store, packageName) : path.join(store, 'node_modules', packageName),
+        // The workspace's own install: a peer dependency (`@playwright/test`) lives here.
+        path.join(ROOT, 'node_modules', packageName),
+    ];
+    for (const dir of candidates) {
         if (fs.existsSync(dir))
             return dir;
     }

package/dist/lib/pdf.js

@@ -1,13 +1,33 @@
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { createCanvas } from '@napi-rs/canvas';
 import { expect } from '@playwright/test';
 import { packageDir } from './paths.js';
 let pdfjs;
-const loadPdfjs = () => (pdfjs ??= import('pdfjs-dist/legacy/build/pdf.mjs'));
-// pdf.js loads its fonts, cmaps and wasm files from the package folder, not from the consuming project.
+const loadPdfjs = () => (pdfjs ??= import('pdfjs-dist/legacy/build/pdf.mjs').catch((error) => {
+    // The one dependency of this module. A raw ERR_MODULE_NOT_FOUND names this file and nothing a person can act on.
+    throw new Error(`The PDF renderer is unavailable: "pdfjs-dist" could not be loaded (${error.message}). The asrun install is ` +
+        'incomplete: run "pnpm install" in the workspace root, or install the framework again ("pnpm add -D ' +
+        '@asrunjs/asrun"). "pnpm asrun doctor" says which part is missing.');
+}));
+// pdf.js loads its fonts, cmaps and wasm files from the package folder, not from the consuming project. The folder is
+// derived from the very module that is imported, so it cannot drift from the code that reads it: a hand-built path was
+// one `node_modules` too deep under pnpm's virtual store, and every PDF check failed although the package was there.
+// `packageDir` answers only when the module itself cannot be resolved (then the load above reports it).
 let pdfjsDir;
-const dirUrl = (dir) => pathToFileURL(path.join((pdfjsDir ??= packageDir('pdfjs-dist')), dir)).href + '/';
+function pdfjsRoot() {
+    if (pdfjsDir !== undefined)
+        return pdfjsDir;
+    try {
+        const build = createRequire(import.meta.url).resolve('pdfjs-dist/legacy/build/pdf.mjs');
+        return (pdfjsDir = path.resolve(path.dirname(build), '..', '..'));
+    }
+    catch {
+        return (pdfjsDir = packageDir('pdfjs-dist'));
+    }
+}
+const dirUrl = (dir) => pathToFileURL(path.join(pdfjsRoot(), dir)).href + '/';
 /** A corner of the page. Defaults: 30% of the width and 12% of the height, enough for a logo and nothing else. */
 export function corner(name, size = {}) {
     const width = size.width ?? 0.3;

package/dist/scripts/check-cases.js

@@ -58,7 +58,7 @@ function questionProblems(id) {
             warnings.push(`the "✍️ Answer:" line of the question on line ${question.line} is not the last line of its block`);
         }
         if (!question.parent) {
-            warnings.push(`the question on line ${question.line} has no text above it: accepting it would delete a claim nobody sees`);
+            warnings.push(`the question on line ${question.line} has no sentence it is about: accepting it would delete a claim nobody sees`);
             continue;
         }
         const step = doc.steps.find((candidate) => candidate.line === question.parent?.line);
@@ -67,8 +67,8 @@ function questionProblems(id) {
         }
         const anchor = immediateAnchor(splitLines(doc.text), question.line, question.indent);
         if (anchor !== null && anchor !== question.parent.line) {
-            const above = splitLines(doc.text).find((line) => line.number === anchor)?.text.trim() ?? '';
-            warnings.push(`the question on line ${question.line} hangs under "${above.slice(0, 80)}", but the panel shows "${question.parent.text.slice(0, 80)}" as the text above it; indent it under that sentence or lift that sentence to a top-level bullet`);
+            const anchorText = splitLines(doc.text).find((line) => line.number === anchor)?.text.trim() ?? '';
+            warnings.push(`the question on line ${question.line} hangs under "${anchorText.slice(0, 80)}", but the panel shows "${question.parent.text.slice(0, 80)}" as the sentence it is about; indent it under that sentence or lift that sentence to a top-level bullet`);
         }
     }
     for (const step of doc.steps) {

package/dist/scripts/cli.js

@@ -44,13 +44,18 @@ async function main() {
         await import('./explore-notes.js');
         return;
     }
+    if (command === 'notify-test') {
+        const { main: notifyTest } = await import('./notify-test.js');
+        process.exitCode = await notifyTest(rest);
+        return;
+    }
     if (command === 'help' || command === '--help-init') {
         console.log(USAGE);
         return;
     }
     await import('./run.js');
 }
-const USAGE = `Usage: pnpm asrun [init|doctor|rules|reset|upgrade|migrate|explore:notes] [options]
+const USAGE = `Usage: pnpm asrun [init|doctor|rules|reset|upgrade|migrate|explore:notes|notify-test] [options]
 
   (no subcommand)  Run the tests of one environment. See "pnpm asrun --help".
   init             Create the files a workspace needs (never overwrites; --update refreshes generated files,
@@ -65,5 +70,7 @@ const USAGE = `Usage: pnpm asrun [init|doctor|rules|reset|upgrade|migrate|explor
                    target release for breaking changes (see "pnpm asrun upgrade --help").
   migrate          Apply the workspace migrations of the installed release, or list them (see "pnpm asrun migrate
                    --help"). "upgrade" runs it; use it after a manual install.
-  explore:notes    Print or validate the local exploration note of a case (see "pnpm asrun explore:notes --help").`;
+  explore:notes    Print or validate the local exploration note of a case (see "pnpm asrun explore:notes --help").
+  notify-test      Show one desktop notification and print the command behind it, to tell a hidden notification from a
+                   broken one (see "pnpm asrun notify-test --help").`;
 await main();

package/dist/scripts/doctor.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { loadProfiles, listEnvs, PROFILES_FILE } from '../lib/profiles.js';
-import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR } from '../lib/paths.js';
+import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR, packageDir } from '../lib/paths.js';
 import { readWorkspaceConfig } from '../lib/config.js';
 import { readProjectRules, mentionedTestDataPrefixes } from '../lib/rules.js';
 import { spawnTarget } from '../lib/command.js';
@@ -85,6 +85,33 @@ function documentedBrowserTools() {
     const section = /^## Runnable\n([\s\S]*?)^## /m.exec(text)?.[1] ?? '';
     return [...new Set(section.match(/browser_[a-z0-9_]+/g) ?? [])];
 }
+/**
+ * The PDF renderer, which is how an exploring agent looks at a downloaded PDF and how a spec checks one: `lib/pdf.js`
+ * imports `pdfjs-dist` and `@napi-rs/canvas` at run time, and pdf.js reads its fonts and cmaps from the package folder
+ * `packageDir` names. Both are runtime dependencies of the framework, so a failure means the install (or the Node
+ * version) is broken — and it used to surface only when someone rendered a PDF, halfway through an exploration.
+ */
+async function pdfRenderer() {
+    let dir;
+    try {
+        dir = packageDir('pdfjs-dist');
+    }
+    catch {
+        // `packageDir` already says where it looked; the caller adds what to do about it.
+        return { ok: false, reason: 'pdfjs-dist is not installed where the framework can reach it' };
+    }
+    try {
+        const version = JSON.parse(read(path.join(dir, 'package.json')) ?? '{}').version ?? 'unknown';
+        // Loading both is what proves it: the module import resolves exactly like the one in `lib/pdf.js`, and the native
+        // canvas is what draws the page.
+        await import('pdfjs-dist/legacy/build/pdf.mjs');
+        await import('@napi-rs/canvas');
+        return { ok: true, version };
+    }
+    catch (error) {
+        return { ok: false, reason: error.message };
+    }
+}
 export async function main(args) {
     if (args.includes('--help')) {
         console.log('Usage: pnpm asrun doctor');
@@ -296,6 +323,17 @@ export async function main(args) {
         warnings.push(`${extra.pkg} is not installed and this machine does not provide it: ${extra.provides} is skipped. Run ` +
             '"pnpm asrun init" (or "pnpm go") to install it, or install the tool yourself and run doctor again.');
     }
+    // The PDF renderer: "pnpm pdf:render", the exploring agent's look at a downloaded PDF, and every `expectPdf` check.
+    const pdf = await pdfRenderer();
+    if (pdf.ok) {
+        facts.push(`pdf renderer:  pdfjs-dist ${pdf.version} (canvas ok)`);
+    }
+    else {
+        // An Error message may already end with a period; the sentence around it must not double it.
+        const reason = pdf.reason.replace(/\.\s*$/, '');
+        errors.push(`The PDF renderer does not work, so "pnpm pdf:render" and every PDF check fail (${reason}). To fix it, run ` +
+            '"pnpm install" in the workspace root (Node 22.13 or newer is required), or install the framework again.');
+    }
     let scripts = null;
     try {
         const packageJson = read(path.join(ROOT, 'package.json'));

package/dist/scripts/notify-test.d.ts

@@ -0,0 +1 @@
+export declare function main(args: string[]): Promise<number>;

package/dist/scripts/notify-test.js

@@ -0,0 +1,48 @@
+import { describeCommand, notificationCommand, sendNotification } from '../lib/desktop-notify.js';
+/*
+ * `pnpm asrun notify-test`
+ *
+ * Shows one desktop notification through the same module the UI server notifies with, and prints what it ran. The
+ * point is to separate "the code is wrong" from "this machine hides notifications": a notification that never appears
+ * while this command exits 0 means the operating system dropped it, and the hint below says where to look.
+ */
+const USAGE = `Usage: pnpm asrun notify-test [--help]
+
+  Shows one desktop notification and prints the command that showed it. Nothing is written to a case or a report.
+
+  Use it when "your turn" produced no notification: the UI server sends those through the same command.
+  macOS:    System Settings > Notifications > the app that runs this (Terminal, iTerm2, ...).
+  Windows:  Settings > System > Notifications, and turn off Focus assist while you test.
+  Linux:    install libnotify (the "notify-send" command).`;
+const HINT = {
+    darwin: 'If nothing appeared, the system dropped it: open System Settings > Notifications, find the app that runs this ' +
+        'command (Terminal, iTerm2, the editor you run pnpm in) and allow notifications for it. Focus mode hides them too.',
+    win32: 'If nothing appeared, check Settings > System > Notifications (and Focus assist), and that a notification banner is ' +
+        'not turned off for Windows PowerShell.',
+    linux: 'If nothing appeared, install libnotify (the "notify-send" command) and check that a notification daemon runs in ' +
+        'this session.',
+};
+export async function main(args) {
+    if (args.includes('--help')) {
+        console.log(USAGE);
+        return 0;
+    }
+    const notification = {
+        title: 'AsRun — test',
+        body: 'A desktop notification: this is how "your turn in the browser window" reaches you.',
+        sound: true,
+    };
+    const command = notificationCommand(process.platform, notification);
+    if (command)
+        console.log(`Running: ${describeCommand(command)}`);
+    const outcome = await sendNotification(notification);
+    if (outcome.ok) {
+        console.log('Done: a notification should be on screen now. If it is not, the system dropped it, not asrun.');
+        return 0;
+    }
+    console.error(`No notification: ${outcome.reason ?? 'the command failed'}`);
+    const hint = HINT[process.platform];
+    if (hint)
+        console.error(hint);
+    return 1;
+}

package/dist/ui/server/actions.js

@@ -259,8 +259,10 @@ export function buildJobSpec(request) {
             thinking: request.thinking,
             force: request.force,
             attended: request.attended,
-            // Naming every profile of the environment is the same as leaving it out: the agent then takes all that are logged in.
-            profiles: request.profiles && request.profiles.length < profilesInEnv.length ? request.profiles : undefined,
+            // Always the picked ids, even when they name every profile of the environment: without the flag explore falls back
+            // to one logged-in profile per domain, which is not the same as "the profiles you ticked". Heal runs only the
+            // profiles that are logged in anyway.
+            profiles: request.profiles,
             hints: hintsPath,
             report: request.report,
         };

package/dist/ui/server/ai-stream.d.ts

@@ -13,6 +13,8 @@ export interface LogPart {
 /** The agent has put a handoff card in the browser window and waits for the person (see user-handoff.md). */
 export interface AwaitingUser {
     message: string | null;
+    /** The finish condition the card shows in its "DONE WHEN" block; null when the options did not name one. */
+    finish: string | null;
     since: number;
 }
 export declare class AiStreamFormatter {
@@ -21,8 +23,12 @@ export declare class AiStreamFormatter {
     private pending;
     private cardCalls;
     private waitingForUser;
-    /** The message of the last options call, kept so a card that runs after unrelated calls still carries it. */
+    /**
+     * The message and finish condition of the last options call, kept so a card that runs after unrelated calls still
+     * carries them.
+     */
     private lastHandoffMessage;
+    private lastHandoffFinish;
     private lastEventAt;
     private lastWaitAt;
     /** The last call the agent finished, so a quiet spell can say what it is doing instead of only that nothing came. */

package/dist/ui/server/ai-stream.js

@@ -271,11 +271,15 @@ const BROWSER_RUN_CODE = /browser_run_code/;
  * badge on.
  */
 const HANDOFF_CFG_TTL_MS = 300_000;
-/** `message: '...'` of the options call that comes right before the card. */
-function handoffMessage(code) {
-    const match = /message\s*:\s*(['"`])((?:\\.|(?!\1)[^\\])*)\1/.exec(code);
+/** A plain string literal of the options call that comes right before the card (`message: '...'`, `finish: '...'`). */
+function handoffText(code, key) {
+    const match = new RegExp(`(?:^|[^\\w$])${key}\\s*:\\s*(['"\`])((?:\\\\.|(?!\\1)[^\\\\])*)\\1`).exec(code);
     return match ? match[2].replace(/\\(['"`\\])/g, '$1').trim() || null : null;
 }
+/** `message: '...'` of the options call that comes right before the card. */
+const handoffMessage = (code) => handoffText(code, 'message');
+/** `finish: '...'` of the options call that comes right before the card. */
+const handoffFinish = (code) => handoffText(code, 'finish');
 const codeOf = (input) => {
     if (!input || typeof input !== 'object')
         return '';
@@ -306,8 +310,12 @@ export class AiStreamFormatter {
     pending = new Map();
     cardCalls = new Set();
     waitingForUser = null;
-    /** The message of the last options call, kept so a card that runs after unrelated calls still carries it. */
+    /**
+     * The message and finish condition of the last options call, kept so a card that runs after unrelated calls still
+     * carries them.
+     */
     lastHandoffMessage = null;
+    lastHandoffFinish = null;
     lastEventAt = Date.now();
     lastWaitAt = 0;
     /** The last call the agent finished, so a quiet spell can say what it is doing instead of only that nothing came. */
@@ -348,18 +356,29 @@ export class AiStreamFormatter {
                 this.waitingForUser = null;
             else {
                 this.cardCalls.add(id);
-                // `??=` on purpose: the options call before it already knows the message and when the wait started.
-                this.waitingForUser ??= { message: handoffMessage(codeOf(input)) ?? this.lastHandoffMessage, since: Date.now() };
+                // `??=` on purpose: the options call before it already knows the message, the finish condition and the start.
+                this.waitingForUser ??= {
+                    message: handoffMessage(codeOf(input)) ?? this.lastHandoffMessage,
+                    finish: handoffFinish(codeOf(input)) ?? this.lastHandoffFinish,
+                    since: Date.now(),
+                };
             }
             return null;
         }
         if (kind === 'options') {
             const message = handoffMessage(codeOf(input));
+            const finish = handoffFinish(codeOf(input));
             if (message)
                 this.lastHandoffMessage = message;
+            if (finish)
+                this.lastHandoffFinish = finish;
             // Keep the start time when the wait is already set: a second report of the same handoff must not announce it twice.
             const since = this.waitingForUser?.since ?? Date.now();
-            this.waitingForUser = { message: message ?? this.lastHandoffMessage, since };
+            this.waitingForUser = {
+                message: message ?? this.lastHandoffMessage,
+                finish: finish ?? this.lastHandoffFinish,
+                since,
+            };
             return null;
         }
         // Anything else ends the wait, unless it was set too recently to be an abandoned one: the card runs right after it.

package/dist/ui/server/jobs.d.ts

@@ -102,6 +102,16 @@ declare class JobManager {
     private verifyLeftoverStopped;
     /** Publishes a change of "waiting for the person" (a handoff card) like any other status change. */
     private syncAwaiting;
+    /**
+     * Shows a desktop notification now. Neither the agent (whose shell the CLI may refuse) nor the page (not open, not
+     * focused, not allowed) can be relied on for this, so the server shows it itself.
+     */
+    private notifyWaiting;
+    /**
+     * Why no notification appeared, written where the person reads next: never a reason to fail the job, and the next
+     * run of the same kind leaves no line at all when the notifier works.
+     */
+    private pushNotificationFailure;
     /**
      * Stops a run whose agent has said nothing for `STALL_MS`: a tool call that never returns leaves the CLI waiting for
      * ever, and the log would only keep repeating "still waiting for ...". The block above the cancel names what to do.

package/dist/ui/server/jobs.js

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import { StringDecoder } from 'node:string_decoder';
 import { ROOT } from '../../lib/paths.js';
 import { spawnTarget } from '../../lib/command.js';
+import { notifyDesktop } from '../../lib/desktop-notify.js';
 import { AiStreamFormatter } from './ai-stream.js';
 import { parseResultState } from './result-state.js';
 import { appendChunkNow, chunksFile, ensureJobDir, logFile, pruneJobs, readChunks, readJobs, writeRecord, } from './job-store.js';
@@ -244,6 +245,11 @@ class JobManager {
             finished = true;
             this.finish(record, code, signal);
         });
+        // A login waits for a person at the browser window it just opened: say so on the desktop, where they are looking.
+        if (spec.kind === 'signin') {
+            this.notifyWaiting(record, 'AsRun — log in', `Log in to ${[spec.profile, spec.env].filter(Boolean).join(' @ ')}, then press "Done, save the session" on ` +
+                'the card in the browser window.');
+        }
         this.events.emit('job', record.info);
         return record.info;
     }
@@ -476,9 +482,39 @@ class JobManager {
             return;
         if (now && before && before.since === new Date(now.since).toISOString())
             return;
-        info.awaitingUser = now ? { message: now.message, since: new Date(now.since).toISOString() } : null;
+        info.awaitingUser = now
+            ? { message: now.message, finish: now.finish, since: new Date(now.since).toISOString() }
+            : null;
         this.persist(record);
         this.events.emit('job', info);
+        // A handoff that starts right now: the person is told on the desktop, because the browser window is somewhere else
+        // and the page may be closed, focused or not allowed to notify. The dedupe keeps one handoff to one notification.
+        if (!before && now) {
+            this.notifyWaiting(record, 'AsRun — your turn', `${info.caseId ? `${info.caseId}: ` : ''}${now.message ?? 'A step in the browser window waits for you.'}` +
+                (now.finish ? ` Done when ${now.finish}.` : ''));
+        }
+    }
+    /**
+     * Shows a desktop notification now. Neither the agent (whose shell the CLI may refuse) nor the page (not open, not
+     * focused, not allowed) can be relied on for this, so the server shows it itself.
+     */
+    notifyWaiting(record, title, body) {
+        notifyDesktop({ title, body, sound: true }, (reason) => this.pushNotificationFailure(record, reason));
+    }
+    /**
+     * Why no notification appeared, written where the person reads next: never a reason to fail the job, and the next
+     * run of the same kind leaves no line at all when the notifier works.
+     */
+    pushNotificationFailure(record, reason) {
+        const line = `\n[no desktop notification shown: ${reason}. "pnpm asrun notify-test" checks the notifier of this machine]\n`;
+        // The job may have ended while the notifier was still running: its log stream is closed then, so the files get the
+        // line directly (a running job is told through its stream, so the page shows it at once).
+        if (record.info.status === 'running' && record.logStream) {
+            this.pushPart(record, { kind: 'hint', at: Date.now(), data: line });
+        }
+        else {
+            this.pushRecovered(record, line);
+        }
     }
     /**
      * Stops a run whose agent has said nothing for `STALL_MS`: a tool call that never returns leaves the CLI waiting for
@@ -586,6 +622,10 @@ class JobManager {
                         : `[process exited with code ${code}]`);
         if (record.spec.ai && info.status === 'succeeded')
             info.resultState = parseResultState(resultText(record));
+        // The agent stopped with questions in the case file: that waits for a person exactly like a handoff card does.
+        if (info.resultState === 'needs-input') {
+            this.notifyWaiting(record, 'AsRun — answers needed', `${info.caseId ? `${info.caseId}: ` : 'The case: '}the agent wrote open questions into the case file.`);
+        }
         this.push(record, 'system', `\n${summary}\n`);
         record.logStream?.end();
         record.chunkStream?.end();

package/dist/ui/shared/ai-commands.js

@@ -134,8 +134,10 @@ const ATTENDED = 'Attended run: a person is at the machine and the browser windo
     'need a choice to them and wait, as the skill describes. Start every handoff (also a second one in the same run) ' +
     'with its own call that sets __handoffCfg, before the call that runs handoff-card.js, and never change those options ' +
     'inside the call that runs the card: the web UI sees that a person is needed only from that call, so without it ' +
-    'there is no "Your turn" badge and no notification. Nobody can answer questions in the chat, so write open ' +
-    `questions into the case file as the skill describes. ${RESULT_LINE_RULE}`;
+    'there is no "Your turn" badge and no notification. Put one action per string in `steps` (the card numbers them), ' +
+    'keep `message` to one sentence, write the finish condition into `finish` as plain text, and set `doneText` to the ' +
+    'exact text that appears when the step is done so the card ends by itself. Nobody can answer ' +
+    `questions in the chat, so write open questions into the case file as the skill describes. ${RESULT_LINE_RULE}`;
 /** The prompt of a one-shot run. Every command may leave open questions in the case, so every one ends with a RESULT line. */
 export function headlessPrompt(command, caseId, options) {
     const slash = slashCommand(command, caseId, options);

package/dist/ui/shared/types.d.ts

@@ -60,6 +60,8 @@ export interface JobInfo {
 export interface AwaitingUserInfo {
     /** What the person is asked to do, as the agent wrote it on the card; null when unknown. */
     message: string | null;
+    /** The finish condition the card shows in its "DONE WHEN" block; null when the agent gave none. */
+    finish?: string | null;
     since: string;
 }
 /** `needs-input`: the agent wrote open questions into the case file and cannot go on without answers. */

package/docs/agents/case-format.md

@@ -94,7 +94,8 @@ Wrong: `- Create a draft named ... and delete it at the end.` (a write → a tag
 - A question block is indented under the sentence it belongs to: 4 spaces under a numbered step, 2 under a bullet.
   The parent line is the suggestion, written as a finished sentence; the `TODO` line holds one question and optional
   `(evidence)`; the block ends with `- ✍️ Answer:` at one level deeper and that line is the last line of the block.
-  Hang it under the immediate sentence, never under a broader one above it, and never inside the `## Values` yaml.
+  Hang it under the immediate sentence, never under a broader sentence that merely contains it, and never inside the
+  `## Values` yaml.
   Details: `.claude/skills/exploring-cases/references/open-questions.md`.
 - A marker (`🔍 to be confirmed: <what a person must decide>`) is the alternative to a question, not a companion: it
   says nobody has to decide, only to check. `(seen on <profile>)` is a plain note the run checks by itself. Its

package/docs/ai-workflow.md

@@ -88,10 +88,13 @@ publishes, shares or deletes anything, in staging or in production. It:
   data-call paths it saw. `/gen-spec` reads it to verify instead of rediscovering, and a page that only exists after a
   write step is written from it. Delete it at any time: without it, generation replays the case.
 
-With many profiles, `--profiles a,b` opens only those (ids from `profiles.yaml`, comma-separated). The others are not
-opened and nothing is written about them, so a case can be explored in passes: A and B first, C later. Runs add up; the
-case keeps what the earlier runs recorded. In the web UI the profile picker of the toolbar does the same: every profile
-that is logged in in that environment is ticked, and the list you tick is remembered for the next run there.
+With many profiles, `--profiles a,b` opens only those (ids from `profiles.yaml`, comma-separated), each in its own
+session; without the flag the agent opens one logged-in profile per domain. Two different hosts are two domains even
+when they serve the same product, so the list is never collapsed into one profile. The profiles the list leaves out are
+not opened and nothing is written about them, so a case can be explored in passes: A and B first, C later. Runs add up;
+the case keeps what the earlier runs recorded. In the web UI the profile picker of the toolbar does the same: every
+profile that is logged in in that environment is ticked, and the list you tick is passed to the run and remembered for
+the next one there.
 
 **To keep what the case says, delete the whole block.** **To answer, write after `Answer:`.** Then run the command
 again. In the web UI the panel calls the first action **Keep what the case says**. The run's **What to do next** bar
@@ -104,9 +107,10 @@ restarted.
 Use it for a case that creates or edits data, or needs a choice (an existing document, items). Stay at the computer:
 the browser window opens and the agent waits while you do those steps.
 
-- The window shows a small draggable card in the bottom-left corner with what to do, **Done** (hand control back) and
-  **Cannot do this**. The agent also continues by itself when the finish condition it named shows up (for example a
-  "Saved" message); the card turns green when control is back. It waits up to 10 minutes per step.
+- The window shows a small draggable card in the bottom-left corner: one sentence about the step, the steps numbered,
+  the texts to copy, and a green **DONE WHEN** block with the finish condition. **Done** hands control back, and
+  **Cannot do this** gives the step up. The agent also continues by itself when the finish condition shows up (for
+  example a "Saved" message); the card turns green when control is back. It waits up to 10 minutes per step.
 - Recording starts and stops by itself. If Playwright's own recording toolbar shows at the top of the page, leave it
   alone: it can stop the recording.
 - The card records what you did, and the agent writes it into the case under the step as **general recipe lines**

package/docs/cases.md

@@ -113,11 +113,11 @@ report and the trace read like the case.
   exploration: positions instead of names of changeable data (`select items #1 to #3`), created names (project prefix
   plus run stamp), control labels but no selectors. Several lines per step are normal. A tagged step with no recipe is
   not generated: `/gen-spec` stops with `needs-input`.
-- **Open questions** go in a `🚫 TODO [blocking]` or `❓ TODO [non-blocking]` block under the sentence they are about,
-  with the agent's suggestion written above and a last line `- ✍️ Answer:`. Accepting a question means deleting the
-  whole block; answering means writing after `Answer:`. In the web panel the two actions are **Keep what the case
-  says** and **Write your answer**. Hang the block under the sentence that makes the claim, not under a broader one
-  above it, and one claim gets one block.
+- **Open questions** go in a `🚫 TODO [blocking]` or `❓ TODO [non-blocking]` block under the sentence they are about:
+  that sentence is the agent's suggestion, and the block's last line is `- ✍️ Answer:`. Accepting a question means
+  deleting the whole block; answering means writing after `Answer:`. In the web panel the two actions are **Keep what
+  the case says** and **Write your answer**. Hang the block under the sentence that makes the claim, not under a
+  broader sentence that merely contains it, and one claim gets one block.
 - **What the AI saw** is marked by what happens if it is wrong: `(seen on <profile>)` is a plain note the run checks by
   itself, and `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)` is a line that would pass even
   if it were wrong, so a person settles it. A marker may name a screenshot (`evidence: .explore/.../x.png`) so nobody

package/docs/commands.md

@@ -16,6 +16,7 @@ thin wrappers, so `pnpm asrun`, `pnpm signin` and the rest work as below. The sa
 | Start the web UI | `pnpm go`, `pnpm ui`, `pnpm ui:dev` |
 | See which profiles are logged in | `pnpm status [--env <env>]` |
 | Log in a profile (a person, with 2FA) | `pnpm signin <profile-id>` |
+| Check that desktop notifications reach you | `pnpm asrun notify-test` |
 | Run tests | `pnpm asrun --env <env> [filters]` |
 | Open the last report | `pnpm report` |
 | Look around a page as a profile | `pnpm explore <profile-id> [path]` |
@@ -116,6 +117,23 @@ pnpm signin example-staging
 The login is done by a person, including 2FA; the session is saved to `.auth/<profile-id>.json` and verified. See
 [profiles.md](./profiles.md).
 
+## Notifications
+
+```bash
+pnpm asrun notify-test
+```
+
+The UI server shows a **desktop notification** when a run waits for you: an AI run handed a step to the browser window,
+a login opened its window, or a run ended with open questions in the case file. It is the server's own call
+(`osascript` on macOS, `notify-send` on Linux, a PowerShell toast on Windows), so it arrives whether or not the UI page
+is open, focused or allowed to notify. The browser's bell is separate: it is for "a run ended", while the tab is in the
+background (see [web-ui.md](./web-ui.md)).
+
+`notify-test` shows one through the same code and prints the command it ran. Exit code 0 with nothing on screen means
+the operating system dropped the notification, not that asrun failed: allow the app that runs the command (Terminal,
+iTerm2, ...) in its notifications settings. The job log says `[no desktop notification shown: ...]` when the command
+itself failed.
+
 ## Cases and checks
 
 ```bash
@@ -284,7 +302,8 @@ init writes (a single file with `--force <file>`). `--force` still keeps `profil
 adds the `allowBuilds` entries `pnpm-workspace.yaml` lacks, and installs the optional packages this machine lacks
 (`ffmpeg-static`; `--no-extras` skips them).
 `doctor` checks profiles, `tsconfig.json`, `playwright.config.ts`, the generated files, the installed version, the
-project rule table, the skill overrides and the workspace migrations. `upgrade` and `migrate` are described above.
+project rule table, the skill overrides, the workspace migrations and the PDF renderer (a missing or unloadable
+`pdfjs-dist` fails every PDF check). `upgrade` and `migrate` are described above.
 
 `reset` removes `node_modules` and the files `init` writes, for a clean reinstall. It deletes a once-only file only
 when it is still identical to its template, so edited files stay; `cases/`, specs, baselines, `profiles.yaml`,

package/docs/install.md

@@ -6,7 +6,7 @@ and is never edited: a project commits only its own test content.
 
 ## Requirements
 
-- **Node.js 22 or newer** and **pnpm**.
+- **Node.js 22.13 or newer** and **pnpm**.
 - **ffmpeg** joins the recordings of one test (a new browser tab has its own video) into one video for the report.
   `pnpm go` installs it with Homebrew on macOS or winget on Windows; on Linux run `sudo apt install ffmpeg`. When it is
   missing, `pnpm go` / `pnpm asrun init` install the bundled `ffmpeg-static` package into the workspace; if neither