@prohost/cli 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,91 @@ Versions follow [semver](https://semver.org/). Publishing is automated: merging
 a version bump to `main` triggers `.github/workflows/npm-publish-cli.yml`, which
 builds via `prepack`, runs the suite, publishes, and tags `cli-v<version>`.
 
+## 0.4.1
+
+Codex runs work again on machines with a Codex **plugin** installed.
+
+- **Plugin-provided MCP servers are now isolated instead of blocking the run.**
+  A plugin declared in `~/.codex/config.toml` — `[plugins."github@openai-curated"]`
+  — contributes an MCP server (`github`) that the per-server `mcp_servers`
+  disable cannot touch: it has no `mcp_servers` entry for `{enabled=false}` to
+  merge onto, so the override leaves a table with no transport and Codex
+  rejects the whole config with `invalid transport in mcp_servers.github`. The
+  isolation verifier correctly refused to start a run it could not prove was
+  sealed, which meant **every** message to a Codex-backed agent failed with
+  `MCP isolation could not be established`. Such servers are now shut off with
+  `-c features.plugins=false`, verified by re-listing exactly like every other
+  disable.
+- **Only when a plugin actually supplies a server.** An install whose plugins
+  contribute no MCP server issues byte-identical commands to 0.4.0 and keeps
+  its plugin skills and hooks; the switch is a bigger hammer than the problem
+  on those machines. Classic `mcp_servers` entries are still disabled
+  individually, and the ProhostAI server and any `extra-mcp.json` servers keep
+  working with plugins off.
+- **Nothing is trusted that wasn't verified.** Every per-plugin form that looks
+  like it should work — `plugins."github@openai-curated".enabled=false`, the
+  same written as a table, `.disabled=true`, a whole-table `plugins={…}` —
+  loads without error and changes nothing at all. A silent no-op is the worst
+  shape a security override can have, and only the re-list distinguishes it
+  from one that took.
+- **The failure message now carries the way out.** When a server still cannot
+  be disabled, the error names the remedy — remove it from
+  `~/.codex/config.toml`, or run the daemon with a dedicated `CODEX_HOME`
+  holding only `auth.json` — rather than leaving the operator with a run that
+  will not start and nothing to do about it.
+
+## 0.4.0
+
+The wall clock stops being the safety mechanism. 0.3.0 raised the run ceiling
+to two hours and added heartbeats — but a heartbeat proves the *daemon* is
+alive, not that the *work* is progressing. A child wedged on a stdin prompt or
+stuck in a loop heartbeats forever, looks healthy in the UI, burns the
+operator's tokens, and — because runs are serialized — makes the agent deaf to
+every other mention until the two-hour clock finally runs out. Meanwhile that
+same clock was killing runs that were doing fine.
+
+- **A run is killed when it goes silent, not when it goes long.** The new
+  inactivity watchdog kills a run that produces **no output at all** for 15
+  minutes (`--idle-timeout <seconds>`, `0` disables it). Any byte on stdout or
+  stderr resets the window, which covers all three brains: Claude Code's
+  stream-json events, Codex's output, and whatever a plain `--exec` command
+  prints. An agent that is working never trips it — the gaps in a healthy run
+  are seconds — while a wedged one is caught in minutes rather than hours. The
+  kill is the same SIGTERM → 5s → SIGKILL escalation a timeout or a cancel
+  uses, the partial answer is salvaged, and a session id recorded mid-run
+  survives, exactly as for a wall-clock kill. The failure reads
+  `no output for 15 minutes — treated as stalled; tune with --idle-timeout
+  <seconds> (0 = disabled)`, because the server echoes it into the thread.
+- **`--timeout` now defaults to `0`: no wall-clock limit.** It remains fully
+  supported for anyone who wants a hard ceiling, but it is no longer the
+  backstop and no longer imposes a shape on the work. The safety story is the
+  watchdog (15 minutes of silence), the server's lease on the run, and the Stop
+  button in ProhostAI.
+- **The prompt tells the agent which regime it is in.** Three shapes now: a
+  named wall-clock budget, the watchdog alone ("no fixed time limit… what is
+  limited is silence"), or neither. The middle one is the default and is the
+  point — a silence limit is advice an agent can act on, where a duration is
+  just an instruction to hurry.
+- **A killed plain `--exec` command salvages its output too.** Claude Code runs
+  already reported the tail of the answer they were writing, parsed out of the
+  stream; a plain command now reports the tail of its stdout instead of
+  nothing, since for a plain command the stdout *is* the answer. Deliberately
+  not extended to the shaped brains: their structured streams carry the raw
+  output of every local command the agent ran, and this string is echoed into a
+  workspace thread.
+- **Both duration flags reject values a timer cannot hold** — anything over
+  2^31-1 ms (~24.9 days), where `setTimeout` silently fires after 1 ms instead
+  and would kill the first run on the spot. `0` remains how both flags spell
+  "no limit". A flag typed with no value at all (`--timeout`, or `--timeout -1`,
+  which the parser reads as two flags) is likewise an error now rather than
+  silently applying the default.
+- **`--idle-timeout` is passed through `install-daemon`** into the launchd
+  plist and systemd unit, like `--timeout`, including an explicit `0`.
+- **The `heartbeat` block in `agent.run_requested` is used when present.** A
+  server that spells out where heartbeats go is followed verbatim; one that
+  doesn't gets the 0.3.0 behaviour unchanged — derive from the completion path,
+  falling back to the documented one. No coordinated upgrade either way.
+
 ## 0.3.0
 
 Long runs. Every change here comes out of one production failure: a paired

package/README.md

@@ -301,16 +301,47 @@ config layer: probing where the harness was launched and then running in
 `$PROHOST_HOME/workspace` or an explicit `--workdir` would certify one MCP
 inventory and execute another.
 
-**The override is checked before it is used**, and one case needs it.
-`{enabled=false}` merges onto a server's existing definition, and a server
-contributed by a **plugin** has no `mcp_servers` entry to merge onto — so the
-override leaves a table with no transport and Codex refuses to start at all.
-The CLI therefore runs the disable past `codex mcp list` first, falls back to
-checking each server individually if the combined form is rejected, and then
-verifies the exact final override. If any configured server cannot be disabled,
-or if the final listing does not show the ProhostAI server and every accepted
-extra enabled, the run fails before Codex starts. Remove that server/plugin or
-use Claude Code.
+**The override is checked before it is used.** `{enabled=false}` merges onto a
+server's existing definition, so an entry Codex cannot make sense of takes the
+whole config down rather than disabling anything. The CLI therefore runs the
+disable past `codex mcp list` first, falls back to checking each server
+individually if the combined form is rejected, and then verifies the exact final
+override. If any configured server cannot be disabled, or if the final listing
+does not show the ProhostAI server and every accepted extra enabled, the run
+fails before Codex starts.
+
+**Codex plugins get a second mechanism, because `mcp_servers` cannot reach
+them.** A plugin declared in your config — say `[plugins."github@openai-curated"]`
+— contributes an MCP server (`github`) that has *no* `mcp_servers` entry for
+`{enabled=false}` to merge onto, so forcing one leaves a table with no transport
+and Codex rejects the config outright: `invalid transport in mcp_servers.github`.
+Nothing in `codex mcp list --json` marks a server as plugin-provided, so the CLI
+measures instead of guessing: it lists again with plugins off, and the names that
+vanish were the plugin's. Those are shut off for the run with
+`-c features.plugins=false`, verified by re-listing like any other disable.
+
+This is applied **only when a plugin actually supplies an MCP server**. Plugins
+also carry skills and hooks, and switching the system off costs you those, so an
+install whose plugins contribute no server keeps everything and gets exactly the
+command line it got before. Your own `prohost` server and your `extra-mcp.json`
+servers are unaffected either way. Per-plugin spellings are deliberately not
+used: `plugins."github@openai-curated".enabled=false` and every variant of it
+load without error and disable nothing at all, which is precisely the kind of
+override the verification step exists to catch.
+
+**If a server still cannot be disabled**, the run fails before Codex starts and
+names it. Two ways out: remove that server or plugin from `~/.codex/config.toml`,
+or give the daemon a `CODEX_HOME` of its own that holds only `auth.json` —
+
+```bash
+mkdir -p ~/.prohost/codex-home
+cp ~/.codex/auth.json ~/.prohost/codex-home/auth.json
+CODEX_HOME=~/.prohost/codex-home prohost agent run --exec 'codex exec'
+```
+
+A dedicated `CODEX_HOME` is the cleanest answer in general: the agent inherits
+your login and nothing else, your own Codex setup is untouched, and no future
+plugin or server you install can change what a paired run can reach.
 
 If the enumeration fails outright — an older Codex without `mcp list --json`,
 or output the CLI doesn't recognise — the run fails before Codex starts. A
@@ -400,7 +431,8 @@ same judgement.
 | Flag | Default | What it does |
 | --- | --- | --- |
 | `--exec` | *(required)* | Command to run for each requested run. Prompt arrives on stdin. |
-| `--timeout` | `7200` | Seconds one run may take before the command is killed. `0` removes the local cap entirely — see "Long runs". |
+| `--idle-timeout` | `900` | Seconds a run may produce **no output at all** before it is treated as stalled and killed. Any byte on stdout or stderr resets it. `0` disables it — see "Long runs". |
+| `--timeout` | `0` | Seconds one run may take before the command is killed, however busy it is. `0` — the default — means no wall-clock limit. Set it if you want a hard ceiling as well. |
 | `--dry-run` | off | Print the reply that would be posted; write nothing. |
 | `--workdir` | `~/.prohost/workspace` | Working directory for the command. See "Where your agent runs". |
 | `--cwd` | — | Deprecated alias for `--workdir`. |
@@ -415,9 +447,18 @@ A paired brain is often asked to do work, not just answer — write the change,
 run the tests, come back. That takes minutes or hours, and the harness is built
 for it:
 
-- **Two hours by default**, and `--timeout 0` removes the local cap entirely.
-  The timeout is a backstop against a genuinely wedged process, not a shape for
-  the work.
+- **There is no wall-clock limit by default.** A run ends when the agent ends
+  it. `--timeout <seconds>` still imposes a hard ceiling if you want one, but
+  the default is `0`, because "this has been going a while" was never evidence
+  that anything was wrong — it only ever distinguished long work from short.
+- **A stalled run is killed after 15 minutes of silence** (`--idle-timeout`).
+  This is the backstop the wall clock used to be, asking a question a clock
+  can't: is the child *doing* anything? Any byte on stdout or stderr resets the
+  window, so an agent that is working — streaming events, calling tools,
+  logging — never trips it, while one wedged on a stdin prompt is caught even
+  though its heartbeats look perfectly healthy. The failed run reports
+  `no output for 15 minutes — treated as stalled`, so the person waiting sees
+  what happened rather than a silence. `--idle-timeout 0` disables it.
 - **Heartbeats keep it alive.** Every run this CLI has accepted — the one
   executing *and* any queued behind it — is reported to ProhostAI once a minute,
   which is what stops the server reaping a run that is still being worked on.

package/dist/agent/codex.d.ts

@@ -190,7 +190,7 @@ export type CommandRunner = (command: string, cwd?: string) => {
  * nothing to disable, while `null` means we do not know, and a run that cannot
  * enumerate must say so rather than claim an isolation it did not apply.
  */
-export declare function listMcpServers(binary: string, runner: CommandRunner, override?: string, cwd?: string): CodexMcpServer[] | null;
+export declare function listMcpServers(binary: string, runner: CommandRunner, overrides?: string | string[], cwd?: string): CodexMcpServer[] | null;
 /** Disable entries proven to work, and the servers that could not be disabled. */
 export interface VerifiedDisable {
     entries: string[];
@@ -216,8 +216,81 @@ export interface VerifiedDisable {
  * `failed` is the honest part. A server that cannot be disabled is still
  * reachable from the run, and the caller has to say so out loud rather than
  * report an isolation it only partly achieved.
+ *
+ * `baseOverrides` are config overrides the run will also carry — in practice
+ * {@link PLUGINS_DISABLED_OVERRIDE}. They have to be present on every probe
+ * here, because "does this entry disable this server" has a different answer
+ * under a different config, and the answer that matters is the one for the
+ * config the run actually gets.
  */
-export declare function disableEntriesThatLoad(binary: string, runner: CommandRunner, targets: string[], cwd?: string): VerifiedDisable;
+export declare function disableEntriesThatLoad(binary: string, runner: CommandRunner, targets: string[], cwd?: string, baseOverrides?: string[]): VerifiedDisable;
+/**
+ * The one override that switches off Codex's plugin system for a single run.
+ *
+ * Needed because a Codex **plugin** contributes MCP servers that the
+ * `mcp_servers` mechanism cannot touch. `[plugins."github@openai-curated"]` in
+ * `~/.codex/config.toml` puts a `github` server in `codex mcp list` that has no
+ * `mcp_servers` entry to merge `{enabled=false}` onto, so the override defines
+ * a table with no transport and Codex rejects the entire config: `invalid
+ * transport in mcp_servers.github`. That is the failure this harness shipped
+ * with — fail-closed and correct, but it meant no run at all on any machine
+ * with a Codex plugin installed.
+ *
+ * Measured against `codex-cli 0.146.0`, and the measurements are the reason
+ * this is a whole-system switch rather than the per-plugin one it should be:
+ *
+ * - `plugins."github@openai-curated".enabled=false`, the same spelled as a
+ *   table, `plugins.github.enabled=false`, `.disabled=true`, `.mcp_servers={}`
+ *   and a whole-table `plugins={…}` **all load without error and change
+ *   nothing** — the server is still listed, still enabled. A silent no-op is
+ *   the worst shape a security override can have, and it is exactly why
+ *   {@link disableEntriesThatLoad} verifies instead of trusting.
+ * - `features.plugins` is a *stable* Codex feature, on by default. Setting it
+ *   false removes plugin-contributed servers from `codex mcp list --json`
+ *   **entirely** (they are absent, not `enabled: false`) while leaving classic
+ *   `mcp_servers` entries and this harness's own `prohost` server untouched.
+ * - The effect is real at runtime, not just in the listing: the same run asked
+ *   for its tool list reported 28 `mcp__codex_apps__*` tools without this
+ *   override and none with it.
+ * - `--ignore-user-config` also works, and is still the wrong tool: it drops
+ *   the operator's model, profile and sandbox settings too.
+ *
+ * Applied only when a plugin actually contributes a server (see
+ * {@link isolateConfiguredServers}). Plugins carry skills and hooks as well, so
+ * an install whose plugins contribute no MCP servers keeps all of that.
+ */
+export declare const PLUGINS_DISABLED_OVERRIDE = "features.plugins=false";
+/** A verified isolation: what to pass Codex, and what could not be shut off. */
+export interface VerifiedIsolation {
+    /** `mcp_servers` fragments, for the single {@link mcpServersOverride}. */
+    entries: string[];
+    /** Whole-config `-c` overrides the run needs on top. Usually empty. */
+    configOverrides: string[];
+    /** Servers still reachable from the run. Empty is the outcome we want. */
+    failed: string[];
+}
+/**
+ * Shut off every server the operator's install has, whatever supplies it.
+ *
+ * Two mechanisms, because Codex has two kinds of MCP server and one lever does
+ * not move both: `mcp_servers` entries are disabled individually
+ * ({@link disableEntriesThatLoad}), plugin-contributed ones only by
+ * {@link PLUGINS_DISABLED_OVERRIDE}. Nothing in `codex mcp list --json` says
+ * which is which — a plugin's server is reported with the same fields as any
+ * other, no source or plugin marker anywhere in the object — so provenance is
+ * *measured* rather than read: list again with plugins off, and the names that
+ * vanished were the plugin's.
+ *
+ * The classic path is tried first and, when it succeeds, returned untouched
+ * with no extra override. So an install with no plugin-backed servers issues
+ * byte-identical commands to the version before plugins were handled at all,
+ * and pays exactly one probe as before.
+ *
+ * Failing to shut a server off is reported, never worked around. A plugin
+ * server that survives even `features.plugins=false` is a mechanism we do not
+ * understand yet, and a run that cannot prove the boundary must not start.
+ */
+export declare function isolateConfiguredServers(binary: string, runner: CommandRunner, targets: string[], cwd?: string): VerifiedIsolation;
 /**
  * The `codex` binary out of the host's `--exec` command.
  *
@@ -267,6 +340,14 @@ export interface CodexFlags {
      * {@link buildMcpOverride} for what happens when they don't.
      */
     mcpEntries?: string[];
+    /**
+     * Whole-config `-c` overrides that are not `mcp_servers` — in practice
+     * {@link PLUGINS_DISABLED_OVERRIDE}, when the operator has a plugin that
+     * contributes MCP servers. They precede the `mcp_servers` override for the
+     * same reason they do in the verifier: the run has to be handed the same
+     * overrides in the same order the probe certified.
+     */
+    configOverrides?: string[];
     /**
      * Run with approvals and the sandbox bypassed. Default ON — see
      * {@link codexCommand}. Set false by `agent run --safe-tools`.

package/dist/agent/codex.js

@@ -485,8 +485,14 @@ export function mcpServersOverride(entries) {
  * nothing to disable, while `null` means we do not know, and a run that cannot
  * enumerate must say so rather than claim an isolation it did not apply.
  */
-export function listMcpServers(binary, runner, override, cwd) {
-    const command = override ? `${binary} mcp list --json -c ${shellQuote(override, process.platform)}` : `${binary} mcp list --json`;
+export function listMcpServers(binary, runner, overrides, cwd) {
+    // Several overrides rather than one, because they land in different config
+    // tables: `mcp_servers={…}` cannot also carry `features.plugins=false`. Codex
+    // applies repeated `-c` in order, and the run must be given this same list in
+    // this same order or the probe certifies a config the run does not get.
+    const list = overrides === undefined ? [] : typeof overrides === 'string' ? [overrides] : overrides;
+    const flags = list.map((value) => ` -c ${shellQuote(value, process.platform)}`).join('');
+    const command = `${binary} mcp list --json${flags}`;
     let result;
     try {
         result = runner(command, cwd);
@@ -537,15 +543,21 @@ export function listMcpServers(binary, runner, override, cwd) {
  * `failed` is the honest part. A server that cannot be disabled is still
  * reachable from the run, and the caller has to say so out loud rather than
  * report an isolation it only partly achieved.
+ *
+ * `baseOverrides` are config overrides the run will also carry — in practice
+ * {@link PLUGINS_DISABLED_OVERRIDE}. They have to be present on every probe
+ * here, because "does this entry disable this server" has a different answer
+ * under a different config, and the answer that matters is the one for the
+ * config the run actually gets.
  */
-export function disableEntriesThatLoad(binary, runner, targets, cwd) {
+export function disableEntriesThatLoad(binary, runner, targets, cwd, baseOverrides = []) {
     if (targets.length === 0)
         return { entries: [], failed: [] };
     const disabled = (names) => {
         const override = mcpServersOverride(disableMcpEntries(names));
         if (!override)
             return [];
-        const listing = listMcpServers(binary, runner, override, cwd);
+        const listing = listMcpServers(binary, runner, [...baseOverrides, override], cwd);
         // A config that does not load disables nothing, and a server the listing
         // still reports as enabled was not disabled whatever the override said.
         if (listing === null)
@@ -570,6 +582,91 @@ export function disableEntriesThatLoad(binary, runner, targets, cwd) {
         failed: targets.filter((name) => !verified.includes(name)),
     };
 }
+/**
+ * The one override that switches off Codex's plugin system for a single run.
+ *
+ * Needed because a Codex **plugin** contributes MCP servers that the
+ * `mcp_servers` mechanism cannot touch. `[plugins."github@openai-curated"]` in
+ * `~/.codex/config.toml` puts a `github` server in `codex mcp list` that has no
+ * `mcp_servers` entry to merge `{enabled=false}` onto, so the override defines
+ * a table with no transport and Codex rejects the entire config: `invalid
+ * transport in mcp_servers.github`. That is the failure this harness shipped
+ * with — fail-closed and correct, but it meant no run at all on any machine
+ * with a Codex plugin installed.
+ *
+ * Measured against `codex-cli 0.146.0`, and the measurements are the reason
+ * this is a whole-system switch rather than the per-plugin one it should be:
+ *
+ * - `plugins."github@openai-curated".enabled=false`, the same spelled as a
+ *   table, `plugins.github.enabled=false`, `.disabled=true`, `.mcp_servers={}`
+ *   and a whole-table `plugins={…}` **all load without error and change
+ *   nothing** — the server is still listed, still enabled. A silent no-op is
+ *   the worst shape a security override can have, and it is exactly why
+ *   {@link disableEntriesThatLoad} verifies instead of trusting.
+ * - `features.plugins` is a *stable* Codex feature, on by default. Setting it
+ *   false removes plugin-contributed servers from `codex mcp list --json`
+ *   **entirely** (they are absent, not `enabled: false`) while leaving classic
+ *   `mcp_servers` entries and this harness's own `prohost` server untouched.
+ * - The effect is real at runtime, not just in the listing: the same run asked
+ *   for its tool list reported 28 `mcp__codex_apps__*` tools without this
+ *   override and none with it.
+ * - `--ignore-user-config` also works, and is still the wrong tool: it drops
+ *   the operator's model, profile and sandbox settings too.
+ *
+ * Applied only when a plugin actually contributes a server (see
+ * {@link isolateConfiguredServers}). Plugins carry skills and hooks as well, so
+ * an install whose plugins contribute no MCP servers keeps all of that.
+ */
+export const PLUGINS_DISABLED_OVERRIDE = 'features.plugins=false';
+/**
+ * Shut off every server the operator's install has, whatever supplies it.
+ *
+ * Two mechanisms, because Codex has two kinds of MCP server and one lever does
+ * not move both: `mcp_servers` entries are disabled individually
+ * ({@link disableEntriesThatLoad}), plugin-contributed ones only by
+ * {@link PLUGINS_DISABLED_OVERRIDE}. Nothing in `codex mcp list --json` says
+ * which is which — a plugin's server is reported with the same fields as any
+ * other, no source or plugin marker anywhere in the object — so provenance is
+ * *measured* rather than read: list again with plugins off, and the names that
+ * vanished were the plugin's.
+ *
+ * The classic path is tried first and, when it succeeds, returned untouched
+ * with no extra override. So an install with no plugin-backed servers issues
+ * byte-identical commands to the version before plugins were handled at all,
+ * and pays exactly one probe as before.
+ *
+ * Failing to shut a server off is reported, never worked around. A plugin
+ * server that survives even `features.plugins=false` is a mechanism we do not
+ * understand yet, and a run that cannot prove the boundary must not start.
+ */
+export function isolateConfiguredServers(binary, runner, targets, cwd) {
+    const direct = disableEntriesThatLoad(binary, runner, targets, cwd);
+    if (direct.failed.length === 0)
+        return { ...direct, configOverrides: [] };
+    // Something resisted. Ask whether turning the plugin system off accounts for
+    // it, rather than assuming the survivors are plugin-backed because they look
+    // like it.
+    const withPluginsOff = listMcpServers(binary, runner, PLUGINS_DISABLED_OVERRIDE, cwd);
+    // The override does not load, so it disables nothing and we know nothing.
+    if (withPluginsOff === null)
+        return { ...direct, configOverrides: [] };
+    const remaining = new Set(withPluginsOff.map((server) => server.name));
+    const removedByPluginsOff = direct.failed.filter((name) => !remaining.has(name));
+    // Plugins were not the problem. Report what the classic path found, so the
+    // operator is told about the real survivor instead of a plugin red herring.
+    if (removedByPluginsOff.length === 0)
+        return { ...direct, configOverrides: [] };
+    // Re-verify the classic disables *under* the plugins-off override. They were
+    // proven against a different config, and a proof about a config the run does
+    // not get is not a proof.
+    const classic = targets.filter((name) => remaining.has(name));
+    const verified = disableEntriesThatLoad(binary, runner, classic, cwd, [PLUGINS_DISABLED_OVERRIDE]);
+    return {
+        entries: verified.entries,
+        configOverrides: [PLUGINS_DISABLED_OVERRIDE],
+        failed: verified.failed,
+    };
+}
 /**
  * The `codex` binary out of the host's `--exec` command.
  *
@@ -705,6 +802,8 @@ export function codexCommand(base, flags = {}) {
     if (!gated && !has(words, ...BYPASS_FLAGS)) {
         parts.push('--yolo');
     }
+    for (const value of flags.configOverrides ?? [])
+        parts.push('-c', quote(value));
     const override = mcpServersOverride(flags.mcpEntries ?? []);
     if (override)
         parts.push('-c', quote(override));

package/dist/agent/command.d.ts

@@ -5,6 +5,30 @@
  * (and testable) as plain async functions with no argv or process concerns.
  */
 type Flags = Record<string, string | boolean>;
+/** Returned by {@link parseSeconds} for a value that isn't a duration. */
+export declare const INVALID_DURATION: unique symbol;
+/**
+ * Read a duration flag's value. Pure — exported so it can be tested without a
+ * process to write errors to.
+ *
+ * Returns ``undefined`` only when the flag was genuinely absent (the harness
+ * then applies its own default) and {@link INVALID_DURATION} for anything that
+ * is not a non-negative, finite number of seconds.
+ *
+ * ``0`` is legal for both flags that use this, and means "no limit of this
+ * kind". For `--timeout` 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.
+ *
+ * Takes the raw flag value rather than a string, because "the operator typed
+ * this flag and got it wrong" and "the operator did not type this flag" have
+ * to be told apart. `--timeout` with nothing after it, and `--timeout -1` —
+ * which the argument parser reads as two flags, since a value cannot begin
+ * with `-` — both arrive here as `true`. Treated as absent, they would apply
+ * the default silently and leave someone believing they had set a limit they
+ * had not.
+ */
+export declare function parseSeconds(raw: string | boolean | undefined): number | undefined | typeof INVALID_DURATION;
 /** Dispatch an ``agent`` subcommand. Returns the process exit code. */
 export declare function runAgent(subcommand: string | undefined, flags: Flags, printHelp: () => void): Promise<number>;
 export {};

package/dist/agent/command.js

@@ -12,7 +12,7 @@ import { fileURLToPath } from 'node:url';
 import { agentLogPath, buildSystemdUnit, harnessArguments, installLaunchdDaemon, launchdLabel, uninstallLaunchdDaemon, } from './daemon.js';
 import { PairError, runPair } from './pair.js';
 import { CredentialsMissingError, ensureWorkspace, loadCredentials, prohostHome } from './credentials.js';
-import { DEFAULT_EXEC_TIMEOUT_MS, runAgentHarness } from './run.js';
+import { DEFAULT_EXEC_TIMEOUT_MS, DEFAULT_IDLE_TIMEOUT_MS, runAgentHarness } from './run.js';
 function flagString(flags, name) {
     const value = flags[name];
     return typeof value === 'string' ? value : undefined;
@@ -28,33 +28,92 @@ function flagString(flags, name) {
 function requestedWorkdir(flags) {
     return flagString(flags, 'workdir') ?? flagString(flags, 'cwd');
 }
-/** Returned by {@link parseTimeoutSeconds} for a value that isn't a timeout. */
-const INVALID_TIMEOUT = Symbol('invalid-timeout');
+/** Returned by {@link parseSeconds} for a value that isn't a duration. */
+export const INVALID_DURATION = Symbol('invalid-duration');
 /**
- * Read `--timeout`, complaining once for both commands that take it.
+ * Longest delay a timer can hold, in milliseconds — 2^31-1, just under 24.9
+ * days.
  *
- * Returns ``undefined`` when the flag was absent (the harness applies its own
- * default) and {@link INVALID_TIMEOUT} after printing the error.
+ * The bound is `setTimeout`'s, not ours: a delay above this overflows the timer
+ * and Node **fires it after 1 ms instead**. So `--idle-timeout 2592000` ("give
+ * it thirty days") would not merely be ignored, it would kill the very first
+ * run on the spot and report it as stalled — the exact opposite of what was
+ * asked for, with nothing to explain it. Rejected at the flag rather than
+ * clamped, because anyone typing a number this large means "no limit", and both
+ * flags already spell that `0`.
  *
- * ``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.
+ * Checked against the *converted* value rather than against seconds, because
+ * the flags take fractions: `--timeout 2147483.9` is under any whole-second
+ * ceiling and still overflows once multiplied out.
  */
-function parseTimeoutSeconds(flags) {
-    const raw = flagString(flags, 'timeout');
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/**
+ * Read a duration flag's value. Pure — exported so it can be tested without a
+ * process to write errors to.
+ *
+ * Returns ``undefined`` only when the flag was genuinely absent (the harness
+ * then applies its own default) and {@link INVALID_DURATION} for anything that
+ * is not a non-negative, finite number of seconds.
+ *
+ * ``0`` is legal for both flags that use this, and means "no limit of this
+ * kind". For `--timeout` 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.
+ *
+ * Takes the raw flag value rather than a string, because "the operator typed
+ * this flag and got it wrong" and "the operator did not type this flag" have
+ * to be told apart. `--timeout` with nothing after it, and `--timeout -1` —
+ * which the argument parser reads as two flags, since a value cannot begin
+ * with `-` — both arrive here as `true`. Treated as absent, they would apply
+ * the default silently and leave someone believing they had set a limit they
+ * had not.
+ */
+export function parseSeconds(raw) {
     if (raw === undefined)
         return undefined;
+    // An empty string is the `--timeout ''` case, and `Number('')` is 0 — which
+    // would quietly read as "no limit" rather than as the typo it is.
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return INVALID_DURATION;
     const seconds = Number(raw);
-    if (!Number.isFinite(seconds) || seconds < 0) {
+    if (!Number.isFinite(seconds) || seconds < 0 || seconds * 1000 > MAX_TIMER_DELAY_MS) {
+        return INVALID_DURATION;
+    }
+    return seconds;
+}
+/**
+ * Read `--timeout`, complaining once for both commands that take it.
+ *
+ * The wall-clock ceiling is opt-in now (`DEFAULT_EXEC_TIMEOUT_MS` is 0), so an
+ * absent flag means "no ceiling" rather than "two hours".
+ */
+function parseTimeoutSeconds(flags) {
+    const parsed = parseSeconds(flags.timeout);
+    if (parsed === INVALID_DURATION) {
         // 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;
+        process.stderr.write('--timeout must be a positive number of seconds under 2147484 (about 24 days), ' +
+            'or 0 for no local limit.\n');
     }
-    return seconds;
+    return parsed;
+}
+/**
+ * Read `--idle-timeout` — how long a run may produce nothing before it is
+ * treated as stalled.
+ *
+ * Validated in both commands for the same reason `--timeout` is: baked into a
+ * plist, a bad value makes every launch exit on this check and KeepAlive
+ * restart it forever.
+ */
+function parseIdleTimeoutSeconds(flags) {
+    const parsed = parseSeconds(flags['idle-timeout']);
+    if (parsed === INVALID_DURATION) {
+        process.stderr.write('--idle-timeout must be a positive number of seconds under 2147484 (about 24 days), ' +
+            'or 0 to disable the stall watchdog.\n');
+    }
+    return parsed;
 }
 /**
  * Environment the daemon must be given explicitly.
@@ -129,7 +188,10 @@ async function installDaemonCommand(flags) {
     // plist makes every launch exit on that same validation and KeepAlive restart
     // it forever.
     const timeoutSeconds = parseTimeoutSeconds(flags);
-    if (timeoutSeconds === INVALID_TIMEOUT)
+    if (timeoutSeconds === INVALID_DURATION)
+        return 1;
+    const idleTimeoutSeconds = parseIdleTimeoutSeconds(flags);
+    if (idleTimeoutSeconds === INVALID_DURATION)
         return 1;
     // Absolute, and created now. A supervisor does not inherit the installing
     // shell's current directory, so a relative `--workdir .` copied verbatim into
@@ -151,6 +213,7 @@ async function installDaemonCommand(flags) {
         exec,
         workdir,
         timeoutSeconds,
+        idleTimeoutSeconds,
         machine: flagString(flags, 'machine'),
         url: flagString(flags, 'url'),
         allowUnverified: flags['allow-unverified'] === true,
@@ -224,7 +287,10 @@ async function runCommand(flags) {
     if (!credentials)
         return 1;
     const parsedTimeout = parseTimeoutSeconds(flags);
-    if (parsedTimeout === INVALID_TIMEOUT)
+    if (parsedTimeout === INVALID_DURATION)
+        return 1;
+    const parsedIdleTimeout = parseIdleTimeoutSeconds(flags);
+    if (parsedIdleTimeout === INVALID_DURATION)
         return 1;
     // First signal stops accepting work and lets the in-flight run finish
     // reporting itself (so the server doesn't wait on a run we abandoned); a
@@ -248,6 +314,7 @@ async function runCommand(flags) {
             machine: flagString(flags, 'machine'),
             cwd: requestedWorkdir(flags),
             timeoutMs: parsedTimeout === undefined ? DEFAULT_EXEC_TIMEOUT_MS : parsedTimeout * 1000,
+            idleTimeoutMs: parsedIdleTimeout === undefined ? DEFAULT_IDLE_TIMEOUT_MS : parsedIdleTimeout * 1000,
             dryRun: flags['dry-run'] === true,
             allowUnverified: flags['allow-unverified'] === true,
             // Two spellings for the same opt-out: `--safe-tools` says what you get,