sequant 2.2.0 → 2.4.0

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

@@ -28,16 +28,71 @@ export declare function getCachePath(): string;
  */
 export declare function getCurrentVersion(): string;
 /**
- * Check if running from a local node_modules install (vs npx cache)
+ * Check if running from a global install (npm root -g).
+ *
+ * On POSIX, npm's global root convention puts packages under
+ * `<prefix>/lib/node_modules/` (e.g. `/usr/local/lib/node_modules`,
+ * `/opt/homebrew/lib/node_modules`, `~/.nvm/versions/node/<v>/lib/node_modules`).
+ *
+ * On Windows, the default global root is `%AppData%\npm\node_modules\` —
+ * sometimes nested under `Roaming\` depending on the npm/Node installer —
+ * with no `lib\` segment. Both variants are matched here.
+ *
+ * Project-local installs live under `<project>/node_modules/` and don't match
+ * either pattern.
+ */
+export declare function isGlobalInstall(installPath?: string): boolean;
+/**
+ * Check if running from a local node_modules install (vs npx cache or global).
  *
  * Local installs are in: <project>/node_modules/sequant/
  * npx installs are in: ~/.npm/_npx/<hash>/node_modules/sequant/
+ * Global installs are in: <prefix>/lib/node_modules/sequant/
+ *
+ * Only project-local installs return true — npx and globals are excluded so
+ * neither receives the project-local "use npm update sequant" warning.
+ */
+export declare function isLocalNodeModulesInstall(installPath?: string): boolean;
+/**
+ * Walk up from the given directory to find the directory containing
+ * sequant's package.json. Returns null if not found.
+ *
+ * Mirrors the walk-up in getCurrentVersion() so callers can reason about
+ * the install root (the directory that actually holds sequant's package.json),
+ * which is needed to distinguish between e.g. project-local installs and the
+ * pathological $HOME/node_modules/sequant case.
+ *
+ * @internal Exported for testability and reuse in bin/cli.ts. Not a stable
+ * public API — may change without a major version bump.
+ */
+export declare function getInstallRoot(startDir?: string): string | null;
+/**
+ * Check whether sequant is installed in $HOME/node_modules/sequant exactly.
+ *
+ * This is a known footgun: a stray `npm install sequant` run from $HOME
+ * leaves a package.json + node_modules/ at the home root, and Node's module
+ * resolution then walks up from any home subdirectory to that stale install
+ * before falling back to the npx cache. The result is that `npx sequant`
+ * silently runs the home-stray copy instead of the latest version.
+ *
+ * Project-local installs (anywhere else under node_modules/), global installs,
+ * and the npx cache all return false.
+ *
+ * `installRoot` is accepted as a parameter for testability.
+ */
+export declare function isHomeStrayInstall(installRoot?: string | null): boolean;
+/**
+ * Render the home-stray warning string for a given install root.
+ *
+ * Extracted from bin/cli.ts so the rendered output can be asserted in unit
+ * tests; the predicate (isHomeStrayInstall) and the emission are then both
+ * covered without spawning a child process. Returns the warning text without
+ * any chalk styling — the caller decides whether to colorize.
  *
- * This matters because:
- * - Local installs should be updated with: npm update sequant
- * - npx installs should be updated with: npx sequant@latest
+ * @internal Exported for the bin/cli.ts caller and unit tests. Not a stable
+ * public API — may change without a major version bump.
  */
-export declare function isLocalNodeModulesInstall(): boolean;
+export declare function buildHomeStrayWarning(installRoot: string): string;
 /**
  * Read the version cache
  */

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

@@ -5,6 +5,7 @@
  * with the latest version on npm.
  */
 import fs from "fs";
+import os from "os";
 import path from "path";
 import { fileURLToPath } from "url";
 import { detectPackageManagerSync, getPackageManagerCommands, } from "./stacks.js";
