@vtxmacro/cli 2026.8.12 → 2026.8.13

package/README.md

@@ -47,6 +47,15 @@ credential.
 
 ### Automated Codex host
 
+Before the first Codex login, enable **Device code authorization for Codex** in
+ChatGPT Security settings. Only enter a device code from a login you initiated,
+and never share it. The automated host advertises `gpt-5.6-sol` with
+`medium`, `high`, and `xhigh` reasoning effort. Before starting a Trader,
+confirm that the VTX AI page shows the intended authenticated ChatGPT email and
+plan. The host reads the live Codex account window: a reached limit pauses new
+dispatch until its reported reset, while a transient throttle uses a short
+bounded cooldown.
+
 ```bash
 vtx inference-host login
 vtx inference-host codex-login
@@ -63,6 +72,21 @@ OAuth grant. It also keeps its ChatGPT subscription login in a dedicated private
 Codex home. Neither credential is copied from or widens the ordinary CLI or Codex
 session. VTX logout/revoke and Codex logout are intentionally separate operations.
 
+Use `vtx inference-host --help` for command discovery. The VTX login verifies
+that the selected credential store can read back the exact saved grant. If an
+OS credential store such as Windows Credential Manager cannot retain it, VTX
+revokes the new remote grant and fails with an actionable error. Retry with the
+supported private-file store by setting
+`VTX_INFERENCE_HOST_CREDENTIAL_STORE=file` before running
+`vtx inference-host login` again. In PowerShell use
+`$env:VTX_INFERENCE_HOST_CREDENTIAL_STORE="file"`; in bash use
+`export VTX_INFERENCE_HOST_CREDENTIAL_STORE=file`.
+
+The browser callback shows a VTX authorization-complete page. If a browser
+extension instead shows `ERR_BLOCKED_BY_CLIENT` but the CLI reports
+`logged_in` and `doctor` reports `credential-present`, only the local
+confirmation page was blocked; the grant succeeded.
+
 ### Any compatible agent harness
 
 Codex, Claude Code, Cursor, GitHub Copilot, Antigravity, and other agents that can
@@ -108,6 +132,12 @@ and normally running VTX Client Mode or Server Mode bots. Server Mode keeps the
 normal VTX call fee. Client Mode has no VTX platform fee. Neither mode falls back
 to another model when the agent host is unavailable.
 
+After any approved Trader start, use `vtx --profile <profile-id> bots status`
+to confirm the normal Trader remains running. If it returns to Stopped, use
+`vtx --profile <profile-id> runtime events` to read the latest error before one
+controlled retry. A start receipt or a brief Live label is not proof of a
+running bot.
+
 ## Remove
 
 First stop the foreground run or agent-run process, revoke the VTX inference
@@ -121,3 +151,7 @@ vtx inference-host revoke
 vtx inference-host codex-logout
 npm uninstall -g @vtxmacro/cli
 ```
+
+If an older failed login left no local credential to revoke, disconnect that
+inactive inference grant from Connected Agent Apps on the VTX Insights page
+before logging in again.

package/bin/vtx.js

