dorfl 0.11.1 → 0.11.2

package/dist/worktree-writer-lock.js

@@ -0,0 +1,158 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { run } from './git.js';
+import { pidAlive } from './harness.js';
+import { processGroupAlive } from './reap-agent-tree.js';
+/**
+ * **The per-WORKING-TREE writer sentinel** (observation
+ * `checkpoint-releases-lock-while-predecessor-agent-still-writes`).
+ *
+ * The per-item lock (`item-lock.ts`) guards the ITEM: it answers "who owns this
+ * task?" and it is what claim / requeue / bounce move around. Nothing guarded the
+ * WORKING TREE. Those are different resources, and the deadline checkpoint is
+ * exactly where they come apart: the checkpoint releases the item lock so the
+ * next tick can continue the task, but the tree the previous agent was editing is
+ * reused by the successor. If the predecessor is still alive, two agents write to
+ * one tree.
+ *
+ * The primary fix is to reap the predecessor and VERIFY it is gone before the
+ * lock moves (`reap-agent-tree.ts`). This sentinel is the INDEPENDENT backstop:
+ * even if a live writer survives by some route the reap did not cover (a
+ * deliberately `setsid`-ed grandchild, a stale run from a crashed runner, an
+ * operator manually re-driving an item), a second agent physically cannot onboard
+ * into a tree that already has a LIVE holder. It is deliberately keyed on the
+ * TREE, not on the item: two different items sharing one worktree is just as
+ * unsafe as two attempts at the same item.
+ *
+ * ## Where the sentinel lives, and why not in the tree
+ *
+ * It is written to the worktree's PRIVATE git directory (`git rev-parse
+ * --absolute-git-dir`, which for a linked worktree is
+ * `.../.git/worktrees/<name>/`), NOT to a file inside the working tree. That
+ * placement is load-bearing:
+ *
+ *  - it is per-worktree (linked worktrees each get their own git dir), which is
+ *    precisely the granularity we are guarding;
+ *  - it can never appear in `git status`, so it cannot be mistaken for agent work,
+ *    cannot be swept into a commit by a `git add -A`, and needs no new exclusion
+ *    in the empty-diff backstop / `gc`'s cleanliness predicate (unlike
+ *    `.dorfl-job.json`, which each of those has to filter out by name);
+ *  - it is removed with the worktree, so it cannot outlive what it guards.
+ *
+ * ## Liveness, not presence
+ *
+ * A pid file that only records presence becomes a permanent blocker the first
+ * time a runner is `kill -9`ed. So the holder is checked for LIVENESS (its
+ * process group first, falling back to its pid) and a dead holder's sentinel is
+ * treated as stale and taken over. Only a genuinely live foreign writer refuses.
+ */
+/** The sentinel filename inside the worktree's private git directory. */
+export const WRITER_SENTINEL_FILENAME = 'dorfl-writer.json';
+/**
+ * The worktree's PRIVATE git directory, or `undefined` when `dir` is not a git
+ * worktree (in which case there is no sentinel location and the caller proceeds
+ * unguarded rather than failing — this is a backstop, not a gate).
+ */
+function worktreeGitDir(dir, env) {
+    const result = run('git', ['rev-parse', '--absolute-git-dir'], dir, { env });
+    if (result.status !== 0) {
+        return undefined;
+    }
+    const path = result.stdout.trim();
+    return path === '' ? undefined : path;
+}
+/** The sentinel path for `dir`, or `undefined` when `dir` is not a worktree. */
+export function writerSentinelPath(dir, env) {
+    const gitDir = worktreeGitDir(dir, env);
+    return gitDir === undefined
+        ? undefined
+        : join(gitDir, WRITER_SENTINEL_FILENAME);
+}
+/** Read + parse the sentinel, or `undefined` when absent/corrupt. */
+export function readWorktreeWriter(dir, env) {
+    const path = writerSentinelPath(dir, env);
+    if (path === undefined || !existsSync(path)) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed?.pid === 'number' ? parsed : undefined;
+    }
+    catch {
+        // A corrupt sentinel records nothing we can trust; treat it as absent so it
+        // self-heals on the next acquire rather than wedging the worktree forever.
+        return undefined;
+    }
+}
+/**
+ * Is the recorded holder still running? Prefers the agent's process GROUP (which
+ * survives the group leader's death and so catches exactly the orphaned-writer
+ * case this exists for), and falls back to the runner pid.
+ */
+export function writerAlive(holder) {
+    if (holder.pgid !== undefined && processGroupAlive(holder.pgid)) {
+        return true;
+    }
+    return pidAlive(holder.pid);
+}
+/**
+ * Claim `dir` as the SOLE agent-writable working tree for `slug`.
+ *
+ * Refuses when a DIFFERENT, still-LIVE writer holds it — the second-agent case
+ * the observation describes. A dead holder's sentinel is stale and is taken over
+ * silently (a `kill -9`ed runner must not poison the worktree forever), and our
+ * OWN pid re-acquiring is a no-op re-entry rather than a refusal.
+ *
+ * When `dir` is not a git worktree there is nowhere private to record the
+ * sentinel; that is reported as acquired with a no-op release, because this is a
+ * defence-in-depth backstop and must never become a new way for a legitimate run
+ * to fail.
+ */
+export function acquireWorktreeWriterLock(params) {
+    const { dir, slug, pgid, env } = params;
+    const path = writerSentinelPath(dir, env);
+    if (path === undefined) {
+        return { acquired: true, release: () => { } };
+    }
+    const existing = readWorktreeWriter(dir, env);
+    if (existing !== undefined &&
+        existing.pid !== process.pid &&
+        writerAlive(existing)) {
+        return {
+            acquired: false,
+            holder: existing,
+            reason: `worktree ${dir} already has a LIVE agent writer: pid ${existing.pid}` +
+                (existing.pgid !== undefined ? ` (group ${existing.pgid})` : '') +
+                ` building '${existing.slug}' since ${existing.startedAt}. Refusing to ` +
+                `onboard '${slug}' into the same working tree: two live agents in one ` +
+                'tree can clobber each other’s edits, and the second can commit the ' +
+                'first’s half-finished work under a message describing something else. ' +
+                'Wait for it to exit, or kill it, then retry.',
+        };
+    }
+    const record = {
+        pid: process.pid,
+        ...(pgid !== undefined ? { pgid } : {}),
+        slug,
+        startedAt: new Date().toISOString(),
+    };
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    let released = false;
+    return {
+        acquired: true,
+        release: () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            // Only remove a sentinel that is still OURS: if it was stolen as stale by
+            // another runner, deleting it would silently un-guard that runner's tree.
+            const current = readWorktreeWriter(dir, env);
+            if (current === undefined || current.pid === process.pid) {
+                rmSync(path, { force: true });
+            }
+        },
+    };
+}
+//# sourceMappingURL=worktree-writer-lock.js.map

