@prohost/cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,58 @@ 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.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

@@ -400,7 +400,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 +416,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/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,

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. */

package/dist/agent/run.js

@@ -26,7 +26,7 @@ import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import WebSocket from 'ws';
 import { completeRun, postReply } from './api.js';
-import { claudeCommand, isClaudeExec, looksLikeResumeFailure, readClaudeStream, writeMcpConfig, } from './claude.js';
+import { MAX_SALVAGE_CHARS, claudeCommand, isClaudeExec, looksLikeResumeFailure, readClaudeStream, writeMcpConfig, } from './claude.js';
 import { MCP_API_KEY_ENV_VAR, codexBinary, codexCommand, codexMcpInventoryFlag, codexProfileName, codexShellSyntax, disableEntriesThatLoad, extraMcpEntries, isCodexExec, listMcpServers, mcpServersOverride, prohostMcpEntry, looksLikeCodexResumeFailure, parseCodexOutput, } from './codex.js';
 import { EXTRA_MCP_FILENAME, loadExtraMcpServers } from './extras.js';
 import { MCP_SERVER_NAME, MCP_TOOL_PATTERN } from './mcp.js';
@@ -41,18 +41,36 @@ import { verifySignature } from './signature.js';
 import { isWebhookEvent } from '../forward.js';
 import { DEFAULT_WS_URL } from '../listen.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 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 const DEFAULT_EXEC_TIMEOUT_MS = 7_200_000;
+export const DEFAULT_IDLE_TIMEOUT_MS = 900_000;
 /** Reconnect backoff — full jitter between ``BASE`` and the current cap. */
 const RECONNECT_BASE_DELAY_MS = 1_000;
 const RECONNECT_MAX_DELAY_MS = 30_000;
@@ -365,6 +383,25 @@ function defaultProbe(command, cwd) {
     });
     return { status: result.status, stdout: result.stdout ?? '' };
 }
+/**
+ * What a killed plain command salvages: the last thing it printed.
+ *
+ * The streaming reader salvages the last thing the *agent* said, having parsed
+ * it out of the event stream. There is no parsing to do for a plain `--exec`
+ * command — its stdout is its reply — so its rolling tail is the same evidence
+ * reached the other way: what the run had produced before it stopped producing
+ * anything.
+ *
+ * Bounded to the same {@link MAX_SALVAGE_CHARS} for the same reason: the
+ * completion `error` this ends up in is capped server-side, and it has a stderr
+ * tail to carry as well.
+ */
+function partialStdout(tail) {
+    const text = tail.trim();
+    if (!text)
+        return undefined;
+    return text.length > MAX_SALVAGE_CHARS ? text.slice(-MAX_SALVAGE_CHARS) : text;
+}
 /**
  * Run the agent command once and turn its output into a reply.
  *
@@ -380,10 +417,14 @@ async function runTurn(run, prompt, options, runtime, mcp, control, log) {
     // share one deadline, which costs the retry nothing in practice — a rejected
     // `--resume` fails in milliseconds, long before any of the budget is spent.
     const budgetMs = options.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS;
-    // `--timeout 0`: no local ceiling at all. The run then ends when the agent
-    // ends it, when somebody cancels it, or when the server stops renewing its
-    // lease — all of which are better judges of "stuck" than a fixed clock.
+    // `--timeout 0`, and the default: no wall-clock ceiling at all. The run then
+    // ends when the agent ends it, when the watchdog below finds it silent, when
+    // somebody cancels it, or when the server stops renewing its lease — all of
+    // which are better judges of "stuck" than a fixed clock.
     const capped = budgetMs > 0;
+    // Not shared between attempts the way the wall clock is: the watchdog bounds
+    // silence, and a fresh attempt starts a fresh silence.
+    const idleMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
     const startedAt = Date.now();
     const remainingMs = () => budgetMs - (Date.now() - startedAt);
     const timeLeft = () => !capped || remainingMs() > 0;
@@ -398,6 +439,16 @@ async function runTurn(run, prompt, options, runtime, mcp, control, log) {
     let recordedSession;
     /** The reader for the attempt currently running, if this brain streams. */
     let stream;
