@ashulab/carrier 0.0.0-stage → 0.1.1

package/dist/doctor/doctor.js

@@ -0,0 +1,255 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { socketPathFits } from '../control/server.js';
+import { enginePlacesOf } from '../config/engine-places.js';
+import { resolveRepoConfig, sameAccount } from '../config/resolve.js';
+import { profileToken } from '../execution/git-workspaces.js';
+import { forgeCwd } from '../integrations/forge-cwd.js';
+import { GhGitHub } from '../integrations/github.js';
+import { listLocalModels, localLabel, localUrl } from '../harnesses/local.js';
+import { configDirVariable } from '../harnesses/names.js';
+import { fixes, installFix } from './fixes.js';
+const log = createScopedLogger('doctor');
+const LOGIN_TIMEOUT_MS = 20_000;
+const AGY_TIMEOUT_MS = 30_000; // logged in answers in about five seconds
+const AGY_LOGGED_OUT = 'Authentication required';
+// Antigravity has no status command, so ask for /usage: it costs nothing. The stderr is never kept past the first line (it holds the login URL).
+function startAgy() {
+    const cwd = mkdtempSync(join(tmpdir(), 'carrier-agy-'));
+    const child = spawn('agy', ['-p', '/usage', '--output-format', 'json'], { cwd, env: { ...process.env, BROWSER: 'true' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    child.once('close', () => rmSync(cwd, { recursive: true, force: true }));
+    return child;
+}
+/** 'in' on status SUCCESS, 'out' at the first stderr line asking for login (the process is killed then, not awaited), 'unknown' otherwise. */
+function agyLogin(deps) {
+    return new Promise((resolve, reject) => {
+        const child = deps.startAgy();
+        let out = '';
+        let err = '';
+        let settled = false;
+        const settle = (verdict) => {
+            if (settled)
+                return; // killing the process closes it, which comes back here
+            settled = true;
+            clearTimeout(timer);
+            resolve(verdict);
+            child.kill();
+        };
+        const timer = setTimeout(() => settle('unknown'), AGY_TIMEOUT_MS);
+        child.once('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.stdout.on('data', (chunk) => (out += chunk));
+        child.stderr.on('data', (chunk) => {
+            if (err.length < AGY_LOGGED_OUT.length)
+                err += chunk; // only the start of the first line matters
+            if (err.startsWith(AGY_LOGGED_OUT))
+                settle('out');
+        });
+        child.once('close', () => {
+            try {
+                settle(JSON.parse(out).status === 'SUCCESS' ? 'in' : 'unknown');
+            }
+            catch {
+                settle('unknown');
+            }
+        });
+    });
+}
+// Reads only the verdict: the output holds an email and an organisation, which never leave this function.
+// Async, so the wizard and the doctor's spinner go on while the CLI answers. After the timeout the whole process group is killed and the
+// probe rejects at once: a CLI that traps SIGTERM, or leaves a child holding the pipe, cannot keep it waiting.
+export function cliLoggedIn(harness, configDir, timeoutMs = LOGIN_TIMEOUT_MS) {
+    const env = configDir ? { ...process.env, [configDirVariable[harness]]: configDir } : process.env;
+    const [command, args] = harness === 'claude' ? ['claude', ['auth', 'status']] : ['codex', ['login', 'status']];
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { env, stdio: ['ignore', 'pipe', 'ignore'], detached: true });
+        let out = '';
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => (out += chunk));
+        const timer = setTimeout(() => {
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                child.kill('SIGKILL'); // no process group to signal (not POSIX), or it is already gone
+            }
+            reject(new Error(`${command} ${args.join(' ')} did not answer in ${timeoutMs / 1000} s`));
+        }, timeoutMs);
+        child.once('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.once('close', (status) => {
+            clearTimeout(timer);
+            if (harness === 'codex')
+                return resolve(status === 0);
+            try {
+                resolve(JSON.parse(out).loggedIn === true);
+            }
+            catch {
+                // the parse error carries the start of the output: only this fixed text is logged and thrown
+                log.warn('could not read the output of claude auth status');
+                reject(new Error('could not read the output of claude auth status'));
+            }
+        });
+    });
+}
+const realDeps = {
+    localModels: (local) => listLocalModels(local),
+    loggedIn: cliLoggedIn,
+    startAgy,
+    which: (command) => spawnSync('which', [command]).status === 0,
+    mint: (profile, repo) => profileToken(profile)(repo),
+    listLabels: (config, repo, folder) => new GhGitHub({
+        profile: config.profiles[config.orchestratorProfile],
+        cwd: forgeCwd(enginePlacesOf(folder)),
+        timeoutMs: config.limits.githubCallTimeoutSeconds * 1000,
+    }).listLabels(repo),
+};
+const identity = (profile) => (profile.kind === 'forge' ? `forge agent ${profile.agent}` : 'your gh login');
+const message = (error) => (error instanceof Error ? error.message : String(error));
+/** What the machine has to be able to do, and whether each identity can act on each repo. Reads only; creates nothing on GitHub. */
+export async function runDoctor(config, folder, overrides = {}, onCheck = () => { }, onStart = () => { }) {
+    const deps = { ...realDeps, ...overrides };
+    const checks = [];
+    const report = (check) => {
+        if (check.fix === undefined)
+            delete check.fix; // a remedy that does not apply is no key at all
+        checks.push(check);
+        onCheck(check);
+        return check.status === 'ok';
+    };
+    const missing = new Set();
+    const installed = (command) => {
+        const name = `${command} installed`;
+        onStart(name);
+        const found = deps.which(command);
+        if (!found)
+            missing.add(command);
+        return report(found ? { name, status: 'ok' } : { name, status: 'fail', detail: 'not found on PATH', fix: installFix[command] });
+    };
+    const repos = config.repos.map((repo) => resolveRepoConfig(config, repo));
+    const orchestrator = config.profiles[config.orchestratorProfile];
+    const rolesOf = (repo) => [repo.agents.author, repo.agents.reviewer, ...(repo.agents.leadReviewer ? [repo.agents.leadReviewer] : [])];
+    const profiles = [orchestrator, ...repos.flatMap((repo) => rolesOf(repo).map((agent) => config.profiles[agent.profile]))];
+    // Only a path that does not fit is reported: Carrier works without the socket, it just has none for the app to use.
+    const socket = enginePlacesOf(folder).socket;
+    const { fits, bytes } = socketPathFits(socket);
+    if (fits === false)
+        report({ name: 'control socket path fits', status: 'warn', detail: `${socket} is ${bytes} bytes and a socket path holds 103, so Carrier starts without its control socket`, fix: fixes.socketPath });
+    const hasGit = installed('git');
+    const hasGh = installed('gh');
+    for (const harness of new Set(repos.flatMap((repo) => rolesOf(repo).map((agent) => agent.harness))))
+        installed(harness);
+    const hasForge = profiles.some((profile) => profile.kind === 'forge') ? installed('agent-forge') : true;
+    // A local model needs its server up and the model downloaded; one check per distinct server and model.
+    const locals = new Map();
+    for (const repo of repos)
+        for (const { provider, model } of rolesOf(repo))
+            if (provider)
+                locals.set(`${provider}|${model}`, { provider, model });
+    for (const { provider, model } of locals.values()) {
+        const name = `${localLabel[provider]} has ${model}`;
+        onStart(name);
+        try {
+            const have = await deps.localModels(provider);
+            report(have.includes(model) ? { name, status: 'ok' } : { name, status: 'fail', detail: `not downloaded there (it has: ${have.join(', ') || 'nothing'})`, fix: fixes.modelMissing(model) });
+        }
+        catch (error) {
+            log.error('a local model server did not answer', error, { provider });
+            report({ name, status: 'fail', detail: `${localLabel[provider]} is not answering at ${localUrl[provider]}; start its server`, fix: fixes.serverDown });
+        }
+    }
+    // Every Claude and Codex provider, whether a role uses it or not: a login that has run out shows here before an epic needs it.
+    // A role's provider that is not logged in fails; any other only warns. Antigravity has no folder and a behaviour test instead.
+    const roleProviders = new Set(repos.flatMap((repo) => rolesOf(repo).flatMap((agent) => [agent.option, agent.providerName].filter((v) => v !== undefined))));
+    for (const [provider, { harness, configDir }] of Object.entries(config.providers)) {
+        if (missing.has(harness))
+            continue;
+        if (harness === 'agy') {
+            const name = `agy provider ${provider} is logged in`;
+            onStart(name);
+            try {
+                const login = await agyLogin(deps);
+                if (login === 'in')
+                    report({ name, status: 'ok' });
+                else if (login === 'out')
+                    report({ name, status: roleProviders.has(provider) ? 'fail' : 'warn', detail: 'not logged in', fix: fixes.login('agy', undefined) });
+                else
+                    report({ name, status: 'warn', detail: 'could not tell whether agy is logged in (it neither answered nor asked for a login in time)' });
+            }
+            catch (error) {
+                log.error('could not run agy to check the login', error, { provider });
+                report({ name, status: 'warn', detail: 'could not run agy to check the login', fix: installFix.agy });
+            }
+            continue;
+        }
+        if (harness !== 'claude' && harness !== 'codex')
+            continue;
+        const name = `${harness} provider ${provider} is logged in`;
+        const status = roleProviders.has(provider) ? 'fail' : 'warn';
+        const where = configDir ? `at ${configDir}` : 'in the environment Carrier runs in';
+        onStart(name);
+        try {
+            report((await deps.loggedIn(harness, configDir)) ? { name, status: 'ok' } : { name, status, detail: `not logged in ${where}`, fix: fixes.login(harness, configDir) });
+        }
+        catch (error) {
+            log.error(`could not run ${harness} to check the login`, error, { provider });
+            report({ name, status, detail: `could not run ${harness} to check the login ${where}`, fix: installFix[harness] });
+        }
+    }
+    // The schema compares profile names; two names can still point at the same bot or the same login. A shared identity allows it.
+    if (config.identities === 'separate') {
+        onStart('author and reviewer are different identities');
+        const clashes = repos.flatMap((repo) => {
+            const author = config.profiles[repo.agents.author.profile];
+            const reviewer = config.profiles[repo.agents.reviewer.profile];
+            const lead = repo.agents.leadReviewer ? config.profiles[repo.agents.leadReviewer.profile] : undefined;
+            const issues = [];
+            if (sameAccount(author, reviewer))
+                issues.push(`${repo.name}: author and reviewer both use ${identity(author)}`);
+            if (lead && sameAccount(author, lead))
+                issues.push(`${repo.name}: author and lead reviewer both use ${identity(author)}`);
+            return issues;
+        });
+        report(clashes.length === 0 ? { name: 'author and reviewer are different identities', status: 'ok' } : { name: 'author and reviewer are different identities', status: 'fail', detail: clashes.join('; '), fix: fixes.clash });
+    }
+    // Without gh, or without agent-forge for a forge profile, the checks below would only repeat the same failure.
+    const usable = (profile) => hasGit && hasGh && (profile.kind === 'gh' || hasForge);
+    const minted = new Set();
+    for (const repo of repos) {
+        for (const agent of rolesOf(repo)) {
+            const profile = config.profiles[agent.profile];
+            const key = `${identity(profile)}|${repo.name}`;
+            if (minted.has(key) || !usable(profile))
+                continue;
+            minted.add(key);
+            const name = `${identity(profile)} can mint a token for ${repo.name}`;
+            onStart(name);
+            try {
+                await deps.mint(profile, repo.name);
+                report({ name, status: 'ok' });
+            }
+            catch (error) {
+                report({ name, status: 'fail', detail: message(error), fix: fixes.mint(profile, repo.name, message(error)) });
+            }
+        }
+        if (!usable(orchestrator))
+            continue;
+        const name = `${identity(orchestrator)} can read ${repo.name}`;
+        onStart(name);
+        try {
+            await deps.listLabels(config, repo.name, folder);
+            report({ name, status: 'ok' });
+        }
+        catch (error) {
+            report({ name, status: 'fail', detail: message(error), fix: fixes.read(repo.name, message(error)) });
+        }
+    }
+    return checks;
+}

