codex-ringside 0.0.0-stage → 0.1.0

package/src/install.cjs

@@ -0,0 +1,222 @@
+'use strict';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const launchd = require('./launchd.cjs');
+const { DEFAULT_APP, isExecutable, resolveCodexBin, resolveNode } = require('./resolve.cjs');
+
+const SWIFTC = '/usr/bin/swiftc';
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const defaults = {
+  repoRoot: path.resolve(__dirname, '..'),
+  current: { ...launchd.paths, label: launchd.LABEL },
+  legacy: { ...launchd.legacyPaths, label: launchd.LEGACY_LABEL },
+  backupRoot: path.join(os.homedir(), 'Library/Application Support/CodexRingside Backups'),
+  trashRoot: path.join(os.homedir(), '.Trash'),
+  services: launchd
+};
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw new Error(`无法读取设置：${file}`, { cause: error });
+  }
+}
+
+function writeJson(file, data) {
+  fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+}
+
+function preflight(settings) {
+  if (process.platform !== 'darwin') throw new Error('只支持 macOS');
+  const app = fs.realpathSync(settings.app);
+  resolveCodexBin(app);
+  if (!isExecutable(SWIFTC)) throw new Error('需要 Xcode Command Line Tools：xcode-select --install');
+  return { app, node: resolveNode() };
+}
+
+function compile(repoRoot, stage) {
+  execFileSync(SWIFTC, ['-O', '-swift-version', '5', path.join(repoRoot, 'native/bridge.swift'), '-o', path.join(stage, 'bridge')], {
+    stdio: ['ignore', 'ignore', 'inherit'], timeout: 180000
+  });
+}
+
+async function waitReady(current, startedAt) {
+  for (let i = 0; i < 100; i++) {
+    const state = readJson(path.join(current.installDir, 'state.json'));
+    if (['watching', 'observing'].includes(state?.event) && state.updatedAt >= startedAt) return;
+    await sleep(100);
+  }
+  throw new Error(`后台任务未就绪，请查看 ${path.join(current.logDir, 'agent.err.log')}`);
+}
+
+function copyIfPresent(source, destination) {
+  if (!fs.existsSync(source)) return;
+  fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+  fs.cpSync(source, destination, { recursive: true, preserveTimestamps: true });
+}
+
+function capture(locations, backup) {
+  return locations.flatMap((location, index) => ['installDir', 'logDir', 'plist'].map(key => {
+    const source = location[key];
+    const destination = path.join(backup, String(index), key);
+    const exists = fs.existsSync(source);
+    if (exists) copyIfPresent(source, destination);
+    return { source, destination, exists };
+  }));
+}
+
+// Serializes install/uninstall. A dead install process leaves a recoverable lock, not a permanent block.
+async function withLock(current, action) {
+  const file = `${current.installDir}.lock`;
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  let fd;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try { fd = fs.openSync(file, 'wx', 0o600); break; }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const pid = Number(fs.readFileSync(file, 'utf8'));
+      if (!Number.isInteger(pid) || pid <= 0) throw new Error(`安装锁无效，请检查：${file}`);
+      try { process.kill(pid, 0); }
+      catch (failure) {
+        if (failure.code === 'ESRCH') { fs.rmSync(file); continue; }
+        throw failure;
+      }
+      throw new Error('另一个安装或卸载任务正在运行');
+    }
+  }
+  if (fd === undefined) throw new Error('无法取得安装锁');
+  fs.writeFileSync(fd, String(process.pid));
+  try { return await action(); }
+  finally { fs.closeSync(fd); fs.rmSync(file, { force: true }); }
+}
+
+function selectSettings(current, legacy, env, observe) {
+  const saved = readJson(path.join(current.installDir, 'settings.json'))
+    ?? readJson(path.join(legacy.installDir, 'settings.json')) ?? {};
+  return {
+    app: env.CODEX_RINGSIDE_APP || env.CODEX_PLUS_APP || saved.app || DEFAULT_APP,
+    allowClientRestart: observe === undefined ? saved.allowClientRestart !== false : !observe
+  };
+}
+
+function copyUserData(source, stage, destination) {
+  for (const name of ['background.json', 'background', 'user-images']) {
+    copyIfPresent(path.join(source, name), path.join(stage, name));
+  }
+  const file = path.join(stage, 'background.json');
+  const config = readJson(file);
+  // An image stored inside the old managed directory must survive that directory being archived.
+  if (typeof config?.image === 'string') {
+    const relative = path.relative(source, config.image);
+    if (relative && !relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative)) {
+      const name = path.join('user-images', `imported${path.extname(config.image)}`);
+      copyIfPresent(config.image, path.join(stage, name));
+      config.image = path.join(destination, name);
+      writeJson(file, config);
+    }
+  }
+}
+
+async function install(options = {}) {
+  const { current, legacy, backupRoot, repoRoot, services } = { ...defaults, ...options };
+  return withLock(current, async () => {
+    const settings = selectSettings(current, legacy, options.env ?? process.env, options.observe);
+    const checked = await (options.preflight ?? preflight)(settings);
+    settings.app = checked.app;
+    const stage = fs.mkdtempSync(`${current.installDir}.staging-`);
+    const locations = [current, legacy];
+    let backup;
+    let snapshots;
+    let running;
+    let touched = false;
+    try {
+      fs.cpSync(path.join(repoRoot, 'src'), path.join(stage, 'src'), { recursive: true });
+      for (const name of ['package.json', 'LICENSE', 'NOTICE']) fs.copyFileSync(path.join(repoRoot, name), path.join(stage, name));
+      await (options.compile ?? compile)(repoRoot, stage);
+      fs.mkdirSync(backupRoot, { recursive: true, mode: 0o700 });
+      backup = fs.mkdtempSync(path.join(backupRoot, 'install-'));
+      snapshots = capture(locations, backup);
+      running = locations.map(location => !!services.printJob(location.label));
+      writeJson(path.join(backup, 'receipt.json'), { locations, running, createdAt: new Date().toISOString() });
+      touched = true;
+      for (const location of locations) await services.bootout(location.label);
+
+      // Copy after stopping writers. Existing Ringside data takes precedence over legacy data.
+      const dataRoot = fs.existsSync(path.join(current.installDir, 'settings.json')) ? current.installDir : legacy.installDir;
+      copyUserData(dataRoot, stage, current.installDir);
+      const cooldown = Math.max(...locations.map(location => {
+        const value = readJson(path.join(location.installDir, 'state.json'))?.lastAttemptAt;
+        return Number.isFinite(value) ? value : 0;
+      }));
+      writeJson(path.join(stage, 'settings.json'), settings);
+      writeJson(path.join(stage, 'state.json'), { lastAttemptAt: cooldown });
+      fs.rmSync(current.installDir, { recursive: true, force: true });
+      fs.renameSync(stage, current.installDir);
+      fs.mkdirSync(current.logDir, { recursive: true, mode: 0o700 });
+      services.writePlist(services.agentConfig({ ...current, node: checked.node }), current.plist);
+      const startedAt = Date.now();
+      services.bootstrap(current.plist);
+      await (options.waitReady ?? waitReady)(current, startedAt);
+      for (const key of ['installDir', 'logDir', 'plist']) fs.rmSync(legacy[key], { recursive: true, force: true });
+      return { backup, settings };
+    } catch (error) {
+      const failures = [];
+      if (touched) {
+        for (const location of locations) {
+          try { await services.bootout(location.label); } catch (failure) { failures.push(failure); }
+        }
+        // Never replace files underneath a job we could not stop.
+        if (locations.some(location => services.printJob(location.label))) {
+          throw new Error(`安装失败，后台任务无法停止；备份保留在 ${backup}。原因：${error.message}`, { cause: error });
+        }
+        for (const item of snapshots) {
+          try {
+            fs.rmSync(item.source, { recursive: true, force: true });
+            if (item.exists) copyIfPresent(item.destination, item.source);
+          } catch (failure) { failures.push(failure); }
+        }
+        for (let i = 0; i < locations.length; i++) {
+          if (running[i]) {
+            try { services.bootstrap(locations[i].plist); } catch (failure) { failures.push(failure); }
+          }
+        }
+      }
+      throw new Error(`${error.message}${touched ? `；已尝试恢复原安装，备份：${backup}` : ''}${failures.length ? `；恢复失败：${failures.map(f => f.message).join(' / ')}` : ''}`, { cause: error });
+    } finally {
+      fs.rmSync(stage, { recursive: true, force: true });
+    }
+  });
+}
+
+async function uninstall(options = {}) {
+  const { current, legacy, trashRoot, services } = { ...defaults, ...options };
+  return withLock(current, async () => {
+    const locations = [current, legacy];
+    const running = locations.map(location => !!services.printJob(location.label));
+    const items = locations.flatMap((location, i) => launchd.trashItems(location)
+      .filter(([file]) => fs.existsSync(file)).map(([file, name]) => [file, `${i ? 'CodexPlus' : 'CodexRingside'}-${name}`]));
+    if (!items.length && !running.some(Boolean)) return null;
+    fs.mkdirSync(trashRoot, { recursive: true, mode: 0o700 });
+    const trash = fs.mkdtempSync(path.join(trashRoot, 'CodexRingside-'));
+    const moved = [];
+    try {
+      for (const location of locations) await services.bootout(location.label);
+      await options.removeUi?.();
+      for (const [file, name] of items) {
+        const destination = path.join(trash, name);
+        fs.renameSync(file, destination);
+        moved.push([file, destination]);
+      }
+      return trash;
+    } catch (error) {
+      for (const [file, destination] of moved.reverse()) fs.renameSync(destination, file);
+      for (let i = 0; i < locations.length; i++) if (running[i] && !services.printJob(locations[i].label)) services.bootstrap(locations[i].plist);
+      throw error;
+    }
+  });
+}
+
+module.exports = { install, uninstall, selectSettings };

