dorfl 0.0.0 → 0.1.0

package/src/readiness.ts

@@ -0,0 +1,98 @@
+import {parseFrontmatter} from './frontmatter.js';
+import {resolveBlockedBy} from './eligibility.js';
+import {ledgerRead} from './ledger-read.js';
+
+/**
+ * The pre-claim readiness guard for the HUMAN `start` / `claim` path. Today the
+ * human path decides purely on the FOLDER on `<arbiter>/main` (is the slug in
+ * `backlog/`?) and never parses the task's frontmatter — so it will happily
+ * claim a task whose `blockedBy` deps are not yet in `work/done/`, or one
+ * flagged `needsAnswers: true`. The autonomous `run --once` path already filters
+ * these out (scan → eligibility → select); this closes that asymmetry for the
+ * human path.
+ *
+ * It reads the SAME source of truth the folder check uses — the task file and
+ * the `work/done/` listing on `<arbiter>/main` — and resolves `blockedBy` with
+ * the shared {@link resolveBlockedBy} (no reimplemented dep resolution).
+ *
+ * The two axes are deliberately treated differently (see WORK-CONTRACT and the
+ * task prd):
+ *
+ *   - `blockedBy` unmet is a FACTUAL prerequisite (the dep work does not exist
+ *     yet) → REFUSE by default. An override flag is the human escape hatch.
+ *   - `needsAnswers: true` is a softer, set-by-someone flag (the claimer may be
+ *     the one about to resolve it) → WARN loudly but still claim. The same
+ *     override silences the warning.
+ *
+ * `humanOnly` is NOT consulted here: `start`/`claim` is the human path, and a
+ * human is never bound by `humanOnly` (it means "a human must drive this", and
+ * the human is here).
+ */
+
+export interface ReadinessVerdict {
+	/**
+	 * `true` when the claim should be REFUSED before the CAS runs (an unmet
+	 * `blockedBy`, not overridden). When `true`, the caller claims nothing.
+	 */
+	refuse: boolean;
+	/** Blocker slugs not present in `work/done/` on the arbiter, in order. */
+	missing: string[];
+	/** Whether the task declares `needsAnswers: true`. */
+	needsAnswers: boolean;
+	/**
+	 * `true` when an override flag was supplied (the refusal is bypassed and the
+	 * `needsAnswers` warning is silenced — loudly).
+	 */
+	overridden: boolean;
+}
+
+export interface ResolveReadinessOptions {
+	/** The slug being claimed (`work/backlog/<slug>.md`). */
+	slug: string;
+	/** Working clone the human path runs in. */
+	cwd: string;
+	/** Name of the arbiter git remote. */
+	arbiter: string;
+	/** Override flag (`--force` / `--ignore-not-ready`): bypass refusal + warning. */
+	override: boolean;
+	/** Environment for child git processes. */
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * Resolve the readiness of a task against `<arbiter>/main`. PURE w.r.t. the
+ * work tree — it reads only committed objects on the arbiter (the task file and
+ * the `work/done/` listing), the same source of truth the folder check uses.
+ *
+ * Assumes the caller has already fetched the arbiter (the human path fetches
+ * before deciding on the folder). Missing/unparseable task frontmatter degrades
+ * to "no blockers, no needsAnswers" — the folder check, not this guard, owns the
+ * "task exists / is in backlog" decision.
+ */
+export async function resolveReadiness(
+	options: ResolveReadinessOptions,
+): Promise<ReadinessVerdict> {
+	const {slug, cwd, arbiter, override, env} = options;
+
+	// Resolve the task + `work/done/` from `<arbiter>/main` THROUGH the read
+	// seam's arbiter method — the single insertion point. Same source of truth the
+	// folder check uses; behaviour is byte-identical to the inline reads it
+	// replaced (task from `backlog/` or `in-progress/`, done slugs from the tree).
+	const {task, doneSlugs} = await ledgerRead.resolveArbiterState({
+		slug,
+		cwd,
+		arbiter,
+		env,
+	});
+	const fm = parseFrontmatter(task ?? '');
+	const needsAnswers = fm.needsAnswers === true;
+
+	const {missing} = resolveBlockedBy(fm.blockedBy, doneSlugs);
+
+	return {
+		refuse: missing.length > 0 && !override,
+		missing,
+		needsAnswers,
+		overridden: override,
+	};
+}

package/src/reap-branches.ts

@@ -0,0 +1,278 @@
+import {run} from './git.js';
+import {isAncestor} from './gc.js';
+import {parseWorkBranchRef} from './slug-namespace.js';
+
+/**
+ * The **remote merged-work-branch reaper** — the cross-machine COUNTERPART of the
+ * job-worktree reaper in `gc.ts`. Where `gc.ts` reaps LOCAL job WORKTREES under
+ * `workspacesDir/work/*`, this reaps REMOTE `work/<slug>` BRANCHES that linger on
+ * 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
+ * `--force`s.
+ *
+ * It is provider-AGNOSTIC plain git (`git ls-remote` to enumerate, `git push
+ * --delete` to reap), so it works against a local `--bare` arbiter and any
+ * provider — NOT relying on GitHub's repo-level auto-delete setting (which is an
+ * additive convenience for GitHub arbiters only). The arbiter is addressed
+ * THROUGH a local repo (`cwd`) whose `<arbiter>` remote points at it: the same
+ * way `requeue --reset` addresses the arbiter for its sanctioned UN-merged
+ * deletion (the complement of this merged-only sweep).
+ */
+
+/** Why a remote `work/<slug>` branch was RETAINED (not provably merged). */
+export type RemoteRetainReason =
+	| 'not-merged' // the tip is NOT an ancestor of <arbiter>/main (still in-flight)
+	| 'main-unresolved'; // <arbiter>/main could not be resolved (cannot prove safety)
+
+/** Human-readable text for each remote-branch retain reason (`sweep` reports). */
+export const REMOTE_RETAIN_REASON_TEXT: Record<RemoteRetainReason, string> = {
+	'not-merged':
+		'not merged (branch tip is not an ancestor of the arbiter main — still in-flight)',
+	'main-unresolved':
+		'arbiter main could not be resolved, so merge could not be proven (kept — safe direction)',
+};
+
+/** A remote `work/<slug>` branch the sweep reaped (provably merged). */
+export interface ReapedBranch {
+	/** The full branch ref (`work/<slug>`). */
+	branch: string;
+	/** The 40-hex tip the branch pointed at when it was deleted. */
+	tip: string;
+}
+
+/** A remote `work/<slug>` branch the sweep RETAINED, with the reason it kept it. */
+export interface RetainedBranch {
+	branch: string;
+	tip: string;
+	reason: RemoteRetainReason;
+	/** Human-readable reason text (`REMOTE_RETAIN_REASON_TEXT[reason]`). */
+	reasonText: string;
+}
+
+export interface SweepRemoteBranchesInput {
+	/**
+	 * A local repo (a checkout or a hub mirror) whose `<arbiter>` remote points at
+	 * the arbiter to sweep. All git runs in here; nothing in the working tree is
+	 * touched (only remote refs are read + deleted).
+	 */
+	cwd: string;
+	/** The arbiter remote name (default `origin`, as `requeue --arbiter` defaults). */
+	arbiter: string;
+	/** Sink for human-readable progress notes (per reaped / retained branch). */
+	note?: (message: string) => void;
+	/**
+	 * Do NOT actually delete — only REPORT what WOULD be reaped vs retained. A
+	 * read-only preview (`--dry-run`); the predicate still runs so the report is
+	 * exact.
+	 */
+	dryRun?: boolean;
+	env?: NodeJS.ProcessEnv;
+}
+
+export interface SweepRemoteBranchesResult {
+	/** The remote branches reaped this sweep (provably merged). Empty on dry-run. */
+	reaped: ReapedBranch[];
+	/** The remote branches retained, each with a clear reason. */
+	retained: RetainedBranch[];
+	/** On `dryRun`, the branches that WOULD be reaped (not actually deleted). */
+	wouldReap: ReapedBranch[];
+}
+
+/**
+ * Sweep the arbiter's remote `work/*` branches and DELETE exactly those that are
+ * provably merged into `<arbiter>/main` (`git merge-base --is-ancestor`, REUSING
+ * `gc.ts`'s `isAncestor`), reporting each as deleted-merged / retained-with-
+ * reason. NEVER `--force` (a merged ref needs none); NEVER touches a branch that
+ * is not an ancestor of `main` (the in-flight recovery point the never-delete
+ * invariant protects). Provider-agnostic plain git, so it works on a `--bare`
+ * arbiter.
+ *
+ * The flow:
+ *   1. `git ls-remote --heads <arbiter> 'work/*'` — enumerate remote work
+ *      branches + their tips (one network round-trip; no full fetch).
+ *   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.
+ */
+export function sweepRemoteMergedBranches(
+	input: SweepRemoteBranchesInput,
+): SweepRemoteBranchesResult {
+	const note = input.note ?? (() => {});
+	const env = input.env;
+	const dryRun = input.dryRun === true;
+	const reaped: ReapedBranch[] = [];
+	const retained: RetainedBranch[] = [];
+	const wouldReap: ReapedBranch[] = [];
+
+	const branches = listRemoteWorkBranches(input.cwd, input.arbiter, env);
+
+	// Resolve the arbiter's main tip LOCALLY (fetch it into a scratch tracking
+	// ref). If it cannot be resolved (unreachable arbiter / no main), we cannot
+	// PROVE any branch merged — retain everything (the safe direction).
+	const mainRef = fetchScratch(input.cwd, input.arbiter, 'main', env);
+
+	for (const {branch, tip} of branches) {
+		if (mainRef === undefined) {
+			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).
+		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).
+			retain(retained, note, branch, tip, 'not-merged');
+			continue;
+		}
+
+		// Provably merged. Report (dry-run) or delete (the real sweep). Deletion of
+		// a fully-merged ref needs NO force — and we NEVER force here. The deletion
+		// is WRITE-THROUGH: drop the LOCAL tracking ref FIRST, THEN `git push
+		// --delete`. An arbiter-delete failure thus leaves the local store BEHIND
+		// (self-healing on next fetch), never AHEAD (a stale tracking ref that
+		// drives a wrong "continue" — the permanent stale-continue bug today's
+		// arbiter-first ordering creates).
+		if (dryRun) {
+			wouldReap.push({branch, tip});
+			note(`Would reap ${branch} (merged) on ${input.arbiter}.`);
+			continue;
+		}
+		run(
+			'git',
+			['update-ref', '-d', `refs/remotes/${input.arbiter}/${branch}`],
+			input.cwd,
+			{env},
+		);
+		const del = run(
+			'git',
+			['push', input.arbiter, '--delete', branch],
+			input.cwd,
+			{env},
+		);
+		if (del.status !== 0) {
+			// A failed delete is NOT a reap; surface it but keep sweeping the rest.
+			// Tolerate "already gone" (a concurrent reap) as a clean delete.
+			const stderr = del.stderr.trim();
+			const alreadyGone = /remote ref does not exist|unable to delete/i.test(
+				stderr,
+			);
+			if (alreadyGone) {
+				reaped.push({branch, tip});
+				note(`Reaped ${branch} (merged; remote ref was already gone).`);
+				continue;
+			}
+			retain(retained, note, branch, tip, 'not-merged');
+			note(
+				`Failed to delete ${branch} on ${input.arbiter} (${stderr || 'unknown error'}); kept.`,
+			);
+			continue;
+		}
+		reaped.push({branch, tip});
+		note(`Reaped ${branch} (merged) on ${input.arbiter}.`);
+	}
+
+	return {reaped, retained, wouldReap};
+}
+
+/** Push a retained branch into the result + emit its note. */
+function retain(
+	retained: RetainedBranch[],
+	note: (message: string) => void,
+	branch: string,
+	tip: string,
+	reason: RemoteRetainReason,
+): void {
+	const reasonText = REMOTE_RETAIN_REASON_TEXT[reason];
+	retained.push({branch, tip, reason, reasonText});
+	note(`Retained ${branch}: ${reasonText}.`);
+}
+
+/**
+ * Enumerate the arbiter's remote `work/*` heads + their tips via
+ * `git ls-remote --heads <arbiter> 'work/*'` (one round-trip, no full fetch).
+ * Only `work/<type>-<slug>` branches that {@link parseWorkBranchRef} recognises
+ * are returned (a stray `work/foo` that is not a namespaced work branch is
+ * ignored — the sweep only reaps the branches the protocol creates). Returns []
+ * when the arbiter is unreachable (the safe direction — nothing to reap).
+ */
+export function listRemoteWorkBranches(
+	cwd: string,
+	arbiter: string,
+	env: NodeJS.ProcessEnv | undefined,
+): Array<{branch: string; tip: string}> {
+	const res = run('git', ['ls-remote', '--heads', arbiter, 'work/*'], cwd, {
+		env,
+	});
+	if (res.status !== 0) {
+		return [];
+	}
+	const out: Array<{branch: string; tip: string}> = [];
+	for (const line of res.stdout.split('\n')) {
+		const trimmed = line.trim();
+		if (trimmed === '') {
+			continue;
+		}
+		// Each line is `<sha>\trefs/heads/<branch>`.
+		const m = /^([0-9a-f]{40})\s+refs\/heads\/(.+)$/.exec(trimmed);
+		if (!m) {
+			continue;
+		}
+		const tip = m[1];
+		const branch = m[2];
+		// Only namespaced work branches (`work/<type>-<slug>`) — the protocol's own
+		// branches. A non-conforming `work/...` head is left untouched.
+		if (parseWorkBranchRef(branch) === undefined) {
+			continue;
+		}
+		out.push({branch, tip});
+	}
+	return out;
+}
+
+/**
+ * Fetch a single arbiter head into a SCRATCH remote-tracking ref
+ * (`refs/remotes/<arbiter>/<head>`) EXPLICITLY (a bare arbiter has no fetch
+ * refspec), so the object + ref resolve LOCALLY for the ancestor check. Returns
+ * the local ref name on success, or `undefined` when the head could not be
+ * fetched (unreachable arbiter / missing head) — the caller reads that as
+ * not-provable ⇒ retain (the safe direction). Best-effort; never throws.
+ */
+function fetchScratch(
+	cwd: string,
+	arbiter: string,
+	head: string,
+	env: NodeJS.ProcessEnv | undefined,
+): string | undefined {
+	const localRef = `refs/remotes/${arbiter}/${head}`;
+	const res = run(
+		'git',
+		['fetch', '--quiet', arbiter, `+refs/heads/${head}:${localRef}`],
+		cwd,
+		{env},
+	);
+	if (res.status !== 0) {
+		return undefined;
+	}
+	// Confirm the ref now resolves locally (an empty/odd fetch should read as
+	// unresolved → retain).
+	const verify = run(
+		'git',
+		['rev-parse', '--verify', '--quiet', localRef],
+		cwd,
+		{
+			env,
+		},
+	);
+	return verify.status === 0 ? localRef : undefined;
+}