package/dist/doctor/fixes.js

@@ -0,0 +1,35 @@
+import { configDirVariable } from '../harnesses/names.js';
+// Every remedy lives here. They only repeat what a check already knows (names, owners): nothing from a child's output.
+export const installFix = {
+    git: 'install git (xcode-select --install on macOS)',
+    gh: 'install the GitHub CLI (https://cli.github.com) and run: gh auth login',
+    claude: 'install Claude Code (https://claude.com/claude-code) and sign in once',
+    codex: 'install the Codex CLI and run: codex login',
+    agy: 'install Antigravity and run agy once to sign in',
+    'agent-forge': 'install it: pnpm add -g @ashulab/agent-forge (https://github.com/AshuLab/agent-forge)',
+};
+export const fixes = {
+    mint(profile, repo, detail) {
+        if (profile.kind === 'gh')
+            return 'run: gh auth login';
+        if (/agent not found/i.test(detail))
+            return 'agent-forge --list shows your agents; add one with: agent-forge add';
+        if (/installation/i.test(detail))
+            return `install the GitHub App of that agent on ${repo.split('/')[0]}`;
+        if (/private key/i.test(detail))
+            return 'check privateKeyPath of that agent in your Forge registry';
+        return `run: agent-forge token --agent ${profile.agent} from a clone of the repo to see the full error`;
+    },
+    read(repo, detail) {
+        if (detail.includes('404'))
+            return `the repo does not exist or this identity cannot see it: install the App on ${repo.split('/')[0]} and give it access to ${repo}`;
+        if (detail.includes('401'))
+            return "the identity's credentials were rejected: for gh run gh auth login, for a bot check its App in Forge";
+        return undefined;
+    },
+    login: (harness, configDir) => (harness === 'agy' ? 'log in with: agy' : `log in with: ${configDir ? `${configDirVariable[harness]}=${configDir} ` : ''}${harness === 'claude' ? 'claude /login' : 'codex login'}`),
+    socketPath: 'move the Carrier folder to a shorter path (CARRIER_HOME, at most 77 bytes)',
+    clash: 'use two different bots (agent-forge add) or one bot and your gh login, or set identities to "shared" to use one account for both',
+    serverDown: 'start the server (LM Studio: lms server start, Ollama: ollama serve) and download the model',
+    modelMissing: (model) => `download it in LM Studio / ollama pull ${model}`,
+};

