@codextheme/cli 0.2.0 → 0.2.1

package/README.md

@@ -5,22 +5,22 @@ Fixed-version, one-command curated and private custom skins for Codex Desktop on
 Apply a catalog skin:
 
 ```sh
-npx --yes @codextheme/cli@0.2.0 apply cathedral-nocturne
+npx --yes @codextheme/cli@0.2.1 apply cathedral-nocturne
 ```
 
 The custom skin studio at [codextheme.tech](https://codextheme.tech) creates an expiring private command:
 
 ```sh
-npx --yes @codextheme/cli@0.2.0 apply-private <private-id>
+npx --yes @codextheme/cli@0.2.1 apply-private <private-id>
 ```
 
 Private packages are downloaded only from the fixed `https://codextheme.tech` origin, bounded, integrity-checked, schema-validated, safety-linted, and cached locally with owner-only permissions. The temporary server link expires after 24 hours; `reapply` uses the validated local cache and works after that link expires.
 
 ```sh
-npx --yes @codextheme/cli@0.2.0 reapply
-npx --yes @codextheme/cli@0.2.0 restore
+npx --yes @codextheme/cli@0.2.1 reapply
+npx --yes @codextheme/cli@0.2.1 restore
 ```
 
-The CLI has no install scripts, does not use `sudo`, and does not modify the Codex application bundle. Requirements: macOS, Node.js 22.4+, and Codex Desktop. A running Codex process is never closed or reopened without an explicit `y` confirmation.
+The CLI has no install scripts, does not use `sudo`, and does not modify the Codex application bundle. Requirements: macOS, Node.js 22.4+, and Codex Desktop. A running Codex process is never closed or reopened without an explicit `y` confirmation. After confirmation, version 0.2.1 uses an owner-only detached one-shot worker so an apply started inside Codex survives that restart; it does not install a persistent service.
 
 CodexTheme is an independent project and is not affiliated with or endorsed by OpenAI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codextheme/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "One-command curated and private custom skins for Codex Desktop on macOS.",
   "type": "module",
   "license": "Apache-2.0",

package/src/handoff-runner.mjs

@@ -0,0 +1,146 @@
+import { execFile } from "node:child_process";
+import { applyPrivateTheme, applyTheme } from "./lifecycle.mjs";
+
+const PUBLIC_FAILURES = new Map([
+  ["E_CODEX_NOT_FOUND", "没有找到已安装的 Codex Desktop。"],
+  ["E_DOM_INCOMPATIBLE", "当前 Codex 界面结构与该主题暂不兼容。"],
+  ["E_CORE_VERIFY", "主题应用后的完整性验证失败。"],
+  ["E_PRIVATE_CACHE", "无法安全读取本地私有主题缓存。"],
+  ["E_RESTORE_FAILED", "主题应用失败，且未能完整恢复 Codex 官方外观。"],
+  ["E_HANDOFF_BUSY", "已有一个 Codex 重启任务正在处理。"],
+  ["E_HANDOFF_FAILED", "CodexTheme 未能完成后台主题应用。"],
+]);
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+export async function waitForProcessExit(
+  pid,
+  { isAlive = processIsAlive, wait = delay, timeoutMs = 10000, pollMs = 100 } = {},
+) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) {
+    throw Object.assign(new Error("Invalid handoff parent process."), { code: "E_HANDOFF_FAILED" });
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isAlive(pid)) return;
+    await wait(pollMs);
+  }
+  throw Object.assign(new Error("Foreground CLI did not exit before handoff."), { code: "E_HANDOFF_FAILED" });
+}
+
+export async function notifyHandoff(status, { execFileApi = execFile } = {}) {
+  const message = status === "success"
+    ? "Theme applied. Codex has reopened."
+    : "Theme apply failed. Open CodexTheme Help for recovery steps.";
+  const script = `display notification ${JSON.stringify(message)} with title "CodexTheme"`;
+  await new Promise((resolve) => {
+    execFileApi("/usr/bin/osascript", ["-e", script], () => resolve());
+  });
+}
+
+function publicFailure(error) {
+  const code = PUBLIC_FAILURES.has(error?.code) ? error.code : "E_HANDOFF_FAILED";
+  return { code, message: PUBLIC_FAILURES.get(code) };
+}
+
+export function validateWorkerInvocation(argv, pendingPath) {
+  if (!Array.isArray(argv) || argv.length !== 2 || argv[0] !== pendingPath || !/^[1-9][0-9]*$/.test(argv[1])) {
+    throw Object.assign(new Error("Invalid handoff worker invocation."), { code: "E_HANDOFF_FAILED" });
+  }
+  const parentPid = Number(argv[1]);
+  if (!Number.isSafeInteger(parentPid)) {
+    throw Object.assign(new Error("Invalid handoff worker invocation."), { code: "E_HANDOFF_FAILED" });
+  }
+  return parentPid;
+}
+
+async function applyJob({ job, lifecycle, cache, runtime, stateStore, now, onApplyStart }) {
+  const shared = {
+    runtime,
+    stateStore,
+    promptRestart: async () => true,
+    now,
+  };
+  if (job.action.source === "catalog") {
+    onApplyStart();
+    return lifecycle.applyTheme({ ...shared, slug: job.action.themeSlug });
+  }
+  const bundle = JSON.parse(await cache.read(job.action.cacheKey));
+  onApplyStart();
+  return lifecycle.applyPrivateTheme({
+    ...shared,
+    bundle,
+    cacheKey: job.action.cacheKey,
+  });
+}
+
+export async function runHandoffJob({
+  store,
+  runtime,
+  stateStore,
+  cache,
+  lifecycle = { applyTheme, applyPrivateTheme },
+  waitForParentExit = waitForProcessExit,
+  settleAfterParentExit = () => delay(1500),
+  notify = notifyHandoff,
+  now = () => new Date(),
+}) {
+  let exitCode = 1;
+  let applyStarted = false;
+  try {
+    const job = await store.readPending();
+    await waitForParentExit(job.parentPid);
+    await settleAfterParentExit();
+    await applyJob({
+      job,
+      lifecycle,
+      cache,
+      runtime,
+      stateStore,
+      now,
+      onApplyStart: () => { applyStarted = true; },
+    });
+    await store.writeResult({
+      schemaVersion: 1,
+      status: "success",
+      completedAt: now().toISOString(),
+      message: "主题已应用并通过验证。",
+    });
+    await notify("success").catch(() => {});
+    exitCode = 0;
+  } catch (error) {
+    let recovered = !applyStarted;
+    if (applyStarted) {
+      try {
+        const recovery = await runtime.recover();
+        recovered = recovery?.recovered === true;
+      } catch { /* The sanitized result below records failed recovery. */ }
+    }
+    const failure = publicFailure(error);
+    try {
+      await store.writeResult({
+        schemaVersion: 1,
+        status: "failure",
+        completedAt: now().toISOString(),
+        code: failure.code,
+        message: failure.message,
+        recovered,
+      });
+    } catch { /* Notification still gives the user a recovery signal. */ }
+    await notify("failure").catch(() => {});
+  } finally {
+    await store.removePending().catch(() => {});
+  }
+  return exitCode;
+}