package/src/recover-isolated.ts

@@ -0,0 +1,276 @@
+import {existsSync} from 'node:fs';
+import {performIntegration} from './integration-core.js';
+import {resolveArbiterUrlFromCheckout} from './do.js';
+import {jobWorktreePath} from './workspace.js';
+import {mirrorPath} from './repo-mirror.js';
+import {reapJob} from './gc.js';
+import {workBranchRef} from './slug-namespace.js';
+import {run, type RunResult} from './git.js';
+import type {IntegrationMode} from './config.js';
+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
+ * `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
+ * (`jobWorktreePath`/`encodeWorkId` — NOT a slug glob, since two repos can share a
+ * slug), then runs the recover-already-committed integration path
+ * (`performIntegration({committedRecovery: true})`) from it: rebase the kept
+ * commit onto `<arbiter>/main` → integrate, SKIPPING the (already-done) gate /
+ * done-move / commit.
+ *
+ * IDEMPOTENT / HONEST: when NO worktree is retained for the slug, this is a clean
+ * "nothing to recover / already integrated" no-op (exit 0, no crash, no fresh
+ * worktree) — after a successful recovery the worktree is reaped, so a re-run
+ * correctly finds nothing. The integration core's own UNSPOOFABLE detection
+ * (`already-integrated`) covers the case where the worktree still exists but its
+ * tip is already on the arbiter (never a double-integrate).
+ *
+ * `resume --isolated <slug>` shares the SAME locate-existing resolver (see
+ * {@link locateIsolatedRecovery}) to re-engage the retained worktree WITHOUT
+ * claiming — it just reports the worktree path for the operator to cd into.
+ */
+
+const DEFAULT_ARBITER = 'origin';
+/** The arbiter remote name valid INSIDE a job worktree (cut from the bare hub mirror). */
+const WORKTREE_ARBITER_REMOTE = 'origin';
+
+export type RecoverIsolatedOutcome =
+	| 'completed' // integrated the kept commit from the retained worktree
+	| 'already-integrated' // the kept tip was already on the arbiter (clean no-op)
+	| 'nothing-to-recover' // no retained worktree for the slug (clean no-op)
+	| 'rebase-conflict' // the kept commit did not replay onto the latest main
+	| 'usage-error'; // not a git repo / no such arbiter remote / etc.
+
+export interface RecoverIsolatedOptions {
+	/** The slug to recover (its retained worktree is located by arbiter-URL + slug). */
+	slug: string;
+	/** The operator's checkout — its arbiter remote names the repo the worktree is off. */
+	cwd: string;
+	/** Name of the arbiter remote in {@link cwd}. Defaults to `origin`. */
+	arbiter?: string;
+	/** The execution working area (config `workspacesDir`); where job worktrees live. */
+	workspacesDir: string;
+	/** Integration mode: `propose` (default) or `merge`. */
+	integration?: IntegrationMode;
+	/** Suppress the PR on the propose path (push the branch, open no review request). */
+	noPR?: boolean;
+	/** Optional fully-formed provider used verbatim (test/embedding seam). */
+	providerInstance?: ReviewProvider;
+	/** Optional injectable PR opener (legacy bridge); used in `propose` mode. */
+	openPr?: (opts: {
+		cwd: string;
+		branch: string;
+		env?: NodeJS.ProcessEnv;
+	}) => void;
+	/** Environment for child git/provider processes (the identity-scoped env). */
+	env?: NodeJS.ProcessEnv;
+	/** Sink for human-readable progress notes. */
+	note?: (message: string) => void;
+}
+
+export interface RecoverIsolatedResult {
+	exitCode: 0 | 1;
+	outcome: RecoverIsolatedOutcome;
+	/** The work branch that was recovered, when a worktree was located. */
+	branch?: string;
+	/** The retained worktree dir that was recovered from, when located. */
+	worktree?: string;
+	/** The review-request URL opened in propose mode, when a provider opened one. */
+	prUrl?: string;
+	/** Human-readable summary of the terminal condition. */
+	message: string;
+}
+
+/**
+ * The LOCATE-EXISTING resolver shared by `complete --isolated` and
+ * `resume --isolated`: resolve the arbiter URL from the operator's checkout, then
+ * the slug's retained job-worktree dir via `jobWorktreePath` (arbiter-URL-keyed —
+ * NOT a slug glob). Returns the resolved dir + arbiter URL when the worktree is
+ * PRESENT; an `error` (usage) when the arbiter is unresolvable; or
+ * `{present: false}` when no worktree is retained (the clean nothing-to-recover
+ * case). Pure resolution — no side effects.
+ */
+export function locateIsolatedRecovery(params: {
+	slug: string;
+	cwd: string;
+	arbiter: string;
+	workspacesDir: string;
+	env?: NodeJS.ProcessEnv;
+}):
+	| {dir: string; arbiterUrl: string; present: true}
+	| {present: false}
+	| {
+			error: string;
+	  } {
+	const arbiterUrl = resolveArbiterUrlFromCheckout(
+		params.cwd,
+		params.arbiter,
+		params.env,
+	);
+	if (arbiterUrl === undefined) {
+		return {
+			error:
+				`--isolated finishes a worktree off this repo's arbiter (inferred from ` +
+				`cwd), but no '${params.arbiter}' remote was found here (is this a git ` +
+				`repo? does the '${params.arbiter}' remote exist?).`,
+		};
+	}
+	const dir = jobWorktreePath(params.workspacesDir, arbiterUrl, params.slug);
+	if (!existsSync(dir)) {
+		return {present: false};
+	}
+	return {dir, arbiterUrl, present: true};
+}
+
+/**
+ * Run the isolated recovery for a stranded, already-committed, already-done-moved
+ * worktree (the `complete --isolated <slug>` surface). Never throws for the
+ * expected cases — they are returned with a specific outcome + exit code.
+ */
+export async function performRecoverIsolated(
+	options: RecoverIsolatedOptions,
+): Promise<RecoverIsolatedResult> {
+	const note = options.note ?? (() => {});
+	const env = options.env;
+	const arbiter = options.arbiter ?? DEFAULT_ARBITER;
+
+	const located = locateIsolatedRecovery({
+		slug: options.slug,
+		cwd: options.cwd,
+		arbiter,
+		workspacesDir: options.workspacesDir,
+		env,
+	});
+	if ('error' in located) {
+		return {exitCode: 1, outcome: 'usage-error', message: located.error};
+	}
+	if (!located.present) {
+		// No retained worktree — honest no-op: nothing to recover (already
+		// integrated + reaped, or never stranded). No crash, NO fresh worktree.
+		const message =
+			`Nothing to recover for '${options.slug}': no retained isolated worktree ` +
+			'found (already integrated and reaped, or never stranded).';
+		note(message);
+		return {exitCode: 0, outcome: 'nothing-to-recover', message};
+	}
+
+	const dir = located.dir;
+	const branch = workBranchRef('task', options.slug);
+	// The strand left the worktree ON its `work/<slug>` branch; make sure we are on
+	// it (it carries the kept committed work + the done-move). Best-effort: if HEAD
+	// is already there this is a no-op; a missing branch surfaces as a usage error
+	// from the integration core's HEAD-resolution.
+	gitSoft(['switch', '--quiet', branch], dir, env);
+
+	note(`Recovering '${options.slug}' from the retained worktree ${dir}…`);
+	const core = await performIntegration({
+		cwd: dir,
+		// Inside a job worktree the arbiter remote is `origin` (the mirror's clone
+		// remote), NOT the operator's checkout arbiter name.
+		arbiter: WORKTREE_ARBITER_REMOTE,
+		slug: options.slug,
+		branch,
+		source: 'in-progress',
+		recovering: false,
+		committedRecovery: true,
+		mode: options.integration ?? 'propose',
+		noPR: options.noPR,
+		providerInstance: options.providerInstance,
+		openPr: options.openPr,
+		env,
+		note,
+	});
+
+	if (core.outcome === 'already-integrated') {
+		// The kept tip is already on the arbiter — a clean no-op. Reap the now-redundant
+		// worktree (its branch is provably on the arbiter), so a re-run finds nothing.
+		reapIfSafe(options.workspacesDir, located.arbiterUrl, branch, dir, env);
+		return {
+			exitCode: 0,
+			outcome: 'already-integrated',
+			branch,
+			worktree: dir,
+			message: core.reason ?? `'${options.slug}' is already integrated.`,
+		};
+	}
+	if (core.outcome === 'rebase-conflict') {
+		// A genuine code conflict — the kept commit stays intact on the branch
+		// (recoverable); the operator resolves it and re-runs. Worktree RETAINED.
+		return {
+			exitCode: 1,
+			outcome: 'rebase-conflict',
+			branch,
+			worktree: dir,
+			message:
+				core.reason ?? `recovering '${options.slug}' hit a rebase conflict.`,
+		};
+	}
+	if (core.outcome === 'completed') {
+		// Integrated from the kept commit. The work is now on the arbiter, so the
+		// worktree is provably redundant — reap it (the same §4 predicate the build
+		// teardown uses; never lose work — reachability still gates).
+		reapIfSafe(options.workspacesDir, located.arbiterUrl, branch, dir, env);
+		const prUrl = core.integration?.url;
+		const message = prUrl
+			? `Recovered '${options.slug}': integrated the kept commit (${prUrl}).`
+			: `Recovered '${options.slug}': integrated the kept commit from ${branch}.`;
+		note(message);
+		return {
+			exitCode: 0,
+			outcome: 'completed',
+			branch,
+			worktree: dir,
+			prUrl,
+			message,
+		};
+	}
+	// Any other core outcome (defensive — committed-recovery only returns the three
+	// above): surface it as a usage error rather than mis-reporting success.
+	return {
+		exitCode: 1,
+		outcome: 'usage-error',
+		branch,
+		worktree: dir,
+		message:
+			core.reason ??
+			`recovering '${options.slug}' returned an unexpected outcome ` +
+				`'${core.outcome}'.`,
+	};
+}
+
+/**
+ * Reap the recovered worktree iff its branch is provably on the arbiter (the §4
+ * predicate, reachable-only so incidental churn does not retain a worktree whose
+ * branch is already safe). Best-effort: never throws on this success path.
+ */
+function reapIfSafe(
+	workspacesDir: string,
+	arbiterUrl: string,
+	branch: string,
+	dir: string,
+	env: NodeJS.ProcessEnv | undefined,
+): void {
+	try {
+		reapJob({
+			dir,
+			branch,
+			mirrorPath: mirrorPath(workspacesDir, arbiterUrl),
+			reachableOnly: true,
+			env,
+		});
+	} catch {
+		// best-effort — the work is already on the arbiter; a reap failure is cosmetic.
+	}
+}
+
+/** Run git, returning the raw result (no throw) — for soft checks. */
+function gitSoft(
+	args: string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): RunResult {
+	return run('git', args, cwd, {env});
+}