dorfl 0.0.0 → 0.1.0

package/src/ledger-write.ts

@@ -0,0 +1,865 @@
+import {randomUUID} from 'node:crypto';
+import {runAsync, type RunResult} from './git.js';
+import {
+	Integrator,
+	type IntegrateResult,
+	type ReviewProvider,
+} from './integrator.js';
+import type {IntegrationMode} from './config.js';
+import {
+	routeToNeedsAttention,
+	returnToBacklog,
+	type RouteToNeedsAttentionOptions,
+	type RouteToNeedsAttentionResult,
+	type ReturnToBacklogOptions,
+	type ReturnToBacklogResult,
+	type SurfaceToNeedsAttentionOptions,
+	type SurfaceToNeedsAttentionResult,
+	type BranchPushOutcome,
+} from './needs-attention.js';
+import {
+	markStuckItemLock,
+	resumeItemLock,
+	type TransitionOutcome,
+} from './item-lock.js';
+
+/**
+ * The **write half** of the ledger-transition seam (ADR
+ * `docs/adr/claim-ledger-vs-protected-main.md`, status: accepted — the "Write
+ * seam"). ONE entry point — "apply this `work/` transition" — that every
+ * transition (claim / complete / needs-attention) routes through, so a FUTURE
+ * strategy could publish a transition elsewhere (e.g. a dedicated `main`-free
+ * ledger ref) without the transition call sites learning a new mechanism.
+ *
+ * It is a PURE REFACTOR: there is exactly ONE strategy ({@link
+ * currentLedgerWrite}) and it does EXACTLY what the code did before — it
+ * CAS-publishes the prepared transition commit to the arbiter's `main` with
+ * `--force-with-lease` and then verifies `<arbiter>/main` is now that commit. No
+ * mode, no config, no `ledgerMode`, no new ref.
+ *
+ * The seam stays at the SEMANTIC level: the caller hands the seam a *prepared*
+ * transition (a local branch carrying the commit, the base the ledger must still
+ * be at for the CAS, and the commit it expects to land) plus the transition
+ * KIND, and asks the seam to publish it. The public input is storage-agnostic —
+ * it does NOT name `main`; that `main` is the publish/verify target is an
+ * implementation detail of the sole strategy below.
+ *
+ * This task routes the CLAIM transition through the seam (see `claim-cas.ts`).
+ * The `complete` and `needs-attention` kinds are named here so the companion
+ * tasks route through the SAME entry point; they are not yet wired.
+ *
+ * The NEEDS-ATTENTION transition is wired here too: the abort paths in
+ * `complete.ts` (red gate, rebase conflict), the runner's stuck routing in
+ * `run.ts`, and the human `return` command all drive the
+ * `* → needs-attention` move (and its `needs-attention → backlog` re-queue)
+ * through this SAME seam rather than calling the move helpers directly. The
+ * sole strategy delegates to the folder-native mechanism in
+ * `needs-attention.ts` UNCHANGED (reason-in-the-body — WORK-CONTRACT rule 3,
+ * bounce from in-progress OR done, ONE atomic commit, optional branch push); the
+ * seam only relocates WHERE the "apply the needs-attention transition" call is
+ * expressed, so the later cherry-pick-to-`main` surfacing is built AGAINST the
+ * seam, not bolted onto the move code.
+ */
+
+/**
+ * The `work/` lifecycle transitions the write seam can apply.
+ *
+ * `tasking` is the legacy tasking-lock MARKER transition. It is now VESTIGIAL: the
+ * capstone cut-over (task
+ * `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`) retired the
+ * `git mv work/prd/<slug>.md → work/tasking/<slug>.md` marker (the historical
+ * marker paths), so the tasking lock
+ * is the unified per-item lock ref (`tasking-lock.ts`) and no longer routes through
+ * {@link applyTransition} with this kind. The member is kept so the strategy
+ * interface and any historical reference stay valid; nothing publishes it.
+ *
+ * `advancing` is the kind {@link createItemThroughCas} (`advancing-lock.ts`) uses
+ * to publish a NEW `work/` item (the triage observation→promote path) through the
+ * SAME CAS the `claim` transition uses, keyed on the new item's identity (its
+ * path). The advancing-lock BORROW itself no longer rides this kind: the
+ * `work/advancing/<entry>.md` presence-marker is retired (the borrow is the unified
+ * `action: advance` lock ref now). So `advancing` survives only as the create-item
+ * CAS kind.
+ */
+export type LedgerTransitionKind =
+	| 'claim'
+	| 'complete'
+	| 'needs-attention'
+	| 'requeue'
+	| 'tasking'
+	| 'advancing'
+	/**
+	 * The **promote** transition (prd `staging-pool-position-gate-and-trust-model`,
+	 * task `pre-backlog-staging-folder-and-promote-step-a`): move a STAGED task
+	 * `work/pre-backlog/<slug>.md → work/backlog/<slug>.md` to enter the
+	 * agent-eligible pool. A durable `main` move, the same category as `requeue`
+	 * (tree-less CAS via {@link applyTransition}). RUNNER/human-owned — no
+	 * agent-facing path performs it (governing ADR
+	 * `placement-is-runner-deterministic-humanonly-is-agent-judgement`).
+	 */
+	| 'promote';
+
+/**
+ * A *prepared* COMPLETE transition the caller asks the seam to publish: a
+ * finished work branch whose code should be integrated back to the arbiter. Like
+ * {@link ApplyTransitionInput} it is storage-agnostic — it names the work branch
+ * + the integration MODE + the review provider, NOT *where* the integration
+ * lands (the sole strategy decides that; today `merge` ff's to the arbiter's
+ * `main`, `propose` pushes the branch + requests review). The caller has already
+ * done the gate / done-move / commit / rebase-onto-arbiter — the seam only
+ * APPLIES the integration of that prepared branch.
+ */
+export interface ApplyCompleteTransitionInput {
+	/** Name of the arbiter git remote the integration is published to. */
+	arbiter: string;
+	/** The prepared (gated, committed, rebased) work branch to integrate. */
+	branch: string;
+	/** Integration mode: `merge` (ff to the ledger) or `propose` (push + review). */
+	mode: IntegrationMode;
+	/** The review-request provider (propose mode); push-only `none` otherwise. */
+	provider: ReviewProvider;
+	/**
+	 * **The PR-INTENT axis** (config `noPR`, ADR §6): when `true` on the propose
+	 * path, push the branch but SKIP the review request (the explicit suppress-PR
+	 * intent). Threaded to {@link Integrator.integrate}. Ignored in `merge` mode.
+	 */
+	noPR?: boolean;
+	/**
+	 * Optional single-line review-request TITLE (propose mode), threaded straight
+	 * to the provider. Absent ⇒ the provider's `--fill` default (no regression).
+	 */
+	title?: string;
+	/**
+	 * Optional review-request BODY (propose mode) — advisory prose, gates nothing —
+	 * threaded straight to the provider. Absent ⇒ the provider's `--fill` default.
+	 */
+	body?: string;
+	/**
+	 * **Reap the remote head branch inline after a merge lands** (the merged-branch
+	 * hygiene task's part (b)). When `true` on the `merge` path, delete the remote
+	 * `work/<slug>` head AFTER the work landed on `main` (provably merged, so
+	 * ancestor-safe; idempotent no-op when no remote head exists). Threaded straight
+	 * to {@link Integrator.integrate}. Ignored in `propose` mode (the branch is the
+	 * review surface, reaped later by `gc --remote-branches`).
+	 */
+	deleteMergedHead?: boolean;
+	/** Working clone/worktree the integration runs in. */
+	cwd: string;
+	/** Environment for child git processes. */
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * The outcome of asking the seam to apply (publish) a prepared COMPLETE
+ * transition. It is exactly the integration result the {@link Integrator}
+ * produces — the seam adds NO interpretation, it only relocates WHERE the
+ * "apply the complete transition" call is expressed.
+ */
+export type ApplyCompleteTransitionResult = IntegrateResult;
+
+/**
+ * A *prepared* NEEDS-ATTENTION transition the caller asks the seam to apply: a
+ * stuck claimed item to bounce to `work/needs-attention/` with its reason. Like
+ * the other inputs it is storage-agnostic — it names the slug, the reason prose,
+ * any surfaced questions, and an OPTIONAL arbiter to also push the branch to,
+ * NOT *where* the move commits/publishes (the sole strategy decides that: a
+ * `git mv` from whichever of in-progress/ or done/ holds the item, the
+ * reason-in-the-body, the ONE atomic commit, the optional branch push). This
+ * mirrors {@link RouteToNeedsAttentionOptions} so the move mechanism is unchanged.
+ */
+export type ApplyNeedsAttentionTransitionInput = RouteToNeedsAttentionOptions;
+
+/**
+ * The outcome of asking the seam to apply a NEEDS-ATTENTION transition — the
+ * move result the folder-native mechanism produces. The RECOVERABLE branch push
+ * outcome rides on `branchPush` (the caller reads it rather than assuming
+ * "pushed" off the local move). The OBSERVABLE half is now the per-item lock
+ * `state: stuck` amend (prd `ledger-status-per-item-lock-refs`); there is no
+ * separate on-`main` surface outcome to report.
+ */
+export type ApplyNeedsAttentionTransitionResult = RouteToNeedsAttentionResult;
+
+/**
+ * A *prepared* RETURN-TO-BACKLOG transition: re-queue a STUCK item so it can be
+ * re-claimed — recovered from EITHER `needs-attention/` (the resolved-surface
+ * path) OR `in-progress/` (a claim that never surfaced), the slug's actual
+ * current folder resolved on the arbiter and moved to `backlog/`.
+ * Storage-agnostic, mirroring {@link ReturnToBacklogOptions}.
+ */
+export type ApplyReturnToBacklogTransitionInput = ReturnToBacklogOptions;
+
+/**
+ * The outcome of asking the seam to apply a RETURN-TO-BACKLOG transition. It is
+ * a Promise: like `claim`, the tree-less strategy fetches + CAS-pushes to the
+ * arbiter (async).
+ */
+export type ApplyReturnToBacklogTransitionResult =
+	Promise<ReturnToBacklogResult>;
+
+/**
+ * A *prepared* TREE-LESS NEEDS-ATTENTION (surface) transition: surface a stuck
+ * AFTER-COMMIT, LEDGER-ONLY item (`in-progress/ → needs-attention/`, with the
+ * reason in the body) WITHOUT a checkout — the SURFACE-direction sibling of the
+ * tree-less requeue, sharing its exact mechanism. The work is ALREADY committed
+ * on the kept `work/<slug>` branch (intact on the arbiter, recoverable), so the
+ * surface is purely the one-file `.md` move + reason — no `pushBranch`, no
+ * worktree. Storage-agnostic, mirroring {@link SurfaceToNeedsAttentionOptions}.
+ * NOT for the wip-save / gate-failed / agent-failed surfaces (which may carry
+ * uncommitted work — those keep {@link applyNeedsAttentionTransition}, the
+ * cwd-bound path that can commit wip first).
+ */
+export type ApplyTreelessNeedsAttentionTransitionInput =
+	SurfaceToNeedsAttentionOptions;
+
+/**
+ * The outcome of asking the seam to apply a TREE-LESS NEEDS-ATTENTION (surface)
+ * transition. A Promise: like `requeue`/`claim`, the tree-less strategy fetches +
+ * CAS-pushes to the arbiter (async).
+ */
+export type ApplyTreelessNeedsAttentionTransitionResult =
+	Promise<SurfaceToNeedsAttentionResult>;
+
+/**
+ * A *prepared* RESOLVE-NEEDS-ATTENTION transition: a human is picking up a stuck
+ * item, so the seam must **clear the stuck state** and restore it to `active`.
+ * Storage-agnostic — it names the slug + the working clone (and an OPTIONAL
+ * arbiter to amend the lock on), NOT *where* the stuck state lives. The sole
+ * strategy clears it by amending the per-item lock `stuck → active` on the
+ * arbiter (task `cutover-needs-attention-becomes-lock-stuck-recovery-surface`).
+ */
+export interface ApplyResolveNeedsAttentionTransitionInput {
+	/** The working clone the `work/` tree lives in. */
+	cwd: string;
+	/** The slug of the stuck item to resolve back to active. */
+	slug: string;
+	/**
+	 * The arbiter remote whose lock ref to amend (`stuck → active`). Omitted ⇒ a
+	 * recorded no-op success (no lock ref to amend; the human-local face).
+	 * Storage-agnostic: it names the remote, not `main`.
+	 */
+	arbiter?: string;
+	/** Environment for child git processes. */
+	env?: NodeJS.ProcessEnv;
+	/** Sink for human-readable progress notes. */
+	note?: (message: string) => void;
+}
+
+/** The outcome of asking the seam to apply a RESOLVE-NEEDS-ATTENTION transition. */
+export interface ApplyResolveNeedsAttentionTransitionResult {
+	/** True iff the lock was amended back to active (or the no-arbiter no-op). */
+	moved: boolean;
+	/** When NOT moved, why (no held stuck lock, contention, …). */
+	reasonNotMoved?: string;
+}
+
+/**
+ * A *prepared* transition the caller asks the seam to publish. Storage-agnostic:
+ * it describes the transition semantically (a kind + a prepared local commit +
+ * the CAS lease), NOT *where* it should be published. The sole strategy decides
+ * that (today: the arbiter's `main`).
+ */
+export interface ApplyTransitionInput {
+	/** Which `work/` transition this is (claim / complete / needs-attention). */
+	kind: LedgerTransitionKind;
+	/** Name of the arbiter git remote the transition is published to. */
+	arbiter: string;
+	/** Local branch carrying the prepared transition commit (its tip = {@link head}). */
+	localBranch: string;
+	/**
+	 * The ledger commit the publish must be a fast-forward FROM — the
+	 * compare-and-swap lease. If the ledger has moved past this, the publish is
+	 * rejected (someone else advanced it under us).
+	 */
+	expectedBase: string;
+	/** The commit sha the caller expects to become the ledger tip after publish. */
+	head: string;
+	/** Working clone/worktree the publish runs in. */
+	cwd: string;
+	/** Show the intended publish without mutating the arbiter (dry-run). */
+	dryRun?: boolean;
+	/** Environment for child git processes. */
+	env?: NodeJS.ProcessEnv;
+	/** Sink for human-readable progress notes. */
+	note?: (message: string) => void;
+}
+
+/** The outcome of asking the seam to publish a prepared transition. */
+export interface ApplyTransitionResult {
+	/**
+	 * `published` — the transition landed (and was verified to be the ledger tip).
+	 * `rejected` — the CAS lease failed (the ledger moved under us); the caller
+	 * decides whether to refetch+retry or give up. The seam never throws for this
+	 * expected contended case.
+	 */
+	kind: 'published' | 'rejected';
+	/** Human-readable summary of the terminal condition. */
+	message: string;
+	/**
+	 * The sha that ACTUALLY landed on the ledger when `published`. The seam stamps
+	 * each attempt's tip with a fresh `CAS-Nonce` trailer (so the pushed sha is
+	 * unique), so the landed commit is NOT the caller's pre-nonce `head` — it is
+	 * this nonce'd descendant-in-content. Callers that branch/track/report off the
+	 * landed commit (e.g. `claim`'s work-branch hint) MUST use this, not their
+	 * input `head`. Absent on `rejected` and on `dryRun`.
+	 */
+	publishedHead?: string;
+}
+
+/**
+ * The write-seam interface: ONE entry point — apply (publish) a prepared `work/`
+ * transition. A future strategy implements this same interface to publish the
+ * transition elsewhere — without any transition call site changing.
+ */
+export interface LedgerWriteStrategy {
+	applyTransition(input: ApplyTransitionInput): Promise<ApplyTransitionResult>;
+	/**
+	 * Apply (publish) a prepared COMPLETE transition: integrate a finished work
+	 * branch back to the arbiter per its mode. The sole strategy delegates to the
+	 * integration mechanism unchanged; a future strategy could integrate elsewhere
+	 * without `complete.ts` changing.
+	 */
+	applyCompleteTransition(
+		input: ApplyCompleteTransitionInput,
+	): Promise<ApplyCompleteTransitionResult>;
+	/**
+	 * Apply a NEEDS-ATTENTION transition: bounce a stuck claimed item to
+	 * `work/needs-attention/` with its reason recorded in the body. The sole
+	 * strategy delegates to the folder-native move mechanism unchanged; a future
+	 * strategy could surface the stuck item elsewhere (e.g. the cherry-pick-to-
+	 * `main` follow-on) without `complete.ts`/`run.ts` changing.
+	 */
+	applyNeedsAttentionTransition(
+		input: ApplyNeedsAttentionTransitionInput,
+	): Promise<ApplyNeedsAttentionTransitionResult>;
+	/**
+	 * Apply a TREE-LESS NEEDS-ATTENTION (surface) transition: surface a stuck
+	 * AFTER-COMMIT, LEDGER-ONLY item (`in-progress/ → needs-attention/`) WITHOUT a
+	 * checkout, reusing the SAME tree-less mechanism `requeue` uses for the reverse
+	 * direction. The sole strategy delegates to the tree-less surface (now a pure lock amend)
+	 * (fetch + scratch-index move + throwaway-ref + leased fast-forward push). NOT
+	 * for the uncommitted-wip surfaces, which keep {@link
+	 * applyNeedsAttentionTransition} (the cwd-bound path that can commit wip first).
+	 */
+	applyTreelessNeedsAttentionTransition(
+		input: ApplyTreelessNeedsAttentionTransitionInput,
+	): ApplyTreelessNeedsAttentionTransitionResult;
+	/**
+	 * Apply a RETURN-TO-BACKLOG transition: re-queue a STUCK item (in
+	 * `needs-attention/` OR `in-progress/` — resolved on the arbiter) for
+	 * re-claiming, routed through the SAME seam. Like `claim`, it is TREE-LESS —
+	 * the move is a compare-and-swap push to the arbiter ref (it never writes the
+	 * cwd tree).
+	 */
+	applyReturnToBacklogTransition(
+		input: ApplyReturnToBacklogTransitionInput,
+	): ApplyReturnToBacklogTransitionResult;
+	/**
+	 * Apply a RESOLVE-NEEDS-ATTENTION transition: a human is picking up a stuck
+	 * item, so **clear the stuck surface** and restore it to `in-progress`. The
+	 * seam carries only that INTENT — "clear the surface" — NOT *how*; the sole
+	 * (mode-M) strategy clears it by reverse-moving needs-attention → in-progress
+	 * on the arbiter's `main`, but a future strategy could clear it differently
+	 * without `start.ts` changing.
+	 */
+	applyResolveNeedsAttentionTransition(
+		input: ApplyResolveNeedsAttentionTransitionInput,
+	): Promise<ApplyResolveNeedsAttentionTransitionResult>;
+}
+
+// --- The sole strategy: exactly today's behaviour -------------------------
+
+/** Run git, returning the raw result (no throw) — for soft checks. */
+function gitSoft(
+	args: string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): Promise<RunResult> {
+	return runAsync('git', args, cwd, {env});
+}
+
+/** Run git; throw on non-zero (genuinely unexpected plumbing failures). */
+async function gitHard(
+	args: string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): Promise<RunResult> {
+	const result = await runAsync('git', args, cwd, {env});
+	if (result.status !== 0) {
+		throw new Error(
+			`git ${args.join(' ')} failed (exit ${result.status}): ${result.stderr.trim()}`,
+		);
+	}
+	return result;
+}
+
+/** The git trailer key the per-attempt CAS nonce rides in (greppable, round-trips). */
+export const CAS_NONCE_TRAILER = 'CAS-Nonce';
+
+/**
+ * Rebuild the transition tip ({@link localBranch}'s commit, whose sha is {@link
+ * head}) into a NEW commit object that is byte-for-byte identical EXCEPT for a
+ * freshly-appended `CAS-Nonce: <uuid>` trailer, and return the new sha. This is
+ * the ONE chokepoint that makes EVERY {@link
+ * LedgerWriteStrategy.applyTransition} caller's CAS commit unique — create,
+ * claim, tasking-lock, advancing-lock, and the needs-attention/requeue surface
+ * all route their publish through `applyTransition`, so stamping HERE (the seam
+ * AMENDING the tip's message just before the push) covers all of them WITHOUT a
+ * shared commit-building helper and WITHOUT touching each commit site.
+ *
+ * It is built with `commit-tree` plumbing on the same tree + parent + ambient
+ * env identity as the tip, so it NEVER mutates the caller's working tree, index,
+ * or HEAD (safe from a job worktree mid-flight), and it preserves WHO/WHAT — it
+ * ONLY appends the trailer to the original message. The author/committer
+ * identity is pinned from the original commit so the stamp does not silently
+ * re-attribute the transition.
+ *
+ * A FRESH nonce is generated on EACH call — and `applyTransition` calls this once
+ * per ATTEMPT (each retry of a caller's outer refetch loop re-enters
+ * `applyTransition`), so two concurrent same-identity racers, and any single
+ * racer across its own retries, ALWAYS get distinct shas.
+ */
+async function stampNonce(params: {
+	localBranch: string;
+	head: string;
+	cwd: string;
+	env: NodeJS.ProcessEnv | undefined;
+}): Promise<string> {
+	const {localBranch, head, cwd, env} = params;
+	const nonce = randomUUID();
+
+	// Read the tip's tree + parents + author/committer identity + original message
+	// in ONE `git log` (one git subprocess, not four) — the body (%B, multi-line)
+	// MUST be last. Fields are NUL-separated (%x00); the trailing field is the raw
+	// body so its embedded newlines do not confuse the split.
+	const FIELD_SEP = '\u0000';
+	const raw = (
+		await gitHard(
+			[
+				'log',
+				'-1',
+				`--format=%T%x00%P%x00%an%x00%ae%x00%aI%x00%cn%x00%ce%x00%B`,
+				head,
+			],
+			cwd,
+			env,
+		)
+	).stdout;
+	const fields = raw.split(FIELD_SEP);
+	const tree = (fields[0] ?? '').trim();
+	const parents = (fields[1] ?? '')
+		.trim()
+		.split(/\s+/)
+		.filter((p) => p.length > 0); // the tip's parents (usually exactly one)
+	const authorName = fields[2] ?? '';
+	const authorEmail = fields[3] ?? '';
+	const authorDate = fields[4] ?? '';
+	const committerName = fields[5] ?? '';
+	const committerEmail = fields[6] ?? '';
+	// The body is the last field; strip trailing whitespace before we append.
+	const message = (fields[7] ?? '').replace(/\s+$/, '');
+
+	// Pin the original author/committer so the stamp re-attributes nothing; we are
+	// only appending a trailer to the message.
+	const stampEnv: NodeJS.ProcessEnv = {
+		...(env ?? process.env),
+		GIT_AUTHOR_NAME: authorName,
+		GIT_AUTHOR_EMAIL: authorEmail,
+		GIT_AUTHOR_DATE: authorDate,
+		GIT_COMMITTER_NAME: committerName,
+		GIT_COMMITTER_EMAIL: committerEmail,
+		// Deliberately do NOT pin GIT_COMMITTER_DATE: even two stamps with identical
+		// everything-else would still differ by the nonce, but leaving the committer
+		// date current is the honest "when this attempt was published".
+	};
+
+	// Append the trailer as its own block so it round-trips as a real git trailer.
+	const noncedMessage = `${message}\n\n${CAS_NONCE_TRAILER}: ${nonce}\n`;
+	const parentArgs = parents.flatMap((p) => ['-p', p]);
+	const result = await runAsync(
+		'git',
+		['commit-tree', tree, ...parentArgs, '-m', noncedMessage],
+		cwd,
+		{env: stampEnv},
+	);
+	if (result.status !== 0) {
+		throw new Error(
+			`git commit-tree (CAS nonce stamp) failed (exit ${result.status}): ${result.stderr.trim()} — localBranch=${localBranch}`,
+		);
+	}
+	return result.stdout.trim();
+}
+
+/**
+ * The ONLY ledger-write strategy: current behaviour. It CAS-publishes the
+ * prepared transition commit to the arbiter's `main` — the `main` push and the
+ * `--force-with-lease=main:<base>` lease live HERE, not in the public input — and
+ * verifies the arbiter's `main` is now that commit (guarding against an
+ * "Everything up-to-date" push masquerading as a successful transition). A future
+ * strategy would be a different object implementing the same interface — chosen
+ * NOWHERE today (no mode/config selects it).
+ */
+export const currentLedgerWrite: LedgerWriteStrategy = {
+	async applyTransition({
+		arbiter,
+		localBranch,
+		expectedBase,
+		head,
+		cwd,
+		dryRun,
+		env,
+		note,
+	}): Promise<ApplyTransitionResult> {
+		const emit = note ?? (() => {});
+
+		if (dryRun) {
+			const message = `[dry-run] would: git push ${arbiter} ${localBranch}:main --force-with-lease=main:${expectedBase}`;
+			emit(message);
+			return {kind: 'published', message};
+		}
+
+		// Stamp this ATTEMPT's transition commit with a FRESH random nonce (a real
+		// `CAS-Nonce: <uuid>` git trailer) so the pushed sha is UNIQUE per attempt.
+		// This is what makes the lease authoritative even for SAME-IDENTITY,
+		// SAME-CONTENT racers: without it, two racers who build an identical tree +
+		// message off the same base within git's 1-second timestamp resolution
+		// produce an IDENTICAL sha X. The first push ff's main to X; the second
+		// push of the SAME X degrades to "Everything up-to-date" (git exits 0, the
+		// lease has nothing to reject), and the post-push verify X === X passes — so
+		// BOTH would return `published`. The nonce gives each attempt a DISTINCT sha,
+		// so the loser's push finds main moved past <base> and is GENUINELY rejected
+		// by the lease, and the verify below correctly fails for it. The stamp is
+		// built with `commit-tree` plumbing (no checkout/HEAD mutation), reusing the
+		// tip's tree + parent + author/committer identity — it ONLY appends the
+		// trailer, leaving WHO/WHAT/the original message intact. Called per ATTEMPT
+		// (each retry of the caller's outer refetch loop re-enters here), so every
+		// attempt gets a fresh nonce, not one per process.
+		const nonced = await stampNonce({localBranch, head, cwd, env});
+
+		// The atomic compare-and-swap. --force-with-lease=main:<base> asserts the
+		// arbiter's main is STILL <base> (unchanged since our fetch); the push then
+		// fast-forwards main to our (nonce'd, thus unique) commit. If main moved, the
+		// lease fails → rejected.
+		const push = await gitSoft(
+			[
+				'push',
+				arbiter,
+				`${nonced}:main`,
+				`--force-with-lease=main:${expectedBase}`,
+			],
+			cwd,
+			env,
+		);
+		if (push.status === 0) {
+			// Verify the arbiter main now points at OUR (nonce'd) commit. INVARIANT:
+			// because the nonce makes our sha unique, a successful push can ONLY mean
+			// either (a) we genuinely ff'd main to our nonce'd commit (published), or
+			// (b) someone else's commit (a DIFFERENT nonce ⇒ a DIFFERENT sha) is already
+			// there and ours did NOT land — i.e. an "up-to-date / no change of our
+			// making" no-op, which is a LOSS. The nonce makes the two naturally
+			// distinguishable: `arbiterHead === nonced` iff WE won. So an up-to-date
+			// no-op can never satisfy this and is classified REJECTED, never published.
+			await gitHard(['fetch', '--quiet', arbiter], cwd, env);
+			const arbiterHead = (
+				await gitHard(['rev-parse', `${arbiter}/main`], cwd, env)
+			).stdout.trim();
+			if (arbiterHead === nonced) {
+				return {
+					kind: 'published',
+					message: 'transition published',
+					publishedHead: nonced,
+				};
+			}
+			emit(
+				`push reported up-to-date / no change of our making — ${arbiter}/main is not our commit — treating as rejected.`,
+			);
+		}
+		return {kind: 'rejected', message: 'push rejected / lease failed'};
+	},
+
+	/**
+	 * The complete transition under the SAME strategy: integrate the prepared work
+	 * branch back to the arbiter exactly as `complete.ts` did before — it builds
+	 * the {@link Integrator} with the chosen provider and calls `integrate` (the
+	 * branch was already rebased onto the latest arbiter ledger by the caller, so
+	 * this is the non-rebasing `integrate`, never `--force`). `merge` ff's the
+	 * branch to the arbiter's `main`; `propose` pushes the branch + asks the
+	 * provider to request review. That `merge` targets `main` is an implementation
+	 * detail of THIS strategy — the public input never names it.
+	 */
+	async applyCompleteTransition({
+		arbiter,
+		branch,
+		mode,
+		provider,
+		noPR,
+		title,
+		body,
+		deleteMergedHead,
+		cwd,
+		env,
+	}): Promise<ApplyCompleteTransitionResult> {
+		const integrator = new Integrator({provider});
+		return integrator.integrate({
+			cwd,
+			arbiter,
+			branch,
+			mode,
+			noPR,
+			title,
+			body,
+			deleteMergedHead,
+			env,
+		});
+	},
+
+	/**
+	 * The needs-attention transition under the SAME strategy. The seam's contract
+	 * is transition-kind-agnostic: durably record a stuck job =
+	 *
+	 *   - **OBSERVABLE** — publish the stuck state to the ledger surface so
+	 *     `scan`/`status`/a fresh checkout/another machine can see it. (THIS mode-M
+	 *     strategy does that by CHERRY-PICKING the move-only commit — the reason +
+	 *     the `git mv` — onto the arbiter's `main`, all-or-nothing, never `--force`d,
+	 *     so the half-finished wip below it never lands there. A future mode-P
+	 *     strategy could make it observable WITHOUT writing `main`, e.g. by reading
+	 *     work-branch tips.)
+	 *   - **RECOVERABLE** — push the work branch (when there IS one), so the saved
+	 *     work travels cross-machine and a requeue continues from its tip. (Mode M
+	 *     does that by `git push`ing the branch; the WHICH branch is the caller's,
+	 *     not assumed `work/<slug>` — a build bounce pushes `work/<slug>`, a tasking
+	 *     bounce its `work/prd-<slug>`, a temp-branch caller pushes NOTHING.)
+	 *
+	 * Both halves are ONE operation done in ONE place: it delegates to {@link
+	 * routeToNeedsAttention}, which appends the reason as body prose (never a
+	 * frontmatter field — WORK-CONTRACT rule 3), saves the aborted work as a
+	 * **wip** commit, `git mv`s the item to `work/needs-attention/` as the
+	 * **move-only** commit (the tip), and — when an `arbiter` is given — pushes the
+	 * work branch (best-effort, branch-parameterised, emptiness-guarded; SURFACE-
+	 * ONLY when `pushBranch: false`). The seam does NOT strip the arbiter: the same
+	 * arbiter both publishes the surface (here) AND drives the helper's branch push,
+	 * so "record stuck" and "save the work" can never drift apart. The human-vs-
+	 * autonomous gate rides on whether an `arbiter` is given at all (human
+	 * `complete` passes none → no surface, no push, local-only; autonomous `do`/`run`
+	 * pass it → both).
+	 */
+	async applyNeedsAttentionTransition(
+		input: ApplyNeedsAttentionTransitionInput,
+	): Promise<ApplyNeedsAttentionTransitionResult> {
+		// BOUNCE = SAVE WIP + PUSH BRANCH (recoverable) + MARK LOCK STUCK (observable)
+		// — task `cutover-needs-attention-becomes-lock-stuck-recovery-surface`
+		// (decision i+). The OBSERVABLE half is now the per-item lock `state: stuck`
+		// (full reason prose + any agent-surfaced questions on the entry), NOT a
+		// `git mv` to `needs-attention/` and NOT an on-`main` surface — so a
+		// protected-`main` bounce succeeds and a branch cut from `main` inherits no
+		// stuck record. The RECOVERABLE half is UNCHANGED: {@link routeToNeedsAttention}
+		// commits the agent's uncommitted wip to the `work/<slug>` branch tip and
+		// pushes the branch (best-effort, branch-parameterised, emptiness-guarded,
+		// outage-retried), so the partial work travels cross-machine and a `requeue`
+		// continues from the tip. The work-branch push is NOT a `main` write.
+		const saved = await routeToNeedsAttention(input);
+		const stuck = await bounceToStuckLock({
+			cwd: input.cwd,
+			slug: input.slug,
+			reason: input.reason,
+			questions: input.questions,
+			arbiter: input.arbiter,
+			env: input.env,
+			note: input.note,
+		});
+		return {
+			// `moved` reflects the OBSERVABLE half (the stuck record): the lock amend.
+			moved: stuck.moved,
+			reasonNotMoved: stuck.reasonNotMoved,
+			// The branch push outcome is the honest RECOVERABLE report (`do`/`run` read
+			// it). The on-`main` surface half is GONE (the lock is the surface now).
+			branchPush: saved.branchPush,
+			pushError: saved.pushError,
+		};
+	},
+
+	/**
+	 * The return-to-backlog transition under the SAME strategy: re-queue the
+	 * stuck item by delegating to {@link returnToBacklog}, which moves the slug's
+	 * current `work/<needs-attention|in-progress>/<slug>.md → work/backlog/<slug>.md`
+	 * TREE-LESSLY — it
+	 * builds the move off `<arbiter>/main` with plumbing and CAS-publishes it back
+	 * THROUGH this same write seam (`applyTransition`, the very push+lease+verify
+	 * `claim` uses), never staging/committing in the cwd working tree.
+	 */
+	applyReturnToBacklogTransition(
+		input: ApplyReturnToBacklogTransitionInput,
+	): ApplyReturnToBacklogTransitionResult {
+		return returnToBacklog(input);
+	},
+
+	/**
+	 * The tree-less surface transition under the SAME strategy: surface the stuck
+	 * AFTER-COMMIT, LEDGER-ONLY item by delegating to the tree-less surface (now a pure lock amend),
+	 * which moves `work/in-progress/<slug>.md → work/needs-attention/<slug>.md`
+	 * (reason in the body) TREE-LESSLY — it builds the move off `<arbiter>/main` with
+	 * plumbing and CAS-publishes it THROUGH this same write seam
+	 * (`applyTransition`, the very push+lease+verify `claim`/`requeue` use), never
+	 * staging/committing in the cwd working tree. The reverse of
+	 * {@link applyReturnToBacklogTransition}, the same one mechanism.
+	 */
+	async applyTreelessNeedsAttentionTransition(
+		input: ApplyTreelessNeedsAttentionTransitionInput,
+	): ApplyTreelessNeedsAttentionTransitionResult {
+		// PURE LOCK AMEND (task
+		// `cutover-needs-attention-becomes-lock-stuck-recovery-surface`, decision i+):
+		// the after-commit / ledger-only surface (continue-push-failure /
+		// continue-rebase-conflict) is now the SAME `active → stuck` lock amend as the
+		// cwd-bound bounce — NO `git mv`, NO `main` write. The recoverable work is
+		// already committed on the kept `work/<slug>` branch (intact on the arbiter);
+		// the stuck reason + questions ride on the lock entry. A re-surface of an
+		// already-stuck item is a tolerated idempotent no-op (`wrong-state`).
+		const moved = await bounceToStuckLock({
+			cwd: input.cwd,
+			slug: input.slug,
+			reason: input.reason,
+			questions: input.questions,
+			arbiter: input.arbiter,
+			env: input.env,
+			note: input.note,
+		});
+		return {moved: moved.moved, reasonNotMoved: moved.reasonNotMoved};
+	},
+
+	/**
+	 * The resolve-needs-attention transition under the SAME strategy — satisfying
+	 * the INTENT "clear the stuck surface + restore in-progress." It delegates to
+	 * the resume lock amend (reverse `git mv` needs-attention →
+	 * in-progress, committed) and, when an `arbiter` is given, publishes that
+	 * reverse move-only commit to the arbiter's `main` — CLEARING the stuck surface
+	 * there (the item is back in in-progress on the ledger). Same all-or-nothing,
+	 * never-`--force` publish. "Reverse-move on `main`" is a detail of THIS
+	 * strategy; the seam's contract is only the intent "clear the surface."
+	 */
+	async applyResolveNeedsAttentionTransition(
+		input: ApplyResolveNeedsAttentionTransitionInput,
+	): Promise<ApplyResolveNeedsAttentionTransitionResult> {
+		// PURE LOCK AMEND (task
+		// `cutover-needs-attention-becomes-lock-stuck-recovery-surface`, decision i+):
+		// resolving a stuck item is `stuck → active` on the per-item lock (a human is
+		// picking it up), NOT a `needs-attention/ → in-progress/` folder move. NO `main`
+		// write — the body already rests in `backlog/` (task 9a) and the work stays on
+		// the kept `work/<slug>` branch. Without an arbiter there is no lock ref to
+		// amend (the human-local face), so it is a recorded no-op success.
+		if (!input.arbiter) {
+			return {moved: true};
+		}
+		const r = await resumeItemLock({
+			item: `task:${input.slug}`,
+			cwd: input.cwd,
+			arbiter: input.arbiter,
+			env: input.env,
+		});
+		if (r.outcome === 'transitioned') {
+			return {moved: true};
+		}
+		// `wrong-state` (already active — not actually stuck) is tolerated as a no-op
+		// success: the item is already in-flight, the caller onboards onto it anyway.
+		if (r.outcome === 'wrong-state') {
+			return {moved: true};
+		}
+		return {
+			moved: false,
+			reasonNotMoved: `could not resume '${input.slug}' (${r.outcome}: ${r.message}).`,
+		};
+	},
+};
+
+/**
+ * The SOLE stuck-state RECORD: amend the item's HELD per-item lock
+ * `active → stuck` + the FULL reason prose + any agent-surfaced questions, via the
+ * state machine's mark-stuck CAS amend ({@link markStuckItemLock}) — task
+ * `cutover-needs-attention-becomes-lock-stuck-recovery-surface` (decision i+; prd
+ * `ledger-status-per-item-lock-refs` US #5/#8; ADR
+ * `ledger-status-on-per-item-lock-refs`). This REPLACES the `git mv →
+ * needs-attention/` folder bounce + its on-`main` surface + branch push: the
+ * bounce now touches ONLY the lock ref (NO `main` write — so a protected-`main`
+ * bounce succeeds, and a work branch cut from `main` inherits no stuck record).
+ *
+ * The bounce holds the TASK's `implement` lock that `claim` acquired (task
+ * `claim-acquires-unified-lock-no-body-move`), so the normal stuck path is a plain
+ * `active → stuck` amend (`transitioned`). The OUTCOME MAPPING onto `{moved}`:
+ *   - `transitioned`  — the lock is now stuck (the stuck state is recorded) ⇒
+ *     `moved: true`.
+ *   - `wrong-state`   — the lock is ALREADY `stuck` (an idempotent re-surface of a
+ *     still-stuck item) ⇒ `moved: true` (the stuck record stands).
+ *   - `not-held`      — there is NO held lock to amend (an item that predates the
+ *     lock, or a flow where claim did not acquire) ⇒ `moved: false` honestly: with
+ *     the folder retired there is no other substrate to record the stuck state on,
+ *     so the caller reports the bounce did NOT land (retry/resolve) rather than
+ *     fake a success.
+ *   - `lost`/`error`  — a concurrent CAS race / environment fault ⇒ `moved: false`.
+ *   - no arbiter      — a human local-only `complete` (no arbiter handle): the lock
+ *     ref lives on the arbiter, so there is no lock to amend; treat as a recorded
+ *     no-op (`moved: true`) — a human is right there (the same human-vs-autonomous
+ *     posture the old local-only folder move took). NOTE this records nothing
+ *     durable, by design: the human is in the loop.
+ *
+ * Keyed on `task:<slug>` (the bounce surfaces a TASK; the prd/observation locks
+ * are tasking/advance holds whose own bounce paths are separate).
+ */
+async function bounceToStuckLock(params: {
+	cwd: string;
+	slug: string;
+	reason: string;
+	questions?: string[];
+	arbiter?: string;
+	env?: NodeJS.ProcessEnv;
+	note?: (message: string) => void;
+}): Promise<{moved: boolean; reasonNotMoved?: string}> {
+	const {cwd, slug, reason, questions, arbiter, env} = params;
+	const note = params.note ?? (() => {});
+	if (!arbiter) {
+		// No arbiter handle ⇒ no lock ref to amend. A human local-only `complete`:
+		// the human is right there, so this is a recorded no-op (parity with the old
+		// local-only folder move that wrote nothing cross-machine).
+		note(
+			`'${slug}' bounced locally (no arbiter) — the stuck reason is not recorded ` +
+				'on a lock ref (a human is right here).',
+		);
+		return {moved: true};
+	}
+	try {
+		const r = await markStuckItemLock({
+			item: `task:${slug}`,
+			reason,
+			questions,
+			cwd,
+			arbiter,
+			env,
+		});
+		const movedOutcomes: TransitionOutcome[] = ['transitioned', 'wrong-state'];
+		if (movedOutcomes.includes(r.outcome)) {
+			if (r.outcome === 'transitioned') {
+				note(`Marked the per-item lock for '${slug}' stuck: ${reason}`);
+			} else {
+				note(`The per-item lock for '${slug}' is already stuck (re-surface).`);
+			}
+			return {moved: true};
+		}
+		const reasonNotMoved =
+			r.outcome === 'not-held'
+				? `'${slug}' has no held lock to mark stuck (the bounce could not record ` +
+					'the stuck state — the item is not lock-held).'
+				: `could not mark the per-item lock for '${slug}' stuck (${r.outcome}: ` +
+					`${r.message}).`;
+		note(reasonNotMoved);
+		return {moved: false, reasonNotMoved};
+	} catch (err) {
+		const reasonNotMoved =
+			`could not mark the per-item lock for '${slug}' stuck ` +
+			`(${err instanceof Error ? err.message : String(err)}).`;
+		note(reasonNotMoved);
+		return {moved: false, reasonNotMoved};
+	}
+}
+
+/**
+ * The active ledger-write strategy. There is exactly one (current behaviour);
+ * this indirection is the seam's single insertion point — NOT a selectable mode.
+ */
+export const ledgerWrite: LedgerWriteStrategy = currentLedgerWrite;