session-orchestrator 5.3.0 → 5.5.0

package/scripts/lib/config/host-paths.mjs

@@ -13,6 +13,17 @@
  *   3. committed Session Config default (the value the committed CLAUDE.md —
  *      AGENTS.md on Codex CLI — produced)
  *
+ * `vault-dir` has one more tier (agents/vault#319): an owner.yaml `vault-dirs:`
+ * cwd match between env and paths.vault-dir. That tier lives in
+ * `resolveVaultDir` in scripts/lib/config.mjs, NOT here: this module is one of
+ * the three direct CP11 helpers check-owner-leakage.mjs imports, and a standalone
+ * vendored copy carries only those three files. A new import edge from here
+ * (e.g. to named-baseline-resolver.mjs) makes CP11 fail closed in that copy.
+ *
+ * `resolveVaultIntegrationHost` is the host-local switch for the
+ * `vault-integration` gate itself (SO#1448). It may only LOWER the committed
+ * level (strict → warn → off), never raise it.
+ *
  * SYNCHRONOUS by design: `parseSessionConfig` in scripts/lib/config.mjs is sync,
  * so this layer reuses the SYNC owner loader (`loadOwnerConfig`) and exposes only
  * sync functions. An empty/whitespace value at any tier is treated as "unset" and
@@ -90,3 +101,71 @@ export function resolveHostPath(key, committedDefault, { env = process.env, owne
 
   return committedDefault;
 }
+
+/** vault-integration levels, weakest first. The index order IS the ordering. */
+const VAULT_INTEGRATION_LEVELS = /** @type {readonly string[]} */ (['off', 'warn', 'strict']);
+
+/**
+ * @param {unknown} v
+ * @returns {'off'|'warn'|'strict'|undefined} a valid level, or undefined for unset/invalid
+ */
+function coerceVaultIntegrationLevel(v) {
+  if (typeof v !== 'string') return undefined;
+  const lower = v.trim().toLowerCase();
+  return VAULT_INTEGRATION_LEVELS.includes(lower)
+    ? /** @type {'off'|'warn'|'strict'} */ (lower)
+    : undefined;
+}
+
+/**
+ * Overlay the host-local `vault-integration` switch onto the committed block
+ * (SO#1448). Precedence: env `SO_VAULT_INTEGRATION=off|warn|strict` > owner.yaml
+ * `vault-integration: { enabled: false | mode: off|warn|strict }` > committed.
+ * An invalid value at a tier counts as unset and falls through, mirroring
+ * resolveDispatcherAutonomy in dispatcher-autonomy.mjs.
+ *
+ * LOWER-ONLY: the host's level is applied only when it is weaker than the
+ * committed one. A host that could raise it would mirror repos into the vault
+ * that never opted in, so `enabled: true` or a stronger mode is ignored.
+ * Applying `off` sets both `enabled: false` and `mode: 'off'`, so either
+ * consumer check (`enabled`, `mode != off`) sees the integration as off.
+ *
+ * @param {{ enabled?: boolean, mode?: string } & Record<string, unknown>} vi — parsed committed block
+ * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object }} [ctx] — from loadHostPaths()
+ * @returns {Record<string, unknown> & { enabled?: boolean, mode?: string, 'host-override': 'env:SO_VAULT_INTEGRATION'|'owner.yaml'|null }}
+ *   a copy of `vi`; `host-override` names the tier that lowered it, `null` when none did
+ */
+export function resolveVaultIntegrationHost(vi, { env = process.env, ownerConfig } = {}) {
+  /** @type {Record<string, unknown> & { enabled?: boolean, mode?: string, 'host-override': 'env:SO_VAULT_INTEGRATION'|'owner.yaml'|null }} */
+  const result = { ...vi, 'host-override': null };
+
+  /** @type {'off'|'warn'|'strict'|undefined} */
+  let requested = coerceVaultIntegrationLevel(env?.SO_VAULT_INTEGRATION);
+  /** @type {'env:SO_VAULT_INTEGRATION'|'owner.yaml'} */
+  let source = 'env:SO_VAULT_INTEGRATION';
+  if (requested === undefined) {
+    const owner = ownerConfig?.['vault-integration'];
+    if (owner !== null && typeof owner === 'object' && !Array.isArray(owner)) {
+      requested = owner.enabled === false ? 'off' : coerceVaultIntegrationLevel(owner.mode);
+      source = 'owner.yaml';
+    }
+  }
+  if (requested === undefined) return result;
+
+  const committedLevel =
+    vi?.enabled === true ? (coerceVaultIntegrationLevel(vi.mode) ?? 'warn') : 'off';
+  if (
+    VAULT_INTEGRATION_LEVELS.indexOf(requested) >= VAULT_INTEGRATION_LEVELS.indexOf(committedLevel)
+  ) {
+    return result;
+  }
+
+  if (requested === 'off') {
+    result.enabled = false;
+    result.mode = 'off';
+  } else {
+    result.mode = requested;
+  }
+  result['host-override'] = source;
+  return result;
+}

package/scripts/lib/config/persona-gate-wave.mjs

@@ -10,7 +10,7 @@
  *   after           — 'quality' | 'impl-polish'  (default: 'quality')
  *   threshold       — string spec parsed via parseThreshold (default: 'all')
  *   personas        — string[] (each matches SAFE_PERSONA_NAME_RE)  (default: [])
- *   dispatch-model  — model alias or full ID  (default: 'claude-opus-4-7')
+ *   dispatch-model  — model alias or full ID  (default: 'opus' — tracks the current Opus)
  *   mode            — 'off' | 'warn' | 'strict'  (default: 'off')
  *
  * Used by skills/wave-executor/wave-loop.md § 3b: Persona-Gate Hook to decide
@@ -32,7 +32,7 @@ const DEFAULTS = Object.freeze({
   threshold: 'all',
   threshold_parsed: null,  // cached ParsedThreshold result; populated by _normalizePersonaGateWave
   personas: [],
-  'dispatch-model': 'claude-opus-4-7',
+  'dispatch-model': 'opus',
   mode: 'off',
 });
 
@@ -138,7 +138,7 @@ export function _normalizePersonaGateWave(parsed) {
     }
     if (!ALLOWED_MODEL_ALIASES.has(m) && !MODEL_ID_RE.test(m)) {
       throw new Error(
-        `persona-gate-wave.dispatch-model must be one of ${[...ALLOWED_MODEL_ALIASES].map((a) => JSON.stringify(a)).join('|')} or a full model ID like "claude-opus-4-7" (got ${JSON.stringify(m)})`,
+        `persona-gate-wave.dispatch-model must be one of ${[...ALLOWED_MODEL_ALIASES].map((a) => JSON.stringify(a)).join('|')} or a full model ID like "claude-opus-5-5" (got ${JSON.stringify(m)})`,
       );
     }
     out['dispatch-model'] = m;

package/scripts/lib/config/reaper.mjs

@@ -27,18 +27,19 @@ import { preprocessBlockLines } from './block-preprocess.mjs';
  * Startwerte für Stufe 1 — NOT calibrated. Every number carries its provenance
  * from the PRD §4 parameter table ("keine Zahl ohne ihre Population").
  *
- * RUNTIME SSOT is `REAPER_DEFAULTS` in `scripts/lib/orphan-reaper.mjs`; these
- * literals mirror it deliberately rather than importing it, because that module
- * pulls `process-group.mjs` + `resource-probe/parsers.mjs` into the config
- * import graph, which every `parseSessionConfig()` caller would then pay for.
- * The parity is held by a test, not by an import
+ * RUNTIME SSOT is `REAPER_DEFAULTS` in `scripts/lib/orphan-reaper/defaults.mjs`; these
+ * literals mirror it rather than importing it. The original reason — the
+ * single-file `orphan-reaper.mjs` pulled `process-group.mjs` +
+ * `resource-probe/parsers.mjs` into the config import graph — no longer holds
+ * since the #1437 split (`defaults.mjs` imports only `node:path`); revisit the
+ * mirror there. The parity is held by a test, not by an import
  * (`tests/lib/config/reaper.test.mjs` § defaults mirror REAPER_DEFAULTS).
  */
 /** 300 s — DevWatchdog's hard limit for `tsgo`; the 2026-09-20 orphans were 7–17 min old. */
 const DEFAULT_MIN_AGE_SECONDS = 300;
 /** 30 s — DevWatchdog's normal scan cadence; keeps a PostToolBatch storm from taxing every tool call. */
 const DEFAULT_MIN_SCAN_INTERVAL_SECONDS = 30;
-/** 10 000 ms — `DEFAULT_KILL_GRACE_MS` from `dispatch-common.mjs:61`; repo convention, not newly invented. */
+/** 10 000 ms — `DEFAULT_KILL_GRACE_MS` from `process-group.mjs`; repo convention, not newly invented. */
 const DEFAULT_KILL_GRACE_MS = 10_000;
 /** 500 ms — wait before reading the effect back; without it the 2026-09-20 check falsely reported "still alive". */
 const DEFAULT_VERIFY_WAIT_MS = 500;

package/scripts/lib/config/vault-integration.mjs

@@ -57,16 +57,31 @@ const MODE_ALLOWED = ['warn', 'strict', 'off'];
  * value portion (including any literal `**` inside it) is untouched.
  *
  * Defaults:
- *   enabled:    false
- *   vault-dir:  null
- *   mode:       "warn" (invalid values silently fall back to "warn")
- *   vault-name: null   (absent = downstream callers use deriveRepo() default)
+ *   enabled:       false
+ *   vault-dir:     null
+ *   mode:          "warn" (invalid values silently fall back to "warn")
+ *   vault-name:    null   (absent = downstream callers use deriveRepo() default)
+ *   gitlab-groups: null   (#1094 — non-empty string[] or null; see _groupsFromScalar)
+ *
+ * `gitlab-groups` accepts a comma string (`a, b`), a flow array (`[a, b]`) and,
+ * in block form only, a YAML block list (`gitlab-groups:` + indented `- a`
+ * lines — the shape docs/session-config-template.md documents). Inside the
+ * inline-object form more than one group needs the `[a, b]` array, because the
+ * literal is split on commas. YAML semantics throughout: `null` / `~` / empty
+ * mean unset (also as a list element), and each element loses one pair of
+ * matching quotes.
  *
  * @param {string} content — full file contents
- * @returns {{enabled: boolean, "vault-dir": string|null, mode: string, "vault-name": string|null}}
+ * @returns {{enabled: boolean, "vault-dir": string|null, mode: string, "vault-name": string|null, "gitlab-groups": string[]|null}}
  */
 export function _parseVaultIntegration(content) {
-  const defaults = { enabled: false, 'vault-dir': null, mode: 'warn', 'vault-name': null };
+  const defaults = {
+    enabled: false,
+    'vault-dir': null,
+    mode: 'warn',
+    'vault-name': null,
+    'gitlab-groups': null,
+  };
   if (typeof content !== 'string' || content === '') return defaults;
 
   // #1162: NOT a raw split. `preprocessBlockLines` drops HTML-commented lines
@@ -106,21 +121,36 @@ export function _parseVaultIntegration(content) {
   let vaultDir = null;
   let mode = 'warn';
   let vaultName = null;
+  let gitlabGroups = null;
+  // Items of a YAML block list under a value-less `gitlab-groups:` line; null
+  // while no such list is open.
+  let groupItems = null;
 
   for (const rawLine of blockLines) {
     const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
     if (!clean.trim()) continue;
 
-    // Only first-level sub-keys (single indent). Skip deeper nested keys like
-    // `gitlab-groups:` list items (handled as a no-op — they aren't in this
-    // parser's return shape).
+    if (groupItems !== null) {
+      const item = clean.match(/^\s+-(?:\s+(.*))?$/);
+      if (item) {
+        const value = _groupName((item[1] ?? '').trim());
+        if (value !== null) groupItems.push(value);
+        continue;
+      }
+    }
+
+    // Sub-keys at any indent. A list-item line (`- x`) never matches, so list
+    // items under a key this parser does not own are skipped here.
     const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)$/);
     if (!kvMatch) continue;
 
+    if (groupItems !== null) {
+      if (groupItems.length > 0) gitlabGroups = groupItems;
+      groupItems = null;
+    }
+
     const k = kvMatch[1];
-    let v = kvMatch[2].trim();
-    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
-    else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+    const v = _stripQuotes(kvMatch[2].trim());
 
     switch (k) {
       case 'enabled':
@@ -140,21 +170,118 @@ export function _parseVaultIntegration(content) {
         if (v === '' || v === 'none' || v === 'null') vaultName = null;
         else vaultName = v;
         break;
+      case 'gitlab-groups': {
+        // A value replaces any earlier one; an empty value opens a block list,
+        // which replaces it only once it has collected an item. The value goes
+        // to `_groupsFromScalar` WITH its quotes, as the inline form's does —
+        // stripping them here first read `"null"` as unset in this form only (#1496).
+        const raw = kvMatch[2].trim();
+        if (raw === '') groupItems = [];
+        else gitlabGroups = _groupsFromScalar(raw);
+        break;
+      }
     }
   }
+  if (groupItems !== null && groupItems.length > 0) gitlabGroups = groupItems;
+
+  return {
+    enabled,
+    'vault-dir': vaultDir,
+    mode,
+    'vault-name': vaultName,
+    'gitlab-groups': gitlabGroups,
+  };
+}
 
-  return { enabled, 'vault-dir': vaultDir, mode, 'vault-name': vaultName };
+/**
+ * Strip ONE pair of matching surrounding quotes (`"x"` / `'x'`). A lone quote
+ * character is returned unchanged.
+ *
+ * @param {string} v — an already-trimmed value
+ * @returns {string}
+ */
+function _stripQuotes(v) {
+  if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
+    return v.slice(1, -1);
+  }
+  return v;
 }
 
+/**
+ * The YAML 1.2 core-schema null scalars, plus the empty value. `none` is NOT
+ * one: YAML reads it as a string, so it stays a literal group name.
+ */
+const YAML_NULL_RE = /^(?:|null|Null|NULL|~)$/;
+
+/**
+ * One `gitlab-groups` element as YAML reads it: an unquoted null scalar (or an
+ * empty element) is no group at all → `null`; otherwise ONE pair of matching
+ * quotes is stripped, so `"null"` stays the string `null` exactly as in YAML.
+ *
+ * @param {string} raw — an already-trimmed element
+ * @returns {string|null}
+ */
+function _groupName(raw) {
+  if (YAML_NULL_RE.test(raw)) return null;
+  const name = _stripQuotes(raw).trim();
+  return name === '' ? null : name;
+}
+
+/**
+ * Normalise a scalar `gitlab-groups` value to a group list with YAML semantics:
+ * a null scalar (`null`, `~`, empty) is unset → `null`; otherwise drop one
+ * leading `[` and one trailing `]`, split on commas, trim, and read each element
+ * through `_groupName` (null elements dropped, one quote pair stripped). An
+ * empty result is `null`, the documented default. Before this, `null` scanned a
+ * GitLab group named "null" and `["a"]` one named `"a"` with the quotes.
+ *
+ * The ONE normalisation for both forms, so both pass the value with its quotes
+ * (#1496). A wholly quoted value is a YAML string, never a null: it loses that
+ * quote pair, is split on commas, and its elements are taken literally —
+ * `"null"` is the group "null", `"a, b"` the groups a and b.
+ *
+ * @param {string} v
+ * @returns {string[]|null}
+ */
+function _groupsFromScalar(v) {
+  const trimmed = v.trim();
+  if (YAML_NULL_RE.test(trimmed)) return null;
+  const unquoted = _stripQuotes(trimmed);
+  const readElement = unquoted === trimmed ? _groupName : (g) => (g === '' ? null : g);
+  const groups = unquoted
+    .replace(/^\[/, '')
+    .replace(/\]$/, '')
+    .split(',')
+    .map((g) => readElement(g.trim()))
+    .filter((g) => g !== null);
+  return groups.length > 0 ? groups : null;
+}
+
+/**
+ * `gitlab-groups: [ ... ]` inside an inline object literal (braces already
+ * removed). Taken out BEFORE the comma split, which would otherwise cut the
+ * array apart; every other pair is split exactly as before.
+ */
+const INLINE_GROUPS_ARRAY_RE = /(^|,)\s*gitlab-groups\s*:\s*(\[[^\]]*\])\s*(?=,|$)/;
+
 /**
  * Parse an inline YAML object literal `{ key: val, key: val }` into the
  * vault-integration return shape. Supports unquoted values including `~/` paths.
  *
  * @param {string} raw — full literal including braces
- * @returns {{enabled: boolean, "vault-dir": string|null, mode: string}}
+ * @returns {{enabled: boolean, "vault-dir": string|null, mode: string, "vault-name": string|null, "gitlab-groups": string[]|null}}
  */
 function _parseInlineObject(raw) {
-  const stripped = raw.replace(/^\s*\{/, '').replace(/\}\s*$/, '').trim();
+  let stripped = raw.replace(/^\s*\{/, '').replace(/\}\s*$/, '').trim();
+  let groupsArray = null;
+  const arrayMatch = stripped.match(INLINE_GROUPS_ARRAY_RE);
+  if (arrayMatch) {
+    groupsArray = arrayMatch[2];
+    stripped =
+      stripped.slice(0, arrayMatch.index) +
+      arrayMatch[1] +
+      stripped.slice(arrayMatch.index + arrayMatch[0].length);
+  }
   const kv = new Map();
   if (stripped !== '') {
     for (const pair of stripped.split(',')) {
@@ -180,7 +307,15 @@ function _parseInlineObject(raw) {
     vaultNameRaw === undefined || vaultNameRaw === '' || vaultNameRaw === 'none' || vaultNameRaw === 'null'
       ? null
       : vaultNameRaw;
-  return { enabled, 'vault-dir': vaultDir, mode, 'vault-name': vaultName };
+  const groupsRaw = groupsArray ?? kv.get('gitlab-groups');
+  const gitlabGroups = groupsRaw === undefined ? null : _groupsFromScalar(groupsRaw);
+  return {
+    enabled,
+    'vault-dir': vaultDir,
+    mode,
+    'vault-name': vaultName,
+    'gitlab-groups': gitlabGroups,
+  };
 }
 
 // ---------------------------------------------------------------------------

package/scripts/lib/config-schema.mjs

@@ -120,6 +120,19 @@ export function validateSessionConfig(config) {
     }
   }
 
+  // #1465 cross-field: offload-first with no declared host can never place a
+  // wave anywhere — advisory (warn-level), it never flips `ok`.
+  if (config['offload-first'] === true) {
+    const hosts = config['remote-hosts'];
+    if (!Array.isArray(hosts) || hosts.length === 0) {
+      warnings.push({
+        path: 'remote-hosts',
+        rule: 'offload-first-cross-field',
+        message: 'offload-first: true but no remote-hosts declared — every wave stays local',
+      });
+    }
+  }
+
   if (errors.length > 0) {
     return { ok: false, errors, warnings };
   }

package/scripts/lib/config.mjs

@@ -78,8 +78,61 @@ import { _parseRemoteHosts } from './config/remote-hosts.mjs';
 import { _parseEvolve, _parseEvolveDecay } from './config/evolve.mjs';
 import { _parseSkillEvolution } from './config/skill-evolution.mjs';
 import { _parseDispatcherAutonomy, resolveDispatcherAutonomy } from './config/dispatcher-autonomy.mjs';
-import { loadHostPaths, resolveHostPath } from './config/host-paths.mjs';
+import { loadHostPaths, resolveHostPath, resolveVaultIntegrationHost } from './config/host-paths.mjs';
 import { resolveNamedBaseline } from './named-baseline-resolver.mjs';
+import { expandTilde } from './common.mjs';
+
+/**
+ * Resolve `vault-dir` and report which tier produced it (agents/vault#319).
+ *
+ * Precedence (highest first): SO_VAULT_DIR env > owner.yaml `vault-dirs:`
+ * path-prefix match against the cwd > owner.yaml `paths.vault-dir` > committed.
+ * The env tier stays on top because tests/setup/vault-guard.mjs relies on it to
+ * shadow every host-local vault for the whole suite.
+ *
+ * Lives here, not in config/host-paths.mjs: host-paths.mjs is a direct CP11
+ * helper of check-owner-leakage.mjs, whose standalone vendored copy carries only
+ * its three direct helpers. The named-baseline-resolver import edge would make
+ * CP11 fail closed there (tests/husky/pre-commit-owner-leakage.test.mjs).
+ *
+ * The two owner.yaml tiers (`match`, `owner`) come back tilde-expanded: owner.yaml
+ * is host-local and `~/…` is the natural way to write a path there, but consumers
+ * such as vault-mirror.mjs `existsSync(resolve(vaultDir))` would read a literal
+ * `~` as `<cwd>/~/…`. The `env` and `committed` tiers keep their pass-through;
+ * vault-mirror.mjs expands its `--vault-dir` at entry for every tier anyway.
+ *
+ * `cwd` in the ctx is a test-only DI seam; production reads `process.cwd()`.
+ *
+ * Exported for vault writers that read only the `vault-integration` block and
+ * cannot afford `parseSessionConfig`, which throws on an invalid value in any
+ * unrelated block (scripts/vault-backfill.mjs, #1094).
+ *
+ * @param {string|null|undefined} committed — value the committed Session Config produced
+ * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object, cwd?: string }} [ctx] — from loadHostPaths()
+ * @returns {{ value: string|null|undefined, source: 'env'|'match'|'owner'|'committed' }}
+ */
+export function resolveVaultDir(committed, { env = process.env, ownerConfig, cwd } = {}) {
+  const isNonBlank = (v) => typeof v === 'string' && v.trim() !== '';
+
+  const envVal = env?.SO_VAULT_DIR;
+  if (isNonBlank(envVal)) return { value: envVal, source: 'env' };
+
+  const matched = resolveNamedBaseline({
+    cwd: cwd ?? process.cwd(),
+    ownerConfig,
+    env,
+    section: 'vault-dirs',
+    envKey: 'SO_VAULT_DIR',
+  });
+  if (matched.source === 'match' && isNonBlank(matched.path)) {
+    return { value: expandTilde(matched.path), source: 'match' };
+  }
+
+  const ownerVal = ownerConfig?.paths?.['vault-dir'];
+  if (isNonBlank(ownerVal)) return { value: expandTilde(ownerVal), source: 'owner' };
+
+  return { value: committed, source: 'committed' };
+}
 // express-path lives one level UP from config/ (see its module header for why):
 // the parser is a sibling of config/state-md-lock.mjs in every respect except
 // its directory. Only the pure parser is imported here — `evaluateExpressPath`
@@ -114,8 +167,9 @@ export { readConfigFile } from './config/io.mjs';
  *   hermetic ctx (e.g. `{ env: {}, ownerConfig: undefined }`) when asserting COMMITTED values:
  *   the default reads the real `owner.yaml`, so a host-local `paths:` override would otherwise
  *   bleed into fixture assertions (incident: 2026-07-03 Full-Gate red after the operator set
- *   `paths.baseline-path` host-locally). `cwd` feeds the `baselines:` match tier (#819) — a
- *   test-only DI seam; production always resolves it from `process.cwd()`.
+ *   `paths.baseline-path` host-locally). `cwd` feeds the `baselines:` (#819) and
+ *   `vault-dirs:` (agents/vault#319) match tiers — a test-only DI seam; production
+ *   always resolves it from `process.cwd()`.
  * @returns {object} config object with EXACT same shape as parse-config.sh stdout
  * @throws if any enum value is invalid
  */
@@ -230,6 +284,9 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // heavy-repo / worktree-cleanup: HR-003 preflight fields (templates/shared/.claude/rules/heavy-repo.md),
   // documented but previously unwired — silently dropped by the parser (baseline issue #60).
   const heavyRepo = _coerceBoolean(kv, 'heavy-repo', false);
+  // offload-first (#1465): route offloadable wave roles to a ready remote host
+  // even on a `proceed` resource verdict (consumed by wave-resource-gate.mjs).
+  const offloadFirst = _coerceBoolean(kv, 'offload-first', false);
 
   // List fields
   const crossRepos = _coerceList(kv, 'cross-repos', undefined);
@@ -331,18 +388,25 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // vault-integration: parsed from full content (block-scoped, avoids the
   // pre-#593 KV-name collision where `enabled:` was shared with 15+ other
   // blocks like docs-orchestrator/vault-staleness/slopcheck).
-  const vaultIntegration = _parseVaultIntegration(mdContent);
-  // Host-local override (issue #653) — applied here, NOT inside _parseVaultIntegration,
-  // so claude-md-drift-check (which calls the parser directly) keeps seeing raw values.
-  vaultIntegration['vault-dir'] = resolveHostPath('vault-dir', vaultIntegration['vault-dir'], hostCtx);
+  // Host-local overrides — applied here, NOT inside _parseVaultIntegration, so
+  // claude-md-drift-check (which calls the parser directly) keeps seeing raw values.
+  //   - the enabled/mode switch (SO#1448): env SO_VAULT_INTEGRATION > owner.yaml
+  //     `vault-integration:` > committed, LOWER-ONLY; `host-override` names the tier.
+  //   - vault-dir (#653, agents/vault#319): env > owner.yaml `vault-dirs:` cwd match >
+  //     owner.yaml paths.vault-dir > committed; `vault-dir-source` names the tier.
+  const vaultIntegration = resolveVaultIntegrationHost(_parseVaultIntegration(mdContent), hostCtx);
+  const vaultIntegrationDir = resolveVaultDir(vaultIntegration['vault-dir'], hostCtx);
+  vaultIntegration['vault-dir'] = vaultIntegrationDir.value;
+  vaultIntegration['vault-dir-source'] = vaultIntegrationDir.source;
 
   // resource-thresholds sub-keys (v3.1.0 env-aware — issue #166)
   const resourceThresholds = _parseResourceThresholds(kv);
 
   // vault-sync: parsed from full content (can live outside Session Config)
   const vaultSync = _parseVaultSync(mdContent);
-  // Host-local override (issue #653) — same host source as vault-integration above.
-  vaultSync['vault-dir'] = resolveHostPath('vault-dir', vaultSync['vault-dir'], hostCtx);
+  // Host-local override (issue #653) — same resolver as vault-integration above, so the
+  // two blocks cannot disagree about which vault this repo writes to (agents/vault#319).
+  vaultSync['vault-dir'] = resolveVaultDir(vaultSync['vault-dir'], hostCtx).value;
 
   // drift-check: parsed from full content (standalone top-level block)
   const driftCheck = _parseDriftCheck(mdContent);
@@ -408,7 +472,7 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // dispatcher-autonomy: opt-in cross-repo dispatcher autonomy block (Epic #673 / issue #679).
   // Parser stays pure (raw committed value) for claude-md-drift-check raw-value parity;
   // the host-local override (env > owner.yaml > committed > off) is overlaid onto the
-  // FINAL object only — mirroring the vault-dir resolveHostPath pattern above. Reuses the
+  // FINAL object only — mirroring the vault-dir host-override pattern above. Reuses the
   // already-loaded hostCtx.ownerConfig so owner.yaml is not read twice.
   const dispatcherAutonomy = _parseDispatcherAutonomy(mdContent);
   dispatcherAutonomy.autonomy = resolveDispatcherAutonomy({
@@ -552,6 +616,7 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     'resource-awareness': resourceAwareness,
     'enable-host-banner': enableHostBanner,
     'heavy-repo': heavyRepo,
+    'offload-first': offloadFirst,
     'worktree-cleanup': worktreeCleanup,
     'resource-thresholds': resourceThresholds,
     'worktree-exclude': worktreeExclude,

package/scripts/lib/eval/engine.mjs

@@ -840,6 +840,19 @@ function resolveModel(model, env, resolveModelFromEnv) {
 // Public API
 // ---------------------------------------------------------------------------
 
+/**
+ * Events window this reader needs retained (#1401 part 3): NONE FIXED, hence
+ * `null` rather than a made-up number. `evaluateSession` reads the whole
+ * ledger through `readEventsWithRotations` to score ONE named past session,
+ * arbitrarily old (`computeWindow`, #1407) — the window it needs is that
+ * session's own age, which no finite retention can be sized for. A session
+ * older than the retained ledger surfaces through `ledgerGapNote` instead.
+ * Read by `scripts/lib/events-retention-banner.mjs`.
+ *
+ * @type {number|null}
+ */
+export const REQUIRED_EVENTS_WINDOW_DAYS = null;
+
 /**
  * Evaluate one completed session against the rubric-v2 dimensions.
  *