session-orchestrator 3.16.0

package/scripts/lib/session-lock.mjs

@@ -0,0 +1,703 @@
+/**
+ * session-lock.mjs — distributed session-lock with TTL (issue #330).
+ *
+ * Provides atomic acquire/release/inspect for a per-repo session.lock file
+ * stored at `.orchestrator/session.lock`. Prevents concurrent deep sessions
+ * from stomping each other's metrics writes and wave executor state.
+ *
+ * Design principles:
+ *  - No-throw: every exported function catches filesystem errors and returns a
+ *    structured failure object instead of propagating exceptions.
+ *  - Atomic writes: acquire() writes to a temp file then renames, giving a
+ *    single syscall that is either visible or not on POSIX systems.
+ *  - Cross-host aware: PID liveness checks are skipped when the lock came from
+ *    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).
+ *
+ * BARREL CONTRACT (#630 A1 barrel-preserving split):
+ *   This module bundled THREE orthogonal lock protocols. Two of them — the
+ *   STATE.md write-lock and the staging-fence commit-mutex — were moved into
+ *   dedicated modules under `scripts/lib/locks/`. This file STAYS the canonical
+ *   barrel: it keeps the session-lock CORE protocol AND re-exports every moved
+ *   symbol, so the original 22-symbol import surface is preserved EXACTLY and
+ *   all 17 importers keep working UNCHANGED. The moved modules import shared
+ *   primitives from leaf modules (file-lock.mjs, locks/lock-body.mjs) and NEVER
+ *   from this file, so the barrel ↔ protocol-module edge is one-directional
+ *   (no import cycle).
+ *     - STATE.md write-lock    → ./locks/state-md-lock.mjs
+ *     - staging-fence mutex     → ./locks/staging-fence-lock.mjs
+ *
+ * No external dependencies — Node 20+ stdlib only.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { classifyMode } from './exclusivity-matrix.mjs';
+import { isPidAliveOnHost } from './file-lock.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).
+// Re-exported here so existing importers (agent-status historically,
+// session-discovery's forensic note, memory-proposals historically, and any
+// external caller) keep resolving `isPidAliveOnHost` from session-lock.mjs.
+export { isPidAliveOnHost };
+
+// ---------------------------------------------------------------------------
+// Re-exports — STATE.md write-lock + staging-fence commit-mutex (#630 split).
+// These two protocols live in dedicated modules now; the barrel re-exports
+// their full public surface so importers of session-lock.mjs are unchanged.
+// ---------------------------------------------------------------------------
+
+export {
+  STATE_LOCK_PATH,
+  DEFAULT_STATE_LOCK_TIMEOUT_MS,
+  STATE_LOCK_POLL_MS,
+  acquireStateLock,
+  releaseStateLock,
+  withStateMdLock,
+} from './locks/state-md-lock.mjs';
+
+export {
+  STAGING_FENCE_LOCK_PATH,
+  DEFAULT_STAGING_FENCE_LOCK_TIMEOUT_MS,
+  STAGING_FENCE_LOCK_POLL_MS,
+  acquireStagingFenceLock,
+  releaseStagingFenceLock,
+  withStagingFenceLock,
+} from './locks/staging-fence-lock.mjs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_TTL_HOURS = 4;
+export const LOCK_PATH = '.orchestrator/session.lock';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+// isPidAliveOnHost lives in file-lock.mjs (#630) and is re-exported at the top
+// of this module. It is a SAME-HOST PID liveness probe (POSIX signal-0). It is
+// 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.
+
+/**
+ * Resolve the absolute path to the lock file.
+ * @param {string|undefined} repoRoot
+ * @returns {string}
+ */
+function lockPathFor(repoRoot) {
+  return path.join(repoRoot ?? process.cwd(), LOCK_PATH);
+}
+
+/**
+ * Return the current time as an ISO-8601 string.
+ * @returns {string}
+ */
+function nowIso() {
+  return new Date().toISOString();
+}
+
+/**
+ * Determine whether a lock's TTL has expired.
+ * @param {{ started_at: string, ttl_hours: number }} lock
+ * @returns {boolean}
+ */
+function isTtlExpired(lock) {
+  const age = Date.now() - Date.parse(lock.started_at);
+  return age > lock.ttl_hours * 3600 * 1000;
+}
+
+/**
+ * Compute the age of a lock in fractional hours.
+ * Returns null if started_at is unparseable.
+ * @param {{ started_at: string }} lock
+ * @returns {number|null}
+ */
+function lockAgeHours(lock) {
+  const ts = Date.parse(lock.started_at);
+  if (Number.isNaN(ts)) return null;
+  return (Date.now() - ts) / (3600 * 1000);
+}
+
+/**
+ * Parse lock file contents into an object. Returns null on any parse error.
+ *
+ * Schema v2 (Epic #583, W2-I3): adds `last_heartbeat` (optional, populated by
+ * `updateHeartbeat()`) + `semantic_session_id` (optional, populated when the
+ * `session_id` field carries a UUID and the caller wants to preserve the
+ * always-semantic id alongside it).
+ *
+ * Back-compat: v1 locks (no `last_heartbeat`) are normalised on read with
+ * `last_heartbeat = started_at`. The optional `semantic_session_id` field is
+ * left undefined when absent. This lets pre-#583 lockfiles flow through the
+ * new liveness rule transparently — the v1 lock's `started_at` becomes its
+ * effective heartbeat, so TTL freshness still rescues recent locks even when
+ * the writer process is dead (the D2/D5 production case).
+ *
+ * @param {string} raw
+ * @returns {object|null}
+ */
+function parseLock(raw) {
+  try {
+    const obj = JSON.parse(raw);
+    if (
+      typeof obj === 'object' &&
+      obj !== null &&
+      typeof obj.session_id === 'string' &&
+      typeof obj.started_at === 'string' &&
+      typeof obj.mode === 'string' &&
+      typeof obj.pid === 'number' &&
+      typeof obj.host === 'string' &&
+      typeof obj.ttl_hours === 'number'
+    ) {
+      // Schema v1 → v2 normalisation: when `last_heartbeat` is absent or
+      // non-string, treat the lock as if it heartbeat-ed once at started_at.
+      const normalised = { ...obj };
+      if (typeof normalised.last_heartbeat !== 'string' || normalised.last_heartbeat.length === 0) {
+        normalised.last_heartbeat = normalised.started_at;
+      }
+      // semantic_session_id stays undefined when absent — callers that need it
+      // should fall back to session_id.
+      return normalised;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a fresh lock object from caller-supplied fields.
+ *
+ * Schema v2 (Epic #583, W2-I3): `last_heartbeat` is seeded equal to
+ * `started_at`. Callers MUST call `updateHeartbeat()` on a known cadence
+ * (session-start, inter-wave, session-end) to keep the lock alive past TTL.
+ *
+ * @param {{ sessionId: string, mode: string, ttlHours: number, semanticSessionId?: string }} args
+ * @returns {object}
+ */
+function buildLock({ sessionId, mode, ttlHours, semanticSessionId }) {
+  const startedAt = nowIso();
+  const lock = {
+    session_id: sessionId,
+    started_at: startedAt,
+    last_heartbeat: startedAt,
+    mode,
+    pid: process.pid,
+    host: os.hostname(),
+    ttl_hours: ttlHours,
+  };
+  if (typeof semanticSessionId === 'string' && semanticSessionId.length > 0) {
+    lock.semantic_session_id = semanticSessionId;
+  }
+  return lock;
+}
+
+/**
+ * Determine whether a lock is "live" based on its last_heartbeat freshness
+ * relative to TTL. Replaces PID-liveness as the primary discovery-time
+ * liveness check (Epic #583, W1-D1 + W1-D4 consensus): the writer-process
+ * PID is the *hook* PID, not the session PID, so PID-liveness incorrectly
+ * filtered out locks whose semantic owner (the Claude harness process) was
+ * still alive.
+ *
+ * Liveness rule: a lock is live when (now - last_heartbeat) < ttl_hours.
+ *
+ * @param {{ last_heartbeat: string, started_at: string, ttl_hours?: number }} lock
+ * @param {number} [nowMs]
+ * @returns {boolean}
+ */
+export function isLockLive(lock, nowMs = Date.now()) {
+  if (!lock || typeof lock !== 'object') return false;
+  // Back-compat: prefer last_heartbeat; fall back to started_at when absent.
+  const hbStr = (typeof lock.last_heartbeat === 'string' && lock.last_heartbeat.length > 0)
+    ? lock.last_heartbeat
+    : lock.started_at;
+  const heartbeatMs = Date.parse(hbStr);
+  if (Number.isNaN(heartbeatMs)) return false;
+  const ttlHours = typeof lock.ttl_hours === 'number' ? lock.ttl_hours : DEFAULT_TTL_HOURS;
+  const ttlMs = ttlHours * 3600 * 1000;
+  return (nowMs - heartbeatMs) < ttlMs;
+}
+
+/**
+ * Atomically write a lock object to disk.
+ * Uses a tmp file in a mkdtemp directory + rename to avoid a partial-write race.
+ * @param {string} lockFile  Absolute path to the lock file.
+ * @param {object} lock      Lock object to serialize.
+ * @returns {{ ok: true } | { ok: false, reason: 'fs-error', error: string }}
+ */
+function writeLockAtomic(lockFile, lock) {
+  try {
+    const dir = path.dirname(lockFile);
+    // Ensure .orchestrator/ directory exists.
+    fs.mkdirSync(dir, { recursive: true });
+
+    // Write to a uniquely-named temp file in the same directory so rename()
+    // is guaranteed to be an atomic same-filesystem operation on POSIX.
+    const tmpSuffix = crypto.randomBytes(6).toString('hex');
+    const tmpFile = path.join(dir, `.session.lock.tmp.${tmpSuffix}`);
+
+    fs.writeFileSync(tmpFile, JSON.stringify(lock, null, 2) + '\n', { encoding: 'utf8' });
+    fs.renameSync(tmpFile, lockFile);
+
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: 'fs-error', error: err.message };
+  }
+}
+
+/**
+ * Atomically create the session-lock file via tmp + hardlink (create-or-fail).
+ *
+ * TOCTOU fix (#590 Item 2): the previous fresh-acquire path used
+ * `writeLockAtomic` (tmp + renameSync), which is last-writer-wins — two
+ * concurrent SessionStart hooks that BOTH observed `readLock() === null` would
+ * BOTH rename their tmp file over the lock and BOTH believe they acquired it.
+ * `linkSync` is POSIX-atomic create-or-fail: exactly one concurrent caller wins
+ * the create, every other caller gets EEXIST. This is the same idiom used by
+ * the file-lock primitive (tryAcquireFileLock) backing the state-lock and
+ * staging-fence-lock modules.
+ *
+ * Used ONLY by the no-existing-lock branch of {@link acquire}. The
+ * intentional-overwrite paths (`forceAcquire`, `updateHeartbeat`) keep using
+ * `writeLockAtomic` because they MUST replace an existing lock, not fail on it.
+ *
+ * @param {string} lockFile  Absolute path to .orchestrator/session.lock.
+ * @param {object} lock      Lock object to serialize.
+ * @returns {{ ok: true } | { ok: false, reason: 'exists' } | { ok: false, reason: 'fs-error', error: string }}
+ */
+function createSessionLockExclusive(lockFile, lock) {
+  const dir = path.dirname(lockFile);
+  let tmpFile;
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpSuffix = crypto.randomBytes(8).toString('hex');
+    tmpFile = path.join(dir, `.session.lock.create.tmp.${tmpSuffix}`);
+    fs.writeFileSync(tmpFile, JSON.stringify(lock, null, 2) + '\n', { encoding: 'utf8' });
+  } catch (err) {
+    if (tmpFile) {
+      try { fs.unlinkSync(tmpFile); } catch { /* best-effort */ }
+    }
+    return { ok: false, reason: 'fs-error', error: err.message };
+  }
+
+  try {
+    fs.linkSync(tmpFile, lockFile);
+    return { ok: true };
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      return { ok: false, reason: 'exists' };
+    }
+    return { ok: false, reason: 'fs-error', error: err.message };
+  } finally {
+    try { fs.unlinkSync(tmpFile); } catch { /* best-effort */ }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exported API
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the lock file without modifying it.
+ * Returns the parsed lock object, or null if absent or unparseable.
+ * Never throws.
+ *
+ * @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 lockFile = lockPathFor(opts.repoRoot);
+  try {
+    const raw = fs.readFileSync(lockFile, 'utf8');
+    return parseLock(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Atomically acquire the session lock.
+ *
+ * Consults the P1.1 exclusivity-matrix when `activeSessions` is provided.
+ * When omitted, falls back to the legacy local-lock-only logic (backward compat).
+ *
+ * @param {object} args
+ * @param {string} args.sessionId
+ * @param {string} args.mode
+ * @param {number} [args.ttlHours]
+ * @param {string} [args.repoRoot]
+ * @param {string} [args.semanticSessionId]
+ *   Optional always-semantic session id (e.g., `<branch>-<date>-<mode>-<n>`).
+ *   When `sessionId` is a UUID (Claude Code path) and a semantic id is also
+ *   known, pass it here to be persisted alongside the UUID. Schema v2.
+ * @param {boolean} [args.quiet=false]
+ *   When true, the unknown-mode classify path SKIPS the `console.warn`-to-stderr
+ *   while still defaulting the caller-class to 'parallel-ok'. Added for #592
+ *   MED-2: the SessionStart hook (lock-bootstrap.mjs) must keep stderr empty,
+ *   and previously pre-sanitised the mode locally to dodge this warn. This flag
+ *   lets callers opt into silent unknown-mode handling without duplicating the
+ *   mode-mapping logic. PURELY ADDITIVE — default (warn) behaviour is unchanged,
+ *   and the raw `mode` is still persisted on the lock body either way.
+ * @param {Array<{mode:string,pid:number,host:string,sessionId:string}>} [args.activeSessions]
+ *   Optional pre-computed array from discoverActiveSessions(repoRoot). When omitted,
+ *   matrix consultation is skipped (legacy behavior). Callers (worktree-pipeline.mjs,
+ *   hooks/on-session-start.mjs) call discoverActiveSessions() themselves and pass the
+ *   result — this keeps acquire() synchronous.
+ *
+ * Returns one of:
+ *   { ok: true, lock, exclusivityClass? }
+ *       — 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: 'fs-error', error, exclusivityClass? }
+ *       — filesystem failure
+ *   { ok: false, reason: 'active-incompatible-exclusive', allActiveSessions, blockingSession, exclusivityClass }
+ *       — caller blocked by an active exclusive-class session (P1.2 #570)
+ *   { ok: false, reason: 'active-compatible-parallel', allActiveSessions, exclusivityClass }
+ *       — caller could create a parallel session; preamble offers Worktree-Auto-Promotion (P1.2 #570)
+ *   { ok: false, reason: 'active-readonly-bypass', allActiveSessions, exclusivityClass: 'always-ok' }
+ *       — caller is read-only-class; preamble passes through without AUQ (P1.2 #570).
+ *       Callers for 'always-ok' modes SHOULD interpret this as "proceed without AUQ, no lock needed".
+ *
+ * The `exclusivityClass` field is optional (undefined when activeSessions is not passed)
+ * and is added to ALL return shapes so callers can always observe the caller's class.
+ *
+ * The caller (session-start) decides whether to invoke forceAcquire() after
+ * obtaining user consent.
+ */
+export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoot, activeSessions, semanticSessionId, quiet = false } = {}) {
+  const lockFile = lockPathFor(repoRoot);
+
+  // -------------------------------------------------------------------------
+  // Safe classifyMode wrapper — unknown modes default to 'parallel-ok' (most
+  // permissive) rather than propagating an exception into the try/catch below
+  // where it would be silently turned into an 'fs-error'. A console.warn is
+  // emitted for visibility UNLESS the caller passes `quiet: true` (#592 MED-2 —
+  // lets lock-bootstrap.mjs keep stderr empty without pre-mapping the mode).
+  // This call is intentionally OUTSIDE the main try/catch so that only
+  // fs-errors reach the catch block.
+  // -------------------------------------------------------------------------
+  let callerClass;
+  try {
+    callerClass = classifyMode(mode);
+  } catch {
+    if (quiet !== true) {
+      console.warn(
+        `acquire: unknown mode "${mode}" — defaulting exclusivityClass to "parallel-ok". ` +
+        'Add the mode to exclusivity-matrix.mjs if intentional.',
+      );
+    }
+    callerClass = 'parallel-ok';
+  }
+
+  // -------------------------------------------------------------------------
+  // P1.2 exclusivity-matrix consultation — only when activeSessions is provided.
+  // Run BEFORE local-lock check so parallel-session conflicts surface first.
+  // -------------------------------------------------------------------------
+  if (Array.isArray(activeSessions) && activeSessions.length > 0) {
+    let hasCompatibleParallel = false;
+
+    for (const entry of activeSessions) {
+      // Safe classify for each active session's mode.
+      let entryClass;
+      try {
+        entryClass = classifyMode(entry.mode);
+      } catch {
+        // Unknown active session mode — treat as parallel-ok (most permissive default).
+        entryClass = 'parallel-ok';
+      }
+
+      if (entryClass === 'exclusive' && callerClass !== 'always-ok') {
+        // An exclusive active session blocks all non-always-ok callers.
+        return {
+          ok: false,
+          reason: 'active-incompatible-exclusive',
+          exclusivityClass: callerClass,
+          allActiveSessions: activeSessions,
+          blockingSession: entry,
+        };
+      }
+
+      if (entryClass === 'parallel-ok' && callerClass === 'parallel-ok') {
+        hasCompatibleParallel = true;
+      }
+    }
+
+    // After loop: handle always-ok bypass (read-only caller).
+    if (callerClass === 'always-ok') {
+      return {
+        ok: false,
+        reason: 'active-readonly-bypass',
+        exclusivityClass: 'always-ok',
+        allActiveSessions: activeSessions,
+      };
+    }
+
+    // Parallel-compatible situation: preamble should offer Worktree-Auto-Promotion.
+    if (hasCompatibleParallel) {
+      return {
+        ok: false,
+        reason: 'active-compatible-parallel',
+        exclusivityClass: callerClass,
+        allActiveSessions: activeSessions,
+      };
+    }
+
+    // All active sessions are 'always-ok' and caller is non-always-ok, or
+    // no blocking condition was found — fall through to local-lock check.
+  }
+
+  // -------------------------------------------------------------------------
+  // Local lock check — unchanged logic from original acquire().
+  // -------------------------------------------------------------------------
+  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.
+    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
+      // session's own PID (Epic #583, W1-D1 + W1-D4 consensus). Likewise,
+      // isTtlExpired measures age from started_at, which wrongly flags a
+      // long-running-but-heartbeating session as expired. Both bugs together
+      // produced the #744 incident: a live heartbeating session was
+      // misclassified 'stale-pid-dead' mid-wave.
+      if (isLockLive(existing)) {
+        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 };
+    };
+
+    const existing = readLock({ repoRoot });
+
+    if (existing !== null) {
+      // A lock is present — classify it.
+      return classifyExisting(existing);
+    }
+
+    // No existing lock — create one with a TOCTOU-safe create-or-fail (#590).
+    // Two concurrent SessionStart hooks can both reach this branch having each
+    // observed readLock() === null; linkSync guarantees exactly one wins.
+    const lock = buildLock({ sessionId, mode, ttlHours, semanticSessionId });
+    const createResult = createSessionLockExclusive(lockFile, lock);
+
+    if (createResult.ok) {
+      return { ok: true, lock, exclusivityClass: callerClass };
+    }
+    if (createResult.reason === 'fs-error') {
+      return { ok: false, reason: 'fs-error', error: createResult.error, exclusivityClass: callerClass };
+    }
+
+    // reason === 'exists' — we lost the create race. Re-read the now-present
+    // lock and classify it exactly as if we had seen it on the up-front check.
+    const raced = readLock({ repoRoot });
+    if (raced === null) {
+      // The EEXIST winner's lock vanished before we could re-read it (ENOENT /
+      // unparseable). Defensive fallback: report 'active' so the caller defers
+      // rather than racing again — mirrors tryAcquireStateLock's vanish-race
+      // handling (a lost-then-vanished race resolves conservatively).
+      return { ok: false, reason: 'active', existingLock: null, exclusivityClass: callerClass };
+    }
+    return classifyExisting(raced);
+  } catch (err) {
+    return { ok: false, reason: 'fs-error', error: err.message, exclusivityClass: callerClass };
+  }
+}
+
+/**
+ * Force-acquire the lock, unconditionally replacing any existing lock.
+ * Call only after the user has explicitly authorised stale-lock takeover.
+ *
+ * Returns:
+ *   { ok: true, lock, replacedLock? }       — lock written (replacedLock present if one was overwritten)
+ *   { ok: false, reason: 'fs-error', ... }  — filesystem failure
+ *
+ * @param {{ sessionId: string, mode: string, ttlHours?: number, repoRoot?: string, semanticSessionId?: string }} args
+ */
+export function forceAcquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoot, semanticSessionId } = {}) {
+  try {
+    const replacedLock = readLock({ repoRoot });
+    const lock = buildLock({ sessionId, mode, ttlHours, semanticSessionId });
+    const lockFile = lockPathFor(repoRoot);
+
+    const writeResult = writeLockAtomic(lockFile, lock);
+    if (!writeResult.ok) return writeResult;
+
+    const result = { ok: true, lock };
+    if (replacedLock !== null) result.replacedLock = replacedLock;
+    return result;
+  } catch (err) {
+    return { ok: false, reason: 'fs-error', error: err.message };
+  }
+}
+
+/**
+ * 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.
+ * Never throws.
+ *
+ * Post-delete verify (#744 Fix 3, refined): after unlinking, re-reads the
+ * lock path to confirm the delete was durable. The retry is **ownership-
+ * scoped** — only OUR OWN lock reappearing (same `session_id`) warrants a
+ * bounded retry unlink, which covers a transient unlink/stat race where our
+ * just-deleted file is briefly still observable. A FOREIGN lock (a
+ * different `session_id`) present at the re-read means a sibling session
+ * legitimately `acquire()`d the path in the race window between our unlink
+ * and this re-read — OUR lock is already gone (the delete succeeded), so
+ * this is treated as verified and the foreign lock is left untouched. This
+ * is load-bearing for PSA-005: a releaser must never unlink a lock it does
+ * not own, even indirectly via a "still present, so retry-unlink" heuristic
+ * that does not check who the present lock belongs to.
+ *
+ * `verified` is computed as "our lock is no longer present" — a foreign
+ * 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
+ * @returns {{ ok: true, deleted: boolean, reason?: string, verified?: boolean }}
+ */
+export function release({ sessionId, repoRoot } = {}) {
+  const lockFile = lockPathFor(repoRoot);
+  try {
+    const existing = readLock({ repoRoot });
+
+    if (existing === null) {
+      return { ok: true, deleted: false, reason: 'no-lock' };
+    }
+
+    if (existing.session_id !== sessionId) {
+      return { ok: true, deleted: false, reason: 'session-mismatch' };
+    }
+
+    fs.unlinkSync(lockFile);
+
+    // Post-delete verify: only retry when OUR OWN lock is still observable.
+    // A foreign lock here belongs to a sibling that re-acquired in the race
+    // window — never touch it (PSA-005).
+    let after = readLock({ repoRoot });
+    if (after !== null && after.session_id === sessionId) {
+      try {
+        fs.unlinkSync(lockFile);
+      } catch {
+        // best-effort retry — fall through to the final re-check regardless.
+      }
+      after = readLock({ repoRoot });
+    }
+
+    const verified = after === null || after.session_id !== sessionId;
+    return { ok: true, deleted: true, verified };
+  } catch (err) {
+    return { ok: false, reason: 'fs-error', error: err.message };
+  }
+}
+
+/**
+ * Refresh the `last_heartbeat` field on an existing lock, atomically.
+ *
+ * Schema v2 (Epic #583, W2-I3): the lock's liveness is determined by
+ * `(now - last_heartbeat) < ttl_hours`. Callers MUST invoke this on a known
+ * cadence (session-start, inter-wave, session-end) to keep the lock alive
+ * across long sessions.
+ *
+ * Same-session guard: refuses to update someone else's lock. Returns `false`
+ * when the lock is absent, malformed, or held by a different session_id.
+ * Returns `true` on a successful atomic update.
+ *
+ * Atomicity: same tmp + rename pattern as writeLockAtomic — single syscall
+ * visibility on POSIX. Never throws.
+ *
+ * @param {{ repoRoot?: string, sessionId: string }} opts
+ * @returns {boolean}
+ */
+export function updateHeartbeat({ repoRoot, sessionId } = {}) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return false;
+  const existing = readLock({ repoRoot });
+  if (existing === null) return false;
+  if (existing.session_id !== sessionId) return false;
+  const updated = { ...existing, last_heartbeat: nowIso() };
+  const lockFile = lockPathFor(repoRoot);
+  const writeResult = writeLockAtomic(lockFile, updated);
+  return writeResult.ok === true;
+}
+
+/**
+ * Inspect the lock file and compute staleness metadata.
+ *
+ * @param {{ repoRoot?: string }} [opts]
+ * @returns {{
+ *   exists: boolean,
+ *   lock: object|null,
+ *   ageHours: number|null,
+ *   ttlExpired: boolean,
+ *   pidAlive: boolean|null,
+ *   host: string|null,
+ *   sameHost: boolean,
+ *   isLive: boolean
+ * }}
+ */
+export function checkStale({ repoRoot } = {}) {
+  const lock = readLock({ repoRoot });
+
+  if (lock === null) {
+    return {
+      exists: false,
+      lock: null,
+      ageHours: null,
+      ttlExpired: false,
+      pidAlive: null,
+      host: null,
+      sameHost: false,
+      isLive: false,
+    };
+  }
+
+  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.
+  const isLive = isLockLive(lock);
+
+  return {
+    exists: true,
+    lock,
+    ageHours,
+    ttlExpired,
+    pidAlive,
+    host: lock.host,
+    sameHost,
+    isLive,
+  };
+}