jevway 0.2.0 → 0.4.0

package/dist/notify/person-messages.js

@@ -0,0 +1,50 @@
+/**
+ * Every phrase jevway says to the person at a wall: the desktop notification, the countdown the agent relays, and the
+ * story line once it cleared. Built from the wall's kind, host and name only, never from the page's text.
+ */
+// '"unusual traffic" page' → 'the "unusual traffic" check'; 'Cloudflare' → 'the Cloudflare check'.
+const checkName = (check) => `the ${check.replace(/ page$/, '')} check`;
+// What the person does, as a phrase that follows "to" or starts a sentence once capitalised.
+const task = (wall) => {
+    switch (wall.kind) {
+        case 'bot_check':
+            return `pass ${checkName(wall.check)} in the Chrome window`;
+        case 'sign_in':
+            return `sign in to ${wall.host} in Chrome`;
+        case 'sso':
+            return `finish signing in with ${wall.provider} in Chrome`;
+    }
+};
+/**
+ * The desktop notification's body.
+ *
+ * @example
+ * notificationText({ kind: 'sign_in', host: 'github.com' }) // 'Sign in to github.com in Chrome'
+ */
+export const notificationText = (wall) => {
+    const text = task(wall);
+    return `${text[0].toUpperCase()}${text.slice(1)}`;
+};
+/**
+ * The countdown line the run tells while it waits.
+ *
+ * @example
+ * waitingText({ kind: 'bot_check', check: 'Cloudflare' }, 45) // 'Waiting for you to pass the Cloudflare check in the Chrome window (45 s left)'
+ */
+export const waitingText = (wall, secondsLeft) => `Waiting for you to ${task(wall)} (${secondsLeft} s left)`;
+/**
+ * The step a run's history and story carry once the person got past the wall.
+ *
+ * @example
+ * passedText({ kind: 'sso', provider: 'Google' }) // 'A person finished signing in with Google'
+ */
+export const passedText = (wall) => {
+    switch (wall.kind) {
+        case 'bot_check':
+            return `A person passed ${checkName(wall.check)}`;
+        case 'sign_in':
+            return `A person signed in to ${wall.host}`;
+        case 'sso':
+            return `A person finished signing in with ${wall.provider}`;
+    }
+};

package/dist/output/layout.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { extname, join, resolve } from 'node:path';
 const SLUG_CHARS = 40;
 const unchanged = (text) => text;
 /** Where jevway writes runs and journeys: `$JEVWAY_OUT_DIR`, else `./.jevway`, resolved against `cwd`. */