package/dist/worktree-writer-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-writer-lock.js","sourceRoot":"","sources":["../src/worktree-writer-lock.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dorfl",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/wighawag/dorfl.git",

package/src/arbiter-refs.ts

@@ -0,0 +1,222 @@
+import {runAsync} from './git.js';
+
+/**
+ * **The ONE arbiter-ref refresh + authoritative-read seam** (observation
+ * `checkpoint-path-reports-its-own-write-as-absent`).
+ *
+ * Every "did my own write land?" / "is the branch on the arbiter?" question in
+ * the checkpoint + surface paths used to be answered the same wrong way: run a
+ * PLAIN `git fetch <arbiter>`, then `git rev-parse <arbiter>/<branch>` — i.e.
+ * read a REMOTE-TRACKING ref (`refs/remotes/<arbiter>/…`) and trust it. That is
+ * unsound in the configuration dorfl itself creates for `--isolated` runs, and
+ * it produced two field defects where dorfl reported its OWN successful write as
+ * absent:
+ *
+ *  1. A job worktree is `git worktree add`ed from the BARE HUB MIRROR
+ *     (`workspace.ts` `createJob` → `repo-mirror.ts` `ensureMirror`), whose
+ *     `origin` carries the MIRROR-style refspec `+refs/heads/*:refs/heads/*`.
+ *     So a plain fetch there writes `refs/heads/main`, and **never populates**
+ *     `refs/remotes/origin/main` at all. `rev-parse origin/main` then returns
+ *     whatever a PRIOR explicit-refspec fetch happened to leave behind — a value
+ *     that PREDATES the write being verified. A push that genuinely landed reads
+ *     back as "not our commit ⇒ rejected".
+ *  2. Worse, in that same worktree a plain `git fetch origin` **fails outright**
+ *     (`fatal: refusing to fetch into branch 'refs/heads/work/<slug>' checked out
+ *     at …`), because the mirror refspec's destination IS the branch the worktree
+ *     has checked out. So it refreshes NOTHING, and a follow-up
+ *     `rev-parse <arbiter>/work/<slug>` fails against a ref that never existed —
+ *     reported as "no work branch on <arbiter>" while the branch (and an hour of
+ *     agent work) sits on the arbiter.
+ *
+ * Both call sites now route through this module, which fixes the class rather
+ * than the two instances:
+ *
+ *   - {@link refreshArbiterRefs} prune-fetches with an EXPLICIT, per-branch
+ *     refspec into the `refs/remotes/<arbiter>/…` namespace the readers actually
+ *     read, tolerating the checked-out-branch refusal instead of being silently
+ *     defeated by it.
+ *   - {@link resolveArbiterBranch} answers the sha question from the ARBITER
+ *     ITSELF (`git ls-remote`), so no local ref-namespace/refspec accident can
+ *     make a landed write look absent. The local tracking ref is only a FALLBACK,
+ *     used when the arbiter cannot be reached at all.
+ *
+ * The `ls-remote`-is-authoritative stance is not new — it is the same one
+ * `continue-branch.ts` (`branchAheadOfArbiter`), `workspace.ts`, `integrator.ts`
+ * and `reap-branches.ts` already take for continue-detection and branch reaping.
+ * This module makes it the SHARED default for the post-write verification too,
+ * instead of each site re-deciding.
+ */
+
+/** How a {@link ResolvedArbiterBranch} sha was obtained — the read's PROVENANCE. */
+export type ArbiterRefAuthority =
+	/** Read from the arbiter itself (`git ls-remote`): AUTHORITATIVE. */
+	| 'arbiter'
+	/**
+	 * The arbiter could not be reached (offline / broken remote), so the local
+	 * remote-tracking ref was used. Best-effort: it may be stale, so a caller
+	 * deciding "did MY write land?" must NOT treat a mismatch here as proof of
+	 * a loss (see {@link ResolvedArbiterBranch.trustworthy}).
+	 */
+	| 'local-fallback'
+	/** Neither the arbiter nor any local ref has this branch. */
+	| 'absent';
+
+/** The resolved state of ONE branch on the arbiter (a single, coherent read). */
+export interface ResolvedArbiterBranch {
+	/** The unqualified branch name that was resolved (e.g. `main`, `work/task-x`). */
+	branch: string;
+	/** Its sha, or `undefined` when the branch exists nowhere we could look. */
+	sha?: string;
+	/** Where {@link sha} came from. */
+	authority: ArbiterRefAuthority;
+	/**
+	 * True iff the arbiter answered (`authority` is `arbiter` or `absent` off a
+	 * REACHABLE arbiter). When false the read is a stale-capable local fallback,
+	 * so a mismatch proves nothing and callers must not report a loss from it.
+	 */
+	trustworthy: boolean;
+	/** The `ls-remote` stderr when the arbiter could not be reached (diagnostics). */
+	unreachableDetail?: string;
+}
+
+/** The explicit refspec that maps an arbiter branch into the namespace we READ. */
+function trackingRefspec(arbiter: string, branch: string): string {
+	return `+refs/heads/${branch}:refs/remotes/${arbiter}/${branch}`;
+}
+
+/**
+ * PRUNE-FETCH the named arbiter branches into `refs/remotes/<arbiter>/<branch>`
+ * — the namespace every reader in this codebase actually reads — using an
+ * EXPLICIT per-branch refspec.
+ *
+ * Three properties matter, and all three are the reason this is not just
+ * `git fetch <arbiter>`:
+ *
+ *  - **Explicit refspec.** A bare-hub-mirror worktree's `origin` maps
+ *    `+refs/heads/*:refs/heads/*`, so a plain fetch never writes
+ *    `refs/remotes/<arbiter>/*`. Naming the destination makes the refresh work
+ *    identically in a normal clone AND in a mirror worktree.
+ *  - **`--prune`.** A branch DELETED on the arbiter (a `requeue --reset`, a
+ *    merge-reap, a cross-machine `gc`) must disappear from our view too;
+ *    otherwise a stale tracking ref answers a liveness question with a ghost.
+ *  - **Per-branch and SOFT.** Fetching branch-at-a-time means the one refspec
+ *    git refuses (the destination that is checked out in THIS worktree — see the
+ *    module doc) cannot abort the refresh of the others, which is exactly how the
+ *    single combined fetch silently refreshed nothing. Every failure is
+ *    tolerated and reported rather than thrown: this is a REFRESH, and the
+ *    authoritative answer comes from {@link resolveArbiterBranch} anyway.
+ *
+ * Returns the branches that could not be refreshed (for diagnostics only — a
+ * caller should not gate on it, because the authoritative read does not depend
+ * on the refresh succeeding).
+ */
+export async function refreshArbiterRefs(params: {
+	cwd: string;
+	arbiter: string;
+	/** Unqualified branch names to refresh (e.g. `['main', 'work/task-x']`). */
+	branches: readonly string[];
+	env?: NodeJS.ProcessEnv;
+}): Promise<{failed: string[]}> {
+	const {cwd, arbiter, branches, env} = params;
+	const failed: string[] = [];
+	for (const branch of branches) {
+		const fetched = await runAsync(
+			'git',
+			[
+				'fetch',
+				'--quiet',
+				'--prune',
+				arbiter,
+				trackingRefspec(arbiter, branch),
+			],
+			cwd,
+			{env},
+		);
+		if (fetched.status !== 0) {
+			failed.push(branch);
+		}
+	}
+	return {failed};
+}
+
+/**
+ * Resolve ONE branch's sha on the arbiter, ARBITER-AUTHORITATIVELY.
+ *
+ * `git ls-remote --heads <arbiter> <branch>` asks the arbiter directly, so the
+ * answer cannot be defeated by a local refspec/namespace accident — which is the
+ * whole point: this is the read a post-write verification uses to decide whether
+ * its OWN push landed, and that decision must never be made from a view that
+ * predates the push.
+ *
+ * Decision order:
+ *   - `ls-remote` exits 0 with a sha ⇒ `{sha, authority: 'arbiter'}` (trustworthy).
+ *   - `ls-remote` exits 0 with EMPTY output ⇒ the arbiter genuinely does not have
+ *     the branch ⇒ `{authority: 'absent'}` (trustworthy: a definite "no").
+ *   - `ls-remote` exits non-zero (unreachable / no such remote) ⇒ fall back to the
+ *     local `refs/remotes/<arbiter>/<branch>`, flagged `trustworthy: false` so a
+ *     caller cannot mistake a stale local read for proof of anything.
+ *
+ * Always call {@link refreshArbiterRefs} first when the caller ALSO needs the
+ * objects locally (a CAS base, a `merge-base` / `rev-list` comparison): a sha
+ * from `ls-remote` names a commit this repo may not have yet.
+ */
+export async function resolveArbiterBranch(params: {
+	cwd: string;
+	arbiter: string;
+	branch: string;
+	env?: NodeJS.ProcessEnv;
+}): Promise<ResolvedArbiterBranch> {
+	const {cwd, arbiter, branch, env} = params;
+	const ls = await runAsync(
+		'git',
+		['ls-remote', '--heads', arbiter, branch],
+		cwd,
+		{env},
+	);
+	if (ls.status === 0) {
+		// `<sha>\t<ref>` lines. `--heads <branch>` can match several refs when the
+		// name is a glob-ish prefix, so take the line whose ref is EXACTLY ours.
+		const sha = ls.stdout
+			.split('\n')
+			.map((line) => line.trim())
+			.filter((line) => line !== '')
+			.map((line) => line.split(/\s+/))
+			.find(([, ref]) => ref === `refs/heads/${branch}`)?.[0];
+		if (sha !== undefined && sha !== '') {
+			return {branch, sha, authority: 'arbiter', trustworthy: true};
+		}
+		// Reachable arbiter that does NOT have the branch: a definite, trustworthy
+		// "absent" (a stale local ref must not be able to resurrect it).
+		return {branch, authority: 'absent', trustworthy: true};
+	}
+	// Unreachable arbiter: best-effort local read, explicitly NOT trustworthy.
+	const local = await runAsync(
+		'git',
+		[
+			'rev-parse',
+			'--verify',
+			'--quiet',
+			`refs/remotes/${arbiter}/${branch}^{commit}`,
+		],
+		cwd,
+		{env},
+	);
+	const localSha = local.status === 0 ? local.stdout.trim() : '';
+	const unreachableDetail =
+		ls.stderr.trim() || `git ls-remote exit ${ls.status}`;
+	if (localSha !== '') {
+		return {
+			branch,
+			sha: localSha,
+			authority: 'local-fallback',
+			trustworthy: false,
+			unreachableDetail,
+		};
+	}
+	return {
+		branch,
+		authority: 'absent',
+		trustworthy: false,
+		unreachableDetail,
+	};
+}

