minecodex 0.1.0

package/packages/cli/src/platform.mjs

@@ -0,0 +1,368 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const defaultExecFile = promisify(execFileCallback);
+const defaultFileSystem = Object.freeze({ mkdir, readFile, stat, unlink, writeFile });
+
+export const SERVICE_LABEL = "com.vontean.minecodex";
+export const CODEX_APP_PATH = "/Applications/ChatGPT.app";
+export const CODEX_EXECUTABLE = `${CODEX_APP_PATH}/Contents/MacOS/ChatGPT`;
+export const MIN_NODE_VERSION = Object.freeze({ major: 22, minor: 5, patch: 0 });
+
+function xml(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+export function buildLaunchAgent({ nodePath, cliPath, paths }) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(nodePath)}</string>
+    <string>${xml(cliPath)}</string>
+    <string>serve</string>
+    <string>--service</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+  <key>StandardOutPath</key>
+  <string>${xml(paths.serviceLogPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(paths.serviceErrorLogPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xml(path.dirname(nodePath))}:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+export function assertNodeSupported(nodeVersion = process.versions.node) {
+  const [major, minor, patch = 0] = String(nodeVersion).split(".").map((part) => Number.parseInt(part, 10));
+  const supported = Number.isInteger(major)
+    && (major > MIN_NODE_VERSION.major
+      || (major === MIN_NODE_VERSION.major && Number.isInteger(minor) && minor >= MIN_NODE_VERSION.minor));
+  if (!supported) {
+    throw new Error(
+      `MineCodex requires Node.js ${MIN_NODE_VERSION.major}.${MIN_NODE_VERSION.minor}.0 or newer; `
+      + `current version is ${nodeVersion}. Upgrade Node.js before running mcx install.`,
+    );
+  }
+  return { major, minor, patch };
+}
+
+export function supportedCodexAppPaths(homeDir = os.homedir()) {
+  return Object.freeze([
+    CODEX_APP_PATH,
+    path.join(homeDir, "Applications", "ChatGPT.app"),
+  ]);
+}
+
+export async function resolveCodexInstallation({
+  homeDir = os.homedir(),
+  fileExists = async (filePath) => {
+    try {
+      await readFile(filePath);
+      return true;
+    } catch (error) {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    }
+  },
+} = {}) {
+  for (const appPath of supportedCodexAppPaths(homeDir)) {
+    const infoPath = path.join(appPath, "Contents", "Info.plist");
+    if (await fileExists(infoPath)) {
+      return Object.freeze({
+        appPath,
+        executable: path.join(appPath, "Contents", "MacOS", "ChatGPT"),
+      });
+    }
+  }
+  throw new Error(
+    `Codex Desktop was not found in a supported installation path: ${supportedCodexAppPaths(homeDir).join(", ")}`,
+  );
+}
+
+export function parseProcessList(output) {
+  return String(output).split("\n").flatMap((line) => {
+    const match = line.match(/^\s*(\d+)\s+(.+)$/);
+    return match ? [{ pid: Number(match[1]), command: match[2] }] : [];
+  });
+}
+
+export function isExactCodexProcess(command, installation) {
+  const value = String(command).trim();
+  return value === installation?.executable || value.startsWith(`${installation?.executable} `);
+}
+
+function hasManagedProfile(command, profileDir) {
+  const value = String(command);
+  const marker = `--user-data-dir=${profileDir}`;
+  let offset = value.indexOf(marker);
+  while (offset >= 0) {
+    const before = offset === 0 || /\s/.test(value[offset - 1]);
+    const end = offset + marker.length;
+    const after = end === value.length || /\s/.test(value[end]);
+    if (before && after) return true;
+    offset = value.indexOf(marker, offset + 1);
+  }
+  return false;
+}
+
+export function serviceIsAbsent(error) {
+  return /could not find service|service not found|no such process|domain does not support specified action/i.test(
+    `${error?.stderr ?? ""}\n${error?.message ?? ""}`,
+  );
+}
+
+async function waitForProcessExit(pid, { processApi, timeoutMs = 8_000, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      processApi.kill(pid, 0);
+    } catch (error) {
+      if (error.code === "ESRCH") return;
+      throw error;
+    }
+    await sleep(100);
+  }
+  throw new Error(`Process ${pid} did not exit in time`);
+}
+
+function serviceTarget(uid) {
+  return `gui/${uid}/${SERVICE_LABEL}`;
+}
+
+export class MacPlatformAdapter {
+  constructor({
+    uid = process.getuid?.() ?? os.userInfo().uid,
+    platform = process.platform,
+    homeDir = os.homedir(),
+    execFile = defaultExecFile,
+    fileSystem = defaultFileSystem,
+    processApi = process,
+    sleep,
+    codexInstallation,
+  } = {}) {
+    this.uid = uid;
+    this.platform = platform;
+    this.homeDir = homeDir;
+    this.execFile = execFile;
+    this.fileSystem = fileSystem;
+    this.processApi = processApi;
+    this.sleep = sleep;
+    this.codexInstallation = codexInstallation;
+  }
+
+  assertInstallSupported() {
+    if (this.platform !== "darwin") {
+      throw new Error("MineCodex v1 installation currently supports macOS only.");
+    }
+  }
+
+  async assertCodexInstalled() {
+    this.codexInstallation = await resolveCodexInstallation({
+      homeDir: this.homeDir,
+      fileExists: async (filePath) => {
+        try {
+          await this.fileSystem.readFile(filePath);
+          return true;
+        } catch (error) {
+          if (error.code === "ENOENT") return false;
+          throw error;
+        }
+      },
+    });
+    return this.codexInstallation;
+  }
+
+  async codex() {
+    return this.codexInstallation ?? this.assertCodexInstalled();
+  }
+
+  async isServiceRunning() {
+    try {
+      await this.execFile("/bin/launchctl", ["print", serviceTarget(this.uid)]);
+      return true;
+    } catch (error) {
+      if (serviceIsAbsent(error)) return false;
+      throw error;
+    }
+  }
+
+  async snapshotServiceState(paths) {
+    let plist;
+    try {
+      const metadataPromise = this.fileSystem.stat
+        ? this.fileSystem.stat(paths.launchAgentPath).catch(() => null)
+        : Promise.resolve(null);
+      const [content, metadata] = await Promise.all([
+        this.fileSystem.readFile(paths.launchAgentPath, "utf8"),
+        metadataPromise,
+      ]);
+      plist = { exists: true, content, mode: metadata?.mode };
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      plist = { exists: false, content: null, mode: null };
+    }
+    return { plist, running: await this.isServiceRunning() };
+  }
+
+  async installService({ cliPath, paths, start = true }) {
+    await this.fileSystem.mkdir(path.dirname(paths.launchAgentPath), { recursive: true });
+    await this.fileSystem.mkdir(paths.logsDir, { recursive: true, mode: 0o700 });
+    const plist = buildLaunchAgent({ nodePath: process.execPath, cliPath, paths });
+    await this.fileSystem.writeFile(paths.launchAgentPath, plist, { mode: 0o600 });
+    await this.stopService({ ignoreErrors: true });
+    await this.execFile("/bin/launchctl", ["bootstrap", `gui/${this.uid}`, paths.launchAgentPath]);
+    if (start) {
+      await this.execFile("/bin/launchctl", ["kickstart", "-k", serviceTarget(this.uid)]);
+    } else {
+      await this.stopService({ ignoreErrors: true });
+    }
+  }
+
+  async stopService({ ignoreErrors = false } = {}) {
+    try {
+      await this.execFile("/bin/launchctl", ["bootout", serviceTarget(this.uid)]);
+    } catch (error) {
+      if (!ignoreErrors || !serviceIsAbsent(error)) throw error;
+    }
+  }
+
+  async startService(paths) {
+    if (!(await this.isServiceRunning())) {
+      await this.execFile("/bin/launchctl", ["bootstrap", `gui/${this.uid}`, paths.launchAgentPath]);
+    }
+    await this.execFile("/bin/launchctl", ["kickstart", "-k", serviceTarget(this.uid)]);
+  }
+
+  async assertServiceStopped() {
+    if (await this.isServiceRunning()) throw new Error("MineCodex launchd service is still running.");
+  }
+
+  async restoreServiceState(snapshot, { cliPath, paths } = {}) {
+    await this.stopService({ ignoreErrors: true });
+    await this.assertServiceStopped();
+    if (snapshot?.plist?.exists) {
+      await this.fileSystem.mkdir(path.dirname(paths.launchAgentPath), { recursive: true });
+      await this.fileSystem.writeFile(paths.launchAgentPath, snapshot.plist.content, {
+        mode: snapshot.plist.mode ? snapshot.plist.mode & 0o777 : 0o600,
+      });
+    } else {
+      await this.fileSystem.unlink(paths.launchAgentPath).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    }
+    if (snapshot?.running) {
+      if (!snapshot?.plist?.exists) throw new Error("Cannot restore a running service without its plist.");
+      await this.execFile("/bin/launchctl", ["bootstrap", `gui/${this.uid}`, paths.launchAgentPath]);
+      await this.execFile("/bin/launchctl", ["kickstart", "-k", serviceTarget(this.uid)]);
+    }
+    return snapshot;
+  }
+
+  async removeService(paths) {
+    await this.stopService({ ignoreErrors: true });
+    await this.assertServiceStopped();
+    await this.fileSystem.unlink(paths.launchAgentPath).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+  }
+
+  async listCodexProcesses() {
+    const installation = await this.codex();
+    const { stdout } = await this.execFile("/bin/ps", ["-axo", "pid=,command="]);
+    return parseProcessList(stdout).filter(({ command }) => isExactCodexProcess(command, installation));
+  }
+
+  async ownedCodexProcesses(paths) {
+    const processes = await this.listCodexProcesses();
+    return processes.filter(({ command }) => hasManagedProfile(command, paths.profileDir));
+  }
+
+  async assertOwnedCodexStopped(paths) {
+    const processes = await this.ownedCodexProcesses(paths);
+    if (processes.length) {
+      throw new Error(`MineCodex-owned Codex processes are still running: ${processes.map(({ pid }) => pid).join(", ")}`);
+    }
+  }
+
+  async snapshotNativeCodexState() {
+    const processes = (await this.listCodexProcesses()).filter(({ command }) => !command.includes("--user-data-dir="));
+    return { count: processes.length, processes };
+  }
+
+  async restoreNativeCodexState(snapshot) {
+    if (!snapshot?.count) return 0;
+    const current = (await this.listCodexProcesses()).filter(({ command }) => !command.includes("--user-data-dir="));
+    if (current.length) return current.length;
+    await this.openNativeCodex();
+    return snapshot.count;
+  }
+
+  async terminateOwnedCodex(paths) {
+    let pid;
+    try {
+      pid = Number((await this.fileSystem.readFile(paths.codexPidPath, "utf8")).trim());
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        await this.assertOwnedCodexStopped(paths);
+        return false;
+      }
+      throw error;
+    }
+    if (!Number.isInteger(pid) || pid <= 1) {
+      await this.assertOwnedCodexStopped(paths);
+      return false;
+    }
+    const processInfo = (await this.ownedCodexProcesses(paths)).find((candidate) => candidate.pid === pid);
+    if (!processInfo) {
+      await this.assertOwnedCodexStopped(paths);
+      return false;
+    }
+    this.processApi.kill(pid, "SIGTERM");
+    await waitForProcessExit(pid, { processApi: this.processApi, sleep: this.sleep });
+    await this.fileSystem.unlink(paths.codexPidPath).catch(() => {});
+    await this.assertOwnedCodexStopped(paths);
+    return true;
+  }
+
+  async terminateNativeCodex() {
+    const processes = (await this.listCodexProcesses()).filter(({ command }) => !command.includes("--user-data-dir="));
+    for (const { pid } of processes) this.processApi.kill(pid, "SIGTERM");
+    await Promise.all(processes.map(({ pid }) => waitForProcessExit(pid, { processApi: this.processApi, sleep: this.sleep })));
+    return processes.length;
+  }
+
+  async openBrowser(url) {
+    await this.execFile("/usr/bin/open", [url]);
+  }
+
+  async openNativeCodex() {
+    const installation = await this.codex();
+    await this.execFile("/usr/bin/open", ["-a", installation.appPath]);
+  }
+}

