fix(update): keep a history-preflight refusal from aborting the update (#4718)

bin/ocx.mjs

@@ -522,6 +522,16 @@ function runPackageManagerSelfUpdate(manager) {
         "  After the update: close the Codex app, run 'ocx doctor', then run 'ocx stop' once to retry.",
       );
     }
+    if (decision.reason === "history-deferred") {
+      // The reported #4718 path is this lane. Nothing was restored, so this is a different
+      // sentence from the manifest warning above: an operator told "history metadata is
+      // incomplete" would assume config and catalog already came back.
+      console.warn(
+        "opencodex: WARNING — the shared teardown was refused by the Codex history preflight and restored nothing.\n" +
+        "  Config, catalog, history and provenance were preserved, and the teardown receipt was kept.\n" +
+        "  The proxy is down, so the update continues; close the Codex app and run 'ocx stop' once afterwards to finish the restore.",
+      );
+    }
   }
 
   // npm keeps the existing stage -> verify -> swap -> rollback flow. pnpm owns a

src/cli/index.ts

@@ -15,7 +15,7 @@ try {
 }
 import { currentExternalCodexModelProvider, restoreNativeCodex, restoreNativeCodexAsync, shouldInjectApiAuthHeader } from "../codex/inject";
 import { stripGrokConfig } from "../grok/inject";
