@ashulab/carrier 0.0.0-stage → 0.1.0

package/dist/terminal/cli/control-client.js

@@ -0,0 +1,94 @@
+import { connect } from 'node:net';
+import { socketPathFits } from '../../control/server.js';
+export class ControlUnreachable extends Error {
+    reason;
+    /** For 'incompatible': the protocol the hello announced, when it announced one. */
+    protocol;
+    // No parameter properties: Node strips types at runtime and cannot run that syntax.
+    constructor(reason, protocol) {
+        super(reason);
+        this.reason = reason;
+        this.protocol = protocol;
+    }
+}
+// Errors that mean no Carrier is listening there; any other one (a permission, say) is a socket that did not answer.
+const nobodyListening = new Set(['ENOENT', 'ECONNREFUSED', 'ENOTSOCK', 'ENAMETOOLONG']);
+/**
+ * Connects to a running Carrier's control socket and reads its hello. `timeoutMs` bounds the hello and each request.
+ * Rejects with a `ControlUnreachable`; the path is never tried when it does not fit the socket limit.
+ */
+export function connectControl(path, { timeoutMs = 5000 } = {}) {
+    if (socketPathFits(path).fits === false)
+        return Promise.reject(new ControlUnreachable('not-running'));
+    return new Promise((resolve, reject) => {
+        const socket = connect(path);
+        socket.setEncoding('utf8');
+        const pending = new Map();
+        let hello;
+        let nextId = 1;
+        let buffer = '';
+        const helloTimer = setTimeout(() => fail('no-answer'), timeoutMs);
+        const fail = (reason, protocol) => {
+            clearTimeout(helloTimer);
+            socket.destroy();
+            reject(new ControlUnreachable(reason, protocol));
+        };
+        const settle = (id, finish) => {
+            const entry = pending.get(id);
+            if (entry === undefined)
+                return;
+            clearTimeout(entry.timer);
+            pending.delete(id);
+            finish(entry);
+        };
+        const onLine = (line) => {
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                return hello === undefined ? fail('incompatible') : undefined;
+            }
+            if (hello === undefined) {
+                if (message?.event !== 'hello' || message.protocol !== 1)
+                    return fail('incompatible', message?.event === 'hello' ? message.protocol : undefined);
+                clearTimeout(helloTimer);
+                hello = message;
+                return resolve({ hello, request, close: () => socket.destroy() });
+            }
+            // the server answers in order, so a reply without an id (a request it could not read) belongs to the oldest one
+            const id = message.id ?? pending.keys().next().value;
+            if (id === undefined)
+                return;
+            settle(id, (entry) => (message.ok === true ? entry.resolve(message.data) : entry.reject(new Error(String(message.error)))));
+        };
+        socket.on('data', (chunk) => {
+            buffer += chunk;
+            for (let end = buffer.indexOf('\n'); end >= 0; end = buffer.indexOf('\n')) {
+                const line = buffer.slice(0, end);
+                buffer = buffer.slice(end + 1);
+                onLine(line);
+            }
+        });
+        socket.on('error', (error) => {
+            if (hello === undefined)
+                fail(nobodyListening.has(error.code ?? '') ? 'not-running' : 'no-answer');
+        });
+        socket.on('close', () => {
+            if (hello === undefined)
+                return fail('no-answer');
+            for (const id of [...pending.keys()])
+                settle(id, (entry) => entry.reject(new ControlUnreachable('no-answer')));
+        });
+        function request(cmd, fields = {}) {
+            if (socket.destroyed)
+                return Promise.reject(new ControlUnreachable('no-answer'));
+            return new Promise((resolveRequest, rejectRequest) => {
+                const id = nextId++;
+                const timer = setTimeout(() => settle(id, (entry) => entry.reject(new ControlUnreachable('no-answer'))), timeoutMs);
+                pending.set(id, { resolve: resolveRequest, reject: rejectRequest, timer });
+                socket.write(`${JSON.stringify({ ...fields, id, cmd })}\n`);
+            });
+        }
+    });
+}

package/dist/terminal/cli/detached.js

