@prohost/cli 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,175 @@ 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
+itself: a prompt bullet that taught agents to doubt tools they had, a way to
+give an agent a tool on purpose, and closing the gaps 0.2.2 shipped with an
+honest note attached.
+
+- **A ToolSearch miss no longer reads as proof.** 0.2.1 told the agent to
+  "search ToolSearch for a capability before telling anyone you lack it", which
+  is right about deferred web browsing and badly wrong as a general rule. In
+  production a paired brain searched ToolSearch for `bash`, found nothing —
+  ToolSearch indexes only the *deferred* tools, and Bash is a direct one — and
+  spent an entire resumed session reporting it had no shell, while
+  `--dangerously-skip-permissions` had been handing it the full toolset the
+  whole time. The prompt now states that the directly-listed tools are the
+  authoritative set, that a ToolSearch miss is evidence of nothing, and that
+  "looking" means running the command rather than reading one's own tool list:
+  a claim of no shell, no file access or no checkout has to come after an
+  attempt that failed and can be quoted. The original bullet stays — deferred
+  browsing is real, and dropping it would just swap one wrong inference for the
+  other.
+- **`~/.prohost/extra-mcp.json` — opt-in extra MCP servers.** A run gets the
+  ProhostAI server and nothing else, and that isolation is a security boundary:
+  a run executes with permission prompts off on prompt text written by whoever
+  mentioned the agent. This adds a way to widen it deliberately without weakening
+  the default. Write the file yourself — the CLI never creates it — holding the
+  same `{"mcpServers": {…}}` object Claude Code's `--mcp-config` takes; it works
+  on both brains. The name `prohost` is reserved and an entry using it is
+  rejected out loud rather than silently honoured; a malformed file is a warning
+  and a run without extras rather than a run that doesn't happen; and which
+  servers loaded is printed when the grant set changes so `agent.log` can answer "did my server
+  load". Every server in that file is exercisable by anyone who can trigger the
+  agent, which the README, the file's own documentation and `--help` all say in
+  those words.
+- **Codex gets the isolation Claude Code has.** 0.2.2 shipped with "there is no
+  Codex equivalent of `--strict-mcp-config`", which turned out to be true of the
+  two mechanisms that look like one and false overall. `-c mcp_servers={…}` does
+  not replace the table — Codex deep-merges overrides — and `--ignore-user-config`
+  works but discards the operator's model, profile and sandbox settings along
+  with their servers. The one that works is per-server: the CLI now asks the
+  binary what it has (`codex mcp list --json`) and passes a single
+  `-c mcp_servers={"<name>"={enabled=false}, …}`, verified end to end against
+  `codex-cli 0.144.1` — the tools are genuinely gone from the model's list
+  mid-run, each server's own definition survives, and servers not named are
+  untouched. Asking the binary rather than parsing `~/.codex/config.toml`
+  matters twice over: on a normal install `codex mcp list` reports servers that
+  appear nowhere in that file, and the name has to go inside the value because
+  a server called `fly.io` written as `-c mcp_servers.fly.io.enabled=false`
+  addresses a three-segment path and makes Codex reject the entire config. The
+  override is also **verified against the binary before it is used**, which one
+  case genuinely needs: `{enabled=false}` merges onto a server's existing
+  definition, and a plugin-contributed server has none to merge onto, so the
+  override leaves a table with no transport and Codex refuses to start —
+  shipped unverified that would have broken every run for anyone with a Codex
+  plugin installed. The CLI falls back to checking each server on its own and
+  fails the run before Codex starts if any cannot be disabled. If the
+  enumeration fails outright the run also fails closed instead of proceeding
+  under `--yolo` with an unprovable boundary. Same treatment for `extra-mcp.json` definitions:
+  rejected ones are dropped with a warning rather than taking the run with them.
+  Every probe now runs in the exact cwd of the eventual Codex process as well,
+  so a trusted repo's project-local `.codex/config.toml` cannot appear only
+  after a clean-directory survey. Default `$PROHOST_HOME/workspace` and an
+  explicit harness `--workdir` both use that same path end to end.
+
+  Three further things the binary had to be asked rather than assumed. Every
+  server goes in **one** `-c mcp_servers={…}`, ProhostAI included: `-c`
+  overrides apply in order and a later whole-table assignment *replaces* an
+  earlier dotted one, so the obvious two-override shape silently dropped the
+  ProhostAI server on every run that disabled anything. An extra whose name
+  your Codex config already uses is **refused**, because Codex merges the two
+  definitions and the existing server's `Authorization` header would be sent to
+  the extra's URL. The extras file and Codex survey are refreshed before every
+  run, so deleting a grant or installing a new server takes effect immediately
+  in a long-lived daemon. Literal header and stdio environment secrets from the
+  Claude-shaped extras file are moved into Codex's child environment instead of
+  being exposed in process arguments.
+
+  One gap stays open and is documented rather than papered over: a `--exec`
+  running Codex under a named profile (`-p work`) can have MCP servers defined
+  only in `work.config.toml`, and `codex mcp list` cannot be asked about a
+  profile at all — `-p`/`--profile` are rejected and `-c profile="…"` is refused
+  as a removed legacy form. The CLI now fails the run before spawning Codex
+  when it sees a profile flag, including clap's joined `-pwork` spelling. It
+  also fails closed on `-c` / `--config`, feature toggles,
+  `--ignore-user-config`, and cwd-changing `-C` / `--cd` flags, because those
+  can make the real run's plugin/MCP inventory differ from the plain verifier
+  command. Finally, an
+  unrecognised item inside otherwise-valid `mcp list --json` output now makes
+  the entire survey unknown instead of being silently mistaken for no server.
+  Recognisable Codex commands containing shell quoting, expansion, glob,
+  comment or control syntax now fail before spawn instead of falling through to
+  the unshaped path; in particular, quoting an inventory-changing flag cannot
+  hide it from the verifier. The final probe must also report the ProhostAI
+  server and every accepted extra enabled — a successful empty or partial list
+  is no longer accepted as proof. Finally, all environment names referenced by
+  every extra are reserved before literal-header secret variables are
+  allocated, preventing one extra from naming and reading another extra's
+  generated credential, including through differently-cased aliases on Windows.
+  Ordinary unquoted Windows executable and workspace paths remain accepted by
+  the shell-syntax guard while `cmd.exe` expansion and control syntax still
+  fail closed.
+- **Codex reports refused tools.** Also filed under "no equivalent" in 0.2.2.
+  Codex has no `permission_denials` field, but a refused call arrives as an
+  `mcp_tool_call` item with `status: "failed"` and `user cancelled MCP tool
+  call`, which is what every run with nobody at the terminal produces. Those are
+  now printed on the same line the Claude Code path uses. A call that failed for
+  another reason — a server returning 502 — is deliberately not counted, so the
+  log doesn't send you to your permissions over a network problem.
+- **Codex is told how it spells its own tools.** The prompt used to name the MCP
+  server and leave the prefix out, because guessing a tool name is the same
+  failure as guessing an endpoint. Measured against the real binary by
+  registering a stub server and asking the model what it had just called: Codex
+  uses the same `mcp__<server>__<tool>` convention as Claude Code, so both
+  brains now get the pattern.
+
 ## 0.2.2
 
 Two agents paired to the same workspace behaved like different products: the

