dorfl 0.1.1 → 0.2.0

package/src/do.ts

@@ -59,7 +59,14 @@ import {
 	parseStopSentinel,
 	isWorkBranchDiffEmpty,
 	emptyDiffStopReason,
+	emptyDiffDisposeEnvelope,
+	type AgentStopClass,
 } from './agent-stop.js';
+import {
+	surfaceStuckToNeedsAttention,
+	routeToNeedsAttention,
+} from './needs-attention.js';
+import {resolveItemPathByIdentity} from './item-path.js';
 import {
 	classifyFailureCause,
 	failureCauseLabel,
@@ -117,6 +124,149 @@ import {
  * `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: {
+	slug: string;
+	count: number;
+	max: number;
+}): string {
+	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: {
+	slug: string;
+	kind: 'no-progress' | 'ceiling';
+	count?: number;
+	max?: number;
+}): string {
+	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: {
+	cwd: string;
+	arbiter: string;
+	branch: string;
+	env: NodeJS.ProcessEnv | undefined;
+}): Promise<number> {
+	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: {
+	slug: string;
+	branch: string;
+	cwd: string;
+	arbiter: string;
+	reason: string;
+	env: NodeJS.ProcessEnv | undefined;
+	note: (message: string) => void;
+}): Promise<import('./needs-attention.js').RouteToNeedsAttentionResult> {
+	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,
+	});
+}
+
 /** The terminal status of one in-place `do` run. */
 export type DoOutcome =
 	| 'completed' // claimed/onboarded → agent → gate green → integrated → exited
@@ -126,18 +276,21 @@ export type DoOutcome =
 	| 'surface-unmoved' // the tree-less surface to needs-attention did NOT land on the arbiter (lost the CAS race / no arbiter) — the item is STILL in-progress on the arbiter; retry/resolve
 	| 'agent-failed' // the agent ran but produced bad/empty output (the conservative generic), OR the cause is unknown — work SAVED + surfaced
 	| 'transient-infra' // a harness-surfaced model/connection outage (post-retry) or a git/provider outage — RETRY the same work (FAILURE-CAUSE axis)
+	| 'needs-reauth' // a credential expired / was revoked (OAuth refresh) — retry cannot help; a human must RE-AUTH (FAILURE-CAUSE axis)
 	| 'config-error' // a thrown CORE wiring/config error (e.g. review on, no reviewGate) — fix the WIRING, not the task (FAILURE-CAUSE axis)
 	| 'agent-stopped' // the agent DELIBERATELY stopped (task drifted/ambiguous) OR produced no change → surfaced; gate + Gate-2 SKIPPED
+	| 'deadline-auto-continued' // the dorfl-internal deadline fired; WIP saved + branch pushed + lock RELEASED (no sidecar) so the next tick continues (spec `graceful-pre-timeout-wip-checkpoint`)
+	| 'deadline-surfaced' // the dorfl-internal deadline fired but auto-continue was refused (no progress this session, or the maxAutoCheckpoints ceiling was hit); WIP saved + question SURFACED for a human
 	| 'refused' // refused (dirty tree, wrong folder, nothing to complete, …)
 	| 'usage-error' // usage / environment problem, or a slug-resolution error
-	| 'tasked' // `do prd:<slug>` — the prd was tasked into work/backlog/ (runner-owned)
-	| 'gate-refused' // `do prd:<slug>` — the tasking gate refused (honest skip)
-	| 'stale'; // `do prd:<slug>` — the held prd was edited under the lock (stale tasking)
+	| 'tasked' // `do spec:<slug>` — the spec was tasked into work/backlog/ (runner-owned)
+	| 'gate-refused' // `do spec:<slug>` — the tasking gate refused (honest skip)
+	| 'stale'; // `do spec:<slug>` — the held spec was edited under the lock (stale tasking)
 
 export interface DoResult {
 	exitCode: 0 | 1 | 2 | 3;
 	outcome: DoOutcome;
-	/** The resolved bare slug acted on (task or prd), when one was resolved. */
+	/** The resolved bare slug acted on (task or spec), when one was resolved. */
 	slug?: string;
 	/** The work branch the run operated on, when one was created/switched-to. */
 	branch?: string;
@@ -168,10 +321,18 @@ export type DoDorfl = (input: {
 	 * Absent ⇒ no body ⇒ the provider degrades to `--fill` (no regression).
 	 */
 	output?: string;
+	/**
+	 * **True iff the injected agent simulates a dorfl-internal DEADLINE stop**
+	 * (spec `graceful-pre-timeout-wip-checkpoint`). Test-only signal so an
+	 * injected `DoDorfl` can drive the checkpoint routing (save WIP +
+	 * auto-continue / surface). Production `runDoAgent` never sets this on the
+	 * injected path — the real deadline race lives in `PiHarness.launchAsync`.
+	 */
+	timedOut?: boolean;
 };
 
 export interface DoOptions {
-	/** The raw CLI slug argument: bare (= task), `task:<slug>`, or `prd:<slug>`. */
+	/** The raw CLI slug argument: bare (= task), `task:<slug>`, or `spec:<slug>`. */
 	arg: string;
 	/** The working clone/checkout to run in-place in. */
 	cwd: string;
@@ -187,10 +348,10 @@ export interface DoOptions {
 	/**
 	 * Per-repo `autoTask` policy (resolved by `autoslice-gate`: flag > env >
 	 * per-repo > global > default false). It gates the AUTO-PICK / pool path only
-	 * (`do-autopick.ts`'s taskable-prd pool): "may an agent auto-task an
-	 * UNDECLARED prd in this repo?". An EXPLICITLY-named `do prd:<slug>` tasks
+	 * (`do-autopick.ts`'s taskable-spec pool): "may an agent auto-task an
+	 * UNDECLARED spec in this repo?". An EXPLICITLY-named `do spec:<slug>` tasks
 	 * REGARDLESS of this policy (the dispatch passes `explicit: true` to
-	 * `performTask` — naming the prd IS the authorization, exactly as `do <task>`
+	 * `performTask` — naming the spec IS the authorization, exactly as `do <task>`
 	 * builds regardless of `autoBuild`). Ignored by the task-build path.
 	 */
 	autoTask?: boolean;
@@ -205,7 +366,7 @@ export interface DoOptions {
 	promptGuidance?: PromptGuidance;
 	/**
 	 * **The tasker review→edit→converge LOOP seam** (`slicer-review-edit-loop`):
-	 * consumed ONLY by the `do prd:<slug>` tasking path — after the agent produces
+	 * consumed ONLY by the `do spec:<slug>` tasking path — after the agent produces
 	 * candidate tasks, run the `review` SKILL as a review→edit→re-review loop that
 	 * improves them, routing the verdict through the needsAnswers / needs-attention
 	 * sink. Ignored by the task-build path. Omitted ⇒ no loop (candidate tasks land
@@ -234,27 +395,27 @@ export interface DoOptions {
 	explicitMerge?: boolean;
 	/**
 	 * **Per-TRANSITION override for the TASKING transition only** (config
-	 * `taskingIntegration`). Consumed ONLY by the `do prd:<slug>` tasking path: the
+	 * `taskingIntegration`). Consumed ONLY by the `do spec:<slug>` tasking path: the
 	 * value threaded into {@link performTask} is `taskingIntegration ?? integration`,
 	 * so an unset override is byte-for-byte today's behaviour (tasking uses
 	 * `integration`). The task-BUILD path ALWAYS threads `integration` (never this
 	 * key). An explicit `--merge`/`--propose` flag wins over BOTH (the flag-override
 	 * layer sets `integration` AND `taskingIntegration` to the typed mode — see
-	 * `do-config.ts`). DISTINCT from intake's per-EMITTED-TYPE `{task, prd}` resolver.
+	 * `do-config.ts`). DISTINCT from intake's per-EMITTED-TYPE `{task, spec}` resolver.
 	 */
 	taskingIntegration?: IntegrationMode;
 	/**
-	 * **The per-repo TASK-PLACEMENT default** (prd
+	 * **The per-repo TASK-PLACEMENT default** (spec
 	 * `staging-pool-position-gate-and-trust-model` US #5, task
 	 * `runner-deterministic-slice-placement-policy-and-precedence`). Consumed by
-	 * the `do prd:<slug>` tasking path: the value is fed as the
+	 * the `do spec:<slug>` tasking path: the value is fed as the
 	 * CONFIGURED-DEFAULT rung into the runner-deterministic placement resolver
 	 * (`src/placement.ts`). Resolved per-repo through the SAME chain as
 	 * `taskingIntegration` (flag > env > per-repo > global > built-in
-	 * `pre-backlog`). The task-BUILD path ignores it (placement is a TASKING
+	 * `backlog`). The task-BUILD path ignores it (placement is a TASKING
 	 * lifecycle concern).
 	 */
-	tasksLandIn?: 'pre-backlog' | 'ready';
+	tasksLandIn?: 'backlog' | 'ready';
 	/**
 	 * **The OPERATOR's EXPLICIT task-placement override** (the TOP precedence
 	 * rung in the placement resolver). Set ONLY when the operator typed
@@ -263,7 +424,7 @@ export interface DoOptions {
 	 * CLI always wins, no special force-key) — the positional analogue of
 	 * `explicitMerge` overriding the untrusted-origin build-propose rule.
 	 */
-	explicitTasksLandIn?: 'pre-backlog' | 'ready';
+	explicitTasksLandIn?: 'backlog' | 'ready';
 	/**
 	 * Override the pre-flight DIVERGENCE guard (`--ignore-diverged-main`, mirroring
 	 * `--ignore-not-ready`): proceed even when local `main` is ahead of
@@ -274,7 +435,7 @@ export interface DoOptions {
 	 */
 	ignoreDivergedMain?: boolean;
 	/**
-	 * **`--allow-backlog`** (prd
+	 * **`--allow-backlog`** (spec
 	 * `do-allow-backlog-drive-staged-tasks-without-promotion`): let this `do task:`
 	 * invocation FIND, CLAIM, and COMPLETE a task that lives in `tasks/backlog/`
 	 * (staging) IN PLACE, WITHOUT first promoting it to the pool — so no `advance`
@@ -284,7 +445,7 @@ export interface DoOptions {
 	 * build/gate are identical, and the done-move goes `tasks/backlog/ → tasks/done/`
 	 * directly (the explicit drive IS the promotion). EXPLICIT-INVOCATION-ONLY:
 	 * default off, never set by `run`/auto-pick/`advance` (the leak-fence). The
-	 * task-build path only; the `do prd:` path is unaffected.
+	 * task-build path only; the `do spec:` path is unaffected.
 	 */
 	allowBacklog?: boolean;
 	/** The declared per-repo ENV-PREP step (string | list), run ONCE before the
@@ -300,7 +461,7 @@ export interface DoOptions {
 	 */
 	freshWorktreeGate?: boolean;
 	/**
-	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, prd
+	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, spec
 	 * `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1
 	 * (a)). Threaded VERBATIM into `performComplete` → `performIntegration` so a
 	 * wide-matrix CI's raised cap actually reaches the cross-job land queue (the
@@ -335,7 +496,7 @@ export interface DoOptions {
 	 */
 	providerInstance?: ReviewProvider;
 	/**
-	 * **Gate 2 — the PR/code review gate** (GATES prd `work/prds/tasked/review.md`):
+	 * **Gate 2 — the PR/code review gate** (GATES spec `work/specs/tasked/review.md`):
 	 * threaded VERBATIM into `performComplete` (the gate rides inside the shared
 	 * `do`/`complete` pipeline, so CI inherits it for free). When `review` is on,
 	 * the `review` SKILL runs as a fresh-context agent AFTER the green `verify` and
@@ -349,7 +510,7 @@ export interface DoOptions {
 	reviewGate?: ReviewGate;
 	/**
 	 * **The task-SET ACCEPTANCE GATE seam** (task `slice-acceptance-gate`):
-	 * consumed ONLY by the `do prd:<slug>` tasking path. When `review` resolves on,
+	 * consumed ONLY by the `do spec:<slug>` tasking path. When `review` resolves on,
 	 * a fresh-context review of the produced task SET runs BEFORE the tasks
 	 * integrate (riding `performIntegration`'s review block); `block` routes the set
 	 * to needs-attention, `approve` lets it integrate. It rides the SAME BUILD
@@ -408,6 +569,22 @@ export interface DoOptions {
 	 * a sink to assert the surfaced lines without a real terminal.
 	 */
 	watchSink?: (line: string) => void;
+	/**
+	 * The dorfl-internal agent-session deadline in minutes (spec
+	 * `graceful-pre-timeout-wip-checkpoint`). Threaded through {@link runDoAgent}
+	 * to `launchWithOptionalWatch` — the harness races the child against it and
+	 * flags a graceful stop on fire, which `performDo` routes as a CHECKPOINT
+	 * (save WIP + auto-continue on progress under the ceiling, else surface).
+	 * Absent ⇒ no deadline (a run that finishes on its own is byte-for-byte
+	 * unchanged).
+	 */
+	agentDeadlineMinutes?: number;
+	/**
+	 * Anti-loop ceiling on CONSECUTIVE deadline auto-continues (spec
+	 * `graceful-pre-timeout-wip-checkpoint`). On hitting this the next
+	 * deadline checkpoint surfaces to a human instead of auto-continuing.
+	 */
+	maxAutoCheckpoints?: number;
 }
 
 /**
@@ -433,6 +610,25 @@ interface DoAgentLaunchOptions {
 	watch?: boolean;
 	watchSink?: (line: string) => void;
 	color?: boolean;
+	/**
+	 * **The dorfl-internal agent deadline in minutes** (spec
+	 * `graceful-pre-timeout-wip-checkpoint`). Threaded to {@link runDoAgent},
+	 * which converts it to a wall-clock `deadlineMs` and passes it to
+	 * {@link launchWithOptionalWatch} — the pi harness races the child against
+	 * that deadline. When the deadline fires, the agent is gracefully stopped
+	 * (SIGTERM + 10s grace + SIGKILL) and the caller routes the run as a
+	 * CHECKPOINT (save WIP + auto-continue / surface). Absent ⇒ no deadline
+	 * (byte-for-byte the pre-task behaviour).
+	 */
+	agentDeadlineMinutes?: number;
+	/**
+	 * **The anti-loop ceiling** for consecutive deadline auto-continues (spec
+	 * `graceful-pre-timeout-wip-checkpoint`). On hitting this the next deadline
+	 * checkpoint SURFACES to a human instead of auto-continuing. Absent ⇒
+	 * unlimited (⇒ defensive callers should always thread the resolved config
+	 * value; the default is 5).
+	 */
+	maxAutoCheckpoints?: number;
 	env?: NodeJS.ProcessEnv;
 	/**
 	 * The optional runner IDENTITY (a bot). Threaded from the host-only
@@ -453,7 +649,7 @@ interface DoAgentLaunchOptions {
  * there is no checkout, so the worktree is materialised under `workspacesDir`.
  */
 export interface DoRemoteOptions extends DoAgentLaunchOptions {
-	/** The raw CLI slug argument: bare (= task), `task:<slug>`, or `prd:<slug>`. */
+	/** The raw CLI slug argument: bare (= task), `task:<slug>`, or `spec:<slug>`. */
 	arg: string;
 	/**
 	 * The registered remote spec/URL to run against (`do --remote <r>`). Resolved
@@ -473,12 +669,12 @@ export interface DoRemoteOptions extends DoAgentLaunchOptions {
 	arbiter?: string;
 	/**
 	 * Per-repo `autoTask` policy — gates the AUTO-PICK / pool path only. An
-	 * EXPLICITLY-named `do --remote prd:<slug>` tasks regardless of it (the
+	 * EXPLICITLY-named `do --remote spec:<slug>` tasks regardless of it (the
 	 * dispatch passes `explicit: true`), mirroring `do <task>` vs `autoBuild`.
 	 * Ignored by the task-build path.
 	 */
 	autoTask?: boolean;
-	/** The tasker review→edit→converge loop seam — `do --remote prd:<slug>` path only (see {@link DoOptions.reviewLoop}). */
+	/** The tasker review→edit→converge loop seam — `do --remote spec:<slug>` path only (see {@link DoOptions.reviewLoop}). */
 	reviewLoop?: TaskReviewGate;
 	/** The tasker improver loop's `taskerLoopMax` cap. Loop only. */
 	taskerLoopMax?: number;
@@ -495,24 +691,24 @@ export interface DoRemoteOptions extends DoAgentLaunchOptions {
 	explicitMerge?: boolean;
 	/**
 	 * **Per-TRANSITION override for the TASKING transition only** (config
-	 * `taskingIntegration`) on the `do --remote prd:<slug>` path: threaded into
+	 * `taskingIntegration`) on the `do --remote spec:<slug>` path: threaded into
 	 * {@link performTask} as `taskingIntegration ?? integration`. Unset ⇒ tasking
 	 * uses `integration` (today's behaviour); the task-BUILD path always threads
 	 * `integration`. See {@link DoOptions.taskingIntegration}.
 	 */
 	taskingIntegration?: IntegrationMode;
 	/**
-	 * **The per-repo TASK-PLACEMENT default** (prd
+	 * **The per-repo TASK-PLACEMENT default** (spec
 	 * `staging-pool-position-gate-and-trust-model` US #5) on the `do --remote
-	 * prd:<slug>` path: threaded into {@link performTask} as the
+	 * spec:<slug>` path: threaded into {@link performTask} as the
 	 * configured-default rung. See {@link DoOptions.tasksLandIn}.
 	 */
-	tasksLandIn?: 'pre-backlog' | 'ready';
+	tasksLandIn?: 'backlog' | 'ready';
 	/**
 	 * **The OPERATOR's EXPLICIT task-placement override** on the `do --remote
-	 * prd:` path. See {@link DoOptions.explicitTasksLandIn}.
+	 * spec:` path. See {@link DoOptions.explicitTasksLandIn}.
 	 */
-	explicitTasksLandIn?: 'pre-backlog' | 'ready';
+	explicitTasksLandIn?: 'backlog' | 'ready';
 	/** The declared per-repo ENV-PREP step (string | list), run ONCE before the
 	 * first `verify` on a fresh worktree. Unset ⇒ a no-op (NO default install). */
 	prepare?: VerifyConfig;
@@ -526,7 +722,7 @@ export interface DoRemoteOptions extends DoAgentLaunchOptions {
 	 */
 	freshWorktreeGate?: boolean;
 	/**
-	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, prd
+	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, spec
 	 * `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1
 	 * (a)). Threaded VERBATIM into `performComplete` → `performIntegration` so the
 	 * resolved cap reaches the cross-job land queue (the CAS loop IS the queue
@@ -564,7 +760,7 @@ export interface DoRemoteOptions extends DoAgentLaunchOptions {
 	reviewModel?: string;
 	reviewMaxRounds?: number;
 	reviewGate?: ReviewGate;
-	/** The task-SET ACCEPTANCE GATE seam — `do --remote prd:<slug>` path only (see {@link DoOptions.taskReviewGate}). */
+	/** The task-SET ACCEPTANCE GATE seam — `do --remote spec:<slug>` path only (see {@link DoOptions.taskReviewGate}). */
 	taskReviewGate?: ReviewGate;
 	/**
 	 * **`--allow-backlog`** on the no-checkout `do --remote`/`--isolated` path (see
@@ -586,7 +782,7 @@ export interface DoRemoteOptions extends DoAgentLaunchOptions {
 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
@@ -620,7 +816,7 @@ function taskResultToDoResult(tasked: TaskResult): DoResult {
 			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;
@@ -684,8 +880,8 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 	}
 
 	// 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 {
@@ -717,10 +913,10 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 			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).
@@ -741,19 +937,24 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 			// `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,
@@ -942,15 +1143,18 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 	//     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,
@@ -984,8 +1188,10 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 		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,
@@ -1008,7 +1214,7 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 
 	// 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`)
@@ -1047,7 +1253,7 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 			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,
@@ -1074,7 +1280,12 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 		throw err;
 	}
 
-	let agent: {ok: boolean; detail?: string; output?: string};
+	let agent: {
+		ok: boolean;
+		detail?: string;
+		output?: string;
+		timedOut?: boolean;
+	};
 	try {
 		agent = await runDoAgent(options, tree.dir, prompt, slug);
 	} catch (err) {
@@ -1089,6 +1300,23 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 			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({
@@ -1123,7 +1351,8 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 			branch,
 			cwd: tree.dir,
 			arbiter: tree.arbiterRemote,
-			reason: stopReason,
+			reason: stopReason.reason,
+			kind: stopReason.kind,
 			env,
 			note,
 		});
@@ -1175,7 +1404,7 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 		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,
@@ -1275,8 +1504,10 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 		// (`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,
@@ -1373,7 +1604,9 @@ function routeReport(
 		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,
 		};
 	}
@@ -1389,7 +1622,10 @@ function routeReport(
 		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,
 	};
 }
@@ -1403,10 +1639,12 @@ function routeReport(
  *
  * 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`
@@ -1429,7 +1667,8 @@ function routeReport(
  * 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: {
 	slug: string;
@@ -1477,8 +1716,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,
@@ -1499,7 +1740,9 @@ function failureCauseToDoOutcome(cause: FailureCause): DoOutcome {
 
 /**
  * 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
@@ -1544,14 +1787,14 @@ async function resolveStopReason(params: {
 	cwd: string;
 	arbiter: string;
 	env: NodeJS.ProcessEnv | undefined;
-}): Promise<string | undefined> {
+}): Promise<AgentStopClass | undefined> {
 	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;
 }
@@ -1570,12 +1813,66 @@ async function saveAgentStop(params: {
 	cwd: string;
 	arbiter: string;
 	reason: string;
+	kind: 'sentinel' | 'empty-diff';
 	env: NodeJS.ProcessEnv | undefined;
 	note: (message: string) => void;
 }): Promise<DoResult> {
-	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,
@@ -1593,8 +1890,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,
@@ -1626,11 +1926,26 @@ async function runDoAgent(
 	cwd: string,
 	prompt: string,
 	slug: string,
-): Promise<{ok: boolean; detail?: string; output?: string}> {
+): Promise<{
+	ok: boolean;
+	detail?: string;
+	output?: string;
+	timedOut?: boolean;
+}> {
 	if (options.dorfl) {
 		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,
@@ -1642,6 +1957,7 @@ async function runDoAgent(
 		sessionId: slug,
 		sessionsDir: options.sessionsDir,
 		watch: options.watch,
+		deadlineMs,
 		watchSink: options.watchSink,
 		color: options.color,
 		env: options.env,
@@ -1649,7 +1965,134 @@ async function runDoAgent(
 	// 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: {
+	slug: string;
+	branch: string;
+	cwd: string;
+	arbiter: string;
+	maxAutoCheckpoints: number;
+	env: NodeJS.ProcessEnv | undefined;
+	note: (message: string) => void;
+}): Promise<DoResult> {
+	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,
+	};
 }
 
 /**
@@ -1875,7 +2318,7 @@ export async function performDoRemote(
 	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 {
@@ -1905,9 +2348,9 @@ export async function performDoRemote(
 				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,
@@ -1919,22 +2362,26 @@ export async function performDoRemote(
 				// `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,
@@ -2094,8 +2541,10 @@ async function runRemotePipeline(
 	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,
@@ -2127,8 +2576,10 @@ async function runRemotePipeline(
 		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,
@@ -2238,7 +2689,7 @@ async function runRemotePipeline(
 			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,
@@ -2265,7 +2716,12 @@ async function runRemotePipeline(
 		throw err;
 	}
 
-	let agent: {ok: boolean; detail?: string; output?: string};
+	let agent: {
+		ok: boolean;
+		detail?: string;
+		output?: string;
+		timedOut?: boolean;
+	};
 	try {
 		agent = await runDoAgent(options, cwd, prompt, slug);
 	} catch (err) {
@@ -2280,6 +2736,19 @@ async function runRemotePipeline(
 			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({
@@ -2311,7 +2780,8 @@ async function runRemotePipeline(
 			branch,
 			cwd,
 			arbiter: arbiterRemote,
-			reason: stopReason,
+			reason: stopReason.reason,
+			kind: stopReason.kind,
 			env,
 			note,
 		});
@@ -2500,8 +2970,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,
@@ -2568,7 +3039,7 @@ async function primeWorktreeTrackingRef(
  * 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).
@@ -2613,6 +3084,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,