@@ -38,7 +38,7 @@ var init_agent_cli_release = __esm({
   "agent-cli-release.json"() {
     agent_cli_release_default = {
       package_name: "@vtxmacro/cli",
-      package_version: "2026.8.12",
+      package_version: "2026.8.13",
       codex_package_name: "@openai/codex",
       codex_version: "0.147.0",
       platforms: {
@@ -14375,7 +14375,7 @@ var init_zod = __esm({
 });
 
 // lib/external-inference-contract.ts
-var EXTERNAL_INFERENCE_CONTRACT_VERSION, EXTERNAL_INFERENCE_CONTROLLER_SCHEMA_VERSION, EXTERNAL_INFERENCE_ADVERTISEMENT_SCHEMA_VERSION, EXTERNAL_INFERENCE_ENVELOPE_SCHEMA_VERSION, EXTERNAL_INFERENCE_JOB_INPUT_SCHEMA_VERSION, EXTERNAL_INFERENCE_USAGE_SCHEMA_VERSION, EXTERNAL_INFERENCE_INPUT_HASH_DOMAIN, MAX_EXTERNAL_INFERENCE_STATUS_HOSTS, MAX_GENERATION, MAX_SAFE_INTEGER, MAX_PROMPT_BYTES, MAX_IMMUTABLE_JOB_INPUT_BYTES, MAX_CANDIDATE_PLAINTEXT_BYTES, MAX_CIPHERTEXT_CHARS, SHA256_INITIAL_STATE, SHA256_ROUND_CONSTANTS, rotateRight, sha256BytesHex, sha256Utf8Hex, computeImmutableJobInputSha256, identifierSchema, operationIdentifierSchema, sha256HexSchema, generationSchema, zeroBasedGenerationSchema, nonNegativeSafeIntegerSchema, positiveSafeIntegerSchema, sqlIntegerTokenCountSchema, timestampSchema, safeCodeSchema, externalInferenceAdapterIdSchema, reasoningEffortSchema, modelNameSchema, displayNameSchema, protocolVersionSchema, base64UrlAlphabet, isCanonicalBase64Url, base64Url32BytesSchema, base64UrlNonceSchema, base64UrlCiphertextSchema, claimHandleSchema, boundedJsonTextSchema, boundedPromptTextSchema, laneSchema, botModeSchema, executionModeSchema, responseModeSchema, dispatchOutcomeSchema, responseOutcomeSchema, nativeModelControllerSchema, externalAgentModelControllerSchema, externalAgentUnboundControllerSchema, liveModelControllerSchema, snapshotModelControllerSchema, modelIdentityMappingSchema, advertisedModelSchema, hostAdvertisementSchema, envelopeAadSchema, validateEnvelopeAad, commonEnvelopeShape, sealedKeyWrapEnvelopeSchema, sealedInputEnvelopeSchema, sealedCandidateEnvelopeSchema, sealedEnvelopeSchema, screenerCandidateRuntimeBindingSchema, screenerClientLeaseBindingSchema, screenerRuntimeBindingSchema, serverRuntimeBindingSchema, clientRuntimeBindingSchema, runtimeBindingSchema, immutableJobInputSchema, canonicalizeJsonValue, serializeImmutableJobInput, reportedTokenUsageSchema, unavailableTokenUsageSchema, tokenUsageSchema, agentConnectRequestSchema, agentNextRequestSchema, agentHeartbeatRequestSchema, emptyAgentNextResultSchema, claimedAgentNextResultSchema, agentNextResultSchema, agentCompleteRequestSchema, agentFailRequestSchema, requestedModelSelectionSchema, completedModelProvenanceSchema, attemptModelProvenanceSchema, hostHeartbeatRequestSchema, jobClaimRequestSchema, emptyJobClaimSchema, claimedJobSchema, jobClaimResultSchema, attemptStartRequestSchema, jobHeartbeatRequestSchema, continueHeartbeatDirectiveSchema, cancelHeartbeatDirectiveSchema, jobHeartbeatResultSchema, adapterOutcomeEvidenceSchema, completionBaseShape, validateCompletion, providerResponseCompletionSchema, decisionCandidateCompletionSchema, jobCompleteRequestSchema, jobFailRequestSchema, jobCancelRequestSchema, jobCancellationReceiptSchema, jobDeliveryRequestSchema, deliveryBaseShape, validateDeliveryCandidate, providerResponseDeliverySchema, decisionCandidateDeliverySchema, jobDeliveryResultSchema, jobConsumptionRequestSchema, jobConsumptionReceiptSchema, jobStateSchema, jobStatusReadSchema, hostStatusReadSchema, controllerBindingStatusReadSchema, queueStatusReadSchema, outcomeStatusReadSchema, externalInferenceStatusReadSchema, nativeResearchEvidenceSourceSchema, externalAgentResearchEvidenceSourceSchema, researchEvidenceSourceSchema, reportedResearchTokenUsageSchema, unavailableResearchTokenUsageSchema, researchTokenUsageSchema, externalInferenceProductLineageBaseShape, traderExternalInferenceProductLineageSchema, decisionChatExternalInferenceProductLineageSchema, screenerExternalInferenceProductLineageSchema, externalInferenceProductLineageSchema, normalProductLinkageSchema, evidenceMaterializationMarkerSchema, deliveredExternalAgentSourceIdentitySchema, deliveredRequestEvidenceSchema, researchEvidenceBaseShape, researchEvidenceBaseSchema, validateExactUtf8, validateResearchEvidence, providerResponseResearchEvidenceSchema, decisionCandidateResearchEvidenceSchema, researchEvidenceSchema;
+var EXTERNAL_INFERENCE_CONTRACT_VERSION, EXTERNAL_INFERENCE_CONTROLLER_SCHEMA_VERSION, EXTERNAL_INFERENCE_ADVERTISEMENT_SCHEMA_VERSION, EXTERNAL_INFERENCE_ENVELOPE_SCHEMA_VERSION, EXTERNAL_INFERENCE_JOB_INPUT_SCHEMA_VERSION, EXTERNAL_INFERENCE_USAGE_SCHEMA_VERSION, EXTERNAL_INFERENCE_INPUT_HASH_DOMAIN, MAX_EXTERNAL_INFERENCE_STATUS_HOSTS, MAX_GENERATION, MAX_SAFE_INTEGER, MAX_PROMPT_BYTES, MAX_IMMUTABLE_JOB_INPUT_BYTES, MAX_CANDIDATE_PLAINTEXT_BYTES, MAX_CIPHERTEXT_CHARS, SHA256_INITIAL_STATE, SHA256_ROUND_CONSTANTS, rotateRight, sha256BytesHex, sha256Utf8Hex, computeImmutableJobInputSha256, identifierSchema, operationIdentifierSchema, sha256HexSchema, generationSchema, zeroBasedGenerationSchema, nonNegativeSafeIntegerSchema, positiveSafeIntegerSchema, sqlIntegerTokenCountSchema, timestampSchema, safeCodeSchema, externalInferenceAdapterIdSchema, reasoningEffortSchema, modelNameSchema, displayNameSchema, authenticatedAccountEmailSchema, protocolVersionSchema, base64UrlAlphabet, isCanonicalBase64Url, base64Url32BytesSchema, base64UrlNonceSchema, base64UrlCiphertextSchema, claimHandleSchema, boundedJsonTextSchema, boundedPromptTextSchema, laneSchema, botModeSchema, executionModeSchema, responseModeSchema, dispatchOutcomeSchema, responseOutcomeSchema, nativeModelControllerSchema, externalAgentModelControllerSchema, externalAgentUnboundControllerSchema, liveModelControllerSchema, snapshotModelControllerSchema, modelIdentityMappingSchema, advertisedModelSchema, hostAdvertisementSchema, envelopeAadSchema, validateEnvelopeAad, commonEnvelopeShape, sealedKeyWrapEnvelopeSchema, sealedInputEnvelopeSchema, sealedCandidateEnvelopeSchema, sealedEnvelopeSchema, screenerCandidateRuntimeBindingSchema, screenerClientLeaseBindingSchema, screenerRuntimeBindingSchema, serverRuntimeBindingSchema, clientRuntimeBindingSchema, runtimeBindingSchema, immutableJobInputSchema, canonicalizeJsonValue, serializeImmutableJobInput, reportedTokenUsageSchema, unavailableTokenUsageSchema, tokenUsageSchema, agentConnectRequestSchema, agentNextRequestSchema, agentHeartbeatRequestSchema, emptyAgentNextResultSchema, claimedAgentNextResultSchema, agentNextResultSchema, agentCompleteRequestSchema, agentFailRequestSchema, requestedModelSelectionSchema, completedModelProvenanceSchema, attemptModelProvenanceSchema, hostHeartbeatRequestSchema, jobClaimRequestSchema, emptyJobClaimSchema, claimedJobSchema, jobClaimResultSchema, attemptStartRequestSchema, jobHeartbeatRequestSchema, continueHeartbeatDirectiveSchema, cancelHeartbeatDirectiveSchema, jobHeartbeatResultSchema, adapterOutcomeEvidenceSchema, completionBaseShape, validateCompletion, providerResponseCompletionSchema, decisionCandidateCompletionSchema, jobCompleteRequestSchema, jobFailRequestSchema, jobCancelRequestSchema, jobCancellationReceiptSchema, jobDeliveryRequestSchema, deliveryBaseShape, validateDeliveryCandidate, providerResponseDeliverySchema, decisionCandidateDeliverySchema, jobDeliveryResultSchema, jobConsumptionRequestSchema, jobConsumptionReceiptSchema, jobStateSchema, jobStatusReadSchema, hostStatusReadSchema, controllerBindingStatusReadSchema, queueStatusReadSchema, outcomeStatusReadSchema, externalInferenceStatusReadSchema, nativeResearchEvidenceSourceSchema, externalAgentResearchEvidenceSourceSchema, researchEvidenceSourceSchema, reportedResearchTokenUsageSchema, unavailableResearchTokenUsageSchema, researchTokenUsageSchema, externalInferenceProductLineageBaseShape, traderExternalInferenceProductLineageSchema, decisionChatExternalInferenceProductLineageSchema, screenerExternalInferenceProductLineageSchema, externalInferenceProductLineageSchema, normalProductLinkageSchema, evidenceMaterializationMarkerSchema, deliveredExternalAgentSourceIdentitySchema, deliveredRequestEvidenceSchema, researchEvidenceBaseShape, researchEvidenceBaseSchema, validateExactUtf8, validateResearchEvidence, providerResponseResearchEvidenceSchema, decisionCandidateResearchEvidenceSchema, researchEvidenceSchema;
 var init_external_inference_contract = __esm({
   "lib/external-inference-contract.ts"() {
     "use strict";
@@ -14580,6 +14580,7 @@ var init_external_inference_contract = __esm({
     reasoningEffortSchema = external_exports.string().min(1).max(32).regex(/^[a-z][a-z0-9_-]{0,31}$/);
     modelNameSchema = external_exports.string().min(1).max(256);
     displayNameSchema = external_exports.string().min(1).max(128);
+    authenticatedAccountEmailSchema = external_exports.string().max(320).email();
     protocolVersionSchema = external_exports.string().min(1).max(64);
     base64UrlAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
     isCanonicalBase64Url = (value, exactBytes) => {
@@ -14713,6 +14714,8 @@ var init_external_inference_contract = __esm({
       key_generation: generationSchema,
       adapter: externalInferenceAdapterIdSchema,
       display_name: displayNameSchema,
+      authenticated_account_email: authenticatedAccountEmailSchema.nullable().optional(),
+      authenticated_account_plan: safeCodeSchema.nullable().optional(),
       protocol_version: protocolVersionSchema,
       envelope_public_key: base64Url32BytesSchema,
       health: external_exports.enum(["healthy", "degraded", "draining"]),
@@ -15576,6 +15579,8 @@ var init_external_inference_contract = __esm({
     hostStatusReadSchema = external_exports.strictObject({
       host_id: identifierSchema,
       display_name: displayNameSchema,
+      authenticated_account_email: authenticatedAccountEmailSchema.nullable().optional(),
+      authenticated_account_plan: safeCodeSchema.nullable().optional(),
       adapter: externalInferenceAdapterIdSchema,
       status: external_exports.enum(["online", "degraded", "offline", "draining", "revoked"]),
       host_generation: generationSchema,
@@ -16653,6 +16658,10 @@ var init_credential_store = __esm({
         }
         const result2 = await this.runner(command, { stdin: serialized, ...options });
         if (result2.exitCode !== 0) throw new Error("OS credential write failed.");
+        const retained = await this.read(accountKey, options);
+        if (!retained || JSON.stringify(retained) !== JSON.stringify(validated)) {
+          throw new Error("OS credential write could not be verified.");
+        }
       }
       async remove(accountKey, options = {}) {
         const command = this.commands.remove(INFERENCE_CREDENTIAL_NAMESPACE, accountKey);
@@ -16870,7 +16879,7 @@ public static class VtxInferenceCredential {
 }`;
     powershellCredentialCommand = (operation, namespace, accountKey) => {
       const target = JSON.stringify(`${namespace}:${accountKey}`);
-      const body = operation === "read" ? `try { [Console]::Out.Write([VtxInferenceCredential]::Read(${target})) } catch [System.ComponentModel.Win32Exception] { if ($_.Exception.NativeErrorCode -eq 1168) { exit 4 }; exit 1 }` : operation === "write" ? `[VtxInferenceCredential]::Write(${target}, [Console]::In.ReadToEnd())` : `try { [VtxInferenceCredential]::Delete(${target}) } catch [System.ComponentModel.Win32Exception] { if ($_.Exception.NativeErrorCode -eq 1168) { exit 4 }; exit 1 }`;
+      const body = operation === "read" ? `try { [Console]::Out.Write([VtxInferenceCredential]::Read(${target})) } catch [System.ComponentModel.Win32Exception] { if ($_.Exception.NativeErrorCode -eq 1168) { exit 4 }; exit 1 }` : operation === "write" ? `try { [VtxInferenceCredential]::Write(${target}, [Console]::In.ReadToEnd()); exit 0 } catch { exit 1 }` : `try { [VtxInferenceCredential]::Delete(${target}) } catch [System.ComponentModel.Win32Exception] { if ($_.Exception.NativeErrorCode -eq 1168) { exit 4 }; exit 1 }`;
       const script = `Add-Type -TypeDefinition @'
 ${windowsCredentialInterop}
 '@
@@ -16985,7 +16994,7 @@ ${body}`;
 });
 
 // lib/inference-host/mcp-client.ts
-var EXTERNAL_INFERENCE_MCP_PROTOCOL_VERSION, EXTERNAL_INFERENCE_AUTOMATED_HOST_TOOLS, EXTERNAL_INFERENCE_OPERATIONAL_TOOLS, ExternalInferenceMcpError, DEFAULT_REQUEST_TIMEOUT_MS, identifierSchema2, safeCodeSchema2, hostMutationResultSchema, attemptStartResultSchema, agentConnectResultSchema, agentHeartbeatResultSchema, jobCompletionResultSchema, jobFailureResultSchema, toolContracts, discoveryResultSchema, toolListResultSchema, inlineStructuredContentSchema, protocolMeta, parseJsonDocument, parseSseDocuments, parseResponseDocuments, exactOperationalInventory, exactJson, invalidBoundResult, verifyToolResult, ExternalInferenceMcpClient;
+var EXTERNAL_INFERENCE_MCP_PROTOCOL_VERSION, EXTERNAL_INFERENCE_AUTOMATED_HOST_TOOLS, EXTERNAL_INFERENCE_OPERATIONAL_TOOLS, ExternalInferenceMcpError, DEFAULT_REQUEST_TIMEOUT_MS, MAX_RETRY_AFTER_MS, parseRetryAfterMs, identifierSchema2, safeCodeSchema2, hostMutationResultSchema, attemptStartResultSchema, agentConnectResultSchema, agentHeartbeatResultSchema, jobCompletionResultSchema, jobFailureResultSchema, toolContracts, discoveryResultSchema, toolListResultSchema, inlineStructuredContentSchema, protocolMeta, parseJsonDocument, parseSseDocuments, parseResponseDocuments, exactOperationalInventory, exactJson, invalidBoundResult, verifyToolResult, ExternalInferenceMcpClient;
 var init_mcp_client = __esm({
   "lib/inference-host/mcp-client.ts"() {
     "use strict";
@@ -17016,9 +17025,29 @@ var init_mcp_client = __esm({
         this.name = "ExternalInferenceMcpError";
         this.code = code;
         this.definitivelyNotApplied = options.definitivelyNotApplied ?? false;
+        this.httpStatusCode = options.httpStatusCode ?? null;
+        this.retryAfterMs = options.retryAfterMs ?? null;
+        this.retryable = options.retryable ?? [
+          "network_error",
+          "transport_rejected",
+          "server_rejected",
+          "rate_limited",
+          "invalid_response",
+          "request_timeout",
+          "authentication_timeout"
+        ].includes(code);
       }
     };
     DEFAULT_REQUEST_TIMEOUT_MS = 15e3;
+    MAX_RETRY_AFTER_MS = 24 * 60 * 60 * 1e3;
+    parseRetryAfterMs = (response, observedAtMs = Date.now()) => {
+      const value = response.headers.get("retry-after")?.trim();
+      if (!value) return null;
+      const seconds = Number(value);
+      const milliseconds = Number.isFinite(seconds) && seconds >= 0 ? Math.ceil(seconds * 1e3) : Math.max(0, Date.parse(value) - observedAtMs);
+      if (!Number.isSafeInteger(milliseconds)) return null;
+      return Math.min(milliseconds, MAX_RETRY_AFTER_MS);
+    };
     identifierSchema2 = external_exports.string().min(1).max(128);
     safeCodeSchema2 = external_exports.string().min(1).max(96);
     hostMutationResultSchema = external_exports.strictObject({
@@ -17238,11 +17267,11 @@ var init_mcp_client = __esm({
         if (!host) return invalidBoundResult(name);
         if (host.host_id !== request.host_id || host.host_generation !== request.host_generation || host.advertisement_generation !== request.advertisement_generation || host.key_generation !== request.key_generation || request.adapter !== void 0 && host.adapter !== request.adapter) invalidBoundResult(name);
         if (name !== "inference.host.heartbeat") {
-          if (host.display_name !== request.display_name || !exactJson(host.models, request.models) || host.status === "revoked") invalidBoundResult(name);
+          if (host.display_name !== request.display_name || (host.authenticated_account_email ?? null) !== (request.authenticated_account_email ?? null) || (host.authenticated_account_plan ?? null) !== (request.authenticated_account_plan ?? null) || !exactJson(host.models, request.models) || host.status === "revoked") invalidBoundResult(name);
           return;
         }
         const expectedStatus = request.status === "healthy" ? "online" : request.status;
-        if (host.status !== expectedStatus) invalidBoundResult(name);
+        if (host.status !== expectedStatus && !(request.status === "healthy" && host.status === "offline")) invalidBoundResult(name);
         return;
       }
       if (name === "inference.agent.connect") {
@@ -17454,9 +17483,14 @@ var init_mcp_client = __esm({
           );
         }
         if (!response.ok) {
+          const httpStatusCode = response.status;
+          const retryAfterMs = parseRetryAfterMs(response);
+          await response.body?.cancel().catch(() => void 0);
+          const retryable = httpStatusCode === 408 || httpStatusCode === 425 || httpStatusCode === 429 || httpStatusCode >= 500;
           throw new ExternalInferenceMcpError(
-            response.status === 401 ? "authentication_rejected" : "transport_rejected",
-            `Insights MCP request failed with HTTP ${response.status}.`
+            httpStatusCode === 401 ? "authentication_rejected" : httpStatusCode === 429 ? "rate_limited" : httpStatusCode >= 500 ? "server_rejected" : retryable ? "transport_rejected" : "http_rejected",
+            `Insights MCP request failed with HTTP ${httpStatusCode}.`,
+            { httpStatusCode, retryAfterMs, retryable }
           );
         }
         let documents;
@@ -18052,13 +18086,13 @@ async function beginInferenceOAuthLogin(options) {
     );
   }
   const fetchImpl = options.fetchImpl || fetch;
-  const callbackPath = `/oauth/callback/${randomBytes2(16).toString("hex")}`;
+  const callbackPath = `/vtx-inference-authorized/${randomBytes2(16).toString("hex")}`;
   let handler = null;
   const server = createServer((request, response) => {
     response.setHeader("Cache-Control", "no-store");
     response.setHeader("Pragma", "no-cache");
     response.setHeader("Referrer-Policy", "no-referrer");
-    response.setHeader("Content-Type", "text/plain; charset=utf-8");
+    response.setHeader("Content-Type", "text/html; charset=utf-8");
     const writeResponse = (status, body) => {
       response.statusCode = status;
       response.end(body);
@@ -18162,9 +18196,12 @@ async function beginInferenceOAuthLogin(options) {
                 cause: error48
               });
             }
-            throw error48;
+            throw new InferenceOAuthCredentialStoreError({ cause: error48 });
           }
-          writeResponse(200, "Authorization complete. Return to VTX CLI.");
+          writeResponse(
+            200,
+            '<!doctype html><html><head><meta charset="utf-8"><title>VTX authorization complete</title></head><body><main><h1>VTX authorization complete</h1><p>The VTX CLI received your approval. You can close this tab and return to the terminal.</p></main></body></html>'
+          );
           await closeServer(server);
           resolve5({
             accessToken: tokens.accessToken,
@@ -18173,9 +18210,12 @@ async function beginInferenceOAuthLogin(options) {
             accountKey
           });
         } catch (error48) {
-          writeResponse(400, "Authorization failed. Return to VTX CLI.");
+          writeResponse(
+            400,
+            '<!doctype html><html><head><meta charset="utf-8"><title>VTX authorization failed</title></head><body><main><h1>VTX authorization failed</h1><p>Return to the VTX CLI for the actionable error.</p></main></body></html>'
+          );
           await closeServer(server);
-          reject(error48 instanceof InferenceOAuthRequestError ? error48 : new Error("Inference OAuth authorization failed."));
+          reject(error48 instanceof InferenceOAuthRequestError || error48 instanceof InferenceOAuthCredentialStoreError ? error48 : new Error("Inference OAuth authorization failed."));
         }
       };
     });
@@ -18225,7 +18265,7 @@ async function beginInferenceOAuthLogin(options) {
     throw error48;
   }
 }
-var INFERENCE_SCOPE, CALLBACK_HOST, TOKEN_PREFIX, DEFAULT_OAUTH_REQUEST_TIMEOUT_MS, InferenceOAuthRequestError;
+var INFERENCE_SCOPE, CALLBACK_HOST, TOKEN_PREFIX, DEFAULT_OAUTH_REQUEST_TIMEOUT_MS, InferenceOAuthRequestError, InferenceOAuthCredentialStoreError;
 var init_oauth = __esm({
   "lib/inference-host/oauth.ts"() {
     "use strict";
@@ -18241,6 +18281,15 @@ var init_oauth = __esm({
         this.code = code;
       }
     };
+    InferenceOAuthCredentialStoreError = class extends Error {
+      constructor(options = {}) {
+        super(
+          "VTX authorization succeeded, but the credential store did not retain the grant. VTX revoked the new remote grant. Set VTX_INFERENCE_HOST_CREDENTIAL_STORE=file and run vtx inference-host login again to use the secure private-file fallback.",
+          { cause: options.cause }
+        );
+        this.name = "InferenceOAuthCredentialStoreError";
+      }
+    };
   }
 });
 
@@ -18488,7 +18537,25 @@ async function loginCodexSubscription(options) {
 async function preflightCodexSubscription(options) {
   const session = await CodexAppServerSession.start(options);
   try {
-    await session.requireManagedChatGptAuth(options.deadlineAtMs, options.signal, true);
+    const account = await session.readAccountSnapshot(
+      options.deadlineAtMs,
+      options.signal,
+      true
+    );
+    if (!account.requiresOpenaiAuth || account.authenticatedChatGptAccount === null) {
+      throw new CodexAppServerError({
+        message: "Codex managed ChatGPT authentication is required.",
+        category: "auth",
+        code: "managed_chatgpt_auth_required",
+        retryable: false
+      });
+    }
+    const rateLimits = await session.readAccountRateLimits(options.deadlineAtMs, options.signal);
+    return {
+      authenticated_account_email: account.authenticatedChatGptAccount.email,
+      authenticated_account_plan: account.authenticatedChatGptAccount.planType,
+      rate_limits: rateLimits
+    };
   } finally {
     await session.close();
   }
@@ -18501,11 +18568,28 @@ async function logoutCodexSubscription(options) {
     await session.close();
   }
 }
-var CODEX_INFERENCE_PERMISSION_PROFILE, CodexAppServerError, objectOrNull, finiteToken, tokenUsageFromBreakdown, usageFromNotification, forbiddenMethod, forbiddenTerminalItem, classifyCodexTurnFailure, scrubbedCodexEnvironment, killWindowsProcessTree, appServerArgs, GUARDIAN_SCRIPT, writeCodexGuardianSpawnIntent, parseGuardianReceipt, readCodexGuardianReceipt, waitForCodexGuardianState, defaultSpawn, CodexAppServerSession;
+var CODEX_INFERENCE_PERMISSION_PROFILE, CODEX_ACCOUNT_PLAN_TYPES, CodexAppServerError, objectOrNull, finiteToken, tokenUsageFromBreakdown, usageFromNotification, validPlanType, nonnegativeSafeIntegerOrNull, nonnegativeFiniteNumberOrNull, parseRateLimitWindow, RATE_LIMIT_REACHED_TYPES, DEFAULT_CODEX_QUOTA_COOLDOWN_MS, MAX_CODEX_QUOTA_COOLDOWN_MS, CODEX_TRANSIENT_RATE_LIMIT_COOLDOWN_MS, parseRateLimitSnapshot, codexRateLimitRetryAtMs, codexAccountRateLimitReached, forbiddenMethod, forbiddenTerminalItem, classifyCodexTurnFailure, scrubbedCodexEnvironment, killWindowsProcessTree, appServerArgs, GUARDIAN_SCRIPT, writeCodexGuardianSpawnIntent, parseGuardianReceipt, readCodexGuardianReceipt, waitForCodexGuardianState, defaultSpawn, CodexAppServerSession;
 var init_codex_app_server = __esm({
   "lib/inference-host/codex-app-server.ts"() {
     "use strict";
     CODEX_INFERENCE_PERMISSION_PROFILE = "vtx_inference_readonly";
+    CODEX_ACCOUNT_PLAN_TYPES = [
+      "free",
+      "go",
+      "plus",
+      "pro",
+      "prolite",
+      "team",
+      "self_serve_business_prolite",
+      "self_serve_business_usage_based",
+      "business",
+      "ent26",
+      "enterprise_cbp_automation",
+      "enterprise_cbp_usage_based",
+      "enterprise",
+      "edu",
+      "unknown"
+    ];
     CodexAppServerError = class extends Error {
       constructor(options) {
         super(options.message, { cause: options.cause });
@@ -18514,6 +18598,9 @@ var init_codex_app_server = __esm({
         this.code = options.code;
         this.retryable = options.retryable;
         this.dispatchOutcome = options.dispatchOutcome ?? "not_dispatched";
+        this.httpStatusCode = options.httpStatusCode ?? null;
+        this.retryAtMs = options.retryAtMs ?? null;
+        this.usage = options.usage ?? null;
       }
     };
     objectOrNull = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
@@ -18554,6 +18641,72 @@ var init_codex_app_server = __esm({
       }
       return null;
     };
+    validPlanType = (value) => typeof value === "string" && CODEX_ACCOUNT_PLAN_TYPES.includes(value);
+    nonnegativeSafeIntegerOrNull = (value) => Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : null;
+    nonnegativeFiniteNumberOrNull = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+    parseRateLimitWindow = (value) => {
+      if (value === null) return null;
+      const candidate = objectOrNull(value);
+      if (!candidate) throw new Error("invalid rate-limit window");
+      const usedPercent = nonnegativeFiniteNumberOrNull(candidate.usedPercent);
+      const windowDurationMins = candidate.windowDurationMins == null ? null : nonnegativeSafeIntegerOrNull(candidate.windowDurationMins);
+      const resetsAt = candidate.resetsAt == null ? null : nonnegativeSafeIntegerOrNull(candidate.resetsAt);
+      if (usedPercent === null || windowDurationMins === null && candidate.windowDurationMins != null || resetsAt === null && candidate.resetsAt != null) {
+        throw new Error("invalid rate-limit window");
+      }
+      return { usedPercent, windowDurationMins, resetsAt };
+    };
+    RATE_LIMIT_REACHED_TYPES = [
+      "rate_limit_reached",
+      "workspace_owner_credits_depleted",
+      "workspace_member_credits_depleted",
+      "workspace_owner_usage_limit_reached",
+      "workspace_member_usage_limit_reached"
+    ];
+    DEFAULT_CODEX_QUOTA_COOLDOWN_MS = 5 * 60 * 1e3;
+    MAX_CODEX_QUOTA_COOLDOWN_MS = 8 * 24 * 60 * 60 * 1e3;
+    CODEX_TRANSIENT_RATE_LIMIT_COOLDOWN_MS = 30 * 1e3;
+    parseRateLimitSnapshot = (value) => {
+      const candidate = objectOrNull(value);
+      if (!candidate) throw new Error("invalid rate-limit snapshot");
+      const limitId = candidate.limitId === null || candidate.limitId === void 0 ? null : typeof candidate.limitId === "string" && candidate.limitId.trim() ? candidate.limitId.trim() : void 0;
+      const limitName = candidate.limitName === null || candidate.limitName === void 0 ? null : typeof candidate.limitName === "string" && candidate.limitName.trim() ? candidate.limitName.trim() : void 0;
+      const planType = candidate.planType === null || candidate.planType === void 0 ? null : validPlanType(candidate.planType) ? candidate.planType : void 0;
+      const reached = candidate.rateLimitReachedType === null || candidate.rateLimitReachedType === void 0 ? null : typeof candidate.rateLimitReachedType === "string" && RATE_LIMIT_REACHED_TYPES.includes(candidate.rateLimitReachedType) ? candidate.rateLimitReachedType : void 0;
+      const spendControlReached = candidate.spendControlReached === null || candidate.spendControlReached === void 0 ? null : typeof candidate.spendControlReached === "boolean" ? candidate.spendControlReached : void 0;
+      if (limitId === void 0 || limitName === void 0 || planType === void 0 || reached === void 0 || spendControlReached === void 0) throw new Error("invalid rate-limit snapshot");
+      return {
+        limitId,
+        limitName,
+        planType,
+        primary: parseRateLimitWindow(candidate.primary ?? null),
+        secondary: parseRateLimitWindow(candidate.secondary ?? null),
+        rateLimitReachedType: reached,
+        spendControlReached
+      };
+    };
+    codexRateLimitRetryAtMs = (accountRateLimits) => {
+      const snapshots = [accountRateLimits.rateLimits];
+      const exhaustedResets = [];
+      const reachedResets = [];
+      for (const snapshot of snapshots) {
+        const windows = [snapshot.primary, snapshot.secondary].filter(
+          (window2) => window2 !== null
+        );
+        for (const window2 of windows) {
+          if (window2.resetsAt === null) continue;
+          const resetAtMs = window2.resetsAt * 1e3;
+          if (!Number.isSafeInteger(resetAtMs)) continue;
+          if (window2.usedPercent >= 100) exhaustedResets.push(resetAtMs);
+          if (snapshot.rateLimitReachedType !== null || snapshot.spendControlReached === true) {
+            reachedResets.push(resetAtMs);
+          }
+        }
+      }
+      const candidates = exhaustedResets.length > 0 ? exhaustedResets : reachedResets.length > 0 ? reachedResets : [];
+      return candidates.length > 0 ? Math.max(...candidates) : null;
+    };
+    codexAccountRateLimitReached = (accountRateLimits) => [accountRateLimits.rateLimits].some((snapshot) => snapshot.rateLimitReachedType !== null || snapshot.spendControlReached === true || snapshot.primary?.usedPercent !== void 0 && snapshot.primary.usedPercent >= 100 || snapshot.secondary?.usedPercent !== void 0 && snapshot.secondary.usedPercent >= 100);
     forbiddenMethod = (method) => method.startsWith("mcpServer/") || method.startsWith("serverRequest/") || method.startsWith("item/mcpToolCall") || method.startsWith("item/commandExecution") || method.startsWith("item/fileChange") || method.startsWith("item/dynamicToolCall") || method.startsWith("item/collabAgentToolCall");
     forbiddenTerminalItem = (item) => ![
       "userMessage",
@@ -18562,13 +18715,13 @@ var init_codex_app_server = __esm({
     ].includes(String(item.type || ""));
     classifyCodexTurnFailure = (codexErrorInfo, terminalStatus) => {
       if (terminalStatus === "interrupted") {
-        return { code: "cancelled", category: "cancelled", retryable: false };
+        return { code: "cancelled", category: "cancelled", retryable: false, httpStatusCode: null };
       }
       if (codexErrorInfo === "usageLimitExceeded") {
-        return { code: "quota_exceeded", category: "model", retryable: false };
+        return { code: "quota_exceeded", category: "model", retryable: false, httpStatusCode: null };
       }
       if (codexErrorInfo === "unauthorized") {
-        return { code: "auth_expired", category: "auth", retryable: false };
+        return { code: "auth_expired", category: "auth", retryable: false, httpStatusCode: null };
       }
       const stableStringCodes = {
         badRequest: "codex_bad_request",
@@ -18585,22 +18738,40 @@ var init_codex_app_server = __esm({
         return {
           code,
           category: "adapter",
-          retryable: code === "codex_internal_error" || code === "codex_server_overloaded"
+          retryable: code === "codex_internal_error" || code === "codex_server_overloaded",
+          httpStatusCode: null
         };
       }
       const structured = objectOrNull(codexErrorInfo);
       if (structured) {
-        if ("httpConnectionFailed" in structured) {
-          return { code: "codex_http_connection_failed", category: "adapter", retryable: true };
-        }
-        if ("responseStreamConnectionFailed" in structured) {
-          return { code: "codex_response_stream_connection_failed", category: "adapter", retryable: true };
-        }
-        if ("responseStreamDisconnected" in structured) {
-          return { code: "codex_response_stream_disconnected", category: "adapter", retryable: true };
+        const variants = [
+          ["httpConnectionFailed", "codex_http_connection_failed"],
+          ["responseStreamConnectionFailed", "codex_response_stream_connection_failed"],
+          ["responseStreamDisconnected", "codex_response_stream_disconnected"],
+          ["responseTooManyFailedAttempts", "codex_provider_retry_exhausted"]
+        ];
+        for (const [variant, code] of variants) {
+          if (!(variant in structured)) continue;
+          const details = objectOrNull(structured[variant]);
+          const rawStatus = details?.httpStatusCode;
+          const httpStatusCode = Number.isSafeInteger(rawStatus) && Number(rawStatus) >= 100 && Number(rawStatus) <= 599 ? Number(rawStatus) : null;
+          if (httpStatusCode === 429) {
+            return {
+              code: "codex_rate_limited",
+              category: "adapter",
+              retryable: true,
+              httpStatusCode
+            };
+          }
+          return {
+            code,
+            category: "adapter",
+            retryable: httpStatusCode === null ? variant !== "responseTooManyFailedAttempts" : httpStatusCode === 408 || httpStatusCode === 425 || httpStatusCode >= 500,
+            httpStatusCode
+          };
         }
       }
-      return { code: "turn_failed", category: "adapter", retryable: false };
+      return { code: "turn_failed", category: "adapter", retryable: false, httpStatusCode: null };
     };
     scrubbedCodexEnvironment = (codexHome) => {
       if (process.platform === "win32") {
@@ -19080,13 +19251,80 @@ child.once('close', async () => {
         this.fatalListeners.add(listener);
         return () => this.fatalListeners.delete(listener);
       }
-      async hasManagedChatGptAuth(deadlineAtMs, signal, refreshToken = false) {
+      async readAccountSnapshot(deadlineAtMs, signal, refreshToken = false) {
         const result2 = await this.request("account/read", { refreshToken }, {
           timeoutMs: Math.max(1, deadlineAtMs - Date.now()),
           signal
         });
         const account = objectOrNull(result2.account);
-        return account?.type === "chatgpt" && result2.requiresOpenaiAuth === true;
+        if (typeof result2.requiresOpenaiAuth !== "boolean") {
+          throw new CodexAppServerError({
+            message: "Codex returned invalid account metadata.",
+            category: "auth",
+            code: "invalid_account_metadata",
+            retryable: false
+          });
+        }
+        if (account?.type === "chatgpt") {
+          const email3 = account.email === null ? null : typeof account.email === "string" && account.email.trim() ? account.email.trim() : void 0;
+          if (email3 === void 0 || !validPlanType(account.planType)) {
+            throw new CodexAppServerError({
+              message: "Codex returned invalid managed ChatGPT account metadata.",
+              category: "auth",
+              code: "invalid_account_metadata",
+              retryable: false
+            });
+          }
+          return {
+            requiresOpenaiAuth: result2.requiresOpenaiAuth,
+            authenticatedChatGptAccount: { email: email3, planType: account.planType }
+          };
+        }
+        if (account !== null && account?.type !== "apiKey" && account?.type !== "amazonBedrock") {
+          throw new CodexAppServerError({
+            message: "Codex returned an unsupported account type.",
+            category: "auth",
+            code: "invalid_account_metadata",
+            retryable: false
+          });
+        }
+        return {
+          requiresOpenaiAuth: result2.requiresOpenaiAuth,
+          authenticatedChatGptAccount: null
+        };
+      }
+      async hasManagedChatGptAuth(deadlineAtMs, signal, refreshToken = false) {
+        const snapshot = await this.readAccountSnapshot(deadlineAtMs, signal, refreshToken);
+        return snapshot.authenticatedChatGptAccount !== null && snapshot.requiresOpenaiAuth;
+      }
+      async readAccountRateLimits(deadlineAtMs, signal) {
+        const result2 = await this.request("account/rateLimits/read", void 0, {
+          timeoutMs: Math.max(1, deadlineAtMs - Date.now()),
+          signal
+        });
+        try {
+          const rateLimits = parseRateLimitSnapshot(result2.rateLimits);
+          const rawByLimitId = result2.rateLimitsByLimitId;
+          let rateLimitsByLimitId = null;
+          if (rawByLimitId !== null && rawByLimitId !== void 0) {
+            const byLimitId = objectOrNull(rawByLimitId);
+            if (!byLimitId) throw new Error("invalid rate-limit bucket map");
+            rateLimitsByLimitId = {};
+            for (const [limitId, snapshot] of Object.entries(byLimitId)) {
+              if (!limitId.trim()) throw new Error("invalid rate-limit bucket identity");
+              rateLimitsByLimitId[limitId] = parseRateLimitSnapshot(snapshot);
+            }
+          }
+          return { rateLimits, rateLimitsByLimitId };
+        } catch (error48) {
+          throw new CodexAppServerError({
+            message: "Codex returned invalid account rate-limit metadata.",
+            category: "adapter",
+            code: "invalid_rate_limit_metadata",
+            retryable: false,
+            cause: error48
+          });
+        }
       }
       async requireManagedChatGptAuth(deadlineAtMs, signal, refreshToken = false) {
         if (!await this.hasManagedChatGptAuth(deadlineAtMs, signal, refreshToken)) {
@@ -19623,13 +19861,54 @@ child.once('close', async () => {
           }
           if (terminal.status !== "completed") {
             const turnError = objectOrNull(terminal.error);
-            const failure = classifyCodexTurnFailure(turnError?.codexErrorInfo, String(terminal.status));
+            let failure = classifyCodexTurnFailure(
+              turnError?.codexErrorInfo,
+              String(terminal.status)
+            );
+            const observedUsage = threadUsage ?? rawResponseUsage;
+            let retryAtMs = null;
+            if (failure.code === "quota_exceeded" || failure.httpStatusCode === 429) {
+              const observedAtMs = Date.now();
+              let accountLimitReached = failure.code === "quota_exceeded";
+              try {
+                const metadataDeadlineAtMs = Math.min(
+                  request.deadlineAtMs,
+                  observedAtMs + 5e3
+                );
+                if (metadataDeadlineAtMs <= observedAtMs) throw new Error("rate-limit deadline elapsed");
+                const rateLimits = await this.readAccountRateLimits(metadataDeadlineAtMs, request.signal);
+                accountLimitReached = accountLimitReached || codexAccountRateLimitReached(rateLimits);
+                retryAtMs = codexRateLimitRetryAtMs(rateLimits);
+              } catch {
+              }
+              if (accountLimitReached) {
+                failure = {
+                  ...failure,
+                  code: "quota_exceeded",
+                  category: "model",
+                  retryable: false
+                };
+                if (retryAtMs === null || retryAtMs <= observedAtMs) {
+                  retryAtMs = observedAtMs + DEFAULT_CODEX_QUOTA_COOLDOWN_MS;
+                } else {
+                  retryAtMs = Math.min(
+                    retryAtMs,
+                    observedAtMs + MAX_CODEX_QUOTA_COOLDOWN_MS
+                  );
+                }
+              } else {
+                retryAtMs = observedAtMs + CODEX_TRANSIENT_RATE_LIMIT_COOLDOWN_MS;
+              }
+            }
             throw new CodexAppServerError({
               message: "Codex turn did not complete successfully.",
               category: failure.category,
               code: failure.code,
               retryable: failure.retryable,
-              dispatchOutcome: "confirmed_dispatched"
+              dispatchOutcome: "confirmed_dispatched",
+              httpStatusCode: failure.httpStatusCode,
+              retryAtMs,
+              usage: observedUsage
             });
           }
           const items = Array.isArray(terminal.items) ? terminal.items.map(objectOrNull) : [];
@@ -19989,7 +20268,10 @@ var init_codex_adapter = __esm({
           category: external_exports.enum(["auth", "model", "schema", "timeout", "cancelled", "transport", "adapter"]),
           code: external_exports.string().min(1).max(96),
           retryable: external_exports.boolean(),
-          dispatchOutcome: external_exports.enum(["not_dispatched", "confirmed_dispatched", "outcome_unknown"])
+          dispatchOutcome: external_exports.enum(["not_dispatched", "confirmed_dispatched", "outcome_unknown"]),
+          httpStatusCode: external_exports.number().int().min(100).max(599).nullable().optional(),
+          retryAtMs: external_exports.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).nullable().optional(),
+          usage: tokenUsageReceiptSchema.nullable().optional()
         })
       })
     ]);
@@ -20510,7 +20792,10 @@ var init_codex_adapter = __esm({
               category: recovered.category,
               code: recovered.code,
               retryable: recovered.retryable,
-              dispatchOutcome: recovered.dispatchOutcome
+              dispatchOutcome: recovered.dispatchOutcome,
+              httpStatusCode: recovered.httpStatusCode,
+              retryAtMs: recovered.retryAtMs,
+              usage: recovered.usage
             });
           }
           throw new CodexAppServerError({
@@ -20649,7 +20934,10 @@ var init_codex_adapter = __esm({
                     category: error48.category,
                     code: error48.code,
                     retryable: error48.retryable,
-                    dispatchOutcome
+                    dispatchOutcome,
+                    httpStatusCode: error48.httpStatusCode,
+                    retryAtMs: error48.retryAtMs,
+                    usage: error48.usage
                   }
                 }
               };
@@ -20662,6 +20950,9 @@ var init_codex_adapter = __esm({
               code: error48.code,
               retryable: error48.retryable,
               dispatchOutcome,
+              httpStatusCode: error48.httpStatusCode,
+              retryAtMs: error48.retryAtMs,
+              usage: error48.usage,
               cause: error48
             });
           }
@@ -27341,7 +27632,7 @@ function createDefaultInferenceHostRunnerDependencies(options) {
     envelopePublicKey: options.envelopePublicKey
   };
 }
-var import_ajv, RUNTIME_RECEIPT_SCHEMA_VERSION, ATTEMPT_RECEIPT_SCHEMA_VERSION, DEFAULT_ADVERTISEMENT_TTL_MS, DEFAULT_ADVERTISEMENT_REFRESH_LEAD_MS, DEFAULT_HOST_HEARTBEAT_MS, DEFAULT_ATTEMPT_HEARTBEAT_MS, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_REMOTE_RETRY_LIMIT, DEFAULT_MAX_CONCURRENCY, MIN_SLEEP_MS, CODEX_INFERENCE_ADVERTISED_MODEL, FileInferenceHostRuntimeReceiptStore, InferenceHostRecoveryRequiredError, InferenceHostRunnerError, defaultSleep, abortError, defaultRegisterSignalHandlers, safeInteger, exactObjectKeys, validIso, validateAttemptReceipt, validateRuntimeReceipt, sha256, stableOperationId, buildAttemptStartRequest, isoAt, finitePositiveOption, validateRunnerOptions, assertLocalCredentialIdentity, retryableRemoteError, controlPlaneFatal, defaultValidateOutput, objectRecord, positiveUtf8ByteLimit, assertCompilableOutputSchema, parseOutputContract, safeFailureCode, exactJson2, runnerIdentityMismatch, assertAdvertisementResult, assertHostHeartbeatResult, assertClaimResult, assertStartResult, assertJobHeartbeatResult, assertTerminalResult, classifyFailure, ambiguousHeartbeatTransport, reportedUsage, InferenceHostRunner;
+var import_ajv, RUNTIME_RECEIPT_SCHEMA_VERSION, ATTEMPT_RECEIPT_SCHEMA_VERSION, DEFAULT_ADVERTISEMENT_TTL_MS, DEFAULT_ADVERTISEMENT_REFRESH_LEAD_MS, DEFAULT_HOST_HEARTBEAT_MS, DEFAULT_ATTEMPT_HEARTBEAT_MS, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_REMOTE_RETRY_LIMIT, DEFAULT_MAX_CONCURRENCY, MIN_SLEEP_MS, DEFAULT_CODEX_ACCOUNT_COOLDOWN_MS, CODEX_INFERENCE_ADVERTISED_MODEL, FileInferenceHostRuntimeReceiptStore, InferenceHostRecoveryRequiredError, InferenceHostRunnerError, defaultSleep, abortError, defaultRegisterSignalHandlers, safeInteger, exactObjectKeys, validIso, validateAttemptReceipt, validateRuntimeReceipt, sha256, stableOperationId, buildAttemptStartRequest, isoAt, finitePositiveOption, validateRunnerOptions, assertLocalCredentialIdentity, retryableRemoteError, remoteRetryAfterMs, controlPlaneFatal, defaultValidateOutput, objectRecord, positiveUtf8ByteLimit, assertCompilableOutputSchema, parseOutputContract, safeFailureCode, exactJson2, runnerIdentityMismatch, assertAdvertisementResult, assertHostHeartbeatResult, assertClaimResult, assertStartResult, assertJobHeartbeatResult, assertTerminalResult, classifyFailure, ambiguousHeartbeatTransport, reportedTokenUsage, reportedUsage, InferenceHostRunner;
 var init_runner = __esm({
   "lib/inference-host/runner.ts"() {
     "use strict";
@@ -27364,6 +27655,7 @@ var init_runner = __esm({
     DEFAULT_REMOTE_RETRY_LIMIT = 3;
     DEFAULT_MAX_CONCURRENCY = 1;
     MIN_SLEEP_MS = 10;
+    DEFAULT_CODEX_ACCOUNT_COOLDOWN_MS = 5 * 60 * 1e3;
     CODEX_INFERENCE_ADVERTISED_MODEL = Object.freeze({
       model_id: INITIAL_CODEX_INFERENCE_MODEL,
       label: "Codex GPT-5.6 Sol",
@@ -27653,19 +27945,14 @@ var init_runner = __esm({
     };
     retryableRemoteError = (error48) => {
       if (error48 instanceof ExternalInferenceMcpError) {
-        return [
-          "network_error",
-          "transport_rejected",
-          "invalid_response",
-          "request_timeout",
-          "authentication_timeout"
-        ].includes(error48.code);
+        return error48.retryable;
       }
       if (error48 && typeof error48 === "object" && "retryable" in error48) {
         return error48.retryable === true;
       }
       return false;
     };
+    remoteRetryAfterMs = (error48, fallbackMs) => error48 instanceof ExternalInferenceMcpError && error48.retryAfterMs !== null && Number.isSafeInteger(error48.retryAfterMs) && error48.retryAfterMs >= 0 ? Math.max(fallbackMs, error48.retryAfterMs) : fallbackMs;
     controlPlaneFatal = (error48) => {
       const code = error48 && typeof error48 === "object" && "code" in error48 ? String(error48.code) : "";
       return [
@@ -27788,11 +28075,12 @@ var init_runner = __esm({
     };
     assertAdvertisementResult = (advertisement, result2) => {
       const host = result2.host;
-      if (host.host_id !== advertisement.host_id || host.host_generation !== advertisement.host_generation || host.advertisement_generation !== advertisement.advertisement_generation || host.key_generation !== advertisement.key_generation || host.display_name !== advertisement.display_name || host.adapter !== advertisement.adapter || host.status === "revoked" || !exactJson2(host.models, advertisement.models)) runnerIdentityMismatch("Host advertisement");
+      if (host.host_id !== advertisement.host_id || host.host_generation !== advertisement.host_generation || host.advertisement_generation !== advertisement.advertisement_generation || host.key_generation !== advertisement.key_generation || host.display_name !== advertisement.display_name || (host.authenticated_account_email ?? null) !== (advertisement.authenticated_account_email ?? null) || (host.authenticated_account_plan ?? null) !== (advertisement.authenticated_account_plan ?? null) || host.adapter !== advertisement.adapter || host.status === "revoked" || !exactJson2(host.models, advertisement.models)) runnerIdentityMismatch("Host advertisement");
     };
-    assertHostHeartbeatResult = (request, result2) => {
+    assertHostHeartbeatResult = (request, result2, allowOfflineProjection = false) => {
       const expectedStatus = request.status === "healthy" ? "online" : request.status;
-      if (result2.host.host_id !== request.host_id || result2.host.host_generation !== request.host_generation || result2.host.advertisement_generation !== request.advertisement_generation || result2.host.key_generation !== request.key_generation || result2.host.adapter !== "codex" || result2.host.status !== expectedStatus) runnerIdentityMismatch("Host heartbeat");
+      const expectedTemporaryOffline = allowOfflineProjection && request.status === "healthy" && result2.host.status === "offline";
+      if (result2.host.host_id !== request.host_id || result2.host.host_generation !== request.host_generation || result2.host.advertisement_generation !== request.advertisement_generation || result2.host.key_generation !== request.key_generation || result2.host.adapter !== "codex" || result2.host.status !== expectedStatus && !expectedTemporaryOffline) runnerIdentityMismatch("Host heartbeat");
     };
     assertClaimResult = (request, result2) => {
       if (result2.claim_request_id !== request.claim_request_id) {
@@ -27828,7 +28116,13 @@ var init_runner = __esm({
         };
       }
       if (error48 instanceof ExternalInferenceMcpError) {
-        const category2 = error48.code.startsWith("authentication") ? "auth" : ["network_error", "transport_rejected", "request_timeout"].includes(error48.code) ? "network" : "transport";
+        const category2 = error48.code.startsWith("authentication") ? "auth" : [
+          "network_error",
+          "transport_rejected",
+          "server_rejected",
+          "rate_limited",
+          "request_timeout"
+        ].includes(error48.code) ? "network" : "transport";
         return {
           category: category2,
           code: safeFailureCode(error48.code, "transport_failure"),
@@ -27854,24 +28148,27 @@ var init_runner = __esm({
       return [
         "network_error",
         "transport_rejected",
+        "server_rejected",
+        "rate_limited",
         "invalid_response",
         "identity_mismatch",
         "request_timeout",
         "authentication_timeout"
       ].includes(code);
     };
-    reportedUsage = (result2) => ({
+    reportedTokenUsage = (usage) => ({
       schema_version: EXTERNAL_INFERENCE_USAGE_SCHEMA_VERSION,
       availability: "reported",
       source: "codex_app_server",
-      input_tokens: result2.usage.inputTokens,
-      cached_input_tokens: result2.usage.cachedInputTokens,
-      output_tokens: result2.usage.outputTokens,
-      reasoning_output_tokens: result2.usage.reasoningOutputTokens,
-      total_tokens: result2.usage.totalTokens,
-      cache_write_input_tokens: result2.usage.cacheWriteInputTokens,
-      cache_write_support: result2.usage.cacheWriteSupported ? "reported" : "unsupported"
-    });
+      input_tokens: usage.inputTokens,
+      cached_input_tokens: usage.cachedInputTokens,
+      output_tokens: usage.outputTokens,
+      reasoning_output_tokens: usage.reasoningOutputTokens,
+      total_tokens: usage.totalTokens,
+      cache_write_input_tokens: usage.cacheWriteInputTokens,
+      cache_write_support: usage.cacheWriteSupported ? "reported" : "unsupported"
+    });
+    reportedUsage = (result2) => reportedTokenUsage(result2.usage);
     InferenceHostRunner = class {
       constructor(dependencies, options) {
         this.receiptWriteChain = Promise.resolve();
@@ -28034,24 +28331,24 @@ var init_runner = __esm({
               } catch (error48) {
                 lastError = error48;
                 if (!retryableRemoteError(error48) || attempt === settings.remoteRetryLimit) throw error48;
-                const retryDelay = Math.min(
-                  250 * attempt,
-                  1e3,
-                  boundary.deadlineAtMs === void 0 ? Number.POSITIVE_INFINITY : Math.max(0, boundary.deadlineAtMs - now())
+                const requestedRetryDelay = remoteRetryAfterMs(
+                  error48,
+                  Math.min(250 * attempt, 1e3)
                 );
-                if (retryDelay < 1) {
+                const remaining = boundary.deadlineAtMs === void 0 ? Number.POSITIVE_INFINITY : Math.max(0, boundary.deadlineAtMs - now());
+                if (requestedRetryDelay < 1 || requestedRetryDelay >= remaining) {
                   throw new ExternalInferenceMcpError(
                     "request_timeout",
                     "Insights MCP retry deadline elapsed.",
                     { cause: error48 }
                   );
                 }
-                await sleep4(retryDelay, boundary.signal);
+                await sleep4(requestedRetryDelay, boundary.signal);
               }
             }
             throw lastError;
           };
-          const publishAdvertisement = async (health, forceAdvance) => {
+          const publishAdvertisement = async (health, forceAdvance, retryRemote = true) => {
             let advertisement = receipt.pending_advertisement;
             if (!advertisement) {
               const generation = receipt.registered && forceAdvance ? receipt.advertisement_generation + 1 : receipt.advertisement_generation;
@@ -28072,6 +28369,8 @@ var init_runner = __esm({
                 key_generation: localState.key_generation,
                 adapter: "codex",
                 display_name: this.options.displayName.trim(),
+                authenticated_account_email: this.options.authenticatedAccountEmail ?? null,
+                authenticated_account_plan: this.options.authenticatedAccountPlan ?? null,
                 protocol_version: this.options.protocolVersion,
                 envelope_public_key: envelopePublicKey,
                 health,
@@ -28094,15 +28393,12 @@ var init_runner = __esm({
             const tool = receipt.registered ? "inference.host.advertise" : "inference.host.register";
             let result2;
             try {
-              result2 = tool === "inference.host.register" ? await retryExact(() => mcp.callTool(
-                tool,
-                advertisement,
-                { signal: this.options.signal }
-              ), { signal: this.options.signal }) : await retryExact(() => mcp.callTool(
+              const advertiseOperation = () => mcp.callTool(
                 tool,
                 advertisement,
                 { signal: this.options.signal }
-              ), { signal: this.options.signal });
+              );
+              result2 = retryRemote ? await retryExact(advertiseOperation, { signal: this.options.signal }) : await advertiseOperation();
             } catch (error48) {
               const definitivelyNotApplied = error48 instanceof ExternalInferenceMcpError ? error48.definitivelyNotApplied : Boolean(error48 && typeof error48 === "object" && error48.definitivelyNotApplied === true);
               const expectedGeneration = receipt.registered ? receipt.advertisement_generation + 1 : receipt.advertisement_generation;
@@ -28113,7 +28409,7 @@ var init_runner = __esm({
                   updated_at: isoAt(now())
                 };
                 await this.persistReceipt(receipt, now);
-                return await publishAdvertisement(health, forceAdvance);
+                return await publishAdvertisement(health, forceAdvance, retryRemote);
               }
               throw error48;
             }
@@ -28135,7 +28431,7 @@ var init_runner = __esm({
           }
           const hostHeartbeat = async (status, requestOptions = {
             signal: this.options.signal
-          }) => {
+          }, retryRemote = true, allowOfflineProjection = false) => {
             const sequence = receipt.host_heartbeat_sequence + 1;
             const request = {
               schema_version: "external_inference_host_heartbeat_v1",
@@ -28161,9 +28457,9 @@ var init_runner = __esm({
               request,
               requestOptions
             );
-            const result2 = status === "draining" ? await heartbeatOperation() : await retryExact(heartbeatOperation, requestOptions);
-            assertHostHeartbeatResult(request, result2);
-            if (["revoked", "offline"].includes(result2.host.status)) {
+            const result2 = status === "draining" || !retryRemote ? await heartbeatOperation() : await retryExact(heartbeatOperation, requestOptions);
+            assertHostHeartbeatResult(request, result2, allowOfflineProjection);
+            if (result2.host.status === "revoked" || result2.host.status === "offline" && !allowOfflineProjection) {
               const error48 = new InferenceHostRunnerError(
                 result2.host.status === "revoked" ? "host_revoked" : "host_offline",
                 "The external inference host is no longer active."
@@ -28173,7 +28469,9 @@ var init_runner = __esm({
           };
           await hostHeartbeat("healthy");
           let nextHostHeartbeatAt = now() + settings.hostHeartbeatMs;
-          let nextClaimAt = now();
+          let nextAdvertisementAttemptAt = 0;
+          let providerRetryAtMs = this.options.codexRateLimits && codexAccountRateLimitReached(this.options.codexRateLimits) ? codexRateLimitRetryAtMs(this.options.codexRateLimits) ?? now() + DEFAULT_CODEX_ACCOUNT_COOLDOWN_MS : null;
+          let nextClaimAt = Math.max(now(), providerRetryAtMs ?? 0);
           let onceClaimed = false;
           const launchClaim = (claim, recovery) => {
             if (!recovery) {
@@ -28211,6 +28509,11 @@ var init_runner = __esm({
               attemptHeartbeatMs: settings.attemptHeartbeatMs,
               sleep: sleep4,
               now,
+              onProviderCooldown: (retryAtMs) => {
+                if (!Number.isSafeInteger(retryAtMs) || retryAtMs <= now()) return;
+                providerRetryAtMs = Math.max(providerRetryAtMs ?? 0, retryAtMs);
+                nextClaimAt = Math.max(nextClaimAt, providerRetryAtMs);
+              },
               resumeReceipt: recovery
             }).then((outcome) => {
               if (outcome === "completed") completed += 1;
@@ -28270,22 +28573,46 @@ var init_runner = __esm({
           while (!drainRequested) {
             const currentTime = now();
             const expiresAt = receipt.advertisement_expires_at ? Date.parse(receipt.advertisement_expires_at) : 0;
-            if (expiresAt - currentTime <= settings.advertisementRefreshLeadMs) {
+            if (currentTime >= nextAdvertisementAttemptAt && expiresAt - currentTime <= settings.advertisementRefreshLeadMs) {
               try {
-                await publishAdvertisement("healthy", true);
+                await publishAdvertisement("healthy", true, false);
+                nextAdvertisementAttemptAt = 0;
               } catch (error48) {
-                requestDrain(controlPlaneFatal(error48) ? "authority_lost" : "advertisement_failed");
-                break;
+                if (controlPlaneFatal(error48)) {
+                  requestDrain("authority_lost");
+                  break;
+                }
+                if (!retryableRemoteError(error48)) {
+                  requestDrain("advertisement_failed");
+                  break;
+                }
+                nextAdvertisementAttemptAt = now() + remoteRetryAfterMs(error48, 1e3);
+                nextClaimAt = Math.max(nextClaimAt, nextAdvertisementAttemptAt);
               }
             }
             if (currentTime >= nextHostHeartbeatAt) {
               try {
-                await hostHeartbeat("healthy");
+                const refreshPendingAcrossExpiry = receipt.pending_advertisement !== null && expiresAt <= currentTime && nextAdvertisementAttemptAt > currentTime;
+                await hostHeartbeat(
+                  "healthy",
+                  { signal: this.options.signal },
+                  false,
+                  refreshPendingAcrossExpiry
+                );
               } catch (error48) {
-                requestDrain(controlPlaneFatal(error48) ? "authority_lost" : "host_heartbeat_failed");
-                break;
+                if (controlPlaneFatal(error48)) {
+                  requestDrain("authority_lost");
+                  break;
+                }
+                if (!retryableRemoteError(error48)) {
+                  requestDrain("host_heartbeat_failed");
+                  break;
+                }
+                nextHostHeartbeatAt = now() + remoteRetryAfterMs(error48, settings.hostHeartbeatMs);
+              }
+              if (!drainRequested && currentTime >= nextHostHeartbeatAt) {
+                nextHostHeartbeatAt = now() + settings.hostHeartbeatMs;
               }
-              nextHostHeartbeatAt = now() + settings.hostHeartbeatMs;
             }
             while (recoveryQueue.length > 0 && active.size < settings.maxConcurrency) {
               const recovery = recoveryQueue.shift();
@@ -28316,15 +28643,19 @@ var init_runner = __esm({
               await this.persistReceipt(receipt, now);
               let claim;
               try {
-                claim = await retryExact(() => mcp.callTool(
+                claim = await mcp.callTool(
                   "inference.job.claim",
                   request,
                   { signal: this.options.signal }
-                ), { signal: this.options.signal });
+                );
                 assertClaimResult(request, claim);
               } catch (error48) {
-                if (!this.options.signal?.aborted) {
-                  requestDrain(controlPlaneFatal(error48) ? "authority_lost" : "claim_failed");
+                if (!this.options.signal?.aborted && controlPlaneFatal(error48)) {
+                  requestDrain("authority_lost");
+                } else if (!this.options.signal?.aborted && retryableRemoteError(error48)) {
+                  nextClaimAt = now() + remoteRetryAfterMs(error48, 1e3);
+                } else if (!this.options.signal?.aborted) {
+                  requestDrain("claim_failed");
                 }
                 break;
               }
@@ -28337,10 +28668,12 @@ var init_runner = __esm({
               if (this.options.once) requestDrain("once_complete");
             }
             if (drainRequested) break;
-            const wakeAt = Math.min(nextClaimAt, nextHostHeartbeatAt, Math.max(
-              now() + MIN_SLEEP_MS,
-              receipt.advertisement_expires_at ? Date.parse(receipt.advertisement_expires_at) - settings.advertisementRefreshLeadMs : now() + MIN_SLEEP_MS
-            ));
+            const advertisementDueAt = nextAdvertisementAttemptAt > now() ? nextAdvertisementAttemptAt : receipt.advertisement_expires_at ? Date.parse(receipt.advertisement_expires_at) - settings.advertisementRefreshLeadMs : now() + MIN_SLEEP_MS;
+            const wakeAt = Math.min(
+              nextClaimAt,
+              nextHostHeartbeatAt,
+              Math.max(now() + MIN_SLEEP_MS, advertisementDueAt)
+            );
             await Promise.race([
               sleep4(Math.max(MIN_SLEEP_MS, wakeAt - now())),
               drainSignal,
@@ -28684,6 +29017,9 @@ var init_runner = __esm({
           if (error48 instanceof InferenceHostRunnerError && error48.code === "terminal_outcome_unconfirmed") {
             throw error48;
           }
+          if (error48 instanceof CodexAppServerError && error48.retryAtMs !== null && ["quota_exceeded", "codex_rate_limited"].includes(error48.code)) {
+            options.onProviderCooldown?.(error48.retryAtMs);
+          }
           const classified = classifyFailure(heartbeatFailure ?? error48, adapterResult);
           const heartbeatAmbiguous = ambiguousHeartbeatTransport(heartbeatFailure);
           const failure = heartbeatAmbiguous ? {
@@ -28734,7 +29070,7 @@ var init_runner = __esm({
               adapter_request_id: canReportEffective ? adapterResult?.adapterRequestId ?? null : null,
               adapter_response_id: canReportEffective ? adapterResult?.adapterResponseId ?? null : null
             },
-            usage: adapterResult ? reportedUsage(adapterResult) : null,
+            usage: adapterResult ? reportedUsage(adapterResult) : error48 instanceof CodexAppServerError && error48.usage ? reportedTokenUsage(error48.usage) : null,
             failure_category: failure.category,
             failure_code: failure.code,
             retryable: failure.retryable,
@@ -28808,6 +29144,9 @@ import { join as join5, resolve as resolve4 } from "node:path";
 async function runInferenceHostCli(argv2, env = process.env, dependencies = {}) {
   const warnings = [];
   try {
+    if (argv2.includes("--help") || argv2.includes("-h") || argv2[1] === "help") {
+      return { exitCode: 0, stdout: INFERENCE_HOST_HELP, stderr: "" };
+    }
     const parsed = parseInferenceHostArgs(argv2, env);
     const config2 = resolveInferenceHostConfig(env);
     if (parsed.command === "login") {
@@ -28873,7 +29212,7 @@ async function runInferenceHostCli(argv2, env = process.env, dependencies = {})
     };
   }
 }
-var INFERENCE_HOST_CLI_VERSION, runtimeReceiptPath, codexRecoveryPath, codexGuardianReceiptRoot, revocationCheckpointPath, foregroundHostLockPath, AGENT_HEARTBEAT_INTERVAL_MS, AGENT_HEARTBEAT_MAX_RETRY_DELAY_MS, retryableAgentHeartbeatError, assertRevocationCheckpoint, readRevocationCheckpoint, writeRevocationCheckpoint, clearRevocationCheckpoint, render, parsePositiveInteger, parseInferenceHostArgs, defaultOpenBrowser, defaultRegisterLifecycleSignalHandlers, lifecycleCancellation, configuredCredentialStore, accountKeyForState, assertCredentialMatchesState2, revocationCheckpointForCredential, assertRevocationCheckpointMatchesLocalIdentity, fileExistsPrivately, inspectCodexAuthentication, clearLocalRuntimeArtifacts, assertLocalRuntimeArtifactsMayBeDiscarded, defaultRunForeground, login, codexLogin, codexLogout, localStatus, doctor, cleanupLogin, runHost, defaultReadStdin, parseAgentStdin, agentOperationId, agentSession, agentConnect, agentRun, agentNext, agentComplete, agentFail, withAgentCommandLock;
+var INFERENCE_HOST_CLI_VERSION, runtimeReceiptPath, codexRecoveryPath, codexGuardianReceiptRoot, revocationCheckpointPath, foregroundHostLockPath, AGENT_HEARTBEAT_INTERVAL_MS, AGENT_HEARTBEAT_MAX_RETRY_DELAY_MS, retryableAgentHeartbeatError, assertRevocationCheckpoint, readRevocationCheckpoint, writeRevocationCheckpoint, clearRevocationCheckpoint, render, INFERENCE_HOST_HELP, parsePositiveInteger, parseInferenceHostArgs, defaultOpenBrowser, defaultRegisterLifecycleSignalHandlers, lifecycleCancellation, configuredCredentialStore, accountKeyForState, assertCredentialMatchesState2, revocationCheckpointForCredential, assertRevocationCheckpointMatchesLocalIdentity, fileExistsPrivately, inspectCodexAuthentication, clearLocalRuntimeArtifacts, assertLocalRuntimeArtifactsMayBeDiscarded, defaultRunForeground, login, codexLogin, codexLogout, localStatus, doctor, cleanupLogin, runHost, defaultReadStdin, parseAgentStdin, agentOperationId, agentSession, agentConnect, agentRun, agentNext, agentComplete, agentFail, withAgentCommandLock;
 var init_cli = __esm({
   "lib/inference-host/cli.ts"() {
     "use strict";
@@ -28955,6 +29294,31 @@ var init_cli = __esm({
     render = (value, json2) => json2 ? `${JSON.stringify(value, null, 2)}
 ` : typeof value === "string" ? `${value}
 ` : `${JSON.stringify(value, null, 2)}
+`;
+    INFERENCE_HOST_HELP = `Usage: vtx inference-host <command> [options]
+
+Commands:
+  login           Authorize the isolated VTX insights:inference grant
+  codex-login     Sign the automated Codex host into a ChatGPT subscription
+  run             Run the automated Codex inference host in the foreground
+  agent-connect   Advertise a model from a compatible agent harness
+  agent-run       Keep an agent-driven host online in the foreground
+  agent-next      Claim the next exact VTX inference request
+  agent-complete  Submit one completed agent result from stdin
+  agent-fail      Submit one truthful agent failure from stdin
+  status          Inspect local host and credential state
+  doctor          Verify credentials, Codex, and private runtime state
+  logout          Remove local VTX host state without revoking the grant
+  revoke          Revoke the VTX grant and remove local host state
+  codex-logout    Remove the automated host's dedicated Codex login
+
+Common options:
+  --json           Emit machine-readable JSON
+  --help, -h       Show this help
+
+If the OS credential store cannot retain the VTX grant, set
+VTX_INFERENCE_HOST_CREDENTIAL_STORE=file before login to use the supported
+private-file fallback. See https://vtxmacro.com/insights#subscription-inference.
 `;
     parsePositiveInteger = (raw, label) => {
       const value = Number(raw);
@@ -29194,6 +29558,9 @@ var init_cli = __esm({
         acquireProcessLock: async () => borrowedProcessLock
       }, {
         displayName: options.displayName,
+        authenticatedAccountEmail: options.authenticatedAccountEmail,
+        authenticatedAccountPlan: options.authenticatedAccountPlan,
+        codexRateLimits: options.codexRateLimits,
         protocolVersion: EXTERNAL_INFERENCE_CONTRACT_VERSION,
         adapterRuntimeVersion: INFERENCE_HOST_CLI_VERSION,
         maxConcurrency: options.maxConcurrency,
@@ -29677,7 +30044,7 @@ Waiting for approval...
         cancellation.signal.throwIfAborted();
         const hostResources = await (dependencies.createHostResources ?? createIsolatedCodexHostResources)(config2.codexHomePath);
         try {
-          await (dependencies.preflightCodex ?? preflightCodexSubscription)({
+          const preflight = await (dependencies.preflightCodex ?? preflightCodexSubscription)({
             binary: verifiedBinary,
             codexHome: config2.codexHomePath,
             deadlineAtMs: Date.now() + 3e4,
@@ -29689,6 +30056,9 @@ Waiting for approval...
             verifiedBinary,
             hostResources,
             displayName: parsed.displayName,
+            authenticatedAccountEmail: preflight?.authenticated_account_email ?? null,
+            authenticatedAccountPlan: preflight?.authenticated_account_plan ?? null,
+            codexRateLimits: preflight?.rate_limits ?? null,
             maxConcurrency: parsed.maxConcurrency,
             once: parsed.once,
             env,
@@ -48303,6 +48673,9 @@ Waiting for approval...
 }
 async function runVtxCli(argv2, env = process.env) {
   try {
+    if (argv2.length === 0 || argv2.includes("--help") || argv2.includes("-h") || argv2[0] === "help") {
+      return { exitCode: 0, stdout: VTX_CLI_HELP, stderr: "" };
+    }
     const parsed = parseFlags(argv2);
     const [group, command, ...args] = parsed.rest;
     const config2 = resolveAgentCliConfig(env);
@@ -48550,7 +48923,7 @@ async function runVtxCli(argv2, env = process.env) {
 ` };
   }
 }
-var WRITABLE_SECRET_FIELDS, delay;
+var VTX_CLI_HELP, WRITABLE_SECRET_FIELDS, delay;
 var init_vtx = __esm({
   "lib/agent-cli/vtx.ts"() {
     "use strict";
@@ -48559,6 +48932,24 @@ var init_vtx = __esm({
     init_headless_runtime();
     init_types();
     init_hyperliquid_market_symbol();
+    VTX_CLI_HELP = `Usage: vtx [--json] [--profile <id>] <command>
+
+Common commands:
+  auth login                 Authorize the normal VTX CLI
+  auth whoami                Show the current VTX CLI identity
+  profiles list              List accessible profiles
+  bots status                Read the selected profile's Trader state
+  bots start                 Start the normal VTX Trader
+  bots stop                  Stop the normal VTX Trader
+  runtime events             Read recent runtime events and errors
+  inference-host --help      Set up an automated or agent-driven inference host
+
+Global options:
+  --json                     Emit machine-readable JSON
+  --profile <id>             Select one VTX profile
+  --version, -v              Show the installed CLI version
+  --help, -h                 Show this help
+`;
     WRITABLE_SECRET_FIELDS = /* @__PURE__ */ new Set([
       "hyperliquid_signing_key",
       "local_ai_api_key",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtxmacro/cli",
-  "version": "2026.8.12",
+  "version": "2026.8.13",
   "description": "VTX Macro CLI, MCP server, and foreground subscription inference host.",
   "type": "module",
   "license": "UNLICENSED",