@@ -56,23 +57,110 @@ export function getCurrentVersion() {
     }
 }
 /**
- * Check if running from a local node_modules install (vs npx cache)
+ * Check if running from a global install (npm root -g).
+ *
+ * On POSIX, npm's global root convention puts packages under
+ * `<prefix>/lib/node_modules/` (e.g. `/usr/local/lib/node_modules`,
+ * `/opt/homebrew/lib/node_modules`, `~/.nvm/versions/node/<v>/lib/node_modules`).
+ *
+ * On Windows, the default global root is `%AppData%\npm\node_modules\` —
+ * sometimes nested under `Roaming\` depending on the npm/Node installer —
+ * with no `lib\` segment. Both variants are matched here.
+ *
+ * Project-local installs live under `<project>/node_modules/` and don't match
+ * either pattern.
+ */
+export function isGlobalInstall(installPath = __dirname) {
+    const normalizedPath = installPath.replace(/\\/g, "/");
+    return (normalizedPath.includes("/lib/node_modules/sequant") ||
+        /\/AppData\/(Roaming\/)?npm\/node_modules\/sequant/.test(normalizedPath));
+}
+/**
+ * Check if running from a local node_modules install (vs npx cache or global).
  *
  * Local installs are in: <project>/node_modules/sequant/
  * npx installs are in: ~/.npm/_npx/<hash>/node_modules/sequant/
+ * Global installs are in: <prefix>/lib/node_modules/sequant/
  *
- * This matters because:
- * - Local installs should be updated with: npm update sequant
- * - npx installs should be updated with: npx sequant@latest
+ * Only project-local installs return true — npx and globals are excluded so
+ * neither receives the project-local "use npm update sequant" warning.
  */