@@ -0,0 +1,41 @@
+import { spawn } from 'node:child_process';
+import { closeSync, mkdirSync, openSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { CliError } from './cli-error.js';
+import { connectControl } from './control-client.js';
+const POLL_MS = 250;
+const GIVE_UP_MS = 15_000;
+const LOG_TAIL_LINES = 20;
+/** The pid of whoever answers on this socket, if one does. */
+export async function pidAt(socketPath) {
+    try {
+        const client = await connectControl(socketPath, { timeoutMs: POLL_MS });
+        client.close();
+        return client.hello.pid;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Starts this program as a detached run (ADR 0010): in its own session, its output in `logPath` (replaced at each start).
+ * Returns the pid once `socketPath` answers; throws a CliError with the end of the log when it exits or stays silent.
+ * `args` are absolute where they name files: the child does not share this process's working directory.
+ */
+export async function startDetached({ label, args, socketPath, logPath }) {
+    mkdirSync(dirname(logPath), { recursive: true });
+    const logFd = openSync(logPath, 'w');
+    let exited = false;
+    const child = spawn(process.execPath, [...process.execArgv, process.argv[1], ...args], { detached: true, stdio: ['ignore', logFd, logFd] });
+    closeSync(logFd);
+    child.on('exit', () => (exited = true));
+    child.unref();
+    for (const deadline = Date.now() + GIVE_UP_MS; exited === false && Date.now() < deadline; await sleep(POLL_MS)) {
+        const pid = await pidAt(socketPath);
+        if (pid !== undefined)
+            return pid;
+    }
+    const tail = readFileSync(logPath, 'utf8').trimEnd().split('\n').slice(-LOG_TAIL_LINES);
+    throw new CliError(1, exited ? `${label} exited before it was ready:` : `${label} did not answer within ${GIVE_UP_MS / 1000} seconds:`, ...tail, `Log: ${logPath}`);
+}

package/dist/terminal/cli/interrupt.js

@@ -0,0 +1,39 @@
+import { createScopedLogger } from '@ashulab/universal-logger';
+const log = createScopedLogger('cli');
+async function stopEngine({ engine, close }, timeoutMs) {
+    let code = 0;
+    let timer;
+    const limit = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`engine did not stop within ${timeoutMs} ms`)), timeoutMs);
+    });
+    try {
+        await Promise.race([engine.shutdown(), limit]);
+    }
+    catch (error) {
+        log.error('shutdown failed', error);
+        code = 1;
+    }
+    finally {
+        clearTimeout(timer);
+        close();
+    }
+    return code;
+}
+/**
+ * The one shutdown: stop the engine without waiting for stages, then free the instance lock and exit with 0 (1 when the
+ * engine failed to stop or did not within `timeoutMs`: its executions stay `running` and the next start recovers them).
+ * Callable from anywhere, not only from a signal handler; calling it again returns the shutdown already under way.
+ */
+export function createShutdown(target, { timeoutMs = 20_000, exit = process.exit } = {}) {
+    let running;
+    const shutdown = () => (running ??= stopEngine(target, timeoutMs).then(exit));
+    return Object.defineProperty(shutdown, 'running', { get: () => running !== undefined });
+}
+// Ctrl+C, SIGTERM (kill) and SIGHUP (closed terminal) all run the one shutdown; a second signal while it runs exits at once.
+export function stopOnSigint(target, { exit = process.exit, ...options } = {}) {
+    const shutdown = createShutdown(target, { ...options, exit });
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+        process.on(signal, () => (shutdown.running ? exit(130) : void shutdown()));
+    }
+    return shutdown;
+}

