great-cto 3.70.1 → 3.72.0

package/board/scripts/lib/codex-pipeline.mjs

@@ -7,6 +7,8 @@ import { parsePipelineToml } from './pipeline-toml.mjs';
 import { scan } from './secret-patterns.mjs';
 import { runCodexExec, codexToolEvent } from './codex-exec.mjs';
 import { runClaudeExec } from './claude-exec.mjs';
+import { auditHostGraphRuntimes } from './host-graph-runtime.mjs';
+import { graphBinding, observeHostGraph, recordHostGraphGap } from './host-graph-observer.mjs';
 import { appendEvent } from './agent-events.mjs';
 import { snapshotTurn, pruneTurns } from './turn-snapshot.mjs';
 import { treeReceipt } from './receipt.mjs';
@@ -74,11 +76,37 @@ function emit(state, event) {
   // The user ran this pipeline here, so it keeps its log here even before /start.
   return appendEvent(join(state.root, '.great_cto'), { ...event, session: state.id }, { explicit: true });
 }
-const toolListener = (state, agent, invocationId = null) => (ev) => {
+const toolListener = (state, agent, invocationId = null, sourceAudited = false, trustedAttemptId = null) => (ev) => {
+  if (state.observeHostGraph === true && invocationId) {
+    const attempt = (state.attempts || []).find(a => a.invocationId === invocationId || a.verifierInvocationId === invocationId);
+    // Parallel worker callbacks precede prepared attempts, but their wave ID is durable.
+    const host = agent.startsWith('claude-') ? 'claude-code' : 'codex';
+    const observed = observeHostGraph({ binding: graphBinding({ root: state.root, runId: state.id, sessionId: invocationId, attemptId: attempt?.id || trustedAttemptId, host }),
+      host, mode: 'controlled', sourceVersion: sourceAudited ? state.hostObservationSources?.find(s => s.host === host)?.sourceVersion || null : null, event: ev });
+    state.hostObservationHealth ||= { state: 'recorded', recorded: 0 };
+    state.hostObservationHealth.recorded += observed.recorded;
+    if (observed.state === 'degraded') state.hostObservationHealth.state = 'degraded';
+  }
   const e = codexToolEvent(ev);
   if (e) emit(state, { ...e, agent, invocation_id: invocationId });
 };
 
+/** Provider-free audit is refreshed for each controller action, never a completeness attestation. */
+export function refreshHostObservationSources(state, { save = () => {}, audit = auditHostGraphRuntimes } = {}) {
+  if (state.observeHostGraph !== true) return;
+  state.hostObservationSources = audit({ binaries: {
+    codex: process.env.GREAT_CTO_CODEX_BIN || 'codex', 'claude-code': process.env.GREAT_CTO_CLAUDE_BIN || 'claude',
+  } });
+  save(state);
+}
+
+function observeRunnerHealth(state, response, { host, invocationId, attemptId }) {
+  if (!state.observeHostGraph || response.observationHealth !== 'degraded') return;
+  state.hostObservationHealth ||= { state: 'recorded', recorded: 0 };
+  state.hostObservationHealth.state = 'degraded';
+  recordHostGraphGap(graphBinding({ root: state.root, runId: state.id, sessionId: invocationId, attemptId, host }), host, 'controlled', ['observer-transport-failure']);
+}
+
 /**
  * ADR-026 — what a stage is told about the stages before it.
  *
@@ -175,8 +203,10 @@ function releaseSummary(state) {
 
 export async function verifyStage(state, role, proposal, execute) {
   const agent = 'codex-verifier';
+  const verifierAttempt = state.attempts?.findLast(a => a.role === role);
   const invocationId = invocationIdentity({ session_id: state.id,
-    agent_id: `${state.attempts?.findLast(a => a.role === role)?.id || randomUUID()}:verifier` });
+    agent_id: `${verifierAttempt?.id || randomUUID()}:verifier` });
+  if (verifierAttempt) verifierAttempt.verifierInvocationId = invocationId;
   const t0 = Date.now();
   let ok = false;
   emit(state, { kind: 'agent-start', agent, invocation_id: invocationId });
@@ -189,10 +219,10 @@ export async function verifyStage(state, role, proposal, execute) {
       if (attempt && admitted.evidence) attempt.domainVerifierContext = admitted.evidence;
       return execute(admitted.options);
     };
-    const result = cleanResponse(await invoke({
+    const verifierResponse = await invoke({
       cwd: state.root, sandbox: 'read-only', ephemeral: true, extraArgs: workerArgs,
       bin: process.env.GREAT_CTO_CODEX_BIN || 'codex', timeoutMs: 300000,
-      invocationId, onEvent: toolListener(state, agent, invocationId),
+      invocationId, onEvent: toolListener(state, agent, invocationId, execute === runCodexExec),
       prompt: `You are an independent verifier for the ${role} stage. Read the ACTUAL files and assess whether they satisfy the task for this stage.\n` +
         frozenPolicyContext(state) +
         (state.specialistStages?.[role] ? `Controlled phase: ${state.specialistStages[role].phase}, before implementation. Verify an implementable contract/threat model and its evidence; do not require nonexistent implementation or treat design sign-off as code approval. Capability: ${codexRoleProfile(specialistRole(state, role))}\n` : '') +
@@ -220,7 +250,9 @@ export async function verifyStage(state, role, proposal, execute) {
         `Do not treat file existence, a previous agent's statement or tests that were not executed as evidence of correctness. ` +
         `Return ONLY JSON {"state":"verified|rework|unverifiable","findings":["..."],"checks":["what you actually inspected or ran"]}, plus dependencyAttestation when scoped dependency evidence is provided. ` +
         `Use unverifiable if unable to inspect the evidence. Use rework when you find defects. No gate approval or file proposals.`,
-    }));
+    });
+    observeRunnerHealth(state, verifierResponse, { host: 'codex', invocationId, attemptId: verifierAttempt?.id || null });
+    const result = cleanResponse(verifierResponse);
     if (!['verified', 'rework', 'unverifiable'].includes(result.state) || !Array.isArray(result.findings) || !Array.isArray(result.checks) || !result.checks.length) throw Error('invalid or empty verifier evidence');
     if (attestWorkflow && result.state === 'verified') {
       const a = result.workflowAttestation;
@@ -650,6 +682,7 @@ export async function runStage(state, { execute = null, runners = { codex: runCo
   if (state.status === 'cancelled') return state;
   if (state.active) throw Error('interrupted stage: inspect state and files before starting a new run');
   if (state.status !== 'ready') return state;
+  refreshHostObservationSources(state, { save });
   preflightSpecialistEpoch(state, save);
   if (state.steps >= 32) throw Error('32-stage run limit reached');
   assertArtifacts(state);
@@ -753,8 +786,9 @@ export async function runStage(state, { execute = null, runners = { codex: runCo
       stageStarted = true; emit(state, { kind: 'agent-start', agent, invocation_id: attempt.invocationId });
       return observeControllerCall(state, { id: `${attempt.id}:worker`, attemptId: attempt.id, host: roleHost(state, role), role, kind: 'worker' }, () => runner({ prompt: admitted.options.prompt, cwd: state.root, sandbox: 'read-only', ephemeral: true,
       bin: roleHost(state, role) === 'codex' ? process.env.GREAT_CTO_CODEX_BIN || 'codex' : process.env.GREAT_CTO_CLAUDE_BIN || 'claude',
-      invocationId: attempt.invocationId, timeoutMs: 300000, extraArgs: roleHost(state, role) === 'codex' ? workerArgs : [], onEvent: toolListener(state, agent, attempt.invocationId) }), save);
+      invocationId: attempt.invocationId, timeoutMs: 300000, extraArgs: roleHost(state, role) === 'codex' ? workerArgs : [], onEvent: roleHost(state, role) === 'codex' || state.observeHostGraph === true ? toolListener(state, agent, attempt.invocationId, runner === runCodexExec || runner === runClaudeExec) : null }), save);
     });
+    observeRunnerHealth(state, response, { host: roleHost(state, role), invocationId: attempt.invocationId, attemptId: attempt.id });
     const proposalSource = traceKey(state, `dispatch:${attempt.id}`) || traceKey(state, `reuse:${attempt.id}`) || contextNode;
     // Codex can recover its session-index lookup without degrading the worker.
     // Keep the diagnostic in the receipt; every other warning/error blocks.
@@ -833,6 +867,7 @@ export async function runStage(state, { execute = null, runners = { codex: runCo
     const beforeVerifier = stageReceipt(state, treeReceipt(state.root), 'verifier input');
     if (JSON.stringify(beforeVerifier) !== JSON.stringify(receipt)) throw Error('working tree changed before verification');
     if (!attempt.checks || attempt.checks.state === 'passed') {
+      attempt.verifierInvocationId = invocationIdentity({ session_id: state.id, agent_id: `${attempt.id}:verifier` });
       recordTrace(state, 'verifier', { key: `verifier:${attempt.id}`, role, attemptId: attempt.id, host: 'codex', status: 'intent',
         parents: [traceKey(state, `checks:${attempt.id}`) || proposalSource,
           ...traceParents(state, Object.keys(state.results), false)], relation: 'verification', input: receipt });
@@ -959,6 +994,7 @@ function preflightParallelProposals(state, roles, responses) {
 /** Dispatch two read-only workers together, then apply their proposals one by one. */
 export async function runParallelWave(state, { runners = { codex: runCodexExec, 'claude-code': runClaudeExec },
   verify = verifyStage, checks = runChecks, save = () => {}, contextStore = null } = {}) {
+  refreshHostObservationSources(state, { save });
   preflightSpecialistEpoch(state, save);
   if (!state.wave) {
     const roles = parallelPair(state);
@@ -998,7 +1034,8 @@ export async function runParallelWave(state, { runners = { codex: runCodexExec,
         const result = await observeControllerCall(state, { id: `${waveId}:${role}`, attemptId: state.wave.attemptIds[role], host: roleHost(state, role), role, kind: 'worker' }, () => runner({ prompt: admitted.options.prompt, cwd: state.root,
           sandbox: 'read-only', ephemeral: true, timeoutMs: 300000,
           bin: roleHost(state, role) === 'codex' ? process.env.GREAT_CTO_CODEX_BIN || 'codex' : process.env.GREAT_CTO_CLAUDE_BIN || 'claude',
-          invocationId, extraArgs: roleHost(state, role) === 'codex' ? workerArgs : [], onEvent: toolListener(state, agent, invocationId) }), save);
+          invocationId, extraArgs: roleHost(state, role) === 'codex' ? workerArgs : [], onEvent: roleHost(state, role) === 'codex' || state.observeHostGraph === true ? toolListener(state, agent, invocationId, runner === runCodexExec || runner === runClaudeExec, state.wave.attemptIds[role]) : null }), save);
+        observeRunnerHealth(state, result, { host: roleHost(state, role), invocationId, attemptId: state.wave.attemptIds[role] });
         ok = true;
         return result;
       } finally {

package/board/scripts/lib/host-graph-bindings.mjs

@@ -0,0 +1,135 @@
+/** Explicit local enrollment; native observation grants no execution authority. */
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, openSync, closeSync, fstatSync, fsyncSync, linkSync, mkdirSync, lstatSync, existsSync, readFileSync, writeFileSync, realpathSync, readdirSync, rmSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { assertExternal, projectIdentity } from './work-tasks.mjs';
+import { readHostGraph } from './host-graph-journal.mjs';
+import { graphBinding, observeHostGraph, projectHostObservations, recordHostGraphGap } from './host-graph-observer.mjs';
+import { codexNativeTurnIdentity } from './host-graph-events.mjs';
+const hostSet = new Set(['codex', 'claude-code']);
+const validVersion = value => value === null || (typeof value === 'string' && value.length <= 80 && /^\d{1,5}\.\d{1,5}\.\d{1,5}(?:[-.+][A-Za-z0-9.-]{1,32})?$/.test(value));
+const identity = value => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,128}$/.test(value);
+export const nativeGraphStore = () => process.env.GREAT_CTO_GRAPH_BINDINGS_DIR || join(homedir(), '.great_cto', 'graph-bindings');
+const key = (root, host, sessionId) => createHash('sha256').update(JSON.stringify([projectIdentity(root), host, sessionId])).digest('hex');
+function secure(root, store, create = false) {
+  assertExternal(root, store);
+  let current = resolve(store);
+  while (current !== dirname(current)) {
+    if (existsSync(current) && lstatSync(current).isSymbolicLink()) throw Error('graph binding store has a symbolic link');
+    current = dirname(current);
+  }
+  if (create) mkdirSync(store, { recursive: true, mode: 0o700 });
+  if (existsSync(store) && (!lstatSync(store).isDirectory() || (lstatSync(store).mode & 0o077) || (process.getuid && lstatSync(store).uid !== process.getuid()))) throw Error('graph bindings require private permissions');
+}
+function syncDirectory(store) { const fd = openSync(store, constants.O_RDONLY); try { fsyncSync(fd); } finally { closeSync(fd); } }
+function readPrivate(file) {
+  const fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.mode & 0o077 || stat.size > 4096 || (process.getuid && stat.uid !== process.getuid())) throw Error('unsafe graph enrollment');
+    return JSON.parse(readFileSync(fd, 'utf8'));
+  } finally { closeSync(fd); }
+}
+function load(root, host, sessionId, store) {
+  secure(root, store);
+  const file = join(store, `${key(root, host, sessionId)}.json`);
+  if (!existsSync(file)) return null;
+  const b = readPrivate(file);
+  if (b.version !== 1 || b.root !== realpathSync(root) || b.projectId !== projectIdentity(root) || b.host !== host || b.sessionId !== sessionId || b.runId !== sessionId) throw Error('graph enrollment binding mismatch');
+  return b;
+}
+export function bindNativeGraph({ root, host, sessionId, sourceVersion = null }, { store = nativeGraphStore() } = {}) {
+  if (!hostSet.has(host) || !identity(sessionId) || !validVersion(sourceVersion)) throw Error('invalid native graph binding');
+  secure(root, store, true);
+  const binding = { version: 1, ...graphBinding({ root: realpathSync(root), runId: sessionId, sessionId }), host, sourceVersion };
+  const file = join(store, `${key(root, host, sessionId)}.json`), tmp = `${file}.${process.pid}.tmp`;
+  if (existsSync(file)) { load(root, host, sessionId, store); throw Error('session already enrolled; remove binding before changing capabilities'); }
+  try { writeFileSync(tmp, JSON.stringify(binding), { mode: 0o600, flag: 'wx' });
+    const fd = openSync(tmp, constants.O_RDONLY); try { fsyncSync(fd); } finally { closeSync(fd); }
+    linkSync(tmp, file); }
+  finally { rmSync(tmp, { force: true }); syncDirectory(store); }
+  return { state: 'enrolled', host, sessionId, projectId: binding.projectId, authority: 'observation-only' };
+}
+export function unbindNativeGraph({ root, host, sessionId }, { store = nativeGraphStore() } = {}) {
+  if (!hostSet.has(host) || !identity(sessionId)) throw Error('invalid native graph binding');
+  const b = load(root, host, sessionId, store);
+  if (b) { rmSync(join(store, `${key(root, host, sessionId)}.json`)); syncDirectory(store); }
+  return { state: b ? 'unenrolled' : 'absent', authority: 'observation-only' };
+}
+export function observeNativeGraphHook({ root, host, event }, { store = nativeGraphStore(), journalStore } = {}) {
+  const sessionId = event?.session_id;
+  if (!hostSet.has(host) || !identity(sessionId)) return { state: 'ignored' };
+  let b = load(root, host, sessionId, store);
+  if (!b && event.hook_event_name === 'SessionStart') {
+    const policyFile = join(store, `${key(root, host, 'project-policy')}.policy`);
+    if (existsSync(policyFile)) {
+      const policy = readPrivate(policyFile);
+      if (policy.version !== 1 || policy.projectId !== projectIdentity(root) || policy.root !== realpathSync(root) || policy.host !== host || policy.enabled !== true) throw Error('invalid graph observation policy');
+      bindNativeGraph({ root, host, sessionId, sourceVersion: policy.sourceVersion }, { store });
+      b = load(root, host, sessionId, store);
+    }
+  }
+  if (!b) return { state: 'not-enrolled' };
+  const turnHook = ['UserPromptSubmit', 'Stop'].includes(event.hook_event_name);
+  const sourceIdentityPresent = host === 'codex' && turnHook ? !!codexNativeTurnIdentity(event) : !!event.event_id;
+  if ((turnHook || (event.hook_event_name === 'SessionStart' && event.source === 'resume')) && !sourceIdentityPresent) {
+    // Retain each received delivery without pretending it has a replay-safe host ID.
+    b = { ...b, sourceEventId: randomUUID() };
+    recordHostGraphGap(b, host, 'native', ['missing-source-event-identity'], { store: journalStore });
+  }
+  if (['SubagentStart', 'SubagentStop'].includes(event.hook_event_name)) {
+    const roots = readHostGraph(b, { store: journalStore }).events.filter(e => e.host === host && e.kind === 'session' && e.phase === 'started');
+    if (roots.length) b = { ...b, parentIds: [roots[0].id] }; // Same explicitly enrolled session; containment, not dispatch order.
+  }
+  return observeHostGraph({ binding: b, host, mode: 'native', sourceVersion: b.sourceVersion, event, store: journalStore });
+}
+export function nativeGraphObservations(root, { store = nativeGraphStore(), journalStore } = {}) {
+  secure(root, store);
+  if (!existsSync(store)) return [];
+  const rows = [];
+  // Enrollment files are bounded and read only after exact project matching.
+  const names = readdirSync(store).filter(n => /^[a-f0-9]{64}\.json$/.test(n));
+  if (names.length > 4096) throw Error('native graph enrollment read limit');
+  for (const name of names) {
+    const file = join(store, name);
+    const candidate = readPrivate(file);
+    if (candidate.projectId !== projectIdentity(root)) continue;
+    if (!hostSet.has(candidate.host) || !identity(candidate.sessionId)) throw Error('invalid graph enrollment');
+    const b = load(root, candidate.host, candidate.sessionId, store);
+    if (name !== `${key(root, b.host, b.sessionId)}.json`) throw Error('invalid graph enrollment filename');
+    rows.push({ host: b.host, sessionId: b.sessionId, runId: b.runId,
+      graph: projectHostObservations(b, { store: journalStore }) });
+  }
+  return rows;
+}
+
+/** Bounded page of exactly one explicitly enrolled session. */
+export function readNativeGraphPage({ root, host, sessionId, cursor = null, limit = 200 }, { store = nativeGraphStore(), journalStore } = {}) {
+  if (!hostSet.has(host) || !identity(sessionId)) throw Error('invalid native graph binding');
+  const b = load(root, host, sessionId, store);
+  if (!b) throw Error('native session is not enrolled in this project');
+  return projectHostObservations(b, { store: journalStore, cursor, limit });
+}
+
+/** Project opt-in before SessionStart permits observation from the real start event. */
+export function enableNativeGraph({ root, host, sourceVersion = null }, { store = nativeGraphStore() } = {}) {
+  if (!hostSet.has(host) || !validVersion(sourceVersion)) throw Error('invalid graph observation policy');
+  secure(root, store, true);
+  const file = join(store, `${key(root, host, 'project-policy')}.policy`);
+  const body = { version: 1, projectId: projectIdentity(root), root: realpathSync(root), host, sourceVersion, enabled: true };
+  const fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+  try { writeFileSync(fd, JSON.stringify(body)); fsyncSync(fd); } finally { closeSync(fd); }
+  syncDirectory(store);
+  return { state: 'enabled', host, projectId: body.projectId, scope: 'new native sessions in this exact project', authority: 'observation-only' };
+}
+export function disableNativeGraph({ root, host }, { store = nativeGraphStore() } = {}) {
+  if (!hostSet.has(host)) throw Error('invalid graph host');
+  secure(root, store);
+  const file = join(store, `${key(root, host, 'project-policy')}.policy`);
+  if (existsSync(file)) { const p = readPrivate(file); if (p.projectId !== projectIdentity(root) || p.host !== host) throw Error('graph policy mismatch'); rmSync(file); }
+  // Revocation also stops already-enrolled sessions for this host/project.
+  for (const row of nativeGraphObservations(root, { store })) if (row.host === host) unbindNativeGraph({ root, host, sessionId: row.sessionId }, { store });
+  if (existsSync(store)) syncDirectory(store);
+  return { state: 'disabled', authority: 'observation-only', retainedHistory: true };
+}

