sequant 2.8.0 → 2.10.0

package/dist/src/lib/errors.js

@@ -107,34 +107,146 @@ export class BillingError extends SequantError {
     }
 }
 /**
- * True when the rate-limit info represents a billing/credits failure (which a
- * retry cannot fix), rather than a transient throttle.
+ * Recognized rate-limit *window* vocabulary — limit types whose exhaustion is
+ * a pause that reopens at `resetsAt`, not a wallet state. `five_hour` is the
+ * subscription session window; `seven_day` is prefix-matched because the SDK
+ * emits model-qualified variants (`seven_day*`, see {@link formatResetTime}).
+ *
+ * Deliberately an allowlist (#860 AC-3): this encodes an inference about
+ * Anthropic's payload vocabulary, so an unlisted type (e.g. `overage`) must
+ * fail closed to the terminal billing path rather than into a five-hour sleep.
+ */
+const WAITABLE_WINDOW_TYPE_RE = /^(five_hour|seven_day)/;
+/**
+ * True when the rate-limit info describes an exhausted *window* that will
+ * reopen at a known future time: a recognized window `rateLimitType` plus a
+ * `resetsAt` still in the future (#860 AC-1).
+ *
+ * This is the discriminator between "subscription window closed until 07:00"
+ * and "account needs credits". The fields that would answer that directly
+ * (`canUserPurchaseCredits`, `hasChargeableSavedPaymentMethod`) are absent
+ * from every real captured payload, so the window shape is the proxy — and
+ * any unrecognized shape returns false (fail closed, #860 AC-3).
+ *
+ * Explicitly informational statuses (`allowed` / `allowed_warning`) are never
+ * waitable. The driver retains marker-carrying warnings as failure-grade
+ * (pre-#732 semantics, unchanged), so a stale "you are nearing your limit"
+ * warning can be misattributed to an unrelated phase failure — classifying it
+ * waitable would upgrade that misattribution from a cheap immediate halt to a
+ * multi-hour sleep. The 26 real captures carry no `status` field at all, so
+ * absent status stays waitable; only a status that affirmatively says
+ * "not a rejection" is excluded.
+ */
+export function isWaitableWindow(info, now = Date.now()) {
+    if (info.status === "allowed" || info.status === "allowed_warning") {
+        return false;
+    }
+    if (typeof info.rateLimitType !== "string")
+        return false;
+    if (!WAITABLE_WINDOW_TYPE_RE.test(info.rateLimitType))
+        return false;
+    if (typeof info.resetsAt !== "number")
+        return false;
+    return resetsAtToMs(info.resetsAt) > now;
+}
+/**
+ * Vocabulary-drift telemetry for the #860 fail-closed path: returns a hint
+ * string when a payload was terminal ONLY because its `rateLimitType` is not
+ * in the recognized window allowlist — i.e. it carries `out_of_credits` plus a
+ * live future `resetsAt` and a *present but unrecognized* window type, and no
+ * explicit `credits_required`. If Anthropic renames or adds a window type,
+ * the halt message names the rejected type instead of silently reading as an
+ * ordinary wallet failure. A missing `rateLimitType` is NOT drift evidence
+ * (API-account payloads may legitimately omit it), so no hint fires there.
  */
