dorfl 0.13.2 → 0.13.4

package/src/reconcile-terminal.ts

@@ -0,0 +1,180 @@
+import {
+	classifyTerminalItemLocks,
+	reconcileTerminalItemLocks,
+	refreshMainRef,
+	type TerminalLockClassification,
+	type TerminalReconcileReport,
+} from './item-lock.js';
+import {
+	classifyTerminalQuestionResidue,
+	reconcileTerminalQuestionResidue,
+	type TerminalQuestionReport,
+	type TerminalQuestionDrainResult,
+} from './needs-attention.js';
+
+/**
+ * **The ONE terminal-state reconciliation pass.**
+ *
+ * Two defects of the same shape motivated this, and they are deliberately fixed
+ * by ONE mechanism rather than two:
+ *
+ *   1. **The propose-path lock leak.** `complete --propose` keeps the per-item
+ *      lock held across the open PR and defers its release to the merge, so every
+ *      completed item leaked its `refs/dorfl/lock/<entry>` ref and reported
+ *      in-progress for ever.
+ *   2. **The stranded question state.** A bounce atomically writes a sidecar plus
+ *      `needsAnswers:true`; if the human disagrees, re-dispatches, and the rebuild
+ *      SUCCEEDS, neither half is ever cleared. The item comes to rest in
+ *      `tasks/done/` still carrying a question asking whether to CANCEL it, and a
+ *      `needsAnswers` gate left armed over shipped work.
+ *
+ * They share a cause, a moment, and a blind spot. The cause is that both are
+ * cleared by a step that only runs on a path the item did not take. The moment
+ * both become moot is exactly the same one: the DONE-MOVE landing on the
+ * arbiter's `main`. And the blind spot is that each is detectable only from a
+ * loop the manual path never enters (`gc --ledger --reap-stale-locks` for the
+ * lock, the `advance` tick's `invariant-violation` classifier for the questions),
+ * while a human driving `do` and merging a PR enters neither.
+ *
+ * Dorfl cannot hook the merge: nobody runs a dorfl process when a human clicks
+ * merge on GitHub, and there is no daemon. So the shape has to be RECONCILE
+ * AGAINST `main` rather than react to the merge. The merge event is unobservable;
+ * its consequence on `main` is durable, so a late pass converges just as well as
+ * a timely one.
+ *
+ * ONE DISCRIMINATOR governs both halves: the item's POSITION on `<arbiter>/main`.
+ * Not a branch, not a PR, not the holder, not age, not the flag/sidecar
+ * disagreement on its own. An item that has reached a terminal resting folder is
+ * finished and cannot need either piece of state; an item resting anywhere else
+ * keeps everything it has, untouched. Both sub-passes resolve every uncertainty
+ * towards LEAVING STATE ALONE, because the failure modes are asymmetric and both
+ * severe: releasing a live lock would let two claimants build one item, and
+ * clearing a live `needsAnswers` would disarm a gate and hand gated work to
+ * agents.
+ *
+ * WHERE THIS RUNS. On the CLAIM path, which already writes to the arbiter and
+ * already runs on every unit of work, so the residue drains as a side effect of
+ * ordinary use. The read-only surfaces (`status`, `scan`) use the CLASSIFY twin
+ * ({@link classifyTerminalState}) to REPORT the same residue without writing, and
+ * perform this pass only under an explicit `--reconcile-locks`. Putting the
+ * automatic clear on a write path rather than behind a flag on a read command is
+ * what makes the fix real: an offer nobody is routed to is what let both defects
+ * accumulate in the first place.
+ */
+export interface TerminalStateReport {
+	locks: TerminalReconcileReport;
+	questions: TerminalQuestionDrainResult;
+}
+
+/** The read-only twin of {@link TerminalStateReport}: what a reconcile WOULD do. */
+export interface TerminalStateClassification {
+	locks: TerminalLockClassification;
+	questions: TerminalQuestionReport;
+}
+
+export interface TerminalStateOptions {
+	cwd: string;
+	arbiter?: string;
+	env?: NodeJS.ProcessEnv;
+	/**
+	 * The ref holding the arbiter's authoritative `main`, for the READ side.
+	 * Defaults to `<arbiter>/main` (the WORKING-CLONE shape); a BARE HUB MIRROR has
+	 * no `refs/remotes/*` namespace at all and must pass `'main'`.
+	 *
+	 * NOTE: this governs the CLASSIFY/read side only. The question-drain's WRITE
+	 * side publishes through `runTreelessLedgerMove`, which resolves its own CAS
+	 * base from `<arbiter>/main`, so {@link reconcileTerminalState} is supported
+	 * from a WORKING CLONE only. Classification is safe from either shape.
+	 */
+	mainRef?: string;
+	note?: (message: string) => void;
+}
+
+/**
+ * READ-ONLY: classify every piece of terminal-state residue on the arbiter (stale
+ * locks + stranded question state) without touching anything. This is what the
+ * read commands render, so finished work stops being reported as in-flight or as
+ * blocked on open questions.
+ */
+export async function classifyTerminalState(
+	opts: TerminalStateOptions,
+): Promise<TerminalStateClassification> {
+	const arbiter = opts.arbiter ?? 'origin';
+	const mainRef = opts.mainRef ?? `${arbiter}/main`;
+	const locks = await classifyTerminalItemLocks(opts.cwd, arbiter, opts.env, {
+		mainRef,
+	});
+	const questions = await classifyTerminalQuestionResidue({
+		cwd: opts.cwd,
+		arbiter,
+		mainRef,
+		env: opts.env,
+	});
+	return {locks, questions};
+}
+
+/**
+ * WRITE: settle both halves of an item's terminal residue in one pass. The lock
+ * sub-pass deletes stale lock refs; the question sub-pass publishes ONE tree-less
+ * commit to `main` removing stale sidecars and clearing stale `needsAnswers`
+ * flags.
+ *
+ * Order matters only for reporting, not correctness: the two touch disjoint state
+ * (a hidden ref namespace vs `main`'s tree) and neither depends on the other. It
+ * never throws; each sub-pass degrades independently, so a failure to reach the
+ * lock refs does not prevent the question drain, or vice versa.
+ */
+export async function reconcileTerminalState(
+	opts: TerminalStateOptions,
+): Promise<TerminalStateReport> {
+	const arbiter = opts.arbiter ?? 'origin';
+	const mainRef = opts.mainRef ?? `${arbiter}/main`;
+	// ONE refresh of `main` for the WHOLE pass. Both sub-passes read the same
+	// durable record, so fetching it twice per claim is pure waste on a hot path.
+	// A failed refresh is not fatal: each sub-pass independently resolves every
+	// uncertainty towards leaving state alone.
+	await refreshMainRef(mainRef, arbiter, opts.cwd, opts.env);
+	// Each sub-pass is independently guarded so one cannot take the other down,
+	// and so a caller running this as opportunistic hygiene (the claim path) is
+	// never failed by unrelated residue. Both are documented as never throwing;
+	// this is the belt that makes that true even if a callee regresses.
+	let locks: TerminalReconcileReport = {
+		released: [],
+		kept: [],
+		stillHeld: [],
+		errors: [],
+	};
+	try {
+		locks = await reconcileTerminalItemLocks(opts.cwd, arbiter, opts.env, {
+			mainRef,
+			mainAlreadyFresh: true,
+		});
+	} catch (err) {
+		locks.errors.push({
+			entry: '(locks)',
+			message: err instanceof Error ? err.message : String(err),
+		});
+	}
+	let questions: TerminalQuestionDrainResult = {
+		drained: [],
+		unflagged: [],
+		answeredHeld: [],
+		errors: [],
+	};
+	try {
+		questions = await reconcileTerminalQuestionResidue({
+			cwd: opts.cwd,
+			arbiter,
+			mainRef,
+			env: opts.env,
+			mainAlreadyFresh: true,
+			note: opts.note,
+		});
+	} catch (err) {
+		questions.errors.push({
+			item: '(questions)',
+			message: err instanceof Error ? err.message : String(err),
+		});
+	}
+	return {locks, questions};
+}