package/dist/terminal/cli/main.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// The entry point: read the command line, hand it to the command, turn a CliError into an exit code. Nothing else lives here.
+import { resolve } from 'node:path';
+import { carrierHome } from '../../config/default-path.js';
+import { parseCli, usage } from './args.js';
+import { CliError } from './cli-error.js';
+import { configPathFor, loadConfigFile, noConfig } from './config-file.js';
+// Not console.*: once logging is installed that goes to the log file, and these are for the person at the terminal.
+const fail = (code, ...lines) => {
+    process.stderr.write(`${lines.join('\n')}\n`);
+    process.exit(code);
+};
+const cli = parseCli(process.argv.slice(2));
+if (!cli.ok)
+    fail(2, cli.message, '', usage());
+else if (cli.flags.help) {
+    process.stdout.write(`${usage()}\n`);
+    process.exit(0);
+}
+else if (cli.flags.version) {
+    process.stdout.write(`${(await import('../../control/server.js')).version}\n`); // the value both hellos carry
+    process.exit(0);
+}
+else {
+    try {
+        const configPath = configPathFor(cli.flags.config);
+        const folder = carrierHome(); // the one read of CARRIER_HOME; everything below is handed it
+        let exit;
+        switch (cli.command) {
+            case 'schema':
+                (await import('./commands/schema.js')).schemaCommand();
+                break;
+            case 'init':
+                exit = await (await import('./commands/init.js')).initCommand(cli.flags, folder);
+                break;
+            case 'doctor':
+                if (configPath === undefined)
+                    throw noConfig('Usage: carrier doctor --config <path>');
+                exit = await (await import('./commands/doctor.js')).doctorCommand(loadConfigFile(configPath), folder, cli.flags.json === true);
+                break;
+            case 'start':
+                if (configPath === undefined)
+                    throw noConfig('Usage: carrier start --config <path>');
+                loadConfigFile(configPath); // refuses a config the detached run would only fail on
+                exit = await (await import('./commands/start.js')).startCommand(folder, resolve(configPath));
+                break;
+            case 'status':
+                exit = await (await import('./commands/status.js')).statusCommand(folder);
+                break;
+            case 'watch':
+                exit = await (await import('./commands/watch.js')).watchCommand(folder);
+                break;
+            case 'stop':
+            case 'pause':
+            case 'resume':
+            case 'check':
+                exit = await (await import('./commands/control.js')).controlCommand(cli.command, folder);
+                break;
+            case 'restart':
+                exit = await (await import('./commands/restart.js')).restartCommand(folder, cli.target, { author: cli.flags.author, reviewer: cli.flags.reviewer });
+                break;
+            case 'chat':
+            case 'chat-host':
+                // the chat runs from the Carrier folder alone (ADR 0016), not from an engine config
+                if (cli.flags.config !== undefined)
+                    throw new CliError(2, `carrier ${cli.command} takes no --config: it runs from the Carrier folder (CARRIER_HOME, else ~/.carrier)`);
+                if (cli.command === 'chat')
+                    exit = await (await import('./commands/chat.js')).chatCommand(cli.flags);
+                else
+                    await (await import('./commands/chat-host.js')).chatHostCommand(); // runs until stopped
+                break;
+            default:
+                if (configPath === undefined)
+                    throw noConfig(usage(), '');
+                await (await import('./commands/run.js')).runCommand(loadConfigFile(configPath), folder); // runs until Ctrl+C
+        }
+        if (exit !== undefined)
+            process.exit(exit); // otherwise the command keeps the process alive (running), or has nothing left to do
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            fail(error.code, ...error.lines);
+        throw error;
+    }
+}

package/dist/terminal/cli/open-url.js

@@ -0,0 +1,9 @@
+import { spawn } from 'node:child_process';
+// Only GitHub issue and PR pages, whatever the row says: the URL goes to `open`, which would take anything.
+const githubPage = /^https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/(issues|pull)\/\d+$/;
+/** Opens a GitHub issue or PR page in the browser. */
+export function openUrl(url) {
+    if (!githubPage.test(url))
+        return;
+    spawn('open', [url], { stdio: 'ignore', detached: true }).on('error', () => { }).unref(); // macOS; where `open` is missing nothing happens
+}

package/dist/terminal/dashboard/dashboard.js

