@prohost/cli 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,79 @@ 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.5.0
+
+A paired agent can no longer sit on a dead socket believing it is connected.
+
+- **The failure.** One daemon (`agent run` under launchd) was "connected" for
+  three weeks and received nothing. The server had closed the socket on
+  2026-08-11 — the laptop was almost certainly asleep, the FIN never arrived —
+  and the client kernel kept the TCP connection in `ESTABLISHED`. The CLI only
+  ever reacted to `close` and `error`, answered pings with pongs, and had no
+  deadline of its own, so from where it stood the connection was open, quiet,
+  and fine. The server pings every 30 s and reaps after 60 s without a pong;
+  that contract only helps when the close actually reaches the client, and on
+  a half-open socket it never does. Nothing on either side had a reason to
+  say anything.
+- **Client-side liveness watchdog.** Every frame the server sends — pings
+  included — is proof of life. Ninety seconds without one (three missed pings,
+  comfortably past the server's own reaper) means the connection is dead
+  whatever the kernel thinks: the CLI logs
+  `… no server ping for 90s — reconnecting`, tears the socket down with
+  `terminate()` (not `close()`, whose handshake would wait on a peer that is
+  not there), and the ordinary backoff-and-reconnect path runs. `listen` has
+  the same deadline; it has no reconnect loop, so it ends the session with
+  `… no server ping for 90s — connection lost` rather than a counter that
+  quietly stopped moving. The timer dies with the socket, so a reconnect never
+  inherits the previous socket's silence.
+- **TCP keepalive.** Switched on for the connection under the websocket, with
+  a 30 s idle delay, as a kernel-level probe underneath the application-level
+  one. Guarded: a `ws` build that hides its socket, or none at all, simply
+  gets no keepalive rather than a crash on `open`.
+- **A heartbeat in the log.** Every five minutes while connected, `agent run`
+  writes `● connected — last server ping Ns ago`. A stalled daemon now looks
+  different in `agent.log` from a healthy quiet one.
+- **The build reports itself.** The websocket auth frame carries
+  `client_version` (this build's version) alongside `api_key` / `machine` /
+  `subscription_id`, and the upgrade request sends `User-Agent:
+  prohost-cli/<version>` like every HTTP call already did. The failing daemon
+  was two minor versions behind npm the whole time and nobody could tell.
+- **An upgrade notice.** At `agent run` startup the CLI asks the npm registry
+  for the latest version, with a 3 s budget, and prints
+  `⬆ @prohost/cli <latest> is available (running <current>) — npm i -g @prohost/cli`
+  when there is one. It is not awaited and cannot fail startup: a slow, down,
+  or nonsensical registry prints nothing.
+- **A stalled handshake is bounded too.** The deadline only starts at `open`,
+  and `ws` has no handshake timeout by default, so `agent run` now gives the
+  handshake 30 s — the same asleep-laptop failure, one step earlier.
+
+A slow reply is no longer reported as a failed run.
+
+- **The second failure, seen the moment the daemon reconnected.** The reply
+  `POST /v1/conversations/{id}/messages` took the server **51,216 ms** and
+  returned 202 — the message was saved — but the CLI had abandoned the request
+  at its 30 s deadline, logged `✗ run … reply rejected (HTTP 0) This operation
+  was aborted`, and completed the run as failed. The server then posted a
+  "picked this up but its run failed — posting the reply failed with HTTP 0"
+  note directly under an answer that had in fact landed. Two consecutive runs.
+  The slow send path is being fixed server-side; this release stops the client
+  turning a slow success into a reported failure.
+- **120 s for the reply and the completion.** Cheap calls (heartbeats) keep
+  30 s. Four times the observed latency is the margin.
+- **No answer is not a failure — replay with the same key.** The reply POST
+  was already keyed on the run id (`Idempotency-Key: prohost-cli-run-<run_id>`),
+  which is exactly what makes asking again safe. On a timeout or a network
+  error the CLI now logs `… reply POST timed out after 120s — replaying with
+  the same idempotency key` and sends the byte-identical request once more.
+  The server answers with the cached response of the attempt that landed
+  (`✓ reply confirmed on replay`), or with `409 idempotency_key_in_flight` if
+  the first attempt is still being processed — in which case the CLI waits
+  5 s and replays once more. Only a definitive answer, or a second transport
+  failure, reports the run as failed, and it does so exactly once.
+- **`HTTP 0` is gone from the log.** A request with no response now says why:
+  `timed out after 120s` or `network error: <cause>`, in the log line and in
+  the failure reason the server shows in the thread.
+
 ## 0.4.2
 
 Isolated Codex runs no longer receive the operator's **apps (connectors)**.

package/README.md

@@ -525,6 +525,16 @@ On macOS this writes a launchd agent to
 `$PROHOST_HOME/agent.log` — the first place to look when the agent is quiet.
 Re-running it with a different `--exec` replaces the old daemon.
 
+**It notices when the connection dies, even when the network doesn't say so.**
+The server pings every 30 seconds. If no frame of any kind arrives for 90
+seconds — a laptop that slept through the server closing the socket looks
+exactly like this — the CLI logs `… no server ping for 90s — reconnecting`,
+drops the socket and reconnects with backoff. While connected it writes
+`● connected — last server ping Ns ago` every five minutes, so a healthy quiet
+daemon and a stalled one read differently in `agent.log`. At startup it also
+checks npm and prints one line if a newer `@prohost/cli` exists; the check
+never delays or fails the connection.
+
 The daemon is scoped to `$PROHOST_HOME`, because that's where the one credential
 lives: installing twice from the same home replaces the daemon rather than
 adding a second one. To run two agents on one machine, give each its own

package/dist/agent/api.d.ts

@@ -13,13 +13,23 @@ export interface ApiOptions {
     baseUrl: string;
     apiKey: string;
     fetchImpl?: typeof fetch;
-    /** Per-request timeout. Defaults to 30 seconds. */
+    /**
+     * Per-request timeout override, applied to every call. Unset, each call
+     * uses its own default — {@link DEFAULT_TIMEOUT_MS} for the cheap ones,
+     * {@link SEND_TIMEOUT_MS} for the reply and the completion.
+     */
     timeoutMs?: number;
 }
 export interface ApiResult {
     ok: boolean;
+    /** HTTP status, or ``0`` when no response arrived at all — see ``failure``. */
     status: number;
     error?: string;
+    /**
+     * Why ``status`` is ``0``: the request was abandoned at its deadline, or the
+     * network failed before any status came back. Absent on every real response.
+     */
+    failure?: 'timeout' | 'network';
     /**
      * The response body, when the caller asked for it.
      *
@@ -28,6 +38,35 @@ export interface ApiResult {
      */
     body?: string;
 }
+/** Deadline for the cheap calls — a heartbeat answers in milliseconds. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Deadline for the reply POST and the completion.
+ *
+ * Thirty seconds was not enough. On 2026-09-01 the server took 51,216 ms to
+ * accept a reply (``POST /v1/conversations/{id}/messages`` → 202): the
+ * message was saved, but the CLI had already abandoned the request at 30 s,
+ * logged the reply as rejected, and completed the run as failed — so the
+ * server posted a "run failed" note under an answer that had in fact landed.
+ * Twice in a row. The slow send path is being fixed server-side; the client's
+ * job is to not turn a slow success into a reported failure, and four times
+ * the observed latency is the margin for that.
+ */
+export declare const SEND_TIMEOUT_MS = 120000;
+/**
+ * One line a person can act on for a failed result: ``HTTP 503``, ``timed
+ * out after 120s``, ``network error: ECONNRESET``. ``HTTP 0`` told nobody
+ * anything, and it was the only thing the log said for the whole of the
+ * 30-second-timeout incident.
+ */
+export declare function describeFailure(result: ApiResult): string;
+/**
+ * The server's "same key, same body, the first attempt is still being
+ * processed" answer (``api_public/middleware/idempotency.py``). A replay that
+ * gets this should wait and replay again — the original will finish and be
+ * cached, and the next replay receives its response.
+ */
+export declare function isIdempotencyInFlight(result: ApiResult): boolean;
 /**
  * Post the agent's reply into the conversation that triggered the run.
  *
@@ -69,6 +108,7 @@ export type HeartbeatOutcome =
     kind: 'error';
     status: number;
     detail?: string;
+    failure?: ApiResult['failure'];
 };
 /**
  * Tell the server a run is still being worked on, and ask whether it should be.

package/dist/agent/api.js

@@ -11,13 +11,52 @@
  */
 import { USER_AGENT } from '../version.js';
 import { MAX_ERROR_CHARS, MAX_PROGRESS_CHARS, RUN_STATUS_FAILED, RUN_STATUS_SUCCEEDED, } from './contract.js';
-const DEFAULT_TIMEOUT_MS = 30_000;
+/** Deadline for the cheap calls — a heartbeat answers in milliseconds. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Deadline for the reply POST and the completion.
+ *
+ * Thirty seconds was not enough. On 2026-09-01 the server took 51,216 ms to
+ * accept a reply (``POST /v1/conversations/{id}/messages`` → 202): the
+ * message was saved, but the CLI had already abandoned the request at 30 s,
+ * logged the reply as rejected, and completed the run as failed — so the
+ * server posted a "run failed" note under an answer that had in fact landed.
+ * Twice in a row. The slow send path is being fixed server-side; the client's
+ * job is to not turn a slow success into a reported failure, and four times
+ * the observed latency is the margin for that.
+ */
+export const SEND_TIMEOUT_MS = 120_000;
 /** 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) {
+/**
+ * One line a person can act on for a failed result: ``HTTP 503``, ``timed
+ * out after 120s``, ``network error: ECONNRESET``. ``HTTP 0`` told nobody
+ * anything, and it was the only thing the log said for the whole of the
+ * 30-second-timeout incident.
+ */
+export function describeFailure(result) {
+    if (result.failure === 'timeout')
+        return result.error ?? 'timed out';
+    if (result.failure === 'network')
+        return `network error: ${result.error ?? 'unknown'}`;
+    if (result.status === 0)
+        return `network error: ${result.error ?? 'unknown'}`;
+    return `HTTP ${result.status}`;
+}
+/**
+ * The server's "same key, same body, the first attempt is still being
+ * processed" answer (``api_public/middleware/idempotency.py``). A replay that
+ * gets this should wait and replay again — the original will finish and be
+ * cached, and the next replay receives its response.
+ */
+export function isIdempotencyInFlight(result) {
+    return result.status === 409 && (result.error ?? '').includes('idempotency_key_in_flight');
+}
+async function post(options, path, body, idempotencyKey, captureBody = false, timeoutMs = DEFAULT_TIMEOUT_MS) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const deadlineMs = options.timeoutMs ?? timeoutMs;
+    const timer = setTimeout(() => controller.abort(), deadlineMs);
     try {
         const response = await fetchImpl(`${options.baseUrl.replace(/\/+$/, '')}${path}`, {
             method: 'POST',
@@ -46,9 +85,22 @@ async function post(options, path, body, idempotencyKey, captureBody = false) {
         return { ok, status: response.status, error, body: captureBody ? text : undefined };
     }
     catch (err) {
+        // Our own deadline fired: `fetch` rejects with an AbortError, whose
+        // message ("This operation was aborted") names neither the cause nor the
+        // duration. Say both.
+        const abortError = err instanceof Error && err.name === 'AbortError';
+        if (controller.signal.aborted || abortError) {
+            return {
+                ok: false,
+                status: 0,
+                failure: 'timeout',
+                error: `timed out after ${Math.round(deadlineMs / 1000)}s`,
+            };
+        }
         return {
             ok: false,
             status: 0,
+            failure: 'network',
             error: err instanceof Error ? err.message : String(err),
         };
     }
@@ -72,7 +124,9 @@ export async function postReply(options, path, bodyKey, message, runId, extra) {
     // `extra` first, so the message can never be clobbered by a `body_extra` key
     // that happens to collide with the body field. The reply text is the one
     // thing in this request that must survive.
-    return post(options, path, { ...extra, [bodyKey]: message }, `prohost-cli-run-${runId}`);
+    // Byte-identical on every attempt: the server hashes the body against the
+    // key, so a replay must serialise exactly as the original did.
+    return post(options, path, { ...extra, [bodyKey]: message }, `prohost-cli-run-${runId}`, false, SEND_TIMEOUT_MS);
 }
 function booleanField(body, key) {
     if (!body)
@@ -107,7 +161,7 @@ export async function heartbeatRun(options, path, progress) {
         return { kind: 'unknown' };
     if (result.status === 409)
         return { kind: 'resolved' };
-    return { kind: 'error', status: result.status, detail: result.error };
+    return { kind: 'error', status: result.status, detail: result.error, failure: result.failure };
 }
 /**
  * Report a run's terminal state. Called for every run — including one whose
@@ -121,7 +175,7 @@ export async function completeRun(options, path, outcome) {
     const body = outcome.ok
         ? { status: RUN_STATUS_SUCCEEDED }
         : { status: RUN_STATUS_FAILED, error: outcome.error.slice(0, MAX_ERROR_CHARS) };
-    const result = await post(options, path, body);
+    const result = await post(options, path, body, undefined, false, SEND_TIMEOUT_MS);
     if (result.status === 409)
         return { ...result, ok: true };
     return result;

package/dist/agent/command.js

@@ -13,6 +13,7 @@ import { agentLogPath, buildSystemdUnit, harnessArguments, installLaunchdDaemon,
 import { PairError, runPair } from './pair.js';
 import { CredentialsMissingError, ensureWorkspace, loadCredentials, prohostHome } from './credentials.js';
 import { DEFAULT_EXEC_TIMEOUT_MS, DEFAULT_IDLE_TIMEOUT_MS, runAgentHarness } from './run.js';
+import { announceUpgradeIfAvailable } from '../upgrade.js';
 function flagString(flags, name) {
     const value = flags[name];
     return typeof value === 'string' ? value : undefined;
@@ -306,6 +307,9 @@ async function runCommand(flags) {
     };
     process.on('SIGINT', onSig);
     process.on('SIGTERM', onSig);
+    // Deliberately not awaited: the registry lookup must never delay or fail the
+    // connection. It prints one line if a newer build exists and nothing else.
+    void announceUpgradeIfAvailable((line) => process.stdout.write(`${line}\n`));
     try {
         const metrics = await runAgentHarness({
             exec,

package/dist/agent/heartbeat.js

@@ -21,7 +21,7 @@
  *   failure mode — an old server that 404s, a dropped network, a handler that
  *   throws — costs at most the beat it happened on.
  */
-import { heartbeatRun } from './api.js';
+import { describeFailure, heartbeatRun } from './api.js';
 /**
  * How often each open run is reported.
  *
@@ -154,8 +154,9 @@ export class HeartbeatLoop {
             // Transient by assumption: keep the cadence rather than give up on the
             // run. A run whose beats all fail is reaped server-side eventually, which
             // is the correct end state for a machine that cannot reach the API.
-            this.options.log(`    ! heartbeat for run ${target.runId.slice(0, 12)} failed (HTTP ${outcome.status})` +
-                `${outcome.detail ? ` ${outcome.detail}` : ''}`);
+            this.options.log(`    ! heartbeat for run ${target.runId.slice(0, 12)} failed ` +
+                `(${describeFailure({ ok: false, status: outcome.status, error: outcome.detail, failure: outcome.failure })})` +
+                `${outcome.status !== 0 && outcome.detail ? ` ${outcome.detail}` : ''}`);
         }
         catch (err) {
             this.options.log(`    ! heartbeat for run ${target.runId.slice(0, 12)} threw: ` +

package/dist/agent/run.d.ts

@@ -121,6 +121,16 @@ export interface AgentRunOptions {
      * inside a test's lifetime.
      */
     heartbeatIntervalMs?: number;
+    /**
+     * How long the server may go silent before the socket is torn down and
+     * reconnected. Defaults to {@link PING_LIVENESS_MS}; tests shorten it.
+     */
+    livenessTimeoutMs?: number;
+    /**
+     * How often a connected harness logs that it is still connected. Defaults
+     * to {@link HEARTBEAT_LOG_INTERVAL_MS}; tests shorten it.
+     */
+    heartbeatLogIntervalMs?: number;
 }
 export interface AgentRunMetrics {
     connections: number;
@@ -134,6 +144,8 @@ export interface AgentRunMetrics {
     ignored: number;
     /** Repeat deliveries of a run already handled this session. */
     duplicates: number;
+    /** Sockets torn down locally because the server went silent past the liveness window. */
+    livenessTimeouts: number;
     /**
      * Set when the harness stopped for a reason retrying can't fix (a rejected
      * credential). The CLI exits nonzero on it, so a service manager doesn't

package/dist/agent/run.js

@@ -25,7 +25,7 @@
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import WebSocket from 'ws';
-import { completeRun, postReply } from './api.js';
+import { completeRun, describeFailure, isIdempotencyInFlight, postReply } from './api.js';
 import { MAX_SALVAGE_CHARS, claudeCommand, isClaudeExec, looksLikeResumeFailure, readClaudeStream, writeMcpConfig, } from './claude.js';
 import { APPS_FEATURE, MCP_API_KEY_ENV_VAR, PLUGINS_DISABLED_OVERRIDE, codexBinary, codexCommand, codexMcpInventoryFlag, codexProfileName, codexShellSyntax, extraMcpEntries, isCodexExec, isolateConfiguredServers, listMcpServers, mcpServersOverride, prohostMcpEntry, looksLikeCodexResumeFailure, parseCodexOutput, } from './codex.js';
 import { EXTRA_MCP_FILENAME, loadExtraMcpServers } from './extras.js';
@@ -40,6 +40,8 @@ import { SessionStore, sessionKeyFor } from './sessionstore.js';
 import { verifySignature } from './signature.js';
 import { isWebhookEvent } from '../forward.js';
 import { DEFAULT_WS_URL } from '../listen.js';
+import { ServerLiveness, enableTcpKeepAlive, seconds, terminateSocket } from '../liveness.js';
+import { CLI_VERSION, USER_AGENT } from '../version.js';
 /**
  * Default ceiling on one agent invocation: none.
  *
@@ -74,6 +76,14 @@ export const DEFAULT_IDLE_TIMEOUT_MS = 900_000;
 /** Reconnect backoff — full jitter between ``BASE`` and the current cap. */
 const RECONNECT_BASE_DELAY_MS = 1_000;
 const RECONNECT_MAX_DELAY_MS = 30_000;
+/**
+ * Longest the websocket handshake may take before `ws` gives up on it.
+ *
+ * The liveness deadline only starts at `open`; without this, a connect that
+ * stalls mid-handshake — the same asleep-laptop shape, one step earlier —
+ * would hang with neither `open` nor `close` to move the loop along.
+ */
+const HANDSHAKE_TIMEOUT_MS = 30_000;
 /** Ack status codes reported back over the socket for each frame. */
 const ACK_ACCEPTED = 200;
 const ACK_IGNORED = 204;
@@ -88,6 +98,7 @@ function newMetrics() {
         signatureRejections: 0,
         ignored: 0,
         duplicates: 0,
+        livenessTimeouts: 0,
     };
 }
 function timestamp() {
@@ -130,12 +141,62 @@ async function completeWithRetry(api, path, outcome, log, sleep) {
         const retryable = result.status === 0 || result.status === 429 || result.status >= 500;
         if (!retryable)
             return result;
-        log(`    … completion failed (HTTP ${result.status}); retrying in ${delay / 1000}s`);
+        log(`    … completion failed (${describeFailure(result)}); retrying in ${delay / 1000}s`);
         await sleep(delay);
         result = await completeRun(api, path, outcome);
     }
     return result;
 }
+/**
+ * How long to wait before replaying a reply whose first attempt the server
+ * reports as still in flight. The original request is being processed at
+ * that moment; a few seconds is enough for it to finish and be cached.
+ */
+const REPLAY_IN_FLIGHT_DELAY_MS = 5_000;
+/**
+ * Post the reply, and if the request dies in transit, replay it once with
+ * the same idempotency key before believing it failed.
+ *
+ * A request abandoned at its deadline is not a request that failed — it is
+ * a request whose answer we did not wait for. On 2026-09-01 the server took
+ * 51 s to accept a reply that the CLI had given up on at 30 s; the message
+ * was in the conversation, and the CLI reported the run as failed anyway.
+ * The key (``prohost-cli-run-<run_id>``) already made the send idempotent
+ * server-side, so the correct reaction to "no answer" is to ask again with
+ * the same key and let the server say what happened:
+ *
+ * - a 2xx (fresh, or the cached response of the attempt that did land) —
+ *   the reply is durable, carry on as a success;
+ * - ``409 idempotency_key_in_flight`` — the first attempt is still being
+ *   processed; wait, then replay once more;
+ * - anything else — a real decision or a second transport failure — is the
+ *   answer, and the run is reported failed exactly once.
+ */
+async function postReplyWithReplay(api, send, label, log, sleep) {
+    let posted = await send();
+    // A real answer — success or a decision — is final. Only "no answer at all"
+    // earns a replay.
+    if (posted.ok || posted.status !== 0)
+        return posted;
+    const why = posted.failure === 'timeout'
+        ? `reply POST ${posted.error}`
+        : `reply POST failed (${describeFailure(posted)})`;
+    log(`${timestamp()} … ${label} ${why} — replaying with the same idempotency key`);
+    posted = await send();
+    if (posted.ok) {
+        log(`${timestamp()} ✓ ${label} reply confirmed on replay`);
+        return posted;
+    }
+    if (isIdempotencyInFlight(posted)) {
+        log(`${timestamp()} … ${label} first reply attempt is still in flight server-side — ` +
+            `replaying again in ${REPLAY_IN_FLIGHT_DELAY_MS / 1000}s`);
+        await sleep(REPLAY_IN_FLIGHT_DELAY_MS);
+        posted = await send();
+        if (posted.ok)
+            log(`${timestamp()} ✓ ${label} reply confirmed on replay`);
+    }
+    return posted;
+}
 /**
  * Decide where the agent command runs.
  *
@@ -728,7 +789,8 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         // it, and anything wrapped around it reads as a crash instead of a stop.
         const closed = await completeWithRetry(api, run.completion_path, { ok: false, error: RUN_ERROR_CANCELLED_BY_USER }, log, sleep);
         if (!closed.ok) {
-            log(`    ! could not report the cancellation (HTTP ${closed.status}) ${closed.error ?? ''}`);
+            log(`    ! could not report the cancellation (${describeFailure(closed)})` +
+                `${closed.status !== 0 && closed.error ? ` ${closed.error}` : ''}`);
             return 'unreported';
         }
         return 'cancelled';
@@ -745,7 +807,8 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         }
         const completed = await completeWithRetry(api, run.completion_path, { ok: false, error: detail ? `${reason}: ${detail}` : reason }, log, sleep);
         if (!completed.ok) {
-            log(`    ! could not report failure (HTTP ${completed.status}) ${completed.error ?? ''}`);
+            log(`    ! could not report failure (${describeFailure(completed)})` +
+                `${completed.status !== 0 && completed.error ? ` ${completed.error}` : ''}`);
             return 'unreported';
         }
         return 'failed';
@@ -772,7 +835,7 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
             log(`    │ ${line}`);
         const completed = await completeWithRetry(api, run.completion_path, { ok: true }, log, sleep);
         if (!completed.ok) {
-            log(`    ! could not mark the run complete (HTTP ${completed.status})`);
+            log(`    ! could not mark the run complete (${describeFailure(completed)})`);
             return 'unreported';
         }
         if (result.sessionId) {
@@ -780,16 +843,20 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         }
         return 'succeeded';
     }
-    const posted = await postReply(api, run.reply_path, run.reply_body_key, reply, run.run_id, run.reply_body_extra);
+    const replyPath = run.reply_path;
+    const replyBodyKey = run.reply_body_key;
+    const posted = await postReplyWithReplay(api, () => postReply(api, replyPath, replyBodyKey, reply, run.run_id, run.reply_body_extra), label, log, sleep);
     if (!posted.ok) {
-        log(`${timestamp()} ✗ ${label} reply rejected (HTTP ${posted.status}) ${posted.error ?? ''}`);
+        const failure = describeFailure(posted);
+        const detail = posted.status === 0 ? '' : ` ${posted.error ?? ''}`;
+        log(`${timestamp()} ✗ ${label} reply rejected (${failure})${detail}`);
         // Undo the mid-run recording. The session exists and the agent's transcript
         // holds this turn, but the conversation never received its answer, so
         // continuing it would skip reasoning nobody can see — the same rule that
         // used to be expressed by simply not recording until the reply landed.
         if (result.sessionRecorded)
             runtime.sessions.forget(sessionKeyFor(run));
-        const reported = await completeWithRetry(api, run.completion_path, { ok: false, error: `posting the reply failed with HTTP ${posted.status}` }, log, sleep);
+        const reported = await completeWithRetry(api, run.completion_path, { ok: false, error: `posting the reply failed: ${failure}` }, log, sleep);
         return reported.ok ? 'failed' : 'unreported';
     }
     // Advance continuity only after the answer is durable on its reply surface.
@@ -804,7 +871,7 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         // failure, not a lost answer — say so precisely. Returning false lets the
         // caller forget the run so a redelivery can retry the completion; the
         // reply's idempotency key stops that from posting twice.
-        log(`${timestamp()} ! ${label} replied, but marking it complete failed (HTTP ${completed.status})`);
+        log(`${timestamp()} ! ${label} replied, but marking it complete failed (${describeFailure(completed)})`);
         return 'unreported';
     }
     log(`${timestamp()} ✓ ${label} replied in ${seconds}s (${reply.length} chars)`);
@@ -945,7 +1012,11 @@ export async function runAgentHarness(options) {
     return metrics;
     /** One socket lifetime. Resolves ``true`` when the session ever authed. */
     function connectOnce() {
-        const ws = new Ctor(url);
+        // The `User-Agent` names the build server-side, the same as every HTTP
+        // call this CLI makes; `client_version` in the auth frame is the copy the
+        // server reads, because a header on an upgrade request is easy to lose in
+        // proxies and logs and a frame field is not.
+        const ws = new Ctor(url, { headers: { 'User-Agent': USER_AGENT }, handshakeTimeout: HANDSHAKE_TIMEOUT_MS });
         let authed = false;
         return new Promise((resolve) => {
             const close = () => {
@@ -962,7 +1033,33 @@ export async function runAgentHarness(options) {
                 else
                     options.signal.addEventListener('abort', close, { once: true });
             }
+            // The server pings every 30 s and reaps after 60 s without a pong — but
+            // that close never reaches a client whose kernel still believes the
+            // connection is up (a laptop that slept through the FIN). Keep our own
+            // deadline: no frame of any kind for the window means the socket is
+            // dead, and tearing it down here is what makes the reconnect loop run.
+            const liveness = new ServerLiveness({
+                timeoutMs: options.livenessTimeoutMs,
+                heartbeatIntervalMs: options.heartbeatLogIntervalMs,
+                onSilence: (silentMs) => {
+                    metrics.livenessTimeouts += 1;
+                    log(`${timestamp()} … no server ping for ${seconds(silentMs)}s — reconnecting`);
+                    terminateSocket(ws);
+                },
+                onHeartbeat: (state) => {
+                    if (!authed)
+                        return;
+                    const since = state.sinceLastPingMs === undefined
+                        ? `no server ping yet (connected ${seconds(state.sinceLastFrameMs)}s ago)`
+                        : `last server ping ${seconds(state.sinceLastPingMs)}s ago`;
+                    log(`${timestamp()} ● connected — ${since}`);
+                },
+            });
             ws.on('open', () => {
+                // Kernel-level probe underneath the application-level one: a dead
+                // peer is detected by the TCP stack even while the socket is idle.
+                enableTcpKeepAlive(ws);
+                liveness.start();
                 // `subscription_id` is a presence signal, not a scoping one: the server
                 // derives which subscription's events this socket receives from the
                 // connection itself. Sending it stamps `connected_from` with this
@@ -972,6 +1069,7 @@ export async function runAgentHarness(options) {
                     type: 'auth',
                     api_key: options.credentials.api_key,
                     machine,
+                    client_version: CLI_VERSION,
                     ...(options.credentials.subscription_id
                         ? { subscription_id: options.credentials.subscription_id }
                         : {}),
@@ -983,11 +1081,16 @@ export async function runAgentHarness(options) {
                     frame = JSON.parse(data.toString());
                 }
                 catch {
+                    // Unparseable, but the server sent it: still proof it is there.
+                    liveness.observe(undefined);
                     return;
                 }
-                if (!frame || typeof frame !== 'object')
+                if (!frame || typeof frame !== 'object') {
+                    liveness.observe(undefined);
                     return;
+                }
                 const f = frame;
+                liveness.observe(f.type);
                 if (f.type === 'auth_ok') {
                     authed = true;
                     const name = options.credentials.agent?.name ?? 'agent';
@@ -1161,6 +1264,7 @@ export async function runAgentHarness(options) {
                 });
             });
             ws.on('close', () => {
+                liveness.stop();
                 if (options.signal)
                     options.signal.removeEventListener('abort', close);
                 resolve(authed);

package/dist/listen.d.ts

@@ -31,12 +31,19 @@ export interface ListenOptions {
      * and the final status has been emitted.
      */
     signal?: AbortSignal;
+    /**
+     * How long the server may go silent before the socket is torn down.
+     * Defaults to {@link PING_LIVENESS_MS}; tests shorten it.
+     */
+    livenessTimeoutMs?: number;
 }
 export interface ListenMetrics {
     connected: boolean;
     eventsReceived: number;
     eventsForwarded: number;
     forwardErrors: number;
+    /** Set when the listener ended because the server went silent, not because it closed. */
+    livenessTimeout?: boolean;
 }
 /**
  * `/ws/webhooks` is served by **api_public**, which is `connect.prohost.ai` —

package/dist/listen.js

@@ -5,6 +5,8 @@
 import os from 'node:os';
 import WebSocket from 'ws';
 import { forwardEvent, isWebhookEvent } from './forward.js';
+import { ServerLiveness, enableTcpKeepAlive, seconds, terminateSocket } from './liveness.js';
+import { CLI_VERSION, USER_AGENT } from './version.js';
 /**
  * `/ws/webhooks` is served by **api_public**, which is `connect.prohost.ai` —
  * the same host as {@link DEFAULT_API_BASE_URL}. It is NOT on `api.prohost.ai`
@@ -35,7 +37,7 @@ export async function runListen(options) {
         eventsForwarded: 0,
         forwardErrors: 0,
     };
-    const ws = new Ctor(url);
+    const ws = new Ctor(url, { headers: { 'User-Agent': USER_AGENT } });
     return new Promise((resolve) => {
         const status = () => {
             const dot = metrics.connected ? '\u25CF' : '\u25CB';
@@ -55,11 +57,27 @@ export async function runListen(options) {
             else
                 options.signal.addEventListener('abort', closeWith, { once: true });
         }
+        // Same contract as the agent harness (see `liveness.ts`): the server's
+        // 60 s reaper cannot close a socket whose FIN never reached us, so keep a
+        // client-side deadline. `listen` has no reconnect loop \u2014 it resolves on
+        // close and the operator restarts it \u2014 so this ends the session with a
+        // reason on screen instead of a counter that silently stopped moving.
+        const liveness = new ServerLiveness({
+            timeoutMs: options.livenessTimeoutMs,
+            onSilence: (silentMs) => {
+                metrics.livenessTimeout = true;
+                onStatus(`\n\u2026 no server ping for ${seconds(silentMs)}s \u2014 connection lost\n`);
+                terminateSocket(ws);
+            },
+        });
         ws.on('open', () => {
+            enableTcpKeepAlive(ws);
+            liveness.start();
             const authFrame = {
                 type: 'auth',
                 api_key: options.apiKey,
                 machine,
+                client_version: CLI_VERSION,
                 ...(options.subscriptionId ? { subscription_id: options.subscriptionId } : {}),
             };
             ws.send(JSON.stringify(authFrame));
@@ -70,11 +88,15 @@ export async function runListen(options) {
                 frame = JSON.parse(data.toString());
             }
             catch {
+                liveness.observe(undefined);
                 return;
             }
-            if (!frame || typeof frame !== 'object')
+            if (!frame || typeof frame !== 'object') {
+                liveness.observe(undefined);
                 return;
+            }
             const f = frame;
+            liveness.observe(f.type);
             if (f.type === 'auth_ok') {
                 metrics.connected = true;
                 status();
@@ -114,6 +136,7 @@ export async function runListen(options) {
             }
         });
         ws.on('close', () => {
+            liveness.stop();
             metrics.connected = false;
             status();
             resolve(metrics);

package/dist/liveness.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Client-side liveness for the event-stream socket.
+ *
+ * The server pings every 30 seconds and closes a socket that has not answered
+ * for 60. That contract only helps when the close actually arrives. A laptop
+ * that sleeps loses the server's FIN, the kernel keeps the TCP connection in
+ * ESTABLISHED, and `ws` — which reacts to `close` and `error` alone — sees a
+ * socket that is open, quiet, and never coming back. One paired agent sat on
+ * exactly that for three weeks: connected as far as the client could tell,
+ * unreachable as far as the server was concerned, and nothing on either side
+ * with a reason to say so.
+ *
+ * So the client keeps its own deadline. Every frame the server sends — pings
+ * included — is a proof of life; ninety seconds without one (three missed
+ * pings, comfortably past the server's own 60 s reaper) means the connection
+ * is dead whatever the kernel thinks, and the socket is torn down locally so
+ * the ordinary reconnect path runs. TCP keepalive is switched on as a second,
+ * kernel-level probe, and a periodic heartbeat line makes a stalled daemon
+ * visible in its log instead of indistinguishable from a healthy quiet one.
+ */
+/** Silence tolerated before the socket is declared dead: three missed pings. */
+export declare const PING_LIVENESS_MS = 90000;
+/** Delay before the kernel starts sending TCP keepalive probes on an idle socket. */
+export declare const TCP_KEEPALIVE_DELAY_MS = 30000;
+/** How often a connected harness writes its "still here" line. */
+export declare const HEARTBEAT_LOG_INTERVAL_MS = 300000;
+/**
+ * The slice of a `ws` client this module touches — narrow so that the test
+ * doubles, which implement only what the harness calls, satisfy it too.
+ */
+export interface LivenessSocket {
+    close(): void;
+    /** `ws` has it; the handwritten test doubles may not. */
+    terminate?(): void;
+}
+export interface LivenessOptions {
+    /** Silence window before {@link ServerLiveness.onSilence} fires. */
+    timeoutMs?: number;
+    /** Cadence of {@link ServerLiveness.onHeartbeat}. Tests shorten it. */
+    heartbeatIntervalMs?: number;
+    /** Clock, injectable so a test can age the connection without waiting. */
+    now?: () => number;
+    /** Called once when the window elapses with no frame. Receives the silence in ms. */
+    onSilence: (silentMs: number) => void;
+    /** Called on each heartbeat tick with the liveness state of the moment. */
+    onHeartbeat?: (state: LivenessState) => void;
+}
+export interface LivenessState {
+    /** Milliseconds since the last frame of any kind from the server. */
+    sinceLastFrameMs: number;
+    /** Milliseconds since the last `ping` — `undefined` before the first one. */
+    sinceLastPingMs: number | undefined;
+}
+/**
+ * Tracks the server's frames for one socket lifetime and fires when they stop.
+ *
+ * Owns two timers: the silence deadline, re-armed on every frame, and the
+ * heartbeat interval. Both are cleared by {@link stop}, which the socket's
+ * `close` handler must call — a timer left running after a reconnect would
+ * tear down the *next* socket for the previous one's silence.
+ */
+export declare class ServerLiveness {
+    private readonly timeoutMs;
+    private readonly heartbeatIntervalMs;
+    private readonly now;
+    private readonly onSilence;
+    private readonly onHeartbeat;
+    private lastFrameAt;
+    private lastPingAt;
+    private deadline;
+    private heartbeat;
+    private stopped;
+    constructor(options: LivenessOptions);
+    /**
+     * Arm the deadline. Called on `open`: the handshake completing is itself the
+     * first proof of life, and `ws` has its own timeout for a handshake that
+     * never completes.
+     */
+    start(): void;
+    /** Record a frame from the server. Any frame counts; a `ping` is also remembered as one. */
+    observe(frameType: unknown): void;
+    /** Release both timers. Idempotent; safe to call from `close` however the socket ended. */
+    stop(): void;
+    state(): LivenessState;
+    private arm;
+}
+/**
+ * Tear a socket down without the closing handshake.
+ *
+ * `close()` sends a close frame and then waits for the peer's — on a half-open
+ * connection that never comes, and `ws` only gives up on it after its own 30 s
+ * timer. `terminate()` destroys the underlying socket immediately, which is
+ * the right thing for a peer we have already decided is not there. The test
+ * doubles have no `terminate`, so fall back to `close`.
+ */
+export declare function terminateSocket(ws: LivenessSocket): void;
+/**
+ * Switch on TCP keepalive for the connection under a `ws` client.
+ *
+ * Reaches into `ws`'s private `_socket` — there is no public accessor — so
+ * everything is guarded: a build of `ws` that renames it, or a test double
+ * that has none, simply gets no keepalive rather than a crash on `open`.
+ * Returns whether the kernel-level probe was actually enabled.
+ */
+export declare function enableTcpKeepAlive(ws: unknown, delayMs?: number): boolean;
+/** Whole seconds, for log lines. */
+export declare function seconds(ms: number): number;

package/dist/liveness.js

@@ -0,0 +1,156 @@
+/**
+ * Client-side liveness for the event-stream socket.
+ *
+ * The server pings every 30 seconds and closes a socket that has not answered
+ * for 60. That contract only helps when the close actually arrives. A laptop
+ * that sleeps loses the server's FIN, the kernel keeps the TCP connection in
+ * ESTABLISHED, and `ws` — which reacts to `close` and `error` alone — sees a
+ * socket that is open, quiet, and never coming back. One paired agent sat on
+ * exactly that for three weeks: connected as far as the client could tell,
+ * unreachable as far as the server was concerned, and nothing on either side
+ * with a reason to say so.
+ *
+ * So the client keeps its own deadline. Every frame the server sends — pings
+ * included — is a proof of life; ninety seconds without one (three missed
+ * pings, comfortably past the server's own 60 s reaper) means the connection
+ * is dead whatever the kernel thinks, and the socket is torn down locally so
+ * the ordinary reconnect path runs. TCP keepalive is switched on as a second,
+ * kernel-level probe, and a periodic heartbeat line makes a stalled daemon
+ * visible in its log instead of indistinguishable from a healthy quiet one.
+ */
+/** Silence tolerated before the socket is declared dead: three missed pings. */
+export const PING_LIVENESS_MS = 90_000;
+/** Delay before the kernel starts sending TCP keepalive probes on an idle socket. */
+export const TCP_KEEPALIVE_DELAY_MS = 30_000;
+/** How often a connected harness writes its "still here" line. */
+export const HEARTBEAT_LOG_INTERVAL_MS = 300_000;
+/**
+ * Tracks the server's frames for one socket lifetime and fires when they stop.
+ *
+ * Owns two timers: the silence deadline, re-armed on every frame, and the
+ * heartbeat interval. Both are cleared by {@link stop}, which the socket's
+ * `close` handler must call — a timer left running after a reconnect would
+ * tear down the *next* socket for the previous one's silence.
+ */
+export class ServerLiveness {
+    timeoutMs;
+    heartbeatIntervalMs;
+    now;
+    onSilence;
+    onHeartbeat;
+    lastFrameAt;
+    lastPingAt;
+    deadline;
+    heartbeat;
+    stopped = false;
+    constructor(options) {
+        this.timeoutMs = options.timeoutMs ?? PING_LIVENESS_MS;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? HEARTBEAT_LOG_INTERVAL_MS;
+        this.now = options.now ?? Date.now;
+        this.onSilence = options.onSilence;
+        this.onHeartbeat = options.onHeartbeat;
+        this.lastFrameAt = this.now();
+    }
+    /**
+     * Arm the deadline. Called on `open`: the handshake completing is itself the
+     * first proof of life, and `ws` has its own timeout for a handshake that
+     * never completes.
+     */
+    start() {
+        if (this.stopped)
+            return;
+        this.lastFrameAt = this.now();
+        this.arm();
+        if (this.onHeartbeat && this.heartbeat === undefined) {
+            this.heartbeat = setInterval(() => this.onHeartbeat?.(this.state()), this.heartbeatIntervalMs);
+            this.heartbeat.unref?.();
+        }
+    }
+    /** Record a frame from the server. Any frame counts; a `ping` is also remembered as one. */
+    observe(frameType) {
+        if (this.stopped)
+            return;
+        this.lastFrameAt = this.now();
+        if (frameType === 'ping')
+            this.lastPingAt = this.lastFrameAt;
+        if (this.deadline !== undefined)
+            this.arm();
+    }
+    /** Release both timers. Idempotent; safe to call from `close` however the socket ended. */
+    stop() {
+        this.stopped = true;
+        if (this.deadline !== undefined)
+            clearTimeout(this.deadline);
+        if (this.heartbeat !== undefined)
+            clearInterval(this.heartbeat);
+        this.deadline = undefined;
+        this.heartbeat = undefined;
+    }
+    state() {
+        const now = this.now();
+        return {
+            sinceLastFrameMs: now - this.lastFrameAt,
+            sinceLastPingMs: this.lastPingAt === undefined ? undefined : now - this.lastPingAt,
+        };
+    }
+    arm() {
+        if (this.deadline !== undefined)
+            clearTimeout(this.deadline);
+        this.deadline = setTimeout(() => {
+            this.deadline = undefined;
+            if (this.stopped)
+                return;
+            // Stop before firing: the callback tears the socket down, and the close
+            // handler that follows calls stop() again — harmless, but the deadline
+            // must not be re-armed by a frame that races the teardown.
+            this.stop();
+            this.onSilence(this.now() - this.lastFrameAt);
+        }, this.timeoutMs);
+        this.deadline.unref?.();
+    }
+}
+/**
+ * Tear a socket down without the closing handshake.
+ *
+ * `close()` sends a close frame and then waits for the peer's — on a half-open
+ * connection that never comes, and `ws` only gives up on it after its own 30 s
+ * timer. `terminate()` destroys the underlying socket immediately, which is
+ * the right thing for a peer we have already decided is not there. The test
+ * doubles have no `terminate`, so fall back to `close`.
+ */
+export function terminateSocket(ws) {
+    try {
+        if (typeof ws.terminate === 'function')
+            ws.terminate();
+        else
+            ws.close();
+    }
+    catch {
+        /* already gone */
+    }
+}
+/**
+ * Switch on TCP keepalive for the connection under a `ws` client.
+ *
+ * Reaches into `ws`'s private `_socket` — there is no public accessor — so
+ * everything is guarded: a build of `ws` that renames it, or a test double
+ * that has none, simply gets no keepalive rather than a crash on `open`.
+ * Returns whether the kernel-level probe was actually enabled.
+ */
+export function enableTcpKeepAlive(ws, delayMs = TCP_KEEPALIVE_DELAY_MS) {
+    try {
+        const socket = ws
+            ._socket;
+        if (!socket || typeof socket.setKeepAlive !== 'function')
+            return false;
+        socket.setKeepAlive(true, delayMs);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whole seconds, for log lines. */
+export function seconds(ms) {
+    return Math.round(ms / 1000);
+}

package/dist/upgrade.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Best-effort "a newer build exists" notice for `agent run`.
+ *
+ * A daemon installed with `npm i -g` never upgrades itself, and nothing in the
+ * product can tell an operator which build their machine is on: the one that
+ * sat on a dead socket for three weeks was two minor versions behind the
+ * registry the whole time. The auth frame now reports the version server-side;
+ * this is the client-side half — one registry lookup at startup, printed as a
+ * single line when it finds something newer, and silent on every other
+ * outcome. It never delays the connection and cannot fail startup: the
+ * registry being slow, down, or answering nonsense is not the operator's
+ * problem and must not become one.
+ */
+export declare const NPM_LATEST_URL = "https://registry.npmjs.org/@prohost/cli/latest";
+/** Longest the registry gets. The socket does not wait on this. */
+export declare const UPGRADE_CHECK_TIMEOUT_MS = 3000;
+export interface UpgradeCheckOptions {
+    /** The running build. Defaults to {@link CLI_VERSION}; tests pin it. */
+    currentVersion?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    registryUrl?: string;
+}
+/**
+ * Compare two `MAJOR.MINOR.PATCH[-prerelease]` strings the way npm orders them
+ * for the cases this check meets: numeric identifiers compared as numbers,
+ * missing ones as zero, and a prerelease sorting *before* its release. Returns
+ * a negative number when `a` is older, positive when newer, `0` when equal.
+ * Not a full semver implementation — build metadata and prerelease ordering
+ * are not needed to answer "is the registry ahead of me".
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Ask the registry for the latest published version.
+ *
+ * Resolves to the version string when it is strictly newer than the running
+ * build, and `undefined` for everything else — up to date, ahead of the
+ * registry (a local build), a timeout, a non-2xx, a malformed body. It never
+ * rejects.
+ */
+export declare function newerVersionAvailable(options?: UpgradeCheckOptions): Promise<string | undefined>;
+/** The one line printed when a newer build exists. */
+export declare function upgradeNotice(latest: string, current?: string): string;
+/**
+ * Run the check without waiting for it: prints the notice if and when one is
+ * due, and otherwise does nothing. The returned promise is for tests; callers
+ * on the startup path drop it.
+ */
+export declare function announceUpgradeIfAvailable(write: (line: string) => void, options?: UpgradeCheckOptions): Promise<void>;

package/dist/upgrade.js

@@ -0,0 +1,99 @@
+/**
+ * Best-effort "a newer build exists" notice for `agent run`.
+ *
+ * A daemon installed with `npm i -g` never upgrades itself, and nothing in the
+ * product can tell an operator which build their machine is on: the one that
+ * sat on a dead socket for three weeks was two minor versions behind the
+ * registry the whole time. The auth frame now reports the version server-side;
+ * this is the client-side half — one registry lookup at startup, printed as a
+ * single line when it finds something newer, and silent on every other
+ * outcome. It never delays the connection and cannot fail startup: the
+ * registry being slow, down, or answering nonsense is not the operator's
+ * problem and must not become one.
+ */
+import { CLI_VERSION, USER_AGENT } from './version.js';
+export const NPM_LATEST_URL = 'https://registry.npmjs.org/@prohost/cli/latest';
+/** Longest the registry gets. The socket does not wait on this. */
+export const UPGRADE_CHECK_TIMEOUT_MS = 3_000;
+/**
+ * Compare two `MAJOR.MINOR.PATCH[-prerelease]` strings the way npm orders them
+ * for the cases this check meets: numeric identifiers compared as numbers,
+ * missing ones as zero, and a prerelease sorting *before* its release. Returns
+ * a negative number when `a` is older, positive when newer, `0` when equal.
+ * Not a full semver implementation — build metadata and prerelease ordering
+ * are not needed to answer "is the registry ahead of me".
+ */
+export function compareVersions(a, b) {
+    const parse = (v) => {
+        const [core = '', prerelease] = v.trim().replace(/^v/, '').split('-', 2);
+        const parts = core.split('.').map((p) => {
+            const n = Number.parseInt(p, 10);
+            return Number.isFinite(n) ? n : 0;
+        });
+        return { parts, prerelease: prerelease !== undefined && prerelease !== '' };
+    };
+    const left = parse(a);
+    const right = parse(b);
+    for (let i = 0; i < Math.max(left.parts.length, right.parts.length); i += 1) {
+        const diff = (left.parts[i] ?? 0) - (right.parts[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    if (left.prerelease === right.prerelease)
+        return 0;
+    return left.prerelease ? -1 : 1;
+}
+/**
+ * Ask the registry for the latest published version.
+ *
+ * Resolves to the version string when it is strictly newer than the running
+ * build, and `undefined` for everything else — up to date, ahead of the
+ * registry (a local build), a timeout, a non-2xx, a malformed body. It never
+ * rejects.
+ */
+export async function newerVersionAvailable(options = {}) {
+    const current = options.currentVersion ?? CLI_VERSION;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? UPGRADE_CHECK_TIMEOUT_MS);
+    timer.unref?.();
+    try {
+        const response = await fetchImpl(options.registryUrl ?? NPM_LATEST_URL, {
+            method: 'GET',
+            headers: { Accept: 'application/json', 'User-Agent': USER_AGENT },
+            signal: controller.signal,
+        });
+        if (response.status < 200 || response.status >= 300)
+            return undefined;
+        const body = await response.json();
+        const latest = body && typeof body === 'object' ? body.version : undefined;
+        if (typeof latest !== 'string' || !/^\d+\.\d+\.\d+/.test(latest))
+            return undefined;
+        return compareVersions(latest, current) > 0 ? latest : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The one line printed when a newer build exists. */
+export function upgradeNotice(latest, current = CLI_VERSION) {
+    return `⬆ @prohost/cli ${latest} is available (running ${current}) — npm i -g @prohost/cli`;
+}
+/**
+ * Run the check without waiting for it: prints the notice if and when one is
+ * due, and otherwise does nothing. The returned promise is for tests; callers
+ * on the startup path drop it.
+ */
+export function announceUpgradeIfAvailable(write, options = {}) {
+    return newerVersionAvailable(options)
+        .then((latest) => {
+        if (latest)
+            write(upgradeNotice(latest, options.currentVersion ?? CLI_VERSION));
+    })
+        .catch(() => {
+        /* never surfaces — see the module comment */
+    });
+}

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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