genetics-mcp 2.24.0 → 2.26.0

package/NATIVE-CODEX-SESSION.md

@@ -0,0 +1,182 @@
+# Native Codex sessions
+
+The native adapter reads `~/.codex/sessions/YYYY/MM/DD/rollout-*-UUID.jsonl`.
+The filename UUID must match the first complete `session_meta.payload.id`; cwd must
+be absolute. Symlinks are excluded. `CODEX_THREAD_ID` identifies the current child
+before the older `CODEX_SESSION_ID` fallback. Tenant ownership still comes from
+the API or an explicit human choice, never from the source directory or cwd.
+
+`push_session` keeps the existing arguments (`tenant`, `uuid`, `title`, `dry_run`).
+Native user messages, assistant commentary/final messages, named tool calls, and
+masked tool-result placeholders are projected to the existing portal wire schema.
+Developer/system instructions, assistant analysis, event duplicates, and compacted
+internal context are excluded. Images have explicit omission placeholders; all
+surrounding human text is retained. Arbitrary shell-write inference is outside this
+adapter. Source metadata is preserved as `tools.client=codex/<cli_version>`,
+`tools.source_format=codex-rollout`, and `tools.codec=codex-rollout-v1`.
+
+The canonical Genetics scrubber runs before caching and again before upload.
+The private cache (`codex-projections` beside the credential file) has mode 0700;
+files have mode 0600. It is not a Claude transcript or a native restore archive.
+Only cwd markers retain local raw paths so the existing private-folder checks see
+every source cwd before upload. Appended complete records extend the same projection
+inode; partial final records are deferred. Source replacement, shrinkage, prefix or
+seam changes rebuild the projection. The typed projection has its own codec revision
+and scrub revision. Genetics append/MAC coordinates refer to this projection, while
+the local receipt separately tracks native source offsets and byte counts.
+
+Bounds: source 8 GiB, retained record 4 MiB, projection 64 MiB, private cache 512 MiB
+and 256 sessions, source inventory 10,000 files/4,096 directories, one cache writer.
+Oversized image values are omitted lexically without decoding their bodies.
+Oversized tool results/internal records are omitted with counters. Oversized retained
+human text or tool input, malformed retained JSON/UTF-8, ambiguous UUIDs, or exhausted
+bounds fail before upload. No arbitrary middle-file rewrite guarantee is made: native
+rollouts are append streams, with explicit prefix/seam checks on reuse. A crashed
+cache writer is reclaimed only when its recorded PID is dead on this host; a lock
+without a valid owner requires local inspection. Cache-limit errors require removal
+of unused projections (subsequent uploads safely rebuild them).
+
+Automatic discovery excludes child/fork/internal sources. It observes the existing
+effective confirmed-folder flag, consent notice, activation cutoff, private-folder
+and server-policy gates. Native sources have no legacy automatic-upload fallback.
+A manual upload does not enable global or folder automatic upload, and does not
+authorize backfilling other sessions. If the server's global switch is off, future
+native session-body uploads remain off. Session heartbeat/world observations are
+separate from publishing a body or finishing a work task.
+
+Use a fresh MCP process when the installed server is still warm on an older module:
+
+```sh
+node mcp/codex-session-cli.mjs whoami
+node mcp/codex-session-cli.mjs dry-run --tenant <verified-slug> --uuid <selected-uuid> --title <title>
+node mcp/codex-session-cli.mjs publish --tenant <verified-slug> --uuid <selected-uuid> --title <title>
+node mcp/codex-session-cli.mjs list --tenant <verified-slug> --page 1
+node mcp/codex-session-cli.mjs watch --tenant <verified-slug> --uuid <selected-uuid> --seconds 60
+```
+
+The runner initializes `clientInfo.name=codex`, then invokes only the selected tool
+through stdio. Existing SSO credentials remain in the child process. Session-only
+mode disables installs, timers, mail/world response side effects, and closing beats;
+its only tools are `whoami`, `list_sessions`, and explicit `push_session`. The runner
+does not toggle policy or infer the tenant. `resume_session` reads published context;
+native `codex resume` reconstruction is not supported by this projection.
+
+Watch runs a fresh normal heartbeat/auto-upload loop for only the selected UUID.
+It drains protocol notifications, disables installation/mail/world/observe side
+effects, compares initial/final selected-tenant lists, and terminates its own child.
+It never overrides global/folder policy, local opt-out, activation cutoff, or the
+existing 90-second upload interval. Start after that interval when validating an
+automatic update immediately following a manual publication. The warm installed
+MCP process is unaffected. Image counters count source image_url values, including
+duplicates inside omitted tool/internal context, rather than unique attachments.
+
+`node mcp/codex-session.test.mjs` exercises the real upload function and fresh stdio
+runner against an isolated localhost API with synthetic person credentials. It is
+transport/codec evidence, not production publication or human acceptance evidence.
+
+
+## Native Codex mail
+
+The local stdio `mail` tool uses the strict native child UUID. It does not require
+Claude's ListAgents identity, invent a sender name, or trust `clientInfo.name` or a
+caller-provided sender. The existing server registration authenticates the person
+and labels the UUID. Claude and Cursor keep their existing identity rules. This is
+Genetics addressed agent mail (session/brain/team addresses), not an SMTP sender.
+Implementing this support does not authorize sending a message to any real person.
+
+Codex keeps the default hookless MCP poll every 60 seconds. Received text is appended
+to the next MCP tool response; a UUID alone never disables that fallback. Optional
+local hooks require an explicit `gcell install-hooks --codex` preview and `--apply`
+installation, followed by Codex's own `/hooks` trust approval. Installed host hooks
+and actual model delivery have not been verified by the synthetic tests here.
+Hosted HTTP MCP connections do not install these local command hooks.
+
+The opt-in PostToolUse hook is synchronous and emits only the official
+`hookSpecificOutput: {hookEventName:"PostToolUse",additionalContext:...}` object.
+It shares an eight-second check throttle. Stop checks mail first even without file
+changes and may request a continuation using `decision:"block",reason:...`.
+`stop_hook_active` reentry cannot pull or acknowledge another batch. Async completion
+while idle cannot create a new Codex turn, so neither Claude PostToolBatch nor
+asyncRewake is installed for Codex. The command timeout is five seconds; registry
+registration, pull and ACK share a three-second monotonic deadline, including curl
+startup, pipe reading and child supervision, with at most 250 ms cleanup grace.
+Successful complete bodies over 256 KiB or configuration stdin over 4 KiB fail closed.
+The native Rust mail hooks currently fail closed outside Unix. Windows keeps the
+original MCP receive path; shared Unix spool guarantees below do not apply to that
+legacy Windows path. No Windows hook acceptance is claimed.
+
+A hook requires a strict UUID, agreement with an available CODEX_THREAD_ID, and a
+native rollout whose first session_meta, filename UUID and repository cwd match.
+An explicit transcript must be that same discovered owned regular file. Symlink
+rollouts, foreign sessions, Claude/Cursor payloads and unconfirmed folder bindings
+cannot select a Codex mailbox. The tenant is the server-confirmed folder binding.
+MCP uses the actual server tenant_id from its index or successful mail receipt.
+Missing IDs are not guessed. Before any pending ACK, the same server must approve
+registration of that native UUID with an empty sender name and client `codex`; its
+returned tenant_id and session must match the pinned key before any pull or ACK.
+
+### Shared journal protocol (version 1)
+
+Both Node and Rust use the actual credential file's parent directory, then
+`mail-receive/v1-<key>.json`. The mail-only Rust resolver mirrors Node: environment
+overrides api.env, api.env base overrides credential.base, and GENETICS_ENV changes
+the default credential directory. The endpoint must be an exact permitted Genetics
+API hostname over HTTPS or exact localhost/127.0.0.1 loopback. The new Rust mail
+resolver rejects userinfo, malformed authority and localhost suffix tricks; it does
+not change the existing Claude/Cursor resolver. Credentials and base are never logged.
+
+The key is hexadecimal SHA256 of this UTF-8 byte sequence, with literal NUL separators:
+
+```
+base-with-all-trailing-slashes-removed\0tenant_id-decimal\0lowercase-UUID\0SHA256(token)-hex
+```
+
+Including the credential digest prevents a later login in the same file from reading
+an earlier person's pending batch. Tenant aliases map to the same server ID. Different
+server bases, tenant IDs, native UUIDs or token values have separate journals.
+
+The journal has exactly `{version:1,last_checked_ms:<epoch integer>,pending:null}`,
+or `pending:{ids:[...],says:"..."}`. IDs are unique positive safe integers, at most 20;
+says is nonempty UTF-8 server-rendered text at most 64 KiB. Unknown fields, incomplete
+JSON, invalid UTF-8, future timestamps, duplicate IDs or invalid bounds fail closed.
+Files are owned regular files with no symlink and mode 0600, inside an owned 0700
+directory. Node reads at most max+1 bytes; Rust uses the same finite read bound.
+
+The nonwaiting `<journal>.lock` is created exclusively with exactly
+`{version:1,pid:<positive PID>,host:"...",nonce:"<nonempty string, max128 bytes>"}`.
+Node uses a random hex nonce; Rust uses its nanosecond nonce. A matching token alone
+can remove its lock. Age never steals a live writer. Only a valid recorded dead PID
+on the same host can be reclaimed, under a separately exclusive `.lock.reap` file.
+An invalid owner, foreign host, live process, or interrupted reaper is fail closed
+and requires local inspection; it is not removed automatically.
+
+A directory-wide `.inventory.lock` serializes admission and atomic state writes.
+At most 128 journal files, 16 MiB total bytes including atomic-write overlap, and a
+510-entry admission scan are allowed. The scan reads at most 510 entries; busy
+inventory is not waited on. Pending batches are never evicted. At capacity, inspect
+and remove only obsolete journals with pending null while the clients are stopped;
+retain undelivered pending data. Every update uses an exclusive private temporary
+file, a complete bounded write (including partial-write checks), file fsync, rename
+and directory fsync. Mail never rewrites the unlocked
+file-author/wake State used by the existing hooks.
+
+Pull saves the complete server-rendered batch before ACK. Failure, a lost ACK response
+or a dead writer retains that pending batch for an idempotent retry by either Node
+or Rust; no local cursor skips it. A successful authorized ACK must return matching
+asked count and an integer stamped count in 0..asked. The API cannot distinguish
+already delivered, expired or absent IDs when stamped is zero. This is an authorized
+ACK attempt followed by one local emission, not proof of every ID's current server
+delivery state. Clearing pending after successful ACK and before emission prevents
+repeated continuation; a crash in that final gap can lose local delivery. The protocol
+does not claim exactly-once model context or an idle wake guarantee.
+
+```sh
+NODE_BIN=<absolute-real-node> GCELL_BIN=<owned-gcell> python3 cell/tests/native-codex-mail.py
+```
+
+This exercises actual local hooks and three bounded
+stdio processes against synthetic loopback mail. It covers single writer exclusion,
+ACK-response loss and cross-language pending recovery, identities, private files,
+aggregate limits, network deadlines and explicit hook configuration. The existing
+`cell/tests/gate.sh` registers this check separately from the six legacy native checks. These tests do not send real mail,
+install user hooks, test production authorization, or invoke a model.

