@ashulab/carrier 0.0.0-stage → 0.1.0

package/dist/orchestration/fake.js

@@ -0,0 +1,152 @@
+import { AuthError, GitHubUnavailable } from './github.js';
+export class FakeGitHub {
+    /** What rateLimit answers. */
+    limit = null;
+    rateLimit() {
+        return this.limit;
+    }
+    /** A ready epic's labels are the issue's, as GitHub lists them. */
+    ready = {};
+    unavailable = null;
+    /** The open epics with their slice progress, by repo; the title defaults to empty and the labels to the issue's. */
+    openEpics = {};
+    /** Makes listOpenEpics fail while the rest works. */
+    openEpicsUnavailable = null;
+    /** What readSlices answers, by `repo#issue`; an epic not listed has no slices. */
+    slices = {};
+    /** Makes readSlices fail while the rest works. */
+    slicesUnavailable = null;
+    /** Every slice read that reached the port, as `repo#issue`. */
+    sliceReads = [];
+    slicesGate = null;
+    /** What readPullRequest answers, by `repo#number`; a pull request not listed does not exist. */
+    pullRequestBlocks = {};
+    /** The review threads readPullRequest answers with, by `repo#number`; a pull request not listed has none. */
+    reviewThreads = {};
+    /** Makes readPullRequest fail while the rest works. */
+    pullRequestUnavailable = null;
+    /** Every pull request read that reached the port, as `repo#number`. */
+    pullRequestReads = [];
+    /** Makes setLabels fail while the rest works. */
+    setLabelsUnavailable = null;
+    issues = {};
+    pulls = {};
+    repoLabels = {};
+    created = [];
+    /** The colour and description each label was created with. */
+    styles = {};
+    calls = 0;
+    /** Makes every call fail like Forge rejecting the orchestrator's profile. */
+    authError = null;
+    /** Every call that reached the port, failed or not. */
+    attempts = 0;
+    guard() {
+        this.attempts++;
+        if (this.authError)
+            throw this.authError;
+    }
+    /** An issue not set up by the test is open and ready. */
+    issue(repo, issue) {
+        return (this.issues[`${repo}#${issue}`] ??= { state: 'open', labels: ['solve:epic:ready'] });
+    }
+    async listReadyEpics(repo) {
+        this.guard();
+        this.calls++;
+        if (this.unavailable)
+            throw this.unavailable;
+        return (this.ready[repo] ?? []).filter((e) => this.issue(repo, e.issue).labels.includes('solve:epic:ready')).map((e) => ({ ...e, labels: [...this.issue(repo, e.issue).labels] })); // like GitHub: the label decides
+    }
+    async listOpenEpics(repo) {
+        this.guard();
+        const failure = this.unavailable ?? this.openEpicsUnavailable;
+        if (failure)
+            throw failure;
+        return (this.openEpics[repo] ?? []).map((epic) => ({ title: '', ...epic, labels: [...(this.issues[`${repo}#${epic.issue}`]?.labels ?? [])] }));
+    }
+    async readSlices(repo, issue) {
+        this.guard();
+        this.sliceReads.push(`${repo}#${issue}`);
+        if (this.slicesUnavailable)
+            throw this.slicesUnavailable;
+        const found = this.slices[`${repo}#${issue}`];
+        await this.slicesGate; // a test holds the answer here: it was read above, it arrives when the gate opens
+        return { slices: found?.slices.map((s) => ({ ...s })) ?? [], truncated: found?.truncated ?? false };
+    }
+    async readPullRequest(repo, number) {
+        this.guard();
+        this.pullRequestReads.push(`${repo}#${number}`);
+        if (this.pullRequestUnavailable)
+            throw this.pullRequestUnavailable;
+        const found = this.pullRequestBlocks[`${repo}#${number}`];
+        if (found === undefined)
+            return null;
+        const read = this.reviewThreads[`${repo}#${number}`];
+        return { pr: { ...found, checks: found.checks && { ...found.checks } }, threads: read?.threads.map((t) => ({ ...t })) ?? [], truncated: read?.truncated ?? false };
+    }
+    async getIssue(repo, issue) {
+        this.guard();
+        const { state, labels } = this.issue(repo, issue);
+        return { state, labels: [...labels] };
+    }
+    async getPullRequest(repo, number) {
+        this.guard();
+        if (this.unavailable)
+            throw this.unavailable;
+        const pull = this.pulls[`${repo}#${number}`];
+        return pull ? { ...pull, headRef: pull.headRef ?? 'feat/epic/epic' } : null;
+    }
+    async findPullRequest(repo, issue) {
+        this.guard();
+        if (this.unavailable)
+            throw this.unavailable;
+        for (const [key, { state, body, headSha }] of Object.entries(this.pulls)) {
+            if (key.startsWith(`${repo}#`) && new RegExp(`\\bcloses #${issue}(?!\\d)`, 'i').test(body))
+                return { number: Number(key.split('#')[1]), state, headSha };
+        }
+        return null;
+    }
+    async setLabels(repo, issue, { add, remove }) {
+        this.guard();
+        if (this.setLabelsUnavailable)
+            throw this.setLabelsUnavailable;
+        const found = this.issue(repo, issue);
+        found.labels = [...new Set([...found.labels.filter((l) => !remove.includes(l)), ...add])];
+    }
+    async listLabels(repo) {
+        this.guard();
+        return [...(this.repoLabels[repo] ?? [])];
+    }
+    async createLabel(repo, name, style) {
+        this.guard();
+        this.styles[name] = style;
+        (this.repoLabels[repo] ??= []).push(name);
+        this.created.push(`${repo}:${name}`);
+    }
+}
+export class FakeClock {
+    time = 0;
+    timers = [];
+    now() {
+        return this.time;
+    }
+    after(ms, fn) {
+        const timer = { at: this.time + ms, fn };
+        this.timers.push(timer);
+        return () => {
+            this.timers = this.timers.filter((t) => t !== timer);
+        };
+    }
+    /** Moves time forward, running due timers in order and waiting for each to finish. */
+    async advance(ms) {
+        const target = this.time + ms;
+        for (;;) {
+            const next = this.timers.filter((t) => t.at <= target).sort((a, b) => a.at - b.at)[0];
+            if (!next)
+                break;
+            this.timers = this.timers.filter((t) => t !== next);
+            this.time = next.at;
+            await next.fn();
+        }
+        this.time = target;
+    }
+}