package/README.md

@@ -179,23 +179,88 @@ word of the command *and* print mode is asked for. Anything else — `npx claude
 redirect, or `&&` — keeps the plain stdin/stdout contract untouched. So
 `--exec 'sh -c "claude -p"'` is the way to opt out.
 
+### Giving the agent other MCP servers
+
+One server by default is a boundary, not an oversight: a run executes with
+permission prompts off, on prompt text written by whoever mentioned your agent.
+Every MCP server reachable from that run is a server your workspace teammates
+can drive.
+
+If you want to widen it anyway, create `~/.prohost/extra-mcp.json` by hand. The
+CLI never creates this file — its existence is you saying yes on purpose. The
+shape is the same `mcpServers` object Claude Code's `--mcp-config` takes, so you
+can lift a block straight out of an existing `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "type": "http",
+      "url": "https://mcp.linear.app/mcp",
+      "headers": { "Authorization": "Bearer lin_api_…" }
+    },
+    "notes": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/notes"]
+    }
+  }
+}
+```
+
+**Read this before you use it.** Every server in that file is exercisable by
+anyone who can trigger your agent — a teammate, a guest whose message routes to
+it — with permission prompts off and no human in the loop. A filesystem server
+scoped at `/` is a filesystem server they can read. Scope each one as narrowly
+as it will go.
+
+Works on both Claude Code and Codex. Details:
+
+- The name `prohost` is **reserved**. An entry using it is rejected with a line
+  in the log and the ProhostAI server stays pointed where pairing put it.
+- **On Codex, a name your own config already uses is also rejected.** Codex
+  merges the two definitions rather than replacing one with the other, so an
+  extra that changes only the URL would inherit the configured server's headers
+  and send its credential to the new host. Rename the extra to use it.
+- Malformed JSON costs you the extras, not the run: the CLI warns and starts
+  without them. The same is true of an entry whose value isn't an object.
+- The file is re-read before every run. Deleting an entry revokes it for the
+  next invocation of an already-running daemon; no restart is required.
+- Which extras loaded is printed when the grant set changes, so `agent.log` answers "did my
+  server actually load" without guessing.
+- On Codex the non-secret parts of each definition become `-c` overrides, which
+  means URLs, commands, and arguments land on a command line other users can
+  read via `ps`. Literal `headers`, `http_headers`, and stdio `env` values are
+  moved to the child environment instead. On Claude Code the definitions go
+  into `~/.prohost/mcp.json`, which is `chmod 600`.
+- Also on Codex: a value with something TOML can't express (an infinity, say)
+  makes that server skipped with a warning, rather than emitted as an override
+  that would fail to parse and take the ProhostAI server down with it. Any
+  server *name* works, dots included.
+- Delete the file to go back to one server. There is no flag to disable it,
+  because a file you have to write by hand is already the opt-in.
+
 ### If your agent is Codex
 
 When `--exec` starts with `codex` and uses the `exec` subcommand, the CLI does
 the same three things it does for Claude Code, through Codex's own flags. The
-detection is just as narrow: interactive `codex`, a wrapper script, a pipeline,
-a command that already says `codex exec resume` / `codex exec review`, or one
-carrying its own prompt (`codex exec 'Be terse'`) all keep the plain
+detection is just as narrow: interactive `codex`, a wrapper script, a command
+that already says `codex exec resume` / `codex exec review`, or one
+carrying its own unquoted prompt (`codex exec Be-terse`) keep the plain
 stdin/stdout contract untouched. That last one matters: Codex takes exactly one
-prompt positional, so the CLI cannot add its own alongside yours. Put standing
-instructions in the agent's ProhostAI profile instead — they arrive at the top
-of the prompt, ahead of everything else.
+prompt positional, so the CLI cannot add its own alongside yours. Shell syntax
+inside a recognisable Codex command — quoting, escapes, expansions, globs,
+comments, redirects, pipelines or lists — instead fails before Codex starts.
+The harness cannot safely make a whitespace scan agree with both POSIX shells
+and `cmd.exe`, and treating such a command as plain would silently drop MCP
+isolation. Ordinary unquoted Windows path separators remain supported. Put
+standing instructions in the agent's ProhostAI profile instead — they arrive at
+the top of the prompt, ahead of everything else.
 
 | | Claude Code | Codex |
 | --- | --- | --- |
 | Reply read from | `--output-format json` | `--json` (JSONL event stream) |
 | Conversation kept with | `--resume <id>` | `codex exec resume <thread>` |
-| Tools wired via | `--mcp-config` | `-c mcp_servers.prohost={…}` |
+| Tools wired via | `--mcp-config` | one verified `-c mcp_servers={…}` override |
 | API key travels in | `~/.prohost/mcp.json` (`chmod 600`) | the child's environment |
 | Tools ungated by | `--dangerously-skip-permissions` | `--yolo` |
 
@@ -210,22 +275,83 @@ does for Claude Code, and it *removes* a bypass flag you wrote yourself rather
 than just declining to add one, so the gating it promises is real. (It covers
 the full bypass only; `--full-auto` still auto-approves inside Codex's sandbox.)
 
-**Two things Codex cannot do that Claude Code can**, both worth knowing before
-you leave it running:
-
-- **Your own MCP servers come along.** There is no Codex equivalent of
-  `--strict-mcp-config`. `--ignore-user-config` looks like one but drops the
-  `-c` overrides too, taking the ProhostAI server with them — so a Codex run
-  also holds whatever servers your `~/.codex/config.toml` defines, with
-  approvals bypassed. The CLI prints this at start-up so it isn't a surprise.
-  If that matters, keep `~/.codex/config.toml` free of servers you would not
-  hand to a teammate's message.
-- **Refused tools stay invisible.** Claude Code reports what it was denied and
-  the CLI prints it; Codex's event stream has no equivalent.
+**Your own MCP servers are switched off for agent runs.** Codex has no
+`--strict-mcp-config`, so the CLI does the same job a different way: before each run
+it asks your binary what servers it has (`codex mcp list --json`) and passes one
+`-c mcp_servers={"<name>"={enabled=false}, …}` covering all of them. A run then
+holds the ProhostAI server, plus anything in your `extra-mcp.json`, and nothing
+else — the same boundary the Claude Code path gets. Each server's own definition
+is left intact; only this invocation sees it disabled.
+
+Two mechanisms that look like they should do this do not, and are worth naming
+so nobody reaches for them. Replacing the `mcp_servers` table does not replace
+it — Codex deep-merges config overrides, so your servers survive alongside
+whatever the override adds. And `--ignore-user-config` works, but throws away
+your model, profile and sandbox settings along with your servers.
+
+The enumeration asks the binary rather than reading `~/.codex/config.toml`,
+because that file is not the whole story: on a normal install `codex mcp list`
+reports servers that appear nowhere in it. It also handles names a dotted-path
+override cannot address — a server called `fly.io` written as
+`-c mcp_servers.fly.io.enabled=false` addresses a three-segment path and Codex
+rejects the whole config, which is why the name goes inside the value instead.
+Every probe also runs in the exact directory the eventual Codex process will
+use. That matters because a trusted project's `.codex/config.toml` is another
+config layer: probing where the harness was launched and then running in
+`$PROHOST_HOME/workspace` or an explicit `--workdir` would certify one MCP
+inventory and execute another.
+
+**The override is checked before it is used**, and one case needs it.
+`{enabled=false}` merges onto a server's existing definition, and a server
+contributed by a **plugin** has no `mcp_servers` entry to merge onto — so the
+override leaves a table with no transport and Codex refuses to start at all.
+The CLI therefore runs the disable past `codex mcp list` first, falls back to
+checking each server individually if the combined form is rejected, and then
+verifies the exact final override. If any configured server cannot be disabled,
+or if the final listing does not show the ProhostAI server and every accepted
+extra enabled, the run fails before Codex starts. Remove that server/plugin or
+use Claude Code.
+
+If the enumeration fails outright — an older Codex without `mcp list --json`,
+or output the CLI doesn't recognise — the run fails before Codex starts. A
+paired run never proceeds under `--yolo` when its MCP boundary cannot be proven.
+Nothing here changes what your Codex config does outside agent runs.
+
+**One gap that cannot be closed from here: profiles.** If your `--exec` runs
+Codex under a named profile (`codex exec -p work`), that profile's
+`work.config.toml` can define MCP servers of its own — and `codex mcp list` has
+no way to be asked about a profile (`-p` and `--profile` are rejected, and the
+`-c profile="…"` form is refused as a removed legacy spelling). Servers defined
+only inside a profile are therefore invisible to the sweep. The CLI fails the
+run before Codex starts when it sees a profile flag; run the agent without `-p`.
+
+The same fail-closed rule applies to `-c` / `--config`, `--enable`, `--disable`,
+`--ignore-user-config`, and `-C` / `--cd` in `--exec`. Those flags can change
+config, plugin loading, or the project config discovery directory for the real
+invocation, while the separate `codex mcp list` verifier cannot safely replay
+an arbitrary shell command's arguments. Use the harness's `--workdir` when you
+need a different directory; dedicated flags such as `--model` and `--sandbox`
+remain supported.
+
+The survey is retaken before every invocation, because
+`install-daemon` runs for weeks and Codex rereads its configuration on every
+invocation — a server you install on Tuesday would otherwise be reachable from
+the next run. The log stays quiet unless the answer changes.
+
+**Refused tools are reported**, as of 0.2.3. Codex has no `permission_denials`
+field, but a refused call arrives as an `mcp_tool_call` item with
+`status: "failed"` and `user cancelled MCP tool call`, and the CLI prints those
+in the same line the Claude Code path uses. A tool call that failed for any
+other reason — an MCP server that 500s — is deliberately not reported as a
+denial, so the log doesn't send you to your permissions when the problem is
+your network.
 
 Your ProhostAI API key is passed to Codex in the child process's environment
 rather than in the `-c` override, because a command line is readable by anyone
-on the machine via `ps` and a process environment is not.
+on the machine via `ps` and a process environment is not. Literal `headers`,
+`http_headers`, and stdio `env` values in `extra-mcp.json` get the same
+treatment: the CLI translates them to Codex's environment-indirection fields,
+so their values do not appear in process arguments.
 
 Runs are handled one at a time, and each run executes **at most once on this
 machine** — even across restarts. Started runs are recorded in
@@ -274,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`. |
@@ -283,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
@@ -363,6 +511,7 @@ Everything the CLI stores lives under `~/.prohost` (`$PROHOST_HOME` moves it):
 | `runs.json` | Runs already executed on this machine, so a redelivery can't run your agent twice. |
 | `sessions.json` | Conversation → Claude Code session / Codex thread, for continuity. Safe to delete; costs the agent its memory of open threads. |
 | `mcp.json` | Generated MCP config. Holds your API key — `chmod 600`. |
+| `extra-mcp.json` | Optional, written by you. Extra MCP servers to expose to agent runs — see "Giving the agent other MCP servers". Never created by the CLI. |
 | `workspace/` | Where your agent command runs by default. |
 | `agent.log` | Daemon output. |
 

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.