package/bin/manifest.json

@@ -1,7 +1,7 @@
 {
-  "aarch64-apple-darwin": "b3e457bc632fa02bd4df2cfe828e8fa04c1288b7553cb9b77b6dbd98a2df748d",
-  "aarch64-unknown-linux-musl": "8e174b10e0ff47263e57663204cd39557e8f6e8898d28b4583e2571466487d95",
-  "x86_64-apple-darwin": "fc4bf9c575465f0222c89ba0b7c4d8f1945b18172fa803c8ae31e74b39a1523d",
-  "x86_64-pc-windows-gnu": "247ed5e4ccacbbdd1a81783a99296f4f5541d9060079547af85d187746b8c187",
-  "x86_64-unknown-linux-musl": "0b93a8e653fd2993bd9e37c79119fbc4f4b4446c55023fa060b529d9a06a80ad"
+  "aarch64-apple-darwin": "67c002cef4354855509ef329d0b7b2a4c4cf7c9f8d469205700824668aaad23f",
+  "aarch64-unknown-linux-musl": "5c96ab2cd1a8971462f9d7505fa5d64b59723c30a1b6fc92b57f06bfd36b102f",
+  "x86_64-apple-darwin": "fe636058430bdf32ddf10bfa901cac27db94c38664b572ef78963b5c79d4e843",
+  "x86_64-pc-windows-gnu": "0a9bb25cf6e617789ffd96dd2f87cdaff3d49a9b7c7f5dd99811a3ab075d546d",
+  "x86_64-unknown-linux-musl": "a0eb644986d0291db0fa91f76504d0d79607e2767e704d4ca419d9220a6be4a2"
 }

