session-orchestrator 4.1.0 → 4.2.0

package/scripts/lib/maintenance-due-banner.mjs

@@ -0,0 +1,440 @@
+/**
+ * maintenance-due-banner.mjs — ONE session-start probe for the whole
+ * maintenance loop.
+ *
+ * ## Why this module exists
+ *
+ * Measured 2026-09-09 across consumer repos: `orchestrator.evolve.completed`
+ * fired ZERO times, all 628 learnings were still active, the session-end
+ * auto-dialectic nudge recorded `decided: true` while nobody ever ran it, and
+ * memory-cleanup had run in 1 of 3 repos. The maintenance loop was not
+ * missing — it was ADVERTISED IN THREE PLACES nobody reads at a moment nobody
+ * acts: two session-end nudges (3.6.5 auto-dream, 3.6.7 auto-dialectic) fire
+ * while the operator is closing down, and the session-start `reconcile-nudge`
+ * probe spoke for one signal out of several.
+ *
+ * This probe replaces all three with a single reading at the ONE moment the
+ * operator can act on it — session start — recommending the one verb that
+ * runs the whole loop: `/session housekeeping`.
+ *
+ * ## Design constraints it is written against
+ *
+ * - **HR-101 (a signal may only warn if it is rare).** Nothing is due ⇒ the
+ *   probe is SILENT. Six independent signals are ANDed with a cooldown, not
+ *   ORed into a permanent warning: a repo that ran `/session housekeeping`
+ *   within the last {@link HOUSEKEEPING_COOLDOWN_DAYS} days says nothing at
+ *   all, because the operator already did the thing the banner would ask for.
+ * - **HR-106 (the banner reports what the rule judged).** Every DUE signal
+ *   carries the number or the date that made it due — never a bare count.
+ * - **Three-state, never two.** A signal whose inputs cannot be read goes to
+ *   `undeterminable`; it is never folded into "clean". Copied wholesale from
+ *   `reconcile-nudge-banner.mjs`'s `never` vs `undeterminable` discipline.
+ * - **NO new Session Config key.** Every threshold below is an EXISTING key or
+ *   an existing module constant. Same posture as `reconcile-nudge-banner.mjs`
+ *   and `loop-readiness-banner.mjs`: an advisory banner needs no switch.
+ *
+ * ## The six signals
+ *
+ * | id                | due when                                                              | source |
+ * |-------------------|-----------------------------------------------------------------------|--------|
+ * | `evolve`          | no `orchestrator.evolve.completed` on record AND ≥20 active learnings  | `events.jsonl` + `computeReconcileNudge` |
+ * | `sweep`           | the dry-run expiry sweep would archive ≥1 entry                       | `learnings/expiry-sweep.mjs` |
+ * | `reconcile`       | `computeReconcileNudge().nudge === true`                              | `reconcile-nudge-banner.mjs` (reused whole) |
+ * | `dialectic`       | `shouldDispatchAutoDialectic().trigger === true`                      | `auto-dialectic.mjs` |
+ * | `memory-cleanup`  | `shouldDispatchAutoDream().trigger === true`                          | `auto-dream.mjs` |
+ * | `pending-sidecar` | a pending dream/dialectic proposal younger than 14 days is unapplied   | `.orchestrator/*-pending*.md` |
+ *
+ * Only SIDE-EFFECT-FREE signal functions are called — never a variant that
+ * advances `.orchestrator/dialectic-last-run`, because a probe that writes the
+ * stamp would consume the very signal it reports. (The former recording wrapper
+ * around this signal was removed in #1288; only the pure decision function
+ * remains.)
+ *
+ * Never throws. `computeMaintenanceDue` always returns the full shape;
+ * `checkMaintenanceDue` returns the banner object or `null`.
+ *
+ * @module scripts/lib/maintenance-due-banner
+ */
+
+import { closeSync, existsSync, fstatSync, openSync, readSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { computeReconcileNudge } from './reconcile-nudge-banner.mjs';
+import { sweepExpiredLearnings } from './learnings/expiry-sweep.mjs';
+import { shouldDispatchAutoDialectic } from './auto-dialectic.mjs';
+import { shouldDispatchAutoDream } from './auto-dream.mjs';
+import { resolveMemoryDir } from './memory-paths.mjs';
+import { readCanonicalSessions } from './sessions-canonical.mjs';
+import { filterRealSessions } from './session-schema.mjs';
+
+/**
+ * How many signals this probe knows about. The banner denominator is this
+ * number MINUS the signals a kill-switch skipped on this host — see the
+ * `skipped` array in {@link computeMaintenanceDue}'s result.
+ */
+export const MAINTENANCE_TOTAL_SIGNALS = 6;
+
+/**
+ * Active-learning floor for the `evolve` signal. Deliberately the SAME number
+ * as `NUDGE_MIN_LEARNINGS` in `reconcile-nudge-banner.mjs` (20) — both answer
+ * "is the corpus large enough that never having processed it is a finding?".
+ * Defined locally rather than imported so the two can diverge if the reconcile
+ * threshold is ever retuned for reconcile-specific reasons.
+ */
+export const MAINTENANCE_MIN_LEARNINGS = 20;
+
+/** Suppress the banner when a housekeeping session completed this recently. */
+export const HOUSEKEEPING_COOLDOWN_DAYS = 7;
+
+/**
+ * A pending sidecar older than this is not a nudge, it is archaeology — the
+ * operator has demonstrably moved on, and re-raising it every session start is
+ * the HR-101 failure mode.
+ */
+export const SIDECAR_MAX_AGE_DAYS = 14;
+
+const MS_PER_DAY = 86_400_000;
+
+/** The event name whose ABSENCE is the `evolve` signal. */
+const EVOLVE_EVENT = 'orchestrator.evolve.completed';
+
+/** Pending-proposal sidecars, repo-relative (owned by auto-dream / auto-dialectic). */
+const PENDING_SIDECARS = ['.orchestrator/pending-dream.md', '.orchestrator/dialectic-pending.md'];
+
+// ---------------------------------------------------------------------------
+// Small readers — every one of them is never-throw and three-state
+// ---------------------------------------------------------------------------
+
+/** @param {unknown} now @returns {number} */
+function nowMs(now) {
+  if (now instanceof Date) return now.getTime();
+  if (typeof now === 'number' && Number.isFinite(now)) return now;
+  const parsed = typeof now === 'string' ? Date.parse(now) : NaN;
+  return Number.isFinite(parsed) ? parsed : Date.now();
+}
+
+/** ISO timestamp → `YYYY-MM-DD`, or null. */
+function isoDay(ts) {
+  return typeof ts === 'string' && ts.length >= 10 ? ts.slice(0, 10) : null;
+}
+
+/**
+ * Backwards-scan chunk size (#1290 item 2).
+ *
+ * NAMED CEILING: 256 KiB is ~800 records in this repo's ledger, so the common
+ * case — a repo that ran /evolve within its recent history — answers after a
+ * handful of reads instead of loading the whole 7.9 MB file. The scan is
+ * UNBOUNDED in the worst case ON PURPOSE: "never ran" is a claim about every
+ * line and cannot be made from a tail, so a repo with no `evolve.completed`
+ * record still walks the file to its start — just in chunks, never all at once
+ * in one string.
+ *
+ * REVISIT TRIGGER: the maintenance probe's median passes 1000 ms (half
+ * `PROBE_BUDGET_MS`), or one repo's `events.jsonl` passes 50 MB. Either means
+ * the "never ran" walk has become the cost that matters and the answer needs an
+ * index rather than a scan.
+ */
+export const TAIL_CHUNK_BYTES = 256 * 1024;
+
+/**
+ * Scan a buffer of COMPLETE lines backwards for the newest evolve record.
+ *
+ * @param {Buffer} buf
+ * @returns {{lastAt: string|null}|null} null ⇒ no record in this buffer
+ */
+function scanEvolveLines(buf) {
+  if (buf.length === 0) return null;
+  const lines = buf.toString('utf8').split('\n');
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i];
+    if (!line || !line.includes(EVOLVE_EVENT)) continue; // cheap pre-filter before JSON.parse
+    try {
+      const rec = JSON.parse(line);
+      if (rec?.event !== EVOLVE_EVENT) continue;
+      return { lastAt: typeof rec.timestamp === 'string' ? rec.timestamp : null };
+    } catch {
+      continue; // a malformed line is not evidence either way — keep scanning
+    }
+  }
+  return null;
+}
+
+/**
+ * Find the most recent `orchestrator.evolve.completed` record.
+ *
+ * Reads the ledger BACKWARDS in {@link TAIL_CHUNK_BYTES} chunks and stops at
+ * the first hit, because the interesting answer is the LAST occurrence. The
+ * former implementation `readFileSync`-ed the whole file (7.9 MB here, 30–44 ms)
+ * to answer a question the last few kilobytes usually settle.
+ *
+ * The one bug a naive chunked scan introduces is a record SPLIT across a chunk
+ * boundary: the bytes before the first newline of a chunk are the tail of a line
+ * whose head is in the chunk not read yet, so they are CARRIED, never parsed
+ * here. Splitting on the 0x0A byte is safe on UTF-8 — no continuation byte can
+ * equal a newline — so a multibyte character never splits a line either.
+ *
+ * @param {string} repoRoot
+ * @returns {{ok: boolean, lastAt: string|null}} `ok: false` ⇒ the ledger exists
+ *   but could not be read — the caller must record `undeterminable`, never clean.
+ */
+function readLastEvolveRun(repoRoot) {
+  const file = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+  if (!existsSync(file)) return { ok: true, lastAt: null }; // fresh repo: genuinely never
+  let fd;
+  try {
+    fd = openSync(file, 'r');
+    let pos = fstatSync(fd).size;
+    /** Partial line at the FRONT of everything read so far. */
+    let carry = Buffer.alloc(0);
+
+    while (pos > 0) {
+      const length = Math.min(TAIL_CHUNK_BYTES, pos);
+      pos -= length;
+      const buf = Buffer.alloc(length);
+      readSync(fd, buf, 0, length, pos);
+      const block = carry.length > 0 ? Buffer.concat([buf, carry]) : buf;
+      const firstNewline = block.indexOf(0x0a);
+      if (firstNewline === -1) {
+        carry = block; // no complete line yet — a line longer than one chunk
+        continue;
+      }
+      const hit = scanEvolveLines(block.subarray(firstNewline + 1));
+      if (hit) return { ok: true, lastAt: hit.lastAt };
+      carry = block.subarray(0, firstNewline);
+    }
+
+    // pos === 0: the carry is the file's FIRST line, complete by construction.
+    const hit = scanEvolveLines(carry);
+    return { ok: true, lastAt: hit ? hit.lastAt : null };
+  } catch {
+    return { ok: false, lastAt: null };
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+}
+
+/**
+ * Most recent COMPLETED housekeeping session, or null.
+ *
+ * @param {string} repoRoot
+ * @returns {string|null} ISO timestamp
+ */
+function readLastHousekeeping(repoRoot) {
+  try {
+    const entries = filterRealSessions(readCanonicalSessions({ repoRoot }));
+    let max = null;
+    for (const e of entries) {
+      if (e?.session_type !== 'housekeeping') continue;
+      const ts = e.completed_at;
+      if (typeof ts !== 'string' || ts.length === 0) continue;
+      if (max === null || ts > max) max = ts;
+    }
+    return max;
+  } catch {
+    return null;
+  }
+}
+
+/** Claude-Code-only memory dir gate — mirrors `session-end/phase-skip.mjs`. */
+function isClaudePlatform(platform) {
+  if (platform === undefined || platform === null || platform === '') return true;
+  const p = String(platform).toLowerCase();
+  return p === 'claude' || p === 'claude-code' || p === 'claudecode';
+}
+
+// ---------------------------------------------------------------------------
+// Computation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the maintenance-due reading. Pure with respect to the repo: reads
+ * only, writes nothing, advances no last-run stamp. Never throws.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot] — defaults to `process.cwd()`.
+ * @param {object} [opts.config] — parsed Session Config (thresholds only).
+ * @param {Date|number} [opts.now] — injectable clock.
+ * @param {string} [opts.platform] — harness platform; non-Claude skips `memory-cleanup`.
+ * @returns {Promise<{
+ *   due: Array<{id: string, detail: string}>,
+ *   total: number,
+ *   skipped: string[],
+ *   undeterminable: string[],
+ *   lastHousekeeping: string|null,
+ * }>}
+ */
+export async function computeMaintenanceDue(opts = {}) {
+  const repoRoot =
+    typeof opts.repoRoot === 'string' && opts.repoRoot.length > 0 ? opts.repoRoot : process.cwd();
+  const config = opts.config ?? {};
+  const now = nowMs(opts.now);
+
+  /** @type {Array<{id: string, detail: string}>} */
+  const due = [];
+  /** @type {string[]} */
+  const undeterminable = [];
+  /**
+   * Signals a kill-switch turned OFF for this host. They are neither due nor
+   * undeterminable — they were never judged, so they must not appear in the
+   * denominator either (HR-106: the banner reports what the rule judged).
+   * @type {string[]}
+   */
+  const skipped = [];
+  const markDue = (id, detail) => due.push({ id, detail });
+
+  // --- reconcile (S3) + the active-learning count S1 needs ------------------
+  // ONE call serves both signals: re-deriving the active-learning filter here
+  // would be a second, drifting copy of the reconcile thresholds (BV-001.2).
+  let nudge;
+  try {
+    nudge = await computeReconcileNudge({ repoRoot, now: opts.now });
+  } catch {
+    /* left undefined — the two signals below become `undeterminable`, not clean */
+  }
+  if (!nudge) {
+    undeterminable.push('evolve', 'reconcile');
+  } else {
+    // --- evolve (S1) -------------------------------------------------------
+    const evolve = readLastEvolveRun(repoRoot);
+    if (!evolve.ok) {
+      undeterminable.push('evolve');
+    } else if (evolve.lastAt === null && nudge.activeLearnings >= MAINTENANCE_MIN_LEARNINGS) {
+      markDue('evolve', `never, ${nudge.activeLearnings} active learnings`);
+    }
+
+    // --- reconcile (S3) ----------------------------------------------------
+    if (nudge.nudge === true) {
+      markDue('reconcile', isoDay(nudge.lastRunAt) ?? 'never');
+    }
+  }
+
+  // --- sweep (S2) ----------------------------------------------------------
+  try {
+    const metrics = path.join(repoRoot, '.orchestrator', 'metrics');
+    const res = await sweepExpiredLearnings({
+      filePath: path.join(metrics, 'learnings.jsonl'),
+      archivePath: path.join(metrics, 'learnings-archive.jsonl'),
+      now: opts.now,
+      dryRun: true,
+    });
+    if (Number(res?.archived) > 0) markDue('sweep', `${res.archived} expired`);
+  } catch {
+    undeterminable.push('sweep');
+  }
+
+  // --- dialectic (S4) ------------------------------------------------------
+  const cadence = config?.dialectic?.cadence ?? 5;
+  if (cadence === 0) {
+    skipped.push('dialectic');
+  } else {
+    try {
+      const dec = await shouldDispatchAutoDialectic({ repoRoot, cadence });
+      if (dec?.trigger === true) {
+        markDue('dialectic', isoDay(dec.signals?.lastRunAt) ?? 'never');
+      }
+    } catch {
+      undeterminable.push('dialectic');
+    }
+  }
+
+  // --- memory-cleanup (S5) -------------------------------------------------
+  const threshold = config?.['memory-cleanup-threshold'] ?? 5;
+  if (threshold === 0 || !isClaudePlatform(opts.platform)) {
+    skipped.push('memory-cleanup');
+  } else {
+    try {
+      const dec = await shouldDispatchAutoDream({
+        repoRoot,
+        memoryDir: resolveMemoryDir(repoRoot),
+        threshold,
+        softLimit: config?.['memory-cleanup-soft-limit'] ?? 180,
+      });
+      if (dec?.trigger === true) {
+        const s = dec.signals ?? {};
+        markDue(
+          'memory-cleanup',
+          isoDay(s.lastCleanupAt) ?? `never, ${s.sessionsSinceCleanup ?? 0} sessions`,
+        );
+      }
+    } catch {
+      undeterminable.push('memory-cleanup');
+    }
+  }
+
+  // --- pending sidecar (S6) ------------------------------------------------
+  try {
+    const pending = [];
+    for (const rel of PENDING_SIDECARS) {
+      const file = path.join(repoRoot, rel);
+      if (!existsSync(file)) continue;
+      const ageDays = (now - statSync(file).mtimeMs) / MS_PER_DAY;
+      if (ageDays <= SIDECAR_MAX_AGE_DAYS) pending.push(path.basename(rel));
+    }
+    if (pending.length > 0) markDue('pending-sidecar', pending.join(', '));
+  } catch {
+    undeterminable.push('pending-sidecar');
+  }
+
+  return {
+    due,
+    // HR-106: the denominator counts the signals this host actually EVALUATED.
+    // A signal a kill-switch turned off was never judged, so reporting it in
+    // "3 of 6" would quote a denominator the rule never used.
+    total: MAINTENANCE_TOTAL_SIGNALS - skipped.length,
+    skipped,
+    undeterminable,
+    lastHousekeeping: readLastHousekeeping(repoRoot),
+  };
+}
+
+/**
+ * Session-start probe entry point.
+ *
+ * Silent (`null`) when nothing is due and everything was readable, and ALSO
+ * when a housekeeping session completed within {@link HOUSEKEEPING_COOLDOWN_DAYS}
+ * days — the cooldown is what keeps this instrument rare (HR-101). The
+ * computation still runs and is still available via {@link computeMaintenanceDue};
+ * only the banner is suppressed.
+ *
+ * @param {{repoRoot?: string, config?: object, now?: Date|number, platform?: string}} [opts]
+ * @returns {Promise<null | {severity: 'warn', message: string}>}
+ */
+export async function checkMaintenanceDue(opts = {}) {
+  try {
+    const computed = await computeMaintenanceDue(opts);
+    if (computed.due.length === 0 && computed.undeterminable.length === 0) return null;
+
+    // Cooldown — no new config key: the housekeeping session's own record IS
+    // the "last maintenance run" stamp.
+    if (computed.lastHousekeeping !== null) {
+      const ageMs = nowMs(opts.now) - Date.parse(computed.lastHousekeeping);
+      if (Number.isFinite(ageMs) && ageMs >= 0 && ageMs < HOUSEKEEPING_COOLDOWN_DAYS * MS_PER_DAY) {
+        return null;
+      }
+    }
+
+    // HR-106: every number in the banner is a number the verdict was computed
+    // from — no aggregate stands alone without the signal that produced it.
+    const detail = computed.due.map((d) => `${d.id}: ${d.detail}`).join(' · ');
+    const unknown =
+      computed.undeterminable.length > 0
+        ? ` · undeterminable: ${computed.undeterminable.join(', ')}`
+        : '';
+    const message =
+      `⚠ maintenance due: ${computed.due.length} of ${computed.total}` +
+      (detail ? ` (${detail})` : '') +
+      unknown +
+      ' — run /session housekeeping.';
+
+    return { severity: 'warn', message };
+  } catch {
+    // Defensive catch-all — a session-start banner must never throw.
+    return null;
+  }
+}

