dorfl 0.0.0 → 0.1.0

package/dist/do.js

@@ -0,0 +1,1882 @@
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { performStart } from './start.js';
+import { performComplete } from './complete.js';
+import { performClaim } from './claim-cas.js';
+import { resolveSlug, SlugResolutionError, workBranchRef, } from './slug-namespace.js';
+import { performTask } from './tasking.js';
+import { resolveTask, buildAgentPrompt, resolveContinueContext, resolvePromptGuidanceForItem, PromptError, } from './prompt.js';
+import { NullHarness } from './harness.js';
+import { PiHarness } from './pi-harness.js';
+import { launchWithOptionalWatch } from './agent-launch.js';
+import { ledgerRead } from './ledger-read.js';
+import { ledgerWrite, } from './ledger-write.js';
+import { jobWorktreeStrategy, selectIsolationStrategy, } from './isolation.js';
+import { ensureMirror, encodeRepoKey, mirrorPath } from './repo-mirror.js';
+import { jobWorktreePath } from './workspace.js';
+import { reapJob } from './gc.js';
+import { isGitHubArbiterUrl, GitHubProvider } from './github.js';
+import { arbiterUrl } 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 { git, run, runAsync, localMainAheadCount } from './git.js';
+import { identityEnv, assertTransportAllowed, } from './identity.js';
+import { parseStopSentinel, isWorkBranchDiffEmpty, emptyDiffStopReason, } from './agent-stop.js';
+import { classifyFailureCause, failureCauseLabel, } from './failure-cause.js';
+const DEFAULT_ARBITER = 'origin';
+/**
+ * Map a `do prd:<slug>` {@link TaskResult} onto the `do` {@link DoResult}
+ * contract: outcomes pass through (tasked / gate-refused / stale / agent-failed /
+ * usage-error), the lock-lost outcome splits into `lost` (exit 2) vs `contended`
+ * (exit 3) by its exit code, and the tasking-only exit 4 (stale) is reported on
+ * the `do` exit contract (`0|1|2|3`) as exit 1 — the needs-attention-class
+ * failure code, same as a stuck build.
+ */
+function taskResultToDoResult(tasked) {
+    let outcome;
+    let exitCode;
+    switch (tasked.outcome) {
+        case 'tasked':
+            outcome = 'tasked';
+            exitCode = 0;
+            break;
+        case 'gate-refused':
+            outcome = 'gate-refused';
+            exitCode = 1;
+            break;
+        case 'lock-lost':
+            if (tasked.exitCode === 3) {
+                outcome = 'contended';
+                exitCode = 3;
+            }
+            else {
+                outcome = 'lost';
+                exitCode = 2;
+            }
+            break;
+        case 'stale':
+            outcome = 'stale';
+            exitCode = 1;
+            break;
+        case 'needs-attention':
+            // The tasker review→edit loop found the decomposition unclear and routed the
+            // prd to needs-attention (no guessed tasks). Same exit class as a stuck
+            // build (1).
+            outcome = 'needs-attention';
+            exitCode = 1;
+            break;
+        case 'agent-failed':
+            outcome = 'agent-failed';
+            exitCode = 1;
+            break;
+        default:
+            outcome = 'usage-error';
+            exitCode = 1;
+    }
+    return { exitCode, outcome, slug: tasked.slug, message: tasked.message };
+}
+/**
+ * Run the in-place `do` ritual end-to-end. Never throws for the expected
+ * lost/contended/refused/needs-attention cases — those are returned with the
+ * appropriate exit code and outcome. The runner owns all git; the agent only
+ * edits code.
+ */
+export async function performDo(options) {
+    const note = options.note ?? (() => { });
+    const arbiter = options.arbiter ?? DEFAULT_ARBITER;
+    const cwd = options.cwd;
+    // `env` here is the runner's GIT/provider env, scoped to the configured
+    // identity (claim, push, integrate, `gh`). The AGENT launch is the ONE thing
+    // that must NOT be the identity — it stays on the ambient `options.env`
+    // (`runDoAgent` reads `options.env` directly, never this local `env`), so the
+    // agent never commits as the bot; only the runner's own transitions do. Absent
+    // identity ⇒ `options.env` unchanged (byte-for-byte ambient). A configured
+    // identity that cannot be resolved (e.g. `tokenEnv` names an unset env var) is
+    // a clean usage error here, never a crash or a silent ambient fallback.
+    let env;
+    try {
+        env = identityEnv(options.identity, options.env ?? process.env);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        note(message);
+        return { exitCode: 1, outcome: 'usage-error', message };
+    }
+    // 0. `--watch` REQUIRES the pi harness (task `do-watch`): only the pi adapter
+    //    writes a session `.jsonl` event log to tail. The null/shell adapter has no
+    //    session log / event taxonomy, so there is nothing to observe — ERROR
+    //    CLEARLY here, BEFORE any git transition (no claim, no branch), rather than
+    //    silently running without the view. The injected `dorfl` (tests /
+    //    custom embeddings) is its own launch path and is exempt.
+    if (options.watch === true &&
+        options.dorfl === undefined &&
+        !(options.harness instanceof PiHarness)) {
+        return {
+            exitCode: 1,
+            outcome: 'usage-error',
+            message: '`do --watch` requires the pi harness; configure `harness: pi` or drop ' +
+                '`--watch`.',
+        };
+    }
+    // 1. Resolve the slug across BOTH namespaces — `do` is the ONE command that
+    //    spans them (ADR §3a): bare → task (after a no-prd-collision check;
+    //    ERROR on collision), `task:`/`prd:` explicit. A collision / resolution
+    //    failure is a loud usage error (exit 1).
+    let resolved;
+    try {
+        resolved = resolveSlug({
+            arg: options.arg,
+            repoPath: options.repoPath ?? cwd,
+            read: options.read ?? ledgerRead,
+        });
+    }
+    catch (err) {
+        if (err instanceof SlugResolutionError) {
+            return { exitCode: 1, outcome: 'usage-error', message: err.message };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return { exitCode: 1, outcome: 'usage-error', message };
+    }
+    // 2. `do spec:<slug>` → the spec-TASKING path (`autoslice-command`): the in-place
+    //    `do` worker is AUTONOMOUS, so it tasks as the AGENT (gate-bound + lock).
+    //    The orchestration (gate → lock → to-task harness → runner-owned commit)
+    //    lives in `tasking.ts`; `do` dispatches `spec:` here. The agent only writes
+    //    task files — the runner owns every git transition (same boundary as the
+    //    build path). It does NOT run the task-build pipeline below.
+    //    `resolveSlug` returns `{namespace:'spec'}` for a `spec:<slug>` arg, so
+    //    `do spec:<slug>` routes here to tasking.
+    if (resolved.namespace === 'spec') {
+        const tasked = await performTask({
+            slug: resolved.slug,
+            cwd,
+            arbiter,
+            doer: 'agent',
+            autoTask: options.autoTask,
+            // EXPLICIT dispatch: a `do prd:<slug>` target was NAMED (the operator typed
+            // it, or the auto-pick POOL already filtered it on `autoTask` before
+            // dispatching here — the single policy-enforcement point). So the tasking gate
+            // drops the `autoTask` policy term and binds only the prd's own readiness
+            // (`humanOnly`/`needsAnswers`) + `taskedAfter`, EXACTLY as `do <task>` builds a
+            // named task regardless of `autoBuild` (the pool gates the policy, not the
+            // explicit claim).
+            explicit: true,
+            // The injected dorfl (tests) writes task files directly. The
+            // DoDorfl shape is a structural superset of TaskDorfl (its
+            // extra `output` is ignored by the tasking path), so it threads straight in.
+            dorfl: options.dorfl,
+            harness: options.harness,
+            agentCmd: options.agentCmd,
+            model: options.model,
+            sessionsDir: options.sessionsDir,
+            // The integrate-time args (task `slice-output-through-integration`): the
+            // `provider` is the SAME the task-build path threads (arg parity), but the
+            // MODE is the per-TRANSITION TASKING resolution (`per-transition-integration-
+            // mode-tasking-vs-build`): `taskingIntegration ?? integration`. Unset override ⇒
+            // falls back to `integration` (today's behaviour); a repo with
+            // `integration:'propose'` + `taskingIntegration:'merge'` lands the task FILES
+            // on main here while the BUILD path below still threads plain `integration`.
+            integration: options.taskingIntegration ?? options.integration,
+            // The per-repo TASK-PLACEMENT default + the operator's explicit
+            // override (task `runner-deterministic-slice-placement-policy-and-
+            // precedence`). The tasker reads them as the configured-default + the
+            // top rung of the runner-deterministic placement resolver; the
+            // `originTrust: untrusted` force is read inside the tasker from the
+            // prd's stamped frontmatter.
+            tasksLandIn: options.tasksLandIn,
+            explicitTasksLandIn: options.explicitTasksLandIn,
+            noPR: options.noPR,
+            providerInstance: options.providerInstance,
+            // The tasker review→edit→converge loop (slicer-review-edit-loop): improves the
+            // candidate tasks in place + routes the verdict through the needsAnswers /
+            // needs-attention sink. Threaded only on the `do prd:` path; omitted ⇒ no loop.
+            reviewLoop: options.reviewLoop,
+            taskerLoopMax: options.taskerLoopMax,
+            reviewExecutions: options.reviewExecutions,
+            taskerLoopModel: options.taskerLoopModel,
+            // The task-SET ACCEPTANCE GATE (slice-acceptance-gate): rides the BUILD
+            // `--review`/`--review-model` family — a fresh-context review of the produced
+            // SET before it integrates, ONE-SHOT, independent of the improver loop above.
+            review: options.review,
+            reviewGate: options.taskReviewGate,
+            acceptanceReviewModel: options.reviewModel,
+            env,
+            // The tasker + review AGENTS launch AMBIENT, never the identity env.
+            agentEnv: options.env,
+            note,
+        });
+        return taskResultToDoResult(tasked);
+    }
+    const slug = resolved.slug;
+    // 3. Refuse on a DIRTY working tree (ar-run.sh's first guard). `do` runs in a
+    //    REAL checkout (the human's clone / the CI container); it must NOT
+    //    entangle unrelated work or run over uncommitted changes. (Mirrors the
+    //    bash driver: "error: working tree is dirty — commit/stash before
+    //    running a task.")
+    if (await isDirtyTree(cwd, env)) {
+        const message = `working tree is dirty — commit or stash before running '${slug}' ` +
+            '(do runs in-place in this checkout and will not entangle unrelated ' +
+            'changes).';
+        return { exitCode: 1, outcome: 'refused', slug, message };
+    }
+    // 3b. Refuse on a DIVERGED local `main` (MERGE MODE ONLY — mirrors `complete`'s
+    //     guard). A local `main` AHEAD of `<arbiter>/main` (unpushed commits) breaks
+    //     ONLY the paths that fast-forward local `main`, and only merge mode ff's it:
+    //     the task builds off `<arbiter>/main`, so a merge-back ff cannot apply over
+    //     a diverged main. Propose mode never ff's local `main` (it pushes the work
+    //     branch + opens a PR; completion only `switch`es to main, no ff), so the
+    //     guard is irrelevant there and must NOT fire. Catch it UP FRONT — before the
+    //     claim + agent run — so a whole build is not wasted. Resolve the mode the
+    //     SAME way the rest of the flow does (the `options.integration` we thread into
+    //     `complete`), then fetch (as the onboarding flow does) and compare.
+    //     `--ignore-diverged-main` overrides (mirrors `--ignore-not-ready`); when
+    //     overridden, Part 1's non-fatal sync handles the persisting divergence
+    //     honestly at complete-time.
+    if ((options.integration ?? 'propose') === 'merge' &&
+        options.ignoreDivergedMain !== true) {
+        await runAsync('git', ['fetch', '--quiet', arbiter], cwd, { env });
+        const ahead = await localMainAheadCount(cwd, arbiter, env);
+        if (ahead > 0) {
+            const message = `local main is ahead of ${arbiter}/main by ${ahead} commit` +
+                `${ahead === 1 ? '' : 's'} (unpushed); the task builds off ${arbiter}/main ` +
+                "and the merge-back can't fast-forward — push or reconcile main first " +
+                '(or re-run with --ignore-diverged-main to proceed anyway).';
+            return { exitCode: 1, outcome: 'refused', slug, message };
+        }
+    }
+    // 3c. PR-INTENT pre-flight guard (the honest-failure value of the `noPR` axis).
+    //     When this run is `propose` on a GITHUB arbiter and the operator INTENDS a PR
+    //     (`noPR` unset), run a `gh` AUTH/AVAILABILITY PROBE UP FRONT — BEFORE the
+    //     claim + agent run — and FAIL FAST if `gh` genuinely cannot open one, instead
+    //     of letting integration silently degrade to manual-PR instructions. This sits
+    //     alongside the dirty-tree / diverged-main guards (and mirrors the shared
+    //     `doNeedsAgentCmd`/`NO_AGENT_CMD_MESSAGE` up-front refusal) so no build work
+    //     is wasted. CRITICAL: the PROBE is the signal, NOT "is a `providers.github`
+    //     identity present" — an absent identity falls back to AMBIENT `gh` auth (the
+    //     common local-dev case), which the probe correctly reports as available, so a
+    //     working ambient setup still PROCEEDS. A genuinely transient mid-run `gh`
+    //     outage (probe passes here, the API fails later) is left to the runtime
+    //     degrade. `noPR: true` skips the guard entirely (no PR is intended).
+    {
+        const url = await arbiterUrl(cwd, arbiter, env);
+        const probe = options.ghCanOpenPr ??
+            ((probeCwd, probeEnv) => new GitHubProvider().available(probeCwd, probeEnv));
+        if (shouldFailProposePrIntent({
+            mode: options.integration ?? 'propose',
+            arbiterIsGitHub: url !== undefined && isGitHubArbiterUrl(url),
+            noPR: options.noPR,
+            ghCanOpenPr: () => probe(cwd, env),
+        })) {
+            return {
+                exitCode: 1,
+                outcome: 'refused',
+                slug,
+                message: PROPOSE_PR_INTENT_GH_UNAVAILABLE_MESSAGE,
+            };
+        }
+    }
+    // 3d. STATIC fresh-worktree-gate readiness guard (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, the throwaway worktree the gate runs in will have no
+    //     `node_modules` and `verify`'s tools (`prettier`/`tsc`/`vitest`) will be
+    //     "command not found" — fail fast HERE, BEFORE the claim and BEFORE spawning
+    //     the build agent, instead of wasting a whole `do` run and (worse) routing
+    //     correct work to needs-attention as if the task were at fault. A repo with
+    //     NO lockfile is the intentional dep-free case (the design point preserved)
+    //     and proceeds. There is NO verify-unset case — `resolveVerifyCommands`
+    //     substitutes the default gate when verify is unset/all-blank, so verify is
+    //     never statically unrunnable-because-unset (the guard is deps-only).
+    {
+        const guard = checkGatePreconditions({
+            freshWorktreeGate: options.freshWorktreeGate,
+            prepare: options.prepare,
+            lockfile: detectLockfileOnDisk(cwd),
+        });
+        if (guard !== undefined) {
+            return { exitCode: 1, outcome: 'refused', slug, message: guard.message };
+        }
+    }
+    // 4. Onboard via the ISOLATION SEAM (`selectIsolationStrategy`/`inPlaceStrategy`)
+    //    with the SAME claim-first composition `do --remote` (and `run`) use — this
+    //    is the consumer that finally puts in-place `do` on the seam, so all THREE
+    //    `do`/`run` forms share the one `IsolatedTree`-handle post-claim shape:
+    //
+    //      a. CLAIM explicitly via the CAS (the claim is the `do` driver's job,
+    //         BEFORE prepare). A lost/contended/usage claim is propagated verbatim
+    //         and NOTHING is onboarded — the same clean skip `run`/`do --remote` do.
+    //         An already-in-progress / done / absent item is NOT claimable, so the
+    //         CAS returns `lost` (exit 2): `do` (the autonomous CI worker) never
+    //         re-claims an item someone else holds, exactly like its siblings.
+    //      b. `selectIsolationStrategy({checkout})` → `inPlaceStrategy`, whose
+    //         `prepare` does the ONBOARDING half (fetch + continue-detection +
+    //         fresh-main `work/<slug>` switch, incl. the §14 continue/rebase path)
+    //         WITHOUT re-claiming — the split the seam mandates (claim → driver,
+    //         onboarding → strategy).
+    const claim = await performClaim({
+        slug,
+        cwd,
+        arbiter,
+        // `--allow-backlog`: widen the claimable predicate to ALSO accept a
+        // `tasks/backlog/`-resident body. Claim stays a pure lock (writes nothing to
+        // `main`, moves nothing); default off ⇒ pool-only, exactly as today.
+        allowBacklog: options.allowBacklog === true,
+        env,
+        note,
+    });
+    if (claim.outcome === 'lost') {
+        return { exitCode: 2, outcome: 'lost', slug, message: claim.message };
+    }
+    if (claim.outcome === 'contended') {
+        return { exitCode: 3, outcome: 'contended', slug, message: claim.message };
+    }
+    if (claim.exitCode !== 0) {
+        // usage/environment error (not inside a repo, no arbiter remote, dirty
+        // index, …): surface verbatim. NOTHING was onboarded.
+        return { exitCode: 1, outcome: 'usage-error', slug, message: claim.message };
+    }
+    // The claim landed (the item is now in-progress on the arbiter). Onboard the
+    // checkout onto its work branch THROUGH the seam — the in-place strategy puts
+    // `cwd` on `work/<slug>` off the freshly-fetched `<arbiter>/main` (or continues
+    // a kept requeue branch + rebases it, §14/§10). `prepare` can throw on a genuine
+    // plumbing failure (unreachable arbiter, …) — surface that as a usage error,
+    // never a false success.
+    let tree;
+    try {
+        tree = selectIsolationStrategy({ checkout: cwd, arbiter }).prepare({
+            slug,
+            // The task-build path: namespace the branch `work/task-<slug>`, and
+            // branch it from the EXACT claim commit (the defensive guard) so a stale
+            // same-named branch (e.g. one `intake` left) is re-pointed, never reused.
+            type: 'task',
+            claimCommit: claim.claimCommit,
+            env,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { exitCode: 1, outcome: 'usage-error', slug, message };
+    }
+    const branch = tree.branch;
+    // 4a. CONTINUE rebase conflict (ADR §14 + §10): a requeue kept a `work/<slug>`
+    //     that did not replay onto the current main at onboard-time (aborted, never
+    //     auto-resolved). Surface to needs-attention TREE-LESSLY via the SAME `#89`
+    //     mechanism `requeue` uses for the reverse direction — the rebase was
+    //     ABORTED, so the kept `work/<slug>` tip == the arbiter tip (already on the
+    //     arbiter, after-commit, recoverable). The surface is purely the one-file
+    //     `in-progress/ → needs-attention/` ledger move + reason (no branch push, no
+    //     worktree mutation) instead of running the agent — the §10 path. The work
+    //     did NOT onboard; the runner owns the bounce.
+    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';
+        const surfaced = await ledgerWrite.applyTreelessNeedsAttentionTransition({
+            cwd: tree.dir,
+            slug,
+            reason,
+            arbiter: tree.arbiterRemote,
+            env,
+            note,
+        });
+        if (!surfaced.moved) {
+            return surfaceUnmovedDoResult({ slug, branch, reason, surfaced });
+        }
+        return {
+            exitCode: 1,
+            outcome: 'needs-attention',
+            slug,
+            branch,
+            message: reason,
+        };
+    }
+    // 4b. 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; the strategy
+    //     CATCHES it and flags `continuePushFailure` so the run does NOT crash
+    //     leaving the task silently in-progress. Surface to needs-attention
+    //     TREE-LESSLY via the SAME `#89` mechanism `requeue` uses — the kept branch
+    //     is already on the arbiter (after-commit, recoverable), so the surface is
+    //     purely the one-file ledger move + reason (no branch push, no worktree).
+    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';
+        const surfaced = await ledgerWrite.applyTreelessNeedsAttentionTransition({
+            cwd: tree.dir,
+            slug,
+            reason,
+            arbiter: tree.arbiterRemote,
+            env,
+            note,
+        });
+        if (!surfaced.moved) {
+            return surfaceUnmovedDoResult({ slug, branch, reason, surfaced });
+        }
+        return {
+            exitCode: 1,
+            outcome: 'needs-attention',
+            slug,
+            branch,
+            message: reason,
+        };
+    }
+    // 5. Run the agent autonomously in the checkout, ON the work branch — the
+    //    SAME prompt assembly `dorfl prompt` emits (canonical wrapper +
+    //    source prd + the task's ## Prompt). The agent only edits code (it does
+    //    no git). This is the one NEW middle step `ar-run.sh` shelled out for
+    //    (`prompt | pi`).
+    //    The post-claim pipeline reads the uniform `IsolatedTree` handle (`tree.dir`)
+    //    — in-place that IS `cwd`, but reading the handle keeps the shared shape the
+    //    future advance-loop tick wraps (no in-place-only special case).
+    let prompt;
+    try {
+        // CONTINUE-aware resolution: on a continue (the arbiter holds a kept
+        // `work/<slug>` whose tip is STRANDED off main) the task may already be in
+        // `work/done/`; admit `done/` ONLY behind the tip-vs-arbiter stranded gate
+        // (story 5), reusing the SAME refs the continue-detection uses.
+        const task = resolveTask(tree.dir, slug, {
+            cwd: tree.dir,
+            branchRef: `${tree.arbiterRemote}/${tree.branch}`,
+            mainRef: `${tree.arbiterRemote}/main`,
+            env,
+        }, 
+        // `--allow-backlog`: also resolve a `tasks/backlog/`-resident body
+        // (lowest priority). Default off ⇒ unchanged.
+        { allowBacklog: options.allowBacklog === true });
+        // CONTINUE-mode (the `agent-prompt-continue-context` task): if the arbiter
+        // holds a kept `work/<slug>` ahead of main (a requeue) the checkout was
+        // CONTINUED onto it — inject the continue block (prior diff + reason + note).
+        // REUSE the SAME continue-detection the onboarding path used (in-place clone
+        // refs: `<arbiter>/work/<slug>` vs `<arbiter>/main`).
+        const continueContext = resolveContinueContext({
+            cwd: tree.dir,
+            slug,
+            arbiter: tree.arbiterRemote,
+            branchRef: `${tree.arbiterRemote}/${tree.branch}`,
+            mainRef: `${tree.arbiterRemote}/main`,
+            content: readFileSync(task.path, 'utf8'),
+            env,
+        });
+        // Per-item override layer: a task or prd may pin `promptGuidance.testFirst`
+        // in its frontmatter, superseding the resolved repo policy for THIS item.
+        const itemGuidance = resolvePromptGuidanceForItem({
+            cwd: tree.dir,
+            repoResolved: { testFirst: options.promptGuidance?.testFirst === true },
+            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({
+                slug,
+                branch,
+                cwd: tree.dir,
+                arbiter: tree.arbiterRemote,
+                detail: err.message,
+                env,
+                note,
+            });
+        }
+        throw err;
+    }
+    let agent;
+    try {
+        agent = await runDoAgent(options, tree.dir, prompt, slug);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return await saveAgentFailure({
+            slug,
+            branch,
+            cwd: tree.dir,
+            arbiter: tree.arbiterRemote,
+            detail: message,
+            env,
+            note,
+        });
+    }
+    if (!agent.ok) {
+        const detail = agent.detail ?? `the agent failed to build '${slug}'.`;
+        return await saveAgentFailure({
+            slug,
+            branch,
+            cwd: tree.dir,
+            arbiter: tree.arbiterRemote,
+            detail,
+            env,
+            note,
+        });
+    }
+    // 5b. HONOR a deliberate STOP (task `agent-stop-signal`). The agent exited
+    //     cleanly (`agent.ok`), but the CLAIM-PROTOCOL wrapper tells it to STOP and
+    //     report on a DRIFTED/ambiguous/stale-premise task WITHOUT building. Detect
+    //     that BEFORE the gate via the in-band sentinel (the agent's reason is the
+    //     needs-attention reason VERBATIM); a clean STOP with no source change is the
+    //     deterministic empty-diff backstop. Either routes to needs-attention and
+    //     SKIPS the acceptance gate AND Gate-2 — a clean STOP is NOT "a build that
+    //     changed nothing".
+    const stopReason = await resolveStopReason({
+        output: agent.output,
+        slug,
+        cwd: tree.dir,
+        arbiter: tree.arbiterRemote,
+        env,
+    });
+    if (stopReason !== undefined) {
+        return await saveAgentStop({
+            slug,
+            branch,
+            cwd: tree.dir,
+            arbiter: tree.arbiterRemote,
+            reason: stopReason,
+            env,
+            note,
+        });
+    }
+    // 6. Gate + done-move + commit + rebase + integrate + branch-tidy LIKE
+    //    `complete` — but with the AUTONOMOUS needs-attention surfacing (pass
+    //    `surfaceArbiter` so a red gate / rebase conflict surfaces on the
+    //    arbiter's main, cross-machine visible — a stuck CI `do` that only routed
+    //    locally would be invisible). The success path reuses `complete`'s
+    //    machinery unchanged.
+    //
+    // Push-time transport-coherence guard (identity): 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(options.identity, tree.arbiterUrl);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return await saveAgentFailure({
+            slug,
+            branch,
+            cwd: tree.dir,
+            arbiter: tree.arbiterRemote,
+            detail: message,
+            env,
+            note,
+        });
+    }
+    const completed = await performComplete({
+        slug,
+        cwd: tree.dir,
+        arbiter: tree.arbiterRemote,
+        integration: options.integration,
+        // An explicit `--merge` overrides the untrusted-origin build-propose rule (task
+        // `untrusted-origin-forces-build-propose`); the autonomous path leaves it
+        // unset so untrusted-origin reliably forces propose.
+        explicitMerge: options.explicitMerge,
+        // `do` already ran the pre-flight divergence guard UP FRONT (step 3b), before
+        // the claim + agent; skip `complete`'s redundant re-check. When `do` was run
+        // with --ignore-diverged-main the guard was bypassed there too, so either way
+        // the (now non-fatal) local-main sync handles any persisting divergence.
+        ignoreDivergedMain: true,
+        // `--allow-backlog`: treat a `tasks/backlog/`-resident body as a valid build
+        // source so the done-move goes `tasks/backlog/ → tasks/done/` directly. Gated
+        // on the flag (without it `complete` refuses a staged strand). Default off.
+        allowBacklog: options.allowBacklog === true,
+        prepare: options.prepare,
+        verify: options.verify,
+        freshWorktreeGate: options.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 so a
+        // wide-matrix CI's raised cap actually reaches the merge loop.
+        mergeRetries: options.mergeRetries,
+        noPR: options.noPR,
+        // The resolved provider INSTANCE seam (tests/embeddings inject a stubbed
+        // GitHubProvider to drive the propose pipeline offline). Unset ⇒ the core
+        // selects from the arbiter URL.
+        providerInstance: options.providerInstance,
+        // Half B (propose-mode PR body): the build agent's FINAL SUMMARY, captured
+        // from the harness seam's `LaunchResult.output` (surfaced by `runDoAgent`
+        // below) and threaded as the PR description. `complete` scaffolds a
+        // deterministic header (task pointer) above it. Undefined ⇒ no body ⇒ the
+        // provider degrades to `gh ... --fill` (no regression).
+        body: agent.output,
+        // Gate 2 (PR/code review) rides INSIDE `complete`: run the `review` SKILL as a
+        // fresh-context agent after the green `verify` (the non-skippable floor) and
+        // before the done-move. A `block` re-uses the same needs-attention surfacing
+        // (`surfaceArbiter`) the red gate does; mapped to `needs-attention` below.
+        review: options.review,
+        reviewModel: options.reviewModel,
+        reviewMaxRounds: options.reviewMaxRounds,
+        reviewGate: options.reviewGate,
+        // `--watch` (task `watch-review-session`): tail the Gate-2 review agent's
+        // session live too, AFTER the build stream the `runDoAgent` watch surfaced
+        // (the gate prints a build→review boundary). Threaded into the gate launch via
+        // `complete`; OFF ⇒ the review path is byte-identical (sync launch, no tailer).
+        watch: options.watch,
+        watchSink: options.watchSink,
+        sessionsDir: options.sessionsDir,
+        // The autonomous failure-surfacing: route stuck items to the arbiter's
+        // main (the `run` semantics), NOT local-only (the human `complete`).
+        surfaceArbiter: tree.arbiterRemote,
+        color: options.color,
+        note,
+        noteBlock: options.noteBlock,
+        env,
+        // 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 carry identity).
+        agentEnv: options.env,
+    });
+    if (completed.outcome === 'completed' ||
+        completed.outcome === 'already-integrated') {
+        // `already-integrated` is the stranded-done auto-recover's clean no-op (the
+        // kept tip was already on `<arbiter>/main` — e.g. the prior PR merged
+        // out-of-band before the re-claim). It is a SUCCESSFUL terminal state — the
+        // work is integrated — so it folds into `DoOutcome 'completed'` (exit 0),
+        // not a new outcome value: the autonomous caller just needs to know the
+        // integrate path ended cleanly. The distinct `CompleteOutcome` value
+        // preserves the no-op signal for tests + the `complete` surface.
+        return {
+            exitCode: 0,
+            outcome: 'completed',
+            slug,
+            branch,
+            message: completed.message,
+        };
+    }
+    if (completed.outcome === 'review-unparseable') {
+        // Gate 2 RAN but its verdict was UNPARSEABLE (malformed JSON). The core already
+        // routed it work-preservingly (branch pushed + surfaced). This is the FAILURE-
+        // CAUSE axis, NOT a reviewer block: classify the parse-failure phrase the core
+        // recorded → `transient-infra` (re-run the SAME work: the gate output is
+        // stochastic + the parser now repairs the control-char class, so a re-run is far
+        // more likely to parse). Same `classifyFailureCause` `run` uses, so `do`/`run`
+        // agree on the label. (`classifyFailureCause` only EVER returns config/transient/
+        // agent-failed; the malformed-JSON signature lands transient-infra, never a
+        // silent success.)
+        const cause = classifyFailureCause(completed.message);
+        return {
+            exitCode: 1,
+            outcome: failureCauseToDoOutcome(cause),
+            slug,
+            branch,
+            message: completed.message,
+        };
+    }
+    if (completed.outcome === 'prepare-failed' ||
+        completed.outcome === 'gate-failed' ||
+        completed.outcome === 'review-blocked' ||
+        completed.outcome === 'rebase-conflict' ||
+        completed.outcome === 'strand-surfaced') {
+        // Failed env-prep / red gate / Gate-2 review block / rebase conflict — routed
+        // to needs-attention (surfaced on the arbiter). A `prepare-failed` (the env
+        // could not be made ready, so verify was NOT run) and a `review-blocked` are
+        // mapped HERE the SAME way `gate-failed` is. The work did NOT complete; the
+        // runner owns the bounce.
+        //
+        // `strand-surfaced` is the autonomous-strand parity (the SHARED `complete.ts`
+        // seam already surfaced the source-strand / empty-staged refusal to
+        // needs-attention on the arbiter) — in-place `performDo` inherits the fix
+        // here, mapped to the SAME `needs-attention` outcome shape `do --remote`
+        // (`runRemotePipeline`) uses, so `advance task:<slug>` (via the default
+        // `doDriver = performDo`) agrees with the remote path on the caller-visible
+        // label.
+        return {
+            exitCode: 1,
+            outcome: 'needs-attention',
+            slug,
+            branch,
+            message: completed.message,
+        };
+    }
+    if (completed.outcome === 'surface-unmoved') {
+        // Strand-surface could not land on the arbiter (CAS contention exhausted /
+        // no arbiter) — HONESTLY still in-progress on the arbiter. Mirror
+        // `runRemotePipeline`'s `surface-unmoved` mapping so in-place `performDo`
+        // (and `advance task:<slug>` via the default `doDriver`) agrees with
+        // `do --remote` on the same signal, never a fake success.
+        return {
+            exitCode: 1,
+            outcome: 'surface-unmoved',
+            slug,
+            branch,
+            message: completed.message,
+        };
+    }
+    // refused (nothing to commit, wrong folder) / usage-error: surface verbatim —
+    // BUT first reclassify a thrown CORE wiring/config error (which `performComplete`
+    // swallows into `usage-error`) onto the SAME `config-error` cause `run` records,
+    // closing the cross-path divergence (`do`: usage-error vs `run`: agent-failed for
+    // the identical thrown core error). Best-effort: a non-config usage-error stays
+    // `usage-error` (the conservative default — the classifier only re-labels what it
+    // recognises).
+    if (completed.outcome === 'usage-error') {
+        const cause = classifyFailureCause(completed.message);
+        if (cause === 'config-error') {
+            return {
+                exitCode: 1,
+                outcome: 'config-error',
+                slug,
+                branch,
+                message: completed.message,
+            };
+        }
+    }
+    const outcome = completed.outcome === 'refused' ? 'refused' : 'usage-error';
+    return { exitCode: 1, outcome, slug, branch, message: completed.message };
+}
+/**
+ * The EXACT recovery one-liner handed to the operator when an isolated/remote `do`
+ * integration fails terminally AFTER the work was committed + done-moved (the
+ * stale-lease-strand class surfaced by Part B #97), leaving the job worktree
+ * RETAINED. It points them straight at the recover-already-committed path
+ * (`complete --isolated <slug>`) so they need not reverse-engineer the encoded
+ * worktree path \u2014 the FINISH half of try-to-finish / else-surface. Detection is
+ * unspoofable (an already-integrated task is a clean no-op), so re-running it is
+ * always safe.
+ *
+ * `complete --isolated` recovers the retained WORKTREE, so it ONLY works ON THE
+ * MACHINE that ran the job (the worktree is local + reaped when that runner ends).
+ * From a DIFFERENT checkout (e.g. a CI-stranded job finished on your laptop),
+ * `--isolated` finds no local worktree and silently no-ops; there, check out the
+ * already-pushed work branch off the arbiter and run plain `complete`. Both named.
+ */
+export function recoverIsolatedOneLiner(slug) {
+    return (`To FINISH the stranded branch once the cause clears: ON THE SAME MACHINE that ` +
+        `ran the job, run \`dorfl complete --isolated ${slug}\` (integrates the ` +
+        `kept commit from the retained worktree; a no-op if already integrated). From ` +
+        `ANOTHER checkout (e.g. a CI-stranded job finished on your laptop), check out ` +
+        `the pushed work branch off the arbiter and run plain \`dorfl complete ` +
+        `${slug}\` instead.`);
+}
+/**
+ * Build the HONEST per-op fragment describing WHAT actually reached the arbiter
+ * after a needs-attention route — reading the seam's captured per-op outcome
+ * (`branchPush`) rather than ASSUMING "pushed" off the local move. Shared by
+ * every save-failure / save-stop message site so they can never drift from
+ * reality (the observed bug: the report claimed "pushed" when the branch push
+ * was skipped-empty or failed). A PUSH failure (HIGH severity: work-at-risk /
+ * breaks cross-machine recovery) flips the fragment to a loud "saved LOCALLY
+ * only" with recovery guidance. The OBSERVABLE half (the stuck state) now rides
+ * on the per-item lock `state: stuck` amend — there is no separate on-`main`
+ * surface to report.
+ */
+function routeReport(routed, branch) {
+    const branchPush = routed.branchPush ?? 'not-attempted';
+    const branchFailed = branchPush === 'failed';
+    if (branchFailed) {
+        // HIGH severity: the recoverable branch push did not reach the arbiter — say
+        // so loudly, the work is saved LOCALLY only, and how to recover.
+        return {
+            fragment: `push of ${branch} FAILED — the work is saved LOCALLY only; push it ` +
+                'when online, then `requeue` (continue), or `requeue --reset` to discard',
+            pushFailed: true,
+        };
+    }
+    // The push that was attempted succeeded (or was honestly skipped). Report
+    // the branch state truthfully.
+    let landed;
+    if (branchPush === 'pushed') {
+        landed = `pushed ${branch}`;
+    }
+    else if (branchPush === 'skipped-empty') {
+        landed = `branch ${branch} skipped (nothing to recover yet)`;
+    }
+    else {
+        landed = 'saved locally';
+    }
+    return {
+        fragment: `${landed}. Recover via \`requeue\` (continue) or \`requeue --reset\` to discard`,
+        pushFailed: false,
+    };
+}
+/**
+ * SAVE the partial work of a FAILED agent instead of dropping it (the keystone of
+ * the `agent-fail-saves-work` task). An agent failure (`runDoAgent` returned
+ * `ok:false`, threw, or the prompt could not be assembled) used to BARE-RETURN
+ * `agent-failed`, leaving whatever the agent edited only on the local work branch
+ * in the (disposable, possibly remote) job worktree — silently lost.
+ *
+ * This routes it through the SAME work-preserving machinery a RED GATE uses: the
+ * ledger write seam's needs-attention transition (`git add -A` + a wip commit
+ * capturing the agent's work + the `git mv → needs-attention/` move-only commit
+ * with the failure detail recorded as the reason in the body), surfaced on the
+ * arbiter's `main` (the autonomous, cross-machine-visible mode-M surfacing `do`
+ * already uses for the gate-fail path) so `scan`/`status`/another machine see it.
+ *
+ * It ALSO pushes the `work/<slug>` branch to the arbiter so the saved partial
+ * commits travel cross-machine and the item is RECOVERABLE via `requeue`
+ * (continue): the continue-detection in `continue-branch.ts` looks for an arbiter
+ * `work/<slug>` ahead of main. That push now lives IN the ledger write seam (the
+ * RECOVERABLE half of the needs-attention transition — fired when an `arbiter` is
+ * given, best-effort, emptiness-guarded), consolidated there by
+ * `centralise-bounce-branch-push` so it cannot drift from the OBSERVABLE surface;
+ * this function no longer pushes separately.
+ *
+ * The EMPTY-failure case (the agent made NO commits / no changes) is handled
+ * without crashing on an empty commit: `routeToNeedsAttention` (under the seam)
+ * skips the wip commit when the tree is clean, and the move-only commit (reason +
+ * the `git mv`) is always non-empty, so the failure reason is still surfaced.
+ *
+ * The OUTCOME is the classified failure CAUSE (the FAILURE-CAUSE axis): the
+ * genuinely-new `transient-infra` / `config-error` where the surfaced detail makes
+ * the cause knowable, else the conservative generic `agent-failed` (still distinct
+ * from a clean success and from a red `gate-failed`/`needs-attention` — `do`'s exit
+ * contract stays coherent). Only the WORK-PRESERVING side-effect (unchanged here)
+ * matches the gate-failure path. We do NOT validate or "fix" the partial work — a broken
+ * tree committed + surfaced (with the reason) is recoverable; the human chooses
+ * `requeue` (continue) vs `requeue --reset` (discard).
+ */
+async function saveAgentFailure(params) {
+    const { slug, cwd, arbiter, detail, env, note } = params;
+    // The work branch is the namespaced build branch (`work/task-<slug>`; the
+    // onboarding switched the checkout to it before the agent ran); derive it from
+    // the slug so the push target is always defined even when the caller's `branch`
+    // was not narrowed.
+    const branch = params.branch ?? workBranchRef('task', slug);
+    // Classify the failure CAUSE (best-effort + conservative) from the surfaced
+    // detail — the SAME `classifyFailureCause` `run` uses, so `do`/`run` agree on the
+    // same error. The cause LABEL prefixes the recorded reason so the cause is legible
+    // on the needs-attention route without a second naming scheme; `agent-failed`
+    // keeps the historical "agent failed:" prefix (no reason-prose regression).
+    const cause = classifyFailureCause(detail);
+    const reason = `${failureCauseLabel(cause)}: ${detail}`;
+    // Route through the SAME seam the gate-fail path uses: save the agent's work as
+    // a wip commit (skipped when the tree is clean — the empty-failure case), amend
+    // the item's per-item lock ref to `state: stuck` with the reason in the body,
+    // surface that lock amend on the arbiter (OBSERVABLE, mode-M, cross-machine
+    // visible) AND push the `work/<slug>` branch (RECOVERABLE — so a requeue-continue
+    // reading <arbiter>/work/<slug> lands on the saved wip). Both halves fire from
+    // the single `arbiter` here; no separate push to forget.
+    const routed = await ledgerWrite.applyNeedsAttentionTransition({
+        cwd,
+        slug,
+        reason,
+        arbiter,
+        env,
+        note,
+    });
+    const report = routed.moved ? routeReport(routed, branch) : undefined;
+    const message = routed.moved
+        ? `Agent run failed building '${slug}' [${cause}] (${detail}); SAVED the ` +
+            `partial work and marked '${slug}' stuck on its lock (${report.fragment}).`
+        : `Agent run failed building '${slug}' [${cause}] (${detail}); could not ` +
+            `mark '${slug}' stuck (${routed.reasonNotMoved ?? 'unknown'}).`;
+    note(message);
+    return {
+        exitCode: 1,
+        outcome: failureCauseToDoOutcome(cause),
+        slug,
+        branch,
+        routedToNeedsAttention: routed.moved,
+        message,
+    };
+}
+/**
+ * Map a {@link FailureCause} onto the `do` {@link DoOutcome}. The cause names ARE
+ * the outcome 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 (`run` has the twin {@link failureCauseToItemStatus}).
+ */
+function failureCauseToDoOutcome(cause) {
+    return cause;
+}
+/**
+ * Build the HONEST result 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 —
+ * a clean `needs-attention` would mislead (it claims the surface landed). Distinct
+ * `surface-unmoved` outcome, carrying `reasonNotMoved`, so the caller/human can
+ * tell it from a successful surface and retry/resolve. The `moved: true` path is
+ * left byte-for-byte unchanged (this branch is only reached on `!moved`).
+ */
+function surfaceUnmovedDoResult(params) {
+    const { slug, branch, reason, surfaced } = params;
+    const message = `'${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}`;
+    return { exitCode: 1, outcome: 'surface-unmoved', slug, branch, message };
+}
+/**
+ * Resolve the STOP reason for a clean (`agent.ok`) run, or `undefined` when the
+ * run is a genuine build that should proceed to the gate (task
+ * `agent-stop-signal`). TWO independent triggers, the sentinel winning:
+ *
+ *   1. The IN-BAND STOP sentinel in the agent's output ({@link parseStopSentinel})
+ *      — the principled case: the agent declared the task drifted/ambiguous and
+ *      reported WHY. Its reason is used VERBATIM (a non-empty diff with a sentinel
+ *      is still a STOP — the agent may have left scratch; the sentinel wins).
+ *   2. The DETERMINISTIC empty-diff backstop ({@link isWorkBranchDiffEmpty}) — the
+ *      observable safety net for when the agent stopped WITHOUT (or with a
+ *      malformed) sentinel: `agent.ok` but no source change vs `<arbiter>/main` is
+ *      never a successful build.
+ *
+ * Shared by `performDo` and `runRemotePipeline` so the in-place and remote forms
+ * detect a STOP identically.
+ */
+async function resolveStopReason(params) {
+    const { output, slug, cwd, arbiter, env } = params;
+    const sentinel = parseStopSentinel(output);
+    if (sentinel !== undefined) {
+        return sentinel.reason;
+    }
+    if (await isWorkBranchDiffEmpty({ cwd, arbiter, env })) {
+        return emptyDiffStopReason(slug);
+    }
+    return undefined;
+}
+/**
+ * Route a DELIBERATE agent STOP (task `agent-stop-signal`) to needs-attention
+ * through the SAME work-preserving seam `saveAgentFailure` uses (save the branch,
+ * surface on the arbiter) — but as the DISTINCT `agent-stopped` outcome, NOT
+ * `agent-failed` (the agent did not error) nor `needs-attention` (no red gate /
+ * rebase conflict). The agent's STOP reason is recorded VERBATIM as the
+ * needs-attention reason. The acceptance gate AND Gate-2 are NEVER reached.
+ */
+async function saveAgentStop(params) {
+    const { slug, cwd, arbiter, reason, env, note } = params;
+    const branch = params.branch ?? workBranchRef('task', slug);
+    const routed = await ledgerWrite.applyNeedsAttentionTransition({
+        cwd,
+        slug,
+        reason,
+        arbiter,
+        env,
+        note,
+    });
+    const report = routed.moved ? routeReport(routed, branch) : undefined;
+    const message = routed.moved
+        ? `The agent STOPPED building '${slug}' (the task drifted / is ambiguous / ` +
+            `produced no change); marked '${slug}' stuck on its lock (${report.fragment}) ` +
+            `WITHOUT running the gate or Gate-2 review. Reason: ${reason}`
+        : `The agent STOPPED building '${slug}' but it could not be marked stuck ` +
+            `(${routed.reasonNotMoved ?? 'unknown'}). Reason: ${reason}`;
+    note(message);
+    return {
+        exitCode: 1,
+        outcome: 'agent-stopped',
+        slug,
+        branch,
+        routedToNeedsAttention: routed.moved,
+        message,
+    };
+}
+/**
+ * Run the agent against the checkout. Prefers the injected `dorfl` (tests
+ * / custom embeddings); otherwise launches `agentCmd` through the SHARED
+ * {@link launchWithOptionalWatch} helper (the null adapter by default),
+ * forwarding the model routing intent.
+ *
+ * With `--watch` (pi harness only, validated earlier), the helper launches the
+ * agent NON-BLOCKING (`PiHarness.launchAsync` — `spawn`, not `spawnSync`) so a
+ * `SessionTailer` can READ the growing session `.jsonl` concurrently and surface
+ * the high-signal events live. The tailer is a pure observer: the launch result
+ * is IDENTICAL to the non-watch path, so outcome / gate / git / exit code are
+ * unchanged — only a concurrent log-tail is added.
+ *
+ * The build session-id is the SLUG (in-place `do` has no work-id), which the
+ * helper makes unique per launch; the Gate-2 REVIEW launch uses the SAME helper
+ * with a DISTINCT id (`<slug>-review`) so the two sessions never collide — one
+ * watch implementation, two callers (task `watch-review-session`).
+ */
+async function runDoAgent(options, cwd, prompt, slug) {
+    if (options.dorfl) {
+        return options.dorfl({ cwd, prompt, slug, env: options.env });
+    }
+    const harness = options.harness ?? new NullHarness();
+    const launched = await launchWithOptionalWatch({
+        harness,
+        dir: cwd,
+        slug,
+        command: options.agentCmd ?? '',
+        prompt,
+        model: options.model,
+        // In-place `do` has NO work-id, so the build session id is the slug.
+        sessionId: slug,
+        sessionsDir: options.sessionsDir,
+        watch: options.watch,
+        watchSink: options.watchSink,
+        color: options.color,
+        env: options.env,
+    });
+    // Surface the agent's FINAL SUMMARY (`LaunchResult.output`) — the source channel
+    // for the propose-mode PR body — instead of dropping it. Absent (no parseable
+    // assistant text) ⇒ undefined ⇒ the body degrades to `--fill` (no regression).
+    return { ok: launched.ok, detail: launched.detail, output: launched.output };
+}
+/**
+ * True when the working tree has uncommitted (unstaged OR staged) changes — the
+ * dirty-tree refusal predicate (ar-run.sh: `git diff --quiet` AND
+ * `git diff --cached --quiet`). Read-only.
+ */
+async function isDirtyTree(cwd, env) {
+    const unstaged = await runAsync('git', ['diff', '--quiet'], cwd, { env });
+    if (unstaged.status !== 0) {
+        return true;
+    }
+    const staged = await runAsync('git', ['diff', '--cached', '--quiet'], cwd, {
+        env,
+    });
+    return staged.status !== 0;
+}
+/**
+ * `dorfl do --remote <r> <arg>` — the per-repo `do` WORKER run against a
+ * REGISTERED repo with NO checkout (`docs/adr/command-surface-and-journeys.md`
+ * §3). Where the in-place {@link performDo} uses the CURRENT checkout AS its
+ * isolation, this form materialises a **hub mirror + job worktree in the AGENTS'
+ * area** (`workspacesDir`, the SAME isolation `run` uses — NEVER the human area),
+ * runs the existing `do` pipeline against that worktree, then tears it down per
+ * the §4 provably-safe deletion predicate.
+ *
+ * **Option A — materialise-then-reuse** (the drift correction; the full
+ * IsolatedTree-seam unification is the SEPARATE `do-run-share-isolation-seam`
+ * task). `performDo` composes the human verbs against a literal `cwd`; this
+ * function does the same — it just points that `cwd` at a freshly-cut job
+ * worktree instead of a checkout. It reuses (does NOT reimplement) the pipeline:
+ * `performStart` (resume) → agent → `performComplete`.
+ *
+ * **The claim ↔ worktree ↔ start composition.** Both `createJob` (cuts the
+ * `work/<slug>` branch off the mirror's fresh main) and `performStart` (claims +
+ * switches to `work/<slug>`) overlap. To compose without double-claiming or
+ * fighting over the branch we order them as the task mandates:
+ *
+ *   1. **CLAIM FIRST** — the CAS push to the arbiter, run in a throwaway clone of
+ *      the mirror (the CAS needs a non-bare checkout with an `origin/main`
+ *      tracking ref + a worktree to commit in, which a bare mirror does not
+ *      provide — exactly `work-on`'s remote-form claim context).
+ *   2. **MATERIALISE the worktree** off the POST-CLAIM fresh main via the EXISTING
+ *      job-worktree machinery (`jobWorktreeStrategy`/`createJob`): `createJob`
+ *      re-`ensureMirror`s (fetching the claim move) then cuts `work/<slug>` off
+ *      the freshly-fetched mirror main.
+ *   3. **RUN start/agent/complete** against the worktree dir as `cwd`. `start` is
+ *      driven with `resume: true` so it PLAIN-SWITCHES the branch `createJob`
+ *      already created (the item is in-progress on the arbiter after the claim;
+ *      `performStart`'s resume path switches without re-claiming) — no
+ *      double-claim, no branch fight. The worktree's arbiter remote is `origin`
+ *      (the bare mirror's clone remote), so both `start` and `complete` use
+ *      `origin`.
+ *
+ * **Teardown** re-applies the §4 predicate via the strategy handle's `teardown`
+ * (`reapJob`): reap the worktree iff clean AND on the arbiter, retain otherwise
+ * (the never-lose-work signal). NEVER `--force`.
+ *
+ * **Recovery contract.** The worktree is disposable; the durable artifact is the
+ * `work/<slug>` BRANCH (pushed by the autonomous needs-attention surfacing on a
+ * stuck/failed run). A human recovers via the human face (`requeue` + re-claim,
+ * or `work-on`), NEVER by editing the agents'-area worktree.
+ */
+/**
+ * Resolve the URL of a CHECKOUT's arbiter remote — the primitive `do --isolated`
+ * needs to point the job-worktree pipeline ({@link performDoRemote}) at MY OWN
+ * arbiter (`git -C <cwd> remote get-url <arbiter>`). Returns the URL, or
+ * `undefined` when the cwd is not a git repo or has no such remote (the
+ * "isolated against what?" case the CLI turns into a clear error naming
+ * `--remote <url>`). Does NOT fork the isolation/integrate path — it only feeds
+ * the EXISTING `performDoRemote` its `remote` URL.
+ */
+export function resolveArbiterUrlFromCheckout(cwd, arbiter, env) {
+    const res = run('git', ['remote', 'get-url', arbiter], cwd, { env });
+    if (res.status !== 0) {
+        return undefined;
+    }
+    const url = res.stdout.trim();
+    return url === '' ? undefined : url;
+}
+export async function performDoRemote(options) {
+    const note = options.note ?? (() => { });
+    // The runner's GIT/provider env, scoped to the configured identity (claim,
+    // push, integrate, `gh`). The AGENT launch stays ambient via `options.env`
+    // (`runDoAgent` reads it directly) — the agent must not commit as the bot.
+    // Absent identity ⇒ `options.env` unchanged (byte-for-byte ambient).
+    const workspacesDir = options.workspacesDir;
+    // Resolve the identity env AND run the push-time transport-coherence guard:
+    // refuse a forbidden transport for THIS remote's URL (the registered remote),
+    // and fail cleanly on an unresolvable identity (e.g. `tokenEnv` unset) — never
+    // a crash or a silent ambient fallback. Both are no-ops without an identity.
+    let env;
+    try {
+        env = identityEnv(options.identity, options.env ?? process.env);
+        assertTransportAllowed(options.identity, options.remote);
+    }
+    catch (err) {
+        return {
+            exitCode: 1,
+            outcome: 'usage-error',
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+    // 0. `--watch` REQUIRES the pi harness (same guard as in-place `do`): only the
+    //    pi adapter writes a session `.jsonl` to tail. Error CLEARLY here, BEFORE
+    //    any mirror/claim/worktree side-effect. The injected `dorfl` (tests)
+    //    is its own launch path and is exempt.
+    if (options.watch === true &&
+        options.dorfl === undefined &&
+        !(options.harness instanceof PiHarness)) {
+        return {
+            exitCode: 1,
+            outcome: 'usage-error',
+            message: '`do --watch` requires the pi harness; configure `harness: pi` or drop ' +
+                '`--watch`.',
+        };
+    }
+    // 1. Resolve / auto-create the hub mirror for `<r>` (the `registry-remote` /
+    //    `work-on`-remote precedent: an unregistered remote is auto-mirrored
+    //    before use). `ensureMirror` creates it (`git clone --bare`) when absent
+    //    or fetches it when present, under `workspacesDir/repos/` — the agents'
+    //    area, NEVER the human area.
+    let mirror;
+    try {
+        mirror = ensureMirror({ url: options.remote, workspacesDir, env });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { exitCode: 1, outcome: 'usage-error', message };
+    }
+    note(mirror.created
+        ? `Auto-registered hub mirror for ${mirror.url} at ${mirror.path}.`
+        : `Using hub mirror for ${mirror.url} at ${mirror.path}.`);
+    // 1b. PR-INTENT pre-flight guard — the AUTONOMOUS mirror of in-place `performDo`
+    //     step 3c. The SAME predicate, run UP FRONT here (mirror resolved, BEFORE the
+    //     claim clone / worktree) so a `propose` run 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. NO claim/
+    //     build side-effect: it precedes even the throwaway claim CLONE below. The probe
+    //     runs in the bare mirror dir (`mirror.path`), which carries the arbiter remote
+    //     as `origin`, NOT a bare cwd. CRITICAL: 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 still PROCEEDS.
+    //     `arbiterIsGitHub` is derived from `mirror.url` (the resolved arbiter URL).
+    //     REUSES the predicate + message so the in-place + autonomous paths cannot
+    //     drift.
+    {
+        const probe = options.ghCanOpenPr ??
+            ((probeCwd, probeEnv) => new GitHubProvider().available(probeCwd, probeEnv));
+        if (shouldFailProposePrIntent({
+            mode: options.integration ?? 'propose',
+            arbiterIsGitHub: isGitHubArbiterUrl(mirror.url),
+            noPR: options.noPR,
+            ghCanOpenPr: () => probe(mirror.path, env),
+        })) {
+            return {
+                exitCode: 1,
+                outcome: 'refused',
+                message: PROPOSE_PR_INTENT_GH_UNAVAILABLE_MESSAGE,
+            };
+        }
+    }
+    // 1c. STATIC fresh-worktree-gate readiness guard — the AUTONOMOUS mirror of
+    //     `performDo` step 3d. When the fresh-worktree gate is ON AND `prepare`
+    //     resolves to no commands AND a lockfile is present IN THE MIRROR, the
+    //     throwaway worktree the gate runs in will have no installed deps, so the
+    //     gate cannot run. Probe the bare mirror's main tree (`git ls-tree main`)
+    //     so the guard fires BEFORE the throwaway claim clone is even cut. A repo
+    //     with NO lockfile is the intentional dep-free case and proceeds. Deps-only
+    //     (verify-unset is impossible — `resolveVerifyCommands` defaults the gate).
+    {
+        const guard = checkGatePreconditions({
+            freshWorktreeGate: options.freshWorktreeGate,
+            prepare: options.prepare,
+            lockfile: detectLockfileOnMirrorMain(mirror.path, env),
+        });
+        if (guard !== undefined) {
+            return { exitCode: 1, outcome: 'refused', message: guard.message };
+        }
+    }
+    // 2. A throwaway claim clone of the mirror (the CAS context). Slug resolution
+    //    + the claim both run here against `origin` (the arbiter URL). Keyed PER
+    //    ARG (not a single fixed `__remote` path per mirror) so two CONCURRENT
+    //    `do --remote` calls on the SAME mirror — the registry-set advance batch's
+    //    per-mirror concurrency (`perRepoMax > 1`) — get DISTINCT claim clones rather
+    //    than racing one shared dir (the SAME per-job-clone keying `run`'s
+    //    `claimAgainstRepo` uses; the prior single-shot caller never raced, so this
+    //    is a pure concurrency hardening, not a behaviour change for it).
+    const claimKey = options.arg.replace(/[^a-zA-Z0-9._-]/g, '_');
+    const claimDir = join(workspacesDir, 'claim', `${encodeRepoKey(mirror.url).split('/').join('__')}__${claimKey}`);
+    rmSync(claimDir, { recursive: true, force: true });
+    mkdirSync(dirname(claimDir), { recursive: true });
+    git(['clone', '--quiet', mirror.url, claimDir], dirname(claimDir), { env });
+    try {
+        // 2a. Resolve the slug across BOTH namespaces against the claim clone (it
+        //     carries `work/` from the mirror's main). A collision / resolution
+        //     failure is a loud usage error; a `prd:` arg reaches the not-yet-wired
+        //     stub — identical behaviour to in-place `do`.
+        let resolved;
+        try {
+            resolved = resolveSlug({
+                arg: options.arg,
+                repoPath: claimDir,
+                read: options.read ?? ledgerRead,
+            });
+        }
+        catch (err) {
+            if (err instanceof SlugResolutionError) {
+                return { exitCode: 1, outcome: 'usage-error', message: err.message };
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            return { exitCode: 1, outcome: 'usage-error', message };
+        }
+        // `do --remote spec:<slug>` routes to tasking (the `spec` namespace).
+        if (resolved.namespace === 'spec') {
+            // `do --remote spec:<slug>`: task the spec as the AGENT, against the claim
+            // clone (its `origin` IS the arbiter URL + it carries a working tree from the
+            // mirror's main). No job worktree is needed — the tasking transition is a
+            // runner-owned `spec → tasking → spec` move + emit-backlog on the arbiter, not
+            // a build pipeline. The agent only writes task files; the runner does all git.
+            const tasked = await performTask({
+                slug: resolved.slug,
+                cwd: claimDir,
+                arbiter: 'origin',
+                doer: 'agent',
+                autoTask: options.autoTask,
+                // EXPLICIT dispatch (same as the in-place path above): the `prd:<slug>` was
+                // NAMED (typed, or pool-filtered on `autoTask` before reaching here), so the
+                // tasking gate drops the policy term — only the prd's own readiness +
+                // `taskedAfter` bind, mirroring the build path vs `autoBuild`.
+                explicit: true,
+                dorfl: options.dorfl,
+                harness: options.harness,
+                agentCmd: options.agentCmd,
+                model: options.model,
+                sessionsDir: options.sessionsDir,
+                // The integrate-time args (task `slice-output-through-integration`): the
+                // `provider` is the SAME the task-build path threads (arg parity), but the
+                // MODE is the per-TRANSITION TASKING resolution
+                // (`per-transition-integration-mode-slicing-vs-build`):
+                // `taskingIntegration ?? integration`, so the `--remote prd:` output ALSO
+                // routes through the shared core with the tasking-resolved mode.
+                integration: options.taskingIntegration ?? options.integration,
+                // The per-repo TASK-PLACEMENT default + the operator's explicit
+                // override (task `runner-deterministic-slice-placement-policy-and-
+                // precedence`). Same threading as the in-place `do prd:` path.
+                tasksLandIn: options.tasksLandIn,
+                explicitTasksLandIn: options.explicitTasksLandIn,
+                noPR: options.noPR,
+                providerInstance: options.providerInstance,
+                // The tasker review→edit→converge loop on the `do --remote prd:` path too.
+                reviewLoop: options.reviewLoop,
+                taskerLoopMax: options.taskerLoopMax,
+                reviewExecutions: options.reviewExecutions,
+                taskerLoopModel: options.taskerLoopModel,
+                // The task-SET ACCEPTANCE GATE on the `do --remote prd:` path too.
+                review: options.review,
+                reviewGate: options.taskReviewGate,
+                acceptanceReviewModel: options.reviewModel,
+                env,
+                // The tasker + review AGENTS launch AMBIENT, never the identity env.
+                agentEnv: options.env,
+                note,
+            });
+            return taskResultToDoResult(tasked);
+        }
+        const slug = resolved.slug;
+        // 3. CLAIM FIRST (the CAS push to the arbiter), in the throwaway clone.
+        //    `origin` there IS the arbiter URL. A lost/contended/usage claim is
+        //    propagated verbatim — NO worktree is materialised (clean failure, like
+        //    `run`'s `runOneItem`).
+        const claim = await performClaim({
+            slug,
+            cwd: claimDir,
+            arbiter: 'origin',
+            // `--allow-backlog`: accept a `tasks/backlog/`-resident body (staging). The
+            // claim stays a pure lock. Default off ⇒ pool-only.
+            allowBacklog: options.allowBacklog === true,
+            env,
+            note,
+        });
+        if (claim.outcome === 'lost') {
+            return { exitCode: 2, outcome: 'lost', slug, message: claim.message };
+        }
+        if (claim.outcome === 'contended') {
+            return { exitCode: 3, outcome: 'contended', slug, message: claim.message };
+        }
+        if (claim.exitCode !== 0) {
+            return {
+                exitCode: 1,
+                outcome: 'usage-error',
+                slug,
+                message: claim.message,
+            };
+        }
+        // 4. MATERIALISE the job worktree off the POST-CLAIM fresh main via the
+        //    EXISTING job-worktree machinery (the SAME path `run` uses). `createJob`
+        //    re-`ensureMirror`s (fetching the claim move) then cuts `work/<slug>`
+        //    off the freshly-fetched mirror main, in the agents' area.
+        const strategy = jobWorktreeStrategy({
+            fromRepo: claimDir,
+            arbiter: 'origin',
+            workspacesDir,
+        });
+        let tree;
+        let result;
+        try {
+            try {
+                tree = strategy.prepare({ slug, type: 'task', env });
+            }
+            catch (err) {
+                // `prepare()`/`createJob` THREW before returning the handle (e.g. an
+                // onboard reconcile/stale-lease push surfaced as a throw). `tree` is
+                // undefined, so the normal teardown below would be skipped and a
+                // partially-created worktree could LEAK with no teardown attempt at all —
+                // and its checked-out `work/<slug>` branch would then poison the next
+                // build's fetch. Best-effort reap the deterministic worktree path for this
+                // slug (it is reaped ONLY if its branch is reachable on the arbiter —
+                // never lose work), then re-throw so the failure is still reported.
+                reapPreparedWorktreeLeak(mirror.url, slug, workspacesDir, env, note);
+                throw err;
+            }
+            result = await runRemotePipeline(options, tree, slug, note, env);
+            return result;
+        }
+        finally {
+            // 7. Teardown via the strategy handle. On a CLEAN completion: reap iff clean
+            //    AND on the arbiter (the standard §4 predicate). On a FAILURE return
+            //    (needs-attention / config-error / refused etc. — the seam already
+            //    surfaced the item + pushed the branch): reap on REACHABILITY ALONE, so a
+            //    churn-dirty-but-arbiter-safe worktree does not linger to poison the next
+            //    build's config-read/materialisation fetch. A worktree whose work is NOT
+            //    yet on the arbiter is RETAINED either way (never lose work). NEVER
+            //    --force.
+            if (tree) {
+                const reachableOnly = result !== undefined && result.outcome !== 'completed';
+                tree.teardown({ reachableOnly });
+            }
+        }
+    }
+    finally {
+        // Remove the throwaway claim clone either way.
+        rmSync(claimDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Best-effort reap of a worktree that {@link IsolationStrategy.prepare}/`createJob`
+ * may have created at the deterministic per-job path BEFORE it threw (so the
+ * handle was never returned and the normal teardown is skipped). Reaps it ONLY
+ * if its branch is provably reachable on the arbiter — a `prepare` throw can
+ * happen AFTER a clean continue-push (work is safe ⇒ reap so it can't poison the
+ * next build) or BEFORE any push (work not safe ⇒ retain; never lose work). All
+ * git ops are swallowed: this runs on an already-failing path and must never mask
+ * the original throw.
+ */
+function reapPreparedWorktreeLeak(mirrorUrl, slug, workspacesDir, env, note) {
+    try {
+        const dir = jobWorktreePath(workspacesDir, mirrorUrl, slug);
+        if (!existsSync(dir)) {
+            return;
+        }
+        const mirrorDir = mirrorPath(workspacesDir, mirrorUrl);
+        const result = reapJob({
+            dir,
+            branch: workBranchRef('task', slug),
+            mirrorPath: mirrorDir,
+            // Same failure-path stance as the normal teardown: reachable-on-arbiter is
+            // enough (don't let incidental churn retain a worktree whose branch is
+            // already safe). Reachability still gates — unsaved work is retained.
+            reachableOnly: true,
+            env,
+        });
+        if (result.removed) {
+            note(`Reaped leaked worktree for ${slug} after prepare() threw ` +
+                `(branch safe on the arbiter).`);
+        }
+    }
+    catch {
+        // best-effort — never mask the original prepare() throw
+    }
+}
+/**
+ * Run the existing `do` pipeline (start[resume] → agent → complete) against an
+ * already-materialised job worktree. Mirrors {@link performDo}'s middle/back —
+ * but `cwd` is the worktree and the arbiter remote inside it is `origin`. The
+ * needs-attention surfacing is the AUTONOMOUS, arbiter-passed variant (like
+ * `run`/in-place `do`): a stuck remote `do` must be cross-machine visible.
+ */
+async function runRemotePipeline(options, tree, slug, note, env) {
+    const cwd = tree.dir;
+    const arbiterRemote = tree.arbiterRemote; // `origin` (the bare mirror's clone).
+    // 4a. CONTINUE rebase conflict (ADR §14 + §10): a requeue kept a `work/<slug>`
+    //     that did not replay onto the current main at onboard-time (aborted, never
+    //     auto-resolved). Route to needs-attention via the seam (surfaced on the
+    //     arbiter + the kept branch already on the arbiter) instead of running the
+    //     agent — the §10 path `run` uses.
+    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';
+        await ledgerWrite.applyNeedsAttentionTransition({
+            cwd,
+            slug,
+            reason,
+            arbiter: arbiterRemote,
+            env,
+            note,
+        });
+        return {
+            exitCode: 1,
+            outcome: 'needs-attention',
+            slug,
+            branch: tree.branch,
+            message: reason,
+        };
+    }
+    // 4b. CONTINUE reconcile-push TERMINAL failure (the stale-lease-strand bug this
+    //     fix kills): the onboard reconcile push of the kept (already-committed)
+    //     work branch to the arbiter FAILED terminally (the stale-lease retry cap
+    //     exhausted, or a non-stale-lease rejection / unreachable arbiter). The push
+    //     helper THROWS; `createJob` CATCHES it and flags `continuePushFailure`
+    //     rather than letting the throw escape (which crashed the run and left the
+    //     task silently in `work/in-progress/` on the arbiter, the work stranded in
+    //     the worktree). Route to needs-attention via the SAME seam the conflict path
+    //     uses — surfaced on the arbiter, the kept branch already on the arbiter from
+    //     the prior requeue (recoverable) — 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';
+        await ledgerWrite.applyNeedsAttentionTransition({
+            cwd,
+            slug,
+            reason,
+            arbiter: arbiterRemote,
+            env,
+            note,
+        });
+        return {
+            exitCode: 1,
+            outcome: 'needs-attention',
+            slug,
+            branch: tree.branch,
+            message: reason,
+        };
+    }
+    // 5. HARDEN start to work against a job-worktree `cwd` (the load-bearing work).
+    //    `performStart` reads/switches via the `<arbiter>/main` REMOTE-TRACKING ref
+    //    (`origin/main` here). A job worktree is cut from a BARE hub mirror whose
+    //    `origin` remote has NO fetch refspec, so `origin/main` /
+    //    `origin/work/<slug>` would not otherwise resolve — and `start` would
+    //    wrongly read the slug as "absent". Prime those two remote-tracking refs
+    //    EXPLICITLY (the SAME technique `integrator.rebaseOntoArbiterMain` /
+    //    `gc.fetchTracking` use against a bare-mirror worktree). After this the
+    //    existing `performStart` runs UNCHANGED against the worktree.
+    await primeWorktreeTrackingRef(cwd, arbiterRemote, 'main', env);
+    await primeWorktreeTrackingRef(cwd, arbiterRemote, workBranchRef('task', slug), env);
+    // Onboard onto the work branch like in-place `do` — but the item is ALREADY
+    // CLAIMED (step 3), so `performStart` runs with `resume: true`: it
+    // PLAIN-SWITCHES the `work/<slug>` branch `createJob` already created WITHOUT
+    // re-claiming (no double-claim, no branch fight). This proves `start` works
+    // against a job-worktree `cwd`.
+    const started = await performStart({
+        slug,
+        cwd,
+        arbiter: arbiterRemote,
+        resume: true,
+        // `--allow-backlog`: a staged body (claimed, still in `tasks/backlog/`) is a
+        // valid onboard residence; without this `start` would read it as `absent`.
+        allowBacklog: options.allowBacklog === true,
+        env,
+        note,
+    });
+    if (started.outcome === 'needs-attention') {
+        return {
+            exitCode: 1,
+            outcome: 'needs-attention',
+            slug,
+            branch: started.branch,
+            message: started.message,
+        };
+    }
+    // FORWARD the honest un-moved signal end-to-end: a continue-site surface that
+    // did NOT land on the arbiter (start's `surface-unmoved`) must NOT degrade to
+    // `usage-error` here — the item is still in-progress on the arbiter (retry/resolve).
+    if (started.outcome === 'surface-unmoved') {
+        return {
+            exitCode: 1,
+            outcome: 'surface-unmoved',
+            slug,
+            branch: started.branch,
+            message: started.message,
+        };
+    }
+    if (started.exitCode !== 0) {
+        const outcome = started.outcome === 'refused' ? 'refused' : 'usage-error';
+        return { exitCode: 1, outcome, slug, message: started.message };
+    }
+    const branch = started.branch;
+    // 6. Build the prompt + run the agent autonomously in the worktree (the SAME
+    //    assembly in-place `do` uses). The agent only edits code.
+    let prompt;
+    try {
+        // CONTINUE-aware resolution (job-worktree path): admit `work/done/` ONLY
+        // behind the tip-vs-arbiter stranded gate (story 5), using the worktree's
+        // primed `<origin>/work/<slug>` vs `<origin>/main` tracking refs.
+        const task = resolveTask(cwd, slug, {
+            cwd,
+            branchRef: `${arbiterRemote}/${branch}`,
+            mainRef: `${arbiterRemote}/main`,
+            env,
+        }, 
+        // `--allow-backlog`: also resolve a `tasks/backlog/`-resident body.
+        { allowBacklog: options.allowBacklog === true });
+        // CONTINUE-mode (job-worktree path): the worktree's tracking refs were primed
+        // above (`primeWorktreeTrackingRef`), so reuse the SAME continue-detection with
+        // the worktree's `<origin>/work/<slug>` vs `<origin>/main` refs.
+        const continueContext = resolveContinueContext({
+            cwd,
+            slug,
+            arbiter: arbiterRemote,
+            branchRef: `${arbiterRemote}/${branch}`,
+            mainRef: `${arbiterRemote}/main`,
+            content: readFileSync(task.path, 'utf8'),
+            env,
+        });
+        // Per-item override layer (mirrors in-place `do`): the task/prd frontmatter
+        // may override the resolved repo `promptGuidance.testFirst` for THIS item.
+        const itemGuidance = resolvePromptGuidanceForItem({
+            cwd,
+            repoResolved: { testFirst: options.promptGuidance?.testFirst === true },
+            taskContent: readFileSync(task.path, 'utf8'),
+        });
+        prompt = buildAgentPrompt(task.slug, task.prd, task.taskPrompt, {
+            cwd,
+            continueContext,
+            promptGuidance: itemGuidance,
+        });
+    }
+    catch (err) {
+        if (err instanceof PromptError) {
+            return await saveRemoteAgentFailure({
+                slug,
+                branch,
+                cwd,
+                arbiterRemote,
+                detail: err.message,
+                env,
+                note,
+            });
+        }
+        throw err;
+    }
+    let agent;
+    try {
+        agent = await runDoAgent(options, cwd, prompt, slug);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return await saveRemoteAgentFailure({
+            slug,
+            branch,
+            cwd,
+            arbiterRemote,
+            detail: message,
+            env,
+            note,
+        });
+    }
+    if (!agent.ok) {
+        const detail = agent.detail ?? `the agent failed to build '${slug}'.`;
+        return await saveRemoteAgentFailure({
+            slug,
+            branch,
+            cwd,
+            arbiterRemote,
+            detail,
+            env,
+            note,
+        });
+    }
+    // 6b. HONOR a deliberate STOP (task `agent-stop-signal`) — the SAME detection
+    //     in-place `do` runs, shared via `resolveStopReason`/`saveAgentStop`. A
+    //     sentinel STOP (verbatim reason) or an empty work-branch diff routes to
+    //     needs-attention (surfaced on the arbiter) and SKIPS the gate + Gate-2. The
+    //     diff base is the worktree's `origin` (arbiterRemote).
+    const stopReason = await resolveStopReason({
+        output: agent.output,
+        slug,
+        cwd,
+        arbiter: arbiterRemote,
+        env,
+    });
+    if (stopReason !== undefined) {
+        return await saveAgentStop({
+            slug,
+            branch,
+            cwd,
+            arbiter: arbiterRemote,
+            reason: stopReason,
+            env,
+            note,
+        });
+    }
+    // 7. Gate + done-move + commit + rebase + integrate LIKE in-place `do`: the
+    //    AUTONOMOUS surfacing (`surfaceArbiter: origin`) so a red gate / rebase
+    //    conflict / review block surfaces on the arbiter's main (cross-machine
+    //    visible). The success path reuses `complete`'s machinery unchanged.
+    const completed = await performComplete({
+        slug,
+        cwd,
+        arbiter: arbiterRemote,
+        integration: options.integration,
+        // An explicit `--merge` overrides the untrusted-origin build-propose rule (task
+        // `untrusted-origin-forces-build-propose`); unset on the autonomous path so
+        // untrusted-origin reliably forces propose.
+        explicitMerge: options.explicitMerge,
+        // SCOPE: the divergence guard is in-place only. A job worktree is cut fresh off
+        // the bare mirror and never ff's the operator's local main, so the guard does
+        // not apply here — opt out explicitly (the task: do NOT touch do --remote/run).
+        ignoreDivergedMain: true,
+        // `--allow-backlog`: a staged build sources from `tasks/backlog/` (gated on
+        // the flag; otherwise a staged strand still refuses). Default off.
+        allowBacklog: options.allowBacklog === true,
+        prepare: options.prepare,
+        verify: options.verify,
+        freshWorktreeGate: options.freshWorktreeGate,
+        // The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) — see
+        // the in-place site above for the rationale; mirrored here so the no-checkout
+        // `do --remote`/`--isolated` path threads the same resolved cap.
+        mergeRetries: options.mergeRetries,
+        noPR: options.noPR,
+        providerInstance: options.providerInstance,
+        body: agent.output,
+        review: options.review,
+        reviewModel: options.reviewModel,
+        reviewMaxRounds: options.reviewMaxRounds,
+        reviewGate: options.reviewGate,
+        watch: options.watch,
+        watchSink: options.watchSink,
+        sessionsDir: options.sessionsDir,
+        surfaceArbiter: arbiterRemote,
+        color: options.color,
+        note,
+        noteBlock: options.noteBlock,
+        env,
+        // 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 carry identity).
+        agentEnv: options.env,
+    });
+    if (completed.outcome === 'completed' ||
+        completed.outcome === 'already-integrated') {
+        // Stranded-done auto-recover's clean no-op folds into `completed` here too
+        // (see the in-place performDo handler for the rationale): same SHARED
+        // `complete.ts` seam — so `do --remote` (this `performDoRemote`) inherits
+        // the auto-recover without per-caller duplication.
+        return {
+            exitCode: 0,
+            outcome: 'completed',
+            slug,
+            branch,
+            message: completed.message,
+        };
+    }
+    if (completed.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 → `transient-infra` (re-run
+        // the SAME work), the SAME convergence in-place `do`/`run` apply, so `do --remote`
+        // agrees on the label. The job worktree is RETAINED by the §4 reap (a
+        // not-provably-safe tree); hand the operator the recover-one-liner like the other
+        // retained-tree failures.
+        note(recoverIsolatedOneLiner(slug));
+        const cause = classifyFailureCause(completed.message);
+        return {
+            exitCode: 1,
+            outcome: failureCauseToDoOutcome(cause),
+            slug,
+            branch,
+            message: completed.message,
+        };
+    }
+    if (completed.outcome === 'prepare-failed' ||
+        completed.outcome === 'gate-failed' ||
+        completed.outcome === 'review-blocked' ||
+        completed.outcome === 'rebase-conflict' ||
+        completed.outcome === 'strand-surfaced') {
+        // The job worktree is RETAINED (the §4 reap keeps a not-provably-safe tree).
+        // When the work was committed + done-moved but the integrate failed terminally
+        // (the stale-lease-strand class Part B #97 surfaces), the operator FINISHES the
+        // stranded branch with the recover-already-committed path \u2014 hand them the EXACT
+        // one-liner so they need not reverse-engineer the encoded worktree path.
+        //
+        // `strand-surfaced` is the autonomous-strand parity (the SHARED `complete.ts`
+        // seam already surfaced the source-strand / empty-staged refusal to
+        // needs-attention on the arbiter) — `do --remote` inherits the fix here
+        // without per-caller duplication; mapped to the SAME `needs-attention`
+        // outcome shape the in-place `performDo` uses.
+        note(recoverIsolatedOneLiner(slug));
+        return {
+            exitCode: 1,
+            outcome: 'needs-attention',
+            slug,
+            branch,
+            message: completed.message,
+        };
+    }
+    if (completed.outcome === 'surface-unmoved') {
+        // Strand-surface could not land on the arbiter (CAS contention exhausted) —
+        // HONESTLY still in-progress on the arbiter. Mirror in-place `performDo`'s
+        // `surface-unmoved` mapping so `do --remote` agrees on the same signal.
+        return {
+            exitCode: 1,
+            outcome: 'surface-unmoved',
+            slug,
+            branch,
+            message: completed.message,
+        };
+    }
+    // Reclassify a thrown CORE wiring/config error (swallowed into `usage-error` by
+    // `performComplete`) onto `config-error` — the SAME convergence in-place `do`
+    // applies, so `do --remote` agrees with `do`/`run` on the same error too.
+    if (completed.outcome === 'usage-error') {
+        const cause = classifyFailureCause(completed.message);
+        if (cause === 'config-error') {
+            return {
+                exitCode: 1,
+                outcome: 'config-error',
+                slug,
+                branch,
+                message: completed.message,
+            };
+        }
+    }
+    const outcome = completed.outcome === 'refused' ? 'refused' : 'usage-error';
+    return { exitCode: 1, outcome, slug, branch, message: completed.message };
+}
+/**
+ * SAVE the partial work of a FAILED agent in a remote `do` worktree — the same
+ * work-preserving routing in-place `do`'s {@link saveAgentFailure} uses, but
+ * against the worktree's `origin` arbiter remote. The agent's edits + the failure
+ * reason are committed + surfaced on the arbiter's main AND the `work/<slug>`
+ * branch is pushed (the RECOVERABLE durable artifact — the disposable worktree is
+ * NOT the recovery surface). The outcome is the classified failure CAUSE
+ * (`transient-infra` / `config-error` / the generic `agent-failed`), same as the
+ * in-place form.
+ */
+async function saveRemoteAgentFailure(params) {
+    const { slug, cwd, arbiterRemote, detail, env, note } = params;
+    const branch = params.branch ?? workBranchRef('task', slug);
+    // Same best-effort cause classification as in-place `do`'s `saveAgentFailure`
+    // (shared `classifyFailureCause`), so the remote form labels the SAME error the
+    // SAME way too.
+    const cause = classifyFailureCause(detail);
+    const reason = `${failureCauseLabel(cause)}: ${detail}`;
+    const routed = await ledgerWrite.applyNeedsAttentionTransition({
+        cwd,
+        slug,
+        reason,
+        arbiter: arbiterRemote,
+        env,
+        note,
+    });
+    const report = routed.moved ? routeReport(routed, branch) : undefined;
+    const message = routed.moved
+        ? `Agent run failed building '${slug}' [${cause}] (${detail}); SAVED the ` +
+            `partial work and marked '${slug}' stuck on its lock (${report.fragment}).`
+        : `Agent run failed building '${slug}' [${cause}] (${detail}); could not ` +
+            `mark '${slug}' stuck (${routed.reasonNotMoved ?? 'unknown'}).`;
+    note(message);
+    return {
+        exitCode: 1,
+        outcome: failureCauseToDoOutcome(cause),
+        slug,
+        branch,
+        routedToNeedsAttention: routed.moved,
+        message,
+    };
+}
+/**
+ * Prime ONE arbiter head into its remote-tracking ref inside a job worktree
+ * (`+refs/heads/<head>:refs/remotes/<arbiter>/<head>`). A job worktree is cut
+ * from a BARE hub mirror whose `origin` remote has no fetch refspec, so
+ * `<arbiter>/main` / `<arbiter>/work/<slug>` would not otherwise resolve — which
+ * makes the (otherwise unchanged) `performStart` read the slug as absent. This is
+ * the EXACT technique `integrator.rebaseOntoArbiterMain` + `gc.fetchTracking`
+ * already use for the same bare-mirror-worktree reason. Best-effort: an
+ * unreachable arbiter / a missing head leaves the local ref absent, which `start`
+ * then handles (the FRESH branch already exists locally from `createJob`).
+ */
+async function primeWorktreeTrackingRef(cwd, arbiter, head, env) {
+    // SOFT (no throw): the head may not exist on the arbiter (e.g. a FRESH cut has
+    // no pushed `work/<slug>` yet) — that is the common, expected case, and `start`
+    // handles a missing remote-tracking ref (the local branch `createJob` created
+    // is plain-switched). A genuine fetch error likewise leaves the ref absent →
+    // the safe direction.
+    await runAsync('git', [
+        'fetch',
+        '--quiet',
+        arbiter,
+        `+refs/heads/${head}:refs/remotes/${arbiter}/${head}`,
+    ], cwd, { env });
+}
+/**
+ * Adapt the IN-PLACE {@link DoOptions} build/task driver onto the WORKTREE-
+ * ISOLATED {@link performDoRemote} pipeline (task
+ * `advance-loop-driver-registry-set-job-worktrees`) — the per-mirror job-worktree
+ * `doDriver` the registry-set advance driver threads into the advance tick.
+ *
+ * The advance tick's build/task rung ORCHESTRATES `do` by calling the
+ * {@link AdvanceContext.doDriver} seam with a resolved {@link DoOptions} (whose
+ * `cwd` is the per-mirror in-place checkout). The DEFAULT driver is
+ * {@link performDo} (in-place, the cwd checkout IS the isolation — the human-local
+ * one-shot `advance` + today's `run --advance`). The DAEMON/CI registry-set path
+ * wants the SAME per-job-worktree isolation `run`'s build tick gives `runOneItem`,
+ * so it injects THIS driver instead: it re-routes the orchestration onto
+ * {@link performDoRemote}, which materialises a hub mirror + job worktree off the
+ * mirror's arbiter via the EXISTING `jobWorktreeStrategy` (no second isolation
+ * mechanism), runs the SAME `do` pipeline there, and reaps per the §4 predicate.
+ * The cwd checkout is NEVER touched (the equivalence the task asserts vs plain
+ * `run`).
+ *
+ * The pipeline knobs (verify / integration / review family / agent launch /
+ * identity) ride VERBATIM from the threaded `DoOptions` onto the structurally-
+ * matching {@link DoRemoteOptions} fields; `cwd` is DROPPED (the worktree replaces
+ * it) and `remote` + `workspacesDir` are supplied from this driver's closure (the
+ * mirror's arbiter URL + the agents' execution area). A `prd:` arg flows through
+ * unchanged — `performDoRemote` tasks it against the claim clone with NO build
+ * worktree (the tasking/surface/triage/apply rungs are tree-less ledger moves, the
+ * substrate the task's criterion 4 preserves).
+ */
+export function jobWorktreeDoDriver(closure) {
+    return (options) => {
+        // Map the in-place DoOptions onto the worktree DoRemoteOptions. `cwd` is
+        // intentionally DROPPED (the worktree is the isolation, not the checkout);
+        // every other pipeline knob rides verbatim onto its structural twin.
+        const remoteOptions = {
+            arg: options.arg,
+            remote: closure.remote,
+            workspacesDir: closure.workspacesDir,
+            arbiter: options.arbiter,
+            identity: options.identity,
+            autoTask: options.autoTask,
+            reviewLoop: options.reviewLoop,
+            taskerLoopMax: options.taskerLoopMax,
+            taskerLoopModel: options.taskerLoopModel,
+            reviewExecutions: options.reviewExecutions,
+            integration: options.integration,
+            // The explicit `--merge` override for the untrusted-origin build-propose rule.
+            explicitMerge: options.explicitMerge,
+            prepare: options.prepare,
+            verify: options.verify,
+            noPR: options.noPR,
+            review: options.review,
+            reviewModel: options.reviewModel,
+            reviewMaxRounds: options.reviewMaxRounds,
+            reviewGate: options.reviewGate,
+            taskReviewGate: options.taskReviewGate,
+            dorfl: options.dorfl,
+            harness: options.harness,
+            agentCmd: options.agentCmd,
+            model: options.model,
+            sessionsDir: options.sessionsDir,
+            watch: options.watch,
+            watchSink: options.watchSink,
+            color: options.color,
+            read: options.read,
+            env: options.env,
+            note: options.note,
+            noteBlock: options.noteBlock,
+        };
+        return performDoRemote(remoteOptions);
+    };
+}
+//# sourceMappingURL=do.js.map