session-orchestrator 3.16.0 → 3.19.0

package/scripts/lib/issue-close-strip-labels.mjs

@@ -14,6 +14,11 @@
  *   - Never throws — all errors are caught and returned as `{ stripped: [],
  *     error: string }` so callers can log and proceed with close unblocked.
  *   - Supports GitLab (`glab`) and GitHub (`gh`). VCS is a required param.
+ *   - Every `glab`/`gh` spawn is pinned to the resolved repo via `-R <spec>`
+ *     (#839) — see `scripts/lib/vcs-repo-spec.mjs` for why: a bare spawn
+ *     falls back to the ambient `GITLAB_HOST`/`GH_HOST`, which can silently
+ *     resolve to the wrong GitLab instance on a multi-host machine, turning
+ *     this whole module into a silent no-op.
  *
  * Usage (from session-end Phase 5 issue-close loop):
  *
@@ -28,6 +33,7 @@
  */
 
 import { execFileSync } from 'node:child_process';
+import { resolveRepoSpec } from './vcs-repo-spec.mjs';
 
 /** Regex that matches any `status:*` label name. */
 const STATUS_LABEL_RE = /^status:/;
@@ -57,15 +63,19 @@ function runCli(cmd, args) {
 /**
  * Fetch the label names currently applied to an issue.
  *
- * @param {{ issueId: number | string, vcs: 'gitlab' | 'github' }} opts
+ * @param {{ issueId: number | string, vcs: 'gitlab' | 'github', spec?: string }} opts
+ *   `spec` is the resolved `-R`/`--repo` host-pinning value (#839); omitted
+ *   (undefined) means no `-R` is appended — never emit `-R undefined`.
  * @returns {{ ok: boolean, labels: string[], stderr: string }}
  */
-function fetchLabels({ issueId, vcs }) {
+function fetchLabels({ issueId, vcs, spec }) {
   const id = String(issueId);
 
   if (vcs === 'github') {
     // `gh issue view <NUMBER> --json labels` returns { labels: [{name, ...}] }
-    const res = runCli('gh', ['issue', 'view', id, '--json', 'labels']);
+    const args = ['issue', 'view', id, '--json', 'labels'];
+    if (spec) args.push('-R', spec);
+    const res = runCli('gh', args);
     if (!res.ok) return { ok: false, labels: [], stderr: res.stderr };
     let parsed;
     try {
@@ -81,7 +91,9 @@ function fetchLabels({ issueId, vcs }) {
 
   // Default: gitlab via glab.
   // `glab issue view <IID> --output json` returns an issue object with a `labels` array.
-  const res = runCli('glab', ['issue', 'view', id, '--output', 'json']);
+  const args = ['issue', 'view', id, '--output', 'json'];
+  if (spec) args.push('-R', spec);
+  const res = runCli('glab', args);
   if (!res.ok) return { ok: false, labels: [], stderr: res.stderr };
   let parsed;
   try {
@@ -89,7 +101,7 @@ function fetchLabels({ issueId, vcs }) {
   } catch (e) {
     return { ok: false, labels: [], stderr: `JSON parse failed: ${e && e.message ? e.message : String(e)}` };
   }
-  // GitLab JSON shape: { labels: ["status:ready", "priority:high", ...] }
+  // GitLab JSON shape: { labels: ["status:ready", "priority::high", ...] }
   const labels = Array.isArray(parsed?.labels)
     ? parsed.labels.map((l) => (typeof l === 'string' ? l : String(l))).filter(Boolean)
     : [];
@@ -105,11 +117,22 @@ function fetchLabels({ issueId, vcs }) {
  *
  * @param {{
  *   issueId: number | string,
- *   vcs?: 'gitlab' | 'github'
+ *   vcs?: 'gitlab' | 'github',
+ *   repoRoot?: string,
+ *   resolveRepoSpecFn?: (opts: { repoRoot: string, vcs: 'gitlab' | 'github' }) => string | undefined
  * }} opts
+ *   `repoRoot` defaults to `process.cwd()`. `resolveRepoSpecFn` is the
+ *   injectable seam for the `-R`/`--repo` host-pinning resolution (#839) —
+ *   defaults to the real `resolveRepoSpec` (shells out to `git remote
+ *   get-url`); tests inject a stub instead of shelling out.
  * @returns {Promise<{ stripped: string[], error?: string }>}
  */
-export async function stripStatusLabels({ issueId, vcs = 'gitlab' } = {}) {
+export async function stripStatusLabels({
+  issueId,
+  vcs = 'gitlab',
+  repoRoot = process.cwd(),
+  resolveRepoSpecFn = resolveRepoSpec,
+} = {}) {
   try {
     const id = String(issueId ?? '').trim();
     if (!id || id === 'undefined' || id === 'null') {
@@ -118,8 +141,12 @@ export async function stripStatusLabels({ issueId, vcs = 'gitlab' } = {}) {
 
     const vcsResolved = vcs === 'github' ? 'github' : 'gitlab';
 
+    // Resolve the -R/--repo host-pinning spec ONCE, reused by both the fetch
+    // and the strip call below (#839). undefined ⇒ no -R is appended anywhere.
+    const spec = resolveRepoSpecFn({ repoRoot, vcs: vcsResolved });
+
     // Step 1: fetch current labels.
-    const { ok, labels, stderr } = fetchLabels({ issueId: id, vcs: vcsResolved });
+    const { ok, labels, stderr } = fetchLabels({ issueId: id, vcs: vcsResolved, spec });
     if (!ok) {
       return { stripped: [], error: `failed to fetch labels: ${stderr}` };
     }
@@ -139,11 +166,14 @@ export async function stripStatusLabels({ issueId, vcs = 'gitlab' } = {}) {
       for (const label of toStrip) {
         args.push('--remove-label', label);
       }
+      if (spec) args.push('-R', spec);
       stripRes = runCli('gh', args);
     } else {
       // `glab issue update <IID> --unlabel label1,label2,...`
       // glab accepts comma-separated list in a single --unlabel flag value.
-      stripRes = runCli('glab', ['issue', 'update', id, '--unlabel', toStrip.join(',')]);
+      const args = ['issue', 'update', id, '--unlabel', toStrip.join(',')];
+      if (spec) args.push('-R', spec);
+      stripRes = runCli('glab', args);
     }
 
     if (!stripRes.ok) {

package/scripts/lib/label-scope.mjs

@@ -0,0 +1,47 @@
+/**
+ * label-scope.mjs — scope-tolerant label comparison.
+ *
+ * The canonical priority-label spelling is the GitLab SCOPED form
+ * `priority::<level>`. Producers were migrated to it because the instance had
+ * drifted to 416 scoped / 249 unscoped / 7 bare labels, and a data migration
+ * that is not preceded by a producer migration is undone within a day.
+ *
+ * The DATA migration is a separate, later step, so for now both spellings
+ * coexist on real issues. Every consumer that MATCHES a label therefore
+ * compares through `normalizeLabel()`, which collapses the scope separator:
+ * `priority::high` and `priority:high` are the same label for matching
+ * purposes, while the emitted/default spelling stays canonical.
+ *
+ * Deliberately NOT applied to label WRITES — those always emit the canonical
+ * scoped form.
+ *
+ * Stdlib-free leaf module.
+ */
+
+/**
+ * Collapse a scoped label's double colon to a single colon and lowercase it,
+ * yielding a comparison key that is identical for `key::value` and `key:value`.
+ *
+ * @param {unknown} label
+ * @returns {string} normalized comparison key ('' for non-strings)
+ */
+export function normalizeLabel(label) {
+  if (typeof label !== 'string') return '';
+  return label.trim().toLowerCase().replace(/::/g, ':');
+}
+
+/**
+ * Build a Set of normalized comparison keys from a label list.
+ *
+ * @param {unknown} labels
+ * @returns {Set<string>}
+ */
+export function normalizedLabelSet(labels) {
+  const set = new Set();
+  if (!Array.isArray(labels)) return set;
+  for (const l of labels) {
+    const key = normalizeLabel(l);
+    if (key) set.add(key);
+  }
+  return set;
+}

package/scripts/lib/learnings/schema.mjs

@@ -83,8 +83,13 @@ export const LEARNING_TYPE_REGISTRY = Object.freeze({
   'fragile-file':                Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: true  }),
   'effective-sizing':            Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: false }),
   'recurring-issue':             Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: true  }),
-  'workflow-pattern':            Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: false }),
-  'proven-pattern':              Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: false }),
+  // workflow-pattern / proven-pattern: flipped ruleConvertible false->true
+  // (issue #900) — the real corpus census showed a large volume of live
+  // `workflow-pattern`/`proven-pattern` records (post type-alias-normalization,
+  // see LEARNING_TYPE_ALIASES below) that carried usable file_paths but were
+  // structurally unconvertible before this flip.
+  'workflow-pattern':            Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
+  'proven-pattern':              Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
   'anti-pattern':                Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
   'autopilot-effectiveness':     Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: false }),
   // autonomy-verdict (#683): repo/scope readiness synthesis from autopilot
@@ -106,6 +111,30 @@ export const LEARNING_TYPE_REGISTRY = Object.freeze({
   'stagnation-class-frequency':  Object.freeze({ ttlDays: 60, agentProposable: false, ruleConvertible: true  }),
 });
 
+/**
+ * Free-form producer-dialect type names -> their canonical
+ * {@link LEARNING_TYPE_REGISTRY} counterpart (issue #900). The real corpus
+ * accumulated learnings stamped with type names that were never registered
+ * (`gotcha`, `pattern`, ...) — these are semantically the SAME classes as
+ * two registered types, just written with a different literal. Applied by
+ * {@link normalizeDialects} on both the read funnel (`normalizeLearning`)
+ * and the write/migration funnel (`migrateLegacyLearning`), so every
+ * downstream consumer (TTL derivation, `CONVERT_TYPES` / `PROPOSAL_TYPES`
+ * membership, reconcile eligibility) sees one canonical type space —
+ * mirrors the existing `files` -> `file_paths` dialect-normalization
+ * pattern one level up (type name instead of field name).
+ *
+ * INVARIANT (guarded by a test): no alias KEY may collide with a
+ * `LEARNING_TYPE_REGISTRY` key — a collision would silently rewrite an
+ * already-canonical type into a different one.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const LEARNING_TYPE_ALIASES = Object.freeze({
+  gotcha: 'anti-pattern',
+  pattern: 'proven-pattern',
+});
+
 /**
  * Per-type TTL policy (in days) for `expires_at` derivation. Derived from
  * {@link LEARNING_TYPE_REGISTRY} — see parent module documentation for tier
@@ -275,7 +304,10 @@ const _warnedSessionIdConflict = new Set();
  * session_id/source_session conflict (see below); idempotent; never throws;
  * non-objects (and arrays) pass through unchanged. Does NOT mutate its input.
  *
- * Dialect rules (Epic #723 B2 — census 2026-07-02):
+ * Dialect rules (Epic #723 B2 — census 2026-07-02; type-alias rule added
+ * issue #900):
+ *   - `type`         → canonical type — resolved via {@link LEARNING_TYPE_ALIASES}
+ *                      (e.g. `gotcha` → `anti-pattern`, `pattern` → `proven-pattern`).
  *   - `files`        → `file_paths`  — verbatim value move; an empty array is
  *                      preserved as an empty `file_paths`; a canonical
  *                      `file_paths` already present wins (legacy `files` dropped).
@@ -310,6 +342,14 @@ export function normalizeDialects(entry, { reserializeTimestamps = true } = {})
 
   const out = { ...entry };
 
+  // type alias resolution (#900) — canonicalize free-form producer type names
+  // (e.g. `gotcha`, `pattern`) to their LEARNING_TYPE_REGISTRY counterpart so
+  // every downstream consumer (TTL derivation, CONVERT_TYPES / PROPOSAL_TYPES
+  // membership, reconcile eligibility) sees one canonical type space.
+  if (typeof out.type === 'string' && out.type in LEARNING_TYPE_ALIASES) {
+    out.type = LEARNING_TYPE_ALIASES[out.type];
+  }
+
   // files → file_paths (verbatim value move; canonical wins; empty array kept).
   if ('files' in out) {
     if (!('file_paths' in out)) {

package/scripts/lib/lock-reaper.mjs

@@ -70,7 +70,6 @@ import { readLock, isLockLive, isPidAliveOnHost, LOCK_PATH, DEFAULT_TTL_HOURS }
 import { emitEvent } from './events.mjs';
 
 const REAPED_ARCHIVE_SUBDIR = '.orchestrator/tmp/reaped-locks';
-const EVENTS_RELPATH = '.orchestrator/metrics/events.jsonl';
 const REAPED_EVENT = 'orchestrator.session.lock.reaped';
 const CURRENT_SESSION_RELPATH = '.orchestrator/current-session.json';
 
@@ -550,7 +549,7 @@ async function evaluateRepo(repoRoot, { nowMs, dryRun, currentSessionId, reapMod
         reap_mode: reapMode,
         current_session: currentSession,
       },
-      { filePath: path.join(repoRoot, EVENTS_RELPATH) },
+      { repoRoot },
     );
   } catch {
     // Observability is best-effort — the archive-move already succeeded.

package/scripts/lib/memory-proposals/schema.mjs

@@ -22,7 +22,11 @@
  *   schema_version   1
  *
  * Optional fields:
- *   proposed_by_agent string | undefined — identifier of the submitting agent
+ *   proposed_by_agent string | undefined  — identifier of the submitting agent
+ *   file_paths        string[] | undefined — repo-relative path(s) this
+ *     proposal applies to (issue #900 C). Omitted entirely when empty/absent
+ *     — never set to `[]`. Required, downstream, for a promoted learning to
+ *     ever become /reconcile-eligible (see `reconcile/eligibility.mjs`).
  */
 
 import { randomUUID } from 'node:crypto';
@@ -86,6 +90,9 @@ const EVIDENCE_MAX = 5000;
  * @param {number} opts.confidence     — [0, 1]
  * @param {string} opts.waveId         — e.g. 'W2'
  * @param {string} [opts.proposedByAgent] — optional agent identifier
+ * @param {string[]} [opts.filePaths]  — optional repo-relative path(s) this
+ *   proposal applies to (issue #900 C). Set on the record ONLY when a
+ *   non-empty array is supplied — mirrors the `proposedByAgent` pattern.
  * @returns {object} complete proposal record
  */
 export function createProposalRecord({
@@ -96,6 +103,7 @@ export function createProposalRecord({
   confidence,
   waveId,
   proposedByAgent,
+  filePaths,
 }) {
   const record = {
     id: randomUUID(),
@@ -113,6 +121,10 @@ export function createProposalRecord({
     record.proposed_by_agent = proposedByAgent;
   }
 
+  if (Array.isArray(filePaths) && filePaths.length > 0) {
+    record.file_paths = filePaths;
+  }
+
   return record;
 }
 
@@ -238,6 +250,29 @@ export function validateProposalRecord(record) {
     errors.push('proposed_by_agent must be a string when present');
   }
 
+  // file_paths (optional, but if present must be a non-empty array of
+  // non-empty, newline-free, glob-metacharacter-free strings) — issue #900 C,
+  // Q3-MED fix pass: a glob metacharacter (* ? [ ] { }) surviving this schema
+  // gate would later reach emitter.mjs::globsFromFilePaths verbatim for a
+  // top-level (dirname==='.') entry, effectively producing an always-on rule
+  // glob (e.g. `file_paths: ['**']`). `createProposalRecord` never sets an
+  // empty array (it omits the key), so a present-but-empty `[]` is itself a
+  // signal of a malformed/tampered record — reject it explicitly.
+  if ('file_paths' in record) {
+    const fp = record.file_paths;
+    const isValidArray =
+      Array.isArray(fp) &&
+      fp.length > 0 &&
+      fp.every(
+        (p) => typeof p === 'string' && p.length > 0 && !/[\r\n]/.test(p) && !/[*?[\]{}]/.test(p),
+      );
+    if (!isValidArray) {
+      errors.push(
+        'file_paths must be a non-empty array of non-empty, newline-free, glob-metacharacter-free strings when present',
+      );
+    }
+  }
+
   if (errors.length > 0) {
     return { ok: false, errors };
   }

package/scripts/lib/moc-staleness-banner.mjs

@@ -0,0 +1,267 @@
+/**
+ * moc-staleness-banner.mjs — Session-start banner for issue #831 (building
+ * block B2).
+ *
+ * Surfaces a `warn` banner during session-start Phase 4 when a Meta-Vault
+ * MOC (map-of-content) index note — a `<vaultDir>/08-topics/*-moc.md` file —
+ * has an `updated:` frontmatter older than a configurable threshold (default
+ * 90 days). Nothing in this repo reads `08-topics/` before this module; it
+ * is the first consumer.
+ *
+ * Design notes:
+ *  - Mirrors the contract used by every other Phase 4 banner
+ *    (`scripts/lib/peer-cards/staleness-banner.mjs`, `scripts/lib/vault-staleness-banner.mjs`,
+ *    `scripts/lib/loop-readiness-banner.mjs`, `scripts/lib/reconcile-nudge-banner.mjs`,
+ *    and sibling building block `scripts/lib/context-coverage-banner.mjs` — B4
+ *    of this same issue): a single `checkXxx()` entry point that returns
+ *    `null` (silent no-op) or `{ severity, message, ... }` — never an array,
+ *    never `undefined`, never a throw.
+ *  - Synchronous — the probe only touches `existsSync`/`readdirSync`/`readFileSync`,
+ *    so unlike the async peer-cards/reconcile-nudge probes this one needs no
+ *    `await` at the call site (mirrors `checkLoopReadiness` / `checkContextCoverage`).
+ *  - Never throws. Wrapped in an outermost defensive `try/catch`; every
+ *    individually-fallible filesystem call additionally gets its own inner
+ *    bare (no-binding) catch with a one-line explanatory comment.
+ *  - `vault-dir` resolution mirrors the host-local-override pattern used
+ *    throughout the plugin (issue #653): an injected `opts.vaultDir` test
+ *    seam wins, then `config['vault-integration']['vault-dir']`, else the
+ *    probe silently no-ops (no vault configured — nothing to check).
+ *  - The committed repo default for `vault-integration.vault-dir` is
+ *    tilde-prefixed (`~/Projects/vault`) and is NOT pre-expanded anywhere
+ *    upstream of this module — `expandTilde()` from `./common.mjs` is applied
+ *    unconditionally before the first `path.join`, exactly as
+ *    `checkContextCoverage()` does for the same reason.
+ *  - A `*-moc.md` file whose `updated:` frontmatter is missing or
+ *    unparseable is EXCLUDED, not reported stale — mirrors
+ *    `scripts/lib/peer-cards/staleness-banner.mjs` (~L61-76): the corrective
+ *    action there is "fix the frontmatter", not this banner's "refresh the
+ *    `updated:` date" remediation hint. Gated via `Number.isFinite(days)`.
+ *
+ * Cross-references:
+ *  - `scripts/lib/config/moc-staleness.mjs` (`_parseMocStaleness`) — the
+ *    `moc-staleness:` Session Config block parser. NOT wired into
+ *    `scripts/lib/config.mjs` by this module — the coordinator registers it
+ *    separately. The exact lines to add there:
+ *
+ *      import { _parseMocStaleness } from './config/moc-staleness.mjs';
+ *      // ... later, alongside the other top-level block parses:
+ *      const mocStaleness = _parseMocStaleness(mdContent);
+ *      // ... in the returned config object:
+ *      'moc-staleness': mocStaleness,
+ *
+ *  - `scripts/lib/common.mjs` (`expandTilde`) — shared tilde-expansion helper.
+ *  - `scripts/lib/context-coverage-banner.mjs` — sibling B4 building block for
+ *    the same issue; this module mirrors its structure closely.
+ *  - `skills/session-start/SKILL.md` Phase 4 — banner render site (wiring
+ *    snippet supplied separately; this module does not edit that file).
+ *  - Issue #831 (building block B2).
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import YAML from 'js-yaml';
+
+import { expandTilde } from './common.mjs';
+
+/** Vault-relative directory holding MOC (map-of-content) index notes. */
+const MOC_SUBDIR = '08-topics';
+
+/** Filename suffix that identifies a MOC note within `08-topics/`. */
+const MOC_SUFFIX = '-moc.md';
+
+/** Fallback staleness threshold (days) when config supplies none/invalid. */
+const DEFAULT_THRESHOLD_DAYS = 90;
+
+/** Matches a leading `---\n...\n---` YAML frontmatter fence. */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+/**
+ * Above this many stale filenames, the message truncates the name list and
+ * says so explicitly rather than silently dropping names past the limit.
+ */
+const MAX_STALE_NAMES_IN_MESSAGE = 20;
+
+/**
+ * Resolve the vault directory to scan.
+ *
+ * Precedence: `opts.vaultDir` (test seam) > `config['vault-integration']['vault-dir']` > null.
+ *
+ * @param {string|undefined} vaultDir
+ * @param {unknown} config
+ * @returns {string|null} raw (not-yet-tilde-expanded) vault dir, or null when unresolvable
+ */
+function _resolveRawVaultDir(vaultDir, config) {
+  if (typeof vaultDir === 'string' && vaultDir.length > 0) return vaultDir;
+
+  if (config && typeof config === 'object') {
+    const vaultIntegration = /** @type {Record<string, unknown>} */ (config)['vault-integration'];
+    if (vaultIntegration && typeof vaultIntegration === 'object') {
+      const raw = /** @type {Record<string, unknown>} */ (vaultIntegration)['vault-dir'];
+      if (typeof raw === 'string' && raw.length > 0) return raw;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Read a single MOC file and compute whole days since its `updated:`
+ * frontmatter field. Returns `NaN` (never throws) when the file cannot be
+ * read, has no frontmatter fence, the YAML fails to parse, `updated` is
+ * missing/non-string, or `updated` is not a parseable date — every one of
+ * these cases is the caller's signal to EXCLUDE the file, not report it
+ * stale.
+ *
+ * @param {string} filePath — absolute path to a `*-moc.md` file
+ * @param {number} nowMs — epoch ms clock
+ * @returns {number} whole days since `updated:`, or `NaN`
+ */
+function _readMocStalenessDays(filePath, nowMs) {
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return NaN;
+  }
+
+  const m = raw.match(FRONTMATTER_RE);
+  if (!m) return NaN;
+
+  let fm;
+  try {
+    fm = YAML.load(m[1]);
+  } catch {
+    return NaN;
+  }
+
+  if (!fm || typeof fm !== 'object' || Array.isArray(fm)) return NaN;
+
+  // js-yaml's default schema auto-resolves an ISO-8601-shaped scalar (the
+  // canonical `updated:` form) into a native `Date`, NOT a string — verified:
+  // `YAML.load('updated: 2026-01-01T00:00:00Z').updated instanceof Date`.
+  // Accept both shapes; anything else (missing, number, array, …) excludes.
+  const rawUpdated = fm.updated;
+  let updatedMs;
+  if (rawUpdated instanceof Date) {
+    updatedMs = rawUpdated.getTime();
+  } else if (typeof rawUpdated === 'string') {
+    updatedMs = Date.parse(rawUpdated);
+  } else {
+    return NaN;
+  }
+  if (!Number.isFinite(updatedMs)) return NaN;
+
+  return Math.floor((nowMs - updatedMs) / 86_400_000);
+}
+
+/**
+ * Format the stale-filename list for the banner message, truncating (with an
+ * explicit note) past `MAX_STALE_NAMES_IN_MESSAGE`.
+ *
+ * @param {Array<{file: string, days: number}>} stale
+ * @returns {string}
+ */
+function _formatStaleNames(stale) {
+  const parts = stale.map((s) => `${s.file} (${s.days}d)`);
+  if (parts.length <= MAX_STALE_NAMES_IN_MESSAGE) return parts.join(', ');
+  const shown = parts.slice(0, MAX_STALE_NAMES_IN_MESSAGE).join(', ');
+  const hiddenCount = parts.length - MAX_STALE_NAMES_IN_MESSAGE;
+  return `${shown}, and ${hiddenCount} more (name list truncated)`;
+}
+
+/**
+ * Check MOC staleness and produce a session-start banner.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot] — REQUIRED absolute path to the repo root.
+ * @param {string} [opts.vaultDir] — test seam; overrides the config-resolved vault dir.
+ * @param {Date|number} [opts.now] — injectable clock for deterministic tests.
+ * @param {object} [opts.config] — optional already-parsed Session Config (avoids
+ *   a second CLAUDE.md (or AGENTS.md on Codex CLI) read; caller passes `$CONFIG`, mirrors `checkContextCoverage`).
+ *   Read keys: `config['moc-staleness']` (`.enabled`, `.mode`, `.thresholds.moc`)
+ *   and `config['vault-integration']['vault-dir']`.
+ * @returns {null | { severity: 'warn', message: string, stale: Array<{file: string, days: number}> }}
+ */
+export function checkMocStaleness({ repoRoot, vaultDir, now, config } = {}) {
+  try {
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    const cfg =
+      config &&
+      typeof config === 'object' &&
+      config['moc-staleness'] &&
+      typeof config['moc-staleness'] === 'object'
+        ? config['moc-staleness']
+        : {};
+
+    // Config gate — returns null BEFORE any filesystem I/O. Explicit opt-in
+    // required: `cfg.enabled` must be the literal `true`, not merely
+    // truthy/absent. A config block that is entirely absent (or present
+    // without an `enabled` key) must fail CLOSED, not open — see issue #831
+    // fail-open regression (a config carrying `vault-integration.vault-dir`
+    // but no `moc-staleness` block previously ran the probe unsolicited,
+    // because `undefined !== false`).
+    if (cfg?.enabled !== true || cfg?.mode === 'off') return null;
+
+    const rawVaultDir = _resolveRawVaultDir(vaultDir, config);
+    if (!rawVaultDir) return null;
+
+    const resolvedVaultDir = expandTilde(rawVaultDir);
+    const topicsDir = path.join(resolvedVaultDir, MOC_SUBDIR);
+
+    if (!existsSync(topicsDir)) return null;
+
+    let entries;
+    try {
+      entries = readdirSync(topicsDir);
+    } catch {
+      return null;
+    }
+    if (!Array.isArray(entries) || entries.length === 0) return null;
+
+    entries = [...entries].sort();
+
+    const mocFiles = entries.filter((f) => typeof f === 'string' && f.endsWith(MOC_SUFFIX));
+    if (mocFiles.length === 0) return null;
+
+    const nowMs =
+      now instanceof Date
+        ? now.getTime()
+        : typeof now === 'number' && Number.isFinite(now)
+          ? now
+          : Date.now();
+
+    const cfgThreshold =
+      cfg.thresholds && typeof cfg.thresholds === 'object' ? cfg.thresholds.moc : undefined;
+    const thresholdDays =
+      typeof cfgThreshold === 'number' && Number.isFinite(cfgThreshold) && cfgThreshold > 0
+        ? cfgThreshold
+        : DEFAULT_THRESHOLD_DAYS;
+
+    const stale = [];
+    for (const file of mocFiles) {
+      const filePath = path.join(topicsDir, file);
+      let days;
+      try {
+        days = _readMocStalenessDays(filePath, nowMs);
+      } catch {
+        days = NaN;
+      }
+      // Missing/unparseable `updated:` is EXCLUDED, not reported stale.
+      if (!Number.isFinite(days)) continue;
+      if (days > thresholdDays) stale.push({ file, days });
+    }
+
+    if (stale.length === 0) return null;
+
+    const subjectLabel = stale.length === 1 ? '1 MOC stale' : `${stale.length} MOCs stale`;
+    const finding = `${subjectLabel} (>${thresholdDays} days)`;
+    const remediation = 'review and refresh the `updated:` frontmatter.';
+    const message = `⚠ moc-staleness: ${finding} — ${_formatStaleNames(stale)} — ${remediation}`;
+
+    return { severity: 'warn', message, stale };
+  } catch {
+    // Defensive catch-all — banner must never throw.
+    return null;
+  }
+}