dorfl 0.13.2 → 0.13.3

package/src/claim-cas.ts

@@ -1,5 +1,6 @@
 import {runAsync, type RunResult} from './git.js';
 import {acquireItemLock, releaseItemLock, heldTaskSlugs} from './item-lock.js';
+import {reconcileTerminalState} from './reconcile-terminal.js';
 import {extractPromptSection} from './prompt.js';
 import {resolveReadiness} from './readiness.js';
 import {workBranchRef} from './slug-namespace.js';
@@ -386,6 +387,45 @@ async function runClaim(
 		}
 	}
 
+	// LAZY RECONCILIATION of TERMINAL-STATE RESIDUE: the stale per-item lock a
+	// propose PR leaves behind (observation
+	// `every-completed-task-leaves-its-lock-ref-reporting-in-progress`) AND the
+	// stranded sidecar + `needsAnswers` flag a bounced-then-rebuilt item leaves
+	// behind (observation
+	// `a-rebuilt-task-leaves-its-bounce-question-asking-to-cancel-a-merged-task`).
+	// ONE pass, because they are the SAME defect wearing two hats: both are cleared
+	// by a step that only runs on a path the item did not take, both become moot at
+	// exactly the same moment (the done-move landing on `main`), and both are
+	// otherwise detectable only from a loop the manual path never enters.
+	//
+	// `complete --propose` deliberately KEEPS its per-item lock held across the open
+	// PR and promises "It is released when the PR merges (reconciled against main)".
+	// That release could never fire: no dorfl process runs when a human clicks merge
+	// on GitHub, there is no merge hook, and there is no daemon, so every completed
+	// propose item leaked its lock ref permanently.
+	//
+	// THIS is where the release belongs, and why it is here rather than on `status`:
+	// the merge EVENT is unobservable, but its CONSEQUENCE on `main` is durable, so
+	// any later sweep converges just as well as a timely one. `claim` is the natural
+	// host, it ALREADY writes to the arbiter (it is about to acquire a lock), it
+	// ALREADY fetched `main` just above, and it runs on EVERY unit of work, so the
+	// leaked set drains continuously without a human ever being asked to run a
+	// clean-up verb. Keeping the release on a write path is what makes the fix real:
+	// `gc --ledger` had been reporting these very locks and printing the
+	// `release-lock` command all along, and that offer is precisely what nobody was
+	// routed to. The read-only surfaces (`status`, `scan`) therefore only CLASSIFY.
+	//
+	// It acts EXACTLY on items that have come to REST in a terminal folder on
+	// `<arbiter>/main`; an item on an OPEN PR still shows its body in the pool and
+	// keeps both its lock and its question state, as does a genuinely stuck one.
+	// Clearing a live `needsAnswers` would be as bad as releasing a live lock: it
+	// would disarm a gate and hand gated work to agents. Best-effort and never throws:
+	// any fault leaves every lock HELD (the safe direction) and never fails the
+	// claim, which is unrelated work, this sweep is opportunistic hygiene, not a
+	// precondition. It also cannot affect THIS claim's outcome: an item terminal on
+	// `main` is not in the claimable pool anyway.
+	await reconcileTerminalState({cwd, arbiter, env});
+
 	// Acquire the lock FIRST. A lock `lost` (someone already holds this SAME item's
 	// lock) makes claim lose DEFINITIVELY — exit 2, NO retry budget (a per-item ref
 	// never falsely contends, so a rejection is a GENUINE same-item conflict the

package/src/cli.ts

@@ -167,6 +167,7 @@ interface ScanFlags {
 	autoBuild?: boolean;
 	json?: boolean;
 	here?: boolean;
+	reconcileLocks?: boolean;
 	arbiterRemote?: string;
 	arbiter?: string;
 }
@@ -1029,6 +1030,7 @@ interface StatusFlags {
 	arbiter?: string;
 	noArbiter?: boolean;
 	here?: boolean;
+	reconcileLocks?: boolean;
 	json?: boolean;
 }
 
@@ -1385,6 +1387,10 @@ export function buildProgram(): Command {
 			'--here',
 			'report ONLY the current repo (the cwd working tree, fetch-first): skip the cross-repo registry loop entirely. The fast, focused path — no N-mirror fetches.',
 		)
