oh-my-codex 0.17.2 → 0.18.0

package/dist/scripts/__tests__/codex-native-hook.test.js

@@ -67,7 +67,7 @@ if [[ "$cmd" == "display-message" ]]; then
   exit 0
 fi
 if [[ "$cmd" == "capture-pane" ]]; then
-  echo "› ready"
+  ${options.busyLeader ? 'echo "• Working… (esc to interrupt)"' : 'echo "› ready"'}
   exit 0
 fi
 if [[ "$cmd" == "send-keys" ]]; then
@@ -1409,6 +1409,67 @@ describe("codex native hook dispatch", () => {
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("does not repeat Stop block when the last autoresearch-goal completion attempt reported objective mismatch", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-autoresearch-mismatch-reported-stop-"));
+        try {
+            await writeJson(join(cwd, ".omx", "goals", "autoresearch", "mismatched-mission", "mission.json"), {
+                version: 1,
+                workflow: "autoresearch-goal",
+                slug: "mismatched-mission",
+                topic: "Passing research bound to another Codex goal",
+                status: "passed",
+            });
+            await writeJson(join(cwd, ".omx", "goals", "autoresearch", "mismatched-mission", "completion.json"), {
+                verdict: "pass",
+                passed: true,
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-autoresearch-mismatch-reported-stop",
+                thread_id: "thread-autoresearch-mismatch-reported-stop",
+                last_assistant_message: [
+                    "I called get_goal and ran omx autoresearch-goal complete --slug mismatched-mission --codex-goal-json /tmp/snapshot.json.",
+                    "The autoresearch-goal completion failed with Codex goal objective mismatch, so I will not repeat the same complete command blindly in this thread.",
+                ].join("\n"),
+            }, { cwd });
+            assert.notEqual(result.outputJson?.decision, "block");
+            assert.doesNotMatch(JSON.stringify(result.outputJson), /autoresearch-goal complete --slug mismatched-mission/);
+            assert.doesNotMatch(JSON.stringify(result.outputJson), /get_goal snapshot reconciliation/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("still blocks later autoresearch-goal completion claims after an objective mismatch if no mismatch is reported in the final answer", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-autoresearch-mismatch-later-retry-stop-"));
+        try {
+            await writeJson(join(cwd, ".omx", "goals", "autoresearch", "retryable-mission", "mission.json"), {
+                version: 1,
+                workflow: "autoresearch-goal",
+                slug: "retryable-mission",
+                topic: "Passing research that can still retry with the correct snapshot",
+                status: "passed",
+            });
+            await writeJson(join(cwd, ".omx", "goals", "autoresearch", "retryable-mission", "completion.json"), {
+                verdict: "pass",
+                passed: true,
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-autoresearch-mismatch-later-retry-stop",
+                thread_id: "thread-autoresearch-mismatch-later-retry-stop",
+                last_assistant_message: "Autoresearch goal complete; next call update_goal({status: \"complete\"}).",
+            }, { cwd });
+            assert.equal(result.outputJson?.decision, "block");
+            assert.match(JSON.stringify(result.outputJson), /get_goal snapshot reconciliation/);
+            assert.match(JSON.stringify(result.outputJson), /omx autoresearch-goal complete --slug retryable-mission/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("treats workflow keywords in native subagent prompt text as literal delegation text", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-subagent-keyword-literal-"));
         try {
@@ -2370,6 +2431,44 @@ exit 0
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("does not block Bash commands that only mention omx question in quoted arguments", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-question-quoted-mention-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-question-quoted-mention",
+                tool_input: {
+                    command: `omx ultragoal create-goals --brief "Deep interview says omx question failed in tmux"`,
+                },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not block Bash heredocs that only document omx question text", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-question-heredoc-mention-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PreToolUse",
+                cwd,
+                tool_name: "Bash",
+                tool_use_id: "tool-question-heredoc-mention",
+                tool_input: {
+                    command: `cat > issue-notes.md <<'EOF'\nomx question failed in the attached tmux pane\nEOF`,
+                },
+            }, { cwd });
+            assert.equal(result.omxEventName, "pre-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("allows Bash omx question when the command preserves the leader-pane return hint", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-pretool-question-allow-"));
         try {
@@ -4052,6 +4151,82 @@ exit 0
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("does not treat non-MCP source output containing detector constants as MCP transport death", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-read-mcp-source-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
+                cwd,
+                tool_name: "Read",
+                tool_use_id: "tool-read-mcp-source",
+                tool_input: { file_path: "src/scripts/codex-native-pre-post.ts" },
+                tool_response: "const MCP_TRANSPORT_FAILURE_PATTERNS = [/transport closed/i, /server disconnected/i];\nconst context = /\\bmcp\\b/i;",
+            }, { cwd });
+            assert.equal(result.omxEventName, "post-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not treat non-MCP docs stdout mentioning closed MCP transport as transport death", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-docs-mcp-log-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
+                cwd,
+                tool_name: "ShellOutput",
+                tool_use_id: "tool-docs-mcp-log",
+                tool_response: JSON.stringify({
+                    stdout: "Troubleshooting note: MCP transport closed after the server disconnected in an old log.",
+                    stderr: "",
+                }),
+            }, { cwd });
+            assert.equal(result.omxEventName, "post-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not MCP-block non-MCP command output with unrelated stderr and MCP transport stdout", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-nonmcp-mixed-output-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
+                cwd,
+                tool_name: "ShellOutput",
+                tool_use_id: "tool-nonmcp-mixed-output",
+                tool_response: JSON.stringify({
+                    stdout: "captured log line: MCP transport closed before response",
+                    stderr: "grep: fixture.txt: No such file or directory",
+                }),
+            }, { cwd });
+            assert.equal(result.omxEventName, "post-tool-use");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("still blocks MCP-like raw transport failures", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-mcp-raw-transport-"));
+        try {
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "PostToolUse",
+                cwd,
+                tool_name: "mcp__omx_state__state_write",
+                tool_use_id: "tool-mcp-raw-transport",
+                tool_response: "transport closed after server disconnected",
+            }, { cwd });
+            assert.equal(result.omxEventName, "post-tool-use");
+            assert.equal(result.outputJson?.decision, "block");
+            assert.match(String(result.outputJson?.reason || ""), /lost its transport\/server connection/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("returns PostToolUse MCP transport fallback guidance for clear MCP transport death", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-posttool-mcp-transport-"));
         try {
@@ -4366,6 +4541,51 @@ exit 0
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("requires Autopilot code review after a compact-boundary Stop exemption", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-autopilot-review-compact-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionId = "sess-stop-autopilot-review-compact";
+            await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+            await writeJson(join(stateDir, "sessions", sessionId, "autopilot-state.json"), {
+                active: true,
+                mode: "autopilot",
+                current_phase: "code-review",
+                state: {
+                    phase_cycle: ["ralplan", "ralph", "code-review"],
+                    handoff_artifacts: {
+                        ralplan: ".omx/plans/prd-issue-2366.md",
+                        ralph: { verification: ["npm test"] },
+                        code_review: null,
+                    },
+                    review_verdict: null,
+                },
+            });
+            const compactBoundary = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+                stop_reason: "context compact",
+            }, { cwd });
+            const resumedStop = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+            }, { cwd });
+            assert.equal(compactBoundary.omxEventName, "stop");
+            assert.equal(compactBoundary.outputJson, null);
+            assert.equal(resumedStop.omxEventName, "stop");
+            assert.deepEqual(resumedStop.outputJson, {
+                decision: "block",
+                reason: "OMX autopilot is still active (phase: code-review); continue the task and gather fresh verification evidence before stopping.",
+                stopReason: "autopilot_code-review",
+                systemMessage: "OMX autopilot is still active (phase: code-review). Run the required $code-review step before completing or clearing Autopilot state.",
+            });
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("suppresses duplicate Autopilot planning Stop replays so stale planning state cannot loop indefinitely", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-autopilot-planning-replay-"));
         try {
@@ -4858,6 +5078,87 @@ exit 0
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("queues worker Stop leader nudge with Tab and submit when leader pane is busy", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-team-worker-busy-leader-"));
+        const prevTeamWorker = process.env.OMX_TEAM_WORKER;
+        const prevTeamStateRoot = process.env.OMX_TEAM_STATE_ROOT;
+        const prevPath = process.env.PATH;
+        try {
+            await initTeamState("worker-stop-team-busy-leader", "worker stop busy leader", "executor", 1, cwd, undefined, { ...process.env, OMX_SESSION_ID: "sess-stop-team-worker-busy-leader" });
+            const fakeBinDir = join(cwd, "fake-bin");
+            const tmuxLogPath = join(cwd, "tmux.log");
+            await mkdir(fakeBinDir, { recursive: true });
+            await writeFile(join(fakeBinDir, "tmux"), buildWorkerStopFakeTmux(tmuxLogPath, { busyLeader: true }));
+            await chmod(join(fakeBinDir, "tmux"), 0o755);
+            const stateDir = join(cwd, ".omx", "state");
+            const teamDir = join(stateDir, "team", "worker-stop-team-busy-leader");
+            const workerDir = join(teamDir, "workers", "worker-1");
+            await writeJson(join(teamDir, "config.json"), {
+                name: "worker-stop-team-busy-leader",
+                tmux_session: "omx-team-worker-stop",
+                leader_pane_id: "%42",
+                workers: [{ name: "worker-1", index: 1, pane_id: "%10" }],
+            });
+            await writeJson(join(teamDir, "manifest.v2.json"), {
+                name: "worker-stop-team-busy-leader",
+                tmux_session: "omx-team-worker-stop",
+                leader_pane_id: "%42",
+                workers: [{ name: "worker-1", index: 1, pane_id: "%10" }],
+            });
+            await writeJson(join(workerDir, "identity.json"), {
+                name: "worker-1",
+                index: 1,
+                role: "executor",
+                assigned_tasks: ["1"],
+                worktree_path: cwd,
+                team_state_root: stateDir,
+            });
+            await writeJson(join(workerDir, "status.json"), {
+                state: "done",
+                current_task_id: "1",
+                updated_at: new Date().toISOString(),
+            });
+            await writeJson(join(teamDir, "tasks", "task-1.json"), {
+                id: "1",
+                subject: "hook task",
+                description: "finish hook task",
+                status: "completed",
+                owner: "worker-1",
+                created_at: new Date().toISOString(),
+            });
+            process.env.OMX_TEAM_WORKER = "worker-stop-team-busy-leader/worker-1";
+            process.env.OMX_TEAM_STATE_ROOT = stateDir;
+            process.env.PATH = `${fakeBinDir}:${prevPath || ""}`;
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: "sess-stop-team-worker-busy-leader",
+            }, { cwd });
+            assert.equal(result.outputJson, null);
+            const tmuxLog = await readFile(tmuxLogPath, "utf-8");
+            assert.match(tmuxLog, /send-keys -t %42 -l \[OMX\] worker-1 native Stop allowed/);
+            assert.match(tmuxLog, /send-keys -t %42 Tab/);
+            assert.match(tmuxLog, /send-keys -t %42 C-m/);
+            assert.ok(tmuxLog.indexOf("send-keys -t %42 Tab") < tmuxLog.indexOf("send-keys -t %42 C-m"), "busy worker-stop nudge should press Tab before C-m");
+            const nudgeState = JSON.parse(await readFile(join(workerDir, "worker-stop-nudge.json"), "utf-8"));
+            assert.equal(nudgeState.delivery, "queued");
+        }
+        finally {
+            if (typeof prevTeamWorker === "string")
+                process.env.OMX_TEAM_WORKER = prevTeamWorker;
+            else
+                delete process.env.OMX_TEAM_WORKER;
+            if (typeof prevTeamStateRoot === "string")
+                process.env.OMX_TEAM_STATE_ROOT = prevTeamStateRoot;
+            else
+                delete process.env.OMX_TEAM_STATE_ROOT;
+            if (typeof prevPath === "string")
+                process.env.PATH = prevPath;
+            else
+                delete process.env.PATH;
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("allows worker Stop when the Stop nudge helper cannot deliver", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-team-worker-helper-fail-"));
         const prevTeamWorker = process.env.OMX_TEAM_WORKER;
@@ -5622,13 +5923,25 @@ exit 0
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("does not block on stale ralplan skill-active when canonical run-state is terminal", async () => {
-        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-terminal-ralplan-run-"));
+    it("does not block when canonical root ralplan state is inactive but session ralplan state is stale active", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-stale-session-ralplan-root-inactive-"));
         try {
             const stateDir = join(cwd, ".omx", "state");
-            const sessionId = "sess-stop-terminal-ralplan";
+            const sessionId = "sess-stop-stale-session-ralplan";
             await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
             await writeJson(join(stateDir, "session.json"), { session_id: sessionId });
+            await writeJson(join(stateDir, "skill-active-state.json"), {
+                active: false,
+                skill: "ralplan",
+                phase: "reviewing",
+                active_skills: [],
+            });
+            await writeJson(join(stateDir, "ralplan-state.json"), {
+                active: false,
+                mode: "ralplan",
+                current_phase: "complete",
+                session_id: sessionId,
+            });
             await writeJson(join(stateDir, "sessions", sessionId, "skill-active-state.json"), {
                 active: true,
                 skill: "ralplan",
@@ -5647,16 +5960,6 @@ exit 0
                 current_phase: "planning",
                 session_id: sessionId,
             });
-            await writeJson(join(stateDir, "sessions", sessionId, "run-state.json"), {
-                version: 1,
-                mode: "ralplan",
-                active: false,
-                outcome: "finish",
-                lifecycle_outcome: "finished",
-                current_phase: "complete",
-                completed_at: "2026-05-01T00:00:00.000Z",
-                updated_at: "2026-05-01T00:00:00.000Z",
-            });
             const result = await dispatchCodexNativeHook({
                 hook_event_name: "Stop",
                 cwd,
@@ -5669,13 +5972,26 @@ exit 0
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("does not block on stale ralplan skill-active when pinned mode state belongs to another session", async () => {
-        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-foreign-ralplan-"));
+    it("keeps blocking current session ralplan when root inactive ralplan state belongs to another session", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-session-ralplan-root-other-session-"));
         try {
             const stateDir = join(cwd, ".omx", "state");
-            const sessionId = "sess-stop-current-ralplan";
+            const sessionId = "sess-stop-current-active-ralplan";
             await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
             await writeJson(join(stateDir, "session.json"), { session_id: sessionId });
+            await writeJson(join(stateDir, "skill-active-state.json"), {
+                active: false,
+                skill: "ralplan",
+                phase: "complete",
+                session_id: "sess-stop-old-ralplan",
+                active_skills: [],
+            });
+            await writeJson(join(stateDir, "ralplan-state.json"), {
+                active: false,
+                mode: "ralplan",
+                current_phase: "complete",
+                session_id: "sess-stop-old-ralplan",
+            });
             await writeJson(join(stateDir, "sessions", sessionId, "skill-active-state.json"), {
                 active: true,
                 skill: "ralplan",
@@ -5692,7 +6008,7 @@ exit 0
                 active: true,
                 mode: "ralplan",
                 current_phase: "planning",
-                session_id: "sess-other-ralplan",
+                session_id: sessionId,
             });
             const result = await dispatchCodexNativeHook({
                 hook_event_name: "Stop",
@@ -5700,21 +6016,260 @@ exit 0
                 session_id: sessionId,
             }, { cwd });
             assert.equal(result.omxEventName, "stop");
-            assert.equal(result.outputJson, null);
+            assert.equal(result.outputJson?.decision, "block");
+            assert.equal(result.outputJson?.stopReason, "skill_ralplan_planning_continue_artifact");
         }
         finally {
             await rm(cwd, { recursive: true, force: true });
         }
     });
-    it("returns an explicit ralplan waiting status while subagents are still active", async () => {
-        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-skill-subagent-"));
+    it("keeps blocking current session ralplan when root inactive ralplan state is unscoped", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-session-ralplan-root-unscoped-"));
         try {
             const stateDir = join(cwd, ".omx", "state");
-            await mkdir(join(stateDir, "sessions", "sess-stop-skill-subagent"), { recursive: true });
-            await writeJson(join(stateDir, "session.json"), { session_id: "sess-stop-skill-subagent" });
-            await writeJson(join(stateDir, "sessions", "sess-stop-skill-subagent", "skill-active-state.json"), {
-                active: true,
-                skill: "ralplan",
+            const sessionId = "sess-stop-unscoped-root-current-active";
+            await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: sessionId });
+            await writeJson(join(stateDir, "skill-active-state.json"), {
+                active: false,
+                skill: "ralplan",
+                phase: "complete",
+                active_skills: [],
+            });
+            await writeJson(join(stateDir, "ralplan-state.json"), {
+                active: false,
+                mode: "ralplan",
+                current_phase: "complete",
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "skill-active-state.json"), {
+                active: true,
+                skill: "ralplan",
+                phase: "planning",
+                session_id: sessionId,
+                active_skills: [{
+                        skill: "ralplan",
+                        phase: "planning",
+                        active: true,
+                        session_id: sessionId,
+                    }],
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "ralplan-state.json"), {
+                active: true,
+                mode: "ralplan",
+                current_phase: "planning",
+                session_id: sessionId,
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.equal(result.outputJson?.decision, "block");
+            assert.equal(result.outputJson?.stopReason, "skill_ralplan_planning_continue_artifact");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not block stale session ralplan when root ralplan is terminal and another root skill is active", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-stale-ralplan-other-root-skill-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionId = "sess-stop-stale-ralplan-other-root-skill";
+            await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: sessionId });
+            await writeJson(join(stateDir, "skill-active-state.json"), {
+                active: true,
+                skill: "deep-interview",
+                phase: "intent-first",
+                session_id: sessionId,
+                active_skills: [{
+                        skill: "deep-interview",
+                        phase: "intent-first",
+                        active: true,
+                        session_id: sessionId,
+                    }],
+            });
+            await writeJson(join(stateDir, "ralplan-state.json"), {
+                active: false,
+                mode: "ralplan",
+                current_phase: "complete",
+                session_id: sessionId,
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "skill-active-state.json"), {
+                active: true,
+                skill: "ralplan",
+                phase: "planning",
+                session_id: sessionId,
+                active_skills: [{
+                        skill: "ralplan",
+                        phase: "planning",
+                        active: true,
+                        session_id: sessionId,
+                    }],
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "ralplan-state.json"), {
+                active: true,
+                mode: "ralplan",
+                current_phase: "planning",
+                session_id: sessionId,
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("keeps blocking session ralplan when canonical root state is not inactive", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-session-ralplan-root-active-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionId = "sess-stop-session-ralplan-root-active";
+            await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: sessionId });
+            await writeJson(join(stateDir, "skill-active-state.json"), {
+                active: true,
+                skill: "ralplan",
+                phase: "planning",
+                session_id: sessionId,
+                active_skills: [{
+                        skill: "ralplan",
+                        phase: "planning",
+                        active: true,
+                        session_id: sessionId,
+                    }],
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "skill-active-state.json"), {
+                active: true,
+                skill: "ralplan",
+                phase: "planning",
+                session_id: sessionId,
+                active_skills: [{
+                        skill: "ralplan",
+                        phase: "planning",
+                        active: true,
+                        session_id: sessionId,
+                    }],
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "ralplan-state.json"), {
+                active: true,
+                mode: "ralplan",
+                current_phase: "planning",
+                session_id: sessionId,
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.equal(result.outputJson?.decision, "block");
+            assert.equal(result.outputJson?.stopReason, "skill_ralplan_planning_continue_artifact");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not block on stale ralplan skill-active when canonical run-state is terminal", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-terminal-ralplan-run-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionId = "sess-stop-terminal-ralplan";
+            await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: sessionId });
+            await writeJson(join(stateDir, "sessions", sessionId, "skill-active-state.json"), {
+                active: true,
+                skill: "ralplan",
+                phase: "planning",
+                session_id: sessionId,
+                active_skills: [{
+                        skill: "ralplan",
+                        phase: "planning",
+                        active: true,
+                        session_id: sessionId,
+                    }],
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "ralplan-state.json"), {
+                active: true,
+                mode: "ralplan",
+                current_phase: "planning",
+                session_id: sessionId,
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "run-state.json"), {
+                version: 1,
+                mode: "ralplan",
+                active: false,
+                outcome: "finish",
+                lifecycle_outcome: "finished",
+                current_phase: "complete",
+                completed_at: "2026-05-01T00:00:00.000Z",
+                updated_at: "2026-05-01T00:00:00.000Z",
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not block on stale ralplan skill-active when pinned mode state belongs to another session", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-foreign-ralplan-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionId = "sess-stop-current-ralplan";
+            await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: sessionId });
+            await writeJson(join(stateDir, "sessions", sessionId, "skill-active-state.json"), {
+                active: true,
+                skill: "ralplan",
+                phase: "planning",
+                session_id: sessionId,
+                active_skills: [{
+                        skill: "ralplan",
+                        phase: "planning",
+                        active: true,
+                        session_id: sessionId,
+                    }],
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "ralplan-state.json"), {
+                active: true,
+                mode: "ralplan",
+                current_phase: "planning",
+                session_id: "sess-other-ralplan",
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("returns an explicit ralplan waiting status while subagents are still active", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-skill-subagent-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            await mkdir(join(stateDir, "sessions", "sess-stop-skill-subagent"), { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: "sess-stop-skill-subagent" });
+            await writeJson(join(stateDir, "sessions", "sess-stop-skill-subagent", "skill-active-state.json"), {
+                active: true,
+                skill: "ralplan",
                 phase: "planning",
             });
             await writeJson(join(stateDir, "sessions", "sess-stop-skill-subagent", "ralplan-state.json"), {
@@ -6605,6 +7160,42 @@ exit 0
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("allows Stop from stale orphaned session-scoped Ralph starting iteration zero state", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-stale-orphan-starting-ralph-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const sessionId = "sess-stale-orphan-ralph";
+            await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+            await writeJson(join(stateDir, "session.json"), { session_id: sessionId, native_session_id: sessionId, cwd });
+            await writeJson(join(stateDir, "sessions", sessionId, "ralph-state.json"), {
+                active: true,
+                mode: "ralph",
+                current_phase: "starting",
+                iteration: 0,
+                session_id: sessionId,
+                updated_at: "2000-01-01T00:00:00.000Z",
+            });
+            await writeJson(join(stateDir, "sessions", sessionId, "skill-active-state.json"), {
+                active: true,
+                skill: "ralph",
+                phase: "starting",
+                session_id: sessionId,
+                active_skills: [{ skill: "ralph", phase: "starting", active: true, session_id: sessionId }],
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: sessionId,
+                thread_id: "thread-verifier-terminal",
+                last_assistant_message: "APPROVE: read-only verifier evidence is fresh and sufficient.",
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.equal(result.outputJson, null);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("blocks Stop on visible active session-scoped Ralph starting state and reports its path", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-visible-starting-ralph-"));
         try {
@@ -6640,6 +7231,126 @@ exit 0
             await rm(cwd, { recursive: true, force: true });
         }
     });
+    it("retires prompt-seeded Ralph starting state when canonical Ralph already completed with audit", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-ralph-shadowed-starting-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const nativeSessionId = "native-hook-seed";
+            const canonicalSessionId = "omx-runtime-session";
+            await mkdir(join(stateDir, "sessions", nativeSessionId), { recursive: true });
+            await mkdir(join(stateDir, "sessions", canonicalSessionId), { recursive: true });
+            await writeJson(join(stateDir, "session.json"), {
+                session_id: canonicalSessionId,
+                cwd,
+            });
+            await writeJson(join(stateDir, "sessions", nativeSessionId, "ralph-state.json"), {
+                active: true,
+                mode: "ralph",
+                current_phase: "starting",
+                session_id: nativeSessionId,
+                iteration: 0,
+                task_slug: "mvp-h-local-method-preflight-execution",
+                started_at: "2026-05-14T07:00:00.000Z",
+            });
+            await writeJson(join(stateDir, "sessions", nativeSessionId, "skill-active-state.json"), {
+                active: true,
+                skill: "ralph",
+                phase: "starting",
+                session_id: nativeSessionId,
+                active_skills: [{ skill: "ralph", phase: "starting", active: true, session_id: nativeSessionId }],
+            });
+            await writeJson(join(stateDir, "sessions", canonicalSessionId, "ralph-state.json"), {
+                active: false,
+                mode: "ralph",
+                current_phase: "complete",
+                session_id: canonicalSessionId,
+                completed_at: "2026-05-14T07:30:00.000Z",
+                completion_audit: {
+                    passed: true,
+                    prompt_to_artifact_checklist: ["task evidence mapped"],
+                    verification_evidence: ["fresh verification evidence recorded"],
+                },
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: nativeSessionId,
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.equal(result.outputJson, null);
+            const retiredState = JSON.parse(await readFile(join(stateDir, "sessions", nativeSessionId, "ralph-state.json"), "utf-8"));
+            assert.equal(retiredState.active, false);
+            assert.equal(retiredState.current_phase, "complete");
+            assert.equal(retiredState.stop_reason, "shadowed_by_completed_canonical_ralph");
+            assert.equal(retiredState.shadowed_by_completed_canonical_ralph.session_id, canonicalSessionId);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("does not retire prompt-seeded Ralph starting state from a completed canonical Ralph owned by another thread", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-ralph-shadowed-thread-mismatch-"));
+        try {
+            const stateDir = join(cwd, ".omx", "state");
+            const nativeSessionId = "native-hook-seed";
+            const canonicalSessionId = "omx-runtime-session";
+            await mkdir(join(stateDir, "sessions", nativeSessionId), { recursive: true });
+            await mkdir(join(stateDir, "sessions", canonicalSessionId), { recursive: true });
+            await writeJson(join(stateDir, "session.json"), {
+                session_id: canonicalSessionId,
+                cwd,
+            });
+            await writeJson(join(stateDir, "sessions", nativeSessionId, "ralph-state.json"), {
+                active: true,
+                mode: "ralph",
+                current_phase: "starting",
+                session_id: nativeSessionId,
+                iteration: 0,
+                task_slug: "mvp-h-local-method-preflight-execution",
+                started_at: "2026-05-14T07:00:00.000Z",
+            });
+            await writeJson(join(stateDir, "sessions", nativeSessionId, "skill-active-state.json"), {
+                active: true,
+                skill: "ralph",
+                phase: "starting",
+                session_id: nativeSessionId,
+                active_skills: [{ skill: "ralph", phase: "starting", active: true, session_id: nativeSessionId }],
+            });
+            await writeJson(join(stateDir, "sessions", canonicalSessionId, "ralph-state.json"), {
+                active: false,
+                mode: "ralph",
+                current_phase: "complete",
+                session_id: canonicalSessionId,
+                owner_codex_thread_id: "thread-A",
+                completed_at: "2026-05-14T07:30:00.000Z",
+                completion_audit: {
+                    passed: true,
+                    prompt_to_artifact_checklist: ["task evidence mapped"],
+                    verification_evidence: ["fresh verification evidence recorded"],
+                },
+            });
+            const result = await dispatchCodexNativeHook({
+                hook_event_name: "Stop",
+                cwd,
+                session_id: nativeSessionId,
+                thread_id: "thread-B",
+            }, { cwd });
+            assert.equal(result.omxEventName, "stop");
+            assert.deepEqual(result.outputJson, {
+                decision: "block",
+                reason: "OMX Ralph is still active (phase: starting; state: .omx/state/sessions/native-hook-seed/ralph-state.json); continue the task and gather fresh verification evidence before stopping.",
+                stopReason: "ralph_starting",
+                systemMessage: "OMX Ralph is still active (phase: starting; state: .omx/state/sessions/native-hook-seed/ralph-state.json); continue the task and gather fresh verification evidence before stopping.",
+            });
+            const preservedState = JSON.parse(await readFile(join(stateDir, "sessions", nativeSessionId, "ralph-state.json"), "utf-8"));
+            assert.equal(preservedState.active, true);
+            assert.equal(preservedState.current_phase, "starting");
+            assert.equal(preservedState.stop_reason, undefined);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
     it("does not block Stop from another session-scoped Ralph state when an explicit session_id has no active Ralph state", async () => {
         const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-explicit-session-ralph-"));
         try {