oh-my-codex 0.20.0 → 0.20.2

package/src/scripts/__tests__/notify-fallback-delivery.test.ts

@@ -0,0 +1,177 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { deliverNotifyFallback, compactNotifyFallbackDeliveries, NOTIFY_FALLBACK_LEASE_MS, NOTIFY_FALLBACK_RETENTION_MS } from '../notify-fallback-delivery.js';
+import { createHash } from 'node:crypto';
+
+function deliveryKeyHash(threadId: string, turnId: string): string {
+  const part = (value: string) => {
+    const data = Buffer.from(value, 'utf8');
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(data.length);
+    return Buffer.concat([length, data]);
+  };
+  return createHash('sha256').update(Buffer.from('omx-notify-fallback-delivery-v1\0')).update(part(threadId)).update(part(turnId)).digest('hex');
+}
+
+async function withState(run: (stateDir: string) => Promise<void>): Promise<void> {
+  const root = await mkdtemp(join(tmpdir(), 'omx-notify-fallback-delivery-'));
+  try { await run(join(root, 'state')); } finally { await rm(root, { recursive: true, force: true }); }
+}
+
+describe('notify fallback delivery', () => {
+  it('allows only one simultaneous claimant to start a hook', async () => withState(async (stateDir) => {
+    let starts = 0;
+    const options = {
+      stateDir,
+      threadId: 'thread-a',
+      turnId: 'turn-a',
+      eventTimestampMs: 1_000,
+      rolloutPath: '/rollout-a.jsonl',
+      watcherMode: 'persistent' as const,
+      deadlineAtMs: 100_000,
+      now: () => 2_000,
+      spawnHook: async () => {
+        starts += 1;
+        return { spawned: true, childPid: 42, status: 0, signal: null };
+      },
+    };
+    const results = await Promise.all([deliverNotifyFallback(options), deliverNotifyFallback(options)]);
+    assert.equal(starts, 1);
+    assert.equal(results.filter((result) => result.kind === 'acquired_effect').length, 1);
+  }));
+
+  it('retries once after durable pre-spawn failure and makes attempt two terminal', async () => withState(async (stateDir) => {
+    let clock = 10_000;
+    const base = { stateDir, threadId: 'thread-b', turnId: 'turn-b', eventTimestampMs: 9_000, rolloutPath: '/rollout-b.jsonl', watcherMode: 'once' as const, deadlineAtMs: 100_000, now: () => clock };
+    const first = await deliverNotifyFallback({ ...base, spawnHook: async () => ({ spawned: false, error: new Error('ENOENT') }) });
+    assert.equal(first.kind, 'retry_eligible');
+    clock += 251;
+    const second = await deliverNotifyFallback({ ...base, spawnHook: async () => ({ spawned: false, error: new Error('ENOENT') }) });
+    assert.equal(second.kind, 'terminal_failed');
+    const third = await deliverNotifyFallback({ ...base, spawnHook: async () => { throw new Error('must not spawn attempt three'); } });
+    assert.equal(third.kind, 'terminal_failed');
+    await compactNotifyFallbackDeliveries(stateDir, Date.now() + NOTIFY_FALLBACK_RETENTION_MS + 1);
+    const afterCompaction = await deliverNotifyFallback({ ...base, spawnHook: async () => ({ spawned: true, childPid: 77, status: 0 }) });
+    assert.equal(afterCompaction.kind, 'acquired_effect');
+  }));
+
+  it('fails closed for malformed timestamps and expired authority', async () => withState(async (stateDir) => {
+    const invalid = await deliverNotifyFallback({
+      stateDir, threadId: 'thread-c', turnId: 'turn-c', eventTimestampMs: Number.NaN, rolloutPath: '/rollout-c.jsonl', watcherMode: 'once', deadlineAtMs: 1,
+      now: () => 2, spawnHook: async () => ({ spawned: true, childPid: 1, status: 0 }),
+    });
+    assert.deepEqual(invalid, { kind: 'invalid_skip', reason: 'invalid_event_timestamp' });
+    const deadline = await deliverNotifyFallback({
+      stateDir, threadId: 'thread-d', turnId: 'turn-d', eventTimestampMs: 0, rolloutPath: '/rollout-d.jsonl', watcherMode: 'once', deadlineAtMs: NOTIFY_FALLBACK_LEASE_MS,
+      now: () => NOTIFY_FALLBACK_LEASE_MS, spawnHook: async () => ({ spawned: true, childPid: 1, status: 0 }),
+    });
+    assert.deepEqual(deadline, { kind: 'deadline_skip', reason: 'authority_deadline' });
+  }));
+
+  it('isolates workspace roots and turns while retaining delivered authority', async () => {
+    const rootA = await mkdtemp(join(tmpdir(), 'omx-notify-isolation-a-'));
+    const rootB = await mkdtemp(join(tmpdir(), 'omx-notify-isolation-b-'));
+    try {
+      let starts = 0;
+      const build = (stateDir: string, turnId: string, threadId = 'thread') => ({
+        stateDir, threadId, turnId, eventTimestampMs: 1_000, rolloutPath: '/rollout.jsonl', watcherMode: 'persistent' as const,
+        deadlineAtMs: 10_000, now: () => 2_000,
+        spawnHook: async () => { starts += 1; return { spawned: true, childPid: starts, status: 0, signal: null }; },
+      });
+      assert.equal((await deliverNotifyFallback(build(join(rootA, 'state'), 'turn'))).kind, 'acquired_effect');
+      assert.equal((await deliverNotifyFallback(build(join(rootB, 'state'), 'turn'))).kind, 'acquired_effect');
+      assert.equal((await deliverNotifyFallback(build(join(rootA, 'state'), 'other-turn'))).kind, 'acquired_effect');
+      assert.equal((await deliverNotifyFallback(build(join(rootA, 'state'), 'turn', 'other-thread'))).kind, 'acquired_effect');
+      assert.equal((await deliverNotifyFallback(build(join(rootA, 'state'), 'turn'))).kind, 'terminal_delivered');
+      assert.equal(starts, 4);
+    } finally {
+      await rm(rootA, { recursive: true, force: true });
+      await rm(rootB, { recursive: true, force: true });
+    }
+  });
+
+  it('treats a spawned nonzero child as terminal ambiguity without retry', async () => withState(async (stateDir) => {
+    const options = {
+      stateDir, threadId: 'thread-e', turnId: 'turn-e', eventTimestampMs: 1_000, rolloutPath: '/rollout-e.jsonl', watcherMode: 'once' as const,
+      deadlineAtMs: 20_000, now: () => 2_000,
+      spawnHook: async () => ({ spawned: true, childPid: 55, status: 1, signal: null }),
+    };
+    assert.equal((await deliverNotifyFallback(options)).kind, 'acquired_effect');
+    assert.equal((await deliverNotifyFallback(options)).kind, 'terminal_ambiguous');
+  }));
+
+  it('rejects event timestamps more than five minutes in the future', async () => withState(async (stateDir) => {
+    const result = await deliverNotifyFallback({
+      stateDir, threadId: 'thread-f', turnId: 'turn-f', eventTimestampMs: 302_001, rolloutPath: '/rollout-f.jsonl', watcherMode: 'persistent',
+      deadlineAtMs: 400_000, now: () => 2_000, spawnHook: async () => ({ spawned: true, childPid: 99, status: 0 }),
+    });
+    assert.deepEqual(result, { kind: 'invalid_skip', reason: 'invalid_event_timestamp' });
+  }));
+
+  it('compacts terminal delivery authority after the 26 hour retention boundary', async () => withState(async (stateDir) => {
+    let starts = 0;
+    const options = {
+      stateDir, threadId: 'thread-g', turnId: 'turn-g', eventTimestampMs: Date.now(), rolloutPath: '/rollout-g.jsonl', watcherMode: 'persistent' as const,
+      deadlineAtMs: Date.now() + 100_000, now: () => Date.now(),
+      spawnHook: async () => ({ spawned: true, childPid: ++starts, status: 0, signal: null }),
+    };
+    await deliverNotifyFallback(options);
+    await compactNotifyFallbackDeliveries(stateDir, Date.now() + NOTIFY_FALLBACK_RETENTION_MS + 1);
+    assert.equal((await deliverNotifyFallback(options)).kind, 'acquired_effect');
+    assert.equal(starts, 2);
+  }));
+
+  it('does not retry a termination-unconfirmed hook outcome', async () => withState(async (stateDir) => {
+    const options = {
+      stateDir, threadId: 'thread-h', turnId: 'turn-h', eventTimestampMs: 1_000, rolloutPath: '/rollout-h.jsonl', watcherMode: 'once' as const,
+      deadlineAtMs: 20_000, now: () => 2_000,
+      spawnHook: async () => ({ spawned: true, childPid: 88, status: null, signal: null, terminationUnconfirmed: true }),
+    };
+    assert.equal((await deliverNotifyFallback(options)).kind, 'acquired_effect');
+    assert.equal((await deliverNotifyFallback(options)).kind, 'terminal_ambiguous');
+  }));
+});
+  it('fails closed when the delivery store root is a symlink', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'omx-notify-symlink-'));
+    const external = await mkdtemp(join(tmpdir(), 'omx-notify-external-'));
+    try {
+      const stateDir = join(root, 'state');
+      await mkdir(stateDir, { recursive: true });
+      await symlink(external, join(stateDir, 'notify-fallback-delivery-v1'), 'dir');
+      let starts = 0;
+      const result = await deliverNotifyFallback({
+        stateDir, threadId: 'thread-link', turnId: 'turn-link', eventTimestampMs: 1_000, rolloutPath: '/rollout-link.jsonl', watcherMode: 'once', deadlineAtMs: 10_000, now: () => 2_000,
+        spawnHook: async () => { starts += 1; return { spawned: true, childPid: 1, status: 0 }; },
+      });
+      assert.equal(result.kind, 'io_skip');
+      assert.equal(starts, 0);
+      await assert.rejects(() => compactNotifyFallbackDeliveries(stateDir, 100_000), /unsafe_directory_path/);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+      await rm(external, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects a retry authorization published before lease expiry', async () => withState(async (stateDir) => {
+    const threadId = 'thread-premature';
+    const turnId = 'turn-premature';
+    const hash = deliveryKeyHash(threadId, turnId);
+    const token = 'a'.repeat(64);
+    const keyDir = join(stateDir, 'notify-fallback-delivery-v1', hash.slice(0, 2), `${hash}.key`);
+    const attemptDir = join(keyDir, 'attempt-1');
+    await mkdir(join(attemptDir, `owner-${token}`), { recursive: true });
+    const identity = { schema_version: 1, key_hash: hash, thread_id: threadId, turn_id: turnId };
+    await writeFile(join(keyDir, 'key.json'), JSON.stringify({ ...identity, created_at_ms: 1_000 }));
+    await writeFile(join(attemptDir, `owner-${token}`, 'claim.json'), JSON.stringify({ ...identity, attempt: 1, owner_token: token, watcher_mode: 'once', claimed_at_ms: 1_000, lease_expires_at_ms: 1_000 + NOTIFY_FALLBACK_LEASE_MS, event_timestamp_ms: 1_000, rollout_path_hash: 'b'.repeat(64) }));
+    await writeFile(join(attemptDir, 'decision'), JSON.stringify({ ...identity, attempt: 1, owner_token: token, publisher_token: 'c'.repeat(64), published_at_ms: 2_000, kind: 'retry_authorized', reason: 'pre_effect_lease_expired', observed_lease_expires_at_ms: 1_000 + NOTIFY_FALLBACK_LEASE_MS }));
+    let starts = 0;
+    const result = await deliverNotifyFallback({
+      stateDir, threadId, turnId, eventTimestampMs: 1_000, rolloutPath: '/rollout-premature.jsonl', watcherMode: 'once', deadlineAtMs: 100_000, now: () => 32_000,
+      spawnHook: async () => { starts += 1; return { spawned: true, childPid: 1, status: 0 }; },
+    });
+    assert.deepEqual(result, { kind: 'invalid_skip', reason: 'invalid_retry_proof' });
+    assert.equal(starts, 0);
+  }));

