@ashulab/carrier 0.0.0-stage → 0.1.1

package/dist/terminal/cli/commands/control.js

@@ -0,0 +1,46 @@
+import { enginePlacesOf } from '../../../config/engine-places.js';
+import { CliError } from '../cli-error.js';
+import { connectControl, ControlUnreachable } from '../control-client.js';
+const requests = { stop: 'stop', pause: 'pause', resume: 'resume', check: 'checkNow' };
+const confirmations = { stop: 'Carrier stopped', pause: 'Intake paused', resume: 'Intake resumed', check: 'Checking GitHub now' };
+const STOP_WAIT_MS = 15_000; // the same limit as the app
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Polls until nothing answers on the socket any more; false when it still does after `STOP_WAIT_MS`. */
+export async function socketGone(path) {
+    for (const deadline = Date.now() + STOP_WAIT_MS; Date.now() < deadline; await sleep(100)) {
+        try {
+            (await connectControl(path, { timeoutMs: 500 })).close();
+        }
+        catch {
+            return true;
+        }
+    }
+    return false;
+}
+/** `stop`, `pause`, `resume` and `check` over the control socket of the Carrier running in this Carrier folder. Returns the exit code. */
+export async function controlCommand(name, folder) {
+    const path = enginePlacesOf(folder).socket;
+    let client;
+    try {
+        client = await connectControl(path);
+        await client.request(requests[name]);
+    }
+    catch (error) {
+        if (error instanceof ControlUnreachable === false)
+            throw new CliError(1, `Carrier refused: ${error instanceof Error ? error.message : String(error)}`);
+        if (error.reason === 'incompatible')
+            throw new CliError(2, 'The running Carrier speaks a protocol this command does not (it expects 1). Update one of them.');
+        if (error.reason === 'no-answer')
+            throw new CliError(1, `Carrier does not answer on ${path}`);
+        if (name === 'stop') {
+            process.stdout.write('Carrier is not running\n');
+            return 0;
+        }
+        throw new CliError(1, 'Carrier is not running');
+    }
+    client.close();
+    if (name === 'stop' && (await socketGone(path)) === false)
+        throw new CliError(1, `Carrier still answers on ${path} after ${STOP_WAIT_MS / 1000} seconds`);
+    process.stdout.write(`${confirmations[name]}\n`);
+    return 0;
+}

package/dist/terminal/cli/commands/doctor.js

@@ -0,0 +1,15 @@
+import { runDoctor } from '../../../doctor/doctor.js';
+import { makeClackUi, noPromptUi, printCheck } from '../../prompts/clack.js';
+/** Lists every check (this command is asked for them) and returns the exit code: 1 when any failed. With `json`, stdout is the checks as one JSON array and nothing else. */
+export async function doctorCommand(config, folder, json = false, overrides = {}) {
+    if (json) {
+        const checks = await runDoctor(config, folder, overrides); // no spinner or progress: the app reads stdout whole
+        process.stdout.write(`${JSON.stringify(checks)}\n`);
+        return checks.some((c) => c.status === 'fail') ? 1 : 0;
+    }
+    const ui = process.stdout.isTTY ? makeClackUi() : { ...noPromptUi, check: printCheck }; // a spinner per check only on a terminal
+    const checks = await runDoctor(config, folder, overrides, ui.check, ui.checkStart);
+    const failed = checks.filter((c) => c.status === 'fail').length;
+    process.stdout.write(failed > 0 ? `\n${failed} of ${checks.length} checks failed\n` : `\nAll ${checks.length} checks passed\n`);
+    return failed > 0 ? 1 : 0;
+}

package/dist/terminal/cli/commands/init.js

