session-orchestrator 4.0.1 → 4.2.0

package/scripts/lib/config/issue-budget.mjs

@@ -1,5 +1,6 @@
 import { matchBlockHeader } from './block-header.mjs';
 import { preprocessBlockLines } from './block-preprocess.mjs';
+import { _coerceInteger } from './coercers.mjs';
 
 /**
  * issue-budget.mjs — Parser for the `issue-budget:` block-style Session Config key.
@@ -17,10 +18,13 @@ import { preprocessBlockLines } from './block-preprocess.mjs';
  * `scripts/lib/spiral-carryover.mjs` `runCli()` (programmatic path), both via
  * `scripts/lib/issue-budget.mjs`.
  *
- * Returns `{ "max-per-session", mode, overflow }`.
- * Tolerant parser: malformed values silently fall back to defaults (the
+ * Returns `{ "max-per-session", "max-per-session-raw", mode, overflow }`.
+ * Tolerant parser: malformed values fall back to defaults (the
  * `reconcile.min-rule-days` posture, NOT the noisier handover-gate WARN) —
- * a hook must never spam stderr on every single Bash call.
+ * a hook must never spam stderr on every single Bash call. ONE exception, and
+ * it is a safety one: a malformed per-session OVERRIDE with a valid base number
+ * (`7 (feature: x)`) keeps the base 7 and WARNs on stderr, because falling back
+ * to the built-in 12 there would silently LOOSEN a cap the operator tightened.
  *
  * Consumers: `scripts/lib/config.mjs`, `scripts/lib/issue-budget.mjs`,
  * `hooks/pre-bash-issue-budget.mjs`, `skills/session-end/SKILL.md` Phase 5.
@@ -44,7 +48,9 @@ const OVERFLOW_SINKS = ['collect-issue', 'vault-note'];
  * Defaults:
  *   max-per-session: 12        integer >= 0; 0 means "no issue may be created"
  *                              (a valid, deliberately harsh setting). Malformed
- *                              or negative input falls back to 12.
+ *                              or negative input falls back to 12 — EXCEPT a
+ *                              malformed override over a valid base (`7 (x: y)`),
+ *                              which keeps 7 and WARNs.
  *   mode:            strict    strict | warn | off
  *   overflow:        collect-issue   collect-issue | vault-note
  *
@@ -54,12 +60,29 @@ const OVERFLOW_SINKS = ['collect-issue', 'vault-note'];
  *     mode: strict
  *     overflow: collect-issue
  *
+ * NEW POLICY (not a restatement of an existing rule): `max-per-session` accepts
+ * the SAME per-session-type override syntax `agents-per-wave` already uses —
+ * `12 (feature: 6)` parses via `_coerceInteger` into
+ * `{ default: 12, feature: 6 }`. The key set is OPEN (any session-type label
+ * the operator writes), because the session-type vocabulary lives in
+ * session-start, not here.
+ *
+ * The parsed override object is returned under `"max-per-session-raw"`, while
+ * `"max-per-session"` stays STRICTLY NUMERIC (the `.default`). That split is
+ * load-bearing: three consumers read the key as a number
+ * (`scripts/lib/issue-budget.mjs` `chargeIssueBudget`,
+ * `hooks/pre-bash-issue-budget.mjs`, and the config-parity docs), and handing
+ * any of them an object would surface as `[object Object]` in a cap comparison
+ * rather than as an error. Resolution against the CURRENT session type is
+ * `resolveMaxPerSession()` in `scripts/lib/issue-budget.mjs`.
+ *
  * @param {string} content — full file contents
- * @returns {{ "max-per-session": number, mode: string, overflow: string }}
+ * @returns {{ "max-per-session": number, "max-per-session-raw": number|{default: number, [k: string]: number}, mode: string, overflow: string }}
  */
 export function _parseIssueBudget(content) {
   const defaults = {
     'max-per-session': 12,
+    'max-per-session-raw': 12,
     mode: 'strict',
     overflow: 'collect-issue',
   };
@@ -84,6 +107,7 @@ export function _parseIssueBudget(content) {
   if (blockLines.length === 0) return { ...defaults };
 
   let maxPerSession = defaults['max-per-session'];
+  let maxPerSessionRaw = defaults['max-per-session-raw'];
   let mode = defaults.mode;
   let overflow = defaults.overflow;
 
@@ -101,10 +125,45 @@ export function _parseIssueBudget(content) {
     else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
 
     switch (k) {
-      case 'max-per-session':
-        // Non-negative integer only; a leading '-' fails \d+ → default.
-        if (/^\d+$/.test(v)) maxPerSession = parseInt(v, 10);
+      case 'max-per-session': {
+        // Non-negative integer, or the `N (type: M)` override form. A leading
+        // '-' fails \d+ inside `_coerceInteger`, which throws → default.
+        // Tolerant by contract: this parser runs on every Bash call via the
+        // hook, so a malformed value must fall back silently, never throw.
+        let coerced;
+        try {
+          coerced = _coerceInteger(new Map([['max-per-session', v]]), 'max-per-session', 12);
+        } catch {
+          // A malformed OVERRIDE (`7 (feature: x)`) must never restore the
+          // built-in 12: the operator wrote a base cap of 7, and discarding the
+          // whole value because the parenthesised part is unparseable LOOSENS
+          // the cap by three on one typo — silently, in the direction nobody
+          // would choose. Keep the base number, drop the override, and say so
+          // once (this branch is reachable only on a malformed value, so it
+          // cannot become per-Bash-call stderr spam).
+          const base = v.match(/^(\d+)\s*\(/);
+          if (base) {
+            const n = Number.parseInt(base[1], 10);
+            if (Number.isInteger(n) && n >= 0) {
+              maxPerSession = n;
+              maxPerSessionRaw = n;
+              process.stderr.write(
+                `⚠ issue-budget: malformed per-session override in 'max-per-session': '${v}' — ` +
+                  `kept the base cap ${n} and dropped the override.\n`,
+              );
+            }
+          }
+          break;
+        }
+        if (typeof coerced === 'number') {
+          maxPerSession = coerced;
+          maxPerSessionRaw = coerced;
+        } else if (Number.isInteger(coerced?.default) && coerced.default >= 0) {
+          maxPerSession = coerced.default;
+          maxPerSessionRaw = coerced;
+        }
         break;
+      }
 
       case 'mode':
         if (MODES.includes(v.toLowerCase())) mode = v.toLowerCase();
@@ -118,6 +177,7 @@ export function _parseIssueBudget(content) {
 
   return {
     'max-per-session': maxPerSession,
+    'max-per-session-raw': maxPerSessionRaw,
     mode,
     overflow,
   };

package/scripts/lib/config/private-config-dir.mjs

@@ -5,8 +5,9 @@
  * `owner.yaml`, the self-alias ledger) moves with it, so the precedence has to
  * live in exactly ONE place. Before #1223 three copies with three different
  * precedences existed: `owner-yaml.mjs`'s import-time homedir-only
- * `OWNER_YAML_PATH`, `owner-config-loader.mjs`'s XDG-only + untrimmed
- * `resolveOwnerConfigPath()`, and `host-identity.mjs`'s `_privateDir()`. The
+ * `OWNER_YAML_PATH`, the now-removed `owner-config-loader.mjs`'s XDG-only +
+ * untrimmed `resolveOwnerConfigPath()`, and `host-identity.mjs`'s
+ * `_privateDir()`. The
  * live consequence: `SO_CONFIG_HOME=<sandbox>` moved the alias ledger but NOT
  * owner.yaml, which kept being read from the operator's REAL home — the
  * CLAUDE.md (Codex CLI alias: AGENTS.md) "vault-dir resolves HOST-LOCALLY"

package/scripts/lib/config/remote-hosts.mjs

@@ -40,8 +40,8 @@ export const REMOTE_HOST_DEFAULTS = Object.freeze({
  * scripts/lib/config.mjs — impl / db / security / compliance / docs stay local.
  *
  * NOT the wave-role enum ("Impl-Core", "Quality", …): those are two different
- * enums and conflating them is the documented trap (see resolveApwCap's docstring
- * in wave-resource-gate.mjs). The wave→agent-mapping-role translation is
+ * enums and conflating them is the documented trap (see the MODE_BLIND_SESSION_TYPE
+ * note in wave-resource-gate.mjs). The wave→agent-mapping-role translation is
  * `OFFLOADABLE_WAVE_ROLES` in that same module.
  *
  * @type {readonly string[]}

package/scripts/lib/config-schema.mjs

@@ -86,6 +86,8 @@ export function validateSessionConfig(config) {
     });
   }
 
+  validateIssueBudget(config['issue-budget'], errors);
+
   validateVaultIntegration(config['vault-integration'], errors);
   validateVaultSync(config['vault-sync'], errors);
 
@@ -124,6 +126,83 @@ export function validateSessionConfig(config) {
   return { ok: true, config, warnings };
 }
 
+/**
+ * Validate the `issue-budget` block's cap, including the per-session-type
+ * override form (#session-shape) — `12 (feature: 6)` parses to
+ * `{ default: 12, feature: 6 }` and lands on `max-per-session-raw`, while
+ * `max-per-session` stays the resolved NUMBER every consumer reads.
+ *
+ * Mirrors `validateAgentsPerWave` in shape, with two deliberate differences:
+ * the floor is 0 (`max-per-session: 0` is a valid "no issue may be created"
+ * setting) and the override key set is free-form, because the session-type
+ * vocabulary is owned by session-start, not by this schema.
+ *
+ * @param {unknown} block — `config['issue-budget']`
+ * @param {Array<{path: string, rule: string, message: string}>} errors
+ */
+function validateIssueBudget(block, errors) {
+  if (block === undefined || block === null) return;
+  if (typeof block !== 'object' || Array.isArray(block)) {
+    errors.push({
+      path: 'issue-budget',
+      rule: 'object',
+      message: `issue-budget must be an object (got ${JSON.stringify(block)})`,
+    });
+    return;
+  }
+
+  const resolved = block['max-per-session'];
+  if (resolved !== undefined && (!Number.isInteger(resolved) || resolved < 0)) {
+    errors.push({
+      path: 'issue-budget.max-per-session',
+      rule: 'integer>=0',
+      message: `issue-budget.max-per-session must be an integer >= 0 (got ${JSON.stringify(resolved)})`,
+    });
+  }
+
+  const raw = block['max-per-session-raw'];
+  if (raw === undefined || raw === null) return;
+
+  if (Number.isInteger(raw)) {
+    if (raw < 0) {
+      errors.push({
+        path: 'issue-budget.max-per-session-raw',
+        rule: 'integer>=0',
+        message: `issue-budget.max-per-session-raw must be an integer >= 0 (got ${raw})`,
+      });
+    }
+    return;
+  }
+
+  if (typeof raw === 'object' && !Array.isArray(raw)) {
+    const defaultVal = raw['default'];
+    if (!Number.isInteger(defaultVal) || defaultVal < 0) {
+      errors.push({
+        path: 'issue-budget.max-per-session-raw.default',
+        rule: 'integer>=0',
+        message: `issue-budget.max-per-session-raw.default must be an integer >= 0 (got ${JSON.stringify(defaultVal)})`,
+      });
+    }
+    for (const [k, v] of Object.entries(raw)) {
+      if (k === 'default') continue;
+      if (!Number.isInteger(v) || v < 0) {
+        errors.push({
+          path: `issue-budget.max-per-session-raw.${k}`,
+          rule: 'integer>=0',
+          message: `issue-budget.max-per-session-raw.${k} must be an integer >= 0 (got ${JSON.stringify(v)})`,
+        });
+      }
+    }
+    return;
+  }
+
+  errors.push({
+    path: 'issue-budget.max-per-session-raw',
+    rule: 'integer-or-object',
+    message: `issue-budget.max-per-session-raw must be an integer >= 0 or an object with numeric entries (got ${JSON.stringify(raw)})`,
+  });
+}
+
 function validateAgentsPerWave(value, errors) {
   if (Number.isInteger(value)) {
     if (value < 2) {

package/scripts/lib/events.mjs

@@ -27,8 +27,8 @@
  *   3. **Never a peer's id (#1123).** A shared working copy means
  *      `session.lock` can name a PEER session that won the acquire race. The
  *      lock alone therefore does not prove ownership; the fill happens only
- *      when a PROCESS-LOCAL id (`CLAUDE_CODE_SESSION_ID`, or a hook payload's
- *      `session_id`) equals the lock's raw `session_id`. STATE.md is NOT a
+ *      when a confirmed native PROCESS-LOCAL id (`CLAUDE_CODE_SESSION_ID` or
+ *      `CODEX_THREAD_ID`) equals the lock's raw `session_id`. STATE.md is NOT a
  *      witness here (#1177 FX1): it is a shared working-copy file written by
  *      the lock holder, so under a peer-owned lock both agreed about the peer
  *      and the union stamped the peer's ids. See {@link attributionForRecord}.
@@ -124,7 +124,7 @@ const STATE_DIR_CANDIDATES = ['.claude', '.codex', '.cursor', '.pi'];
  * when one exists it decides alone.**
  *
  *   - No lock (CI, a bare script) → `{}`. Nothing to attribute to.
- *   - No process-local id (`CLAUDE_CODE_SESSION_ID` absent) → `{}`. Ownership is
+ *   - No confirmed process-local id (absent or ambiguous native env) → `{}`. Ownership is
  *     UNPROVEN, and an unproven attribution is exactly the peer-id write #1123
  *     forbids; an absent key costs a correlation, a wrong key costs a false one.
  *   - A process-local id that equals the lock's raw `session_id` → fill BOTH

package/scripts/lib/file-lock.mjs

@@ -6,11 +6,12 @@
  * and the state-lock / staging-fence / session-lock blocks of session-lock.mjs).
  * Each copy independently re-implemented the same skeleton:
  *
- *   1. atomic create-or-fail via `linkSync(tmp, lock)` (POSIX mutex);
- *   2. on EEXIST → read + parse the existing body;
- *   3. same-host + dead-PID (or unparseable) → atomic override + WARN;
- *   4. live holder OR cross-host → poll until a deadline;
- *   5. owner-guarded release.
+ *   1. exclusive acquisition guard via `linkSync(tmp, lock + '.acquire')`;
+ *   2. atomic create-or-fail via `linkSync(tmp, lock)` (POSIX mutex);
+ *   3. on EEXIST → read + parse the existing body;
+ *   4. same-host + dead-PID (or unparseable) → guarded override + WARN;
+ *   5. release the acquisition guard; live/cross-host holders wait until a deadline;
+ *   6. owner-guarded primary-lock release.
  *
  * This module is the single home for that skeleton. It is a near-PURE primitive:
  * it imports ONLY scripts/lib/io.mjs (for writeJsonAtomicSync), the two host
@@ -27,6 +28,8 @@
  *     opinion of its own — every divergence between the five copies is a knob.
  *   - Cross-host locks are NEVER auto-overridden (PSA-003 hard invariant).
  *   - Overrides always go through writeJsonAtomicSync (tmp + renameSync).
+ *   - #1284 serializes acquisition and takeover: a stale observation must not
+ *     replace a different process's newly acquired lock.
  *
  * No external dependencies — Node 20+ stdlib + io.mjs only.
  */
@@ -258,6 +261,21 @@ function serializeBody(body, indent) {
  * overridden via writeJsonAtomicSync and a WARN is emitted. A live holder or a
  * cross-host body returns `{ acquired: false, reason: 'held' }`.
  *
+ * Every acquisition pass owns the exclusive sibling `${lockPath}.acquire`
+ * from before create/read through any takeover. This prevents a waiter from
+ * reading an old holder, observing its exit, then replacing a newer holder.
+ * All contenders must use this guarded implementation; legacy writers that
+ * ignore the sibling guard cannot participate safely in the same protocol.
+ *
+ * Crash-liveness tradeoff: the guard is held only for this synchronous pass,
+ * not for the caller's critical section. If its owner dies during the pass or
+ * cleanup fails, the guard remains and attempts return `held` immediately;
+ * withFileLock's normal deadline bounds polling. Even a dead-PID or malformed
+ * guard is NEVER stolen, because stale-guard replacement would repeat the same
+ * race. Recovery requires quiescing every process that can acquire this lock,
+ * verifying the guard is abandoned, then explicitly removing only that sibling.
+ * The primary lock retains its existing stale/host/owner protections.
+ *
  * The `signalVanished` knob reproduces memory-proposals/store.mjs's distinct
  * third state: when the lock file disappears between the EEXIST and the read
  * (concurrent release race), `{ acquired: false, reason: 'vanished' }` is
@@ -284,6 +302,30 @@ function serializeBody(body, indent) {
  *   | { acquired: false, reason: 'held'|'vanished'|'fs-error', existing?: object|null, error?: string }}
  */
 export function tryAcquireFileLock(lockPath, opts = {}) {
+  const guardPath = `${lockPath}.acquire`;
+  const guard = createExclusive(guardPath, {
+    pid: process.pid,
+    host: os.hostname(),
+    acquiredAt: new Date().toISOString(),
+    kind: 'acquisition-guard',
+  }, { indent: 2, tmpPrefix: `${opts.tmpPrefix ?? '.file.lock'}.acquire` });
+  if (!guard.ok) {
+    return guard.reason === 'exists'
+      ? { acquired: false, reason: 'held', existing: null }
+      : { acquired: false, reason: 'fs-error', error: guard.error };
+  }
+
+  try {
+    return tryAcquireGuardedFileLock(lockPath, opts);
+  } finally {
+    // Only this pass can own/remove this guard; no acquisition path replaces
+    // it. An unlink failure deliberately leaves subsequent attempts blocked.
+    try { fs.unlinkSync(guardPath); } catch { /* fail closed; see recovery above */ }
+  }
+}
+
+/** Caller must hold the acquisition guard throughout this synchronous pass. */
+function tryAcquireGuardedFileLock(lockPath, opts) {
   const {
     staleCheck = 'pid',
     staleMs,