@prohost/cli 0.2.2 → 0.3.0

package/dist/agent/command.js

@@ -35,14 +35,23 @@ const INVALID_TIMEOUT = Symbol('invalid-timeout');
  *
  * Returns ``undefined`` when the flag was absent (the harness applies its own
  * default) and {@link INVALID_TIMEOUT} after printing the error.
+ *
+ * ``0`` is legal and means "no local cap": the run ends when the agent ends it,
+ * when somebody cancels it, or when the server stops renewing its lease. It was
+ * rejected until long runs existed, because before heartbeats an uncapped run
+ * on a laptop that went to sleep was a row that span forever.
  */
 function parseTimeoutSeconds(flags) {
     const raw = flagString(flags, 'timeout');
     if (raw === undefined)
         return undefined;
     const seconds = Number(raw);
-    if (!Number.isFinite(seconds) || seconds <= 0) {
-        process.stderr.write('--timeout must be a positive number of seconds.\n');
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        // Keeps the phrase "--timeout must be a positive number" verbatim: the
+        // desktop app's supervisor matches on it to tell a misconfigured child from
+        // a recoverable crash (`desktop/src/main/agent/supervisor-policy.ts`), and
+        // it reads this CLI's stderr rather than any structured output.
+        process.stderr.write('--timeout must be a positive number of seconds, or 0 for no local limit.\n');
         return INVALID_TIMEOUT;
     }
     return seconds;

package/dist/agent/contract.d.ts

@@ -13,6 +13,7 @@
  * Server-side sources of truth:
  *   - payload shape — `shared/events/payloads/agent_runs.py`
  *   - `POST /v1/agent-runs/{id}/complete` — `api_public/routers/agent_runs.py`
+ *   - `POST /v1/agent-runs/{id}/heartbeat` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-pairing/redeem` — `api_public/routers/agent_pairing.py`
  *   - `POST /v1/conversations/{id}/messages` — `api_public/routers/conversations.py`
  */
@@ -28,12 +29,50 @@ export declare const RUN_STATUS_SUCCEEDED = "succeeded";
 export declare const RUN_STATUS_FAILED = "failed";
 /** Server-side cap on the `error` field of a completion (`MAX_ERROR_CHARS`). */
 export declare const MAX_ERROR_CHARS = 1000;
+/**
+ * The completion `error` that means "a person asked for this run to stop".
+ *
+ * A magic string on purpose, and it must be sent **exactly**: the server
+ * matches on it to word the notice it drops in the thread ("cancelled" rather
+ * than "failed"). Prefixing it with a reason, or sending
+ * `cancelled_by_user: …`, makes a deliberate stop read as a crash.
+ */
+export declare const RUN_ERROR_CANCELLED_BY_USER = "cancelled_by_user";
+/**
+ * Cap on the `progress` string sent with a heartbeat.
+ *
+ * Progress is a hint for the UI — "using Bash", the first line of what the
+ * agent is drafting — not a transcript. Bounded here so a brain that emits one
+ * enormous block of text can't turn a keep-alive into a payload.
+ */
+export declare const MAX_PROGRESS_CHARS = 200;
 /** `POST` — exchange a one-time pairing code for a scoped credential. */
 export declare const REDEEM_PATH = "/v1/agent-pairing/redeem";
 /** `POST` — send a message into a conversation as the paired agent. */
 export declare function conversationMessagesPath(conversationId: string): string;
 /** `POST` — close out a run. Must be called for every run, success or not. */
 export declare function agentRunCompletePath(runId: string): string;
+/**
+ * `POST` — say a run is still alive, and hear back whether it was cancelled.
+ *
+ * The server holds a lease on every running row and reaps the ones that stop
+ * being heard from; a run that legitimately takes four hours has to say so on a
+ * cadence or it is reaped mid-work. The response also carries
+ * `cancel_requested`, which is the only way a laptop behind NAT learns that
+ * somebody pressed stop.
+ */
+export declare function agentRunHeartbeatPath(runId: string): string;
+/**
+ * Where this run's heartbeats go.
+ *
+ * Derived from the server-supplied completion path rather than rebuilt from the
+ * run id, on the same reasoning the rest of this module prefers server-supplied
+ * paths: the two calls are the same resource, so a server that moves its
+ * agent-run routes moves both together and this CLI follows without a release.
+ * The documented path is the fallback for a completion path shaped in some way
+ * we don't recognise.
+ */
+export declare function heartbeatPathFor(run: AgentRunRequest): string;
 /**
  * A file or image hanging off a message.
  *

package/dist/agent/contract.js

@@ -13,6 +13,7 @@
  * Server-side sources of truth:
  *   - payload shape — `shared/events/payloads/agent_runs.py`
  *   - `POST /v1/agent-runs/{id}/complete` — `api_public/routers/agent_runs.py`
+ *   - `POST /v1/agent-runs/{id}/heartbeat` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-pairing/redeem` — `api_public/routers/agent_pairing.py`
  *   - `POST /v1/conversations/{id}/messages` — `api_public/routers/conversations.py`
  */
@@ -28,6 +29,23 @@ export const RUN_STATUS_SUCCEEDED = 'succeeded';
 export const RUN_STATUS_FAILED = 'failed';
 /** Server-side cap on the `error` field of a completion (`MAX_ERROR_CHARS`). */
 export const MAX_ERROR_CHARS = 1000;
+/**
+ * The completion `error` that means "a person asked for this run to stop".
+ *
+ * A magic string on purpose, and it must be sent **exactly**: the server
+ * matches on it to word the notice it drops in the thread ("cancelled" rather
+ * than "failed"). Prefixing it with a reason, or sending
+ * `cancelled_by_user: …`, makes a deliberate stop read as a crash.
+ */
+export const RUN_ERROR_CANCELLED_BY_USER = 'cancelled_by_user';
+/**
+ * Cap on the `progress` string sent with a heartbeat.
+ *
+ * Progress is a hint for the UI — "using Bash", the first line of what the
+ * agent is drafting — not a transcript. Bounded here so a brain that emits one
+ * enormous block of text can't turn a keep-alive into a payload.
+ */
+export const MAX_PROGRESS_CHARS = 200;
 /** `POST` — exchange a one-time pairing code for a scoped credential. */
 export const REDEEM_PATH = '/v1/agent-pairing/redeem';
 /** `POST` — send a message into a conversation as the paired agent. */
@@ -38,6 +56,35 @@ export function conversationMessagesPath(conversationId) {
 export function agentRunCompletePath(runId) {
     return `/v1/agent-runs/${encodeURIComponent(runId)}/complete`;
 }
+/**
+ * `POST` — say a run is still alive, and hear back whether it was cancelled.
+ *
+ * The server holds a lease on every running row and reaps the ones that stop
+ * being heard from; a run that legitimately takes four hours has to say so on a
+ * cadence or it is reaped mid-work. The response also carries
+ * `cancel_requested`, which is the only way a laptop behind NAT learns that
+ * somebody pressed stop.
+ */
+export function agentRunHeartbeatPath(runId) {
+    return `/v1/agent-runs/${encodeURIComponent(runId)}/heartbeat`;
+}
+/**
+ * Where this run's heartbeats go.
+ *
+ * Derived from the server-supplied completion path rather than rebuilt from the
+ * run id, on the same reasoning the rest of this module prefers server-supplied
+ * paths: the two calls are the same resource, so a server that moves its
+ * agent-run routes moves both together and this CLI follows without a release.
+ * The documented path is the fallback for a completion path shaped in some way
+ * we don't recognise.
+ */
+export function heartbeatPathFor(run) {
+    const completion = run.completion_path;
+    const suffix = '/complete';
+    return completion.endsWith(suffix)
+        ? `${completion.slice(0, -suffix.length)}/heartbeat`
+        : agentRunHeartbeatPath(run.run_id);
+}
 /**
  * Ceiling on how many context entries are kept from one payload.
  *

package/dist/agent/exec.d.ts

@@ -17,12 +17,36 @@ export interface ExecOptions {
     command: string;
     /** Prompt written to the child's stdin. */
     prompt: string;
-    /** Hard cap on wall-clock runtime. */
+    /**
+     * Hard cap on wall-clock runtime.
+     *
+     * ``0`` disables it: the child then runs until it exits on its own, until
+     * {@link cancelSignal} fires, or until the server gives up on the run. That
+     * is a real configuration (`--timeout 0`), not a degenerate one — some work
+     * genuinely takes hours and a local clock is the wrong thing to bound it by.
+     */
     timeoutMs: number;
     /** Working directory for the child. Defaults to the CLI's cwd. */
     cwd?: string;
     /** Extra environment for the child, merged over ``process.env``. */
     env?: NodeJS.ProcessEnv;
+    /**
+     * Ends the run early — a person pressed stop, or the server closed the run.
+     *
+     * Terminated through exactly the same SIGTERM → grace → SIGKILL path a
+     * timeout uses, because the problem is identical: the thing being stopped is
+     * a process *group* that may be ignoring polite signals.
+     */
+    cancelSignal?: AbortSignal;
+    /**
+     * Each stdout chunk, as it arrives.
+     *
+     * The captured ``stdout`` is still returned in full; this exists for the
+     * things that cannot wait for the process to exit — reading a session id out
+     * of the first event, tracking what the agent is doing for the heartbeat, and
+     * having *something* to salvage from a run that gets killed.
+     */
+    onStdout?: (chunk: string) => void;
     /** Injectable spawn — tests substitute a fake process. */
     spawnImpl?: typeof spawn;
 }
@@ -32,17 +56,31 @@ export interface ExecResult {
     stderr: string;
     exitCode: number | null;
     timedOut: boolean;
+    /** The run was stopped through {@link ExecOptions.cancelSignal}. */
+    cancelled: boolean;
     /** Populated when the process could not be started at all. */
     error?: string;
     durationMs: number;
 }
 /** Cap on captured output (in characters) so a runaway agent can't exhaust memory. */
 export declare const MAX_OUTPUT_CHARS: number;
+/** ``error`` on a result the caller stopped deliberately. */
+export declare const CANCELLED_ERROR = "cancelled";
+/**
+ * What a timed-out run reports.
+ *
+ * Ends with the way out, because this string does not stay in `agent.log`: the
+ * server echoes a failed run's error into the thread, so the person who was
+ * waiting reads it. Told "timed out after 7200000ms" they learn only that
+ * something broke; told how to raise the ceiling they can fix it themselves.
+ * Kept to one line for the same reason.
+ */
+export declare function timeoutMessage(timeoutMs: number): string;
 /**
  * Execute the agent command with ``prompt`` on stdin and return its stdout.
  *
- * Never throws: a spawn failure, a non-zero exit, and a timeout all come back
- * as ``ok: false`` with the detail filled in, because the caller must report
- * *some* outcome to the server for every run.
+ * Never throws: a spawn failure, a non-zero exit, a timeout, and a cancellation
+ * all come back as ``ok: false`` with the detail filled in, because the caller
+ * must report *some* outcome to the server for every run.
  */
 export declare function execAgent(options: ExecOptions): Promise<ExecResult>;

package/dist/agent/exec.js

@@ -11,11 +11,25 @@
  * comes from the host's own flag — but event-derived text never reaches the
  * shell, so a crafted mention cannot inject a command.
  */
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 /** Cap on captured output (in characters) so a runaway agent can't exhaust memory. */
 export const MAX_OUTPUT_CHARS = 512 * 1024;
-/** Grace period between SIGTERM and SIGKILL when a run overruns its timeout. */
+/** Grace period between SIGTERM and SIGKILL when a run is being stopped. */
 const KILL_GRACE_MS = 5_000;
+/** ``error`` on a result the caller stopped deliberately. */
+export const CANCELLED_ERROR = 'cancelled';
+/**
+ * What a timed-out run reports.
+ *
+ * Ends with the way out, because this string does not stay in `agent.log`: the
+ * server echoes a failed run's error into the thread, so the person who was
+ * waiting reads it. Told "timed out after 7200000ms" they learn only that
+ * something broke; told how to raise the ceiling they can fix it themselves.
+ * Kept to one line for the same reason.
+ */
+export function timeoutMessage(timeoutMs) {
+    return `timed out after ${timeoutMs}ms — raise the ceiling with --timeout <seconds> (0 = no limit)`;
+}
 function clamp(text) {
     if (text.length <= MAX_OUTPUT_CHARS)
         return text;
@@ -24,9 +38,9 @@ function clamp(text) {
 /**
  * Execute the agent command with ``prompt`` on stdin and return its stdout.
  *
- * Never throws: a spawn failure, a non-zero exit, and a timeout all come back
- * as ``ok: false`` with the detail filled in, because the caller must report
- * *some* outcome to the server for every run.
+ * Never throws: a spawn failure, a non-zero exit, a timeout, and a cancellation
+ * all come back as ``ok: false`` with the detail filled in, because the caller
+ * must report *some* outcome to the server for every run.
  */
 export async function execAgent(options) {
     const spawnImpl = options.spawnImpl ?? spawn;
@@ -35,7 +49,23 @@ export async function execAgent(options) {
         let stdout = '';
         let stderr = '';
         let timedOut = false;
+        let cancelled = false;
         let settled = false;
+        // Nothing to stop if the stop already happened: a run cancelled while it
+        // sat in the queue must not spawn the agent at all.
+        if (options.cancelSignal?.aborted) {
+            resolve({
+                ok: false,
+                stdout: '',
+                stderr: '',
+                exitCode: null,
+                timedOut: false,
+                cancelled: true,
+                error: CANCELLED_ERROR,
+                durationMs: Date.now() - started,
+            });
+            return;
+        }
         const spawnOptions = {
             shell: true,
             cwd: options.cwd,
@@ -58,27 +88,52 @@ export async function execAgent(options) {
                 stderr: '',
                 exitCode: null,
                 timedOut: false,
+                cancelled: false,
                 error: err instanceof Error ? err.message : String(err),
                 durationMs: Date.now() - started,
             });
             return;
         }
+        let timer;
         let killTimer;
+        /** Why the run ended, when it ended because we ended it. */
+        const stopReason = () => cancelled ? CANCELLED_ERROR : timedOut ? timeoutMessage(options.timeoutMs) : undefined;
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
-            clearTimeout(timer);
+            if (timer !== undefined)
+                clearTimeout(timer);
             if (killTimer !== undefined)
                 clearTimeout(killTimer);
+            options.cancelSignal?.removeEventListener('abort', onAbort);
             resolve({ ...result, durationMs: Date.now() - started });
         };
         /**
-         * Signal the child's whole process group, falling back to the child alone
-         * when there is no group (Windows, or a spawn that never got a pid).
+         * Signal the child's whole process tree.
+         *
+         * POSIX: the child has its own process group (see `detached` above), so one
+         * signal reaches the shell and everything it started.
+         *
+         * Windows has no process groups to signal, and `shell: true` means the
+         * child is `cmd.exe` — killing it alone leaves the agent it launched
+         * running, which is a run reported as stopped that carries on acting with
+         * the operator's credentials. `taskkill /T` walks the tree instead, with
+         * `/F` as the SIGKILL half of the escalation. It is best-effort: if
+         * `taskkill` is missing or refuses, the fallback below still kills the
+         * shell, which is exactly what this did before.
          */
         const signalTree = (signal) => {
             const pid = child.pid;
+            if (pid !== undefined && process.platform === 'win32') {
+                try {
+                    const args = ['/pid', String(pid), '/T', ...(signal === 'SIGKILL' ? ['/F'] : [])];
+                    spawnSync('taskkill', args, { windowsHide: true });
+                }
+                catch {
+                    // Fall through — the child itself is still signalled below.
+                }
+            }
             try {
                 if (pid !== undefined && spawnOptions.detached)
                     process.kill(-pid, signal);
@@ -89,11 +144,18 @@ export async function execAgent(options) {
                 // ESRCH — the group is already gone, which is the outcome we wanted.
             }
         };
-        const timer = setTimeout(() => {
-            timedOut = true;
+        /**
+         * End the run: ask politely, then insist.
+         *
+         * The single path for both reasons a run is stopped from outside. They need
+         * identical handling — an agent that ignores SIGTERM ignores it whoever
+         * sent it — and having one caller escalate and the other not is how a
+         * cancelled run wedges the queue behind a child that never died.
+         */
+        const terminate = () => {
+            if (settled || killTimer !== undefined)
+                return;
             signalTree('SIGTERM');
-            // Escalate if the agent ignores SIGTERM, so a wedged child can't hold
-            // the harness open past its timeout.
             killTimer = setTimeout(() => {
                 signalTree('SIGKILL');
                 // A descendant can still hold the pipes open after the group is
@@ -104,14 +166,36 @@ export async function execAgent(options) {
                     stdout: clamp(stdout),
                     stderr: clamp(stderr),
                     exitCode: null,
-                    timedOut: true,
-                    error: `timed out after ${options.timeoutMs}ms`,
+                    timedOut,
+                    cancelled,
+                    error: stopReason(),
                 });
             }, KILL_GRACE_MS);
-        }, options.timeoutMs);
+        };
+        function onAbort() {
+            cancelled = true;
+            terminate();
+        }
+        if (options.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                timedOut = true;
+                terminate();
+            }, options.timeoutMs);
+        }
+        options.cancelSignal?.addEventListener('abort', onAbort, { once: true });
         child.stdout?.on('data', (chunk) => {
+            const text = chunk.toString();
+            // Capture is bounded; the callback is not. A parser that stops being fed
+            // at 512 KB would report stale progress and salvage the wrong text for
+            // the rest of a long run — and the callback keeps nothing per chunk.
             if (stdout.length < MAX_OUTPUT_CHARS)
-                stdout += chunk.toString();
+                stdout += text;
+            try {
+                options.onStdout?.(text);
+            }
+            catch {
+                // A broken observer must not cost the run its output.
+            }
         });
         child.stderr?.on('data', (chunk) => {
             if (stderr.length < MAX_OUTPUT_CHARS)
@@ -124,17 +208,19 @@ export async function execAgent(options) {
                 stderr: clamp(stderr),
                 exitCode: null,
                 timedOut,
+                cancelled,
                 error: err.message,
             });
         });
         child.on('close', (code) => {
             finish({
-                ok: !timedOut && code === 0,
+                ok: !timedOut && !cancelled && code === 0,
                 stdout: clamp(stdout),
                 stderr: clamp(stderr),
                 exitCode: code,
                 timedOut,
-                error: timedOut ? `timed out after ${options.timeoutMs}ms` : undefined,
+                cancelled,
+                error: stopReason(),
             });
         });
         // stdin may already be closed if the command failed to start.

