session-orchestrator 3.16.0

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

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/**
+ * vault-repo-backfill.mjs — Pure inference layer for vault session→repo backfill.
+ *
+ * Infers the owning repo namespace for historical, flat-corpus vault SESSION notes
+ * that predate per-repo namespacing (Issue #700 Vault-Coverage-Lift). Unlike
+ * vault-relocation-rules.mjs (which classifies notes that already carry a `repo:` /
+ * `project/<slug>` signal), this module recovers ownership for sessions whose only
+ * recoverable signal is their `id` — by joining against authoritative cross-repo
+ * indices that the CLI builds from each repo's `sessions.jsonl`.
+ *
+ * This module is PURE: no `fs`, no `child_process`, no `process.cwd()`, no network.
+ * ALL cross-repo data (the sid + branch/date indices) is INJECTED by the caller.
+ * The CLI walks the filesystem and builds the indices; this module only reasons.
+ * The ONLY import is the pure, leak-guarding resolveRepoNamespace string function.
+ *
+ * Confidence tiers (W1-D5 frozen contract; W1-D2 evidence — do not re-litigate):
+ *   - HIGH   ('sid-authoritative')  : frontmatter.id is in sidIndex AND that id maps
+ *                                     to EXACTLY ONE repo. The sid-join is collision-
+ *                                     free by construction (size===1 gate). 23 ids
+ *                                     collide cross-repo → they hit SKIP, never HIGH.
+ *   - SKIP   ('id-collision')       : id maps to >1 repo in sidIndex → ambiguous.
+ *   - MEDIUM ('branchdate-unique')  : id NOT in sidIndex, but (branch,date) parsed
+ *                                     from the id maps to EXACTLY ONE repo in bdIndex.
+ *                                     Bare branch+date is UNSAFE (37/106 pairs collide)
+ *                                     — that's exactly why MEDIUM also requires size===1.
+ *   - SKIP   ('no-signal')          : no usable signal / ambiguous (branch+date >1 repo,
+ *                                     or no parseable date token).
+ *   - SKIP   ('leak-guarded')       : a tier resolved a repo, but the resolved namespace
+ *                                     is 'redacted-repo' or 'unknown-repo'. A leak-guarded
+ *                                     slug must NEVER become a confident move — this is the
+ *                                     blast-radius floor for a mis-inferred PRIVATE slug on
+ *                                     a future live --apply.
+ */
+
+import { resolveRepoNamespace } from './vault-mirror/namespace.mjs';
+
+// ---------------------------------------------------------------------------
+// Test seam — mirrors _setResolverForTest in vault-relocation-rules.mjs
+// ---------------------------------------------------------------------------
+
+/** @type {(opts: { vaultName: string | null }) => string} */
+let _resolveNamespace = resolveRepoNamespace;
+
+/**
+ * Inject a custom namespace resolver for testing. Returns the previous resolver
+ * so tests can restore it after each case.
+ *
+ * @param {(opts: { vaultName: string | null }) => string} fn
+ * @returns {(opts: { vaultName: string | null }) => string}
+ */
+export function _setResolverForTest(fn) {
+  const prev = _resolveNamespace;
+  _resolveNamespace = fn;
+  return prev;
+}
+
+// ---------------------------------------------------------------------------
+// Leak-guard sentinels
+// ---------------------------------------------------------------------------
+
+const LEAK_GUARDED = new Set(['redacted-repo', 'unknown-repo']);
+
+// ---------------------------------------------------------------------------
+// Session-id parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a session id into its branch + date components.
+ *
+ * A session_id looks like `<branch>-YYYY-MM-DD-<suffix>` where the BRANCH MAY
+ * CONTAIN HYPHENS (e.g. `feat-harness-reliability-2026-04-19-1515` → branch
+ * `feat-harness-reliability`, date `2026-04-19`). The regex anchors on the date
+ * token so a hyphenated branch is captured whole.
+ *
+ * @param {string} id
+ * @returns {{ branch: string, date: string } | null} null when no date token is found.
+ */
+export function parseSessionId(id) {
+  if (!id || typeof id !== 'string') return null;
+  const m = id.match(/^(.*)-(\d{4}-\d{2}-\d{2})(?:-|$)/);
+  if (!m) return null;
+  const branch = m[1];
+  const date = m[2];
+  // A bare leading date ('2026-04-19-x') yields an empty branch — no (branch,date)
+  // signal, since branch is part of the bdIndex key.
+  if (!branch) return null;
+  return { branch, date };
+}
+
+// ---------------------------------------------------------------------------
+// Internal: leak-guarded namespace resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a repo basename to its vault namespace, then apply the leak-guard
+ * downgrade. Returns either the confident namespace, or a SKIP result when the
+ * resolved namespace is a leak-guard sentinel.
+ *
+ * @param {string} repoBasename - the single resolved repo basename
+ * @returns {{ repo: string, confidence: 'HIGH'|'MEDIUM', source: string } | { repo: null, confidence: 'SKIP', source: 'leak-guarded' }}
+ *   shaped via the caller passing through the intended confidence/source on success.
+ */
+function resolveWithLeakGuard(repoBasename, confidence, source) {
+  const namespace = _resolveNamespace({ vaultName: repoBasename });
+  if (LEAK_GUARDED.has(namespace)) {
+    return { repo: null, confidence: 'SKIP', source: 'leak-guarded' };
+  }
+  return { repo: namespace, confidence, source };
+}
+
+/**
+ * Extract the sole member of a Set, or null when the set is absent/empty/non-unique.
+ *
+ * @param {Set<string> | undefined} set
+ * @returns {string | null}
+ */
+function soleMember(set) {
+  if (!set || typeof set.size !== 'number' || set.size !== 1) return null;
+  // Iterate to grab the single element.
+  for (const v of set) return v;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Per-session inference
+// ---------------------------------------------------------------------------
+
+/**
+ * Infer the owning repo namespace for a single vault session note.
+ *
+ * @param {object} frontmatter - parsed session frontmatter; only `id` is consulted.
+ * @param {object} [opts]
+ * @param {Map<string, Set<string>>} [opts.sidIndex] - Map<sessionId, Set<repoBasename>>:
+ *   the AUTHORITATIVE join — which repos' sessions.jsonl carry this session_id.
+ * @param {Map<string, Set<string>>} [opts.bdIndex] - Map<`${branch}|${date}`, Set<repoBasename>>:
+ *   the branch+date fallback index.
+ * @param {(o: { vaultName: string | null }) => string} [opts.resolveNamespace] -
+ *   per-call override of the bound resolver (defaults to the module resolver).
+ * @returns {{ repo: string | null, confidence: 'HIGH'|'MEDIUM'|'SKIP', source: string }}
+ */
+export function inferRepoForSession(frontmatter, opts = {}) {
+  const {
+    sidIndex = new Map(),
+    bdIndex = new Map(),
+    resolveNamespace,
+  } = opts;
+
+  // Allow a per-call resolver override without disturbing the module seam.
+  const prev = resolveNamespace ? _setResolverForTest(resolveNamespace) : null;
+  try {
+    const id =
+      frontmatter && typeof frontmatter.id === 'string' ? frontmatter.id.trim() : '';
+
+    // --- Tier 1: authoritative sid-join (HIGH / id-collision SKIP) ---
+    if (id && sidIndex.has(id)) {
+      const repos = sidIndex.get(id);
+      if (repos && repos.size > 1) {
+        return { repo: null, confidence: 'SKIP', source: 'id-collision' };
+      }
+      const sole = soleMember(repos);
+      if (sole) {
+        return resolveWithLeakGuard(sole, 'HIGH', 'sid-authoritative');
+      }
+      // Defensive: an empty Set under a present key carries no signal — fall through.
+    }
+
+    // --- Tier 2: branch+date fallback (MEDIUM / no-signal SKIP) ---
+    if (id) {
+      const parsed = parseSessionId(id);
+      if (parsed) {
+        const key = `${parsed.branch}|${parsed.date}`;
+        const repos = bdIndex.get(key);
+        const sole = soleMember(repos);
+        if (sole) {
+          return resolveWithLeakGuard(sole, 'MEDIUM', 'branchdate-unique');
+        }
+      }
+    }
+
+    // --- No usable signal / ambiguous ---
+    return { repo: null, confidence: 'SKIP', source: 'no-signal' };
+  } finally {
+    if (prev) _setResolverForTest(prev);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Convenience index builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a backfill index from already-parsed vault session notes.
+ *
+ * The CLI parses each vault session file into `{ id, frontmatter }`; this stays
+ * pure and only reasons over the injected indices. Returns ONLY confident entries
+ * (HIGH or MEDIUM); SKIP entries are omitted.
+ *
+ * @param {Array<{ id: string, frontmatter: object }>} parsedVaultSessions
+ * @param {object} [opts] - forwarded to inferRepoForSession (sidIndex, bdIndex, resolveNamespace).
+ * @returns {Map<string, { repo: string, confidence: 'HIGH'|'MEDIUM', source: string }>}
+ *   keyed by sessionId.
+ */
+export function buildBackfillIndex(parsedVaultSessions, opts = {}) {
+  const out = new Map();
+  if (!Array.isArray(parsedVaultSessions)) return out;
+
+  for (const entry of parsedVaultSessions) {
+    if (!entry || typeof entry !== 'object') continue;
+    const { id, frontmatter } = entry;
+    if (!id || typeof id !== 'string') continue;
+
+    const result = inferRepoForSession(frontmatter ?? {}, opts);
+    if (isBackfillDerivable(result.confidence)) {
+      out.set(id, result);
+    }
+  }
+
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Derivability predicate
+// ---------------------------------------------------------------------------
+
+/**
+ * Single source of truth for "feeds --derivable-only": a confidence tier is
+ * derivable iff it is HIGH or MEDIUM. SKIP (any source) is not derivable.
+ *
+ * @param {string} confidence
+ * @returns {boolean}
+ */
+export function isBackfillDerivable(confidence) {
+  return confidence === 'HIGH' || confidence === 'MEDIUM';
+}

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

@@ -0,0 +1,142 @@
+/**
+ * vault-staleness-banner.mjs — #319
+ * Reads the latest vault-staleness probe record and classifies a banner
+ * severity (warn | alert) for surfacing stale projects in the Meta-Vault.
+ *
+ * Plain-JS validation — no Zod dependency. Never throws. Never mutates input.
+ *
+ * Source JSONL schema (one line per probe run):
+ *   {timestamp, probe, project_root, vault_dir, scanned_projects,
+ *    stale_count, errors, duration_ms,
+ *    findings: [{slug, severity, last_sync, delta_hours, flag}, ...]}
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Format a delta_hours number for the banner message.
+ * Rounds to 1 decimal; integers render without a trailing ".0".
+ *
+ * @param {number} hours
+ * @returns {string}
+ */
+function formatDelta(hours) {
+  const n = Number(hours);
+  if (!Number.isFinite(n)) return '0';
+  const rounded = Math.round(n * 10) / 10;
+  // Drop ".0" for whole numbers (e.g. 23.0 -> "23"), keep "140.7"
+  return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
+}
+
+/**
+ * Reads `.orchestrator/metrics/vault-staleness.jsonl` (last record) and
+ * computes a banner severity classification. Never throws — graceful no-op
+ * on any read error, schema mismatch, or empty/zero-stale state.
+ *
+ * Severity rules (issue #319):
+ *   - file absent / unreadable / malformed / stale_count === 0 → null (silent)
+ *   - stale_count > 0 AND maxDelta <= 48 → 'warn'
+ *   - stale_count > 0 AND maxDelta  > 48 → 'alert' (cron likely broken)
+ *
+ * @param {{repoRoot: string}} opts
+ * @returns {null | {
+ *   severity: 'warn'|'alert',
+ *   message: string,
+ *   staleCount: number,
+ *   maxDeltaHours: number,
+ *   timestamp: string,
+ * }}
+ */
+export function checkVaultStaleness({ repoRoot } = {}) {
+  try {
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    const jsonlPath = path.join(
+      repoRoot,
+      '.orchestrator',
+      'metrics',
+      'vault-staleness.jsonl',
+    );
+
+    if (!existsSync(jsonlPath)) return null;
+
+    let raw;
+    try {
+      raw = readFileSync(jsonlPath, 'utf8');
+    } catch {
+      return null;
+    }
+
+    // Take the last non-empty line.
+    const lines = raw.split('\n').filter((l) => l.length > 0);
+    if (lines.length === 0) return null;
+    const lastLine = lines[lines.length - 1];
+
+    let record;
+    try {
+      record = JSON.parse(lastLine);
+    } catch {
+      return null;
+    }
+
+    if (!record || typeof record !== 'object') return null;
+
+    const staleCount = record.stale_count;
+    if (typeof staleCount !== 'number' || staleCount < 0 || Number.isNaN(staleCount)) {
+      return null;
+    }
+
+    if (!Array.isArray(record.findings)) return null;
+
+    if (staleCount === 0) return null;
+
+    // Compute max delta_hours across findings; treat undefined/null/NaN as 0.
+    let maxDelta = 0;
+    for (const finding of record.findings) {
+      if (!finding || typeof finding !== 'object') continue;
+      const d = Number(finding.delta_hours);
+      if (Number.isFinite(d) && d > maxDelta) maxDelta = d;
+    }
+
+    const severity = maxDelta > 48 ? 'alert' : 'warn';
+    const timestamp = typeof record.timestamp === 'string' ? record.timestamp : 'unknown';
+    const deltaStr = formatDelta(maxDelta);
+
+    let message;
+    if (severity === 'alert') {
+      message =
+        `⚠ vault-staleness: ${staleCount} projects stale ` +
+        `(max delta: ${deltaStr}h) — Vault-Sync cron likely broken; ` +
+        `verify the cron source and the last-success timestamp.`;
+    } else {
+      message =
+        `⚠ vault-staleness: ${staleCount} projects stale ` +
+        `(max delta: ${deltaStr}h) — last run ${timestamp}.`;
+    }
+
+    return {
+      severity,
+      message,
+      staleCount,
+      maxDeltaHours: maxDelta,
+      timestamp,
+    };
+  } catch {
+    // Defensive catch-all — banner must never throw.
+    return null;
+  }
+}
+
+/**
+ * Convenience renderer: returns the banner message string, or empty string
+ * when no banner should be shown. Intended for inline use from SKILL.md
+ * snippets (e.g. `node -e "import('./...').then(m => process.stdout.write(m.renderBanner({repoRoot: process.cwd()})))"`).
+ *
+ * @param {{repoRoot: string}} opts
+ * @returns {string}
+ */
+export function renderBanner({ repoRoot } = {}) {
+  const result = checkVaultStaleness({ repoRoot });
+  return result ? result.message : '';
+}