package/src/scripts/__tests__/notify-state-io.test.ts

@@ -1,11 +1,15 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
 import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import {
   getScopedStatePath,
+  getScopedStatePathAtScope,
+  readScopedJsonAtScope,
+  writeScopedJsonAtScope,
   readCurrentSessionId,
   readScopedJsonIfExists,
   resolveScopedStateDir,
@@ -165,4 +169,73 @@ describe('notify-hook state I/O session authority', () => {
       await rm(wd, { recursive: true, force: true });
     }
   });
+
+  it('maps the recorded OMX owner alias to the canonical session for implicit and explicit writes', async () => {
+    const wd = await mkdtemp(join(tmpdir(), 'omx-notify-state-io-owner-alias-'));
+    const previousOmxSessionId = process.env.OMX_SESSION_ID;
+    try {
+      const stateDir = join(wd, '.omx', 'state');
+      const canonicalSessionId = 'omx-canonical';
+      const ownerSessionId = 'omx-owner';
+      await mkdir(join(stateDir, 'sessions', canonicalSessionId), { recursive: true });
+      await writeFile(
+        join(stateDir, 'session.json'),
+        JSON.stringify({
+          session_id: canonicalSessionId,
+          owner_omx_session_id: ownerSessionId,
+          cwd: wd,
+        }, null, 2),
+        'utf-8',
+      );
+      process.env.OMX_SESSION_ID = ownerSessionId;
+
+      assert.equal(await readCurrentSessionId(stateDir), canonicalSessionId);
+      assert.equal(
+        await resolveScopedStateDir(stateDir),
+        join(stateDir, 'sessions', canonicalSessionId),
+      );
+      assert.equal(
+        await resolveScopedStateDir(stateDir, ownerSessionId),
+        join(stateDir, 'sessions', canonicalSessionId),
+      );
+
+      await writeScopedJson(stateDir, 'hud-state.json', ownerSessionId, { turn_count: 12 });
+      const value = JSON.parse(
+        await readFile(join(stateDir, 'sessions', canonicalSessionId, 'hud-state.json'), 'utf-8'),
+      ) as { turn_count?: unknown };
+      assert.equal(value.turn_count, 12);
+      assert.equal(existsSync(join(stateDir, 'sessions', ownerSessionId)), false);
+    } finally {
+      if (typeof previousOmxSessionId === 'string') process.env.OMX_SESSION_ID = previousOmxSessionId;
+      else delete process.env.OMX_SESSION_ID;
+      await rm(wd, { recursive: true, force: true });
+    }
+  });
+
+  it('uses the immutable target scope without consulting a stale environment session', async () => {
+    const wd = await mkdtemp(join(tmpdir(), 'omx-notify-state-io-context-'));
+    const previousOmxSessionId = process.env.OMX_SESSION_ID;
+    try {
+      const stateDir = join(wd, '.omx', 'state');
+      const scope = {
+        targetSessionId: 'fork-existing',
+        ownerCodexSessionId: 'payload-owner',
+        allowedStorageSessionIds: ['fork-existing'],
+      };
+      await mkdir(join(stateDir, 'sessions', 'fork-existing'), { recursive: true });
+      process.env.OMX_SESSION_ID = 'stale-singleton';
+
+      assert.equal(
+        await getScopedStatePathAtScope(stateDir, 'hud-state.json', scope),
+        join(stateDir, 'sessions', 'fork-existing', 'hud-state.json'),
+      );
+      await writeScopedJsonAtScope(stateDir, 'hud-state.json', scope, { turn_count: 1 });
+      assert.deepEqual(await readScopedJsonAtScope(stateDir, 'hud-state.json', scope, null), { turn_count: 1 });
+      assert.equal(existsSync(join(stateDir, 'sessions', 'stale-singleton')), false);
+    } finally {
+      if (typeof previousOmxSessionId === 'string') process.env.OMX_SESSION_ID = previousOmxSessionId;
+      else delete process.env.OMX_SESSION_ID;
+      await rm(wd, { recursive: true, force: true });
+    }
+  });
 });