package/board/scripts/lib/host-graph-events.mjs

@@ -0,0 +1,157 @@
+/** Host observations are metadata, never controller approval or execution authority. */
+import { createHash } from 'node:crypto';
+
+const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const safeId = value => typeof value === 'string' && /^[a-zA-Z0-9_.:-]{1,160}$/.test(value) ? value : null;
+const uuid = value => typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+const version = value => typeof value === 'string' && /^\d{1,5}(?:\.\d{1,5}){0,3}(?:[-+][a-zA-Z0-9.-]{1,32})?$/.test(value) ? value : null;
+const hosts = new Set(['codex', 'claude-code']);
+const modes = new Set(['controlled', 'native']);
+const timestamp = value => typeof value === 'string' && value.length <= 40 && Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null;
+
+/** Supported event families do not attest that a particular run was fully observed. */
+export function hostGraphCapabilities({ host, mode, sourceVersion } = {}) {
+  const known = false; // Version compatibility is established by the collector's capability audit, never semver syntax alone.
+  return { lifecycle: known ? 'supported' : 'unknown', tools: known ? 'supported' : 'unknown',
+    parentChild: known ? 'supported' : 'unknown', verification: 'unsupported', gates: 'unsupported', artifacts: 'unsupported' };
+}
+
+function toolClass(name) {
+  if (typeof name !== 'string') return 'other';
+  if (/^(?:mcp__|mcp:)/.test(name)) return 'mcp';
+  const classes = { Bash: 'shell', shell: 'shell', command_execution: 'shell', Read: 'read', read_file: 'read',
+    Edit: 'write', Write: 'write', MultiEdit: 'write', apply_patch: 'write', file_change: 'write',
+    Glob: 'search', Grep: 'search', WebSearch: 'search', web_search: 'search',
+    Agent: 'agent', Task: 'agent', collab_tool_call: 'agent', mcp_tool_call: 'mcp' };
+  return Object.hasOwn(classes, name) ? classes[name] : 'other';
+}
+const opaque = value => typeof value === 'string' && value.length > 0 && value.length <= 512 ? hash(value) : null;
+const record = value => value && typeof value === 'object' && !Array.isArray(value);
+export function codexNativeTurnIdentity(raw) {
+  if (!['UserPromptSubmit', 'Stop'].includes(raw?.hook_event_name)) return null;
+  return safeId(raw.event_id) || safeId(raw.turn_id);
+}
+const codexTrackedItems = new Set(['command_execution', 'file_change', 'mcp_tool_call', 'web_search', 'collab_tool_call']);
+function ignoredClaudeBlock(block) {
+  if (!record(block)) return false;
+  return (block.type === 'text' && typeof block.text === 'string')
+    || (block.type === 'thinking' && typeof block.thinking === 'string')
+    || (block.type === 'redacted_thinking' && typeof block.data === 'string');
+}
+function ignoredPayload(host, mode, raw, sourceVersion) {
+  if (host === 'codex' && !(mode === 'native' && raw.hook_event_name)) {
+    if (!['item.started', 'item.updated', 'item.completed'].includes(raw.type) || !record(raw.item) || !opaque(raw.item.id)) return false;
+    const item = raw.item;
+    if (raw.type === 'item.updated' && codexTrackedItems.has(item.type)) return true;
+    if (['agent_message', 'reasoning'].includes(item.type)) return typeof item.text === 'string';
+    return item.type === 'todo_list' && Array.isArray(item.items)
+      && item.items.every(value => record(value) && typeof value.text === 'string' && typeof value.completed === 'boolean');
+  }
+  if (host !== 'claude-code') return false;
+  // Audited 2.1.292 schema: this push invalidates rendered UI trees only.
+  // Keep future versions, instance variants and extra structural fields visible
+  // as gaps until independently classified; subtype alone is not evidence.
+  if (mode === 'controlled' && sourceVersion === '2.1.292' && raw.type === 'system' && raw.subtype === 'ui_invalidate'
+    && raw.event === 'ui.render' && uuid(raw.uuid) && uuid(raw.session_id)
+    && Object.keys(raw).length === 5
+    && Object.keys(raw).every(key => ['type', 'subtype', 'event', 'uuid', 'session_id'].includes(key))) return true;
+  if (['assistant', 'user'].includes(raw.type)) {
+    const content = raw.message?.content;
+    return Array.isArray(content) && content.length > 0 && content.every(ignoredClaudeBlock);
+  }
+  // These advisory frames carry no graph lifecycle or causal relationship.
+  if (raw.type === 'system' && raw.subtype === 'status') return raw.status === null || raw.status === 'compacting';
+  if (raw.type === 'system' && raw.subtype === 'compact_boundary') return record(raw.compact_metadata)
+    && ['manual', 'auto'].includes(raw.compact_metadata.trigger) && Number.isSafeInteger(raw.compact_metadata.pre_tokens) && raw.compact_metadata.pre_tokens >= 0;
+  return raw.type === 'rate_limit_event' && record(raw.rate_limit_info)
+    && ['allowed', 'allowed_warning', 'rejected'].includes(raw.rate_limit_info.status);
+}
+function codexEvent(raw) {
+  if (raw.type === 'thread.started') return { kind: 'session', phase: 'started', source: raw.thread_id };
+  if (raw.type === 'turn.started') return { kind: 'turn', phase: 'started' };
+  if (raw.type === 'turn.completed') return { kind: 'turn', phase: 'completed', outcome: 'succeeded' };
+  if (raw.type === 'turn.failed') return { kind: 'turn', phase: 'failed', outcome: 'failed' };
+  if (raw.type === 'error') return { kind: 'error', phase: 'failed', outcome: 'failed' };
+  if (!['item.started', 'item.completed'].includes(raw.type) || !raw.item || typeof raw.item !== 'object') return null;
+  const item = raw.item;
+  if (!codexTrackedItems.has(item.type)) return null;
+  const status = String(item.status || '').toLowerCase();
+  const started = raw.type === 'item.started';
+  const outcome = started ? 'unknown' : ['failed', 'errored'].includes(status) || (Number.isInteger(item.exit_code) && item.exit_code !== 0) ? 'failed'
+    : ['declined', 'cancelled', 'canceled', 'interrupted'].includes(status) ? 'cancelled' : status === 'completed' ? 'succeeded' : 'unknown';
+  return { kind: item.type === 'collab_tool_call' ? 'child' : 'tool', phase: started ? 'started' : outcome === 'failed' ? 'failed' : 'completed',
+    outcome, source: item.id, toolClass: toolClass(item.type) };
+}
+function claudeEvent(raw) {
+  const hook = raw.hook_event_name;
+  const hooks = {
+    SessionStart: { kind: 'session', phase: 'started' }, SessionEnd: { kind: 'session', phase: 'stopped' },
+    UserPromptSubmit: { kind: 'turn', phase: 'started' }, Stop: { kind: 'turn', phase: 'stopped' },
+    PreToolUse: { kind: 'tool', phase: 'started' }, PostToolUse: { kind: 'tool', phase: 'completed', outcome: 'succeeded' },
+    PostToolUseFailure: { kind: 'tool', phase: 'failed', outcome: 'failed' },
+    SubagentStart: { kind: 'child', phase: 'started' }, SubagentStop: { kind: 'child', phase: 'stopped' },
+  };
+  if (Object.hasOwn(hooks, hook || '')) return { ...hooks[hook], source: raw.tool_use_id || raw.agent_id || raw.event_id,
+    toolClass: hooks[hook].kind === 'tool' ? toolClass(raw.tool_name) : hooks[hook].kind === 'child' ? 'agent' : null };
+  if (raw.type === 'system' && raw.subtype === 'init') return { kind: 'session', phase: 'started', source: raw.session_id };
+  if (raw.type === 'result') return { kind: 'turn', phase: raw.is_error === true ? 'failed' : 'completed',
+    outcome: raw.is_error === true ? 'failed' : raw.is_error === false || raw.subtype === 'success' ? 'succeeded' : 'unknown', source: raw.uuid };
+  if (!['assistant', 'user'].includes(raw.type)) return null;
+  const content = raw.message?.content;
+  if (!Array.isArray(content) || content.length !== 1 || !record(content[0])) return null;
+  const b = content[0];
+  if (b.type === 'tool_use' ? !opaque(b.id) || typeof b.name !== 'string' || !b.name.length
+    : b.type === 'tool_result' ? !opaque(b.tool_use_id) || (b.is_error !== undefined && typeof b.is_error !== 'boolean') : true) return null;
+  return b.type === 'tool_use' ? { kind: 'tool', phase: 'started', source: b.id, toolClass: toolClass(b.name) }
+    : { kind: 'tool', phase: b.is_error === true ? 'failed' : 'completed', outcome: b.is_error === true ? 'failed' : b.is_error === false ? 'succeeded' : 'unknown', source: b.tool_use_id, toolClass: 'other' };
+}
+
+/** Bindings come from the operator-owned collector, not fields inside the host payload. */
+export function normalizeHostEvent({ host, mode, sourceVersion, event: raw, binding } = {}) {
+  const capabilities = hostGraphCapabilities({ host, mode, sourceVersion });
+  const rejected = reason => ({ event: null, diagnostics: [reason], capabilities });
+  if (!hosts.has(host) || !modes.has(mode)) return rejected('unsupported-host-or-mode');
+  if (!binding || !safeId(binding.projectId) || !safeId(binding.runId) || !safeId(binding.sessionId)
+    || (binding.attemptId != null && !safeId(binding.attemptId))) return rejected('invalid-trusted-binding');
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return rejected('invalid-event');
+  if (ignoredPayload(host, mode, raw, sourceVersion)) return { event: null, diagnostics: [], capabilities };
+  const hookShape = mode === 'native' && typeof raw.hook_event_name === 'string';
+  const parsed = host === 'codex' && !hookShape ? codexEvent(raw) : claudeEvent(raw);
+  if (!parsed) return rejected('unsupported-event-shape');
+  if (host === 'codex' && hookShape) {
+    // Codex PostToolUse also fires for failed calls; output content is not a status.
+    if (raw.hook_event_name === 'PostToolUse') parsed.outcome = 'unknown';
+    if (['UserPromptSubmit', 'Stop'].includes(raw.hook_event_name)) parsed.source = codexNativeTurnIdentity(raw);
+  }
+  const parents = binding.parentIds ?? [];
+  if (!Array.isArray(parents) || parents.length > 16 || parents.some(p => !safeId(p))) return rejected('invalid-trusted-parents');
+  const diagnostics = [];
+  if (parsed.kind === 'child' && !parents.length) diagnostics.push('missing-explicit-parent');
+  const sequence = Number.isSafeInteger(binding.sequence) && binding.sequence >= 0 ? binding.sequence : null;
+  const rawSourceId = binding.sourceEventId ?? parsed.source ?? binding.turnId ?? null;
+  const sourceEventId = opaque(rawSourceId);
+  if (rawSourceId != null && !sourceEventId) diagnostics.push('missing-source-event-identity');
+  if (!sourceEventId && sequence === null && (['tool', 'child'].includes(parsed.kind) || (parsed.kind === 'turn' && binding.attemptId == null))) diagnostics.push('missing-source-event-identity');
+  if (!version(sourceVersion)) diagnostics.push('source-version-unverified');
+  const event = { schemaVersion: 1, projectId: binding.projectId, runId: binding.runId, sessionId: binding.sessionId,
+    attemptId: binding.attemptId ?? null, host, mode, sourceVersion: version(sourceVersion), sourceEventId, sequence,
+    kind: parsed.kind, phase: parsed.phase, outcome: parsed.outcome || 'unknown', parentIds: [...new Set(parents)],
+    occurredAt: timestamp(raw.timestamp ?? raw.at), toolClass: parsed.toolClass ?? null,
+    callId: ['tool', 'child'].includes(parsed.kind) ? opaque(parsed.source ?? binding.sourceEventId ?? null) : null };
+  // Collector wall clock is excluded: replaying an identical source event is idempotent.
+  return { event: { ...event, id: hash(event), observedAt: new Date().toISOString() }, diagnostics: [...new Set(diagnostics)], capabilities };
+}
+
+/** A streamed Claude message may carry several independent tool blocks. */
+export function normalizeHostEvents(input = {}) {
+  const content = input.event?.message?.content;
+  if (input.host !== 'claude-code' || !['assistant', 'user'].includes(input.event?.type) || !Array.isArray(content)) {
+    const result = normalizeHostEvent(input);
+    return { events: result.event ? [result.event] : [], diagnostics: result.diagnostics, capabilities: result.capabilities };
+  }
+  if (!content.length) return { events: [], diagnostics: ['unsupported-event-shape'], capabilities: hostGraphCapabilities(input) };
+  const results = content.map(block => normalizeHostEvent({ ...input,
+    event: { ...input.event, message: { content: [block] } } }));
+  return { events: results.flatMap(r => r.event ? [r.event] : []),
+    diagnostics: [...new Set(results.flatMap(r => r.diagnostics))], capabilities: hostGraphCapabilities(input) };
+}