oh-my-codex 0.16.0 → 0.16.2

package/skills/ralplan/SKILL.md

@@ -54,14 +54,24 @@ The consensus workflow:
    d. Return to Critic evaluation
    e. Repeat this loop until Critic returns `APPROVE` or 5 iterations are reached
    f. If 5 iterations are reached without `APPROVE`, present the best version to the user
-6. On Critic approval *(--interactive only)*: If `--interactive` is set, use the structured question UI to present the plan with approval options (Approve and execute via ralph / Approve and implement via team / Request changes / Reject). Final plan must include ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups), an explicit available-agent-types roster, concrete follow-up staffing guidance for both `ralph` and `team`, suggested reasoning levels by lane, explicit `omx team` / `$team` launch hints, and a concrete **team verification** path. Otherwise, output the final plan and stop.
-7. *(--interactive only)* User chooses: Approve (ralph or team), Request changes, or Reject
-8. *(--interactive only)* On approval: invoke `$ralph` for sequential execution or `$team` for parallel team execution with the explicit available-agent-types roster, reasoning-by-lane guidance, role/staffing allocation guidance, launch hints, and verification-path guidance from the approved plan -- never implement directly
+6. On Critic approval *(--interactive only)*: If `--interactive` is set, use the structured question UI to present the plan with approval options (Approve and execute via ralph / Approve and implement via team / Start a goal-mode follow-up / Request changes / Reject). Final plan must include ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups), an explicit available-agent-types roster, concrete follow-up staffing guidance for both `ralph` and `team`, suggested reasoning levels by lane, explicit `omx team` / `$team` launch hints, a concrete **team verification** path, and a product-facing **Goal-Mode Follow-up Suggestions** section. Recommend `$ultragoal` by default for goal-mode follow-up, use `$autoresearch-goal` instead when the context is a research project, and use `$performance-goal` instead when the context is an optimization or performance project. Otherwise, output the final plan and stop.
+7. *(--interactive only)* User chooses: Approve (ralph, team, or a goal-mode follow-up), Request changes, or Reject
+8. *(--interactive only)* On approval: invoke `$ralph` for sequential execution, `$team` for parallel team execution, or the selected goal-mode follow-up (`$ultragoal`, `$autoresearch-goal`, or `$performance-goal`) with the approved plan and matching success/evaluator context -- never implement directly. Preserve the explicit available-agent-types roster, reasoning-by-lane guidance, role/staffing allocation guidance, launch hints, and verification-path guidance from the approved plan for Ralph/team paths.
 
 > **Important:** Steps 3 and 4 MUST run sequentially. Do NOT issue both agent calls in the same parallel batch. Always await the Architect result before invoking Critic.
 
 Follow the Plan skill's full documentation for consensus mode details.
 
+## Goal-Mode Follow-up Suggestions
+
+When ralplan outputs a final handoff or asks the user to choose a next lane, include product-facing goal-mode suggestions alongside the existing Ralph and team options:
+
+- `$ultragoal` — **default goal-mode follow-up** for implementation or general goal-oriented follow-up plans that should become durable Codex/OMX goals with sequential completion tracking.
+- `$autoresearch-goal` — research-project follow-up when the plan centers on a question, literature/reference gathering, evaluator-backed research, or a professor/critic-style research deliverable.
+- `$performance-goal` — optimization/performance follow-up when the plan centers on speed, latency, throughput, memory, benchmark, or other measurable performance work.
+
+Keep `$ralph` and `$team` as first-class execution options where appropriate: use Ralph for persistent single-owner completion/verification pressure and team for coordinated parallel implementation. Do not present the goal-mode options as replacements for Ralph/team when the task is mainly implementation delivery; present them as better fits when durable goal tracking, research validation, or performance evaluators are the primary need.
+
 ## Pre-context Intake
 
 Before consensus planning or execution handoff, ensure a grounded context snapshot exists:

package/skills/team/SKILL.md

@@ -183,7 +183,7 @@ Default-model rule:
 Thinking-level rule (critical):
 - **No model-name heuristic mapping.**
 - Team runtime must **not** infer `model_reasoning_effort` from model-name substrings (e.g., `spark`, `high-capability`, `mini`).
