@prohost/cli 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,112 @@ 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
+brain was given a real coding task, worked on it for five minutes, and was
+killed mid-edit by a timeout that had been chosen when "a run" meant "answer a
+mention". The person waiting got `timed out after 300000ms` and nothing else —
+no partial answer, no way to resume the session it had built up, and no way to
+tell from the thread that the agent had been doing anything at all.
+
+- **The default ceiling is two hours, and `--timeout 0` removes it.** A coding
+  agent's unit of work is not a chat reply. The timeout is now a backstop
+  against a genuinely wedged process rather than a shape imposed on the work,
+  and `0` — previously rejected — means the run ends when the agent ends it,
+  when somebody cancels it, or when the server stops renewing its lease. The
+  timeout message names the way out (`raise the ceiling with --timeout
+  <seconds>`) because that string does not stay in `agent.log`: the server
+  echoes a failed run's error into the thread, so the person waiting reads it.
+- **Heartbeats keep long runs alive, and are how "stop" reaches a laptop.**
+  Every run this process has accepted is reported once a minute — the executing
+  one *and* every run queued behind it, since a run waiting behind a four-hour
+  job is `running` server-side for four hours and is reaped on exactly the same
+  clock. The response carries `cancel_requested`, which is the only channel by
+  which a stop pressed in ProhostAI can reach a machine that accepts no inbound
+  connections. Cancelling signals the command's whole process group the same way
+  a timeout does (SIGTERM, then SIGKILL five seconds later), reports the run
+  with the marker the server words as a cancellation, and posts no reply. A run
+  the server has already closed out (409) is abandoned outright: the child is
+  killed and nothing is posted, because there is nothing left to post to.
+- **Against an older ProhostAI server, nothing changes.** The heartbeat endpoint
+  answers `404` there; the CLI says so once per run, stops asking, and behaves
+  exactly as 0.2.3 did. No `Depends-on`, no coordinated upgrade.
+- **Claude Code runs are read as they happen (`--output-format stream-json`).**
+  Three things fall out of that, none of which could work when stdout was read
+  at exit. The session id is recorded the moment the run announces it, so a run
+  killed at hour two can still be resumed — where before, the id arrived with
+  the final envelope a killed run never produces, and two hours of context went
+  with it. The heartbeat carries what the agent is doing (the tool it just
+  called, or the opening of what it is writing). And a killed or cancelled run
+  reports the tail of the answer it had been writing rather than only the fact
+  that it stopped. A rejected reply still un-records the session, so the rule
+  that used to be expressed by recording late is kept. Codex and plain `--exec`
+  commands are untouched; heartbeats and cancellation apply to them all the
+  same, they just have no progress to report.
+- **The prompt states the actual budget.** It used to say "this run has a hard
+  time limit" — the same sentence whether the limit was five minutes or four
+  hours, which is how an agent with two hours triages work it had time to
+  finish. It now says roughly how long, or that there is no fixed limit and a
+  long silence gets reported as a stalled run.
+- **A dropped completion is retried for about ten minutes**, up from thirteen
+  seconds. The old schedule was sized for a five-minute run; losing the
+  completion of a four-hour one is worth waiting out a wifi drop for. The run
+  keeps being heartbeated throughout, so the row it is trying to close is not
+  reaped underneath the retries.
+
 ## 0.2.3
 
 Three things, all of them about a run knowing what is actually true about

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` | `300` | Seconds one run may take before the command is killed. |
+| `--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`. |
@@ -409,6 +410,37 @@ same judgement.
 | `--allow-unverified` | off | Run events whose signature can't be verified. See below. |
 | `--safe-tools` | off | Gate the agent's tools behind permission prompts instead of bypassing them. Claude Code and Codex only. Alias: `--no-skip-permissions`. |
 
+### Long runs
+
+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:
+
+- **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.
+  Against an older ProhostAI server the heartbeat endpoint answers `404`; the
+  CLI says so once per run and otherwise behaves exactly as it did before.
+- **Cancel works.** Stopping a run in ProhostAI is answered on the next
+  heartbeat: the command's whole process group gets `SIGTERM`, then `SIGKILL`
+  five seconds later, and the run is reported as cancelled. No reply is posted.
+- **A killed run is not silent.** With Claude Code the CLI reads the run's
+  output as it is produced, so the run's session id is saved immediately (the
+  next turn on that surface can still resume it) and a run that is killed or
+  cancelled reports the tail of whatever the agent had written.
+
 ### Keeping it running
 
 `agent run` in a terminal window stops being an agent the moment you close the

package/dist/agent/api.d.ts

@@ -1,10 +1,10 @@
 /**
- * The two HTTP writes the harness makes back into ProhostAI: post the reply,
- * then close out the run.
+ * The HTTP writes the harness makes back into ProhostAI: post the reply, say a
+ * long run is still alive, and close the run out.
  *
- * Both authenticate with the paired API key over ``X-API-Key`` and both return
- * a result object rather than throwing — the runner has to keep going (and
- * still complete the run) whichever one fails.
+ * All of them authenticate with the paired API key over ``X-API-Key`` and all
+ * of them return a result object rather than throwing — the runner has to keep
+ * going (and still complete the run) whichever one fails.
  *
  * The paths come from the run event itself (`reply_instructions.path` /
  * `completion.path`), which is why these take a path rather than building one.
@@ -20,6 +20,13 @@ export interface ApiResult {
     ok: boolean;
     status: number;
     error?: string;
+    /**
+     * The response body, when the caller asked for it.
+     *
+     * Only the heartbeat reads a success body — it is the one call whose answer
+     * carries information (``cancel_requested``) rather than just an acceptance.
+     */
+    body?: string;
 }
 /**
  * Post the agent's reply into the conversation that triggered the run.
@@ -34,6 +41,47 @@ export interface ApiResult {
  * a CLI release.
  */
 export declare function postReply(options: ApiOptions, path: string, bodyKey: string, message: string, runId: string, extra?: Record<string, unknown>): Promise<ApiResult>;
+/**
+ * What one heartbeat told us about a run.
+ *
+ * Four outcomes, and the harness does something different with each — which is
+ * why this is a tagged union rather than an {@link ApiResult}. In particular
+ * ``unknown`` (404) is not an error to report: it is what **every server built
+ * before heartbeats existed** answers, and the only correct response to it is
+ * to stop asking and behave exactly as this CLI did before.
+ */
+export type HeartbeatOutcome = 
+/** The run is still open server-side. ``cancelRequested`` means: stop now. */
+{
+    kind: 'alive';
+    cancelRequested: boolean;
+}
+/** 404 — an older server, or a run this credential no longer owns. */
+ | {
+    kind: 'unknown';
+}
+/** 409 — the run already reached a terminal state without us. */
+ | {
+    kind: 'resolved';
+}
+/** Anything else, including a network failure (``status: 0``). */
+ | {
+    kind: 'error';
+    status: number;
+    detail?: string;
+};
+/**
+ * Tell the server a run is still being worked on, and ask whether it should be.
+ *
+ * Sent on a cadence for every run this process has accepted and not yet
+ * reported — the one being executed *and* the ones queued behind it, because a
+ * run queued behind a four-hour job is exactly as reapable as the job itself.
+ *
+ * ``progress`` is a courtesy for whoever is watching the run in the UI, never a
+ * requirement: a queued run has none, and the brains that don't stream their
+ * work send none either.
+ */
+export declare function heartbeatRun(options: ApiOptions, path: string, progress?: string): Promise<HeartbeatOutcome>;
 /**
  * Report a run's terminal state. Called for every run — including one whose
  * command crashed — so the server never waits on a run this harness abandoned.

package/dist/agent/api.js

@@ -1,18 +1,20 @@
 /**
- * The two HTTP writes the harness makes back into ProhostAI: post the reply,
- * then close out the run.
+ * The HTTP writes the harness makes back into ProhostAI: post the reply, say a
+ * long run is still alive, and close the run out.
  *
- * Both authenticate with the paired API key over ``X-API-Key`` and both return
- * a result object rather than throwing — the runner has to keep going (and
- * still complete the run) whichever one fails.
+ * All of them authenticate with the paired API key over ``X-API-Key`` and all
+ * of them return a result object rather than throwing — the runner has to keep
+ * going (and still complete the run) whichever one fails.
  *
  * The paths come from the run event itself (`reply_instructions.path` /
  * `completion.path`), which is why these take a path rather than building one.
  */
 import { USER_AGENT } from '../version.js';
-import { MAX_ERROR_CHARS, RUN_STATUS_FAILED, RUN_STATUS_SUCCEEDED } from './contract.js';
+import { MAX_ERROR_CHARS, MAX_PROGRESS_CHARS, RUN_STATUS_FAILED, RUN_STATUS_SUCCEEDED, } from './contract.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
-async function post(options, path, body, idempotencyKey) {
+/** Cap on a captured response body. Every one we parse is a small object. */
+const MAX_BODY_CHARS = 2_000;
+async function post(options, path, body, idempotencyKey, captureBody = false) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
@@ -30,15 +32,18 @@ async function post(options, path, body, idempotencyKey) {
         });
         const ok = response.status >= 200 && response.status < 300;
         let error;
-        if (!ok) {
+        let text;
+        if (!ok || captureBody) {
             // Surface the server's reason — a scope or tier denial is the most
             // likely failure here and the host can act on it.
-            error = await response
+            text = await response
                 .text()
-                .then((t) => t.slice(0, 500))
+                .then((t) => t.slice(0, MAX_BODY_CHARS))
                 .catch(() => undefined);
+            if (!ok)
+                error = text?.slice(0, 500);
         }
-        return { ok, status: response.status, error };
+        return { ok, status: response.status, error, body: captureBody ? text : undefined };
     }
     catch (err) {
         return {
@@ -69,6 +74,41 @@ export async function postReply(options, path, bodyKey, message, runId, extra) {
     // thing in this request that must survive.
     return post(options, path, { ...extra, [bodyKey]: message }, `prohost-cli-run-${runId}`);
 }
+function booleanField(body, key) {
+    if (!body)
+        return false;
+    try {
+        const parsed = JSON.parse(body);
+        if (!parsed || typeof parsed !== 'object')
+            return false;
+        return parsed[key] === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Tell the server a run is still being worked on, and ask whether it should be.
+ *
+ * Sent on a cadence for every run this process has accepted and not yet
+ * reported — the one being executed *and* the ones queued behind it, because a
+ * run queued behind a four-hour job is exactly as reapable as the job itself.
+ *
+ * ``progress`` is a courtesy for whoever is watching the run in the UI, never a
+ * requirement: a queued run has none, and the brains that don't stream their
+ * work send none either.
+ */
+export async function heartbeatRun(options, path, progress) {
+    const trimmed = progress?.trim();
+    const result = await post(options, path, trimmed ? { progress: trimmed.slice(0, MAX_PROGRESS_CHARS) } : {}, undefined, true);
+    if (result.ok)
+        return { kind: 'alive', cancelRequested: booleanField(result.body, 'cancel_requested') };
+    if (result.status === 404)
+        return { kind: 'unknown' };
+    if (result.status === 409)
+        return { kind: 'resolved' };
+    return { kind: 'error', status: result.status, detail: result.error };
+}
 /**
  * Report a run's terminal state. Called for every run — including one whose
  * command crashed — so the server never waits on a run this harness abandoned.

package/dist/agent/claude.d.ts

@@ -106,7 +106,7 @@ export type ClaudeOutput = {
     denials: string[];
 };
 /**
- * Read the reply and the session id out of `--output-format json` stdout.
+ * Read the reply and the session id out of a finished run's stdout.
  *
  * Unparseable output is a **failure**, not a fallback to posting the raw text.
  * We asked for JSON; stdout that isn't JSON means something went wrong that we
@@ -114,8 +114,60 @@ export type ClaudeOutput = {
  * one thing that must not happen is that being posted verbatim into a customer's
  * conversation. Reporting the run failed is recoverable; sending a stack trace
  * to a guest is not.
+ *
+ * Still whole-stdout rather than streaming, and still used: it is what
+ * {@link readClaudeStream} falls back to when a run produced no `result` event
+ * at all, and it reads a plain `--output-format json` envelope exactly as it
+ * always did.
  */
 export declare function parseClaudeOutput(stdout: string): ClaudeOutput;
+/** Cap on the activity line handed to the heartbeat. */
+export declare const MAX_ACTIVITY_CHARS = 120;
+/** Cap on the partial answer salvaged from a run that was killed. */
+export declare const MAX_SALVAGE_CHARS = 500;
+/**
+ * A run's stdout, read as it is produced.
+ *
+ * Everything here is an enhancement over reading stdout at exit, and every one
+ * of them fails soft: a stream we cannot parse costs progress reporting and
+ * salvage, never the run.
+ */
+export interface ClaudeStream {
+    /** Feed one stdout chunk. Never throws. */
+    push(chunk: string): void;
+    /**
+     * The session id, as soon as the run announced it.
+     *
+     * This is the whole reason the session id is read here rather than out of the
+     * final envelope: a run killed at hour two never produces a final envelope,
+     * and without the id its two hours of context are unreachable — the next turn
+     * on that surface starts from nothing.
+     */
+    sessionId(): string | undefined;
+    /**
+     * What the agent is doing right now, in one short line — the last tool it
+     * called, or the opening of the text it is writing.
+     */
+    activity(): string | undefined;
+    /** The tail of the last thing the agent wrote, for a run that was killed. */
+    salvage(): string | undefined;
+    /**
+     * The turn's outcome. ``stdout`` is the complete captured output, used only
+     * when the stream held no `result` event — a crashed binary, a login prompt,
+     * or a plain `--output-format json` envelope from a command we did not shape.
+     */
+    finish(stdout: string): ClaudeOutput;
+}
+/**
+ * Parse `--output-format stream-json` incrementally.
+ *
+ * Line-delimited JSON, one event per line, so the parser is a buffer and a
+ * split. Anything it doesn't recognise is skipped in silence: the event
+ * vocabulary belongs to Claude Code and grows without asking us, and a reader
+ * that failed on an unknown `type` would turn a Claude Code release into a
+ * fleet of broken laptops.
+ */
+export declare function readClaudeStream(): ClaudeStream;
 /**
  * Does this look like the resume having been rejected, rather than the agent
  * having failed at its actual work?

package/dist/agent/claude.js

@@ -109,7 +109,17 @@ export function claudeCommand(base, flags = {}) {
             .split(/\s+/)
             .filter((word) => word !== '--dangerously-skip-permissions')
             .join(' ');
-    const parts = [command, '--output-format', 'json'];
+    // `stream-json` rather than `json`, and the two flags travel together:
+    // Claude Code refuses `--output-format stream-json` in print mode without
+    // `--verbose`. What it buys is everything that cannot wait for the process to
+    // exit — the session id lands in the ledger on the first event rather than
+    // after the reply is posted, the heartbeat can say what the agent is doing,
+    // and a run that gets killed at hour two still has a partial answer to
+    // report. The final `result` event carries the same fields the single JSON
+    // envelope did, so the reply itself is unchanged.
+    const parts = [command, '--output-format', 'stream-json'];
+    if (!/(^|\s)--verbose(\s|$)/.test(command))
+        parts.push('--verbose');
     if (skipPermissions)
         parts.push('--dangerously-skip-permissions');
     if (flags.sessionId)
@@ -198,27 +208,13 @@ function text(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
 /**
- * Read the reply and the session id out of `--output-format json` stdout.
+ * Turn a `result` envelope into the harness's view of the turn.
  *
- * Unparseable output is a **failure**, not a fallback to posting the raw text.
- * We asked for JSON; stdout that isn't JSON means something went wrong that we
- * do not understand — a crash banner, a login prompt, an npm warning — and the
- * one thing that must not happen is that being posted verbatim into a customer's
- * conversation. Reporting the run failed is recoverable; sending a stack trace
- * to a guest is not.
+ * Shared by the whole-stdout parser and the streaming reader, because the
+ * envelope is identical either way: `--output-format stream-json` ends with the
+ * same object `--output-format json` used to print on its own.
  */
-export function parseClaudeOutput(stdout) {
-    const parsed = resultEnvelope(stdout);
-    if (!parsed) {
-        const sample = stdout.trim().slice(0, 200);
-        return {
-            denials: [],
-            ok: false,
-            error: sample
-                ? `claude did not return JSON (asked for --output-format json). First 200 chars: ${sample}`
-                : 'claude returned no output',
-        };
-    }
+function outputFromEnvelope(parsed) {
     const sessionId = text(parsed.session_id);
     const result = text(parsed.result);
     const denials = denialNames(parsed.permission_denials);
@@ -239,6 +235,155 @@ export function parseClaudeOutput(stdout) {
     }
     return { ok: true, text: result, sessionId, denials };
 }
+/**
+ * Read the reply and the session id out of a finished run's stdout.
+ *
+ * Unparseable output is a **failure**, not a fallback to posting the raw text.
+ * We asked for JSON; stdout that isn't JSON means something went wrong that we
+ * do not understand — a crash banner, a login prompt, an npm warning — and the
+ * one thing that must not happen is that being posted verbatim into a customer's
+ * conversation. Reporting the run failed is recoverable; sending a stack trace
+ * to a guest is not.
+ *
+ * Still whole-stdout rather than streaming, and still used: it is what
+ * {@link readClaudeStream} falls back to when a run produced no `result` event
+ * at all, and it reads a plain `--output-format json` envelope exactly as it
+ * always did.
+ */
+export function parseClaudeOutput(stdout) {
+    const parsed = resultEnvelope(stdout);
+    if (!parsed) {
+        const sample = stdout.trim().slice(0, 200);
+        return {
+            denials: [],
+            ok: false,
+            error: sample
+                ? `claude did not return JSON (asked for --output-format stream-json). First 200 chars: ${sample}`
+                : 'claude returned no output',
+        };
+    }
+    return outputFromEnvelope(parsed);
+}
+/** Cap on the activity line handed to the heartbeat. */
+export const MAX_ACTIVITY_CHARS = 120;
+/** Cap on the partial answer salvaged from a run that was killed. */
+export const MAX_SALVAGE_CHARS = 500;
+/**
+ * Cap on a single buffered stdout line.
+ *
+ * A stream line is one JSON event, and a pathological one that never ends
+ * (binary output from a wrapper script, say) would otherwise accumulate
+ * unbounded between newlines. Dropped rather than truncated: half a JSON object
+ * parses as nothing useful anyway.
+ */
+const MAX_LINE_CHARS = 4 * 1024 * 1024;
+/** Text of an `assistant` event's message, and the last tool it invoked. */
+function assistantContent(event) {
+    const message = event.message;
+    if (!message || typeof message !== 'object')
+        return {};
+    const content = message.content;
+    if (!Array.isArray(content))
+        return {};
+    let latestText;
+    let latestTool;
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const entry = block;
+        if (entry.type === 'text' && typeof entry.text === 'string' && entry.text.trim()) {
+            latestText = entry.text;
+        }
+        else if (entry.type === 'tool_use' && typeof entry.name === 'string' && entry.name) {
+            latestTool = entry.name;
+        }
+    }
+    return { text: latestText, tool: latestTool };
+}
+/**
+ * Parse `--output-format stream-json` incrementally.
+ *
+ * Line-delimited JSON, one event per line, so the parser is a buffer and a
+ * split. Anything it doesn't recognise is skipped in silence: the event
+ * vocabulary belongs to Claude Code and grows without asking us, and a reader
+ * that failed on an unknown `type` would turn a Claude Code release into a
+ * fleet of broken laptops.
+ */
+export function readClaudeStream() {
+    let buffer = '';
+    let session;
+    let lastActivity;
+    let lastText;
+    let result;
+    const handle = (line) => {
+        const event = asObject(line);
+        if (!event)
+            return;
+        // Present on the `system`/`init` event, and repeated on most others. Taken
+        // from whichever arrives first — they all name the same session.
+        if (!session)
+            session = text(event.session_id);
+        if (event.type === 'result') {
+            result = event;
+            return;
+        }
+        if (event.type !== 'assistant')
+            return;
+        const { text: written, tool } = assistantContent(event);
+        if (written)
+            lastText = written;
+        // Whichever happened last within this message: a tool call after some text
+        // means the agent has moved on from writing to doing.
+        if (tool)
+            lastActivity = `using ${tool}`;
+        else if (written)
+            lastActivity = written.replace(/\s+/g, ' ').trim().slice(0, MAX_ACTIVITY_CHARS);
+    };
+    return {
+        push(chunk) {
+            buffer += chunk;
+            if (!buffer.includes('\n')) {
+                if (buffer.length > MAX_LINE_CHARS)
+                    buffer = '';
+                return;
+            }
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            if (buffer.length > MAX_LINE_CHARS)
+                buffer = '';
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    handle(trimmed);
+            }
+        },
+        sessionId: () => session,
+        activity: () => lastActivity,
+        salvage: () => {
+            const trimmed = lastText?.trim();
+            if (!trimmed)
+                return undefined;
+            return trimmed.length > MAX_SALVAGE_CHARS ? trimmed.slice(-MAX_SALVAGE_CHARS) : trimmed;
+        },
+        finish(stdout) {
+            // A trailing event with no newline after it is still an event — a binary
+            // that exits without flushing a final `\n` must not lose its result.
+            const tail = buffer.trim();
+            if (tail) {
+                handle(tail);
+                buffer = '';
+            }
+            if (result)
+                return outputFromEnvelope(result);
+            // No `result` event: either the command isn't emitting the stream we
+            // asked for, or it died before finishing. Either way the whole-output
+            // parser gives the better error message, and it still understands a
+            // single `json` envelope.
+            const parsed = parseClaudeOutput(stdout);
+            return session && !parsed.sessionId ? { ...parsed, sessionId: session } : parsed;
+        },
+    };
+}
 /**
  * Does this look like the resume having been rejected, rather than the agent
  * having failed at its actual work?

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 {};