session-orchestrator 3.24.0 → 4.0.1

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

@@ -213,6 +213,37 @@ function learningContentMatches(existingContent, renderedContent) {
   );
 }
 
+/**
+ * Would the process-wide masker (see `ensureMasker` below) still change `text`
+ * if it ran again right now? (#1028 residue 1)
+ *
+ * Used as a LAST guard before returning `skipped-noop` in BOTH `processLearning`
+ * and `processSession` — the session channel's two skip sites were date-only
+ * until the W4 review of #1028 (see the module note above).
+ * `learningContentMatches` above compares only five canonical fields, so it
+ * cannot see a raw secret sitting in a NON-canonical field (`evidence` is the
+ * realistic one — see the KNOWN-RESIDUAL note on `maskEntrySecrets` below): a
+ * candidate that matches on those five fields can still be an on-disk leak.
+ * When this returns `true`, the caller must NOT skip — it falls through to the
+ * write path so the note is re-rendered (and re-masked) from the current entry.
+ *
+ * NAMED CEILING: this only heals a needle that is still present in the CURRENT
+ * process env. A needle that has since been rotated out of the env no longer
+ * masks to anything different, so `mask(text) === text` and this returns
+ * `false` — that needle's leak is healed only by an explicit `force: true`
+ * re-mirror (which bypasses the comparison entirely), never by a plain re-run.
+ *
+ * COST: one extra `mask()` call per candidate no-op — cheap relative to the
+ * read/parse/render already done to reach this check, and only paid on the
+ * no-op path (a real content change already writes without reaching here).
+ *
+ * @param {string} text — on-disk note content to probe
+ * @returns {boolean} true when masking `text` again would produce different output
+ */
+function maskerWouldChange(text) {
+  return ensureMasker().mask(text) !== text;
+}
+
 // ── repo derivation ───────────────────────────────────────────────────────────
 
 /**
@@ -451,36 +482,54 @@ export function getMaskerStats() {
  *      as a wildcard (see that function) so this direction resolves to
  *      `skipped-noop` again.
  *
- *      KNOWN RESIDUAL — and NOT the one an earlier revision of this note named.
- *      That revision claimed a COLD-START FREEZE over the CANONICAL fields: first
- *      run without the env writes the raw value, later runs render `[REDACTED]`,
- *      and the note freezes. Measured, that direction HEALS: with no marker on the
- *      on-disk side `matchesModuloRedaction` returns false at its first line, the
- *      canonical fields differ, and the run writes the masked content. The
- *      asymmetry is still deliberate (an on-disk redaction is evidence a mask ran;
- *      an on-disk raw value is evidence of nothing) — it simply does not freeze
- *      anything the field comparison can see.
- *
- *      What DOES freeze is the half the field comparison cannot see.
- *      `learningContentMatches` compares exactly five canonical fields — `status`,
- *      `expires`, `confidence`, `insight`, `source_session`. A raw secret sitting
- *      in any OTHER field (`evidence` is the realistic one; it is agent-authored
- *      free text and it is rendered into the note) leaves all five identical
- *      between the raw on-disk note and the masked candidate. The comparison
- *      reports a match, the run emits `skipped-noop`, and the plaintext stays in
- *      the tracked, pushed file permanently — no later run rewrites it, because no
- *      later run ever sees a difference.
- *
- *      THE ESCAPE HATCH EXISTS AND IS UNDOCUMENTED ELSEWHERE, which is the real
- *      defect: `processLearning(entry, n, { ...ctx, force: true })` skips the
- *      date/content comparison entirely and re-renders from the (masked) entry, so
- *      a single forced re-mirror with the env populated heals every such note. It
- *      covers the same-id and legacy-flat paths; the disambiguated-collision
- *      branch below does not read `force` and is not healed by it.
- *      Revisit-Trigger: widen the canonical field set (or diff the whole rendered
- *      body) the first time a mirror run is observed leaving a raw needle in a
- *      non-canonical field — a test written TODAY would only pin the leak as
- *      expected behaviour.
+ *      RESIDUAL (#1028), NOW HEALED BY A MASK RE-PROBE — and NOT the residual an
+ *      earlier revision of this note named. That revision claimed a COLD-START
+ *      FREEZE over the CANONICAL fields: first run without the env writes the raw
+ *      value, later runs render `[REDACTED]`, and the note freezes. Measured, that
+ *      direction HEALS: with no marker on the on-disk side `matchesModuloRedaction`
+ *      returns false at its first line, the canonical fields differ, and the run
+ *      writes the masked content. The asymmetry is still deliberate (an on-disk
+ *      redaction is evidence a mask ran; an on-disk raw value is evidence of
+ *      nothing) — it simply does not freeze anything the field comparison can see.
+ *
+ *      What the field comparison ALONE cannot see: `learningContentMatches`
+ *      compares exactly five canonical fields — `status`, `expires`, `confidence`,
+ *      `insight`, `source_session`. A raw secret sitting in any OTHER field
+ *      (`evidence` is the realistic one; it is agent-authored free text and it is
+ *      rendered into the note) leaves all five identical between the raw on-disk
+ *      note and the masked candidate — the comparison alone reports a match.
+ *
+ *      THE FIX — IN BOTH GENERATORS, which is the half an earlier revision of
+ *      this note got wrong: it described the guard as a `processLearning` matter,
+ *      and `processSession` shipped with two purely DATE-based `skipped-noop`
+ *      returns beside it. The session note's narrative body is the LARGER
+ *      free-text surface of the two, so that omission was the bigger half of the
+ *      leak. Every `skipped-noop` return in BOTH `processLearning` (legacy-flat,
+ *      disambig-collision, same-id) and `processSession` (legacy-flat, same-id)
+ *      is now gated by `maskerWouldChange` (see that function above). When the
+ *      on-disk content would still be changed by the CURRENT masker, the run
+ *      falls through to the write path and re-renders (masked) instead of
+ *      skipping — so a plain re-mirror heals the leak on its own; `force: true`
+ *      is no longer the only escape hatch. The disambig-collision branch's
+ *      `!force` guard now also matches the same-id and legacy-flat branches (it
+ *      previously lacked one, so `force: true` was silently ignored there).
+ *
+ *      THE LEGACY-FLAT BRANCH NEEDS ONE MORE STEP (#1028 residue 2). Falling
+ *      through there writes the NAMESPACED path, and from the next run on
+ *      `existsSync(targetPath)` is true — the flat file is never read again. A
+ *      guard alone would therefore leave the plaintext on disk and merely make it
+ *      unreachable to the heal, with the ledger reporting a clean write. Both
+ *      generators now re-render the legacy flat note IN PLACE (masked) before
+ *      falling through, and mark the resulting action `healed_legacy_flat: true`.
+ *      Rewriting rather than deleting is what the deferred-migration decision
+ *      above asks for: that decision is about not MOVING the note, which a masked
+ *      re-render preserves and a deletion would silently undo.
+ *      Revisit-Trigger: `maskerWouldChange` only detects needles present in the
+ *      CURRENT process env — a needle since rotated out of the env is not seen as
+ *      still-leaking and is healed only by an explicit `force: true` re-mirror.
+ *      Widen this (e.g. persist a needle-shape fingerprint, or diff the whole
+ *      rendered body) the first time a rotated-out secret is observed staying on
+ *      disk after a plain re-run.
  *
  * FRONTMATTER AND BODY ARE TREATED IDENTICALLY. A credential is exactly as
  * published in `title:` as it is under `## Insight` — both live in the same
@@ -636,22 +685,48 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   // duplicating the note. The deferred-migration decision means we only skip;
   // we do NOT move the flat note into the namespaced dir here.
   const legacyFlatPath = join(resolve(vaultDir), '40-learnings', `${slug}.md`);
+  // Set when a still-leaking legacy flat note was healed in place below, so the
+  // action emitted for THIS entry can say so (see the write sites at the end).
+  let healedLegacyFlat = false;
   if (!existsSync(targetPath) && existsSync(legacyFlatPath)) {
     const legacyContent = readFileSync(legacyFlatPath, 'utf8');
     const legacyFm = parseFrontmatter(legacyContent);
     // Only skip if the flat note is ours (has our generator marker and matching id).
     if (legacyFm && legacyFm['_generator'] === GENERATOR_MARKER && legacyFm['id'] === slug) {
       const entryUpdated = toDate(dateSource);
+      // #1028 residue 2 (W4 review HIGH-2): the leak probe must run on EVERY
+      // path that leaves this branch, not only the date-not-advanced one — every
+      // one of them falls through to the NAMESPACED path, after which
+      // `existsSync(targetPath)` is true forever and this legacy file is never
+      // read again. A raw secret left in it would become unreachable to the
+      // self-heal while staying fully published in the tracked vault.
+      const legacyStillLeaks = maskerWouldChange(legacyContent);
       if (!force && legacyFm['updated'] && legacyFm['updated'] >= entryUpdated) {
         // Date has not advanced — but content may have changed (confidence, insight, etc.).
         // Render the candidate and compare canonical fields before deciding to skip.
         const candidateContent = generator(entry, slug, generatorOpts);
-        if (learningContentMatches(legacyContent, candidateContent)) {
+        if (learningContentMatches(legacyContent, candidateContent) && !legacyStillLeaks) {
+          // #1028 residue 1: the five-field compare cannot see a raw secret
+          // sitting in a non-canonical field (e.g. `evidence`) — the
+          // `legacyStillLeaks` probe above is what makes this match trustworthy.
           return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: legacyFlatPath, id: slug });
         }
-        // Content differs — fall through to write into the namespaced path.
+        // Content differs, or the on-disk note still leaks under the current
+        // env — fall through to write into the namespaced path.
       }
       // Updated date would advance or content changed — fall through to write into the namespaced path.
+      //
+      // Heal the leaking legacy note IN PLACE first. Rewriting is the option
+      // consistent with the deferred-migration rationale above: that decision is
+      // about not MOVING the note (the flat path stays authoritative for older
+      // vaults and for hand-made links into it), which a masked re-render
+      // preserves and a deletion would silently undo. Deleting an operator-visible
+      // vault file to fix a leak also trades one irreversible loss for another —
+      // the content here is already ours (generator marker + id checked above).
+      if (legacyStillLeaks) {
+        if (!dryRun) writeFileSync(legacyFlatPath, generator(entry, slug, generatorOpts), 'utf8');
+        healedLegacyFlat = true;
+      }
     }
   }
 
@@ -686,13 +761,22 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
           return emitEntryAction(_lineNum, ctx, { action: 'skipped-handwritten', path: targetPath, id: entryId });
         }
         // Check updated advancement; if date has not advanced, also diff content.
+        // #1028 residue 1: this guard previously lacked the `!force &&` that the
+        // legacy-flat and same-id branches carry, so `force: true` was silently
+        // ignored on this one path — byte-identical guard shape to those two now.
         const entryUpdated = toDate(dateSource);
-        if (disambigFm['updated'] && disambigFm['updated'] >= entryUpdated) {
+        if (!force && disambigFm['updated'] && disambigFm['updated'] >= entryUpdated) {
           const candidateContent = generator(entry, slug, generatorOpts);
           if (learningContentMatches(disambigContent, candidateContent)) {
-            return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: disambigSlug });
+            // #1028 residue 1: probe the on-disk content against the CURRENT
+            // masker before trusting the five-field match — see maskerWouldChange.
+            const stillLeaks = maskerWouldChange(disambigContent);
+            if (!stillLeaks) {
+              return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: disambigSlug });
+            }
           }
-          // Content differs — fall through to write.
+          // Content differs, or the on-disk note still leaks under the current
+          // env — fall through to write.
         }
       }
 
@@ -708,9 +792,15 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     if (!force && fm['updated'] && fm['updated'] >= entryUpdated) {
       const candidateContent = generator(entry, slug, generatorOpts);
       if (learningContentMatches(existingContent, candidateContent)) {
-        return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: slug });
+        // #1028 residue 1: probe the on-disk content against the CURRENT masker
+        // before trusting the five-field match — see maskerWouldChange above.
+        const stillLeaks = maskerWouldChange(existingContent);
+        if (!stillLeaks) {
+          return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: slug });
+        }
       }
-      // Content differs — fall through to overwrite (same path as date-advance branch).
+      // Content differs, or the on-disk note still leaks under the current env —
+      // fall through to overwrite (same path as date-advance branch).
     }
 
     // Overwrite with advanced updated date (or forced re-render)
@@ -722,7 +812,15 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   // File does not exist — create
   const content = generator(entry, slug, generatorOpts);
   if (!dryRun) writeFileSync(targetPath, content, 'utf8');
-  return emitEntryAction(_lineNum, ctx, { action: 'created', path: targetPath, id: slug });
+  return emitEntryAction(_lineNum, ctx, {
+    action: 'created',
+    path: targetPath,
+    id: slug,
+    // No PATH in the meta: the stdout payload's `path` is vault-relative on
+    // purpose (emitAction relativises it), a raw absolute path here would put
+    // the operator's home dir on stdout and into the ledger record.
+    ...(healedLegacyFlat ? { meta: { healed_legacy_flat: true } } : {}),
+  });
 }
 
 export async function processSession(rawEntry, _lineNum, ctx) {
@@ -841,15 +939,30 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   // the namespaced path as absent. If a session note already exists flat
   // (pre-namespace migration), skip creating a duplicate.
   const legacyFlatPath = join(resolve(vaultDir), '50-sessions', `${session_id}.md`);
+  let healedLegacyFlat = false;
   if (!existsSync(targetPath) && existsSync(legacyFlatPath)) {
     const legacyContent = readFileSync(legacyFlatPath, 'utf8');
     const legacyFm = parseFrontmatter(legacyContent);
     if (legacyFm && legacyFm['_generator'] === GENERATOR_MARKER && legacyFm['id'] === session_id) {
       const entryUpdated = toDate(entry.completed_at);
-      if (!force && legacyFm['updated'] && legacyFm['updated'] >= entryUpdated) {
+      // #1028 residue 1, session channel (W4 review HIGH-1): the skip decision
+      // here is DATE-ONLY — it never looks at the note's content, so a raw
+      // secret written into the narrative before the env carried the needle
+      // would stay published forever. Same `maskerWouldChange` probe the
+      // learning channel carries; see that function above.
+      const legacyStillLeaks = maskerWouldChange(legacyContent);
+      if (!force && !legacyStillLeaks && legacyFm['updated'] && legacyFm['updated'] >= entryUpdated) {
         return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: legacyFlatPath, id: session_id });
       }
-      // Updated date would advance — fall through to write into the namespaced path.
+      // Updated date would advance, or the on-disk note still leaks — fall
+      // through to write into the namespaced path. Heal the legacy note in place
+      // first (HIGH-2, same rationale as processLearning's legacy-flat branch):
+      // after this run `existsSync(targetPath)` is true, so the flat file is
+      // never read again and its plaintext would be unreachable to the heal.
+      if (legacyStillLeaks) {
+        if (!dryRun) writeFileSync(legacyFlatPath, renderedBody, 'utf8');
+        healedLegacyFlat = true;
+      }
     }
   }
 
@@ -871,7 +984,11 @@ export async function processSession(rawEntry, _lineNum, ctx) {
     // Same generator: check id and updated
     if (fm['id'] === session_id) {
       const entryUpdated = toDate(entry.completed_at);
-      if (!force && fm['updated'] && fm['updated'] >= entryUpdated) {
+      // #1028 residue 1, session channel (W4 review HIGH-1): probe the on-disk
+      // content against the CURRENT masker before trusting the date-only skip —
+      // the session note's narrative body is the larger free-text leak surface
+      // of the two channels. See maskerWouldChange above.
+      if (!force && !maskerWouldChange(existingContent) && fm['updated'] && fm['updated'] >= entryUpdated) {
         return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: session_id });
       }
       if (!dryRun) writeFileSync(targetPath, renderedBody, 'utf8');
@@ -882,5 +999,11 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   // 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');
-  return emitEntryAction(_lineNum, ctx, { action: 'created', path: targetPath, id: session_id });
+  return emitEntryAction(_lineNum, ctx, {
+    action: 'created',
+    path: targetPath,
+    id: session_id,
+    // Boolean only — never a path; see the same note in processLearning.
+    ...(healedLegacyFlat ? { meta: { healed_legacy_flat: true } } : {}),
+  });
 }

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

@@ -38,7 +38,7 @@
  */
 
 import { emitEvent, sessionAttribution } from '../events.mjs';
