@vtxmacro/cli 2026.8.11 → 2026.8.12

package/README.md

@@ -77,6 +77,7 @@ vtx inference-host agent-connect \
   --model-label "<display label>" \
   --effort <reasoning-effort> \
   --json
+vtx inference-host agent-run
 vtx inference-host agent-next --wait-seconds 50 --json
 ```
 
@@ -99,7 +100,9 @@ Use `not_dispatched` only when no harness inference began,
 `outcome_unknown` when dispatch itself cannot be confirmed. Pipe exactly one
 object to `vtx inference-host agent-fail --json`.
 
-Keep calling `agent-next` while the host should remain available. This same loop
+Keep `agent-run` open in a separate terminal and keep calling `agent-next`
+while the host should remain available. The independent keeper preserves
+truthful liveness while the harness reasons. This same loop
 supports Main, Review, and Screener; Provider response and Decision candidate;
 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
@@ -107,8 +110,10 @@ to another model when the agent host is unavailable.
 
 ## Remove
 
-First revoke the VTX inference grant, then uninstall the package. Automated
-Codex users should also remove the dedicated Codex login:
+First stop the foreground run or agent-run process, revoke the VTX inference
+grant, then uninstall the package. Cleanup refuses while a foreground host
+process still owns the host. Automated Codex users should also remove the
+dedicated Codex login:
 
 ```bash
 vtx inference-host revoke

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.11",
+      package_version: "2026.8.12",
       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, 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, 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";
@@ -15051,6 +15051,12 @@ var init_external_inference_contract = __esm({
       host_id: identifierSchema,
       requested_at: timestampSchema
     });
