@prohost/cli 0.3.0 → 0.4.1

package/dist/agent/contract.d.ts

@@ -63,14 +63,19 @@ export declare function agentRunCompletePath(runId: string): string;
  */
 export declare function agentRunHeartbeatPath(runId: string): string;
 /**
- * Where this run's heartbeats go.
+ * Where this run's heartbeats go, in descending order of how much we know.
  *
- * 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.
+ * 1. The `heartbeat` block, when the payload carries one. A path the server
+ *    stated is not a guess, so it is used verbatim.
+ * 2. Otherwise, derived from the server-supplied completion path: the two
+ *    calls are the same resource, so a server that moves its agent-run routes
+ *    moves both together and a CLI already on somebody's laptop follows
+ *    without a release.
+ * 3. Otherwise the documented path, for a completion path shaped in some way
+ *    we don't recognise.
+ *
+ * Steps 2 and 3 are exactly what shipped in 0.3.0 and are not going anywhere:
+ * the block is additive, and every server that predates it must keep working.
  */
 export declare function heartbeatPathFor(run: AgentRunRequest): string;
 /**
@@ -216,6 +221,14 @@ export interface AgentRunRequest {
     reply_body_extra?: Record<string, unknown>;
     /** Server-supplied path to complete the run at. */
     completion_path: string;
