@ashulab/carrier 0.0.0-stage → 0.1.1

package/dist/chat/sweep.js

@@ -0,0 +1,64 @@
+import { execFileSync } from 'node:child_process';
+import { eq, isNotNull } from 'drizzle-orm';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { sessions } from './schema.js';
+const log = createScopedLogger('chat');
+export const realProcesses = {
+    commandOf(pid) {
+        try {
+            return execFileSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
+        }
+        catch {
+            return undefined; // ps exits 1 when there is no such process
+        }
+    },
+    groupAlive(pgid) {
+        try {
+            process.kill(-pgid, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code === 'EPERM'; // alive but not ours
+        }
+    },
+    signalGroup(pgid, signal) {
+        try {
+            process.kill(-pgid, signal);
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                throw error;
+        }
+    },
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+export const SWEEP_GRACE_MS = 5_000;
+/**
+ * At host start: ends the agent groups a dead host left running (SIGTERM, then SIGKILL after the grace) and closes their
+ * sessions, which stay resumable by their native id. A recorded process whose command is not the recorded one is not
+ * ours any more (the pid was reused): it is left alone and only the record is cleared. A group that could not be ended
+ * keeps its record so the next start tries again. Returns how many groups it ended.
+ */
+export async function sweepDeadHost(db, processes = realProcesses, graceMs = SWEEP_GRACE_MS) {
+    let ended = 0;
+    for (const found of db.select().from(sessions).where(isNotNull(sessions.pid)).all()) {
+        try {
+            const { pid, pgid, command } = found;
+            const ours = pid !== null && pgid !== null && command !== null && processes.commandOf(pid)?.startsWith(command) === true;
+            if (ours && processes.groupAlive(pgid)) {
+                processes.signalGroup(pgid, 'SIGTERM');
+                for (let waited = 0; waited < graceMs && processes.groupAlive(pgid); waited += 100)
+                    await processes.sleep(100);
+                if (processes.groupAlive(pgid))
+                    processes.signalGroup(pgid, 'SIGKILL');
+                ended++;
+                log.info('ended an agent a dead host left running', { sessionId: found.id, pgid });
+            }
+            db.update(sessions).set({ state: 'idle', pid: null, pgid: null, command: null }).where(eq(sessions.id, found.id)).run();
+        }
+        catch (error) {
+            log.error('sweeping a session of a dead host failed', error);
+        }
+    }
+    return ended;
+}

package/dist/chat/transcript.js

@@ -0,0 +1,31 @@
+import { boundOutput, clean } from '../execution/events.js';
+// Characters, not bytes. The limits of a conversation, not of an epic's log (spec: The record).
+export const chatCaps = { message: 64_000, arg: 1024, title: 80, error: 4096 };
+/** What is stored of an event: redacted first and then cut, so a secret is never cut in a way that hides its shape. A `delta` is not stored. */
+export function boundEvent(event) {
+    switch (event.kind) {
+        case 'delta':
+            return undefined;
+        case 'user':
+            return { text: clean(event.text, chatCaps.message), ...(event.command !== undefined && { command: event.command }) };
+        case 'assistant':
+            return { text: clean(event.text, chatCaps.message) };
+        case 'error':
+            return { text: clean(event.text, chatCaps.error) };
+        case 'tool_start':
+        case 'tool_end': {
+            const { kind: _kind, arg, output, ...rest } = event;
+            return { ...rest, ...(arg !== undefined && { arg: clean(arg, chatCaps.arg) }), ...(output !== undefined && { output: boundOutput(output.join('\n')) }) };
+        }
+        case 'approval': {
+            const { kind: _kind, arg, ...rest } = event;
+            return { ...rest, ...(arg !== undefined && { arg: clean(arg, chatCaps.arg) }) };
+        }
+        default: {
+            const { kind: _kind, ...rest } = event;
+            return rest;
+        }
+    }
+}
+/** The title of a session: the first line of its first message, cut. */
+export const titleOf = (text) => clean(text.trim().split('\n')[0], chatCaps.title);

package/dist/chat/words.js

@@ -0,0 +1,20 @@
+// The words a worktree's generated name is made of: `<adjective>-<unit>-<place>`. Lowercase single words from
+// StarCraft's units, structures and tech, never a character's full name (ADR 0014).
+export const adjectives = [
+    'psionic', 'cloaked', 'burrowed', 'sieged', 'nuclear', 'plasma', 'ionic', 'adaptive', 'stimmed', 'hallucinated',
+    'irradiated', 'parasitic', 'spawning', 'vespene', 'hardened', 'infested', 'mutated', 'consumed', 'ensnared', 'plagued',
+    'charged', 'cybernetic', 'khaydarin', 'twilight', 'dark', 'void', 'shielded', 'armored', 'swift', 'tactical',
+    'orbital', 'enslaved', 'recalled', 'warped', 'cerebrate',
+];
+export const units = [
+    'marine', 'firebat', 'medic', 'ghost', 'vulture', 'goliath', 'wraith', 'valkyrie', 'battlecruiser', 'dropship',
+    'zealot', 'dragoon', 'archon', 'reaver', 'corsair', 'scout', 'carrier', 'arbiter', 'observer', 'shuttle',
+    'probe', 'scv', 'zergling', 'hydralisk', 'mutalisk', 'ultralisk', 'lurker', 'defiler', 'guardian', 'devourer',
+    'overlord', 'queen', 'drone', 'scourge', 'templar', 'interceptor', 'tank', 'broodling',
+];
+export const places = [
+    'bunker', 'barracks', 'factory', 'starport', 'nexus', 'pylon', 'gateway', 'forge', 'cannon', 'assimilator',
+    'hatchery', 'lair', 'hive', 'spire', 'extractor', 'refinery', 'academy', 'armory', 'depot', 'turret',
+    'comsat', 'nydus', 'citadel', 'stargate', 'beacon', 'observatory', 'tribunal', 'aiur', 'char', 'korhal',
+    'tarsonis', 'shakuras', 'zerus', 'braxis', 'bhekar',
+];

package/dist/chat/workspace.js

@@ -0,0 +1,134 @@
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { ChatRefused } from './runner.js';
+const log = createScopedLogger('chat');
+const lines = (out) => out.split('\n').filter((line) => line !== '');
+/** `owner/name` of a GitHub remote in its https or ssh form (with or without `.git`, a trailing slash or credentials); null for any other remote. */
+export function parseOrigin(url) {
+    const found = /^(?:https:\/\/(?:[^@/\s]+@)?github\.com\/|(?:ssh:\/\/)?git@github\.com[:/])([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/i.exec(url.trim());
+    if (found === null || [found[1], found[2]].some((part) => part === '.' || part === '..'))
+        return null;
+    return { owner: found[1], name: found[2] };
+}
+/** The number of lines `git status --porcelain` printed. */
+export const countPorcelain = (out) => lines(out).length;
+/** From `for-each-ref --format=%(refname) refs/heads refs/remotes/origin`: local branches, then `origin/x` ones, `origin/HEAD` left out. */
+export function parseBranches(out) {
+    const found = [];
+    for (const ref of lines(out)) {
+        if (ref.startsWith('refs/heads/'))
+            found.push({ name: ref.slice('refs/heads/'.length), remote: false });
+        else if (ref.startsWith('refs/remotes/origin/') && ref !== 'refs/remotes/origin/HEAD')
+            found.push({ name: ref.slice('refs/remotes/'.length), remote: true });
+    }
+    return found.sort((a, b) => Number(a.remote) - Number(b.remote)); // stable: each group stays in git's order
+}
+/** `origin/HEAD` (`symbolic-ref` printed `refs/remotes/origin/main`) when set, else `main`, else `master` when listed, else null. */
+export function parseDefaultBranch(originHead, branches) {
+    const prefix = 'refs/remotes/origin/';
+    const head = originHead?.trim() ?? '';
+    if (head.startsWith(prefix) && head.length > prefix.length)
+        return head.slice(prefix.length);
+    return ['main', 'master'].find((name) => branches.some((branch) => branch.name === name || branch.name === `origin/${name}`)) ?? null;
+}
+const refused = () => new ChatRefused('Git could not read that folder');
+/** A command whose failure with exit status 1 is an answer ("not set", "detached"): the output, or null for that answer; any other failure refuses. */
+function answer(result, what) {
+    if (result.ok)
+        return result.out.trim();
+    if (result.code === 1)
+        return null;
+    log.error(`git ${what} failed`, { code: result.code });
+    throw refused();
+}
+function mustRun(result, what) {
+    if (result.ok)
+        return result.out;
+    log.error(`git ${what} failed`, { code: result.code });
+    throw refused();
+}
+const mtimeOf = (path) => {
+    try {
+        return Math.floor(statSync(path).mtimeMs);
+    }
+    catch {
+        return null;
+    }
+};
+/** Asks git what `folder` (already checked, a real path) is. A folder git does not know as a repository answers `git: false`. */
+export async function inspectFolder(git, folder) {
+    const plain = { folder, git: false, bare: false, linkedWorktree: false, repo: null, branch: null, defaultBranch: null, dirty: 0, branches: [], fetchedAt: null };
+    const probe = await git.run(folder, ['rev-parse', '--is-bare-repository', '--git-dir', '--git-common-dir', '--git-path', 'FETCH_HEAD']);
+    if (probe.ok === false && probe.code === 128)
+        return plain; // "not a git repository"
+    const printed = lines(mustRun(probe, 'rev-parse'));
+    const [bare, gitDir, commonDir, fetchHead] = printed;
+    if (fetchHead === undefined) {
+        log.error('git rev-parse printed no FETCH_HEAD path', { printed: printed.length });
+        throw refused();
+    }
+    const isBare = bare === 'true';
+    const [url, branch, originHead, refs, status] = await Promise.all([
+        git.run(folder, ['config', '--get', 'remote.origin.url']),
+        git.run(folder, ['symbolic-ref', '-q', '--short', 'HEAD']),
+        git.run(folder, ['symbolic-ref', '-q', 'refs/remotes/origin/HEAD']),
+        git.run(folder, ['for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/remotes/origin']),
+        isBare ? Promise.resolve({ ok: true, out: '' }) : git.run(folder, ['--no-optional-locks', 'status', '--porcelain']),
+    ]);
+    const branches = parseBranches(mustRun(refs, 'for-each-ref'));
+    const origin = answer(url, 'config');
+    return {
+        folder,
+        git: true,
+        bare: isBare,
+        linkedWorktree: resolve(folder, gitDir) !== resolve(folder, commonDir),
+        repo: origin === null ? null : parseOrigin(origin),
+        branch: answer(branch, 'symbolic-ref') || null,
+        defaultBranch: parseDefaultBranch(answer(originHead, 'symbolic-ref'), branches),
+        dirty: countPorcelain(mustRun(status, 'status')),
+        branches,
+        fetchedAt: mtimeOf(resolve(folder, fetchHead)),
+    };
+}
+/** What a fetch may take before the host gives up on it. */
+export const FETCH_TIMEOUT_MS = 60_000;
+/** Runs `git fetch origin --prune` in `folder` (already checked, a real path) and answers what the folder is after it. A refusal never carries git's own words: they can hold a URL or a token. */
+export async function fetchFolder(git, folder) {
+    const probe = await git.run(folder, ['rev-parse', '--git-dir']);
+    if (probe.ok === false && probe.code === 128)
+        throw new ChatRefused('That folder is not a git repository');
+    mustRun(probe, 'rev-parse');
+    if (answer(await git.run(folder, ['config', '--get', 'remote.origin.url']), 'config') === null)
+        throw new ChatRefused('That repository has no origin remote to fetch');
+    const fetched = await git.run(folder, ['fetch', 'origin', '--prune'], { timeoutMs: FETCH_TIMEOUT_MS });
+    if (fetched.ok === false) {
+        log.error('git fetch failed', { code: fetched.code, timedOut: fetched.timedOut === true });
+        throw new ChatRefused(fetched.timedOut === true ? 'The fetch took too long and was stopped' : 'The fetch of origin failed');
+    }
+    return inspectFolder(git, folder);
+}
+/**
+ * Checks out `branch` (a name `inspectFolder` lists) in `folder` (already checked, a real path), so the folder follows what the person picked. A folder
+ * with uncommitted changes is never switched: it refuses with the reason in words and the branch is left as it was. A remote branch is checked out as
+ * a local one that tracks it, or as the local one of the same name when there is one.
+ */
+export async function checkout(git, folder, branch) {
+    const info = await inspectFolder(git, folder);
+    if (info.git === false || info.bare)
+        throw new ChatRefused('That folder is not a git repository with a working folder, so it has no branch to check out');
+    const listed = info.branches.find((candidate) => candidate.name === branch);
+    if (listed === undefined)
+        throw new ChatRefused('That branch is not one this repository lists');
+    if (info.branch === branch)
+        return;
+    if (info.dirty > 0)
+        throw new ChatRefused(`The folder has ${info.dirty} uncommitted ${info.dirty === 1 ? 'file' : 'files'}, so its branch was not changed to ${branch}. Save the work and try again.`);
+    const local = listed.remote ? branch.slice('origin/'.length) : branch;
+    const twin = listed.remote && info.branches.some((candidate) => candidate.remote === false && candidate.name === local);
+    const switched = await git.run(folder, listed.remote && twin === false ? ['switch', '--track', branch] : ['switch', local]);
+    if (switched.ok === false) {
+        log.error('git switch failed', { code: switched.code, timedOut: switched.timedOut === true });
+        throw new ChatRefused(`Git could not check out ${branch}`);
+    }
+}

package/dist/chat/worktree.js

@@ -0,0 +1,142 @@
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { BRANCH_PREFIX, invalidReason, repository, worktreePath, worktreesDir } from './names.js';
+import { ChatRefused } from './runner.js';
+import { countPorcelain } from './workspace.js';
+const log = createScopedLogger('chat');
+/** What a checkout of a big repository may take before the host gives up on it. */
+const ADD_TIMEOUT_MS = 60_000;
+/**
+ * Creates `<CARRIER_HOME>/chat/worktrees/<owner>/<repo>/<name>` on a new branch `carrier/<name>` cut from `from`, in the
+ * repository of `folder` (already checked, a real path). The base folder is only read: git adds the worktree without a
+ * checkout, stash or commit in it. Refuses, with a reason in words, a folder that is not a repository or is bare, a `from`
+ * that `workspace` does not list and a name that is invalid or taken. When git fails nothing is left behind.
+ * Callers run it one at a time, so what it checked is still true when git adds. `signal` stops the add, and what it made is taken away.
+ */
+export async function createWorktree(git, folder, request, signal) {
+    const { info, takenBecause, freeName } = await repository(git, folder);
+    const start = info.branches.find((branch) => branch.name === request.from);
+    if (start === undefined)
+        throw new ChatRefused('The branch to start from is not one this repository lists');
+    if (request.name !== undefined) {
+        const refusal = invalidReason(request.name) ?? takenBecause(request.name);
+        if (refusal !== null)
+            throw new ChatRefused(refusal);
+    }
+    const name = request.name ?? freeName();
+    const made = { path: worktreePath(info, name), branch: `${BRANCH_PREFIX}${name}`, from: start.name, base: folder };
+    // What is absent right before the add is what this call may take away if the add fails: a branch or folder that appears in between is someone else's.
+    const mine = {
+        branch: (await branchExists(git, folder, made.branch)) === false,
+        folder: existsSync(made.path) === false,
+    };
+    // The start point is spelled as a full ref, so it cannot read as an option, and `--no-track` leaves the new branch without an upstream.
+    const added = await git.run(folder, ['worktree', 'add', '--no-track', '-b', made.branch, made.path, `${start.remote ? 'refs/remotes/' : 'refs/heads/'}${start.name}`], { timeoutMs: ADD_TIMEOUT_MS, signal });
+    if (added.ok === false) {
+        log.error('git worktree add failed', { code: added.code, timedOut: added.timedOut === true });
+        await removeWorktree(git, made, mine);
+        throw new ChatRefused(added.timedOut === true ? 'Creating the worktree took too long and was stopped' : 'Git could not create the worktree');
+    }
+    return made;
+}
+/** Whether `refs/heads/<branch>` exists in `base`. A missing branch is an answer; any other git failure refuses, since guessing would decide what gets deleted. */
+async function branchExists(git, base, branch) {
+    const found = await git.run(base, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]);
+    if (found.ok)
+        return true;
+    if (found.code === 1)
+        return false;
+    log.error('git could not tell whether a branch exists', { code: found.code, timedOut: found.timedOut === true });
+    throw new ChatRefused('Git could not read the branches of the repository');
+}
+/** Removes a folder Carrier made. One that cannot be removed is logged and left, and `false` says so. */
+function removeFolder(path) {
+    try {
+        rmSync(path, { recursive: true, force: true });
+        return true;
+    }
+    catch (error) {
+        log.error('a worktree folder could not be removed', error);
+        return false;
+    }
+}
+/** Takes away what `createWorktree` made, whatever state it was left in: the worktree, its folder and its branch. `mine` leaves alone the branch or the folder this call did not make. Never throws; what cannot be removed is logged. */
+export async function removeWorktree(git, { path, branch, base }, mine = { branch: true, folder: true }) {
+    if (mine.folder) {
+        await git.run(base, ['worktree', 'remove', '--force', path]);
+        if (existsSync(path))
+            removeFolder(path);
+        await git.run(base, ['worktree', 'prune']);
+    }
+    if (mine.branch === false)
+        return;
+    const exists = await git.run(base, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]);
+    if (exists.ok === false) {
+        if (exists.code !== 1)
+            log.error('git could not tell whether the branch of a worktree that was not kept exists', { code: exists.code });
+        return;
+    }
+    const deleted = await git.run(base, ['branch', '-D', branch]);
+    if (deleted.ok === false)
+        log.error('the branch of a worktree that was not kept could not be removed', { code: deleted.code });
+}
+/** The number `git rev-list --count` printed. */
+export const parseCount = (out) => Number.parseInt(out.trim(), 10) || 0;
+/** The entries a worktree folder holds besides its `.git` link: what is left to lose when git cannot read the worktree. */
+const filesLeft = (path) => (existsSync(path) ? readdirSync(path).filter((entry) => entry !== '.git').length : 0);
+/** The path of a recorded worktree, which must be `<worktrees>/<owner>/<repo>/<name>` with the branch `carrier/<name>`; refuses anything else, so a tampered record removes nothing. */
+function recorded({ path, branch }) {
+    const target = resolve(path);
+    const root = resolve(worktreesDir());
+    const [owner, repo, name, ...deeper] = target.startsWith(root + sep) ? target.slice(root.length + 1).split(sep) : [];
+    if (owner === undefined || repo === undefined || name === undefined || deeper.length > 0 || invalidReason(name) !== null || branch !== `${BRANCH_PREFIX}${name}`)
+        throw new ChatRefused('This session\'s worktree is not one Carrier made, so nothing was removed');
+    return target;
+}
+/** What deleting a worktree would discard: the lines `git status --porcelain` prints in it and the commits of its branch that no other branch of `batch` (the branches of the sessions deleted together, this one included) or remote branch contains. With the base folder gone git reads nothing and the commits went with it, so only the files left in the worktree folder count. A branch that is already gone has no commits to lose. */
+export async function previewWorktree(git, made, batch) {
+    if (existsSync(made.base) === false)
+        return { dirty: filesLeft(made.path), unpushed: 0 };
+    const where = existsSync(made.path) ? made.path : made.base;
+    const hasBranch = await branchExists(git, made.base, made.branch);
+    const [status, ahead] = await Promise.all([
+        where === made.path ? git.run(where, ['--no-optional-locks', 'status', '--porcelain']) : Promise.resolve({ ok: true, out: '' }),
+        // the branch is spelled as a full ref and each exclusion is a value of its own option, so neither can read as an option
+        hasBranch ? git.run(where, ['rev-list', '--count', `refs/heads/${made.branch}`, '--not', ...[...new Set([made.branch, ...batch])].map((branch) => `--exclude=${branch}`), '--branches', '--remotes']) : Promise.resolve({ ok: true, out: '0' }),
+    ]);
+    if (status.ok === false || ahead.ok === false) {
+        log.error('git could not read a worktree to preview its deletion', { status: status.ok ? 0 : status.code, ahead: ahead.ok ? 0 : ahead.code });
+        throw new ChatRefused('Git could not read the worktree of a session');
+    }
+    return { dirty: countPorcelain(status.out), unpushed: parseCount(ahead.out) };
+}
+/**
+ * Removes the worktree a session recorded, then its recorded branch, and refuses with a reason in words when git cannot, so the session stays.
+ * Only a path under the worktrees folder is touched. When the base folder is gone git cannot do it: the worktree folder is removed directly and the branch is left.
+ */
+export async function deleteWorktree(git, made) {
+    const path = recorded(made);
+    if (existsSync(made.base) === false) {
+        if (removeFolder(path) === false)
+            throw new ChatRefused('Its folder could not be removed, so the session was kept');
+        return;
+    }
+    const cannot = (what, result) => {
+        log.error(`git ${what} failed while deleting a worktree`, { code: result.code, timedOut: result.timedOut === true });
+        return new ChatRefused(`Git could not ${what === 'branch' ? 'delete the branch of' : 'remove'} the worktree, so the session was kept`);
+    };
+    // a folder that is already gone only leaves its entry for git to forget
+    const removed = await git.run(made.base, existsSync(path) ? ['worktree', 'remove', '--force', path] : ['worktree', 'prune']);
+    if (removed.ok === false)
+        throw cannot('worktree', removed);
+    const found = await git.run(made.base, ['rev-parse', '--verify', '--quiet', `refs/heads/${made.branch}`]);
+    if (found.ok === false) {
+        if (found.code === 1)
+            return; // the branch is already gone
+        throw cannot('branch', found);
+    }
+    const deleted = await git.run(made.base, ['branch', '-D', made.branch]);
+    if (deleted.ok === false)
+        throw cannot('branch', deleted);
+}

package/dist/config/default-path.js

@@ -0,0 +1,7 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const expandHome = (path) => (path === '~' || path.startsWith('~/') ? join(homedir(), path.slice(1)) : path);
+/** Carrier's home: `CARRIER_HOME`, else `~/.carrier`. Holds the engine's config and one subfolder per process (`engine/`, `chat/`). */
+export const carrierHome = () => process.env.CARRIER_HOME || join(homedir(), '.carrier');
+/** Where `carrier init` writes the config and where `carrier` looks when there is no `--config`: global, one per user. */
+export const defaultConfigPath = () => join(carrierHome(), 'config.json');

package/dist/config/engine-places.js

@@ -0,0 +1,9 @@
+import { join } from 'node:path';
+/** The control socket in an engine state folder; the server opens it from the folder it is given. */
+export const controlSocketIn = (state) => join(state, 'control.sock');
+/** The engine's places, all computed from the Carrier folder here and nowhere else. */
+export function enginePlacesOf(folder) {
+    const dir = join(folder, 'engine');
+    const state = join(dir, 'state');
+    return { dir, state, socket: controlSocketIn(state), db: join(state, 'carrier.db'), logs: join(dir, 'logs'), repos: join(dir, 'repos'), reviews: join(dir, 'reviews'), worktrees: join(dir, 'worktrees') };
+}

package/dist/config/json-schema.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { defaults } from './load.js';
+import { configSchema } from './schema.js';
+// The file is merged over `defaults` before the schema sees it, so what has a default is not required of the user.
+function optionalWhereDefaulted(schema, base) {
+    schema.required = schema.required?.filter((key) => !(key in base));
+    for (const [key, value] of Object.entries(base)) {
+        const child = schema.properties?.[key];
+        if (child && typeof value === 'object' && value !== null)
+            optionalWhereDefaulted(child, value);
+    }
+    return schema;
+}
+/** JSON Schema of the config file as the user writes it, for editors and for agents that write it. */
+export const userConfigJsonSchema = () => optionalWhereDefaulted(z.toJSONSchema(configSchema, { io: 'input' }), defaults);

package/dist/config/load.js

@@ -0,0 +1,48 @@
+import { configSchema } from './schema.js';
+export const defaults = {
+    pollIntervalMinutes: 5,
+    finishedWindowDays: 15,
+    logLevel: 'info',
+    identities: 'separate',
+    limits: {
+        maxConcurrentEpics: 3,
+        maxReviews: 5,
+        maxExecutionRetries: 3,
+        maxExecutionHours: 4,
+        githubCallTimeoutSeconds: 30,
+        optionChoiceSeconds: 60,
+    },
+};
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// Objects merge per field; anything else (scalars, arrays, mismatched types) is replaced as-is
+// and left for the schema to reject.
+function merge(base, override) {
+    if (!isObject(base) || !isObject(override))
+        return override;
+    const result = { ...base };
+    for (const [key, value] of Object.entries(override))
+        result[key] = merge(base[key], value);
+    return result;
+}
+const movedKeys = ['option'];
+export function loadConfig(base, user) {
+    const parsed = configSchema.safeParse(merge(base, user));
+    if (parsed.success)
+        return { ok: true, config: parsed.data };
+    return {
+        ok: false,
+        errors: parsed.error.issues.flatMap((issue) => {
+            const path = issue.path.join('.') || '(root)';
+            if (issue.code === 'unrecognized_keys' && issue.path.includes('agents')) {
+                const moved = issue.keys.filter((key) => movedKeys.includes(key));
+                if (moved.length > 0) {
+                    return moved.map((key) => ({
+                        path: `${path}.${key}`,
+                        message: `"${key}" was replaced by "provider" and "model" directly on the agent (see docs/configuration.md)`,
+                    }));
+                }
+            }
+            return [{ path, message: issue.message }];
+        }),
+    };
+}

package/dist/config/resolve.js

@@ -0,0 +1,41 @@
+// Two names can point at the same bot or at the same `gh` login: what matters is the account that posts.
+export const sameAccount = (a, b) => a.kind === b.kind && (a.kind === 'gh' || a.agent === b.agent);
+/** Returns the failover order for a specific role: role-specific chain if configured, else default chain. */
+export function failoverOrderFor(failover, role) {
+    if (!failover?.enabled)
+        return undefined;
+    return failover.roles?.[role] ?? failover.default ?? failover.order;
+}
+// Each repo inherits the global value of every field it does not override.
+export function resolveRepoConfig(config, repo) {
+    const roleOf = (role) => {
+        const base = config.agents[role];
+        const repoAgent = repo.agents?.[role];
+        if (!base && !repoAgent)
+            return undefined;
+        const merged = { ...(base ?? {}), ...(repoAgent ?? {}) };
+        if (!merged.profile)
+            return undefined;
+        const providerConfig = merged.provider ? config.providers[merged.provider] : undefined;
+        return {
+            profile: merged.profile,
+            harness: providerConfig?.harness ?? 'claude',
+            model: merged.model ?? providerConfig?.model ?? '',
+            ...(providerConfig?.provider && { provider: providerConfig.provider }),
+            ...(providerConfig?.configDir && { configDir: providerConfig.configDir }),
+            ...(merged.persona && { persona: merged.persona }),
+            option: merged.provider,
+            providerName: merged.provider,
+        };
+    };
+    const leadReviewer = roleOf('leadReviewer');
+    const agents = { author: roleOf('author'), reviewer: roleOf('reviewer'), ...(leadReviewer ? { leadReviewer } : {}) };
+    const [author, reviewer] = [config.profiles[agents.author?.profile], config.profiles[agents.reviewer?.profile]];
+    return {
+        name: repo.name,
+        sharedIdentity: author !== undefined && reviewer !== undefined && sameAccount(author, reviewer),
+        providers: config.providers,
+        ...(config.failover && { failover: config.failover }),
+        agents,
+    };
+}