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

package/dist/src/api/chat.js

@@ -1,11 +1,13 @@
 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 { isUserInputQuestionArray } from './contracts.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.') {
@@ -17,11 +19,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) {
@@ -51,6 +55,7 @@ function parseSseBlock(block) {
         return { event, data: text };
     }
 }
+let toolStateSeqCounter = 0;
 function toolStateFromSession(session) {
     return {
         autoYes: session.autoYes,
@@ -93,17 +98,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,11 +161,16 @@ function publicStatusMessage(data) {
         ? event.toolName
         : 'tool';
     if (event.phase === 'thinking')
-        return 'Thinking...';
+        return 'Exploring options...';
+    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')
         return `Running ${toolName} locally...`;
+    if (event.phase === 'waiting_for_user_input')
+        return 'Waiting for your input...';
     return null;
 }
 function normalizeShellJobToolCall(call) {
@@ -184,6 +207,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`, {
@@ -202,6 +226,71 @@ async function postToolResult({ config, turnId, event, result, session, fetchImp
         throw await readErrorResponse(response, trace.traceId);
     }
 }
+async function postUserInputResult({ config, turnId, requestId, result, fetchImpl, traceId, }) {
+    const payload = {
+        requestId,
+        result,
+    };
+    const trace = createTraceContext(traceId);
+    const response = await fetchImpl(`${normalizeServerUrl(config.serverUrl)}/v1/chat/turn/${encodeURIComponent(turnId)}/user-input-result`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${config.token}`,
+            'content-type': 'application/json',
+            ...trace.headers,
+        },
+        body: JSON.stringify(payload),
+    });
+    if (response.status === 410) {
+        return;
+    }
+    if (!response.ok) {
+        throw await readErrorResponse(response, trace.traceId);
+    }
+}
+export async function postInterjection({ config, turnId, text, messageId, fetchImpl = globalThis.fetch, traceId, }) {
+    const payload = { text, messageId };
+    const trace = createTraceContext(traceId);
+    const response = await fetchImpl(`${normalizeServerUrl(config.serverUrl)}/v1/chat/turn/${encodeURIComponent(turnId)}/interject`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${config.token}`,
+            'content-type': 'application/json',
+            ...trace.headers,
+        },
+        body: JSON.stringify(payload),
+    });
+    if (response.status === 410) {
+        return 'stale';
+    }
+    if (!response.ok) {
+        throw await readErrorResponse(response, trace.traceId);
+    }
+    return 'delivered';
+}
+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) {
@@ -210,10 +299,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);
         }
@@ -236,10 +324,12 @@ 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, }) {
+async function consumeTurnStream({ response, config, projectIndex, session, input, fetchImpl, signal, traceId, onTurnStart, onInterjectionDelivered, }) {
     if (!response.body) {
         throw new Error('Server returned an empty chat stream.');
     }
@@ -249,8 +339,50 @@ 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 === 'turn-start') {
+            const turnId = String(event.data?.turnId ?? '').trim();
+            if (turnId)
+                onTurnStart?.(turnId);
+            return;
+        }
+        if (event.event === 'interjection-delivered') {
+            onInterjectionDelivered?.(event.data);
+            return;
+        }
         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);
@@ -260,11 +392,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,36 +426,75 @@ async function consumeTurnStream({ response, config, projectIndex, session, inpu
             }
             return;
         }
+        if (event.event === 'user-input-request') {
+            await drainParallelTools();
+            const data = event.data;
+            const turnId = String(data?.turnId ?? '').trim();
+            const requestId = String(data?.requestId ?? '').trim();
+            if (!turnId ||
+                !requestId ||
+                !isUserInputQuestionArray(data?.questions)) {
+                throw new Error('Server emitted an invalid user-input request.');
+            }
+            if (!session.requestUserInput) {
+                throw new Error('Interactive user input is unavailable in this client.');
+            }
+            const result = await session.requestUserInput({ questions: data.questions }, signal);
+            if (signal?.aborted) {
+                throw new TurnCancelledError();
+            }
+            await postUserInputResult({
+                config,
+                turnId,
+                requestId,
+                result,
+                fetchImpl,
+                traceId,
+            });
+            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();
@@ -322,7 +508,7 @@ async function consumeTurnStream({ response, config, projectIndex, session, inpu
     }
     return finalResult.current;
 }
-export async function sendServerUserMessage({ config, projectIndex, session, input, imageAttachments = [], fetchImpl = globalThis.fetch, signal, }) {
+export async function sendServerUserMessage({ config, projectIndex, session, input, imageAttachments = [], fetchImpl = globalThis.fetch, signal, onTurnStart, onInterjectionDelivered, }) {
     const autoAttach = autoAttachImages(input, session.rootDir, imageAttachments);
     const requestImageAttachments = autoAttach.attachments.length > 0
         ? [...imageAttachments, ...autoAttach.attachments]
@@ -379,6 +565,8 @@ export async function sendServerUserMessage({ config, projectIndex, session, inp
             fetchImpl,
             signal,
             traceId: trace.traceId,
+            onTurnStart,
+            onInterjectionDelivered,
         });
         applySessionSnapshot(session, result.snapshot, { preserveAgentMode: true });
         return {
@@ -395,8 +583,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/contracts.js

@@ -1 +1,55 @@
-export {};
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+const USER_INPUT_ID_PATTERN = /^[a-z][a-z0-9_]*$/;
+export function isUserInputQuestionArray(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 4) {
+        return false;
+    }
+    const questionIds = new Set();
+    return value.every((question) => {
+        if (!question || typeof question !== 'object' || Array.isArray(question)) {
+            return false;
+        }
+        const candidate = question;
+        if (!nonEmptyString(candidate.id) ||
+            !USER_INPUT_ID_PATTERN.test(candidate.id) ||
+            questionIds.has(candidate.id) ||
+            !nonEmptyString(candidate.header) ||
+            Array.from(candidate.header).length > 12 ||
+            !nonEmptyString(candidate.question) ||
+            typeof candidate.multiSelect !== 'boolean' ||
+            !Array.isArray(candidate.options) ||
+            candidate.options.length < 2 ||
+            candidate.options.length > 4) {
+            return false;
+        }
+        questionIds.add(candidate.id);
+        const optionIds = new Set();
+        const optionsValid = candidate.options.every((option) => {
+            if (!option || typeof option !== 'object' || Array.isArray(option)) {
+                return false;
+            }
+            const item = option;
+            if (!nonEmptyString(item.id) ||
+                !USER_INPUT_ID_PATTERN.test(item.id) ||
+                optionIds.has(item.id) ||
+                !nonEmptyString(item.label) ||
+                !nonEmptyString(item.description)) {
+                return false;
+            }
+            optionIds.add(item.id);
+            return true;
+        });
+        if (!optionsValid) {
+            return false;
+        }
+        if (candidate.recommendedOptionId !== undefined &&
+            (!nonEmptyString(candidate.recommendedOptionId) ||
+                candidate.recommendedOptionId !==
+                    candidate.options[0].id)) {
+            return false;
+        }
+        return true;
+    });
+}

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/executor.js

@@ -596,7 +596,7 @@ export function commandUsesSudo(command) {
 }
 export function sudoPromptFromTail(text) {
     const tail = text.slice(-1000).replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
-    const match = tail.match(/(?:\[sudo\][^\r\n]*password[^\r\n]*: ?|sudo[^\r\n]*password[^\r\n]*: ?|password[^\r\n]*: ?)$/i);
+    const match = tail.match(/(?:\[sudo\][^\r\n]*password[^\r\n]*: ?|\[?sudo[^\r\n]*password[^\r\n]*: ?|password[^\r\n]*: ?)$/i);
     return match?.[0] ?? null;
 }
 function isSudoPromptLine(text) {

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',
     '',
@@ -46,7 +47,9 @@ const HELP_MARKDOWN = [
     '',
     '## Modes',
     '',
-    '- Default — asks before shell commands and file edits.',
+    '- Default — asks before creating, editing or deleting files and before',
+    '  running commands. Each answer can be remembered for the rest of the',
+    '  session; see Safety & approvals.',
     '- Auto-Accept — approves shell commands and file edits for the session.',
     '- Plan — read-only; the agent can inspect, ask typed questions, and plan,',
     '  with file-reading shell commands only. It will not edit files or run tests,',
@@ -56,7 +59,15 @@ 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.',
+    '- **While the agent is working**, Enter queues your message and locks the',
+    '  composer. Press **Enter** again to send it into the running turn: the agent',
+    '  picks it up at its next step instead of waiting for the turn to finish, and',
+    '  the Your messages panel tracks it from queued to delivered. **↑** brings it',
+    '  back for editing and **Esc**/**Ctrl+C** discards it; both unlock the',
+    '  composer for the next message. Messages with images cannot be sent mid-turn',
+    '  and are sent with the next prompt instead.',
     `- **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,14 +88,33 @@ 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',
     '',
-    '- TheGitAI asks before running shell commands or applying file edits.',
-    '- At each prompt: **y** approves once, **a** approves the rest of the',
-    '  session, **n** denies.',
+    '- In Default mode TheGitAI asks before it creates a file, edits an existing',
+    '  file, deletes a file, or runs a command. These are four separate',
+    '  permissions: allowing edits does not allow deletions, and allowing file',
+    '  changes does not allow commands.',
+    '- At each prompt: **↑/↓** moves between choices, **Enter** confirms the',
+    '  highlighted one, and **Esc** denies. Deny is selected by default.',
+    '  Single-letter shortcuts were removed on purpose: a prompt can appear',
+    '  while you are typing, and a stray letter must never approve anything.',
+    '- Every prompt offers Approve once, an "Always allow" for that kind of',
+    '  action, and Deny. A command also offers to remember just its prefix — for',
+    '  example approving `npm test -- --watch=false` can allow `npm test`.',
+    '- A prefix is only offered when the command shows a plain verb, as in',
+    '  `npm test` or `git status`. Commands with no verb (`ls -la`), interpreters',
+    '  and wrappers (`bash -c`, `python -c`, `env`, `timeout`, `make`), and',
+    '  destructive or network binaries (`rm`, `sudo`, `curl`) are never offered',
+    '  one — a bare binary grant would mean "anything this program can do".',
+    '  `npm run` must name its script, so the grant is `npm run build`.',
+    '- A remembered prefix never covers a command that chains, pipes, redirects,',
+    '  or substitutes, so allowing `npm test` can never green-light',
+    '  `npm test && rm -rf build`.',
+    '- Everything you allow lasts for the current session only and is forgotten',
+    '  when it ends. `/new` clears it immediately.',
     '- If an approved `sudo` command needs a password, the TUI shows the exact',
     '  command and keeps the password masked and local.',
     '- `-y` / `--yes` at startup auto-approves every shell command and file',
@@ -105,7 +135,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 +159,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+(.*)$/);