session-orchestrator 3.23.0 → 4.0.0

package/scripts/lib/vault-status/board-lock.mjs

@@ -0,0 +1,185 @@
+/**
+ * board-lock.mjs — cross-repo mutex for the vault live-status board (issue #1180).
+ *
+ * The board at `<vault-dir>/01-projects/_active-sessions.md` is ONE file shared
+ * by every repo on the host: `sweepBoard()` runs at every session-start and
+ * session-end of EVERY repo, and each run performs a read-modify-write
+ * (`mirrorBoardInner` reads the existing board to seed `preservedRows` /
+ * `priorStatusByRepo`, merges the freshly-derived rows over it, then writes).
+ * `atomicWriteWithBackup`'s tmp+rename protects READERS from a half-written
+ * file; it does NOT protect the merge, so two sessions that read the same base
+ * concurrently both write a board missing the other's row — last writer wins.
+ *
+ * Why not `withStateMdLock`: that lock lives at `<repoRoot>/.orchestrator/state.lock`
+ * and is PER-REPO. Two different repos racing on the one shared board never
+ * contend on it — wrong domain.
+ *
+ * Why `staleCheck: 'mtime'` and not `'pid'`: the vault directory can be shared
+ * across hosts (Obsidian sync / a network volume), so the recorded pid is not
+ * probeable here. `mtime` ages the lock out after `staleMs` regardless of who
+ * wrote it. (`tryAcquireFileLock` never auto-overrides a CROSS-HOST body — see
+ * `file-lock.mjs` `isExistingStale` — so a foreign-host lock is waited out and
+ * then handled by the fail-open path below, never stolen.)
+ *
+ * FAIL-OPEN by contract: a board update is best-effort telemetry and must never
+ * abort a session phase (same posture as `writeBoard`'s `skipped-write-failed`
+ * return). On acquire timeout or fs-error we emit exactly ONE stderr WARN and
+ * run `fn` unlocked.
+ *
+ * Return shape follows {@link import('../locks/state-md-lock.mjs').withStateMdLock}:
+ * the value of `fn` is returned verbatim, so call sites need no branching. The
+ * lock outcome — which is diagnostic, not part of the board result — is exposed
+ * through the optional `onLockOutcome` callback instead of widening the return
+ * type for every caller. That is the simpler of the two shapes the issue offered:
+ * `mirrorBoardInner` already returns a `{ result, rows }` envelope of its own and
+ * would have had to unwrap a second one on every path.
+ *
+ * No external deps — Node stdlib + `file-lock.mjs`.
+ */
+
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { withFileLock } from '../file-lock.mjs';
+import { expandTilde } from '../common.mjs';
+
+/** Default acquire budget: short — the critical section is a read + a rename. */
+const DEFAULT_TIMEOUT_MS = 5000;
+/** Default poll cadence while another writer holds the board. */
+const DEFAULT_POLL_MS = 50;
+/**
+ * Default mtime staleness TTL — a board write that took a minute is dead.
+ *
+ * CEILING (BV-004): 60 s bounds the WHOLE critical section, and that section is
+ * not just the rename — `mirrorBoardInner` runs `collectRows` over every repo
+ * registered on this host. A sweep that ever exceeds 60 s makes a LIVE writer
+ * look stale, and the second writer overrides its lock and re-opens the exact
+ * lost-update race this mutex exists to close. It is a constant rather than a
+ * measurement because the sweep is fast today and a self-tuning TTL would be a
+ * second thing to be wrong.
+ * REVISIT when a board sweep is measured above 30 s (half the TTL — the point
+ * at which a slow host crosses it), or when an `onLockOutcome` carrying
+ * `staleOverride` is observed in the events ledger on a host that had no crash.
+ */
+const DEFAULT_STALE_MS = 60_000;
+
+/**
+ * Resolve the board lock path for a vault directory.
+ *
+ * `<vaultDir>/.orchestrator/board.lock` — deliberately NOT beside the board in
+ * `01-projects/`: the vault's own `.gitignore` already ignores
+ * `.orchestrator/*.lock`, and `vault-sync` walks `.md` files only, so the lock
+ * is invisible to both the vault's VCS and its validator.
+ *
+ * Home-expansion is `expandTilde` from `../common.mjs` — the consolidation the
+ * comment above once deferred (issue #1182): 8 inline `expandHome` copies in
+ * 3 non-equivalent shapes, one of them (`gitlab-portfolio/cli.mjs`) actively
+ * wrong on `~user/x`. All 8 call sites now import the shared helper.
+ *
+ * @param {string} vaultDir — absolute or `~`-prefixed vault root.
+ * @returns {string} absolute lock path.
+ */
+export function boardLockPathFor(vaultDir) {
+  return path.join(expandTilde(vaultDir), '.orchestrator', 'board.lock');
+}
+
+/**
+ * Run `fn` while holding the board mutex for `vaultDir`.
+ *
+ * Acquire polls until `timeoutMs`; the containing `.orchestrator/` directory is
+ * created on demand (`tryAcquireFileLock` → `createExclusive` does a
+ * `mkdirSync(dir, { recursive: true })` before linking). The lock is always
+ * released in a `finally`, including when `fn` throws — a throw propagates
+ * unchanged and is NEVER converted into the fail-open path (an unlocked retry
+ * of a throwing merge would run it twice).
+ *
+ * @param {string} vaultDir
+ * @param {() => (T | Promise<T>)} fn
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs=5000]
+ * @param {number} [opts.pollMs=50]
+ * @param {number} [opts.staleMs=60000] — mtime age after which a lock is overridden.
+ * @param {string} [opts.holder] — holder label recorded in the lock body.
+ * @param {(outcome: { locked: boolean, lockPath: string, reason?: string, staleOverride?: string }) => void} [opts.onLockOutcome]
+ *   — diagnostic sink, called exactly once before `fn` runs. `staleOverride`
+ *   is present only when this acquire OVERRODE an aged lock, and carries
+ *   `file-lock.mjs`'s own reason token — the observable behind the
+ *   DEFAULT_STALE_MS revisit trigger.
+ * @param {(lockPath: string, fn: Function, opts: object) => Promise<object>} [opts.lockImpl]
+ *   — test seam; defaults to {@link withFileLock}. Must honour the same
+ *   `{ ok: true, value } | { ok: false, reason }` contract.
+ * @param {(msg: string) => void} [opts.warn] — WARN sink (default: stderr).
+ * @returns {Promise<T>} whatever `fn` returned.
+ * @template T
+ */
+export async function withBoardLock(vaultDir, fn, opts = {}) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('withBoardLock: fn must be a function');
+  }
+
+  const {
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    pollMs = DEFAULT_POLL_MS,
+    staleMs = DEFAULT_STALE_MS,
+    holder: holderOpt,
+    onLockOutcome,
+    lockImpl = withFileLock,
+    warn = (msg) => process.stderr.write(msg),
+  } = opts;
+
+  const lockPath = boardLockPathFor(vaultDir);
+  const holder = typeof holderOpt === 'string' && holderOpt.length > 0
+    ? holderOpt
+    : `board-writer-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+
+  let outcomeReported = false;
+  // A stale-override is the one event that can silently break the mutex's
+  // guarantee (see DEFAULT_STALE_MS § CEILING), and `withFileLock` announces it
+  // ONLY through its `warn` sink — where it is prose nobody can aggregate. Lift
+  // it onto the diagnostic outcome so the revisit trigger is observable rather
+  // than anecdotal. It rides the SAME single `onLockOutcome` call (the override
+  // happens during acquire, i.e. strictly before `fn`), which keeps the
+  // documented "called exactly once" contract intact.
+  let staleOverride = null;
+  const warnAndWatch = (msg) => {
+    const hit = /overriding stale lock \(([^)]*)\)/.exec(msg);
+    if (hit) staleOverride = hit[1];
+    warn(`${msg}\n`);
+  };
+
+  const result = await lockImpl(
+    lockPath,
+    async () => {
+      outcomeReported = true;
+      onLockOutcome?.({
+        locked: true,
+        lockPath,
+        ...(staleOverride ? { staleOverride } : {}),
+      });
+      return await fn();
+    },
+    {
+      timeoutMs,
+      pollMs,
+      staleCheck: 'mtime',
+      staleMs,
+      holder,
+      indent: 2,
+      tmpPrefix: '.board.lock',
+      warn: warnAndWatch,
+    },
+  );
+
+  if (result?.ok) return result.value;
+
+  // Fail-open: never let a contended or broken lock abort a session phase.
+  // `outcomeReported` guards the (impossible-by-contract, but cheap to pin)
+  // case of an impl that both ran `fn` and reported failure.
+  if (!outcomeReported) {
+    const reason = result?.reason ?? 'unknown';
+    warn(`⚠ withBoardLock: ${reason} acquiring ${lockPath} — writing board WITHOUT the lock (best-effort)\n`);
+    onLockOutcome?.({ locked: false, lockPath, reason });
+    return await fn();
+  }
+  return result?.value;
+}

package/scripts/lib/vault-status/board-writer.mjs

@@ -58,6 +58,8 @@ import { readConfigFile, parseSessionConfig } from '../config.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { enumerateCandidates } from '../dispatcher/enumerate.mjs';
 import { atomicWriteWithBackup } from '../io.mjs';
+import { withBoardLock } from './board-lock.mjs';
+import { expandTilde } from '../common.mjs';
 
 /** Frontmatter sentinel that identifies generator-owned board files. */
 export const GENERATOR_MARKER = 'session-orchestrator-active-sessions@1';
@@ -180,22 +182,6 @@ const nameSlot = (repo) => `n:${foldKey(repo)}`;
 
 // ── Path helpers ────────────────────────────────────────────────────────────────
 
-/**
- * Expand a leading `~` to the current user's home directory. Inlined here on
- * purpose — the shared helper is private elsewhere, and a shared
- * `vault-write-guard.mjs` extraction is deferred to a later epic (W2 forbids a
- * new shared file in this slice).
- *
- * @param {string} p
- * @returns {string}
- */
-function expandHome(p) {
-  if (typeof p !== 'string' || p.length === 0) return p;
-  if (p === '~') return os.homedir();
-  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
-  return p;
-}
-
 /**
  * Resolve the board file path from a vault directory.
  *
@@ -203,7 +189,7 @@ function expandHome(p) {
  * @returns {string} `<vaultDir>/01-projects/_active-sessions.md`
  */
 export function resolveBoardPath(vaultDir) {
-  return path.join(expandHome(vaultDir), '01-projects', '_active-sessions.md');
+  return path.join(expandTilde(vaultDir), '01-projects', '_active-sessions.md');
 }
 
 // ── Formatting helpers ───────────────────────────────────────────────────────────
@@ -729,6 +715,10 @@ export const BOARD_EVENT = 'orchestrator.vault.board_written';
  * @param {number} [opts.reposSwept] — candidates {@link enumerateCandidates}
  *   returned, on the {@link sweepBoard} path only.
  * @param {number} [opts.durationMs]
+ * @param {{ locked: boolean, reason?: string, stale_override?: string, waited_ms: number }} [opts.lock]
+ *   — board-lock outcome, present only when the lock was actually attempted
+ *   (i.e. not on the early no-op guards, not on dry-run). Never carries the lock
+ *   PATH — that is a `$HOME`-rooted string, the CP1 shape this payload keeps out.
  * @returns {Promise<void>}
  */
 /**
@@ -765,7 +755,7 @@ function telemetrySafePath(outputPath) {
   return base.length > 0 ? base : undefined;
 }
 
-async function emitBoardEvent({ repoRoot, caller, action, path: outputPath, rows, reposSwept, durationMs }) {
+async function emitBoardEvent({ repoRoot, caller, action, path: outputPath, rows, reposSwept, durationMs, lock }) {
   // Refuse the SO_PROJECT_DIR fallback instead of guessing a destination.
   // Without an explicit repoRoot, `emitEvent` resolves `eventsFilePath(undefined)`
   // and writes into whatever tree the ambient env points at — so `mirrorBoard()`
@@ -798,6 +788,12 @@ async function emitBoardEvent({ repoRoot, caller, action, path: outputPath, rows
         ...(Number.isFinite(rows) ? { rows } : {}),
         ...(Number.isFinite(reposSwept) ? { repos_swept: reposSwept } : {}),
         ...(Number.isFinite(durationMs) ? { duration_ms: durationMs } : {}),
+        // Lock diagnostics (absent on every path that never took the lock: the
+        // early no-op guards and dry-run). `lock.locked === false` marks a
+        // fail-open unlocked write; `lock.stale_override` marks an acquire that
+        // aged out someone else's lock — the observable behind board-lock's
+        // DEFAULT_STALE_MS revisit trigger.
+        ...(lock && typeof lock === 'object' ? { lock } : {}),
         // #1147: join key parity with the sibling `narrative_mirrored` event,
         // which has carried attribution since #1073. Without it a board record
         // cannot be joined to the session that wrote it. Both keys are OMITTED
@@ -851,7 +847,10 @@ async function emitBoardEvent({ repoRoot, caller, action, path: outputPath, rows
  *   `owner.yaml`, whose `paths.vault-dir` override (if set) wins over the fixture value
  *   and bleeds into the assertion (issue #783). Production callers omit this — the
  *   default (real owner.yaml resolution) is the correct host-local behavior there.
- * @returns {Promise<{ result: { action: string, path?: string }, rows?: number }>}
+ * @returns {Promise<{ result: { action: string, path?: string }, rows?: number,
+ *   lock?: { locked: boolean, reason?: string, stale_override?: string, waited_ms: number } }>}
+ *   `lock` is present only on the locked path (absent on the early no-op guards
+ *   and on dry-run, which deliberately takes no lock).
  *   `rows` is present only once the render was reached — see
  *   {@link emitBoardEvent}'s `rows` contract. The public {@link mirrorBoard}
  *   wrapper unwraps `result` so the caller-visible return shape is unchanged.
@@ -880,7 +879,7 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
   }
 
   // Safety: the resolved vault dir must live under $HOME.
-  const expandedVault = expandHome(vaultDir);
+  const expandedVault = expandTilde(vaultDir);
   const home = os.homedir();
   const inHome = validatePathInsideProject(expandedVault, home);
   if (!inHome.ok) {
@@ -934,132 +933,171 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
 
   const outputPath = resolveBoardPath(vaultDir);
 
-  // Read the EXISTING generator-owned board (if any) to:
-  //   1. preserve its `created:` — otherwise every render differs on `created:`
-  //      and the noop-skip in writeBoard would never fire.
-  //   2. recover the prior per-repo status — drives the `closed` derivation for
-  //      repos NOT in this update (idempotent merge: their rows are re-derived).
-  // Both maps are keyed by {@link foldKey}(repo) — case-insensitively folded
-  // (issue #719) — so two prior rows differing only by case (e.g.
-  // `some-repo` vs `Some-Repo`, the same physical directory on a
-  // case-insensitive-preserving filesystem like APFS) collapse to ONE entry
-  // instead of coexisting as duplicates. The row OBJECTS keep their original
-  // `repo` string untouched, so `renderBoard` still displays true casing.
-  const fsReadFile = fs?.readFileSync ?? readFileSync;
-  const fsExists = fs?.existsSync ?? existsSync;
-  let createdIso;
-  const priorStatusByRepo = new Map();   // LEGACY rows only — see collectRows contract
-  const priorStatusByKey = new Map();    // boardKey → status (authoritative since #871)
-  const preservedRows = new Map(); // merge slot (see hashSlot/nameSlot) → prior row
-  if (fsExists(outputPath)) {
-    let existing;
-    try {
-      existing = fsReadFile(outputPath, 'utf8');
-    } catch {
-      existing = null;
-    }
-    if (existing) {
-      const fm = parseFrontmatter(existing);
-      if (fm && fm['_generator'] === GENERATOR_MARKER) {
-        if (fm['created']) createdIso = fm['created'];
-        for (const prior of parseBoardRows(existing)) {
-          // Dual-key slotting (#871): a keyed row owns its own hash slot; a
-          // legacy (6-column) row falls back to its folded display name. Two
-          // keyed rows can only collide when they resolve to the SAME path, so
-          // the heartbeat-preference resolution below is now reached almost
-          // exclusively by legacy rows — which is precisely the case it was
-          // written for (#719).
-          const key = prior.key ? hashSlot(prior.key) : nameSlot(prior.repo);
-          const collidingPrior = preservedRows.get(key);
-          if (collidingPrior) {
-            // Collision WITHIN parseBoardRows output — two prior rows fold to
-            // the same key with no fresh row in play yet (that upsert happens
-            // below). Prefer the row with the most-recent `heartbeat` rather
-            // than silently last-in-file-order. Guard: if either heartbeat is
-            // unparsable, fall through to last-written-wins (the pre-#719
-            // default) by NOT skipping the overwrite below.
-            const collidingTs = Date.parse(collidingPrior.heartbeat ?? '');
-            const priorTs = Date.parse(prior.heartbeat ?? '');
-            if (Number.isFinite(collidingTs) && Number.isFinite(priorTs) && collidingTs > priorTs) {
-              // The already-preserved row is strictly newer — keep it, skip
-              // this older colliding row entirely.
-              continue;
+  // Everything below — the two reads of the existing board, the merge, and the
+  // write — is ONE read-modify-write over a file shared by every repo on the
+  // host (issue #1180). Serialise it on the vault-scoped board lock so a
+  // concurrent sweepBoard() from another repo cannot compute its merge from a
+  // base we are about to replace. Fail-open: withBoardLock runs the closure
+  // unlocked (with a WARN) rather than let a contended lock abort the phase.
+  const mergeAndWrite = async () => {
+    // Read the EXISTING generator-owned board (if any) to:
+    //   1. preserve its `created:` — otherwise every render differs on `created:`
+    //      and the noop-skip in writeBoard would never fire.
+    //   2. recover the prior per-repo status — drives the `closed` derivation for
+    //      repos NOT in this update (idempotent merge: their rows are re-derived).
+    // Both maps are keyed by {@link foldKey}(repo) — case-insensitively folded
+    // (issue #719) — so two prior rows differing only by case (e.g.
+    // `some-repo` vs `Some-Repo`, the same physical directory on a
+    // case-insensitive-preserving filesystem like APFS) collapse to ONE entry
+    // instead of coexisting as duplicates. The row OBJECTS keep their original
+    // `repo` string untouched, so `renderBoard` still displays true casing.
+    const fsReadFile = fs?.readFileSync ?? readFileSync;
+    const fsExists = fs?.existsSync ?? existsSync;
+    let createdIso;
+    const priorStatusByRepo = new Map();   // LEGACY rows only — see collectRows contract
+    const priorStatusByKey = new Map();    // boardKey → status (authoritative since #871)
+    const preservedRows = new Map(); // merge slot (see hashSlot/nameSlot) → prior row
+    if (fsExists(outputPath)) {
+      let existing;
+      try {
+        existing = fsReadFile(outputPath, 'utf8');
+      } catch {
+        existing = null;
+      }
+      if (existing) {
+        const fm = parseFrontmatter(existing);
+        if (fm && fm['_generator'] === GENERATOR_MARKER) {
+          if (fm['created']) createdIso = fm['created'];
+          for (const prior of parseBoardRows(existing)) {
+            // Dual-key slotting (#871): a keyed row owns its own hash slot; a
+            // legacy (6-column) row falls back to its folded display name. Two
+            // keyed rows can only collide when they resolve to the SAME path, so
+            // the heartbeat-preference resolution below is now reached almost
+            // exclusively by legacy rows — which is precisely the case it was
+            // written for (#719).
+            const key = prior.key ? hashSlot(prior.key) : nameSlot(prior.repo);
+            const collidingPrior = preservedRows.get(key);
+            if (collidingPrior) {
+              // Collision WITHIN parseBoardRows output — two prior rows fold to
+              // the same key with no fresh row in play yet (that upsert happens
+              // below). Prefer the row with the most-recent `heartbeat` rather
+              // than silently last-in-file-order. Guard: if either heartbeat is
+              // unparsable, fall through to last-written-wins (the pre-#719
+              // default) by NOT skipping the overwrite below.
+              const collidingTs = Date.parse(collidingPrior.heartbeat ?? '');
+              const priorTs = Date.parse(prior.heartbeat ?? '');
+              if (Number.isFinite(collidingTs) && Number.isFinite(priorTs) && collidingTs > priorTs) {
+                // The already-preserved row is strictly newer — keep it, skip
+                // this older colliding row entirely.
+                continue;
+              }
             }
+            if (prior.key) {
+              priorStatusByKey.set(prior.key, prior.status);
+            } else {
+              // LEGACY rows only. Seeding this map from keyed rows too would let
+              // repo B (never seen, same basename) inherit repo A's terminal
+              // status through the name fallback in collectRows — reintroducing
+              // the identity collision #871 exists to remove, one layer down.
+              priorStatusByRepo.set(foldKey(prior.repo), prior.status);
+            }
+            preservedRows.set(key, prior);
           }
-          if (prior.key) {
-            priorStatusByKey.set(prior.key, prior.status);
-          } else {
-            // LEGACY rows only. Seeding this map from keyed rows too would let
-            // repo B (never seen, same basename) inherit repo A's terminal
-            // status through the name fallback in collectRows — reintroducing
-            // the identity collision #871 exists to remove, one layer down.
-            priorStatusByRepo.set(foldKey(prior.repo), prior.status);
-          }
-          preservedRows.set(key, prior);
         }
       }
     }
-  }
 
-  const rows = await collectRows({ repos: repoList, now, priorStatusByRepo, priorStatusByKey });
-
-  // TTL-staleness re-derivation for PRESERVED rows (issue #829 Finding 2).
-  // Without this pass, a preserved `in-progress` row (a repo NOT in this
-  // update) is copied forward FOREVER — a crashed/never-closed session's row
-  // never flips even after its heartbeat has aged well past the lock's TTL,
-  // because `collectRows` only re-derives status for repos actually IN
-  // `repoList`. Re-derive staleness for every preserved row here, BEFORE the
-  // freshly-derived `rows` are upserted over it below (fresh data always
-  // wins regardless of this pass — a live lock or an explicit-closed update
-  // always takes precedence over the TTL flip).
-  //
-  // Board rows carry only a raw `heartbeat` string, never the lock's own
-  // `ttl_hours` (that field is not part of the rendered board) — so this
-  // reuses the shared {@link DEFAULT_TTL_HOURS} constant rather than the
-  // per-lock TTL {@link isLockLive} uses when a live lock object is in hand.
-  // Rows with an unparseable/absent heartbeat are left UNCHANGED (fail-open,
-  // never crash on a malformed prior board).
-  const nowMs = now instanceof Date ? now.getTime() : Date.now();
-  const ttlMs = DEFAULT_TTL_HOURS * 3600 * 1000;
-  const staleRederivedRows = new Map();
-  for (const [key, row] of preservedRows) {
-    if (row.status === STATUS_IN_PROGRESS) {
-      const heartbeatMs = Date.parse(row.heartbeat ?? '');
-      if (Number.isFinite(heartbeatMs) && (nowMs - heartbeatMs) >= ttlMs) {
-        staleRederivedRows.set(key, { ...row, status: STATUS_FORCE_CLOSED });
-        continue;
+    const rows = await collectRows({ repos: repoList, now, priorStatusByRepo, priorStatusByKey });
+
+    // TTL-staleness re-derivation for PRESERVED rows (issue #829 Finding 2).
+    // Without this pass, a preserved `in-progress` row (a repo NOT in this
+    // update) is copied forward FOREVER — a crashed/never-closed session's row
+    // never flips even after its heartbeat has aged well past the lock's TTL,
+    // because `collectRows` only re-derives status for repos actually IN
+    // `repoList`. Re-derive staleness for every preserved row here, BEFORE the
+    // freshly-derived `rows` are upserted over it below (fresh data always
+    // wins regardless of this pass — a live lock or an explicit-closed update
+    // always takes precedence over the TTL flip).
+    //
+    // Board rows carry only a raw `heartbeat` string, never the lock's own
+    // `ttl_hours` (that field is not part of the rendered board) — so this
+    // reuses the shared {@link DEFAULT_TTL_HOURS} constant rather than the
+    // per-lock TTL {@link isLockLive} uses when a live lock object is in hand.
+    // Rows with an unparseable/absent heartbeat are left UNCHANGED (fail-open,
+    // never crash on a malformed prior board).
+    const nowMs = now instanceof Date ? now.getTime() : Date.now();
+    const ttlMs = DEFAULT_TTL_HOURS * 3600 * 1000;
+    const staleRederivedRows = new Map();
+    for (const [key, row] of preservedRows) {
+      if (row.status === STATUS_IN_PROGRESS) {
+        const heartbeatMs = Date.parse(row.heartbeat ?? '');
+        if (Number.isFinite(heartbeatMs) && (nowMs - heartbeatMs) >= ttlMs) {
+          staleRederivedRows.set(key, { ...row, status: STATUS_FORCE_CLOSED });
+          continue;
+        }
       }
+      staleRederivedRows.set(key, row);
     }
-    staleRederivedRows.set(key, row);
-  }
 
-  // Idempotent merge: keep prior (TTL-rederived) rows for repos NOT in this
-  // update, then upsert the freshly-derived rows over them so repeated writes
-  // stay stable. A freshly-derived row ALWAYS wins over a preserved row in the
-  // same slot — that is what collapses a live row over a stale preserved one.
-  //
-  // Dual-key upsert (#871). A naive switch from the folded name to the path
-  // key would make the two key spaces DISJOINT: the fresh row would never
-  // overwrite the legacy row, the legacy row would become immortal (the sweep
-  // skips `frei` candidates and the TTL pass only rewrites `status`, never
-  // removes a row), and the board would grow a permanent duplicate per repo.
-  // So a fresh row first claims its hash slot; if that slot is new, it ADOPTS
-  // the legacy name slot for the same folded name — one board write converts
-  // the row, and the migration is complete for that repo.
-  const merged = new Map(staleRederivedRows);
-  for (const row of rows) {
-    const slot = row.key ? hashSlot(row.key) : nameSlot(row.repo);
-    if (row.key && !merged.has(slot)) {
-      // First keyed write for this repo — take over its legacy row rather than
-      // rendering a second one beside it.
-      merged.delete(nameSlot(row.repo));
+    // Idempotent merge: keep prior (TTL-rederived) rows for repos NOT in this
+    // update, then upsert the freshly-derived rows over them so repeated writes
+    // stay stable. A freshly-derived row ALWAYS wins over a preserved row in the
+    // same slot — that is what collapses a live row over a stale preserved one.
+    //
+    // Dual-key upsert (#871). A naive switch from the folded name to the path
+    // key would make the two key spaces DISJOINT: the fresh row would never
+    // overwrite the legacy row, the legacy row would become immortal (the sweep
+    // skips `frei` candidates and the TTL pass only rewrites `status`, never
+    // removes a row), and the board would grow a permanent duplicate per repo.
+    // So a fresh row first claims its hash slot; if that slot is new, it ADOPTS
+    // the legacy name slot for the same folded name — one board write converts
+    // the row, and the migration is complete for that repo.
+    const merged = new Map(staleRederivedRows);
+    for (const row of rows) {
+      const slot = row.key ? hashSlot(row.key) : nameSlot(row.repo);
+      if (row.key && !merged.has(slot)) {
+        // First keyed write for this repo — take over its legacy row rather than
+        // rendering a second one beside it.
+        merged.delete(nameSlot(row.repo));
+      }
+      merged.set(slot, row);
     }
-    merged.set(slot, row);
-  }
 
-  const content = renderBoard([...merged.values()], { now, createdIso });
+    const content = renderBoard([...merged.values()], { now, createdIso });
+
+    return { result: writeBoard({ outputPath, content, dryRun, fs }), rows: merged.size };
+  };
+
+  // dry-run never touches disk (writeBoard guard 1) — so it must not create a
+  // lock file in the operator's vault either. Nothing to serialise.
+  if (dryRun) return await mergeAndWrite();
+
+  // The lock outcome is diagnostic, and until now it went nowhere: `withBoardLock`
+  // has exposed `onLockOutcome` since #1180, and NO production caller passed one
+  // (measured 2026-09-02: `grep -rn onLockOutcome scripts hooks` → board-lock.mjs
+  // and its test, nothing else). So the two states that silently weaken the mutex —
+  // a fail-open unlocked write, and a stale-override that can override a LIVE
+  // writer (see board-lock's DEFAULT_STALE_MS § CEILING) — were unobservable in
+  // aggregate, which is exactly what the revisit trigger needs. Capture it here and
+  // ride it out on the ONE board_written event rather than adding a second event.
+  let lockOutcome;
+  const acquireStartedAt = Date.now();
+  const inner = await withBoardLock(expandedVault, mergeAndWrite, {
+    onLockOutcome: (o) => {
+      // Called exactly once, strictly BEFORE `fn` — so the elapsed time is the
+      // acquire wait, not the merge. `lockPath` is deliberately DROPPED: it is
+      // `<vault>/.orchestrator/board.lock` under $HOME, i.e. the CP1 (OS username)
+      // shape `telemetrySafePath` exists to keep out of the payload.
+      lockOutcome = {
+        locked: o?.locked === true,
+        ...(typeof o?.reason === 'string' ? { reason: o.reason } : {}),
+        ...(typeof o?.staleOverride === 'string' ? { stale_override: o.staleOverride } : {}),
+        waited_ms: Date.now() - acquireStartedAt,
+      };
+    },
+  });
 
-  return { result: writeBoard({ outputPath, content, dryRun, fs }), rows: merged.size };
+  return lockOutcome === undefined ? inner : { ...inner, lock: lockOutcome };
 }
 
 /**
@@ -1095,7 +1133,7 @@ export async function mirrorBoard(opts = {}) {
   // throws exactly as it did before this wrapper existed.
   const { repoRoot, caller = 'mirrorBoard', reposSwept } = opts;
 
-  const { result, rows } = await mirrorBoardInner(opts);
+  const { result, rows, lock } = await mirrorBoardInner(opts);
 
   await emitBoardEvent({
     repoRoot,
@@ -1105,6 +1143,7 @@ export async function mirrorBoard(opts = {}) {
     rows,
     reposSwept,
     durationMs: Date.now() - startedAt,
+    lock,
   });
 
   return result;