package/src/handoff-worker.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { createPrivateCache } from "./cache.mjs";
+import { createHandoffStore } from "./handoff.mjs";
+import { runHandoffJob, validateWorkerInvocation } from "./handoff-runner.mjs";
+import { runtime } from "./runtime.mjs";
+import { createStateStore } from "./state.mjs";
+
+const store = createHandoffStore();
+
+try {
+  const parentPid = validateWorkerInvocation(process.argv.slice(2), store.pendingPath);
+  const pending = await store.readPending();
+  if (pending.parentPid !== parentPid) {
+    throw Object.assign(new Error("Handoff parent mismatch."), { code: "E_HANDOFF_FAILED" });
+  }
+  process.exitCode = await runHandoffJob({
+    store,
+    runtime,
+    stateStore: createStateStore(),
+    cache: createPrivateCache(),
+  });
+} catch {
+  process.exitCode = 1;
+}

package/src/handoff.mjs

@@ -0,0 +1,223 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SAFE_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SAFE_CACHE_KEY = /^[a-f0-9]{64}$/;
+const MAX_PENDING_AGE_MS = 5 * 60 * 1000;
+
+function handoffError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function exactKeys(value, keys) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+
+function cleanAction(value) {
+  if (
+    exactKeys(value, ["schemaVersion", "source", "themeSlug"])
+    && value.schemaVersion === 2
+    && value.source === "catalog"
+    && typeof value.themeSlug === "string"
+    && SAFE_SLUG.test(value.themeSlug)
+  ) {
+    return { source: "catalog", themeSlug: value.themeSlug };
+  }
+  if (
+    exactKeys(value, ["schemaVersion", "source", "cacheKey"])
+    && value.schemaVersion === 2
+    && value.source === "private"
+    && typeof value.cacheKey === "string"
+    && SAFE_CACHE_KEY.test(value.cacheKey)
+  ) {
+    return { source: "private", cacheKey: value.cacheKey };
+  }
+  throw handoffError("E_HANDOFF_FAILED", "无法创建安全的 Codex 重启任务。");
+}
+
+function cleanStoredAction(value) {
+  if (value?.source === "catalog" && exactKeys(value, ["source", "themeSlug"])) {
+    return cleanAction({ schemaVersion: 2, ...value });
+  }
+  if (value?.source === "private" && exactKeys(value, ["source", "cacheKey"])) {
+    return cleanAction({ schemaVersion: 2, ...value });
+  }
+  throw handoffError("E_HANDOFF_FAILED", "本地 Codex 重启任务无效。");
+}
+
+function cleanJob(value) {
+  if (
+    !exactKeys(value, ["schemaVersion", "createdAt", "parentPid", "action"])
+    || value.schemaVersion !== 1
+    || typeof value.createdAt !== "string"
+    || !Number.isFinite(Date.parse(value.createdAt))
+    || !Number.isSafeInteger(value.parentPid)
+    || value.parentPid <= 0
+  ) {
+    throw handoffError("E_HANDOFF_FAILED", "本地 Codex 重启任务无效。");
+  }
+  const action = cleanStoredAction(value.action);
+  return {
+    schemaVersion: 1,
+    createdAt: value.createdAt,
+    parentPid: value.parentPid,
+    action,
+  };
+}
+
+function cleanResult(value) {
+  if (
+    value?.schemaVersion !== 1
+    || !["success", "failure"].includes(value.status)
+    || typeof value.completedAt !== "string"
+    || !Number.isFinite(Date.parse(value.completedAt))
+    || typeof value.message !== "string"
+    || !value.message
+  ) {
+    throw handoffError("E_HANDOFF_FAILED", "Codex 重启任务结果无效。");
+  }
+  if (value.status === "success" && exactKeys(value, ["schemaVersion", "status", "completedAt", "message"])) {
+    return { schemaVersion: 1, status: "success", completedAt: value.completedAt, message: value.message };
+  }
+  if (
+    value.status === "failure"
+    && exactKeys(value, ["schemaVersion", "status", "completedAt", "code", "message", "recovered"])
+    && typeof value.code === "string"
+    && /^E_[A-Z0-9_]+$/.test(value.code)
+    && typeof value.recovered === "boolean"
+  ) {
+    return {
+      schemaVersion: 1,
+      status: "failure",
+      completedAt: value.completedAt,
+      code: value.code,
+      message: value.message,
+      recovered: value.recovered,
+    };
+  }
+  throw handoffError("E_HANDOFF_FAILED", "Codex 重启任务结果无效。");
+}
+
+async function ensureDirectory(directory, fsApi) {
+  await fsApi.mkdir(directory, { recursive: true, mode: 0o700 });
+  await fsApi.chmod(directory, 0o700);
+}
+
+async function createExclusive(filename, serialized, fsApi) {
+  const temporary = `${filename}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await fsApi.writeFile(temporary, serialized, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await fsApi.link(temporary, filename);
+    await fsApi.chmod(filename, 0o600);
+  } finally {
+    await fsApi.rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+async function replaceFile(filename, serialized, fsApi) {
+  const temporary = `${filename}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await fsApi.writeFile(temporary, serialized, { encoding: "utf8", mode: 0o600 });
+    await fsApi.rename(temporary, filename);
+    await fsApi.chmod(filename, 0o600);
+  } finally {
+    await fsApi.rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+export function createHandoffStore({ home = os.homedir(), fsApi = fs, now = () => new Date() } = {}) {
+  const directory = path.join(home, "Library", "Application Support", "codextheme", "handoff");
+  const pendingPath = path.join(directory, "pending.json");
+  const resultPath = path.join(directory, "last-result.json");
+
+  return {
+    directory,
+    pendingPath,
+    resultPath,
+
+    async createPending(action, parentPid) {
+      const createdAt = now().toISOString();
+      const job = cleanJob({ schemaVersion: 1, createdAt, parentPid, action: cleanAction(action) });
+      await ensureDirectory(directory, fsApi);
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+          await createExclusive(pendingPath, `${JSON.stringify(job, null, 2)}\n`, fsApi);
+          return job;
+        } catch (error) {
+          if (error?.code !== "EEXIST") {
+            if (String(error?.code ?? "").startsWith("E_HANDOFF_")) throw error;
+            throw handoffError("E_HANDOFF_FAILED", "无法写入本地 Codex 重启任务。");
+          }
+          let existing;
+          try {
+            existing = await this.readPending();
+          } catch {
+            throw handoffError("E_HANDOFF_BUSY", "已有一个 Codex 重启任务正在处理。");
+          }
+          if (now().getTime() - Date.parse(existing.createdAt) <= MAX_PENDING_AGE_MS) {
+            throw handoffError("E_HANDOFF_BUSY", "已有一个 Codex 重启任务正在处理。");
+          }
+          await fsApi.rm(pendingPath, { force: true });
+        }
+      }
+      throw handoffError("E_HANDOFF_BUSY", "已有一个 Codex 重启任务正在处理。");
+    },
+
+    async readPending() {
+      try {
+        return cleanJob(JSON.parse(await fsApi.readFile(pendingPath, "utf8")));
+      } catch (error) {
+        if (String(error?.code ?? "").startsWith("E_HANDOFF_")) throw error;
+        throw handoffError("E_HANDOFF_FAILED", "无法安全读取本地 Codex 重启任务。");
+      }
+    },
+
+    async writeResult(value) {
+      const result = cleanResult(value);
+      await ensureDirectory(directory, fsApi);
+      await replaceFile(resultPath, `${JSON.stringify(result, null, 2)}\n`, fsApi);
+      return result;
+    },
+
+    async removePending() {
+      await fsApi.rm(pendingPath, { force: true });
+    },
+  };
+}
+
+export function createRestartHandoff({
+  home = os.homedir(),
+  fsApi = fs,
+  now = () => new Date(),
+  spawnProcess = spawn,
+  execPath = process.execPath,
+  workerPath = fileURLToPath(new URL("./handoff-worker.mjs", import.meta.url)),
+  parentPid = process.pid,
+} = {}) {
+  const store = createHandoffStore({ home, fsApi, now });
+  return {
+    store,
+    async schedule(action) {
+      await store.createPending(action, parentPid);
+      try {
+        const child = spawnProcess(
+          execPath,
+          [workerPath, store.pendingPath, String(parentPid)],
+          { detached: true, stdio: "ignore" },
+        );
+        if (!child || typeof child.unref !== "function") throw new Error("invalid child");
+        child.unref();
+      } catch {
+        await store.removePending().catch(() => {});
+        throw handoffError("E_HANDOFF_FAILED", "无法启动独立的 Codex 重启任务。");
+      }
+      return { queued: true, resultPath: store.resultPath };
+    },
+  };
+}

