@prohost/cli 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,122 @@ 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)**.
+
+- **`codex_apps` tools are kept out of every run.** A Codex "app" is a set of
+  MCP tools served under the name `codex_apps`, and it appears in **no**
+  `codex mcp list --json` output at any setting: apps are account-level, arrive
+  with the ChatGPT login, and are cached under `$CODEX_HOME/cache/codex_apps_tools`
+  rather than declared in `mcp_servers`. The isolation contract is that a run
+  gets the ProhostAI server and the operator's explicitly-allowed extras and
+  nothing else, and this broke it silently — the enumeration the guarantee is
+  built on cannot see these tools at all. Every isolated run now carries
+  `-c features.apps=false`.
+- **It was not hypothetical, and not limited to plugin installs.** Measured
+  against codex-cli 0.146.0: a `CODEX_HOME` whose config declares no plugins
+  and one ordinary MCP server — where 0.4.1 disables that server cleanly, finds
+  nothing that resists, and therefore applies no whole-config override at all —
+  still handed the run 28 `mcp__codex_apps__*` tools. They are not read-only:
+  `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` publish sites and rewrite app permissions on
+  the operator's own account.
+- **A dedicated `CODEX_HOME` was never a fix for this one.** A directory holding
+  only `auth.json` — 0.4.1's own suggested remedy — fetches the account's apps
+  on its first run, writes them to its own cache, and serves the full set from
+  the second run onwards. The login carries them, so a fresh directory delays
+  the exposure by exactly one run. Hence unconditional rather than opt-in.
+- **`features.plugins=false` was the wrong lever, and only ever worked by
+  accident.** It closed this on plugin-bearing machines because apps happened to
+  arrive through that pipeline there, but it leaves the apps instructions in the
+  prompt, costs the operator their plugin skills and hooks, and is never applied
+  at all on a classic-only install. `features.apps=false` is the narrow switch:
+  it leaves `plugins` on, so skills and hooks survive.
+- **Proven, not assumed.** There is no listing to verify against, so the switch
+  is read back out of `codex features list` — the `apps` row must actually read
+  `false` under the exact overrides the run will carry. A renamed feature, an
+  older Codex with no `features` subcommand, or an override that loads and
+  changes nothing all read as *unknown*, and a run that cannot prove the
+  boundary fails before Codex starts with a one-line remedy. 0.4.1's plugin
+  handling, three-tier probe path and classic `mcp_servers` disabling are
+  unchanged and regression-tested.
+
 ## 0.4.1
 
 Codex runs work again on machines with a Codex **plugin** installed.

package/README.md

@@ -329,6 +329,35 @@ used: `plugins."github@openai-curated".enabled=false` and every variant of it
 load without error and disable nothing at all, which is precisely the kind of
 override the verification step exists to catch.
 
+**Your apps (connectors) are switched off for every run, unconditionally.**
+Codex "apps" are the third way tools reach a run, and the only one with no
+inventory to read: an app *is* a set of MCP tools, served under the name
+`codex_apps`, and it appears in **no** `codex mcp list --json` output at any
+setting. Apps are account-level — they come with your ChatGPT login and are
+cached under `$CODEX_HOME/cache/codex_apps_tools`, not declared in
+`mcp_servers`. On the install this was measured against they were 28 tools, and
+they are not read-only: `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` publish sites and rewrite app permissions
+on your account.
+
+So this one is not applied on evidence, the way the plugins switch is — there is
+no listing to take evidence from. Every isolated run carries
+`-c features.apps=false`, and the CLI reads the result back out of
+`codex features list` to confirm the `apps` row really flipped. If it cannot
+confirm that, the run fails before Codex starts, for the same reason a server
+that will not disable fails it: an override that loads happily and changes
+nothing is the failure mode this whole path exists to catch.
+
+`features.plugins=false` is **not** a substitute. It costs you your plugin
+skills and hooks, it leaves the apps instructions in the prompt, and on an
+install with no plugin-backed server it is never applied at all — which is
+exactly the shape that was quietly receiving these tools before 0.4.2. Turning
+apps off leaves `plugins` on, so plugin skills and hooks survive; what a run
+loses is your connectors, which is the intent. The run executes on behalf of
+whoever mentioned the agent, and your connectors are yours.
+
 **If a server still cannot be disabled**, the run fails before Codex starts and
 names it. Two ways out: remove that server or plugin from `~/.codex/config.toml`,
 or give the daemon a `CODEX_HOME` of its own that holds only `auth.json` —