@@ -0,0 +1,43 @@
+import { runInit } from '../../wizard/wizard.js';
+import { cancelled, makeClackUi, noPromptUi } from '../../prompts/clack.js';
+import { Cancelled } from '../../prompts/types.js';
+import { CliError } from '../cli-error.js';
+import { runCommand } from './run.js';
+/** The guided setup. Returns the exit code, or undefined when "Start Carrier now?" was answered yes and it is running. */
+export async function initCommand(flags, folder) {
+    const ui = flags.yes || !process.stdin.isTTY ? noPromptUi : makeClackUi({ compact: true });
+    let started;
+    try {
+        started = await runInit({
+            repo: flags.repo,
+            identities: flags.identities,
+            authorProfile: flags['author-profile'],
+            reviewerProfile: flags['reviewer-profile'],
+            leadReviewerProfile: flags['lead-reviewer-profile'],
+            author: flags.author,
+            reviewer: flags.reviewer,
+            leadReviewer: flags['lead-reviewer'],
+            authorProvider: flags['author-provider'],
+            reviewerProvider: flags['reviewer-provider'],
+            leadReviewerProvider: flags['lead-reviewer-provider'],
+            authorPersonaName: flags['author-persona-name'],
+            authorPersonaPrompt: flags['author-persona-prompt'],
+            reviewerPersonaName: flags['reviewer-persona-name'],
+            reviewerPersonaPrompt: flags['reviewer-persona-prompt'],
+            leadReviewerPersonaName: flags['lead-reviewer-persona-name'],
+            leadReviewerPersonaPrompt: flags['lead-reviewer-persona-prompt'],
+            out: flags.out,
+            yes: flags.yes,
+        }, ui, undefined, folder);
+    }
+    catch (error) {
+        if (error instanceof Cancelled) {
+            cancelled();
+            return 0;
+        }
+        throw new CliError(1, error instanceof Error ? error.message : String(error));
+    }
+    if (started.start)
+        return void (await runCommand(started.config, folder, { framed: true })); // the same process, until Ctrl+C
+    return started.checks.some((c) => c.status === 'fail') ? 1 : 0;
+}

package/dist/terminal/cli/commands/restart.js