+    /**
+     * Rolling tail of a plain command's stdout — the last thing it printed.
+     *
+     * Kept as the output arrives rather than sliced off the captured `stdout` at
+     * the end, because capture is bounded at {@link MAX_OUTPUT_CHARS} from the
+     * *front*: a chatty command that overran that and then stalled would
+     * otherwise salvage half a megabyte of stale opening output and call it the
+     * unfinished answer.
+     */
+    let tail = '';
     /**
      * Act on what the stream has said so far.
      *
@@ -438,10 +489,12 @@ async function runTurn(run, prompt, options, runtime, mcp, control, log) {
         // session, and inheriting the failed attempt's id would resume nothing.
         const reader = runtime.brain === 'claude' ? readClaudeStream() : undefined;
         stream = reader;
+        tail = '';
         return execAgent({
             command,
             prompt,
             timeoutMs: capped ? Math.max(1, remainingMs()) : 0,
+            idleTimeoutMs: idleMs,
             cwd: runtime.workdir,
             env: mcp.execEnv,
             spawnImpl: options.spawnImpl,
@@ -451,7 +504,11 @@ async function runTurn(run, prompt, options, runtime, mcp, control, log) {
                     reader.push(chunk);
                     observe(reader);
                 }
-                : undefined,
+                : runtime.brain === 'plain'
+                    ? (chunk) => {
+                        tail = (tail + chunk).slice(-MAX_SALVAGE_CHARS);
+                    }
+                    : undefined,
         });
     };
     // Wall clock for the whole turn, retry included — what the operator waited,
@@ -462,10 +519,28 @@ async function runTurn(run, prompt, options, runtime, mcp, control, log) {
     }
     const failure = (result) => {
         // A killed run has no reply, but it usually has most of one. Reporting the
-        // tail of what the agent was writing turns "timed out after 7200000ms" into
+        // tail of what the agent was writing turns "no output for 15 minutes" into
         // something the person waiting can act on — and it is the only trace left
-        // of however many hours of work.
-        const salvaged = result.timedOut || result.cancelled ? stream?.salvage() : undefined;
+        // of however many hours of work. A stalled run is the case this matters
+        // most for: the last thing it said is the best clue to what it stalled on.
+        // A plain command has no stream to salvage a parsed answer from, but its
+        // stdout *is* its answer by contract — so the tail of what it managed to
+        // print is the same evidence, reached the other way. Without this a stalled
+        // plain run reports nothing but the fact that it stalled.
+        //
+        // Deliberately NOT extended to the shaped brains. Both are run with
+        // structured output (`--output-format stream-json`, `--json`), whose
+        // stream carries the agent's reasoning and the raw output of every local
+        // command and tool call it made — which `readClaudeStream`/
+        // `parseCodexOutput` exist to filter out. This string is persisted in the
+        // completion and echoed into a workspace thread, so tailing that stream
+        // raw would publish local shell output, and whatever was in it, to
+        // everyone who can read the conversation. A shaped brain whose parser
+        // salvaged nothing salvages nothing.
+        const killed = result.timedOut || result.idleTimedOut || result.cancelled;
+        const salvaged = killed
+            ? (stream?.salvage() ?? (runtime.brain === 'plain' ? partialStdout(tail) : undefined))
+            : undefined;
         // The stderr tail yields room when there is a salvaged answer to carry: the
         // completion `error` is capped server-side, and of the two, what the agent
         // was saying beats the last 500 characters of its logging.
@@ -525,7 +600,11 @@ async function runTurn(run, prompt, options, runtime, mcp, control, log) {
         result = await exec(build());
     }
     if (!result.ok) {
-        if (!result.timedOut && !result.cancelled)
+        // A run we killed keeps its session, whichever clock killed it: the
+        // transcript is real, it holds however long the agent worked, and the next
+        // delivery on that surface can resume it. Only a turn that failed on its
+        // own — a crash, an unparseable answer — has no continuity worth keeping.
+        if (!result.timedOut && !result.idleTimedOut && !result.cancelled)
             forgetRecordedSession();
         return failure(result);
     }
@@ -598,8 +677,9 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         // it is. See PromptContext.mcpToolPattern.
         mcpToolPattern: runtime.brain !== 'plain' && mcp.mcpWired ? MCP_TOOL_PATTERN : undefined,
         toolsGated: !runtime.skipPermissions,
-        // The real number, not a vague "there is a limit" — see PromptContext.
+        // The real numbers, not a vague "there is a limit" — see PromptContext.
         timeoutMs: options.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS,
+        idleTimeoutMs: options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS,
     });
     const result = await runTurn(run, prompt, options, runtime, mcp, control, log);
     const seconds = (result.durationMs / 1000).toFixed(1);

package/dist/index.js

@@ -25,7 +25,7 @@ function printHelp() {
         'Usage:',
         '  prohost listen --forward-to <local-url> [--api-key <key>] [--url <ws-url>] [--machine <name>] [--subscription-id <id>]',
         '  prohost agent pair --code <pairing-code> [--webhook-url <https-url>] [--base-url <url>]',
-        "  prohost agent run --exec '<command>' [--timeout <seconds>] [--dry-run] [--workdir <dir>]",
+        "  prohost agent run --exec '<command>' [--idle-timeout <seconds>] [--timeout <seconds>] [--dry-run] [--workdir <dir>]",
         "  prohost agent install-daemon --exec '<command>' [--workdir <dir>]   Keep the agent running",
         '  prohost agent uninstall-daemon',
         '',
@@ -43,9 +43,12 @@ function printHelp() {
         '',
         'agent run flags:',
         '  --exec           Command to run for each mention; the prompt arrives on stdin (required)',
-        '  --timeout        Seconds one run may take before it is killed. Defaults to 7200 (2 hours).',
-        '                   Pass 0 for no local limit — the run then ends when the agent finishes,',
-        '                   when someone cancels it in ProhostAI, or when the server reaps it.',
+        '  --idle-timeout   Seconds a run may produce NO output at all before it is treated as',
+        '                   stalled and killed. Defaults to 900 (15 minutes). Any byte on stdout or',
+        '                   stderr resets it, so a working agent never trips it. Pass 0 to disable.',
+        '  --timeout        Seconds one run may take before it is killed, however busy it is.',
+        '                   Defaults to 0 — no wall-clock limit, because a long run is not a stuck',
+        '                   one. Set it if you want a hard ceiling as well as the stall watchdog.',
         '  --dry-run        Print the reply that would be posted; write nothing.',
         '  --workdir        Working directory for the agent command. Defaults to $PROHOST_HOME/workspace.',
         '                   Avoid pointing it at a code checkout: agents read CLAUDE.md, .claude/settings.json',
@@ -71,7 +74,8 @@ function printHelp() {
         '',
         'agent install-daemon flags:  (macOS: launchd; Linux: prints a systemd-user unit)',
         '  --exec           The same command you would pass to `agent run` (required).',
-        '  --workdir, --timeout, --machine, --url, --allow-unverified, --safe-tools — passed to `agent run`.',
+        '  --workdir, --idle-timeout, --timeout, --machine, --url, --allow-unverified, --safe-tools',
+        '                   — passed to `agent run`.',
         '',
         'Global flags:',
         '  --help, -h       Show this help and exit.',

package/dist/version.d.ts

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export declare const CLI_VERSION = "0.3.0";
+export declare const CLI_VERSION = "0.4.0";
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
-export declare const USER_AGENT = "prohost-cli/0.3.0";
+export declare const USER_AGENT = "prohost-cli/0.4.0";

package/dist/version.js

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export const CLI_VERSION = '0.3.0';
+export const CLI_VERSION = '0.4.0';
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
 export const USER_AGENT = `prohost-cli/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prohost/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Run your own AI agent as a ProhostAI teammate, and stream your account's webhooks to your laptop.",
   "type": "module",
   "license": "MIT",