session-orchestrator 3.22.0 → 3.24.0

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

@@ -10,8 +10,16 @@
  * liveness via {@link isLockLive}) plus the host-wide session registry (the
  * registry entry is the ONLY source of `branch` — the lock lacks that field).
  *
+ * Telemetry: every {@link mirrorBoard} call — and therefore every
+ * {@link sweepBoard} call — emits exactly ONE {@link BOARD_EVENT} record,
+ * including the no-op paths (`skipped-vault-disabled`, `skipped-handwritten`,
+ * `skipped-noop`, `skipped-write-failed`). Those are the states that previously
+ * looked identical to a healthy write from outside the process. Emission is
+ * best-effort and can never fail a board write.
+ *
  * Exports:
  *   GENERATOR_MARKER  — frontmatter sentinel that identifies generator-owned files
+ *   BOARD_EVENT       — canonical event name for a board-write attempt
  *   boardKey          — repoRoot → stable path-derived row identity (issue #871)
  *   resolveBoardPath  — vaultDir → `<vaultDir>/01-projects/_active-sessions.md`
  *   collectRows       — per-repo status derivation (readLock + readRegistry)
@@ -42,6 +50,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+import { emitEvent, sessionAttribution } from '../events.mjs';
 import { isLockLive, readLock, DEFAULT_TTL_HOURS } from '../session-lock.mjs';
 import { readRegistry, repoPathHash, isRegistryEntryFresh } from '../session-registry.mjs';
 import { parseFrontmatter } from '../vault-mirror/utils.mjs';
@@ -49,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';
@@ -171,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.
  *
@@ -194,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 ───────────────────────────────────────────────────────────
@@ -681,6 +676,141 @@ export function writeBoard(opts) {
   return { action: 'written', path: outputPath };
 }
 
+// ── Telemetry ────────────────────────────────────────────────────────────────────
+
+/**
+ * Canonical event name for a board-write attempt.
+ *
+ * ONE event per {@link mirrorBoard} call — including every no-op path. The
+ * no-op paths are the point: a vault-disabled config, a hand-edited board, or a
+ * failed write returned silently before this existed, so an outage of this
+ * writer was indistinguishable from a healthy skip. Measured 2026-08-23 over
+ * 28 387 ledger records: ZERO board/mirror events, because this module did not
+ * import {@link emitEvent} at all.
+ */
+export const BOARD_EVENT = 'orchestrator.vault.board_written';
+
+/**
+ * Emit the board-write telemetry record. Best-effort: never throws, never
+ * alters the board result.
+ *
+ * ABSENT IS NOT ZERO (`docs/events-schema.md`): every optional field is spread
+ * conditionally, so an UNMEASURED field is missing from the record rather than
+ * written as `0`. A present `repos_swept: 0` therefore means "enumeration ran
+ * and surfaced nothing" (the documented silent-enumeration failure mode), while
+ * an absent `repos_swept` means "not a sweep, or enumeration threw" — reading
+ * the missing key as `0` would conflate the two in both directions.
+ *
+ * @param {object} opts
+ * @param {string} [opts.repoRoot] — pins the ledger to THIS repo's
+ *   `.orchestrator/metrics/events.jsonl` (#941). Omitted only when the caller
+ *   supplied no usable root, where `SO_PROJECT_DIR` is the sole destination left.
+ * @param {'sweepBoard'|'mirrorBoard'} opts.caller — which entry point ran.
+ * @param {string} opts.action — the `action` the board write returned.
+ * @param {string} [opts.path] — resolved board path, when one was resolved.
+ * @param {number} [opts.rows] — rows in the board content THIS call rendered.
+ *   Present whenever the render was reached (so also on `skipped-noop` /
+ *   `dry-run`, where the content was built but not written — `action` is what
+ *   says whether it landed); absent on the early no-op paths that never render.
+ * @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>}
+ */
+/**
+ * Reduce an absolute vault path to its LAST TWO segments for telemetry.
+ *
+ * The full path is the module's public return contract and stays untouched.
+ * What must not travel is the path in the EMITTED payload: on a real host it
+ * reads `/Users/<name>/Projects/<vault>/01-projects/<private-slug>/…`, i.e. an
+ * OS username plus a private project slug. Those are exactly the two shapes
+ * `scripts/lib/validate/check-owner-leakage.mjs` blocks as CP1 and CP6 — and
+ * that scanner structurally cannot see this one, because it walks `git ls-files`
+ * and `.orchestrator/metrics/*.jsonl` is gitignored (`.gitignore:40`).
+ * The record is invisible to the pre-commit guard and visible to the optional
+ * Clank webhook (`scripts/lib/events.mjs`, `CLANK_EVENT_URL`), which posts the
+ * payload verbatim with no redaction.
+ *
+ * The BASENAME is the deliberate ceiling — one segment, not two. Two segments
+ * would keep the parent directory, and under `01-projects/` that directory IS
+ * the private project slug, i.e. exactly the CP6 shape this is meant to drop.
+ * The diagnostic value lives in the filename alone: it says WHICH writer ran
+ * (`_session-narrative.md` vs `_active-sessions.md`), which is the question the
+ * event exists to answer. Which project it was is already answerable from the
+ * record's own `session_id` / repo-scoped ledger location.
+ * Revisit trigger: a consumer that needs more than the filename — then it
+ * belongs in the RETURN value, which already carries the absolute path, never
+ * in the event.
+ *
+ * @param {unknown} outputPath
+ * @returns {string|undefined} `undefined` when there is nothing measured to report.
+ */
+function telemetrySafePath(outputPath) {
+  if (typeof outputPath !== 'string' || outputPath.length === 0) return undefined;
+  const base = path.basename(outputPath);
+  return base.length > 0 ? base : undefined;
+}
+
+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()`
+  // called with no argument used to append a record to an UNRELATED repo's ledger.
+  // Measured 2026-08-23: a review agent reproduced it and put a second, byte-identical
+  // record into this repo's live events.jsonl doing so. Two sibling emitters in the
+  // same commit arc already refuse it (`express-path.mjs` with a WARN,
+  // `narrative-mirror.mjs` silently); this one was the odd one out, and it was the
+  // unsafe one. A stderr WARN, not silence: a telemetry record that goes missing
+  // should say so, or it becomes the very blind spot this event was added to close.
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
+    process.stderr.write(
+      `[board-writer] ${BOARD_EVENT} not emitted: no repoRoot given, and the ambient ` +
+        `SO_PROJECT_DIR fallback would write to an unrelated repo's ledger.\n`,
+    );
+    return;
+  }
+  try {
+    await emitEvent(
+      BOARD_EVENT,
+      {
+        action,
+        caller,
+        ...(telemetrySafePath(outputPath) !== undefined ? { path_tail: telemetrySafePath(outputPath) } : {}),
+        // Number.isFinite — NOT truthiness — is what keeps a MEASURED zero in
+        // the record (`repos_swept: 0` = "enumeration ran, found nothing") while
+        // still omitting an unmeasured field. `x || undefined` would silently
+        // delete exactly the zero the field exists to report. (`!= null` is the
+        // idiom elsewhere but this repo's eqeqeq rule forbids it.)
+        ...(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
+        // (never fabricated) when no session.lock is readable at `repoRoot` —
+        // and `repoRoot` is the SAME root the ledger line is pinned to below,
+        // so the attribution can never name a different tree than the record.
+        ...sessionAttribution(repoRoot),
+      },
+      { repoRoot },
+    );
+  } catch {
+    /* Best-effort telemetry. emitEvent does real file I/O (mkdir + append), so a
+       read-only or occupied ledger path WILL throw — and a broken ledger must
+       never fail a board write. The board result is authoritative. */
+  }
+}
+
 // ── Convenience: config-read + resolve + write ───────────────────────────────────
 
 /**
@@ -717,11 +847,17 @@ export function writeBoard(opts) {
  *   `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<{ action: string, path?: string }>}
+ * @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.
  */
