session-orchestrator 3.22.0 → 3.23.0

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

@@ -14,6 +14,7 @@ import { isRealSession } from '../session-schema/filters.mjs';
 import { resolveRepoNamespace } from './namespace.mjs';
 import { detectLearningSchema, normalizeLearningEntry, generateLearningNote, generateLearningNoteV2 } from './render-learnings.mjs';
 import { detectSessionSchema, normalizeSessionEntry, generateSessionNote, generateSessionNoteV2, generateSessionNoteV3 } from './render-sessions.mjs';
+import { emitMirrorEvent } from './telemetry.mjs';
 
 const GENERATOR_MARKER = 'session-orchestrator-vault-mirror@1';
 
@@ -256,8 +257,33 @@ export { deriveRepo } from './namespace.mjs';
  * @param {object} [opts.meta] — optional extra fields merged into the emitted JSON
  *   (used for quality-gate skips to carry a `reason` field). Callers that omit
  *   `meta` get the base JSON shape unchanged.
+ * @param {number} [opts.line] — 1-based JSONL line number. When FINITE, this
+ *   entry also gets one `orchestrator.vault.mirror_completed` ledger record
+ *   (#1147) — UNLESS `action` is `skipped-noop`, whose per-entry record is
+ *   suppressed as ledger flood and reported only in the run-level roll-up
+ *   (#1151; see the gate below). Omitting `line` keeps the stdout-only
+ *   behaviour, which is what the direct unit tests of this function exercise.
+ * @param {boolean} [opts.dryRun] — the run's dry-run flag, for telemetry only.
+ * @param {string} [opts.skipClass] — `validation` | `mapper-crash`; telemetry only.
+ * @param {string} [opts.reason] — explicit telemetry reason. Defaults to
+ *   `meta.reason` when that exists, so the quality-gate strings
+ *   (`confidence:X < min:Y` / `narrative:N < min:M` / `status:…`) are REUSED
+ *   rather than recomputed — recomputing is how one fact becomes two copies.
+ * @returns {Promise<string>} the `action` string, so the CLI's main loop can
+ *   tally a run-level denominator without a second census of these call sites.
  */
-export function emitAction({ action, path, kind, id, vaultDir, meta }) {
+export async function emitAction({
+  action,
+  path,
+  kind,
+  id,
+  vaultDir,
+  meta,
+  line,
+  dryRun,
+  skipClass,
+  reason,
+}) {
   let rel;
   if (path === null || path === undefined) {
     rel = null;
@@ -271,7 +297,59 @@ export function emitAction({ action, path, kind, id, vaultDir, meta }) {
   if (meta && typeof meta === 'object') {
     Object.assign(payload, meta);
   }
+  // The stdout JSON-per-entry protocol is the CONTRACT other callers parse —
+  // it stays byte-identical; the ledger record below is purely additive.
   process.stdout.write(JSON.stringify(payload) + '\n');
+
+  // Per-entry ledger record for every action EXCEPT `skipped-noop` (#1151).
+  //
+  // `skipped-noop` is the STEADY STATE, not an event: on a populated vault
+  // nearly every record is already mirrored, so one `--kind session` run over
+  // this repo's ~276-record sessions ledger wrote ~276 per-entry records that
+  // between them said "nothing happened" — burying every other event class in
+  // the same file. No information is lost by dropping them: `finishRun()` in
+  // `scripts/vault-mirror.mjs` counts this class into the run event's `skipped`
+  // total AND names it in `action_breakdown['skipped-noop']`, so the noop COUNT
+  // stays measured per run and the gate stays falsifiable (HR-105).
+  //
+  // BV-004 ceiling: what this drops is the per-LINE locator for noops — the
+  // ledger can still say HOW MANY records were unchanged, never WHICH. Revisit
+  // if a consumer ever needs to name them (a staleness audit over unchanged
+  // notes would); reinstate it behind an opt-in flag then, not unconditionally.
+  if (Number.isFinite(line) && action !== 'skipped-noop') {
+    const telemetryReason =
+      reason ?? (meta && typeof meta.reason === 'string' ? meta.reason : undefined);
+    await emitMirrorEvent({
+      action,
+      kind,
+      line,
+      recordId: id,
+      // The VAULT-RELATIVE path (`rel`), never the absolute one: the ledger
+      // record can travel over the optional Clank webhook unredacted.
+      path: rel,
+      skipClass,
+      reason: telemetryReason,
+      dryRun,
+    });
+  }
+
+  return action;
+}
+
+/**
+ * Per-entry stdout + telemetry wrapper used by {@link processLearning} and
+ * {@link processSession}. Threads the line number, kind, vaultDir and dry-run
+ * flag out of the processor `ctx` so the 18 call sites do not repeat them.
+ *
+ * @param {number} lineNum — 1-based JSONL line number of the entry.
+ * @param {object} ctx — processor context (`vaultDir`, `dryRun`, `kind`).
+ * @param {object} opts — the remaining {@link emitAction} fields (`action`,
+ *   `path`, `id`, and optionally `meta`).
+ * @returns {Promise<string>} the `action` string.
+ */
+function emitEntryAction(lineNum, ctx, opts) {
+  const { vaultDir, dryRun, kind } = ctx;
+  return emitAction({ ...opts, vaultDir, kind, line: lineNum, dryRun });
 }
 
 // ── Secret masking (#974) — THE choke-point ───────────────────────────────────
@@ -447,7 +525,7 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   const {
     vaultDir,
     dryRun,
-    kind,
+    kind: _kind, // threaded to emitAction via ctx by emitEntryAction (#1147); kept for ctx symmetry
     force = false,
     qualityMinConfidence = 0.5,
     qualityMinNarrativeChars: _qualityMinNarrativeChars = 400, // unused for learnings; kept for ctx symmetry
@@ -531,15 +609,12 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   // Missing/non-numeric confidence is treated as 1.0 (legacy entries pass).
   const learningConfidence = typeof entry.confidence === 'number' ? entry.confidence : 1.0;
   if (learningConfidence < qualityMinConfidence) {
-    emitAction({
+    return emitEntryAction(_lineNum, ctx, {
       action: 'skipped-quality-low',
       path: null,
-      kind,
       id: entryId,
-      vaultDir,
       meta: { reason: `confidence:${learningConfidence} < min:${qualityMinConfidence}` },
     });
-    return;
   }
 
   // #660: namespace new writes under a per-repo subdirectory.
@@ -572,8 +647,7 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
         // Render the candidate and compare canonical fields before deciding to skip.
         const candidateContent = generator(entry, slug, generatorOpts);
         if (learningContentMatches(legacyContent, candidateContent)) {
-          emitAction({ action: 'skipped-noop', path: legacyFlatPath, kind, id: slug, vaultDir });
-          return;
+          return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: legacyFlatPath, id: slug });
         }
         // Content differs — fall through to write into the namespaced path.
       }
@@ -588,15 +662,13 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     if (!fm || !fm['_generator']) {
       // Hand-written: skip
       process.stderr.write(`SKIP hand-written: ${targetPath}\n`);
-      emitAction({ action: 'skipped-handwritten', path: targetPath, kind, id: entryId, vaultDir });
-      return;
+      return emitEntryAction(_lineNum, ctx, { action: 'skipped-handwritten', path: targetPath, id: entryId });
     }
 
     if (fm['_generator'] !== GENERATOR_MARKER) {
       // Different generator — treat as hand-written to be safe
       process.stderr.write(`SKIP unknown generator: ${targetPath}\n`);
-      emitAction({ action: 'skipped-handwritten', path: targetPath, kind, id: entryId, vaultDir });
-      return;
+      return emitEntryAction(_lineNum, ctx, { action: 'skipped-handwritten', path: targetPath, id: entryId });
     }
 
     if (fm['id'] !== slug) {
@@ -611,16 +683,14 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
         const disambigFm = parseFrontmatter(disambigContent);
         if (!disambigFm || !disambigFm['_generator']) {
           process.stderr.write(`SKIP hand-written (disambig): ${targetPath}\n`);
-          emitAction({ action: 'skipped-handwritten', path: targetPath, kind, id: entryId, vaultDir });
-          return;
+          return emitEntryAction(_lineNum, ctx, { action: 'skipped-handwritten', path: targetPath, id: entryId });
         }
         // Check updated advancement; if date has not advanced, also diff content.
         const entryUpdated = toDate(dateSource);
         if (disambigFm['updated'] && disambigFm['updated'] >= entryUpdated) {
           const candidateContent = generator(entry, slug, generatorOpts);
           if (learningContentMatches(disambigContent, candidateContent)) {
-            emitAction({ action: 'skipped-noop', path: targetPath, kind, id: disambigSlug, vaultDir });
-            return;
+            return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: disambigSlug });
           }
           // Content differs — fall through to write.
         }
@@ -628,8 +698,7 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
 
       const content = generator(entry, slug, generatorOpts);
       if (!dryRun) writeFileSync(targetPath, content, 'utf8');
-      emitAction({ action: 'skipped-collision-resolved', path: targetPath, kind, id: slug, vaultDir });
-      return;
+      return emitEntryAction(_lineNum, ctx, { action: 'skipped-collision-resolved', path: targetPath, id: slug });
     }
 
     // Same id: check if updated would advance (unless --force overrides).
@@ -639,8 +708,7 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     if (!force && fm['updated'] && fm['updated'] >= entryUpdated) {
       const candidateContent = generator(entry, slug, generatorOpts);
       if (learningContentMatches(existingContent, candidateContent)) {
-        emitAction({ action: 'skipped-noop', path: targetPath, kind, id: slug, vaultDir });
-        return;
+        return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: slug });
       }
       // Content differs — fall through to overwrite (same path as date-advance branch).
     }
@@ -648,21 +716,20 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     // Overwrite with advanced updated date (or forced re-render)
     const content = generator(entry, slug, generatorOpts);
     if (!dryRun) writeFileSync(targetPath, content, 'utf8');
-    emitAction({ action: 'updated', path: targetPath, kind, id: slug, vaultDir });
-    return;
+    return emitEntryAction(_lineNum, ctx, { action: 'updated', path: targetPath, id: slug });
   }
 
   // File does not exist — create
   const content = generator(entry, slug, generatorOpts);
   if (!dryRun) writeFileSync(targetPath, content, 'utf8');
