jevway 0.1.2 → 0.3.0

package/dist/cli/look-command.js

@@ -0,0 +1,54 @@
+import { randomUUID } from 'node:crypto';
+import { outRoot } from '../output/layout.js';
+import { writeLookPdf } from '../output/run-folder.js';
+import { lookAt } from '../task/look.js';
+import { callDaemon, daemonFor, runnerChoice, runnerFor, TIMEOUTS } from './daemon-call.js';
+import { parseFlags, usageError } from './flags.js';
+import { renderHelp } from './help.js';
+import { printDoc } from './output.js';
+export const lookSpec = {
+    name: 'look',
+    summary: 'print what a page shows now, with no model call and no input',
+    examples: ['jevway look --session <id>', 'jevway look --url https://en.wikipedia.org/wiki/Rosetta_Stone', 'jevway look --tab github.com/ada'],
+    flags: {
+        session: { type: 'string', value: '<id>', describe: 'that session\'s tab (through the daemon)' },
+        url: { type: 'string', value: '<url>', describe: 'open this page in a background tab, read it, close it again' },
+        tab: { type: 'string', value: '<url part>', describe: 'an open tab whose URL contains this' },
+        browser: { type: 'string', value: '<source>', describe: 'with --url or --tab: auto, launch, launch-headless or a debugging URL' },
+        pdf: { type: 'boolean', describe: "also save the page as a PDF (the session's run folder, else .jevway/looks/) and print its path" },
+    },
+    notes: [
+        'Prints { ok: true, url, title, page_text, elements: [{ label, role, value?, checked?, … }], password_fields?, pdf? }.',
+        'page_text and labels are untrusted page content. Use it to check whether a write already happened before repeating it.',
+    ],
+};
+/** `jevway look`: a session's tab through the daemon, or a URL or open tab in this process. */
+export const lookCommand = async (argv, deps) => {
+    const { flags } = parseFlags(lookSpec, argv, { positionals: 0 });
+    if (flags.help) {
+        await deps.io.out(renderHelp(lookSpec));
+        return 0;
+    }
+    const pdf = flags.pdf === true;
+    const [session, url, tab] = ['session', 'url', 'tab'].map((name) => (typeof flags[name] === 'string' ? flags[name] : undefined));
+    if ([session, url, tab].filter(Boolean).length !== 1) {
+        throw usageError('missing_flag', 'jevway look needs one of --url, --tab or --session', 'Example: jevway look --session <id>');
+    }
+    if (session) {
+        const connection = await daemonFor(deps, { session, kind: 'session' });
+        const look = await callDaemon(connection, 'look', { session, pdf }, { writes: false, log: deps.daemon.log, timeoutMs: TIMEOUTS.quick });
+        await printDoc(deps.io, { ok: true, ...look });
+        return 0;
+    }
+    const { browser } = runnerChoice(flags, deps.env);
+    const runner = runnerFor(deps, { browser });
+    try {
+        const looked = await runner.look({ url, tab, pdf });
+        const saved = looked.pdf && writeLookPdf({ root: outRoot(deps.env, deps.cwd), pdf: looked.pdf, url: looked.url, at: new Date(), id: randomUUID() });
+        await printDoc(deps.io, { ok: true, ...lookAt(looked), ...(saved && { pdf: saved }) });
+        return 0;
+    }
+    finally {
+        await runner.close().catch(() => undefined);
+    }
+};