package/src/launchd.cjs

@@ -0,0 +1,91 @@
+'use strict';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const LABEL = 'com.codexringside.agent';
+const home = os.homedir();
+const paths = {
+  installDir: path.join(home, 'Library/Application Support/CodexRingside'),
+  logDir: path.join(home, 'Library/Logs/CodexRingside'),
+  plist: path.join(home, 'Library/LaunchAgents', `${LABEL}.plist`)
+};
+const LEGACY_LABEL = 'com.codexplus.agent';
+const legacyPaths = {
+  installDir: path.join(home, 'Library/Application Support/CodexPlus'),
+  logDir: path.join(home, 'Library/Logs/CodexPlus'),
+  plist: path.join(home, 'Library/LaunchAgents', `${LEGACY_LABEL}.plist`)
+};
+const domain = () => `gui/${process.getuid()}`;
+
+// [installed path, name inside the Trash folder]. The two directories share a basename.
+const trashItems = (locations = paths) => [
+  [locations.installDir, 'Application Support'],
+  [locations.logDir, 'Logs'],
+  [locations.plist, path.basename(locations.plist)]
+];
+
+const escapeXml = value => String(value)
+  .replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+
+function xml(value) {
+  if (typeof value === 'boolean') return value ? '<true/>' : '<false/>';
+  if (typeof value === 'number') return `<integer>${value}</integer>`;
+  if (Array.isArray(value)) return `<array>${value.map(xml).join('')}</array>`;
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value).map(([key, item]) => `<key>${escapeXml(key)}</key>${xml(item)}`);
+    return `<dict>${entries.join('')}</dict>`;
+  }
+  return `<string>${escapeXml(value)}</string>`;
+}
+
+function plistXml(value) {
+  return '<?xml version="1.0" encoding="UTF-8"?>\n'
+    + '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n'
+    + `<plist version="1.0">${xml(value)}</plist>\n`;
+}
+
+function agentConfig({ node, installDir = paths.installDir, logDir = paths.logDir, label = LABEL }) {
+  return {
+    Label: label,
+    ProgramArguments: [node, path.join(installDir, 'src/agent.cjs')],
+    RunAtLoad: true,
+    KeepAlive: { SuccessfulExit: false },
+    ThrottleInterval: 10,
+    ProcessType: 'Background',
+    StandardOutPath: path.join(logDir, 'agent.log'),
+    StandardErrorPath: path.join(logDir, 'agent.err.log')
+  };
+}
+
+const launchctl = (...args) => execFileSync('/bin/launchctl', args, {
+  encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'pipe']
+});
+
+function printJob(label = LABEL) {
+  try {
+    return launchctl('print', `${domain()}/${label}`);
+  } catch {
+    return null;
+  }
+}
+
+function bootstrap(plist = paths.plist) {
+  launchctl('bootstrap', domain(), plist);
+}
+
+async function bootout(label = LABEL) {
+  if (!printJob(label)) return;
+  launchctl('bootout', `${domain()}/${label}`);
+  for (let i = 0; i < 50 && printJob(label); i++) await new Promise(resolve => setTimeout(resolve, 100));
+  if (printJob(label)) throw new Error(`后台任务未退出：${label}`);
+}
+
+function writePlist(config, file = paths.plist) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, plistXml(config), { mode: 0o644 });
+  execFileSync('/usr/bin/plutil', ['-lint', file], { stdio: 'ignore' });
+}
+
+module.exports = { LABEL, LEGACY_LABEL, legacyPaths, agentConfig, bootout, bootstrap, paths, plistXml, printJob, trashItems, writePlist };

