dorfl 0.1.1 → 0.2.0

package/src/orphan-sidecar.ts

@@ -3,17 +3,53 @@ import {join} from 'node:path';
 import {run} from './git.js';
 import {resolveSidecarIdentity} from './sidecar.js';
 import {resolveItemPathByIdentity} from './item-path.js';
+import {terminalMainPaths} from './item-lock.js';
 import {workFolderPath, workFolderRel} from './work-layout.js';
 
+/**
+ * Resolve the source item's CURRENT on-disk path INCLUDING its TERMINAL resting
+ * records — the orphan-sweep existence predicate.
+ *
+ * This deliberately WIDENS {@link resolveItemPathByIdentity} (which scans the
+ * ACTIVE lifecycle folders + staging, and EXCLUDES terminals on purpose: for the
+ * apply rung a terminal-reached item is `vanished`). The orphan sweep asks a
+ * DIFFERENT question — "does a source item for this sidecar exist AT ALL?" — and a
+ * task/spec that reached its terminal (`tasks/cancelled/`, `specs/dropped/`) is a
+ * durable RESTING record that still EXISTS, so its sidecar is NOT an orphan.
+ * Treating "reached a terminal" as "gone" would let a routine `gc` delete a live
+ * sidecar (and any human answer it carries) — the 2026-07-12 false-positive.
+ *
+ * Reuses the shared {@link terminalMainPaths} (`item-lock.ts`, the SAME per-type
+ * terminal set the lock/branch reapers key off) so the "where do terminals live?"
+ * knowledge stays single-sourced. Returns the ACTIVE path when present, else the
+ * first existing TERMINAL path, else `undefined` (a genuine orphan).
+ */
+function resolveSourceForOrphanSweep(
+	cwd: string,
+	item: string,
+): string | undefined {
+	const active = resolveItemPathByIdentity(cwd, item);
+	if (active !== undefined) {
+		return active;
+	}
+	const {type, slug} = resolveSidecarIdentity(item);
+	for (const rel of terminalMainPaths(type, slug)) {
+		if (existsSync(join(cwd, rel))) {
+			return rel;
+		}
+	}
+	return undefined;
+}
+
 /**
  * The **orphan-sidecar reaper** — the WORKING-TREE counterpart of the job-worktree
  * and remote-branch reapers (`gc.ts` / `reap-branches.ts`), folded into `dorfl gc`
- * (prd `agentic-question-resolution-retire-disposition-vocabulary`, US #10).
+ * (spec `agentic-question-resolution-retire-disposition-vocabulary`, US #10).
  *
  * A question sidecar is a tooling-owned file `work/questions/<type>-<slug>.md`
  * keyed on its source item's `(type, slug)` identity (`sidecarPathFor`). The
  * contract is that notes/sidecars leave by DELETION (git history is the archive),
- * so when a human deletes the source observation (or task/prd) out-of-band, its
+ * so when a human deletes the source observation (or task/spec) out-of-band, its
  * sidecar is ORPHANED.
  *
  * WHY THIS IS A SWEEP, NOT AN APPLY STEP. An orphan's source item is GONE, so it
@@ -26,10 +62,14 @@ import {workFolderPath, workFolderRel} from './work-layout.js';
  *
  * The existence check REUSES the keystone's extracted `resolveItemPathByIdentity`
  * (`item-path.ts`, the neutral re-exported seam) — the same working-tree,
- * by-identity "does the source item exist?" resolver the apply rung uses — never a
- * forked second resolver. A sidecar whose source EXISTS is left untouched; a
- * sidecar whose source is ABSENT is `git rm`'d (deletion, not a `git mv`: the
- * sidecar leaves by deletion, recoverable from git history).
+ * by-identity "does the source item exist?" resolver the apply rung uses — WIDENED
+ * to also count a source that has reached a TERMINAL folder (`tasks/cancelled/`,
+ * `specs/dropped/`, via the shared `terminalMainPaths`) as EXISTING: a terminal is
+ * a durable resting record, not "gone", so its sidecar is NOT an orphan (see
+ * `resolveSourceForOrphanSweep`). A sidecar whose source EXISTS anywhere is left
+ * untouched; a sidecar whose source is ABSENT from every active AND terminal
+ * folder is `git rm`'d (deletion, not a `git mv`: the sidecar leaves by deletion,
+ * recoverable from git history).
  */
 
 /** A sidecar the orphan sweep reaped (its source item was absent). */
