sequant 2.9.0 → 2.10.0

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/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;

package/dist/src/lib/mcp-config.js

@@ -7,8 +7,29 @@
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import { getVersion } from "./version.js";
 /** Path to the project-level MCP config file used by Claude Code */
 export 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 function getSequantPackageSpec() {
+    const version = getVersion();
+    return version && version !== "0.0.0"
+        ? `sequant@${version}`
+        : "sequant@latest";
+}
 /**
  * Clients that need an explicit cwd because they don't run from the project directory.
  */
@@ -25,7 +46,7 @@ const CLIENTS_NEEDING_CWD = new Set([
 export function getSequantMcpConfig(options) {
     const config = {
         command: "npx",
-        args: ["-y", "sequant@latest", "serve"],
+        args: ["-y", getSequantPackageSpec(), "serve"],
     };
     // Add cwd for clients that don't run from the project directory
     if (options?.clientType && CLIENTS_NEEDING_CWD.has(options.clientType)) {
@@ -170,3 +191,58 @@ export function createProjectMcpJson(projectDir) {
     }
     return { created: true, merged: false, skipped: false };
 }
+/**
+ * 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 function syncSequantMcpPin(projectDir, opts) {
+    const mcpJsonPath = path.resolve(projectDir ?? ".", PROJECT_MCP_JSON);
+    if (!fs.existsSync(mcpJsonPath)) {
+        return { updated: false, reason: "no-file" };
+    }
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(mcpJsonPath, "utf-8"));
+    }
+    catch {
+        // Corrupt file — leave it alone rather than overwriting user content.
+        return { updated: false, reason: "no-file" };
+    }
+    const servers = config?.mcpServers;
+    const sequant = servers?.sequant;
+    if (!sequant) {
+        return { updated: false, reason: "no-entry" };
+    }
+    const args = sequant.args;
+    if (!Array.isArray(args)) {
+        return { updated: false, reason: "no-pin" };
+    }
+    const pinIndex = args.findIndex((a) => typeof a === "string" && a.startsWith("sequant@"));
+    if (pinIndex === -1) {
+        return { updated: false, reason: "no-pin" };
+    }
+    const from = args[pinIndex];
+    const to = getSequantPackageSpec();
+    if (from === to) {
+        return { updated: false, reason: "already-current" };
+    }
+    if (!opts?.dryRun) {
+        args[pinIndex] = to;
+        fs.writeFileSync(mcpJsonPath, JSON.stringify(config, null, 2) + "\n");
+    }
+    return { updated: true, from, to };
+}

package/dist/src/lib/merge-check/combined-branch-test.d.ts

@@ -2,11 +2,30 @@
  * Combined branch testing (AC-1)
  *
  * Creates a temporary branch merging all feature branches from a run batch,
- * runs npm test && npm run build on the combined state, and reports results.
+ * reinstalls dependencies when the merge moved a lockfile, then runs the
+ * project's test and build scripts on the combined state and reports results.
  */
 import type { BranchInfo, CheckResult, BranchCheckResult, CheckFinding } from "./types.js";
+import { resolveFailureReason, type CommandResult } from "./command-result.js";
+export { resolveFailureReason, type CommandResult };
 /**
- * Create temp branch, merge all feature branches, run tests and build.
+ * Run a package-manager command line (e.g. "npm ci", "pnpm run build").
+ *
+ * @param command Full command line, as stored in PM_CONFIG
+ * @param cwd Working directory
+ * @param timeoutMs Kill the command after this long
+ * @internal Exported for testing
+ */
+export declare function runPackageManagerCommand(command: string, cwd: string, timeoutMs: number): CommandResult;
+/**
+ * Whether any lockfile differs between `baseRef` and the current HEAD.
+ *
+ * @internal Exported for testing
+ */
+export declare function lockfileChanged(repoRoot: string, baseRef: string): boolean;
+/**
+ * Create temp branch, merge all feature branches, reinstall dependencies if the
+ * lockfile moved, then run tests and build.
  *
  * @param branches - Feature branches to merge
  * @param repoRoot - Path to the git repository root