agentic-qe 3.15.1 → 3.15.3

package/dist/mcp/handlers/domain-handler-configs.js

@@ -7,6 +7,7 @@
  * @module mcp/handlers/domain-handler-configs
  */
 import { generateV2LearningFeedback, analyzeComplexity, generateV2AIInsights, generateV2Tests, detectAntiPatterns, generateTestId, } from './handler-factory.js';
+import { describeSavedResults } from './save-results-option.js';
 import { MetricsCollector } from '../metrics/index.js';
 import { DEFAULT_FRAMEWORKS, FRAMEWORK_TO_LANGUAGE, } from '../../shared/types/test-frameworks.js';
 import { buildRiskDecisionFromQualityGate, validateRiskDecision, } from '../../contracts/verdicts.js';
@@ -163,7 +164,8 @@ export const testGenerateConfig = {
             coverageEstimate: data.coverageEstimate ?? null,
             patternsUsed: data.patternsUsed || ['assertion-patterns', 'mock-generation', 'edge-case-detection'],
             duration,
-            savedFiles,
+            // #925: state plainly whether result files were written, with their paths.
+            ...describeSavedResults(params?.saveResults !== false, savedFiles),
             // #567: propagate the LLM-enhancement signal to the MCP caller.
             llmEnhanced,
             ...(data.generationMode ? { generationMode: data.generationMode } : {}),

package/dist/mcp/handlers/handler-factory.js

@@ -15,6 +15,7 @@ import { getFleetState, isFleetInitialized } from './core-handlers.js';
 import { createTaskExecutor } from '../../coordination/task-executor.js';
 import { getTaskRouter } from '../services/task-router.js';
 import { toErrorMessage } from '../../shared/error-utils.js';
+import { describeSavedResults, readSaveResultsOption } from './save-results-option.js';
 import { createInitializedFeedbackLoop, getQualityFeedbackLoop } from '../../feedback/feedback-loop.js';
 // ============================================================================
 // Shared Utilities (exported for response mappers)
@@ -594,6 +595,8 @@ export function createDomainHandler(config) {
         const { queen } = getFleetState();
         let routingResult = null;
         try {
+            // #925: per-call opt-out of result files, validated before any work.
+            const saveResults = readSaveResultsOption(params);
             // Step 2: Route task to optimal model tier (ADR-051).
             // Bounded by ROUTE_ADVISORY_TIMEOUT_MS — routing is an advisory hint and
             // must never block the tool; on timeout we proceed with null routing
@@ -603,6 +606,8 @@ export function createDomainHandler(config) {
             routingResult = await withTimeout(routeDomainTask(taskDescription, domain, codeContext), ROUTE_ADVISORY_TIMEOUT_MS, null);
             // Step 3: Build payload and submit task
             const payload = mapToPayload(params, routingResult);
+            if (!saveResults)
+                payload.saveResults = false;
             const timeout = calculateTimeout?.(params) ?? defaultTimeout;
             const submitResult = await queen.submitTask({
                 type: taskType,
@@ -636,6 +641,8 @@ export function createDomainHandler(config) {
             // Step 5: Map result
             const data = result.data;
             const mappedResult = mapToResult(submitResult.value, data, result.duration, result.savedFiles, params);
+            // #933: every result-saving tool reports what it wrote, the same way.
+            Object.assign(mappedResult, describeSavedResults(saveResults, result.savedFiles));
             // Step 5b: Record pattern usage on success (Phase 5.3 — fire-and-forget)
             recordPatternUsageAsync(routingResult?.patternHints, true, domain, result.duration);
             // Step 5c: Capture real execution learning (fire-and-forget)

package/dist/mcp/handlers/save-results-option.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Agentic QE v3 - saveResults option (#925)
+ *
+ * Domain tools that run through the handler factory persist their output via
+ * the task executor's ResultSaver (.agentic-qe/results/<kind>/...). This module
+ * holds the boundary validation for the per-call `saveResults` opt-out and the
+ * wording the tools report back, so every tool states the same thing.
+ *
+ * @module mcp/handlers/save-results-option
+ */
+import type { ToolParameter } from '../types';
+/** Directory (relative to the project) that ResultSaver writes under. */
+export declare const RESULTS_DIR = ".agentic-qe/results/";
+/**
+ * Every MCP tool whose handler is built by createDomainHandler, and so writes
+ * through ResultSaver (#933): what it saves, and the verb for "Set false to
+ * <verb> without writing...". Subdirectories match ResultSaver.save().
+ */
+export declare const RESULT_SAVING_TOOLS: {
+    readonly test_generate_enhanced: {
+        readonly saves: "a manifest and report under .agentic-qe/results/tests/";
+        readonly verb: "generate";
+    };
+    readonly test_execute_parallel: {
+        readonly saves: "the run results under .agentic-qe/results/other/";
+        readonly verb: "run the tests";
+    };
+    readonly coverage_analyze_sublinear: {
+        readonly saves: "coverage results and a report under .agentic-qe/results/coverage/";
+        readonly verb: "analyze";
+    };
+    readonly quality_assess: {
+        readonly saves: "an assessment and report under .agentic-qe/results/quality/";
+        readonly verb: "assess";
+    };
+    readonly security_scan_comprehensive: {
+        readonly saves: "scan results and a report under .agentic-qe/results/security/";
+        readonly verb: "scan";
+    };
+    readonly contract_validate: {
+        readonly saves: "the validation results under .agentic-qe/results/contracts/";
+        readonly verb: "validate";
+    };
+    readonly accessibility_test: {
+        readonly saves: "the test results under .agentic-qe/results/accessibility/";
+        readonly verb: "test";
+    };
+    readonly chaos_test: {
+        readonly saves: "the chaos run results under .agentic-qe/results/chaos/";
+        readonly verb: "run";
+    };
+    readonly defect_predict: {
+        readonly saves: "the prediction under .agentic-qe/results/defects/";
+        readonly verb: "predict";
+    };
+    readonly requirements_validate: {
+        readonly saves: "the validation results under .agentic-qe/results/other/";
+        readonly verb: "validate";
+    };
+    readonly code_index: {
+        readonly saves: "the index results under .agentic-qe/results/code-index/";
+        readonly verb: "index";
+    };
+};
+export type ResultSavingTool = keyof typeof RESULT_SAVING_TOOLS;
+/**
+ * Short hint a result-saving tool adds to its top-level description. Tool
+ * descriptions are kept short for clients that truncate them (OpenCode shows
+ * about 200 characters), so the full explanation lives in the `saveResults`
+ * parameter description instead.
+ */
+export declare const SAVE_RESULTS_HINT = "Saves results (saveResults).";
+/** The `saveResults` input parameter, worded the same for every tool. */
+export declare function saveResultsParameter(tool: ResultSavingTool): ToolParameter;
+/**
+ * Read and validate the optional `saveResults` parameter.
+ *
+ * @returns true when results should be saved (the default), false to opt out.
+ * @throws Error when the parameter is present but not a boolean.
+ */
+export declare function readSaveResultsOption(params: unknown): boolean;
+export interface SavedResultsReport {
+    /** True when at least one result file was written. */
+    resultsSaved: boolean;
+    /** Paths of the files written; empty when nothing was written. */
+    savedFiles: string[];
+    /** Plain statement of what was written, for the caller to relay. */
+    resultsNote: string;
+}
+/**
+ * Describe what the result saver did for one call.
+ *
+ * @param saveResults - the validated option value
+ * @param savedFiles - paths the task executor reported as written
+ */
+export declare function describeSavedResults(saveResults: boolean, savedFiles: string[] | undefined): SavedResultsReport;
+//# sourceMappingURL=save-results-option.d.ts.map

package/dist/mcp/handlers/save-results-option.js

@@ -0,0 +1,94 @@
+/**
+ * Agentic QE v3 - saveResults option (#925)
+ *
+ * Domain tools that run through the handler factory persist their output via
+ * the task executor's ResultSaver (.agentic-qe/results/<kind>/...). This module
+ * holds the boundary validation for the per-call `saveResults` opt-out and the
+ * wording the tools report back, so every tool states the same thing.
+ *
+ * @module mcp/handlers/save-results-option
+ */
+/** Directory (relative to the project) that ResultSaver writes under. */
+export const RESULTS_DIR = '.agentic-qe/results/';
+/**
+ * Every MCP tool whose handler is built by createDomainHandler, and so writes
+ * through ResultSaver (#933): what it saves, and the verb for "Set false to
+ * <verb> without writing...". Subdirectories match ResultSaver.save().
+ */
+export const RESULT_SAVING_TOOLS = {
+    test_generate_enhanced: { saves: 'a manifest and report under .agentic-qe/results/tests/', verb: 'generate' },
+    test_execute_parallel: { saves: 'the run results under .agentic-qe/results/other/', verb: 'run the tests' },
+    coverage_analyze_sublinear: { saves: 'coverage results and a report under .agentic-qe/results/coverage/', verb: 'analyze' },
+    quality_assess: { saves: 'an assessment and report under .agentic-qe/results/quality/', verb: 'assess' },
+    security_scan_comprehensive: { saves: 'scan results and a report under .agentic-qe/results/security/', verb: 'scan' },
+    contract_validate: { saves: 'the validation results under .agentic-qe/results/contracts/', verb: 'validate' },
+    accessibility_test: { saves: 'the test results under .agentic-qe/results/accessibility/', verb: 'test' },
+    chaos_test: { saves: 'the chaos run results under .agentic-qe/results/chaos/', verb: 'run' },
+    defect_predict: { saves: 'the prediction under .agentic-qe/results/defects/', verb: 'predict' },
+    requirements_validate: { saves: 'the validation results under .agentic-qe/results/other/', verb: 'validate' },
+    code_index: { saves: 'the index results under .agentic-qe/results/code-index/', verb: 'index' },
+};
+/**
+ * Short hint a result-saving tool adds to its top-level description. Tool
+ * descriptions are kept short for clients that truncate them (OpenCode shows
+ * about 200 characters), so the full explanation lives in the `saveResults`
+ * parameter description instead.
+ */
+export const SAVE_RESULTS_HINT = 'Saves results (saveResults).';
+/** The `saveResults` input parameter, worded the same for every tool. */
+export function saveResultsParameter(tool) {
+    const { saves, verb } = RESULT_SAVING_TOOLS[tool];
+    return {
+        name: 'saveResults',
+        type: 'boolean',
+        description: `Save ${saves} (default true). Set false to ${verb} without writing any files under ${RESULTS_DIR}. The server state store (.agentic-qe/memory.db) is updated either way.`,
+        default: true,
+    };
+}
+/**
+ * Read and validate the optional `saveResults` parameter.
+ *
+ * @returns true when results should be saved (the default), false to opt out.
+ * @throws Error when the parameter is present but not a boolean.
+ */
+export function readSaveResultsOption(params) {
+    if (params === null || typeof params !== 'object')
+        return true;
+    const value = params.saveResults;
+    // Some clients send null for an omitted optional; treat it as unset.
+    if (value === undefined || value === null)
+        return true;
+    if (typeof value !== 'boolean') {
+        throw new Error(`saveResults must be a boolean (true or false), got ${typeof value}.`);
+    }
+    return value;
+}
+/**
+ * Describe what the result saver did for one call.
+ *
+ * @param saveResults - the validated option value
+ * @param savedFiles - paths the task executor reported as written
+ */
+export function describeSavedResults(saveResults, savedFiles) {
+    if (!saveResults) {
+        return {
+            resultsSaved: false,
+            savedFiles: [],
+            resultsNote: `saveResults was false: no files were written under ${RESULTS_DIR}.`,
+        };
+    }
+    const files = savedFiles ?? [];
+    if (files.length === 0) {
+        return {
+            resultsSaved: false,
+            savedFiles: [],
+            resultsNote: `No result files were written under ${RESULTS_DIR} (saving is disabled or failed).`,
+        };
+    }
+    return {
+        resultsSaved: true,
+        savedFiles: files,
+        resultsNote: `Saved ${files.length} result file(s) under ${RESULTS_DIR}; see savedFiles. Pass saveResults: false to skip.`,
+    };
+}
+//# sourceMappingURL=save-results-option.js.map

package/dist/mcp/protocol-server.js

@@ -43,6 +43,7 @@ import { getPerformanceMonitor, } from './performance-monitor.js';
 import { ToolCallSignatureTracker } from '../kernel/anti-drift-middleware.js';
 import { formatErrorForLog } from '../logging/redaction.js';
 import { BEHAVIOR_EXAMPLE_ITEM_SCHEMA } from '../domains/test-generation/services/behavior-example-validation.js';
+import { SAVE_RESULTS_HINT, saveResultsParameter } from './handlers/save-results-option.js';
 import { requestOwnedShutdown } from '../kernel/process-lifecycle.js';
 import { createRequire } from 'module';
 const _require = createRequire(import.meta.url);
@@ -848,7 +849,7 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'test_generate_enhanced',
-                description: 'Generate unit/integration/e2e tests with AI pattern recognition and anti-pattern detection. Example: test_generate_enhanced({ sourceCode: "function add(a,b){return a+b}", testType: "unit", framework: "jest" })',
+                description: 'Generate unit/integration/e2e tests with AI pattern recognition and anti-pattern detection. By default saves a manifest and report under .agentic-qe/results/tests/ (paths returned in savedFiles); pass saveResults: false to generate without writing any result files. Example: test_generate_enhanced({ sourceCode: "function add(a,b){return a+b}", testType: "unit", framework: "jest" })',
                 category: 'domain',
                 parameters: [
                     { name: 'sourceCode', type: 'string', description: 'Source code to generate tests for' },
@@ -860,6 +861,7 @@ export class MCPProtocolServer {
                     { name: 'behaviorExamples', type: 'array', description: 'Trusted specification fixtures: [{functionName: "add", args: [2,3], expected: 5}]. Named JS/TS functions with required simple parameters; unit vitest/jest/node-test. No source-derived oracle. Omit for scaffolding.', items: BEHAVIOR_EXAMPLE_ITEM_SCHEMA },
                     { name: 'aiEnhancement', type: 'boolean', description: 'Enable AI-powered enhancement', default: true },
                     { name: 'detectAntiPatterns', type: 'boolean', description: 'Detect and report anti-patterns', default: false },
+                    saveResultsParameter('test_generate_enhanced'),
                 ],
             },
             handler: (params) => handleTestGenerate(params),
@@ -868,11 +870,12 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'test_execute_parallel',
-                description: 'Execute test files in parallel with automatic retry on flaky failures. Example: test_execute_parallel({ testFiles: ["tests/auth.test.ts"], parallel: true })',
+                description: `Execute test files in parallel with automatic retry on flaky failures. ${SAVE_RESULTS_HINT} Example: test_execute_parallel({ testFiles: ["tests/auth.test.ts"], parallel: true })`,
                 category: 'domain',
                 parameters: [
                     { name: 'testFiles', type: 'array', description: 'Nonempty list of concrete test file paths (relative to the project working directory or absolute). Expand glob patterns before calling; glob patterns are rejected.' },
                     { name: 'parallel', type: 'boolean', description: 'Enable parallel execution', default: true },
+                    saveResultsParameter('test_execute_parallel'),
                 ],
             },
             handler: (params) => handleTestExecute(params),
@@ -881,12 +884,13 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'coverage_analyze_sublinear',
-                description: 'Analyze code coverage with O(log n) sublinear algorithm and ML-powered gap detection. Example: coverage_analyze_sublinear({ target: "src/", detectGaps: true })',
+                description: `Analyze code coverage with O(log n) sublinear algorithm and ML-powered gap detection. ${SAVE_RESULTS_HINT} Example: coverage_analyze_sublinear({ target: "src/", detectGaps: true })`,
                 category: 'domain',
                 isConcurrencySafe: true,
                 parameters: [
                     { name: 'target', type: 'string', description: 'Target path to analyze', required: true },
                     { name: 'detectGaps', type: 'boolean', description: 'Detect coverage gaps', default: true },
+                    saveResultsParameter('coverage_analyze_sublinear'),
                 ],
             },
             handler: (params) => handleCoverageAnalyze(params),
@@ -895,11 +899,12 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'quality_assess',
-                description: 'Assess code quality metrics and optionally run a pass/fail quality gate. Example: quality_assess({ runGate: true })',
+                description: `Assess code quality metrics and optionally run a pass/fail quality gate. ${SAVE_RESULTS_HINT} Example: quality_assess({ runGate: true })`,
                 category: 'domain',
                 isConcurrencySafe: true,
                 parameters: [
                     { name: 'runGate', type: 'boolean', description: 'Evaluate all seven canonical measured quality checks; requires complete, valid evidence from the last 24 hours. Returns individual checks, not a static aggregate score.', default: false },
+                    saveResultsParameter('quality_assess'),
                 ],
             },
             handler: (params) => handleQualityAssess(params),
@@ -908,13 +913,14 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'security_scan_comprehensive',
-                description: 'Run security scans with execution evidence and explicit coverage limitations. Complete means the declared required scope ran, not that all vulnerabilities are absent. Example: security_scan_comprehensive({ target: "src/", sast: true })',
+                description: `Run security scans with execution evidence and explicit coverage limitations. Complete means the declared required scope ran, not that all vulnerabilities are absent. Example: security_scan_comprehensive({ target: "src/", sast: true })`,
                 category: 'domain',
                 parameters: [
                     { name: 'sast', type: 'boolean', description: 'Run SAST scan', default: true },
                     { name: 'dast', type: 'boolean', description: 'Run DAST scan', default: false },
                     { name: 'target', type: 'string', description: 'Source file or directory for SAST' },
                     { name: 'targetUrl', type: 'string', description: 'URL for a requested DAST scan' },
+                    saveResultsParameter('security_scan_comprehensive'),
                 ],
             },
             handler: (params) => handleSecurityScan(params),
@@ -923,10 +929,11 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'contract_validate',
-                description: 'Validate API contracts for breaking changes against consumers. Example: contract_validate({ contractPath: "api/openapi.yaml" })',
+                description: `Validate API contracts for breaking changes against consumers. ${SAVE_RESULTS_HINT} Example: contract_validate({ contractPath: "api/openapi.yaml" })`,
                 category: 'domain',
                 parameters: [
                     { name: 'contractPath', type: 'string', description: 'Path to contract file' },
+                    saveResultsParameter('contract_validate'),
                 ],
             },
             handler: (params) => handleContractValidate(params),
@@ -935,11 +942,12 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'accessibility_test',
-                description: 'Test accessibility against WCAG 2.1/2.2 and Section 508 standards. Example: accessibility_test({ url: "http://localhost:3000", standard: "wcag21-aa" })',
+                description: `Test accessibility against WCAG 2.1/2.2 and Section 508 standards. ${SAVE_RESULTS_HINT} Example: accessibility_test({ url: "http://localhost:3000", standard: "wcag21-aa" })`,
                 category: 'domain',
                 parameters: [
                     { name: 'url', type: 'string', description: 'URL to test', required: true },
                     { name: 'standard', type: 'string', description: 'Accessibility standard' },
+                    saveResultsParameter('accessibility_test'),
                 ],
             },
             handler: (params) => handleAccessibilityTest(params),
@@ -948,11 +956,12 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'chaos_test',
-                description: 'Inject faults (latency, errors, CPU) for chaos engineering resilience testing. Example: chaos_test({ faultType: "latency", target: "api-service" })',
+                description: `Inject faults (latency, errors, CPU) for chaos engineering resilience testing. ${SAVE_RESULTS_HINT} Example: chaos_test({ faultType: "latency", target: "api-service" })`,
                 category: 'domain',
                 parameters: [
                     { name: 'faultType', type: 'string', description: 'Type of fault to inject' },
                     { name: 'target', type: 'string', description: 'Target service' },
+                    saveResultsParameter('chaos_test'),
                 ],
             },
             handler: (params) => handleChaosTest(params),
@@ -961,11 +970,12 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'defect_predict',
-                description: 'Predict potential defects using AI analysis of code complexity and change history. Example: defect_predict({ target: "src/auth/" })',
+                description: `Predict potential defects using AI analysis of code complexity and change history. ${SAVE_RESULTS_HINT} Example: defect_predict({ target: "src/auth/" })`,
                 category: 'domain',
                 isConcurrencySafe: true,
                 parameters: [
                     { name: 'target', type: 'string', description: 'Target path', required: true },
+                    saveResultsParameter('defect_predict'),
                 ],
             },
             handler: (params) => handleDefectPredict(params),
