session-orchestrator 3.23.0 → 4.0.0

package/scripts/lib/validate/markdown-fences.mjs

@@ -0,0 +1,196 @@
+/**
+ * markdown-fences.mjs — the ONE fenced-code-block tracker shared by every
+ * Markdown-scanning validator/extractor in this repo (#1181).
+ *
+ * ## Why one module
+ *
+ * The same regex pair + open/close comparison had drifted into four separate
+ * copies — `check-doc-cli-commands.mjs`, `check-skill-script-paths.mjs`,
+ * `check-vcs-repo-flag.mjs` and `auq/parse.mjs` — each tracking fence depth
+ * and language independently. A drifted copy is a silent one: nothing fails
+ * when copy #3 diverges from copy #1, because each copy only has to agree
+ * with itself.
+ *
+ * ## The rule this module encodes
+ *
+ * A fence opens on a line beginning with 3+ backticks or 3+ tildes, carrying
+ * an optional info string (most commonly a language tag). It closes on a
+ * line whose marker CHARACTER matches, whose LENGTH is at least the
+ * opener's, and whose info string is empty — CommonMark reserves the info
+ * string for the OPENING fence only, so a fence-shaped line that still
+ * carries one is fence CONTENT (most often a nested fence one level in), not
+ * a closer.
+ *
+ * ## The one real divergence between the four original copies, preserved as a parameter
+ *
+ * Three of the four copies anchor the fence-line regex only at the START of
+ * the line — trailing text after the info string is simply not captured,
+ * never rejected. `auq/parse.mjs`'s copy anchors at BOTH ends: a line
+ * carrying anything past the info string besides trailing whitespace is not
+ * recognised as a fence line at all. This is `{ wholeLine: true }` below —
+ * a real behavioural difference, not stylistic, so it stays a caller-chosen
+ * option rather than being silently resolved one way. Every other
+ * consumer-specific behaviour (the shell-language predicate, blockquote
+ * stripping, unbalanced-fence reporting) likewise stays at the call site —
+ * this module owns only the fence-line grammar itself.
+ */
+
+/** Fence languages whose body is shell. Both `check-doc-cli-commands.mjs` and
+ * `check-vcs-repo-flag.mjs` filtered on this identical literal set before
+ * extraction; centralised here rather than kept as two copies of the same
+ * five strings. */
+export const SHELL_LANGS = Object.freeze(new Set(['bash', 'sh', 'shell', 'console', 'zsh']));
+
+/** Start-anchored: matches CommonMark, tolerates trailing info-string text. */
+const FENCE_LINE_START_RE = /^\s*(`{3,}|~{3,})\s*([A-Za-z0-9_+-]*)/;
+
+/** Whole-line-anchored: nothing but whitespace may follow the info string. */
+const FENCE_LINE_WHOLE_RE = /^[ \t]*(`{3,}|~{3,})[ \t]*([^\s`~]*)[ \t]*$/u;
+
+/**
+ * Match a candidate fence-marker line.
+ *
+ * @param {string} line
+ * @param {{ wholeLine?: boolean }} [options] `wholeLine: true` requires the
+ *   ENTIRE line (after the marker) to be nothing but the info string plus
+ *   trailing whitespace — the stricter reading `auq/parse.mjs` needs.
+ *   Default `false` only anchors the START of the line, matching
+ *   CommonMark and the three `check-*.mjs` validators.
+ * @returns {{ marker: string, length: number, info: string } | null}
+ */
+export function matchFenceLine(line, { wholeLine = false } = {}) {
+  const match = (wholeLine ? FENCE_LINE_WHOLE_RE : FENCE_LINE_START_RE).exec(line);
+  if (!match) return null;
+  return { marker: match[1][0], length: match[1].length, info: match[2] ?? '' };
+}
+
+/**
+ * Does `candidate` close the fence opened by `open`? Same marker character,
+ * at least as long, and carrying no info string of its own.
+ *
+ * @param {{ marker: string, length: number }} open
+ * @param {{ marker: string, length: number, info: string }} candidate
+ * @returns {boolean}
+ */
+export function closesFence(open, candidate) {
+  return candidate.marker === open.marker && candidate.length >= open.length && candidate.info === '';
+}
+
+/**
+ * Normalise a fence's info string into a comparable language tag. Every
+ * caller that classified a fence by language did `.toLowerCase()` (never
+ * `.trim()`, since the capturing regex cannot include leading/trailing
+ * whitespace in the first place) before comparing against a language set —
+ * this makes that normalisation a single, explicit step instead of an
+ * implicit property of the extraction regex.
+ *
+ * @param {string} info
+ * @returns {string}
+ */
+export function normalizeLang(info) {
+  return String(info ?? '').trim().toLowerCase();
+}
+
+/**
+ * Strip a leading blockquote `>` chain so a quoted fence (`> \`\`\``) is
+ * still recognised as a fence line. Only `check-skill-script-paths.mjs`
+ * needs this — a fence inside a blockquote is still a fence there, but the
+ * other callers never scan quoted content.
+ *
+ * @param {string} line
+ * @returns {string}
+ */
+export function stripBlockquote(line) {
+  return line.replace(/^(?:\s*>)+\s?/, '');
+}
+
+/**
+ * Walk `text` line by line, tracking fence state, and call `onLine` for
+ * every CONTENT line. Fence-marker lines themselves (the opener and the
+ * closer) are consumed by the tracker and never handed to the callback —
+ * all four original copies treated marker lines as structural, never as
+ * scannable content. A fence-shaped line that neither opens nor validly
+ * closes (a nested fence one level in) IS still content and reaches the
+ * callback, exactly as in the original copies.
+ *
+ * @param {string} text
+ * @param {(line: string, state: { lineNumber: number, inFence: boolean, lang: string | null }) => void} onLine
+ * @param {{ wholeLine?: boolean, stripBlockquotes?: boolean }} [options]
+ * @returns {{ unbalancedFenceLine: number | null }} the 1-based line of a
+ *   fence that opened and never closed by EOF, or `null` if every fence
+ *   this walk saw was balanced.
+ */
+export function forEachLine(text, onLine, options = {}) {
+  const { wholeLine = false, stripBlockquotes = false } = options;
+  const lines = text.split('\n');
+  /** @type {{ marker: string, length: number, openLine: number } | null} */
+  let fence = null;
+  let lang = null;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index];
+    const probe = stripBlockquotes ? stripBlockquote(raw) : raw;
+    const candidate = matchFenceLine(probe, { wholeLine });
+    if (candidate) {
+      if (fence === null) {
+        fence = { marker: candidate.marker, length: candidate.length, openLine: index + 1 };
+        lang = normalizeLang(candidate.info);
+        continue;
+      }
+      if (closesFence(fence, candidate)) {
+        fence = null;
+        lang = null;
+        continue;
+      }
+      // Otherwise it is fence content (a nested fence inside a wider one) — falls through.
+    }
+    onLine(raw, { lineNumber: index + 1, inFence: fence !== null, lang });
+  }
+
+  return { unbalancedFenceLine: fence ? fence.openLine : null };
+}
+
+/**
+ * Extract fence BLOCKS (an open/close pair plus its body) rather than a
+ * per-line walk — the shape `auq/parse.mjs` needs, since it iterates fences
+ * as units, not lines.
+ *
+ * An unbalanced fence (opens, never closes) contributes NO block, mirroring
+ * the original `fencesOf()` contract: it silently drops the dangling opener
+ * rather than reporting it. Unlike `check-skill-script-paths.mjs`, whose
+ * unterminated fence is a doc DEFECT worth its own finding, `auq/parse.mjs`
+ * scans AskUserQuestion blocks in production code and prose, where an
+ * unterminated fence was never treated as a reportable condition in its own
+ * right — only as "no block found here".
+ *
+ * @param {string} text
+ * @param {{ wholeLine?: boolean }} [options]
+ * @returns {Array<{ openLine: number, closeLine: number, lang: string, bodyLines: string[], bodyStartLine: number }>}
+ */
+export function scanFenceBlocks(text, options = {}) {
+  const { wholeLine = false } = options;
+  const lines = text.split('\n');
+  /** @type {Array<{ openLine: number, closeLine: number, lang: string, bodyLines: string[], bodyStartLine: number }>} */
+  const blocks = [];
+  /** @type {{ marker: string, length: number, info: string, startIdx: number } | null} */
+  let open = null;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const candidate = matchFenceLine(lines[index], { wholeLine });
+    if (!candidate) continue;
+    if (open === null) {
+      open = { ...candidate, startIdx: index };
+      continue;
+    }
+    if (!closesFence(open, candidate)) continue; // fence content (nested), not a close
+    blocks.push({
+      openLine: open.startIdx + 1,
+      closeLine: index + 1,
+      lang: open.info,
+      bodyLines: lines.slice(open.startIdx + 1, index),
+      bodyStartLine: open.startIdx + 2,
+    });
+    open = null;
+  }
+  return blocks;
+}

