session-orchestrator 3.22.0 → 3.24.0

package/scripts/lib/session-identity/own-session.mjs

@@ -0,0 +1,220 @@
+/**
+ * own-session.mjs — "which session am I, and does this shared artefact belong to me?"
+ *
+ * A working copy is shared; a session is not. Every `.orchestrator/` and
+ * `<state-dir>/` artefact in this repo is written into the WORKING COPY, so a
+ * second live session reads the first one's files as if they were its own. The
+ * damage is always invisible to the writer: a peer's corrective hints briefing
+ * this session's fixer (#1058), a peer's `allowedPaths: []` locking this
+ * session out of every write (#1082/#1123).
+ *
+ * This module is the reusable half of that check, split into two pure-ish
+ * functions so a caller can resolve identity once and classify many artefacts:
+ *
+ *   - {@link readOwnSessionIds} — every id that provably names THIS session.
+ *   - {@link classifyManifestSession} — own / foreign / unknown for a manifest.
+ *
+ * Semantics were lifted from the `current-session.json` ownership check in
+ * `scripts/lib/quality-gate.mjs` (#1058), which is module-private there and sits
+ * behind a module this repo's hook guard-source-loader cannot bind. This is a
+ * deliberate re-implementation of the SEMANTICS, not a re-export.
+ *
+ * **Only what is PROVABLY foreign is foreign.** Every unprovable case returns
+ * `'unknown'`, and every caller is expected to treat `'unknown'` exactly as it
+ * behaved before this check existed. An ownership check that guesses turns
+ * "cannot tell" into a silent feature-off on every harness that exports no
+ * session id.
+ */
+
+import { readLock } from '../session-lock.mjs';
+
+/**
+ * The set of session ids that provably name THIS session — the UNION of every
+ * tier, never the first one that answers.
+ *
+ * Three sources, all read, all merged:
+ *
+ *   1. `hookInput` — the harness's own statement about the invocation being
+ *      handled right now (`session_id` / `sessionId`, plus `parent_session_id`
+ *      for a sub-agent invocation, whose coordinator is equally us). The only
+ *      tier that is per-INVOCATION rather than per-working-copy.
+ *   2. `CLAUDE_CODE_SESSION_ID` — process-scoped, absent on harnesses that
+ *      export no session env var.
+ *   3. `session.lock` `session_id` / `semantic_session_id` — repo-GLOBAL, and
+ *      the identity the WRITER of a manifest uses: `wave-scope.json`'s
+ *      `session` field comes from `sessionAttribution()`, which reads this same
+ *      lock (`skills/wave-executor/wave-loop.md` § Scope Manifest 1).
+ *
+ * **Why the union, and not first-tier-wins.** Any id the process can
+ * legitimately claim — its own invocation, its harness env, the repo's live
+ * lock — names this session; only an id in NONE of them is somebody else's.
+ * Gating the tiers made the READER's identity a strict subset of the WRITER's,
+ * and three distinct ways of diverging all landed on the same silent failure —
+ * the OWN manifest classified `foreign`, so the write gate switched itself off
+ * for the whole wave, with an event that reads exactly like correct behaviour:
+ *
+ *   - **Nested-harness divergence.** The payload `session_id` and
+ *     `CLAUDE_CODE_SESSION_ID` disagree in a nested harness — already measured
+ *     and documented in `resolveSessionId()` of
+ *     `hooks/pre-bash-issue-budget.mjs`: *"stdin still wins: it is the id of
+ *     THIS tool call, whereas the env var is the id of the process tree, and
+ *     the two differ in a nested harness"*, alongside the measurement that the
+ *     env var equals the `session.lock` `session_id` and survives into
+ *     subagents. Under tier-gating, the payload alone decided.
+ *   - **Sub-agent invocation.** A dispatched agent's own set was
+ *     `{subagent-uuid}` while the manifest names the coordinator.
+ *     `parent_session_id` is in tier 1 too, but a payload that carries only
+ *     `session_id` still hid the coordinator's env/lock ids behind the gate.
+ *   - **Peer-owned lock.** A second session that failed to acquire the lock
+ *     (`bootstrapLock()` reason `active`, the lock keeps the PEER's id) writes
+ *     that peer id into its OWN manifest via `sessionAttribution()`. Its own
+ *     hook then read the payload tier, never reached the lock, and disarmed
+ *     itself against the manifest it had just written.
+ *
+ * **The security direction is unchanged: the union only ADDS ids this process
+ * actually carries.** A manifest whose id appears in NO tier — not the
+ * invocation, not the env, not the lock — still classifies `foreign`, exactly
+ * as before; nothing here invents an id or widens what counts as a match.
+ *
+ * The cost is named rather than hidden, and it points the fail-CLOSED way: when
+ * the lock names a peer, that peer's manifest now reads `own`, so we ENFORCE a
+ * wave plan that is not ours. That is a visible, actionable deny — the inverse
+ * of tier-gating's failure, which was a silent enforcement-off. `unknown` still
+ * means unknown: an empty set can only produce `unknown`, never a mismatch.
+ *
+ * Every value is `.trim()`ed before it enters the set: a whitespace-only env
+ * var is truthy and would otherwise enter as a PHANTOM id that matches nothing
+ * — which would make every manifest read `foreign` and switch enforcement off
+ * (`.claude/rules/development.md` § env-var whitespace trap).
+ *
+ * Never throws.
+ *
+ * @param {string} repoRoot — working copy root, for the `session.lock` tier.
+ * @param {{ hookInput?: object|null }} [opts]
+ * @returns {Set<string>} possibly EMPTY — an empty set means "identity
+ *   unresolvable", which {@link classifyManifestSession} treats as `unknown`,
+ *   never as a mismatch.
+ */
+export function readOwnSessionIds(repoRoot, { hookInput = null } = {}) {
+  const ids = new Set();
+  const add = (value) => {
+    const trimmed = typeof value === 'string' ? value.trim() : '';
+    if (trimmed) ids.add(trimmed);
+  };
+
+  // Source 1 — the harness's statement about THIS invocation.
+  if (hookInput && typeof hookInput === 'object') {
+    for (const key of ['session_id', 'sessionId', 'parent_session_id']) add(hookInput[key]);
+  }
+
+  // Source 2 — process-scoped env var.
+  add(process.env.CLAUDE_CODE_SESSION_ID);
+
+  // Source 3 — repo-global lock file (the manifest writer's own identity).
+  try {
+    const lock = readLock({ repoRoot });
+    for (const key of ['session_id', 'semantic_session_id']) add(lock?.[key]);
+  } catch {
+    /* readLock never throws by contract, but that contract is not ours to trust */
+  }
+  return ids;
+}
+
+/**
+ * The ids that name this session and are PROCESS-LOCAL — tiers 1 and 2 only,
+ * never the lock and never STATE.md.
+ *
+ * A sibling of {@link readOwnSessionIds}, not a replacement: the two answer
+ * different questions and the difference is the whole point.
+ *
+ *   - `readOwnSessionIds()` answers *"could this id name me?"* and unions three
+ *     tiers, the third of which IS `session.lock`. That union is correct when
+ *     the thing being classified was written by some OTHER process (a wave-scope
+ *     manifest), because every id this process can legitimately claim counts.
+ *   - This function answers *"which process is emitting right now?"*, and for
+ *     that question the lock is **vacuous**: when the candidate ids under
+ *     judgement are the lock's OWN values, a membership test against a set that
+ *     contains the lock matches by construction — a peer-owned lock would
+ *     classify as `own` 100% of the time.
+ *
+ * **STATE.md is excluded for the same reason, and this is the #1177-FX1 fix.**
+ * `.claude/STATE.md` is a SHARED working-copy artefact written by whichever
+ * session owns the working copy — normally the lock holder. So when a peer holds
+ * the lock, the peer also wrote STATE.md, and the two "independent" witnesses
+ * agree with each other about the PEER. Unioning a shared-file witness with a
+ * process-local one lets the weaker witness carry the verdict while a
+ * disagreeing process-local id cannot veto it (measured: lock=peer +
+ * STATE.md=peer + `CLAUDE_CODE_SESSION_ID`=me stamped the PEER's ids). Tiering
+ * rather than unioning is the fix — a better signal REPLACES a worse one
+ * (`.claude/rules/host-resources.md` § HR-102).
+ *
+ * Never throws.
+ *
+ * @param {{ env?: object, hookInput?: object|null }} [opts]
+ * @param {object} [opts.env=process.env] — injectable for tests.
+ * @param {object|null} [opts.hookInput=null] — the harness's statement about
+ *   THIS invocation, when the caller is a hook.
+ * @returns {string[]} possibly EMPTY — an empty result means "this process
+ *   cannot prove who it is", which callers must treat as unprovable rather
+ *   than as a match.
+ */
+export function readProcessLocalSessionIds({ env = process.env, hookInput = null } = {}) {
+  const ids = [];
+  const add = (value) => {
+    const trimmed = typeof value === 'string' ? value.trim() : '';
+    if (trimmed && !ids.includes(trimmed)) ids.push(trimmed);
+  };
+
+  // Tier 1 — the harness's statement about THIS invocation.
+  if (hookInput && typeof hookInput === 'object') {
+    for (const key of ['session_id', 'sessionId', 'parent_session_id']) add(hookInput[key]);
+  }
+  // Tier 2 — process-scoped env var.
+  add(env?.CLAUDE_CODE_SESSION_ID);
+
+  return ids;
+}
+
+/**
+ * Decide whether a wave-scope manifest belongs to THIS session.
+ *
+ * Three outcomes, and the middle one is load-bearing:
+ *
+ *   - `'foreign'` — the manifest names at least one session id, we know at
+ *     least one of our own, and NONE of them match. The only verdict that
+ *     changes behaviour.
+ *   - `'unknown'` — the manifest names no id (a legacy manifest written before
+ *     the `session` field existed), or we could not resolve our own. Ownership
+ *     is unproven in BOTH directions, so the caller must keep doing exactly
+ *     what it did before.
+ *   - `'own'` — an id matched.
+ *
+ * Both id fields are consulted because they address the same session under two
+ * naming schemes: `session` is the raw harness session id (a UUID on Claude
+ * Code), `semantic_session` the `<branch>-<date>-<mode>-<n>` form. A harness
+ * that resolves only the semantic one must still recognise its own manifest.
+ *
+ * @param {unknown} scope — parsed wave-scope manifest (any shape; a non-object
+ *   simply yields no ids, hence `'unknown'`).
+ * @param {Set<string>} ownIds — from EITHER producer, depending on what is
+ *   being judged: {@link readOwnSessionIds} when every id this process could
+ *   legitimately claim counts, or `new Set(`{@link readProcessLocalSessionIds}
+ *   `(...))` when the lock tier would match vacuously — which is the case for a
+ *   wave-scope manifest in a checkout shared by two sessions (#1194). Note the
+ *   latter returns a `string[]`: a bare array is NOT a Set and folds to the
+ *   empty set below, yielding `'unknown'` for every manifest.
+ * @returns {{ verdict: 'own'|'foreign'|'unknown', manifestIds: string[] }}
+ */
+export function classifyManifestSession(scope, ownIds) {
+  const manifestIds = [];
+  if (scope && typeof scope === 'object' && !Array.isArray(scope)) {
+    for (const key of ['session', 'semantic_session']) {
+      const value = typeof scope[key] === 'string' ? scope[key].trim() : '';
+      if (value) manifestIds.push(value);
+    }
+  }
+  const own = ownIds instanceof Set ? ownIds : new Set();
+  if (manifestIds.length === 0 || own.size === 0) return { verdict: 'unknown', manifestIds };
+  const matched = manifestIds.some((id) => own.has(id));
+  return { verdict: matched ? 'own' : 'foreign', manifestIds };
+}

