sequant 2.9.0 → 2.11.0

package/dist/src/lib/templates.js

@@ -1,7 +1,8 @@
 /**
  * Template management - copy and process templates
  */
-import { readdir, chmod } from "fs/promises";
+import { readdir, chmod, stat } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
 import { join, dirname, relative, isAbsolute } from "path";
 import { fileURLToPath } from "url";
 import { diffLines } from "diff";
@@ -11,18 +12,122 @@ const SKILLS_VERSION_PATH = ".claude/skills/.sequant-version";
 import { getStackConfig, getStackNotes, getMultiStackNotes } from "./stacks.js";
 import { isNativeWindows } from "./system.js";
 import { getProjectName } from "./project-name.js";
+/**
+ * Offsets from this module's directory to the bundled `templates/` root, in
+ * probe order. This module lives at `src/lib/templates.ts`, so it sits three
+ * levels below the package root once compiled (`dist/src/lib/templates.js`) but
+ * only two when executed straight from source under `tsx` (`src/lib/`).
+ *
+ * The compiled offset is listed first so consumers — who always run the compiled
+ * binary — keep byte-identical behavior. See #822.
+ */
+const TEMPLATES_DIR_OFFSETS = [
+    ["..", "..", "..", "templates"], // compiled: dist/src/lib → <pkg>/templates
+    ["..", "..", "templates"], // source (tsx): src/lib → <repo>/templates
+];
+/**
+ * Resolve the templates root relative to a module directory, given a ranking
+ * function.
+ *
+ * Split out from `getTemplatesDir` purely so both layouts are testable: a test
+ * cannot relocate `import.meta.url`, so without injection the "works from both
+ * layouts" assertion could only ever exercise whichever layout the test runner
+ * happens to use.
+ *
+ * Resolution order: the first `package-root` candidate, else the first that
+ * merely `exists` (keeps any layout that works today working, even one whose
+ * package root is not where we expect), else the **compiled** offset — so the
+ * caller's error message names the canonical expected location rather than a
+ * source-tree guess.
+ */
+export function resolveTemplatesDirFrom(baseDir, rank) {
+    const candidates = TEMPLATES_DIR_OFFSETS.map((offset) => join(baseDir, ...offset));
+    const ranked = candidates.map((candidate) => ({
+        candidate,
+        rank: rank(candidate),
+    }));
+    return (ranked.find((c) => c.rank === "package-root")?.candidate ??
+        ranked.find((c) => c.rank === "exists")?.candidate ??
+        candidates[0]);
+}
+/**
+ * Rank a candidate by checking whether it exists and whether its parent is the
+ * sequant package root. Anchoring on `package.json` mirrors how every other
+ * root resolver in this codebase locates the package (`version.ts`,
+ * `manifest.ts`, `bin/preflight.ts`).
+ */
+function rankTemplatesCandidate(candidate) {
+    if (!existsSync(candidate)) {
+        return "missing";
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(join(candidate, "..", "package.json"), "utf-8"));
+        if (pkg.name === "sequant") {
+            return "package-root";
+        }
+    }
+    catch {
+        // No readable/parseable package.json beside it — still a usable directory,
+        // just not a positively identified package root.
+    }
+    return "exists";
+}
+/**
+ * Memoized bundled-templates path. Resolution is now stat-backed rather than a
+ * pure string join, and `getTemplateContent` calls it once per template file
+ * during a drift scan — ~2ms per scan uncached, on a pre-flight path #708
+ * deliberately keeps in the 2-5ms range. The install layout cannot change
+ * within a process, so caching it is safe. Only the *bundled* resolution is
+ * cached; the env override is re-read every call, so tests that set and unset
+ * `SEQUANT_TEMPLATES_DIR` are unaffected.
+ */
+let cachedBundledTemplatesDir;
 // Get the package templates directory
 export function getTemplatesDir() {
     // Allow overriding the templates source (used by tests; also lets the dir be
-    // relocated without relying on the compiled-output layout below).
+    // relocated without relying on the compiled-output layout below). Returned
+    // verbatim — the override is authoritative and is never probed, so a bad
+    // value surfaces at `assertTemplatesDirExists` rather than silently falling
+    // back to the bundled tree.
     if (process.env.SEQUANT_TEMPLATES_DIR) {
         return process.env.SEQUANT_TEMPLATES_DIR;
     }
-    const __dirname = dirname(fileURLToPath(import.meta.url));
-    // Compiled structure: dist/src/lib/templates.js
-    // So we need ../../../templates to reach project root templates/
-    const devPath = join(__dirname, "..", "..", "..", "templates");
-    return devPath;
+    if (cachedBundledTemplatesDir === undefined) {
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        cachedBundledTemplatesDir = resolveTemplatesDirFrom(__dirname, rankTemplatesCandidate);
+    }
+    return cachedBundledTemplatesDir;
+}
+/**
+ * Resolve the templates root and fail loudly when it does not exist.
+ *
+ * A missing templates *root* means the install is broken: every `copyDir` call
+ * below would hit `copyDir`'s per-directory ENOENT skip, no-op, and let the
+ * caller print a success message over an empty tree (#822). That skip is
+ * deliberate for individual subdirectories — a stack may legitimately ship
+ * without `memory/` — but it must not absorb the whole source tree.
+ *
+ * Throws rather than printing so the lib layer stays free of presentation;
+ * commands catch and render.
+ */
+export async function assertTemplatesDirExists() {
+    const templatesDir = getTemplatesDir();
+    // A *directory* check, not a bare existence check: a stray file at that path
+    // would pass `access()` and then fail deeper in `readdir` with the same silent
+    // ENOTDIR-shaped confusion this guard exists to prevent.
+    let isDirectory;
+    try {
+        isDirectory = (await stat(templatesDir)).isDirectory();
+    }
+    catch {
+        isDirectory = false;
+    }
+    if (isDirectory) {
+        return templatesDir;
+    }
+    throw new Error(`Bundled templates directory not found: ${templatesDir}\n` +
+        "This usually means the Sequant install is incomplete or was run from an unexpected layout.\n" +
+        "Reinstall sequant, or set SEQUANT_TEMPLATES_DIR to the templates/ directory.");
 }
 /**
  * Process template variables in content
@@ -112,6 +217,35 @@ export async function buildTemplateVariables(stack, tokens, options = {}) {
         STACK_NOTES: stackNotes,
     };
 }
+/**
+ * Map a bundled template path to the location `copyTemplates` installs it to,
+ * or `null` for templates the copy/diff cycle does not manage.
+ *
+ * This mirrors the routing in `copyTemplates` (write time) so
+ * `computeTemplateChanges` (diff time) can never report drift on a file init
+ * deliberately places elsewhere — `.claude/mcp.json`, `.claude/relay/*`, and
+ * `.claude/scripts/*` read as phantom "new" files on every fresh install when
+ * the diff assumed a flat `.claude/<relpath>` layout. #708 gives the same
+ * guarantee for the template *variables*; this covers the *destinations*.
+ *
+ * - `templates/mcp.json` → `null`: the project `.mcp.json` is generated and
+ *   version-pinned by `mcp-config.ts` (`syncSequantMcpPin`), never copied.
+ * - `templates/relay/` → `null`: not installed by `copyTemplates`.
+ * - `templates/scripts/` → `scripts/dev/`: symlinked on POSIX, copied on
+ *   Windows / `--no-symlinks`.
+ * - everything else → `.claude/<relpath>`.
+ */
+export function templateDestination(templatePath) {
+    const normalized = templatePath.replace(/\\/g, "/");
+    if (normalized === "templates/mcp.json")
+        return null;
+    if (normalized.startsWith("templates/relay/"))
+        return null;
+    if (normalized.startsWith("templates/scripts/")) {
+        return normalized.replace("templates/scripts/", "scripts/dev/");
+    }
+    return normalized.replace("templates/", ".claude/");
+}
 /**
  * Compare bundled template content against what's installed under `.claude/`.
  *
@@ -126,12 +260,13 @@ export async function computeTemplateChanges(stack, tokens, options = {}) {
     const templateFiles = await listTemplateFiles();
     const changes = [];
     for (const templatePath of templateFiles) {
-        // Normalize separators first: listTemplateFiles builds paths with the OS
-        // separator (backslashes on Windows), but the prefix swap and the .local/
-        // and customizable-file checks below all assume forward slashes (#708).
-        const localPath = templatePath
-            .replace(/\\/g, "/")
-            .replace("templates/", ".claude/");
+        // templateDestination normalizes separators (listTemplateFiles builds
+        // paths with the OS separator, backslashes on Windows — #708) and applies
+        // the same routing copyTemplates uses at write time.
+        const localPath = templateDestination(templatePath);
+        if (localPath === null) {
+            continue;
+        }
         // Skip .local files (user customizations are never overwritten)
         if (localPath.includes(".local/")) {
             continue;
@@ -165,8 +300,11 @@ export async function computeTemplateChanges(stack, tokens, options = {}) {
         // auto-skipped above because it lives under `.local/`. The directive sits at
         // the top, not end-of-file, so it fires reliably even in 3000-line skills.
         // See docs/guides/customization.md.
-        const localOverridePath = localPath.replace(".claude/", ".claude/.local/");
-        const hasLocalOverride = await fileExists(localOverridePath);
+        // Only `.claude/` files have `.local/` twins; for `scripts/dev/` paths the
+        // replace would be a no-op and the file would shadow itself as its own
+        // "override".
+        const hasLocalOverride = localPath.startsWith(".claude/") &&
+            (await fileExists(localPath.replace(".claude/", ".claude/.local/")));
         if (hasLocalOverride || isCustomizableFile(localPath)) {
             changes.push({
                 path: localPath,
@@ -293,6 +431,9 @@ export async function copyTemplates(stack, tokens, options = {}) {
     const templatesDir = getTemplatesDir();
     // Single source of truth for template variables (shared with the diff path)
     const variables = await buildTemplateVariables(stack, tokens, options);
+    // Customizable files skipped on the write path (see copyDir), surfaced to the
+    // caller so it can report them without a second diff pass (#814).
+    const preservedCustomizable = [];
     async function copyDir(srcDir, destDir) {
         try {
             const entries = await readdir(srcDir, { withFileTypes: true });
@@ -307,6 +448,20 @@ export async function copyTemplates(stack, tokens, options = {}) {
                     // Read, process, and write
                     let content = await readFile(srcPath);
                     content = processTemplate(content, variables);
+                    // Protect in-place customizations on the write path. A file in
+                    // CUSTOMIZABLE_FILES that already exists and differs from the
+                    // rendered template is preserved unless the caller explicitly opted
+                    // in via `overwriteCustomizable`. A missing file (fresh install) or
+                    // an identical one falls through and is written as usual (#814).
+                    if (!options.overwriteCustomizable &&
+                        isCustomizableFile(destPath) &&
+                        (await fileExists(destPath))) {
+                        const existing = await readFile(destPath);
+                        if (existing !== content) {
+                            preservedCustomizable.push(destPath.replace(/\\/g, "/"));
+                            continue;
+                        }
+                    }
                     await writeFile(destPath, content);
                     // Make shell scripts executable
                     if (entry.name.endsWith(".sh")) {
@@ -352,5 +507,5 @@ export async function copyTemplates(stack, tokens, options = {}) {
     }
     // Write skills version marker for sync detection
     await writeFile(SKILLS_VERSION_PATH, getPackageVersion());
-    return { scriptsSymlinked, symlinkResults };
+    return { scriptsSymlinked, symlinkResults, preservedCustomizable };
 }

package/dist/src/lib/test-tautology-detector.d.ts

@@ -100,9 +100,17 @@ export declare function extractTestBlocks(content: string): Array<{
     style: "it" | "test";
 }>;
 /**
- * Check if a test block contains calls to any of the imported production functions
+ * Check if a test block calls production code. A block counts as non-tautological
+ * when it references an imported production function, directly spawns the
+ * project's build output, or calls a helper that (transitively) does so.
+ *
+ * @param productionHandles Names of describe/module-scope helpers that reach
+ *   production — by spawning the project's executable code or by calling an
+ *   imported production function (see {@link collectProductionHandles}).
+ * @param buildOutputVars Variable names bound to a build-output path (see
+ *   {@link collectBuildOutputVars}).
  */
