session-orchestrator 3.19.0 → 3.21.0

package/scripts/lib/validate/frontmatter-block.mjs

@@ -0,0 +1,61 @@
+// frontmatter-block.mjs — Extract the leading `---`-fenced YAML block from a Markdown file.
+//
+// SHARED: THE EXTRACTION. NOT SHARED: THE RULES.
+//
+// This module owns exactly one thing — finding the frontmatter block's byte range and
+// handing back its text. It deliberately owns NOTHING about what a valid frontmatter
+// contains. Do not grow it into a validator, and do not "unify" the callers' rules
+// against it: the three frontmatter checkers in this directory disagree on purpose.
+//
+//   * check-agents.mjs   BANS  `description: >` — the agent loader cannot read a folded
+//                              block scalar, so the form is a live defect for agents/*.md.
+//   * check-skills.mjs   ALLOWS `description: >` — for SKILL.md the sign is REVERSED: the
+//                              folded scalar is the only form that makes the `: `
+//                              collision inside an unquoted description structurally
+//                              impossible. Measured 2026-08-15: 23 of 46 SKILL.md files
+//                              use it, and porting the agent ban here would red 35 of 46.
+//   * check-commands.mjs has its own, narrower field contract again (`argument-hint`).
+//
+// Those divergences are the product requirement, not drift. What WAS drift is this
+// function: it stood verbatim in check-skills.mjs and check-commands.mjs, so the next
+// change to the block format (a BOM, a new delimiter tolerance) would have been made in
+// one copy and one gate would have started accepting what the other rejects — with no
+// test able to see it, because each gate tested its own copy.
+//
+// BEHAVIOUR IS PINNED, NOT ASPIRATIONAL. tests/lib/validate/frontmatter-block.test.mjs
+// documents what the body does today, including the two sharp edges below. Both are
+// intentional records of the status quo, NOT endorsements — changing either is a
+// behaviour change under two gates at once and needs its own task, not a drive-by edit.
+//
+//   1. CRLF input is handled: the split is `/\r?\n/`, so a CRLF file's first line
+//      compares equal to '---' and the returned yamlText is LF-normalised.
+//   2. A line that is exactly `---` INSIDE the block (e.g. an unindented `---` inside a
+//      multi-line string) terminates the block early. Only a column-0, whitespace-free
+//      `---` does this; an indented `  ---` is ordinary content.
+
+/**
+ * Extract the YAML frontmatter block delimited by the leading `---` fence.
+ *
+ * The opening fence must be the very first line of the file. The closing fence is the
+ * first subsequent line equal to `---`. Line endings may be LF or CRLF; the returned
+ * text is always LF-joined.
+ *
+ * @param {string} content - full file text
+ * @returns {{ ok: true, yamlText: string } | { ok: false, diagnostic: string }}
+ *   On success, `yamlText` is the block's inner text with no fences (empty string for an
+ *   empty block). On failure, `diagnostic` is a caller-printable reason and there is no
+ *   `yamlText` — callers must not fall through to a parse.
+ */
+export function extractInitialFrontmatter(content) {
+  const lines = content.split(/\r?\n/);
+  if (lines[0] !== '---') {
+    return { ok: false, diagnostic: 'missing YAML frontmatter opening delimiter' };
+  }
+
+  const closingDelimiter = lines.indexOf('---', 1);
+  if (closingDelimiter === -1) {
+    return { ok: false, diagnostic: 'missing YAML frontmatter closing delimiter' };
+  }
+
+  return { ok: true, yamlText: lines.slice(1, closingDelimiter).join('\n') };
+}

package/scripts/lib/validate/tier-inference.mjs

@@ -25,7 +25,36 @@ const WRITE_TOOLS = new Set(['Edit', 'Write']);
 
 // Tools that are acceptable in the read-only tier (Bash is fine — fine-grained
 // Bash control lives in hooks/pre-bash-destructive-guard.mjs, NOT here).
