mandrel 2.2.0 → 2.4.0

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -159,6 +159,68 @@ export async function emitRuntimeFriction({
   }
 }
 
+/**
+ * Emit the recovery counterpart of a `story-blocked` record when a Story
+ * leaves `agent::blocked` for an active state (Story #4622).
+ *
+ * A transient block that self-resolves — lease contention or a stale label
+ * read under concurrent shared-checkout pressure (swarm-os friction #581) —
+ * still fired a `story-blocked` record at the block flip, which the retro
+ * composer counts toward the `story-blocked` recurrence total exactly like a
+ * terminal block. This emits a companion `story-blocked` record carrying the
+ * `details.recovered: true` discriminator, so the composer can net the whole
+ * incident out (see `retro-proposals.js`). The category is deliberately kept
+ * as `story-blocked` rather than a new bucket: a distinct category would
+ * itself aggregate into a routable proposal, re-introducing the noise.
+ *
+ * Best-effort; never throws.
+ *
+ * @param {object} args
+ * @param {number} args.storyId
+ * @param {string} [args.fromState] The state parked at (`agent::blocked`).
+ * @param {string} [args.toState]   The active state recovered into.
+ * @param {object} [args.config]
+ * @returns {Promise<boolean>} true when a record was appended.
+ */
+export async function emitBlockRecoveredFriction({
+  storyId,
+  fromState,
+  toState,
+  config,
+} = {}) {
+  return emitRuntimeFriction({
+    storyId,
+    category: RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED,
+    tool: 'transitionTicketState',
+    details: {
+      recovered: true,
+      fromState: fromState ?? null,
+      toState: toState ?? null,
+    },
+    config,
+  });
+}
+
+/**
+ * Pure predicate: is this signal a recovery-marked `story-blocked` record?
+ * Shared with the retro composer so the "recovered" discriminator is read
+ * from one place. A record is a recovery marker when its category is
+ * `story-blocked` and `details.recovered === true`.
+ *
+ * @param {object} signal
+ * @returns {boolean}
+ */
+export function isRecoveredBlockSignal(signal) {
+  return (
+    signal !== null &&
+    typeof signal === 'object' &&
+    signal.category === RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED &&
+    signal.details !== null &&
+    typeof signal.details === 'object' &&
+    signal.details.recovered === true
+  );
+}
+
 /**
  * Decide whether a `story-deliver-terminal` envelope is worth a friction
  * record, and describe it. **Pure** — no I/O — so the (interesting) policy

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -62,7 +62,7 @@ function normalizeIssueLabels(issue) {
  *
  * @param {object} issue
  * @param {number} [requestedId] The id the operator asked for, for error text.
- * @returns {{ id, title, body, url, labels, state }}
+ * @returns {{ id, title, body, url, labels, state, assignees }}
  */
 export function toStoryRecord(issue, requestedId) {
   const id = Number(issue?.number ?? issue?.id ?? requestedId);
@@ -93,6 +93,14 @@ export function toStoryRecord(issue, requestedId) {
     url: issue?.html_url ?? issue?.url ?? null,
     labels,
     state: String(issue?.state ?? 'open').toLowerCase(),
+    // The assignee list carries the Story lease (`ticket-lease.js`): its sole
+    // assignee is the operator that owns the in-flight run. The probe reads it
+    // to withhold a Story another operator holds (`live-probe.js`), so it is
+    // threaded onto the record here rather than dropped. `issueToTicket`
+    // already reduces assignees to bare login strings; keep only those.
+    assignees: Array.isArray(issue?.assignees)
+      ? issue.assignees.filter((a) => typeof a === 'string' && a.length > 0)
+      : [],
   };
 }
 

package/.agents/scripts/lib/orchestration/retro-proposals.js

@@ -34,6 +34,11 @@
  * @typedef {Object} FrictionSignal
  * @property {string} category   Free-form bucket (e.g. `"lint-loop"`).
  * @property {"framework"|"consumer"} source
