@thegitai/cli 1.0.0-beta.9 → 1.0.0-preview.10

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

@@ -1,5 +1,5 @@
-import chalk from 'chalk';
-import { deleteProjectFile } from '../patcher.js';
+import chalk from '../colors.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/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';
@@ -17,8 +18,10 @@ 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),
@@ -44,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,15 +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 { 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';
 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' };
@@ -28,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);
@@ -67,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()) {
@@ -93,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/path-suggest.js

@@ -1,9 +1,6 @@
-import { readdirSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import path from 'node:path';
-import { isSensitiveProjectPath } from '../artifact-policy.js';
-// "File not found" recovery hint: when a model mistypes a filename (most
-// often Unicode punctuation — a straight ' for a curly ’ — or a small typo),
-// suggest the closest real file from the same directory.
+import { isSensitiveProjectPath, shouldIgnoreArtifactPath, } from '../artifact-policy.js';
 function foldName(name) {
     return name
         .normalize('NFC')
@@ -46,9 +43,6 @@ export function suggestClosestPath(rootDir, missingPath) {
     let best = null;
     let bestDistance = Number.POSITIVE_INFINITY;
     for (const candidate of candidates) {
-        // Never suggest a file the caller would refuse to read/write directly:
-        // probing a near-miss like `.enx` or `credential.docx` must not leak the
-        // existence of `.env`/credentials through the recovery hint.
         const candidateRelative = path.relative(rootDir, path.join(directory, candidate));
         if (isSensitiveProjectPath(candidateRelative))
             continue;
@@ -64,3 +58,82 @@ export function suggestClosestPath(rootDir, missingPath) {
     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,7 +1,7 @@
 import path from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { isSensitiveProjectPath, normalizeProjectRelativePath, } from '../artifact-policy.js';
-import { suggestClosestPath } from './path-suggest.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');
@@ -71,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' };
     }

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

@@ -3,6 +3,8 @@ 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';
 const MAX_FILE_READ_CHARS = 12000;
@@ -10,11 +12,12 @@ 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' };
     }
     const projectPath = normalizeProjectRelativePath(rootDir, filePath);
+    const scratchPath = path.isAbsolute(filePath) && isWithinSessionScratchDir(filePath);
     if (!projectPath && !path.isAbsolute(filePath)) {
         return {
             ok: false,
@@ -36,18 +39,28 @@ export async function readFile(context, args) {
         };
     }
     let content;
-    if (projectPath) {
+    if (projectPath || scratchPath) {
         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');
@@ -57,10 +70,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) &&

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

@@ -1,10 +1,10 @@
-import chalk from 'chalk';
+import chalk from '../colors.js';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { isSensitiveProjectPath, normalizeProjectRelativePath, } from '../artifact-policy.js';
 import { readCliAuthConfig } from '../api/auth.js';
 import { resolveProjectPath, writeProjectFileBuffer } from '../patcher.js';
-import { suggestClosestPath } from './path-suggest.js';
+import { repairFilePath, suggestClosestPath } from './path-suggest.js';
 import { isTuiMode } from '../runtime-mode.js';
 function normalizeReplacements(value) {
     if (!Array.isArray(value))
@@ -76,7 +76,7 @@ async function replaceDocumentTextOnServer(config, fileName, fileData, replaceme
     return data;
 }
 export async function replaceDocumentText(context, args) {
-    const sourceRaw = String(args.filePath ?? args.file_path ?? '').trim();
+    const sourceRaw = repairFilePath(context.rootDir, String(args.filePath ?? args.file_path ?? '').trim());
     if (!sourceRaw) {
         return { ok: false, error: 'filePath is required' };
     }
@@ -149,9 +149,6 @@ export async function replaceDocumentText(context, args) {
             failureCategory: serverResult.failureCategory ?? 'external_service',
         };
     }
-    // Validate-only: report per-replacement match info without touching the file.
-    // changed:false marks it non-mutating so the agent loop does not count a
-    // dry-run as an applied edit.
     if (validateOnly) {
         return {
             ok: true,
@@ -162,8 +159,6 @@ export async function replaceDocumentText(context, args) {
             results: serverResult.results,
         };
     }
-    // No replacement matched: nothing was written. Surface per-item reasons so
-    // the model can correct and resend only the failing entries.
     const replacementCount = Number(serverResult.replacementCount ?? 0);
     if (replacementCount === 0) {
         const failures = Array.isArray(serverResult.replacements)
@@ -193,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.',
             };
         }
     }
@@ -220,9 +221,6 @@ export async function replaceDocumentText(context, args) {
         failedCount: serverResult.failedCount,
         replacements: serverResult.replacements,
         bytesWritten: nextData.length,
-        // A partial batch still wrote the matched entries (changed:true above), but
-        // the loop must reflect and repair the missed entries — needsRepair forces
-        // that without losing credit for the applied edits.
         ...(failedCount > 0
             ? {
                 needsRepair: true,

package/dist/src/tools/restore-checkpoint.js

@@ -1,4 +1,4 @@
-import chalk from 'chalk';
+import chalk from '../colors.js';
 import { isTuiMode } from '../runtime-mode.js';
 import { createPromptCheckpoint, restoreCheckpointFiles, } from '../session-safety.js';
 import { invalidateShellDiagnosticsCache, runShellDiagnostics, } from './shell-diagnostics.js';

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

@@ -1,4 +1,5 @@
-import chalk from 'chalk';
+import chalk from '../colors.js';
+import { startBackgroundJob } from '../background-jobs.js';
 import { getBlockedCommandReason, runCommand, } from '../executor.js';
 import { syncIndexFromDisk } from '../project-index.js';
 import { isTuiMode } from '../runtime-mode.js';
@@ -12,9 +13,10 @@ export async function runShellCommand(context, args) {
     if (!command) {
         return { ok: false, error: 'command is required' };
     }
+    const runInBackground = args.background === true;
     const hasTimeout = typeof args.timeout_ms === 'number' && args.timeout_ms > 0;
     const repoHint = buildNestedGitHint(rootDir, command);
-    const blockedReason = getBlockedCommandReason(command, hasTimeout, rootDir);
+    const blockedReason = getBlockedCommandReason(command, hasTimeout || runInBackground, rootDir);
     if (blockedReason) {
         const error = blockedReason;
         if (!isTuiMode())
@@ -37,7 +39,9 @@ export async function runShellCommand(context, args) {
                 error: 'confirmCommand is required when autoYes is false',
             };
         }
-        const approved = await confirmCommand(command);
+        const approved = await confirmCommand(runInBackground
+            ? `${command}\n\nRuns as a managed background job until it exits or is killed.`
+            : command);
         if (!approved) {
             if (!isTuiMode())
                 console.log(chalk.dim(`  ⏭  Skipped: ${command}`));
@@ -45,50 +49,131 @@ export async function runShellCommand(context, args) {
                 ok: false,
                 skipped: true,
                 command,
-                error: 'User declined command execution',
+                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.',
             };
         }
     }
+    if (runInBackground) {
+        return runBackgroundCommand(context, command, args.timeout_ms, repoHint);
+    }
     const result = await runCommand(command, rootDir, {
         requestSudoPassword,
         timeout: typeof args.timeout_ms === 'number' && args.timeout_ms > 0 ? args.timeout_ms : undefined,
     });
-    const repoSync = projectIndex.initialized
-        ? await syncIndexFromDisk(projectIndex)
-        : {
+    const repoSync = await syncRepoIndex(projectIndex, onStatus);
+    invalidateShellDiagnosticsCache(rootDir);
+    const diagnostics = buildDeferredShellDiagnostics('run_command');
+    if (repoSync.added || repoSync.modified || repoSync.removed) {
+        onStatus(`Synced repo state after command (${repoSync.added} added, ${repoSync.modified} modified, ${repoSync.removed} removed).`);
+    }
+    const output = typeof result.output === 'string'
+        ? boundCommandOutput(redactConnectionStringCredentials(result.output))
+        : result.output;
+    return {
+        ok: result.exitCode === 0,
+        command,
+        exitCode: result.exitCode,
+        timedOut: result.timedOut,
+        output,
+        repoSync,
+        retrievalTokensUsed: repoSync.retrievalTokensUsed,
+        diagnostics,
+        repoHint,
+    };
+}
+export function boundCommandOutput(output) {
+    if (output.length <= MAX_OUTPUT_CHARS)
+        return output;
+    const headSize = Math.floor(MAX_OUTPUT_CHARS * 0.2);
+    const tailSize = MAX_OUTPUT_CHARS - headSize;
+    return (output.slice(0, headSize) +
+        `\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, {
+        startupWaitMs: typeof timeoutMs === 'number' && timeoutMs > 0 ? timeoutMs : undefined,
+        sessionId: context.sessionId,
+    });
+    if (!started.ok || !started.snapshot) {
+        if (!isTuiMode())
+            console.log(chalk.red(`\n  ✖ ${started.error}`));
+        return {
+            ok: false,
+            blocked: true,
+            command,
+            error: started.error ?? 'Background job failed to start.',
+            repoHint,
+        };
+    }
+    const snapshot = started.snapshot;
+    const repoSync = await syncRepoIndex(projectIndex, onStatus);
     invalidateShellDiagnosticsCache(rootDir);
-    const diagnostics = buildDeferredShellDiagnostics('run_command');
     if (repoSync.added || repoSync.modified || repoSync.removed) {
         onStatus(`Synced repo state after command (${repoSync.added} added, ${repoSync.modified} modified, ${repoSync.removed} removed).`);
     }
-    // Redact connection-string passwords so shell output (e.g. `cat .env`,
-    // `printenv`) cannot leak them into history or telemetry.
-    let output = typeof result.output === 'string'
-        ? redactConnectionStringCredentials(result.output)
-        : result.output;
-    if (typeof output === 'string' && output.length > MAX_OUTPUT_CHARS) {
-        const headSize = Math.floor(MAX_OUTPUT_CHARS * 0.2);
-        const tailSize = MAX_OUTPUT_CHARS - headSize;
-        output =
-            output.slice(0, headSize) +
-                `\n\n... (${output.length - headSize - tailSize} chars truncated) ...\n\n` +
-                output.slice(-tailSize);
+    const output = boundCommandOutput(redactConnectionStringCredentials(started.startupOutput ?? '').trim());
+    if (snapshot.status === 'running') {
+        return {
+            ok: true,
+            backgrounded: true,
+            command,
+            jobId: snapshot.id,
+            status: 'running',
+            pid: snapshot.pid,
+            output,
+            note: `Background job ${snapshot.id} is running. Use shell_job_output to poll status and new output, and shell_job_kill to stop it.`,
+            repoSync,
+            retrievalTokensUsed: repoSync.retrievalTokensUsed,
+            repoHint,
+        };
     }
     return {
-        ok: result.exitCode === 0,
+        ok: snapshot.exitCode === 0,
+        backgrounded: true,
         command,
-        exitCode: result.exitCode,
-        timedOut: result.timedOut,
+        jobId: snapshot.id,
+        status: snapshot.status,
+        exitCode: snapshot.exitCode,
         output,
+        note: `Background job ${snapshot.id} finished during the startup window.`,
         repoSync,
         retrievalTokensUsed: repoSync.retrievalTokensUsed,
-        diagnostics,
         repoHint,
     };
 }

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

@@ -1,8 +1,9 @@
-import chalk from 'chalk';
+import chalk from '../colors.js';
 import { execFileSync, spawn } from 'node:child_process';
 import { syncIndexFromDisk } from '../project-index.js';
 import { isTuiMode } from '../runtime-mode.js';
 import { buildDeferredShellDiagnostics, invalidateShellDiagnosticsCache, } from './shell-diagnostics.js';
+import { ensureSessionScratchDir } from '../scratch-dir.js';
 const DEFAULT_TIMEOUT = 5 * 60 * 1000;
 const MAX_OUTPUT_CHARS = 4000;
 const MAX_CAPTURE_CHARS = 1024 * 1024;
@@ -99,6 +100,7 @@ function executeNodeScript(rootDir, script, timeout) {
                 npm_config_progress: 'false',
                 npm_config_fund: 'false',
                 npm_config_audit: 'false',
+                THEGITAI_SCRATCH_DIR: ensureSessionScratchDir(),
             },
             stdio: ['pipe', 'pipe', 'pipe'],
         });
@@ -173,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.',
             };
         }
     }
@@ -184,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).`);