+    /**
+     * Server-supplied path to heartbeat the run at.
+     *
+     * Absent on every server built before the `heartbeat` block was added
+     * alongside `completion`, which is most of them — see {@link heartbeatPathFor}
+     * for what happens then.
+     */
+    heartbeat_path?: string;
     /**
      * Earlier messages on this surface, oldest first. Absent on a server that
      * predates the field — which is the case the harness shipped with, so an

package/dist/agent/contract.js

@@ -69,16 +69,23 @@ export function agentRunHeartbeatPath(runId) {
     return `/v1/agent-runs/${encodeURIComponent(runId)}/heartbeat`;
 }
 /**
- * Where this run's heartbeats go.
+ * Where this run's heartbeats go, in descending order of how much we know.
  *
- * 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.
+ * 1. The `heartbeat` block, when the payload carries one. A path the server
+ *    stated is not a guess, so it is used verbatim.
+ * 2. Otherwise, derived from the server-supplied completion path: the two
+ *    calls are the same resource, so a server that moves its agent-run routes
+ *    moves both together and a CLI already on somebody's laptop follows
+ *    without a release.
+ * 3. Otherwise the documented path, for a completion path shaped in some way
+ *    we don't recognise.
+ *
+ * Steps 2 and 3 are exactly what shipped in 0.3.0 and are not going anywhere:
+ * the block is additive, and every server that predates it must keep working.
  */
 export function heartbeatPathFor(run) {
+    if (run.heartbeat_path)
+        return run.heartbeat_path;
     const completion = run.completion_path;
     const suffix = '/complete';
     return completion.endsWith(suffix)
@@ -255,6 +262,7 @@ export function parseRunRequest(data) {
     const trigger = obj(data.trigger);
     const replyInstructions = obj(data.reply_instructions);
     const completion = obj(data.completion);
+    const heartbeat = obj(data.heartbeat);
     const context = obj(data.context);
     const declaredSurface = str(replyInstructions.surface);
     const conversationId = str(data.conversation_id) ?? str(replyInstructions.conversation_id);
@@ -297,6 +305,9 @@ export function parseRunRequest(data) {
         reply_body_key: str(replyInstructions.body_field) ?? legacyBodyKeyFor(surface),
         reply_body_extra: bodyExtra(replyInstructions.body_extra),
         completion_path: str(completion.path) ?? agentRunCompletePath(runId),
+        // No fallback of its own: an absent block is not an error, it is an older
+        // server, and `heartbeatPathFor` already knows what to do about that.
+        heartbeat_path: str(heartbeat.path),
         // Accepted both at the top level and nested under `context`, because the
         // server can move them without a CLI release either way — and a published
         // CLI cannot be redeployed to follow.

package/dist/agent/daemon.d.ts

@@ -83,6 +83,8 @@ export interface HarnessInvocation {
     exec: string;
     workdir: string;
     timeoutSeconds?: number;
+    /** Seconds of total silence before a run is treated as stalled. */
+    idleTimeoutSeconds?: number;
     machine?: string;
     url?: string;
     allowUnverified?: boolean;

package/dist/agent/daemon.js

@@ -176,8 +176,14 @@ export function harnessArguments(invocation) {
         '--workdir',
         invocation.workdir,
     ];
+    // Compared against `undefined` rather than tested for truth: `0` is a real
+    // setting for both flags — no wall-clock cap, no watchdog — and dropping it
+    // would install a daemon quietly running the defaults instead.
     if (invocation.timeoutSeconds !== undefined)
         args.push('--timeout', String(invocation.timeoutSeconds));
+    if (invocation.idleTimeoutSeconds !== undefined) {
+        args.push('--idle-timeout', String(invocation.idleTimeoutSeconds));
+    }
     if (invocation.machine)
         args.push('--machine', invocation.machine);
     if (invocation.url)

package/dist/agent/exec.d.ts

@@ -26,6 +26,19 @@ export interface ExecOptions {
      * genuinely takes hours and a local clock is the wrong thing to bound it by.
      */
     timeoutMs: number;
+    /**
+     * Kill the run when the child produces **nothing** for this long.
+     *
+     * The question a wall clock cannot answer: is this run working, or wedged?
+     * Bytes on stdout or stderr are the one signal every brain emits — stream
+     * events, a progress line, a log — so a window of total silence is the
+     * closest thing to evidence that a child has stopped making progress rather
+     * than merely taking a while. Every chunk on either stream resets it.
+     *
+     * ``0`` or unset disables it, at which point only {@link timeoutMs}, the
+     * {@link cancelSignal} and the server's lease can end the run.
+     */
+    idleTimeoutMs?: number;
     /** Working directory for the child. Defaults to the CLI's cwd. */
     cwd?: string;
     /** Extra environment for the child, merged over ``process.env``. */
@@ -55,7 +68,18 @@ export interface ExecResult {
     stdout: string;
     stderr: string;
     exitCode: number | null;
+    /** The run overran {@link ExecOptions.timeoutMs}. */
     timedOut: boolean;
+    /**
+     * The run went silent for {@link ExecOptions.idleTimeoutMs} and was killed.
+     *
+     * Separate from {@link timedOut} because the two say different things to
+     * whoever reads the failure: one run used its whole budget, the other stopped
+     * doing anything at all. They are handled identically everywhere else — both
+     * are kills from outside, so both salvage partial output and keep the
+     * session they had recorded.
+     */
+    idleTimedOut: boolean;
     /** The run was stopped through {@link ExecOptions.cancelSignal}. */
     cancelled: boolean;
     /** Populated when the process could not be started at all. */
@@ -76,6 +100,17 @@ export declare const CANCELLED_ERROR = "cancelled";
  * Kept to one line for the same reason.
  */
 export declare function timeoutMessage(timeoutMs: number): string;
+/**
+ * What a run killed by the inactivity watchdog reports.
+ *
+ * Same job as {@link timeoutMessage}, and the same constraint: the server
+ * echoes a failed run's error into the thread, so this is read by the person
+ * who was waiting rather than by whoever tails `agent.log`. It has to say what
+ * happened ("nothing came out of it"), that this is an inference rather than a
+ * crash the agent reported, and how to change the judgement — in one line,
+ * because the notice it lands in has room for one.
+ */
+export declare function idleTimeoutMessage(idleTimeoutMs: number): string;
 /**
  * Execute the agent command with ``prompt`` on stdin and return its stdout.
  *

package/dist/agent/exec.js

@@ -30,6 +30,38 @@ export const CANCELLED_ERROR = 'cancelled';
 export function timeoutMessage(timeoutMs) {
     return `timed out after ${timeoutMs}ms — raise the ceiling with --timeout <seconds> (0 = no limit)`;
 }
+/**
+ * Say a silence window the way a person would say it.
+ *
+ * The default is fifteen minutes and it wants to read as "15 minutes", not
+ * "900000ms": this string is shown to whoever was waiting on the agent, and a
+ * number they have to convert is a number they will misread.
+ */
+function renderWindow(ms) {
+    if (ms >= 60_000 && ms % 60_000 === 0) {
+        const minutes = ms / 60_000;
+        return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+    }
+    const seconds = ms / 1_000;
+    const rendered = Number.isInteger(seconds)
+        ? String(seconds)
+        : seconds.toFixed(seconds < 1 ? 2 : 1);
+    return `${rendered} second${rendered === '1' ? '' : 's'}`;
+}
+/**
+ * What a run killed by the inactivity watchdog reports.
+ *
+ * Same job as {@link timeoutMessage}, and the same constraint: the server
+ * echoes a failed run's error into the thread, so this is read by the person
+ * who was waiting rather than by whoever tails `agent.log`. It has to say what
+ * happened ("nothing came out of it"), that this is an inference rather than a
+ * crash the agent reported, and how to change the judgement — in one line,
+ * because the notice it lands in has room for one.
+ */
+export function idleTimeoutMessage(idleTimeoutMs) {
+    return (`no output for ${renderWindow(idleTimeoutMs)} — treated as stalled; ` +
+        'tune with --idle-timeout <seconds> (0 = disabled)');
+}
 function clamp(text) {
     if (text.length <= MAX_OUTPUT_CHARS)
         return text;
@@ -49,6 +81,7 @@ export async function execAgent(options) {
         let stdout = '';
         let stderr = '';
         let timedOut = false;
+        let idleTimedOut = false;
         let cancelled = false;
         let settled = false;
         // Nothing to stop if the stop already happened: a run cancelled while it
@@ -60,6 +93,7 @@ export async function execAgent(options) {
                 stderr: '',
                 exitCode: null,
                 timedOut: false,
+                idleTimedOut: false,
                 cancelled: true,
                 error: CANCELLED_ERROR,
                 durationMs: Date.now() - started,
@@ -88,6 +122,7 @@ export async function execAgent(options) {
                 stderr: '',
                 exitCode: null,
                 timedOut: false,
+                idleTimedOut: false,
                 cancelled: false,
                 error: err instanceof Error ? err.message : String(err),
                 durationMs: Date.now() - started,
@@ -95,15 +130,32 @@ export async function execAgent(options) {
             return;
         }
         let timer;
+        let idleTimer;
         let killTimer;
-        /** Why the run ended, when it ended because we ended it. */
-        const stopReason = () => cancelled ? CANCELLED_ERROR : timedOut ? timeoutMessage(options.timeoutMs) : undefined;
+        const idleMs = options.idleTimeoutMs ?? 0;
+        /**
+         * Why the run ended, when it ended because we ended it.
+         *
+         * Ordered by which decision was made first in practice: a deliberate stop
+         * outranks either clock, and the wall clock outranks the watchdog because
+         * `terminate` disarms the watchdog on its way out — so if both flags are
+         * somehow set, the ceiling is what actually fired.
+         */
+        const stopReason = () => cancelled
+            ? CANCELLED_ERROR
+            : timedOut
+                ? timeoutMessage(options.timeoutMs)
+                : idleTimedOut
+                    ? idleTimeoutMessage(idleMs)
+                    : undefined;
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
             if (timer !== undefined)
                 clearTimeout(timer);
+            if (idleTimer !== undefined)
+                clearTimeout(idleTimer);
             if (killTimer !== undefined)
                 clearTimeout(killTimer);
             options.cancelSignal?.removeEventListener('abort', onAbort);
@@ -155,6 +207,21 @@ export async function execAgent(options) {
         const terminate = () => {
             if (settled || killTimer !== undefined)
                 return;
+            // Both clocks are disarmed here rather than in `finish`, because a
+            // termination takes up to KILL_GRACE_MS and neither clock may re-decide
+            // the reason during it. A ceiling that lapses while a stalled run is
+            // being killed would otherwise overwrite "no output for 15 minutes" with
+            // "timed out", sending whoever reads it to the wrong flag — and the
+            // child's dying output would likewise re-arm a watchdog for a run that
+            // is already on its way out.
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            if (idleTimer !== undefined) {
+                clearTimeout(idleTimer);
+                idleTimer = undefined;
+            }
             signalTree('SIGTERM');
             killTimer = setTimeout(() => {
                 signalTree('SIGKILL');
@@ -167,11 +234,30 @@ export async function execAgent(options) {
                     stderr: clamp(stderr),
                     exitCode: null,
                     timedOut,
+                    idleTimedOut,
                     cancelled,
                     error: stopReason(),
                 });
             }, KILL_GRACE_MS);
         };
+        /**
+         * (Re)start the silence window.
+         *
+         * Armed once the child exists and again on every chunk it writes, so the
+         * window measures time since the last sign of life rather than time since
+         * the run began. Deliberately a no-op once a kill is under way: the run's
+         * fate is already decided, and the flag that explains it is already set.
+         */
+        const armIdleWatchdog = () => {
+            if (idleMs <= 0 || settled || killTimer !== undefined)
+                return;
+            if (idleTimer !== undefined)
+                clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+                idleTimedOut = true;
+                terminate();
+            }, idleMs);
+        };
         function onAbort() {
             cancelled = true;
             terminate();
@@ -185,6 +271,7 @@ export async function execAgent(options) {
         options.cancelSignal?.addEventListener('abort', onAbort, { once: true });
         child.stdout?.on('data', (chunk) => {
             const text = chunk.toString();
+            armIdleWatchdog();
             // 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.
@@ -198,6 +285,10 @@ export async function execAgent(options) {
             }
         });
         child.stderr?.on('data', (chunk) => {
+            // stderr counts as life exactly as much as stdout does. An agent that
+            // logs its progress to stderr and answers on stdout — several do — is
+            // plainly working, and a watchdog watching one stream would kill it.
+            armIdleWatchdog();
             if (stderr.length < MAX_OUTPUT_CHARS)
                 stderr += chunk.toString();
         });
@@ -208,21 +299,27 @@ export async function execAgent(options) {
                 stderr: clamp(stderr),
                 exitCode: null,
                 timedOut,
+                idleTimedOut,
                 cancelled,
                 error: err.message,
             });
         });
         child.on('close', (code) => {
             finish({
-                ok: !timedOut && !cancelled && code === 0,
+                ok: !timedOut && !idleTimedOut && !cancelled && code === 0,
                 stdout: clamp(stdout),
                 stderr: clamp(stderr),
                 exitCode: code,
                 timedOut,
+                idleTimedOut,
                 cancelled,
                 error: stopReason(),
             });
         });
+        // Started here, not at the top of the function: the window measures the
+        // child's silence, and a child that has not been spawned yet — or that
+        // failed to spawn at all — has nothing to be silent about.
+        armIdleWatchdog();
         // stdin may already be closed if the command failed to start.
         try {
             child.stdin?.on('error', () => {

package/dist/agent/prompt.d.ts

@@ -50,6 +50,17 @@ export interface PromptContext {
      * They cannot tell those apart from a sentence that says neither.
      */
     timeoutMs?: number;
+    /**
+     * How long the run may produce nothing at all before it is killed, in
+     * milliseconds. ``0`` is `--idle-timeout 0`: no watchdog.
+     *
+     * Threaded in for the same reason as {@link timeoutMs}, and it now carries
+     * most of the weight: with no wall-clock ceiling by default, this is usually
+     * the only local limit there is. It is also a limit an agent can act on,
+     * which a duration is not — "do not go completely silent for a quarter of an
+     * hour" is advice about how to work, not a request to hurry.
+     */
+    idleTimeoutMs?: number;
 }
 /** Build the stdin prompt for one run. */
 export declare function buildPrompt(run: AgentRunRequest, context: PromptContext): string;

package/dist/agent/prompt.js

@@ -23,31 +23,68 @@ function renderBudget(timeoutMs) {
     return `about ${Math.max(1, Math.round(timeoutMs / 1_000))} seconds`;
 }
 /**
- * The bullet that tells the agent how much time it actually has.
+ * The bullet that tells the agent what its run is actually bounded by.
  *
- * Both branches are load-bearing. A named ceiling stops an agent from treating
- * a two-hour budget like a five-minute one (the failure this replaced: a
- * multi-minute coding task killed at 300s having been told only that a limit
- * existed). And an *uncapped* run still needs a word about pace, because
- * nothing is posted until the turn ends — a run that explores forever reads,
- * from the thread, exactly like one that crashed.
+ * Three shapes, and each says something different about how to work:
+ *
+ * * **A wall-clock ceiling** (`--timeout <n>`) means budget the turn. Naming
+ *   the number is what stops an agent from treating two hours like five
+ *   minutes — the failure this replaced was a multi-minute coding task killed
+ *   at 300s having been told only that "a limit" existed. A watchdog set
+ *   *shorter* than the ceiling is named alongside it, because it is then the
+ *   deadline that actually fires first: told only "you have two hours", an
+ *   agent has no reason to break up the quiet forty-minute step that kills it
+ *   at fifteen.
+ * * **The watchdog alone** — the default — means the turn is bounded by
+ *   *silence*, not duration. That is a limit an agent can actually act on, and
+ *   it must be stated as what it is, because an agent told it has "no limit"
+ *   and then killed at fifteen minutes of quiet was told something false.
+ * * **Neither** means nothing local will stop the run, which still needs a word
+ *   about pace: nothing is posted until the turn ends, so a run that explores
+ *   forever reads, from the thread, exactly like one that crashed.
  */
-function timeBudgetLines(timeoutMs) {
-    if (timeoutMs === undefined)
+function timeBudgetLines(timeoutMs, idleTimeoutMs) {
+    // Said nothing about by the caller: say nothing back, rather than describe a
+    // regime this prompt has not been told is in force.
+    if (timeoutMs === undefined && idleTimeoutMs === undefined)
         return [];
-    if (timeoutMs <= 0) {
+    const wallMs = timeoutMs ?? 0;
+    const idleMs = idleTimeoutMs ?? 0;
+    if (wallMs > 0) {
+        return [
+            `- You have ${renderBudget(wallMs)} for this whole turn. Past that you are killed`,
+            '  mid-thought and the person waiting gets nothing, so spend the budget on the',
+            '  work and leave yourself room to write the answer.',
+            // Only when it can actually fire first. A watchdog window at or above the
+            // ceiling is unreachable — a run silent that long has already overrun —
+            // and naming an unreachable limit is noise the agent has to reason past.
+            ...(idleMs > 0 && idleMs < wallMs
+                ? [
+                    '- Going quiet ends the turn early, well before that: produce no output at',
+                    `  all for ${renderBudget(idleMs)} and the run is killed and reported as`,
+                    '  stalled. Ordinary work clears that on its own; a single step that will',
+                    '  be silent for longer is the one thing to break up.',
+                ]
+                : []),
+        ];
+    }
+    if (idleMs > 0) {
         return [
-            '- There is no fixed time limit on this turn, so work that genuinely takes',
-            '  a while is fine — finish it rather than cutting it short. But nothing you',
-            '  write is posted until the turn ends, and a long silence gets reported as a',
-            '  stalled run, so keep moving toward an answer rather than exploring',
-            '  indefinitely.',
+            '- There is no fixed time limit on this turn, so work that genuinely takes a',
+            '  while is fine — finish it rather than cutting it short. What is limited is',
+            `  silence: produce no output at all for ${renderBudget(idleMs)} and the run is`,
+            '  killed and reported as stalled. Ordinary work clears that on its own; a',
+            '  single step that will be quiet for longer than that is the one thing to',
+            '  break up. Nothing you write is posted until the turn ends, so keep moving',
+            '  toward an answer rather than exploring indefinitely.',
         ];
     }
     return [
-        `- You have ${renderBudget(timeoutMs)} for this whole turn. Past that you are killed`,
-        '  mid-thought and the person waiting gets nothing, so spend the budget on the',
-        '  work and leave yourself room to write the answer.',
+        '- There is no time limit on this turn and nothing local will stop it, so work',
+        '  that genuinely takes a while is fine — finish it rather than cutting it',
+        '  short. But nothing you write is posted until the turn ends, so a run that',
+        '  explores indefinitely is indistinguishable from one that crashed. Keep',
+        '  moving toward an answer.',
     ];
 }
 /**
@@ -187,7 +224,7 @@ export function buildPrompt(run, context) {
     // not buried under the tool advice: how long the agent has changes how it
     // should approach the work, so it has to be read before any of the "go and
     // look" bullets below.
-    ...timeBudgetLines(context.timeoutMs), 
+    ...timeBudgetLines(context.timeoutMs, context.idleTimeoutMs), 
     // Claude Code lazy-loads part of its catalog — WebSearch/WebFetch among
     // them — so a run that inspects its loaded tools concludes it cannot
     // browse and says so to a customer, when one ToolSearch call away it

package/dist/agent/run.d.ts

@@ -26,18 +26,36 @@ import type { spawn } from 'node:child_process';
 import WebSocket from 'ws';
 import type { AgentCredentials } from './credentials.js';
 /**
- * Default ceiling on one agent invocation.
+ * Default ceiling on one agent invocation: none.
  *
- * Two hours, up from five minutes. Five was a guess made when a run meant
- * "answer a mention", and it was wrong in the expensive direction: a paired
- * brain given a real coding task in production was killed at 300s, mid-edit,
- * and reported `timed out after 300000ms` to the person waiting. A coding
- * agent's unit of work is not a chat reply, and no local clock can tell a
- * wedged run from a productive one — the server's lease can, which is what
- * heartbeats are for. This is now a backstop against a genuinely stuck process
- * rather than a shape imposed on the work; `--timeout 0` removes it entirely.
+ * The wall clock kept being raised — five minutes, then two hours — because it
+ * was answering the wrong question. "How long has this run been going?" does
+ * not distinguish a wedged child from a productive one; it only distinguishes
+ * long work from short, and killing long work is precisely the failure the two
+ * previous defaults each produced in production. What the harness can actually
+ * observe is whether the child is *doing* anything, which is what
+ * {@link DEFAULT_IDLE_TIMEOUT_MS} watches.
+ *
+ * So a run is now bounded by three things, none of them a fixed duration:
+ * the inactivity watchdog (default 15 minutes of total silence), the server's
+ * lease on the run (heartbeats stop, the row is reaped), and the Stop button in
+ * ProhostAI (which reaches this machine on the next heartbeat). `--timeout`
+ * remains fully supported for anyone who wants a hard ceiling as well.
+ */
+export declare const DEFAULT_EXEC_TIMEOUT_MS = 0;
+/**
+ * Default silence window before a run is treated as stalled.
+ *
+ * Fifteen minutes is chosen against what real work looks like, not against
+ * what feels responsive: an agent mid-task emits stream events, tool calls and
+ * log lines continuously, so the gaps in a healthy run are seconds. The long
+ * tail that legitimately goes quiet is a single slow tool call — a test suite,
+ * a build, a big fetch — and fifteen minutes clears those comfortably while
+ * still catching the failure this exists for, a child wedged on a stdin prompt
+ * that heartbeats look perfectly healthy for and that burns the operator's
+ * tokens and their agent's availability indefinitely.
  */
-export declare const DEFAULT_EXEC_TIMEOUT_MS = 7200000;
+export declare const DEFAULT_IDLE_TIMEOUT_MS = 900000;
 export interface AgentRunOptions {
     /** Shell command that runs the agent, e.g. ``claude -p``. */
     exec: string;
@@ -46,8 +64,16 @@ export interface AgentRunOptions {
     url?: string;
     /** Machine name shown in the ProhostAI UI. Defaults to the OS hostname. */
     machine?: string;
-    /** Per-run execution timeout. ``0`` disables it — see `--timeout 0`. */
+    /**
+     * Per-run wall-clock ceiling. ``0`` disables it, and that is now the default
+     * — see {@link DEFAULT_EXEC_TIMEOUT_MS}.
+     */
     timeoutMs?: number;
+    /**
+     * How long a run may produce no output at all before it is killed. ``0``
+     * disables the watchdog — see {@link DEFAULT_IDLE_TIMEOUT_MS}.
+     */
+    idleTimeoutMs?: number;
     /** Print the reply that would be posted and make no writes. */
     dryRun?: boolean;
     /** Execute runs whose signature could not be verified. Off by default. */
@@ -120,6 +146,8 @@ interface PreparedMcp {
     mcpConfigPath?: string;
     /** Codex: entries in the single verified `mcp_servers` override. */
     codexMcpEntries?: string[];
+    /** Codex: verified non-`mcp_servers` overrides, e.g. plugins off. */
+    codexConfigOverrides?: string[];
     /** Credentials moved out of Codex's process argv. */
     execEnv?: NodeJS.ProcessEnv;
     /** ProhostAI tools are actually reachable from this invocation. */