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

package/dist/src/api/chat.js

@@ -1,10 +1,12 @@
 import { drainBackgroundJobNotifications } from '../background-jobs.js';
 import { createPromptCheckpoint, sanitizeSessionSafetyForServer, } from '../session-safety.js';
-import { applySessionSnapshot, snapshotFromSession, } from '../session-store.js';
+import { applySessionSnapshot, saveSessionState, 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';
+import { formatTurnFailureMarker } from '../turn-failure-marker.js';
 export class TurnCancelledError extends Error {
     name = 'TurnCancelledError';
     constructor(message = 'Turn cancelled.') {
@@ -16,11 +18,13 @@ export class ChatTurnFailedError extends Error {
     category;
     retryable;
     traceId;
-    constructor(message, category = 'unknown_error', retryable = false, traceId = '') {
+    partialSnapshot;
+    constructor(message, category = 'unknown_error', retryable = false, traceId = '', partialSnapshot) {
         super(traceId ? `${message}\nTrace ID: ${traceId}` : message);
         this.category = category;
         this.retryable = retryable;
         this.traceId = traceId;
+        this.partialSnapshot = partialSnapshot;
     }
 }
 export function isTurnCancelledError(error) {
@@ -50,6 +54,7 @@ function parseSseBlock(block) {
         return { event, data: text };
     }
 }
+let toolStateSeqCounter = 0;
 function toolStateFromSession(session) {
     return {
         autoYes: session.autoYes,
@@ -92,17 +97,30 @@ export function preserveCancelledTurnInput(session, input) {
             return;
         break;
     }
-    session.history.push({ role: 'user', parts: [{ text }], kind: 'turnStart' });
+    session.history.push({
+        role: 'user',
+        parts: [{ text }],
+        kind: 'turnStart',
+        userInput: text,
+    });
+}
+function appendTurnFailureMarker(session, category) {
+    session.history.push({
+        role: 'model',
+        parts: [{ text: formatTurnFailureMarker(category) }],
+    });
 }
 function preserveFailedTurnInput(session, input, category) {
     const text = input.trim();
     if (!text)
         return;
-    session.history.push({ role: 'user', parts: [{ text }], kind: 'turnStart' });
     session.history.push({
-        role: 'model',
-        parts: [{ text: `Turn failed before completion: ${category}.` }],
+        role: 'user',
+        parts: [{ text }],
+        kind: 'turnStart',
+        userInput: text,
     });
+    appendTurnFailureMarker(session, category);
 }
 function historyHasToolCall(session, callId) {
     return session.history.some((entry) => (entry.parts ?? []).some((part) => String(part?.functionCall?.id ?? '') === callId));
@@ -143,6 +161,9 @@ function publicStatusMessage(data) {
         : 'tool';
     if (event.phase === 'thinking')
         return 'Thinking...';
+    if (event.phase === 'analyzing_image') {
+        return (event.imageCount ?? 1) > 1 ? 'Analyzing images...' : 'Analyzing image...';
+    }
     if (event.phase === 'running_tool')
         return `Running ${toolName}...`;
     if (event.phase === 'waiting_for_tool')
@@ -183,6 +204,7 @@ async function postToolResult({ config, turnId, event, result, session, fetchImp
         toolCallId: event.call.id,
         result,
         toolState: toolStateFromSession(session),
+        toolStateSeq: ++toolStateSeqCounter,
     };
     const trace = createTraceContext(traceId);
     const response = await fetchImpl(`${normalizeServerUrl(config.serverUrl)}/v1/chat/turn/${encodeURIComponent(turnId)}/tool-result`, {
@@ -201,6 +223,29 @@ async function postToolResult({ config, turnId, event, result, session, fetchImp
         throw await readErrorResponse(response, trace.traceId);
     }
 }
+const turnIdOverrides = new WeakMap();
+function enterServerTurnId(session, serverSessionTurnId) {
+    const active = turnIdOverrides.get(session);
+    if (active) {
+        active.depth += 1;
+        return;
+    }
+    turnIdOverrides.set(session, {
+        previousTurnId: session.turnState.id,
+        depth: 1,
+    });
+    session.turnState.id = serverSessionTurnId;
+}
+function exitServerTurnId(session) {
+    const active = turnIdOverrides.get(session);
+    if (!active)
+        return;
+    active.depth -= 1;
+    if (active.depth === 0) {
+        session.turnState.id = active.previousTurnId;
+        turnIdOverrides.delete(session);
+    }
+}
 async function executeAndPostToolResult({ config, projectIndex, session, event, input, fetchImpl, signal, traceId, }) {
     const turnId = String(event?.turnId ?? '').trim();
     if (!turnId || !event?.call?.id || !event.call.name) {
@@ -209,10 +254,9 @@ async function executeAndPostToolResult({ config, projectIndex, session, event,
     if (signal?.aborted) {
         throw new TurnCancelledError();
     }
-    const previousTurnId = session.turnState.id;
     const serverSessionTurnId = String(event.sessionTurnId ?? '').trim();
     if (serverSessionTurnId) {
-        session.turnState.id = serverSessionTurnId;
+        enterServerTurnId(session, serverSessionTurnId);
         if (!session.clientState.safety.checkpoints.some((checkpoint) => checkpoint.turnId === serverSessionTurnId)) {
             createPromptCheckpoint(session.clientState.safety, 'prompt boundary', serverSessionTurnId);
         }
@@ -235,7 +279,9 @@ async function executeAndPostToolResult({ config, projectIndex, session, event,
         });
     }
     finally {
-        session.turnState.id = previousTurnId;
+        if (serverSessionTurnId) {
+            exitServerTurnId(session);
+        }
     }
 }
 async function consumeTurnStream({ response, config, projectIndex, session, input, fetchImpl, signal, traceId, }) {
@@ -248,8 +294,40 @@ async function consumeTurnStream({ response, config, projectIndex, session, inpu
     const finalResult = {
         current: null,
     };
+    const pendingParallelTools = [];
+    let firstParallelFailure = null;
+    let rejectOnParallelFailure = null;
+    const parallelToolFailure = new Promise((_, reject) => {
+        rejectOnParallelFailure = reject;
+    });
+    parallelToolFailure.catch(() => { });
+    function recordParallelFailure(error) {
+        const failure = error ?? new Error('Local tool execution failed.');
+        if (firstParallelFailure == null) {
+            firstParallelFailure = failure;
+            rejectOnParallelFailure?.(failure);
+        }
+        return failure;
+    }
+    async function drainParallelTools() {
+        if (!pendingParallelTools.length)
+            return;
+        const pending = pendingParallelTools.splice(0);
+        const outcomes = await Promise.all(pending);
+        for (const outcome of outcomes) {
+            if (outcome != null)
+                throw outcome;
+        }
+    }
     async function handleEvent(event) {
         if (event.event === 'status') {
+            const data = event.data;
+            if (data?.phase === 'analyzing_image') {
+                session.onImageAnalysis?.(Math.max(1, Number(data.imageCount ?? 1) || 1));
+            }
+            else if (data?.phase) {
+                session.onImageAnalysis?.(0);
+            }
             const message = publicStatusMessage(event.data);
             if (message)
                 session.onStatus(message);
@@ -259,11 +337,26 @@ async function consumeTurnStream({ response, config, projectIndex, session, inpu
             return;
         }
         if (event.event === 'tool-call') {
+            const data = event.data;
+            if (data?.parallelSafe === true) {
+                pendingParallelTools.push(executeAndPostToolResult({
+                    config,
+                    projectIndex,
+                    session,
+                    event: data,
+                    input,
+                    fetchImpl,
+                    signal,
+                    traceId,
+                }).then(() => null, (error) => recordParallelFailure(error)));
+                return;
+            }
+            await drainParallelTools();
             await executeAndPostToolResult({
                 config,
                 projectIndex,
                 session,
-                event: event.data,
+                event: data,
                 input,
                 fetchImpl,
                 signal,
@@ -279,35 +372,47 @@ async function consumeTurnStream({ response, config, projectIndex, session, inpu
             return;
         }
         if (event.event === 'result') {
+            await drainParallelTools();
             finalResult.current = event.data;
             return;
         }
         if (event.event === 'cancelled' || event.event === 'error') {
+            await drainParallelTools().catch(() => { });
             const message = String(event.data?.message ?? 'Server chat failed.');
             if (event.event === 'cancelled') {
                 throw new TurnCancelledError(message);
             }
-            throw new ChatTurnFailedError(message, typeof event.data?.category === 'string' ? event.data.category : 'unknown_error', Boolean(event.data?.retryable), typeof event.data?.traceId === 'string' ? event.data.traceId : traceId);
+            throw new ChatTurnFailedError(message, typeof event.data?.category === 'string' ? event.data.category : 'unknown_error', Boolean(event.data?.retryable), typeof event.data?.traceId === 'string' ? event.data.traceId : traceId, event.data?.snapshot);
         }
     }
-    while (true) {
-        if (signal?.aborted) {
-            await reader.cancel().catch(() => { });
-            throw new TurnCancelledError();
-        }
-        const read = await reader.read();
-        if (read.done)
-            break;
-        buffer += decoder.decode(read.value, { stream: true });
-        let separatorIndex = buffer.indexOf('\n\n');
-        while (separatorIndex !== -1) {
-            const block = buffer.slice(0, separatorIndex);
-            buffer = buffer.slice(separatorIndex + 2);
-            const event = parseSseBlock(block);
-            if (event)
-                await handleEvent(event);
-            separatorIndex = buffer.indexOf('\n\n');
+    try {
+        while (true) {
+            if (signal?.aborted) {
+                await reader.cancel().catch(() => { });
+                throw new TurnCancelledError();
+            }
+            const read = await Promise.race([reader.read(), parallelToolFailure]);
+            if (read.done)
+                break;
+            buffer += decoder.decode(read.value, { stream: true });
+            let separatorIndex = buffer.indexOf('\n\n');
+            while (separatorIndex !== -1) {
+                const block = buffer.slice(0, separatorIndex);
+                buffer = buffer.slice(separatorIndex + 2);
+                const event = parseSseBlock(block);
+                if (event)
+                    await handleEvent(event);
+                separatorIndex = buffer.indexOf('\n\n');
+            }
         }
+        await drainParallelTools();
+    }
+    catch (error) {
+        await reader.cancel().catch(() => { });
+        throw error;
+    }
+    finally {
+        await drainParallelTools().catch(() => { });
     }
     buffer += decoder.decode();
     const tail = buffer.trim();
@@ -339,6 +444,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,
@@ -393,8 +499,19 @@ export async function sendServerUserMessage({ config, projectIndex, session, inp
                 ? error
                 : new TurnCancelledError();
         }
-        session.history.length = preTurnHistoryLength;
-        preserveFailedTurnInput(session, requestInputBase, error instanceof ChatTurnFailedError ? error.category : 'unknown_error');
+        const category = error instanceof ChatTurnFailedError ? error.category : 'unknown_error';
+        const partial = error instanceof ChatTurnFailedError ? error.partialSnapshot : undefined;
+        if (partial) {
+            applySessionSnapshot(session, partial, { preserveAgentMode: true });
+        }
+        else {
+            session.history.length = preTurnHistoryLength;
+            preserveFailedTurnInput(session, requestInputBase, category);
+        }
+        try {
+            saveSessionState(session, session.env);
+        }
+        catch { }
         throw error;
     }
     finally {

package/dist/src/api/http.js

@@ -6,11 +6,13 @@ export const CLIENT_PLATFORM_HEADER = 'x-thegitai-client-platform';
 export class ServerApiError extends Error {
     status;
     traceId;
-    constructor(message, status, traceId) {
+    code;
+    constructor(message, status, traceId, code = '') {
         super(traceId ? `${message}\nTrace ID: ${traceId}` : message);
         this.name = 'ServerApiError';
         this.status = status;
         this.traceId = traceId;
+        this.code = code;
     }
 }
 export function createTraceId() {
@@ -96,9 +98,20 @@ export async function readJsonResponse(response) {
 export function failureMessage(data, status) {
     return String(data?.error?.message ?? data?.message ?? `Request failed with ${status}`);
 }
+export function failureCode(data) {
+    return typeof data?.error?.code === 'string' ? data.error.code : '';
+}
+export function isAuthenticationError(error) {
+    return error instanceof ServerApiError && error.status === 401;
+}
+export function authenticationErrorMessage(error) {
+    return error.code === 'AUTH_TOKEN_EXPIRED'
+        ? 'Your login expired after 24 hours of inactivity. Run `ai login` and resume this saved session.'
+        : 'Your login is no longer valid. Run `ai login` and resume this saved session.';
+}
 export async function readErrorResponse(response, traceId = response.headers.get(TRACE_ID_HEADER) ?? '') {
     const data = await readJsonResponse(response);
-    return new ServerApiError(failureMessage(data, response.status), response.status, traceId);
+    return new ServerApiError(failureMessage(data, response.status), response.status, traceId, failureCode(data));
 }
 export async function authorizedJson({ config, path, method = 'GET', body = null, headers = {}, fetchImpl = globalThis.fetch, timeoutMs = REQUEST_TIMEOUT_MS, }) {
     const trace = createTraceContext();
@@ -115,7 +128,7 @@ export async function authorizedJson({ config, path, method = 'GET', body = null
     });
     const data = await readJsonResponse(response);
     if (!response.ok) {
-        throw new ServerApiError(failureMessage(data, response.status), response.status, trace.traceId);
+        throw new ServerApiError(failureMessage(data, response.status), response.status, trace.traceId, failureCode(data));
     }
     return data;
 }

package/dist/src/api/models.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import { getClientStateDir } from '../client-state.js';
-import { REQUEST_TIMEOUT_MS, ServerApiError, createTraceContext, failureMessage, normalizeServerUrl, readJsonResponse, retryTransient, } from './http.js';
+import { REQUEST_TIMEOUT_MS, ServerApiError, createTraceContext, failureCode, failureMessage, normalizeServerUrl, readJsonResponse, retryTransient, } from './http.js';
 function sanitizeModelInfo(raw) {
     if (!raw || typeof raw !== 'object') {
         return null;
@@ -9,10 +9,15 @@ function sanitizeModelInfo(raw) {
     const value = raw;
     const id = Number(value.id);
     const label = String(value.label ?? '').trim();
-    if (!Number.isInteger(id) || id <= 0 || !label) {
+    const costRating = Number(value.costRating);
+    const description = String(value.description ?? '').trim();
+    if (!Number.isInteger(id) || id <= 0 || !label || !isCostRating(costRating)) {
         return null;
     }
-    return { id, label };
+    return { id, label, costRating, description };
+}
+function isCostRating(value) {
+    return Number.isInteger(value) && value >= 1 && value <= 3;
 }
 export function getModelsCachePath(env = process.env) {
     return path.join(getClientStateDir(env), 'models.json');
@@ -70,7 +75,7 @@ export async function fetchServerModels({ config, fetchImpl = globalThis.fetch,
         });
         const data = (await readJsonResponse(response));
         if (!response.ok) {
-            throw new ServerApiError(failureMessage(data, response.status), response.status, trace.traceId);
+            throw new ServerApiError(failureMessage(data, response.status), response.status, trace.traceId, failureCode(data));
         }
         const models = Array.isArray(data?.models)
             ? data.models.map(sanitizeModelInfo).filter(Boolean)

package/dist/src/help-text.js

@@ -22,6 +22,7 @@ const HELP_MARKDOWN = [
     '',
     '- `ai` — start an interactive chat session in the current repo',
     '- `ai "<request>"` — start an interactive session with `<request>` as the first message',
+    '- Coding sessions require terminal stdin and stdout; piped prompts are not supported.',
     '',
     '## Auth',
     '',
@@ -35,8 +36,8 @@ const HELP_MARKDOWN = [
     '',
     '- `ai --list-sessions` — list saved sessions for this repo',
     '- `ai --session <id|name>` — resume a saved session by id or name',
-    '- Sessions are stored locally and scoped to the current repo. The five',
-    '  most recent sessions per repo are kept.',
+    '- Sessions are stored locally and can be listed or resumed in the same repo.',
+    '  Continuing one requires the TheGitAI account used for that session.',
     '',
     '## Options',
     '',
@@ -56,7 +57,8 @@ const HELP_MARKDOWN = [
     '## Keys & clipboard',
     '',
     '- **Enter** sends • **Shift+Tab** cycles modes • **Esc** cancels the turn •',
-    '  **Ctrl+C** quits. These are the same on macOS, Linux, and Windows.',
+    '  **Ctrl+C** clears the composer or the queued message, and quits once there',
+    '  is nothing left to clear. These are the same on macOS, Linux, and Windows.',
     `- **Paste** into the composer with your terminal's paste shortcut (\`${PASTE_SHORTCUT}\``,
     '  on this system) or by right-clicking the composer.',
     '- **Copy** from the transcript by dragging to select; double-click copies a',
@@ -77,7 +79,7 @@ const HELP_MARKDOWN = [
     '  browse them, press Enter to expand one and read its output, k to stop it',
     '- `/jobs output <id>` — print one job\'s full captured output',
     '- `/jobs kill <id>` — stop one background job',
-    '- `/clear` — clear the current conversation history',
+    '- `/new` — start a new conversation; this session remains saved',
     '- `/exit` — quit the session',
     '',
     '## Safety & approvals',
@@ -105,7 +107,10 @@ const HELP_MARKDOWN = [
     '- Auth or permission errors → run `ai whoami` to confirm the signed-in',
     '  account.',
     '- Usage or quota errors → run `ai --usage`.',
-    '- Stuck on the wrong account → `ai logout`, then `ai login` again.',
+    '- Signed in with the wrong credentials → `ai logout`, then `ai login` with',
+    '  the account you intended to use.',
+    '- A local session was used with a different sign-in → sign in with the',
+    '  account you used for that session or start a new session.',
     '- For anything else, re-run the command and report the printed error',
     '  message — there is no client-side debug mode by design.',
 ].join('\n');
@@ -126,8 +131,15 @@ export function formatInteractiveHelpText() {
     return HELP_MARKDOWN;
 }
 export function formatCliHelpText({ color = false } = {}) {
-    if (!color)
-        return HELP_MARKDOWN;
+    if (!color) {
+        return HELP_MARKDOWN.split('\n')
+            .map((line) => line
+            .replace(/^#{1,6}\s+/, '')
+            .replace(/^-\s+/, '  ')
+            .replace(/`([^`]+)`/g, '$1')
+            .replace(/\*\*([^*]+)\*\*/g, '$1'))
+            .join('\n');
+    }
     return HELP_MARKDOWN.split('\n')
         .map((line) => {
         const heading = line.match(/^(#{1,6})\s+(.*)$/);

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-index.js

@@ -39,10 +39,21 @@ function removeFile(index, relPath) {
     index.chunksByFile.delete(relPath);
     index.fileSignatures.delete(relPath);
 }
+function countIndexedChunks(index) {
+    return Array.from(index.chunksByFile.values()).reduce((sum, chunks) => sum + chunks.length, 0);
+}
 async function initializeIndex(index) {
     if (index.initialized) {
-        return Array.from(index.chunksByFile.values()).reduce((sum, chunks) => sum + chunks.length, 0);
+        return countIndexedChunks(index);
+    }
+    if (!index._initializing) {
+        index._initializing = scanProjectIntoIndex(index).finally(() => {
+            index._initializing = null;
+        });
     }
+    return index._initializing;
+}
+async function scanProjectIntoIndex(index) {
     const files = listProjectFiles(index.rootDir);
     const chunks = await scanFiles(index.rootDir, files);
     index.fileSignatures.clear();
@@ -106,6 +117,7 @@ export function createIndex({ rootDir, onStatus = null, onContextLog = null, })
     return {
         rootDir: path.resolve(rootDir),
         initialized: false,
+        _initializing: null,
         fileSignatures: new Map(),
         chunksByFile: new Map(),
         onStatus,