-export async function mirrorBoard({ repoRoot, repos, explicitStatus, now = new Date(), dryRun = false, fs, hostPaths } = {}) {
+async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Date(), dryRun = false, fs, hostPaths } = {}) {
   if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
 
   // Read + parse Session Config. Any failure → silent no-op.
@@ -730,24 +866,24 @@ export async function mirrorBoard({ repoRoot, repos, explicitStatus, now = new D
     const text = await readConfigFile(repoRoot);
     config = parseSessionConfig(text, { hostPaths });
   } catch {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
 
   const vault = config?.['vault-integration'];
   if (!vault || vault.enabled !== true) {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
   const vaultDir = vault['vault-dir'];
   if (typeof vaultDir !== 'string' || vaultDir.length === 0) {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
 
   // 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) {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
 
   // `vault-name` (#660) overrides the git-derived repo slug for per-project
@@ -797,132 +933,220 @@ export async function mirrorBoard({ repoRoot, repos, explicitStatus, now = new D
 
   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 writeBoard({ outputPath, content, dryRun, fs });
+  return lockOutcome === undefined ? inner : { ...inner, lock: lockOutcome };
+}
+
+/**
+ * Public {@link mirrorBoardInner} wrapper that emits exactly ONE
+ * {@link BOARD_EVENT} per call — on EVERY path, no-ops included.
+ *
+ * The wrapper exists so the emit cannot be forgotten: the six return points
+ * inside {@link mirrorBoardInner} (five `skipped-vault-disabled` guards plus
+ * whatever {@link writeBoard} decides) all funnel through here, and so does the
+ * seventh someone adds next. Emitting per-return instead would leave each new
+ * early return silent by default — which is the exact defect being fixed.
+ *
+ * A THROW from the inner function is deliberately NOT converted into an event:
+ * `action` is mandatory in the payload and a throw has no action the code knows,
+ * so inventing one would put a fictional state in the ledger. The throw is not
+ * silent either — it propagates to the caller, and on the {@link sweepBoard}
+ * path the fallback write emits its own record.
+ *
+ * Return shape is byte-identical to the pre-telemetry contract.
+ *
+ * @param {Parameters<typeof mirrorBoardInner>[0] & {
+ *   caller?: 'sweepBoard'|'mirrorBoard', reposSwept?: number }} [opts]
+ *   — full parameter contract (`repoRoot`, `repos`, `explicitStatus`, `now`,
+ *   `dryRun`, `fs`, `hostPaths`) is documented on {@link mirrorBoardInner}.
+ *   `caller` / `reposSwept` are telemetry attribution only and never reach the
+ *   board content. `caller` defaults to `'mirrorBoard'`; {@link sweepBoard}
+ *   overrides it so the two entry points stay separable in the ledger.
+ * @returns {Promise<{ action: string, path?: string }>}
+ */
+export async function mirrorBoard(opts = {}) {
+  const startedAt = Date.now();
+  // Destructured directly (not via `opts ?? {}`) so a `null` argument still
+  // throws exactly as it did before this wrapper existed.
+  const { repoRoot, caller = 'mirrorBoard', reposSwept } = opts;
+
+  const { result, rows, lock } = await mirrorBoardInner(opts);
+
+  await emitBoardEvent({
+    repoRoot,
+    caller,
+    action: result?.action,
+    path: result?.path,
+    rows,
+    reposSwept,
+    durationMs: Date.now() - startedAt,
+    lock,
+  });
+
+  return result;
 }
 
 // ── Host-wide sweep (issue #716) ─────────────────────────────────────────────────
@@ -1022,6 +1246,12 @@ export function buildSweepRepos(candidates, { thisRepoRoot } = {}) {
  * write still happens. `mirrorBoard`'s own internal guards (vault disabled,
  * `_overview.md` refusal, noop-skip, …) are untouched and still apply.
  *
+ * Telemetry: BOTH paths emit one {@link BOARD_EVENT} with `caller: 'sweepBoard'`
+ * (the wrapping {@link mirrorBoard} call does the emitting, so a sweep never
+ * produces two records). The happy path carries `repos_swept`; the fallback
+ * omits it, which is what distinguishes "enumeration ran and found nothing"
+ * (`repos_swept: 0`) from "enumeration threw" (key absent).
+ *
  * @param {object} [opts]
  * @param {string} opts.repoRoot — the calling repo (always included in the sweep).
  * @param {string} [opts.startDir] — enumeration root; omitted in production so
@@ -1061,11 +1291,21 @@ export async function sweepBoard({ repoRoot, startDir, now = new Date(), dryRun
   try {
     const candidates = await enumerateCandidates({ startDir, now: nowMs, deps });
     const repos = buildSweepRepos(candidates, { thisRepoRoot: repoRoot });
-    return await mirrorBoard({ repoRoot, repos, now: nowForMirror, dryRun, fs, hostPaths });
+    // Telemetry counts what ENUMERATION surfaced, not what we sweep: `repos`
+    // always contains at least `thisRepoRoot` (buildSweepRepos unions it in),
+    // so a silently-empty enumeration — the documented macOS realpath-hop
+    // failure, 0 candidates and no error — would be invisible in `repos.length`
+    // and plainly visible as `repos_swept: 0`. Guarded with Array.isArray so a
+    // non-array return keeps flowing into buildSweepRepos exactly as before
+    // rather than throwing us into the fallback branch below.
+    const reposSwept = Array.isArray(candidates) ? candidates.length : undefined;
+    return await mirrorBoard({ repoRoot, repos, now: nowForMirror, dryRun, fs, hostPaths, caller: 'sweepBoard', reposSwept });
   } catch (err) {
     console.warn('[sweepBoard] host-wide enumeration failed — degraded to single-repo board write:', err?.message ?? err);
     // Best-effort fallback: enumeration failed for any reason — degrade to the
     // pre-#716 single-repo write so the board is still updated for THIS repo.
-    return mirrorBoard({ repoRoot, explicitStatus: 'in-progress', now: nowForMirror, dryRun, fs, hostPaths });
+    // `reposSwept` is deliberately NOT passed: nothing was enumerated, so the
+    // field is omitted rather than reported as 0 (absent is not zero).
+    return mirrorBoard({ repoRoot, explicitStatus: 'in-progress', now: nowForMirror, dryRun, fs, hostPaths, caller: 'sweepBoard' });
   }
 }