@@ -111,9 +151,10 @@ export function sweepOrphanSidecars(
 		const {item} = resolveSidecarIdentity(stem.replace('-', ':'));
 		const path = `${workFolderRel('questions')}/${entry}`;
 
-		const sourcePath = resolveItemPathByIdentity(input.cwd, item);
+		const sourcePath = resolveSourceForOrphanSweep(input.cwd, item);
 		if (sourcePath !== undefined) {
-			// The source item still exists ⇒ a LIVE sidecar ⇒ leave it untouched.
+			// The source item still exists (active lifecycle OR a terminal resting
+			// record) ⇒ a LIVE sidecar ⇒ leave it untouched.
 			retained.push({path, item, sourcePath});
 			note(`Retained ${path}: source ${item} still exists (${sourcePath}).`);
 			continue;

package/src/pi-harness.ts

@@ -65,6 +65,15 @@ import type {HarnessAdapter} from './config.js';
 /** The default pi CLI binary name (resolved on `PATH`). */
 export const DEFAULT_PI_BIN = 'pi';
 
+/**
+ * The grace period between a deadline SIGTERM and the follow-up SIGKILL in
+ * {@link PiHarness.launchAsync} (spec `graceful-pre-timeout-wip-checkpoint`).
+ * Ten seconds gives pi enough time to flush its session `.jsonl` and exit
+ * cleanly; a wedged/frozen child that ignores SIGTERM still gets reaped in a
+ * bounded time so the promise settles and the caller's checkpoint routing runs.
+ */
+export const DEADLINE_SIGKILL_GRACE_MS = 10_000;
+
 export interface PiHarnessOptions {
 	/**
 	 * The pi CLI binary (default `pi` on `PATH`). Tests inject a stub script here
@@ -239,11 +248,60 @@ export class PiHarness implements Harness {
 			child.stdout?.on('data', () => {});
 			// Guard so `exit` and a late `error` never double-settle the promise.
 			let settled = false;
+			let timedOut = false;
+			// DEADLINE RACE (spec `graceful-pre-timeout-wip-checkpoint`): when the
+			// caller threads a `deadlineMs` (absolute wall-clock epoch-ms), arm a
+			// SOFT SIGTERM at that time, then a HARD SIGKILL after a ~10s grace. The
+			// child's own `exit` handler below still resolves the promise (with
+			// `timedOut: true`), so we preserve the settle-once + FD-release
+			// discipline and never double-settle. A run that finishes BEFORE the
+			// deadline clears both timers (see the `exit` handler) — byte-for-byte
+			// unchanged from the pre-task behaviour.
+			let softTimer: NodeJS.Timeout | undefined;
+			let hardTimer: NodeJS.Timeout | undefined;
+			const clearDeadlineTimers = (): void => {
+				if (softTimer !== undefined) {
+					clearTimeout(softTimer);
+					softTimer = undefined;
+				}
+				if (hardTimer !== undefined) {
+					clearTimeout(hardTimer);
+					hardTimer = undefined;
+				}
+			};
+			if (input.deadlineMs !== undefined) {
+				const softMs = Math.max(0, input.deadlineMs - Date.now());
+				softTimer = setTimeout(() => {
+					if (settled) {
+						return;
+					}
+					timedOut = true;
+					try {
+						child.kill('SIGTERM');
+					} catch {
+						// Best-effort: a already-exited child throws ESRCH; the `exit`
+						// handler will still settle the promise.
+					}
+					hardTimer = setTimeout(() => {
+						if (settled) {
+							return;
+						}
+						try {
+							child.kill('SIGKILL');
+						} catch {
+							// Best-effort: see above.
+						}
+					}, DEADLINE_SIGKILL_GRACE_MS);
+					hardTimer.unref?.();
+				}, softMs);
+				softTimer.unref?.();
+			}
 			child.on('error', (err) => {
 				if (settled) {
 					return;
 				}
 				settled = true;
+				clearDeadlineTimers();
 				reject(new Error(`failed to spawn pi (${this.piBin}): ${err.message}`));
 			});
 			// Resolve on `exit` (pi itself terminated), NOT `close`: `close` waits for
@@ -255,6 +313,7 @@ export class PiHarness implements Harness {
 					return;
 				}
 				settled = true;
+				clearDeadlineTimers();
 				// Release our end of the stdio pipes so a leaked grandchild's inherited
 				// FDs stop keeping our streams referenced; `unref` the child handle too.
 				child.stdout?.destroy();
@@ -263,9 +322,11 @@ export class PiHarness implements Harness {
 				child.unref?.();
 				const status = code ?? -1;
 				resolve({
-					ok: status === 0,
+					ok: status === 0 && !timedOut,
 					record,
-					detail: status === 0 ? undefined : stderr.trim(),
+					detail:
+						status === 0 && !timedOut ? undefined : stderr.trim() || undefined,
+					timedOut: timedOut ? true : undefined,
 					// Read the agent's ANSWER from the `.jsonl` at `exit` — the same
 					// last-assistant-text read `launch` does at return (task
 					// `harness-agent-output`); the process has exited so the log is final.
@@ -354,6 +415,14 @@ export class PiHarness implements Harness {
  * pointer with an `existsSync` check. This is the pi-native "is there an audit
  * trail to look at?" signal — distinct from PID liveness, and STILL not mtime
  * (we check existence, never modification time).
+ *
+ * Studied (task `pi-harness-polish`, finding
+ * `work/notes/findings/pi-harness-channels.md`): the recorded `--session <path>`
+ * file remains the right audit pointer even against pi's other output surfaces
+ * (`--mode json` stdout stream, `--mode rpc`, in-process SDK) — those are
+ * transient stdio channels that do not survive the process, whereas the session
+ * file is the versioned, dashboard-visible activity trail pi itself treats as
+ * the audit artefact. PID stays the liveness anchor alongside it.
  */
 export function piSessionExists(record: HarnessRecord): boolean {
 	return record.session !== undefined && existsSync(record.session);
@@ -368,6 +437,17 @@ export function piSessionExists(record: HarnessRecord): boolean {
  * It REUSES `watch-session.ts`'s {@link lastAssistantText} (one `.jsonl` parser,
  * not two). An absent file (pi never wrote it) yields `undefined`, as does a log
  * with no assistant text — a read error is never thrown back into the launch.
+ *
+ * Studied (task `pi-harness-polish`, finding
+ * `work/notes/findings/pi-harness-channels.md`, pinned against pi 0.73.1 +
+ * session format v3): the session `.jsonl` is the right channel for output
+ * because it is the only one that is BOTH post-mortem readable AND explicitly
+ * versioned + migrated (`docs/session-format.md`). The `--mode json` STDOUT
+ * event stream is not versioned and is transient; `--mode rpc` and the
+ * in-process SDK cost more without solving anything the file does not. The
+ * cross-harness `LaunchResult.output` seam (Option C) is a bare `string | undefined`,
+ * so a future stream/HTTP-shaped harness (opencode-style) still fits: the file
+ * shape lives BEHIND this reader and is not observable through the seam.
  */
 function readLastAssistantText(sessionFile: string): string | undefined {
 	let jsonl: string;

package/src/placement.ts

@@ -1,5 +1,5 @@
 /**
- * **The shared STAGING/POOL placement resolver** (prd
+ * **The shared STAGING/POOL placement resolver** (spec
  * `staging-pool-position-gate-and-trust-model`, task
  * `runner-deterministic-slice-placement-policy-and-precedence`, governing ADR
  * `placement-is-runner-deterministic-humanonly-is-agent-judgement`).
@@ -19,7 +19,7 @@
  *
  * LIFECYCLE-GENERIC. The folder names + the configured-default value are
  * PARAMETERS (`slots`, `configuredDefault`), so the same resolver serves the
- * TASK lifecycle (`tasksLandIn`: `pre-backlog`/`ready` — the POOL value was
+ * TASK lifecycle (`tasksLandIn`: `backlog`/`ready` — the POOL value was
  * renamed `'backlog'` → `'todo'` → `'ready'`, ADR
  * `rename-task-pool-folder-todo-to-ready`) AND the SPEC-
  * placement lifecycle (`specsLandIn`: `pre-proposed`/`ready`) without forking. A future
@@ -31,19 +31,19 @@
  * Which side of the staging/pool split the runner chose. The CALLER maps this
  * onto the lifecycle's concrete folder name via {@link PlacementSlots}.
  *
- * - `'staging'` — land in the staging area (tasks: `pre-backlog/`; prds:
- *   `prds/proposed/`). Not in the agent pool; a human/runner promotion is needed to make
+ * - `'staging'` — land in the staging area (tasks: `tasks/backlog/`; prds:
+ *   `specs/proposed/`). Not in the agent pool; a human/runner promotion is needed to make
  *   the item eligible. Review-without-PR review surface.
  * - `'pool'` — land directly in the agent-eligible pool (tasks: `tasks/ready/`;
- *   prds: `prds/ready/`). The trusted-fast-path landing.
+ *   prds: `specs/ready/`). The trusted-fast-path landing.
  */
 export type PlacementSide = 'staging' | 'pool';
 
 /**
  * The two folder names a lifecycle uses for its staging/pool split. Supplied by
  * the caller so this resolver stays lifecycle-generic (the TASK caller passes
- * `{staging: 'pre-backlog', pool: 'tasks/ready'}`; the PRD-placement caller passes
- * `{staging: 'prds/proposed', pool: 'prds/ready'}`).
+ * `{staging: 'tasks/backlog', pool: 'tasks/ready'}`; the SPEC-placement caller passes
+ * `{staging: 'specs/proposed', pool: 'specs/ready'}`).
  */
 export interface PlacementSlots {
 	staging: string;
@@ -100,7 +100,7 @@ const BUILT_IN_FLOOR: PlacementSide = 'staging';
  *   explicit  >  untrusted-origin ⇒ staging  >  configured default  >  built-in
  *
  * Pure: no I/O, no env reads — the caller resolves config + reads the
- * frontmatter and passes both in. Reused by every lifecycle (task + prd
+ * frontmatter and passes both in. Reused by every lifecycle (task + spec
  * placement + future intake variants) so a precedence change touches ONE place.
  */
 export function resolvePlacement(

package/src/prd-to-spec.ts

@@ -8,10 +8,11 @@ import {
 	mkdirSync,
 	rmdirSync,
 } from 'node:fs';
-import {join, relative, dirname} from 'node:path';
+import {join, relative, dirname, basename} from 'node:path';
 import {run, git, gitMv} from './git.js';
 import {resolveProtocolDoc} from './prompt.js';
 import {WORK_ROOT} from './work-layout.js';
+import {repoConfigPath} from './repo-config.js';
 
 /**
  * The **`dorfl prd-to-spec` migration ENGINE** (spec
@@ -675,7 +676,9 @@ export function migrateConfig(
 	migration: VocabularyMigration = MIGRATION,
 	options: {dryRun?: boolean} = {},
 ): ConfigRewrite[] {
-	const configAbs = join(repoPath, '.dorfl.json');
+	// Resolve the repo's actual config file (prefers `dorfl.json`, falls back to
+	// the legacy `.dorfl.json`), so the key rewrite finds it under either name.
+	const configAbs = repoConfigPath(repoPath);
 	if (!existsSync(configAbs)) {
 		return [];
 	}
@@ -922,10 +925,15 @@ export function scanForLeaks(
 			scanText(rel, readFileSync(join(repoPath, rel), 'utf8'), []);
 		}
 	}
-	// The config file (the key layer).
-	const configAbs = join(repoPath, '.dorfl.json');
+	// The config file (the key layer) — under either the preferred `dorfl.json`
+	// or the legacy `.dorfl.json`.
+	const configAbs = repoConfigPath(repoPath);
 	if (existsSync(configAbs)) {
-		scanText('.dorfl.json', readFileSync(configAbs, 'utf8'), configKeyPatterns);
+		scanText(
+			basename(configAbs),
+			readFileSync(configAbs, 'utf8'),
+			configKeyPatterns,
+		);
 	}
 	// The FOLDER TREE itself: a surviving `work/prds/` directory (empty ⇒ no
 	// file, but the folder still leaks). Report it structurally.

package/src/prompt.ts

@@ -1,6 +1,6 @@
 /**
  * Builds the prompt the runner hands to `agentCmd`: a small CONSTANT wrapper
- * (only the `<slug>` / source-prd path vary) around the claimed task's own
+ * (only the `<slug>` / source-spec path vary) around the claimed task's own
  * `## Prompt` section. This is dual-use — the SAME assembly the autonomous
  * runner feeds `agentCmd` and the human `dorfl prompt [<slug>]` command.
  *
@@ -416,7 +416,7 @@ export function buildContinueBlock(slug: string, ctx: ContinueContext): string {
 }
 
 /**
- * Build the full prompt: the canonical wrapper for `slug` (with its source prd
+ * Build the full prompt: the canonical wrapper for `slug` (with its source spec
  * substituted) followed by the task's own `## Prompt` body, appended verbatim.
  *
  * In CONTINUE-mode (a {@link ContinueContext} is supplied), a CONTINUE block is
@@ -459,10 +459,7 @@ export interface ResolvedTask {
 	path: string;
 	/** The folder the task was resolved from (in-progress wins over tasks-ready). */
 	folder: TaskFolder;
-	/**
-	 * The task's source SPEC slug (frontmatter `spec:`, or the legacy `prd:` key
-	 * as read-only back-compat), if any.
-	 */
+	/** The task's source SPEC slug (frontmatter `spec:`), if any. */
 	spec: string | undefined;
 	/** The extracted `## Prompt` body. */
 	taskPrompt: string;
@@ -493,7 +490,7 @@ export class PromptError extends Error {}
 /**
  * The CONTINUE-only gate that lets {@link resolveTask} reach a task that has
  * already been done-moved into `work/done/` — story 5 of the `ledger-integrity`
- * prd (defect 3). A continue/re-claim can legitimately land on a branch whose
+ * spec (defect 3). A continue/re-claim can legitimately land on a branch whose
  * task was ALREADY moved to `done/` (the green-but-unpushed STRAND state), and
  * onboard must find it; but a `done/` task is folder-indistinguishable between
  * two states and re-onboarding a genuinely-finished one would RE-RUN it. So
@@ -533,7 +530,7 @@ export interface ContinueResolutionGate {
 
 /**
  * Extra knobs for {@link resolveTask} beyond the continue gate. Today the only
- * member is `allowBacklog` (prd
+ * member is `allowBacklog` (spec
  * `do-allow-backlog-drive-staged-tasks-without-promotion`): the operator's
  * EXPLICIT `do … --allow-backlog`, which widens resolution to also search
  * `tasks-backlog` (staging) at LOWEST priority. Default off (omitted) \u21d2 the
@@ -574,7 +571,7 @@ function isStrandedDoneTip(gate: ContinueResolutionGate): boolean {
 
 /**
  * Resolve a task's file: prefer `work/in-progress/<slug>.md`, fall back to
- * `work/tasks/ready/<slug>.md` (the pool). Returns the parsed prd + extracted
+ * `work/tasks/ready/<slug>.md` (the pool). Returns the parsed spec + extracted
  * `## Prompt` body. Throws {@link PromptError} when neither file exists or it has
  * no prompt body.
  *
@@ -588,11 +585,11 @@ function isStrandedDoneTip(gate: ContinueResolutionGate): boolean {
  * the only addition, and it is gated. With no gate (a fresh claim) the behaviour
  * is byte-identical to the original `['in-progress','tasks-ready']`-only resolution.
  *
- * `--allow-backlog` (prd `do-allow-backlog-drive-staged-tasks-without-promotion`):
+ * `--allow-backlog` (spec `do-allow-backlog-drive-staged-tasks-without-promotion`):
  * when {@link ResolveTaskOptions.allowBacklog} is set, `tasks-backlog` (the staging
  * folder) is appended at the LOWEST priority — after `tasks-ready`, so a slug
  * present in BOTH the pool and staging resolves to the READY copy (the same-slug
- * precedence the prd's decision 5 fixes). Default off ⇒ byte-identical to today
+ * precedence the spec's decision 5 fixes). Default off ⇒ byte-identical to today
  * (no autonomous path sets it; staging stays unreachable to `run`/auto-pick).
  */
 export function resolveTask(
@@ -627,9 +624,8 @@ export function resolveTask(
 			);
 		}
 		const fm = parseFrontmatter(content);
-		// Read the parent-spec pointer off `fm.spec` (populated from EITHER the
-		// canonical `spec:` key or the legacy `prd:` back-compat alias) into the
-		// `spec`-only `ResolvedTask` (spec
+		// Read the parent-spec pointer off `fm.spec` (populated from the canonical
+		// `spec:` key) into the `spec`-only `ResolvedTask` (spec
 		// `prd-to-spec-vocabulary-cutover-and-migration-command`).
 		return {slug, path, folder, spec: fm.spec, taskPrompt};
 	}
@@ -665,13 +661,13 @@ export function inferSlugFromBranch(
  */
 /**
  * Resolve the EFFECTIVE `promptGuidance` for an item by walking the precedence
- * chain (highest → lowest): the per-task frontmatter override, the per-prd
- * frontmatter override (only when the task carries a `prd:`), then the
+ * chain (highest → lowest): the per-task frontmatter override, the per-spec
+ * frontmatter override (only when the task carries a `spec:`), then the
  * already-resolved repo policy. Each nudge member resolves independently — a
  * task's `promptGuidance.testFirst` override never bleeds into a sibling
  * member — mirroring the `humanOnly`/`autoBuild` per-item override shape.
  *
- * A task may carry the override even when it has NO `prd:` (a self-contained
+ * A task may carry the override even when it has NO `spec:` (a self-contained
  * chore), by symmetry with `humanOnly` at the item level; `specFrontmatter`
  * is then simply absent and the chain reads task ⇒ repo.
  */
@@ -688,11 +684,11 @@ export function resolveItemPromptGuidance(
 }
 
 /**
- * Locate a prd's file on disk: prefer `work/prds/ready/<slug>.md` (the
- * auto-slice pool), then fall back to `work/prds/tasked/<slug>.md` (tasked,
+ * Locate a spec's file on disk: prefer `work/specs/ready/<slug>.md` (the
+ * auto-slice pool), then fall back to `work/specs/tasked/<slug>.md` (tasked,
  * resting). Returns `undefined` when neither exists — the caller treats that
- * as "no prd-level override available" and the precedence chain falls
- * through to the repo policy (a missing prd is NOT an error at this seam;
+ * as "no spec-level override available" and the precedence chain falls
+ * through to the repo policy (a missing spec is NOT an error at this seam;
  * the per-item override is OPTIONAL by design).
  */
 export function findSpecPath(
@@ -714,7 +710,7 @@ export function findSpecPath(
 /**
  * The convenience seam every caller of {@link buildAgentPrompt} reuses to
  * resolve the per-item override: load the task frontmatter from its file +
- * (when the task carries `prd:`) the prd frontmatter, then walk
+ * (when the task carries `spec:`) the spec frontmatter, then walk
  * {@link resolveItemPromptGuidance}. Pure-ish (reads at most two files);
  * returns the repo policy verbatim when neither item layer overrides anything.
  */
@@ -725,8 +721,7 @@ export function resolvePromptGuidanceForItem(options: {
 }): PromptGuidance {
 	const taskFm = parseFrontmatter(options.taskContent);
 	let specFm: Frontmatter | undefined;
-	// Read the parent-spec pointer off `fm.spec` (populated from the `spec:` key or
-	// the legacy `prd:` back-compat alias).
+	// Read the parent-spec pointer off `fm.spec` (populated from the `spec:` key).
 	if (taskFm.spec !== undefined) {
 		const specPath = findSpecPath(options.cwd, taskFm.spec);
 		if (specPath !== undefined) {
@@ -745,7 +740,7 @@ export function renderPrompt(options: PromptOptions): string {
 		);
 	}
 	const task = resolveTask(options.cwd, slug);
-	// Per-item override layer: a task or prd may pin `promptGuidance.testFirst`
+	// Per-item override layer: a task or spec may pin `promptGuidance.testFirst`
 	// in its frontmatter, superseding the resolved repo policy for THIS item.
 	// We ALWAYS walk the resolver (even when no repo policy was threaded), so a
 	// task can opt IN to the strengthened nudge even on a repo whose default is

package/src/readiness.ts

@@ -16,7 +16,7 @@ import {ledgerRead} from './ledger-read.js';
  * the shared {@link resolveBlockedBy} (no reimplemented dep resolution).
  *
  * The two axes are deliberately treated differently (see WORK-CONTRACT and the
- * task prd):
+ * task spec):
  *
  *   - `blockedBy` unmet is a FACTUAL prerequisite (the dep work does not exist
  *     yet) → REFUSE by default. An override flag is the human escape hatch.

package/src/reap-branches.ts

@@ -1,6 +1,7 @@
 import {run} from './git.js';
-import {isAncestor} from './gc.js';
+import {isProvablyMergedForReap} from './gc.js';
 import {parseWorkBranchRef} from './slug-namespace.js';
+import type {SidecarType} from './sidecar.js';
 
 /**
  * The **remote merged-work-branch reaper** — the cross-machine COUNTERPART of the
@@ -9,13 +10,15 @@ import {parseWorkBranchRef} from './slug-namespace.js';
  * the arbiter after their propose-mode PR has MERGED.
  *
  * The safety lynchpin is the SAME provably-merged predicate the worktree reaper
- * uses (`gc.ts` `isAncestor`, REUSED here, never a second one): a remote
- * `work/<slug>` branch is reapable **iff** its tip is
- * `git merge-base --is-ancestor <tip> <arbiter>/main` — provably on `main`. A
- * merely-pushed-but-unmerged branch (an in-flight, kept-for-continue recovery
- * point) is NOT an ancestor of `main`, so the predicate AUTOMATICALLY excludes it
- * — the never-delete-the-in-flight-branch invariant (ADR §4 deletion-safety)
- * stays absolute. Deletion of a fully-merged ref needs NO force, so this NEVER
+ * uses (`gc.ts` `isProvablyMergedForReap`, REUSED here, never a second one): a
+ * remote `work/<slug>` branch is reapable **iff** it is provably on
+ * `<arbiter>/main` — EITHER `git merge-base --is-ancestor <tip> <arbiter>/main`
+ * (fast path) OR the squash-aware fallback (durable done/dropped record on main
+ * AND branch carries nothing main lacks). A merely-pushed-but-unmerged branch
+ * (an in-flight, kept-for-continue recovery point) has no terminal record on
+ * main AND is not an ancestor, so the predicate AUTOMATICALLY excludes it — the
+ * never-delete-the-in-flight-branch invariant (ADR §4 deletion-safety) stays
+ * absolute. Deletion of a fully-merged ref needs NO force, so this NEVER
  * `--force`s.
  *
  * It is provider-AGNOSTIC plain git (`git ls-remote` to enumerate, `git push
@@ -101,8 +104,9 @@ export interface SweepRemoteBranchesResult {
  *   2. Fetch `<arbiter>/main` into a local tracking ref so the ancestor check
  *      resolves the descendant LOCALLY; fetch each candidate tip object too (so
  *      `merge-base` can read it) — best-effort, into a scratch ref.
- *   3. For each branch whose tip `--is-ancestor` of the fetched main ⇒ delete via
- *      `git push <arbiter> --delete <branch>`; else retain with a reason.
+ *   3. For each branch that is provably merged for reap (fast-path ancestor
+ *      OR squash-aware fallback — {@link isProvablyMergedForReap}) ⇒ delete
+ *      via `git push <arbiter> --delete <branch>`; else retain with a reason.
  */
 export function sweepRemoteMergedBranches(
 	input: SweepRemoteBranchesInput,
@@ -126,12 +130,32 @@ export function sweepRemoteMergedBranches(
 			retain(retained, note, branch, tip, 'main-unresolved');
 			continue;
 		}
-		// Make the candidate tip OBJECT readable locally so `merge-base` can use it
-		// (ls-remote gave us the sha, but the object may not be in the local repo).
+		// Make the candidate tip OBJECT readable locally so `merge-base` /
+		// `diff` / `cherry` can read it (ls-remote gave us the sha, but the
+		// object may not be in the local repo).
 		fetchScratch(input.cwd, input.arbiter, branch, env);
 
-		if (!isAncestor(input.cwd, tip, mainRef, env)) {
-			// NOT an ancestor of main ⇒ still in-flight ⇒ NEVER delete (the invariant).
+		const parsed = parseWorkBranchRef(branch);
+		if (parsed === undefined) {
+			// Guarded above by `listRemoteWorkBranches` (which only enumerates
+			// parseable heads), but keep a defensive belt: without a slug the
+			// squash-aware fallback has no anchor ⇒ retain.
+			retain(retained, note, branch, tip, 'not-merged');
+			continue;
+		}
+
+		if (
+			!isProvablyMergedForReap({
+				cwd: input.cwd,
+				tip,
+				arbiterMain: mainRef,
+				namespace: parsed.namespace as SidecarType,
+				slug: parsed.slug,
+				env,
+			})
+		) {
+			// NOT provably merged (neither ancestor nor squash-aware equivalent)
+			// ⇒ still in-flight ⇒ NEVER delete (the invariant).
 			retain(retained, note, branch, tip, 'not-merged');
 			continue;
 		}

package/src/recover-isolated.ts

@@ -11,7 +11,7 @@ import type {ReviewProvider} from './integrator.js';
 
 /**
  * **`complete --isolated <slug>` — FINISH an already-committed, already-done-moved
- * STRANDED isolated worktree** (prd `ledger-integrity` story 6, the
+ * STRANDED isolated worktree** (spec `ledger-integrity` story 6, the
  * `finish-already-committed-branch` task). The LOCATE-EXISTING inverse of
  * `do --isolated` (which CREATES a worktree): it resolves the slug's RETAINED job
  * worktree via the existing arbiter-URL-keyed naming
@@ -57,6 +57,18 @@ export interface RecoverIsolatedOptions {
 	integration?: IntegrationMode;
 	/** Suppress the PR on the propose path (push the branch, open no review request). */
 	noPR?: boolean;
+	/**
+	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, spec
+	 * `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1
+	 * (a)). Threaded VERBATIM into {@link performIntegration} so a wide-matrix CI's
+	 * raised cap actually reaches the cross-job land queue on the isolated-recovery
+	 * path too (task `thread-merge-retries-cross-task-and-ratify-default`). Resolved
+	 * ONCE at the CLI (the `complete --isolated` command) through the SAME
+	 * gate-family precedence chain the plain `complete` path uses (flag > env >
+	 * per-repo > global > default). Unset ⇒ the engine's `DEFAULT_MERGE_RETRIES =
+	 * 1000` (byte-for-byte unchanged).
+	 */
+	mergeRetries?: number;
 	/** Optional fully-formed provider used verbatim (test/embedding seam). */
 	providerInstance?: ReviewProvider;
 	/** Optional injectable PR opener (legacy bridge); used in `propose` mode. */
@@ -177,6 +189,11 @@ export async function performRecoverIsolated(
 		recovering: false,
 		committedRecovery: true,
 		mode: options.integration ?? 'propose',
+		// The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) — the
+		// git-alone floor of the cross-job land queue, resolved through the gate-
+		// family precedence chain in the CLI and threaded here so the isolated-
+		// recovery land tail respects the per-repo cap.
+		mergeRetries: options.mergeRetries,
 		noPR: options.noPR,
 		providerInstance: options.providerInstance,
 		openPr: options.openPr,