oh-my-codex 0.18.1 → 0.18.2

package/src/scripts/codex-native-hook.ts

@@ -3,8 +3,9 @@ import { closeSync, existsSync, openSync, readFileSync, readSync } from "fs";
 import { appendFile, mkdir, readFile, readdir, stat, writeFile } from "fs/promises";
 import { extname, join, relative, resolve } from "path";
 import { pathToFileURL } from "url";
-import { readModeState, readModeStateForActiveDecision, readModeStateForSession, updateModeState } from "../modes/base.js";
+import { readModeStateForActiveDecision, readModeStateForSession, updateModeState } from "../modes/base.js";
 import {
+  SKILL_ACTIVE_STATE_FILE,
   extractSessionIdFromInitializedStatePath,
   getSkillActiveStatePathsForStateDir,
   listActiveSkills,
@@ -14,6 +15,7 @@ import {
 } from "../state/skill-active.js";
 import {
   readSubagentSessionSummary,
+  readSubagentTrackingState,
   recordSubagentTurnForSession,
 } from "../subagents/tracker.js";
 import { resolveCanonicalTeamStateRoot, resolveWorkerNotifyTeamStateRootPath } from "../team/state-root.js";
@@ -297,18 +299,32 @@ async function isNativeSubagentHook(
   nativeSessionId: string,
   threadId: string,
 ): Promise<boolean> {
-  const sessionId = canonicalSessionId.trim();
-  if (!sessionId) return false;
-
-  const summary = await readSubagentSessionSummary(cwd, sessionId).catch(() => null);
-  if (!summary) return false;
-
   const candidateIds = [nativeSessionId, threadId]
     .map((value) => value.trim())
     .filter(Boolean);
   if (candidateIds.length === 0) return false;
 
-  return candidateIds.some((id) => summary.allSubagentThreadIds.includes(id));
+  const sessionId = canonicalSessionId.trim();
+  if (sessionId) {
+    const summary = await readSubagentSessionSummary(cwd, sessionId).catch(() => null);
+    if (summary && candidateIds.some((id) => summary.allSubagentThreadIds.includes(id))) {
+      return true;
+    }
+  }
+
+  // Native Codex resume can report the child native session as the canonical
+  // session id before OMX reconciles it back to the owning session.  In that
+  // window the per-session summary lookup above misses the child and a
+  // subagent UserPromptSubmit can accidentally activate workflow keywords from
+  // quoted review context.  Fall back to the global tracking index so any known
+  // subagent thread is treated as subagent-scoped, regardless of the current
+  // hook payload's session-id mapping.
+  const trackingState = await readSubagentTrackingState(cwd).catch(() => null);
+  if (!trackingState) return false;
+
+  return Object.values(trackingState.sessions).some((session) => (
+    candidateIds.some((id) => session.threads[id]?.kind === "subagent")
+  ));
 }
 
 function shouldSuppressSubagentLifecycleHookDispatch(): boolean {
@@ -1683,6 +1699,17 @@ function buildSkillStateCliInstruction(mode: string, statePath: string): string
   return `skill: ${mode} activated and initial state initialized at ${statePath}; use CLI-first state updates via \`omx state write/read/clear --input '<json>' --json\`; use omx_state MCP only when explicit MCP compatibility is enabled.`;
 }
 
+function buildAutopilotPromptActivationNote(skillState?: SkillActiveState | null): string | null {
+  if (skillState?.initialized_mode !== "autopilot") return null;
+  return [
+    "Autopilot protocol: the durable default chain is $deep-interview -> $ralplan -> $ultragoal (+ $team if needed) -> $code-review -> $ultraqa (deep-interview -> ralplan -> ultragoal -> code-review -> ultraqa).",
+    "Start/resume at current_phase=deep-interview unless the task is clear and bounded; if deep-interview is intentionally skipped, persist and state an explicit deep_interview_gate.skip_reason before moving to ralplan.",
+    "The ralplan phase is not complete until Planner output has been reviewed sequentially by Architect and then Critic; do not hand off to Ultragoal or implementation until the ralplan state/artifact records both ralplan_architect_review and ralplan_critic_review with approval or an explicit blocker.",
+    "Do not silently fall back to ordinary $plan/ralplan-only handling; keep autopilot-state.json, skill-active-state.json, HUD/statusline, and Codex goal-mode handoff guidance visible while the workflow is active.",
+    "When Codex goal tools are available, call get_goal/create_goal only from the active thread handoff and treat the active goal as the completion contract until code-review and ultraqa are clean.",
+  ].join(" ");
+}
+
 function buildAdditionalContextMessage(
   prompt: string,
   skillState?: SkillActiveState | null,
@@ -1716,6 +1743,7 @@ function buildAdditionalContextMessage(
   const ultragoalPromptActivationNote = match.skill === "ultragoal"
     ? "Ultragoal protocol: use `omx ultragoal create-goals` / `complete-goals` / `checkpoint` for `.omx/ultragoal` artifacts, then use Codex goal model tools only from the active agent handoff (`get_goal`, `create_goal`, `update_goal`) and never overwrite a different active Codex goal. Ultragoal does not call `/goal clear`; for multiple sequential ultragoal runs in one Codex session/thread, manually clear the completed Codex goal in the UI before creating the next aggregate goal."
     : null;
+  const autopilotPromptActivationNote = buildAutopilotPromptActivationNote(skillState);
   const combinedTransitionMessage = (() => {
     if (!skillState?.transition_message) return null;
     if (matches.length <= 1 || activeSkills.length <= 1) return skillState.transition_message;
@@ -1743,6 +1771,7 @@ function buildAdditionalContextMessage(
         : null,
       promptPriorityMessage,
       ultragoalPromptActivationNote,
+      autopilotPromptActivationNote,
       skillState.initialized_mode && skillState.initialized_state_path
         ? buildSkillStateCliInstruction(skillState.initialized_mode, skillState.initialized_state_path)
         : null,
@@ -1769,6 +1798,7 @@ function buildAdditionalContextMessage(
       deepInterviewPromptActivationNote,
       ultraworkPromptActivationNote,
       ultragoalPromptActivationNote,
+      autopilotPromptActivationNote,
       buildTeamRuntimeInstruction(cwd, payload),
       buildTeamHelpInstruction(cwd, payload),
       "Follow AGENTS.md routing and preserve workflow transition and planning-safety rules.",
@@ -1787,12 +1817,13 @@ function buildAdditionalContextMessage(
       deepInterviewPromptActivationNote,
       ultraworkPromptActivationNote,
       ultragoalPromptActivationNote,
+      autopilotPromptActivationNote,
       ralphPromptActivationNote,
       "Follow AGENTS.md routing and preserve workflow transition and planning-safety rules.",
     ].join(" ");
   }
 
-  return [detectedKeywordMessage, promptPriorityMessage, ultragoalPromptActivationNote, "Follow AGENTS.md routing and preserve workflow transition and planning-safety rules."].filter(Boolean).join(" ");
+  return [detectedKeywordMessage, promptPriorityMessage, ultragoalPromptActivationNote, autopilotPromptActivationNote, "Follow AGENTS.md routing and preserve workflow transition and planning-safety rules."].filter(Boolean).join(" ");
 }
 
 function parseTeamWorkerEnv(rawValue: string): { teamName: string; workerName: string } | null {
@@ -2041,6 +2072,7 @@ async function findActiveGoalWorkflowReconciliationRequirement(cwd: string): Pro
         `If get_goal returns a completed task-scoped objective for the same aggregate ultragoal plan, checkpoint ${goalId} with evidence naming ${goalId} plus .omx/ultragoal/goals.json or ledger.jsonl and pass final quality-gate JSON; OMX will reconcile the completed planned scope without mutating Codex goal state.`,
         `If get_goal instead returns a different completed legacy objective and complete checkpointing fails, do not repeat --status complete in this thread.`,
         `Record the non-terminal blocker with: omx ultragoal checkpoint --goal-id ${goalId} --status blocked --codex-goal-json '<different completed get_goal JSON or path>' --evidence '<completed legacy Codex goal blocks create_goal in this thread>'.`,
+        `If get_goal itself is unavailable with a Codex DB/schema/context error such as "no such table: thread_goals", record an auditable safe-recovery blocker instead: omx ultragoal checkpoint --goal-id ${goalId} --status blocked --codex-goal-json '<unavailable get_goal error JSON or path>' --evidence '<get_goal unavailable due to Codex DB/schema/context error; safe recovery requires a working Codex goal context>'.`,
         "Then continue only from a Codex goal context with no active/completed conflicting goal in the same repo/worktree and create the intended goal there.",
       ].join(" "),
     };
@@ -2127,36 +2159,60 @@ async function buildGoalWorkflowReconciliationStopOutput(
   };
 }
 
+interface TeamModeStateForStop {
+  state: Record<string, unknown>;
+  scope: "session" | "root";
+}
+
+function teamStateMatchesThreadForStop(
+  state: Record<string, unknown>,
+  threadId?: string,
+  options: { requireOwnerThread?: boolean } = {},
+): boolean {
+  const normalizedThreadId = safeString(threadId).trim();
+  if (!normalizedThreadId) return true;
+
+  const ownerThreadId = safeString(state.owner_codex_thread_id ?? state.thread_id).trim();
+  if (!ownerThreadId) return options.requireOwnerThread !== true;
+  return ownerThreadId === normalizedThreadId;
+}
+
 async function readTeamModeStateForStop(
   cwd: string,
   stateDir: string,
   sessionId?: string,
-): Promise<Record<string, unknown> | null> {
+  threadId?: string,
+): Promise<TeamModeStateForStop | null> {
   const normalizedSessionId = safeString(sessionId).trim();
-  if (!normalizedSessionId) {
-    return await readModeState("team", cwd);
-  }
+  if (!normalizedSessionId) return null;
 
   const scopedState = await readStopSessionPinnedState("team-state.json", cwd, normalizedSessionId, stateDir);
-  if (scopedState) return scopedState;
+  if (scopedState) {
+    return teamStateMatchesThreadForStop(scopedState, threadId)
+      ? { state: scopedState, scope: "session" }
+      : null;
+  }
 
   const rootState = await readJsonIfExists(join(stateDir, "team-state.json"));
   if (rootState?.active !== true) return null;
 
+  const teamName = safeString(rootState.team_name).trim();
+  if (!teamName) return null;
+
   const ownerSessionId = safeString(rootState.session_id).trim();
-  if (ownerSessionId && ownerSessionId !== normalizedSessionId) {
-    return null;
-  }
+  if (!ownerSessionId || ownerSessionId !== normalizedSessionId) return null;
+  if (!teamStateMatchesThreadForStop(rootState, threadId, { requireOwnerThread: true })) return null;
 
-  return rootState;
+  return { state: rootState, scope: "root" };
 }
 
-async function buildTeamStopOutput(cwd: string, sessionId?: string): Promise<Record<string, unknown> | null> {
+async function buildTeamStopOutput(cwd: string, sessionId?: string, threadId?: string): Promise<Record<string, unknown> | null> {
   if (await readCanonicalTerminalRunStateForStop(cwd, sessionId, "team")) {
     return null;
   }
-  const teamState = await readTeamModeStateForStop(cwd, getBaseStateDir(cwd), sessionId);
-  if (teamState?.active !== true) return null;
+  const teamStateForStop = await readTeamModeStateForStop(cwd, getBaseStateDir(cwd), sessionId, threadId);
+  if (!teamStateForStop || teamStateForStop.state.active !== true) return null;
+  const teamState = teamStateForStop.state;
   const teamName = safeString(teamState.team_name).trim();
   if (teamName) {
     const canonicalTeamDir = join(resolveCanonicalTeamStateRoot(cwd), "team", teamName);
@@ -2165,7 +2221,9 @@ async function buildTeamStopOutput(cwd: string, sessionId?: string): Promise<Rec
     }
   }
   const coarsePhase = teamState.current_phase;
-  const canonicalPhase = teamName ? (await readTeamPhase(teamName, cwd))?.current_phase ?? coarsePhase : coarsePhase;
+  const canonicalPhaseState = teamName ? await readTeamPhase(teamName, cwd) : null;
+  if (teamStateForStop.scope === "root" && !canonicalPhaseState) return null;
+  const canonicalPhase = canonicalPhaseState?.current_phase ?? coarsePhase;
   if (!isNonTerminalPhase(canonicalPhase)) return null;
   return buildTeamStopOutputForPhase(teamName, formatPhase(canonicalPhase));
 }
@@ -2272,6 +2330,151 @@ async function readStopSessionPinnedState(
   return readJsonIfExists(statePath);
 }
 
+const DEEP_INTERVIEW_ALLOWED_WRITE_PREFIXES = [
+  ".omx/context",
+  ".omx/interviews",
+  ".omx/specs",
+  ".omx/state",
+] as const;
+
+const DEEP_INTERVIEW_IMPLEMENTATION_TOOL_NAMES = new Set([
+  "Write",
+  "Edit",
+  "MultiEdit",
+  "apply_patch",
+  "ApplyPatch",
+]);
+
+function isActiveDeepInterviewPhase(state: Record<string, unknown> | null): boolean {
+  if (!state || state.active !== true) return false;
+  const mode = safeString(state.mode).trim();
+  if (mode && mode !== "deep-interview") return false;
+  const phase = safeString(state.current_phase ?? state.currentPhase).trim().toLowerCase();
+  if (phase && (TERMINAL_MODE_PHASES.has(phase) || phase === "completing")) return false;
+  return true;
+}
+
+function isAllowedDeepInterviewArtifactPath(cwd: string, rawPath: string): boolean {
+  const trimmed = rawPath.trim().replace(/^['"]|['"]$/g, "");
+  if (!trimmed || trimmed.includes("\0")) return false;
+  let relativePath: string;
+  try {
+    const absolute = resolve(cwd, trimmed);
+    relativePath = relative(cwd, absolute).replace(/\\/g, "/");
+  } catch {
+    return false;
+  }
+  if (!relativePath || relativePath.startsWith("..") || relativePath.startsWith("/")) return false;
+  return DEEP_INTERVIEW_ALLOWED_WRITE_PREFIXES.some((prefix) => (
+    relativePath === prefix || relativePath.startsWith(`${prefix}/`)
+  ));
+}
+
+function readPreToolUseCommand(payload: CodexHookPayload): string {
+  const toolInput = safeObject(payload.tool_input);
+  return safeString(toolInput.command).trim();
+}
+
+function readPreToolUsePathCandidates(payload: CodexHookPayload): string[] {
+  const input = safeObject(payload.tool_input);
+  const candidates = [
+    input.file_path,
+    input.filePath,
+    input.path,
+    input.target_path,
+    input.targetPath,
+  ];
+  return candidates.map((candidate) => safeString(candidate).trim()).filter(Boolean);
+}
+
+function commandHasDeepInterviewWriteIntent(command: string): boolean {
+  return /\bapply_patch\b/.test(command)
+    || /(?:^|[;&|]\s*)(?:cat|printf|echo)\b[\s\S]{0,240}>\s*[^\s&|;]+/.test(command)
+    || /\btee\s+(?:-a\s+)?[^\s&|;]+/.test(command)
+    || /\bsed\s+(?:[^\n;&|]*\s)?-i(?:\b|['"])/.test(command)
+    || /\b(?:python3?|node|perl|ruby)\b[\s\S]{0,260}\b(?:writeFileSync|writeFile|write_text|open\([^)]*["']w|File\.write|Path\()/.test(command)
+    || /\b(?:git\s+(?:checkout|switch|restore|reset|apply|am|merge|rebase)|npm\s+(?:install|i|ci)|pnpm\s+(?:install|i)|yarn\s+(?:install|add))\b/.test(command);
+}
+
+function extractDeepInterviewCommandWriteTargets(command: string): string[] {
+  const targets: string[] = [];
+  for (const match of command.matchAll(/(?:^|[^>])>{1,2}\s*(["']?)([^\s&|;<>]+)\1/g)) {
+    const candidate = safeString(match[2]).trim();
+    if (candidate) targets.push(candidate);
+  }
+  for (const match of command.matchAll(/\btee\s+(?:-a\s+)?(["']?)([^\s&|;<>]+)\1/g)) {
+    const candidate = safeString(match[2]).trim();
+    if (candidate) targets.push(candidate);
+  }
+  return targets;
+}
+
+function isAllowedDeepInterviewBashWrite(cwd: string, command: string): boolean {
+  if (!commandHasDeepInterviewWriteIntent(command)) return true;
+  if (/\bomx\s+(?:state\s+(?:write|read|clear)|question)\b/.test(command)) return true;
+  const targets = extractDeepInterviewCommandWriteTargets(command);
+  return targets.length > 0 && targets.every((target) => isAllowedDeepInterviewArtifactPath(cwd, target));
+}
+
+async function readActiveDeepInterviewStateForPreToolUse(
+  cwd: string,
+  stateDir: string,
+  sessionId: string,
+  threadId: string,
+): Promise<Record<string, unknown> | null> {
+  const modeState = sessionId
+    ? await readStopSessionPinnedState("deep-interview-state.json", cwd, sessionId, stateDir)
+    : await readJsonIfExists(join(stateDir, "deep-interview-state.json"));
+  if (!isActiveDeepInterviewPhase(modeState) || !modeState) return null;
+  if (!modeStateMatchesSkillStopContext(modeState, cwd, sessionId)) return null;
+
+  const canonicalState = sessionId
+    ? await readVisibleSkillActiveStateForStateDir(stateDir, sessionId)
+    : await readSkillActiveState(join(stateDir, SKILL_ACTIVE_STATE_FILE));
+  if (!canonicalState) return modeState;
+  const hasActiveDeepInterviewSkill = listActiveSkills(canonicalState).some((entry) => (
+    entry.skill === "deep-interview"
+    && matchesSkillStopContext(entry, canonicalState, sessionId, threadId)
+  ));
+  return hasActiveDeepInterviewSkill ? modeState : null;
+}
+
+async function buildDeepInterviewPreToolUseBoundaryOutput(
+  payload: CodexHookPayload,
+  cwd: string,
+  stateDir: string,
+): Promise<Record<string, unknown> | null> {
+  const sessionId = readPayloadSessionId(payload);
+  const threadId = readPayloadThreadId(payload);
+  const activeState = await readActiveDeepInterviewStateForPreToolUse(cwd, stateDir, sessionId, threadId);
+  if (!activeState) return null;
+
+  const toolName = safeString(payload.tool_name).trim();
+  const command = readPreToolUseCommand(payload);
+  const pathCandidates = readPreToolUsePathCandidates(payload);
+  let blocked = false;
+
+  if (toolName === "Bash") {
+    blocked = !isAllowedDeepInterviewBashWrite(cwd, command);
+  } else if (DEEP_INTERVIEW_IMPLEMENTATION_TOOL_NAMES.has(toolName)) {
+    blocked = pathCandidates.length === 0
+      || !pathCandidates.every((candidate) => isAllowedDeepInterviewArtifactPath(cwd, candidate));
+  }
+
+  if (!blocked) return null;
+
+  const phase = formatPhase(activeState.current_phase ?? activeState.currentPhase, "planning");
+  return {
+    decision: "block",
+    reason: `Deep-interview is active (phase: ${phase}); implementation/write tools are blocked until an explicit handoff workflow is activated.`,
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      additionalContext:
+        "Deep-interview is requirements/spec mode. Treat detailed user answers as interview/spec material, not implicit implementation authorization. You may write only deep-interview artifacts under `.omx/context/`, `.omx/interviews/`, `.omx/specs/`, or required `.omx/state/` files. To implement, first ask for or process an explicit transition such as `$ralplan`, `$autopilot`, `$ralph`, `$team`, or `$ultragoal`.",
+    },
+  };
+}
+
 function matchesSkillStopContext(
   entry: { session_id?: string; thread_id?: string },
   state: { session_id?: string; thread_id?: string },
@@ -2909,6 +3112,7 @@ async function returnPersistentStopBlock(
 async function findCanonicalActiveTeamForSession(
   cwd: string,
   sessionId: string,
+  threadId?: string,
 ): Promise<{ teamName: string; phase: string } | null> {
   if (!sessionId.trim()) return null;
   const teamsRoot = join(resolveCanonicalTeamStateRoot(cwd), "team");
@@ -2927,6 +3131,7 @@ async function findCanonicalActiveTeamForSession(
     if (!manifest || !phaseState) continue;
     const ownerSessionId = (manifest.leader?.session_id ?? "").trim();
     if (ownerSessionId && ownerSessionId !== sessionId.trim()) continue;
+    if (!teamStateMatchesThreadForStop(manifest.leader as unknown as Record<string, unknown>, threadId)) continue;
     if (!isNonTerminalPhase(phaseState.current_phase)) continue;
 
     return {
@@ -2942,12 +3147,13 @@ async function resolveActiveTeamNameForStop(
   cwd: string,
   stateDir: string,
   sessionId: string,
+  threadId?: string,
 ): Promise<string> {
-  const directState = await readTeamModeStateForStop(cwd, stateDir, sessionId);
-  const directTeamName = safeString(directState?.team_name).trim();
-  if (directState?.active === true && directTeamName) return directTeamName;
+  const directState = await readTeamModeStateForStop(cwd, stateDir, sessionId, threadId);
+  const directTeamName = safeString(directState?.state.team_name).trim();
+  if (directState?.state.active === true && directTeamName) return directTeamName;
 
-  const canonicalTeam = await findCanonicalActiveTeamForSession(cwd, sessionId);
+  const canonicalTeam = await findCanonicalActiveTeamForSession(cwd, sessionId, threadId);
   return canonicalTeam?.teamName ?? "";
 }
 
@@ -2959,7 +3165,7 @@ async function maybeBuildReleaseReadinessFinalizeStopOutput(
 ): Promise<{ matched: boolean; output: Record<string, unknown> | null }> {
   if (!sessionId) return { matched: false, output: null };
 
-  const teamName = await resolveActiveTeamNameForStop(cwd, stateDir, sessionId);
+  const teamName = await resolveActiveTeamNameForStop(cwd, stateDir, sessionId, readPayloadThreadId(payload));
   if (!teamName) return { matched: false, output: null };
 
   const explicitReleaseReadinessContext =
@@ -3288,7 +3494,7 @@ async function buildStopHookOutput(
     );
     if (releaseReadinessFinalizeResult.matched) return releaseReadinessFinalizeResult.output;
 
-    const teamOutput = await buildTeamStopOutput(cwd, canonicalSessionId);
+    const teamOutput = await buildTeamStopOutput(cwd, canonicalSessionId, threadId);
     if (teamOutput) {
       return await returnPersistentStopBlock(
         payload,
@@ -3320,7 +3526,7 @@ async function buildStopHookOutput(
 
       const canonicalTeam = await readCanonicalTerminalRunStateForStop(cwd, canonicalSessionId, "team")
         ? null
-        : await findCanonicalActiveTeamForSession(cwd, canonicalSessionId);
+        : await findCanonicalActiveTeamForSession(cwd, canonicalSessionId, threadId);
       if (canonicalTeam) {
         const canonicalTeamOutput = buildTeamStopOutputForPhase(
           canonicalTeam.teamName,
@@ -3710,7 +3916,8 @@ export async function dispatchCodexNativeHook(
       };
     }
   } else if (hookEventName === "PreToolUse") {
-    outputJson = buildNativePreToolUseOutput(payload);
+    outputJson = await buildDeepInterviewPreToolUseBoundaryOutput(payload, cwd, stateDir)
+      ?? buildNativePreToolUseOutput(payload);
   } else if (hookEventName === "PostToolUse") {
     if (detectMcpTransportFailure(payload)) {
       await markTeamTransportFailure(cwd, payload);

package/src/scripts/notify-dispatcher.ts

@@ -7,6 +7,9 @@
 
 import { readFile } from "fs/promises";
 import { spawnSync } from "child_process";
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { tmpdir } from "os";
 
 interface NotifyDispatcherMetadata {
 	managedBy?: string;
@@ -16,6 +19,195 @@ interface NotifyDispatcherMetadata {
 	dispatcherNotify?: string[];
 }
 
+const DISPATCH_LOCK_STALE_MS = 45_000;
+// Codex Desktop can replay a backlog of turn-ended callbacks well after the UI
+// window has gone away. Keep the default same-turn coalescing window longer
+// than a heavily loaded notification hook invocation so sequential queued
+// callbacks from one thread do not slip through merely because the first
+// dispatch was slow. Payloads with different thread/session identity retain
+// independent notification cadence.
+const DEFAULT_TURN_DISPATCH_MIN_INTERVAL_MS = 10_000;
+const DEFAULT_STALE_EVENT_AGE_MS = 5 * 60_000;
+
+interface DispatchGuard {
+	ok: boolean;
+	release?: () => void;
+}
+
+interface DispatchGuardState {
+	lastDispatchAt?: unknown;
+	lastDispatchByIdentity?: Record<string, unknown>;
+}
+
+function parseNonNegativeEnvMs(name: string, fallback: number): number {
+	const raw = process.env[name];
+	if (typeof raw !== "string" || raw.trim() === "") return fallback;
+	const parsed = Number(raw);
+	return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function parsePayloadObject(payloadArg: string): Record<string, unknown> | null {
+	try {
+		const parsed = JSON.parse(payloadArg) as unknown;
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+			? (parsed as Record<string, unknown>)
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+function isTurnEndedPayload(payload: Record<string, unknown> | null): boolean {
+	if (!payload) return false;
+	const type = String(payload.type ?? payload.event ?? payload.hook_event_name ?? "")
+		.trim()
+		.toLowerCase();
+	return type === ""
+		|| type === "agent-turn-complete"
+		|| type === "turn-complete"
+		|| type === "turn-ended";
+}
+
+function readPayloadTimestampMs(payload: Record<string, unknown>): number | null {
+	for (const key of ["timestamp", "created_at", "createdAt", "event_time", "eventTime", "time"]) {
+		const value = payload[key];
+		if (typeof value === "number" && Number.isFinite(value)) {
+			return value > 1_000_000_000_000 ? value : value * 1000;
+		}
+		if (typeof value === "string" && value.trim()) {
+			const parsed = Date.parse(value);
+			if (Number.isFinite(parsed)) return parsed;
+		}
+	}
+	return null;
+}
+
+function readPayloadIdentity(payload: Record<string, unknown> | null): string {
+	if (!payload) return "global";
+	for (const key of [
+		"thread_id",
+		"threadId",
+		"conversation_id",
+		"conversationId",
+		"session_id",
+		"sessionId",
+	]) {
+		const value = payload[key];
+		if (typeof value === "string" && value.trim()) {
+			return `${key}:${value.trim()}`;
+		}
+	}
+	return "global";
+}
+
+function dispatchGuardDir(metadataPath: string): string {
+	if (metadataPath) return dirname(metadataPath);
+	return join(tmpdir(), "oh-my-codex-notify-dispatch");
+}
+
+function writeDispatchGuardState(
+	statePath: string,
+	state: DispatchGuardState,
+	identity: string,
+	minIntervalMs: number,
+	staleEventAgeMs: number,
+): void {
+	const previousByIdentity = state.lastDispatchByIdentity && typeof state.lastDispatchByIdentity === "object"
+		? state.lastDispatchByIdentity
+		: {};
+	const retainedByIdentity: Record<string, number> = {};
+	const now = Date.now();
+	const retentionMs = Math.max(minIntervalMs, staleEventAgeMs, DEFAULT_TURN_DISPATCH_MIN_INTERVAL_MS);
+	for (const [key, value] of Object.entries(previousByIdentity)) {
+		if (typeof value === "number" && now - value <= retentionMs) {
+			retainedByIdentity[key] = value;
+		}
+	}
+	retainedByIdentity[identity] = now;
+	writeFileSync(statePath, JSON.stringify({
+		lastDispatchAt: identity === "global" ? now : (typeof state.lastDispatchAt === "number" ? state.lastDispatchAt : undefined),
+		lastDispatchByIdentity: retainedByIdentity,
+		pid: process.pid,
+	}));
+}
+
+function acquireTurnDispatchGuard(metadataPath: string, payloadArg: string): DispatchGuard {
+	const payload = parsePayloadObject(payloadArg);
+	if (!isTurnEndedPayload(payload)) return { ok: true };
+
+	const now = Date.now();
+	const staleEventAgeMs = parseNonNegativeEnvMs("OMX_NOTIFY_DISPATCH_STALE_EVENT_AGE_MS", DEFAULT_STALE_EVENT_AGE_MS);
+	const eventTimestampMs = payload ? readPayloadTimestampMs(payload) : null;
+	if (eventTimestampMs !== null && staleEventAgeMs > 0 && now - eventTimestampMs > staleEventAgeMs) {
+		return { ok: false };
+	}
+
+	const dir = dispatchGuardDir(metadataPath);
+	mkdirSync(dir, { recursive: true });
+	const lockPath = join(dir, "notify-dispatch.lock");
+	const statePath = join(dir, "notify-dispatch.guard.json");
+	try {
+		const lockStat = statSync(lockPath);
+		if (now - lockStat.mtimeMs > DISPATCH_LOCK_STALE_MS) unlinkSync(lockPath);
+	} catch {
+		// Missing or unreadable lock: try to acquire below.
+	}
+
+	let fd: number;
+	try {
+		fd = openSync(lockPath, "wx");
+		writeFileSync(fd, String(process.pid));
+		closeSync(fd);
+	} catch {
+		return { ok: false };
+	}
+
+	const release = () => {
+		try {
+			unlinkSync(lockPath);
+		} catch {
+			// Best effort.
+		}
+	};
+
+	try {
+		const minIntervalMs = parseNonNegativeEnvMs("OMX_NOTIFY_DISPATCH_MIN_INTERVAL_MS", DEFAULT_TURN_DISPATCH_MIN_INTERVAL_MS);
+		const identity = readPayloadIdentity(payload);
+		let state: DispatchGuardState = {};
+		try {
+			state = JSON.parse(readFileSync(statePath, "utf-8")) as typeof state;
+		} catch {
+			// No prior guard state.
+		}
+		if (minIntervalMs > 0) {
+			const byIdentity = state.lastDispatchByIdentity && typeof state.lastDispatchByIdentity === "object"
+				? state.lastDispatchByIdentity
+				: {};
+			const identityLastDispatchAt = typeof byIdentity[identity] === "number" ? byIdentity[identity] : 0;
+			const legacyLastDispatchAt = identity === "global" && typeof state.lastDispatchAt === "number" ? state.lastDispatchAt : 0;
+			const lastDispatchAt = Math.max(identityLastDispatchAt, legacyLastDispatchAt);
+			if (lastDispatchAt > 0 && now - lastDispatchAt < minIntervalMs) {
+				release();
+				return { ok: false };
+			}
+		}
+		return {
+			ok: true,
+			release: () => {
+				try {
+					writeDispatchGuardState(statePath, state, identity, minIntervalMs, staleEventAgeMs);
+				} catch {
+					// Guard state is best effort; the lock still prevents concurrent duplicate dispatch.
+				}
+				release();
+			},
+		};
+	} catch {
+		release();
+		return { ok: false };
+	}
+}
+
 function parseArgs(): { metadataPath: string; payloadArg: string } {
 	let metadataPath = "";
 	const args = process.argv.slice(2);
@@ -200,11 +392,17 @@ function runNotify(
 async function main(): Promise<void> {
 	const { metadataPath, payloadArg } = parseArgs();
 	if (!payloadArg || payloadArg.startsWith("-")) return;
-	const metadata = await readMetadata(metadataPath);
-	if (!isManagedPreviousNotify(metadata?.previousNotify, metadata)) {
-		runNotify(metadata?.previousNotify, payloadArg);
+	const guard = acquireTurnDispatchGuard(metadataPath, payloadArg);
+	if (!guard.ok) return;
+	try {
+		const metadata = await readMetadata(metadataPath);
+		if (!isManagedPreviousNotify(metadata?.previousNotify, metadata)) {
+			runNotify(metadata?.previousNotify, payloadArg);
+		}
+		runNotify(metadata?.omxNotify, payloadArg);
+	} finally {
+		guard.release?.();
 	}
-	runNotify(metadata?.omxNotify, payloadArg);
 }
 
 main().catch(() => {});

package/src/scripts/run-test-files.ts

@@ -5,6 +5,14 @@ import { join, resolve } from 'node:path';
 const DEFAULT_TEST_TIMEOUT_MS = 0;
 const DEFAULT_RUNNER_TIMEOUT_MS = 30 * 60 * 1_000;
 const DEFAULT_CI_TEST_CONCURRENCY = 1;
+const RUNTIME_STATE_ENV_KEYS = [
+  'OMX_ROOT',
+  'OMX_STATE_ROOT',
+  'OMX_TEAM_STATE_ROOT',
+  'OMX_SESSION_ID',
+  'CODEX_SESSION_ID',
+  'SESSION_ID',
+] as const;
 
 function parseBooleanEnv(value: string | undefined): boolean {
   if (!value) return false;
@@ -91,6 +99,11 @@ console.error(
 const childEnv = { ...process.env };
 delete childEnv.NODE_TEST_CONTEXT;
 childEnv.OMX_TEST_RELAX_TMUX_TIMEOUT = '1';
+if (!parseBooleanEnv(process.env.OMX_NODE_TEST_PRESERVE_RUNTIME_ENV)) {
+  for (const key of RUNTIME_STATE_ENV_KEYS) {
+    delete childEnv[key];
+  }
+}
 
 const result = spawnSync(process.execPath, testArgs, {
   stdio: 'inherit',