package/packages/cli/src/runtime-manager.mjs

@@ -0,0 +1,338 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { readConfig, FEATURE_IDS } from "./config.mjs";
+
+export const RUNTIME_PLUGIN_STATES = Object.freeze([
+  "configured",
+  "launching",
+  "ready",
+  "injected",
+  "failed",
+  "stopped",
+]);
+
+function enabledFeatureIds(config) {
+  return FEATURE_IDS.filter((id) => config.features[id]);
+}
+
+function hasExited(child) {
+  return Boolean(child && (child.exitCode != null || child.signalCode != null));
+}
+
+function normalizedFailure(failure) {
+  if (!failure || typeof failure !== "object") return failure ?? null;
+  return {
+    code: failure.code ?? "RUNTIME_PLUGIN_FAILED",
+    message: failure.message ?? "MineCodex plugin failed.",
+    phase: failure.phase ?? "runtime",
+  };
+}
+
+export function normalizeRuntimeReady(ready = {}) {
+  const sourcePlugins = Array.isArray(ready.plugins) ? ready.plugins : [];
+  const plugins = sourcePlugins.flatMap((plugin) => {
+    if (!plugin || typeof plugin.featureId !== "string") return [];
+    const state = RUNTIME_PLUGIN_STATES.includes(plugin.state) ? plugin.state : "failed";
+    return [{
+      ...plugin,
+      featureId: plugin.featureId,
+      state,
+      owned: plugin.owned === true,
+      health: plugin.health ?? null,
+      failure: normalizedFailure(plugin.failure),
+    }];
+  });
+  const legacyFeatures = Array.isArray(ready.features)
+    ? ready.features.filter((id) => typeof id === "string")
+    : [];
+  const features = [...new Set([
+    ...legacyFeatures,
+    ...plugins.filter(({ state }) => ["configured", "launching", "ready", "injected"].includes(state)).map(({ featureId }) => featureId),
+  ])];
+  const renderer = ready.renderer && typeof ready.renderer === "object"
+    ? {
+      ...ready.renderer,
+      discovered: ready.renderer.discovered === true,
+      injectedTargets: Number.isInteger(ready.renderer.injectedTargets) ? ready.renderer.injectedTargets : 0,
+      active: ready.renderer.active === true,
+      runtimeSessionId: ready.renderer.runtimeSessionId ?? null,
+    }
+    : null;
+  return {
+    ...ready,
+    runtimeSessionId: ready.runtimeSessionId ?? null,
+    features,
+    plugins,
+    failures: Array.isArray(ready.failures) ? ready.failures : [],
+    renderer,
+  };
+}
+
+function isReadyPayload(ready, child) {
+  return ready?.pid === child.pid
+    && (Array.isArray(ready.features) || Array.isArray(ready.plugins));
+}
+
+function rendererUnavailableReady(ready) {
+  const normalized = normalizeRuntimeReady(ready);
+  return normalizeRuntimeReady({
+    ...normalized,
+    plugins: normalized.plugins.map((plugin) => plugin.state === "injected"
+      ? { ...plugin, state: "ready", health: null }
+      : plugin),
+    renderer: {
+      ...(normalized.renderer ?? {}),
+      discovered: false,
+      injectedTargets: 0,
+      active: false,
+      runtimeSessionId: normalized.runtimeSessionId,
+    },
+  });
+}
+
+async function waitForReady(readyPath, child, timeoutMs = 25_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const ready = JSON.parse(await readFile(readyPath, "utf8"));
+      if (isReadyPayload(ready, child)) {
+        child.readyPayloadSeen = true;
+        return normalizeRuntimeReady(ready);
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT" && !(error instanceof SyntaxError)) throw error;
+    }
+    if (hasExited(child)) {
+      throw new Error(`RuntimeHost exited before becoming ready (${child.signalCode ?? child.exitCode ?? "unknown"})`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error("RuntimeHost did not report ready in time");
+}
+
+export class RuntimeManager {
+  constructor({
+    paths,
+    platform,
+    logger = console,
+    spawnProcess = spawn,
+    waitForReady: readyWaiter = waitForReady,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    stopTimeoutMs = 5_000,
+  }) {
+    this.paths = paths;
+    this.platform = platform;
+    this.logger = logger;
+    this.spawnProcess = spawnProcess;
+    this.waitForReady = readyWaiter;
+    this.sleep = sleep;
+    this.stopTimeoutMs = stopTimeoutMs;
+    this.child = null;
+    this.appliedFeatures = [];
+    this.plugins = [];
+    this.ready = null;
+    this.stopping = false;
+    this.lifecycleQueue = Promise.resolve();
+    this.restartInFlight = null;
+  }
+
+  enqueue(operation) {
+    const next = this.lifecycleQueue.catch(() => {}).then(operation);
+    this.lifecycleQueue = next.catch(() => {});
+    return next;
+  }
+
+  async startInternal() {
+    if (this.child && !hasExited(this.child)) return this.status();
+    this.clearChildState();
+    this.stopping = false;
+    const config = await readConfig(this.paths.configPath);
+    const features = enabledFeatureIds(config);
+    const codexInstallation = typeof this.platform?.codex === "function"
+      ? await this.platform.codex()
+      : null;
+    const codexExecutable = codexInstallation?.executable
+      ?? process.env.MINECODEX_CODEX_EXECUTABLE;
+    await mkdir(this.paths.supportDir, { recursive: true, mode: 0o700 });
+    await unlink(this.paths.runtimeReadyPath).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+    const child = this.spawnProcess(process.execPath, [this.paths.runtimeEntry], {
+      cwd: this.paths.packageRoot,
+      env: {
+        ...process.env,
+        CODEX_FEATURES_ROOT: this.paths.featuresRoot,
+        CODEX_RUNTIME_PROFILE_DIR: this.paths.profileDir,
+        CODEX_RUNTIME_CDP_PORT: process.env.CODEX_RUNTIME_CDP_PORT ?? "9231",
+        CODEX_IMAGE_HOST_DATA_DIR: this.paths.imagesDataDir,
+        CODEX_NOTES_DATA_DIR: this.paths.notesDataDir,
+        MINECODEX_ENABLED_FEATURES: features.join(","),
+        MINECODEX_CODEX_PID_FILE: this.paths.codexPidPath,
+        MINECODEX_RUNTIME_READY_FILE: this.paths.runtimeReadyPath,
+        ...(codexExecutable ? { MINECODEX_CODEX_EXECUTABLE: codexExecutable } : {}),
+      },
+      stdio: "inherit",
+    });
+    this.child = child;
+    if (hasExited(child)) {
+      this.clearChildState();
+      throw new Error(`RuntimeHost exited immediately (${child.signalCode ?? child.exitCode})`);
+    }
+    child.once("exit", (code, signal) => {
+      if (this.child === child) this.clearChildState();
+      if (!this.stopping && (code !== 0 || signal !== null)) {
+        this.logger.error(`MineCodex RuntimeHost exited (${signal ?? code ?? "unknown"})`);
+      }
+    });
+    try {
+      const ready = await this.waitForReady(this.paths.runtimeReadyPath, child);
+      this.ready = normalizeRuntimeReady(ready);
+      this.appliedFeatures = [...this.ready.features];
+      this.plugins = [...this.ready.plugins];
+    } catch (startupError) {
+      let cleanupError = null;
+      this.stopping = true;
+      try {
+        if (hasExited(child)) {
+          this.clearChildState();
+        } else {
+          const exited = await this.waitForExactExit(child, "SIGTERM", this.stopTimeoutMs);
+          const confirmed = exited || await this.waitForExactExit(child, "SIGKILL", this.stopTimeoutMs);
+          if (confirmed) {
+            this.clearChildState();
+          } else {
+            cleanupError = new Error(
+              `RuntimeHost pid ${child.pid} did not exit after SIGKILL within ${this.stopTimeoutMs}ms`,
+            );
+          }
+        }
+      } catch (failure) {
+        cleanupError = failure;
+      } finally {
+        this.stopping = false;
+      }
+      if (cleanupError) {
+        throw new Error(`${startupError.message}; cleanup also failed: ${cleanupError.message}`, { cause: startupError });
+      }
+      throw startupError;
+    }
+    return this.status();
+  }
+
+  clearChildState() {
+    this.child = null;
+    this.ready = null;
+    this.appliedFeatures = [];
+    this.plugins = [];
+  }
+
+  start() {
+    return this.enqueue(() => this.startInternal());
+  }
+
+  async stopInternal() {
+    const child = this.child;
+    if (!child || hasExited(child)) {
+      this.clearChildState();
+      return;
+    }
+    this.stopping = true;
+    let confirmed = false;
+    try {
+      const exited = await this.waitForExactExit(child, "SIGTERM", this.stopTimeoutMs);
+      confirmed = exited || await this.waitForExactExit(child, "SIGKILL", this.stopTimeoutMs);
+    } finally {
+      this.stopping = false;
+    }
+    if (!confirmed) {
+      throw new Error(`RuntimeHost pid ${child.pid} did not exit after SIGKILL within ${this.stopTimeoutMs}ms`);
+    }
+    this.clearChildState();
+  }
+
+  async waitForExactExit(child, signal, timeoutMs) {
+    if (hasExited(child)) return true;
+    let exited = false;
+    const onExit = () => { exited = true; };
+    child.once("exit", onExit);
+    try {
+      try {
+        child.kill(signal);
+      } catch (error) {
+        if (error?.code === "ESRCH") return true;
+        throw error;
+      }
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
+        if (exited || hasExited(child)) return true;
+        await this.sleep(50);
+      }
+      return exited || hasExited(child);
+    } finally {
+      child.removeListener?.("exit", onExit);
+    }
+  }
+
+  stop() {
+    return this.enqueue(() => this.stopInternal());
+  }
+
+  async refreshStatus() {
+    const child = this.child;
+    if (!child || hasExited(child)) return this.status();
+    try {
+      const ready = normalizeRuntimeReady(JSON.parse(await readFile(this.paths.runtimeReadyPath, "utf8")));
+      const expectedSession = this.ready?.runtimeSessionId ?? null;
+      const currentSession = ready.runtimeSessionId ?? null;
+      if (!isReadyPayload(ready, child) || (expectedSession && currentSession !== expectedSession)) {
+        this.ready = rendererUnavailableReady(this.ready ?? ready);
+      } else {
+        this.ready = ready;
+        this.appliedFeatures = [...ready.features];
+        this.plugins = [...ready.plugins];
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT" && !(error instanceof SyntaxError)) throw error;
+      if (this.ready) this.ready = rendererUnavailableReady(this.ready);
+    }
+    if (this.ready) {
+      this.appliedFeatures = [...this.ready.features];
+      this.plugins = [...this.ready.plugins];
+    }
+    return this.status();
+  }
+
+  restart() {
+    if (this.restartInFlight) return this.restartInFlight;
+    const operation = this.enqueue(async () => {
+      await this.stopInternal();
+      await this.platform.terminateOwnedCodex(this.paths);
+      return this.startInternal();
+    });
+    this.restartInFlight = operation;
+    const shared = this.restartInFlight.finally(() => {
+      if (this.restartInFlight === operation) this.restartInFlight = null;
+    });
+    return shared;
+  }
+
+  status() {
+    const running = Boolean(this.child && !hasExited(this.child));
+    return {
+      running,
+      pid: this.child?.pid ?? null,
+      appliedFeatures: running ? [...this.appliedFeatures] : [],
+      plugins: running ? [...this.plugins] : [],
+      pluginStates: running ? [...this.plugins] : [],
+      ready: running ? this.ready : null,
+      runtimeSessionId: running ? this.ready?.runtimeSessionId ?? null : null,
+      renderer: running ? this.ready?.renderer ?? null : null,
+      failures: running ? [...(this.ready?.failures ?? [])] : [],
+    };
+  }
+}
+
+export async function writeServicePid(pidPath) {
+  await writeFile(pidPath, `${process.pid}\n`, { mode: 0o600 });
+  return async () => unlink(pidPath).catch(() => {});
+}