@@ -0,0 +1,92 @@
+import { enginePlacesOf } from '../../../config/engine-places.js';
+import { cancelled, makeClackUi } from '../../prompts/clack.js';
+import { Cancelled } from '../../prompts/types.js';
+import { CliError } from '../cli-error.js';
+import { connectControl, ControlUnreachable } from '../control-client.js';
+// The engine waits up to 30 seconds for the epic to start again before it refuses.
+const RESTART_WAIT_MS = 40_000;
+// What the engine's short refusal means for the person, and what to do next.
+const refusals = {
+    'unknown epic': (target) => `Carrier does not know ${target}. Use the owner/repo#issue that carrier status shows.`,
+    'not stopped': (target) => `${target} is not stopped, so there is nothing to restart.`,
+    'github unavailable': () => 'GitHub did not answer, so nothing changed. Try again in a moment.',
+    'did not restart': () => 'The ready label is back on the issue, but the epic did not start within 30 seconds. The next check will take it.',
+    'unknown option': () => 'That option is not in agentOptions of the configuration. Use a name declared there.',
+};
+/**
+ * One question per role with the role's current option preselected, and the option of the role that stopped the epic marked.
+ * When that role ran out of usage its option is not preselected: two Enters would run the same option again.
+ * Nothing is asked of an epic that has fewer than two options to choose from (or predates options).
+ */
+export async function askRestartOptions(epic, ui) {
+    const options = epic?.options;
+    if (!options || options.names.length < 2)
+        return {};
+    const failed = epic.stage === 'review' ? 'reviewer' : 'author';
+    const chosen = {};
+    for (const role of ['author', 'reviewer']) {
+        const current = options[role];
+        const ranOut = role === failed && epic.needsHumanKind === 'usage_limit';
+        chosen[role] = await ui.select({
+            message: `Option for the ${role}`,
+            initialValue: (ranOut ? options.names.find((name) => name !== current) : current) ?? undefined,
+            options: options.names.map((name) => ({ value: name, label: name, ...(name === current && { hint: ranOut ? 'ran out' : role === failed ? 'current, failed' : 'current' }) })),
+        });
+    }
+    return chosen;
+}
+/** `carrier restart <owner/repo>#<issue>`: resumes a stopped epic over the control socket. Returns the exit code. */
+export async function restartCommand(folder, { repo, issue }, flags) {
+    const path = enginePlacesOf(folder).socket;
+    let client;
+    try {
+        client = await connectControl(path, { timeoutMs: RESTART_WAIT_MS });
+    }
+    catch (error) {
+        if (error instanceof ControlUnreachable === false)
+            throw error;
+        if (error.reason === 'incompatible')
+            throw new CliError(2, 'The running Carrier speaks a protocol this command does not (it expects 1). Update one of them.');
+        if (error.reason === 'no-answer')
+            throw new CliError(1, `Carrier does not answer on ${path}`);
+        throw new CliError(1, 'Carrier is not running');
+    }
+    try {
+        if (client.hello.capabilities.includes('agentOptions') === false)
+            throw new CliError(1, 'The running Carrier is too old to restart an epic on a chosen option (it lacks the agentOptions capability). Update it.');
+        let chosen = { ...(flags.author && { author: flags.author }), ...(flags.reviewer && { reviewer: flags.reviewer }) };
+        if (flags.author === undefined && flags.reviewer === undefined && process.stdin.isTTY && process.stdout.isTTY) {
+            const { epics } = (await client.request('snapshot'));
+            const epic = epics.find((e) => e.repo === repo && e.issue === issue);
+            // Before any question: an epic the engine would refuse is not worth asking about.
+            if (epic === undefined)
+                throw new CliError(1, refusals['unknown epic'](`${repo}#${issue}`));
+            if (epic.status !== 'needs_human')
+                throw new CliError(1, refusals['not stopped'](`${repo}#${issue}`));
+            try {
+                chosen = await askRestartOptions(epic, makeClackUi({ compact: true }));
+            }
+            catch (error) {
+                if (error instanceof Cancelled === false)
+                    throw error;
+                cancelled();
+                return 0;
+            }
+        }
+        process.stdout.write(`Restarting ${repo}#${issue}…\n`); // the engine waits up to 30 seconds
+        await client.request('resumeEpic', { repo, issue, ...chosen });
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        if (error instanceof ControlUnreachable)
+            throw new CliError(1, `Carrier does not answer on ${path}`);
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new CliError(1, refusals[reason]?.(`${repo}#${issue}`) ?? `Carrier refused: ${reason}`);
+    }
+    finally {
+        client.close();
+    }
+    process.stdout.write(`Restarted ${repo}#${issue}\n`);
+    return 0;
+}

package/dist/terminal/cli/commands/run.js