package/src/limits.cjs

@@ -0,0 +1,146 @@
+'use strict';
+// Pure helpers: turn an account/rateLimits/read response into what the card renders.
+
+const FIVE_HOURS = 300;
+const ONE_WEEK = 10080;
+const ONE_MONTH = 43200;
+
+const isRecord = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const hasField = (value, key) => isRecord(value) && Object.hasOwn(value, key);
+const validWindow = value => isRecord(value) && Number.isFinite(value.usedPercent);
+const isCodexLimit = value => value?.limitId == null || value.limitId === 'codex';
+const near = (minutes, target) => Math.abs((minutes ?? 0) - target) <= 1;
+
+function remainingPercent(used) {
+  return Math.max(0, Math.min(100, Math.round(100 - used)));
+}
+
+function tone(percent) {
+  if (!Number.isFinite(percent)) return 'muted';
+  if (percent < 10) return 'danger';
+  return percent <= 50 ? 'warning' : 'normal';
+}
+
+function windowLabels(minutes) {
+  if (near(minutes, FIVE_HOURS)) return { short: '5小时', long: '5 小时额度' };
+  if (near(minutes, ONE_WEEK)) return { short: '周', long: '每周额度' };
+  if (near(minutes, ONE_MONTH)) return { short: '月', long: '每月额度' };
+  for (const [unit, label] of [[1440, '天'], [60, '小时']]) {
+    if (minutes > 0 && minutes % unit === 0) {
+      return { short: `${minutes / unit}${label}`, long: `${minutes / unit} ${label}额度` };
+    }
+  }
+  return { short: '额度', long: '额度' };
+}
+
+function formatResetTime(seconds) {
+  if (!Number.isFinite(seconds) || seconds <= 0) return null;
+  const date = new Date(seconds * 1000);
+  if (!Number.isFinite(date.getTime())) return null;
+  return new Intl.DateTimeFormat('zh-CN', {
+    month: 'numeric', day: 'numeric', hour: '2-digit', minute: '2-digit', hour12: false
+  }).format(date);
+}
+
+function pickCodexSnapshot(response) {
+  if (!isRecord(response)) return null;
+  if (hasField(response.rateLimitsByLimitId, 'codex')) {
+    const keyed = response.rateLimitsByLimitId.codex;
+    return isRecord(keyed) && isCodexLimit(keyed) ? keyed : null;
+  }
+  if (hasField(response, 'rateLimits')) {
+    return isRecord(response.rateLimits) && isCodexLimit(response.rateLimits) ? response.rateLimits : null;
+  }
+  return null;
+}
+
+function mergeWindow(current, patch) {
+  if (patch === undefined) return current ?? null;
+  if (!isRecord(patch)) return null;
+  const sameWindow = current
+    && (!Number.isFinite(patch.windowDurationMins) || current.windowDurationMins === patch.windowDurationMins);
+  return sameWindow ? { ...current, ...patch } : { ...patch };
+}
+
+function mergeSnapshot(current, patch) {
+  if (patch === undefined) return current ?? null;
+  if (!isRecord(patch)) return null;
+  // A plan change means a different account: nothing from the old windows applies.
+  const base = current?.planType && patch.planType && current.planType !== patch.planType ? null : current;
+  return {
+    ...base,
+    ...patch,
+    primary: mergeWindow(base?.primary, patch.primary),
+    secondary: mergeWindow(base?.secondary, patch.secondary)
+  };
+}
+
+// account/rateLimits/updated carries deltas; a read is a full snapshot (pass current = null).
+function mergeResponse(current, patch) {
+  if (patch === undefined) return current ?? null;
+  if (!isRecord(patch)) return null;
+  const changedAccount = hasField(patch, 'accountId') && hasField(current, 'accountId')
+    && patch.accountId !== current.accountId;
+  const base = changedAccount ? {} : current ?? {};
+  const merged = { ...base, ...patch };
+  merged.rateLimits = base.rateLimits ?? null;
+  if (isRecord(base.rateLimitsByLimitId)) merged.rateLimitsByLimitId = base.rateLimitsByLimitId;
+
+  if (hasField(patch, 'rateLimits') && isCodexLimit(patch.rateLimits)) {
+    merged.rateLimits = mergeSnapshot(base.rateLimits, patch.rateLimits);
+    if (isRecord(base.rateLimitsByLimitId)) {
+      merged.rateLimitsByLimitId = { ...base.rateLimitsByLimitId, codex: merged.rateLimits };
+    }
+  }
+
+  if (hasField(patch, 'rateLimitsByLimitId')) {
+    if (!isRecord(patch.rateLimitsByLimitId)) {
+      merged.rateLimitsByLimitId = null;
+      if (!hasField(patch, 'rateLimits')) merged.rateLimits = null;
+    } else {
+      const next = { ...merged.rateLimitsByLimitId };
+      for (const [id, snapshot] of Object.entries(patch.rateLimitsByLimitId)) {
+        const previous = base.rateLimitsByLimitId?.[id] ?? (id === 'codex' ? base.rateLimits : null);
+        Object.defineProperty(next, id, {
+          value: mergeSnapshot(previous, snapshot), enumerable: true, configurable: true, writable: true
+        });
+      }
+      merged.rateLimitsByLimitId = next;
+      if (hasField(next, 'codex')) merged.rateLimits = next.codex;
+    }
+  }
+  return merged;
+}
+
+function formatUsage(response) {
+  const snapshot = pickCodexSnapshot(response);
+  const windows = [snapshot?.primary, snapshot?.secondary]
+    .filter(validWindow)
+    .sort((a, b) => (a.windowDurationMins ?? 0) - (b.windowDurationMins ?? 0));
+  const rings = windows.map(window => {
+    const labels = windowLabels(window.windowDurationMins);
+    const percent = remainingPercent(window.usedPercent);
+    return { label: labels.short, name: labels.long, percent, tone: tone(percent), resetsAt: formatResetTime(window.resetsAt) };
+  });
+  return {
+    rings,
+    message: rings.length ? null : '暂时无法读取 Codex 剩余额度',
+    note: resetCreditsNote(response)
+  };
+}
+
+function resetCreditsNote(response) {
+  const count = Number(response?.rateLimitResetCredits?.availableCount);
+  return Number.isFinite(count) && count > 0 ? `重置卡：${Math.floor(count)} 张可用` : null;
+}
+
+function unavailable(value, message = '暂时无法读取 Codex 剩余额度，正在重试') {
+  return {
+    ...value,
+    message,
+    stale: true,
+    rings: (value?.rings ?? []).map(ring => ({ ...ring, percent: null, tone: 'muted', resetsAt: null }))
+  };
+}
+
+module.exports = { formatResetTime, formatUsage, mergeResponse, pickCodexSnapshot, remainingPercent, tone, unavailable };

