@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/shell.js

@@ -0,0 +1,504 @@
+import { execFile, spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+import { promisify } from 'node:util';
+import { readFile, readdir, stat, realpath } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { resolveCodexExecutable } from './codex-executable.js';
+import { recordCommandTiming } from './command-metrics.js';
+const OUTPUT_LIMIT = 32_768;
+const executeFile = promisify(execFile);
+const delay = (milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds));
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function signal(pid, kind) {
+    try {
+        process.kill(pid, kind);
+    }
+    catch { /* The process already exited. */ }
+}
+async function linuxProcess(pid, marker) {
+    try {
+        const status = await readFile(`/proc/${pid}/stat`, 'utf8');
+        const fields = status.slice(status.lastIndexOf(')') + 1).trim().split(/\s+/);
+        const marked = marker ? (await readFile(`/proc/${pid}/environ`).catch(() => Buffer.alloc(0))).includes(Buffer.from(`${marker}\0`)) : false;
+        return { pid, parent: Number(fields[1]), group: Number(fields[2]), started: fields[19], marked };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function signalProcess(row, kind) {
+    // A PID may have been recycled between enumeration and escalation.
+    if (process.platform === 'linux' && (await linuxProcess(row.pid))?.started !== row.started)
+        return;
+    signal(row.pid, kind);
+}
+async function processRows(marker) {
+    if (process.platform === 'linux') {
+        // Minimal Linux images often have no ps binary; procfs exposes the same ancestry.
+        const entries = (await readdir('/proc')).filter(name => /^[0-9]+$/.test(name));
+        if (entries.length > 32_768)
+            throw new Error('Process table exceeds cleanup scan limit');
+        const rows = [];
+        for (let index = 0; index < entries.length; index += 128) {
+            const batch = await Promise.all(entries.slice(index, index + 128).map(entry => linuxProcess(Number(entry), marker)));
+            rows.push(...batch.filter((row) => !!row && row.pid > 1));
+        }
+        return rows;
+    }
+    const { stdout } = await executeFile('ps', ['-A', '-o', 'pid=', '-o', 'ppid=', '-o', 'pgid='], { timeout: 1_000, maxBuffer: 2_097_152 });
+    return stdout.trim().split('\n').map(line => {
+        const [pid, parent, group] = line.trim().split(/\s+/).map(Number);
+        return { pid, parent, group };
+    }).filter(row => Number.isSafeInteger(row.pid) && row.pid > 1);
+}
+async function stopPosix(child, marker) {
+    const root = child.pid;
+    if (!root)
+        return;
+    const deadline = Date.now() + 4_000;
+    // Keep parents alive while their children exit, so waitpid can reap each child.
+    // Killing the entire group together leaves zombies when container PID 1 does not reap.
+    try {
+        while (Date.now() < deadline) {
+            const rows = await processRows(marker);
+            const owned = new Set([root]);
+            for (const row of rows)
+                if (row.marked || row.group === root)
+                    owned.add(row.pid);
+            let added = true;
+            while (added) {
+                added = false;
+                for (const row of rows)
+                    if (owned.has(row.parent) && !owned.has(row.pid)) {
+                        owned.add(row.pid);
+                        added = true;
+                    }
+            }
+            const descendants = rows.filter(row => row.pid !== root && owned.has(row.pid));
+            if (!descendants.length)
+                break;
+            const parents = new Set(descendants.map(row => row.parent));
+            const leaves = descendants.filter(row => !parents.has(row.pid));
+            await Promise.all(leaves.map(row => signalProcess(row, 'SIGTERM')));
+            await delay(150);
+            await Promise.all(leaves.map(row => signalProcess(row, 'SIGKILL')));
+            // Give the still-running parents time to reap, before moving up the tree.
+            const reapDeadline = Math.min(deadline, Date.now() + 250);
+            while (leaves.some(row => alive(row.pid)) && Date.now() < reapDeadline)
+                await delay(25);
+        }
+    }
+    catch {
+        // If process enumeration is inaccessible, retain bounded best-effort group cleanup.
+        signal(-root, 'SIGTERM');
+        await delay(250);
+    }
+    if (child.exitCode === null && child.signalCode === null && alive(root)) {
+        signal(root, 'SIGTERM');
+        const parentDeadline = Date.now() + 250;
+        while (alive(root) && Date.now() < parentDeadline)
+            await delay(25);
+    }
+    // Escalate stubborn processes/new group members after the graceful reaping window.
+    if (child.exitCode === null && child.signalCode === null) {
+        signal(-root, 'SIGKILL');
+        if (alive(root))
+            signal(root, 'SIGKILL');
+    }
+}
+/** Cleanup runs in the host: never discover its executable through cwd or PATH. */
+export async function resolveTrustedTaskkill(workspace, env = process.env) {
+    const failure = () => new Error('Shell cleanup requires a validated absolute SystemRoot\\System32\\taskkill.exe outside the workspace. No PATH fallback is allowed.');
+    const systemRoot = env.SystemRoot;
+    // Reject relative, network and device namespaces before probing the filesystem.
+    if (!systemRoot || !/^[a-z]:[\\/]/i.test(systemRoot) || systemRoot.slice(2).includes(':'))
+        throw failure();
+    const candidate = path.join(systemRoot, 'System32', 'taskkill.exe');
+    const roots = [path.resolve(workspace), await realpath(workspace)];
+    const insideWorkspace = (target) => roots.some(root => {
+        const relative = path.relative(root, target);
+        return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+    });
+    if (insideWorkspace(candidate))
+        throw failure();
+    const canonicalRoot = await realpath(systemRoot).catch(() => undefined);
+    const executable = await realpath(candidate).catch(() => undefined);
+    if (!canonicalRoot || !executable || insideWorkspace(executable)
+        || path.relative(path.join(canonicalRoot, 'System32', 'taskkill.exe'), executable) !== ''
+        || !(await stat(executable).catch(() => undefined))?.isFile())
+        throw failure();
+    return executable;
+}
+async function stopWindows(child, taskkill) {
+    if (!child.pid)
+        return;
+    // On busy Windows hosts tree enumeration itself can take several seconds.
+    // Killing only the parent after an overly short timeout strands its children.
+    try {
+        await executeFile(taskkill, ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, timeout: 20_000 });
+    }
+    catch {
+        child.kill();
+    }
+}
+function containsPath(root, target) {
+    const relative = path.relative(root, target);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+/** A nested cwd does not make the rest of its repository a trusted installation. */
+async function launcherExclusionRoots(workspace) {
+    const roots = new Set([path.resolve(workspace), await realpath(workspace)]);
+    for (const initial of [...roots]) {
+        let directory = initial;
+        while (true) {
+            // Both ordinary repositories and worktrees/submodules use this marker.
+            if (await stat(path.join(directory, '.git')).catch(() => undefined)) {
+                roots.add(directory);
+                roots.add(await realpath(directory));
+                break;
+            }
+            const parent = path.dirname(directory);
+            if (parent === directory)
+                break;
+            directory = parent;
+        }
+    }
+    return [...roots];
+}
+async function validateLauncher(roots, candidate) {
+    const absolute = path.resolve(candidate);
+    if (roots.some(root => containsPath(root, absolute)))
+        return undefined;
+    const resolved = await realpath(candidate).catch(() => undefined);
+    if (!resolved || roots.some(root => containsPath(root, resolved)) || !(await stat(resolved).catch(() => undefined))?.isFile())
+        return undefined;
+    return resolved;
+}
+/** Canonical repository exclusion applies to configured, packaged and PATH candidates. */
+export async function validateCodexExecutableOutsideWorkspace(workspace, candidate) {
+    return validateLauncher(await launcherExclusionRoots(workspace), candidate);
+}
+export async function resolveTrustedCodexExecutable(workspace, options = {}) {
+    const env = options.env ?? process.env;
+    try {
+        if (env.ANDORRA_CODEX_PATH && !path.isAbsolute(env.ANDORRA_CODEX_PATH))
+            throw new Error('Restricted launch overrides must name an absolute installation path');
+        const excluded = await launcherExclusionRoots(workspace);
+        // PATH order is discovery, not an installation trust grant. Custom native
+        // or npm global prefixes remain supported through the explicit override.
+        const installations = [
+            ...(env.LOCALAPPDATA ? [path.join(env.LOCALAPPDATA, 'Programs', 'OpenAI', 'Codex')] : []),
+            ...(env.ProgramFiles ? [path.join(env.ProgramFiles, 'OpenAI', 'Codex')] : []),
+            ...(env.APPDATA ? [path.join(env.APPDATA, 'npm')] : []),
+            path.join(homedir(), 'AppData', 'Local', 'Programs', 'OpenAI', 'Codex'),
+            path.join(env.ProgramFiles ?? 'C:\\Program Files', 'OpenAI', 'Codex'),
+            path.join(homedir(), 'AppData', 'Roaming', 'npm'),
+            path.join(homedir(), '.cargo', 'bin'),
+        ];
+        const canonicalInstallations = (await Promise.all(installations.map(root => realpath(root).catch(() => undefined))))
+            .filter((root) => !!root && !excluded.some(exclusion => containsPath(exclusion, root)));
+        const executable = await resolveCodexExecutable({
+            platform: 'win32', arch: options.arch, env,
+            extraCandidates: [
+                path.join(homedir(), 'AppData', 'Local', 'Programs', 'OpenAI', 'Codex', 'bin', 'codex.exe'),
+                path.join(env.ProgramFiles ?? 'C:\\Program Files', 'OpenAI', 'Codex', 'bin', 'codex.exe'),
+                path.join(homedir(), '.cargo', 'bin', 'codex.exe'),
+            ],
+            // Validate both npm shims before package discovery and the final native
+            // executable. No shim is ever executed, and canonical aliases into the
+            // workspace cannot supply either the package or its native launcher.
+            validateCandidate: async (candidate) => {
+                if (!/\.(?:exe|cmd|bat)$/i.test(candidate))
+                    return undefined;
+                // Reject untrusted automatic PATH entries before probing them, including
+                // remote shares that must not receive an unsandboxed filesystem request.
+                if (!env.ANDORRA_CODEX_PATH && !installations.some(root => containsPath(path.resolve(root), path.resolve(candidate))))
+                    return undefined;
+                const validated = await validateLauncher(excluded, candidate);
+                if (!validated)
+                    return undefined;
+                if (env.ANDORRA_CODEX_PATH)
+                    return validated;
+                // The trusted installation location and its canonical target must agree;
+                // aliases into excluded repositories remain forbidden by validateLauncher.
+                if (!canonicalInstallations.some(root => containsPath(root, validated)))
+                    return undefined;
+                return validated;
+            },
+        });
+        if (!/\.exe$/i.test(executable))
+            throw new Error('Native Codex executable required');
+        return executable;
+    }
+    catch {
+        throw new Error('Restricted shell requires a trusted native Codex installation outside the workspace. Set ANDORRA_CODEX_PATH to an external native installation or install the official Codex CLI. Workspace launchers and npm shims are not executed; no host fallback was run.');
+    }
+}
+export function codexSandboxArgs(cwd, protectedRoots, sandbox, command, kind = defaultShellKind) {
+    const tomlString = (value) => JSON.stringify(value.replace(/\\/g, '/'));
+    // Describe the required policy; building a profile does not prove enforcement.
+    // Actual restricted launches stay blocked until a backend is verified to
+    // enforce the read boundary, including its implicit platform allowances.
+    const moduleRoot = path.dirname(fileURLToPath(import.meta.url));
+    // Match the engine imports from src (and dist/src in the published package).
+    const runtimeRoots = [path.dirname(process.execPath), moduleRoot, path.resolve(moduleRoot, '../vendor/engine/runtime'), path.resolve(moduleRoot, '../../node_modules')];
+    // Concrete runtime paths are more specific than the workspace grant. When the
+    // CLI itself is inside a writable workspace, inherit that grant instead of
+    // making its source, dependencies, or engine runtime unexpectedly read-only.
+    const workspaceRoot = path.resolve(cwd);
+    const runtimeReadRoots = runtimeRoots.filter(root => {
+        if (sandbox === 'read-only')
+            return true;
+        const relative = path.relative(workspaceRoot, path.resolve(root));
+        return relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+    });
+    const filesystem = ['":root"="none"', '":minimal"="read"', `":workspace_roots"=${tomlString(sandbox === 'read-only' ? 'read' : 'write')}`, ...runtimeReadRoots.map(root => `${tomlString(path.resolve(root))}="read"`), ...protectedRoots.map(root => `${tomlString(path.resolve(root))}="none"`)].join(',');
+    // Codex recursively merges profile tables, so each launch owns an unpredictable name.
+    const profile = `andorra-shell-${randomUUID()}`;
+    return ['sandbox', '-C', cwd, '-P', profile, '-c', `permissions={${profile}={workspace_roots={${tomlString(cwd)}=true},filesystem={${filesystem}},network={enabled=false}}}`, '-c', 'windows.sandbox="elevated"', '--', process.execPath, fileURLToPath(new URL('./sandbox-child.js', import.meta.url)), Buffer.from(command, 'utf8').toString('base64'), kind];
+}
+export const defaultShellKind = process.platform === 'win32' ? 'powershell' : 'posix';
+/** Terminate a spawned shell tree with the same owned-tree cleanup the shell tool uses. */
+export async function stopProcessTree(child, runId) {
+    return process.platform === 'win32' ? stopWindows(child, await resolveTrustedTaskkill(process.cwd())) : stopPosix(child, `ANDORRACODE_RUN_ID=${runId}`);
+}
+/**
+ * The exact environment shell execution inherits: configuration locations, never
+ * credential values. Process managers must build from this so background QA
+ * processes see the same view (and the same ANDORRACODE cleanup marker).
+ */
+export function shellBaseEnv(marker) {
+    const env = {};
+    const allowed = new Set([
+        'path', 'pathext', 'systemroot', 'windir', 'comspec', 'temp', 'tmp', 'tmpdir', 'lang', 'lc_all', 'term',
+        'codex_home', 'home', 'userprofile', 'homedrive', 'homepath', 'appdata', 'localappdata',
+        'xdg_config_home', 'xdg_cache_home', 'xdg_data_home', 'xdg_state_home', 'xdg_runtime_dir',
+    ]);
+    for (const [key, value] of Object.entries(process.env))
+        if (allowed.has(key.toLowerCase()))
+            env[key] = key.toLowerCase() === 'codex_home' && value ? path.resolve(value) : value;
+    if (marker !== undefined)
+        env.ANDORRACODE_RUN_ID = marker;
+    return env;
+}
+/** Resolve only the requested interpreter. Never fall back to cmd.exe or WSL. */
+export function shellInvocation(command, kind = defaultShellKind) {
+    if (kind === 'powershell') {
+        const executable = process.platform === 'win32'
+            ? path.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+            : 'pwsh';
+        // EncodedCommand bypasses Windows command-line quoting entirely; user code is
+        // interpreted exactly once by PowerShell, including JS arrows and redirects.
+        const payload = Buffer.from(command, 'utf8').toString('base64');
+        // Compile inside try so even syntax errors are emitted as ordinary UTF-8
+        // stderr instead of EncodedCommand's CLIXML error serialization.
+        // Windows PowerShell 5.1 promotes redirected native stderr to error records.
+        // Stop on cmdlet errors via common parameters, not on native stderr; render
+        // those records directly so warnings neither abort a process nor emit CLIXML.
+        const script = `$ErrorActionPreference = 'Continue'
+$PSDefaultParameterValues['*:ErrorAction'] = 'Stop'
+$PSDefaultParameterValues['Out-File:Encoding'] = 'utf8'
+$PSNativeCommandUseErrorActionPreference = $false
+$ProgressPreference = 'SilentlyContinue'
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$OutputEncoding = [Console]::OutputEncoding
+$andorraHadPowerShellError = $false
+try {
+& ([ScriptBlock]::Create([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${payload}')))) 2>&1 | ForEach-Object {
+  if ($_ -is [System.Management.Automation.ErrorRecord]) {
+    [Console]::Error.WriteLine($_.ToString())
+    if ($_.FullyQualifiedErrorId -notin @('NativeCommandError', 'NativeCommandErrorMessage')) { $andorraHadPowerShellError = $true }
+  } else { $_ }
+}
+if ($andorraHadPowerShellError) { exit 1 }
+if ($null -ne $LASTEXITCODE) { exit $LASTEXITCODE }
+} catch {
+[Console]::Error.WriteLine(($_ | Out-String))
+exit 1
+}`;
+        return { executable, args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-OutputFormat', 'Text', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')] };
+    }
+    let executable = kind === 'posix' ? '/bin/sh' : '/bin/bash';
+    if (process.platform === 'win32') {
+        if (kind !== 'bash')
+            throw new Error('POSIX sh is unavailable on Windows; request powershell or bash explicitly');
+        const candidates = [process.env.ProgramFiles, process.env['ProgramFiles(x86)'], process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, 'Programs')]
+            .filter((entry) => !!entry).map(entry => path.join(entry, 'Git', 'bin', 'bash.exe'));
+        executable = candidates.find(candidate => existsSync(candidate)) ?? '';
+        if (!executable)
+            throw new Error('Git Bash is not installed in a supported location. Use powershell or install Git for Windows.');
+    }
+    return { executable, args: ['-c', `trap 'andorra_exit_status=$?; trap - EXIT; wait; exit "$andorra_exit_status"' EXIT\neval "$1"`, 'andorra-shell', command] };
+}
+async function runShellCore(command, cwd, timeout, abortSignal, kind = defaultShellKind, onData, sandbox, launchPolicy, directInvocation) {
+    const requestStarted = Date.now();
+    let taskkill;
+    while (true) {
+        if (launchPolicy)
+            sandbox = launchPolicy();
+        if (sandbox && process.platform !== 'win32')
+            throw new Error('Restricted shell requires the verified Windows elevated Codex sandbox. This platform is not supported yet; request explicit escalation or choose Full Access.');
+        if (sandbox) {
+            // The installed Windows backend has both refused this profile and accepted
+            // it while allowing an owned Documents file outside all granted roots.
+            // Never let an unverified backend run the user's restricted command.
+            throw new Error(`Restricted shell is unavailable: the Windows backend cannot enforce workspace-only read access reliably (${sandbox}). No command or host fallback ran. Request explicit escalation with a justification, or choose Full Access.`);
+        }
+        // Validate before spawning, then retain this exact absolute path for timeout
+        // and abort cleanup even if environment variables change during execution.
+        taskkill = process.platform === 'win32' ? await resolveTrustedTaskkill(cwd) : undefined;
+        abortSignal.throwIfAborted();
+        // Discovery above can yield to live permission changes. Re-evaluate policy
+        // if needed; no await may separate this guard from spawn. Restricted modes
+        // reject before protected-root or launcher discovery can probe host paths.
+        if (launchPolicy && launchPolicy() !== sandbox)
+            continue;
+        break;
+    }
+    const runId = randomUUID();
+    const env = shellBaseEnv(runId);
+    abortSignal.throwIfAborted();
+    const started = Date.now();
+    return new Promise((resolve, reject) => {
+        // Retain the shell until background jobs finish, including on explicit exit.
+        // Passing the command as an argument preserves its quoting without interpolation.
+        const options = { cwd, env, windowsHide: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] };
+        const invocation = directInvocation ?? shellInvocation(command, kind);
+        const child = spawn(invocation.executable, invocation.args, options);
+        let firstOutputAt;
+        let closedAt;
+        let output = '', stdout = '', stderr = '', outputBytes = 0, truncated = false;
+        let timedOut = false, aborted = false, stopped;
+        let stopping;
+        const streams = [['out', child.stdout], ['err', child.stderr]];
+        for (const [target, stream] of streams) {
+            const decoder = new StringDecoder('utf8');
+            let clipped = false;
+            stream.on('data', (chunk) => {
+                firstOutputAt ??= Date.now();
+                onData?.(chunk);
+                const remaining = OUTPUT_LIMIT - outputBytes;
+                const accepted = chunk.subarray(0, Math.max(0, remaining));
+                outputBytes += accepted.length;
+                const text = decoder.write(accepted);
+                output += text;
+                if (target === 'out')
+                    stdout += text;
+                else
+                    stderr += text;
+                if (chunk.length > remaining) {
+                    clipped = true;
+                    truncated = true;
+                }
+            });
+            stream.on('end', () => {
+                // A byte limit may bisect a UTF-8 character: discard only that incomplete tail.
+                const tail = decoder.end();
+                if (!clipped) {
+                    output += tail;
+                    if (target === 'out')
+                        stdout += tail;
+                    else
+                        stderr += tail;
+                }
+            });
+        }
+        const stop = (reason) => {
+            if (stopped)
+                return;
+            stopped = reason;
+            stopping = process.platform === 'win32' ? stopWindows(child, taskkill) : stopPosix(child, `ANDORRACODE_RUN_ID=${runId}`);
+            // Escaped/inaccessible descendants can retain pipe descriptors after the shell exits.
+            // Cleanup has a deadline; pipe ownership must not extend the tool timeout indefinitely.
+            void stopping.finally(() => {
+                child.stdout.destroy();
+                child.stderr.destroy();
+                finish(child.exitCode, child.signalCode);
+            }).catch(reject);
+        };
+        const abort = () => { aborted = true; stop('Shell command aborted'); };
+        const timer = setTimeout(() => { timedOut = true; stop(`Shell command timed out after ${timeout} ms`); }, timeout);
+        abortSignal.addEventListener('abort', abort, { once: true });
+        if (abortSignal.aborted)
+            abort();
+        const cleanup = () => { clearTimeout(timer); abortSignal.removeEventListener('abort', abort); };
+        child.on('error', error => { cleanup(); reject(error); });
+        let settled = false;
+        const finish = (code, exitSignal) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            void (async () => {
+                await stopping;
+                const settledAt = Date.now();
+                recordCommandTiming({
+                    kind: directInvocation ? 'native' : 'shell',
+                    durationMs: settledAt - requestStarted,
+                    validationMs: started - requestStarted,
+                    spawnToCloseMs: (closedAt ?? settledAt) - started,
+                    ...(firstOutputAt === undefined ? {} : { firstOutputMs: firstOutputAt - started }),
+                    cleanupMs: settledAt - (closedAt ?? settledAt),
+                    timedOut, aborted, exitCode: code,
+                });
+                resolve({ exitCode: code, exitSignal, timedOut, aborted, stopReason: stopped, output, stdout, stderr, truncated, durationMs: settledAt - requestStarted });
+            })().catch(reject);
+        };
+        child.on('close', (code, exitSignal) => { closedAt = Date.now(); finish(code, exitSignal); });
+    });
+}
+/** Formatted legacy observation; rejects on timeout, abort and nonzero exits exactly as before. */
+export function runShell(command, cwd, timeout, abortSignal, kind = defaultShellKind, onData, sandbox, launchPolicy) {
+    return runShellCore(command, cwd, timeout, abortSignal, kind, onData, sandbox, launchPolicy).then(outcome => {
+        const observation = `Exit code: ${outcome.exitCode ?? outcome.exitSignal}\n${outcome.output}${outcome.truncated ? '\n[output truncated]' : ''}`;
+        if (outcome.stopReason)
+            throw new Error(`${outcome.stopReason}\n${observation}`);
+        if (outcome.exitCode !== 0 || outcome.exitSignal)
+            throw new Error(observation);
+        return observation;
+    }, error => { throw error; });
+}
+/**
+ * Structured shell execution for the QA layer: exit codes, streams and timeouts
+ * resolve as data so check runners can normalize results; only spawn failures and
+ * explicit cancellation reject, and cancellation keeps the legacy wording so the
+ * runtime still recognizes an aborted tool.
+ */
+export function executeShell(command, cwd, timeout, abortSignal, kind = defaultShellKind, sandbox) {
+    return runShellCore(command, cwd, timeout, abortSignal, kind, undefined, sandbox).then(outcome => {
+        if (outcome.aborted)
+            throw new Error('Shell command aborted');
+        return {
+            command, cwd, exitCode: outcome.exitCode, stdout: outcome.stdout, stderr: outcome.stderr,
+            durationMs: outcome.durationMs, timedOut: outcome.timedOut, truncated: outcome.truncated, exitSignal: outcome.exitSignal,
+        };
+    });
+}
+/** Execute an already-selected native program without spawning a command interpreter.
+ * Approval/sandbox enforcement and owned process-tree cleanup are identical to runShell.
+ */
+export function runNativeProcess(executable, args, cwd, timeout, abortSignal, launchPolicy) {
+    if (!executable || executable.includes('\0') || args.some(arg => typeof arg !== 'string' || arg.includes('\0'))) {
+        throw new Error('Native executable and arguments must not contain NUL bytes');
+    }
+    return runShellCore(executable, cwd, timeout, abortSignal, defaultShellKind, undefined, undefined, launchPolicy, { executable, args }).then(outcome => {
+        const observation = `Exit code: ${outcome.exitCode ?? outcome.exitSignal}\n${outcome.output}${outcome.truncated ? '\n[output truncated]' : ''}`;
+        if (outcome.stopReason)
+            throw new Error(`${outcome.stopReason}\n${observation}`);
+        if (outcome.exitCode !== 0 || outcome.exitSignal)
+            throw new Error(observation);
+        return observation;
+    });
+}

