@dfsramos/foreman 0.0.0-stage → 0.3.0

package/dist/linear/client.js

@@ -0,0 +1,48 @@
+const ENDPOINT = 'https://api.linear.app/graphql';
+const REQUEST_TIMEOUT_MS = 30_000;
+export class LinearError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'LinearError';
+        this.status = status;
+    }
+}
+export function createLinearClient(apiKey, fetchImpl = fetch) {
+    return {
+        async request(query, variables) {
+            let response;
+            try {
+                response = await fetchImpl(ENDPOINT, {
+                    method: 'POST',
+                    // Personal API keys are sent bare; only OAuth tokens take a "Bearer" prefix.
+                    headers: { 'Content-Type': 'application/json', Authorization: apiKey },
+                    body: JSON.stringify({ query, variables }),
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                throw new LinearError(`Linear API unreachable: ${reason}`);
+            }
+            let body;
+            try {
+                body = (await response.json());
+            }
+            catch {
+                body = undefined;
+            }
+            const messages = body?.errors?.map((e) => e.message).join('; ');
+            if (!response.ok) {
+                throw new LinearError(`Linear API returned HTTP ${response.status}${messages ? `: ${messages}` : ''}`, response.status);
+            }
+            if (messages) {
+                throw new LinearError(`Linear API error: ${messages}`, response.status);
+            }
+            if (!body || body.data === undefined || body.data === null) {
+                throw new LinearError('Linear API returned an empty response', response.status);
+            }
+            return body.data;
+        },
+    };
+}

package/dist/linear/issues.js

@@ -0,0 +1,99 @@
+import { LinearError } from './client.js';
+const STATES_QUERY = `
+query TeamStates($teamId: String!) {
+  team(id: $teamId) { states { nodes { id name } } }
+}`;
+// The label condition is only part of the query when a label is asked for.
+const candidatesQuery = (withLabel) => `
+query Candidates($teamId: ID!, $projectId: ID!, $stateId: ID!, $after: String${withLabel ? ', $label: String!' : ''}) {
+  issues(
+    first: 100
+    after: $after
+    filter: {
+      team: { id: { eq: $teamId } }
+      project: { id: { eq: $projectId } }
+      state: { id: { eq: $stateId } }${withLabel ? '\n      labels: { some: { name: { eqIgnoreCase: $label } } }' : ''}
+    }
+  ) {
+    nodes { id identifier title description url priority createdAt branchName }
+    pageInfo { hasNextPage endCursor }
+  }
+}`;
+// Bounds a poll against a runaway cursor; 2000 issues waiting in one state is already far outside normal use.
+const MAX_CANDIDATE_PAGES = 20;
+const MOVE_MUTATION = `
+mutation MoveIssue($id: String!, $stateId: String!) {
+  issueUpdate(id: $id, input: { stateId: $stateId }) { success }
+}`;
+const COMMENT_MUTATION = `
+mutation AddComment($issueId: String!, $body: String!) {
+  commentCreate(input: { issueId: $issueId, body: $body }) { success }
+}`;
+// "No priority" (0) sorts after "low" (4).
+const priorityRank = (priority) => (priority === 0 ? 5 : priority);
+export function createIssueApi(client) {
+    return {
+        async resolveStates(teamId, names) {
+            const ids = await this.findStateIds(teamId, [names.target, names.inProgress, names.success]);
+            return { targetId: ids[names.target], inProgressId: ids[names.inProgress], successId: ids[names.success] };
+        },
+        async findStateIds(teamId, names) {
+            const data = await client.request(STATES_QUERY, { teamId });
+            const states = data.team.states.nodes;
+            const ids = {};
+            const missing = [];
+            for (const name of names) {
+                const id = states.find((s) => s.name.toLowerCase() === name.trim().toLowerCase())?.id;
+                if (id)
+                    ids[name] = id;
+                else
+                    missing.push(name);
+            }
+            if (missing.length > 0) {
+                const available = states.map((s) => s.name).join(', ');
+                const quoted = [...new Set(missing)].map((name) => `"${name}"`).join(', ');
+                throw new LinearError(`Workflow state not found: ${quoted}. Available states: ${available}`);
+            }
+            return ids;
+        },
+        async fetchCandidates(teamId, projectId, stateId, label) {
+            const wanted = label?.trim() ?? '';
+            const query = candidatesQuery(wanted !== '');
+            // Every page is needed: the pick order is decided here, not by the API.
+            const nodes = [];
+            let after = null;
+            for (let page = 0; page < MAX_CANDIDATE_PAGES; page += 1) {
+                const data = await client.request(query, {
+                    teamId,
+                    projectId,
+                    stateId,
+                    ...(wanted !== '' ? { label: wanted } : {}),
+                    after,
+                });
+                nodes.push(...data.issues.nodes);
+                if (!data.issues.pageInfo?.hasNextPage || !data.issues.pageInfo.endCursor)
+                    break;
+                after = data.issues.pageInfo.endCursor;
+            }
+            return nodes.sort((a, b) => priorityRank(a.priority) - priorityRank(b.priority) || a.createdAt.localeCompare(b.createdAt));
+        },
+        async moveIssue(issueId, stateId) {
+            const data = await client.request(MOVE_MUTATION, {
+                id: issueId,
+                stateId,
+            });
+            if (!data.issueUpdate.success) {
+                throw new LinearError(`Linear did not update issue ${issueId}`);
+            }
+        },
+        async addComment(issueId, body) {
+            const data = await client.request(COMMENT_MUTATION, {
+                issueId,
+                body,
+            });
+            if (!data.commentCreate.success) {
+                throw new LinearError(`Linear did not create a comment on issue ${issueId}`);
+            }
+        },
+    };
+}

package/dist/linear/workspace.js

@@ -0,0 +1,30 @@
+// Linear limits query complexity, and nesting two lists under teams exceeds it, so the projects
+// are fetched per team.
+const TEAMS_QUERY = `
+query Teams {
+  teams(first: 50) {
+    nodes { id key name states(first: 50) { nodes { name position } } }
+  }
+}`;
+const PROJECTS_QUERY = `
+query TeamProjects($teamId: String!) {
+  team(id: $teamId) { projects(first: 100) { nodes { id name } } labels(first: 100) { nodes { name } } }
+  issueLabels(first: 100, filter: { team: { null: true } }) { nodes { name } }
+}`;
+/** The teams an API key can see, each with its workflow states and projects. Read-only. */
+export async function fetchWorkspace(client) {
+    const data = await client.request(TEAMS_QUERY, {});
+    const teams = [];
+    for (const team of data.teams.nodes) {
+        const projects = await client.request(PROJECTS_QUERY, { teamId: team.id });
+        teams.push({
+            id: team.id,
+            key: team.key,
+            name: team.name,
+            states: [...team.states.nodes].sort((a, b) => a.position - b.position).map((state) => state.name),
+            labels: [...new Set([...projects.team.labels.nodes, ...projects.issueLabels.nodes].map((label) => label.name))].sort((a, b) => a.localeCompare(b)),
+            projects: [...projects.team.projects.nodes].sort((a, b) => a.name.localeCompare(b.name)),
+        });
+    }
+    return teams.sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/paths.js

@@ -0,0 +1,12 @@
+import path from 'node:path';
+export const PID_FILE = 'foreman.pid';
+export const LOG_FILE = 'foreman.log';
+export const ENV_FILE = '.env';
+/** Where foreman keeps its data when DATA_DIR is not set: the platform's standard place for per-user application data. */
+export function defaultDataDir(platform, env, home) {
+    if (platform === 'darwin')
+        return path.join(home, 'Library', 'Application Support', 'foreman');
+    // The XDG spec says a relative XDG_DATA_HOME is invalid and must be ignored.
+    const xdg = env.XDG_DATA_HOME?.trim();
+    return path.join(xdg && path.isAbsolute(xdg) ? xdg : path.join(home, '.local', 'share'), 'foreman');
+}

package/dist/pidfile.js

@@ -0,0 +1,35 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { PID_FILE } from './paths.js';
+export function writePidFile(dataDir, pid) {
+    fs.writeFileSync(path.join(dataDir, PID_FILE), String(pid));
+}
+export function removePidFile(dataDir) {
+    fs.rmSync(path.join(dataDir, PID_FILE), { force: true });
+}
+/** True while a process with this pid exists; one owned by another user (EPERM) exists too. */
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/** The pid of the running foreman, or null when there is no pid file or its process has exited. */
+export function readLivePid(dataDir) {
+    let content;
+    try {
+        content = fs.readFileSync(path.join(dataDir, PID_FILE), 'utf8').trim();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const pid = Number(content);
+    if (!/^\d+$/.test(content) || pid <= 0)
+        return null;
+    return isAlive(pid) ? pid : null;
+}

package/dist/projects.js

@@ -0,0 +1,211 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { AGENT_TIMEOUT_RANGE, POLL_INTERVAL_RANGE } from './config.js';
+import { SOURCE_TYPES } from './sources/registry.js';
+export const PRIORITIES = ['low', 'normal', 'high'];
+/** How many turns a project gets, relative to the others, when agent slots are contended. */
+export const PRIORITY_WEIGHTS = { low: 1, normal: 2, high: 3 };
+/**
+ * Who is asked to review a pull request once it opens: nobody (a person does it), GitHub Copilot,
+ * an agent other than the author's, or any agent, preferring another than the author's.
+ */
+export const REVIEW_MODES = ['none', 'copilot', 'other_agent', 'any_agent'];
+export const DEFAULT_REVIEW_ROUNDS = 5;
+/** Bots that comment on pull requests without reviewing them. Review bots are deliberately not listed. */
+export const DEFAULT_IGNORED_AUTHORS = ['vercel', 'linear', 'linear-code', 'github-actions', 'netlify', 'dependabot'];
+const REVIEW_ROUNDS_RANGE = { min: 0, max: 20 };
+const slug = (name) => name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'project';
+const wholeNumber = (value, range) => {
+    const n = typeof value === 'string' && /^\d+$/.test(value.trim()) ? Number(value) : value;
+    return typeof n === 'number' && Number.isInteger(n) && n >= range.min && n <= range.max ? n : null;
+};
+/** Turns console input into a storable project, or says what is wrong with it field by field. */
+export function validateProject(input, options) {
+    const { existing, others, dataDir, agentIds, sourceTypes = SOURCE_TYPES, sourceOnly = false } = options;
+    const errors = {};
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return { errors: { _: 'Request body must be a JSON object' } };
+    }
+    const body = input;
+    const sourceType = sourceTypes.find((type) => type.id === body.sourceType);
+    if (!sourceType)
+        errors.sourceType = 'is not a known source';
+    const rawSettings = typeof body.sourceSettings === 'object' && body.sourceSettings !== null ? body.sourceSettings : {};
+    const sourceSettings = {};
+    for (const field of sourceType?.fields ?? []) {
+        const raw = rawSettings[field.key];
+        let value = typeof raw === 'string' ? raw.trim() : '';
+        // A secret left empty while editing means "keep what is stored".
+        if (value === '' && field.type === 'secret' && existing?.sourceType === sourceType?.id) {
+            value = existing?.sourceSettings[field.key] ?? '';
+        }
+        // An optional field left empty on purpose stays empty; only a missing or required one takes its default.
+        if (value === '' && field.default !== undefined && (raw === undefined || field.required))
+            value = field.default;
+        if (raw !== undefined && typeof raw !== 'string')
+            errors[`sourceSettings.${field.key}`] = 'must be text';
+        else if (value === '' && field.required)
+            errors[`sourceSettings.${field.key}`] = 'is required';
+        sourceSettings[field.key] = value;
+    }
+    for (const key of Object.keys(rawSettings)) {
+        if (sourceType && !sourceType.fields.some((field) => field.key === key)) {
+            errors[`sourceSettings.${key}`] = 'is not a setting of this source';
+        }
+    }
+    const name = typeof body.name === 'string' ? body.name.trim() : '';
+    const repoPath = typeof body.repoPath === 'string' ? body.repoPath.trim() : '';
+    if (!sourceOnly) {
+        if (name === '')
+            errors.name = 'is required';
+        else if (name.length > 80)
+            errors.name = 'must be at most 80 characters';
+        else if (others.some((other) => other.name.toLowerCase() === name.toLowerCase()))
+            errors.name = 'is already used by another project';
+        if (repoPath === '')
+            errors.repoPath = 'is required';
+        else if (!path.isAbsolute(repoPath))
+            errors.repoPath = 'must be an absolute path';
+        else if (!fs.existsSync(repoPath))
+            errors.repoPath = 'does not exist';
+        else if (!fs.existsSync(path.join(repoPath, '.git')))
+            errors.repoPath = 'is not a git repository';
+        else {
+            const taken = others.find((other) => path.resolve(other.repoPath) === path.resolve(repoPath));
+            if (taken)
+                errors.repoPath = `is already used by the project "${taken.name}"`;
+        }
+    }
+    let worktreeRoot = typeof body.worktreeRoot === 'string' ? body.worktreeRoot.trim() : '';
+    if (worktreeRoot === '')
+        worktreeRoot = path.join(dataDir, 'worktrees', slug(name));
+    else if (!path.isAbsolute(worktreeRoot))
+        errors.worktreeRoot = 'must be an absolute path';
+    const priority = body.priority ?? 'normal';
+    if (!PRIORITIES.includes(priority))
+        errors.priority = `must be one of: ${PRIORITIES.join(', ')}`;
+    const pollIntervalSeconds = wholeNumber(body.pollIntervalSeconds ?? 60, POLL_INTERVAL_RANGE);
+    if (pollIntervalSeconds === null) {
+        errors.pollIntervalSeconds = `must be a whole number between ${POLL_INTERVAL_RANGE.min} and ${POLL_INTERVAL_RANGE.max}`;
+    }
+    const agentTimeoutMinutes = wholeNumber(body.agentTimeoutMinutes ?? 30, AGENT_TIMEOUT_RANGE);
+    if (agentTimeoutMinutes === null) {
+        errors.agentTimeoutMinutes = `must be a whole number between ${AGENT_TIMEOUT_RANGE.min} and ${AGENT_TIMEOUT_RANGE.max}`;
+    }
+    const agents = body.agents ?? [];
+    if (!Array.isArray(agents) || agents.some((id) => typeof id !== 'string'))
+        errors.agents = 'must be a list of agent ids';
+    else if (agents.some((id) => !agentIds.includes(id)))
+        errors.agents = 'contains an unknown agent';
+    else if (new Set(agents).size !== agents.length)
+        errors.agents = 'must not contain duplicates';
+    if (body.autostart !== undefined && typeof body.autostart !== 'boolean')
+        errors.autostart = 'must be true or false';
+    const reviewMaxRounds = wholeNumber(body.reviewMaxRounds ?? existing?.reviewMaxRounds ?? DEFAULT_REVIEW_ROUNDS, REVIEW_ROUNDS_RANGE);
+    if (reviewMaxRounds === null) {
+        errors.reviewMaxRounds = `must be a whole number between ${REVIEW_ROUNDS_RANGE.min} and ${REVIEW_ROUNDS_RANGE.max}`;
+    }
+    const rawIgnored = body.reviewIgnoreAuthors ?? existing?.reviewIgnoreAuthors ?? DEFAULT_IGNORED_AUTHORS;
+    const ignoredList = typeof rawIgnored === 'string' ? rawIgnored.split(',') : rawIgnored;
+    let reviewIgnoreAuthors = [];
+    if (!Array.isArray(ignoredList) || ignoredList.some((author) => typeof author !== 'string')) {
+        errors.reviewIgnoreAuthors = 'must be a list of GitHub account names';
+    }
+    else {
+        reviewIgnoreAuthors = [...new Set(ignoredList.map((author) => author.trim().replace(/^@/, '')).filter((author) => author !== ''))];
+    }
+    const reviewMode = body.reviewMode ?? existing?.reviewMode ?? 'none';
+    if (!REVIEW_MODES.includes(reviewMode))
+        errors.reviewMode = `must be one of: ${REVIEW_MODES.join(', ')}`;
+    const waitForCi = body.waitForCi ?? existing?.waitForCi ?? true;
+    if (typeof waitForCi !== 'boolean')
+        errors.waitForCi = 'must be true or false';
+    if (Object.keys(errors).length > 0)
+        return { errors };
+    return {
+        project: {
+            name,
+            priority: priority,
+            sourceType: sourceType.id,
+            sourceSettings,
+            repoPath,
+            worktreeRoot,
+            pollIntervalSeconds: pollIntervalSeconds,
+            agentTimeoutMinutes: agentTimeoutMinutes,
+            agents: agents,
+            autostart: body.autostart === true,
+            reviewMaxRounds: reviewMaxRounds,
+            reviewIgnoreAuthors,
+            reviewMode: reviewMode,
+            waitForCi: waitForCi,
+        },
+    };
+}
+/** A project as the console may see it: every secret replaced by whether it is set. */
+export function maskProject(project, sourceTypes = SOURCE_TYPES) {
+    const type = sourceTypes.find((candidate) => candidate.id === project.sourceType);
+    const secrets = new Set(type?.fields.filter((field) => field.type === 'secret').map((field) => field.key));
+    // Settings without a known field are dropped rather than risk exposing a secret of a removed source type.
+    const sourceSettings = {};
+    for (const field of type?.fields ?? []) {
+        // A setting added after the project was saved shows the default the source applies for it.
+        const value = project.sourceSettings[field.key] ?? field.default ?? '';
+        sourceSettings[field.key] = secrets.has(field.key) ? { set: value !== '' } : value;
+    }
+    return { ...project, sourceSettings, sourceSummary: type?.summarise(project.sourceSettings) ?? project.sourceType };
+}
+const LEGACY_OVERRIDE_KEYS = [
+    'targetState',
+    'inProgressState',
+    'successState',
+    'pollIntervalSeconds',
+    'repoPath',
+    'worktreeRoot',
+    'agentTimeoutMinutes',
+];
+/**
+ * Creates the first project from a single-project setup in the environment, with any values that
+ * were overridden in the old Config tab applied. Does nothing once a project exists.
+ */
+export function migrateLegacy(db, env) {
+    // The old override rows are meaningless without the config they overrode; drop them either way.
+    const overrides = {};
+    for (const key of LEGACY_OVERRIDE_KEYS) {
+        const value = db.getSetting(key);
+        if (value !== undefined)
+            overrides[key] = value;
+        db.deleteSetting(key);
+    }
+    if (!env.legacy || db.listProjects().length > 0)
+        return null;
+    const legacy = { ...env.legacy, ...overrides };
+    const project = db.createProject({
+        name: path.basename(legacy.repoPath) || 'Default',
+        priority: 'normal',
+        sourceType: 'linear',
+        sourceSettings: {
+            apiKey: legacy.apiKey,
+            teamId: legacy.teamId,
+            projectId: legacy.projectId,
+            targetState: legacy.targetState,
+            inProgressState: legacy.inProgressState,
+            successState: legacy.successState,
+        },
+        repoPath: legacy.repoPath,
+        worktreeRoot: legacy.worktreeRoot,
+        pollIntervalSeconds: Number(legacy.pollIntervalSeconds),
+        agentTimeoutMinutes: Number(legacy.agentTimeoutMinutes),
+        agents: [],
+        autostart: legacy.autostart,
+        reviewMaxRounds: DEFAULT_REVIEW_ROUNDS,
+        reviewIgnoreAuthors: DEFAULT_IGNORED_AUTHORS,
+        reviewMode: 'none',
+        waitForCi: true,
+    });
+    // Every run so far was this setup's.
+    db.adoptRuns(project);
+    return project;
+}

package/dist/review/decide.js

@@ -0,0 +1,186 @@
+import { isPlainApproval } from '../agent/prompt.js';
+/**
+ * After a conflict round, GitHub takes a while to notice the push and go on reporting the old head
+ * as conflicting. Until it reports a new head, or this long has passed, the conflict is not raised again.
+ */
+export const CONFLICT_SETTLE_MS = 10 * 60_000;
+const timeOf = (iso) => (iso ? new Date(iso).getTime() : 0);
+/** Feedback newer than what has been dealt with. Compared as times: GitHub and foreman format timestamps differently. */
+const newerThan = (feedback, handledUntil) => feedback.filter((item) => timeOf(item.createdAt) > timeOf(handledUntil));
+/** Feedback that counts as review: new, and not from an account the project ignores (deployment bots and the like). */
+export const reviewable = (feedback, handledUntil, ignoreAuthors) => {
+    const ignored = new Set(ignoreAuthors.map((author) => author.toLowerCase()));
+    return newerThan(feedback, handledUntil).filter((item) => !ignored.has(item.author.toLowerCase().replace(/\[bot\]$/, '')));
+};
+/** The later of `floor` and the newest feedback: everything up to it counts as dealt with. */
+export const latestOf = (feedback, floor) => new Date(Math.max(floor.getTime(), ...feedback.map((item) => timeOf(item.createdAt)))).toISOString();
+/** Whether a pull request's conflict is one to act on now. */
+export function conflictToResolve(pr, progress, now) {
+    if (pr.mergeable !== 'CONFLICTING')
+        return false;
+    // A conflict has no timestamp to mark it as dealt with, so once the issue has been handed to a
+    // person at the round limit it is not raised again.
+    if (progress.handedOver)
+        return false;
+    // Same head as when the last conflict round ended: most likely GitHub has not caught up with the push.
+    const settling = progress.conflictHead === pr.headSha && now.getTime() - timeOf(progress.conflictAt ?? '') < CONFLICT_SETTLE_MS;
+    return !settling;
+}
+/** What a follow-up run is doing, for the pickup comment. */
+export const followUp = (item) => [
+    item.feedback.length > 0 ? 'addressing review feedback' : null,
+    item.conflict ? 'resolving merge conflicts' : null,
+    item.ciFailures?.length ? 'fixing failing checks' : null,
+]
+    .filter(Boolean)
+    .join(' and ') || 'addressing review feedback';
+/** Checks pending this long on one head are taken to be stuck. */
+export const CI_STUCK_MS = 2 * 60 * 60_000;
+/** Reruns of failed checks allowed on one head, automatic ones and those the agent asked for together. */
+export const CI_MAX_RERUNS = 2;
+/** GitHub Actions conclusions that say the job did not get to judge the code. */
+const INFRA_STATES = new Set(['CANCELLED', 'TIMED_OUT', 'STARTUP_FAILURE']);
+const failingChecks = (ci) => ci.checks.filter((check) => check.bucket === 'fail' || check.bucket === 'cancel');
+const names = (checks) => checks.map((check) => check.name).join(', ');
+const rerunnable = (checks) => checks.length > 0 && checks.every((check) => check.runId !== null);
+const runIdsOf = (checks) => [...new Set(checks.map((check) => check.runId))];
+const green = (ci) => !ci || ci.state === 'passing' || ci.state === 'none';
+/** The CI fields of `progress` for the pull request's current head; another head starts from nothing. */
+function headCi(progress, pr) {
+    const same = progress.ciHead === pr.headSha;
+    return {
+        reruns: same ? (progress.ciReruns ?? 0) : 0,
+        handled: same && progress.ciHandled === true,
+        notCode: same ? (progress.ciNotCode ?? null) : null,
+        pendingSince: same ? (progress.ciPendingSince ?? null) : null,
+    };
+}
+/** Failing checks on the head that no round or hand-over has dealt with yet. */
+function unhandledFailures(progress, pr, ci) {
+    if (!ci || ci.state !== 'failing' || progress.handedOver || headCi(progress, pr).handled)
+        return [];
+    return failingChecks(ci);
+}
+/**
+ * How the review progress's CI fields should change for what the checks show now: a new head starts
+ * afresh, and the first time its checks are seen pending is noted. Null when nothing changes.
+ */
+export function trackCi(progress, pr, ci, now) {
+    // No checks: nothing to keep, and a later head without a record starts afresh anyway.
+    if (!ci || ci.state === 'none')
+        return null;
+    const pending = ci.state === 'pending';
+    if (progress.ciHead !== pr.headSha) {
+        return { ciHead: pr.headSha, ciReruns: 0, ciHandled: false, ciNotCode: null, ciPendingSince: pending ? now.toISOString() : null };
+    }
+    if (pending && !progress.ciPendingSince)
+        return { ciPendingSince: now.toISOString() };
+    if (!pending && progress.ciPendingSince)
+        return { ciPendingSince: null };
+    return null;
+}
+/** The author name foreman gives an agent reviewer's findings; not a GitHub account. */
+export const AGENT_REVIEWER = 'foreman reviewer';
+/** An agent reviewer's findings, waiting for the author's agent, as one item of review feedback. */
+const pendingFindings = (progress, now) => progress.agentFindings
+    ? [
+        {
+            id: `foreman-review-${progress.agentReviewedHead ?? 'unknown'}`,
+            kind: 'review',
+            author: AGENT_REVIEWER,
+            body: progress.agentFindings,
+            state: 'CHANGES_REQUESTED',
+            createdAt: now.toISOString(),
+        },
+    ]
+    : [];
+const agentReviews = (mode) => mode === 'other_agent' || mode === 'any_agent';
+export function decideReview({ pr, progress, stage, ignoreAuthors, now, mode, ci = null }) {
+    // No pull request, or one closed without merging: nothing foreman can decide.
+    if (!pr || pr.state === 'CLOSED')
+        return { kind: 'none' };
+    if (pr.state === 'MERGED')
+        return { kind: 'finish', pr };
+    const feedback = [...reviewable(pr.feedback, progress.handledUntil, ignoreAuthors), ...pendingFindings(progress, now)];
+    const conflict = conflictToResolve(pr, progress, now);
+    const head = headCi(progress, pr);
+    const failures = unhandledFailures(progress, pr, ci);
+    if (failures.length > 0) {
+        if (head.notCode) {
+            return { kind: 'hand_over', pr, needs: `checks that still fail after a rerun (${names(failures)}); the agent found the cause is not the code: ${head.notCode}` };
+        }
+        const infra = failures.every((check) => INFRA_STATES.has(check.state));
+        if (infra && rerunnable(failures) && head.reruns < CI_MAX_RERUNS) {
+            return { kind: 'rerun', pr, runIds: runIdsOf(failures), checks: failures.map((check) => check.name) };
+        }
+        return { kind: 'round', pr, feedback, conflict, ciFailures: failures };
+    }
+    if (ci?.state === 'pending' && !progress.handedOver && !head.handled && head.pendingSince && now.getTime() - timeOf(head.pendingSince) >= CI_STUCK_MS) {
+        return { kind: 'hand_over', pr, needs: 'checks that have been pending for 2 hours' };
+    }
+    if (feedback.length > 0 || conflict) {
+        if (!conflict && isPlainApproval(feedback)) {
+            const handledUntil = latestOf(pr.feedback, now);
+            return green(ci) ? { kind: 'approve', pr, moveIssue: stage === 'review', handledUntil } : { kind: 'hold', pr, handledUntil };
+        }
+        return { kind: 'round', pr, feedback, conflict };
+    }
+    if (progress.approvalHead === pr.headSha && green(ci)) {
+        return { kind: 'approve', pr, moveIssue: stage === 'review', handledUntil: latestOf(pr.feedback, now) };
+    }
+    const unreviewed = agentReviews(mode) && stage === 'review' && progress.agentReviewedHead !== pr.headSha;
+    return unreviewed && green(ci) ? { kind: 'agent_review', pr } : { kind: 'none' };
+}
+export function decideCiFollowUp({ verdict, ci, progress, headBefore, headAfter, }) {
+    // A push starts the head afresh, whatever the agent said.
+    if (headAfter !== headBefore)
+        return { kind: 'none' };
+    const failures = failingChecks(ci);
+    if (!verdict)
+        return { kind: 'hand_over', needs: `failing checks (${names(failures)}); the agent did not say whether the change causes them and pushed nothing` };
+    if (verdict.verdict === 'fixed')
+        return { kind: 'hand_over', needs: `failing checks (${names(failures)}); the agent said it fixed them but pushed nothing` };
+    const reruns = progress.ciHead === headBefore ? (progress.ciReruns ?? 0) : 0;
+    if (rerunnable(failures) && reruns < CI_MAX_RERUNS)
+        return { kind: 'rerun', runIds: runIdsOf(failures), reason: verdict.reason };
+    return { kind: 'hand_over', needs: `failing checks (${names(failures)}) that the agent found are not caused by the code: ${verdict.reason}` };
+}
+/**
+ * Chooses the agent to review a pull request from the agents free now, in preference order. Another
+ * agent than the author's always comes first; only `any_agent` falls back to the author's own agent.
+ * Null means no agent review, or none possible right now.
+ */
+export function pickReviewer(mode, authorAgentId, free) {
+    if (mode !== 'other_agent' && mode !== 'any_agent')
+        return null;
+    const other = free.find((agent) => agent.id !== authorAgentId);
+    if (other)
+        return { agent: other, self: false };
+    const author = mode === 'any_agent' ? free.find((agent) => agent.id === authorAgentId) : undefined;
+    return author ? { agent: author, self: true } : null;
+}
+export function decideRoundStart({ pr, progress, ignoreAuthors, now, maxRounds, ci = null }) {
+    if (!pr || pr.state !== 'OPEN')
+        return { kind: 'none' };
+    const feedback = [...reviewable(pr.feedback, progress.handledUntil, ignoreAuthors), ...pendingFindings(progress, now)];
+    const conflict = conflictToResolve(pr, progress, now);
+    const ciFailures = unhandledFailures(progress, pr, ci);
+    if (feedback.length === 0 && !conflict && ciFailures.length === 0)
+        return { kind: 'none' };
+    if (progress.rounds >= maxRounds) {
+        const needs = [feedback.length > 0 ? 'new feedback' : null, conflict ? 'merge conflicts' : null, ciFailures.length > 0 ? 'failing checks' : null]
+            .filter(Boolean)
+            .join(' and ');
+        return { kind: 'hand_over', rounds: progress.rounds, needs, handledUntil: latestOf(pr.feedback, now) };
+    }
+    return { kind: 'start', round: progress.rounds + 1, feedback, conflict, ...(ciFailures.length > 0 ? { ciFailures } : {}) };
+}
+/** What to do when an agent is free to review a pull request, judged on it as it is now. An agent review counts as a round. */
+export function decideAgentReviewStart({ pr, progress, maxRounds, now }) {
+    if (!pr || pr.state !== 'OPEN' || progress.agentReviewedHead === pr.headSha)
+        return { kind: 'none' };
+    if (progress.rounds >= maxRounds) {
+        return { kind: 'hand_over', rounds: progress.rounds, needs: 'an agent review of the latest changes', handledUntil: latestOf(pr.feedback, now) };
+    }
+    return { kind: 'start', round: progress.rounds + 1 };
+}