package/codex-session-cli.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/** One explicit native-session operation through a fresh MCP stdio child. Credentials stay in the child. */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const argv = process.argv.slice(2), operation = argv.shift();
+if (!['dry-run', 'publish', 'whoami', 'list', 'watch'].includes(operation)) {
+  process.stderr.write('Usage: node codex-session-cli.mjs dry-run|publish --tenant <slug> --uuid <UUID> [--title <title>]\n'
+    + '       node codex-session-cli.mjs whoami | list --tenant <slug> [--page <n>]\n'
+    + '       node codex-session-cli.mjs watch --tenant <slug> --uuid <UUID> [--seconds 60]\n');
+  process.exit(2);
+}
+const options = {};
+for (let i = 0; i < argv.length; i += 2) {
+  if (!['--tenant', '--uuid', '--title', '--page', '--seconds'].includes(argv[i]) || argv[i + 1] === undefined) throw new Error('Unknown or missing CLI option');
+  options[argv[i].slice(2)] = argv[i + 1];
+}
+if (operation !== 'whoami' && !options.tenant) throw new Error('Explicit tenant is required; it is never inferred from cwd');
+if (['dry-run', 'publish', 'watch'].includes(operation) && !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(options.uuid || '')) throw new Error('Explicit valid session UUID required');
+const watching = operation === 'watch', seconds = Number(options.seconds || 60);
+if (watching && (!Number.isInteger(seconds) || seconds < 1 || seconds > 60)) throw new Error('Watch seconds must be 1..60');
+const watchDeadline = watching ? Date.now() + seconds * 1000 : 0;
+const tool = operation === 'whoami' ? 'whoami' : operation === 'list' || watching ? 'list_sessions' : 'push_session';
+const args = operation === 'whoami' ? {} : operation === 'list' || watching ? { tenant: options.tenant, limit: 100, page: Number(options.page || 1) }
+  : { tenant: options.tenant, uuid: options.uuid, ...(options.title ? { title: options.title } : {}), dry_run: operation === 'dry-run' };
+const child = spawn(process.execPath, [fileURLToPath(new URL('./genetics.mjs', import.meta.url))], {
+  stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, GENETICS_SESSION_ONLY: watching ? '' : '1',
+    GENETICS_SESSION_WATCH_UUID: watching ? options.uuid : '', ...(watching ? { CODEX_THREAD_ID: options.uuid } : {}),
+    GENETICS_NO_BEAT: watching ? '' : '1', GENETICS_NO_CELL: '1', GENETICS_NO_SKILL: '1',
+    ...(watching ? {} : { GENETICS_NO_AUTO_PUSH: '1' }) } });
+let buffer = '', stderrBytes = 0, sequence = 0, notifications = 0;
+const pending = new Map();
+child.stdout.setEncoding('utf8');
+child.stdout.on('data', chunk => {
+  buffer += chunk;
+  if (Buffer.byteLength(buffer) > 1024 ** 2) { child.kill(); return; }
+  for (let at; (at = buffer.indexOf('\n')) >= 0;) {
+    const line = buffer.slice(0, at); buffer = buffer.slice(at + 1);
+    try { const reply = JSON.parse(line); const task = pending.get(reply.id); if (task) { pending.delete(reply.id); task.resolve(reply); } else if (reply.method) notifications++; }
+    catch { child.kill(); }
+  }
+});
+child.stderr.on('data', chunk => { stderrBytes += chunk.length; if (stderrBytes > 1024 ** 2) child.kill();
+  // The server only emits operational messages here; never print inherited credentials/environment.
+  else process.stderr.write(chunk); });
+child.on('exit', () => { for (const task of pending.values()) task.reject(new Error('MCP child exited before its reply')); pending.clear(); });
+function rpc(method, params) {
+  return new Promise((resolve, reject) => {
+    const id = ++sequence, timeout = watching ? Math.max(1, watchDeadline - Date.now()) : 300_000;
+    const timer = setTimeout(() => { pending.delete(id); child.kill(); reject(new Error('MCP operation deadline exceeded')); }, timeout);
+    pending.set(id, { resolve: reply => { clearTimeout(timer); resolve(reply); }, reject: error => { clearTimeout(timer); reject(error); } });
+    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+  });
+}
+try {
+  const initialized = await rpc('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'codex', version: 'native-session-cli-v1' } });
+  if (initialized.error) throw new Error(initialized.error.message);
+  const initial = await rpc('tools/call', { name: tool, arguments: args });
+  let reply = initial;
+  if (watching) {
+    if (initial.error || initial.result?.isError) throw new Error('Initial selected-tenant session list failed');
+    const notices = response => (response.result?.content || []).filter(item => item.type === 'text' && /^genetics:/.test(item.text || ''));
+    let shown = notices(initial);
+    // Resolve can finish after the first tool response. Emit its real notice before
+    // waiting for the automatic update; do not synthesize a consent flag.
+    for (let attempt = 0; !shown.length && attempt < 5 && watchDeadline - Date.now() > 600; attempt++) {
+      await new Promise(resolve => setTimeout(resolve, 250));
+      shown = notices(await rpc('tools/call', { name: 'whoami', arguments: {} }));
+    }
+    for (const notice of shown) process.stderr.write(notice.text + '\n');
+    await new Promise(resolve => setTimeout(resolve, Math.max(0, watchDeadline - Date.now() - Math.min(5000, seconds * 250))));
+    reply = await rpc('tools/call', { name: tool, arguments: args });
+  }
+  process.stdout.write(JSON.stringify({ operation, tenant: options.tenant || null, uuid: options.uuid || null,
+    ...(watching ? { initial: initial.result, notifications_drained: notifications, window_seconds: seconds } : {}), result: reply.result || reply.error }) + '\n');
+  if (reply.error || reply.result?.isError) process.exitCode = 1;
+} catch (e) { process.stderr.write(`${e.message}\n`); process.exitCode = 1; }
+finally {
+  child.stdin.end();
+  if (child.exitCode === null) { const closed = new Promise(resolve => child.once('exit', resolve));
+    const kill = setTimeout(() => child.kill('SIGKILL'), 3000); await closed; clearTimeout(kill); }
+}

package/codex-session.mjs

@@ -0,0 +1,353 @@
+/** Native Codex rollout → portal wire records. No Claude transcript is created.
+ * Raw offsets belong to the rollout; Genetics append offsets belong to this versioned projection.
+ * First scan is sequential and bounded; later scans read only complete appended records.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const CODEX_CODEC = 'codex-rollout-v1';
+export const CODEX_LIMITS = Object.freeze({ input_bytes: 8 * 1024 ** 3, record_bytes: 4 * 1024 ** 2,
+  projection_bytes: 64 * 1024 ** 2, cache_bytes: 512 * 1024 ** 2, cache_entries: 256,
+  records: 1_000_000, files: 10_000, directories: 4096, chunk_bytes: 1024 ** 2 });
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MASK = '[가림: 서버에 올리며 지움]';
+
+export function codexSessionId(env = process.env) {
+  // A child has its own THREAD_ID; SESSION_ID can still name its parent.
+  const id = env.CODEX_THREAD_ID || env.CODEX_SESSION_ID || '';
+  return UUID.test(id) ? id.toLowerCase() : '';
+}
+
+function plainFile(file) {
+  try { const st = fs.lstatSync(file); return st.isFile() && !st.isSymbolicLink() ? st : null; } catch { return null; }
+}
+
+/** Fixed date depth, no symlinks, and an explicit inventory budget. */
+export function codexRollouts(home = os.homedir()) {
+  const root = path.join(home, '.codex', 'sessions');
+  try { if (fs.lstatSync(path.join(home, '.codex')).isSymbolicLink()) return []; } catch { return []; }
+  const found = [];
+  let directories = 0, files = 0;
+  const visit = (dir, depth) => {
+    let entries;
+    try { if (!fs.lstatSync(dir).isDirectory() || fs.lstatSync(dir).isSymbolicLink()) return;
+      entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    if (++directories > CODEX_LIMITS.directories) throw new Error('Codex session directory inventory limit exceeded');
+    entries.sort((a, b) => b.name.localeCompare(a.name));
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const file = path.join(dir, entry.name);
+      if (depth < 3 && entry.isDirectory() && (depth === 0 ? /^\d{4}$/ : /^(0[1-9]|[12]\d|3[01])$/).test(entry.name)) visit(file, depth + 1);
+      if (depth !== 3 || !entry.isFile()) continue;
+      if (++files > CODEX_LIMITS.files) throw new Error('Codex session file inventory limit exceeded');
+      const m = /^rollout-.*-([0-9a-f-]{36})\.jsonl$/i.exec(entry.name);
+      if (m && UUID.test(m[1])) found.push({ uuid: m[1].toLowerCase(), file });
+    }
+  };
+  visit(root, 0);
+  return found;
+}
+
+export function codexMetadata(file, uuid) {
+  const st = plainFile(file);
+  if (!st || st.size > CODEX_LIMITS.input_bytes || (process.getuid && st.uid !== process.getuid())) return null;
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+  try {
+    const opened = fs.fstatSync(fd);
+    if (opened.ino !== st.ino || opened.dev !== st.dev || opened.uid !== st.uid) return null;
+    const bytes = Buffer.alloc(Math.min(st.size, 64 * 1024));
+    fs.readSync(fd, bytes, 0, bytes.length, 0);
+    const end = bytes.indexOf(10);
+    if (end < 0) return null; // active partial metadata is never a source
+    const r = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, end)));
+    const p = r.payload;
+    if (r.type !== 'session_meta' || !UUID.test(p?.id || '') || p.id.toLowerCase() !== uuid.toLowerCase()
+        || typeof p.cwd !== 'string' || !path.isAbsolute(p.cwd)) return null;
+    const version = /^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(p.cli_version || '') ? p.cli_version : 'unknown';
+    return { uuid: p.id.toLowerCase(), cwd: p.cwd, cli_version: version, source_ino: String(st.ino), source_dev: String(st.dev), source_uid: st.uid,
+      parent_thread_id: p.parent_thread_id || null, forked_from_id: p.forked_from_id || null,
+      thread_source: p.thread_source || null, source: p.source || null, file, size: st.size, mtime: st.mtimeMs };
+  } catch { return null; } finally { fs.closeSync(fd); }
+}
+
+export function findCodexRollout(uuid, home = os.homedir()) {
+  if (!UUID.test(uuid || '')) return null;
+  const named = codexRollouts(home).filter(r => r.uuid === uuid.toLowerCase());
+  const matches = named.map(r => codexMetadata(r.file, uuid)).filter(Boolean);
+  if (matches.length > 1) throw new Error(`Ambiguous native Codex session UUID: ${uuid}`);
+  if (named.length && !matches.length) throw new Error(`Native Codex source metadata/ownership/size cannot be verified: ${uuid}`);
+  return matches[0] || null;
+}
+
+export function codexHumanRoot(meta) {
+  return !meta.parent_thread_id && !meta.forked_from_id && (!meta.source || typeof meta.source !== 'object')
+    && (!meta.thread_source || meta.thread_source === 'user');
+}
+
+function textContent(p) {
+  if (!Array.isArray(p.content)) return [];
+  const blocks = [];
+  for (const b of p.content) {
+    if ((b?.type === 'input_text' || b?.type === 'output_text') && typeof b.text === 'string') {
+      if (p.role === 'user' && (/^\s*# AGENTS\.md instructions/.test(b.text) || /^\s*<INSTRUCTIONS>/.test(b.text))) continue;
+      const text = b.text.replace(/<environment_context>[\s\S]*?<\/environment_context>/g, '').trim();
+      if (text) blocks.push({ type: 'text', text });
+    } else if (b?.type === 'input_image' || b?.type === 'image') blocks.push({ type: 'text', text: '[첨부 이미지 생략]' });
+  }
+  return blocks;
+}
+
+export function codexWireRecord(r, metadata, offset) {
+  const p = r?.payload;
+  if (!p || typeof p !== 'object') return null;
+  if ((r.type === 'session_meta' || r.type === 'turn_context') && typeof p.cwd === 'string')
+    return { type: 'system', cwd: p.cwd }; // scrub counts every source cwd before dropping this marker
+  if (r.type !== 'response_item') return null; // event_msg duplicates, reasoning, token accounting
+  const base = { uuid: crypto.createHash('sha256').update(`${metadata.uuid}:${offset}`).digest('hex').slice(0, 32),
+    timestamp: r.timestamp, cwd: metadata.cwd, source_client: 'codex' };
+  if (p.type === 'message') {
+    if (!['user', 'assistant'].includes(p.role) || (p.role === 'assistant' && p.channel != null && !['final', 'commentary', 'default'].includes(p.channel))) return null;
+    const content = textContent(p);
+    return content.length ? { ...base, type: p.role, message: { role: p.role, content } } : null;
+  }
+  if (p.type === 'custom_tool_call' || p.type === 'function_call') {
+    if (typeof p.name !== 'string' || typeof p.call_id !== 'string') throw new Error('Codex tool call lacks name/call_id');
+    let input = { source: String(p.input ?? p.arguments ?? '') };
+    if (p.type === 'function_call') { try { input = JSON.parse(p.arguments); } catch { /* preserve text, never execute */ } }
+    return { ...base, type: 'assistant', message: { role: 'assistant', content: [{ type: 'tool_use', id: p.call_id, name: p.name, input }] } };
+  }
+  if (p.type === 'custom_tool_call_output' || p.type === 'function_call_output') {
+    if (typeof p.call_id !== 'string') throw new Error('Codex tool result lacks call_id');
+    return { ...base, type: 'user', message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: p.call_id, content: MASK }] } };
+  }
+  return null;
+}
+
+/** Oversized output can be masked without decoding its body. Anything potentially publishable fails closed. */
+function oversizedRecord(prefix) {
+  const s = prefix.toString('utf8');
+  if (/"type"\s*:\s*"(event_msg|reasoning|compacted)"/.test(s.slice(0, 256))) return null;
+  if (!/^\s*\{[^\n]*?"type"\s*:\s*"response_item"/.test(s.slice(0, 256))) throw new Error('Oversized Codex record cannot be safely classified');
+  const output = /"payload"\s*:\s*\{\s*"type"\s*:\s*"(custom_tool_call_output|function_call_output)"/.exec(s);
+  const call = /"call_id"\s*:\s*("(?:[^"\\]|\\.)*")/.exec(s);
+  const timestamp = /"timestamp"\s*:\s*("(?:[^"\\]|\\.)*")/.exec(s);
+  if (!output || !call) throw new Error('Codex publishable record exceeds record_bytes limit');
+  return { type: 'response_item', timestamp: timestamp ? JSON.parse(timestamp[1]) : null,
+    payload: { type: output[1], call_id: JSON.parse(call[1]) } };
+}
+
+/** JSON lexical filtering: only an actual image_url string value is omitted, never quoted user text.
+ * A screenshot may be tens of MiB, while its surrounding human text stays within record_bytes.
+ */
+class ImageOmitter {
+  constructor() { this.string = false; this.omit = false; this.token = ''; this.between = ''; this.slashes = 0; this.images = 0; }
+  filter(bytes) {
+    const out = [];
+    for (let at = 0; at < bytes.length;) {
+      if (!this.string) {
+        const q = bytes.indexOf(34, at), end = q < 0 ? bytes.length : q;
+        const between = bytes.subarray(at, end);
+        out.push(between);
+        this.between = (this.between + between.toString('ascii')).slice(-32);
+        if (q < 0) break;
+        this.omit = this.token === 'image_url' && /^\s*:\s*$/.test(this.between);
+        this.token = ''; this.between = ''; this.slashes = 0; this.string = true;
+        out.push(bytes.subarray(q, q + 1));
+        if (this.omit) { out.push(Buffer.from('[첨부 이미지 생략]')); this.images++; }
+        at = q + 1;
+      } else {
+        const q = bytes.indexOf(34, at), end = q < 0 ? bytes.length : q;
+        const value = bytes.subarray(at, end);
+        if (!this.omit) { out.push(value); if (this.token.length <= 256) this.token += value.toString('utf8'); }
+        let slashes = 0;
+        for (let i = end - 1; i >= at && bytes[i] === 92; i--) slashes++;
+        if (slashes === value.length) slashes += this.slashes;
+        this.slashes = slashes;
+        if (q < 0) break;
+        if (!this.omit) out.push(bytes.subarray(q, q + 1));
+        if (slashes % 2) { if (this.token.length <= 256) this.token += '"'; this.slashes = 0; at = q + 1; continue; }
+        if (this.omit) out.push(bytes.subarray(q, q + 1));
+        this.string = false; this.omit = false; this.between = ''; this.slashes = 0;
+        at = q + 1;
+      }
+    }
+    return Buffer.concat(out);
+  }
+}
+
+function hashWindow(fd, start, length) {
+  const bytes = Buffer.alloc(length);
+  if (fs.readSync(fd, bytes, 0, length, start) !== length) throw new Error('Codex source changed while reading');
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function readState(file) {
+  try { const st = plainFile(file); if (!st || st.size > 64 * 1024) return null;
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    try { return JSON.parse(fs.readFileSync(fd, 'utf8')); } finally { fs.closeSync(fd); }
+  } catch { return null; }
+}
+
+/** mkdir ownership prevents a live-lock rename window. Reap only a dead PID on this host, never by age. */
+function projectionLock(dir) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let made = false;
+    try {
+      fs.mkdirSync(dir, { mode: 0o700 }); made = true;
+      const ino = fs.lstatSync(dir).ino;
+      fs.writeFileSync(path.join(dir, 'owner.json'), JSON.stringify({ pid: process.pid, host: os.hostname() }), { mode: 0o600 });
+      return () => { try { if (fs.lstatSync(dir).ino === ino) fs.rmSync(dir, { recursive: true }); } catch (e) { if (e.code !== 'ENOENT') throw e; } };
+    } catch (e) { if (made) fs.rmSync(dir, { recursive: true, force: true }); if (e.code !== 'EEXIST') throw e; }
+    const lockStat = fs.lstatSync(dir);
+    if (!lockStat.isDirectory() || lockStat.isSymbolicLink()) break;
+    const owner = readState(path.join(dir, 'owner.json'));
+    let dead = false;
+    if (owner?.host === os.hostname() && Number.isSafeInteger(owner.pid) && owner.pid > 0) {
+      try { process.kill(owner.pid, 0); } catch (e) { dead = e.code === 'ESRCH'; }
+    }
+    if (!dead) break;
+    let reap;
+    try { reap = fs.openSync(path.join(dir, 'reaping'), 'wx', 0o600); } catch { break; }
+    try {
+      const still = readState(path.join(dir, 'owner.json'));
+      if (still?.pid !== owner.pid || still?.host !== owner.host) break;
+      fs.rmSync(dir, { recursive: true });
+    } finally { fs.closeSync(reap); }
+  }
+  throw new Error('Native Codex projection is already being refreshed; retry after it completes');
+}
+
+function checkCacheBudget(root, output, nextBytes) {
+  let bytes = nextBytes, entries = 1;
+  const names = fs.readdirSync(root);
+  if (names.length > CODEX_LIMITS.cache_entries * 3 + 8) throw new Error('Codex cache inventory limit exceeded');
+  for (const name of names) {
+    if (!/^[0-9a-f-]{36}\.jsonl$/.test(name)) continue;
+    const file = path.join(root, name);
+    if (file === output) continue;
+    const st = plainFile(file);
+    if (st) { bytes += st.size; entries++; }
+  }
+  if (bytes > CODEX_LIMITS.cache_bytes || entries > CODEX_LIMITS.cache_entries)
+    throw new Error('Codex private projection cache limit exceeded; remove unused native projections before retrying');
+}
+
+function reusable(state, fd, st, output, source) {
+  if (!state || state.codec !== CODEX_CODEC || state.source !== source || state.ino !== String(st.ino) || state.dev !== String(st.dev)
+      || state.raw_off > st.size || plainFile(output)?.size !== state.projection_bytes) return false;
+  if (![state.raw_off, state.projection_bytes, state.records, state.kept, state.prefix_bytes, state.seam_bytes].every(n => Number.isSafeInteger(n) && n >= 0)
+      || state.prefix_bytes > 4096 || state.seam_bytes > 4096 || state.raw_off < state.seam_bytes
+      || state.projection_bytes > CODEX_LIMITS.projection_bytes || state.records > CODEX_LIMITS.records) return false;
+  return state.prefix_sha === hashWindow(fd, 0, state.prefix_bytes)
+    && state.seam_sha === hashWindow(fd, Math.max(0, state.raw_off - state.seam_bytes), state.seam_bytes);
+}
+
+/** O(chunk + record + projection cap), never O(rollout size). A partial trailing record is deferred. */
+async function project(fd, snapshotBytes, start, metadata, scrub, delta, old) {
+  const out = fs.openSync(delta, 'wx', 0o600);
+  const chunk = Buffer.alloc(CODEX_LIMITS.chunk_bytes);
+  let parts = [], recordBytes = 0, sourceRecordBytes = 0, prefix = Buffer.alloc(0), oversized = false;
+  let imageFilter = new ImageOmitter(), omittedImages = old?.omitted_images || 0, omittedLarge = old?.omitted_large || 0;
+  let rawOffset = start, recordStart = start, records = old?.records || 0, kept = old?.kept || 0;
+  let projectionBytes = old?.projection_bytes || 0, cwd = old?.cwd || metadata.cwd;
+  try {
+    for (let pos = start; pos < snapshotBytes;) {
+      const length = Math.min(chunk.length, snapshotBytes - pos);
+      const n = fs.readSync(fd, chunk, 0, length, pos);
+      if (n !== length) throw new Error('Codex source shrank while projecting');
+      for (let at = 0; at < n;) {
+        const newline = chunk.indexOf(10, at);
+        const end = newline < 0 || newline >= n ? n : newline;
+        const piece = chunk.subarray(at, end);
+        sourceRecordBytes += piece.length;
+        if (prefix.length < 64 * 1024) prefix = Buffer.concat([prefix, piece.subarray(0, 64 * 1024 - prefix.length)]);
+        const retained = oversized ? Buffer.alloc(0) : imageFilter.filter(piece);
+        recordBytes += oversized ? piece.length : retained.length;
+        if (recordBytes <= CODEX_LIMITS.record_bytes) parts.push(retained);
+        else { oversized = true; parts = []; }
+        if (end < n) {
+          if (++records > CODEX_LIMITS.records) throw new Error('Codex record count limit exceeded');
+          const r = oversized ? oversizedRecord(prefix) : JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts)));
+          omittedImages += imageFilter.images;
+          if (sourceRecordBytes > CODEX_LIMITS.record_bytes && r?.payload?.type !== 'message') omittedLarge++;
+          if (r && (r.type === 'turn_context' || r.type === 'session_meta') && typeof r.payload?.cwd === 'string') cwd = r.payload.cwd;
+          const row = r ? codexWireRecord(r, { ...metadata, cwd }, recordStart) : null;
+          let wire = '';
+          if (row?.type === 'system') wire = JSON.stringify(row) + '\n';
+          else if (row) {
+            wire = scrub(JSON.stringify(row) + '\n', { delta: true }).jsonl;
+            if (wire) { const masked = JSON.parse(wire); masked.cwd = cwd; wire = JSON.stringify(masked) + '\n'; kept++; }
+          }
+          projectionBytes += Buffer.byteLength(wire);
+          if (projectionBytes > CODEX_LIMITS.projection_bytes) throw new Error('Codex projection_bytes limit exceeded; no upload performed');
+          if (wire) fs.writeSync(out, wire);
+          rawOffset = pos + end + 1; recordStart = rawOffset;
+          parts = []; recordBytes = 0; sourceRecordBytes = 0; prefix = Buffer.alloc(0); oversized = false; imageFilter = new ImageOmitter();
+        }
+        at = end < n ? end + 1 : n;
+      }
+      pos += n;
+      await new Promise(resolve => setImmediate(resolve)); // cancel/stdio/timers can progress during multi-GiB scans
+    }
+    fs.fsyncSync(out);
+    return { raw_off: rawOffset, records, kept, projection_bytes: projectionBytes, cwd, deferred_bytes: snapshotBytes - rawOffset,
+      omitted_images: omittedImages, omitted_large: omittedLarge };
+  } finally { fs.closeSync(out); }
+}
+
+export async function prepareCodexProjection(metadata, { cacheRoot, scrub, scrubRevision = '' } = {}) {
+  if (typeof scrub !== 'function' || !cacheRoot) throw new Error('Codex projection requires the canonical Genetics scrubber and private cacheRoot');
+  fs.mkdirSync(cacheRoot, { recursive: true, mode: 0o700 });
+  if (fs.lstatSync(cacheRoot).isSymbolicLink()) throw new Error('Codex projection directory must not be a symlink');
+  fs.chmodSync(cacheRoot, 0o700);
+  const output = path.join(cacheRoot, `${metadata.uuid}.jsonl`), stateFile = path.join(cacheRoot, `${metadata.uuid}.json`);
+  // One cache writer bounds aggregate temporary bytes as well as duplicate multi-GiB scans.
+  const unlock = projectionLock(path.join(cacheRoot, '.refresh.lock'));
+  const delta = output + `.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  let fd;
+  try {
+    fd = fs.openSync(metadata.file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    const st = fs.fstatSync(fd);
+    if (st.size > CODEX_LIMITS.input_bytes) throw new Error('Codex input_bytes limit exceeded');
+    if (String(st.ino) !== metadata.source_ino || String(st.dev) !== metadata.source_dev
+        || st.uid !== metadata.source_uid || (process.getuid && st.uid !== process.getuid()))
+      throw new Error('Codex opened source inode/ownership differs from discovery');
+    const head = Buffer.alloc(Math.min(st.size, 64 * 1024)); fs.readSync(fd, head, 0, head.length, 0);
+    const headEnd = head.indexOf(10);
+    const actual = headEnd >= 0 ? JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(head.subarray(0, headEnd))) : null;
+    if (actual?.type !== 'session_meta' || actual.payload?.id?.toLowerCase() !== metadata.uuid || actual.payload?.cwd !== metadata.cwd)
+      throw new Error('Codex opened source metadata does not match the selected session');
+    const state = readState(stateFile);
+    const old = state?.scrub_revision === scrubRevision && reusable(state, fd, st, output, metadata.file) ? state : null;
+    const initialPrefixBytes = Math.min(st.size, 4096), initialPrefix = hashWindow(fd, 0, initialPrefixBytes);
+    const next = await project(fd, st.size, old?.raw_off || 0, metadata, scrub, delta, old);
+    if (!next.kept) throw new Error('Native Codex session has no publishable messages');
+    if (hashWindow(fd, 0, initialPrefixBytes) !== initialPrefix || fs.fstatSync(fd).size < st.size)
+      throw new Error('Codex source changed while projecting; retry from the verified source');
+    checkCacheBudget(cacheRoot, output, next.projection_bytes);
+    if (old) {
+      const dest = fs.openSync(output, fs.constants.O_WRONLY | fs.constants.O_APPEND | (fs.constants.O_NOFOLLOW || 0));
+      try { for await (const bytes of fs.createReadStream(delta)) fs.writeSync(dest, bytes); fs.fsyncSync(dest); } finally { fs.closeSync(dest); }
+    } else fs.renameSync(delta, output);
+    fs.chmodSync(output, 0o600);
+    const prefixBytes = Math.min(next.raw_off, 4096), seamBytes = Math.min(next.raw_off, 4096);
+    const receipt = { ...next, codec: CODEX_CODEC, scrub_revision: scrubRevision, source: metadata.file, ino: String(st.ino), dev: String(st.dev),
+      prefix_bytes: prefixBytes, prefix_sha: hashWindow(fd, 0, prefixBytes), seam_bytes: seamBytes,
+      seam_sha: hashWindow(fd, next.raw_off - seamBytes, seamBytes), metadata };
+    fs.writeFileSync(delta + '.state', JSON.stringify(receipt), { mode: 0o600 });
+    fs.renameSync(delta + '.state', stateFile);
+    return { ...metadata, projection: output, source_bytes: st.size, ...next, codec: CODEX_CODEC };
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    fs.rmSync(delta, { force: true }); fs.rmSync(delta + '.state', { force: true });
+    unlock();
+  }
+}
+
+export function cachedCodexProjection(metadata, cacheRoot) {
+  const file = path.join(cacheRoot, `${metadata.uuid}.jsonl`);
+  const state = readState(path.join(cacheRoot, `${metadata.uuid}.json`));
+  return state?.codec === CODEX_CODEC && state.source === metadata.file && plainFile(file)?.size === state.projection_bytes ? file : null;
+}