dorfl 0.14.2 → 0.15.0

package/src/triage-persist.ts

@@ -10,7 +10,12 @@ import {
 import {resolveSidecarIdentity, sidecarPathFor} from './sidecar.js';
 import type {TriageAutoKind} from './triage-gate.js';
 import {renderTaskBody, renderSpecBody} from './buildable-body.js';
-import {setFrontmatterMarker} from './frontmatter.js';
+import {
+	assertFrontmatterFields,
+	FrontmatterRenderError,
+	quoteYamlScalar,
+	setFrontmatterMarker,
+} from './frontmatter.js';
 import {ensureSafeSlug} from './slug-safety.js';
 
 /**
@@ -476,6 +481,21 @@ export async function promoteObservation(
 		'promotedFrom',
 		item,
 	);
+	// Re-parse the RUNNER-OWNED keys before anything is written (task
+	// `intake-frontmatter-title-injection-strips-origin-stamp`). The stamp above
+	// replaces the FIRST `slug:` line, but the frontmatter parser keeps the LAST,
+	// so a drafted body that repeats `slug:` (or `promotedFrom:`) would still set
+	// the item's identity. Refuse it loudly; the observation stays for a retry.
+	try {
+		assertFrontmatterFields(content, {slug: newSlug, promotedFrom: item});
+	} catch (err) {
+		if (!(err instanceof FrontmatterRenderError)) throw err;
+		return {
+			outcome: 'usage-error',
+			exitCode: 1,
+			message: `promote ${item}: ${err.message}`,
+		};
+	}
 
 	// The note + its answered sidecar `git rm` IN THE SAME create commit (promote =
 	// ONE atomic commit). A CAS LOSER never reaches the commit, so it leaves both
@@ -620,7 +640,9 @@ function buildPromotedBody(
 	const hasQuestions = openQuestions.trim() !== '';
 	const frontmatter: string[] = [
 		'---',
-		`title: ${slug}`,
+		// The title is the (sanitised, agent-draftable) slug, still written through
+		// the shared frontmatter quoter so every runner-rendered title has one shape.
+		`title: ${quoteYamlScalar(slug)}`,
 		`slug: ${slug}`,
 		`needsAnswers: ${hasQuestions ? 'true' : 'false'}`,
 		// A SPEC is a north-star doc, not a blockable task — only the task shape carries

package/src/verify-workflow-template.ts

@@ -21,6 +21,7 @@
  * trigger surface — the forward seam the spec's Applied Answers q3 names.
  */
 
+import {ACTION_PINS, pinnedUses} from './install-ci-action-pins.js';
 import type {ResolvedCIConfig} from './install-ci-core.js';
 import {shouldDropCheckoutCredentials} from './install-ci-core.js';
 
@@ -101,9 +102,9 @@ concurrency:
   group: ${VERIFY_CHECK_CONTEXT}-\${{ github.ref }}
   cancel-in-progress: true
 
-# NO \`workflows\` permission (US #9). \`contents: read\` is all the gate needs.
-permissions:
-  contents: read
+# Nothing at workflow level: the job grants its own scopes. NO \`workflows\`
+# permission (US #9).
+permissions: {}
 
 jobs:
   # The job name IS the GitHub check context — it must equal VERIFY_CHECK_CONTEXT
@@ -111,8 +112,11 @@ jobs:
   # context this workflow does not produce.
   ${VERIFY_CHECK_CONTEXT}:
     runs-on: ubuntu-latest
+    # \`contents: read\` is all the gate needs.
+    permissions:
+      contents: read
     steps:
-      - uses: actions/checkout@v5
+      - uses: ${pinnedUses(ACTION_PINS.checkout)}
         with:
           fetch-depth: 0${checkoutCredentials}
       - uses: ./.github/actions/dorfl-setup

package/src/verify.ts

@@ -1,4 +1,5 @@
 import {spawn} from 'node:child_process';
+import {assertAgentOrRepoCodeAllowed} from './phase.js';
 
 /**
  * The per-repo acceptance gate, run as `dorfl verify`. It is a
@@ -149,6 +150,9 @@ export const VERIFY_OUTPUT_TAIL_LINES = 20;
 export async function runVerify(
 	options: RunVerifyOptions,
 ): Promise<RunVerifyResult> {
+	// PHASE GUARD: the gate runs repository code, never in the CI lock/apply
+	// phases (their jobs hold the write token; see `phase.ts`).
+	assertAgentOrRepoCodeAllowed('verify');
 	let commands: string[];
 	try {
 		commands = resolveVerifyCommands(options.verify);

package/src/watch-session.ts

@@ -1,4 +1,5 @@
 import {open, type FileHandle} from 'node:fs/promises';
+import type {CutOffTurn} from './harness.js';
 
 /**
  * The **`do --watch` observer** (tasks `do-watch` + `do-watch-session-log-format`)
@@ -151,6 +152,14 @@ interface SessionLogRecord {
 		content?: unknown;
 		/** The Anthropic-API turn-termination reason (mirrored by pi into the session log). */
 		stop_reason?: unknown;
+		/**
+		 * pi's OWN normalised turn-termination reason (`stop` / `toolUse` / `length`
+		 * / `error` / `aborted`), the key real pi session logs carry on every
+		 * assistant message.
+		 */
+		stopReason?: unknown;
+		/** The provider's error text pi records on an `error`-stopped turn. */
+		errorMessage?: unknown;
 		/** The turn's token usage (mirrored by pi). `output` OR `output_tokens` is the produced-token count. */
 		usage?: unknown;
 	};
