phoebe-agent 0.0.0

package/dist/src/main.js

@@ -0,0 +1,1180 @@
+// Phoebe orchestration engine — an away-from-keyboard (AFK) worker loop.
+//
+// Picks ready-labelled issues off the configured repo one at a time and
+// works each in a git worktree off the container's private clone, on its own
+// branch, opening a PR to the default branch. The container is both
+// orchestrator and execution environment; agent CLIs run as direct children
+// with an allowlisted env. See docs/architecture.md for the full design.
+//
+// The `runEngine(argv)` export is the loop entry point invoked by src/cli.ts
+// after it loads the consumer's phoebe.config.ts and installs the resolved
+// config into src/resolved-config.ts. Recognised argv flags:
+//
+//   (no flags)              # persistent poll loop
+//   --run-once              # one unit of the first one-shot-eligible kind
+//   --dry-run --run-once    # host-side selection preview
+//
+// Work-unit execution is refused outside the container marker
+// (src/execution-gate.ts).
+import { execFileSync, execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { config } from "./resolved-config.js";
+import { PROVIDER_NAMES } from "./config-schema.js";
+import { buildAgentEnv } from "./agent-env.js";
+import { EXECUTION_REFUSED_MESSAGE, executionDecision, isInsideContainer, } from "./execution-gate.js";
+import { addWorktreeForExistingBranch, addWorktreeForNewBranch, commitCount, fetchOrigin as gitFetchOrigin, originBranchSha as gitOriginBranchSha, pushBranch, removeWorktree, worktreeDirForBranch, } from "./git-model.js";
+import { PROVIDERS } from "./providers/providers.js";
+import { runAgent } from "./providers/run-agent.js";
+import { buildDefaultPromptArgs, renderPrompt } from "./prompt.js";
+import { SELF_UPDATE_EXIT_CODE, shouldExitForSelfUpdate } from "./supervisor-decision.js";
+import { buildInitialPrBody, buildReviewsHandledComment, checksFixFailureComment, conflictFixFailureComment, followUpPrComment, formatFailingChecksForPrompt, isReviewSummaryComment, issueBranch, isPrInScope, isPrMergeConflicting, listFailingChecks, newestReviewThreadCommentCreatedAt, parseBlockedBy, parseChecksFailWatermarkFromComments, parseConflictFailWatermarkFromComments, parseReviewsHandledWatermarkFromComments, parseIssueNumberFromBranch, getMergedBlockerPrNumbers, oneShotWorkKinds, selectChecksCandidates, selectChecksUnit, selectReviewsCandidates, selectReviewsUnit, stackedCatchUpRetractionComment, RUN_ONCE_NOTHING_MESSAGE, selectConflictFixCandidates, selectFirstWorkUnit, selectConflictUnit, selectIssue, shouldPostChecksFixFailure, shouldPostConflictFixFailure, statusCheckRollupState, validateWorkOrder, workflowRunsToCheckItems, } from "./orchestrator.js";
+const DEFAULT_POLL_INTERVAL_MS = 300_000;
+// Never let a gh/git child process block the persistent loop forever (rate-limit
+// backoff, credential prompt, network partition). Configured toolchain commands
+// (install/test) get a longer leash.
+const CHILD_PROCESS_TIMEOUT_MS = 120_000;
+const SHELL_COMMAND_TIMEOUT_MS = 600_000;
+const MERGEABLE_RETRY_MS = 5_000;
+const MERGEABLE_RETRY_COUNT = 3;
+const PR_BASE = config.defaultBranch;
+// The branch the supervisor keeps the clone on — normally the default branch,
+// overridable (matching container/supervisor.sh) so a not-yet-merged Phoebe
+// branch can run itself end-to-end. PRs and worktree bases still use
+// config.defaultBranch.
+const trackedBranch = process.env["PHOEBE_DEFAULT_BRANCH"] ?? config.defaultBranch;
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+// Resolve a package-root-relative resource by walking up from this module's
+// directory: the build emits dist/src/main.js while prompts/ and templates/
+// ship at the package root, so the depth back to the root differs between the
+// source layout (src/) and the built layout (dist/src/).
+function resolvePackageFile(relativePath) {
+    let dir = moduleDir;
+    while (true) {
+        const candidate = join(dir, relativePath);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = dirname(dir);
+        // Stop at the package boundary. When Phoebe is installed as a dependency,
+        // its package sits directly inside a `node_modules` directory; walking past
+        // it would escape into the consuming repo, where an unrelated resource of
+        // the same relative path could shadow a genuinely-missing packaged one.
+        if (parent === dir || basename(parent) === "node_modules") {
+            throw new Error(`Could not find ${relativePath} within the Phoebe package (searched from ${moduleDir})`);
+        }
+        dir = parent;
+    }
+}
+const inContainer = isInsideContainer();
+// On the host only selection/--dry-run runs, against the local checkout; in
+// the container all git state lives in the private clone on the named volume.
+const repoDir = inContainer ? config.paths.repoDir : process.cwd();
+const worktreesDir = config.paths.worktreesDir;
+// ---------------------------------------------------------------------------
+// Provider selection (multi-provider ready)
+// ---------------------------------------------------------------------------
+function selectProvider() {
+    const name = process.env["PHOEBE_AGENT"] ?? config.defaultProvider;
+    if (!PROVIDER_NAMES.includes(name)) {
+        throw new Error(`Unknown PHOEBE_AGENT "${name}". Use one of: ${PROVIDER_NAMES.join(", ")}.`);
+    }
+    const provider = PROVIDERS[name];
+    const model = process.env["PHOEBE_MODEL"] ?? config.defaultModels[name];
+    return { provider, model };
+}
+const workOrder = validateWorkOrder(config.workOrder);
+// ---------------------------------------------------------------------------
+// gh helpers — always pinned to the configured repo
+// ---------------------------------------------------------------------------
+function ghJson(args) {
+    return JSON.parse(execFileSync("gh", [...args, "-R", config.repoSlug], {
+        encoding: "utf8",
+        timeout: CHILD_PROCESS_TIMEOUT_MS,
+    }));
+}
+function ghApiJson(endpoint) {
+    return JSON.parse(execFileSync("gh", ["api", endpoint], {
+        encoding: "utf8",
+        timeout: CHILD_PROCESS_TIMEOUT_MS,
+    }));
+}
+function gh(args, opts) {
+    execFileSync("gh", [...args, "-R", config.repoSlug], {
+        stdio: opts?.input !== undefined ? ["pipe", "inherit", "inherit"] : "inherit",
+        timeout: CHILD_PROCESS_TIMEOUT_MS,
+        ...(opts?.input !== undefined ? { input: opts.input } : {}),
+    });
+}
+function listReadyIssues() {
+    return ghJson([
+        "issue",
+        "list",
+        "--state",
+        "open",
+        "--label",
+        config.readyLabel,
+        "--limit",
+        "100",
+        "--search",
+        "sort:created-asc",
+        "--json",
+        "number,title,body,labels,createdAt",
+    ]).map((row) => ({
+        number: row.number,
+        title: row.title,
+        body: row.body,
+        createdAt: row.createdAt,
+        labels: row.labels.map((l) => l.name),
+    }));
+}
+function blockerPrState(blockerIssueNumber) {
+    const branch = issueBranch(blockerIssueNumber);
+    const open = ghJson([
+        "pr",
+        "list",
+        "--head",
+        branch,
+        "--state",
+        "open",
+        "--json",
+        "number",
+        "--limit",
+        "1",
+    ]);
+    const merged = ghJson([
+        "pr",
+        "list",
+        "--head",
+        branch,
+        "--state",
+        "merged",
+        "--json",
+        "number",
+        "--limit",
+        "1",
+    ]);
+    return {
+        hasOpenPr: open.length > 0,
+        openPrNumber: open[0]?.number,
+        hasMergedPr: merged.length > 0,
+        mergedPrNumber: merged[0]?.number,
+    };
+}
+function buildBlockerStates(issues) {
+    const blockerNumbers = new Set();
+    for (const issue of issues) {
+        for (const n of parseBlockedBy(issue.body)) {
+            blockerNumbers.add(n);
+        }
+    }
+    const states = new Map();
+    for (const n of blockerNumbers) {
+        try {
+            states.set(n, blockerPrState(n));
+        }
+        catch (error) {
+            // Absent entries are treated as unmerged blockers — safe to retry next cycle.
+            console.warn(`[phoebe] Skipping blocker state for #${n} this cycle — ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return states;
+}
+function buildBlockerStatesFromBodies(bodies) {
+    return buildBlockerStates(bodies.map(({ number, body }) => ({
+        number,
+        title: "",
+        body,
+        labels: [],
+        createdAt: "",
+    })));
+}
+function postPrComment(prNumber, body) {
+    gh(["pr", "comment", String(prNumber), "--body", body]);
+}
+function listOpenPhoebePrs() {
+    return ghJson([
+        "pr",
+        "list",
+        "--base",
+        PR_BASE,
+        "--state",
+        "open",
+        "--json",
+        "number,headRefName,isDraft,isCrossRepository,labels,author",
+        "--limit",
+        "100",
+    ])
+        .filter((pr) => isPrInScope({
+        headRefName: pr.headRefName,
+        isDraft: pr.isDraft,
+        isCrossRepository: pr.isCrossRepository,
+        labels: pr.labels.map((label) => label.name),
+    }))
+        .map((pr) => ({
+        number: pr.number,
+        headRefName: pr.headRefName,
+        authorLogin: pr.author.login,
+    }));
+}
+function viewPrMergeInfo(prNumber) {
+    return ghJson([
+        "pr",
+        "view",
+        String(prNumber),
+        "--json",
+        "number,headRefName,headRefOid,mergeable,mergeStateStatus",
+    ]);
+}
+function prConflictFailWatermark(prNumber) {
+    const { comments } = ghJson([
+        "pr",
+        "view",
+        String(prNumber),
+        "--json",
+        "comments",
+    ]);
+    return parseConflictFailWatermarkFromComments(comments.map((comment) => comment.body));
+}
+function prChecksFailWatermark(prNumber) {
+    const { comments } = ghJson([
+        "pr",
+        "view",
+        String(prNumber),
+        "--json",
+        "comments",
+    ]);
+    return parseChecksFailWatermarkFromComments(comments.map((comment) => comment.body));
+}
+function prReviewsHandledWatermark(prNumber) {
+    const { comments } = ghJson([
+        "pr",
+        "view",
+        String(prNumber),
+        "--json",
+        "comments",
+    ]);
+    return parseReviewsHandledWatermarkFromComments(comments.map((comment) => comment.body));
+}
+function phoebeGhLogin() {
+    return ghApiJson("user").login;
+}
+function issueBody(issueNumber) {
+    return ghJson(["issue", "view", String(issueNumber), "--json", "body"]).body;
+}
+// ---------------------------------------------------------------------------
+// git helpers bound to the clone
+// ---------------------------------------------------------------------------
+function fetchOrigin() {
+    gitFetchOrigin(repoDir);
+}
+function originBranchSha(branch) {
+    return gitOriginBranchSha(repoDir, branch);
+}
+function currentConflictFailureWatermark(branch) {
+    fetchOrigin();
+    return {
+        prHead: originBranchSha(branch),
+        mainHead: originBranchSha(config.defaultBranch),
+    };
+}
+function currentChecksFailureWatermark(branch) {
+    fetchOrigin();
+    return { prHead: originBranchSha(branch) };
+}
+function gitInWorktree(worktreeDir, args, opts) {
+    return execFileSync("git", ["-C", worktreeDir, ...args], {
+        encoding: "utf8",
+        timeout: CHILD_PROCESS_TIMEOUT_MS,
+        ...(opts?.stdio ? { stdio: opts.stdio } : {}),
+    });
+}
+/** Run a configured toolchain command (a shell string) inside a worktree. */
+function runShellCommand(command, cwd) {
+    execSync(command, { cwd, stdio: "inherit", timeout: SHELL_COMMAND_TIMEOUT_MS });
+}
+/** Shell executor for prompt !`...` expansion — captures stdout. */
+function promptShell(cwd) {
+    return (command) => execSync(command, { cwd, encoding: "utf8", timeout: SHELL_COMMAND_TIMEOUT_MS });
+}
+function loadPromptTemplate(relativePath) {
+    return readFileSync(resolvePackageFile(relativePath), "utf8");
+}
+/**
+ * After each cycle's fetch, exit deliberately when Phoebe's own code changed
+ * on the default branch — the container supervisor reinstalls and re-execs.
+ *
+ * When the supervisor has pinned us to the last-good SHA because a freshly
+ * pulled commit was crash-looping, it passes that quarantined SHA in
+ * `PHOEBE_QUARANTINED_SHA`; we stay on the good code (no self-update) while
+ * `origin/<branch>` still points at it, and resume self-updating only once the
+ * branch advances past it (a fix landed).
+ */
+function exitForSelfUpdateIfNeeded() {
+    if (!inContainer)
+        return;
+    fetchOrigin();
+    const originSha = originBranchSha(trackedBranch);
+    const changed = gitInWorktree(repoDir, ["diff", "--name-only", `HEAD..origin/${trackedBranch}`])
+        .split("\n")
+        .filter(Boolean);
+    if (shouldExitForSelfUpdate({
+        changedFiles: changed,
+        selfUpdatePaths: config.selfUpdatePaths,
+        originSha,
+        quarantinedSha: process.env["PHOEBE_QUARANTINED_SHA"] || null,
+    })) {
+        console.log(`[phoebe] Own code changed on origin/${trackedBranch} — exiting for supervisor re-exec.`);
+        process.exit(SELF_UPDATE_EXIT_CODE);
+    }
+}
+// ---------------------------------------------------------------------------
+// Work-unit execution
+// ---------------------------------------------------------------------------
+function prepareWorktree(opts) {
+    const worktreeDir = worktreeDirForBranch(worktreesDir, opts.branch);
+    removeWorktree(repoDir, worktreeDir);
+    if (opts.baseRef) {
+        addWorktreeForNewBranch({
+            repoDir,
+            worktreeDir,
+            branch: opts.branch,
+            baseRef: opts.baseRef,
+        });
+    }
+    else {
+        addWorktreeForExistingBranch({ repoDir, worktreeDir, branch: opts.branch });
+    }
+    return worktreeDir;
+}
+async function runAgentInWorktree(opts) {
+    const { provider, model } = selectProvider();
+    // Caller-supplied per-callsite args (ISSUE_NUMBER, PR_NUMBER, …) override
+    // the standard config-derived set by key.
+    const prompt = renderPrompt(loadPromptTemplate(opts.promptFile), { ...buildDefaultPromptArgs(config), ...opts.promptArgs }, promptShell(opts.worktreeDir));
+    const env = buildAgentEnv({
+        parentEnv: process.env,
+        provider: provider.name,
+        providerEnv: config.providerEnv,
+    });
+    const { exitCode } = await runAgent({
+        provider,
+        model,
+        prompt,
+        cwd: opts.worktreeDir,
+        env,
+    });
+    if (exitCode !== 0) {
+        console.log(`[phoebe] Agent exited with code ${exitCode}.`);
+    }
+}
+function tryCleanMerge(branch, mergedBlockerPrNumbers = []) {
+    let worktreeDir;
+    try {
+        worktreeDir = prepareWorktree({ branch });
+    }
+    catch {
+        return "failed";
+    }
+    try {
+        for (const blockerPrNumber of mergedBlockerPrNumbers) {
+            gitInWorktree(worktreeDir, ["fetch", "origin", `pull/${blockerPrNumber}/head`], {
+                stdio: "inherit",
+            });
+            gitInWorktree(worktreeDir, ["merge", "FETCH_HEAD"], { stdio: "pipe" });
+        }
+        gitInWorktree(worktreeDir, ["fetch", "origin", config.defaultBranch], { stdio: "inherit" });
+        gitInWorktree(worktreeDir, ["merge", `origin/${config.defaultBranch}`], { stdio: "pipe" });
+        pushBranch(worktreeDir, branch);
+        removeWorktree(repoDir, worktreeDir);
+        return "pushed";
+    }
+    catch {
+        try {
+            const unmerged = gitInWorktree(worktreeDir, ["diff", "--name-only", "--diff-filter=U"]);
+            if (unmerged.trim()) {
+                gitInWorktree(worktreeDir, ["merge", "--abort"], { stdio: "ignore" });
+                removeWorktree(repoDir, worktreeDir);
+                return "needs_agent";
+            }
+        }
+        catch {
+            // Fall through to failed.
+        }
+        try {
+            gitInWorktree(worktreeDir, ["merge", "--abort"], { stdio: "ignore" });
+        }
+        catch {
+            // Best-effort.
+        }
+        removeWorktree(repoDir, worktreeDir);
+        return "failed";
+    }
+}
+/** Blocker-first merge attempt, mirroring `cmd && … || true` hook semantics. */
+function attemptBlockerFirstMerges(worktreeDir, mergedBlockerPrNumbers) {
+    try {
+        for (const n of mergedBlockerPrNumbers) {
+            gitInWorktree(worktreeDir, ["fetch", "origin", `pull/${n}/head`], { stdio: "inherit" });
+            gitInWorktree(worktreeDir, ["merge", "FETCH_HEAD"], { stdio: "pipe" });
+        }
+        gitInWorktree(worktreeDir, ["fetch", "origin", config.defaultBranch], { stdio: "inherit" });
+        gitInWorktree(worktreeDir, ["merge", `origin/${config.defaultBranch}`], { stdio: "pipe" });
+    }
+    catch {
+        // Conflicts stay in the tree for the agent to resolve.
+    }
+}
+async function runConflictResolutionAgent(pr, mergedBlockerPrNumbers) {
+    const branch = pr.headRefName;
+    fetchOrigin();
+    const originShaBefore = originBranchSha(branch);
+    const worktreeDir = prepareWorktree({ branch });
+    try {
+        runShellCommand(config.installCommand, worktreeDir);
+        attemptBlockerFirstMerges(worktreeDir, mergedBlockerPrNumbers);
+        await runAgentInWorktree({
+            worktreeDir,
+            promptFile: config.promptFiles.conflict,
+            promptArgs: {
+                PR_NUMBER: String(pr.prNumber),
+                PR_BRANCH: branch,
+                BLOCKER_PR_NUMBERS: mergedBlockerPrNumbers.join(","),
+            },
+        });
+        fetchOrigin();
+        const originShaAfter = originBranchSha(branch);
+        const prInfo = viewPrMergeInfo(pr.prNumber);
+        const localCommitCount = commitCount(worktreeDir, `origin/${branch}..HEAD`);
+        let pushed = false;
+        if (shouldPostConflictFixFailure({
+            hostCommitCount: localCommitCount,
+            originShaBefore,
+            originShaAfter,
+            mergeable: prInfo.mergeable,
+            mergeStateStatus: prInfo.mergeStateStatus,
+        })) {
+            console.log(`[phoebe] Conflict fix for PR #${pr.prNumber} produced no commits — leaving PR unchanged.`);
+            postPrComment(pr.prNumber, conflictFixFailureComment(pr.prNumber, currentConflictFailureWatermark(pr.headRefName)));
+        }
+        else {
+            if (localCommitCount > 0) {
+                pushBranch(worktreeDir, branch);
+                pushed = true;
+                console.log(`[phoebe] Conflict resolved for PR #${pr.prNumber} — pushed.`);
+            }
+            else {
+                pushed = true;
+                console.log(`[phoebe] Conflict resolved for PR #${pr.prNumber} — already pushed by agent.`);
+            }
+        }
+        return pushed;
+    }
+    finally {
+        removeWorktree(repoDir, worktreeDir);
+    }
+}
+async function fixOnePrConflict(pr, issueBodies, blockerStates) {
+    console.log(`[phoebe] Conflict fix: PR #${pr.prNumber} (${pr.headRefName}).`);
+    fetchOrigin();
+    const issueNumber = pr.issueNumber ?? parseIssueNumberFromBranch(pr.headRefName);
+    const body = issueNumber !== null ? (issueBodies.get(issueNumber) ?? "") : "";
+    const mergedBlockerPrNumbers = getMergedBlockerPrNumbers(body, blockerStates);
+    if (mergedBlockerPrNumbers.length > 0) {
+        console.log(`[phoebe] Stacked catch-up: merging blocker PR(s) ${mergedBlockerPrNumbers.map((n) => `#${n}`).join(", ")} before ${config.defaultBranch}.`);
+    }
+    const cleanResult = tryCleanMerge(pr.headRefName, mergedBlockerPrNumbers);
+    if (cleanResult === "pushed") {
+        console.log(`[phoebe] Clean merge for PR #${pr.prNumber} — pushed.`);
+        if (mergedBlockerPrNumbers.length > 0) {
+            postPrComment(pr.prNumber, stackedCatchUpRetractionComment(mergedBlockerPrNumbers));
+        }
+        return;
+    }
+    if (cleanResult === "failed") {
+        console.log(`[phoebe] Could not start merge for PR #${pr.prNumber} — skipping.`);
+        postPrComment(pr.prNumber, conflictFixFailureComment(pr.prNumber, currentConflictFailureWatermark(pr.headRefName)));
+        return;
+    }
+    await runConflictResolutionAgent(pr, mergedBlockerPrNumbers);
+}
+async function runChecksResolutionAgent(pr) {
+    const branch = pr.headRefName;
+    fetchOrigin();
+    const originShaBefore = originBranchSha(branch);
+    const worktreeDir = prepareWorktree({ branch });
+    try {
+        runShellCommand(config.installCommand, worktreeDir);
+        await runAgentInWorktree({
+            worktreeDir,
+            promptFile: config.promptFiles.checks,
+            promptArgs: {
+                PR_NUMBER: String(pr.prNumber),
+                PR_BRANCH: branch,
+                FAILING_CHECKS: formatFailingChecksForPrompt(pr.failingChecks),
+            },
+        });
+        fetchOrigin();
+        const originShaAfter = originBranchSha(branch);
+        const localCommitCount = commitCount(worktreeDir, `origin/${branch}..HEAD`);
+        let pushed = false;
+        if (shouldPostChecksFixFailure({
+            hostCommitCount: localCommitCount,
+            originShaBefore,
+            originShaAfter,
+        })) {
+            console.log(`[phoebe] Checks fix for PR #${pr.prNumber} produced no commits — leaving PR unchanged.`);
+            postPrComment(pr.prNumber, checksFixFailureComment(pr.prNumber, currentChecksFailureWatermark(pr.headRefName)));
+        }
+        else {
+            if (localCommitCount > 0) {
+                pushBranch(worktreeDir, branch);
+                pushed = true;
+                console.log(`[phoebe] Checks fixed for PR #${pr.prNumber} — pushed.`);
+            }
+            else {
+                pushed = true;
+                console.log(`[phoebe] Checks fixed for PR #${pr.prNumber} — already pushed by agent.`);
+            }
+        }
+        return pushed;
+    }
+    finally {
+        removeWorktree(repoDir, worktreeDir);
+    }
+}
+async function fixOnePrChecks(pr, issueBodies, blockerStates) {
+    console.log(`[phoebe] Checks fix: PR #${pr.prNumber} (${pr.headRefName}) — ` +
+        `${pr.failingChecks.map((c) => c.name).join(", ")}.`);
+    fetchOrigin();
+    if (pr.mergeStateStatus === "BEHIND") {
+        const issueNumber = pr.issueNumber ?? parseIssueNumberFromBranch(pr.headRefName);
+        const body = issueNumber !== null ? (issueBodies.get(issueNumber) ?? "") : "";
+        const mergedBlockerPrNumbers = getMergedBlockerPrNumbers(body, blockerStates);
+        if (mergedBlockerPrNumbers.length > 0) {
+            console.log(`[phoebe] Behind main — catch-up merging blocker PR(s) ${mergedBlockerPrNumbers.map((n) => `#${n}`).join(", ")} before ${config.defaultBranch}.`);
+        }
+        else {
+            console.log(`[phoebe] Behind main — catch-up merge for PR #${pr.prNumber}.`);
+        }
+        const cleanResult = tryCleanMerge(pr.headRefName, mergedBlockerPrNumbers);
+        if (cleanResult === "pushed") {
+            console.log(`[phoebe] Catch-up merge for PR #${pr.prNumber} — pushed; waiting for CI on next cycle.`);
+            if (mergedBlockerPrNumbers.length > 0) {
+                postPrComment(pr.prNumber, stackedCatchUpRetractionComment(mergedBlockerPrNumbers));
+            }
+            return;
+        }
+        if (cleanResult === "needs_agent" || cleanResult === "failed") {
+            console.log(`[phoebe] Catch-up merge conflicted for PR #${pr.prNumber} — deferring to conflicts mode.`);
+            return;
+        }
+    }
+    await runChecksResolutionAgent(pr);
+}
+function fetchReviewThreads(prNumber) {
+    const [owner, repo] = config.repoSlug.split("/");
+    const threads = [];
+    let cursor = null;
+    let hasNextPage = true;
+    while (hasNextPage) {
+        const afterArg = cursor ? `, after:"${cursor}"` : "";
+        const query = `query($owner:String!,$repo:String!,$pr:Int!) {
+  repository(owner:$owner,name:$repo) {
+    pullRequest(number:$pr) {
+      reviewThreads(first:100${afterArg}) {
+        pageInfo { hasNextPage endCursor }
+        nodes {
+          isResolved
+          isOutdated
+          comments(first:30) {
+            nodes {
+              createdAt
+              author { login }
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+        const page = JSON.parse(execFileSync("gh", [
+            "api",
+            "graphql",
+            "-f",
+            `query=${query}`,
+            "-f",
+            `owner=${owner}`,
+            "-f",
+            `repo=${repo}`,
+            "-F",
+            `pr=${prNumber}`,
+        ], { encoding: "utf8", timeout: CHILD_PROCESS_TIMEOUT_MS }));
+        const reviewThreads = page.data.repository.pullRequest.reviewThreads;
+        for (const node of reviewThreads.nodes) {
+            threads.push({
+                isResolved: node.isResolved,
+                isOutdated: node.isOutdated,
+                comments: node.comments.nodes.map((comment) => ({
+                    createdAt: comment.createdAt,
+                    authorLogin: comment.author?.login ?? "",
+                })),
+            });
+        }
+        hasNextPage = reviewThreads.pageInfo.hasNextPage;
+        cursor = reviewThreads.pageInfo.endCursor;
+        if (!hasNextPage) {
+            break;
+        }
+    }
+    return threads;
+}
+function hasNewReviewSummaryComment(prNumber, phoebeLogin, since) {
+    const { comments } = ghJson(["pr", "view", String(prNumber), "--json", "comments"]);
+    return comments.some((comment) => comment.author.login === phoebeLogin &&
+        comment.createdAt > since &&
+        isReviewSummaryComment(comment.body));
+}
+async function runReviewsResolutionAgent(pr, phoebeLogin) {
+    const branch = pr.headRefName;
+    const runStartedAt = new Date().toISOString();
+    fetchOrigin();
+    const originShaBefore = originBranchSha(branch);
+    const worktreeDir = prepareWorktree({ branch });
+    try {
+        runShellCommand(config.installCommand, worktreeDir);
+        await runAgentInWorktree({
+            worktreeDir,
+            promptFile: config.promptFiles.reviews,
+            promptArgs: {
+                PR_NUMBER: String(pr.prNumber),
+                PR_BRANCH: branch,
+            },
+        });
+        fetchOrigin();
+        const originShaAfter = originBranchSha(branch);
+        const localCommitCount = commitCount(worktreeDir, `origin/${branch}..HEAD`);
+        if (localCommitCount > 0) {
+            pushBranch(worktreeDir, branch);
+            console.log(`[phoebe] Review feedback handled for PR #${pr.prNumber} — pushed.`);
+        }
+        else if (originShaAfter !== originShaBefore) {
+            console.log(`[phoebe] Review feedback handled for PR #${pr.prNumber} — already pushed by agent.`);
+        }
+        const hasSummary = hasNewReviewSummaryComment(pr.prNumber, phoebeLogin, runStartedAt);
+        const pushed = localCommitCount > 0 || originShaAfter !== originShaBefore;
+        // Watermark only the activity captured before the agent ran (pr.threads is
+        // the pre-run snapshot from fetchReviewsWorkData). Re-fetching here could
+        // absorb feedback posted concurrently with the run — marking it handled
+        // even though the agent never observed it, so it would never trigger another
+        // cycle. Any activity newer than this snapshot correctly re-selects the PR.
+        const latestActivityAt = newestReviewThreadCommentCreatedAt(pr.threads);
+        if (hasSummary) {
+            console.log(`[phoebe] Review summary posted for PR #${pr.prNumber}.`);
+        }
+        else if (!pushed) {
+            console.log(`[phoebe] Review handling for PR #${pr.prNumber} produced no summary or push.`);
+        }
+        postPrComment(pr.prNumber, buildReviewsHandledComment({
+            latestActivityAt,
+            failed: !hasSummary && !pushed,
+        }));
+    }
+    finally {
+        removeWorktree(repoDir, worktreeDir);
+    }
+}
+async function fixOnePrReviews(pr, phoebeLogin) {
+    console.log(`[phoebe] Reviews fix: PR #${pr.prNumber} (${pr.headRefName}).`);
+    fetchOrigin();
+    await runReviewsResolutionAgent(pr, phoebeLogin);
+}
+async function runOneIssue(issueNumber, issueTitle, worktreeBase, stacked, blockerIssueNumber, blockerPrNumber) {
+    const agentBranch = issueBranch(issueNumber);
+    fetchOrigin();
+    const worktreeDir = prepareWorktree({ branch: agentBranch, baseRef: worktreeBase });
+    try {
+        runShellCommand(config.installCommand, worktreeDir);
+        await runAgentInWorktree({
+            worktreeDir,
+            promptFile: config.promptFiles.issue,
+            promptArgs: { ISSUE_NUMBER: String(issueNumber) },
+        });
+        const newCommitCount = commitCount(worktreeDir, `${worktreeBase}..HEAD`);
+        if (newCommitCount > 0) {
+            pushBranch(worktreeDir, agentBranch);
+            const existingPr = ghJson([
+                "pr",
+                "list",
+                "--head",
+                agentBranch,
+                "--state",
+                "open",
+                "--json",
+                "number",
+            ])[0]?.number;
+            if (existingPr === undefined) {
+                const prTitle = `Phoebe: ${issueTitle} (#${issueNumber})`;
+                const prBody = buildInitialPrBody({
+                    issueNumber,
+                    commitCount: newCommitCount,
+                    ...(stacked && blockerIssueNumber !== undefined && blockerPrNumber !== undefined
+                        ? { stacked: { blockerIssueNumber, blockerPrNumber } }
+                        : {}),
+                });
+                gh([
+                    "pr",
+                    "create",
+                    "--head",
+                    agentBranch,
+                    "--base",
+                    PR_BASE,
+                    "--title",
+                    prTitle,
+                    "--body-file",
+                    "-",
+                ], { input: prBody });
+            }
+            else {
+                console.log(`[phoebe] PR #${existingPr} already exists for ${agentBranch} — posting follow-up note.`);
+                postPrComment(existingPr, followUpPrComment(issueNumber, newCommitCount));
+            }
+        }
+        else {
+            console.log("[phoebe] No commits — skipping PR creation.");
+        }
+    }
+    finally {
+        removeWorktree(repoDir, worktreeDir);
+    }
+}
+async function conflictingPrCandidate(pr) {
+    for (let attempt = 0; attempt < MERGEABLE_RETRY_COUNT; attempt++) {
+        const info = viewPrMergeInfo(pr.number);
+        if (isPrMergeConflicting(info.mergeable, info.mergeStateStatus)) {
+            const issueNumber = parseIssueNumberFromBranch(info.headRefName);
+            return {
+                prNumber: info.number,
+                headRefName: info.headRefName,
+                headSha: info.headRefOid,
+                ...(issueNumber !== null ? { issueNumber } : {}),
+            };
+        }
+        if (info.mergeable !== "UNKNOWN") {
+            return null;
+        }
+        if (attempt < MERGEABLE_RETRY_COUNT - 1) {
+            await sleep(MERGEABLE_RETRY_MS);
+        }
+    }
+    return null;
+}
+async function fetchConflictingPrs() {
+    const openPrs = listOpenPhoebePrs();
+    const conflicting = [];
+    for (const pr of openPrs) {
+        try {
+            const candidate = await conflictingPrCandidate(pr);
+            if (candidate) {
+                conflicting.push(candidate);
+            }
+        }
+        catch (error) {
+            console.warn(`[phoebe] Skipping PR #${pr.number} for conflicts this cycle — ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return conflicting;
+}
+// GraphQL statusCheckRollup is not readable by fine-grained PATs (GitHub-App/
+// OAuth only), so check state comes from the REST Actions API instead.
+function listCommitCheckItems(headSha) {
+    return workflowRunsToCheckItems(ghJson([
+        "run",
+        "list",
+        "--commit",
+        headSha,
+        "--json",
+        "workflowName,status,conclusion",
+        "--limit",
+        "50",
+    ]));
+}
+async function failingChecksCandidate(pr) {
+    for (let attempt = 0; attempt < MERGEABLE_RETRY_COUNT; attempt++) {
+        const info = viewPrMergeInfo(pr.number);
+        if (isPrMergeConflicting(info.mergeable, info.mergeStateStatus)) {
+            return null;
+        }
+        const checkItems = listCommitCheckItems(info.headRefOid);
+        const rollup = statusCheckRollupState(checkItems);
+        if (rollup === "FAILURE") {
+            const issueNumber = parseIssueNumberFromBranch(info.headRefName);
+            return {
+                prNumber: info.number,
+                headRefName: info.headRefName,
+                headSha: info.headRefOid,
+                mergeable: info.mergeable,
+                mergeStateStatus: info.mergeStateStatus,
+                failingChecks: listFailingChecks(checkItems),
+                ...(issueNumber !== null ? { issueNumber } : {}),
+            };
+        }
+        if (rollup !== "PENDING" && info.mergeable !== "UNKNOWN") {
+            return null;
+        }
+        if (attempt < MERGEABLE_RETRY_COUNT - 1) {
+            await sleep(MERGEABLE_RETRY_MS);
+        }
+    }
+    return null;
+}
+async function fetchFailingCheckPrs() {
+    const openPrs = listOpenPhoebePrs();
+    const failing = [];
+    for (const pr of openPrs) {
+        try {
+            const candidate = await failingChecksCandidate(pr);
+            if (candidate) {
+                failing.push(candidate);
+            }
+        }
+        catch (error) {
+            console.warn(`[phoebe] Skipping PR #${pr.number} for checks this cycle — ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return failing;
+}
+async function fetchReviewsWorkData() {
+    const phoebeLogin = phoebeGhLogin();
+    const openPrs = listOpenPhoebePrs();
+    const reviewActivityPrs = [];
+    for (const pr of openPrs) {
+        try {
+            const info = viewPrMergeInfo(pr.number);
+            if (isPrMergeConflicting(info.mergeable, info.mergeStateStatus)) {
+                continue;
+            }
+            const threads = fetchReviewThreads(pr.number);
+            const issueNumber = parseIssueNumberFromBranch(info.headRefName);
+            reviewActivityPrs.push({
+                prNumber: info.number,
+                headRefName: info.headRefName,
+                authorLogin: pr.authorLogin,
+                mergeable: info.mergeable,
+                mergeStateStatus: info.mergeStateStatus,
+                threads,
+                handledWatermark: prReviewsHandledWatermark(pr.number),
+                ...(issueNumber !== null ? { issueNumber } : {}),
+            });
+        }
+        catch (error) {
+            console.warn(`[phoebe] Skipping PR #${pr.number} for reviews this cycle — ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const issueNumbers = [
+        ...new Set(reviewActivityPrs
+            .map((pr) => pr.issueNumber ?? parseIssueNumberFromBranch(pr.headRefName))
+            .filter((n) => n !== null)),
+    ];
+    const issueBodies = new Map(issueNumbers.map((number) => [number, issueBody(number)]));
+    return { reviewActivityPrs, issueBodies, phoebeLogin };
+}
+async function fetchConflictWorkData() {
+    const rawConflictingPrs = await fetchConflictingPrs();
+    fetchOrigin();
+    const currentMainHead = originBranchSha(config.defaultBranch);
+    const conflictingPrs = rawConflictingPrs.map((pr) => ({
+        ...pr,
+        failureWatermark: prConflictFailWatermark(pr.prNumber),
+    }));
+    const issueNumbers = [
+        ...new Set(conflictingPrs
+            .map((pr) => pr.issueNumber ?? parseIssueNumberFromBranch(pr.headRefName))
+            .filter((n) => n !== null)),
+    ];
+    const issueBodies = new Map(issueNumbers.map((number) => [number, issueBody(number)]));
+    return { conflictingPrs, issueBodies, currentMainHead };
+}
+async function fetchChecksWorkData() {
+    const rawFailingPrs = await fetchFailingCheckPrs();
+    const failingCheckPrs = rawFailingPrs.map((pr) => ({
+        ...pr,
+        failureWatermark: prChecksFailWatermark(pr.prNumber),
+    }));
+    const issueNumbers = [
+        ...new Set(failingCheckPrs
+            .map((pr) => pr.issueNumber ?? parseIssueNumberFromBranch(pr.headRefName))
+            .filter((n) => n !== null)),
+    ];
+    const issueBodies = new Map(issueNumbers.map((number) => [number, issueBody(number)]));
+    return { failingCheckPrs, issueBodies };
+}
+function fetchIssueWorkData() {
+    const issues = listReadyIssues();
+    return { issues, blockerStates: buildBlockerStates(issues) };
+}
+async function runIssueUnit(unit) {
+    const { issue: target, resolution } = unit;
+    console.log(`[phoebe] Working #${target.number} — base ${resolution.worktreeBase}` +
+        (resolution.stacked ? ` (stacked on #${resolution.blockerIssueNumber})` : "") +
+        ".");
+    await runOneIssue(target.number, target.title, resolution.worktreeBase, resolution.stacked, resolution.blockerIssueNumber, resolution.blockerPrNumber);
+}
+let conflictRunContext = {
+    issueBodies: new Map(),
+    blockerStates: new Map(),
+};
+let checksRunContext = {
+    issueBodies: new Map(),
+    blockerStates: new Map(),
+};
+let reviewsRunContext = { phoebeLogin: "" };
+const KINDS = {
+    conflicts: {
+        name: "conflicts",
+        fetch: async () => {
+            const { conflictingPrs, issueBodies, currentMainHead } = await fetchConflictWorkData();
+            return { kind: "conflicts", conflictingPrs, issueBodies, currentMainHead };
+        },
+        runUnit: async (unit) => {
+            await fixOnePrConflict(unit, conflictRunContext.issueBodies, conflictRunContext.blockerStates);
+        },
+    },
+    checks: {
+        name: "checks",
+        fetch: async () => {
+            const { failingCheckPrs, issueBodies } = await fetchChecksWorkData();
+            return { kind: "checks", failingCheckPrs, issueBodies };
+        },
+        runUnit: async (unit) => {
+            await fixOnePrChecks(unit, checksRunContext.issueBodies, checksRunContext.blockerStates);
+        },
+    },
+    reviews: {
+        name: "reviews",
+        fetch: async () => {
+            const { reviewActivityPrs, issueBodies, phoebeLogin } = await fetchReviewsWorkData();
+            return { kind: "reviews", reviewActivityPrs, issueBodies, phoebeLogin };
+        },
+        runUnit: async (unit) => {
+            await fixOnePrReviews(unit, reviewsRunContext.phoebeLogin);
+        },
+    },
+    issues: {
+        name: "issues",
+        fetch: async () => {
+            const { issues, blockerStates } = fetchIssueWorkData();
+            return { kind: "issues", issues, blockerStates };
+        },
+        runUnit: async (unit) => {
+            await runIssueUnit(unit);
+        },
+    },
+};
+async function fetchCycleWorkData(kinds) {
+    let issues = [];
+    let blockerStates = new Map();
+    let conflictingPrs = [];
+    let failingCheckPrs = [];
+    let reviewActivityPrs = [];
+    let issueBodies = new Map();
+    let phoebeLogin;
+    let currentMainHead;
+    for (const kind of kinds) {
+        const fetched = await KINDS[kind].fetch();
+        if (fetched.kind === "issues") {
+            issues = fetched.issues;
+            blockerStates = fetched.blockerStates;
+        }
+        else if (fetched.kind === "conflicts") {
+            conflictingPrs = fetched.conflictingPrs;
+            issueBodies = fetched.issueBodies;
+            currentMainHead = fetched.currentMainHead;
+        }
+        else if (fetched.kind === "checks") {
+            failingCheckPrs = fetched.failingCheckPrs;
+            for (const [number, body] of fetched.issueBodies) {
+                issueBodies.set(number, body);
+            }
+        }
+        else {
+            reviewActivityPrs = fetched.reviewActivityPrs;
+            phoebeLogin = fetched.phoebeLogin;
+            for (const [number, body] of fetched.issueBodies) {
+                issueBodies.set(number, body);
+            }
+        }
+    }
+    const allBodies = [...issueBodies.entries()].map(([number, body]) => ({ number, body }));
+    if (allBodies.length > 0) {
+        const mergedBlockerStates = buildBlockerStatesFromBodies(allBodies);
+        for (const [blockerIssue, state] of mergedBlockerStates) {
+            blockerStates.set(blockerIssue, state);
+        }
+    }
+    conflictRunContext = { issueBodies, blockerStates };
+    checksRunContext = { issueBodies, blockerStates };
+    if (phoebeLogin) {
+        reviewsRunContext = { phoebeLogin };
+    }
+    return {
+        issues,
+        blockerStates,
+        conflictingPrs,
+        failingCheckPrs,
+        reviewActivityPrs,
+        issueBodies,
+        phoebeLogin,
+        currentMainHead,
+    };
+}
+function logIdleCycle(data) {
+    const phoebeBase = process.env["PHOEBE_BASE"];
+    if (data.issues.length > 0 && !selectIssue(data.issues, data.blockerStates, phoebeBase)) {
+        console.log(`[phoebe] ${data.issues.length} ${config.readyLabel} issue(s) but none workable this cycle (blocked or waiting on blocker PR).`);
+        return;
+    }
+    if (data.conflictingPrs.length > 0) {
+        const conflictBlockerStates = buildBlockerStatesFromBodies([...data.issueBodies.entries()].map(([number, body]) => ({ number, body })));
+        const conflictOpts = data.currentMainHead
+            ? { currentMainHead: data.currentMainHead }
+            : undefined;
+        const candidatesWithoutWatermark = selectConflictFixCandidates(data.conflictingPrs, data.issueBodies, conflictBlockerStates);
+        const candidates = selectConflictFixCandidates(data.conflictingPrs, data.issueBodies, conflictBlockerStates, conflictOpts);
+        const unit = selectConflictUnit(data.conflictingPrs, data.issueBodies, conflictBlockerStates, conflictOpts);
+        const skippedStacked = data.conflictingPrs.length - candidatesWithoutWatermark.length;
+        const skippedWatermark = candidatesWithoutWatermark.length - candidates.length;
+        if (skippedStacked > 0) {
+            console.log(`[phoebe] ${skippedStacked} conflicting PR(s) skipped (stacked on open blocker).`);
+        }
+        if (skippedWatermark > 0) {
+            console.log(`[phoebe] ${skippedWatermark} conflicting PR(s) skipped (unchanged failure watermark).`);
+        }
+        if (!unit) {
+            console.log(`[phoebe] ${data.conflictingPrs.length} conflicting PR(s) but none fixable this cycle.`);
+            return;
+        }
+    }
+    if (data.failingCheckPrs.length > 0) {
+        const checksBlockerStates = buildBlockerStatesFromBodies([...data.issueBodies.entries()].map(([number, body]) => ({ number, body })));
+        const candidatesWithoutWatermark = selectChecksCandidates(data.failingCheckPrs, data.issueBodies, checksBlockerStates);
+        const unit = selectChecksUnit(data.failingCheckPrs, data.issueBodies, checksBlockerStates);
+        const skippedStacked = data.failingCheckPrs.length - candidatesWithoutWatermark.length;
+        if (skippedStacked > 0) {
+            console.log(`[phoebe] ${skippedStacked} failing-CI PR(s) skipped (stacked or watermarked).`);
+        }
+        if (!unit) {
+            console.log(`[phoebe] ${data.failingCheckPrs.length} failing-CI PR(s) but none fixable this cycle.`);
+            return;
+        }
+    }
+    if (data.reviewActivityPrs.length > 0 && data.phoebeLogin) {
+        const reviewsBlockerStates = buildBlockerStatesFromBodies([...data.issueBodies.entries()].map(([number, body]) => ({ number, body })));
+        const candidates = selectReviewsCandidates(data.reviewActivityPrs, data.issueBodies, reviewsBlockerStates, data.phoebeLogin);
+        const unit = selectReviewsUnit(data.reviewActivityPrs, data.issueBodies, reviewsBlockerStates, data.phoebeLogin);
+        const skipped = data.reviewActivityPrs.length - candidates.length;
+        if (skipped > 0) {
+            console.log(`[phoebe] ${skipped} review-feedback PR(s) skipped (stacked, watermarked, or no new activity).`);
+        }
+        if (!unit) {
+            console.log(`[phoebe] ${data.reviewActivityPrs.length} review-feedback PR(s) but none fixable this cycle.`);
+            return;
+        }
+    }
+    console.log("[phoebe] No work this cycle — idle.");
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function describeUnit(picked) {
+    if (picked.kind === "conflicts") {
+        const unit = picked.unit;
+        return `conflict fix for PR #${unit.prNumber} (${unit.headRefName})`;
+    }
+    if (picked.kind === "checks") {
+        const unit = picked.unit;
+        return `checks fix for PR #${unit.prNumber} (${unit.headRefName})`;
+    }
+    if (picked.kind === "reviews") {
+        const unit = picked.unit;
+        return `review feedback for PR #${unit.prNumber} (${unit.headRefName})`;
+    }
+    const unit = picked.unit;
+    return `issue #${unit.issue.number} — base ${unit.resolution.worktreeBase}`;
+}
+// ---------------------------------------------------------------------------
+// Main loop
+// ---------------------------------------------------------------------------
+/**
+ * Drive the Phoebe worker loop until it exits (persistent mode) or completes
+ * one unit (`--run-once`). Called by src/cli.ts after the resolved config is
+ * installed; the CLI passes its argv with `--config <path>` already stripped
+ * so this only sees engine-level flags.
+ */
+export async function runEngine(argv = process.argv.slice(2)) {
+    const runOnce = argv.includes("--run-once");
+    const dryRun = argv.includes("--dry-run");
+    const rawPollIntervalMs = Number(process.env["PHOEBE_POLL_INTERVAL_MS"]);
+    const pollIntervalMs = Number.isFinite(rawPollIntervalMs) && rawPollIntervalMs > 0
+        ? rawPollIntervalMs
+        : DEFAULT_POLL_INTERVAL_MS;
+    console.log(runOnce
+        ? "[phoebe] Run-once mode — will work at most one unit of the first one-shot-eligible kind in WORK_ORDER, then exit."
+        : `[phoebe] Persistent mode — idle poll every ${pollIntervalMs}ms.`);
+    if (dryRun) {
+        console.log("[phoebe] Dry-run — selection only, nothing executes.");
+    }
+    while (true) {
+        exitForSelfUpdateIfNeeded();
+        const fetchKinds = runOnce ? oneShotWorkKinds(workOrder) : workOrder;
+        const data = await fetchCycleWorkData(fetchKinds);
+        const picked = selectFirstWorkUnit(workOrder, {
+            issues: data.issues,
+            blockerStates: data.blockerStates,
+            conflictingPrs: data.conflictingPrs,
+            failingCheckPrs: data.failingCheckPrs,
+            reviewActivityPrs: data.reviewActivityPrs,
+            issueBodies: data.issueBodies,
+            phoebeBase: process.env["PHOEBE_BASE"],
+            phoebeLogin: data.phoebeLogin,
+            currentMainHead: data.currentMainHead,
+        }, { oneShotOnly: runOnce });
+        if (!picked) {
+            if (runOnce) {
+                console.log(RUN_ONCE_NOTHING_MESSAGE);
+            }
+            else {
+                logIdleCycle(data);
+            }
+            if (runOnce || dryRun)
+                break;
+            await sleep(pollIntervalMs);
+            continue;
+        }
+        const decision = executionDecision({ dryRun, inContainer });
+        if (decision === "dry-run") {
+            console.log(`[phoebe] Would execute: ${describeUnit(picked)}.`);
+            break;
+        }
+        if (decision === "refuse") {
+            console.error(EXECUTION_REFUSED_MESSAGE);
+            process.exit(1);
+        }
+        try {
+            await KINDS[picked.kind].runUnit(picked.unit);
+        }
+        catch (error) {
+            if (runOnce) {
+                throw error;
+            }
+            // A failed unit must not kill the daemon — prepareWorktree clears any
+            // stale worktree on the next attempt.
+            console.error(`[phoebe] Failed executing ${describeUnit(picked)} — ${error instanceof Error ? error.message : String(error)}`);
+            await sleep(pollIntervalMs);
+            continue;
+        }
+        if (runOnce)
+            break;
+    }
+}