package/scripts/lib/vault-backfill/template.mjs

@@ -1,17 +1,71 @@
 /**
  * template.mjs — Canonical .vault.yaml template renderer for vault-backfill.
  *
- * Reads the template once from projects-baseline; subsequent calls use cache.
+ * Reads the template once from a projects-baseline checkout; subsequent calls
+ * use the cache. The checkout is optional — see docs/baseline.md.
  * Part of scripts/vault-backfill.mjs (Issue #241).
  */
 
 import { readFileSync, existsSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveHostPath } from '../config/host-paths.mjs';
 
-export const TEMPLATE_PATH = process.env.PROJECTS_BASELINE_DIR
-  ? resolve(process.env.PROJECTS_BASELINE_DIR, 'templates/shared/.vault.yaml.template')
-  : resolve(homedir(), 'Projects/projects-baseline/templates/shared/.vault.yaml.template');
+/** Path of the template RELATIVE to a projects-baseline checkout root. */
+const TEMPLATE_REL_PATH = 'templates/shared/.vault.yaml.template';
+
+/** This file lives at `<repoRoot>/scripts/lib/vault-backfill/`. */
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+/**
+ * Candidate projects-baseline checkout roots. The baseline is optional and
+ * private (`docs/baseline.md`), so no host-specific directory name may be
+ * committed here.
+ *
+ * Two tiers, and the split is load-bearing:
+ *
+ *   EXPLICIT — `PROJECTS_BASELINE_DIR`, else `SO_BASELINE_PATH` / `owner.yaml`
+ *   `paths.baseline-path`. When the operator has SAID where the baseline is,
+ *   that answer is used ALONE. Probing past a wrong explicit value would resolve
+ *   a DIFFERENT baseline than the one named and report success — silently using
+ *   a corpus nobody asked for is worse than the abort, and it would hide the
+ *   typo forever.
+ *
+ *   CONVENTION — the sibling checkout `scripts/sync-vault-schema.mjs` already
+ *   uses, then the legacy `~/Projects` default this module shipped with. These
+ *   are guesses, so probing among them is exactly right.
+ *
+ * @returns {string[]} never empty
+ */
+function baselineCandidates() {
+  const envDir = (process.env.PROJECTS_BASELINE_DIR || '').trim();
+  if (envDir) return [envDir];
+  const hostDir = resolveHostPath('baseline-path', null);
+  if (typeof hostDir === 'string' && hostDir.trim() !== '') return [hostDir.trim()];
+  return [
+    resolve(REPO_ROOT, '..', 'projects-baseline'),
+    resolve(homedir(), 'Projects/projects-baseline'),
+  ];
+}
+
+/**
+ * Resolved absolute path of the canonical template.
+ *
+ * Import-time resolution is retained deliberately: the export is a plain string
+ * that `scripts/vault-backfill.mjs` and the tests both read directly. Ceiling:
+ * at most two `existsSync` calls at import. When no candidate exists the FIRST
+ * candidate is exported anyway, so `loadTemplate`'s die message names the path
+ * the operator most likely meant rather than `undefined`.
+ */
+export const TEMPLATE_PATH = (() => {
+  const candidates = baselineCandidates();
+  for (const base of candidates) {
+    const candidate = resolve(base, TEMPLATE_REL_PATH);
+    if (existsSync(candidate)) return candidate;
+  }
+  return resolve(candidates[0], TEMPLATE_REL_PATH);
+})();
 
 const TODAY = new Date().toISOString().slice(0, 10);
 
@@ -27,7 +81,10 @@ export function loadTemplate(dieFn) {
     dieFn(
       2,
       `canonical template not found at ${TEMPLATE_PATH} — ` +
-        `set PROJECTS_BASELINE_DIR env var or check projects-baseline checkout at $HOME/Projects/projects-baseline`,
+        `the projects-baseline checkout is optional and private (see docs/baseline.md). ` +
+        `Point at it with owner.yaml \`paths.baseline-path\` (host-local, never committed), ` +
+        `the SO_BASELINE_PATH env var, or PROJECTS_BASELINE_DIR; a sibling checkout at ` +
+        `../projects-baseline is picked up automatically.`,
     );
   }
 

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());
 }
 
 /**