package/dist/agent/extras.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The operator's opt-in extra MCP servers (`$PROHOST_HOME/extra-mcp.json`).
+ *
+ * Both brains this harness shapes get exactly one MCP server by default — ours
+ * — and that isolation is a security boundary rather than an implementation
+ * detail. A paired run executes with permission prompts off, on prompt text
+ * written by anyone who can mention the agent in the workspace, so every server
+ * reachable from that run is a server a workspace teammate can drive. Claude
+ * Code is held to it by `--strict-mcp-config`; Codex is held to it by
+ * explicitly disabling the servers its own config defines.
+ *
+ * That leaves no way at all to give the agent a tool the operator *does* want
+ * it to have, which is why this file exists. It is **never created by the
+ * CLI** — its presence is the operator's deliberate act, taken after reading
+ * what it costs. Nothing here weakens the boundary; it moves the decision to a
+ * file whose only purpose is to record it.
+ *
+ * Everything in this module fails soft, in the sense `claude.ts` states: a
+ * malformed file is a warning and a run without extras, never a run that
+ * doesn't happen. The operator's agent going quiet is a worse outcome than
+ * their extra server being missing, and the missing server is the one they can
+ * actually see in the log.
+ */
+/** Filename of the operator-authored extras file, inside `$PROHOST_HOME`. */
+export declare const EXTRA_MCP_FILENAME = "extra-mcp.json";
+/** One server definition, passed through to the brain untouched. */
+export type ExtraServer = Record<string, unknown>;
+export interface ExtraMcpServers {
+    /** Accepted definitions, keyed by server name. Empty when there are none. */
+    servers: Record<string, ExtraServer>;
+    /**
+     * Lines for the operator to see when the current grant set is loaded.
+     *
+     * Both the good news and the bad travel this way: which extras loaded is as
+     * worth printing as which were rejected, because "I added a server and the
+     * agent still can't use it" is otherwise a silent, unfalsifiable complaint.
+     */
+    warnings: string[];
+}
+/** Absolute path of the extras file. */
+export declare function extraMcpPath(env?: NodeJS.ProcessEnv): string;
+export interface LoadExtraOptions {
+    env?: NodeJS.ProcessEnv;
+    /** Injectable read, so a test can exercise the parse without a filesystem. */
+    readImpl?: (file: string) => string;
+}
+/**
+ * Read and validate `extra-mcp.json`.
+ *
+ * The file's shape is deliberately the same object Claude Code's
+ * `--mcp-config` takes — `{"mcpServers": {"<name>": {...}}}` — so an operator
+ * can lift a block straight out of a `.mcp.json` they already have rather than
+ * learn a format that exists only here.
+ *
+ * Four rejections, each returning a warning rather than an exception:
+ *
+ *  * **No file.** Not a warning at all — the overwhelmingly common case, and
+ *    the CLI never creates one, so its absence is the default state rather
+ *    than something the operator did wrong.
+ *  * **Unparseable JSON.** A warning and zero extras. The alternative — refuse
+ *    to start — would take a working agent offline over a trailing comma in an
+ *    optional enhancement.
+ *  * **A server named `prohost`.** Rejected loudly and never merged. The name
+ *    is how the prompt, the `--allowedTools` pattern and both generated
+ *    configs refer to the ProhostAI server; letting a file on disk take it
+ *    over would silently redirect a run's workspace lookups — with the agent
+ *    still reporting, in good faith, that it looked them up.
+ *  * **A definition that is not an object.** Rejected per entry, because a
+ *    `"github": "https://…"` typo would otherwise reach the brain as a config
+ *    it cannot parse and take the whole config down with it — including our
+ *    server.
+ */
+export declare function loadExtraMcpServers(options?: LoadExtraOptions): ExtraMcpServers;

