synabun 1.3.0 → 2.0.0

package/neural-interface/lib/codex-request-journal.js

@@ -0,0 +1,242 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+
+export const CODEX_REQUEST_STATUSES = Object.freeze([
+  'pending',
+  'answered',
+  'dismissed',
+  'timed_out',
+  'turn_canceled',
+  'delivery_failed',
+]);
+
+const TERMINAL_STATUSES = new Set(CODEX_REQUEST_STATUSES.slice(1));
+const STORE_VERSION = 1;
+
+function cleanId(value) {
+  return value == null ? '' : String(value);
+}
+
+export function codexRequestCorrelation(value = {}) {
+  return {
+    sessionId: cleanId(value.sessionId),
+    threadId: cleanId(value.threadId),
+    turnId: cleanId(value.turnId),
+    requestId: cleanId(value.requestId),
+    toolCallId: cleanId(value.toolCallId),
+  };
+}
+
+export function codexRequestKey(value = {}) {
+  const ids = codexRequestCorrelation(value);
+  return [ids.sessionId, ids.threadId, ids.turnId, ids.requestId, ids.toolCallId]
+    .map((part) => encodeURIComponent(part))
+    .join('|');
+}
+
+export function correlationMismatch(expected, actual) {
+  const left = codexRequestCorrelation(expected);
+  const right = codexRequestCorrelation(actual);
+  for (const field of Object.keys(left)) {
+    if (left[field] && right[field] && left[field] !== right[field]) return field;
+  }
+  return '';
+}
+
+function emptyStore() {
+  return { version: STORE_VERSION, requests: {} };
+}
+
+function normalizeStore(value) {
+  return {
+    version: STORE_VERSION,
+    requests: value?.requests && typeof value.requests === 'object' ? value.requests : {},
+  };
+}
+
+export class CodexRequestJournalPersistenceError extends Error {
+  constructor(filePath, cause) {
+    super(`Could not persist the Codex request journal: ${cause?.message || cause}`);
+    this.name = 'CodexRequestJournalPersistenceError';
+    this.code = cause?.code || 'JOURNAL_WRITE_FAILED';
+    this.filePath = filePath;
+    this.retryable = true;
+    this.cause = cause;
+  }
+}
+
+export function writeCodexRequestJournalAtomically(filePath, store, suffix = Date.now()) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${suffix}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(store, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+    try { chmodSync(tmp, 0o600); } catch {}
+    renameSync(tmp, filePath);
+  } catch (error) {
+    try { if (existsSync(tmp)) unlinkSync(tmp); } catch {}
+    throw error;
+  }
+}
+
+export class CodexRequestJournal {
+  constructor(filePath, {
+    now = () => Date.now(),
+    writeStore = writeCodexRequestJournalAtomically,
+  } = {}) {
+    this.filePath = filePath;
+    this.now = now;
+    this.writeStore = writeStore;
+    this.store = this.load();
+    this.revision = 0;
+  }
+
+  load() {
+    try {
+      if (!existsSync(this.filePath)) return emptyStore();
+      return normalizeStore(JSON.parse(readFileSync(this.filePath, 'utf-8')));
+    } catch {
+      return emptyStore();
+    }
+  }
+
+  commitEntry(key, entry) {
+    const nextStore = {
+      version: STORE_VERSION,
+      requests: { ...this.store.requests, [key]: entry },
+    };
+    try {
+      this.writeStore(this.filePath, nextStore, this.now());
+    } catch (error) {
+      throw new CodexRequestJournalPersistenceError(this.filePath, error);
+    }
+    this.store = nextStore;
+    this.revision += 1;
+    return entry;
+  }
+
+  register(correlation, details = {}) {
+    const ids = codexRequestCorrelation(correlation);
+    const key = codexRequestKey(ids);
+    const existing = this.store.requests[key];
+    if (existing) return existing;
+    const createdAt = this.now();
+    const entry = {
+      key,
+      ...ids,
+      method: details.method || '',
+      status: 'pending',
+      createdAt,
+      updatedAt: createdAt,
+      answerPersistedAt: null,
+      deliveredAt: null,
+      continuationObservedAt: null,
+      deliveryAttempts: 0,
+      responseToken: '',
+      result: null,
+      error: null,
+    };
+    return this.commitEntry(key, entry);
+  }
+
+  get(correlation) {
+    return this.store.requests[codexRequestKey(correlation)] || null;
+  }
+
+  findByRequestId({ sessionId = '', requestId = '' } = {}) {
+    const matches = Object.values(this.store.requests).filter((entry) => (
+      cleanId(entry.requestId) === cleanId(requestId)
+      && (!sessionId || cleanId(entry.sessionId) === cleanId(sessionId))
+    ));
+    return matches.sort((a, b) => b.updatedAt - a.updatedAt)[0] || null;
+  }
+
+  persistAnswer(correlation, { responseToken = '', result = null, error = null } = {}) {
+    const entry = this.get(correlation);
+    if (!entry) return { ok: false, reason: 'not_found', entry: null };
+    const mismatch = correlationMismatch(entry, correlation);
+    if (mismatch) return { ok: false, reason: `mismatched_${mismatch}`, entry };
+    if (entry.status === 'answered' || entry.status === 'delivery_failed') {
+      return { ok: true, duplicate: true, entry };
+    }
+    if (TERMINAL_STATUSES.has(entry.status)) {
+      return { ok: false, reason: entry.status, entry };
+    }
+    const timestamp = this.now();
+    const nextEntry = {
+      ...entry,
+      status: 'answered',
+      updatedAt: timestamp,
+      answerPersistedAt: timestamp,
+      responseToken: cleanId(responseToken),
+      result,
+      error,
+    };
+    this.commitEntry(entry.key, nextEntry);
+    return { ok: true, duplicate: false, entry: nextEntry };
+  }
+
+  recordDelivery(correlation, { ok, error = '' } = {}) {
+    const entry = this.get(correlation);
+    if (!entry) return null;
+    const timestamp = this.now();
+    const nextEntry = {
+      ...entry,
+      deliveryAttempts: Number(entry.deliveryAttempts || 0) + 1,
+      updatedAt: timestamp,
+    };
+    if (ok) {
+      nextEntry.status = 'answered';
+      nextEntry.deliveredAt ||= timestamp;
+      // The payload is needed only for retry. Once app-server accepts it, keep
+      // lifecycle metadata but do not retain potentially sensitive answers.
+      nextEntry.result = null;
+      nextEntry.error = null;
+    } else {
+      nextEntry.status = 'delivery_failed';
+      nextEntry.error = error || 'Delivery failed';
+    }
+    return this.commitEntry(entry.key, nextEntry);
+  }
+
+  finish(correlation, status, error = '') {
+    if (!TERMINAL_STATUSES.has(status)) throw new Error(`Unknown request terminal status: ${status}`);
+    const entry = this.get(correlation);
+    if (!entry) return null;
+    if (entry.answerPersistedAt) return entry;
+    const timestamp = this.now();
+    return this.commitEntry(entry.key, {
+      ...entry,
+      status,
+      updatedAt: timestamp,
+      error: error || null,
+    });
+  }
+
+  markContinuation(correlation) {
+    const entry = this.get(correlation);
+    if (!entry || !entry.deliveredAt || entry.continuationObservedAt) return false;
+    const continuationObservedAt = this.now();
+    this.commitEntry(entry.key, {
+      ...entry,
+      continuationObservedAt,
+      updatedAt: continuationObservedAt,
+    });
+    return true;
+  }
+
+  unresolved({ sessionId = '', threadId = '' } = {}) {
+    return Object.values(this.store.requests).filter((entry) => (
+      (!sessionId || entry.sessionId === cleanId(sessionId))
+      && (!threadId || entry.threadId === cleanId(threadId))
+      && (entry.status === 'pending' || entry.status === 'delivery_failed')
+    ));
+  }
+}

