agentic-qe 3.15.16 → 3.15.18

package/dist/shared/pytest-junit-report.d.ts

@@ -0,0 +1,93 @@
+/**
+ * #1248: running pytest and reading its JUnit XML report.
+ *
+ * pytest is started as `<python> -m pytest <files> --junitxml=<file>`, with
+ * the report in a temporary directory owned by the run, so the result never
+ * depends on the console summary. The interpreter is `AQE_PYTHON` when set,
+ * otherwise `python` when it is on PATH, otherwise `python3`.
+ *
+ * The report is read with a small parser for the XML pytest writes (one or
+ * more `<testsuite>` elements holding `<testcase>` elements, each with an
+ * optional `<failure>`, `<error>` or `<skipped>` child). Counts come from the
+ * test cases themselves, so they always match the per-test list. An expected
+ * failure (xfail) is reported by pytest as skipped and counted as skipped.
+ *
+ * A run is only a result when pytest finished its tests: exit code 5 (no
+ * tests collected), 2 (interrupted, for example by a collection error),
+ * 3 (internal error) and 4 (usage error), or a missing report (pytest not
+ * installed for the interpreter), are runner errors, never a pass.
+ */
+import { TestRunnerExecutionError } from './test-runner-verdict.js';
+import { Result } from './types';
+/** True for a Python test file, which only pytest can run. */
+export declare function isPythonTestFile(file: string): boolean;
+/** The Python interpreter that runs pytest. */
+export declare function resolvePythonCommand(env?: NodeJS.ProcessEnv): string;
+/** Environment for a pytest process: no ANSI colour in its output or report. */
+export declare const PYTEST_ENV: Readonly<Record<string, string>>;
+/** Command and arguments that run `targets` (paths or node ids) with pytest. */
+export declare function pytestCommand(targets: readonly string[], reportPath: string, env?: NodeJS.ProcessEnv): {
+    command: string;
+    args: string[];
+};
+/** A per-run JUnit report location, read back after pytest exits. */
+export interface PytestJunitReport {
+    /** Absolute path pytest writes the report to. */
+    readonly path: string;
+    /** Arguments that point pytest at the report (already in pytestCommand). */
+    readonly args: readonly string[];
+    /** The report text; undefined when pytest wrote none. Malformed reports throw. */
+    read(stdout?: string): string | undefined;
+    /** Remove the temporary report directory. Safe to call more than once. */
+    cleanup(): void;
+}
+export declare function createPytestJunitReport(): PytestJunitReport;
+export type PytestCaseStatus = 'passed' | 'failed' | 'error' | 'skipped';
+/** One `<testcase>` of a pytest JUnit report. */
+export interface PytestJunitCase {
+    classname: string;
+    name: string;
+    status: PytestCaseStatus;
+    /** Duration in milliseconds, when reported. */
+    duration?: number;
+    /** The failure, error or skip message attribute. */
+    message?: string;
+    /** The failure or error body (traceback). */
+    details?: string;
+}
+/** The test cases of a pytest JUnit XML report, in report order. */
+export declare function parsePytestJunitXml(xml: string): PytestJunitCase[];
+/**
+ * The run file a test case belongs to, and its name inside that file
+ * (`TestClass::test_name[param]`, the node id without the file). The class
+ * name is the module's dotted path relative to pytest's rootdir followed by
+ * any classes, so the file is the one whose path ends with the longest
+ * leading part of it.
+ */
+export declare function locatePytestCase(testCase: Pick<PytestJunitCase, 'classname' | 'name'>, files: readonly string[]): {
+    file: string;
+    name: string;
+};
+/** One test of a finished pytest run. */
+export interface PytestTest {
+    name: string;
+    file: string;
+    status: 'passed' | 'failed' | 'skipped';
+    duration?: number;
+    /** Failure or error text for a failed test. */
+    failureMessage?: string;
+}
+export interface PytestRun {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    tests: PytestTest[];
+}
+/**
+ * The result of a finished pytest run, or the runner error that kept it from
+ * being one. `report` is the JUnit XML text, undefined when pytest wrote none.
+ * A test case that errored (in a fixture, say) counts as a failed test.
+ */
+export declare function pytestRunFromReport(report: string | undefined, files: readonly string[], exitCode: number | null, output: string, python?: string): Result<PytestRun, TestRunnerExecutionError>;
+//# sourceMappingURL=pytest-junit-report.d.ts.map

package/dist/shared/pytest-junit-report.js

