@asrunjs/asrun 0.9.0 → 0.11.0

package/dist/ui/server/jobs.js

@@ -1,33 +1,40 @@
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
-import path from 'node:path';
 import { StringDecoder } from 'node:string_decoder';
 import { ROOT } from '../../lib/paths.js';
 import { spawnTarget } from '../../lib/command.js';
 import { AiStreamFormatter } from './ai-stream.js';
-const LOG_DIR = path.join(ROOT, '.tmp', 'ui-jobs');
+import { parseResultState } from './result-state.js';
+import { appendChunkNow, chunksFile, ensureJobDir, logFile, pruneJobs, readChunks, readJobs, writeRecord, } from './job-store.js';
+import { killProcessTree, probeProcesses } from './process-info.js';
 const MAX_BUFFERED_CHARS = 4_000_000;
-const MAX_FINISHED_JOBS = 30;
+const MAX_FINISHED_JOBS = 50;
 const LOG_RETENTION_MS = 7 * 24 * 3600 * 1000;
 const KILL_GRACE_MS = 5000;
 // An agent that has said nothing for this long gets a "still waiting for <tool call>" line in its log.
 const QUIET_MS = 45_000;
 const HEARTBEAT_MS = 15_000;
+// A leftover process is looked at again this often, so a new AI run stops being blocked once it exits by itself.
+const LEFTOVER_PROBE_MS = 5_000;
+// An AI run that has said nothing at all for this long is given up on: a tool call that never returns (the biggest
+// case: the `playwright-test` MCP server stopped answering) would otherwise leave the job running for ever. A handoff
+// card waiting for a person gets `HANDOFF_GRACE_MS` on top, because that wait is the point of an attended run.
+const STALL_MS = 10 * 60_000;
+const HANDOFF_GRACE_MS = 5 * 60_000;
+const STALL_MESSAGE = 'The agent stopped answering, so this run was stopped. The browser MCP server (`playwright-test`) most likely ' +
+    'stopped responding: one interrupted browser call leaves it wedged for every later run in this workspace. Restart ' +
+    'OpenCode (that ends its MCP processes) and start the run again; `pnpm asrun doctor` cannot see this, because it ' +
+    'starts a fresh server of its own.';
 export class JobConflictError extends Error {
 }
