agentic-qe 3.15.5 → 3.15.7

package/dist/cli/utils/coverage-verdict.js

@@ -0,0 +1,193 @@
+/**
+ * Agentic QE v3 - Shared CLI coverage verdict (#995, #1010, #1012)
+ *
+ * One resolution and one verdict for every CLI surface that reports coverage
+ * (`aqe coverage`, the `aqe ci` coverage phase), built on the same shared
+ * functions as the MCP `coverage_analyze_sublinear` handler
+ * (`resolveExistingCoverage`, `thresholdVerdict`, `reconcileRecommendations`):
+ *
+ *   - measured   — an instrumented report covers the target: judged on the
+ *                  metrics the report collected (an uncollected metric is null,
+ *                  never 0%, and is left out of the threshold);
+ *   - unmeasured — the report has no entry for the target, the runner ran 0
+ *                  tests, or only test files were reported: no figure, exit 3;
+ *   - estimate   — no report exists, so the CLI shows a labelled STATIC
+ *                  ESTIMATE. It carries no threshold verdict, is never
+ *                  persisted as evidence, and also exits 3: nothing was measured;
+ *   - error      — the target is missing or the given report is unreadable.
+ */
+import chalk from 'chalk';
+import { walkSourceFiles } from './file-discovery.js';
+import { buildCoverageData, summarizeCoverage } from './coverage-data.js';
+import { describeNoData, reconcileRecommendations, resolveExistingCoverage, thresholdVerdict, } from '../../coordination/handlers/coverage-target.js';
+/** `aqe coverage` exit code when no coverage measurement exists for the target (#995). */
+export const EXIT_UNMEASURED = 3;
+/** Provenance labels, the same vocabulary as MCP `coverage_analyze_sublinear`. */
+export const MEASURED_METHOD = 'instrumented-report';
+export const ESTIMATE_METHOD = 'static-estimation';
+/**
+ * Resolve the coverage data for a CLI target (#995).
+ *
+ * Uses the SAME resolution and verdict as the MCP handler
+ * (`resolveExistingCoverage`), so CLI and MCP cannot disagree about what a
+ * report says for a target:
+ *   - a coverage report file (lcov.info, coverage-final.json, ...) is parsed
+ *     directly;
+ *   - a directory or source file is scoped against the instrumented report of
+ *     its PROJECT ROOT (nearest package.json/.git above it), not the cwd;
+ *   - with no report at the project root, the CLI falls back to its labelled
+ *     heuristic estimate (the CLI never runs the test suite).
+ */
+export async function resolveCliCoverageData(targetPath, log = message => console.log(message)) {
+    const existing = await resolveExistingCoverage(targetPath);
+    if (existing.status === 'target-missing') {
+        return { kind: 'no-data', reason: 'target-missing', message: describeNoData('target-missing', targetPath, null) };
+    }
+    if (existing.status === 'evaluated') {
+        const { evaluation, projectRoot } = existing;
+        if (evaluation.status === 'measured') {
+            const files = evaluation.files;
+            return { kind: 'data', data: { files, summary: summarizeCoverage(files), instrumented: true }, projectRoot };
+        }
+        return { kind: 'no-data', reason: evaluation.reason, message: describeNoData(evaluation.reason, targetPath, projectRoot) };
+    }
+    const sourceFiles = walkSourceFiles(existing.target, { includeTests: false });
+    if (sourceFiles.length === 0)
+        return { kind: 'no-sources' };
+    log(chalk.gray(`  Analyzing ${sourceFiles.length} files...\n`));
+    return { kind: 'data', data: buildCoverageData(sourceFiles, existing.projectRoot), projectRoot: existing.projectRoot };
+}
+/** Which optional metrics an instrumented report actually carries. */
+export function metricsCollected(data) {
+    return {
+        branch: data.files.some(f => f.branches.total > 0),
+        function: data.files.some(f => f.functions.total > 0),
+        // #1027 N7: lcov / Cobertura carry no statement detail.
+        statement: data.files.some(f => f.statements.total > 0),
+    };
+}
+const isError = (reason) => reason === 'target-missing' || reason === 'unreadable-report';
+/** Caller-facing explanation of a static estimate. */
+export function estimateMessage() {
+    return 'UNMEASURED: no coverage report exists for this project, so these figures are a ' +
+        'STATIC ESTIMATE derived from source shape — not measured coverage. No threshold verdict ' +
+        'is given and nothing is stored as evidence. Run your tests with coverage first ' +
+        '(e.g. `npm test -- --coverage`) and re-run.';
+}
+/**
+ * Resolve, analyze and judge coverage for a CLI target. Shared by
+ * `aqe coverage` and the `aqe ci` coverage phase.
+ */
+export async function evaluateCliCoverage(api, targetPath, threshold, log) {
+    const resolved = await resolveCliCoverageData(targetPath, log);
+    if (resolved.kind === 'no-sources')
+        return resolved;
+    if (resolved.kind === 'no-data') {
+        return isError(resolved.reason)
+            ? { kind: 'error', reason: resolved.reason, message: resolved.message }
+            : { kind: 'unmeasured', reason: resolved.reason, message: resolved.message };
+    }
+    const data = resolved.data;
+    const measured = data.instrumented;
+    // #1008: a heuristic estimate is shown, never persisted as coverage evidence.
+    const result = await api.analyze({
+        coverageData: data, threshold, includeFileDetails: true, measured,
+        ...(resolved.projectRoot ? { projectRoot: resolved.projectRoot } : {}),
+    });
+    if (!result.success || !result.value) {
+        return { kind: 'analysis-failed', message: result.error?.message || 'Coverage analysis failed' };
+    }
+    const report = result.value;
+    if (!measured) {
+        return { kind: 'estimate', data, summary: { ...report.summary }, message: estimateMessage() };
+    }
+    // #995 review NB5: a metric the report never collected is null — not 0 —
+    // and is left out of the threshold verdict (same rule as MCP).
+    const collected = metricsCollected(data);
+    const verdict = thresholdVerdict(report.summary, threshold, collected);
+    return {
+        kind: 'measured',
+        data,
+        collected,
+        verdict,
+        summary: {
+            ...report.summary,
+            branch: collected.branch ? report.summary.branch : null,
+            function: collected.function ? report.summary.function : null,
+            statement: collected.statement ? report.summary.statement : null,
+        },
+        // NB-A: the shortfall advice comes from the same verdict (shared with MCP).
+        recommendations: reconcileRecommendations(report.recommendations ?? [], verdict, threshold, collected),
+    };
+}
+/**
+ * Exit code: 0 meets (by more than 5%), 1 below / error, 2 within 5% above,
+ * 3 UNMEASURED (not in the report, 0 tests, test-only report, or estimate only).
+ */
+export function coverageExitCode(outcome, threshold) {
+    switch (outcome.kind) {
+        case 'measured': {
+            const { overall, meetsThreshold } = outcome.verdict;
+            if (!meetsThreshold)
+                return 1;
+            return overall < threshold + 5 ? 2 : 0;
+        }
+        case 'estimate':
+        case 'unmeasured':
+            return EXIT_UNMEASURED;
+        case 'no-sources':
+            return 0;
+        default:
+            return 1;
+    }
+}
+/** The `-F json` document for an outcome (same shape in every case). */
+export function coverageJson(outcome, threshold, target) {
+    const nulls = { line: null, branch: null, function: null, statement: null };
+    switch (outcome.kind) {
+        case 'measured':
+            return {
+                summary: outcome.summary,
+                meetsThreshold: outcome.verdict.meetsThreshold,
+                threshold,
+                recommendations: outcome.recommendations,
+                measured: true,
+                estimated: false,
+                coverageMethod: MEASURED_METHOD,
+                branchDataCollected: outcome.collected.branch,
+                functionDataCollected: outcome.collected.function,
+                statementDataCollected: outcome.collected.statement,
+                ...(outcome.data.unmeasuredFiles?.length ? { unmeasuredFiles: outcome.data.unmeasuredFiles } : {}),
+            };
+        case 'estimate':
+            return {
+                summary: outcome.summary,
+                meetsThreshold: null,
+                threshold,
+                measured: false,
+                estimated: true,
+                unmeasured: true,
+                coverageMethod: ESTIMATE_METHOD,
+                reason: 'no-coverage-report',
+                target,
+                warning: outcome.message,
+            };
+        case 'unmeasured':
+        case 'error':
+            return {
+                summary: nulls,
+                meetsThreshold: null,
+                threshold,
+                measured: false,
+                unmeasured: outcome.kind === 'unmeasured',
+                reason: outcome.reason,
+                target,
+                warning: outcome.message,
+            };
+        case 'analysis-failed':
+            return { summary: nulls, meetsThreshold: null, threshold, measured: false, target, error: outcome.message };
+        case 'no-sources':
+            return { summary: nulls, meetsThreshold: null, threshold, measured: false, target, warning: 'No source files found' };
+    }
+}
+//# sourceMappingURL=coverage-verdict.js.map

