session-orchestrator 3.22.0 → 3.23.0

package/scripts/lib/issue-budget.mjs

@@ -27,16 +27,59 @@
  * Stdlib only — the hook path must stay cheap enough to run on every Bash call.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { digestSha256Short } from './crypto-digest-utils.mjs';
+import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from 'node:fs';
 import path from 'node:path';
 
 import { writeJsonAtomicSync } from './io.mjs';
 import { resolveInstructionFile } from './common.mjs';
 import { _parseIssueBudget } from './config/issue-budget.mjs';
 
-/** Runtime counter file, relative to the repo root. */
+/**
+ * Legacy single-slot counter file, relative to the repo root.
+ *
+ * Kept as the path for IDENTITY-LESS callers only, and as the one-time
+ * migration source for a session whose spend was recorded before #1141.
+ */
 export const BUDGET_STATE_REL = '.orchestrator/runtime/issue-budget.json';
 
+/** Directory holding the per-session counter files, relative to the repo root. */
+export const BUDGET_STATE_DIR_REL = '.orchestrator/runtime/issue-budget';
+
+/**
+ * Relative path of the counter file for one accounting session (#1141).
+ *
+ * WHY per session and not one file: the counter used to be ONE slot per
+ * WORKING COPY, keyed by whichever `sessionId` happened to write last, and
+ * `readBudgetState` zeroes the state whenever the file's `sessionId` differs
+ * from the reader's. Two concurrent sessions in one working copy therefore
+ * alternately reset each other's counter and BOTH ran with the cap silently
+ * off — measured 2026-08-23, where the live file was owned by a session that
+ * had started 11 h before the one reading it. Session identity belongs in the
+ * FILE NAME, not in a field the next writer overwrites.
+ *
+ * The name is a truncated SHA-256 rather than the id itself because session
+ * ids are operator/host-supplied strings: a semantic id contains `/`-free but
+ * unbounded text, and a raw id is a UUID. Hashing gives a fixed-length,
+ * filesystem-safe, path-traversal-free name for both shapes. 16 hex chars
+ * (64 bits) is far beyond the handful of sessions that ever share one working
+ * copy; revisit only if a repo ever needs the id to be readable from the name
+ * (it never has — every reader already knows which session it is).
+ *
+ * An identity-less caller (`null`/empty) keeps the legacy flat path: it never
+ * reads and never persists (see `readBudgetState` / `chargeIssueBudget`), so
+ * it needs a stable path only to NAME the store in messages.
+ *
+ * @param {string|null|undefined} sessionId accounting session key
+ * @returns {string} repo-relative path
+ */
+export function budgetStateRel(sessionId) {
+  const key = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+  if (key === null) return BUDGET_STATE_REL;
+  const digest = digestSha256Short(key, { length: 16 });
+  return `${BUDGET_STATE_DIR_REL}/${digest}.json`;
+}
+
 /**
  * Resolve the accounting key for a native session id.
  *
@@ -126,12 +169,55 @@ export function loadIssueBudgetConfig(repoRoot) {
 }
 
 /**
- * Absolute path of the runtime counter file for a repo.
+ * Absolute path of the runtime counter file for one session in a repo.
+ *
  * @param {string} repoRoot
+ * @param {string|null} [sessionId] accounting session key; omitted/empty
+ *   yields the legacy identity-less flat path.
  * @returns {string}
  */
