sequant 2.9.0 → 2.11.0

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. */
@@ -29,3 +45,31 @@ export const LockFileSchema = z.object({
      */
     skipPidCheck: z.boolean().optional(),
 });
+/**
+ * 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 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 const CheckoutLockFileSchema = LockFileSchema.extend({
+    issue: z.number().int().positive(),
+    sessionId: z.string().optional(),
+});

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

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

@@ -2,10 +2,37 @@
  * 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 { spawnSync } from "child_process";
 import { getBranchRef } from "./types.js";
+import { detectPackageManagerSync, resolvePackageManagerConfig, } from "../stacks.js";
+import { toCommandResult, resolveFailureReason, } from "./command-result.js";
+// Re-exported for the existing test suite and any downstream consumer that
+// imported these from here before they moved to ./command-result.js.
+export { resolveFailureReason };
+/**
+ * Lockfile names for the JS package managers we support. Kept in sync with the
+ * equivalent list in `workflow/worktree-manager.ts`.
+ */
+const LOCKFILES = [
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "bun.lockb",
+    "bun.lock",
+    "yarn.lock",
+];
+/**
+ * Per-step command timeouts. A dependency install and a full test suite are
+ * both slower than the previous flat 2-minute budget allowed. An expired
+ * timeout kills the process with `status: null` and no captured output, which
+ * showed up as a BLOCKED verdict with no stated reason (#803).
+ */
+const INSTALL_TIMEOUT_MS = 300_000; // 5 min
+const TEST_BUILD_TIMEOUT_MS = 600_000; // 10 min
+/** Ref the combined state is built on top of, and compared against. */
+const BASE_REF = "origin/main";
 /**
  * Run a git command and return the result
  */
@@ -22,23 +49,39 @@ function git(args, cwd) {
     };
 }
 /**
- * Run npm command and return result
+ * 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
  */