package/dist/cli/utils/file-discovery.js

@@ -8,6 +8,7 @@
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { join, extname } from 'path';
+import { isAqeManagedDir } from '../../shared/aqe-managed-dirs.js';
 // ============================================================================
 // Source File Extensions by Language
 // ============================================================================
@@ -77,6 +78,10 @@ export function walkSourceFiles(targetPath, options = {}) {
             if (entry.isDirectory()) {
                 if (SKIP_DIRS.has(entry.name))
                     continue;
+                // #999: AQE state/assets are not source (.agentic-qe anywhere; .claude
+                // at the root or next to a nested .agentic-qe)
+                if (isAqeManagedDir(dir, entry.name, depth === 0))
+                    continue;
                 walk(join(dir, entry.name), depth + 1);
             }
             else if (entry.isFile()) {

package/dist/coordination/deterministic-actions.js

@@ -10,6 +10,7 @@
  * for live metrics — keeping execution fully deterministic (SQL-only).
  */
 import { ok } from '../shared/types/index.js';
+import { MEASURED_COVERAGE_SESSION_SQL } from '../feedback/coverage-session-provenance.js';
 function tryGetDb() {
     try {
         // Dynamic import to avoid hard dependency — the module may not be initialised
@@ -45,8 +46,10 @@ const qualityGateCheck = {
                 try {
                     // Latest coverage from coverage_sessions
                     if (currentCoverage === null) {
-                        const row = db.prepare(`SELECT after_lines FROM coverage_sessions ORDER BY created_at DESC LIMIT 1`).get();
-                        currentCoverage = row?.after_lines ?? 0;
+                        // #1014: skip legacy estimate/unmeasured rows without provenance.
+                        const row = db.prepare(`SELECT after_lines FROM coverage_sessions WHERE ${MEASURED_COVERAGE_SESSION_SQL} ORDER BY created_at DESC LIMIT 1`).get();
+                        // #1027 N6: no measured session → unmeasured (null), never 0%.
+                        currentCoverage = typeof row?.after_lines === 'number' ? row.after_lines : null;
                     }
                     // Test pass rate from recent test_outcomes
                     if (currentTestsPassingRate === null) {
@@ -70,16 +73,17 @@ const qualityGateCheck = {
                 }
             }
         }
-        // Apply defaults for anything still null
-        currentCoverage = currentCoverage ?? 0;
+        // Apply defaults for anything still null — except coverage (#1027 N6):
+        // unmeasured coverage stays null and fails its check (no evidence ≠ 0%).
+        const coverageMeasured = currentCoverage !== null;
         currentTestsPassingRate = currentTestsPassingRate ?? 0;
         currentBugs = currentBugs ?? 0;
-        const coveragePassed = currentCoverage >= coverageMin;
+        const coveragePassed = currentCoverage !== null && currentCoverage >= coverageMin;
         const testsPassed = currentTestsPassingRate >= testsPassingMin;
         const bugsPassed = currentBugs <= maxBugs;
         const passed = coveragePassed && testsPassed && bugsPassed;
         // Score is a normalized 0-1 value
-        const coverageScore = Math.min(currentCoverage / coverageMin, 1);
+        const coverageScore = currentCoverage === null ? 0 : Math.min(currentCoverage / coverageMin, 1);
         const testsScore = Math.min(currentTestsPassingRate / testsPassingMin, 1);
         const bugsScore = maxBugs > 0 ? Math.max(0, 1 - currentBugs / maxBugs) : (currentBugs === 0 ? 1 : 0);
         const score = (coverageScore + testsScore + bugsScore) / 3;
@@ -88,7 +92,10 @@ const qualityGateCheck = {
             score: Math.round(score * 100) / 100,
             source: typeof input.currentCoverage === 'number' ? 'input' : 'database',
             details: {
-                coverage: { current: currentCoverage, threshold: coverageMin, passed: coveragePassed },
+                coverage: {
+                    current: currentCoverage, threshold: coverageMin, passed: coveragePassed,
+                    ...(coverageMeasured ? {} : { unmeasured: true }),
+                },
                 testsPassing: { current: currentTestsPassingRate, threshold: testsPassingMin, passed: testsPassed },
                 bugs: { current: currentBugs, threshold: maxBugs, passed: bugsPassed },
             },
@@ -112,25 +119,29 @@ const coverageThresholdCheck = {
             const db = tryGetDb();
             if (db) {
                 try {
-                    const row = db.prepare(`SELECT after_lines FROM coverage_sessions ORDER BY created_at DESC LIMIT 1`).get();
-                    currentCoverage = row?.after_lines ?? 0;
+                    // #1014: skip legacy estimate/unmeasured rows without provenance.
+                    const row = db.prepare(`SELECT after_lines FROM coverage_sessions WHERE ${MEASURED_COVERAGE_SESSION_SQL} ORDER BY created_at DESC LIMIT 1`).get();
+                    // #1027 N6: no measured session → unmeasured (null), never 0%.
+                    currentCoverage = typeof row?.after_lines === 'number' ? row.after_lines : null;
                 }
                 catch {
-                    currentCoverage = 0;
+                    currentCoverage = null;
                 }
             }
             else {
-                currentCoverage = 0;
+                currentCoverage = null;
             }
         }
-        const passed = currentCoverage >= minCoverage;
-        const gap = passed ? 0 : Math.round((minCoverage - currentCoverage) * 100) / 100;
+        // Unmeasured coverage fails the check (no evidence), with no fake gap.
+        const passed = currentCoverage !== null && currentCoverage >= minCoverage;
+        const gap = currentCoverage === null ? null : passed ? 0 : Math.round((minCoverage - currentCoverage) * 100) / 100;
         return ok({
             currentCoverage,
             passed,
             gap,
             minCoverage,
             source,
+            ...(currentCoverage === null ? { unmeasured: true } : {}),
         });
     },
 };

package/dist/coordination/handlers/code-intelligence-handlers.d.ts

@@ -5,5 +5,13 @@
  * Covers: index-code, predict-defects
  */
 import type { TaskHandlerContext } from './handler-types';
+/** Project metric summary returned by the MCP index-code handler (#999). */
+export interface IndexProjectMetricsSummary {
+    root: string;
+    loc: number;
+    locByLanguage: Record<string, number>;
+    tests: number;
+    toolsUsed: string[];
+}
 export declare function registerCodeIntelligenceHandlers(ctx: TaskHandlerContext): void;
 //# sourceMappingURL=code-intelligence-handlers.d.ts.map

package/dist/coordination/handlers/code-intelligence-handlers.js

@@ -9,6 +9,39 @@ import * as path from 'path';
 import { ok, err } from '../../shared/types/index.js';
 import { toError } from '../../shared/error-utils.js';
 import { discoverSourceFiles } from './handler-utils.js';
+import { resolveProjectRootFromPaths } from '../../domains/code-intelligence/project-root-resolver.js';
+import { createLogger } from '../../logging/logger-factory.js';
+const logger = createLogger('CodeIntelligenceHandlers');
+async function collectProjectMetricsForTarget(ctx, targetPath, indexedFiles) {
+    if (!ctx.getCodeIntelligenceCoordinator)
+        return undefined;
+    const root = resolveProjectRootFromPaths(indexedFiles, { target: path.resolve(targetPath) });
+    if (!root) {
+        logger.debug('Skipping project metrics: no project root resolved (filesystem root or no paths)');
+        return undefined;
+    }
+    try {
+        const coordinator = await ctx.getCodeIntelligenceCoordinator();
+        if (!coordinator)
+            return undefined;
+        const metrics = await coordinator.collectProjectMetrics(root);
+        if (!metrics.success) {
+            logger.debug(`Project metrics unavailable: ${metrics.error.message}`);
+            return undefined;
+        }
+        return {
+            root,
+            loc: metrics.value.loc.total,
+            locByLanguage: metrics.value.loc.byLanguage,
+            tests: metrics.value.tests.total,
+            toolsUsed: metrics.value.toolsUsed,
+        };
+    }
+    catch (error) {
+        logger.debug(`Project metrics unavailable: ${toError(error).message}`);
+        return undefined;
+    }
+}
 export function registerCodeIntelligenceHandlers(ctx) {
     // Register code indexing handler - REAL IMPLEMENTATION
     ctx.registerHandler('index-code', async (task) => {
@@ -45,6 +78,11 @@ export function registerCodeIntelligenceHandlers(ctx) {
                 return result;
             }
             const indexResult = result.value;
+            // #999 MCP-CLI parity: `aqe code index` runs the coordinator's project
+            // metric step (LOC, tests, tools); run the same step here, rooted at the
+            // caller's target the way #997 resolves it. Best-effort: indexing has
+            // already succeeded, so a metric failure only omits projectMetrics.
+            const projectMetrics = await collectProjectMetricsForTarget(ctx, targetPath, filesToIndex);
             // Detect languages from files
             const detectedLanguages = new Set();
             const extToLang = {
@@ -78,6 +116,7 @@ export function registerCodeIntelligenceHandlers(ctx) {
                 duration: indexResult.duration,
                 errors: indexResult.errors,
                 warnings: indexResult.warnings,
+                ...(projectMetrics ? { projectMetrics } : {}),
             });
         }
         catch (error) {

package/dist/coordination/handlers/coverage-handlers.js

@@ -8,7 +8,9 @@ import { ok, err } from '../../shared/types/index.js';
 import { toError } from '../../shared/error-utils.js';
 import { buildEstimatedCoverage, collectRustCoverage, findCargoRoot, isCoverageExecDisabled, isRustProject, } from './coverage-collection.js';
 import { describeNoData, evaluateCoverageForTarget, isUnmeasured, resolveExistingCoverage, scopeCoverageToTarget, reconcileRecommendations, thresholdVerdict, } from './coverage-target.js';
-import { describeRunFailure, runJsCoverage } from './coverage-runner.js';
+import { randomUUID } from 'crypto';
+import { describeRunFailure, runJsCoverage, testRunStatus } from './coverage-runner.js';
+import { collectedMetrics } from '../../domains/coverage-analysis/collected-metrics.js';
 /**
  * How long the project's test runner may take before its process tree is
  * killed. `AQE_COVERAGE_TIMEOUT_MS` overrides the 120s default.
@@ -23,11 +25,15 @@ function recomputeSummary(files) {
     const pct = (covered, total) => (total > 0 ? Math.round((covered / total) * 100) : 0);
     const totalLines = sum(f => f.lines.total);
     const coveredLines = sum(f => f.lines.covered);
+    // #1012: statements are statements (lcov carries its line figures there).
+    const totalStatements = sum(f => f.statements.total);
     return {
         line: pct(coveredLines, totalLines),
         branch: pct(sum(f => f.branches.covered), sum(f => f.branches.total)),
         function: pct(sum(f => f.functions.covered), sum(f => f.functions.total)),
-        statement: pct(coveredLines, totalLines),
+        statement: totalStatements > 0
+            ? pct(sum(f => f.statements.covered), totalStatements)
+            : pct(coveredLines, totalLines),
         files: files.length,
     };
 }
@@ -114,7 +120,19 @@ async function collectCoverage(targetPath) {
         const evaluation = run.data
             ? evaluateCoverageForTarget(run.data, projectRoot, target, { numTotalTests: run.numTotalTests })
             : { status: 'no-data', reason: 'no-tests-ran' };
-        return fromEvaluation(evaluation, run.exitedCleanly || run.data !== null, projectRoot);
+        const result = fromEvaluation(evaluation, run.exitedCleanly || run.data !== null, projectRoot);
+        if (result.collected) {
+            // #1027 N4/NB2: a run with failing tests still measured coverage; the
+            // failure is decided from the runner's counts, not its exit code.
+            result.runStatus = testRunStatus(run);
+            // #1027 NB1: the run's own testsPassing is recorded with its coverage.
+            if (typeof run.numPassedTests === 'number' && typeof run.numFailedTests === 'number') {
+                result.testRun = {
+                    runId: randomUUID(), passed: run.numPassedTests, failed: run.numFailedTests, skipped: run.numPendingTests ?? 0,
+                };
+            }
+        }
+        return result;
     }
     // No report at all: say exactly what happened to the run (not installed,
     // timed out, crashed with stderr), then fall back to a labelled estimate.
@@ -167,7 +185,7 @@ export function registerCoverageHandlers(ctx) {
             const analyzer = ctx.getCoverageAnalyzer();
             const targetPath = payload.target || process.cwd();
             const threshold = payload.threshold || 80;
-            const { collected, ranTests, noData, projectRoot, notes } = await collectCoverage(targetPath);
+            const { collected, ranTests, noData, projectRoot, notes, runStatus, testRun } = await collectCoverage(targetPath);
             // #995 review N5: say so plainly instead of "no coverage data found".
             if (noData === 'target-missing') {
                 return err(new Error(describeNoData('target-missing', targetPath, null)));
@@ -200,6 +218,10 @@ export function registerCoverageHandlers(ctx) {
                 threshold,
                 includeFileDetails: payload.detectGaps,
                 measured: !provenance.estimated,
+                // #1027 N7: per-file records use absolute keys; N4: failing-suite coverage is labelled.
+                ...(projectRoot ? { projectRoot } : {}),
+                ...(runStatus && !provenance.estimated ? { runStatus } : {}),
+                ...(testRun && !provenance.estimated ? { testRun } : {}),
             });
             if (!analysisResult.success) {
                 return analysisResult;
@@ -240,7 +262,11 @@ export function registerCoverageHandlers(ctx) {
             // than send a developer to fix a number that doesn't exist.
             // #995 NB5/NB-A: the verdict and the shortfall advice come from the same
             // collected-metrics computation (shared with the CLI), so they can't disagree.
-            const metricsCollected = { branch: provenance.branchDataCollected, function: provenance.functionDataCollected };
+            // #1027 N7: lcov / Cobertura carry no statement data — n/a, out of the verdict.
+            const statementCollected = provenance.estimated || collectedMetrics(coverageData.files).statement;
+            const metricsCollected = {
+                branch: provenance.branchDataCollected, function: provenance.functionDataCollected, statement: statementCollected,
+            };
             const verdict = thresholdVerdict(report.summary, threshold, metricsCollected);
             const recommendations = reconcileRecommendations(report.recommendations, verdict, threshold, metricsCollected);
             return ok({
@@ -249,7 +275,7 @@ export function registerCoverageHandlers(ctx) {
                 // 100% — when no branch data was collected.
                 branchCoverage: provenance.branchDataCollected ? round(report.summary.branch) : null,
                 functionCoverage: provenance.functionDataCollected ? round(report.summary.function) : null,
-                statementCoverage: round(report.summary.statement),
+                statementCoverage: statementCollected ? round(report.summary.statement) : null,
                 totalFiles: report.summary.files,
                 coverageByFile: coverageData.files.map(f => ({
                     file: f.path,
@@ -269,6 +295,8 @@ export function registerCoverageHandlers(ctx) {
                 coverageMethod: provenance.method,
                 branchDataCollected: provenance.branchDataCollected,
                 functionDataCollected: provenance.functionDataCollected,
+                statementDataCollected: statementCollected,
+                ...(runStatus && !provenance.estimated ? { runStatus } : {}),
                 ...(warnings.length > 0 ? { warning: warnings.join(' ') } : {}),
             });
         }

package/dist/coordination/handlers/coverage-runner.d.ts

@@ -55,9 +55,25 @@ export interface JsCoverageRun {
      * not be read — "unknown", which callers must not treat as 0.
      */
     numTotalTests: number | null;
+    /**
+     * Per-outcome counts from the runner's JSON result (#1027 NB1/NB2), null
+     * when unknown. A failing suite is decided from these, not the exit code:
+     * vitest also exits non-zero for a coverage-threshold failure.
+     */
+    numPassedTests?: number | null;
+    numFailedTests?: number | null;
+    numPendingTests?: number | null;
+    numFailedTestSuites?: number | null;
     /** The runner's first error line plus the last ~2 KB of its stderr, for diagnosing a crash. */
     stderrTail: string;
 }
+/**
+ * Outcome of a coverage run's tests (#1027 NB2): 'failed' when the runner's
+ * own result reports a failed test or test suite, 'passed' when it reports
+ * none — whatever the exit code (a coverage-threshold failure exits 1 with
+ * every test passing). Without counts (nyc), the exit code decides.
+ */
+export declare function testRunStatus(run: JsCoverageRun): 'passed' | 'failed';
 /**
  * Summarise a runner's stderr for a caller: the FIRST error-looking line (or
  * the first ~512 bytes) plus the last ~2 KB (#995 review NB-C). A tail alone
@@ -70,6 +86,12 @@ export declare function summarizeStderr(head: string, tail: string, totalBytes:
  * project root (hoisted monorepo installs live above the package).
  */
 export declare function findPackageBin(projectRoot: string, pkg: string, binName?: string, maxDepth?: number): string | null;
+/**
+ * Every `node_modules/.bin` from the project up to the workspace root,
+ * nearest first. Runners that shell out to sibling tools (nyc → mocha) need
+ * the hoisted ones too (#1012).
+ */
+export declare function runnerBinDirs(projectRoot: string): string[];
 /**
  * Pick the runner and its argv. No shell is involved: `command` is the Node
  * binary and `args[0]` the runner's JS entry, so paths are passed verbatim.