-export function isBillingFailure(info) {
+export function unrecognizedWindowHint(info, now = Date.now()) {
+    if (info.errorCode === "credits_required")
+        return null;
+    if (info.overageDisabledReason !== "out_of_credits")
+        return null;
+    if (info.status === "allowed" || info.status === "allowed_warning") {
+        return null;
+    }
+    if (typeof info.rateLimitType !== "string")
+        return null;
+    if (WAITABLE_WINDOW_TYPE_RE.test(info.rateLimitType))
+        return null;
+    if (typeof info.resetsAt !== "number")
+        return null;
+    if (resetsAtToMs(info.resetsAt) <= now)
+        return null;
+    return `unrecognized window type "${info.rateLimitType}" with a future reset — treated as terminal (auto-wait recognizes five_hour/seven_day)`;
+}
+/**
+ * True when the info carries an explicit billing/credits marker, regardless
+ * of whether a live window would make it waitable. This is the pre-#860
+ * `isBillingFailure` predicate, kept for failure-*detection* sites
+ * ({@link isRateLimitFailureInfo}) whose retention semantics must not narrow.
+ */
+function hasBillingMarkers(info) {
     return (info.errorCode === "credits_required" ||
         info.overageDisabledReason === "out_of_credits");
 }
+/**
+ * True when the rate-limit info represents a billing/credits failure (which
+ * waiting cannot fix), rather than a transient throttle or an exhausted
+ * window.
+ *
+ * Narrowed by #860: a subscription plan hitting its five-hour cap with
+ * overage disabled emits `overageDisabledReason: "out_of_credits"` *plus* a
+ * window type and a live `resetsAt` — a pause, not a wallet failure. That
+ * shape is excluded here so it classifies as a retryable {@link RateLimitError}
+ * and `--auto-wait` (#804) can act on it. An explicit
+ * `errorCode: "credits_required"` stays terminal even alongside window
+ * evidence — it is the SDK's direct "purchase needed" signal (#860 AC-2).
+ * Anything short of the full recognized window shape remains terminal
+ * (fail closed, #860 AC-3).
+ */
+export function isBillingFailure(info, now = Date.now()) {
+    if (info.errorCode === "credits_required")
+        return true;
+    return (info.overageDisabledReason === "out_of_credits" &&
+        !isWaitableWindow(info, now));
+}
 /**
  * True when the rate-limit info represents an actual failure (rejection or
  * billing), as opposed to an informational `allowed` / `allowed_warning`
  * event. The driver uses this to avoid mis-attributing a stale warning event
  * to an unrelated phase failure.
+ *
+ * Built on the raw billing *markers*, not the #860-narrowed classification:
+ * the captured five-hour payloads cannot prove they carried
+ * `status: "rejected"`, so narrowing here could silently drop the very events
+ * #860 exists to keep (they'd fall back to a metadata-less assistant error and
+ * auto-wait would stay inert). Retention semantics are unchanged; only the
+ * billing-vs-waitable *classification* narrowed.
  */
 export function isRateLimitFailureInfo(info) {
-    return info.status === "rejected" || isBillingFailure(info);
+    return info.status === "rejected" || hasBillingMarkers(info);
+}
+/**
+ * Normalize a `resetsAt` timestamp to milliseconds. The SDK does not pin the
+ * unit, so use the same heuristic everywhere a `resetsAt` is compared or
+ * displayed: values below ~1e12 are seconds, otherwise milliseconds.
+ */
+export function resetsAtToMs(resetsAt) {
+    return resetsAt < 1e12 ? resetsAt * 1000 : resetsAt;
 }
 /**
  * Format a Unix timestamp (seconds or ms) as a local time string.
  *
  * Bare `HH:MM` when the reset falls on the current local calendar day;
- * date-qualified `MM-DD HH:MM` otherwise. Multi-day windows
+ * date-qualified `MM-DD HH:MM` otherwise. Also used for #804's auto-wait wake
+ * time (a wake is `resetsAt + buffer`, already in ms, which `resetsAtToMs`
+ * passes through unchanged) so both render in one convention.
+ *
+ * Multi-day windows
  * (`rateLimitType: seven_day*`) can reset days out — a bare `HH:MM` there reads
  * as "later today" and misleads the user (#732 QA follow-up), so the date is
  * included whenever the reset is not today.
  */
-function formatResetTime(resetsAt) {
-    // Heuristic: values below ~1e12 are seconds, otherwise milliseconds.
-    const ms = resetsAt < 1e12 ? resetsAt * 1000 : resetsAt;
+export function formatResetTime(resetsAt) {
+    const ms = resetsAtToMs(resetsAt);
     const d = new Date(ms);
     const hh = String(d.getHours()).padStart(2, "0");
     const mm = String(d.getMinutes()).padStart(2, "0");
@@ -156,16 +268,27 @@ function formatResetTime(resetsAt) {
  * - transient throttle → "Rate limited — resets at HH:MM" (date-qualified as
  *   "MM-DD HH:MM" when the reset is not today; reset time omitted entirely when
  *   `resetsAt` is absent)
+ *
+ * `now` feeds the #860 waitable-window classification so message and error
+ * type are derived against the same instant (and tests can pin the clock).
+ * A waitable window renders through the rate-limited branch — its reset time
+ * is the actionable fact; "Out of credits" would misname a pause as a wallet
+ * failure.
  */
-export function formatRateLimitMessage(info) {
-    if (isBillingFailure(info)) {
+export function formatRateLimitMessage(info, now = Date.now()) {
+    if (isBillingFailure(info, now)) {
+        // #860 drift telemetry: when the ONLY reason this is terminal is an
+        // unrecognized window type, say so — the message is the one channel that
+        // reaches run output, logs, and `PhaseResult.error` on every display path.
+        const hint = unrecognizedWindowHint(info, now);
+        const suffix = hint ? ` (${hint})` : "";
         if (info.canUserPurchaseCredits === true) {
-            return "Out of credits — purchasable";
+            return `Out of credits — purchasable${suffix}`;
         }
         if (info.canUserPurchaseCredits === false) {
-            return "Out of credits — hard limit";
+            return `Out of credits — hard limit${suffix}`;
         }
-        return "Out of credits";
+        return `Out of credits${suffix}`;
     }
     if (info.resetsAt !== undefined) {
         return `Rate limited — resets at ${formatResetTime(info.resetsAt)}`;
@@ -175,10 +298,12 @@ export function formatRateLimitMessage(info) {
 /**
  * Construct the appropriate typed error from structured rate-limit info.
  * Billing/credits failures become a non-retryable {@link BillingError};
- * transient throttles become a retryable {@link RateLimitError}.
+ * transient throttles AND exhausted-but-reopening windows (#860) become a
+ * retryable {@link RateLimitError}. `now` pins the waitable-window check to
+ * one instant across message and classification.
  */
-export function createRateLimitError(info) {
-    const message = formatRateLimitMessage(info);
+export function createRateLimitError(info, now = Date.now()) {
+    const message = formatRateLimitMessage(info, now);
     const metadata = {
         resetsAt: info.resetsAt,
         rateLimitType: info.rateLimitType,
@@ -187,7 +312,7 @@ export function createRateLimitError(info) {
         canUserPurchaseCredits: info.canUserPurchaseCredits,
         hasChargeableSavedPaymentMethod: info.hasChargeableSavedPaymentMethod,
     };
-    return isBillingFailure(info)
+    return isBillingFailure(info, now)
         ? new BillingError(message, metadata)
         : new RateLimitError(message, metadata);
 }

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

@@ -1,7 +1,7 @@
 /**
  * Public surface for the issue-level concurrency lock (#625).
  */
-export { LockManager, classifyStaleness, defaultIsPidAlive, formatLockedMessage, isOrchestratorMode, resolveLocksDir, } from "./lock-manager.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_STALE_AGE_MS, LockFileSchema, } from "./types.js";
-export type { AcquireResult, LockFile, LockListing, SignalOtherResult, SignalReason, } from "./types.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";

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

@@ -1,5 +1,5 @@
 /**
  * Public surface for the issue-level concurrency lock (#625).
  */
-export { LockManager, classifyStaleness, defaultIsPidAlive, formatLockedMessage, isOrchestratorMode, resolveLocksDir, } from "./lock-manager.js";
-export { DEFAULT_LOCKS_DIR, DEFAULT_STALE_AGE_MS, LockFileSchema, } from "./types.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";

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,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 { type AcquireResult, type LockFile, type LockListing, type SignalOtherResult } from "./types.js";
+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 +33,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). */
@@ -52,6 +60,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 +82,15 @@ 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;
 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.
@@ -19,7 +21,7 @@
 import { openSync, closeSync, writeSync, readFileSync, existsSync, unlinkSync, mkdirSync, readdirSync, statSync, } from "fs";
 import { join, resolve } from "path";
 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);
@@ -43,6 +45,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 +89,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,8 +115,7 @@ 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";
@@ -96,6 +125,7 @@ export class LockManager {
     locksDir;
     staleAgeMs;
     skillLockTtlMs;
+    maxLockAgeMs;
     orchestratorMode;
     hostname;
     pid;
@@ -110,6 +140,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,6 +188,7 @@ export class LockManager {
                 now: this.now(),
                 staleAgeMs: this.staleAgeMs,
                 skillLockTtlMs: this.skillLockTtlMs,
+                maxLockAgeMs: this.maxLockAgeMs,
                 isPidAlive: this.isPidAlive,
             });
             if (staleReason) {
@@ -211,6 +244,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 +346,7 @@ export class LockManager {
                 now,
                 staleAgeMs: this.staleAgeMs,
                 skillLockTtlMs: this.skillLockTtlMs,
+                maxLockAgeMs: this.maxLockAgeMs,
                 isPidAlive: this.isPidAlive,
             });
             out.push({
@@ -338,6 +381,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;
@@ -35,7 +59,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 +67,7 @@ export interface LockListing {
     holder: LockFile;
     ageMs: number;
     stale: boolean;
-    staleReason: "pid-dead" | "age-exceeded" | null;
+    staleReason: StaleReason | null;
     lockPath: string;
 }
 /**
@@ -51,7 +75,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;

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

@@ -14,6 +14,22 @@ export const DEFAULT_STALE_AGE_MS = 2 * 60 * 60 * 1000; // 2h
  * Override per-process via `SEQUANT_SKILL_LOCK_TTL_MS` (milliseconds).
  */
 export const DEFAULT_SKILL_LOCK_TTL_MS = 6 * 60 * 60 * 1000; // 6h
+/**
+ * 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 const DEFAULT_MAX_LOCK_AGE_MS = 24 * 60 * 60 * 1000; // 24h
 /** Default lock directory relative to the project root. */
 export const DEFAULT_LOCKS_DIR = ".sequant/locks";
 /** On-disk lock payload. */

package/dist/src/lib/manifest.js

@@ -2,6 +2,7 @@
  * Manifest management for tracking installed version
  */
 import { readFile, writeFile, fileExists } from "./fs.js";
+import { compareVersions } from "./version-check.js";
 import { fileURLToPath } from "url";
 import { dirname, resolve } from "path";
 import { readFileSync } from "fs";
@@ -32,23 +33,6 @@ const PACKAGE_VERSION = pkg.version;
 export function getPackageVersion() {
     return PACKAGE_VERSION;
 }
-/**
- * Compare two semver versions.
- * Returns: 1 if a > b, -1 if a < b, 0 if equal
- */
-function compareVersions(a, b) {
-    const partsA = a.split(".").map(Number);
-    const partsB = b.split(".").map(Number);
-    for (let i = 0; i < 3; i++) {
-        const numA = partsA[i] || 0;
-        const numB = partsB[i] || 0;
-        if (numA > numB)
-            return 1;
-        if (numA < numB)
-            return -1;
-    }
-    return 0;
-}
 export async function getManifest() {
     if (!(await fileExists(MANIFEST_PATH))) {
         return null;

package/dist/src/lib/mcp-config.d.ts

@@ -6,6 +6,21 @@
  */
 /** Path to the project-level MCP config file used by Claude Code */
 export declare const PROJECT_MCP_JSON = ".mcp.json";
+/**
+ * npm package specifier used to launch the MCP server (#793).
+ *
+ * We pin to the installed version rather than `@latest` so that `npx` does not
+ * re-resolve and reinstall the package on the first MCP reconnect after every
+ * sequant release — the reinstall was surfacing as an opaque
+ * `Failed to reconnect to sequant: -32000` when npx's cache was corrupted
+ * (npm ENOTEMPTY). `setup`/`update` (re)write this pin, so the MCP server
+ * tracks new releases when the user runs `sequant update` — matching how the
+ * plugin cache already pins. See docs/troubleshooting.md ("MCP Server Issues").
+ *
+ * Falls back to `latest` if the installed version cannot be resolved, so a
+ * failed lookup never writes a bogus `sequant@0.0.0` pin into `.mcp.json`.
+ */
+export declare function getSequantPackageSpec(): string;
 export type McpClientType = "claude-desktop" | "cursor" | "vscode-continue";
 export interface McpClientInfo {
     name: string;
@@ -52,3 +67,33 @@ export interface ProjectMcpJsonResult {
  * because Claude Code runs from the project root.
  */
 export declare function createProjectMcpJson(projectDir?: string): ProjectMcpJsonResult;
+export interface SyncMcpPinResult {
+    updated: boolean;
+    /** Why no rewrite happened, when updated === false. */
+    reason?: "no-file" | "no-entry" | "no-pin" | "already-current";
+    /** Previous package spec, when updated === true (e.g. "sequant@latest"). */
+    from?: string;
+    /** New package spec, when updated === true (e.g. "sequant@2.9.0"). */
+    to?: string;
+}
+/**
+ * Re-pin an existing project `.mcp.json` sequant entry to the installed version (#793).
+ *
+ * Unlike {@link createProjectMcpJson} (which skips when a sequant entry already
+ * exists), this is the `update`/`sync` path: it refreshes the version pin so the
+ * MCP server tracks the release the user just updated to. It only rewrites the
+ * `sequant@<version>` token inside `args` and leaves everything else untouched.
+ *
+ * No-ops (returns `updated: false`) when:
+ * - `.mcp.json` doesn't exist (`no-file`) — we never create it here; that's init's job
+ * - there's no sequant server entry (`no-entry`)
+ * - the entry uses a local-binary form with no `sequant@…` arg (`no-pin`) — a
+ *   deliberate contributor override we must not clobber
+ * - the pin already matches the installed version (`already-current`)
+ *
+ * With `opts.dryRun`, computes `from`/`to` and returns `updated: true` for a
+ * pending change but does not write the file — the caller reports it as a preview.
+ */
+export declare function syncSequantMcpPin(projectDir?: string, opts?: {
+    dryRun?: boolean;
+}): SyncMcpPinResult;