-export function budgetStatePath(repoRoot) {
-  return path.join(repoRoot, BUDGET_STATE_REL);
+export function budgetStatePath(repoRoot, sessionId = null) {
+  return path.join(repoRoot, budgetStateRel(sessionId));
+}
+
+/**
+ * Coerce a parsed counter file into a state object, or `null` when it does not
+ * belong to `accountingSessionId`.
+ *
+ * The owner check survives the move to per-session files: the file NAME now
+ * carries identity, but a hand-edited, hash-colliding or hand-copied file must
+ * still not hand its spend to a different session.
+ *
+ * @param {unknown} data
+ * @param {string} accountingSessionId
+ * @returns {{ sessionId: string, count: number, exempt: number, overflow: object[] }|null}
+ */
+function _coerceState(data, accountingSessionId) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return null;
+  if (data.sessionId !== accountingSessionId) return null;
+  return {
+    sessionId: accountingSessionId,
+    count: Number.isInteger(data.count) && data.count >= 0 ? data.count : 0,
+    exempt: Number.isInteger(data.exempt) && data.exempt >= 0 ? data.exempt : 0,
+    overflow: Array.isArray(data.overflow) ? data.overflow : [],
+  };
+}
+
+/**
+ * Read a counter file and coerce it, swallowing every I/O and parse error
+ * (fail-open: an unreadable ledger must never block a creation).
+ *
+ * @param {string} file
+ * @param {string} accountingSessionId
+ * @returns {object|null}
+ */
+function _readStateFile(file, accountingSessionId) {
+  if (!existsSync(file)) return null;
+  try {
+    return _coerceState(JSON.parse(readFileSync(file, 'utf8')), accountingSessionId);
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -144,10 +230,18 @@ export function budgetStatePath(repoRoot) {
  * but avoiding cross-session budget and overflow attribution wins over a
  * continuity guess without a verified native identity.
  *
- * The counter file is SHARED across invocations, so this read-side isolation is
- * only half the contract: an identity-less charge must also never PERSIST its
- * fresh state, or it silently zeroes a live session's count and deletes its
- * parked overflow records. `chargeIssueBudget` enforces that write-side half.
+ * The counter file is per session since #1141, but an identity-less charge
+ * still must never PERSIST its fresh state — it would land on the shared
+ * legacy path and, before the split, silently zeroed a live session's count
+ * and deleted its parked overflow records. `chargeIssueBudget` enforces that
+ * write-side half.
+ *
+ * MIGRATION (one-time, read-only): a session that started before the per-session
+ * split has its spend in the legacy flat file. When no per-session file exists
+ * yet and the legacy file still names THIS session, seed from it — otherwise the
+ * split itself would hand every in-flight session a fresh cap, which is the very
+ * failure it exists to remove. The legacy file is never written back; the first
+ * charge after the seed persists to the per-session path.
  *
  * @param {string} repoRoot
  * @param {string|null} sessionId
@@ -159,33 +253,33 @@ export function readBudgetState(repoRoot, sessionId) {
   const fresh = { sessionId: accountingSessionId, count: 0, exempt: 0, overflow: [] };
   if (accountingSessionId === null) return fresh;
 
-  const file = budgetStatePath(repoRoot);
-  if (!existsSync(file)) return fresh;
-  try {
-    const data = JSON.parse(readFileSync(file, 'utf8'));
-    if (!data || typeof data !== 'object') return fresh;
-    if (data.sessionId !== accountingSessionId) return fresh;
-    return {
-      sessionId: accountingSessionId,
-      count: Number.isInteger(data.count) && data.count >= 0 ? data.count : 0,
-      exempt: Number.isInteger(data.exempt) && data.exempt >= 0 ? data.exempt : 0,
-      overflow: Array.isArray(data.overflow) ? data.overflow : [],
-    };
-  } catch {
-    return fresh;
-  }
+  const ownFile = budgetStatePath(repoRoot, accountingSessionId);
+  const own = _readStateFile(ownFile, accountingSessionId);
+  if (own) return own;
+  // A present-but-unusable own file is a fail-open fresh state, NOT a reason to
+  // fall back to the legacy slot — the migration seed applies only before the
+  // session has a file of its own.
+  if (existsSync(ownFile)) return fresh;
+
+  return _readStateFile(path.join(repoRoot, BUDGET_STATE_REL), accountingSessionId) ?? fresh;
 }
 
 /**
- * Persist the counter file. Best-effort: a write failure never blocks a
- * creation (fail-open), it only means the count is under-reported.
+ * Persist the counter file for `state.sessionId`. Best-effort: a write failure
+ * never blocks a creation (fail-open), it only means the count is
+ * under-reported.
+ *
+ * The target path is derived from `state.sessionId`, so a state object can only
+ * ever be written into its OWN session's slot. `writeJsonAtomicSync` mkdir -p's
+ * the containing directory (`io.mjs#atomicWriteWithBackup`), which is what
+ * creates `.orchestrator/runtime/issue-budget/` on first use.
  *
  * @param {string} repoRoot
  * @param {object} state
  * @returns {boolean} true on success
  */
 export function writeBudgetState(repoRoot, state) {
-  const res = writeJsonAtomicSync(budgetStatePath(repoRoot), state, {
+  const res = writeJsonAtomicSync(budgetStatePath(repoRoot, state?.sessionId ?? null), state, {
     tmpPrefix: '.issue-budget',
   });
   return res.ok === true;
@@ -236,7 +330,12 @@ export function chargeIssueBudget({
   const max = cfg['max-per-session'];
   const mode = cfg.mode;
   const overflowSink = cfg.overflow;
-  const overflowPath = budgetStatePath(repoRoot);
+  const accountingSessionId =
+    typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+  // Per-session store (#1141) — the path an operator or session-end must open
+  // to find THIS session's parked overflow, so the verdict has to name the
+  // session's own slot, not the directory or the legacy flat file.
+  const overflowPath = budgetStatePath(repoRoot, accountingSessionId);
 
   const base = { max, mode, overflowSink, overflowPath };
 
@@ -244,8 +343,6 @@ export function chargeIssueBudget({
     return { ...base, decision: 'off', count: 0, overflowCount: 0, reason: null };
   }
 
-  const accountingSessionId =
-    typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
   const state = readBudgetState(repoRoot, accountingSessionId);
   state.sessionId = accountingSessionId;
 
@@ -321,3 +418,105 @@ export function formatBlockReason(v) {
     `\`mode: warn\` reports without blocking, \`mode: off\` disables the gate.`,
   ].join('\n');
 }
+
+/**
+ * Default age past which a per-session counter file is reaped (#1151).
+ *
+ * BV-004 ceiling: 14 days is a "nobody will ever drain this now" horizon, not a
+ * measured retention requirement. A session's overflow is drained at ITS OWN
+ * close (session-end Phase 5 Step 3b), so a file still carrying undrained
+ * overflow two weeks later belongs to a session that ended without closing —
+ * its parked items are already unreachable by the drain, which only ever reads
+ * the CURRENT session's file. Revisit if a triage workflow ever reads a foreign
+ * session's overflow after the fact.
+ */
+export const BUDGET_REAP_MAX_AGE_DAYS = 14;
+
+/**
+ * Recognised per-session counter file name — the 16-hex digest `budgetStateRel`
+ * emits, plus `.json`. Anything else in the directory is left alone: the reaper
+ * must only ever remove files it can prove it wrote itself.
+ */
+const BUDGET_FILE_NAME_RE = /^[0-9a-f]{16}\.json$/;
+
+/**
+ * Remove stale per-session counter files (#1151).
+ *
+ * WHY: the per-session split (#1141) writes one file per accounting session
+ * into `.orchestrator/runtime/issue-budget/` and NOTHING ever removed them —
+ * there was not a single unlink site for that directory in the repo. Every
+ * session in a working copy therefore left a permanent 100-200 byte artefact
+ * behind. This is the missing other half of the file's lifecycle, owned by
+ * session-end Phase 5 Step 3b (the drain runs first, this sweeps after).
+ *
+ * Age is judged by MTIME, and the CURRENT session's file is exempt regardless
+ * of age. Both halves are safety, not convenience: a parallel session in the
+ * same working copy (PSA-001) owns a file this process did not write, and its
+ * freshly-touched mtime is the only evidence available here that the owner is
+ * still alive — the same age-gate discipline `session-registry.mjs`
+ * `sweepZombies` uses for in-flight claim files.
+ *
+ * Best-effort by contract: every failure path is swallowed and the file counted
+ * as kept. A reaper that throws would abort the session close it runs inside,
+ * which is a strictly worse outcome than an un-reaped counter file.
+ *
+ * @param {{
+ *   repoRoot: string,
+ *   sessionId?: string|null,
+ *   maxAgeDays?: number,
+ *   now?: number,
+ * }} opts `sessionId` is the accounting session id whose file must survive;
+ *   `now` is an epoch-ms injection point for tests.
+ * @returns {{ removed: string[], kept: string[] }} absolute paths, so a caller
+ *   gets both a count (`.length`) and an audit trail.
+ */
+export function reapStaleBudgetFiles({
+  repoRoot,
+  sessionId = null,
+  maxAgeDays = BUDGET_REAP_MAX_AGE_DAYS,
+  now = Date.now(),
+} = {}) {
+  const removed = [];
+  const kept = [];
+  try {
+    const dir = path.join(repoRoot, BUDGET_STATE_DIR_REL);
+    const cutoff = now - maxAgeDays * 24 * 60 * 60 * 1000;
+    const ownFile =
+      typeof sessionId === 'string' && sessionId.length > 0
+        ? budgetStatePath(repoRoot, sessionId)
+        : null;
+
+    let names;
+    try {
+      names = readdirSync(dir);
+    } catch {
+      // No directory yet (or unreadable) — nothing to reap, not an error.
+      return { removed, kept };
+    }
+
+    for (const name of names) {
+      // Unrecognised entries are not part of this reaper's population at all:
+      // neither removed nor reported as kept.
+      if (!BUDGET_FILE_NAME_RE.test(name)) continue;
+      const file = path.join(dir, name);
+      if (file === ownFile) {
+        kept.push(file);
+        continue;
+      }
+      try {
+        if (statSync(file).mtimeMs >= cutoff) {
+          kept.push(file);
+          continue;
+        }
+        unlinkSync(file);
+        removed.push(file);
+      } catch {
+        // Vanished under us (a peer's own reaper), or permission-denied.
+        kept.push(file);
+      }
+    }
+  } catch {
+    // Unreachable in practice; the contract is "never throws", not "never fails".
+  }
+  return { removed, kept };
+}

package/scripts/lib/learnings/io.mjs

@@ -42,10 +42,20 @@ import {
  * append touches disk, so a bad write can never reach the file.
  *
  * @param {object} validated — already validated+normalized learning entry
+ * @param {{ legacyTolerant?: boolean }} [opts] — GitLab #386. When `true`,
+ *   a field that was ALREADY ABSENT on `validated` (e.g. a legacy record with
+ *   no `source_session`, tolerated by `readLearnings()`) stays tolerated after
+ *   the round-trip too — the re-validation call below runs in the same
+ *   tolerant mode. This does NOT weaken the #662 guarantee: a key that WAS
+ *   present on `validated` (even `undefined`) and is no longer a key on the
+ *   reparsed object is genuine JSON.stringify corruption, detected by the
+ *   dedicated `droppedKeys` check below and thrown regardless of
+ *   `legacyTolerant`. Default `false` — `appendLearning`'s single-record path
+ *   calls this with no options and is unaffected.
  * @returns {string} the verified JSONL line (newline-terminated)
  * @throws {ValidationError} when the serialized line does not round-trip
  */
-function serializeLearningLineChecked(validated) {
+function serializeLearningLineChecked(validated, { legacyTolerant = false } = {}) {
   let line;
   try {
     line = JSON.stringify(validated);
@@ -66,9 +76,23 @@ function serializeLearningLineChecked(validated) {
       `serialized learning line does not parse back as JSON: ${err.message}`
     );
   }
+  if (legacyTolerant) {
+    // A key that existed on `validated` (present, even as `undefined`) but
+    // vanished from `reparsed` was DROPPED by JSON.stringify — the exact
+    // undefined/NaN/etc. corruption #662 exists to catch. A key that was
+    // never on `validated` in the first place (the #386 legacy-field case)
+    // cannot appear here, because we only iterate `validated`'s own keys.
+    const droppedKeys = Object.keys(validated).filter((k) => !(k in reparsed));
+    if (droppedKeys.length > 0) {
+      throw new ValidationError(
+        `learning lost field(s) during JSON round-trip serialization ` +
+          `(non-serializable value?): ${droppedKeys.join(', ')}`
+      );
+    }
+  }
   // Re-validate the round-tripped shape — catches required fields that were
-  // present as `undefined`/`NaN` before stringify but vanished after.
-  validateLearning(reparsed);
+  // present as `undefined`/`NaN` before stringify but vanished/coerced after.
+  validateLearning(reparsed, { legacyTolerant });
   return line + '\n';
 }
 
@@ -203,29 +227,50 @@ async function rotateBackups(dir, baseName, keep = BACKUP_KEEP) {
  * - `backup` (default `true`): before the destructive rename, copy the current
  *   file to `${filePath}.bak-<ISO>`, then rotate to keep only the newest
  *   {@link BACKUP_KEEP}. Rotation is best-effort and never blocks the rewrite.
+ * - `legacyTolerant` (default `true`, GitLab #386): this function is a
+ *   ROUND-TRIP writer — its usual caller (`sweepExpiredLearnings` /
+ *   `pruneLearnings` in `expiry-sweep.mjs`) reads the store with
+ *   `readLearnings()` first, and that reader already tolerates a legacy
+ *   record missing e.g. `source_session` (WARN, pass through unchanged — see
+ *   `normalizeLearning`). Before this option existed, `rewriteLearnings()`
+ *   re-validated with the SAME strict gate `appendLearning()` uses for a
+ *   brand-new single record, so re-writing the unchanged KEEP batch of a
+ *   mechanical sweep could throw on data the reader itself had just accepted
+ *   — `sweep-expired-learnings --apply` failed on ANY store holding one such
+ *   record, even though the sweep never touches that record's fields. The
+ *   default is `true` precisely because the sweep/prune call sites cannot be
+ *   changed to opt in explicitly without touching `expiry-sweep.mjs`, which
+ *   passes no `legacyTolerant`; every field that genuinely CANNOT survive a
+ *   round-trip (a value JSON.stringify drops or coerces, e.g. `undefined`/
+ *   `NaN`) is still caught by the #662 checked serializer regardless of this
+ *   flag — see {@link serializeLearningLineChecked}. Pass `false` to restore
+ *   the pre-#386 fully-strict behaviour.
  *
  * @param {string} filePath
  * @param {object[]} entries
- * @param {{dryRun?: boolean, backup?: boolean}} [opts]
+ * @param {{dryRun?: boolean, backup?: boolean, legacyTolerant?: boolean}} [opts]
  * @returns {Promise<object[]>} validated entries (always returned, even dryRun)
  */
 export async function rewriteLearnings(
   filePath,
   entries,
-  { dryRun = false, backup = true } = {}
+  { dryRun = false, backup = true, legacyTolerant = true } = {}
 ) {
   const validated = entries.map((e) =>
-    validateLearning({
-      ...e,
-      schema_version: e?.schema_version ?? CURRENT_SCHEMA_VERSION,
-    })
+    validateLearning(
+      {
+        ...e,
+        schema_version: e?.schema_version ?? CURRENT_SCHEMA_VERSION,
+      },
+      { legacyTolerant }
+    )
   );
   // Pre-write round-trip self-validation (#662): serialize ALL entries through
   // the checked serializer before touching disk — a single bad entry throws
   // ValidationError and the file is left untouched (atomicity preserved because
   // we validate the full batch first, then write once). This runs even under
   // dryRun, so an invalid entry is still rejected on a dry probe.
-  const lines = validated.map((e) => serializeLearningLineChecked(e));
+  const lines = validated.map((e) => serializeLearningLineChecked(e, { legacyTolerant }));
 
   // dryRun (#721): validation has run; deliberately do NOT touch disk — no
   // rewrite, no backup — and hand the validated entries back to the caller.

package/scripts/lib/learnings/schema.mjs

@@ -59,7 +59,7 @@ export const CURRENT_ANONYMIZATION_VERSION = 1;
 
 /**
  * Type capability registry (Epic #723 I1, issue #733 Teil b) — the single
- * source of truth for every learning `type`'s TTL policy AND its two
+ * source of truth for every learning `type`'s TTL policy AND its three
  * cross-module capability axes. Before this registry existed, three modules
  * independently hand-maintained overlapping type lists that drifted out of
  * sync (`memory-proposals/schema.mjs` PROPOSAL_TYPES, `reconcile/eligibility.mjs`
@@ -76,39 +76,54 @@ export const CURRENT_ANONYMIZATION_VERSION = 1;
  *   - ruleConvertible:  may appear in `reconcile/eligibility.mjs` CONVERT_TYPES
  *                       (i.e. the reconcile engine may convert this type into a
  *                       conditional `.claude/rules/*.md` rule proposal).
+ *   - hostScoped:       this type's content is genuinely chip/OS-specific, so
+ *                       `reconcile/emitter.mjs` may copy a record's `host_class`
+ *                       through as the emitted rule's `host-class` activation
+ *                       axis (issue #1090; derived set: that module's
+ *                       HOST_SPECIFIC_TYPES). `false` for every general finding,
+ *                       whose `host_class` merely records the machine it was
+ *                       authored on and must never gate the rule.
+ *
+ * Every entry declares every axis explicitly — an omitted flag would read as
+ * `undefined` (falsy) and silently opt a new type out of a capability without
+ * anyone deciding that. Guarded by a test in
+ * `tests/lib/learnings-schema-normalization.test.mjs`.
  */
 export const LEARNING_TYPE_REGISTRY = Object.freeze({
-  'mode-selector-accuracy':      Object.freeze({ ttlDays: 30, agentProposable: true,  ruleConvertible: false }),
-  'hardware-pattern':            Object.freeze({ ttlDays: 60, agentProposable: true,  ruleConvertible: false }),
-  'fragile-file':                Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: true  }),
-  'effective-sizing':            Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: false }),
-  'recurring-issue':             Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: true  }),
+  'mode-selector-accuracy':      Object.freeze({ ttlDays: 30, agentProposable: true,  ruleConvertible: false, hostScoped: false }),
+  // hardware-pattern is the ONLY hostScoped type today: its content IS the
+  // chip/OS, so gating the emitted rule by host-class is faithful rather than
+  // an accidental one-machine restriction (#1090).
+  'hardware-pattern':            Object.freeze({ ttlDays: 60, agentProposable: true,  ruleConvertible: false, hostScoped: true  }),
+  'fragile-file':                Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
+  'effective-sizing':            Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: false, hostScoped: false }),
+  'recurring-issue':             Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
   // workflow-pattern / proven-pattern: flipped ruleConvertible false->true
   // (issue #900) — the real corpus census showed a large volume of live
   // `workflow-pattern`/`proven-pattern` records (post type-alias-normalization,
   // see LEARNING_TYPE_ALIASES below) that carried usable file_paths but were
   // structurally unconvertible before this flip.
-  'workflow-pattern':            Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
-  'proven-pattern':              Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
-  'anti-pattern':                Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
-  'autopilot-effectiveness':     Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: false }),
+  'workflow-pattern':            Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
+  'proven-pattern':              Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
+  'anti-pattern':                Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
+  'autopilot-effectiveness':     Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: false, hostScoped: false }),
   // autonomy-verdict (#683): repo/scope readiness synthesis from autopilot
   // effectiveness plus skill-judge signals. 90d matches the operational
   // autopilot-effectiveness horizon it depends on. Analyzer-only — never
   // agent-proposable.
-  'autonomy-verdict':            Object.freeze({ ttlDays: 90, agentProposable: false, ruleConvertible: false }),
+  'autonomy-verdict':            Object.freeze({ ttlDays: 90, agentProposable: false, ruleConvertible: false, hostScoped: false }),
   // domain-regression (#638): a sidecar-sourced regression flag (metric baseline→recent
   // delta) surfaced via /evolve extra-sources. 60d aligns with the moderate-decay tier
   // (hardware-pattern / default) — a regression signal should age out if it stops recurring.
-  'domain-regression':           Object.freeze({ ttlDays: 60, agentProposable: true,  ruleConvertible: false }),
-  'convention':                  Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
-  'architecture-pattern':        Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
-  'design-pattern':              Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
+  'domain-regression':           Object.freeze({ ttlDays: 60, agentProposable: true,  ruleConvertible: false, hostScoped: false }),
+  'convention':                  Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
+  'architecture-pattern':        Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
+  'design-pattern':              Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
   // fragile-pattern / stagnation-class-frequency: 0 live instances as of
   // 2026-07-02 (see reconcile/eligibility.mjs census) — CONVERT-eligible but
   // NOT agent-proposable (analyzer-synthesized classes, not agent-observed).
-  'fragile-pattern':             Object.freeze({ ttlDays: 45, agentProposable: false, ruleConvertible: true  }),
-  'stagnation-class-frequency':  Object.freeze({ ttlDays: 60, agentProposable: false, ruleConvertible: true  }),
+  'fragile-pattern':             Object.freeze({ ttlDays: 45, agentProposable: false, ruleConvertible: true,  hostScoped: false }),
+  'stagnation-class-frequency':  Object.freeze({ ttlDays: 60, agentProposable: false, ruleConvertible: true,  hostScoped: false }),
 });
 
 /**
@@ -215,47 +230,99 @@ export class ValidationError extends Error {
  * Throws ValidationError on contract violations. Does NOT mutate input.
  *
  * @param {object} entry — candidate learning
+ * @param {{ legacyTolerant?: boolean }} [opts] — GitLab #386. When `true`, a
+ *   value `normalizeLearning()` already passes through UNCHECKED (or merely
+ *   DEFAULTED, never validated) on read is no longer rejected here either:
+ *   an out-of-enum `schema_version` (measured against the real EventDrop.at
+ *   store: 3 live records carry `schema_version: 2`), the
+ *   LEGACY_REQUIRED_FIELDS presence check, the `confidence` range/type check
+ *   when NO `confidence` key is present, and the `scope`/`host_class`/
+ *   `anonymized` shape checks (measured live: a record with `scope:
+ *   "src/components/landing/mobile-sticky-cta.tsx"` — a producer bug that
+ *   wrote a file path into the scope column, which `normalizeLearning` never
+ *   validates and therefore never rejects). A field that IS present keeps
+ *   being validated regardless when its DATA TYPE can be silently corrupted
+ *   by a JSON round-trip (a present-but-malformed `confidence` still throws
+ *   — see io.mjs #662): this option relaxes "you must HAVE a valid value",
+ *   never "if a round-trip could have silently mangled it, that's fine too".
+ *   The privacy CONTRACT (`scope: 'public'` requiring `anonymized`/
+ *   `host_class` to be consistent) is NEVER relaxed — it only ever fires for
+ *   a record that genuinely claims `scope: 'public'`, which is exactly the
+ *   case a round-trip must not silently launder. Default `false` — every
+ *   existing direct caller (including `appendLearning`'s single-record write
+ *   path) is unaffected.
  * @returns {object} normalized entry with scope/host_class/anonymized defaulted
  */
-export function validateLearning(entry) {
+export function validateLearning(entry, { legacyTolerant = false } = {}) {
   if (!entry || typeof entry !== 'object') {
     throw new ValidationError('learning must be an object');
   }
 
   // schema_version: 0 (implicit/legacy), 1 (current). Both accepted.
+  // `normalizeLearning()` never validates this value on read (any value
+  // passes through as-is), so under legacyTolerant an ABSENT schema_version
+  // (defaults to the valid `0`) or one already present with SOME value is
+  // both fine — only a truly missing-AND-invalid combination cannot occur
+  // (missing defaults to 0, which is always valid), so in practice this skips
+  // the check whenever legacyTolerant is set and a non-legacy value survived
+  // a prior read (e.g. `schema_version: 2`, measured live in production).
   const schemaVersion = entry.schema_version ?? 0;
-  if (schemaVersion !== 0 && schemaVersion !== 1) {
+  if (!legacyTolerant && schemaVersion !== 0 && schemaVersion !== 1) {
     throw new ValidationError(
       `schema_version must be 0 (legacy) or 1, got: ${schemaVersion}`
     );
   }
 
-  for (const field of LEGACY_REQUIRED_FIELDS) {
-    if (!(field in entry)) {
-      throw new ValidationError(`learning missing required field: ${field}`);
+  if (!legacyTolerant) {
+    for (const field of LEGACY_REQUIRED_FIELDS) {
+      if (!(field in entry)) {
+        throw new ValidationError(`learning missing required field: ${field}`);
+      }
     }
   }
 
-  if (typeof entry.confidence !== 'number' || entry.confidence < 0 || entry.confidence > 1) {
-    throw new ValidationError(`confidence must be a number in [0, 1], got: ${entry.confidence}`);
+  // confidence carries its own type/range check in addition to the presence
+  // loop above, so it needs its own legacyTolerant gate: skip ONLY when the
+  // key is genuinely absent (mirrors the presence loop); a present-but-bad
+  // value (wrong type, out of range, or `null` after a JSON round-trip
+  // coerced a non-serializable value — see io.mjs #662) still throws under
+  // legacyTolerant, same as under strict mode.
+  if (!legacyTolerant || 'confidence' in entry) {
+    if (typeof entry.confidence !== 'number' || entry.confidence < 0 || entry.confidence > 1) {
+      throw new ValidationError(`confidence must be a number in [0, 1], got: ${entry.confidence}`);
+    }
   }
 
+  // scope/host_class/anonymized: `normalizeLearning()` only DEFAULTS an
+  // absent value (`d.scope ?? 'local'`, etc.) on read — it never validates a
+  // PRESENT one, so a corrupt legacy value round-trips silently today
+  // (measured live in production: a record with `scope:
+  // "src/components/landing/mobile-sticky-cta.tsx"` — evidently a producer
+  // bug that wrote a file path into the scope column). All three checks are
+  // therefore skipped under legacyTolerant. Unlike `confidence` (a number,
+  // where `NaN`/`Infinity` are non-JSON-safe and silently become `null`
+  // across a JSON round-trip — the #662 concern), a string/string-or-null/
+  // boolean value round-trips through JSON byte-for-byte, so there is no
+  // corresponding round-trip-corruption risk to guard against here.
   const scope = entry.scope ?? 'local';
-  if (!VALID_SCOPES.includes(scope)) {
+  if (!legacyTolerant && !VALID_SCOPES.includes(scope)) {
     throw new ValidationError(`scope must be one of ${VALID_SCOPES.join('|')}, got: ${scope}`);
   }
 
   const hostClass = entry.host_class ?? null;
-  if (hostClass !== null && typeof hostClass !== 'string') {
+  if (!legacyTolerant && hostClass !== null && typeof hostClass !== 'string') {
     throw new ValidationError(`host_class must be string or null, got: ${typeof hostClass}`);
   }
 
   const anonymized = entry.anonymized ?? false;
-  if (typeof anonymized !== 'boolean') {
+  if (!legacyTolerant && typeof anonymized !== 'boolean') {
     throw new ValidationError(`anonymized must be boolean, got: ${typeof anonymized}`);
   }
 
-  // Privacy contract
+  // Privacy contract — NEVER relaxed, legacyTolerant or not: an out-of-enum
+  // `scope` (garbage or otherwise) is by definition not `'public'`, so this
+  // pair only ever fires for a record that genuinely claims `scope: 'public'`
+  // — exactly the case a round-trip must not silently launder.
   if (scope === 'public' && !anonymized) {
     throw new ValidationError(
       'scope=public requires anonymized=true (privacy contract violation)'

package/scripts/lib/lock-reaper.mjs

@@ -68,6 +68,7 @@ import path from 'node:path';
 import { enumerateCandidates } from './dispatcher/enumerate.mjs';
 import { readLock, isLockLive, isPidAliveOnHost, LOCK_PATH, DEFAULT_TTL_HOURS } from './session-lock.mjs';
 import { emitEvent } from './events.mjs';
+import { hostnamesMatch, lockHostCandidate } from './host-identity.mjs';
 
 const REAPED_ARCHIVE_SUBDIR = '.orchestrator/tmp/reaped-locks';
 const REAPED_EVENT = 'orchestrator.session.lock.reaped';
@@ -463,7 +464,12 @@ async function evaluateRepo(repoRoot, { nowMs, dryRun, currentSessionId, reapMod
     };
   }
 
-  const ownHost = lock.host === D.hostname();
+  // #1072: alias-aware host identity. A raw comparison classified this
+  // machine's OWN orphaned lock as cross-host after a hostname flip, so it was
+  // never reaped and every subsequent session needed operator intervention.
+  // The invariant is unchanged for a genuinely foreign host: its name was never
+  // written into this machine's self-alias ledger, so it can never match.
+  const ownHost = hostnamesMatch(lockHostCandidate(lock), D.hostname());
 
   // Invariant (c): cross-host leases are NEVER auto-reaped — only listed.
   if (!ownHost) {