@bakapiano/ccsm 0.14.0 → 0.15.0

package/bin/ccsm.js

@@ -1,194 +1,194 @@
-#!/usr/bin/env node
-'use strict';
-
-// ccsm launcher · entry point for `ccsm` / `npx @bakapiano/ccsm`.
-//
-// Two modes by how it's invoked:
-//
-//   plain `ccsm`           → start backend if not running, open a browser
-//                            window pointing at it. Terminal returns to a
-//                            prompt immediately (detached).
-//
-//   `ccsm ccsm://<action>` → fired by Windows when the user clicks a
-//                            ccsm:// link (PWA offline banner). Same
-//                            backend startup as above, but DO NOT spawn
-//                            an extra browser — the PWA window that
-//                            triggered the click is already open and
-//                            will reconnect as soon as the backend
-//                            becomes reachable.
-//
-// In both modes, if a server is already running we just ping it. New
-// browser window opens only in the plain-`ccsm` case.
-
-const path = require('node:path');
-const fs = require('node:fs');
-const os = require('node:os');
-const http = require('node:http');
-const { spawn } = require('node:child_process');
-
-const SERVER = path.join(__dirname, '..', 'server.js');
-const HOME = process.env.CCSM_HOME || path.join(os.homedir(), '.ccsm');
-const LOG  = path.join(HOME, 'server.log');
-
-function loadPreferredPort() {
-  try {
-    const cfg = JSON.parse(fs.readFileSync(path.join(HOME, 'config.json'), 'utf8'));
-    return Number(cfg.port) || 7777;
-  } catch {
-    return 7777;
-  }
-}
-
-function probe(port, timeoutMs = 800) {
-  return new Promise((resolve) => {
-    const req = http.get(`http://localhost:${port}/api/health`, { timeout: timeoutMs }, (res) => {
-      let body = '';
-      res.on('data', (c) => body += c);
-      res.on('end', () => {
-        try {
-          const j = JSON.parse(body);
-          resolve(j && j.name === '@bakapiano/ccsm' ? j : null);
-        } catch { resolve(null); }
-      });
-    });
-    req.on('error',   () => resolve(null));
-    req.on('timeout', () => { req.destroy(); resolve(null); });
-  });
-}
-
-function post(port, pathname, timeoutMs = 2000) {
-  return new Promise((resolve) => {
-    const req = http.request({
-      hostname: 'localhost', port, path: pathname, method: 'POST',
-      headers: { 'Content-Type': 'application/json', 'Content-Length': 2 },
-      timeout: timeoutMs,
-    }, (res) => {
-      res.resume();
-      res.on('end', () => resolve(res.statusCode < 300));
-    });
-    req.on('error',   () => resolve(false));
-    req.on('timeout', () => { req.destroy(); resolve(false); });
-    req.write('{}');
-    req.end();
-  });
-}
-
-// Detect ccsm:// protocol invocation. Windows runs us as
-// `ccsm.cmd ccsm://start` when the user clicks a protocol link.
-// argv layout: [node, ccsm.js, "ccsm://..."]
-function parseProtocolArg() {
-  const a = process.argv[2];
-  if (!a || !/^ccsm:\/\//i.test(a)) return null;
-  try {
-    // Normalise: ccsm://start or ccsm://start?foo=bar
-    const u = new URL(a);
-    // host is the action (`start`, `restart`, ...); empty host means
-    // the URL was `ccsm:start` or `ccsm:///action`
-    const action = (u.hostname || u.pathname.replace(/^\/+/, '').split('/')[0] || '').toLowerCase();
-    return { action, raw: a };
-  } catch {
-    return { action: '', raw: a };
-  }
-}
-
-// Compare what's running with what's installed. Returns true if they
-// match (or running is unknown). False means we should restart so the
-// new code takes over after an `npm i -g @bakapiano/ccsm@latest`.
-function isSameVersion(running) {
-  try {
-    const installed = require('../package.json').version;
-    return running.version === installed;
-  } catch { return true; }
-}
-
-(async () => {
-  const protocol = parseProtocolArg();
-  const SILENT = !!protocol;  // ccsm:// invocations should not open a new browser
-  const port = loadPreferredPort();
-
-  // Case 1: existing instance on the preferred port
-  let existing = await probe(port);
-
-  // If an old version is running, ask it to shut down so the freshly
-  // installed code can take over. The launcher then falls through to
-  // Case 2 and spawns the new server itself.
-  if (existing && !isSameVersion(existing)) {
-    const installed = require('../package.json').version;
-    console.log(`ccsm upgrading · running v${existing.version} → installed v${installed}`);
-    await post(port, '/api/shutdown');
-    // Wait for the old process to actually exit so its port frees up.
-    for (let i = 0; i < 30; i++) {
-      await new Promise((r) => setTimeout(r, 200));
-      if (!(await probe(port, 200))) { existing = null; break; }
-    }
-  }
-
-  if (existing) {
-    if (!SILENT) {
-      const opened = await post(port, '/api/spawn-browser');
-      console.log(`ccsm already running · v${existing.version} · http://localhost:${port}`);
-      if (!opened) console.log('(could not open a new window — server might be busy)');
-    } else {
-      console.log(`ccsm already running · ${protocol.raw}`);
-    }
-    return;
-  }
-
-  // Case 2: spawn detached server
-  fs.mkdirSync(HOME, { recursive: true });
-  const out = fs.openSync(LOG, 'a');
-  fs.writeSync(out, `\n[${new Date().toISOString()}] ccsm starting (protocol=${protocol?.raw || '-'})...\n`);
-
-  const child = spawn(process.execPath, [SERVER], {
-    detached: true,
-    stdio: ['ignore', out, out],
-    windowsHide: true,
-    env: {
-      ...process.env,
-      CCSM_LAUNCHER: '1',
-      // Suppress the server's own auto-spawn of a browser when this launch
-      // came from a ccsm:// click — the PWA window that fired it is the
-      // browser, and a second window would just be noise.
-      ...(SILENT ? { CCSM_NO_BROWSER: '1' } : {}),
-    },
-  });
-  child.unref();
-
-  // Poll /api/health for up to ~10s. Once it answers we know the server
-  // is fully booted (port is bound, config loaded, snapshot loop running).
-  // The actual port may differ from the preferred one if it was taken,
-  // so on each iteration we re-probe the preferred port first, then fall
-  // back to scanning preferred+1..preferred+9.
-  const portsToTry = [port, ...Array.from({ length: 9 }, (_, i) => port + i + 1)];
-  let actualPort = null;
-  let ready = null;
-  outer:
-  for (let i = 0; i < 50; i++) {
-    await new Promise((r) => setTimeout(r, 200));
-    for (const p of portsToTry) {
-      const r = await probe(p, 300);
-      if (r) { ready = r; actualPort = p; break outer; }
-    }
-  }
-  if (!ready) {
-    console.error(`ccsm server did not come up in 10s. Check ${LOG}`);
-    process.exit(1);
-  }
-  console.log(`ccsm started · v${ready.version}`);
-  console.log(`backend:  http://localhost:${actualPort}${actualPort !== port ? `  (preferred ${port} was taken)` : ''}`);
-  console.log(`frontend: https://bakapiano.github.io/ccsm/v1/`);
-  console.log(`logs:     ${LOG}`);
-
-  // First-run hint — printed once, then a marker file makes us quiet.
-  const firstRunMark = path.join(HOME, '.first-run-shown');
-  if (!fs.existsSync(firstRunMark)) {
-    try { fs.writeFileSync(firstRunMark, new Date().toISOString()); } catch {}
-    console.log('');
-    console.log('First run · ccsm is now running in the background.');
-    console.log('Open the frontend URL above, click "Install ccsm" in your browser');
-    console.log('to install it as a PWA so the icon launches directly into the app.');
-  }
-})().catch((err) => {
-  console.error('ccsm launcher failed:', err);
-  process.exit(1);
-});
+#!/usr/bin/env node
+'use strict';
+
+// ccsm launcher · entry point for `ccsm` / `npx @bakapiano/ccsm`.
+//
+// Two modes by how it's invoked:
+//
+//   plain `ccsm`           → start backend if not running, open a browser
+//                            window pointing at it. Terminal returns to a
+//                            prompt immediately (detached).
+//
+//   `ccsm ccsm://<action>` → fired by Windows when the user clicks a
+//                            ccsm:// link (PWA offline banner). Same
+//                            backend startup as above, but DO NOT spawn
+//                            an extra browser — the PWA window that
+//                            triggered the click is already open and
+//                            will reconnect as soon as the backend
+//                            becomes reachable.
+//
+// In both modes, if a server is already running we just ping it. New
+// browser window opens only in the plain-`ccsm` case.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const os = require('node:os');
+const http = require('node:http');
+const { spawn } = require('node:child_process');
+
+const SERVER = path.join(__dirname, '..', 'server.js');
+const HOME = process.env.CCSM_HOME || path.join(os.homedir(), '.ccsm');
+const LOG  = path.join(HOME, 'server.log');
+
+function loadPreferredPort() {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(HOME, 'config.json'), 'utf8'));
+    return Number(cfg.port) || 7777;
+  } catch {
+    return 7777;
+  }
+}
+
+function probe(port, timeoutMs = 800) {
+  return new Promise((resolve) => {
+    const req = http.get(`http://localhost:${port}/api/health`, { timeout: timeoutMs }, (res) => {
+      let body = '';
+      res.on('data', (c) => body += c);
+      res.on('end', () => {
+        try {
+          const j = JSON.parse(body);
+          resolve(j && j.name === '@bakapiano/ccsm' ? j : null);
+        } catch { resolve(null); }
+      });
+    });
+    req.on('error',   () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+function post(port, pathname, timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    const req = http.request({
+      hostname: 'localhost', port, path: pathname, method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': 2 },
+      timeout: timeoutMs,
+    }, (res) => {
+      res.resume();
+      res.on('end', () => resolve(res.statusCode < 300));
+    });
+    req.on('error',   () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.write('{}');
+    req.end();
+  });
+}
+
+// Detect ccsm:// protocol invocation. Windows runs us as
+// `ccsm.cmd ccsm://start` when the user clicks a protocol link.
+// argv layout: [node, ccsm.js, "ccsm://..."]
+function parseProtocolArg() {
+  const a = process.argv[2];
+  if (!a || !/^ccsm:\/\//i.test(a)) return null;
+  try {
+    // Normalise: ccsm://start or ccsm://start?foo=bar
+    const u = new URL(a);
+    // host is the action (`start`, `restart`, ...); empty host means
+    // the URL was `ccsm:start` or `ccsm:///action`
+    const action = (u.hostname || u.pathname.replace(/^\/+/, '').split('/')[0] || '').toLowerCase();
+    return { action, raw: a };
+  } catch {
+    return { action: '', raw: a };
+  }
+}
+
+// Compare what's running with what's installed. Returns true if they
+// match (or running is unknown). False means we should restart so the
+// new code takes over after an `npm i -g @bakapiano/ccsm@latest`.
+function isSameVersion(running) {
+  try {
+    const installed = require('../package.json').version;
+    return running.version === installed;
+  } catch { return true; }
+}
+
+(async () => {
+  const protocol = parseProtocolArg();
+  const SILENT = !!protocol;  // ccsm:// invocations should not open a new browser
+  const port = loadPreferredPort();
+
+  // Case 1: existing instance on the preferred port
+  let existing = await probe(port);
+
+  // If an old version is running, ask it to shut down so the freshly
+  // installed code can take over. The launcher then falls through to
+  // Case 2 and spawns the new server itself.
+  if (existing && !isSameVersion(existing)) {
+    const installed = require('../package.json').version;
+    console.log(`ccsm upgrading · running v${existing.version} → installed v${installed}`);
+    await post(port, '/api/shutdown');
+    // Wait for the old process to actually exit so its port frees up.
+    for (let i = 0; i < 30; i++) {
+      await new Promise((r) => setTimeout(r, 200));
+      if (!(await probe(port, 200))) { existing = null; break; }
+    }
+  }
+
+  if (existing) {
+    if (!SILENT) {
+      const opened = await post(port, '/api/spawn-browser');
+      console.log(`ccsm already running · v${existing.version} · http://localhost:${port}`);
+      if (!opened) console.log('(could not open a new window — server might be busy)');
+    } else {
+      console.log(`ccsm already running · ${protocol.raw}`);
+    }
+    return;
+  }
+
+  // Case 2: spawn detached server
+  fs.mkdirSync(HOME, { recursive: true });
+  const out = fs.openSync(LOG, 'a');
+  fs.writeSync(out, `\n[${new Date().toISOString()}] ccsm starting (protocol=${protocol?.raw || '-'})...\n`);
+
+  const child = spawn(process.execPath, [SERVER], {
+    detached: true,
+    stdio: ['ignore', out, out],
+    windowsHide: true,
+    env: {
+      ...process.env,
+      CCSM_LAUNCHER: '1',
+      // Suppress the server's own auto-spawn of a browser when this launch
+      // came from a ccsm:// click — the PWA window that fired it is the
+      // browser, and a second window would just be noise.
+      ...(SILENT ? { CCSM_NO_BROWSER: '1' } : {}),
+    },
+  });
+  child.unref();
+
+  // Poll /api/health for up to ~10s. Once it answers we know the server
+  // is fully booted (port is bound, config loaded, snapshot loop running).
+  // The actual port may differ from the preferred one if it was taken,
+  // so on each iteration we re-probe the preferred port first, then fall
+  // back to scanning preferred+1..preferred+9.
+  const portsToTry = [port, ...Array.from({ length: 9 }, (_, i) => port + i + 1)];
+  let actualPort = null;
+  let ready = null;
+  outer:
+  for (let i = 0; i < 50; i++) {
+    await new Promise((r) => setTimeout(r, 200));
+    for (const p of portsToTry) {
+      const r = await probe(p, 300);
+      if (r) { ready = r; actualPort = p; break outer; }
+    }
+  }
+  if (!ready) {
+    console.error(`ccsm server did not come up in 10s. Check ${LOG}`);
+    process.exit(1);
+  }
+  console.log(`ccsm started · v${ready.version}`);
+  console.log(`backend:  http://localhost:${actualPort}${actualPort !== port ? `  (preferred ${port} was taken)` : ''}`);
+  console.log(`frontend: https://bakapiano.github.io/ccsm/v1/`);
+  console.log(`logs:     ${LOG}`);
+
+  // First-run hint — printed once, then a marker file makes us quiet.
+  const firstRunMark = path.join(HOME, '.first-run-shown');
+  if (!fs.existsSync(firstRunMark)) {
+    try { fs.writeFileSync(firstRunMark, new Date().toISOString()); } catch {}
+    console.log('');
+    console.log('First run · ccsm is now running in the background.');
+    console.log('Open the frontend URL above, click "Install ccsm" in your browser');
+    console.log('to install it as a PWA so the icon launches directly into the app.');
+  }
+})().catch((err) => {
+  console.error('ccsm launcher failed:', err);
+  process.exit(1);
+});

package/lib/cliActivity.js

@@ -0,0 +1,118 @@
+'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 };
+    state.set(record.id, s);
+  }
+  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';
+  }
+  const now = Date.now();
+  if (mtimeMs !== s.lastMtimeMs) {
+    s.lastMtimeMs = mtimeMs;
+    s.lastChangedAt = now;
+  }
+  return (now - s.lastChangedAt) < WORKING_WINDOW_MS ? 'working' : 'idle';
+}
+
+function releaseSession(sessionId) { state.delete(sessionId); }
+
+module.exports = { probeActivity, releaseSession };

package/lib/codexSeed.js

@@ -0,0 +1,147 @@
+'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. Wrappers like `cxp` relocate CODEX_HOME to a
+// non-default dir (e.g. %LOCALAPPDATA%\gc2cc\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');
+
+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,
+    }, (err, stdout, stderr) => {
+      resolve({ err, stdout: String(stdout || ''), stderr: String(stderr || '') });
+    });
+  });
+}
+
+// Parse `CODEX_HOME    <path> (dir)` out of `codex doctor` output. Codex
+// formats it with variable whitespace; the `(dir)` / `(file)` suffix is
+// the easiest anchor to identify the path end.
+function parseCodexHomeFromDoctor(text) {
+  if (!text) return null;
+  const m = text.match(/\bCODEX_HOME\s+(.+?)\s*\((?:dir|file)\)/);
+  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);
+  // Wrappers like cxp 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 like cxp 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;
+}
+
+module.exports = { seedCodexSession, probeCodexHome, parseCodexHomeFromDoctor };
+