dorfl 0.14.2 → 0.15.0

package/src/integrator.ts

@@ -380,6 +380,34 @@ export interface IntegrateResult {
 	commit?: string;
 }
 
+/**
+ * The HONEST propose-land check (task `intake-reports-the-pr-it-actually-opened`):
+ * the reason NO review request exists for a propose land that pushed its branch,
+ * else `undefined`. A propose land whose provider did not open a request (a
+ * degraded `gh pr create`, e.g. a repository that refuses PR creation by Actions;
+ * the push-only `none` provider; the `noPR` intent) returns the provider's
+ * `instruction` (the real `gh` error + the manual `gh pr create` command), so every
+ * caller can say "pushed, but no PR" instead of implying one. `undefined` for a
+ * merge land, an opened request, a benign already-landed no-op (nothing was
+ * pushed, nothing to propose), or no integration at all.
+ */
+export function proposeRequestNotOpened(
+	integration: IntegrateResult | undefined,
+): string | undefined {
+	if (
+		integration === undefined ||
+		integration.mode !== 'propose' ||
+		integration.requestOpened ||
+		integration.alreadyLanded === true
+	) {
+		return undefined;
+	}
+	return (
+		integration.instruction ??
+		`Pushed ${integration.pushedRef}; no review request was opened.`
+	);
+}
+
 /** Outcome of the full rebase-then-integrate flow. */
 export interface IntegrateWithRebaseResult {
 	outcome: 'integrated' | 'needs-attention';

package/src/isolation.ts

@@ -4,8 +4,10 @@ import {reapJob} from './gc.js';
 import {
 	branchAheadOfArbiter,
 	rebaseContinuedBranchOntoMain,
-	pushContinuedBranchWithStaleLeaseRetry,
+	type ContinueRebaseFailure,
 } from './continue-branch.js';
+import {refWrite} from './ref-write.js';
+import {activePhase} from './phase.js';
 import {workBranchRef, type SlugNamespace} from './slug-namespace.js';
 
 /**
@@ -69,13 +71,22 @@ export interface IsolatedTree {
 	 */
 	continued?: boolean;
 	/**
-	 * True iff a CONTINUE rebase onto fresh main CONFLICTED at onboard-time
+	 * True iff a CONTINUE rebase onto fresh main did not apply at onboard-time
 	 * (a requeue kept a `work/<slug>` whose commits did not replay onto the
-	 * current main; aborted, never auto-resolved). The pipeline routes the item
+	 * current main, by a genuine conflict or any other rebase failure; aborted,
+	 * never auto-resolved). The pipeline routes the item
 	 * to needs-attention (the §10 path) instead of running the agent. Absent /
 	 * false on a fresh cut and on a clean continue.
 	 */
 	continueRebaseConflict?: boolean;
+	/**
+	 * Why the continue rebase did not apply (set exactly when
+	 * {@link continueRebaseConflict} is): a genuine conflict with its paths, or
+	 * any other rebase failure with git's report, plus the `main` sha rebased
+	 * onto. The needs-attention reason renders it with
+	 * `describeContinueRebaseFailure`.
+	 */
+	continueRebaseFailure?: ContinueRebaseFailure;
 	/**
 	 * Set iff the CONTINUE reconcile push to the arbiter FAILED TERMINALLY at
 	 * onboard-time (the stale-lease retry cap exhausted, or a non-stale-lease
@@ -199,6 +210,7 @@ export function jobWorktreeHandle(
 		arbiterUrl: job.mirror.url,
 		continued: job.continued,
 		continueRebaseConflict: job.continueRebaseConflict,
+		continueRebaseFailure: job.continueRebaseFailure,
 		continuePushFailure: job.continuePushFailure,
 		teardown(opts?: {reachableOnly?: boolean}): void {
 			// Auto-reap at end-of-job (ADR §4): re-apply the provably-safe deletion
@@ -261,7 +273,7 @@ export function inPlaceStrategy(options: {
 			// it)? In a normal clone the refs are the remote-tracking
 			// `<arbiter>/work/<slug>` and `<arbiter>/main`.
 			let continued = false;
-			let continueRebaseConflict = false;
+			let continueRebaseFailure: ContinueRebaseFailure | undefined;
 			let continuePushFailure: string | undefined;
 			// ARBITER-AUTHORITATIVE continue-detection: `ls-remote` the arbiter so a
 			// STALE local remote-tracking ref (a plain `git fetch` does NOT prune
@@ -310,8 +322,14 @@ export function inPlaceStrategy(options: {
 					`${arbiter}/main`,
 					env,
 				);
-				if (rebase.kind === 'conflict') {
-					continueRebaseConflict = true;
+				if (rebase.kind !== 'clean') {
+					continueRebaseFailure = rebase;
+				} else if (activePhase() === 'agent') {
+					// CI AGENT PHASE (ADR `ci-agent-job-holds-no-write-token` decision 7):
+					// the agent job holds no write token, so the rebase stays LOCAL. The
+					// apply job pushes the rebased branch (in the handoff bundle) with
+					// `--force-with-lease` against the tip the lock job observed
+					// (`continueTip`), before any other write.
 				} else {
 					// The helper THROWS on a terminal failure (the stale-lease retry cap, or
 					// a non-stale-lease rejection / unreachable arbiter). CATCH it and flag
@@ -319,7 +337,7 @@ export function inPlaceStrategy(options: {
 					// — the kept work stays committed + recoverable — rather than crashing
 					// the run and stranding it silently in-progress (the stale-lease bug).
 					try {
-						const pushed = pushContinuedBranchWithStaleLeaseRetry({
+						const pushed = refWrite.pushContinuedBranch({
 							cwd: checkout,
 							branch,
 							arbiter,
@@ -327,8 +345,8 @@ export function inPlaceStrategy(options: {
 							expectedRemoteTip,
 							env,
 						});
-						if (pushed.kind === 'conflict') {
-							continueRebaseConflict = true;
+						if (pushed.kind !== 'pushed') {
+							continueRebaseFailure = pushed;
 						}
 					} catch (err) {
 						continuePushFailure =
@@ -376,7 +394,8 @@ export function inPlaceStrategy(options: {
 				arbiterRemote: arbiter,
 				arbiterUrl,
 				continued,
-				continueRebaseConflict,
+				continueRebaseConflict: continueRebaseFailure !== undefined,
+				continueRebaseFailure,
 				continuePushFailure,
 				// NO-OP teardown: the checkout is the human's / CI's tree — left on
 				// `work/<slug>` in a defined state, NEVER reaped (ADR §2/§4). The

package/src/item-lock.ts

@@ -1,5 +1,6 @@
 import {randomUUID} from 'node:crypto';
 import {runAsync, type RunResult} from './git.js';
+import {refWrite} from './ref-write.js';
 import {
 	resolveSidecarIdentity,
 	sidecarPathFor,
@@ -128,8 +129,27 @@ export interface LockEntry {
 	state: LockState;
 	holder: string;
 	since: string;
+	/**
+	 * Why a finished build still holds the lock, when it does (task
+	 * `wire-merge-questions-into-the-advance-tick`, decision 4). Absent on every
+	 * live hold. See {@link LockKeptFor}.
+	 */
+	keptFor?: LockKeptFor;
 }
 