package/src/scan.ts

@@ -27,6 +27,8 @@ import type {LifecyclePoolGates} from './lifecycle-pools.js';
 import {
 	heldTaskSlugs,
 	listItemLockEntries,
+	classifyTerminalItemLocks,
+	reconcileTerminalItemLocks,
 	type LockEntry,
 } from './item-lock.js';
 
@@ -203,6 +205,15 @@ export interface RepoReport {
 	 * {@link listItemLockEntries}). Optional so older literals stay valid.
 	 */
 	lockHeld?: LockEntry[];
+	/**
+	 * Lock `<entry>` names whose item is already at REST in a terminal folder on
+	 * this repo's `main`: finished work (typically a merged propose PR) whose lock
+	 * has not been released yet. Reported SEPARATELY from {@link lockHeld}, and
+	 * deliberately excluded from it, so completed work never reads as in-progress.
+	 * `scan` is read-only and RELEASES nothing; these drain on the next claim, or
+	 * under `scan --reconcile-locks`.
+	 */
+	staleLocks?: string[];
 }
 
 /** The full cross-repo scan result. */
@@ -406,6 +417,14 @@ export async function scan(
 	config: Config,
 	options: {
 		warn?: (message: string) => void;
+		/**
+		 * OPT-IN WRITE (`scan --reconcile-locks`). Omitted/`false` (the DEFAULT) keeps
+		 * `scan` strictly READ-ONLY: stale terminal locks are classified and excluded
+		 * from the in-flight surface, but nothing on any arbiter is touched. `true`
+		 * additionally RELEASES them. Routine convergence does not need this, the
+		 * claim path sweeps on every unit of work.
+		 */
+		reconcileLocks?: boolean;
 		env?: NodeJS.ProcessEnv;
 		/**
 		 * The per-machine {@link ConfigOverrideMap} (from `loadConfigOverride`),
@@ -448,6 +467,65 @@ export async function scan(
 		// Held-slug subtraction: a bare hub mirror's arbiter is its `origin`. Reads
 		// the lock refs from the mirror's origin; non-fatal (empty set on any fault),
 		// so the read-only scan degrades gracefully exactly as its config reads do.
+		// CLASSIFY the mirror's held locks against its `main` (fix for the propose-path
+		// lock leak; observation
+		// `every-completed-task-leaves-its-lock-ref-reporting-in-progress`). A
+		// `complete --propose` KEEPS its per-item lock held across the open PR and
+		// defers the release to the PR merge, an event NO dorfl process is present
+		// for (there is no merge hook and no daemon), so the release never fired and
+		// every completed item stayed locked and reported in-progress for ever.
+		//
+		// `scan` is READ-ONLY (it says so in its own description) and stays that way:
+		// we only CLASSIFY here, so a lock whose item has come to REST in a terminal
+		// folder on `main` is reported as STALE instead of being listed as an
+		// in-flight hold. The refs are drained by the paths that already write on
+		// every unit of work (the claim path). Best-effort and never throws: any
+		// fault treats every lock as HELD, so `scan` degrades to its previous
+		// behaviour.
+		//
+		// Under the explicit `--reconcile-locks` opt-in, the ONE way `scan` writes
+		// the same classification is applied instead of merely reported.
+		//
+		// A hub mirror is a BARE clone with no `refs/remotes/*` namespace, so its
+		// copy of the arbiter's main is the plain `main` ref (the SAME ref
+		// `lintRefLedger` below reads). Passing the default `origin/main` would fail
+		// EVERY probe with `invalid object name` and silently classify every lock as
+		// in-flight, making this a permanent no-op.
+		const MIRROR_MAIN = {mainRef: 'main'};
+		let staleLockEntries: string[];
+		let lockHeld: LockEntry[];
+		if (options.reconcileLocks === true) {
+			const swept = await reconcileTerminalItemLocks(
+				mirror.path,
+				'origin',
+				options.env,
+				MIRROR_MAIN,
+			);
+			if (swept.released.length > 0) {
+				options.warn?.(
+					`${mirror.path}: released ${swept.released.length} stale per-item ` +
+						'lock(s) whose item is terminal on main (the work landed; a ' +
+						`propose PR merged out-of-band): ${swept.released.join(', ')}`,
+				);
+			}
+			// Under an EXPLICIT drain request, a refusal must be reported.
+			for (const e of swept.errors) {
+				options.warn?.(
+					`${mirror.path}: could not release '${e.entry}': ${e.message}`,
+				);
+			}
+			staleLockEntries = [];
+			lockHeld = swept.stillHeld;
+		} else {
+			const classified = await classifyTerminalItemLocks(
+				mirror.path,
+				'origin',
+				options.env,
+				MIRROR_MAIN,
+			);
+			staleLockEntries = classified.terminal.map((l) => l.entry);
+			lockHeld = classified.inFlight;
+		}
 		const heldSlugs = await heldTaskSlugs(mirror.path, 'origin', options.env);
 		// The PER-ITEM LOCK in-flight view (spec US #8; task
 		// `needs-attention-as-stuck-lock-state`): ADDITIONALLY read the full held
@@ -457,11 +535,9 @@ export async function scan(
 		// best-effort (empty list on any fault), so the read-only scan degrades
 		// gracefully. This is a SURFACE only — eligibility/selection stay offline on
 		// `main` (the subtraction above), not gated on this view.
-		const lockHeld = await listItemLockEntries(
-			mirror.path,
-			'origin',
-			options.env,
-		);
+		// `lockHeld` comes STRAIGHT from the classification above, so the stale ones
+		// are already excluded (finished work is not an in-flight hold) and we avoid a
+		// second `ls-remote` + fetch per mirror.
 		// Spec pool — the TASKABLE-SPEC companion of the task pool above
 		// (`ci-propose-matrix-must-enumerate-sliceable-prds-not-only-slices`). Resolve
 		// `autoTask` PER REPO from the mirror's COMMITTED `dorfl.json`
@@ -533,6 +609,7 @@ export async function scan(
 			lifecycle,
 			ledgerDuplicates,
 			lockHeld,
+			staleLocks: staleLockEntries,
 		});
 	}
 

package/src/status.ts

@@ -6,7 +6,12 @@ import './pi-harness.js';
 import {type JobState} from './workspace.js';
 import {fetchMirrorMainOrWarn} from './repo-mirror.js';
 import {formatArbiterStatus, type ArbiterStatusReport} from './arbiter.js';
-import {listItemLockEntries, type LockEntry} from './item-lock.js';
+import {
+	listItemLockEntries,
+	classifyTerminalItemLocks,
+	reconcileTerminalItemLocks,
+	type LockEntry,
+} from './item-lock.js';
 import {formatCwdSection, formatLockEntryLines} from './format.js';
 import type {CwdSection} from './cwd-section.js';
 import {
@@ -96,6 +101,16 @@ export interface RepoLockEntries {
 	entries: LockEntry[];
 }
 
+/** One repo's STALE per-item locks: entries whose item has already come to rest
+ * in a terminal folder on that repo's `main`, so the hold is finished work
+ * awaiting release rather than an in-flight claim. */
+export interface RepoStaleLocks {
+	/** The repo path whose lock refs were classified (a hub-mirror path). */
+	repoPath: string;
+	/** The stale lock `<entry>` names, sorted. */
+	entries: string[];
+}
+
 /** One repo's one-slug-one-folder LINT result, surfaced for the dashboard. */
 export interface RepoLedgerDuplicates {
 	/** The repo path whose `work/` ledger was linted (a hub-mirror path). */
@@ -123,6 +138,16 @@ export interface StatusReport {
 	 * populates it (possibly empty).
 	 */
 	lockHeld?: RepoLockEntries[];
+	/**
+	 * Per registered hub mirror, the lock `<entry>` names whose item is already at
+	 * REST in a terminal folder on that mirror's `main`, finished work (typically
+	 * a merged propose PR) whose lock has not been released yet. Reported
+	 * SEPARATELY from {@link StatusReport.lockHeld}, and deliberately excluded from
+	 * it, so completed work never reads as in-progress (the symptom of the
+	 * propose-path lock leak). `status` RELEASES nothing by default, it is
+	 * read-only; these drain on the next claim, or under `--reconcile-locks`.
+	 */
+	staleLocks?: RepoStaleLocks[];
 	/**
 	 * The one-slug-one-folder LINT (spec `ledger-integrity` story 3): per registered
 	 * hub mirror, any slug present in MORE THAN ONE `work/` status folder (a corrupt
@@ -170,6 +195,15 @@ export interface StatusOptions {
 	 * Omitted ⇒ only the job worktrees are reported.
 	 */
 	mirrorPaths?: string[];
+	/**
+	 * OPT-IN WRITE (`status --reconcile-locks`). `false`/omitted (the DEFAULT)
+	 * keeps `status` strictly READ-ONLY: stale locks are classified and REPORTED
+	 * via {@link StatusReport.staleLocks} and nothing on any arbiter is touched.
+	 * `true` additionally RELEASES them. 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 (ADR §5/§6): when a mirror's `main`
 	 * cannot be fetched, `status` warns through this and reads that mirror's
@@ -229,26 +263,86 @@ export async function status(options: StatusOptions): Promise<StatusReport> {
 	// held (`active` = in-progress) AND stuck (`needs-attention`) entries + their
 	// reasons/questions.
 	const lockHeld: RepoLockEntries[] = [];
+	const staleLocks: RepoStaleLocks[] = [];
 	const ledgerDuplicates: RepoLedgerDuplicates[] = [];
 	for (const mirrorPath of options.mirrorPaths ?? []) {
 		// Fetch-first (ADR §5/§6): refresh this mirror's `main` so the duplicate lint
 		// reflects the remote truth. Never fatal — a failed fetch WARNS and falls back
 		// to the mirror's last-known `main`.
 		fetchMirrorMainOrWarn({mirrorPath, warn: options.warn, env: options.env});
+		// CLASSIFY the mirror's held locks against its `main` (fix for the propose-path
+		// lock leak; observation
+		// `every-completed-task-leaves-its-lock-ref-reporting-in-progress`). A
+		// `complete --propose` KEEPS its lock held across the open PR and defers the
+		// release to the merge, an event no dorfl process is present for (no hook, no
+		// daemon), so the release never fired and every completed item reported
+		// in-progress for ever.
+		//
+		// `status` is READ-ONLY and stays that way: by DEFAULT we only classify, so a
+		// lock whose item has come to REST in a terminal folder on the mirror's `main`
+		// is reported as STALE rather than listed in-flight. The refs themselves are
+		// drained by the paths that already write on every unit of work (the claim
+		// path), or here under the explicit `--reconcile-locks` opt-in. An item on an
+		// OPEN PR (still in the pool on `main`) stays in-flight either way.
+		// Best-effort and never throws, any fault treats the lock as HELD.
+		//
+		// A hub mirror is a BARE clone with no `refs/remotes/*` namespace, so its copy
+		// of the arbiter's main is the plain `main` ref (the SAME ref
+		// `fetchMirrorMainOrWarn` above and `lintRefLedger` below read). Passing the
+		// default `origin/main` here would fail EVERY probe with `invalid object name`
+		// and silently classify every lock as in-flight.
+		const MIRROR_MAIN = {mainRef: 'main'};
+		let staleEntries: string[] = [];
+		let entries: LockEntry[];
+		if (options.reconcileLocks === true) {
+			const reconciled = await reconcileTerminalItemLocks(
+				mirrorPath,
+				'origin',
+				options.env,
+				MIRROR_MAIN,
+			);
+			if (reconciled.released.length > 0) {
+				options.warn?.(
+					`${mirrorPath}: released ${reconciled.released.length} stale per-item ` +
+						'lock(s) whose item is terminal on main (work landed; the ' +
+						`propose PR merged out-of-band): ${reconciled.released.join(', ')}`,
+				);
+			}
+			// Under an EXPLICIT drain request a refusal must be reported: the operator
+			// asked for these to go away, so silence would be a lie.
+			for (const e of reconciled.errors) {
+				options.warn?.(
+					`${mirrorPath}: could not release '${e.entry}': ${e.message}`,
+				);
+			}
+			entries = reconciled.stillHeld;
+		} else {
+			const classified = await classifyTerminalItemLocks(
+				mirrorPath,
+				'origin',
+				options.env,
+				MIRROR_MAIN,
+			);
+			staleEntries = classified.terminal.map((l) => l.entry);
+			entries = classified.inFlight;
+		}
 		// The PER-ITEM LOCK in-flight view (spec US #8): read the mirror's lock refs to
 		// surface held (`active` = in-progress) and stuck (`needs-attention`) entries +
 		// reasons/questions. A bare hub mirror's arbiter is its `origin` (the SAME
 		// handle the `scan` held-slug subtraction reads). Best-effort: a fetch/read
 		// fault yields an EMPTY list (see {@link listItemLockEntries}), so this
 		// read-only view degrades to "no in-flight locks" rather than erroring.
-		const entries = await listItemLockEntries(
-			mirrorPath,
-			'origin',
-			options.env,
-		);
+		// `entries` comes STRAIGHT from the classification above (its `inFlight`
+		// partition, or `stillHeld` after a sweep), so the stale ones are already
+		// excluded: finished work is not an in-flight hold, and listing it as one is
+		// the exact symptom being fixed. Reusing that result also avoids a SECOND
+		// `ls-remote` + fetch per mirror, and the TOCTOU window between two reads.
 		if (entries.length > 0) {
 			lockHeld.push({repoPath: mirrorPath, entries});
 		}
+		if (staleEntries.length > 0) {
+			staleLocks.push({repoPath: mirrorPath, entries: staleEntries});
+		}
 		// The one-slug-one-folder LINT (spec story 3): derive any slug residing in >1
 		// status folder from the SAME freshly-fetched `main` ref, surfaced LOUDLY.
 		const dups = lintRefLedger('main', mirrorPath, options.env);
@@ -257,12 +351,14 @@ export async function status(options: StatusOptions): Promise<StatusReport> {
 		}
 	}
 	lockHeld.sort((a, b) => a.repoPath.localeCompare(b.repoPath));
+	staleLocks.sort((a, b) => a.repoPath.localeCompare(b.repoPath));
 	ledgerDuplicates.sort((a, b) => a.repoPath.localeCompare(b.repoPath));
 
 	return {
 		active,
 		attention,
 		lockHeld,
+		staleLocks,
 		ledgerDuplicates,
 		...(options.arbiter ? {arbiter: options.arbiter} : {}),
 		...(options.cwd ? {cwd: options.cwd} : {}),
@@ -319,6 +415,8 @@ export function formatStatus(report: StatusReport): string {
 
 	const lockHeld = report.lockHeld ?? [];
 	const lockCount = lockHeld.reduce((sum, r) => sum + r.entries.length, 0);
+	const staleLocks = report.staleLocks ?? [];
+	const staleCount = staleLocks.reduce((sum, r) => sum + r.entries.length, 0);
 	const ledgerDuplicates = report.ledgerDuplicates ?? [];
 	const dupCount = ledgerDuplicates.reduce(
 		(sum, r) => sum + r.duplicates.length,
@@ -328,6 +426,10 @@ export function formatStatus(report: StatusReport): string {
 		report.active.length === 0 &&
 		report.attention.length === 0 &&
 		lockCount === 0 &&
+		// A repo whose ONLY locks are stale must not print "the work area is empty":
+		// that would turn the old "wrongly shown as in-progress" bug into a worse
+		// "not shown at all" one.
+		staleCount === 0 &&
 		dupCount === 0 &&
 		report.arbiter === undefined &&
 		cwdLines.length === 0
@@ -377,6 +479,29 @@ export function formatStatus(report: StatusReport): string {
 		}
 	}
 
+	// STALE locks: finished work whose lock has not been released yet (the
+	// propose-path lock leak). Rendered as its OWN block and deliberately NOT under
+	// "In-flight locks" above, because 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.
+	if (staleCount > 0) {
+		lines.push('');
+		lines.push(
+			`Completed, lock not yet released (${staleCount}; the item is at rest on ` +
+				'main, so this is NOT in flight):',
+		);
+		for (const repo of staleLocks) {
+			lines.push(`  ${repo.repoPath}`);
+			for (const entry of repo.entries) {
+				lines.push(`    ${entry}`);
+			}
+		}
+		lines.push(
+			'  These clear automatically on the next claim. To drain them now: ' +
+				'`dorfl status --reconcile-locks`.',
+		);
+	}
+
 	// The one-slug-one-folder LINT (spec `ledger-integrity` story 3): WARN LOUDLY
 	// about every slug residing in >1 status folder of a registered mirror's ledger
 	// (a corrupt ledger — never a silent pass). A human must resolve each.