@thegitai/cli 1.0.0-beta.15 → 1.0.0-beta.17

package/dist/src/client-environment.js

@@ -1,6 +1,7 @@
 import { accessSync, constants, readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { ensureSessionScratchDir } from './scratch-dir.js';
 const PACKAGE_MANAGER_CANDIDATES = [
     'apt',
     'apt-get',
@@ -123,5 +124,6 @@ export function collectClientEnvironment(options = {}) {
         shell: detectShell(platform, env),
         ...linuxDistro,
         packageManagers: detectPackageManagers(env, platform, executableExists),
+        scratchDir: options.scratchDir ?? ensureSessionScratchDir(),
     };
 }

package/dist/src/core/image-path-extractor.js

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadImageFromFile } from './clipboard.js';
@@ -9,12 +9,51 @@ const IMAGE_PATH_PATTERN = new RegExp(`"([^"]*\\.${EXT})"` +
     `|'([^']*\\.${EXT})'` +
     `|file://(\\S*\\.${EXT})` +
     `|(${BARE_PATH})`, 'gi');
+const EXTENSION_TOKEN = new RegExp(`^(?:[A-Za-z]:[\\\\/])?(?:\\\\ |${BARE_CHAR})+$`);
+const MAX_EXTENSION_TOKENS = 8;
+function isFile(p) {
+    try {
+        return statSync(p, { throwIfNoEntry: false })?.isFile() ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+function extendBareMatchAcrossSpaces(input, matchStart, raw, cwd) {
+    const baseInner = raw.replace(/\\ /g, ' ');
+    const baseExists = isFile(path.isAbsolute(baseInner) ? baseInner : path.resolve(cwd, baseInner));
+    let best = null;
+    let candidate = raw;
+    let start = matchStart;
+    let addedSeparator = false;
+    for (let hops = 0; hops < MAX_EXTENSION_TOKENS; hops++) {
+        if (start < 2 || input[start - 1] !== ' ' || /\s/.test(input[start - 2]))
+            break;
+        let i = start - 2;
+        while (i >= 0 && !/\s/.test(input[i]))
+            i--;
+        const tokenStart = i + 1;
+        const token = input.slice(tokenStart, start - 1);
+        if (!EXTENSION_TOKEN.test(token))
+            break;
+        candidate = `${token} ${candidate}`;
+        start = tokenStart;
+        addedSeparator = addedSeparator || /[\\/]/.test(token);
+        if (baseExists && !addedSeparator)
+            continue;
+        const inner = candidate.replace(/\\ /g, ' ');
+        const resolved = path.isAbsolute(inner) ? inner : path.resolve(cwd, inner);
+        if (isFile(resolved))
+            best = candidate;
+    }
+    return best ?? raw;
+}
 function detectImagePaths(input, cwd) {
     const regex = new RegExp(IMAGE_PATH_PATTERN.source, IMAGE_PATH_PATTERN.flags);
-    const rawsByPath = new Map();
+    const detected = [];
     let match;
     while ((match = regex.exec(input)) !== null) {
-        const raw = match[0];
+        let raw = match[0];
         if (match[4] != null && raw.includes('://'))
             continue;
         let inner;
@@ -46,9 +85,21 @@ function detectImagePaths(input, cwd) {
             }
         }
         else {
-            inner = match[4].replace(/\\ /g, ' ');
+            raw = extendBareMatchAcrossSpaces(input, match.index, raw, cwd);
+            inner = raw.replace(/\\ /g, ' ');
         }
         const resolvedPath = path.isAbsolute(inner) ? inner : path.resolve(cwd, inner);
+        const start = match.index - (raw.length - match[0].length);
+        while (detected.length > 0) {
+            const prev = detected[detected.length - 1];
+            if (prev.start + prev.raw.length <= start)
+                break;
+            detected.pop();
+        }
+        detected.push({ resolvedPath, raw, start });
+    }
+    const rawsByPath = new Map();
+    for (const { resolvedPath, raw } of detected) {
         const existing = rawsByPath.get(resolvedPath);
         if (existing) {
             existing.push(raw);

package/dist/src/executor.js

@@ -6,6 +6,7 @@ import os from 'os';
 import path from 'path';
 import { ARTIFACT_INSPECT_BLOCK_DIRS, getBlockedArtifactInspectDir, relativeProjectPath, } from './artifact-policy.js';
 import { emitCommandOutput, isTuiMode } from './runtime-mode.js';
+import { ensureSessionScratchDir, isInsideTheGitAiScratch, sessionScratchDir, } from './scratch-dir.js';
 const requireFromHere = createRequire(import.meta.url);
 let nodePtyCache;
 function loadNodePty() {
@@ -217,6 +218,7 @@ function isExistingDirectory(absPath) {
         return false;
     }
 }
+const OS_TEMP_BLOCK_MARKER = 'os-temp:';
 function getBlockedOsTempInspection(rawToken, rootDir) {
     const token = normalizeToken(rawToken);
     if (!token || !path.isAbsolute(token))
@@ -224,6 +226,8 @@ function getBlockedOsTempInspection(rawToken, rootDir) {
     const resolved = path.resolve(token);
     if (!isInsideOsTemp(resolved))
         return null;
+    if (isInsideTheGitAiScratch(resolved))
+        return null;
     if (rootDir) {
         const resolvedRoot = path.resolve(rootDir);
         if (resolved === resolvedRoot ||
@@ -234,7 +238,7 @@ function getBlockedOsTempInspection(rawToken, rootDir) {
     if (resolved === path.resolve(os.tmpdir()) ||
         hasPathGlob(token) ||
         isExistingDirectory(resolved)) {
-        return path.basename(os.tmpdir()) || os.tmpdir();
+        return `${OS_TEMP_BLOCK_MARKER}${path.basename(os.tmpdir()) || os.tmpdir()}`;
     }
     return null;
 }
@@ -250,6 +254,9 @@ function findBlockedDirForToken(rawToken, rootDir, baseDir, allowBareDirMatch =
         const resolved = path.isAbsolute(token)
             ? path.resolve(token)
             : path.resolve(baseDir ?? rootDir, token);
+        const osTempResolved = getBlockedOsTempInspection(resolved, rootDir);
+        if (osTempResolved)
+            return osTempResolved;
         return getBlockedProjectPathDir(resolved, rootDir);
     }
     if (!allowBareDirMatch || !BLOCKED_PATH_INSPECT_DIRS.has(token)) {
@@ -386,11 +393,16 @@ function findBlockedDirInCommandTokens(command, rootDir, baseDir) {
     }
     return null;
 }
+function expandTempEnvRefs(command) {
+    return command
+        .replace(/\$\{THEGITAI_SCRATCH_DIR[^}]*\}|\$THEGITAI_SCRATCH_DIR\b/g, sessionScratchDir())
+        .replace(/\$\{TMPDIR[^}]*\}|\$TMPDIR\b/g, process.env.TMPDIR || os.tmpdir());
+}
 function findIgnoredPathInspection(command, rootDir) {
     if (!FILE_INSPECTION_COMMAND_PATTERN.test(command)) {
         return null;
     }
-    const haystack = maskNonPathIgnoreDirTokens(maskHereDocumentBodies(command));
+    const haystack = maskNonPathIgnoreDirTokens(maskHereDocumentBodies(expandTempEnvRefs(command)));
     const baseDir = getCommandBaseDir(haystack, rootDir);
     const blockedDir = findBlockedDirInCommandTokens(haystack, rootDir, baseDir);
     if (blockedDir) {
@@ -447,7 +459,7 @@ function shouldDropOutputLine(line, rootDir, baseDir) {
 function isLsDirectoryHeader(line) {
     return /^\.?\/?.+:$/.test(line) && !line.includes(' ');
 }
-function sanitizeCommandText(command, text, rootDir) {
+export function sanitizeCommandText(command, text, rootDir) {
     if (!text)
         return '';
     const lines = text.split('\n');
@@ -522,7 +534,7 @@ export function cancelActiveCommand() {
         cancelled: true,
     });
 }
-function terminateChild(child, signal) {
+export function terminateChild(child, signal) {
     if (!child?.pid)
         return;
     if (process.platform === 'win32') {
@@ -550,10 +562,17 @@ function terminateChild(child, signal) {
     }
 }
 export function getBlockedPathInspectDir(command, rootDir) {
-    return findIgnoredPathInspection(command, rootDir);
+    const blocked = findIgnoredPathInspection(command, rootDir);
+    return blocked?.startsWith(OS_TEMP_BLOCK_MARKER)
+        ? blocked.slice(OS_TEMP_BLOCK_MARKER.length)
+        : blocked;
 }
 export function getBlockedCommandReason(command, hasTimeout, rootDir) {
     const ignoredDir = findIgnoredPathInspection(command, rootDir);
+    if (ignoredDir?.startsWith(OS_TEMP_BLOCK_MARKER)) {
+        const tempName = ignoredDir.slice(OS_TEMP_BLOCK_MARKER.length);
+        return `Listing or scanning the shared OS temp directory (${tempName}) is blocked because it can contain other users' and processes' files. Use the session scratch directory ${ensureSessionScratchDir()} for temporary scripts and files — creating, running, and listing are all allowed there — or reference an exact file path.`;
+    }
     if (ignoredDir) {
         return `Command inspects an off-limits generated or dependency directory (${ignoredDir}). Avoid that path.`;
     }
@@ -572,7 +591,7 @@ export function getBlockedCommandReason(command, hasTimeout, rootDir) {
     }
     return null;
 }
-function commandUsesSudo(command) {
+export function commandUsesSudo(command) {
     return /\bsudo\b/.test(getUnquotedShellText(command));
 }
 export function sudoPromptFromTail(text) {
@@ -600,7 +619,7 @@ function redactSecrets(text, secrets) {
     }
     return redacted;
 }
-function buildCommandEnv(cwd) {
+export function buildCommandEnv(cwd) {
     const venvBin = detectVenvBin(cwd);
     const envPath = buildCommandPath(process.env.PATH, venvBin ? [venvBin] : []);
     return {
@@ -615,6 +634,7 @@ function buildCommandEnv(cwd) {
         npm_config_fund: 'false',
         npm_config_audit: 'false',
         NUXI_INIT_SKIP_PROMPT: 'true',
+        THEGITAI_SCRATCH_DIR: ensureSessionScratchDir(),
     };
 }
 function sanitizePtyOutput(command, output, cwd, secrets) {

package/dist/src/help-text.js

@@ -73,6 +73,10 @@ const HELP_MARKDOWN = [
     '- `/model` — list supported models and pick one',
     '- `/model <id>` — switch the active model without clearing history',
     '- `/resume` — resume a saved session for this repo',
+    '- `/jobs` — open the background jobs picker (Enter expands/collapses,',
+    '  k kills the selected job)',
+    '- `/jobs output <id>` — print one job\'s full captured output',
+    '- `/jobs kill <id>` — kill one background job',
     '- `/clear` — clear the current conversation history',
     '- `/exit` — quit the session',
     '',
@@ -85,6 +89,12 @@ const HELP_MARKDOWN = [
     '  command and keeps the password masked and local.',
     '- `-y` / `--yes` at startup auto-approves every shell command and file',
     '  edit for the whole session — use with care.',
+    '- Long-running commands (e.g. dev servers) can run as managed background',
+    '  jobs after the same approval as any other command. Background output',
+    '  stays quiet once the model has responded; the footer shows only a compact',
+    '  shell-running indicator, `/jobs` lists, inspects, and kills jobs, and',
+    '  killed jobs disappear immediately. Every job is killed when the session',
+    '  ends.',
     '- File and shell operations are confined to the target repo root.',
     '- Sensitive directories (`.git`, `node_modules`, build output) are',
     '  never indexed.',

package/dist/src/scratch-dir.js

@@ -0,0 +1,57 @@
+import { chmodSync, lstatSync, mkdirSync, mkdtempSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+let cachedScratchDir = null;
+export function sessionScratchDir() {
+    if (!cachedScratchDir) {
+        cachedScratchDir = path.join(os.tmpdir(), `thegitai-${process.pid}`);
+    }
+    return cachedScratchDir;
+}
+function isSquattedScratchRoot(dir) {
+    try {
+        const st = lstatSync(dir);
+        if (st.isSymbolicLink() || !st.isDirectory())
+            return true;
+        if (process.platform !== 'win32' &&
+            typeof process.getuid === 'function' &&
+            st.uid !== process.getuid()) {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+export function ensureSessionScratchDir() {
+    const dir = sessionScratchDir();
+    try {
+        if (isSquattedScratchRoot(dir)) {
+            cachedScratchDir = mkdtempSync(path.join(os.tmpdir(), 'thegitai-'));
+            return cachedScratchDir;
+        }
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (process.platform !== 'win32') {
+            chmodSync(dir, 0o700);
+        }
+    }
+    catch {
+    }
+    return sessionScratchDir();
+}
+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)) {
+        return false;
+    }
+    return !isSquattedScratchRoot(path.join(tempRoot, first));
+}

package/dist/src/tool-executor.js

@@ -1,7 +1,9 @@
+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';
 const EDIT_FILE_PATH_ARG_ALIASES = [
@@ -12,6 +14,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') {
@@ -20,6 +23,10 @@ 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();
+    }
     const filePath = getEditToolFilePath(call);
     if (filePath)
         return filePath;
@@ -53,6 +60,84 @@ function editToolWritesSeparateOutput(call) {
     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;
@@ -146,6 +231,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,
@@ -167,28 +253,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/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,6 +18,7 @@ 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 { writeFile } from './write-file.js';
@@ -44,6 +46,8 @@ export const TOOL_MAP = {
     undo_edit: undoEdit,
     run_command: runShellCommand,
     run_node_script: runNodeScript,
+    shell_job_output: shellJobOutput,
+    shell_job_kill: shellJobKill,
 };
 function invalidToolCall(error) {
     return {

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

@@ -1,4 +1,5 @@
 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 || args.run_in_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 stopped.`
+            : command);
         if (!approved) {
             if (!isTuiMode())
                 console.log(chalk.dim(`  ⏭  Skipped: ${command}`));
@@ -45,10 +49,13 @@ export async function runShellCommand(context, args) {
                 ok: false,
                 skipped: true,
                 command,
-                error: 'User declined command execution',
+                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.',
             };
         }
     }
+    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,
@@ -67,17 +74,9 @@ export async function runShellCommand(context, args) {
     if (repoSync.added || repoSync.modified || repoSync.removed) {
         onStatus(`Synced repo state after command (${repoSync.added} added, ${repoSync.modified} modified, ${repoSync.removed} removed).`);
     }
-    let output = typeof result.output === 'string'
-        ? redactConnectionStringCredentials(result.output)
+    const output = typeof result.output === 'string'
+        ? boundCommandOutput(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);
-    }
     return {
         ok: result.exitCode === 0,
         command,
@@ -90,3 +89,72 @@ export async function runShellCommand(context, args) {
         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 runBackgroundCommand(context, command, timeoutMs, repoHint) {
+    const { rootDir, projectIndex, onStatus } = context;
+    const started = await startBackgroundJob(command, rootDir, {
+        startupWaitMs: typeof timeoutMs === 'number' && timeoutMs > 0 ? timeoutMs : undefined,
+    });
+    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 = projectIndex.initialized
+        ? await syncIndexFromDisk(projectIndex)
+        : {
+            added: 0,
+            modified: 0,
+            removed: 0,
+            indexedChunks: 0,
+            retrievalTokensUsed: 0,
+        };
+    invalidateShellDiagnosticsCache(rootDir);
+    if (repoSync.added || repoSync.modified || repoSync.removed) {
+        onStatus(`Synced repo state after command (${repoSync.added} added, ${repoSync.modified} modified, ${repoSync.removed} removed).`);
+    }
+    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: snapshot.exitCode === 0,
+        backgrounded: true,
+        command,
+        jobId: snapshot.id,
+        status: snapshot.status,
+        exitCode: snapshot.exitCode,
+        output,
+        note: `Background job ${snapshot.id} finished during the startup window.`,
+        repoSync,
+        retrievalTokensUsed: repoSync.retrievalTokensUsed,
+        repoHint,
+    };
+}

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

@@ -3,6 +3,7 @@ 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'],
         });