@agentwhy/cli 0.0.0-dev

package/dist/cli/commands/report-arguments.js

@@ -0,0 +1,62 @@
+import { parseArgs } from 'node:util';
+import { widthFor } from './report-usage.js';
+/**
+ * Parses the arguments after `report`. Never throws: bad input is a usage error. `columns` is what the terminal
+ * reported, and is used only when `--width` says nothing.
+ */
+export function parseReportArguments(args, columns) {
+    let values;
+    try {
+        values = parseValues(args);
+    }
+    catch (error) {
+        return usageError(error instanceof Error ? error.message : String(error));
+    }
+    if (values.help)
+        return { kind: 'help' };
+    const width = values.width === undefined ? widthFor(columns) : Number(values.width);
+    if (!Number.isInteger(width) || width < 40)
+        return usageError('--width must be a whole number of at least 40');
+    // `--input` is optional: without it the command reads the newest session of the current project, which is
+    // what someone standing in their repository means by "report".
+    return {
+        kind: 'options',
+        options: {
+            ...(values.input === undefined || values.input === '' ? {} : { input: values.input }),
+            ...(values.policy === undefined ? {} : { policyPath: values.policy }),
+            ...(values.settings === undefined ? {} : { settingsPath: values.settings }),
+            ...(values.html === undefined ? {} : { htmlPath: values.html }),
+            ascii: values.ascii === true,
+            full: values.full === true,
+            colour: values['no-color'] !== true,
+            open: values.open === true,
+            ...(values.quiet === true ? { quiet: true } : {}),
+            share: values.share === true,
+            width,
+        },
+    };
+}
+function parseValues(args) {
+    return parseArgs({
+        args: [...args],
+        options: {
+            input: { type: 'string' },
+            policy: { type: 'string' },
+            settings: { type: 'string' },
+            html: { type: 'string' },
+            ascii: { type: 'boolean', default: false },
+            full: { type: 'boolean', default: false },
+            'no-color': { type: 'boolean', default: false },
+            open: { type: 'boolean', default: false },
+            quiet: { type: 'boolean', default: false },
+            share: { type: 'boolean', default: false },
+            width: { type: 'string' },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+        strict: true,
+        allowPositionals: false,
+    }).values;
+}
+function usageError(message) {
+    return { kind: 'usage-error', message };
+}

package/dist/cli/commands/report-cli-command.js

@@ -0,0 +1,36 @@
+import { EXIT_CODE } from '../exit-codes.js';
+import { parseReportArguments } from './report-arguments.js';
+import { REPORT_USAGE } from './report-usage.js';
+// A Record over the outcome union: a new outcome does not compile until it has an exit code. An incomplete
+// report still exits 0 - it said what was missing, which is the report doing its job.
+export const EXIT_CODE_BY_OUTCOME = {
+    complete: EXIT_CODE.ok,
+    incomplete: EXIT_CODE.ok,
+    'policy-refused': EXIT_CODE.usage,
+    'session-unreadable': EXIT_CODE.mainTranscriptMissing,
+    'no-session': EXIT_CODE.mainTranscriptMissing,
+};
+export class ReportCliCommand {
+    name = 'report';
+    usage = REPORT_USAGE;
+    #report;
+    /** The terminal's width, read once in the shell. `undefined` where there is no terminal to read. */
+    #columns;
+    constructor(report, columns) {
+        this.#report = report;
+        this.#columns = columns;
+    }
+    async execute(args) {
+        const parsed = parseReportArguments(args, this.#columns);
+        switch (parsed.kind) {
+            case 'help':
+                return { kind: 'help', usage: this.usage };
+            case 'usage-error':
+                return { kind: 'usage-error', message: parsed.message, usage: this.usage };
+            case 'options': {
+                const result = await this.#report.run(parsed.options);
+                return { kind: 'completed', output: result.output, exitCode: EXIT_CODE_BY_OUTCOME[result.outcome] };
+            }
+        }
+    }
+}

package/dist/cli/commands/report-usage.js

@@ -0,0 +1,41 @@
+export const DEFAULT_WIDTH = 100;
+/** Narrower than this the layout stops being a layout; wider, a line is too long to run an eye back along. */
+const WIDTH_BOUNDS = { least: 60, most: 120 };
+/**
+ * The width a report is drawn at when `--width` is not given: the terminal's, kept inside bounds. With no terminal
+ * - piped, redirected, in CI - it is `DEFAULT_WIDTH`, so a script's output does not change with the window.
+ */
+export function widthFor(columns) {
+    if (columns === undefined || !Number.isFinite(columns))
+        return DEFAULT_WIDTH;
+    return Math.min(Math.max(Math.trunc(columns), WIDTH_BOUNDS.least), WIDTH_BOUNDS.most);
+}
+export const REPORT_USAGE = `Usage: agentwhy report --input <session-dir | session.jsonl> [options]
+
+  --input <path>      the session to read: a directory or its <session-id>.jsonl
+  --policy <file>     the policy that says which paths are protected
+  --settings <file>   a settings file whose deny rules stand in for a policy
+  --html <file>       also write the report as one self-contained HTML file
+  --open              open the HTML report in whatever this machine opens HTML with.
+                      Without --html it is written to a temporary file first
+  --quiet             say where the report is and nothing else. The summary names paths and
+                      what became of each, which is not what an agent should be handed when it
+                      opens a report because you said yes
+  --share             a report fit to hand to someone else: paths are shown relative to the
+                      project root and nothing above it appears. This reduces exposure; it does
+                      not anonymise - a path inside the repository still names what the
+                      repository names
+  --full              every section in detail: for each file, who reached it, what they had
+                      been asked to do, what they ran and which record says so. Without it
+                      the terminal gets a summary, and its last line says how to see the rest
+  --ascii             draw the tree with + - | instead of box-drawing characters
+  --no-color          no colour, even at a terminal. It is also off under NO_COLOR, with
+                      --ascii, and whenever the output is not a terminal
+  --width <columns>   width of the output. At a terminal it follows the window, between
+                      ${WIDTH_BOUNDS.least} and ${WIDTH_BOUNDS.most} columns; piped or redirected it is ${DEFAULT_WIDTH}
+  -h, --help          this text
+
+Without --policy or --settings the built-in default is used, and the report says so.
+The summary is printed either way; --html adds a file, it does not replace the output.
+Values never appear in the output: they are replaced on the way into the report, not on the way out.
+`;

package/dist/cli/commands/sessions-cli-command.js

@@ -0,0 +1,184 @@
+import { parseArgs } from 'node:util';
+import { parseSince, splitBySince } from '../../core/session-filter.js';
+import { sessionKey } from '../../core/session-catalogue.js';
+import { PROVIDER_NAMES } from '../../core/session-format.js';
+import { recogniseAll } from '../../core/session-titles.js';
+import { table } from '../../shared/text-table.js';
+import { EXIT_CODE } from '../exit-codes.js';
+import { EXIT_CODE_BY_OUTCOME } from './report-cli-command.js';
+export const SESSIONS_USAGE = `Usage: agentwhy sessions [--since <span | date>] [--no-interactive]
+
+Lists the sessions Claude Code has kept for the current directory's project, newest first,
+so that reporting on one does not require typing the path it is stored under.
+
+At a terminal, with no --since, it first asks how far back to look - there can be a lot of
+sessions - then the list can be chosen from: typing narrows it by title, date or id, the arrow
+keys move, Enter opens a report on that session, Escape leaves. A title is the one Claude Code
+gave the session, passed through the redactor. Piped or redirected it prints the table and
+exits, unchanged, so that a script sees the same output either way.
+
+  --since <span|date> only sessions last active since then: 7d, 12h, 2w, or 2026-09-01 (UTC).
+                      Off a terminal, without it, every session is listed
+  --no-interactive    asks for the table at a terminal too, every session, unfiltered
+  -h, --help          this text
+`;
+const QUICK_RANGES = [
+    { label: 'Today', span: '1d' },
+    { label: 'Last 7 days', span: '7d' },
+    { label: 'Last 30 days', span: '30d' },
+];
+/** `agentwhy sessions` - the answer to "which session did I mean?", and a way to act on the answer. */
+export class SessionsCliCommand {
+    name = 'sessions';
+    usage = SESSIONS_USAGE;
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async execute(args) {
+        let values;
+        try {
+            ({ values } = parseArgs({
+                args: [...args],
+                options: {
+                    since: { type: 'string' },
+                    'no-interactive': { type: 'boolean', default: false },
+                    help: { type: 'boolean', short: 'h', default: false },
+                },
+                strict: true,
+                allowPositionals: false,
+            }));
+        }
+        catch (error) {
+            return { kind: 'usage-error', message: error instanceof Error ? error.message : String(error), usage: this.usage };
+        }
+        if (values.help)
+            return { kind: 'help', usage: this.usage };
+        let since;
+        if (values.since !== undefined) {
+            const parsed = parseSince(values.since, this.#dependencies.now);
+            if ('error' in parsed)
+                return { kind: 'usage-error', message: parsed.error, usage: this.usage };
+            since = parsed;
+        }
+        const { catalogue, workingDirectory } = this.#dependencies;
+        const listing = await catalogue.list(workingDirectory);
+        // "Nothing here" and "looked in the wrong place" are different answers, and the second is far more likely
+        // to be the truth when a path encoding is involved.
+        if (!listing.found) {
+            return {
+                kind: 'completed',
+                output: `No sessions are stored for this directory.\nLooked in ${listing.searched.map((place) => place.directory).join(' and ')}\n` +
+                    `agentwhy reads sessions Claude Code and Codex already keep, so either this directory has not been used with either yet, or it is not the one being worked in.\n` +
+                    `Use Claude Code or Codex here, then run agentwhy sessions again - or run agentwhy init now, to be protected in Claude Code before there is history to check.\n`,
+                exitCode: EXIT_CODE.ok,
+            };
+        }
+        if (listing.sessions.length === 0) {
+            return { kind: 'completed', output: `That project has no sessions yet.\n${listing.directory}\n`, exitCode: EXIT_CODE.ok };
+        }
+        const interactive = this.#dependencies.interactive && !values['no-interactive'];
+        // At a terminal, with no --since on the command line: asked before the list, because the list itself can be
+        // the very thing too long to read (the reason this exists at all).
+        if (interactive && since === undefined) {
+            const picked = await this.#pickRange(listing.sessions.length);
+            if (picked.kind === 'left')
+                return { kind: 'completed', output: '', exitCode: EXIT_CODE.ok };
+            if (picked.kind === 'since')
+                since = picked.since;
+            // 'all': since stays undefined, and every session is kept below.
+        }
+        const sessions = since === undefined ? listing.sessions : splitBySince(listing.sessions, since.since).inRange;
+        if (since !== undefined && sessions.length === 0) {
+            return { kind: 'completed', output: `No sessions of this project were active since ${since.asked}.\n`, exitCode: EXIT_CODE.ok };
+        }
+        return interactive ? this.#choose(sessions, since) : { kind: 'completed', output: render(sessions, since), exitCode: EXIT_CODE.ok };
+    }
+    /** R: how far back to look, asked before the list itself, because the list can be the thing too long to read. */
+    async #pickRange(total) {
+        const { chooser, asker, now } = this.#dependencies;
+        const rows = [
+            ...QUICK_RANGES.map(({ label, span }) => ({ label, detail: `--since ${span}` })),
+            { label: 'All sessions', detail: `${count(total)}, unfiltered` },
+            { label: 'Type a date or span', detail: 'e.g. 2026-09-01, or 12h' },
+        ];
+        const at = await chooser.choose('How far back? There can be a lot of sessions.', rows);
+        if (at === undefined)
+            return { kind: 'left' };
+        if (at === QUICK_RANGES.length)
+            return { kind: 'all' };
+        if (at < QUICK_RANGES.length) {
+            const range = QUICK_RANGES[at];
+            if (range === undefined)
+                return { kind: 'left' };
+            const parsed = parseSince(range.span, now);
+            return 'error' in parsed ? { kind: 'left' } : { kind: 'since', since: parsed };
+        }
+        for (let question = 'Since when? 7d, 12h, 2w, or a date such as 2026-09-01';;) {
+            const typed = await asker.ask(question, '7d');
+            if (typed === undefined || typed === '')
+                return { kind: 'left' };
+            const parsed = parseSince(typed, now);
+            if (!('error' in parsed))
+                return { kind: 'since', since: parsed };
+            question = `${parsed.error}. Try again, or leave it blank to go back`;
+        }
+    }
+    /** The list, chosen from. Leaving without choosing is an ordinary way to finish, not a failure. */
+    async #choose(sessions, since) {
+        const { chooser, report, titles, width } = this.#dependencies;
+        const titled = (await recogniseAll(titles, sessions)).map((recognised) => recognised.title);
+        const heading = `${count(sessions.length)}${rangeWords(since)}, newest first. Type to narrow the list.`;
+        const at = await chooser.choose(heading, sessions.map((session, position) => toChoice(session, titled[position])));
+        const chosen = at === undefined ? undefined : sessions[at];
+        if (chosen === undefined)
+            return { kind: 'completed', output: '', exitCode: EXIT_CODE.ok };
+        const result = await report.run({
+            input: chosen.path,
+            ascii: false,
+            full: false,
+            // Printed at the terminal the list was chosen at; the shell still decides whether it may be coloured.
+            colour: true,
+            open: true,
+            share: false,
+            width,
+        });
+        return { kind: 'completed', output: result.output, exitCode: EXIT_CODE_BY_OUTCOME[result.outcome] };
+    }
+}
+function count(sessions) {
+    return `${sessions} ${sessions === 1 ? 'session' : 'sessions'}`;
+}
+function rangeWords(since) {
+    return since === undefined ? '' : ` active since ${since.asked}`;
+}
+function when(session) {
+    return new Date(session.modifiedAt).toISOString().slice(0, 16).replace('T', ' ');
+}
+function delegations(session) {
+    return session.delegations === 0 ? 'no delegations' : `${session.delegations} delegations`;
+}
+/**
+ * The title when there is one, and the key either way: two sessions can carry the same title. Every row names the AI
+ * that wrote it (`2026-09-27-what-codex-wrote.md` X28).
+ */
+function toChoice(session, title) {
+    const ai = PROVIDER_NAMES[session.provider];
+    if (title === undefined)
+        return { label: `untitled · ${sessionKey(session)}`, detail: `${ai} · ${when(session)} · ${delegations(session)}` };
+    return { label: title, detail: `${ai} · ${when(session)} · ${delegations(session)} · ${session.id.slice(0, 8)}` };
+}
+function render(sessions, since) {
+    const rows = sessions.map((session, index) => [
+        `${index === 0 ? '*' : ' '} ${sessionKey(session)}`,
+        `${when(session)}  ${PROVIDER_NAMES[session.provider]}  ${delegations(session)}`,
+    ]);
+    return [
+        `${count(sessions.length)}${rangeWords(since)}, newest first. \`agentwhy report\` reads the one marked *.`,
+        '',
+        ...table(rows, 2),
+        '',
+        'To read another: agentwhy report --input <the id above>',
+        '',
+    ].join('\n');
+}

package/dist/cli/commands/start-cli-command.js

@@ -0,0 +1,83 @@
+import { parseArgs } from 'node:util';
+import { parseSince } from '../../core/session-filter.js';
+import { EXIT_CODE } from '../exit-codes.js';
+export const START_USAGE = `Usage: agentwhy start [--since <span | date>] [--out <dir>] [--policy <file> | --settings <file>]
+                     [--no-open] [--serve | --no-serve] [--share]
+
+Lists every session of the current directory's project on one page, writes a report for each
+session active inside the range, and opens the page. The page it opens is served from 127.0.0.1,
+at an address holding a random token, so a file marked done on it is recorded at once; it stops
+after 30 minutes with no request, or with Ctrl+C. The reports are files either way.
+
+  --since <span|date> sessions last active since then: 7d, 12h, 2w, or 2026-09-01 (UTC). Default 7d
+  --out <dir>         where to write; default a new directory in the system temporary location.
+                      Refused inside a repository
+  --policy <file>     the policy every report reads, as for \`report\`
+  --settings <file>   a settings file whose deny rules stand in for a policy, as for \`report\`.
+                      Without either, every report uses the built-in default and says so
+  --no-open           write the files and print where, without opening anything
+  --serve             serve the page even with --no-open, and print its address
+  --no-serve          open the page as a file and return; marks on it are copied as commands
+  --share             no session ids, no project path, nothing above the project root. This
+                      reduces exposure; it does not anonymise
+  -h, --help          this text
+`;
+// A Record over the outcome union: a new outcome does not compile until it has an exit code.
+const EXIT_CODE_BY_OUTCOME = {
+    written: EXIT_CODE.ok,
+    // No sessions is an answer about this directory, the same one `sessions` gives with exit 0.
+    'no-sessions': EXIT_CODE.ok,
+    refused: EXIT_CODE.usage,
+    unwritable: EXIT_CODE.usage,
+};
+/** `agentwhy start` - a page to begin from, for someone who has a date and not a session id. */
+export class StartCliCommand {
+    name = 'start';
+    usage = START_USAGE;
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async execute(args) {
+        let values;
+        try {
+            ({ values } = parseArgs({
+                args: [...args],
+                options: {
+                    since: { type: 'string', default: '7d' },
+                    out: { type: 'string' },
+                    policy: { type: 'string' },
+                    settings: { type: 'string' },
+                    'no-open': { type: 'boolean', default: false },
+                    serve: { type: 'boolean' },
+                    'no-serve': { type: 'boolean', default: false },
+                    share: { type: 'boolean', default: false },
+                    help: { type: 'boolean', short: 'h', default: false },
+                },
+                strict: true,
+                allowPositionals: false,
+            }));
+        }
+        catch (error) {
+            return { kind: 'usage-error', message: error instanceof Error ? error.message : String(error), usage: this.usage };
+        }
+        if (values.help)
+            return { kind: 'help', usage: this.usage };
+        if (values.serve === true && values['no-serve']) {
+            return { kind: 'usage-error', message: '--serve and --no-serve cannot be given together', usage: this.usage };
+        }
+        const since = parseSince(values.since, this.#dependencies.now);
+        if ('error' in since)
+            return { kind: 'usage-error', message: since.error, usage: this.usage };
+        const result = await this.#dependencies.start.run({
+            since,
+            ...(values.out === undefined || values.out === '' ? {} : { out: values.out }),
+            ...(values.policy === undefined ? {} : { policyPath: values.policy }),
+            ...(values.settings === undefined ? {} : { settingsPath: values.settings }),
+            open: !values['no-open'],
+            share: values.share,
+            ...(values['no-serve'] ? { serve: false } : values.serve === true ? { serve: true } : {}),
+        });
+        return { kind: 'completed', output: result.output, exitCode: EXIT_CODE_BY_OUTCOME[result.outcome] };
+    }
+}

