session-orchestrator 3.21.0 → 3.23.0

package/scripts/lib/vault-mirror/telemetry.mjs

@@ -0,0 +1,210 @@
+/**
+ * telemetry.mjs — vault-mirror telemetry emitters (#1116, #1073, #1147).
+ *
+ * Two events, deliberately BOTH:
+ *
+ *   - `orchestrator.vault.mirror_completed` — ONE record per JSONL entry
+ *     processed (created / updated / every `skipped-*` EXCEPT `skipped-noop`),
+ *     carrying the same `action` the CLI wrote to stdout for that entry.
+ *     `skipped-noop` is excluded because it is the steady state of a populated
+ *     vault, not an event: emitting it made a single run write hundreds of
+ *     records that between them said nothing happened (#1151). Its count is
+ *     carried by the run event's `skipped` total and `action_breakdown`, so the
+ *     class stays measured — only its per-line locators are gone.
+ *   - `orchestrator.vault.mirror_run_completed` — ONE record per CLI run,
+ *     carrying the DENOMINATOR (`total` plus the per-class counts).
+ *
+ * The per-entry event alone is not enough, and that is the whole point of the
+ * pairing: a healthy run over an empty source emits zero per-entry records, and
+ * a mirror whose emitter is broken also emits zero — the two are
+ * indistinguishable from the ledger (`.claude/rules/host-resources.md` § HR-105,
+ * "a rule you cannot falsify is not a rule"). The run event is emitted
+ * unconditionally — including on every abort path, where it carries an
+ * `aborted` discriminator (`missing-vault-dir` | `vault-not-canonical` |
+ * `missing-source` | `malformed-json` | `filesystem-error` |
+ * `unexpected-error`). So `total: 0` is a MEASURED zero, a partial count is a
+ * LABELLED partial rather than a silent one, and the record's absence — and
+ * nothing else — is the broken-emitter signal.
+ *
+ * Both emitters are best-effort: a telemetry failure must never fail a mirror
+ * run, so every emit is wrapped and its rejection swallowed (same posture as the
+ * `orchestrator.secret_masker.applied` emit in `scripts/vault-mirror.mjs`).
+ *
+ * Ledger destination: `emitEvent` is called 2-arg, so every event from one run
+ * resolves the SAME destination (`SO_PROJECT_DIR`, i.e. `CLAUDE_PROJECT_DIR` or
+ * the CWD walk-up) as the masker emit. This CLI has no repo-root flag and
+ * deriving one from `--source` would split a single run's telemetry across two
+ * ledgers.
+ */
+
+import { emitEvent, sessionAttribution } from '../events.mjs';
+import { SO_PROJECT_DIR } from '../platform.mjs';
+
+/** Canonical event name for a single vault-mirror JSONL entry. */
+export const MIRROR_EVENT = 'orchestrator.vault.mirror_completed';
+
+/** Canonical event name for the run-level roll-up (the denominator). */
+export const MIRROR_RUN_EVENT = 'orchestrator.vault.mirror_run_completed';
+
+/**
+ * Upper bound (characters) on the `reason` string written into the events
+ * ledger. Renderer validation messages are short and structured
+ * (`missing required field 'x' (session_id=…)`), quality-gate reasons are
+ * shorter still (`confidence:0.4 < min:0.5`), and native mapper-crash messages
+ * are bounded in practice — the clamp only stops a pathological message from
+ * bloating every ledger line. Revisit if a legitimate reason is ever observed
+ * truncated.
+ */
+const MIRROR_REASON_MAX = 300;
+
+/**
+ * "Absent is not zero" admission test (docs/events-schema.md): a field that was
+ * not measured is OMITTED, never written as `0`/`null`. `null` counts as
+ * not-measured here — `record_id` is explicitly `null` for a record carrying
+ * neither `id` nor `session_id`, and a null `record_id` in the ledger would read
+ * as a measured empty id rather than as "this record had none".
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+const present = (v) => v !== undefined && v !== null;
+
+/**
+ * Session attribution for this CLI's events.
+ *
+ * The explicit `SO_PROJECT_DIR` argument is LOAD-BEARING, not decoration:
+ * `readLock()` (via `lockPathFor`) defaults to `process.cwd()`, NOT to
+ * `SO_PROJECT_DIR`. Calling `sessionAttribution()` bare would therefore read the
+ * lock of whatever directory the process happens to run in while the ledger line
+ * lands under `CLAUDE_PROJECT_DIR` — attributing a record to a session that
+ * never wrote it. Same root for both halves or neither.
+ *
+ * @returns {{session_id?: string, semantic_session_id?: string}}
+ */
+function mirrorSessionAttribution() {
+  return sessionAttribution(SO_PROJECT_DIR);
+}
+
+/**
+ * Emit one `orchestrator.vault.mirror_completed` telemetry record for a single
+ * mirrored entry. Never throws — a rejected emit is swallowed silently.
+ *
+ * @param {object} opts
+ * @param {string} opts.action — the `action` value the CLI wrote to stdout for
+ *   this same entry (`created` | `updated` | `skipped-*`).
+ * @param {string} opts.kind — `learning` | `session` (the `--kind` flag).
+ * @param {number} opts.line — 1-based JSONL line number of the entry. Always
+ *   measured; the only locator available when the record has no id.
+ * @param {string|null} [opts.recordId] — the record's `id` / `session_id`.
+ *   Omitted from the payload when absent.
+ * @param {string|null} [opts.path] — VAULT-RELATIVE target path, when one was
+ *   resolved. Omitted on `skipped-invalid` and on the pre-path quality skips,
+ *   which are reached before any target path exists. Relative, never absolute:
+ *   this payload also travels over the optional Clank webhook with no
+ *   redaction, and an absolute path leaks the operator's home directory.
+ * @param {string} [opts.skipClass] — failure-class discriminator on the invalid
+ *   branches: `validation` | `mapper-crash`.
+ * @param {string} [opts.reason] — the renderer's error message, or the
+ *   quality-gate `meta.reason` string. Clamped to {@link MIRROR_REASON_MAX}.
+ * @param {boolean} [opts.dryRun] — whether this run wrote anything at all.
+ * @returns {Promise<void>}
+ */
+export async function emitMirrorEvent({
+  action,
+  kind,
+  line,
+  recordId,
+  path,
+  skipClass,
+  reason,
+  dryRun,
+}) {
+  try {
+    await emitEvent(MIRROR_EVENT, {
+      action,
+      kind,
+      line,
+      ...(present(recordId) ? { record_id: recordId } : {}),
+      ...(present(path) ? { path } : {}),
+      ...(present(skipClass) ? { skip_class: skipClass } : {}),
+      ...(present(reason) ? { reason: String(reason).slice(0, MIRROR_REASON_MAX) } : {}),
+      ...(typeof dryRun === 'boolean' ? { dry_run: dryRun } : {}),
+      ...mirrorSessionAttribution(),
+    });
+  } catch {
+    // Silent no-op — telemetry must never be the reason a mirror run fails.
+  }
+}
+
+/**
+ * Emit the single `orchestrator.vault.mirror_run_completed` roll-up for a
+ * whole CLI run. Never throws.
+ *
+ * The five counters (`total`, `created`, `updated`, `skipped`, `failed`) are
+ * ALWAYS present, INCLUDING when they are `0` — they are the denominator, and
+ * this is the one place where a written zero is the payload rather than a
+ * violation of "absent is not zero": each one was measured over the entire run.
+ * `action_breakdown` is the opposite: it enumerates only the actions that
+ * actually occurred, and a missing key there means zero occurrences (the
+ * always-present `total` makes that reading unambiguous).
+ *
+ * On an ABORTED run the same five counters are still written, and `aborted`
+ * is what keeps them honest: it says the run stopped before its tail, so the
+ * lines after the abort were never attempted and
+ * `created + updated + skipped + failed === total` no longer holds. Without
+ * that label a partial denominator would be indistinguishable from a complete
+ * one — the same "absent is not zero" failure this event exists to prevent,
+ * one level up.
+ *
+ * @param {object} opts
+ * @param {string} opts.kind — `learning` | `session` (the `--kind` flag).
+ * @param {number} opts.total — non-blank JSONL entries the run attempted.
+ * @param {number} opts.created — entries whose action was `created`.
+ * @param {number} opts.updated — entries whose action was `updated`.
+ * @param {number} opts.skipped — entries skipped for a NON-failure reason
+ *   (`skipped-noop`, `skipped-handwritten`, `skipped-quality-low`,
+ *   `skipped-collision-resolved`, `skipped-abandoned`).
+ * @param {number} opts.failed — entries that produced `skipped-invalid`
+ *   (validation error or mapper crash). Split out from `skipped` because these
+ *   are the runs where a session silently ends up WITHOUT its vault note.
+ * @param {Record<string, number>} [opts.actionBreakdown] — per-action counts;
+ *   only actions observed at least once appear.
+ * @param {boolean} opts.dryRun — whether this run wrote anything at all.
+ * @param {'missing-vault-dir'|'vault-not-canonical'|'missing-source'|'malformed-json'|'filesystem-error'|'unexpected-error'} [opts.aborted]
+ *   Present ONLY when the run exited before its normal tail. OMITTED on a
+ *   complete run — absent means "ran to the end", never "unknown". The first
+ *   three values are PRE-LOOP aborts (#1151): the run never reached its first
+ *   entry, so all five counters are `0` and that zero is the point — without a
+ *   record, a mirror that never started is indistinguishable from one that was
+ *   never invoked.
+ * @returns {Promise<void>}
+ */
+export async function emitMirrorRunEvent({
+  kind,
+  total,
+  created,
+  updated,
+  skipped,
+  failed,
+  actionBreakdown,
+  dryRun,
+  aborted,
+}) {
+  try {
+    await emitEvent(MIRROR_RUN_EVENT, {
+      kind,
+      total,
+      created,
+      updated,
+      skipped,
+      failed,
+      ...(actionBreakdown && Object.keys(actionBreakdown).length > 0
+        ? { action_breakdown: actionBreakdown }
+        : {}),
+      dry_run: dryRun,
+      ...(present(aborted) ? { aborted } : {}),
+      ...mirrorSessionAttribution(),
+    });
+  } catch {
+    // Silent no-op — telemetry must never be the reason a mirror run fails.
+  }
+}

