@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
922 lines (883 loc) • 44.6 kB
text/typescript
import { restoreApprovedCodexProviders } from "../provider-routing";
import { beginCodexWriteSection, cleanExternalProviderJournal, publishCodexArtifact } from "./config-write-section";
import { assertCodexHomeOwner, codexHomeIsAbsent, codexHomeOwnerBlocksCompensation, CodexHomeOwnerRefusal, type CodexHomeOwnerRefusalReason } from "../codex-home-owner";
import { loadConfig } from "../../config";
import { StopRestoreOwnershipError } from "../../client/restore-ownership";
import { withHistoryWriteSerialization } from "../history-lock";
import { shouldSyncCodexOnStart } from "../desired-state";
import { siblingOfLivePort, siblingSkipMessage } from "../sibling-start";
import { withCatalogWriteSerialization } from "../catalog-write-serialization";
import { restoreCodexCatalogWithPermit } from "../catalog/sync";
import { readCodexCatalogPath } from "../catalog/parsing";
import { notifyCatalogPublication } from "../catalog/publication-observer";
import { withCodexWriteLock, CodexWriteLockSkipped } from "../codex-write-lock";
import { inspectNativeCodexOwnership } from "../../integrations/native/ownership-preflight";
import { resolveCodexHistoryTransition } from "../history-transition";
import {
captureCodexPreImages,
codexWriteCoordinationEligibility,
CodexPartialWriteError,
CodexWriteConflictError,
DEFAULT_INJECT_LOCK_TIMEOUT_MS,
recordCodexNativeTransactionProvenance,
restoreCodexPreImages,
} from "../inject-coordination";
import { readIntegrationRecord } from "../integration-record";
import { classifyNativeRoutedResidue } from "../native-residue";
import {
resolveCodexCoordinatorDatabasePath,
resolveEffectiveUserIdentity,
} from "../user-identity";
import {
journaledInjectedCatalogPath,
JOURNAL_PATH,
releaseJournalHomeBinding,
restoreJournalState,
} from "../journal";
import {
preflightCodexHistoryInjection,
syncCodexHistoryProvider,
HISTORY_RELABEL_STANDS_DOWN,
type CodexHistoryFailureReason,
} from "../history-provider";
import {
describeHistoryJobFailure,
deriveCodexHistoryOperation,
resolveCodexHistoryJobTarget,
runCodexHistoryJob,
type CodexHistoryJobOutcome,
} from "../history-job";
import {
CODEX_CONFIG_PATH,
DEFAULT_CATALOG_PATH,
getCodexHome,
tomlString,
} from "../paths";
import {
acquireConfigWriteLock,
releaseConfigWriteLock,
configWriteLockFailureMessage, withConfigWriteLockHeld,
ConfigWriteContentChanged,
} from "../config-write-lock";
import type { LockHandle } from "../config-write-lock";
import { shouldInjectApiAuthHeader } from "../loopback-target";
import { currentExternalCodexModelProvider } from "./config-toml";
import {
readOcxProviderTableBlock,
removeCodexConfig,
retainOcxProviderTableOnDisk,
} from "./remove";
class CodexRestoreRefusal extends Error {
constructor(readonly config: CodexRestoreConfigResult) {
super(config.message);
}
}
let beforeRestoreConfigForTests: ((kind: string) => void) | undefined;
export function setBeforeRestoreConfigForTests(hook: typeof beforeRestoreConfigForTests): void {
beforeRestoreConfigForTests = hook;
}
/**
* `partial` means the artifact was restored as far as it safely could be and named what
* it left behind. It is not a failure — the caller's obligation was discharged — but it
* is not a plain `ok` either, because something on disk still needs a decision (#4812).
*/
export type CodexRestoreArtifactState = "ok" | "partial" | "skipped" | "failed";
/** What a degraded restore kept, why, and how to finish the job. */
export interface RetainedCodexProviderTable {
reason: typeof HISTORY_RELABEL_STANDS_DOWN;
/** The exact `config.toml` lines left on disk. */
lines: string[];
followUp: string;
}
const RETAINED_PROVIDER_TABLE_FOLLOW_UP =
"Run 'ocx restore --remove-codex-provider-table' to remove it; conversations already tagged "
+ "opencodex will stop opening if you do.";
/**
* The one sentence every teardown surface prints about retained residue.
*
* Shared rather than rewritten per caller: `restore`, `stop`, `uninstall`, the service
* subcommands and the stop API all report this same outcome, and a user who runs two of
* them should not have to work out whether two different descriptions mean the same state.
*/
export function describeRetainedCodexProviderTable(retained: RetainedCodexProviderTable): string {
return "Kept [model_providers.opencodex] in $CODEX_HOME/config.toml because Codex owns this home's"
+ ` paginated history (${retained.reason}): conversations already tagged opencodex resolve only`
+ ` through that table. Plain \`codex\` is native again. ${retained.followUp}`;
}
export interface CodexRestoreConfigResult {
state: CodexRestoreArtifactState;
changed: boolean;
action:
| "journal-restored"
| "owned-fields-stripped"
| "routing-restored-provider-retained"
| "external-provider-preserved"
| "approved-provider-restored"
| "failed";
message: string;
retained?: RetainedCodexProviderTable;
retryable?: boolean;
}
export interface CodexRestoreCatalogResult {
state: CodexRestoreArtifactState;
changed: boolean;
removed: number;
kept: number;
path: string | null;
message: string;
}
export interface CodexRestoreHistoryResult {
state: CodexRestoreArtifactState;
changed: boolean;
reason?: CodexHistoryFailureReason;
rows: number;
files: number;
ejectedRows: number;
message: string;
}
export interface CodexNativeRestoreResult {
ownershipRefusal?: CodexHomeOwnerRefusalReason;
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;
/**
* Set when routing came out but `[model_providers.opencodex]` stayed (#4812).
*
* Distinct from `historyPreflightRefusal`, which means nothing was attempted at all.
* This one means the config obligation WAS discharged, so a stop receipt must be
* released rather than preserved.
*/
retainedCodexProviderTable?: RetainedCodexProviderTable;
artifacts: {
config: CodexRestoreConfigResult;
catalog: CodexRestoreCatalogResult;
history: CodexRestoreHistoryResult;
};
}
function failedHistoryRestore(
reason?: CodexHistoryFailureReason,
detail?: string,
progress: { rows?: number; files?: number } = {},
): CodexRestoreHistoryResult {
const rows = progress.rows ?? 0;
const files = progress.files ?? 0;
const changed = rows > 0 || files > 0;
return {
state: "failed",
changed,
...(reason ? { reason } : {}),
rows,
files,
ejectedRows: 0,
message: reason === "permission"
? changed
? "Codex resume history changed but did NOT converge because permission was denied while finalizing the backup manifest; the manifest was retained for review and safe retry."
: "Codex resume history could NOT be restored because permission was denied."
: reason === "busy"
? changed
? "Codex resume history changed but did NOT converge because backup-manifest finalization remained busy; the manifest was retained for review and safe retry."
: detail ?? "Codex resume history could NOT be restored — the Codex app appears to be holding the history database."
: reason === "integrity"
? changed
? "Codex resume history changed but did NOT converge because the backup or target changed; the manifest was retained for review and safe retry."
: "Codex resume history could NOT be restored because the backup or restore target failed integrity checks; unverified provider metadata was left unchanged."
: detail
? `Codex resume history could NOT be restored: ${detail}`
: "Codex resume history could NOT be restored; the reason was not recorded. Run 'ocx doctor'.",
};
}
/**
* Restore failure wording for a Worker outcome.
*
* Only a genuine busy result blames the Codex app. An unsafe-path refusal, an
* unavailable coordinator database, a permission denial, or a dead/timed-out
* worker is a different problem; the old collapse made every one of those read
* as "the Codex app is holding the database" (issue #1191). `busy` and
* `permission` keep the restore-specific sentence built by
* `failedHistoryRestore`; every other reason reuses the single formatter so
* the two modules cannot drift apart.
*/
export function failedHistoryRestoreFromOutcome(
outcome: Extract<CodexHistoryJobOutcome, { kind: "blocked" | "failed" }>,
): CodexRestoreHistoryResult {
if (outcome.kind === "blocked" && outcome.reason === "busy") return failedHistoryRestore("busy");
if (outcome.kind === "failed" && outcome.historyFailureReason === "busy") {
return failedHistoryRestore(
"busy",
describeHistoryJobFailure(outcome, "restore"),
{ rows: outcome.rows, files: outcome.files },
);
}
if (outcome.kind === "failed" && outcome.historyFailureReason === "permission") {
return failedHistoryRestore("permission", undefined, { rows: outcome.rows, files: outcome.files });
}
if (outcome.kind === "failed" && outcome.historyFailureReason === "integrity") {
return failedHistoryRestore("integrity", undefined, { rows: outcome.rows, files: outcome.files });
}
return failedHistoryRestore(undefined, describeHistoryJobFailure(outcome, "restore"));
}
export function finishApprovedProviderRestore(result: CodexNativeRestoreResult, revalidateDesiredState = false): CodexNativeRestoreResult {
if (!result.success || revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) return result;
try {
if (!restoreApprovedCodexProviders()) return result;
} catch (error) {
if (error instanceof CodexHomeOwnerRefusal) throw error;
const message = `Approved Codex provider URL restoration failed: ${error instanceof Error ? error.message : String(error)}`;
return { ...result, success: false, message: `${result.message} ${message}`, artifacts: {
...result.artifacts, config: { ...result.artifacts.config, state: "failed", action: "failed", message },
} };
}
const message = "Approved Codex provider URLs restored; identity, other settings and history preserved.";
return { ...result, message: result.externalProvider ? message : `${result.message} ${message}`, artifacts: {
...result.artifacts,
config: { ...result.artifacts.config, state: result.artifacts.config.state === "partial" ? "partial" : "ok", changed: true,
action: result.artifacts.config.changed ? result.artifacts.config.action : "approved-provider-restored",
message: result.artifacts.config.state === "partial" ? `${result.artifacts.config.message} ${message}` : message },
} };
}
function externalProviderRestoreResult(activeProvider: string): CodexNativeRestoreResult {
const message = `External Codex provider ${tomlString(activeProvider)} preserved; no native restore was needed.`;
return {
success: true,
message,
externalProvider: activeProvider,
artifacts: {
config: { state: "skipped", changed: false, action: "external-provider-preserved", message },
catalog: { state: "skipped", changed: false, removed: 0, kept: 0, path: null, message },
history: { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message },
},
};
}
/** A foreign service claim is an authority boundary, including explicit CLI restore. */
function foreignOwnershipRestoreRefusal(message: string): CodexNativeRestoreResult {
return {
success: false,
message: `Codex native restore refused: ${message}`,
artifacts: {
config: { state: "skipped", changed: false, action: "failed", message },
catalog: { state: "skipped", changed: false, removed: 0, kept: 0, path: null, message },
history: { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message },
},
};
}
function desiredEnabledRestoreSkip(): CodexNativeRestoreResult {
const message = "Codex integration was re-enabled; native restore was skipped.";
return skippedRestoreEnvelope(true, message);
}
/**
* A sibling instance restores nothing: the journal, config and catalog are the live owner's.
*
* It has to be checked before anything else, not left to the desired-state re-reads below. Those
* skip a restore when `shouldSyncCodexOnStart` says ON, and the sibling mark makes that gate
* answer OFF, so without this the gate would read as "the user turned Codex off" and the restore
* would replay the owner's journal.
*/
function siblingRestoreSkip(): CodexNativeRestoreResult | null {
return siblingOfLivePort() === null ? null : skippedRestoreEnvelope(true, siblingSkipMessage());
}
/**
* A schema-complete all-skipped envelope for outcomes decided before any
* restore machinery runs. Every `restore --json` path must stay shape-stable
* with `CodexNativeRestoreResult`; consumers never special-case early exits.
*/
export function skippedRestoreEnvelope(success: boolean, message: string): CodexNativeRestoreResult {
return {
success,
message,
artifacts: {
config: { state: "skipped", changed: false, action: "owned-fields-stripped", message },
catalog: { state: "skipped", changed: false, removed: 0, kept: 0, path: null, message },
history: { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message },
},
};
}
/** Config was attempted and failed; downstream artifacts were never attempted. */
function failedConfigRestoreEnvelope(config: CodexRestoreConfigResult): CodexNativeRestoreResult {
const result = skippedRestoreEnvelope(false, config.message);
result.artifacts.config = config;
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;
}
/**
* How a restore may proceed given what the history preflight says.
*
* The preflight answers one question — may conversation history be rewritten — and this
* translates it into the separate question the restore actually needs answered: may
* OpenCodex routing come out of `config.toml`, and what has to stay if it does.
*/
export type RestoreHistoryDisposition =
| { kind: "proceed" }
| { kind: "stand-down"; retainProviderTable: boolean }
| { kind: "refuse"; reason: string };
export function resolveRestoreHistoryDisposition(
removeProviderTable: boolean | undefined,
reason: string | null = preflightCodexHistoryInjection(false, false),
): RestoreHistoryDisposition {
if (!reason) return { kind: "proceed" };
// Every other reason still means the history state itself is wrong — a missing store, an
// unreadable rollout, an integrity failure. Those keep the hard refusal and the
// compensating rollback they have always had.
if (reason !== HISTORY_RELABEL_STANDS_DOWN) return { kind: "refuse", reason };
// The rows stay tagged `opencodex` either way, because the native writer owns them.
// Retaining the table is what keeps those conversations openable; the explicit flag is
// the user accepting that they will not be.
return { kind: "stand-down", retainProviderTable: removeProviderTable !== true };
}
export interface RestoreConfigOptions {
/** Strip `[model_providers.opencodex]` too, accepting that tagged threads stop opening. */
removeProviderTable?: boolean;
/** Synchronous caller policy and exclusion, repeated at every async restore write boundary. */
withWriteGuard?: <T>(write: () => T) => T;
}
function guardedRestoreWrite<T>(options: RestoreConfigOptions, write: () => T): T {
return options.withWriteGuard ? options.withWriteGuard(write) : write();
}
/** The config/profile half of a native restore, reported as one artifact. */
function restoreCodexConfigInline(
kind = "sync",
options: RestoreConfigOptions = {},
heldConfigWriteLock?: LockHandle,
): CodexRestoreConfigResult {
/*
* The whole config half — preimage capture, journal replay, removal, the
* provider-table re-attach, and failure compensation — is ONE section of the
* shared write lock. Splitting it let a foreign write land between the pieces
* and left preimage compensation replaying over bytes that writer committed.
*/
const locked = withConfigWriteLockHeld(CODEX_CONFIG_PATH, heldConfigWriteLock, (held) => guardedRestoreWrite(options, () => {
beginCodexWriteSection(held);
assertCodexHomeOwner(getCodexHome());
beforeRestoreConfigForTests?.(kind);
assertCodexHomeOwner(getCodexHome());
const preImages = captureCodexPreImages();
const result = restoreCodexConfigInlineImpl(kind, options, held);
if (result.state === "failed") {
const compensated = restoreCodexPreImages(preImages, held);
if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
}
return result;
}));
if (!locked.ok) {
// Nothing was captured or written — there is nothing to compensate.
return {
state: "failed", changed: false, action: "failed",
retryable: locked.error === "locked", message: configWriteLockFailureMessage(locked),
};
}
return locked.value;
}
function restoreCodexConfigInlineImpl(
kind: string,
options: RestoreConfigOptions,
heldConfigWriteLock: LockHandle,
): CodexRestoreConfigResult {
try {
const disposition = resolveRestoreHistoryDisposition(options.removeProviderTable);
if (disposition.kind === "refuse") {
return { state: "failed", changed: false, action: "failed", message: `Codex configuration and journal preserved: ${disposition.reason}.` };
}
// Captured unconditionally, not only when the stand-down is already known.
//
// Two different paths need bytes that only exist before the write. The journal restore
// replays the pre-injection config, which never contained our table, and then deletes
// the journal. And Codex can paginate DURING the write: the post-write re-check below
// then sees a stand-down that the pre-write check did not, at which point the table has
// already been stripped and there is nothing left to read. Both are cheap to prevent
// and impossible to repair afterwards, so the read happens once, here.
//
// The one caller that must not capture is the explicit removal flag: it is the user
// accepting that tagged conversations stop opening.
const capturedBlock = options.removeProviderTable === true ? null : readOcxProviderTableBlock();
const journal = restoreJournalState({ heldConfigWriteLock });
if (journal.ownershipRefusal) throw new CodexHomeOwnerRefusal(journal.ownershipRefusal);
if (journal.lockUnsafe) return { state: "failed", changed: false, action: "failed", retryable: false, message: journal.lockUnsafe };
if (journal.lockBusy) {
// Only reachable when this impl ran without a live held handle — the
// outer section takes the file lock before anything else runs.
return {
state: "failed", changed: false, action: "failed",
retryable: true, message: "Another process is writing Codex configuration right now. Retry shortly.",
};
}
if (journal.unverified) {
return {
state: "failed", changed: false, action: "failed",
message: "Codex journal recovery was not verified; current configuration files and the journal were preserved.",
};
}
if (journal.profileRestoreFailed) {
return {
state: "failed", changed: false, action: "failed",
message: "Codex profile could not be restored; native files and the journal binding were preserved.",
};
}
assertCodexHomeOwner(getCodexHome());
const restored = journal.configRestored
? { success: true, message: "Codex config restored from opencodex journal.", retainedProviderTable: undefined as string[] | undefined }
: removeCodexConfig({
preserveProfile: journal.profileRestored || journal.profileChanged,
// The history question was resolved above; hand the answer down rather than making
// the transform re-derive it, which refused the explicit-removal path outright.
historyDisposition: disposition.kind === "stand-down"
? disposition.retainProviderTable ? "stand-down-retain" : "stand-down-remove"
: "refuse-on-any",
heldConfigWriteLock,
});
let retainedLines = restored.retainedProviderTable ?? null;
if (restored.success) {
// A successful journal/fallback write can race native history migration too.
// Refuse here while preimage compensation and the remove transaction can roll back.
// A stand-down observed now is the same stand-down that was already accounted for —
// it must not undo a routing removal that has already reached disk.
const settled = resolveRestoreHistoryDisposition(options.removeProviderTable);
if (settled.kind === "refuse") {
return { state: "failed", changed: false, action: "failed", message: `Codex configuration and journal preserved: ${settled.reason}.` };
}
// One re-attach covers three cases that all need the same bytes on disk: the journal
// path, which wrote a config without our table; the migration race, where the strip ran
// before anyone knew a table was needed; and the ordinary planned retention, where
// `removeCodexConfig` already put it back and this is a no-op. Re-attaching is
// idempotent — it checks for the table before appending — so the three do not have to
// be told apart here.
if (settled.kind === "stand-down" && settled.retainProviderTable && capturedBlock !== null) {
retainedLines = retainOcxProviderTableOnDisk(capturedBlock, heldConfigWriteLock) ?? retainedLines;
}
// All native work and the final migration check succeeded. A field-level
// fallback retains its snapshot, but no longer owns this Codex home.
publishCodexArtifact(JOURNAL_PATH, heldConfigWriteLock, (_path, hooks) => releaseJournalHomeBinding(hooks));
}
if (restored.success && retainedLines !== null) {
return {
state: "partial",
changed: true,
action: "routing-restored-provider-retained",
message: journal.configRestored
? "Codex config restored from opencodex journal. Kept [model_providers.opencodex] so conversations already"
+ " tagged opencodex still open; remove it with 'ocx restore --remove-codex-provider-table'"
+ " (those conversations stop opening)."
: restored.message,
retained: {
reason: HISTORY_RELABEL_STANDS_DOWN,
lines: retainedLines,
followUp: RETAINED_PROVIDER_TABLE_FOLLOW_UP,
},
};
}
return restored.success
? {
state: "ok",
changed: journal.configRestored || journal.profileRestored || journal.profileChanged || restored.message.startsWith("Removed"),
action: journal.configRestored ? "journal-restored" : "owned-fields-stripped",
message: restored.message,
}
: { state: "failed", changed: false, action: "failed", message: restored.message };
} catch (error) {
if (error instanceof CodexHomeOwnerRefusal) throw error;
return {
state: "failed", changed: false, action: "failed", message: error instanceof Error ? error.message : String(error),
...(error instanceof ConfigWriteContentChanged ? { retryable: true } : {}),
};
}
}
/** The catalog half, always inside its own K acquisition. */
/**
* The catalog half, always inside its own K acquisition.
*
* `journaledCatalogPath` must be captured by the CALLER, before the config half runs: a
* successful journal restore deletes the journal, and a config restore can remove
* `model_catalog_json`. Reading it here would be too late in both cases (#1798).
*/
function restoreCodexCatalogArtifact(
revalidateDesiredState: boolean,
journaledCatalogPath: string | null,
options: RestoreConfigOptions = {},
): CodexRestoreCatalogResult {
const owningCodexHome = getCodexHome();
try {
const restored = withCatalogWriteSerialization(owningCodexHome, permit => guardedRestoreWrite(options, () =>
revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())
? null
: restoreCodexCatalogWithPermit(permit, owningCodexHome, journaledCatalogPath)),
{ intent: "restore", writer: "codex-restore" });
return restored.kind === "completed" && restored.value !== null
? { state: "ok", changed: restored.value.removed > 0, ...restored.value, message: "Codex catalog restored." }
: restored.kind === "completed"
? {
state: "skipped", changed: false, removed: 0, kept: 0, path: null,
message: "Codex integration was re-enabled; native catalog restoration was skipped.",
}
: {
state: "failed", changed: false, removed: 0, kept: 0, path: DEFAULT_CATALOG_PATH,
message: `Codex catalog could not be restored: ${restored.reason}.`,
};
} catch (error) {
return {
state: "failed", changed: false, removed: 0, kept: 0, path: DEFAULT_CATALOG_PATH,
message: error instanceof Error ? error.message : String(error),
};
}
}
/**
* Restore native Codex, running history in a Worker under H.
*
* On a coordinated home the config/profile restore happens INSIDE the Codex
* write lock, publishing a `remove` transition — the same serialization inject
* uses. Without it, an older restore could overwrite a config a concurrent
* enable had just written under the lock, and then honestly report success
* while desired intent said ON. The desired-state re-read under the lock turns
* that lost race into the discriminated `desired_enabled` skip.
*/
export async function restoreNativeCodexAsync(
options: RestoreConfigOptions & { revalidateDesiredState?: boolean } = {},
): Promise<CodexNativeRestoreResult> {
if (codexHomeIsAbsent(getCodexHome())) return skippedRestoreEnvelope(true, "Codex config not found; no native restore was needed.");
const sibling = siblingRestoreSkip();
if (sibling) return sibling;
try {
assertCodexHomeOwner(getCodexHome());
const result = await restoreNativeCodexAsyncImpl(options);
return guardedRestoreWrite(options, () => finishApprovedProviderRestore(result, options.revalidateDesiredState));
} catch (error) {
if (error instanceof CodexHomeOwnerRefusal) return homeOwnerRestoreRefusal(error);
if (!(error instanceof CodexRestoreRefusal)) throw error;
return failedConfigRestoreEnvelope(error.config);
}
}
async function restoreNativeCodexAsyncImpl(
options: RestoreConfigOptions & { revalidateDesiredState?: boolean },
): Promise<CodexNativeRestoreResult> {
const activeProvider = currentExternalCodexModelProvider();
if (activeProvider) {
// External-provider courtesy: only the stale journal is removed. The
// history worker must not launch — it would turn a read-mostly courtesy
// result into a history mutation on a home we do not own.
guardedRestoreWrite(options, () => cleanExternalProviderJournal());
return externalProviderRestoreResult(activeProvider);
}
// `restore` normally honours a human request even when an unrelated
// service-manager probe is unavailable. A recorded FOREIGN home is not an
// unrelated probe: it is positive evidence another installation owns these
// native artifacts, so do not create profile/claim locks before refusing.
if (options.revalidateDesiredState) {
const ownership = inspectNativeCodexOwnership();
if (ownership.ownership === "foreign") return foreignOwnershipRestoreRefusal(ownership.reason);
if (shouldSyncCodexOnStart(loadConfig())) return desiredEnabledRestoreSkip();
}
const disposition = resolveRestoreHistoryDisposition(options.removeProviderTable);
if (disposition.kind === "refuse") return historyPreflightRefusalEnvelope(disposition.reason);
// A stand-down spawns no history Worker. The preflight the Worker would run first has
// already answered, and the rows stay tagged `opencodex` on purpose — which is exactly
// why the provider table has to survive the config half.
const historyStandsDown = disposition.kind === "stand-down";
const eligibility = codexWriteCoordinationEligibility({
coordinatorPath: () =>
resolveCodexCoordinatorDatabasePath(resolveEffectiveUserIdentity(), getCodexHome()),
residue: () => classifyNativeRoutedResidue(),
integrationRecord: () => readIntegrationRecord(),
});
// 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).
const journaledCatalogPath = journaledInjectedCatalogPath() ?? readCodexCatalogPath();
let config: CodexRestoreConfigResult;
let transitionReceipt: { nativeGeneration: number; currentTxId: string } | undefined;
if (eligibility.kind === "coordinated" || eligibility.kind === "adopt") {
/*
* File lock BEFORE N — the same order injection takes. With the config
* writes living inside the journal replay under the file lock, a restore
* that took N first while a sibling held the file lock was the one
* deliberate inversion; acquiring here first removes it.
*/
const configLock = await acquireConfigWriteLock(CODEX_CONFIG_PATH);
if (!configLock.ok) {
config = {
state: "failed",
changed: false,
action: "failed",
retryable: configLock.error === "locked", message: configWriteLockFailureMessage(configLock),
};
} else try {
beginCodexWriteSection(configLock.handle);
// The restore has no candidate bytes to witness; freshness comes from the
// filesystem reads and the desired-state re-read performed under the lock.
const witness = { authoritySnapshotId: "codex-native-restore" };
const coordinated = await withCodexWriteLock(
{
timeoutMs: DEFAULT_INJECT_LOCK_TIMEOUT_MS,
...(eligibility.kind === "adopt" ? { adoption: { direction: "remove" as const } } : {}),
admitted: witness,
readAdmissionUnderLock: () => witness,
},
(ctx) => guardedRestoreWrite(options, () => {
assertCodexHomeOwner(getCodexHome());
if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
throw new CodexWriteLockSkipped("desired_enabled");
}
const published = ctx.coordinator.beginTransition(
{
nativeGeneration: ctx.expectation.nativeBefore,
currentTxId: ctx.currentTxId,
},
{
txId: ctx.expectation.txId,
direction: "remove",
authoritySnapshotId: ctx.admission.authoritySnapshotId,
nextRetryAt: new Date().toISOString(),
},
);
if (published.kind !== "updated") {
throw new CodexWriteConflictError(
`The Codex transition could not be published: ${published.kind}.`,
);
}
const preImages = captureCodexPreImages();
let restored: CodexRestoreConfigResult;
try {
restored = restoreCodexConfigInline(eligibility.kind, options, configLock.handle);
// Throw inside N so the published remove transition rolls back too.
if (restored.state === "failed") throw new CodexRestoreRefusal(restored);
} catch (error) {
if (codexHomeOwnerBlocksCompensation(getCodexHome(), error)) throw error;
const compensated = restoreCodexPreImages(preImages, configLock.handle);
if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
throw error;
}
return {
config: restored,
preImages,
receipt: {
nativeGeneration: ctx.expectation.nativeAfter,
currentTxId: ctx.expectation.txId,
},
};
}),
);
if (coordinated.status === "skipped") return desiredEnabledRestoreSkip();
if (coordinated.status !== "acquired") {
config = {
state: "failed",
changed: false,
action: "failed",
message: coordinated.status === "busy"
? `Another process is writing Codex configuration right now (waited ${coordinated.waitedMs}ms). Retry shortly.`
: `Codex configuration was not restored: ${coordinated.message}`,
};
} else {
guardedRestoreWrite(options, () => recordCodexNativeTransactionProvenance(
coordinated.value.preImages,
coordinated.value.receipt.currentTxId,
));
config = coordinated.value.config;
transitionReceipt = coordinated.value.receipt;
}
} finally {
releaseConfigWriteLock(configLock.handle);
}
} else {
// Legacy-uncoordinated (or unresolvable) homes keep the unserialized path
// they have always had; restore is the escape hatch and must not strand
// them. The plain re-read still honors an intervening re-enable.
if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
return desiredEnabledRestoreSkip();
}
config = restoreCodexConfigInline(eligibility.kind, options);
}
if (config.state === "failed") return failedConfigRestoreEnvelope(config);
guardedRestoreWrite(options, () => notifyCatalogPublication({ kind: "native-released", path: journaledCatalogPath }));
const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath, options);
// Catalog failures are artifact results; a caller-policy refusal must also stop later work.
guardedRestoreWrite(options, () => {});
// Re-asked after the config half, because the store can paginate mid-transaction. Deciding
// the history job from the pre-write answer alone would spawn a Worker whose own preflight
// is now guaranteed to refuse, and report that refusal as a restore failure on a home that
// was in fact restored.
const historyStoodDown = historyStandsDown
|| resolveRestoreHistoryDisposition(options.removeProviderTable).kind === "stand-down";
const outcome: CodexHistoryJobOutcome = historyStoodDown
? { kind: "skipped" }
: await runCodexHistoryJob({
...resolveCodexHistoryJobTarget(),
...(options.revalidateDesiredState ? { expectedDesiredEnabled: false } : {}),
...(options.withWriteGuard ? { guardStopOwnership: true } : {}),
operation: deriveCodexHistoryOperation({ direction: "restore", resumeHistory: true, legacyMode: false }),
});
if (outcome.kind === "failed" && outcome.restoreBoundary) {
// Preserve the Worker's observed refusal even if the connection changes again
// before the parent resumes. The parent guard latches this typed boundary.
const boundary = outcome.restoreBoundary;
guardedRestoreWrite(options, () => { throw new StopRestoreOwnershipError(boundary); });
}
if (transitionReceipt) {
resolveCodexHistoryTransition(transitionReceipt, outcome);
}
const history: CodexRestoreHistoryResult = historyStoodDown
? {
state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0,
message: `Codex resume history was left to Codex's native writer (${HISTORY_RELABEL_STANDS_DOWN});`
+ " existing threads keep the provider they are tagged with and no rollout byte was read or written.",
}
: outcome.kind === "converged"
? {
state: "ok", changed: outcome.rows > 0 || outcome.files > 0, rows: outcome.rows, files: outcome.files, ejectedRows: 0,
message: outcome.rows > 0
? `Resume history metadata restored from opencodex backup (${outcome.rows} thread(s)); original providers preserved.`
: "No backed-up resume-history metadata was pending; untracked routed history was left unchanged.",
}
: outcome.kind === "skipped"
? { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message: "Codex resume history was skipped." }
: outcome.kind === "blocked" && (outcome.reason === "desired_disabled" || outcome.reason === "desired_enabled")
? {
state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0,
message: outcome.reason === "desired_disabled"
? "Codex integration was disabled; history restoration was skipped."
: "Codex integration was enabled; history restoration was skipped.",
}
: outcome.kind === "blocked" || outcome.kind === "failed"
? failedHistoryRestoreFromOutcome(outcome)
: failedHistoryRestore();
const base = catalog.removed > 0
? `${config.message} Catalog restored to ${catalog.kept} native model(s) (dropped ${catalog.removed} proxy-routed).`
: config.message;
const success = catalog.state !== "failed"
&& history.state !== "failed";
// A stood-down relabel is not a failure, but it is something the operator has to be told:
// their existing conversations keep the provider they are tagged with, and nothing will
// ever change that from this side. Printing only the config half would be the same
// partial-success-reported-as-success problem this change exists to end.
const historyNote = history.state === "failed"
? ` ⚠️ ${history.message}`
: historyStoodDown ? ` ${history.message}` : "";
return {
success,
message: `${base}${historyNote}`,
...(config.retained ? { retainedCodexProviderTable: config.retained } : {}),
artifacts: { config, catalog, history },
};
}
function homeOwnerRestoreRefusal(error: CodexHomeOwnerRefusal): CodexNativeRestoreResult {
return { ...skippedRestoreEnvelope(false, error.message), ownershipRefusal: error.reason };
}
export function restoreNativeCodex(
options: RestoreConfigOptions & { skipHistory?: boolean; revalidateDesiredState?: boolean } = {},
): CodexNativeRestoreResult {
if (codexHomeIsAbsent(getCodexHome())) return skippedRestoreEnvelope(true, "Codex config not found; no native restore was needed.");
const sibling = siblingRestoreSkip();
if (sibling) return sibling;
try {
assertCodexHomeOwner(getCodexHome());
const result = restoreNativeCodexImpl(options);
return guardedRestoreWrite(options, () => finishApprovedProviderRestore(result, options.revalidateDesiredState));
} catch (error) {
if (error instanceof CodexHomeOwnerRefusal) return homeOwnerRestoreRefusal(error);
throw error;
}
}
function restoreNativeCodexImpl(
options: RestoreConfigOptions & { skipHistory?: boolean; revalidateDesiredState?: boolean } = {},
): CodexNativeRestoreResult {
const activeProvider = currentExternalCodexModelProvider();
if (activeProvider) {
guardedRestoreWrite(options, () => cleanExternalProviderJournal());
return externalProviderRestoreResult(activeProvider);
}
if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
return desiredEnabledRestoreSkip();
}
const disposition = resolveRestoreHistoryDisposition(options.removeProviderTable);
if (disposition.kind === "refuse") return historyPreflightRefusalEnvelope(disposition.reason);
const historyStandsDown = disposition.kind === "stand-down";
// 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).
const journaledCatalogPath = journaledInjectedCatalogPath() ?? readCodexCatalogPath();
const config = restoreCodexConfigInline("sync", options);
if (config.state === "failed") return failedConfigRestoreEnvelope(config);
guardedRestoreWrite(options, () => notifyCatalogPublication({ kind: "native-released", path: journaledCatalogPath }));
// Same mid-transaction pagination re-check as the async path.
const historyStoodDown = historyStandsDown
|| resolveRestoreHistoryDisposition(options.removeProviderTable).kind === "stand-down";
const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath, options);
guardedRestoreWrite(options, () => {});
// Design B (loopback) steady state: threads are already tagged openai, so prove the
// no-op with a readonly probe instead of write-opening a DB the Codex app may hold
// (Windows: WAL writer lock -> seconds of stalling + a false warning on every stop).
// Legacy (non-loopback) installs keep the unconditional write-open restore.
let skipWhenProvablyNoop = false;
try {
skipWhenProvablyNoop = !shouldInjectApiAuthHeader(loadConfig());
} catch {
/* unreadable config: keep the conservative write-open restore */
}
// `skipHistory` is how the async wrapper takes this work for itself: the
// native files come down here, and history runs in the Worker under H.
let historyLockFailure: CodexRestoreHistoryResult | undefined;
const rawHistory = options.skipHistory || historyStoodDown
? { rows: 0, files: 0 }
: (() => {
const target = resolveCodexHistoryJobTarget();
const restore = () => syncCodexHistoryProvider("openai", target.canonicalStateDbPath, target.canonicalBackupPath, {
skipWhenProvablyNoop, withWriteGuard: options.withWriteGuard,
});
if (!options.withWriteGuard) return restore();
const locked = withHistoryWriteSerialization(target.canonicalCodexHome, target.canonicalStateDbPath, () =>
restore());
if (locked.kind === "completed") return locked.value;
// H availability says nothing about connection ownership; Grok must still clean up.
historyLockFailure = failedHistoryRestoreFromOutcome({ kind: "blocked", reason: locked.reason });
return { rows: 0, files: 0 };
})();
const history: CodexRestoreHistoryResult = historyStoodDown
? {
state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0,
message: `Codex resume history was left to Codex's native writer (${HISTORY_RELABEL_STANDS_DOWN});`
+ " existing threads keep the provider they are tagged with and no rollout byte was read or written.",
}
: options.skipHistory
? { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message: "History restoration runs asynchronously." }
: historyLockFailure ?? (rawHistory.failed
? failedHistoryRestore(rawHistory.failureReason, undefined, rawHistory)
: {
state: "ok",
changed: rawHistory.rows > 0 || rawHistory.files > 0 || (rawHistory.ejectedRows ?? 0) > 0,
rows: rawHistory.rows,
files: rawHistory.files,
ejectedRows: rawHistory.ejectedRows ?? 0,
message: rawHistory.rows > 0
? `Resume history metadata restored from opencodex backup (${rawHistory.rows} thread(s)); original providers preserved.`
: "No backed-up resume-history metadata was pending; untracked routed history was left unchanged.",
});
const message = catalog.removed > 0
? `${config.message} Catalog restored to ${catalog.kept} native model(s) (dropped ${catalog.removed} proxy-routed).`
: config.message;
return {
success: catalog.state !== "failed" && history.state !== "failed",
message: historyStoodDown ? `${message} ${history.message}` : message,
...(config.retained ? { retainedCodexProviderTable: config.retained } : {}),
artifacts: { config, catalog, history },
};
}