mandrel 2.3.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));
+  }
+}

package/.agents/scripts/lib/wave-runner/live-probe.js

@@ -25,11 +25,16 @@
  *     labels, **unioned with the ids the host says it has dispatched**
  *     (`--dispatched`). The label alone is not sufficient: the kernel's
  *     contract counts "executing / closing / dispatched-not-yet-labelled" as
- *     in-flight, and `single-story-init.js` flips `agent::executing` at step 6
- *     of 6 — *after* a 3–6 minute worktree install. For that whole window a
- *     dispatched Story still reads `agent::ready`, so a label-only derivation
- *     re-emits it in the next beat's `ready[]` and the host dispatches it a
- *     second time onto the same branch and worktree (Story #4601).
+ *     in-flight, and there is still a window between the host spawning a
+ *     sub-agent and that sub-agent's `single-story-init.js` publishing the
+ *     `agent::executing` label. Story #4620 shrank that window sharply — the
+ *     flip now lands before the multi-minute worktree install rather than
+ *     after it — but it is not zero (init still runs the lease acquire and a
+ *     branch fetch first), so a label-only derivation could still re-emit a
+ *     just-dispatched Story in the next beat's `ready[]` and dispatch it a
+ *     second time onto the same branch (Story #4601). `--dispatched` closes
+ *     the residual window; foreign runs are covered by the assignee lease
+ *     (see `deriveForeignHeld`).
  *   - **blocked** — the ids carrying `agent::blocked`. `classifyStory` has
  *     always returned this class; nothing consumed it, so a blocked Story was
  *     neither done, ready, nor in-flight and the beat reported a permanent
@@ -56,6 +61,10 @@ import {
 } from '../../resolve-stories.js';
 import { AGENT_LABELS } from '../label-constants.js';
 import { buildStoriesEnvelope } from '../orchestration/resolve-stories.js';
+import {
+  currentOwner,
+  normalizeOperatorHandle,
+} from '../orchestration/ticket-lease.js';
 import { classifyStory, storyIdOf } from './ready-set.js';
 
 /**
@@ -67,10 +76,13 @@ import { classifyStory, storyIdOf } from './ready-set.js';
  *   1. **Live labels.** `classifyStory` folds `agent::executing` and
  *      `agent::closing` into one `executing` class — both are in-flight and
  *      neither may be re-dispatched.
- *   2. **`dispatched`** — ids the host has spawned. This closes the init
- *      window: `single-story-init.js` flips `agent::executing` last, after a
- *      3–6 minute install, so between spawn and flip a dispatched Story reads
- *      `agent::ready` and a label-only derivation hands it back as ready.
+ *   2. **`dispatched`** — ids the host has spawned. This closes the residual
+ *      init window: between the host spawning a sub-agent and that agent's
+ *      `single-story-init.js` publishing `agent::executing`, a dispatched Story
+ *      still reads `agent::ready` and a label-only derivation hands it back as
+ *      ready. Story #4620 moved the flip ahead of the worktree install, so the
+ *      window is now short rather than minutes-long, but `--dispatched` still
+ *      covers it deterministically.
  *
  * `dispatched` is deliberately **not** the `--done`-style accounting probe
  * mode retired. Three properties keep it from becoming one:
@@ -129,6 +141,54 @@ function deriveBlockedIds(storyRecords) {
     .sort((a, b) => a - b);
 }
 
+/**
+ * Identify Stories claimed by a **different** operator's lease.
+ *
+ * The Story lease rides the ticket's assignees (`ticket-lease.js`): the sole
+ * assignee is the operator driving that Story's run. `single-story-init.js`
+ * takes the lease at init, but flips `agent::executing` only after a 3–6 minute
+ * worktree install — so for that whole window a Story another operator is
+ * actively delivering still reads `agent::ready` with no in-flight label. A
+ * label-only probe classifies it `ready` and hands it to this run, which then
+ * dispatches into a guaranteed init failure (the fail-closed lease refuses a
+ * foreign assignee) mid-batch. Reading the assignee lets the probe withhold it
+ * up front and report who holds it instead.
+ *
+ * Only Stories that would otherwise be `ready` are considered — a `done`,
+ * `blocked`, or already-`executing` Story is handled by its own class, and a
+ * self-held assignee is this run's own claim and never withholds.
+ *
+ * When `self` is unresolved (no `github.operatorHandle`), foreign cannot be
+ * told from self, so this returns empty and warns once: the probe is a
+ * read-only path that must not fail closed, and init's lease acquire remains
+ * the backstop.
+ *
+ * @param {Array<{id?: number, number?: number, labels?: string[], state?: string, assignees?: string[]}>} storyRecords
+ * @param {string|null|undefined} self  Resolved bare operator login for this run.
+ * @param {(msg: string) => void} [warn]
+ * @returns {Map<number, string>} Foreign-held Story id → holder login.
+ */
+function deriveForeignHeld(storyRecords, self, warn) {
+  const held = new Map();
+  if (!self) {
+    warn?.(
+      '[live-probe] github.operatorHandle is unset (or the shipped ' +
+        '@[USERNAME] placeholder), so a foreign lease cannot be told from ' +
+        'this run’s own claim — skipping assignee-based withholding. ' +
+        'Set your handle in .agentrc.local.json to de-conflict concurrent ' +
+        'runs at probe time; init’s lease still refuses a foreign claim.',
+    );
+    return held;
+  }
+  for (const rec of storyRecords) {
+    const id = storyIdOf(rec);
+    if (id === null || classifyStory(rec) !== 'ready') continue;
+    const owner = currentOwner(rec.assignees);
+    if (owner && owner !== self) held.set(id, owner);
+  }
+  return held;
+}
+
 /**
  * Resolve the provider + repo coordinates the probe reads through.
  *
@@ -138,13 +198,21 @@ function deriveBlockedIds(storyRecords) {
  *
  * @param {object} [deps]
  * @param {Function} [deps.resolveProvider] Injection seam for tests.
- * @returns {{ provider: object, owner: string|undefined, repo: string|undefined }}
+ * @returns {{ provider: object, owner: string|undefined, repo: string|undefined, self: string|null }}
  */
 export function createProbeContext({
   resolveProvider = resolveStoriesProvider,
 } = {}) {
   const { provider, config } = resolveProvider();
-  return { provider, owner: config?.github?.owner, repo: config?.github?.repo };
+  return {
+    provider,
+    owner: config?.github?.owner,
+    repo: config?.github?.repo,
+    // Bare login this run claims leases under. Normalised (leading `@` stripped,
+    // `@[USERNAME]` placeholder → null) so it compares against the bare assignee
+    // logins GitHub returns; `null` disables assignee-based withholding.
+    self: normalizeOperatorHandle(config?.github?.operatorHandle),
+  };
 }
 
 /**
@@ -165,6 +233,10 @@ export function createProbeContext({
  * @param {boolean} [args.native=true]   Read native `blocked_by` edges.
  * @param {number[]} [args.dispatched=[]] Ids the host has spawned but may not
  *   yet have observed labelled `agent::executing` (see `deriveInFlightIds`).
+ * @param {string|null} [args.self]     Resolved bare operator login for this
+ *   run, used to withhold Stories another operator's lease holds
+ *   (`deriveForeignHeld`). Absent/unresolved → assignee-based withholding is
+ *   skipped (the probe never fails closed).
  * @param {(msg: string) => void} [args.warn]
  * Each returned node carries its **live labels**. That is load-bearing, not
  * decoration: `selectReadySet` classifies from labels, so a node stripped of
@@ -177,7 +249,8 @@ export function createProbeContext({
  *   nodes: Array<{id: number, dependsOn: number[], files: string[], labels: string[]}>,
  *   doneIds: Set<number>,
  *   inFlight: number,
- *   blockedIds: number[]
+ *   blockedIds: number[],
+ *   foreignHeld: Array<{id: number, holder: string}>
  * }>}
  */
 export async function probeLiveState({
@@ -187,6 +260,7 @@ export async function probeLiveState({
   repo,
   native = true,
   dispatched = [],
+  self,
   warn,
 }) {
   const stories = await fetchStories(provider, ids);
@@ -209,6 +283,12 @@ export async function probeLiveState({
 
   const labelsById = new Map(stories.map((s) => [s.id, s.labels ?? []]));
   const inFlightIds = deriveInFlightIds(stories, dispatched);
+  // A Story another operator's lease holds occupies a (global) dispatch slot
+  // just like an in-flight one: fold it into the in-flight set so it is both
+  // withheld (via the projected label) and excluded from a false wedge, but
+  // never dispatched by this run.
+  const foreignHeld = deriveForeignHeld(stories, self, warn);
+  for (const id of foreignHeld.keys()) inFlightIds.add(id);
   return {
     nodes: envelope.dag.map((node) => ({
       ...node,
@@ -220,6 +300,7 @@ export async function probeLiveState({
     doneIds: new Set(envelope.done),
     inFlight: inFlightIds.size,
     blockedIds: deriveBlockedIds(stories),
+    foreignHeld: [...foreignHeld].map(([id, holder]) => ({ id, holder })),
   };
 }
 

package/.agents/scripts/single-story-init.js

@@ -11,14 +11,19 @@
  *
  * What this script does:
  *   1. Validate the Story (type::story, not closed).
- *   2. Fetch origin.
- *   3. Create the Story branch from `project.baseBranch` (default
+ *   2. Acquire the assignee lease, then refuse a Story already labelled
+ *      `agent::executing` this run does not hold (unless `--steal`).
+ *   3. Flip the Story to `agent::executing` — BEFORE provisioning, so the
+ *      claim is label-visible to concurrent operators' probes during the
+ *      multi-minute install window (Story #4620). A provisioning failure after
+ *      this reverts the label and releases the lease.
+ *   4. Fetch origin.
+ *   5. Create the Story branch from `project.baseBranch` (default
  *      `main`) — local-only, no remote push at this stage.
- *   4. Materialise a worktree at `.worktrees/story-<id>/` when worktree
+ *   6. Materialise a worktree at `.worktrees/story-<id>/` when worktree
  *      isolation is enabled; otherwise check out the branch in-place.
- *   5. Upsert a `story-init` structured comment carrying
+ *   7. Upsert a `story-init` structured comment carrying
  *      `standalone: true`.
- *   6. Flip the Story to `agent::executing`.
  *
  * What this script does NOT do:
  *   - Child-Task transitions — a Story is atomic (one branch, one
@@ -55,7 +60,10 @@ import {
   planFastForward,
 } from './lib/orchestration/git-cleanup/phases/fast-forward.js';
 import { verifyRemote } from './lib/orchestration/remote-verifier.js';
-import { acquireStoryLease } from './lib/orchestration/single-story-lease-guard.js';
+import {
+  acquireStoryLease,
+  releaseStoryLease,
+} from './lib/orchestration/single-story-lease-guard.js';
 import { handleRemoteVerificationFailure } from './lib/orchestration/story-init-remote.js';
 import {
   STATE_LABELS,
@@ -127,6 +135,127 @@ export function assertDeliverableStory(story, storyId) {
   }
 }
 
+/**
+ * Defense-in-depth refusal for a Story already labelled `agent::executing`
+ * that this run does not already hold.
+ *
+ * The assignee lease is the primary cross-run guard, but the label and the
+ * assignee can drift apart: a prior run that crashed *after* the early
+ * `agent::executing` flip but *before* (or without) taking/holding the lease
+ * leaves the Story labelled executing with no live foreign lease to trip the
+ * lease preflight. Left unchecked, a fresh run would seed the branch and
+ * worktree straight over that drift. Refuse unless the caller already holds the
+ * lease (`reason === 'already-held'`, i.e. a legitimate idempotent re-init) or
+ * passed `--steal`.
+ *
+ * Runs *after* the lease acquire (so it can read the acquire's reason) but
+ * *before* any git mutation. On refusal it releases the lease this run just
+ * took so the ticket is left exactly as found — a clean state for the operator
+ * to inspect before re-running with `--steal`.
+ *
+ * @param {object} args
+ * @param {{ labels?: string[] }} args.story        Fetched Story ticket.
+ * @param {{ reason: string, previousOwner: string|null }} args.lease  Acquire result.
+ * @param {boolean} args.stealRequested
+ * @param {number} args.storyId
+ * @param {object} args.provider
+ * @param {object} args.config
+ */
+export async function assertNotForeignExecuting({
+  story,
+  lease,
+  stealRequested,
+  storyId,
+  provider,
+  config,
+}) {
+  const labelled =
+    Array.isArray(story?.labels) &&
+    story.labels.includes(STATE_LABELS.EXECUTING);
+  if (!labelled || stealRequested || lease.reason === 'already-held') return;
+
+  // Back out the lease we just took so the refusal leaves the ticket unchanged.
+  try {
+    await releaseStoryLease({ provider, storyId, config });
+  } catch (err) {
+    Logger.error(
+      `[single-story-init] ⚠️ Failed to release lease during executing-refusal: ${err?.message ?? err}`,
+    );
+  }
+  throw new Error(
+    `Story #${storyId} is already labelled agent::executing` +
+      (lease.previousOwner
+        ? ` (assignee @${lease.previousOwner})`
+        : ' with no assignee') +
+      '. Another /deliver run may already own it. Confirm that run is dead, ' +
+      'then re-run with --steal to take it.',
+  );
+}
+
+/**
+ * Publish this run's claim as the `agent::executing` label **before** the
+ * multi-minute worktree install, so a concurrent operator's probe sees the
+ * claim during the install window instead of reading `agent::ready` and
+ * dispatching the Story a second time.
+ *
+ * Best-effort: the assignee lease is the real guard, so a failed flip logs and
+ * proceeds rather than aborting init. Routes through `transitionTicketState`
+ * so the Projects v2 Status column follows the label (Story #2548).
+ *
+ * @param {object} provider
+ * @param {number} storyId
+ * @param {object} story  Prefetched snapshot (round-trip elimination).
+ * @returns {Promise<void>}
+ */
+async function flipStoryToExecuting(provider, storyId, story) {
+  try {
+    await transitionTicketState(provider, storyId, STATE_LABELS.EXECUTING, {
+      ticketSnapshot: story,
+      cascade: false,
+    });
+    progress('LABELS', `🏷️  Story #${storyId} → agent::executing`);
+  } catch (err) {
+    Logger.error(
+      `[single-story-init] ⚠️ Failed to flip Story labels: ${err?.message ?? err}`,
+    );
+  }
+}
+
+/**
+ * Undo this run's claim when provisioning fails after the early
+ * `agent::executing` flip: revert the label to `agent::ready` and release the
+ * lease, both best-effort. Without this a crashed init would strand the Story
+ * as phantom-executing — claimed and labelled in-flight but with no live run —
+ * which every other operator's probe would then withhold indefinitely.
+ *
+ * @param {object} provider
+ * @param {number} storyId
+ * @param {object} config
+ * @returns {Promise<void>}
+ */
+async function rollbackClaimOnInitFailure(provider, storyId, config) {
+  try {
+    await transitionTicketState(provider, storyId, STATE_LABELS.READY, {
+      cascade: false,
+    });
+    progress(
+      'ROLLBACK',
+      `↩️  Reverted Story #${storyId} → agent::ready after init failure`,
+    );
+  } catch (err) {
+    Logger.error(
+      `[single-story-init] ⚠️ Failed to revert label after init failure: ${err?.message ?? err}`,
+    );
+  }
+  try {
+    await releaseStoryLease({ provider, storyId, config });
+  } catch (err) {
+    Logger.error(
+      `[single-story-init] ⚠️ Failed to release lease after init failure: ${err?.message ?? err}`,
+    );
+  }
+}
+
 /**
  * Decide how to seed the Story branch given local / remote presence. Pure and
  * exported for testing (Story #3483 AC3: an existing `story-<id>` branch must
@@ -449,6 +578,11 @@ export async function runSingleStoryInit({
   steal = false,
   leaseNow,
   injectedVerifyRemote,
+  // Story #4620: swap the git-touching provisioning steps so the
+  // early-flip-then-rollback ordering is unit-testable without a real worktree.
+  injectedMaterialize = materializeBaseBranch,
+  injectedSeedBranch = seedStoryBranch,
+  injectedProvisionWorktree = provisionWorktree,
 } = {}) {
   const parsed =
     storyIdParam !== undefined
@@ -523,6 +657,10 @@ export async function runSingleStoryInit({
   // assignee is treated as a live claim and aborts init (naming the current
   // owner) unless --steal forcibly transfers it. Unclaimed / self-held claims
   // proceed. Skipped under --dry-run (no assignee mutation).
+  let workCwd = cwd;
+  let worktreeCreated = false;
+  let installStatus = { status: 'skipped', reason: 'dry-run' };
+
   if (!dryRun) {
     const acquire = injectedAcquireLease ?? acquireStoryLease;
     const lease = await acquire({
@@ -536,31 +674,51 @@ export async function runSingleStoryInit({
       'LEASE',
       `🔒 Story #${storyId} lease ${lease.reason} (owner=@${lease.owner}).`,
     );
-  }
-
-  let workCwd = cwd;
-  let worktreeCreated = false;
-  let installStatus = { status: 'skipped', reason: 'dry-run' };
 
-  if (!dryRun) {
-    await materializeBaseBranch({
-      cwd,
-      baseBranch,
-      storyBranch,
-      config,
-      provider,
-      injectedSweep,
-      progress,
-    });
-    seedStoryBranch({ cwd, storyBranch, baseBranch, progress });
-    ({ workCwd, worktreeCreated, installStatus } = await provisionWorktree({
-      runtime,
-      cwd,
+    // Defense in depth: refuse a Story already labelled agent::executing that
+    // this run does not hold (label/assignee drift the lease alone misses).
+    // Runs before any git mutation; releases the just-taken lease on refusal.
+    await assertNotForeignExecuting({
+      story,
+      lease,
+      stealRequested,
       storyId,
-      storyBranch,
+      provider,
       config,
-      progress,
-    }));
+    });
+
+    // Publish the claim as agent::executing BEFORE the multi-minute worktree
+    // install (not after), so a concurrent operator's probe sees it during the
+    // install window instead of reading agent::ready and double-dispatching.
+    await flipStoryToExecuting(provider, storyId, story);
+
+    // Any failure from here on leaves a claimed, executing-labelled Story with
+    // no live run behind it — revert the label and release the lease so the
+    // Story is not stranded as phantom-executing.
+    try {
+      await injectedMaterialize({
+        cwd,
+        baseBranch,
+        storyBranch,
+        config,
+        provider,
+        injectedSweep,
+        progress,
+      });
+      injectedSeedBranch({ cwd, storyBranch, baseBranch, progress });
+      ({ workCwd, worktreeCreated, installStatus } =
+        await injectedProvisionWorktree({
+          runtime,
+          cwd,
+          storyId,
+          storyBranch,
+          config,
+          progress,
+        }));
+    } catch (err) {
+      await rollbackClaimOnInitFailure(provider, storyId, config);
+      throw err;
+    }
   }
 
   const dependenciesInstalled =
@@ -589,8 +747,9 @@ export async function runSingleStoryInit({
     remoteProbe: { remoteUrl: remote.remoteUrl, detail: remote.detail },
   };
 
-  // Upsert the `story-init` structured comment + flip Story to executing.
-  // Both are no-ops under --dry-run.
+  // Upsert the `story-init` structured comment (no-op under --dry-run). The
+  // `agent::executing` flip already happened above, before provisioning, so the
+  // claim is label-visible during the install window (see `flipStoryToExecuting`).
   if (!dryRun) {
     try {
       await upsertStructuredComment(
@@ -608,27 +767,6 @@ export async function runSingleStoryInit({
         `[single-story-init] ⚠️ Failed to upsert story-init structured comment: ${err?.message ?? err}`,
       );
     }
-
-    try {
-      // Route through the canonical state mutator so the Projects v2
-      // Status column mirrors the label flip (Story #2548 wires column-
-      // sync inside `transitionTicketState`). A direct
-      // `provider.updateTicket({ labels })` would skip the board update
-      // and leave the Story on its prior status column for the entire
-      // run. `cascade: false` is correct — a standalone Story has no
-      // parent chain — and threading the prefetched `story` as
-      // `ticketSnapshot` preserves the round-trip elimination from
-      // Story #1795.
-      await transitionTicketState(provider, storyId, STATE_LABELS.EXECUTING, {
-        ticketSnapshot: story,
-        cascade: false,
-      });
-      progress('LABELS', `🏷️  Story #${storyId} → agent::executing`);
-    } catch (err) {
-      Logger.error(
-        `[single-story-init] ⚠️ Failed to flip Story labels: ${err?.message ?? err}`,
-      );
-    }
   }
 
   Logger.info('\n--- STORY INIT RESULT ---');

package/.agents/scripts/stories-wave-tick.js

@@ -709,12 +709,13 @@ export async function runProbedStoriesWaveTick({
 
   let probed;
   try {
-    const { provider, owner, repo } = context();
+    const { provider, owner, repo, self } = context();
     probed = await probe({
       ids,
       provider,
       owner,
       repo,
+      self,
       dispatched: [...dispatchedIds],
       warn: (m) => Logger.warn(m),
     });
@@ -728,7 +729,13 @@ export async function runProbedStoriesWaveTick({
     );
   }
 
-  const { nodes, doneIds, inFlight, blockedIds = [] } = probed;
+  const {
+    nodes,
+    doneIds,
+    inFlight,
+    blockedIds = [],
+    foreignHeld = [],
+  } = probed;
   const { envelope, exitCode } = buildReadySetEnvelope(nodes, {
     concurrencyCap,
     doneIds,
@@ -745,6 +752,11 @@ export async function runProbedStoriesWaveTick({
       epilogueDue,
       blocked: blockedIds,
       blockedReason: blockedReasonFor(blockedIds),
+      // Stories another operator's lease holds — withheld from dispatch this
+      // beat (folded into in-flight) and surfaced so the run can report
+      // "#<id> held by @<holder>" instead of dispatching into an init refusal.
+      foreignHeld,
+      foreignHeldReason: foreignHeldReasonFor(foreignHeld),
     },
     // A blocked Story outranks the scheduler's own verdict — including a
     // wedge, whose named blockers are moot while a human owes a decision.
@@ -776,6 +788,31 @@ function blockedReasonFor(blockedIds) {
   );
 }
 
+/**
+ * Render the operator-facing note for Stories held by another operator's
+ * lease, or `null` when none are held.
+ *
+ * These are not errors and not a wedge: the holder's run is progressing
+ * normally, this run simply must not join it on the same branch. The Story
+ * stays withheld and re-probes each beat, so it dispatches on its own the
+ * moment the holder's lease clears (their run lands or is stolen).
+ *
+ * @param {Array<{id: number, holder: string}>} foreignHeld
+ * @returns {string|null}
+ */
+function foreignHeldReasonFor(foreignHeld) {
+  if (!Array.isArray(foreignHeld) || foreignHeld.length === 0) return null;
+  const list = foreignHeld
+    .map((h) => `#${h.id} held by @${h.holder}`)
+    .join(', ');
+  return (
+    `${foreignHeld.length} Story(ies) are held by another operator's lease — ` +
+    `${list}. They are withheld this beat, not failed: the holder's run owns ` +
+    `the branch and worktree. This run picks each up automatically once that ` +
+    `lease clears (their run lands, or you --steal it after confirming it is dead).`
+  );
+}
+
 async function main(argv) {
   const { values } = parseArgs({
     args: argv,

package/.agents/workflows/deliver.md

@@ -44,7 +44,7 @@ silently dropping the offending id and under-delivering.
 
 | Flag | Meaning |
 | --- | --- |
-| `--concurrency <n>` | Ready-set fan-out cap (default **3** from `delivery.deliverRunner.concurrencyCap`; set `1` for sequential). |
+| `--concurrency <n>` | **Optional** per-run override of the ready-set fan-out cap. Omit it to honor `delivery.deliverRunner.concurrencyCap` (config default **3**, including any `.agentrc.local.json` override); pass it **only** when the operator explicitly wants a one-run cap. Set `1` for sequential. |
 | `--yes` | Suppress the multi-Story confirmation gate. |
 | `--steal` | Forwarded to `single-story-init.js` / lease steal. |
 | `--wait-merge` | Force close-and-land (the default; `delivery.routing.closeAndLand`, default `true`). |
@@ -85,10 +85,19 @@ to respect.
 
    ```bash
    node .agents/scripts/stories-wave-tick.js \
-     --stories <id,id,...> --probe-live --concurrency <n> \
+     --stories <id,id,...> --probe-live \
      --dispatched <every id you have dispatched so far>
    ```
 
+   **Do not add `--concurrency` unless the operator explicitly asked for a
+   per-run cap.** Omitting it is what lets the tick resolve the cap from
+   `delivery.deliverRunner.concurrencyCap` — including a `.agentrc.local.json`
+   override. An explicit `--concurrency <n>` wins over config for that run
+   (`resolveConcurrencyCap` returns the flag before it ever reads config), so
+   filling in a literal — e.g. the documented default `3` — silently defeats
+   the operator's configured override. Thread `--concurrency` through here
+   only when it was passed to `/deliver`.
+
    Each beat re-probes live state: it re-resolves the graph, classifies done
    (`agent::done` or a closed issue — including foreign blockers that landed
    in another run), and derives in-flight from live `agent::executing` /
@@ -96,12 +105,27 @@ to respect.
    accounting is read from reality every beat (Story #4594).
 
    **`--dispatched` is the one thing you must tell it (Story #4601).** List
-   every Story id you have spawned this run. Live state cannot report a Story
-   you dispatched ninety seconds ago: `single-story-init.js` flips
-   `agent::executing` at step 6 of 6, *after* a 3–6 minute worktree install,
-   so until then the Story still reads `agent::ready` and the next beat hands
-   it back — a second sub-agent then joins the first on the same branch and
-   worktree, interleaving commits.
+   every Story id you have spawned this run. Live state cannot instantly report
+   a Story you dispatched moments ago: `single-story-init.js` publishes
+   `agent::executing` before the worktree install (Story #4620 moved it ahead
+   of the multi-minute install, so the window is now short rather than
+   minutes-long), but it is not zero — until the label lands the Story still
+   reads `agent::ready` and, without `--dispatched`, the next beat would hand
+   it back and a second sub-agent would join the first on the same branch and
+   worktree, interleaving commits. `--dispatched` closes that residual
+   same-run window.
+
+   **Cross-run de-confliction is automatic (Story #4620).** A Story another
+   operator is delivering is withheld without any bookkeeping from you: the
+   probe reads the Story's assignee lease and, when it belongs to a different
+   operator, withholds the Story and reports it in the envelope's
+   `foreignHeld: [{ id, holder }]` (with `foreignHeldReason`). That is not a
+   failure or a wedge — the holder's run owns the branch, and this run picks
+   the Story up automatically once their lease clears. Init is the backstop:
+   it refuses a Story already labelled `agent::executing`, or one whose lease a
+   different operator holds, unless you pass `--steal`. Assignee-based
+   withholding needs `github.operatorHandle` set (in `.agentrc.local.json`);
+   without it the probe logs a warning and leans on init's lease refusal alone.
 
    The rule is **append-only: add each id as you dispatch it and never remove
    one.** The flag is additive, not authoritative — the probe unions it into

package/docs/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.4.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.3.0...mandrel-v2.4.0) (2026-07-17)
+
+
+### Added
+
+* **deliver:** cross-run Story de-confliction — lease-aware probe, executing refusal, race-verified acquire, early claim publish (refs [#4620](https://github.com/dsj1984/mandrel/issues/4620)) ([#4621](https://github.com/dsj1984/mandrel/issues/4621)) ([c493bbf](https://github.com/dsj1984/mandrel/commit/c493bbf14cf9a9ff2bc70fe7fea081f866668b2e))
+
+
+### Fixed
+
+* **deliver:** keep --concurrency opt-in so local cap override is honored ([#4618](https://github.com/dsj1984/mandrel/issues/4618)) ([a9c61dc](https://github.com/dsj1984/mandrel/commit/a9c61dcde654b746d176581f606a40c559c6f80a))
+* **deliver:** serialize post-land checkout mutations under concurrent close (refs [#4622](https://github.com/dsj1984/mandrel/issues/4622)) ([#4623](https://github.com/dsj1984/mandrel/issues/4623)) ([a502405](https://github.com/dsj1984/mandrel/commit/a502405d38f5dc57e245b212904139c4479a0e98))
+
 ## [2.3.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.2.0...mandrel-v2.3.0) (2026-07-17)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",