-const READ_ONLY_TOOLS = new Set(['Read', 'Grep', 'Glob', 'Bash', 'Skill']);
+//
+// SendMessage / ListAgents are pure agent-to-coordinator communication surfaces
+// with no filesystem write path, so they do not lift an agent out of read-only
+// (#1049, PRD § 2 A5). Without them here, every read-only agent that opts into
+// SendMessage silently infers `repo-write` and trips validateTierConsistency.
+const READ_ONLY_TOOLS = new Set([
+  'Read',
+  'Grep',
+  'Glob',
+  'Bash',
+  'Skill',
+  'SendMessage',
+  'ListAgents',
+]);
+
+/**
+ * Normalise one raw frontmatter tool entry to its lookup key.
+ *
+ * Single source of truth for the "Skill(...)" → "Skill" collapse: both
+ * inferTierFromTools and validateTierConsistency's detail text must agree on
+ * what a tool entry IS, or the error message names offenders the inference
+ * never objected to.
+ *
+ * @param {unknown} t - raw entry from the frontmatter tools array
+ * @returns {string} lookup key
+ */
+function normaliseTool(t) {
+  if (typeof t !== 'string') return String(t);
+  return t.startsWith('Skill(') ? 'Skill' : t.trim();
+}
 
 /**
  * Infer the sandbox tier from a parsed tools array.
@@ -47,10 +76,7 @@ export function inferTierFromTools(toolsArray) {
   }
 
   // Normalise "Skill(...)" → "Skill"
-  const normalised = toolsArray.map((t) => {
-    if (typeof t !== 'string') return String(t);
-    return t.startsWith('Skill(') ? 'Skill' : t.trim();
-  });
+  const normalised = toolsArray.map(normaliseTool);
 
   // Any write tool → repo-write
   for (const t of normalised) {
@@ -86,10 +112,22 @@ export function validateTierConsistency({ declared, inferred, tools }) {
 
   // 2. Read-only agent must not have write tools.
   if (declared === 'read-only' && inferred !== 'read-only') {
-    const writeToolsPresent = Array.isArray(tools)
-      ? tools.filter((t) => WRITE_TOOLS.has(t))
+    // Name EVERY tool responsible for the verdict, not only the write tools.
+    // inferTierFromTools falls through to `repo-write` for any UNRECOGNISED
+    // tool too, and filtering the detail text on WRITE_TOOLS alone reported
+    // "tools suggest repo-write" with no culprit named in exactly that case
+    // (#1049). Normalised via the same helper the inference uses, so a
+    // "Skill(...)" entry is never listed as an offender.
+    const offenders = Array.isArray(tools)
+      ? [
+          ...new Set(
+            tools
+              .map(normaliseTool)
+              .filter((t) => WRITE_TOOLS.has(t) || !READ_ONLY_TOOLS.has(t)),
+          ),
+        ]
       : [];
-    const detail = writeToolsPresent.length > 0 ? ` (tools include: ${writeToolsPresent.join(', ')})` : '';
+    const detail = offenders.length > 0 ? ` (tools include: ${offenders.join(', ')})` : '';
     return {
       ok: false,
       error: `agent declares sandbox-tier "read-only" but tools suggest "${inferred}"${detail}`,

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

@@ -22,13 +22,31 @@
  *   - Redacts UNMAPPED owner-privacy leaks (CP1/CP6/CP10) to 'redacted-repo' +
  *     stderr WARN — identical to pre-#725 behaviour when no map is configured.
  *   - Falls back to 'unknown-repo' when slug derivation produces an empty string.
+ *
+ * Dependency direction (issue #734b): this module OWNS {@link deriveRepo}; it does
+ * NOT import from `./process.mjs`. Until #734b, `deriveRepo` lived in `process.mjs`
+ * while `process.mjs` imported `resolveRepoNamespace` from here — the repo's only
+ * import cycle (`namespace.mjs ↔ process.mjs`). The cycle was broken by moving the
+ * *identity* half down here (this module is the repo-identity resolver; `process.mjs`
+ * is the record-mirroring pipeline that CONSUMES an identity), and `process.mjs`
+ * re-exports `deriveRepo` from here so its public surface is unchanged.
+ *
+ * The direction is load-bearing beyond cycle-breaking: three modules
+ * (`vault-repo-backfill.mjs`, `vault-relocation-rules.mjs`, `scripts/vault-mirror.mjs`)
+ * import ONLY `resolveRepoNamespace` and previously dragged the entire `process.mjs`
+ * graph (secret-masker, render-learnings, render-sessions, session-schema/filters)
+ * in behind it. Keep this module leaf-ward: it may import `./utils.mjs`,
+ * `./pseudonym-map.mjs`, the leak-guard, host-paths and `../vcs-repo-spec.mjs`
+ * (itself a leaf — `node:child_process` only) — never the pipeline.
  */
 
