@asrunjs/asrun 0.13.0 → 0.15.0

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
@@ -198,11 +199,13 @@ The framework folder is read-only in a project: never edit it. Its own layout an
 Three steps, each learns one thing: the intent, the facts and inputs, the implementation.
 1. `making-cases` (or `/make-case <notes>`) turns raw notes into case documents. It writes `cases/*.md` only and
    never opens a browser. Check them with `pnpm case:check`.
-2. `exploring-cases` (or `/explore-case <case-id> <env> [--attended] [--profiles a,b]`) explores the real pages for one
+2. `exploring-cases` (or `/explore-case <case-id> <env> [--attended] [--profiles a,b] [--lead <profile-id>]`) explores the real pages for one
    case. It edits that case file: wording, observations, TODO blocks, and, with `--attended`, the `- Recipe:` lines
    of the steps that write or need a choice, and it writes a local note under `.explore/notes/` with the locators and
    data-call paths it saw. `--profiles` narrows the run to those profiles; runs add up, so the case can be explored in
-   passes.
+   passes. `--lead` explores one profile in full and the rest only where they can differ (values, targets, the steps
+   that reach them), so a case with many profiles is not paid for once per profile; a profile whose page or flow
+   differs is explored in full instead, and the report says so.
 3. `generating-specs` (or `/gen-spec <case-id> <env>`) turns the case into a spec. It replays the case, its
    step recipes and the exploration note, and `## Values`, writes the spec (values stay in the case document), but never
    runs the tests, never writes data and never creates baselines. There is no profile selection here: it covers every
@@ -215,6 +218,11 @@ before installing), `pnpm asrun init [--update] [--force]` writes or refreshes t
 migrate` applies only the migrations (for a manual install), and `pnpm asrun reset` removes `node_modules` and the
 files init wrote (edited files, cases, specs, `profiles.yaml` and `package.json` stay), so
 `pnpm dlx @asrunjs/asrun init --install` can scaffold again.
+A release can change a file the project owns (its `AGENTS.md`, `.mcp.json`, `cases/_template.md`) or ask for a manual
+migration step; `pnpm asrun upgrade` ends with a `NEXT` block that names each one with its exact command.
+`/upgrade-workspace` (or `pnpm asrun upgrade --prompt`, whose output it follows) does that work: it merges only the
+scaffold text outside `## 2`/`## 3`, fixes case structure without changing what a case expects, runs the checks, and
+leaves `pnpm asrun migrate --ack <id>` and the `init --ack <file>` confirmations to the person.
 Do not hand-write specs unless asked. Do not edit `lib/` to make a single spec pass.
 Every case step is wrapped in `test.step('<n>. <case step text>', ...)` so reports and traces show the
 case's own steps (see the skill's `references/conventions.md`).

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.
@@ -58,6 +58,17 @@ generated files, applies the migrations and runs `doctor`. `--dry-run` shows the
 that predates `upgrade` updates once by hand: `pnpm add -D @asrunjs/asrun@latest`, `pnpm asrun init --update`,
 `pnpm asrun migrate`, `pnpm asrun doctor`.
 
+When the release changes a file the project owns (`AGENTS.md`, `.mcp.json`, a case template) or records manual
+migration steps, the upgrade ends with a `NEXT` block that names each one with its exact command. Hand that block to
+an AI:
+
+```bash
+pnpm asrun upgrade --prompt   # the task as Markdown; changes nothing
+```
+
+or run `/upgrade-workspace` in Claude Code / OpenCode, which does the same. The prompt is the same for every release —
+it reads which files moved and which steps are open from the workspace and the installed package.
+
 `init --update` alone refreshes only the generated files; it never overwrites `AGENTS.md`, `CLAUDE.md` or your skill
 overrides. `doctor` checks profiles, generated files, the installed version, the migrations and the project rules.
 `init --force` rewrites every file init writes (rules still need `--reset-rules`; `profiles.yaml` and `package.json`
@@ -102,7 +113,8 @@ exempts `@asrunjs/asrun` from pnpm's 24-hour release age, so a fresh release ins
    writes what they show into the case and turns what it cannot know into questions. It also saves a local note of the
    locators and data calls it saw. Answer the questions in the case file, or in the UI's **Answer** sheet, and run it
    again. With many profiles, `--profiles a,b` opens only those; a later run with the others adds theirs, and the case
-   keeps both.
+   keeps both. `--lead <profile-id>` pays for the flow once: that profile is explored in full, the others only where
+   they can differ (their values, their target screenshots, the steps that reach them).
 5. **Generate, run, read.** `/gen-spec header-logo staging` reads those notes, writes `tests/header-logo.spec.ts` and
    fills the case's `## Values`. Then:
 

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.
+        }
+    });
+}