package/dist/cli/commands/watch-cli-command.js

@@ -0,0 +1,142 @@
+import { parseArgs } from 'node:util';
+import { ALERT_THRESHOLDS } from '../../report/watch/agent-alert.js';
+import { SAID_AS } from '../../report/watch/notice-choices.js';
+import { CLEAN_MODES, DEFAULT_CHANNELS, DEFAULT_CLEAN, NOTICE_CHANNELS, } from '../../report/watch/subagent-watch.js';
+import { EXIT_CODE } from '../exit-codes.js';
+export const WATCH_USAGE = `Usage: agentwhy watch [--policy <file> | --settings <file>]
+                     [--on value | reached | refused]
+                     [--clean off | once | every-turn] [--say agent | line]
+                     [--notify chat,terminal,os]
+
+Run by Claude Code hooks, never by hand: reads the hook input on standard input and works out which
+event it was. On SubagentStop it checks the agent that just finished and keeps what it found; on Stop
+it says, in the conversation, what that turn's agents did. It speaks when an agent wrote a value from
+a protected file into its own messages, and otherwise says nothing - unless --on asks for less.
+The notice names no path and no value, and reaches no model; agentwhy report --open shows the rest.
+It always exits 0: a SubagentStop hook that exits 2 hands its error to the agent as an instruction,
+and a Stop hook that exits 2 keeps the turn from ending.
+
+  --policy <file>     the policy to read the session under, as for \`report\`
+  --settings <file>   a settings file whose deny rules stand in for a policy, as for \`report\`
+  --on <level>        value (default): only a value written from a protected file.
+                      reached: also an agent that reached a protected file.
+                      refused: also an attempt a rule refused, where nothing was reached -
+                      the one notice that asks for nothing and says a rule held
+  --clean <when>      when a turn that found nothing says so, in the conversation
+                      once (default): the first quiet turn says the session is being watched.
+                      off: nothing is ever said about a quiet turn, as before.
+                      every-turn: after every reply. A quiet turn of a session that was
+                      not quiet says both, so a clean turn never reads as a clean session
+  --say <how>         how a value in the conversation is said
+                      agent (default): the turn is kept open and your own agent says it,
+                      in its words and your language, and offers to open the report. The
+                      line is said beside it. Only where a person is reading: not in claude -p
+                      line: the grey line under the reply, and nothing else
+  --notify <channels> where the notice is shown, comma-separated. Default chat
+                      chat: a line in the conversation, at the end of the turn, in any interface
+                      terminal: a notification the terminal interface of Claude Code shows
+                      os: a macOS notification, shown whatever interface is in use
+  -h, --help          this text
+
+To use it, run agentwhy init in the project, which asks before it writes. Or add this to
+.claude/settings.local.json yourself - watch itself installs nothing:
+
+  "hooks": {
+    "SubagentStop": [
+      { "hooks": [ { "type": "command",
+          "command": "agentwhy watch --settings \\"$CLAUDE_PROJECT_DIR/.claude/settings.json\\"" } ] }
+    ],
+    "Stop": [
+      { "hooks": [ { "type": "command",
+          "command": "agentwhy watch --settings \\"$CLAUDE_PROJECT_DIR/.claude/settings.json\\"" } ] }
+    ]
+  }
+
+The same command line in both: it reads the event it was given. Without the Stop hook nothing is said
+in the conversation, and the notice waits for a channel that shows it.
+
+A hook can fail to run at all. agentwhy start still reads every session, and stays the backstop.
+`;
+/** `agentwhy watch` - the hook end of `specs/2026-09-16-when-an-agent-finishes.md`. */
+export class WatchCliCommand {
+    name = 'watch';
+    usage = WATCH_USAGE;
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async execute(args) {
+        let values;
+        try {
+            ({ values } = parseArgs({
+                args: [...args],
+                options: {
+                    policy: { type: 'string' },
+                    settings: { type: 'string' },
+                    on: { type: 'string' },
+                    clean: { type: 'string' },
+                    say: { type: 'string' },
+                    notify: { type: 'string' },
+                    help: { type: 'boolean', short: 'h', default: false },
+                },
+                strict: true,
+                allowPositionals: false,
+            }));
+        }
+        catch {
+            // The channels are still read where they can be: a hook with one wrong flag was still told where to speak.
+            const asked = channelsIn(looseNotify(args));
+            return this.#notChecked(asked === 'unknown' ? DEFAULT_CHANNELS : asked);
+        }
+        if (values.help)
+            return { kind: 'help', usage: this.usage };
+        // The only usage error this command returns: at a terminal no hook is listening, so exit 2 instructs nobody (R13).
+        if (this.#dependencies.interactive) {
+            return { kind: 'usage-error', message: 'watch reads a hook input on standard input, and this is a terminal', usage: this.usage };
+        }
+        /*
+         * A flag that was not written is not a choice: it is left to what the person set, and the use case settles it
+         * (`the-agent-tells-you.md` R24). A flag that was written and is not a value this version knows is still an
+         * error - a hook asking for `--on everything` is a hook whose person believes they are being told more.
+         */
+        const on = read(values.on, ALERT_THRESHOLDS);
+        const clean = read(values.clean, CLEAN_MODES);
+        const say = read(values.say, SAID_AS);
+        const channels = values.notify === undefined ? undefined : channelsIn(values.notify);
+        if (on === 'unknown' || clean === 'unknown' || say === 'unknown' || channels === 'unknown') {
+            return this.#notChecked(channels === undefined || channels === 'unknown' ? DEFAULT_CHANNELS : channels);
+        }
+        const result = await this.#dependencies.watch.run({
+            ...(on === undefined ? {} : { on }),
+            ...(clean === undefined ? {} : { clean }),
+            ...(say === undefined ? {} : { say }),
+            ...(channels === undefined ? {} : { channels }),
+            ...(values.policy === undefined ? {} : { policyPath: values.policy }),
+            ...(values.settings === undefined ? {} : { settingsPath: values.settings }),
+        });
+        // R8: every outcome is exit 0. What could not be checked is said in the output, never in the exit code.
+        return { kind: 'completed', output: result.output, exitCode: EXIT_CODE.ok };
+    }
+    /** Arguments a hook was configured with and this version cannot use: said to the user, exit 0 (R8). */
+    async #notChecked(channels) {
+        const result = await this.#dependencies.watch.announce({ kind: 'not-checked', reason: 'arguments' }, channels);
+        return { kind: 'completed', output: result.output, exitCode: EXIT_CODE.ok };
+    }
+}
+/** One flag, as written: what it names, nothing where it was not written, and `unknown` where it names nothing. */
+function read(value, known) {
+    if (value === undefined)
+        return undefined;
+    return known.find((candidate) => candidate === value) ?? 'unknown';
+}
+/** `--notify` as given, read without refusing anything else in the arguments. */
+function looseNotify(args) {
+    const { values } = parseArgs({ args: [...args], options: { notify: { type: 'string' } }, strict: false, allowPositionals: true });
+    return typeof values.notify === 'string' ? values.notify : undefined;
+}
+/** The channels named, or `unknown` when one is not a channel or none is named. */
+function channelsIn(list) {
+    const names = (list ?? '').split(',').map((name) => name.trim()).filter((name) => name !== '');
+    const channels = names.map((name) => NOTICE_CHANNELS.find((channel) => channel === name));
+    return channels.length === 0 || channels.includes(undefined) ? 'unknown' : [...new Set(channels)];
+}