-export declare function testBlockCallsProductionCode(body: string, importedFunctions: ImportedFunction[]): boolean;
+export declare function testBlockCallsProductionCode(body: string, importedFunctions: ImportedFunction[], productionHandles?: string[], buildOutputVars?: string[]): boolean;
 /**
  * Check if a file opts out of tautology detection via pragma comment.
  *

package/dist/src/lib/test-tautology-detector.js

@@ -341,20 +341,219 @@ function escapeRegex(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 /**
- * Check if a test block contains calls to any of the imported production functions
+ * Build a whole-identifier reference matcher for `name`, bounded by
+ * non-identifier chars ([\w$]). Catches direct calls, method calls, callback
+ * references, and assignments while rejecting substring matches.
  */
-export function testBlockCallsProductionCode(body, importedFunctions) {
-    if (importedFunctions.length === 0) {
-        return false;
+function referenceMatcher(name) {
+    return new RegExp(`(?<![\\w$])${escapeRegex(name)}(?![\\w$])`);
+}
+/**
+ * Child-process spawn functions. A test that spawns the project's *build
+ * output* is exercising production code across a process boundary that static
+ * import analysis cannot see through — issue #885.
+ *
+ * Two alternates by name ambiguity: the long names are unambiguous
+ * child-process API and match anywhere, including method-style calls from a
+ * namespace import (`cp.execSync(...)`). The short names (`exec`, `spawn`,
+ * `fork`) collide with unrelated methods — `RegExp.prototype.exec` most of
+ * all — so they must not be preceded by `.` (or an identifier char). The
+ * cost is that method-style callback `cp.exec(...)` no longer counts; tests
+ * that spawn build output overwhelmingly use the sync variants, and a false
+ * tautology report is loud where the `.exec()` collision was silent.
+ */
+const SPAWN_PATTERN = /(?:\b(?:execFileSync|spawnSync|execSync|execFile)\s*\(|(?<![\w$.])(?:exec|fork|spawn)\s*\()/;
+/**
+ * Marker for the project's build-output directory. A spawn whose arguments
+ * reach this path is running compiled production code.
+ */
+const BUILD_OUTPUT_PATTERN = /\bdist\//;
+/**
+ * Non-compiled production code this project ships and executes: the hook
+ * scripts and the `scripts/` + `templates/scripts/` trees (#906).
+ *
+ * `dist/` alone was too narrow. `checkout-lock.integration.test.ts` drives the
+ * real `.claude/hooks/pre-tool.sh` as a subprocess — that hook IS the
+ * enforcement half of the feature under test — yet every block in the file
+ * read as tautological because the path is not under `dist/`.
+ */
+const PROJECT_SCRIPT_PATTERN = /\b(?:hooks\/[\w.-]+\.sh|scripts\/[\w./-]+)/;
+/**
+ * Collect names of variables bound to a path into the project's own executable
+ * code, e.g.
+ *   const cliPath = resolve(projectRoot, "dist/bin/cli.js");
+ *   const HOOK    = join(REPO_ROOT, ".claude/hooks/pre-tool.sh");
+ * captures `cliPath` / `HOOK`. Tests almost always spawn via such a handle
+ * rather than an inline string, so these names stand in for the literal path.
+ *
+ * The right-hand side is statement-bounded (`[^;]`) so a match cannot bleed
+ * across declarations, and must reach one of the two markers. Spawning a
+ * *system* binary (`git`, `bash` with a temp fixture) matches neither, which
+ * is the intended exclusion — those are not this project's code.
+ */
+function collectBuildOutputVars(content) {
+    const names = new Set();
+    const patterns = [
+        /(?:const|let|var)\s+(\w+)\s*=\s*[^;]*?\bdist\//g,
+        /(?:const|let|var)\s+(\w+)\s*=\s*[^;]*?\b(?:hooks\/[\w.-]+\.sh|scripts\/[\w./-]+)/g,
+    ];
+    for (const pattern of patterns) {
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+            names.add(match[1]);
+        }
     }
+    return [...names];
+}
+/**
+ * Whether a code body references a build-output token: either the literal
+ * `dist/` marker or one of the collected build-path variable names.
+ */
+function referencesBuildOutput(body, buildOutputVars) {
+    if (BUILD_OUTPUT_PATTERN.test(body) || PROJECT_SCRIPT_PATTERN.test(body)) {
+        return true;
+    }
+    return buildOutputVars.some((name) => referenceMatcher(name).test(body));
+}
+/**
+ * Whether a code body itself spawns the build output: it must contain BOTH a
+ * child-process spawn call AND a build-output token. Requiring co-occurrence
+ * keeps a helper that merely mentions `dist/` in a string (but never spawns)
+ * from counting as production (#885 AC-5).
+ */
+function spawnsBuildOutput(body, buildOutputVars) {
+    return (SPAWN_PATTERN.test(body) && referencesBuildOutput(body, buildOutputVars));
+}
+/**
+ * Extract module/describe-scope helper definitions as { name, body } pairs.
+ *
+ * Two shapes, because both are idiomatic and a detector that saw only one
+ * produced large-scale false positives (#906): a test calling a helper the
+ * detector cannot see reads as import-less, hence tautological. Measured on
+ * `checkout-lock.integration.test.ts` (helpers written as `function`
+ * declarations): 17 of 19 blocks flagged, every one of them real.
+ *
+ * Params are matched with `[^()]*` (no nested parens) to keep the scan from
+ * running away across the file. Expression-bodied arrows are skipped — they
+ * have no `{` body to extract.
+ */
+function extractHelperDefinitions(content) {
+    const helpers = [];
+    // Arrow consts anchor on `=> {`, so the body brace is unambiguous.
+    const arrowPattern = /(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\([^()]*\)\s*(?::[^=]*?)?=>\s*\{/g;
+    let match;
+    while ((match = arrowPattern.exec(content)) !== null) {
+        if (isInsideString(content, match.index))
+            continue;
+        const braceIndex = match.index + match[0].length - 1;
+        helpers.push({
+            name: match[1],
+            body: extractBlockBody(content.substring(braceIndex)),
+        });
+    }
+    // Declarations have no `=>` marker, and the return-type annotation may open
+    // a brace group of its own:
+    //   function runHook(o): { status: number; stderr: string } { ... }
+    // so the body is NOT simply the first `{` after the parameters. Do not try
+    // to express that in the regex — a greedy annotation subpattern silently ran
+    // past the body and anchored on the NEXT declaration's brace, yielding a
+    // "helper" whose body was somebody else's code (caught by the object
+    // return-type test below). Match only to the closing paren, then walk: take
+    // the first brace group; if another `{` follows it, that group was the
+    // return type and the body is the next one.
+    const declPattern = /(?:async\s+)?function\s*\*?\s*(\w+)\s*\([^()]*\)/g;
+    while ((match = declPattern.exec(content)) !== null) {
+        if (isInsideString(content, match.index))
+            continue;
+        const rest = content.substring(match.index + match[0].length);
+        const firstBrace = rest.indexOf("{");
+        if (firstBrace === -1)
+            continue;
+        // Anything between `)` and the first `{` must be an annotation, not code.
+        if (/[;)=]/.test(rest.substring(0, firstBrace)))
+            continue;
+        let body = extractBlockBody(rest.substring(firstBrace));
+        const after = rest.substring(firstBrace + body.length);
+        if (/^\s*\{/.test(after)) {
+            body = extractBlockBody(after);
+        }
+        helpers.push({ name: match[1], body });
+    }
+    return helpers;
+}
+/**
+ * Collect the names of helper functions that reach production code, resolving
+ * indirection transitively: a helper that calls an already-known handle is
+ * itself a handle. This lets a test that only calls `expectFlagAccepted(...)`
+ * (which calls `runInUninitializedDir`, which spawns the CLI) count as
+ * exercising production code.
+ *
+ * A helper qualifies two ways:
+ *  - it spawns the project's own executable code (subprocess integration
+ *    tests), or
+ *  - it references an imported production function (#906). `makeLock()`
+ *    returning `new CheckoutLock({...})` is production code by any reading,
+ *    but seeding on spawns alone missed it, so every test that built its
+ *    subject through a factory read as tautological.
+ */
+function collectProductionHandles(content, buildOutputVars, importedFunctions = []) {
+    const helpers = extractHelperDefinitions(content);
+    const handles = new Set();
+    // Seed: helpers that directly reach production.
+    for (const helper of helpers) {
+        if (spawnsBuildOutput(helper.body, buildOutputVars) ||
+            importedFunctions.some((fn) => referenceMatcher(fn.name).test(helper.body))) {
+            handles.add(helper.name);
+        }
+    }
+    // Transitive closure: a helper referencing a known spawn helper is one too.
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const helper of helpers) {
+            if (handles.has(helper.name)) {
+                continue;
+            }
+            for (const known of handles) {
+                if (referenceMatcher(known).test(helper.body)) {
+                    handles.add(helper.name);
+                    changed = true;
+                    break;
+                }
+            }
+        }
+    }
+    return [...handles];
+}
+/**
+ * Check if a test block calls production code. A block counts as non-tautological
+ * when it references an imported production function, directly spawns the
+ * project's build output, or calls a helper that (transitively) does so.
+ *
+ * @param productionHandles Names of describe/module-scope helpers that reach
+ *   production — by spawning the project's executable code or by calling an
+ *   imported production function (see {@link collectProductionHandles}).
+ * @param buildOutputVars Variable names bound to a build-output path (see
+ *   {@link collectBuildOutputVars}).
+ */
+export function testBlockCallsProductionCode(body, importedFunctions, productionHandles = [], buildOutputVars = []) {
+    // 1. References an imported production function.
     for (const fn of importedFunctions) {
-        // Check for any reference to the imported name bounded by non-identifier chars.
-        // Uses [\w$] to match JS identifier characters (letters, digits, _, $).
-        // This catches direct calls (fn()), method calls (ns.method()),
-        // callback references (arr.map(fn)), and assignments (const x = fn).
-        const escaped = escapeRegex(fn.name);
-        const referencePattern = new RegExp(`(?<![\\w$])${escaped}(?![\\w$])`);
-        if (referencePattern.test(body)) {
+        if (referenceMatcher(fn.name).test(body)) {
+            return true;
+        }
+    }
+    // 2. Directly spawns the project's build output (#885). Static import
+    //    analysis can't see through a subprocess boundary, so a test that runs
+    //    `dist/bin/cli.js` looks import-less but exercises production code.
+    if (spawnsBuildOutput(body, buildOutputVars)) {
+        return true;
+    }
+    // 3. Calls a describe/module-scope helper that (transitively) reaches
+    //    production — spawns the project's executable code, or calls an imported
+    //    production function (#906). Covers arrow-const and `function` helpers.
+    for (const handle of productionHandles) {
+        if (referenceMatcher(handle).test(body)) {
             return true;
         }
     }
@@ -389,12 +588,14 @@ export function analyzeTestFile(content, filePath) {
     }
     try {
         const importedFunctions = extractImports(content);
+        const buildOutputVars = collectBuildOutputVars(content);
+        const productionHandles = collectProductionHandles(content, buildOutputVars, importedFunctions);
         const testBlocks = extractTestBlocks(content);
         const analyzedBlocks = testBlocks.map((block) => ({
             description: block.description,
             lineNumber: block.lineNumber,
             style: block.style,
-            isTautological: !testBlockCallsProductionCode(block.body, importedFunctions),
+            isTautological: !testBlockCallsProductionCode(block.body, importedFunctions, productionHandles, buildOutputVars),
         }));
         const tautologicalCount = analyzedBlocks.filter((b) => b.isTautological).length;
         const totalTests = analyzedBlocks.length;

package/dist/src/lib/version-check.d.ts

@@ -53,6 +53,37 @@ export declare function isGlobalInstall(installPath?: string): boolean;
  * neither receives the project-local "use npm update sequant" warning.
  */
 export declare function isLocalNodeModulesInstall(installPath?: string): boolean;
+/**
+ * Check if running from the npx cache (~/.npm/_npx/<hash>/node_modules/sequant).
+ *
+ * Separated from `isLocalNodeModulesInstall`, which deliberately excludes the
+ * cache: that predicate answers "is this a project dependency the user can
+ * `npm update`", while this one answers "did the user reach us through npx".
+ * Backslashes are normalized first, so the single forward-slash form also
+ * matches a Windows `…\.npm\_npx\…` path.
+ */
+export declare function isNpxCacheInstall(installPath?: string): boolean;
+/**
+ * Resolve the invocation to name in user-facing "run this next" messages.
+ *
+ * A hardcoded `npx sequant` is right for the documented install path (README:
+ * `npm install sequant` then `npx sequant init`) — npx resolves the project's
+ * `node_modules/.bin/sequant`, and a bare `sequant` would not be on PATH. It is
+ * wrong for a global or `npm link`ed install with no local dependency: there,
+ * `npx sequant` cannot resolve locally and falls through to the npx cache,
+ * which can hold an older *published* copy than the one currently running. The
+ * observed symptom is a remediation that fights itself — the recommended
+ * command reinstalls the very content whose staleness triggered the message.
+ *
+ * So recommend the form that actually reaches *this* build:
+ * - project-local dependency or npx cache → `npx sequant`
+ * - global, `npm link`ed, or a dev checkout → `sequant`
+ *
+ * A linked checkout resolves through its realpath (Node resolves symlinks
+ * unless `--preserve-symlinks` is set), so it looks like neither a global nor a
+ * local install and correctly lands on the bare form.
+ */
+export declare function resolveCliInvocation(installPath?: string): "sequant" | "npx sequant";
 /**
  * Walk up from the given directory to find the directory containing
  * sequant's package.json. Returns null if not found.

package/dist/src/lib/version-check.js

@@ -8,7 +8,7 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import { fileURLToPath } from "url";
-import { detectPackageManagerSync, getPackageManagerCommands, } from "./stacks.js";
+import { detectPackageManagerSync, resolvePackageManagerConfig, } from "./stacks.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PACKAGE_NAME = "sequant";
@@ -92,6 +92,44 @@ export function isLocalNodeModulesInstall(installPath = __dirname) {
         normalizedPath.includes("\\.npm\\_npx\\");
     return inNodeModules && !inNpxCache && !isGlobalInstall(normalizedPath);
 }
+/**
+ * Check if running from the npx cache (~/.npm/_npx/<hash>/node_modules/sequant).
+ *
+ * Separated from `isLocalNodeModulesInstall`, which deliberately excludes the
+ * cache: that predicate answers "is this a project dependency the user can
+ * `npm update`", while this one answers "did the user reach us through npx".
+ * Backslashes are normalized first, so the single forward-slash form also
+ * matches a Windows `…\.npm\_npx\…` path.
+ */
+export function isNpxCacheInstall(installPath = __dirname) {
+    return installPath.replace(/\\/g, "/").includes("/.npm/_npx/");
+}
+/**
+ * Resolve the invocation to name in user-facing "run this next" messages.
+ *
+ * A hardcoded `npx sequant` is right for the documented install path (README:
+ * `npm install sequant` then `npx sequant init`) — npx resolves the project's
+ * `node_modules/.bin/sequant`, and a bare `sequant` would not be on PATH. It is
+ * wrong for a global or `npm link`ed install with no local dependency: there,
+ * `npx sequant` cannot resolve locally and falls through to the npx cache,
+ * which can hold an older *published* copy than the one currently running. The
+ * observed symptom is a remediation that fights itself — the recommended
+ * command reinstalls the very content whose staleness triggered the message.
+ *
+ * So recommend the form that actually reaches *this* build:
+ * - project-local dependency or npx cache → `npx sequant`
+ * - global, `npm link`ed, or a dev checkout → `sequant`
+ *
+ * A linked checkout resolves through its realpath (Node resolves symlinks
+ * unless `--preserve-symlinks` is set), so it looks like neither a global nor a
+ * local install and correctly lands on the bare form.
+ */
+export function resolveCliInvocation(installPath = __dirname) {
+    return isLocalNodeModulesInstall(installPath) ||
+        isNpxCacheInstall(installPath)
+        ? "npx sequant"
+        : "sequant";
+}
 /**
  * Walk up from the given directory to find the directory containing
  * sequant's package.json. Returns null if not found.
@@ -314,7 +352,12 @@ export function getVersionWarning(currentVersion, latestVersion, isLocal) {
     const isLocalInstall = isLocal ?? isLocalNodeModulesInstall();
     if (isLocalInstall) {
         const pm = detectPackageManagerSync();
-        const pmConfig = getPackageManagerCommands(pm);
+        // Resolved, not read off PM_CONFIG: `updatePkg` is one of the fields whose
+        // yarn spelling depends on the major (berry `yarn up` vs classic
+        // `yarn upgrade`), and this string is a command we are telling the user to
+        // run. Both `detectPackageManagerSync` and the resolver read the cwd, which
+        // is the project this local install belongs to (#871).
+        const pmConfig = resolvePackageManagerConfig(pm, process.cwd());
         return `sequant ${latestVersion} is available (you have ${currentVersion})
    Run: ${pmConfig.updatePkg} sequant
    Note: You have sequant as a local dependency. npx uses your node_modules version.`;