specrails-desktop 2.36.0 → 2.42.2

package/server/dist/transient-children.js

@@ -1,9 +1,10 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BACKGROUND_LOG_RETENTION_MS = void 0;
+exports.BACKGROUND_PERSISTENCE_FLUSH_MS = exports.BACKGROUND_LOG_RETENTION_MS = void 0;
+exports.initializeBackgroundProcessPersistence = initializeBackgroundProcessPersistence;
+exports.flushBackgroundProcessPersistence = flushBackgroundProcessPersistence;
+exports.closeBackgroundProcessPersistence = closeBackgroundProcessPersistence;
+exports.purgeBackgroundProcessHistory = purgeBackgroundProcessHistory;
 exports.trackTransientChild = trackTransientChild;
 exports.killTransientChildren = killTransientChildren;
 exports.startBackgroundProcess = startBackgroundProcess;
@@ -13,62 +14,238 @@ exports.listBackgroundProcesses = listBackgroundProcesses;
 exports.killBackgroundProcess = killBackgroundProcess;
 exports.killOwnedBackgroundProcess = killOwnedBackgroundProcess;
 exports.killBackgroundProcessesForChat = killBackgroundProcessesForChat;
-const tree_kill_1 = __importDefault(require("tree-kill"));
+exports.awaitBackgroundProcessesStopped = awaitBackgroundProcessesStopped;
+const win_spawn_1 = require("./util/win-spawn");
 const child_process_1 = require("child_process");
-const readline_1 = __importDefault(require("readline"));
+const crypto_1 = require("crypto");
+const string_decoder_1 = require("string_decoder");
 const process_admission_1 = require("./process-admission");
-/**
- * Registry of fire-and-forget child processes that are NOT owned by a long-lived
- * manager (QueueManager / ChatManager / SetupManager track their own). The Quick
- * spec-generation spawn in particular keeps only a closure handle + a watchdog,
- * so `ProjectRegistry.removeProject()` / `shutdown()` could not terminate it —
- * it survived project removal (burning AI-CLI spend) until the watchdog fired.
- *
- * Children registered here are tree-killed when their project is removed or the
- * app shuts down. Self-cleaning: each child is auto-unregistered on `close`.
- */
+const background_process_control_1 = require("./background-process-control");
+const win_spawn_2 = require("./util/win-spawn");
+const background_process_store_1 = require("./background-process-store");
+const background_windows_bootstrap_1 = require("./background-windows-bootstrap");
+/** Fire-and-forget children not already owned by a long-lived provider manager. */
 const byProject = new Map();
 const backgroundByPid = new Map();
-const finishedBackgroundByPid = new Map();
-const backgroundTerminal = new Set(['exited', 'killed', 'failed']);
+const finishedBackgroundById = new Map();
+const backgroundTerminal = new Set(['exited', 'killed', 'failed', 'interrupted']);
 const BACKGROUND_KILL_GRACE_MS = 2500;
-const BACKGROUND_OUTPUT_MAX_LINE_CHARS = 1000;
+const BACKGROUND_STOP_CONFIRM_MS = 2500;
+const BACKGROUND_OUTPUT_MAX_LINE_CHARS = 4000;
 const BACKGROUND_OUTPUT_MAX_LINES_PER_SECOND = 20;
-const BACKGROUND_LOG_MAX_LINES = 500;
+const BACKGROUND_LOG_MAX_LINES = 2000;
+const BACKGROUND_FINISHED_MAX = 32;
 exports.BACKGROUND_LOG_RETENTION_MS = 10 * 60 * 1000;
