dorfl 0.1.2 → 0.2.1

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,8 +276,11 @@ 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 spec:<slug>` — the spec was tasked into work/backlog/ (runner-owned)
@@ -168,6 +321,14 @@ 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 {
@@ -251,10 +412,10 @@ export interface DoOptions {
 	 * 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
@@ -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
@@ -507,12 +703,12 @@ export interface DoRemoteOptions extends DoAgentLaunchOptions {
 	 * 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
 	 * 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;
@@ -741,6 +937,11 @@ 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
@@ -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,
@@ -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,
 		});
@@ -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,
+	};
 }
 
 /**
@@ -1922,6 +2365,10 @@ export async function performDoRemote(
 				// `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 spec:` path.
@@ -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,
@@ -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,
@@ -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,