@agentwhy/cli 0.0.0-dev

package/dist/doctor/render/text-doctor-renderer.js

@@ -0,0 +1,124 @@
+import { countsTable, table } from '../../shared/text-table.js';
+const SECTION_INDENT = 2;
+const SUBSECTION_INDENT = 4;
+const DETAIL_INDENT = 6;
+const NOTHING_TO_REPORT = 'none';
+export class TextDoctorRenderer {
+    #attentionRules;
+    constructor(attentionRules) {
+        this.#attentionRules = attentionRules;
+    }
+    render(report) {
+        return [
+            `agentwhy doctor · session ${report.sessionId}`,
+            `format contract v${report.contractVersion}, verified against Claude Code ${report.verifiedAgainst}`,
+            '',
+            'Needs attention',
+            ...this.#attention(report).map((item) => `${' '.repeat(SECTION_INDENT)}${item}`),
+            '',
+            ...sourcesSection(report),
+            '',
+            'Claude Code versions (lines)',
+            ...countsTable(report.toolVersions, SECTION_INDENT),
+            '',
+            'Working directories (cwd)',
+            ...table([
+                ['distinct', String(report.workingDirectories.distinct)],
+                ['invalid', String(report.workingDirectories.invalid)],
+            ], SECTION_INDENT),
+            '',
+            ...transcriptSection('Main session', report.main),
+            '',
+            ...transcriptSection('Subagents', report.subagents),
+            '',
+            ...metaSection(report),
+            '',
+            'Agent tool input keys',
+            ...countsTable(report.agentToolInputKeys, SECTION_INDENT),
+            '',
+            'Denials by toolDenialKind',
+            ...countsTable(report.denials.byKind, SECTION_INDENT),
+            '',
+            'Spilled result references',
+            ...table([
+                ['referenced', String(report.toolResultReferences.referenced)],
+                ['missing', String(report.toolResultReferences.missing)],
+            ], SECTION_INDENT),
+            '',
+            'Task notifications delivered',
+            ...table([
+                ['naming a delegation', String(report.taskNotifications.namingADelegation)],
+                ['naming another call', String(report.taskNotifications.namingAnotherCall)],
+                ['naming no call here', String(report.taskNotifications.namingNoCall)],
+                ['naming nothing', String(report.taskNotifications.withoutCallId)],
+            ], SECTION_INDENT),
+            '',
+        ].join('\n');
+    }
+    #attention(report) {
+        const findings = this.#attentionRules.flatMap((rule) => rule.findings(report));
+        return findings.length > 0 ? findings : [NOTHING_TO_REPORT];
+    }
+}
+function sourcesSection({ sources }) {
+    const files = sources.subagentFiles;
+    return [
+        'Sources',
+        ...table([
+            ['main transcript', sources.mainTranscript],
+            ['subagents directory', sources.subagentsDirectory],
+            ['tool-results directory', sources.toolResultsDirectory],
+            ['subagent files', `total ${files.total} · with transcript ${files.withTranscript} · with meta ${files.withMeta}`],
+            ['spilled result files', String(sources.toolResultFiles)],
+            ['unrecognised entries', String(sources.unrecognisedEntries)],
+        ], SECTION_INDENT),
+    ];
+}
+function transcriptSection(title, stats) {
+    const { sidechain } = stats;
+    return [
+        title,
+        ...table([
+            ['transcript files', `${stats.files} (${stats.unreadableFiles} unreadable)`],
+            ['lines', `${stats.lines} (${stats.unparsableLines} unparsable)`],
+            [
+                'isSidechain',
+                `true ${sidechain.true} · false ${sidechain.false} · absent ${sidechain.absent} · invalid ${sidechain.invalid}`,
+            ],
+            ['Agent calls', String(stats.agentToolUses)],
+            ['denied calls', String(stats.deniedCalls)],
+            ['unique toolu_ ids', String(stats.uniqueToolUseIds)],
+            ['unique UUIDs', String(stats.uniqueUuids)],
+        ], SECTION_INDENT),
+        '  line types',
+        ...countsTable(stats.lineTypes, SUBSECTION_INDENT),
+        '  system subtypes',
+        ...countsTable(stats.systemSubtypes, SUBSECTION_INDENT),
+        '  tools',
+        ...countsTable(stats.tools, SUBSECTION_INDENT),
+        '  top-level keys',
+        ...countsTable(stats.topLevelKeys, SUBSECTION_INDENT),
+        '  keys on unknown line types',
+        ...keysByTypeLines(stats.unknownLineTypeKeys),
+    ];
+}
+function keysByTypeLines(keysByType) {
+    const entries = Object.entries(keysByType);
+    if (entries.length === 0)
+        return countsTable({}, SUBSECTION_INDENT);
+    return entries.flatMap(([type, keys]) => [`${' '.repeat(SUBSECTION_INDENT)}${type}`, ...countsTable(keys, DETAIL_INDENT)]);
+}
+function metaSection({ meta }) {
+    return [
+        'meta.json',
+        ...table([['files', `${meta.files} (${meta.unparsableFiles} unparsable, ${meta.unreadableFiles} unreadable)`]], SECTION_INDENT),
+        '  agentType',
+        ...countsTable(meta.agentType, SUBSECTION_INDENT),
+        '  spawnDepth (files per depth)',
+        ...countsTable(meta.spawnDepth, SUBSECTION_INDENT),
+        '  requestShape',
+        ...countsTable(meta.requestShape, SUBSECTION_INDENT),
+        '  keys',
+        ...countsTable(meta.keys, SUBSECTION_INDENT),
+    ];
+}