package/dist/execution/agent-runner.js

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

package/dist/execution/caller-result.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+const Sha = z.string().regex(/^[0-9a-f]{40}$/);
+const Pr = z.object({ number: z.number().int().positive(), headSha: Sha });
+const Id = z.string().min(1).max(64);
+const MAX_LIST = 50; // the same cap the `epic` reply puts on a round's blockers
+const Resolved = z.array(Id).max(MAX_LIST).optional();
+const Finding = z.object({ id: Id.optional(), title: z.string().min(1), url: z.string().url().optional() });
+const distinct = (ids) => new Set(ids).size === ids.length;
+const Common = {
+    executionId: z.string().min(1),
+    repo: z.string().regex(/^[\w.-]+\/[\w.-]+$/),
+    epic: z.number().int().positive(),
+    stage: z.enum(['ship', 'review', 'fix']),
+    summary: z.string().min(1),
+};
+export const CallerResult = z.discriminatedUnion('outcome', [
+    z.object({
+        ...Common,
+        outcome: z.literal('completed'),
+        pr: Pr,
+        verification: z.object({ ci: z.enum(['passed', 'absent']), evidence: z.string().min(1) }),
+        /** Reviewer only: ids of earlier blockers it considers fixed. Optional, so results that predate it still validate. */
+        resolved: Resolved,
+        /** Reviewer only: findings that do not stop approval (nitpicks, suggestions). Same shape as a blocker; optional. */
+        observations: z.array(Finding).max(MAX_LIST).optional(),
+    }).refine((r) => distinct(r.resolved ?? []), { message: 'resolved has a duplicate id' })
+        .refine((r) => distinct((r.observations ?? []).flatMap(({ id }) => id ?? [])), { message: 'two observations share an id' }),
+    z.object({
+        ...Common,
+        outcome: z.literal('changes_requested'),
+        stage: z.literal('review'),
+        pr: Pr,
+        // `id` is stable across rounds: the reviewer reuses it when a finding persists. Optional, like `resolved`.
+        blockers: z.array(Finding).min(1).max(MAX_LIST),
+        resolved: Resolved,
+    }).refine((r) => distinct(r.blockers.flatMap(({ id }) => id ?? [])), { message: 'two blockers share an id' })
+        .refine((r) => distinct([...r.blockers.flatMap(({ id }) => id ?? []), ...(r.resolved ?? [])]), { message: 'resolved has a duplicate id or one that is still a blocker' }),
+    z.object({ ...Common, outcome: z.literal('needs_human'), reason: z.string().min(1) }),
+]);
+/** `raw` is the file content, or null when the caller left no file. */
+export function parseCallerResult(raw, expected) {
+    if (raw === null)
+        return { ok: false, kind: 'invalid', message: 'result file is missing' };
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, kind: 'invalid', message: 'result is not valid JSON' };
+    }
+    const parsed = CallerResult.safeParse(json);
+    if (!parsed.success)
+        return { ok: false, kind: 'invalid', message: z.prettifyError(parsed.error) };
+    const result = parsed.data;
+    for (const key of ['executionId', 'repo', 'epic', 'stage']) {
+        if (result[key] !== expected[key]) {
+            return { ok: false, kind: 'mismatch', message: `${key} is ${result[key]}, expected ${expected[key]}` };
+        }
+    }
+    return { ok: true, result };
+}