package/src/scripts/__tests__/role-intent-bootstrap-e2e-3181.test.ts

@@ -0,0 +1,215 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it } from 'node:test';
+
+import { ralplanCommand } from '../../cli/ralplan.js';
+import { readSubagentTrackingState, recordSubagentTurnForSession } from '../../subagents/tracker.js';
+import { dispatchCodexNativeHook } from '../codex-native-hook.js';
+
+async function invokeRoleIntent(cwd: string, args: string[]) {
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  const previous = process.exitCode;
+  try {
+    process.exitCode = undefined;
+    await ralplanCommand(args, { cwd: () => cwd, stdout: (l) => stdout.push(l), stderr: (l) => stderr.push(l) });
+    return { stdout, stderr, exitCode: process.exitCode };
+  } finally {
+    process.exitCode = previous;
+  }
+}
+
+describe('#3181 end-to-end fresh App turn bootstrap', () => {
+  it('SessionStart reconcile alone neither attests nor authorizes a role intent (fail-closed; positive provenance required)', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'omx-3181-e2e-'));
+    const priorEnv = { OMX_SESSION_ID: process.env.OMX_SESSION_ID, CODEX_SESSION_ID: process.env.CODEX_SESSION_ID, SESSION_ID: process.env.SESSION_ID };
+    try {
+      delete process.env.OMX_SESSION_ID;
+      delete process.env.CODEX_SESSION_ID;
+      delete process.env.SESSION_ID;
+      const nativeSessionId = 'codex-native-fresh-app';
+
+      // 1. Fresh App/outside-tmux turn start: no session.json, no tracker yet.
+      await dispatchCodexNativeHook(
+        { hook_event_name: 'SessionStart', cwd, session_id: nativeSessionId },
+        { cwd, sessionOwnerPid: process.pid },
+      );
+
+      // 2. SessionStart reconciles the canonical pointer but does NOT attest a leader
+      //    (a null transcript cannot positively classify a root vs a malformed child) and
+      //    writes no positively-provenanced tracker leader.
+      const afterStart = await readSubagentTrackingState(cwd);
+      assert.equal(afterStart.sessions[nativeSessionId]?.leader_attested_at, undefined, 'SessionStart must not attest a leader');
+
+      // 3. A role-intent write on the reconciled-pointer-only session FAILS CLOSED: the bare
+      //    session.json native_session_id is not a trusted leader anchor (an ambiguous /
+      //    malformed-child SessionStart could set it). Authorization requires positive
+      //    provenance — a PreToolUse attestation (next test) or a recorded tracker leader.
+      const res = await invokeRoleIntent(cwd, ['role-intent', 'write', '--role', 'architect', '--parent-thread', nativeSessionId, '--json']);
+      assert.equal(res.exitCode, 1);
+      assert.deepEqual(JSON.parse(res.stdout.join('\n')), { ok: false, reason: 'parent_not_active_leader' });
+
+      const finalState = await readSubagentTrackingState(cwd);
+      assert.deepEqual(finalState.pending_role_intents, []);
+    } finally {
+      if (priorEnv.OMX_SESSION_ID !== undefined) process.env.OMX_SESSION_ID = priorEnv.OMX_SESSION_ID;
+      if (priorEnv.CODEX_SESSION_ID !== undefined) process.env.CODEX_SESSION_ID = priorEnv.CODEX_SESSION_ID;
+      if (priorEnv.SESSION_ID !== undefined) process.env.SESSION_ID = priorEnv.SESSION_ID;
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it('PreToolUse (leader turn) bootstraps the pointer + attestation when SessionStart did not, so the first role-intent write succeeds', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'omx-3181-e2e-pretool-'));
+    const priorEnv = { OMX_SESSION_ID: process.env.OMX_SESSION_ID, CODEX_SESSION_ID: process.env.CODEX_SESSION_ID, SESSION_ID: process.env.SESSION_ID };
+    try {
+      delete process.env.OMX_SESSION_ID;
+      delete process.env.CODEX_SESSION_ID;
+      delete process.env.SESSION_ID;
+      const nativeSessionId = 'codex-native-exec-leader';
+
+      // Fresh exec turn where the first event reaching OMX is a leader PreToolUse (no
+      // prior SessionStart pointer). The leader turn carries thread_id == session_id.
+      await dispatchCodexNativeHook(
+        {
+          hook_event_name: 'PreToolUse',
+          cwd,
+          session_id: nativeSessionId,
+          thread_id: nativeSessionId,
+          tool_name: 'Bash',
+          tool_use_id: 'tool-exec-first',
+          tool_input: { command: 'omx ralplan role-intent write --role architect --parent-thread "$CODEX_THREAD_ID" --json' },
+        },
+        { cwd, sessionOwnerPid: process.pid },
+      );
+
+      const afterPreTool = await readSubagentTrackingState(cwd);
+      const attested = afterPreTool.sessions[nativeSessionId];
+      assert.equal(attested?.leader_thread_id, nativeSessionId);
+      assert.equal(attested?.leader_attest_source, 'native-pretooluse');
+
+      const res = await invokeRoleIntent(cwd, ['role-intent', 'write', '--role', 'architect', '--parent-thread', nativeSessionId, '--json']);
+      assert.equal(res.exitCode, undefined);
+      const receipt = JSON.parse(res.stdout.join('\n')) as { ok: boolean; intent: { role: string } };
+      assert.equal(receipt.ok, true);
+      assert.equal(receipt.intent.role, 'architect');
+      assert.equal((await readSubagentTrackingState(cwd)).pending_role_intents.length, 1);
+    } finally {
+      if (priorEnv.OMX_SESSION_ID !== undefined) process.env.OMX_SESSION_ID = priorEnv.OMX_SESSION_ID;
+      if (priorEnv.CODEX_SESSION_ID !== undefined) process.env.CODEX_SESSION_ID = priorEnv.CODEX_SESSION_ID;
+      if (priorEnv.SESSION_ID !== undefined) process.env.SESSION_ID = priorEnv.SESSION_ID;
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it('never attests a thread durably tracked as a subagent, even via a source-less leader-shaped PreToolUse', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'omx-3181-e2e-child-'));
+    const priorEnv = { OMX_SESSION_ID: process.env.OMX_SESSION_ID, CODEX_SESSION_ID: process.env.CODEX_SESSION_ID, SESSION_ID: process.env.SESSION_ID };
+    try {
+      delete process.env.OMX_SESSION_ID;
+      delete process.env.CODEX_SESSION_ID;
+      delete process.env.SESSION_ID;
+      const childThreadId = 'codex-native-child-thread';
+
+      // A child is durably recorded as a subagent (e.g. at its own SessionStart).
+      await recordSubagentTurnForSession(cwd, {
+        sessionId: 'leader-session',
+        threadId: childThreadId,
+        kind: 'subagent',
+        leaderThreadId: 'leader-session',
+        timestamp: new Date().toISOString(),
+      });
+
+      // The child then emits a source-less, untyped, leader-shaped PreToolUse
+      // (thread_id === session_id). It must NOT be promoted to leader.
+      await dispatchCodexNativeHook(
+        {
+          hook_event_name: 'PreToolUse',
+          cwd,
+          session_id: childThreadId,
+          thread_id: childThreadId,
+          tool_name: 'Bash',
+          tool_use_id: 'tool-child-selfpromote',
+          tool_input: { command: 'omx ralplan role-intent write --role architect --parent-thread "$CODEX_THREAD_ID" --json' },
+        },
+        { cwd, sessionOwnerPid: process.pid },
+      );
+
+      const state = await readSubagentTrackingState(cwd);
+      assert.equal(state.sessions[childThreadId]?.leader_attested_at, undefined, 'child thread must not be attested as leader');
+    } finally {
+      if (priorEnv.OMX_SESSION_ID !== undefined) process.env.OMX_SESSION_ID = priorEnv.OMX_SESSION_ID;
+      if (priorEnv.CODEX_SESSION_ID !== undefined) process.env.CODEX_SESSION_ID = priorEnv.CODEX_SESSION_ID;
+      if (priorEnv.SESSION_ID !== undefined) process.env.SESSION_ID = priorEnv.SESSION_ID;
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it('never bootstraps a leader from a PreToolUse carrying a malformed/blank thread_spawn carrier', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'omx-3181-e2e-malformed-spawn-'));
+    const priorEnv = { OMX_SESSION_ID: process.env.OMX_SESSION_ID, CODEX_SESSION_ID: process.env.CODEX_SESSION_ID, SESSION_ID: process.env.SESSION_ID };
+    try {
+      delete process.env.OMX_SESSION_ID;
+      delete process.env.CODEX_SESSION_ID;
+      delete process.env.SESSION_ID;
+      const childThreadId = 'codex-native-malformed-spawn';
+      // Present-but-malformed thread_spawn carrier (blank parent id) is still child
+      // provenance and must veto leader bootstrap: no pointer, no attestation.
+      await dispatchCodexNativeHook(
+        {
+          hook_event_name: 'PreToolUse',
+          cwd,
+          session_id: childThreadId,
+          thread_id: childThreadId,
+          tool_name: 'Bash',
+          tool_use_id: 'tool-malformed-spawn',
+          source: { subagent: { thread_spawn: { parent_thread_id: '' } } },
+          tool_input: { command: 'omx ralplan role-intent write --role architect --parent-thread "$CODEX_THREAD_ID" --json' },
+        },
+        { cwd, sessionOwnerPid: process.pid },
+      );
+      const state = await readSubagentTrackingState(cwd);
+      assert.equal(state.sessions[childThreadId]?.leader_attested_at, undefined, 'malformed thread_spawn must not attest as leader');
+    } finally {
+      if (priorEnv.OMX_SESSION_ID !== undefined) process.env.OMX_SESSION_ID = priorEnv.OMX_SESSION_ID;
+      if (priorEnv.CODEX_SESSION_ID !== undefined) process.env.CODEX_SESSION_ID = priorEnv.CODEX_SESSION_ID;
+      if (priorEnv.SESSION_ID !== undefined) process.env.SESSION_ID = priorEnv.SESSION_ID;
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it('never bootstraps a leader from a PreToolUse carrying an explicit non-installed agent_role', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'omx-3181-e2e-unknown-role-'));
+    const priorEnv = { OMX_SESSION_ID: process.env.OMX_SESSION_ID, CODEX_SESSION_ID: process.env.CODEX_SESSION_ID, SESSION_ID: process.env.SESSION_ID };
+    try {
+      delete process.env.OMX_SESSION_ID;
+      delete process.env.CODEX_SESSION_ID;
+      delete process.env.SESSION_ID;
+      const childThreadId = 'codex-native-unknown-role';
+      // An explicit but non-installed agent role is still role provenance and must veto
+      // leader bootstrap even though it does not resolve to an installed OMX agent.
+      await dispatchCodexNativeHook(
+        {
+          hook_event_name: 'PreToolUse',
+          cwd,
+          session_id: childThreadId,
+          thread_id: childThreadId,
+          agent_role: 'collaboration-child',
+          tool_name: 'Bash',
+          tool_use_id: 'tool-unknown-role',
+          tool_input: { command: 'omx ralplan role-intent write --role architect --parent-thread "$CODEX_THREAD_ID" --json' },
+        },
+        { cwd, sessionOwnerPid: process.pid },
+      );
+      const state = await readSubagentTrackingState(cwd);
+      assert.equal(state.sessions[childThreadId]?.leader_attested_at, undefined, 'explicit non-installed agent_role must not attest as leader');
+    } finally {
+      if (priorEnv.OMX_SESSION_ID !== undefined) process.env.OMX_SESSION_ID = priorEnv.OMX_SESSION_ID;
+      if (priorEnv.CODEX_SESSION_ID !== undefined) process.env.CODEX_SESSION_ID = priorEnv.CODEX_SESSION_ID;
+      if (priorEnv.SESSION_ID !== undefined) process.env.SESSION_ID = priorEnv.SESSION_ID;
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+});