package/scripts/lib/vault-staleness-banner.mjs

@@ -1,5 +1,5 @@
 /**
- * vault-staleness-banner.mjs — #319
+ * vault-staleness-banner.mjs — #319, record-age gate #1159
  * Reads the latest vault-staleness probe record and classifies a banner
  * severity (warn | alert) for surfacing stale projects in the Meta-Vault.
  *
@@ -9,11 +9,36 @@
  *   {timestamp, probe, project_root, vault_dir, scanned_projects,
  *    stale_count, errors, duration_ms,
  *    findings: [{slug, severity, last_sync, delta_hours, flag}, ...]}
+ *
+ * **One vocabulary, not two (#1158/#1159 review, N3).** The record-age gate's
+ * first cut returned `severity: 'info'` for a stale probe record, and the
+ * `vault-staleness` registry entry in `scripts/lib/session-start-probes.mjs`
+ * then had to remap that to `'warn'` by hand so the banner would actually
+ * render (the module-level default there drops anything but warn/alert as
+ * `'ok'`, silent). Two files disagreeing about what severity the SAME record
+ * carries is the defect, not either value alone — this module now returns
+ * `severity: 'warn'` directly for the demoted case, and the registry needs no
+ * remap for it. `kind: 'probe-stale'` still carries the "this is a demotion,
+ * not a fresh finding" meaning for any consumer that cares.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * Max age (in days) of the last probe record before its stale-project
+ * findings are demoted to a `kind: 'probe-stale'` result (#1159; severity
+ * stays `'warn'` — see N3 in the header). The vault-sync bridge runs hourly,
+ * but the probe itself only runs per `/discovery` invocation or at
+ * session-end — so a week with no new record means the PROBE has stopped
+ * running, not that the projects it last saw are still stale today. A
+ * 47-day-old record was otherwise re-reported as a current finding on every
+ * session start.
+ */
+export const MAX_RECORD_AGE_DAYS = 7;
+
 /**
  * Format a delta_hours number for the banner message.
  * Rounds to 1 decimal; integers render without a trailing ".0".
@@ -34,21 +59,39 @@ function formatDelta(hours) {
  * computes a banner severity classification. Never throws — graceful no-op
  * on any read error, schema mismatch, or empty/zero-stale state.
  *
- * Severity rules (issue #319):
+ * Severity rules (issue #319, record-age gate #1159, single-vocabulary N3):
  *   - file absent / unreadable / malformed / stale_count === 0 → null (silent)
- *   - stale_count > 0 AND maxDelta <= 48 → 'warn'
- *   - stale_count > 0 AND maxDelta  > 48 → 'alert' (cron likely broken)
+ *   - stale_count > 0 AND record.timestamp older than MAX_RECORD_AGE_DAYS
+ *     → {severity: 'warn', kind: 'probe-stale', ...} (the probe stopped
+ *     running; the recorded findings are not a current finding — `kind`
+ *     carries the demotion meaning, `severity` is what every consumer reads)
+ *   - stale_count > 0 AND missing/unparsable timestamp AND maxDelta <= 48
+ *     → 'warn' (unchanged pre-#1159 behaviour)
+ *   - stale_count > 0 AND missing/unparsable timestamp AND maxDelta  > 48
+ *     → 'alert' (cron likely broken; unchanged pre-#1159 behaviour)
+ *   - stale_count > 0 AND record.timestamp within MAX_RECORD_AGE_DAYS AND
+ *     maxDelta <= 48 → 'warn'
+ *   - stale_count > 0 AND record.timestamp within MAX_RECORD_AGE_DAYS AND
+ *     maxDelta  > 48 → 'alert' (cron likely broken)
  *
- * @param {{repoRoot: string}} opts
+ * @param {{repoRoot: string, now?: number}} opts `now` is an optional clock
+ *   seam (epoch ms, defaults to `Date.now()`) so callers can test the
+ *   age gate deterministically without global fake timers.
  * @returns {null | {
  *   severity: 'warn'|'alert',
  *   message: string,
  *   staleCount: number,
  *   maxDeltaHours: number,
  *   timestamp: string,
+ * } | {
+ *   severity: 'warn',
+ *   kind: 'probe-stale',
+ *   message: string,
+ *   ageDays: number,
+ *   timestamp: string,
  * }}
  */
