sequant 2.9.0 → 2.10.0

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

@@ -100,9 +100,16 @@ 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 spawnHandles Names of describe/module-scope helpers that spawn the
+ *   build output (see {@link collectSpawnHandles}).
+ * @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[], spawnHandles?: 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,159 @@ 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\//;
+/**
+ * Collect names of variables bound to a build-output path, e.g.
+ *   const cliPath = resolve(projectRoot, "dist/bin/cli.js");
+ * captures `cliPath`. Tests almost always spawn via such a handle rather than
+ * an inline string, so these names stand in for the literal build path.
+ *
+ * The right-hand side is statement-bounded (`[^;]`) so a match cannot bleed
+ * across declarations, and must contain the `dist/` marker.
+ */
+function collectBuildOutputVars(content) {
+    const names = new Set();
+    const pattern = /(?:const|let|var)\s+(\w+)\s*=\s*[^;]*?\bdist\//g;
+    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)) {
+        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 (named block-bodied arrow
+ * consts) as { name, body } pairs.
+ *
+ * Anchors on `=> {` so a return-type object annotation
+ *   const run = (): { stdout: string } => { ... }
+ * is not mistaken for the function body. Params are matched with `[^()]*` (no
+ * nested parens) to keep the scan from running away across the file. Only
+ * block-bodied arrows are collected; the subprocess integration tests this
+ * targets all use them.
+ */
+function extractHelperDefinitions(content) {
+    const helpers = [];
+    const pattern = /(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\([^()]*\)\s*(?::[^=]*?)?=>\s*\{/g;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        if (isInsideString(content, match.index)) {
+            continue;
+        }
+        const name = match[1];
+        // The final `{` of the match is the function body's opening brace.
+        const braceIndex = match.index + match[0].length - 1;
+        const body = extractBlockBody(content.substring(braceIndex));
+        helpers.push({ name, body });
+    }
+    return helpers;
+}
+/**
+ * Collect the names of helper functions that spawn the build output, resolving
+ * indirection transitively: a helper that calls an already-known spawn helper
+ * is itself a spawn helper. This lets a test that only calls
+ * `expectFlagAccepted(...)` (which calls `runInUninitializedDir`, which spawns
+ * the CLI) count as exercising production code.
+ */
+function collectSpawnHandles(content, buildOutputVars) {
+    const helpers = extractHelperDefinitions(content);
+    const handles = new Set();
+    // Seed: helpers that directly spawn the build output.
+    for (const helper of helpers) {
+        if (spawnsBuildOutput(helper.body, buildOutputVars)) {
+            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 spawnHandles Names of describe/module-scope helpers that spawn the
+ *   build output (see {@link collectSpawnHandles}).
+ * @param buildOutputVars Variable names bound to a build-output path (see
+ *   {@link collectBuildOutputVars}).
+ */
+export function testBlockCallsProductionCode(body, importedFunctions, spawnHandles = [], 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) spawns the
+    //    build output.
+    for (const handle of spawnHandles) {
+        if (referenceMatcher(handle).test(body)) {
             return true;
         }
     }
@@ -389,12 +528,14 @@ export function analyzeTestFile(content, filePath) {
     }
     try {
         const importedFunctions = extractImports(content);
+        const buildOutputVars = collectBuildOutputVars(content);
+        const spawnHandles = collectSpawnHandles(content, buildOutputVars);
         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, spawnHandles, 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.`;

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

@@ -7,6 +7,7 @@
  * (including quality-loop retries, checkpoint commits, rebasing, and PR
  * creation).
  */
+import { LogWriter } from "./log-writer.js";
 import { ExecutionConfig, PhaseResult, IssueResult, type RunOptions, type IssueExecutionContext, type BatchExecutionContext, type ProgressCallback } from "./types.js";
 import { type ErrorCategory } from "./error-classifier.js";
 export type { RunOptions, ProgressCallback, IssueExecutionContext, BatchExecutionContext, } from "./types.js";
@@ -21,15 +22,32 @@ export type { RunOptions, ProgressCallback, IssueExecutionContext, BatchExecutio
  * @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).
+ * Wrap an `ExecutionConfig` with the runtime liveness hooks:
+ * - `onActivity` — re-emits each agent-output ping as an `"activity"` progress
+ *   event for the dashboard (#543).
+ * - `onAutoWait` — re-emits each auto-wait tick as a `"waiting"` progress
+ *   event so the renderer and heartbeat can show the pause and its wake time
+ *   (#804 AC-7). Under `SEQUANT_ORCHESTRATOR` it additionally emits throttled
+ *   `SEQUANT_PROGRESS` waiting lines (#860): an MCP-driven wait was previously
+ *   invisible on the JSON channel — indistinguishable from a hang — AND was
+ *   killed by the MCP inactivity timeout, which resets on progress lines.
+ *   Optionally notifies `onWaitTransition` on wait start/end so the caller
+ *   can persist the wait to issue state (`sequant status` truthfulness).
  *
- * Returns the input config unchanged when no `onProgress` callback is set,
- * so non-TUI runs pay no overhead.
+ * Returns the input config unchanged when there is no consumer at all (no
+ * `onProgress`, no orchestrator channel, no transition callback), so plain
+ * 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;
+export declare function withActivityHook(base: ExecutionConfig, issueNumber: number, phase: string, onProgress: ProgressCallback | undefined, onWaitTransition?: (wakeAtMs: number | null) => void): ExecutionConfig;
+/**
+ * Cadence of orchestrator-channel waiting lines during an auto-wait (#860).
+ * See {@link withActivityHook}.
+ *
+ * @internal Exported for testing only
+ */
+export declare const AUTO_WAIT_PROGRESS_LINE_INTERVAL_MS = 60000;
 /**
  * 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
@@ -38,10 +56,12 @@ export declare function withActivityHook(base: ExecutionConfig, issueNumber: num
  * @internal Exported for testing only
  */
 export declare function buildLoopContext(failedResult: PhaseResult): string;
-export declare function emitProgressLine(issue: number, phase: string, event?: "start" | "complete" | "failed", extra?: {
+export declare function emitProgressLine(issue: number, phase: string, event?: "start" | "complete" | "failed" | "waiting", extra?: {
     durationSeconds?: number;
     error?: string;
     iteration?: number;
+    wakeAtMs?: number;
+    remainingMs?: number;
 }): void;
 /**
  * Emit the current run's UUID on stderr so MCP callers can look up the exact
@@ -73,6 +93,32 @@ export declare function parseBatches(batchArgs: string[]): number[][];
  * Parse environment variables for CI configuration
  */
 export declare function getEnvConfig(): Partial<RunOptions>;
+/**
+ * Record an issue's completion in the run log in ONE place (#879): PR info, the
+ * PR-failure status flip, then finalize. Extracted so every batch loop shares a
+ * single completion sequence and cannot drift.
+ *
+ * The #879 defect was exactly such a drift: `markIssueFailed` was wired into
+ * `executeBatch`'s loop, but the live `sequant run` path is
+ * `RunOrchestrator.executeOneIssue`, which called `setPRInfo` + `completeIssue`
+ * without it — so a real run left the run-log status at `success` on a
+ * PR-creation failure. Both call sites now go through this helper.
+ *
+ * A PR-creation failure occurs after every phase has been logged, so
+ * `deriveIssueLogStatus` (last run at phase-log time) leaves the issue at
+ * `success`; the flip here is what counts it under `failed`. Safe post-hoc:
+ * no further phase is logged before `completeIssue`.
+ */
+export declare function recordIssueCompletion(logWriter: LogWriter, result: IssueResult, issueNumber?: number): void;
+/**
+ * @deprecated No live caller — `sequant run` executes issues via
+ * `RunOrchestrator.executeOneIssue`; this survives only as a
+ * `commands/run-compat` re-export. Do not build a new execution loop on it:
+ * any path that completes an issue MUST go through
+ * {@link recordIssueCompletion}, or the #879 status-drift returns (a
+ * completion path that skips the PR-failure flip logs a failed issue as
+ * `success`). Slated for removal with the run-compat surface.
+ */
 export declare function executeBatch(issueNumbers: number[], batchCtx: BatchExecutionContext): Promise<IssueResult[]>;
 /**
  * Derive the bounded-enum failure category for a failed issue (#761 AC-7).
@@ -86,4 +132,77 @@ export declare function executeBatch(issueNumbers: number[], batchCtx: BatchExec
  * @internal Exported for testing
  */
 export declare function deriveFailureCategory(phaseResults: PhaseResult[]): ErrorCategory | undefined;
+/**
+ * "Halt, don't loop" predicate for the outer `-Q` quality loop (#799).
+ *
+ * A billing / out-of-credits failure (`BillingError`) or a window-exhausted
+ * rate limit (reset hours away, per `isWindowExhaustedRateLimit`) cannot be
+ * recovered by re-running the phase — every retry re-spawns into the same
+ * closed window and, worse, mislabels the halt as a downstream
+ * `QA completed without a parseable verdict`. Mirrors the `haltedByCap` (#739)
+ * treatment: surface the real cause and halt so the user resumes once credits
+ * or the rate-limit window are restored.
+ *
+ * A transient / metadata-absent rate limit is NOT a halt: it returns false and
+ * keeps today's outer-loop behavior (the inner retry ladder in `phase-executor`
+ * handles its backoff, per #761 AC-4/AC-9).
+ *
+ * @internal Exported for testing
+ */
+export declare function isBillingOrWindowHalt(result: PhaseResult): boolean;
+/**
+ * The billing half of {@link isBillingOrWindowHalt} (#804 AC-8).
+ *
+ * Split out because the two causes stopped being interchangeable once
+ * `--auto-wait` existed: a closed window can now reopen on its own, while
+ * out-of-credits cannot — credits are purchased, not waited out. Callers that
+ * need to reason about recoverability must be able to tell them apart.
+ *
+ * @internal Exported for testing
+ */
+export declare function isBillingHalt(result: PhaseResult): boolean;
+/**
+ * The rate-limit-window half of {@link isBillingOrWindowHalt} (#804 AC-8).
+ *
+ * NOTE — this predicate needed no behavioral change for auto-wait, and that is
+ * a deliberate finding rather than an oversight. AC-8 anticipated that a phase
+ * which waits and then succeeds would still halt the `-Q` loop. It cannot:
+ * every call site (`:~700` spec, `:~1030` progress label, `:~1150` halt flag)
+ * sits inside the `else` of an `if (result.success)`, so a successful
+ * post-wait result never reaches this predicate at all. When auto-wait does
+ * NOT fire — the default, an exhausted budget, or a spent wait bound — the
+ * result is still a failure carrying a window-exhausted `RateLimitError`, and
+ * halting is then the correct outcome (#799 behavior, preserved exactly).
+ *
+ * @internal Exported for testing
+ */
+export declare function isWindowHalt(result: PhaseResult): boolean;
+/**
+ * Human-readable halt reason for a billing / rate-limit-window failure (#799
+ * AC-3). Surfaces the driver's real cause verbatim — `result.error` is already
+ * the well-formatted message the driver built via `formatRateLimitMessage`
+ * (`Out of credits` for billing, `Rate limited — resets at <local time>` for a
+ * throttle with a known reset), so the phase-failed line and run summary name
+ * the actual cause instead of a downstream `QA completed without a parseable
+ * verdict`.
+ *
+ * Do NOT re-append `resetsAt` here: the rate-limit message already carries the
+ * reset time, and doing so produced a doubled, timezone-inconsistent string
+ * (`… resets at 07-24 14:32 — resets at 2026-…Z`). Credits failures carry no
+ * reset time by design (they need purchasing, not a window wait).
+ *
+ * @internal Exported for testing
+ */
+export declare function billingHaltReason(result: PhaseResult): string;
+/**
+ * Epoch ms after which a waitable-window halt can be re-entered (#892 AC-1):
+ * the window's `resetsAt` normalized to ms plus the same buffer auto-wait
+ * applies (`AUTO_WAIT_BUFFER_MS`), so in-process waits and durable halts wake
+ * on the same clock. Returns `null` when the result carries no future-reset
+ * rate-limit window — callers must then skip the `windowHalt` write rather
+ * than invent a resume time.
+ *
+ * @internal Exported for testing
+ */
+export declare function windowHaltResumeAtMs(result: PhaseResult): number | null;
 export declare function runIssueWithLogging(ctx: IssueExecutionContext): Promise<IssueResult>;