package/scripts/lib/session-lock.mjs

@@ -45,6 +45,7 @@ import crypto from 'node:crypto';
 import { classifyMode } from './exclusivity-matrix.mjs';
 import { isPidAliveOnHost } from './file-lock.mjs';
 import { writeJsonAtomicSync } from './io.mjs';
+import { hostnamesMatch, lockHostCandidate, recordHostAlias, stableHostname } from './host-identity.mjs';
 
 // isPidAliveOnHost moved into file-lock.mjs in #630 (the file-lock primitive
 // owns it so the dependency edge points file-lock → io, never the reverse).
@@ -101,11 +102,12 @@ export const OWNER_PROOF_RELPATH = '.orchestrator/runtime/lock-owner-proof.json'
 // NOT the discovery-path liveness check — since Epic #583 the discovery
 // decision tree uses heartbeat-age via {@link isLockLive} instead, because the
 // `pid` recorded on a session.lock is the *ephemeral hook subprocess* PID.
-// Same-host callers (`acquire`, `checkStale`, and the state-lock /
-// staging-fence stale-override paths, now via the file-lock primitive) use it
-// only for the short-lived stale-override path where the recorded PID IS the
-// live writer's PID. See file-lock.mjs for the full @forensic + PID-recycle
-// trade-off note.
+// NOTHING IN THIS MODULE CALLS IT any more: `acquire()` stopped consulting the
+// pid in #744/#1137 and `checkStale()` in #1151 — the re-export is a
+// compatibility surface for external importers only. The remaining production
+// callers are file-lock.mjs's own stale-override path and lock-reaper.mjs,
+// where the recorded PID IS the process being asked about. See file-lock.mjs
+// for the full @forensic + PID-recycle trade-off note.
 
 /**
  * Resolve the absolute path to the lock file.
@@ -146,6 +148,28 @@ function lockAgeHours(lock) {
   return (Date.now() - ts) / (3600 * 1000);
 }
 
+/**
+ * Compute the age of a lock's heartbeat in fractional minutes.
+ *
+ * This is the diagnostic counterpart to `isLockLive()` — the SAME quantity the
+ * liveness rule thresholds against, surfaced as a number so callers (the
+ * Phase-1.2 stale-lock AUQ, recovery diagnostics) can report WHY a lock was
+ * classified stale instead of asserting a PID verdict the lock cannot support
+ * (#1137). Mirrors `isLockLive()`'s `last_heartbeat` → `started_at` fallback.
+ *
+ * @param {{ last_heartbeat?: string, started_at?: string }} lock
+ * @returns {number|null} minutes since the last heartbeat, or null if unparseable.
+ */
+function heartbeatAgeMinutes(lock) {
+  if (!lock || typeof lock !== 'object') return null;
+  const hbStr = (typeof lock.last_heartbeat === 'string' && lock.last_heartbeat.length > 0)
+    ? lock.last_heartbeat
+    : lock.started_at;
+  const ts = Date.parse(hbStr);
+  if (Number.isNaN(ts)) return null;
+  return (Date.now() - ts) / (60 * 1000);
+}
+
 /**
  * Parse lock file contents into an object. Returns null on any parse error.
  *
@@ -213,13 +237,22 @@ function parseLock(raw) {
  */
 function buildLock({ sessionId, mode, ttlHours, semanticSessionId }) {
   const startedAt = nowIso();
+  // Writing a session lock is the one moment we KNOW the current os.hostname()
+  // belongs to this machine — record it so a later reading under a different
+  // spelling can still be recognised as the same host (#1072). Best-effort:
+  // recordHostAlias never throws, and a failed write only costs the alias.
+  recordHostAlias();
   const lock = {
     session_id: sessionId,
     started_at: startedAt,
     last_heartbeat: startedAt,
     mode,
     pid: process.pid,
+    // `host` stays the RAW hostname — it is an on-the-wire event field
+    // (orchestrator.session.lock.acquired) and feeds the privacy-hash contract.
+    // `host_id` is the additive normalised twin every comparison reads (#1072).
     host: os.hostname(),
+    host_id: stableHostname(),
     ttl_hours: ttlHours,
   };
   if (typeof semanticSessionId === 'string' && semanticSessionId.length > 0) {
@@ -455,10 +488,15 @@ export function readLockDetailed(opts = {}) {
  *       — lock created
  *   { ok: false, reason: 'active', existingLock, exclusivityClass? }
  *       — local lock held (live TTL, live PID)
- *   { ok: false, reason: 'stale-pid-dead', existingLock, exclusivityClass? }
- *       — local lock stale (dead PID)
- *   { ok: false, reason: 'stale-pid-alive', existingLock, exclusivityClass? }
- *       — local lock stale (live PID, TTL expired)
+ *   { ok: false, reason: 'stale-heartbeat', existingLock, ageHours, heartbeatAgeMinutes, exclusivityClass? }
+ *       — local lock stale: its last_heartbeat is older than ttl_hours. This is
+ *         the ONLY stale reason (#1137). It replaced the `stale-pid-dead` /
+ *         `stale-pid-alive` pair, which claimed a PID verdict the lock cannot
+ *         support: the recorded `pid` is the ephemeral hook / `node -e`
+ *         subprocess, dead within ~1s of genesis (measured 2026-08-23: 7 of 7
+ *         recorded pids dead, INCLUDING the currently heartbeating session's
+ *         own lock), so `stale-pid-alive` was unreachable same-host and every
+ *         stale lock rendered as "confirmed dead" in the recovery AUQ.
  *   { ok: false, reason: 'fs-error', error, exclusivityClass? }
  *       — filesystem failure
  *   { ok: false, reason: 'active-incompatible-exclusive', allActiveSessions, blockingSession, exclusivityClass }
@@ -563,12 +601,8 @@ export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoo
   try {
     // Classify an existing lock into the correct failure result. Shared by the
     // up-front readLock() check AND the create-race EEXIST-loser path below so
-    // both report identical active / stale-pid-dead / stale-pid-alive reasons.
+    // both report identical active / stale-heartbeat reasons.
     const classifyExisting = (existing) => {
-      const sameHost = existing.host === os.hostname();
-      // PID liveness is only meaningful on the same host.
-      const pidAlive = sameHost ? isPidAliveOnHost(existing.pid) : null;
-
       // Heartbeat-first liveness (#744): isLockLive is the SOLE active gate.
       // A dead recorded PID must NOT veto a fresh last_heartbeat — the pid on
       // a session.lock is the ephemeral hook subprocess PID, not the semantic
@@ -581,11 +615,24 @@ export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoo
         return { ok: false, reason: 'active', existingLock: existing, exclusivityClass: callerClass };
       }
 
-      // Heartbeat expired — classify the stale variant. Cross-host locks never
-      // have a confirmable dead PID (pidAlive stays null), so they always land
-      // on 'stale-pid-alive' rather than 'stale-pid-dead'.
-      const reason = (pidAlive === false) ? 'stale-pid-dead' : 'stale-pid-alive';
-      return { ok: false, reason, existingLock: existing, exclusivityClass: callerClass };
+      // Heartbeat expired — ONE stale reason, derived from the same signal the
+      // active gate above used (#1137). The former two-way split asked
+      // isPidAliveOnHost(existing.pid) and reported 'stale-pid-dead' /
+      // 'stale-pid-alive'; that question has no answer the lock can give,
+      // because `pid` is the short-lived writer subprocess, not the session.
+      // Same-host it was therefore ~always 'dead' (7/7 measured, live sessions
+      // included) and 'stale-pid-alive' was structurally unreachable. The
+      // ageHours + heartbeatAgeMinutes fields carry the evidence instead, so a
+      // recovery prompt can state the measured heartbeat age rather than a
+      // liveness verdict.
+      return {
+        ok: false,
+        reason: 'stale-heartbeat',
+        existingLock: existing,
+        ageHours: lockAgeHours(existing),
+        heartbeatAgeMinutes: heartbeatAgeMinutes(existing),
+        exclusivityClass: callerClass,
+      };
     };
 
     const existing = readLock({ repoRoot });
@@ -978,7 +1025,7 @@ export function updateHeartbeat({ repoRoot, sessionId } = {}) {
  *   lock: object|null,
  *   ageHours: number|null,
  *   ttlExpired: boolean,
- *   pidAlive: boolean|null,
+ *   heartbeatAgeMinutes: number|null,
  *   host: string|null,
  *   sameHost: boolean,
  *   isLive: boolean
@@ -993,7 +1040,7 @@ export function checkStale({ repoRoot } = {}) {
       lock: null,
       ageHours: null,
       ttlExpired: false,
-      pidAlive: null,
+      heartbeatAgeMinutes: null,
       host: null,
       sameHost: false,
       isLive: false,
@@ -1002,14 +1049,22 @@ export function checkStale({ repoRoot } = {}) {
 
   const ageHours = lockAgeHours(lock);
   const ttlExpired = isTtlExpired(lock);
-  const sameHost = lock.host === os.hostname();
-  // Only attempt PID check when the lock was written on this machine.
-  const pidAlive = sameHost ? isPidAliveOnHost(lock.pid) : null;
-  // Heartbeat-based liveness (#744) — additive field alongside the pre-existing
-  // ttlExpired/pidAlive/sameHost fields (back-compat). This is the SAME check
-  // acquire()'s classifyExisting now uses as its sole active gate, surfaced
-  // here so callers of checkStale() (recovery-flow diagnostics) can observe
-  // when isLive diverges from the legacy pidAlive/ttlExpired signals.
+  // #1072: alias-aware, not a raw os.hostname() comparison — this machine's
+  // hostname flips spelling, which made `sameHost` false for its own lock.
+  const sameHost = hostnamesMatch(lockHostCandidate(lock), os.hostname());
+  // NO `pidAlive` FIELD (#1151). #1137 kept it as an always-null shape stub;
+  // nothing ever read it — measured @ f0766e1, zero production readers
+  // repo-wide. Probing isPidAliveOnHost(lock.pid) answered a question about the
+  // ephemeral writer subprocess, not the session: 2026-08-23, 7 of 7 recorded
+  // pids were dead, including the lock of the session that was heartbeating at
+  // that very moment, so a `false` here read as "the session is dead" and was
+  // wrong every time. `isLive` is the verdict and `heartbeatAgeMinutes` the
+  // magnitude behind it. `isPidAliveOnHost` itself stays exported —
+  // file-lock.mjs and lock-reaper.mjs are legitimate callers, where the pid IS
+  // the process being asked about.
+  // Heartbeat-based liveness (#744) — the SAME check acquire()'s
+  // classifyExisting uses as its sole active gate, surfaced here so callers of
+  // checkStale() (recovery-flow diagnostics) can observe it directly.
   const isLive = isLockLive(lock);
 
   return {
@@ -1017,7 +1072,7 @@ export function checkStale({ repoRoot } = {}) {
     lock,
     ageHours,
     ttlExpired,
-    pidAlive,
+    heartbeatAgeMinutes: heartbeatAgeMinutes(lock),
     host: lock.host,
     sameHost,
     isLive,

package/scripts/lib/session-schema/normalizer.mjs

@@ -6,7 +6,8 @@
  * aliases) or parent barrel.
  *
  * Exports: normalizeSession
- * Module-private: _warnedMissingSchemaVersion (Set, per-process dedupe)
+ * Module-private: _warnedMissingSchemaVersion (Set, per-process dedupe),
+ *   isPlainObject, _canonicalizeExpressPath
  */
 
 import { SESSION_KEY_ALIASES } from './constants.mjs';
@@ -19,19 +20,82 @@ import { SESSION_KEY_ALIASES } from './constants.mjs';
 // per process, preventing log-spam on large sessions.jsonl files.
 const _warnedMissingSchemaVersion = new Set();
 
+// ---------------------------------------------------------------------------
+// Internal helper (intentional duplication — Option 1 submodule isolation,
+// mirroring aliases.mjs / validator.mjs rather than adding a cross-import)
+// ---------------------------------------------------------------------------
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * Collapse the legacy OBJECT form of `express_path` onto the canonical
+ * BOOLEAN form, in place on the caller's already-copied `next` object.
+ *
+ * WHY BOOLEAN IS CANONICAL. The ledger carried the field in two forms with no
+ * arbiter: 20 boolean records (14 `false`, 6 `true`) and exactly ONE object,
+ * `{activated, tasks, notes}` on `main-2026-05-01-housekeeping-2` (measured
+ * 2026-08-23 over 271 records). That single record is a hand-composition
+ * artefact, not a richer designed variant: it is the only one of the 21 with
+ * no top-level `notes`, and its `express_path.notes` holds session-level
+ * narrative that every other record puts in the canonical top-level `notes`.
+ * It also carries the same era's ad-hoc vocabulary elsewhere
+ * (`waves_completed`, `issues_new`, `cross_repo_writes`), so the object form
+ * is that composition freedom, not a schema. The question the field exists to
+ * answer — "greift der Express Path?" (docs/prd/2026-08-22-framework-
+ * verschlankung.md § VS-1) — is a boolean question whose denominator is the
+ * 14 `false` records.
+ *
+ * NOTHING IS DISCARDED. The original object is preserved verbatim under
+ * `_express_path_detail`, following the module's own "original keys are
+ * preserved alongside their canonical alias" convention and the
+ * `_completed_at_conflict` forensics tag in aliases.mjs. The conversion is
+ * therefore deterministic AND reversible.
+ *
+ * A shape this function cannot recognise (string, number, array, or an object
+ * without a boolean `activated`) is passed through UNTOUCHED — normalizeSession
+ * never throws. Refusing such a shape is the write path's job; validator.mjs
+ * rejects it there.
+ *
+ * BOUNDED TOLERANCE — REVISIT TRIGGER: the legacy object form is accepted only
+ * because one historical record uses it. When that record leaves the ledger (or
+ * is rewritten by a migration), delete this function and the matching
+ * `express_path` object clause in validator.mjs — canonical-boolean-only.
+ *
+ * @param {Record<string, any>} next — mutable copy of the entry being normalized
+ */
+function _canonicalizeExpressPath(next) {
+  if (!('express_path' in next)) return;
+  const raw = next.express_path;
+  if (!isPlainObject(raw)) return; // boolean (canonical), null, or unrecognised
+  if (typeof raw.activated !== 'boolean') return; // not the legacy shape
+
+  // Non-clobber, matching the alias rule above: never overwrite a sidecar that
+  // a previous normalization pass (or a producer) already wrote.
+  if (!('_express_path_detail' in next)) {
+    next._express_path_detail = raw;
+  }
+  next.express_path = raw.activated;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
 /**
- * Normalize a session entry read from disk. Applies SAFE key aliases, tags
+ * Normalize a session entry read from disk. Applies SAFE key aliases, collapses
+ * the legacy object form of `express_path` onto its canonical boolean, and tags
  * legacy entries without `schema_version` as 0 (distinct from
  * CURRENT_SESSION_SCHEMA_VERSION=2 which is stamped on new writes; bumped
  * 1 -> 2 via #372).
  *
  * Never throws. Malformed input (null, non-object, array) is passed through
  * unchanged. Original keys are preserved alongside their canonical alias for
- * debugging.
+ * debugging; the pre-collapse `express_path` object is preserved under
+ * `_express_path_detail` for the same reason.
+ *
+ * Idempotent: normalize(normalize(x)) deep-equals normalize(x).
  *
  * @param {any} entry
  * @returns {any} normalized entry (or original if non-object)
@@ -48,6 +112,9 @@ export function normalizeSession(entry) {
     }
   }
 
+  // express_path — same key, two shapes. Collapse onto the canonical boolean.
+  _canonicalizeExpressPath(next);
+
   // schema_version — legacy entries tagged as 0 (NOT CURRENT_SESSION_SCHEMA_VERSION).
   if ('schema_version' in next && next.schema_version !== undefined) {
     // Preserve existing version.

package/scripts/lib/session-schema/validator.mjs

@@ -431,6 +431,46 @@ function _validateOptionalFields(entry) {
       }
     }
   }
+
+  // `express_path` — CANONICAL FORM IS BOOLEAN (`true` = the express path was
+  // taken, `false` = it was offered and declined). Until now the field had no
+  // arbiter at all: the ledger carried 20 booleans and 1 object
+  // (`{activated, tasks, notes}`) and nothing in the schema knew the key, so
+  // neither shape could be called wrong. See the rationale + the 2026-08-23
+  // census in normalizer.mjs `_canonicalizeExpressPath`.
+  //
+  // The legacy `{activated: boolean, ...}` object is a BOUNDED read tolerance,
+  // in the same spirit as `_validateSchemaVersion` accepting [0,1,2,3] while
+  // only CURRENT_SESSION_SCHEMA_VERSION is ever written. It is bounded in two
+  // ways: an object WITHOUT a boolean `activated` is refused (the tolerance
+  // cannot grow into "any object"), and `normalizeSession` collapses the
+  // legacy object to the canonical boolean on every read, so no consumer
+  // downstream of the read path ever observes two shapes. Rejecting the legacy
+  // object outright here would have cost exactly one historical record its
+  // clean bill of health in `checkSessionsIntegrity` for zero benefit —
+  // measured 2026-08-23: `validateSession` fails 0 of 271 records today.
+  //
+  // REVISIT TRIGGER: when no ledger record uses the object form any more, drop
+  // the `isPlainObject` branch below and require a boolean outright.
+  if (entry.express_path !== undefined && entry.express_path !== null) {
+    const ep = entry.express_path;
+    if (typeof ep !== 'boolean' && !(isPlainObject(ep) && typeof ep.activated === 'boolean')) {
+      const shape = Array.isArray(ep) ? 'array' : typeof ep;
+      throw new ValidationError(
+        `express_path must be a boolean (canonical), null, or the legacy {activated: boolean} object, got: ${shape}`
+      );
+    }
+  }
+
+  // `_express_path_detail` — forensic sidecar written by `normalizeSession`
+  // when it collapses a legacy object `express_path` onto its boolean. Holds
+  // the pre-collapse object verbatim so the conversion stays reversible.
+  // Same optional-object contract as `effectiveness` / `discovery_stats`.
+  if (entry._express_path_detail !== undefined && entry._express_path_detail !== null) {
+    if (!isPlainObject(entry._express_path_detail)) {
+      throw new ValidationError('_express_path_detail must be an object or null');
+    }
+  }
 }
 
 // ---------------------------------------------------------------------------