@walkhi/code-relax 0.1.0-beta.1 → 0.1.0-beta.100

package/dist/src/managed-app-server.mjs

@@ -1,207 +1,398 @@
-import fs from 'node:fs';
-import net from 'node:net';
-import path from 'node:path';
-import { EventEmitter } from 'node:events';
-import { setTimeout as delay } from 'node:timers/promises';
-import { readRecord, writeRecord } from './service-lifecycle.mjs';
-import { SharedAppServer } from './shared-app-server.mjs';
-
-export const managedAppServerUrl = 'ws://127.0.0.1:45839';
-export const managedAppServerReadyUrl = 'http://127.0.0.1:45839/readyz';
-const retryDelays = [1_000, 2_000, 5_000, 10_000, 20_000];
-
-export function managedPortAvailable() {
-  return new Promise(resolve => {
-    const server = net.createServer();
-    server.once('error', () => resolve(false));
-    server.listen(45839, '127.0.0.1', () => server.close(() => resolve(true)));
-  });
-}
-
-export class ManagedAppServer extends EventEmitter {
-  constructor({ stateRoot, host, environment = process.env, available = managedPortAvailable,
-    wait = delay, timeout = 30_000, now = Date.now, client = new SharedAppServer(managedAppServerUrl) }) {
-    super();
-    this.stateRoot = stateRoot;
-    this.host = host;
-    this.environment = environment;
-    this.available = available;
-    this.wait = wait;
-    this.timeout = timeout;
-    this.now = now;
-    this.recordPath = path.join(stateRoot, 'managed-app-server.json');
-    this.legacyRecordPath = path.join(stateRoot, 'shared-desktop.json');
-    this.client = client;
-    this.state = { state: 'absent', ready: false, error: null };
-    this.restartStatus = null;
-    this.stopped = true;
-    this.restarting = false;
-    this.retryAttempt = 0;
-    this.retryAfter = 0;
-    this.client.on('disconnected', () => {
-      if (!this.stopped && !this.restarting) this.failed('Codex 内核连接断开。');
-    });
-  }
-
-  snapshot() { return { ...this.state, ...(this.restartStatus ? { restart: { ...this.restartStatus } } : {}) }; }
-
-  async start() {
-    this.stopped = false;
-    return this.ensure();
-  }
-
-  async ensure() {
-    if (this.stopped) return false;
-    if (this.restarting) return false;
-    if (this.work) return this.work;
-    if (this.now() < this.retryAfter) return false;
-    this.work = this.ensureNow().finally(() => { this.work = null; });
-    return this.work;
-  }
-
-  async ensureNow() {
-    // Keep an already verified instance available while the periodic identity
-    // check runs; publishing "starting" every three seconds makes health flicker.
-    if (!this.state.ready) this.publish({ state: 'starting', ready: false, error: null });
-    try {
-      fs.mkdirSync(this.stateRoot, { recursive: true });
-      const info = await this.host.inspect();
-      if (!info.cli) throw new Error('未找到 Desktop 管理的 codex.exe，请先安装并登录 Codex Desktop。');
-      let record = null, actual = null;
-      for (const candidate of [readRecord(this.recordPath), readRecord(this.legacyRecordPath)].filter(Boolean)) {
-        const process = candidate.pid ? await this.host.process(candidate.pid) : null;
-        if (sameManagedProcess(candidate, process)) { record = candidate; actual = process; break; }
-      }
-      if (!actual) {
-        if (!await this.available()) throw new Error('45839 被未识别进程占用，未启动或结束任何进程。');
-        const childEnvironment = { ...this.environment };
-        for (const key of ['CODEX_APP_SERVER_WS_URL', 'CODEX_APP_SERVER_FORCE_CLI', 'CODEX_APP_TOOLS_PIPE_PATH']) delete childEnvironment[key];
-        const pid = await this.host.start(info.cli, ['app-server', '--listen', managedAppServerUrl], childEnvironment,
-          [path.join(this.stateRoot, 'managed-app-server.stdout.log'), path.join(this.stateRoot, 'managed-app-server.stderr.log')]);
-        const started = await this.host.process(pid);
-        if (!sameManagedProcess(started, started)) throw new Error('Codex 内核启动后进程身份无法确认。');
-        record = actual = started;
-        writeRecord(this.recordPath, record);
-      } else if (!readRecord(this.recordPath)) {
-        writeRecord(this.recordPath, actual);
-      }
-      await this.waitUntilReady(actual);
-      await this.client.connect();
-      if (!this.client.ready) throw new Error('Codex 内核协议初始化未完成。');
-      const preferredExecutable = path.resolve(info.cli);
-      const updatePending = path.resolve(actual.executable).toLowerCase() !== preferredExecutable.toLowerCase();
-      this.retryAttempt = 0;
-      this.retryAfter = 0;
-      this.publish({ state: 'ready', ready: true, error: null, pid: actual.pid,
-        created: actual.created, executable: actual.executable, preferredExecutable,
-        updatePending, url: managedAppServerUrl });
-      return true;
-    } catch (error) {
-      this.failed(error instanceof Error ? error.message : String(error));
-      return false;
-    }
-  }
-
-  async waitUntilReady(expected) {
-    const deadline = this.now() + this.timeout;
-    while (true) {
-      const actual = await this.host.process(expected.pid);
-      if (!sameManagedProcess(expected, actual)) throw new Error('Codex 内核在就绪前退出。');
-      if (await this.host.ready(managedAppServerReadyUrl)) return;
-      if (this.now() >= deadline) throw new Error('Codex 内核未在 30 秒内就绪，请查看工作站诊断日志。');
-      await this.wait(250);
-    }
-  }
-
-  restart(operationId) {
-    if (this.stopped) throw new Error('工作站服务正在停止，不能重启 Codex 内核。');
-    if (this.restartWork) {
-      if (this.restartStatus?.operationId === operationId) return this.snapshot();
-      const error = new Error('Codex 内核已经在重启，请等待当前操作完成。');
-      error.code = 'managed_app_server_restarting';
-      throw error;
-    }
-    this.restartStatus = { operationId, status: 'running', stage: 'checking', error: null,
-      startedAt: new Date(this.now()).toISOString() };
-    this.emit('state', this.snapshot());
-    this.restartWork = this.restartNow().finally(() => { this.restartWork = null; });
-    return this.snapshot();
-  }
-
-  async restartNow() {
-    this.restarting = true;
-    const previous = this.state;
-    this.publish({ ...previous, state: 'restarting', ready: false, error: null });
-    try {
-      const record = readRecord(this.recordPath) || readRecord(this.legacyRecordPath);
-      const actual = record?.pid ? await this.host.process(record.pid) : null;
-      if (actual && !sameManagedProcess(record, actual)) {
-        throw new Error('Codex 内核进程身份已经变化，未结束任何进程。');
-      }
-      this.restartStage('stopping');
-      this.client.close();
-      if (actual) {
-        await this.host.stop(actual.pid);
-        await this.waitUntilStopped(actual);
-      } else if (!await this.available()) {
-        throw new Error('45839 被未识别进程占用，未结束任何进程。');
-      }
-      fs.rmSync(this.recordPath, { force: true });
-      this.retryAttempt = 0;
-      this.retryAfter = 0;
-      this.restartStage('starting');
-      const ready = await this.ensureNow();
-      if (!ready) throw new Error(this.state.error || 'Codex 内核未能重新启动。');
-      this.restartStatus = { ...this.restartStatus, status: 'completed', stage: 'ready',
-        completedAt: new Date(this.now()).toISOString() };
-      this.emit('state', this.snapshot());
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (this.state.state === 'restarting') this.failed(message);
-      this.restartStatus = { ...this.restartStatus, status: 'failed', stage: 'failed', error: message,
-        completedAt: new Date(this.now()).toISOString() };
-      this.emit('state', this.snapshot());
-    } finally {
-      this.restarting = false;
-    }
-  }
-
-  restartStage(stage) {
-    this.restartStatus = { ...this.restartStatus, stage };
-    this.emit('state', this.snapshot());
-  }
-
-  async waitUntilStopped(expected) {
-    const deadline = this.now() + 10_000;
-    while (true) {
-      const actual = await this.host.process(expected.pid);
-      if (!sameManagedProcess(expected, actual) && await this.available()) return;
-      if (this.now() >= deadline) throw new Error('Codex 内核未在 10 秒内退出；不会启动第二个实例。');
-      await this.wait(100);
-    }
-  }
-
-  failed(message) {
-    const retryMs = retryDelays[Math.min(this.retryAttempt++, retryDelays.length - 1)];
-    this.retryAfter = this.now() + retryMs;
-    this.publish({ state: 'failed', ready: false, error: message, retryAt: new Date(this.retryAfter).toISOString() });
-  }
-
-  publish(value) {
-    const changed = JSON.stringify(value) !== JSON.stringify(this.state);
-    this.state = value;
-    if (changed) this.emit('state', this.snapshot());
-  }
-
-  close() {
-    this.stopped = true;
-    this.client.close();
-  }
-}
-
-export function sameManagedProcess(record, actual) {
-  if (!record || !actual || record.pid !== actual.pid || record.created !== actual.created) return false;
-  if (String(record.executable || '').toLowerCase() !== String(actual.executable || '').toLowerCase()) return false;
-  const command = String(actual.command || '').toLowerCase();
-  return command.includes('app-server') && command.includes(managedAppServerUrl);
-}
+import fs from 'node:fs';
+import { executableKey } from './platform/path-identity.mjs';
+import net from 'node:net';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { EventEmitter } from 'node:events';
+import { setTimeout as delay } from 'node:timers/promises';
+import { readRecord, writeRecord } from './service-lifecycle.mjs';
+import { SharedAppServer } from './shared-app-server.mjs';
+import { pruneRetainedDesktopRuntimes, resolveCodexRuntime, runtimeFilesAvailable } from './platform/codex-runtime.mjs';
+
+import { defaultManagedPort, managedProcessUrl } from './managed-endpoint.mjs';
+import { configureManagedEnvironment } from './platform/user-environment.mjs';
+export const managedAppServerLauncherRevision = 3;
+const retryDelays = [1_000, 2_000, 5_000, 10_000, 20_000];
+
+export function managedPortAvailable(port = defaultManagedPort) {
+  return new Promise(resolve => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.listen(port, '127.0.0.1', () => server.close(() => resolve(true)));
+  });
+}
+export function availableManagedPort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      server.close(error => error ? reject(error) : resolve(port));
+    });
+  });
+}
+
+export class ManagedAppServer extends EventEmitter {
+  constructor({ stateRoot, host, environment = process.env, available = managedPortAvailable,
+    wait = delay, timeout = 30_000, now = Date.now, client = new SharedAppServer(`ws://127.0.0.1:${defaultManagedPort}`),
+    selectPort = availableManagedPort, configureEnvironment = configureManagedEnvironment, resolveRuntime = resolveCodexRuntime,
+    diagnose = () => {} }) {
+    super();
+    this.stateRoot = stateRoot;
+    this.host = host;
+    this.environment = environment;
+    this.available = available;
+    this.selectPort = selectPort;
+    this.configureEnvironment = configureEnvironment;
+    this.resolveRuntime = resolveRuntime;
+    this.diagnose = diagnose;
+    this.wait = wait;
+    this.timeout = timeout;
+    this.now = now;
+    this.recordPath = path.join(stateRoot, 'managed-app-server.json');
+    this.pendingPath = path.join(stateRoot, 'managed-app-server.pending.json');
+    this.lockPath = path.join(stateRoot, 'managed-app-server.lock');
+    this.client = client;
+    this.state = { state: 'absent', ready: false, error: null };
+    this.client.diagnosticIdentity = () => ({ kernelPid: this.state.pid ?? null, kernelCreated: this.state.created ?? null });
+    this.restartStatus = null;
+    this.stopped = true;
+    this.restarting = false;
+    this.retryAttempt = 0;
+    this.retryAfter = 0;
+    this.client.on('disconnected', () => {
+      if (!this.stopped && !this.restarting && !this.work) this.failed('Codex 内核连接断开。');
+    });
+  }
+
+  snapshot() {
+    return { ...this.state,
+      version: this.state.ready && this.client.ready ? this.client.serverVersion || null : null,
+      ...(this.restartStatus ? { restart: { ...this.restartStatus } } : {}) };
+  }
+
+  async start() {
+    this.stopped = false;
+    return this.ensure();
+  }
+
+  async ensure() {
+    if (this.stopped) return false;
+    if (this.restarting) return false;
+    if (this.work) return this.work;
+    if (this.now() < this.retryAfter) return false;
+    this.work = this.ensureNow().finally(() => { this.work = null; });
+    return this.work;
+  }
+
+  async ensureNow(lockHeld = false) {
+    // Keep an already verified instance available while the periodic identity
+    // check runs; publishing "starting" every three seconds makes health flicker.
+    if (!this.state.ready) this.publish({ state: 'starting', ready: false, error: null });
+    try {
+      fs.mkdirSync(this.stateRoot, { recursive: true });
+      const release = lockHeld ? () => {} : await this.acquireLock();
+      if (!release) return false;
+      try {
+      const pending = readRecord(this.pendingPath);
+      if (pending?.phase === 'spawning') throw new Error('上次内核启动的进程交接未完成，已停止自动启动以避免重复内核；请检查内核启动日志与 managed-app-server.pending.json。');
+      let record = pending || readRecord(this.recordPath);
+      let actual = record?.pid ? await this.host.process(record.pid) : null;
+      if (actual && !sameManagedProcess(record, actual)) {
+        // Stale PID now belongs to someone else: leave it untouched and select
+        // another available endpoint rather than adopting or stopping it.
+        actual = null;
+        record = null;
+      }
+      const startedHere = !actual;
+      const savedRuntime = actual ? readRecord(path.join(this.stateRoot, 'codex-runtime.json')) : null;
+      const runtime = actual && savedRuntime?.executable && runtimeFilesAvailable(savedRuntime.executable)
+        ? savedRuntime
+        : await this.resolveRuntime(this.stateRoot, { refresh: !actual, environment: this.environment });
+      if (actual && !runtimeFilesAvailable(actual.executable)) {
+        throw new Error(`运行中的 Codex 内核目录已被移除或缺少配套 code-mode-host：${actual.executable}；请确认重启内核。`);
+      }
+      if (!actual) {
+        const selection = { reason: this.restarting ? 'confirmed-restart' : record?.pid ? 'previous-process-exited' : 'no-running-kernel',
+          version: runtime.version, source: runtime.source, executable: runtime.executable };
+        const selectionSignature = JSON.stringify(selection);
+        if (selectionSignature !== this.diagnosticSelectionSignature) {
+          this.diagnosticSelectionSignature = selectionSignature;
+          this.diagnose('kernel-start-selected', selection);
+        }
+        fs.rmSync(this.pendingPath, { force: true });
+        const childEnvironment = { ...this.environment, CODEX_HOME: runtime.codexHome, RUST_LOG: 'warn' };
+        for (const key of ['CODEX_APP_SERVER_WS_URL', 'CODEX_APP_SERVER_FORCE_CLI', 'CODEX_APP_TOOLS_PIPE_PATH']) delete childEnvironment[key];
+        for (const key of Object.keys(childEnvironment)) {
+          if (/^npm_/iu.test(key) || key.toUpperCase() === 'INIT_CWD') delete childEnvironment[key];
+        }
+        // A probe cannot reserve a port for another process. Retry only when our
+        // previous child has definitely exited, never on a live unready kernel.
+        for (let attempt = 0; attempt < 5; attempt++) {
+          const preferred = attempt === 0 ? Number(managedProcessUrl(record)?.split(':').at(-1)) || defaultManagedPort : 0;
+          const port = preferred && await this.available(preferred) ? preferred : await this.selectPort();
+          const url = `ws://127.0.0.1:${port}`;
+          // Commit intent before spawning: if the launcher dies before it can
+          // record the child PID, a successor must fail closed, not duplicate it.
+          writeRecord(this.pendingPath, { phase: 'spawning', url, executable: runtime.executable, startedAt: new Date().toISOString() });
+          const pid = await this.host.start(runtime.executable, ['app-server', '--listen', url], childEnvironment,
+            [path.join(this.stateRoot, 'managed-app-server.stdout.log'), path.join(this.stateRoot, 'managed-app-server.stderr.log')]);
+          this.diagnose('kernel-spawned', { pid, executable: runtime.executable, selectedVersion: runtime.version,
+            source: runtime.source, attempt: attempt + 1 });
+          const started = await this.host.process(pid);
+          if (!started) {
+            fs.rmSync(this.pendingPath, { force: true });
+            if (attempt < 4) continue;
+            throw new Error('Codex 内核启动后退出，动态端口尝试已用完。');
+          }
+          record = { ...started, url, launcherRevision: managedAppServerLauncherRevision };
+          if (!sameManagedProcess(record, started) || executableKey(started.executable) !== executableKey(runtime.executable)) {
+            throw new Error('Codex 内核启动后进程身份无法确认，未启动第二个实例。');
+          }
+          // Private ownership journal is not a published endpoint. It prevents
+          // duplicate children even if the launcher crashes before readiness.
+          writeRecord(this.pendingPath, record);
+          actual = started;
+          try { await this.connectReady(record); break; }
+          catch (error) {
+            const remaining = await this.host.process(pid);
+            if (remaining || attempt === 4) throw error;
+            fs.rmSync(this.pendingPath, { force: true });
+            actual = null;
+          }
+        }
+      } else await this.connectReady(record);
+      const url = managedProcessUrl(record);
+      // Do not publish a guessed port or update Desktop before ownership,
+      // readiness and protocol initialization have all succeeded.
+      if (this.publishedUrl !== url) await this.configureEnvironment(this.stateRoot, url);
+      this.environment.CODEX_APP_SERVER_WS_URL = url;
+      process.env.CODEX_APP_SERVER_WS_URL = url;
+      if (this.publishedUrl !== url || readRecord(this.pendingPath)) writeRecord(this.recordPath, { ...record, url });
+      this.publishedUrl = url;
+      fs.rmSync(this.pendingPath, { force: true });
+      if (startedHere) {
+        try { await pruneRetainedDesktopRuntimes(this.stateRoot, actual.executable); }
+        catch (error) { console.error('旧版 Codex 内核文件清理失败：', error); }
+      }
+      const preferredExecutable = path.resolve(runtime.executable);
+      const updatePending = executableKey(actual.executable) !== executableKey(preferredExecutable);
+      const launcherRevision = Number.isSafeInteger(record?.launcherRevision) ? record.launcherRevision : 0;
+      this.retryAttempt = 0;
+      this.retryAfter = 0;
+      this.publish({ state: 'ready', ready: true, error: null, pid: actual.pid,
+        created: actual.created, executable: actual.executable, preferredExecutable,
+        updatePending, launcherRevision, selectedVersion: runtime.version, source: runtime.source,
+        launcherRestartRequired: launcherRevision !== managedAppServerLauncherRevision,
+        url });
+      return true;
+      } finally { release(); }
+    } catch (error) {
+      this.failed(error instanceof Error ? error.message : String(error));
+      return false;
+    }
+  }
+
+  async acquireLock() {
+    const token = randomUUID();
+    const temporary = `${this.lockPath}.${token}.tmp`;
+    const owner = await this.host.process(process.pid);
+    if (!owner) throw new Error('启动器进程身份无法确认。');
+    try {
+      // Publish a fully written record atomically; a crash cannot leave an
+      // empty lock that has no identifiable owner.
+      fs.writeFileSync(temporary, JSON.stringify({ ...owner, token }), { flag: 'wx', mode: 0o600 });
+      try { fs.linkSync(temporary, this.lockPath); }
+      catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        const previous = readRecord(this.lockPath);
+        if (!previous?.token) throw new Error('内核启动锁无法识别，请检查 managed-app-server.lock。');
+        const actual = await this.host.process(previous.pid);
+        if (!actual || actual.created !== previous.created || executableKey(actual.executable) !== executableKey(previous.executable)) {
+          // One permanent tombstone per abandoned generation means two stale
+          // observers cannot delete a replacement owner's lock (ABA race).
+          if (await this.claimRecovery(previous, this.lockPath, temporary)) {
+            if (readRecord(this.lockPath)?.token === previous.token) fs.rmSync(this.lockPath, { force: true });
+          }
+        }
+        return null;
+      }
+      return () => { if (readRecord(this.lockPath)?.token === token) fs.rmSync(this.lockPath, { force: true }); };
+    } finally { fs.rmSync(temporary, { force: true }); }
+  }
+
+  async claimRecovery(previous, target, ownerFile, depth = 0) {
+    if (depth > 16) throw new Error('内核启动锁多次异常中断，请检查启动器日志。');
+    const recovered = `${this.lockPath}.${previous.token}.recovered`;
+    try { fs.linkSync(ownerFile, recovered); return true; }
+    catch (error) { if (error.code !== 'EEXIST') throw error; }
+    const claimant = readRecord(recovered);
+    if (!claimant?.token) throw new Error('内核启动锁回收记录无法识别。');
+    const actual = await this.host.process(claimant.pid);
+    if (actual && actual.created === claimant.created && executableKey(actual.executable) === executableKey(claimant.executable)) return false;
+    // A reclaimer can itself crash. Keep an append-only ownership chain so its
+    // successor can complete cleanup without allowing two live reclaimers.
+    return this.claimRecovery(claimant, recovered, ownerFile, depth + 1);
+  }
+
+  async connectReady(expected) {
+    const url = managedProcessUrl(expected);
+    if (!url) throw new Error('Codex 内核地址无效。');
+    await this.waitUntilReady(expected);
+    if (this.client.url !== url) {
+      await this.disconnectClient();
+      this.client.url = url;
+    }
+    await this.client.connect();
+    if (!this.client.ready || !sameManagedProcess(expected, await this.host.process(expected.pid))
+        || !await this.host.ownsListener(expected, url)) {
+      this.client.close();
+      throw new Error('Codex 内核协议初始化或监听进程验证未完成。');
+    }
+  }
+
+  async disconnectClient() {
+    const socket = this.client.socket;
+    this.client.close();
+    if (socket && socket.readyState !== 3) {
+      await new Promise(resolve => {
+        const timer = setTimeout(() => { socket.terminate(); }, 1000);
+        socket.once('close', () => { clearTimeout(timer); resolve(); });
+      });
+    }
+    this.client.ready = false;
+  }
+
+  async waitUntilReady(expected) {
+    const url = managedProcessUrl(expected);
+    const deadline = this.now() + this.timeout;
+    while (true) {
+      const actual = await this.host.process(expected.pid);
+      if (!sameManagedProcess(expected, actual)) throw new Error('Codex 内核在就绪前退出。');
+      if (await this.host.ownsListener(expected, url) && await this.host.ready(url.replace('ws:', 'http:') + '/readyz')) return;
+      if (this.now() >= deadline) throw new Error('Codex 内核未在 30 秒内就绪；保留已启动实例，不会另起重复内核。');
+      await this.wait(250);
+    }
+  }
+
+  restart(operationId) {
+    if (this.stopped) throw new Error('工作站服务正在停止，不能重启 Codex 内核。');
+    if (this.restartWork) {
+      if (this.restartStatus?.operationId === operationId) return this.snapshot();
+      const error = new Error('Codex 内核已经在重启，请等待当前操作完成。');
+      error.code = 'managed_app_server_restarting';
+      throw error;
+    }
+    this.restartStatus = { operationId, status: 'running', stage: 'checking', error: null,
+      startedAt: new Date(this.now()).toISOString() };
+    this.emit('state', this.snapshot());
+    this.restartWork = this.restartNow().finally(() => { this.restartWork = null; });
+    return this.snapshot();
+  }
+
+  async restartNow() {
+    this.restarting = true;
+    await this.work;
+    const previous = this.state;
+    let release;
+    this.publish({ ...previous, state: 'restarting', ready: false, error: null });
+    try {
+      release = await this.acquireLock();
+      if (!release) throw new Error('另一个内核启动操作正在进行，请稍后重试。');
+      const pending = readRecord(this.pendingPath);
+      if (pending?.phase === 'spawning') throw new Error('上次内核启动交接未完成，无法安全重启未知进程；请检查内核启动日志。');
+      const record = pending || readRecord(this.recordPath);
+      const actual = record?.pid ? await this.host.process(record.pid) : null;
+      if (actual && !sameManagedProcess(record, actual)) {
+        throw new Error('Codex 内核进程身份已经变化，未结束任何进程。');
+      }
+      this.restartStage('stopping');
+      // Resolve the replacement before stopping the current working process.
+      const runtime = await this.resolveRuntime(this.stateRoot, { refresh: true, environment: this.environment });
+      const desktop = await this.host.prepareKernelRestart?.();
+      await this.disconnectClient();
+      if (actual) {
+        await this.host.stop(actual.pid, actual);
+        await this.waitUntilStopped(actual);
+      }
+      fs.rmSync(this.pendingPath, { force: true });
+      this.publishedUrl = null;
+      this.retryAttempt = 0;
+      this.retryAfter = 0;
+      this.restartStage('starting');
+      const ready = await this.ensureNow(true);
+      if (!ready) throw new Error(this.state.error || 'Codex 内核未能重新启动。');
+      const desktopEnvironment = { ...this.environment, CODEX_HOME: runtime.codexHome, CODEX_APP_SERVER_WS_URL: this.state.url };
+      delete desktopEnvironment.CODEX_APP_SERVER_FORCE_CLI;
+      delete desktopEnvironment.CODEX_APP_TOOLS_PIPE_PATH;
+      await this.host.resumeAfterKernelRestart?.(desktop, desktopEnvironment);
+      this.restartStatus = { ...this.restartStatus, status: 'completed', stage: 'ready',
+        completedAt: new Date(this.now()).toISOString() };
+      this.emit('state', this.snapshot());
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (this.state.state === 'restarting') this.failed(message);
+      this.restartStatus = { ...this.restartStatus, status: 'failed', stage: 'failed', error: message,
+        completedAt: new Date(this.now()).toISOString() };
+      this.emit('state', this.snapshot());
+    } finally {
+      release?.();
+      this.restarting = false;
+    }
+  }
+
+  restartStage(stage) {
+    this.restartStatus = { ...this.restartStatus, stage };
+    this.emit('state', this.snapshot());
+  }
+
+  async waitUntilStopped(expected) {
+    const deadline = this.now() + 10_000;
+    while (true) {
+      const actual = await this.host.process(expected.pid);
+      if (!sameManagedProcess(expected, actual)) return;
+      if (this.now() >= deadline) throw new Error('Codex 内核未在 10 秒内退出；不会启动第二个实例。');
+      await this.wait(100);
+    }
+  }
+
+  failed(message) {
+    const retryMs = retryDelays[Math.min(this.retryAttempt++, retryDelays.length - 1)];
+    this.retryAfter = this.now() + retryMs;
+    this.publish({ state: 'failed', ready: false, error: message, retryAt: new Date(this.retryAfter).toISOString() });
+  }
+
+  publish(value) {
+    const changed = JSON.stringify(value) !== JSON.stringify(this.state);
+    this.state = value;
+    if (changed) this.emit('state', this.snapshot());
+    // Retry transitions remain visible to health consumers; diagnostic output
+    // records a repeated failure once until it changes or the kernel recovers.
+    if (value.state === 'starting' && this.diagnosticState?.state === 'failed') return;
+    const details = { state: value.state, ready: value.ready, pid: value.pid ?? null, created: value.created ?? null,
+      version: value.ready && this.client.ready ? this.client.serverVersion || null : null,
+      executable: value.executable || null, selectedVersion: value.selectedVersion || null,
+      preferredExecutable: value.preferredExecutable || null, source: value.source || null,
+      updatePending: value.updatePending === true, error: value.error || null };
+    const signature = JSON.stringify(details);
+    if (signature === this.diagnosticStateSignature) return;
+    this.diagnosticStateSignature = signature;
+    this.diagnosticState = details;
+    if (value.ready) this.diagnosticSelectionSignature = null;
+    this.diagnose('kernel-state', { ...details, retryAt: value.retryAt || null });
+  }
+
+  close() {
+    this.stopped = true;
+    this.client.close();
+  }
+}
+
+export function sameManagedProcess(record, actual) {
+  if (!record || !actual || record.pid !== actual.pid || record.created !== actual.created) return false;
+  if (!record.executable || !actual.executable || executableKey(record.executable) !== executableKey(actual.executable)) return false;
+  const url = managedProcessUrl(record);
+  if (!url || managedProcessUrl(actual) !== url) return false;
+  return Array.isArray(actual.args) ? JSON.stringify(record.args) === JSON.stringify(actual.args)
+    : record.command === actual.command;
+}