@wlv-zedd/dsh-chatgpt-web 1.0.0

package/src/codex-integration.ts

@@ -0,0 +1,529 @@
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { dirname } from "node:path";
+import type { AppConfig } from "./config";
+import { atomicWriteFile, getConfigPath, loadConfig, saveConfig } from "./config";
+import { installCodexInterruptHook, installCodexInterruptHookCommand } from "./codex-interrupt-hook";
+import {
+  CODEX_REALTIME_WEBRTC_CALL_BASE_URL,
+  getCodexConfigPath,
+  getCodexJournalPath,
+  getCodexJournalRecoveryPath,
+  getCodexModelsCachePath,
+  restoreFileSnapshot,
+  routeUrl,
+  sha256,
+  snapshotFile,
+  writeIntegrationState,
+} from "./codex-integration-shared";
+import type {
+  AnyCodexIntegrationJournal,
+  CodexIntegrationJournal,
+  InstallCodexIntegrationOptions,
+  LegacyCodexIntegrationJournalV4,
+  LegacyCodexIntegrationJournalV5,
+  LegacyCodexIntegrationJournalV6,
+  LegacyCodexIntegrationJournalV7,
+  LegacyCodexIntegrationJournalV8,
+  LegacyCodexIntegrationJournalV9,
+  SetCodexIntegrationActiveResult,
+  UninstallCodexIntegrationResult,
+} from "./codex-integration-shared";
+import { assertJournalTargetsConfig, readJournal } from "./codex-integration-journal";
+import {
+  findTopLevelAssignment,
+  installCompatibilityV1Features,
+  splitLines,
+  textFormat,
+} from "./codex-integration-document";
+import {
+  assertPreservedPreviousAssignments,
+  assertPreservedPreviousRealtimeAssignment,
+  installRoute,
+  managedJournalIsActive,
+  replacementBaseline,
+  restoreLegacyV2,
+  restoreManagedRoute,
+  verifyInstalledRoute,
+  verifyManagedJournalState,
+  verifyRestoredRoute,
+} from "./codex-integration-route";
+
+function installConfiguredRoute(
+  baseline: string,
+  installedUrl: string,
+  config: Pick<AppConfig, "subagentProtocol"> & (
+    Pick<AppConfig, "runtimeCommand"> | { interruptHookCommand: string }
+  ),
+  replaceExistingRoute: boolean,
+  replaceExistingRealtimeRoute: boolean,
+): {
+  text: string;
+  previous: CodexIntegrationJournal["previous"];
+  previousRealtimeWebrtcCallBaseUrl: CodexIntegrationJournal["previousRealtimeWebrtcCallBaseUrl"];
+  previousMultiAgent?: CodexIntegrationJournal["previousMultiAgent"];
+  previousMultiAgentV2?: CodexIntegrationJournal["previousMultiAgentV2"];
+  previousAgentMaxDepth?: CodexIntegrationJournal["previousAgentMaxDepth"];
+  installedAgentMaxDepth?: number;
+  interruptHook: CodexIntegrationJournal["interruptHook"];
+} {
+  const route = installRoute(
+    baseline,
+    installedUrl,
+    replaceExistingRoute,
+    replaceExistingRealtimeRoute,
+  );
+  const configured = config.subagentProtocol === "compatibility-v1"
+    ? (() => {
+        const features = installCompatibilityV1Features(route.text);
+        return {
+          text: features.text,
+          previous: route.previous,
+          previousRealtimeWebrtcCallBaseUrl: route.previousRealtimeWebrtcCallBaseUrl,
+          previousMultiAgent: features.previousMultiAgent,
+          previousMultiAgentV2: features.previousMultiAgentV2,
+          previousAgentMaxDepth: features.previousAgentMaxDepth,
+          installedAgentMaxDepth: features.installedAgentMaxDepth,
+        };
+      })()
+    : route;
+  const hook = "interruptHookCommand" in config
+    ? installCodexInterruptHookCommand(configured.text, getCodexConfigPath(), config.interruptHookCommand)
+    : installCodexInterruptHook(configured.text, getCodexConfigPath(), config);
+  return { ...configured, text: hook.text, interruptHook: hook.installed };
+}
+
+function journalProtocol(journal: Exclude<AnyCodexIntegrationJournal, { version: 2 }>): AppConfig["subagentProtocol"] {
+  return journal.version === 8 || journal.version === 9 || journal.version === 10
+    ? journal.installed.subagent_protocol
+    : "native";
+}
+
+export {
+  getCodexConfigPath,
+  getCodexHome,
+  getCodexJournalPath,
+  getCodexJournalRecoveryPath,
+  getCodexModelsCachePath,
+} from "./codex-integration-shared";
+export { readCodexModelContextOverride } from "./codex-integration-document";
+export type {
+  CodexIntegrationJournal,
+  CodexModelContextOverride,
+  InstallCodexIntegrationOptions,
+  SetCodexIntegrationActiveResult,
+  UninstallCodexIntegrationResult,
+} from "./codex-integration-shared";
+
+export function readCodexSubagentProtocol(
+  fallback: AppConfig["subagentProtocol"] = "compatibility-v1",
+): AppConfig["subagentProtocol"] {
+  const journal = readJournal();
+  return journal?.version === 8 || journal?.version === 9 || journal?.version === 10
+    ? journal.installed.subagent_protocol
+    : fallback;
+}
+
+export function setCodexSubagentProtocol(
+  config: AppConfig,
+  protocol: AppConfig["subagentProtocol"],
+): CodexIntegrationJournal {
+  const status = inspectCodexIntegration();
+  if (!status.installed) throw new Error("Codex integration is not installed; run setup first");
+  if (!status.active) {
+    throw new Error("Codex integration is disconnected; reconnect it before changing the subagent protocol");
+  }
+  const nextConfig = { ...config, subagentProtocol: protocol };
+  // The runtime catalog and Codex feature surface are two halves of one protocol selection. If
+  // either write fails, restore every participant so the next launcher/Codex restart cannot load a
+  // split V1/V2 state.
+  const snapshots = [
+    getConfigPath(),
+    getCodexConfigPath(),
+    getCodexModelsCachePath(),
+    getCodexJournalPath(),
+    getCodexJournalRecoveryPath(),
+  ].map(snapshotFile);
+  try {
+    const journal = installCodexIntegration(nextConfig);
+    saveConfig(nextConfig);
+    return journal;
+  } catch (error) {
+    const rollbackFailures: string[] = [];
+    for (const snapshot of [...snapshots].reverse()) {
+      try {
+        restoreFileSnapshot(snapshot);
+      } catch (rollbackError) {
+        rollbackFailures.push(
+          `${snapshot.path}: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`,
+        );
+      }
+    }
+    const primary = error instanceof Error ? error.message : String(error);
+    throw new Error(rollbackFailures.length > 0
+      ? `${primary}; subagent protocol rollback also failed: ${rollbackFailures.join("; ")}`
+      : primary);
+  }
+}
+
+export function preflightCodexIntegration(
+  config: AppConfig,
+  options: InstallCodexIntegrationOptions = {},
+): void {
+  const configPath = getCodexConfigPath();
+  const configExists = existsSync(configPath);
+  const currentText = configExists ? readFileSync(configPath, "utf8") : "";
+  const existing = readJournal();
+  const installedUrl = routeUrl(config);
+  if (existing) assertJournalTargetsConfig(existing, configPath);
+  if (existing && existing.version !== 2) {
+    if (!configExists) {
+      if (options.replaceExistingRoute !== true) {
+        throw new Error(`Codex config is missing: ${configPath}`);
+      }
+      installConfiguredRoute("", installedUrl, config, true, true);
+      return;
+    }
+    try {
+      verifyManagedJournalState(currentText, existing);
+    } catch (error) {
+      if (options.replaceExistingRoute !== true) throw error;
+      installConfiguredRoute(
+        replacementBaseline(currentText, configExists, existing),
+        installedUrl,
+        config,
+        true,
+        true,
+      );
+      return;
+    }
+    if (existing.version === 10) return;
+    const baseline = managedJournalIsActive(existing)
+      ? restoreManagedRoute(currentText, existing)
+      : currentText;
+    installConfiguredRoute(
+      baseline,
+      installedUrl,
+      config,
+      true,
+      options.replaceExistingRoute === true,
+    );
+    return;
+  }
+  let baseline = currentText;
+  if (existing?.version === 2) {
+    if (existsSync(existing.catalogPath) && sha256(readFileSync(existing.catalogPath)) !== existing.catalogSha256) {
+      throw new Error(`Managed legacy catalog changed after setup; refusing migration: ${existing.catalogPath}`);
+    }
+    baseline = restoreLegacyV2(currentText, existing);
+  }
+  installConfiguredRoute(
+    baseline,
+    installedUrl,
+    config,
+    options.replaceExistingRoute === true,
+    options.replaceExistingRoute === true,
+  );
+}
+export function installCodexIntegration(
+  config: AppConfig,
+  options: InstallCodexIntegrationOptions = {},
+): CodexIntegrationJournal {
+  const configPath = getCodexConfigPath();
+  mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
+  const configExists = existsSync(configPath);
+  const currentText = configExists ? readFileSync(configPath, "utf8") : "";
+  const existing = readJournal();
+  const installedUrl = routeUrl(config);
+  if (existing) assertJournalTargetsConfig(existing, configPath);
+
+  const hasManagedJournal = Boolean(existing && existing.version !== 2);
+  if (hasManagedJournal && !configExists && options.replaceExistingRoute !== true) {
+    throw new Error(`Codex config is missing: ${configPath}`);
+  }
+
+  if (hasManagedJournal && existing && existing.version !== 2) {
+    let baseline: string;
+    let preservePrevious = true;
+    try {
+      verifyManagedJournalState(currentText, existing);
+      baseline = managedJournalIsActive(existing)
+        ? restoreManagedRoute(currentText, existing)
+        : currentText;
+    } catch (error) {
+      if (options.replaceExistingRoute !== true) throw error;
+      baseline = replacementBaseline(currentText, configExists, existing);
+      preservePrevious = false;
+    }
+    const patched = installConfiguredRoute(
+      baseline,
+      installedUrl,
+      config,
+      true,
+      !preservePrevious || existing.version === 9 || existing.version === 10 || options.replaceExistingRoute === true,
+    );
+    if (preservePrevious) {
+      assertPreservedPreviousAssignments(patched.previous, existing.previous);
+      if (existing.version === 9 || existing.version === 10) {
+        assertPreservedPreviousRealtimeAssignment(
+          patched.previousRealtimeWebrtcCallBaseUrl,
+          existing.previousRealtimeWebrtcCallBaseUrl,
+        );
+      }
+    }
+    const updated: CodexIntegrationJournal = {
+      version: 10,
+      active: true,
+      configPath,
+      installed: {
+        openai_base_url: installedUrl,
+        experimental_realtime_webrtc_call_base_url: CODEX_REALTIME_WEBRTC_CALL_BASE_URL,
+        subagent_protocol: config.subagentProtocol,
+        ...(config.subagentProtocol === "compatibility-v1" ? {
+          agent_max_depth: patched.installedAgentMaxDepth,
+        } : {}),
+      },
+      previous: preservePrevious ? existing.previous : patched.previous,
+      previousRealtimeWebrtcCallBaseUrl: preservePrevious && (existing.version === 9 || existing.version === 10)
+        ? existing.previousRealtimeWebrtcCallBaseUrl
+        : patched.previousRealtimeWebrtcCallBaseUrl,
+      interruptHook: patched.interruptHook,
+      ...(config.subagentProtocol === "compatibility-v1" ? {
+        previousMultiAgent: patched.previousMultiAgent,
+        previousMultiAgentV2: patched.previousMultiAgentV2,
+        previousAgentMaxDepth: patched.previousAgentMaxDepth,
+      } : {}),
+      ...(existing.format ? { format: existing.format } : {}),
+    };
+    writeIntegrationState(updated, { path: configPath, data: patched.text }, [getCodexModelsCachePath()]);
+    return updated;
+  }
+
+  let baseline = currentText;
+  if (existing?.version === 2) {
+    if (existsSync(existing.catalogPath) && sha256(readFileSync(existing.catalogPath)) !== existing.catalogSha256) {
+      throw new Error(`Managed legacy catalog changed after setup; refusing migration: ${existing.catalogPath}`);
+    }
+    baseline = restoreLegacyV2(currentText, existing);
+  }
+  const patched = installConfiguredRoute(
+    baseline,
+    installedUrl,
+    config,
+    options.replaceExistingRoute === true,
+    options.replaceExistingRoute === true,
+  );
+  const journal: CodexIntegrationJournal = {
+    version: 10,
+    active: true,
+    configPath,
+    installed: {
+      openai_base_url: installedUrl,
+      experimental_realtime_webrtc_call_base_url: CODEX_REALTIME_WEBRTC_CALL_BASE_URL,
+      subagent_protocol: config.subagentProtocol,
+      ...(config.subagentProtocol === "compatibility-v1" ? {
+        agent_max_depth: patched.installedAgentMaxDepth,
+      } : {}),
+    },
+    previous: patched.previous,
+    previousRealtimeWebrtcCallBaseUrl: patched.previousRealtimeWebrtcCallBaseUrl,
+    interruptHook: patched.interruptHook,
+    ...(config.subagentProtocol === "compatibility-v1" ? {
+      previousMultiAgent: patched.previousMultiAgent,
+      previousMultiAgentV2: patched.previousMultiAgentV2,
+      previousAgentMaxDepth: patched.previousAgentMaxDepth,
+    } : {}),
+    format: textFormat(baseline),
+  };
+  writeIntegrationState(journal, { path: configPath, data: patched.text }, [getCodexModelsCachePath()]);
+  if (existing?.version === 2 && existsSync(existing.catalogPath)) rmSync(existing.catalogPath);
+  return journal;
+}
+
+export function deactivateCodexIntegration(): SetCodexIntegrationActiveResult {
+  const existing = readJournal();
+  if (!existing) return { changed: false, active: false };
+  if (existing.version === 2) {
+    throw new Error("Legacy Codex integration must be upgraded by Setup before the bridge can be disconnected");
+  }
+  assertJournalTargetsConfig(existing, getCodexConfigPath());
+  if (!existsSync(existing.configPath)) throw new Error(`Codex config is missing: ${existing.configPath}`);
+  const current = readFileSync(existing.configPath, "utf8");
+  if ((existing.version === 4 || existing.version === 5 || existing.version === 6 || existing.version === 7 || existing.version === 8 || existing.version === 9 || existing.version === 10) && !existing.active) {
+    verifyRestoredRoute(current, existing);
+    return { changed: false, active: false };
+  }
+  const restored = restoreManagedRoute(current, existing);
+  const disconnected:
+    | CodexIntegrationJournal
+    | LegacyCodexIntegrationJournalV9
+    | LegacyCodexIntegrationJournalV8
+    | LegacyCodexIntegrationJournalV6
+    | LegacyCodexIntegrationJournalV7
+    | LegacyCodexIntegrationJournalV5
+    | LegacyCodexIntegrationJournalV4 = existing.version === 6 || existing.version === 5
+      || existing.version === 7 || existing.version === 8 || existing.version === 9 || existing.version === 10
+      ? { ...existing, active: false }
+      : { ...existing, version: 4, active: false };
+  writeIntegrationState(disconnected, { path: existing.configPath, data: restored }, [getCodexModelsCachePath()]);
+  return { changed: true, active: false };
+}
+
+export function activateCodexIntegration(): SetCodexIntegrationActiveResult {
+  const existing = readJournal();
+  if (!existing) throw new Error("Codex integration is not installed");
+  if (existing.version === 2) {
+    throw new Error("Legacy Codex integration must be upgraded by Setup before the bridge can be reconnected");
+  }
+  assertJournalTargetsConfig(existing, getCodexConfigPath());
+  if (!existsSync(existing.configPath)) throw new Error(`Codex config is missing: ${existing.configPath}`);
+  const current = readFileSync(existing.configPath, "utf8");
+  if (existing.version === 10 && existing.active) {
+    verifyInstalledRoute(current, existing);
+    return { changed: false, active: true };
+  }
+  let baseline: string;
+  if ((existing.version === 4 || existing.version === 5 || existing.version === 6 || existing.version === 7 || existing.version === 8 || existing.version === 9 || existing.version === 10) && !existing.active) {
+    verifyRestoredRoute(current, existing);
+    baseline = current;
+  } else {
+    verifyInstalledRoute(current, existing);
+    baseline = restoreManagedRoute(current, existing);
+  }
+  const protocol = journalProtocol(existing);
+  const hookConfig = existing.version === 10
+    ? { interruptHookCommand: existing.interruptHook.command }
+    : { runtimeCommand: loadConfig().runtimeCommand };
+  const route = installConfiguredRoute(
+    baseline,
+    existing.installed.openai_base_url,
+    { subagentProtocol: protocol, ...hookConfig },
+    true,
+    existing.version === 9 || existing.version === 10,
+  );
+  assertPreservedPreviousAssignments(route.previous, existing.previous);
+  if (existing.version === 9 || existing.version === 10) {
+    assertPreservedPreviousRealtimeAssignment(
+      route.previousRealtimeWebrtcCallBaseUrl,
+      existing.previousRealtimeWebrtcCallBaseUrl,
+    );
+  }
+  const connected: CodexIntegrationJournal = {
+    version: 10,
+    active: true,
+    configPath: existing.configPath,
+    installed: {
+      openai_base_url: existing.installed.openai_base_url,
+      experimental_realtime_webrtc_call_base_url: CODEX_REALTIME_WEBRTC_CALL_BASE_URL,
+      subagent_protocol: protocol,
+      ...(protocol === "compatibility-v1" ? {
+        agent_max_depth: route.installedAgentMaxDepth,
+      } : {}),
+    },
+    previous: existing.previous,
+    previousRealtimeWebrtcCallBaseUrl: existing.version === 9 || existing.version === 10
+      ? existing.previousRealtimeWebrtcCallBaseUrl
+      : route.previousRealtimeWebrtcCallBaseUrl,
+    interruptHook: route.interruptHook,
+    ...(protocol === "compatibility-v1" ? {
+      previousMultiAgent: route.previousMultiAgent,
+      previousMultiAgentV2: route.previousMultiAgentV2,
+      previousAgentMaxDepth: route.previousAgentMaxDepth,
+    } : {}),
+    ...(existing.format ? { format: existing.format } : {}),
+  };
+  writeIntegrationState(connected, { path: existing.configPath, data: route.text }, [getCodexModelsCachePath()]);
+  return { changed: true, active: true };
+}
+
+export function uninstallCodexIntegration(): UninstallCodexIntegrationResult {
+  const journal = readJournal();
+  if (!journal) return { changed: false };
+  if (!existsSync(journal.configPath)) throw new Error(`Codex config is missing: ${journal.configPath}`);
+  const current = readFileSync(journal.configPath, "utf8");
+  let restored: string;
+  if (journal.version === 2) {
+    if (existsSync(journal.catalogPath) && sha256(readFileSync(journal.catalogPath)) !== journal.catalogSha256) {
+      throw new Error(`Managed legacy catalog changed after setup: ${journal.catalogPath}`);
+    }
+    restored = restoreLegacyV2(current, journal);
+  } else if ((journal.version === 4 || journal.version === 5 || journal.version === 6 || journal.version === 7 || journal.version === 8 || journal.version === 9 || journal.version === 10) && !journal.active) {
+    verifyRestoredRoute(current, journal);
+    restored = current;
+  } else {
+    restored = restoreManagedRoute(current, journal);
+  }
+  const configSnapshot = snapshotFile(journal.configPath);
+  const catalogSnapshot = journal.version === 2 ? snapshotFile(journal.catalogPath) : undefined;
+  const modelsCacheSnapshot = snapshotFile(getCodexModelsCachePath());
+  const journalSnapshot = snapshotFile(getCodexJournalPath());
+  const recoverySnapshot = snapshotFile(getCodexJournalRecoveryPath());
+  try {
+    atomicWriteFile(journal.configPath, restored);
+    if (catalogSnapshot?.exists) rmSync(catalogSnapshot.path);
+    rmSync(modelsCacheSnapshot.path, { force: true });
+    rmSync(getCodexJournalPath(), { force: true });
+    rmSync(getCodexJournalRecoveryPath(), { force: true });
+  } catch (error) {
+    const rollbackFailures: string[] = [];
+    for (const snapshot of [recoverySnapshot, journalSnapshot, modelsCacheSnapshot, catalogSnapshot, configSnapshot]) {
+      if (!snapshot) continue;
+      try {
+        restoreFileSnapshot(snapshot);
+      } catch (caught) {
+        rollbackFailures.push(`${snapshot.path}: ${caught instanceof Error ? caught.message : String(caught)}`);
+      }
+    }
+    const primary = error instanceof Error ? error.message : String(error);
+    throw new Error(rollbackFailures.length > 0
+      ? `${primary}; Codex integration rollback also failed: ${rollbackFailures.join("; ")}`
+      : primary);
+  }
+  return { changed: true };
+}
+
+export function inspectCodexIntegration(): {
+  installed: boolean;
+  active: boolean;
+  configPath: string;
+  routeUrl?: string;
+  journal?: AnyCodexIntegrationJournal;
+  errors: string[];
+} {
+  const journal = readJournal();
+  const errors: string[] = [];
+  if (journal) {
+    try {
+      assertJournalTargetsConfig(journal, getCodexConfigPath());
+      const text = readFileSync(journal.configPath, "utf8");
+      if ((journal.version === 4 || journal.version === 5 || journal.version === 6 || journal.version === 7 || journal.version === 8 || journal.version === 9 || journal.version === 10) && !journal.active) {
+        verifyRestoredRoute(text, journal);
+      }
+      else if (journal.version === 3 || journal.version === 4 || journal.version === 5 || journal.version === 6 || journal.version === 7 || journal.version === 8 || journal.version === 9 || journal.version === 10) {
+        verifyInstalledRoute(text, journal);
+      }
+      else {
+        const lines = splitLines(text);
+        for (const key of ["model_provider", "model_catalog_json"] as const) {
+          if (findTopLevelAssignment(lines, key).value !== journal.installed[key]) {
+            errors.push(`Codex ${key} no longer matches this installation`);
+          }
+        }
+        if (!text.includes(journal.providerBlock)) errors.push("Managed legacy Codex provider block no longer matches this installation");
+      }
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return {
+    installed: Boolean(journal),
+    active: journal?.version === 4 || journal?.version === 5 || journal?.version === 6 || journal?.version === 7 || journal?.version === 8 || journal?.version === 9 || journal?.version === 10
+      ? journal.active
+      : Boolean(journal),
+    configPath: getCodexConfigPath(),
+    ...(journal?.version === 3 || journal?.version === 4 || journal?.version === 5 || journal?.version === 6 || journal?.version === 7 || journal?.version === 8 || journal?.version === 9 || journal?.version === 10
+      ? { routeUrl: journal.installed.openai_base_url }
+      : {}),
+    ...(journal ? { journal } : {}),
+    errors,
+  };
+}

package/src/codex-interrupt-hook.ts

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, posix, resolve, win32 } from "node:path";
+import type { AppConfig } from "./config";
+import { getConfigDir } from "./config";
+import type { InstalledCodexInterruptHook } from "./codex-integration-shared";
+
+export const MANAGED_INTERRUPT_HOOK_START =
+  "# Managed by codex-chatgpt-web: release the exact Responses request when its Codex turn is interrupted.";
+export const MANAGED_INTERRUPT_HOOK_END =
+  "# End codex-chatgpt-web interrupt lifecycle hook.";
+
+function canonicalJson(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalJson);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => [key, canonicalJson(item)]),
+  );
+}
+
+/** Match codex_config::version_for_toml for the normalized Interrupt command hook. */
+export function codexInterruptHookHash(command: string): string {
+  const identity = canonicalJson({
+    event_name: "interrupt",
+    hooks: [{
+      type: "command",
+      command,
+      timeout: 3,
+      async: false,
+    }],
+  });
+  return `sha256:${createHash("sha256").update(JSON.stringify(identity)).digest("hex")}`;
+}
+
+function posixShellArgument(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+function cmdShellArgument(value: string): string {
+  if (value.includes('"') || /[\r\n]/.test(value)) {
+    throw new Error("Codex interrupt hook command contains an invalid Windows path character");
+  }
+  // Codex executes command hooks through cmd.exe /C on Windows. Quoting every argument preserves
+  // spaces and shell metacharacters in the installed runtime path.
+  return `"${value}"`;
+}
+
+export function codexInterruptHookCommand(
+  config: Pick<AppConfig, "runtimeCommand">,
+  home = getConfigDir(),
+  platform: NodeJS.Platform = process.platform,
+): string {
+  const absoluteHome = platform === "win32" ? win32.resolve(home) : posix.resolve(home);
+  const args = [...config.runtimeCommand, "--home", absoluteHome, "hook", "interrupt"];
+  return args.map(platform === "win32" ? cmdShellArgument : posixShellArgument).join(" ");
+}
+
+function lineEnding(text: string): "\n" | "\r\n" | "\r" {
+  return text.includes("\r\n") ? "\r\n" : text.includes("\n") ? "\n" : text.includes("\r") ? "\r" : "\n";
+}
+
+function interruptGroupCount(text: string): number {
+  return text.split(/\r\n|\n|\r/).filter(line => /^\s*\[\[hooks\.Interrupt\]\]\s*(?:#.*)?$/.test(line)).length;
+}
+
+function managedMarkerCount(text: string): number {
+  return text.split(MANAGED_INTERRUPT_HOOK_START).length - 1;
+}
+
+function canonicalConfigPath(configPath: string): string {
+  const absolute = resolve(configPath);
+  try {
+    return realpathSync.native(absolute);
+  } catch {
+    try {
+      return join(realpathSync.native(dirname(absolute)), basename(absolute));
+    } catch {
+      return absolute;
+    }
+  }
+}
+
+export function installCodexInterruptHook(
+  text: string,
+  configPath: string,
+  config: Pick<AppConfig, "runtimeCommand">,
+): { text: string; installed: InstalledCodexInterruptHook } {
+  return installCodexInterruptHookCommand(text, configPath, codexInterruptHookCommand(config));
+}
+
+export function installCodexInterruptHookCommand(
+  text: string,
+  configPath: string,
+  command: string,
+): { text: string; installed: InstalledCodexInterruptHook } {
+  if (managedMarkerCount(text) !== 0 || text.includes(MANAGED_INTERRUPT_HOOK_END)) {
+    throw new Error("Codex config already contains a codex-chatgpt-web interrupt hook marker");
+  }
+  const groupIndex = interruptGroupCount(text);
+  const stateKey = `${canonicalConfigPath(configPath)}:interrupt:${groupIndex}:0`;
+  const trustedHash = codexInterruptHookHash(command);
+  const ending = lineEnding(text);
+  const core = [
+    MANAGED_INTERRUPT_HOOK_START,
+    "[[hooks.Interrupt]]",
+    "",
+    "[[hooks.Interrupt.hooks]]",
+    'type = "command"',
+    `command = ${JSON.stringify(command)}`,
+    "timeout = 3",
+    "",
+    `[hooks.state.${JSON.stringify(stateKey)}]`,
+    `trusted_hash = ${JSON.stringify(trustedHash)}`,
+    MANAGED_INTERRUPT_HOOK_END,
+  ].join(ending);
+  const leading = text.length === 0
+    ? ""
+    : text.endsWith(`${ending}${ending}`)
+      ? ""
+      : text.endsWith(ending)
+        ? ending
+        : `${ending}${ending}`;
+  const trailing = text.length > 0 && text.endsWith(ending) ? ending : "";
+  const fragment = `${leading}${core}${trailing}`;
+  return {
+    text: `${text}${fragment}`,
+    installed: { command, groupIndex, stateKey, trustedHash, fragment },
+  };
+}
+
+export function verifyCodexInterruptHook(text: string, installed: InstalledCodexInterruptHook): void {
+  const first = text.indexOf(installed.fragment);
+  if (first < 0 || text.indexOf(installed.fragment, first + installed.fragment.length) >= 0) {
+    throw new Error("Codex interrupt lifecycle hook changed after setup; refusing to overwrite it");
+  }
+  if (interruptGroupCount(text.slice(0, first)) !== installed.groupIndex) {
+    throw new Error("Codex interrupt lifecycle hook order changed after setup; refusing to overwrite it");
+  }
+  if (managedMarkerCount(text) !== 1 || !text.includes(MANAGED_INTERRUPT_HOOK_END)) {
+    throw new Error("Codex interrupt lifecycle hook markers changed after setup; refusing to overwrite them");
+  }
+  if (codexInterruptHookHash(installed.command) !== installed.trustedHash) {
+    throw new Error("Codex interrupt lifecycle hook journal hash is invalid");
+  }
+}
+
+export function restoreCodexInterruptHook(text: string, installed: InstalledCodexInterruptHook): string {
+  verifyCodexInterruptHook(text, installed);
+  return text.replace(installed.fragment, "");
+}
+
+export function verifyCodexInterruptHookRestored(text: string): void {
+  if (managedMarkerCount(text) !== 0 || text.includes(MANAGED_INTERRUPT_HOOK_END)) {
+    throw new Error("Codex interrupt lifecycle hook is present while the bridge is disconnected");
+  }
+}