package/dist/agent/extras.js

@@ -0,0 +1,118 @@
+/**
+ * The operator's opt-in extra MCP servers (`$PROHOST_HOME/extra-mcp.json`).
+ *
+ * Both brains this harness shapes get exactly one MCP server by default — ours
+ * — and that isolation is a security boundary rather than an implementation
+ * detail. A paired run executes with permission prompts off, on prompt text
+ * written by anyone who can mention the agent in the workspace, so every server
+ * reachable from that run is a server a workspace teammate can drive. Claude
+ * Code is held to it by `--strict-mcp-config`; Codex is held to it by
+ * explicitly disabling the servers its own config defines.
+ *
+ * That leaves no way at all to give the agent a tool the operator *does* want
+ * it to have, which is why this file exists. It is **never created by the
+ * CLI** — its presence is the operator's deliberate act, taken after reading
+ * what it costs. Nothing here weakens the boundary; it moves the decision to a
+ * file whose only purpose is to record it.
+ *
+ * Everything in this module fails soft, in the sense `claude.ts` states: a
+ * malformed file is a warning and a run without extras, never a run that
+ * doesn't happen. The operator's agent going quiet is a worse outcome than
+ * their extra server being missing, and the missing server is the one they can
+ * actually see in the log.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { prohostHome } from './credentials.js';
+import { MCP_SERVER_NAME } from './mcp.js';
+/** Filename of the operator-authored extras file, inside `$PROHOST_HOME`. */
+export const EXTRA_MCP_FILENAME = 'extra-mcp.json';
+/** Absolute path of the extras file. */
+export function extraMcpPath(env = process.env) {
+    return path.join(prohostHome(env), EXTRA_MCP_FILENAME);
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Read and validate `extra-mcp.json`.
+ *
+ * The file's shape is deliberately the same object Claude Code's
+ * `--mcp-config` takes — `{"mcpServers": {"<name>": {...}}}` — so an operator
+ * can lift a block straight out of a `.mcp.json` they already have rather than
+ * learn a format that exists only here.
+ *
+ * Four rejections, each returning a warning rather than an exception:
+ *
+ *  * **No file.** Not a warning at all — the overwhelmingly common case, and
+ *    the CLI never creates one, so its absence is the default state rather
+ *    than something the operator did wrong.
+ *  * **Unparseable JSON.** A warning and zero extras. The alternative — refuse
+ *    to start — would take a working agent offline over a trailing comma in an
+ *    optional enhancement.
+ *  * **A server named `prohost`.** Rejected loudly and never merged. The name
+ *    is how the prompt, the `--allowedTools` pattern and both generated
+ *    configs refer to the ProhostAI server; letting a file on disk take it
+ *    over would silently redirect a run's workspace lookups — with the agent
+ *    still reporting, in good faith, that it looked them up.
+ *  * **A definition that is not an object.** Rejected per entry, because a
+ *    `"github": "https://…"` typo would otherwise reach the brain as a config
+ *    it cannot parse and take the whole config down with it — including our
+ *    server.
+ */
+export function loadExtraMcpServers(options = {}) {
+    const file = extraMcpPath(options.env ?? process.env);
+    const read = options.readImpl ?? ((target) => readFileSync(target, 'utf8'));
+    let raw;
+    try {
+        raw = read(file);
+    }
+    catch (err) {
+        // ENOENT is the normal state and must stay silent. Anything else — a
+        // permission problem, a directory where the file should be — the operator
+        // wants to hear about, because they put the file there on purpose.
+        const code = err.code;
+        if (code === 'ENOENT')
+            return { servers: {}, warnings: [] };
+        return {
+            servers: {},
+            warnings: [`could not read ${file} (${err instanceof Error ? err.message : String(err)}); no extra MCP servers`],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            servers: {},
+            warnings: [`${file} is not valid JSON (${err instanceof Error ? err.message : String(err)}); no extra MCP servers`],
+        };
+    }
+    if (!isPlainObject(parsed) || !isPlainObject(parsed.mcpServers)) {
+        return {
+            servers: {},
+            warnings: [`${file} has no "mcpServers" object; no extra MCP servers`],
+        };
+    }
+    const servers = {};
+    const warnings = [];
+    for (const [name, definition] of Object.entries(parsed.mcpServers)) {
+        if (name === MCP_SERVER_NAME) {
+            warnings.push(`${file} defines a server named "${MCP_SERVER_NAME}" — that name is reserved for the ` +
+                'ProhostAI server and the entry was ignored. Rename it to use it.');
+            continue;
+        }
+        if (!isPlainObject(definition)) {
+            warnings.push(`${file}: server "${name}" is not an object; the entry was ignored`);
+            continue;
+        }
+        servers[name] = definition;
+    }
+    const names = Object.keys(servers);
+    if (names.length > 0) {
+        warnings.push(`extra MCP servers loaded from ${EXTRA_MCP_FILENAME}: ${names.join(', ')} — ` +
+            'anyone who can trigger this agent can use them, with permission prompts off.');
+    }
+    return { servers, warnings };
+}