+/**
+ * The PROPOSE-KEPT marker a lock entry may carry. `propose-pr`: a propose land
+ * pushed the work branch (and opened a PR where the host allows it) but the
+ * work is not on `main` yet, so the build's `implement` lock is KEPT HELD
+ * "until the PR merges" (task `propose-keep-lock-until-pr-merge`). No build is
+ * running under it. It is what lets the merge-question surfacer tell a finished
+ * propose build (ask) from a live build (skip), and what the answered-merge
+ * lock phase may take over (for the same item) instead of backing off. A lock
+ * WITHOUT the marker is a live build, including the rebuild of a bounced task's
+ * kept branch, whose tip can already carry the done-move.
+ */
+export type LockKeptFor = 'propose-pr';
+
 /** Outcome of an acquire attempt. `acquired` = we hold it; `lost` = someone else
  * does (a genuine same-item conflict). `error` = environment/usage. */
 export type AcquireOutcome = 'acquired' | 'lost' | 'error';
@@ -151,12 +171,12 @@ export interface ReleaseResult {
 }
 
 /**
- * Outcome of an AMEND-style transition (resume-crash-orphan / requeue) — the
+ * Outcome of an AMEND-style transition (resume-crash-orphan) — the
  * lock-entry STATE MACHINE's interior moves. Post-CONTRACT step (task
  * `retire-stuck-lock-state`) the `mark-stuck` transition + the `wrong-state`
  * verdict are retired with the `stuck` state itself.
  *   - `transitioned` — we won the CAS; the entry is now at the target state
- *                      (or removed, for requeue).
+ *                      (or removed, for the crash-orphan clear).
  *   - `not-held`     — there is no entry to transition (the move's precondition
  *                      is a held entry; absent ⇒ illegal here).
  *   - `lost`         — the leased CAS was rejected because a CONCURRENT writer
@@ -172,7 +192,7 @@ export interface TransitionResult {
 	entry: string;
 	ref: string;
 	message: string;
-	/** The lock entry AFTER a successful `transitioned` (absent for requeue's removal). */
+	/** The lock entry AFTER a successful `transitioned` (absent for a removal). */
 	lock?: LockEntry;
 }
 