package/src/resolve.cjs

@@ -0,0 +1,51 @@
+'use strict';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const DEFAULT_APP = '/Applications/ChatGPT.app';
+const MIN_NODE_MAJOR = 22;
+
+function isExecutable(file) {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// Always this client's own CLI: a PATH install can lag behind what the desktop app expects.
+function resolveCodexBin(appPath = DEFAULT_APP) {
+  const found = [
+    `${appPath}/Contents/Resources/codex-cli/bin/codex`,
+    `${appPath}/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex`,
+    `${appPath}/Contents/Resources/codex`
+  ].find(isExecutable);
+  if (!found) throw new Error(`找不到 ${appPath} 内置的 Codex CLI`);
+  return found;
+}
+
+function nodeMajor(file) {
+  try {
+    const version = execFileSync(file, ['--version'], { encoding: 'utf8', timeout: 5000 });
+    return Number(version.match(/^v(\d+)/)?.[1]);
+  } catch {
+    return 0;
+  }
+}
+
+// Prefer a stable symlink: Homebrew's real path contains the version and vanishes on upgrade.
+function resolveNode() {
+  const found = ['/opt/homebrew/bin/node', '/usr/local/bin/node', process.execPath]
+    .find(file => isExecutable(file) && nodeMajor(file) >= MIN_NODE_MAJOR);
+  if (!found) throw new Error(`需要 Node.js ${MIN_NODE_MAJOR} 或更高版本`);
+  return found;
+}
+
+function authFile() {
+  return path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'auth.json');
+}
+
+module.exports = { DEFAULT_APP, MIN_NODE_MAJOR, authFile, isExecutable, resolveCodexBin, resolveNode };