package/dist/doctor/session-doctor.js

@@ -0,0 +1,16 @@
+/** Discovers a session, measures it and renders the report. Returns the result; writing it is the shell's job. */
+export class SessionDoctor {
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async run(options) {
+        const { discovery, probe, renderers } = this.#dependencies;
+        const session = await discovery.discover(options.input);
+        const report = await probe.probe(session);
+        return {
+            outcome: session.mainTranscript.present ? 'complete' : 'main-transcript-missing',
+            output: renderers[options.format].render(report),
+        };
+    }
+}

package/dist/infrastructure/clack-asker.js

@@ -0,0 +1,24 @@
+import { isCancel, text } from '@clack/prompts';
+/** One line of text, through `@clack/prompts`. A blank answer comes back as an empty string, never as a cancellation. */
+export class ClackAsker {
+    #input;
+    #output;
+    #banner;
+    /** The banner is shared with the command's other prompts, so the mark is drawn once above the first of them. */
+    constructor(input, output, banner) {
+        this.#input = input;
+        this.#output = output;
+        this.#banner = banner;
+    }
+    async ask(question, placeholder) {
+        this.#banner?.drawOn(this.#output);
+        const answer = await text({
+            message: question,
+            ...(placeholder === undefined ? {} : { placeholder }),
+            defaultValue: '',
+            input: this.#input,
+            output: this.#output,
+        });
+        return isCancel(answer) ? undefined : answer;
+    }
+}

package/dist/infrastructure/clack-chooser.js

