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

package/dist/src/executor.js

@@ -1,11 +1,25 @@
-import chalk from 'chalk';
-import * as pty from '@homebridge/node-pty-prebuilt-multiarch';
+import chalk from './colors.js';
 import { execFileSync, spawn } from 'child_process';
 import { existsSync, statSync } from 'fs';
+import { createRequire } from 'node:module';
 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() {
+    if (nodePtyCache !== undefined)
+        return nodePtyCache;
+    try {
+        nodePtyCache = requireFromHere('@lydell/node-pty');
+    }
+    catch {
+        nodePtyCache = null;
+    }
+    return nodePtyCache;
+}
 const COMMON_TOOLCHAIN_BIN_DIRS = ['/usr/local/go/bin'];
 function detectVenvBin(dir) {
     for (const name of ['.venv', 'venv', 'env']) {
@@ -204,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))
@@ -211,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 ||
@@ -221,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;
 }
@@ -237,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)) {
@@ -373,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) {
@@ -434,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');
@@ -509,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') {
@@ -537,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.`;
     }
@@ -559,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) {
@@ -587,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 {
@@ -602,12 +634,13 @@ 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) {
     return sanitizeCommandText(command, stripSudoPromptText(redactSecrets(output, secrets)), cwd);
 }
-async function runPtyCommand(command, cwd, effectiveTimeout, exploratory, requestSudoPassword) {
+async function runPtyCommand(command, cwd, effectiveTimeout, exploratory, requestSudoPassword, nodePty) {
     return new Promise((resolve) => {
         let output = '';
         let timedOut = false;
@@ -623,7 +656,7 @@ async function runPtyCommand(command, cwd, effectiveTimeout, exploratory, reques
         const args = process.platform === 'win32'
             ? ['/d', '/s', '/c', command]
             : ['-lc', command];
-        const child = pty.spawn(shell, args, {
+        const child = nodePty.spawn(shell, args, {
             cols: 120,
             rows: 30,
             cwd,
@@ -776,7 +809,10 @@ export async function runCommand(command, cwd, { requestSudoPassword, timeout, }
     }
     const exploratory = isExploratoryCommand(command);
     if (requestSudoPassword && commandUsesSudo(command)) {
-        return runPtyCommand(command, cwd, effectiveTimeout, exploratory, requestSudoPassword);
+        const nodePty = loadNodePty();
+        if (nodePty) {
+            return runPtyCommand(command, cwd, effectiveTimeout, exploratory, requestSudoPassword, nodePty);
+        }
     }
     return new Promise((resolve) => {
         let stdout = '';

package/dist/src/help-text.js

@@ -1,9 +1,5 @@
-import chalk from 'chalk';
+import chalk from './colors.js';
 import { getCliVersion, getPlatformTag } from './version.js';
-// The bound keys (Enter/Esc/Ctrl+C/Tab/arrows) are identical across platforms in
-// a terminal. The one thing that genuinely differs is the terminal's paste
-// shortcut, so surface the one for the host OS (right-click paste works
-// everywhere regardless).
 function pasteShortcutForPlatform() {
     switch (process.platform) {
         case 'darwin':
@@ -77,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` — manage long-running commands like dev servers and watchers:',
+    '  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',
     '- `/exit` — quit the session',
     '',
@@ -89,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.',
@@ -104,7 +110,6 @@ const HELP_MARKDOWN = [
     '  message — there is no client-side debug mode by design.',
 ].join('\n');
 export function formatAboutCard() {
-    // Fenced so the column alignment survives terminal markdown rendering.
     return [
         '```',
         'TheGitAI',

package/dist/src/markdown-renderer.js

@@ -1,4 +1,4 @@
-import chalk from 'chalk';
+import chalk from './colors.js';
 function renderInline(text) {
     const parts = String(text ?? '').split(/(`[^`]+`)/g);
     return parts

package/dist/src/patcher.js

@@ -1,4 +1,4 @@
-import chalk from 'chalk';
+import chalk from './colors.js';
 import { existsSync, lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from 'fs';
 import path from 'path';
 import { createInterface } from 'readline';
@@ -162,7 +162,6 @@ export function writeProjectFile(rootDir, filePath, content) {
             }
         }
         catch {
-            // If we can't read it for some reason, proceed with write
         }
     }
     mkdirSync(path.dirname(absPath), { recursive: true });
@@ -179,7 +178,6 @@ export function writeProjectFileBuffer(rootDir, filePath, content) {
             }
         }
         catch {
-            // If we can't read it for some reason, proceed with write
         }
     }
     mkdirSync(path.dirname(absPath), { recursive: true });

package/dist/src/scanner.js

@@ -1,14 +1,12 @@
 import { execSync } from 'child_process';
-import { readFileSync, statSync } from 'fs';
-import { glob } from 'glob';
+import { readdirSync, readFileSync, statSync } from 'fs';
 import path from 'path';
 import { getNodePrimarySignature, getStructuralChildren, parseRepoSource, } from './tree-sitter-runtime.js';
-import { ARTIFACT_FALLBACK_IGNORE_GLOBS, ARTIFACT_IGNORE_DIRS, ARTIFACT_IGNORE_FILES, ARTIFACT_INSPECT_BLOCK_DIRS, BINARY_ARTIFACT_EXTENSIONS, isSensitiveProjectPath, shouldIgnoreArtifactPath, } from './artifact-policy.js';
+import { ARTIFACT_IGNORE_DIRS, ARTIFACT_IGNORE_FILES, ARTIFACT_INSPECT_BLOCK_DIRS, BINARY_ARTIFACT_EXTENSIONS, isSensitiveProjectPath, shouldIgnoreArtifactPath, } from './artifact-policy.js';
 const BINARY_EXTENSIONS = BINARY_ARTIFACT_EXTENSIONS;
 const ALWAYS_IGNORE_FILES = ARTIFACT_IGNORE_FILES;
 export const ALWAYS_IGNORE_DIRS = ARTIFACT_IGNORE_DIRS;
 export const BLOCKED_PATH_INSPECT_DIRS = ARTIFACT_INSPECT_BLOCK_DIRS;
-const FALLBACK_IGNORE = ARTIFACT_FALLBACK_IGNORE_GLOBS;
 export const SCANNER_MAX_SOURCE_FILE_BYTES = 100 * 1024;
 const MAX_FILE_SIZE = SCANNER_MAX_SOURCE_FILE_BYTES;
 const MAX_CHUNKS = 2000;
@@ -29,16 +27,56 @@ function getFiles(rootDir, { limit = Infinity } = {}) {
         return Number.isFinite(limit) ? files.slice(0, limit) : files;
     }
     catch {
-        return glob
-            .sync('**/*', {
-            cwd: rootDir,
-            nodir: true,
-            dot: false,
-            ignore: FALLBACK_IGNORE,
-        })
-            .slice(0, Number.isFinite(limit) ? limit : undefined);
+        return walkProjectFilesFallback(rootDir, Number.isFinite(limit) ? limit : Infinity);
     }
 }
+const FALLBACK_LOCKFILES = new Set([
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+]);
+function isFallbackIgnoredFile(relPath, fileName) {
+    if (shouldIgnorePath(relPath))
+        return true;
+    if (fileName.endsWith('.lock'))
+        return true;
+    return FALLBACK_LOCKFILES.has(fileName);
+}
+function walkProjectFilesFallback(rootDir, limit) {
+    const results = [];
+    const visit = (relDir) => {
+        if (results.length >= limit)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(path.join(rootDir, relDir), {
+                withFileTypes: true,
+            });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (results.length >= limit)
+                return;
+            const name = entry.name;
+            if (name.startsWith('.'))
+                continue;
+            const relPath = relDir ? `${relDir}/${name}` : name;
+            if (entry.isDirectory()) {
+                if (ALWAYS_IGNORE_DIRS.has(name) || shouldIgnoreArtifactPath(relPath)) {
+                    continue;
+                }
+                visit(relPath);
+            }
+            else if (entry.isFile() && !isFallbackIgnoredFile(relPath, name)) {
+                results.push(relPath);
+            }
+        }
+    };
+    visit('');
+    return results;
+}
 function shouldSkipFile(relPath, stat) {
     if (shouldIgnorePath(relPath))
         return true;

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/secret-preview.js

@@ -6,11 +6,7 @@ const PRIVATE_KEY_REDACTION = '[REDACTED: private key]';
 const SENSITIVE_JSON_KEY_PATTERN = /^(?:private[_-]?key|secret|api[_-]?key|password|client_secret|refresh_token|access_token|id_token|auth_provider_x509_cert_url)$/i;
 const PEM_BLOCK_PATTERN = /-----BEGIN [^-]*(?:PRIVATE KEY|SECRET KEY|OPENSSH PRIVATE KEY)[\s\S]*?-----END [^-]*(?:PRIVATE KEY|SECRET KEY|OPENSSH PRIVATE KEY)-----/gi;
 const PEM_SECRET_PATH_PATTERN = /\.(?:pem|key)$/i;
-// Password embedded in a connection-string URL, e.g.
-// `postgresql://user:PASS@host`. Redacted from shell output so secrets in
-// commands like `cat .env` do not leak into history or telemetry.
 const URL_CREDENTIALS_PATTERN = /\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)([^\s/@]+)(@)/gi;
-/** Redact only userinfo passwords in connection-string URLs (zero false positives). */
 export function redactConnectionStringCredentials(text) {
     return text.replace(URL_CREDENTIALS_PATTERN, (_match, prefix, _password, at) => `${prefix}${VALUE_REDACTION}${at}`);
 }
@@ -72,12 +68,6 @@ export function isDotenvLikePath(value) {
     const base = path.posix.basename(text.replace(/\\/g, '/'));
     return DOTENV_BASENAME_PATTERN.test(base);
 }
-/**
- * True only for a clean dotenv file we can safely show with keys visible and
- * values tokenized: no PEM block, not JSON, and every non-blank/non-comment line
- * is a `KEY=VALUE` assignment. Anything ambiguous (a stray line that might be a
- * raw secret) returns false so the caller keeps the opaque blackout instead.
- */
 export function looksLikeEditableDotenv(content) {
     PEM_BLOCK_PATTERN.lastIndex = 0;
     if (PEM_BLOCK_PATTERN.test(content))

package/dist/src/session-safety.js

@@ -454,17 +454,6 @@ export function resolveRedactionTokens(state, text, filePath, hash) {
 }
 const DOTENV_ASSIGNMENT_PATTERN = /^(\s*(?:export\s+)?[A-Za-z_][A-Za-z0-9_]*\s*=)(.*)$/;
 const DOTENV_COMMENT_PATTERN = /^(\s*#\s*)(\S.*)$/;
-/**
- * Redact a dotenv file's values while leaving keys visible. Every assignment's
- * value is replaced with a stable, reversible token so the agent can see the
- * file's structure and edit it (remove or replace lines) without ever seeing a
- * secret value; `resolveRedactionTokens` swaps the real values back on write.
- * Comment bodies are tokenized too, because developers routinely leave
- * commented-out credentials in dotenv files and those must not leak where the
- * opaque preview would have hidden them. Callers must confirm the content is
- * clean dotenv (`looksLikeEditableDotenv`) first so the only non-assignment
- * lines reaching here are blanks and comments.
- */
 export function redactDotenvWithStableTokens(state, content, filePath, hash) {
     const tokens = [];
     const redactedLines = content.split('\n').map((line) => {
@@ -490,14 +479,6 @@ export function redactDotenvWithStableTokens(state, content, filePath, hash) {
     });
     return { content: redactedLines.join('\n'), tokens };
 }
-/**
- * The redaction-token registry is capped at `MAX_REDACTION_TOKENS`; a read that
- * emits more tokens than that would evict its own oldest tokens, leaving
- * `[REDACTED:n]` markers in the preview that `write_file`/`str_replace` can no
- * longer resolve (silently writing the literal token back). So a dotenv file
- * with more tokenizable lines than the budget must not use the editable preview
- * — the caller falls back to the opaque blackout instead.
- */
 export function dotenvFitsRedactionBudget(content) {
     let count = 0;
     for (const line of content.split('\n')) {

package/dist/src/session-store.js

@@ -122,7 +122,6 @@ function loadAllSnapshots(rootDir, env = process.env) {
             snapshots.push(loadSnapshotFile(filePath, rootDir));
         }
         catch {
-            // Skip corrupted snapshots silently — customers have no actionable debug path here.
         }
     }
     return snapshots.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));

package/dist/src/todo-list.js

@@ -0,0 +1,106 @@
+export const MAX_TODO_ITEMS = 20;
+export const MAX_TODO_TEXT_CHARS = 160;
+let items = [];
+let activeSessionId = null;
+const STATUS_ALIASES = {
+    pending: 'pending',
+    todo: 'pending',
+    not_started: 'pending',
+    in_progress: 'in_progress',
+    active: 'in_progress',
+    doing: 'in_progress',
+    completed: 'completed',
+    complete: 'completed',
+    done: 'completed',
+};
+function normalizeStatus(raw) {
+    const key = String(raw ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/[-\s]+/g, '_');
+    return STATUS_ALIASES[key] ?? null;
+}
+export function isCompletedStatus(raw) {
+    return normalizeStatus(raw) === 'completed';
+}
+const TODOS_ARG_ALIASES = ['items', 'todo_list', 'todoList', 'list', 'tasks'];
+export function extractTodosArg(args) {
+    if (!args || typeof args !== 'object')
+        return undefined;
+    const record = args;
+    if (record.todos !== undefined)
+        return record.todos;
+    for (const key of TODOS_ARG_ALIASES) {
+        if (record[key] !== undefined)
+            return record[key];
+    }
+    return undefined;
+}
+export function setTodoSession(sessionId) {
+    const next = String(sessionId ?? '').trim() || null;
+    if (activeSessionId !== next) {
+        items = [];
+    }
+    activeSessionId = next;
+}
+export function listTodos() {
+    return items.map((item) => ({ ...item }));
+}
+export function getTodoSnapshot() {
+    return {
+        items: listTodos(),
+        completedCount: items.filter((item) => item.status === 'completed').length,
+        totalCount: items.length,
+    };
+}
+export function clearTodos() {
+    items = [];
+}
+export function replaceTodos(raw) {
+    if (!Array.isArray(raw)) {
+        return { ok: false, error: 'todos must be an array of { text, status } items.' };
+    }
+    const normalizations = [];
+    if (raw.length > MAX_TODO_ITEMS) {
+        return {
+            ok: false,
+            error: `todos supports at most ${MAX_TODO_ITEMS} items; got ${raw.length}. Use fewer, broader steps.`,
+        };
+    }
+    const next = [];
+    let sawInProgress = false;
+    for (const [index, entry] of raw.entries()) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            return { ok: false, error: `todos[${index}] must be an object with text and status.` };
+        }
+        const text = String(entry.text ?? '')
+            .replace(/\s+/g, ' ')
+            .trim();
+        if (!text) {
+            return { ok: false, error: `todos[${index}].text must be a non-empty string.` };
+        }
+        const status = normalizeStatus(entry.status);
+        if (!status) {
+            return {
+                ok: false,
+                error: `todos[${index}].status must be one of: pending, in_progress, completed.`,
+            };
+        }
+        let boundedText = text;
+        if (boundedText.length > MAX_TODO_TEXT_CHARS) {
+            boundedText = `${boundedText.slice(0, MAX_TODO_TEXT_CHARS - 1)}…`;
+            normalizations.push(`todos[${index}].text truncated to ${MAX_TODO_TEXT_CHARS} chars`);
+        }
+        let finalStatus = status;
+        if (status === 'in_progress') {
+            if (sawInProgress) {
+                finalStatus = 'pending';
+                normalizations.push(`todos[${index}] demoted to pending: only one item can be in_progress`);
+            }
+            sawInProgress = true;
+        }
+        next.push({ text: boundedText, status: finalStatus });
+    }
+    items = next;
+    return { ok: true, snapshot: getTodoSnapshot(), normalizations };
+}