oh-my-codex 0.20.1 → 0.20.3

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__/reasoning-artifact-contract.test.ts

@@ -0,0 +1,129 @@
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parse as parseToml } from '@iarna/toml';
+import { test } from 'node:test';
+import {
+  assertInstalledReasoningDeclarationContract,
+  assertInstalledRootReasoningHelp,
+  assertInstalledRootReasoningRejection,
+  assertInstalledTeamSkillContract,
+} from '../smoke-packed-install.js';
+
+const root = process.cwd();
+const dist = join(root, 'dist');
+
+function read(relativePath: string): string {
+  return readFileSync(join(root, relativePath), 'utf-8');
+}
+
+test('compiled reasoning artifacts preserve exact surface-specific max contracts', async () => {
+  const requiredArtifacts = [
+    'dist/config/models.js',
+    'dist/config/models.d.ts',
+    'dist/agents/definitions.js',
+    'dist/agents/definitions.d.ts',
+    'dist/agents/native-config.js',
+    'dist/agents/native-config.d.ts',
+    'dist/team/model-contract.js',
+    'dist/team/model-contract.d.ts',
+    'dist/cli/index.js',
+    'dist/cli/index.d.ts',
+    'dist/cli/omx.js',
+    'dist/cli/omx.d.ts',
+  ];
+  for (const relativePath of requiredArtifacts) {
+    assert.equal(existsSync(join(root, relativePath)), true, `missing compiled artifact: ${relativePath}`);
+  }
+
+  const modelsDeclaration = read('dist/config/models.d.ts');
+  const definitionsDeclaration = read('dist/agents/definitions.d.ts');
+  const nativeDeclaration = read('dist/agents/native-config.d.ts');
+  const teamDeclaration = read('dist/team/model-contract.d.ts');
+  assertInstalledReasoningDeclarationContract({
+    models: modelsDeclaration,
+    definitions: definitionsDeclaration,
+    nativeConfig: nativeDeclaration,
+    team: teamDeclaration,
+  });
+
+  const models = await import(pathToFileURL(join(dist, 'config/models.js')).href);
+  assert.deepEqual(models.CANONICAL_REASONING_EFFORTS, ['low', 'medium', 'high', 'xhigh']);
+  assert.deepEqual(models.AMBIGUOUS_UNSUPPORTED_REASONING_EFFORTS, ['max', 'ultra']);
+  assert.deepEqual(models.PER_AGENT_REASONING_EFFORTS, ['low', 'medium', 'high', 'xhigh', 'max']);
+  assert.deepEqual(models.ROOT_REASONING_EFFORTS, ['low', 'medium', 'high', 'xhigh']);
+  assert.deepEqual(models.ROOT_UNSUPPORTED_REASONING_EFFORTS, ['max', 'ultra']);
+  assert.equal(models.isAmbiguousUnsupportedReasoningEffort('MAX'), true);
+  assert.equal(models.isUnsupportedRootReasoningEffort('MAX'), true);
+  assert.equal(models.isUnsupportedRootReasoningEffort('ultra'), true);
+  assert.equal(models.isUnsupportedRootReasoningEffort('xhigh'), false);
+  assert.equal(models.normalizeUnsupportedRootReasoningEffort(' MAX '), 'max');
+  assert.equal(models.normalizeUnsupportedRootReasoningEffort('Ultra'), 'ultra');
+  assert.equal(models.normalizeUnsupportedRootReasoningEffort('xhigh'), undefined);
+
+  const nativeConfig = await import(pathToFileURL(join(dist, 'agents/native-config.js')).href);
+  const definitions = await import(pathToFileURL(join(dist, 'agents/definitions.js')).href);
+  const codexHome = mkdtempSync(join(tmpdir(), 'omx-artifact-max-native-'));
+  try {
+    writeFileSync(join(codexHome, '.omx-config.json'), JSON.stringify({
+      agentReasoning: { architect: ' MAX ', critic: 'ultra' },
+    }));
+    const maxToml = nativeConfig.generateAgentToml(
+      definitions.AGENT_DEFINITIONS.architect,
+      'compiled native max contract',
+      { codexHomeOverride: codexHome },
+    );
+    assert.match(maxToml, /model_reasoning_effort = "max"/);
+    assert.doesNotMatch(maxToml, /model_reasoning_effort = "xhigh"/);
+    assert.equal((parseToml(maxToml) as { model_reasoning_effort?: unknown }).model_reasoning_effort, 'max');
+
+    const fallbackToml = nativeConfig.generateAgentToml(
+      definitions.AGENT_DEFINITIONS.critic,
+      'compiled native ultra fallback contract',
+      { codexHomeOverride: codexHome },
+    );
+    assert.match(fallbackToml, /model_reasoning_effort = "high"/);
+    assert.doesNotMatch(fallbackToml, /model_reasoning_effort = "ultra"/);
+  } finally {
+    rmSync(codexHome, { recursive: true, force: true });
+  }
+
+  const team = await import(pathToFileURL(join(dist, 'team/model-contract.js')).href);
+  const maxArgs = team.resolveTeamWorkerLaunchArgs({ preferredReasoning: 'max' });
+  assert.deepEqual(maxArgs, ['-c', 'model_reasoning_effort="max"']);
+  assert.equal(maxArgs.includes('model_reasoning_effort="xhigh"'), false);
+  const opaqueUltra = team.resolveTeamWorkerLaunchDiagnostics({
+    existingRaw: '-c model_reasoning_effort="ultra"',
+    preferredReasoning: 'max',
+  });
+  assert.equal(opaqueUltra.reasoningSource, 'explicit');
+  assert.equal(opaqueUltra.actualReasoning, undefined);
+
+  const canonicalSkill = readFileSync(join(root, 'skills/team/SKILL.md'));
+  const pluginSkill = readFileSync(join(root, 'plugins/oh-my-codex/skills/team/SKILL.md'));
+  assertInstalledTeamSkillContract(canonicalSkill, pluginSkill);
+});
+
+test('compiled root reasoning keeps four-value help and rejects max/ultra without mutation', () => {
+  const omxPath = join(dist, 'cli/omx.js');
+  const codexHome = mkdtempSync(join(tmpdir(), 'omx-artifact-root-reasoning-'));
+  try {
+    const env = { ...process.env, CODEX_HOME: codexHome };
+    const configPath = join(codexHome, 'config.toml');
+    const help = spawnSync(process.execPath, [omxPath, 'reasoning'], { encoding: 'utf-8', env });
+    assert.equal(help.status, 0, help.stderr);
+    assertInstalledRootReasoningHelp(help.stdout);
+    const max = spawnSync(process.execPath, [omxPath, 'reasoning', 'max'], { encoding: 'utf-8', env });
+    assertInstalledRootReasoningRejection('max', max, undefined, existsSync(configPath) ? readFileSync(configPath, 'utf-8') : undefined);
+
+    const originalConfig = 'model = "preserve-root-config"\n';
+    writeFileSync(configPath, originalConfig);
+    const ultra = spawnSync(process.execPath, [omxPath, 'reasoning', 'ultra'], { encoding: 'utf-8', env });
+    assertInstalledRootReasoningRejection('ultra', ultra, originalConfig, readFileSync(configPath, 'utf-8'));
+  } finally {
+    rmSync(codexHome, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,78 @@
+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 { describe, it } from 'node:test';
+
+import { recordSubagentTurnForSession, readSubagentTrackingState } from '../../subagents/tracker.js';
+import { dispatchCodexNativeHook } from '../codex-native-hook.js';
+
+describe('#3194 role-intent native-hook e2e', () => {
+  it('does not treat legacy thread_id as leader authority and preserves a child record', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'omx-3194-'));
+    try {
+      await recordSubagentTurnForSession(cwd, {
+        sessionId: 'synthetic-leader-session', threadId: 'synthetic-child-thread', kind: 'subagent',
+        leaderThreadId: 'synthetic-leader-thread', timestamp: new Date(0).toISOString(),
+      });
+      const before = await readSubagentTrackingState(cwd);
+      const result = await dispatchCodexNativeHook({
+        hook_event_name: 'PreToolUse', cwd, session_id: 'synthetic-child-thread', thread_id: 'synthetic-child-thread',
+        tool_name: 'Bash', tool_use_id: 'synthetic-tool-use', tool_input: { command: 'omx ralplan role-intent write --role architect --parent-thread "$CODEX_THREAD_ID" --json' },
+      }, { cwd, sessionOwnerPid: process.pid });
+      assert.deepEqual(result.outputJson, {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse', permissionDecision: 'deny',
+          permissionDecisionReason: 'unsupported_documented_leader_proof: Codex 0.144.5 hooks do not expose documented root identity required for adapted Ralplan.',
+        },
+      });
+      assert.deepEqual(await readSubagentTrackingState(cwd), before);
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it('does not create session state for a fresh documented payload without thread_id', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'omx-3194-'));
+    try {
+      const result = await dispatchCodexNativeHook({
+        hook_event_name: 'PreToolUse', cwd, session_id: 'synthetic-session', tool_name: 'Bash', tool_use_id: 'synthetic-tool-use',
+        tool_input: { command: 'omx ralplan role-intent write --role architect --parent-thread "$CODEX_THREAD_ID" --json' },
+      }, { cwd, sessionOwnerPid: process.pid });
+      assert.deepEqual(result.outputJson, {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse', permissionDecision: 'deny',
+          permissionDecisionReason: 'unsupported_documented_leader_proof: Codex 0.144.5 hooks do not expose documented root identity required for adapted Ralplan.',
+        },
+      });
+      assert.equal(existsSync(join(cwd, '.omx', 'state')), false);
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it('does not mutate a foreign or stale pointer before denying the documented payload', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'omx-3194-'));
+    try {
+      const stateDir = join(cwd, '.omx', 'state');
+      const pointerPath = join(stateDir, 'session.json');
+      const pointer = '{"session_id":"synthetic-foreign","native_session_id":"synthetic-foreign","started_at":"1970-01-01T00:00:00.000Z"}\n';
+      await mkdir(stateDir, { recursive: true });
+      await writeFile(pointerPath, pointer);
+      const result = await dispatchCodexNativeHook({
+        hook_event_name: 'PreToolUse', cwd, session_id: 'synthetic-current', tool_name: 'Bash', tool_use_id: 'synthetic-tool-use',
+        tool_input: { command: 'omx ralplan role-intent write --role architect --parent-thread "$CODEX_THREAD_ID" --json' },
+      }, { cwd, sessionOwnerPid: process.pid });
+      assert.deepEqual(result.outputJson, {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse', permissionDecision: 'deny',
+          permissionDecisionReason: 'unsupported_documented_leader_proof: Codex 0.144.5 hooks do not expose documented root identity required for adapted Ralplan.',
+        },
+      });
+      assert.equal(await readFile(pointerPath, 'utf8'), pointer);
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+});

package/src/scripts/__tests__/role-intent-durable-recovery-3181.test.ts

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { describe, it } from 'node:test';
+
+import {
+  bindPendingRoleIntentUnderLock,
+  readSubagentTrackingState,
+  readSubagentTrackingStateStrict,
+  recordPendingRoleIntent,
+  subagentTrackingPath,
+} from '../../subagents/tracker.js';
+
+const ARCHITECT_TOKEN = 'abcdef0123456789abcdef0123456789';
+const CRITIC_TOKEN = '00112233445566778899aabbccddeeff';
+
+async function withCwd(fn: (cwd: string) => Promise<void>): Promise<void> {
+  const cwd = await mkdtemp(join(tmpdir(), 'omx-3194-'));
+  try { await fn(cwd); } finally { await rm(cwd, { recursive: true, force: true }); }
+}
+
+describe('#3194 pending role-intent durability', () => {
+  it('keeps Architect before Critic as distinct single-flight intents and preserves binding integrity', async () => {
+    await withCwd(async (cwd) => {
+      const architect = recordPendingRoleIntent(cwd, {
+        role: 'architect', sessionId: 'synthetic-session', parentThreadId: 'synthetic-parent', correlationToken: ARCHITECT_TOKEN, nowMs: 0,
+      });
+      assert.equal(architect.ok, true);
+      const critic = recordPendingRoleIntent(cwd, {
+        role: 'critic', sessionId: 'synthetic-session', parentThreadId: 'synthetic-parent', correlationToken: CRITIC_TOKEN, nowMs: 0,
+      });
+      assert.deepEqual(critic, { ok: false, reason: 'single_flight_conflict' });
+      const binding = bindPendingRoleIntentUnderLock(cwd, {
+        sessionId: 'synthetic-session', parentThreadId: 'synthetic-parent', correlationToken: ARCHITECT_TOKEN, nowMs: 1,
+      }, (state) => state);
+      assert.equal(binding?.role, 'architect');
+      assert.equal(binding?.alreadyBound, false);
+      const retry = bindPendingRoleIntentUnderLock(cwd, {
+        sessionId: 'synthetic-session', parentThreadId: 'synthetic-parent', correlationToken: ARCHITECT_TOKEN, nowMs: 2,
+      }, () => { throw new Error('an existing binding must not invoke the callback'); });
+      assert.equal(retry?.alreadyBound, true);
+      const state = await readSubagentTrackingState(cwd);
+      assert.equal(state.pending_role_intents.length, 1);
+      assert.equal(state.pending_role_intents[0]?.binding_state, 'bound');
+      assert.equal(state.pending_role_intents[0]?.correlation_token, ARCHITECT_TOKEN);
+    });
+  });
+
+  it('strictly rejects corrupt durable tracker bytes without mutation', async () => {
+    await withCwd(async (cwd) => {
+      const path = subagentTrackingPath(cwd);
+      const corrupt = '{ synthetic corrupt tracker';
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, corrupt);
+      assert.deepEqual(await readSubagentTrackingStateStrict(cwd), { ok: false });
+      assert.equal(await readFile(path, 'utf8'), corrupt);
+    });
+  });
+});