@@ -0,0 +1,204 @@
+import { formatDuration } from '../../format/duration.js';
+import { printable } from './printable.js';
+import { finishedSections, itemsOf, maxListed, waitingEpic } from './ui-state.js';
+import { detailOf, historyLine } from './history.js';
+const codes = { bold: 1, dim: 2, inverse: 7, red: 31, green: 32, yellow: 33, cyan: 36 };
+// eslint-disable-next-line no-control-regex
+const ansi = /\x1b\[[0-9;]*m/g;
+export const visibleLength = (text) => text.replace(ansi, '').length;
+/** Cuts a styled line to `columns` visible characters (a wrapped line would break the cursor-up count of the redraw). */
+export function fit(line, columns) {
+    if (visibleLength(line) <= columns)
+        return line;
+    let out = '';
+    let shown = 0;
+    let open = false; // a style is on and not yet reset
+    for (const part of line.split(/(\x1b\[[0-9;]*m)/)) {
+        if (/^\x1b\[[0-9;]*m$/.test(part)) {
+            out += part;
+            open = part !== '\x1b[0m';
+        }
+        else {
+            const room = columns - shown;
+            out += part.slice(0, Math.max(0, room));
+            shown += Math.min(part.length, Math.max(0, room));
+        }
+    }
+    return open ? `${out}\x1b[0m` : out;
+}
+const stages = ['ship', 'review', 'fix'];
+/**
+ * The panel for a terminal: header, slots, then one section per kind of epic (running, queued, needing a person, ready
+ * for test). Pure: the same snapshot gives the same lines; `color: false` gives them with no ANSI.
+ */
+export function renderDashboard(s, { columns = 80, color = true, ui, logLines = [], activity, detail, quit = 'stop', canChoose = false } = {}) {
+    const paint = (text, ...styles) => (color && styles.length > 0 ? `\x1b[${styles.map((x) => codes[x]).join(';')}m${text}\x1b[0m` : text);
+    const width = Math.min(Math.max(columns, 50), 80) - 2;
+    const ago = (at) => (at === null ? 'a while' : `${formatDuration(Math.max(0, s.now - at))} ago`);
+    const up = `up ${formatDuration(s.now - s.startedAt)}`;
+    const title = '◆ CARRIER ';
+    const rule = '─'.repeat(Math.max(3, width - title.length - up.length - 2));
+    const lines = [];
+    const add = (text = '') => lines.push(text);
+    add(` ${paint(title, 'bold', 'cyan')}${paint(rule, 'dim')} ${paint(up, 'dim')}`);
+    const wait = s.nextCheckAt === null ? 'starting' : s.nextCheckAt <= s.now ? 'checking now…' : `next check in ${formatDuration(s.nextCheckAt - s.now)}`;
+    add(`   ${paint(`watching ${s.repos} repo${s.repos === 1 ? '' : 's'} · ${wait}`, 'dim')}`);
+    if (s.problem)
+        add(`   ${paint(`▲ ${printable(s.problem)}`, 'yellow')}`);
+    if (s.paused)
+        add(`   ${paint('▲ PAUSED: new epics wait in the queue (p resumes)', 'yellow')}`);
+    add();
+    const dots = Array.from({ length: s.slots.total }, (_, i) => (i < s.slots.busy ? paint('●', 'green') : paint('○', 'dim'))).join('');
+    add(`   Slots  ${dots}   ${s.slots.busy} of ${s.slots.total} busy`);
+    const section = (name, ...styles) => {
+        add();
+        add(` ${paint(name, 'bold', ...styles)}`);
+    };
+    const selected = (repo, issue) => ui?.selected === `${repo}#${issue}`;
+    // An issue title is written by someone else: printable, and `fit` cuts the line. A missing one leaves the row as it was.
+    const titled = (title) => (title ? `  ${printable(title)}` : '');
+    const pointer = paint('›', 'bold', 'cyan');
+    // The first line of the selected row carries the pointer where the others have the bar or the indent.
+    const lead = (repo, issue, plain) => (selected(repo, issue) ? ` ${pointer} ` : plain);
+    // Only the keys that do something now: no ↑↓ with one row, no logs for a row with no agent.
+    // Packed into as many lines as the width needs: a line cut at the edge loses the keys at its end (q among them).
+    const hints = () => {
+        const items = itemsOf(s);
+        const current = items.find((i) => i.key === ui?.selected);
+        const waiting = canChoose && ui?.selected && waitingEpic(s, ui.selected);
+        const parts = [items.length > 1 && '↑↓ select', current && 'enter open', current?.executionId && 'l logs', waiting && 'o options · a automatic', 'r check now', s.paused ? 'p resume' : 'p pause', '? help', quit === 'stop' ? 'q quit' : 'q leave'].filter(Boolean);
+        return parts.reduce((rows, part) => {
+            const last = rows.at(-1);
+            if (last !== undefined && visibleLength(`${last} · ${part}`) <= width - 1)
+                rows[rows.length - 1] = `${last} · ${part}`;
+            else
+                rows.push(part);
+            return rows;
+        }, []);
+    };
+    const footer = () => {
+        if (ui?.toast)
+            add(`   ${paint(`› ${printable(ui.toast.text)}`, 'cyan')}`);
+        add();
+        const exit = quit === 'stop' ? 'q quit' : 'q leave';
+        const rows = ui === undefined ? [quit === 'stop' ? 'Ctrl+C stops it' : 'Ctrl+C leaves it running'] : ui.mode === 'dashboard' ? hints() : ui.mode === 'choose' ? [`↑↓ role · ←→ option · enter start · esc cancel · ${exit}`] : [`esc back · ${exit}`];
+        for (const row of rows)
+            add(`   ${paint(row, 'dim')}`);
+    };
+    if (ui?.mode === 'help') {
+        section('KEYS');
+        for (const [key, what] of [['↑ ↓ j k', 'select an epic'], ['enter', 'open its PR (or issue) in the browser'], ['l', 'agent output of the selected epic'], ...(canChoose ? [['o', 'choose the options of the selected epic that is waiting'], ['a', 'start it on its default options now']] : []), ['r', 'check GitHub now'], ['p', 'pause or resume taking new epics'], ['?', 'this help'], ['esc', 'back'], ['q', quit === 'stop' ? 'stop Carrier (same as Ctrl+C)' : 'leave (Carrier keeps running)']])
+            add(`   ${paint(key.padEnd(9), 'bold', 'cyan')} ${what}`);
+        footer();
+        return lines.map((line) => fit(line, width + 2));
+    }
+    if (ui?.mode === 'logs') {
+        const target = [...s.epics, ...s.done, ...(s.finished ?? [])].find((e) => selected(e.repo, e.issue));
+        section(`AGENT OUTPUT · ${ui.selected ?? ''}${target?.executionId ? ` · ${target.executionId.slice(0, 8)}` : ''}`, 'cyan');
+        if (logLines.length === 0)
+            add(paint('   (nothing written yet)', 'dim'));
+        for (const l of logLines)
+            add(`   ${printable(l)}`);
+        footer();
+        return lines.map((line) => fit(line, width + 2));
+    }
+    const running = s.epics.filter((e) => e.status === 'running');
+    const needsYou = s.epics.filter((e) => e.status === 'needs_human');
+    const card = (e, first) => {
+        const chosen = selected(e.repo, e.issue);
+        const bar = chosen ? paint('▌', 'bold', 'cyan') : paint('┃', 'dim');
+        const choice = e.options?.choiceDeadline;
+        const chain = choice != null ? paint(`waiting for its choice · starts in ${formatDuration(choice - s.now)}`, 'dim') : e.stage === null ? paint('starting', 'dim') : stages.map((st) => (st === e.stage ? paint(`[${st}]`, 'bold', 'cyan') : paint(st, 'dim'))).join(paint(' ▸ ', 'dim'));
+        const round = e.round === null ? '' : ` · round ${Array.from({ length: e.maxReviews }, (_, i) => (i < e.round ? '●' : '○')).join('')}`;
+        if (!first)
+            add();
+        add(chosen ? ` ${pointer}${paint(` ${e.repo} #${e.issue} `, 'bold', 'inverse')}${titled(e.title)}` : ` ${bar} ${paint(`${e.repo} #${e.issue}`, 'bold')}${titled(e.title)}`); // the selected card's title is a highlighted label
+        if (chosen && ui?.mode === 'choose' && ui.choice) {
+            add(` ${bar} ${paint(`choose the options · ${formatDuration(choice - s.now)} left`, 'dim')}`);
+            for (const role of ['author', 'reviewer'])
+                add(` ${bar} ${ui.choice.role === role ? pointer : ' '} ${role.padEnd(8)} ${paint(`‹ ${ui.choice[role]} ›`, ui.choice.role === role ? 'bold' : 'dim')}`);
+        }
+        else
+            add(` ${bar} ${chain}${round}`);
+        if (choice != null && !(chosen && ui?.mode === 'choose' && ui.choice))
+            for (const role of ['author', 'reviewer'])
+                add(` ${bar} ${paint(`${role} ${e.options[role]}`, 'dim')}`); // one per line: long option names do not fit two roles in 50 columns
+        const history = detail && detailOf(detail, e);
+        if (history && history.length > 0)
+            add(` ${bar} ${historyLine(history, s.now, paint, width - 4)}`);
+        const blockers = e.blockers > 0 ? paint(` · blockers ${e.blockers}`, 'yellow') : '';
+        const slices = e.slices && e.slices.total > 0 ? ` · slices ${e.slices.done}/${e.slices.total}` : '';
+        add(` ${bar} ${formatDuration(s.now - e.stageSince)} in stage · ${e.lastActivityAt === null ? 'no activity yet' : `active ${ago(e.lastActivityAt)}`}${blockers}${slices}`);
+        add(` ${bar} ${paint(e.prUrl ?? e.issueUrl, 'dim')}`);
+        if (e.lastError)
+            add(` ${bar} ${paint(`error: ${printable(e.lastError)}`, 'red')}`);
+        // What the agent is doing: three lines for the selected card, one for the others.
+        const now = e.executionId && activity ? activity(e.executionId, chosen ? 3 : 1) : [];
+        now.forEach((l, i) => add(` ${bar} ${i === 0 ? paint('now', 'dim') : '   '}  ${paint(printable(l), 'dim')}`));
+        // The open blockers of a review or fix, by title, listed the way the queue is.
+        const titles = e.stage === 'review' || e.stage === 'fix' ? (e.blockerTitles ?? []) : [];
+        for (const t of titles.slice(0, 3))
+            add(` ${bar}   ${paint(`· ${printable(t)}`, 'yellow')}`);
+        if (titles.length > 0 && e.blockers > 3)
+            add(` ${bar}   ${paint(`… and ${e.blockers - 3} more`, 'dim')}`);
+    };
+    if (running.length > 0) {
+        section('RUNNING', 'cyan');
+        running.forEach((e, i) => card(e, i === 0));
+    }
+    if (s.queue.length > 0) {
+        section(`QUEUED ${s.queue.length}`);
+        for (const q of s.queue.slice(0, maxListed))
+            add(`${lead(q.repo, q.issue, '   ')}${q.repo} #${q.issue}${titled(q.title)}`);
+        if (s.queue.length > maxListed)
+            add(paint(`   … and ${s.queue.length - maxListed} more`, 'dim'));
+    }
+    if (needsYou.length > 0) {
+        section('NEEDS YOU ▲', 'yellow');
+        for (const e of needsYou) {
+            add(`${lead(e.repo, e.issue, '   ')}${paint(`${e.repo} #${e.issue}`, 'bold')}${titled(e.title)}`);
+            if (e.needsHumanReason)
+                add(`   ${printable(e.needsHumanReason)}`);
+            const history = detail && detailOf(detail, e);
+            if (history && history.length > 0)
+                add(`   ${historyLine(history, s.now, paint, width - 3)}`);
+            add(`   ${paint(e.prUrl ?? e.issueUrl, 'dim')}`);
+            if (e.lastError)
+                add(`   ${paint(`error: ${printable(e.lastError)}`, 'red')}`);
+        }
+    }
+    // last: a cut title costs less than a cut PR number or time
+    const row = (d) => `${lead(d.repo, d.issue, '   ')}${d.repo} #${d.issue}${d.prNumber === null ? '' : ` · PR #${d.prNumber}`} · ${ago(d.finishedAt)}${titled(d.title)}`;
+    if (s.done.length > 0) {
+        section('READY FOR TEST ✔', 'green');
+        for (const d of s.done) {
+            add(row(d));
+            const history = detail && detailOf(detail, d);
+            if (history && history.length > 0)
+                add(`   ${historyLine(history, s.now, paint, width - 3)}`);
+        }
+    }
+    // Only while GitHub refused some repo's last check; a healthy Carrier shows nothing extra.
+    const refused = (s.watched ?? []).filter((w) => !w.ok);
+    if (refused.length > 0) {
+        section('REPOS GITHUB REFUSED ▲', 'yellow');
+        for (const w of refused)
+            add(`   ${paint(w.repo, 'bold')}  ${paint(printable(w.error ?? 'the last check failed'), 'red')}`);
+    }
+    if (s.epics.length === 0 && s.queue.length === 0 && s.done.length === 0) {
+        add();
+        add(`   ${paint('Idle.', 'bold')} Mark an epic ${paint('solve:epic:ready', 'cyan')} in a watched repo to start one.`);
+    }
+    for (const { name, rows, more } of finishedSections(s)) {
+        section(name, 'dim');
+        for (const f of rows) {
+            add(row(f));
+            if (f.cancelReason)
+                add(`   ${printable(f.cancelReason)}`);
+        }
+        if (more > 0)
+            add(paint(`   +${more} more`, 'dim'));
+    }
+    footer();
+    return lines.map((line) => fit(line, width + 2));
+}

package/dist/terminal/dashboard/history.js

@@ -0,0 +1,38 @@
+import { formatDuration } from '../../format/duration.js';
+// ponytail: entries of epics that left the panel stay until the provider is dropped; a prune if a long run ever shows it.
+const caches = new WeakMap();
+/** An epic's detail, asked again only when its stage, round, status, blockers or latest execution changed (a finished epic has only the last). */
+export function detailOf(provider, e) {
+    const cache = caches.get(provider) ?? new Map();
+    caches.set(provider, cache);
+    const key = `${e.repo}#${e.issue}`;
+    const signature = [e.stage, e.round, e.status, e.blockers, e.executionId].join('|');
+    const hit = cache.get(key);
+    if (hit?.signature === signature)
+        return hit.detail;
+    const detail = provider(e.repo, e.issue);
+    if (detail === undefined)
+        return hit?.detail ?? null;
+    cache.set(key, { signature, detail });
+    return detail;
+}
+const marks = { completed: ['✓', 'green'], changes_requested: ['↻ changes', 'yellow'], needs_human: ['▲ needs you', 'yellow'] };
+/** "ship ✓ 14m · review ↻ changes round 1 4m · [fix] 2m": oldest first, the running stage in brackets; the oldest are dropped to fit `width`. */
+export function historyLine(sessions, now, paint, width) {
+    const parts = [...sessions].reverse().map((x) => {
+        const took = formatDuration((x.finishedAt ?? now) - x.startedAt);
+        const round = x.round === null ? '' : ` round ${x.round}`;
+        if (x.status === 'running')
+            return { shown: `[${x.stage}]${round} ${took}`, styled: paint(`[${x.stage}]`, 'bold', 'cyan') + `${round} ${took}` };
+        const [mark, color] = x.failure ? [`✗ ${x.failure.kind}`, 'yellow'] : x.result ? marks[x.result.outcome] : ['', 'dim'];
+        return { shown: `${x.stage}${mark ? ` ${mark}` : ''}${round} ${took}`, styled: `${x.stage}${mark ? ` ${paint(mark, color)}` : ''}${round} ${took}` };
+    });
+    const separator = ' · ';
+    const length = (list) => list.reduce((n, p) => n + p.shown.length, 0) + separator.length * (list.length - 1);
+    let dropped = false;
+    while (parts.length > 1 && length(parts) + (dropped ? 2 : 0) > width) {
+        parts.shift();
+        dropped = true;
+    }
+    return `${dropped ? '… ' : ''}${parts.map((p) => p.styled).join(paint(separator, 'dim'))}`;
+}

package/dist/terminal/dashboard/interactive.js

@@ -0,0 +1,60 @@
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { startKeys } from './keys.js';
+import { startPanel } from './panel.js';
+import { renderDashboard } from './dashboard.js';
+import { initialUi, itemsOf, onKey, settle, toastFor } from './ui-state.js';
+const logRows = 18;
+const log = createScopedLogger('panel');
+/** The engine's expected refusals of `chooseOptions`, in the panel's words. */
+const refusalWords = {
+    'not waiting': 'Already started on its defaults',
+    'unknown option': 'That option is not in the configuration',
+    'unknown epic': 'That epic is gone',
+    'github unavailable': 'GitHub is not answering: it starts on its own when it does',
+};
+/**
+ * The dashboard with keys: select an epic, open it, read its agent's output, check GitHub now, pause intake, choose the options of a waiting epic, quit.
+ * Every key redraws at once instead of waiting for the next second. Returns the stop function.
+ */
+export function startInteractivePanel({ snapshot, out, stdin, controls, now = Date.now, intervalMs, quit }) {
+    let ui = initialUi;
+    const canChoose = controls.chooseOptions !== undefined;
+    const panel = startPanel(snapshot, out, intervalMs, (s, columns) => {
+        ui = settle(ui, s, now());
+        const executionId = ui.mode === 'logs' ? itemsOf(s).find((i) => i.key === ui.selected)?.executionId : undefined;
+        return renderDashboard(s, { columns, ui, logLines: executionId ? controls.logs(executionId, logRows) : [], activity: controls.logs, detail: controls.detail, quit, canChoose });
+    });
+    const perform = (action) => {
+        if (action?.type === 'open')
+            controls.open(action.url);
+        else if (action?.type === 'poll')
+            void controls.poll();
+        else if (action?.type === 'pause')
+            void controls.setPaused(action.paused);
+        else if (action?.type === 'choose') {
+            // The engine says no when the deadline won the race, and a rejection nobody catches ends the process: tell the person instead.
+            Promise.resolve(controls.chooseOptions?.(action.repo, action.issue, { author: action.author, reviewer: action.reviewer })).catch((error) => {
+                const reason = error instanceof Error ? error.message : String(error);
+                // A refusal is the engine answering; anything else is a failure.
+                if (Object.hasOwn(refusalWords, reason))
+                    log.info('the engine refused the chosen options', { reason, repo: action.repo, epic: action.issue });
+                else
+                    log.error('could not start the epic on the chosen options', error, { repo: action.repo, epic: action.issue });
+                ui = { ...ui, toast: { text: refusalWords[reason] ?? `Could not start it: ${reason}`, until: now() + toastFor } };
+                panel.redraw();
+            });
+        }
+        else if (action?.type === 'quit')
+            controls.quit();
+    };
+    const stopKeys = startKeys(stdin, (key) => {
+        const next = onKey(ui, key, snapshot(), now(), canChoose);
+        ui = next.ui;
+        perform(next.action);
+        panel.redraw();
+    });
+    return () => {
+        stopKeys();
+        panel();
+    };
+}

package/dist/terminal/dashboard/keys.js

@@ -0,0 +1,22 @@
+import { emitKeypressEvents } from 'node:readline';
+/**
+ * Reads single keys from the terminal. Raw mode means Ctrl+C is a key like any other (it no longer raises SIGINT),
+ * so the caller has to treat it as a quit. Nothing happens without a terminal. Returns the stop function.
+ */
+export function startKeys(stdin, onKey) {
+    if (!stdin.isTTY || stdin.setRawMode === undefined)
+        return () => { };
+    emitKeypressEvents(stdin);
+    stdin.setRawMode(true);
+    stdin.resume();
+    const handler = (sequence, key) => onKey({ name: key?.name, ctrl: key?.ctrl, sequence });
+    stdin.on('keypress', handler);
+    const restore = () => stdin.setRawMode?.(false); // also when the process dies on its own
+    process.once('exit', restore);
+    return () => {
+        stdin.off('keypress', handler);
+        process.removeListener('exit', restore);
+        restore();
+        stdin.pause();
+    };
+}