session-orchestrator 5.3.0 → 5.5.0

package/scripts/lib/session-lock.mjs

@@ -86,6 +86,45 @@ export {
 export const DEFAULT_TTL_HOURS = 4;
 export const LOCK_PATH = '.orchestrator/session.lock';
 
+/**
+ * How far in the future a `last_heartbeat` may lie and still count as live
+ * (#1494). Every heartbeat is stamped by `Date.now()` on the writing host, so
+ * on one host it is never ahead of the clock unless that clock was stepped
+ * backwards (NTP at boot, a manual change) — the tolerance absorbs such a step
+ * and cross-host skew on a shared checkout. Ceiling (BV-004): a clock stepped
+ * back by more than 5 minutes makes every live lock written just before it read
+ * as stale, and the next SessionStart reclaims it. Revisit if a `reclaimed`
+ * event follows a clock step on a host whose previous session was still running.
+ *
+ * Exported as the ONE copy of this tolerance (#1505.1/.2): the session registry
+ * (`session-registry.mjs` `_ageMinutes`) and the lock reaper (`lock-reaper.mjs`
+ * `ageHoursOf`, `currentSessionAgeHours`) apply the same future-stamp rule.
+ */
+export const FUTURE_HEARTBEAT_TOLERANCE_MS = 5 * 60 * 1000;
+
+/**
+ * The lock manager's own transient files beside `session.lock` (#1505.3): the
+ * `writeLockAtomic()` tmp (6 random bytes), the `createSessionLockExclusive()`
+ * tmp and the `reclaimIfNotLive()` tombstone (8 random bytes each). A process
+ * SIGKILLed between creating one and its cleanup leaves it behind for good.
+ * Anchored and exact so `session.lock` itself — or any foreign file — can
+ * never match.
+ */
+const LOCK_LEFTOVER_RE = /^\.session\.lock\.(?:tmp\.[0-9a-f]{12}|create\.tmp\.[0-9a-f]{16}|reclaim\.[0-9a-f]{16})$/;
+
+/**
+ * Minimum age before {@link sweepLockLeftovers} removes a leftover. Every one
+ * of them lives inside ONE synchronous call (write → rename/link → unlink),
+ * milliseconds long. Ceiling (BV-004): the age is taken from the later of
+ * mtime and ctime, because a tombstone is a RENAMED lock whose mtime is the
+ * old lock's last write; rename updates ctime (measured 2026-10-03 on APFS;
+ * ext4/xfs do too). On a filesystem whose rename touches neither, a tombstone
+ * could look old mid-reclaim — the tombstone content check below still keeps
+ * every live one. Revisit if a `reclaimed` event is followed by a lost
+ * link-back on such a filesystem.
+ */
+export const LOCK_LEFTOVER_MIN_AGE_MS = 60 * 60 * 1000;
+
 /**
  * Where the durable lock-ownership proof lives, relative to the repo root
  * (#987 Part 1). `.orchestrator/runtime/` is machine-local, gitignored state —
@@ -156,17 +195,18 @@ function lockAgeHours(lock) {
  * 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.
+ * (#1137). Reads `last_heartbeat` only, like `isLockLive()`: a lock without one
+ * has no heartbeat age, so this returns `null` rather than an age invented from
+ * `started_at` (#595, 2026-10-02 — the v1 fallback is gone).
  *
- * @param {{ last_heartbeat?: string, started_at?: string }} lock
- * @returns {number|null} minutes since the last heartbeat, or null if unparseable.
+ * @param {{ last_heartbeat?: string }} lock
+ * @returns {number|null} minutes since the last heartbeat, or null when the lock
+ *   carries no parseable `last_heartbeat`.
  */
 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 (typeof lock.last_heartbeat !== 'string' || lock.last_heartbeat.length === 0) return null;
+  const ts = Date.parse(lock.last_heartbeat);
   if (Number.isNaN(ts)) return null;
   return (Date.now() - ts) / (60 * 1000);
 }
