mandrel 2.2.0 → 2.4.0

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,27 @@
 
 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)
+
+
+### Fixed
+
+* **test:** resolve Windows drive-letter path bug in quality-preview test ([#4614](https://github.com/dsj1984/mandrel/issues/4614)) ([a7da94d](https://github.com/dsj1984/mandrel/commit/a7da94d1c4a83b9b721e632e468bb34df07465dd))
+* **update:** make post-install bin re-exec pnpm/layout-agnostic ([#4613](https://github.com/dsj1984/mandrel/issues/4613)) ([#4616](https://github.com/dsj1984/mandrel/issues/4616)) ([82dc5a2](https://github.com/dsj1984/mandrel/commit/82dc5a2e9ce662f9b9c0c7880ea684fd370a507f))
+
 ## [2.2.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.1.0...mandrel-v2.2.0) (2026-07-17)