-import { SO_PROJECT_DIR } from '../platform.mjs';
+import { getProjectDir } from '../platform.mjs';
 
 /** Canonical event name for a single vault-mirror JSONL entry. */
 export const MIRROR_EVENT = 'orchestrator.vault.mirror_completed';
@@ -81,7 +81,7 @@ const present = (v) => v !== undefined && v !== null;
  * @returns {{session_id?: string, semantic_session_id?: string}}
  */
 function mirrorSessionAttribution() {
-  return sessionAttribution(SO_PROJECT_DIR);
+  return sessionAttribution(getProjectDir());
 }
 
 /**

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

@@ -218,15 +218,27 @@ export function extractNarrative(stateMdContents) {
  * REFERENCE (byte-identical downstream), and `mask` passes non-strings through —
  * masking must never be the reason a mirror run dies.
  *
+ * Takes the ALREADY-BUILT masker (rather than building its own) so
+ * `runNarrativeMirror` can build it exactly ONCE per run and reuse it for both
+ * the actual masking below AND the `orchestrator.secret_masker.applied`
+ * telemetry (#1028) — the masker's `needleCount` is measured once, not
+ * potentially twice with process.env read between the two reads.
+ *
  * @param {{ waveHistory: string, deviations: string, whatNotToRetry: string, missionStatus: object[]|null }} narrative
- * @returns {{ waveHistory: string, deviations: string, whatNotToRetry: string, missionStatus: object[]|null }}
+ * @param {{ mask: (text: string) => string, needleCount: number }} masker
+ * @returns {{ narrative: { waveHistory: string, deviations: string, whatNotToRetry: string, missionStatus: object[]|null }, hits: number }}
  */
