agentic-qe 3.15.10 → 3.15.12

package/dist/mcp/tools/test-execution/execute.js

@@ -9,6 +9,7 @@
 import { MCPToolBase } from '../base.js';
 import { toErrorMessage } from '../../../shared/error-utils.js';
 import { secureRandom, secureRandomFloat } from '../../../shared/utils/crypto-random.js';
+import { DEFAULT_TEST_RETRY_COUNT } from '../../../domains/test-execution/services/retry-outcome.js';
 // ============================================================================
 // Tool Implementation
 // ============================================================================
@@ -22,7 +23,7 @@ export class TestExecuteTool extends MCPToolBase {
         timeout: 300000,
     };
     async execute(params, context) {
-        const { testFiles = [], testSuites = [], pattern, parallel = true, parallelism = 4, retryCount = 3, timeout = 60000, collectCoverage = false, reportFormat = 'json', failFast = false, } = params;
+        const { testFiles = [], testSuites = [], pattern, parallel = true, parallelism = 4, retryCount = DEFAULT_TEST_RETRY_COUNT, collectCoverage = false, failFast = false, } = params;
         const startTime = Date.now();
         try {
             // Determine files to test
@@ -164,7 +165,7 @@ const TEST_EXECUTE_SCHEMA = {
             description: 'Number of retries for failed tests',
             minimum: 0,
             maximum: 5,
-            default: 3,
+            default: DEFAULT_TEST_RETRY_COUNT,
         },
         timeout: {
             type: 'number',

package/dist/mcp/types.d.ts

@@ -584,6 +584,20 @@ export interface CoverageAnalyzeResult {
      * this is "no measurement", never 0%.
      */
     unmeasured?: boolean;
+    /**
+     * #1154: `insufficient-evidence` when source files under the target are not
+     * in the report, or the report is older than the sources. The figures then
+     * cover the measured files only and must not be read as a pass.
+     */
+    evidenceStatus?: 'complete' | 'insufficient-evidence';
+    /** #1154: source files under the target with no entry in the report. */
+    unmeasuredFiles?: string[];
+    /** #1154: the report is older than these source files. */
+    staleReport?: {
+        reportPath: string;
+        reportModified: string;
+        newerFiles: string[];
+    };
     /** Caveats the caller should surface (e.g. "no instrumentation ran"). */
     warning?: string;
 }

package/dist/memory/crdt/crdt-store.js

@@ -309,6 +309,9 @@ export function createCRDTStore(config) {
         applyState(incoming) {
             // Apply registers
             for (const [key, state] of Object.entries(incoming.registers)) {
+                // One malformed peer entry must not block unrelated state from converging.
+                if (typeof state?.timestamp !== 'number' || !Number.isFinite(state.timestamp))
+                    continue;
                 if (!registers.has(key)) {
                     registers.set(key, createLWWRegisterFromState(nodeId, state));
                 }
@@ -431,6 +434,8 @@ export function createCRDTStore(config) {
             // Apply delta similar to full state, but only for included keys
             if (delta.registers) {
                 for (const [key, state] of Object.entries(delta.registers)) {
+                    if (typeof state?.timestamp !== 'number' || !Number.isFinite(state.timestamp))
+                        continue;
                     if (!registers.has(key)) {
                         registers.set(key, createLWWRegisterFromState(nodeId, state));
                     }

package/dist/memory/crdt/lww-register.js

@@ -7,6 +7,11 @@
  *
  * @module memory/crdt/lww-register
  */
+function assertFiniteTimestamp(timestamp) {
+    if (!Number.isFinite(timestamp)) {
+        throw new RangeError('LWW register timestamp must be a finite number');
+    }
+}
 // =============================================================================
 // LWW Register Implementation
 // =============================================================================
@@ -26,10 +31,12 @@
  * ```
  */
 export function createLWWRegister(nodeId, initialValue, initialTimestamp) {
+    const timestamp = initialTimestamp ?? (initialValue !== undefined ? Date.now() : 0);
+    assertFiniteTimestamp(timestamp);
     // Internal state
     let state = {
         value: initialValue,
-        timestamp: initialTimestamp ?? (initialValue !== undefined ? Date.now() : 0),
+        timestamp,
         nodeId: initialValue !== undefined ? nodeId : '',
         version: initialValue !== undefined ? 1 : 0,
         lastUpdated: Date.now(),
@@ -51,6 +58,7 @@ export function createLWWRegister(nodeId, initialValue, initialTimestamp) {
         },
         set(value, timestamp) {
             let ts = timestamp ?? Date.now();
+            assertFiniteTimestamp(ts);
             // Without an explicit timestamp the write means "now": a second write by
             // this node within one clock tick (or after a backwards clock step) must
             // still supersede its own earlier write, not tie with it and be dropped.
@@ -88,6 +96,8 @@ export function createLWWRegister(nodeId, initialValue, initialTimestamp) {
             // (0) would otherwise beat a real write at a negative timestamp.
             if (incoming.version === 0)
                 return;
+            // NaN breaks total ordering; infinity would permanently outrank finite writes.
+            assertFiniteTimestamp(incoming.timestamp);
             // Only update if incoming timestamp wins
             if (state.version === 0 ||
                 compareTimestamps(incoming.timestamp, incoming.nodeId, state.timestamp, state.nodeId) > 0) {
@@ -134,7 +144,7 @@ export function isLWWRegisterState(value) {
         return false;
     }
     const state = value;
-    return (typeof state.timestamp === 'number' &&
+    return (typeof state.timestamp === 'number' && Number.isFinite(state.timestamp) &&
         typeof state.nodeId === 'string' &&
         typeof state.version === 'number' &&
         typeof state.lastUpdated === 'number' &&

package/dist/optimization/early-exit-token-optimizer.js

@@ -8,6 +8,7 @@
  */
 import { detectQEDomain } from '../learning/qe-patterns.js';
 import { toErrorMessage } from '../shared/error-utils.js';
+import { createSafeRecord } from '../shared/utils/safe-record.js';
 /**
  * Default early exit configuration
  */
@@ -374,7 +375,8 @@ export class EarlyExitTokenOptimizer {
             reasonBreakdown[attempt.reason]++;
         }
         // Calculate domain breakdown
-        const domainBreakdown = {};
+        // #1157: domains come from recorded requests.
+        const domainBreakdown = createSafeRecord();
         for (const reuse of this.reuseHistory) {
             const domain = reuse.domain ?? 'unknown';
             if (!domainBreakdown[domain]) {

package/dist/planning/goap-planner.js

@@ -645,6 +645,11 @@ export class GOAPPlanner {
             if (current === null || current === undefined) {
                 return undefined;
             }
+            // #1157: goal and condition keys can come from callers; an inherited
+            // member such as `constructor` is not part of the world state.
+            if (typeof current !== 'object' || !Object.hasOwn(current, part)) {
+                return undefined;
+            }
             current = current[part];
         }
         return current;

package/dist/planning/plan-executor.js

@@ -900,6 +900,11 @@ export class PlanExecutor {
             if (current === null || current === undefined) {
                 return undefined;
             }
+            // #1157: goal and condition keys can come from callers; an inherited
+            // member such as `constructor` is not part of the world state.
+            if (typeof current !== 'object' || !Object.hasOwn(current, part)) {
+                return undefined;
+            }
             current = current[part];
         }
         return current;

package/dist/routing/advisor/redaction.js

@@ -26,7 +26,7 @@ const PATTERNS = [
     },
     {
         category: 'api_key_header',
-        regex: /(Authorization:\s*Bearer\s+)\S+/gi,
+        regex: /(Authorization:\s*(?:Bearer|Token)\s+)\S+/gi,
         replacement: '$1<REDACTED:api_key>',
         modes: ['strict', 'balanced'],
     },
@@ -38,7 +38,8 @@ const PATTERNS = [
     },
     {
         category: 'private_key',
-        regex: /-----BEGIN\s[\w\s]*PRIVATE KEY-----[\s\S]*?-----END\s[\w\s]*PRIVATE KEY-----/g,
+        // A block with no END line (truncated output) is redacted to end of input.
+        regex: /-----BEGIN\s[\w\s]*PRIVATE KEY-----(?:[\s\S]*?-----END\s[\w\s]*PRIVATE KEY-----|[\s\S]*)/g,
         replacement: '<REDACTED:private_key>',
         modes: ['strict', 'balanced'],
     },
@@ -66,6 +67,25 @@ const PATTERNS = [
         replacement: '<REDACTED:slack_token>',
         modes: ['strict', 'balanced'],
     },
+    {
+        category: 'huggingface_token',
+        regex: /\bhf_[A-Za-z0-9]{30,}\b/g,
+        replacement: '<REDACTED:huggingface_token>',
+        modes: ['strict', 'balanced'],
+    },
+    {
+        category: 'npm_token',
+        regex: /\bnpm_[A-Za-z0-9]{36,}\b/g,
+        replacement: '<REDACTED:npm_token>',
+        modes: ['strict', 'balanced'],
+    },
+    {
+        // Cognitum API keys; the trailing lookahead skips snake_case identifiers.
+        category: 'cognitum_key',
+        regex: /\bcog_[A-Za-z0-9-]{20,}(?!\w)/g,
+        replacement: '<REDACTED:cognitum_key>',
+        modes: ['strict', 'balanced'],
+    },
     {
         category: 'stripe_key',
         regex: /\b(sk_live_|pk_live_|sk_test_|pk_test_|rk_live_|rk_test_)[A-Za-z0-9]{10,}\b/g,

package/dist/shared/io/confined-read.d.ts

@@ -0,0 +1,74 @@
+/**
+ * #1161: read a file inside the project root without a check-then-use race.
+ *
+ * The payload path guard (#1126) checks a path by name and the handler opens
+ * it again later, so a file or symlink swapped in between could be read
+ * unchecked. These readers OPEN first and validate what was opened:
+ *
+ * - the path's realpath is opened with O_NOFOLLOW (a symlink swapped onto the
+ *   final name fails the open) and O_NONBLOCK (a FIFO cannot hang the open);
+ * - the descriptor must be a regular file within the size limit (fstat);
+ * - the descriptor's real location (/proc/self/fd/N on Linux; elsewhere the
+ *   re-resolved realpath, which must be the same inode) must lie inside the
+ *   project root, so a directory component swapped for a symlink is caught;
+ * - the content is read from that same descriptor, and never past the limit,
+ *   even if the file grows after the fstat.
+ *
+ * A path spelled outside the root is refused before any filesystem call,
+ * unless the caller opts into `outsideRoot: 'allow'` for paths it accepts
+ * from a trusted source (the other checks still apply).
+ */
+import { type Stats } from 'node:fs';
+import { CallerInputError } from '../error-utils.js';
+/** Default upper bound for a confined read when the caller names none. */
+export declare const DEFAULT_MAX_CONFINED_READ_BYTES: number;
+export type ConfinedReadReason = 'not-found' | 'not-a-file' | 'outside-project-root' | 'unreadable' | 'too-large';
+export interface ConfinedReadOptions {
+    /** Project root; defaults to findProjectRoot(). */
+    projectRoot?: string;
+    /** Refuse files larger than this; defaults to DEFAULT_MAX_CONFINED_READ_BYTES. */
+    maxBytes?: number;
+    /**
+     * A path spelled outside the project root is refused ('refuse', default),
+     * or read without the containment check ('allow') when the caller already
+     * trusts it. Paths spelled inside the root are always held to the root.
+     */
+    outsideRoot?: 'refuse' | 'allow';
+}
+/**
+ * A confined read that was refused; `reason` matches the payload guard's.
+ * `code` is the errno code when the filesystem gave one (ENOENT, ELOOP, ...),
+ * otherwise the reason in errno style (OUTSIDE_PROJECT_ROOT, NOT_A_FILE,
+ * TOO_LARGE), so callers that report error codes keep working.
+ */
+export declare class ConfinedReadError extends CallerInputError {
+    readonly filePath: string;
+    readonly reason: ConfinedReadReason;
+    readonly code: string;
+    constructor(filePath: string, reason: ConfinedReadReason, errnoCode?: string);
+}
+/** Flags for opening a checked realpath: read-only, no final symlink, no FIFO wait. */
+export declare const CONFINED_OPEN_FLAGS: number;
+/** True when `candidate` is `root` or lies beneath it (both absolute). */
+export declare function isWithinRoot(root: string, candidate: string): boolean;
+/**
+ * Where an OPEN descriptor really points. On Linux, /proc/self/fd/N resolves
+ * to the opened file itself. Elsewhere, re-resolve the path and accept it only
+ * if it is the same inode as the descriptor, so a swap after the open is
+ * detected. Returns null when it cannot be proven.
+ */
+export declare function openedLocation(fd: number, lexical: string, opened: Stats): Promise<string | null>;
+/** Synchronous openedLocation, for callers that read synchronously. */
+export declare function openedLocationSync(fd: number, lexical: string, opened: Stats): string | null;
+/**
+ * Read a file by path, confined to the project root and validated on the
+ * opened descriptor (see the module comment). Throws ConfinedReadError.
+ */
+export declare function readConfinedFile(filePath: string, options?: ConfinedReadOptions): Promise<Buffer>;
+/** readConfinedFile decoded as UTF-8. */
+export declare function readConfinedText(filePath: string, options?: ConfinedReadOptions): Promise<string>;
+/** Synchronous readConfinedFile, for callers that cannot await. */
+export declare function readConfinedFileSync(filePath: string, options?: ConfinedReadOptions): Buffer;
+/** readConfinedFileSync decoded as UTF-8. */
+export declare function readConfinedTextSync(filePath: string, options?: ConfinedReadOptions): string;
+//# sourceMappingURL=confined-read.d.ts.map

package/dist/shared/io/confined-read.js

@@ -0,0 +1,256 @@
+/**
+ * #1161: read a file inside the project root without a check-then-use race.
+ *
+ * The payload path guard (#1126) checks a path by name and the handler opens
+ * it again later, so a file or symlink swapped in between could be read
+ * unchecked. These readers OPEN first and validate what was opened:
+ *
+ * - the path's realpath is opened with O_NOFOLLOW (a symlink swapped onto the
+ *   final name fails the open) and O_NONBLOCK (a FIFO cannot hang the open);
+ * - the descriptor must be a regular file within the size limit (fstat);
+ * - the descriptor's real location (/proc/self/fd/N on Linux; elsewhere the
+ *   re-resolved realpath, which must be the same inode) must lie inside the
+ *   project root, so a directory component swapped for a symlink is caught;
+ * - the content is read from that same descriptor, and never past the limit,
+ *   even if the file grows after the fstat.
+ *
+ * A path spelled outside the root is refused before any filesystem call,
+ * unless the caller opts into `outsideRoot: 'allow'` for paths it accepts
+ * from a trusted source (the other checks still apply).
+ */
+import { constants as fsConstants } from 'node:fs';
+import * as fsSync from 'node:fs';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { findProjectRoot } from '../../kernel/project-root.js';
+import { CallerInputError } from '../error-utils.js';
+/** Default upper bound for a confined read when the caller names none. */
+export const DEFAULT_MAX_CONFINED_READ_BYTES = 128 * 1024 * 1024;
+/**
+ * A confined read that was refused; `reason` matches the payload guard's.
+ * `code` is the errno code when the filesystem gave one (ENOENT, ELOOP, ...),
+ * otherwise the reason in errno style (OUTSIDE_PROJECT_ROOT, NOT_A_FILE,
+ * TOO_LARGE), so callers that report error codes keep working.
+ */
+export class ConfinedReadError extends CallerInputError {
+    filePath;
+    reason;
+    code;
+    constructor(filePath, reason, errnoCode) {
+        super(`Cannot read ${filePath}: ${reason}`);
+        this.filePath = filePath;
+        this.reason = reason;
+        this.name = 'ConfinedReadError';
+        this.code = errnoCode ?? reason.toUpperCase().replace(/-/g, '_');
+    }
+}
+/** Flags for opening a checked realpath: read-only, no final symlink, no FIFO wait. */
+export const CONFINED_OPEN_FLAGS = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0);
+/** True when `candidate` is `root` or lies beneath it (both absolute). */
+export function isWithinRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+/**
+ * Where an OPEN descriptor really points. On Linux, /proc/self/fd/N resolves
+ * to the opened file itself. Elsewhere, re-resolve the path and accept it only
+ * if it is the same inode as the descriptor, so a swap after the open is
+ * detected. Returns null when it cannot be proven.
+ */
+export async function openedLocation(fd, lexical, opened) {
+    const sameFile = async (candidate) => {
+        const st = await fs.stat(candidate).catch(() => null);
+        return st !== null && st.dev === opened.dev && st.ino === opened.ino;
+    };
+    const viaProc = await fs.realpath(`/proc/self/fd/${fd}`).catch(() => null);
+    if (viaProc && path.isAbsolute(viaProc) && await sameFile(viaProc))
+        return viaProc;
+    const real = await fs.realpath(lexical).catch(() => null);
+    if (real && await sameFile(real))
+        return real;
+    return null;
+}
+/** Synchronous openedLocation, for callers that read synchronously. */
+export function openedLocationSync(fd, lexical, opened) {
+    const sameFile = (candidate) => {
+        try {
+            const st = fsSync.statSync(candidate);
+            return st.dev === opened.dev && st.ino === opened.ino;
+        }
+        catch {
+            return false;
+        }
+    };
+    const realOrNull = (p) => {
+        try {
+            return fsSync.realpathSync(p);
+        }
+        catch {
+            return null;
+        }
+    };
+    const viaProc = realOrNull(`/proc/self/fd/${fd}`);
+    if (viaProc && path.isAbsolute(viaProc) && sameFile(viaProc))
+        return viaProc;
+    const real = realOrNull(lexical);
+    if (real && sameFile(real))
+        return real;
+    return null;
+}
+function reasonFor(error) {
+    const code = error?.code;
+    if (code === 'ENOENT' || code === 'ENOTDIR')
+        return 'not-found';
+    // ELOOP: a symlink was swapped onto the checked realpath's final name.
+    if (code === 'EISDIR' || code === 'ELOOP')
+        return 'not-a-file';
+    return 'unreadable';
+}
+function fail(filePath, reason, error) {
+    return new ConfinedReadError(filePath, reason, error?.code);
+}
+function plan(filePath, rootReal, options) {
+    if (typeof filePath !== 'string' || filePath === '' || filePath.includes('\0')) {
+        throw fail(String(filePath), 'unreadable');
+    }
+    const rootLexical = path.resolve(options.projectRoot ?? findProjectRoot());
+    const lexical = path.resolve(filePath);
+    const inRoot = isWithinRoot(rootLexical, lexical) || isWithinRoot(rootReal, lexical);
+    // Spelled outside the root: refused before any filesystem call, so the
+    // reason cannot reveal whether an outside path exists.
+    if (!inRoot && options.outsideRoot !== 'allow')
+        throw fail(filePath, 'outside-project-root');
+    return { lexical, rootReal, inRoot, limit: options.maxBytes ?? DEFAULT_MAX_CONFINED_READ_BYTES };
+}
+/** Check the opened descriptor's stat before anything is read. */
+function checkOpened(filePath, st, limit) {
+    if (!st.isFile())
+        throw fail(filePath, 'not-a-file');
+    if (st.size > limit)
+        throw fail(filePath, 'too-large');
+}
+/**
+ * Read a file by path, confined to the project root and validated on the
+ * opened descriptor (see the module comment). Throws ConfinedReadError.
+ */
+export async function readConfinedFile(filePath, options = {}) {
+    const root = path.resolve(options.projectRoot ?? findProjectRoot());
+    const rootReal = await fs.realpath(root).catch(() => root);
+    const p = plan(filePath, rootReal, options);
+    let real;
+    try {
+        real = await fs.realpath(p.lexical);
+    }
+    catch (error) {
+        throw fail(filePath, reasonFor(error), error);
+    }
+    if (p.inRoot && !isWithinRoot(p.rootReal, real))
+        throw fail(filePath, 'outside-project-root');
+    let handle;
+    try {
+        handle = await fs.open(real, CONFINED_OPEN_FLAGS);
+    }
+    catch (error) {
+        throw fail(filePath, reasonFor(error), error);
+    }
+    try {
+        const st = await handle.stat();
+        checkOpened(filePath, st, p.limit);
+        if (p.inRoot) {
+            const location = await openedLocation(handle.fd, real, st);
+            if (!location || !isWithinRoot(p.rootReal, location))
+                throw fail(filePath, 'outside-project-root');
+        }
+        // Read at most limit + 1 bytes from this descriptor: a file that grew
+        // after the fstat is refused rather than read without bound.
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, p.limit + 1 - total));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+            if (bytesRead === 0)
+                break;
+            chunks.push(chunk.subarray(0, bytesRead));
+            total += bytesRead;
+            if (total > p.limit)
+                throw fail(filePath, 'too-large');
+        }
+        return Buffer.concat(chunks, total);
+    }
+    catch (error) {
+        if (error instanceof ConfinedReadError)
+            throw error;
+        throw fail(filePath, reasonFor(error), error);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+/** readConfinedFile decoded as UTF-8. */
+export async function readConfinedText(filePath, options = {}) {
+    return (await readConfinedFile(filePath, options)).toString('utf-8');
+}
+/** Synchronous readConfinedFile, for callers that cannot await. */
+export function readConfinedFileSync(filePath, options = {}) {
+    const root = path.resolve(options.projectRoot ?? findProjectRoot());
+    let rootReal = root;
+    try {
+        rootReal = fsSync.realpathSync(root);
+    }
+    catch { /* keep the lexical root */ }
+    const p = plan(filePath, rootReal, options);
+    let real;
+    try {
+        real = fsSync.realpathSync(p.lexical);
+    }
+    catch (error) {
+        throw fail(filePath, reasonFor(error), error);
+    }
+    if (p.inRoot && !isWithinRoot(p.rootReal, real))
+        throw fail(filePath, 'outside-project-root');
+    let fd;
+    try {
+        fd = fsSync.openSync(real, CONFINED_OPEN_FLAGS);
+    }
+    catch (error) {
+        throw fail(filePath, reasonFor(error), error);
+    }
+    try {
+        const st = fsSync.fstatSync(fd);
+        checkOpened(filePath, st, p.limit);
+        if (p.inRoot) {
+            const location = openedLocationSync(fd, real, st);
+            if (!location || !isWithinRoot(p.rootReal, location))
+                throw fail(filePath, 'outside-project-root');
+        }
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, p.limit + 1 - total));
+            const bytesRead = fsSync.readSync(fd, chunk, 0, chunk.length, null);
+            if (bytesRead === 0)
+                break;
+            chunks.push(chunk.subarray(0, bytesRead));
+            total += bytesRead;
+            if (total > p.limit)
+                throw fail(filePath, 'too-large');
+        }
+        return Buffer.concat(chunks, total);
+    }
+    catch (error) {
+        if (error instanceof ConfinedReadError)
+            throw error;
+        throw fail(filePath, reasonFor(error), error);
+    }
+    finally {
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch { /* already closed */ }
+    }
+}
+/** readConfinedFileSync decoded as UTF-8. */
+export function readConfinedTextSync(filePath, options = {}) {
+    return readConfinedFileSync(filePath, options).toString('utf-8');
+}
+//# sourceMappingURL=confined-read.js.map

package/dist/shared/io/file-reader.d.ts

@@ -74,12 +74,12 @@ export declare class FileReader {
      */
     private inProjectRoot;
     /**
-     * #1021 round 2b: read an in-root path without a check-then-use race.
-     * The file is OPENED first and the open descriptor is verified — its real
-     * location (/proc/self/fd/N on Linux; otherwise the re-resolved realpath,
-     * which must be the same inode) must lie inside the root — and the content
-     * is read from that same descriptor. Swapping a symlink (file or directory
-     * component) between the check and the read can no longer redirect it.
+     * #1021 round 2b / #1161: read an in-root path without a check-then-use
+     * race. readConfinedText opens the path once and verifies the opened
+     * descriptor (a regular file whose real location lies inside the root) and
+     * reads from that same descriptor, so swapping a symlink (file or directory
+     * component) between a check and the read cannot redirect it, and a FIFO or
+     * device cannot hang or flood the read.
      */
     private readContained;
     /**

package/dist/shared/io/file-reader.js

@@ -7,6 +7,7 @@ import * as path from 'node:path';
 import { ok, err } from '../types/index.js';
 import { validatePath } from '../security/path-traversal-validator.js';
 import { safeJsonParse } from '../safe-json.js';
+import { ConfinedReadError, readConfinedText } from './confined-read.js';
 /** Extensions never read, inside or outside the project root. */
 const DENIED_EXTENSIONS = ['.exe', '.bat', '.cmd', '.ps1', '.dll', '.so'];
 export class FileReadError extends Error {
@@ -65,25 +66,6 @@ function readError(error, absolutePath) {
     }
     return new FileReadError(message, absolutePath, nodeError.code, nodeError);
 }
-/**
- * #1021 round 2b: where an OPEN descriptor really points. On Linux,
- * /proc/self/fd/N resolves to the opened file itself. Elsewhere, re-resolve
- * the path and accept it only if it is the same inode as the descriptor, so
- * a swap after the open is detected. Returns null when it cannot be proven.
- */
-async function openedLocation(fd, lexical, opened) {
-    const sameFile = async (candidate) => {
-        const st = await fs.stat(candidate).catch(() => null);
-        return st !== null && st.dev === opened.dev && st.ino === opened.ino;
-    };
-    const viaProc = await fs.realpath(`/proc/self/fd/${fd}`).catch(() => null);
-    if (viaProc && path.isAbsolute(viaProc) && await sameFile(viaProc))
-        return viaProc;
-    const real = await fs.realpath(lexical).catch(() => null);
-    if (real && await sameFile(real))
-        return real;
-    return null;
-}
 /** True when `candidate` is `root` or lies beneath it (both absolute). */
 function isWithin(root, candidate) {
     const relative = path.relative(root, candidate);
@@ -341,38 +323,30 @@ export class FileReader {
         return { lexical, rootReal };
     }
     /**
-     * #1021 round 2b: read an in-root path without a check-then-use race.
-     * The file is OPENED first and the open descriptor is verified — its real
-     * location (/proc/self/fd/N on Linux; otherwise the re-resolved realpath,
-     * which must be the same inode) must lie inside the root — and the content
-     * is read from that same descriptor. Swapping a symlink (file or directory
-     * component) between the check and the read can no longer redirect it.
+     * #1021 round 2b / #1161: read an in-root path without a check-then-use
+     * race. readConfinedText opens the path once and verifies the opened
+     * descriptor (a regular file whose real location lies inside the root) and
+     * reads from that same descriptor, so swapping a symlink (file or directory
+     * component) between a check and the read cannot redirect it, and a FIFO or
+     * device cannot hang or flood the read.
      */
     async readContained(filePath, lexical, rootReal) {
         this.stats.totalReads++;
-        let handle;
         try {
-            handle = await fs.open(lexical, 'r');
+            // The lexical root, so a path spelled under a symlinked root still
+            // counts as inside; the primitive resolves the root's realpath itself.
+            return ok(await readConfinedText(lexical, { projectRoot: this.projectRoot ?? rootReal }));
         }
         catch (error) {
-            return err(readError(error, lexical));
-        }
-        try {
-            const opened = await handle.stat();
-            const location = await openedLocation(handle.fd, lexical, opened);
-            if (!location || !isWithin(rootReal, location)) {
+            if (!(error instanceof ConfinedReadError))
+                return err(readError(error, lexical));
+            if (error.reason === 'outside-project-root') {
                 return err(new PathTraversalError(filePath, ['Path resolves outside the project root'], 'critical'));
             }
-            if (!opened.isFile()) {
-                return err(new FileReadError('Path is a directory: ' + lexical, lexical, 'EISDIR'));
+            if (error.reason === 'not-a-file') {
+                return err(new FileReadError('Not a regular file: ' + lexical, lexical, error.code === 'NOT_A_FILE' ? 'EISDIR' : error.code));
             }
-            return ok(await handle.readFile('utf-8'));
-        }
-        catch (error) {
-            return err(readError(error, lexical));
-        }
-        finally {
-            await handle.close().catch(() => undefined);
+            return err(readError({ code: error.reason === 'not-found' ? 'ENOENT' : error.code }, lexical));
         }
     }
     /**