-- When the leader assigns teammate roles/tasks, OMX allocates **per-worker reasoning effort dynamically** from the resolved worker role (`low`, `medium`, `high`).
+- When the leader assigns teammate roles/tasks, OMX allocates **per-worker reasoning effort dynamically** from the resolved worker role and `agentReasoning` overrides (`low`, `medium`, `high`, `xhigh`).
 - Explicit launch args still win: if `OMX_TEAM_WORKER_LAUNCH_ARGS` already includes `-c model_reasoning_effort=...`, that explicit value overrides dynamic allocation for every worker.
 
 Normalization requirements:
@@ -191,7 +191,7 @@ Normalization requirements:
 - Remove duplicate/conflicting model flags
 - Emit exactly one final canonical flag: `--model <value>`
 - Preserve unrelated args in worker launch config
-- If explicit reasoning exists, preserve canonical `-c model_reasoning_effort="<level>"`; otherwise inject the worker role's default reasoning level
+- If explicit reasoning exists, preserve canonical `-c model_reasoning_effort="<level>"`; otherwise inject the worker role's default or `agentReasoning`-overridden reasoning level
 
 ## Required Lifecycle (Operator Contract)
 

package/skills/ultragoal/SKILL.md

@@ -9,7 +9,7 @@ Use when the user asks for `ultragoal`, `create-goals`, `complete-goals`, durabl
 
 ## Purpose
 
-`ultragoal` turns a brief into repo-native artifacts and then drives one goal at a time through Codex goal tools:
+`ultragoal` turns a brief into repo-native artifacts and then drives a Codex goal safely through goal tools. New plans default to an aggregate Codex goal for the whole ultragoal run while OMX tracks G001/G002 story progress in the ledger.
 
 - `.omx/ultragoal/brief.md`
 - `.omx/ultragoal/goals.json`
@@ -21,6 +21,7 @@ Use when the user asks for `ultragoal`, `create-goals`, `complete-goals`, durabl
    - `omx ultragoal create-goals --brief "<brief>"`
    - `omx ultragoal create-goals --brief-file <path>`
    - `cat <brief> | omx ultragoal create-goals --from-stdin`
+   - `omx ultragoal create-goals --codex-goal-mode per-story --brief "<brief>"` only when one fresh Codex thread per story is explicitly preferred
 2. Inspect `.omx/ultragoal/goals.json` and refine if needed.
 
 ## Complete goals
@@ -30,20 +31,23 @@ Loop until `omx ultragoal status` reports all goals complete:
 1. Run `omx ultragoal complete-goals`.
 2. Read the printed handoff.
 3. Call `get_goal`.
-4. If no active Codex goal exists, call `create_goal` with the printed payload.
-5. Complete that single goal only.
-6. Run a completion audit against the objective and real artifacts/tests.
-7. When complete, call `update_goal({status: "complete"})`, then call `get_goal` again for a fresh completion snapshot.
+4. If no active Codex goal exists, call `create_goal` with the printed payload. In aggregate mode, if the same aggregate Codex objective is already active, continue the current OMX story without creating a new Codex goal.
+5. Complete the current OMX story only.
+6. Run a completion audit against the story objective and real artifacts/tests.
+7. In aggregate mode, do **not** call `update_goal` for intermediate stories; checkpoint with a fresh `get_goal` snapshot whose aggregate objective is still `active`. On the final story only, call `update_goal({status: "complete"})`, then call `get_goal` again for a fresh `complete` snapshot.
 8. Checkpoint the durable ledger with that snapshot:
    `omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --codex-goal-json <get_goal-json-or-path>`
 9. If blocked or failed, checkpoint failure:
    `omx ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"`
-10. Resume failed goals with `omx ultragoal complete-goals --retry-failed`.
+10. For legacy per-story completed-goal blockers, preserve the non-terminal blocker with:
+   `omx ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json <get_goal-json-or-path>`
+11. Resume failed goals with `omx ultragoal complete-goals --retry-failed`.
 
 ## Constraints
 
 - The shell command cannot directly invoke Codex interactive `/goal`; it emits a model-facing handoff for the active Codex agent.
 - Never call `create_goal` when `get_goal` reports a different active goal.
