@bakapiano/ccsm 0.22.3 → 0.22.4

package/lib/cliActivity.js

@@ -1,139 +1,139 @@
-'use strict';
-
-// Detect whether each running CLI session is "working" (actively writing
-// to its transcript) or "idle" (waiting on user input). We poll the
-// transcript file's mtime on each /api/sessions request: if it moved
-// since the previous probe, the CLI is writing → working. If it hasn't
-// moved within WORKING_WINDOW_MS, idle.
-//
-// Transcript paths per CLI:
-//   claude  → ~/.claude/projects/<slug>/<cliSessionId>.jsonl
-//   codex   → <CODEX_HOME>/sessions/YYYY/MM/DD/rollout-*-<id>.jsonl
-//   copilot → ~/.copilot/session-state/<cliSessionId>/
-//
-// Resolution is cached forever per ccsm session id — once we've found
-// the file, subsequent probes are a single fs.stat().
-
-const fs = require('node:fs/promises');
-const path = require('node:path');
-const os = require('node:os');
-
-// 8s window is comfortably above the 5s frontend poll cadence — if a CLI
-// wrote anything within the last 8s we still call it working when the
-// next refresh lands.
-const WORKING_WINDOW_MS = 8000;
-
-// sessionId → { resolvedPath, lastMtimeMs, lastChangedAt }
-const state = new Map();
-
-async function fileExists(p) {
-  try { await fs.access(p); return true; }
-  catch { return false; }
-}
-
-async function resolveClaude(id) {
-  const root = path.join(os.homedir(), '.claude', 'projects');
-  let dirs;
-  try { dirs = await fs.readdir(root); } catch { return null; }
-  for (const d of dirs) {
-    const p = path.join(root, d, `${id}.jsonl`);
-    if (await fileExists(p)) return p;
-  }
-  return null;
-}
-
-async function resolveCodex(id, cliCfg) {
-  let home = null;
-  try {
-    const { probeCodexHome } = require('./codexSeed');
-    home = await probeCodexHome({ command: cliCfg.command, shell: cliCfg.shell });
-  } catch { /* probe is best-effort */ }
-  if (!home) home = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-  const root = path.join(home, 'sessions');
-  const suffix = `-${id}.jsonl`;
-  async function walk(dir, depth) {
-    if (depth > 4) return null;
-    let entries;
-    try { entries = await fs.readdir(dir, { withFileTypes: true }); }
-    catch { return null; }
-    for (const e of entries) {
-      const p = path.join(dir, e.name);
-      if (e.isDirectory()) {
-        const r = await walk(p, depth + 1);
-        if (r) return r;
-      } else if (e.isFile() && e.name.endsWith(suffix)) {
-        return p;
-      }
-    }
-    return null;
-  }
-  return walk(root, 0);
-}
-
-async function resolveCopilot(id) {
-  const p = path.join(os.homedir(), '.copilot', 'session-state', id);
-  if (await fileExists(p)) return p;
-  return null;
-}
-
-async function resolveTranscript(record, cliCfg) {
-  if (!record.cliSessionId || !cliCfg) return null;
-  switch (cliCfg.type) {
-    case 'claude':  return resolveClaude(record.cliSessionId);
-    case 'codex':   return resolveCodex(record.cliSessionId, cliCfg);
-    case 'copilot': return resolveCopilot(record.cliSessionId);
-    default: return null;
-  }
-}
-
-// Returns 'working' | 'idle' | 'unknown' for a single record.
-async function probeActivity(record, cliCfg) {
-  let s = state.get(record.id);
-  if (!s) {
-    s = { resolvedPath: null, lastMtimeMs: 0, lastChangedAt: 0, lastOutputAt: 0 };
-    state.set(record.id, s);
-  }
-  // PTY output (CLI is streaming text — thinking spinners, token output,
-  // status lines) is the strongest signal that the CLI is working. It's
-  // ALSO the only signal we have when the transcript file isn't being
-  // updated — claude/codex buffer reasoning + tool results for tens of
-  // seconds before flushing a turn, so mtime alone reports "idle"
-  // through long thinking phases. Check PTY first; short-circuit if the
-  // CLI is clearly active, skipping the fs.stat below.
-  const now = Date.now();
-  if (s.lastOutputAt && (now - s.lastOutputAt) < WORKING_WINDOW_MS) {
-    return 'working';
-  }
-  if (!s.resolvedPath) {
-    s.resolvedPath = await resolveTranscript(record, cliCfg);
-    if (!s.resolvedPath) return 'unknown';
-  }
-  let mtimeMs;
-  try { mtimeMs = (await fs.stat(s.resolvedPath)).mtimeMs; }
-  catch {
-    // File disappeared (rollover, manual delete) — drop the cache so we
-    // re-resolve on the next probe.
-    s.resolvedPath = null;
-    return 'unknown';
-  }
-  if (mtimeMs !== s.lastMtimeMs) {
-    s.lastMtimeMs = mtimeMs;
-    s.lastChangedAt = now;
-  }
-  return (now - s.lastChangedAt) < WORKING_WINDOW_MS ? 'working' : 'idle';
-}
-
-// Called from server.js's spawnCliSession onData hook. Cheap (timestamp
-// write); bound by how often the PTY emits, which is fine.
-function noteOutput(sessionId) {
-  let s = state.get(sessionId);
-  if (!s) {
-    s = { resolvedPath: null, lastMtimeMs: 0, lastChangedAt: 0, lastOutputAt: 0 };
-    state.set(sessionId, s);
-  }
-  s.lastOutputAt = Date.now();
-}
-
-function releaseSession(sessionId) { state.delete(sessionId); }
-
-module.exports = { probeActivity, noteOutput, releaseSession };
+'use strict';
+
+// Detect whether each running CLI session is "working" (actively writing
+// to its transcript) or "idle" (waiting on user input). We poll the
+// transcript file's mtime on each /api/sessions request: if it moved
+// since the previous probe, the CLI is writing → working. If it hasn't
+// moved within WORKING_WINDOW_MS, idle.
+//
+// Transcript paths per CLI:
+//   claude  → ~/.claude/projects/<slug>/<cliSessionId>.jsonl
+//   codex   → <CODEX_HOME>/sessions/YYYY/MM/DD/rollout-*-<id>.jsonl
+//   copilot → ~/.copilot/session-state/<cliSessionId>/
+//
+// Resolution is cached forever per ccsm session id — once we've found
+// the file, subsequent probes are a single fs.stat().
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+
+// 8s window is comfortably above the 5s frontend poll cadence — if a CLI
+// wrote anything within the last 8s we still call it working when the
+// next refresh lands.
+const WORKING_WINDOW_MS = 8000;
+
+// sessionId → { resolvedPath, lastMtimeMs, lastChangedAt }
+const state = new Map();
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; }
+  catch { return false; }
+}
+
+async function resolveClaude(id) {
+  const root = path.join(os.homedir(), '.claude', 'projects');
+  let dirs;
+  try { dirs = await fs.readdir(root); } catch { return null; }
+  for (const d of dirs) {
+    const p = path.join(root, d, `${id}.jsonl`);
+    if (await fileExists(p)) return p;
+  }
+  return null;
+}
+
+async function resolveCodex(id, cliCfg) {
+  let home = null;
+  try {
+    const { probeCodexHome } = require('./codexSeed');
+    home = await probeCodexHome({ command: cliCfg.command, shell: cliCfg.shell });
+  } catch { /* probe is best-effort */ }
+  if (!home) home = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  const root = path.join(home, 'sessions');
+  const suffix = `-${id}.jsonl`;
+  async function walk(dir, depth) {
+    if (depth > 4) return null;
+    let entries;
+    try { entries = await fs.readdir(dir, { withFileTypes: true }); }
+    catch { return null; }
+    for (const e of entries) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        const r = await walk(p, depth + 1);
+        if (r) return r;
+      } else if (e.isFile() && e.name.endsWith(suffix)) {
+        return p;
+      }
+    }
+    return null;
+  }
+  return walk(root, 0);
+}
+
+async function resolveCopilot(id) {
+  const p = path.join(os.homedir(), '.copilot', 'session-state', id);
+  if (await fileExists(p)) return p;
+  return null;
+}
+
+async function resolveTranscript(record, cliCfg) {
+  if (!record.cliSessionId || !cliCfg) return null;
+  switch (cliCfg.type) {
+    case 'claude':  return resolveClaude(record.cliSessionId);
+    case 'codex':   return resolveCodex(record.cliSessionId, cliCfg);
+    case 'copilot': return resolveCopilot(record.cliSessionId);
+    default: return null;
+  }
+}
+
+// Returns 'working' | 'idle' | 'unknown' for a single record.
+async function probeActivity(record, cliCfg) {
+  let s = state.get(record.id);
+  if (!s) {
+    s = { resolvedPath: null, lastMtimeMs: 0, lastChangedAt: 0, lastOutputAt: 0 };
+    state.set(record.id, s);
+  }
+  // PTY output (CLI is streaming text — thinking spinners, token output,
+  // status lines) is the strongest signal that the CLI is working. It's
+  // ALSO the only signal we have when the transcript file isn't being
+  // updated — claude/codex buffer reasoning + tool results for tens of
+  // seconds before flushing a turn, so mtime alone reports "idle"
+  // through long thinking phases. Check PTY first; short-circuit if the
+  // CLI is clearly active, skipping the fs.stat below.
+  const now = Date.now();
+  if (s.lastOutputAt && (now - s.lastOutputAt) < WORKING_WINDOW_MS) {
+    return 'working';
+  }
+  if (!s.resolvedPath) {
+    s.resolvedPath = await resolveTranscript(record, cliCfg);
+    if (!s.resolvedPath) return 'unknown';
+  }
+  let mtimeMs;
+  try { mtimeMs = (await fs.stat(s.resolvedPath)).mtimeMs; }
+  catch {
+    // File disappeared (rollover, manual delete) — drop the cache so we
+    // re-resolve on the next probe.
+    s.resolvedPath = null;
+    return 'unknown';
+  }
+  if (mtimeMs !== s.lastMtimeMs) {
+    s.lastMtimeMs = mtimeMs;
+    s.lastChangedAt = now;
+  }
+  return (now - s.lastChangedAt) < WORKING_WINDOW_MS ? 'working' : 'idle';
+}
+
+// Called from server.js's spawnCliSession onData hook. Cheap (timestamp
+// write); bound by how often the PTY emits, which is fine.
+function noteOutput(sessionId) {
+  let s = state.get(sessionId);
+  if (!s) {
+    s = { resolvedPath: null, lastMtimeMs: 0, lastChangedAt: 0, lastOutputAt: 0 };
+    state.set(sessionId, s);
+  }
+  s.lastOutputAt = Date.now();
+}
+
+function releaseSession(sessionId) { state.delete(sessionId); }
+
+module.exports = { probeActivity, noteOutput, releaseSession };

