dorfl 0.1.2 → 0.2.0

package/src/close-job-template.ts

@@ -110,7 +110,7 @@ jobs:
   close-merged-issues:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup

package/src/complete.ts

@@ -13,6 +13,8 @@ import {
 import {ledgerWrite} from './ledger-write.js';
 import {releaseItemLock} from './item-lock.js';
 import {workBranchRef, parseWorkBranchRef} from './slug-namespace.js';
+import {isProvablyMergedForReap} from './gc.js';
+import type {SidecarType} from './sidecar.js';
 import type {ReviewProvider} from './integrator.js';
 import type {IntegrationMode} from './config.js';
 import {runAsync, localMainAheadCount, type RunResult} from './git.js';
@@ -315,9 +317,12 @@ export interface CompleteResult {
 	outcome: CompleteOutcome;
 	/**
 	 * True iff a FAILURE outcome (gate-failed / rebase-conflict) was routed to
-	 * `work/needs-attention/` via the shared mechanism (ADR §12), rather than left
-	 * dangling. Undefined/false on the success, `--skip-verify`, refused, and
-	 * usage-error paths (none of which move the item to needs-attention).
+	 * the shared needs-attention mechanism (ADR §12) — post lock-cutover, the
+	 * per-item lock is amended to `state: stuck` with the reason recorded on the
+	 * lock entry (there is no `work/needs-attention/` folder write anymore),
+	 * rather than the item being left dangling. Undefined/false on the success,
+	 * `--skip-verify`, refused, and usage-error paths (none of which mark the
+	 * item stuck).
 	 */
 	routedToNeedsAttention?: boolean;
 	/** The work branch that was completed, when one was resolved. */
@@ -489,13 +494,11 @@ function strandRefusalSlug(err: unknown): string | undefined {
 }
 
 /**
- * Surface an autonomous-path strand refusal to `needs-attention/` on the
- * arbiter via the TREE-LESS seam ({@link
- * ledgerWrite.applyTreelessNeedsAttentionTransition}). The mechanism is the
- * one `requeue`/`continue` already use in reverse: fetch `<arbiter>/main`,
- * resolve the slug's actual current folder ON THE ARBITER (arbiter-is-truth),
- * build the one-file `work/<src>/<slug>.md → work/needs-attention/<slug>.md`
- * move on a scratch index, and CAS-publish it. It NEVER touches the caller's
+ * Surface an autonomous-path strand refusal via the TREE-LESS seam ({@link
+ * ledgerWrite.applyTreelessNeedsAttentionTransition}). Post lock-cutover the
+ * seam is a pure LOCK AMEND — the item's per-item lock is moved to
+ * `state: stuck` with the reason on the lock entry; no folder move, no
+ * `work/needs-attention/` write. It NEVER touches the caller's
  * working tree / HEAD / index — important here because the refusal was raised
  * precisely because the working tree does NOT hold an `.md` to `git mv`. It is
  * idempotent (a re-surface of an already-surfaced slug is a no-op) and reports
@@ -523,11 +526,13 @@ async function surfaceAutonomousStrand(params: {
 	});
 	if (surfaced.moved) {
 		const message =
-			`'${slug}' refused (${reason}); surfaced to work/needs-attention/ on ` +
-			`${arbiter}/main so the next autonomous tick does NOT re-claim it.`;
+			`'${slug}' refused (${reason}); surfaced on ${arbiter}/main as a stuck ` +
+			'question (needsAnswers) so the next autonomous tick does NOT re-claim it.';
 		note(message);
+		// PR-2b D3: a clean surface is GREEN (exitCode 0). The autonomous strand
+		// surface is one of the cleanly-surfaced bounce sites this policy applies to.
 		return {
-			exitCode: 1,
+			exitCode: 0,
 			outcome: 'strand-surfaced',
 			routedToNeedsAttention: true,
 			message,
@@ -668,12 +673,14 @@ async function runComplete(
 	// removes it from THERE, so the move can never disagree with what the arbiter
 	// holds even when the local tree diverges (ledger-integrity defect 1). The
 	// `source` we pass is the arbiter-content fallback for the degenerate "arbiter
-	// holds nothing" case, not the authority. `in-progress/` is RETAINED below for
-	// the legacy/bounce surfaces that may still source from it until its folder
-	// removal (9c, OUT of this task's scope).
+	// holds nothing" case, not the authority. The legacy `in-progress/` FOLDER PROBE
+	// is GONE (task `finish-in-progress-folder-cutover-remove-legacy-recovery-readers`):
+	// the per-item-lock cutover moved claim OFF writing `work/in-progress/` (the body
+	// rests in `tasks/backlog/`, liveness is the held lock), so nothing writes that
+	// folder anymore and the `existsSync(inProgress)` arm could not fire. Liveness is
+	// the lock, not the folder.
 	const backlog = workItemPath(cwd, 'tasks-ready', slug);
 	const staged = workItemPath(cwd, 'tasks-backlog', slug);
-	const inProgress = workItemPath(cwd, 'in-progress', slug);
 	const done = workItemPath(cwd, 'done', slug);
 	const onBacklog = existsSync(backlog);
 	// `--allow-backlog` drive (spec
@@ -686,7 +693,6 @@ async function runComplete(
 	// strand `complete` must REFUSE (the honest "not finished, not done" position),
 	// NOT silently integrate — only the deliberate drive promotes from staging.
 	const onPreBacklog = options.allowBacklog === true && existsSync(staged);
-	const onInProgress = existsSync(inProgress);
 	// SELF-RENAMING FOLDER task backstop: the binary-known `work/done/<slug>.md`,
 	// OR — when none of the binary-known ledger folders hold the record — the slug
 	// at a RENAMED done-position the migration agent placed it in (e.g.
@@ -695,13 +701,10 @@ async function runComplete(
 	// resolution is byte-for-byte unchanged.
 	const onDone =
 		existsSync(done) ||
-		(!onBacklog &&
-			!onPreBacklog &&
-			!onInProgress &&
-			recordAtRenamedDonePosition(cwd, slug));
+		(!onBacklog && !onPreBacklog && recordAtRenamedDonePosition(cwd, slug));
 	// STRANDED-DONE AUTO-RECOVER (spec `ledger-integrity` story 6, the autonomous
-	// half of `finish-already-committed-branch`). When neither in-progress/ nor
-	// needs-attention/ holds the slug on the BRANCH tree BUT done/ does, the work
+	// half of `finish-already-committed-branch`). When the pool/staging does NOT
+	// hold the slug on the BRANCH tree BUT done/ does, the work
 	// branch was already built + done-moved + committed by a prior run that never
 	// landed on the arbiter (a terminal push failed, or the PR never merged). The
 	// autonomous `do`/`advance`/plain-`complete` path used to refuse this with
@@ -713,8 +716,7 @@ async function runComplete(
 	// `<arbiter>/main` returns `already-integrated` (clean no-op, NEVER a
 	// re-push/double-integrate). Mutually exclusive with the build-path source +
 	// `recovering` flags — the core ignores them when `committedRecovery` is set.
-	const folderShapeStranded =
-		!onBacklog && !onPreBacklog && !onInProgress && onDone;
+	const folderShapeStranded = !onBacklog && !onPreBacklog && onDone;
 	// DIRTY-CONTINUE GATE (task `recover-autodetect-gated-on-nothing-to-commit`).
 	// The folder-shape stranded-done auto-detect is necessary but NOT sufficient on
 	// a CONTINUE: a requeued task whose prior attempt already done-moved the slug
@@ -749,24 +751,19 @@ async function runComplete(
 	// "nothing to complete" CompleteRefusal). We default `source` to `'tasks-ready'`
 	// so `sourcePath` resolves to the canonical pool path the refusal message
 	// names; the refusal fires because that file does not exist on disk.
-	const source: 'tasks-ready' | 'tasks-backlog' | 'in-progress' | 'done' =
-		dirtyContinue
-			? 'done'
-			: onBacklog
-				? 'tasks-ready'
-				: onInProgress
-					? 'in-progress'
-					: onPreBacklog
-						? 'tasks-backlog'
-						: 'tasks-ready';
+	const source: 'tasks-ready' | 'tasks-backlog' | 'done' = dirtyContinue
+		? 'done'
+		: onBacklog
+			? 'tasks-ready'
+			: onPreBacklog
+				? 'tasks-backlog'
+				: 'tasks-ready';
 	const sourcePath =
 		source === 'tasks-ready'
 			? backlog
 			: source === 'tasks-backlog'
 				? staged
-				: source === 'in-progress'
-					? inProgress
-					: done;
+				: done;
 	if (dirtyContinue) {
 		// Announce LOUDLY (parallel to the `committedRecovery` recovery note above):
 		// the autonomous integrate path took the CONTINUE-BUILD branch, not the
@@ -924,9 +921,19 @@ async function runComplete(
 
 	// The FAILURE outcomes map 1:1 onto `complete`'s — the core already note()'d
 	// the reason and did any routing; the tail never runs for them.
+	// PR-2b exit-code policy (spec
+	// `surface-stuck-as-questions-and-retire-stuck-lock-state`, decision #4 / D3):
+	// a cleanly-surfaced bounce is GREEN (`exitCode: 0`) iff its surface transition
+	// SUCCEEDED (`routedToNeedsAttention: true`); a FAILED surface stays non-zero
+	// (retry/resolve). Applies to `prepare-failed`/`gate-failed`/`review-blocked`/
+	// `review-unparseable`/`rebase-conflict`. The empty-diff backstop is owned by
+	// task `empty-diff-bounce-surfaces-dispose-defaulted-question` and is NOT
+	// reached here.
+	const surfaceExit = (routed: boolean | undefined): 0 | 1 =>
+		routed === true ? 0 : 1;
 	if (core.outcome === 'prepare-failed') {
 		return {
-			exitCode: 1,
+			exitCode: surfaceExit(core.routedToNeedsAttention),
 			outcome: 'prepare-failed',
 			routedToNeedsAttention: core.routedToNeedsAttention,
 			branch: core.branch,
@@ -935,7 +942,7 @@ async function runComplete(
 	}
 	if (core.outcome === 'gate-failed') {
 		return {
-			exitCode: 1,
+			exitCode: surfaceExit(core.routedToNeedsAttention),
 			outcome: 'gate-failed',
 			routedToNeedsAttention: core.routedToNeedsAttention,
 			branch: core.branch,
@@ -944,7 +951,7 @@ async function runComplete(
 	}
 	if (core.outcome === 'review-blocked') {
 		return {
-			exitCode: 1,
+			exitCode: surfaceExit(core.routedToNeedsAttention),
 			outcome: 'review-blocked',
 			routedToNeedsAttention: core.routedToNeedsAttention,
 			branch: core.branch,
@@ -958,7 +965,7 @@ async function runComplete(
 		// `do`/`run` tail re-labels its cause `transient-infra` (NOT a reviewer block) off
 		// the parse-failure phrase in `core.reason`.
 		return {
-			exitCode: 1,
+			exitCode: surfaceExit(core.routedToNeedsAttention),
 			outcome: 'review-unparseable',
 			routedToNeedsAttention: core.routedToNeedsAttention,
 			branch: core.branch,
@@ -967,7 +974,7 @@ async function runComplete(
 	}
 	if (core.outcome === 'rebase-conflict') {
 		return {
-			exitCode: 1,
+			exitCode: surfaceExit(core.routedToNeedsAttention),
 			outcome: 'rebase-conflict',
 			routedToNeedsAttention: core.routedToNeedsAttention,
 			branch: core.branch,
@@ -1120,6 +1127,43 @@ async function runComplete(
 	// ONE thing the human must act on, so it is emitted as a visually-distinct
 	// block (blank lines + heading + TTY-aware color) ON TOP of the plain summary
 	// note below — cosmetic only; the structured result is unchanged.
+	//
+	// BENIGN ALREADY-LANDED RACE TAIL (task `propose-push-survives-stale-lease-
+	// on-reaped-work-ref`, follow-up
+	// `complete-propose-honour-already-landed-and-rename-continue-branch-module`):
+	// when the integrator's propose push observed a REAPED `work/<slug>` ref AND
+	// the work was provably on `<arbiter>/main`, it returns `alreadyLanded: true`
+	// with a custom `instruction`. In that case NOTHING was pushed and there is
+	// NO ref for a PR to point at, so emitting the generic
+	// `formatProposeNextStep` push+PR block ("Pushed ... Open a PR/MR ...") would
+	// misreport a clean no-op as unfinished work. Surface the integrator's
+	// `instruction` VERBATIM instead — it is already the correct clean-no-op
+	// prose (the CI-dominant recovery path via `performIntegration` already does
+	// the same; this is the sibling `complete.ts` caller's honest report). The
+	// tail (switch-to-main / delete-local-branch / `--no-switch`) is UNCHANGED
+	// — only the emitted next-step + summary text differ.
+	if (result.alreadyLanded === true) {
+		const instruction =
+			result.instruction ??
+			`${branch}: already on ${arbiter}/main (clean no-op).`;
+		const tail = options.noSwitch
+			? `; left on ${branch} (--no-switch).`
+			: deletedLocalBranch
+				? `; switched to main and deleted ${branch}.`
+				: '; switched to main.';
+		const message = `Completed '${slug}': ${instruction}${tail}`;
+		note(message);
+		return {
+			exitCode: 0,
+			outcome: 'completed',
+			branch,
+			commitMessage,
+			mergedToMain: false,
+			switchedTo,
+			deletedLocalBranch,
+			message,
+		};
+	}
 	const color = options.color ?? shouldUseColor(process.stdout);
 	const noteBlock = options.noteBlock ?? note;
 	noteBlock(
@@ -1316,15 +1360,29 @@ export async function isLocalBranchProvablyOnArbiter(
 	// Refresh remote-tracking refs against the live arbiter (best-effort).
 	await gitSoft(['fetch', '--quiet', arbiter], cwd, env);
 
-	// Merged: tip is an ancestor of <arbiter>/main.
+	// Merged: the tip is provably on <arbiter>/main — fast-path ancestor OR
+	// squash-aware fallback (durable done/dropped record on main + branch
+	// carries nothing main lacks). The SAME predicate `gc.ts`'s worktree reaper
+	// and `reap-branches.ts`'s remote sweep use — do not fork it.
+	const parsed = parseWorkBranchRef(branch);
+	const arbiterMainRef = `${arbiter}/main`;
 	const merged =
-		(
-			await gitSoft(
-				['merge-base', '--is-ancestor', localTip, `${arbiter}/main`],
-				cwd,
-				env,
-			)
-		).status === 0;
+		parsed === undefined
+			? (
+					await gitSoft(
+						['merge-base', '--is-ancestor', localTip, arbiterMainRef],
+						cwd,
+						env,
+					)
+				).status === 0
+			: isProvablyMergedForReap({
+					cwd,
+					tip: localTip,
+					arbiterMain: arbiterMainRef,
+					namespace: parsed.namespace as SidecarType,
+					slug: parsed.slug,
+					env,
+				});
 	if (merged) {
 		return true;
 	}

package/src/config.ts

@@ -22,7 +22,7 @@ export type IntegrationMode = 'propose' | 'merge';
  * `runner-deterministic-slice-placement-policy-and-precedence`, governing ADR
  * `placement-is-runner-deterministic-humanonly-is-agent-judgement`). Which
  * folder the runner lands the tasker's emitted task files in BY DEFAULT —
- * `'pre-backlog'` (staging — durable + readable but NOT in the agent-eligible
+ * `'backlog'` (staging — durable + readable but NOT in the agent-eligible
  * POOL; a runner/human promotion is needed to make an item claimable; the on-disk
  * folder for this value is `work/tasks/backlog/`) or `'ready'` (the agent-eligible
  * POOL — the trusted fast-path landing, on-disk `work/tasks/ready/`). The pool
@@ -30,12 +30,13 @@ export type IntegrationMode = 'propose' | 'merge';
  * `rename-task-pool-folder-todo-to-ready`, a CLEAN BREAK matching the on-disk
  * folder `tasks/ready/` and the spec-side `'ready'` pool spelling). The runner-deterministic
  * placement RESOLVER (`src/placement.ts`) layers on top: `explicit operator flag
- * > untrusted-origin ⇒ pre-backlog > tasksLandIn default > built-in
- * (pre-backlog)`. An untrusted-origin tasker output is FORCED to staging even in
+ * > untrusted-origin ⇒ backlog > tasksLandIn default > built-in
+ * (backlog)`. The staging value was renamed `'pre-backlog'` → `'backlog'`
+ * (matching the on-disk folder `tasks/backlog/`). An untrusted-origin tasker output is FORCED to staging even in
  * a `'ready'` repo (the positional analogue of the existing
  * `untrusted-origin-forces-build-propose` rule).
  */
-export type TasksLandIn = 'pre-backlog' | 'ready';
+export type TasksLandIn = 'backlog' | 'ready';
 
 /**
  * **Per-repo SPEC-PLACEMENT default** (spec
@@ -352,7 +353,7 @@ export interface Config {
 	 * {@link integration}: flag (`--merge`/`--propose`) > env
 	 * (`DORFL_TASKING_INTEGRATION`) > per-repo > global > (fall back to)
 	 * `integration` > default `propose`. DISTINCT from intake's per-EMITTED-TYPE
-	 * `{task, prd}` resolver (front door, author-trust-resolved): this is a
+	 * `{task, spec}` resolver (front door, author-trust-resolved): this is a
 	 * per-LIFECYCLE-TRANSITION knob, inside the trust boundary, operator/config-only.
 	 */
 	taskingIntegration?: IntegrationMode;
@@ -362,7 +363,7 @@ export interface Config {
 	 * `runner-deterministic-slice-placement-policy-and-precedence`). Resolved
 	 * per-repo EXACTLY like {@link taskingIntegration} (flag `--tasks-land-in`
 	 * > env `DORFL_TASKS_LAND_IN` > per-repo > global > built-in
-	 * `'pre-backlog'`). The tasking path reads it and passes it as the
+	 * `'backlog'`). The tasking path reads it and passes it as the
 	 * CONFIGURED-DEFAULT rung into the shared placement resolver
 	 * (`src/placement.ts`); the resolver overlays an EXPLICIT operator flag
 	 * (top) and the UNTRUSTED-ORIGIN force (staging) on top, in that order. The
@@ -385,7 +386,7 @@ export interface Config {
 	 * influence it. KEY-LEVEL SYMMETRY with `tasksLandIn` — one resolver, two
 	 * lifecycles, one precedence change touches ONE place.
 	 *
-	 * The sole spec-placement key after the `prd` → `spec` HARD CUTOVER (spec
+	 * The sole spec-placement key after the ''prd'' → `spec` HARD CUTOVER (spec
 	 * `prd-to-spec-vocabulary-cutover-and-migration-command`): the legacy
 	 * `prdsLandIn` config key + `--prds-land-in` flag are GONE (clean break).
 	 */
@@ -508,8 +509,8 @@ export interface Config {
 	 * re-rolled — re-reviewing an unchanged tip after a block would just be a
 	 * stochastic dice re-roll that could launder a real reject into a pass). So a
 	 * value > 1 makes a FALSE APPROVE harder to slip through (each extra round is a
-	 * veto), it does NOT give blocked work a second chance. A non-approve forces
-	 * `needs-attention/` (never silently merges or loops), per the maintainer
+	 * veto), it does NOT give blocked work a second chance. A non-approve forces the
+	 * item stuck (the lock `state: stuck`; never silently merges or loops), per the maintainer
 	 * decision. Default a small N (2): two independent approvals required. (A future
 	 * builder-REVISE step that MUTATES the tree between rounds is the only thing that
 	 * should make a block retryable, because it changes the artifact under review; it
@@ -626,6 +627,40 @@ export interface Config {
 	 * `observationTriage` default or shape — a SEPARATE, independent axis.
 	 */
 	strictMergeApproval: boolean;
+	/**
+	 * **The dorfl-INTERNAL agent deadline** (minutes). The agent session self-stops
+	 * at this budget; dorfl then SAVES the WIP (commit + push `work/<slug>`) and
+	 * routes it per the progress+ceiling decision (auto-continue, or surface). This
+	 * is the PRIMARY stop (see spec `graceful-pre-timeout-wip-checkpoint`); the
+	 * GitHub `timeout-minutes` cap is a BACKSTOP set above it as
+	 * `agentDeadlineMinutes + checkpointHeadroomMinutes`. Default 60; MAX 240 (4h).
+	 * FAIL-LOUD: values outside `[1, 240]` throw at config load (never silently
+	 * clamped). Resolved per-repo through the SAME chain as `integration` (flag >
+	 * env `DORFL_AGENT_DEADLINE_MINUTES` > per-repo > global > default).
+	 */
+	agentDeadlineMinutes: number;
+	/**
+	 * **The GitHub-backstop head-room above the internal deadline** (minutes). The
+	 * enumerate job's dynamic `githubTimeout` output is
+	 * `agentDeadlineMinutes + checkpointHeadroomMinutes`; the MIN 10 guarantees the
+	 * GitHub cap is always at least 10 minutes above the internal deadline so the
+	 * graceful save always has room to commit + push before the hard kill. Default
+	 * 30; MIN 10; MAX 60 (1h). FAIL-LOUD: out-of-range throws at load. Resolved
+	 * per-repo through the SAME chain as `agentDeadlineMinutes`.
+	 */
+	checkpointHeadroomMinutes: number;
+	/**
+	 * **The auto-continue ceiling** for the deadline-checkpoint anti-loop guard
+	 * (spec `graceful-pre-timeout-wip-checkpoint`). Counts CONSECUTIVE deadline
+	 * auto-continues; on hitting this cap the next deadline checkpoint SURFACES a
+	 * `needsAnswers:true` question ("this task has hit the deadline N times — it
+	 * may be too big for one CI leg; split it or run it locally?") instead of
+	 * auto-continuing. The counter naturally resets when the item completes (the
+	 * work branch is discarded on integration). Default 5. Must be a positive
+	 * integer (fail-loud). Resolved per-repo through the SAME chain as its
+	 * siblings.
+	 */
+	maxAutoCheckpoints: number;
 	/**
 	 * The optional runner **identity** (a bot): run the runner's git + provider
 	 * operations as a configured entity via process-scoped env overrides, without
@@ -741,7 +776,7 @@ export const DEFAULT_CONFIG: Config = {
 	// always first. Reproduces today's tasks-first two-pool default. Subsumes the
 	// removed `prdsFirst` boolean (`[task, build, ...]` reproduces `prdsFirst: true`).
 	selectionOrder: DEFAULT_SELECTION_ORDER,
-	maxParallel: 4,
+	maxParallel: 2,
 	perRepoMax: 2,
 	defaultArbiter: 'origin',
 	workspacesDir: join(homedir(), brand.workdirName),
@@ -752,14 +787,14 @@ export const DEFAULT_CONFIG: Config = {
 	// branch but deliberately skip the PR (the explicit suppress-PR intent that
 	// re-homes the old `provider: none` use). NOT a provider choice.
 	noPR: false,
-	// The tasker's emitted tasks land STAGED (`pre-backlog/`) by default — the
+	// The tasker's emitted tasks land STAGED (`tasks/backlog/`) by default — the
 	// conservative landing that preserves the tracer task's behaviour: an item is
 	// durable + readable but NOT in the agent-eligible pool until a human/runner
 	// promotes it. A repo opts into the trusted fast-path with `tasksLandIn:
 	// 'ready'` (or `--tasks-land-in ready` / `DORFL_TASKS_LAND_IN=ready`).
 	// The runner-deterministic resolver overlays explicit-flag + untrusted-origin
 	// force on top of this default (`src/placement.ts`).
-	tasksLandIn: 'pre-backlog',
+	tasksLandIn: 'backlog',
 	// `intake`-authored specs land STAGED (`pre-proposed/`) by default — the
 	// conservative landing that mirrors `tasksLandIn`'s built-in floor: a spec is
 	// durable + readable but NOT in the auto-tasking POOL until a human/runner
@@ -806,8 +841,65 @@ export const DEFAULT_CONFIG: Config = {
 	// `DORFL_STRICT_MERGE_APPROVAL=true`). The re-surface vs. land branch is
 	// `apply-rung-merge-disposition`'s consumer, NOT here.
 	strictMergeApproval: false,
+	// The dorfl-INTERNAL agent deadline defaults to 60 minutes (spec
+	// `graceful-pre-timeout-wip-checkpoint`). A legitimately-long task that runs
+	// past this checkpoints its WIP + auto-continues on the next tick (rather than
+	// losing everything to a 6h GitHub SIGKILL). MAX 240 (4h); fail-loud outside.
+	agentDeadlineMinutes: 60,
+	// The GitHub-backstop head-room above the internal deadline defaults to 30
+	// minutes: the enumerate job's dynamic `githubTimeout` output is
+	// deadline + headroom, so the default GitHub cap is 60 + 30 = 90 (1h30). MIN 10
+	// (guarantees the graceful save has room); MAX 60; fail-loud outside.
+	checkpointHeadroomMinutes: 30,
+	// The auto-continue ceiling defaults to 5 CONSECUTIVE deadline checkpoints;
+	// past that the next checkpoint SURFACES to a human (spec
+	// `graceful-pre-timeout-wip-checkpoint` anti-loop guard).
+	maxAutoCheckpoints: 5,
 };
 
+/**
+ * Fail-loud range validation for the deadline / backstop / ceiling triple
+ * (spec `graceful-pre-timeout-wip-checkpoint`). Called at the two resolution
+ * FINAL points (`loadConfig` for the global chain; `resolveRepoConfigFromLoaded`
+ * for the per-repo chain), so an out-of-range value from ANY layer (flag / env /
+ * per-repo / global) surfaces as a clean throw naming the field + the valid
+ * range. Never clamps — the task's decision is fail-loud, since a silently
+ * clamped 400-minute deadline would look correct in `dorfl config --json` and
+ * quietly break the invariant that GitHub cap > internal deadline.
+ */
+export function validateDeadlineConfig(config: Config): void {
+	const adm = config.agentDeadlineMinutes;
+	if (!Number.isInteger(adm) || adm < 1 || adm > 240) {
+		throw new Error(
+			`agentDeadlineMinutes must be a positive integer in [1, 240] ` +
+				`(got ${adm}). The dorfl-internal agent deadline caps a single ` +
+				`agent session; 240 minutes (4h) is the hard ceiling so the ` +
+				`GitHub backstop (deadline + headroom) still fits under GitHub's ` +
+				`6h job limit.`,
+		);
+	}
+	const chm = config.checkpointHeadroomMinutes;
+	if (!Number.isInteger(chm) || chm < 10 || chm > 60) {
+		throw new Error(
+			`checkpointHeadroomMinutes must be an integer in [10, 60] ` +
+				`(got ${chm}). This is the head-room the GitHub 'timeout-minutes' ` +
+				`backstop sits above the internal deadline (rendered dynamically ` +
+				`as agentDeadlineMinutes + checkpointHeadroomMinutes by the ` +
+				`advance-lifecycle 'enumerate' job); MIN 10 guarantees the ` +
+				`graceful save always has room to commit + push before the hard kill.`,
+		);
+	}
+	const cap = config.maxAutoCheckpoints;
+	if (!Number.isInteger(cap) || cap < 1) {
+		throw new Error(
+			`maxAutoCheckpoints must be a positive integer (got ${cap}). ` +
+				`It caps CONSECUTIVE deadline auto-continues; past this the ` +
+				`next checkpoint surfaces a needs-answers question to a human ` +
+				`(the anti-loop guard for the graceful pre-timeout checkpoint).`,
+		);
+	}
+}
+
 /** The conventional config location (`~/.config/dorfl/config.json`). */
 export function defaultConfigPath(): string {
 	return join(homedir(), '.config', brand.configDirName, 'config.json');
@@ -879,5 +971,7 @@ export function loadConfig(path: string = defaultConfigPath()): Config {
 			);
 		}
 	}
-	return mergeConfig(parsed);
+	const merged = mergeConfig(parsed);
+	validateDeadlineConfig(merged);
+	return merged;
 }

package/src/continue-branch.ts

@@ -1,6 +1,28 @@
 import {run, type RunResult} from './git.js';
 
 /**
+ * BROADENED SCOPE NOTE (follow-up task
+ * `complete-propose-honour-already-landed-and-rename-continue-branch-module`):
+ * this module's name still reads as "continue-branch" (its ORIGINAL role: the
+ * continue-detection + rebase-onto-fresh-main helpers used by the onboarding
+ * paths, documented below), BUT it now ALSO hosts the shared
+ * **stale-lease work-branch push** helpers used by MULTIPLE callers:
+ *
+ *   - {@link pushContinuedBranchWithStaleLeaseRetry} — the original
+ *     continue/onboard caller (the mirror hub → arbiter reconcile push).
+ *   - {@link pushProposeBranchWithStaleLeaseRetry} — the propose-mode
+ *     integrator's push (task `propose-push-survives-stale-lease-on-reaped-work-
+ *     ref`), which adds the BENIGN already-landed predicate (gone remote ref +
+ *     work reachable from `<arbiter>/main`) on top of the shared `stale info`
+ *     retry.
+ *
+ * A rename to something like `stale-lease-work-push.ts` was considered; the
+ * scope-note is preferred here because a rename would churn many imports
+ * across `src/` + `test/` for no behavioural gain, and the module already reads
+ * as a single conceptual bucket ("the work-branch push + continue-detection
+ * helpers"). Add new stale-lease work-ref push helpers here rather than
+ * spawning a sibling module.
+ *
  * The **continue-detection** shared by BOTH onboarding paths (the keystone of
  * the `requeue-continue-and-reset` task). `requeue` keeps the `work/<slug>`
  * branch so the NEXT claim CONTINUES from its tip instead of force-cutting a