package/dist/execution/events.js

@@ -0,0 +1,19 @@
+import { redact } from '../logging/redact.js';
+export const createEventState = () => ({ calls: new Map(), tasks: new Map(), lanes: new Map(), text: new Map() });
+// Characters, not bytes.
+export const caps = { arg: 1024, summary: 200, text: 4096, output: 4096, diffLines: 200, diffLine: 200 };
+/** Redacts first, so a secret is never cut in a way that hides its shape, then cuts. */
+export function clean(text, max) {
+    const safe = redact(text);
+    return safe.length <= max ? safe : `${safe.slice(0, max - 1)}…`;
+}
+/** A command's result: all of it when small, else the first and last half of the budget around a gap. */
+export function boundOutput(text) {
+    const safe = redact(text).trimEnd();
+    if (safe === '')
+        return [];
+    if (safe.length <= caps.output)
+        return safe.split('\n');
+    const half = Math.floor((caps.output - 3) / 2); // the gap line and its two newlines count too
+    return [...safe.slice(0, half).split('\n'), '…', ...safe.slice(-half).split('\n')];
+}

package/dist/execution/failure.js

@@ -0,0 +1,3 @@
+import { redact } from '../logging/redact.js';
+/** Redacted first, then one line, then cut: in that order, so a token cut in half cannot slip through. */
+export const failureDetail = (text) => redact(text).replace(/\s+/g, ' ').trim().slice(0, 300);