+exports.BACKGROUND_PERSISTENCE_FLUSH_MS = 250;
+const pendingPersistence = new Map();
+let backgroundStore;
+let persistenceAttempted = false;
+let persistenceError;
+let persistenceTimer;
+let lastPersistenceAttempt = 0;
+let persistenceRetryDelay = exports.BACKGROUND_PERSISTENCE_FLUSH_MS;
+let persistenceFile;
+let persistenceClosed = false;
+let lastHistoryOpenAttempt = 0;
+function ensureBackgroundProcessStore() {
+    if (backgroundStore || !persistenceAttempted)
+        return backgroundStore;
+    if (!persistenceClosed && persistenceFile && Date.now() - lastHistoryOpenAttempt >= 1000) {
+        try {
+            initializeBackgroundProcessPersistence(persistenceFile);
+        }
+        catch { /* report the retained open failure below */ }
+    }
+    if (!backgroundStore)
+        throw new Error(`Background process history is unavailable: ${persistenceClosed ? 'the store is closed' : persistenceError ?? 'the store could not be opened'}. Retry after the storage problem is resolved.`);
+    return backgroundStore;
+}
+function schedulePersistenceFlush(delay) {
+    if (persistenceTimer || !pendingPersistence.size || !backgroundStore)
+        return;
+    persistenceTimer = setTimeout(() => {
+        persistenceTimer = undefined;
+        try {
+            flushBackgroundProcessPersistence();
+        }
+        catch { /* failure schedules a bounded retry even for a quiet process */ }
+    }, delay);
+    persistenceTimer.unref?.();
+}
+function initializeBackgroundProcessPersistence(file) {
+    if (backgroundStore) {
+        flushBackgroundProcessPersistence();
+        return;
+    }
+    persistenceFile = file;
+    persistenceClosed = false;
+    lastHistoryOpenAttempt = Date.now();
+    persistenceAttempted = true;
+    try {
+        backgroundStore = new background_process_store_1.BackgroundProcessStore(file);
+        persistenceError = undefined;
+        for (const record of backgroundByPid.values()) {
+            for (const line of record.outputLines)
+                queuePersistence(record, line);
+            queuePersistence(record);
+        }
+        flushBackgroundProcessPersistence();
+    }
+    catch (error) {
+        persistenceError = error instanceof Error ? error.message : String(error);
+        throw error;
+    }
+}
+function queuePersistence(record, line) {
+    if (!backgroundStore || record.skipPersistence)
+        return;
+    let pending = pendingPersistence.get(record.process.processId);
+    if (!pending) {
+        pending = { record, lines: new Map() };
+        pendingPersistence.set(record.process.processId, pending);
+    }
+    if (line)
+        pending.lines.set(line.sequence, cloneLogLine(line));
+    if (pending.lines.size >= BACKGROUND_LOG_MAX_LINES) {
+        if (!persistenceError || Date.now() - lastPersistenceAttempt >= exports.BACKGROUND_PERSISTENCE_FLUSH_MS) {
+            try {
+                flushBackgroundProcessPersistence();
+            }
+            catch { /* failure stays visible and the buffer remains bounded */ }
+        }
+        while (pending.lines.size > BACKGROUND_LOG_MAX_LINES)
+            pending.lines.delete(pending.lines.keys().next().value);
+    }
+    schedulePersistenceFlush(persistenceError ? persistenceRetryDelay : exports.BACKGROUND_PERSISTENCE_FLUSH_MS);
+}
+/** One transaction and one bulk line statement per batch, including upserts
+ * for partial lines. A crash can lose at most the last 250ms of normal output. */
+function flushBackgroundProcessPersistence() {
+    if (persistenceTimer) {
+        clearTimeout(persistenceTimer);
+        persistenceTimer = undefined;
+    }
+    if (!backgroundStore) {
+        if (persistenceError)
+            throw new Error(persistenceError);
+        return;
+    }
+    lastPersistenceAttempt = Date.now();
+    let failure;
+    for (const [processId, pending] of pendingPersistence) {
+        if (pending.record.skipPersistence) {
+            pendingPersistence.delete(processId);
+            continue;
+        }
+        const record = pending.record;
+        try {
+            const { persistenceError: previousError, ...process } = record.process;
+            backgroundStore.write({ process, lines: [...pending.lines.values()], nextSequence: record.nextSequence, clipped: record.clippedOutput });
+            pendingPersistence.delete(processId);
+            delete record.process.persistenceError;
+            const retained = finishedBackgroundById.get(processId);
+            if (retained)
+                delete retained.process.persistenceError;
+            if (previousError)
+                safelyNotify(() => record.hooks.onUpdated?.(cloneProcess(record.process)));
+        }
+        catch (error) {
+            failure = error;
+            const message = `Background history could not be saved: ${error instanceof Error ? error.message : String(error)}`;
+            if (record.process.persistenceError !== message) {
+                record.process.persistenceError = message;
+                const retained = finishedBackgroundById.get(processId);
+                if (retained)
+                    retained.process.persistenceError = message;
+                safelyNotify(() => record.hooks.onUpdated?.(cloneProcess(record.process)));
+            }
+        }
+    }
+    persistenceError = failure ? (failure instanceof Error ? failure.message : String(failure)) : undefined;
+    if (failure) {
+        schedulePersistenceFlush(persistenceRetryDelay);
+        persistenceRetryDelay = Math.min(5000, persistenceRetryDelay * 2);
+        throw failure;
+    }
+    persistenceRetryDelay = exports.BACKGROUND_PERSISTENCE_FLUSH_MS;
+}
+function closeBackgroundProcessPersistence() {
+    persistenceClosed = true;
+    try {
+        flushBackgroundProcessPersistence();
+    }
+    finally {
+        if (persistenceTimer) {
+            clearTimeout(persistenceTimer);
+            persistenceTimer = undefined;
+        }
+        const store = backgroundStore;
+        backgroundStore = undefined;
+        store?.close();
+    }
+}
+function purgeBackgroundProcessHistory(filter) {
+    if (!filter.chatId && !filter.projectId)
+        throw new Error('A conversation or project is required to purge background history.');
+    // Do not discard pending data or acknowledge deletion while its durable
+    // store is inaccessible. A subsequent explicit retry can reopen it.
+    ensureBackgroundProcessStore()?.purge(filter);
+    const matches = (process) => (!filter.chatId || process.chatId === filter.chatId) && (!filter.projectId || process.projectId === filter.projectId);
+    for (const record of backgroundByPid.values())
+        if (matches(record.process)) {
+            record.skipPersistence = true;
+            pendingPersistence.delete(record.process.processId);
+        }
+    for (const [id, record] of finishedBackgroundById)
+        if (matches(record.process)) {
+            clearTimeout(record.cleanupTimer);
+            finishedBackgroundById.delete(id);
+            pendingPersistence.delete(id);
+        }
+}
 function treeKillSafe(pid, signal) {
     try {
-        (0, tree_kill_1.default)(pid, signal, () => undefined);
+        (0, win_spawn_1.treeKillSafe)(pid, signal, () => undefined);
     }
-    catch { /* best-effort */ }
+    catch { /* generic provider owners handle their own terminal state */ }
 }