-const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
-/** The last `RESULT: ready|needs-input` line the agent said (markdown emphasis around it is fine). */
-function parseResultState(record) {
-    const text = record.chunks
-        // Only what the agent said counts: a file it read or a page it dumped may quote the same words.
+/** What the agent itself said, as one text: a file it read or a page it dumped may quote the same words. */
+function resultText(record) {
+    return record.chunks
         .filter((chunk) => (chunk.kind ? chunk.kind === 'markdown' : chunk.stream !== 'system'))
         .map((chunk) => chunk.data)
-        .join('\n')
-        .replace(ANSI, '');
-    const matches = [...text.matchAll(/^[\s*`>_-]*RESULT:\s*(ready|needs-input)\b/gm)];
-    return matches.at(-1)?.[1] ?? null;
+        .join('\n');
 }
 /**
  * A block of an AI run as the log file keeps it: the same text the UI shows, with the timestamp the UI styles written
@@ -48,31 +55,75 @@ function logFileText(part) {
     }
     return `${stamp}${part.data}\n`;
 }
+/**
+ * Whether a process the system reports for a job's pid is really that job. The command line has to hold one of the
+ * arguments the job was started with (the script, the case, the profile), and the process must have started around the
+ * job: a pid that was reused by an unrelated program fails both.
+ */
+function matchesJob(details, spec, startedAt) {
+    if (details.commandLine === '')
+        return false;
+    const line = details.commandLine.toLowerCase();
+    const tokens = spec.args.filter((value) => value.length >= 4).map((value) => value.toLowerCase());
+    const spawned = spec.spawnedPath;
+    if (spawned && spawned !== process.execPath && /[\\/]/.test(spawned))
+        tokens.push(spawned.toLowerCase());
+    if (!tokens.some((token) => line.includes(token)))
+        return false;
+    if (details.startedAt !== null) {
+        const started = Date.parse(startedAt);
+        if (Number.isFinite(started) && (details.startedAt < started - 60_000 || details.startedAt > started + 180_000)) {
+            return false;
+        }
+    }
+    return true;
+}
 class JobManager {
     jobs = new Map();
+    leftoverTimer = null;
     /** Emits `job` with a JobInfo on every status change of any job. */
     events = new EventEmitter();
     constructor() {
         this.events.setMaxListeners(0);
-        this.pruneOldLogs();
+        this.recover();
     }
     list() {
         return [...this.jobs.values()].map((record) => record.info).reverse();
     }
     get(id) {
-        return this.jobs.get(id);
+        const record = this.jobs.get(id);
+        if (record)
+            this.ensureChunks(record);
+        return record;
+    }
+    /** The request "Run again" starts, or undefined when this job was not started from one. */
+    rerunRequest(id) {
+        return this.jobs.get(id)?.spec.rerun;
+    }
+    /**
+     * True while this job still holds its locks. A job a restart left behind holds them only while its process is
+     * confirmed to be alive: starting another agent next to it would wedge the one MCP server for both.
+     */
+    holdsLock(info) {
+        if (info.status === 'running')
+            return true;
+        return info.status === 'interrupted' && info.leftover?.state === 'alive';
     }
     start(spec) {
         for (const record of this.jobs.values()) {
-            if (record.info.status !== 'running')
+            if (!this.holdsLock(record.info))
                 continue;
             const clash = record.spec.locks.find((lock) => spec.locks.includes(lock));
-            if (clash) {
+            if (!clash)
+                continue;
+            if (record.info.status === 'running') {
                 throw new JobConflictError(`Cannot start: "${record.info.command}" is already running (${clash}). Wait for it to finish or cancel it.`);
             }
+            throw new JobConflictError(`Cannot start: "${record.info.command}" was interrupted by a UI server restart and its process is still ` +
+                `running (${clash}). Stop the leftover process in the Jobs drawer first.`);
         }
         const id = crypto.randomBytes(6).toString('hex');
-        fs.mkdirSync(LOG_DIR, { recursive: true });
+        ensureJobDir(id);
         const record = {
             info: {
                 id,
@@ -96,6 +147,7 @@ class JobManager {
                     resultState: null,
                 }),
                 ...(spec.continuesJobId && { continuesJobId: spec.continuesJobId }),
+                ...(spec.rerun && { rerunable: true }),
             },
             spec,
             chunks: [],
@@ -103,20 +155,29 @@ class JobManager {
             nextSeq: 0,
             emitter: new EventEmitter(),
             child: null,
+            pid: null,
             cancelRequested: false,
-            logStream: fs.createWriteStream(path.join(LOG_DIR, `${id}.log`)),
+            stalled: false,
+            lastActivityAt: Date.now(),
+            logStream: fs.createWriteStream(logFile(id)),
+            chunkStream: fs.createWriteStream(chunksFile(id)),
+            chunksLoaded: true,
             formatter: spec.stream ? new AiStreamFormatter(spec.stream) : null,
             heartbeat: null,
         };
         record.emitter.setMaxListeners(0);
         this.jobs.set(id, record);
         this.push(record, 'system', `$ ${spec.command}\n`);
+        // Written before the process starts, so a crash during the start still leaves a record to find.
+        this.persist(record);
         // A CLI installed globally is a `.cmd` shim on Windows, which spawn cannot start on its own (see lib/command.ts).
         const target = spawnTarget(spec.file, spec.args);
         if (target === null) {
             this.finish(record, null, null, `Failed to start: "${spec.file}" was not found on PATH. Install it, or choose the other tool.`);
             return record.info;
         }
+        record.spec.spawnedPath = target.path;
+        this.persist(record);
         let child;
         try {
             child = spawn(target.file, target.args, {
@@ -135,6 +196,8 @@ class JobManager {
             return record.info;
         }
         record.child = child;
+        record.pid = child.pid ?? null;
+        this.persist(record);
         for (const stream of ['stdout', 'stderr']) {
             const decoder = new StringDecoder('utf8');
             const formatted = stream === 'stdout' ? record.formatter : null;
@@ -163,6 +226,7 @@ class JobManager {
                 const line = formatter.waiting(QUIET_MS);
                 if (line)
                     this.pushPart(record, line);
+                this.watchStall(record);
             }, HEARTBEAT_MS);
             record.heartbeat.unref();
         }
@@ -191,24 +255,215 @@ class JobManager {
     }
     cancel(id) {
         const record = this.jobs.get(id);
-        const pid = record?.child?.pid;
-        if (!record || record.info.status !== 'running' || !pid)
+        if (!record)
+            return false;
+        // A job the previous server left behind: only its own process is ended, and only once it is recognized.
+        const leftover = record.info.leftover;
+        if (record.info.status === 'interrupted' && leftover?.state === 'alive') {
+            const probe = probeProcesses([leftover.pid]).get(leftover.pid) ?? null;
+            if (probe === null) {
+                record.info.leftover = { ...leftover, state: 'gone' };
+                this.persist(record);
+                this.events.emit('job', record.info);
+                return false;
+            }
+            if (!matchesJob(probe, record.spec, record.info.startedAt)) {
+                record.info.leftover = { ...leftover, state: 'unknown' };
+                this.persist(record);
+                this.events.emit('job', record.info);
+                return false;
+            }
+            killProcessTree(leftover.pid, 'SIGTERM');
+            const leftoverPid = leftover.pid;
+            record.info.leftover = { ...leftover, state: 'stopped' };
+            this.pushRecovered(record, '\n[stopped: the leftover process tree of an interrupted job was ended]\n');
+            this.persist(record);
+            this.events.emit('job', record.info);
+            // A signal is not proof: if it did not work, the entry goes back to "alive" so the person can try again.
+            setTimeout(() => this.verifyLeftoverStopped(record, leftoverPid), KILL_GRACE_MS).unref();
+            return true;
+        }
+        const pid = record.child?.pid ?? record.pid;
+        if (record.info.status !== 'running' || !pid)
             return false;
         record.cancelRequested = true;
-        this.signalGroup(pid, 'SIGTERM');
+        killProcessTree(pid, 'SIGTERM');
         setTimeout(() => {
             if (record.info.status === 'running')
-                this.signalGroup(pid, 'SIGKILL');
+                killProcessTree(pid, 'SIGKILL');
         }, KILL_GRACE_MS).unref();
         return true;
     }
     /** Stops everything; called when the server shuts down. */
     killAll() {
         for (const record of this.jobs.values()) {
-            const pid = record.child?.pid;
+            const pid = record.child?.pid ?? record.pid;
             if (record.info.status === 'running' && pid)
-                this.signalGroup(pid, 'SIGTERM');
+                killProcessTree(pid, 'SIGTERM');
+        }
+    }
+    /**
+     * Reads the jobs of earlier server runs. One that was still running is marked `interrupted`: its output stops where
+     * the server died, and its process is either gone or a leftover the person can stop. An AI run that had already
+     * written its `RESULT:` line is recovered as succeeded, so its answers can still be answered.
+     */
+    recover() {
+        pruneJobs(MAX_FINISHED_JOBS, LOG_RETENTION_MS);
+        const stored = readJobs();
+        const interrupted = stored.filter((job) => job.info.status === 'running');
+        const pids = interrupted.map((job) => job.pid).filter((pid) => typeof pid === 'number');
+        const probe = probeProcesses(pids);
+        const now = new Date().toISOString();
+        for (const record of stored) {
+            const job = {
+                info: record.info,
+                spec: { ...record.spec },
+                chunks: [],
+                bufferedChars: 0,
+                nextSeq: 0,
+                emitter: new EventEmitter(),
+                child: null,
+                pid: record.pid ?? null,
+                cancelRequested: false,
+                stalled: false,
+                lastActivityAt: Date.now(),
+                logStream: null,
+                chunkStream: null,
+                chunksLoaded: false,
+                formatter: null,
+                heartbeat: null,
+            };
+            job.emitter.setMaxListeners(0);
+            if (record.info.status === 'running') {
+                // Its result line lives in the chunks, and the note about the restart is appended below.
+                this.ensureChunks(job);
+                this.recoverInterrupted(job, probe, now);
+            }
+            this.jobs.set(job.info.id, job);
+        }
+        // A record from an earlier restart may still say its process is alive; look once before the server answers.
+        this.checkLeftovers();
+        if ([...this.jobs.values()].some((job) => job.info.leftover?.state === 'alive')) {
+            this.startLeftoverProbe();
+        }
+    }
+    /** Reads a finished job's chunks the first time someone opens it; a job this server runs already has them. */
+    ensureChunks(record) {
+        if (record.chunksLoaded)
+            return;
+        const loaded = readChunks(record.info.id, MAX_BUFFERED_CHARS);
+        record.chunks = loaded.chunks;
+        record.bufferedChars = loaded.bufferedChars;
+        record.nextSeq = loaded.nextSeq;
+        record.chunksLoaded = true;
+    }
+    recoverInterrupted(record, probe, now) {
+        const info = record.info;
+        info.awaitingUser = null;
+        info.interruptedAt = now;
+        info.endedAt = now;
+        const pid = record.pid;
+        const found = pid === null ? null : (probe.get(pid) ?? null);
+        if (pid === null) {
+            info.status = 'interrupted';
+            info.leftover = undefined;
+            this.pushRecovered(record, '\n[interrupted: the UI server stopped while this job was running. Its process is unknown]\n');
+        }
+        else if (found === null) {
+            info.leftover = { pid, state: 'gone' };
+            const state = record.spec.ai ? parseResultState(resultText(record)) : null;
+            if (state !== null) {
+                // The agent had already finished its turn; the server only died before it could record the outcome.
+                info.status = 'succeeded';
+                info.resultState = state;
+                info.exitCode = null;
+                info.signal = null;
+                this.pushRecovered(record, `\n[the UI server stopped while this job was running, but the agent had already written ` +
+                    `RESULT: ${state}. The exit code is unknown]\n`);
+            }
+            else {
+                info.status = 'interrupted';
+                info.resultState = null;
+                this.pushRecovered(record, '\n[interrupted: the UI server stopped while this job was running. Its process is gone]\n');
+            }
+        }
+        else if (matchesJob(found, record.spec, info.startedAt)) {
+            info.status = 'interrupted';
+            info.resultState = null;
+            info.leftover = { pid, state: 'alive' };
+            this.pushRecovered(record, `\n[interrupted: the UI server stopped while this job was running. Its process (pid ${pid}) is still ` +
+                'running; stop it before starting another AI run]\n');
+        }
+        else {
+            info.status = 'interrupted';
+            info.resultState = null;
+            info.leftover = { pid, state: 'unknown' };
+            this.pushRecovered(record, `\n[interrupted: the UI server stopped while this job was running. A process with its pid (${pid}) is ` +
+                'running, but it could not be identified as this job, so it was not marked for stopping]\n');
+        }
+        this.persist(record);
+    }
+    /** Keeps the leftover state current, so a process that exits by itself stops blocking new jobs. */
+    startLeftoverProbe() {
+        if (this.leftoverTimer)
+            return;
+        this.leftoverTimer = setInterval(() => this.checkLeftovers(), LEFTOVER_PROBE_MS);
+        this.leftoverTimer.unref();
+    }
+    checkLeftovers() {
+        const records = [...this.jobs.values()].filter((record) => record.info.status === 'interrupted' && record.info.leftover?.state === 'alive');
+        if (records.length === 0) {
+            if (this.leftoverTimer)
+                clearInterval(this.leftoverTimer);
+            this.leftoverTimer = null;
+            return;
         }
+        const probe = probeProcesses(records.map((record) => record.info.leftover.pid));
+        for (const record of records) {
+            const leftover = record.info.leftover;
+            const found = probe.get(leftover.pid) ?? null;
+            const state = found === null ? 'gone' : matchesJob(found, record.spec, record.info.startedAt) ? 'alive' : 'unknown';
+            if (state === leftover.state)
+                continue;
+            record.info.leftover = { ...leftover, state };
+            // A process that had already written its result and then exited is a finished turn, not an interruption.
+            if (state === 'gone' && record.spec.ai && record.info.resultState === null) {
+                this.ensureChunks(record);
+                const result = parseResultState(resultText(record));
+                if (result !== null) {
+                    record.info.status = 'succeeded';
+                    record.info.resultState = result;
+                    this.pushRecovered(record, `\n[the agent had already written RESULT: ${result}, but the UI server did not record the end of the ` +
+                        'run; the exit code is unknown]\n');
+                }
+            }
+            this.persist(record);
+            this.events.emit('job', record.info);
+        }
+    }
+    /** After a stop was requested, make sure the process is really gone; a signal that was ignored is not a stop. */
+    verifyLeftoverStopped(record, pid) {
+        const found = probeProcesses([pid]).get(pid) ?? null;
+        if (found === null)
+            return;
+        if (!matchesJob(found, record.spec, record.info.startedAt)) {
+            record.info.leftover = { ...(record.info.leftover ?? { pid }), state: 'unknown' };
+            this.persist(record);
+            this.events.emit('job', record.info);
+            return;
+        }
+        killProcessTree(pid, 'SIGKILL');
+        setTimeout(() => {
+            const still = probeProcesses([pid]).get(pid) ?? null;
+            if (still === null)
+                return;
+            const state = matchesJob(still, record.spec, record.info.startedAt) ? 'alive' : 'unknown';
+            record.info.leftover = { ...(record.info.leftover ?? { pid }), state };
+            this.persist(record);
+            this.events.emit('job', record.info);
+            if (state === 'alive')
+                this.startLeftoverProbe();
+        }, 1_000).unref();
     }
     /** Publishes a change of "waiting for the person" (a handoff card) like any other status change. */
     syncAwaiting(record) {
@@ -222,21 +477,26 @@ class JobManager {
         if (now && before && before.since === new Date(now.since).toISOString())
             return;
         info.awaitingUser = now ? { message: now.message, since: new Date(now.since).toISOString() } : null;
+        this.persist(record);
         this.events.emit('job', info);
     }
-    signalGroup(pid, signal) {
-        if (process.platform === 'win32') {
-            // Windows has no process groups (a negative pid throws ESRCH), so the whole tree is ended at once:
-            // cmd.exe, the agent CLI it started, and anything below them.
-            spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+    /**
+     * Stops a run whose agent has said nothing for `STALL_MS`: a tool call that never returns leaves the CLI waiting for
+     * ever, and the log would only keep repeating "still waiting for ...". The block above the cancel names what to do.
+     */
+    watchStall(record) {
+        if (record.info.status !== 'running' || record.stalled || record.cancelRequested)
             return;
-        }
-        try {
-            process.kill(-pid, signal);
-        }
-        catch {
-            // Already gone.
-        }
+        // A handoff card is a wait with a person at the other end, not a hang: the silence is counted from the card's
+        // start and gets `HANDOFF_GRACE_MS` on top, so a person has time to act but a card that never returns is caught.
+        const awaitingSince = record.formatter?.awaiting?.since ?? 0;
+        const since = Math.max(record.lastActivityAt, awaitingSince);
+        const limit = awaitingSince ? STALL_MS + HANDOFF_GRACE_MS : STALL_MS;
+        if (Date.now() - since < limit)
+            return;
+        record.stalled = true;
+        this.pushPart(record, { kind: 'error', at: Date.now(), data: `\n${STALL_MESSAGE}\n` });
+        this.cancel(record.info.id);
     }
     /** A block of an AI run's log, with the time it was produced and how the UI should present it. */
     pushPart(record, part) {
@@ -258,13 +518,49 @@ class JobManager {
     /** Keeps the chunk for the browser and writes it to the job's log file, which is what is left after the run. */
     store(record, chunk, fileText) {
         record.chunks.push(chunk);
+        // A heartbeat line reports how long the silence is, so it must not count as activity of its own.
+        if (chunk.kind !== 'meta')
+            record.lastActivityAt = Date.now();
         record.bufferedChars += chunk.data.length;
         while (record.bufferedChars > MAX_BUFFERED_CHARS && record.chunks.length > 1) {
             record.bufferedChars -= record.chunks.shift().data.length;
         }
-        record.logStream.write(fileText);
+        record.logStream?.write(fileText);
+        record.chunkStream?.write(`${JSON.stringify(chunk)}\n`);
         record.emitter.emit('chunk', chunk);
     }
+    /** A chunk for a job that no longer runs: appended to both files, never to a stream that is still open. */
+    pushRecovered(record, data) {
+        this.ensureChunks(record);
+        const chunk = { seq: record.nextSeq++, stream: 'system', data };
+        record.chunks.push(chunk);
+        record.bufferedChars += data.length;
+        while (record.bufferedChars > MAX_BUFFERED_CHARS && record.chunks.length > 1) {
+            record.bufferedChars -= record.chunks.shift().data.length;
+        }
+        try {
+            appendChunkNow(record.info.id, chunk, data);
+        }
+        catch (error) {
+            console.error('Could not write the job record:', error);
+        }
+    }
+    persist(record) {
+        // `onFinish` is a function and is reattached by `buildJobSpec` when the job is started again.
+        const { onFinish: _onFinish, ...spec } = record.spec;
+        const persisted = {
+            version: 1,
+            info: record.info,
+            spec: spec,
+            ...(record.pid !== null && { pid: record.pid }),
+        };
+        try {
+            writeRecord(persisted);
+        }
+        catch (error) {
+            console.error('Could not write the job record:', error);
+        }
+    }
     finish(record, code, signal, note) {
         const { info } = record;
         if (record.heartbeat)
@@ -273,21 +569,27 @@ class JobManager {
         info.exitCode = code;
         info.signal = signal;
         info.endedAt = new Date().toISOString();
-        info.status = record.cancelRequested
-            ? 'cancelled'
-            : code === 0
-                ? 'succeeded'
-                : 'failed';
+        info.status = record.stalled
+            ? 'failed'
+            : record.cancelRequested
+                ? 'cancelled'
+                : code === 0
+                    ? 'succeeded'
+                    : 'failed';
         const summary = note ??
-            (info.status === 'cancelled'
-                ? '[cancelled]'
-                : signal
-                    ? `[process killed by ${signal}]`
-                    : `[process exited with code ${code}]`);
+            (record.stalled
+                ? '[stopped: the agent did not answer]'
+                : info.status === 'cancelled'
+                    ? '[cancelled]'
+                    : signal
+                        ? `[process killed by ${signal}]`
+                        : `[process exited with code ${code}]`);
         if (record.spec.ai && info.status === 'succeeded')
-            info.resultState = parseResultState(record);
+            info.resultState = parseResultState(resultText(record));
         this.push(record, 'system', `\n${summary}\n`);
-        record.logStream.end();
+        record.logStream?.end();
+        record.chunkStream?.end();
+        this.persist(record);
         try {
             record.spec.onFinish?.(info);
         }
@@ -299,18 +601,18 @@ class JobManager {
         this.pruneFinished();
     }
     pruneFinished() {
-        const finished = [...this.jobs.values()].filter((record) => record.info.status !== 'running');
+        const live = new Set([...this.jobs.values()].filter((record) => record.info.status === 'running').map((record) => record.info.id));
+        const finished = [...this.jobs.values()].filter((record) => record.info.status !== 'running' &&
+            record.info.leftover?.state !== 'alive' &&
+            record.info.leftover?.state !== 'unknown');
         for (const record of finished.slice(0, Math.max(0, finished.length - MAX_FINISHED_JOBS))) {
             this.jobs.delete(record.info.id);
         }
-    }
-    pruneOldLogs() {
-        if (!fs.existsSync(LOG_DIR))
-            return;
-        for (const name of fs.readdirSync(LOG_DIR)) {
-            const file = path.join(LOG_DIR, name);
-            if (Date.now() - fs.statSync(file).mtimeMs > LOG_RETENTION_MS)
-                fs.rmSync(file, { force: true });
+        try {
+            pruneJobs(MAX_FINISHED_JOBS, LOG_RETENTION_MS, live);
+        }
+        catch (error) {
+            console.error('Could not prune the job records:', error);
         }
     }
 }

package/dist/ui/server/process-info.d.ts

@@ -0,0 +1,17 @@
+export interface ProcessDetails {
+    /** The command line the system reports, empty when the platform could not read it. */
+    commandLine: string;
+    /** Milliseconds since the Unix epoch, or null when the platform could not report it. */
+    startedAt: number | null;
+}
+/**
+ * The details of these pids, or `null` for one that is gone. One call for all of them: a restart usually has only a
+ * handful of jobs to look at, but probing should not be started once per job.
+ */
+export declare function probeProcesses(pids: number[]): Map<number, ProcessDetails | null>;
+/**
+ * Ends a process and everything it started: the agent CLI, the browser and the MCP server below it. Off Windows the
+ * process was spawned as the leader of its own group, so the whole group is signalled; Windows has no process groups,
+ * and `taskkill /T` walks the tree instead.
+ */
+export declare function killProcessTree(pid: number, signal: NodeJS.Signals): void;