+ * @property {number} [storyId]  Emitting Story id (used to net out recovered
+ *                               `story-blocked` incidents — Story #4622).
+ * @property {object} [details]  Kind-specific payload; a `story-blocked`
+ *                               record with `details.recovered === true` is a
+ *                               recovery marker.
  *
  * @typedef {Object} BlockedEvent
  * @property {number} ticketId
@@ -68,6 +73,11 @@
  * @property {DiscardedItem[]}  discarded
  */
 
+import {
+  isRecoveredBlockSignal,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../observability/runtime-friction.js';
+
 /**
  * Empty result helper — returned for zero-input callers so the consumer
  * never needs to defensively spread undefineds.
@@ -89,6 +99,44 @@ function asString(value) {
   return value.trim();
 }
 
+/**
+ * Net transient (self-resolved) blocks out of the signal stream before it is
+ * aggregated (Story #4622).
+ *
+ * A `blocked → active` recovery emits a `story-blocked` record carrying
+ * `details.recovered === true`. When a Story has such a marker, its block was
+ * transient — lease contention or a stale label read under concurrent
+ * shared-checkout pressure (swarm-os friction #581) that cleared on a later
+ * beat — not a terminal HITL pause. This drops **every** `story-blocked`
+ * record for such a Story (both the original block and its recovery marker),
+ * so the retro counts only Stories still parked at `agent::blocked`.
+ *
+ * The netting is by `storyId`, not 1:1 pairing: a Story that ever recovered
+ * from a block in the run is treated as non-terminal for the whole run. That
+ * is a deliberate coarsening — the aggregate is a routing heuristic, not an
+ * incident ledger, and the signal stream carries no reliable ordering to
+ * reconstruct interleaved block/recover cycles. Non-`story-blocked` records
+ * and Stories with no recovery marker pass through untouched.
+ *
+ * @param {FrictionSignal[]} signals
+ * @returns {FrictionSignal[]}
+ */
+function netOutRecoveredBlocks(signals) {
+  const recoveredStoryIds = new Set();
+  for (const sig of signals) {
+    if (isRecoveredBlockSignal(sig) && Number.isInteger(sig.storyId)) {
+      recoveredStoryIds.add(sig.storyId);
+    }
+  }
+  if (recoveredStoryIds.size === 0) return signals;
+  return signals.filter((sig) => {
+    if (sig === null || typeof sig !== 'object') return true;
+    const isBlocked =
+      sig.category === RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED;
+    return !(isBlocked && recoveredStoryIds.has(sig.storyId));
+  });
+}
+
 /**
  * Aggregate friction signals by `category`, tracking per-source counts and
  * arrival order so we can pick a dominant source deterministically.
@@ -403,7 +451,7 @@ export function composeRoutedProposals(input) {
   } = normalised;
 
   return routeCategoryBuckets({
-    byCategory: aggregateByCategory(signals),
+    byCategory: aggregateByCategory(netOutRecoveredBlocks(signals)),
     blockedForceActionable: blockedForceMap(unresolvedBlockedEvents),
     anchorId,
     anchorKind,

package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js

@@ -29,8 +29,11 @@
  * is best-effort and records its own reason.
  */
 
+import path from 'node:path';
+
 import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
 import { Logger } from '../../../Logger.js';
+import { acquireLockWithWait as defaultAcquireLockWithWait } from '../../../single-story-sweep/sweep-lock.js';
 import {
   executeFastForward as defaultExecuteFastForward,
   planFastForward as defaultPlanFastForward,
@@ -38,6 +41,21 @@ import {
 import { reassertStatusColumn as defaultReassertStatusColumn } from '../../reassert-status-column.js';
 import { captureStoryFollowUps as defaultCaptureStoryFollowUps } from '../../story-follow-ups.js';
 
+/**
+ * Lockfile that serializes the local-checkout git mutations of the land tail
+ * across concurrent closes. Keyed on the **main checkout** (never a
+ * worktree): every concurrent `single-story-close` runs its tail against the
+ * same `cwd`, so anchoring the lock under that checkout's `.git` directory
+ * makes them all contend on one file. `.git` is always present, is one per
+ * checkout, and is never itself tracked, so it is a safe rendezvous home.
+ *
+ * @param {string} cwd Main checkout root.
+ * @returns {string}
+ */
+function postLandLockPath(cwd) {
+  return path.join(cwd, '.git', 'mandrel-post-land-tail.lock');
+}
+
 /**
  * Run one tail step, converting any throw into a `false` + reason. Keeps
  * each step's own body free of defensive boilerplate while guaranteeing the
@@ -210,6 +228,19 @@ async function stepBaseFastForward({
  * after the ref reap so `git branch -D` is not fighting a checkout that just
  * moved HEAD.
  *
+ * **Cross-process serialization (Story #4622).** The two local-checkout
+ * mutations — `stepRefCleanup` (`git branch -D`) and `stepBaseFastForward`
+ * (fast-forward `baseBranch`) — run inside a best-effort cross-process lock
+ * keyed on the main checkout. Under concurrent delivery (multiple
+ * story-workers closing against one shared checkout + per-Story worktrees),
+ * an unserialized tail races on the `main` ref and the worktree registry —
+ * the `refCleanup:false` ("used by worktree") / `baseFastForward:false`
+ * ("not-fast-forward") signature reported in swarm-os friction #579. The
+ * GitHub-touching steps stay OUTSIDE the lock so a contended checkout never
+ * delays them. The lock is never load-bearing: on sustained contention the
+ * bounded wait expires and the mutations run anyway (proceeding is the same
+ * best-effort contract every tail step already has).
+ *
  * @param {object} args
  * @param {number} args.storyId
  * @param {string} args.storyBranch
@@ -223,6 +254,7 @@ async function stepBaseFastForward({
  * @param {Function} [args.gitSpawnFn]              Test seam.
  * @param {Function} [args.planFastForwardFn]       Test seam.
  * @param {Function} [args.executeFastForwardFn]    Test seam.
+ * @param {Function} [args.acquireLockWithWaitFn]   Test seam.
  * @returns {Promise<{ followUps: boolean, statusResync: boolean, refCleanup: boolean, baseFastForward: boolean, details: Record<string, string|null> }>}
  */
 export async function runPostLandTail({
@@ -238,6 +270,7 @@ export async function runPostLandTail({
   gitSpawnFn = defaultGitSpawn,
   planFastForwardFn = defaultPlanFastForward,
   executeFastForwardFn = defaultExecuteFastForward,
+  acquireLockWithWaitFn = defaultAcquireLockWithWait,
 }) {
   progress?.('POST-LAND', `🧾 Running land tail for Story #${storyId}...`);
 
@@ -264,21 +297,46 @@ export async function runPostLandTail({
       }),
     { name: 'status-column resync', progress },
   );
-  const refCleanup = await step(
-    () => stepRefCleanup({ cwd, storyBranch, progress, gitSpawnFn }),
-    { name: 'local ref cleanup', progress },
-  );
-  const baseFastForward = await step(
-    () =>
-      stepBaseFastForward({
-        cwd,
-        baseBranch,
-        progress,
-        planFastForwardFn,
-        executeFastForwardFn,
-      }),
-    { name: 'base fast-forward', progress },
-  );
+  // Local-checkout mutations: serialized behind a best-effort cross-process
+  // lock (Story #4622). Acquire once, run both steps, release in `finally`.
+  const lockCfg = config?.delivery?.postLandLock ?? {};
+  const lock = await acquireLockWithWaitFn({
+    lockPath: postLandLockPath(cwd),
+    waitMs: lockCfg.waitMs,
+    pollMs: lockCfg.pollMs,
+    timeoutMs: lockCfg.timeoutMs,
+    ownerId: `post-land-${storyId}`,
+  });
+  if (!lock.acquired) {
+    // Never load-bearing: proceed anyway. The bounded wait already gave the
+    // concurrent holder its window; blocking the land on a lock we could not
+    // take would turn a best-effort damper into a false negative.
+    progress?.(
+      'POST-LAND',
+      `⚠️ post-land lock not acquired (${lock.reason}); proceeding unserialized.`,
+    );
+  }
+  let refCleanup;
+  let baseFastForward;
+  try {
+    refCleanup = await step(
+      () => stepRefCleanup({ cwd, storyBranch, progress, gitSpawnFn }),
+      { name: 'local ref cleanup', progress },
+    );
+    baseFastForward = await step(
+      () =>
+        stepBaseFastForward({
+          cwd,
+          baseBranch,
+          progress,
+          planFastForwardFn,
+          executeFastForwardFn,
+        }),
+      { name: 'base fast-forward', progress },
+    );
+  } finally {
+    if (lock.acquired) lock.release();
+  }
 
   const tail = {
     followUps: followUps.ok,

package/.agents/scripts/lib/orchestration/ticket-lease.js

@@ -211,6 +211,16 @@ export async function describeLease(opts) {
  *                                     `reason: 'reclaimed'`.
  *   - Foreign claim + `steal:true` → reassign operator, `acquired: true`,
  *                                     `reason: 'stolen'`.
+ *   - Lost a write race            → a foreign login co-assigned between our
+ *                                     PATCH and the verify re-read; back the
+ *                                     operator out, `acquired: false`,
+ *                                     `owner: <foreign>`, `reason: 'lost-race'`.
+ *
+ * Every claiming write is verified: GitHub's assignee PATCH is not a
+ * compare-and-set, so two runs that both read the ticket unassigned will both
+ * write themselves. {@link claimAndVerify} re-reads after the write and refuses
+ * (fail-closed) when a foreign login is present, so the loser of a simultaneous
+ * claim never proceeds as though it holds the lease.
  *
  * @param {object} opts
  * @param {object} opts.provider              Ticketing provider.
@@ -225,7 +235,7 @@ export async function describeLease(opts) {
  *   acquired: boolean,
  *   owner: string,
  *   previousOwner: string|null,
- *   reason: 'unclaimed'|'already-held'|'reclaimed'|'stolen'|'held',
+ *   reason: 'unclaimed'|'already-held'|'reclaimed'|'stolen'|'held'|'lost-race',
  * }>}
  */
 export async function acquireLease(opts) {
@@ -240,13 +250,13 @@ export async function acquireLease(opts) {
 
   // Unclaimed → take it.
   if (owner === null) {
-    await provider.updateTicket(ticketId, { assignees: [operator] });
-    return {
-      acquired: true,
-      owner: operator,
+    return claimAndVerify({
+      provider,
+      ticketId,
+      operator,
       previousOwner: null,
       reason: 'unclaimed',
-    };
+    });
   }
 
   // Already ours → no write needed.
@@ -270,12 +280,70 @@ export async function acquireLease(opts) {
     };
   }
 
-  await provider.updateTicket(ticketId, { assignees: [operator] });
-  return {
-    acquired: true,
-    owner: operator,
+  return claimAndVerify({
+    provider,
+    ticketId,
+    operator,
     previousOwner: owner,
     reason: steal && live ? 'stolen' : 'reclaimed',
+  });
+}
+
+/**
+ * Write the operator to a ticket's assignees, then re-read to confirm the
+ * claim actually stuck before reporting success.
+ *
+ * The assignee write is not atomic — GitHub offers no compare-and-set on the
+ * assignees surface — so two runs that both observed the ticket unassigned (or
+ * a stale foreign claim) will both PATCH themselves in. Without a check the
+ * loser of that race returns `acquired: true` and marches into the worktree
+ * the winner is already building. The verify closes that window: it re-reads
+ * with `fresh: true` (bypassing any provider cache so it sees the other run's
+ * write, not our own), and if a foreign login is present it concedes — removes
+ * the operator from the assignee set so no phantom co-owner lingers, and
+ * returns `acquired: false` / `reason: 'lost-race'` so the fail-closed caller
+ * refuses. A clean read (assignees exactly `[operator]`) confirms the claim.
+ *
+ * It does not eliminate the race — two writes still happen — but it makes the
+ * outcome deterministic: exactly one operator survives as the sole assignee,
+ * and the other is told it lost.
+ *
+ * @param {object} args
+ * @param {object} args.provider              Ticketing provider.
+ * @param {number} args.ticketId              Ticket being claimed.
+ * @param {string} args.operator              Operator acquiring the lease.
+ * @param {string|null} args.previousOwner    Owner before this write (for the result).
+ * @param {string} args.reason                Success reason when the claim holds.
+ * @returns {Promise<{ acquired: boolean, owner: string, previousOwner: string|null, reason: string }>}
+ */
+async function claimAndVerify({
+  provider,
+  ticketId,
+  operator,
+  previousOwner,
+  reason,
+}) {
+  await provider.updateTicket(ticketId, { assignees: [operator] });
+
+  const after = await provider.getTicket(ticketId, { fresh: true });
+  const assignees = Array.isArray(after?.assignees) ? after.assignees : [];
+  const foreign = assignees.filter((login) => login !== operator);
+
+  if (foreign.length === 0) {
+    return { acquired: true, owner: operator, previousOwner, reason };
+  }
+
+  // A foreign login co-assigned after our write — we lost a simultaneous
+  // claim. Back ourselves out so the winner is the sole assignee, and report
+  // the loss so the fail-closed caller refuses rather than double-delivering.
+  await provider
+    .updateTicket(ticketId, { assignees: foreign })
+    .catch(() => undefined);
+  return {
+    acquired: false,
+    owner: foreign[0],
+    previousOwner,
+    reason: 'lost-race',
   };
 }
 

package/.agents/scripts/lib/orchestration/ticketing/transition.js

@@ -38,6 +38,7 @@ import {
   renderTransitionMessage,
 } from '../../notifications/notifier.js';
 import {
+  emitBlockRecoveredFriction,
   emitRuntimeFriction,
   RUNTIME_FRICTION_CATEGORIES,
 } from '../../observability/runtime-friction.js';
@@ -122,20 +123,41 @@ function validateTransitionInputs(newState) {
   return newState;
 }
 
+/**
+ * Active states a `agent::blocked` Story can recover into (Story #4622). A
+ * `blocked → {executing|ready}` transition is a self-resolved block; every
+ * other target (`done`, `closing`) is a real terminal outcome, not a
+ * recovery.
+ */
+const BLOCK_RECOVERY_TARGETS = [STATE_LABELS.EXECUTING, STATE_LABELS.READY];
+
 /**
  * Resolve the pre-transition ticket snapshot that drives the notify
  * payload and the provider's label-merge path. Honors the caller-supplied
  * `opts.ticketSnapshot` (Story #1795) when present; otherwise issues a
  * best-effort `getTicket` and returns `null` on transient failure.
  *
+ * The snapshot is loaded when a caller threads `notify` (its `fromState`
+ * feeds the notification payload) OR when `needFromState` is set — Story
+ * #4622's recovery detection needs the *prior* state, and `getTicket` after
+ * `updateTicket` would already read the new label. Bounding the extra read
+ * to recovery-target transitions keeps every other flip on the snapshot-free
+ * fast path.
+ *
  * @param {object} provider
  * @param {{ notify?: Function, ticketSnapshot?: object|null }} opts
  * @param {number} ticketId
+ * @param {boolean} [needFromState]
  * @returns {Promise<object|null>}
  */
-async function loadTicketSnapshot(provider, opts, ticketId) {
+async function loadTicketSnapshot(provider, opts, ticketId, needFromState) {
   if (opts.ticketSnapshot) return opts.ticketSnapshot;
-  if (!opts.notify || typeof provider.getTicket !== 'function') return null;
+  if (
+    (!opts.notify && !needFromState) ||
+    typeof provider.getTicket !== 'function'
+  ) {
+    return null;
+  }
   try {
     return await provider.getTicket(ticketId);
   } catch (err) {
@@ -301,26 +323,50 @@ function dispatchTransitionNotification(args) {
  * (see `frictionForTerminal`): the two would otherwise count one incident
  * twice.
  *
- * Best-effort and awaited: `emitRuntimeFriction` swallows its own failures
- * and resolves `false`, so this can neither throw nor block the transition.
+ * Story #4622 extends the hook to the inverse edge: a `blocked → active`
+ * transition emits a recovery marker so a transient block that self-resolved
+ * can be netted out of the retro's `story-blocked` recurrence total.
+ *
+ * Best-effort and awaited: the friction emitters swallow their own failures
+ * and resolve `false`, so this can neither throw nor block the transition.
  * It is awaited rather than fire-and-forget because CLI entry points exit
  * via `process.exit` as soon as `main` resolves (`cli-utils.runAsCli` with
  * `propagateExitCode`), which would discard a still-pending append.
  *
  * @param {number} ticketId
+ * @param {string|null} fromState  Prior state label, or null.
  * @param {string} newState
  * @param {{ config?: object }} opts
  * @returns {Promise<void>}
  */
-async function emitBlockedFriction(ticketId, newState, opts) {
-  if (newState !== STATE_LABELS.BLOCKED) return;
-  await emitRuntimeFriction({
-    storyId: ticketId,
-    category: RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED,
-    tool: 'transitionTicketState',
-    details: { toState: newState },
-    config: opts?.config,
-  });
+async function emitBlockedFriction(ticketId, fromState, newState, opts) {
+  if (newState === STATE_LABELS.BLOCKED) {
+    await emitRuntimeFriction({
+      storyId: ticketId,
+      category: RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED,
+      tool: 'transitionTicketState',
+      details: { toState: newState },
+      config: opts?.config,
+    });
+    return;
+  }
+  // Story #4622 — a transition *out* of `agent::blocked` into an active state
+  // is a recovery: the earlier block self-resolved. Emit its recovery marker
+  // so the retro composer can net the transient block out of the
+  // `story-blocked` recurrence total (swarm-os friction #581). Only a genuine
+  // block→active recovery qualifies; blocked→done/closing is a real
+  // terminal outcome, not a recovery, so it is left counted.
+  if (
+    fromState === STATE_LABELS.BLOCKED &&
+    BLOCK_RECOVERY_TARGETS.includes(newState)
+  ) {
+    await emitBlockRecoveredFriction({
+      storyId: ticketId,
+      fromState,
+      toState: newState,
+      config: opts?.config,
+    });
+  }
 }
 
 /**
@@ -382,7 +428,12 @@ export async function transitionTicketState(
   // snapshot is also forwarded to `provider.updateTicket` so the label
   // merge path skips its own `getTicket` call (the second of the two
   // round-trips this seam eliminates).
-  const ticketSnapshot = await loadTicketSnapshot(provider, opts, ticketId);
+  const ticketSnapshot = await loadTicketSnapshot(
+    provider,
+    opts,
+    ticketId,
+    BLOCK_RECOVERY_TARGETS.includes(newState),
+  );
   const fromState =
     ticketSnapshot?.labels?.find((l) => ALL_STATES.includes(l)) ?? null;
 
@@ -406,8 +457,9 @@ export async function transitionTicketState(
   });
 
   // Story #4578 — derive a friction signal from the block, at the point the
-  // runtime already knows. Best-effort; never blocks the transition.
-  await emitBlockedFriction(ticketId, newState, opts);
+  // runtime already knows. Story #4622 also emits the recovery marker on the
+  // inverse block→active transition. Best-effort; never blocks the transition.
+  await emitBlockedFriction(ticketId, fromState, newState, opts);
 
   // Story #2548 — mirror the new state onto the Projects v2 Status
   // column. Best-effort; never blocks the transition.

package/.agents/scripts/lib/single-story-sweep/sweep-lock.js

@@ -167,3 +167,76 @@ function buildAcquired(lockPath, ownerId, fsImpl) {
   }
   return { acquired: true, release, ownerId };
 }
+
+const DEFAULT_WAIT_MS = 8_000;
+const DEFAULT_POLL_MS = 150;
+
+/**
+ * Promise-based delay. Injectable so tests can drive the wait loop on a fake
+ * clock without a real timer.
+ *
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function defaultSleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/**
+ * Bounded-wait wrapper over {@link acquireSweepLock}.
+ *
+ * `acquireSweepLock` is single-attempt on purpose: a *skipped* sweep is
+ * harmless, so the sweep caller proceeds immediately on contention. The
+ * post-land tail is the opposite case — proceeding immediately IS the race
+ * two concurrent closes hit on a shared main checkout — so this wrapper
+ * polls the primitive with short backoff up to `waitMs` before giving up.
+ *
+ * It is still **never load-bearing**: on `waitMs` exhaustion it returns
+ * `{ acquired: false, reason: 'contended-after-wait' }` and the caller is
+ * expected to proceed anyway. The bounded wait is a best-effort collision
+ * damper, not a mutual-exclusion guarantee. A hard I/O error short-circuits
+ * the loop (spinning would just re-hit it).
+ *
+ * @param {object} opts
+ * @param {string} opts.lockPath
+ * @param {number} [opts.waitMs]     Max total time to wait for the lock.
+ * @param {number} [opts.pollMs]     Delay between acquire attempts.
+ * @param {number} [opts.timeoutMs]  Stale-lock expiry, forwarded to the
+ *                                   underlying acquire.
+ * @param {string} [opts.ownerId]
+ * @param {() => number} [opts.nowFn]
+ * @param {(ms: number) => Promise<void>} [opts.sleepFn]
+ * @param {object} [opts.fsImpl]
+ * @returns {Promise<{ acquired: true, release: () => void, ownerId: string }
+ *          | { acquired: false, reason: 'contended-after-wait' | 'error', detail?: string }>}
+ */
+export async function acquireLockWithWait({
+  lockPath,
+  waitMs = DEFAULT_WAIT_MS,
+  pollMs = DEFAULT_POLL_MS,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  ownerId,
+  nowFn = Date.now,
+  sleepFn = defaultSleep,
+  fsImpl = fs,
+} = {}) {
+  const deadline = nowFn() + Math.max(0, waitMs);
+  for (;;) {
+    const res = acquireSweepLock({
+      lockPath,
+      timeoutMs,
+      ownerId,
+      nowFn,
+      fsImpl,
+    });
+    if (res.acquired) return res;
+    // A hard error will not resolve by retrying — surface it immediately.
+    if (res.reason === 'error') return res;
+    if (nowFn() >= deadline) {
+      return { acquired: false, reason: 'contended-after-wait' };
+    }
+    await sleepFn(Math.max(0, pollMs));
+  }
+}