-function maskNarrative(narrative) {
-  const { mask, needleCount } = createSecretValueMasker(process.env);
-  if (needleCount === 0) return narrative;
+function maskNarrative(narrative, masker) {
+  const { mask, needleCount } = masker;
+  if (needleCount === 0) return { narrative, hits: 0 };
 
+  let hits = 0;
   const walk = (value) => {
-    if (typeof value === 'string') return mask(value);
+    if (typeof value === 'string') {
+      const masked = mask(value);
+      if (masked !== value) hits++;
+      return masked;
+    }
     if (Array.isArray(value)) return value.map(walk);
     if (value && typeof value === 'object') {
       const out = {};
@@ -236,7 +248,7 @@ function maskNarrative(narrative) {
     return value;
   };
 
-  return walk(narrative);
+  return { narrative: walk(narrative), hits };
 }
 
 // ── Pure render ────────────────────────────────────────────────────────────────
@@ -404,6 +416,30 @@ function normalizeUpdated(content) {
  * between runs: run 1 (env set) → `skipped-noop`, run 2 (env absent) → `written`
  * with the raw value on disk.
  *
+ * WHY THERE IS NO `maskerWouldChange` RE-PROBE HERE (#1214). The two sibling
+ * sinks in `vault-mirror/process.mjs` (processLearning, processSession) guard
+ * all five of their `skipped-noop` returns with `maskerWouldChange(existing)`,
+ * because their five-field / date comparisons can report a match while the
+ * on-disk note still carries a raw needle. This sink compares the WHOLE
+ * document, which makes that residue unreachable: `matchesModuloRedaction`
+ * only fires when the EXISTING side carries a `[REDACTED]` marker, and every
+ * literal segment around such a marker must appear verbatim in the candidate —
+ * but the candidate comes through `maskNarrative` with the CURRENT masker, so
+ * it can never contain a value that masker would redact. A raw needle on disk
+ * therefore always lands in a literal segment that fails to match, and the run
+ * writes. Measured 2026-09-04 at HEAD cd785003 in both directions (no marker on
+ * disk; marker already on disk plus a second needle entering the env): both
+ * returned `written` with the raw value gone. The two tests named `(#1214)` in
+ * tests/lib/vault-status/narrative-mirror.test.mjs pin that invariant — an
+ * argument-order slip on the call below makes both return `skipped-noop` and
+ * republish the raw value, which is how they were verified to bite.
+ *
+ * NAMED CEILING: the invariant rests on `maskNarrative` walking EVERY string
+ * that reaches the render. `repo` is fed to `renderNarrative` outside that walk
+ * (it is a directory basename, not STATE.md content), so a future rendered
+ * field added outside the walk would reopen this. Revisit trigger: any new
+ * `renderNarrative` input that does not pass through `maskNarrative`.
+ *
  * `matchesModuloRedaction` is IMPORTED from `../vault-mirror/process.mjs`, not
  * re-derived here: `secret-masker.mjs`'s header states this compensation as a
  * contract binding on every consumer that diffs a written artifact against a fresh
@@ -664,6 +700,56 @@ async function emitNarrativeEvent({ repoRoot, action, path: outputPath, chars, e
   }
 }
 
+/**
+ * Emit this channel's `orchestrator.secret_masker.applied` record (#1028
+ * residue 2). Until now the narrative mirror was the ONLY masker channel of
+ * the three (`vault-mirror`, `narrative-mirror`, `export-hw-learnings`) that
+ * never emitted this event — `maskNarrative` has masked unconditionally since
+ * #1025, but nothing told the ledger. A census grepping event NAMES for
+ * `narrative` therefore read as "this channel masks nothing", which was never
+ * true; it just never SAID so.
+ *
+ * Emitted UNCONDITIONALLY once per `mirrorNarrative` run whenever a `repoRoot`
+ * was resolvable — including every skip outcome, not only `written` — so
+ * `needle_count: 0` is a REAL measured "the env carries no secret-shaped
+ * value" rather than a stand-in for "the masker never ran" (same
+ * force-build-don't-default posture as `getMaskerStats()` in
+ * `scripts/lib/vault-mirror/process.mjs`). `records` is the literal `1`: one
+ * `mirrorNarrative` run always masks (or attempts to mask) exactly one
+ * STATE.md, unlike the CLI channels that fan out over many JSONL lines.
+ *
+ * Same field set as the `vault-mirror` channel's own masker emit
+ * (`channel`, `needle_count`, `records`, `hits`, `dry_run`), PLUS
+ * `session_id`/`semantic_session_id` via `sessionAttribution` — matching this
+ * module's own `emitNarrativeEvent` above rather than the CLI's 2-arg
+ * `emitEvent` call, because `mirrorNarrative` (unlike the CLI) already always
+ * carries a `repoRoot` to attribute against.
+ *
+ * Best-effort: never throws, never alters the mirror result.
+ *
+ * @param {{ repoRoot?: string, needleCount: number, hits: number, dryRun: boolean }} opts
+ * @returns {Promise<void>}
+ */
+async function emitMaskerEvent({ repoRoot, needleCount, hits, dryRun }) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return;
+  try {
+    await emitEvent(
+      'orchestrator.secret_masker.applied',
+      {
+        channel: 'narrative-mirror',
+        needle_count: needleCount,
+        records: 1,
+        hits,
+        dry_run: dryRun,
+        ...sessionAttribution(repoRoot),
+      },
+      { repoRoot },
+    );
+  } catch {
+    /* Best-effort telemetry — see emitNarrativeEvent above for why. */
+  }
+}
+
 // ── Convenience orchestration ────────────────────────────────────────────────────
 
 /**
@@ -723,42 +809,62 @@ export async function mirrorNarrative(opts) {
     chars: outcome.chars,
   });
 
+  // #1028 residue 2: the masker-telemetry sibling of the narrative event
+  // above, on every non-throwing outcome (including skips) — see
+  // emitMaskerEvent for why this fires unconditionally.
+  await emitMaskerEvent({
+    repoRoot: opts?.repoRoot,
+    needleCount: outcome.needleCount,
+    hits: outcome.hits,
+    dryRun: outcome.dryRun,
+  });
+
   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
+ * Split out so that the two emit sites in `mirrorNarrative` (the narrative
+ * event AND, since #1028, the masker event) each cover EVERY outcome from
+ * ONE call: 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 }>}
+ * @returns {Promise<{ result: { action: string, path?: string }, chars?: number, needleCount: number, hits: number, dryRun: boolean }>}
  */
 async function runNarrativeMirror(opts) {
   const { repoRoot, repo, now = new Date(), dryRun = false, fs: injectedFs, hostPaths } = opts;
 
   if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
-    return { result: { action: 'skipped-vault-disabled' } };
+    return { result: { action: 'skipped-vault-disabled' }, needleCount: 0, hits: 0, dryRun };
   }
 
+  // #1028: the masker is built ONCE per run, right here — before every
+  // remaining early-return below — so `mirrorNarrative`'s
+  // `orchestrator.secret_masker.applied` emit always carries a REAL measured
+  // `needle_count` on every outcome (including a skip), rather than a
+  // defaulted 0 that would be indistinguishable from "the masker never ran".
+  // Same "force-build, never default" posture as `getMaskerStats()` in
+  // `scripts/lib/vault-mirror/process.mjs`.
+  const masker = createSecretValueMasker(process.env);
+
   // Read Session Config (CLAUDE.md / AGENTS.md) and resolve vault settings.
   let config;
   try {
     const configText = await readConfigFile(repoRoot);
     config = parseSessionConfig(configText, { hostPaths });
   } catch {
-    return { result: { action: 'skipped-vault-disabled' } };
+    return { result: { action: 'skipped-vault-disabled' }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
 
   const vaultIntegration = config?.['vault-integration'];
   if (!vaultIntegration || vaultIntegration.enabled !== true) {
-    return { result: { action: 'skipped-vault-disabled' } };
+    return { result: { action: 'skipped-vault-disabled' }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
 
   // Defense-in-depth: when the caller omits (or passes an empty) `repo`, derive
@@ -775,7 +881,7 @@ async function runNarrativeMirror(opts) {
 
   const rawVaultDir = vaultIntegration['vault-dir'];
   if (!rawVaultDir || typeof rawVaultDir !== 'string') {
-    return { result: { action: 'skipped-vault-disabled' } };
+    return { result: { action: 'skipped-vault-disabled' }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
 
   const vaultDir = path.resolve(expandTilde(rawVaultDir));
@@ -799,7 +905,7 @@ async function runNarrativeMirror(opts) {
     canonicalizeRoot: true,
   });
   if (!inside.ok) {
-    return { result: { action: 'skipped-invalid-path', path: outputPath } };
+    return { result: { action: 'skipped-invalid-path', path: outputPath }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
 
   // Read STATE.md (best-effort; absent STATE.md → nothing to mirror).
@@ -808,13 +914,13 @@ async function runNarrativeMirror(opts) {
   try {
     stateContents = await readFile(stateMdPath, 'utf8');
   } catch {
-    return { result: { action: 'skipped-no-statemd', path: outputPath } };
+    return { result: { action: 'skipped-no-statemd', path: outputPath }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
 
   // #1025: the ONE masking site for the narrative mirror — after the frontmatter
   // parse (so `[REDACTED]` can never break it) and before the render, the
   // idempotency comparison and the write. See maskNarrative above.
-  const narrative = maskNarrative(extractNarrative(stateContents));
+  const { narrative, hits } = maskNarrative(extractNarrative(stateContents), masker);
   const content = renderNarrative({ repo: repoName, narrative, now });
 
   // `chars` measures the document THIS call rendered — so it is present on
@@ -823,5 +929,8 @@ async function runNarrativeMirror(opts) {
   return {
     result: writeNarrative({ outputPath, content, dryRun, fs: injectedFs }),
     chars: content.length,
+    needleCount: masker.needleCount,
+    hits,
+    dryRun,
   };
 }