@thegitai/cli 1.0.0-beta.2 → 1.0.0-beta.21

package/dist/src/tool-executor.js

@@ -1,8 +1,12 @@
+import { drainBackgroundJobNotifications, getBackgroundJob, } from './background-jobs.js';
 import { canStoreEditSnapshot, isEditToolName, isGitWorkTree, MAX_EDIT_JOURNAL_RECORDS, operationFromSnapshots, readFileEditSnapshot, } from './edit-journal.js';
 import { clearEditFailure, collectCommandMutations, captureMutationBaseline, ensureActiveCheckpoint, recordEditFailure, recordSessionEdit, rememberCheckpointFiles, } from './session-safety.js';
 import { buildAgentModeToolBlockedResult, } from './agent-mode.js';
 import { dispatchTool } from './tools/index.js';
+import { syncIndexFromDisk } from './project-index.js';
+import { PATH_REPAIRING_EDIT_TOOLS, repairFilePath } from './tools/path-suggest.js';
 import { invalidateShellDiagnosticsCache, runShellDiagnostics, } from './tools/shell-diagnostics.js';
+import { extractTodosArg } from './todo-list.js';
 const EDIT_FILE_PATH_ARG_ALIASES = [
     'filePath',
     'file_path',
@@ -11,6 +15,7 @@ const EDIT_FILE_PATH_ARG_ALIASES = [
     'file',
     'filename',
 ];
+const backgroundCommandTrackers = new Map();
 function toolCallSummary(call) {
     const args = call.args && typeof call.args === 'object' ? call.args : {};
     if (call.name === 'run_command') {
@@ -19,6 +24,17 @@ function toolCallSummary(call) {
     if (call.name === 'run_node_script') {
         return String(args.script ?? '').trim().slice(0, 120);
     }
+    if (call.name === 'shell_job_output' ||
+        call.name === 'shell_job_kill') {
+        return String(args.job_id ?? '').trim();
+    }
+    if (call.name === 'update_todos') {
+        const raw = extractTodosArg(args);
+        const todos = Array.isArray(raw) ? raw : [];
+        if (todos.length === 0)
+            return '';
+        return `${todos.length} item${todos.length === 1 ? '' : 's'}`;
+    }
     const filePath = getEditToolFilePath(call);
     if (filePath)
         return filePath;
@@ -32,6 +48,12 @@ export function formatToolCallForStatus(call) {
 }
 function getEditToolFilePath(call) {
     const args = call.args && typeof call.args === 'object' ? call.args : {};
+    if (call.name === 'replace_document_text') {
+        const outputPath = args.outputPath ?? args.output_path;
+        if (typeof outputPath === 'string' && outputPath.trim()) {
+            return outputPath.trim();
+        }
+    }
     for (const key of EDIT_FILE_PATH_ARG_ALIASES) {
         const value = args[key];
         if (typeof value === 'string' && value.trim())
@@ -39,6 +61,91 @@ function getEditToolFilePath(call) {
     }
     return '';
 }
+function editToolWritesSeparateOutput(call) {
+    if (call.name !== 'replace_document_text')
+        return false;
+    const args = call.args && typeof call.args === 'object' ? call.args : {};
+    const output = args.outputPath ?? args.output_path;
+    return typeof output === 'string' && output.trim().length > 0;
+}
+async function collectTrackedCommandMutations({ session, projectIndex, result, tracker, toolName, toolCallId, turnId, }) {
+    const checkpoint = ensureActiveCheckpoint(session.clientState.safety, turnId);
+    const records = collectCommandMutations({
+        state: session.clientState.safety,
+        rootDir: session.rootDir,
+        tracker,
+        toolName,
+        toolCallId,
+        turnId,
+        checkpointId: checkpoint.id,
+    });
+    if (!records.length)
+        return;
+    invalidateShellDiagnosticsCache(session.rootDir);
+    rememberCheckpointFiles(session.clientState.safety, session.rootDir, records.map((record) => record.filePath), turnId);
+    const repoSync = await syncIndexFromDisk(projectIndex);
+    result.repoSync = repoSync;
+    result.sessionEdits = records.map((record) => ({
+        id: record.id,
+        filePath: record.filePath,
+        operation: record.operation,
+        beforeHash: record.beforeHash,
+        afterHash: record.afterHash,
+    }));
+    result.diagnostics = runShellDiagnostics(session.rootDir);
+}
+export async function collectBackgroundJobUiKillMutations({ session, projectIndex, jobId, result, }) {
+    const normalizedJobId = String(jobId ?? result.snapshot?.id ?? '').trim();
+    if (!normalizedJobId || !result.ok)
+        return;
+    const tracked = backgroundCommandTrackers.get(normalizedJobId);
+    if (!tracked)
+        return;
+    const mutationResult = result;
+    await collectTrackedCommandMutations({
+        session,
+        projectIndex,
+        result: mutationResult,
+        tracker: tracked.tracker,
+        toolName: tracked.toolName,
+        toolCallId: tracked.toolCallId,
+        turnId: tracked.turnId,
+    });
+    if (result.snapshot?.status === 'running') {
+        tracked.tracker = captureMutationBaseline(session.rootDir);
+    }
+    else {
+        backgroundCommandTrackers.delete(normalizedJobId);
+    }
+}
+export async function collectBackgroundJobUiOutputMutations({ session, projectIndex, jobId, }) {
+    const normalizedJobId = String(jobId ?? '').trim();
+    if (!normalizedJobId)
+        return;
+    const tracked = backgroundCommandTrackers.get(normalizedJobId);
+    if (!tracked)
+        return;
+    const snapshot = getBackgroundJob(normalizedJobId, {
+        sessionId: session.sessionId,
+    });
+    if (!snapshot)
+        return;
+    await collectTrackedCommandMutations({
+        session,
+        projectIndex,
+        result: {},
+        tracker: tracked.tracker,
+        toolName: tracked.toolName,
+        toolCallId: tracked.toolCallId,
+        turnId: tracked.turnId,
+    });
+    if (snapshot.status === 'running') {
+        tracked.tracker = captureMutationBaseline(session.rootDir);
+    }
+    else {
+        backgroundCommandTrackers.delete(normalizedJobId);
+    }
+}
 function recordAssistantEdit(session, call, result, before) {
     if (!before || !isEditToolName(call.name))
         return;
@@ -79,6 +186,7 @@ function recordAssistantEdit(session, call, result, before) {
         beforeHash: before.hash,
         afterHash: after.hash,
         beforeContent: operation === 'create' ? null : before.content,
+        beforeContentEncoding: before.contentEncoding,
         createdAt: new Date().toISOString(),
         revertedAt: null,
         revertedByToolCallId: null,
@@ -98,6 +206,7 @@ function recordAssistantEdit(session, call, result, before) {
         beforeHash: before.hash,
         afterHash: after.hash,
         beforeContent: operation === 'create' ? null : before.content,
+        beforeContentEncoding: before.contentEncoding,
         checkpointId: checkpoint.id,
     });
     clearEditFailure(session.clientState.safety, filePath);
@@ -111,7 +220,14 @@ export async function executeLocalToolCall(toolContext, session, call) {
             session.onToolEvent?.({ call, result });
             return result;
         }
-        const filePathBeforeEdit = isEditToolName(call.name) ? getEditToolFilePath(call) : '';
+        const rawEditFilePath = isEditToolName(call.name)
+            ? getEditToolFilePath(call)
+            : '';
+        const filePathBeforeEdit = rawEditFilePath &&
+            PATH_REPAIRING_EDIT_TOOLS.has(call.name) &&
+            !editToolWritesSeparateOutput(call)
+            ? repairFilePath(session.rootDir, rawEditFilePath)
+            : rawEditFilePath;
         if (filePathBeforeEdit) {
             rememberCheckpointFiles(session.clientState.safety, session.rootDir, [filePathBeforeEdit], session.turnState.id);
         }
@@ -123,6 +239,7 @@ export async function executeLocalToolCall(toolContext, session, call) {
             : null;
         const context = {
             rootDir: session.rootDir,
+            sessionId: session.sessionId,
             projectIndex: toolContext.projectIndex,
             autoYes: session.autoYes,
             confirmCommand: session.confirmCommand,
@@ -144,28 +261,57 @@ export async function executeLocalToolCall(toolContext, session, call) {
         };
         const result = await dispatchTool(context, call);
         recordAssistantEdit(session, call, result, beforeEditSnapshot);
-        if (result && commandTracker && (call.name === 'run_command' || call.name === 'run_node_script')) {
-            const checkpoint = ensureActiveCheckpoint(session.clientState.safety, session.turnState.id);
-            const records = collectCommandMutations({
-                state: session.clientState.safety,
-                rootDir: session.rootDir,
+        if (result && typeof result === 'object' && commandTracker) {
+            await collectTrackedCommandMutations({
+                session,
+                projectIndex: toolContext.projectIndex,
+                result,
                 tracker: commandTracker,
                 toolName: call.name,
                 toolCallId: call.id,
                 turnId: session.turnState.id,
-                checkpointId: checkpoint.id,
             });
-            if (records.length) {
-                invalidateShellDiagnosticsCache(session.rootDir);
-                rememberCheckpointFiles(session.clientState.safety, session.rootDir, records.map((record) => record.filePath), session.turnState.id);
-                result.sessionEdits = records.map((record) => ({
-                    id: record.id,
-                    filePath: record.filePath,
-                    operation: record.operation,
-                    beforeHash: record.beforeHash,
-                    afterHash: record.afterHash,
-                }));
-                result.diagnostics = runShellDiagnostics(session.rootDir);
+            if (call.name === 'run_command' &&
+                result.backgrounded === true &&
+                result.status === 'running' &&
+                result.jobId) {
+                backgroundCommandTrackers.set(String(result.jobId), {
+                    tracker: captureMutationBaseline(session.rootDir),
+                    toolName: call.name,
+                    toolCallId: call.id,
+                    turnId: session.turnState.id,
+                });
+            }
+        }
+        if (result &&
+            typeof result === 'object' &&
+            (call.name === 'shell_job_output' || call.name === 'shell_job_kill')) {
+            const jobId = String(result.jobId ?? call.args?.job_id ?? '').trim();
+            const tracked = backgroundCommandTrackers.get(jobId);
+            if (tracked) {
+                await collectTrackedCommandMutations({
+                    session,
+                    projectIndex: toolContext.projectIndex,
+                    result,
+                    tracker: tracked.tracker,
+                    toolName: tracked.toolName,
+                    toolCallId: tracked.toolCallId,
+                    turnId: tracked.turnId,
+                });
+                if (result.status === 'running') {
+                    tracked.tracker = captureMutationBaseline(session.rootDir);
+                }
+                else {
+                    backgroundCommandTrackers.delete(jobId);
+                }
+            }
+        }
+        if (result && typeof result === 'object') {
+            const backgroundJobUpdate = drainBackgroundJobNotifications({
+                sessionId: session.sessionId,
+            });
+            if (backgroundJobUpdate) {
+                result.backgroundJobUpdate = backgroundJobUpdate;
             }
         }
         session.onToolEvent?.({ call, result });

package/dist/src/tools/delete-file.js

@@ -1,4 +1,4 @@
-import chalk from 'chalk';
+import chalk from '../colors.js';
 import { deleteProjectFile } from '../patcher.js';
 import { isTuiMode } from '../runtime-mode.js';
 import { removeIndexFile } from '../project-index.js';

package/dist/src/tools/index.js

@@ -1,3 +1,4 @@
+import { shellJobOutput } from './shell-job-output.js';
 import { deleteFile } from './delete-file.js';
 import { findSymbol } from './find-symbol.js';
 import { getDiagnostics } from './get-diagnostics.js';
@@ -11,13 +12,16 @@ import { listSymbols } from './list-symbols.js';
 import { patchFile } from './patch-file.js';
 import { readDocument } from './read-document.js';
 import { readFile } from './read-file.js';
+import { replaceDocumentText } from './replace-document-text.js';
 import { runShellCommand } from './run-command.js';
 import { runNodeScript } from './run-node-script.js';
 import { restoreFilesToCheckpoint, restoreToCheckpoint, } from './restore-checkpoint.js';
 import { searchCode } from './search-code.js';
 import { getSignatureHelp } from './signature-help.js';
+import { shellJobKill } from './shell-job-kill.js';
 import { strReplace } from './str-replace.js';
 import { undoEdit } from './undo-edit.js';
+import { updateTodos } from './update-todos.js';
 import { writeFile } from './write-file.js';
 export const TOOL_MAP = {
     search_code: (context, args) => searchCode(context.projectIndex, args),
@@ -25,6 +29,7 @@ export const TOOL_MAP = {
     list_directories: (context, args) => listDirectories(context, args),
     read_file: (context, args) => readFile(context, args),
     read_document: (context, args) => readDocument(context.rootDir, args, context.env),
+    replace_document_text: replaceDocumentText,
     grep_code: (context, args) => grepCode(context.rootDir, args),
     find_symbol: (context, args) => findSymbol(context, args),
     list_symbols: (context, args) => listSymbols(context, args),
@@ -42,6 +47,9 @@ export const TOOL_MAP = {
     undo_edit: undoEdit,
     run_command: runShellCommand,
     run_node_script: runNodeScript,
+    shell_job_output: shellJobOutput,
+    shell_job_kill: shellJobKill,
+    update_todos: updateTodos,
 };
 function invalidToolCall(error) {
     return {

package/dist/src/tools/patch-file.js

@@ -1,13 +1,16 @@
-import chalk from 'chalk';
+import chalk from '../colors.js';
+import path from 'node:path';
 import { normalizeProjectRelativePath } from '../artifact-policy.js';
 import { applyUnifiedPatch, readProjectFile, renderDiffPreview, writeProjectFile, } from '../patcher.js';
 import { upsertIndexFile } from '../project-index.js';
+import { repairFilePath } from './path-suggest.js';
 import { isTuiMode } from '../runtime-mode.js';
 import { getCurrentFileHash, resolveRedactionTokens } from '../session-safety.js';
 import { invalidateShellDiagnosticsCache, runShellDiagnostics, } from './shell-diagnostics.js';
+const DOCUMENT_EXTENSIONS = new Set(['.pdf', '.xlsx', '.docx']);
 export async function patchFile(context, args) {
     const { rootDir, projectIndex, autoYes, confirmPatch } = context;
-    const filePath = String(args.filePath ?? '').trim();
+    const filePath = repairFilePath(rootDir, String(args.filePath ?? '').trim());
     let patch = typeof args.patch === 'string' ? args.patch : '';
     if (!filePath) {
         return { ok: false, error: 'filePath is required' };
@@ -15,6 +18,17 @@ export async function patchFile(context, args) {
     if (!patch.trim()) {
         return { ok: false, error: 'patch is required' };
     }
+    const ext = path.extname(filePath).toLowerCase();
+    if (DOCUMENT_EXTENSIONS.has(ext)) {
+        return {
+            ok: false,
+            filePath,
+            error: ext === '.docx'
+                ? 'Use replace_document_text for .docx files.'
+                : `Use read_document for ${ext} files; patching is not supported.`,
+            failureCategory: 'invalid_argument',
+        };
+    }
     let originalContent;
     try {
         originalContent = readProjectFile(rootDir, filePath);

package/dist/src/tools/path-suggest.js

@@ -0,0 +1,139 @@
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { isSensitiveProjectPath, shouldIgnoreArtifactPath, } from '../artifact-policy.js';
+function foldName(name) {
+    return name
+        .normalize('NFC')
+        .replace(/[‘’ʼ]/g, "'")
+        .replace(/[“”]/g, '"')
+        .replace(/ /g, ' ')
+        .toLowerCase();
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    let prev = Array.from({ length: cols }, (_, j) => j);
+    for (let i = 1; i < rows; i++) {
+        const current = [i, ...new Array(cols - 1).fill(0)];
+        for (let j = 1; j < cols; j++) {
+            current[j] = Math.min(prev[j] + 1, current[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = current;
+    }
+    return prev[cols - 1];
+}
+export function suggestClosestPath(rootDir, missingPath) {
+    const resolved = path.isAbsolute(missingPath)
+        ? missingPath
+        : path.resolve(rootDir, missingPath);
+    const directory = path.dirname(resolved);
+    const wantedBase = foldName(path.basename(resolved));
+    if (!wantedBase)
+        return null;
+    let candidates;
+    try {
+        candidates = readdirSync(directory);
+    }
+    catch {
+        return null;
+    }
+    const threshold = Math.max(2, Math.floor(wantedBase.length * 0.25));
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const candidateRelative = path.relative(rootDir, path.join(directory, candidate));
+        if (isSensitiveProjectPath(candidateRelative))
+            continue;
+        const distance = levenshtein(wantedBase, foldName(candidate));
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    if (!best || bestDistance > threshold)
+        return null;
+    const suggested = path.join(directory, best);
+    const relative = path.relative(rootDir, suggested);
+    return relative && !relative.startsWith('..') ? relative : suggested;
+}
+function foldPunctuation(name) {
+    return name
+        .normalize('NFC')
+        .replace(/[‘’ʼ]/g, "'")
+        .replace(/[“”]/g, '"')
+        .replace(/ /g, ' ');
+}
+function stripSurroundingQuotes(p) {
+    if (p.length >= 2) {
+        const first = p[0];
+        const last = p[p.length - 1];
+        if ((first === "'" && last === "'") || (first === '"' && last === '"')) {
+            return p.slice(1, -1);
+        }
+    }
+    return p;
+}
+function collapseDoubledBackslashes(p) {
+    return p.replace(/\\\\/g, '\\');
+}
+function resolveAgainst(rootDir, p) {
+    return path.isAbsolute(p) ? p : path.resolve(rootDir, p);
+}
+function existsAgainst(rootDir, p) {
+    try {
+        return existsSync(resolveAgainst(rootDir, p));
+    }
+    catch {
+        return false;
+    }
+}
+function isProtectedRepairTarget(rootDir, candidate) {
+    const rel = path.relative(rootDir, resolveAgainst(rootDir, candidate));
+    const projectPath = rel && !rel.startsWith('..') ? rel : candidate;
+    return (isSensitiveProjectPath(projectPath) ||
+        (rel !== '' && !rel.startsWith('..') && shouldIgnoreArtifactPath(rel)));
+}
+export const PATH_REPAIRING_EDIT_TOOLS = new Set([
+    'str_replace',
+    'patch_file',
+    'replace_document_text',
+]);
+export function repairFilePath(rootDir, raw) {
+    if (!raw || existsAgainst(rootDir, raw))
+        return raw;
+    const dequoted = stripSurroundingQuotes(raw);
+    for (const candidate of [
+        dequoted,
+        collapseDoubledBackslashes(raw),
+        collapseDoubledBackslashes(dequoted),
+    ]) {
+        if (candidate !== raw &&
+            existsAgainst(rootDir, candidate) &&
+            !isProtectedRepairTarget(rootDir, candidate)) {
+            return candidate;
+        }
+    }
+    const probe = resolveAgainst(rootDir, dequoted);
+    const directory = path.dirname(probe);
+    const wanted = foldPunctuation(path.basename(probe));
+    if (!wanted)
+        return raw;
+    let entries;
+    try {
+        entries = readdirSync(directory);
+    }
+    catch {
+        return raw;
+    }
+    const matches = entries.filter((entry) => foldPunctuation(entry) === wanted);
+    if (matches.length !== 1)
+        return raw;
+    const matchedAbs = path.join(directory, matches[0]);
+    const matchedRel = path.relative(rootDir, matchedAbs);
+    const matched = path.isAbsolute(dequoted) ? matchedAbs : matchedRel || matchedAbs;
+    if (isProtectedRepairTarget(rootDir, matched))
+        return raw;
+    return matched;
+}

package/dist/src/tools/read-document.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { isSensitiveProjectPath, normalizeProjectRelativePath, } from '../artifact-policy.js';
+import { repairFilePath, suggestClosestPath } from './path-suggest.js';
 import { readCliAuthConfig } from '../api/auth.js';
 export function normalizeDocumentText(raw) {
     const text = String(raw ?? '').replace(/\r\n?/g, '\n');
@@ -36,6 +37,7 @@ export function normalizeDocumentText(raw) {
 }
 async function parseDocumentOnServer(config, fileName, fileData, ext, args) {
     const includePageArgs = ext === '.pdf';
+    const includeParagraphArgs = ext === '.docx';
     const response = await globalThis.fetch(`${config.serverUrl.replace(/\/+$/, '')}/v1/document/parse`, {
         method: 'POST',
         headers: {
@@ -51,6 +53,12 @@ async function parseDocumentOnServer(config, fileName, fileData, ext, args) {
             ...(includePageArgs && args.lastPage !== undefined
                 ? { lastPage: args.lastPage }
                 : {}),
+            ...(includeParagraphArgs && args.firstParagraph !== undefined
+                ? { firstParagraph: args.firstParagraph }
+                : {}),
+            ...(includeParagraphArgs && args.lastParagraph !== undefined
+                ? { lastParagraph: args.lastParagraph }
+                : {}),
         }),
     });
     const data = await response.json().catch(() => null);
@@ -63,7 +71,7 @@ async function parseDocumentOnServer(config, fileName, fileData, ext, args) {
     return data;
 }
 export async function readDocument(rootDir, args, env) {
-    const raw = String(args.filePath ?? '').trim();
+    const raw = repairFilePath(rootDir, String(args.filePath ?? '').trim());
     if (!raw) {
         return { ok: false, error: 'filePath is required' };
     }
@@ -76,17 +84,20 @@ export async function readDocument(rootDir, args, env) {
         };
     }
     if (!existsSync(resolvedPath)) {
+        const suggestion = suggestClosestPath(rootDir, resolvedPath);
         return {
             ok: false,
-            error: `File not found: ${resolvedPath}`,
+            error: suggestion
+                ? `File not found: ${resolvedPath}. Did you mean "${suggestion}"? Note the exact punctuation (e.g. curly apostrophe ’ vs straight ').`
+                : `File not found: ${resolvedPath}`,
             failureCategory: 'not_found',
         };
     }
     const ext = path.extname(resolvedPath).toLowerCase();
-    if (ext !== '.pdf' && ext !== '.xlsx') {
+    if (ext !== '.pdf' && ext !== '.xlsx' && ext !== '.docx') {
         return {
             ok: false,
-            error: `Unsupported file type: "${ext}". read_document only supports .pdf and .xlsx.`,
+            error: `Unsupported file type: "${ext}". read_document only supports .pdf, .xlsx, and .docx.`,
         };
     }
     const authConfig = readCliAuthConfig(env);

package/dist/src/tools/read-file.js

@@ -3,13 +3,15 @@ import path from 'path';
 import { normalizeProjectRelativePath, shouldIgnoreArtifactPath, } from '../artifact-policy.js';
 import { buildSecretFilePreview, isDotenvLikePath, looksLikeEditableDotenv, shouldUseSecretFilePreview, } from '../secret-preview.js';
 import { readProjectFile } from '../patcher.js';
+import { repairFilePath } from './path-suggest.js';
 import { dotenvFitsRedactionBudget, getCurrentFileHash, recordReadCoverage, redactContentWithStableTokens, redactDotenvWithStableTokens, } from '../session-safety.js';
 import { readFileRange, truncate } from '../utils.js';
 const MAX_FILE_READ_CHARS = 12000;
+const DOCUMENT_EXTENSIONS = new Set(['.pdf', '.xlsx', '.docx']);
 export async function readFile(context, args) {
     const rootDir = typeof context === 'string' ? context : context.rootDir;
     const safety = typeof context === 'string' ? undefined : context.safety;
-    const filePath = String(args.filePath ?? '').trim();
+    const filePath = repairFilePath(rootDir, String(args.filePath ?? '').trim());
     if (!filePath) {
         return { ok: false, error: 'filePath is required' };
     }
@@ -26,19 +28,37 @@ export async function readFile(context, args) {
             error: 'This path is not permitted.',
         };
     }
+    const documentExt = path.extname(projectPath ?? filePath).toLowerCase();
+    if (DOCUMENT_EXTENSIONS.has(documentExt)) {
+        return {
+            ok: false,
+            error: `Use read_document for ${documentExt} files.`,
+            failureCategory: 'invalid_argument',
+        };
+    }
     let content;
     if (projectPath) {
         try {
             content = readProjectFile(rootDir, filePath);
         }
         catch (err) {
-            return { ok: false, error: err.message };
+            const message = String(err?.message ?? err);
+            const notFound = /^File does not exist:/.test(message);
+            return {
+                ok: false,
+                error: message,
+                ...(notFound ? { failureCategory: 'not_found' } : {}),
+            };
         }
     }
     else {
         const absPath = path.resolve(filePath);
         if (!existsSync(absPath)) {
-            return { ok: false, error: `File does not exist: ${filePath}` };
+            return {
+                ok: false,
+                error: `File does not exist: ${filePath}`,
+                failureCategory: 'not_found',
+            };
         }
         try {
             content = readFileSync(absPath, 'utf-8');
@@ -48,10 +68,6 @@ export async function readFile(context, args) {
         }
     }
     const previewPath = projectPath ?? filePath;
-    // A clean dotenv file is shown with keys visible and values tokenized so the
-    // agent can still edit it (str_replace/write_file round-trip the tokens) and
-    // read coverage is recorded. Any other secret file — PEM, JSON credentials,
-    // or a dotenv with a stray non-assignment line — keeps the opaque blackout.
     const editableDotenv = Boolean(projectPath) &&
         Boolean(safety) &&
         isDotenvLikePath(previewPath) &&