-- Never call `update_goal` unless the current goal is actually complete.
+- Never call `update_goal` unless the aggregate run or legacy per-story goal is actually complete.
+- In aggregate mode, intermediate story checkpoints require a matching `active` Codex snapshot; final story completion requires a matching `complete` snapshot after `update_goal`.
 - Completion checkpoints require read-only Codex snapshot reconciliation: pass fresh `get_goal` JSON/path with `--codex-goal-json`; shell commands and hooks must not mutate Codex goal state.
 - Treat `ledger.jsonl` as the durable audit trail; checkpoint after every success or failure.

package/skills/visual-ralph/SKILL.md

@@ -65,6 +65,14 @@ Prompt requirements:
 - forbid logos/watermarks/unrequested brand marks,
 - ask imagegen to avoid impossible UI details or unreadable text.
 
+When running under OMX CLI/runtime and a generated reference is part of an active Ralph-style loop, queue a continuation checkpoint before invoking the built-in image tool:
+
+```bash
+omx imagegen continuation <session-id> --artifact <slug-or-filename> --generated-dir "$CODEX_HOME/generated_images/<session>" --work-dir ".omx/artifacts/visual-ralph/<slug>"
+```
+
+This helper records `.omx/state/sessions/<session>/imagegen-pending.json` and uses the existing Stop-hook follow-up queue. It exists because built-in image generation may have to end the assistant turn immediately; the next Stop checkpoint should resume artifact recovery, copy the generated image into the workspace, and run the required visual QA/verdict gate instead of relying on a manual `$ralph` re-prompt.
+
 For project-bound implementation, copy the approved reference into the workspace, for example under `.omx/artifacts/visual-ralph/<slug>/reference.png`. Never leave the implementation reference only in `$CODEX_HOME/generated_images/...`.
 
 ### 3. Require explicit user approval

package/skills/wiki/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wiki
-description: Persistent markdown project wiki stored under .omx/wiki with keyword search and lifecycle capture
+description: Persistent markdown project wiki stored under repository omx_wiki with keyword search and lifecycle capture
 triggers: ["wiki add", "wiki lint", "wiki query", "wiki read", "wiki delete"]
 ---
 
@@ -42,9 +42,9 @@ wiki_refresh()
 `architecture`, `decision`, `pattern`, `debugging`, `environment`, `session-log`, `reference`, `convention`
 
 ## Storage
-- Pages: `.omx/wiki/*.md`
-- Index: `.omx/wiki/index.md`
-- Log: `.omx/wiki/log.md`
+- Pages: `omx_wiki/*.md`
+- Index: `omx_wiki/index.md`
+- Log: `omx_wiki/log.md`
 
 ## Cross-References
 Use `[[page-name]]` wiki-link syntax to create cross-references between pages.
@@ -54,4 +54,4 @@ At session end, discoveries can be captured as `session-log-*` pages. Configure
 
 ## Hard Constraints
 - No vector embeddings — query uses keyword + tag matching only