@@ -343,6 +372,13 @@ A dedicated `CODEX_HOME` is the cleanest answer in general: the agent inherits
 your login and nothing else, your own Codex setup is untouched, and no future
 plugin or server you install can change what a paired run can reach.
 
+It is not, however, an answer to apps. A `CODEX_HOME` holding only `auth.json`
+fetches your account's apps on its first run, writes them to its own cache, and
+serves the full set from the second run onwards — the login is what carries
+them, so a fresh directory only delays it by one run. That is why the apps
+switch is unconditional rather than something an operator can opt out of by
+tidying their config.
+
 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.
@@ -489,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/codex.d.ts

@@ -191,6 +191,43 @@ export type CommandRunner = (command: string, cwd?: string) => {
  * enumerate must say so rather than claim an isolation it did not apply.
  */
 export declare function listMcpServers(binary: string, runner: CommandRunner, overrides?: string | string[], cwd?: string): CodexMcpServer[] | 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 declare 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 declare function featureState(binary: string, runner: CommandRunner, feature: string, overrides?: string | string[], cwd?: string): boolean | null;
 /** Disable entries proven to work, and the servers that could not be disabled. */
 export interface VerifiedDisable {
     entries: string[];
@@ -217,11 +254,12 @@ export interface VerifiedDisable {
  * 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 declare function disableEntriesThatLoad(binary: string, runner: CommandRunner, targets: string[], cwd?: string, baseOverrides?: string[]): VerifiedDisable;
 /**
@@ -260,14 +298,58 @@ export declare function disableEntriesThatLoad(binary: string, runner: CommandRu
  * an install whose plugins contribute no MCP servers keeps all of that.
  */
 export declare 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 declare const APPS_DISABLED_OVERRIDE = "features.apps=false";
 /** A verified isolation: what to pass Codex, and what could not be shut off. */
 export interface VerifiedIsolation {
     /** `mcp_servers` fragments, for the single {@link mcpServersOverride}. */
     entries: string[];
-    /** Whole-config `-c` overrides the run needs on top. Usually empty. */
+    /** Whole-config `-c` overrides the run needs on top. Never empty. */
     configOverrides: string[];
     /** Servers still reachable from the run. Empty is the outcome we want. */
     failed: string[];
+    /**
+     * Why a whole-config switch could not be *proven* to have taken effect.
+     *
+     * Separate from {@link failed}, which names MCP servers and earns a remedy
+     * about `mcp_servers`. This one is not a server and has no such remedy, so it
+     * carries its own sentence. Set means the run must not start.
+     */
+    unproven?: string;
 }
 /**
  * Shut off every server the operator's install has, whatever supplies it.
@@ -281,14 +363,23 @@ export interface VerifiedIsolation {
  * *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 declare function isolateConfiguredServers(binary: string, runner: CommandRunner, targets: string[], cwd?: string): VerifiedIsolation;
 /**
@@ -341,8 +432,9 @@ export interface CodexFlags {
      */
     mcpEntries?: string[];
     /**
-     * Whole-config `-c` overrides that are not `mcp_servers` — in practice
-     * {@link PLUGINS_DISABLED_OVERRIDE}, when the operator has a plugin that
+     * Whole-config `-c` overrides that are not `mcp_servers`:
+     * {@link APPS_DISABLED_OVERRIDE} on every isolated run, plus
+     * {@link PLUGINS_DISABLED_OVERRIDE} when the operator has a plugin that
      * contributes MCP servers. They precede the `mcp_servers` override for the
      * same reason they do in the verifier: the run has to be handed the same
      * overrides in the same order the probe certified.