-function treeKillWithEscalation(pid, isStillAlive = () => backgroundByPid.has(pid)) {
-    treeKillSafe(pid, 'SIGTERM');
-    const timer = setTimeout(() => {
-        if (isStillAlive())
-            treeKillSafe(pid, 'SIGKILL');
-    }, BACKGROUND_KILL_GRACE_MS);
-    timer.unref?.();
-    return timer;
+function isCurrent(record) { return backgroundByPid.get(record.process.pid) === record; }
+function cloneProcess(value) { return { ...value }; }
+function cloneLogLine(value) { return { ...value }; }
+function safelyNotify(callback) {
+    try {
+        callback?.();
+    }
+    catch (error) {
+        console.warn('[background-process] notification failed:', error instanceof Error ? error.message : String(error));
+    }
 }
-function cloneProcess(process) {
-    return { ...process };
+function notifyUpdated(record) {
+    queuePersistence(record);
+    try {
+        flushBackgroundProcessPersistence();
+    }
+    catch { /* process control must continue when history persistence fails */ }
+    safelyNotify(() => record.hooks.onUpdated?.(cloneProcess(record.process)));
 }
-function cloneLogLine(line) {
-    return { ...line };
+function reportError(record, error) {
+    if (!isCurrent(record))
+        return;
+    const message = error instanceof Error ? error.message : String(error);
+    if (record.process.error === message)
+        return;
+    record.process.error = message;
+    notifyUpdated(record);
 }
-/** Track a child under a projectId; auto-removes itself on close. */
+/** Track a provider child under a projectId; its own manager retains lifecycle ownership. */
 function trackTransientChild(projectId, child) {
     try {
         (0, process_admission_1.assertProcessAdmission)(projectId);
     }
-    catch (err) {
-        // A continuation may have spawned immediately before observing the closed
-        // project epoch. Never leave that child unowned simply because registration
-        // lost the teardown race.
+    catch (error) {
         if (child.pid)
             treeKillSafe(child.pid, 'SIGTERM');
-        throw err;
+        throw error;
     }
     let set = byProject.get(projectId);
     if (!set) {
@@ -77,247 +254,459 @@ function trackTransientChild(projectId, child) {
     }
     set.add(child);
     const drop = () => {
-        const s = byProject.get(projectId);
-        if (s) {
-            s.delete(child);
-            if (s.size === 0)
-                byProject.delete(projectId);
-        }
+        const current = byProject.get(projectId);
+        current?.delete(child);
+        if (current?.size === 0)
+            byProject.delete(projectId);
     };
     child.once('close', drop);
     child.once('error', drop);
 }
-/** SIGTERM the whole subtree of every tracked child for a project, then escalate. */
+/** Background apps retain their group owner until exit is confirmed. */
 function killTransientChildren(projectId) {
-    const set = byProject.get(projectId);
-    if (set)
-        for (const child of set) {
-            if (child.pid) {
-                if (backgroundByPid.has(child.pid))
-                    continue;
-                let alive = true;
-                const timer = treeKillWithEscalation(child.pid, () => alive);
-                const clear = () => { alive = false; clearTimeout(timer); };
-                child.once('close', clear);
-                child.once('error', clear);
-            }
+    const children = byProject.get(projectId);
+    if (children)
+        for (const child of children) {
+            if (!child.pid || backgroundByPid.get(child.pid)?.child === child)
+                continue;
+            let alive = true;
+            treeKillSafe(child.pid, 'SIGTERM');
+            const timer = setTimeout(() => { if (alive)
+                treeKillSafe(child.pid, 'SIGKILL'); }, BACKGROUND_KILL_GRACE_MS);
+            timer.unref?.();
+            const clear = () => { alive = false; clearTimeout(timer); };
+            child.once('close', clear);
+            child.once('error', clear);
         }
     byProject.delete(projectId);
-    for (const [pid, record] of [...backgroundByPid]) {
-        if (record.process.projectId !== projectId)
-            continue;
-        markTerminal(record, 'killed', null, 'SIGTERM');
-        terminateBackgroundRecord(record);
+    for (const record of backgroundByPid.values()) {
+        if (record.process.projectId === projectId)
+            terminateBackgroundRecord(record);
     }
 }
-function startBackgroundProcess(command, cwd, chatId, projectId, hooks) {
+function startBackgroundProcess(command, cwd, chatId, projectId, hooks = {}, metadata = {}) {
     (0, process_admission_1.assertProcessAdmission)(projectId);
-    const child = (0, child_process_1.spawn)(command, {
-        cwd,
-        shell: true,
-        detached: true,
-        stdio: ['ignore', 'pipe', 'pipe'],
+    ensureBackgroundProcessStore();
+    if (persistenceError)
+        flushBackgroundProcessPersistence();
+    const startedAt = Date.now();
+    const windowsBootstrap = process.platform === 'win32' ? (0, background_windows_bootstrap_1.spawnWindowsBackgroundBootstrap)(command, cwd) : undefined;
+    const child = windowsBootstrap?.child ?? (0, child_process_1.spawn)(command, {
+        cwd, shell: true, detached: true, stdio: ['ignore', 'pipe', 'pipe'],
+        ...(process.platform === 'win32' ? { env: (0, win_spawn_2.windowsSpawnEnv)(), windowsHide: true } : {}),
     });
     if (!child.pid) {
-        throw new Error('background process failed to start: missing pid');
-    }
-    const process = {
-        pid: child.pid,
-        command,
-        cwd,
-        startedAt: Date.now(),
-        status: 'running',
-        chatId,
-        projectId,
-    };
-    const staleFinished = finishedBackgroundByPid.get(child.pid);
-    if (staleFinished) {
-        clearTimeout(staleFinished.cleanupTimer);
-        finishedBackgroundByPid.delete(child.pid);
+        // spawn emits error asynchronously even when it returns no pid.
+        child.once('error', () => { });
+        child.stdout?.destroy();
+        child.stderr?.destroy();
+        throw new Error('Background process failed to start; check its command and working directory.');
+    }
+    const previous = backgroundByPid.get(child.pid);
+    if (previous) {
+        // Defensive against a reused pid in stale registry state: never let old
+        // timers, child events or UI requests operate on the replacement.
+        finishRecord(previous, 'failed', 'The operating system reused this process ID.');
     }
     const record = {
-        child,
-        process,
-        hooks: hooks ?? {},
-        outputLines: [],
-        droppedOutputLines: 0,
+        child, control: windowsBootstrap?.control ?? (0, background_process_control_1.createBackgroundProcessControl)(child, startedAt), hooks, windowsBootstrap,
+        process: { processId: (0, crypto_1.randomUUID)(), pid: child.pid, command, cwd, startedAt, status: windowsBootstrap ? 'starting' : 'running', chatId, projectId, ...metadata },
+        stoppingAttempt: 0, stopAttemptActive: false, rootClosed: false, rootExited: false, userStopRequested: false, groupGone: false, exitCode: null, exitSignal: null,
+        outputLines: [], outputBySequence: new Map(), nextSequence: 0, droppedOutputLines: 0, clippedOutput: false,
+        flushOutput: [], outputWindowStart: Date.now(), outputEventsInWindow: 0,
     };
     backgroundByPid.set(child.pid, record);
-    trackTransientChild(projectId, child);
-    attachOutput(child, 'stdout', record);
-    attachOutput(child, 'stderr', record);
-    child.once('error', () => {
-        markTerminal(record, process.status === 'killed' ? 'killed' : 'failed', null, null);
-        backgroundByPid.delete(process.pid);
-        retainFinishedRecord(record);
+    attachOutput(child.stdout, 'stdout', record);
+    attachOutput(child.stderr, 'stderr', record);
+    child.once('error', error => { reportError(record, error); void probeRecord(record); });
+    child.once('exit', (code, signal) => {
+        record.rootExited = true;
+        record.exitCode = code;
+        record.exitSignal = signal;
+        void probeRecord(record);
     });
     child.once('close', (code, signal) => {
-        const status = process.status === 'killed' ? 'killed' : code === 0 ? 'exited' : 'failed';
-        markTerminal(record, status, code, signal);
-        backgroundByPid.delete(process.pid);
-        retainFinishedRecord(record);
+        record.rootExited = true;
+        record.rootClosed = true;
+        record.exitCode = code;
+        record.exitSignal = signal;
+        record.flushOutput.forEach(flush => flush());
+        void probeRecord(record);
     });
-    record.hooks.onStarted?.(cloneProcess(process));
-    return cloneProcess(process);
+    queuePersistence(record);
+    try {
+        flushBackgroundProcessPersistence();
+    }
+    catch (error) {
+        terminateBackgroundRecord(record);
+        throw error;
+    }
+    safelyNotify(() => hooks.onStarted?.(cloneProcess(record.process)));
+    if (windowsBootstrap) {
+        void record.control.ready?.then(() => {
+            if (!isCurrent(record) || record.process.status !== 'starting' || record.rootExited) {
+                windowsBootstrap.cancel();
+                return;
+            }
+            windowsBootstrap.start();
+            record.process.status = 'running';
+            queuePersistence(record);
+            safelyNotify(() => hooks.onUpdated?.(cloneProcess(record.process)));
+        }).catch(error => {
+            if (!isCurrent(record))
+                return;
+            reportError(record, error);
+            if (windowsBootstrap.hasLaunched())
+                terminateBackgroundRecord(record, true);
+            else
+                windowsBootstrap.cancel();
+        });
+    }
+    scheduleProbe(record);
+    return cloneProcess(record.process);
+}
+function scheduleProbe(record) {
+    if (!isCurrent(record) || record.probeTimer)
+        return;
+    const delay = record.process.status === 'stopping' && process.platform !== 'win32' ? 100 : 1000;
+    record.probeTimer = setTimeout(() => { record.probeTimer = undefined; void probeRecord(record); }, delay);
+    record.probeTimer.unref?.();
+}
+function probeRecord(record) {
+    if (!isCurrent(record))
+        return Promise.resolve();
+    if (record.probing)
+        return record.probing;
+    const pending = Promise.resolve().then(async () => {
+        try {
+            // Before admission the bootstrap has no descendants. Its own child handle
+            // can confirm exit even if Windows identity discovery failed or was cancelled.
+            if (record.windowsBootstrap && !record.windowsBootstrap.hasLaunched() && record.rootClosed)
+                record.groupGone = true;
+            if (!record.groupGone)
+                record.groupGone = !(await record.control.isAlive());
+            if (!isCurrent(record))
+                return;
+            if (record.groupGone && record.rootClosed) {
+                const containmentFailure = record.control.terminalFailure?.();
+                finishRecord(record, containmentFailure ? 'failed' : record.userStopRequested ? 'killed' : record.exitCode === 0 ? 'exited' : 'failed', containmentFailure);
+            }
+            else if (record.rootExited && !record.groupGone && record.process.status !== 'stopping') {
+                // A wrapper that exits must not leave an unowned app behind. Clean up
+                // its group, retaining the wrapper's original success/failure outcome.
+                terminateBackgroundRecord(record, true);
+            }
+            else if (record.forceKillAt !== undefined && Date.now() - record.forceKillAt >= BACKGROUND_STOP_CONFIRM_MS && !record.groupGone) {
+                record.stopAttemptActive = false;
+                reportError(record, new Error('The process group has not stopped after the force-stop request. Retry stopping it.'));
+            }
+        }
+        catch (error) {
+            record.stopAttemptActive = false;
+            reportError(record, error);
+        }
+    }).finally(() => { if (record.probing === pending)
+        record.probing = undefined; scheduleProbe(record); });
+    record.probing = pending;
+    return pending;
+}
+/** Stop is idempotent while an attempt is progressing. Failed attempts remain
+ * visible and may be retried; terminal state requires both OS and child close. */
+function terminateBackgroundRecord(record, automatic = false) {
+    record.windowsBootstrap?.cancel();
+    if (!automatic)
+        record.userStopRequested = true;
+    if (!isCurrent(record) || record.stopAttemptActive)
+        return;
+    record.stopAttemptActive = true;
+    const attempt = ++record.stoppingAttempt;
+    record.process.status = 'stopping';
+    record.process.stopRequestedAt ??= Date.now();
+    delete record.process.error;
+    record.forceKillAt = undefined;
+    if (record.killTimer)
+        clearTimeout(record.killTimer);
+    notifyUpdated(record);
+    const signal = async (value) => {
+        if (!isCurrent(record) || record.stoppingAttempt !== attempt || record.groupGone)
+            return;
+        try {
+            await record.control.terminate(value);
+        }
+        catch (error) {
+            if (record.stoppingAttempt === attempt) {
+                record.stopAttemptActive = false;
+                reportError(record, error);
+            }
+        }
+        await probeRecord(record);
+    };
+    void signal('SIGTERM');
+    record.killTimer = setTimeout(() => {
+        record.killTimer = undefined;
+        if (!isCurrent(record) || record.stoppingAttempt !== attempt || record.groupGone)
+            return;
+        record.forceKillAt = Date.now();
+        void signal('SIGKILL');
+    }, BACKGROUND_KILL_GRACE_MS);
+    // Keep the escalation armed even after the shell's close event. Shutdown
+    // additionally awaits the drain below before exiting the server process.
+    record.killTimer.unref?.();
 }
-function attachOutput(child, source, record) {
-    const stream = source === 'stdout' ? child.stdout : child.stderr;
-    const rl = readline_1.default.createInterface({ input: stream });
-    let windowStart = Date.now();
-    let emittedInWindow = 0;
-    rl.on('line', (line) => {
-        const clipped = line.length > BACKGROUND_OUTPUT_MAX_LINE_CHARS ? `${line.slice(0, BACKGROUND_OUTPUT_MAX_LINE_CHARS)}...` : line;
-        appendOutputLine(record, source, clipped);
-        if (!record.hooks.onOutput)
+/** Incremental bounded terminal-text capture. StringDecoder keeps split UTF-8
+ * intact; escape state is finite even for unterminated OSC/CSI sequences. */
+function attachOutput(stream, source, record) {
+    if (!stream)
+        return;
+    const decoder = new string_decoder_1.StringDecoder('utf8');
+    let text = '', clipped = false, pendingCR = false, ended = false;
+    let escape = 'plain';
+    let row;
+    const publish = (partial) => {
+        if (!text && !row && partial)
             return;
+        if (!row || !record.outputBySequence.has(row.sequence)) {
+            row = { sequence: ++record.nextSequence, at: Date.now(), source, line: '', partial };
+            record.outputLines.push(row);
+            record.outputBySequence.set(row.sequence, row);
+            if (record.outputLines.length > BACKGROUND_LOG_MAX_LINES) {
+                const removed = record.outputLines.shift();
+                record.outputBySequence.delete(removed.sequence);
+                record.droppedOutputLines += 1;
+            }
+        }
+        row.line = clipped ? `${text.slice(0, BACKGROUND_OUTPUT_MAX_LINE_CHARS - 1).replace(/[\uD800-\uDBFF]$/, '')}…` : text;
+        row.partial = partial;
+        if (clipped)
+            record.clippedOutput = true;
+        queuePersistence(record, row);
         const now = Date.now();
-        if (now - windowStart >= 1000) {
-            windowStart = now;
-            emittedInWindow = 0;
+        if (now - record.outputWindowStart >= 1000) {
+            record.outputWindowStart = now;
+            record.outputEventsInWindow = 0;
+        }
+        // Live notifications are hints; sequence gaps are recoverable from the
+        // bounded authoritative snapshot. Never drop lines from that snapshot.
+        if (record.outputEventsInWindow < BACKGROUND_OUTPUT_MAX_LINES_PER_SECOND) {
+            record.outputEventsInWindow += 1;
+            safelyNotify(() => record.hooks.onOutput?.({ ...cloneLogLine(row), processId: record.process.processId, pid: record.process.pid, chatId: record.process.chatId, projectId: record.process.projectId }));
+        }
+    };
+    const consume = (chunk) => {
+        for (const character of chunk) {
+            if (escape === 'escape') {
+                escape = character === '[' ? 'csi' : [']', 'P', '^', '_'].includes(character) ? 'osc' : 'plain';
+                continue;
+            }
+            if (escape === 'csi') {
+                if (character >= '@' && character <= '~')
+                    escape = 'plain';
+                continue;
+            }
+            if (escape === 'osc') {
+                if (character === '\u0007')
+                    escape = 'plain';
+                else if (character === '\u001b')
+                    escape = 'oscEscape';
+                continue;
+            }
+            if (escape === 'oscEscape') {
+                escape = character === '\\' ? 'plain' : 'osc';
+                continue;
+            }
+            if (character === '\u001b') {
+                escape = 'escape';
+                continue;
+            }
+            if (character === '\u009b') {
+                escape = 'csi';
+                continue;
+            }
+            if (pendingCR) {
+                pendingCR = false;
+                if (character !== '\n') {
+                    text = '';
+                    clipped = false;
+                }
+            }
+            if (character === '\r') {
+                pendingCR = true;
+                continue;
+            }
+            if (character === '\n') {
+                publish(false);
+                text = '';
+                clipped = false;
+                row = undefined;
+                continue;
+            }
+            if (character === '\b') {
+                text = Array.from(text).slice(0, -1).join('');
+                continue;
+            }
+            if ((character < ' ' && character !== '\t') || character === '\u007f' || (character >= '\u0080' && character <= '\u009f'))
+                continue;
+            if (text.length + character.length <= BACKGROUND_OUTPUT_MAX_LINE_CHARS)
+                text += character;
+            else
+                clipped = true;
         }
-        if (emittedInWindow >= BACKGROUND_OUTPUT_MAX_LINES_PER_SECOND)
+        publish(true);
+    };
+    stream.on('data', (chunk) => { if (!ended)
+        consume(typeof chunk === 'string' ? chunk : decoder.write(chunk)); });
+    const finish = () => {
+        if (ended)
             return;
-        emittedInWindow += 1;
-        record.hooks.onOutput?.({
-            pid: record.process.pid,
-            chatId: record.process.chatId,
-            projectId: record.process.projectId,
-            source,
-            line: clipped,
-        });
-    });
+        consume(decoder.end());
+        ended = true;
+        if (row || text)
+            publish(false);
+    };
+    stream.once('end', finish);
+    stream.once('close', finish);
+    stream.once('error', error => { reportError(record, error); finish(); });
+    record.flushOutput.push(finish);
 }
-function appendOutputLine(record, source, line) {
-    record.outputLines.push({ at: Date.now(), source, line });
-    if (record.outputLines.length > BACKGROUND_LOG_MAX_LINES) {
-        const overflow = record.outputLines.length - BACKGROUND_LOG_MAX_LINES;
-        record.outputLines.splice(0, overflow);
-        record.droppedOutputLines += overflow;
+function finishRecord(record, status, error) {
+    if (!isCurrent(record))
+        return;
+    if (record.killTimer)
+        clearTimeout(record.killTimer);
+    if (record.probeTimer)
+        clearTimeout(record.probeTimer);
+    record.process.status = status;
+    record.process.endedAt = Date.now();
+    record.process.exitCode = record.exitCode;
+    record.process.signal = record.exitSignal;
+    if (error)
+        record.process.error = error;
+    record.flushOutput.forEach(flush => flush());
+    queuePersistence(record);
+    try {
+        flushBackgroundProcessPersistence();
     }
-}
-function retainFinishedRecord(record) {
-    if (record.retained) {
-        const existing = finishedBackgroundByPid.get(record.process.pid);
-        if (existing) {
-            existing.process = cloneProcess(record.process);
-            existing.outputLines = record.outputLines.map(cloneLogLine);
-            existing.droppedOutputLines = record.droppedOutputLines;
-        }
+    catch { /* retain the pending batch and visible persistenceError for a later retry */ }
+    backgroundByPid.delete(record.process.pid);
+    if (record.skipPersistence) {
+        safelyNotify(() => record.hooks.onExited?.(cloneProcess(record.process)));
         return;
     }
-    record.retained = true;
-    const previous = finishedBackgroundByPid.get(record.process.pid);
-    if (previous)
-        clearTimeout(previous.cleanupTimer);
-    const cleanupTimer = setTimeout(() => {
-        finishedBackgroundByPid.delete(record.process.pid);
-    }, exports.BACKGROUND_LOG_RETENTION_MS);
+    const processId = record.process.processId;
+    const cleanupTimer = setTimeout(() => { finishedBackgroundById.delete(processId); }, exports.BACKGROUND_LOG_RETENTION_MS);
     cleanupTimer.unref?.();
-    finishedBackgroundByPid.set(record.process.pid, {
-        process: cloneProcess(record.process),
-        outputLines: record.outputLines.map(cloneLogLine),
-        droppedOutputLines: record.droppedOutputLines,
-        cleanupTimer,
+    finishedBackgroundById.set(processId, {
+        process: cloneProcess(record.process), outputLines: record.outputLines.map(cloneLogLine),
+        nextSequence: record.nextSequence, droppedOutputLines: record.droppedOutputLines, clippedOutput: record.clippedOutput, cleanupTimer,
     });
+    while (finishedBackgroundById.size > BACKGROUND_FINISHED_MAX) {
+        const oldest = finishedBackgroundById.entries().next().value;
+        clearTimeout(oldest[1].cleanupTimer);
+        finishedBackgroundById.delete(oldest[0]);
+    }
+    safelyNotify(() => record.hooks.onExited?.(cloneProcess(record.process)));
 }
-function markTerminal(record, status, exitCode, signal) {
-    if (record.killTimer)
-        clearTimeout(record.killTimer);
-    record.process.status = status;
-    record.process.exitCode = exitCode;
-    record.process.signal = signal;
-    if (record.terminalNotified)
-        return;
-    record.terminalNotified = true;
-    record.hooks.onExited?.(cloneProcess(record.process));
+function findRecord(pid, processId) {
+    const live = backgroundByPid.get(pid);
+    if (live && (!processId || live.process.processId === processId))
+        return live;
+    if (processId) {
+        const finished = finishedBackgroundById.get(processId);
+        return finished?.process.pid === pid ? finished : undefined;
+    }
+    return [...finishedBackgroundById.values()].reverse().find(record => record.process.pid === pid);
 }
-function getBackgroundProcess(pid) {
-    const record = backgroundByPid.get(pid);
-    if (record)
-        return cloneProcess(record.process);
-    const finished = finishedBackgroundByPid.get(pid);
-    return finished ? cloneProcess(finished.process) : null;
+function getBackgroundProcess(pid, processId) {
+    const record = findRecord(pid, processId);
+    return record ? cloneProcess(record.process) : ensureBackgroundProcessStore()?.get(pid, processId) ?? null;
 }
 function getBackgroundProcessLogs(pid, filter = {}) {
-    const live = backgroundByPid.get(pid);
-    const record = live
-        ? {
-            process: live.process,
-            outputLines: live.outputLines,
-            droppedOutputLines: live.droppedOutputLines,
-        }
-        : finishedBackgroundByPid.get(pid);
+    const record = findRecord(pid, filter.processId);
     if (!record)
+        return ensureBackgroundProcessStore()?.logs(pid, filter) ?? null;
+    if ((filter.projectId && record.process.projectId !== filter.projectId) || (filter.chatId && record.process.chatId !== filter.chatId))
         return null;
-    if (filter.projectId && record.process.projectId !== filter.projectId)
-        return null;
-    if (filter.chatId && record.process.chatId !== filter.chatId)
-        return null;
-    const limit = typeof filter.limit === 'number' && Number.isFinite(filter.limit)
-        ? Math.max(1, Math.min(BACKGROUND_LOG_MAX_LINES, Math.floor(filter.limit)))
-        : BACKGROUND_LOG_MAX_LINES;
-    const start = Math.max(0, record.outputLines.length - limit);
-    const lines = record.outputLines.slice(start).map(cloneLogLine);
-    const droppedByLimit = record.outputLines.length - lines.length;
-    const droppedLines = record.droppedOutputLines + droppedByLimit;
+    const maxLines = backgroundStore ? background_process_store_1.BACKGROUND_HISTORY_MAX_LINES : BACKGROUND_LOG_MAX_LINES;
+    const limit = typeof filter.limit === 'number' && Number.isFinite(filter.limit) ? Math.max(1, Math.min(maxLines, Math.floor(filter.limit))) : BACKGROUND_LOG_MAX_LINES;
+    let durable = null;
+    try {
+        durable = ensureBackgroundProcessStore()?.logs(pid, { ...filter, processId: record.process.processId, limit }) ?? null;
+    }
+    catch (error) {
+        record.process.persistenceError = `Background history could not be read: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    const combined = new Map((durable?.lines ?? []).map(line => [line.sequence, line]));
+    for (const line of record.outputLines)
+        combined.set(line.sequence, line);
+    for (const line of pendingPersistence.get(record.process.processId)?.lines.values() ?? [])
+        combined.set(line.sequence, line);
+    const lines = [...combined.values()].sort((a, b) => a.sequence - b.sequence).slice(-limit).map(cloneLogLine);
+    const nextSequence = Math.max(record.nextSequence, durable?.nextSequence ?? 0);
+    const droppedLines = Math.max(0, nextSequence - lines.length);
     return {
-        process: cloneProcess(record.process),
-        lines,
-        truncated: droppedLines > 0,
-        droppedLines,
-        maxLines: BACKGROUND_LOG_MAX_LINES,
-        maxLineChars: BACKGROUND_OUTPUT_MAX_LINE_CHARS,
-        retentionMs: exports.BACKGROUND_LOG_RETENTION_MS,
+        process: cloneProcess(record.process), lines, nextSequence,
+        truncated: droppedLines > 0 || record.clippedOutput || (durable?.truncated ?? false), droppedLines,
+        maxLines, maxLineChars: BACKGROUND_OUTPUT_MAX_LINE_CHARS, retentionMs: backgroundStore ? background_process_store_1.BACKGROUND_HISTORY_RETENTION_MS : exports.BACKGROUND_LOG_RETENTION_MS,
     };
 }
 function listBackgroundProcesses(filter = {}) {
-    const processes = [];
-    for (const record of backgroundByPid.values()) {
-        const process = record.process;
-        if (filter.projectId && process.projectId !== filter.projectId)
-            continue;
-        if (filter.chatId && process.chatId !== filter.chatId)
-            continue;
-        if (backgroundTerminal.has(process.status))
-            continue;
-        processes.push(cloneProcess(process));
-    }
-    return processes;
+    const records = [...backgroundByPid.values(), ...(filter.includeFinished ? finishedBackgroundById.values() : [])];
+    const combined = new Map((ensureBackgroundProcessStore()?.list(filter) ?? []).map(process => [process.processId, process]));
+    for (const record of records)
+        if ((!filter.projectId || record.process.projectId === filter.projectId) && (!filter.chatId || record.process.chatId === filter.chatId))
+            combined.set(record.process.processId, cloneProcess(record.process));
+    return [...combined.values()].sort((a, b) => a.startedAt - b.startedAt);
 }
-function killBackgroundProcess(pid) {
+function killBackgroundProcess(pid, processId) {
     const record = backgroundByPid.get(pid);
-    if (!record)
-        return;
-    record.process.status = 'killed';
-    terminateBackgroundRecord(record);
+    if (record && (!processId || processId === record.process.processId))
+        terminateBackgroundRecord(record);
 }
 function killOwnedBackgroundProcess(pid, owner) {
-    const record = backgroundByPid.get(pid);
+    const record = findRecord(pid, owner.processId);
     if (!record)
+        return false; // historical rows never regain operating-system control
+    if (!record || record.process.projectId !== owner.projectId || record.process.chatId !== owner.chatId)
         return false;
-    if (record.process.projectId !== owner.projectId)
-        return false;
-    if (record.process.chatId !== owner.chatId)
-        return false;
-    killBackgroundProcess(pid);
+    if (!backgroundTerminal.has(record.process.status))
+        killBackgroundProcess(pid, record.process.processId);
     return true;
 }
-function terminateBackgroundRecord(record) {
-    if (record.killTimer)
-        clearTimeout(record.killTimer);
-    record.killTimer = treeKillWithEscalation(record.process.pid);
-}
 function killBackgroundProcessesForChat(chatId, projectId) {
-    let killed = 0;
+    let count = 0;
     for (const record of backgroundByPid.values()) {
-        if (record.process.chatId !== chatId)
-            continue;
-        if (projectId && record.process.projectId !== projectId)
+        if (record.process.chatId !== chatId || (projectId && record.process.projectId !== projectId))
             continue;
-        record.process.status = 'killed';
-        markTerminal(record, 'killed', null, 'SIGTERM');
         terminateBackgroundRecord(record);
-        killed += 1;
+        count += 1;
+    }
+    return count;
+}
+/** Shutdown requests stop for all owned apps and keeps the event loop alive
+ * through escalation. Returns unresolved processes rather than claiming exit. */
+async function awaitBackgroundProcessesStopped(timeoutMs = 6000) {
+    for (const record of backgroundByPid.values())
+        terminateBackgroundRecord(record);
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    while (backgroundByPid.size > 0 && Date.now() < deadline) {
+        let deadlineTimer;
+        try {
+            await Promise.race([
+                Promise.all([...backgroundByPid.values()].map(probeRecord)),
+                new Promise(resolve => { deadlineTimer = setTimeout(resolve, Math.max(0, deadline - Date.now())); }),
+            ]);
+        }
+        finally {
+            if (deadlineTimer)
+                clearTimeout(deadlineTimer);
+        }
+        if (backgroundByPid.size === 0 || Date.now() >= deadline)
+            break;
+        await new Promise(resolve => setTimeout(resolve, Math.min(50, Math.max(0, deadline - Date.now()))));
+    }
+    try {
+        flushBackgroundProcessPersistence();
     }
-    return killed;
+    catch { /* storage failure must not prevent control/shutdown; close reports it to the app */ }
+    return [...backgroundByPid.values()].map(record => cloneProcess(record.process));
 }