@@ -292,7 +301,7 @@ function assistantContentText(content: unknown): string {
  * (task `harness-agent-output`) — the agent's final ANSWER, surfaced through
  * the harness seam as `LaunchResult.output`. A thin delegate to
  * {@link lastAssistantTurn} (one walk, returning the `.text`); the turn reader
- * ALSO carries the `stop_reason`/`usage` the pi adapter uses for the
+ * ALSO carries the stop reason + `usage` the pi adapter uses for the
  * `LaunchResult.outputCapped` cap-truncation signal.
  *
  * Kept as a PURE `string → string | undefined` function on purpose: the pi
@@ -315,8 +324,9 @@ export function lastAssistantText(jsonl: string): string | undefined {
 }
 
 /**
- * The last assistant turn's TEXT + its Anthropic-API turn-termination signal
- * (`stop_reason` + `usage.output`/`usage.output_tokens` token count). Reused by
+ * The last assistant turn's TEXT + its turn-termination signal (the stop
+ * reason, read by {@link readStopReason}, + the `usage.output`/`usage.output_tokens`
+ * token count). Reused by
  * the pi adapter to populate BOTH `LaunchResult.output` (the `.text`) AND
  * `LaunchResult.outputCapped` (the cap-truncation signal — see
  * {@link isOutputCappedTurn}). One walk over the `.jsonl`, not two. `text` is the
@@ -328,16 +338,34 @@ export function lastAssistantText(jsonl: string): string | undefined {
 export interface LastAssistantTurn {
 	/** The last assistant turn's concatenated `text` parts (its answer). */
 	text?: string;
-	/** The turn's `stop_reason` (raw — `null`, `'end_turn'`, `'max_tokens'`, …). */
-	stopReason?: string | null;
+	/**
+	 * The last TEXT turn's stop reason, read by {@link readStopReason} (pi's
+	 * `stopReason`: `'stop'`, `'toolUse'`, `'length'`, …; or a raw `stop_reason`
+	 * such as `'end_turn'` / `'max_tokens'` for another harness shape).
+	 */
+	stopReason?: string;
 	/** The turn's produced output-token count (`usage.output` OR `usage.output_tokens`). */
 	outputTokens?: number;
+	/**
+	 * The stop reason of the FINAL assistant message in the log, WHATEVER it
+	 * carried (text, tool calls, or only a thinking block), read by the SAME
+	 * {@link readStopReason} as {@link stopReason}. Unlike {@link stopReason}
+	 * (which belongs to the last TEXT turn), this is how the run actually ENDED:
+	 * a turn that spent its whole output budget thinking has no text, so only this
+	 * field sees it. `undefined` when the log has no assistant message or the
+	 * final one carries no stop reason. Read by {@link cutOffTurnOf}.
+	 */
+	finalStopReason?: string;
+	/** The final assistant message's `errorMessage` (pi records it on an `error` stop). */
+	finalErrorMessage?: string;
 }
 
 export function lastAssistantTurn(jsonl: string): LastAssistantTurn {
 	let lastText: string | undefined;
-	let lastStopReason: string | null | undefined = undefined;
+	let lastStopReason: string | undefined = undefined;
 	let lastOutputTokens: number | undefined = undefined;
+	let finalStopReason: string | undefined = undefined;
+	let finalErrorMessage: string | undefined = undefined;
 	for (const line of jsonl.split('\n')) {
 		const trimmed = line.trim();
 		if (trimmed === '') {
@@ -360,10 +388,17 @@ export function lastAssistantTurn(jsonl: string): LastAssistantTurn {
 		if (!message || message.role !== 'assistant') {
 			continue;
 		}
+		// EVERY assistant message (text or not) moves the "how did the run end"
+		// pointer: the final one wins.
+		finalStopReason = readStopReason(message);
+		finalErrorMessage =
+			typeof message.errorMessage === 'string' && message.errorMessage !== ''
+				? message.errorMessage
+				: undefined;
 		const text = assistantContentText(message.content);
 		if (text !== '') {
 			lastText = text; // a later text turn supersedes an earlier one.
-			lastStopReason = readStopReason(message.stop_reason);
+			lastStopReason = readStopReason(message);
 			lastOutputTokens = readOutputTokens(message.usage);
 		}
 	}
@@ -371,37 +406,60 @@ export function lastAssistantTurn(jsonl: string): LastAssistantTurn {
 		text: lastText,
 		stopReason: lastStopReason,
 		outputTokens: lastOutputTokens,
+		finalStopReason,
+		finalErrorMessage,
 	};
 }
 
 /**
- * Is this assistant turn's signal an OUTPUT-CAP truncation — the turn did NOT
- * end naturally? `stop_reason` `null`/`None`/`undefined` (the turn was cut off) OR
- * `'max_tokens'` (the model hit its output-token cap), together with a positive
- * produced-token count. The `null`/`None` form is what pi's session log records
- * when the `--print` run is truncated before the turn closes (observation
- * `tasker-review-edits-payload-caps-the-verdict-response`); `'max_tokens'` is the
- * standard API cap signal. Both name the same structural cause: the verdict never
- * finished.
+ * Was the run's FINAL assistant turn CUT OFF rather than ended normally (task
+ * `a-truncated-agent-turn-routes-as-agent-failed`)? `length` (the per-turn
+ * output-token cap: observed with a turn whose whole 16,384-token budget went
+ * into a thinking block, no text, no tool call) and `error` (a provider error)
+ * are the two cut-off causes; every other reason (`stop`, `toolUse`, `aborted`,
+ * or none recorded) returns `undefined`. `aborted` is deliberately NOT a cut-off
+ * here: it is what a deliberate kill (the deadline stop) leaves, which has its
+ * own checkpoint route.
+ */
+export function cutOffTurnOf(turn: LastAssistantTurn): CutOffTurn | undefined {
+	if (turn.finalStopReason !== 'length' && turn.finalStopReason !== 'error') {
+		return undefined;
+	}
+	return turn.finalErrorMessage === undefined
+		? {cause: turn.finalStopReason}
+		: {cause: turn.finalStopReason, errorMessage: turn.finalErrorMessage};
+}
+
+/**
+ * Did this assistant turn HIT THE OUTPUT-TOKEN CAP (and nothing else)? True iff
+ * its stop reason is pi's `'length'` (or the raw API `'max_tokens'`, for a
+ * harness that mirrors the provider's own key) AND it produced a positive
+ * token count (observation `tasker-review-edits-payload-caps-the-verdict-response`:
+ * the verdict never finished). A normal end (`'stop'`, `'toolUse'`, `'end_turn'`,
+ * …), an error/abort, or NO recorded stop reason is NOT a cap: an unknown reason
+ * proves nothing, and inferring a cap from it named every pi parse failure a cap
+ * truncation (observation `output-capped-signal-reads-the-wrong-stop-reason-key`).
  */
 export function isOutputCappedTurn(turn: LastAssistantTurn): boolean {
 	const cappedReason =
-		turn.stopReason === null ||
-		turn.stopReason === undefined ||
-		turn.stopReason === 'None' ||
-		turn.stopReason === 'max_tokens';
+		turn.stopReason === 'length' || turn.stopReason === 'max_tokens';
 	return cappedReason && (turn.outputTokens ?? 0) > 0;
 }
 
-/** Read `stop_reason` defensively as a string-or-null (pi may emit `None`/`null`). */
-function readStopReason(raw: unknown): string | null | undefined {
-	if (raw === null) {
-		return null;
-	}
-	if (typeof raw === 'string') {
-		return raw;
-	}
-	return undefined;
+/**
+ * THE one stop-reason reader, shared by the output-cap signal
+ * ({@link isOutputCappedTurn}, via `stopReason`) and the cut-off signal
+ * ({@link cutOffTurnOf}, via `finalStopReason`) so the two can never disagree
+ * about a turn. Reads pi's normalised camelCase `message.stopReason` (what real
+ * pi session logs carry), falling back to a snake_case `message.stop_reason` for
+ * other harness shapes. Anything that is not a string (absent, `null`) is
+ * `undefined`: no recorded reason.
+ */
+function readStopReason(
+	message: NonNullable<SessionLogRecord['message']>,
+): string | undefined {
+	const raw = message.stopReason ?? message.stop_reason;
+	return typeof raw === 'string' ? raw : undefined;
 }
 
 /** Read the produced output-token count from `usage.output` OR `usage.output_tokens`. */

package/src/work-layout.ts

@@ -217,18 +217,26 @@ export type TaskResolutionFolder =
 	| 'tasks-backlog';
 
 /**
- * The task LIFECYCLE folders a `task:<slug>` / lone-task `issue:` can reside
- * in (spec-complete.ts + close-job.ts `TASK_FOLDERS`): `tasks-ready`, `in-progress`,
- * `done`. `needs-attention` was dropped post-cutover
+ * The task LIFECYCLE folders a `spec:<slug>` task / lone-task `issue:` can reside
+ * in (spec-complete.ts + close-job.ts `TASK_FOLDERS`): EVERY folder a task body can
+ * rest in, staged to terminal: `tasks-backlog`, `tasks-ready`, `in-progress`,
+ * `done`, `cancelled`. `tasks-backlog` and `cancelled` were added by task
+ * `spec-complete-counts-staged-and-cancelled-tasks`: tasking stages new tasks in
+ * `tasks/backlog/` by default, so a scan that skipped it declared a spec complete
+ * (and the CI close-job closed its issue) while work was still staged; `cancelled`
+ * is scanned so a caller can tell "all cancelled" apart from "no tasks".
+ * `needs-attention` was dropped post-cutover
  * (`finish-needs-attention-folder-cutover-remove-legacy-recovery-readers`, ratified
  * in `docs/adr/needs-attention-folder-cutover-followup-nits.md`): the folder is
  * retired — a stuck item is the per-item lock `state: stuck` with the body resting
  * in `tasks/ready/`, so no task ever resides in `work/needs-attention/`.
  */
 export const TASK_LIFECYCLE_FOLDERS = [
+	'tasks-backlog',
 	'tasks-ready',
 	'in-progress',
 	'done',
+	'cancelled',
 ] as const satisfies readonly WorkFolderKey[];
 
 /** One of the task lifecycle folders (spec-complete.ts / close-job.ts). */

package/src/workspace.ts

@@ -2,11 +2,19 @@ import {
 	existsSync,
 	lstatSync,
 	readFileSync,
+	realpathSync,
 	rmSync,
 	writeFileSync,
 } from 'node:fs';
 import {basename, dirname, join} from 'node:path';
-import {git} from './git.js';
+import {git, run} from './git.js';
+// Call-time use only (gc.ts imports this module too; an ESM cycle is fine for
+// functions/constants read inside function bodies).
+import {
+	evaluateDeletionSafety,
+	RETAIN_REASON_TEXT,
+	type RetainReason,
+} from './gc.js';
 import {
 	encodeRepoKey,
 	ensureMirror,
@@ -15,8 +23,9 @@ import {
 import {
 	branchAheadOfArbiter,
 	rebaseContinuedBranchOntoMain,
-	pushContinuedBranchWithStaleLeaseRetry,
+	type ContinueRebaseFailure,
 } from './continue-branch.js';
+import {refWrite} from './ref-write.js';
 import {type HarnessRecord} from './harness.js';
 import {brand} from './brand.js';
 import {workBranchRef, type SlugNamespace} from './slug-namespace.js';
@@ -170,6 +179,14 @@ export interface CreateJobOptions {
 	workspacesDir: string;
 	/** The initial harness block to persist in the record (default: null adapter). */
 	harness?: HarnessRecord;
+	/**
+	 * Rebase a kept branch LOCALLY only: skip the `--force-with-lease` push of the
+	 * rebased tip (ADR `ci-agent-job-holds-no-write-token` decision 7). The CI
+	 * agent job holds a read-only token, so its continue rebase stays local and
+	 * the apply job pushes the tip, leased on the one the lock job observed
+	 * (task `ci-split-answered-merge-action`). Default `false`: today's push.
+	 */
+	localContinue?: boolean;
 	env?: NodeJS.ProcessEnv;
 }
 
@@ -201,12 +218,21 @@ export interface Job {
 	 */
 	continued: boolean;
 	/**
-	 * True iff a CONTINUE rebase onto fresh main CONFLICTED (aborted, never
-	 * auto-resolved). The caller (`run`'s pipeline / `do --remote`) routes the
-	 * item to needs-attention via the §10 path; the worktree is left on the
-	 * un-rebased kept branch as the never-lose-work signal.
+	 * True iff a CONTINUE rebase onto fresh main did not apply (aborted, never
+	 * auto-resolved): a genuine conflict OR any other rebase failure, which
+	 * {@link continueRebaseFailure} tells apart. The caller (`run`'s pipeline /
+	 * `do --remote`) routes the item to needs-attention via the §10 path; the
+	 * worktree is left on the un-rebased kept branch as the never-lose-work
+	 * signal.
 	 */
 	continueRebaseConflict: boolean;
+	/**
+	 * Why the continue rebase did not apply (set exactly when
+	 * {@link continueRebaseConflict} is): the conflicting paths or git's report,
+	 * and the `main` sha rebased onto. Render it with
+	 * `describeContinueRebaseFailure` in the needs-attention reason.
+	 */
+	continueRebaseFailure?: ContinueRebaseFailure;
 	/**
 	 * Set iff the CONTINUE reconcile push to the arbiter FAILED TERMINALLY (the
 	 * stale-lease retry cap was exhausted, or a non-stale-lease rejection such as
@@ -229,6 +255,48 @@ export interface Job {
 
 const DEFAULT_HARNESS: HarnessRecord = {adapter: 'null'};
 
+/**
+ * Carry the commit identity git resolves in the checkout `cwd` (`user.name` /
+ * `user.email`, read with `env`) into `env`'s own git config
+ * (`GIT_CONFIG_COUNT` / `GIT_CONFIG_KEY_<n>` / `GIT_CONFIG_VALUE_<n>`), so a
+ * job worktree cut from the hub mirror commits as that checkout does.
+ *
+ * WHY (task `a-failed-rebase-reports-its-real-cause`): the hub mirror is its
+ * OWN repository under `workspacesDir`, so it does not see the checkout's
+ * local config. The generated CI workflows set the identity with a plain
+ * `git config user.name` / `user.email` IN THE CHECKOUT, and a GitHub-hosted
+ * runner has no global identity, so in the CI agent job the continue rebase of
+ * an answered merge (which rewrites commits, so needs a committer) failed with
+ * git's `unable to auto-detect email address`, reported as a conflict.
+ *
+ * Returns `env` unchanged when the checkout resolves no complete identity (git
+ * then behaves as before). The value is exactly what git already uses in the
+ * checkout, so this changes nothing for a caller whose identity was global.
+ */
+export function withCheckoutCommitIdentity(
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): NodeJS.ProcessEnv | undefined {
+	const read = (key: string): string =>
+		run('git', ['config', '--get', key], cwd, {env}).stdout.trim();
+	const name = read('user.name');
+	const email = read('user.email');
+	if (name === '' || email === '') {
+		return env;
+	}
+	const base = env ?? process.env;
+	const parsed = Number(base.GIT_CONFIG_COUNT ?? '0');
+	const count = Number.isInteger(parsed) && parsed > 0 ? parsed : 0;
+	return {
+		...base,
+		GIT_CONFIG_COUNT: String(count + 2),
+		[`GIT_CONFIG_KEY_${count}`]: 'user.name',
+		[`GIT_CONFIG_VALUE_${count}`]: name,
+		[`GIT_CONFIG_KEY_${count + 1}`]: 'user.email',
+		[`GIT_CONFIG_VALUE_${count + 1}`]: email,
+	};
+}
+
 /**
  * Create (or recreate) a job: ensure the hub mirror via `repo-mirror`, then
  * `git worktree add` a per-job worktree OUTSIDE the hub at
@@ -275,7 +343,7 @@ export function createJob(options: CreateJobOptions): Job {
 		env,
 	});
 	let continued = false;
-	let continueRebaseConflict = false;
+	let continueRebaseFailure: ContinueRebaseFailure | undefined;
 	let continuePushFailure: string | undefined;
 
 	if (continueFromKept) {
@@ -302,9 +370,9 @@ export function createJob(options: CreateJobOptions): Job {
 		// NEVER --force, NEVER to main (§11). A CONFLICT → aborted (never
 		// auto-resolved) + flagged so the caller routes to needs-attention.
 		const rebase = rebaseContinuedBranchOntoMain(dir, 'main', env);
-		if (rebase.kind === 'conflict') {
-			continueRebaseConflict = true;
-		} else {
+		if (rebase.kind !== 'clean') {
+			continueRebaseFailure = rebase;
+		} else if (options.localContinue !== true) {
 			// Push the rebased tip with --force-with-lease, SURVIVING a stale-lease
 			// ("stale info") rejection: re-fetch the arbiter `work/<slug>` + main,
 			// re-rebase onto current main, and retry (bounded) instead of stranding the
@@ -320,7 +388,7 @@ export function createJob(options: CreateJobOptions): Job {
 			// to needs-attention — the kept work stays committed + recoverable on the
 			// branch — instead of stranding it.
 			try {
-				const pushed = pushContinuedBranchWithStaleLeaseRetry({
+				const pushed = refWrite.pushContinuedBranch({
 					cwd: dir,
 					branch,
 					arbiter: 'origin',
@@ -328,14 +396,30 @@ export function createJob(options: CreateJobOptions): Job {
 					expectedRemoteTip,
 					env,
 				});
-				if (pushed.kind === 'conflict') {
-					continueRebaseConflict = true;
+				if (pushed.kind !== 'pushed') {
+					continueRebaseFailure = pushed;
 				}
 			} catch (err) {
 				continuePushFailure = err instanceof Error ? err.message : String(err);
 			}
 		}
 	} else {
+		// NEVER-LOSE-WORK guard (task
+		// `a-fresh-claim-does-not-discard-a-retained-worktrees-unsaved-work`): a
+		// RETAINED worktree at this work-id (a crashed run whose lock was released
+		// some way other than `requeue`, e.g. `release-lock`) may hold work the
+		// arbiter lacks. Apply the SAME deletion-safety predicate `gc` and the
+		// requeue save use; if it does not hold, REFUSE loudly (throw) and leave the
+		// worktree untouched instead of clearing it below.
+		refuseToClearUnsavedWorktree({
+			dir,
+			branch,
+			slug,
+			type: options.type ?? 'task',
+			mirrorPath: mirror.path,
+			env,
+		});
+
 		// Clear any stale registration for this work-id (idempotent re-create): a
 		// leftover worktree dir or branch from a prior crashed run would block the
 		// `worktree add`. We use git's own removal, never a bare rm -rf (ADR §4).
@@ -366,7 +450,8 @@ export function createJob(options: CreateJobOptions): Job {
 		record,
 		mirror,
 		continued,
-		continueRebaseConflict,
+		continueRebaseConflict: continueRebaseFailure !== undefined,
+		...(continueRebaseFailure === undefined ? {} : {continueRebaseFailure}),
 		continuePushFailure,
 		dispose() {
 			git(['worktree', 'remove', '--force', dir], mirror.path, {env});
@@ -376,6 +461,117 @@ export function createJob(options: CreateJobOptions): Job {
 	};
 }
 
+/**
+ * Thrown by {@link createJob} when its FRESH-cut path finds a RETAINED job
+ * worktree at the work-id that holds work the arbiter lacks (the gc
+ * deletion-safety predicate, {@link evaluateDeletionSafety}, does not hold).
+ * Clearing it would silently discard that work, so the claim is refused and the
+ * worktree is left untouched. The message names the path and the recovery.
+ *
+ * A caller that best-effort reaps a leaked worktree after `createJob` threw
+ * (`do --isolated`'s `reapPreparedWorktreeLeak`) MUST skip that reap for this
+ * error: the worktree is not a leak, it is the work being protected.
+ */
+export class RetainedWorktreeUnsavedWorkError extends Error {
+	readonly dir: string;
+	/** The branch the retained worktree is on (its HEAD branch, else the job branch). */
+	readonly retainedBranch: string;
+	readonly reason: RetainReason;
+	constructor(input: {
+		message: string;
+		dir: string;
+		retainedBranch: string;
+		reason: RetainReason;
+	}) {
+		super(input.message);
+		this.name = 'RetainedWorktreeUnsavedWorkError';
+		this.dir = input.dir;
+		this.retainedBranch = input.retainedBranch;
+		this.reason = input.reason;
+	}
+}
+
+/**
+ * The claim-time never-lose-work guard: if `dir` is a real git working tree (a
+ * retained job worktree, not an orphan dir / dangling symlink the self-heal in
+ * {@link forceClearWorktreePath} handles) and the shared deletion-safety
+ * predicate does NOT hold for it (dirty tree, or a tip the arbiter lacks),
+ * throw {@link RetainedWorktreeUnsavedWorkError}. A worktree that is provably
+ * safe (clean AND merged/pushed) passes, and the caller clears it as before.
+ */
+function refuseToClearUnsavedWorktree(input: {
+	dir: string;
+	branch: string;
+	slug: string;
+	type: SlugNamespace;
+	mirrorPath: string;
+	env: NodeJS.ProcessEnv | undefined;
+}): void {
+	const {dir, branch, slug, type, mirrorPath, env} = input;
+	if (!isGitWorkingTreeRoot(dir, env)) {
+		return;
+	}
+	// Judge the worktree by the branch it is ACTUALLY on (a same-slug run of the
+	// other type shares this work-id), falling back to the job branch when HEAD
+	// is detached (e.g. a run killed mid-rebase).
+	const head = run('git', ['symbolic-ref', '-q', '--short', 'HEAD'], dir, {
+		env,
+	});
+	const retainedBranch =
+		head.status === 0 && head.stdout.trim() !== ''
+			? head.stdout.trim()
+			: branch;
+	const verdict = evaluateDeletionSafety({
+		dir,
+		branch: retainedBranch,
+		env,
+	});
+	if (verdict.safe) {
+		return;
+	}
+	const reason = verdict.reason ?? 'unmerged-commits';
+	const save =
+		type === 'task' && retainedBranch === branch
+			? `Save it with \`dorfl requeue ${slug}\` (with the lock held, it commits ` +
+				`any residue as a wip commit and pushes ${branch}, so the next claim ` +
+				`continues from it), or push ${retainedBranch} from ${dir} yourself.`
+			: `Save it by pushing ${retainedBranch} from ${dir}, then release the lock.`;
+	throw new RetainedWorktreeUnsavedWorkError({
+		dir,
+		retainedBranch,
+		reason,
+		message:
+			`refusing to cut a fresh ${branch} for '${slug}': the retained job ` +
+			`worktree ${dir} (on ${retainedBranch}) holds work the arbiter lacks ` +
+			`(${RETAIN_REASON_TEXT[reason]}), and clearing it would discard that ` +
+			`work. The worktree is left untouched. ${save} To discard it on purpose, ` +
+			`run \`git -C ${mirrorPath} worktree remove --force ${dir}\` and claim again.`,
+	});
+}
+
+/**
+ * True iff `dir` is itself the ROOT of a git working tree (a registered job
+ * worktree). An orphan directory git does not manage, or a dangling symlink,
+ * is not (it holds no git-tracked work, and the self-heal removes it).
+ */
+function isGitWorkingTreeRoot(
+	dir: string,
+	env: NodeJS.ProcessEnv | undefined,
+): boolean {
+	if (!existsSync(dir)) {
+		return false;
+	}
+	const top = run('git', ['rev-parse', '--show-toplevel'], dir, {env});
+	if (top.status !== 0) {
+		return false;
+	}
+	try {
+		return realpathSync(top.stdout.trim()) === realpathSync(dir);
+	} catch {
+		return false;
+	}
+}
+
 /**
  * Write (or overwrite) a job's record to its SIBLING path ({@link jobRecordPath},
  * `<work-id>.json` next to the worktree), OUTSIDE the checked-out tree. `dir` is