@agentwhy/cli 0.0.0-dev

package/dist/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { homedir, tmpdir } from 'node:os';
+import { EXIT_CODE, HOOK_BLOCK_EXIT_CODE } from './cli/exit-codes.js';
+import { runSwitching } from './cli/project-switches.js';
+import { createCommandRouter, processServer } from './composition-root.js';
+import { colourWanted } from './shared/colour.js';
+// The shell: the only module that touches `process`.
+async function main(argv) {
+    // One folder's environment: the one `agentwhy` was typed in, or one a page switched to (which-project V14), with the
+    // seams that let its run start the next.
+    const environmentAt = (workingDirectory, seams) => ({
+        workingDirectory,
+        ...seams,
+        home: homedir(),
+        platform: process.platform,
+        temporaryDirectory: tmpdir(),
+        // Who this process is, for the one store that keeps a file in the shared temporary directory and has to know
+        // whether the directory it found there is this person's. Undefined on a platform with no such notion.
+        user: process.getuid?.(),
+        // A command that behaves differently when it is being watched is not scriptable, so this is asked once,
+        // here, and every command is told rather than looking for itself.
+        interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
+        // Asked apart from `interactive`: a hook's stdout is never a terminal, but its stdin is a pipe either way.
+        inputIsTerminal: process.stdin.isTTY === true,
+        // Decided here and once, like `interactive`: a renderer that looked at a stream would colour a piped report.
+        colour: colourWanted(process.stdout.isTTY === true, process.env.NO_COLOR),
+        // Whether anyone is looking at the output. The wordmark is drawn for a person and not for a pipe, and it is
+        // asked apart from `colour`, which NO_COLOR turns off without making the terminal any less of a terminal.
+        terminal: process.stdout.isTTY === true,
+        // How wide the report may be drawn. Undefined when stdout is not a terminal: a piped report keeps one width,
+        // so what a script reads does not depend on the window someone happened to run it in.
+        columns: process.stdout.isTTY === true ? process.stdout.columns : undefined,
+        input: process.stdin,
+        output: process.stdout,
+        // Read once per run: every range and every age on a page is measured from the moment its command began - for a run
+        // a page switched to, the moment of the switch.
+        now: Date.now(),
+        // Which way into Claude Code ran this, when a hook did: `cli` and `claude-vscode` have a person reading, and
+        // `sdk-cli` is `claude -p` (`the-agent-tells-you.md` B9e2). The hook input says nothing about it; this does.
+        entryPoint: process.env.CLAUDE_CODE_ENTRYPOINT,
+        // The system's language, in the order POSIX reads it, for a line nobody chose a language for
+        // (`the-agent-tells-you.md` R29). An empty variable says nothing, so it is passed over like a missing one.
+        locale: process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || undefined,
+        // The project a hook runs for, the variable its own `--settings "$CLAUDE_PROJECT_DIR/…"` is expanded with: whose
+        // settings say how the hook runs agentwhy, and so how the agent is asked to (`the-agent-tells-you.md` R18).
+        projectDirectory: process.env.CLAUDE_PROJECT_DIR || undefined,
+        // How this agentwhy runs, which decides the command a hook written now runs (`a-hook-runs-what-you-ran.md` J2):
+        // the script as it was started, and the `PATH` a hook's shell would look it up on.
+        script: process.argv[1],
+        path: process.env.PATH,
+    });
+    // which-project V14, amended: one page server for the process, so a switched-from project's pages still reach it.
+    const server = processServer();
+    const result = await runSwitching((workingDirectory, args, seams) => createCommandRouter({ ...environmentAt(workingDirectory, seams), server }).route(args), process.cwd(), argv, write);
+    return write(result);
+}
+/** A result, written where it belongs: the output to stdout, a refusal to stderr. The exit code it carries is returned. */
+function write(result) {
+    switch (result.kind) {
+        case 'help':
+            process.stdout.write(result.usage);
+            return EXIT_CODE.ok;
+        case 'usage-error':
+            process.stderr.write(`agentwhy: ${result.message}\n\n${result.usage}`);
+            return EXIT_CODE.usage;
+        case 'completed':
+            process.stdout.write(result.output);
+            return result.exitCode;
+        case 'hook-block':
+            process.stderr.write(result.reason);
+            return HOOK_BLOCK_EXIT_CODE;
+    }
+}
+try {
+    process.exitCode = await main(process.argv.slice(2));
+}
+catch (error) {
+    process.stderr.write(`agentwhy: unexpected error: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = EXIT_CODE.unexpected;
+}

package/dist/composition-root.js

@@ -0,0 +1,411 @@
+/**
+ * A port for a place where nobody can be asked. The served Settings view runs setup with its own confirm step as
+ * the consent (R58, `interactive: false`), so a question here would be a question with no one at the other end:
+ * it is refused loudly rather than answered with a guess.
+ */
+function unaskable(what) {
+    const refuse = () => {
+        throw new Error(`agentwhy tried to ask for ${what} where nobody can be asked.`);
+    };
+    return { choose: refuse, chooseMany: refuse, ask: refuse };
+}
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { TellLists, tellListPaths } from './report/private-files/tell-lists.js';
+import { projectDirectoryName } from './adapter/claude-code/contract/projects.js';
+import { ClaudeCodeSessionCatalogue } from './adapter/claude-code/discovery/claude-code-session-catalogue.js';
+import { ClaudeCodeSessionDiscovery } from './adapter/claude-code/discovery/claude-code-session-discovery.js';
+import { ClaudeCodeSessionTitles } from './adapter/claude-code/discovery/claude-code-session-titles.js';
+import { ClaudeCodeProjectCatalogue } from './adapter/claude-code/discovery/claude-code-project-catalogue.js';
+import { ClaudeCodeSessionSource } from './adapter/claude-code/events/claude-code-session-source.js';
+import { ClaudeCodeProbe } from './adapter/claude-code/probe/claude-code-probe.js';
+import { recogniseClaudeCode } from './adapter/claude-code/discovery/claude-code-recognition.js';
+import { recogniseCodex } from './adapter/codex/discovery/codex-recognition.js';
+import { CodexSessionDiscovery } from './adapter/codex/discovery/codex-session-discovery.js';
+import { CodexSessionIndex } from './adapter/codex/discovery/codex-session-index.js';
+import { CodexSessionCatalogue } from './adapter/codex/discovery/codex-session-catalogue.js';
+import { CodexSessionTitles } from './adapter/codex/discovery/codex-session-titles.js';
+import { CodexProjectCatalogue } from './adapter/codex/discovery/codex-project-catalogue.js';
+import { SESSIONS_ROOT as CODEX_SESSIONS_ROOT, THREAD_NAMES } from './adapter/codex/contract/session.js';
+import { CodexSessionSource } from './adapter/codex/events/codex-session-source.js';
+import { CombinedProjectCatalogue } from './core/combined-project-catalogue.js';
+import { CombinedSessionCatalogue } from './core/combined-session-catalogue.js';
+import { ProviderTitles } from './core/provider-titles.js';
+import { FormatSelectingReader } from './core/session-reader.js';
+import { CodexProbe } from './adapter/codex/probe/codex-probe.js';
+import { CommandRouter } from './cli/command-router.js';
+import { CheckCliCommand } from './cli/commands/check-cli-command.js';
+import { InitCliCommand } from './cli/commands/init-cli-command.js';
+import { RefuseCliCommand } from './cli/commands/refuse-cli-command.js';
+import { CodexStopCliCommand } from './cli/commands/codex-stop-cli-command.js';
+import { CodexTurnRefusals } from './adapter/codex/hooks/stop-refusals.js';
+import { DoctorCliCommand } from './cli/commands/doctor-cli-command.js';
+import { ReportCliCommand } from './cli/commands/report-cli-command.js';
+import { SessionsCliCommand } from './cli/commands/sessions-cli-command.js';
+import { MenuCliCommand } from './cli/commands/menu-cli-command.js';
+import { StartCliCommand } from './cli/commands/start-cli-command.js';
+import { NotifyCliCommand } from './cli/commands/notify-cli-command.js';
+import { WatchCliCommand } from './cli/commands/watch-cli-command.js';
+import { widthFor } from './cli/commands/report-usage.js';
+import { Redactor } from './core/redaction/redactor.js';
+import { SessionFormats } from './core/session-format.js';
+import { SessionReport } from './report/session-report.js';
+import { TextDigestRenderer } from './report/check/render/text-digest-renderer.js';
+import { SessionCheck } from './report/check/session-check.js';
+import { CommandRefusal } from './refuse/command-refusal.js';
+import { CodexMirror } from './setup/codex-mirror.js';
+import { ProjectSetup } from './setup/project-setup.js';
+import { ReportPageRenderer } from './report/render/report-page/report-page-renderer.js';
+import { ConversationsRenderer } from './report/start/conversations/conversations-renderer.js';
+import { SettingsRenderer } from './report/start/settings/settings-renderer.js';
+import { MonthRenderer } from './report/start/month/month-renderer.js';
+import { ToFixRenderer } from './report/start/to-fix/to-fix-renderer.js';
+import { SessionStart } from './report/start/session-start.js';
+import { NoticeWordsRenderer } from './report/watch/render/notice-words.js';
+import { NoticeSettings } from './report/watch/notice-settings.js';
+import { SubagentWatch } from './report/watch/subagent-watch.js';
+import { TextReportRenderer } from './report/render/text-report-renderer.js';
+import { createDoctorAttentionRules } from './doctor/render/attention/doctor-attention-rules.js';
+import { JsonDoctorRenderer } from './doctor/render/json-doctor-renderer.js';
+import { TextDoctorRenderer } from './doctor/render/text-doctor-renderer.js';
+import { SessionDoctor } from './doctor/session-doctor.js';
+import { CodexDoctor } from './doctor/codex-doctor.js';
+import { FormatSelectingDoctor } from './doctor/format-selecting-doctor.js';
+import { CodexTextDoctorRenderer } from './doctor/render/codex-text-doctor-renderer.js';
+import { NodeBrowser } from './infrastructure/node-browser.js';
+import { OsascriptFolderChooser } from './infrastructure/osascript-folder-chooser.js';
+import { PowershellFolderChooser } from './infrastructure/powershell-folder-chooser.js';
+import { ClackAsker } from './infrastructure/clack-asker.js';
+import { ClackChooser } from './infrastructure/clack-chooser.js';
+import { ClackMultiChooser } from './infrastructure/clack-multi-chooser.js';
+import { FileMarkStore } from './infrastructure/file-mark-store.js';
+import { FileCheckedStore } from './infrastructure/file-checked-store.js';
+import { FileOnboardingStore } from './infrastructure/file-onboarding-store.js';
+import { OnboardingRenderer } from './report/start/onboarding/onboarding-renderer.js';
+import { NodeFileSystem } from './infrastructure/node-file-system.js';
+import { realDirectory } from './infrastructure/real-directory.js';
+import { NodeAgentwhyInvocation } from './infrastructure/node-agentwhy-invocation.js';
+import { NodeLocalServer } from './infrastructure/node-local-server.js';
+import { NodeTextInput } from './infrastructure/node-text-input.js';
+import { StreamPrinter } from './infrastructure/stream-printer.js';
+import { TerminalBanner } from './infrastructure/terminal-banner.js';
+import { FileAlertStore } from './infrastructure/file-alert-store.js';
+import { OsNotifier } from './infrastructure/os-notifier.js';
+import { TAGLINE, terminalLogo } from './shared/terminal-logo.js';
+/**
+ * Where a person's answers about being told are kept (`the-agent-tells-you.md` R22): one file, beside the marks,
+ * under the directory this tool already owns in their home - outside every project, and so outside every repository.
+ */
+export function preferencesPath(environment) {
+    return join(environment.home, '.agentwhy', 'notices.json');
+}
+/** Where the pages `start` writes lead to one another. */
+const APP_LINKS = { conversations: 'index.html', toFix: 'to-fix.html', month: 'month.html', settings: 'settings.html', onboarding: 'onboarding.html' };
+/**
+ * The page server for a whole process (`.ai/specs/2026-09-27-which-project.md` V14, amended 2026-09-28): every project a
+ * page switches to is served at the same address, so the pages of the one before still reach it.
+ */
+export function processServer() {
+    return new NodeLocalServer();
+}
+export function createCommandRouter(environment) {
+    const files = new NodeFileSystem();
+    // which-project V6: the home directory as a working directory is given, every link followed - read only to tell a
+    // run started there. Every other use keeps `home` as the shell gave it.
+    const realHome = realDirectory(environment.home);
+    // J1-J3: how this agentwhy runs, for every hook written in this run and for the command `watch` offers.
+    const invocation = new NodeAgentwhyInvocation({ script: environment.script, path: environment.path, platform: environment.platform });
+    // `check` lists Claude Code's sessions alone: the Codex specification covers `doctor`, `report` and the pages `start`
+    // serves, and nothing else (`.ai/plans/2026-09-29-what-codex-wrote.md` step 8's audit). `watch` and every hook read
+    // Claude Code alone too, by their own source.
+    const claudeCatalogue = new ClaudeCodeSessionCatalogue(files, environment.home);
+    // XD7: the one registry that tells formats apart by content - Codex's strict first-line rule first - read by `doctor`,
+    // `report`, `start` and `sessions`. One listing of Codex's root serves the catalogue and the reports it lists.
+    const codexDiscovery = new CodexSessionDiscovery({ directories: files, files });
+    const codexIndex = new CodexSessionIndex(codexDiscovery);
+    const codexRoot = join(environment.home, ...CODEX_SESSIONS_ROOT);
+    const codexCatalogue = new CodexSessionCatalogue({ index: codexIndex, directories: files, sessionsRoot: codexRoot });
+    // XD5: one list of a project's conversations for both AIs, each row naming its AI.
+    const catalogue = new CombinedSessionCatalogue([claudeCatalogue, codexCatalogue]);
+    // codex-blocks-too CK6: a project uses Codex where a Codex conversation is listed for it.
+    const codexConversations = async () => (await codexCatalogue.list(environment.workingDirectory)).sessions.length > 0;
+    const formats = new SessionFormats([
+        { provider: 'codex', recognise: (input) => recogniseCodex(codexDiscovery, files, input) },
+        { provider: 'claude-code', recognise: (input) => recogniseClaudeCode(files, input) },
+    ]);
+    const doctor = new FormatSelectingDoctor({
+        formats,
+        doctors: {
+            codex: new CodexDoctor({
+                probe: new CodexProbe({ discovery: codexDiscovery, directories: files, files }),
+                renderers: { text: new CodexTextDoctorRenderer(), json: new JsonDoctorRenderer() },
+            }),
+            'claude-code': new SessionDoctor({
+                discovery: new ClaudeCodeSessionDiscovery(files),
+                probe: new ClaudeCodeProbe(files),
+                renderers: {
+                    text: new TextDoctorRenderer(createDoctorAttentionRules()),
+                    json: new JsonDoctorRenderer(),
+                },
+            }),
+        },
+        whenUnavailable: 'claude-code',
+    });
+    // One opener, so a report and an index are shown the same way.
+    const browser = new NodeBrowser(environment.platform);
+    // F57: the files a person asked only to be told about, read with the policy by every command that chooses one, so
+    // an alert, a report and a refusal never read the same file differently.
+    const tell = tellListPaths(environment.home, environment.workingDirectory);
+    const tellLists = new TellLists({ files, writer: files, paths: tell });
+    const report = new SessionReport({
+        reader: new FormatSelectingReader({
+            formats,
+            sources: {
+                codex: new CodexSessionSource({ discovery: codexDiscovery, files, sessionsRoot: codexRoot, index: codexIndex }),
+                'claude-code': new ClaudeCodeSessionSource({ discovery: new ClaudeCodeSessionDiscovery(files), files }),
+            },
+            whenUnavailable: 'claude-code',
+        }),
+        files,
+        tell,
+        // A salt per run, so a pseudonym says "the same value" inside one report and nothing at all outside it.
+        createRedactor: (projectRoot, share) => new Redactor(randomUUID(), projectRoot, share),
+        createRenderer: (options) => new TextReportRenderer(options.width, {
+            ascii: options.ascii,
+            full: options.full,
+            colour: environment.colour && options.colour,
+        }),
+        htmlRenderer: new ReportPageRenderer(),
+        // A record's time on the page is this machine's, as the days on Conversations are (the report page spec M4).
+        timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        catalogue,
+        workingDirectory: environment.workingDirectory,
+        browser,
+        temporaryDirectory: environment.temporaryDirectory,
+        now: environment.now,
+    });
+    // Its own salt: a pseudonym in a title means "the same value" within one list of sessions and nothing beyond it.
+    // One process runs one command, so `start` and `sessions` never share a list; both AIs' titles are one list's.
+    // Codex's are the names Codex gave its threads (`THREAD_NAMES`, measured 2026-09-30); a thread it named nothing - a
+    // `codex exec` run - keeps the missing-title state rather than a message guessed at.
+    const titleRedactor = new Redactor(randomUUID());
+    const titles = new ProviderTitles({
+        'claude-code': new ClaudeCodeSessionTitles({ transcripts: files, redactor: titleRedactor }),
+        codex: new CodexSessionTitles({ files, directories: files, path: join(environment.home, ...THREAD_NAMES.file), redactor: titleRedactor }),
+    });
+    // which-project V9-V11: the person's projects, for the window the sidebar's card opens. A title from another project
+    // passes a redactor of its own, as this project's titles do.
+    // A folder only Codex worked in is listed under the id Claude Code would give it, so a folder in both is one project
+    // (decided 2026-09-29).
+    const projects = new CombinedProjectCatalogue([
+        new ClaudeCodeProjectCatalogue({ directories: files, transcripts: files, redactor: new Redactor(randomUUID()), home: environment.home }),
+        new CodexProjectCatalogue({ index: codexIndex, directories: files, sessionsRoot: codexRoot, projectId: projectDirectoryName }),
+    ]);
+    // One person's record of what they did about a file, beside nothing else and outside every project
+    // (`worth-running-every-day` R33). The directory is named the way Claude Code names the project's sessions.
+    const projectRecords = join(environment.home, '.agentwhy', 'projects', projectDirectoryName(environment.workingDirectory));
+    const marks = new FileMarkStore(join(projectRecords, 'marks.jsonl'));
+    // Beside it, the conversations a person asked to check although they were older than a run (F55).
+    const checked = new FileCheckedStore(join(projectRecords, 'checked.jsonl'));
+    // Whether this person finished the onboarding, here and anywhere: one file for every project, since the intro plays
+    // once per person (`.ai/specs/2026-09-24-onboarding.md` W21, N1, N2). Outside every project, as the marks are.
+    const onboarding = new FileOnboardingStore(join(environment.home, '.agentwhy', 'onboarding.jsonl'), projectDirectoryName(environment.workingDirectory));
+    // One set of rules for the preferences file, with two ways in: this command, and the page's Notifications panel.
+    const notices = new NoticeSettings({
+        files,
+        writer: files,
+        path: preferencesPath(environment),
+        workingDirectory: environment.workingDirectory,
+    });
+    const start = new SessionStart({
+        catalogue,
+        report,
+        files,
+        tell,
+        tellLists,
+        // live-pages L4: a clock that only moves forward, to space out reading a session the agent is still writing.
+        elapsed: () => performance.now(),
+        policyFiles: files,
+        directories: files,
+        browser,
+        // The Conversations page is the index; To fix, This month and Settings are pages of their own, on the UI kit.
+        // The earlier page they were views of is gone (`.ai/plans/2026-09-23-to-fix-redesign.md` step 4).
+        renderer: new ConversationsRenderer(APP_LINKS),
+        pages: {
+            [APP_LINKS.month]: new MonthRenderer(APP_LINKS),
+            [APP_LINKS.toFix]: new ToFixRenderer(APP_LINKS),
+            [APP_LINKS.settings]: new SettingsRenderer(APP_LINKS),
+        },
+        // Days and times on the page are this machine's (`for-people-who-build-with-ai.md` O2).
+        timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        digest: new TextDigestRenderer('counts', { colour: environment.colour }),
+        marks,
+        checked,
+        // The first page a project's first served run opens (W23), and written with every served run (W25).
+        onboarding: { page: new OnboardingRenderer(APP_LINKS), file: APP_LINKS.onboarding, store: onboarding },
+        titles,
+        projects,
+        // which-project V14, V15: another project shown in the same tab, by a run the shell starts beside this one.
+        ...(environment.switchTo === undefined ? {} : { switchTo: environment.switchTo }),
+        ...(environment.handedOver === undefined ? {} : { handedOver: environment.handedOver }),
+        ...(environment.arrivedFrom === undefined ? {} : { arrivedFrom: environment.arrivedFrom }),
+        ...(environment.served === undefined ? {} : { served: environment.served }),
+        ...(environment.pastRuns === undefined ? {} : { pastRuns: environment.pastRuns }),
+        // V12: the computer's own folder window - macOS's, measured (VB1), or Windows', not yet (VB7). Elsewhere none.
+        folderChooser: environment.platform === 'win32' ? new PowershellFolderChooser(environment.platform) : new OsascriptFolderChooser(environment.platform),
+        // R50-R54: the page `start` opens is served from the loopback address, behind a token only that page is given.
+        server: environment.server ?? new NodeLocalServer(),
+        // R58: a change made in Settings runs through the same setup a terminal runs. Nothing here can ask a question:
+        // the page's own confirm step is the consent, so the choosers are never reached and say so if they ever are.
+        // nothing-updates-by-itself U2: the version this run is, beside the hooks' own, for the update notice.
+        invocation,
+        // codex-blocks-too CK5: every write of Claude Code's `refuse` - a switch, Finish blocking, the onboarding - writes
+        // Codex's with it, in a project that uses Codex.
+        setup: new CodexMirror({
+            setup: new ProjectSetup({
+                files,
+                chooser: unaskable('a choice'),
+                hookChooser: unaskable('a list'),
+                asker: unaskable('a question'),
+                interactive: false,
+                workingDirectory: environment.workingDirectory,
+                home: environment.home,
+                realHome,
+                invocation,
+            }),
+            files,
+            chooser: unaskable('a choice'),
+            interactive: false,
+            workingDirectory: environment.workingDirectory,
+            invocation,
+            codexConversations,
+        }),
+        // R26a: the panel that says what a person is told, writing the one file outside every project.
+        notices,
+        printer: new StreamPrinter(environment.output),
+        // The wordmark above the answer, and colour over it: both decided in the shell, neither read from a stream here.
+        terminal: { colour: environment.colour, decorated: environment.terminal },
+        token: () => randomUUID(),
+        clock: () => Date.now(),
+        workingDirectory: environment.workingDirectory,
+        home: environment.home,
+        realHome,
+        temporaryDirectory: environment.temporaryDirectory,
+        now: environment.now,
+    });
+    const check = new SessionCheck({
+        catalogue: claudeCatalogue,
+        report,
+        files,
+        tell,
+        createRenderer: (options) => new TextDigestRenderer(options.full ? 'full' : 'brief', { colour: environment.colour }),
+        marks,
+        workingDirectory: environment.workingDirectory,
+        now: environment.now,
+    });
+    const watch = new SubagentWatch({
+        source: new ClaudeCodeSessionSource({ discovery: new ClaudeCodeSessionDiscovery(files), files }),
+        files,
+        tell,
+        input: new NodeTextInput(environment.input),
+        // Its own salt, as every report has: nothing it redacts means anything outside this one run.
+        createRedactor: (projectRoot) => new Redactor(randomUUID(), projectRoot, false),
+        renderer: new NoticeWordsRenderer(),
+        notifier: new OsNotifier(environment.platform),
+        home: environment.home,
+        // What one hook run leaves for the next: outside every project, and swept by age (`a-notice-in-the-conversation` R7).
+        store: new FileAlertStore(environment.temporaryDirectory, environment.user),
+        // What a person chose about being told: their own file, outside every project, read on every run (R22, R25).
+        preferencesPath: preferencesPath(environment),
+        // R14: the agent is asked to speak only where a person is reading, and the entry point is what says so.
+        ...(environment.entryPoint === undefined ? {} : { entryPoint: environment.entryPoint }),
+        // R29: the language of a line nobody chose one for.
+        ...(environment.locale === undefined ? {} : { locale: environment.locale }),
+        // R18: the agent runs agentwhy the way this project's hook does; J6: else the way this hook was started.
+        ...(environment.projectDirectory === undefined ? {} : { projectDirectory: environment.projectDirectory }),
+        invocation,
+    });
+    // Drawn above the first question each of these commands asks, and not again: one banner per command.
+    const logo = () => new TerminalBanner(terminalLogo([TAGLINE], { colour: environment.colour, ascii: false }));
+    const setupBanner = logo();
+    // Registration order is the order `--help` lists them in, so the way in comes first.
+    const start_ = new StartCliCommand({ start, now: environment.now });
+    const check_ = new CheckCliCommand({ check, now: environment.now });
+    const setupChooser = new ClackChooser(environment.input, environment.output, setupBanner);
+    const init_ = new InitCliCommand(new CodexMirror({
+        setup: new ProjectSetup({
+            files,
+            chooser: setupChooser,
+            hookChooser: new ClackMultiChooser(environment.input, environment.output, setupBanner),
+            asker: new ClackAsker(environment.input, environment.output, setupBanner),
+            interactive: environment.interactive,
+            workingDirectory: environment.workingDirectory,
+            home: environment.home,
+            realHome,
+            invocation,
+        }),
+        files,
+        chooser: setupChooser,
+        interactive: environment.interactive,
+        workingDirectory: environment.workingDirectory,
+        invocation,
+        codexConversations,
+    }));
+    // One banner for both ports this command can ask through - the range question, then the list - so it is drawn once.
+    const sessionsBanner = logo();
+    const sessions_ = new SessionsCliCommand({
+        catalogue,
+        workingDirectory: environment.workingDirectory,
+        chooser: new ClackChooser(environment.input, environment.output, sessionsBanner),
+        asker: new ClackAsker(environment.input, environment.output, sessionsBanner),
+        titles,
+        report,
+        width: widthFor(environment.columns),
+        interactive: environment.interactive,
+        now: environment.now,
+    });
+    // `agentwhy menu`: the few things to do here, in the order most people want them.
+    const menu = new MenuCliCommand({
+        chooser: new ClackChooser(environment.input, environment.output, logo()),
+        printer: new StreamPrinter(environment.output),
+        interactive: environment.interactive,
+        // Named by what a person gets, with the command beside it. `start` leads while `check`'s rows are unmeasured
+        // (spec §5): a page carries a row that turns out to be a mention far better than a list in a terminal does.
+        entries: [
+            { label: 'Open the last 7 days of sessions', detail: 'agentwhy start', command: start_ },
+            { label: 'List what to rotate or check', detail: 'agentwhy check', command: check_ },
+            { label: 'Open one session', detail: 'agentwhy sessions', command: sessions_ },
+            // The hint carries the words a person searches by - the list filters on both, and "settings" is what
+            // this is called out loud, while `init` is what the command is called.
+            { label: 'Set up protection for this project', detail: "agentwhy init · what agents can do, what's protected", command: init_ },
+        ],
+    });
+    // R72-R73: a bare `agentwhy` opens the page, and only where a person is there to see it. With no terminal there is
+    // no such command, so the router's usage error stands and nothing is opened or served.
+    return new CommandRouter([
+        start_,
+        menu,
+        // Then the command a person runs every day, and the one that sets a project up to be told without asking.
+        check_,
+        init_,
+        sessions_,
+        // What a person wants to be told, and where: the file the hook reads, changed from a terminal or from the page.
+        new NotifyCliCommand({ settings: notices }),
+        new ReportCliCommand(report, environment.columns),
+        new DoctorCliCommand(doctor),
+        // Last: it is run by a hook, not by a person looking for where to begin.
+        new WatchCliCommand({ watch, interactive: environment.inputIsTerminal }),
+        new RefuseCliCommand({
+            refusal: new CommandRefusal({
+                input: new NodeTextInput(environment.input),
+                files,
+                directories: files,
+                workingDirectory: environment.workingDirectory,
+                home: environment.home,
+                tell,
+            }),
+            interactive: environment.inputIsTerminal,
+        }),
+        new CodexStopCliCommand(new CodexTurnRefusals(new NodeTextInput(environment.input), files), environment.inputIsTerminal),
+    ], environment.interactive ? start_ : undefined);
+}