package/scripts/lib/owner-config.example.yaml

@@ -4,69 +4,52 @@
 # ~/.config/session-orchestrator/owner.yaml (or $XDG_CONFIG_HOME/...) and
 # fill in your values. NEVER commit this file to a project repo.
 #
-# Issue #174 (Sub-Epic #161 — Owner Persona Layer). Schema reference:
-# docs/owner-config-schema.md.
-
-# Schema version. MUST be 1. The plugin refuses to load mismatched versions.
-schema-version: 1
+# SSOT is code, not this file: scripts/lib/owner-yaml.mjs (schema, validator,
+# loader, writer). Doc cross-check: docs/owner-config-schema.md.
 
 owner:
-  # Required. Display name. 1-100 characters.
+  # Required. Display name.
   name: Your Name
 
-  # Optional. SHA256 hex digest of your email address. Used for cross-host
-  # identity correlation when sharing learnings (D4/C4). 64 hex chars exactly,
-  # or null to opt out. Plugin can compute this for you on first bootstrap.
-  email-hash: null
-
-  # Required. ISO-639-1 language code (e.g. "de", "en"). Optionally with a
-  # region tag like "en-US". Drives default response language in soul.md.
+  # Required. ISO-639-1 language code — only "de" or "en" are valid.
   language: en
 
 tone:
-  # How direct should responses be. One of: direct | neutral | friendly.
-  # Default: neutral.
+  # Required. One of: direct | neutral | friendly.
   style: direct
 
-  # Optional free-form descriptor. Up to 200 chars. Examples:
-  # "austrian-pragmatic", "british-dry", "minimal-comments".
+  # Optional free-form descriptor, e.g. "austrian-pragmatic", "british-dry".
   tonality: austrian-pragmatic
 
 efficiency:
-  # Caveman-inspired output dial. One of: lite | full | ultra.
-  #   lite  — minimum tokens, telegram style, why-use-many-token-when-few-do-trick.
+  # Required. Caveman-inspired output dial. One of: lite | full | ultra.
+  #   lite  — minimum tokens, telegram style.
   #   full  — default, sentence-style narration.
-  #   ultra — full + extra context, narrative tone (ECC/teaching mode).
+  #   ultra — full + extra context, narrative tone.
   output-level: full
 
-  # Pre-tool-call narration intensity. One of: minimal | verbose.
+  # Required. Pre-tool-call narration intensity. One of: minimal | verbose.
   preamble: minimal
 
-  # Inline code comments. One of: minimal | full.
-  comments-in-code: minimal
-
 hardware-sharing:
-  # Consent gate for sharing hardware-pattern learnings (Sub-Epic C+E).
-  # When true, the plugin may export anonymized hardware patterns (e.g.
-  # "Mac M1 16GB freezes at 8 parallel agents"). Default: false (off).
+  # Required. Consent gate for sharing hardware-pattern learnings. When true,
+  # the plugin may export anonymized hardware patterns (e.g. "Mac M1 16GB
+  # freezes at 8 parallel agents"). Default: false (off).
   enabled: false
 