package/dist/lib/explore-notes.d.ts

@@ -8,6 +8,9 @@
  * A note holds only what the case does not: locators the agent confirmed on the page, the data-call paths of the
  * actions that load something, and the match count of a target card's element. Expected values stay in the case's
  * `## Values`, ready signals in the case's `Ready when:` lines, and assertions nowhere near this file.
+ *
+ * A `full` note (the default) covers every step. A `diff` note belongs to a profile that an `--lead` run explored only
+ * where it can differ, and names the lead profile in `basedOn` for the steps it did not open.
  */
 export declare const NOTES_VERSION = 1;
 export interface ExploreLocator {
@@ -38,6 +41,13 @@ export interface ExploreNote {
     capturedAt: string;
     /** Set when a later `/gen-spec` refreshed an entry it confirmed on the page. */
     updatedAt?: string;
+    /**
+     * `full` (the default when absent) explored every step of the case; `diff` explored only the steps that can differ
+     * on this profile, and leans on `basedOn` for the rest. See `references/notes.md`, "Coverage".
+     */
+    depth?: 'full' | 'diff';
+    /** The lead profile a `diff` note leans on for the steps it did not open. */
+    basedOn?: string;
     steps: Record<string, ExploreNoteStep>;
     targets?: Record<string, ExploreNoteTarget>;
 }
@@ -64,6 +74,11 @@ export declare function validateExploreNote(value: unknown, expected: {
     caseId: string;
     profile: string;
 }): string[];
+/** `full` when the note explored every step, `diff` when it covered only the steps that can differ per profile. */
+export declare function noteCoverage(note: ExploreNote): {
+    depth: 'full' | 'diff';
+    basedOn?: string;
+};
 /**
  * Reads every note of a case (or one profile's), parses and validates it. A malformed file is reported, never thrown:
  * the caller decides whether it matters, and generation treats an unreadable note as a missing one.

package/dist/lib/explore-notes.js

@@ -13,6 +13,9 @@ import { CASES_DIR, EXPLORE_DIR } from './paths.js';
  * A note holds only what the case does not: locators the agent confirmed on the page, the data-call paths of the
  * actions that load something, and the match count of a target card's element. Expected values stay in the case's
  * `## Values`, ready signals in the case's `Ready when:` lines, and assertions nowhere near this file.
+ *
+ * A `full` note (the default) covers every step. A `diff` note belongs to a profile that an `--lead` run explored only
+ * where it can differ, and names the lead profile in `basedOn` for the steps it did not open.
  */
 export const NOTES_VERSION = 1;
 const HASH = /^[a-f0-9]{64}$/;
@@ -194,15 +197,45 @@ export function validateExploreNote(value, expected) {
     if (value.env !== undefined && (typeof value.env !== 'string' || value.env.trim() === '')) {
         problems.push('env must be a non-empty string when it is present');
     }
+    if (value.depth !== undefined && value.depth !== 'full' && value.depth !== 'diff') {
+        problems.push('depth must be "full" or "diff" when it is present');
+    }
+    if (value.basedOn !== undefined) {
+        if (typeof value.basedOn !== 'string' || !PROFILE_FILE.test(value.basedOn)) {
+            problems.push('basedOn must be a profile id (letters, digits, ".", "_" and "-")');
+        }
+        else if (value.depth !== 'diff') {
+            problems.push('basedOn is only allowed on a note whose depth is "diff"');
+        }
+    }
+    if (value.depth === 'diff' && value.basedOn === undefined) {
+        problems.push('a diff note must name the lead profile in basedOn');
+    }
     checkSteps(value.steps, problems);
     if (value.targets !== undefined)
         checkTargets(value.targets, problems);
-    const known = new Set(['version', 'caseId', 'profile', 'env', 'caseSha256', 'capturedAt', 'updatedAt', 'steps', 'targets']);
+    const known = new Set([
+        'version',
+        'caseId',
+        'profile',
+        'env',
+        'caseSha256',
+        'capturedAt',
+        'updatedAt',
+        'depth',
+        'basedOn',
+        'steps',
+        'targets',
+    ]);
     for (const key of Object.keys(value))
         if (!known.has(key))
             problems.push(`${key} is not a known field`);
     return problems;
 }
+/** `full` when the note explored every step, `diff` when it covered only the steps that can differ per profile. */
+export function noteCoverage(note) {
+    return note.depth === 'diff' ? { depth: 'diff', basedOn: note.basedOn } : { depth: 'full' };
+}
 /**
  * Reads every note of a case (or one profile's), parses and validates it. A malformed file is reported, never thrown:
  * the caller decides whether it matters, and generation treats an unreadable note as a missing one.

package/dist/lib/migrations.d.ts

@@ -23,9 +23,9 @@ export interface MigrationContext {
  * on any older release may still need it.
  */
 export interface Migration {
-    /** stable and unique: `<version>-<slug>`, for example `0.9.0-pnpm-release-age` */
+    /** stable and unique: `<version>-<slug>`, or `unreleased-<slug>` until the release names its version */
     id: string;
-    /** the release that introduced the change; workspaces older than this get the migration */
+    /** the release that introduced the change; `unreleased` while it is still being prepared */
     version: string;
     /** one line for the person, in the release plan before the install and in the migration output after it */
     summary: string;
@@ -37,6 +37,17 @@ export interface Migration {
     details?: string;
     /** steps only a person can do; they are printed and remembered until they are acknowledged */
     manual?: string[];
+    /**
+     * The project files the change touches. A once-only scaffold file here (`AGENTS.md`, `.mcp.json`, ...) also advances
+     * that file's baseline when the migration is acknowledged, so one `migrate --ack` clears both reminders.
+     */
+    files?: string[];
+    /**
+     * `true` for a release that touched project files but asks nothing of an existing workspace: documentation, a
+     * clarified contract, a new optional flag. The entry exists so `pnpm migrations:check` can tell "reviewed, nothing
+     * to do" from "forgotten"; the command reports it and moves on.
+     */
+    advisory?: boolean;
     /** true when the migration runs without asking after the install; the command still prints what it did */
     auto?: boolean;
     /** true when the workspace already looks migrated; a false answer skips `apply` */
@@ -46,6 +57,21 @@ export interface Migration {
 }
 /** A migration as it travels in `dist/migrations/manifest.json`: the same entry without its code. */
 export type MigrationManifestEntry = Omit<Migration, 'detect' | 'apply'>;
+/**
+ * `version` written by an entry that is still being prepared: the release it ships with names the version later, and
+ * release-please only knows it once the release pull request exists. Resolved to the installed release's own version,
+ * which is by definition the release that carries the entry's code.
+ */
+export declare const UNRELEASED = "unreleased";
+/** True for an entry whose version is still `unreleased`. */
+export declare function isUnreleased(version: string): boolean;
+/**
+ * The registry with `unreleased` resolved to the installed release. Every consumer compares versions, so they must all
+ * see the resolved entries: a leftover sentinel would sort as a plain string and silently pick the wrong migrations.
+ */
+export declare function resolveMigrations<T extends {
+    version: string;
+}>(entries: readonly T[], installedVersion: string): T[];
 /**
  * The migration state of a workspace, recorded in `.asrun.json`. `since` is the release the workspace was last
  * migrated from, so only newer entries apply. It survives `init --update`, which is what keeps a manual
@@ -63,6 +89,10 @@ export interface WorkspaceMarker {
         since?: unknown;
         manual?: unknown;
     };
+    /** The template each once-only project file is known to be aligned with (`lib/scaffold.ts`). */
+    scaffold?: unknown;
+    /** The release the workspace came from, before the last `init` wrote the current one. */
+    previous?: unknown;
     [key: string]: unknown;
 }
 /** Where `pnpm build` writes the manifest, relative to the package root. */
@@ -88,8 +118,12 @@ export interface VersionedMigration {
  * `since` is the release the workspace already matches, `to` is the release being installed.
  */
 export declare function pendingMigrations<T extends VersionedMigration>(entries: readonly T[], since: string, to: string): T[];
-/** The manifest of a registry: the same entries, without the code that cannot travel in JSON. */
-export declare function toManifest(entries: readonly Migration[]): MigrationManifestEntry[];
+/**
+ * The manifest of a registry: the same entries, without the code that cannot travel in JSON. Versions are resolved
+ * first, so a published manifest never carries the `unreleased` sentinel: an older `upgrade` reads it out of the target
+ * tarball before installing anything, and has to compare real versions.
+ */
+export declare function toManifest(entries: readonly Migration[], installedVersion: string): MigrationManifestEntry[];
 /** The marker of a workspace, or null when the file is missing or not a JSON object. */
 export declare function readMarker(root: string): WorkspaceMarker | null;
 /**
@@ -98,6 +132,11 @@ export declare function readMarker(root: string): WorkspaceMarker | null;
  * starts at the installed version, so no historical entry runs on it.
  */
 export declare function migrationState(marker: WorkspaceMarker | null, installedVersion: string): MigrationState;
+/**
+ * Reads the marker, lets the caller change it and writes it back, keeping every other field. Every module that records
+ * something in `.asrun.json` goes through this one function, so two of them can never overwrite each other's block.
+ */
+export declare function updateMarker(root: string, mutate: (marker: WorkspaceMarker) => void): void;
 /**
  * Writes the migration state back into the marker and keeps every other field (init writes the rest). The workspace
  * must already have a marker: `migrate` says so instead of creating one, because a workspace that was never

package/dist/lib/migrations.js

@@ -1,6 +1,23 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { MARKER } from './paths.js';
+/**
+ * `version` written by an entry that is still being prepared: the release it ships with names the version later, and
+ * release-please only knows it once the release pull request exists. Resolved to the installed release's own version,
+ * which is by definition the release that carries the entry's code.
+ */
+export const UNRELEASED = 'unreleased';
+/** True for an entry whose version is still `unreleased`. */
+export function isUnreleased(version) {
+    return version === UNRELEASED;
+}
+/**
+ * The registry with `unreleased` resolved to the installed release. Every consumer compares versions, so they must all
+ * see the resolved entries: a leftover sentinel would sort as a plain string and silently pick the wrong migrations.
+ */
+export function resolveMigrations(entries, installedVersion) {
+    return entries.map((entry) => (entry.version === UNRELEASED ? { ...entry, version: installedVersion } : entry));
+}
 /** Where `pnpm build` writes the manifest, relative to the package root. */
 export const MANIFEST_FILE = 'dist/migrations/manifest.json';
 /** The same file inside an npm tarball, which prefixes every path with `package/`. */
@@ -53,9 +70,13 @@ export function pendingMigrations(entries, since, to) {
         .filter((entry) => compareVersions(entry.version, since) > 0 && compareVersions(entry.version, to) <= 0)
         .sort((a, b) => compareVersions(a.version, b.version) || a.id.localeCompare(b.id));
 }
-/** The manifest of a registry: the same entries, without the code that cannot travel in JSON. */
-export function toManifest(entries) {
-    return entries.map(({ id, version, summary, breaking, appliesTo, details, manual, auto }) => ({
+/**
+ * The manifest of a registry: the same entries, without the code that cannot travel in JSON. Versions are resolved
+ * first, so a published manifest never carries the `unreleased` sentinel: an older `upgrade` reads it out of the target
+ * tarball before installing anything, and has to compare real versions.
+ */
+export function toManifest(entries, installedVersion) {
+    return resolveMigrations(entries, installedVersion).map(({ id, version, summary, breaking, appliesTo, details, manual, files, advisory, auto }) => ({
         id,
         version,
         summary,
@@ -63,6 +84,8 @@ export function toManifest(entries) {
         ...(appliesTo !== undefined && { appliesTo }),
         ...(details !== undefined && { details }),
         ...(manual !== undefined && { manual }),
+        ...(files !== undefined && { files }),
+        ...(advisory !== undefined && { advisory }),
         ...(auto !== undefined && { auto }),
     }));
 }
@@ -93,14 +116,23 @@ export function migrationState(marker, installedVersion) {
         : [];
     return { since, manual: [...new Set(manual)] };
 }
+/**
+ * Reads the marker, lets the caller change it and writes it back, keeping every other field. Every module that records
+ * something in `.asrun.json` goes through this one function, so two of them can never overwrite each other's block.
+ */
+export function updateMarker(root, mutate) {
+    const file = path.join(root, MARKER);
+    const marker = readMarker(root) ?? {};
+    mutate(marker);
+    fs.writeFileSync(file, JSON.stringify(marker, null, 2) + '\n');
+}
 /**
  * Writes the migration state back into the marker and keeps every other field (init writes the rest). The workspace
  * must already have a marker: `migrate` says so instead of creating one, because a workspace that was never
  * initialized has no release to migrate from.
  */
 export function writeMigrationState(root, state) {
-    const file = path.join(root, MARKER);
-    const marker = readMarker(root) ?? {};
-    marker.migrations = { since: state.since, manual: [...new Set(state.manual)] };
-    fs.writeFileSync(file, JSON.stringify(marker, null, 2) + '\n');
+    updateMarker(root, (marker) => {
+        marker.migrations = { since: state.since, manual: [...new Set(state.manual)] };
+    });
 }

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;