package/dist/execution/fake.js

@@ -0,0 +1,82 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+const crash = { kind: 'crashed', detail: 'exit code 1', exitCode: 1, signal: null, hostFreeMemMb: 8000, hostLoad: 1.5 };
+export class FakeAgentRunner {
+    tasks = [];
+    stopped = [];
+    /** Executions alive: the running ones, plus whatever a test adds to play a previous process's orphans. */
+    alive = new Set();
+    /** What each run does; by default it hangs, so a test sees the execution while it is running. */
+    behavior = () => ({ exit: 'hang' });
+    eventSinks = new Map();
+    /** Delivers a batch of events from a run later on, when the test decides. */
+    emit(executionId, events) {
+        for (const cb of this.eventSinks.get(executionId) ?? [])
+            cb(events);
+    }
+    run(task) {
+        this.tasks.push(task);
+        this.alive.add(task.executionId);
+        const behavior = this.behavior(task);
+        const { sessionId, output = [], events = [], write, exit = 'ok', when } = behavior;
+        const failure = 'failure' in behavior ? behavior.failure : exit === 'failed' ? crash : undefined;
+        const sessions = [];
+        const outputs = [];
+        const eventSinks = [];
+        this.eventSinks.set(task.executionId, eventSinks);
+        let resolveDone;
+        const finish = (result) => {
+            this.alive.delete(task.executionId);
+            resolveDone(result);
+        };
+        const done = new Promise((resolve) => (resolveDone = resolve));
+        // Runs after the caller registered its callbacks.
+        queueMicrotask(() => {
+            if (sessionId)
+                for (const cb of sessions)
+                    cb(sessionId);
+            for (const [stream, chunk] of output)
+                for (const cb of outputs)
+                    cb(stream, chunk);
+            for (const batch of events)
+                for (const cb of eventSinks)
+                    cb(batch);
+            if (write !== undefined) {
+                mkdirSync(dirname(task.resultPath), { recursive: true });
+                writeFileSync(task.resultPath, typeof write === 'string' ? write : JSON.stringify(write));
+            }
+            if (when && exit !== 'hang')
+                void when.then(() => finish({ exit, sessionId, failure }));
+            else if (exit !== 'hang')
+                finish({ exit, sessionId, failure });
+        });
+        return {
+            onSession: (cb) => void sessions.push(cb),
+            onOutput: (cb) => void outputs.push(cb),
+            onEvent: (cb) => void eventSinks.push(cb),
+            done,
+            stop: async () => {
+                this.stopped.push(task.executionId);
+                finish({ exit: 'stopped', sessionId });
+            },
+        };
+    }
+    async listActive() {
+        return [...this.alive];
+    }
+    async stop(executionId) {
+        this.stopped.push(executionId);
+        this.alive.delete(executionId);
+    }
+}
+export class FakeWorkspaces {
+    async prepareAuthor(repo, epic) {
+        return `/work/${repo}/${epic}/author`;
+    }
+    async prepareReviewer(repo, epic, pr) {
+        return `/work/${repo}/${epic}/reviewer-${pr}`;
+    }
+    async findWorktree(repo, branch) {
+        return `/work/${repo}/worktrees/${branch}`;
+    }
+}