-import { deriveRepo } from './process.mjs';
+import { basename } from 'node:path';
+
 import { subjectToSlug } from './utils.mjs';
 import { isOwnerLeakySegment } from '../../lib/validate/check-owner-leakage.mjs';
 import { loadPseudonymMap } from './pseudonym-map.mjs';
 import { loadHostPaths, resolveHostPath } from '../config/host-paths.mjs';
+import { isQueryFailure, resolvePreferredRemote } from '../vcs-repo-spec.mjs';
 
 // ── Lazy pseudonym-map path resolution (Epic #725 D5) ────────────────────────
 // The map path comes from env SO_NAMESPACE_MAP > owner.yaml paths.namespace-map-path
@@ -68,6 +86,133 @@ function currentMapPath() {
   return _lazyPath;
 }
 
+// ── Repo identity (issue #343; moved here from process.mjs for #734b) ────────
+
+let _cachedRepo = null;
+
+/** scp-like SSH remote: `git@host:org/name.git` (no `://`, an `@` before any `/`). */
+const SCP_LIKE_REMOTE_RE = /^[^@/\s]+@[^:/\s]+:(.+)$/;
+
+/** `scheme://[authority]/path` remote: https, ssh, git, file, … */
+const SCHEME_REMOTE_RE = /^([a-z][a-z0-9+.-]*):\/\/[^/]*\/(.+)$/i;
+
+/**
+ * Split a remote's path portion into meaningful segments: drop a trailing
+ * `.git` (with any trailing slashes), then discard empty and `.`/`..` segments.
+ *
+ * The `.`-dropping is the load-bearing part: `git clone <path>/.` records the
+ * origin VERBATIM as `/…/<repo>/.`, so the final segment of a filesystem remote
+ * is routinely a bare dot (measured golden record, 2026-08-19).
+ *
+ * @param {string} path
+ * @returns {string[]}
+ */
+function remotePathSegments(path) {
+  return path
+    .replace(/\.git\/*$/i, '')
+    .split('/')
+    .map((segment) => segment.trim())
+    .filter((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+
+/**
+ * Derive the RAW repo identifier from one git remote URL.
+ *
+ * - Hosted remote (scp-like SSH or a non-`file` scheme URL) → the last two path
+ *   segments, `org/name` — byte-identical to the pre-#1039 regex for every
+ *   hosted shape, so no existing vault namespace moves.
+ * - Filesystem remote (`git clone <path>`, `file://…`) → the repo DIRECTORY
+ *   name alone. A local clone has no owner segment, so `org/name` is not
+ *   derivable and inventing one from the parent directory would namespace vault
+ *   notes under an arbitrary path component.
+ *
+ * Returns `''` when nothing usable can be derived (caller falls back).
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+function repoIdentifierFromRemoteUrl(url) {
+  const value = String(url ?? '').trim();
+  if (value === '') return '';
+
+  const scp = SCP_LIKE_REMOTE_RE.exec(value);
+  const asUrl = scp === null ? SCHEME_REMOTE_RE.exec(value) : null;
+  const isFileUrl = asUrl !== null && asUrl[1].toLowerCase() === 'file';
+
+  if (scp !== null || (asUrl !== null && !isFileUrl)) {
+    const segments = remotePathSegments(scp !== null ? scp[1] : asUrl[2]);
+    if (segments.length === 0) return '';
+    return segments.length >= 2
+      ? `${segments[segments.length - 2]}/${segments[segments.length - 1]}`
+      : segments[segments.length - 1];
+  }
+
+  const segments = remotePathSegments(isFileUrl ? asUrl[2] : value);
+  return segments.length === 0 ? '' : segments[segments.length - 1];
+}
+
+/**
+ * Derive the canonical repo identifier for cross-repo vault aggregation (issue #343).
+ *
+ * Strategy (#1039): ask the shared remote-resolution core for the repo's
+ * PREFERRED remote — `resolvePreferredRemote` without a `vcs`, i.e. the
+ * `origin` → `gitlab` → `github` order, plus its sole-remote fallback — then
+ * derive `org/name` (hosted) or the repo directory name (filesystem clone) from
+ * that remote's URL. The pre-#1039 implementation read the hard-coded literal
+ * `git remote get-url origin`, which produced two live defects:
+ *
+ *   1. A repo whose remotes are named `gitlab`/`github` (no `origin`) silently
+ *      namespaced its vault notes under the CHECKOUT DIRECTORY name.
+ *   2. A `git clone <path>` origin (`/…/<repo>/.` — what the pre-push hook's
+ *      clone records) parsed to `<repo>/.`, whose slug is empty, so
+ *      {@link resolveRepoNamespace} returned `'unknown-repo'`. Measured
+ *      2026-08-19; it turned a namespace assertion red and blocked a push.
+ *
+ * Fallback: `path.basename(process.cwd())`, as before — but the two reasons for
+ * reaching it are no longer indistinguishable. A QUERY FAILURE (not a git repo,
+ * git not on PATH, git errored — {@link isQueryFailure}) emits a stderr WARN,
+ * because the identity under which vault notes are written was GUESSED. A real
+ * ABSENCE (a repo with no remotes) stays silent: that is a legitimate repo state
+ * and the directory name is the best available identity, not a degraded one.
+ * An `ok` resolution whose URL yields no usable identifier also falls back
+ * silently — the query succeeded and the answer was simply unusable.
+ *
+ * Cached per-process — repo identity does not change mid-run, and the cache also
+ * keeps the WARN to at most one line per process.
+ *
+ * NOTE — this is the RAW identifier and is NOT leak-guarded. Never write its
+ * output to the vault directly; route it through {@link resolveRepoNamespace}
+ * (which is what the `vaultName`-less path below does). The WARN above therefore
+ * deliberately does NOT print the derived value.
+ *
+ * Re-exported by `./process.mjs` for backwards compatibility — that was its home
+ * until the #734b cycle break, and the module-level cache means there must remain
+ * exactly ONE definition.
+ *
+ * @returns {string} e.g. 'Kanevry/session-orchestrator' or a bare directory name.
+ */
+export function deriveRepo() {
+  if (_cachedRepo !== null) return _cachedRepo;
+
+  const resolved = resolvePreferredRemote({});
+  if (resolved.ok) {
+    const identifier = repoIdentifierFromRemoteUrl(resolved.url);
+    if (identifier !== '') {
+      _cachedRepo = identifier;
+      return _cachedRepo;
+    }
+  } else if (isQueryFailure(resolved.reason)) {
+    process.stderr.write(
+      `WARN vault-mirror/namespace: could not query git remotes (${resolved.reason}); ` +
+        'falling back to the checkout directory name — vault notes may be namespaced ' +
+        'under the directory rather than the repo identity\n',
+    );
+  }
+
+  _cachedRepo = basename(process.cwd());
+  return _cachedRepo;
+}
+
 /**
  * Look up a stable pseudonym for this repo. Checks the sanitised segment first
  * (the canonical, stable key) then the raw base (covers a vaultName override

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

@@ -6,9 +6,9 @@
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
-import { join, resolve, basename } from 'node:path';
+import { join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { execFileSync } from 'node:child_process';
+import { createSecretValueMasker } from '../secret-masker.mjs';
 import { subjectToSlug, isValidSlug, uuidPrefix8, toDate, parseFrontmatter } from './utils.mjs';
 import { isRealSession } from '../session-schema/filters.mjs';
 import { resolveRepoNamespace } from './namespace.mjs';
@@ -99,6 +99,80 @@ function extractLearningCanonicalFields(noteContent) {
   return { status, expires, confidence, insight, source_session };
 }
 
+/**
+ * The marker every redaction sink in this repo splices in (`redact-spans.mjs`).
+ * Declared here as a literal rather than imported: `redactSpans` does not export
+ * it, and this module needs it as a SEARCH token, not as a replacement.
+ */
+const REDACTION_MARKER = '[REDACTED]';
+
+/**
+ * Does the on-disk `existingVal` match `renderedVal` once every `[REDACTED]`
+ * span in it is treated as a wildcard? (#1025)
+ *
+ * WHY THIS EXISTS. Masking is env-derived and the env is not part of the record,
+ * so the two sides of the idempotency comparison can be masked DIFFERENTLY: a
+ * note written while `FOO_TOKEN` was set carries `[REDACTED]`, and a later run
+ * with that var absent renders the RAW value. Plain equality then reports
+ * "content changed" and the mirror WRITES THE RAW SECRET — the repeated leak
+ * measured in #1025 Probe A. Treating an on-disk redaction as "some value stood
+ * here" makes that second run a `skipped-noop` again.
+ *
+ * DIRECTION IS DELIBERATE — the wildcard is only ever read off the ON-DISK side.
+ * An on-disk `[REDACTED]` is evidence that a mask ran; an on-disk raw value is
+ * evidence of nothing, so the reverse (candidate redacted, disk raw) stays a
+ * mismatch. See the COLD-START FREEZE note in `maskEntrySecrets` for the residual
+ * that this asymmetry leaves open on purpose.
+ *
+ * NAMED CEILING: the wildcard is exactly as wide as the marker spans — every
+ * literal segment AROUND them must still match byte for byte. A genuine content
+ * edit that happens to sit entirely inside a redacted span is therefore read as a
+ * no-op. That is a bounded over-approximation on a field whose masked half is by
+ * definition unpublishable; the alternative (persisting the needle set to disk)
+ * would put a secrets file on disk to protect against secrets, which is worse.
+ *
+ * THE MARKER IS NOT AUTHENTICATED — and it cannot be. `[REDACTED]` is an ordinary
+ * string that this repo's own prose uses freely (ADRs, rule files, learnings), so
+ * its presence is evidence a mask MAY have run, never proof one did. Two cheap
+ * narrowings bound what that costs:
+ *   - A value consisting of NOTHING BUT markers (`[REDACTED]`, or two in a row)
+ *     leaves zero literal anchors, compiling to a pattern that matches every
+ *     string — a field permanently blind to every future edit. Rejected outright:
+ *     with no anchor there is no evidence of what stood there, so the safe read is
+ *     "not a redaction of this candidate".
+ *   - A marker span stands for at least ONE character (`+?`, not `*?`). A masked
+ *     needle is >= `MIN_MASKABLE_LENGTH` (8) characters by construction, so this
+ *     never rejects a real redaction and does reject the empty-span reading.
+ *
+ * REJECTED ALTERNATIVE — gating the wildcard on `needleCount > 0`. It reads as the
+ * obvious authentication ("no needles this run, so an on-disk marker cannot be
+ * ours") and it destroys the fix, because the leaking run is EXACTLY the run with
+ * zero needles: #1025 Probe A reproduced `written` + raw value on the second run
+ * precisely because the env no longer carried the secret. Gating there would
+ * disable the wildcard in the only case it exists for. The needle count of the
+ * CURRENT run says nothing about the env of the run that wrote the file.
+ *
+ * SHARED BY TWO VAULT SINKS — do not inline a second copy. `writeNarrative` in
+ * `scripts/lib/vault-status/narrative-mirror.mjs` imports this for its own
+ * skip-noop decision; both write into the same tracked, pushed vault repo, so the
+ * contract in `secret-masker.mjs`'s header must hold identically in both. (That
+ * module is the natural long-term home for this predicate — see the note there.)
+ *
+ * @param {string} existingVal — field value parsed out of the note on disk
+ * @param {string} renderedVal — same field from the freshly rendered candidate
+ * @returns {boolean}
+ */
+export function matchesModuloRedaction(existingVal, renderedVal) {
+  if (typeof existingVal !== 'string' || typeof renderedVal !== 'string') return false;
+  if (!existingVal.includes(REDACTION_MARKER)) return false;
+  const segments = existingVal.split(REDACTION_MARKER);
+  // Degenerate-wildcard guard: no literal anchor survives, so the pattern would
+  // match anything and freeze the field forever. See the header above.
+  if (segments.every((segment) => segment === '')) return false;
+  const pattern = segments.map((segment) => RegExp.escape(segment)).join('[\\s\\S]+?');
+  return new RegExp(`^${pattern}$`).test(renderedVal);
+}
+
 /**
  * Return true when the existing vault note content and the freshly-rendered
  * candidate share identical canonical fields (i.e. no meaningful update needed).
@@ -123,8 +197,12 @@ function learningContentMatches(existingContent, renderedContent) {
   // For each field: if the existing value is absent (empty string), it cannot
   // signal a mismatch — it means the old note didn't track that field. Only
   // non-empty existing values are compared against the rendered candidate.
+  // #1025: a field whose only difference from the candidate is a `[REDACTED]`
+  // span counts as a match — see matchesModuloRedaction above.
   const fieldMatches = (existingVal, renderedVal) =>
-    existingVal === '' || existingVal === renderedVal;
+    existingVal === '' ||
+    existingVal === renderedVal ||
+    matchesModuloRedaction(existingVal, renderedVal);
   return (
     fieldMatches(existing.status, rendered.status) &&
     fieldMatches(existing.expires, rendered.expires) &&
@@ -136,35 +214,20 @@ function learningContentMatches(existingContent, renderedContent) {
 
 // ── repo derivation ───────────────────────────────────────────────────────────
 
-let _cachedRepo = null;
-
 /**
- * Derive the canonical repo identifier for cross-repo vault aggregation (issue #343).
+ * `deriveRepo` LIVES IN `./namespace.mjs` and is re-exported here (issue #734b).
  *
- * Strategy: parse `git remote get-url origin` and extract the org/name pair
- * (e.g. `git@github.com:Kanevry/session-orchestrator.git` → `Kanevry/session-orchestrator`).
- * Falls back to `path.basename(process.cwd())` when not in a git repo or origin
- * is unavailable. Cached per-process — repo identity does not change mid-run.
+ * Until #734b this module defined it while `namespace.mjs` imported it — and
+ * `namespace.mjs` was in turn imported here for `resolveRepoNamespace`, forming
+ * the repo's only import cycle. Moving the definition down to the leaf-ward
+ * identity module broke the cycle; this re-export keeps `process.mjs`'s public
+ * surface unchanged for the existing consumers that import it from here.
+ *
+ * Do NOT re-add a second definition: `deriveRepo` caches its result in a
+ * module-level variable, so a duplicate would produce two independent caches
+ * (and two `git remote get-url origin` spawns).
  */
-export function deriveRepo() {
-  if (_cachedRepo !== null) return _cachedRepo;
-  try {
-    const url = execFileSync('git', ['remote', 'get-url', 'origin'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-    // Match git@host:org/name(.git)? OR https://host/org/name(.git)?
-    const sshMatch = url.match(/[:/]([^:/]+\/[^/]+?)(?:\.git)?$/);
-    if (sshMatch && sshMatch[1]) {
-      _cachedRepo = sshMatch[1];
-      return _cachedRepo;
-    }
-  } catch {
-    // git unavailable or no origin configured — fall through
-  }
-  _cachedRepo = basename(process.cwd());
-  return _cachedRepo;
-}
+export { deriveRepo } from './namespace.mjs';
 
 // ── Action output ─────────────────────────────────────────────────────────────
 
@@ -211,6 +274,173 @@ export function emitAction({ action, path, kind, id, vaultDir, meta }) {
   process.stdout.write(JSON.stringify(payload) + '\n');
 }
 
+// ── Secret masking (#974) — THE choke-point ───────────────────────────────────
+
+/**
+ * Lazily-built, process-wide masker. `createSecretValueMasker` scans the whole
+ * env and compiles one RegExp per needle, so it is built ONCE (on the first
+ * record) and reused for every record afterwards — never per entry.
+ *
+ * Lazy rather than module-load-eager so that importing this module for
+ * `deriveRepo`/`emitAction` alone costs nothing, and so the env is read at the
+ * moment the mirror actually runs.
+ *
+ * @type {{ mask: (text: string) => string, needleCount: number } | null}
+ */
+let _secretMasker = null;
+
+/** Records handed to `maskEntrySecrets` this process. Counts only. */
+let _maskedRecords = 0;
+/** String values this process that masking actually CHANGED. Counts only. */
+let _maskHits = 0;
+
+/**
+ * Build (once) and return the process-wide masker.
+ * @returns {{ mask: (text: string) => string, needleCount: number }}
+ */
+function ensureMasker() {
+  if (_secretMasker === null) _secretMasker = createSecretValueMasker(process.env);
+  return _secretMasker;
+}
+
+/**
+ * Counts-only view of the masking that happened in this process (#1025).
+ *
+ * Exists so the CLI can emit `orchestrator.secret_masker.applied` at the END of a
+ * channel run without reaching into a module-private singleton. It FORCE-BUILDS
+ * the masker rather than reporting 0 for an unbuilt one: at 0 processed records
+ * the lazy build never fires, and a `needle_count: 0` from that path would be
+ * indistinguishable from "this channel has no masking wired at all" — the exact
+ * ambiguity the event was added to remove.
+ *
+ * NEVER returns a needle, a prefix of one, or any masked text — only cardinals.
+ *
+ * @returns {{ needleCount: number, records: number, hits: number }}
+ */
+export function getMaskerStats() {
+  return { needleCount: ensureMasker().needleCount, records: _maskedRecords, hits: _maskHits };
+}
+
+/**
+ * Mask every env-derived secret VALUE occurring anywhere in a mirror record,
+ * BEFORE any of it becomes a filename, a stdout line, or vault Markdown.
+ *
+ * WHY THIS IS THE CHOKE-POINT — and why it is on the INPUT, not the output.
+ * Everything this mirror writes lands in a TRACKED, PUSHED artifact
+ * (`auto-commit.mjs` runs `git add` + `commit` in the vault repo), so a leak here
+ * is not deletable — it would need a history rewrite in a foreign repo that
+ * neither this repo's `.gitleaks.toml` nor `check-owner-leakage.mjs` guards.
+ *
+ * THIS IS NOT THE ONLY SUCH CHANNEL — an earlier revision of this comment claimed
+ * it was, and that was wrong. Measured 2026-08-15 against the vault at
+ * `83a868059` (`git -C <vault> ls-files`): 18 tracked `_session-narrative.md`
+ * files (written by `scripts/lib/vault-status/narrative-mirror.mjs`) and 1 tracked
+ * `01-projects/session-orchestrator/research/hardware-patterns.md` (written by
+ * `scripts/export-hw-learnings.mjs`) live in the same pushed repo. All three
+ * channels carry agent-authored free text and all three need hardening
+ * independently — the value masker was wired into `export-hw-learnings.mjs` in
+ * #1025 for exactly this reason. Read "the vault is a tracked sink" as the
+ * property that makes masking necessary HERE, never as a census of the sinks.
+ *
+ * The records carry agent-authored free text (`insight`, `evidence`, `notes`,
+ * `text`) that routinely quotes command lines and error output, which is exactly
+ * the class shape-regexes cannot catch: the VALUE is in the prose, with no
+ * `FOO_TOKEN=` key beside it.
+ *
+ * Masking the ENTRY rather than the rendered Markdown is deliberate, for four
+ * reasons — a post-render mask would be wrong on all four:
+ *   1. The FILENAME. `slug` / `session_id` derive from `subject` / `session_id`,
+ *      and the file path is itself committed. A post-render mask never touches
+ *      the path, so a secret in a subject would be published as a filename.
+ *   2. STDOUT. `emitAction` prints the derived `id` and `path`; masking the input
+ *      keeps the action stream clean too.
+ *   3. YAML VALIDITY. The renderers decide quoting with `yamlQuoteIfNeeded`
+ *      BEFORE emitting `title:`. Masking first lets that decision see the `[`
+ *      of the marker and quote the scalar; masking afterwards would inject a bare
+ *      `title: [REDACTED]` — a YAML flow sequence, which fails the vault-sync
+ *      frontmatter schema at the session-end hard gate.
+ *   4. IDEMPOTENCY. `learningContentMatches` compares the on-disk note against a
+ *      freshly rendered candidate. Masking the input keeps both sides masked, so
+ *      an already-mirrored record still resolves to `skipped-noop`; masking only
+ *      on write would make every affected note re-render (and re-commit) forever.
+ *
+ *      That symmetry holds only while the ENV is stable, and the env is not part
+ *      of the record — so idempotency here is env-DEPENDENT. Reproduced (#1025):
+ *      a run WITH the secret in env writes `[REDACTED]`; a second run WITHOUT it
+ *      renders the raw value, the two differ, and the note is `updated` — i.e.
+ *      the leak is written a second time, by the very run that was supposed to be
+ *      a no-op. `learningContentMatches` now treats an on-disk `[REDACTED]` span
+ *      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.
+ *
+ * FRONTMATTER AND BODY ARE TREATED IDENTICALLY. A credential is exactly as
+ * published in `title:` as it is under `## Insight` — both live in the same
+ * committed file — so there is no case for exempting the structured half. The
+ * schema risk that exemption would otherwise be arguing for is removed by
+ * reason 3 above rather than by leaving a field unmasked.
+ *
+ * Fail-soft by construction: with zero needles the entry is returned by
+ * reference (byte-identical downstream), and `mask` itself passes non-strings
+ * through — the masker must never be the reason a mirror run dies.
+ *
+ * @template T
+ * @param {T} entry — a normalized learning/session record (plain JSON shape)
+ * @returns {T} the same record with every string value masked
+ */
+function maskEntrySecrets(entry) {
+  const { mask, needleCount } = ensureMasker();
+  // Counted BEFORE the fast path: "records the choke-point saw" must not depend
+  // on whether the env happened to carry a needle.
+  _maskedRecords++;
+  if (needleCount === 0) return entry;
+  const walk = (value) => {
+    if (typeof value === 'string') {
+      const masked = mask(value);
+      if (masked !== value) _maskHits++;
+      return masked;
+    }
+    if (Array.isArray(value)) return value.map(walk);
+    if (value && typeof value === 'object') {
+      const out = {};
+      for (const [k, v] of Object.entries(value)) out[k] = walk(v);
+      return out;
+    }
+    return value;
+  };
+  return walk(entry);
+}
+
 // ── Core processing ───────────────────────────────────────────────────────────
 
 export async function processLearning(rawEntry, _lineNum, ctx) {
@@ -225,7 +455,9 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   // #635: map producer alias fields (summary/detail, description/rationale,
   // title/body, name, narrative, content) onto the canonical v1 shape BEFORE
   // schema detection and slug/id derivation. Canonical entries pass through.
-  const entry = normalizeLearningEntry(rawEntry);
+  // #974: the ONE masking site for learnings — before slug/filename derivation,
+  // before the render, before any write. See maskEntrySecrets above.
+  const entry = maskEntrySecrets(normalizeLearningEntry(rawEntry));
   const schema = detectLearningSchema(entry);
   const entryId = entry.id;
 
@@ -438,7 +670,8 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   // #635: map producer alias fields (ended_at, mode, total_waves/waves_completed
   // without a `waves` field) onto the canonical shapes BEFORE schema detection.
   // Canonical v1/v2/v3 entries pass through untouched.
-  const entry = normalizeSessionEntry(rawEntry);
+  // #974: the ONE masking site for sessions — same contract as processLearning.
+  const entry = maskEntrySecrets(normalizeSessionEntry(rawEntry));
   const { session_id: rawSessionId } = entry;
   const schema = detectSessionSchema(entry);
   const generator =