package/src/startup/controller.cjs

@@ -0,0 +1,157 @@
+'use strict';
+
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+const MAX_LAUNCH_AGE_MS = 8000;
+const QUIT_TIMEOUT_MS = 10000;
+
+// Decides whether a freshly opened Codex may be swapped for one with the debugging port.
+// All side effects go through `adapter`, so every guard below is testable without a real app.
+class StartupController {
+  constructor(adapter, { now = Date.now, sleep = delay, lastAttemptAt = 0, cooldownMs = 120000, allowClientRestart = true } = {}) {
+    Object.assign(this, { adapter, now, sleep, lastAttemptAt, cooldownMs });
+    this.allowClientRestart = allowClientRestart === true;
+    this.seen = new Set();
+    this.baselined = false;
+    this.busy = false;
+    this.stopped = false;
+    this.pendingLaunch = false;
+  }
+
+  stop() {
+    this.stopped = true;
+  }
+
+  remember(apps) {
+    for (const app of apps) this.seen.add(app.key);
+  }
+
+  async tick() {
+    if (this.busy || this.stopped) return;
+    this.busy = true;
+    this.pendingLaunch = false;
+    try {
+      await this.evaluate();
+    } catch (error) {
+      await this.adapter.record('error', { message: error.message }).catch(() => {});
+    } finally {
+      this.busy = false;
+    }
+  }
+
+  async evaluate() {
+    const snapshot = await this.adapter.snapshot();
+    if (!this.allowClientRestart) {
+      this.seen = new Set(snapshot.apps.map(app => app.key));
+      this.baselined = true;
+      await this.adapter.record('observing', { existingApps: snapshot.apps.length });
+      return;
+    }
+    // Anything already running when we start is somebody's work session: never touch it.
+    if (!this.baselined) {
+      this.remember(snapshot.apps);
+      this.baselined = true;
+      await this.adapter.record('watching', { existingApps: snapshot.apps.length });
+      return;
+    }
+
+    const fresh = snapshot.apps.filter(app => !this.seen.has(app.key));
+    if (this.seen.size > 256) this.seen = new Set(snapshot.apps.map(app => app.key));
+    if (fresh.length !== 1 || snapshot.apps.length !== 1) {
+      this.remember(snapshot.apps);
+      return;
+    }
+
+    const app = fresh[0];
+    const age = this.now() - app.launchedAt;
+    if (!app.argumentsKnown || app.debugPort !== null) {
+      this.seen.add(app.key);
+      return;
+    }
+    const untouched = age >= 0 && age <= MAX_LAUNCH_AGE_MS && snapshot.inputIdleMs >= age;
+    // Never interrupt a partially initialized app; look again shortly.
+    if (untouched && (!app.finishedLaunching || snapshot.frontmostPid !== app.pid)) {
+      this.pendingLaunch = true;
+      return;
+    }
+
+    // Remember rejected candidates too, so a running window is never revisited later.
+    this.seen.add(app.key);
+    if (!untouched || snapshot.frontmostPid !== app.pid) {
+      await this.adapter.record('skipped-active-or-background');
+      return;
+    }
+    if (this.lastAttemptAt && this.now() - this.lastAttemptAt < this.cooldownMs) {
+      await this.adapter.record('skipped-cooldown');
+      return;
+    }
+    if (await this.adapter.portInUse()) {
+      await this.adapter.record('port-in-use');
+      return;
+    }
+    await this.handoff(app, snapshot);
+  }
+
+  async handoff(app, snapshot) {
+    if (this.stopped) return;
+    // The receipt must be durable before quitting, so a crash here cannot become a restart loop.
+    this.lastAttemptAt = this.now();
+    await this.adapter.record('attempt', { lastAttemptAt: this.lastAttemptAt, processKey: app.key });
+    if (this.stopped) return;
+
+    const quit = await this.adapter.quit(app, snapshot.inputStamp);
+    if (!quit.accepted) {
+      await this.adapter.record('quit-refused');
+      return;
+    }
+
+    const absent = await this.waitForExit(app);
+    if (!absent) return;
+
+    await this.sleep(250);
+    const beforeLaunch = await this.adapter.snapshot();
+    if (this.stopped || beforeLaunch.apps.length) {
+      this.remember(beforeLaunch.apps);
+      await this.adapter.record('reopen-canceled');
+      return;
+    }
+
+    // Past a successful quit, input only suppresses focus; the app itself is always reopened.
+    const opened = await this.adapter.launch();
+    if (!opened.launched) {
+      await this.adapter.record('launch-failed');
+      return;
+    }
+    if (opened.key) this.seen.add(opened.key);
+    if (this.stopped) return;
+
+    const beforeShow = await this.adapter.snapshot();
+    this.remember(beforeShow.apps);
+    const undisturbed = absent.inputStamp === snapshot.inputStamp
+      && beforeLaunch.inputStamp === snapshot.inputStamp
+      && beforeShow.inputStamp === snapshot.inputStamp
+      && beforeShow.frontmostPid === beforeLaunch.frontmostPid
+      && !beforeShow.apps.some(current => current.key !== opened.key);
+    const shown = undisturbed && !this.stopped
+      ? await this.adapter.show(opened, snapshot.inputStamp, beforeLaunch.frontmostPid)
+      : { shown: false };
+    await this.adapter.record('reopened', { shown: !!shown.shown, processKey: opened.key });
+  }
+
+  async waitForExit(app) {
+    const deadline = this.now() + QUIT_TIMEOUT_MS;
+    while (!this.stopped && this.now() < deadline) {
+      await this.sleep(200);
+      const current = await this.adapter.snapshot();
+      if (current.apps.some(other => other.key !== app.key)) {
+        this.remember(current.apps);
+        await this.adapter.record('another-instance-started');
+        return null;
+      }
+      if (current.apps.length === 0) return current;
+    }
+    if (!this.stopped) await this.adapter.record('quit-timeout');
+    return null;
+  }
+}
+
+module.exports = { StartupController };