@vtxmacro/cli 2026.8.39 → 2026.8.40

package/README.md

@@ -15,6 +15,11 @@ The VTX host verifies that native runtime's version and digest before use; it
 does not borrow a Codex binary from PATH or an editor extension.
 For Windows-login auto-start, install and configure the CLI from native Windows;
 a CLI installed only inside WSL cannot start the WSL virtual machine at login.
+An npm update does not replace code already loaded by a running durable service.
+After updating, check `vtx inference-host service status --json`. If the service
+was already desired-running, run `vtx inference-host service stop` followed by
+`vtx inference-host service start`, then verify status and logs. Leave an
+intentionally stopped service stopped until you want to run it.
 
 ## Configure
 
@@ -86,6 +91,21 @@ distinct. Use `service uninstall --instance <name>` to remove one worker;
 unqualified `service uninstall` removes the whole supervisor. The legacy
 unqualified host commands continue to target `default`.
 
+On native Windows, if service status or logs show that guarded recovery is
+blocking one installed subscription, recover that exact instance without rebooting:
+
+```bash
+vtx inference-host service recover --instance <name> --force-recovery --json
+```
+
+Recovery is intentionally noninteractive and requires both `--instance` and
+`--force-recovery`; `--json` changes only the output format. The shared
+supervisor briefly quiesces so every installed worker can stop cooperatively,
+then VTX restores its previous desired state and the same peer subscriptions.
+The command never kills an arbitrary process, logs either account out, changes
+VTX profile settings, or controls a Trader. If any package-owned VTX automation
+is still live, recovery fails closed and preserves its evidence.
+
 For each VTX profile and lane, **Subscription #1** is tried first and later
 compatible subscriptions follow in the saved Account cascade order.
 Quota/credits exhaustion, unusable authentication, and exhausted recoverable

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.39",
+      package_version: "2026.8.40",
       codex_package_name: "@openai/codex",
       codex_version: "0.147.0",
       platforms: {
@@ -21473,10 +21473,10 @@ import {
   realpath as realpath3,
   rm as rm3
 } from "node:fs/promises";
-import { randomBytes as randomBytes3 } from "node:crypto";
+import { createHash as createHash4, randomBytes as randomBytes3 } from "node:crypto";
 import { tmpdir as tmpdir2 } from "node:os";
 import { isAbsolute as isAbsolute3, join as join4, relative as relative2, resolve as resolve3, sep as sep2 } from "node:path";
-var MAX_PROMPT_BYTES2, CODEX_MODEL_NAME_PATTERN, CODEX_REASONING_EFFORT_PATTERN, tokenUsageReceiptSchema, turnResultReceiptSchema, terminalReceiptSchema, recoveryCheckpointSchema, recoveryFileSchema, FileCodexAttemptRecoveryStore, utf8Bytes, assertAttemptActive, tomlString, permissionConfig, ensureDedicatedCodexHome, createIsolatedCodexAttemptResources, createIsolatedCodexHostResources, validateAttemptInput, isStrictDescendant, assertRecoveryResourceScope, removeRecoveredThread, confirmGuardianTerminatedForRecovery, reconcileCodexAttemptRecovery, CodexSubscriptionAdapter;
+var MAX_PROMPT_BYTES2, CODEX_MODEL_NAME_PATTERN, CODEX_REASONING_EFFORT_PATTERN, codexRecoveryCheckpointProcessFingerprint, proveCodexSameBootQuiescence, tokenUsageReceiptSchema, turnResultReceiptSchema, terminalReceiptSchema, recoveryCheckpointSchema, recoveryFileSchema, FileCodexAttemptRecoveryStore, utf8Bytes, assertAttemptActive, tomlString, permissionConfig, ensureDedicatedCodexHome, createIsolatedCodexAttemptResources, createIsolatedCodexHostResources, validateAttemptInput, isStrictDescendant, assertRecoveryResourceScope, removeRecoveredThread, confirmGuardianTerminatedForRecovery, reconcileCodexAttemptRecovery, CodexSubscriptionAdapter;
 var init_codex_adapter = __esm({
   "lib/inference-host/codex-adapter.ts"() {
     "use strict";
@@ -21487,6 +21487,34 @@ var init_codex_adapter = __esm({
     MAX_PROMPT_BYTES2 = 3e5;
     CODEX_MODEL_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u;
     CODEX_REASONING_EFFORT_PATTERN = /^[a-z][a-z0-9_-]{0,31}$/u;
+    codexRecoveryCheckpointProcessFingerprint = (checkpoint) => createHash4("sha256").update(JSON.stringify({
+      attemptId: checkpoint.attemptId,
+      processToken: checkpoint.processToken,
+      processReceiptPath: checkpoint.processReceiptPath,
+      processState: checkpoint.processState,
+      bootIdentity: checkpoint.bootIdentity ?? null,
+      cleanupConfirmed: checkpoint.cleanupConfirmed
+    })).digest("hex");
+    proveCodexSameBootQuiescence = async (options) => {
+      const readBootIdentity = options.readBootIdentity ?? readInferenceSystemBootIdentity;
+      const bootIdentityBefore = await readBootIdentity();
+      await options.confirmNoManagedCodexProcesses();
+      const bootIdentityAfter = await readBootIdentity();
+      if (bootIdentityAfter !== bootIdentityBefore) {
+        throw new Error("System boot identity changed during Codex recovery process inspection.");
+      }
+      return {
+        schemaVersion: "vtx_codex_same_boot_quiescence_v1",
+        bootIdentity: bootIdentityAfter,
+        observedAtMs: (options.now ?? Date.now)(),
+        checkpointFingerprints: Object.fromEntries(
+          Object.entries(options.attempts).map(([attemptId, checkpoint]) => [
+            attemptId,
+            codexRecoveryCheckpointProcessFingerprint(checkpoint)
+          ])
+        )
+      };
+    };
     tokenUsageReceiptSchema = external_exports.strictObject({
       inputTokens: external_exports.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
       cachedInputTokens: external_exports.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
@@ -21959,11 +21987,20 @@ var init_codex_adapter = __esm({
             throw new Error("Codex cross-boot recovery receipt ownership is unconfirmed.");
           }
         } else {
-          await confirmGuardianTerminatedForRecovery(
-            checkpoint,
-            guardian,
-            options.deadlineMs ?? 5e3
-          );
+          const receipt = await readCodexGuardianReceipt(guardian.receiptPath);
+          if (receipt === null && options.sameBootQuiescenceProof) {
+            const proof = options.sameBootQuiescenceProof;
+            const expectedFingerprint = proof.checkpointFingerprints[checkpoint.attemptId];
+            if (proof.schemaVersion !== "vtx_codex_same_boot_quiescence_v1" || proof.bootIdentity !== currentBootIdentity || checkpoint.bootIdentity !== currentBootIdentity || !Number.isFinite(proof.observedAtMs) || proof.observedAtMs > Date.now() + 1e3 || Date.now() - proof.observedAtMs > 3e4 || expectedFingerprint !== codexRecoveryCheckpointProcessFingerprint(checkpoint)) {
+              throw new Error("Codex same-boot recovery process fence is invalid or stale.");
+            }
+          } else {
+            await confirmGuardianTerminatedForRecovery(
+              checkpoint,
+              guardian,
+              options.deadlineMs ?? 5e3
+            );
+          }
         }
         assertRecoveryResourceScope(checkpoint);
         await removeRecoveredThread(checkpoint, options.codexHome);
@@ -22607,11 +22644,147 @@ var init_codex_adapter = __esm({
   }
 });
 
+// lib/inference-host/codex-recovery-process.ts
+import { spawn as spawn5 } from "node:child_process";
+var normalizedWindowsPath, classifyCodexRecoveryProcesses, WINDOWS_PROCESS_QUERY, queryWindowsProcesses, confirmNoVtxManagedCodexProcesses;
+var init_codex_recovery_process = __esm({
+  "lib/inference-host/codex-recovery-process.ts"() {
+    "use strict";
+    normalizedWindowsPath = (value) => value.replaceAll("\\", "/").replaceAll(/\/+$/gu, "").toLowerCase();
+    classifyCodexRecoveryProcesses = (processes, pinnedBinaryPath) => {
+      const pinned = normalizedWindowsPath(pinnedBinaryPath);
+      let managedProcessCount = 0;
+      let ambiguousProcessCount = 0;
+      for (const process3 of processes) {
+        const name = process3.name.trim().toLowerCase();
+        if (name === "codex.exe") {
+          if (!process3.executable_path || !process3.command_line || !process3.creation_date) {
+            ambiguousProcessCount += 1;
+            continue;
+          }
+          const executable = normalizedWindowsPath(process3.executable_path);
+          const packageOwned = executable === pinned || executable.includes("/node_modules/@vtxmacro/") && executable.includes("/node_modules/@openai/codex-win32-x64/") || executable.includes("/node_modules/@vtxmacro/.cli-") && executable.includes("/node_modules/@openai/codex-win32-x64/");
+          if (packageOwned) managedProcessCount += 1;
+          continue;
+        }
+        if (name !== "node.exe") continue;
+        if (!process3.executable_path || !process3.command_line || !process3.creation_date) {
+          ambiguousProcessCount += 1;
+          continue;
+        }
+        if (process3.command_line.includes("--input-type=module") && process3.command_line.includes("vtx_codex_guardian_v1") && process3.command_line.includes("processToken") && process3.command_line.includes("receiptPath")) {
+          managedProcessCount += 1;
+        }
+      }
+      return {
+        managed_process_count: managedProcessCount,
+        ambiguous_process_count: ambiguousProcessCount
+      };
+    };
+    WINDOWS_PROCESS_QUERY = String.raw`
+$ErrorActionPreference = 'Stop'
+$items = @(Get-CimInstance Win32_Process | Where-Object { $_.Name -in @('node.exe', 'codex.exe') } | ForEach-Object {
+  [ordered]@{
+    process_id = [int]$_.ProcessId
+    name = [string]$_.Name
+    executable_path = if ($null -eq $_.ExecutablePath) { $null } else { [string]$_.ExecutablePath }
+    command_line = if ($null -eq $_.CommandLine) { $null } else { [string]$_.CommandLine }
+    creation_date = if ($null -eq $_.CreationDate) { $null } else { [string]$_.CreationDate }
+  }
+})
+[Console]::Out.Write(($items | ConvertTo-Json -Depth 3 -Compress))
+`;
+    queryWindowsProcesses = async () => {
+      const args = [
+        "-NoLogo",
+        "-NoProfile",
+        "-NonInteractive",
+        "-EncodedCommand",
+        Buffer.from(WINDOWS_PROCESS_QUERY, "utf16le").toString("base64")
+      ];
+      const result2 = await new Promise(
+        (resolvePromise, reject) => {
+          const child = spawn5("powershell.exe", args, {
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"]
+          });
+          let stdout = "";
+          let stderr = "";
+          child.stdout.on("data", (chunk) => {
+            stdout = `${stdout}${chunk.toString("utf8")}`.slice(-4e6);
+          });
+          child.stderr.on("data", (chunk) => {
+            stderr = `${stderr}${chunk.toString("utf8")}`.slice(-4096);
+          });
+          child.once("error", reject);
+          child.once("close", (code) => {
+            if (code !== 0) {
+              reject(new Error("Windows process ownership inventory failed."));
+              return;
+            }
+            resolvePromise({ exitCode: code ?? 1, stdout });
+          });
+        }
+      );
+      if (result2.exitCode !== 0) throw new Error("Windows process ownership inventory failed.");
+      let parsed;
+      try {
+        parsed = result2.stdout.trim() ? JSON.parse(result2.stdout) : [];
+      } catch {
+        throw new Error("Windows process ownership inventory was invalid.");
+      }
+      const entries = Array.isArray(parsed) ? parsed : [parsed];
+      return entries.map((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+          throw new Error("Windows process ownership inventory was invalid.");
+        }
+        const record2 = entry;
+        if (!Number.isSafeInteger(record2.process_id) || Number(record2.process_id) < 1 || typeof record2.name !== "string" || record2.executable_path !== null && typeof record2.executable_path !== "string" || record2.command_line !== null && typeof record2.command_line !== "string" || record2.creation_date !== null && typeof record2.creation_date !== "string") {
+          throw new Error("Windows process ownership inventory was invalid.");
+        }
+        return {
+          process_id: Number(record2.process_id),
+          name: record2.name,
+          executable_path: record2.executable_path,
+          command_line: record2.command_line,
+          creation_date: record2.creation_date
+        };
+      });
+    };
+    confirmNoVtxManagedCodexProcesses = async (options) => {
+      if ((options.platform ?? process.platform) !== "win32") {
+        throw new Error("Same-boot service recovery is currently supported only on Windows.");
+      }
+      const queryProcesses = options.queryProcesses ?? queryWindowsProcesses;
+      const sleep4 = options.sleep ?? (async (milliseconds) => {
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds));
+      });
+      for (let observation = 0; observation < 2; observation += 1) {
+        const classification = classifyCodexRecoveryProcesses(
+          await queryProcesses(),
+          options.pinnedBinaryPath
+        );
+        if (classification.ambiguous_process_count > 0) {
+          throw new Error(
+            "Codex process ownership could not be inspected completely; recovery evidence was preserved."
+          );
+        }
+        if (classification.managed_process_count > 0) {
+          throw new Error(
+            "VTX-managed Codex automation is still running; recovery evidence was preserved."
+          );
+        }
+        if (observation === 0) await sleep4(250);
+      }
+    };
+  }
+});
+
 // lib/inference-host/crypto.ts
 import {
   createCipheriv,
   createDecipheriv,
-  createHash as createHash4,
+  createHash as createHash5,
   createPrivateKey,
   createPublicKey,
   diffieHellman,
@@ -22650,7 +22823,7 @@ var init_crypto = __esm({
       const aad = envelopeAadSchema.parse(input);
       return Buffer.from(JSON.stringify(canonicalize(aad)), "utf8");
     };
-    externalInferenceSha256 = (value) => createHash4("sha256").update(value).digest("hex");
+    externalInferenceSha256 = (value) => createHash5("sha256").update(value).digest("hex");
     decodeCanonicalBase64Url = (value, fieldName, expectedBytes) => {
       if (!/^[A-Za-z0-9_-]+$/u.test(value)) {
         throw new ExternalInferenceEnvelopeError("invalid_encoding", `${fieldName} is invalid.`);
@@ -22749,7 +22922,7 @@ var init_crypto = __esm({
       return Buffer.from(hkdfSync(
         "sha256",
         root,
-        createHash4("sha256").update(aadBytes).digest(),
+        createHash5("sha256").update(aadBytes).digest(),
         info,
         32
       ));
@@ -29163,7 +29336,7 @@ var require_ajv = __commonJS({
 });
 
 // lib/inference-host/runner.ts
-import { createHash as createHash5 } from "node:crypto";
+import { createHash as createHash6 } from "node:crypto";
 function createDefaultInferenceHostRunnerDependencies(options) {
   const fetchImpl = options.fetchImpl ?? fetch;
   return {
@@ -29471,7 +29644,7 @@ var init_runner = __esm({
         attempts
       };
     };
-    sha256 = (value) => createHash5("sha256").update(value, "utf8").digest("hex");
+    sha256 = (value) => createHash6("sha256").update(value, "utf8").digest("hex");
     stableOperationId = (kind, parts) => `${kind}_${sha256(JSON.stringify(parts)).slice(0, 48)}`;
     buildAttemptStartRequest = (claim, attemptId, startedAt) => attemptStartRequestSchema.parse({
       schema_version: "external_inference_attempt_start_v1",
@@ -31110,7 +31283,7 @@ var init_runner = __esm({
 });
 
 // lib/inference-host/service.ts
-import { spawn as spawn5 } from "node:child_process";
+import { spawn as spawn6 } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { createWriteStream, readFileSync } from "node:fs";
 import { access as access3, chmod as chmod3, mkdir as mkdir3, readFile as readFile5, rm as rm4, writeFile as writeFile2 } from "node:fs/promises";
@@ -31156,7 +31329,7 @@ var init_service = __esm({
     plistEscape = xmlEscape;
     systemdQuote = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%")}"`;
     defaultRunCommand = async (command, args) => await new Promise((resolvePromise) => {
-      const child = spawn5(command, [...args], {
+      const child = spawn6(command, [...args], {
         windowsHide: true,
         stdio: ["ignore", "pipe", "pipe"]
       });
@@ -31629,8 +31802,10 @@ WantedBy=default.target
         }
         throw new Error("Background service did not reach an active state within 10 seconds.");
       }
-      async restoreRunningSupervisor(manifest) {
-        const restoredManifest = assertManifest({
+      async restoreRunningSupervisor(manifest, preserveGeneration = false, targetInstanceName) {
+        const previousRuntime = await readRuntimeAcrossAtomicReplacement(this.runtimePath()).catch(() => null);
+        const previousRuntimeUpdatedAt = previousRuntime?.manifest_generation === manifest.generation ? Date.parse(previousRuntime.updated_at) : Number.NaN;
+        const restoredManifest = preserveGeneration ? manifest : assertManifest({
           ...manifest,
           generation: randomUUID(),
           installed_at: this.now().toISOString()
@@ -31658,10 +31833,15 @@ ${result2.stderr}`)) {
         }
         await this.waitForManagerActive();
         if (!this.confirmInitialReadiness) return await this.status();
-        const runtime = await this.waitForManifestApplied(restoredManifest);
+        const runtime = await this.waitForManifestApplied(
+          restoredManifest,
+          targetInstanceName,
+          this.reconcileWaitAttempts,
+          Number.isFinite(previousRuntimeUpdatedAt) ? previousRuntimeUpdatedAt : void 0
+        );
         return await this.status(runtime);
       }
-      async waitForManifestApplied(manifest, targetInstanceName, maxAttempts = this.reconcileWaitAttempts) {
+      async waitForManifestApplied(manifest, targetInstanceName, maxAttempts = this.reconcileWaitAttempts, minimumRuntimeUpdatedAtExclusive) {
         let consecutiveReadyObservations = 0;
         for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
           let runtime = null;
@@ -31672,7 +31852,9 @@ ${result2.stderr}`)) {
               throw error48;
             }
           }
-          if (runtime?.manifest_generation === manifest.generation) {
+          const runtimeUpdatedAt = runtime ? Date.parse(runtime.updated_at) : Number.NaN;
+          const runtimeIsFresh = minimumRuntimeUpdatedAtExclusive === void 0 || Number.isFinite(runtimeUpdatedAt) && runtimeUpdatedAt > minimumRuntimeUpdatedAtExclusive;
+          if (runtime?.manifest_generation === manifest.generation && runtimeIsFresh) {
             const configuredNames = manifest.workers.map((worker) => worker.instance_name).sort();
             const runtimeNames = runtime.workers.map((worker) => worker.instance_name).sort();
             const exactWorkerSet = JSON.stringify(configuredNames) === JSON.stringify(runtimeNames);
@@ -31934,7 +32116,71 @@ ${result2.stderr}`)) {
       async stop() {
         return await this.withControlLock(async () => await this.stopUnlocked());
       }
-      async stopUnlocked() {
+      /**
+       * Quiesce the complete installed worker boundary while one exact instance's
+       * durable Codex recovery evidence is reconciled. The service process lock is
+       * held for the callback, so neither the manager nor a manual run-internal can
+       * recreate workers during the same-boot process inspection.
+       */
+      async recoverInstance(instanceName, operation, options = {}) {
+        return await this.withControlLock(async () => {
+          const manifest = await readInferenceHostServiceManifest(this.manifestPath());
+          if (!manifest) throw new Error("Inference-host service is not installed.");
+          if (!manifest.workers.some((worker) => worker.instance_name === instanceName)) {
+            throw new Error(`Inference-host instance ${instanceName} is not installed.`);
+          }
+          if (options.expectedManifestGeneration && options.expectedManifestGeneration !== manifest.generation) {
+            throw new Error("Inference-host service manifest changed during recovery.");
+          }
+          const recordedDesiredRunning = await readInferenceHostServiceDesired(this.desiredPath());
+          const desiredRunning = options.restoreDesiredRunning ?? recordedDesiredRunning;
+          const context = { manifest, desiredRunning };
+          await options.prepare?.(context);
+          const before = await this.status();
+          if (recordedDesiredRunning || before.manager_active) {
+            await this.stopUnlocked(true);
+          } else {
+            await writeDesired(this.desiredPath(), false, this.now());
+          }
+          let serviceFence = null;
+          let result2;
+          let operationError = null;
+          try {
+            serviceFence = await this.acquireProcessLock(
+              `${this.config.supervisorProcessLockPath}.service`
+            );
+            const stopped = await this.status();
+            if (stopped.manager_active) {
+              throw new Error("Background service manager became active during recovery quiescence.");
+            }
+            result2 = await operation(context);
+          } catch (error48) {
+            operationError = error48;
+          } finally {
+            await serviceFence?.release().catch((error48) => {
+              operationError = operationError ?? error48;
+            });
+          }
+          let restoredStatus;
+          try {
+            restoredStatus = desiredRunning ? await this.restoreRunningSupervisor(manifest, true, instanceName) : await this.status();
+          } catch (restoreError) {
+            if (operationError) {
+              throw new Error(
+                "Inference-host recovery failed and the previous supervisor could not be restored.",
+                { cause: new AggregateError([operationError, restoreError]) }
+              );
+            }
+            throw new Error(
+              "Inference-host recovery completed, but the previous supervisor could not be restored.",
+              { cause: restoreError }
+            );
+          }
+          if (operationError) throw operationError;
+          return { result: result2, status: restoredStatus };
+        });
+      }
+      async stopUnlocked(preserveManifestGenerationOnFailure = false) {
         const manifest = await readInferenceHostServiceManifest(this.manifestPath());
         if (!manifest) {
           throw new Error("Inference-host service is not installed.");
@@ -31976,7 +32222,7 @@ ${result2.stderr}`)) {
         } catch (error48) {
           if (!restoreOnFailure) throw error48;
           try {
-            await this.restoreRunningSupervisor(manifest);
+            await this.restoreRunningSupervisor(manifest, preserveManifestGenerationOnFailure);
           } catch (restoreError) {
             throw new Error(
               "Inference-host stop failed and the previous supervisor could not be restored.",
@@ -32143,7 +32389,7 @@ ${result2.stderr}`)) {
 `);
           }
         };
-        const child = spawn5(manifest.executable, args, {
+        const child = spawn6(manifest.executable, args, {
           env: inferenceHostServiceChildEnvironment(worker.runtime_environment),
           windowsHide: true,
           stdio: ["pipe", "pipe", "pipe"]
@@ -32433,8 +32679,8 @@ __export(cli_exports, {
   registerInferenceHostServiceControlInput: () => registerInferenceHostServiceControlInput,
   runInferenceHostCli: () => runInferenceHostCli
 });
-import { randomUUID as randomUUID2 } from "node:crypto";
-import { spawn as spawn6 } from "node:child_process";
+import { createHash as createHash7, randomUUID as randomUUID2 } from "node:crypto";
+import { spawn as spawn7 } from "node:child_process";
 import { lstat as lstat4, realpath as realpath4, rm as rm5 } from "node:fs/promises";
 import { join as join6, resolve as resolve5 } from "node:path";
 async function runInferenceHostCli(argv2, env = process.env, dependencies = {}) {
@@ -32444,6 +32690,21 @@ async function runInferenceHostCli(argv2, env = process.env, dependencies = {})
       return { exitCode: 0, stdout: INFERENCE_HOST_HELP, stderr: "" };
     }
     const parsed = parseInferenceHostArgs(argv2, env);
+    if (parsed.forceRecovery && !(parsed.command === "service" && parsed.serviceAction === "recover")) {
+      throw new Error("--force-recovery is accepted only by service recover.");
+    }
+    if (parsed.command === "service" && parsed.serviceAction === "recover") {
+      if (!parsed.instanceFlagExplicit) {
+        throw new Error(
+          "Service recovery requires an explicit --instance NAME; an environment or default instance is not accepted."
+        );
+      }
+      if (!parsed.forceRecovery) {
+        throw new Error(
+          `Service recovery is disruptive. Rerun with --instance ${parsed.instanceName} --force-recovery after checking service status and logs.`
+        );
+      }
+    }
     const config2 = await resolveInferenceHostCommandConfig(parsed, env, dependencies);
     if (parsed.command === "login") {
       return await login(config2, parsed, env, dependencies, warnings);
@@ -32482,7 +32743,18 @@ async function runInferenceHostCli(argv2, env = process.env, dependencies = {})
       );
     }
     if (parsed.command === "service") {
-      return await serviceCommand(config2, parsed, env, dependencies, warnings);
+      const mutationActions = /* @__PURE__ */ new Set(["install", "start", "stop", "recover", "uninstall"]);
+      if (!parsed.serviceAction || !mutationActions.has(parsed.serviceAction)) {
+        return await serviceCommand(config2, parsed, env, dependencies, warnings);
+      }
+      const recoveryCommandLock = await acquireInferenceHostProcessLock(
+        serviceRecoveryCommandLockPath(config2)
+      );
+      try {
+        return await serviceCommand(config2, parsed, env, dependencies, warnings);
+      } finally {
+        await recoveryCommandLock.release();
+      }
     }
     if (parsed.command === "status") {
       return await localStatus(config2, parsed, dependencies, warnings);
@@ -32511,7 +32783,7 @@ async function runInferenceHostCli(argv2, env = process.env, dependencies = {})
     };
   }
 }
-var INFERENCE_HOST_CLI_VERSION, runtimeReceiptPath, codexRecoveryPath, codexGuardianReceiptRoot, revocationCheckpointPath, foregroundHostLockPath, credentialLifecycleLockPath, AGENT_HEARTBEAT_INTERVAL_MS, AGENT_HEARTBEAT_MAX_RETRY_DELAY_MS, retryableAgentHeartbeatError, assertRevocationCheckpoint, readRevocationCheckpoint, writeRevocationCheckpoint, clearRevocationCheckpoint, render, INFERENCE_HOST_HELP, parseHostConcurrency, parseInferenceHostArgs, defaultOpenBrowser, registerInferenceHostServiceControlInput, defaultRegisterLifecycleSignalHandlers, lifecycleCancellation, configuredCredentialStore, restoreInferenceHostCredentialContext, recoverInferenceHostCredentialContextTransition, accountKeyForState, assertCredentialMatchesState2, revocationCheckpointForCredential, assertRevocationCheckpointMatchesLocalIdentity, fileExistsPrivately, inspectCodexAuthentication, clearLocalRuntimeArtifacts, assertDurableServiceUninstalled, assertLocalRuntimeArtifactsMayBeDiscarded, defaultRunForeground, login, codexLogin, codexLogout, localStatus, doctor, cleanupLogin, runHost, defaultReadStdin, parseAgentStdin, agentOperationId, agentSession, agentConnect, agentRun, agentNext, agentComplete, agentFail, withAgentCommandLock, serviceCommand, hasExplicitCredentialStoreConfiguration, credentialEnvironmentForIdentity, commandRequiresRetainedCredentialStore, commandUsesInstalledServiceCredentials, resolveInferenceHostCommandConfig;
+var INFERENCE_HOST_CLI_VERSION, runtimeReceiptPath, codexRecoveryPath, codexGuardianReceiptRoot, revocationCheckpointPath, foregroundHostLockPath, credentialLifecycleLockPath, serviceRecoveryCommandLockPath, AGENT_HEARTBEAT_INTERVAL_MS, AGENT_HEARTBEAT_MAX_RETRY_DELAY_MS, retryableAgentHeartbeatError, assertRevocationCheckpoint, readRevocationCheckpoint, writeRevocationCheckpoint, clearRevocationCheckpoint, render, INFERENCE_HOST_HELP, parseHostConcurrency, parseInferenceHostArgs, defaultOpenBrowser, registerInferenceHostServiceControlInput, defaultRegisterLifecycleSignalHandlers, lifecycleCancellation, configuredCredentialStore, restoreInferenceHostCredentialContext, recoverInferenceHostCredentialContextTransition, accountKeyForState, assertCredentialMatchesState2, revocationCheckpointForCredential, assertRevocationCheckpointMatchesLocalIdentity, fileExistsPrivately, inspectCodexAuthentication, clearLocalRuntimeArtifacts, assertDurableServiceUninstalled, assertLocalRuntimeArtifactsMayBeDiscarded, defaultRunForeground, login, codexLogin, codexLogout, localStatus, doctor, cleanupLogin, runHost, defaultReadStdin, parseAgentStdin, agentOperationId, agentSession, agentConnect, agentRun, agentNext, agentComplete, agentFail, withAgentCommandLock, recoveryBackupPath, serviceRecoveryTransactionPath, readServiceRecoveryTransaction, assertResumableCodexRecoveryEvidence, recoverInstalledCodexService, serviceCommand, hasExplicitCredentialStoreConfiguration, credentialEnvironmentForIdentity, commandRequiresRetainedCredentialStore, commandUsesInstalledServiceCredentials, resolveInferenceHostCommandConfig;
 var init_cli = __esm({
   "lib/inference-host/cli.ts"() {
     "use strict";
@@ -32520,6 +32792,7 @@ var init_cli = __esm({
     init_agent_client();
     init_agent_state();
     init_codex_adapter();
+    init_codex_recovery_process();
     init_codex_app_server();
     init_codex_binary();
     init_config();
@@ -32536,6 +32809,7 @@ var init_cli = __esm({
     revocationCheckpointPath = (config2) => `${config2.statePath}.revoke.json`;
     foregroundHostLockPath = (config2) => `${config2.processLockPath}.foreground`;
     credentialLifecycleLockPath = (config2) => `${inferenceHostCredentialContextPath(config2)}.lock`;
+    serviceRecoveryCommandLockPath = (config2) => `${config2.supervisorProcessLockPath}.service-recovery-command`;
     AGENT_HEARTBEAT_INTERVAL_MS = 3e3;
     AGENT_HEARTBEAT_MAX_RETRY_DELAY_MS = 9e3;
     retryableAgentHeartbeatError = (error48) => {
@@ -32632,7 +32906,8 @@ Durable service:
   vtx inference-host codex-login --instance codex-2
   vtx inference-host service install --instance codex-2
   vtx inference-host service uninstall --instance codex-2
-  vtx inference-host service <start|stop|status|logs|uninstall>
+  vtx inference-host service recover --instance codex-1 --force-recovery
+  vtx inference-host service <start|stop|status|logs|recover|uninstall>
 `;
     parseHostConcurrency = (raw, label) => {
       const value = Number(raw);
@@ -32648,6 +32923,7 @@ Durable service:
       let maxConcurrency = configuredConcurrency ? parseHostConcurrency(configuredConcurrency, "VTX_INFERENCE_HOST_MAX_CONCURRENCY") : null;
       let instanceName = String(env.VTX_INFERENCE_HOST_INSTANCE || "default").trim();
       let instanceExplicit = Boolean(String(env.VTX_INFERENCE_HOST_INSTANCE || "").trim());
+      let instanceFlagExplicit = false;
       let displayName = String(env.VTX_INFERENCE_HOST_DISPLAY_NAME || "").trim() || "Codex subscription host";
       let displayNameExplicit = Boolean(String(env.VTX_INFERENCE_HOST_DISPLAY_NAME || "").trim());
       let adapter = null;
@@ -32657,6 +32933,7 @@ Durable service:
       let waitSeconds = 50;
       let lines = 100;
       let serviceManifestPath = null;
+      let forceRecovery = false;
       const positionals = [];
       for (let index = 0; index < argv2.length; index += 1) {
         const argument = argv2[index];
@@ -32668,6 +32945,10 @@ Durable service:
           once = true;
           continue;
         }
+        if (argument === "--force-recovery") {
+          forceRecovery = true;
+          continue;
+        }
         if (argument === "--max-concurrency") {
           const raw = argv2[index + 1];
           if (!raw) throw new Error("--max-concurrency requires a value.");
@@ -32706,6 +32987,7 @@ Durable service:
           if (argument === "--instance") {
             instanceName = raw.trim();
             instanceExplicit = true;
+            instanceFlagExplicit = true;
           }
           index += 1;
           continue;
@@ -32736,6 +33018,7 @@ Durable service:
         maxConcurrency,
         instanceName,
         instanceExplicit,
+        instanceFlagExplicit,
         displayName,
         adapter,
         modelId,
@@ -32744,13 +33027,14 @@ Durable service:
         waitSeconds,
         lines,
         serviceAction,
-        serviceManifestPath
+        serviceManifestPath,
+        forceRecovery
       };
     };
     defaultOpenBrowser = (url2) => {
       const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
       const args = process.platform === "win32" ? ["/c", "start", "", url2] : [url2];
-      const child = spawn6(command, args, {
+      const child = spawn7(command, args, {
         detached: true,
         stdio: "ignore",
         windowsHide: true
@@ -32914,10 +33198,14 @@ Durable service:
         codexRecoveryPath(config2),
         "Codex attempt recovery file"
       );
+      const serviceRecoveryPresent = await fileExistsPrivately(
+        `${config2.supervisorStatePath}.service-recovery.json`,
+        "Inference-host service recovery transaction"
+      );
       const revocationCheckpointPresent = await readRevocationCheckpoint(config2) !== null;
       const agentAttemptPresent = await readInferenceAgentAttemptState(config2.statePath) !== null;
       const agentNextRecoveryPresent = await readInferenceAgentNextState(config2.statePath) !== null;
-      if (pendingAttempts > 0 || codexRecoveryPresent || revocationCheckpointPresent || agentAttemptPresent || agentNextRecoveryPresent) {
+      if (pendingAttempts > 0 || codexRecoveryPresent || serviceRecoveryPresent || revocationCheckpointPresent || agentAttemptPresent || agentNextRecoveryPresent) {
         throw new Error(
           "Inference host logout refused because attempt recovery is still pending (Codex, agent-driven, or revocation recovery). Rerun agent-next, complete or fail the active attempt, run the automated host to reconcile it, or resume revoke."
         );
@@ -33232,6 +33520,10 @@ Waiting for approval...
         codexRecoveryPath(config2),
         "Codex attempt recovery file"
       );
+      const serviceRecoveryPresent = await fileExistsPrivately(
+        `${config2.supervisorStatePath}.service-recovery.json`,
+        "Inference-host service recovery transaction"
+      );
       const agentAttempt = await readInferenceAgentAttemptState(config2.statePath);
       const agentNextRecoveryPresent = await readInferenceAgentNextState(config2.statePath) !== null;
       return {
@@ -33260,6 +33552,7 @@ Waiting for approval...
           } : null,
           agent_next_recovery_present: agentNextRecoveryPresent,
           codex_recovery_present: recoveryPresent,
+          service_recovery_present: serviceRecoveryPresent,
           codex_auth: codexAuthentication,
           source: "local_only"
         }, parsed.json),
@@ -34016,10 +34309,292 @@ Waiting for approval...
         await lock2.release();
       }
     };
+    recoveryBackupPath = (config2, transactionId) => `${codexRecoveryPath(config2)}.service-recovery-${transactionId}.backup`;
+    serviceRecoveryTransactionPath = (config2) => `${config2.supervisorStatePath}.service-recovery.json`;
+    readServiceRecoveryTransaction = async (config2) => {
+      const raw = await readInferencePrivateFile(
+        serviceRecoveryTransactionPath(config2),
+        "Inference-host service recovery transaction"
+      );
+      if (raw === null) return null;
+      let value;
+      try {
+        value = JSON.parse(raw);
+      } catch {
+        throw new Error("Inference-host service recovery transaction is not valid JSON.");
+      }
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Inference-host service recovery transaction is invalid.");
+      }
+      const record2 = value;
+      const exactKeys = [
+        "schema_version",
+        "phase",
+        "transaction_id",
+        "instance_name",
+        "manifest_generation",
+        "restore_desired_running",
+        "recovery_backup_path",
+        "recovery_backup_sha256",
+        "cleanup_confirmed_attempt_ids",
+        "started_at"
+      ];
+      if (Object.keys(record2).sort().join("\0") !== exactKeys.sort().join("\0") || record2.schema_version !== "vtx_inference_service_recovery_v1" || record2.phase !== "prepared" && record2.phase !== "reconciled" || typeof record2.transaction_id !== "string" || !/^[0-9a-f-]{36}$/u.test(record2.transaction_id) || typeof record2.instance_name !== "string" || typeof record2.manifest_generation !== "string" || typeof record2.restore_desired_running !== "boolean" || typeof record2.recovery_backup_path !== "string" || typeof record2.recovery_backup_sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(record2.recovery_backup_sha256) || !Array.isArray(record2.cleanup_confirmed_attempt_ids) || record2.cleanup_confirmed_attempt_ids.some(
+        (attemptId) => typeof attemptId !== "string" || attemptId.length < 1 || attemptId.length > 256
+      ) || new Set(record2.cleanup_confirmed_attempt_ids).size !== record2.cleanup_confirmed_attempt_ids.length || [...record2.cleanup_confirmed_attempt_ids].sort().join("\0") !== record2.cleanup_confirmed_attempt_ids.join("\0") || typeof record2.started_at !== "string" || !Number.isFinite(Date.parse(record2.started_at)) || new Date(record2.started_at).toISOString() !== record2.started_at) {
+        throw new Error("Inference-host service recovery transaction is invalid.");
+      }
+      if (resolve5(record2.recovery_backup_path) !== resolve5(recoveryBackupPath(config2, record2.transaction_id))) {
+        throw new Error("Inference-host service recovery backup path is invalid.");
+      }
+      return record2;
+    };
+    assertResumableCodexRecoveryEvidence = (backupAttempts, currentAttempts, cleanupConfirmedAttemptIds, phase) => {
+      const backupIds = Object.keys(backupAttempts).sort();
+      const currentIds = Object.keys(currentAttempts).sort();
+      const backupIdSet = new Set(backupIds);
+      const cleanupConfirmedIdSet = new Set(cleanupConfirmedAttemptIds);
+      if (backupIds.length === 0 || currentIds.some((attemptId) => !backupIdSet.has(attemptId)) || cleanupConfirmedAttemptIds.some((attemptId) => !backupIdSet.has(attemptId)) || phase === "reconciled" && backupIds.some((attemptId) => !cleanupConfirmedIdSet.has(attemptId))) {
+        throw new Error("Codex recovery evidence does not match the retained service recovery backup.");
+      }
+      for (const attemptId of backupIds) {
+        const original = backupAttempts[attemptId];
+        const current = currentAttempts[attemptId];
+        if (!current) {
+          if (!cleanupConfirmedIdSet.has(attemptId)) {
+            throw new Error("Codex recovery evidence does not match the retained service recovery backup.");
+          }
+          continue;
+        }
+        if (cleanupConfirmedIdSet.has(attemptId) && !original.cleanupConfirmed && !(current.processState === "terminated" && current.cleanupConfirmed)) {
+          throw new Error("Codex recovery evidence regressed after confirmed cleanup.");
+        }
+        const {
+          processState: _originalProcessState,
+          cleanupConfirmed: _originalCleanupConfirmed,
+          ...originalStable
+        } = original;
+        const {
+          processState: _currentProcessState,
+          cleanupConfirmed: _currentCleanupConfirmed,
+          ...currentStable
+        } = current;
+        if (JSON.stringify(originalStable) !== JSON.stringify(currentStable) || !(current.processState === original.processState && current.cleanupConfirmed === original.cleanupConfirmed) && !(current.processState === "terminated" && current.cleanupConfirmed)) {
+          throw new Error("Codex recovery evidence changed outside an exact cleanup transition.");
+        }
+      }
+    };
+    recoverInstalledCodexService = async (config2, parsed, env, dependencies, manager) => {
+      if (!parsed.instanceFlagExplicit) {
+        throw new Error(
+          "Service recovery requires an explicit --instance NAME; an environment or default instance is not accepted."
+        );
+      }
+      if (!parsed.forceRecovery) {
+        throw new Error(
+          `Service recovery is disruptive. Rerun with --instance ${config2.instanceName} --force-recovery after checking service status and logs.`
+        );
+      }
+      const credentialLock = await acquireInferenceHostProcessLock(
+        credentialLifecycleLockPath(config2)
+      );
+      try {
+        const recoveryStore = new FileCodexAttemptRecoveryStore(codexRecoveryPath(config2));
+        const existingTransaction = await readServiceRecoveryTransaction(config2);
+        if (existingTransaction && existingTransaction.instance_name !== config2.instanceName) {
+          throw new Error(
+            `Service recovery for instance ${existingTransaction.instance_name} must finish before another instance can recover.`
+          );
+        }
+        const initialAttempts = await recoveryStore.loadAll();
+        const pendingAttempts = Object.values(initialAttempts).filter(
+          (checkpoint) => !checkpoint.cleanupConfirmed
+        );
+        if (pendingAttempts.length === 0 && !existingTransaction) {
+          const status = await manager.status();
+          return {
+            exitCode: 0,
+            stdout: render({
+              status: "service_recovery_not_needed",
+              instance_name: config2.instanceName,
+              recovery_needed: false,
+              recovered_attempt_count: 0,
+              outcome_unknown_attempt_count: 0,
+              desired_running: status.desired_running,
+              manager_active: status.manager_active,
+              worker_runtime_state: status.workers.find(
+                (worker) => worker.instance_name === config2.instanceName
+              )?.runtime_state ?? "unknown"
+            }, parsed.json),
+            stderr: ""
+          };
+        }
+        const recoveryRaw = await readInferencePrivateFile(
+          codexRecoveryPath(config2),
+          "Codex attempt recovery file"
+        );
+        if (recoveryRaw === null && existingTransaction?.phase !== "reconciled") {
+          throw new Error("Codex recovery evidence changed before service recovery began.");
+        }
+        const transactionId = existingTransaction?.transaction_id ?? randomUUID2();
+        const backupPath = existingTransaction?.recovery_backup_path ?? recoveryBackupPath(config2, transactionId);
+        if (!existingTransaction) {
+          await writeAtomicInferencePrivateFile(backupPath, recoveryRaw);
+        }
+        const backupRaw = await readInferencePrivateFile(
+          backupPath,
+          "Codex service recovery backup"
+        );
+        const backupSha256 = backupRaw === null ? null : createHash7("sha256").update(backupRaw).digest("hex");
+        if (backupSha256 === null || existingTransaction && backupSha256 !== existingTransaction.recovery_backup_sha256) {
+          throw new Error("Codex service recovery backup is missing or changed.");
+        }
+        const backupAttempts = await new FileCodexAttemptRecoveryStore(backupPath).loadAll();
+        assertResumableCodexRecoveryEvidence(
+          backupAttempts,
+          initialAttempts,
+          existingTransaction?.cleanup_confirmed_attempt_ids ?? [],
+          existingTransaction?.phase ?? "prepared"
+        );
+        const recoverySha256 = recoveryRaw === null ? null : createHash7("sha256").update(recoveryRaw).digest("hex");
+        const unresolvedAttemptIds = Object.keys(backupAttempts).filter((attemptId) => !existingTransaction?.cleanup_confirmed_attempt_ids.includes(attemptId) && !initialAttempts[attemptId]?.cleanupConfirmed);
+        const binary = unresolvedAttemptIds.length > 0 ? await (dependencies.resolveBinary ?? resolvePinnedCodexBinary)(env) : null;
+        let activeTransaction = existingTransaction;
+        let completed = false;
+        try {
+          const recovered = await manager.recoverInstance(config2.instanceName, async ({ manifest }) => {
+            const workerLocks = [];
+            try {
+              for (const worker of [...manifest.workers].sort(
+                (left, right) => left.instance_name.localeCompare(right.instance_name)
+              )) {
+                const workerConfig = resolveInferenceHostConfig({
+                  ...env,
+                  ...worker.runtime_environment,
+                  VTX_INFERENCE_HOST_INSTANCE: worker.instance_name
+                });
+                workerLocks.push(await acquireInferenceHostProcessLock(
+                  foregroundHostLockPath(workerConfig)
+                ));
+                workerLocks.push(await acquireInferenceHostProcessLock(workerConfig.processLockPath));
+              }
+              try {
+                if (!activeTransaction) {
+                  throw new Error("Inference-host service recovery transaction was not prepared.");
+                }
+                const attempts = await recoveryStore.loadAll();
+                assertResumableCodexRecoveryEvidence(
+                  backupAttempts,
+                  attempts,
+                  activeTransaction.cleanup_confirmed_attempt_ids,
+                  activeTransaction.phase
+                );
+                const unresolved = Object.keys(backupAttempts).filter((attemptId) => !activeTransaction.cleanup_confirmed_attempt_ids.includes(attemptId) && !attempts[attemptId]?.cleanupConfirmed);
+                if (unresolved.length === 0) return 0;
+                const currentRaw = await readInferencePrivateFile(
+                  codexRecoveryPath(config2),
+                  "Codex attempt recovery file"
+                );
+                if (currentRaw === null || recoverySha256 === null || createHash7("sha256").update(currentRaw).digest("hex") !== recoverySha256) {
+                  throw new Error("Codex recovery evidence changed while the service was stopping.");
+                }
+                const proof = await (dependencies.proveCodexQuiescence ?? proveCodexSameBootQuiescence)({
+                  attempts,
+                  confirmNoManagedCodexProcesses: async () => await (dependencies.confirmNoManagedCodexProcesses ?? confirmNoVtxManagedCodexProcesses)({ pinnedBinaryPath: binary.path })
+                });
+                return await (dependencies.reconcileCodexRecovery ?? reconcileCodexAttemptRecovery)({
+                  recoveryHooks: recoveryStore,
+                  codexHome: config2.codexHomePath,
+                  guardianReceiptRoot: codexGuardianReceiptRoot(config2),
+                  sameBootQuiescenceProof: proof
+                });
+              } finally {
+                if (!activeTransaction) {
+                  throw new Error("Inference-host service recovery transaction was not prepared.");
+                }
+                const progressedAttempts = await recoveryStore.loadAll();
+                assertResumableCodexRecoveryEvidence(
+                  backupAttempts,
+                  progressedAttempts,
+                  activeTransaction.cleanup_confirmed_attempt_ids,
+                  activeTransaction.phase
+                );
+                const priorConfirmedIds = new Set(activeTransaction.cleanup_confirmed_attempt_ids);
+                const cleanupConfirmedAttemptIds = Object.keys(backupAttempts).filter((attemptId) => priorConfirmedIds.has(attemptId) || progressedAttempts[attemptId]?.cleanupConfirmed).sort();
+                activeTransaction = {
+                  ...activeTransaction,
+                  phase: cleanupConfirmedAttemptIds.length === Object.keys(backupAttempts).length ? "reconciled" : "prepared",
+                  cleanup_confirmed_attempt_ids: cleanupConfirmedAttemptIds
+                };
+                await writeAtomicInferencePrivateFile(
+                  serviceRecoveryTransactionPath(config2),
+                  `${JSON.stringify(activeTransaction, null, 2)}
+`
+                );
+              }
+            } finally {
+              for (const lock2 of workerLocks.reverse()) await lock2.release();
+            }
+          }, {
+            restoreDesiredRunning: existingTransaction?.restore_desired_running,
+            expectedManifestGeneration: existingTransaction?.manifest_generation,
+            prepare: existingTransaction ? void 0 : async ({ manifest, desiredRunning }) => {
+              activeTransaction = {
+                schema_version: "vtx_inference_service_recovery_v1",
+                phase: "prepared",
+                transaction_id: transactionId,
+                instance_name: config2.instanceName,
+                manifest_generation: manifest.generation,
+                restore_desired_running: desiredRunning,
+                recovery_backup_path: backupPath,
+                recovery_backup_sha256: backupSha256,
+                cleanup_confirmed_attempt_ids: [],
+                started_at: (/* @__PURE__ */ new Date()).toISOString()
+              };
+              await writeAtomicInferencePrivateFile(
+                serviceRecoveryTransactionPath(config2),
+                `${JSON.stringify(activeTransaction, null, 2)}
+`
+              );
+            }
+          });
+          completed = true;
+          const outcomeUnknownAttemptCount = Object.values(backupAttempts).filter(
+            (checkpoint) => checkpoint.dispatchOutcome === "outcome_unknown"
+          ).length;
+          return {
+            exitCode: 0,
+            stdout: render({
+              status: "service_recovered",
+              instance_name: config2.instanceName,
+              recovery_needed: true,
+              recovered_attempt_count: recovered.result,
+              outcome_unknown_attempt_count: outcomeUnknownAttemptCount,
+              desired_running: recovered.status.desired_running,
+              manager_active: recovered.status.manager_active,
+              worker_runtime_state: recovered.status.workers.find(
+                (worker) => worker.instance_name === config2.instanceName
+              )?.runtime_state ?? "unknown"
+            }, parsed.json),
+            stderr: ""
+          };
+        } finally {
+          if (completed) {
+            await clearInferencePrivateFile(
+              serviceRecoveryTransactionPath(config2),
+              "Inference-host service recovery transaction"
+            );
+            await rm5(backupPath, { force: true });
+          }
+        }
+      } finally {
+        await credentialLock.release();
+      }
+    };
     serviceCommand = async (config2, parsed, env, dependencies, warnings) => {
       const action = parsed.serviceAction;
       if (!action) {
-        throw new Error("Usage: vtx inference-host service <install|start|stop|status|logs|uninstall>.");
+        throw new Error("Usage: vtx inference-host service <install|start|stop|status|logs|recover|uninstall>.");
       }
       if (action === "run-internal") {
         if (!parsed.serviceManifestPath) throw new Error("Internal service manifest path is required.");
@@ -34046,15 +34621,32 @@ Waiting for approval...
           await serviceLock.release();
         }
       }
+      if (parsed.forceRecovery && action !== "recover") {
+        throw new Error("--force-recovery is accepted only by service recover.");
+      }
       const manager = dependencies.createServiceManager?.(
         config2,
         dependencies.serviceDependencies
       ) ?? new InferenceHostServiceManager(config2, dependencies.serviceDependencies);
+      if (action === "recover") {
+        return await recoverInstalledCodexService(
+          config2,
+          parsed,
+          env,
+          dependencies,
+          manager
+        );
+      }
       if (action === "install") {
         const credentialLock = await acquireInferenceHostProcessLock(
           credentialLifecycleLockPath(config2)
         );
         try {
+          if (await readServiceRecoveryTransaction(config2)) {
+            throw new Error(
+              "A guarded service recovery transaction must finish before installing a subscription."
+            );
+          }
           const adapter = parsed.adapter || "codex";
           if (adapter !== "codex") {
             throw new Error(
@@ -34112,9 +34704,15 @@ Waiting for approval...
         };
       }
       if (action === "start") {
+        if (await readServiceRecoveryTransaction(config2)) {
+          throw new Error("A guarded service recovery transaction must finish before starting the service.");
+        }
         return { exitCode: 0, stdout: render({ status: "service_started", ...await manager.start() }, parsed.json), stderr: "" };
       }
       if (action === "stop") {
+        if (await readServiceRecoveryTransaction(config2)) {
+          throw new Error("A guarded service recovery transaction must finish before stopping the service.");
+        }
         return { exitCode: 0, stdout: render({ status: "service_stopped", ...await manager.stop() }, parsed.json), stderr: "" };
       }
       if (action === "status") {
@@ -34127,6 +34725,11 @@ Waiting for approval...
           credentialLifecycleLockPath(config2)
         );
         try {
+          if (await readServiceRecoveryTransaction(config2)) {
+            throw new Error(
+              "A guarded service recovery transaction must finish before uninstalling a subscription."
+            );
+          }
           if (parsed.instanceExplicit) {
             const retained = await readInferenceHostCredentialContext(config2);
             const retainedIdentity = retained ? resolveInferenceHostConfig({
@@ -34145,7 +34748,7 @@ Waiting for approval...
           await credentialLock.release();
         }
       }
-      throw new Error("Usage: vtx inference-host service <install|start|stop|status|logs|uninstall>.");
+      throw new Error("Usage: vtx inference-host service <install|start|stop|status|logs|recover|uninstall>.");
     };
     hasExplicitCredentialStoreConfiguration = (env) => Boolean(
       String(env.VTX_INFERENCE_HOST_CREDENTIAL_STORE || "").trim() || String(env.VTX_INFERENCE_HOST_CREDENTIAL_FILE || "").trim()
@@ -34167,8 +34770,8 @@ Waiting for approval...
       }
       throw new Error("Inference host credential store identity is invalid.");
     };
-    commandRequiresRetainedCredentialStore = (parsed) => parsed.command === "logout" || parsed.command === "revoke" || parsed.command === "service" && parsed.instanceExplicit && (parsed.serviceAction === "install" || parsed.serviceAction === "uninstall");
-    commandUsesInstalledServiceCredentials = (parsed) => parsed.command === "login" || parsed.command === "logout" || parsed.command === "revoke" || parsed.command === "status" || parsed.command === "doctor" || parsed.command === "service" && parsed.serviceAction === "install" || parsed.command === "service" && parsed.serviceAction === "uninstall" && parsed.instanceExplicit;
+    commandRequiresRetainedCredentialStore = (parsed) => parsed.command === "logout" || parsed.command === "revoke" || parsed.command === "service" && parsed.instanceExplicit && (parsed.serviceAction === "install" || parsed.serviceAction === "recover" || parsed.serviceAction === "uninstall");
+    commandUsesInstalledServiceCredentials = (parsed) => parsed.command === "login" || parsed.command === "logout" || parsed.command === "revoke" || parsed.command === "status" || parsed.command === "doctor" || parsed.command === "service" && parsed.serviceAction === "install" || parsed.command === "service" && parsed.serviceAction === "recover" || parsed.command === "service" && parsed.serviceAction === "uninstall" && parsed.instanceExplicit;
     resolveInferenceHostCommandConfig = async (parsed, env, dependencies) => {
       const selectedEnv = {
         ...env,
@@ -34191,6 +34794,9 @@ Waiting for approval...
       const installedEnvironment = manifest?.workers.find(
         (worker) => worker.instance_name === baseConfig.instanceName
       )?.runtime_environment;
+      if (parsed.command === "service" && parsed.serviceAction === "recover" && !installedEnvironment) {
+        throw new Error(`Inference-host instance ${baseConfig.instanceName} is not installed.`);
+      }
       const persistedContext = installedEnvironment ? null : await readInferenceHostCredentialContext(baseConfig);
       const revocationCheckpoint = !installedEnvironment && !persistedContext && parsed.command === "revoke" ? await readRevocationCheckpoint(baseConfig) : null;
       const retainedEnvironment = installedEnvironment ?? (persistedContext ? {
@@ -38718,7 +39324,7 @@ var init_utils = __esm({
 });
 
 // node_modules/ethers/lib.esm/crypto/crypto.js
-import { createHash as createHash6, createHmac, pbkdf2Sync, randomBytes as randomBytes5 } from "crypto";
+import { createHash as createHash8, createHmac, pbkdf2Sync, randomBytes as randomBytes5 } from "crypto";
 var init_crypto2 = __esm({
   "node_modules/ethers/lib.esm/crypto/crypto.js"() {
   }
@@ -39932,10 +40538,10 @@ var init_sha22 = __esm({
     init_crypto2();
     init_utils();
     _sha256 = function(data) {
-      return createHash6("sha256").update(data).digest();
+      return createHash8("sha256").update(data).digest();
     };
     _sha512 = function(data) {
-      return createHash6("sha512").update(data).digest();
+      return createHash8("sha512").update(data).digest();
     };
     __sha256 = _sha256;
     __sha512 = _sha512;
@@ -52112,7 +52718,7 @@ __export(vtx_exports, {
   runVtxCli: () => runVtxCli
 });
 import { randomUUID as randomUUID6 } from "node:crypto";
-import { spawn as spawn7 } from "node:child_process";
+import { spawn as spawn8 } from "node:child_process";
 function render2(value, json2) {
   if (json2) {
     return `${JSON.stringify(value, null, 2)}
@@ -52142,7 +52748,7 @@ function openBrowser(url2) {
   const platform = process.platform;
   const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
   const args = platform === "win32" ? ["/c", "start", "", url2] : [url2];
-  const child = spawn7(command, args, { detached: true, stdio: "ignore" });
+  const child = spawn8(command, args, { detached: true, stdio: "ignore" });
   child.unref();
 }
 function parseFlags(args) {

package/package.json

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