agentic-qe 3.15.1 → 3.15.3

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

@@ -6,17 +6,35 @@
  * 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
  */
 import { randomUUID } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import { findProjectRoot } from '../../kernel/project-root.js';
+import { SessionWriteBuffer, encodeEntry } from './session-write-buffer.js';
 // ============================================================================
 // Session Store
 // ============================================================================
 const DEFAULT_SESSION_DIR = '.agentic-qe/sessions';
 const BATCH_FLUSH_MS = 100;
+const DEFAULT_MAX_BUFFERED_ENTRIES = 10_000;
+// Matches the largest transcript session-resume will read.
+const DEFAULT_MAX_BUFFERED_BYTES = 16 * 1024 * 1024;
+function positiveLimit(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`SessionStore ${name} must be a positive integer, got ${value}`);
+    }
+    return value;
+}
 export class SessionStore {
     sessionDir;
     sessionId = null;
@@ -27,13 +45,20 @@ export class SessionStore {
     createdAt = 0;
     lastActivityAt = 0;
     currentState = 'idle';
-    writeBuffer = [];
+    /** Lines not yet fully on disk, oldest first. */
+    writeBuffer;
+    dropWarned = false;
+    maxBufferedEntries;
+    maxBufferedBytes;
     flushTimer = null;
     closed = false;
     // Database-free mode (#534): keep session bookkeeping in memory but never
     // write .agentic-qe/sessions/*.jsonl to disk.
     persistDisabled = process.env.AQE_MEMORY_BACKEND === 'memory';
-    constructor(sessionDir) {
+    constructor(sessionDir, options = {}) {
+        this.maxBufferedEntries = positiveLimit('maxBufferedEntries', options.maxBufferedEntries, DEFAULT_MAX_BUFFERED_ENTRIES);
+        this.maxBufferedBytes = positiveLimit('maxBufferedBytes', options.maxBufferedBytes, DEFAULT_MAX_BUFFERED_BYTES);
+        this.writeBuffer = this.createWriteBuffer();
         // #735: a cwd-relative default created `<subdir>/.agentic-qe/sessions`
         // on the first MCP tool call, which later runs then adopted as the
         // nearest project store. Anchor the default at the project root.
@@ -55,7 +80,8 @@ export class SessionStore {
         this.createdAt = Date.now();
         this.lastActivityAt = this.createdAt;
         this.currentState = 'idle';
-        this.writeBuffer = [];
+        this.writeBuffer = this.createWriteBuffer();
+        this.dropWarned = false;
         this.flushTimer = null;
         this.closed = false;
         return this.sessionId;
@@ -65,7 +91,7 @@ export 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.
@@ -82,24 +108,37 @@ export class SessionStore {
         };
         // Database-free mode keeps bookkeeping without serialization or disk I/O.
         if (!this.persistDisabled) {
-            const line = JSON.stringify(fullEntry) + '\n';
+            const line = encodeEntry(fullEntry);
             if (!this.fileCreated) {
                 // First write: synchronous for write-ahead guarantee
                 this.ensureDirectory();
-                fs.appendFileSync(this.filePath, line, 'utf-8');
+                this.writeBuffer.push(fullEntry, line);
+                try {
+                    this.writePending();
+                }
+                catch (error) {
+                    if (!this.writeBuffer.hasPartialHead) {
+                        // Nothing reached the disk: reject the entry and leave the chain as it was.
+                        this.writeBuffer.popNewest();
+                        throw error;
+                    }
+                    // Part of the line is on disk. Keep it so a retry completes the record
+                    // rather than leaving a torn prefix for the next line to glue onto.
+                    this.fileCreated = true;
+                    this.accept(fullEntry);
+                    this.scheduleBatchFlush();
+                    throw error;
+                }
                 this.fileCreated = true;
             }
             else {
                 // Subsequent writes: buffer and batch
-                this.writeBuffer.push(line);
+                this.writeBuffer.push(fullEntry, line);
                 this.scheduleBatchFlush();
             }
         }
         // Only advance the chain and metadata after the entry has been accepted.
-        this.lastUuid = uuid;
-        this.entryCount++;
-        this.lastActivityAt = fullEntry.timestamp;
-        this.currentState = fullEntry.state;
+        this.accept(fullEntry);
         return uuid;
     }
     /**
@@ -110,12 +149,20 @@ export class SessionStore {
             clearTimeout(this.flushTimer);
             this.flushTimer = null;
         }
-        if (this.writeBuffer.length > 0 && this.filePath && this.fileCreated) {
-            const batch = this.writeBuffer.join('');
-            fs.appendFileSync(this.filePath, batch, 'utf-8');
-            this.writeBuffer = [];
+        if (this.fileCreated) {
+            this.writePending();
         }
     }
+    /**
+     * Size of the unwritten backlog and how many entries the cap has dropped.
+     */
+    getWriteBufferStats() {
+        return {
+            bufferedEntries: this.writeBuffer.size,
+            bufferedBytes: this.writeBuffer.bufferedBytes,
+            droppedEntries: this.writeBuffer.droppedEntries,
+        };
+    }
     /**
      * Returns metadata about the current session.
      */
@@ -162,6 +209,28 @@ export class SessionStore {
             fs.mkdirSync(dir, { recursive: true });
         }
     }
+    accept(entry) {
+        this.lastUuid = entry.uuid;
+        this.entryCount++;
+        this.lastActivityAt = entry.timestamp;
+        this.currentState = entry.state;
+    }
+    writePending() {
+        if (this.filePath)
+            this.writeBuffer.writeTo(this.filePath);
+    }
+    createWriteBuffer() {
+        return new SessionWriteBuffer(this.maxBufferedEntries, this.maxBufferedBytes, () => {
+            if (this.dropWarned)
+                return;
+            this.dropWarned = true;
+            // "[AQE] WARN" passes the MCP entry's stderr filter.
+            console.error(`[AQE] WARN session journal ${this.filePath}: writes keep failing and the buffer reached its cap `
+                + `(${this.maxBufferedEntries} entries / ${this.maxBufferedBytes} bytes). The oldest unwritten entries `
+                + 'are replaced by one gap marker: their content is lost, but the transcript stays resumable. '
+                + 'The dropped count is in getWriteBufferStats() and in the marker.');
+        });
+    }
     scheduleBatchFlush() {
         if (this.flushTimer === null) {
             this.flushTimer = setTimeout(() => {

package/dist/mcp/services/session-write-buffer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Bounded, progress-tracking write buffer for the JSONL session journal (#910).
+ *
+ * - Writes track byte progress, so a write that fails partway (ENOSPC, EIO)
+ *   resumes where it stopped instead of re-appending what reached the disk.
+ * - While writes keep failing, the backlog is capped. The oldest unwritten
+ *   entries are replaced by one `state_change` gap marker that reuses the last
+ *   dropped entry's uuid and the first dropped entry's parentUuid, so the
+ *   parentUuid chain on disk stays valid and session-resume still accepts it.
+ *
+ * @module mcp/services/session-write-buffer
+ */
+import type { SessionEntry } from './session-store';
+/** `result` payload of a gap marker entry. */
+export interface JournalGap {
+    droppedEntries: number;
+    reason: string;
+}
+export declare function encodeEntry(entry: SessionEntry): Buffer;
+export declare class SessionWriteBuffer {
+    private readonly maxEntries;
+    private readonly maxBytes;
+    /** Called once per drop event with the running dropped total. */
+    private readonly onDrop;
+    private lines;
+    /** Bytes of lines[0] already on disk after a write that failed partway. */
+    private headWritten;
+    private bytes;
+    private dropped;
+    constructor(maxEntries: number, maxBytes: number, 
+    /** Called once per drop event with the running dropped total. */
+    onDrop: (droppedTotal: number) => void);
+    get size(): number;
+    get bufferedBytes(): number;
+    get droppedEntries(): number;
+    /** True when part of the oldest line is already on disk. */
+    get hasPartialHead(): boolean;
+    push(entry: SessionEntry, data?: Buffer): void;
+    /** Remove the newest line (an entry whose first write put nothing on disk). */
+    popNewest(): void;
+    /**
+     * Append every buffered line with one write loop over a single buffer, then
+     * map the bytes written back onto line boundaries. On failure only the
+     * unwritten remainder stays buffered.
+     */
+    writeTo(filePath: string): void;
+    /** Drop the lines fully covered by `offset` bytes and keep partial progress. */
+    private settle;
+    /**
+     * Replace the oldest droppable lines with one gap marker until both caps hold.
+     * The newest line and a partially written head line are never dropped.
+     */
+    private enforceCaps;
+}
+//# sourceMappingURL=session-write-buffer.d.ts.map

package/dist/mcp/services/session-write-buffer.js

@@ -0,0 +1,144 @@
+/**
+ * Bounded, progress-tracking write buffer for the JSONL session journal (#910).
+ *
+ * - Writes track byte progress, so a write that fails partway (ENOSPC, EIO)
+ *   resumes where it stopped instead of re-appending what reached the disk.
+ * - While writes keep failing, the backlog is capped. The oldest unwritten
+ *   entries are replaced by one `state_change` gap marker that reuses the last
+ *   dropped entry's uuid and the first dropped entry's parentUuid, so the
+ *   parentUuid chain on disk stays valid and session-resume still accepts it.
+ *
+ * @module mcp/services/session-write-buffer
+ */
+import * as fs from 'fs';
+const GAP_REASON = 'write buffer cap reached while the session journal could not be written';
+// Upper bound on a gap marker line, used while choosing how many lines to drop.
+const GAP_MARKER_MAX_BYTES = 512;
+export function encodeEntry(entry) {
+    return Buffer.from(JSON.stringify(entry) + '\n', 'utf-8');
+}
+export class SessionWriteBuffer {
+    maxEntries;
+    maxBytes;
+    onDrop;
+    lines = [];
+    /** Bytes of lines[0] already on disk after a write that failed partway. */
+    headWritten = 0;
+    bytes = 0;
+    dropped = 0;
+    constructor(maxEntries, maxBytes, 
+    /** Called once per drop event with the running dropped total. */
+    onDrop) {
+        this.maxEntries = maxEntries;
+        this.maxBytes = maxBytes;
+        this.onDrop = onDrop;
+    }
+    get size() { return this.lines.length; }
+    get bufferedBytes() { return this.bytes; }
+    get droppedEntries() { return this.dropped; }
+    /** True when part of the oldest line is already on disk. */
+    get hasPartialHead() { return this.headWritten > 0; }
+    push(entry, data = encodeEntry(entry)) {
+        this.lines.push({
+            data, uuid: entry.uuid, parentUuid: entry.parentUuid,
+            timestamp: entry.timestamp, state: entry.state, represents: 1,
+        });
+        this.bytes += data.length;
+        this.enforceCaps();
+    }
+    /** Remove the newest line (an entry whose first write put nothing on disk). */
+    popNewest() {
+        const line = this.lines.pop();
+        if (line)
+            this.bytes -= line.data.length;
+    }
+    /**
+     * Append every buffered line with one write loop over a single buffer, then
+     * map the bytes written back onto line boundaries. On failure only the
+     * unwritten remainder stays buffered.
+     */
+    writeTo(filePath) {
+        if (this.lines.length === 0)
+            return;
+        const pending = Buffer.concat(this.lines.map(line => line.data));
+        let offset = this.headWritten;
+        const fd = fs.openSync(filePath, 'a');
+        try {
+            while (offset < pending.length) {
+                const count = fs.writeSync(fd, pending, offset, pending.length - offset);
+                if (count <= 0)
+                    throw new Error(`session journal write made no progress: ${filePath}`);
+                offset += count;
+            }
+        }
+        finally {
+            this.settle(offset);
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // The bytes were handed to the kernel already; a write error, if any,
+                // is the one worth reporting.
+            }
+        }
+    }
+    /** Drop the lines fully covered by `offset` bytes and keep partial progress. */
+    settle(offset) {
+        let completed = 0;
+        let consumed = 0;
+        while (completed < this.lines.length && consumed + this.lines[completed].data.length <= offset) {
+            consumed += this.lines[completed].data.length;
+            completed++;
+        }
+        if (completed > 0) {
+            this.lines.splice(0, completed);
+            this.bytes -= consumed;
+        }
+        this.headWritten = offset - consumed;
+    }
+    /**
+     * Replace the oldest droppable lines with one gap marker until both caps hold.
+     * The newest line and a partially written head line are never dropped.
+     */
+    enforceCaps() {
+        const start = this.headWritten > 0 ? 1 : 0;
+        const newest = this.lines.length - 1;
+        let end = start;
+        let removedBytes = 0;
+        const over = () => {
+            const removed = end - start;
+            const marker = removed > 0 ? 1 : 0;
+            return this.lines.length - removed + marker > this.maxEntries
+                || this.bytes - removedBytes + marker * GAP_MARKER_MAX_BYTES > this.maxBytes;
+        };
+        if (!over())
+            return;
+        while (end < newest && over()) {
+            removedBytes += this.lines[end].data.length;
+            end++;
+        }
+        // Swapping a single line for a marker frees nothing (caps below 2 lines).
+        if (end - start < 2)
+            return;
+        const run = this.lines.slice(start, end);
+        const first = run[0];
+        const last = run[run.length - 1];
+        const represents = run.reduce((sum, line) => sum + line.represents, 0);
+        // An earlier marker inside the run was already counted.
+        const newlyDropped = run.filter(line => line.represents === 1).length;
+        const gap = { droppedEntries: represents, reason: GAP_REASON };
+        const markerEntry = {
+            uuid: last.uuid, parentUuid: first.parentUuid, timestamp: last.timestamp,
+            type: 'state_change', state: last.state, result: { journalGap: gap },
+        };
+        const data = encodeEntry(markerEntry);
+        this.lines.splice(start, run.length, {
+            data, uuid: last.uuid, parentUuid: first.parentUuid,
+            timestamp: last.timestamp, state: last.state, represents,
+        });
+        this.bytes += data.length - removedBytes;
+        this.dropped += newlyDropped;
+        this.onDrop(this.dropped);
+    }
+}
+//# sourceMappingURL=session-write-buffer.js.map

package/dist/mcp/types.d.ts

@@ -178,6 +178,11 @@ export interface TestGenerateParams {
     behaviorExamples?: import('../domains/test-generation/interfaces').BehaviorExample[];
     aiEnhancement?: boolean;
     detectAntiPatterns?: boolean;
+    /**
+     * #925: write a manifest and report under .agentic-qe/results/tests/
+     * (default true). false generates without writing any result files.
+     */
+    saveResults?: boolean;
 }
 /**
  * Test execution parameters
@@ -477,6 +482,10 @@ export interface TestGenerateResult {
     antiPatternsDetected?: number;
     suggestions?: string[];
     savedFiles?: string[];
+    /** #925: true when result files were written; see savedFiles for their paths. */
+    resultsSaved?: boolean;
+    /** #925: plain statement of what was (or was not) written to disk. */
+    resultsNote?: string;
     patternsUsed?: string[];
     /**
      * #567: true when the ADR-051 LLM branch actually ran. When false the tests

package/dist/memory/crdt/g-counter.js

@@ -7,6 +7,7 @@
  *
  * @module memory/crdt/g-counter
  */
+import { addToCount, createSafeRecord, getOwn, setOwn } from '../../shared/utils/safe-record.js';
 // =============================================================================
 // G-Counter Implementation
 // =============================================================================
@@ -27,12 +28,13 @@
 export function createGCounter(nodeId) {
     // Internal state: per-node counts
     const state = {
-        counts: {},
+        // Node ids are data: keep them off Object.prototype (#914).
+        counts: createSafeRecord(),
         version: 0,
         lastUpdated: Date.now(),
     };
     // Initialize this node's count
-    state.counts[nodeId] = 0;
+    setOwn(state.counts, nodeId, 0);
     return {
         get() {
             // Sum all node counts
@@ -45,7 +47,7 @@ export function createGCounter(nodeId) {
             if (n === 0) {
                 return;
             }
-            state.counts[nodeId] = (state.counts[nodeId] || 0) + n;
+            addToCount(state.counts, nodeId, n);
             state.version++;
             state.lastUpdated = Date.now();
         },
@@ -56,7 +58,7 @@ export function createGCounter(nodeId) {
         getState() {
             // Return a deep copy to prevent external mutation
             return {
-                counts: { ...state.counts },
+                counts: Object.assign(createSafeRecord(), state.counts),
                 version: state.version,
                 lastUpdated: state.lastUpdated,
             };
@@ -65,9 +67,9 @@ export function createGCounter(nodeId) {
             let changed = false;
             // Merge counts: take max for each node
             for (const [incomingNodeId, incomingCount] of Object.entries(incoming.counts)) {
-                const currentCount = state.counts[incomingNodeId] || 0;
+                const currentCount = getOwn(state.counts, incomingNodeId) ?? 0;
                 if (incomingCount > currentCount) {
-                    state.counts[incomingNodeId] = incomingCount;
+                    setOwn(state.counts, incomingNodeId, incomingCount);
                     changed = true;
                 }
             }
@@ -80,7 +82,7 @@ export function createGCounter(nodeId) {
             return nodeId;
         },
         getLocalCount() {
-            return state.counts[nodeId] || 0;
+            return getOwn(state.counts, nodeId) ?? 0;
         },
     };
 }
@@ -123,7 +125,7 @@ export function isGCounterState(value) {
  * Get the count for a specific node from state
  */
 export function getNodeCountFromState(state, nodeId) {
-    return state.counts[nodeId] || 0;
+    return getOwn(state.counts, nodeId) ?? 0;
 }
 /**
  * Get all contributing nodes from state

package/dist/shared/embeddings/ollama-client.d.ts

@@ -21,7 +21,7 @@ export declare class OllamaClient {
      */
     generateEmbedding(prompt: string): Promise<number[]>;
     /**
-     * Fetch with timeout support
+     * Keep the request timeout active through required body consumption.
      */
     private fetchWithTimeout;
     /**

package/dist/shared/embeddings/ollama-client.js

@@ -24,24 +24,24 @@ export class OllamaClient {
      */
     async healthCheck() {
         try {
-            const response = await this.fetchWithTimeout(`${this.baseUrl}/api/tags`, {
+            return await this.fetchWithTimeout(`${this.baseUrl}/api/tags`, {
                 method: 'GET',
                 headers: { 'Content-Type': 'application/json' },
-            }, 5000 // Shorter timeout for health check
-            );
-            if (!response.ok) {
+            }, 5000, // Shorter timeout for health check
+            async (response) => {
+                if (!response.ok)
+                    return false;
+                const data = await response.json();
+                // Check if configured embedding model is available
+                // Match the configured model exactly, allowing its existing tag suffix.
+                if (data.models) {
+                    return data.models.some((model) => model.name === EMBEDDING_CONFIG.MODEL ||
+                        model.name?.startsWith(`${EMBEDDING_CONFIG.MODEL}:`) ||
+                        model.model === EMBEDDING_CONFIG.MODEL ||
+                        model.model?.startsWith(`${EMBEDDING_CONFIG.MODEL}:`));
+                }
                 return false;
-            }
-            const data = await response.json();
-            // Check if configured embedding model is available
-            // Match the configured model exactly, allowing its existing tag suffix.
-            if (data.models) {
-                return data.models.some((model) => model.name === EMBEDDING_CONFIG.MODEL ||
-                    model.name?.startsWith(`${EMBEDDING_CONFIG.MODEL}:`) ||
-                    model.model === EMBEDDING_CONFIG.MODEL ||
-                    model.model?.startsWith(`${EMBEDDING_CONFIG.MODEL}:`));
-            }
-            return false;
+            });
         }
         catch {
             return false;
@@ -58,16 +58,17 @@ export class OllamaClient {
         let lastError = null;
         for (let attempt = 0; attempt < this.maxRetries; attempt++) {
             try {
-                const response = await this.fetchWithTimeout(`${this.baseUrl}/api/embeddings`, {
+                const data = await this.fetchWithTimeout(`${this.baseUrl}/api/embeddings`, {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json' },
                     body: JSON.stringify(request),
-                }, this.timeoutMs);
-                if (!response.ok) {
-                    const errorText = await response.text();
-                    throw new Error(`Ollama API error (${response.status}): ${errorText}`);
-                }
-                const data = await response.json();
+                }, this.timeoutMs, async (response) => {
+                    if (!response.ok) {
+                        const errorText = await response.text();
+                        throw new Error(`Ollama API error (${response.status}): ${errorText}`);
+                    }
+                    return await response.json();
+                });
                 // Validate embedding dimensions
                 if (data.embedding.length !== EMBEDDING_CONFIG.DIMENSIONS) {
                     throw new Error(`Invalid embedding dimensions: expected ${EMBEDDING_CONFIG.DIMENSIONS}, got ${data.embedding.length}`);
@@ -90,9 +91,9 @@ export class OllamaClient {
         throw new Error(`Failed to generate embedding after ${this.maxRetries} attempts: ${lastError?.message}`);
     }
     /**
-     * Fetch with timeout support
+     * Keep the request timeout active through required body consumption.
      */
-    async fetchWithTimeout(url, options, timeoutMs) {
+    async fetchWithTimeout(url, options, timeoutMs, consume) {
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
         try {
@@ -100,7 +101,7 @@ export class OllamaClient {
                 ...options,
                 signal: controller.signal,
             });
-            return response;
+            return await consume(response);
         }
         finally {
             clearTimeout(timeoutId);
@@ -117,14 +118,12 @@ export class OllamaClient {
      */
     async getServerInfo() {
         try {
-            const response = await this.fetchWithTimeout(`${this.baseUrl}/api/tags`, {
+            return await this.fetchWithTimeout(`${this.baseUrl}/api/tags`, {
                 method: 'GET',
                 headers: { 'Content-Type': 'application/json' },
-            }, 5000);
-            if (!response.ok) {
-                return null;
-            }
-            return await response.json();
+            }, 5000, async (response) => response.ok
+                ? await response.json()
+                : null);
         }
         catch {
             return null;

package/dist/shared/git/git-analyzer.d.ts

@@ -102,8 +102,11 @@ export declare class GitAnalyzer {
     getChangedFiles(since?: Date): Promise<string[]>;
     /**
      * Get files changed in a specific commit
-     * @param commitHash - Git commit hash (default: HEAD)
+     * @param commitHash - Git revision (SHA, `HEAD~3`, `origin/main`, tag; default: HEAD)
      * @returns Array of changed file paths relative to repo root
+     * @throws Error when `commitHash` is option-shaped (starts with "-") or otherwise
+     *   not a safe revision argument; git would otherwise parse it as an option
+     *   (e.g. `--output=<path>` writes an arbitrary file). See issue #960.
      */
     getCommitFiles(commitHash?: string): Promise<string[]>;
     /**

package/dist/shared/git/git-analyzer.js

@@ -10,6 +10,7 @@
  */
 import { execFileSync } from 'child_process';
 import * as path from 'path';
+import { assertSafeGitRef } from './ref-validation.js';
 /**
  * Sanitize a string for safe use in git arguments
  * Removes shell metacharacters that could enable injection
@@ -432,18 +433,22 @@ export class GitAnalyzer {
     }
     /**
      * Get files changed in a specific commit
-     * @param commitHash - Git commit hash (default: HEAD)
+     * @param commitHash - Git revision (SHA, `HEAD~3`, `origin/main`, tag; default: HEAD)
      * @returns Array of changed file paths relative to repo root
+     * @throws Error when `commitHash` is option-shaped (starts with "-") or otherwise
+     *   not a safe revision argument; git would otherwise parse it as an option
+     *   (e.g. `--output=<path>` writes an arbitrary file). See issue #960.
      */
     async getCommitFiles(commitHash = 'HEAD') {
+        // Validate before touching git: execFileSync has no shell, so stripping
+        // metacharacters does not help, but a leading "-" is still parsed as an option.
+        assertSafeGitRef(commitHash, 'commit hash');
         if (!(await this.isGitRepository())) {
             return [];
         }
         try {
-            // Sanitize commit hash to prevent injection
-            const sanitizedHash = sanitizeGitArg(commitHash);
             const output = execFileSync('git', [
-                'diff-tree', '--no-commit-id', '--name-only', '-z', '-r', sanitizedHash
+                'diff-tree', '--root', '--no-commit-id', '--name-only', '-z', '-r', commitHash
             ], {
                 cwd: this.config.repoRoot,
                 encoding: 'utf-8',