package/src/lifecycle.mjs

@@ -32,7 +32,15 @@ async function requireRestartConsent(promptRestart) {
   }
 }
 
-async function applyResolvedTheme({ theme, nextState, runtime, stateStore, promptRestart, now }) {
+async function delegateRestart({ theme, nextState, restartHandoff }) {
+  return {
+    theme,
+    handoff: await restartHandoff.schedule(nextState),
+    appliedAt: null,
+  };
+}
+
+async function applyResolvedTheme({ theme, nextState, runtime, stateStore, promptRestart, restartHandoff, now }) {
   let detection;
   try {
     detection = await runtime.detect();
@@ -46,6 +54,7 @@ async function applyResolvedTheme({ theme, nextState, runtime, stateStore, promp
   let restartExisting = false;
   if (detection.running && !detection.ready) {
     await requireRestartConsent(promptRestart);
+    if (restartHandoff) return delegateRestart({ theme, nextState, restartHandoff });
     restartExisting = true;
   }
 
@@ -55,6 +64,7 @@ async function applyResolvedTheme({ theme, nextState, runtime, stateStore, promp
   } catch (error) {
     if (error?.code === "CODEDROBE_RESTART_REQUIRED" && !restartExisting) {
       await requireRestartConsent(promptRestart);
+      if (restartHandoff) return delegateRestart({ theme, nextState, restartHandoff });
       restartExisting = true;
       try {
         result = await runtime.apply({ theme, restartExisting });
@@ -75,7 +85,7 @@ async function applyResolvedTheme({ theme, nextState, runtime, stateStore, promp
   return { theme, result, appliedAt };
 }
 
-export async function applyTheme({ slug, runtime, stateStore, promptRestart, now = () => new Date() }) {
+export async function applyTheme({ slug, runtime, stateStore, promptRestart, restartHandoff, now = () => new Date() }) {
   let theme;
   try {
     theme = await runtime.loadTheme(slug);
@@ -88,11 +98,12 @@ export async function applyTheme({ slug, runtime, stateStore, promptRestart, now
     runtime,
     stateStore,
     promptRestart,
+    restartHandoff,
     now,
   });
 }
 
-export async function applyPrivateTheme({ bundle, cacheKey, runtime, stateStore, promptRestart, now = () => new Date() }) {
+export async function applyPrivateTheme({ bundle, cacheKey, runtime, stateStore, promptRestart, restartHandoff, now = () => new Date() }) {
   let theme;
   try {
     theme = await runtime.loadThemeBundle(bundle);
@@ -105,6 +116,7 @@ export async function applyPrivateTheme({ bundle, cacheKey, runtime, stateStore,
     runtime,
     stateStore,
     promptRestart,
+    restartHandoff,
     now,
   });
 }

package/src/main.mjs

@@ -1,14 +1,15 @@
 import { CATALOG, getCatalogEntry } from "./catalog.mjs";
 import { createPrivateCache } from "./cache.mjs";
+import { createRestartHandoff } from "./handoff.mjs";
 import { applyPrivateTheme, applyTheme, CliError, reapplyTheme, restoreTheme } from "./lifecycle.mjs";
 import { privateThemeSource } from "./private-source.mjs";
 import { confirmRestart } from "./prompt.mjs";
 import { runtime as productionRuntime } from "./runtime.mjs";
 import { createStateStore } from "./state.mjs";
 
-export const VERSION = "0.2.0";
-const REAPPLY = "npx --yes @codextheme/cli@0.2.0 reapply";
-const RESTORE = "npx --yes @codextheme/cli@0.2.0 restore";
+export const VERSION = "0.2.1";
+const REAPPLY = "npx --yes @codextheme/cli@0.2.1 reapply";
+const RESTORE = "npx --yes @codextheme/cli@0.2.1 restore";
 
 const HELP = `CodexTheme ${VERSION}
 
@@ -40,11 +41,26 @@ function safePublicError(error) {
     "E_PRIVATE_DOWNLOAD",
     "E_PRIVATE_INVALID",
     "E_PRIVATE_CACHE",
+    "E_HANDOFF_BUSY",
+    "E_HANDOFF_FAILED",
   ]);
   if (allowed.has(error?.code)) return { code: error.code, message: error.message, exitCode: 1 };
   return { code: "E_DOM_INCOMPATIBLE", message: "CodexTheme 未能完成本次操作。", exitCode: 1 };
 }
 
+function writeApplyResult(stdout, result, name, successMessage, { showReapply = true } = {}) {
+  if (result.handoff?.queued) {
+    stdout.write(
+      `✓ ${name} 已交给独立任务处理\n`
+      + "Codex 将自动关闭并重新打开一次，随后完成主题应用和验证。\n"
+      + "当前 Codex task 可能结束；最终结果会通过 macOS 通知显示。\n",
+    );
+    return;
+  }
+  const reapply = showReapply ? `重开 Codex 后运行：${REAPPLY}\n` : "";
+  stdout.write(`${successMessage}\n${reapply}恢复官方外观：${RESTORE}\n`);
+}
+
 function validateCommand(argv) {
   if (argv.length === 2 && argv[0] === "apply") {
     const theme = getCatalogEntry(argv[1]);
@@ -75,7 +91,7 @@ export async function run(argv, dependencies = {}) {
   try {
     const parsed = validateCommand(argv);
     if ((dependencies.platform ?? process.platform) !== "darwin") {
-      throw new CliError("E_PLATFORM", "0.2.0 版本仅支持 macOS 上的 Codex Desktop。");
+      throw new CliError("E_PLATFORM", `${VERSION} 版本仅支持 macOS 上的 Codex Desktop。`);
     }
     const services = {
       runtime: dependencies.runtime ?? productionRuntime,
@@ -83,23 +99,24 @@ export async function run(argv, dependencies = {}) {
       promptRestart: dependencies.promptRestart ?? (() => confirmRestart()),
       now: dependencies.now ?? (() => new Date()),
       cache: dependencies.privateCache ?? createPrivateCache(),
+      restartHandoff: dependencies.restartHandoff ?? createRestartHandoff(),
     };
     const privateSource = dependencies.privateSource ?? privateThemeSource;
 
     if (parsed.command === "apply") {
       const result = await applyTheme({ ...services, slug: parsed.slug });
       const name = result.theme.theme?.displayName?.split(" / ")[0] ?? getCatalogEntry(parsed.slug).name;
-      stdout.write(`✓ ${name} 主题已应用并通过验证\n重开 Codex 后运行：${REAPPLY}\n恢复官方外观：${RESTORE}\n`);
+      writeApplyResult(stdout, result, name, `✓ ${name} 主题已应用并通过验证`);
     } else if (parsed.command === "apply-private") {
       const downloaded = await privateSource.download(parsed.privateId);
       const cacheKey = await services.cache.write(downloaded.serialized);
       const result = await applyPrivateTheme({ ...services, bundle: downloaded.bundle, cacheKey });
       const name = result.theme.theme?.displayName ?? "Private Custom Skin";
-      stdout.write(`✓ ${name} 已应用并通过验证\n重开 Codex 后运行：${REAPPLY}\n恢复官方外观：${RESTORE}\n`);
+      writeApplyResult(stdout, result, name, `✓ ${name} 已应用并通过验证`);
     } else if (parsed.command === "reapply") {
       const result = await reapplyTheme(services);
       const name = result.theme.theme?.displayName?.split(" / ")[0] ?? "当前";
-      stdout.write(`✓ ${name} 主题已重新应用并通过验证\n恢复官方外观：${RESTORE}\n`);
+      writeApplyResult(stdout, result, name, `✓ ${name} 主题已重新应用并通过验证`, { showReapply: false });
     } else {
       await restoreTheme(services);
       stdout.write("✓ 已恢复 Codex 官方外观\n");

package/src/runtime.mjs

@@ -1,67 +1,100 @@
-import {
-  applySkin,
-  discoverApp,
-  findRunningPids,
-  findTargets,
-  getAdapter,
-  lintThemePackage,
-  readThemePackage,
-  resolveThemeTarget,
-  restoreSkin,
-  validateThemePackage,
-} from "@codextheme/runtime";
+import * as runtimeCore from "@codextheme/runtime";
 import { themeFilename } from "./catalog.mjs";
 
-const adapter = getAdapter("codex");
+const RENDERER_ABSENT_CODES = new Set(["CODEDROBE_TARGET_TIMEOUT", "ECONNREFUSED"]);
 
-function resolveSafeTheme(bundle) {
-  try {
-    validateThemePackage(bundle);
-    if (lintThemePackage(bundle).length) throw new Error("lint");
-    return resolveThemeTarget(bundle, adapter.id);
-  } catch {
-    throw Object.assign(new Error("Theme failed safety validation."), { code: "E_DOM_INCOMPATIBLE" });
-  }
+function restoreComplete(result) {
+  const rendererComplete = result?.renderer?.restored === true
+    || RENDERER_ABSENT_CODES.has(result?.renderer?.code);
+  const hostComplete = result?.host?.restored === true
+    || result?.host?.reason === "missing-backup";
+  return rendererComplete && hostComplete;
 }
 
-export const runtime = {
-  async loadTheme(slug) {
-    const filename = themeFilename(slug);
-    if (!filename) throw Object.assign(new Error("Unknown theme."), { code: "E_USAGE" });
-    const bundle = await readThemePackage(filename);
-    return resolveSafeTheme(bundle);
-  },
+export function createRuntime({ core = runtimeCore, platform = process.platform } = {}) {
+  const adapter = core.getAdapter("codex");
 
-  async loadThemeBundle(bundle) {
-    return resolveSafeTheme(bundle);
-  },
+  function resolveSafeTheme(bundle) {
+    try {
+      core.validateThemePackage(bundle);
+      if (core.lintThemePackage(bundle).length) throw new Error("lint");
+      return core.resolveThemeTarget(bundle, adapter.id);
+    } catch {
+      throw Object.assign(new Error("Theme failed safety validation."), { code: "E_DOM_INCOMPATIBLE" });
+    }
+  }
 
-  async detect() {
-    const discovered = await discoverApp(adapter);
+  async function detectCodex() {
+    const discovered = await core.discoverApp(adapter, platform);
     if (!discovered) return { installed: false, running: false, ready: false };
     let ready = false;
     try {
-      ready = (await findTargets(adapter, adapter.defaultPort)).length > 0;
+      ready = (await core.findTargets(adapter, adapter.defaultPort)).length > 0;
     } catch { /* An absent loopback endpoint is an expected detection result. */ }
     let running = ready;
     if (!running) {
       try {
-        running = (await findRunningPids(adapter, process.platform, discovered.executable)).length > 0;
+        running = (await core.findRunningPids(adapter, platform, discovered.executable)).length > 0;
       } catch { /* applySkin still performs the authoritative launch check. */ }
     }
     return { installed: true, running, ready };
-  },
+  }
+
+  return {
+    async loadTheme(slug) {
+      const filename = themeFilename(slug);
+      if (!filename) throw Object.assign(new Error("Unknown theme."), { code: "E_USAGE" });
+      const bundle = await core.readThemePackage(filename);
+      return resolveSafeTheme(bundle);
+    },
+
+    async loadThemeBundle(bundle) {
+      return resolveSafeTheme(bundle);
+    },
+
+    detect: detectCodex,
 
-  async apply({ theme, restartExisting }) {
-    return applySkin({
-      adapter,
-      targetTheme: theme,
-      launch: true,
-      restartExisting,
-    });
-  },
+    async apply({ theme, restartExisting }) {
+      return core.applySkin({
+        adapter,
+        targetTheme: theme,
+        launch: true,
+        restartExisting,
+      });
+    },
+
+    async restore() {
+      return core.restoreSkin({ adapter });
+    },
+
+    async recover() {
+      let restored = null;
+      try {
+        restored = await core.restoreSkin({ adapter });
+      } catch { /* Relaunch still runs even when restore itself fails. */ }
+
+      let detection;
+      try {
+        detection = await detectCodex();
+      } catch {
+        detection = { installed: false, running: false, ready: false };
+      }
+
+      let launch = null;
+      if (detection.installed && !detection.running) {
+        try {
+          launch = await core.launchApp({ adapter });
+        } catch { /* The returned recovery result remains false. */ }
+      }
+
+      const running = detection.running || Boolean(launch?.targets);
+      return {
+        recovered: restoreComplete(restored) && running,
+        restore: restored,
+        launch,
+      };
+    },
+  };
+}
 
-  async restore() {
-    return restoreSkin({ adapter });
-  },
-};
+export const runtime = createRuntime();