@@ -974,11 +984,12 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'requirements_validate',
-                description: 'Validate requirements for completeness and generate BDD scenarios. Example: requirements_validate({ requirementsPath: "docs/requirements.md" })',
+                description: `Validate requirements for completeness and generate BDD scenarios. ${SAVE_RESULTS_HINT} Example: requirements_validate({ requirementsPath: "docs/requirements.md" })`,
                 category: 'domain',
                 isConcurrencySafe: true,
                 parameters: [
                     { name: 'requirementsPath', type: 'string', description: 'Path to requirements' },
+                    saveResultsParameter('requirements_validate'),
                 ],
             },
             handler: (params) => handleRequirementsValidate(params),
@@ -987,11 +998,12 @@ export class MCPProtocolServer {
         this.registerTool({
             definition: {
                 name: 'code_index',
-                description: 'Index source code into the knowledge graph for dependency and impact analysis. Example: code_index({ target: "src/" })',
+                description: `Index source code into the knowledge graph for dependency and impact analysis. ${SAVE_RESULTS_HINT} Example: code_index({ target: "src/" })`,
                 category: 'domain',
                 isConcurrencySafe: true,
                 parameters: [
                     { name: 'target', type: 'string', description: 'Target path', required: true },
+                    saveResultsParameter('code_index'),
                 ],
             },
             handler: (params) => handleCodeIndex(params),

package/dist/mcp/security/rate-limiter.d.ts

@@ -101,7 +101,12 @@ export declare class RateLimiter {
      */
     consume(clientId?: string, endpoint?: string, tokens?: number): RateLimitResult;
     /**
-     * Wait until tokens are available (async)
+     * Wait until tokens are available (async).
+     *
+     * Rejects with a RangeError instead of waiting forever when the request can
+     * never be admitted: the cost exceeds the resolved bucket's maxBurst, or the
+     * bucket cannot refill (tokensPerSecond <= 0), or the refill delay exceeds
+     * what setTimeout can represent (it would clamp to 1 ms and spin). See #905.
      */
     wait(clientId?: string, endpoint?: string, tokens?: number): Promise<RateLimitResult>;
     /**
@@ -132,6 +137,8 @@ export declare class RateLimiter {
      * Dispose the rate limiter
      */
     dispose(): void;
+    /** Throw if `tokens` can never fit in the bucket resolved for `endpoint`. */
+    private assertAdmissible;
     private createBucket;
     private getBucket;
     private getEndpointKey;

package/dist/mcp/security/rate-limiter.js

@@ -9,6 +9,8 @@
  * - Configurable limits per endpoint
  */
 import { createSafeRegex } from './validators/regex-safety-validator.js';
+/** Largest delay setTimeout honours; larger values are clamped to 1 ms. */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 // ============================================================================
 // Token Bucket Implementation
 // ============================================================================
@@ -121,12 +123,29 @@ export class RateLimiter {
         };
     }
     /**
-     * Wait until tokens are available (async)
+     * Wait until tokens are available (async).
+     *
+     * Rejects with a RangeError instead of waiting forever when the request can
+     * never be admitted: the cost exceeds the resolved bucket's maxBurst, or the
+     * bucket cannot refill (tokensPerSecond <= 0), or the refill delay exceeds
+     * what setTimeout can represent (it would clamp to 1 ms and spin). See #905.
      */
     async wait(clientId, endpoint, tokens = 1) {
+        this.assertAdmissible(endpoint, tokens);
         let result = this.consume(clientId, endpoint, tokens);
-        while (!result.allowed && result.retryAfter) {
-            await this.sleep(result.retryAfter);
+        while (!result.allowed) {
+            const delay = result.retryAfter;
+            if (delay === undefined || !Number.isFinite(delay) || delay <= 0) {
+                throw new RangeError(`Rate limit bucket for ${endpoint ?? 'default'} cannot refill (retryAfter=${delay}); ` +
+                    'wait() would never settle');
+            }
+            if (delay > MAX_TIMER_DELAY_MS) {
+                throw new RangeError(`Rate limit retryAfter ${delay}ms for ${endpoint ?? 'default'} bucket exceeds the ` +
+                    `${MAX_TIMER_DELAY_MS}ms setTimeout maximum; wait() would spin instead of sleeping`);
+            }
+            await this.sleep(delay);
+            // Endpoint limits may change while sleeping; re-check before retrying.
+            this.assertAdmissible(endpoint, tokens);
             result = this.consume(clientId, endpoint, tokens);
         }
         return result;
@@ -199,6 +218,14 @@ export class RateLimiter {
     // ============================================================================
     // Private Methods
     // ============================================================================
+    /** Throw if `tokens` can never fit in the bucket resolved for `endpoint`. */
+    assertAdmissible(endpoint, tokens) {
+        const { maxBurst } = this.getConfig(endpoint);
+        if (tokens > maxBurst) {
+            throw new RangeError(`Token cost ${tokens} exceeds maxBurst ${maxBurst} for ${endpoint ?? 'default'} bucket; ` +
+                'wait() can never admit it');
+        }
+    }
     createBucket() {
         const now = Date.now();
         return {
@@ -274,7 +301,9 @@ export class RateLimiter {
         };
     }
     refillBucket(bucket, tokensPerSecond, maxBurst, now) {
-        const elapsed = (now - bucket.lastUpdate) / 1000;
+        // A bucket created after `now` was read (or a clock step back) must not
+        // remove tokens, so negative elapsed time counts as zero.
+        const elapsed = Math.max(0, now - bucket.lastUpdate) / 1000;
         const newTokens = elapsed * tokensPerSecond;
         bucket.tokens = Math.min(maxBurst, bucket.tokens + newTokens);
         bucket.lastUpdate = now;

package/dist/mcp/services/session-resume.js

@@ -43,6 +43,14 @@ function isValidEntry(value) {
             && Number.isSafeInteger(entry.tokenEstimate)
             && entry.tokenEstimate >= 0));
 }
+/** Entries a session-store gap marker stands for (#910), or 0 for an ordinary entry. */
+function gapSize(entry) {
+    if (entry.type !== 'state_change' || !entry.result || typeof entry.result !== 'object')
+        return 0;
+    const gap = entry.result.journalGap;
+    const dropped = gap?.droppedEntries;
+    return typeof dropped === 'number' && Number.isSafeInteger(dropped) && dropped > 0 ? dropped : 0;
+}
 function resolveLimit(value, defaultValue) {
     const limit = value ?? defaultValue;
     return Number.isSafeInteger(limit) && limit > 0 && limit <= defaultValue ? limit : undefined;
@@ -168,6 +176,7 @@ export function resumeSession(filePath, options) {
         const entries = [];
         const seen = new Set();
         let previous;
+        let droppedInGaps = 0;
         for (const rawLine of lines) {
             if (!rawLine.trim())
                 continue;
@@ -198,6 +207,7 @@ export function resumeSession(filePath, options) {
                 return emptyResult(filePath, 'INVALID', ['first entry has a forged parentUuid']);
             }
             seen.add(parsed.uuid);
+            droppedInGaps += gapSize(parsed);
             entries.push(parsed);
             previous = parsed;
         }
@@ -208,6 +218,7 @@ export function resumeSession(filePath, options) {
         const diagnostics = [
             'legacy JSONL has no durable commit marker',
             ...(hasTornTail ? ['discarded an incomplete final record'] : []),
+            ...(droppedInGaps > 0 ? [`journal gap: ${droppedInGaps} entries dropped while the disk was failing`] : []),
         ];
         return {
             metadata: {

package/dist/mcp/services/session-store.d.ts

@@ -6,6 +6,12 @@
  * changes within a session. Supports write batching (100ms window) and
  * lazy file creation (no file until first append).
  *
+ * Issue #910: writes track progress byte by byte, so a write that fails partway
+ * (ENOSPC, EIO) resumes where it stopped instead of re-appending what already
+ * reached the disk. The unwritten backlog is bounded while the disk keeps
+ * failing; dropped entries become one gap marker that keeps the transcript
+ * resumable (see session-write-buffer.ts).
+ *
  * @module mcp/services/session-store
  */
 export interface SessionEntry {
@@ -27,6 +33,18 @@ export interface SessionMetadata {
     state: 'idle' | 'running' | 'requires_action';
 }
 export type SessionEntryInput = Omit<SessionEntry, 'uuid' | 'parentUuid'>;
+export interface SessionStoreOptions {
+    /** Most unwritten entries held while writes fail. Oldest are dropped beyond it. */
+    maxBufferedEntries?: number;
+    /** Most unwritten bytes held while writes fail. Oldest are dropped beyond it. */
+    maxBufferedBytes?: number;
+}
+export interface SessionWriteBufferStats {
+    bufferedEntries: number;
+    bufferedBytes: number;
+    /** Entries replaced by a gap marker in this session because the buffer hit a cap. */
+    droppedEntries: number;
+}
 export declare class SessionStore {
     private readonly sessionDir;
     private sessionId;
@@ -37,11 +55,15 @@ export declare class SessionStore {
     private createdAt;
     private lastActivityAt;
     private currentState;
+    /** Lines not yet fully on disk, oldest first. */
     private writeBuffer;
+    private dropWarned;
+    private readonly maxBufferedEntries;
+    private readonly maxBufferedBytes;
     private flushTimer;
     private closed;
     private readonly persistDisabled;
-    constructor(sessionDir?: string);
+    constructor(sessionDir?: string, options?: SessionStoreOptions);
     /**
      * Start a new session. Returns the sessionId (UUID).
      * File is NOT created until the first append (lazy creation).
@@ -52,7 +74,7 @@ export declare class SessionStore {
      * Assigns a uuid, links parentUuid to the previous entry,
      * and writes a JSON line to the file.
      *
-     * First write uses appendFileSync for write-ahead guarantee.
+     * The first write is synchronous for a write-ahead guarantee.
      * Subsequent writes are batched for up to 100ms before flushing.
      *
      * Returns the assigned uuid.
@@ -62,6 +84,10 @@ export declare class SessionStore {
      * Force sync any buffered writes to disk immediately.
      */
     flush(): void;
+    /**
+     * Size of the unwritten backlog and how many entries the cap has dropped.
+     */
+    getWriteBufferStats(): SessionWriteBufferStats;
     /**
      * Returns metadata about the current session.
      */
@@ -80,6 +106,9 @@ export declare class SessionStore {
      */
     getFilePath(): string | null;
     private ensureDirectory;
+    private accept;
+    private writePending;
+    private createWriteBuffer;
     private scheduleBatchFlush;
 }
 //# sourceMappingURL=session-store.d.ts.map