@@ -0,0 +1,40 @@
+import { autocomplete, isCancel } from '@clack/prompts';
+/** Rows shown at once. The rest are reached by moving, or found by typing. */
+const VISIBLE = 10;
+/**
+ * Chooses through `@clack/prompts`: a list that narrows as a person types, so a session is found by a word of its
+ * title, its date or its id rather than by counting rows. It is the project's only runtime dependency, and this is
+ * the only module allowed to import it (`2026-09-13-conventions.md`, Runtime dependencies).
+ *
+ * **Replaced a hand-written chooser on 2026-09-15**, after someone at a real terminal could not choose with it. The
+ * failure did not reproduce in a pseudo-terminal, so this swaps in a widely used implementation; it does not fix a
+ * cause that was found.
+ */
+export class ClackChooser {
+    #input;
+    #output;
+    #banner;
+    /** `banner` is drawn above the first question of a command: it decides for itself whether it has been drawn already. */
+    constructor(input, output, banner) {
+        this.#input = input;
+        this.#output = output;
+        this.#banner = banner;
+    }
+    async choose(heading, choices) {
+        if (choices.length === 0)
+            return undefined;
+        this.#banner?.drawOn(this.#output);
+        const chosen = await autocomplete({
+            message: heading,
+            options: choices.map((choice, position) => ({ value: position, label: choice.label, hint: choice.detail })),
+            // The default filter also matches the value, which here is a row number: typing "2" would match row 2
+            // whatever it says. What a person searches by is what they can see.
+            filter: (search, option) => `${option.label ?? ''} ${option.hint ?? ''}`.toLowerCase().includes(search.toLowerCase()),
+            maxItems: VISIBLE,
+            input: this.#input,
+            output: this.#output,
+        });
+        // Escape and Ctrl-C cancel. Enter on a search that matches nothing resolves with no value, which is not a choice.
+        return isCancel(chosen) || chosen === undefined ? undefined : chosen;
+    }
+}

package/dist/infrastructure/clack-multi-chooser.js

@@ -0,0 +1,31 @@
+import { isCancel, multiselect } from '@clack/prompts';
+/**
+ * A list with boxes, through `@clack/prompts` - the package the session chooser already uses, so no new dependency
+ * (`2026-09-13-conventions.md`, Runtime dependencies). Answering with nothing ticked is an answer, not a cancellation:
+ * "install none of this" is a thing a person may mean.
+ */
+export class ClackMultiChooser {
+    #input;
+    #output;
+    #banner;
+    /** The banner is shared with the command's other prompts, so the mark is drawn once above the first of them. */
+    constructor(input, output, banner) {
+        this.#input = input;
+        this.#output = output;
+        this.#banner = banner;
+    }
+    async chooseMany(heading, choices) {
+        this.#banner?.drawOn(this.#output);
+        if (choices.length === 0)
+            return [];
+        const chosen = await multiselect({
+            message: heading,
+            options: choices.map((choice, position) => ({ value: position, label: choice.label, hint: choice.detail })),
+            initialValues: choices.flatMap((choice, position) => (choice.selected ? [position] : [])),
+            required: false,
+            input: this.#input,
+            output: this.#output,
+        });
+        return isCancel(chosen) ? undefined : [...chosen].sort((a, b) => a - b);
+    }
+}

package/dist/infrastructure/file-alert-store.js