package/src/do.ts

@@ -17,7 +17,8 @@ import {
 	resolvePromptGuidanceForItem,
 	PromptError,
 } from './prompt.js';
-import {NullHarness, type Harness} from './harness.js';
+import {NullHarness, type AgentTreeReap, type Harness} from './harness.js';
+import {acquireWorktreeWriterLock} from './worktree-writer-lock.js';
 import {PiHarness} from './pi-harness.js';
 import {launchWithOptionalWatch} from './agent-launch.js';
 import {ledgerRead, type LedgerReadStrategy} from './ledger-read.js';
@@ -155,10 +156,27 @@ function deadlineAutoContinueReason(params: {
 }
 function deadlineSurfaceReason(params: {
 	slug: string;
-	kind: 'no-progress' | 'ceiling';
+	kind: 'no-progress' | 'ceiling' | 'unreaped';
 	count?: number;
 	max?: number;
+	/** The harness's loud reap detail (the `unreaped` kind only). */
+	detail?: string;
 }): string {
+	if (params.kind === 'unreaped') {
+		// The auto-continue path is BLOCKED, not merely skipped: releasing the lock
+		// would let a successor onboard into a worktree a live predecessor may still
+		// be writing to (observation
+		// `checkpoint-releases-lock-while-predecessor-agent-still-writes`). The work
+		// is saved and pushed; only the hand-off is withheld.
+		return (
+			`deadline checkpoint (agent NOT verifiably stopped): '${params.slug}' hit ` +
+			'the dorfl-internal deadline and its WIP was saved + pushed, but the agent ' +
+			'process tree could not be confirmed dead, so the lock was NOT released and ' +
+			'no successor was dispatched — a second agent in the same working tree can ' +
+			'clobber or silently absorb the first one\u2019s edits. ' +
+			`${params.detail ?? ''}`.trim()
+		);
+	}
 	if (params.kind === 'no-progress') {
 		return (
 			`deadline checkpoint (no progress / ceiling): '${params.slug}' hit ` +
@@ -329,6 +347,16 @@ export type DoDorfl = (input: {
 	 * injected path — the real deadline race lives in `PiHarness.launchAsync`.
 	 */
 	timedOut?: boolean;
+	/**
+	 * **The simulated process-tree REAP verdict** for a {@link timedOut} stop
+	 * (observation `checkpoint-releases-lock-while-predecessor-agent-still-writes`).
+	 * Test-only signal, the sibling of `timedOut`, so an injected agent can drive
+	 * the "predecessor could not be verified dead" routing — where the checkpoint
+	 * must NOT release the item lock, because the next tick would then onboard a
+	 * successor into a working tree the predecessor may still be writing to.
+	 * Absent ⇒ nothing was left running (the pre-existing behaviour).
+	 */
+	reap?: AgentTreeReap;
 };
 
 export interface DoOptions {
@@ -1306,6 +1334,7 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 		detail?: string;
 		output?: string;
 		timedOut?: boolean;
+		reap?: AgentTreeReap;
 	};
 	try {
 		agent = await runDoAgent(options, tree.dir, prompt, slug);
@@ -1334,6 +1363,7 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 			cwd: tree.dir,
 			arbiter: tree.arbiterRemote,
 			maxAutoCheckpoints: options.maxAutoCheckpoints ?? 5,
+			reap: agent.reap,
 			env,
 			note,
 		});
@@ -1952,11 +1982,58 @@ async function runDoAgent(
 	detail?: string;
 	output?: string;
 	timedOut?: boolean;
+	reap?: AgentTreeReap;
 }> {
 	if (options.dorfl) {
 		return options.dorfl({cwd, prompt, slug, env: options.env});
 	}
 	const harness = options.harness ?? new NullHarness();
+
+	// WORKING-TREE SENTINEL (observation
+	// `checkpoint-releases-lock-while-predecessor-agent-still-writes`): the item
+	// lock guards the ITEM; this guards the TREE. A deadline checkpoint releases the
+	// item lock so the next tick can continue the task in the SAME worktree, so the
+	// item lock alone cannot keep a successor out while a predecessor is still
+	// alive. Refuse to launch a second agent into a tree that already has a LIVE
+	// writer, independently of the reap. A dead holder's sentinel is stale and taken
+	// over, so a crashed runner never poisons the worktree.
+	const writer = acquireWorktreeWriterLock({dir: cwd, slug, env: options.env});
+	if (!writer.acquired) {
+		return {ok: false, detail: writer.reason};
+	}
+	try {
+		return await launchAgentUnderWriterLock({
+			options,
+			cwd,
+			prompt,
+			slug,
+			harness,
+		});
+	} finally {
+		writer.release();
+	}
+}
+
+/**
+ * The actual harness launch, run while this process holds the worktree writer
+ * sentinel (see {@link runDoAgent}). Split out purely so the sentinel's
+ * acquire/release brackets the launch in a `try/finally` without indenting the
+ * whole body.
+ */
+async function launchAgentUnderWriterLock(params: {
+	options: DoAgentLaunchOptions;
+	cwd: string;
+	prompt: string;
+	slug: string;
+	harness: Harness;
+}): Promise<{
+	ok: boolean;
+	detail?: string;
+	output?: string;
+	timedOut?: boolean;
+	reap?: AgentTreeReap;
+}> {
+	const {options, cwd, prompt, slug, harness} = params;
 	// 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
@@ -1991,6 +2068,10 @@ async function runDoAgent(
 		detail: launched.detail,
 		output: launched.output,
 		timedOut: launched.timedOut,
+		// The harness's PROOF that a deadline-stopped agent's process tree is gone.
+		// Threaded to {@link routeDeadlineCheckpoint}, which refuses to release the
+		// item lock without it.
+		reap: launched.reap,
 	};
 }
 
@@ -2008,10 +2089,39 @@ async function routeDeadlineCheckpoint(params: {
 	cwd: string;
 	arbiter: string;
 	maxAutoCheckpoints: number;
+	/**
+	 * The harness's VERIFIED reap of the checkpointed agent's process tree. The
+	 * auto-continue branch releases the lock and lets the next tick dispatch a
+	 * SUCCESSOR into this same worktree, so it may only run once the predecessor
+	 * is proven gone (observation
+	 * `checkpoint-releases-lock-while-predecessor-agent-still-writes`). Absent ⮕
+	 * the harness spawned no killable group (test doubles, the null adapter), which
+	 * is treated as "nothing was left running".
+	 */
+	reap?: AgentTreeReap;
 	env: NodeJS.ProcessEnv | undefined;
 	note: (message: string) => void;
 }): Promise<DoResult> {
-	const {slug, branch, cwd, arbiter, maxAutoCheckpoints, env, note} = params;
+	const {slug, branch, cwd, arbiter, maxAutoCheckpoints, reap, env, note} =
+		params;
+
+	// 0. THE PREDECESSOR MUST BE DEAD BEFORE THE LOCK CAN MOVE.
+	//
+	// The item lock guards the ITEM; nothing guards the WORKING TREE. So if we
+	// released the lock while the checkpointed agent's tree were still alive, the
+	// next tick would onboard a successor into the very worktree the predecessor is
+	// still writing to — one lock, one working tree, two live writers. That was
+	// observed in the field: a predecessor kept writing for four minutes into its
+	// successor's run, and its last write landed on a file the successor had already
+	// read as clean in its opening `git status`.
+	//
+	// A reap we could not VERIFY is therefore a hard stop for the auto-continue
+	// path. We still SAVE the work below (never lose work) and still surface the
+	// item, but we do not hand the tree to anybody else.
+	const predecessorGone = reap === undefined || reap.reaped;
+	if (reap !== undefined && reap.escalatedToSigkill && reap.reaped) {
+		note(`Deadline checkpoint for '${slug}': ${reap.detail}`);
+	}
 
 	// 1. ALWAYS save the WIP first: commit any residue + push the work branch.
 	const savedReason = `deadline checkpoint save for '${slug}'`;
@@ -2040,7 +2150,11 @@ async function routeDeadlineCheckpoint(params: {
 		env,
 	});
 
-	if (madeProgressThisSession && checkpointCount <= maxAutoCheckpoints) {
+	if (
+		predecessorGone &&
+		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.
@@ -2057,10 +2171,27 @@ async function routeDeadlineCheckpoint(params: {
 			note,
 		});
 		if (returned.moved) {
+			// Derive this line from the SINGLE state `returnToBacklog` resolved, never
+			// from an independent assumption. It used to assert "the next tick continues
+			// from <branch>" unconditionally, which contradicted the requeue's own
+			// "'<slug>' has no work branch on <arbiter> — nothing to continue from" line
+			// emitted two lines earlier. Both cannot be true, and acting on the wrong one
+			// re-drives the task from scratch and discards the saved work (observation
+			// `checkpoint-path-reports-its-own-write-as-absent`). One resolved state, one
+			// story: mutually contradictory lines are worse than emitting nothing.
+			const continueFrom = returned.continueBranch;
+			const continuation =
+				continueFrom === undefined || continueFrom.aheadOfMain
+					? `lock released so the next tick continues from ${continueFrom?.branch ?? branch}`
+					: continueFrom.trustworthy
+						? 'lock released; the arbiter has no work to continue from, so the next ' +
+							'tick starts this item fresh'
+						: `lock released; the arbiter could not be read to confirm ${continueFrom.branch}, ` +
+							'so do NOT assume the work is gone — check the branch before re-driving';
 			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}`;
+				`${continuation}. ${reason}`;
 			note(message);
 			return {
 				exitCode: 0,
@@ -2080,14 +2211,16 @@ async function routeDeadlineCheckpoint(params: {
 	// 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 surfaceReason = !predecessorGone
+		? deadlineSurfaceReason({slug, kind: 'unreaped', detail: reap?.detail})
+		: madeProgressThisSession
+			? deadlineSurfaceReason({
+					slug,
+					kind: 'ceiling',
+					count: checkpointCount,
+					max: maxAutoCheckpoints,
+				})
+			: deadlineSurfaceReason({slug, kind: 'no-progress'});
 	const routed = await ledgerWrite.applyNeedsAttentionTransition({
 		cwd,
 		slug,
@@ -2097,12 +2230,14 @@ async function routeDeadlineCheckpoint(params: {
 		note,
 	});
 	const report = routed.moved ? routeReport(routed, branch) : undefined;
+	const why = !predecessorGone
+		? 'the checkpointed agent could not be verified dead'
+		: madeProgressThisSession
+			? `ceiling ${checkpointCount}/${maxAutoCheckpoints}`
+			: 'no progress this session';
 	const message = routed.moved
-		? `Surfaced '${slug}' at the deadline checkpoint (${
-				madeProgressThisSession
-					? `ceiling ${checkpointCount}/${maxAutoCheckpoints}`
-					: 'no progress this session'
-			}); ${report!.fragment}. ${surfaceReason}`
+		? `Surfaced '${slug}' at the deadline checkpoint (${why}); ` +
+			`${report!.fragment}. ${surfaceReason}`
 		: `Could not surface '${slug}' at the deadline checkpoint ` +
 			`(${routed.reasonNotMoved ?? 'unknown'}). ${surfaceReason}`;
 	note(message);
@@ -2746,6 +2881,7 @@ async function runRemotePipeline(
 		detail?: string;
 		output?: string;
 		timedOut?: boolean;
+		reap?: AgentTreeReap;
 	};
 	try {
 		agent = await runDoAgent(options, cwd, prompt, slug);
@@ -2770,6 +2906,7 @@ async function runRemotePipeline(
 			cwd,
 			arbiter: arbiterRemote,
 			maxAutoCheckpoints: options.maxAutoCheckpoints ?? 5,
+			reap: agent.reap,
 			env,
 			note,
 		});