package/neural-interface/lib/codex-runtime-path.js

@@ -0,0 +1,213 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const CODEX_TARGETS = {
+  'win32:x64': {
+    targetTriple: 'x86_64-pc-windows-msvc',
+    platformPackage: '@openai/codex-win32-x64',
+    binaryName: 'codex.exe',
+  },
+  'win32:arm64': {
+    targetTriple: 'aarch64-pc-windows-msvc',
+    platformPackage: '@openai/codex-win32-arm64',
+    binaryName: 'codex.exe',
+  },
+};
+
+const CODEX_VENDOR_BINARY_DIRS = ['bin', 'codex'];
+
+export function codexPlatformTarget(platform = process.platform, arch = process.arch) {
+  return CODEX_TARGETS[`${platform}:${arch}`] || null;
+}
+
+function uniquePaths(values, pathImpl) {
+  const seen = new Set();
+  const result = [];
+  for (const value of values) {
+    if (!value) continue;
+    const normalized = pathImpl.normalize(String(value).trim());
+    const key = normalized.toLowerCase();
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(normalized);
+    }
+  }
+  return result;
+}
+
+/**
+ * Pick a Windows launcher suitable for the sidepanel's shell-aware spawn path.
+ * npm lists its extensionless sh shim before the native Windows launcher, so
+ * prefer a PATHEXT-style launcher while retaining the first result as a last
+ * resort for non-npm installations.
+ */
+export function selectWindowsCodexLauncher(launchers = [], acceptLauncher = () => true) {
+  const accepted = uniquePaths(launchers, path.win32).filter(acceptLauncher);
+  return accepted.find((launcher) => /\.(cmd|exe|bat|ps1)$/i.test(launcher))
+    || accepted[0]
+    || null;
+}
+
+function packageJsonCandidatesForLauncher(launcher, pathImpl) {
+  const binDir = pathImpl.dirname(launcher);
+  const candidates = [
+    pathImpl.join(binDir, 'node_modules', '@openai', 'codex', 'package.json'),
+  ];
+  if (pathImpl.basename(binDir).toLowerCase() === '.bin') {
+    candidates.push(pathImpl.join(pathImpl.dirname(binDir), '@openai', 'codex', 'package.json'));
+  }
+  return candidates;
+}
+
+export function windowsCodexPackageJsonCandidates({
+  npmRoots = [],
+  appData = '',
+  npmConfigPrefix = '',
+  synabunPackageRoot = '',
+  nodeExecutable = '',
+} = {}) {
+  const pathImpl = path.win32;
+  const nodeModulesRoots = [...npmRoots];
+  if (appData) nodeModulesRoots.push(pathImpl.join(appData, 'npm', 'node_modules'));
+  if (npmConfigPrefix) {
+    nodeModulesRoots.push(
+      pathImpl.basename(npmConfigPrefix).toLowerCase() === 'node_modules'
+        ? npmConfigPrefix
+        : pathImpl.join(npmConfigPrefix, 'node_modules'),
+    );
+  }
+  if (
+    synabunPackageRoot
+    && pathImpl.basename(synabunPackageRoot).toLowerCase() === 'synabun'
+    && pathImpl.basename(pathImpl.dirname(synabunPackageRoot)).toLowerCase() === 'node_modules'
+  ) {
+    nodeModulesRoots.push(pathImpl.dirname(synabunPackageRoot));
+  }
+  if (nodeExecutable) {
+    nodeModulesRoots.push(pathImpl.join(pathImpl.dirname(nodeExecutable), 'node_modules'));
+  }
+  return uniquePaths(
+    nodeModulesRoots.map((root) => pathImpl.join(root, '@openai', 'codex', 'package.json')),
+    pathImpl,
+  );
+}
+
+function defaultResolvePlatformPackage(codexPackageJsonPath, platformPackage) {
+  const req = createRequire(codexPackageJsonPath);
+  return req.resolve(`${platformPackage}/package.json`);
+}
+
+function vendorBinaryCandidates(packageJsonPath, spec, pathImpl) {
+  const packageDir = pathImpl.dirname(packageJsonPath);
+  return CODEX_VENDOR_BINARY_DIRS.map((binaryDir) => pathImpl.join(
+    packageDir,
+    'vendor',
+    spec.targetTriple,
+    binaryDir,
+    spec.binaryName,
+  ));
+}
+
+/**
+ * Resolve the spawnable native Codex executable from a trusted global npm
+ * installation on Windows. `@openai/codex-sdk` uses child_process.spawn with
+ * shell:false, so npm's extensionless/.cmd launchers are not valid overrides.
+ *
+ * Dependencies are injectable so Windows path behavior can be tested on Unix.
+ */
+export function resolveTrustedWindowsCodexBinary({
+  launchers = [],
+  codexPackageJsonPaths = [],
+  arch = process.arch,
+  exists = existsSync,
+  resolvePlatformPackage = defaultResolvePlatformPackage,
+  acceptBinary = () => true,
+} = {}) {
+  const spec = codexPlatformTarget('win32', arch);
+  if (!spec) {
+    return { path: null, reason: `Unsupported Windows architecture: ${arch}`, checked: [] };
+  }
+
+  const pathImpl = path.win32;
+  const launcherPaths = uniquePaths(launchers, pathImpl);
+  const checked = [];
+
+  // A direct native executable on PATH is already suitable for SDK spawn.
+  for (const launcher of launcherPaths) {
+    checked.push(launcher);
+    if (/\.exe$/i.test(launcher) && exists(launcher) && acceptBinary(launcher)) {
+      return { path: launcher, source: 'path-exe', launcher, ...spec, checked };
+    }
+  }
+
+  const packageJsonPaths = uniquePaths([
+    ...codexPackageJsonPaths,
+    ...launcherPaths.flatMap((launcher) => packageJsonCandidatesForLauncher(launcher, pathImpl)),
+  ], pathImpl);
+
+  for (const codexPackageJsonPath of packageJsonPaths) {
+    checked.push(codexPackageJsonPath);
+    if (!exists(codexPackageJsonPath)) continue;
+
+    for (const localVendorBinary of vendorBinaryCandidates(codexPackageJsonPath, spec, pathImpl)) {
+      checked.push(localVendorBinary);
+      if (exists(localVendorBinary) && acceptBinary(localVendorBinary)) {
+        return {
+          path: localVendorBinary,
+          source: 'global-package-vendor',
+          packageJsonPath: codexPackageJsonPath,
+          ...spec,
+          checked,
+        };
+      }
+    }
+
+    let resolvedPlatformPackageJsonPath = null;
+    try {
+      resolvedPlatformPackageJsonPath = resolvePlatformPackage(
+        codexPackageJsonPath,
+        spec.platformPackage,
+      );
+    } catch (error) {
+      checked.push(`${codexPackageJsonPath} -> ${spec.platformPackage}: ${error.message}`);
+    }
+
+    // npm usually hoists the aliased platform package beside @openai/codex,
+    // but some npm versions keep it inside that package's node_modules. Check
+    // both layouts directly so package exports/hoisting do not block discovery.
+    const platformSegments = spec.platformPackage.split('/');
+    const codexPackageDir = pathImpl.dirname(codexPackageJsonPath);
+    const globalNodeModules = pathImpl.dirname(pathImpl.dirname(codexPackageDir));
+    const platformPackageJsonPaths = uniquePaths([
+      resolvedPlatformPackageJsonPath,
+      pathImpl.join(globalNodeModules, ...platformSegments, 'package.json'),
+      pathImpl.join(codexPackageDir, 'node_modules', ...platformSegments, 'package.json'),
+    ], pathImpl);
+
+    for (const platformPackageJsonPath of platformPackageJsonPaths) {
+      checked.push(platformPackageJsonPath);
+      if (!exists(platformPackageJsonPath)) continue;
+      for (const platformBinary of vendorBinaryCandidates(platformPackageJsonPath, spec, pathImpl)) {
+        checked.push(platformBinary);
+        if (exists(platformBinary) && acceptBinary(platformBinary)) {
+          return {
+            path: platformBinary,
+            source: 'global-platform-package',
+            packageJsonPath: codexPackageJsonPath,
+            platformPackageJsonPath,
+            ...spec,
+            checked,
+          };
+        }
+      }
+    }
+  }
+
+  return {
+    path: null,
+    reason: `No spawnable ${spec.binaryName} was found in the global Codex installation`,
+    ...spec,
+    checked,
+  };
+}

