dorfl 0.1.1 → 0.2.0

package/src/drop-source.ts

@@ -5,7 +5,7 @@ import {resolveSidecarIdentity, sidecarPathFor} from './sidecar.js';
 import {resolveItemPathByIdentity} from './item-path.js';
 
 /**
- * The DIRECT-DELETE helper (prd
+ * The DIRECT-DELETE helper (spec
  * `agentic-question-resolution-retire-disposition-vocabulary`, US #5/#11; task
  * `direct-delete-question-cli-helper`) — the "I just want to throw this away"
  * path that `git rm`s a source item AND its question sidecar (when present) in
@@ -33,7 +33,7 @@ export interface DropSourceOptions {
 	/** Working clone/worktree the deletion commits in. */
 	cwd: string;
 	/**
-	 * The namespaced item identity to delete (`task:foo` / `prd:bar` /
+	 * The namespaced item identity to delete (`task:foo` / `spec:bar` /
 	 * `observation:baz` / `obs:baz` / a bare `<slug>` = task). Resolved to its
 	 * on-disk path by identity, folder-agnostic.
 	 */

package/src/env-config.ts

@@ -65,7 +65,7 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// LOUDLY naming the variable + the valid options.
 	observationTriage: {enum: ['off', 'ask', 'auto']},
 	// The merge-question SURFACER gate is a 3-state ENUM coercion (mirrors
-	// `observationTriage`'s shape; SEPARATE axis with a HIGHER default, prd
+	// `observationTriage`'s shape; SEPARATE axis with a HIGHER default, spec
 	// `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
 	// `merge-questions-gate-axis`), so `DORFL_MERGE_QUESTIONS=off|ask|auto`
 	// works and a typo FAILS LOUDLY naming the variable + the valid options.
@@ -74,8 +74,8 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// `DORFL_SURFACE_BLOCKERS=true|false` works and a typo FAILS LOUDLY.
 	surfaceBlockers: 'boolean',
 	// `surfaceStaging` (the BOOLEAN gate-family member that widens the SURFACE
-	// candidate set to include STAGING — `tasks/backlog/` + `prds/proposed/` —
-	// not only the agent pool; prd
+	// candidate set to include STAGING — `tasks/backlog/` + `specs/proposed/` —
+	// not only the agent pool; spec
 	// `staging-surface-and-apply-promote-safety` F2) coerces as a BOOLEAN like
 	// `autoBuild`/`surfaceBlockers`, so `DORFL_SURFACE_STAGING=true|false`
 	// works and a typo FAILS LOUDLY. Resolution chain identical to the other
@@ -98,14 +98,14 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// works and a typo FAILS LOUDLY. Unset ⇒ the tasking transition falls back to
 	// `integration` (the flat value). It NEVER touches the build transition or intake.
 	taskingIntegration: {enum: ['propose', 'merge']},
-	// `tasksLandIn` (the per-repo TASK-PLACEMENT default — prd
+	// `tasksLandIn` (the per-repo TASK-PLACEMENT default — spec
 	// `staging-pool-position-gate-and-trust-model` US #5) coerces as the
-	// `pre-backlog`/`ready` enum, so `DORFL_TASKS_LAND_IN=ready` works and a
+	// `backlog`/`ready` enum, so `DORFL_TASKS_LAND_IN=ready` works and a
 	// typo FAILS LOUDLY. Same
 	// precedence chain as `taskingIntegration` (flag > env > per-repo > global >
-	// built-in `pre-backlog`); fed into the runner-deterministic placement
+	// built-in `backlog`); fed into the runner-deterministic placement
 	// resolver (`src/placement.ts`) as the configured-default rung.
-	tasksLandIn: {enum: ['pre-backlog', 'ready']},
+	tasksLandIn: {enum: ['backlog', 'ready']},
 	// `specsLandIn` (the per-repo SPEC-PLACEMENT default — spec
 	// `staging-pool-position-gate-and-trust-model` US #2/#5) coerces as the
 	// `pre-proposed`/`ready` enum, so `DORFL_SPECS_LAND_IN=ready` works and a typo
@@ -113,7 +113,7 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// > global > built-in `pre-proposed`); fed into the shared placement resolver
 	// (`src/placement.ts`) as the configured-default rung for the spec lifecycle.
 	// The legacy `prdsLandIn` key / `DORFL_PRDS_LAND_IN` env are GONE after the
