@ashulab/carrier 0.0.0-stage → 0.1.0

package/dist/orchestration/engine.js

@@ -0,0 +1,1068 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { and, asc, desc, eq, inArray, isNotNull, isNull, notInArray, sql } from 'drizzle-orm';
+import { failoverOrderFor } from '../config/resolve.js';
+import { failoverTriggers, matchesFailoverTrigger } from '../config/schema.js';
+import { failureDetail } from '../execution/failure.js';
+import { parseCallerResult } from '../execution/caller-result.js';
+import { importResult } from '../execution/import-result.js';
+import { epicReviewThreads } from '../storage/epic-review-threads.js';
+import { epicSlices } from '../storage/epic-slices.js';
+import { callerResults } from '../storage/caller-results.js';
+import { epicEvents, recordEvents } from '../storage/events.js';
+import { executions } from '../storage/executions.js';
+import { executionOutput, taskContext } from '../logging/logger.js';
+import { epics } from '../storage/schema.js';
+import { latestBlockers, latestObservations } from './blockers.js';
+import { changesSlices } from './changes-slices.js';
+import { ResumeRefused } from './resume-refused.js';
+import { endOf } from './final-pr.js';
+import { AuthError, GitHubUnavailable, labelStyles, needsHumanLabel, ownedLabels, readyForTestLabel, readyLabel, runningLabel } from './github.js';
+import { reserve } from './reserve.js';
+import { startRetention } from './retention.js';
+import { failureStreak } from './retry.js';
+const log = createScopedLogger('engine');
+const activityEveryMs = 10_000;
+const resumeWaitMs = 30_000;
+const resumeTickMs = 1_000;
+// Slices read outside the poll: at most one read per epic in each window, and a timer as a net for what no event signals.
+const sliceWindowMs = 10_000;
+const sliceTimerMs = 60_000;
+const liveStatuses = ['running', 'needs_human', 'ready_for_test'];
+// Technical end of the process; whether the epic moves on depends on its result (retries and timeouts: later slices).
+const sessionLost = 'the agent session is not available';
+const noExit = { exitCode: null, signal: null, hostFreeMemMb: null, hostLoad: null };
+const failureColumns = (f) => f && { failureKind: f.kind, failureDetail: f.detail, exitCode: f.exitCode, signal: f.signal, hostFreeMemMb: f.hostFreeMemMb, hostLoad: f.hostLoad };
+const executionStatus = {
+    ok: 'finished',
+    failed: 'failed',
+    timed_out: 'timed_out',
+    stopped: 'interrupted',
+    auth_failed: 'failed',
+    session_unavailable: 'failed',
+};
+export function createEngine({ db, github, clock, repos, pollIntervalMs, maxConcurrentEpics, maxExecutionHours, maxExecutionRetries, maxReviews, optionChoiceSeconds, runner, workspaces, places, sessionDirs }) {
+    let error = null;
+    let nextPollAt = null;
+    let paused = false; // intake only: nothing new is reserved, what is running goes on
+    let polling = null;
+    // The orchestrator's profile failed: no GitHub call is made until the poll's probe succeeds. Never another profile.
+    let suspended = null;
+    let cancel = null;
+    let stopRetention = null;
+    const labelledRepos = new Set();
+    // Slice progress GitHub reported on the last good read, by repo and issue; not stored, so it is empty until the first poll after a start.
+    const progress = new Map();
+    // The last poll of each repo, in memory only: when, whether it worked and why not. Empty until the first poll after a start.
+    const checks = new Map();
+    // Runs of this process still going, to stop them when the epic ends from outside.
+    const active = new Map();
+    // Set by shutdown(): from then on nothing polls, reserves, launches or writes to GitHub.
+    let stopping = false;
+    // Creates the owned labels a repo lacks, with their colour and description; never touches existing ones nor creates `ready` (Solve's).
+    async function ensureLabels() {
+        for (const { name } of repos) {
+            if (stopping)
+                return;
+            if (labelledRepos.has(name))
+                continue;
+            const existing = await github.listLabels(name);
+            for (const label of ownedLabels)
+                if (!existing.includes(label))
+                    await github.createLabel(name, label, labelStyles[label]);
+            labelledRepos.add(name);
+        }
+    }
+    // The one owned label each status shows; merged and cancelled (stopped from outside) show none.
+    const labelOf = (status) => ({ running: runningLabel, needs_human: needsHumanLabel, ready_for_test: readyForTestLabel })[status];
+    // An epic a person sent back to the queue: nothing of the previous attempt is kept, the executions stay as history.
+    const restart = (queuedAt) => ({
+        status: 'queued', queuedAt, startedAt: null, config: null, labelPending: false, stage: null, stageStartedAt: null, workspace: null,
+        lastActivityAt: null, lastError: null, round: null, prNumber: null, prHeadSha: null, pr: null, reviewedSha: null, verification: null, observationsPassAt: null,
+        needsHumanReason: null, needsHumanKind: null, finishedAt: null, authorOption: null, reviewerOption: null, choiceDeadline: null,
+    });
+    // Mirrors the epic's status on its issue: its label, none of the other owned ones, and no `ready` while running.
+    const applyLabels = async ({ id, repo, issue, status }) => {
+        if (stopping || suspended)
+            return; // labelPending stays true: the next run reflects it
+        const wanted = labelOf(status);
+        await github.setLabels(repo, issue, {
+            add: wanted ? [wanted] : [],
+            remove: [...ownedLabels.filter((l) => l !== wanted), ...(status === 'running' ? [readyLabel] : [])],
+        });
+        db.update(epics).set({ labelPending: false }).where(eq(epics.id, id)).run();
+    };
+    const fresh = (id) => db.select().from(epics).where(eq(epics.id, id)).get();
+    // GitHub being down is expected (the next poll retries), and so is a failing orchestrator profile; anything else is a bug and surfaces.
+    const failed = (e) => {
+        if (e instanceof AuthError)
+            suspended = e;
+        else if (!(e instanceof GitHubUnavailable))
+            throw e;
+        error = e;
+    };
+    // The epic leaves `running` for `needs_human`; the label follows (labelPending) and the slot is free.
+    const toNeedsHuman = (writer, id, kind, reason) => writer.update(epics).set({ status: 'needs_human', needsHumanKind: kind, needsHumanReason: reason, finishedAt: clock.now(), labelPending: true }).where(eq(epics.id, id)).run();
+    // Mirrors the label, then launches the author unless the epic already has one or is waiting for its choice of options.
+    const begin = async (epic) => {
+        if (stopping)
+            return;
+        await applyLabels(epic);
+        if (epic.status !== 'running' || epic.stage !== null)
+            return;
+        const restarted = restarts.get(epic.id);
+        restarts.delete(epic.id);
+        if (restarted && epic.choiceDeadline !== null)
+            await startChosen(epic.id, declaredOnly(epic, restarted)); // already chosen at the restart: no wait
+        else if (epic.choiceDeadline === null)
+            await launch(epic, 'ship');
+        else
+            await awaitChoice(epic);
+    };
+    // The options a person picked when restarting a stopped epic, by epic id, until the poll that requeues it reserves it again.
+    // ponytail: in memory, an engine restart in between falls back to the defaults and the choice wait; persist it if that bites.
+    const restarts = new Map();
+    const declaredOnly = ({ id, config }, chosen) => Object.fromEntries(Object.entries(chosen).filter(([role, name]) => {
+        const declared = Object.hasOwn((config?.providers ?? config?.options) ?? {}, name);
+        if (!declared)
+            log.warn('the option chosen at the restart is not declared any more, the role starts on its default', { epicId: id, role, option: name });
+        return declared;
+    }));
+    // The timers of the epics waiting for their choice, by id.
+    const choiceTimers = new Map();
+    // Waits for `chooseOptions`, or for the deadline: a deadline already gone starts the epic on its defaults at once.
+    async function awaitChoice({ id, choiceDeadline }) {
+        if (choiceTimers.has(id))
+            return;
+        const wait = choiceDeadline - clock.now();
+        if (wait <= 0)
+            return void (await startChosen(id, {}));
+        choiceTimers.set(id, clock.after(wait, async () => {
+            try {
+                await startChosen(id, {});
+            }
+            catch (e) {
+                log.error('could not start the epic at the end of its choice', e, { epicId: id });
+            }
+        }));
+    }
+    // Ends the wait of a waiting epic and launches its author, on the options chosen for the roles and on the saved ones for the roles left out.
+    // False when the epic is not waiting (any more): the claim is one write, so only one caller gets it.
+    async function startChosen(id, chosen) {
+        choiceTimers.get(id)?.();
+        choiceTimers.delete(id);
+        if (stopping)
+            return false;
+        const { config, choiceDeadline } = fresh(id);
+        if (!config)
+            return false;
+        const roleOn = (role) => {
+            const name = chosen[role];
+            return name === undefined ? config.agents[role] : onOption(config, role, name);
+        };
+        const agents = { author: roleOn('author'), reviewer: roleOn('reviewer') };
+        const claimed = db
+            .update(epics)
+            .set({ config: { ...config, agents }, choiceDeadline: null, authorOption: agents.author.option ?? null, reviewerOption: agents.reviewer.option ?? null })
+            .where(and(eq(epics.id, id), eq(epics.status, 'running'), isNotNull(epics.choiceDeadline)))
+            .returning()
+            .get();
+        if (!claimed)
+            return false;
+        try {
+            await launch(claimed, 'ship');
+        }
+        catch (e) {
+            // launch reads GitHub before it takes the stage: failing there leaves no agent and no wait. The wait is put back (the options
+            // chosen stay saved in the config), and resumeChoices starts the epic again on a later poll.
+            if (fresh(id).stage === null)
+                db.update(epics).set({ choiceDeadline }).where(eq(epics.id, id)).run();
+            throw e;
+        }
+        return true;
+    }
+    // Running epics whose wait for a choice has no timer: the start failed (GitHub was down) or a timer was lost. Past its deadline, each starts now.
+    async function resumeChoices() {
+        if (stopping || suspended)
+            return;
+        for (const epic of db.select().from(epics).where(and(eq(epics.status, 'running'), isNull(epics.stage), isNotNull(epics.choiceDeadline))).orderBy(asc(epics.id)).all())
+            await awaitChoice(epic);
+    }
+    const defaultHarnessModels = {
+        claude: 'sonnet',
+        codex: 'gpt-5.3-codex',
+        agy: 'gemini-3.8-flash-low',
+    };
+    // The role of the epic's saved config pointed at another of its saved options or providers: same profile and persona.
+    const onOption = (config, role, name) => {
+        const roleAgent = config.agents[role];
+        const { profile, persona, model } = roleAgent;
+        const provider = (config.providers ?? config.options)?.[name];
+        if (!provider)
+            throw new Error(`provider "${name}" is not declared in config.providers`);
+        const modelStr = provider.model ?? (provider.harness === roleAgent.harness ? model : defaultHarnessModels[provider.harness] ?? model);
+        return {
+            profile,
+            model: modelStr,
+            harness: provider.harness,
+            ...(provider.provider && { provider: provider.provider }),
+            ...(provider.configDir && { configDir: provider.configDir }),
+            ...(persona && { persona }),
+            option: name,
+            providerName: name,
+        };
+    };
+    // With failover on, the role that ran out moves to the first option of `order` that has not run out in this epic and its stage runs
+    // again as a rebuilt session, no retry spent. `why` is what to add to the stop reason when it could not move.
+    async function failOver(epicId, stage, failedExecution) {
+        const epic = fresh(epicId);
+        const { config } = epic;
+        if (!config?.failover?.enabled)
+            return { relaunched: false, why: '' };
+        const triggers = config.failover.triggers ?? failoverTriggers;
+        if (!matchesFailoverTrigger(triggers, failedExecution.failureKind, failedExecution.failureDetail))
+            return { relaunched: false, why: '' };
+        const failoverKinds = [
+            ...(triggers.includes('usage_limit') ? ['usage_limit'] : []),
+            ...((triggers.includes('service_down') || triggers.includes('rate_limit')) ? ['api_error', 'spawn_error'] : []),
+        ];
+        const ranOut = [...new Set(db.select({ option: executions.option }).from(executions).where(and(eq(executions.epicId, epicId), inArray(executions.failureKind, failoverKinds))).orderBy(asc(sql `rowid`)).all().flatMap(({ option }) => option ?? []))];
+        const role = stage === 'review' ? 'reviewer' : 'author';
+        const order = failoverOrderFor(config.failover, role) ?? config.failover.default ?? [];
+        const next = order.find((name) => !ranOut.includes(name));
+        if (next === undefined)
+            return { relaunched: false, why: `; no provider left in failover, ran out: ${ranOut.join(', ')}` };
+        if (stopping || epic.status !== 'running')
+            return { relaunched: true };
+        // Read only; GitHub being down is not a reason to stop: the agent verifies the state first anyway.
+        const found = await github.findPullRequest(epic.repo, epic.issue).catch((e) => (failed(e), null));
+        db.transaction((tx) => {
+            tx.update(epics).set({ config: { ...config, agents: { ...config.agents, [role]: onOption(config, role, next) } }, ...(role === 'author' ? { authorOption: next } : { reviewerOption: next }) }).where(eq(epics.id, epicId)).run();
+            tx.insert(epicEvents).values({ epicId, at: clock.now(), type: 'option_switched', data: { role, from: config.agents[role].option ?? null, to: next, stage } }).run();
+        });
+        await execute(fresh(epicId), stage, failedExecution, { pr: found && { number: found.number, headSha: found.headSha } });
+        return { relaunched: true };
+    }
+    // A stage ended on its usage limit: another option of the failover list, or the epic stops for a person. The reason says how to go on
+    // (the panel cuts long lines, so the way out comes before the agent's own detail, which carries the reset time).
+    async function onUsageLimit(epicId, execution) {
+        const moved = await failOver(epicId, execution.stage, execution);
+        if (moved.relaunched)
+            return;
+        const { repo, issue } = fresh(epicId);
+        const role = execution.stage === 'review' ? 'reviewer' : 'author';
+        const detail = execution.failureDetail ? ` · ${execution.failureDetail}` : '';
+        toNeedsHuman(db, epicId, 'usage_limit', `the ${execution.stage} execution ran out of usage on option ${execution.option ?? execution.harness} · carrier restart ${repo}#${issue} --${role} <option>${detail}${moved.why}`);
+        await freeSlot();
+    }
+    // Launches the author (ship, fix) or the reviewer (review) for the epic's current stage.
+    async function launch(epic, stage) {
+        if (stopping)
+            return;
+        let rebuild;
+        if (stage === 'ship') {
+            // An author on another option than the one that wrote the epic's session cannot continue it: a new session, rebuilt like a lost one.
+            // Read before the claim: if GitHub is down this throws with the stage still free (startChosen puts the wait back).
+            const before = lastAuthor(epic.id);
+            const optionNow = epic.config.agents.author.option ?? null;
+            if (before && (before.option ?? null) !== optionNow) {
+                const pr = await github.findPullRequest(epic.repo, epic.issue);
+                rebuild = { pr: pr && { number: pr.number, headSha: pr.headSha } };
+            }
+            // Claim the launch first: concurrent reconciles (a result freeing a slot, the poll) never start a second author.
+            const claimed = db.update(epics).set({ stage: 'ship', stageStartedAt: clock.now() }).where(and(eq(epics.id, epic.id), isNull(epics.stage))).returning().get();
+            if (!claimed)
+                return;
+            if (rebuild)
+                db.insert(epicEvents).values({ epicId: epic.id, at: clock.now(), type: 'session_rebuilt', data: { stage, from: before.option, to: optionNow, pr: rebuild.pr } }).run();
+        }
+        await execute(epic, stage, undefined, rebuild);
+    }
+    // Starts an execution of the stage; `retryOf` is the failed or interrupted one it replaces: same session, verify
+    // the real state first. `rebuild` (the session is gone) starts a new session instead, with the PR as GitHub has it now.
+    async function execute(epic, stage, retryOf, rebuild) {
+        const reviewing = stage === 'review';
+        const resumeSession = rebuild ? undefined : (retryOf?.sessionId ?? (stage === 'fix' ? authorSession(epic.id) : stage === 'ship' && !retryOf ? sameOptionSession(epic) : undefined));
+        const pr = rebuild?.pr ?? (epic.prNumber ? { number: epic.prNumber, headSha: epic.prHeadSha } : undefined);
+        let workspace;
+        try {
+            if (stage === 'fix') {
+                // Where `ship` left the epic's worktree: a session resumed anywhere else would act in another cwd.
+                if (!epic.workspace)
+                    throw new Error('the epic has no saved worktree');
+                workspace = epic.workspace;
+            }
+            else
+                workspace = reviewing ? await workspaces.prepareReviewer(epic.repo, epic.issue, epic.prNumber) : await workspaces.prepareAuthor(epic.repo, epic.issue);
+        }
+        catch (e) {
+            log.error('could not prepare the workspace', e, { repo: epic.repo, epic: epic.issue, stage });
+            toNeedsHuman(db, epic.id, 'workspace', `could not prepare the workspace: ${e instanceof Error ? e.message : String(e)}`);
+            return applyLabels(fresh(epic.id));
+        }
+        const executionId = randomUUID();
+        const resultPath = join(places.state, 'results', `${executionId}.json`);
+        // A fix right after a review that completed is the observations pass; after one that asked for changes, it answers the blockers.
+        const observations = stage === 'fix' ? latestObservations(db, epic.id) : null;
+        const task = {
+            executionId,
+            repo: epic.repo,
+            epic: epic.issue,
+            stage,
+            ...(reviewing ? epic.config.agents.reviewer : epic.config.agents.author),
+            sharedIdentity: epic.config.sharedIdentity === true,
+            workspace,
+            resultPath,
+            timeoutMs: maxExecutionHours === 'unlimited' ? null : maxExecutionHours * 3_600_000,
+            ...(resumeSession && { resumeSession }),
+            context: {
+                previousSummaries: reviewing || rebuild ? previousSummaries(epic.id) : [],
+                ...(observations ? { observations } : (stage === 'fix' || (reviewing && (epic.round ?? 0) > 1)) && { blockers: latestBlockers(db, epic.id) }),
+                ...(retryOf && { verifyStateFirst: true }),
+                ...(pr && { pr }),
+                ...(epic.round && { round: epic.round }),
+            },
+        };
+        if (stopping)
+            return;
+        db.insert(executions)
+            .values({ executionId, epicId: epic.id, stage, harness: task.harness, model: task.model, provider: task.provider ?? null, option: task.option ?? null, configDir: task.configDir ?? null, workspace, round: epic.round, resultPath, startedAt: clock.now() })
+            .run();
+        const context = taskContext({ repo: epic.repo, epic: epic.issue, executionId, stage, round: epic.round });
+        log.info('execution started', context);
+        const run = runner.run(task);
+        active.set(executionId, run);
+        const output = executionOutput(places.logs, executionId);
+        // The panel's "last activity": a SQLite write at most every 10 s, not one per chunk.
+        let activityAt = null;
+        run.onOutput((stream, chunk) => {
+            output.write(stream, chunk);
+            const now = clock.now();
+            if (activityAt !== null && now - activityAt < activityEveryMs)
+                return;
+            activityAt = now;
+            db.update(epics).set({ lastActivityAt: now }).where(eq(epics.id, epic.id)).run();
+        });
+        const sliceCalls = new Set(); // calls of this execution that started and have not ended; gone with it
+        // A failed insert must not break the run: the log still has everything, and the replay script can fill the rows.
+        run.onEvent((events) => {
+            try {
+                recordEvents(db, executionId, events, clock.now());
+            }
+            catch (e) {
+                log.error('could not store the events of a chunk', e, context);
+            }
+            // A command that changes the slices is only a signal to look, and GitHub shows the change once it has ended, error or not.
+            for (const { kind, callId, arg } of events) {
+                if (callId === undefined)
+                    continue;
+                if (kind === 'tool_start' && arg !== undefined && changesSlices(arg))
+                    sliceCalls.add(callId);
+                else if (kind === 'tool_end' && sliceCalls.delete(callId))
+                    readSlicesSoon(epic.id, epic.repo, epic.issue);
+            }
+        });
+        run.onSession((sessionId) => db.update(executions).set({ sessionId }).where(eq(executions.executionId, executionId)).run());
+        track(run.done.then(async ({ exit, sessionId, failure: processFailure }) => {
+            active.delete(executionId);
+            output.flush();
+            (exit === 'ok' ? log.info : log.warn)('execution ended', { ...context, exit });
+            const failoverConfig = epic.config?.failover;
+            const triggers = failoverConfig?.enabled ? (failoverConfig.triggers ?? failoverTriggers) : [];
+            const isFailoverFailure = exit === 'failed' && processFailure?.kind !== undefined && matchesFailoverTrigger(triggers, processFailure.kind, processFailure.detail);
+            const outOfCredits = exit === 'failed' && processFailure?.kind === 'usage_limit';
+            // Like a timeout, failover leaves no error on the execution: it is not a retryable failure and ends the streak.
+            const failure = (outOfCredits || isFailoverFailure) ? undefined : { failed: `the agent process ended with an error (${processFailure?.kind ?? 'unknown'}${processFailure?.detail ? `: ${processFailure.detail}` : ''})`, auth_failed: `authentication error for profile ${task.profile}`, session_unavailable: sessionLost }[exit];
+            // The ends with their own handling carry no failure from the runner: their kind follows from the exit.
+            const endFailure = {
+                failed: { kind: 'unknown', detail: '' },
+                auth_failed: { kind: 'auth', detail: `profile ${task.profile}` },
+                session_unavailable: { kind: 'session_lost', detail: sessionLost },
+                timed_out: { kind: 'timeout', detail: `exceeded ${maxExecutionHours} h` },
+            };
+            db.update(executions)
+                .set({ status: executionStatus[exit], finishedAt: clock.now(), ...(sessionId && { sessionId }), ...(failure && { error: failure }), ...failureColumns(processFailure ?? (endFailure[exit] && { ...noExit, ...endFailure[exit] })) })
+                .where(eq(executions.executionId, executionId))
+                .run();
+            if (failure)
+                db.update(epics).set({ lastError: failure }).where(eq(epics.id, epic.id)).run();
+            if (exit === 'ok')
+                await settle(db.select().from(executions).where(eq(executions.executionId, executionId)).get());
+            else if (isFailoverFailure || outOfCredits) {
+                // Retrying the same option only burns the retries.
+                await onUsageLimit(epic.id, db.select().from(executions).where(eq(executions.executionId, executionId)).get());
+            }
+            else if (exit === 'failed' || exit === 'session_unavailable')
+                await retry(epic.id);
+            else if (exit === 'auth_failed')
+                await stopProfile(task.profile);
+            else if (exit === 'timed_out') {
+                // Session and workspace stay as they are; a person decides how to go on.
+                toNeedsHuman(db, epic.id, 'timeout', `the ${stage} execution exceeded the time limit`);
+                await freeSlot();
+            }
+        }));
+    }
+    // Forge rejected a profile: the running epics that use it stop for a person, with their runs; the others go on.
+    // The profile is never swapped for another one.
+    async function stopProfile(profile) {
+        for (const epic of db.select().from(epics).where(eq(epics.status, 'running')).orderBy(asc(epics.id)).all()) {
+            const { author, reviewer } = epic.config.agents;
+            if (author.profile !== profile && reviewer.profile !== profile)
+                continue;
+            toNeedsHuman(db, epic.id, 'auth', `authentication error for profile ${profile}`);
+            const running = db.select().from(executions).where(and(eq(executions.epicId, epic.id), eq(executions.status, 'running'))).all();
+            await Promise.all(running.map(({ executionId }) => active.get(executionId)?.stop()));
+        }
+        await freeSlot();
+    }
+    // Relaunches the stage whose last execution failed technically, until the retries run out.
+    const retrying = new Set();
+    async function retry(epicId) {
+        if (stopping || suspended || retrying.has(epicId))
+            return;
+        retrying.add(epicId);
+        try {
+            const epic = fresh(epicId);
+            const [last, ...earlier] = failureStreak(db, epicId);
+            if (epic.status !== 'running' || !last)
+                return;
+            if (earlier.length >= maxExecutionRetries) {
+                toNeedsHuman(db, epicId, 'retries_exhausted', `ran out of ${last.stage} retries (${earlier.length + 1} attempts): ${last.error}`);
+                return await freeSlot();
+            }
+            // Read only: what the failed execution may have left on GitHub. A failed query is not an attempt, the poll tries again.
+            const pr = await github.findPullRequest(epic.repo, epic.issue);
+            // A lost session is rebuilt, not resumed: new session, same profile, context from SQLite and GitHub.
+            const lost = last.failureKind === 'session_lost';
+            db.insert(epicEvents)
+                .values({ epicId, at: clock.now(), type: lost ? 'session_rebuilt' : 'execution_retried', data: { stage: last.stage, failed: last.executionId, attempt: earlier.length + 2, error: last.error, pr } })
+                .run();
+            await execute(epic, last.stage, last, lost ? { pr: pr && { number: pr.number, headSha: pr.headSha } } : undefined);
+        }
+        finally {
+            retrying.delete(epicId);
+        }
+    }
+    // Running epics whose last execution failed and was not relaunched yet (GitHub was down).
+    async function retryPending() {
+        for (const { id } of db.select({ id: epics.id }).from(epics).where(eq(epics.status, 'running')).orderBy(asc(epics.id)).all())
+            await retry(id);
+    }
+    // Summaries the caller left in earlier review and fix turns, oldest first.
+    const previousSummaries = (epicId) => db
+        .select({ result: callerResults.result })
+        .from(callerResults)
+        .innerJoin(executions, eq(executions.executionId, callerResults.executionId))
+        .where(and(eq(executions.epicId, epicId), inArray(executions.stage, ['review', 'fix'])))
+        .orderBy(asc(executions.startedAt))
+        .all()
+        .map(({ result }) => JSON.parse(result).summary);
+    // Where the author left off, and the option that wrote it.
+    const lastAuthor = (epicId) => db
+        .select({ sessionId: executions.sessionId, option: executions.option })
+        .from(executions)
+        .where(and(eq(executions.epicId, epicId), inArray(executions.stage, ['ship', 'fix']), isNotNull(executions.sessionId)))
+        .orderBy(desc(sql `rowid`))
+        .get();
+    // The fix turn resumes it.
+    const authorSession = (epicId) => lastAuthor(epicId)?.sessionId ?? undefined;
+    // A ship that starts again continues the author's session only on the option that wrote it.
+    const sameOptionSession = (epic) => {
+        const before = lastAuthor(epic.id);
+        return before && (before.option ?? null) === (epic.config.agents.author.option ?? null) ? (before.sessionId ?? undefined) : undefined;
+    };
+    const inflight = new Set();
+    const track = (work) => {
+        const tracked = work
+            .catch((e) => {
+            log.error('stage work failed', e);
+            failed(e);
+        })
+            .finally(() => inflight.delete(tracked));
+        inflight.add(tracked);
+    };
+    // Does the final PR the caller reported hold up against what GitHub says? Returns why not, or null.
+    function prProblem({ issue }, found, pr, stage) {
+        if (!found)
+            return `PR #${pr.number} does not exist`;
+        if (found.state !== 'open')
+            return `PR #${pr.number} is not open`;
+        if (!new RegExp(`\\bcloses #${issue}(?!\\d)`, 'i').test(found.body))
+            return `PR #${pr.number} does not reference the epic (missing "Closes #${issue}")`;
+        if (found.headSha !== pr.headSha) {
+            return stage === 'review' ? 'the head changed during the review' : `the head of PR #${pr.number} is ${found.headSha}, not ${pr.headSha}`;
+        }
+        return null;
+    }
+    const expectedOf = (epic, execution) => ({ executionId: execution.executionId, repo: epic.repo, epic: epic.issue, stage: execution.stage });
+    // The file the caller left, null when there is none (the parser reports it).
+    function readResult({ resultPath }) {
+        try {
+            return readFileSync(resultPath, 'utf8');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+            return null;
+        }
+    }
+    // Imports the result of a finished execution and moves the epic. Safe to repeat: the import is idempotent.
+    async function settle(execution) {
+        if (stopping || suspended)
+            return; // stays `finished` without a result: the next run imports it
+        const epic = fresh(execution.epicId);
+        if (epic.status === 'merged' || epic.status === 'cancelled' || epic.status === 'repo_removed')
+            return; // ended from outside or stopped: nothing new moves
+        const expected = expectedOf(epic, execution);
+        const raw = readResult(execution);
+        const parsed = parseCallerResult(raw, expected);
+        const context = taskContext({ repo: epic.repo, epic: epic.issue, executionId: execution.executionId, stage: execution.stage, round: epic.round });
+        if (!parsed.ok) {
+            log.warn('invalid caller result', { ...context, reason: parsed.message });
+            db.update(executions).set({ status: 'invalid_result', error: parsed.message, ...failureColumns({ ...noExit, kind: 'invalid_result', detail: failureDetail(parsed.message) }) }).where(eq(executions.executionId, execution.executionId)).run();
+            db.update(epics).set({ lastError: parsed.message }).where(eq(epics.id, epic.id)).run();
+            return retry(epic.id);
+        }
+        let problem = null;
+        let workspace;
+        let branch; // the final PR's branch
+        if (parsed.result.outcome !== 'needs_human') {
+            const { pr } = parsed.result;
+            const found = await github.getPullRequest(epic.repo, pr.number);
+            const invalid = prProblem(epic, found, pr, execution.stage);
+            if (invalid)
+                problem = { kind: 'pr_invalid', text: invalid };
+            if (!problem && execution.stage === 'ship') {
+                // Solve put the epic's worktree where its solve.md says: read it back from git, keep the real path for the fix turns.
+                branch = found.headRef;
+                try {
+                    workspace = (await workspaces.findWorktree(epic.repo, branch)) ?? undefined;
+                }
+                catch (e) {
+                    log.error('could not list the worktrees', e, context);
+                }
+                if (!workspace)
+                    problem = { kind: 'workspace', text: `could not find the worktree for branch ${branch} in the clone of ${epic.repo}` };
+            }
+        }
+        const imported = importResult(db, raw, expected, (tx, result) => {
+            const update = (set) => tx.update(epics).set(set).where(eq(epics.id, epic.id)).run();
+            if (result.outcome === 'needs_human')
+                toNeedsHuman(tx, epic.id, 'agent_needs_human', result.reason);
+            else if (problem)
+                toNeedsHuman(tx, epic.id, problem.kind, problem.text);
+            else if (execution.stage === 'ship')
+                update({ stage: 'review', stageStartedAt: clock.now(), round: 1, prNumber: result.pr.number, prHeadSha: result.pr.headSha, workspace, branch });
+            // The pass ended with the head that was reviewed: nothing to review again, the reviewer's verification stands.
+            else if (execution.stage === 'fix' && latestObservations(db, epic.id) && result.pr.headSha === epic.reviewedSha)
+                update({ status: 'ready_for_test', finishedAt: clock.now(), labelPending: true });
+            else if (execution.stage === 'fix')
+                update({ stage: 'review', stageStartedAt: clock.now(), round: (epic.round ?? 0) + 1, prHeadSha: result.pr.headSha });
+            // The round stays: the fix turn answers it, and the next review numbers the following one.
+            else if (result.outcome === 'changes_requested') {
+                if ((epic.round ?? 0) >= maxReviews)
+                    toNeedsHuman(tx, epic.id, 'review_limit', `review limit: round ${epic.round} of ${maxReviews} still has requested changes`);
+                else
+                    update({ stage: 'fix', stageStartedAt: clock.now() });
+            }
+            // The one observations pass: the author answers them on the same round, and the reviewed head and verification wait for how it ends.
+            else if (result.outcome === 'completed' && result.observations?.length && epic.observationsPassAt === null && (epic.round ?? 0) < maxReviews) {
+                update({ stage: 'fix', stageStartedAt: clock.now(), observationsPassAt: clock.now(), reviewedSha: result.pr.headSha, verification: result.verification });
+            }
+            else
+                update({ status: 'ready_for_test', reviewedSha: result.pr.headSha, verification: result.verification, finishedAt: clock.now(), labelPending: true });
+        });
+        if (!('duplicate' in imported))
+            db.update(epics).set({ lastError: null }).where(eq(epics.id, epic.id)).run();
+        log.info('result imported', { ...context, outcome: parsed.result.outcome, duplicate: 'duplicate' in imported });
+        const next = fresh(epic.id);
+        // ship and fix hand over to the reviewer, a review with changes hands over to the author.
+        if (!('duplicate' in imported) && next.status === 'running' && next.stage && next.stage !== 'ship')
+            await launch(next, next.stage);
+        await freeSlot();
+    }
+    // A result arrived: reflect it on the issue and give the freed slot to the next epic without waiting for the poll.
+    async function freeSlot() {
+        await reconcileLabels();
+        await fillSlots();
+    }
+    // The final PR was merged or the epic issue / final PR closed without merge: the epic stops and its
+    // executions too. Sessions and history stay; the label follows (labelPending) and the slot is free.
+    // Parked epics (needs_human, ready_for_test) end the same way: a person merges or closes outside Carrier.
+    async function stopEnded() {
+        for (const epic of db.select().from(epics).where(and(inArray(epics.status, ['running', 'needs_human', 'ready_for_test']), inArray(epics.repo, repos.map((r) => r.name)))).orderBy(asc(epics.id)).all()) {
+            const end = await endOf(github, epic);
+            if (!end)
+                continue;
+            db.update(epics)
+                .set({ status: end.status, ...(end.status === 'cancelled' && { cancelReason: end.reason }), finishedAt: clock.now(), labelPending: true })
+                .where(eq(epics.id, epic.id))
+                .run();
+            db.insert(epicEvents).values({ epicId: epic.id, at: clock.now(), type: `epic_${end.status}`, data: { reason: end.reason } }).run();
+            const running = db.select().from(executions).where(and(eq(executions.epicId, epic.id), eq(executions.status, 'running'))).all();
+            await Promise.all(running.map(({ executionId }) => active.get(executionId)?.stop()));
+        }
+    }
+    // Finished executions whose result could not be imported yet (GitHub was down).
+    async function settlePending() {
+        const pending = db
+            .select({ execution: executions })
+            .from(executions)
+            .leftJoin(callerResults, eq(callerResults.executionId, executions.executionId))
+            .where(and(eq(executions.status, 'finished'), isNull(callerResults.executionId)))
+            .orderBy(asc(executions.startedAt))
+            .all();
+        for (const { execution } of pending)
+            await settle(execution);
+    }
+    // SQLite is the authority: a label that did not reach GitHub is retried here.
+    async function reconcileLabels() {
+        const pending = db
+            .select()
+            .from(epics)
+            .where(and(inArray(epics.status, ['running', 'needs_human', 'ready_for_test', 'merged', 'cancelled']), eq(epics.labelPending, true)))
+            .orderBy(asc(epics.id))
+            .all();
+        for (const epic of pending)
+            await begin(epic);
+    }
+    // Starts the oldest queued epics until the concurrency limit or the queue is exhausted.
+    async function fillSlots() {
+        for (;;) {
+            if (stopping || suspended || paused)
+                return;
+            const epic = reserve(db, { maxConcurrent: maxConcurrentEpics, now: clock.now(), repos, choiceMs: optionChoiceSeconds * 1000 });
+            if (!epic)
+                return;
+            const cancelWith = (cancelReason) => db.update(epics).set({ status: 'cancelled', cancelReason, finishedAt: clock.now(), labelPending: false }).where(eq(epics.id, epic.id)).run();
+            let issue;
+            try {
+                issue = await github.getIssue(epic.repo, epic.issue);
+            }
+            catch (e) {
+                // Could not check it: give the slot back, the epic keeps its place in the queue.
+                db.update(epics).set({ status: 'queued', startedAt: null, config: null, labelPending: false, authorOption: null, reviewerOption: null, choiceDeadline: null }).where(eq(epics.id, epic.id)).run();
+                throw e;
+            }
+            if (issue.state === 'closed')
+                cancelWith('closed before it started');
+            else if (!issue.labels.includes(readyLabel))
+                cancelWith('ready label removed');
+            else {
+                // Its slices exist before it is ready: read them now so the app has the list from the first second, not after the next poll.
+                await readEpicSlices(epic.repo, epic.id, epic.issue);
+                await begin(epic); // GitHubUnavailable here leaves it reserved, labelPending
+            }
+        }
+    }
+    // Restart, before anything is reserved: stop what the previous process left alive, then continue each running
+    // epic from where it was. Safe to repeat (GitHub may be down halfway): what it relaunched is `active` or running.
+    let recovered = false;
+    async function recover() {
+        // Orphans first: no second agent may start on a workspace while the first still acts on it. An orphan is an execution
+        // this engine folder's SQLite launched: the process list is the machine's, and a live agent of another carrier is not ours to stop.
+        const ownExecution = (id) => db.select({ id: executions.executionId }).from(executions).where(eq(executions.executionId, id)).get() !== undefined;
+        for (const id of await runner.listActive())
+            if (!active.has(id) && ownExecution(id)) {
+                log.warn('stopping orphan execution', { executionId: id });
+                await runner.stop(id);
+            }
+        for (const { executionId } of db.select().from(executions).where(eq(executions.status, 'running')).all()) {
+            if (active.has(executionId))
+                continue;
+            db.update(executions).set({ status: 'interrupted', finishedAt: clock.now() }).where(eq(executions.executionId, executionId)).run();
+        }
+        // A repo missing from the config stops its pending epics, untouched, with where they were; a repo back resumes them
+        // there (a `needs_human` one stays stopped). No GitHub call, label change, execution or retry for either.
+        const configured = repos.map((r) => r.name);
+        const now = clock.now();
+        for (const epic of db.select().from(epics).where(and(inArray(epics.status, ['queued', 'running', 'needs_human']), notInArray(epics.repo, configured))).all()) {
+            const reason = 'the repo is no longer in the configuration';
+            db.update(epics).set({ status: 'repo_removed', removedFrom: epic.status, removedReason: reason }).where(eq(epics.id, epic.id)).run();
+            db.insert(epicEvents).values({ epicId: epic.id, at: now, type: 'repo_removed', data: { from: epic.status, reason } }).run();
+        }
+        for (const epic of db.select().from(epics).where(and(eq(epics.status, 'repo_removed'), inArray(epics.repo, configured))).all()) {
+            db.update(epics).set({ status: epic.removedFrom, removedFrom: null, removedReason: null }).where(eq(epics.id, epic.id)).run();
+            db.insert(epicEvents).values({ epicId: epic.id, at: now, type: 'repo_restored', data: { to: epic.removedFrom } }).run();
+        }
+        for (const { id } of db.select({ id: epics.id }).from(epics).where(eq(epics.status, 'running')).orderBy(asc(epics.id)).all()) {
+            const epic = fresh(id);
+            const last = db.select().from(executions).where(eq(executions.epicId, id)).orderBy(desc(sql `rowid`)).get();
+            log.info('recovering epic', { repo: epic.repo, epic: epic.issue, stage: epic.stage, lastStatus: last?.status });
+            if (!last && epic.choiceDeadline !== null) {
+                await awaitChoice(epic); // still waiting for its choice, or past the deadline: the defaults
+            }
+            else if (!last) {
+                // Stopped between claiming the launch and inserting the execution: no agent ever ran, so launching is not a blind restart.
+                db.update(epics).set({ stage: null }).where(eq(epics.id, id)).run();
+                await launch(fresh(id), 'ship');
+            }
+            else if (last.status === 'interrupted') {
+                // The agent may have written its result just before the cut: import it once instead of launching again.
+                if (parseCallerResult(readResult(last), expectedOf(epic, last)).ok) {
+                    db.update(executions).set({ status: 'finished' }).where(eq(executions.executionId, last.executionId)).run();
+                    await settle({ ...last, status: 'finished' });
+                }
+                else
+                    await execute(epic, last.stage, last);
+            }
+            else if (epic.stage !== null &&
+                last.status === 'failed' &&
+                (last.failureKind === 'usage_limit' ||
+                    (epic.config?.failover?.enabled &&
+                        matchesFailoverTrigger(epic.config.failover.triggers ?? failoverTriggers, last.failureKind, last.failureDetail)))) {
+                // Stopped before the epic moved on: no agent is running and none would be launched. A requeued epic (no stage yet) keeps its old
+                // executions: that history is not this stop, the restart's own launch (begin, resumeChoices) takes it from here.
+                await onUsageLimit(id, last);
+            }
+            else if (last.status === 'finished' && epic.stage && db.select().from(callerResults).where(eq(callerResults.executionId, last.executionId)).get()) {
+                await launch(epic, epic.stage); // imported, but the next stage was never launched
+            }
+        }
+        // SQLite is the authority: labels that differ on GitHub are put back.
+        for (const epic of db.select().from(epics).where(and(inArray(epics.status, ['running', 'needs_human', 'ready_for_test']), inArray(epics.repo, configured))).orderBy(asc(epics.id)).all()) {
+            const { labels } = await github.getIssue(epic.repo, epic.issue);
+            const wanted = labelOf(epic.status);
+            if (ownedLabels.some((l) => labels.includes(l) !== (l === wanted)) || (epic.status === 'running' && labels.includes(readyLabel)))
+                await applyLabels(epic);
+        }
+        recovered = true;
+    }
+    // A failed read keeps the last known values and the poll goes on: progress is only for show. A rejected profile is not "only for show".
+    async function refreshProgress(repo) {
+        try {
+            const open = await github.listOpenEpics(repo);
+            progress.set(repo, new Map(open.map(({ issue, slices }) => [issue, slices])));
+            // The same read carries the title and labels of the epics Carrier already holds, whatever their status.
+            for (const { issue, title, labels } of open)
+                db.update(epics).set({ title, labels }).where(and(eq(epics.repo, repo), eq(epics.issue, issue))).run();
+        }
+        catch (e) {
+            if (e instanceof AuthError)
+                throw e;
+            log.error('slice progress read failed, keeping the last values', e);
+        }
+    }
+    // The one refresh rule of the caches of GitHub (ADR 0008), shared by the slices and the pull request block: live epics (running, parked)
+    // are read every poll; a finished one keeps what it has and is read once only when it has nothing cached, e.g. it ended before the cache existed.
+    function toRefresh(repo, hasCache) {
+        return db.select({ id: epics.id, issue: epics.issue, status: epics.status, prNumber: epics.prNumber, pr: epics.pr }).from(epics).where(eq(epics.repo, repo)).orderBy(asc(epics.id)).all()
+            .filter((e) => liveStatuses.includes(e.status) || (['merged', 'cancelled'].includes(e.status) && !hasCache(e)));
+    }
+    // The slices of each epic to refresh, replacing its rows. A cache of GitHub: nothing the engine decides reads it back.
+    // A failed read keeps the last rows and the poll goes on.
+    // One read at a time per epic, whoever asks (the poll, an event, the timer): a read waits for the one in flight, so it starts after
+    // the other has written and an older answer never lands over a newer one.
+    const sliceReads = new Map();
+    function readEpicSlices(repo, id, issue) {
+        const inFlight = sliceReads.get(id);
+        const read = inFlight ? inFlight.then(() => readSlicesNow(repo, id, issue)) : readSlicesNow(repo, id, issue);
+        const settled = read.catch(() => { });
+        sliceReads.set(id, settled);
+        void settled.then(() => { if (sliceReads.get(id) === settled)
+            sliceReads.delete(id); });
+        return read;
+    }
+    async function readSlicesNow(repo, id, issue) {
+        try {
+            const { slices, truncated } = await github.readSlices(repo, issue);
+            const readAt = clock.now();
+            db.transaction((tx) => {
+                tx.delete(epicSlices).where(eq(epicSlices.epicId, id)).run();
+                if (slices.length > 0)
+                    tx.insert(epicSlices).values(slices.map((slice) => ({ ...slice, epicId: id, readAt, truncated }))).run();
+            });
+        }
+        catch (e) {
+            if (e instanceof AuthError)
+                throw e;
+            log.error('slices read failed, keeping the last rows', e);
+        }
+    }
+    // Reads one epic's slices now, or once at the end of the window when one was read less than sliceWindowMs ago: a burst makes one read
+    // per window and the last change is seen; one slower than the window is followed by the next, never overlapped (readEpicSlices).
+    const sliceReadAt = new Map();
+    const sliceReadLater = new Map();
+    function readSlicesSoon(id, repo, issue) {
+        if (stopping || suspended || sliceReadLater.has(id))
+            return;
+        const read = async () => {
+            sliceReadLater.delete(id);
+            if (stopping || suspended)
+                return;
+            sliceReadAt.set(id, clock.now());
+            try {
+                await readEpicSlices(repo, id, issue);
+            }
+            catch (e) {
+                failed(e); // only a rejected profile gets here: it suspends the engine like in a poll
+            }
+        };
+        const wait = (sliceReadAt.get(id) ?? -sliceWindowMs) + sliceWindowMs - clock.now();
+        if (wait <= 0)
+            track(read());
+        else
+            sliceReadLater.set(id, clock.after(wait, read));
+    }
+    // The net: every minute, whatever the events said, the slices of the live epics (also a slice taken by hand on GitHub).
+    let cancelSliceTimer = null;
+    const sliceTimer = () => {
+        if (stopping)
+            return;
+        cancelSliceTimer = clock.after(sliceTimerMs, async () => {
+            const configured = repos.map((r) => r.name);
+            for (const { id, repo, issue } of db.select().from(epics).where(and(inArray(epics.status, liveStatuses), inArray(epics.repo, configured))).orderBy(asc(epics.id)).all())
+                readSlicesSoon(id, repo, issue);
+            sliceTimer();
+        });
+    };
+    const stopSliceReads = () => {
+        cancelSliceTimer?.();
+        for (const cancelRead of sliceReadLater.values())
+            cancelRead();
+    };
+    async function refreshSlices(repo) {
+        const stored = new Set(db.select({ id: epicSlices.epicId }).from(epicSlices).all().map((r) => r.id));
+        for (const { id, issue } of toRefresh(repo, (e) => stored.has(e.id)))
+            await readEpicSlices(repo, id, issue);
+    }
+    // The pull request block and review threads of each epic to refresh that has a PR, one query per epic and none for one without. A cache of GitHub
+    // like the slices: a failed read keeps the last block and rows; a PR that GitHub does not know leaves them as they were.
+    async function refreshPullRequests(repo) {
+        for (const { id, prNumber } of toRefresh(repo, (e) => e.pr !== null || e.prNumber === null)) {
+            if (prNumber === null)
+                continue;
+            try {
+                const read = await github.readPullRequest(repo, prNumber);
+                if (read === null)
+                    continue;
+                const { pr, threads, truncated } = read;
+                const readAt = clock.now();
+                db.transaction((tx) => {
+                    tx.update(epics).set({ pr }).where(eq(epics.id, id)).run();
+                    tx.delete(epicReviewThreads).where(eq(epicReviewThreads.epicId, id)).run();
+                    if (threads.length > 0)
+                        tx.insert(epicReviewThreads).values(threads.map((thread, position) => ({ ...thread, epicId: id, position, readAt, truncated }))).run();
+                });
+            }
+            catch (e) {
+                if (e instanceof AuthError)
+                    throw e;
+                log.error('pull request read failed, keeping the last block and threads', e);
+            }
+        }
+    }
+    // Returns the wait until the next poll.
+    async function poll() {
+        if (stopping)
+            return pollIntervalMs;
+        const read = new Set();
+        try {
+            // Fetch every repo before writing: a failure on any of them leaves the queue untouched.
+            const found = [];
+            await ensureLabels();
+            if (!recovered)
+                await recover();
+            for (const { name: repo } of repos) {
+                for (const { issue, title, labels } of await github.listReadyEpics(repo))
+                    found.push({ repo, issue, title, labels });
+                await refreshProgress(repo);
+                await refreshSlices(repo);
+                await refreshPullRequests(repo);
+                checks.set(repo, { at: clock.now(), ok: true, error: null });
+                read.add(repo);
+            }
+            suspended = null; // listing worked: the orchestrator's profile is back, the cycle goes on
+            const queuedAt = clock.now();
+            db.transaction((tx) => {
+                for (const epic of found) {
+                    tx.insert(epics).values({ ...epic, queuedAt }).onConflictDoUpdate({ target: [epics.repo, epics.issue], set: { title: epic.title, labels: epic.labels } }).run();
+                    // Carrier never leaves `ready` on a stopped epic, so finding it on a `needs_human` one is a person saying "go on":
+                    // it starts again from ship, which reuses the epic's worktree and PR.
+                    tx.update(epics).set(restart(queuedAt)).where(and(eq(epics.repo, epic.repo), eq(epics.issue, epic.issue), eq(epics.status, 'needs_human'))).run();
+                }
+            });
+            await stopEnded();
+            await settlePending();
+            await retryPending();
+            await resumeChoices();
+            await reconcileLabels();
+            await fillSlots();
+            error = null;
+            return pollIntervalMs;
+        }
+        catch (e) {
+            log.error('poll failed', e);
+            failed(e);
+            // Only an expected failure gets here (`failed` rethrows the rest): the repos not read this cycle share it.
+            const reason = e instanceof AuthError ? `authentication error for profile ${e.profile}` : e.message;
+            for (const { name } of repos)
+                if (!read.has(name))
+                    checks.set(name, { at: clock.now(), ok: false, error: reason });
+            return Math.max(pollIntervalMs, (e instanceof GitHubUnavailable && e.retryAfterMs) || 0);
+        }
+    }
+    // One poll at a time: a poll asked for by a person while the timer's is running is that one.
+    const runPoll = () => {
+        if (polling)
+            return polling;
+        polling = (async () => {
+            try {
+                schedule(await poll());
+            }
+            finally {
+                polling = null;
+            }
+        })();
+        return polling;
+    };
+    const schedule = (ms) => {
+        if (stopping)
+            return;
+        nextPollAt = clock.now() + ms;
+        cancel = clock.after(ms, runPoll);
+    };
+    return {
+        async start() {
+            stopRetention = startRetention(db, places.logs, clock, sessionDirs);
+            // GitHub down: retried every cycle until it works.
+            for (const step of [ensureLabels, recover]) {
+                try {
+                    await step();
+                }
+                catch (err) {
+                    log.error('startup step failed', err);
+                    failed(err);
+                }
+            }
+            schedule(pollIntervalMs);
+            sliceTimer();
+        },
+        stop() {
+            cancel?.();
+            for (const cancelChoice of choiceTimers.values())
+                cancelChoice();
+            choiceTimers.clear();
+            stopSliceReads();
+            stopRetention?.();
+        },
+        /**
+         * Ctrl+C: stops polling and reserving, then stops every active run without waiting for its stage.
+         * Their executions end `interrupted` (session ids already saved), the epics stay `running` and
+         * nothing is written to GitHub. Resolves once those states are in SQLite.
+         */
+        async shutdown() {
+            stopping = true;
+            cancel?.();
+            for (const cancelChoice of choiceTimers.values())
+                cancelChoice();
+            choiceTimers.clear();
+            stopSliceReads();
+            stopRetention?.();
+            await Promise.all([...active.values()].map((run) => run.stop()));
+            while (inflight.size > 0)
+                await Promise.all([...inflight]);
+        },
+        /** Resolves when no execution is being followed any more. */
+        async idle() {
+            while (inflight.size > 0)
+                await Promise.all([...inflight]);
+        },
+        /** Polls now instead of waiting for the interval, then goes on from there. */
+        pollNow() {
+            if (stopping)
+                return Promise.resolve();
+            cancel?.();
+            return runPoll();
+        },
+        /**
+         * Puts `ready` on a stopped epic's issue, as a person does, and checks now; resolves once the epic is no longer in
+         * needs_human. It restarts on the option named for each role and on the one it has for a role left out, without waiting for a choice.
+         * Rejects with ResumeRefused: nothing was changed unless it is `did not restart`, which leaves the label for the next check.
+         */
+        async resumeEpic(repo, issue, chosen = {}) {
+            const epic = db.select().from(epics).where(and(eq(epics.repo, repo), eq(epics.issue, issue))).get();
+            if (!epic)
+                throw new ResumeRefused('unknown epic');
+            if (epic.status !== 'needs_human')
+                throw new ResumeRefused('not stopped');
+            // The requeue freezes the epic's options again from the configuration the engine runs with, so that is what the names are checked against.
+            const repoConfig = repos.find((r) => r.name === repo);
+            const declared = (repoConfig?.providers ?? repoConfig?.options) ?? {};
+            if ([chosen.author, chosen.reviewer].some((name) => name !== undefined && !Object.hasOwn(declared, name)))
+                throw new ResumeRefused('unknown option');
+            // A role left out keeps the option it has: the epic is not asked again.
+            const author = chosen.author ?? epic.authorOption;
+            const reviewer = chosen.reviewer ?? epic.reviewerOption;
+            restarts.set(epic.id, { ...(author && { author }), ...(reviewer && { reviewer }) });
+            try {
+                await github.setLabels(repo, issue, { add: [readyLabel], remove: [] });
+            }
+            catch (e) {
+                restarts.delete(epic.id);
+                if (e instanceof GitHubUnavailable || e instanceof AuthError)
+                    throw new ResumeRefused('github unavailable');
+                throw e;
+            }
+            // Not awaited: the wait below has the deadline. A poll already running is the one that answers, but it may have listed
+            // before the label went on: once it settles with the epic still stopped, one more check is asked for.
+            const check = () => this.pollNow().catch((e) => log.error('check for a resumed epic failed', e));
+            let settled = false;
+            void check().then(() => (settled = true));
+            let again = false;
+            const deadline = clock.now() + resumeWaitMs;
+            while (fresh(epic.id).status === 'needs_human') {
+                if (clock.now() >= deadline) {
+                    restarts.delete(epic.id);
+                    throw new ResumeRefused('did not restart');
+                }
+                if (settled && !again) {
+                    again = true;
+                    void check();
+                }
+                await new Promise((resolve) => clock.after(resumeTickMs, async () => resolve()));
+            }
+        },
+        /**
+         * Ends the wait of an epic that is waiting for its choice: it starts on the option named for each role and on the saved one for a role left out,
+         * and this resolves once the author is launched. Rejects with ResumeRefused, changing nothing: an unknown epic, one that is not waiting, an option not declared.
+         */
+        async chooseOptions(repo, issue, chosen) {
+            const epic = db.select().from(epics).where(and(eq(epics.repo, repo), eq(epics.issue, issue))).get();
+            if (!epic)
+                throw new ResumeRefused('unknown epic');
+            if (epic.status !== 'running' || epic.choiceDeadline === null)
+                throw new ResumeRefused('not waiting');
+            const declared = (epic.config?.providers ?? epic.config?.options) ?? {};
+            if ([chosen.author, chosen.reviewer].some((name) => name !== undefined && !Object.hasOwn(declared, name)))
+                throw new ResumeRefused('unknown option');
+            if (!(await startChosen(epic.id, chosen)))
+                throw new ResumeRefused('not waiting');
+        },
+        /** Stops (or resumes) taking epics from the queue; running epics are not touched. Resuming fills the free slots at once. */
+        setPaused(value) {
+            paused = value;
+            return value ? Promise.resolve() : this.pollNow();
+        },
+        get paused() {
+            return paused;
+        },
+        /** When the next poll is due (ms since epoch); null before the first one is scheduled. */
+        get nextPollAt() {
+            return nextPollAt;
+        },
+        /** Last GitHub failure, null once a poll succeeds. */
+        get error() {
+            return error;
+        },
+        /** Slices closed out of the total on the last good read; null until the first one or when GitHub sends none. */
+        slices: (repo, issue) => progress.get(repo)?.get(issue) ?? null,
+        /** The last poll of a repo; undefined until the first one after a start. */
+        lastCheck: (repo) => checks.get(repo),
+        /** Queued epics, oldest first. */
+        queue: () => db.select().from(epics).where(eq(epics.status, 'queued')).orderBy(asc(epics.id)).all(),
+    };
+}