@@ -0,0 +1,20 @@
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { CliError } from '../cli-error.js';
+import { InstanceBusy, startCarrier } from '../compose.js';
+/**
+ * Starts the orchestrator; it keeps the process alive until Ctrl+C. On a terminal: "Starting…" until the engine is up,
+ * then the arrival line, then the panel. `framed`: the caller (init) already opened the frame the spinner lives in.
+ */
+export async function runCommand(config, folder, { framed = false } = {}) {
+    const announce = process.stdout.isTTY ? (await import('../../prompts/clack.js')).announceStart({ framed }) : undefined;
+    try {
+        await startCarrier(config, folder, { onArrived: announce?.arrived });
+    }
+    catch (error) {
+        announce?.failed();
+        if (error instanceof InstanceBusy)
+            throw new CliError(1, error.message);
+        createScopedLogger('cli').error('startup failed', error); // logging is installed by now: the stack goes to the log file
+        throw new CliError(1, `carrier failed to start: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/terminal/cli/commands/schema.js

@@ -0,0 +1,4 @@
+import { userConfigJsonSchema } from '../../../config/json-schema.js';
+export function schemaCommand() {
+    process.stdout.write(`${JSON.stringify(userConfigJsonSchema(), null, 2)}\n`);
+}

package/dist/terminal/cli/commands/start.js

@@ -0,0 +1,21 @@
+import { join } from 'node:path';
+import { enginePlacesOf } from '../../../config/engine-places.js';
+import { pidAt, startDetached } from '../detached.js';
+/**
+ * Starts Carrier as a detached run (ADR 0010): the same program with `--config`, in its own session, its output in
+ * `<folder>/engine/logs/start.log`. Returns once the control socket answers; a Carrier already answering is left alone.
+ * `folder` is the Carrier folder; `configPath` is absolute: the child does not share this process's working directory.
+ */
+export async function startCommand(folder, configPath) {
+    const places = enginePlacesOf(folder);
+    const socketPath = places.socket;
+    const logPath = join(places.logs, 'start.log');
+    const running = await pidAt(socketPath);
+    if (running !== undefined) {
+        process.stdout.write(`Carrier is already running (pid ${running}).\n`);
+        return 0;
+    }
+    const pid = await startDetached({ label: 'Carrier', args: ['--config', configPath], socketPath, logPath });
+    process.stdout.write(`Carrier is running (pid ${pid}). Log: ${logPath}\n`);
+    return 0;
+}

package/dist/terminal/cli/commands/status.js

@@ -0,0 +1,61 @@
+import { enginePlacesOf } from '../../../config/engine-places.js';
+import { renderDashboard } from '../../dashboard/dashboard.js';
+import { connectControl, ControlUnreachable } from '../control-client.js';
+const out = (text) => process.stdout.write(`${text}\n`);
+const err = (text) => process.stderr.write(`${text}\n`);
+/** Connects to the Carrier running in this Carrier folder; when there is none to use, says why and returns the exit code instead: 1 not running or silent, 2 another protocol. */
+export async function attach(folder) {
+    try {
+        return await connectControl(enginePlacesOf(folder).socket);
+    }
+    catch (error) {
+        if (error instanceof ControlUnreachable === false)
+            throw error;
+        if (error.reason === 'incompatible') {
+            err(`This carrier speaks control protocol 1; the running one speaks ${error.protocol === undefined ? 'something else' : `protocol ${String(error.protocol)}`}. Update the older one so both match.`);
+            return 2;
+        }
+        err(error.reason === 'no-answer' ? 'Carrier is running but does not answer. Try again, or check its log.' : 'Carrier is not running. Start it with "carrier start".');
+        return 1;
+    }
+}
+/**
+ * An epic's stages over the socket; null when there are none to know (the engine's hello does not list `sessions` and nothing is sent,
+ * or it answers `unknown epic`) and undefined when the request failed this time. Either way the epic is drawn without detail, which
+ * never breaks the panel; only the failure is worth asking again.
+ */
+export async function stagesOf(client, repo, issue) {
+    if (client.hello.capabilities.includes('sessions') === false)
+        return null;
+    try {
+        return (await client.request('sessions', { repo, issue })).sessions;
+    }
+    catch (error) {
+        return error instanceof Error && error.message === 'unknown epic' ? null : undefined;
+    }
+}
+/** Prints the panel of the running Carrier once. Exit 0 it runs; 1 it is not running or does not answer; 2 it speaks another protocol. */
+export async function statusCommand(folder) {
+    const client = await attach(folder);
+    if (typeof client === 'number')
+        return client;
+    try {
+        const snapshot = (await client.request('snapshot'));
+        const tty = process.stdout.isTTY === true;
+        // Every epic on the panel shows its stages; one print, so one request each.
+        const shown = [...snapshot.epics, ...snapshot.done];
+        const stages = new Map(await Promise.all(shown.map(async (e) => [`${e.repo}#${e.issue}`, await stagesOf(client, e.repo, e.issue)])));
+        const detail = (repo, issue) => stages.get(`${repo}#${issue}`) ?? null;
+        out(renderDashboard(snapshot, { color: tty, columns: tty ? process.stdout.columns : 100, detail }).join('\n'));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof ControlUnreachable === false)
+            throw error;
+        err('Carrier is running but does not answer. Try again, or check its log.');
+        return 1;
+    }
+    finally {
+        client.close();
+    }
+}