-	// prd → spec hard cutover (clean break).
+	// ''prd'' → `spec` hard cutover (clean break).
 	specsLandIn: {enum: ['pre-proposed', 'ready']},
 	// `noPR` (the PR-INTENT axis) is a BOOLEAN coercion (like `review`), so
 	// `DORFL_NO_PR=true|false` works and a typo FAILS LOUDLY. The removed
@@ -139,19 +139,27 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// `freshWorktreeGate` is a BOOLEAN coercion (like `taskerLoop`), so
 	// `DORFL_FRESH_WORKTREE_GATE=true|false` works and a typo FAILS LOUDLY.
 	freshWorktreeGate: 'boolean',
-	// `mergeRetries` (the cross-job merge serialiser's CAS-retry cap — prd
+	// `mergeRetries` (the cross-job merge serialiser's CAS-retry cap — spec
 	// `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a))
 	// coerces as a NUMBER (like `reviewMaxRounds`), so `DORFL_MERGE_RETRIES=20`
 	// works and a typo FAILS LOUDLY. A wide-matrix CI raises it; the default
 	// (1000 — the C2 large liveness ceiling) stays in place when unset.
 	mergeRetries: 'number',
 	// `strictMergeApproval` (the OPT-IN strictness layered on the OQ6
-	// stale-approval default — prd `land-time-reverify-and-parallel-merge-ceiling`
+	// stale-approval default — spec `land-time-reverify-and-parallel-merge-ceiling`
 	// sidecar OQ6 / task `strict-merge-approval-gate`) coerces as a BOOLEAN
 	// (like `freshWorktreeGate`), so `DORFL_STRICT_MERGE_APPROVAL=true|false`
 	// works and a typo FAILS LOUDLY. Default OFF; ON re-surfaces the
 	// merge-question on a merge-base change instead of auto-landing.
 	strictMergeApproval: 'boolean',
+	// The dorfl-INTERNAL agent deadline (minutes) — spec
+	// `graceful-pre-timeout-wip-checkpoint`. NUMBER coercion (like
+	// `reviewMaxRounds`); range validation is fail-loud in `validateDeadlineConfig`
+	// (not clamped here). Env is a per-machine source, so CI can override the
+	// per-repo default without a config edit: `DORFL_AGENT_DEADLINE_MINUTES=90`.
+	agentDeadlineMinutes: 'number',
+	checkpointHeadroomMinutes: 'number',
+	maxAutoCheckpoints: 'number',
 	// `promptGuidance` is a STRUCTURED (nested) namespace, so it has no scalar env
 	// var of its own — each MEMBER carries its own env var (the nested-key form
 	// `DORFL_PROMPT_GUIDANCE_<MEMBER>`), handled out-of-band in
@@ -163,7 +171,7 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 /**
  * The env vars for the nested members of the `promptGuidance` namespace. The
  * key is the env var name (`DORFL_PROMPT_GUIDANCE_<MEMBER>`, the nested
- * naming the prd specifies); the value is the (boolean) coercion. Each member
+ * naming the spec specifies); the value is the (boolean) coercion. Each member
  * present in env contributes `{<member>: bool}` into a single
  * `promptGuidance` partial — mergeConfig replaces the whole namespace per the
  * layered precedence, which is correct because EVERY member is included (env

package/src/failure-cause.ts

@@ -2,7 +2,8 @@
  * **The failure-CAUSE classifier** (task `failure-cause-classification-model-vs-
  * git-vs-agent`).
  *
- * When a claimed item routes to `work/needs-attention/`, the runner records WHY.
+ * When a claimed item is marked stuck on its per-item lock (post lock-cutover —
+ * `state: stuck`, no `work/needs-attention/` folder write), the runner records WHY.
  * Historically several DIFFERENT causes collapsed into one undifferentiated label
  * ("agent failed"), even though the CAUSE drives the RECOVERY:
  *
@@ -49,6 +50,7 @@
  */
 export type FailureCause =
 	| 'transient-infra' // a harness-surfaced model/connection outage (post-retry), or a git/provider outage — RETRY the same work
