session-orchestrator 3.23.0 → 4.0.0

package/scripts/lib/owner-yaml.mjs

@@ -38,26 +38,148 @@
  *
  * ── Exports ───────────────────────────────────────────────────────────────────
  *
- *   OWNER_YAML_PATH            — default file path on disk
+ *   resolvePrivateConfigDir({env}?) — THE host-private config dir resolver (#1223)
+ *   resolveOwnerYamlPath(env?) — owner.yaml path, resolved at CALL time (#1223)
  *   validateOwnerSections(obj) — pure validation, no I/O; bucketed per section (#820)
  *   validateOwnerConfig(obj)   — pure validation, no I/O; thin wrapper over validateOwnerSections
  *   loadOwnerConfig({path?})   — reads file; per-section tolerance for OPTIONAL
  *                                sections (paths/dispatcher/vaults/baselines) — #820
  *   writeOwnerConfig(config, {path?}) — validates, writes YAML, creates dir
  *   getDefaults()              — returns sensible default config object
+ *
+ * ── Zero bare-specifier imports (GH#62/#63, GitLab #1230) ────────────────────
+ *
+ * `js-yaml` is resolved LAZILY inside {@link loadOwnerConfig} / {@link
+ * writeOwnerConfig} (see {@link getYaml}), never at module load. Importing this
+ * module therefore costs `node:fs` + `node:path` + `node:module` and nothing
+ * else, which is what keeps it safe on the hook import graph: before this
+ * change, `import yaml from 'js-yaml'` at the top of this file crashed FOUR
+ * hooks with `ERR_MODULE_NOT_FOUND` for anyone whose `node_modules` was absent
+ * (on-session-start, on-session-end, post-edit-validate,
+ * skill-invocation-telemetry — measured 2026-09-06 over a `hooks/` + `scripts/`
+ * copy with no `node_modules`, 4 of 27 hooks rc=1).
+ *
+ * When the package cannot be resolved both entry points DEGRADE rather than
+ * throw: they return their normal shape plus `reason: 'yaml-parser-missing'`
+ * (`source: 'defaults'` / `written: false`) and emit ONE rate-limited stderr
+ * WARN naming `npm install` as the fix.
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
-import yaml from 'js-yaml';
+import { createRequire } from 'node:module';
+import { resolvePrivateConfigDir } from './config/private-config-dir.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-/** Default path for the owner persona config file. */
-export const OWNER_YAML_PATH = join(homedir(), '.config', 'session-orchestrator', 'owner.yaml');
+/** Basename of the owner persona config file. */
+const OWNER_YAML_FILE = 'owner.yaml';
+
+// ---------------------------------------------------------------------------
+// Lazy js-yaml resolution (GH#62/#63, GitLab #1230)
+// ---------------------------------------------------------------------------
+
+/**
+ * Memoised `js-yaml` module, or `false` once resolution has failed.
+ * `null` = not yet attempted.
+ * @type {null | false | { load: Function, dump: Function }}
+ */
+let _yaml = null;
+
+/** Guards the one-per-process stderr WARN below. */
+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
+ * `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`.
+ *
+ * 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
+ * failure is catchable — instead of at module load, where it is not.
+ *
+ * Same shape as the `getPicomatch()` pattern in `scripts/lib/rule-loader.mjs`
+ * and `scripts/lib/validate-vendored-rules.mjs`.
+ *
+ * @returns {{ load: Function, dump: Function } | null} the module, or `null`
+ *   when `node_modules` is absent / the package cannot be resolved.
+ */
+function getYaml() {
+  if (_yaml !== null) return _yaml === false ? null : _yaml;
+  try {
+    _yaml = createRequire(import.meta.url)('js-yaml');
+  } catch {
+    _yaml = false;
+  }
+  return _yaml === false ? null : _yaml;
+}
+
+/**
+ * Emit the one-per-process actionable WARN for a missing `js-yaml`. Kept to a
+ * SINGLE line and rate-limited to once per process, mirroring the GH#63
+ * degradation contract `hooks/on-stop.mjs` already satisfies: a missing package
+ * must never be louder than the fix it asks for.
+ */
+function warnYamlMissing() {
+  if (_yamlWarned) return;
+  _yamlWarned = true;
+  console.warn(
+    "WARN owner-yaml: 'js-yaml' is not installed — owner.yaml cannot be parsed or written; " +
+      "using defaults. Run 'npm install' in the plugin directory to restore it.",
+  );
+}
+
+/**
+ * Re-export of the single host-private-config-dir resolver (#1223).
+ *
+ * The implementation lives in the ZERO-IMPORT leaf
+ * `scripts/lib/config/private-config-dir.mjs`, NOT here: `host-identity.mjs`
+ * sits on `hooks/on-stop.mjs`'s import subgraph (via `session-lock.mjs`), and
+ * this module statically imports `js-yaml`. While the resolver lived here,
+ * importing it from `host-identity.mjs` dragged `js-yaml` onto THAT subgraph and
+ * broke the GH#63 "degrade gracefully without node_modules" contract
+ * (`ERR_MODULE_NOT_FOUND` in `tests/hooks/on-stop.test.mjs`).
+ *
+ * As of GitLab #1230 (2026-09-06) THIS module is no longer a bare-specifier node
+ * on that graph either: the `js-yaml` import it used to carry statically is now
+ * lazy (see {@link getYaml}), so the four hooks that reach this file —
+ * on-session-start, on-session-end, post-edit-validate,
+ * skill-invocation-telemetry — load without `node_modules` instead of dying with
+ * ERR_MODULE_NOT_FOUND. Keep it that way: any NEW static bare import added here
+ * re-breaks all four at once, in a file whose own unit tests would never notice
+ * (the repo always has `node_modules`).
+ *
+ * NOTE for `tests/husky/pre-commit-owner-leakage.test.mjs`: that test copies
+ * the CP11 import chain FILE BY FILE into a tmp repo, so the leaf below is on
+ * its copied-file list. Any FURTHER repo-local import added here needs the same
+ * treatment.
+ */
+export { resolvePrivateConfigDir };
+
+/**
+ * Resolve the owner.yaml path at CALL time via the single private-config-dir
+ * resolver {@link resolvePrivateConfigDir} (#1223). Honours
+ * `SO_CONFIG_HOME` > `XDG_CONFIG_HOME` > homedir, each trimmed.
+ *
+ * @param {Record<string, string|undefined>} [env] — env source (default `process.env`)
+ * @returns {string} absolute path to owner.yaml
+ */
+export function resolveOwnerYamlPath(env = process.env) {
+  return join(resolvePrivateConfigDir({ env }), OWNER_YAML_FILE);
+}
 
 const VALID_LANGUAGES = /** @type {const} */ (['de', 'en']);
 const VALID_TONE_STYLES = /** @type {const} */ (['direct', 'neutral', 'friendly']);
@@ -418,19 +540,43 @@ export function validateOwnerConfig(obj) {
  * surfaced only via `sectionWarnings` (never dropped, never counted towards
  * `'partial'`).
  *
+ * MERGE RULE for the whole-file discard (GitLab #1244). The discard returns
+ * `getDefaults()` — but a VALID optional object section is merged back on top
+ * of its default (`{...defaults[name], ...parsed[name]}`), key by key. `source`
+ * stays `'defaults'` and `errors` still carries every required-section error,
+ * so no existing caller's branch changes; what changes is that a host-local
+ * path the operator DID declare correctly is no longer thrown away because an
+ * unrelated section (e.g. `tone:`) is malformed. That silent loss was a
+ * fail-OPEN path for the owner-leakage scanner's CP11 rule: a partial
+ * owner.yaml carrying only `owner:` + `paths.confidential-names-file:` made the
+ * scanner report PASS while matching nothing. An INVALID optional section is
+ * still replaced by its default and is now reported via `droppedSections` on
+ * this branch too (previously only on the required-valid branch), so a consumer
+ * can tell "not configured" from "configured but unusable".
+ *
  * Defensive — never throws.
  *
+ * When `js-yaml` cannot be resolved (no `node_modules`), returns defaults with
+ * `source: 'defaults'`, `reason: 'yaml-parser-missing'` and one explanatory
+ * entry in `errors` — never throws, never crashes the importing hook (GH#62/#63).
+ * When the file exists but cannot be turned into an object at all (unreadable,
+ * YAML syntax error, non-mapping top level) the same shape is returned with
+ * `reason: 'unparseable'`: in that state NOTHING about the file's contents is
+ * knowable, which is the distinction CP11 needs in order to fail CLOSED rather
+ * than assume "nothing configured".
+ *
  * @param {{ path?: string }} [opts]
  * @returns {{
  *   config: object,
  *   source: 'file'|'defaults'|'partial',
  *   errors: string[],
+ *   reason?: 'yaml-parser-missing'|'unparseable',
  *   droppedSections?: Array<{ section: string, errors: string[] }>,
  *   sectionWarnings?: Array<{ section: string, errors: string[] }>,
  * }}
  */
 export function loadOwnerConfig(opts = {}) {
-  const filePath = opts.path ?? OWNER_YAML_PATH;
+  const filePath = opts.path ?? resolveOwnerYamlPath();
 
   if (!existsSync(filePath)) {
     return { config: getDefaults(), source: 'defaults', errors: [] };
@@ -443,10 +589,24 @@ export function loadOwnerConfig(opts = {}) {
     return {
       config: getDefaults(),
       source: 'defaults',
+      reason: 'unparseable',
       errors: [`failed to read owner.yaml: ${err.message}`],
     };
   }
 
+  const yaml = getYaml();
+  if (!yaml) {
+    warnYamlMissing();
+    return {
+      config: getDefaults(),
+      source: 'defaults',
+      reason: 'yaml-parser-missing',
+      errors: [
+        "yaml-parser-missing: 'js-yaml' is not installed, so owner.yaml could not be parsed (run 'npm install' in the plugin directory)",
+      ],
+    };
+  }
+
   let parsed;
   try {
     parsed = yaml.load(raw);
@@ -454,6 +614,7 @@ export function loadOwnerConfig(opts = {}) {
     return {
       config: getDefaults(),
       source: 'defaults',
+      reason: 'unparseable',
       errors: [`YAML parse error: ${err.message}`],
     };
   }
@@ -462,20 +623,36 @@ export function loadOwnerConfig(opts = {}) {
     return {
       config: getDefaults(),
       source: 'defaults',
+      reason: 'unparseable',
       errors: ['owner.yaml must contain a YAML mapping at the top level'],
     };
   }
 
   const { sections, errors: allErrors } = validateOwnerSections(parsed);
 
-  // Any REQUIRED section invalid → legacy whole-file-discard, unchanged (#820).
+  // Any REQUIRED section invalid → whole-file discard (#820), EXCEPT that a
+  // VALID optional object section is merged back onto its default (#1244 — see
+  // the MERGE RULE in the JSDoc above). `source` stays 'defaults' and `errors`
+  // is unchanged, so every existing caller branch is untouched; only the
+  // discarded-but-valid `paths:`/`dispatcher:` keys survive, which is what stops
+  // CP11 from going silently inert on a partial owner.yaml.
   const requiredInvalid = REQUIRED_SECTIONS.some((name) => !sections[name]?.valid);
   if (requiredInvalid) {
-    return {
-      config: getDefaults(),
-      source: 'defaults',
-      errors: allErrors,
-    };
+    const discardConfig = getDefaults();
+    const discardDropped = [];
+    for (const name of OPTIONAL_OBJECT_SECTIONS) {
+      const sec = sections[name];
+      if (sec?.valid && isPlainObject(parsed[name])) {
+        discardConfig[name] = { ...discardConfig[name], ...parsed[name] };
+      } else if (sec && !sec.valid) {
+        // Present but malformed — already replaced by its default above. Report
+        // it so a consumer can distinguish "not configured" from "unusable".
+        discardDropped.push({ section: name, errors: sec.errors });
+      }
+    }
+    const discardResult = { config: discardConfig, source: 'defaults', errors: allErrors };
+    if (discardDropped.length > 0) discardResult.droppedSections = discardDropped;
+    return discardResult;
   }
 
   // All REQUIRED sections valid — tolerate malformed OPTIONAL sections instead
@@ -532,12 +709,16 @@ export function loadOwnerConfig(opts = {}) {
  *
  * Synchronous. Defensive — never throws.
  *
+ * When `js-yaml` cannot be resolved (no `node_modules`), returns
+ * `{ written: false, reason: 'yaml-parser-missing', errors: [...] }` — the file
+ * is left untouched rather than half-written (GH#62/#63).
+ *
  * @param {object} config
  * @param {{ path?: string }} [opts]
- * @returns {{ written: boolean, errors: string[] }}
+ * @returns {{ written: boolean, errors: string[], reason?: 'yaml-parser-missing' }}
  */
 export function writeOwnerConfig(config, opts = {}) {
-  const filePath = opts.path ?? OWNER_YAML_PATH;
+  const filePath = opts.path ?? resolveOwnerYamlPath();
 
   const validation = validateOwnerConfig(config);
   if (!validation.valid) {
@@ -554,6 +735,18 @@ export function writeOwnerConfig(config, opts = {}) {
     };
   }
 
+  const yaml = getYaml();
+  if (!yaml) {
+    warnYamlMissing();
+    return {
+      written: false,
+      reason: 'yaml-parser-missing',
+      errors: [
+        "yaml-parser-missing: 'js-yaml' is not installed, so owner.yaml could not be written (run 'npm install' in the plugin directory)",
+      ],
+    };
+  }
+
   let yamlStr;
   try {
     yamlStr = yaml.dump(config, { lineWidth: 120, noRefs: true });

package/scripts/lib/peer-discovery.mjs

@@ -100,7 +100,16 @@ function _ageHoursFrom(startedAt, nowMs) {
 /**
  * Map one discoverActiveSessions entry into a provenance-tagged peer.
  *
- * @param {{worktreePath:string,sessionId:string,mode:string,startedAt:string,pid:number,host:string,branch:string}} s
+ * GH#67 pass-through: `registryOnly` / `lockSuperseded` / `lockOwnerId` are
+ * threaded through UNCHANGED when the upstream entry carries them (registry-
+ * sourced sessions only). Absent stays absent, so a lock-sourced peer object is
+ * byte-identical to the pre-GH#67 shape. `lockSuperseded: true` is a HINT that
+ * a LIVE lock at that repoRoot is owned by a different raw session_id — not a
+ * verdict that the peer is dead (the lock is advisory, #1085). Consumers
+ * deciding a worktree PROMOTION_OFFER downgrade such a peer to an advisory
+ * line; consumers counting or displaying peers keep it.
+ *
+ * @param {{worktreePath:string,sessionId:string,mode:string,startedAt:string,pid:number,host:string,branch:string,registryOnly?:boolean,lockSuperseded?:boolean,lockOwnerId?:string|null}} s
  * @param {number} nowMs
  * @returns {object}
  */
@@ -118,6 +127,10 @@ function _peerFromDiscovered(s, nowMs) {
     worktreePath: s.worktreePath,
   };
   if (ageHours !== undefined) peer.ageHours = ageHours;
+  // GH#67 — additive, absent-stays-absent.
+  if (s.registryOnly !== undefined) peer.registryOnly = s.registryOnly;
+  if (s.lockSuperseded !== undefined) peer.lockSuperseded = s.lockSuperseded;
+  if (s.lockOwnerId !== undefined) peer.lockOwnerId = s.lockOwnerId;
   return peer;
 }
 
@@ -189,7 +202,12 @@ function _discoveredSelfSessionId(mySessionId, repoRoot) {
  *   per-source — only the fields the originating surface can supply are emitted
  *   (no field is advertised that the implementation does not set):
  *     - source 'discovered' (from discoverActiveSessions — lock + registry unified):
- *         { source, sessionId, mode|null, host, pid, worktreePath, ageHours? }
+ *         { source, sessionId, mode|null, host, pid, worktreePath, ageHours?,
+ *           registryOnly?, lockSuperseded?, lockOwnerId? }
+ *       The last three appear ONLY on registry-sourced entries (GH#67
+ *       annotation, passed through verbatim — see `_peerFromDiscovered`).
+ *       `lockSuperseded` is a HINT, never a liveness verdict: no peer is
+ *       dropped on account of it, because the session lock is advisory.
  *     - source 'state-md' (from checkPeerStateMd):
  *         { source, sessionId, mode|null, currentWave, reason, ageHours? }
  */

package/scripts/lib/platform.mjs

@@ -2,10 +2,15 @@
  * platform.mjs — platform detection for session-orchestrator (Node.js port of platform.sh)
  * ESM-importable. Uses only Node built-ins. No external dependencies.
  *
- * Exports 10 constants + 5 named helper functions:
- *   SO_PLATFORM, SO_PLUGIN_ROOT, SO_PROJECT_DIR, SO_STATE_DIR, SO_CONFIG_FILE,
- *   SO_SHARED_DIR, SO_OS, SO_IS_WINDOWS, SO_IS_WSL, SO_PATH_SEP
- *   detectPlatform, resolvePluginRoot, resolveProjectDir, resolveStateDir, resolveConfigFile
+ * Exports:
+ *   - lazy memoized accessors (#1153 P5): getPlatform, getPluginRoot, getProjectDir,
+ *     getStateDir, getConfigFile (+ test-only _resetPlatformCache)
+ *   - plain constants (no filesystem work): SO_SHARED_DIR, SO_OS, SO_IS_WINDOWS,
+ *     SO_IS_WSL, SO_PATH_SEP
+ *   - pure resolvers: detectPlatform, resolvePluginRoot, resolveProjectDir,
+ *     resolveStateDir, resolveConfigFile
+ *
+ * NOTHING in this module touches the filesystem at import time.
  */
 
 import { existsSync, statSync } from 'node:fs';
@@ -293,23 +298,111 @@ export function resolveConfigFile(platform) {
 }
 
 // ---------------------------------------------------------------------------
-// Auto-initialise — compute all exported constants at module load
+// Lazy, memoized accessors (#1153 P5)
 // ---------------------------------------------------------------------------
+//
+// These five values used to be `export const … = detect…()` evaluated at MODULE
+// LOAD, so every one of the ~31 static importers — including the hottest
+// deny-capable hooks, which run on every single tool call — paid a filesystem
+// walk-up (statSync/existsSync per ancestor directory, twice over for
+// resolvePluginRoot) merely for importing this module, whether or not it ever
+// read the value.
+//
+// They are now computed on FIRST USE and memoized. Call the getter at the point
+// of use, never at a module's top level — a top-level `const X = getProjectDir()`
+// re-creates the exact cost this change removes.
 
-/** @type {"claude"|"codex"|"cursor"|"pi"} */
-export const SO_PLATFORM = detectPlatform();
+/**
+ * Memo slots. `undefined` is the miss sentinel — `''` is a legitimate
+ * resolvePluginRoot() result and must not re-trigger resolution.
+ * @type {{platform: ("claude"|"codex"|"cursor"|"pi")|undefined, pluginRoot: string|undefined, projectDir: string|undefined, stateDir: string|undefined, configFile: string|undefined}}
+ */
+const _cache = {
+  platform: undefined,
+  pluginRoot: undefined,
+  projectDir: undefined,
+  stateDir: undefined,
+  configFile: undefined,
+};
 
-/** Absolute path to the session-orchestrator plugin directory (empty string if unresolvable) */
-export const SO_PLUGIN_ROOT = resolvePluginRoot(SO_PLATFORM);
+/**
+ * Host platform, detected once per process.
+ * @returns {"claude"|"codex"|"cursor"|"pi"}
+ */
+export function getPlatform() {
+  if (_cache.platform === undefined) {
+    _cache.platform = detectPlatform();
+  }
+  return _cache.platform;
+}
 
-/** Absolute path to the current project root */
-export const SO_PROJECT_DIR = resolveProjectDir(SO_PLATFORM);
+/**
+ * Absolute path to the session-orchestrator plugin directory, resolved once.
+ * @returns {string}  Absolute path, or empty string if unresolvable.
+ */
+export function getPluginRoot() {
+  if (_cache.pluginRoot === undefined) {
+    _cache.pluginRoot = resolvePluginRoot(getPlatform());
+  }
+  return _cache.pluginRoot;
+}
 
-/** Platform-native state directory name */
-export const SO_STATE_DIR = resolveStateDir(SO_PLATFORM);
+/**
+ * Absolute path to the current project root, resolved once.
+ * @returns {string}
+ */
+export function getProjectDir() {
+  if (_cache.projectDir === undefined) {
+    _cache.projectDir = resolveProjectDir(getPlatform());
+  }
+  return _cache.projectDir;
+}
 
-/** Platform config file name */
-export const SO_CONFIG_FILE = resolveConfigFile(SO_PLATFORM);
+/**
+ * Platform-native state directory name (".claude" | ".codex" | ".cursor" | ".pi").
+ * @returns {string}
+ */
+export function getStateDir() {
+  if (_cache.stateDir === undefined) {
+    _cache.stateDir = resolveStateDir(getPlatform());
+  }
+  return _cache.stateDir;
+}
+
+/**
+ * Platform config file name ("CLAUDE.md" | "AGENTS.md").
+ * @returns {string}
+ */
+export function getConfigFile() {
+  if (_cache.configFile === undefined) {
+    _cache.configFile = resolveConfigFile(getPlatform());
+  }
+  return _cache.configFile;
+}
+
+/**
+ * Test-only: drop every memoized value so the next getter re-detects.
+ * Production code must never call this — the values are process-stable.
+ * @returns {void}
+ */
+export function _resetPlatformCache() {
+  _cache.platform = undefined;
+  _cache.pluginRoot = undefined;
+  _cache.projectDir = undefined;
+  _cache.stateDir = undefined;
+  _cache.configFile = undefined;
+}
+
+// The deprecated `export let SO_PLATFORM / SO_PLUGIN_ROOT / SO_PROJECT_DIR /
+// SO_STATE_DIR / SO_CONFIG_FILE` live bindings (#1153 P5) are GONE. They were
+// `undefined` until the matching getter had run in the process, which made
+// every bare read a silent wrong answer. Every consumer now calls the getter
+// (getPlatform(), getProjectDir(), …). A re-introduction is caught by the
+// named-export assertion in tests/lib/platform.test.mjs — do not add them back.
+
+// ---------------------------------------------------------------------------
+// Plain constants — no filesystem work, safe to evaluate at load
+// ---------------------------------------------------------------------------
 
 /** Shared orchestrator directory name — always ".orchestrator" */
 export const SO_SHARED_DIR = '.orchestrator';