@sanqianx/ai-coding-event-bridge-console 0.5.1 → 0.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sanqianx/ai-coding-event-bridge-console",
-  "version": "0.5.1",
-  "description": "Local console for the AI coding event bridge: project import with per-project journal storage, REST query API and a built-in conversation explorer page.",
+  "version": "0.6.0",
+  "description": "Durable AI coding event bridge, all in one: capture connectors and installers (Claude Code, Codex, OpenCode, ZCode), journal with commit boundaries and per-commit conversation sealing, headless query, and a local conversation explorer console.",
   "license": "MIT",
   "private": false,
   "repository": {
@@ -22,8 +22,5 @@
   ],
   "scripts": {
     "test": "node ../../test/run-all.js"
-  },
-  "dependencies": {
-    "@sanqianx/ai-coding-event-bridge": "0.5.0"
   }
 }

package/src/agent-detect.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const core = require('@sanqianx/ai-coding-event-bridge');
+const core = require('./bridge');
 
 /**
  * Detection of AI coding agent tools on this machine. "Installed" means the

package/src/bin.js

@@ -2,17 +2,21 @@
 'use strict';
 
 const http = require('http');
-const { bridgeHome } = require('@sanqianx/ai-coding-event-bridge');
+const { bridgeHome } = require('./bridge');
 const { createConsoleServer } = require('./server');
 const { warmFolderPicker } = require('./pick-folder');
 
 /**
- * ai-coding-event-bridge-console CLI (also reachable as
- * `ai-coding-event-bridge serve` via the core package's dispatcher).
+ * ai-coding-event-bridge-console CLI — the single package of this project.
  *
  *   serve [--port 8790] [--host 127.0.0.1] [--home DIR]
  *         Start the local console (explorer page + JSON API).
  *
+ *   commit-boundary [--cwd <repo>] [--home DIR] [--sha] [--branch]
+ *                   [--committed-at ISO] [--subject TEXT]
+ *       Append one commit boundary event — the call a managed git
+ *       post-commit hook makes.
+ *
  * The server binds to localhost by default: journals contain full
  * conversation bodies, so they stay on this machine unless --host says
  * otherwise.
@@ -24,8 +28,23 @@ async function main(argv = process.argv.slice(2)) {
     return i >= 0 ? argv[i + 1] : undefined;
   };
 
+  if (command === 'commit-boundary') {
+    // The boundary entry reads its own flags from process.argv; the extra
+    // positional is ignored by its --flag lookup. The contract is one JSON
+    // line (ok:true/false) on stdout, preserved even when required from here.
+    await require('./bridge/bin/commit-boundary').main().catch((err) => {
+      process.stderr.write(`${JSON.stringify({ ok: false, error: err && err.message ? err.message : String(err) })}\n`);
+      process.exitCode = 1;
+    });
+    return;
+  }
+
   if (command !== 'serve') {
-    console.log('Usage: ai-coding-event-bridge-console serve [--port 8790] [--host 127.0.0.1] [--home DIR]');
+    console.log('Usage: ai-coding-event-bridge-console <command> [options]');
+    console.log('  serve            Start the local console (explorer page + JSON API)');
+    console.log('                     --port 8790  --host 127.0.0.1  --home DIR');
+    console.log('  commit-boundary  Append one commit boundary event (git post-commit hooks)');
+    console.log('                     --cwd <repo>  --home DIR  --sha  --branch');
     process.exitCode = command ? 1 : 0;
     return;
   }

package/src/bridge/bin/commit-boundary.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Bridge commit-boundary injection point. Any git hook (or a human, or a
+ * test) can signal "this repo just committed" by running:
+ *
+ *   node commit-boundary.js --cwd <repo> [--home <bridge home>]
+ *                           [--sha <sha>] [--branch <name>] [--committed-at <iso>]
+ *
+ * The repo identity is resolved from the working tree (that is how the bridge
+ * knows which registered project — and therefore which store — the commit
+ * belongs to). Facts not provided are read from the repo's git. Output is a
+ * single JSON line on stdout; errors exit non-zero so callers can distinguish
+ * a failed injection from a skip.
+ */
+
+const { execFileSync } = require('child_process');
+const { resolveRepoContext } = require('../core/repo-context');
+const { createBridge } = require('../core/bridge');
+
+function arg(name, fallback = '') {
+  const prefix = `--${name}`;
+  const argv = process.argv.slice(2);
+  const index = argv.indexOf(prefix);
+  if (index === -1) return fallback;
+  const value = argv[index + 1];
+  return value === undefined || value.startsWith('--') ? fallback : value;
+}
+
+function git(cwd, args) {
+  return String(execFileSync('git', args, { cwd, windowsHide: true, encoding: 'utf8' })).trim();
+}
+
+async function main() {
+  const cwd = arg('cwd', process.cwd());
+  const repo = await resolveRepoContext(cwd);
+  if (!repo || !repo.repoIdentity) {
+    throw new Error(`not a Git work tree (no repo identity): ${cwd}`);
+  }
+  const commitSha = arg('sha') || git(cwd, ['rev-parse', 'HEAD']);
+  const branch = arg('branch') || git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const committedAt = arg('committed-at') || git(cwd, ['log', '-1', '--format=%cI']);
+  const subject = arg('subject') || git(cwd, ['log', '-1', '--format=%s']);
+  const homeDir = arg('home') || undefined;
+  const bridge = createBridge(homeDir ? { homeDir } : {});
+  const result = await bridge.appendCommitBoundary({
+    repoIdentity: repo.repoIdentity,
+    commitSha,
+    branch,
+    subject,
+    committedAt: committedAt || undefined
+  });
+  process.stdout.write(`${JSON.stringify({ ok: true, projectPath: repo.projectPath, ...result })}\n`);
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main().catch((err) => {
+    process.stderr.write(`${JSON.stringify({ ok: false, error: err && err.message ? err.message : String(err) })}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/bridge/connectors/capture-guard.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * Capture-disable guard. Project-Knowledge (or any host) marks its internal
+ * AI SDK sessions with AI_CODING_EVENT_BRIDGE_CAPTURE=0 and
+ * AI_CODING_EVENT_ORIGIN. Every connector checks this FIRST — before
+ * normalization, repo Git resolution, or any journal write — so internal
+ * Workbench/Analyzer conversations never reach the durable journal.
+ */
+function isCaptureDisabled(env = process.env, payload = null) {
+  if (env && env.AI_CODING_EVENT_BRIDGE_CAPTURE === '0') {
+    return true;
+  }
+  if (payload && typeof payload === 'object' && payload.meta && typeof payload.meta === 'object') {
+    return String(payload.meta.bridgeCapture) === '0';
+  }
+  return false;
+}
+
+function captureDisabledResult() {
+  return { status: 'ignored', reason: 'capture-disabled' };
+}
+
+module.exports = { isCaptureDisabled, captureDisabledResult };

package/src/bridge/connectors/claude-code/hook-entry.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const { normalizeClaudeCode } = require('../../core/normalizer');
+const { resolveRepoContext } = require('../../core/repo-context');
+const { journalFor } = require('../../core/journal-router');
+const { isCaptureDisabled, captureDisabledResult } = require('../capture-guard');
+const { notifyConsumers } = require('./notify');
+
+/**
+ * Durable-first Claude Code hook processing. The event is appended and fsynced
+ * to the Bridge journal before any consumer notification is attempted, and the
+ * whole entry fails open: a broken Bridge must never block the AI client.
+ * Internal host SDK sessions (AI_CODING_EVENT_BRIDGE_CAPTURE=0) are ignored
+ * before any Git/journal work happens.
+ */
+async function main({ home, payload }) {
+  if (isCaptureDisabled(process.env, payload)) {
+    return captureDisabledResult();
+  }
+  if (!payload || typeof payload !== 'object') {
+    return { status: 'ignored' };
+  }
+  const event = normalizeClaudeCode(payload);
+  if (!event) {
+    return { status: 'ignored' };
+  }
+  const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+  const repo = await resolveRepoContext(cwd);
+  const journal = journalFor(home, event.repoIdentity || repo.repoIdentity);
+  const appended = await journal.appendConversationEvent({
+    ...event,
+    repoIdentity: event.repoIdentity || repo.repoIdentity,
+    projectPath: event.projectPath || repo.projectPath,
+    branch: event.branch || repo.branch,
+    headAtCapture: event.headAtCapture || repo.headAtCapture
+  });
+  await notifyConsumers(home, { sequence: appended.sequence, eventId: appended.eventId });
+  return { status: 'captured', sequence: appended.sequence, turnId: appended.turnId };
+}
+
+function mainFailOpen({ home, payload }) {
+  return main({ home, payload }).catch(() => ({ status: 'fail-open' }));
+}
+
+module.exports = { main, mainFailOpen };

package/src/bridge/connectors/claude-code/notify.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const http = require('http');
+const https = require('https');
+const { ConsumerRegistry } = require('../../core/consumer-registry');
+
+function postJson(url, body, timeoutMs = 1500) {
+  return new Promise((resolve) => {
+    try {
+      const target = new URL(url);
+      const mod = target.protocol === 'https:' ? https : http;
+      const data = JSON.stringify(body);
+      const req = mod.request(
+        {
+          hostname: target.hostname,
+          port: target.port || (target.protocol === 'https:' ? 443 : 80),
+          path: `${target.pathname}${target.search}`,
+          method: 'POST',
+          headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(data) },
+          timeout: timeoutMs
+        },
+        (res) => {
+          res.resume();
+          res.on('end', () => resolve({ ok: res.statusCode && res.statusCode < 500 }));
+        }
+      );
+      req.on('timeout', () => {
+        req.destroy();
+        resolve({ ok: false });
+      });
+      req.on('error', () => resolve({ ok: false }));
+      req.end(data);
+    } catch (_) {
+      resolve({ ok: false });
+    }
+  });
+}
+
+/**
+ * Best-effort wake-up for consumers that registered a notifyUrl. Always runs
+ * after the durable append; failures never propagate to the AI client.
+ */
+async function notifyConsumers(home, info) {
+  try {
+    const registry = new ConsumerRegistry(home);
+    const consumers = await registry.getConsumers();
+    const urls = consumers
+      .map((consumer) => consumer.meta && consumer.meta.notifyUrl)
+      .filter((url) => typeof url === 'string' && url);
+    await Promise.all(urls.map((url) => postJson(url, info)));
+    return { notified: urls.length };
+  } catch (_) {
+    return { notified: 0 };
+  }
+}
+
+module.exports = { notifyConsumers, postJson };

package/src/bridge/connectors/codex/cursor-store.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { writeJsonAtomicSync, readJsonIfExists, ensureDirSync } = require('../../core/fs-utils');
+
+/**
+ * Atomic per-session cursor state. One JSON file per Codex session under
+ * <home>/cursors/codex/, written via rename so a crash never corrupts it.
+ * Cursor v2 stores an independent offset and workspace context for every
+ * rollout file. A v1 cursor is upgraded in memory without resetting its
+ * consumed offset, so discovering a continuation file never replays history.
+ */
+const CURSOR_SCHEMA = 'codex-cursor/v2';
+
+function fileState(state = {}) {
+  return {
+    filePath: state.filePath,
+    byteOffset: Number.isInteger(state.byteOffset) && state.byteOffset >= 0 ? state.byteOffset : 0,
+    lastRecordKey: state.lastRecordKey || null,
+    activeCwd: state.activeCwd || null,
+    repoIdentity: state.repoIdentity || null,
+    projectPath: state.projectPath || null,
+    branch: state.branch || null,
+    headAtCapture: state.headAtCapture || null
+  };
+}
+
+function normalizeCursor(sessionId, state) {
+  const normalized = { schema: CURSOR_SCHEMA, sessionId: String(sessionId), files: {} };
+  if (!state || typeof state !== 'object') return normalized;
+
+  if (state.schema === CURSOR_SCHEMA && state.files && typeof state.files === 'object') {
+    for (const [key, value] of Object.entries(state.files)) {
+      if (!value || typeof value !== 'object' || typeof value.filePath !== 'string') continue;
+      normalized.files[key] = fileState(value);
+    }
+    return normalized;
+  }
+
+  // v1 compatibility: preserve the exact consumed offset and context. The
+  // caller supplies the canonical key after resolving the legacy file path.
+  if (typeof state.filePath === 'string' && state.filePath) {
+    normalized.legacyFile = fileState(state);
+  }
+  return normalized;
+}
+
+class CodexCursorStore {
+  constructor(homeDir) {
+    this.dir = path.join(homeDir, 'cursors', 'codex');
+    ensureDirSync(this.dir);
+  }
+
+  _fileFor(sessionId) {
+    const safe = String(sessionId).replace(/[^A-Za-z0-9._-]/g, '_');
+    return path.join(this.dir, `${safe}.json`);
+  }
+
+  read(sessionId) {
+    return normalizeCursor(sessionId, readJsonIfExists(this._fileFor(sessionId)));
+  }
+
+  write(sessionId, state) {
+    const normalized = normalizeCursor(sessionId, state);
+    writeJsonAtomicSync(this._fileFor(sessionId), {
+      schema: CURSOR_SCHEMA,
+      sessionId: normalized.sessionId,
+      files: normalized.files,
+      updatedAt: new Date().toISOString()
+    });
+  }
+
+  clear(sessionId) {
+    try {
+      fs.rmSync(this._fileFor(sessionId), { force: true });
+    } catch (_) {
+      // Already gone.
+    }
+  }
+}
+
+module.exports = { CodexCursorStore, CURSOR_SCHEMA, normalizeCursor };

package/src/bridge/connectors/codex/hook-entry.js

@@ -0,0 +1,215 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { validateAndNormalizeEvent } = require('../../core/event-schema');
+const { resolveRepoContext } = require('../../core/repo-context');
+const { journalFor } = require('../../core/journal-router');
+const { CodexCursorStore } = require('./cursor-store');
+const { parseSessionChunk, extractMessage, extractWorkspaceMeta } = require('./session-parser');
+const { isCaptureDisabled, captureDisabledResult } = require('../capture-guard');
+const { notifyConsumers } = require('../claude-code/notify');
+const { CrossProcessLock } = require('../../core/lock');
+
+/**
+ * Deterministic Codex capture.
+ *
+ * The notify payload is only a wake-up signal; it never carries the workspace.
+ * The real workspace comes from the session's authoritative rollout metadata
+ * (session_meta.payload.cwd / turn_context.payload.cwd) — NEVER from the
+ * session file's location, which is Codex runtime storage. Bytes are consumed
+ * incrementally per session; a partial trailing line stays unread until the
+ * next wake-up. When no authoritative cwd can be parsed, a
+ * codex-workspace-unresolved gap is recorded and the event is never bound to
+ * any project.
+ */
+
+function recordGap(home, reason, meta = {}) {
+  try {
+    const gapsFile = path.join(home, 'journal', 'capture-gaps.jsonl');
+    fs.mkdirSync(path.dirname(gapsFile), { recursive: true });
+    fs.appendFileSync(
+      gapsFile,
+      `${JSON.stringify({ schema: 'bridge-capture-gap/v1', source: 'codex', reason, ...meta, at: new Date().toISOString() })}\n`
+    );
+  } catch (_) {
+    // Gap persistence is best effort; the decision to not guess stands regardless.
+  }
+}
+
+function normalizedPath(filePath) {
+  const resolved = path.resolve(filePath);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function fileKey(sessionsRoot, filePath) {
+  return path.relative(path.resolve(sessionsRoot), path.resolve(filePath)).split(path.sep).join('/');
+}
+
+async function findSessionFiles(sessionsRoot, sessionId) {
+  // Deterministic discovery: Codex rollout files embed the session id in the
+  // file name; we search by exact id, never by mtime.
+  const stack = [sessionsRoot];
+  const matches = [];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_) {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile() && entry.name.endsWith('.jsonl') && entry.name.includes(sessionId)) {
+        matches.push(full);
+      }
+    }
+  }
+  return matches.sort((left, right) => fileKey(sessionsRoot, left).localeCompare(fileKey(sessionsRoot, right)));
+}
+
+async function findSessionFile(sessionsRoot, sessionId) {
+  const files = await findSessionFiles(sessionsRoot, sessionId);
+  return files[0] || null;
+}
+
+function emptyFileState(filePath) {
+  return {
+    filePath,
+    byteOffset: 0,
+    lastRecordKey: null,
+    activeCwd: null,
+    repoIdentity: null,
+    projectPath: null,
+    branch: null,
+    headAtCapture: null
+  };
+}
+
+async function captureSessionUnlocked({ home, sessionsRoot, sessionId, cursorStore }) {
+  const cursor = cursorStore.read(sessionId);
+  const filePaths = await findSessionFiles(sessionsRoot, sessionId);
+  if (!filePaths.length) {
+    recordGap(home, 'session-file-not-found', { sessionId });
+    return { status: 'gap', reason: 'session-file-not-found' };
+  }
+
+  if (cursor.legacyFile) {
+    const legacyMatch = filePaths.find(candidate => normalizedPath(candidate) === normalizedPath(cursor.legacyFile.filePath));
+    if (legacyMatch) {
+      cursor.files[fileKey(sessionsRoot, legacyMatch)] = { ...cursor.legacyFile, filePath: legacyMatch };
+    }
+    delete cursor.legacyFile;
+  }
+
+  let captured = 0;
+  let completeBytes = 0;
+
+  for (const filePath of filePaths) {
+    const key = fileKey(sessionsRoot, filePath);
+    const state = cursor.files[key] || emptyFileState(filePath);
+    state.filePath = filePath;
+    const fromOffset = state.byteOffset || 0;
+    const parsed = parseSessionChunk(filePath, fromOffset);
+    let unresolvedGapRecorded = false;
+
+    for (let index = 0; index < parsed.records.length; index += 1) {
+      const record = parsed.records[index];
+      const meta = extractWorkspaceMeta(record);
+      if (meta) {
+        if (meta.cwd && meta.cwd !== state.activeCwd) {
+          // Authoritative workspace switch (session start or turn_context change).
+          const repo = await resolveRepoContext(meta.cwd);
+          state.activeCwd = meta.cwd;
+          state.repoIdentity = repo.repoIdentity;
+          state.projectPath = repo.projectPath;
+          state.branch = repo.branch;
+          state.headAtCapture = repo.headAtCapture;
+        }
+        continue;
+      }
+      const message = extractMessage(record);
+      if (!message) continue;
+      if (!state.repoIdentity && !unresolvedGapRecorded) {
+        recordGap(home, 'codex-workspace-unresolved', { sessionId, rolloutFile: key });
+        unresolvedGapRecorded = true;
+      }
+      const byteOffset = parsed.recordOffsets[index];
+      const recordKey = `${key}:${byteOffset}`;
+      const event = validateAndNormalizeEvent({
+        source: 'codex',
+        eventType: message.role === 'user' ? 'user_prompt' : 'assistant_response',
+        role: message.role,
+        content: message.text,
+        sessionId,
+        turnId: message.turnId,
+        repoIdentity: state.repoIdentity,
+        projectPath: state.projectPath,
+        branch: state.branch,
+        headAtCapture: state.headAtCapture,
+        identityConfidence: message.turnId ? 'exact' : 'partial',
+        captureStatus: 'complete',
+        rawEventType: record.type || 'message',
+        eventKey: `codex:${sessionId}:${recordKey}`,
+        meta: { recordKey, rolloutFile: key, byteOffset, phase: message.phase }
+      });
+      // The workspace can switch mid-session (turn_context), so the journal is
+      // routed per record from the authoritative identity, never per session.
+      const journal = journalFor(home, state.repoIdentity);
+      const appended = await journal.appendConversationEvent(event);
+      state.lastRecordKey = recordKey;
+      if (!appended.duplicate) captured += 1;
+    }
+
+    state.byteOffset = fromOffset + parsed.completeBytes;
+    cursor.files[key] = state;
+    completeBytes += parsed.completeBytes;
+  }
+
+  cursorStore.write(sessionId, cursor);
+  return { status: 'captured', captured, files: filePaths.length, completeBytes };
+}
+
+async function captureSession({ home, sessionsRoot, sessionId }) {
+  const cursorStore = new CodexCursorStore(home);
+  const safe = String(sessionId).replace(/[^A-Za-z0-9._-]/g, '_');
+  const lock = new CrossProcessLock(path.join(home, 'cursors', 'codex', `${safe}.capture.lock`));
+  return lock.withLock(() => captureSessionUnlocked({ home, sessionsRoot, sessionId, cursorStore }));
+}
+
+async function main({ home, payload }) {
+  if (isCaptureDisabled(process.env, payload)) {
+    return captureDisabledResult();
+  }
+  if (!payload || typeof payload !== 'object') {
+    return { status: 'ignored' };
+  }
+  const sessionId = payload.session_id || payload.sessionId || null;
+  if (!sessionId || typeof sessionId !== 'string') {
+    // Ambiguous notify: never fall back to the newest session by mtime.
+    recordGap(home, 'notify-session-unresolved', { keys: Object.keys(payload).slice(0, 8) });
+    return { status: 'gap', reason: 'notify-session-unresolved' };
+  }
+  const sessionsRoot =
+    payload.sessions_root ||
+    (process.env.CODEX_SESSIONS_ROOT) ||
+    path.join(home, 'fixtures', 'codex-sessions');
+  const result = await captureSession({
+    home,
+    sessionsRoot,
+    sessionId
+  });
+  if (result.status === 'captured' && result.captured > 0) {
+    await notifyConsumers(home, { source: 'codex', sessionId });
+  }
+  return result;
+}
+
+function mainFailOpen({ home, payload }) {
+  return main({ home, payload }).catch(() => ({ status: 'fail-open' }));
+}
+
+module.exports = { main, mainFailOpen, captureSession, findSessionFile, findSessionFiles, recordGap };

package/src/bridge/connectors/codex/session-parser.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * Incremental Codex session JSONL parser. Reads only appended bytes after the
+ * cursor offset, tolerates a partial trailing line, and classifies records
+ * into messages and workspace metadata. Never re-reads the whole file and
+ * never selects sessions by mtime — the caller identifies the session file
+ * deterministically.
+ */
+function parseSessionChunk(filePath, fromOffset) {
+  const size = fs.statSync(filePath).size;
+  if (size <= fromOffset) return { records: [], recordOffsets: [], completeBytes: 0, size };
+  const fd = fs.openSync(filePath, 'r');
+  let raw;
+  try {
+    const buf = Buffer.alloc(size - fromOffset);
+    const read = fs.readSync(fd, buf, 0, buf.length, fromOffset);
+    raw = buf.toString('utf8', 0, read);
+  } finally {
+    fs.closeSync(fd);
+  }
+  const records = [];
+  const recordOffsets = [];
+  let completeBytes = 0;
+  const chunks = raw.split('\n');
+  for (let i = 0; i < chunks.length; i++) {
+    const line = chunks[i];
+    if (i === chunks.length - 1) break; // trailing bytes without newline = partial
+    if (line.length === 0) {
+      completeBytes += 1;
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (_) {
+      parsed = null;
+    }
+    if (parsed && typeof parsed === 'object') {
+      records.push(parsed);
+      recordOffsets.push(fromOffset + completeBytes);
+    }
+    completeBytes += Buffer.byteLength(line, 'utf8') + 1;
+  }
+  return { records, recordOffsets, completeBytes, size };
+}
+
+/**
+ * Authoritative workspace metadata from Codex rollout records:
+ * session_meta.payload.cwd and turn_context.payload.cwd. A verified
+ * turn_context cwd may update the active workspace for subsequent events.
+ */
+function extractWorkspaceMeta(record) {
+  if (!record || typeof record !== 'object') return null;
+  const payload = record.payload && typeof record.payload === 'object' ? record.payload : null;
+  if (record.type === 'session_meta' || (payload && payload.type === 'session_meta')) {
+    const cwd = payload && typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : null;
+    return { kind: 'session_meta', cwd };
+  }
+  if (record.type === 'turn_context' || (payload && payload.type === 'turn_context')) {
+    const cwd = payload && typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : null;
+    return { kind: 'turn_context', cwd };
+  }
+  return null;
+}
+
+function extractMessage(record) {
+  if (!record || typeof record !== 'object') return null;
+  const payload = record.payload && typeof record.payload === 'object' ? record.payload : record;
+  const role = payload.role || record.role;
+  if (role !== 'user' && role !== 'assistant') return null;
+  const text = collectText(payload.content !== undefined ? payload.content : record.content);
+  if (text === null) return null;
+  const passthrough = payload.internal_chat_message_metadata_passthrough;
+  const nestedTurnId = passthrough && typeof passthrough === 'object' ? passthrough.turn_id : null;
+  return {
+    role,
+    text,
+    turnId: payload.turn_id || nestedTurnId || record.turn_id || null,
+    phase: typeof payload.phase === 'string' && payload.phase ? payload.phase : null
+  };
+}
+
+function collectText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    const parts = [];
+    for (const item of content) {
+      if (typeof item === 'string') parts.push(item);
+      else if (item && typeof item === 'object' && typeof item.text === 'string') parts.push(item.text);
+    }
+    if (parts.length) return parts.join('\n');
+    return null;
+  }
+  return null;
+}
+
+module.exports = { parseSessionChunk, extractMessage, extractWorkspaceMeta };