+	| 'needs-reauth' // a credential expired / was revoked (e.g. OAuth refresh token) — RETRY CANNOT help; a human must RE-AUTH
 	| 'config-error' // a thrown CORE wiring/config error (e.g. review on, no reviewGate) — fix the WIRING
 	| 'agent-failed'; // the conservative generic: the agent ran but produced bad/empty output, OR the cause is UNKNOWN
 
@@ -65,6 +67,24 @@ const CONFIG_ERROR_SIGNATURES = [
 	/no review gate is configured/i,
 ];
 
+/**
+ * Substrings that mark a CREDENTIAL-EXPIRY failure surfaced by the harness: an
+ * OAuth refresh token has expired or been revoked, or a 401 came back tagged
+ * `authentication_required`. Retry cannot help these — only a human RE-AUTH can.
+ * Kept SEPARATE from `TRANSIENT_INFRA_SIGNATURES` (see ADR
+ * `transient-infra-and-needs-reauth-routing`) so downstream routing can branch
+ * cleanly on the cause: retry-with-backoff for infra, straight to a needs-reauth
+ * surface for credentials. Conservative: unrelated 401s that don't mention auth /
+ * token stay `agent-failed`.
+ */
+const NEEDS_REAUTH_SIGNATURES = [
+	/authentication_required/i,
+	/OAuth (?:refresh )?token (?:expired|revoked|invalid)/i,
+	/refresh token (?:expired|revoked|invalid)/i,
+	/\b401\b[^\n]{0,80}(?:auth|token|credential|unauthori[sz]ed)/i,
+	/(?:auth|token|credential)[^\n]{0,40}\b401\b/i,
+];
+
 /**
  * Substrings that mark a TRANSIENT-INFRA failure: a model endpoint / connection
  * outage the harness surfaced AFTER exhausting its own retries, or a git/provider
@@ -117,6 +137,13 @@ export function classifyFailureCause(detail: string | undefined): FailureCause {
 	if (CONFIG_ERROR_SIGNATURES.some((re) => re.test(text))) {
 		return 'config-error';
 	}
+	// Credential-expiry is checked BEFORE `transient-infra` because a 401 body may
+	// also mention words like "unavailable"/network, and no amount of retry helps
+	// — a human must re-auth. Kept as its own cause per ADR
+	// `transient-infra-and-needs-reauth-routing`.
+	if (NEEDS_REAUTH_SIGNATURES.some((re) => re.test(text))) {
+		return 'needs-reauth';
+	}
 	if (TRANSIENT_INFRA_SIGNATURES.some((re) => re.test(text))) {
 		return 'transient-infra';
 	}
@@ -134,6 +161,8 @@ export function failureCauseLabel(cause: FailureCause): string {
 	switch (cause) {
 		case 'transient-infra':
 			return 'transient infra';
+		case 'needs-reauth':
+			return 'needs re-auth (credential expired)';
 		case 'config-error':
 			return 'config error';
 		case 'agent-failed':

package/src/format.ts

@@ -117,40 +117,20 @@ function cwdDivergenceLine(
  * consistency rule): the two reads have different freshness + storage models.
  */
 /**
- * Render ONE held per-item lock entry (action × state + reason/questions) as
- * indented lines, the SHARED renderer for the in-flight lock surface on BOTH the
- * registry view (`formatStatus`) and the cwd section (`formatCwdSection`), so the
- * two substrates present a held/stuck item identically (NOT a forked renderer). An
- * `active` hold reads as `in-progress`; a `stuck` hold as `needs-attention` and
- * carries its (possibly multi-line) reason + any surfaced questions.
+ * Render ONE held per-item lock entry as an indented line, the SHARED renderer
+ * for the in-flight lock surface on BOTH the registry view (`formatStatus`) and
+ * the cwd section (`formatCwdSection`). Post-`retire-stuck-lock-state` the
+ * lock state is degenerate (`active` only) — a held lock is always an
+ * in-progress hold; a parked item is a `needsAnswers:true` pool item on `main`
+ * with a sidecar, rendered by the pool categoriser (NOT here).
  */
 export function formatLockEntryLines(
 	entry: LockEntry,
 	indent: string,
 ): string[] {
-	const lines: string[] = [];
-	const view = entry.state === 'stuck' ? 'needs-attention' : 'in-progress';
-	lines.push(
-		`${indent}${entry.entry}   (${entry.action}/${entry.state} = ${view})`,
-	);
-	if (entry.state === 'stuck') {
-		const reason =
-			entry.reason && entry.reason !== ''
-				? entry.reason
-				: '(no reason recorded)';
-		const reasonLines = reason.split('\n');
-		lines.push(`${indent}  reason: ${reasonLines[0]}`);
-		for (const extra of reasonLines.slice(1)) {
-			lines.push(`${indent}    ${extra}`);
-		}
-		if (entry.questions && entry.questions.length > 0) {
-			lines.push(`${indent}  questions:`);
-			for (const q of entry.questions) {
-				lines.push(`${indent}    - ${q}`);
-			}
-		}
-	}
-	return lines;
+	return [
+		`${indent}${entry.entry}   (${entry.action}/${entry.state} = in-progress)`,
+	];
 }
 
 export function formatCwdSection(section: CwdSection): string[] {
@@ -202,7 +182,7 @@ export function formatCwdSection(section: CwdSection): string[] {
 		}
 	}
 