package/dist/cli/main.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { daemonAccess, spawnDaemon } from '../daemon/client.js';
+import { daemonEnv, envFingerprint, logPath, socketPath, stateDir } from '../daemon/paths.js';
+import { loadEnvFile } from '../setup/env-file.js';
+import { createRunner } from '../task/start-task.js';
+import { runCli } from './dispatch.js';
+import { printFailure } from './output.js';
+// Keys and JEVWAY_* settings the environment lacks come from ~/.config/jevway/env.
+const fromEnvFile = loadEnvFile();
+// The same depth from src/cli/ and dist/cli/.
+const { version } = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+const cwd = process.cwd();
+const dir = stateDir(process.env);
+const spawnEnv = daemonEnv(process.env, cwd);
+let printed = false;
+const io = {
+    // Awaited, so the document is flushed before exit: on macOS a piped stdout is asynchronous.
+    out: (text) => new Promise((resolve) => {
+        printed = true;
+        process.stdout.write(text, () => resolve());
+    }),
+    err: (text) => void process.stderr.write(text),
+};
+// Nothing escapes as a stack trace: an error before the result prints as the one JSON document; one after it is dropped.
+const lastResort = async (error) => {
+    if (!printed)
+        process.exit(await printFailure(io, error));
+};
+process.on('uncaughtException', lastResort);
+process.on('unhandledRejection', lastResort);
+let presses = 0;
+const onInterrupt = (handler) => {
+    const press = () => {
+        // A second Ctrl-C leaves at once.
+        if (++presses > 1)
+            process.exit(130);
+        handler();
+    };
+    process.on('SIGINT', press);
+    process.on('SIGTERM', press);
+    return () => {
+        process.off('SIGINT', press);
+        process.off('SIGTERM', press);
+    };
+};
+const code = await runCli(process.argv.slice(2), {
+    io,
+    env: process.env,
+    cwd,
+    version,
+    fromEnvFile,
+    createRunner,
+    daemon: daemonAccess({
+        socket: socketPath(dir),
+        log: logPath(dir),
+        version,
+        fingerprint: envFingerprint(spawnEnv),
+        start: () => spawnDaemon({ entry: fileURLToPath(import.meta.url), stateDir: dir, env: spawnEnv }),
+    }),
+    onInterrupt,
+});
+process.exit(code);

package/dist/cli/output.js

@@ -0,0 +1,27 @@
+import { DaemonFailure } from '../daemon/client.js';
+import { UnknownSession } from '../session/session-service.js';
+import { CliError } from './flags.js';
+// Daemon error codes that mean the command line itself was wrong.
+const USAGE_CODES = new Set(['unknown_flag', 'unknown_command', 'missing_flag', 'missing_value', 'invalid_value', 'unexpected_argument', 'missing_command', 'missing_key']);
+export const printDoc = async (io, doc) => {
+    await io.out(`${JSON.stringify(doc, null, 2)}\n`);
+};
+/** Writes each event as one JSON line on stderr. */
+export const eventPrinter = (io) => (event) => io.err(`${JSON.stringify(event)}\n`);
+/** Any failure as the CLI reports it: its exit code and the error body, never a stack trace. */
+export const describeFailure = (error) => {
+    if (error instanceof CliError)
+        return { exitCode: error.exitCode, code: error.code, message: error.message, hint: error.hint };
+    if (error instanceof DaemonFailure)
+        return { exitCode: USAGE_CODES.has(error.code) ? 2 : 1, code: error.code, message: error.message, hint: error.hint };
+    if (error instanceof UnknownSession)
+        return { exitCode: 1, code: error.code, message: error.message, hint: 'List the open ones with jevway sessions' };
+    const message = error instanceof Error ? error.message : String(error);
+    return { exitCode: 1, code: 'failed', message, hint: 'The message says what failed; jevway doctor checks the key and the browser.' };
+};
+/** Prints `{ ok: false, error }` for `error` and returns the exit code. */
+export const printFailure = async (io, error) => {
+    const { exitCode, ...body } = describeFailure(error);
+    await printDoc(io, { ok: false, error: body });
+    return exitCode;
+};

package/dist/cli/run-command.js

