session-orchestrator 3.22.0 → 3.23.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';
@@ -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' });
   }
 }

package/scripts/lib/vault-status/narrative-mirror.mjs

@@ -18,6 +18,7 @@
  *
  * Exports:
  *   GENERATOR_MARKER       — frontmatter sentinel identifying generator-owned files
+ *   NARRATIVE_EVENT        — canonical telemetry event name for a mirror attempt
  *   extractNarrative       — pure: STATE.md contents → { waveHistory, deviations, whatNotToRetry, missionStatus }
  *   renderNarrative        — pure: narrative + repo + now → full markdown (frontmatter + body)
  *   writeNarrative         — idempotent write with skip-handwritten / skip-noop / dry-run + _overview refusal
@@ -30,6 +31,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 
+import { emitEvent, sessionAttribution } from '../events.mjs';
 import { parseStateMd, parseMissionStatus } from '../state-md.mjs';
 import {
   parseFrontmatter,
@@ -557,6 +559,128 @@ function resolveLooseSlug(vaultDir, candidateSlug, fsSeam = {}) {
   return matches.length === 1 ? matches[0] : candidateSlug;
 }
 
+// ── Telemetry ────────────────────────────────────────────────────────────────────
+
+/**
+ * Canonical event name for a narrative-mirror attempt (issue #1129).
+ *
+ * ONE event per {@link mirrorNarrative} call — the REJECTION and NO-OP paths
+ * included, because those are the point. Before this existed, a vault-disabled
+ * config, a missing STATE.md, a hand-authored target file and a healthy write
+ * were all indistinguishable from the ledger's side: measured 2026-08-23 over
+ * 28 387 records in `.orchestrator/metrics/events.jsonl`, ZERO board/mirror
+ * events, because this module did not import {@link emitEvent} at all. Its only
+ * caller is shell prose in `skills/session-end/session-metrics-write.md`, whose
+ * `mode: warn` degradation prints a WARNING and closes the session anyway — so
+ * an outage of this writer left no durable trace whatsoever.
+ *
+ * Name deliberately NOT minted here: it is the one the wave assigned, so the
+ * fact "a narrative mirror ran" has exactly one address in the ledger.
+ */
+export const NARRATIVE_EVENT = 'orchestrator.vault.narrative_mirrored';
+
+/**
+ * Emit the narrative-mirror telemetry record. Best-effort: never throws, never
+ * alters the mirror 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`. `chars: 0` would then honestly mean "the narrative rendered to
+ * an empty document"; an absent `chars` means "no render was reached on this
+ * path" — reading the missing key as `0` conflates the two in both directions.
+ *
+ * NAMED CEILING (build-value BV-004): when `repoRoot` is absent or empty this
+ * emits NOTHING. `emitEvent` without `opts.repoRoot` falls back to
+ * `SO_PROJECT_DIR` (#941), so the only destination left for a rootless call is
+ * whichever repo the process happens to sit in — i.e. a caller that named no
+ * repo would silently append to a FOREIGN ledger, and the two call shapes that
+ * reach this branch today are the `repoRoot: ''` / omitted-`repoRoot` unit
+ * tests, which would then write synthetic records into this repo's real fleet
+ * telemetry on every suite run. REVISIT TRIGGER: if a production caller ever
+ * legitimately invokes `mirrorNarrative` without a `repoRoot`, that call needs a
+ * destination decision of its own — not this silent skip.
+ *
+ * @param {object} opts
+ * @param {string} [opts.repoRoot] — pins the ledger to THIS repo's
+ *   `.orchestrator/metrics/events.jsonl` (#941), and supplies session attribution.
+ * @param {string} opts.action — the `action` the mirror returned, or `'error'`
+ *   when the writer threw. ALWAYS present.
+ * @param {string} [opts.path] — resolved narrative path, when one was resolved.
+ * @param {number} [opts.chars] — length of the rendered narrative document this
+ *   call produced. Present whenever the render was reached (so also on
+ *   `skipped-noop` / `dry-run`, where the document was built but not written —
+ *   `action` is what says whether it landed); absent on the earlier no-op paths,
+ *   which return before anything is rendered.
+ * @param {string} [opts.errorCode] — `err.code` on the throw path (a bounded
+ *   token such as `EACCES`). The error MESSAGE is deliberately NOT recorded: it
+ *   can quote a path or STATE.md content, and this module's whole reason for
+ *   masking (#1025) is that such prose carries secrets.
+ * @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 emitNarrativeEvent({ repoRoot, action, path: outputPath, chars, errorCode }) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return;
+  try {
+    await emitEvent(
+      NARRATIVE_EVENT,
+      {
+        action,
+        ...(telemetrySafePath(outputPath) !== undefined ? { path_tail: telemetrySafePath(outputPath) } : {}),
+        // `typeof … === 'number'` rather than `!= null`: the repo's eslint
+        // `eqeqeq: always` forbids the loose form, and this shape additionally
+        // refuses a non-numeric `chars` outright. A measured `0` still lands.
+        ...(typeof chars === 'number' ? { chars } : {}),
+        // `typeof === 'string'`, not truthiness: an `err.code` of '' is a measured
+        // empty code, and the sibling `chars` field four lines up already states
+        // why this file rejects the loose form.
+        ...(typeof errorCode === 'string' && errorCode.length > 0 ? { error_code: errorCode } : {}),
+        // session_id / semantic_session_id — omitted entirely when no session
+        // lock is readable (CI, ad-hoc runs). See sessionAttribution's contract:
+        // a fabricated id would read as a real session.
+        ...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 narrative write. The mirror result is authoritative. */
+  }
+}
+
 // ── Convenience orchestration ────────────────────────────────────────────────────
 
 /**
@@ -594,10 +718,50 @@ function resolveLooseSlug(vaultDir, candidateSlug, fsSeam = {}) {
  * @returns {Promise<{ action: string, path?: string }>}
  */
 export async function mirrorNarrative(opts) {
+  let outcome;
+  try {
+    outcome = await runNarrativeMirror(opts);
+  } catch (err) {
+    // The harshest silent-failure case: `session-metrics-write.md` catches this
+    // throw, prints a WARNING under `mode: warn` and closes the session anyway.
+    // Record it, then re-throw — telemetry observes, it never swallows.
+    await emitNarrativeEvent({
+      repoRoot: opts?.repoRoot,
+      action: 'error',
+      errorCode: typeof err?.code === 'string' ? err.code : undefined,
+    });
+    throw err;
+  }
+
+  await emitNarrativeEvent({
+    repoRoot: opts?.repoRoot,
+    action: outcome.result.action,
+    path: outcome.result.path,
+    chars: outcome.chars,
+  });
+
+  return outcome.result;
+}
+
+/**
+ * The mirror itself — every early return of {@link mirrorNarrative} lives here.
+ *
+ * Split out so that exactly ONE emit site covers EVERY outcome: a future early
+ * return added inside this function is telemetered by construction, whereas
+ * hand-placing an emit beside each of the seven `return`s makes "forgot the new
+ * one" the default failure. The `chars` companion travels beside the result
+ * rather than inside it because the returned object is a PUBLIC shape that
+ * callers (and tests) compare with `toEqual` — adding a key there would be an
+ * observable contract change for a purely internal measurement.
+ *
+ * @param {Parameters<typeof mirrorNarrative>[0]} opts
+ * @returns {Promise<{ result: { action: string, path?: string }, chars?: number }>}
+ */
+async function runNarrativeMirror(opts) {
   const { repoRoot, repo, now = new Date(), dryRun = false, fs: injectedFs, hostPaths } = opts;
 
   if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
 
   // Read Session Config (CLAUDE.md / AGENTS.md) and resolve vault settings.
@@ -606,12 +770,12 @@ export async function mirrorNarrative(opts) {
     const configText = await readConfigFile(repoRoot);
     config = parseSessionConfig(configText, { hostPaths });
   } catch {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
 
   const vaultIntegration = config?.['vault-integration'];
   if (!vaultIntegration || vaultIntegration.enabled !== true) {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
 
   // Defense-in-depth: when the caller omits (or passes an empty) `repo`, derive
@@ -628,7 +792,7 @@ export async function mirrorNarrative(opts) {
 
   const rawVaultDir = vaultIntegration['vault-dir'];
   if (!rawVaultDir || typeof rawVaultDir !== 'string') {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
 
   const vaultDir = path.resolve(expandHome(rawVaultDir));
@@ -640,9 +804,19 @@ export async function mirrorNarrative(opts) {
   const outputPath = resolveNarrativePath(vaultDir, repoSlug);
 
   // Defense-in-depth: ensure the resolved file stays inside the vault root.
-  const inside = validatePathInsideProject(path.relative(vaultDir, outputPath), vaultDir);
+  //
+  // `canonicalizeRoot: true` (#1033) is load-bearing, not hygiene. The guard's
+  // realpath phase is skipped while the target is ABSENT (ENOENT) and fires once
+  // it EXISTS — so on a vault root reached through a symlink, run 1 writes and
+  // run 2 resolves the file to the canonical path, reads it as outside the
+  // LEXICAL root, and returns `skipped-invalid-path` forever after. Canonicalizing
+  // the root makes both sides of the comparison the same kind of path. Same call
+  // shape as scripts/lib/reconcile/writer.mjs and scripts/lib/memory-proposals/store.mjs.
+  const inside = validatePathInsideProject(path.relative(vaultDir, outputPath), vaultDir, {
+    canonicalizeRoot: true,
+  });
   if (!inside.ok) {
-    return { action: 'skipped-invalid-path', path: outputPath };
+    return { result: { action: 'skipped-invalid-path', path: outputPath } };
   }
 
   // Read STATE.md (best-effort; absent STATE.md → nothing to mirror).
@@ -651,7 +825,7 @@ export async function mirrorNarrative(opts) {
   try {
     stateContents = await readFile(stateMdPath, 'utf8');
   } catch {
-    return { action: 'skipped-no-statemd', path: outputPath };
+    return { result: { action: 'skipped-no-statemd', path: outputPath } };
   }
 
   // #1025: the ONE masking site for the narrative mirror — after the frontmatter
@@ -660,5 +834,11 @@ export async function mirrorNarrative(opts) {
   const narrative = maskNarrative(extractNarrative(stateContents));
   const content = renderNarrative({ repo: repoName, narrative, now });
 
-  return writeNarrative({ outputPath, content, dryRun, fs: injectedFs });
+  // `chars` measures the document THIS call rendered — so it is present on
+  // `skipped-noop` and `dry-run` too, where the render happened but nothing
+  // landed. `action` is the field that says whether it landed.
+  return {
+    result: writeNarrative({ outputPath, content, dryRun, fs: injectedFs }),
+    chars: content.length,
+  };
 }