package/dist/src/side-panel.d.ts

@@ -0,0 +1,144 @@
+import type { Graph } from './graphs.js';
+import type { TodoItem } from './todos.js';
+/**
+ * The status panel that draws to the right of the conversation.
+ *
+ * The panel is a second column of the same frame: the transcript keeps its own layout at
+ * the reduced chat width and the panel is composed alongside it, one row at a time, so
+ * nothing reflows and the terminal keeps rewriting only the rows that changed. This module
+ * owns what the panel says and how its rows fit; the terminal owns painting them, and the
+ * CLI owns the I/O that produces the snapshot (a Git summary, the live terminal list), which
+ * is what keeps every layout rule here testable without a TTY.
+ *
+ * A row carries styled segments rather than one color so a single row can pair a label with
+ * a value in a semantic color (`+120` green beside `-8` red) the way the reference panel
+ * does. Callers that only care about the text use {@link panelRowText}.
+ */
+/** The working-tree summary the Git section reports. Produced by `git-summary.ts`. */
+export interface PanelChanges {
+    isGit: boolean;
+    /**
+     * The branch the summary's own repository read reported, when it could name one.
+     *
+     * The panel shows this rather than `TerminalStatus.branch`, because the two readers answer
+     * different questions: `gitBranch` refuses metadata outside the workspace by design, so a
+     * workspace that is a subdirectory of a repository has no branch there while the summary -
+     * which asks git itself - does. One row, one repository.
+     */
+    branch?: string;
+    /** Tracked files with staged or unstaged changes, renames counted once. */
+    files: number;
+    /** Untracked files, counted separately because they carry no line statistics here. */
+    untracked: number;
+    insertions: number;
+    deletions: number;
+    /**
+     * Why the change counts are absent, when they are.
+     *
+     * One case refuses to read the working tree at all: a repository whose configuration defines
+     * a Git filter driver, because comparing the worktree through that driver would run a
+     * workspace-controlled command on a panel refresh. The panel says so instead of showing a
+     * count nothing measured.
+     */
+    skipped?: string;
+    /**
+     * Why no reading could be taken at all, when none could.
+     *
+     * A failed read with no earlier success to fall back on reports this rather than leaving the
+     * section claiming to be reading forever.
+     */
+    unavailable?: string;
+}
+/** One background terminal session the panel lists. Running sessions carry their age. */
+export interface PanelTerminal {
+    id: string;
+    command: string;
+    running: boolean;
+    startedAt?: number;
+}
+/** One graph node the run is on. The first entry is the node the reader is watching. */
+export interface PanelNode {
+    id: string;
+    name: string;
+    detail?: string;
+    model?: string;
+}
+/** Everything the panel draws, snapshotted by the terminal at render time. */
+export interface PanelData {
+    branch?: string;
+    changes?: PanelChanges;
+    nodes: readonly PanelNode[];
+    graph?: Graph;
+    /** Whether the selected graph is a custom one; the zoom section is only for those. */
+    customGraph: boolean;
+    /** Node ids visited during the current run, in visit order. */
+    visited: readonly string[];
+    /**
+     * The node a cancelled, exhausted or failed run stopped on, when one was named.
+     *
+     * It never completed, so it is not part of {@link visited}; it is the position the zoom must
+     * show afterwards, because reporting the last completed predecessor instead would say the run
+     * ended somewhere it did not.
+     */
+    stoppedNode?: string;
+    todos: readonly TodoItem[];
+    terminals: readonly PanelTerminal[];
+    /** Clock used for terminal ages; injected so tests read deterministic rows. */
+    now: number;
+}
+export interface PanelSegment {
+    text: string;
+    color?: number | string;
+}
+export interface PanelRow {
+    segments: readonly PanelSegment[];
+}
+/** The plain text of a row, for tests and width checks that care about content, not color. */
+export declare const panelRowText: (row: PanelRow) => string;
+/**
+ * Visible columns the terminal needs before the panel is worth drawing.
+ *
+ * The panel claims roughly a third of the width, so below this the chat column would drop
+ * under about 77 columns: narrow enough that the transcript's own wrapping and the command
+ * popup degrade, which is a worse trade than losing the panel.
+ */
+export declare const PANEL_MIN_COLUMNS = 110;
+/**
+ * Rows the panel needs before it is drawn.
+ *
+ * The floor is the tallest fixed stack the panel can reach - the Git section's four rows,
+ * the Node section's four, and the progress summary's three, plus the rules between them -
+ * so a terminal that shows the panel always has room for every section that cannot shrink.
+ */
+export declare const PANEL_MIN_ROWS = 14;
+/**
+ * Total columns the panel occupies at a given terminal width, divider included.
+ *
+ * A fixed share keeps the panel's measurements stable as the terminal grows while the clamps
+ * stop it from becoming a second chat column on very wide terminals or a sliver on the
+ * narrowest ones that still show it.
+ */
+export declare const panelWidth: (columns: number) => number;
+/**
+ * Whether the selected graph is a custom one.
+ *
+ * The built-in Software Engineer harness is stored under `'default'` (and answers to its own
+ * id when a graph file was never written), so both spell the default; anything else is a
+ * user-authored graph, which is what the zoom section exists for.
+ */
+export declare const isCustomGraph: (selection: string | undefined, graph: Graph | undefined) => boolean;
+/** `5m 20s`, `1h 04m`, `12s` - the age a background terminal has been running. */
+export declare function panelDuration(milliseconds: number): string;
+/**
+ * The panel's rows, top to bottom, for a terminal of `columns` x `height`.
+ *
+ * Sections are anchored: Git tools, Node, Progress and the plan read from the top, while the
+ * terminal list and the graph zoom are held against the bottom - the reader asked for the graph
+ * section to be at the bottom of the panel - with whatever rows the top sections leave as blank
+ * space between them, so a tall terminal does not park the zoom in the middle of the screen.
+ * The panel never outgrows the terminal: the plan list is elastic and takes only what the fixed
+ * sections leave, and when even those overflow, whole sections are given up from the bottom
+ * upward - the zoom first, then the terminal list - because the sections above them are read on
+ * every run while those two describe states that come and go.
+ */
+export declare function sidePanelRows(data: PanelData, columns: number, height: number): PanelRow[];