-  # 32-byte hex salt (64 chars), per-host. Used to derive a stable but
-  # anonymous host-class identifier. Generated on first bootstrap when
-  # hardware-sharing.enabled is set to true.
-  hash-salt: null
-
-defaults:
-  # Optional. Override the project's `test-command` from CLAUDE.md (or
-  # AGENTS.md on Codex CLI) when no repo-local override exists. Up to 200
-  # chars. See skills/_shared/instruction-file-resolution.md for the alias rule.
-  preferred-test-command: null
-
-  # Optional. Editor command for "open in editor" actions. Up to 50 chars.
-  preferred-editor: null
-
-metadata:
-  # Auto-set by the writer on first save (D2 bootstrap).
-  created_at: null
-  # Auto-bumped on every successful save.
-  updated_at: null
+  # Required (non-empty) only when enabled: true above. Per-host salt used to
+  # derive a stable but anonymous host-class identifier. Leave empty while
+  # enabled: false — the plugin can generate one for you on opt-in.
+  hash-salt: ''
+
+# Optional. Host-local path overrides (#653). Uncomment and set any of these
+# to override the committed repo-level defaults on THIS host only.
+# paths:
+#   vault-dir: ''                  # '' = no override
+#   baseline-path: ''              # '' = no override
+#   namespace-map-path: ''         # '' = no override (#725 D5)
+#   confidential-names-file: ''    # '' = no override (#728a)
+
+# Optional. Host-local cross-repo dispatcher autonomy override (#679).
+# dispatcher:
+#   autonomy: ''   # '' = no override; one of off | advisory | autonomous-gated