@@ -179,20 +219,19 @@ function heartbeatAgeMinutes(lock) {
  * `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).
- *
- * RETAINED, not forgotten (#595, re-verified 2026-08-15): zero v1 files exist
- * on this host, but this normalisation is MIRRORED in
- * `scripts/lib/harness-audit/categories/category4.mjs` `lockIsLive()` and
- * pinned by `tests/lib/lock-ttl-parity.test.mjs`. Removing it here alone
- * breaks that parity by construction — see
- * `skills/_shared/state-ownership.md` § Schema v1 Sunset for the full
- * co-change set the removal needs.
+ * A lock WITHOUT `last_heartbeat` (#595 sunset, 2026-10-02) is returned as-is:
+ * its heartbeat is no longer filled in from `started_at`, and it is deliberately not
+ * rejected either. It stays VISIBLE — `readLockDetailed()` reports `ok` and
+ * `acquire()` classifies it `stale-heartbeat` (heartbeat age `null`), which
+ * lets the SessionStart bootstrap reclaim it — while `isLockLive()` reads it
+ * as not live. Rejecting it here would make it `corrupt`: still reclaimable
+ * (`acquire()` reports `corrupt` since 2026-10-02 — until then the
+ * create-or-fail hit EEXIST and the vanished-race branch answered `active`
+ * with `existingLock: null` on every attempt, wedging the repo), but invisible
+ * to every `readLock()` caller, which would lose its session_id, host and
+ * started_at. No writer has produced such a lock since Epic #583:
+ * `buildLock()`, the hook bootstrap and `updateHeartbeat()` all set
+ * `last_heartbeat`.
  *
  * @param {string} raw
  * @returns {object|null}
@@ -203,18 +242,9 @@ function parseLock(raw) {
     // The six-field predicate lives in ONE place (#1153 P7) — see
     // `./session-lock-shape.mjs` for the other consumer and the fail-open
     // drift this sharing prevents.
-    if (isLockShape(obj)) {
-      // 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;
+    // semantic_session_id stays undefined when absent — callers that need it
+    // should fall back to session_id.
+    return isLockShape(obj) ? obj : null;
   } catch {
     return null;
   }
@@ -241,14 +271,21 @@ function buildLock({ sessionId, mode, ttlHours, semanticSessionId }) {
     session_id: sessionId,
     started_at: startedAt,
     last_heartbeat: startedAt,
-    mode,
+    // mode and ttl_hours are coerced here because acquire()/forceAcquire() take
+    // them from hand-written callers (dispatcher claimRepo, the phase-1.2 prose)
+    // unchecked: `mode: undefined` vanished from the JSON and `ttlHours: null`
+    // or "4" had the wrong type, so the lock failed isLockShape() — and a lock
+    // that fails the shape is reclaimed as 'corrupt' by the next session even
+    // while its heartbeat is fresh. 'unknown' classifies like any unknown mode
+    // (parallel-ok, see the acquire() wrapper).
+    mode: typeof mode === 'string' && mode.trim().length > 0 ? mode : 'unknown',
     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,
+    ttl_hours: Number.isFinite(ttlHours) && ttlHours > 0 ? ttlHours : DEFAULT_TTL_HOURS,
   };
   if (typeof semanticSessionId === 'string' && semanticSessionId.length > 0) {
     lock.semantic_session_id = semanticSessionId;
@@ -266,24 +303,32 @@ function buildLock({ sessionId, mode, ttlHours, semanticSessionId }) {
  *
  * Liveness rule: a lock is live when (now - last_heartbeat) < ttl_hours.
  *
- * The `started_at` fallback below is RETAINED, not forgotten (#595,
- * re-verified 2026-08-15): it is mirrored verbatim in
- * `scripts/lib/harness-audit/categories/category4.mjs` `lockIsLive()` and
- * pinned by `tests/lib/lock-ttl-parity.test.mjs`. See
- * `skills/_shared/state-ownership.md` § Schema v1 Sunset.
+ * No `started_at` fallback (#595 sunset, 2026-10-02): a lock with no
+ * `last_heartbeat` is NOT live — nothing is heartbeating it, so it must not
+ * hold the repo for a TTL window counted from its start. The rule is mirrored
+ * in `scripts/lib/harness-audit/categories/category4.mjs` `lockIsLive()`, and
+ * `tests/lib/lock-ttl-parity.test.mjs` holds the two to identical verdicts.
+ * See `skills/_shared/state-ownership.md` § Schema v1 Sunset.
+ *
+ * A heartbeat stamped more than {@link FUTURE_HEARTBEAT_TOLERANCE_MS} in the
+ * future is NOT live either (#1494): `now - heartbeat` went negative, stayed
+ * below every TTL, and such a lock — a hand edit, a clock stepped backwards —
+ * held the repo until the wall clock caught up, a year for a year-ahead stamp.
+ * Same rule as the orphan-reaper's throttle marker (#1487,
+ * `orphan-reaper/scan-throttle.mjs` `shouldScanNow`), plus a tolerance: a
+ * marker in the future only costs one extra scan, a lock misread as dead is
+ * taken over while its owner still runs.
  *
- * @param {{ last_heartbeat: string, started_at: string, ttl_hours?: number }} lock
+ * @param {{ last_heartbeat: 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 (typeof lock.last_heartbeat !== 'string' || lock.last_heartbeat.length === 0) return false;
+  const heartbeatMs = Date.parse(lock.last_heartbeat);
   if (Number.isNaN(heartbeatMs)) return false;
+  if (heartbeatMs > nowMs + FUTURE_HEARTBEAT_TOLERANCE_MS) return false;
   const ttlHours = typeof lock.ttl_hours === 'number' ? lock.ttl_hours : DEFAULT_TTL_HOURS;
   const ttlMs = ttlHours * 3600 * 1000;
   return (nowMs - heartbeatMs) < ttlMs;
@@ -328,9 +373,12 @@ function writeLockAtomic(lockFile, lock) {
  * 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.
+ * Used by the no-existing-lock branch of {@link acquire} and by the
+ * single-winner reclaim (`forceAcquire({ onlyIfNotLive: true })` →
+ * `reclaimIfNotLive()`), which moves the old lock aside first and then needs
+ * exactly this create-or-fail. The unconditional overwrite paths (a plain
+ * `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.
@@ -481,8 +529,11 @@ export function readLockDetailed(opts = {}) {
  * 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: 'active', existingLock, ageHours, exclusivityClass? }
+ *       — local lock held: its last_heartbeat is within ttl_hours. `ageHours`
+ *         is the age from `started_at` (null when unparseable). `existingLock`
+ *         is null, `ageHours` null, only when a lost create race found the
+ *         winner's lock already gone.
  *   { 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` /
@@ -492,6 +543,18 @@ export function readLockDetailed(opts = {}) {
  *         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: 'corrupt', existingLock: null, exclusivityClass? }
+ *       — a lock file is present but fails parseLock() (invalid JSON, or not
+ *         the six-field lock shape). It can never be a live lock — every
+ *         writer writes atomically — so the SessionStart bootstrap reclaims it
+ *         with one stderr WARN. Before 2026-10-02 this case answered 'active'
+ *         with `existingLock: null` on every attempt and wedged the repo.
+ *   { ok: false, reason: 'unreadable', existingLock: null, error, exclusivityClass? }
+ *       — the lock path exists but cannot be read (EACCES, or a directory at
+ *         the path: EISDIR). Nothing was written and the path is left as it
+ *         is; the SessionStart bootstrap reports it (stderr WARN + a
+ *         `orchestrator.session.lock.read_anomaly` event) instead of reclaiming
+ *         it. Until #1494 this answered 'active' / existingLock:null silently.
  *   { ok: false, reason: 'missing-session-id' }
  *       — no usable `sessionId` given; NOTHING was written. Same reason string
  *         and same predicate as forceAcquire() (see its docblock for why an
@@ -536,6 +599,10 @@ export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoo
     return { ok: false, reason: 'missing-session-id' };
   }
 
+  // #1505.3: remove what a SIGKILLed writer or reclaimer left beside the lock.
+  // Result-neutral and best-effort: it never reads or touches `session.lock`.
+  try { sweepLockLeftovers({ repoRoot }); } catch { /* never blocks acquire */ }
+
   const lockFile = lockPathFor(repoRoot);
 
   // -------------------------------------------------------------------------
@@ -634,7 +701,16 @@ export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoo
       // 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 };
+        // ageHours is the figure the Phase-1.2 "active" prompt renders
+        // ("started <ageHours>h ago"); it was missing from this shape, so the
+        // prompt printed a value nothing had computed (#1494).
+        return {
+          ok: false,
+          reason: 'active',
+          existingLock: existing,
+          ageHours: lockAgeHours(existing),
+          exclusivityClass: callerClass,
+        };
       }
 
       // Heartbeat expired — ONE stale reason, derived from the same signal the
@@ -657,12 +733,42 @@ export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoo
       };
     };
 
-    const existing = readLock({ repoRoot });
-
-    if (existing !== null) {
+    // A file that is present but fails parseLock() — invalid JSON, or JSON
+    // without the six-field lock shape — gets its OWN reason instead of
+    // collapsing into the vanished-race branch below. It used to: readLock()
+    // returned null, the create-or-fail hit EEXIST on the file still there,
+    // the re-read was null again, and every attempt answered
+    // `active` / `existingLock: null` — which the bootstrap cannot reclaim, so
+    // one damaged file blocked every new session in the repo for good.
+    // Such a file can never be a live lock: all four production writers
+    // (createSessionLockExclusive, writeLockAtomic via forceAcquire and
+    // updateHeartbeat, the bootstrap's writeJsonAtomicSync) write a full
+    // buildLock() body via tmp+link / tmp+rename, so no reader ever sees a
+    // partial write. Reported, not cleared — the caller decides (see the
+    // decision-deferred note in the module header).
+    // Ceiling (BV-004): a future writer emitting a body that fails
+    // isLockShape() would be classified corrupt too. Revisit if the lock
+    // schema ever changes a required field's type or name.
+    const corrupt = () => ({ ok: false, reason: 'corrupt', existingLock: null, exclusivityClass: callerClass });
+
+    // A lock path that exists but cannot be read — EACCES, or a DIRECTORY at
+    // the path (EISDIR) — gets its own reason too (#1494, #599). It used to
+    // fall through to the create-or-fail, hit EEXIST and answer
+    // 'active' / existingLock:null, which nobody reports: the bootstrap
+    // neither forced nor warned, and every session ran without a lock, with
+    // no trace. Never reclaimed — what sits there was not written by a lock
+    // writer, and a directory may hold content nobody here created (PSA-003).
+    const unreadable = (error) => ({ ok: false, reason: 'unreadable', existingLock: null, error, exclusivityClass: callerClass });
+
+    const existing = readLockDetailed({ repoRoot });
+
+    if (existing.status === 'ok') {
       // A lock is present — classify it.
-      return classifyExisting(existing);
+      return classifyExisting(existing.lock);
     }
+    if (existing.status === 'corrupt') return corrupt();
+    if (existing.status === 'unreadable') return unreadable(existing.error);
+    // 'absent' → create below.
 
     // No existing lock — create one with a TOCTOU-safe create-or-fail (#590).
     // Two concurrent SessionStart hooks can both reach this branch having each
@@ -679,15 +785,15 @@ export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoo
 
     // 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);
+    const raced = readLockDetailed({ repoRoot });
+    if (raced.status === 'ok') return classifyExisting(raced.lock);
+    if (raced.status === 'corrupt') return corrupt();
+    if (raced.status === 'unreadable') return unreadable(raced.error);
+    // The EEXIST winner's lock vanished before we could re-read it (ENOENT).
+    // 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, ageHours: null, exclusivityClass: callerClass };
   } catch (err) {
     return { ok: false, reason: 'fs-error', error: err.message, exclusivityClass: callerClass };
   }
@@ -718,7 +824,14 @@ export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoo
  * no information while breaking the direct `forceAcquire()` calls documented in
  * `skills/session-start/references/phase-1-2-session-lock.md`.
  *
- * @param {{ sessionId: string, mode: string, ttlHours?: number, repoRoot?: string, semanticSessionId?: string }} args
+ * `onlyIfNotLive: true` (#1494) turns the unconditional overwrite into a
+ * single-winner takeover of a stale or corrupt lock: a lock that is live when
+ * it is moved aside is put back, and every lost race returns a fresh
+ * `acquire()` result instead of `ok: true` — see `reclaimIfNotLive()`. The
+ * SessionStart bootstrap passes it for its `stale-heartbeat` / `corrupt`
+ * reclaims; the operator-approved force-take of a LIVE lock (Phase 1.2) omits it.
+ *
+ * @param {{ sessionId: string, mode: string, ttlHours?: number, repoRoot?: string, semanticSessionId?: string, onlyIfNotLive?: boolean }} args
  */
 /**
  * A `sessionId` is usable only when it is a non-blank string. ONE predicate,
@@ -733,10 +846,13 @@ function hasUsableSessionId(sessionId) {
   return typeof sessionId === 'string' && sessionId.trim().length > 0;
 }
 
-export function forceAcquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoot, semanticSessionId } = {}) {
+export function forceAcquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoot, semanticSessionId, onlyIfNotLive = false } = {}) {
   if (!hasUsableSessionId(sessionId)) {
     return { ok: false, reason: 'missing-session-id' };
   }
+  if (onlyIfNotLive === true) {
+    return reclaimIfNotLive({ sessionId, mode, ttlHours, repoRoot, semanticSessionId });
+  }
   try {
     const replacedLock = readLock({ repoRoot });
     const lock = buildLock({ sessionId, mode, ttlHours, semanticSessionId });
@@ -753,6 +869,143 @@ export function forceAcquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, re
   }
 }
 
+/**
+ * Single-winner takeover of a stale or corrupt lock — `forceAcquire({
+ * onlyIfNotLive: true })` (#1494).
+ *
+ * The plain force is last-writer-wins: two SessionStarts that both saw the same
+ * stale lock both forced it, both got `ok: true`, and the later rename won while
+ * the loser kept running as if it held the lock. Here the lock is first renamed
+ * to a unique tombstone. A rename moves exactly one directory entry, so only one
+ * caller can hold the moved file; it is judged only then, from the tombstone:
+ *   - not live (stale, heartbeat-less, unparseable) → replaced via the same
+ *     create-or-fail link as a fresh acquire();
+ *   - live → a racer finished its takeover between our acquire() read and our
+ *     rename, and what we moved is ITS lock: linked back, never replaced.
+ * Every losing path — the rename finds nothing (ENOENT: a racer moved it
+ * first), the create finds a lock (EEXIST), the moved lock was live — ends in
+ * ONE fresh `acquire()`, which reads whatever sits at the path now and answers
+ * as on a first look (normally `active` with the winner's lock).
+ *
+ * Ceilings (BV-004), both reachable with TWO SessionStarts:
+ * (1) A racer's fresh lock that we move and link back is absent for that
+ * window, and any reader in it sees no lock. The reader most likely to land
+ * there is the winner's own bootstrap re-reading the lock it just acquired, so
+ * `hooks/_lib/lock-bootstrap.mjs` re-reads on ENOENT (5 × 10 ms) instead of
+ * giving up the enrichment; a third reader just sees "absent" briefly.
+ * (2) A lock that turned LIVE after both starts read it stale — its own owner
+ * heartbeated in between — is moved by one start while the other's rename
+ * finds nothing and its fresh `acquire()` creates a lock in the empty path. The
+ * link-back then fails with EEXIST and the owner's lock is dropped; the owner
+ * learns it at its next heartbeat (updateHeartbeat() returns false on the
+ * session mismatch). Not a regression: the plain force overwrote that live lock
+ * unconditionally. Revisit if a `reclaimed` event pair within one second shows
+ * up in events.jsonl again, or a session's heartbeat starts failing right after
+ * another start reclaimed its lock.
+ *
+ * @param {{ sessionId: string, mode: string, ttlHours: number, repoRoot?: string, semanticSessionId?: string }} args
+ * @returns {object} forceAcquire()'s `{ ok: true, lock, replacedLock? }` or
+ *   `fs-error` shape, or — on a lost race — the result of a fresh `acquire()`.
+ */
+function reclaimIfNotLive({ sessionId, mode, ttlHours, repoRoot, semanticSessionId }) {
+  const lockFile = lockPathFor(repoRoot);
+  const reacquire = () => acquire({ sessionId, mode, ttlHours, repoRoot, semanticSessionId, quiet: true });
+  const tomb = path.join(path.dirname(lockFile), `.session.lock.reclaim.${crypto.randomBytes(8).toString('hex')}`);
+
+  try {
+    fs.renameSync(lockFile, tomb);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return reacquire();
+    return { ok: false, reason: 'fs-error', error: err.message };
+  }
+
+  let keepTomb = false;
+  try {
+    let raw;
+    try {
+      raw = fs.readFileSync(tomb, 'utf8');
+    } catch {
+      // Unjudgeable — something unreadable replaced the stale file after
+      // acquire() read it. Not ours to drop: put it back (a directory cannot
+      // be hard-linked, and renaming a directory never replaces a file); if
+      // the path is taken by then, it stays under the tombstone name.
+      keepTomb = true;
+      try {
+        if (fs.lstatSync(tomb).isDirectory()) fs.renameSync(tomb, lockFile);
+        else { fs.linkSync(tomb, lockFile); keepTomb = false; }
+      } catch { /* stays at the tombstone name */ }
+      return reacquire();
+    }
+
+    const moved = parseLock(raw);
+    if (moved !== null && isLockLive(moved)) {
+      try { fs.linkSync(tomb, lockFile); } catch { /* ceiling (2) above */ }
+      return reacquire();
+    }
+
+    const lock = buildLock({ sessionId, mode, ttlHours, semanticSessionId });
+    const created = createSessionLockExclusive(lockFile, lock);
+    if (created.ok) {
+      const result = { ok: true, lock };
+      if (moved !== null) result.replacedLock = moved;
+      return result;
+    }
+    if (created.reason === 'exists') return reacquire();
+    return created;
+  } finally {
+    if (!keepTomb) {
+      try { fs.unlinkSync(tomb); } catch { /* best-effort */ }
+    }
+  }
+}
+
+/**
+ * Remove the lock manager's own leftovers beside `session.lock` (#1505.3) —
+ * files named exactly like {@link LOCK_LEFTOVER_RE}, regular files only (lstat:
+ * a symlink, directory or anything else is never followed nor removed), last
+ * touched more than {@link LOCK_LEFTOVER_MIN_AGE_MS} ago. A tombstone is
+ * removed only on the decision its killed reclaimer would have taken itself:
+ * readable and not a live lock. An unreadable one is kept, as
+ * `reclaimIfNotLive()` keeps it. Unlinking a tombstone removes only that NAME —
+ * when it is still a hard link to the primary lock's inode (killed between
+ * link-back and unlink), `session.lock` keeps its content.
+ *
+ * Never throws; a file that vanished or cannot be removed is skipped.
+ *
+ * @param {{ repoRoot?: string, nowMs?: number }} [opts]
+ * @returns {{ removed: string[] }} basenames removed
+ */
+export function sweepLockLeftovers({ repoRoot, nowMs = Date.now() } = {}) {
+  const removed = [];
+  let dir;
+  let names;
+  try {
+    dir = path.dirname(lockPathFor(repoRoot));
+    names = fs.readdirSync(dir);
+  } catch {
+    return { removed };
+  }
+  for (const name of names) {
+    if (!LOCK_LEFTOVER_RE.test(name)) continue;
+    const full = path.join(dir, name);
+    try {
+      const st = fs.lstatSync(full);
+      if (!st.isFile()) continue;
+      // A future mtime/ctime (clock stepped back) yields a negative age: kept.
+      if (!(nowMs - Math.max(st.mtimeMs, st.ctimeMs) > LOCK_LEFTOVER_MIN_AGE_MS)) continue;
+      if (name.startsWith('.session.lock.reclaim.')) {
+        let raw;
+        try { raw = fs.readFileSync(full, 'utf8'); } catch { continue; }
+        const moved = parseLock(raw);
+        if (moved !== null && isLockLive(moved, nowMs)) continue;
+      }
+      fs.unlinkSync(full);
+      removed.push(name);
+    } catch { /* vanished or unremovable — best-effort */ }
+  }
+  return { removed };
+}
+
 /**
  * Extract an ownership-proof object from a lock — the field-name translation
  * layer `isLockOwnedByProof()` expects. Intended usage: a caller that just