package/lib/codexSeed.js

@@ -1,183 +1,183 @@
-'use strict';
-
-// Seed a fake codex rollout file so `codex resume <uuid>` works from the
-// VERY FIRST launch — the same trick claude/copilot's `--session-id` flag
-// gives us natively. codex has no equivalent flag; its only "set the id"
-// surface is `resume <SESSION_ID>` against a file that already exists on
-// disk. We pre-write that file with one `session_meta` line carrying the
-// id + cwd ccsm pre-assigned, then spawn `codex resume <id>`. Codex picks
-// up our seed and appends its actual conversation events to it.
-//
-// Path layout (matches codex's own scheme):
-//   ~/.codex/sessions/YYYY/MM/DD/rollout-<iso-ts>-<uuid>.jsonl
-//
-// Filename timestamp uses dashes-only (codex's convention), but it's
-// purely cosmetic — codex looks up sessions by UUID, not filename.
-//
-// CODEX_HOME resolution. Some wrappers relocate CODEX_HOME to a
-// non-default dir (e.g. %LOCALAPPDATA%\<wrapper>\codex-home) so the seed has
-// to land there or `resume <id>` won't find it. We probe by running
-// `<cli.command> doctor` once per (command, shell) pair and parsing the
-// "CODEX_HOME ... (dir)" line out of its output. Cached for the life of
-// the process.
-
-const fs = require('node:fs/promises');
-const path = require('node:path');
-const os = require('node:os');
-const { execFile } = require('node:child_process');
-const { spawnEnv } = require('./winPath');
-
-function isoForFilename(d = new Date()) {
-  // 2026-05-25T15:39:11 → 2026-05-25T15-39-11 (codex strips ms + colons)
-  return d.toISOString().replace(/\.\d+Z$/, '').replace(/:/g, '-');
-}
-
-// command+shell → CODEX_HOME (or null if probe failed / not detected).
-// Module-scope so we probe at most once per (command, shell) per server.
-const codexHomeCache = new Map();
-function cacheKey(command, shell) { return `${shell || 'direct'}|${command}`; }
-
-function execWithTimeout(exe, args, { timeoutMs = 8000 } = {}) {
-  return new Promise((resolve) => {
-    execFile(exe, args, {
-      windowsHide: true,
-      timeout: timeoutMs,
-      maxBuffer: 1024 * 1024,
-      // Use the registry-merged user PATH so wrapper commands resolve
-      // even when the long-running server inherited a stale PATH at boot.
-      env: spawnEnv(),
-    }, (err, stdout, stderr) => {
-      resolve({ err, stdout: String(stdout || ''), stderr: String(stderr || '') });
-    });
-  });
-}
-
-// Pull CODEX_HOME out of a wrapper's `doctor` (or `--version`) output. Two
-// shapes appear, and we must handle BOTH:
-//   1. Diagnostic table:  `CODEX_HOME    <path> (dir)`  — only when `doctor`
-//      fully succeeds. Variable whitespace; the `(dir)`/`(file)` suffix marks
-//      the path end.
-//   2. Wrapper banner:    `CODEX_HOME=<path>`  — printed on EVERY invocation.
-//      Critical because in ccsm's non-interactive spawn `doctor` often exits
-//      non-zero (skipping the table) yet still prints this banner line, so it's
-//      the reliable source. Without it the probe returns null and the seed
-//      lands in ~/.codex instead of the wrapper's relocated home, breaking
-//      `resume <id>` ("No saved session found with ID …").
-// Some wrappers colour the label (`\x1b[7mCODEX_HOME\x1b[0m`); strip ANSI first.
-function parseCodexHomeFromDoctor(text) {
-  if (!text) return null;
-  const clean = String(text).replace(/\x1b\[[0-9;]*m/g, '');
-  let m = clean.match(/\bCODEX_HOME\s+(.+?)\s*\((?:dir|file)\)/);   // table form
-  if (!m) m = clean.match(/\bCODEX_HOME=(.+?)\s*$/m);               // banner form
-  if (!m) return null;
-  const p = m[1].trim();
-  return p || null;
-}
-
-// Build the [exe, args] needed to run `<cli.command> doctor` honouring
-// the same shell-wrapping rules webTerminal uses. Mirrors the relevant
-// bits of server.js' resolveCommand — kept local so this module doesn't
-// drag a dependency on server.js.
-function buildDoctorInvocation(command, shell) {
-  const cmd = String(command || '').replace(/^\.[\\/]/, '');
-  if (!cmd) return null;
-  if (shell === 'pwsh') {
-    return {
-      exe: 'pwsh.exe',
-      args: ['-NoLogo', '-NonInteractive', '-Command', `& { ${cmd} doctor }`],
-    };
-  }
-  if (shell === 'cmd') {
-    return {
-      exe: process.env.ComSpec || 'cmd.exe',
-      args: ['/d', '/s', '/c', `${cmd} doctor`],
-    };
-  }
-  // direct
-  if (path.isAbsolute(cmd)) {
-    const ext = path.extname(cmd).toLowerCase();
-    if (ext === '.cmd' || ext === '.bat') {
-      return { exe: process.env.ComSpec || 'cmd.exe', args: ['/d', '/s', '/c', `"${cmd}" doctor`] };
-    }
-    if (ext === '.ps1') {
-      return { exe: 'powershell.exe', args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', cmd, 'doctor'] };
-    }
-    return { exe: cmd, args: ['doctor'] };
-  }
-  // bare name on direct → defer to cmd.exe so Windows resolves via PATH
-  return { exe: process.env.ComSpec || 'cmd.exe', args: ['/d', '/s', '/c', `${cmd} doctor`] };
-}
-
-async function probeCodexHome({ command, shell }) {
-  const key = cacheKey(command, shell);
-  if (codexHomeCache.has(key)) return codexHomeCache.get(key);
-  const inv = buildDoctorInvocation(command, shell);
-  if (!inv) { codexHomeCache.set(key, null); return null; }
-  const { stdout, stderr } = await execWithTimeout(inv.exe, inv.args);
-  // Some wrappers print their banner to stderr; doctor itself prints
-  // the CODEX_HOME line to stdout. Search both to be safe.
-  const home = parseCodexHomeFromDoctor(stdout) || parseCodexHomeFromDoctor(stderr);
-  codexHomeCache.set(key, home);
-  return home;
-}
-
-async function seedCodexSession({ id, cwd, cli }) {
-  if (!id || !cwd) throw new Error('seedCodexSession: id and cwd required');
-  // Resolution order:
-  //   1. `<cli.command> doctor` probe (handles wrappers that
-  //      relocate CODEX_HOME)
-  //   2. process.env.CODEX_HOME (global override)
-  //   3. ~/.codex (codex's own default)
-  let home = null;
-  if (cli?.command) {
-    try { home = await probeCodexHome({ command: cli.command, shell: cli.shell }); }
-    catch (_) { /* probe is best-effort */ }
-  }
-  if (!home) home = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-
-  const now = new Date();
-  const yyyy = String(now.getUTCFullYear());
-  const mm = String(now.getUTCMonth() + 1).padStart(2, '0');
-  const dd = String(now.getUTCDate()).padStart(2, '0');
-  const dir = path.join(home, 'sessions', yyyy, mm, dd);
-  await fs.mkdir(dir, { recursive: true });
-  const file = path.join(dir, `rollout-${isoForFilename(now)}-${id}.jsonl`);
-  const meta = {
-    timestamp: now.toISOString(),
-    type: 'session_meta',
-    payload: {
-      id,
-      timestamp: now.toISOString(),
-      cwd,
-      originator: 'ccsm',
-      cli_version: '0.0.0',
-      source: 'ccsm-seed',
-    },
-  };
-  await fs.writeFile(file, JSON.stringify(meta) + '\n', 'utf8');
-  return file;
-}
-
-// Copy ccsm's bundled light codex syntax theme into the codex home's themes/
-// dir so `-c tui.theme=ccsm-light` resolves. This theme carries light
-// markup.inserted/deleted backgrounds, which at true-color level override
-// codex's diff palette — the only way to get a LIGHT diff on Windows, where
-// codex's own background detection (default_bg()) is compiled out and always
-// falls back to a dark diff. Idempotent (writes only when missing/changed).
-async function ensureCodexLightTheme(home) {
-  if (!home) return false;
-  const src = path.join(__dirname, 'codexThemes', 'ccsm-light.tmTheme');
-  const dstDir = path.join(home, 'themes');
-  const dst = path.join(dstDir, 'ccsm-light.tmTheme');
-  try {
-    const content = await fs.readFile(src, 'utf8');
-    await fs.mkdir(dstDir, { recursive: true });
-    let existing = null;
-    try { existing = await fs.readFile(dst, 'utf8'); } catch {}
-    if (existing !== content) await fs.writeFile(dst, content, 'utf8');
-    return true;
-  } catch { return false; }
-}
-
-module.exports = { seedCodexSession, probeCodexHome, parseCodexHomeFromDoctor, ensureCodexLightTheme };
-
+'use strict';
+
+// Seed a fake codex rollout file so `codex resume <uuid>` works from the
+// VERY FIRST launch — the same trick claude/copilot's `--session-id` flag
+// gives us natively. codex has no equivalent flag; its only "set the id"
+// surface is `resume <SESSION_ID>` against a file that already exists on
+// disk. We pre-write that file with one `session_meta` line carrying the
+// id + cwd ccsm pre-assigned, then spawn `codex resume <id>`. Codex picks
+// up our seed and appends its actual conversation events to it.
+//
+// Path layout (matches codex's own scheme):
+//   ~/.codex/sessions/YYYY/MM/DD/rollout-<iso-ts>-<uuid>.jsonl
+//
+// Filename timestamp uses dashes-only (codex's convention), but it's
+// purely cosmetic — codex looks up sessions by UUID, not filename.
+//
+// CODEX_HOME resolution. Some wrappers relocate CODEX_HOME to a
+// non-default dir (e.g. %LOCALAPPDATA%\<wrapper>\codex-home) so the seed has
+// to land there or `resume <id>` won't find it. We probe by running
+// `<cli.command> doctor` once per (command, shell) pair and parsing the
+// "CODEX_HOME ... (dir)" line out of its output. Cached for the life of
+// the process.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { execFile } = require('node:child_process');
+const { spawnEnv } = require('./winPath');
+
+function isoForFilename(d = new Date()) {
+  // 2026-05-25T15:39:11 → 2026-05-25T15-39-11 (codex strips ms + colons)
+  return d.toISOString().replace(/\.\d+Z$/, '').replace(/:/g, '-');
+}
+
+// command+shell → CODEX_HOME (or null if probe failed / not detected).
+// Module-scope so we probe at most once per (command, shell) per server.
+const codexHomeCache = new Map();
+function cacheKey(command, shell) { return `${shell || 'direct'}|${command}`; }
+
+function execWithTimeout(exe, args, { timeoutMs = 8000 } = {}) {
+  return new Promise((resolve) => {
+    execFile(exe, args, {
+      windowsHide: true,
+      timeout: timeoutMs,
+      maxBuffer: 1024 * 1024,
+      // Use the registry-merged user PATH so wrapper commands resolve
+      // even when the long-running server inherited a stale PATH at boot.
+      env: spawnEnv(),
+    }, (err, stdout, stderr) => {
+      resolve({ err, stdout: String(stdout || ''), stderr: String(stderr || '') });
+    });
+  });
+}
+
+// Pull CODEX_HOME out of a wrapper's `doctor` (or `--version`) output. Two
+// shapes appear, and we must handle BOTH:
+//   1. Diagnostic table:  `CODEX_HOME    <path> (dir)`  — only when `doctor`
+//      fully succeeds. Variable whitespace; the `(dir)`/`(file)` suffix marks
+//      the path end.
+//   2. Wrapper banner:    `CODEX_HOME=<path>`  — printed on EVERY invocation.
+//      Critical because in ccsm's non-interactive spawn `doctor` often exits
+//      non-zero (skipping the table) yet still prints this banner line, so it's
+//      the reliable source. Without it the probe returns null and the seed
+//      lands in ~/.codex instead of the wrapper's relocated home, breaking
+//      `resume <id>` ("No saved session found with ID …").
+// Some wrappers colour the label (`\x1b[7mCODEX_HOME\x1b[0m`); strip ANSI first.
+function parseCodexHomeFromDoctor(text) {
+  if (!text) return null;
+  const clean = String(text).replace(/\x1b\[[0-9;]*m/g, '');
+  let m = clean.match(/\bCODEX_HOME\s+(.+?)\s*\((?:dir|file)\)/);   // table form
+  if (!m) m = clean.match(/\bCODEX_HOME=(.+?)\s*$/m);               // banner form
+  if (!m) return null;
+  const p = m[1].trim();
+  return p || null;
+}
+
+// Build the [exe, args] needed to run `<cli.command> doctor` honouring
+// the same shell-wrapping rules webTerminal uses. Mirrors the relevant
+// bits of server.js' resolveCommand — kept local so this module doesn't
+// drag a dependency on server.js.
+function buildDoctorInvocation(command, shell) {
+  const cmd = String(command || '').replace(/^\.[\\/]/, '');
+  if (!cmd) return null;
+  if (shell === 'pwsh') {
+    return {
+      exe: 'pwsh.exe',
+      args: ['-NoLogo', '-NonInteractive', '-Command', `& { ${cmd} doctor }`],
+    };
+  }
+  if (shell === 'cmd') {
+    return {
+      exe: process.env.ComSpec || 'cmd.exe',
+      args: ['/d', '/s', '/c', `${cmd} doctor`],
+    };
+  }
+  // direct
+  if (path.isAbsolute(cmd)) {
+    const ext = path.extname(cmd).toLowerCase();
+    if (ext === '.cmd' || ext === '.bat') {
+      return { exe: process.env.ComSpec || 'cmd.exe', args: ['/d', '/s', '/c', `"${cmd}" doctor`] };
+    }
+    if (ext === '.ps1') {
+      return { exe: 'powershell.exe', args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', cmd, 'doctor'] };
+    }
+    return { exe: cmd, args: ['doctor'] };
+  }
+  // bare name on direct → defer to cmd.exe so Windows resolves via PATH
+  return { exe: process.env.ComSpec || 'cmd.exe', args: ['/d', '/s', '/c', `${cmd} doctor`] };
+}
+
+async function probeCodexHome({ command, shell }) {
+  const key = cacheKey(command, shell);
+  if (codexHomeCache.has(key)) return codexHomeCache.get(key);
+  const inv = buildDoctorInvocation(command, shell);
+  if (!inv) { codexHomeCache.set(key, null); return null; }
+  const { stdout, stderr } = await execWithTimeout(inv.exe, inv.args);
+  // Some wrappers print their banner to stderr; doctor itself prints
+  // the CODEX_HOME line to stdout. Search both to be safe.
+  const home = parseCodexHomeFromDoctor(stdout) || parseCodexHomeFromDoctor(stderr);
+  codexHomeCache.set(key, home);
+  return home;
+}
+
+async function seedCodexSession({ id, cwd, cli }) {
+  if (!id || !cwd) throw new Error('seedCodexSession: id and cwd required');
+  // Resolution order:
+  //   1. `<cli.command> doctor` probe (handles wrappers that
+  //      relocate CODEX_HOME)
+  //   2. process.env.CODEX_HOME (global override)
+  //   3. ~/.codex (codex's own default)
+  let home = null;
+  if (cli?.command) {
+    try { home = await probeCodexHome({ command: cli.command, shell: cli.shell }); }
+    catch (_) { /* probe is best-effort */ }
+  }
+  if (!home) home = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+
+  const now = new Date();
+  const yyyy = String(now.getUTCFullYear());
+  const mm = String(now.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(now.getUTCDate()).padStart(2, '0');
+  const dir = path.join(home, 'sessions', yyyy, mm, dd);
+  await fs.mkdir(dir, { recursive: true });
+  const file = path.join(dir, `rollout-${isoForFilename(now)}-${id}.jsonl`);
+  const meta = {
+    timestamp: now.toISOString(),
+    type: 'session_meta',
+    payload: {
+      id,
+      timestamp: now.toISOString(),
+      cwd,
+      originator: 'ccsm',
+      cli_version: '0.0.0',
+      source: 'ccsm-seed',
+    },
+  };
+  await fs.writeFile(file, JSON.stringify(meta) + '\n', 'utf8');
+  return file;
+}
+
+// Copy ccsm's bundled light codex syntax theme into the codex home's themes/
+// dir so `-c tui.theme=ccsm-light` resolves. This theme carries light
+// markup.inserted/deleted backgrounds, which at true-color level override
+// codex's diff palette — the only way to get a LIGHT diff on Windows, where
+// codex's own background detection (default_bg()) is compiled out and always
+// falls back to a dark diff. Idempotent (writes only when missing/changed).
+async function ensureCodexLightTheme(home) {
+  if (!home) return false;
+  const src = path.join(__dirname, 'codexThemes', 'ccsm-light.tmTheme');
+  const dstDir = path.join(home, 'themes');
+  const dst = path.join(dstDir, 'ccsm-light.tmTheme');
+  try {
+    const content = await fs.readFile(src, 'utf8');
+    await fs.mkdir(dstDir, { recursive: true });
+    let existing = null;
+    try { existing = await fs.readFile(dst, 'utf8'); } catch {}
+    if (existing !== content) await fs.writeFile(dst, content, 'utf8');
+    return true;
+  } catch { return false; }
+}
+
+module.exports = { seedCodexSession, probeCodexHome, parseCodexHomeFromDoctor, ensureCodexLightTheme };
+