@@ -0,0 +1,120 @@
+import { lstat, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** One directory of its own, so pruning never looks at a file this tool did not write. */
+const DIRECTORY = 'agentwhy-alerts';
+/** A session nobody finished leaves a file behind. After this it is swept, whether its turn ever ended or not. */
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/** Everything else in a session id is replaced, so no id can name a path of its own. */
+const UNSAFE = /[^A-Za-z0-9._-]/g;
+/**
+ * The alerts of a session, in the system's temporary directory (`specs/2026-09-16-a-notice-in-the-conversation.md`
+ * R7): written when `SubagentStop` finds one, read and cleared when `Stop` says it, and swept by age so an
+ * abandoned session leaves nothing behind.
+ *
+ * Nothing here throws. A hook cannot afford it: on `SubagentStop` an error becomes the agent's next instruction, and
+ * on `Stop` it holds the turn open. A store that could not write is a notice that was not said - and `check` still
+ * finds the same thing in the records.
+ */
+export class FileAlertStore {
+    #directory;
+    #user;
+    #now;
+    constructor(temporaryDirectory, user, now = Date.now) {
+        this.#directory = join(temporaryDirectory, DIRECTORY);
+        this.#user = user;
+        this.#now = now;
+    }
+    /**
+     * Whether the directory this run would use is this person's own. A mode on `mkdir` settles how a directory is
+     * created and says nothing about one that was there already - and on Linux the system's temporary directory is
+     * one `/tmp` shared by every account, where this directory's fixed name is a name another account can take
+     * first. A symlink left under it would send every write below into whatever directory its author chose.
+     *
+     * So: not a link, this person's own, and not writable by anyone else. Anything short of that and there is no
+     * store, which is a state this class already has an answer for - see the note above.
+     */
+    async #mine() {
+        try {
+            const entry = await lstat(this.#directory);
+            const owner = this.#user === undefined || entry.uid === this.#user;
+            return entry.isDirectory() && owner && (entry.mode & 0o022) === 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    async remember(sessionId, alert) {
+        try {
+            // The owner alone, and the directory first: the system's temporary directory is one `/tmp` shared by every
+            // account on a Linux machine, and this directory's name is fixed, so it is a name another account can reach
+            // for. A mode of its own keeps what is written here - which protected file an agent reached, and in whose
+            // session - out of every other account's reading.
+            await mkdir(this.#directory, { recursive: true, mode: 0o700 });
+            if (!(await this.#mine()))
+                return;
+            await this.#prune();
+            const kept = (await this.#read(sessionId)).filter((remembered) => remembered.agentId !== alert.agentId);
+            await writeFile(this.#fileFor(sessionId), JSON.stringify([...kept, alert]), { encoding: 'utf8', mode: 0o600 });
+        }
+        catch {
+            // See the note above: a store that could not write says nothing, and nothing is a state this tool has words for.
+        }
+    }
+    async take(sessionId) {
+        const remembered = await this.#read(sessionId);
+        try {
+            await rm(this.#fileFor(sessionId), { force: true });
+        }
+        catch {
+            // Said once is said: if the file survives, the next turn repeats a notice. That is better than losing one.
+        }
+        return remembered;
+    }
+    /** A session id is not a file name until this makes it one: no separator, no `..`, no length worth worrying about. */
+    #fileFor(sessionId) {
+        const safe = sessionId.replace(UNSAFE, '-').slice(0, 80);
+        return join(this.#directory, `${safe === '' ? 'session' : safe}.json`);
+    }
+    async #read(sessionId) {
+        if (!(await this.#mine()))
+            return [];
+        try {
+            const parsed = JSON.parse(await readFile(this.#fileFor(sessionId), 'utf8'));
+            return Array.isArray(parsed) ? parsed.filter(isRemembered) : [];
+        }
+        catch {
+            // A missing file is the common case; a half-written one is the same answer, because nothing here is authoritative.
+            return [];
+        }
+    }
+    async #prune() {
+        const oldest = this.#now() - MAX_AGE_MS;
+        for (const name of await readdir(this.#directory)) {
+            if (!name.endsWith('.json'))
+                continue;
+            const file = join(this.#directory, name);
+            try {
+                if ((await stat(file)).mtimeMs < oldest)
+                    await rm(file, { force: true });
+            }
+            catch {
+                // A file that vanished between the listing and the check is a file this does not have to remove.
+            }
+        }
+    }
+}
+/** Read from a file this process wrote, and still checked: a shape that does not hold is a record that is not there. */
+function isRemembered(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const record = value;
+    return typeof record.agentId === 'string' && typeof record.level === 'string' && typeof record.words === 'string' &&
+        (record.counts === undefined || areCounts(record.counts));
+}
+/** Counts that are not two whole numbers are counts this did not write: the record is read as one without them. */
+function areCounts(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const counts = value;
+    return Number.isInteger(counts.values) && Number.isInteger(counts.reached);
+}

package/dist/infrastructure/file-checked-store.js

@@ -0,0 +1,55 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** A session id as Claude Code names a transcript: nothing that could be a path or carry anything else. */
+const SESSION_ID = /^[A-Za-z0-9_-]{1,200}$/;
+/**
+ * The conversations a person asked to be checked, as JSON lines in their home directory beside their marks
+ * (`for-people-who-build-with-ai.md` F55): outside every repository, readable by that person only, appended to.
+ */
+export class FileCheckedStore {
+    #file;
+    constructor(file) {
+        this.#file = file;
+    }
+    async read() {
+        let text;
+        try {
+            text = await readFile(this.#file, 'utf8');
+        }
+        catch (error) {
+            // Never asked is the ordinary answer; anything else is a record that exists and was not read.
+            const missing = error instanceof Error && 'code' in error && error.code === 'ENOENT';
+            return { ids: new Set(), failed: !missing };
+        }
+        const ids = new Set();
+        for (const line of text.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                // Read from a file a person could have edited: a line that does not hold is skipped.
+                if (parsed !== null && typeof parsed === 'object') {
+                    const record = parsed;
+                    if (record.kind === 'checked' && typeof record.id === 'string' && SESSION_ID.test(record.id))
+                        ids.add(record.id);
+                }
+            }
+            catch {
+                // skipped, as a line that does not hold
+            }
+        }
+        return { ids, failed: false };
+    }
+    async add(id, at) {
+        if (!SESSION_ID.test(id))
+            return false;
+        try {
+            await mkdir(dirname(this.#file), { recursive: true, mode: 0o700 });
+            await appendFile(this.#file, JSON.stringify({ kind: 'checked', id, at }) + '\n', { encoding: 'utf8', mode: 0o600 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/infrastructure/file-mark-store.js

@@ -0,0 +1,67 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { isMarkResult } from '../ports/mark-store.js';
+/**
+ * A person's marks for one project, as JSON lines in their home directory (`worth-running-every-day` R33): outside every
+ * repository, readable by that person only, appended to and never rewritten, so what was undone stays visible (R34).
+ */
+export class FileMarkStore {
+    #file;
+    constructor(file) {
+        this.#file = file;
+    }
+    async read() {
+        let text;
+        try {
+            text = await readFile(this.#file, 'utf8');
+        }
+        catch (error) {
+            // Never marked is the ordinary answer; anything else is a record that exists and was not read.
+            const missing = error instanceof Error && 'code' in error && error.code === 'ENOENT';
+            return { records: [], skipped: 0, failed: !missing };
+        }
+        const records = [];
+        let skipped = 0;
+        for (const line of text.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (isRecord(parsed))
+                    records.push(parsed);
+                else
+                    skipped += 1;
+            }
+            catch {
+                skipped += 1;
+            }
+        }
+        return { records, skipped, failed: false };
+    }
+    async append(record) {
+        try {
+            await mkdir(dirname(this.#file), { recursive: true, mode: 0o700 });
+            await appendFile(this.#file, JSON.stringify(record) + '\n', { encoding: 'utf8', mode: 0o600 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/** Read from a file a person could have edited, so every field is checked: a line that does not hold is skipped. */
+function isRecord(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const record = value;
+    if (typeof record.path !== 'string' || record.path === '' || typeof record.at !== 'number' || !Number.isFinite(record.at))
+        return false;
+    if (record.kind === 'unmark')
+        return true;
+    return (record.kind === 'mark' &&
+        typeof record.label === 'string' &&
+        isMarkResult(record.result) &&
+        (record.note === undefined || typeof record.note === 'string') &&
+        Array.isArray(record.sessions) &&
+        record.sessions.every((session) => typeof session === 'string'));
+}

package/dist/infrastructure/file-onboarding-store.js

@@ -0,0 +1,93 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/**
+ * A project as the record names it: the name its sessions' directory has, which holds letters, digits and hyphens
+ * only. Nothing that could be a path, and nothing else a hand-edited line could slip in.
+ */
+const PROJECT = /^[A-Za-z0-9-]{1,1024}$/;
+/**
+ * Which projects' onboarding a person finished, as JSON lines in their home directory beside their notice preferences
+ * (`.ai/specs/2026-09-24-onboarding.md` W21): outside every repository, readable by that person only, appended to.
+ * One file for every project, so "has this person seen the intro anywhere?" is one read (N1, N2).
+ */
+export class FileOnboardingStore {
+    #file;
+    #project;
+    constructor(file, project) {
+        this.#file = file;
+        this.#project = project;
+    }
+    async read() {
+        const record = await this.#record();
+        if (record === 'failed')
+            return { here: false, anywhere: false, failed: true };
+        return { here: record.finished.has(this.#project), anywhere: record.anywhere, failed: false };
+    }
+    async doneFor(projects) {
+        const record = await this.#record();
+        if (record === 'failed')
+            return undefined;
+        return new Set(projects.filter((project) => record.finished.has(project)));
+    }
+    /**
+     * The record as it stands: every project whose last word is `done`, and whether any project ever finished. Absent is
+     * "never"; any other error is `failed`.
+     */
+    async #record() {
+        let text;
+        try {
+            text = await readFile(this.#file, 'utf8');
+        }
+        catch (error) {
+            // Never finished is the ordinary answer; anything else is a record that exists and was not read.
+            const missing = error instanceof Error && 'code' in error && error.code === 'ENOENT';
+            return missing ? { finished: new Set(), anywhere: false } : 'failed';
+        }
+        const finished = new Set();
+        let anywhere = false;
+        // In the order written: a reset for a project cancels the `done` before it (W25a), and a later `done` counts again.
+        for (const line of text.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                // Read from a file a person could have edited: a line that does not hold is skipped.
+                if (parsed !== null && typeof parsed === 'object') {
+                    const record = parsed;
+                    if (typeof record.project !== 'string' || !PROJECT.test(record.project))
+                        continue;
+                    if (record.kind === 'done') {
+                        // The intro is once per person (N2): a finish anywhere counts, whatever was reset after it.
+                        anywhere = true;
+                        finished.add(record.project);
+                    }
+                    else if (record.kind === 'reset') {
+                        finished.delete(record.project);
+                    }
+                }
+            }
+            catch {
+                // skipped, as a line that does not hold
+            }
+        }
+        return { finished, anywhere };
+    }
+    async add(at) {
+        return this.#append('done', at);
+    }
+    async reset(at) {
+        return this.#append('reset', at);
+    }
+    async #append(kind, at) {
+        if (!PROJECT.test(this.#project))
+            return false;
+        try {
+            await mkdir(dirname(this.#file), { recursive: true, mode: 0o700 });
+            await appendFile(this.#file, JSON.stringify({ kind, project: this.#project, at }) + '\n', { encoding: 'utf8', mode: 0o600 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/infrastructure/folder-window.js

@@ -0,0 +1,26 @@
+import { execFile } from 'node:child_process';
+import { realpath } from 'node:fs/promises';
+/**
+ * Runs `program` with `args` and no shell, its own console window hidden where the system would draw one (Windows); a
+ * window the program opens is still shown. A program that exits with a code answers it; one that could not start rejects.
+ */
+export function runProgram(program, args) {
+    return new Promise((resolve, reject) => {
+        execFile(program, [...args], { windowsHide: true }, (error, stdout, stderr) => {
+            if (error !== null && typeof error.code !== 'number') {
+                reject(error);
+                return;
+            }
+            resolve({ code: error === null ? 0 : Number(error.code), stdout: String(stdout), stderr: String(stderr) });
+        });
+    });
+}
+/** The folder a window answered, with every link followed; one that is not there is said so. */
+export async function chosenFolder(path) {
+    try {
+        return { chosen: await realpath(path) };
+    }
+    catch {
+        return { failed: 'The folder chosen could not be found.' };
+    }
+}