sequant 2.9.0 → 2.11.0

package/dist/src/lib/locks/lock-manager.d.ts

@@ -7,6 +7,8 @@
  * `state.json`) keeps acquisition atomic — no read-modify-write race.
  *
  * Stale detection (in order):
+ *   0. Absolute ceiling (any host, any PID state): `startedAt > maxLockAgeMs
+ *      ago` → cleared. Guards against recycled PIDs and SIGKILL leaks (#856).
  *   1. `hostname === os.hostname()`: check `process.kill(pid, 0)`.
  *      Not alive → cleared.
  *   2. Cross-host: PID check is meaningless. Use age only.
@@ -16,7 +18,8 @@
  * method is a no-op (no fs touches, no warnings). Mirrors the
  * `OrchestratorRenderer` pattern at `src/lib/cli-ui/run-renderer.ts:244`.
  */
-import { type AcquireResult, type LockFile, type LockListing, type SignalOtherResult } from "./types.js";
+import { renameSync, linkSync } from "fs";
+import { type AcquireResult, type LockFile, type LockListing, type SignalOtherResult, type StaleReason } from "./types.js";
 export interface LockManagerOptions {
     /** Directory holding `<issue>.lock` files (default: `.sequant/locks`). */
     locksDir?: string;
@@ -31,6 +34,12 @@ export interface LockManagerOptions {
      * the lock has to bridge long /fullsolve runs with multi-iteration QA loops.
      */
     skillLockTtlMs?: number;
+    /**
+     * Absolute age ceiling (ms). A lock older than this is stale regardless of
+     * host, PID liveness, or `skipPidCheck`. Default 24h. See
+     * `DEFAULT_MAX_LOCK_AGE_MS` (#856).
+     */
+    maxLockAgeMs?: number;
     /** Override for orchestrator detection (test seam). */
     orchestratorMode?: boolean;
     /** Override for `os.hostname()` (test seam). */
@@ -44,7 +53,11 @@ export interface LockManagerOptions {
 }
 /** Detect orchestrator mode purely from env (no caching) so tests can mutate. */
 export declare function isOrchestratorMode(): boolean;
-/** Resolve the locks directory honoring `SEQUANT_LOCKS_DIR` for test isolation. */
+/**
+ * Resolve the locks directory. Priority: explicit option > `SEQUANT_LOCKS_DIR`
+ * > the shared git checkout root (#909) > plain cwd-relative (non-git
+ * fallback, preserves pre-#909 behavior).
+ */
 export declare function resolveLocksDir(explicit?: string): string;
 /**
  * Resolve `SEQUANT_SKILL_LOCK_TTL_MS` (milliseconds) — env override for the
@@ -52,6 +65,13 @@ export declare function resolveLocksDir(explicit?: string): string;
  * caller can fall back to the constructor option / default.
  */
 export declare function resolveSkillLockTtlMs(): number | null;
+/**
+ * Resolve `SEQUANT_MAX_LOCK_AGE_MS` (milliseconds) — env override for the
+ * absolute lock-age ceiling (#856). Returns `null` when unset or unparseable
+ * so the caller can fall back to the constructor option / default. Mirrors
+ * `resolveSkillLockTtlMs`.
+ */
+export declare function resolveMaxLockAgeMs(): number | null;
 /** Default same-host PID check. `process.kill(pid, 0)` throws if not alive. */
 export declare function defaultIsPidAlive(pid: number): boolean;
 /** Build the canonical "issue is in use" error message (AC: error format). */
@@ -67,12 +87,90 @@ export declare function classifyStaleness(args: {
     staleAgeMs: number;
     /** TTL for skill-shell (skipPidCheck) locks; falls back to staleAgeMs. */
     skillLockTtlMs?: number;
+    /** Absolute ceiling; falls back to `DEFAULT_MAX_LOCK_AGE_MS`. */
+    maxLockAgeMs?: number;
     isPidAlive: (pid: number) => boolean;
-}): "pid-dead" | "age-exceeded" | null;
+}): StaleReason | null;
+/** The fields that uniquely identify a lock's holder (any lock class). */
+export interface StaleLockIdentity {
+    pid: number;
+    hostname: string;
+    startedAt: string;
+}
+/**
+ * Atomically steal a stale lock (#908) — the compare-and-swap replacement for
+ * the old unlink-then-create, shared by both lock classes so they cannot drift
+ * (AC-1, AC-2).
+ *
+ * `unlink(lockPath)` removes whatever inode is at the path — including a fresh
+ * lock a winner created microseconds earlier — so two sessions that both
+ * classified the same lock stale could each destroy the other's fresh lock and
+ * both "win" (two holders, the exact failure the lock exists to prevent). A
+ * bare `rename(lockPath, …)` has the identical flaw: rename moves whatever is
+ * at the path, fresh or not.
+ *
+ * So take possession atomically, THEN check identity:
+ *
+ *   1. `rename(lockPath → tmp)` — atomic on POSIX. Of two racing stealers,
+ *      exactly one moves the current inode; the loser gets `ENOENT`.
+ *   2. Read what we moved. If it is the stale holder we `classified`, discard
+ *      it (`unlink tmp`) — the steal is legitimate and `lockPath` is now free
+ *      for the caller's terminal `openSync(…, "wx")` to claim.
+ *   3. If it is NOT that holder, a fresh lock appeared between our staleness
+ *      read and our rename. We must not destroy it: `link` it back into place
+ *      (never overwrites) and report the steal lost. A third session that
+ *      claimed `lockPath` in the gap is left intact and our copy becomes a
+ *      harmless `*.steal.*` orphan, which `list()` ignores (it matches only
+ *      `.lock`).
+ *
+ * Returns `true` only when this caller legitimately removed the stale lock it
+ * classified. `false` means "lost" — the caller falls through to `writeAtomic`,
+ * whose `O_CREAT|O_EXCL` arbitrates the real holder (accepting the current
+ * occupant on `EEXIST`).
+ *
+ * NOTE ON DEVIATION FROM THE #908 SPEC: the plan prescribed a *plain*
+ * rename-away ("rename, unlink tmp, ENOENT = lost", then fall through). That is
+ * behaviorally identical to the `unlink` it replaces — verified by a
+ * hand-driven interleave: in the issue's own documented ordering
+ * (`A.steal → A.create → B.steal → B.create`) B's rename succeeds on A's fresh
+ * lock and destroys it, two holders, same as today. The identity check in
+ * step 2/3 is what actually makes AC-1 ("loser cannot remove the winner's fresh
+ * lock") hold and makes AC-4's mutation test possible.
+ *
+ * RESIDUAL: the sub-millisecond window at step 3 where a third session's
+ * O_EXCL create races our `link`-back is not fully closed — plain lock files
+ * admit no atomic compare-and-swap on content. It is far narrower than the
+ * original (which failed on a *single* race, every time a stealer's removal
+ * landed on a fresh lock) and never destroys a live lock. Fully closing it is a
+ * larger protocol change (claim file / lease), flagged for follow-up.
+ *
+ * NEVER THROWS. A steal is an opportunistic optimization on the acquire path;
+ * no filesystem error here is worth crashing `acquire` over. Errors degrade to
+ * "lost" (`false`) and the caller's terminal create surfaces any real
+ * environment problem (EACCES etc.) with the same errno the pre-#908 path did.
+ * The one active recovery: if the `link`-back restore fails because the
+ * filesystem refuses hard links (EPERM/ENOTSUP), fall back to renaming `tmp`
+ * back into place — leaving a fresh lock renamed-away IS the two-holder bug,
+ * so restoring it outweighs `link`'s no-overwrite guarantee on such a
+ * filesystem.
+ *
+ * `ops` is a test seam for the link/rename syscalls — production callers omit
+ * it. Injecting a failing `link` is the only way to drive the fallback branch
+ * deterministically (capability errors like ENOTSUP cannot be provoked on a
+ * normal tmpdir).
+ */
+export declare function stealStaleLock(lockPath: string, classified: StaleLockIdentity, self: {
+    pid: number;
+    now: number;
+}, ops?: {
+    link?: typeof linkSync;
+    rename?: typeof renameSync;
+}): boolean;
 export declare class LockManager {
     private readonly locksDir;
     private readonly staleAgeMs;
     private readonly skillLockTtlMs;
+    private readonly maxLockAgeMs;
     private readonly orchestratorMode;
     private readonly hostname;
     private readonly pid;

package/dist/src/lib/locks/lock-manager.js

@@ -7,6 +7,8 @@
  * `state.json`) keeps acquisition atomic — no read-modify-write race.
  *
  * Stale detection (in order):
+ *   0. Absolute ceiling (any host, any PID state): `startedAt > maxLockAgeMs
+ *      ago` → cleared. Guards against recycled PIDs and SIGKILL leaks (#856).
  *   1. `hostname === os.hostname()`: check `process.kill(pid, 0)`.
  *      Not alive → cleared.
  *   2. Cross-host: PID check is meaningless. Use age only.
@@ -16,18 +18,57 @@
  * method is a no-op (no fs touches, no warnings). Mirrors the
  * `OrchestratorRenderer` pattern at `src/lib/cli-ui/run-renderer.ts:244`.
  */
-import { openSync, closeSync, writeSync, readFileSync, existsSync, unlinkSync, mkdirSync, readdirSync, statSync, } from "fs";
-import { join, resolve } from "path";
+import { openSync, closeSync, writeSync, readFileSync, existsSync, unlinkSync, renameSync, linkSync, mkdirSync, readdirSync, statSync, } from "fs";
+import { basename, dirname, join, resolve } from "path";
+import { execFileSync } from "child_process";
 import * as os from "os";
-import { DEFAULT_LOCKS_DIR, DEFAULT_SKILL_LOCK_TTL_MS, DEFAULT_STALE_AGE_MS, LockFileSchema, } from "./types.js";
+import { DEFAULT_LOCKS_DIR, DEFAULT_MAX_LOCK_AGE_MS, DEFAULT_SKILL_LOCK_TTL_MS, DEFAULT_STALE_AGE_MS, LockFileSchema, } from "./types.js";
 /** Detect orchestrator mode purely from env (no caching) so tests can mutate. */
 export function isOrchestratorMode() {
     return Boolean(process.env.SEQUANT_ORCHESTRATOR);
 }
-/** Resolve the locks directory honoring `SEQUANT_LOCKS_DIR` for test isolation. */
+/**
+ * Resolve the checkout root shared by the main worktree and every linked
+ * worktree of the same repository (#909). `--git-common-dir` (unlike
+ * `--show-toplevel`) points at the same physical `.git` for all of them, so
+ * a linked worktree lands on the main checkout's `.sequant/locks` instead of
+ * growing its own — matching what `pre-tool.sh`'s checkout guard reads.
+ * Returns `null` outside a git repository (or if `git` is unavailable).
+ *
+ * Deliberately omits `--path-format=absolute` (Git >=2.31, 2021): that flag
+ * failing on an older git would fall into the same `catch` as "not a repo"
+ * and silently re-open the bug this function exists to fix, with no signal
+ * that the cause was an old toolchain rather than a bare directory. Plain
+ * `--git-common-dir` (Git >=2.5, 2015) is resolved by hand instead —
+ * `resolve(cwd, out)` is a no-op when git already returned an absolute path
+ * (the common linked-worktree case) and anchors a relative one (the common
+ * main-checkout case) to `cwd`, so it is correct either way.
+ */
+function resolveGitCheckoutRoot(cwd) {
+    try {
+        const commonDir = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return commonDir ? dirname(resolve(cwd, commonDir)) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the locks directory. Priority: explicit option > `SEQUANT_LOCKS_DIR`
+ * > the shared git checkout root (#909) > plain cwd-relative (non-git
+ * fallback, preserves pre-#909 behavior).
+ */
 export function resolveLocksDir(explicit) {
     const fromEnv = process.env.SEQUANT_LOCKS_DIR;
-    return resolve(explicit ?? fromEnv ?? DEFAULT_LOCKS_DIR);
+    if (explicit !== undefined || fromEnv !== undefined) {
+        return resolve(explicit ?? fromEnv ?? DEFAULT_LOCKS_DIR);
+    }
+    const gitRoot = resolveGitCheckoutRoot(process.cwd());
+    return resolve(gitRoot ?? process.cwd(), DEFAULT_LOCKS_DIR);
 }
 /**
  * Resolve `SEQUANT_SKILL_LOCK_TTL_MS` (milliseconds) — env override for the
@@ -43,6 +84,21 @@ export function resolveSkillLockTtlMs() {
         return null;
     return ms;
 }
+/**
+ * Resolve `SEQUANT_MAX_LOCK_AGE_MS` (milliseconds) — env override for the
+ * absolute lock-age ceiling (#856). Returns `null` when unset or unparseable
+ * so the caller can fall back to the constructor option / default. Mirrors
+ * `resolveSkillLockTtlMs`.
+ */
+export function resolveMaxLockAgeMs() {
+    const raw = process.env.SEQUANT_MAX_LOCK_AGE_MS;
+    if (raw === undefined || raw === "")
+        return null;
+    const ms = Number.parseInt(raw, 10);
+    if (!Number.isFinite(ms) || ms <= 0)
+        return null;
+    return ms;
+}
 /** Default same-host PID check. `process.kill(pid, 0)` throws if not alive. */
 export function defaultIsPidAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
@@ -72,6 +128,19 @@ export function formatLockedMessage(issue, holder) {
 export function classifyStaleness(args) {
     const { holder, myHostname, now, staleAgeMs, isPidAlive } = args;
     const skillTtl = args.skillLockTtlMs ?? staleAgeMs;
+    const maxAge = args.maxLockAgeMs ?? DEFAULT_MAX_LOCK_AGE_MS;
+    const ageMs = now - Date.parse(holder.startedAt);
+    const ageKnown = Number.isFinite(ageMs);
+    // 0. Absolute ceiling, checked FIRST and unconditionally (#856). The
+    //    same-host branch below treats a live PID as proof of freshness, but a
+    //    PID is only a stable identity while its process lives — once the OS
+    //    recycles it, an abandoned lock points at an unrelated process and
+    //    reads as fresh forever. Nothing legitimate holds a lock this long
+    //    (24h vs a 30-minute phase timeout), so age wins over PID liveness
+    //    past the ceiling. Also the sole recovery path for locks leaked by a
+    //    SIGKILLed run, whose release handlers never got to run.
+    if (ageKnown && ageMs > maxAge)
+        return "max-age-exceeded";
     // 1. Same-host PID check is authoritative — except when the holder asked
     //    us to skip it (skill shells exit before the lock is released; their
     //    PID is dead but the skill is still running in Claude Code).
@@ -85,17 +154,195 @@ export function classifyStaleness(args) {
     //    with multi-iteration QA loops don't lose their own lock; cross-host
     //    uses the stricter staleAgeMs (default 2h).
     const ttl = holder.skipPidCheck ? skillTtl : staleAgeMs;
-    const ageMs = now - Date.parse(holder.startedAt);
-    if (!Number.isFinite(ageMs))
+    if (!ageKnown)
         return null;
     if (ageMs > ttl)
         return "age-exceeded";
     return null;
 }
+/** Read just the identity fields of a lock file. Null if missing/unparseable. */
+function readLockIdentity(lockPath) {
+    if (!existsSync(lockPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(lockPath, "utf-8"));
+        if (parsed &&
+            typeof parsed.pid === "number" &&
+            typeof parsed.hostname === "string" &&
+            typeof parsed.startedAt === "string") {
+            return {
+                pid: parsed.pid,
+                hostname: parsed.hostname,
+                startedAt: parsed.startedAt,
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best-effort unlink for a steal's private `tmp` file. Failure to remove it is
+ * never worth crashing `acquire` over — the orphan sweep below reclaims it.
+ */
+function unlinkBestEffort(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Best-effort: swept later by sweepStealOrphans.
+    }
+}
+/**
+ * Age past which a `<lock>.steal.<pid>.<ts>` file cannot be an in-flight steal
+ * (the live window is microseconds) and is reclaimed as an orphan.
+ */
+const STEAL_ORPHAN_TTL_MS = 10 * 60 * 1000;
+/**
+ * Reap aged `*.steal.*` orphans left behind by lost restore races (the
+ * documented EEXIST branch below). Best-effort throughout: steals are the only
+ * producer and the only consumer, `list()` never sees these files, and a
+ * failure here must not affect the steal itself.
+ */
+function sweepStealOrphans(lockPath, now) {
+    const prefix = `${basename(lockPath)}.steal.`;
+    try {
+        const dir = dirname(lockPath);
+        for (const name of readdirSync(dir)) {
+            if (!name.startsWith(prefix))
+                continue;
+            const orphan = join(dir, name);
+            try {
+                if (now - statSync(orphan).mtimeMs > STEAL_ORPHAN_TTL_MS) {
+                    unlinkSync(orphan);
+                }
+            }
+            catch {
+                // Raced away or unreadable — skip it.
+            }
+        }
+    }
+    catch {
+        // Locks dir unreadable — nothing to sweep.
+    }
+}
+/**
+ * Atomically steal a stale lock (#908) — the compare-and-swap replacement for
+ * the old unlink-then-create, shared by both lock classes so they cannot drift
+ * (AC-1, AC-2).
+ *
+ * `unlink(lockPath)` removes whatever inode is at the path — including a fresh
+ * lock a winner created microseconds earlier — so two sessions that both
+ * classified the same lock stale could each destroy the other's fresh lock and
+ * both "win" (two holders, the exact failure the lock exists to prevent). A
+ * bare `rename(lockPath, …)` has the identical flaw: rename moves whatever is
+ * at the path, fresh or not.
+ *
+ * So take possession atomically, THEN check identity:
+ *
+ *   1. `rename(lockPath → tmp)` — atomic on POSIX. Of two racing stealers,
+ *      exactly one moves the current inode; the loser gets `ENOENT`.
+ *   2. Read what we moved. If it is the stale holder we `classified`, discard
+ *      it (`unlink tmp`) — the steal is legitimate and `lockPath` is now free
+ *      for the caller's terminal `openSync(…, "wx")` to claim.
+ *   3. If it is NOT that holder, a fresh lock appeared between our staleness
+ *      read and our rename. We must not destroy it: `link` it back into place
+ *      (never overwrites) and report the steal lost. A third session that
+ *      claimed `lockPath` in the gap is left intact and our copy becomes a
+ *      harmless `*.steal.*` orphan, which `list()` ignores (it matches only
+ *      `.lock`).
+ *
+ * Returns `true` only when this caller legitimately removed the stale lock it
+ * classified. `false` means "lost" — the caller falls through to `writeAtomic`,
+ * whose `O_CREAT|O_EXCL` arbitrates the real holder (accepting the current
+ * occupant on `EEXIST`).
+ *
+ * NOTE ON DEVIATION FROM THE #908 SPEC: the plan prescribed a *plain*
+ * rename-away ("rename, unlink tmp, ENOENT = lost", then fall through). That is
+ * behaviorally identical to the `unlink` it replaces — verified by a
+ * hand-driven interleave: in the issue's own documented ordering
+ * (`A.steal → A.create → B.steal → B.create`) B's rename succeeds on A's fresh
+ * lock and destroys it, two holders, same as today. The identity check in
+ * step 2/3 is what actually makes AC-1 ("loser cannot remove the winner's fresh
+ * lock") hold and makes AC-4's mutation test possible.
+ *
+ * RESIDUAL: the sub-millisecond window at step 3 where a third session's
+ * O_EXCL create races our `link`-back is not fully closed — plain lock files
+ * admit no atomic compare-and-swap on content. It is far narrower than the
+ * original (which failed on a *single* race, every time a stealer's removal
+ * landed on a fresh lock) and never destroys a live lock. Fully closing it is a
+ * larger protocol change (claim file / lease), flagged for follow-up.
+ *
+ * NEVER THROWS. A steal is an opportunistic optimization on the acquire path;
+ * no filesystem error here is worth crashing `acquire` over. Errors degrade to
+ * "lost" (`false`) and the caller's terminal create surfaces any real
+ * environment problem (EACCES etc.) with the same errno the pre-#908 path did.
+ * The one active recovery: if the `link`-back restore fails because the
+ * filesystem refuses hard links (EPERM/ENOTSUP), fall back to renaming `tmp`
+ * back into place — leaving a fresh lock renamed-away IS the two-holder bug,
+ * so restoring it outweighs `link`'s no-overwrite guarantee on such a
+ * filesystem.
+ *
+ * `ops` is a test seam for the link/rename syscalls — production callers omit
+ * it. Injecting a failing `link` is the only way to drive the fallback branch
+ * deterministically (capability errors like ENOTSUP cannot be provoked on a
+ * normal tmpdir).
+ */
+export function stealStaleLock(lockPath, classified, self, ops = {}) {
+    const rename = ops.rename ?? renameSync;
+    const link = ops.link ?? linkSync;
+    const tmp = `${lockPath}.steal.${self.pid}.${self.now}`;
+    sweepStealOrphans(lockPath, self.now);
+    try {
+        rename(lockPath, tmp);
+    }
+    catch {
+        // ENOENT: another stealer moved it first — cleanly lost. Anything else
+        // (EACCES, EROFS, …): nothing was moved, so there is nothing to restore;
+        // report lost and let the terminal create surface the environment problem.
+        return false;
+    }
+    const moved = readLockIdentity(tmp);
+    if (moved &&
+        moved.pid === classified.pid &&
+        moved.hostname === classified.hostname &&
+        moved.startedAt === classified.startedAt) {
+        unlinkBestEffort(tmp);
+        return true;
+    }
+    // A fresh (or corrupt) holder slipped in between our read and our rename.
+    // Put back exactly what we took, without overwriting a newer claim, then
+    // lose the steal.
+    try {
+        link(tmp, lockPath);
+        unlinkBestEffort(tmp);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "EEXIST" && code !== "ENOENT") {
+            // Hard links refused (EPERM/ENOTSUP/…) — restore by rename instead.
+            // The overwrite risk this reintroduces needs a third session's create
+            // to land in this same sub-ms window ON a no-hardlink filesystem;
+            // not restoring at all destroys the fresh lock every time.
+            try {
+                rename(tmp, lockPath);
+            }
+            catch {
+                // Out of options — degrades to pre-#908 behavior on this filesystem.
+            }
+        }
+        // EEXIST: `lockPath` was re-claimed in the gap → leave `tmp` as an orphan
+        // (swept by sweepStealOrphans) rather than clobber the new holder.
+        // ENOENT: `tmp` already gone.
+    }
+    return false;
+}
 export class LockManager {
     locksDir;
     staleAgeMs;
     skillLockTtlMs;
+    maxLockAgeMs;
     orchestratorMode;
     hostname;
     pid;
@@ -110,6 +357,8 @@ export class LockManager {
             options.skillLockTtlMs ??
                 resolveSkillLockTtlMs() ??
                 DEFAULT_SKILL_LOCK_TTL_MS;
+        this.maxLockAgeMs =
+            options.maxLockAgeMs ?? resolveMaxLockAgeMs() ?? DEFAULT_MAX_LOCK_AGE_MS;
         this.orchestratorMode = options.orchestratorMode ?? isOrchestratorMode();
         this.hostname = options.hostname ?? os.hostname();
         this.pid = options.pid ?? process.pid;
@@ -156,10 +405,19 @@ export class LockManager {
                 now: this.now(),
                 staleAgeMs: this.staleAgeMs,
                 skillLockTtlMs: this.skillLockTtlMs,
+                maxLockAgeMs: this.maxLockAgeMs,
                 isPidAlive: this.isPidAlive,
             });
             if (staleReason) {
-                this.unlinkSafe(lockPath);
+                // Compare-and-swap steal, not a blind unlink (#908): only remove the
+                // stale inode we classified, never a fresh lock a racing winner may
+                // have created at this path in the meantime. Win or lose, fall through
+                // to `writeAtomic` — its `O_CREAT|O_EXCL` arbitrates the real holder.
+                stealStaleLock(lockPath, {
+                    pid: existing.pid,
+                    hostname: existing.hostname,
+                    startedAt: existing.startedAt,
+                }, { pid: this.pid, now: this.now() });
             }
             else {
                 return {
@@ -211,6 +469,15 @@ export class LockManager {
         if (holder.pid === this.pid || holder.pid === process.ppid) {
             return { sent: false, reason: "self-or-parent" };
         }
+        // #856: past the absolute ceiling, the PID is no longer trustworthy
+        // identity — the OS has almost certainly recycled it onto an unrelated
+        // process. `acquire` already treats such a lock as abandoned; signalling
+        // it would kill a stranger's program on behalf of a lock nobody holds.
+        // The liveness probe below cannot catch this: a recycled PID *is* alive.
+        const ageMs = this.now() - Date.parse(holder.startedAt);
+        if (Number.isFinite(ageMs) && ageMs > this.maxLockAgeMs) {
+            return { sent: false, reason: "stale-pid-untrusted" };
+        }
         if (!this.isPidAlive(holder.pid))
             return { sent: false, reason: "pid-dead" };
         try {
@@ -304,6 +571,7 @@ export class LockManager {
                 now,
                 staleAgeMs: this.staleAgeMs,
                 skillLockTtlMs: this.skillLockTtlMs,
+                maxLockAgeMs: this.maxLockAgeMs,
                 isPidAlive: this.isPidAlive,
             });
             out.push({
@@ -338,6 +606,7 @@ export class LockManager {
                 now: this.now(),
                 staleAgeMs: this.staleAgeMs,
                 skillLockTtlMs: this.skillLockTtlMs,
+                maxLockAgeMs: this.maxLockAgeMs,
                 isPidAlive: this.isPidAlive,
             });
             if (!staleReason) {

package/dist/src/lib/locks/types.d.ts

@@ -14,8 +14,32 @@ export declare const DEFAULT_STALE_AGE_MS: number;
  * Override per-process via `SEQUANT_SKILL_LOCK_TTL_MS` (milliseconds).
  */
 export declare const DEFAULT_SKILL_LOCK_TTL_MS: number;
+/**
+ * Absolute age ceiling (ms) beyond which a lock is stale no matter what
+ * (#856). Unlike the two TTLs above this one is NOT conditional on host or
+ * PID liveness: the same-host branch of `classifyStaleness` treats a live PID
+ * as authoritative proof of freshness, so before this ceiling existed a lock
+ * whose PID had been recycled by the OS read as fresh forever and blocked its
+ * issue permanently (observed: `505.lock` from 2026-05-14, `708.lock`,
+ * `803.lock`). It is also the recovery path for locks leaked by a SIGKILLed
+ * run, where no in-process release handler can ever fire.
+ *
+ * 24h is ~48x the 30-minute default phase timeout and 4x
+ * `DEFAULT_SKILL_LOCK_TTL_MS`, so no real run can reach it.
+ *
+ * Override per-process via `SEQUANT_MAX_LOCK_AGE_MS` (milliseconds).
+ */
+export declare const DEFAULT_MAX_LOCK_AGE_MS: number;
 /** Default lock directory relative to the project root. */
 export declare const DEFAULT_LOCKS_DIR = ".sequant/locks";
+/**
+ * Why a lock is considered stale, or `null` when it is fresh.
+ *
+ * - `pid-dead` — same-host holder PID is gone.
+ * - `age-exceeded` — cross-host / skill-shell lock past its TTL.
+ * - `max-age-exceeded` — past the absolute ceiling; applies unconditionally.
+ */
+export type StaleReason = "pid-dead" | "age-exceeded" | "max-age-exceeded";
 /** On-disk lock payload. */
 export declare const LockFileSchema: z.ZodObject<{
     pid: z.ZodNumber;
@@ -25,6 +49,78 @@ export declare const LockFileSchema: z.ZodObject<{
     skipPidCheck: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type LockFile = z.infer<typeof LockFileSchema>;
+/**
+ * Filename of the checkout-scoped lock (#901), stored alongside the numeric
+ * `<issue>.lock` files. Deliberately non-numeric so `LockManager.list()` —
+ * which parses each filename as an issue number and skips anything else —
+ * ignores it rather than surfacing a bogus `NaN` issue.
+ */
+export declare const CHECKOUT_LOCK_FILENAME = "checkout.lock";
+/**
+ * On-disk payload for the checkout-scoped lock (#901).
+ *
+ * The per-issue lock from #625 is keyed on issue number, so two sessions
+ * working *different* issues take different lock files and never contend —
+ * yet `git checkout`, `reset`, `rebase` and `merge` are global to a working
+ * tree. This lock represents the tree itself.
+ *
+ * Extends `LockFileSchema` with:
+ *  - `issue` — which issue the holder is working on, so a refusal can name it
+ *    (AC-2) and point the loser at the right worktree (AC-3).
+ *  - `sessionId` — Claude Code's per-session id, read from the PreToolUse
+ *    stdin envelope. Optional: it is the *preferred* holder identity because a
+ *    skill shell's PID dies immediately after acquire, but the hook falls back
+ *    to `pid`+`hostname` when the envelope does not carry one, so nothing
+ *    depends on it being present.
+ */
+export declare const CheckoutLockFileSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    hostname: z.ZodString;
+    startedAt: z.ZodString;
+    command: z.ZodString;
+    skipPidCheck: z.ZodOptional<z.ZodBoolean>;
+    issue: z.ZodNumber;
+    sessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CheckoutLockFile = z.infer<typeof CheckoutLockFileSchema>;
+/** Identity of the session asking for the checkout lock. */
+export interface CheckoutHolderIdentity {
+    /** Claude Code session id, when the caller knows it. */
+    sessionId?: string;
+    /** Falls back to these when `sessionId` is absent on either side. */
+    pid: number;
+    hostname: string;
+    /**
+     * The issue this session is working on (#906).
+     *
+     * Last-resort ownership proxy for `skipPidCheck` locks, whose PID is dead
+     * by the time anything checks it. Optional because a live process releasing
+     * its own lock identifies itself by PID and needs none of this — but a
+     * skill shell that omits it can no longer release, which is deliberate.
+     */
+    issue?: number;
+}
+/** Outcome of `CheckoutLock.acquire()`. */
+export type CheckoutAcquireResult = {
+    acquired: true;
+    lockPath: string;
+    /** True when the caller already held it — re-acquire is idempotent. */
+    reentrant: boolean;
+} | {
+    acquired: false;
+    holder: CheckoutLockFile;
+    lockPath: string;
+    stale: false;
+    staleReason: null;
+};
+/** Listing entry for the checkout lock, mirroring `LockListing`. */
+export interface CheckoutLockListing {
+    holder: CheckoutLockFile;
+    ageMs: number;
+    stale: boolean;
+    staleReason: StaleReason | null;
+    lockPath: string;
+}
 /** Outcome of `LockManager.acquire()`. */
 export type AcquireResult = {
     acquired: true;
@@ -35,7 +131,7 @@ export type AcquireResult = {
     lockPath: string;
     /** True when the holder appears stale and could be cleared with `--force`. */
     stale: boolean;
-    staleReason?: "pid-dead" | "age-exceeded" | null;
+    staleReason?: StaleReason | null;
 };
 /** Listing entry from `LockManager.list()`. */
 export interface LockListing {
@@ -43,7 +139,7 @@ export interface LockListing {
     holder: LockFile;
     ageMs: number;
     stale: boolean;
-    staleReason: "pid-dead" | "age-exceeded" | null;
+    staleReason: StaleReason | null;
     lockPath: string;
 }
 /**
@@ -51,7 +147,14 @@ export interface LockListing {
  * that previously all collapsed to `false`, so callers can produce accurate
  * log lines (#637).
  */
-export type SignalReason = "sent" | "orchestrator" | "cross-host" | "self-or-parent" | "pid-dead" | "kill-failed";
+export type SignalReason = "sent" | "orchestrator" | "cross-host" | "self-or-parent" | "pid-dead"
+/**
+ * Holder is past the absolute age ceiling, so its PID is not trustworthy
+ * identity (#856). Signalling it would target whatever process the OS has
+ * since recycled that PID onto — an unrelated program, killed by a
+ * `--force --signal-other` aimed at a lock abandoned weeks ago.
+ */
+ | "stale-pid-untrusted" | "kill-failed";
 /** Outcome of `LockManager.signalOther()`. */
 export interface SignalOtherResult {
     sent: boolean;