@prohost/cli 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,60 @@ 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.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,7 @@ 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. |
+| `--timeout` | `7200` | Seconds one run may take before the command is killed. `0` removes the local cap entirely — see "Long runs". |
 | `--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 +409,28 @@ 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:
+
+- **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.
+- **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.js

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

package/dist/agent/contract.d.ts

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