dorfl 0.0.0 → 0.1.0

package/dist/run.js

@@ -0,0 +1,963 @@
+import { resolvePromptGuidance } from './config.js';
+import { resolveRepoConfig } from './repo-config.js';
+import { scan } from './scan.js';
+import { selectCandidates } from './select.js';
+import { performClaim } from './claim-cas.js';
+import { updateJobRecord, encodeWorkId } from './workspace.js';
+import { encodeRepoKey } from './repo-mirror.js';
+import { run as runProcess } from './git.js';
+import { mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { ledgerWrite } from './ledger-write.js';
+import { jobWorktreeStrategy, } from './isolation.js';
+import { runConcurrent, createKeyedLock } from './concurrency.js';
+import { createHarness } from './pi-harness.js';
+import { generateSessionPath } from './session-path.js';
+import { resolveTask, buildAgentPrompt, resolveContinueContext, resolvePromptGuidanceForItem, PromptError, } from './prompt.js';
+import { parseStopSentinel, isWorkBranchDiffEmpty, emptyDiffStopReason, } from './agent-stop.js';
+import { classifyFailureCause, failureCauseLabel, } from './failure-cause.js';
+import { performIntegration } from './integration-core.js';
+import { shouldFailProposePrIntent, PROPOSE_PR_INTENT_GH_UNAVAILABLE_MESSAGE, } from './do-config.js';
+import { checkGatePreconditions, detectLockfileOnDisk, detectLockfileOnMirrorMain, } from './gate-readiness.js';
+import { isGitHubArbiterUrl, GitHubProvider } from './github.js';
+import { identityEnv, assertTransportAllowed } from './identity.js';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+/** Is `repoPath` a BARE git repository (a registry hub mirror has no work tree)? */
+function isBareRepo(repoPath, env) {
+    const result = runProcess('git', ['rev-parse', '--is-bare-repository'], repoPath, { env });
+    return result.status === 0 && result.stdout.trim() === 'true';
+}
+/**
+ * Claim a slug against a repo that may be EITHER a working checkout (the in-place
+ * test/`do` path) OR a BARE registry hub mirror (`run`'s production discovery).
+ *
+ * The claim CAS needs a NON-bare checkout with an `origin/main` tracking ref and
+ * a work tree to commit in (a bare mirror cannot `git mv`/`git commit`). So for a
+ * bare mirror we clone it into a throwaway claim dir under `workspace` and claim
+ * THERE against `origin` (the mirror URL) — the EXACT pattern `do --remote` uses
+ * (`do.ts` §2–3). For a non-bare checkout we claim in place against the configured
+ * arbiter remote, unchanged. The returned `fromRepo` is what the job-worktree
+ * strategy then resolves the mirror off (the claim clone, or the checkout).
+ */
+async function claimAgainstRepo(opts) {
+    const { slug, repoPath, workspace, arbiter, env } = opts;
+    if (!isBareRepo(repoPath, env)) {
+        // In-place checkout: claim directly against the configured arbiter remote.
+        const claim = await performClaim({ slug, cwd: repoPath, arbiter, env });
+        return {
+            claim,
+            fromRepo: repoPath,
+            strategyArbiter: arbiter,
+            cleanup: () => { },
+        };
+    }
+    // Bare hub mirror (the registry): clone it into a throwaway claim dir and claim
+    // there against `origin` (the mirror URL = the arbiter). Keyed per slug so two
+    // in-flight jobs in the same mirror get DISTINCT claim clones (worktree
+    // isolation — no shared mutable state across in-flight jobs).
+    const mirrorUrl = runProcess('git', ['remote', 'get-url', 'origin'], repoPath, {
+        env,
+    }).stdout.trim();
+    const url = mirrorUrl !== '' ? mirrorUrl : `file://${repoPath}`;
+    const claimDir = join(workspace, 'claim', `${encodeRepoKey(url).split('/').join('__')}__${slug}`);
+    rmSync(claimDir, { recursive: true, force: true });
+    mkdirSync(dirname(claimDir), { recursive: true });
+    runProcess('git', ['clone', '--quiet', url, claimDir], dirname(claimDir), {
+        env,
+    });
+    const claim = await performClaim({
+        slug,
+        cwd: claimDir,
+        arbiter: 'origin',
+        env,
+    });
+    return {
+        claim,
+        fromRepo: claimDir,
+        // Inside the clone the arbiter is `origin` (the mirror URL).
+        strategyArbiter: 'origin',
+        cleanup: () => rmSync(claimDir, { recursive: true, force: true }),
+    };
+}
+/**
+ * Resolve the arbiter URL for `repoPath` PRE-CLAIM, the SAME way
+ * {@link claimAgainstRepo} derives the claim target. A BARE registry hub mirror's
+ * arbiter is its `origin` remote URL (falling back to `file://${repoPath}` when it
+ * has none); a working CHECKOUT's arbiter is the configured `arbiter` remote URL
+ * (falling back to `file://${repoPath}`). Used by the PR-INTENT pre-flight guard
+ * to know whether the arbiter is GitHub BEFORE the claim — it must not claim then
+ * refuse (that would strand the item in-progress on main). Read-only; mutates
+ * nothing.
+ */
+function arbiterUrlForRepo(opts) {
+    const { repoPath, arbiter, env } = opts;
+    const remote = isBareRepo(repoPath, env) ? 'origin' : arbiter;
+    const res = runProcess('git', ['remote', 'get-url', remote], repoPath, { env });
+    const url = res.status === 0 ? res.stdout.trim() : '';
+    return url !== '' ? url : `file://${repoPath}`;
+}
+/**
+ * Run one supervised tick: claim up to `maxParallel` eligible items
+ * (≤ `perRepoMax` per repo), run the agent on each in an isolated **job
+ * worktree** (the shared execution substrate — hub mirror + worktree + seams),
+ * gate on acceptance tests, rebase onto the latest arbiter main, and integrate
+ * the green ones. The runner owns EVERY git-state transition (claim, done-move,
+ * completion commit, integration); the agent only edits code. A lost race (claim
+ * exit 2) is skipped cleanly; failing work never reaches `work/done/`; a rebase
+ * conflict is aborted and routed to needs-attention (ADR §10).
+ */
+export async function runOnce(options) {
+    const config = options.config;
+    // Default discovery is the REGISTRY (the hub-mirror set, ADR §1) — the reframe
+    // that landed in `run-daemon-reframe` (work/done/). Callers that still operate
+    // on WORKING CHECKOUTS (the CLI / its tests) inject an explicit `report` built
+    // from working-tree paths ({@link scanRepoPaths}); without an injected report
+    // we fall back to the registry scan (async).
+    const report = options.report ?? (await scan(config, { override: options.override }));
+    const candidates = selectCandidates(report, {
+        maxParallel: config.maxParallel,
+        perRepoMax: config.perRepoMax,
+    });
+    // The launch harness: an explicit injection wins (tests); otherwise build the
+    // adapter the config selects (`harness: 'pi'` ⇒ the pi CLI; default ⇒ null,
+    // shelling out to `agentCmd`). pi specifics stay behind the seam.
+    const harness = options.harness ??
+        createHarness({ harness: config.harness, piBin: config.piBin });
+    // An explicitly-injected provider INSTANCE (tests / embedding) wins over
+    // per-item auto-detection; otherwise each item selects its own provider PURELY
+    // from its arbiter URL (see runOneItem). This is the resolved provider OBJECT,
+    // not a config override (there is none — the provider is arbiter-derived).
+    const provider = options.provider;
+    const workspace = options.workspace ?? config.workspacesDir;
+    const env = options.env;
+    // The per-repo claim serialiser: the ONLY shared-working-tree step in the
+    // otherwise-concurrent tick is the claim (it prepares its micro-commit in the
+    // repo's checkout/mirror). Two concurrent claims in ONE repo would corrupt each
+    // other's HEAD/index, so we serialise the CLAIM per repo (cheap — mv + commit +
+    // CAS push) while the agent run + the rebase-or-abort integration stay fully
+    // concurrent in each job's OWN worktree. Distinct repos claim in parallel.
+    const claimLock = createKeyedLock();
+    // The per-repo INTEGRATE serialiser — the SIBLING of `claimLock`, the same
+    // `createKeyedLock` primitive keyed on the same repo key. The land-on-`main`
+    // TAIL of merge-mode integration (fetch+rebase → `${branch}:main` push) is a
+    // shared-`main` step: two concurrent SAME-repo merge jobs both rebase onto the
+    // same pre-merge base and the loser's plain push is non-fast-forward (today it
+    // only works by benign timing). Serialising ONLY that tail per repo (the seam
+    // is applied INSIDE `performIntegration`, around step 4–5, NOT the whole call —
+    // the slow gate + Gate-2 review stay at the front, OUTSIDE the lock, so they
+    // run concurrently) makes the loser re-fetch + rebase onto the winner's
+    // now-advanced main, so its push is a clean fast-forward. Distinct repos
+    // integrate in parallel (per-repo key); a genuine same-repo code conflict
+    // routes exactly ONE job to needs-attention (it cannot both-land).
+    //
+    // This lock is the SIBLING-INTEGRATE serialiser ONLY. It does NOT cover the
+    // claim-vs-integrate race: a sibling same-repo CLAIM advances `<arbiter>/main`
+    // under the SEPARATE `claimLock` (above), which can land INSIDE this job's
+    // integrate push window. That is closed independently by the integrator's
+    // bounded re-rebase-and-retry on a non-fast-forward merge push (task
+    // `run-fleet-claim-integrate-and-sibling-rebase-concurrency-safe`, Race 1) — the
+    // two locks are NOT merged (merging would serialise the cheap claim behind the
+    // slow gated integrate, killing run's parallelism), the retry handles the
+    // cross-lock main-advance instead.
+    const integrateLock = createKeyedLock();
+    // GENUINELY CONCURRENT (ADR §3 — the whole point of `run`): run up to
+    // `maxParallel` `runOneItem`s IN FLIGHT at once, capped at `perRepoMax`
+    // concurrently per repo. The caps now bound ACTUAL in-flight execution, not just
+    // selection (this replaced the old `for (const c) { await runOneItem }` loop
+    // that ran selected candidates one-at-a-time). The substrate is parallel-ready —
+    // each slug → a distinct `work/<slug>` branch → a distinct job worktree, and the
+    // arbiter CAS serialises claims (a loser gets dropped) — so the only shared state
+    // across in-flight jobs is read-only config; each job owns its own worktree.
+    // Integration ordering is independent per job: each rebases-or-aborts onto a
+    // moving `<arbiter>/main` on its own, and a conflict routes only THAT job to
+    // needs-attention (the executor never lets one job's failure abort the others).
+    const settled = await runConcurrent({
+        items: candidates,
+        maxInFlight: config.maxParallel,
+        keyFor: (candidate) => candidate.repoPath,
+        perKeyMax: config.perRepoMax,
+        worker: (candidate) => runOneItem(candidate, {
+            config,
+            override: options.override,
+            workspace,
+            dorfl: options.dorfl,
+            harness,
+            reviewGate: options.reviewGate,
+            provider,
+            ghCanOpenPr: options.ghCanOpenPr,
+            openPr: options.openPr,
+            env,
+            onWarn: options.onWarn,
+            backoff: options.backoff,
+            sleep: options.sleep,
+            claimLock,
+            integrateLock,
+        }),
+    });
+    // `runOneItem` is total (it maps every failure to an `ItemResult` and never
+    // throws), so a captured `{error}` slot is a defensive last resort — surface it
+    // as a claim-error item rather than crashing the whole tick.
+    const items = settled.map((slot, i) => 'ok' in slot
+        ? slot.ok
+        : {
+            repoPath: candidates[i].repoPath,
+            slug: candidates[i].slug,
+            status: 'claim-error',
+            detail: slot.error?.message ?? String(slot.error),
+        });
+    const claimedAndDone = items.filter((i) => i.status === 'claimed-done').length;
+    const skipped = items.filter((i) => i.status === 'lost-race' || i.status === 'claim-contended').length;
+    const needsAttention = items.filter((i) => i.status === 'tests-failed' ||
+        i.status === 'needs-attention' ||
+        i.status === 'agent-stopped').length;
+    const failed = items.filter((i) => i.status === 'tests-failed' ||
+        i.status === 'needs-attention' ||
+        i.status === 'agent-stopped' ||
+        i.status === 'agent-failed' ||
+        // The FAILURE-CAUSE refinements of `agent-failed` count the SAME way (they
+        // are the same agent/run-failure routed to needs-attention, just labelled
+        // by cause).
+        i.status === 'transient-infra' ||
+        i.status === 'config-error' ||
+        // The surface to needs-attention did NOT land (lost the CAS race); the item
+        // is still in-progress on the arbiter — a genuine FAILURE (not a clean
+        // needs-attention), so it counts as failed, NOT in `needsAttention`.
+        i.status === 'surface-unmoved' ||
+        i.status === 'claim-error').length;
+    return { claimedAndDone, skipped, failed, needsAttention, items };
+}
+async function runOneItem(candidate, ctx) {
+    const { slug, repoPath } = candidate;
+    const base = { repoPath, slug, status: 'lost-race' };
+    // Resolve THIS repo's effective config against its own `.dorfl.json`
+    // layered over the global config (flag > per-repo > global > default). Each
+    // repo gets its own integration mode / arbiter, so repo A can be `merge`
+    // while repo B is `propose` in one tick.
+    const resolved = resolveRepoConfig({
+        repoPath,
+        global: ctx.config,
+        override: ctx.override,
+    });
+    const config = resolved.config;
+    if (resolved.message) {
+        ctx.onWarn?.(resolved.message);
+    }
+    // The IDENTITY env for this repo's GIT + provider operations (claim, push,
+    // integration, `gh`). Derived from the host-only `config.identity` (absent ⇒
+    // `ctx.env` unchanged, byte-for-byte ambient). This is the INTEGRATION-PATH
+    // env ONLY: the agent launch keeps the plain ambient `ctx.env` (the runner,
+    // not the agent, acts as the configured identity — design point 4). The push-
+    // time transport-coherence guard (`assertTransportAllowed`) fires before the
+    // integration push (where the arbiter URL is known), turning a forbidden
+    // transport into a clear error, never a silent wrong-account push.
+    let gitEnv;
+    try {
+        gitEnv = identityEnv(config.identity, ctx.env ?? process.env);
+    }
+    catch (err) {
+        // A configured identity that cannot be resolved (e.g. `tokenEnv` names an
+        // unset env var) is a CONFIG error — fail THIS item cleanly (surfaced), never
+        // crash the tick or silently fall back to an ambient credential.
+        const message = err.message;
+        ctx.onWarn?.(message);
+        return { ...base, status: 'config-error', detail: message };
+    }
+    // A per-ITEM context carrying `gitEnv` so the needs-attention save helpers
+    // (`saveAgentFailure`/`saveAgentStop`) push under the identity too. We rebind a
+    // COPY (never mutate the shared tick `ctx` — items run concurrently).
+    ctx = { ...ctx, gitEnv };
+    // 0. PR-INTENT pre-flight guard — the AUTONOMOUS mirror of in-place `performDo`
+    //    step 3c. The SAME predicate, run UP FRONT here (per-repo config resolved,
+    //    BEFORE the claim) so a `propose` item on a GitHub arbiter that INTENDS a PR
+    //    (`noPR` unset) fails fast when `gh` genuinely cannot open one, instead of
+    //    letting integration silently degrade to manual-PR instructions. CRITICAL: the
+    //    probe runs BEFORE the claim — claiming then refusing would strand the item
+    //    in-progress on main (the claim precedes `prepare()`). The arbiter URL is
+    //    derived from `repoPath` the SAME way `claimAgainstRepo` derives the claim
+    //    target (`arbiterUrlForRepo`). The PROBE is the signal, NOT a config check —
+    //    an absent `providers.github` identity falls back to AMBIENT `gh` auth (the
+    //    probe reports it available), so a working ambient setup PROCEEDS. A true
+    //    result returns a CLEAN PRE-CLAIM item result on the `config-error` failure-
+    //    cause status (a wiring/config failure, NOT a task fault), with NO claim,
+    //    build, or half-built needs-attention surface — and it never crashes the tick
+    //    or aborts siblings (the result is returned; `runConcurrent` continues).
+    //    REUSES the predicate + message so the in-place + autonomous paths cannot
+    //    drift.
+    {
+        const arbiterUrl = arbiterUrlForRepo({
+            repoPath,
+            arbiter: config.defaultArbiter,
+            env: gitEnv,
+        });
+        const probe = ctx.ghCanOpenPr ??
+            ((probeCwd, probeEnv) => new GitHubProvider().available(probeCwd, probeEnv));
+        if (shouldFailProposePrIntent({
+            mode: config.integration,
+            arbiterIsGitHub: isGitHubArbiterUrl(arbiterUrl),
+            noPR: config.noPR,
+            ghCanOpenPr: () => probe(repoPath, gitEnv),
+        })) {
+            return {
+                ...base,
+                status: 'config-error',
+                detail: PROPOSE_PR_INTENT_GH_UNAVAILABLE_MESSAGE,
+            };
+        }
+    }
+    // 0b. STATIC fresh-worktree-gate readiness guard — the fleet mirror of
+    //     `performDo` step 3d / `performDoRemote` step 1c (task
+    //     `do-fails-fast-when-acceptance-gate-statically-unrunnable`). When the
+    //     fresh-worktree gate is ON AND `prepare` resolves to no commands AND a
+    //     lockfile is present in the repo, the throwaway worktree the gate runs in
+    //     will have no installed deps, so the gate cannot run. Fail this item
+    //     CLEANLY before the claim (no claim, no isolate, no agent, no surface) so a
+    //     fleet tick never burns a build to discover a STATIC config gap and never
+    //     routes correct work to needs-attention for this reason. Surfaced on the
+    //     same `config-error` axis the PR-intent guard above uses (a wiring/config
+    //     fault, not a task fault). The repo discovery is either a working checkout
+    //     (in-place tests) OR a BARE hub mirror (production fleet); detect the
+    //     lockfile from whichever shape `repoPath` is. Deps-only — there is no
+    //     verify-unset case (the gate substitutes `DEFAULT_VERIFY_COMMAND`).
+    {
+        const lockfile = detectLockfileOnDisk(repoPath) ??
+            detectLockfileOnMirrorMain(repoPath, gitEnv);
+        const guard = checkGatePreconditions({
+            freshWorktreeGate: config.freshWorktreeGate,
+            prepare: config.prepare,
+            lockfile,
+        });
+        if (guard !== undefined) {
+            return { ...base, status: 'config-error', detail: guard.message };
+        }
+    }
+    // 1. Claim (the runner's first git-state transition) via the in-process CAS.
+    //    `claimAgainstRepo` handles BOTH discovery shapes: a working CHECKOUT (the
+    //    in-place test/`do` path — claim directly) and a BARE registry hub mirror
+    //    (`run`'s production discovery — claim in a throwaway clone, since a bare
+    //    repo cannot `git mv`/`git commit`; the SAME pattern `do --remote` uses). It
+    //    returns the `fromRepo`/`strategyArbiter` the worktree strategy resolves its
+    //    mirror off (kept alive until AFTER prepare). `performClaim` is async, so two
+    //    awaited claims over one slug genuinely race — the arbiter ref-CAS picks the
+    //    winner.
+    const doClaim = () => claimAgainstRepo({
+        slug,
+        repoPath,
+        workspace: ctx.workspace,
+        arbiter: config.defaultArbiter,
+        env: gitEnv,
+    });
+    // Serialise the claim PER REPO (it prepares its micro-commit in a checkout/clone
+    // of the repo) so two in-flight jobs in the same repo do not stomp on each
+    // other; the arbiter CAS then picks the winner across machines. Different repos
+    // (and everything AFTER the claim) run concurrently.
+    const repoClaim = ctx.claimLock
+        ? await ctx.claimLock(repoPath, doClaim)
+        : await doClaim();
+    const claim = repoClaim.claim;
+    if (claim.outcome === 'lost') {
+        repoClaim.cleanup();
+        return { ...base, status: 'lost-race' };
+    }
+    if (claim.outcome === 'contended') {
+        repoClaim.cleanup();
+        return { ...base, status: 'claim-contended' };
+    }
+    if (claim.outcome === 'usage-error') {
+        repoClaim.cleanup();
+        return { ...base, status: 'claim-error', detail: claim.message };
+    }
+    // 2. Isolate via the isolation-strategy seam (ADR §3). `run` always selects
+    //    the JOB-WORKTREE strategy: materialise the hub mirror + cut a per-job
+    //    worktree off the freshly-fetched `<hub>/main` in the agents' area
+    //    (ADR §1/§2). The seam yields a UNIFORM HANDLE (dir/branch/arbiterRemote/
+    //    arbiterUrl + a strategy-appropriate teardown) that the post-claim pipeline
+    //    below reads from — never a concrete `Job` — so the SAME steps serve the
+    //    in-place strategy too (wired by `do-in-place`). The mirror is keyed off
+    //    the arbiter URL resolved from this repo, so jobs reuse it (fetch, not
+    //    re-clone) across the run.
+    const strategy = jobWorktreeStrategy({
+        // In-place: the checkout. Bare-mirror: the throwaway claim CLONE (still alive)
+        // — the strategy resolves the mirror URL off it at prepare time, then we drop it.
+        fromRepo: repoClaim.fromRepo,
+        arbiter: repoClaim.strategyArbiter,
+        workspacesDir: ctx.workspace,
+    });
+    let tree;
+    try {
+        tree = strategy.prepare({ slug, env: gitEnv });
+        // The claim clone (bare-mirror path) has done its job: the mirror is
+        // materialised + the worktree cut. Drop it (no-op for the in-place path).
+        repoClaim.cleanup();
+        // 2a. CONTINUE rebase conflict (ADR §14 + §10): a requeue kept a
+        //     `work/<slug>` whose commits did not replay cleanly onto the current
+        //     main at onboard-time (aborted, never auto-resolved). Route the item to
+        //     needs-attention TREE-LESSLY via the SAME `#89` mechanism `requeue` uses
+        //     for the reverse direction — the rebase was ABORTED, so this worktree's
+        //     `work/<slug>` tip == the arbiter tip (the kept branch, unchanged,
+        //     after-commit). The DURABLE artifact is that branch on the arbiter + the
+        //     main surface (ADR §14: the job worktree is a disposable cache; recovery
+        //     flows through the branch + folder-native surfaces, NOT by editing the
+        //     worktree). So the surface is purely the one-file `in-progress/ →
+        //     needs-attention/` ledger move + reason — no branch push, no worktree
+        //     mutation. Because the branch is provably on the arbiter, the §4 reap
+        //     predicate still HOLDS and this worktree is reaped — more §14-aligned.
+        if (tree.continueRebaseConflict) {
+            const reason = `continuing the kept ${tree.branch}: rebase onto the latest main ` +
+                'conflicted (aborted, never auto-resolved) — resolve against the latest ' +
+                'main, or `requeue --reset` to discard and start fresh';
+            updateJobRecord(tree.dir, { state: 'needs-attention', reason });
+            const surfaced = await ledgerWrite.applyTreelessNeedsAttentionTransition({
+                cwd: tree.dir,
+                slug,
+                reason,
+                arbiter: tree.arbiterRemote,
+                env: gitEnv,
+            });
+            if (!surfaced.moved) {
+                return surfaceUnmovedItemResult({ base, tree, slug, reason, surfaced });
+            }
+            return { ...base, status: 'needs-attention', detail: reason };
+        }
+        // 2b. CONTINUE reconcile-push TERMINAL failure (the stale-lease-strand bug):
+        //     the onboard reconcile push of the kept (already-committed) work branch
+        //     FAILED terminally (stale-lease cap exhausted, or a non-stale-lease
+        //     rejection / unreachable arbiter). The push helper THROWS; `createJob`
+        //     CATCHES it and flags `continuePushFailure` so the tick does NOT crash
+        //     leaving the task silently in-progress on the arbiter. Surface to
+        //     needs-attention TREE-LESSLY via the SAME `#89` mechanism `requeue` uses —
+        //     the kept branch already on the arbiter from the prior requeue
+        //     (after-commit, recoverable), so the surface is purely the one-file ledger
+        //     move + reason (no branch push, no worktree) — instead of running the agent.
+        if (tree.continuePushFailure !== undefined) {
+            const reason = `continuing the kept ${tree.branch}: publishing the rebased work branch ` +
+                `to the arbiter failed terminally (${tree.continuePushFailure}) — the ` +
+                'kept branch is left intact on the arbiter (recoverable); `requeue` to ' +
+                'retry once the churn settles, or `requeue --reset` to discard and start ' +
+                'fresh';
+            updateJobRecord(tree.dir, { state: 'needs-attention', reason });
+            const surfaced = await ledgerWrite.applyTreelessNeedsAttentionTransition({
+                cwd: tree.dir,
+                slug,
+                reason,
+                arbiter: tree.arbiterRemote,
+                env: gitEnv,
+            });
+            if (!surfaced.moved) {
+                return surfaceUnmovedItemResult({ base, tree, slug, reason, surfaced });
+            }
+            return { ...base, status: 'needs-attention', detail: reason };
+        }
+        // 3. Build the prompt — the SAME dual-use assembly `dorfl prompt`
+        //    emits: the canonical wrapper (+ source prd) + the task's ## Prompt.
+        let prompt;
+        try {
+            // CONTINUE-aware resolution: only on a continue (the job continued a kept
+            // arbiter `work/<slug>`) may the task already be in `work/done/`; admit
+            // `done/` ONLY behind the tip-vs-arbiter stranded gate (story 5). In a bare
+            // hub mirror's worktree the refs are the LOCAL heads `work/<slug>` / `main`.
+            const task = resolveTask(tree.dir, slug, tree.continued
+                ? {
+                    cwd: tree.dir,
+                    branchRef: tree.branch,
+                    mainRef: 'main',
+                    env: gitEnv,
+                }
+                : undefined);
+            // CONTINUE-mode (the `agent-prompt-continue-context` task): when the job
+            // CONTINUED a kept arbiter `work/<slug>` (a requeue), inject the continue
+            // block (prior diff + reason + handoff note). REUSE the SAME continue-
+            // detection — in a bare hub mirror's worktree the refs are the LOCAL heads
+            // `work/<slug>` and `main` (after `ensureMirror`'s mirror-style fetch).
+            const continueContext = tree.continued
+                ? resolveContinueContext({
+                    cwd: tree.dir,
+                    slug,
+                    arbiter: tree.arbiterRemote,
+                    branchRef: tree.branch,
+                    mainRef: 'main',
+                    content: readFileSync(task.path, 'utf8'),
+                    env: gitEnv,
+                })
+                : undefined;
+            // Thread the resolved per-repo nudge through the per-item override layer
+            // (a task or prd may pin `promptGuidance.testFirst` in its frontmatter,
+            // superseding the repo policy for THIS item) before the wrapper is built.
+            const itemGuidance = resolvePromptGuidanceForItem({
+                cwd: tree.dir,
+                repoResolved: resolvePromptGuidance(config),
+                taskContent: readFileSync(task.path, 'utf8'),
+            });
+            prompt = buildAgentPrompt(task.slug, task.prd, task.taskPrompt, {
+                cwd: tree.dir,
+                continueContext,
+                promptGuidance: itemGuidance,
+            });
+        }
+        catch (err) {
+            if (err instanceof PromptError) {
+                return await saveAgentFailure(base, tree, slug, err.message, ctx);
+            }
+            throw err;
+        }
+        // 4. Run the agent — via the injected runner (tests) or the harness seam
+        //    (null adapter by default), shelling out to the configured agentCmd. The
+        //    resolved per-repo `model` (ADR §13) flows through the seam to the adapter;
+        //    a `{model}`-in-agentCmd misconfiguration surfaces as agent-failed.
+        let agent;
+        try {
+            agent = runAgent(ctx, tree, prompt, slug, config.agentCmd, config.model, config.sessionsDir);
+        }
+        catch (err) {
+            return await saveAgentFailure(base, tree, slug, err.message, ctx);
+        }
+        if (!agent.ok) {
+            return await saveAgentFailure(base, tree, slug, agent.detail ?? `the agent failed to build '${slug}'.`, ctx);
+        }
+        // 4b. HONOR a deliberate STOP (task `agent-stop-signal`) — the SAME detection
+        //     in-place/remote `do` run, mirrored here. The agent exited cleanly but the
+        //     CLAIM-PROTOCOL wrapper tells it to STOP on a DRIFTED/ambiguous task; an
+        //     in-band sentinel carries its reason VERBATIM, and the empty-diff backstop
+        //     catches a stop without one. Either routes to needs-attention (surfaced on
+        //     the arbiter) and SKIPS the gate + Gate-2 (the whole `performIntegration`
+        //     band) — a clean STOP is NOT "a build that changed nothing".
+        const sentinel = parseStopSentinel(agent.output);
+        const stopReason = sentinel !== undefined
+            ? sentinel.reason
+            : (await isWorkBranchDiffEmpty({
+                cwd: tree.dir,
+                arbiter: tree.arbiterRemote,
+                env: gitEnv,
+            }))
+                ? emptyDiffStopReason(slug)
+                : undefined;
+        if (stopReason !== undefined) {
+            return await saveAgentStop(base, tree, slug, stopReason, ctx);
+        }
+        // 5–7 (CONVERGED). The whole gate → review → done-move → commit → rebase →
+        // integrate band — plus the needs-attention routing on any failure — now runs
+        // through the SHARED `performIntegration` core (`integration-core.ts`, the
+        // run/do convergence prd). `run` no longer forks its own gate / done-move /
+        // completion commit / `Integrator`+`integrateWithRebase`: that closed all
+        // three drift instances at once (the fleet now gets the review gate, the PR
+        // title/body, AND the per-repo language-agnostic `verify` gate instead of the
+        // old test-only `pnpm -r test` floor). The HEAD above (claim, isolate, agent,
+        // failure-save) and the TAIL below (job record + worktree reap) stay here;
+        // the band is what they share. `run` is ALWAYS autonomous, so it ALWAYS
+        // passes `surfaceArbiter` (every failure surfaces on the arbiter's main +
+        // pushes the branch). The injected `openPr` legacy bridge is forwarded to the
+        // core unchanged; absent it the core selects the provider PURELY from the
+        // arbiter URL (a GitHub remote ⇒ `gh pr create`). The per-repo `noPR` INTENT
+        // (suppress the PR) rides separately — it does not pick a provider.
+        //
+        // `performIntegration` THROWS a plain `Error` for a misconfigured gate
+        // (`review` on with no `reviewGate` wired) — `run`'s CLI always wires one when
+        // `config.review` is on, so that is a defensive case, but it must NOT crash
+        // the whole tick. We catch it and route the item through the same
+        // work-preserving needs-attention seam an agent failure uses (`saveAgentFailure`)
+        // so the worktree is handled and the run continues to the next item.
+        // Push-time transport-coherence guard (identity feature): refuse a forbidden
+        // transport for THIS arbiter's actual URL rather than silently pushing under
+        // an ambient credential. A no-op when no identity is configured.
+        try {
+            assertTransportAllowed(config.identity, tree.arbiterUrl);
+        }
+        catch (err) {
+            return await saveAgentFailure(base, tree, slug, err.message, ctx);
+        }
+        let core;
+        try {
+            core = await performIntegration({
+                cwd: tree.dir,
+                // The arbiter remote name valid inside the isolated tree (job-worktree:
+                // the mirror's clone remote `origin`), NOT the source repo's
+                // `defaultArbiter` name.
+                arbiter: tree.arbiterRemote,
+                slug,
+                // Claim no longer moves the body (task
+                // `cutover-claim-body-stays-and-complete-sources-from-backlog`): a
+                // freshly-built task RESTS in `tasks/ready/` on `main`, so the done-move
+                // sources from there.
+                source: 'tasks-ready',
+                recovering: false,
+                // `run` is ALWAYS autonomous → surface every failure on the arbiter's
+                // main AND push the work branch (DATA, not a caller-identity flag).
+                surfaceArbiter: tree.arbiterRemote,
+                // The per-repo, language-agnostic gate (ADR §8) — the protocol-conformance
+                // fix: `run` now honours `config.verify` instead of the deleted
+                // `defaultTestGate`'s hardcoded `pnpm -r test`.
+                verify: config.verify,
+                // The per-repo ENV-PREP step (`prepare`), sequenced ONCE before the first
+                // `verify` on the fresh job worktree so it has deps (a fresh worktree off
+                // the mirror has no `node_modules`). Unset ⇒ a no-op; never baked into verify.
+                prepare: config.prepare,
+                // FRESH-WORKTREE GATE (task `gate-on-rebased-tip-fresh-worktree`): run the
+                // acceptance gate against the REBASED tip in a clean throwaway worktree (the
+                // tree that integrates) so a green gate provably describes the merged
+                // artifact. Passed UNCONDITIONALLY (the resolved flag) at ANY `perRepoMax`:
+                // the two PRE-EXISTING run-fleet same-repo races the gate's latency used to
+                // make deterministic are now CLOSED on their own merits (task
+                // `run-fleet-claim-integrate-and-sibling-rebase-concurrency-safe`) — RACE 1
+                // (claim-vs-integrate non-fast-forward push) by the integrator's bounded
+                // re-rebase-and-retry on the merge push, RACE 2 (sibling-slug divergent-base
+                // ledger rebase) by the step-4 sibling-ledger reconciliation arm — so the
+                // `perRepoMax === 1` downgrade is REMOVED and the fresh rebased-tip gate runs
+                // on the `run` fleet at any same-repo parallelism. Single-job callers
+                // (`do`/`--isolated`/`--remote`/`complete`) already pass it unconditionally.
+                freshWorktreeGate: config.freshWorktreeGate,
+                // The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) —
+                // the git-alone FLOOR of the cross-job land queue (prd `land-time-reverify-
+                // and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)). Threaded
+                // from the per-repo resolved config so a wide-matrix CI's raised cap actually
+                // reaches the merge loop — across separate `run` fleet jobs the CAS loop IS
+                // the queue (`integrateLock` only serialises sibling integrates in ONE process).
+                mergeRetries: config.mergeRetries,
+                // Gate 2 (PR/code review): the per-repo resolved flags ride from `config`;
+                // only the gate SEAM is threaded through `ctx` (the CLI wires the prod
+                // `harnessReviewGate()` only when `config.review` is on).
+                review: config.review,
+                reviewModel: config.reviewModel,
+                reviewMaxRounds: config.reviewMaxRounds,
+                reviewGate: ctx.reviewGate,
+                mode: config.integration,
+                // PR-INTENT: the per-repo `noPR` (suppress the PR even on an authed GitHub
+                // arbiter). NOT a provider choice — the provider is purely arbiter-derived.
+                noPR: config.noPR,
+                // Provider: an injected `openPr` wins (legacy test bridge); otherwise the
+                // core selects PURELY from the arbiter URL (a GitHub remote ⇒ `gh pr
+                // create`, else push-only `none`). `providerInstance` (the resolved object
+                // the `run` seam injects) STAYS — it is a DIFFERENT `provider`.
+                providerInstance: ctx.provider,
+                openPr: ctx.openPr,
+                // The per-repo INTEGRATE serialiser (sibling of the claim lock): the
+                // core applies it around ONLY the rebase-to-integrate TAIL, keyed on
+                // the repo path (the same key the claim lock uses), so two same-repo
+                // merge jobs land on `main` one-at-a-time. Absent on single-job paths.
+                integrateLock: ctx.integrateLock,
+                integrateLockKey: repoPath,
+                // Half A/B: the synthesised single-line title + the agent's surfaced
+                // final summary as the PR body (the core scaffolds the task-pointer
+                // header). `title` is synthesised inside the core from the task's
+                // frontmatter; `body` is the agent output (undefined ⇒ `--fill`).
+                body: agent.output,
+                env: gitEnv,
+                // The review AGENT (Gate 2) launches AMBIENT — never the identity env
+                // (an agent must not act as the bot; only the runner's git ops do).
+                agentEnv: ctx.env,
+            });
+        }
+        catch (err) {
+            // A thrown core error (misconfigured gate, or an unexpected plumbing
+            // failure) — SAVE the work + route to needs-attention, never crash the tick.
+            return await saveAgentFailure(base, tree, slug, err.message, ctx);
+        }
+        // TAIL: map the core's DATA outcome onto the job record + `ItemStatus`. The
+        // core already ran the gate/review/move/commit/rebase/integrate AND did the
+        // needs-attention routing; `run`'s tail does ONLY the job-record write + (in
+        // `finally`) the worktree reap. `run` NEVER switches/ff/deletes branches
+        // (that is `do`'s in-place tail; a job worktree is reaped, not switched).
+        if (core.outcome === 'gate-failed') {
+            updateJobRecord(tree.dir, {
+                state: 'needs-attention',
+                reason: core.reason,
+            });
+            return { ...base, status: 'tests-failed', detail: core.reason };
+        }
+        if (core.outcome === 'review-unparseable') {
+            // Gate 2 RAN but its verdict was UNPARSEABLE (malformed JSON). The core already
+            // routed it work-preservingly (branch pushed + surfaced). FAILURE-CAUSE axis,
+            // NOT a reviewer block: classify the parse-failure phrase the core recorded →
+            // `transient-infra` (re-run the SAME work — the stochastic gate + the parser's
+            // repair pass make a re-run far more likely to parse), the SAME
+            // `classifyFailureCause` `do` uses, so the cross-path label agrees. The job
+            // record carries the classified status; the worktree is retained by the §4 reap.
+            const cause = classifyFailureCause(core.reason);
+            updateJobRecord(tree.dir, {
+                state: 'needs-attention',
+                reason: core.reason,
+            });
+            return {
+                ...base,
+                status: failureCauseToItemStatus(cause),
+                detail: core.reason,
+            };
+        }
+        if (core.outcome === 'prepare-failed' ||
+            core.outcome === 'review-blocked' ||
+            core.outcome === 'rebase-conflict' ||
+            core.outcome === 'invariant-violation') {
+            // `prepare-failed`: the env-prep (install) step was red, so the env could
+            // not be made ready and `verify` was NOT run — distinct from a `tests-failed`
+            // red gate. Route it to needs-attention like the others (a human fixes the
+            // prepare command, then re-runs); the core already surfaced the bounce.
+            // `invariant-violation`: the one-slug-one-folder guard FAILED LOUD (the
+            // arbiter already holds the slug in >1 status folder — a corrupt ledger).
+            // The core integrated NOTHING. On the LEAST-supervised caller this MUST
+            // NOT fall through to the SUCCESS branch (state:'done' / 'claimed-done'
+            // with no prUrl) — that would misreport a refusal as a completed job, the
+            // opposite of fail-loud. Route it to needs-attention like a rebase conflict
+            // (a human resolves the duplicate, then re-runs); `complete.ts` mirrors this
+            // refusal with exit 1.
+            updateJobRecord(tree.dir, {
+                state: 'needs-attention',
+                reason: core.reason,
+            });
+            return { ...base, status: 'needs-attention', detail: core.reason };
+        }
+        // SUCCESS: the core integrated. Record the PR/MR URL (when a provider opened
+        // one) on the job, surfaced by `status`.
+        const prUrl = core.integration?.url;
+        updateJobRecord(tree.dir, { state: 'done', prUrl });
+        return { ...base, status: 'claimed-done', integration: core.integration };
+    }
+    finally {
+        // Strategy-appropriate teardown via the uniform handle (ADR §4). Job-worktree:
+        // re-apply the provably-safe deletion predicate and remove the worktree ONLY
+        // if it holds (clean tree AND the branch tip reachable on the arbiter — merged
+        // or pushed). One rule, no done-vs-failed special-casing: a claimed-done job
+        // is on the arbiter → reaped; a tests-failed / needs-attention / un-pushed job
+        // is NOT → retained (the worktree is the needs-attention signal; `gc` catches
+        // up). In-place: a NO-OP (the checkout is never reaped). NEVER `--force` here.
+        if (tree) {
+            tree.teardown();
+        }
+    }
+}
+/**
+ * Run the agent against the isolated tree. Prefers the injected `dorfl`
+ * (tests / custom embeddings); otherwise launches `agentCmd` through the harness
+ * seam (recording the PID in the job's harness block, when there is one).
+ */
+function runAgent(ctx, tree, prompt, slug, agentCmd, model, sessionsDir) {
+    if (ctx.dorfl) {
+        return ctx.dorfl({ cwd: tree.dir, prompt, slug, env: ctx.env });
+    }
+    // Generate the full pi session-FILE path (task `session-path-pi-default`):
+    // `<sessionsDir>/<work-id>-<unique>.jsonl`, or pi's per-cwd default folder when
+    // `sessionsDir` is unset. The work-id (arbiter URL + slug) is `run`'s natural
+    // unique-per-claim id. Threaded through the seam so the pi adapter passes
+    // `--session <path>` (never `--session-dir` into the worktree).
+    const session = generateSessionPath({
+        sessionsDir,
+        cwd: tree.dir,
+        id: encodeWorkId(tree.arbiterUrl, slug),
+    });
+    const launched = ctx.harness.launch({
+        dir: tree.dir,
+        slug,
+        command: agentCmd,
+        prompt,
+        // The model routing intent (ADR §13) — the adapter decides HOW it reaches
+        // its tool (pi: `--model`; null/shell: `{model}` placeholder).
+        model,
+        session,
+        env: ctx.env,
+    });
+    updateJobRecord(tree.dir, { harness: launched.record });
+    // Surface the agent's FINAL SUMMARY (`LaunchResult.output`) — the source channel
+    // for the propose-mode PR body — instead of dropping it (mirrors `do`'s
+    // `runDoAgent`). Absent (no parseable assistant text) ⇒ undefined ⇒ `--fill`.
+    return { ok: launched.ok, detail: launched.detail, output: launched.output };
+}
+/**
+ * SAVE the partial work of a FAILED agent instead of dropping it (closing the
+ * fifth-and-last instance of the recurring asymmetry —
+ * `work/notes/observations/run-agent-failure-does-not-save-work.md`). `run`'s
+ * agent-failure return points (prompt-assembly fail / `runAgent` throw /
+ * `agent.ok === false`) used to BARE-RETURN `agent-failed`, leaving whatever the
+ * agent edited only on the LOCAL work branch in the (disposable, possibly remote)
+ * job worktree — not on the arbiter, so a requeue-continue on a DIFFERENT machine
+ * (or after a `gc` reap) re-cut fresh off main and orphaned it.
+ *
+ * This mirrors `do.ts`'s `saveAgentFailure`: route the failure through the SAME
+ * ledger write seam's needs-attention transition the gate-fail / integrate-
+ * conflict bounces use — which (with the arbiter) saves the agent's work as a wip
+ * commit, `git mv`s the item to needs-attention/ with the failure detail recorded
+ * as the reason, surfaces the move-only commit on the arbiter's `main`
+ * (OBSERVABLE), AND pushes the `work/<slug>` branch (RECOVERABLE — the durable
+ * artifact a requeue-continue lands the next agent on; continue-detection reads
+ * <arbiter>/work/<slug> ahead of main). The push is best-effort — an unreachable
+ * arbiter leaves the retained worktree + the local commits standing (the genuinely
+ * un-pushed case). The status is the classified failure CAUSE (`transient-infra` /
+ * `config-error` where knowable, else the conservative generic `agent-failed`);
+ * only the work-preserving side-effect now matches the gate-fail path.
+ */
+async function saveAgentFailure(base, tree, slug, detail, ctx) {
+    // Classify the failure CAUSE (best-effort + conservative) from the surfaced
+    // detail via the SAME `classifyFailureCause` `do` uses — so a thrown CORE config/
+    // wiring error reads as `config-error` (NOT `agent-failed`) on BOTH paths, closing
+    // the cross-path divergence; a harness-surfaced model/connection outage reads as
+    // `transient-infra`; an unrecognised cause stays the generic `agent-failed`. The
+    // cause LABEL prefixes the recorded reason so the cause is legible on the
+    // needs-attention route; `agent-failed` keeps the historical "agent failed:"
+    // prefix (no reason-prose regression).
+    const cause = classifyFailureCause(detail);
+    const reason = `${failureCauseLabel(cause)}: ${detail}`;
+    updateJobRecord(tree.dir, { state: 'needs-attention', reason });
+    await ledgerWrite.applyNeedsAttentionTransition({
+        cwd: tree.dir,
+        slug,
+        reason,
+        // Autonomous (`run`): surface on the arbiter's main AND push the work branch
+        // (the seam does both now), so the fleet's failed-agent work is cross-machine
+        // recoverable via requeue-continue. The route is fault-tolerant: a git outage
+        // is retried with bounded backoff then gives up cleanly (never hangs the tick).
+        arbiter: tree.arbiterRemote,
+        env: ctx.gitEnv ?? ctx.env,
+        backoff: ctx.backoff,
+        sleep: ctx.sleep,
+    });
+    return { ...base, status: failureCauseToItemStatus(cause), detail };
+}
+/**
+ * Map a {@link FailureCause} onto the `run` {@link ItemStatus}. The cause names
+ * ARE the status names (the FAILURE-CAUSE axis reuses the terminal vocabulary), so
+ * this is identity — a single helper documents the mapping + keeps the `do`/`run`
+ * sites symmetric (`do` has the twin `failureCauseToDoOutcome`).
+ */
+function failureCauseToItemStatus(cause) {
+    return cause;
+}
+/**
+ * Build the HONEST {@link ItemResult} for a CONTINUE-site surface that did NOT
+ * land on the arbiter (`{moved: false}`). The tree-less `in-progress/ →
+ * needs-attention/` move lost the CAS race against a busy arbiter (its
+ * contention-retry cap exhausted) or had no arbiter to publish to, so the item is
+ * STILL in-progress on the arbiter — reporting a clean `needs-attention` would
+ * mislead (it claims the surface landed, when it did not). The DISTINCT
+ * `surface-unmoved` status carries `reasonNotMoved` so the caller/human can tell
+ * it apart from a successful surface and retry/resolve.
+ *
+ * The local job record was set to `state: 'needs-attention'` (its LOCAL intent,
+ * recorded regardless of the arbiter move) right before the surface; on a
+ * `moved: false` we OVERWRITE its reason so that local record does not
+ * confusingly claim a landed surface either.
+ */
+function surfaceUnmovedItemResult(params) {
+    const { base, tree, slug, reason, surfaced } = params;
+    const detail = `'${slug}' could NOT be surfaced to needs-attention — the surface did not ` +
+        `reach the arbiter's main; the item is still IN-PROGRESS on the arbiter ` +
+        `(retry/resolve). ${surfaced.reasonNotMoved ?? reason}`;
+    updateJobRecord(tree.dir, { state: 'needs-attention', reason: detail });
+    return { ...base, status: 'surface-unmoved', detail };
+}
+/**
+ * Route a DELIBERATE agent STOP (task `agent-stop-signal`) to needs-attention
+ * through the SAME work-preserving seam `saveAgentFailure` uses, but as the
+ * DISTINCT `agent-stopped` status (NOT `agent-failed` — the agent did not error;
+ * NOT `tests-failed`/`needs-attention` — there was no red gate / rebase conflict).
+ * The agent's STOP reason is recorded VERBATIM; the job record names it honestly.
+ * The `performIntegration` band (gate + Gate-2) is NEVER reached.
+ */
+async function saveAgentStop(base, tree, slug, reason, ctx) {
+    updateJobRecord(tree.dir, { state: 'needs-attention', reason });
+    await ledgerWrite.applyNeedsAttentionTransition({
+        cwd: tree.dir,
+        slug,
+        reason,
+        // Autonomous (`run`): surface on the arbiter's main AND push the work branch
+        // (the seam does both), so the stopped item is cross-machine visible/recoverable.
+        arbiter: tree.arbiterRemote,
+        env: ctx.gitEnv ?? ctx.env,
+        backoff: ctx.backoff,
+        sleep: ctx.sleep,
+    });
+    return { ...base, status: 'agent-stopped', detail: reason };
+}
+/** A throwaway default workspace under the OS temp dir (CLI convenience). */
+export function defaultRunWorkspace() {
+    return join(tmpdir(), 'dorfl-workspace');
+}
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * `run` (no flag) — the cross-repo, parallel, **forever-looping daemon** (ADR §3):
+ * loop the supervised concurrent tick over the registry until a stop bound
+ * (max-iterations / max-duration / a stop signal) or forever (the future system
+ * service). Each tick claims + runs a CONCURRENT batch ({@link runOnce}’s
+ * `maxParallel`/`perRepoMax` in-flight execution), integrates, then the loop
+ * continues. This absorbs the retired `watch` verb’s bounded-session + surface-
+ * failures behaviour: a stuck item (timeout / red gate / rebase conflict) is
+ * routed through the EXISTING ledger needs-attention seam INSIDE the tick
+ * (`runOneItem` → `applyNeedsAttentionTransition`, surfaced on `main`) — the loop
+ * does NOT infinite-retry it and adds NO bespoke failure reporting; it just keeps
+ * ticking. `run --once` is exactly ONE tick (call {@link runOnce} directly, the
+ * debug/test affordance — NOT the CI path; CI is `do`).
+ *
+ * The loop owns ONLY scheduling (when/whether to tick); the TICK owns one batch’s
+ * work — kept separable so advance-loop can swap the tick later (see {@link
+ * RunTick}).
+ */
+export async function runLoop(options) {
+    const tick = options.tick ?? runOnce;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? realSleep;
+    const intervalMs = options.intervalMs ?? 0;
+    const start = now();
+    const deadline = options.maxDurationMs !== undefined
+        ? start + options.maxDurationMs
+        : undefined;
+    // The per-tick options are the RunOnceOptions subset of RunLoopOptions; the
+    // loop-only knobs (bounds / seams / callbacks) are not forwarded to the tick.
+    const tickOptions = {
+        config: options.config,
+        report: options.report,
+        workspace: options.workspace,
+        dorfl: options.dorfl,
+        harness: options.harness,
+        reviewGate: options.reviewGate,
+        provider: options.provider,
+        openPr: options.openPr,
+        env: options.env,
+        agentId: options.agentId,
+        onWarn: options.onWarn,
+    };
+    const ticks = [];
+    let stoppedBy = 'max-iterations';
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        // Stop-condition checks BEFORE running a tick (so a zero-iteration / already-
+        // expired / pre-signalled session does no work).
+        if (options.stop?.()) {
+            stoppedBy = 'signal';
+            break;
+        }
+        if (options.maxIterations !== undefined &&
+            ticks.length >= options.maxIterations) {
+            stoppedBy = 'max-iterations';
+            break;
+        }
+        if (deadline !== undefined && now() >= deadline) {
+            stoppedBy = 'max-duration';
+            break;
+        }
+        const result = await tick(tickOptions);
+        ticks.push(result);
+        options.onTick?.(result, ticks.length);
+        // Re-check the bounds AFTER the tick so we never sleep past a stop condition.
+        if (options.maxIterations !== undefined &&
+            ticks.length >= options.maxIterations) {
+            stoppedBy = 'max-iterations';
+            break;
+        }
+        if (deadline !== undefined && now() >= deadline) {
+            stoppedBy = 'max-duration';
+            break;
+        }
+        if (options.stop?.()) {
+            stoppedBy = 'signal';
+            break;
+        }
+        if (intervalMs > 0) {
+            await sleep(intervalMs);
+        }
+    }
+    return {
+        iterations: ticks.length,
+        stoppedBy,
+        claimedAndDone: ticks.reduce((n, t) => n + t.claimedAndDone, 0),
+        skipped: ticks.reduce((n, t) => n + t.skipped, 0),
+        failed: ticks.reduce((n, t) => n + t.failed, 0),
+        needsAttention: ticks.reduce((n, t) => n + t.needsAttention, 0),
+        ticks,
+    };
+}
+//# sourceMappingURL=run.js.map