package/dist/orchestration/final-pr.js

@@ -0,0 +1,15 @@
+/**
+ * Did the epic end outside Carrier? Only the epic issue and the final PR (the one saved when `ship`
+ * was validated) count: a slice PR or slice issue never shows up here. A merge is checked first
+ * because merging the final PR closes the epic issue too.
+ */
+export async function endOf(github, { repo, issue, prNumber }) {
+    const pr = prNumber === null ? null : await github.getPullRequest(repo, prNumber);
+    if (pr?.state === 'merged')
+        return { status: 'merged', reason: `the final PR #${prNumber} was merged` };
+    if (pr?.state === 'closed')
+        return { status: 'cancelled', reason: `the final PR #${prNumber} was closed without merging` };
+    if ((await github.getIssue(repo, issue)).state === 'closed')
+        return { status: 'cancelled', reason: 'the epic issue was closed without merging' };
+    return null;
+}

package/dist/orchestration/github.js

@@ -0,0 +1,31 @@
+export class GitHubUnavailable extends Error {
+    kind;
+    retryAfterMs;
+    // No parameter property: Node strips types at runtime and cannot run that syntax.
+    constructor(kind, detail, retryAfterMs) {
+        super(`GitHub unavailable (${kind}: ${detail})`);
+        this.kind = kind;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/** Forge reported an authentication error for the profile the port acts as (the orchestrator's). Thrown by any GitHub call. */
+export class AuthError extends Error {
+    profile;
+    constructor(profile) {
+        super('auth error');
+        this.profile = profile;
+    }
+}
+// Labels Carrier owns (it creates them) and the one Solve owns (it never does).
+export const ownedLabels = ['solve:epic:running', 'solve:epic:ready-for-test', 'solve:epic:needs-human'];
+export const readyLabel = 'solve:epic:ready';
+export const epicLabel = 'solve:epic';
+/** How Carrier creates its labels (GitHub limits a description to 100 characters). `needs-human` is the loud one: it is the state that most needs to be seen. */
+export const labelStyles = {
+    'solve:epic:running': { color: '0969da', description: 'An orchestrator is building this epic' },
+    'solve:epic:ready-for-test': { color: '8957e5', description: 'Reviewed on the current head; a person tests and merges' },
+    'solve:epic:needs-human': { color: 'd93f0b', description: 'Stopped: a person has to step in (reason in the issue or PR)' },
+};
+export const runningLabel = ownedLabels[0];
+export const readyForTestLabel = ownedLabels[1];
+export const needsHumanLabel = ownedLabels[2];

package/dist/orchestration/reserve.js

@@ -0,0 +1,32 @@
+import { and, asc, count, eq, inArray } from 'drizzle-orm';
+import { epics } from '../storage/schema.js';
+// Atomic: the check of free slots, the pick of the oldest queued epic and the move to `running`
+// happen in one write transaction, so two connections to the same file can never reserve the
+// same epic or exceed the limit. Only queued epics are picked, so a running one is never reserved again.
+// With two or more options the epic is also marked as waiting for its choice for `choiceMs`; each role starts on its configured option.
+export function reserve(db, { maxConcurrent, now, repos, choiceMs }) {
+    return db.transaction((tx) => {
+        const running = tx.select({ n: count() }).from(epics).where(eq(epics.status, 'running')).get().n;
+        if (running >= maxConcurrent)
+            return null;
+        const next = tx
+            .select()
+            .from(epics)
+            .where(and(eq(epics.status, 'queued'), inArray(epics.repo, repos.map((r) => r.name))))
+            .orderBy(asc(epics.id))
+            .get();
+        if (!next)
+            return null;
+        const config = repos.find((r) => r.name === next.repo);
+        return tx
+            .update(epics)
+            .set({
+            status: 'running', startedAt: now, config, labelPending: true,
+            authorOption: config.agents.author.option ?? null, reviewerOption: config.agents.reviewer.option ?? null,
+            choiceDeadline: Object.keys((config.providers ?? config.options) ?? {}).length >= 2 ? now + choiceMs : null,
+        })
+            .where(eq(epics.id, next.id))
+            .returning()
+            .get();
+    }, { behavior: 'immediate' });
+}

package/dist/orchestration/resume-refused.js

@@ -0,0 +1,7 @@
+export class ResumeRefused extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}

package/dist/orchestration/retention.js

@@ -0,0 +1,145 @@
+import { readdirSync, realpathSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, sep } from 'node:path';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { and, eq, inArray, isNotNull, lte } from 'drizzle-orm';
+import { executionEvents } from '../storage/events.js';
+import { executions } from '../storage/executions.js';
+import { epics } from '../storage/schema.js';
+const DAY = 24 * 60 * 60 * 1000;
+export const retentionMs = 30 * DAY;
+// Only an epic that is over expires; queued, running, needs_human and repo_removed keep everything.
+const finished = ['ready_for_test', 'merged', 'cancelled'];
+// Ids come from SQLite but end up in a path: an allowlist keeps `..` and separators out.
+const safeId = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+export const sessionDirsFrom = (env = process.env) => ({
+    claude: env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude'),
+    codex: env.CODEX_HOME ?? join(homedir(), '.codex'),
+});
+const log = createScopedLogger('retention');
+// Entries of a folder; absent means that CLI never ran here, anything else (permissions, IO) is logged: a purge that cannot look is not a clean one.
+const entries = (dir) => {
+    try {
+        return readdirSync(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            log.error('cannot list a session folder', error, { dir });
+        return [];
+    }
+};
+// Folders to walk down into: a symlink is never followed out of the CLI's own tree.
+const folders = (dir) => entries(dir).filter((e) => e.isDirectory()).map((e) => e.name);
+const files = (dir) => entries(dir).map((e) => e.name);
+/**
+ * The files of a session, found by its id (docs/research/headless-agents.md): Claude keeps
+ * `projects/<cwd with / and . as ->/<id>.jsonl` (plus `<id>/` for what it spawned, only beside its transcript),
+ * Codex `sessions/YYYY/MM/DD/rollout-<date>-<id>.jsonl`. Nothing a CLI reported is used as a path, only the id.
+ */
+function sessionFiles({ claude, codex }, ids) {
+    const found = [];
+    const wanted = new Set(ids);
+    const projects = join(claude, 'projects');
+    for (const folder of folders(projects)) {
+        const present = files(join(projects, folder));
+        for (const entry of present) {
+            if (!entry.endsWith('.jsonl') || !wanted.has(entry.slice(0, -'.jsonl'.length)))
+                continue;
+            found.push(join(projects, folder, entry));
+            const spawned = entry.slice(0, -'.jsonl'.length);
+            if (present.includes(spawned))
+                found.push(join(projects, folder, spawned));
+        }
+    }
+    const sessions = join(codex, 'sessions');
+    for (const year of folders(sessions))
+        for (const month of folders(join(sessions, year)))
+            for (const day of folders(join(sessions, year, month))) {
+                for (const file of files(join(sessions, year, month, day))) {
+                    const id = /^rollout-\d{4}-\d\d-\d\dT\d\d-\d\d-\d\d-(.+)\.jsonl$/.exec(file)?.[1];
+                    if (id !== undefined && wanted.has(id))
+                        found.push(join(sessions, year, month, day, file));
+                }
+            }
+    return found;
+}
+/**
+ * Deletes the execution logs (`<logs>/executions/<executionId>/`) and the sessions the CLIs saved
+ * for them, of epics finished or cancelled 30 days or more before `now`, and the events stored from those logs.
+ * Never touches other SQLite rows nor workspaces; a symlink is removed itself, never followed. Returns the paths deleted.
+ */
+export function purgeExpired(db, logs, now, sessionDirs = sessionDirsFrom()) {
+    const rows = db
+        .select({ executionId: executions.executionId, sessionId: executions.sessionId, configDir: executions.configDir })
+        .from(executions)
+        .innerJoin(epics, eq(epics.id, executions.epicId))
+        .where(and(inArray(epics.status, finished), isNotNull(epics.finishedAt), lte(epics.finishedAt, now - retentionMs)))
+        .all();
+    // The events are a copy of the logs: they go when the logs do.
+    db.transaction((tx) => {
+        for (const { executionId } of rows)
+            tx.delete(executionEvents).where(eq(executionEvents.executionId, executionId)).run();
+    });
+    const deleted = [];
+    const remove = (target) => {
+        rmSync(target, { recursive: true, force: true });
+        deleted.push(target);
+    };
+    // Each session is looked up in the folder of the execution that wrote it; a row that predates the column uses the environment's own.
+    const idsByFolder = new Map();
+    for (const { sessionId, configDir } of rows) {
+        if (sessionId === null || !safeId.test(sessionId))
+            continue;
+        if (configDir !== null && !isAbsolute(configDir)) {
+            log.warn('ignoring a recorded config folder that is not an absolute path', { configDir });
+            continue;
+        }
+        idsByFolder.set(configDir, [...(idsByFolder.get(configDir) ?? []), sessionId]);
+    }
+    for (const [folder, ids] of idsByFolder) {
+        for (const file of sessionFiles(folder === null ? sessionDirs : { claude: folder, codex: folder }, ids))
+            if (!deleted.includes(file))
+                remove(file);
+    }
+    let real;
+    try {
+        real = realpathSync(logs);
+    }
+    catch {
+        return deleted; // no logs folder: no logs were ever written
+    }
+    try {
+        // A folder that resolves outside the logs folder (symlinked) is not ours to delete from.
+        if (!realpathSync(join(logs, 'executions')).startsWith(real + sep))
+            return deleted;
+    }
+    catch {
+        return deleted; // folder absent
+    }
+    for (const { executionId } of rows)
+        if (safeId.test(executionId))
+            remove(join(logs, 'executions', executionId));
+    return deleted;
+}
+/** Purges now and every 24 hours on the injected clock; a failed purge is logged and tried again next day. */
+export function startRetention(db, logs, clock, sessionDirs) {
+    let cancel = () => { };
+    let stopped = false;
+    const run = async () => {
+        try {
+            const deleted = purgeExpired(db, logs, clock.now(), sessionDirs);
+            if (deleted.length > 0)
+                log.info('purged expired logs and sessions', { count: deleted.length });
+        }
+        catch (error) {
+            log.error('retention purge failed', error);
+        }
+        if (!stopped)
+            cancel = clock.after(DAY, run);
+    };
+    void run();
+    return () => {
+        stopped = true;
+        cancel();
+    };
+}

package/dist/orchestration/retry.js

@@ -0,0 +1,16 @@
+import { desc, eq, sql } from 'drizzle-orm';
+import { executions } from '../storage/executions.js';
+/**
+ * The epic's latest executions that ended in a retryable technical failure, newest first. The streak
+ * stops at the first execution without `error` (a finished one, or one that is not retried), so
+ * findings, rounds and GitHub query errors never count: only technical failures do.
+ */
+export function failureStreak(db, epicId) {
+    const streak = [];
+    for (const execution of db.select().from(executions).where(eq(executions.epicId, epicId)).orderBy(desc(sql `rowid`)).all()) {
+        if (execution.error === null)
+            break;
+        streak.push(execution);
+    }
+    return streak;
+}

package/dist/prompts/build-prompt.js

@@ -0,0 +1,13 @@
+import { fix } from './fix.js';
+import { intro } from './intro.js';
+import { resultContract } from './result.js';
+import { review } from './review.js';
+import { ship } from './ship.js';
+// Only used when the task has no PR yet (ship); the engine validates the real PR against GitHub.
+const placeholderPr = { number: 1, headSha: '0'.repeat(40) };
+/** The prompt of one run: who you are, what this stage asks, and how to hand the result back. */
+export function buildPrompt(task, { forgeAgent } = {}) {
+    const pr = task.context.pr ?? placeholderPr;
+    const stage = task.stage === 'ship' ? ship(task) : task.stage === 'fix' ? fix(task, pr) : review(task, pr);
+    return [...intro(task, forgeAgent), ...stage, ...resultContract(task, pr)].join('\n');
+}

package/dist/prompts/fix.js

@@ -0,0 +1,21 @@
+import { invoke } from './invoke.js';
+const item = (b) => `- ${b.title}${b.url ? ` (${b.url})` : ''}`;
+/** Stage `fix`: answer the blockers of the last review, or, when it only left observations, reply to them. */
+export const fix = (task, pr) => {
+    const observations = task.context.observations ?? [];
+    if (observations.length > 0) {
+        return [
+            `Invoke ${invoke(task, 'code-resolve')} on PR #${pr.number}, answering the observations the last review left and fixing what applies.`,
+            'Reply on each thread with your decision, whether or not it changes the code. Leave every thread open: only the reviewer can say it is satisfied, you do not resolve them.',
+            'Never merge the final PR.',
+            'Observations of the last review:',
+            ...observations.map(item),
+        ];
+    }
+    return [
+        `Invoke ${invoke(task, 'code-resolve')} on PR #${pr.number}, answering every finding of the last review and fixing what applies.`,
+        'Never merge the final PR. Leave the blockers open: the reviewer verifies them, you do not resolve them.',
+        'Blockers of the last review:',
+        ...(task.context.blockers ?? []).map(item),
+    ];
+};

package/dist/prompts/intro.js

@@ -0,0 +1,21 @@
+import { personaLines } from './persona.js';
+/** Who the agent is, the ground rules, and what happened in earlier turns of this epic. */
+export function intro(task, forgeAgent) {
+    const { executionId, repo, epic, stage, context } = task;
+    const lines = [
+        `You are the ${stage === 'review' ? 'reviewer' : 'author'} of the final integration PR of epic #${epic} in ${repo}. Execution ${executionId}, stage ${stage}.`,
+        ...personaLines(task),
+        'Nobody answers questions during this run: decide, and use needs_human when you cannot.',
+        'Apply the repo\'s own rules (its docs, agent instructions and conventions) to choose and evaluate tests, CI and blockers. Do not assume commands from other repos.',
+    ];
+    if (forgeAgent) {
+        lines.push(`Your GitHub token expires about an hour after this run starts. If a \`gh\` call fails with 401 (Bad credentials), run it again as \`agent-forge gh ${forgeAgent} <the same arguments>\` from inside the workspace. git renews its own credentials.`);
+    }
+    if (context.verifyStateFirst) {
+        lines.push('A previous attempt of this stage was interrupted. Before acting, verify what is already done (branch, commits, PR, comments, threads) and continue from there instead of repeating work.');
+    }
+    if (context.previousSummaries.length > 0) {
+        lines.push('Summaries of the previous turns, oldest first:', ...context.previousSummaries.map((s, i) => `${i + 1}. ${s}`));
+    }
+    return lines;
+}

package/dist/prompts/invoke.js

@@ -0,0 +1,2 @@
+/** How a harness spells "run this skill": Claude Code and Antigravity expand /skill, Codex $skill. */
+export const invoke = (task, skill) => `${task.harness === 'codex' ? '$' : '/'}${skill}`;

package/dist/prompts/persona.js

@@ -0,0 +1,12 @@
+export const signatureOf = (role, name) => `🤖 ${role === 'author' ? 'Author' : 'Reviewer'}${name ? ` [${name}]` : ''} via Carrier`;
+/** Who the user says this role is: its name, then its prompt as written. Under a shared identity, the rule to sign what it publishes. */
+export function personaLines({ persona, sharedIdentity, stage }) {
+    const signature = signatureOf(stage === 'review' ? 'reviewer' : 'author', persona?.name);
+    return [
+        ...(persona?.name ? [`Your name is ${persona.name}.`] : []),
+        ...(persona?.prompt ? [persona.prompt] : []),
+        ...(sharedIdentity
+            ? [`The GitHub account you publish with is shared with the person running Carrier and with the other role. End everything you publish on GitHub with this signature on its own last line: review comments and bodies, the pull request body, replies on threads, and any other comment, issue or issue body you post. In a commit message make it the last line of the body, before any trailers such as Co-Authored-By: ${signature}`]
+            : []),
+    ];
+}

package/dist/prompts/result.js

@@ -0,0 +1,32 @@
+const json = (result) => '```json\n' + JSON.stringify(result, null, 2) + '\n```';
+/** The contract: where to write the result and which JSON shapes Carrier accepts for this stage. */
+export function resultContract(task, pr) {
+    const { executionId, repo, epic, stage, resultPath } = task;
+    const reviewing = stage === 'review';
+    const common = { executionId, repo, epic, stage, summary: '<one or two sentences for the next agent of this epic: what you did and concluded>' };
+    const completed = (evidence) => ({
+        ...common,
+        outcome: 'completed',
+        pr,
+        verification: { ci: 'passed', evidence },
+        ...(reviewing && { observations: [{ id: '<stable-id>', title: '<non-blocking finding>', url: `https://github.com/${repo}/pull/${pr.number}#discussion_r456` }] }),
+    });
+    const changesRequested = {
+        ...common,
+        stage: 'review',
+        outcome: 'changes_requested',
+        pr,
+        blockers: [{ id: '<stable-id>', title: '<blocker>', url: `https://github.com/${repo}/pull/${pr.number}#discussion_r123` }],
+        resolved: ['<id of an earlier blocker that is now fixed>'],
+    };
+    const needsHuman = { ...common, outcome: 'needs_human', reason: '<why a person has to step in>' };
+    const examples = reviewing
+        ? [completed('<one line: which verifications you confirmed on this commit>'), changesRequested, needsHuman]
+        : [completed('<one line: which verifications you ran and their result>'), needsHuman];
+    return [
+        `Before finishing, write exactly one JSON object to ${resultPath}. That path is also in the environment variable CARRIER_RESULT_PATH: write to "$CARRIER_RESULT_PATH" instead of retyping it, because a path with one segment missing is a result nobody reads. Repeat executionId, repo, epic and stage as given. Allowed outputs:`,
+        ...examples.map(json),
+        ...(reviewing ? [] : ['Replace pr.number and pr.headSha with the real final PR and its current head (git rev-parse HEAD). A failing CI is not a completed result.']),
+        'verification.ci is "absent" when the repo has no CI; say so in evidence.',
+    ];
+}

package/dist/prompts/review.js

@@ -0,0 +1,15 @@
+import { invoke } from './invoke.js';
+/** Stage `review`: judge the final PR with a different identity than the author's. */
+export const review = (task, pr) => [
+    `Review PR #${pr.number}${task.context.round ? `, round ${task.context.round}` : ''}. First confirm the PR head is ${pr.headSha}; if it is not, return needs_human.`,
+    `Invoke ${invoke(task, 'code-review')} against the epic's spec and tickets, checking that earlier findings were fixed and nothing regressed, then publish the findings with ${invoke(task, 'code-post')}.`,
+    ...(task.context.blockers?.length
+        ? [
+            'Blockers of the previous round (id and title):',
+            ...task.context.blockers.map((b) => `- ${b.id ?? '(no id)'}: ${b.title}`),
+            'Give every blocker you return a short stable id. When a finding above persists, reuse its id; never reuse an id for a different finding. List in "resolved" the ids of the blockers above that are now fixed.',
+        ]
+        : ['Give every blocker you return a short stable id (for example "token-expiry"), so a later round can say whether it persists or was fixed.']),
+    'Findings that do not stop approval (what you would post as a nitpick or a suggestion) are observations: list them in "observations" of a completed result, each with a title, a link when you have one, and a short stable id by the same rule as blockers (reuse it when the finding persists; never reuse an id for a different finding). Leave the field out when there are none.',
+    'Return changes_requested with the blockers if there are any. Return completed only if the review is conclusive, there are no blockers and the repo\'s verifications are confirmed on that same commit. If the review is inconclusive (missing context, cannot verify), return needs_human.',
+];

package/dist/prompts/ship.js

@@ -0,0 +1,8 @@
+import { invoke } from './invoke.js';
+/** Stage `ship`: drain the epic into its own worktree and leave the final PR open. */
+export const ship = (task) => [
+    `Invoke ${invoke(task, 'ship')} for epic #${task.epic} and tell it to worktree this epic, whatever mode the repo's solve.md has: the epic must live in its own git worktree. Leave the final integration PR open.`,
+    'Never merge the final PR: a person tests it and decides the merge.',
+    // Carrier may run on another machine: a file on someone's disk is not a source. The remote is the only shared channel.
+    'The epic\'s design artifacts (spec, ADRs, glossary) must already be on the remote, on the epic branch or the base branch. Do not look for uncommitted files in other directories of this machine. If the epic refers to a spec or ADR that is not there, return needs_human naming what is missing.',
+];

package/dist/status/snapshot.js

@@ -0,0 +1,92 @@
+import { and, asc, count, desc, eq, gte, inArray, sql } from 'drizzle-orm';
+import { latestBlockers } from '../orchestration/blockers.js';
+import { executions } from '../storage/executions.js';
+import { epics } from '../storage/schema.js';
+const agentOf = ({ harness, model, provider }) => ({ harness, model, provider: provider ?? null });
+const agentsOf = (config) => ({ author: agentOf(config.agents.author), reviewer: agentOf(config.agents.reviewer) });
+/** The options of an epic as the panel and the epic's reply list them; undefined for one saved before options existed. */
+export const optionsOf = ({ config, authorOption, reviewerOption, choiceDeadline }) => {
+    const directory = config?.providers ?? config?.options;
+    return directory && { names: Object.keys(directory), author: authorOption, reviewer: reviewerOption, choiceDeadline };
+};
+/** One row per watched repo: the agents it resolves to and its last poll (not checked yet: null and ok). */
+export function watchedOf(repos, lastCheck) {
+    return repos.map((r) => {
+        const check = lastCheck(r.name);
+        return { repo: r.name, lastCheckedAt: check?.at ?? null, ok: check?.ok ?? true, error: check?.error ?? null, agents: agentsOf(r) };
+    });
+}
+const maxBlockerTitles = 10;
+const maxBlockerTitleLength = 200;
+/**
+ * What the panel shows, read from SQLite: slots, the queue (oldest first) and each epic that is running or waiting for a person.
+ * What the engine does not keep in SQLite comes in through the optional inputs and is empty (null or []) without them.
+ */
+export function buildSnapshot(db, { now, maxConcurrentEpics, maxReviews, finishedWindowDays, startedAt, repos, nextCheckAt, problem, paused, slices, version, pollIntervalMs, rateLimit = null, watched = [], lastEvent = () => null, }) {
+    const busy = db.select({ n: count() }).from(epics).where(eq(epics.status, 'running')).get().n;
+    const queue = db.select({ repo: epics.repo, issue: epics.issue, title: epics.title, queuedAt: epics.queuedAt }).from(epics).where(eq(epics.status, 'queued')).orderBy(asc(epics.id)).all()
+        .map((q) => ({ repo: q.repo, issue: q.issue, title: q.title, queuedAt: q.queuedAt }));
+    const shown = db.select().from(epics).where(inArray(epics.status, ['running', 'needs_human'])).orderBy(asc(epics.id)).all();
+    const lastExecution = (epicId) => db.select({ id: executions.executionId }).from(executions).where(eq(executions.epicId, epicId)).orderBy(desc(executions.startedAt), sql `rowid desc`).limit(1).get()?.id ?? null;
+    const done = db.select({ id: epics.id, repo: epics.repo, issue: epics.issue, title: epics.title, labels: epics.labels, prNumber: epics.prNumber, finishedAt: epics.finishedAt }).from(epics).where(eq(epics.status, 'ready_for_test')).orderBy(desc(epics.finishedAt)).limit(5).all()
+        .map(({ id, labels, ...rest }) => ({ ...rest, labels: labels ?? [], executionId: lastExecution(id) }));
+    const finished = db.select({ id: epics.id, repo: epics.repo, issue: epics.issue, title: epics.title, labels: epics.labels, prNumber: epics.prNumber, finishedAt: epics.finishedAt, status: epics.status, cancelReason: epics.cancelReason }).from(epics)
+        .where(and(inArray(epics.status, ['merged', 'cancelled']), gte(epics.finishedAt, now - finishedWindowDays * 86_400_000))).orderBy(desc(epics.finishedAt)).all()
+        .map(({ id, labels, finishedAt, status, cancelReason, ...rest }) => ({ ...rest, labels: labels ?? [], finishedAt: finishedAt, status: status, cancelReason: status === 'cancelled' ? cancelReason : null, executionId: lastExecution(id) }));
+    const epicAgents = (e) => e.config && agentsOf(e.config);
+    const sessions = shown.flatMap((e) => {
+        const agent = epicAgents(e);
+        const running = db.select({ executionId: executions.executionId, stage: executions.stage, startedAt: executions.startedAt }).from(executions)
+            .where(and(eq(executions.epicId, e.id), eq(executions.status, 'running'))).orderBy(desc(executions.startedAt), sql `rowid desc`).limit(1).get();
+        if (e.status !== 'running' || !running || !agent)
+            return [];
+        const { harness, model } = agent[running.stage === 'review' ? 'reviewer' : 'author'];
+        return [{ executionId: running.executionId, repo: e.repo, issue: e.issue, stage: running.stage, round: e.round, harness, model, startedAt: running.startedAt, last: lastEvent(running.executionId) }];
+    });
+    return {
+        now,
+        startedAt,
+        repos,
+        nextCheckAt,
+        problem,
+        paused,
+        done,
+        slots: { busy, total: maxConcurrentEpics },
+        queue,
+        engine: { version, pollIntervalMs, maxConcurrentEpics, rateLimit },
+        watched,
+        sessions,
+        finished,
+        epics: shown.map((e) => {
+            const blockers = latestBlockers(db, e.id);
+            return {
+                repo: e.repo,
+                issue: e.issue,
+                status: e.status,
+                stage: e.stage,
+                round: e.round,
+                maxReviews,
+                blockers: blockers.length,
+                stageSince: e.stageStartedAt ?? e.startedAt ?? now,
+                lastActivityAt: e.lastActivityAt,
+                issueUrl: `https://github.com/${e.repo}/issues/${e.issue}`,
+                prUrl: e.prNumber === null ? null : `https://github.com/${e.repo}/pull/${e.prNumber}`,
+                lastError: e.lastError,
+                needsHumanReason: e.needsHumanReason,
+                slices: slices(e.repo, e.issue),
+                executionId: lastExecution(e.id),
+                title: e.title,
+                labels: e.labels ?? [],
+                queuedAt: e.queuedAt,
+                startedAt: e.startedAt,
+                finishedAt: e.finishedAt,
+                branch: e.branch,
+                workspace: e.workspace,
+                needsHumanKind: e.needsHumanKind,
+                blockerTitles: blockers.slice(0, maxBlockerTitles).map((b) => b.title.slice(0, maxBlockerTitleLength)),
+                agents: epicAgents(e),
+                options: optionsOf(e),
+            };
+        }),
+    };
+}

package/dist/status/types.js

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

package/dist/storage/caller-results.js

@@ -0,0 +1,7 @@
+import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
+// One row per execution: the primary key is what makes importing a result idempotent.
+export const callerResults = sqliteTable('caller_results', {
+    executionId: text().primaryKey(),
+    outcome: text().notNull(),
+    result: text().notNull(), // the validated JSON
+});