-  emitAction({ action: 'created', path: targetPath, kind, id: slug, vaultDir });
+  return emitEntryAction(_lineNum, ctx, { action: 'created', path: targetPath, id: slug });
 }
 
 export async function processSession(rawEntry, _lineNum, ctx) {
   const {
     vaultDir,
     dryRun,
-    kind,
+    kind: _kind, // threaded to emitAction via ctx by emitEntryAction (#1147); kept for ctx symmetry
     force = false,
     qualityMinNarrativeChars = 400,
     qualityMinConfidence: _qualityMinConfidence = 0.5, // unused for sessions; kept for ctx symmetry
@@ -716,15 +783,12 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   // status from the vault; the mapping keeps every OTHER status honest, and
   // guards the generators' other entry point (the render.mjs barrel).
   if (!isRealSession(entry)) {
-    emitAction({
+    return emitEntryAction(_lineNum, ctx, {
       action: 'skipped-abandoned',
       path: null,
-      kind,
       id: session_id,
-      vaultDir,
       meta: { reason: `status:${entry?.status}` },
     });
-    return;
   }
 
   // #732: resolve the leak-guarded repo namespace ONCE per session, BEFORE the
@@ -752,15 +816,12 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   const narrativeBody = renderedBody.replace(/^---[\s\S]*?---/m, '').trim();
   const narrativeChars = narrativeBody.length;
   if (narrativeChars < qualityMinNarrativeChars) {
-    emitAction({
+    return emitEntryAction(_lineNum, ctx, {
       action: 'skipped-quality-low',
       path: null,
-      kind,
       id: session_id,
-      vaultDir,
       meta: { reason: `narrative:${narrativeChars} < min:${qualityMinNarrativeChars}` },
     });
-    return;
   }
 
   // #660: namespace new writes under a per-repo subdirectory. repoNs was
@@ -786,8 +847,7 @@ export async function processSession(rawEntry, _lineNum, ctx) {
     if (legacyFm && legacyFm['_generator'] === GENERATOR_MARKER && legacyFm['id'] === session_id) {
       const entryUpdated = toDate(entry.completed_at);
       if (!force && legacyFm['updated'] && legacyFm['updated'] >= entryUpdated) {
-        emitAction({ action: 'skipped-noop', path: legacyFlatPath, kind, id: session_id, vaultDir });
-        return;
+        return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: legacyFlatPath, id: session_id });
       }
       // Updated date would advance — fall through to write into the namespaced path.
     }
@@ -800,31 +860,27 @@ export async function processSession(rawEntry, _lineNum, ctx) {
     if (!fm || !fm['_generator']) {
       // Hand-written: skip
       process.stderr.write(`SKIP hand-written: ${targetPath}\n`);
-      emitAction({ action: 'skipped-handwritten', path: targetPath, kind, id: session_id, vaultDir });
-      return;
+      return emitEntryAction(_lineNum, ctx, { action: 'skipped-handwritten', path: targetPath, id: session_id });
     }
 
     if (fm['_generator'] !== GENERATOR_MARKER) {
       process.stderr.write(`SKIP unknown generator: ${targetPath}\n`);
-      emitAction({ action: 'skipped-handwritten', path: targetPath, kind, id: session_id, vaultDir });
-      return;
+      return emitEntryAction(_lineNum, ctx, { action: 'skipped-handwritten', path: targetPath, id: session_id });
     }
 
     // Same generator: check id and updated
     if (fm['id'] === session_id) {
       const entryUpdated = toDate(entry.completed_at);
       if (!force && fm['updated'] && fm['updated'] >= entryUpdated) {
-        emitAction({ action: 'skipped-noop', path: targetPath, kind, id: session_id, vaultDir });
-        return;
+        return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: session_id });
       }
       if (!dryRun) writeFileSync(targetPath, renderedBody, 'utf8');
-      emitAction({ action: 'updated', path: targetPath, kind, id: session_id, vaultDir });
-      return;
+      return emitEntryAction(_lineNum, ctx, { action: 'updated', path: targetPath, id: session_id });
     }
   }
 
   // File does not exist — create. Reuse the rendered body computed during the
   // quality-gate check (avoids a second generator invocation).
   if (!dryRun) writeFileSync(targetPath, renderedBody, 'utf8');
-  emitAction({ action: 'created', path: targetPath, kind, id: session_id, vaultDir });
+  return emitEntryAction(_lineNum, ctx, { action: 'created', path: targetPath, id: session_id });
 }

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) {