+    agentHeartbeatRequestSchema = external_exports.strictObject({
+      operation_id: operationIdentifierSchema,
+      host_id: identifierSchema,
+      attempt_id: identifierSchema.nullable().optional(),
+      requested_at: timestampSchema
+    });
     emptyAgentNextResultSchema = external_exports.strictObject({
       claim_state: external_exports.literal("empty"),
       retry_after_ms: nonNegativeSafeIntegerSchema
@@ -16979,7 +16985,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, 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, 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";
@@ -16999,6 +17005,7 @@ var init_mcp_client = __esm({
     EXTERNAL_INFERENCE_OPERATIONAL_TOOLS = [
       ...EXTERNAL_INFERENCE_AUTOMATED_HOST_TOOLS,
       "inference.agent.connect",
+      "inference.agent.heartbeat",
       "inference.agent.next",
       "inference.agent.complete",
       "inference.agent.fail"
@@ -17030,6 +17037,20 @@ var init_mcp_client = __esm({
       reasoning_effort: safeCodeSchema2,
       replayed: external_exports.boolean()
     });
+    agentHeartbeatResultSchema = external_exports.strictObject({
+      host: hostStatusReadSchema,
+      active_attempts: external_exports.number().int().min(0).max(1),
+      available_slots: external_exports.number().int().min(0).max(1),
+      replayed: external_exports.boolean()
+    }).superRefine((value, context) => {
+      if (value.active_attempts + value.available_slots !== 1) {
+        context.addIssue({
+          code: "custom",
+          message: "Agent heartbeat capacity must describe exactly one slot.",
+          path: ["available_slots"]
+        });
+      }
+    });
     jobCompletionResultSchema = external_exports.strictObject({
       job_id: identifierSchema2,
       attempt_id: identifierSchema2,
@@ -17099,6 +17120,10 @@ var init_mcp_client = __esm({
         arguments: agentConnectRequestSchema,
         result: agentConnectResultSchema
       },
+      "inference.agent.heartbeat": {
+        arguments: agentHeartbeatRequestSchema,
+        result: agentHeartbeatResultSchema
+      },
       "inference.agent.next": {
         arguments: agentNextRequestSchema,
         result: agentNextResultSchema
@@ -17225,6 +17250,12 @@ var init_mcp_client = __esm({
         if (!host || host.host_id !== request.host_id || host.adapter !== request.adapter || result2.model_id !== request.model_id || result2.reasoning_effort !== request.reasoning_effort) invalidBoundResult(name);
         return;
       }
+      if (name === "inference.agent.heartbeat") {
+        const host = result2.host;
+        const expectedActive = request.attempt_id == null ? 0 : 1;
+        if (!host || host.host_id !== request.host_id || host.status !== "online" || result2.active_attempts !== expectedActive || result2.available_slots !== 1 - expectedActive) invalidBoundResult(name);
+        return;
+      }
       if (name === "inference.agent.next") {
         if (result2.claim_state === "claimed" && !result2.job_id) invalidBoundResult(name);
         return;
@@ -17343,7 +17374,7 @@ var init_mcp_client = __esm({
         }).passthrough().parse(rawResult);
         if (callResult.isError === true) {
           const errorText = (callResult.content ?? []).filter((block) => block.type === "text").map((block) => block.text ?? "").join("\n");
-          const definitivelyNotApplied = (name === "inference.host.register" || name === "inference.host.advertise") && errorText.includes("Advertisement is already expired.") || name === "inference.agent.next" && (errorText.includes("Advertisement time is outside the allowed clock skew.") || errorText.includes("Advertisement is already expired.") || errorText.includes("Heartbeat time is outside the allowed clock skew."));
+          const definitivelyNotApplied = (name === "inference.host.register" || name === "inference.host.advertise") && errorText.includes("Advertisement is already expired.") || (name === "inference.agent.next" || name === "inference.agent.heartbeat") && (errorText.includes("Advertisement time is outside the allowed clock skew.") || errorText.includes("Advertisement is already expired.") || errorText.includes("Heartbeat time is outside the allowed clock skew."));
           throw new ExternalInferenceMcpError(
             "tool_rejected",
             `Insights MCP rejected ${name}.`,
@@ -28794,6 +28825,9 @@ async function runInferenceHostCli(argv2, env = process.env, dependencies = {})
         async () => await agentConnect(config2, parsed, dependencies, warnings)
       );
     }
+    if (parsed.command === "agent-run") {
+      return await agentRun(config2, parsed, dependencies, warnings);
+    }
     if (parsed.command === "agent-next") {
       return await withAgentCommandLock(
         config2,
@@ -28828,7 +28862,7 @@ async function runInferenceHostCli(argv2, env = process.env, dependencies = {})
       return await cleanupLogin(config2, parsed, dependencies, warnings, true);
     }
     throw new Error(
-      "Usage: vtx inference-host <login|codex-login|run|agent-connect|agent-next|agent-complete|agent-fail|status|doctor|logout|codex-logout|revoke> [--json]"
+      "Usage: vtx inference-host <login|codex-login|run|agent-connect|agent-run|agent-next|agent-complete|agent-fail|status|doctor|logout|codex-logout|revoke> [--json]"
     );
   } catch (error48) {
     return {
@@ -28839,7 +28873,7 @@ async function runInferenceHostCli(argv2, env = process.env, dependencies = {})
     };
   }
 }
-var INFERENCE_HOST_CLI_VERSION, runtimeReceiptPath, codexRecoveryPath, codexGuardianReceiptRoot, revocationCheckpointPath, 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, 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, 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";
@@ -28855,11 +28889,20 @@ var init_cli = __esm({
     init_crypto();
     init_oauth();
     init_runner();
+    init_mcp_client();
     INFERENCE_HOST_CLI_VERSION = agent_cli_release_default.package_version;
     runtimeReceiptPath = (config2) => `${config2.statePath}.runtime.json`;
     codexRecoveryPath = (config2) => `${config2.statePath}.codex-recovery.json`;
     codexGuardianReceiptRoot = (config2) => `${config2.statePath}.codex-processes`;
     revocationCheckpointPath = (config2) => `${config2.statePath}.revoke.json`;
+    foregroundHostLockPath = (config2) => `${config2.processLockPath}.foreground`;
+    AGENT_HEARTBEAT_INTERVAL_MS = 3e3;
+    AGENT_HEARTBEAT_MAX_RETRY_DELAY_MS = 9e3;
+    retryableAgentHeartbeatError = (error48) => {
+      if (!(error48 instanceof ExternalInferenceMcpError)) return false;
+      if (error48.code === "network_error" || error48.code === "request_timeout") return true;
+      return error48.code === "transport_rejected" && /HTTP (?:408|425|429|5\d\d)\b/u.test(error48.message);
+    };
     assertRevocationCheckpoint = (value) => {
       if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new Error("Inference host revocation checkpoint is invalid.");
@@ -29489,7 +29532,18 @@ Waiting for approval...
     };
     cleanupLogin = async (config2, parsed, dependencies, warnings, revoke) => {
       const lock2 = await acquireInferenceHostProcessLock(config2.processLockPath);
+      let keeperLock = null;
       try {
+        try {
+          keeperLock = await acquireInferenceHostProcessLock(foregroundHostLockPath(config2));
+        } catch (error48) {
+          if (error48 instanceof Error && error48.message.includes("Another inference host process already owns")) {
+            throw new Error(
+              "Stop vtx inference-host agent-run before logging out or revoking this host."
+            );
+          }
+          throw error48;
+        }
         if (!revoke) {
           await assertLocalRuntimeArtifactsMayBeDiscarded(config2);
         }
@@ -29592,13 +29646,16 @@ Waiting for approval...
 ` : ""
         };
       } finally {
+        await keeperLock?.release();
         await lock2.release();
       }
     };
     runHost = async (config2, parsed, env, dependencies, warnings) => {
       const cancellation = lifecycleCancellation(dependencies);
+      let foregroundLock = null;
       let processLock = null;
       try {
+        foregroundLock = await acquireInferenceHostProcessLock(foregroundHostLockPath(config2));
         processLock = await acquireInferenceHostProcessLock(config2.processLockPath);
         cancellation.signal.throwIfAborted();
         if (await readRevocationCheckpoint(config2)) {
@@ -29649,6 +29706,7 @@ Waiting for approval...
         }
       } finally {
         await processLock?.release();
+        await foregroundLock?.release();
         cancellation.unregister();
       }
     };
@@ -29728,12 +29786,130 @@ Waiting for approval...
           lanes: ["main", "review", "screener"],
           response_modes: ["provider_response", "decision_candidate"],
           execution_modes: ["client", "server"],
-          next_command: "vtx inference-host agent-next --wait-seconds 50 --json"
+          next_command: "vtx inference-host agent-next --wait-seconds 50 --json",
+          keeper_command: "vtx inference-host agent-run"
         }, parsed.json),
         stderr: warnings.length > 0 ? `${warnings.join("\n")}
 ` : ""
       };
     };
+    agentRun = async (config2, parsed, dependencies, warnings) => {
+      const cancellation = lifecycleCancellation(dependencies);
+      let keeperLock = null;
+      let heartbeatCount = 0;
+      try {
+        keeperLock = await acquireInferenceHostProcessLock(foregroundHostLockPath(config2));
+        const store = configuredCredentialStore(config2, dependencies, (message) => {
+          warnings.push(message);
+        });
+        const session = await (dependencies.createAgentSession ?? createInferenceAgentMcpSession)({
+          config: config2,
+          credentialStore: store,
+          clientVersion: INFERENCE_HOST_CLI_VERSION,
+          signal: cancellation.signal
+        });
+        const emitStdout = dependencies.emitStdout ?? ((text) => {
+          process.stdout.write(text);
+        });
+        const emitStderr = dependencies.emitStderr ?? ((text) => {
+          process.stderr.write(text);
+        });
+        let consecutiveHeartbeatFailures = 0;
+        let retryDelayMs = AGENT_HEARTBEAT_INTERVAL_MS;
+        let pendingHeartbeatRequest = null;
+        emitStdout(parsed.json ? `${JSON.stringify({ status: "running", host_id: session.localState.host_id })}
+` : "Agent-driven inference host keeper is running.\n");
+        while (!cancellation.signal.aborted) {
+          let commandLock = null;
+          try {
+            commandLock = await acquireInferenceHostProcessLock(config2.processLockPath);
+          } catch (error48) {
+            if (!(error48 instanceof Error) || !error48.message.includes("Another inference host process already owns")) {
+              throw error48;
+            }
+          }
+          if (commandLock) {
+            let heartbeatSuppressed = false;
+            try {
+              const active = await readInferenceAgentAttemptState(config2.statePath);
+              const pendingNext = await readInferenceAgentNextState(config2.statePath);
+              heartbeatSuppressed = Boolean(pendingNext && !active);
+              if (heartbeatSuppressed) pendingHeartbeatRequest = null;
+              if (!heartbeatSuppressed) {
+                if (active && active.host_id !== session.localState.host_id) {
+                  throw new Error("Active agent-driven attempt belongs to another inference host.");
+                }
+                const activeAttemptId = active?.attempt_id ?? null;
+                if (pendingHeartbeatRequest?.attempt_id !== activeAttemptId) {
+                  pendingHeartbeatRequest = null;
+                }
+                const heartbeatRequest = pendingHeartbeatRequest ?? {
+                  operation_id: agentOperationId("agent-heartbeat"),
+                  host_id: session.localState.host_id,
+                  attempt_id: activeAttemptId,
+                  requested_at: (dependencies.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+                };
+                try {
+                  await session.client.callTool(
+                    "inference.agent.heartbeat",
+                    heartbeatRequest,
+                    { signal: cancellation.signal }
+                  );
+                  heartbeatCount += 1;
+                  pendingHeartbeatRequest = null;
+                  consecutiveHeartbeatFailures = 0;
+                  retryDelayMs = AGENT_HEARTBEAT_INTERVAL_MS;
+                } catch (error48) {
+                  if (cancellation.signal.aborted) break;
+                  if (error48 instanceof ExternalInferenceMcpError && error48.definitivelyNotApplied) {
+                    pendingHeartbeatRequest = null;
+                    consecutiveHeartbeatFailures = 0;
+                    retryDelayMs = AGENT_HEARTBEAT_INTERVAL_MS;
+                    emitStderr(parsed.json ? `${JSON.stringify({
+                      status: "heartbeat_retry",
+                      retry_after_ms: retryDelayMs
+                    })}
+` : `Agent-driven inference heartbeat was not applied; retrying in ${retryDelayMs}ms.
+`);
+                  } else {
+                    if (!retryableAgentHeartbeatError(error48)) throw error48;
+                    pendingHeartbeatRequest = heartbeatRequest;
+                    consecutiveHeartbeatFailures += 1;
+                    retryDelayMs = Math.min(
+                      AGENT_HEARTBEAT_INTERVAL_MS * 2 ** Math.max(0, consecutiveHeartbeatFailures - 1),
+                      AGENT_HEARTBEAT_MAX_RETRY_DELAY_MS
+                    );
+                    const message = `Agent-driven inference heartbeat was temporarily unavailable; retrying in ${retryDelayMs}ms.
+`;
+                    emitStderr(parsed.json ? `${JSON.stringify({
+                      status: "heartbeat_retry",
+                      retry_after_ms: retryDelayMs
+                    })}
+` : message);
+                  }
+                }
+              }
+            } finally {
+              await commandLock.release();
+            }
+            if (parsed.once && (heartbeatCount > 0 || heartbeatSuppressed)) break;
+          }
+          if (parsed.once && !commandLock) break;
+          await (dependencies.sleep ?? (async (milliseconds) => {
+            await new Promise((resolve5) => setTimeout(resolve5, milliseconds));
+          }))(retryDelayMs);
+        }
+        return {
+          exitCode: 0,
+          stdout: render({ status: "stopped", heartbeats: heartbeatCount }, parsed.json),
+          stderr: warnings.length > 0 ? `${warnings.join("\n")}
+` : ""
+        };
+      } finally {
+        await keeperLock?.release();
+        cancellation.unregister();
+      }
+    };
     agentNext = async (config2, parsed, dependencies, warnings) => {
       const active = await readInferenceAgentAttemptState(config2.statePath);
       const recoveredNext = await readInferenceAgentNextState(config2.statePath);

package/package.json

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