@ashulab/carrier 0.0.0-stage → 0.1.1

package/dist/chat/codex.js

@@ -0,0 +1,375 @@
+import { execFile, spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { endGroup, resolveAgentBinary } from './group.js';
+import { ChatRefused } from './runner.js';
+// The Codex adapter of the chat runner: the user's own `codex app-server`, JSON-RPC over stdio, one JSON object per
+// line (docs/research/chat-spike.md). No npm dependency: the adapter spawns the binary and speaks the protocol itself.
+//
+// Written against codex-cli / app-server 0.153.4, which Codex marks as experimental: the protocol changes with the
+// version. The messages below are the ones the spike recorded; a notification this adapter does not know gives no
+// event, and a server request it does not know is answered with an error so that it never holds a turn. A version other
+// than this one is logged when the server says hello.
+export const CODEX_APP_SERVER_VERSION = '0.153.4';
+const log = createScopedLogger('chat');
+const APPROVAL_POLICIES = [
+    { id: 'untrusted', label: 'Ask unless the command is known to be safe' },
+    { id: 'on-request', label: 'The agent decides when to ask' },
+    { id: 'never', label: 'Never ask' },
+];
+// `danger-full-access` is left out, as Claude's `bypassPermissions` is: Carrier does not turn it on.
+const SANDBOXES = [
+    { id: 'read-only', label: 'Read only' },
+    { id: 'workspace-write', label: 'Write in the folder' },
+];
+/** A turn takes the sandbox as an object, a thread as a name. */
+const SANDBOX_POLICIES = {
+    'read-only': { type: 'readOnly', networkAccess: false },
+    'workspace-write': { type: 'workspaceWrite', writableRoots: [], networkAccess: false, excludeTmpdirEnvVar: false, excludeSlashTmp: false },
+};
+const codexLoggedIn = (binary, env) => new Promise((done) => {
+    execFile(binary, ['login', 'status'], { env, timeout: 15_000 }, (error) => done(error === null)); // what it prints is not read: it names the login
+});
+const ownGroup = (binary, { cwd, env }) => {
+    const child = spawn(binary, ['app-server'], { cwd, env, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+    child.stderr.resume(); // drained and never read: it may say things about the login
+    child.stdin.on('error', () => { }); // a write after the process ended; `onExit` reports the end
+    const lines = createInterface({ input: child.stdout });
+    return {
+        pid: child.pid,
+        write: (line) => void child.stdin.write(`${line}\n`),
+        onLine: (listener) => void lines.on('line', listener),
+        onExit(listener) {
+            let called = false;
+            const once = () => called || ((called = true), listener());
+            child.once('error', once);
+            child.once('close', once);
+        },
+    };
+};
+export const realCodexDeps = { resolve: (command, env) => resolveAgentBinary('codex', command, env), loggedIn: codexLoggedIn, spawn: ownGroup };
+export function codexChatRunner(deps = realCodexDeps) {
+    return {
+        async open({ folder, resume, options = {}, command, env }) {
+            let binary;
+            try {
+                binary = deps.resolve(command, env);
+            }
+            catch {
+                throw new ChatRefused(`Codex is not installed: ${command === undefined ? 'there is no "codex" on the path' : `"${command}" cannot be run`}`);
+            }
+            if (!(await deps.loggedIn(binary, env)))
+                throw new ChatRefused('Codex is not logged in; run "codex login" once to log in');
+            const conversation = new CodexConversation(options, binary);
+            try {
+                await conversation.start(deps, { folder, env, resume });
+            }
+            catch (error) {
+                log.error('codex could not be started', error);
+                await conversation.close();
+                throw new ChatRefused(resume === undefined ? 'Codex could not be started' : 'Codex could not resume that conversation');
+            }
+            return conversation;
+        },
+    };
+}
+class CodexConversation {
+    nativeId;
+    listeners = [];
+    endListeners = [];
+    transport;
+    nextId = 1;
+    waiting = new Map();
+    /** Approvals asked and not answered: the server's request id, and the decision each choice answers with. */
+    pending = new Map();
+    /** The skills `skills/list` gave for the folder: what the person can invoke. */
+    skills = [];
+    models = [];
+    model;
+    effort;
+    approvalPolicy;
+    sandbox;
+    /** What changed since the last turn: Codex applies it from the next `turn/start`, and keeps it after. */
+    overrides = {};
+    turning = false;
+    turnId;
+    usage = {};
+    closing = false;
+    chosen;
+    binary;
+    constructor(chosen, binary) {
+        this.chosen = chosen;
+        this.binary = binary;
+        this.model = chosen.model ?? '';
+        this.effort = chosen.effort ?? '';
+        this.approvalPolicy = chosen.approvalPolicy ?? 'untrusted'; // every command that is not known to be safe asks, as Claude's default mode does
+        this.sandbox = chosen.sandbox ?? 'workspace-write';
+    }
+    async start(deps, { folder, env, resume }) {
+        this.transport = deps.spawn(this.binary, { cwd: folder, env });
+        this.transport.onLine((line) => this.receive(line));
+        this.transport.onExit(() => this.ended());
+        const hello = await this.request('initialize', { clientInfo: { name: 'carrier', title: 'Carrier', version: '0.0.0' } });
+        const version = /\/(\d+\.\d+\.\d+)/.exec(String(hello?.userAgent))?.[1];
+        if (version !== CODEX_APP_SERVER_VERSION)
+            log.warn('codex app-server is not the version this adapter was written against', { found: version, expected: CODEX_APP_SERVER_VERSION });
+        this.notify('initialized');
+        const params = { cwd: folder, approvalPolicy: this.approvalPolicy, sandbox: this.sandbox, ...(this.chosen.model && { model: this.chosen.model }) };
+        const started = await this.request(resume === undefined ? 'thread/start' : 'thread/resume', resume === undefined ? params : { threadId: resume, ...params });
+        this.nativeId = started.thread.id;
+        this.model = this.chosen.model ?? started.model ?? '';
+        this.effort = this.chosen.effort ?? started.reasoningEffort ?? '';
+        if (this.chosen.effort)
+            this.overrides.effort = this.chosen.effort; // a thread takes no effort: the first turn carries it
+        this.models = (await this.request('model/list', {})).data.filter((m) => !m.hidden);
+        // the skills of the folder; a provider that cannot say leaves the list empty and the conversation goes on
+        try {
+            const listed = await this.request('skills/list', { cwds: [folder] });
+            this.skills = (listed?.data ?? []).flatMap((entry) => (entry.skills ?? []).filter((skill) => skill.enabled !== false));
+        }
+        catch (error) {
+            log.warn('codex could not list its skills', { error: String(error) });
+        }
+    }
+    get process() {
+        return this.transport?.pid === undefined ? undefined : { pid: this.transport.pid, pgid: this.transport.pid, command: this.binary }; // it leads its own group (`ownGroup`)
+    }
+    get options() {
+        const efforts = this.effortsOf(this.model);
+        return [
+            { id: 'approvalPolicy', label: 'Approvals', values: APPROVAL_POLICIES, current: this.approvalPolicy },
+            { id: 'sandbox', label: 'Sandbox', values: SANDBOXES, current: this.sandbox },
+            { id: 'model', label: 'Model', values: this.models.map((m) => ({ id: m.model, label: m.displayName, version: m.model })), current: this.model },
+            ...(efforts.length > 0 ? [{ id: 'effort', label: 'Reasoning effort', values: efforts.map((id) => ({ id, label: id })), current: this.effort }] : []),
+        ];
+    }
+    effortsOf = (model) => this.models.find((m) => m.model === model)?.supportedReasoningEfforts.map((e) => e.reasoningEffort) ?? [];
+    get commands() {
+        return this.skills.map((skill) => ({ id: skill.path, name: skill.name, description: skill.shortDescription ?? skill.description, kind: 'skill' }));
+    }
+    send(text, command) {
+        this.turning = true;
+        this.usage = {};
+        this.turnId = undefined;
+        const overrides = this.overrides;
+        this.overrides = {};
+        this.request('turn/start', { threadId: this.nativeId, input: this.inputOf(text, command), ...overrides }).then((started) => {
+            if (this.turning && this.turnId === undefined)
+                this.turnId = started?.turn?.id;
+        }, (error) => {
+            if (this.closing)
+                return;
+            log.error('codex did not start the turn', error);
+            this.emit({ kind: 'error', text: 'Codex did not start the turn' }, { kind: 'turn_end', outcome: 'error', model: this.model });
+            this.turning = false;
+        });
+    }
+    /** Codex takes a skill as an item of its own in the turn's input, before what the person wrote after it. */
+    inputOf(text, command) {
+        const written = text === '' ? [] : [{ type: 'text', text, text_elements: [] }];
+        return command === undefined ? written : [{ type: 'skill', name: command.name, path: command.id }, ...written];
+    }
+    answer(approvalId, choiceId) {
+        const ask = this.pending.get(approvalId);
+        if (ask === undefined)
+            throw new ChatRefused('That approval is not pending any more');
+        if (!(choiceId in ask.decisions))
+            throw new ChatRefused('That is not one of the choices');
+        this.pending.delete(approvalId);
+        this.emit({ kind: 'approval_answered', approvalId, choiceId });
+        this.respond(ask.requestId, { decision: ask.decisions[choiceId] });
+    }
+    async interrupt() {
+        if (!this.turning)
+            return;
+        this.denyPending();
+        for (let waited = 0; this.turnId === undefined && this.turning && waited < 2_000; waited += 50)
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        if (this.turnId !== undefined && this.turning)
+            await this.request('turn/interrupt', { threadId: this.nativeId, turnId: this.turnId });
+        // The turn ends at its `turn/completed`; wait for it, so the host never sees the next turn start before this one's end.
+        for (let waited = 0; this.turning && waited < 5_000; waited += 50)
+            await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    async setOption(id, value) {
+        const option = this.options.find((o) => o.id === id);
+        if (option === undefined)
+            throw new ChatRefused(`There is no option "${id}"`);
+        if (!option.values.some((v) => v.id === value))
+            throw new ChatRefused(`"${value}" is not a value of ${id}`);
+        const events = [{ kind: 'option', id, value }];
+        if (id === 'model') {
+            this.model = value;
+            this.overrides.model = value;
+            // A level the new model does not list cannot stay.
+            const efforts = this.effortsOf(value);
+            if (efforts.length > 0 && !efforts.includes(this.effort)) {
+                this.effort = this.models.find((m) => m.model === value)?.defaultReasoningEffort ?? efforts[0];
+                this.overrides.effort = this.effort;
+                events.push({ kind: 'option', id: 'effort', value: this.effort });
+            }
+        }
+        else if (id === 'effort') {
+            this.effort = value;
+            this.overrides.effort = value;
+        }
+        else if (id === 'approvalPolicy') {
+            this.approvalPolicy = value;
+            this.overrides.approvalPolicy = value;
+        }
+        else {
+            this.sandbox = value;
+            this.overrides.sandboxPolicy = SANDBOX_POLICIES[value];
+        }
+        this.emit(...events);
+    }
+    async close() {
+        if (this.closing)
+            return;
+        this.closing = true;
+        this.denyPending();
+        this.rejectWaiting();
+        if (this.transport?.pid !== undefined)
+            await endGroup(this.transport.pid);
+    }
+    onEvent(listener) {
+        this.listeners.push(listener);
+    }
+    onEnd(listener) {
+        this.endListeners.push(listener);
+    }
+    emit(...events) {
+        for (const event of events)
+            for (const listener of this.listeners)
+                listener(event);
+    }
+    denyPending() {
+        for (const ask of this.pending.values())
+            this.respond(ask.requestId, { decision: 'cancel' });
+        this.pending.clear();
+    }
+    rejectWaiting() {
+        for (const call of this.waiting.values())
+            call.reject(new Error('The Codex process ended'));
+        this.waiting.clear();
+    }
+    ended() {
+        this.rejectWaiting();
+        if (this.closing)
+            return;
+        // The process ended on its own: that is the end of the turn that was running.
+        this.emit({ kind: 'error', text: 'The Codex process ended' });
+        if (this.turning)
+            this.emit({ kind: 'turn_end', outcome: 'error', model: this.model });
+        this.turning = false;
+        for (const listener of this.endListeners)
+            listener();
+    }
+    request(method, params) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.waiting.set(id, { resolve, reject });
+            this.transport.write(JSON.stringify({ id, method, params }));
+        });
+    }
+    notify(method) {
+        this.transport.write(JSON.stringify({ method }));
+    }
+    respond(id, result) {
+        this.transport.write(JSON.stringify({ id, result }));
+    }
+    /** One line from the server. Never throws: a line it cannot read or does not know gives no event. */
+    receive(line) {
+        try {
+            const m = JSON.parse(line);
+            if (typeof m.method === 'string' && m.id !== undefined)
+                this.serverRequest(m.id, m.method, m.params);
+            else if (typeof m.method === 'string')
+                this.emit(...this.translate(m.method, m.params));
+            else if (m.id !== undefined) {
+                const call = this.waiting.get(m.id);
+                this.waiting.delete(m.id);
+                if (m.error === undefined)
+                    call?.resolve(m.result);
+                else
+                    call?.reject(new Error(`codex answered with an error: ${String(m.error?.message)}`));
+            }
+        }
+        catch (error) {
+            log.error('a codex message could not be handled', error);
+        }
+    }
+    serverRequest(requestId, method, params) {
+        if (method !== 'item/commandExecution/requestApproval') {
+            // A request left unanswered holds the turn: say the method is not there.
+            log.warn('codex asked for something this adapter does not handle', { method });
+            this.transport.write(JSON.stringify({ id: requestId, error: { code: -32601, message: `Method not supported: ${method}` } }));
+            return;
+        }
+        const listed = Array.isArray(params?.availableDecisions) ? params.availableDecisions : [];
+        const amendment = listed.find((d) => typeof d === 'object' && d !== null && 'acceptWithExecpolicyAmendment' in d);
+        const decisions = { accept: 'accept', decline: 'decline' }; // `decline` is not listed and works
+        const choices = [
+            { id: 'accept', label: 'Allow', allow: true },
+            { id: 'decline', label: 'Deny', allow: false },
+        ];
+        if (amendment !== undefined) {
+            decisions.amend = amendment;
+            choices.push({ id: 'amend', label: `Always allow ${Array.isArray(params.proposedExecpolicyAmendment) ? params.proposedExecpolicyAmendment.join(' ') : 'this command'}`, allow: true });
+        }
+        if (listed.includes('cancel')) {
+            decisions.cancel = 'cancel';
+            choices.push({ id: 'cancel', label: 'Deny and stop the turn', allow: false });
+        }
+        const approvalId = String(requestId);
+        this.pending.set(approvalId, { requestId, decisions });
+        this.emit({ kind: 'approval', approvalId, tool: 'command', arg: typeof params?.command === 'string' ? params.command : undefined, choices });
+    }
+    translate(method, params) {
+        switch (method) {
+            case 'turn/started':
+                if (typeof params?.turn?.id === 'string')
+                    this.turnId = params.turn.id;
+                return [];
+            case 'serverRequest/resolved':
+                this.pending.delete(String(params?.requestId)); // answered elsewhere, or by the end of the turn
+                return [];
+            case 'item/agentMessage/delta':
+                return typeof params?.delta === 'string' && params.delta !== '' ? [{ kind: 'delta', text: params.delta }] : [];
+            case 'item/started': {
+                const item = params?.item;
+                return item?.type === 'commandExecution' && typeof item.id === 'string' ? [{ kind: 'tool_start', callId: item.id, tool: 'command', arg: typeof item.command === 'string' ? item.command : undefined }] : [];
+            }
+            case 'item/completed': {
+                const item = params?.item;
+                if (item?.type === 'agentMessage' && typeof item.text === 'string' && item.text !== '')
+                    return [{ kind: 'assistant', text: item.text }];
+                if (item?.type !== 'commandExecution' || typeof item.id !== 'string')
+                    return [];
+                return [{ kind: 'tool_end', callId: item.id, tool: 'command', ...(typeof item.aggregatedOutput === 'string' && { output: item.aggregatedOutput.split('\n') }), status: item.status === 'completed' && item.exitCode === 0 ? 'ok' : 'err' }];
+            }
+            case 'thread/tokenUsage/updated':
+                // One update per model call: the turn's usage is what its calls added up to.
+                for (const [key, value] of Object.entries((params?.tokenUsage?.last ?? {})))
+                    if (typeof value === 'number')
+                        this.usage[key] = (this.usage[key] ?? 0) + value;
+                return [];
+            case 'turn/completed':
+                return this.turnEnd(params?.turn);
+            default:
+                return [];
+        }
+    }
+    turnEnd(turn) {
+        const outcome = turn?.status === 'completed' ? 'ok' : turn?.status === 'interrupted' ? 'interrupted' : 'error';
+        const usage = this.usage;
+        this.turning = false;
+        this.turnId = undefined;
+        this.usage = {};
+        const events = [];
+        if (outcome === 'error')
+            events.push({ kind: 'error', text: typeof turn?.error?.message === 'string' ? turn.error.message : 'The turn failed' });
+        events.push({ kind: 'turn_end', outcome, model: this.model, usage });
+        return events;
+    }
+}

package/dist/chat/config.js

@@ -0,0 +1,61 @@
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { LogLevel } from '@ashulab/universal-logger';
+import { z } from 'zod';
+import { carrierHome, expandHome } from '../config/default-path.js';
+/** An agent a chat can start with. Narrower than the engine's harnesses: Antigravity is not offered. */
+export const chatAgent = z.strictObject({
+    harness: z.enum(['claude', 'codex']),
+    /** The binary, when it is not the one on the path. */
+    command: z.string().min(1).optional(),
+    model: z.string().min(1).optional(),
+    /** Default options of the provider, by the provider's own option id. */
+    options: z.record(z.string(), z.string()).optional(),
+});
+export const chatAgentName = /^[a-z][a-z0-9-]*$/;
+/** Days of no activity before the session lifecycle acts (ADR 0019): a whole number, or `"never"` to turn that step off. */
+const days = z.union([z.int().positive(), z.literal('never')]);
+// The chat's own configuration level (ADR 0016): `<folder>/chat/chat.json`, every key optional, strict like the engine's config.
+const chatConfigSchema = z.strictObject({
+    agents: z.record(z.string().regex(chatAgentName, 'a chat agent name is lowercase letters, digits and hyphens, starting with a letter'), chatAgent).optional(),
+    projectsFolder: z.string().min(1).transform(expandHome).refine(isAbsolute, 'must be an absolute path, or start with ~/').optional(),
+    githubCallTimeoutSeconds: z.int().positive().optional(),
+    logLevel: z.enum(LogLevel).optional(),
+    /** A session left alone this long is archived by the host's clock pass. */
+    archiveAfterDays: days.default(15),
+    /** An archived session left alone this long is deleted by the same pass, unless its worktree holds unsaved work; it must be greater than `archiveAfterDays` when both are numbers. */
+    deleteAfterDays: days.default(30),
+}).refine((c) => typeof c.archiveAfterDays !== 'number' || typeof c.deleteAfterDays !== 'number' || c.deleteAfterDays > c.archiveAfterDays, {
+    path: ['deleteAfterDays'],
+    when: (payload) => payload.issues.length === 0, // a value already refused is not also reported against the other
+    error: 'must be greater than archiveAfterDays',
+});
+/** Where the chat keeps what it owns, inside the Carrier folder. */
+export const chatDirOf = (folder = carrierHome()) => join(folder, 'chat');
+export const chatStateOf = (folder = carrierHome()) => join(chatDirOf(folder), 'state');
+export const chatLogsOf = (folder = carrierHome()) => join(chatDirOf(folder), 'logs');
+export const chatSocketOf = (folder = carrierHome()) => join(chatStateOf(folder), 'chat.sock');
+export const chatConfigPathOf = (folder = carrierHome()) => join(chatDirOf(folder), 'chat.json');
+const defaultAgents = { claude: { harness: 'claude' }, codex: { harness: 'codex' } };
+/** The chat's settings from the parsed contents of `chat.json` (`{}` when there is no file), with the defaults for what it leaves out. */
+export function loadChatConfig(user, folder = carrierHome()) {
+    const parsed = chatConfigSchema.safeParse(user);
+    if (parsed.success === false)
+        return { ok: false, errors: parsed.error.issues.map((issue) => ({ path: issue.path.join('.') || '(root)', message: issue.message })) };
+    const { agents = defaultAgents, projectsFolder = join(chatDirOf(folder), 'projects'), githubCallTimeoutSeconds = 30, logLevel = LogLevel.INFO, archiveAfterDays, deleteAfterDays } = parsed.data;
+    return { ok: true, settings: { agents: Object.entries(agents).map(([name, agent]) => ({ name, ...agent })), projectsFolder, githubCallTimeoutSeconds, logLevel, archiveAfterDays, deleteAfterDays } };
+}
+/** `chat.json` read and validated; a file that is not there is the defaults, one that cannot be read or does not match is an error naming the key. */
+export function readChatConfig(folder = carrierHome()) {
+    let user = {};
+    try {
+        user = JSON.parse(readFileSync(chatConfigPathOf(folder), 'utf8'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            return { ok: false, errors: [{ path: '(file)', message: error instanceof SyntaxError ? `is not valid JSON: ${error.message}` : 'cannot be read' }] };
+    }
+    return loadChatConfig(user, folder);
+}
+/** The error a person sees when `chat.json` is wrong: the file and each key with what is wrong with it. */
+export const chatConfigProblem = (folder, errors) => `Invalid chat config ${chatConfigPathOf(folder)}:\n${errors.map((e) => `  ${e.path}: ${e.message}`).join('\n')}`;

package/dist/chat/db.js

@@ -0,0 +1,9 @@
+import Database from 'better-sqlite3';
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import { migrate } from 'drizzle-orm/better-sqlite3/migrator';
+/** `chat.db`: the chat host's own file with its own migrations, so no other process migrates or writes the engine's database. */
+export function openChatDatabase(file) {
+    const db = drizzle(new Database(file));
+    migrate(db, { migrationsFolder: `${import.meta.dirname}/migrations` });
+    return db;
+}

package/dist/chat/fake.js

@@ -0,0 +1,203 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { FakeClock } from '../orchestration/fake.js';
+import { createProjects } from './projects.js';
+import { ChatRefused } from './runner.js';
+/**
+ * A conversation that plays what a test tells it: `reply` runs on each message sent, `emit` plays an event any time
+ * (a turn ends on cue, an approval is asked and stays pending until `answer` is called).
+ */
+export class FakeConversation {
+    options = [];
+    nativeId;
+    process;
+    sent = [];
+    answers = [];
+    closed = false;
+    /** Events to play when a message arrives. */
+    reply = () => { };
+    listeners = [];
+    endListeners = [];
+    /** What the fake lists for the person to invoke; the commands each message invoked go to `invoked`. */
+    commands = [];
+    invoked = [];
+    send(text, command) {
+        this.invoked.push(command?.id);
+        this.sent.push(text);
+        this.reply(text, this);
+    }
+    answer(approvalId, choiceId) {
+        this.answers.push({ approvalId, choiceId });
+        this.emit({ kind: 'approval_answered', approvalId, choiceId });
+    }
+    interrupts = 0;
+    /** Plays what the provider does on an interrupt; by default nothing, as an adapter that never says the turn ended. */
+    onInterrupt = () => { };
+    async interrupt() {
+        this.interrupts++;
+        this.onInterrupt(this);
+    }
+    async setOption(id, value) {
+        const option = this.options.find((o) => o.id === id);
+        if (option)
+            option.current = value;
+        this.emit({ kind: 'option', id, value });
+    }
+    async close() {
+        this.closed = true;
+    }
+    onEvent(listener) {
+        this.listeners.push(listener);
+    }
+    onEnd(listener) {
+        this.endListeners.push(listener);
+    }
+    /** Plays the agent's process ending on its own: the error (and the end of a running turn) as an adapter says them, then the end. */
+    die(...events) {
+        this.emit(...events);
+        for (const listener of this.endListeners)
+            listener();
+    }
+    emit(...events) {
+        for (const event of events)
+            for (const listener of this.listeners)
+                listener(event);
+    }
+}
+/** A runner with no provider behind it: it hands out `FakeConversation`s and remembers what it was asked. */
+export class FakeChatRunner {
+    opened = [];
+    conversations = [];
+    /** Set to make `open` refuse, as a provider that is not installed does. */
+    refuseWith;
+    /** Applied to each new conversation, to script its answers. */
+    setup = () => { };
+    async open(args) {
+        this.opened.push(args);
+        if (this.refuseWith !== undefined)
+            throw new ChatRefused(this.refuseWith);
+        const conversation = new FakeConversation();
+        this.setup(conversation);
+        this.conversations.push(conversation);
+        return conversation;
+    }
+}
+/** A git with a table of folders and the repositories in them, which answers the commands the host sends, and plays scripted failures. */
+export class FakeGit {
+    repos = new Map();
+    /** Every command run, in order. */
+    calls = [];
+    /** While set, a `clone` waits for it (or for its signal to abort) before it ends: a clone that is still running. */
+    clonePending;
+    /** While set, a `worktree add` waits for it (or for its signal to abort) before it makes anything: a worktree that is still being made. */
+    worktreePending;
+    /** Commands that fail instead of answering, by their arguments joined with a space. */
+    failures = new Map();
+    /** What a repository is when it has just been cloned, besides its origin: `head` and `branches` are `main` unless this says otherwise. */
+    cloned = {};
+    progress;
+    /** Plays a line of stderr of the clone that is running, as git writes it. */
+    emitProgress(...lines) {
+        for (const line of lines)
+            this.progress?.(line);
+    }
+    async run(folder, args, options) {
+        this.calls.push({ folder, args, timeoutMs: options?.timeoutMs, env: options?.env });
+        if (args[0] === 'clone') {
+            this.progress = options?.onProgress;
+            // clone -- <url> <dest>: git makes the folder first; a failure or an abort leaves it half made
+            const [url, dest] = args.slice(2);
+            mkdirSync(dest, { recursive: true });
+            const signal = options?.signal;
+            if (this.clonePending !== undefined)
+                await Promise.race([this.clonePending, new Promise((resolve) => signal?.addEventListener('abort', resolve, { once: true }))]);
+            if (signal?.aborted === true)
+                return { ok: false, code: null, stderr: 'killed' };
+            const failure = this.failures.get(args.join(' '));
+            if (failure !== undefined)
+                return failure;
+            mkdirSync(join(dest, '.git'));
+            this.repos.set(dest, { head: 'main', branches: ['main'], ...structuredClone(this.cloned), origin: url });
+            return { ok: true, out: '' };
+        }
+        if (args[0] === 'init') {
+            // init -b <branch>: a failure leaves a half-made .git, as git can
+            mkdirSync(join(folder, '.git'), { recursive: true });
+            const failure = this.failures.get(args.join(' '));
+            if (failure !== undefined)
+                return failure;
+            this.repos.set(folder, { head: args[2], branches: [] });
+            return { ok: true, out: '' };
+        }
+        const failure = this.failures.get(args.join(' '));
+        if (failure !== undefined)
+            return failure;
+        const repo = this.repos.get(folder);
+        if (repo === undefined)
+            return { ok: false, code: 128, stderr: 'fatal: not a git repository' };
+        const out = (...printed) => ({ ok: true, out: printed.map((line) => `${line}\n`).join('') });
+        const no = { ok: false, code: 1, stderr: '' };
+        const [verb, ...rest] = args[0] === '--no-optional-locks' ? args.slice(1) : args;
+        if (verb === 'rev-parse' && rest.includes('--verify'))
+            return [...repo.branches.map((name) => `refs/heads/${name}`), ...(repo.remoteBranches ?? []).map((name) => `refs/remotes/origin/${name}`)].includes(rest.at(-1)) ? out(rest.at(-1)) : no;
+        if (verb === 'worktree' && rest[0] === 'add') {
+            const signal = options?.signal;
+            if (this.worktreePending !== undefined)
+                await Promise.race([this.worktreePending, new Promise((resolve) => signal?.addEventListener('abort', resolve, { once: true }))]);
+            if (signal?.aborted === true)
+                return { ok: false, code: null, stderr: 'killed' };
+            // worktree add --no-track -b <branch> <path> <start>: the branch and the folder appear, as git makes them
+            const [branch, path, start] = rest.slice(3);
+            const known = [...repo.branches.map((name) => `refs/heads/${name}`), ...(repo.remoteBranches ?? []).map((name) => `refs/remotes/origin/${name}`)];
+            if (repo.branches.includes(branch) || known.includes(start) === false)
+                return { ok: false, code: 128, stderr: 'fatal: invalid reference' };
+            mkdirSync(path, { recursive: true });
+            repo.branches.push(branch);
+            (repo.worktrees ??= []).push({ path: path, branch: branch });
+            return out();
+        }
+        if (verb === 'worktree' && rest[0] === 'remove') {
+            rmSync(rest.at(-1), { recursive: true, force: true });
+            repo.worktrees = (repo.worktrees ?? []).filter((worktree) => worktree.path !== rest.at(-1));
+            return out();
+        }
+        if (verb === 'worktree' && rest[0] === 'prune')
+            return out();
+        if (verb === 'branch' && rest[0] === '-D') {
+            if (repo.branches.includes(rest[1]) === false)
+                return { ok: false, code: 1, stderr: 'error: branch not found' };
+            repo.branches = repo.branches.filter((name) => name !== rest[1]);
+            return out();
+        }
+        if (verb === 'rev-parse')
+            return out(String(repo.bare === true), repo.linked ? '/elsewhere/.git/worktrees/w' : '.git', repo.linked ? '/elsewhere/.git' : '.git', repo.fetchHead ?? '.git/FETCH_HEAD');
+        if (verb === 'config')
+            return repo.origin === undefined ? no : out(repo.origin);
+        if (verb === 'symbolic-ref' && rest.includes('refs/remotes/origin/HEAD'))
+            return repo.originHead === undefined ? no : out(`refs/remotes/origin/${repo.originHead}`);
+        if (verb === 'symbolic-ref')
+            return repo.head === null ? no : out(repo.head);
+        if (verb === 'for-each-ref')
+            return out(...repo.branches.map((name) => `refs/heads/${name}`), ...(repo.remoteBranches ?? []).map((name) => `refs/remotes/origin/${name}`), ...(repo.originHead === undefined ? [] : ['refs/remotes/origin/HEAD']));
+        if (verb === 'rev-list')
+            return out(String(repo.unpushed?.[rest[1].replace('refs/heads/', '')] ?? 0));
+        if (verb === 'switch') {
+            // switch <branch>, or switch --track origin/<branch>, which makes the local branch
+            const target = rest.at(-1);
+            const local = target.replace(/^origin\//, '');
+            if (rest[0] === '--track')
+                repo.branches.push(local);
+            else if (repo.branches.includes(target) === false)
+                return { ok: false, code: 128, stderr: 'fatal: invalid reference' };
+            repo.head = local;
+            return out();
+        }
+        if (verb === 'fetch')
+            return out();
+        if (verb === 'status')
+            return out(...(repo.status ?? []));
+        return { ok: false, code: 129, stderr: `the fake git does not know ${verb}` };
+    }
+}
+/** What brings repositories onto the Mac, over a fake git and a fake `gh`: the token is `ghp_fake`, GitHub lists nothing and knows `main` and `feat/x` for any repository. */
+export const fakeProjects = (git, clock = new FakeClock(), github = {}) => createProjects({ git, clock, token: async () => 'ghp_fake', github: { repos: async () => ({ repos: [], hasMore: false }), login: async () => 'me', branches: async () => ({ default: 'main', branches: ['main', 'feat/x'], hasMore: false }), ...github } });