-function npm(args, cwd) {
-    const result = spawnSync("npm", args, {
+export function runPackageManagerCommand(command, cwd, timeoutMs) {
+    const [bin, ...args] = command.split(" ");
+    const result = spawnSync(bin, args, {
         cwd,
         stdio: "pipe",
         encoding: "utf-8",
-        timeout: 120_000, // 2 min timeout for test/build
+        timeout: timeoutMs,
+        // On Windows the package managers are `.cmd` shims, which CreateProcess
+        // will not resolve from a bare "npm"/"pnpm". `command` is always a constant
+        // from PM_CONFIG — never user input — so there is nothing to inject here.
+        shell: process.platform === "win32",
     });
-    return {
-        ok: result.status === 0,
-        stdout: result.stdout?.trim() ?? "",
-        stderr: result.stderr?.trim() ?? "",
-    };
+    return toCommandResult(result);
 }
 /**
- * Create temp branch, merge all feature branches, run tests and build.
+ * Whether any lockfile differs between `baseRef` and the current HEAD.
+ *
+ * @internal Exported for testing
+ */
+export function lockfileChanged(repoRoot, baseRef) {
+    const result = git(["diff", "--name-only", baseRef, "HEAD", "--", ...LOCKFILES], repoRoot);
+    return result.ok && result.stdout.length > 0;
+}
+/**
+ * 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
@@ -49,123 +92,203 @@ export function runCombinedBranchTest(branches, repoRoot) {
     const tempBranch = `merge-check/temp-${Date.now()}`;
     const branchResults = [];
     const batchFindings = [];
-    const mergeAttempts = [];
-    // Save current branch to restore in finally block
+    const pm = detectPackageManagerSync(repoRoot);
+    // Resolved against the repo rather than read straight off PM_CONFIG: yarn's
+    // frozen install differs between classic and berry, and `pm` is "yarn" for
+    // both (#871).
+    //
+    // This resolution describes the PRE-MERGE tree, which is what the restore
+    // install in the `finally` below runs against — it fires after
+    // `git checkout restoreBranch`, so the original branch's yarn major is the
+    // right one there. `runChecks` re-resolves for the combined state, where a
+    // merged branch may have changed the major.
+    const pmConfig = resolvePackageManagerConfig(pm, repoRoot);
+    // Flipped the moment we start installing against the combined lockfile, so
+    // the caller's node_modules can be put back afterwards. A mutable holder
+    // rather than a return value: if runChecks throws, a return value never
+    // arrives and the restore would be skipped precisely when the tree is most
+    // likely to be inconsistent.
+    const installState = { installedCombinedDeps: false };
+    // Save current branch to restore in the cleanup step
     const originalBranch = git(["rev-parse", "--abbrev-ref", "HEAD"], repoRoot);
     try {
-        // Fetch latest from remote
-        git(["fetch", "origin"], repoRoot);
-        // Create temp branch from main
-        const createResult = git(["checkout", "-b", tempBranch, "origin/main"], repoRoot);
-        if (!createResult.ok) {
-            batchFindings.push({
-                check: "combined-branch-test",
-                severity: "error",
-                message: `Failed to create temp branch: ${createResult.stderr}`,
-            });
-            return buildResult(branchResults, batchFindings, startTime);
-        }
-        // Merge each feature branch
-        for (const branch of branches) {
-            const mergeResult = git(["merge", "--no-ff", "--no-edit", getBranchRef(branch)], repoRoot);
-            if (mergeResult.ok) {
-                mergeAttempts.push({
-                    issueNumber: branch.issueNumber,
-                    branch: branch.branch,
-                    success: true,
-                });
-                branchResults.push({
-                    issueNumber: branch.issueNumber,
-                    verdict: "PASS",
-                    findings: [
-                        {
-                            check: "combined-branch-test",
-                            severity: "info",
-                            message: `Branch merged cleanly into combined state`,
-                            issueNumber: branch.issueNumber,
-                        },
-                    ],
-                });
-            }
-            else {
-                // Get conflicting files
-                const conflictResult = git(["diff", "--name-only", "--diff-filter=U"], repoRoot);
-                const conflictFiles = conflictResult.stdout
-                    ? conflictResult.stdout.split("\n")
-                    : [];
-                mergeAttempts.push({
-                    issueNumber: branch.issueNumber,
-                    branch: branch.branch,
-                    success: false,
-                    conflictFiles,
-                    error: mergeResult.stderr,
-                });
-                branchResults.push({
-                    issueNumber: branch.issueNumber,
-                    verdict: "FAIL",
-                    findings: [
-                        {
-                            check: "combined-branch-test",
-                            severity: "error",
-                            message: `Merge conflict with ${conflictFiles.length} file(s): ${conflictFiles.join(", ")}`,
-                            issueNumber: branch.issueNumber,
-                        },
-                    ],
+        runChecks(branches, repoRoot, tempBranch, pm, branchResults, batchFindings, installState);
+    }
+    finally {
+        // Restore original branch and delete temp branch
+        const restoreBranch = originalBranch.ok ? originalBranch.stdout : "main";
+        git(["checkout", restoreBranch], repoRoot);
+        git(["branch", "-D", tempBranch], repoRoot);
+        // We installed the combined state's dependency tree into the caller's
+        // node_modules; put it back so the restored branch is not left running
+        // against another branch's dependencies.
+        //
+        // Frozen again, for the same reason as the forward install: a plain
+        // `npm install` normalizes and rewrites the lockfile, which would leave
+        // the user's restored branch with a dirty working tree that this check
+        // never asked them for.
+        if (installState.installedCombinedDeps) {
+            const restoreInstall = runPackageManagerCommand(pmConfig.ciInstall, repoRoot, INSTALL_TIMEOUT_MS);
+            if (!restoreInstall.ok) {
+                batchFindings.push({
+                    check: "combined-branch-test",
+                    severity: "warning",
+                    message: `Dependencies were reinstalled for the combined state but could not be restored for \`${restoreBranch}\`. Run \`${pmConfig.ciInstall}\` to resync node_modules: ${resolveFailureReason(restoreInstall)}`,
                 });
-                // Abort the failed merge and continue
-                git(["merge", "--abort"], repoRoot);
             }
         }
-        // If any merges failed, skip tests but report what we have
-        const failedMerges = mergeAttempts.filter((m) => !m.success);
-        if (failedMerges.length > 0) {
-            batchFindings.push({
-                check: "combined-branch-test",
-                severity: "error",
-                message: `${failedMerges.length}/${branches.length} branches had merge conflicts — skipping test/build`,
+    }
+    // Built after cleanup so findings pushed during cleanup are reflected in the
+    // verdict rather than silently arriving too late to affect `passed`.
+    return buildResult(branchResults, batchFindings, startTime);
+}
+/**
+ * Assemble the combined state and run install/test/build against it.
+ *
+ * Mutates `branchResults`, `batchFindings`, and `installState` — the last so
+ * the caller's cleanup can restore node_modules even if this function throws.
+ */
+function runChecks(branches, repoRoot, tempBranch, pm, branchResults, batchFindings, installState) {
+    const mergeAttempts = [];
+    // Fetch latest from remote
+    git(["fetch", "origin"], repoRoot);
+    // Create temp branch from main
+    const createResult = git(["checkout", "-b", tempBranch, BASE_REF], repoRoot);
+    if (!createResult.ok) {
+        batchFindings.push({
+            check: "combined-branch-test",
+            severity: "error",
+            message: `Failed to create temp branch: ${createResult.stderr}`,
+        });
+        return;
+    }
+    // Merge each feature branch
+    for (const branch of branches) {
+        const mergeResult = git(["merge", "--no-ff", "--no-edit", getBranchRef(branch)], repoRoot);
+        if (mergeResult.ok) {
+            mergeAttempts.push({
+                issueNumber: branch.issueNumber,
+                branch: branch.branch,
+                success: true,
             });
-            return buildResult(branchResults, batchFindings, startTime);
-        }
-        // Run npm test
-        const testResult = npm(["test"], repoRoot);
-        if (testResult.ok) {
-            batchFindings.push({
-                check: "combined-branch-test",
-                severity: "info",
-                message: "npm test passed on combined state",
+            branchResults.push({
+                issueNumber: branch.issueNumber,
+                verdict: "PASS",
+                findings: [
+                    {
+                        check: "combined-branch-test",
+                        severity: "info",
+                        message: `Branch merged cleanly into combined state`,
+                        issueNumber: branch.issueNumber,
+                    },
+                ],
             });
         }
         else {
-            batchFindings.push({
-                check: "combined-branch-test",
-                severity: "error",
-                message: `npm test failed on combined state: ${testResult.stderr.slice(0, 500)}`,
+            // Get conflicting files
+            const conflictResult = git(["diff", "--name-only", "--diff-filter=U"], repoRoot);
+            const conflictFiles = conflictResult.stdout
+                ? conflictResult.stdout.split("\n")
+                : [];
+            mergeAttempts.push({
+                issueNumber: branch.issueNumber,
+                branch: branch.branch,
+                success: false,
+                conflictFiles,
+                error: mergeResult.stderr,
             });
-        }
-        // Run npm run build
-        const buildResult2 = npm(["run", "build"], repoRoot);
-        if (buildResult2.ok) {
-            batchFindings.push({
-                check: "combined-branch-test",
-                severity: "info",
-                message: "npm run build passed on combined state",
+            branchResults.push({
+                issueNumber: branch.issueNumber,
+                verdict: "FAIL",
+                findings: [
+                    {
+                        check: "combined-branch-test",
+                        severity: "error",
+                        message: `Merge conflict with ${conflictFiles.length} file(s): ${conflictFiles.join(", ")}`,
+                        issueNumber: branch.issueNumber,
+                    },
+                ],
             });
+            // Abort the failed merge and continue
+            git(["merge", "--abort"], repoRoot);
         }
-        else {
+    }
+    // If any merges failed, skip tests but report what we have
+    const failedMerges = mergeAttempts.filter((m) => !m.success);
+    if (failedMerges.length > 0) {
+        batchFindings.push({
+            check: "combined-branch-test",
+            severity: "error",
+            message: `${failedMerges.length}/${branches.length} branches had merge conflicts — skipping test/build`,
+        });
+        return;
+    }
+    // Resolved HERE, after the merges landed, not from the caller's pre-merge
+    // resolution: the commands below run against the combined tree, and a merged
+    // branch can move the yarn major (a `packageManager` bump, a new
+    // `.yarnrc.yml`). Installing the combined state with the pre-merge major's
+    // frozen-install flag would fail on an unknown option and report a false
+    // BLOCKED — the exact failure class #803 added this install to prevent (#871).
+    const pmConfig = resolvePackageManagerConfig(pm, repoRoot);
+    // Reinstall dependencies when the merged branches moved the lockfile (#803).
+    // Without this, test/build run against the node_modules of whatever branch
+    // the user happened to be on, so a batch that merely added a dependency fails
+    // with module-not-found errors — a false BLOCKED on a healthy stack.
+    //
+    // A frozen install is used rather than a plain one: it mirrors what CI does,
+    // it will not rewrite the lockfile (which would dirty the temp branch and
+    // break the checkout during cleanup), and it fails loudly on a lockfile that
+    // is inconsistent with package.json.
+    if (lockfileChanged(repoRoot, BASE_REF)) {
+        // Marked before the install runs, not after: a frozen install deletes
+        // node_modules up front, so even a failed or interrupted one leaves the
+        // caller's tree needing a restore.
+        installState.installedCombinedDeps = true;
+        const installResult = runPackageManagerCommand(pmConfig.ciInstall, repoRoot, INSTALL_TIMEOUT_MS);
+        if (!installResult.ok) {
+            // Surface install failures on their own terms rather than letting them
+            // resurface downstream as an unexplained test failure.
             batchFindings.push({
                 check: "combined-branch-test",
                 severity: "error",
-                message: `npm run build failed on combined state: ${buildResult2.stderr.slice(0, 500)}`,
+                message: `Dependency install failed on combined state (\`${pmConfig.ciInstall}\`) — skipping test/build. The merged lockfile may be inconsistent with package.json: ${resolveFailureReason(installResult)}`,
             });
+            return;
         }
-        return buildResult(branchResults, batchFindings, startTime);
-    }
-    finally {
-        // Clean up: restore original branch and delete temp branch
-        const restoreBranch = originalBranch.ok ? originalBranch.stdout : "main";
-        git(["checkout", restoreBranch], repoRoot);
-        git(["branch", "-D", tempBranch], repoRoot);
+        batchFindings.push({
+            check: "combined-branch-test",
+            severity: "info",
+            message: `Lockfile changed in the combined state — reinstalled dependencies with \`${pmConfig.ciInstall}\``,
+        });
     }
+    // Run the test suite
+    const testCommand = `${pmConfig.run} test`;
+    const testResult = runPackageManagerCommand(testCommand, repoRoot, TEST_BUILD_TIMEOUT_MS);
+    batchFindings.push(testResult.ok
+        ? {
+            check: "combined-branch-test",
+            severity: "info",
+            message: `\`${testCommand}\` passed on combined state`,
+        }
+        : {
+            check: "combined-branch-test",
+            severity: "error",
+            message: `\`${testCommand}\` failed on combined state: ${resolveFailureReason(testResult)}`,
+        });
+    // Run the build
+    const buildCommand = `${pmConfig.run} build`;
+    const buildOutcome = runPackageManagerCommand(buildCommand, repoRoot, TEST_BUILD_TIMEOUT_MS);
+    batchFindings.push(buildOutcome.ok
+        ? {
+            check: "combined-branch-test",
+            severity: "info",
+            message: `\`${buildCommand}\` passed on combined state`,
+        }
+        : {
+            check: "combined-branch-test",
+            severity: "error",
+            message: `\`${buildCommand}\` failed on combined state: ${resolveFailureReason(buildOutcome)}`,
+        });
 }
 export function buildResult(branchResults, batchFindings, startTime) {
     const hasErrors = batchFindings.some((f) => f.severity === "error");