package/dist/terminal/cli/commands/watch.js

@@ -0,0 +1,112 @@
+import { renderDashboard } from '../../dashboard/dashboard.js';
+import { startInteractivePanel } from '../../dashboard/interactive.js';
+import { startPanel } from '../../dashboard/panel.js';
+import { ControlUnreachable } from '../control-client.js';
+import { openUrl } from '../open-url.js';
+import { attach, stagesOf } from './status.js';
+const REFRESH_MS = 1000;
+const TAIL_LINES = 18; // what the logs screen shows; the cards' "now" lines take the end of the same answer
+/**
+ * The panel's `Controls` and snapshot over a control socket. The panel reads both synchronously, so the snapshot and
+ * each execution's output are kept from the last answer and renewed in the background: `refresh` for the snapshot,
+ * a new `tail` request at each read of the output. `lost` is called when the socket stops answering.
+ * The stages of each epic work the same way: the panel's cache rule decides when to ask again, the request goes out
+ * in the background, the last answer stays on screen meanwhile and the next redraw shows the new one.
+ */
+export function socketPanel(client, { open, quit, lost }) {
+    let latest;
+    const tails = new Map();
+    // Another failure (the engine refused one request) leaves the panel as it was.
+    const guard = (request) => request.catch((error) => error instanceof ControlUnreachable && lost());
+    const stages = new Map();
+    const detail = (repo, issue) => {
+        const key = `${repo}#${issue}`;
+        const known = stages.get(key) ?? { detail: null, asking: false, arrived: false };
+        stages.set(key, known);
+        if (known.arrived) {
+            known.arrived = false;
+            return known.detail;
+        }
+        if (known.asking === false) {
+            known.asking = true;
+            // A failed request is not an answer: the last one stays and the next draw asks again.
+            void stagesOf(client, repo, issue).then((answer) => Object.assign(known, answer === undefined ? { asking: false } : { detail: answer, asking: false, arrived: true }));
+        }
+        // ponytail: an answer that was asked before the epic's latest change is shown as if current until the next change; per-ask tokens if it ever shows.
+        return undefined; // not remembered: the panel asks again at its next draw
+    };
+    const controls = {
+        detail,
+        poll: () => guard(client.request('checkNow')),
+        setPaused: (paused) => guard(client.request(paused ? 'pause' : 'resume')),
+        // An engine that does not list agentOptions cannot be asked, so the panel is given no way to ask.
+        // The engine's refusal (`not waiting`, `unknown option`) goes back to the panel, which tells the person.
+        ...(client.hello.capabilities.includes('agentOptions') && {
+            chooseOptions: (repo, issue, chosen) => client.request('chooseOptions', { repo, issue, ...chosen }).catch((error) => {
+                if (error instanceof ControlUnreachable)
+                    lost();
+                else
+                    throw error;
+            }),
+        }),
+        open,
+        quit,
+        logs: (executionId, count) => {
+            const tail = tails.get(executionId) ?? { lines: [], asking: false };
+            tails.set(executionId, tail);
+            if (tail.asking === false) {
+                tail.asking = true;
+                void guard(client.request('tail', { executionId, lines: TAIL_LINES }).then((lines) => (tail.lines = lines))).finally(() => (tail.asking = false));
+            }
+            return tail.lines.slice(-count);
+        },
+    };
+    return {
+        controls,
+        snapshot: () => latest,
+        /** Asks for the snapshot; rejects when the socket does not answer. */
+        refresh: async () => {
+            latest = (await client.request('snapshot'));
+        },
+    };
+}
+/** Shows the live panel of the running Carrier, with the foreground panel's keys; `q` and Ctrl+C leave and Carrier keeps running. Exit 0 left; 1 not running, or it stopped; 2 another protocol. */
+export async function watchCommand(folder) {
+    const client = await attach(folder);
+    if (typeof client === 'number')
+        return client;
+    return new Promise((resolve) => {
+        let stop = () => { };
+        let timer;
+        let finished = false;
+        const finish = (code, message) => {
+            if (finished)
+                return;
+            finished = true;
+            clearInterval(timer);
+            process.off('SIGINT', leave);
+            stop(); // the cursor and the keys back before anything else is printed
+            client.close();
+            if (message)
+                process.stderr.write(`${message}\n`);
+            resolve(code);
+        };
+        const leave = () => finish(0);
+        const panel = socketPanel(client, { open: openUrl, quit: leave, lost: () => finish(1, 'Carrier stopped.') });
+        process.once('SIGINT', leave); // a Ctrl+C that is not a key: no raw mode, because stdin is not a terminal
+        panel.refresh().then(() => {
+            const { stdout, stdin } = process;
+            stop =
+                stdout.isTTY && stdin.isTTY
+                    ? startInteractivePanel({ snapshot: panel.snapshot, out: stdout, stdin, controls: panel.controls, quit: 'leave' })
+                    : startPanel(panel.snapshot, stdout, REFRESH_MS, (s, columns) => renderDashboard(s, { columns, quit: 'leave', detail: panel.controls.detail }));
+            let asking = false;
+            timer = setInterval(() => {
+                if (asking)
+                    return;
+                asking = true;
+                panel.refresh().catch(() => finish(1, 'Carrier stopped.')).finally(() => (asking = false));
+            }, REFRESH_MS);
+        }, () => finish(1, 'Carrier is running but does not answer. Try again, or check its log.'));
+    });
+}

