@dfsramos/foreman 0.0.0-stage → 0.3.0

package/dist/runner.js

@@ -0,0 +1,1281 @@
+import { EventEmitter } from 'node:events';
+import { stopOrphanedAgent } from './agent/process.js';
+import { buildAgentReviewPrompt, buildPrompt, buildReviewPrompt, parseBlocked, parseCiVerdict, parseReviewVerdict, parseVerdict, } from './agent/prompt.js';
+import { PRIORITY_WEIGHTS } from './projects.js';
+import { AGENT_REVIEWER, CI_MAX_RERUNS, decideAgentReviewStart, decideCiFollowUp, decideRoundStart, followUp, latestOf, pickReviewer, } from './review/decide.js';
+import { checkReviews, ciOf, handOverCi, progressOf, saveProgress } from './review/loop.js';
+import { getSourceType } from './sources/registry.js';
+/** Candidates older than this are fetched again before one is claimed: claiming a task that has moved on would pull it back. */
+const CANDIDATE_FRESH_MS = 5000;
+/** Pull requests are checked for feedback at most this often per project, to stay well inside GitHub's rate limit. */
+const REVIEW_CHECK_MS = 120_000;
+/** How long an agent's sign-in check is trusted before it is asked again, whatever the answer was. */
+const SIGN_IN_RECHECK_MS = 60_000;
+const PICKED_UP = 'Foreman: picked up.';
+/** Copilot's reviewer login; `requestReview` turns it into the name gh asks Copilot by. */
+const COPILOT_REVIEWER = 'copilot-pull-request-reviewer';
+const RESULT_COMMENT_LIMIT = 2000;
+const REASON_LIMIT = 500;
+const USAGE_SETTING = 'agentUsage';
+const WINDOW_NAMES = { five_hour: '5-hour', seven_day: '7-day' };
+const errorMessage = (error) => (error instanceof Error ? error.message : String(error));
+const truncate = (text, limit) => (text.length > limit ? `${text.slice(0, limit)}…` : text);
+const configured = (agent) => agent.enabled && agent.available && agent.maxConcurrent > 0;
+const windowName = (key) => WINDOW_NAMES[key] ?? key.replace(/_/g, ' ');
+const allowed = (project, agent) => project.agents.length === 0 || project.agents.includes(agent.id);
+/** A reset time in the machine's local time, with the date only when it is not today. */
+export function formatReset(iso, now) {
+    const date = new Date(iso);
+    const time = `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
+    if (date.toDateString() === now.toDateString())
+        return time;
+    return `${date.toLocaleDateString('en-GB', { weekday: 'short', day: 'numeric', month: 'short' })} ${time}`;
+}
+/** Change in utilization per window between two reports; null where the window reset in between. */
+export function usageDelta(start, end, shared) {
+    const windows = {};
+    for (const [name, after] of Object.entries(end.windows)) {
+        const before = start.windows[name];
+        windows[name] = before && before.resetsAt === after.resetsAt ? Math.max(0, after.utilization - before.utilization) : null;
+    }
+    return { windows, shared };
+}
+/**
+ * Polls each started project for work and hands free agent slots to the projects that have some.
+ * Several runs can be in progress at once, up to each agent's concurrency limit. When projects
+ * compete for a slot they take weighted turns by priority, so a busy project cannot starve another.
+ */
+export class Runner extends EventEmitter {
+    deps;
+    now;
+    setTimer;
+    clearTimer;
+    projects = new Map();
+    active = new Map();
+    /** Tasks being claimed, before their run exists. */
+    claiming = new Map();
+    /** Tail of the queue of git operations per repository; git's own locks do not tolerate overlap. */
+    repoLocks = new Map();
+    /** Latest account usage reported by each agent's CLI; kept across restarts. */
+    usage = new Map();
+    /** The latest sign-in check per agent id, and when it was made. */
+    signIns = new Map();
+    filling = null;
+    fillAgain = false;
+    served = 0;
+    constructor(deps) {
+        super();
+        this.deps = deps;
+        this.now = deps.now ?? (() => new Date());
+        this.setTimer = deps.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+        this.clearTimer = deps.clearTimer ?? ((handle) => clearTimeout(handle));
+        try {
+            const stored = deps.db.getSetting(USAGE_SETTING);
+            for (const [agentId, usage] of Object.entries(stored ?? {}))
+                this.usage.set(agentId, usage);
+        }
+        catch {
+            // Usage is informational; a bad stored value is simply dropped.
+        }
+    }
+    /* ---------- status ---------- */
+    getStatus() {
+        const projects = this.deps.getProjects().map((project) => this.projectStatus(project.id));
+        const anyStarted = projects.some((project) => project.state === 'idle' || project.state === 'working');
+        const busy = this.active.size > 0 || this.claiming.size > 0 || [...this.projects.values()].some((state) => state.releasing !== null);
+        return {
+            state: anyStarted ? (busy ? 'working' : 'idle') : busy ? 'stopping' : 'stopped',
+            projects,
+            activeRunIds: [...this.active.keys()],
+        };
+    }
+    projectStatus(projectId) {
+        const state = this.projects.get(projectId);
+        const activeRunIds = [...this.active.entries()].filter(([, entry]) => entry.projectId === projectId).map(([id]) => id);
+        const busy = activeRunIds.length > 0 || [...this.claiming.values()].includes(projectId) || (state !== undefined && state.releasing !== null);
+        return {
+            id: projectId,
+            state: state?.started ? (busy ? 'working' : 'idle') : busy ? 'stopping' : 'stopped',
+            lastPollAt: state?.lastPollAt ?? null,
+            nextPollAt: state?.nextPollAt ?? null,
+            lastError: state?.lastError ?? state?.reviewError ?? null,
+            waiting: (state?.candidates.length ?? 0) + (state?.reviewWork.length ?? 0) > 0,
+            activeRunIds,
+            inReview: state?.inReview ?? 0,
+            awaitingApproval: state?.awaitingApproval ?? 0,
+        };
+    }
+    /** True when the agent's latest sign-in check, still within its recheck window, found it signed out. */
+    signedOut(agentId) {
+        const check = this.signIns.get(agentId);
+        return check !== undefined && !check.signedIn && this.now().getTime() - check.at < SIGN_IN_RECHECK_MS;
+    }
+    /** Latest account usage per agent id, for agents whose CLI reports it. */
+    getUsage() {
+        return Object.fromEntries(this.usage);
+    }
+    /**
+     * Why an agent may not take new work because of the account's plan usage, or null when it may.
+     * A window whose reset time has passed no longer counts, so a pause lifts by itself.
+     */
+    pauseReason(agent) {
+        const usage = this.usage.get(agent.id);
+        if (!usage)
+            return null;
+        const now = this.now().getTime();
+        const current = Object.entries(usage.windows).filter(([, window]) => !window.resetsAt || new Date(window.resetsAt).getTime() > now);
+        // Every window has reset since the report: nothing in it is known to hold any more.
+        if (current.length === 0)
+            return null;
+        if (agent.maxUsagePercent !== null) {
+            for (const [name, window] of current) {
+                const percent = Math.round(window.utilization * 100);
+                if (window.utilization * 100 >= agent.maxUsagePercent) {
+                    const until = window.resetsAt ? `, resets ${formatReset(window.resetsAt, this.now())}` : '';
+                    return `${windowName(name)} plan usage is at ${percent}% (limit ${agent.maxUsagePercent}%${until})`;
+                }
+            }
+        }
+        if (usage.usingOverage && !agent.allowOverage)
+            return 'the account is spending paid overage';
+        return null;
+    }
+    /* ---------- control ---------- */
+    /** Begins polling a project. Returns false unless that project exists and is fully stopped. */
+    startProject(projectId) {
+        if (!this.deps.getProjects().some((project) => project.id === projectId))
+            return false;
+        if (this.projectStatus(projectId).state !== 'stopped')
+            return false;
+        const state = this.stateOf(projectId);
+        state.started = true;
+        state.lastError = null;
+        this.emitStatus();
+        this.launchPoll(projectId);
+        return true;
+    }
+    /** Stops polling a project; its runs in progress are allowed to finish. Returns false when it is not started. */
+    stopProject(projectId) {
+        const state = this.projects.get(projectId);
+        if (!state?.started)
+            return false;
+        state.started = false;
+        state.generation += 1;
+        state.candidates = [];
+        state.reviewWork = [];
+        this.cancelTimer(state);
+        this.releaseIfIdle(projectId);
+        this.emitStatus();
+        return true;
+    }
+    /** Starts every stopped project. Returns how many were started. */
+    startAll() {
+        return this.deps.getProjects().filter((project) => this.startProject(project.id)).length;
+    }
+    /** Stops every started project. Returns how many were stopped. */
+    stopAll() {
+        return [...this.projects.keys()].filter((projectId) => this.stopProject(projectId)).length;
+    }
+    /** Forgets a project that no longer exists. Returns false while it is started or has runs in progress. */
+    forgetProject(projectId) {
+        if (this.projectStatus(projectId).state !== 'stopped')
+            return false;
+        this.projects.delete(projectId);
+        return true;
+    }
+    /**
+     * Has the source hand the lease back once a stopped project's runs and claims are over, after any
+     * poll or refresh still in flight. The project reads `stopping` until the hand-back has landed, so a restart
+     * waits for it; a hand-back that fails is reported and the project is stopped all the same.
+     */
+    releaseIfIdle(projectId) {
+        const state = this.projects.get(projectId);
+        const source = state?.source;
+        if (!state || state.started || state.releasing !== null || !source?.release)
+            return;
+        if ([...this.active.values()].some((entry) => entry.projectId === projectId) || [...this.claiming.values()].includes(projectId))
+            return;
+        state.releasing = (async () => {
+            // A poll in flight when the project stopped, or a fill pass refreshing its candidates, may be taking the
+            // lease; the hand-back comes after them.
+            await state.polling;
+            await this.filling;
+            if (state.started)
+                return;
+            await source.release();
+        })()
+            .catch((error) => {
+            state.lastError = `Could not hand back the lease: ${errorMessage(error)}`;
+        })
+            .finally(() => {
+            state.releasing = null;
+            this.emitStatus();
+        });
+        this.emitStatus();
+    }
+    /** Kills the agent of one run. Returns false when that run is not active or has nothing left to stop. */
+    abort(runId) {
+        const entry = this.active.get(runId);
+        if (!entry || !entry.abortable || entry.controller.signal.aborted)
+            return false;
+        entry.controller.abort();
+        return true;
+    }
+    /** Aborts every run and every claim in progress. Used on shutdown. */
+    abortAll() {
+        let count = 0;
+        for (const controller of this.claiming.keys())
+            controller.abort();
+        for (const runId of this.active.keys()) {
+            if (this.abort(runId))
+                count += 1;
+        }
+        return count;
+    }
+    /** Resolves once the polls in flight, the slot allocation, every active run and every hand-back of a lease have finished. */
+    async settled() {
+        const pending = () => [
+            this.filling,
+            ...[...this.projects.values()].map((state) => state.polling),
+            ...[...this.projects.values()].map((state) => state.releasing),
+            ...[...this.active.values()].map((entry) => entry.done),
+        ];
+        while (pending().some((promise) => promise !== null)) {
+            await Promise.all(pending());
+        }
+    }
+    /** Marks runs left "running" by a previous process as failed, stops their agents and tells the tracker. */
+    async recoverInterrupted() {
+        const stopAgent = this.deps.stopOrphanedAgent ?? stopOrphanedAgent;
+        for (const stale of this.deps.db.listRunning()) {
+            const reason = 'Foreman restarted while this run was in progress';
+            const run = this.deps.db.finishRun(stale.id, 'failed', reason);
+            this.emit('run', run);
+            try {
+                const bin = this.deps.getAgents().find((agent) => agent.id === stale.agent)?.bin;
+                if (stale.agentPid !== null && bin && stopAgent(stale.agentPid, bin)) {
+                    this.log(run.id, 'foreman', `Stopped the agent left running by the previous foreman process (pid ${stale.agentPid}).`);
+                }
+                const project = this.deps.getProjects().find((candidate) => candidate.id === stale.projectId);
+                if (project) {
+                    const source = this.deps.createSource(project);
+                    const task = { id: run.issueId };
+                    await this.commentQuietly(run, source, task, this.failureComment(run, `Foreman: run failed.\n\n${reason}.`, source));
+                }
+                else {
+                    this.log(run.id, 'foreman', 'The project this run belonged to no longer exists, so its tracker was not told.');
+                }
+            }
+            catch (error) {
+                this.log(run.id, 'foreman', `Could not finish recovering ${run.identifier}: ${errorMessage(error)}`);
+            }
+        }
+    }
+    /* ---------- polling ---------- */
+    stateOf(projectId) {
+        let state = this.projects.get(projectId);
+        if (!state) {
+            state = {
+                started: false,
+                generation: 0,
+                timer: null,
+                polling: null,
+                releasing: null,
+                lastPollAt: null,
+                nextPollAt: null,
+                lastError: null,
+                candidates: [],
+                source: null,
+                fetchedAt: 0,
+                reviewWork: [],
+                reviewCheckedAt: 0,
+                reviewError: null,
+                inReview: 0,
+                awaitingApproval: 0,
+                credit: 0,
+                lastServed: 0,
+            };
+            this.projects.set(projectId, state);
+        }
+        return state;
+    }
+    launchPoll(projectId) {
+        const state = this.stateOf(projectId);
+        const generation = state.generation;
+        const live = () => state.started && state.generation === generation;
+        const poll = this.poll(projectId, state, live)
+            .catch((error) => {
+            // poll() handles its own failures; this guards against a bug taking the loop down.
+            if (live())
+                state.lastError = `Unexpected error: ${errorMessage(error)}`;
+        })
+            .finally(() => {
+            if (state.polling === poll)
+                state.polling = null;
+            if (live())
+                this.schedule(projectId, state);
+            // A project stopped during its first poll has its source only now.
+            this.releaseIfIdle(projectId);
+            this.requestFill();
+        });
+        state.polling = poll;
+    }
+    /** Asks one project's tracker what is waiting. Claims nothing; that is `fill()`'s job. */
+    async poll(projectId, state, live) {
+        state.lastPollAt = this.now().toISOString();
+        state.nextPollAt = null;
+        this.emitStatus();
+        const project = this.deps.getProjects().find((candidate) => candidate.id === projectId);
+        if (!project) {
+            // Deleted while started.
+            state.started = false;
+            return;
+        }
+        const blocked = this.noAgentReason(project);
+        if (blocked) {
+            state.lastError = blocked;
+            state.candidates = [];
+            return;
+        }
+        try {
+            await this.refresh(project, state);
+            if (!live()) {
+                state.candidates = [];
+                return;
+            }
+            state.lastError = null;
+        }
+        catch (error) {
+            if (!live())
+                return;
+            state.lastError = errorMessage(error);
+            state.candidates = [];
+            return;
+        }
+        if (project.reviewMaxRounds > 0 && this.now().getTime() - state.reviewCheckedAt >= REVIEW_CHECK_MS) {
+            try {
+                const problems = await this.checkReviews(project, state);
+                if (live())
+                    state.reviewError = problems;
+            }
+            catch (error) {
+                // New work is unaffected; only the watching of pull requests is.
+                if (live())
+                    state.reviewError = `Review check failed: ${errorMessage(error)}`;
+                state.reviewWork = [];
+            }
+            if (!live())
+                state.reviewWork = [];
+        }
+    }
+    /**
+     * Looks at the pull request of every issue in review or awaiting approval: finishes the merged
+     * ones, moves plainly approved ones on, and queues the rest of the new feedback for an agent.
+     * Returns what went wrong with single issues, which were left as they were, or null.
+     */
+    async checkReviews(project, state) {
+        const source = state.source ?? this.deps.createSource(project);
+        state.reviewCheckedAt = this.now().getTime();
+        const busy = new Set([...this.active.values()].map((entry) => entry.taskId));
+        const { db, git } = this.deps;
+        const check = await checkReviews({ db, git, now: this.now }, project, source, busy);
+        state.inReview = check.inReview;
+        state.awaitingApproval = check.awaitingApproval;
+        state.source = source;
+        state.reviewWork = check.work;
+        return check.errors.length > 0 ? check.errors.join('; ') : null;
+    }
+    async refresh(project, state) {
+        const source = this.deps.createSource(project);
+        const candidates = await source.fetchCandidates();
+        // A tracker may still list a task for a moment after it was claimed.
+        const taken = new Set([...this.active.values()].map((entry) => entry.taskId));
+        state.source = source;
+        state.candidates = candidates.filter((task) => !taken.has(task.id));
+        state.fetchedAt = this.now().getTime();
+    }
+    /** Why no agent can work on this project at all, or null when at least one could. */
+    noAgentReason(project) {
+        const agents = this.deps.getAgents().filter((agent) => allowed(project, agent));
+        if (agents.some((agent) => this.usable(agent)))
+            return null;
+        const reasons = agents.filter(configured).flatMap((agent) => {
+            if (this.signedOut(agent.id))
+                return [`${agent.adapter.name} is not signed in (checked again within a minute)`];
+            const paused = this.pauseReason(agent);
+            return paused ? [`${agent.adapter.name} is paused: ${paused}`] : [];
+        });
+        if (reasons.length > 0)
+            return `No agent can take work: ${reasons.join('; ')}`;
+        return project.agents.length > 0
+            ? 'No agent can take work: none of the agents allowed for this project is enabled and installed'
+            : 'No agent can take work: enable at least one installed agent with a concurrency above zero';
+    }
+    schedule(projectId, state) {
+        const project = this.deps.getProjects().find((candidate) => candidate.id === projectId);
+        if (!project)
+            return;
+        const ms = project.pollIntervalSeconds * 1000;
+        this.cancelTimer(state);
+        state.nextPollAt = new Date(this.now().getTime() + ms).toISOString();
+        state.timer = this.setTimer(() => {
+            state.timer = null;
+            if (state.started)
+                this.launchPoll(projectId);
+        }, ms);
+        this.emitStatus();
+    }
+    cancelTimer(state) {
+        if (state.timer !== null) {
+            this.clearTimer(state.timer);
+            state.timer = null;
+        }
+        state.nextPollAt = null;
+    }
+    /* ---------- slot allocation ---------- */
+    usable(agent) {
+        return configured(agent) && this.pauseReason(agent) === null && !this.signedOut(agent.id);
+    }
+    /**
+     * Asks whether the agent is signed in, at most once per recheck window. A signed-out agent takes
+     * no work until a later check finds it signed in; an answer that cannot be read lets it work.
+     */
+    async confirmSignedIn(project, agent) {
+        if (!this.deps.checkSignIn)
+            return true;
+        const cached = this.signIns.get(agent.id);
+        if (cached && this.now().getTime() - cached.at < SIGN_IN_RECHECK_MS)
+            return cached.signedIn;
+        const check = await this.deps.checkSignIn(agent);
+        const signedIn = check.signedIn !== false;
+        this.signIns.set(agent.id, { signedIn, at: this.now().getTime() });
+        if (!signedIn) {
+            this.stateOf(project.id).lastError = this.noAgentReason(project);
+            this.emitStatus();
+        }
+        return signedIn;
+    }
+    /** The first agent in preference order that this project may use and that has a slot free. */
+    freeAgent(project, agents) {
+        return this.freeAgents(project, agents)[0];
+    }
+    /** Every agent this project may use that has a slot free, in preference order. */
+    freeAgents(project, agents) {
+        const counts = new Map();
+        for (const entry of this.active.values())
+            counts.set(entry.agentId, (counts.get(entry.agentId) ?? 0) + 1);
+        return agents.filter((agent) => allowed(project, agent) && this.usable(agent) && (counts.get(agent.id) ?? 0) < agent.maxConcurrent);
+    }
+    /** Runs `fill()` now, or once more after the pass already in progress. */
+    requestFill() {
+        if (this.filling) {
+            this.fillAgain = true;
+            return;
+        }
+        const pass = this.fill()
+            .catch(() => {
+            // fill() reports its failures on the project concerned.
+        })
+            .finally(() => {
+            this.filling = null;
+            if (this.fillAgain) {
+                this.fillAgain = false;
+                this.requestFill();
+            }
+        });
+        this.filling = pass;
+    }
+    /** Hands free agent slots to projects with work waiting, one task at a time, until either runs out. */
+    async fill() {
+        for (;;) {
+            const agents = this.deps.getAgents();
+            const projects = this.deps.getProjects();
+            const eligible = projects.filter((project) => {
+                const state = this.projects.get(project.id);
+                return state?.started && state.candidates.length + state.reviewWork.length > 0 && this.freeAgent(project, agents) !== undefined;
+            });
+            if (eligible.length === 0)
+                return;
+            const project = this.takeTurn(eligible);
+            const state = this.stateOf(project.id);
+            // Work already under review comes before new work: finish what was started.
+            if (state.reviewWork[0]?.agentReview) {
+                const item = state.reviewWork[0];
+                const pick = pickReviewer(project.reviewMode, this.deps.db.authorAgent(item.task.id), this.freeAgents(project, agents));
+                // No suitable reviewer free now: the next review check offers it again.
+                if (!pick) {
+                    state.reviewWork.shift();
+                    continue;
+                }
+                if (!(await this.confirmSignedIn(project, pick.agent)))
+                    continue;
+                state.reviewWork.shift();
+                if (state.source)
+                    await this.startAgentReview(project, state.source, item, pick.agent, pick.self);
+                continue;
+            }
+            if (state.reviewWork.length > 0) {
+                const reviewer = this.freeAgent(project, agents);
+                if (!reviewer || !(await this.confirmSignedIn(project, reviewer)))
+                    continue;
+                const review = state.reviewWork.shift();
+                if (review && state.source)
+                    await this.startReview(project, state.source, review, reviewer);
+                continue;
+            }
+            if (this.now().getTime() - state.fetchedAt > CANDIDATE_FRESH_MS) {
+                try {
+                    await this.refresh(project, state);
+                }
+                catch (error) {
+                    state.lastError = errorMessage(error);
+                    state.candidates = [];
+                    this.emitStatus();
+                }
+                // The project may have been stopped, or its work taken elsewhere, while the tracker answered.
+                if (!state.started || state.candidates.length === 0)
+                    continue;
+            }
+            const agent = this.freeAgent(project, agents);
+            if (!agent || !(await this.confirmSignedIn(project, agent)))
+                continue;
+            const task = state.candidates.shift();
+            const source = state.source;
+            if (!task || !source)
+                continue;
+            const claimed = await this.claim(project, source, task, agent);
+            // A failed claim usually means the tracker is unhappy; the rest can wait for the next poll.
+            if (!claimed)
+                state.candidates = [];
+        }
+    }
+    /**
+     * Smooth weighted round-robin: every contender earns its weight, the richest goes next and pays
+     * the sum of all weights. Over time each project is served in proportion to its weight.
+     */
+    takeTurn(eligible) {
+        let total = 0;
+        for (const project of eligible) {
+            const weight = PRIORITY_WEIGHTS[project.priority];
+            this.stateOf(project.id).credit += weight;
+            total += weight;
+        }
+        const chosen = eligible.reduce((best, project) => {
+            const a = this.stateOf(best.id);
+            const b = this.stateOf(project.id);
+            return b.credit > a.credit || (b.credit === a.credit && b.lastServed < a.lastServed) ? project : best;
+        });
+        const state = this.stateOf(chosen.id);
+        state.credit -= total;
+        state.lastServed = ++this.served;
+        return chosen;
+    }
+    /** Claims a task and starts its run without waiting for it. Returns false when the claim failed. */
+    async claim(project, source, task, agent) {
+        const state = this.stateOf(project.id);
+        // Created before the claim so that a shutdown can stop a run that is still being claimed.
+        const controller = new AbortController();
+        this.claiming.set(controller, project.id);
+        this.emitStatus();
+        let run;
+        try {
+            await source.claim(task);
+            run = this.deps.db.createRun(task, agent.id, project);
+        }
+        catch (error) {
+            // Not claimed, or claimed but unrecordable: either way no run exists.
+            state.lastError = `Could not claim ${task.identifier}: ${errorMessage(error)}`;
+            this.claiming.delete(controller);
+            this.releaseIfIdle(project.id);
+            this.emitStatus();
+            return false;
+        }
+        this.begin(run, task, project, source, agent, controller);
+        return true;
+    }
+    /**
+     * Hands a round of review feedback to an agent, or, once the round limit is reached, hands the
+     * issue over to a person. Returns after the run has started, without waiting for it.
+     */
+    async startReview(project, source, item, agent) {
+        const state = this.stateOf(project.id);
+        const { task } = item;
+        const controller = new AbortController();
+        this.claiming.set(controller, project.id);
+        this.emitStatus();
+        try {
+            // The feedback was found some time ago; look again before acting on it.
+            const pr = await this.deps.git.pullRequest(project.repoPath, task.branchName);
+            const progress = await progressOf(this.deps.db, source, task);
+            const ci = await ciOf(this.deps.git, project, pr);
+            const decision = decideRoundStart({ pr, progress, ignoreAuthors: project.reviewIgnoreAuthors, now: this.now(), maxRounds: project.reviewMaxRounds, ci });
+            if (decision.kind === 'none' || !pr)
+                return;
+            if (decision.kind === 'hand_over') {
+                await this.handOver(source, item, pr, progress, decision);
+                return;
+            }
+            const { round, feedback, conflict, ciFailures } = decision;
+            await source.claim(task);
+            const run = this.deps.db.createRun(task, agent.id, project, { round, branch: task.branchName });
+            this.begin(run, task, project, source, agent, controller, {
+                item: { ...item, pr, feedback, conflict, ...(ciFailures ? { ciFailures } : { ciFailures: undefined }) },
+                round,
+            });
+        }
+        catch (error) {
+            state.reviewError = `Could not start the review of ${task.identifier}: ${errorMessage(error)}`;
+        }
+        finally {
+            this.claiming.delete(controller);
+            this.releaseIfIdle(project.id);
+            this.emitStatus();
+        }
+    }
+    /**
+     * Has an agent review the pull request, or, once the round limit is reached, hands the issue over
+     * to a person. The issue stays in review while the reviewer reads. Returns once the run has started.
+     */
+    async startAgentReview(project, source, item, agent, self) {
+        const state = this.stateOf(project.id);
+        const { task } = item;
+        const controller = new AbortController();
+        this.claiming.set(controller, project.id);
+        this.emitStatus();
+        try {
+            const pr = await this.deps.git.pullRequest(project.repoPath, task.branchName);
+            const progress = await progressOf(this.deps.db, source, task);
+            const decision = decideAgentReviewStart({ pr, progress, maxRounds: project.reviewMaxRounds, now: this.now() });
+            if (decision.kind === 'none' || !pr)
+                return;
+            if (decision.kind === 'hand_over') {
+                await this.handOver(source, item, pr, progress, decision);
+                return;
+            }
+            const run = this.deps.db.createRun(task, agent.id, project, { round: decision.round, branch: task.branchName, kind: 'agent_review' });
+            this.begin(run, task, project, source, agent, controller, { item: { ...item, pr }, round: decision.round, agentReview: { self } });
+        }
+        catch (error) {
+            state.reviewError = `Could not start the agent review of ${task.identifier}: ${errorMessage(error)}`;
+        }
+        finally {
+            this.claiming.delete(controller);
+            this.releaseIfIdle(project.id);
+            this.emitStatus();
+        }
+    }
+    /** At the round limit: tells the issue a person is needed, moves it to approval if it is in review, and stops raising it. */
+    async handOver(source, item, pr, progress, decision) {
+        const { approval } = source.describe();
+        await source.comment(item.task, `Foreman: ${decision.rounds} rounds of follow-up have been handled and the pull request needs attention again (${decision.needs}). Handing over to a person${item.stage === 'review' ? `; moved to "${approval}"` : ''}: ${pr.url}`);
+        if (item.stage === 'review')
+            await source.approve(item.task);
+        await saveProgress(this.deps.db, source, { ...progress, handledUntil: decision.handledUntil, handedOver: true });
+    }
+    /** Registers a claimed run as active and starts working on it. */
+    begin(run, task, project, source, agent, controller, review) {
+        const entry = {
+            controller,
+            agentId: agent.id,
+            projectId: project.id,
+            taskId: task.id,
+            abortable: true,
+            done: Promise.resolve(),
+            usageStart: null,
+            usageEnd: null,
+            shared: false,
+        };
+        // Usage is reported for the whole account, so overlapping runs on one agent cannot be told apart.
+        for (const other of this.active.values()) {
+            if (other.agentId === agent.id) {
+                other.shared = true;
+                entry.shared = true;
+            }
+        }
+        this.active.set(run.id, entry);
+        this.claiming.delete(controller);
+        this.emit('run', run);
+        this.emitStatus();
+        entry.done = this.work(run, task, project, source, agent, entry, review).finally(() => {
+            this.active.delete(run.id);
+            this.releaseIfIdle(entry.projectId);
+            this.emitStatus();
+            // A slot is free again.
+            this.requestFill();
+        });
+    }
+    /* ---------- one run ---------- */
+    /** Runs one claimed task through the rest of the pipeline. Never throws. */
+    async work(run, task, project, source, agent, entry, review) {
+        try {
+            this.log(run.id, 'foreman', review?.agentReview
+                ? `Reviewing ${task.identifier}; it stays in "${source.describe().done}".`
+                : `Claimed ${task.identifier}: moved to "${source.describe().claimed}".`);
+            const doing = review?.agentReview
+                ? `reviewing the pull request${review.agentReview.self ? ' (self-review)' : ''}`
+                : review
+                    ? followUp(review.item)
+                    : null;
+            await this.commentQuietly(run, source, task, review
+                ? `${PICKED_UP} ${agent.adapter.name} is ${doing}, round ${review.round} of ${project.reviewMaxRounds}.`
+                : `${PICKED_UP} ${agent.adapter.name} is working on it.`);
+            const outcome = await this.execute(run.id, task, project, agent, entry, review);
+            entry.abortable = false;
+            // A run that did not succeed keeps the step it stopped at, so the UI can show where it failed.
+            if (outcome.kind === 'succeeded' || outcome.kind === 'reviewed' || outcome.kind === 'agent_reviewed')
+                this.update(run.id, { step: 'report' });
+            await this.report(run.id, task, project, source, outcome, review);
+        }
+        catch (error) {
+            const reason = `Unexpected error: ${errorMessage(error)}`;
+            try {
+                const failed = this.deps.db.finishRun(run.id, 'failed', reason);
+                this.emit('run', failed);
+                await this.commentQuietly(failed, source, task, this.failureComment(failed, `Foreman: run failed.\n\n${reason}.`, source));
+            }
+            catch (inner) {
+                this.stateOf(project.id).lastError = `${reason}; additionally: ${errorMessage(inner)}`;
+            }
+        }
+    }
+    async execute(runId, task, project, agent, entry, review) {
+        const { git } = this.deps;
+        const { signal } = entry.controller;
+        const branch = task.branchName;
+        // An abort can arrive while the task is still being claimed.
+        if (signal.aborted)
+            return { kind: 'aborted' };
+        this.update(runId, { step: 'worktree', branch });
+        let worktreePath;
+        let baseRef;
+        try {
+            [baseRef, worktreePath] = await this.withRepoLock(project.repoPath, async () => {
+                await git.fetch(project.repoPath, signal);
+                if (review) {
+                    // The branch already exists on origin: work continues where the pull request stands.
+                    const existing = await git.checkoutWorktree({ repoPath: project.repoPath, worktreeRoot: project.worktreeRoot, identifier: task.identifier, branch, signal });
+                    return [`origin/${branch}`, existing];
+                }
+                const base = await git.defaultBaseRef(project.repoPath, signal);
+                const created = await git.createWorktree({
+                    repoPath: project.repoPath,
+                    worktreeRoot: project.worktreeRoot,
+                    identifier: task.identifier,
+                    branch,
+                    baseRef: base,
+                    signal,
+                });
+                return [base, created];
+            });
+        }
+        catch (error) {
+            if (signal.aborted)
+                return { kind: 'aborted' };
+            return { kind: 'failed', reason: `Worktree setup failed: ${errorMessage(error)}` };
+        }
+        this.update(runId, { worktreePath });
+        this.log(runId, 'foreman', `Created worktree ${worktreePath} on branch ${branch} from ${baseRef}.`);
+        if (signal.aborted)
+            return { kind: 'aborted' };
+        this.update(runId, { step: 'agent' });
+        this.log(runId, 'foreman', `Starting ${agent.adapter.name}.`);
+        const tracker = getSourceType(project.sourceType)?.name ?? project.sourceType;
+        // The git source keeps its tasks in the repository the agent works in; the prompt tells the agent to leave them alone.
+        const taskDirectory = project.sourceType === 'git' ? project.sourceSettings.directory : undefined;
+        const ciFailures = review?.item.ciFailures ? await this.ciFailureLogs(runId, project, review.item.ciFailures, signal) : undefined;
+        const result = await this.deps.runAgent({
+            adapter: agent.adapter,
+            bin: agent.bin,
+            cwd: worktreePath,
+            prompt: review?.agentReview
+                ? buildAgentReviewPrompt({ issue: task, tracker, prUrl: review.item.pr.url, worktreePath, branch, self: review.agentReview.self, taskDirectory })
+                : review
+                    ? buildReviewPrompt({
+                        issue: task,
+                        worktreePath,
+                        repoPath: project.repoPath,
+                        branch,
+                        prUrl: review.item.pr.url,
+                        feedback: review.item.feedback,
+                        conflictWith: review.item.conflict ? review.item.pr.baseBranch : undefined,
+                        round: review.round,
+                        maxRounds: project.reviewMaxRounds,
+                        tracker,
+                        ciFailures,
+                        taskDirectory,
+                    })
+                    : buildPrompt({ issue: task, worktreePath, repoPath: project.repoPath, branch, baseRef, tracker, taskDirectory }),
+            settings: agent.settings,
+            timeoutMs: project.agentTimeoutMinutes * 60_000,
+            signal,
+            onEvent: (event) => this.log(runId, event.kind, event.text),
+            onSpawn: (pid) => this.update(runId, { agentPid: pid }),
+            onUsage: (usage) => {
+                entry.usageStart ??= usage;
+                entry.usageEnd = usage;
+                this.recordUsage(agent.id, usage);
+            },
+        });
+        this.update(runId, {
+            costUsd: result.costUsd,
+            numTurns: result.numTurns,
+            // The first report arrives after the run's first request, so this slightly undercounts.
+            ...(entry.usageStart && entry.usageEnd ? { usageDelta: usageDelta(entry.usageStart, entry.usageEnd, entry.shared) } : {}),
+        });
+        if (result.outcome === 'aborted')
+            return { kind: 'aborted' };
+        if (result.outcome === 'timeout') {
+            return { kind: 'failed', reason: `Agent timed out after ${project.agentTimeoutMinutes} minutes` };
+        }
+        if (result.outcome === 'error') {
+            const detail = result.errorMessage ?? result.resultText ?? 'no output';
+            return {
+                kind: 'failed',
+                reason: `Agent failed (exit ${result.exitCode ?? 'none'}): ${truncate(detail, REASON_LIMIT)}`,
+            };
+        }
+        this.update(runId, { step: 'pull_request' });
+        if (review) {
+            const verdict = review.agentReview ? null : parseVerdict(result.resultText);
+            const agentVerdict = review.agentReview ? parseReviewVerdict(result.resultText) : null;
+            if (review.agentReview && !agentVerdict)
+                return { kind: 'failed', reason: 'Agent review finished without a verdict' };
+            if (!review.agentReview && !verdict)
+                return { kind: 'failed', reason: 'Agent finished without a verdict on the review feedback' };
+            this.update(runId, { prUrl: review.item.pr.url });
+            // Everything on the pull request now, including the agent's own replies, counts as dealt with.
+            // Otherwise a small clock difference with GitHub could make the agent answer itself.
+            let handledUntil = latestOf(review.item.feedback, this.now());
+            let headSha = review.item.pr.headSha;
+            try {
+                const current = await git.pullRequest(project.repoPath, branch, signal);
+                if (current) {
+                    handledUntil = latestOf(current.feedback, this.now());
+                    headSha = current.headSha;
+                }
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return { kind: 'aborted' };
+                this.log(runId, 'foreman', `Could not re-read the pull request: ${errorMessage(error)}`);
+            }
+            if (agentVerdict) {
+                this.log(runId, 'foreman', `Review verdict: ${agentVerdict.verdict}.`);
+                return { kind: 'agent_reviewed', verdict: agentVerdict.verdict, findings: agentVerdict.findings, prUrl: review.item.pr.url, handledUntil };
+            }
+            this.log(runId, 'foreman', `Verdict on the feedback: ${verdict.replace(/_/g, ' ')}.`);
+            const ciVerdict = review.item.ciFailures ? parseCiVerdict(result.resultText) : null;
+            if (review.item.ciFailures)
+                this.log(runId, 'foreman', `Verdict on the failing checks: ${ciVerdict ? ciVerdict.verdict.replace(/_/g, ' ') : 'none given'}.`);
+            return { kind: 'reviewed', verdict: verdict, prUrl: review.item.pr.url, handledUntil, headSha, resultText: result.resultText, ciVerdict };
+        }
+        let prUrl;
+        try {
+            prUrl = await git.findOpenPr(worktreePath, branch, signal);
+        }
+        catch (error) {
+            if (signal.aborted)
+                return { kind: 'aborted' };
+            return { kind: 'failed', reason: `Pull request lookup failed: ${errorMessage(error)}` };
+        }
+        if (!prUrl) {
+            const needs = parseBlocked(result.resultText);
+            if (needs)
+                return { kind: 'blocked', needs, baseRef };
+            return { kind: 'failed', reason: 'Agent finished without opening a pull request' };
+        }
+        this.update(runId, { prUrl });
+        this.log(runId, 'foreman', `Found pull request ${prUrl}.`);
+        return { kind: 'succeeded', prUrl, resultText: result.resultText };
+    }
+    async report(runId, task, project, source, outcome, review) {
+        const { db, git } = this.deps;
+        if (review?.agentReview) {
+            await this.reportAgentReview(runId, task, project, source, outcome, review);
+            return;
+        }
+        if (outcome.kind === 'reviewed' && review) {
+            const names = source.describe();
+            const { item } = review;
+            // A conflict fixed on a pull request that was already awaiting approval, with no new feedback
+            // to weigh, leaves it awaiting approval.
+            const conflictOnly = item.conflict && item.feedback.length === 0 && !item.ciFailures;
+            const ciOnly = !!item.ciFailures && item.feedback.length === 0 && !item.conflict;
+            const wantsApproval = outcome.verdict === 'approved' || (conflictOnly && item.stage === 'approval');
+            // An approval moves the issue only on green checks; otherwise it waits on this head.
+            const held = wantsApproval && !(await this.ciGreen(runId, project, item.pr));
+            const approved = wantsApproval && !held;
+            const target = approved ? names.approval : names.done;
+            const before = await progressOf(db, source, task);
+            const ciFollow = item.ciFailures
+                ? decideCiFollowUp({
+                    verdict: outcome.ciVerdict ?? null,
+                    ci: { state: 'failing', checks: item.ciFailures },
+                    progress: before,
+                    headBefore: item.pr.headSha,
+                    headAfter: outcome.headSha,
+                })
+                : null;
+            const sameCiHead = before.ciHead === item.pr.headSha;
+            // Recorded first: whatever happens next, this feedback must not be handed out again.
+            await saveProgress(db, source, {
+                ...before,
+                issueId: task.id,
+                handledUntil: outcome.handledUntil,
+                rounds: review.round,
+                handedOver: false,
+                // What GitHub showed as the head when a conflict round ended; see CONFLICT_SETTLE_MS.
+                conflictHead: review.item.conflict ? outcome.headSha : null,
+                conflictAt: review.item.conflict ? this.now().toISOString() : null,
+                // An agent reviewer's findings were part of this round, so they are dealt with; its reviewed head stands.
+                agentFindings: null,
+                approvalHead: held ? outcome.headSha : approved ? null : (before.approvalHead ?? null),
+                // The head's failing checks were this round's; a rerun the agent asked for leaves them open until it reports.
+                ...(ciFollow
+                    ? {
+                        ciHead: item.pr.headSha,
+                        ciHandled: ciFollow.kind !== 'rerun',
+                        ciReruns: (sameCiHead ? (before.ciReruns ?? 0) : 0) + (ciFollow.kind === 'rerun' ? 1 : 0),
+                        ciNotCode: ciFollow.kind === 'rerun' ? ciFollow.reason : sameCiHead ? (before.ciNotCode ?? null) : null,
+                    }
+                    : {}),
+            });
+            try {
+                if (approved)
+                    await source.approve(task);
+                else
+                    await source.complete(task);
+            }
+            catch (error) {
+                const reason = `Review feedback handled (${outcome.prUrl}) but the tracker update failed: ${errorMessage(error)}`;
+                this.log(runId, 'foreman', reason);
+                const failed = db.finishRun(runId, 'failed', reason);
+                this.emit('run', failed);
+                await this.commentQuietly(failed, source, task, this.failureComment(failed, `Foreman: run failed.\n\n${reason}.`, source));
+                return;
+            }
+            this.log(runId, 'foreman', `Moved ${task.identifier} to "${target}".`);
+            // Back in review: the people (or bots) whose feedback this round answered are asked to look again.
+            const rereview = approved ? '' : await this.requestRereview(runId, project, review);
+            const resolved = item.conflict && outcome.verdict === 'changes_made' ? `merge conflicts with "${item.pr.baseBranch}" resolved` : null;
+            const where = approved ? `Awaiting approval: ${outcome.prUrl}` : `Back in review: ${outcome.prUrl}`;
+            const headline = held
+                ? `Foreman: the review recommends approval; waiting for its checks to pass before moving it to "${names.approval}": ${outcome.prUrl}`
+                : ciOnly
+                    ? outcome.verdict === 'changes_made'
+                        ? `Foreman: fixed the failing checks (round ${review.round}). ${where}`
+                        : `Foreman: looked at the failing checks (round ${review.round}); the agent changed nothing. ${where}`
+                    : conflictOnly
+                        ? resolved
+                            ? `Foreman: ${resolved} (round ${review.round}). ${where}`
+                            : `Foreman: checked the pull request for merge conflicts (round ${review.round}); the agent changed nothing. ${where}`
+                        : outcome.verdict === 'approved'
+                            ? `Foreman: the review recommends approval${resolved ? `, and ${resolved}` : ''}. A person now approves and merges: ${outcome.prUrl}`
+                            : outcome.verdict === 'changes_made'
+                                ? `Foreman: review feedback addressed${resolved ? ` and ${resolved}` : ''} (round ${review.round}). ${where}`
+                                : `Foreman: looked at the new feedback (round ${review.round}); no changes were needed. ${where}`;
+            const summary = outcome.resultText
+                ? `\n\n${truncate(outcome.resultText.replace(/^[ \t]*FOREMAN_(VERDICT|CI):.*$/gim, '').trim(), RESULT_COMMENT_LIMIT)}`
+                : '';
+            const reviewed = db.getRun(runId);
+            if (reviewed)
+                await this.commentQuietly(reviewed, source, task, `${headline}${rereview}${summary}`);
+            if (ciFollow && ciFollow.kind !== 'none')
+                await this.followUpCi(runId, project, source, task, item, outcome.headSha, ciFollow);
+            if (reviewed?.worktreePath) {
+                const worktreePath = reviewed.worktreePath;
+                try {
+                    await this.withRepoLock(project.repoPath, () => git.removeWorktree(project.repoPath, worktreePath));
+                    this.log(runId, 'foreman', `Removed worktree ${worktreePath}.`);
+                }
+                catch (error) {
+                    this.log(runId, 'foreman', `Kept worktree ${worktreePath}: ${errorMessage(error)}`);
+                }
+            }
+            this.emit('run', db.finishRun(runId, 'succeeded'));
+            return;
+        }
+        if (outcome.kind === 'succeeded') {
+            // Move first: if it fails, the task really is still in progress and the failure comment is accurate.
+            try {
+                await source.complete(task);
+            }
+            catch (error) {
+                const reason = `Pull request opened (${outcome.prUrl}) but the tracker update failed: ${errorMessage(error)}`;
+                this.log(runId, 'foreman', reason);
+                const failed = db.finishRun(runId, 'failed', reason);
+                this.emit('run', failed);
+                await this.commentQuietly(failed, source, task, this.failureComment(failed, `Foreman: run failed.\n\n${reason}.`, source));
+                return;
+            }
+            this.log(runId, 'foreman', `Moved ${task.identifier} to "${source.describe().done}".`);
+            const reviewNote = project.reviewMode === 'copilot' ? ` ${await this.requestCopilotReview(runId, project, task)}` : '';
+            const summary = outcome.resultText ? `\n\n${truncate(outcome.resultText, RESULT_COMMENT_LIMIT)}` : '';
+            const finished = db.getRun(runId);
+            if (finished) {
+                await this.commentQuietly(finished, source, task, `Foreman: agent finished. Pull request: ${outcome.prUrl}${reviewNote}${summary}`);
+            }
+            const run = db.getRun(runId);
+            if (run?.worktreePath) {
+                const worktreePath = run.worktreePath;
+                try {
+                    await this.withRepoLock(project.repoPath, () => git.removeWorktree(project.repoPath, worktreePath));
+                    this.log(runId, 'foreman', `Removed worktree ${worktreePath}.`);
+                }
+                catch (error) {
+                    this.log(runId, 'foreman', `Kept worktree ${worktreePath}: ${errorMessage(error)}`);
+                }
+            }
+            this.emit('run', db.finishRun(runId, 'succeeded'));
+            return;
+        }
+        if (outcome.kind === 'blocked') {
+            await this.reportBlocked(runId, task, project, source, outcome);
+            return;
+        }
+        const aborted = outcome.kind === 'aborted';
+        const reason = aborted ? 'Aborted by operator' : outcome.kind === 'failed' ? outcome.reason : 'Unexpected outcome';
+        this.log(runId, 'foreman', aborted ? 'Run aborted by operator.' : `Run failed: ${reason}`);
+        const run = db.finishRun(runId, aborted ? 'aborted' : 'failed', reason);
+        this.emit('run', run);
+        const headline = aborted ? 'Foreman: run aborted by operator.' : `Foreman: run failed.\n\n${reason}.`;
+        await this.commentQuietly(run, source, task, this.failureComment(run, headline, source));
+    }
+    /**
+     * Records an agent review. Its head counts as reviewed whatever the outcome, so a failed review is
+     * not repeated until something new is pushed. Approval moves the issue on; requested changes wait
+     * for the next round, which hands them to the author's agent. The issue was never claimed, so it stays in review.
+     */
+    async reportAgentReview(runId, task, project, source, outcome, review) {
+        const { db, git } = this.deps;
+        const run = db.getRun(runId);
+        const reviewer = this.deps.getAgents().find((agent) => agent.id === run?.agent)?.adapter.name ?? run?.agent ?? 'The reviewer';
+        const progress = await progressOf(db, source, task);
+        const reviewed = outcome.kind === 'agent_reviewed';
+        await saveProgress(db, source, {
+            ...progress,
+            rounds: review.round,
+            agentReviewedHead: review.item.pr.headSha,
+            ...(reviewed ? { handledUntil: outcome.handledUntil, agentFindings: outcome.verdict === 'changes' ? outcome.findings || '(The reviewer gave no details.)' : null } : {}),
+        });
+        let body;
+        let status = 'succeeded';
+        let reason;
+        if (outcome.kind === 'agent_reviewed' && outcome.verdict === 'approve' && !(await this.ciGreen(runId, project, review.item.pr))) {
+            await saveProgress(db, source, { ...(await progressOf(db, source, task)), approvalHead: review.item.pr.headSha });
+            body = `Foreman: ${reviewer} reviewed the pull request (round ${review.round}) and found nothing that needs changing; waiting for its checks to pass before moving it to "${source.describe().approval}": ${outcome.prUrl}`;
+        }
+        else if (outcome.kind === 'agent_reviewed' && outcome.verdict === 'approve') {
+            try {
+                await source.approve(task);
+            }
+            catch (error) {
+                reason = `Review approved (${outcome.prUrl}) but the tracker update failed: ${errorMessage(error)}`;
+                this.log(runId, 'foreman', reason);
+                status = 'failed';
+            }
+            body = reason
+                ? `Foreman: ${reviewer} found nothing that needs changing, but the issue could not be moved: ${reason}.`
+                : `Foreman: ${reviewer} reviewed the pull request (round ${review.round}) and found nothing that needs changing. Moved to "${source.describe().approval}"; a person now approves and merges it: ${outcome.prUrl}`;
+        }
+        else if (outcome.kind === 'agent_reviewed') {
+            body = `Foreman: ${reviewer} reviewed the pull request (round ${review.round}) and asked for changes; the author's agent takes them next.\n\n${truncate(outcome.findings, RESULT_COMMENT_LIMIT)}`;
+        }
+        else {
+            status = outcome.kind === 'aborted' ? 'aborted' : 'failed';
+            reason = outcome.kind === 'aborted' ? 'Aborted by operator' : outcome.kind === 'failed' ? outcome.reason : 'Unexpected outcome';
+            this.log(runId, 'foreman', `Agent review ${status}: ${reason}`);
+            body = `Foreman: the agent review ${status === 'aborted' ? 'was aborted' : 'failed'}.\n\n${reason}.\n\nThe issue stays in "${source.describe().done}"; the next push to the pull request is reviewed again.`;
+        }
+        const current = db.getRun(runId);
+        if (current)
+            await this.commentQuietly(current, source, task, body);
+        if (current?.worktreePath) {
+            const worktreePath = current.worktreePath;
+            try {
+                await this.withRepoLock(project.repoPath, () => git.removeWorktree(project.repoPath, worktreePath));
+                this.log(runId, 'foreman', `Removed worktree ${worktreePath}.`);
+            }
+            catch (error) {
+                this.log(runId, 'foreman', `Kept worktree ${worktreePath}: ${errorMessage(error)}`);
+            }
+        }
+        this.emit('run', db.finishRun(runId, status, reason));
+    }
+    /** The failing checks of a CI round with an excerpt of each Actions log, fetched once per run. */
+    async ciFailureLogs(runId, project, checks, signal) {
+        const logs = new Map();
+        for (const check of checks) {
+            if (check.runId === null || logs.has(check.runId))
+                continue;
+            const log = await this.deps.git.failedLog(project.repoPath, check.runId, signal);
+            if (!log)
+                this.log(runId, 'foreman', `No log available for the failed run ${check.runId}.`);
+            logs.set(check.runId, log);
+        }
+        return checks.map((check) => ({ name: check.name, link: check.link, log: check.runId === null ? null : (logs.get(check.runId) ?? null) }));
+    }
+    /** Whether an approval may move the issue: always without the CI gate, else only on passing checks or none. A check that cannot be read holds it. */
+    async ciGreen(runId, project, pr) {
+        if (!project.waitForCi)
+            return true;
+        try {
+            const ci = await this.deps.git.ciStatus(project.repoPath, pr.number);
+            return ci.state === 'passing' || ci.state === 'none';
+        }
+        catch (error) {
+            this.log(runId, 'foreman', `Could not read the checks; holding the approval: ${errorMessage(error)}`);
+            return false;
+        }
+    }
+    /** After a CI round: reruns the checks the agent found are not the code's, or hands the issue to a person. */
+    async followUpCi(runId, project, source, task, item, head, follow) {
+        const { db, git } = this.deps;
+        const pr = { ...item.pr, headSha: head };
+        if (follow.kind === 'hand_over') {
+            this.log(runId, 'foreman', `Handing over: ${follow.needs}`);
+            await handOverCi(db, source, task, 'review', pr, follow.needs);
+            return;
+        }
+        const checks = (item.ciFailures ?? []).map((check) => check.name).join(', ');
+        try {
+            for (const id of follow.runIds)
+                await git.rerunFailed(project.repoPath, id);
+        }
+        catch (error) {
+            this.log(runId, 'foreman', `Could not rerun the checks: ${errorMessage(error)}`);
+            await handOverCi(db, source, task, 'review', pr, `checks that could not be rerun (${checks}): ${errorMessage(error)}`);
+            return;
+        }
+        const reruns = (await progressOf(db, source, task)).ciReruns ?? 1;
+        this.log(runId, 'foreman', `Reran ${checks}: ${follow.reason}`);
+        await source
+            .comment(task, `Foreman: reran ${checks} (rerun ${reruns} of ${CI_MAX_RERUNS}) because the agent found the failure is not caused by the code: ${follow.reason}`)
+            .catch(() => { });
+    }
+    /** Asks GitHub Copilot to review a newly opened pull request. Returns a sentence for the tracker comment; never throws. */
+    async requestCopilotReview(runId, project, task) {
+        let note;
+        try {
+            const pr = await this.deps.git.pullRequest(project.repoPath, task.branchName);
+            if (!pr) {
+                note = 'Could not request a Copilot review: no pull request found for the branch.';
+            }
+            else {
+                const { failed } = await this.deps.git.requestReview(project.repoPath, pr.number, [COPILOT_REVIEWER]);
+                note = failed.length > 0 ? `Could not request a Copilot review: ${failed[0].reason}.` : 'Copilot review requested.';
+            }
+        }
+        catch (error) {
+            note = `Could not request a Copilot review: ${errorMessage(error)}.`;
+        }
+        this.log(runId, 'foreman', note);
+        return note;
+    }
+    /**
+     * The agent stopped to ask for something. Its question goes on the issue, which stays claimed, and the
+     * worktree and branch are cleared so that a retry starts clean, unless the agent left work in them.
+     */
+    async reportBlocked(runId, task, project, source, outcome) {
+        const { db, git } = this.deps;
+        this.log(runId, 'foreman', `Agent is blocked: ${outcome.needs}`);
+        const run = db.getRun(runId);
+        const kept = [];
+        if (run?.worktreePath && run.branch) {
+            const { worktreePath, branch } = run;
+            try {
+                await this.withRepoLock(project.repoPath, () => git.removeWorktree(project.repoPath, worktreePath));
+                this.log(runId, 'foreman', `Removed worktree ${worktreePath}.`);
+                try {
+                    await this.withRepoLock(project.repoPath, () => git.deleteBranchAt(project.repoPath, branch, outcome.baseRef));
+                    this.log(runId, 'foreman', `Deleted branch ${branch}.`);
+                }
+                catch (error) {
+                    this.log(runId, 'foreman', `Kept branch ${branch}: ${errorMessage(error)}`);
+                    kept.push(`The branch \`${branch}\` has commits, so it was kept; delete it before retrying.`);
+                }
+            }
+            catch (error) {
+                this.log(runId, 'foreman', `Kept worktree ${worktreePath}: ${errorMessage(error)}`);
+                kept.push(`The worktree was kept at \`${worktreePath}\` because it holds files the agent did not commit. Remove it and delete the branch \`${branch}\` before retrying.`);
+            }
+        }
+        const finished = db.finishRun(runId, 'blocked', truncate(outcome.needs, REASON_LIMIT));
+        this.emit('run', finished);
+        const { claimed, waiting } = source.describe();
+        const body = [
+            'Foreman: the agent needs input before it can go on.',
+            '',
+            truncate(outcome.needs, RESULT_COMMENT_LIMIT),
+            '',
+            `The issue was left in "${claimed}". To retry, add the answer to the issue's description and move it back to "${waiting}".`,
+            ...kept,
+        ].join('\n');
+        await this.commentQuietly(finished, source, task, body);
+    }
+    /**
+     * Asks the authors of a round's feedback to review again. The pull request's own author cannot
+     * review it, so they are left out. Returns a sentence for the tracker comment, or nothing.
+     */
+    async requestRereview(runId, project, review) {
+        const { pr, feedback } = review.item;
+        const reviewers = [...new Set(feedback.map((item) => item.author))].filter((author) => author !== 'unknown' && author !== AGENT_REVIEWER && author.toLowerCase() !== pr.author.toLowerCase());
+        if (reviewers.length === 0)
+            return '';
+        try {
+            const { requested, failed } = await this.deps.git.requestReview(project.repoPath, pr.number, reviewers);
+            for (const { login, reason } of failed)
+                this.log(runId, 'foreman', `Could not request a re-review from ${login}: ${reason}`);
+            if (requested.length === 0)
+                return '';
+            this.log(runId, 'foreman', `Requested a re-review from ${requested.join(', ')}.`);
+            return ` Re-review requested from ${requested.join(', ')}.`;
+        }
+        catch (error) {
+            this.log(runId, 'foreman', `Could not request a re-review: ${errorMessage(error)}`);
+            return '';
+        }
+    }
+    recordUsage(agentId, usage) {
+        this.usage.set(agentId, usage);
+        this.deps.db.setSetting(USAGE_SETTING, Object.fromEntries(this.usage));
+        this.emit('usage', { agentId, usage });
+    }
+    /** Runs `task` after every earlier task for the same repository has finished. */
+    withRepoLock(repoPath, task) {
+        const previous = this.repoLocks.get(repoPath) ?? Promise.resolve();
+        const next = previous.then(task, task);
+        const tail = next.catch(() => { });
+        this.repoLocks.set(repoPath, tail);
+        void tail.then(() => {
+            if (this.repoLocks.get(repoPath) === tail)
+                this.repoLocks.delete(repoPath);
+        });
+        return next;
+    }
+    failureComment(run, headline, source) {
+        const { claimed, waiting } = source.describe();
+        const lines = [headline, '', `The issue was left in "${claimed}"; move it back to "${waiting}" to retry.`];
+        if (run.worktreePath) {
+            lines.push(`The worktree was kept at \`${run.worktreePath}\`. Remove it and delete the branch \`${run.branch}\` before retrying.`);
+        }
+        return lines.join('\n');
+    }
+    async commentQuietly(run, source, task, body) {
+        try {
+            await source.comment(task, body);
+        }
+        catch (error) {
+            this.log(run.id, 'foreman', `Could not comment on ${run.identifier}: ${errorMessage(error)}`);
+        }
+    }
+    update(runId, patch) {
+        this.emit('run', this.deps.db.updateRun(runId, patch));
+    }
+    log(runId, kind, text) {
+        this.emit('log', this.deps.db.addEvent(runId, kind, text));
+    }
+    emitStatus() {
+        this.emit('status', this.getStatus());
+    }
+}