-import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "../update/stop-contract.mjs";
+import { STOP_HISTORY_DEFERRED_EXIT_CODE, STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "../update/stop-contract.mjs";
 import {
   describeHistoryJobFailure,
   resolveCodexHistoryJobTarget,
@@ -46,6 +46,7 @@ import {
   isPendingTeardownAbandoned,
   listPendingTeardowns,
   pendingTeardownPathFor,
+  pendingTeardownsAreExactly,
   quarantinePendingTeardown,
 } from "../config/pending-teardown";
 import { collectStatus, hubStatusLines, remoteHubBannerLine, remoteHubStatusLines, unusedProxyWarningLines } from "./status";
@@ -785,9 +786,16 @@ async function handleRestartStartWhenStopped(): Promise<boolean | "skipped"> {
  *
  * The distinction exists because `ocx update` must proceed for the first and abort for the
  * second, and it can only see an exit code (#3008).
+ *
+ * `historyDeferred` is the third kind (#4718). The Codex history preflight refuses BEFORE
+ * the config half runs, so nothing was restored at all: config, catalog, history and
+ * provenance are untouched and the client is still routed at the proxy that just stopped.
+ * Like `historyOnly` the proxy is genuinely down, so an update may replace package files.
+ * Unlike `historyOnly` the obligation was not performed, so the receipt must survive.
  */
-async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boolean; other: boolean }> {
+async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boolean; historyDeferred: boolean; other: boolean }> {
   let historyOnly = false;
+  let historyDeferred = false;
   let other = false;
   try {
     const result = await restoreNativeCodexAsync();
@@ -798,7 +806,16 @@ async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boole
       // not — a client reads those, so their failure is a real teardown failure.
       const artifacts = result.artifacts;
       const configOrCatalogFailed = artifacts.config.state === "failed" || artifacts.catalog.state === "failed";
-      if (!configOrCatalogFailed && artifacts.history.state === "failed") historyOnly = true;
+      // A preflight refusal reports every artifact as `skipped` because none of them were
+      // attempted. Reading the states alone cannot tell that apart from an ownership
+      // refusal, so the structured reason carries it and the states are still required to
+      // agree — a refusal that somehow reports a failed artifact is not this case.
+      const preflightRefused = result.historyPreflightRefusal !== undefined
+        && artifacts.config.state === "skipped"
+        && artifacts.catalog.state === "skipped"
+        && artifacts.history.state === "skipped";
+      if (preflightRefused) historyDeferred = true;
+      else if (!configOrCatalogFailed && artifacts.history.state === "failed") historyOnly = true;
       else other = true;
       console.error(`⚠️  ${result.message}`);
     }
@@ -816,7 +833,7 @@ async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boole
     other = true;
     console.error(`⚠️  Grok config restore failed: ${error instanceof Error ? error.message : String(error)}`);
   }
-  return { historyOnly, other };
+  return { historyOnly, historyDeferred, other };
 }
 
 async function handleStop() {
@@ -860,6 +877,11 @@ async function handleStop() {
   };
   let stopFailed = false;
   let historyOnlyFailure = false;
+  /**
+   * Obligations this run deliberately kept because the Codex history preflight refused
+   * before restoring anything (#4718). Non-null selects the deferred exit code.
+   */
+  let historyDeferredNonces: string[] | null = null;
   // Only Task Scheduler respawns after a successful stop (#764), so only it earns the
   // restart-window wait; launchd, systemd and WinSW are down when they say so.
   let schedulerCanRespawn = false;
@@ -1138,14 +1160,24 @@ async function handleStop() {
     }
     const restore = await restoreSharedClientStateAfterStop();
     if (restore.other) stopFailed = true;
+    else if (restore.historyDeferred) historyDeferredNonces = teardownNonce ? [teardownNonce, ...recoveredNonces] : recoveredNonces;
     else if (restore.historyOnly) historyOnlyFailure = true;
     // The obligation is discharged whether or not history metadata finalized: config and
     // catalog are what a client reads, and `restore.other` already fails the stop.
     //
     // Each nonce names its own file, so a clear can only ever remove the obligation it
     // names — never one a concurrent stop wrote. Both this run's claim and every inherited
     // receipt it proved discharged are released together.
-    if (!restore.other) {
+    //
+    // A history-preflight refusal is the exception: it restored nothing, so there is
+    // nothing to discharge. Clearing here would drop a real obligation on the floor and
+    // leave the client config pointing at a proxy that is gone, with nothing on disk
+    // saying so — which is the whole failure the receipt exists to prevent (#4718).
+    if (restore.historyDeferred) {
+      console.error("   The shared teardown was refused before it changed anything, so it is still owed.");
+      console.error("   Its receipt is preserved; run 'ocx stop' again once Codex is closed to retry the restore.");
+    }
+    if (!restore.other && !restore.historyDeferred) {
       const discharged = teardownNonce ? [teardownNonce, ...recoveredNonces] : recoveredNonces;
       for (const nonce of discharged) {
         // A receipt that survives its discharge re-triggers recovery forever, so a failed
@@ -1185,6 +1217,17 @@ async function handleStop() {
   // still wins: it is the stronger signal.
   if (stopFailed) process.exitCode = 1;
   else if (historyOnlyFailure) process.exitCode = STOP_HISTORY_INCOMPLETE_EXIT_CODE;
+  // The deferred code says "the only obligations left are the ones I just decided to
+  // keep". It is read across a process boundary by an updater that will replace package
+  // files on the strength of it, so this run has to be able to prove the claim: if any
+  // other obligation is sitting in the home — quarantined, or a concurrent stop's — the
+  // claim is false and the ordinary failure code is the honest answer. That is also the
+  // behaviour before #4718, so the fallback loses nothing that used to work.
+  else if (historyDeferredNonces) {
+    process.exitCode = pendingTeardownsAreExactly(historyDeferredNonces)
+      ? STOP_HISTORY_DEFERRED_EXIT_CODE
+      : 1;
+  }
   return !stopFailed;
 }
 

src/codex/inject/restore.ts

@@ -89,6 +89,18 @@ export interface CodexNativeRestoreResult {
   success: boolean;
   message: string;
   externalProvider?: string;
+  /**
+   * Set when the restore refused at the Codex history preflight (#4718).
+   *
+   * The preflight runs before the config half, so a refusal leaves config, catalog,
+   * history and provenance exactly as they were. That is a different outcome from a
+   * restore that ran and failed, and callers that decide whether an obligation was
+   * discharged need to tell them apart. Reading the artifact states alone cannot: a
+   * refusal reports every artifact as `skipped`, which is also what an ownership refusal
+   * and a desired-state skip report. Matching the human-readable message instead would
+   * make a safety decision depend on prose.
+   */
+  historyPreflightRefusal?: string;
   artifacts: {
     config: CodexRestoreConfigResult;
     catalog: CodexRestoreCatalogResult;
@@ -216,6 +228,21 @@ function failedConfigRestoreEnvelope(config: CodexRestoreConfigResult): CodexNat
   return result;
 }
 
+/**
+ * The history preflight refused, so nothing was attempted at all (#4718).
+ *
+ * The message is unchanged from what this path has always printed; the structured reason
+ * is added beside it so a caller can act on the refusal without reading the prose.
+ */
+function historyPreflightRefusalEnvelope(historyError: string): CodexNativeRestoreResult {
+  const result = skippedRestoreEnvelope(
+    false,
+    `Native restore refused: ${historyError}. Config, catalog, history and provenance were preserved.`,
+  );
+  result.historyPreflightRefusal = historyError;
+  return result;
+}
+
 /** The config/profile half of a native restore, reported as one artifact. */
 function restoreCodexConfigInline(kind = "sync"): CodexRestoreConfigResult {
   const preImages = captureCodexPreImages();
@@ -342,7 +369,7 @@ async function restoreNativeCodexAsyncImpl(
   }
 
   const historyError = preflightCodexHistoryInjection(false, false);
-  if (historyError) return skippedRestoreEnvelope(false, `Native restore refused: ${historyError}. Config, catalog, history and provenance were preserved.`);
+  if (historyError) return historyPreflightRefusalEnvelope(historyError);
 
   const eligibility = codexWriteCoordinationEligibility({
     coordinatorPath: () =>
@@ -490,7 +517,7 @@ export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateD
     return desiredEnabledRestoreSkip();
   }
   const historyError = preflightCodexHistoryInjection(false, false);
-  if (historyError) return skippedRestoreEnvelope(false, `Native restore refused: ${historyError}. Config, catalog, history and provenance were preserved.`);
+  if (historyError) return historyPreflightRefusalEnvelope(historyError);
   // Captured before the config half: a successful journal restore DELETES the journal, and
   // restoring the config can drop `model_catalog_json`. Either one would hide the routed
   // catalog we actually wrote (#1798).

src/config/pending-teardown.ts

@@ -202,6 +202,37 @@ export function pendingTeardownOutstanding(): boolean {
   }
 }
 
+/**
+ * Are the outstanding obligations EXACTLY the ones this stop chose to keep?
+ *
+ * `ocx stop` can preserve its own obligations deliberately — the Codex history preflight
+ * refuses before anything is restored, so the receipt has to survive for a later stop
+ * (#4718). That is safe for an update to continue past, because the stop knows those
+ * receipts describe a proxy it just proved down.
+ *
+ * Nothing else is. A quarantined receipt is waiting on a human, and a receipt belonging
+ * to a live owner means another stop is in flight; letting either ride along would turn
+ * "we deliberately kept ours" into "we ignored everyone's". So membership is the test,
+ * not a count of ours: an unrecognized obligation of any kind answers false and the
+ * caller falls back to the ordinary failure code.
+ *
+ * Quarantined names are included in the scan on purpose. They do not correspond to any
+ * nonce this run preserved, so their presence always answers false.
+ */
+export function pendingTeardownsAreExactly(nonces: readonly string[]): boolean {
+  const expected = new Set(nonces.map(nonce => `${PREFIX}${nonce}${SUFFIX}`));
+  let names: string[];
+  try {
+    names = readdirSync(getConfigDir());
+  } catch (error) {
+    // A home that does not exist holds nothing, which matches only an empty expectation.
+    // Any other scan failure may be hiding an obligation and must not answer "exactly".
+    return (error as NodeJS.ErrnoException).code === "ENOENT" && expected.size === 0;
+  }
+  const found = names.filter(isAnyTeardownObligationFileName);
+  return found.length === expected.size && found.every(name => expected.has(name));
+}
+
 /** Paths of quarantined obligations awaiting a human. */
 export function listQuarantinedTeardowns(): string[] {
   try {

src/update/index.ts

@@ -481,6 +481,16 @@ export async function runUpdate(): Promise<void> {
         "    After the update: close the Codex app, run 'ocx doctor', then run 'ocx stop' once to retry.",
       );
     }
+    if (decision.reason === "history-deferred") {
+      // Not the same warning: nothing was restored here. Saying "history metadata is
+      // incomplete" would imply config and catalog came back, and an operator who
+      // believed that would not know a teardown is still owed.
+      console.warn(
+        "⚠️  The shared teardown was refused by the Codex history preflight and restored nothing.\n" +
+        "    Config, catalog, history and provenance were preserved, and the teardown receipt was kept.\n" +
+        "    The proxy is down, so the update continues; close the Codex app and run 'ocx stop' once afterwards to finish the restore.",
+      );
+    }
   }
 
   console.log(`Updating${latest ? ` to v${latest}` : ""}…\n$ ${bin} ${cmdArgs.join(" ")}`);

src/update/stop-contract.d.mts

@@ -1,2 +1,3 @@
 /** Declaration for the plain-ESM stop contract shared with `bin/ocx.mjs`. */
 export declare const STOP_HISTORY_INCOMPLETE_EXIT_CODE: 79;
+export declare const STOP_HISTORY_DEFERRED_EXIT_CODE: 80;

src/update/stop-contract.mjs

@@ -13,3 +13,22 @@
  * the child's code faithfully enough to propagate the confusion.
  */
 export const STOP_HISTORY_INCOMPLETE_EXIT_CODE = 79;
+
+/**
+ * The exit code `ocx stop` uses to say "the proxy is down and the shared teardown was
+ * refused before it changed anything" (#4718).
+ *
+ * This is NOT 79. Seventy-nine means the teardown ran: config and catalog came back to
+ * their native values and only the Codex history metadata could not be finalized, so the
+ * receipt is discharged. Eighty means the Codex history preflight refused FIRST, so
+ * config, catalog, history and provenance are all untouched, the client is still routed
+ * at the proxy that just stopped, and the receipt stays outstanding for a later stop.
+ *
+ * Collapsing the two would be a data-loss bug in the quiet direction: a caller reading 79
+ * discharges an obligation that was never performed.
+ *
+ * Eighty sits in the same unoccupied window as 79 — above `sysexits.h` (64-78), below
+ * `128 + signal`, and outside 0, 1, 2, 4, 64 and 130, which are the codes this CLI and its
+ * dispatcher already emit.
+ */
+export const STOP_HISTORY_DEFERRED_EXIT_CODE = 80;

src/update/stop-decision.d.mts

@@ -6,5 +6,5 @@ export declare function decidePostStopUpdate(input: {
   teardownOutstanding?: boolean;
 }): {
   proceed: boolean;
-  reason: "stop-failed" | "runtime-state" | "teardown-outstanding" | "proxy-live" | "proxy-unknown" | "history-only" | "ok";
+  reason: "stop-failed" | "runtime-state" | "teardown-outstanding" | "proxy-live" | "proxy-unknown" | "history-only" | "history-deferred" | "ok";
 };

src/update/stop-decision.mjs

@@ -1,4 +1,4 @@
-import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "./stop-contract.mjs";
+import { STOP_HISTORY_DEFERRED_EXIT_CODE, STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "./stop-contract.mjs";
 
 /**
  * May an update replace package files after `ocx stop` returned?
@@ -22,13 +22,22 @@ import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "./stop-contract.mjs";
  *   absence, and replacing files under a live server leaves it running a mix of old and
  *   new modules.
  * - `ok` / `history-only` — proceed; the second also prints the manifest warning.
+ * - `history-deferred` — proceed; the stop is down but restored nothing, because the
+ *   Codex history preflight refused first (#4718). The receipts it kept are the ONLY
+ *   obligations it left, which the child proved before choosing this status, so
+ *   `teardownOutstanding` seeing them is expected rather than disqualifying. Every other
+ *   gate still applies: runtime records and a live or unreadable endpoint abort exactly
+ *   as they do for a clean stop, because package replacement under a live server is the
+ *   danger this function exists to prevent, and a history refusal says nothing about it.
  */
 export function decidePostStopUpdate({ status, hasRuntimeState, liveness, teardownOutstanding = false }) {
   const historyOnly = status === STOP_HISTORY_INCOMPLETE_EXIT_CODE;
-  if (status !== 0 && !historyOnly) return { proceed: false, reason: "stop-failed" };
+  const historyDeferred = status === STOP_HISTORY_DEFERRED_EXIT_CODE;
+  if (status !== 0 && !historyOnly && !historyDeferred) return { proceed: false, reason: "stop-failed" };
   if (hasRuntimeState) return { proceed: false, reason: "runtime-state" };
-  if (teardownOutstanding) return { proceed: false, reason: "teardown-outstanding" };
+  if (teardownOutstanding && !historyDeferred) return { proceed: false, reason: "teardown-outstanding" };
   if (liveness === "live") return { proceed: false, reason: "proxy-live" };
   if (liveness !== "dead") return { proceed: false, reason: "proxy-unknown" };
+  if (historyDeferred) return { proceed: true, reason: "history-deferred" };
   return { proceed: true, reason: historyOnly ? "history-only" : "ok" };
 }

tests/codex-integration/codex-inject-integration.test.ts

@@ -123,6 +123,15 @@ describe("injectCodexConfig integration (Design B)", () => {
     expect(result.defaultEntries).toBe(1);
     expect(result.result.success).toBe(false);
     expect(result.result.message).toContain("history_paginated_requires_native_writer");
+    // #4718: the refusal also has to be legible without reading the message. `ocx stop`
+    // decides whether an obligation was discharged from this envelope, and every artifact
+    // comes back "skipped" here — the same shape an ownership refusal and a desired-state
+    // skip produce. Without the structured reason the caller could only match prose, and
+    // the stop misread this as a generic teardown failure and aborted the update.
+    expect(result.result.historyPreflightRefusal).toBe("history_paginated_requires_native_writer");
+    expect(result.result.artifacts.config.state).toBe("skipped");
+    expect(result.result.artifacts.catalog.state).toBe("skipped");
+    expect(result.result.artifacts.history.state).toBe("skipped");
     expect(result.preserved).toBe(true);
   });
 

tests/providers/xai/grok-lifecycle.test.ts

@@ -315,7 +315,11 @@ describe("Grok fence lifecycle wiring", () => {
     const updateSource2 = readFileSync(repoPath("src", "update", "index.ts"), "utf8");
     expect(updateSource2).toContain("teardownOutstanding: pendingTeardownOutstanding()");
     const decisionSource = readFileSync(repoPath("src", "update", "stop-decision.mjs"), "utf8");
-    expect(decisionSource).toContain('if (teardownOutstanding) return { proceed: false, reason: "teardown-outstanding" };');
+    // The gate has exactly one exemption, and it is the child saying it kept those
+    // receipts on purpose after the Codex history preflight refused (#4718). Anything
+    // else — including a stop that merely exited 0 — still aborts the install.
+    expect(decisionSource).toContain('if (teardownOutstanding && !historyDeferred) return { proceed: false, reason: "teardown-outstanding" };');
+    expect(decisionSource).toContain("const historyDeferred = status === STOP_HISTORY_DEFERRED_EXIT_CODE;");
     const receiptSource = readFileSync(repoPath("src", "config", "pending-teardown.ts"), "utf8");
     expect(receiptSource).toContain('from "./pending-teardown-names.mjs"');
     expect(receiptSource).toContain("isPendingTeardownFileName(name)");