-export function checkVaultStaleness({ repoRoot } = {}) {
+export function checkVaultStaleness({ repoRoot, now = Date.now() } = {}) {
   try {
     if (!repoRoot || typeof repoRoot !== 'string') return null;
 
@@ -91,6 +134,33 @@ export function checkVaultStaleness({ repoRoot } = {}) {
 
     if (staleCount === 0) return null;
 
+    // Record-age gate (#1159): a parseable timestamp older than
+    // MAX_RECORD_AGE_DAYS means the PROBE has not run since, not that the
+    // projects it last saw are still stale — demote the FINDING (via `kind`)
+    // rather than re-reporting a warn/alert every session, but keep
+    // `severity: 'warn'` (N3, #1158/#1159 review) so a caller reading only
+    // `severity` still renders it; a second `severity: 'info'` vocabulary
+    // that only the registry's remap understood was the two-files-disagree
+    // defect this shape replaces. A missing or unparsable timestamp falls
+    // through to today's behaviour unchanged.
+    const rawTimestamp = record.timestamp;
+    const parsedMs = typeof rawTimestamp === 'string' ? Date.parse(rawTimestamp) : NaN;
+    if (Number.isFinite(parsedMs)) {
+      const ageDays = Math.floor((now - parsedMs) / MS_PER_DAY);
+      if (ageDays > MAX_RECORD_AGE_DAYS) {
+        return {
+          severity: 'warn',
+          kind: 'probe-stale',
+          message:
+            `⚠ vault-staleness: last probe record is ${ageDays} days old ` +
+            `(${rawTimestamp}) — the probe has not run since; the recorded ` +
+            `${staleCount} stale projects are NOT a current finding.`,
+          ageDays,
+          timestamp: rawTimestamp,
+        };
+      }
+    }
+
     // Compute max delta_hours across findings; treat undefined/null/NaN as 0.
     let maxDelta = 0;
     for (const finding of record.findings) {

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';
@@ -681,6 +690,131 @@ 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]
+ * @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 }) {
+  // 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 } : {}),
+        // #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 +851,14 @@ 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 }>}
+ *   `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,16 +867,16 @@ 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.
@@ -747,7 +884,7 @@ export async function mirrorBoard({ repoRoot, repos, explicitStatus, now = new D
   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
@@ -922,7 +1059,55 @@ export async function mirrorBoard({ repoRoot, repos, explicitStatus, now = new D
 
   const content = renderBoard([...merged.values()], { now, createdIso });
 
-  return writeBoard({ outputPath, content, dryRun, fs });
+  return { result: writeBoard({ outputPath, content, dryRun, fs }), rows: merged.size };
+}
+
+/**
+ * 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 } = await mirrorBoardInner(opts);
+
+  await emitBoardEvent({
+    repoRoot,
+    caller,
+    action: result?.action,
+    path: result?.path,
+    rows,
+    reposSwept,
+    durationMs: Date.now() - startedAt,
+  });
+
+  return result;
 }
 
 // ── Host-wide sweep (issue #716) ─────────────────────────────────────────────────
@@ -1022,6 +1207,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 +1252,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' });
   }
 }