session-orchestrator 3.22.0 → 3.23.0

package/scripts/lib/session-end/worktree-cleanup.mjs

@@ -2,9 +2,12 @@
  * worktree-cleanup.mjs — Phase 4a Auto-Promoted Worktree Cleanup helpers (#575 P3.2).
  *
  * Public API:
- *   - detectAutoPromotedWorktree(repoRoot, sessionId, opts): { wtPath, sessionId, branch } | null
+ *   - detectAutoPromotedWorktree(repoRoot, sessionId, opts): { wtPath, sessionId, branch, source } | null
  *   - isWorktreeClean(wtPath, opts): boolean
  *     (opts.execFileFn — injectable execFileSync seam for tests; #577 HARDEN-001)
+ *   - PROMOTION_MARKER_RELPATH — repo-relative path of the promotion marker
+ *     written by `enterWorktree()` (SSOT for the file location; the WRITER
+ *     imports this constant from here, so writer and reader can never drift).
  *
  * Closes #575 — Epic #568 Phase 3.2 (Parallel-Aware Sessions Auto-Promoted Worktree Cleanup)
  * PRD: "Parallel-aware sessions" (#568; archived in the private Meta-Vault) §3 P3 Gherkin rows 2-3
@@ -21,27 +24,162 @@
  * kept divergent on purpose — unifying them would break the sync/async boundary.
  */
 import path from 'node:path';
+import { readFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { parseSessionId } from '../session-id.mjs';
 
+/**
+ * Repo-relative location of the promotion marker `enterWorktree()` drops into
+ * every worktree it creates. Deliberately inside `.orchestrator/` (the session
+ * state dir) and deliberately WITHOUT any absolute path in its payload — the
+ * source checkout is recorded as `repoPathHash()` so the file can be committed
+ * or shipped without leaking the operator's filesystem layout.
+ *
+ * @type {string}
+ */
+export const PROMOTION_MARKER_RELPATH = path.join('.orchestrator', 'promoted-from.json');
+
+/**
+ * Read + shape-validate the promotion marker of a candidate worktree.
+ *
+ * Never throws: a missing file, a directory, unreadable permissions, invalid
+ * JSON, or a payload of the wrong shape all mean "no marker" (→ legacy path).
+ *
+ * @param {string} repoRoot
+ * @returns {{branch: string, source_session_id: string} & Record<string, unknown> | null}
+ */
+function readPromotionMarker(repoRoot) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path.join(repoRoot, PROMOTION_MARKER_RELPATH), 'utf8'));
+  } catch {
+    return null; // absent / unreadable / corrupt JSON — fall back to legacy detection
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  if (typeof parsed.branch !== 'string' || parsed.branch.length === 0) return null;
+  if (typeof parsed.source_session_id !== 'string' || parsed.source_session_id.length === 0) {
+    return null;
+  }
+  return parsed;
+}
+
+/**
+ * The marker path as git reports it in `status --porcelain` — always
+ * forward-slashed, regardless of the host separator.
+ * @type {string}
+ */
+const PROMOTION_MARKER_GIT_PATH = PROMOTION_MARKER_RELPATH.split(path.sep).join('/');
+
+/**
+ * True for the ONE porcelain line the promotion marker itself produces:
+ * `?? .orchestrator/promoted-from.json`.
+ *
+ * Why this exists: in THIS repo `.gitignore` already lists
+ * `.orchestrator/promoted-from.json` explicitly (`git check-ignore
+ * .orchestrator/promoted-from.json` exits 0), so the marker never reaches
+ * `git status --porcelain` here at all — this exemption is redundant
+ * belt-and-braces for the repo that ships it. It earns its keep in CONSUMER
+ * repos: `.orchestrator/` is commonly only PARTLY gitignored there
+ * (`.orchestrator/metrics/*.jsonl`, `session.lock`, … but not the bare
+ * directory, and not necessarily this file), and on a worktree whose branch
+ * predates that ignore line being added, the marker would show up as an
+ * untracked file and make every promoted worktree read "dirty" — turning the
+ * Phase 4a clean path (auto-remove) into a permanent operator AUQ. Repos that
+ * gitignore `.orchestrator/` wholesale never see the line at all. A third shape exists —
+ * the directory untracked AND un-ignored, where git collapses everything into
+ * one `?? .orchestrator/` line — and is deliberately NOT matched here:
+ * discounting a whole directory could hide operator work, and such a worktree
+ * is already dirty from the session's own `session.lock` / `STATE.md` writes
+ * regardless of this marker.
+ *
+ * Deliberately narrow: ONLY the untracked (`??`) status of exactly this path is
+ * ignored. A modified, staged, renamed or conflicted marker still counts as
+ * dirty, and no other file under `.orchestrator/` is affected — this is our own
+ * bookkeeping artefact, not operator work (PSA-003: we created it, so it is
+ * ours to discount).
+ *
+ * @param {string} line - One `git status --porcelain` line.
+ * @returns {boolean}
+ */
+function isUntrackedPromotionMarker(line) {
+  if (!line.startsWith('?? ')) return false;
+  const filePath = line.slice(3).trim().replace(/^"(.*)"$/, '$1');
+  return filePath === PROMOTION_MARKER_GIT_PATH;
+}
+
+/**
+ * Current branch of a worktree, or `null` when it cannot be determined
+ * (git error, or a detached HEAD — `git branch --show-current` prints nothing).
+ *
+ * @param {Function} execFileFn
+ * @param {string} repoRoot
+ * @returns {string|null}
+ */
+function currentBranchOf(execFileFn, repoRoot) {
+  try {
+    const out = execFileFn('git', ['-C', repoRoot, 'branch', '--show-current'], {
+      encoding: 'utf8',
+    });
+    const branch = String(out ?? '').trim();
+    return branch.length > 0 ? branch : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Detect whether the given repoRoot is an auto-promoted sibling worktree
  * created by `enterWorktree()` during the Phase 0.5 PROMOTION_OFFER path.
  *
- * Auto-promoted layout: <basePath>/<repo-name>-<sessionId>/
+ * Two keys, tried in this order:
+ *
+ *  1. **Marker (primary).** `<repoRoot>/.orchestrator/promoted-from.json`,
+ *     written by `enterWorktree()` at creation time. Accepted when the file
+ *     parses, carries `branch` + `source_session_id`, and the worktree's
+ *     current branch either MATCHES the recorded one or cannot be read at all.
+ *     This is the only key that survives the #1069 process boundary: since
+ *     #1069 the session that RUNS in the promoted worktree is a NEW session
+ *     with its OWN id, and since #1067 the worktree sits on `so/<sourceId>` —
+ *     so the current session's id appears in neither the directory name nor
+ *     the branch, and key 2 below can never match. Recording the fact at
+ *     creation time is what makes it re-derivable later.
+ *  2. **Basename (legacy fallback).** `<basePath>/<main-repo-name>-<sessionId>/`
+ *     against the CURRENT session id — still correct for worktrees created
+ *     before the marker existed, and for the same-session case.
  *
  * Returns:
- *   { wtPath, sessionId, branch } on match
+ *   { wtPath, sessionId, branch, source: 'marker'|'basename' } on match
  *   null on non-match (UUID session, non-promoted path, or git error)
  *
  * @param {string} repoRoot - Absolute path to the candidate worktree
  * @param {string} sessionId - Session ID (semantic or UUID)
- * @returns {{wtPath: string, sessionId: string, branch: string} | null}
+ * @returns {{wtPath: string, sessionId: string, branch: string, source: 'marker'|'basename'} | null}
  */
 export function detectAutoPromotedWorktree(repoRoot, sessionId, opts = {}) {
   // #577 HARDEN-001: execFileSync + args ARRAY (no shell) is structurally
   // injection-proof — repoRoot can never be interpreted as shell metacharacters.
   const execFileFn = opts.execFileFn ?? execFileSync;
+
+  // --- Key 1: the marker written at creation time (session-id independent) ---
+  const marker = readPromotionMarker(repoRoot);
+  if (marker) {
+    const current = currentBranchOf(execFileFn, repoRoot);
+    // `current === null` (git unavailable / detached HEAD) is accepted: the
+    // marker is written by exactly one code path, and the destructive step in
+    // Phase 4a is gated separately by `isWorktreeClean()`, which fails CLOSED
+    // on any git error. So an unverifiable branch can only ever route the
+    // operator into the AUQ, never into an automatic removal.
+    if (current === null || current === marker.branch) {
+      return {
+        wtPath: repoRoot,
+        sessionId: marker.source_session_id,
+        branch: marker.branch,
+        source: 'marker',
+      };
+    }
+  }
+
+  // --- Key 2: legacy basename match against the CURRENT session id ---
   const parsed = parseSessionId(sessionId);
   if (!parsed || parsed.format !== 'semantic') return null; // UUID-format sessions are never auto-promoted
 
@@ -72,7 +210,7 @@ export function detectAutoPromotedWorktree(repoRoot, sessionId, opts = {}) {
   const isPromotedPath = path.basename(repoRoot) === expectedBasename;
 
   if (isPromotedPath) {
-    return { wtPath: repoRoot, sessionId, branch: parsed.branch };
+    return { wtPath: repoRoot, sessionId, branch: parsed.branch, source: 'basename' };
   }
   return null;
 }
@@ -82,7 +220,9 @@ export function detectAutoPromotedWorktree(repoRoot, sessionId, opts = {}) {
  *
  * A worktree is clean iff ALL three conditions hold:
  *   1. No uncommitted changes (`git status --porcelain` is empty)
- *   2. No untracked files (implicit in #1 — porcelain includes `??` entries)
+ *   2. No untracked files (implicit in #1 — porcelain includes `??` entries),
+ *      with ONE exception: the untracked promotion marker this module's own
+ *      writer drops into the worktree (see isUntrackedPromotionMarker)
  *   3. No unpushed commits (`git status --short --branch` lacks `ahead`)
  *
  * On any git error, returns `false` (safer per PSA-003 — conservative default
@@ -98,7 +238,14 @@ export function isWorktreeClean(wtPath, opts = {}) {
     const status = execFileFn('git', ['-C', wtPath, 'status', '--porcelain'], {
       encoding: 'utf8',
     });
-    if (status.trim().length > 0) return false; // dirty (modified, untracked, or staged)
+    const significant = String(status ?? '')
+      .split('\n')
+      .map((l) => l.trimEnd())
+      .filter((l) => l.length > 0)
+      // Our own promotion marker is not operator work — see
+      // isUntrackedPromotionMarker() for why it must not count as dirty.
+      .filter((l) => !isUntrackedPromotionMarker(l));
+    if (significant.length > 0) return false; // dirty (modified, untracked, or staged)
 
     const branchStatus = execFileFn('git', ['-C', wtPath, 'status', '--short', '--branch'], {
       encoding: 'utf8',

package/scripts/lib/session-id.mjs

@@ -6,7 +6,7 @@
  *   - parseSessionId(id): { format: 'semantic'|'uuid', ...fields, raw } | null
  *   - DEFAULT_SESSION_ID_SOURCES — the default `sources` array (see below)
  *   - SEMANTIC_ID_RE — source-of-truth regex for semantic session IDs
- *   - UUID_V4_RE     — regex for UUID-v4 format session IDs
+ *   - UUID_RE        — regex for RFC 9562 UUID session IDs (any version 1–8)
  *
  * Closes #572 — Epic #568 Phase 2.1 (Parallel-Aware Sessions Semantic ID)
  * Closes #585 — Epic #583 W2-I2 (history-aware n-increment) per audit
@@ -67,14 +67,25 @@ import { parseStateMd } from './state-md/yaml-parser.mjs';
 export const SEMANTIC_ID_RE = /^([a-z0-9._/-]+)-(\d{4}-\d{2}-\d{2})-([a-z-]+)-(\d+)$/;
 
 /**
- * Regex for UUID-v4 session IDs.
+ * Regex for RFC 9562 UUID session IDs — ANY version 1–8, variant `10xx`.
  *
- * Matches: 8-4-4-4-12 hex digits, version nibble = '4', variant nibble in {8,9,a,b}.
- * Case-insensitive to accept both uppercase and lowercase hex.
+ * Matches: 8-4-4-4-12 hex digits, version nibble in [1-8], variant nibble in
+ * {8,9,a,b}. Case-insensitive to accept both uppercase and lowercase hex.
+ *
+ * Why the version nibble is a RANGE and not the literal `4` (Kanevry#66 / #1091):
+ * Claude Code mints UUIDv4 session ids, but Codex CLI mints UUIDv7. Pinning `4`
+ * made `parseSessionId()` return `null` for every Codex session, so
+ * `hooks/on-session-start.mjs` fell through to a freshly generated
+ * `randomUUID()` and every later hook in that session missed the lock.
+ *
+ * The structure stays strict on purpose: the dash/length layout and the
+ * variant nibble are what discriminate a real UUID from a 36-char lookalike,
+ * so only the version nibble is widened. Version `0` (nil UUID) and `9`..`f`
+ * (unassigned / max UUID) remain rejected — RFC 9562 defines 1–8.
  *
  * @type {RegExp}
  */
-export const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -344,8 +355,12 @@ export const DEFAULT_SESSION_ID_SOURCES = Object.freeze([
  *   1. Semantic: `<branch>-<YYYY-MM-DD>-<mode>-<n>`
  *      Returns `{ format: 'semantic', branch, date, mode, n, raw }`.
  *
- *   2. UUID-v4: `xxxxxxxx-xxxx-4xxx-[89ab]xxx-xxxxxxxxxxxx`
- *      Returns `{ format: 'uuid', uuid, raw }`.
+ *   2. RFC 9562 UUID, any version 1–8, variant `10xx`:
+ *      `xxxxxxxx-xxxx-[1-8]xxx-[89ab]xxx-xxxxxxxxxxxx`
+ *      Returns `{ format: 'uuid', uuid, version, raw }`, where `version` is the
+ *      version nibble as an integer (4 for Claude Code's v4 ids, 7 for Codex
+ *      CLI's v7 ids). Callers that only branch on `format` are unaffected —
+ *      `version` is additive (Kanevry#66 / #1091).
  *
  * Returns `null` for any input that is not a non-empty string or does not
  * match either known format. Never throws.
@@ -356,7 +371,7 @@ export const DEFAULT_SESSION_ID_SOURCES = Object.freeze([
  *
  * @param {unknown} id - The session ID to parse.
  * @returns {{ format: 'semantic', branch: string, date: string, mode: string, n: number, raw: string }
- *           | { format: 'uuid', uuid: string, raw: string }
+ *           | { format: 'uuid', uuid: string, version: number, raw: string }
  *           | null}
  */
 export function parseSessionId(id) {
@@ -375,9 +390,10 @@ export function parseSessionId(id) {
     };
   }
 
-  // Try UUID-v4.
-  if (UUID_V4_RE.test(id)) {
-    return { format: 'uuid', uuid: id, raw: id };
+  // Try RFC 9562 UUID (any version 1–8). Index 14 is the version nibble, and
+  // UUID_RE has already constrained it to [1-8], so Number() cannot be NaN.
+  if (UUID_RE.test(id)) {
+    return { format: 'uuid', uuid: id, version: Number(id[14]), raw: id };
   }
 
   return null;
@@ -418,9 +434,9 @@ export function parseSessionId(id) {
  *   cannot assign the same n. The #952 collision was NOT a concurrency defect —
  *   the lock held; the candidate set was incomplete.
  *
- * UUID-v4 entries (in any source) are silently dropped (parseSessionId returns
- * format:'uuid' which the filter excludes). Malformed semantic-looking IDs are
- * also dropped (SEMANTIC_ID_RE rejects them).
+ * UUID entries of ANY version (in any source) are silently dropped
+ * (parseSessionId returns format:'uuid' which the filter excludes). Malformed
+ * semantic-looking IDs are also dropped (SEMANTIC_ID_RE rejects them).
  *
  * @param {object} opts
  * @param {string} opts.branch - Current git branch (e.g. "main", "feature/foo").

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

@@ -0,0 +1,159 @@
+/**
+ * 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;
+}
+
+/**
+ * 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 {@link readOwnSessionIds}.
+ * @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,