-export function isLocalNodeModulesInstall() {
-    // Check if our path contains node_modules/sequant but NOT in .npm/_npx
-    const normalizedPath = __dirname.replace(/\\/g, "/");
-    // Running from local node_modules (not npx cache)
+export function isLocalNodeModulesInstall(installPath = __dirname) {
+    const normalizedPath = installPath.replace(/\\/g, "/");
     const inNodeModules = normalizedPath.includes("/node_modules/sequant");
     const inNpxCache = normalizedPath.includes("/.npm/_npx/") ||
         normalizedPath.includes("\\.npm\\_npx\\");
-    return inNodeModules && !inNpxCache;
+    return inNodeModules && !inNpxCache && !isGlobalInstall(normalizedPath);
+}
+/**
+ * Walk up from the given directory to find the directory containing
+ * sequant's package.json. Returns null if not found.
+ *
+ * Mirrors the walk-up in getCurrentVersion() so callers can reason about
+ * the install root (the directory that actually holds sequant's package.json),
+ * which is needed to distinguish between e.g. project-local installs and the
+ * pathological $HOME/node_modules/sequant case.
+ *
+ * @internal Exported for testability and reuse in bin/cli.ts. Not a stable
+ * public API — may change without a major version bump.
+ */
+export function getInstallRoot(startDir = __dirname) {
+    let dir = startDir;
+    while (dir !== path.dirname(dir)) {
+        const candidate = path.resolve(dir, "package.json");
+        try {
+            const content = fs.readFileSync(candidate, "utf8");
+            const pkg = JSON.parse(content);
+            if (pkg.name === "sequant") {
+                return dir;
+            }
+        }
+        catch {
+            // Not found, continue searching
+        }
+        dir = path.dirname(dir);
+    }
+    return null;
+}
+/**
+ * Check whether sequant is installed in $HOME/node_modules/sequant exactly.
+ *
+ * This is a known footgun: a stray `npm install sequant` run from $HOME
+ * leaves a package.json + node_modules/ at the home root, and Node's module
+ * resolution then walks up from any home subdirectory to that stale install
+ * before falling back to the npx cache. The result is that `npx sequant`
+ * silently runs the home-stray copy instead of the latest version.
+ *
+ * Project-local installs (anywhere else under node_modules/), global installs,
+ * and the npx cache all return false.
+ *
+ * `installRoot` is accepted as a parameter for testability.
+ */
+export function isHomeStrayInstall(installRoot = getInstallRoot()) {
+    if (!installRoot)
+        return false;
+    const expected = path.join(os.homedir(), "node_modules", "sequant");
+    return path.resolve(installRoot) === path.resolve(expected);
+}
+/**
+ * Render the home-stray warning string for a given install root.
+ *
+ * Extracted from bin/cli.ts so the rendered output can be asserted in unit
+ * tests; the predicate (isHomeStrayInstall) and the emission are then both
+ * covered without spawning a child process. Returns the warning text without
+ * any chalk styling — the caller decides whether to colorize.
+ *
+ * @internal Exported for the bin/cli.ts caller and unit tests. Not a stable
+ * public API — may change without a major version bump.
+ */
+export function buildHomeStrayWarning(installRoot) {
+    const parent = path.dirname(installRoot);
+    return (`!  Sequant is running from ${installRoot} — this pollutes\n` +
+        `   resolution for every subdirectory of your home directory.\n\n` +
+        `   If accidental (usually is — one stray \`npm install sequant\` from ~ does it):\n` +
+        `       remove ${parent}\n` +
+        `       remove $HOME/package.json and $HOME/package-lock.json\n\n` +
+        `   If intentional: use \`npm install -g sequant\` or the Claude Code plugin.\n`);
 }
 /**
  * Read the version cache

package/dist/src/lib/workflow/batch-executor.d.ts

@@ -7,7 +7,7 @@
  * (including quality-loop retries, checkpoint commits, rebasing, and PR
  * creation).
  */
-import { PhaseResult, IssueResult, type RunOptions, type IssueExecutionContext, type BatchExecutionContext } from "./types.js";
+import { ExecutionConfig, PhaseResult, IssueResult, type RunOptions, type IssueExecutionContext, type BatchExecutionContext, type ProgressCallback } from "./types.js";
 export type { RunOptions, ProgressCallback, IssueExecutionContext, BatchExecutionContext, } from "./types.js";
 /**
  * Emit a structured progress line to stderr for MCP progress notifications.
@@ -19,6 +19,16 @@ export type { RunOptions, ProgressCallback, IssueExecutionContext, BatchExecutio
  * @param event - Phase lifecycle event: "start", "complete", or "failed"
  * @param extra - Optional fields: durationSeconds (on complete), error (on failed)
  */
+/**
+ * Wrap an `ExecutionConfig` with an `onActivity` hook that re-emits each
+ * agent-output ping as a `"activity"` progress event for the dashboard (#543).
+ *
+ * Returns the input config unchanged when no `onProgress` callback is set,
+ * so non-TUI runs pay no overhead.
+ *
+ * @internal Exported for testing only
+ */
+export declare function withActivityHook(base: ExecutionConfig, issueNumber: number, phase: string, onProgress: ProgressCallback | undefined): ExecutionConfig;
 /**
  * Build enriched prompt context for the /loop phase from a failed phase result (#488).
  * Passes QA verdict, failed ACs, and error directly so the /loop skill doesn't need
@@ -30,7 +40,16 @@ export declare function buildLoopContext(failedResult: PhaseResult): string;
 export declare function emitProgressLine(issue: number, phase: string, event?: "start" | "complete" | "failed", extra?: {
     durationSeconds?: number;
     error?: string;
+    iteration?: number;
 }): void;
+/**
+ * Emit the current run's UUID on stderr so MCP callers can look up the exact
+ * log file produced by this subprocess instead of relying on a fuzzy time
+ * filter (#631). Gated on `SEQUANT_ORCHESTRATOR` so CLI users see nothing.
+ *
+ * Must be called before `emitProgressLine` to satisfy AC-1.
+ */
+export declare function emitRunIdLine(runId: string): void;
 export declare function getIssueInfo(issueNumber: number): Promise<{
     title: string;
     labels: string[];