+		.option(
+			'--reconcile-locks',
+			'WRITE: release the per-item locks whose item is already at rest in a terminal folder on the arbiter’s main (e.g. a merged propose PR left its lock behind). Without this flag `scan` is strictly read-only. Not normally needed, the claim path releases them automatically on every unit of work. An item that is NOT terminal on main (a live build, an open PR, a stuck item) is NEVER released, with or without the flag.',
+		)
 		.option('--json', 'output the raw report as JSON')
 		.action(async (flags: ScanFlags, command: Commander) => {
 			const fileConfig = loadConfig(flags.config);
@@ -1403,6 +1409,7 @@ export function buildProgram(): Command {
 					override,
 					arbiterRemote: flags.arbiterRemote,
 					lockArbiterRemote: flags.arbiter ?? 'origin',
+					reconcileLocks: flags.reconcileLocks === true,
 					warn,
 				});
 			// `--here`: report ONLY the cwd — skip the registry loop ENTIRELY (the fast,
@@ -1425,7 +1432,11 @@ export function buildProgram(): Command {
 				}
 				return;
 			}
-			const report = await scan(config, {warn, override});
+			const report = await scan(config, {
+				warn,
+				override,
+				reconcileLocks: flags.reconcileLocks === true,
+			});
 			// The cwd-local section: resolve it ONLY when a participating cwd is NOT
 			// already covered by a registered mirror. A FETCH-FREE pre-check
 			// (`cwdSectionDisposition`) decides this with zero network I/O; an
@@ -3908,6 +3919,10 @@ export function buildProgram(): Command {
 			'--here',
 			'report ONLY the current repo (the cwd working tree, fetch-first): skip the jobs, registry-mirror, and arbiter sections entirely. "This repo, nothing else" — the fast, focused path.',
 		)