package/dist/cli/exit-codes.js

@@ -0,0 +1,13 @@
+// Documented in each command's usage text; tests/cli/commands/doctor-usage.test.ts pins the doctor usage to it.
+export const EXIT_CODE = {
+    ok: 0,
+    mainTranscriptMissing: 1,
+    usage: 2,
+    unexpected: 3,
+};
+/**
+ * What a `PreToolUse` hook exits with to block the call; the hooks reference documents that its stderr then reaches the
+ * model as the reason (`specs/2026-09-16-worth-running-every-day.md` R19). The same number as a usage error, on purpose
+ * named apart: one is this tool's own convention, the other is Claude Code's.
+ */
+export const HOOK_BLOCK_EXIT_CODE = 2;

package/dist/cli/project-switches.js

@@ -0,0 +1,46 @@
+/**
+ * `agentwhy` in the folder it was typed in, and every project a page switches to after it, in this one process
+ * (`.ai/specs/2026-09-27-which-project.md` V14, V18). A switch starts `start` for the chosen folder with the range the page
+ * was drawn with; the page is answered with the new run's address once that run serves, and the run it came from ends.
+ * A run that ends before it serves - nothing there to show, a folder that cannot be read - answers the page with what it
+ * said, and nothing else changes. The terminal is given back when the last run shown has ended: Ctrl+C there stops it,
+ * as it stopped the first.
+ *
+ * `write` is given each run's result as it ends; the last one's is returned for the shell to write and exit with.
+ */
+export async function runSwitching(runIn, workingDirectory, argv, write) {
+    const shown = [];
+    const past = [];
+    const seams = (folder, handedOver, arrivedFrom) => ({
+        switchTo: (folder, since, from) => new Promise((resolve) => {
+            let answered = false;
+            const run = runIn(folder, ['start', '--since', since], seams(folder, (url) => {
+                answered = true;
+                shown.push(run);
+                resolve({ url });
+            }, from));
+            run.then((result) => {
+                if (!answered)
+                    resolve({ failed: reasonOf(result) });
+            }, (error) => {
+                if (!answered)
+                    resolve({ failed: error instanceof Error ? error.message : String(error) });
+            });
+        }),
+        ...(handedOver === undefined ? {} : { handedOver }),
+        ...(arrivedFrom === undefined ? {} : { arrivedFrom }),
+        served: (token) => { past.push({ token, folder }); },
+        pastRuns: () => past,
+    });
+    let result = await runIn(workingDirectory, argv, seams(workingDirectory));
+    for (let at = 0; at < shown.length; at += 1) {
+        write(result);
+        result = await shown[at];
+    }
+    return result;
+}
+/** What a run that never served said, as one line a page can show. */
+function reasonOf(result) {
+    const said = result.kind === 'completed' ? result.output : result.kind === 'hook-block' ? result.reason : result.kind === 'usage-error' ? result.message : result.usage;
+    return said.trim().split('\n')[0] || 'agentwhy could not show that project.';
+}