@@ -213,9 +233,12 @@ export function serialiseLockEntry(e: LockEntry): string {
 		`state: ${e.state}`,
 		`holder: ${e.holder}`,
 		`since: ${e.since}`,
+		...(e.keptFor === undefined ? [] : [`keptFor: ${e.keptFor}`]),
 		'---',
 		'',
-		`Lock held for \`${e.entry}\` (${e.action}/${e.state}).`,
+		e.keptFor === undefined
+			? `Lock held for \`${e.entry}\` (${e.action}/${e.state}).`
+			: `Lock kept for \`${e.entry}\` (${e.action}/${e.state}, ${e.keptFor}): the build finished; its work is not on main yet.`,
 		'',
 	].join('\n');
 }
@@ -326,11 +349,7 @@ export async function acquireItemLock(
 			env,
 		);
 		// CREATE-ONLY push: --force-with-lease=<ref>: (empty) succeeds iff ref absent.
-		const push = await gitSoft(
-			['push', arbiter, `${commit}:${ref}`, `--force-with-lease=${ref}:`],
-			cwd,
-			env,
-		);
+		const push = await refWrite.createLockRef({arbiter, ref, commit, cwd, env});
 		if (push.status === 0) {
 			return {outcome: 'acquired', entry, ref, message: `locked ${entry}`};
 		}
@@ -379,6 +398,42 @@ export async function acquireItemLock(
 	}
 }
 