package/dist/execution/git-workspaces.js

@@ -0,0 +1,136 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { repoNamePattern } from '../config/schema.js';
+const execFileAsync = promisify(execFile);
+const defaultRemoteUrl = (repo) => `https://github.com/${repo}.git`;
+async function git(args, opts = {}) {
+    try {
+        const { stdout } = await execFileAsync('git', args, {
+            cwd: opts.cwd,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0', ...opts.env },
+            timeout: opts.timeoutMs,
+            maxBuffer: 16 * 1024 * 1024,
+            encoding: 'utf8',
+        });
+        return stdout.trim();
+    }
+    catch (error) {
+        // execFile's own message repeats the argv; the credentials only travel in the environment, which it never prints.
+        const failed = error;
+        throw new Error(`git ${args[0]} failed: ${(failed.stderr || failed.message).trim().slice(0, 500)}`);
+    }
+}
+/**
+ * Token of a GitHub profile. Forge picks the App installation from the `origin` of the cwd, so it runs in a
+ * throwaway repo pointing at the target: that works before the clone exists, too.
+ */
+export function profileToken(profile, remoteUrl = defaultRemoteUrl) {
+    return async (repo) => {
+        if (profile.kind === 'gh')
+            return (await execFileAsync('gh', ['auth', 'token'], { encoding: 'utf8' })).stdout.trim();
+        const scratch = await mkdtemp(join(tmpdir(), 'carrier-token-'));
+        try {
+            await git(['init', '-q'], { cwd: scratch });
+            await git(['remote', 'add', 'origin', remoteUrl(repo)], { cwd: scratch });
+            return (await execFileAsync('agent-forge', ['token', '--agent', profile.agent], { cwd: scratch, encoding: 'utf8' })).stdout.trim();
+        }
+        catch (error) {
+            // Never echo the child's output or argv beyond this: they are the only place a token could appear.
+            throw new Error(`could not mint a token for ${profile.kind === 'forge' ? profile.agent : 'gh'}: ${error.stderr?.trim().slice(0, 300) ?? 'failed'}`);
+        }
+        finally {
+            await rm(scratch, { recursive: true, force: true });
+        }
+    };
+}
+export class GitWorkspaces {
+    places;
+    token;
+    remoteUrl;
+    reviewRef;
+    timeoutMs;
+    queues = new Map();
+    constructor(options) {
+        this.places = options.places;
+        this.token = options.token;
+        this.remoteUrl = options.remoteUrl ?? defaultRemoteUrl;
+        this.reviewRef = options.reviewRef ?? ((pr) => `refs/pull/${pr}/head`);
+        this.timeoutMs = options.timeoutMs ?? 10 * 60_000;
+    }
+    clonePath(repo) {
+        return join(this.places.repos, repo);
+    }
+    /** One git operation at a time per repo: concurrent fetches and worktree adds on one clone collide on its locks. */
+    serial(repo, work) {
+        const run = (this.queues.get(repo) ?? Promise.resolve()).catch(() => { }).then(work);
+        this.queues.set(repo, run.catch(() => { }));
+        return run;
+    }
+    /** Git over the network with the profile's token in the environment (not in argv, not in any config file). */
+    async remote(repo, args, cwd) {
+        const env = {};
+        if (this.token) {
+            const basic = Buffer.from(`x-access-token:${await this.token(repo)}`).toString('base64');
+            Object.assign(env, { GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'http.extraHeader', GIT_CONFIG_VALUE_0: `Authorization: Basic ${basic}` });
+        }
+        return git(args, { cwd, env, timeoutMs: this.timeoutMs });
+    }
+    /** Clones or fetches; returns the clone. Callers hold the repo's queue. */
+    async ensureClone(repo) {
+        if (!repoNamePattern.test(repo))
+            throw new Error(`invalid repo "${repo}", expected owner/name`);
+        const path = this.clonePath(repo);
+        if (existsSync(join(path, '.git')))
+            await this.remote(repo, ['fetch', '--prune', 'origin'], path);
+        else {
+            await mkdir(dirname(path), { recursive: true });
+            await this.remote(repo, ['clone', this.remoteUrl(repo), path]);
+        }
+        return path;
+    }
+    /** The clone, up to date. `ship` runs here and puts the epic's worktree where the repo's solve.md says. */
+    async prepareAuthor(repo, epic) {
+        assertCount(epic, 'epic');
+        return this.serial(repo, () => this.ensureClone(repo));
+    }
+    async findWorktree(repo, branch) {
+        return this.serial(repo, async () => {
+            const list = await git(['worktree', 'list', '--porcelain'], { cwd: this.clonePath(repo) });
+            // One block per worktree: `worktree <path>`, then `branch refs/heads/<name>` unless it is detached.
+            // The first is the clone itself: other epics of the repo share it, so an epic that was not isolated has no workspace.
+            for (const block of list.split('\n\n').slice(1)) {
+                const lines = block.split('\n');
+                if (lines.includes(`branch refs/heads/${branch}`))
+                    return lines.find((l) => l.startsWith('worktree ')).slice('worktree '.length);
+            }
+            return null;
+        });
+    }
+    /** A checkout detached at the PR's head, apart from the author's and from Solve's `worktrees/`; each round re-points it. */
+    async prepareReviewer(repo, epic, pr) {
+        assertCount(epic, 'epic');
+        assertCount(pr, 'pr');
+        return this.serial(repo, async () => {
+            const clone = await this.ensureClone(repo);
+            await this.remote(repo, ['fetch', 'origin', this.reviewRef(pr)], clone);
+            const sha = await git(['rev-parse', '--verify', 'FETCH_HEAD^{commit}'], { cwd: clone });
+            const path = join(this.places.reviews, repo.split('/')[1], String(epic));
+            if (existsSync(join(path, '.git')))
+                await git(['switch', '--detach', sha], { cwd: path });
+            else {
+                await mkdir(dirname(path), { recursive: true });
+                await git(['worktree', 'prune'], { cwd: clone });
+                await git(['worktree', 'add', '--detach', path, sha], { cwd: clone });
+            }
+            return path;
+        });
+    }
+}
+function assertCount(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`invalid ${name} ${value}`);
+}