+		.option(
+			'--reconcile-locks',
+			'WRITE: release the per-item locks reported as "Completed, lock not yet released" (item already at rest in a terminal folder on the arbiter’s main, e.g. a merged propose PR). Without this flag `status` is strictly read-only and only REPORTS them. Not normally needed, the claim path releases them automatically on every unit of work; this is the manual “drain them now” lever. An item that is NOT terminal on main (a live build, an open PR, a stuck item) is NEVER released, with or without the flag.',
+		)
 		.option('--json', 'output the raw report as JSON')
 		.action(async (flags: StatusFlags) => {
 			const config = resolveGlobalConfig(loadConfig(flags.config), {});
@@ -3923,6 +3938,7 @@ export function buildProgram(): Command {
 					override,
 					arbiterRemote: flags.arbiterRemote ?? DEFAULT_ARBITER_REMOTE,
 					lockArbiterRemote: flags.arbiter ?? 'origin',
+					reconcileLocks: flags.reconcileLocks === true,
 					warn,
 				});
 			// `--here`: report ONLY the cwd — skip the jobs, registry-mirror, and arbiter
@@ -3976,6 +3992,7 @@ export function buildProgram(): Command {
 				mirrorPaths,
 				arbiter,
 				cwd: cwdSection,
+				reconcileLocks: flags.reconcileLocks === true,
 				warn,
 			});
 			if (flags.json) {

package/src/complete.ts

@@ -1260,10 +1260,17 @@ async function releaseClaimLockAfterDurableMove(
 	if (!durablyOnMain) {
 		// PROPOSE, PR open: the done-move is on the PR branch, not on `main`. KEEP the
 		// lock held so the in-flight task is not re-claimed during the review window.
+		// The wording used to promise "It is released when the PR merges (reconciled
+		// against main)", which was FALSE: no dorfl process is present at merge time
+		// (no hook, no daemon), so nothing could act on that event and every propose
+		// build leaked its lock ref for ever. The release actually happens on the next
+		// command that writes to the arbiter (the claim path sweeps stale terminal
+		// locks), so the message now names a trigger that really fires.
 		note(
 			`'${slug}': keeping the per-item lock HELD (propose PR open; the work is ` +
-				'not yet on main). It is released when the PR merges (reconciled against ' +
-				'main).',
+				'not yet on main). Once the PR merges, the item comes to rest on main and ' +
+				'the lock is released by the next claim (or now, with `dorfl status ' +
+				'--reconcile-locks`).',
 		);
 		return;
 	}

package/src/cwd-section.ts

@@ -8,7 +8,14 @@ import {
 	heldTaskSlugsStrict,
 	heldSpecSlugsStrict,
 	listItemLockEntries,
+	classifyTerminalItemLocks,
+	reconcileTerminalItemLocks,
+	type LockEntry,
 } from './item-lock.js';
+import {
+	classifyTerminalQuestionResidue,
+	reconcileTerminalQuestionResidue,
+} from './needs-attention.js';
 import type {Config} from './config.js';
 import type {ConfigOverrideMap} from './config-override.js';
 
@@ -105,6 +112,36 @@ export interface CwdSection {
 	registeredMirrorPath?: string;
 	/** The cwd repo's arbiter + divergence (fetch-first). Absent when no arbiter. */
 	arbiter?: CwdArbiter;
+	/**
+	 * Lock `<entry>` names whose item is already at REST in a terminal folder on
+	 * `<arbiter>/main`, finished work (typically a merged propose PR) whose lock
+	 * has not been released yet. These are STALE, not in flight, and are reported
+	 * separately from {@link RepoReport.lockHeld} so completed work never reads as
+	 * in-progress. Purely a CLASSIFICATION: `status` releases nothing (it is
+	 * read-only). They are released automatically by the next claim, or on demand
+	 * via `--reconcile-locks` / `dorfl gc --ledger --reap-stale-locks`.
+	 */
+	staleLocks?: string[];
+	/**
+	 * Lock `<entry>` names this call actually RELEASED. Populated ONLY under the
+	 * explicit `reconcileLocks` opt-in (`status --reconcile-locks`), which is the
+	 * one way this otherwise read-only resolver writes to the arbiter. Empty/absent
+	 * ⇒ nothing was written.
+	 */
+	reconciledLocks?: string[];
+	/**
+	 * Items resting in a TERMINAL folder on `main` that still carry question state
+	 * (a stale bounce sidecar, and often a stranded `needsAnswers:true` gate over
+	 * shipped work). Reported so the residue is visible; `status` clears nothing.
+	 * These drain on the next claim.
+	 */
+	staleQuestions?: string[];
+	/**
+	 * Terminal items whose sidecar carries a human's ANSWER that was never applied.
+	 * Deliberately NEVER auto-drained (the answer is prose the tool did not
+	 * author), so it is surfaced for a human instead.
+	 */
+	unappliedAnswers?: string[];
 }
 
 /** True iff the working repo has a git remote with name `remote`. The held-lock
@@ -204,6 +241,16 @@ export interface ResolveCwdSectionOptions {
 	 * arbiter even when the divergence remote is absent. Default `origin`.
 	 */
 	lockArbiterRemote?: string;
+	/**
+	 * OPT-IN WRITE (`status --reconcile-locks`). `false`/omitted (the DEFAULT)
+	 * keeps this resolver strictly READ-ONLY: stale locks are classified and
+	 * REPORTED via {@link CwdSection.staleLocks}, and nothing on the arbiter is
+	 * touched. `true` additionally RELEASES the locks whose item is terminal on
+	 * `<arbiter>/main`, reporting them via {@link CwdSection.reconciledLocks}.
+	 * Not needed for routine convergence, the claim path already sweeps on every
+	 * unit of work; this is the manual "drain them now" lever.
+	 */
+	reconcileLocks?: boolean;
 	/** Sink for the fetch-first fall-back warning (warn + last-known, never error). */
 	warn?: (message: string) => void;
 	env?: NodeJS.ProcessEnv;
@@ -261,6 +308,96 @@ export async function resolveCwdSection(
 	//    nothing to fail against — it keeps the empty set.
 	const lockRemote = options.lockArbiterRemote ?? 'origin';
 	const hasLockRemote = remoteExists(cwd, lockRemote, env);
+
+	// 2a. CLASSIFY the held locks against `main` (fix for the propose-path lock
+	//     leak; observation
+	//     `every-completed-task-leaves-its-lock-ref-reporting-in-progress`).
+	//     `complete --propose` deliberately keeps the lock HELD across the open PR
+	//     and promises it is "released when the PR merges (reconciled against
+	//     main)", but NO dorfl process runs when a human clicks merge on GitHub,
+	//     and there is no daemon, so that release could never fire. Every completed
+	//     propose item therefore kept its lock ref and was reported in-progress for
+	//     ever.
+	//
+	//     `status` is READ-ONLY and stays that way: by DEFAULT this only
+	//     CLASSIFIES, splitting the held locks into genuinely in-flight ones and
+	//     ones whose item has come to REST in a terminal folder on
+	//     `<arbiter>/main`. That alone fixes the MIS-REPORTING half of the bug
+	//     finished work stops reading as in-progress, without this command
+	//     mutating the arbiter. The REF is drained by the paths that already write
+	//     on every unit of work (the claim path), or on demand here via the
+	//     explicit `reconcileLocks` opt-in below.
+	//
+	//     The terminal test is the item's POSITION ON MAIN, never a branch or a
+	//     PR, so an item on an OPEN PR (body still in the pool on `main`) stays
+	//     in-flight, as does a genuinely stuck one. Ordered BEFORE the held-slug
+	//     reads below so, under the opt-in, the subtraction and the in-flight
+	//     surface both see the reconciled truth in the SAME run.
+	//
+	//     Best-effort by construction: neither call throws, and every uncertainty
+	//     resolves to KEEP, so an offline or push-denied checkout degrades to the
+	//     previous behaviour.
+	//
+	//     The cwd is a WORKING CLONE, so the arbiter's main is the remote-tracking
+	//     ref `<lockRemote>/main`, which is the default. (A bare hub mirror would
+	//     need `mainRef: 'main'`; see the mirror callers in `status`/`scan`.)
+	let staleLocks: string[] = [];
+	let reconciledLocks: string[] = [];
+	// The in-flight entries, taken straight from the classification so the surface
+	// below needs no second `ls-remote` + fetch. `undefined` = not read at all.
+	let inFlightLocks: LockEntry[] | undefined;
+	if (hasLockRemote) {
+		if (options.reconcileLocks === true) {
+			// The ONLY write this resolver performs, and only when explicitly asked.
+			const swept = await reconcileTerminalItemLocks(cwd, lockRemote, env);
+			reconciledLocks = swept.released;
+			inFlightLocks = swept.stillHeld;
+			// Under an EXPLICIT drain request a refusal must be reported: the operator
+			// asked for these to go away, so silence would be a lie. (On the claim
+			// path the same errors are ignored on purpose: there the sweep is
+			// opportunistic hygiene, not something the operator asked for.)
+			for (const e of swept.errors) {
+				options.warn?.(`could not release lock '${e.entry}': ${e.message}`);
+			}
+		} else {
+			const classified = await classifyTerminalItemLocks(cwd, lockRemote, env);
+			staleLocks = classified.terminal.map((l) => l.entry);
+			inFlightLocks = classified.inFlight;
+		}
+	}
+
+	// 2b. The OTHER half of the same terminal residue: a bounced-then-rebuilt item
+	//     whose sidecar + `needsAnswers` flag were never cleared (observation
+	//     `a-rebuilt-task-leaves-its-bounce-question-asking-to-cancel-a-merged-task`).
+	//     READ-ONLY here, exactly like the lock half: `status` reports it and the
+	//     claim path drains it. Best-effort; a fault yields an empty report.
+	let staleQuestions: string[] = [];
+	let unappliedAnswers: string[] = [];
+	if (hasLockRemote && options.reconcileLocks !== true) {
+		const residue = await classifyTerminalQuestionResidue({
+			cwd,
+			arbiter: lockRemote,
+			mainRef: `${lockRemote}/main`,
+			env,
+		});
+		staleQuestions = residue.drainable.map((r) => r.item);
+		unappliedAnswers = residue.answeredHeld.map((r) => r.item);
+	} else if (hasLockRemote) {
+		// Under the explicit opt-in the question residue is DRAINED alongside the
+		// locks, through the one shared pass.
+		const drained = await reconcileTerminalQuestionResidue({
+			cwd,
+			arbiter: lockRemote,
+			mainRef: `${lockRemote}/main`,
+			env,
+			note: options.warn,
+		});
+		unappliedAnswers = drained.answeredHeld;
+		for (const e of drained.errors) {
+			options.warn?.(`could not drain questions for '${e.item}': ${e.message}`);
+		}
+	}
+
 	const heldSlugs = hasLockRemote
 		? await heldTaskSlugsStrict(cwd, lockRemote, env)
 		: new Set<string>();
@@ -307,10 +444,16 @@ export async function resolveCwdSection(
 	//     different fault models (selection fails closed; the surface degrades).
 	//     Read from the SAME coordination remote the subtraction used. A repo with no
 	//     coordination remote has no lock refs to read — empty surface.
-	if (repo !== undefined && hasLockRemote) {
-		const lockHeld = await listItemLockEntries(cwd, lockRemote, env);
-		if (lockHeld.length > 0) {
-			repo.lockHeld = lockHeld;
+	if (repo !== undefined && inFlightLocks !== undefined) {
+		// Taken STRAIGHT from the classification in 2a, so the stale ones are already
+		// excluded. This is the reporting half of the propose-lock-leak fix: a lock
+		// whose item is already at REST on `main` is finished work, NOT an in-flight
+		// hold, so it must not appear under "In progress" (the symptom being fixed:
+		// completed tasks reported in-progress for ever). It is surfaced under
+		// `staleLocks` instead. Reusing that result also avoids a second `ls-remote` +
+		// fetch and the TOCTOU window between two separate reads.
+		if (inFlightLocks.length > 0) {
+			repo.lockHeld = inFlightLocks;
 		}
 	}
 
@@ -326,6 +469,10 @@ export async function resolveCwdSection(
 		path: cwd,
 		participating: true,
 		repo,
+		staleLocks,
+		reconciledLocks,
+		staleQuestions,
+		unappliedAnswers,
 		totalItems: localReport.totalItems,
 		totalEligible: localReport.totalEligible,
 		alsoRegistered,

package/src/format.ts

@@ -199,6 +199,78 @@ export function formatCwdSection(section: CwdSection): string[] {
 			lines.push(...formatLockEntryLines(entry, '      '));
 		}
 	}
+
+	// STALE locks, finished work whose lock has not been released yet (fix for the
+	// propose-path lock leak). `complete --propose` keeps the lock held and defers
+	// its release to the PR merge, an event dorfl is never present for, so these
+	// accumulate. They are shown as their OWN block and NOT under "In progress":
+	// reporting completed work as in-progress for ever was the symptom. `status` is
+	// read-only, so it names the state and how it clears rather than clearing it.
+	const stale = section.staleLocks ?? [];
+	if (stale.length > 0) {
+		lines.push('');
+		lines.push(
+			`    Completed, lock not yet released (${stale.length}; item is at rest ` +
+				'on main, so this is NOT in flight):',
+		);
+		for (const entry of stale) {
+			lines.push(`      ${entry}`);
+		}
+		lines.push(
+			'      These clear automatically on the next claim. To drain them now: ' +
+				'`dorfl status --reconcile-locks`.',
+		);
+	}
+
+	// STRANDED QUESTION STATE on terminal items: a bounce wrote a sidecar +
+	// `needsAnswers:true` atomically, the human re-dispatched instead of answering,
+	// the rebuild succeeded, and neither half was ever cleared. The flag is the
+	// harmful part: it is a gate left armed over shipped work, which is why this is
+	// surfaced rather than left to be discovered in the questions folder.
+	const staleQuestions = section.staleQuestions ?? [];
+	if (staleQuestions.length > 0) {
+		lines.push('');
+		lines.push(
+			`    Completed, question state not yet cleared (${staleQuestions.length}; ` +
+				'stale bounce sidecar and/or a needsAnswers gate on a finished item):',
+		);
+		for (const item of staleQuestions) {
+			lines.push(`      ${item}`);
+		}
+		lines.push(
+			'      These clear automatically on the next claim. To drain them now: ' +
+				'`dorfl status --reconcile-locks`.',
+		);
+	}
+
+	// A human's ANSWER that nothing ever applied. Never auto-drained, because the
+	// prose is data the tool did not author; it needs a human, so it is named.
+	const unapplied = section.unappliedAnswers ?? [];
+	if (unapplied.length > 0) {
+		lines.push('');
+		lines.push(
+			`    Answered but never applied (${unapplied.length}; the sidecar carries ` +
+				'your answer and the item is already finished, kept, never auto-deleted):',
+		);
+		for (const item of unapplied) {
+			lines.push(`      ${item}`);
+		}
+	}
+
+	// Locks this run actually RELEASED (only under the explicit
+	// `--reconcile-locks` opt-in, the one way `status` writes). Always reported,
+	// never silent.
+	const reconciled = section.reconciledLocks ?? [];
+	if (reconciled.length > 0) {
+		lines.push('');
+		lines.push(
+			`    Released ${reconciled.length} completed lock(s) (item is terminal on ` +
+				'main, the propose PR merged out-of-band):',
+		);
+		for (const entry of reconciled) {
+			lines.push(`      ${entry}`);
+		}
+	}
 	lines.push('');
 	lines.push(
 		`  Local total: ${total} ${pluralItems(total)} ` +

package/src/index.ts

@@ -341,6 +341,8 @@ export {
 	releaseHeldItemLock,
 	readItemLock,
 	reconcileItemLockAgainstMain,
+	reconcileTerminalItemLocks,
+	classifyTerminalItemLocks,
 	classifyItemLockAgainstMain,
 	reportItemLocks,
 	formatItemLockReport,