@thegitai/cli 1.0.0-preview.1 → 1.0.0-preview.2

package/dist/bin/ai.js

@@ -18,6 +18,7 @@ import { formatVersionLine } from '../src/version.js';
 import { parseArgs } from '../src/cli-args.js';
 import { getJobBufferedOutput, killBackgroundJob, killAllBackgroundJobs, listBackgroundJobs, setBackgroundJobSession, } from '../src/background-jobs.js';
 import { collectBackgroundJobUiKillMutations, collectBackgroundJobUiOutputMutations, } from '../src/tool-executor.js';
+import { setScratchSession } from '../src/scratch-dir.js';
 const DEFAULT_SERVER_URL = 'https://thegit.ai';
 const { auth, chat, models, sessions } = ServerApi;
 function printUsage() {
@@ -318,6 +319,7 @@ async function mainInteractive({ authConfig, projectIndex, serverModels, serverS
             }
             applySessionSnapshot(session, snapshot);
             setBackgroundJobSession(session.sessionId);
+            setScratchSession(session.sessionId);
             await saveSessionBoth({ session, serverSessionClient });
             console.log(chalk.dim(`Resumed session${session.sessionName ? ` "${session.sessionName}"` : ''} (${session.sessionId})\n`));
             continue;
@@ -454,6 +456,7 @@ export async function main() {
         applySessionSnapshot(session, sourceSnapshot);
         await saveSessionBoth({ session, serverSessionClient });
     }
+    setScratchSession(session.sessionId);
     const projectIndex = createIndex({
         rootDir,
         onStatus: (message) => {
@@ -503,6 +506,7 @@ export async function main() {
     finally {
         killAllBackgroundJobs({ sessionId: session.sessionId, remove: true });
         setBackgroundJobSession(null);
+        setScratchSession(null);
     }
 }
 main().catch((error) => {

package/dist/src/api/chat.js

@@ -4,6 +4,7 @@ import { applySessionSnapshot, snapshotFromSession, } from '../session-store.js'
 import { executeLocalToolCall } from '../tool-executor.js';
 import { createTraceContext, normalizeServerUrl, readErrorResponse, } from './http.js';
 import { collectClientEnvironment } from '../client-environment.js';
+import { collectProjectOrientation } from '../project-orientation.js';
 import { autoAttachImages } from '../core/image-path-extractor.js';
 export class TurnCancelledError extends Error {
     name = 'TurnCancelledError';
@@ -339,6 +340,7 @@ export async function sendServerUserMessage({ config, projectIndex, session, inp
         input: requestInputBase,
         backgroundJobUpdate: backgroundJobUpdate || undefined,
         clientEnvironment: collectClientEnvironment({ env: session.env }),
+        projectOrientation: collectProjectOrientation(session.rootDir) ?? undefined,
         imageAttachments: imageAttachmentsForServer(requestImageAttachments),
         maxToolSteps: session.maxToolSteps,
         autoYes: session.autoYes,

package/dist/src/patcher.js

@@ -1,8 +1,9 @@
 import chalk from './colors.js';
-import { existsSync, lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from 'fs';
+import { chmodSync, closeSync, constants, existsSync, fchmodSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, unlinkSync, writeFileSync, } from 'fs';
 import path from 'path';
 import { createInterface } from 'readline';
 import { runCommand } from './executor.js';
+import { ensureSessionScratchDir, isInsideTheGitAiScratch, isWithinSessionScratchDir, } from './scratch-dir.js';
 import { isTuiMode } from './runtime-mode.js';
 import { truncate } from './utils.js';
 function parseUnifiedDiff(patchText) {
@@ -143,17 +144,92 @@ export function renderDiffPreview(filePath, patchText) {
 function normalizeRoot(rootDir) {
     return path.resolve(rootDir);
 }
-export function resolveProjectPath(rootDir, filePath) {
+function expandScratchPath(filePath) {
+    const match = filePath.match(/^(?:\$THEGITAI_SCRATCH_DIR|\$\{THEGITAI_SCRATCH_DIR\})(?:[\\/](.*))?$/);
+    if (!match)
+        return filePath;
+    const root = ensureSessionScratchDir();
+    return match[1] ? path.join(root, match[1]) : root;
+}
+export function classifyProjectPath(rootDir, filePath) {
     const absRoot = normalizeRoot(rootDir);
-    const absPath = path.resolve(absRoot, filePath);
+    const absPath = path.resolve(absRoot, expandScratchPath(filePath));
+    if (isWithinSessionScratchDir(absPath)) {
+        return absPath !== path.resolve(ensureSessionScratchDir()) &&
+            isInsideTheGitAiScratch(absPath)
+            ? 'scratch'
+            : 'outside';
+    }
     const relative = path.relative(absRoot, absPath);
-    if (relative.startsWith('..') || path.isAbsolute(relative)) {
-        throw new Error(`Refusing to access path outside the project root: ${filePath}`);
+    if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
+        return 'project';
+    }
+    return 'outside';
+}
+export function resolveProjectPath(rootDir, filePath) {
+    const absRoot = normalizeRoot(rootDir);
+    const absPath = path.resolve(absRoot, expandScratchPath(filePath));
+    if (classifyProjectPath(rootDir, filePath) === 'outside') {
+        throw new Error(`Refusing to access path outside the project root: ${filePath}. Allowed locations are the project root and the session scratch directory ($THEGITAI_SCRATCH_DIR).`);
     }
     return absPath;
 }
+function mkdirForWrite(absPath, scratchPath) {
+    const parent = path.dirname(absPath);
+    if (!scratchPath) {
+        mkdirSync(parent, { recursive: true });
+        return;
+    }
+    const scratchRoot = path.resolve(ensureSessionScratchDir());
+    const relative = path.relative(scratchRoot, parent);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`Refusing to create a directory outside the session scratch root: ${parent}`);
+    }
+    let current = scratchRoot;
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            mkdirSync(current, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error?.code !== 'EEXIST')
+                throw error;
+        }
+        const stat = lstatSync(current);
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+            throw new Error(`Refusing to traverse unsafe scratch directory: ${current}`);
+        }
+        if (process.platform !== 'win32')
+            chmodSync(current, 0o700);
+    }
+}
+function writeScratchFile(absPath, content) {
+    const scratchRoot = realpathSync(ensureSessionScratchDir());
+    const parent = realpathSync(path.dirname(absPath));
+    const relativeParent = path.relative(scratchRoot, parent);
+    if (relativeParent.startsWith('..') || path.isAbsolute(relativeParent)) {
+        throw new Error(`Refusing to write through an unsafe scratch directory: ${absPath}`);
+    }
+    const verifiedPath = path.join(parent, path.basename(absPath));
+    const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+    const fd = openSync(verifiedPath, constants.O_WRONLY | constants.O_CREAT | noFollow, 0o600);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.nlink > 1) {
+            throw new Error(`Refusing to write an unsafe scratch file: ${absPath}`);
+        }
+        ftruncateSync(fd, 0);
+        if (process.platform !== 'win32')
+            fchmodSync(fd, 0o600);
+        writeFileSync(fd, content);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 export function writeProjectFile(rootDir, filePath, content) {
     const absPath = resolveProjectPath(rootDir, filePath);
+    const scratchPath = classifyProjectPath(rootDir, filePath) === 'scratch';
     if (existsSync(absPath)) {
         try {
             const existingContent = readFileSync(absPath, 'utf-8');
@@ -164,12 +240,18 @@ export function writeProjectFile(rootDir, filePath, content) {
         catch {
         }
     }
-    mkdirSync(path.dirname(absPath), { recursive: true });
-    writeFileSync(absPath, content, 'utf-8');
+    mkdirForWrite(absPath, scratchPath);
+    if (scratchPath) {
+        writeScratchFile(absPath, content);
+    }
+    else {
+        writeFileSync(absPath, content, 'utf-8');
+    }
     return { absPath, changed: true };
 }
 export function writeProjectFileBuffer(rootDir, filePath, content) {
     const absPath = resolveProjectPath(rootDir, filePath);
+    const scratchPath = classifyProjectPath(rootDir, filePath) === 'scratch';
     if (existsSync(absPath)) {
         try {
             const existingContent = readFileSync(absPath);
@@ -180,8 +262,13 @@ export function writeProjectFileBuffer(rootDir, filePath, content) {
         catch {
         }
     }
-    mkdirSync(path.dirname(absPath), { recursive: true });
-    writeFileSync(absPath, content);
+    mkdirForWrite(absPath, scratchPath);
+    if (scratchPath) {
+        writeScratchFile(absPath, content);
+    }
+    else {
+        writeFileSync(absPath, content);
+    }
     return { absPath, changed: true };
 }
 export function deleteProjectFile(rootDir, filePath) {

package/dist/src/project-orientation.js

@@ -0,0 +1,99 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readdirSync, readFileSync, } from 'node:fs';
+import path from 'node:path';
+import { shouldIgnoreArtifactPath } from './artifact-policy.js';
+const MAX_TOP_LEVEL_ENTRIES = 80;
+const MAX_DECLARED_TASKS = 40;
+const MAX_NAME_CHARS = 120;
+const MAX_PACKAGE_JSON_BYTES = 1024 * 1024;
+function normalizeName(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value
+        .replace(/[\u0000-\u001f\u007f]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, MAX_NAME_CHARS);
+    return normalized || null;
+}
+function normalizeNames(value, limit) {
+    if (!Array.isArray(value))
+        return [];
+    const names = [];
+    const seen = new Set();
+    for (const item of value) {
+        const name = normalizeName(item);
+        if (!name || seen.has(name))
+            continue;
+        seen.add(name);
+        names.push(name);
+        if (names.length >= limit)
+            break;
+    }
+    return names;
+}
+function readPackageTasks(rootDir) {
+    const packagePath = path.join(rootDir, 'package.json');
+    let fd = null;
+    try {
+        const pathStat = lstatSync(packagePath);
+        if (pathStat.isSymbolicLink() ||
+            !pathStat.isFile() ||
+            pathStat.nlink > 1 ||
+            pathStat.size > MAX_PACKAGE_JSON_BYTES) {
+            return [];
+        }
+        const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+        fd = openSync(packagePath, constants.O_RDONLY | noFollow);
+        const fileStat = fstatSync(fd);
+        if (!fileStat.isFile() ||
+            fileStat.nlink > 1 ||
+            fileStat.size > MAX_PACKAGE_JSON_BYTES ||
+            fileStat.dev !== pathStat.dev ||
+            fileStat.ino !== pathStat.ino) {
+            return [];
+        }
+        const parsed = JSON.parse(readFileSync(fd, 'utf8'));
+        if (!parsed?.scripts || typeof parsed.scripts !== 'object')
+            return [];
+        return normalizeNames(Object.keys(parsed.scripts), MAX_DECLARED_TASKS);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+export function normalizeProjectOrientation(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const record = value;
+    const topLevelEntries = normalizeNames(record.topLevelEntries, MAX_TOP_LEVEL_ENTRIES);
+    const packageScripts = normalizeNames(record.packageScripts, MAX_DECLARED_TASKS);
+    if (topLevelEntries.length === 0 && packageScripts.length === 0)
+        return null;
+    return {
+        topLevelEntries,
+        packageScripts,
+        truncated: record.truncated === true,
+    };
+}
+export function collectProjectOrientation(rootDir) {
+    try {
+        const entries = readdirSync(rootDir, { withFileTypes: true })
+            .filter((entry) => !shouldIgnoreArtifactPath(entry.name))
+            .sort((a, b) => a.name.localeCompare(b.name));
+        const topLevelEntries = entries
+            .slice(0, MAX_TOP_LEVEL_ENTRIES)
+            .map((entry) => `${entry.name}${entry.isDirectory() ? '/' : ''}`);
+        return normalizeProjectOrientation({
+            topLevelEntries,
+            packageScripts: readPackageTasks(rootDir),
+            truncated: entries.length > MAX_TOP_LEVEL_ENTRIES,
+        });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/scratch-dir.js

@@ -1,57 +1,75 @@
-import { chmodSync, lstatSync, mkdirSync, mkdtempSync } from 'node:fs';
+import { chmodSync, lstatSync, mkdtempSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-let cachedScratchDir = null;
+const scratchDirs = new Map();
+let activeSessionId = 'default';
+export function setScratchSession(sessionId) {
+    activeSessionId = String(sessionId ?? '').trim() || 'default';
+}
+function allocateSessionScratchDir() {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'thegitai-'));
+    scratchDirs.set(activeSessionId, dir);
+    return dir;
+}
 export function sessionScratchDir() {
-    if (!cachedScratchDir) {
-        cachedScratchDir = path.join(os.tmpdir(), `thegitai-${process.pid}`);
-    }
-    return cachedScratchDir;
+    return scratchDirs.get(activeSessionId) ?? allocateSessionScratchDir();
 }
-function isSquattedScratchRoot(dir) {
+function isOwnedDirectory(dir) {
     try {
         const st = lstatSync(dir);
         if (st.isSymbolicLink() || !st.isDirectory())
-            return true;
+            return false;
         if (process.platform !== 'win32' &&
             typeof process.getuid === 'function' &&
             st.uid !== process.getuid()) {
-            return true;
+            return false;
         }
-        return false;
+        return true;
     }
     catch {
         return false;
     }
 }
 export function ensureSessionScratchDir() {
-    const dir = sessionScratchDir();
-    try {
-        if (isSquattedScratchRoot(dir)) {
-            cachedScratchDir = mkdtempSync(path.join(os.tmpdir(), 'thegitai-'));
-            return cachedScratchDir;
+    let dir = sessionScratchDir();
+    if (!isOwnedDirectory(dir)) {
+        dir = allocateSessionScratchDir();
+    }
+    if (process.platform !== 'win32') {
+        chmodSync(dir, 0o700);
+    }
+    return dir;
+}
+function hasUnsafeScratchComponent(root, relativePath) {
+    let current = root;
+    for (const segment of relativePath.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            const stat = lstatSync(current);
+            if (stat.isSymbolicLink())
+                return true;
+            if (stat.isDirectory())
+                continue;
+            if (!stat.isFile() || stat.nlink > 1)
+                return true;
         }
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
-        if (process.platform !== 'win32') {
-            chmodSync(dir, 0o700);
+        catch (error) {
+            return error?.code !== 'ENOENT';
         }
     }
-    catch {
-    }
-    return sessionScratchDir();
+    return false;
+}
+export function isWithinSessionScratchDir(absPath) {
+    const root = path.resolve(ensureSessionScratchDir());
+    const resolved = path.resolve(absPath);
+    const relative = path.relative(root, resolved);
+    return !relative.startsWith('..') && !path.isAbsolute(relative);
 }
 export function isInsideTheGitAiScratch(absPath) {
-    const tempRoot = path.resolve(os.tmpdir());
-    const relPath = path.relative(tempRoot, path.resolve(absPath));
-    if (!relPath || relPath.startsWith('..') || path.isAbsolute(relPath)) {
-        return false;
-    }
-    const first = relPath.split(/[\\/]/, 1)[0] ?? '';
-    if (!/^thegitai(?:$|[-.])/i.test(first)) {
-        return false;
-    }
-    if (/[*?[\]{}]/.test(first)) {
+    const root = path.resolve(ensureSessionScratchDir());
+    const resolved = path.resolve(absPath);
+    const relative = path.relative(root, resolved);
+    if (!isWithinSessionScratchDir(resolved))
         return false;
-    }
-    return !isSquattedScratchRoot(path.join(tempRoot, first));
+    return !hasUnsafeScratchComponent(root, relative);
 }

package/dist/src/tool-executor.js

@@ -2,6 +2,7 @@ import { drainBackgroundJobNotifications, getBackgroundJob, } from './background
 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 { classifyProjectPath } from './patcher.js';
 import { dispatchTool } from './tools/index.js';
 import { syncIndexFromDisk } from './project-index.js';
 import { PATH_REPAIRING_EDIT_TOOLS, repairFilePath } from './tools/path-suggest.js';
@@ -84,9 +85,38 @@ async function collectTrackedCommandMutations({ session, projectIndex, result, t
     invalidateShellDiagnosticsCache(session.rootDir);
     rememberCheckpointFiles(session.clientState.safety, session.rootDir, records.map((record) => record.filePath), turnId);
     const priorSync = result.repoSync;
-    if (!(priorSync &&
-        (priorSync.added || priorSync.modified || priorSync.removed))) {
-        result.repoSync = await syncIndexFromDisk(projectIndex);
+    if (!(priorSync && (priorSync.added || priorSync.modified || priorSync.removed))) {
+        const mutationCounts = {
+            added: records.filter((record) => record.operation === 'create').length,
+            modified: records.filter((record) => record.operation === 'update').length,
+            removed: records.filter((record) => record.operation === 'delete').length,
+            indexedChunks: 0,
+            retrievalTokensUsed: 0,
+        };
+        if (priorSync?.error) {
+            result.repoSync = {
+                ...mutationCounts,
+                indexSyncError: priorSync.error,
+                skipped: true,
+                reason: 'local index sync failed after command execution',
+            };
+        }
+        else {
+            try {
+                const repoSync = await syncIndexFromDisk(projectIndex);
+                result.repoSync = {
+                    ...repoSync,
+                    added: Math.max(repoSync.added, mutationCounts.added),
+                    modified: Math.max(repoSync.modified, mutationCounts.modified),
+                    removed: Math.max(repoSync.removed, mutationCounts.removed),
+                };
+            }
+            catch (error) {
+                const indexSyncError = error instanceof Error ? error.message : String(error);
+                result.repoSync = { ...mutationCounts, indexSyncError };
+                session.onStatus(`Repository changes were recorded, but local index sync failed: ${indexSyncError}`);
+            }
+        }
     }
     result.sessionEdits = records.map((record) => ({
         id: record.id,
@@ -150,7 +180,7 @@ export async function collectBackgroundJobUiOutputMutations({ session, projectIn
     }
 }
 function recordAssistantEdit(session, call, result, before) {
-    if (!before || !isEditToolName(call.name))
+    if (!before || !isEditToolName(call.name) || result?.scratch === true)
         return;
     if (!result || typeof result !== 'object' || result.ok !== true) {
         const filePath = getEditToolFilePath(call);
@@ -231,10 +261,12 @@ export async function executeLocalToolCall(toolContext, session, call) {
             !editToolWritesSeparateOutput(call)
             ? repairFilePath(session.rootDir, rawEditFilePath)
             : rawEditFilePath;
-        if (filePathBeforeEdit) {
+        const tracksRepositoryEdit = filePathBeforeEdit &&
+            classifyProjectPath(session.rootDir, filePathBeforeEdit) === 'project';
+        if (tracksRepositoryEdit) {
             rememberCheckpointFiles(session.clientState.safety, session.rootDir, [filePathBeforeEdit], session.turnState.id);
         }
-        const beforeEditSnapshot = filePathBeforeEdit
+        const beforeEditSnapshot = tracksRepositoryEdit
             ? readFileEditSnapshot(session.rootDir, filePathBeforeEdit)
             : null;
         const commandTracker = call.name === 'run_command' || call.name === 'run_node_script'

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

@@ -1,5 +1,5 @@
 import chalk from '../colors.js';
-import { deleteProjectFile } from '../patcher.js';
+import { classifyProjectPath, deleteProjectFile } from '../patcher.js';
 import { isTuiMode } from '../runtime-mode.js';
 import { removeIndexFile } from '../project-index.js';
 import { invalidateShellDiagnosticsCache, runShellDiagnostics, } from './shell-diagnostics.js';
@@ -9,10 +9,27 @@ export async function deleteFile(context, args) {
     if (!filePath) {
         return { ok: false, error: 'filePath is required' };
     }
+    const pathKind = classifyProjectPath(rootDir, filePath);
+    if (pathKind === 'outside') {
+        return {
+            ok: false,
+            filePath,
+            error: `Refusing to delete outside the project root: ${filePath}. Deletable locations are the project root and the session scratch directory ($THEGITAI_SCRATCH_DIR).`,
+            failureCategory: 'invalid_argument',
+            failureDetails: {
+                category: 'invalid_argument',
+                tool: 'delete_file',
+                action: 'Delete files inside the project root, or use an absolute path under the session scratch directory ($THEGITAI_SCRATCH_DIR).',
+            },
+        };
+    }
+    const scratchPath = pathKind === 'scratch';
     const result = deleteProjectFile(rootDir, filePath);
     if (result.deleted) {
-        await removeIndexFile(projectIndex, filePath);
-        invalidateShellDiagnosticsCache(rootDir, filePath);
+        if (!scratchPath) {
+            await removeIndexFile(projectIndex, filePath);
+            invalidateShellDiagnosticsCache(rootDir, filePath);
+        }
         if (!isTuiMode())
             console.log(chalk.red(`  🗑️  Deleted: ${filePath}`));
     }
@@ -21,7 +38,8 @@ export async function deleteFile(context, args) {
         filePath,
         changed: result.deleted,
         deleted: result.deleted,
+        ...(scratchPath ? { scratch: true } : {}),
         content: result.content,
-        diagnostics: result.deleted ? runShellDiagnostics(rootDir) : undefined,
+        diagnostics: result.deleted && !scratchPath ? runShellDiagnostics(rootDir) : undefined,
     };
 }

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

@@ -1,7 +1,7 @@
 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 { applyUnifiedPatch, classifyProjectPath, readProjectFile, renderDiffPreview, writeProjectFile, } from '../patcher.js';
 import { upsertIndexFile } from '../project-index.js';
 import { repairFilePath } from './path-suggest.js';
 import { isTuiMode } from '../runtime-mode.js';
@@ -29,6 +29,21 @@ export async function patchFile(context, args) {
             failureCategory: 'invalid_argument',
         };
     }
+    const pathKind = classifyProjectPath(rootDir, filePath);
+    if (pathKind === 'outside') {
+        return {
+            ok: false,
+            filePath,
+            error: `Refusing to edit outside the project root: ${filePath}. Editable locations are the project root and the session scratch directory ($THEGITAI_SCRATCH_DIR).`,
+            failureCategory: 'invalid_argument',
+            failureDetails: {
+                category: 'invalid_argument',
+                tool: 'patch_file',
+                action: 'Edit files inside the project root, or use an absolute path under the session scratch directory ($THEGITAI_SCRATCH_DIR) for temporary files.',
+            },
+        };
+    }
+    const scratchPath = pathKind === 'scratch';
     let originalContent;
     try {
         originalContent = readProjectFile(rootDir, filePath);
@@ -68,20 +83,29 @@ export async function patchFile(context, args) {
                 ok: false,
                 skipped: true,
                 filePath,
-                error: 'User declined patch',
+                failureCategory: 'user_declined',
+                failureDetails: {
+                    category: 'user_declined',
+                    tool: 'patch_file',
+                    action: 'Respect the real user’s decision. Do not retry the same or an equivalent edit; reconsider the approach or ask one specific question if needed.',
+                },
+                error: 'The real user rejected this proposed patch. Nothing was changed; this was not a tool failure or an automated system skip.',
             };
         }
     }
     const { changed } = writeProjectFile(rootDir, filePath, patchedContent);
     let indexedChunks = 0;
     let retrievalTokensUsed = 0;
-    if (changed) {
+    if (changed && !scratchPath) {
         const indexResult = await upsertIndexFile(projectIndex, filePath);
         indexedChunks = indexResult.indexedChunks;
         retrievalTokensUsed = indexResult.retrievalTokensUsed ?? 0;
     }
-    invalidateShellDiagnosticsCache(rootDir, filePath);
-    const diagnostics = runShellDiagnostics(rootDir, filePath);
+    let diagnostics;
+    if (!scratchPath) {
+        invalidateShellDiagnosticsCache(rootDir, filePath);
+        diagnostics = runShellDiagnostics(rootDir, filePath);
+    }
     const originalLines = originalContent.split('\n').length;
     const patchedLines = patchedContent.split('\n').length;
     if (!isTuiMode()) {
@@ -94,6 +118,7 @@ export async function patchFile(context, args) {
         filePath,
         changed,
         operation: 'patch',
+        ...(scratchPath ? { scratch: true } : {}),
         indexedChunks,
         retrievalTokensUsed,
         bytesWritten: Buffer.byteLength(patchedContent, 'utf-8'),

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

@@ -3,6 +3,7 @@ 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 { isWithinSessionScratchDir } from '../scratch-dir.js';
 import { repairFilePath } from './path-suggest.js';
 import { dotenvFitsRedactionBudget, getCurrentFileHash, recordReadCoverage, redactContentWithStableTokens, redactDotenvWithStableTokens, } from '../session-safety.js';
 import { readFileRange, truncate } from '../utils.js';
@@ -16,6 +17,7 @@ export async function readFile(context, args) {
         return { ok: false, error: 'filePath is required' };
     }
     const projectPath = normalizeProjectRelativePath(rootDir, filePath);
+    const scratchPath = path.isAbsolute(filePath) && isWithinSessionScratchDir(filePath);
     if (!projectPath && !path.isAbsolute(filePath)) {
         return {
             ok: false,
@@ -37,7 +39,7 @@ export async function readFile(context, args) {
         };
     }
     let content;
-    if (projectPath) {
+    if (projectPath || scratchPath) {
         try {
             content = readProjectFile(rootDir, filePath);
         }

package/dist/src/tools/replace-document-text.js

@@ -188,7 +188,13 @@ export async function replaceDocumentText(context, args) {
                 ok: false,
                 skipped: true,
                 filePath: targetPath,
-                error: 'User declined replace_document_text',
+                failureCategory: 'user_declined',
+                failureDetails: {
+                    category: 'user_declined',
+                    tool: 'replace_document_text',
+                    action: 'Respect the real user’s decision. Do not retry the same or an equivalent edit; reconsider the approach or ask one specific question if needed.',
+                },
+                error: 'The real user rejected this proposed document edit. Nothing was changed; this was not a tool failure or an automated system skip.',
             };
         }
     }

package/dist/src/tools/run-command.js

@@ -49,7 +49,13 @@ export async function runShellCommand(context, args) {
                 ok: false,
                 skipped: true,
                 command,
-                error: 'User declined command execution. Do not rerun this command or try a broader variant of it; either continue without it or ask the user one specific question about how to proceed.',
+                failureCategory: 'user_declined',
+                failureDetails: {
+                    category: 'user_declined',
+                    tool: 'run_command',
+                    action: 'Respect the real user’s decision. Do not retry the same or an equivalent action; reconsider the approach or ask one specific question if needed.',
+                },
+                error: 'The real user rejected this proposed command. Nothing was executed; this was not a tool failure or an automated system skip.',
             };
         }
     }
@@ -60,15 +66,7 @@ export async function runShellCommand(context, args) {
         requestSudoPassword,
         timeout: typeof args.timeout_ms === 'number' && args.timeout_ms > 0 ? args.timeout_ms : undefined,
     });
-    const repoSync = projectIndex.initialized
-        ? await syncIndexFromDisk(projectIndex)
-        : {
-            added: 0,
-            modified: 0,
-            removed: 0,
-            indexedChunks: 0,
-            retrievalTokensUsed: 0,
-        };
+    const repoSync = await syncRepoIndex(projectIndex, onStatus);
     invalidateShellDiagnosticsCache(rootDir);
     const diagnostics = buildDeferredShellDiagnostics('run_command');
     if (repoSync.added || repoSync.modified || repoSync.removed) {
@@ -98,6 +96,34 @@ export function boundCommandOutput(output) {
         `\n\n... (${output.length - headSize - tailSize} chars truncated) ...\n\n` +
         output.slice(-tailSize));
 }
+async function syncRepoIndex(projectIndex, onStatus) {
+    if (!projectIndex.initialized) {
+        return {
+            added: 0,
+            modified: 0,
+            removed: 0,
+            indexedChunks: 0,
+            retrievalTokensUsed: 0,
+        };
+    }
+    try {
+        return await syncIndexFromDisk(projectIndex);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        onStatus(`Command completed, but local index sync failed: ${message}`);
+        return {
+            added: 0,
+            modified: 0,
+            removed: 0,
+            indexedChunks: 0,
+            retrievalTokensUsed: 0,
+            skipped: true,
+            reason: 'local index sync failed after command execution',
+            error: message,
+        };
+    }
+}
 async function runBackgroundCommand(context, command, timeoutMs, repoHint) {
     const { rootDir, projectIndex, onStatus } = context;
     const started = await startBackgroundJob(command, rootDir, {
@@ -116,15 +142,7 @@ async function runBackgroundCommand(context, command, timeoutMs, repoHint) {
         };
     }
     const snapshot = started.snapshot;
-    const repoSync = projectIndex.initialized
-        ? await syncIndexFromDisk(projectIndex)
-        : {
-            added: 0,
-            modified: 0,
-            removed: 0,
-            indexedChunks: 0,
-            retrievalTokensUsed: 0,
-        };
+    const repoSync = await syncRepoIndex(projectIndex, onStatus);
     invalidateShellDiagnosticsCache(rootDir);
     if (repoSync.added || repoSync.modified || repoSync.removed) {
         onStatus(`Synced repo state after command (${repoSync.added} added, ${repoSync.modified} modified, ${repoSync.removed} removed).`);

package/dist/src/tools/run-node-script.js

@@ -175,7 +175,13 @@ export async function runNodeScript(context, args) {
                 ok: false,
                 skipped: true,
                 command: COMMAND_LABEL,
-                error: 'User declined command execution',
+                failureCategory: 'user_declined',
+                failureDetails: {
+                    category: 'user_declined',
+                    tool: 'run_node_script',
+                    action: 'Respect the real user’s decision. Do not retry the same or an equivalent action; reconsider the approach or ask one specific question if needed.',
+                },
+                error: 'The real user rejected this proposed script. Nothing was executed; this was not a tool failure or an automated system skip.',
             };
         }
     }
@@ -186,13 +192,27 @@ export async function runNodeScript(context, args) {
     const afterGitStatus = readGitStatusSignature(rootDir);
     const gitStatusCleanBeforeAndAfter = beforeGitStatus === '' && afterGitStatus === '';
     const shouldSync = context.projectIndex.initialized && !gitStatusCleanBeforeAndAfter;
-    const repoSync = shouldSync
-        ? await syncIndexFromDisk(context.projectIndex)
-        : emptyRepoSync(!context.projectIndex.initialized
+    let repoSync;
+    if (shouldSync) {
+        try {
+            repoSync = await syncIndexFromDisk(context.projectIndex);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            context.onStatus(`Node script completed, but local index sync failed: ${message}`);
+            repoSync = {
+                ...emptyRepoSync('local index sync failed after Node script execution'),
+                error: message,
+            };
+        }
+    }
+    else {
+        repoSync = emptyRepoSync(!context.projectIndex.initialized
             ? 'project index not initialized'
             : gitStatusCleanBeforeAndAfter
                 ? 'git status clean before and after'
                 : 'sync not needed');
+    }
     invalidateShellDiagnosticsCache(rootDir);
     if (repoSync.added || repoSync.modified || repoSync.removed) {
         context.onStatus(`Synced repo state after Node script (${repoSync.added} added, ${repoSync.modified} modified, ${repoSync.removed} removed).`);

package/dist/src/tools/str-replace.js

@@ -1,7 +1,7 @@
 import chalk from '../colors.js';
 import path from 'node:path';
 import { normalizeProjectRelativePath } from '../artifact-policy.js';
-import { readProjectFile, writeProjectFile } from '../patcher.js';
+import { classifyProjectPath, readProjectFile, writeProjectFile, } from '../patcher.js';
 import { repairFilePath } from './path-suggest.js';
 import { upsertIndexFile } from '../project-index.js';
 import { isTuiMode } from '../runtime-mode.js';
@@ -106,6 +106,21 @@ export async function strReplace(context, args) {
             failureCategory: 'invalid_argument',
         };
     }
+    const pathKind = classifyProjectPath(rootDir, filePath);
+    if (pathKind === 'outside') {
+        return {
+            ok: false,
+            filePath,
+            error: `Refusing to edit outside the project root: ${filePath}. Editable locations are the project root and the session scratch directory ($THEGITAI_SCRATCH_DIR).`,
+            failureCategory: 'invalid_argument',
+            failureDetails: {
+                category: 'invalid_argument',
+                tool: 'str_replace',
+                action: 'Edit files inside the project root, or use an absolute path under the session scratch directory ($THEGITAI_SCRATCH_DIR) for temporary files.',
+            },
+        };
+    }
+    const scratchPath = pathKind === 'scratch';
     let originalContent;
     try {
         originalContent = readProjectFile(rootDir, filePath);
@@ -169,7 +184,13 @@ export async function strReplace(context, args) {
                 ok: false,
                 skipped: true,
                 filePath,
-                error: 'User declined str_replace',
+                failureCategory: 'user_declined',
+                failureDetails: {
+                    category: 'user_declined',
+                    tool: 'str_replace',
+                    action: 'Respect the real user’s decision. Do not retry the same or an equivalent edit; reconsider the approach or ask one specific question if needed.',
+                },
+                error: 'The real user rejected this proposed edit. Nothing was changed; this was not a tool failure or an automated system skip.',
             };
         }
     }
@@ -178,13 +199,16 @@ export async function strReplace(context, args) {
     const replacements = changed ? (replaceAll ? n : 1) : 0;
     let indexedChunks = 0;
     let retrievalTokensUsed = 0;
-    if (changed) {
+    if (changed && !scratchPath) {
         const indexResult = await upsertIndexFile(projectIndex, filePath);
         indexedChunks = indexResult.indexedChunks;
         retrievalTokensUsed = indexResult.retrievalTokensUsed ?? 0;
     }
-    invalidateShellDiagnosticsCache(rootDir, filePath);
-    const diagnostics = runShellDiagnostics(rootDir, filePath);
+    let diagnostics;
+    if (!scratchPath) {
+        invalidateShellDiagnosticsCache(rootDir, filePath);
+        diagnostics = runShellDiagnostics(rootDir, filePath);
+    }
     const originalLines = originalContent.split('\n').length;
     const nextLines = nextContent.split('\n').length;
     if (!isTuiMode()) {
@@ -197,6 +221,7 @@ export async function strReplace(context, args) {
         filePath,
         changed,
         operation: 'str_replace',
+        ...(scratchPath ? { scratch: true } : {}),
         replacements,
         indexedChunks,
         retrievalTokensUsed,

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

@@ -1,7 +1,7 @@
 import chalk from '../colors.js';
 import path from 'node:path';
 import { normalizeProjectRelativePath } from '../artifact-policy.js';
-import { writeProjectFile } from '../patcher.js';
+import { classifyProjectPath, writeProjectFile } from '../patcher.js';
 import { upsertIndexFile } from '../project-index.js';
 import { isTuiMode } from '../runtime-mode.js';
 import { getCurrentFileHash, hasFreshFullReadCoverage, resolveRedactionTokens, } from '../session-safety.js';
@@ -25,9 +25,25 @@ export async function writeFile(context, args) {
             failureCategory: 'invalid_argument',
         };
     }
+    const pathKind = classifyProjectPath(rootDir, filePath);
+    if (pathKind === 'outside') {
+        return {
+            ok: false,
+            filePath,
+            error: `Refusing to write outside the project root: ${filePath}. Writable locations are the project root and the session scratch directory ($THEGITAI_SCRATCH_DIR).`,
+            failureCategory: 'invalid_argument',
+            failureDetails: {
+                category: 'invalid_argument',
+                tool: 'write_file',
+                action: 'Write inside the project root, or use an absolute path under the session scratch directory ($THEGITAI_SCRATCH_DIR) for temporary files.',
+            },
+        };
+    }
+    const scratchPath = pathKind === 'scratch';
     const coveragePath = normalizeProjectRelativePath(rootDir, filePath) ?? filePath;
     const currentHash = getCurrentFileHash(rootDir, filePath);
-    if (currentHash !== null &&
+    if (!scratchPath &&
+        currentHash !== null &&
         context.safety &&
         !hasFreshFullReadCoverage(context.safety, coveragePath, currentHash)) {
         return {
@@ -47,13 +63,16 @@ export async function writeFile(context, args) {
     const { changed } = writeProjectFile(rootDir, filePath, content);
     let indexedChunks = 0;
     let retrievalTokensUsed = 0;
-    if (changed) {
+    if (changed && !scratchPath) {
         const indexResult = await upsertIndexFile(projectIndex, filePath);
         indexedChunks = indexResult.indexedChunks;
         retrievalTokensUsed = indexResult.retrievalTokensUsed ?? 0;
     }
-    invalidateShellDiagnosticsCache(rootDir, filePath);
-    const diagnostics = runShellDiagnostics(rootDir, filePath);
+    let diagnostics;
+    if (!scratchPath) {
+        invalidateShellDiagnosticsCache(rootDir, filePath);
+        diagnostics = runShellDiagnostics(rootDir, filePath);
+    }
     if (!isTuiMode()) {
         const icon = changed ? '✨' : '📝';
         const label = changed ? 'Created/Updated' : 'Created/Updated (no change)';
@@ -64,6 +83,7 @@ export async function writeFile(context, args) {
         filePath,
         changed,
         operation: 'write',
+        ...(scratchPath ? { scratch: true } : {}),
         indexedChunks,
         retrievalTokensUsed,
         bytesWritten: Buffer.byteLength(content, 'utf-8'),

package/dist/src/ui/repl.js

@@ -7,6 +7,7 @@ import { chat, models } from '../api/index.js';
 import { isTurnCancelledError } from '../api/chat.js';
 import { getJobBufferedOutput, getJobOutputPreview, hasRunningBackgroundJobs, killAllBackgroundJobs, killBackgroundJob, listBackgroundJobs, setBackgroundJobSession, setBackgroundJobUpdateHook, } from '../background-jobs.js';
 import { clearTodos, listTodos, setTodoSession } from '../todo-list.js';
+import { setScratchSession } from '../scratch-dir.js';
 import { cancelActiveCommand } from '../executor.js';
 import { setCommandOutputHook, withTuiMode } from '../runtime-mode.js';
 import { collectBackgroundJobUiKillMutations, collectBackgroundJobUiOutputMutations, } from '../tool-executor.js';
@@ -558,6 +559,31 @@ function buildFileChangeEntry(event) {
             title: skipped ? `${verb} skipped: ${filePath}` : `${verb} failed: ${filePath}`,
         };
     }
+    if (result?.scratch === true) {
+        const scratchName = truncate(filePath.split(/[\\/]/).filter(Boolean).at(-1) ?? filePath, 72);
+        if (call.name === 'delete_file') {
+            return {
+                body: '',
+                filePath,
+                kind: 'tool',
+                title: result?.deleted === true
+                    ? `Removed scratch file: ${scratchName}`
+                    : `Scratch delete skipped: ${scratchName}`,
+            };
+        }
+        const content = typeof call.args?.content === 'string' ? call.args.content : '';
+        const lineSummary = call.name === 'write_file' && content
+            ? ` (${splitDiffLines(content).length} lines)`
+            : '';
+        return {
+            body: '',
+            filePath,
+            kind: 'tool',
+            title: call.name === 'write_file'
+                ? `Wrote scratch file: ${scratchName}${lineSummary}`
+                : `Edited scratch file: ${scratchName}`,
+        };
+    }
     if (call.name === 'undo_edit') {
         const dryRun = result?.dryRun === true ||
             result?.dry_run === true ||
@@ -1257,6 +1283,7 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
     }
     await withTuiMode(async () => {
         setBackgroundJobSession(session.sessionId);
+        setScratchSession(session.sessionId);
         setTodoSession(session.sessionId);
         const store = createShellStore(createInitialShellState(session, serverModels, debugUi));
         store.replaceTranscript(createSessionTranscript(session));
@@ -1933,6 +1960,7 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
                 const snapshot = await loadInteractiveSession(selected.id);
                 applySessionSnapshot(session, snapshot);
                 setBackgroundJobSession(session.sessionId);
+                setScratchSession(session.sessionId);
                 syncBackgroundJobsState();
                 setTodoSession(session.sessionId);
                 syncTodosState();
@@ -2531,6 +2559,7 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
             terminalTitle.dispose();
             killAllBackgroundJobs();
             setBackgroundJobSession(null);
+            setScratchSession(null);
             setTodoSession(null);
             setBackgroundJobUpdateHook(null);
             await bridge.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thegitai/cli",
-  "version": "1.0.0-preview.1",
+  "version": "1.0.0-preview.2",
   "description": "TheGitAI CLI client (source-visible, proprietary)",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://thegit.ai",
@@ -25,10 +25,10 @@
     "@lydell/node-pty-linux-x64": "1.1.0",
     "@lydell/node-pty-win32-arm64": "1.1.0",
     "@lydell/node-pty-win32-x64": "1.1.0",
-    "@thegitai/tui-darwin-arm64": "1.0.0-preview.1",
-    "@thegitai/tui-darwin-x64": "1.0.0-preview.1",
-    "@thegitai/tui-linux-x64": "1.0.0-preview.1",
-    "@thegitai/tui-win32-x64": "1.0.0-preview.1",
+    "@thegitai/tui-darwin-arm64": "1.0.0-preview.2",
+    "@thegitai/tui-darwin-x64": "1.0.0-preview.2",
+    "@thegitai/tui-linux-x64": "1.0.0-preview.2",
+    "@thegitai/tui-win32-x64": "1.0.0-preview.2",
     "@vscode/ripgrep": "1.18.0"
   },
   "publishConfig": {