agentic-qe 3.15.16 → 3.15.17

package/dist/domains/test-execution/services/retry-handler.js

@@ -7,6 +7,7 @@ import { spawn } from 'node:child_process';
 import { createVitestJsonReport } from '../../../shared/vitest-json-report.js';
 import { jestExactPathPattern, nameFilterArg, runnerFilePath } from '../../../shared/test-runner-args.js';
 import { runnerCwdFor } from '../../../shared/test-runner-project.js';
+import { createPytestJunitReport, isPythonTestFile, parsePytestJunitXml, pytestCommand, PYTEST_ENV, } from '../../../shared/pytest-junit-report.js';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
 import { ok, err } from '../../../shared/types/index.js';
@@ -300,8 +301,8 @@ export class RetryHandlerService {
         // projectRoot, else a configured directory, else the file's runner
         // project. The file path stays relative to `cwd`.
         const runCwd = projectRoot ?? this.config.cwd ?? runnerCwdFor(testFile);
-        // Detect or use configured test runner
-        const runner = await this.detectTestRunner(runCwd);
+        // Detect or use configured test runner. #1248: a Python file is pytest's.
+        const runner = isPythonTestFile(testFile) ? 'pytest' : await this.detectTestRunner(runCwd);
         if (!runner) {
             throw new Error(`No test runner detected or configured. Install vitest, jest, or mocha, ` +
                 `or configure testRunner in RetryHandlerConfig. Cannot execute retry for: ${testFile}`);
@@ -309,7 +310,7 @@ export class RetryHandlerService {
         // Build command based on runner
         const { command, args, report } = this.buildTestCommand(runner, testFile, testName, cwd);
         // Execute the test
-        return this.spawnTestProcess(command, args, runCwd, report, runner === 'vitest' ? testFile : undefined);
+        return this.spawnTestProcess(command, args, runCwd, report, runner === 'vitest' ? testFile : undefined, runner === 'pytest' ? (code, reportText, output) => this.parsePytestRetry(code, reportText, output) : undefined);
     }
     /**
      * Detect which test runner is available in the project
@@ -415,6 +416,13 @@ export class RetryHandlerService {
                         mochaArgs.push(nameFilterArg('mocha', testName));
                     return { command: npx, args: mochaArgs };
                 }
+            case 'pytest':
+                // #1248: the failed test's node id is <file>::<name> (name from the run).
+                {
+                    const report = createPytestJunitReport();
+                    const file = runnerFilePath(testFile, cwd);
+                    return { ...pytestCommand([filterByName ? `${file}::${testName}` : file], report.path), report };
+                }
             default:
                 throw new Error(`Unsupported test runner: ${runner}`);
         }
@@ -422,7 +430,7 @@ export class RetryHandlerService {
     /**
      * Spawn a test process and parse the result
      */
-    spawnTestProcess(command, args, cwd, report, targetFile) {
+    spawnTestProcess(command, args, cwd, report, targetFile, parseReport) {
         return new Promise((resolve, reject) => {
             const timeout = this.config.testTimeout;
             let stdout = '';
@@ -439,7 +447,7 @@ export class RetryHandlerService {
             const proc = spawn(command, args, {
                 cwd,
                 detached: process.platform !== 'win32',
-                env: { ...process.env, FORCE_COLOR: '0', CI: 'true' },
+                env: { ...process.env, FORCE_COLOR: '0', CI: 'true', ...PYTEST_ENV },
             });
             const untrackExit = trackTestRunnerExit(proc);
             const timeoutHandle = setTimeout(() => {
@@ -470,6 +478,10 @@ export class RetryHandlerService {
                 // report to the --outputFile; read it back rather than trusting stdout).
                 try {
                     const reportText = report ? report.read(stdout) : stdout;
+                    if (parseReport) {
+                        settle(resolve, parseReport(code, reportText, `${stderr}\n${stdout}`.trim()));
+                        return;
+                    }
                     if (reportText === undefined) {
                         throw new Error('The current Vitest JSON report is missing for the retry run.');
                     }
@@ -489,6 +501,33 @@ export class RetryHandlerService {
             });
         });
     }
+    /**
+     * #1248: a pytest retry passes only when its JUnit report shows the test
+     * passed. A node id pytest cannot find (exit code 4) or no collected test
+     * (exit code 5) reran nothing.
+     */
+    parsePytestRetry(exitCode, report, output) {
+        const failure = (text) => ({
+            passed: false,
+            error: redactFailureText(text || `pytest exited with code ${exitCode}`).substring(0, 1000),
+        });
+        if (exitCode === 4 || exitCode === 5)
+            return UNMATCHED;
+        if (report === undefined)
+            return failure(output);
+        try {
+            const cases = parsePytestJunitXml(report);
+            if (cases.length === 0)
+                return UNMATCHED;
+            const failed = cases.find(c => c.status === 'failed' || c.status === 'error');
+            if (exitCode === 0 && !failed && cases.some(c => c.status === 'passed'))
+                return { passed: true };
+            return failure(failed ? [failed.message, failed.details].filter(Boolean).join('\n') : output);
+        }
+        catch {
+            return failure(output);
+        }
+    }
     /**
      * Parse test runner output to determine pass/fail status
      */

package/dist/domains/test-execution/services/runner-test-cases.d.ts

@@ -6,6 +6,8 @@
  * derived from aggregate counts.
  */
 import type { ITestCaseResult } from '../interfaces';
+/** A test case's failure text: redacted (#1122) and capped. */
+export declare function testCaseFailureMessage(text: string): string | undefined;
 /**
  * #1122: failure text goes back over MCP and into saved results, so
  * credential-shaped values (e.g. a connection string) are redacted first.

package/dist/domains/test-execution/services/runner-test-cases.js

@@ -12,10 +12,14 @@ const MAX_FAILURE_MESSAGE_LENGTH = 4000;
 function failureMessageOf(assertion) {
     if (!Array.isArray(assertion.failureMessages))
         return undefined;
-    const joined = assertion.failureMessages.filter((m) => typeof m === 'string').join('\n').trim();
-    if (!joined)
+    return testCaseFailureMessage(assertion.failureMessages.filter((m) => typeof m === 'string').join('\n'));
+}
+/** A test case's failure text: redacted (#1122) and capped. */
+export function testCaseFailureMessage(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
         return undefined;
-    const message = redactFailureText(joined);
+    const message = redactFailureText(trimmed);
     return message.length > MAX_FAILURE_MESSAGE_LENGTH
         ? `${message.slice(0, MAX_FAILURE_MESSAGE_LENGTH)}… [truncated]`
         : message;

package/dist/domains/test-execution/services/test-executor.d.ts

@@ -115,7 +115,7 @@ export declare class TestExecutorService implements ITestExecutionService {
     private executeTestFiles;
     private executeProjectFiles;
     /**
-     * Spawn actual test runner process (vitest, jest, mocha)
+     * Spawn actual test runner process (vitest, jest, mocha, node:test, pytest)
      */
     private spawnTestRunner;
     /**
@@ -126,6 +126,10 @@ export declare class TestExecutorService implements ITestExecutionService {
      * Parse test runner output to extract results
      */
     private parseTestOutput;
+    /**
+     * #1248: a pytest run from its JUnit report (undefined when pytest wrote none).
+     */
+    private parsePytestOutput;
     /**
      * Parse the TAP or spec summary emitted by Node's built-in test runner.
      */

package/dist/domains/test-execution/services/test-executor.js

@@ -17,11 +17,12 @@ import { secureRandom, secureRandomInt } from '../../../shared/utils/crypto-rand
 import { writeTestRunEvidence } from '../../quality-assessment/quality-evidence.js';
 import { istanbulLineHits } from '../../../coordination/handlers/handler-utils.js';
 import { fileCoverageKey, projectFileCoverageKeys } from '../../coverage-analysis/collected-metrics.js';
-import { mergeTestCases, redactFailedTests, redactFailureText, testCasesFromRunnerReport } from './runner-test-cases.js';
+import { mergeTestCases, redactFailedTests, redactFailureText, testCaseFailureMessage, testCasesFromRunnerReport } from './runner-test-cases.js';
 import { capDiagnostics, getTestRunnerExecutionError, TestRunnerExecutionError } from '../../../shared/test-runner-verdict.js';
 import { createVitestJsonReport } from '../../../shared/vitest-json-report.js';
+import { createPytestJunitReport, isPythonTestFile, pytestCommand, pytestRunFromReport, PYTEST_ENV } from '../../../shared/pytest-junit-report.js';
 import { jestExactPathPattern, runnerFilePath } from '../../../shared/test-runner-args.js';
-import { groupByRunnerProject } from '../../../shared/test-runner-project.js';
+import { groupByRunnerProject, runnerFrameworkFor } from '../../../shared/test-runner-project.js';
 import { getClaudeModelForTier } from '../../../shared/llm/model-registry.js';
 import { terminateTestRunner, trackTestRunnerExit } from '../../../shared/test-runner-process.js';
 const DEFAULT_CONFIG = {
@@ -315,7 +316,7 @@ Provide:
         return ok(undefined);
     }
     async runTests(request) {
-        const { testFiles, framework, timeout = 30000, projectRoot } = request;
+        const { testFiles, framework, timeout = 30000, projectRoot, frameworkFromConfig } = request;
         const failedTests = [];
         const coverages = [];
         const allFileCoverages = [];
@@ -324,7 +325,7 @@ Provide:
         let failed = 0;
         let skipped = 0;
         for (const file of testFiles) {
-            const result = await this.executeTestFile(file, framework, timeout, projectRoot);
+            const result = await this.executeTestFile(file, framework, timeout, projectRoot, frameworkFromConfig);
             executionResults.push(result);
             passed += result.passed;
             failed += result.failed;
@@ -394,25 +395,40 @@ Provide:
         const coverage = this.extractCoverageFromJson({ coverageMap: merged });
         return coverage.summary ? { summary: coverage.summary, perFile: coverage.perFile } : undefined;
     }
-    async executeTestFile(file, framework, timeout, projectRoot) {
-        return this.executeTestFiles([file], framework, timeout, projectRoot);
+    async executeTestFile(file, framework, timeout, projectRoot, frameworkFromConfig = false) {
+        return this.executeTestFiles([file], framework, timeout, projectRoot, frameworkFromConfig);
     }
-    async executeTestFiles(files, framework, timeout, projectRoot) {
+    async executeTestFiles(files, framework, timeout, projectRoot, frameworkFromConfig = false) {
         // In simulation mode (for unit testing), use random behavior
         if (this.config.simulateForTesting) {
             return this.aggregateResults(files.map(file => this.simulateTestExecution(file)));
         }
         // #1247: a runner loads the config of the directory it starts in, so each
         // file runs from its own runner project (or the caller's projectRoot).
+        // #1248: Python files run apart from the others, with pytest.
         const groups = projectRoot
-            ? [{ cwd: projectRoot, files }]
+            ? [files.filter(isPythonTestFile), files.filter(file => !isPythonTestFile(file))]
+                .filter(group => group.length > 0)
+                .map(group => ({ cwd: projectRoot, files: group }))
             : groupByRunnerProject(files);
+        // #1272: an explicit framework wins; otherwise the project's config decides.
+        // #1248: Python files run with pytest, never with a JavaScript runner.
+        const frameworkIn = (group) => {
+            if (group.files.some(isPythonTestFile)) {
+                if (frameworkFromConfig || framework.toLowerCase() === 'pytest')
+                    return 'pytest';
+                throw new TestRunnerExecutionError(`Python test files cannot run with ${framework}: ${group.files.filter(isPythonTestFile).join(', ')}. ` +
+                    `Use framework 'pytest', or leave the framework unset.`);
+            }
+            return (frameworkFromConfig ? runnerFrameworkFor(group.cwd) : undefined) ?? framework;
+        };
         if (groups.length === 1) {
-            return this.executeProjectFiles(groups[0].files, framework, timeout, groups[0].cwd);
+            return this.executeProjectFiles(groups[0].files, frameworkIn(groups[0]), timeout, groups[0].cwd);
         }
         // Each project gets its own runner and timeout. Their coverage maps are
         // merged from raw counters, or left unmeasured (#1030).
-        const results = await Promise.all(groups.map(group => this.executeProjectFiles(group.files, framework, timeout, group.cwd)));
+        const frameworks = groups.map(frameworkIn);
+        const results = await Promise.all(groups.map((group, index) => this.executeProjectFiles(group.files, frameworks[index], timeout, group.cwd)));
         const combined = this.aggregateResults(results);
         const merged = this.mergeSequentialCoverage(results);
         combined.coverage = merged?.summary;
@@ -445,7 +461,7 @@ Provide:
         return result.value;
     }
     /**
-     * Spawn actual test runner process (vitest, jest, mocha)
+     * Spawn actual test runner process (vitest, jest, mocha, node:test, pytest)
      */
     async spawnTestRunner(files, framework, timeout, cwd = process.cwd()) {
         // Verify test file exists
@@ -490,6 +506,7 @@ Provide:
                     env: {
                         ...process.env,
                         FORCE_COLOR: '0', // Disable color codes for easier parsing
+                        ...PYTEST_ENV, // pytest reads any FORCE_COLOR as "force colour" (#1248)
                         CI: 'true', // Enable CI mode for consistent output
                     },
                 });
@@ -534,11 +551,15 @@ Provide:
                     finish(err(toError(error)));
                     return;
                 }
-                if (reportText === undefined) {
+                // #1248: pytest reports its own missing report (pytest not installed).
+                const pytest = framework.toLowerCase() === 'pytest';
+                if (reportText === undefined && !pytest) {
                     finish(err(new TestRunnerExecutionError(`The current Vitest JSON report is missing for ${fileLabel}.`)));
                     return;
                 }
-                const parseResult = this.parseTestOutput(reportText, stderr, fileLabel, framework, code);
+                const parseResult = pytest
+                    ? this.parsePytestOutput(reportText, `${stderr}\n${stdout}`, files, code, command)
+                    : this.parseTestOutput(reportText ?? '', stderr, fileLabel, framework, code);
                 // Read only this invocation's coverage artifacts. A previous or
                 // concurrent run's project coverage directory is not evidence.
                 if (parseResult.success && coverageDirectory) {
@@ -611,8 +632,14 @@ Provide:
                     command: process.execPath,
                     args: ['--test', ...files],
                 };
+            case 'pytest': {
+                // #1248: results come from the JUnit report file; no coverage is collected.
+                const report = createPytestJunitReport();
+                return { ...pytestCommand(files, report.path), report };
+            }
             default: {
-                // Default to vitest
+                // Default to vitest. Python files never get here: executeTestFiles
+                // sends them to pytest or refuses the run (#1248).
                 const coverageDirectory = createCoverageDirectory();
                 let report;
                 try {
@@ -655,6 +682,43 @@ Provide:
                 `stdout: ${capDiagnostics(stdout, 500)}\nstderr: ${capDiagnostics(stderr, 500)}`));
         }
     }
+    /**
+     * #1248: a pytest run from its JUnit report (undefined when pytest wrote none).
+     */
+    parsePytestOutput(report, output, files, exitCode, python) {
+        const run = pytestRunFromReport(report, files, exitCode, output, python);
+        if (!run.success)
+            return run;
+        const failedTests = run.value.tests
+            .filter(test => test.status === 'failed')
+            .map(test => ({
+            testId: uuidv4(),
+            testName: test.name,
+            file: test.file,
+            error: test.failureMessage ?? 'Test failed',
+            stack: test.failureMessage ?? '',
+            duration: test.duration ?? 0,
+        }));
+        const testCases = run.value.tests.map(test => {
+            const failureMessage = test.failureMessage && testCaseFailureMessage(test.failureMessage);
+            return {
+                name: test.name,
+                file: test.file,
+                status: test.status,
+                ...(test.duration !== undefined ? { duration: test.duration } : {}),
+                ...(failureMessage ? { failureMessage } : {}),
+            };
+        });
+        return ok({
+            total: run.value.total,
+            passed: run.value.passed,
+            failed: run.value.failed,
+            skipped: run.value.skipped,
+            failedTests,
+            testCases,
+            coverage: undefined,
+        });
+    }
     /**
      * Parse the TAP or spec summary emitted by Node's built-in test runner.
      */
@@ -1018,7 +1082,7 @@ Provide:
         return shards;
     }
     async executeWorker(files, _workerIndex, _isolation, request) {
-        return this.executeTestFiles(files, request.framework, request.timeout ?? 30000, request.projectRoot);
+        return this.executeTestFiles(files, request.framework, request.timeout ?? 30000, request.projectRoot, request.frameworkFromConfig);
     }
     aggregateResults(results) {
         const aggregated = {

package/dist/init/copilot-installer.d.ts

@@ -29,6 +29,12 @@ export declare class CopilotInstaller {
     private generator;
     constructor(options: CopilotInstallerOptions);
     install(): Promise<CopilotInstallResult>;
+    /**
+     * Replace AQE's server entry in an existing config, keeping everything else.
+     * Returns null when the file cannot be merged safely (e.g. JSONC comments,
+     * which VS Code accepts but JSON.parse does not) so the user's file is never
+     * clobbered wholesale.
+     */
     private mergeExistingConfig;
 }
 export declare function createCopilotInstaller(options: CopilotInstallerOptions): CopilotInstaller;

package/dist/init/copilot-installer.js

@@ -8,6 +8,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { toErrorMessage } from '../shared/error-utils.js';
+import { writeFileIfChanged } from './idempotent-write.js';
 import { createPlatformConfigGenerator, } from './platform-config-generator.js';
 // ============================================================================
 // Copilot Installer Class
@@ -37,20 +38,28 @@ export class CopilotInstaller {
             const mcpConfig = this.generator.generateMcpConfig('copilot', { memoryBackend: this.options.memoryBackend });
             const configPath = join(this.projectRoot, mcpConfig.path);
             result.configPath = configPath;
-            if (!existsSync(configPath) || this.overwrite) {
+            // AQE's own server entry is refreshed on every init, independent of
+            // `overwrite` (#1269): its launch config is version-pinned, and a stale one
+            // leaves VS Code serving tool schemas cached from an older server. Other
+            // servers and top-level keys in the file are preserved.
+            if (!existsSync(configPath)) {
                 const configDir = dirname(configPath);
                 if (!existsSync(configDir)) {
                     mkdirSync(configDir, { recursive: true });
                 }
-                // Merge with existing if present
-                if (existsSync(configPath) && this.overwrite) {
-                    const merged = this.mergeExistingConfig(configPath, mcpConfig.content);
-                    writeFileSync(configPath, merged);
+                writeFileSync(configPath, mcpConfig.content);
+                result.mcpConfigured = true;
+            }
+            else {
+                const merged = this.mergeExistingConfig(configPath, mcpConfig.content);
+                if (merged === null) {
+                    result.errors.push(`${configPath} is not plain JSON (comments?) and was left unchanged; ` +
+                        `update its "agentic-qe" server entry by hand`);
                 }
                 else {
-                    writeFileSync(configPath, mcpConfig.content);
+                    writeFileIfChanged(configPath, merged);
+                    result.mcpConfigured = true;
                 }
-                result.mcpConfigured = true;
             }
             // Generate behavioral rules
             const rules = this.generator.generateBehavioralRules('copilot');
@@ -71,23 +80,34 @@ export class CopilotInstaller {
         }
         return result;
     }
+    /**
+     * Replace AQE's server entry in an existing config, keeping everything else.
+     * Returns null when the file cannot be merged safely (e.g. JSONC comments,
+     * which VS Code accepts but JSON.parse does not) so the user's file is never
+     * clobbered wholesale.
+     */
     mergeExistingConfig(configPath, newContent) {
+        let existing;
         try {
-            const existing = JSON.parse(readFileSync(configPath, 'utf-8'));
-            const incoming = JSON.parse(newContent);
-            // Merge servers
-            if (!existing.servers) {
-                existing.servers = {};
-            }
-            Object.assign(existing.servers, incoming.servers);
-            return JSON.stringify(existing, null, 2) + '\n';
+            existing = JSON.parse(readFileSync(configPath, 'utf-8'));
         }
         catch {
-            // If existing config is invalid, overwrite
-            return newContent;
+            return null;
         }
+        if (!isPlainObject(existing))
+            return null;
+        if (existing.servers === undefined)
+            existing.servers = {};
+        if (!isPlainObject(existing.servers))
+            return null;
+        const incoming = JSON.parse(newContent);
+        Object.assign(existing.servers, incoming.servers);
+        return JSON.stringify(existing, null, 2) + '\n';
     }
 }
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 // ============================================================================
 // Factory Function
 // ============================================================================

package/dist/init/platform-config-generator.d.ts

@@ -23,6 +23,16 @@ export interface GeneratedConfig {
     format: string;
 }
 export declare const PLATFORM_REGISTRY: Record<PlatformId, PlatformDefinition>;
+/**
+ * Issue #1269: VS Code caches each MCP server's tool list keyed by a hash of its
+ * launch config (command/args/env) and only restarts the server when that hash
+ * changes. The `agentic-qe@latest` entry is identical across releases, so tool
+ * schemas cached from an older server (the pre-#1185 "array type must have items"
+ * ones) survived upgrades. Stamping the installing version into the Copilot
+ * entry's env changes the hash whenever `aqe init` runs after an upgrade, without
+ * pinning which server version npx launches. The server does not read it.
+ */
+export declare function getCopilotInitVersionEnv(): Record<string, string>;
 export declare class PlatformConfigGenerator {
     /**
      * Get the platform definition for a given platform ID

package/dist/init/platform-config-generator.js

@@ -4,6 +4,7 @@
  *
  * Supports: GitHub Copilot, Cursor, Cline, Kilo Code, Roo Code, OpenAI Codex, Windsurf, Continue.dev
  */
+import { createRequire } from 'module';
 // ============================================================================
 // Platform Registry
 // ============================================================================
@@ -146,6 +147,29 @@ function getMcpServerEnv(dbFree) {
         ? { AQE_MEMORY_BACKEND: 'memory', AQE_V3_MODE: 'true' }
         : { AQE_MEMORY_PATH: '.agentic-qe/memory.db', AQE_V3_MODE: 'true' };
 }
+/**
+ * Installed AQE version: the build-time define in the CLI/MCP bundles, otherwise
+ * package.json (tsc output and tests). Both src/init/ and dist/cli/ sit two levels
+ * below the package root.
+ */
+function getInstalledAqeVersion() {
+    if (typeof __CLI_VERSION__ !== 'undefined')
+        return __CLI_VERSION__;
+    const pkg = createRequire(import.meta.url)('../../package.json');
+    return pkg.version;
+}
+/**
+ * Issue #1269: VS Code caches each MCP server's tool list keyed by a hash of its
+ * launch config (command/args/env) and only restarts the server when that hash
+ * changes. The `agentic-qe@latest` entry is identical across releases, so tool
+ * schemas cached from an older server (the pre-#1185 "array type must have items"
+ * ones) survived upgrades. Stamping the installing version into the Copilot
+ * entry's env changes the hash whenever `aqe init` runs after an upgrade, without
+ * pinning which server version npx launches. The server does not read it.
+ */
+export function getCopilotInitVersionEnv() {
+    return { AQE_INIT_VERSION: getInstalledAqeVersion() };
+}
 function getMcpServerEntry(withAutoApprove, dbFree) {
     const entry = {
         command: 'npx',
@@ -164,12 +188,13 @@ function getMcpServerEntry(withAutoApprove, dbFree) {
 function generateJsonConfig(platform, dbFree) {
     const serverEntry = getMcpServerEntry(platform.supportsAutoApprove, dbFree);
     if (platform.id === 'copilot') {
-        // Copilot uses "servers" key with "type": "stdio"
+        // Copilot uses "servers" key with "type": "stdio"; env carries the init version stamp (#1269)
         const config = {
             [platform.configKey]: {
                 'agentic-qe': {
                     type: 'stdio',
                     ...serverEntry,
+                    env: { ...serverEntry.env, ...getCopilotInitVersionEnv() },
                 },
             },
         };

package/dist/kernel/unified-memory.d.ts

@@ -82,6 +82,8 @@ export declare class UnifiedMemoryManager {
     private constructor();
     static getInstance(config?: Partial<UnifiedMemoryConfig>): UnifiedMemoryManager;
     static getInstanceAsync(config?: Partial<UnifiedMemoryConfig>): Promise<UnifiedMemoryManager>;
+    /** The shared instance when it is initialized; never creates one. */
+    static peekInitialized(): UnifiedMemoryManager | null;
     static resetInstance(): void;
     initialize(options?: {
         signal?: AbortSignal;
@@ -227,6 +229,12 @@ export declare class UnifiedMemoryManager {
 }
 export declare function getUnifiedMemory(config?: Partial<UnifiedMemoryConfig>): UnifiedMemoryManager;
 export declare function initializeUnifiedMemory(config?: Partial<UnifiedMemoryConfig>): Promise<UnifiedMemoryManager>;
+/**
+ * The shared memory.db connection when UnifiedMemory is already initialized,
+ * else null. Never opens it: callers that run before it keep their
+ * no-database behavior (#1298).
+ */
+export declare function getOpenUnifiedMemoryDatabase(): DatabaseType | null;
 export declare function resetUnifiedMemory(): void;
 /**
  * Run a write on `db` through the shared manager's writeWhenUnlocked queue

package/dist/kernel/unified-memory.js

@@ -174,6 +174,11 @@ export class UnifiedMemoryManager {
         }
         return UnifiedMemoryManager.instancePromise;
     }
+    /** The shared instance when it is initialized; never creates one. */
+    static peekInitialized() {
+        const instance = UnifiedMemoryManager.instance;
+        return instance?.initialized ? instance : null;
+    }
     static resetInstance() {
         if (UnifiedMemoryManager.instance) {
             UnifiedMemoryManager.instance.close();
@@ -1118,6 +1123,14 @@ export async function initializeUnifiedMemory(config) {
     await manager.initialize();
     return manager;
 }
+/**
+ * The shared memory.db connection when UnifiedMemory is already initialized,
+ * else null. Never opens it: callers that run before it keep their
+ * no-database behavior (#1298).
+ */
+export function getOpenUnifiedMemoryDatabase() {
+    return UnifiedMemoryManager.peekInitialized()?.getDatabase() ?? null;
+}
 export function resetUnifiedMemory() {
     UnifiedMemoryManager.resetInstance();
 }

package/dist/learning/embedder-endpoint-client.d.ts

@@ -15,6 +15,8 @@
  *   - Bearer auth from env only; URL userinfo stripped + warned on construct.
  *   - Probe + identity fingerprint required before `embed()`; breaker recovery
  *     invalidates identity so re-probe runs against a fresh endpoint.
+ *   - The first identity is bound for the client's lifetime: a re-probe that
+ *     finds another model is refused, never adopted (#1282).
  *   - True TCP connect timeout via socket-level setTimeout (not req.setTimeout).
  *   - TLS knobs (ca / cert / key / rejectUnauthorized / servername) for self-hosted.
  */
@@ -64,6 +66,8 @@ export interface EmbedderEndpointClientOptions {
     /** TLS overrides for https transport. Ignored for http/unix. */
     tlsOptions?: EmbedderTlsOptions;
 }
+/** The text every probe embeds; its vector is the endpoint's identity evidence. */
+export declare const ENDPOINT_IDENTITY_CANARY = "AQE embedder endpoint identity canary v1";
 /**
  * Parsed endpoint — either an HTTP(S) URL or a Unix socket path.
  */
@@ -92,6 +96,17 @@ export declare class EmbedderEndpointTimeoutError extends Error {
     readonly limitMs: number;
     constructor(phase: 'connect' | 'request', limitMs: number);
 }
+/**
+ * #1282: a probe found a different endpoint identity than the one the client
+ * bound to. Vectors from the new identity are not comparable with stored ones,
+ * so the client refuses to embed until the endpoint serves the bound identity
+ * again or the process restarts.
+ */
+export declare class EmbedderEndpointIdentityChangedError extends Error {
+    readonly bound: EndpointIdentity;
+    readonly current: EndpointIdentity;
+    constructor(bound: EndpointIdentity, current: EndpointIdentity);
+}
 /**
  * OpenAI-compatible embeddings client with keep-alive, circuit breaker, and identity probe.
  */
@@ -101,6 +116,15 @@ export declare class EmbedderEndpointClient {
     private readonly breaker;
     private readonly opts;
     private cachedIdentity;
+    /**
+     * #1282: the first identity a probe found. Every embedding this client
+     * returns belongs to it; later probes must find it again.
+     */
+    private boundIdentity;
+    /** #1282: the canary vector behind `boundIdentity`. */
+    private boundCanary;
+    /** #1282: set while the endpoint serves an identity other than the bound one. */
+    private identityChange;
     /** True while a probe is in flight — prevents the embed() lazy-probe race. */
     private probeInFlight;
     /**
@@ -146,7 +170,28 @@ export declare class EmbedderEndpointClient {
     probe(): Promise<EndpointIdentity>;
     private ensureProbed;
     private doProbe;
+    /**
+     * #1282: true when a re-probe found the bound model. The int16 fingerprint
+     * flips on noise of about 3e-5 per component, which the same model restarted
+     * on other hardware or kernels can produce, so a changed hash alone is not a
+     * changed model: the canary must also have moved below the ADR-097
+     * round-trip cosine.
+     */
+    private isBoundModel;
+    /**
+     * #1282: the endpoint answers, but as a different model than the one this
+     * client bound to (an endpoint restarted with another model of the same
+     * dimension, typically seen when the breaker recovers). Treat it as down:
+     * open the breaker so every caller fast-fails with this error, and retry
+     * as a half-open trial after each window, in case the bound model returns.
+     * Reported once per new identity.
+     */
+    private refuseIdentityChange;
     getCachedIdentity(): EndpointIdentity | null;
+    /** #1282: the identity every vector from this client belongs to. */
+    getBoundIdentity(): EndpointIdentity | null;
+    /** #1298: the canary vector behind the bound identity (ENDPOINT_IDENTITY_CANARY). */
+    getBoundCanary(): readonly number[] | null;
     getBreakerState(): {
         open: boolean;
         failures: number;