-	// The PER-ITEM LOCK in-flight SURFACE for the cwd (prd
+	// The PER-ITEM LOCK in-flight SURFACE for the cwd (spec
 	// `ledger-status-per-item-lock-refs` US #8): held (`active` = in-progress) and
 	// `stuck` (= needs-attention) lock entries + their reasons. This is what keeps a
 	// held/stuck cwd item from vanishing: the held-slug subtraction removes it from
@@ -214,7 +194,7 @@ export function formatCwdSection(section: CwdSection): string[] {
 	const lockHeld = section.repo.lockHeld ?? [];
 	if (lockHeld.length > 0) {
 		lines.push('');
-		lines.push('    In progress / stuck (lock held — refs/dorfl/lock/*):');
+		lines.push('    In progress (lock held — refs/dorfl/lock/*):');
 		for (const entry of lockHeld) {
 			lines.push(...formatLockEntryLines(entry, '      '));
 		}
@@ -263,7 +243,7 @@ export function formatReport(report: ScanReport, cwd?: CwdSection): string {
 			lines.push('No participating repos found.');
 			lines.push(
 				'(A repo participates iff its work/ tree has lifecycle content in any ' +
-					'pool: tasks/ready, tasks/backlog, prds/proposed, prds/ready, ' +
+					'pool: tasks/ready, tasks/backlog, specs/proposed, specs/ready, ' +
 					'notes/observations, or questions.)',
 			);
 		} else {
@@ -281,7 +261,7 @@ export function formatReport(report: ScanReport, cwd?: CwdSection): string {
 		const groups = categoriseItems(repo.items);
 		allGroups.push(groups);
 		lines.push(...formatRepo(repo.path, groups));
-		// The one-slug-one-folder LINT (prd `ledger-integrity` story 3): WARN LOUDLY
+		// The one-slug-one-folder LINT (spec `ledger-integrity` story 3): WARN LOUDLY
 		// when any slug in this repo's ledger resides in >1 status folder (a corrupt
 		// ledger — never a silent pass). Clean ledgers add no lines.
 		const warnings = formatDuplicateWarnings(repo.ledgerDuplicates ?? []);

package/src/frontmatter.ts

@@ -7,8 +7,8 @@
 
 /**
  * **Origin-trust PROVENANCE** (task `untrusted-origin-forces-build-propose`).
- * How a prd/task was BORN and the AUTHOR-TRUST verdict at birth, stamped so the
- * signal SURVIVES the prd/task merge boundary (a landed-on-`main` artifact would
+ * How a spec/task was BORN and the AUTHOR-TRUST verdict at birth, stamped so the
+ * signal SURVIVES the spec/task merge boundary (a landed-on-`main` artifact would
  * otherwise erase how it was created — the laundering gap).
  *
  * - `origin` — `human` (the default / unset: a human authored it locally; a local
@@ -47,11 +47,12 @@ export interface Frontmatter {
 	 * Source SPEC slug: the parent-spec pointer this artifact derives from; the
 	 * spec lives at `work/specs/ready/<spec>.md`. The `spec` vocabulary name (spec
 	 * `prd-to-spec-vocabulary-cutover-and-migration-command`). `parseFrontmatter`
-	 * populates it from EITHER the canonical `spec:` key OR the LEGACY `prd:` key
-	 * (the latter kept as a read-only BACK-COMPAT alias for un-migrated downstream
-	 * repos, whose data still carries `prd:` until `dorfl prd-to-spec` converts it).
-	 * `spec:` wins when both are present. There is no longer a separate `fm.prd`
-	 * FIELD — both keys feed this one field.
+	 * populates it from the canonical `spec:` key ONLY — the HARD CUTOVER (the last
+	 * ''prd'' back-compat surface removed): the legacy ''prd:'' KEY read is GONE, so
+	 * an un-migrated ''prd:'' field no longer silently resolves. A downstream repo
+	 * migrates its data with `dorfl prd-to-spec` (a purely TEXTUAL `prd: → spec:`
+	 * rewrite that does NOT go through this parser), after which the field reads
+	 * canonically. There is no `fm.prd` FIELD.
 	 */
 	spec: string | undefined;
 	/**
@@ -105,19 +106,19 @@ export interface Frontmatter {
 	/** Slugs this item is blocked by; `[]` when omitted or empty. */
 	blockedBy: string[];
 	/**
-	 * Prd-only: slugs of prds that must already be TASKED before this prd may be
-	 * tasked (resolved against `work/prds/tasked/` residence, NOT `done/`). `[]` when
+	 * Spec-only: slugs of prds that must already be TASKED before this spec may be
+	 * tasked (resolved against `work/specs/tasked/` residence, NOT `done/`). `[]` when
 	 * omitted or empty. Parsed here so the auto-tasker can read it; enforcement
 	 * lives in the `auto-slice` capability, not in eligibility.
 	 */
 	taskedAfter: string[];
 	/**
 	 * The per-item override layer for the `promptGuidance` NUDGE namespace
-	 * (task `prompt-guidance-testfirst-item-override`, prd US #5). A task or
-	 * prd may carry one or more `promptGuidance.<member>: true | false`
+	 * (task `prompt-guidance-testfirst-item-override`, spec US #5). A task or
+	 * spec may carry one or more `promptGuidance.<member>: true | false`
 	 * frontmatter lines to OVERRIDE the resolved repo policy for THAT ITEM only.
 	 * Each member is `undefined` when omitted (⇒ inherit the next layer down in
-	 * the precedence chain: per-task > per-prd > repo-resolved). The override
+	 * the precedence chain: per-task > per-spec > repo-resolved). The override
 	 * is honoured at the prompt-assembly seam (`prompt.ts`); it never affects
 	 * the `verify` gate.
 	 *
@@ -291,14 +292,44 @@ export function setFrontmatterMarker(
 	return lines.join('\n');
 }
 
+/**
+ * Read ONE arbitrary top-level scalar frontmatter key by name, returning its
+ * unquoted value (or `undefined` when the doc has no fence, or the key is absent).
+ *
+ * A general-purpose companion to {@link parseFrontmatter} for keys that are NOT in
+ * the modelled {@link Frontmatter} shape — e.g. the observation→task provenance
+ * back-reference `promotedFrom:` the triage-promote path stamps and the create-CAS
+ * lost-race disambiguation reads (task
+ * `observation-triage-already-triaged-benign-skip`). Only top-level `key: value`
+ * lines are matched (block-list / nested values are out of scope for a scalar read).
+ */
+export function readFrontmatterField(
+	content: string,
+	key: string,
+): string | undefined {
+	const block = extractBlock(content);
+	if (block === undefined) {
+		return undefined;
+	}
+	const pattern = new RegExp(`^${key}\\s*:\\s*(.*)$`);
+	for (const line of block.split('\n')) {
+		const match = pattern.exec(line);
+		if (match) {
+			const value = unquote(match[1]);
+			return value === '' ? undefined : value;
+		}
+	}
+	return undefined;
+}
+
 /**
  * PROPAGATE the origin-trust PROVENANCE (`origin` + `originTrust`) from a SOURCE
- * artifact (a prd) onto a TARGET artifact's content (an emitted task), returning
+ * artifact (a spec) onto a TARGET artifact's content (an emitted task), returning
  * the new content (task `untrusted-origin-forces-build-propose`). The tasker
- * calls this so a task born from an untrusted-origin prd carries the stamp the
+ * calls this so a task born from an untrusted-origin spec carries the stamp the
  * BUILD transition reads. IDEMPOTENT: each present source field is written via
  * {@link setFrontmatterMarker} (replace-or-append). When the source has NO `origin`
- * (a human/local-authored prd ⇒ trusted), the target is returned UNCHANGED — the
+ * (a human/local-authored spec ⇒ trusted), the target is returned UNCHANGED — the
  * normal path is never stamped (zero behaviour change). When a stamp IS applied to
  * a fence-less target, {@link setFrontmatterMarker} now prepends a fence to carry
  * it (tasks the tasker emits always have a fence, so this is the defensive path).
@@ -370,27 +401,16 @@ export function parseFrontmatter(content: string): Frontmatter {
 			result.originTrust = v === 'trusted' || v === 'untrusted' ? v : undefined;
 		} else if (key === 'slug') {
 			result.slug = rawValue === '' ? undefined : unquote(rawValue);
-		} else if (key === 'spec' || key === 'prd') {
-			// The parent-spec pointer, read from EITHER the canonical `spec:` key OR the
-			// LEGACY `prd:` key into the SINGLE `fm.spec` field (spec
-			// `prd-to-spec-vocabulary-cutover-and-migration-command`). The `prd:` key
-			// read is a permanent-for-now BACK-COMPAT alias so an un-migrated downstream
-			// repo (whose data still carries `prd:` until `dorfl prd-to-spec` converts
-			// it) keeps resolving its parent spec. `spec:` WINS when both are present
-			// (the canonical key over the legacy alias); an empty value on one key does
-			// NOT clobber a non-empty value already read from the other.
-			const value = rawValue === '' ? undefined : unquote(rawValue);
-			if (key === 'spec') {
-				// The canonical key wins: overwrite whatever `prd:` may have set.
-				if (value !== undefined) {
-					result.spec = value;
-				}
-			} else if (result.spec === undefined) {
-				// Legacy `prd:` only fills in when `spec:` has not already set it.
-				result.spec = value;
-			}
+		} else if (key === 'spec') {
+			// The parent-spec pointer, read from the canonical `spec:` key ONLY into the
+			// `fm.spec` field (spec `prd-to-spec-vocabulary-cutover-and-migration-command`,
+			// HARD CUTOVER). The legacy ''prd:'' KEY read is GONE — an un-migrated ''prd:''
+			// field no longer resolves here; a repo converts its data via the TEXTUAL
+			// `dorfl prd-to-spec` rewrite (which does not use this parser). An empty value
+			// leaves the field undefined.
+			result.spec = rawValue === '' ? undefined : unquote(rawValue);
 		} else if (key === 'issue') {
-			// Integer issue link (`intake`'s prd-emit OR a lone-task emit). A
+			// Integer issue link (`intake`'s spec-emit OR a lone-task emit). A
 			// non-integer / empty value reads as undefined (the field is absent rather
 			// than malformed).
 			const n = Number(unquote(rawValue));

package/src/gc.ts

@@ -8,7 +8,9 @@ import {
 	removeJobRecord,
 	type JobRecord,
 } from './workspace.js';
-import {workBranchRef} from './slug-namespace.js';
+import {parseWorkBranchRef, workBranchRef} from './slug-namespace.js';
+import {terminalMainPaths} from './item-lock.js';
+import type {SidecarType} from './sidecar.js';
 
 /**
  * The **reaper** for job worktrees, governed by the **provably-safe deletion
@@ -140,8 +142,23 @@ export function evaluateDeletionSafety(
 
 	const localTip = revParse(input.dir, 'HEAD', env);
 
-	// 2a. Merged: the tip is an ancestor of <arbiter>/main.
-	if (isAncestor(input.dir, localTip, `refs/remotes/${arbiter}/main`, env)) {
+	// 2a. Merged: the tip is provably on <arbiter>/main — either a plain
+	//     ancestor (fast path) OR squash-aware-equivalent (the durable done/
+	//     dropped record is on main AND the branch carries nothing main lacks).
+	const arbiterMainRef = `refs/remotes/${arbiter}/main`;
+	const reapIdentity = reapIdentityFromBranch(input.branch);
+	if (
+		reapIdentity !== undefined
+			? isProvablyMergedForReap({
+					cwd: input.dir,
+					tip: localTip,
+					arbiterMain: arbiterMainRef,
+					namespace: reapIdentity.namespace,
+					slug: reapIdentity.slug,
+					env,
+				})
+			: isAncestor(input.dir, localTip, arbiterMainRef, env)
+	) {
 		return {safe: true, reachableVia: 'merged'};
 	}
 
@@ -432,14 +449,160 @@ function fetchTracking(
 	);
 }
 
+/**
+ * Extract the `{namespace, slug}` identity a reap decision needs from a work
+ * branch ref (`work/[<producer>-]<type>-<slug>`). Returns `undefined` for a
+ * non-namespaced branch — the caller then falls back to the ancestry-only
+ * fast-path (the squash-aware fallback has no anchor without an identity to
+ * look up on `<arbiter>/main`, so the safe direction is the strict old rule).
+ */
+function reapIdentityFromBranch(
+	branch: string,
+): {namespace: SidecarType; slug: string} | undefined {
+	const parsed = parseWorkBranchRef(branch);
+	if (parsed === undefined) {
+		return undefined;
+	}
+	// `SlugNamespace` and `SidecarType` share the same three members
+	// (`'task' | 'spec' | 'observation'`); the cast is structural.
+	return {namespace: parsed.namespace as SidecarType, slug: parsed.slug};
+}
+
+/** Input for {@link isProvablyMergedForReap}. */
+export interface ProvablyMergedForReapInput {
+	/** The local repo the git predicates run in. */
+	cwd: string;
+	/** The candidate branch tip (a 40-hex sha or a resolvable ref). */
+	tip: string;
+	/**
+	 * The arbiter's main as a ref RESOLVABLE INSIDE `cwd` — a fetched
+	 * remote-tracking ref (`refs/remotes/<arbiter>/main`) or short-form
+	 * (`<arbiter>/main`). Callers are responsible for the fetch (best-effort;
+	 * an unresolvable ref reads as not-provable ⇒ false).
+	 */
+	arbiterMain: string;
+	/**
+	 * The item's type (task/spec/observation) — used to look up the durable
+	 * terminal records on `<arbiter>/main`. Reap decisions on a
+	 * `work/<type>-<slug>` branch pass the parsed type from
+	 * {@link parseWorkBranchRef}.
+	 */
+	namespace: SidecarType;
+	/** The item's bare slug — the anchor for the squash-aware fallback. */
+	slug: string;
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * The **squash-aware, provably-merged predicate** used to decide reap-safety
+ * across the workspace: `gc.ts`'s worktree reaper, `reap-branches.ts`'s remote
+ * `work/*` sweep, `integrator.ts`'s post-merge remote-head reap, and
+ * `complete.ts`'s local-branch reap. ONE decision point so the two rules can
+ * never drift apart, and NEVER `--force` — a merged-for-reap ref needs none.
+ *
+ * A remote/local `work/<slug>` branch is reapable iff EITHER:
+ *
+ *   1. **Fast path (unchanged).** `git merge-base --is-ancestor <tip>
+ *      <arbiter>/main` succeeds — the fast-forward / true-merge land case.
+ *   2. **Squash-aware fallback (new).** BOTH of the following hold:
+ *      - the item is TERMINAL on `<arbiter>/main` — i.e. the matching
+ *        {@link terminalMainPaths} (`work/tasks/done/<slug>.md` or
+ *        `work/tasks/cancelled/<slug>.md` for a task; `work/specs/tasked/…`
+ *        or `work/specs/dropped/…` for a spec) exists in the fetched main
+ *        tree; AND
+ *      - the branch carries NOTHING main lacks — either `git diff --quiet
+ *        <arbiter>/main <tip>` reads clean (content-equal / content-subset)
+ *        OR `git cherry <arbiter>/main <tip>` reports every commit as
+ *        already applied by patch-id (`-` on every line, catching
+ *        rebase-lands the tree check misses).
+ *
+ * Grounding: the durable `<arbiter>/main` record is authoritative. It is what
+ * `complete` writes FIRST, so if the terminal record is there the item's work
+ * is at rest, and a branch that carries nothing main lacks has no in-flight
+ * work to protect. The safety floor is unchanged: NEVER reap an in-flight /
+ * unmerged branch (no terminal record ⇒ retain), NEVER reap a branch carrying
+ * commits main lacks (content check fails ⇒ retain), NEVER `--force`.
+ *
+ * This is the branch-side twin of the lock-side terminal-on-main recovery
+ * (`isTerminalOnMain` in `item-lock.ts`): same anchor, different subject.
+ */
+export function isProvablyMergedForReap(
+	input: ProvablyMergedForReapInput,
+): boolean {
+	const {cwd, tip, arbiterMain, namespace, slug, env} = input;
+
+	// 1. Fast path — the fast-forward / true-merge land case. Cheap: one
+	//    `git merge-base --is-ancestor`.
+	if (isAncestor(cwd, tip, arbiterMain, env)) {
+		return true;
+	}
+
+	// 2. Squash-aware fallback. Anchor: the durable terminal record on
+	//    `<arbiter>/main`. No terminal record ⇒ the item is still in-flight (or
+	//    an observation, which has no terminal folder) ⇒ retain (never reap
+	//    in-flight work).
+	if (!terminalRecordOnMain(cwd, arbiterMain, namespace, slug, env)) {
+		return false;
+	}
+
+	// 2a. Content-subset: `git diff --quiet <arbiterMain> <tip>` clean ⇒ the
+	//     two trees are identical, so the branch carries nothing main lacks
+	//     (the incident shape: the branch is a since-lagged snapshot of a
+	//     squash-landed item, no new content on it).
+	const diff = run('git', ['diff', '--quiet', arbiterMain, tip], cwd, {env});
+	if (diff.status === 0) {
+		return true;
+	}
+
+	// 2b. Patch-id equivalence via `git cherry <upstream> <head>`: every commit
+	//     reachable from `<tip>` but not `<arbiterMain>` is reported as `-`
+	//     (already applied upstream by patch-id). This catches rebase-lands
+	//     where the tree diff is non-empty but every commit is already on main
+	//     under a different sha.
+	const cherry = run('git', ['cherry', arbiterMain, tip], cwd, {env});
+	if (cherry.status === 0) {
+		const lines = cherry.stdout
+			.split('\n')
+			.map((l) => l.trim())
+			.filter((l) => l !== '');
+		if (lines.length > 0 && lines.every((l) => l.startsWith('- '))) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/** True iff `<arbiterMain>` carries ANY of the item's durable terminal records
+ * ({@link terminalMainPaths}). Best-effort: `cat-file -e` is a cheap tree
+ * probe; an unresolvable `<arbiterMain>` reads as no-record ⇒ retain (the safe
+ * direction). Observations have no terminal folder ⇒ always false. */
+function terminalRecordOnMain(
+	cwd: string,
+	arbiterMain: string,
+	namespace: SidecarType,
+	slug: string,
+	env: NodeJS.ProcessEnv | undefined,
+): boolean {
+	for (const path of terminalMainPaths(namespace, slug)) {
+		const res = run('git', ['cat-file', '-e', `${arbiterMain}:${path}`], cwd, {
+			env,
+		});
+		if (res.status === 0) {
+			return true;
+		}
+	}
+	return false;
+}
+
 /**
  * True iff `ancestor` is an ancestor of (or equal to) `descendant`, both
- * resolved IN the local repo `dir` (`git merge-base --is-ancestor`). This is the
- * ONE provably-merged reachability predicate in the system: the worktree reaper
- * above uses it for `<tip> --is-ancestor <arbiter>/main`, and the remote
- * merged-branch sweep (`reap-branches.ts`) REUSES it (not a second predicate) to
- * decide a remote `work/<slug>` branch is provably merged before deleting it.
- * EXPORTED so that single source of truth is shared, never forked.
+ * resolved IN the local repo `dir` (`git merge-base --is-ancestor`). The
+ * low-level fast-path building block for {@link isProvablyMergedForReap} —
+ * reap-safety decisions across the workspace go through the squash-aware
+ * wrapper, never this raw predicate. EXPORTED so callers that legitimately
+ * need pure ancestry (non-reap idempotency checks, claim-reachability guards)
+ * keep the one shared implementation.
  */
 export function isAncestor(
 	dir: string,