@prohost/cli 0.4.1 → 0.5.0

package/dist/agent/codex.js

@@ -524,6 +524,67 @@ export function listMcpServers(binary, runner, overrides, cwd) {
         return null;
     }
 }
+/**
+ * The Codex feature that supplies the `codex_apps` MCP.
+ *
+ * Its own prompt text is the definition, and it is worth quoting because
+ * nothing else in the CLI says it: *"An app is equivalent to a set of MCP tools
+ * within the `codex_apps` MCP."* Apps are the operator's **connectors** —
+ * account-level, not config-level.
+ */
+export const APPS_FEATURE = 'apps';
+/**
+ * Read one feature's *effective* state, under the overrides the run will carry.
+ *
+ * This is {@link listMcpServers}'s counterpart for the thing that listing cannot
+ * see, and it exists because `codex_apps` appears in **no** MCP inventory:
+ * `codex mcp list --json` reports the operator's servers and says nothing about
+ * apps, so the entire 0.4.1 verification path is blind to 28 tools the run
+ * actually gets.
+ *
+ * `codex features list` answers it — it prints `<name> <stage> <state>` per
+ * feature and honours `-c`, so asking it under the run's own overrides turns
+ * "did the switch take" into a measurement rather than an assumption. Measured
+ * at ~0.14s with no network, so it is cheap enough to run every time.
+ *
+ * Only the one requested row is read, deliberately unlike `listMcpServers`,
+ * which fails the whole answer on a single malformed entry. There the *set* is
+ * the boundary, so an unparsed member is a hole; here the question is about one
+ * named key, and refusing to answer because some unrelated future row gained a
+ * column would break every run to protect nothing. The last whitespace-separated
+ * token is the state — the stage column is sometimes two words (`under
+ * development`), so the row is read from both ends rather than by field index.
+ *
+ * Returns `null` when the answer is unknown: the command failed (a malformed
+ * override makes `features list` exit 1 and print nothing), the feature has no
+ * row, or its state is not a boolean. A renamed or retired feature therefore
+ * reads as unknown rather than as "off", and the caller fails the run closed.
+ */
+export function featureState(binary, runner, feature, overrides, cwd) {
+    const list = overrides === undefined ? [] : typeof overrides === 'string' ? [overrides] : overrides;
+    const flags = list.map((value) => ` -c ${shellQuote(value, process.platform)}`).join('');
+    let result;
+    try {
+        result = runner(`${binary} features list${flags}`, cwd);
+    }
+    catch {
+        return null;
+    }
+    if (result.status !== 0)
+        return null;
+    for (const line of result.stdout.split('\n')) {
+        const words = line.trim().split(/\s+/);
+        if (words.length < 2 || words[0] !== feature)
+            continue;
+        const state = words[words.length - 1];
+        if (state === 'true')
+            return true;
+        if (state === 'false')
+            return false;
+        return null;
+    }
+    return null;
+}
 /**
  * Disable entries, checked against the binary before they are used.
  *
@@ -544,11 +605,12 @@ export function listMcpServers(binary, runner, overrides, cwd) {
  * reachable from the run, and the caller has to say so out loud rather than
  * report an isolation it only partly achieved.
  *
- * `baseOverrides` are config overrides the run will also carry — in practice
- * {@link PLUGINS_DISABLED_OVERRIDE}. They have to be present on every probe
- * here, because "does this entry disable this server" has a different answer
- * under a different config, and the answer that matters is the one for the
- * config the run actually gets.
+ * `baseOverrides` are config overrides the run will also carry —
+ * {@link APPS_DISABLED_OVERRIDE} always, and {@link PLUGINS_DISABLED_OVERRIDE}
+ * when a plugin supplies a server. They have to be present on every probe here,
+ * because "does this entry disable this server" has a different answer under a
+ * different config, and the answer that matters is the one for the config the
+ * run actually gets.
  */
 export function disableEntriesThatLoad(binary, runner, targets, cwd, baseOverrides = []) {
     if (targets.length === 0)
@@ -618,6 +680,42 @@ export function disableEntriesThatLoad(binary, runner, targets, cwd, baseOverrid
  * an install whose plugins contribute no MCP servers keeps all of that.
  */
 export const PLUGINS_DISABLED_OVERRIDE = 'features.plugins=false';
+/**
+ * The one override that keeps the operator's **apps (connectors)** out of a run.
+ *
+ * Applied to every isolated run, unconditionally, which is the whole point of
+ * it. Measured against `codex-cli 0.146.0`:
+ *
+ * - `codex_apps` is the {@link APPS_FEATURE} surface, and `apps` is a *stable*
+ *   Codex feature that is **on by default**. Turning it off removes the
+ *   `<apps_instructions>` block from the prompt and all 28 `mcp__codex_apps__*`
+ *   tools from the run, while leaving `plugins` — and so the operator's plugin
+ *   skills and hooks — switched on.
+ * - Those tools are not read-only. They include `sites_create_site`,
+ *   `sites_deploy_site_version`, `sites_add_custom_domain`,
+ *   `sites_update_environment_variables`, `sites_generate_siwc_bypass_token`,
+ *   `plugin_management_update_app_permissions` and
+ *   `plugin_management_uninstall_app`: publishing sites and rewriting app
+ *   permissions on the operator's own ChatGPT account.
+ * - **Nothing in `codex mcp list --json` mentions any of it.** Apps are
+ *   account-level and cached under `$CODEX_HOME/cache/codex_apps_tools`, not
+ *   declared in `mcp_servers`, so the entire server-enumeration path this module
+ *   is built on cannot see them. That is why this is unconditional rather than
+ *   applied on evidence, as {@link PLUGINS_DISABLED_OVERRIDE} is: there is no
+ *   listing to take evidence from.
+ * - It is not enough to have no plugins and no configured servers. A
+ *   `CODEX_HOME` holding **only `auth.json`** — 0.4.1's own suggested remedy —
+ *   fetches the account's apps on its first run, writes them to that cache, and
+ *   serves all 28 tools from the second run onwards. Measured, not reasoned.
+ *
+ * `features.plugins=false` also happens to remove the tools on installs where
+ * apps arrive through the plugin pipeline, which is why 0.4.1 closed this by
+ * accident on plugin-bearing machines. It is the wrong lever regardless: it
+ * leaves `<apps_instructions>` in the prompt, it costs the operator their plugin
+ * skills and hooks, and it does nothing at all on a classic-only install —
+ * exactly the shape where 0.4.1 applies no override.
+ */
+export const APPS_DISABLED_OVERRIDE = `features.${APPS_FEATURE}=false`;
 /**
  * Shut off every server the operator's install has, whatever supplies it.
  *
@@ -630,42 +728,64 @@ export const PLUGINS_DISABLED_OVERRIDE = 'features.plugins=false';
  * *measured* rather than read: list again with plugins off, and the names that
  * vanished were the plugin's.
  *
- * The classic path is tried first and, when it succeeds, returned untouched
- * with no extra override. So an install with no plugin-backed servers issues
- * byte-identical commands to the version before plugins were handled at all,
- * and pays exactly one probe as before.
+ * A **third** mechanism sits underneath both and is not a server at all: the
+ * operator's apps (connectors), which reach the run as the `codex_apps` MCP and
+ * appear in no listing this module can read. {@link APPS_DISABLED_OVERRIDE} is
+ * therefore applied to every run unconditionally — there is no inventory to
+ * decide from — and every probe below carries it, so each disable is proven
+ * against the config the run is actually handed.
+ *
+ * The classic path is still tried first and, when it succeeds, returned with no
+ * *plugins* override, so an install with no plugin-backed servers keeps its
+ * plugin skills and hooks and pays the same one probe it did before.
  *
  * Failing to shut a server off is reported, never worked around. A plugin
  * server that survives even `features.plugins=false` is a mechanism we do not
- * understand yet, and a run that cannot prove the boundary must not start.
+ * understand yet, and a run that cannot prove the boundary must not start. The
+ * apps switch is held to the same standard: it is *measured* off through
+ * {@link featureState} under the final override set, because an override that
+ * silently does nothing is the failure mode this whole module exists to catch.
  */
 export function isolateConfiguredServers(binary, runner, targets, cwd) {
-    const direct = disableEntriesThatLoad(binary, runner, targets, cwd);
+    // Present on every probe from here down, and on the run itself.
+    const base = [APPS_DISABLED_OVERRIDE];
+    const prove = (isolation) => {
+        if (featureState(binary, runner, APPS_FEATURE, isolation.configOverrides, cwd) === false) {
+            return isolation;
+        }
+        return {
+            ...isolation,
+            unproven: `Codex would not confirm its "${APPS_FEATURE}" feature is off, so the operator's apps ` +
+                '(connectors) and their tools cannot be kept out of this run',
+        };
+    };
+    const direct = disableEntriesThatLoad(binary, runner, targets, cwd, base);
     if (direct.failed.length === 0)
-        return { ...direct, configOverrides: [] };
+        return prove({ ...direct, configOverrides: base });
     // Something resisted. Ask whether turning the plugin system off accounts for
     // it, rather than assuming the survivors are plugin-backed because they look
     // like it.
-    const withPluginsOff = listMcpServers(binary, runner, PLUGINS_DISABLED_OVERRIDE, cwd);
+    const withPluginsOff = listMcpServers(binary, runner, [...base, PLUGINS_DISABLED_OVERRIDE], cwd);
     // The override does not load, so it disables nothing and we know nothing.
     if (withPluginsOff === null)
-        return { ...direct, configOverrides: [] };
+        return prove({ ...direct, configOverrides: base });
     const remaining = new Set(withPluginsOff.map((server) => server.name));
     const removedByPluginsOff = direct.failed.filter((name) => !remaining.has(name));
     // Plugins were not the problem. Report what the classic path found, so the
     // operator is told about the real survivor instead of a plugin red herring.
     if (removedByPluginsOff.length === 0)
-        return { ...direct, configOverrides: [] };
+        return prove({ ...direct, configOverrides: base });
     // Re-verify the classic disables *under* the plugins-off override. They were
     // proven against a different config, and a proof about a config the run does
     // not get is not a proof.
     const classic = targets.filter((name) => remaining.has(name));
-    const verified = disableEntriesThatLoad(binary, runner, classic, cwd, [PLUGINS_DISABLED_OVERRIDE]);
-    return {
+    const configOverrides = [...base, PLUGINS_DISABLED_OVERRIDE];
+    const verified = disableEntriesThatLoad(binary, runner, classic, cwd, configOverrides);
+    return prove({
         entries: verified.entries,
-        configOverrides: [PLUGINS_DISABLED_OVERRIDE],
+        configOverrides,
         failed: verified.failed,
-    };
+    });
 }
 /**
  * The `codex` binary out of the host's `--exec` command.

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,9 +25,9 @@
 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 { 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 { 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';
 import { MCP_SERVER_NAME, MCP_TOOL_PATTERN } from './mcp.js';
 import { EVENT_AGENT_RUN_REQUESTED, EVENT_MENTION_CREATED, EVENT_MESSAGE_TEAM_CHAT, RUN_ERROR_CANCELLED_BY_USER, eventData, heartbeatPathFor, parseRunRequest, } from './contract.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.
  *
@@ -329,7 +390,15 @@ function codexMcpEntries(options, extraServers, log, workdir) {
     if (acceptedExtraEntries.length === 0)
         acceptedExtraNames.clear();
     const targets = [...configuredNames].filter((name) => !acceptedExtraNames.has(name));
-    const { entries: disabled, configOverrides, failed } = isolateConfiguredServers(binary, probe, targets, workdir);
+    const { entries: disabled, configOverrides, failed, unproven } = isolateConfiguredServers(binary, probe, targets, workdir);
+    if (unproven) {
+        // Not an `mcp_servers` problem, so it does not get the `mcp_servers`
+        // remedy. Upgrading Codex is the honest advice: the switch is read back
+        // from `codex features list`, so this fires when that command, the feature,
+        // or its name is not what this harness was measured against.
+        return fail(`${unproven} — upgrade Codex, or run the daemon with a Codex build that reports ` +
+            `"${APPS_FEATURE}" in \`codex features list\``);
+    }
     if (failed.length > 0) {
         // The remedy belongs in the message. This string is echoed into the thread
         // the teammate is waiting in, and "could not be disabled" on its own leaves
@@ -341,6 +410,11 @@ function codexMcpEntries(options, extraServers, log, workdir) {
     if (targets.length > 0) {
         log(`${timestamp()} ⚙ your own Codex MCP servers are disabled for agent runs: ${targets.join(', ')}`);
     }
+    // Unconditional, so it is stated every run rather than only when something
+    // was found: the operator's connectors are account-level and invisible to
+    // `codex mcp list`, and "nothing was listed" is exactly the wrong thing for
+    // them to conclude from silence here.
+    log(`${timestamp()} ⚙ Codex apps (connectors) are switched off for agent runs`);
     if (configOverrides.includes(PLUGINS_DISABLED_OVERRIDE)) {
         log(`${timestamp()} ⚙ Codex plugins are switched off for agent runs — a plugin supplies an MCP ` +
             'server that cannot be disabled on its own');
@@ -715,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';
@@ -732,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';
@@ -759,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) {
@@ -767,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.
@@ -791,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)`);
@@ -932,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 = () => {
@@ -949,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
@@ -959,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 }
                         : {}),
@@ -970,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';
@@ -1148,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);