zames_pro 2.71.0 → 2.72.1

package/dist/changelog.js

@@ -78,3 +78,32 @@ export function renderChangelogDraft(groups) {
     }
     return out.join('\n').trimEnd();
 }
+/**
+ * Replace the body between `## [Unreleased]` and the next `## [` heading with
+ * a freshly drafted body (D2). PURE so a test can pin the exact behavior.
+ *
+ * When `body` is empty the existing Unreleased section is CLEARED to just the
+ * heading (no stray blank content). A changelog without an Unreleased heading
+ * is returned UNCHANGED (we never guess where to insert one).
+ */
+export function syncUnreleased(changelog, body) {
+    const nl = '\n';
+    const anchor = '## [Unreleased]';
+    const idx = changelog.indexOf(anchor);
+    if (idx < 0)
+        return changelog;
+    const afterAnchor = idx + anchor.length;
+    // The section ends at the next top-level `## [` (the next version).
+    const rest = changelog.slice(afterAnchor);
+    const next = rest.search(/\n## \[/);
+    const tail = next < 0 ? '' : rest.slice(next);
+    const cleanBody = String(body || '')
+        .replace(/^## \[Unreleased\]\s*/m, '')
+        .trim()
+        // The draft renders groups as `## Added` (top-level), but INSIDE the file
+        // a version's groups are `### Added` (a subsection of the version heading).
+        // `## [` (the next version) is left alone.
+        .replace(/^## (?!\[)/gm, '### ');
+    const section = cleanBody ? nl + nl + cleanBody + nl : nl;
+    return changelog.slice(0, afterAnchor) + section + tail;
+}

package/dist/cli-args.js

@@ -0,0 +1,48 @@
+// PURE CLI argument parsing (BACKLOG C3). index.ts used to hold `args` as a
+// module-level constant plus three helpers closing over it, which made the
+// parsing impossible to unit-test in isolation (index.ts is the entry point and
+// is not covered). `createCliArgs(argv)` binds the argv ONCE and returns the
+// same three helpers, so every call site in index.ts keeps its shape
+// (`getArg('--x')` / `hasFlag('--x')`) while the LOGIC is now pure and tested.
+//
+// Behavior is intentionally identical to the old inline helpers, including the
+// quirk that a value-flag appearing WITHOUT a value returns the fallback (never
+// the flag itself or the next flag).
+// Flags that consume the NEXT argv entry as their value, so the positional
+// parser must skip it. Kept in sync with the getArg call sites by
+// test/cli-flags.test.ts.
+export const SKIP_VALUE_FLAGS = [
+    '--dir',
+    '--task',
+    '--max-iter',
+    '--chat',
+    '--output-format',
+];
+export function createCliArgs(argv) {
+    const args = Array.isArray(argv) ? argv : [];
+    const getArg = (flag, fallback = null) => {
+        const i = args.indexOf(flag);
+        // `args[i + 1]` truthiness means an empty string or a missing value falls
+        // back — the historical behavior (an empty `--task ''` is not a task).
+        // NOTE: this does NOT special-case a following FLAG, so `--task --debug`
+        // returns `--debug` (the original inline helper did the same); we preserve
+        // it rather than "fix" a long-standing quirk in a refactor.
+        return i !== -1 && args[i + 1] ? args[i + 1] : fallback;
+    };
+    const hasFlag = (flag) => args.includes(flag);
+    const getPositional = () => {
+        const positional = [];
+        for (let i = 0; i < args.length; i++) {
+            const a = args[i];
+            if (SKIP_VALUE_FLAGS.includes(a)) {
+                i++;
+                continue;
+            }
+            if (a.startsWith('--'))
+                continue;
+            positional.push(a);
+        }
+        return positional;
+    };
+    return { getArg, hasFlag, getPositional };
+}

package/dist/compact.js

@@ -1,5 +1,6 @@
 import { translate } from './i18n.js';
 import { buildCompactPrompt, buildCompactCarryover, isUsableCompactSummary, trimRestoredMessages, formatRestoredHistory, } from './commands.js';
+import { loadHooks, runLifecycleHooks } from './hooks.js';
 const NL = String.fromCharCode(10);
 /** How many times the summary call is retried before the local fallback. */
 export const COMPACT_SUMMARY_ATTEMPTS = 3;
@@ -42,6 +43,14 @@ export async function performCompact(opts) {
     try {
         if (!quiet)
             log(t('compact.start'));
+        // PreCompact hook (N32): runs BEFORE the chat is summarized/rewritten, so
+        // a hook can persist state or notify. Best-effort.
+        try {
+            const out = await runLifecycleHooks(loadHooks(workdir), 'PreCompact', workdir, { chatId: currentChatId });
+            if (out)
+                transcript?.log('hook_pre_compact', { output: out });
+        }
+        catch { }
         // 1) Ask the OLD chat to summarize itself.
         let summary = '';
         let summaryErr = '';

package/dist/config.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { DEFAULT_DIAGNOSTICS } from './diagnostics.js';
 import { DEFAULT_LOCALE } from './i18n.js';
 import { writeJsonAtomic } from './fsutil.js';
 const ZAMES_HOME = path.join(os.homedir(), '.zames');
@@ -67,7 +68,12 @@ export const DEFAULTS = {
         contextLimit: 1_000_000,
         // 0 = auto: terminal width, capped at 100 columns (the historical width).
         answerWidth: 0,
+        // N37 statusLine hook. Off by default; edit config.json to set a command.
+        statusLineCommand: '',
+        statusLineIntervalMs: 10_000,
     },
+    // Off by default: a full tsc/eslint run after every edit is slow; opt in.
+    diagnostics: { ...DEFAULT_DIAGNOSTICS },
 };
 export function loadConfig() {
     const merged = JSON.parse(JSON.stringify(DEFAULTS));

package/dist/diagnostics.js

@@ -0,0 +1,71 @@
+import { spawnSync } from 'node:child_process';
+export const DEFAULT_DIAGNOSTICS = {
+    enabled: false,
+    command: 'npx tsc --noEmit',
+    timeoutMs: 60_000,
+    tools: ['Edit', 'Write', 'MultiEdit', 'ApplyPatch'],
+    maxChars: 4000,
+};
+/** True when the tool mutates files and so should trigger a check. */
+export function shouldRunDiagnostics(cfg, tool) {
+    if (!cfg || !cfg.enabled)
+        return false;
+    if (!cfg.command || !cfg.command.trim())
+        return false;
+    return (cfg.tools || DEFAULT_DIAGNOSTICS.tools).includes(tool);
+}
+/**
+ * Collapse a check's output to the lines a model actually needs. A clean run
+ * (empty output, or tsc's "no errors") returns null: there is nothing to say,
+ * and a noise line on every edit would train the model to ignore it.
+ */
+export function summarizeDiagnostics(raw, maxChars) {
+    const text = String(raw || '').trim();
+    if (!text)
+        return null;
+    // tsc prints nothing on success; eslint prints nothing too. Guard against a
+    // benign banner that some tools emit.
+    if (/^(no errors?\.?|0 problems?.*)$/im.test(text) && text.length < 40) {
+        return null;
+    }
+    // Keep only error-looking lines when we can recognise them, so a long build
+    // log collapses to the actual problems. Fall back to the whole output.
+    const lines = text.split(/\r?\n/);
+    const errLines = lines.filter((l) => /error|warning|✖|✗|TS\d{4}|\bnot assignable\b|\bcannot find\b/i.test(l));
+    const chosen = errLines.length ? errLines : lines;
+    let out = chosen.join('\n');
+    if (out.length > maxChars) {
+        out = out.slice(0, maxChars) + '\n… [diagnostics truncated]';
+    }
+    return out;
+}
+/**
+ * Run the diagnostics command and return a human-readable summary, or null
+ * when it is disabled / clean. Never throws: a failed spawn is treated as
+ * "no diagnostics" so an edit is never blocked by the checker.
+ */
+export function runDiagnostics(workdir, cfg) {
+    if (!cfg || !cfg.enabled || !cfg.command || !cfg.command.trim())
+        return null;
+    const isWin = process.platform === 'win32';
+    let res;
+    try {
+        res = spawnSync(cfg.command, {
+            cwd: workdir,
+            shell: isWin ? process.env.ComSpec || true : '/bin/sh',
+            timeout: cfg.timeoutMs || DEFAULT_DIAGNOSTICS.timeoutMs,
+            encoding: 'utf-8',
+            windowsHide: true,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (res.error)
+        return null;
+    const out = String(res.stdout || '') + String(res.stderr || '');
+    const summary = summarizeDiagnostics(out, cfg.maxChars || DEFAULT_DIAGNOSTICS.maxChars);
+    // Exit 0 with a summary means warnings only; still surface them.
+    return summary;
+}

package/dist/hooks.js

@@ -1,6 +1,13 @@
 import fs from 'fs';
 import path from 'path';
 import { exec } from 'child_process';
+const LIFECYCLE_EVENTS = [
+    'SessionStart',
+    'UserPromptSubmit',
+    'PreCompact',
+    'Stop',
+    'SubagentStop',
+];
 // A hook is a helper, not a task: if it has not finished in ten seconds the
 // tool call must not be held hostage by it.
 const HOOK_TIMEOUT_MS = 10_000;
@@ -33,6 +40,11 @@ export function loadHooks(workdir) {
     return {
         PreToolUse: normalizeEntries(obj['PreToolUse']),
         PostToolUse: normalizeEntries(obj['PostToolUse']),
+        SessionStart: normalizeEntries(obj['SessionStart']),
+        UserPromptSubmit: normalizeEntries(obj['UserPromptSubmit']),
+        PreCompact: normalizeEntries(obj['PreCompact']),
+        Stop: normalizeEntries(obj['Stop']),
+        SubagentStop: normalizeEntries(obj['SubagentStop']),
     };
 }
 function normalizeEntries(value) {
@@ -141,11 +153,27 @@ export async function runPreToolUse(hooks, tool, args, workdir) {
  * its result must be reported.
  */
 export async function runPostToolUse(hooks, tool, args, result, workdir) {
+    return runEventHooks(hooks, 'PostToolUse', workdir, tool, args, result);
+}
+/**
+ * Run every hook registered for a LIFECYCLE event (SessionStart, Stop, …).
+ * Best-effort like the tool hooks: the combined stdout is returned to the
+ * caller for a notice, and errors never break the task. `tool`/`args` are
+ * informational for these events (there is no tool call), so they default to
+ * the event name and an empty object.
+ */
+export async function runLifecycleHooks(hooks, event, workdir, extra = {}) {
+    if (!LIFECYCLE_EVENTS.includes(event))
+        return '';
+    return runEventHooks(hooks, event, workdir, event, extra);
+}
+async function runEventHooks(hooks, event, workdir, tool, args, result) {
+    const list = hooks?.[event];
     const parts = [];
-    for (const entry of hooks?.PostToolUse ?? []) {
+    for (const entry of list ?? []) {
         if (!matchesHook(entry, tool))
             continue;
-        const r = await runHook(entry, 'PostToolUse', tool, args, workdir, result);
+        const r = await runHook(entry, event, tool, args, workdir, result);
         const out = r.stdout.trim();
         if (out)
             parts.push(out);

package/dist/i18n/common.js

@@ -116,6 +116,10 @@ export const commonMessages = {
         ru: 'Разрешить выполнение?',
         en: 'Allow this call?',
     },
+    'perm.ask_sub': {
+        ru: '⚠ Субагент запрашивает подтверждение: {tool} ({reason})',
+        en: '⚠ Subagent approval required: {tool} ({reason})',
+    },
     'perm.allowed': {
         ru: '✔ Разрешено оператором.',
         en: '✔ Allowed by operator.',

package/dist/index.js

@@ -22,10 +22,13 @@ import { CheckpointStore, pickRecord as pickCheckpoint } from './checkpoint.js';
 import { selfReview, selfDiff, selfApply, selfList } from './self-review.js';
 import { performCompact } from './compact.js';
 import { Scheduler, parseInterval, formatInterval, formatJobLine, parseCron, } from './scheduler.js';
+import { createCliArgs } from './cli-args.js';
 import { renderMarkdown, setAnswerWidth } from './markdown.js';
+import { runStatusLineCommand } from './statusline.js';
 import { parseBacklogNote } from './backlog.js';
+import { askOperatorConfirm, } from './run-task.js';
 import { closeWeb } from './web.js';
-import { assertCommandInsideRoot, runShell } from './shell.js';
+import { assertCommandInsideRoot, runShell, killAllBackground, } from './shell.js';
 import { saveSession, loadLastSession, readSession, listSessions, sessionsDir, loadHistory, saveHistory, } from './sessions.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const NL = String.fromCharCode(10);
@@ -48,28 +51,9 @@ function authMarkerExists() {
     }
 }
 // ---------- CLI parsing ----------
-const args = process.argv.slice(2);
-function getArg(flag, fallback = null) {
-    const i = args.indexOf(flag);
-    return i !== -1 && args[i + 1] ? args[i + 1] : fallback;
-}
-function hasFlag(flag) {
-    return args.includes(flag);
-}
-function getPositional() {
-    const positional = [];
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i];
-        if (['--dir', '--task', '--max-iter', '--chat', '--output-format'].includes(a)) {
-            i++;
-            continue;
-        }
-        if (a.startsWith('--'))
-            continue;
-        positional.push(a);
-    }
-    return positional;
-}
+// The pure helpers live in src/cli-args.ts (C3) and are bound to this process's
+// argv ONCE here. Call sites keep using getArg/hasFlag/getPositional.
+const { getArg, hasFlag, getPositional } = createCliArgs(process.argv.slice(2));
 // /compact asks the OLD chat for a summary. If browser.ask() exhausts its own
 // rate-limit budget, aborting the whole compaction used to force the operator
 // to start over. We retry the summary call a few times instead (inside
@@ -1146,7 +1130,20 @@ async function main() {
             maxSubagents: config.browser.maxSubagents,
             askDeadlineMs: config.browser.askDeadlineMs,
             maxAfterToolRetries: config.browser.maxAfterToolRetries,
-            selfImprovement: devMode,
+            // An `ask` permission rule must also gate the subagent: otherwise a
+            // guarded tool (e.g. a dangerous Bash command) would run inside the
+            // subagent WITHOUT the operator's confirmation.
+            onAskPermission: async (info) => {
+                if (editor)
+                    editor.pause();
+                try {
+                    return await askOperatorConfirm(null, t('perm.ask_sub', { tool: info.tool, reason: info.reason }));
+                }
+                finally {
+                    if (editor)
+                        editor.resume();
+                }
+            },
         })
         : null;
     // A compact "tasks: 2/5" summary for the status line. Empty when the list
@@ -1245,6 +1242,8 @@ async function main() {
     let reviewMode = null;
     process.on('SIGINT', async () => {
         running = false;
+        // Kill any background processes (N33) so no dev-server outlives the agent.
+        killAllBackground();
         await browser.close().catch(() => { });
         // Close the lazy headless browser from web.js, otherwise it would stay
         // as a separate process after the agent exits.
@@ -1297,6 +1296,8 @@ async function main() {
     // the typed text is never overwritten by output. In non-TTY (pipe) —
     // the old promptOnce.
     let editor = null;
+    // N37 statusLine hook timer (cleared on exit).
+    let statusLineTimer = null;
     let waiter = null;
     const takeInput = () => {
         if (pendingQueue.length)
@@ -1347,6 +1348,28 @@ async function main() {
         // Toggle icons (🧠 deep thinking, 🌐 web search) before the context
         // counter. The editor pulls the live state on every render.
         ed.onToggleQuery = () => browser.getToggleStatesSync();
+        // N37 statusLine hook: run the configured command on its own timer (never
+        // per-render — a spawn would block typing) and show its first stdout line
+        // in the status line. Off when ui.statusLineCommand is empty.
+        if (config.ui.statusLineCommand) {
+            const statusLineInfo = () => ({
+                chatId: currentChatId,
+                queueLength: pendingQueue.length,
+                tokens: browser.getLastTokenUsage(),
+                contextLimit: config.ui.contextLimit,
+                tasks: todosSummary(),
+                locale: currentLocale,
+            });
+            const tick = async () => {
+                const line = await runStatusLineCommand(currentWorkdir, config.ui.statusLineCommand, statusLineInfo()).catch(() => '');
+                editor?.setStatusLine(line);
+            };
+            void tick();
+            const interval = Math.max(2000, config.ui.statusLineIntervalMs || 10_000);
+            statusLineTimer = setInterval(() => void tick(), interval);
+            if (typeof statusLineTimer.unref === 'function')
+                statusLineTimer.unref();
+        }
         ed.onAttach = async (raw) => {
             // Case 1: the paste is the image data itself (data URL / base64 blob).
             const image = parseImagePaste(raw);
@@ -3501,6 +3524,8 @@ async function main() {
         editor.dispose();
     if (scheduleTimer)
         clearInterval(scheduleTimer);
+    if (statusLineTimer)
+        clearInterval(statusLineTimer);
     await browser.close().catch(() => { });
     await mod.closeWeb().catch(() => { });
     if (mcpPool)

package/dist/input.js

@@ -163,6 +163,11 @@ export class LineEditor {
     // A callback the editor calls before every render to read the agent's
     // current task-list summary ("tasks: 2/5"), empty when there is no list.
     onTasksQuery;
+    // Extra status text produced by an external command (N37 statusLine hook).
+    // Set via setStatusLine(); shown before the queue/tasks badges. Kept as a
+    // plain field because the CALLER runs the command on its own timer (a
+    // per-render spawn would block typing).
+    statusLine;
     // Whether the DeepSeek "Deep thinking" / "Smart search" toggles are ON.
     // Shown as two colored icons before the context counter: a dim gray icon
     // means off, a teal-green icon means on.
@@ -256,6 +261,7 @@ export class LineEditor {
         this.onToggleQuery = null;
         this.onContextQuery = null;
         this.queueLength = 0;
+        this.statusLine = '';
         this.onQueueQuery = null;
         this.onTasksQuery = null;
     }
@@ -339,6 +345,11 @@ export class LineEditor {
             return '';
         }
     }
+    // The statusLine hook text (N37), shown before the queue/tasks badges.
+    // A trailing space separates it from whatever follows; empty hides it.
+    _statusLineBadge() {
+        return this.statusLine ? theme.system(this.statusLine) + ' ' : '';
+    }
     // Icons for the DeepSeek toggles: 🧠 "Deep thinking" and 🌐 "Smart search",
     // shown before the context counter. Only the ENABLED toggles are shown, so
     // the state is unambiguous WITHOUT relying on the terminal coloring the
@@ -623,6 +634,15 @@ export class LineEditor {
     }
     // Update the context window size (from config.ui.contextLimit). The next
     // render recomputes the percentage and its color with the new limit.
+    // Set the statusLine hook text (N37). The caller runs the command on its
+    // own timer; this only stores + repaints. An empty string hides the badge.
+    setStatusLine(text) {
+        const t = String(text || '').trim();
+        if (t === this.statusLine)
+            return;
+        this.statusLine = t;
+        this._render();
+    }
     setContextLimit(limit) {
         if (typeof limit === 'number' && Number.isFinite(limit) && limit > 0) {
             this.contextLimit = limit;
@@ -721,7 +741,11 @@ export class LineEditor {
         // but the icons are still meaningful.
         const ctxRaw = this._contextText();
         this._refreshToggles();
-        const ctxText = this._queueBadge() + this._tasksBadge() + this._toggleIcons() + ctxRaw;
+        const ctxText = this._statusLineBadge() +
+            this._queueBadge() +
+            this._tasksBadge() +
+            this._toggleIcons() +
+            ctxRaw;
         let statusOut = '';
         let top = 0;
         // Never fill a row to the FULL terminal width: on terminals with

package/dist/run-task.js

@@ -279,6 +279,8 @@ export async function runTask(deps, browser, tools, taskText, workdir, opts, att
         // Set when the loop ends without a real answer (iteration limit / watchdog)
         // so the one-shot mode can exit non-zero. See N5.
         let failure = null;
+        // N31: the machine-readable reason for the last task's outcome.
+        let outcomeKind = 'ok';
         let next = {
             text: taskText,
             attachments,
@@ -359,6 +361,9 @@ export async function runTask(deps, browser, tools, taskText, workdir, opts, att
                 getTokenUsage,
                 selfImprovement,
                 onSubagent,
+                // N38: the check command appended to a tool result after an edit
+                // (off by default; config.diagnostics).
+                diagnostics: deps.config.diagnostics,
             });
             // The loop may end WITHOUT a model answer: an exhausted iteration limit
             // or an ask() watchdog. Surface it instead of a silent stop.
@@ -368,6 +373,14 @@ export async function runTask(deps, browser, tools, taskText, workdir, opts, att
                 ui.warning(outcome);
                 transcript?.log('agent_no_answer', { outcome });
                 failure = outcome;
+                // N31: a machine-readable reason so `--output-format jsonl` consumers
+                // (CI) can tell a real error from an exhausted limit / watchdog.
+                outcomeKind = outcome.startsWith('Iteration limit reached')
+                    ? 'iteration_limit'
+                    : 'watchdog';
+            }
+            else {
+                outcomeKind = 'ok';
             }
             // T7: one summary line per task (duration + tool calls + tokens spent).
             // Printed even on an abort, so the operator sees what happened.
@@ -433,6 +446,23 @@ export async function runTask(deps, browser, tools, taskText, workdir, opts, att
                 sendSystemPrompt: false,
             };
         }
+        // Stop hook (N32): the whole task (including drained queue messages) is
+        // done. A cleanup/notification hook runs here. Best-effort.
+        try {
+            const { runLifecycleHooks } = await import('./hooks.js');
+            const out = await runLifecycleHooks(undefined, 'Stop', workdir, {
+                failure: failure ?? '',
+            });
+            if (out)
+                ui.warning(out);
+        }
+        catch { }
+        // N31: a single terminal event carrying the reason, so a jsonl consumer
+        // does not have to guess from the exit code alone.
+        transcript?.log('task_result', {
+            ok: !failure,
+            outcome: failure ? outcomeKind : 'ok',
+        });
         return failure ? { ok: false, error: failure } : { ok: true };
     }
     catch (e) {
@@ -441,6 +471,7 @@ export async function runTask(deps, browser, tools, taskText, workdir, opts, att
         if (debug)
             console.error(e.stack);
         transcript?.log('agent_error', { error: e.message });
+        transcript?.log('task_result', { ok: false, outcome: 'error' });
         return { ok: false, error: e.message };
     }
     finally {

package/dist/shell.js

@@ -1,6 +1,7 @@
-import { exec, execFile } from 'child_process';
+import { exec, execFile, spawn } from 'child_process';
 import path from 'path';
 import os from 'os';
+import { randomBytes } from 'crypto';
 // Shared shell runner for the Bash tool and the operator's `!command` escape.
 // Kept in its own module so both call sites use the SAME sandbox guard and the
 // SAME abort wiring; a second, ad-hoc runner would drift from the real one.
@@ -87,6 +88,106 @@ export function runShell(workdir, command, timeout = 30_000, signal) {
         });
     });
 }
+const BG_PROCS = new Map();
+const BG_MAX_BUFFER = 1024 * 1024;
+function bgTrim(p) {
+    if (p.out.length > BG_MAX_BUFFER) {
+        p.out =
+            '[...earlier output trimmed]' +
+                String.fromCharCode(10) +
+                p.out.slice(p.out.length - BG_MAX_BUFFER);
+    }
+}
+/** Start a shell command in the background. Returns a short id. */
+export function startBackground(workdir, command) {
+    const id = randomBytes(3).toString('hex');
+    const shellCmd = process.platform === 'win32'
+        ? process.env.ComSpec || 'C:\\Windows\\System32\\cmd.exe'
+        : '/bin/sh';
+    const child = spawn(shellCmd, ['-c', command], {
+        cwd: workdir,
+        windowsHide: true,
+        env: { ...process.env },
+        // Own process group so a kill reaches children (a dev server spawns more).
+        detached: process.platform !== 'win32',
+    });
+    const proc = {
+        id,
+        command,
+        child,
+        out: '',
+        status: 'running',
+        code: null,
+        signal: null,
+        startedAt: Date.now(),
+    };
+    const append = (chunk) => {
+        proc.out += chunk.toString();
+        bgTrim(proc);
+    };
+    child.stdout?.on('data', append);
+    child.stderr?.on('data', append);
+    child.on('exit', (code, signal) => {
+        proc.status = 'exited';
+        proc.code = code;
+        proc.signal = signal;
+        proc.out += `\n[exited code=${code} signal=${signal}]`;
+        bgTrim(proc);
+    });
+    child.on('error', (err) => {
+        proc.status = 'exited';
+        proc.out += `\n[error: ${err.message}]`;
+    });
+    BG_PROCS.set(id, proc);
+    return id;
+}
+/** Read the accumulated output of a background process (and its status). */
+export function pollBackground(id) {
+    const p = BG_PROCS.get(id);
+    if (!p)
+        return `No background process with id ${id}.`;
+    const head = '[' +
+        id +
+        ' ' +
+        p.status +
+        (p.status === 'exited' ? ' code=' + p.code : '') +
+        '] ' +
+        p.command;
+    const body = p.out.trim() || '(no output yet)';
+    return head + String.fromCharCode(10) + body;
+}
+/** Kill a background process (its whole group on POSIX). */
+export function killBackground(id) {
+    const p = BG_PROCS.get(id);
+    if (!p)
+        return `No background process with id ${id}.`;
+    if (p.status === 'exited')
+        return `Process ${id} already exited (code=${p.code}).`;
+    try {
+        if (process.platform !== 'win32' && p.child.pid) {
+            process.kill(-p.child.pid, 'SIGTERM');
+        }
+        else {
+            p.child.kill('SIGTERM');
+        }
+    }
+    catch (e) {
+        return `Failed to kill ${id}: ${e.message}`;
+    }
+    BG_PROCS.delete(id);
+    return `Killed background process ${id}.`;
+}
+/** List running background processes (for /status and cleanup). */
+export function listBackground() {
+    return [...BG_PROCS.values()]
+        .filter((p) => p.status === 'running')
+        .map((p) => ({ id: p.id, command: p.command }));
+}
+/** Kill every background process — called on exit so no orphan survives. */
+export function killAllBackground() {
+    for (const id of [...BG_PROCS.keys()])
+        killBackground(id);
+}
 // Run an executable directly with an argument ARRAY (no shell). Use this
 // whenever an argument comes from the model: the shell never sees it, so
 // $(...), backticks and quotes cannot be interpreted as commands.