package/neural-interface/lib/codex-session-catalog.js

@@ -0,0 +1,231 @@
+import { existsSync, statSync } from 'node:fs';
+import { resolve, sep, win32 as pathWin32 } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+export const CODEX_RESUME_SOURCE_KINDS = ['cli', 'vscode', 'exec', 'appServer'];
+
+function comparablePath(value) {
+  const normalized = resolve(String(value || ''));
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+export function samePath(left, right, { platform = process.platform } = {}) {
+  if (!left || !right) return false;
+  const normalize = (value) => {
+    const normalized = platform === 'win32'
+      ? pathWin32.resolve(String(value || ''))
+      : resolve(String(value || ''));
+    return platform === 'win32' ? normalized.toLowerCase() : normalized;
+  };
+  return normalize(left) === normalize(right);
+}
+
+export function pathIsWithin(candidate, root) {
+  if (!candidate || !root) return false;
+  const child = comparablePath(candidate);
+  const parent = comparablePath(root);
+  return child === parent || child.startsWith(parent + sep);
+}
+
+function timestampMs(primaryMs, fallbackSeconds) {
+  const ms = Number(primaryMs);
+  if (Number.isFinite(ms) && ms > 0) return ms;
+  if (typeof primaryMs === 'string') {
+    const parsed = Date.parse(primaryMs);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  const seconds = Number(fallbackSeconds);
+  if (Number.isFinite(seconds) && seconds > 0) return seconds * 1000;
+  if (typeof fallbackSeconds === 'string') {
+    const parsed = Date.parse(fallbackSeconds);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return 0;
+}
+
+function accountLabel(account) {
+  return account?.label || account?.email || (account?.id === 'default' ? 'Default' : 'Account');
+}
+
+function selectColumn(columns, name, fallback = "''") {
+  return `${columns.has(name) ? `\"${name}\"` : fallback} AS \"${name}\"`;
+}
+
+function existingRollout(path) {
+  if (!path || !existsSync(path)) return null;
+  try {
+    const stat = statSync(path);
+    return stat.isFile() ? stat : null;
+  } catch {
+    return null;
+  }
+}
+
+function projectForCwd(cwd, projects) {
+  if (!cwd) return null;
+  return [...projects]
+    .filter((project) => project?.path && pathIsWithin(cwd, project.path))
+    .sort((a, b) => comparablePath(b.path).length - comparablePath(a.path).length)[0] || null;
+}
+
+function rowToSession(row, account, projects, rolloutStat) {
+  if (!row?.id) return null;
+  const createdAt = timestampMs(row.created_at_ms, row.created_at);
+  const updatedAt = timestampMs(
+    row.recency_at_ms || row.updated_at_ms,
+    row.recency_at || row.updated_at,
+  ) || createdAt;
+  const firstPrompt = String(row.title || row.preview || row.first_user_message || '').trim();
+  const preview = String(row.preview || row.first_user_message || row.title || '').trim();
+  const project = projectForCwd(row.cwd, projects);
+  return {
+    id: String(row.id),
+    sessionId: String(row.id),
+    name: firstPrompt,
+    title: firstPrompt,
+    firstPrompt,
+    preview,
+    source: row.source || row.thread_source || 'unknown',
+    cwd: row.cwd || '',
+    projectPath: project?.path || null,
+    projectLabel: project?.label || (project?.path ? String(project.path).split(/[\\/]/).pop() : null),
+    createdAt,
+    updatedAt,
+    created: createdAt ? new Date(createdAt).toISOString() : null,
+    modified: updatedAt ? new Date(updatedAt).toISOString() : null,
+    accountId: account.id,
+    accountLabel: accountLabel(account),
+    model: row.model || '',
+    reasoningEffort: row.reasoning_effort || '',
+    tokensUsed: Number(row.tokens_used) || 0,
+    gitBranch: row.git_branch || null,
+    messageCount: 0,
+    archived: !!row.archived,
+    resumable: !!rolloutStat,
+    rolloutPath: row.rollout_path || '',
+    fileSize: rolloutStat?.size || 0,
+    fileMtime: rolloutStat?.mtime?.toISOString?.() || null,
+  };
+}
+
+export function listCodexSessionsFromAccount(account, options = {}) {
+  if (!account?.id || !account?.home) return [];
+  const dbPath = resolve(account.home, 'state_5.sqlite');
+  if (!existsSync(dbPath)) return [];
+
+  const projects = Array.isArray(options.projects) ? options.projects : [];
+  const sourceKinds = Array.isArray(options.sourceKinds)
+    ? options.sourceKinds.map((value) => String(value || '').trim()).filter(Boolean)
+    : CODEX_RESUME_SOURCE_KINDS;
+  const includeArchived = !!options.includeArchived;
+  const includeMissingRollouts = !!options.includeMissingRollouts;
+  const cwd = options.cwd ? resolve(String(options.cwd)) : null;
+  const maxRows = Math.max(1, Number(options.maxRows) || 10000);
+
+  let db = null;
+  try {
+    db = new DatabaseSync(dbPath, { readOnly: true });
+    const columns = new Set(
+      db.prepare('PRAGMA table_info(threads)').all().map((column) => String(column?.name || '')),
+    );
+    if (!columns.has('id') || !columns.has('rollout_path')) return [];
+
+    const where = [];
+    const params = [];
+    if (!includeArchived && columns.has('archived')) where.push('archived = 0');
+    const sourceColumn = columns.has('source') ? 'source' : (columns.has('thread_source') ? 'thread_source' : '');
+    if (sourceKinds.length && sourceColumn) {
+      where.push(`\"${sourceColumn}\" IN (${sourceKinds.map(() => '?').join(', ')})`);
+      params.push(...sourceKinds);
+    }
+
+    const rows = db.prepare(`
+      SELECT ${[
+        selectColumn(columns, 'id'),
+        selectColumn(columns, 'rollout_path'),
+        selectColumn(columns, 'title'),
+        selectColumn(columns, 'preview'),
+        selectColumn(columns, 'first_user_message'),
+        selectColumn(columns, 'source'),
+        selectColumn(columns, 'thread_source'),
+        selectColumn(columns, 'cwd'),
+        selectColumn(columns, 'created_at', '0'),
+        selectColumn(columns, 'created_at_ms', '0'),
+        selectColumn(columns, 'updated_at', '0'),
+        selectColumn(columns, 'updated_at_ms', '0'),
+        selectColumn(columns, 'recency_at', '0'),
+        selectColumn(columns, 'recency_at_ms', '0'),
+        selectColumn(columns, 'model'),
+        selectColumn(columns, 'reasoning_effort'),
+        selectColumn(columns, 'tokens_used', '0'),
+        selectColumn(columns, 'git_branch'),
+        selectColumn(columns, 'archived', '0'),
+        selectColumn(columns, 'agent_path'),
+      ].join(', ')}
+      FROM threads
+      ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+      LIMIT ?
+    `).all(...params, maxRows);
+
+    const sessions = [];
+    for (const row of rows) {
+      if (row.agent_path) continue;
+      if (cwd && !pathIsWithin(row.cwd, cwd)) continue;
+      const rolloutStat = existingRollout(row.rollout_path);
+      if (!rolloutStat && !includeMissingRollouts) continue;
+      const session = rowToSession(row, account, projects, rolloutStat);
+      if (session) sessions.push(session);
+    }
+    return sortCodexSessionSummaries(sessions);
+  } finally {
+    try { db?.close(); } catch {}
+  }
+}
+
+export function listCodexSessionsFromAccounts(accounts, options = {}) {
+  const sessions = [];
+  for (const account of (Array.isArray(accounts) ? accounts : [])) {
+    try {
+      sessions.push(...listCodexSessionsFromAccount(account, options));
+    } catch (err) {
+      options.onError?.(account, err);
+    }
+  }
+  return mergeCodexSessionSummaries(sessions);
+}
+
+export function sortCodexSessionSummaries(sessions) {
+  return sessions.sort((a, b) => {
+    const bt = timestampMs(b?.updatedAt, 0) || timestampMs(b?.createdAt, 0);
+    const at = timestampMs(a?.updatedAt, 0) || timestampMs(a?.createdAt, 0);
+    if (bt !== at) return bt - at;
+    return String(b?.id || b?.sessionId || '').localeCompare(String(a?.id || a?.sessionId || ''));
+  });
+}
+
+export function mergeCodexSessionSummaries(...groups) {
+  const byKey = new Map();
+  for (const group of groups) {
+    for (const raw of (Array.isArray(group) ? group : [])) {
+      const id = raw?.id || raw?.sessionId;
+      if (!id) continue;
+      const accountId = raw.accountId || 'default';
+      const session = { ...raw, id, sessionId: raw.sessionId || id, accountId };
+      const key = `${accountId}:${id}`;
+      const previous = byKey.get(key);
+      byKey.set(key, previous ? {
+        ...previous,
+        ...session,
+        name: session.name || previous.name,
+        title: session.title || previous.title,
+        firstPrompt: session.firstPrompt || previous.firstPrompt,
+        preview: session.preview || previous.preview,
+        cwd: session.cwd || previous.cwd,
+        accountLabel: session.accountLabel || previous.accountLabel,
+        rolloutPath: session.rolloutPath || previous.rolloutPath,
+        resumable: session.resumable ?? previous.resumable,
+      } : session);
+    }
+  }
+  return sortCodexSessionSummaries([...byKey.values()]);
+}