@@ -0,0 +1,241 @@
+/**
+ * #1248: running pytest and reading its JUnit XML report.
+ *
+ * pytest is started as `<python> -m pytest <files> --junitxml=<file>`, with
+ * the report in a temporary directory owned by the run, so the result never
+ * depends on the console summary. The interpreter is `AQE_PYTHON` when set,
+ * otherwise `python` when it is on PATH, otherwise `python3`.
+ *
+ * The report is read with a small parser for the XML pytest writes (one or
+ * more `<testsuite>` elements holding `<testcase>` elements, each with an
+ * optional `<failure>`, `<error>` or `<skipped>` child). Counts come from the
+ * test cases themselves, so they always match the per-test list. An expected
+ * failure (xfail) is reported by pytest as skipped and counted as skipped.
+ *
+ * A run is only a result when pytest finished its tests: exit code 5 (no
+ * tests collected), 2 (interrupted, for example by a collection error),
+ * 3 (internal error) and 4 (usage error), or a missing report (pytest not
+ * installed for the interpreter), are runner errors, never a pass.
+ */
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import * as path from 'node:path';
+import { capDiagnostics, getTestRunnerExecutionError, TestRunnerExecutionError } from './test-runner-verdict.js';
+import { ok, err } from './types/index.js';
+/** True for a Python test file, which only pytest can run. */
+export function isPythonTestFile(file) {
+    return /\.py$/i.test(file);
+}
+function onPath(command, env) {
+    const names = process.platform === 'win32' ? [`${command}.exe`, `${command}.cmd`, command] : [command];
+    for (const dir of (env.PATH ?? env.Path ?? '').split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            try {
+                if (statSync(path.join(dir, name)).isFile())
+                    return true;
+            }
+            catch {
+                // Not in this directory.
+            }
+        }
+    }
+    return false;
+}
+/** The Python interpreter that runs pytest. */
+export function resolvePythonCommand(env = process.env) {
+    const configured = env.AQE_PYTHON?.trim();
+    if (configured)
+        return configured;
+    if (onPath('python', env))
+        return 'python';
+    return onPath('python3', env) ? 'python3' : 'python';
+}
+/** Environment for a pytest process: no ANSI colour in its output or report. */
+export const PYTEST_ENV = { PY_COLORS: '0' };
+/** Command and arguments that run `targets` (paths or node ids) with pytest. */
+export function pytestCommand(targets, reportPath, env = process.env) {
+    return {
+        command: resolvePythonCommand(env),
+        // No colour: runners are started with FORCE_COLOR set, which pytest reads
+        // as "force colour" (even in its report). PY_COLORS=0 (PYTEST_ENV) wins
+        // over FORCE_COLOR; --color=no covers the console output.
+        args: ['-m', 'pytest', ...targets, `--junitxml=${reportPath}`, '--color=no'],
+    };
+}
+export function createPytestJunitReport() {
+    const dir = mkdtempSync(path.join(tmpdir(), 'aqe-pytest-report-'));
+    const reportPath = path.join(dir, 'junit.xml');
+    let cleaned = false;
+    return {
+        path: reportPath,
+        args: [],
+        read: () => {
+            if (!existsSync(reportPath))
+                return undefined;
+            const text = readFileSync(reportPath, 'utf-8');
+            if (!/<testsuite\b/.test(text))
+                throw new TestRunnerExecutionError('The current pytest JUnit report is malformed.');
+            return text;
+        },
+        cleanup: () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // Best effort: a leftover temp dir is not worth failing a test run over.
+            }
+        },
+    };
+}
+function unescapeXml(text) {
+    return text.replace(/&(#x[0-9a-f]+|#\d+|lt|gt|amp|quot|apos);/gi, (_, entity) => {
+        const lower = entity.toLowerCase();
+        if (lower === 'lt')
+            return '<';
+        if (lower === 'gt')
+            return '>';
+        if (lower === 'amp')
+            return '&';
+        if (lower === 'quot')
+            return '"';
+        if (lower === 'apos')
+            return '\'';
+        const code = lower.startsWith('#x') ? parseInt(lower.slice(2), 16) : parseInt(lower.slice(1), 10);
+        return Number.isFinite(code) && code >= 0 && code <= 0x10ffff ? String.fromCodePoint(code) : '';
+    });
+}
+function attributes(text) {
+    const attrs = {};
+    for (const match of text.matchAll(/([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+        attrs[match[1]] = unescapeXml(match[2] ?? match[3] ?? '');
+    }
+    return attrs;
+}
+/** The test cases of a pytest JUnit XML report, in report order. */
+export function parsePytestJunitXml(xml) {
+    if (!/<testsuite\b/.test(xml))
+        throw new Error('Not a JUnit XML report: no <testsuite> element.');
+    const cases = [];
+    const testcase = /<testcase\b((?:[^>"']|"[^"]*"|'[^']*')*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
+    for (const match of xml.matchAll(testcase)) {
+        const attrs = attributes(match[1]);
+        const body = match[2] ?? '';
+        // An error (setup/teardown) outranks a failure in the same test case.
+        const child = (tag) => body.match(new RegExp(`<${tag}\\b((?:[^>"']|"[^"]*"|'[^']*')*?)(?:\\/>|>([\\s\\S]*?)<\\/${tag}>)`));
+        const error = child('error');
+        const failure = child('failure');
+        const skipped = child('skipped');
+        const outcome = error ?? failure ?? skipped;
+        const status = error ? 'error' : failure ? 'failed' : skipped ? 'skipped' : 'passed';
+        const seconds = Number.parseFloat(attrs.time ?? '');
+        const message = outcome ? attributes(outcome[1]).message : undefined;
+        const details = outcome?.[2] !== undefined ? unescapeXml(outcome[2]).trim() : undefined;
+        cases.push({
+            classname: attrs.classname ?? '',
+            name: attrs.name ?? '',
+            status,
+            ...(Number.isFinite(seconds) ? { duration: Math.round(seconds * 1000) } : {}),
+            ...(message ? { message } : {}),
+            ...(details ? { details } : {}),
+        });
+    }
+    return cases;
+}
+/** A collection error is reported as an error case with no class name. */
+function isCollectionError(testCase) {
+    return testCase.status === 'error' && (testCase.classname === '' || testCase.message === 'collection failure');
+}
+function pathSegments(file) {
+    return file.replace(/\.py$/i, '').split(/[\\/]+/).filter(Boolean);
+}
+/**
+ * The run file a test case belongs to, and its name inside that file
+ * (`TestClass::test_name[param]`, the node id without the file). The class
+ * name is the module's dotted path relative to pytest's rootdir followed by
+ * any classes, so the file is the one whose path ends with the longest
+ * leading part of it.
+ */
+export function locatePytestCase(testCase, files) {
+    const dotted = testCase.classname ? testCase.classname.split('.') : [];
+    let best;
+    for (const file of files) {
+        const segments = pathSegments(file);
+        for (let length = Math.min(dotted.length, segments.length); length > 0; length--) {
+            const tail = segments.slice(segments.length - length);
+            if (tail.every((segment, index) => segment === dotted[index])) {
+                if (!best || length > best.matched)
+                    best = { file, matched: length };
+                break;
+            }
+        }
+    }
+    if (!best) {
+        return {
+            file: files.length === 1 ? files[0] : files.join(', '),
+            name: testCase.classname ? `${testCase.classname}::${testCase.name}` : testCase.name,
+        };
+    }
+    return { file: best.file, name: [...dotted.slice(best.matched), testCase.name].join('::') };
+}
+const PYTEST_EXIT_REASONS = {
+    2: 'was interrupted (for example by a collection error)',
+    3: 'hit an internal error',
+    4: 'rejected its command line',
+    5: 'collected no tests',
+};
+/**
+ * The result of a finished pytest run, or the runner error that kept it from
+ * being one. `report` is the JUnit XML text, undefined when pytest wrote none.
+ * A test case that errored (in a fixture, say) counts as a failed test.
+ */
+export function pytestRunFromReport(report, files, exitCode, output, python = resolvePythonCommand()) {
+    const label = files.join(', ');
+    if (report === undefined) {
+        const notInstalled = /No module named pytest/.test(output);
+        return err(new TestRunnerExecutionError(`pytest wrote no JUnit report for ${label} (exit code ${exitCode ?? 'unknown'}).` +
+            (notInstalled
+                ? ` pytest is not installed for '${python}'; install it, or set AQE_PYTHON to an interpreter that has it.`
+                : ` Check that '${python} -m pytest' runs; set AQE_PYTHON to choose the interpreter.`) +
+            (output.trim() ? `\n${capDiagnostics(output.trim())}` : '')));
+    }
+    let cases;
+    try {
+        cases = parsePytestJunitXml(report);
+    }
+    catch (error) {
+        return err(new TestRunnerExecutionError(`Could not read the pytest JUnit report for ${label}: ${error instanceof Error ? error.message : String(error)}`));
+    }
+    const collectionErrors = cases.filter(isCollectionError);
+    const exitReason = exitCode !== null ? PYTEST_EXIT_REASONS[exitCode] : undefined;
+    if (exitReason || collectionErrors.length > 0) {
+        const reasons = collectionErrors.map(c => `${c.name}: ${c.details ?? c.message ?? 'collection failure'}`);
+        return err(new TestRunnerExecutionError(`pytest ${exitReason ?? 'reported a collection error'} for ${label} (exit code ${exitCode ?? 'unknown'}).` +
+            `\n${capDiagnostics([...reasons, output.trim()].filter(Boolean).join('\n'))}`));
+    }
+    const tests = cases.map(testCase => {
+        const { file, name } = locatePytestCase(testCase, files);
+        const failed = testCase.status === 'failed' || testCase.status === 'error';
+        const failureMessage = failed
+            ? [testCase.message, testCase.details].filter(Boolean).join('\n') || 'Test failed'
+            : undefined;
+        return {
+            name, file,
+            status: failed ? 'failed' : testCase.status === 'skipped' ? 'skipped' : 'passed',
+            ...(testCase.duration !== undefined ? { duration: testCase.duration } : {}),
+            ...(failureMessage ? { failureMessage } : {}),
+        };
+    });
+    const passed = tests.filter(t => t.status === 'passed').length;
+    const failed = tests.filter(t => t.status === 'failed').length;
+    const skipped = tests.filter(t => t.status === 'skipped').length;
+    const executionError = getTestRunnerExecutionError('pytest', label, exitCode, { passed, failed, skipped }, output);
+    if (executionError)
+        return err(executionError);
+    return ok({ total: tests.length, passed, failed, skipped, tests });
+}
+//# sourceMappingURL=pytest-junit-report.js.map

package/dist/shared/safe-db.d.ts

@@ -16,7 +16,7 @@ export interface SafeDbOptions {
     fileMustExist?: boolean;
     /** Busy timeout in ms (default: 5000) */
     busyTimeout?: number;
-    /** Enable WAL mode (default: true for writable, false for readonly) */
+    /** Enable WAL mode (default: true for writable; always ignored for readonly) */
     walMode?: boolean;
     /**
      * M3.2: on a malformed/corrupt existing DB, auto-restore the newest verified

package/dist/shared/safe-db.js

@@ -12,6 +12,7 @@ import Database from 'better-sqlite3';
 import { basename } from 'node:path';
 import { attemptAutoRestore } from './db-recovery.js';
 import { withNativeModuleRemedy } from './native-module-errors.js';
+import { setJournalModeWithRetry } from './sqlite-journal-mode.js';
 /**
  * Open a SQLite database with safe defaults that prevent corruption.
  *
@@ -95,8 +96,11 @@ export function openDatabase(dbPath, opts) {
                 // 2026-07-07), so continuing to write in WAL would trade a loud outage for
                 // silent corruption. Availability is not worth that; the message below
                 // carries the exact command that finds the real holder.
+                //
+                // Concurrent openers racing the same one-time switch (#1164) are retried
+                // within busyTimeout first; only contention that outlasts it fails closed.
                 try {
-                    db.pragma(`journal_mode = ${desired}`);
+                    setJournalModeWithRetry(db, desired, busyTimeout);
                 }
                 catch (err) {
                     const code = err?.code;
@@ -135,11 +139,22 @@ export function openDatabase(dbPath, opts) {
             }
         }
     }
-    else if (walMode) {
+    else if (walMode && !readonly) {
         // WAL mode for writable connections prevents corruption from concurrent
-        // writers. Readonly connections inherit WAL from the DB file but we set it
-        // explicitly to be safe in case the DB was created without WAL.
-        db.pragma('journal_mode = WAL');
+        // writers. Readonly connections inherit the file's journal mode and must
+        // not switch it: that is a write and fails with SQLITE_READONLY on a
+        // rollback-journal file (#1320), so `walMode` is ignored for readonly opens.
+        //
+        // #1164: switching a rollback-journal file to WAL upgrades a read lock to a
+        // write lock, and SQLite returns SQLITE_BUSY for that at once instead of
+        // waiting on busy_timeout. Concurrent first opens retry within busyTimeout.
+        try {
+            setJournalModeWithRetry(db, 'WAL', busyTimeout);
+        }
+        catch (err) {
+            db.close();
+            throw err;
+        }
     }
     return db;
 }

package/dist/shared/sqlite-journal-mode.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Switch a SQLite connection's journal mode, retrying lock contention (#1164).
+ *
+ * `PRAGMA journal_mode = WAL` on a rollback-journal database reads page 1
+ * under a SHARED lock and then upgrades to a write lock to rewrite the header.
+ * SQLite does not run the busy handler for that upgrade (an upgrade from a
+ * held read lock could deadlock), so when several processes open the same
+ * non-WAL database at once, all but one can get SQLITE_BUSY in well under a
+ * millisecond even with busy_timeout set. Leaving WAL needs an EXCLUSIVE lock
+ * and fails the same way.
+ *
+ * This retries the switch with a short, growing sleep until `budgetMs` has
+ * passed, then throws the last error. Once another process has switched the
+ * file, the retry finds the mode already set, which needs no write lock.
+ *
+ * Dependency-free (no better-sqlite3 import) so optional-dependency callers can
+ * use it with a connection they loaded themselves.
+ */
+/** The part of a better-sqlite3 connection this needs. */
+export interface JournalModeConnection {
+    pragma(source: string, options?: {
+        simple?: boolean;
+    }): unknown;
+}
+export interface JournalModeRetryOptions {
+    /** Synchronous sleep, injectable for tests. */
+    sleep?: (ms: number) => void;
+    /** Clock in ms, injectable for tests. */
+    now?: () => number;
+}
+/** True for SQLITE_BUSY / SQLITE_LOCKED, including extended codes such as SQLITE_BUSY_RECOVERY. */
+export declare function isJournalLockContention(err: unknown): boolean;
+/**
+ * Set `journal_mode` to `mode`, retrying SQLITE_BUSY / SQLITE_LOCKED for up to
+ * `budgetMs`. Returns the mode SQLite reports afterwards, lower-cased. Any
+ * other error is thrown at once.
+ */
+export declare function setJournalModeWithRetry(db: JournalModeConnection, mode: string, budgetMs: number, options?: JournalModeRetryOptions): string;
+//# sourceMappingURL=sqlite-journal-mode.d.ts.map

package/dist/shared/sqlite-journal-mode.js

@@ -0,0 +1,53 @@
+/**
+ * Switch a SQLite connection's journal mode, retrying lock contention (#1164).
+ *
+ * `PRAGMA journal_mode = WAL` on a rollback-journal database reads page 1
+ * under a SHARED lock and then upgrades to a write lock to rewrite the header.
+ * SQLite does not run the busy handler for that upgrade (an upgrade from a
+ * held read lock could deadlock), so when several processes open the same
+ * non-WAL database at once, all but one can get SQLITE_BUSY in well under a
+ * millisecond even with busy_timeout set. Leaving WAL needs an EXCLUSIVE lock
+ * and fails the same way.
+ *
+ * This retries the switch with a short, growing sleep until `budgetMs` has
+ * passed, then throws the last error. Once another process has switched the
+ * file, the retry finds the mode already set, which needs no write lock.
+ *
+ * Dependency-free (no better-sqlite3 import) so optional-dependency callers can
+ * use it with a connection they loaded themselves.
+ */
+const FIRST_BACKOFF_MS = 2;
+const MAX_BACKOFF_MS = 50;
+/** True for SQLITE_BUSY / SQLITE_LOCKED, including extended codes such as SQLITE_BUSY_RECOVERY. */
+export function isJournalLockContention(err) {
+    const code = err?.code;
+    return typeof code === 'string' && (code.startsWith('SQLITE_BUSY') || code.startsWith('SQLITE_LOCKED'));
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Set `journal_mode` to `mode`, retrying SQLITE_BUSY / SQLITE_LOCKED for up to
+ * `budgetMs`. Returns the mode SQLite reports afterwards, lower-cased. Any
+ * other error is thrown at once.
+ */
+export function setJournalModeWithRetry(db, mode, budgetMs, options = {}) {
+    const sleep = options.sleep ?? sleepSync;
+    const now = options.now ?? Date.now;
+    const deadline = now() + Math.max(0, budgetMs);
+    let backoff = FIRST_BACKOFF_MS;
+    for (;;) {
+        try {
+            return String(db.pragma(`journal_mode = ${mode}`, { simple: true }) ?? '').toLowerCase();
+        }
+        catch (err) {
+            const remaining = deadline - now();
+            if (!isJournalLockContention(err) || remaining <= 0)
+                throw err;
+            // Jitter so processes that collided do not retry in lockstep.
+            sleep(Math.min(remaining, backoff / 2 + Math.random() * backoff / 2));
+            backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+        }
+    }
+}
+//# sourceMappingURL=sqlite-journal-mode.js.map

package/dist/shared/test-runner-project.d.ts

@@ -14,6 +14,26 @@
  * A run from the current working directory is kept whenever that directory is
  * already inside the file's runner project (a single-project repository, or a
  * server started inside the package), so those runs behave as before.
+ *
+ * #1272: a package with its own config runs from that package, even when the
+ * root config also lists it in `test.projects` (or a `vitest.workspace.*`).
+ * Settings that only the root config adds to that project (its setup files,
+ * aliases or environment) are then not applied; the package's own config is
+ * what runs. A package without its own config still runs from the root.
+ *
+ * #1272: `vite.config.*` counts only when its text contains `test:`. The
+ * config is code, and reading what it exports would mean running it, so a
+ * `test` block built some other way (spread from another module, say) is not
+ * seen and a `test:` that only appears in a comment is. Name the runner config
+ * `vitest.config.*` for an exact match.
+ *
+ * #1248: a Python test file belongs to the nearest directory with pytest
+ * configuration instead (`pytest.ini`, `pyproject.toml` with
+ * `[tool.pytest.ini_options]`, `setup.cfg` with `[tool:pytest]`, `tox.ini`
+ * with `[pytest]`), and JavaScript files ignore that configuration. A
+ * `conftest.py` marks a pytest project for detection but is not a directory
+ * to run from: it is often in `tests/`, and pytest started there would not
+ * have the project root on `sys.path`.
  */
 import { Result } from './types';
 /**
@@ -34,8 +54,30 @@ export interface RunnerProjectGroup {
     cwd: string;
     files: string[];
 }
+/** A runner whose project configuration can be recognised from its files. */
+export type RunnerFramework = 'vitest' | 'jest';
 /** True when `dir` holds a Vitest or Jest configuration. */
 export declare function isRunnerProjectDir(dir: string): boolean;
+/**
+ * #1248: true when `dir` holds pytest configuration; with `conftest`, a
+ * `conftest.py` counts too (see the header note).
+ */
+export declare function isPytestProjectDir(dir: string, conftest?: boolean): boolean;
+/**
+ * #1248: true when `dir`, or a directory above it no higher than `boundary`,
+ * is configured for pytest (including a `conftest.py`).
+ */
+export declare function isPytestProject(dir: string, boundary?: string): boolean;
+/**
+ * #1272: the runner configured by the runner project that `dir` belongs to:
+ * the nearest directory at or above `dir`, no higher than `boundary`, with
+ * runner configuration. Jest config (`jest.config.*`, or a `jest` key in
+ * package.json) means jest; Vitest config (`vitest.config.*`,
+ * `vitest.workspace.*`, a `vite.config.*` with `test`, or a `vitest` key)
+ * means vitest. Undefined when no project is found or it configures both, so
+ * the caller keeps its own choice.
+ */
+export declare function runnerFrameworkFor(dir: string, boundary?: string): RunnerFramework | undefined;
 /**
  * The nearest directory at or above `file` with runner configuration, searching no
  * higher than `boundary`. Undefined when the file lies outside the boundary or
@@ -50,7 +92,8 @@ export declare function findRunnerProjectDir(file: string, boundary: string, cwd
 export declare function runnerCwdFor(file: string, options?: RunnerProjectOptions): string;
 /**
  * Group `files` by the directory each must run from, in first-seen order.
- * Files keep the spelling they were given.
+ * Files keep the spelling they were given. #1248: Python files never share a
+ * group with other files, since only pytest runs them.
  */
 export declare function groupByRunnerProject(files: readonly string[], options?: RunnerProjectOptions): RunnerProjectGroup[];
 /** Test files to run, and the directory to run them from when the caller named one. */
@@ -66,4 +109,11 @@ export interface TestRunTargets {
  * files are then read from it, and every path is returned absolute.
  */
 export declare function requireTestRunTargets(taskType: string, testFiles: unknown, projectRoot: unknown): Promise<Result<TestRunTargets, Error>>;
+/**
+ * An explicit `projectRoot` (MCP `test_execute_parallel`, CLI
+ * `aqe test execute --project-root`): a directory inside the project, checked
+ * by realpath so `..`, an outside absolute path or a symlink pointing out is
+ * refused. Returns the absolute directory.
+ */
+export declare function requireRunProjectRoot(taskType: string, projectRoot: unknown): Promise<Result<string, Error>>;
 //# sourceMappingURL=test-runner-project.d.ts.map