+/**
+ * Lock refs whose release is LEASED on a known sha: `<ref>` → the sha this
+ * process last observed for it (spec `ci-agent-job-without-write-token` §8, the
+ * lock-ownership rule; task `ci-split-build-path-non-integrate-intents`).
+ *
+ * The CI apply phase holds the lock the lock JOB took, and every CI run's lock
+ * `holder` is the same bot, so only the sha tells runs apart. Its releases are
+ * reached from deep inside the reused write halves (the surface, the
+ * return-to-backlog, the land's needs-attention routes), which do not carry the
+ * sha, so the apply phase registers it here for its whole run
+ * ({@link leaseLockReleases}) and {@link releaseLockEntry} refuses to delete a
+ * lock that no longer points at it. Process-global for the same reason the
+ * phase is (`phase.ts`): a phase run is a one-shot process. Empty outside the
+ * apply phase, where every release behaves exactly as before.
+ */
+const releaseLeases = new Map<string, string>();
+
+/**
+ * Lease every release of `item`'s lock on `expectedSha` until the returned
+ * function is called: a release then deletes the ref only while it still points
+ * at `expectedSha`, and otherwise reports an `error` and leaves it untouched (the
+ * lock was re-taken by another run).
+ */
+export function leaseLockReleases(
+	item: string,
+	expectedSha: string,
+): () => void {
+	const ref = itemLockRef(lockEntryFor(item));
+	const previous = releaseLeases.get(ref);
+	releaseLeases.set(ref, expectedSha);
+	return () => {
+		if (previous === undefined) releaseLeases.delete(ref);
+		else releaseLeases.set(ref, previous);
+	};
+}
+
 export interface ReleaseOptions {
 	/** The NAMESPACED item identity (same forms as {@link AcquireOptions.item}). */
 	item: string;
@@ -453,11 +508,24 @@ async function releaseLockEntry(
 		// Delete the ref on the arbiter. Lease on the current value guards against a
 		// concurrent change between our fetch and the delete.
 		const cur = (await gitHard(['rev-parse', ref], cwd, env)).stdout.trim();
-		const del = await gitSoft(
-			['push', arbiter, '--delete', ref, `--force-with-lease=${ref}:${cur}`],
+		const lease = releaseLeases.get(ref);
+		if (lease !== undefined && lease !== cur) {
+			return {
+				outcome: 'error',
+				entry,
+				ref,
+				message:
+					`not released: ${ref} now points at ${cur}, not the leased ` +
+					`${lease} (another run holds the lock now)`,
+			};
+		}
+		const del = await refWrite.deleteLockRef({
+			arbiter,
+			ref,
+			expectedSha: cur,
 			cwd,
 			env,
-		);
+		});
 		if (del.status === 0) {
 			// Drop our local copy of the ref too (best-effort).
 			await gitSoft(['update-ref', '-d', ref], cwd, env);
@@ -583,7 +651,7 @@ export async function releaseHeldItemLock(
 /**
  * Fetch the lock refs and return the held entry + its current ref sha, or
  * `undefined` when the item is at REST (no ref). Shared read-before-CAS step for
- * the amend-style transitions (mark-stuck / resume / requeue): they all need BOTH
+ * the amend-style transitions (resume): they need BOTH
  * the current entry (to check the state precondition + carry forward `action` /
  * `holder` / `since`) and the current sha (to lease the CAS on it).
  */
@@ -626,52 +694,6 @@ async function fetchHeldEntry(
 	return {lock, sha};
 }
 
-/**
- * AMEND the held entry in place via a leased CAS: build a NEW parentless commit
- * carrying `next` and push it to the SAME ref with `--force-with-lease=<ref>:<sha>`
- * (the sha we just read). The arbiter accepts ONLY if the ref is unchanged since
- * our read — a concurrent writer who moved it makes our lease fail (`lost`). No
- * retry loop: a rejection is a genuine same-item race the caller should lose.
- */
-async function amendHeldEntry(
-	next: LockEntry,
-	ref: string,
-	expectedSha: string,
-	cwd: string,
-	arbiter: string,
-	env: NodeJS.ProcessEnv | undefined,
-): Promise<TransitionResult> {
-	const commit = await buildLockCommit(next, cwd, env);
-	const push = await gitSoft(
-		[
-			'push',
-			arbiter,
-			`${commit}:${ref}`,
-			`--force-with-lease=${ref}:${expectedSha}`,
-		],
-		cwd,
-		env,
-	);
-	if (push.status === 0) {
-		// Move our local copy to the new commit too (best-effort) so a subsequent
-		// read in the same clone sees the amended entry without a refetch.
-		await gitSoft(['update-ref', ref, commit], cwd, env);
-		return {
-			outcome: 'transitioned',
-			entry: next.entry,
-			ref,
-			message: `${next.entry} → ${next.action}/${next.state}`,
-			lock: next,
-		};
-	}
-	return {
-		outcome: 'lost',
-		entry: next.entry,
-		ref,
-		message: `'${next.entry}' lock changed concurrently (CAS lost). Back off.`,
-	};
-}
-
 /** Verdict of the SHARED leased delete {@link leasedDeleteLockRef}: `deleted` (the
  * ref was removed), `lost` (a concurrent change moved the ref between the read and
  * the delete — the lease was REJECTED, never `--force`d), or `error`. */
@@ -695,17 +717,13 @@ async function leasedDeleteLockRef(
 	arbiter: string,
 	env: NodeJS.ProcessEnv | undefined,
 ): Promise<LeasedDeleteOutcome> {
-	const del = await gitSoft(
-		[
-			'push',
-			arbiter,
-			'--delete',
-			ref,
-			`--force-with-lease=${ref}:${expectedSha}`,
-		],
+	const del = await refWrite.deleteLockRef({
+		arbiter,
+		ref,
+		expectedSha,
 		cwd,
 		env,
-	);
+	});
 	if (del.status !== 0) {
 		return 'lost';
 	}
@@ -871,21 +889,35 @@ export async function resumeItemLock(
 	}
 }
 
+export interface MarkProposeKeptOptions {
+	/** The NAMESPACED item identity (same forms as {@link AcquireOptions.item}). */
+	item: string;
+	cwd: string;
+	arbiter?: string;
+	/**
+	 * The lock sha the caller holds (the CI apply phase's `lockSha`). When set,
+	 * the mark is refused (`lost`) unless the ref still points at it. Unset: the
+	 * current sha is read and leased on (the laptop `complete`, which holds the
+	 * lock it claimed).
+	 */
+	expectedSha?: string;
+	env?: NodeJS.ProcessEnv;
+}
+
 /**
- * requeue: give up on a held lock and return the item to the pool by REMOVING
- * the entry. Post-CONTRACT step (task `retire-stuck-lock-state`) there is NO
- * `stuck` state to guard against — the held lock is always `active`, so
- * requeue works on any held entry (a leased delete; a concurrent change ⇒
- * `lost`). The body never moved (it rests in the pool on `main`), so requeue
- * is purely "release the lock"; the kept `work/<slug>` branch remains for
- * recovery.
+ * STAMP the {@link LockKeptFor} `propose-pr` marker on a held lock (task
+ * `wire-merge-questions-into-the-advance-tick`, decision 4): a propose land
+ * that keeps the build's lock held "until the PR merges" calls this, so the lock
+ * says it is kept for a propose PR and no longer covers a live build. The entry
+ * keeps its `action`, `holder` and `since`; the ref is replaced by a leased CAS
+ * (never forced), so a concurrent change is `lost`. Idempotent: a lock that
+ * already carries the marker is `transitioned` without a write.
  */
-export async function requeueItemLock(
-	opts: ReleaseOptions,
+export async function markLockKeptForProposePr(
+	opts: MarkProposeKeptOptions,
 ): Promise<TransitionResult> {
 	const arbiter = opts.arbiter ?? 'origin';
-	const env = opts.env;
-	const cwd = opts.cwd;
+	const {cwd, env} = opts;
 	if (!opts.item) {
 		return {outcome: 'error', entry: '', ref: '', message: 'missing item'};
 	}
@@ -898,34 +930,155 @@ export async function requeueItemLock(
 				outcome: 'not-held',
 				entry,
 				ref,
-				message: `'${entry}' not locked`,
+				message: `'${entry}' not locked; nothing to mark`,
 			};
 		}
-		const del = await gitSoft(
-			[
-				'push',
+		if (opts.expectedSha !== undefined && held.sha !== opts.expectedSha) {
+			return {
+				outcome: 'lost',
+				entry,
+				ref,
+				message: `'${entry}' now points at ${held.sha}, not ${opts.expectedSha}; not marked`,
+			};
+		}
+		if (held.lock.keptFor === 'propose-pr') {
+			return {
+				outcome: 'transitioned',
+				entry,
+				ref,
+				message: `'${entry}' is already kept for a propose PR`,
+				lock: held.lock,
+			};
+		}
+		const lock: LockEntry = {...held.lock, keptFor: 'propose-pr'};
+		const commit = await buildLockCommit(lock, cwd, env);
+		const push = await refWrite.replaceLockRef({
+			arbiter,
+			ref,
+			commit,
+			expectedSha: held.sha,
+			cwd,
+			env,
+		});
+		if (push.status !== 0) {
+			return {
+				outcome: 'lost',
+				entry,
+				ref,
+				message: `marking '${entry}' kept for a propose PR was rejected: ${push.stderr.trim()}`,
+			};
+		}
+		return {
+			outcome: 'transitioned',
+			entry,
+			ref,
+			message: `marked '${entry}' kept for a propose PR`,
+			lock,
+		};
+	} catch (err) {
+		return {
+			outcome: 'error',
+			entry,
+			ref,
+			message: err instanceof Error ? err.message : String(err),
+		};
+	}
+}
+
+export interface TakeOverProposeKeptOptions {
+	/** The NAMESPACED item identity (same forms as {@link AcquireOptions.item}). */
+	item: string;
+	/** The action the taken-over lock is held for (the answered merge: `advance`). */
+	action: LockAction;
+	cwd: string;
+	arbiter?: string;
+	holder?: string;
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * TAKE OVER a lock that a finished propose build of the SAME item keeps held
+ * (task `wire-merge-questions-into-the-advance-tick`, decisions 2 and 4): the
+ * answered-merge lock phase calls this when the create-only acquire found the
+ * item locked. It succeeds ONLY when the held entry carries the
+ * {@link LockKeptFor} `propose-pr` marker and was taken for `implement` (the
+ * propose build's own claim); the ref is then replaced, leased on the sha read,
+ * by a fresh `action` hold without the marker, so the rest of the run owns it
+ * exactly like a lock it created. Any other held lock (a live build, a tasking,
+ * another advance) is `lost`, as the plain acquire reports it. A lock released
+ * meanwhile falls back to the plain create-only acquire.
+ */
+export async function takeOverProposeKeptLock(
+	opts: TakeOverProposeKeptOptions,
+): Promise<AcquireResult> {
+	const arbiter = opts.arbiter ?? 'origin';
+	const {cwd, env} = opts;
+	if (!opts.item) {
+		return {outcome: 'error', entry: '', ref: '', message: 'missing item'};
+	}
+	const entry = lockEntryFor(opts.item);
+	const ref = itemLockRef(entry);
+	try {
+		const held = await fetchHeldEntry(entry, ref, cwd, arbiter, env);
+		if (!held) {
+			return acquireItemLock({
+				item: opts.item,
+				action: opts.action,
+				cwd,
 				arbiter,
-				'--delete',
+				holder: opts.holder,
+				env,
+			});
+		}
+		if (
+			held.lock.keptFor !== 'propose-pr' ||
+			held.lock.action !== 'implement' ||
+			held.lock.entry !== entry
+		) {
+			return {
+				outcome: 'lost',
+				entry,
 				ref,
-				`--force-with-lease=${ref}:${held.sha}`,
-			],
+				message:
+					`'${entry}' is already locked (${held.lock.action}, not kept for a ` +
+					'propose PR): a live hold is never taken over. Back off.',
+			};
+		}
+		const holder = opts.holder ?? (await resolveHolder(cwd, env));
+		const commit = await buildLockCommit(
+			{
+				entry,
+				action: opts.action,
+				state: 'active',
+				holder,
+				since: new Date().toISOString(),
+			},
 			cwd,
 			env,
 		);
-		if (del.status === 0) {
-			await gitSoft(['update-ref', '-d', ref], cwd, env);
+		const push = await refWrite.replaceLockRef({
+			arbiter,
+			ref,
+			commit,
+			expectedSha: held.sha,
+			cwd,
+			env,
+		});
+		if (push.status !== 0) {
 			return {
-				outcome: 'transitioned',
+				outcome: 'lost',
 				entry,
 				ref,
-				message: `requeued ${entry} (lock released, body still in pool)`,
+				message: `taking over '${entry}' lost the race: ${push.stderr.trim()}`,
 			};
 		}
+		// Keep the local copy in step, as the create-only acquire's fetch would.
+		await gitSoft(['update-ref', ref, commit], cwd, env);
 		return {
-			outcome: 'lost',
+			outcome: 'acquired',
 			entry,
 			ref,
-			message: `'${entry}' lock changed concurrently (CAS lost). Back off.`,
+			message: `took over '${entry}' from its finished propose build (kept for a propose PR)`,
 		};
 	} catch (err) {
 		return {
@@ -2410,6 +2563,65 @@ export async function heldTaskSlugsStrict(
 	);
 }
 
+/**
+ * STRICT (fail-CLOSED) twin of {@link listItemLockEntries}: THROWS when the
+ * lock refs cannot be read (the same fetch {@link listItemLocks} does), so a
+ * caller that ACTS on the absence of a lock (the merge-question surfacer asks
+ * about a branch only when no live build holds its item) never mistakes an
+ * unreadable arbiter for "no locks". A held ref whose body does not parse is
+ * returned as a plain `implement` hold without the marker (a live build: the
+ * safe reading).
+ */
+export async function listItemLockEntriesStrict(
+	cwd: string,
+	arbiter = 'origin',
+	env?: NodeJS.ProcessEnv,
+): Promise<LockEntry[]> {
+	const names = await listItemLocks(cwd, arbiter, env);
+	const entries: LockEntry[] = [];
+	for (const entry of names) {
+		const show = await gitSoft(
+			['show', `${itemLockRef(entry)}:lock.md`],
+			cwd,
+			env,
+		);
+		const lock = show.status === 0 ? parseLockEntry(show.stdout) : undefined;
+		entries.push(
+			lock ?? {
+				entry,
+				action: 'implement',
+				state: 'active',
+				holder: '',
+				since: '',
+			},
+		);
+	}
+	return entries;
+}
+
+/**
+ * The TASK slugs whose lock a finished propose build keeps held, i.e. whose
+ * entry carries the {@link LockKeptFor} `propose-pr` marker (task
+ * `wire-merge-questions-into-the-advance-tick`, decision 6). Selection uses it
+ * to let an answered `merge` through the held-slug subtraction; the
+ * merge-question surfacer to tell a finished propose build from a live one.
+ * GRACEFUL: a read fault yields an empty set, so a held lock keeps excluding
+ * its item (the safe direction).
+ */
+export async function proposeKeptTaskSlugs(
+	cwd: string,
+	arbiter = 'origin',
+	env?: NodeJS.ProcessEnv,
+): Promise<Set<string>> {
+	const entries = await listItemLockEntries(cwd, arbiter, env);
+	const prefix = 'task-';
+	return new Set(
+		entries
+			.filter((e) => e.keptFor === 'propose-pr' && e.entry.startsWith(prefix))
+			.map((e) => e.entry.slice(prefix.length)),
+	);
+}
+
 /**
  * List the SPEC slugs currently lock-held on the arbiter — the held-SPEC set the
  * TASKABLE-spec pool readers SUBTRACT (fix
@@ -2492,6 +2704,10 @@ export function parseLockEntry(body: string): LockEntry | undefined {
 		state: 'active',
 		holder: fields.holder ?? '',
 		since: fields.since ?? '',
+		// Only the one known marker value is read; anything else is a live hold.
+		...(fields.keptFor === 'propose-pr'
+			? {keptFor: 'propose-pr' as const}
+			: {}),
 	};
 }