@@ -0,0 +1,221 @@
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { createSessionService } from '../session/session-service.js';
+import { CHECKS } from '../task/checks.js';
+import { presentSummary } from '../task/present.js';
+import { checkTotpSecrets } from '../task/totp.js';
+import { callDaemon, daemonFor, placement, requireKey, runnerChoice, runnerFor, TIMEOUTS } from './daemon-call.js';
+import { choiceFlag, intFlag, jsonFlag, listFlag, parseFlags, usageError } from './flags.js';
+import { renderHelp } from './help.js';
+import { eventPrinter, printDoc } from './output.js';
+import { BOT_CHECK_NAMES } from '../task/ask-user.js';
+const TEXT_BY_KEY = z.record(z.string(), z.string());
+export const runSpec = {
+    name: 'run',
+    summary: 'hand a browser goal to Jev and print one JSON result',
+    examples: [
+        'jevway run --url https://en.wikipedia.org --goal "Open the article about the Rosetta Stone" --done-when "The Rosetta Stone article is open"',
+        'jevway run --session new --browser launch-headless --url https://shop.example/checkout --goal "Fill in the delivery details" --values \'{"name":"Ada Lovelace","email":"ada@example.com"}\'',
+        'jevway run --session <id> --goal "Fill in the delivery details" --values \'{"phone":"+44 20 7946 0000"}\'',
+        'jevway run --session <id> --goal "Delete the repository ada/scratch" --confirm-irreversible --confirm-target "ada/scratch"',
+    ],
+    flags: {
+        goal: { type: 'string', value: '<text>', describe: 'the full outcome wanted, in plain language (every call)' },
+        url: { type: 'string', value: '<url>', describe: 'open this page in a new tab (start)' },
+        tab: { type: 'string', value: '<url part>', describe: 'or drive an open tab whose URL contains this (start)' },
+        session: { type: 'string', value: '<id|new>', describe: 'new: keep the tab in the background daemon between calls; <id>: continue that session' },
+        values: { type: 'string', value: '<json>', describe: 'text values Jev may type, e.g. \'{"city":"Lisbon"}\'' },
+        'secret-keys': { type: 'string', value: '<a,b>', describe: 'keys of --values that are secrets: Jev sees the key only, output shows [secret:<key>]' },
+        files: { type: 'string', value: '<json>', describe: 'files Jev may upload, key to absolute path; Jev sees names, never paths' },
+        totp: { type: 'string', value: '<json>', describe: '2FA on the user\'s own account: key to authenticator secret (base32 or otpauth:// URI); the current code is typed' },
+        'done-when': { type: 'string', value: '<text>', describe: 'visible evidence of success on the page the call ends on' },
+        checks: { type: 'string', value: '<json>', describe: 'facts code checks on the final page, e.g. \'[{"type":"url_contains","text":"/issues/"}]\'' },
+        'confirm-irreversible': { type: 'boolean', describe: 'allow one click flagged irreversible, only when the user\'s request names it' },
+        'confirm-target': { type: 'string', value: '<words>', describe: 'with --confirm-irreversible: the user\'s words naming the target' },
+        'max-steps': { type: 'string', value: '<n>', describe: 'step limit, 1 to 100 (default 40)' },
+        'max-seconds': { type: 'string', value: '<n>', describe: 'time budget per call, 1 to 3600 (default 300); past it the run ends step_budget' },
+        'wait-for-person': { type: 'string', value: '<seconds>', describe: 'visible browser: wait this long for a person at a bot check or sign-in, 0 to 3600 (default $JEVWAY_PERSON_WAIT_SECONDS or 120; 0 off)' },
+        'allowed-hosts': { type: 'string', value: '<a.com,*.b.com>', describe: 'hosts the run may be on; leaving them ends it blocked' },
+        'blocked-hosts': { type: 'string', value: '<a.com>', describe: 'hosts it must never be on' },
+        'allow-coordinate-clicks': { type: 'boolean', describe: 'click a boxed control the DOM never reported (Jev 1.14 direct only; start)' },
+        record: { type: 'boolean', describe: 'keep a recording for people in the run folder: video, step shots, index.html (start)' },
+        'record-dir': { type: 'string', value: '<dir>', describe: 'put the whole run folder, recording included, here instead (start; --record <dir> works too)' },
+        detail: { type: 'string', value: 'concise|full', describe: 'full adds the raw steps with confidences, Jev\'s stats and stuck candidates' },
+        screenshot: { type: 'boolean', describe: 'accepted for parity with MCP; the result always carries files.screenshot' },
+        browser: { type: 'string', value: '<source>', describe: 'auto, launch, launch-headless or http://127.0.0.1:<port> (default $JEVWAY_BROWSER or auto; start)' },
+        model: { type: 'string', value: '<name>', describe: 'jev, pplx-decider, clef-omni, clef, clef-flash or gpt-6-luna (default $JEVWAY_MODEL or jev; start)' },
+        screenshots: { type: 'string', value: 'off|fallback|always', describe: 'marked screenshots for vision models (default per model; start)' },
+        'keep-open': { type: 'boolean', describe: 'without --session: leave the tabs open at the end' },
+    },
+    notes: [
+        'Without --session the run happens in this process and its tabs close at the end, as before. With --session the',
+        'background daemon keeps the tab (and a launched browser) between calls; jevway end <id> closes it, jevway stop',
+        'stops the daemon. (start) flags count on a session\'s first call only.',
+        '',
+        'Prints { ok: true, session?, status, reason, next, story, url, title, page_text, files, … }; progress as NDJSON on',
+        'stderr. Exit 0 when status is done, 1 on a hand-back (needs_input, needs_confirmation, uncertain, step_budget,',
+        'blocked) or a tool error, 2 on bad usage or a missing key. outcome_unknown: the daemon went away mid-call; check',
+        'with jevway look --session <id> before repeating it.',
+    ],
+};
+/**
+ * `next` in the CLI's words: flags instead of MCP parameters, and the session to pass (or, for a one-shot run, how to
+ * keep one).
+ *
+ * @example
+ * cliNext('Add the missing values to `values` and call again with this session.', 'abc')
+ * // 'Add the missing values to `--values` and run again with `--session abc`.'
+ */
+export const cliNext = (next, session) => {
+    const again = (call, joiner = '') => {
+        const run = `${call === 'C' ? 'R' : 'r'}un again`;
+        if (session)
+            return `${run} with \`--session ${session}\`${joiner}`;
+        return joiner ? `${run} with ` : run;
+    };
+    let text = next
+        .replace(/`confirm_irreversible: true`/g, '`--confirm-irreversible`')
+        .replace(/`values\.\w+`(?:, `values\.\w+`)*/g, (run) => {
+        const keys = [...run.matchAll(/`values\.(\w+)`/g)].map(([, key]) => `"${key}"`);
+        return `\`--values\` ${keys.length > 1 ? 'keys' : 'key'} ${keys.join(', ')}`;
+    })
+        .replace(/`(values|goal|confirm_target|max_steps|max_seconds|secret_keys)`/g, (_, name) => `\`--${name.replace(/_/g, '-')}\``)
+        .replace(/([Cc])all again with this session(, | and )?/g, (_, call, joiner) => again(call, joiner));
+    text = session
+        ? text.replace('end the session when', `end it with \`jevway end ${session}\` when`)
+        : text.replace('; end the session when you no longer need its tab', '');
+    return !session && /un again/.test(text) ? `${text} Pass \`--session new\` to keep the tab between calls.` : text;
+};
+// A one-shot run closes its browser, so "pass it in the Chrome window" can't work any more: offer a session instead.
+const askAgainWithSession = (wall) => ({
+    question: `The ${wall.kind === 'sign_in' ? 'sign-in' : `${(wall.name && BOT_CHECK_NAMES[wall.name]) ?? 'bot'} check`} on ${wall.origin} stopped this run, and a one-shot run closes its browser. Run it again with a session, so jevway keeps the tab and waits for you to ${wall.kind === 'sign_in' ? 'sign in' : 'pass it'}?`,
+    header: wall.kind === 'sign_in' ? 'Sign in' : 'Bot check',
+    options: [
+        { label: 'Run again', description: 'Keep the tab open and wait for me' },
+        { label: 'Skip', description: 'Leave it; stop here' },
+    ],
+    then: 'On Run again, repeat the command with `--session new` and a visible `--browser` (auto or launch): jevway waits up to 120 s for the person; on Skip, tell the user the step was not done.',
+});
+/**
+ * A presented result in the CLI's words: `next` and the `ask_user` question's `then` name flags, and a one-shot run
+ * stopped at a wall a person could pass asks to run again with a session.
+ */
+export const inCliWords = (result, session) => {
+    const oneShotWall = !session && result.ask_user && result.wall && result.wall.person_can_act !== false;
+    const ask = oneShotWall ? askAgainWithSession(result.wall) : result.ask_user && { ...result.ask_user, then: cliNext(result.ask_user.then, session) };
+    return { ...result, next: cliNext(result.next, session), ...(ask && { ask_user: ask }) };
+};
+// Today's `--record <dir>` keeps working: a value after --record is the folder.
+const withRecordDir = (argv) => argv.flatMap((arg, i) => (arg === '--record' && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-') ? ['--record-dir'] : [arg]));
+const TOTP_HINT = 'Pass the base32 secret behind the QR code or its otpauth://totp/ URI by key, e.g. --totp \'{"otp":"JBSWY3DPEHPK3PXP"}\'';
+/** `--totp` as JSON, each secret checked here so a bad one is a usage error (exit 2) that never repeats it. */
+const totpFlag = (raw) => {
+    let totp;
+    try {
+        totp = jsonFlag('totp', raw, TEXT_BY_KEY, '{"otp":"JBSWY3DPEHPK3PXP"}');
+    }
+    catch {
+        // A JSON parse error quotes the input, and the input is the secret.
+        throw usageError('invalid_value', '--totp must be a JSON object of key to secret', TOTP_HINT);
+    }
+    try {
+        checkTotpSecrets(totp);
+    }
+    catch (error) {
+        throw usageError('invalid_value', `--totp: ${error.message}`, TOTP_HINT);
+    }
+    return totp;
+};
+const defined = (value) => Object.fromEntries(Object.entries(value).filter(([, inner]) => inner !== undefined));
+/** `jevway run`: one goal, in-process without `--session`, through the daemon with it. */
+export const runCommand = async (argv, deps) => {
+    const { flags } = parseFlags(runSpec, withRecordDir(argv), { positionals: 0 });
+    if (flags.help) {
+        await deps.io.out(renderHelp(runSpec));
+        return 0;
+    }
+    const text = (name) => (typeof flags[name] === 'string' ? flags[name] : undefined);
+    const yes = (name) => (flags[name] === true ? true : undefined);
+    const goal = text('goal');
+    if (!goal)
+        throw usageError('missing_flag', 'jevway run needs --goal', 'Example: jevway run --url https://example.com --goal "Open the pricing page"');
+    const session = text('session');
+    const starting = !session || session === 'new';
+    if (starting && !text('url') && !text('tab')) {
+        throw usageError('missing_flag', 'jevway run needs --url or --tab (or --session to continue)', 'Example: jevway run --url https://example.com --goal "Open the pricing page"');
+    }
+    const detail = choiceFlag('detail', text('detail'), ['concise', 'full']) ?? 'concise';
+    const recordDir = text('record-dir');
+    const request = defined({
+        goal,
+        url: text('url'),
+        tab: text('tab'),
+        values: jsonFlag('values', text('values'), TEXT_BY_KEY, '{"city":"Lisbon"}'),
+        secretKeys: listFlag(text('secret-keys')),
+        files: jsonFlag('files', text('files'), TEXT_BY_KEY, '{"avatar":"/Users/ada/me.png"}'),
+        totp: totpFlag(text('totp')),
+        doneWhen: text('done-when'),
+        checks: jsonFlag('checks', text('checks'), CHECKS, '[{"type":"url_contains","text":"/issues/"}]'),
+        maxSteps: intFlag('max-steps', text('max-steps'), { min: 1, max: 100 }),
+        maxSeconds: intFlag('max-seconds', text('max-seconds'), { min: 1, max: 3600 }),
+        waitForPersonSeconds: intFlag('wait-for-person', text('wait-for-person'), { min: 0, max: 3600 }),
+        allowedHosts: listFlag(text('allowed-hosts')),
+        blockedHosts: listFlag(text('blocked-hosts')),
+        confirmIrreversible: yes('confirm-irreversible'),
+        confirmTarget: text('confirm-target'),
+        allowCoordinateClicks: yes('allow-coordinate-clicks'),
+        record: yes('record'),
+        recordDir: recordDir && resolve(deps.cwd, recordDir),
+    });
+    const choice = runnerChoice(flags, deps.env);
+    if (!session)
+        return runHere(deps, request, { choice, detail, keepOpen: Boolean(yes('keep-open')) });
+    if (starting)
+        requireKey(runnerFor(deps, choice));
+    const connection = await daemonFor(deps, starting ? { start: true } : { session, kind: 'session' });
+    const printEvent = eventPrinter(deps.io);
+    let id = starting ? undefined : session;
+    const cancel = new AbortController();
+    const stopListening = deps.onInterrupt(() => cancel.abort());
+    try {
+        const result = await callDaemon(connection, 'task', { request: { ...request, ...(id && { session: id }) }, detail, runner: choice, place: placement(deps) }, {
+            writes: true,
+            session: () => id,
+            log: deps.daemon.log,
+            signal: cancel.signal,
+            timeoutMs: TIMEOUTS.task(request.maxSeconds, !starting),
+            onEvent: (event) => {
+                if (event?.type === 'started')
+                    id = event.session;
+                printEvent(event);
+            },
+        });
+        await printDoc(deps.io, { ok: true, ...inCliWords(result, result.session) });
+        return result.status === 'done' ? 0 : 1;
+    }
+    finally {
+        stopListening();
+    }
+};
+/** A one-shot run in this process, as before the daemon: its own browser connection, its tabs closed at the end. */
+const runHere = async (deps, request, { choice, detail, keepOpen }) => {
+    const runner = runnerFor(deps, choice);
+    requireKey(runner);
+    const sessions = createSessionService(runner, { env: deps.env, cwd: deps.cwd });
+    // Ctrl-C stops the run at its next check (an action under way finishes), so the result still prints and the tab closes.
+    const cancel = new AbortController();
+    const stopListening = deps.onInterrupt(() => cancel.abort());
+    try {
+        const result = await sessions.task(request, { signal: cancel.signal, onEvent: eventPrinter(deps.io) });
+        if (!keepOpen)
+            await sessions.end(result.session).catch(() => undefined);
+        // Nothing is left to continue, so the result names no session.
+        const { session: _session, ...presented } = presentSummary(result, { detail });
+        await printDoc(deps.io, { ok: true, ...inCliWords(presented, undefined) });
+        return presented.status === 'done' ? 0 : 1;
+    }
+    finally {
+        stopListening();
+        await sessions.close().catch(() => undefined);
+    }
+};

package/dist/cli/session-commands.js

@@ -0,0 +1,132 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DaemonRunning, startDaemon } from '../daemon/server.js';
+import { envFingerprint } from '../daemon/paths.js';
+import { callDaemon, daemonFor, TIMEOUTS } from './daemon-call.js';
+import { CliError, durationFlag, parseFlags, usageError } from './flags.js';
+import { renderHelp } from './help.js';
+import { printDoc } from './output.js';
+export const sessionsSpec = {
+    name: 'sessions',
+    summary: 'list the daemon\'s open sessions and journeys',
+    examples: ['jevway sessions'],
+    flags: {},
+    notes: ['Prints { ok: true, daemon: { pid, version, socket, log, idle_timeout_s } | null, sessions: [{ session, kind, goal, status, url, running, run_dir, … }] }. Never starts the daemon.'],
+};
+export const endSpec = {
+    name: 'end',
+    argument: '<id>',
+    summary: 'end a session (or finish a journey) and close the tabs it opened',
+    examples: ['jevway end <id>', 'jevway end <id> --keep-tab'],
+    flags: {
+        session: { type: 'string', value: '<id>', describe: 'the session (or pass it as the argument)' },
+        'keep-tab': { type: 'boolean', describe: 'leave its tabs open' },
+    },
+    notes: ['Prints { ok: true, session, run_dir }. A session the daemon does not hold is unknown_session, exit 1.'],
+};
+export const serveSpec = {
+    name: 'serve',
+    summary: 'run the session daemon in the foreground (other commands start it in the background when needed)',
+    examples: ['jevway serve', 'jevway serve --idle-timeout 0'],
+    flags: { 'idle-timeout': { type: 'string', value: '<duration>', describe: 'end sessions idle this long, then exit: seconds, or 90s, 30m, 2h; 0 never (default 1h)' } },
+    notes: [
+        'Prints { ok: true, socket, pid, version, idle_timeout_s } once it listens, then NDJSON log lines on stderr until it stops.',
+        'Socket and log: $JEVWAY_STATE_DIR, else $XDG_RUNTIME_DIR/jevway, else ~/.cache/jevway (daemon.sock, daemon.log).',
+        'It keeps the environment it started with; after changing keys, jevway stop and the next command starts a fresh one.',
+    ],
+};
+export const stopSpec = {
+    name: 'stop',
+    summary: 'stop the daemon: end every session, close the tabs they opened and any browser it launched',
+    examples: ['jevway stop'],
+    flags: {},
+    notes: ['Prints { ok: true, stopped: true, ended: <sessions> }, or { ok: true, stopped: false } when none was running.'],
+};
+const helped = async (spec, argv, deps, positionals = 0) => {
+    const parsed = parseFlags(spec, argv, { positionals });
+    if (!parsed.flags.help)
+        return parsed;
+    await deps.io.out(renderHelp(spec));
+    return undefined;
+};
+const daemonInfo = (hello, deps) => ({
+    pid: hello.pid,
+    version: hello.version,
+    socket: deps.daemon.socket,
+    log: deps.daemon.log,
+    idle_timeout_s: hello.idle_timeout_s,
+    started_at: hello.started_at,
+});
+/** `jevway sessions`: what the running daemon holds; no daemon is an empty list. */
+export const sessionsCommand = async (argv, deps) => {
+    if (!(await helped(sessionsSpec, argv, deps)))
+        return 0;
+    const connection = await deps.daemon.find();
+    if (!connection) {
+        await printDoc(deps.io, { ok: true, daemon: null, sessions: [] });
+        return 0;
+    }
+    const { daemon, sessions } = await callDaemon(connection, 'sessions', {}, { writes: false, log: deps.daemon.log, timeoutMs: TIMEOUTS.quick });
+    await printDoc(deps.io, { ok: true, daemon: daemonInfo(daemon, deps), sessions });
+    return 0;
+};
+/** `jevway end <id>`: ends a session or finishes a journey. */
+export const endCommand = async (argv, deps) => {
+    const parsed = await helped(endSpec, argv, deps, 1);
+    if (!parsed)
+        return 0;
+    const session = parsed.positionals[0] ?? parsed.flags.session;
+    if (!session)
+        throw usageError('missing_flag', 'jevway end needs the session id', 'Example: jevway end <id> (jevway sessions lists them)');
+    const connection = await daemonFor(deps, { session, kind: 'session' });
+    const ended = await callDaemon(connection, 'end', { session, keepTab: parsed.flags['keep-tab'] === true }, { writes: true, session: () => session, log: deps.daemon.log, timeoutMs: TIMEOUTS.quick });
+    await printDoc(deps.io, { ok: true, ...ended });
+    return 0;
+};
+/** `jevway stop`: stops the running daemon, if any. */
+export const stopCommand = async (argv, deps) => {
+    if (!(await helped(stopSpec, argv, deps)))
+        return 0;
+    const connection = await deps.daemon.find();
+    if (!connection) {
+        await printDoc(deps.io, { ok: true, stopped: false });
+        return 0;
+    }
+    const result = await callDaemon(connection, 'stop', {}, { writes: false, log: deps.daemon.log, timeoutMs: TIMEOUTS.quick });
+    await Promise.race([connection.closed, new Promise((resolve) => setTimeout(resolve, 2_000).unref())]);
+    await printDoc(deps.io, { ok: true, ...result });
+    return 0;
+};
+/** `jevway serve`: the daemon in the foreground, until `jevway stop`, Ctrl-C or the idle timeout. */
+export const serveCommand = async (argv, deps) => {
+    const parsed = await helped(serveSpec, argv, deps);
+    if (!parsed)
+        return 0;
+    const raw = parsed.flags['idle-timeout'];
+    const idleMs = typeof raw === 'string' ? durationFlag('idle-timeout', raw) : 3_600_000;
+    const { socket } = deps.daemon;
+    if (process.platform !== 'win32')
+        mkdirSync(dirname(socket), { recursive: true, mode: 0o700 });
+    let daemon;
+    try {
+        daemon = await startDaemon({
+            socket,
+            version: deps.version,
+            fingerprint: envFingerprint(deps.env),
+            idleMs,
+            runnerFor: ({ browser, ...choice }) => deps.createRunner(browser, choice),
+            log: (entry) => deps.io.err(`${JSON.stringify({ time: new Date().toISOString(), ...entry })}\n`),
+        });
+    }
+    catch (error) {
+        if (error instanceof DaemonRunning)
+            throw new CliError(1, error.code, error.message, 'jevway sessions shows it; jevway stop stops it');
+        throw error;
+    }
+    const stopListening = deps.onInterrupt(() => void daemon.stop());
+    // One line, so a background daemon's log stays one JSON object per line.
+    await deps.io.out(`${JSON.stringify({ ok: true, socket, pid: process.pid, version: deps.version, idle_timeout_s: idleMs ? idleMs / 1000 : null })}\n`);
+    await daemon.closed;
+    stopListening();
+    return 0;
+};