@agentwhy/cli 0.0.0-dev

package/dist/infrastructure/node-agentwhy-invocation.js

@@ -0,0 +1,99 @@
+import { constants } from 'node:fs';
+import { access, readFile, realpath, stat } from 'node:fs/promises';
+import { delimiter, dirname, join, sep } from 'node:path';
+import { parseJsonObject } from '../shared/json.js';
+import { PACKAGE } from '../shared/package-name.js';
+import { plainVersion } from '../shared/plain-version.js';
+/** The installed way, and the name of the bin a hook's shell looks up on `PATH`. */
+const INSTALLED = 'agentwhy';
+/**
+ * `agentwhy` where the first `agentwhy` on `PATH` belongs to the package this process runs from, and the published way
+ * everywhere else (`a-hook-runs-what-you-ran.md` J2, J3): `npx @agentwhy/cli@<version>`, pinned to this package's own
+ * version where it is a release, so no hook runs a version nobody chose (`nothing-updates-by-itself.md` U1).
+ *
+ * `PATH` is read without the entries `npx` adds for the length of its run - its cache, a `node_modules/.bin` for every
+ * directory up to `/`, npm's `node-gyp-bin` - each of which has a `node_modules` segment (JB2). Read with them, the
+ * answer inside `npx` is always "installed", and a hook written from it fails as soon as `npx` has exited.
+ */
+export class NodeAgentwhyInvocation {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    async find() {
+        const { script, path, platform } = this.#options;
+        const running = script === undefined ? undefined : await packageOf(script);
+        const npx = published(running === undefined ? undefined : await versionIn(running));
+        // J3: a `.cmd` shim is what a global bin is on Windows, and nothing here has measured one.
+        if (platform === 'win32' || running === undefined || path === undefined)
+            return npx;
+        for (const directory of path.split(delimiter)) {
+            if (directory === '' || directory.split(sep).includes('node_modules'))
+                continue;
+            const bin = await executable(join(directory, INSTALLED));
+            // The first one found is the one a hook's shell runs, whichever package it is.
+            if (bin !== undefined)
+                return (await packageOf(bin)) === running ? INSTALLED : npx;
+        }
+        return npx;
+    }
+    async version() {
+        const { script } = this.#options;
+        const running = script === undefined ? undefined : await packageOf(script);
+        return running === undefined ? undefined : versionIn(running);
+    }
+}
+/**
+ * The published way, written without `--yes`: a hook's first run installs without asking (JB5). Pinned to a release;
+ * a version that is not one (`0.0.0-dev`) is on no registry, and is left out rather than written (U1).
+ */
+function published(version) {
+    return version !== undefined && plainVersion(version) !== undefined ? `npx ${PACKAGE}@${version}` : `npx ${PACKAGE}`;
+}
+/** What a package's `package.json` names as its version, or `undefined` where it cannot be read. */
+async function versionIn(packageRoot) {
+    try {
+        const version = parseJsonObject(await readFile(join(packageRoot, 'package.json'), 'utf8'))?.version;
+        return typeof version === 'string' ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The file a path leads to, where it exists and may be run; `undefined` for a broken link or anything else. */
+async function executable(path) {
+    try {
+        const file = await realpath(path);
+        // A directory passes X_OK, and a shell looking a command up skips it. Found by a review: a checkout named
+        // agentwhy earlier on PATH hid the bin after it.
+        if (!(await stat(file)).isFile())
+            return undefined;
+        await access(file, constants.X_OK);
+        return file;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The nearest directory above a file's real path that holds a `package.json`: the package it belongs to. */
+async function packageOf(file) {
+    let directory;
+    try {
+        directory = dirname(await realpath(file));
+    }
+    catch {
+        return undefined;
+    }
+    for (;;) {
+        try {
+            await access(join(directory, 'package.json'));
+            return directory;
+        }
+        catch {
+            const parent = dirname(directory);
+            if (parent === directory)
+                return undefined;
+            directory = parent;
+        }
+    }
+}

package/dist/infrastructure/node-browser.js

@@ -0,0 +1,40 @@
+import { spawn } from 'node:child_process';
+/**
+ * What each platform calls to open a file with whatever is registered for it. The empty argument after `start`
+ * is not a mistake: `cmd` reads the first quoted argument as the window title, so a path that needs quoting
+ * would otherwise become one.
+ */
+function opener(platform) {
+    if (platform === 'darwin')
+        return { program: 'open', leading: [] };
+    if (platform === 'win32')
+        return { program: 'cmd', leading: ['/c', 'start', ''] };
+    return { program: 'xdg-open', leading: [] };
+}
+/**
+ * Opens a file through the platform's own opener, detached and with its streams closed, so that whatever starts
+ * does not hold this process open and cannot write over the report the terminal is printing.
+ */
+export class NodeBrowser {
+    #platform;
+    constructor(platform) {
+        this.#platform = platform;
+    }
+    async open(path) {
+        const { program, leading } = opener(this.#platform);
+        return new Promise((resolve) => {
+            try {
+                const child = spawn(program, [...leading, path], { stdio: 'ignore', detached: true });
+                child.once('error', () => resolve(false));
+                child.once('spawn', () => {
+                    child.unref();
+                    resolve(true);
+                });
+            }
+            catch {
+                // A platform with no opener at all, or one that refuses to spawn: the file is still written.
+                resolve(false);
+            }
+        });
+    }
+}

package/dist/infrastructure/node-file-system.js

@@ -0,0 +1,111 @@
+import { createReadStream } from 'node:fs';
+import { mkdir, open, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { FileAccessError } from '../ports/file-access-error.js';
+/**
+ * The owner alone, for everything this writes. What it writes is a report: which protected files an agent
+ * reached, the titles a person gave their sessions, the paths of the project they were in. `report --open` and
+ * `start` both land that in the system's temporary directory, which on Linux is one `/tmp` shared by every
+ * account on the machine - and the default of `writeFile` there is a file the whole machine can read.
+ *
+ * `FileMarkStore` has held its record at `0o600` under a `0o700` directory since it was written; this is the
+ * same standard, applied to the larger of the two things this tool puts on disk.
+ */
+const OWNER_ONLY_FILE = 0o600;
+const OWNER_ONLY_DIRECTORY = 0o700;
+export class NodeFileSystem {
+    async writeText(path, text) {
+        await attempt(path, () => writeFile(path, text, { mode: OWNER_ONLY_FILE }));
+    }
+    async ensureDirectory(path) {
+        await attempt(path, () => mkdir(path, { recursive: true, mode: OWNER_ONLY_DIRECTORY }));
+    }
+    async kindOf(path) {
+        return entryKind(await attempt(path, () => stat(path)));
+    }
+    async modifiedAt(path) {
+        return (await attempt(path, () => stat(path))).mtimeMs;
+    }
+    async list(path) {
+        const entries = await attempt(path, () => readdir(path, { withFileTypes: true }));
+        return entries.map((entry) => ({ name: entry.name, kind: entryKind(entry) }));
+    }
+    readText(path) {
+        return attempt(path, () => readFile(path, 'utf8'));
+    }
+    /** Read by position, so a transcript of any size costs at most `bytes`. A read may return less than asked, hence the loop. */
+    readTail(path, bytes) {
+        return attempt(path, async () => {
+            const handle = await open(path, 'r');
+            try {
+                const { size } = await handle.stat();
+                const length = Math.min(bytes, size);
+                const buffer = Buffer.alloc(length);
+                let filled = 0;
+                while (filled < length) {
+                    const { bytesRead } = await handle.read(buffer, filled, length - filled, size - length + filled);
+                    if (bytesRead === 0)
+                        break;
+                    filled += bytesRead;
+                }
+                return buffer.subarray(0, filled).toString('utf8');
+            }
+            finally {
+                await handle.close();
+            }
+        });
+    }
+    /**
+     * JSONL records are delimited by \n alone. `readline` also ends a line on a lone \r, which JSON counts as
+     * ordinary whitespace between tokens - so a record containing one would be split into two halves, each
+     * unparsable, and the record itself lost. Measured on one session, where it cost one `user` line.
+     */
+    async *readLines(path) {
+        const stream = createReadStream(path, { encoding: 'utf8' });
+        let pending = '';
+        try {
+            for await (const chunk of stream) {
+                const parts = (pending + chunk).split('\n');
+                pending = parts.pop() ?? '';
+                for (const line of parts)
+                    yield withoutTrailingReturn(line);
+            }
+        }
+        catch (error) {
+            throw accessError(path, error);
+        }
+        if (pending !== '')
+            yield withoutTrailingReturn(pending);
+    }
+}
+/** Only a \r that terminates the line is a terminator: that is a CRLF file, not a record with a \r inside it. */
+function withoutTrailingReturn(line) {
+    return line.endsWith('\r') ? line.slice(0, -1) : line;
+}
+function entryKind(entry) {
+    if (entry.isFile())
+        return 'file';
+    if (entry.isDirectory())
+        return 'directory';
+    return 'other';
+}
+async function attempt(path, operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        throw accessError(path, error);
+    }
+}
+// Only the failures the application turns into a status are translated; anything else propagates unchanged.
+function accessError(path, error) {
+    const code = error instanceof Error && 'code' in error ? error.code : undefined;
+    // A name too long for the system, or a loop of links, names nothing that can be opened: found by measuring `refuse`
+    // on real transcripts, where a script passed on a command line was looked up as a directory.
+    if (code === 'ENOENT' || code === 'ENOTDIR' || code === 'ENAMETOOLONG' || code === 'ELOOP') {
+        return new FileAccessError('not-found', path, { cause: error });
+    }
+    // A folder read as a file cannot be read as one: `report --input` given a folder of Codex rollouts, which `doctor` takes.
+    if (code === 'EACCES' || code === 'EPERM' || code === 'EISDIR')
+        return new FileAccessError('unreadable', path, { cause: error });
+    return error;
+}

package/dist/infrastructure/node-local-server.js

@@ -0,0 +1,115 @@
+import { createServer } from 'node:http';
+const LOOPBACK = '127.0.0.1';
+/**
+ * `node:http` on 127.0.0.1 and a port the system picks. It stops after a stretch with no request, so a page left open in
+ * a tab does not keep a process running for ever (R54). Headers every answer carries are set here, once.
+ *
+ * One listener for the process (`.ai/specs/2026-09-27-which-project.md` V14, V18, amended 2026-09-28): a run a page
+ * switched to serves at the same address as the run it replaced, so the pages of the project shown before - in a tab's
+ * history, or a tab left open - still reach this process, and are told what happened instead of reaching nothing. Every
+ * `serve` is a run; requests go to the newest. Closing an older run settles it and nothing else; closing the newest - or
+ * a stretch with no request - stops the listener.
+ */
+export class NodeLocalServer {
+    #listening;
+    #current;
+    #timer;
+    #idleMs = 0;
+    async serve(handle, options) {
+        let settle = () => undefined;
+        const closed = new Promise((resolve) => {
+            settle = resolve;
+        });
+        const run = { handle, settle, maxBody: options.maxBody };
+        this.#idleMs = options.idleMs;
+        const listening = this.#listening ?? await this.#listen();
+        this.#current = run;
+        this.#restart();
+        let done = false;
+        const close = () => {
+            if (done)
+                return;
+            done = true;
+            if (this.#current === run) {
+                this.#stop();
+                return;
+            }
+            settle();
+        };
+        return { origin: listening.origin, closed, close };
+    }
+    async #listen() {
+        const server = createServer((incoming, outgoing) => {
+            this.#restart();
+            const run = this.#current;
+            if (run === undefined) {
+                outgoing.writeHead(503, { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store' });
+                outgoing.end('No project is being shown.');
+                return;
+            }
+            void answer(incoming, outgoing, run.handle, run.maxBody);
+        });
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(0, LOOPBACK, () => resolve());
+        });
+        const { port } = server.address();
+        this.#listening = { server, origin: `http://${LOOPBACK}:${port}` };
+        return this.#listening;
+    }
+    /** The newest run ends, and with it the listener: nothing is left to answer. */
+    #stop() {
+        if (this.#timer !== undefined)
+            clearTimeout(this.#timer);
+        const run = this.#current;
+        const listening = this.#listening;
+        this.#current = undefined;
+        this.#listening = undefined;
+        if (listening === undefined) {
+            run?.settle();
+            return;
+        }
+        listening.server.close(() => run?.settle());
+        listening.server.closeAllConnections();
+    }
+    #restart() {
+        if (this.#timer !== undefined)
+            clearTimeout(this.#timer);
+        this.#timer = setTimeout(() => this.#stop(), this.#idleMs);
+        this.#timer.unref();
+    }
+}
+async function answer(incoming, outgoing, handle, maxBody) {
+    const send = (response) => {
+        outgoing.writeHead(response.status, {
+            'Content-Type': response.type,
+            'Cache-Control': 'no-store',
+            'Referrer-Policy': 'no-referrer',
+            'X-Content-Type-Options': 'nosniff',
+            ...(response.location === undefined ? {} : { Location: response.location }),
+        });
+        outgoing.end(response.body, () => response.after?.());
+    };
+    try {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of incoming) {
+            size += chunk.length;
+            if (size > maxBody) {
+                send({ status: 413, type: 'text/plain; charset=utf-8', body: 'Too large.' });
+                incoming.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        }
+        const url = incoming.url ?? '/';
+        const headers = {};
+        for (const [name, value] of Object.entries(incoming.headers))
+            headers[name] = Array.isArray(value) ? value.join(', ') : value;
+        send(await handle({ method: incoming.method ?? 'GET', path: url.split('?')[0] ?? '/', headers, body: Buffer.concat(chunks).toString('utf8') }));
+    }
+    catch {
+        if (!outgoing.headersSent)
+            send({ status: 500, type: 'text/plain; charset=utf-8', body: 'Something went wrong.' });
+    }
+}

package/dist/infrastructure/node-text-input.js

@@ -0,0 +1,26 @@
+/** Reads a stream to its end, and gives up past a size rather than holding whatever arrives. */
+export class NodeTextInput {
+    #stream;
+    constructor(stream) {
+        this.#stream = stream;
+    }
+    async readAll(maxBytes) {
+        const chunks = [];
+        let size = 0;
+        try {
+            for await (const chunk of this.#stream) {
+                const buffer = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+                size += buffer.length;
+                if (size > maxBytes)
+                    return undefined;
+                chunks.push(buffer);
+            }
+        }
+        catch {
+            // A stream reports its failures as plain errors, and the port's promise is an answer, not an exception: a hook
+            // whose input broke off is told it was not checked (`specs/2026-09-16-when-an-agent-finishes.md` R8).
+            return undefined;
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    }
+}

package/dist/infrastructure/os-notifier.js

@@ -0,0 +1,21 @@
+import { execFile } from 'node:child_process';
+/**
+ * A system notification (`specs/2026-09-16-when-an-agent-finishes.md` R15). On macOS through `osascript`, which showed
+ * in the terminal interface and, once notifications were allowed, outside it (B4f); on another platform the answer is
+ * `false`, and the terminal notice is what remains.
+ *
+ * The words travel as arguments to the script, never inside its source, so nothing in them can be read as AppleScript.
+ */
+export class OsNotifier {
+    #platform;
+    constructor(platform) {
+        this.#platform = platform;
+    }
+    notify(title, text) {
+        if (this.#platform !== 'darwin')
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            execFile('osascript', ['-e', 'on run argv', '-e', 'display notification (item 2 of argv) with title (item 1 of argv)', '-e', 'end run', title, text], (error) => resolve(error === null));
+        });
+    }
+}

package/dist/infrastructure/osascript-folder-chooser.js

@@ -0,0 +1,53 @@
+import { chosenFolder, runProgram } from './folder-window.js';
+/** What AppleScript answers when the person closes the window with Cancel. */
+const CANCELLED = /-128\b/;
+/**
+ * The script: forward through AppKit, which is quick (VB1), then Standard Additions' folder window, headed by the first
+ * argument and opened at the second where there is one. Its answer is the folder's path.
+ */
+const CHOOSE_FOLDER = [
+    'function run(argv) {',
+    "  ObjC.import('AppKit');",
+    '  $.NSApplication.sharedApplication.activateIgnoringOtherApps(true);',
+    '  const app = Application.currentApplication();',
+    '  app.includeStandardAdditions = true;',
+    '  const options = { withPrompt: argv[0] };',
+    '  if (argv[1]) options.defaultLocation = Path(argv[1]);',
+    '  return app.chooseFolder(options).toString();',
+    '}',
+].join('\n');
+/**
+ * The folder window of macOS, opened through `osascript` (`.ai/specs/2026-09-27-which-project.md` V12, VD3), in front
+ * of the browser that asked for it. The prompt and the folder it starts in travel as arguments to the script, never inside
+ * its source, as `OsNotifier`'s words do. The answer is the folder's path with every link followed. Elsewhere there is no
+ * window this code has measured, and none is offered.
+ *
+ * VB1, measured 2026-09-28 on the maintainer's computer, from the moment `osascript` is started to the moment its window
+ * is on screen: AppleScript's `activate` then `choose folder` took 2.5 s and the window was still not in front; without
+ * `activate` 0.5 s, behind the browser; JavaScript for Automation bringing itself forward through AppKit, 0.6 s and in
+ * front. It is the last. The window starts in the folder it is given: left to itself it opens where it was last left,
+ * which on that computer is a folder iCloud keeps.
+ */
+export class OsascriptFolderChooser {
+    available;
+    #run;
+    constructor(platform, run = (args) => runProgram('osascript', args)) {
+        this.available = platform === 'darwin';
+        this.#run = run;
+    }
+    async choose(prompt, startIn) {
+        if (!this.available)
+            return { failed: 'This computer has no folder window agentwhy can open.' };
+        let answer;
+        try {
+            answer = await this.#run(['-l', 'JavaScript', '-e', CHOOSE_FOLDER, prompt, ...(startIn === undefined ? [] : [startIn])]);
+        }
+        catch (error) {
+            return { failed: error instanceof Error ? error.message : String(error) };
+        }
+        if (answer.code !== 0)
+            return CANCELLED.test(answer.stderr) ? { cancelled: true } : { failed: answer.stderr.trim() || 'The folder window could not open.' };
+        const path = answer.stdout.trim();
+        return path === '' ? { cancelled: true } : chosenFolder(path);
+    }
+}

package/dist/infrastructure/powershell-folder-chooser.js

@@ -0,0 +1,78 @@
+import { chosenFolder, runProgram } from './folder-window.js';
+/** What the script exits with when the person closes the window with Cancel. */
+const CANCELLED = 3;
+/** Text as the script receives it: base64 of its UTF-8, so nothing the page says is ever read as PowerShell. */
+function encoded(text) {
+    return Buffer.from(text, 'utf8').toString('base64');
+}
+/**
+ * The script: Windows Forms' folder window, headed by the prompt and opened at the folder given where it is there, owned
+ * by an unseen window that stays on top, so it is not opened behind the browser that asked for it. The folder chosen is
+ * written as base64 of its UTF-8, since the console's code page would change a name that is not plain ASCII; Cancel exits
+ * with 3, and anything that went wrong is written after `failed:` - an error PowerShell wrote itself would reach stderr as
+ * serialized XML, which says nothing to a person.
+ */
+function script(prompt, startIn) {
+    return [
+        "$ErrorActionPreference = 'Stop'",
+        "$ProgressPreference = 'SilentlyContinue'",
+        'try {',
+        '  Add-Type -AssemblyName System.Windows.Forms',
+        '  [System.Windows.Forms.Application]::EnableVisualStyles()',
+        `  $prompt = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encoded(prompt)}'))`,
+        `  $start = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encoded(startIn ?? '')}'))`,
+        '  $owner = New-Object System.Windows.Forms.Form',
+        '  $owner.TopMost = $true',
+        '  $owner.ShowInTaskbar = $false',
+        '  $dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
+        '  $dialog.Description = $prompt',
+        '  $dialog.ShowNewFolderButton = $true',
+        "  if ($start -ne '' -and (Test-Path -LiteralPath $start -PathType Container)) { $dialog.SelectedPath = $start }",
+        '  $result = $dialog.ShowDialog($owner)',
+        '  $owner.Dispose()',
+        `  if ($result -ne [System.Windows.Forms.DialogResult]::OK) { exit ${CANCELLED} }`,
+        '  [Console]::Out.Write([Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($dialog.SelectedPath)))',
+        '  exit 0',
+        '} catch {',
+        "  [Console]::Out.Write('failed:' + $_.Exception.Message)",
+        '  exit 1',
+        '}',
+    ].join('\n');
+}
+/**
+ * The folder window of Windows (`.ai/specs/2026-09-27-which-project.md` V12; VD3 amended 2026-09-28: "write it for Windows
+ * too"), opened through Windows PowerShell, which every Windows 10 and 11 has. The script travels as `-EncodedCommand` -
+ * UTF-16 in base64, as PowerShell reads it - and the prompt and the folder it starts in inside it as base64 too, so
+ * nothing the page sent is spliced into code.
+ *
+ * VB7, not measured: whether the window comes in front of the browser, how long PowerShell takes to open it, and what
+ * a folder with a name that is not plain ASCII comes back as. WSL is not this: there the platform is Linux, and no window
+ * is offered.
+ */
+export class PowershellFolderChooser {
+    available;
+    #run;
+    constructor(platform, run = (args) => runProgram('powershell.exe', args)) {
+        this.available = platform === 'win32';
+        this.#run = run;
+    }
+    async choose(prompt, startIn) {
+        if (!this.available)
+            return { failed: 'This computer has no folder window agentwhy can open.' };
+        let answer;
+        try {
+            answer = await this.#run(['-NoProfile', '-NonInteractive', '-STA', '-ExecutionPolicy', 'Bypass',
+                '-EncodedCommand', Buffer.from(script(prompt, startIn), 'utf16le').toString('base64')]);
+        }
+        catch (error) {
+            return { failed: error instanceof Error ? error.message : String(error) };
+        }
+        if (answer.code === CANCELLED)
+            return { cancelled: true };
+        const written = answer.stdout.trim();
+        if (answer.code !== 0)
+            return { failed: written.startsWith('failed:') ? written.slice('failed:'.length).trim() || 'The folder window could not open.' : answer.stderr.trim() || 'The folder window could not open.' };
+        const path = Buffer.from(written, 'base64').toString('utf8');
+        return path === '' ? { cancelled: true } : chosenFolder(path);
+    }
+}

package/dist/infrastructure/real-directory.js

@@ -0,0 +1,18 @@
+import { realpathSync } from 'node:fs';
+/**
+ * A directory as the system names it, every link followed: what a shell's working directory is given as, where `HOME`
+ * may reach the same directory through a link (`which-project.md` V6). Where a link cannot be followed - the path is
+ * missing, unreadable or a loop - the path as it was given, so a home that cannot be read is compared as it is written.
+ * An empty path names no directory and stays empty: `realpathSync` would resolve it to the directory the process
+ * stands in, and every run would be standing in its home.
+ */
+export function realDirectory(path) {
+    if (path === '')
+        return path;
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}

package/dist/infrastructure/stream-printer.js

@@ -0,0 +1,11 @@
+/** Writes to a stream the shell owns. The shell decides which one; nothing here reads `process`. */
+export class StreamPrinter {
+    #output;
+    constructor(output) {
+        this.#output = output;
+    }
+    write(text) {
+        if (text !== '')
+            this.#output.write(text);
+    }
+}

package/dist/infrastructure/terminal-banner.js

@@ -0,0 +1,19 @@
+/**
+ * The lines drawn above the first question a command asks, and above none of the ones after it. `init` asks up to
+ * three things in a row; the mark belongs at the top of that conversation, not before every prompt. One banner is
+ * shared by the prompts of one command, and the first of them to be asked draws it.
+ */
+export class TerminalBanner {
+    #lines;
+    #drawn = false;
+    constructor(lines = []) {
+        this.#lines = lines;
+    }
+    /** Writes the lines the first time it is called, and nothing on any call after that. */
+    drawOn(output) {
+        if (this.#drawn || this.#lines.length === 0)
+            return;
+        this.#drawn = true;
+        output.write(`${this.#lines.join('\n')}\n`);
+    }
+}

package/dist/ports/agentwhy-invocation.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/alert-store.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/asker.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/browser.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/checked-store.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/chooser.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/directory-reader.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/file-access-error.js

@@ -0,0 +1,11 @@
+/** The only failure a file port reports. Implementations translate their own errors into it. */
+export class FileAccessError extends Error {
+    failure;
+    path;
+    constructor(failure, path, options) {
+        super(`${failure}: ${path}`, options);
+        this.name = 'FileAccessError';
+        this.failure = failure;
+        this.path = path;
+    }
+}

package/dist/ports/file-reader.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/file-tail-reader.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/file-writer.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/folder-chooser.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/local-server.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/mark-store.js

@@ -0,0 +1,10 @@
+/**
+ * What a person says they did about a file (R31; `for-people-who-build-with-ai.md` F25, F50): the keys it held were
+ * replaced, a template's values are placeholders, what could be done about a file whose contents cannot be changed was
+ * done, or the file holds nothing private.
+ */
+export const MARK_RESULTS = ['rotated', 'not-secret', 'handled', 'not-private'];
+/** A result read from a file, a flag or a request, which this version knows. */
+export function isMarkResult(value) {
+    return MARK_RESULTS.includes(value);
+}