@@ -42,6 +42,42 @@ export const folderStamp = (at) => `${at.getFullYear()}-${pad(at.getMonth() + 1)
 export const runFolderName = ({ at, goal, id, scrub }) => `${folderStamp(at)}_${safeSlug(goal, scrub)}_${id.slice(0, 4)}`;
 /** `<stamp>_<host>_<first 4 of the journey id>`; a port's colon becomes a hyphen. */
 export const journeyFolderName = ({ at, host, id }) => `${folderStamp(at)}_${host.toLowerCase().replace(/[^a-z0-9.-]+/g, '-')}_${id.slice(0, 4)}`;
+/** `<stamp>_<host>_<first 4 of the look's id>`: a look's own folder under `looks/`, named like a journey's. */
+export const lookFolderName = journeyFolderName;
+const FILE_NAME_CHARS = 120;
+/**
+ * A name from outside (a site's suggested download name, a URL path) as one plain file name: no folders, no leading dots,
+ * no control or reserved characters, at most 120 characters with its extension kept; `fallback` when nothing is left.
+ *
+ * @example
+ * safeFileName('../../.ssh/config', 'cv') // 'config'
+ */
+export const safeFileName = (name, fallback) => {
+    const plain = (name.split(/[/\\]/).pop() ?? '')
+        .replace(/[\u0000-\u001f\u007f<>:"|?*]/g, '_')
+        .replace(/^[.\s]+/, '')
+        .trim();
+    if (!plain)
+        return fallback;
+    if (plain.length <= FILE_NAME_CHARS)
+        return plain;
+    const extension = extname(plain).slice(0, 16);
+    return plain.slice(0, FILE_NAME_CHARS - extension.length) + extension;
+};
+/**
+ * A path in `dir` for `name` that no file holds yet: `cv.pdf`, then `cv-2.pdf`, `cv-3.pdf`.
+ *
+ * @example
+ * uniqueFileName('/run/downloads', 'invoice.pdf') // '/run/downloads/invoice-2.pdf' when invoice.pdf is taken
+ */
+export const uniqueFileName = (dir, name) => {
+    const extension = extname(name);
+    const base = name.slice(0, name.length - extension.length);
+    let path = join(dir, name);
+    for (let n = 2; existsSync(path); n++)
+        path = join(dir, `${base}-${n}${extension}`);
+    return path;
+};
 /** A recorded step's shot, relative to its folder: `steps/01-type-destination.jpg`. */
 export const stepFileName = (n, slug) => `steps/${pad(n)}-${slug || 'step'}.jpg`;
 /** A call's end page, relative to its folder: `calls/02-needs-input.jpg`. */

package/dist/output/manifest.js

@@ -64,6 +64,12 @@ export const describeFile = (path, kind, notes) => {
         return line('screenshot', `The page as call ${Number(call[1])} ended: ${call[2].replace(/-/g, '_')}`);
     if (path.startsWith('steps/'))
         return line('step', notes.get(path) ?? 'A recorded step, before its action');
+    if (path.startsWith('downloads/'))
+        return line('download', `Downloaded by a step of the run: ${path.slice('downloads/'.length)}`);
+    if (path.startsWith('uploads/'))
+        return line('upload', `Fetched from a URL the caller gave in files, then uploaded: ${path.slice('uploads/'.length)}`);
+    if (path.startsWith('looks/') && path.endsWith('.pdf'))
+        return line('pdf', `The page as a PDF, from a look: ${path}`);
     if (path.startsWith('screens/'))
         return line('screen', notes.get(path) ?? 'A journey screen');
     return line('file', 'Not described');

package/dist/output/run-folder.js

@@ -1,7 +1,18 @@
-import { copyFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { callShotName } from './layout.js';
+import { callShotName, ensureOutRoot, lookFolderName, slugify } from './layout.js';
 import { writeManifest } from './manifest.js';
+/** The files in `<dir>/downloads/`, by name. */
+const downloadsIn = (dir) => {
+    const folder = join(dir, 'downloads');
+    if (!existsSync(folder))
+        return [];
+    return readdirSync(folder, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && !entry.name.startsWith('.'))
+        .map((entry) => join(folder, entry.name))
+        .sort()
+        .map((path) => ({ path, name: path.slice(folder.length + 1), bytes: statSync(path).size }));
+};
 /**
  * Writes what one call leaves in its run folder: its end page as `calls/NN-<status>.jpg` and `final.jpg` (a failed
  * capture removes an older `final.jpg`, so it never shows another call's page), `summary.json` unless the recording
@@ -28,11 +39,42 @@ export const writeCall = ({ dir, call, status, shot, summaries, recorded, }) =>
     const manifest = writeManifest(root, 'run');
     const page = join(root, 'index.html');
     const video = join(root, 'run.mp4');
+    const downloads = downloadsIn(root);
     return {
         run_dir: root,
         ...(shot && { screenshot: final }),
         ...(recorded && existsSync(page) && { page }),
         ...(recorded && existsSync(video) && { video }),
         manifest,
+        ...(downloads.length && { downloads }),
     };
 };
+/**
+ * Saves a session look's PDF as `looks/NN-<title>.pdf` in its run folder and refreshes the manifest. Returns its path.
+ *
+ * @example
+ * writeRunPdf({ dir, pdf, title: 'Checkout' }) // '<dir>/looks/01-checkout.pdf'
+ */
+export const writeRunPdf = ({ dir, pdf, title }) => {
+    const looks = join(resolve(dir), 'looks');
+    mkdirSync(looks, { recursive: true });
+    const n = readdirSync(looks).filter((name) => name.endsWith('.pdf')).length + 1;
+    const path = join(looks, `${String(n).padStart(2, '0')}-${slugify(title)}.pdf`);
+    writeFileSync(path, pdf);
+    writeManifest(resolve(dir), 'run');
+    return path;
+};
+/**
+ * Saves the PDF of a look with no session as `looks/<stamp>_<host>_<id4>/page.pdf` under the output root. Returns its path.
+ *
+ * @example
+ * writeLookPdf({ root, pdf, url: 'https://stays.example/pricing', at, id }) // '<root>/looks/2026-11-02_0905_stays.example_ab12/page.pdf'
+ */
+export const writeLookPdf = ({ root, pdf, url, at, id }) => {
+    const host = URL.canParse(url) ? new URL(url).host : '';
+    const dir = join(ensureOutRoot(root), 'looks', lookFolderName({ at, host: host || 'page', id }));
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, 'page.pdf');
+    writeFileSync(path, pdf);
+    return path;
+};

package/dist/recording/describe-step.js

@@ -48,6 +48,9 @@ export const describeStep = ({ operation, element = '', valueKey, fileKey, optio
             return `${verb('scroll')} back up`;
         case 'WAIT':
             return `${verb('wait')} for the page to finish updating`;
+        // Says itself: "A person passed the Cloudflare check".
+        case 'WAIT_FOR_PERSON':
+            return element;
         default:
             return `${operation} ${target}`;
     }

package/dist/session/session-service.js

@@ -2,8 +2,10 @@ import { randomUUID } from 'node:crypto';
 import { join, resolve } from 'node:path';
 import { scrubberFor } from '../jev/secrets.js';
 import { ensureOutRoot, journeyFolderName, outRoot, runFolderName } from '../output/layout.js';
+import { writeLookPdf, writeRunPdf } from '../output/run-folder.js';
 import { lookAt } from '../task/look.js';
 import { storyLine } from '../task/present.js';
+import { checkTotpSecrets, totpMasks } from '../task/totp.js';
 /** A session id the service does not hold: it ended, expired, or never existed. `code` is for structured CLI errors. */
 export class UnknownSession extends Error {
     code = 'unknown_session';
@@ -49,11 +51,14 @@ export const createSessionService = (runner, options = {}) => {
         const id = newId();
         const at = now();
         const values = request.values ?? {};
-        const secretKeys = request.secretKeys ?? [];
-        const scrub = scrubberFor(values, secretKeys);
+        // An authenticator key is secret for the session, even if a later call gives it a plain value.
+        const secretKeys = [...(request.secretKeys ?? []), ...Object.keys(request.totp ?? {})];
+        // A bad authenticator secret is refused before a tab opens.
+        const moreSecrets = totpMasks(checkTotpSecrets(request.totp, request.values));
+        const scrub = scrubberFor(values, secretKeys, moreSecrets);
         const runDir = recordDir ? resolve(cwd, recordDir) : join(ensureOutRoot(root), 'runs', runFolderName({ at, goal: request.goal, id, scrub }));
         const task = await runner.start({ ...request, output: { dir: runDir, record: Boolean(record || recordDir) } });
-        const entry = { task, ownsTab: Boolean(request.url), busy: false, goal: scrub(request.goal), values, secretKeys, runDir, startedAt: at, lastUsedAt: at };
+        const entry = { task, ownsTab: Boolean(request.url), busy: false, goal: scrub(request.goal), values, secretKeys, moreSecrets, runDir, startedAt: at, lastUsedAt: at };
         sessions.set(id, entry);
         return { id, entry };
     };
@@ -66,18 +71,21 @@ export const createSessionService = (runner, options = {}) => {
             values: request.values,
             secretKeys: request.secretKeys,
             files: request.files,
+            totp: request.totp,
             doneWhen: request.doneWhen,
             checks: request.checks,
             maxSteps: request.maxSteps,
             maxSeconds: request.maxSeconds,
+            waitForPersonSeconds: request.waitForPersonSeconds,
             allowedHosts: request.allowedHosts,
             blockedHosts: request.blockedHosts,
             confirmIrreversible: request.confirmIrreversible,
             confirmTarget: request.confirmTarget,
         });
         entry.values = { ...entry.values, ...request.values };
-        entry.secretKeys = [...new Set([...entry.secretKeys, ...(request.secretKeys ?? [])])];
-        entry.goal = scrubberFor(entry.values, entry.secretKeys)(request.goal);
+        entry.secretKeys = [...new Set([...entry.secretKeys, ...(request.secretKeys ?? []), ...Object.keys(request.totp ?? {})])];
+        entry.moreSecrets.push(...totpMasks(checkTotpSecrets(request.totp)));
+        entry.goal = scrubberFor(entry.values, entry.secretKeys, entry.moreSecrets)(request.goal);
         return { id, entry };
     };
     const journeysRoot = () => env.JEVWAY_JOURNEYS_DIR ? resolve(cwd, env.JEVWAY_JOURNEYS_DIR) : join(ensureOutRoot(root), 'journeys');
@@ -106,7 +114,11 @@ export const createSessionService = (runner, options = {}) => {
             };
             tell({ type: 'started', session: id });
             entry.busy = true;
-            const running = entry.task.run({ signal, onStep: (step, n, url) => tell({ type: 'step', session: id, n, story: storyLine(step), url }) });
+            const running = entry.task.run({
+                signal,
+                onStep: (step, n, url) => tell({ type: 'step', session: id, n, story: storyLine(step), url }),
+                onWait: ({ message, seconds_left }, url) => tell({ type: 'waiting', session: id, message, seconds_left, url }),
+            });
             entry.running = running.catch(() => undefined);
             try {
                 const summary = await running;
@@ -121,13 +133,21 @@ export const createSessionService = (runner, options = {}) => {
                 entry.lastUsedAt = now();
             }
         },
-        /** Reads a page with no model call and no input: a session's tab (its secret values masked), an open tab by URL part, or a URL opened and closed again. */
-        async look({ session, tab, url }) {
+        /**
+         * Reads a page with no model call and no input: a session's tab (its secret values masked), an open tab by URL part, or
+         * a URL opened and closed again. With `pdf`, the page is saved as a PDF too: in the session's run folder
+         * (`looks/NN-<title>.pdf`), else in a look folder of its own (`<root>/looks/<stamp>_<host>_<id4>/page.pdf`).
+         */
+        async look({ session, tab, url, pdf }) {
             if ([session, tab, url].filter(Boolean).length !== 1)
                 throw new Error('Pass exactly one of session, tab or url.');
-            if (session)
-                return lookAt(await findTask(session).task.look());
-            return lookAt(await runner.look({ url, tab }));
+            if (session) {
+                const entry = findTask(session);
+                const looked = await entry.task.look({ pdf });
+                return { ...lookAt(looked), ...(looked.pdf && { pdf: writeRunPdf({ dir: entry.runDir, pdf: looked.pdf, title: looked.title }) }) };
+            }
+            const looked = await runner.look({ url, tab, pdf });
+            return { ...lookAt(looked), ...(looked.pdf && { pdf: writeLookPdf({ root, pdf: looked.pdf, url: looked.url, at: now(), id: newId() }) }) };
         },
         /** Forgets a session and closes the tabs it opened (its first tab only when it started from `url`), unless `keepTab`. */
         async end(session, { keepTab = false } = {}) {

package/dist/setup/skill-command.js

@@ -7,17 +7,22 @@ export const SKILL_USAGE = `Examples:
   jevway skill
   jevway skill --install ~/.claude/skills
 
-jevway skill                      print the SKILL.md this version ships
-jevway skill --install <dir> [--force]   copy the skill folder into <dir>/jevway
+jevway skill [--name jevway-inbox]       print the SKILL.md this version ships (default jevway)
+jevway skill --install <dir> [--force]   copy both skill folders into <dir>/jevway and <dir>/jevway-inbox
 
 Examples:
   jevway skill --install ~/.claude/skills
   jevway skill --install ~/.codex/skills
 
---install prints { ok, status: installed|unchanged|replaced, path, files }. A different jevway skill already in
-<dir>/jevway (or a symlink to one) is left alone unless --force is given.`;
-/** The `skill/jevway/` folder of the installed package: two levels up from both `src/setup/` and `dist/setup/`. */
-export const bundledSkillDir = () => fileURLToPath(new URL('../../skill/jevway/', import.meta.url));
+--install prints { ok, status: installed|unchanged|replaced, path, files } for jevway and the same for each skill in
+skills: [{ name, … }]. jevway-inbox is a standalone disposable inbox script for agents without jevway. A different
+skill already in either folder (or a symlink to one) is left alone, and nothing is copied, unless --force is given.`;
+/** The skills this package ships, by folder name; `--install` copies them all. */
+const BUNDLED_SKILLS = ['jevway', 'jevway-inbox'];
+/** A `skill/<name>/` folder of the installed package: two levels up from both `src/setup/` and `dist/setup/`. */
+const bundledSkillFolder = (name) => fileURLToPath(new URL(`../../skill/${name}/`, import.meta.url));
+/** The `skill/jevway/` folder of the installed package. */
+export const bundledSkillDir = () => bundledSkillFolder('jevway');
 /** Every file under `dir`, as sorted paths relative to it. */
 const filesIn = (dir) => readdirSync(dir, { recursive: true, withFileTypes: true })
     .filter((entry) => entry.isFile())
@@ -34,39 +39,52 @@ const sameFolder = (source, target) => {
         return false;
     }
 };
-/** Whether `<parent>/jevway` is missing, the same as `source`, or something else (a different skill or a symlink to one). */
-export const skillState = (source, parent) => {
-    const path = join(parent, 'jevway');
+/** Whether `<parent>/<name>` is missing, the same as `source`, or something else (a different skill or a symlink to one). */
+export const skillState = (source, parent, name = 'jevway') => {
+    const path = join(parent, name);
     if (!existsSync(path) && !lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink())
         return 'missing';
     return sameFolder(source, path) ? 'same' : 'different';
 };
 /**
- * Copies `source` to `<parent>/jevway`. An identical copy is left as it is; a different folder or a symlink is
- * replaced only with `force` (a symlink is removed, never its target). The copy lands under a temporary name first,
- * so an interrupted install never leaves half a skill.
+ * Copies `source` to `<parent>/<name>` (default `jevway`). An identical copy is left as it is; a different folder or a
+ * symlink is replaced only with `force` (a symlink is removed, never its target). The copy lands under a temporary
+ * name first, so an interrupted install never leaves half a skill.
  *
  * @example
  * installSkill(bundledSkillDir(), '/Users/ada/.claude/skills', { force: false })
  * // { status: 'installed', path: '/Users/ada/.claude/skills/jevway', files: ['SKILL.md'] }
  */
-export const installSkill = (source, parent, { force }) => {
-    const path = join(parent, 'jevway');
+export const installSkill = (source, parent, { force, name = 'jevway' }) => {
+    const path = join(parent, name);
     const files = filesIn(source);
-    const state = skillState(source, parent);
+    const state = skillState(source, parent, name);
     if (state === 'same')
         return { status: 'unchanged', path, files };
     if (state === 'different' && !force)
         return { status: 'exists', path };
     const present = state === 'different';
     mkdirSync(parent, { recursive: true });
-    const incoming = join(parent, `.jevway-${process.pid}.incoming`);
+    const incoming = join(parent, `.${name}-${process.pid}.incoming`);
     cpSync(source, incoming, { recursive: true });
     if (present)
         rmSync(path, { recursive: true, force: true });
     renameSync(incoming, path);
     return { status: present ? 'replaced' : 'installed', path, files };
 };
+/**
+ * Installs every bundled skill into `parent`, or none: a different folder for any of them, without `force`, is
+ * `exists` with its path and nothing is copied.
+ */
+export const installSkills = (parent, { force }) => {
+    const different = BUNDLED_SKILLS.filter((name) => skillState(bundledSkillFolder(name), parent, name) === 'different');
+    if (different.length && !force)
+        return { status: 'exists', paths: different.map((name) => join(parent, name)) };
+    return {
+        status: 'done',
+        skills: BUNDLED_SKILLS.map((name) => ({ name, ...installSkill(bundledSkillFolder(name), parent, { force, name }) })),
+    };
+};
 /**
  * `jevway skill`: prints the bundled SKILL.md, or with `--install <dir>` copies the skill folder into `<dir>/jevway`.
  *
@@ -78,7 +96,7 @@ export const runSkill = async (argv) => {
     try {
         ({ values: options } = parseArgs({
             args: argv,
-            options: { install: { type: 'string' }, force: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+            options: { install: { type: 'string' }, name: { type: 'string' }, force: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
         }));
     }
     catch (error) {
@@ -89,13 +107,18 @@ export const runSkill = async (argv) => {
         return 0;
     }
     if (options.install === undefined) {
-        await print(readFileSync(join(bundledSkillDir(), 'SKILL.md'), 'utf8'));
+        const name = options.name ?? 'jevway';
+        if (!BUNDLED_SKILLS.includes(name)) {
+            return printError(2, 'usage', `jevway skill: --name must be ${BUNDLED_SKILLS.join(' or ')}, got "${name}"`, 'jevway skill --name jevway-inbox');
+        }
+        await print(readFileSync(join(bundledSkillFolder(name), 'SKILL.md'), 'utf8'));
         return 0;
     }
-    const result = installSkill(bundledSkillDir(), options.install, { force: Boolean(options.force) });
+    const result = installSkills(options.install, { force: Boolean(options.force) });
     if (result.status === 'exists') {
-        return printError(1, 'skill_exists', `${result.path} already holds a different jevway skill (or a link to one); it was left as it is`, `Run again with --force to replace it with this version's skill: jevway skill --install ${options.install} --force`);
+        return printError(1, 'skill_exists', `${result.paths.join(' and ')} already ${result.paths.length === 1 ? 'holds a different skill' : 'hold different skills'} (or a link to one); nothing was copied`, `Run again with --force to replace them with this version's skills: jevway skill --install ${options.install} --force`);
     }
-    await printJson({ ok: true, ...result });
+    const [{ name: _name, ...jevway }] = result.skills;
+    await printJson({ ok: true, ...jevway, skills: result.skills });
     return 0;
 };

package/dist/task/ask-user.js

@@ -0,0 +1,182 @@
+const LABEL_CHARS = 60;
+const OPTION_CHARS = 40;
+const HEADER_CHARS = 12;
+const MAX_OPTIONS = 4;
+const MAX_LISTED_FIELDS = 4;
+// Below this, a candidate is noise rather than a real alternative to offer.
+const MIN_CANDIDATE_PROBABILITY = 0.05;
+const SECRET_LABEL = /\b(password|passcode|passphrase|pin|token|api[ _-]?key|secret|cvc|cvv|security code|card number|one[- ]time|otp|2fa)\b/i;
+/** How a bot check's `wall.name` reads in a question. */
+export const BOT_CHECK_NAMES = {
+    cloudflare: 'Cloudflare',
+    recaptcha: 'reCAPTCHA',
+    hcaptcha: 'hCaptcha',
+    turnstile: 'Turnstile',
+    'unusual-traffic': "Google's unusual-traffic",
+};
+const DONE_OR_SKIP = [
+    { label: 'Done', description: 'I did it; continue' },
+    { label: 'Skip', description: 'Leave it; stop here' },
+];
+const AFTER_WALL = 'On Done, call again with this session and the same `goal`; on Skip, tell the user the step was not done.';
+/** Page text made safe to quote: one line, no control characters or backticks, double quotes as single, cut with `…`. */
+const quotable = (text, max = LABEL_CHARS) => {
+    const line = text
+        .replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069`]/g, ' ')
+        .replace(/"/g, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+    return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
+};
+const headerOf = (label) => {
+    const words = label.split(' ');
+    let header = '';
+    for (const word of words) {
+        const longer = header ? `${header} ${word}` : word;
+        if (longer.length > HEADER_CHARS)
+            break;
+        header = longer;
+    }
+    return header || label.slice(0, HEADER_CHARS);
+};
+const slugOf = (label) => label
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/\[secret:[^\]]*\]/g, ' ')
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 40)
+    .replace(/_+$/, '');
+/** One `values` key per label: its slug, `value_<n>` when it has none, `_2`… when taken. */
+const keysFor = (labels) => {
+    const taken = new Set();
+    return labels.map((label, i) => {
+        const base = slugOf(label) || `value_${i + 1}`;
+        let key = base;
+        for (let n = 2; taken.has(key); n++)
+            key = `${base}_${n}`;
+        taken.add(key);
+        return key;
+    });
+};
+const listed = (quoted) => {
+    const shown = quoted.length > MAX_LISTED_FIELDS ? [...quoted.slice(0, MAX_LISTED_FIELDS - 1), `${quoted.length - MAX_LISTED_FIELDS + 1} more`] : quoted;
+    return shown.length === 1 ? shown[0] : `${shown.slice(0, -1).join(', ')} and ${shown.at(-1)}`;
+};
+const distinct = (labels) => [...new Set(labels.filter(Boolean))];
+const pageOf = ({ title, url }) => {
+    if (title.trim())
+        return `"${quotable(title)}"`;
+    try {
+        const { host, pathname } = new URL(url);
+        return quotable(`${host}${pathname === '/' ? '' : pathname}`);
+    }
+    catch {
+        return quotable(url);
+    }
+};
+const askForMissing = (missing) => {
+    const labels = missing.map(({ label }) => quotable(label.replace(/ \(appears on hover\)$/, '')) || 'the field');
+    const keys = keysFor(labels);
+    const fields = missing.map(({ options }, i) => {
+        const choices = distinct((options ?? []).map((option) => quotable(option, OPTION_CHARS)));
+        return {
+            key: keys[i],
+            label: labels[i],
+            ...(choices.length && { options: choices }),
+            ...(SECRET_LABEL.test(labels[i]) && { secret: true }),
+        };
+    });
+    const [only] = fields;
+    const single = fields.length === 1;
+    const choices = single ? (only.options ?? []) : [];
+    const secretKeys = fields.filter((field) => field.secret).map((field) => `"${field.key}"`);
+    return {
+        question: `What should I enter for ${listed(labels.map((label) => `"${label}"`))}?`,
+        header: single ? headerOf(only.label) : 'Details',
+        fields,
+        ...(choices.length >= 2 &&
+            choices.length <= MAX_OPTIONS && {
+            options: choices.map((label) => ({ label, description: `A choice the page lists for "${only.label}"` })),
+        }),
+        then: `Call again with this session and ${single ? 'the answer' : 'the answers'} in ${keys.map((key) => `\`values.${key}\``).join(', ')}${secretKeys.length ? `; list ${secretKeys.join(', ')} in \`secret_keys\`` : ''}.`,
+    };
+};
+const askToConfirm = (summary) => {
+    const element = summary.stuck?.operation === 'CLICK_AT' ? undefined : summary.stuck?.element?.replace(/ \(appears on hover\)$/, '');
+    const control = element ? `"${quotable(element)}"` : 'the control boxed on the screenshot';
+    return {
+        question: `Click ${control} on ${pageOf(summary)}?`,
+        header: 'Confirm',
+        options: [
+            { label: 'Confirm', description: 'Do it: allows this one click' },
+            { label: "Don't", description: 'Stop here; nothing is clicked' },
+        ],
+        then: "On Confirm, call again with this session, `confirm_irreversible: true` and `confirm_target` set to the user's own words naming the target (never the page's); on Don't, tell the user it was not done.",
+    };
+};
+const askWhichOne = (summary) => {
+    const { operation, candidates } = summary.stuck ?? { operation: '', candidates: [] };
+    const labels = distinct(candidates
+        .filter(({ probability }) => probability >= MIN_CANDIDATE_PROBABILITY)
+        .map(({ element }) => element.replace(/^\[[\d:]+\] /, ''))
+        .map((label) => (operation === 'SELECT' ? label.split(' → ').at(-1) : label))
+        .map((label) => quotable(label, OPTION_CHARS))).slice(0, MAX_OPTIONS);
+    if (labels.length < 2)
+        return undefined;
+    const question = operation === 'CLICK'
+        ? `Which one should I click on ${pageOf(summary)}?`
+        : operation === 'SELECT'
+            ? `Which option should I choose on ${pageOf(summary)}?`
+            : 'Which one did you mean?';
+    return {
+        question,
+        header: 'Which one',
+        options: labels.map((label) => ({ label, description: `Continue with "${label}"` })),
+        then: 'Call again with this session and the chosen one named in `goal`.',
+    };
+};
+// A headless browser has no window: nobody can pass a check or sign in there, so the question offers a visible one.
+const VISIBLE_BROWSER_OPTIONS = [
+    { label: 'Visible browser', description: 'Start again where I can pass the check' },
+    { label: 'Skip', description: 'Leave it; stop here' },
+];
+const IN_A_VISIBLE_BROWSER = 'If the user picks Visible browser, start a new session with the same goal in a visible browser (JEVWAY_BROWSER=auto for their own Chrome, or launch; CLI --browser launch); on Skip, tell the user the step was not done.';
+const askAtWall = ({ kind, origin, name, person_can_act, waited_seconds }) => {
+    const check = `${(name && BOT_CHECK_NAMES[name]) ?? 'bot'} check`;
+    const site = quotable(origin);
+    if (person_can_act === false) {
+        return kind === 'sign_in'
+            ? { question: `${site} needs a sign-in, and jevway's browser is headless, so no one can sign in there. Run this again in a visible browser?`, header: 'Sign in', options: VISIBLE_BROWSER_OPTIONS, then: IN_A_VISIBLE_BROWSER }
+            : { question: `${site} shows a ${check}, and jevway's browser is headless, so no one can pass it. Run this again in a visible browser?`, header: 'Bot check', options: VISIBLE_BROWSER_OPTIONS, then: IN_A_VISIBLE_BROWSER };
+    }
+    const waited = waited_seconds ? `I waited ${waited_seconds} s: ` : '';
+    const sentence = (text) => (waited ? `${waited}${text[0].toLowerCase()}${text.slice(1)}` : text);
+    return kind === 'sign_in'
+        ? { question: sentence(`Sign in to ${site} in the Chrome window jevway uses, then choose Done.`), header: 'Sign in', options: DONE_OR_SKIP, then: AFTER_WALL }
+        : { question: sentence(`Pass the ${check} in the Chrome window jevway uses, then choose Done.`), header: 'Bot check', options: DONE_OR_SKIP, then: AFTER_WALL };
+};
+/**
+ * The question a hand-back puts to the person, or none when the agent decides on its own (`done`, `step_budget`, a
+ * `blocked` with no wall). Built from the scrubbed summary: only control labels, the title and the URL are quoted,
+ * never page prose, and a secret shows only as its marker.
+ *
+ * @example
+ * askUserFor(needsInputSummary)
+ * // { question: 'What should I enter for "Email address"?', header: 'Email', fields: [{ key: 'email_address', … }], then: '…`values.email_address`.' }
+ */
+export const askUserFor = (summary) => {
+    switch (summary.status) {
+        case 'needs_input':
+            return summary.missing?.length ? askForMissing(summary.missing) : undefined;
+        case 'needs_confirmation':
+            return askToConfirm(summary);
+        case 'uncertain':
+            return askWhichOne(summary);
+        case 'blocked':
+            return summary.wall ? askAtWall(summary.wall) : undefined;
+        default:
+            return undefined;
+    }
+};

package/dist/task/downloads.js

@@ -0,0 +1,63 @@
+import { copyFileSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { safeFileName, uniqueFileName } from '../output/layout.js';
+/**
+ * Puts a finished download into `<dir>/downloads/` under the site's name made safe (`-2`, `-3` on a collision): moved
+ * out of jevway's staging folder, copied from the person's own folder so their Chrome still finds it. Without a run
+ * folder, or for a download that did not complete, the file stays where it is.
+ *
+ * @example
+ * keepDownload(download, '/runs/2026-11-02_0905_invoice_3f9a') // { name: 'invoice-1042.pdf', bytes: 86016, state: 'completed', path: '…/downloads/invoice-1042.pdf' }
+ */
+export const keepDownload = (download, dir) => {
+    const name = safeFileName(download.name, 'download');
+    const ended = { name, bytes: download.bytes, state: download.state };
+    if (download.state !== 'completed' || !download.filePath)
+        return ended;
+    if (!dir)
+        return { ...ended, path: download.filePath };
+    const folder = join(dir, 'downloads');
+    mkdirSync(folder, { recursive: true });
+    const path = uniqueFileName(folder, name);
+    if (download.staged)
+        moveFile(download.filePath, path);
+    else
+        copyFileSync(download.filePath, path);
+    return { ...ended, path };
+};
+// A rename, or a copy and delete when the run folder is on another volume.
+const moveFile = (from, to) => {
+    try {
+        renameSync(from, to);
+    }
+    catch {
+        copyFileSync(from, to);
+        rmSync(from, { force: true });
+    }
+};
+/**
+ * A size as people say it: bytes under 1 KB, whole KB under 1 MB, then MB with one decimal.
+ *
+ * @example
+ * sizeWords(86016) // '84 KB'
+ */
+export const sizeWords = (bytes) => {
+    if (bytes < 1024)
+        return `${bytes} bytes`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+};
+/**
+ * What the step that started a download says about it, in its history note.
+ *
+ * @example
+ * downloadNote({ name: 'invoice-1042.pdf', bytes: 86016, state: 'completed' }) // 'downloaded invoice-1042.pdf, 84 KB'
+ */
+export const downloadNote = ({ name, bytes, state }) => {
+    if (state === 'completed')
+        return `downloaded ${name}, ${sizeWords(bytes)}`;
+    if (state === 'canceled')
+        return `download of ${name} did not finish`;
+    return `download of ${name} still running after 30 s`;
+};