package/scripts/lib/owner-yaml.mjs

@@ -2,9 +2,10 @@
  * owner-yaml.mjs — owner.yaml schema, validator, parser, writer (Issue #161, D1).
  *
  * Implements the public Owner Persona Layer API: schema validation, disk I/O,
- * and sensible defaults. Intentionally separate from `owner-config.mjs` (which
- * ships the richer D2-era schema with schema-version, metadata, and extended
- * fields). This module targets the simpler D1 surface defined in the #161 epic.
+ * and sensible defaults. This module IS the live owner-config surface — the
+ * richer D2-era schema (`owner-config.mjs`, with `schema-version`, `metadata`,
+ * and extended fields) was removed on 2026-09-09; this module's D1 surface
+ * from the #161 epic is now the only one.
  *
  * ── Schema (schema-version: 1) ───────────────────────────────────────────────
  *
@@ -95,17 +96,17 @@ let _yamlWarned = false;
  * Resolve `js-yaml` at CALL time instead of at import time (GH#62/#63).
  *
  * WHY `createRequire` and not `await import('js-yaml')`: every caller of
- * {@link loadOwnerConfig} consumes it SYNCHRONOUSLY. Measured 2026-09-06 with
+ * {@link loadOwnerConfig} consumes it SYNCHRONOUSLY. Measured 2026-09-09 with
  * `rg -n --glob '!tests/**' 'loadOwnerConfig\(' scripts hooks skills` (minus
- * this file and the unrelated async homonym in `owner-config-loader.mjs`):
- * 9 call sites — 8 in code, 1 in `skills/session-start/SKILL.md:1113` — and
- * `rg 'await\s+loadOwnerConfig'` over the same scope returns ZERO. Eight read
- * `loadOwnerConfig().config` (`hooks/on-session-start.mjs:639`,
- * `hooks/skill-invocation-telemetry.mjs:155`, `scripts/telemetry.mjs:81,130`,
- * `scripts/vault-mirror.mjs:444`, `scripts/lib/telemetry/sync.mjs:202,269`,
- * and the SKILL.md snippet); the ninth destructures the same sync return
- * (`scripts/lib/soul-resolve.mjs:123`). `writeOwnerConfig` is likewise sync at
- * its single call site, `scripts/lib/owner-interview.mjs:228`.
+ * this file itself — this is the sole loader now, no other async homonym
+ * exists): 8 call sites, all synchronous — `rg 'await\s+loadOwnerConfig'`
+ * over the same scope returns ZERO. All eight read `loadOwnerConfig().config`
+ * (`hooks/on-session-start.mjs:639`, `hooks/skill-invocation-telemetry.mjs:155`,
+ * `scripts/telemetry.mjs:81,130`, `scripts/vault-mirror.mjs:444`,
+ * `scripts/lib/telemetry/sync.mjs:513,643`, and
+ * `skills/session-start/references/phase-6-7-memory-banner-telemetry-consent.md:53`).
+ * `writeOwnerConfig` is likewise sync at its single call site,
+ * `scripts/lib/owner-interview.mjs:228`.
  *
  * Making either loader async would be a breaking change to all of them; a lazy
  * `require()` keeps the sync contract and only fails at CALL time — where the

package/scripts/lib/quality-gate.mjs

@@ -117,16 +117,18 @@ function resolveRepoRoot(explicit) {
  * Closed set of `degraded` reasons for {@link loadCommandsFromSessionConfigDetailed}.
  *
  * Its own enum, deliberately not shared with `ci-status-banner.mjs`'s
- * `DEGRADED_REASONS`: the members below are exactly the three ways THIS
+ * `DEGRADED_REASONS`: the members below are the ways THIS
  * config-read can fail, and an enum whose members are not exhaustively
  * reachable cannot be switched on exhaustively.
  *
+ *   - `invalid-repo-root` — no non-blank string root was supplied.
  *   - `script-missing` — `scripts/parse-config.mjs` is not on disk.
  *   - `spawn-failed`   — the subprocess exited non-zero, timed out, or wrote
  *                        nothing to stdout.
  *   - `parse-error`    — stdout was not parseable JSON (or the read threw).
  */
 export const CONFIG_READ_DEGRADED_REASONS = Object.freeze([
+  'invalid-repo-root',
   'script-missing',
   'spawn-failed',
   'parse-error',
@@ -168,13 +170,18 @@ function sessionConfigFileExists(repoRoot) {
  * `degraded` is OMITTED, not set to null, on the success path, so a strict
  * `toEqual({commands: {…}})` pin holds for every readable config.
  *
- * Never throws.
+ * Requires an explicit, non-blank repository root; callers that intend cwd
+ * must resolve that default before invoking this loader. Never throws.
  *
  * @param {string} repoRoot
  * @returns {{commands: {lint?: string, typecheck?: string, test?: string},
- *            degraded?: 'script-missing'|'spawn-failed'|'parse-error'}}
+ *            degraded?: 'invalid-repo-root'|'script-missing'|'spawn-failed'|'parse-error'}}
  */
 export function loadCommandsFromSessionConfigDetailed(repoRoot) {
+  // Node inherits cwd for undefined/null, which would read another repo's config.
+  if (typeof repoRoot !== 'string' || !repoRoot.trim()) {
+    return { commands: {}, degraded: 'invalid-repo-root' };
+  }
   try {
     const scriptPath = join(
       dirname(fileURLToPath(import.meta.url)),
@@ -229,9 +236,9 @@ export function loadCommandsFromSessionConfigDetailed(repoRoot) {
  * Returns a partial object — keys that fail to resolve are simply absent
  * (the caller falls through to DEFAULT_COMMANDS for those).
  *
- * Thin wrapper over {@link loadCommandsFromSessionConfigDetailed}; byte-identical
- * return value for every input, including every failure path. Callers that need
- * to tell a failed read from an empty config use the detailed variant.
+ * Returns the commands half of {@link loadCommandsFromSessionConfigDetailed},
+ * including an empty object for an invalid root. Callers that need to tell a
+ * failed read from an empty config use the detailed variant.
  *
  * Never throws.
  *