sequant 2.10.0 → 2.12.0

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

@@ -0,0 +1,389 @@
+/**
+ * CheckoutLock — working-tree-scoped lock (#901).
+ *
+ * The per-issue lock from #625 keys on issue number, so two sessions working
+ * different issues take different lock files and never contend. But
+ * `git checkout`, `switch`, `reset`, `rebase`, `merge` and `cherry-pick` are
+ * global to a working tree: the contended resource is the *checkout*, not the
+ * issue. This lock represents the checkout.
+ *
+ * Relationship to `LockManager`:
+ *   - Stale semantics are *shared code*, not a parallel implementation — this
+ *     class calls the same exported `classifyStaleness`, so the same-host
+ *     dead-PID rule, the age ceiling and `SEQUANT_MAX_LOCK_AGE_MS` behave
+ *     identically by construction (AC-4).
+ *   - `LockManager`'s numeric key is left alone. Widening `lockPathFor` /
+ *     `acquire` / `release` / `list` / `held` from `number` to `string` would
+ *     ripple through `status.ts`, `merge.ts`, `resume.ts` and
+ *     `run-orchestrator.ts`, all of which pass real issue numbers, for the
+ *     benefit of exactly one new key. The cost of not widening is the
+ *     duplicated `O_CREAT|O_EXCL` write below (~30 lines).
+ *
+ * Orchestrator / MCP mode: every public method is a no-op, mirroring
+ * `LockManager` (AC-5).
+ */
+import { openSync, closeSync, writeSync, readFileSync, existsSync, unlinkSync, mkdirSync, } from "fs";
+import { join } from "path";
+import * as os from "os";
+import { classifyStaleness, defaultIsPidAlive, isOrchestratorMode, resolveLocksDir, resolveMaxLockAgeMs, resolveSkillLockTtlMs, stealStaleLock, } from "./lock-manager.js";
+import { CHECKOUT_LOCK_FILENAME, CheckoutLockFileSchema, DEFAULT_MAX_LOCK_AGE_MS, DEFAULT_SKILL_LOCK_TTL_MS, DEFAULT_STALE_AGE_MS, } from "./types.js";
+/**
+ * Reserved holder id for `/release`, which mutates the main checkout but has
+ * no issue of its own (#911). The lock file and the `pre-tool.sh` guard both
+ * key on a positive integer, so the skill claims the tree under this sentinel
+ * rather than a symbolic label (which would require schema + CLI + hook
+ * changes — tracked in #911 as a follow-up).
+ */
+export const RELEASE_SENTINEL_ISSUE = 999999999;
+/**
+ * Render a checkout-lock holder's issue for CLI display. The sentinel is not
+ * a real issue, and printing it as `#999999999` invites readers to go looking
+ * for one.
+ */
+export function describeCheckoutHolderIssue(issue) {
+    return issue === RELEASE_SENTINEL_ISSUE ? "/release (sentinel)" : `#${issue}`;
+}
+/**
+ * Does `identity` own the checkout `holder` claimed? (#906)
+ *
+ * One predicate for both `acquire`'s reentrancy check and `release`'s
+ * permission check, so the two cannot disagree about who the holder is: a
+ * session able to release by a given identity is exactly the one able to
+ * re-acquire by it. Exported for the hook-parity tests.
+ *
+ * The rules are ordered, and the order is load-bearing:
+ *
+ *  1. Cross-host callers never own the lock. Checked first — no weaker rule
+ *     below may overturn it.
+ *  2. When *both* sides carry a `sessionId`, equality decides and nothing
+ *     falls through: a mismatch is positive proof of non-ownership, so
+ *     consulting a weaker signal afterwards could only overturn a stronger
+ *     one. (Dormant in the shipped flow — no env var carries Claude Code's
+ *     session id into a skill shell, so `acquire` never passes one. Kept
+ *     because leaking a lock for its TTL is the safer failure.)
+ *  3. Same PID on the same host: a live process releasing its own lock.
+ *  4. `skipPidCheck` locks only: the holder's issue number. A skill shell's
+ *     PID is dead by the time the next block runs — that is what
+ *     `skipPidCheck` marks — so the issue is the only identity left, and the
+ *     hook's blocking side (`pre-tool.sh`) already decides holder-ness the
+ *     same way. Deliberately a *courtesy* check, not a security boundary:
+ *     the issue number is readable from the lock file and `clear --force`
+ *     exists. It defends against the accident this rule was written for — a
+ *     *blocked* session running its release contract, which by construction
+ *     carries a different issue.
+ *  5. Anything else is refused.
+ */
+export function isCheckoutOwner(holder, identity) {
+    if (holder.hostname !== identity.hostname)
+        return false;
+    if (holder.sessionId && identity.sessionId) {
+        return holder.sessionId === identity.sessionId;
+    }
+    if (holder.pid === identity.pid)
+        return true;
+    if (holder.skipPidCheck === true &&
+        identity.issue !== undefined &&
+        identity.issue === holder.issue) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Build the refusal text for a blocked session (AC-2 + AC-3).
+ *
+ * AC-2 requires the message name the holding session and its issue; AC-3
+ * requires it say how to proceed rather than only reporting the block. Both
+ * halves are produced here, in one place, so the CLI and the hook cannot
+ * drift on wording.
+ *
+ * @param holder    The session currently holding the checkout.
+ * @param blocked   The issue the *refused* session is working on, when known —
+ *                  used to name the worktree it should be using instead.
+ * @param nowMs     Clock, for the human-readable age.
+ */
+export function formatCheckoutLockedMessage(holder, blocked = {}, nowMs = Date.now()) {
+    const ageMs = nowMs - Date.parse(holder.startedAt);
+    const ageText = Number.isFinite(ageMs)
+        ? `${Math.max(0, Math.floor(ageMs / 60_000))}m ago`
+        : "unknown age";
+    const lines = [
+        `The working tree is held by the session working #${holder.issue} ` +
+            `(PID ${holder.pid} on ${holder.hostname}, started ${holder.startedAt}, ${ageText}).`,
+        `Command: ${holder.command}`,
+        "",
+        "Branch-mutating git operations here would race with that session.",
+        "",
+        "To proceed:",
+    ];
+    if (blocked.issue !== undefined) {
+        lines.push(`  • Work in your own worktree instead: ../worktrees/feature/${blocked.issue}-*/`, `    (create it with: ./scripts/new-feature.sh ${blocked.issue})`);
+    }
+    else {
+        lines.push("  • Work in your issue's worktree instead: ../worktrees/feature/<issue>-*/", "    (create it with: ./scripts/new-feature.sh <issue>)");
+    }
+    lines.push("  • Or run the command with `git -C <worktree>` so it does not touch this tree.", "  • If that session is gone, clear the stale holder:", 
+    // `--force` is not optional advice (#906). Plain `clear` refuses a holder
+    // that still reads fresh, and a leaked skill-shell lock reads fresh for
+    // the full 6h TTL — so the un-forced form fails in exactly the situation
+    // that sends someone here.
+    "      sequant locks checkout clear --force");
+    return lines.join("\n");
+}
+export class CheckoutLock {
+    locksDir;
+    staleAgeMs;
+    skillLockTtlMs;
+    maxLockAgeMs;
+    orchestratorMode;
+    hostname;
+    pid;
+    isPidAlive;
+    now;
+    constructor(options = {}) {
+        this.locksDir = resolveLocksDir(options.locksDir);
+        this.staleAgeMs = options.staleAgeMs ?? DEFAULT_STALE_AGE_MS;
+        this.skillLockTtlMs =
+            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;
+        this.isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
+        this.now = options.now ?? Date.now;
+    }
+    /** True if all operations are no-ops (orchestrator/MCP mode). */
+    get isNoop() {
+        return this.orchestratorMode;
+    }
+    /** Absolute path to the checkout lock file. */
+    get lockPath() {
+        return join(this.locksDir, CHECKOUT_LOCK_FILENAME);
+    }
+    /**
+     * This process's identity, for callers that don't have a session id.
+     *
+     * Deliberately carries no `issue` (#906): a bare `release()` losing the
+     * power to remove a *skill-shell* lock is the fix working, not an omission.
+     * A caller that legitimately owns such a lock knows its issue and must say
+     * so — `release({ ...lock.selfIdentity, issue })`.
+     */
+    get selfIdentity() {
+        return { pid: this.pid, hostname: this.hostname };
+    }
+    /**
+     * Claim the checkout for `issue`.
+     *
+     * Re-acquiring while already the holder succeeds idempotently
+     * (`reentrant: true`) — a session must not be able to block itself part-way
+     * through its own run.
+     */
+    acquire(issue, command, options = {}) {
+        if (this.orchestratorMode) {
+            return { acquired: true, lockPath: "", reentrant: false };
+        }
+        const lockPath = this.lockPath;
+        mkdirSync(this.locksDir, { recursive: true });
+        const existing = this.readSafe(lockPath);
+        if (existing) {
+            // `issue` belongs in the identity for the same reason `release` needs
+            // it (#906): without it a session could release its own skill-shell
+            // lock by issue but not re-acquire it, and acquire would refuse the
+            // holder against its own lock part-way through a run.
+            const identity = {
+                sessionId: options.sessionId,
+                pid: this.pid,
+                hostname: this.hostname,
+                issue,
+            };
+            if (isCheckoutOwner(existing, identity)) {
+                return { acquired: true, lockPath, reentrant: true };
+            }
+            const staleReason = this.staleness(existing);
+            if (staleReason) {
+                // Compare-and-swap steal, not a blind unlink (#908): shared with
+                // `LockManager` via `stealStaleLock` so the two lock classes cannot
+                // drift. Only the classified stale inode is removed — never a fresh
+                // lock a racing winner created at this path. Fall through to
+                // `writeAtomic` regardless; its `O_CREAT|O_EXCL` picks the real holder.
+                stealStaleLock(lockPath, {
+                    pid: existing.pid,
+                    hostname: existing.hostname,
+                    startedAt: existing.startedAt,
+                }, { pid: this.pid, now: this.now() });
+            }
+            else {
+                return {
+                    acquired: false,
+                    holder: existing,
+                    lockPath,
+                    stale: false,
+                    staleReason: null,
+                };
+            }
+        }
+        return this.writeAtomic(lockPath, issue, command, options);
+    }
+    /**
+     * Release the checkout if `identity` owns it. Returns true when a lock was
+     * removed — `false` covers both "nothing held" and "held, but not yours".
+     *
+     * Ownership is `isCheckoutOwner`, the same predicate `acquire` uses. Before
+     * #906 this method took any same-host caller's word for a `skipPidCheck`
+     * lock, which made acquire and release asymmetric in the one scenario the
+     * lock exists for: a second session's *acquire* was correctly refused while
+     * the holder was fresh, but its *release* — which every `/fullsolve` halt
+     * branch runs — succeeded and handed the tree away mid-run.
+     *
+     * `LockManager.releaseExternal` keeps the looser same-host rule safely
+     * because its lock *file* is issue-keyed: naming the file already proves the
+     * caller knows the issue. `checkout.lock` has a constant filename, so that
+     * proof has to move into the identity — which is exactly what rule 4 of
+     * `isCheckoutOwner` asks for.
+     */
+    release(identity) {
+        if (this.orchestratorMode)
+            return false;
+        const lockPath = this.lockPath;
+        const current = this.readSafe(lockPath);
+        if (!current)
+            return false;
+        if (!isCheckoutOwner(current, identity ?? this.selfIdentity))
+            return false;
+        this.unlinkSafe(lockPath);
+        return true;
+    }
+    /** Read the holder without acquiring. Null when free or unparseable. */
+    check() {
+        if (this.orchestratorMode)
+            return null;
+        return this.readSafe(this.lockPath);
+    }
+    /** Holder plus computed staleness metadata, for `locks list`. */
+    listing() {
+        if (this.orchestratorMode)
+            return null;
+        const holder = this.readSafe(this.lockPath);
+        if (!holder)
+            return null;
+        const ageMs = this.now() - Date.parse(holder.startedAt);
+        const staleReason = this.staleness(holder);
+        return {
+            holder,
+            ageMs: Number.isFinite(ageMs) ? ageMs : 0,
+            stale: staleReason !== null,
+            staleReason,
+            lockPath: this.lockPath,
+        };
+    }
+    /**
+     * Manually clear the checkout lock. With `safetyCheck` (default), refuses to
+     * clear a holder that is still fresh — mirrors `LockManager.clearLock`.
+     *
+     * A file that exists but does not parse is removed unconditionally (#906).
+     * That state is reachable: `writeAtomic` creates the file with `openSync`
+     * and writes to it as a second step, so a process killed in between leaves a
+     * zero-byte `checkout.lock` (#856 documents the group-SIGKILL that does it).
+     * Before this branch existed such a file was unclearable by any command —
+     * `clear` read it, saw `null`, and reported `no-lock` without unlinking
+     * (`--force` only ever reached the *staleness* check, never the read), while
+     * `acquire` threw raw `EEXIST` and the hook, unable to parse any field,
+     * blocked on it forever. `safetyCheck` is not consulted because there is no
+     * holder to protect: unparseable bytes name no session.
+     */
+    clear(options = {}) {
+        if (this.orchestratorMode) {
+            return { cleared: false, reason: "orchestrator-mode" };
+        }
+        const safetyCheck = options.safetyCheck ?? true;
+        const lockPath = this.lockPath;
+        const holder = this.readSafe(lockPath);
+        if (!holder) {
+            if (existsSync(lockPath)) {
+                this.unlinkSafe(lockPath);
+                return { cleared: true, reason: "cleared-corrupt" };
+            }
+            return { cleared: false, reason: "no-lock" };
+        }
+        if (safetyCheck && !this.staleness(holder)) {
+            return { cleared: false, reason: "fresh-holder" };
+        }
+        this.unlinkSafe(lockPath);
+        return { cleared: true, reason: "cleared" };
+    }
+    // ── internals ────────────────────────────────────────────────────────────
+    /**
+     * Delegates wholesale to the per-issue lock's classifier so the two locks
+     * cannot drift on staleness (AC-4).
+     */
+    staleness(holder) {
+        return classifyStaleness({
+            holder,
+            myHostname: this.hostname,
+            now: this.now(),
+            staleAgeMs: this.staleAgeMs,
+            skillLockTtlMs: this.skillLockTtlMs,
+            maxLockAgeMs: this.maxLockAgeMs,
+            isPidAlive: this.isPidAlive,
+        });
+    }
+    writeAtomic(lockPath, issue, command, options) {
+        const payload = {
+            pid: this.pid,
+            hostname: this.hostname,
+            startedAt: new Date(this.now()).toISOString(),
+            command,
+            issue,
+            ...(options.sessionId ? { sessionId: options.sessionId } : {}),
+            ...(options.skipPidCheck ? { skipPidCheck: true } : {}),
+        };
+        let fd;
+        try {
+            fd = openSync(lockPath, "wx", 0o644);
+        }
+        catch (err) {
+            if (err.code === "EEXIST") {
+                const winner = this.readSafe(lockPath);
+                if (winner) {
+                    return {
+                        acquired: false,
+                        holder: winner,
+                        lockPath,
+                        stale: false,
+                        staleReason: null,
+                    };
+                }
+            }
+            throw err;
+        }
+        try {
+            writeSync(fd, JSON.stringify(payload, null, 2));
+        }
+        finally {
+            closeSync(fd);
+        }
+        return { acquired: true, lockPath, reentrant: false };
+    }
+    readSafe(lockPath) {
+        if (!existsSync(lockPath))
+            return null;
+        try {
+            const parsed = CheckoutLockFileSchema.safeParse(JSON.parse(readFileSync(lockPath, "utf-8")));
+            return parsed.success ? parsed.data : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    unlinkSafe(lockPath) {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+    }
+}

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

@@ -1,7 +1,10 @@
 /**
- * Public surface for the issue-level concurrency lock (#625).
+ * Public surface for the issue-level concurrency lock (#625) and the
+ * checkout-scoped lock (#901).
  */
+export { CheckoutLock, RELEASE_SENTINEL_ISSUE, describeCheckoutHolderIssue, formatCheckoutLockedMessage, isCheckoutOwner, } from "./checkout-lock.js";
+export type { CheckoutLockOptions } from "./checkout-lock.js";
 export { LockManager, classifyStaleness, defaultIsPidAlive, formatLockedMessage, isOrchestratorMode, resolveLocksDir, resolveMaxLockAgeMs, } from "./lock-manager.js";
 export type { LockManagerOptions } from "./lock-manager.js";
-export { DEFAULT_LOCKS_DIR, DEFAULT_MAX_LOCK_AGE_MS, DEFAULT_STALE_AGE_MS, LockFileSchema, } from "./types.js";
-export type { AcquireResult, LockFile, LockListing, SignalOtherResult, SignalReason, StaleReason, } from "./types.js";
+export { CHECKOUT_LOCK_FILENAME, CheckoutLockFileSchema, DEFAULT_LOCKS_DIR, DEFAULT_MAX_LOCK_AGE_MS, DEFAULT_STALE_AGE_MS, LockFileSchema, } from "./types.js";
+export type { AcquireResult, CheckoutAcquireResult, CheckoutHolderIdentity, CheckoutLockFile, CheckoutLockListing, LockFile, LockListing, SignalOtherResult, SignalReason, StaleReason, } from "./types.js";

package/dist/src/lib/locks/index.js

@@ -1,5 +1,7 @@
 /**
- * Public surface for the issue-level concurrency lock (#625).
+ * Public surface for the issue-level concurrency lock (#625) and the
+ * checkout-scoped lock (#901).
  */
+export { CheckoutLock, RELEASE_SENTINEL_ISSUE, describeCheckoutHolderIssue, formatCheckoutLockedMessage, isCheckoutOwner, } from "./checkout-lock.js";
 export { LockManager, classifyStaleness, defaultIsPidAlive, formatLockedMessage, isOrchestratorMode, resolveLocksDir, resolveMaxLockAgeMs, } from "./lock-manager.js";
-export { DEFAULT_LOCKS_DIR, DEFAULT_MAX_LOCK_AGE_MS, DEFAULT_STALE_AGE_MS, LockFileSchema, } from "./types.js";
+export { CHECKOUT_LOCK_FILENAME, CheckoutLockFileSchema, DEFAULT_LOCKS_DIR, DEFAULT_MAX_LOCK_AGE_MS, DEFAULT_STALE_AGE_MS, LockFileSchema, } from "./types.js";

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

@@ -18,6 +18,7 @@
  * method is a no-op (no fs touches, no warnings). Mirrors the
  * `OrchestratorRenderer` pattern at `src/lib/cli-ui/run-renderer.ts:244`.
  */
+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`). */
@@ -52,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
@@ -86,6 +91,81 @@ export declare function classifyStaleness(args: {
     maxLockAgeMs?: number;
     isPidAlive: (pid: number) => boolean;
 }): 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;