-- Wiki files remain local project state under `.omx/wiki/`
+- Wiki files are repository project knowledge under `omx_wiki/`; legacy `.omx/wiki/` is read-only compatibility input when no canonical wiki exists

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

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { chmod, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -24,6 +24,8 @@ import { writeSessionStart } from "../../hooks/session.js";
 import { resetTriageConfigCache } from "../../hooks/triage-config.js";
 import { executeStateOperation } from "../../state/operations.js";
 import { OMX_TMUX_HUD_OWNER_ENV } from "../../hud/reconcile.js";
+import { writePage } from "../../wiki/storage.js";
+import { WIKI_SCHEMA_VERSION } from "../../wiki/types.js";
 
 function nativeHookScriptPath(): string {
   return join(process.cwd(), "dist", "scripts", "codex-native-hook.js");
@@ -188,6 +190,8 @@ const TEAM_ENV_KEYS = [
   "OMX_TEAM_STATE_ROOT",
   "OMX_TEAM_LEADER_CWD",
   "OMX_SESSION_ID",
+  "OMX_ROOT",
+  "OMX_STATE_ROOT",
   "SESSION_ID",
   "OMX_QUESTION_RETURN_PANE",
   "OMX_LEADER_PANE_ID",
@@ -223,6 +227,8 @@ describe("codex native hook config", () => {
       "PreToolUse",
       "PostToolUse",
       "UserPromptSubmit",
+      "PreCompact",
+      "PostCompact",
       "Stop",
     ]);
 
@@ -437,14 +443,142 @@ describe("codex native hook dispatch", () => {
     }
   });
 
+  it("logs Stop dispatch failures without foreground stderr noise", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-stop-dispatch-silent-"));
+    try {
+      const result = spawnSync(process.execPath, [nativeHookScriptPath()], {
+        cwd,
+        input: JSON.stringify({
+          hook_event_name: "Stop",
+          cwd,
+          session_id: "sess-cli-stop-dispatch-silent",
+          thread_id: "thread-cli-stop-dispatch-silent",
+          turn_id: "turn-cli-stop-dispatch-silent",
+        }),
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          NODE_ENV: "test",
+          OMX_NATIVE_HOOK_TEST_THROW_STOP_DISPATCH: "1",
+        },
+      });
+
+      assert.equal(result.status, 0, result.stderr || result.stdout);
+      assert.equal(result.stderr, "");
+      const output = parseSingleJsonStdout(result.stdout);
+      assert.equal(output.stopReason, "native_stop_dispatch_failure");
+
+      const logFiles = await readdir(join(cwd, ".omx", "logs"));
+      assert.equal(logFiles.some((name) => /^native-hook-\d{4}-\d{2}-\d{2}\.jsonl$/.test(name)), true);
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps non-Stop dispatch failures fail-closed without foreground stderr noise", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-cli-pretool-dispatch-silent-"));
+    try {
+      const result = spawnSync(process.execPath, [nativeHookScriptPath()], {
+        cwd,
+        input: JSON.stringify({
+          hook_event_name: "PreToolUse",
+          cwd,
+          session_id: "sess-cli-pretool-dispatch-silent",
+          thread_id: "thread-cli-pretool-dispatch-silent",
+          turn_id: "turn-cli-pretool-dispatch-silent",
+          tool_name: "Bash",
+          tool_input: { command: "pwd" },
+        }),
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          NODE_ENV: "test",
+          OMX_NATIVE_HOOK_TEST_THROW_DISPATCH: "1",
+        },
+      });
+
+      assert.equal(result.status, 1);
+      assert.equal(result.stdout, "");
+      assert.equal(result.stderr, "");
+
+      const logFiles = await readdir(join(cwd, ".omx", "logs"));
+      assert.equal(logFiles.some((name) => /^native-hook-\d{4}-\d{2}-\d{2}\.jsonl$/.test(name)), true);
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
   it("maps Codex events onto OMX logical surfaces", () => {
     assert.equal(mapCodexHookEventToOmxEvent("SessionStart"), "session-start");
     assert.equal(mapCodexHookEventToOmxEvent("UserPromptSubmit"), "keyword-detector");
     assert.equal(mapCodexHookEventToOmxEvent("PreToolUse"), "pre-tool-use");
     assert.equal(mapCodexHookEventToOmxEvent("PostToolUse"), "post-tool-use");
+    assert.equal(mapCodexHookEventToOmxEvent("PreCompact"), "pre-compact");
+    assert.equal(mapCodexHookEventToOmxEvent("PostCompact"), "post-compact");
     assert.equal(mapCodexHookEventToOmxEvent("Stop"), "stop");
   });
 
+
+
+  it("returns bounded wiki context for PreCompact", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-precompact-"));
+    try {
+      writePage(cwd, {
+        filename: "architecture.md",
+        frontmatter: {
+          title: "Architecture",
+          tags: ["architecture"],
+          created: "2026-05-08T00:00:00.000Z",
+          updated: "2026-05-08T00:00:00.000Z",
+          sources: [],
+          links: [],
+          category: "architecture",
+          confidence: "high",
+          schemaVersion: WIKI_SCHEMA_VERSION,
+        },
+        content: "\n# Architecture\n\nCompaction-relevant architecture note.\n",
+      });
+
+      const result = await dispatchCodexNativeHook({
+        hook_event_name: "PreCompact",
+        cwd,
+        session_id: "sess-precompact",
+      });
+
+      assert.equal(result.hookEventName, "PreCompact");
+      assert.equal(result.omxEventName, "pre-compact");
+      const additionalContext = (result.outputJson as { hookSpecificOutput?: { additionalContext?: string } } | null)
+        ?.hookSpecificOutput?.additionalContext ?? "";
+      assert.match(additionalContext, /Wiki: 1 pages/);
+      assert.match(additionalContext, /architecture/);
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it("returns a PostCompact nudge to write compaction artifacts to omx_wiki", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-postcompact-"));
+    try {
+      const result = await dispatchCodexNativeHook({
+        hook_event_name: "PostCompact",
+        cwd,
+        session_id: "sess-postcompact",
+      });
+
+      assert.equal(result.hookEventName, "PostCompact");
+      assert.equal(result.omxEventName, "post-compact");
+      const additionalContext = (result.outputJson as { hookSpecificOutput?: { additionalContext?: string } } | null)
+        ?.hookSpecificOutput?.additionalContext ?? "";
+      assert.match(additionalContext, /PostCompact Nudge/);
+      assert.match(additionalContext, /omx_wiki/);
+      assert.match(additionalContext, /compaction artifacts/);
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
   it("writes SessionStart state against the long-lived session owner pid and injects environment context", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-session-start-"));
     try {
@@ -1032,7 +1166,12 @@ describe("codex native hook dispatch", () => {
       assert.ok(result.outputJson, "UserPromptSubmit should emit developer context");
       assert.match(JSON.stringify(result.outputJson), /skill: ralplan activated and initial state initialized at \.omx\/state\/sessions\/sess-1\/ralplan-state\.json; write subsequent updates via omx_state MCP\./);
 
-      const statePath = join(cwd, ".omx", "state", "skill-active-state.json");
+      assert.equal(
+        existsSync(join(cwd, ".omx", "state", "skill-active-state.json")),
+        false,
+        "session-scoped keyword activation should not write root skill-active-state.json",
+      );
+      const statePath = join(cwd, ".omx", "state", "sessions", "sess-1", "skill-active-state.json");
       assert.equal(existsSync(statePath), true);
       const state = JSON.parse(await readFile(statePath, "utf-8")) as {
         skill?: string;
@@ -8409,6 +8548,167 @@ exit 0
     }
   });
 
+  it("clears stale root skill-active state when current session ralplan is terminal", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-stale-root-skill-terminal-"));
+    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, "ralplan-state.json"), {
+        active: false,
+        mode: "ralplan",
+        current_phase: "completed",
+        lifecycle_outcome: "finished",
+        run_outcome: "finish",
+        final_artifact: "proposed_plan",
+      });
+      await writeJson(join(stateDir, "skill-active-state.json"), {
+        active: true,
+        skill: "ultrawork",
+        phase: "planning",
+        source: "keyword-detector",
+        active_skills: [
+          { skill: "ultrawork", phase: "planning", active: true },
+        ],
+      });
+
+      const result = await dispatchCodexNativeHook(
+        {
+          hook_event_name: "Stop",
+          cwd,
+          session_id: sessionId,
+          thread_id: "thread-stop-terminal-ralplan",
+          turn_id: "turn-stop-terminal-ralplan-1",
+          last_assistant_message: "Done.",
+        },
+        { cwd },
+      );
+
+      assert.equal(result.omxEventName, "stop");
+      assert.equal(result.outputJson, null);
+
+      const rootSkillState = JSON.parse(
+        await readFile(join(stateDir, "skill-active-state.json"), "utf-8"),
+      ) as { active?: boolean; active_skills?: unknown[]; reconciliation_reason?: string };
+      assert.equal(rootSkillState.active, false);
+      assert.deepEqual(rootSkillState.active_skills, []);
+      assert.equal(rootSkillState.reconciliation_reason, "stop_hook_session_state_terminal");
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it("preserves legitimate session-scoped ultrawork blocking while reconciling root skill-active state", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-active-root-skill-session-mode-"));
+    try {
+      const stateDir = join(cwd, ".omx", "state");
+      const sessionId = "sess-stop-active-ultrawork";
+      await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+      await writeJson(join(stateDir, "session.json"), { session_id: sessionId });
+      await writeJson(join(stateDir, "sessions", sessionId, "ultrawork-state.json"), {
+        active: true,
+        mode: "ultrawork",
+        current_phase: "executing",
+        session_id: sessionId,
+      });
+      await writeJson(join(stateDir, "skill-active-state.json"), {
+        active: true,
+        skill: "ultrawork",
+        phase: "planning",
+        source: "keyword-detector",
+        active_skills: [
+          { skill: "ultrawork", phase: "planning", active: true, session_id: sessionId },
+        ],
+      });
+
+      const result = await dispatchCodexNativeHook(
+        {
+          hook_event_name: "Stop",
+          cwd,
+          session_id: sessionId,
+          thread_id: "thread-stop-active-ultrawork",
+          turn_id: "turn-stop-active-ultrawork-1",
+        },
+        { cwd },
+      );
+
+      assert.equal(result.omxEventName, "stop");
+      assert.deepEqual(result.outputJson, {
+        decision: "block",
+        reason: "OMX ultrawork is still active (phase: executing); continue the task and gather fresh verification evidence before stopping.",
+        stopReason: "ultrawork_executing",
+        systemMessage: "OMX ultrawork is still active (phase: executing).",
+      });
+
+      const rootSkillState = JSON.parse(
+        await readFile(join(stateDir, "skill-active-state.json"), "utf-8"),
+      ) as { active?: boolean; active_skills?: Array<{ skill?: string }> };
+      assert.equal(rootSkillState.active, true);
+      assert.deepEqual(rootSkillState.active_skills?.map((entry) => entry.skill), ["ultrawork"]);
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it("reconciles stale root skill-active state under OMX_ROOT boxed state", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-boxed-source-"));
+    const omxRoot = await mkdtemp(join(tmpdir(), "omx-native-hook-stop-boxed-root-"));
+    const previousOmxRoot = process.env.OMX_ROOT;
+    try {
+      process.env.OMX_ROOT = omxRoot;
+      const stateDir = join(omxRoot, ".omx", "state");
+      const sourceStateDir = join(cwd, ".omx", "state");
+      const sessionId = "sess-stop-boxed-ralplan";
+      await mkdir(join(stateDir, "sessions", sessionId), { recursive: true });
+      await writeJson(join(stateDir, "session.json"), { session_id: sessionId });
+      await writeJson(join(stateDir, "sessions", sessionId, "ralplan-state.json"), {
+        active: false,
+        mode: "ralplan",
+        current_phase: "completed",
+        lifecycle_outcome: "finished",
+        run_outcome: "finish",
+      });
+      await writeJson(join(stateDir, "skill-active-state.json"), {
+        active: true,
+        skill: "ultrawork",
+        phase: "planning",
+        source: "keyword-detector",
+        active_skills: [
+          { skill: "ultrawork", phase: "planning", active: true },
+        ],
+      });
+
+      const result = await dispatchCodexNativeHook(
+        {
+          hook_event_name: "Stop",
+          cwd,
+          session_id: sessionId,
+          thread_id: "thread-stop-boxed-ralplan",
+          turn_id: "turn-stop-boxed-ralplan-1",
+          last_assistant_message: "Done.",
+        },
+        { cwd },
+      );
+
+      assert.equal(result.omxEventName, "stop");
+      assert.equal(result.outputJson, null);
+
+      const boxedRootSkillState = JSON.parse(
+        await readFile(join(stateDir, "skill-active-state.json"), "utf-8"),
+      ) as { active?: boolean; active_skills?: unknown[]; reconciliation_reason?: string };
+      assert.equal(boxedRootSkillState.active, false);
+      assert.deepEqual(boxedRootSkillState.active_skills, []);
+      assert.equal(boxedRootSkillState.reconciliation_reason, "stop_hook_session_state_terminal");
+      assert.equal(existsSync(join(sourceStateDir, "skill-active-state.json")), false);
+    } finally {
+      if (previousOmxRoot === undefined) delete process.env.OMX_ROOT;
+      else process.env.OMX_ROOT = previousOmxRoot;
+      await rm(cwd, { recursive: true, force: true });
+      await rm(omxRoot, { recursive: true, force: true });
+    }
+  });
+
   it("auto-continues native Stop for permission-seeking prompts even outside OMX runtime", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "omx-native-hook-auto-nudge-plain-session-"));
     try {

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

@@ -0,0 +1,73 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  getScopedStatePath,
+  readScopedJsonIfExists,
+  resolveScopedStateDir,
+  writeScopedJson,
+} from '../notify-hook/state-io.js';
+
+describe('notify-hook state I/O session authority', () => {
+  it('uses an explicit session id before the current session pointer', async () => {
+    const wd = await mkdtemp(join(tmpdir(), 'omx-notify-state-io-'));
+    try {
+      const stateDir = join(wd, '.omx', 'state');
+      await mkdir(join(stateDir, 'sessions', 'sess-current'), { recursive: true });
+      await mkdir(join(stateDir, 'sessions', 'sess-explicit'), { recursive: true });
+      await writeFile(
+        join(stateDir, 'session.json'),
+        JSON.stringify({ session_id: 'sess-current', cwd: wd }, null, 2),
+        'utf-8',
+      );
+
+      assert.equal(
+        await resolveScopedStateDir(stateDir, 'sess-explicit'),
+        join(stateDir, 'sessions', 'sess-explicit'),
+      );
+      assert.equal(
+        await getScopedStatePath(stateDir, 'hud-state.json', 'sess-explicit'),
+        join(stateDir, 'sessions', 'sess-explicit', 'hud-state.json'),
+      );
+
+      await writeScopedJson(stateDir, 'hud-state.json', 'sess-explicit', { turn_count: 3 });
+      const explicitHud = JSON.parse(
+        await readFile(join(stateDir, 'sessions', 'sess-explicit', 'hud-state.json'), 'utf-8'),
+      ) as { turn_count?: unknown };
+      assert.equal(explicitHud.turn_count, 3);
+    } finally {
+      await rm(wd, { recursive: true, force: true });
+    }
+  });
+
+  it('does not read current-session data when an explicit session has no state file', async () => {
+    const wd = await mkdtemp(join(tmpdir(), 'omx-notify-state-io-missing-'));
+    try {
+      const stateDir = join(wd, '.omx', 'state');
+      await mkdir(join(stateDir, 'sessions', 'sess-current'), { recursive: true });
+      await writeFile(
+        join(stateDir, 'session.json'),
+        JSON.stringify({ session_id: 'sess-current', cwd: wd }, null, 2),
+        'utf-8',
+      );
+      await writeFile(
+        join(stateDir, 'sessions', 'sess-current', 'auto-nudge-state.json'),
+        JSON.stringify({ count: 9 }, null, 2),
+        'utf-8',
+      );
+
+      const value = await readScopedJsonIfExists(
+        stateDir,
+        'auto-nudge-state.json',
+        'sess-explicit',
+        null,
+      );
+      assert.equal(value, null);
+    } finally {
+      await rm(wd, { recursive: true, force: true });
+    }
+  });
+});

package/src/scripts/codex-execution-surface.ts

@@ -6,6 +6,8 @@ type CodexHookEventName =
   | "PreToolUse"
   | "PostToolUse"
   | "UserPromptSubmit"
+  | "PreCompact"
+  | "PostCompact"
   | "Stop";
 
 type CodexHookPayload = Record<string, unknown>;