session-orchestrator 3.17.0 → 3.19.0

package/scripts/lib/session-lock.mjs

@@ -14,6 +14,13 @@
  *    a different hostname (can't signal a remote process).
  *  - Decision deferred: acquire() reports stale locks but does NOT auto-clear
  *    them. session-start handles the recovery AUQ flow (W3-C3).
+ *  - Owner-proof, not just id-match (#906-class fix): the semantic session id
+ *    is NOT globally unique (the id-counter can hand out the same
+ *    `<branch>-<date>-<mode>-<n>` to two different session processes on the
+ *    same day). `buildLockOwnerProof()` / `isLockOwnedByProof()` verify
+ *    ownership via a SECOND identity factor (pid + host + started_at)
+ *    instead of trusting a session_id/semantic_session_id match alone. See
+ *    their JSDoc for the fail-closed contract and factor-choice rationale.
  *
  * BARREL CONTRACT (#630 A1 barrel-preserving split):
  *   This module bundled THREE orthogonal lock protocols. Two of them — the
@@ -37,6 +44,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { classifyMode } from './exclusivity-matrix.mjs';
 import { isPidAliveOnHost } from './file-lock.mjs';
+import { writeJsonAtomicSync } from './io.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).
@@ -76,6 +84,14 @@ export {
 export const DEFAULT_TTL_HOURS = 4;
 export const LOCK_PATH = '.orchestrator/session.lock';
 
+/**
+ * Where the durable lock-ownership proof lives, relative to the repo root
+ * (#987 Part 1). `.orchestrator/runtime/` is machine-local, gitignored state —
+ * the proof must survive across hook subprocesses of the SAME logical session
+ * but never travel via VCS.
+ */
+export const OWNER_PROOF_RELPATH = '.orchestrator/runtime/lock-owner-proof.json';
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -315,17 +331,80 @@ function createSessionLockExclusive(lockFile, lock) {
  * Returns the parsed lock object, or null if absent or unparseable.
  * Never throws.
  *
+ * BACK-COMPAT CONTRACT (load-bearing — grep-verified 2026-07-29):
+ *   A bare `grep -rn "readLock("` over scripts/ + hooks/ reports 14 hits, but
+ *   6 of those are comment/JSDoc mentions, not calls. Filtering them out —
+ *   `grep -rn "readLock(" --include='*.mjs' scripts/ hooks/ | grep -v
+ *   "scripts/lib/session-lock.mjs" | grep -vE ':\s*(\*|//)' | wc -l` → 8 real
+ *   production call sites across 6 files (lock-reaper, peer-discovery,
+ *   session-close-backfill, session-discovery, sessions-staleness-banner,
+ *   vault-status/board-writer). The tests/ figure has the same caveat: of the
+ *   45 raw hits, ~11 are comments and 3 are local same-named test doubles.
+ *   Counting raw grep hits as call sites OVERSTATES the surface — the number
+ *   is smaller than first briefed, but every one of those 8 relies on the
+ *   "absent/unreadable/corrupt all collapse to null" contract below, so the
+ *   conclusion is unchanged. This function's signature and null behaviour
+ *   MUST stay byte-for-byte identical — the discriminated read that
+ *   distinguishes those three cases is the NEW, additive `readLockDetailed()`
+ *   below; `readLock()` is now a thin projection of it back onto the legacy
+ *   contract (RCR-007: changing the 59-call-site contract itself would be a
+ *   public-API break, not a same-scope fix).
+ *
  * @param {{ repoRoot?: string }} [opts]
  * @returns {{ session_id: string, started_at: string, mode: string, pid: number, host: string, ttl_hours: number } | null}
  */
 export function readLock(opts = {}) {
+  const detailed = readLockDetailed(opts);
+  return detailed.status === 'ok' ? detailed.lock : null;
+}
+
+/**
+ * Read the lock file and DISCRIMINATE why it might not yield a usable lock —
+ * additive alongside `readLock()` (see its back-compat contract note above),
+ * which collapses every non-ok case to `null`. That collapse is exactly how
+ * a vanished/unreadable lock has read as "no lock" instead of "anomaly"
+ * throughout this session's investigation (#906-class incident).
+ *
+ * Four discriminated outcomes:
+ *   - `{ status: 'absent' }` — the file does not exist (ENOENT). This is the
+ *     ONLY case that should be treated as "no lock, proceed as if free".
+ *   - `{ status: 'unreadable', error }` — the file exists but could not be
+ *     read (e.g. EACCES, EISDIR). Distinct from `absent` on purpose: an
+ *     unreadable lock is an ANOMALY a caller may want to surface, not a
+ *     green light to acquire.
+ *   - `{ status: 'corrupt', raw }` — the file was read but its contents
+ *     failed `parseLock()` (invalid JSON, or valid JSON missing the required
+ *     shape). `raw` is included so a caller can log/diagnose without a
+ *     second read.
+ *   - `{ status: 'ok', lock }` — the file was read and parsed successfully.
+ *
+ * Never throws.
+ *
+ * @param {{ repoRoot?: string }} [opts]
+ * @returns {
+ *   { status: 'absent' } |
+ *   { status: 'unreadable', error: string } |
+ *   { status: 'corrupt', raw: string } |
+ *   { status: 'ok', lock: object }
+ * }
+ */
+export function readLockDetailed(opts = {}) {
   const lockFile = lockPathFor(opts.repoRoot);
+  let raw;
   try {
-    const raw = fs.readFileSync(lockFile, 'utf8');
-    return parseLock(raw);
-  } catch {
-    return null;
+    raw = fs.readFileSync(lockFile, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { status: 'absent' };
+    }
+    return { status: 'unreadable', error: err.message };
   }
+
+  const lock = parseLock(raw);
+  if (lock === null) {
+    return { status: 'corrupt', raw };
+  }
+  return { status: 'ok', lock };
 }
 
 /**
@@ -558,6 +637,206 @@ export function forceAcquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, re
   }
 }
 
+/**
+ * Extract an ownership-proof object from a lock — the field-name translation
+ * layer `isLockOwnedByProof()` expects. Intended usage: a caller that just
+ * created/observed a lock IT WROTE (the `lock` returned by
+ * `acquire()`/`forceAcquire()`, or a `readLock()`/`readLockDetailed()` taken
+ * immediately after) calls this ONCE at genesis time and persists the
+ * RESULT — not the raw lock — as its durable "I own this" evidence. Later,
+ * a different process invocation (e.g. a subsequent hook subprocess in the
+ * same logical session) can present that persisted proof to
+ * `isLockOwnedByProof()` against whatever lock is on disk AT THAT TIME.
+ *
+ * Pure, no-throw. Returns `null` (never a partial object) when any of the
+ * three required fields is missing or the wrong type — a caller cannot
+ * construct a proof from a lock it cannot fully observe.
+ *
+ * @param {object|null} lock
+ * @returns {{ pid: number, host: string, startedAt: string } | null}
+ */
+export function buildLockOwnerProof(lock) {
+  if (!lock || typeof lock !== 'object') return null;
+  const { pid, host, started_at: startedAt } = lock;
+  if (typeof pid !== 'number') return null;
+  if (typeof host !== 'string' || host.length === 0) return null;
+  if (typeof startedAt !== 'string' || startedAt.length === 0) return null;
+  return { pid, host, startedAt };
+}
+
+/**
+ * Verify that a caller genuinely owns a lock, using a SECOND identity factor
+ * beyond the (non-unique) session_id / semantic_session_id.
+ *
+ * WHY THIS EXISTS (#906-class bug, this session's root-cause finding): the
+ * semantic session id (`<branch>-<date>-<mode>-<n>`) is NOT globally unique
+ * — the id-counter can hand out the SAME id to two different session
+ * processes on the same day (live-observed collisions this session:
+ * `main-2026-07-29-deep-1` and `main-2026-07-29-session-1`, each assigned
+ * twice). `hooks/on-session-end.mjs`'s `ownBySemanticStrict` path currently
+ * decides lock ownership from that colliding id alone and can delete a
+ * LIVE, foreign session's lock as a result. `release()`'s pre-existing
+ * `existing.session_id !== sessionId` check (below) is a TOCTOU re-read
+ * guard — it re-derives the exact same potentially-colliding key, so it
+ * catches "the lock changed between my two reads" but NOT "the lock I'm
+ * looking at was never mine to begin with". This function is the missing
+ * proof.
+ *
+ * FACTOR CHOICE — pid + host + started_at, never session_id:
+ *   - `host` is required first: liveness/identity cannot be asserted across
+ *     machines anyway (see `isPidAliveOnHost`), so a lock written on a
+ *     DIFFERENT host is rejected outright, no further comparison needed.
+ *   - `pid` alone is not unique on a long-lived host — the OS recycles PIDs
+ *     once the original process exits — so it cannot carry the proof by
+ *     itself.
+ *   - `started_at` is the actual discriminator: its ISO-8601-with-
+ *     milliseconds value is knowable ONLY to a caller that was PRESENT at
+ *     lock-creation time (it wrote the lock itself, or read it back
+ *     immediately after `acquire()`/`forceAcquire()` returned). A same-day
+ *     semantic-id collision from an unrelated process has, with
+ *     overwhelming probability, a DIFFERENT millisecond `started_at` — this
+ *     is exactly the discriminator the id-collision case lacks.
+ *   - Combined, `pid + host + started_at` is a proof of PRESENCE AT GENESIS,
+ *     not a re-assertion of the same collidable name.
+ *
+ * FAIL-CLOSED CONTRACT: any missing/malformed field on EITHER side (the
+ * live lock or the caller's proof) returns `false`. This function must
+ * never answer "true" when it cannot actually confirm ownership — silently
+ * defaulting to permissive on incomplete data is the exact fail-open shape
+ * this session exists to close (see the `console.log + process.exit()`
+ * stdout-truncation rule and the exit-code-to-JSON-migration rule in this
+ * repo's reconciled learnings for the same failure class in other guards).
+ *
+ * @param {object|null} lock  The CURRENT on-disk lock (e.g. from `readLock()`).
+ * @param {{ pid: number, host: string, startedAt: string }|null} proof
+ *   Typically the return value of `buildLockOwnerProof()` captured at
+ *   genesis time. NEVER re-derive this from `process.pid`/`os.hostname()`
+ *   at check-time — the checking process is very likely a DIFFERENT
+ *   subprocess (each hook invocation is its own process) than the one that
+ *   originally wrote the lock.
+ * @returns {boolean} true only when pid, host, AND started_at all match
+ *   exactly between `lock` and `proof`.
+ */
+export function isLockOwnedByProof(lock, proof) {
+  if (!lock || typeof lock !== 'object') return false;
+  if (!proof || typeof proof !== 'object') return false;
+
+  const { pid: lockPid, host: lockHost, started_at: lockStartedAt } = lock;
+  const { pid: proofPid, host: proofHost, startedAt: proofStartedAt } = proof;
+
+  if (typeof lockPid !== 'number' || typeof proofPid !== 'number') return false;
+  if (typeof lockHost !== 'string' || lockHost.length === 0) return false;
+  if (typeof proofHost !== 'string' || proofHost.length === 0) return false;
+  if (typeof lockStartedAt !== 'string' || lockStartedAt.length === 0) return false;
+  if (typeof proofStartedAt !== 'string' || proofStartedAt.length === 0) return false;
+
+  return lockPid === proofPid && lockHost === proofHost && lockStartedAt === proofStartedAt;
+}
+
+/**
+ * Persist the ownership proof of a just-written lock to
+ * `.orchestrator/runtime/lock-owner-proof.json` (#987 Part 1 — proof
+ * persistence at lock genesis; Part 2, the on-session-end consumption side,
+ * is a separate change).
+ *
+ * Intended caller: `bootstrapLock()` (hooks/_lib/lock-bootstrap.mjs)
+ * immediately after its enriched-lock write — the `lock` argument there is
+ * byte-identical to the on-disk lock, so the proof it yields will verify via
+ * `isLockOwnedByProof()` against any later re-read of that same lock.
+ *
+ * Envelope shape (schema_version 1):
+ *   {
+ *     schema_version: 1,
+ *     proof: { pid, host, startedAt },   // the ONLY field ever compared
+ *     lock_session_id,                   // forensic-only
+ *     semantic_session_id,               // forensic-only
+ *     repo_root,                         // forensic-only
+ *     written_at,                        // forensic-only
+ *   }
+ *
+ * INVARIANT: only `proof` may ever participate in an ownership comparison.
+ * `lock_session_id` / `semantic_session_id` rotate per session and the
+ * semantic form COLLIDES across same-day sessions — trusting them is exactly
+ * the #906-class bug this proof exists to close. Consumers go through
+ * `loadOwnerProof()`, which strips the envelope and returns the triple alone.
+ *
+ * No-throw. When the lock cannot yield a full proof (missing/mistyped
+ * pid/host/started_at), this is a deliberate no-op: nothing is written and
+ * `{ ok: false, reason: 'unproovable-lock' }` is returned — a partial proof
+ * on disk would be a fail-open artifact.
+ *
+ * @param {{ repoRoot?: string, lock: object|null }} args
+ * @returns {{ ok: true, path: string }
+ *          |{ ok: false, reason: 'unproovable-lock' }
+ *          |{ ok: false, reason: 'fs-error', error: string }}
+ */
+export function writeOwnerProof({ repoRoot, lock } = {}) {
+  try {
+    const proof = buildLockOwnerProof(lock);
+    if (proof === null) {
+      return { ok: false, reason: 'unproovable-lock' };
+    }
+
+    const root = repoRoot ?? process.cwd();
+    const proofFile = path.join(root, OWNER_PROOF_RELPATH);
+    const envelope = {
+      schema_version: 1,
+      proof,
+      lock_session_id: typeof lock.session_id === 'string' ? lock.session_id : null,
+      semantic_session_id:
+        typeof lock.semantic_session_id === 'string' ? lock.semantic_session_id : null,
+      repo_root: root,
+      written_at: nowIso(),
+    };
+
+    const w = writeJsonAtomicSync(proofFile, envelope, { tmpPrefix: '.lock-owner-proof.tmp' });
+    if (!w.ok) return w;
+    return { ok: true, path: proofFile };
+  } catch (err) {
+    return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * Load the persisted ownership proof written by `writeOwnerProof()` and
+ * return the inner `{ pid, host, startedAt }` triple — nothing else from the
+ * envelope ever escapes (the forensic fields must not leak into comparisons,
+ * see the INVARIANT on `writeOwnerProof()`).
+ *
+ * FAIL-CLOSED, never throws: a missing file, unreadable file, malformed
+ * JSON, an envelope without a `proof` object, or a proof with any
+ * missing/mistyped field all return `null`. A `null` proof presented to
+ * `isLockOwnedByProof()` yields `false` — the consumer degrades to
+ * "cannot prove ownership", never to "assume ownership".
+ *
+ * Note the proof carries no self-expiry: a stale proof from a PREVIOUS
+ * session is harmless by construction, because the triple it holds (its
+ * millisecond `started_at` above all) will not match any newer lock —
+ * `isLockOwnedByProof()` rejects it. See the stale-proof test in
+ * tests/lib/session-lock.test.mjs.
+ *
+ * @param {{ repoRoot?: string }} args
+ * @returns {{ pid: number, host: string, startedAt: string } | null}
+ */
+export function loadOwnerProof({ repoRoot } = {}) {
+  try {
+    const proofFile = path.join(repoRoot ?? process.cwd(), OWNER_PROOF_RELPATH);
+    const raw = fs.readFileSync(proofFile, 'utf8');
+    const envelope = JSON.parse(raw);
+    if (!envelope || typeof envelope !== 'object') return null;
+
+    const p = envelope.proof;
+    if (!p || typeof p !== 'object') return null;
+    if (typeof p.pid !== 'number') return null;
+    if (typeof p.host !== 'string' || p.host.length === 0) return null;
+    if (typeof p.startedAt !== 'string' || p.startedAt.length === 0) return null;
+
+    return { pid: p.pid, host: p.host, startedAt: p.startedAt };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Release the lock IFF it belongs to the given session_id.
  * Silent no-op when the lock belongs to a different session or does not exist.
@@ -580,10 +859,20 @@ export function forceAcquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, re
  * lock present is fine (ours is gone); only our own lock still being
  * observable after the bounded retry sets `verified: false`.
  *
- * @param {{ sessionId: string, repoRoot?: string }} args
+ * Optional proof-gated ownership (#906-class fix, additive): pass `proof`
+ * (see `buildLockOwnerProof()` / `isLockOwnedByProof()`) to require a SECOND
+ * identity factor beyond `session_id` before deleting — this is what makes
+ * a same-day semantic-id collision safe to release against. When `proof` is
+ * omitted (the default), behaviour is BYTE-IDENTICAL to before this change:
+ * only the `session_id` match gates the delete. This keeps the ONE other
+ * external caller (`scripts/lib/autopilot/worktree-pipeline.mjs`, which does
+ * not pass `proof`) working unchanged — it stays on the weaker,
+ * session_id-only path.
+ *
+ * @param {{ sessionId: string, repoRoot?: string, proof?: { pid: number, host: string, startedAt: string } }} args
  * @returns {{ ok: true, deleted: boolean, reason?: string, verified?: boolean }}
  */
-export function release({ sessionId, repoRoot } = {}) {
+export function release({ sessionId, repoRoot, proof } = {}) {
   const lockFile = lockPathFor(repoRoot);
   try {
     const existing = readLock({ repoRoot });
@@ -596,6 +885,15 @@ export function release({ sessionId, repoRoot } = {}) {
       return { ok: true, deleted: false, reason: 'session-mismatch' };
     }
 
+    // Proof-gated release (additive, #906-class fix): when the caller supplies
+    // `proof`, the session_id match above is NOT sufficient by itself —
+    // session_id collisions are the documented root cause behind this check.
+    // Omitting `proof` leaves this branch dead code, preserving the exact
+    // pre-existing behaviour for callers that don't pass it.
+    if (proof !== undefined && !isLockOwnedByProof(existing, proof)) {
+      return { ok: true, deleted: false, reason: 'proof-mismatch' };
+    }
+
     fs.unlinkSync(lockFile);
 
     // Post-delete verify: only retry when OUR OWN lock is still observable.

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

@@ -82,9 +82,17 @@ export const REQUIRED_FIELDS = Object.freeze([
 export const AGENT_SUMMARY_FIELDS = Object.freeze(['complete', 'partial', 'failed', 'spiral']);
 
 /**
- * Optional additive fields introduced for the remote-agent substrate (ADR-364 thin-slice).
- * These are NOT in REQUIRED_FIELDS — older entries lacking them validate cleanly.
- * Validator: see `_validateOptionalFields` in validator.mjs.
+ * Optional fields — declared here so a field's status is STATED, never inferred
+ * from the presence of an `if` in the validator. Seeded by the remote-agent
+ * substrate (ADR-364 thin-slice) and grown additively since (#644, #724, #773,
+ * #964). These are NOT in REQUIRED_FIELDS — older entries lacking them validate
+ * cleanly. Validator: see `_validateOptionalFields` in validator.mjs.
+ *
+ * NOT YET EXHAUSTIVE. `_validateOptionalFields` additionally shape-checks
+ * `discovery_stats`, `review_stats`, `platform`, `branch`, `base_branch`,
+ * `notes`, `duration_seconds`, `issues_closed` and `issues_created` without
+ * listing them here. Treat membership as "declared optional", never absence as
+ * "not a known field" — see the #964 follow-up note in the session report.
  */
 export const OPTIONAL_FIELDS = Object.freeze([
   'agent_identity',
@@ -112,4 +120,15 @@ export const OPTIONAL_FIELDS = Object.freeze([
   'open_questions_asked',
   'open_questions_answered',
   'open_questions_deferred',
+  // #964 — `effectiveness` was shape-checked by `_validateOptionalFields` while
+  // appearing in NEITHER list, so its status could only be inferred from an
+  // `if`. It is OPTIONAL on the write path and stays that way: making it
+  // required would retroactively invalidate the 10 existing records that lack
+  // it, plus every `abandoned` stub the SessionEnd backfill (#724 C1) will ever
+  // write. It is REQUIRED by the vault-mirror v1 renderer
+  // (`RENDERABLE_SESSION_FIELDS_V1`, scripts/lib/vault-mirror/render-sessions.mjs)
+  // — that is a strictly stronger, deliberately separate contract: "renderable
+  // into a note a human reads" ⊃ "schema-valid". A record missing it is a clean
+  // vault-mirror skip, NOT a malformed record.
+  'effectiveness',
 ]);

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

@@ -105,6 +105,22 @@ function _validateSchemaVersion(entry) {
   }
 }
 
+/**
+ * Required-field gate for the WRITE path.
+ *
+ * #964 — the predicate is KEY PRESENCE (`field in entry`), deliberately NOT
+ * value presence. An explicit `{ total_waves: null }` passes here and is then
+ * rejected by the typed sub-validator below with a message that names the type
+ * violation, which is the more useful diagnostic. The vault-mirror renderers
+ * use the OTHER predicate (`entry[field] === null || undefined`) because a null
+ * value is unrenderable even though it is well-formed. The two predicates agree
+ * on every live record but are not the same test — do not "unify" them without
+ * deciding which failure each side is supposed to report.
+ *
+ * The renderers' field LISTS are likewise a separate, strictly stronger
+ * contract; the superset relationship between them is enforced mechanically in
+ * tests/lib/vault-mirror/render-sessions.test.mjs, not by prose here.
+ */
 function _validateRequiredFields(entry) {
   for (const field of REQUIRED_FIELDS) {
     if (!(field in entry)) {