package/dist/execution/import-result.js

@@ -0,0 +1,23 @@
+import { callerResults } from '../storage/caller-results.js';
+import { parseCallerResult } from './caller-result.js';
+/**
+ * Validates the result, stores it and runs `transition` in one transaction: if `transition` throws,
+ * neither is kept. Importing the same executionId again changes nothing and skips `transition`.
+ */
+export function importResult(db, raw, expected, transition) {
+    const parsed = parseCallerResult(raw, expected);
+    if (!parsed.ok)
+        return parsed;
+    return db.transaction((tx) => {
+        const { result } = parsed;
+        const inserted = tx
+            .insert(callerResults)
+            .values({ executionId: result.executionId, outcome: result.outcome, result: JSON.stringify(result) })
+            .onConflictDoNothing()
+            .run();
+        if (inserted.changes === 0)
+            return { ...parsed, duplicate: true };
+        transition(tx, result);
+        return parsed;
+    });
+}

package/dist/execution/workspaces.js

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

package/dist/format/duration.js

@@ -0,0 +1,12 @@
+// "45s", "3m 05s", "2h 03m", "1d 4h": the two largest units, for the panel and anything else that shows elapsed time.
+export function formatDuration(ms) {
+    const s = Math.floor(Math.max(0, ms) / 1000);
+    const [d, h, m] = [Math.floor(s / 86_400), Math.floor((s % 86_400) / 3600), Math.floor((s % 3600) / 60)];
+    if (d > 0)
+        return `${d}d ${h}h`;
+    if (h > 0)
+        return `${h}h ${String(m).padStart(2, '0')}m`;
+    if (m > 0)
+        return `${m}m ${String(s % 60).padStart(2, '0')}s`;
+    return `${s}s`;
+}