package/dist/terminal/cli/compose.js

@@ -0,0 +1,163 @@
+import { chmodSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { enginePlacesOf } from '../../config/engine-places.js';
+import { resolveRepoConfig } from '../../config/resolve.js';
+import { GitWorkspaces, profileToken } from '../../execution/git-workspaces.js';
+import { epicOf } from '../../control/epic.js';
+import { eventsOf, lastEventOf } from '../../control/events.js';
+import { fileDiff, filesOf } from '../../control/files.js';
+import { inheritedConfigDirs, sessionsOf } from '../../control/sessions.js';
+import { startControlServer, version } from '../../control/server.js';
+import { listAvailableRepos } from '../../integrations/available-repos.js';
+import { forgeCwd } from '../../integrations/forge-cwd.js';
+import { GhGitHub } from '../../integrations/github.js';
+import { installFileLogging } from '../../logging/logger.js';
+import { realClock } from '../../orchestration/clock.js';
+import { createEngine } from '../../orchestration/engine.js';
+import { AuthError } from '../../orchestration/github.js';
+import { sessionDirsFrom } from '../../orchestration/retention.js';
+import { renderDashboard } from '../dashboard/dashboard.js';
+import { startInteractivePanel } from '../dashboard/interactive.js';
+import { tailExecution } from '../dashboard/logs.js';
+import { startPanel } from '../dashboard/panel.js';
+import { buildSnapshot, watchedOf } from '../../status/snapshot.js';
+import { profileCredentials } from '../../harnesses/credentials.js';
+import { HostAgentRunner } from '../../harnesses/host-runner.js';
+import { openDatabase } from '../../storage/db.js';
+import { acquireLock } from '../../storage/lock.js';
+import { stopOnSigint } from './interrupt.js';
+import { openUrl } from './open-url.js';
+export class InstanceBusy extends Error {
+}
+const realDeps = () => ({
+    installLogging: installFileLogging,
+    clock: realClock,
+    makeGitHub: (options) => new GhGitHub(options),
+    makeWorkspaces: (options) => new GitWorkspaces(options),
+    makeRunner: (options) => new HostAgentRunner(options),
+    mint: (profile, repo) => profileToken(profile)(repo),
+    sessionDirs: sessionDirsFrom(),
+    listRepos: listAvailableRepos,
+    panelOut: process.stdout,
+    onSigint: stopOnSigint,
+    stdin: process.stdin,
+    openUrl,
+    quit: () => process.kill(process.pid, 'SIGINT'),
+});
+/**
+ * Starts carrier on a validated config and the Carrier folder it keeps its files in: the instance lock, file logging, the engine with the real GitHub (the
+ * orchestrator's profile, through Forge), workspaces and the runner of each harness, the panel, and Ctrl+C.
+ * Throws InstanceBusy when another carrier holds the folder's `engine/state/`.
+ */
+export async function startCarrier(config, folder, overrides = {}) {
+    const deps = { ...realDeps(), ...overrides };
+    const places = enginePlacesOf(folder);
+    // First side effect of startup: one instance per Carrier folder.
+    const lock = acquireLock(places.state);
+    if (!lock.ok)
+        throw new InstanceBusy(`Another carrier instance is already running on ${places.state}`);
+    mkdirSync(places.logs, { recursive: true });
+    chmodSync(places.logs, 0o700); // execution output is for the user only
+    // From here on console.* goes to the log file; the terminal is for the panel.
+    deps.installLogging(join(places.logs, 'orchestrator.log'), config.logLevel);
+    createScopedLogger('cli').info('carrier started', { folder, repos: config.repos.length });
+    const startedAt = deps.clock.now();
+    const db = openDatabase(places.db);
+    const repos = config.repos.map((repo) => resolveRepoConfig(config, repo));
+    const { limits } = config;
+    // Git over the network (clone, fetch) runs as the repo's author profile.
+    const authorProfile = (repo) => config.profiles[repos.find((r) => r.name === repo).agents.author.profile];
+    const github = deps.makeGitHub({
+        profile: config.profiles[config.orchestratorProfile],
+        cwd: forgeCwd(places),
+        timeoutMs: limits.githubCallTimeoutSeconds * 1000,
+    });
+    const engine = createEngine({
+        db,
+        clock: deps.clock,
+        github,
+        workspaces: deps.makeWorkspaces({ places, token: (repo) => deps.mint(authorProfile(repo), repo) }),
+        runner: deps.makeRunner({ credentials: profileCredentials({ profiles: config.profiles, mint: deps.mint, botId: deps.botId }) }),
+        repos,
+        pollIntervalMs: config.pollIntervalMinutes * 60_000,
+        maxConcurrentEpics: limits.maxConcurrentEpics,
+        maxReviews: limits.maxReviews,
+        maxExecutionRetries: limits.maxExecutionRetries,
+        optionChoiceSeconds: limits.optionChoiceSeconds,
+        maxExecutionHours: limits.maxExecutionHours,
+        places,
+        sessionDirs: deps.sessionDirs,
+    });
+    let stopPanel = () => { }; // the panel starts once the engine is up
+    let stopControl = () => { };
+    const close = () => {
+        stopControl(); // before the lock goes: a socket without the lock is what a takeover looks like
+        stopPanel();
+        engine.stop();
+        db.$client.close();
+        lock.release();
+    };
+    // Before the engine starts: its recovery may launch agents already, and Ctrl+C has to stop them.
+    const shutdown = deps.onSigint({ engine, close });
+    try {
+        await engine.start();
+    }
+    catch (error) {
+        await engine.shutdown(); // recovery may have launched agents already
+        close();
+        throw error;
+    }
+    // Only now: until the engine is up the terminal belongs to whoever is waiting for it (the "Starting…" spinner).
+    deps.onArrived?.();
+    const snapshot = () => {
+        const limit = github.rateLimit();
+        return buildSnapshot(db, {
+            now: deps.clock.now(),
+            maxConcurrentEpics: limits.maxConcurrentEpics,
+            maxReviews: limits.maxReviews,
+            finishedWindowDays: config.finishedWindowDays,
+            startedAt,
+            repos: config.repos.length,
+            nextCheckAt: engine.nextPollAt,
+            problem: engine.error instanceof AuthError ? `authentication error for profile ${engine.error.profile}` : engine.error ? 'GitHub is unavailable: it will be tried again' : null,
+            paused: engine.paused,
+            slices: engine.slices,
+            version,
+            pollIntervalMs: config.pollIntervalMinutes * 60_000,
+            rateLimit: limit && { ...limit, profile: 'orchestrator' },
+            watched: watchedOf(repos, engine.lastCheck),
+            lastEvent: (executionId) => lastEventOf(db, executionId),
+        });
+    };
+    const controls = {
+        poll: () => engine.pollNow(),
+        setPaused: (paused) => engine.setPaused(paused),
+        open: deps.openUrl,
+        quit: deps.quit,
+        logs: (id, count) => tailExecution(places.logs, id, count),
+        sessions: (repo, issue) => sessionsOf(db, repo, issue, inheritedConfigDirs()),
+        events: (executionId, after, limit) => eventsOf(db, executionId, after, limit),
+        epic: (repo, issue) => epicOf(db, repo, issue),
+        files: (repo, issue, executionId) => filesOf(db, places.repos, repo, issue, executionId),
+        fileDiff: (repo, issue, section, path) => fileDiff(db, places.repos, repo, issue, section, path),
+        availableRepos: (page) => deps.listRepos(page, limits.githubCallTimeoutSeconds * 1000),
+        resumeEpic: (repo, issue, chosen) => engine.resumeEpic(repo, issue, chosen),
+        chooseOptions: (repo, issue, chosen) => engine.chooseOptions(repo, issue, chosen),
+    };
+    stopControl = (await startControlServer({ stateDir: places.state, snapshot, startedAt, controls, stop: shutdown })).close;
+    const detail = (repo, issue) => controls.sessions(repo, issue)?.sessions ?? null;
+    // With a terminal on both sides the panel takes keys; otherwise it only draws (or writes plain lines).
+    stopPanel =
+        deps.panelOut.isTTY && deps.stdin?.isTTY
+            ? startInteractivePanel({
+                snapshot,
+                out: deps.panelOut,
+                stdin: deps.stdin,
+                intervalMs: deps.panelIntervalMs,
+                now: () => deps.clock.now(),
+                controls: { ...controls, detail },
+            })
+            : startPanel(snapshot, deps.panelOut, deps.panelIntervalMs, (s, columns) => renderDashboard(s, { columns, detail }));
+    return { engine, db, close };
+}

package/dist/terminal/cli/config-file.js

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { defaultConfigPath } from '../../config/default-path.js';
+import { defaults, loadConfig } from '../../config/load.js';
+import { CliError } from './cli-error.js';
+/** The explicit `--config` wins; otherwise the global file `carrier init` writes, if it is there. */
+export const configPathFor = (explicit) => (typeof explicit === 'string' ? explicit : existsSync(defaultConfigPath()) ? defaultConfigPath() : undefined);
+/** When there is no config to use: what to do about it. */
+export const noConfig = (...first) => new CliError(2, ...first, `No config at ${defaultConfigPath()}: run "carrier init" to create one.`);
+/** Reads, merges over the defaults and validates; every problem is reported at once, with its field. */
+export function loadConfigFile(path) {
+    const file = resolve(path);
+    let user;
+    try {
+        user = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new CliError(1, `Cannot read config ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const result = loadConfig(defaults, user);
+    if (!result.ok)
+        throw new CliError(1, `Invalid config ${file}:`, ...result.errors.map((e) => `  ${e.path}: ${e.message}`));
+    return result.config;
+}