dorfl 0.1.1 → 0.2.0

package/dist/do.js

@@ -21,11 +21,162 @@ import { shouldFailProposePrIntent, PROPOSE_PR_INTENT_GH_UNAVAILABLE_MESSAGE, }
 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 { parseStopSentinel, isWorkBranchDiffEmpty, emptyDiffStopReason, emptyDiffDisposeEnvelope, } from './agent-stop.js';
+import { surfaceStuckToNeedsAttention, routeToNeedsAttention, } from './needs-attention.js';
+import { resolveItemPathByIdentity } from './item-path.js';
 import { classifyFailureCause, failureCauseLabel, } from './failure-cause.js';
+/**
+ * `dorfl do <slug>` (in-place form) — the per-repo, in-place WORKER that
+ * claims + builds + gates + integrates in ONE checkout, then EXITS (ADR §3).
+ * **This is the CI command** (CI has a checkout, is one repo, is one triggered
+ * invocation, exits) and it ABSORBS the manual `ar-run.sh` test-driver.
+ *
+ * In-place `do` is on the ISOLATION SEAM (`do-run-share-isolation-seam`): it is
+ * the FIRST production consumer of `selectIsolationStrategy`/`inPlaceStrategy`,
+ * so all THREE `do`/`run` forms (in-place `do`, `do --remote`, `run`) share the
+ * ONE `IsolatedTree`-handle post-claim shape. The composition mirrors
+ * `do --remote`/`run` exactly: keep the two in-place GUARDS (dirty-tree refusal
+ * + pre-flight diverged-main guard) in this driver BEFORE onboarding, CLAIM
+ * explicitly via the CAS (`performClaim`), then let
+ * `selectIsolationStrategy({checkout}).prepare()` do the ONBOARDING half (fetch +
+ * continue-detection + fresh-main `work/<slug>` switch, incl. the §14
+ * continue/rebase + §10 conflict path) WITHOUT re-claiming. The agent run is the
+ * ONLY new middle step (the one `ar-run.sh` shelled out for, `prompt | pi`). The
+ * runner owns EVERY git-state transition (claim, done-move, completion commit,
+ * integration); the agent only edits code.
+ *
+ * The in-place ISOLATION (ADR §3): the current checkout / CI container IS the
+ * isolation — no hub mirror, no external worktree. `inPlaceStrategy.prepare()`
+ * puts the checkout on `work/<slug>` cut from the freshly-fetched
+ * `<arbiter>/main`; its handle's `teardown` is a NO-OP (the checkout is left in a
+ * defined state on `work/<slug>`, NEVER reaped). `do --remote` (the job-worktree
+ * strategy) is the SEPARATE `do-remote` task; auto-pick / multi-arg / `-n` is
+ * `do-autopick`.
+ *
+ * CLAIM SEMANTICS (autonomous, same as `do --remote`/`run`): the claim is
+ * explicit and claim-or-lose. An item that is NOT in the pool (`tasks-ready`) on
+ * the arbiter (already in-progress / done / absent) is not claimable, so the CAS
+ * returns
+ * `lost` (exit 2) and the run skips cleanly — `do`, the unattended CI worker,
+ * never re-claims an item someone else holds and never silently picks up a
+ * needs-attention item (a human does that through the human face).
+ *
+ * **CRITICAL — `do` is AUTONOMOUS, so its failure path is `run`'s, NOT
+ * `complete`'s.** On a red gate / rebase conflict, `performComplete` routes the
+ * item to needs-attention via the SAME seam call as `run`'s `runOneItem`, but
+ * `complete` calls it WITHOUT an arbiter (the human path: a human is right
+ * there). `do` runs UNATTENDED, so it MUST get the autonomous, arbiter-passed
+ * surfacing like `run` (the on-`main` cherry-pick that makes a stuck CI run
+ * visible to `scan`/`status`/another machine). We achieve this by passing
+ * `surfaceArbiter` into `performComplete` (resolution (a) from the task): the
+ * success path reuses `complete`'s machinery; only the NEEDS-ATTENTION routing
+ * becomes the autonomous variant.
+ *
+ * `--propose` (default) / `--merge` is resolved at integrate-time exactly like
+ * `complete` (the caller threads the resolved mode in as `integration`).
+ */
+/**
+ * The commit-message subject the deadline-checkpoint save writes, and the
+ * pattern used to COUNT consecutive checkpoints on the branch (spec
+ * `graceful-pre-timeout-wip-checkpoint` — the anti-loop ceiling). Living
+ * on-branch means the counter naturally RESETS when the item completes (the
+ * branch is discarded on integration) and when a `--reset` requeue discards
+ * the branch: a genuinely-progressing task cannot silently accumulate a
+ * ceiling breach across generations.
+ */
+const DEADLINE_CHECKPOINT_COMMIT_SUBJECT_PREFIX = 'chore(deadline-checkpoint)';
+/**
+ * Distinct reason strings for the two deadline-checkpoint branches (spec
+ * `graceful-pre-timeout-wip-checkpoint` — the CI/human report must NEVER
+ * collapse to a generic "agent-failed"). Auto-continue and surface carry
+ * different phrasing so the counter + ceiling are legible.
+ */
+function deadlineAutoContinueReason(params) {
+    return (`deadline checkpoint (auto-continued ${params.count}/${params.max}): ` +
+        `'${params.slug}' hit the dorfl-internal deadline with new work-branch ` +
+        `progress this session; saved the WIP and released the lock so the next ` +
+        `tick continues from the branch tip.`);
+}
+function deadlineSurfaceReason(params) {
+    if (params.kind === 'no-progress') {
+        return (`deadline checkpoint (no progress / ceiling): '${params.slug}' hit ` +
+            `the dorfl-internal deadline WITHOUT any work-branch progress this ` +
+            `session — indistinguishable from a wedge; surfaced for a human to ` +
+            `decide (continue / split / cancel).`);
+    }
+    return (`deadline checkpoint (no progress / ceiling): '${params.slug}' has hit ` +
+        `the dorfl-internal deadline ${params.count}/${params.max} times ` +
+        `consecutively — it may be too big for one CI leg. Split it or run ` +
+        `it locally; surfaced for a human to decide.`);
+}
+/**
+ * Count how many DEADLINE-CHECKPOINT commits (subject prefix
+ * `chore(deadline-checkpoint)`) currently sit on the work branch ahead of
+ * `<arbiter>/main` — the branch-based anti-loop counter (spec
+ * `graceful-pre-timeout-wip-checkpoint`). A best-effort count: an unreachable
+ * arbiter / a bare mirror reads as 0 (the SAFE direction — never falsely block
+ * an auto-continue) so a genuine plumbing fault degrades to "under the ceiling"
+ * rather than surfacing a spurious ceiling breach. Resets naturally when the
+ * item completes (the branch is discarded on integration).
+ */
+async function countDeadlineCheckpointsOnBranch(params) {
+    const { cwd, arbiter, branch, env } = params;
+    const range = `${arbiter}/main..HEAD`;
+    void branch;
+    const r = await runAsync('git', ['log', '--format=%s', range], cwd, { env });
+    if (r.status !== 0) {
+        return 0;
+    }
+    const lines = r.stdout.split('\n').filter((s) => s.length > 0);
+    return lines.filter((s) => s.startsWith(DEADLINE_CHECKPOINT_COMMIT_SUBJECT_PREFIX)).length;
+}
+/**
+ * SAVE the WIP on a deadline stop (spec `graceful-pre-timeout-wip-checkpoint`,
+ * build step 3): commit the tree as-is + push `work/<slug>`. Reuses the SAVE
+ * HALF of the needs-attention mechanism ({@link routeToNeedsAttention}) but
+ * ADDS a distinguishing checkpoint-marker commit on top so
+ * {@link countDeadlineCheckpointsOnBranch} can count auto-continues. Distinct
+ * from `applyNeedsAttentionTransition` (the whole thing) which ALSO marks the
+ * lock stuck — auto-continue must NOT mark stuck; only the surface branch does.
+ */
+async function saveDeadlineCheckpoint(params) {
+    const { slug, branch, cwd, arbiter, reason, env, note } = params;
+    void reason;
+    // Save any uncommitted work first (the routeToNeedsAttention save half also
+    // commits + pushes; but we ALSO want a distinct checkpoint-marker commit so
+    // countDeadlineCheckpointsOnBranch can enumerate them). Stage everything and
+    // commit a MARKER commit if there's anything to record OR if there is not
+    // already a marker on the tip — the marker's job is to make the checkpoint
+    // COUNTABLE, not to represent new work.
+    const addResult = await runAsync('git', ['add', '-A'], cwd, { env });
+    void addResult;
+    const diffCached = await runAsync('git', ['diff', '--cached', '--quiet'], cwd, { env });
+    const hasStaged = diffCached.status !== 0;
+    if (hasStaged) {
+        await runAsync('git', [
+            'commit',
+            '-q',
+            '-m',
+            `${DEADLINE_CHECKPOINT_COMMIT_SUBJECT_PREFIX}: save wip for '${slug}'`,
+        ], cwd, { env });
+    }
+    // Push the branch to the arbiter (best-effort). Reuse routeToNeedsAttention's
+    // save-half exact contract: it commits any residue + pushes the branch with
+    // bounded backoff. We already committed above; the wip commit inside
+    // routeToNeedsAttention will be a no-op (clean tree) and the push runs.
+    return routeToNeedsAttention({
+        cwd,
+        slug,
+        reason: `deadline-checkpoint save for '${slug}' (see branch)`,
+        arbiter,
+        branch,
+        note,
+        env,
+    });
+}
 const DEFAULT_ARBITER = 'origin';
 /**
- * Map a `do prd:<slug>` {@link TaskResult} onto the `do` {@link DoResult}
+ * Map a `do spec:<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
@@ -60,7 +211,7 @@ function taskResultToDoResult(tasked) {
             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
+            // spec to needs-attention (no guessed tasks). Same exit class as a stuck
             // build (1).
             outcome = 'needs-attention';
             exitCode = 1;
@@ -119,8 +270,8 @@ export async function performDo(options) {
         };
     }
     // 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
+    //    spans them (ADR §3a): bare → task (after a no-spec-collision check;
+    //    ERROR on collision), `task:`/`spec:` explicit. A collision / resolution
     //    failure is a loud usage error (exit 1).
     let resolved;
     try {
@@ -152,10 +303,10 @@ export async function performDo(options) {
             arbiter,
             doer: 'agent',
             autoTask: options.autoTask,
-            // EXPLICIT dispatch: a `do prd:<slug>` target was NAMED (the operator typed
+            // EXPLICIT dispatch: a `do spec:<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
+            // drops the `autoTask` policy term and binds only the spec'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).
@@ -176,19 +327,24 @@ export async function performDo(options) {
             // `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 cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) —
+            // threaded so the `do spec:` tasking-transition's land tail respects the
+            // same per-repo cap the build path uses (task
+            // `thread-merge-retries-cross-task-and-ratify-default`).
+            mergeRetries: options.mergeRetries,
             // 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.
+            // spec'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.
+            // needs-attention sink. Threaded only on the `do spec:` path; omitted ⇒ no loop.
             reviewLoop: options.reviewLoop,
             taskerLoopMax: options.taskerLoopMax,
             reviewExecutions: options.reviewExecutions,
@@ -362,14 +518,17 @@ export async function performDo(options) {
     //     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
+    //     arbiter, after-commit, recoverable). The surface is purely the lock amend
+    //     to `state: stuck` with the reason (post lock-cutover — no folder move, 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';
+            'conflicted (aborted, never auto-resolved) — run `requeue --reconcile` ' +
+            'to non-destructively re-sync the mirror and retry the rebase (keeps ' +
+            'the work). Last resort: `requeue --reset` DESTRUCTIVELY discards the ' +
+            'branch and starts fresh.';
         const surfaced = await ledgerWrite.applyTreelessNeedsAttentionTransition({
             cwd: tree.dir,
             slug,
@@ -401,8 +560,10 @@ export async function performDo(options) {
     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';
+            'branch is left intact on the arbiter (recoverable); `requeue --reconcile` ' +
+            'to non-destructively re-sync the mirror and retry once the churn ' +
+            'settles (keeps the work). Last resort: `requeue --reset` DESTRUCTIVELY ' +
+            'discards the branch and starts fresh.';
         const surfaced = await ledgerWrite.applyTreelessNeedsAttentionTransition({
             cwd: tree.dir,
             slug,
@@ -424,7 +585,7 @@ export async function performDo(options) {
     }
     // 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
+    //    source spec + 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`)
@@ -459,7 +620,7 @@ export async function performDo(options) {
             content: readFileSync(task.path, 'utf8'),
             env,
         });
-        // Per-item override layer: a task or prd may pin `promptGuidance.testFirst`
+        // Per-item override layer: a task or spec may pin `promptGuidance.testFirst`
         // in its frontmatter, superseding the resolved repo policy for THIS item.
         const itemGuidance = resolvePromptGuidanceForItem({
             cwd: tree.dir,
@@ -502,6 +663,23 @@ export async function performDo(options) {
             note,
         });
     }
+    // DEADLINE CHECKPOINT (spec `graceful-pre-timeout-wip-checkpoint`): the
+    // dorfl-internal deadline fired — stop is graceful, NOT a failure. Route
+    // through the shared checkpoint path (save WIP + auto-continue on progress
+    // under the ceiling, else surface). Distinct from `saveAgentFailure` on
+    // purpose — the deadline path must NOT mark the item stuck when it
+    // auto-continues.
+    if (agent.timedOut) {
+        return await routeDeadlineCheckpoint({
+            slug,
+            branch,
+            cwd: tree.dir,
+            arbiter: tree.arbiterRemote,
+            maxAutoCheckpoints: options.maxAutoCheckpoints ?? 5,
+            env,
+            note,
+        });
+    }
     if (!agent.ok) {
         const detail = agent.detail ?? `the agent failed to build '${slug}'.`;
         return await saveAgentFailure({
@@ -535,7 +713,8 @@ export async function performDo(options) {
             branch,
             cwd: tree.dir,
             arbiter: tree.arbiterRemote,
-            reason: stopReason,
+            reason: stopReason.reason,
+            kind: stopReason.kind,
             env,
             note,
         });
@@ -587,7 +766,7 @@ export async function performDo(options) {
         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-
+        // git-alone FLOOR of the cross-job land queue (spec `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,
@@ -682,8 +861,10 @@ export async function performDo(options) {
         // (`runRemotePipeline`) uses, so `advance task:<slug>` (via the default
         // `doDriver = performDo`) agrees with the remote path on the caller-visible
         // label.
+        //
+        // PR-2b D3: a clean surface (routedToNeedsAttention:true) is GREEN.
         return {
-            exitCode: 1,
+            exitCode: completed.routedToNeedsAttention ? 0 : 1,
             outcome: 'needs-attention',
             slug,
             branch,
@@ -770,7 +951,9 @@ function routeReport(routed, branch) {
         // 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',
+                'when online, then `requeue` (continue) or `requeue --reconcile` ' +
+                '(non-destructive retry). Last resort: `requeue --reset` ' +
+                'DESTRUCTIVELY discards.',
             pushFailed: true,
         };
     }
@@ -787,7 +970,9 @@ function routeReport(routed, branch) {
         landed = 'saved locally';
     }
     return {
-        fragment: `${landed}. Recover via \`requeue\` (continue) or \`requeue --reset\` to discard`,
+        fragment: `${landed}. Recover via \`requeue\` (continue) or \`requeue --reconcile\` ` +
+            '(non-destructive retry). Last resort: `requeue --reset` ' +
+            'DESTRUCTIVELY discards.',
         pushFailed: false,
     };
 }
@@ -800,10 +985,12 @@ function routeReport(routed, branch) {
  *
  * 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.
+ * capturing the agent's work, then — post lock-cutover — a LOCK AMEND to
+ * `state: stuck` with the failure detail as the reason on the lock entry, in
+ * place of the retired `git mv → needs-attention/` move-only commit), 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`
@@ -826,7 +1013,8 @@ function routeReport(routed, branch) {
  * 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).
+ * `requeue` (continue) / `requeue --reconcile` (non-destructive retry) vs
+ * `requeue --reset` (destructive last resort).
  */
 async function saveAgentFailure(params) {
     const { slug, cwd, arbiter, detail, env, note } = params;
@@ -864,8 +1052,10 @@ async function saveAgentFailure(params) {
         : `Agent run failed building '${slug}' [${cause}] (${detail}); could not ` +
             `mark '${slug}' stuck (${routed.reasonNotMoved ?? 'unknown'}).`;
     note(message);
+    // PR-2b D3: a cleanly-surfaced bounce is GREEN (exitCode 0); a FAILED surface
+    // stays non-zero.
     return {
-        exitCode: 1,
+        exitCode: routed.moved ? 0 : 1,
         outcome: failureCauseToDoOutcome(cause),
         slug,
         branch,
@@ -884,7 +1074,9 @@ function failureCauseToDoOutcome(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
+ * arbiter (`{moved: false}`). The tree-less stuck-lock amend (post lock-cutover —
+ * `state: stuck` with the reason, in place of the retired `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
@@ -920,10 +1112,10 @@ async function resolveStopReason(params) {
     const { output, slug, cwd, arbiter, env } = params;
     const sentinel = parseStopSentinel(output);
     if (sentinel !== undefined) {
-        return sentinel.reason;
+        return { kind: 'sentinel', reason: sentinel.reason };
     }
     if (await isWorkBranchDiffEmpty({ cwd, arbiter, env })) {
-        return emptyDiffStopReason(slug);
+        return { kind: 'empty-diff', reason: emptyDiffStopReason(slug) };
     }
     return undefined;
 }
@@ -936,8 +1128,59 @@ async function resolveStopReason(params) {
  * 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 { slug, cwd, arbiter, reason, kind, env, note } = params;
     const branch = params.branch ?? workBranchRef('task', slug);
+    // EMPTY-DIFF branch (spec resolved decision #2, task
+    // `empty-diff-bounce-surfaces-dispose-defaulted-question`): surface a sidecar
+    // on `<arbiter>/main` carrying an engine-authored DISPOSE-DEFAULTED envelope
+    // question, THEN release the lock. "Nothing to do" is a non-deterministic LLM
+    // judgement, so this seam MUST NOT blindly requeue (that would infinite-loop);
+    // the surfaced sidecar + `needsAnswers:true` on `main` parks the item as a
+    // human-visible question a `dispose` answer settles to `tasks/cancelled/`.
+    if (kind === 'empty-diff') {
+        const item = `task:${slug}`;
+        const itemPath = resolveItemPathByIdentity(cwd, item);
+        if (itemPath === undefined) {
+            const message = `The agent STOPPED building '${slug}' (empty diff) but its body could ` +
+                `not be located on the arbiter to surface a sidecar. Reason: ${reason}`;
+            note(message);
+            return {
+                exitCode: 1,
+                outcome: 'agent-stopped',
+                slug,
+                branch,
+                routedToNeedsAttention: false,
+                message,
+            };
+        }
+        const surfaced = await surfaceStuckToNeedsAttention({
+            cwd,
+            slug,
+            item,
+            itemPath,
+            reason,
+            envelope: emptyDiffDisposeEnvelope({ item, reason }),
+            arbiter,
+            env,
+            note,
+        });
+        const message = surfaced.surfaced
+            ? `The agent STOPPED building '${slug}' (empty diff); surfaced a ` +
+                `dispose-defaulted question on ${arbiter}/main and released the lock. ` +
+                `Reason: ${reason}`
+            : `The agent STOPPED building '${slug}' (empty diff) but the surface ` +
+                `did not land (${surfaced.reasonNotSurfaced ?? 'unknown'}). ` +
+                `Reason: ${reason}`;
+        note(message);
+        return {
+            exitCode: 1,
+            outcome: 'agent-stopped',
+            slug,
+            branch,
+            routedToNeedsAttention: surfaced.surfaced,
+            message,
+        };
+    }
     const routed = await ledgerWrite.applyNeedsAttentionTransition({
         cwd,
         slug,
@@ -954,8 +1197,11 @@ async function saveAgentStop(params) {
         : `The agent STOPPED building '${slug}' but it could not be marked stuck ` +
             `(${routed.reasonNotMoved ?? 'unknown'}). Reason: ${reason}`;
     note(message);
+    // PR-2b D3: agent-stopped (sentinel) on a clean surface is GREEN (exitCode 0);
+    // a FAILED surface stays non-zero. The empty-diff branch above is UNCHANGED
+    // (owned by `empty-diff-bounce-surfaces-dispose-defaulted-question`).
     return {
-        exitCode: 1,
+        exitCode: routed.moved ? 0 : 1,
         outcome: 'agent-stopped',
         slug,
         branch,
@@ -986,6 +1232,15 @@ async function runDoAgent(options, cwd, prompt, slug) {
         return options.dorfl({ cwd, prompt, slug, env: options.env });
     }
     const harness = options.harness ?? new NullHarness();
+    // Convert the dorfl-internal deadline (minutes) into a wall-clock epoch-ms so
+    // the harness (`launchAsync`) can race the child against it (spec
+    // `graceful-pre-timeout-wip-checkpoint`). Absent ⇒ no deadline; a run that
+    // finishes before it is byte-for-byte unchanged (the harness clears the
+    // timer on normal exit). Forcing the async path when a deadline is set is
+    // {@link launchWithOptionalWatch}'s job.
+    const deadlineMs = options.agentDeadlineMinutes !== undefined
+        ? Date.now() + options.agentDeadlineMinutes * 60_000
+        : undefined;
     const launched = await launchWithOptionalWatch({
         harness,
         dir: cwd,
@@ -997,6 +1252,7 @@ async function runDoAgent(options, cwd, prompt, slug) {
         sessionId: slug,
         sessionsDir: options.sessionsDir,
         watch: options.watch,
+        deadlineMs,
         watchSink: options.watchSink,
         color: options.color,
         env: options.env,
@@ -1004,7 +1260,115 @@ async function runDoAgent(options, cwd, prompt, slug) {
     // 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 };
+    return {
+        ok: launched.ok,
+        detail: launched.detail,
+        output: launched.output,
+        timedOut: launched.timedOut,
+    };
+}
+/**
+ * Route a DEADLINE STOP (spec `graceful-pre-timeout-wip-checkpoint`) through
+ * the checkpoint machinery: ALWAYS save the WIP (commit + push), then
+ * decide — progress AND under ceiling ⇒ AUTO-CONTINUE (release lock, keep
+ * branch, NO sidecar, exit 0); else ⇒ SURFACE a `needsAnswers:true` question.
+ * Shared by {@link performDo} and {@link runRemotePipeline} so the in-place
+ * and remote forms route a deadline stop identically.
+ */
+async function routeDeadlineCheckpoint(params) {
+    const { slug, branch, cwd, arbiter, maxAutoCheckpoints, env, note } = params;
+    // 1. ALWAYS save the WIP first: commit any residue + push the work branch.
+    const savedReason = `deadline checkpoint save for '${slug}'`;
+    const saved = await saveDeadlineCheckpoint({
+        slug,
+        branch,
+        cwd,
+        arbiter,
+        reason: savedReason,
+        env,
+        note,
+    });
+    void saved;
+    // 2. Progress this session? Reuse the SAME primitive the STOP backstop uses.
+    const emptyDiff = await isWorkBranchDiffEmpty({ cwd, arbiter, env });
+    const madeProgressThisSession = !emptyDiff;
+    // 3. Count consecutive deadline checkpoints on the branch (ceiling gate). The
+    //    marker commit we just saved is included — so the count is the number
+    //    of checkpoints INCLUDING this one.
+    const checkpointCount = await countDeadlineCheckpointsOnBranch({
+        cwd,
+        arbiter,
+        branch,
+        env,
+    });
+    if (madeProgressThisSession && checkpointCount <= maxAutoCheckpoints) {
+        // AUTO-CONTINUE: release the lock via the SAME default keep+continue path
+        // `requeue` uses (no --reset, no --reconcile, no sidecar). The branch is
+        // KEPT on the arbiter so the next claim continues from its tip.
+        const reason = deadlineAutoContinueReason({
+            slug,
+            count: checkpointCount,
+            max: maxAutoCheckpoints,
+        });
+        const returned = await ledgerWrite.applyReturnToBacklogTransition({
+            cwd,
+            slug,
+            arbiter,
+            env,
+            note,
+        });
+        if (returned.moved) {
+            const message = `Auto-continued '${slug}' at the dorfl-internal deadline (checkpoint ` +
+                `${checkpointCount}/${maxAutoCheckpoints}): WIP saved + branch pushed, ` +
+                `lock released so the next tick continues from ${branch}. ${reason}`;
+            note(message);
+            return {
+                exitCode: 0,
+                outcome: 'deadline-auto-continued',
+                slug,
+                branch,
+                message,
+            };
+        }
+        // The auto-continue lock release did not land — fall through to SURFACE.
+        note(`Auto-continue lock release for '${slug}' did not land ` +
+            `(${returned.reasonNotMoved ?? 'unknown'}); surfacing instead.`);
+    }
+    // SURFACE: mark the lock stuck via the whole applyNeedsAttentionTransition
+    // (save + push + stuck). The WIP was already saved above; a second save is
+    // idempotent (empty commit is skipped inside routeToNeedsAttention).
+    const surfaceReason = madeProgressThisSession
+        ? deadlineSurfaceReason({
+            slug,
+            kind: 'ceiling',
+            count: checkpointCount,
+            max: maxAutoCheckpoints,
+        })
+        : deadlineSurfaceReason({ slug, kind: 'no-progress' });
+    const routed = await ledgerWrite.applyNeedsAttentionTransition({
+        cwd,
+        slug,
+        reason: surfaceReason,
+        arbiter,
+        env,
+        note,
+    });
+    const report = routed.moved ? routeReport(routed, branch) : undefined;
+    const message = routed.moved
+        ? `Surfaced '${slug}' at the deadline checkpoint (${madeProgressThisSession
+            ? `ceiling ${checkpointCount}/${maxAutoCheckpoints}`
+            : 'no progress this session'}); ${report.fragment}. ${surfaceReason}`
+        : `Could not surface '${slug}' at the deadline checkpoint ` +
+            `(${routed.reasonNotMoved ?? 'unknown'}). ${surfaceReason}`;
+    note(message);
+    return {
+        exitCode: 1,
+        outcome: 'deadline-surfaced',
+        slug,
+        branch,
+        routedToNeedsAttention: routed.moved,
+        message,
+    };
 }
 /**
  * True when the working tree has uncommitted (unstaged OR staged) changes — the
@@ -1200,7 +1564,7 @@ export async function performDoRemote(options) {
     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
+        //     failure is a loud usage error; a `spec:` arg reaches the not-yet-wired
         //     stub — identical behaviour to in-place `do`.
         let resolved;
         try {
@@ -1230,9 +1594,9 @@ export async function performDoRemote(options) {
                 arbiter: 'origin',
                 doer: 'agent',
                 autoTask: options.autoTask,
-                // EXPLICIT dispatch (same as the in-place path above): the `prd:<slug>` was
+                // EXPLICIT dispatch (same as the in-place path above): the `spec:<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 +
+                // tasking gate drops the policy term — only the spec's own readiness +
                 // `taskedAfter` bind, mirroring the build path vs `autoBuild`.
                 explicit: true,
                 dorfl: options.dorfl,
@@ -1244,22 +1608,26 @@ export async function performDoRemote(options) {
                 // `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
+                // `taskingIntegration ?? integration`, so the `--remote spec:` output ALSO
                 // routes through the shared core with the tasking-resolved mode.
                 integration: options.taskingIntegration ?? options.integration,
+                // The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) —
+                // threaded on the no-checkout `do --remote spec:` tasking path too,
+                // mirroring the in-place site above.
+                mergeRetries: options.mergeRetries,
                 // 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.
+                // precedence`). Same threading as the in-place `do spec:` 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.
+                // The tasker review→edit→converge loop on the `do --remote spec:` 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.
+                // The task-SET ACCEPTANCE GATE on the `do --remote spec:` path too.
                 review: options.review,
                 reviewGate: options.taskReviewGate,
                 acceptanceReviewModel: options.reviewModel,
@@ -1402,8 +1770,10 @@ async function runRemotePipeline(options, tree, slug, note, env) {
     //     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';
+            'conflicted (aborted, never auto-resolved) — run `requeue --reconcile` ' +
+            'to non-destructively re-sync the mirror and retry the rebase (keeps ' +
+            'the work). Last resort: `requeue --reset` DESTRUCTIVELY discards the ' +
+            'branch and starts fresh.';
         await ledgerWrite.applyNeedsAttentionTransition({
             cwd,
             slug,
@@ -1433,8 +1803,10 @@ async function runRemotePipeline(options, tree, slug, note, env) {
     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';
+            'branch is left intact on the arbiter (recoverable); `requeue --reconcile` ' +
+            'to non-destructively re-sync the mirror and retry once the churn ' +
+            'settles (keeps the work). Last resort: `requeue --reset` DESTRUCTIVELY ' +
+            'discards the branch and starts fresh.';
         await ledgerWrite.applyNeedsAttentionTransition({
             cwd,
             slug,
@@ -1531,7 +1903,7 @@ async function runRemotePipeline(options, tree, slug, note, env) {
             content: readFileSync(task.path, 'utf8'),
             env,
         });
-        // Per-item override layer (mirrors in-place `do`): the task/prd frontmatter
+        // Per-item override layer (mirrors in-place `do`): the task/spec frontmatter
         // may override the resolved repo `promptGuidance.testFirst` for THIS item.
         const itemGuidance = resolvePromptGuidanceForItem({
             cwd,
@@ -1574,6 +1946,19 @@ async function runRemotePipeline(options, tree, slug, note, env) {
             note,
         });
     }
+    // Deadline checkpoint on the no-checkout `do --remote` path — same routing
+    // as the in-place path (see performDo).
+    if (agent.timedOut) {
+        return await routeDeadlineCheckpoint({
+            slug,
+            branch: branch ?? workBranchRef('task', slug),
+            cwd,
+            arbiter: arbiterRemote,
+            maxAutoCheckpoints: options.maxAutoCheckpoints ?? 5,
+            env,
+            note,
+        });
+    }
     if (!agent.ok) {
         const detail = agent.detail ?? `the agent failed to build '${slug}'.`;
         return await saveRemoteAgentFailure({
@@ -1604,7 +1989,8 @@ async function runRemotePipeline(options, tree, slug, note, env) {
             branch,
             cwd,
             arbiter: arbiterRemote,
-            reason: stopReason,
+            reason: stopReason.reason,
+            kind: stopReason.kind,
             env,
             note,
         });
@@ -1775,8 +2161,9 @@ async function saveRemoteAgentFailure(params) {
         : `Agent run failed building '${slug}' [${cause}] (${detail}); could not ` +
             `mark '${slug}' stuck (${routed.reasonNotMoved ?? 'unknown'}).`;
     note(message);
+    // PR-2b D3: cleanly-surfaced remote agent failure is GREEN.
     return {
-        exitCode: 1,
+        exitCode: routed.moved ? 0 : 1,
         outcome: failureCauseToDoOutcome(cause),
         slug,
         branch,
@@ -1831,7 +2218,7 @@ async function primeWorktreeTrackingRef(cwd, arbiter, head, env) {
  * 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
+ * mirror's arbiter URL + the agents' execution area). A `spec:` 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).
@@ -1871,6 +2258,8 @@ export function jobWorktreeDoDriver(closure) {
             watch: options.watch,
             watchSink: options.watchSink,
             color: options.color,
+            agentDeadlineMinutes: options.agentDeadlineMinutes,
+            maxAutoCheckpoints: options.maxAutoCheckpoints,
             read: options.read,
             env: options.env,
             note: options.note,