oh-my-codex 0.18.0 → 0.18.2

package/src/scripts/__tests__/docs-site-contract.test.ts

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { describe, it } from 'node:test';
+
+const root = process.cwd();
+
+function read(path: string): string {
+  return readFileSync(join(root, path), 'utf-8');
+}
+
+const docsPages = ['docs/index.html', 'docs/getting-started.html', 'docs/agents.html', 'docs/skills.html', 'docs/integrations.html'];
+
+describe('public docs site contract', () => {
+  it('keeps every repo-owned docs HTML page linked to an existing stylesheet', () => {
+    for (const page of docsPages) {
+      const content = read(page);
+      const hrefs = [...content.matchAll(/<link\s+[^>]*rel="stylesheet"[^>]*href="([^"]+)"/g)].map((match) => match[1]);
+      assert.ok(hrefs.length > 0, `${page} should link a stylesheet`);
+      for (const href of hrefs) {
+        assert.ok(!href.startsWith('http'), `${page} should use a repo-owned relative stylesheet, got ${href}`);
+        const resolved = join(root, dirname(page), href);
+        assert.ok(existsSync(resolved), `${page} stylesheet must exist: ${href}`);
+      }
+    }
+  });
+
+  it('defines CSS for the layout classes used by the static docs pages', () => {
+    const css = read('docs/style.css');
+    assert.match(css, /(^|\n)\.grid\s*,\s*\n\.card-grid\s*\{/, 'docs/style.css must style .grid cards used by docs pages');
+    for (const page of docsPages) {
+      const content = read(page);
+      if (content.includes('class="grid"')) {
+        assert.match(css, /(^|\n)\.grid\s*,/, `${page} uses .grid, so docs/style.css must style it`);
+      }
+    }
+  });
+
+  it('documents research workflow boundaries on the public skills page', () => {
+    const content = read('docs/skills.html');
+    assert.match(content, /Research and Planning Boundaries/);
+    assert.match(content, /\$best-practice-research[\s\S]*ordinary pre-planning wrapper/);
+    assert.match(content, /\$autoresearch[\s\S]*bounded validator-gated research deliverable/);
+    assert.match(content, /\$autoresearch-goal[\s\S]*Codex goal-mode version/);
+    assert.match(content, /Autoresearch findings gathered before planning should feed into <code>\$ralplan<\/code> as evidence/);
+  });
+});

package/src/scripts/__tests__/notify-dispatcher.test.ts

@@ -6,16 +6,145 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 
-function runDispatcher(metadataPath: string): void {
+function runDispatcher(
+	metadataPath: string,
+	payload: Record<string, unknown> = { type: "test" },
+	env: NodeJS.ProcessEnv = {},
+): void {
 	const dispatcherScript = join(process.cwd(), "dist", "scripts", "notify-dispatcher.js");
 	const result = spawnSync(
 		process.execPath,
-		[dispatcherScript, "--metadata", metadataPath, JSON.stringify({ type: "test" })],
-		{ encoding: "utf-8", windowsHide: true },
+		[dispatcherScript, "--metadata", metadataPath, JSON.stringify(payload)],
+		{ encoding: "utf-8", env: { ...process.env, ...env }, windowsHide: true },
 	);
 	assert.equal(result.status, 0, result.stderr || result.stdout);
 }
 
+describe("notify dispatcher turn-ended storm guard", () => {
+	it("coalesces rapid turn-ended dispatcher callbacks to one OMX notify run", () => {
+		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-rapid-"));
+		try {
+			const omxMarker = join(wd, "omx-ran");
+			const omxHook = join(wd, "current-notify-hook.js");
+			writeFileSync(omxHook, `import { appendFileSync } from "node:fs"; appendFileSync(${JSON.stringify(omxMarker)}, "omx|");\n`);
+			const metadataPath = join(wd, "notify-dispatch.json");
+			writeFileSync(metadataPath, JSON.stringify({ managedBy: "oh-my-codex", version: 1, omxNotify: [process.execPath, omxHook] }));
+
+			for (let index = 0; index < 10; index += 1) {
+				runDispatcher(metadataPath, { type: "agent-turn-complete", thread_id: "desktop-thread", turn_id: `queued-${index}` });
+			}
+
+			assert.equal(readFileSync(omxMarker, "utf-8"), "omx|");
+		} finally {
+			rmSync(wd, { recursive: true, force: true });
+		}
+	});
+
+	it("allows separate turn-ended identities to dispatch independently", () => {
+		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-identities-"));
+		try {
+			const omxMarker = join(wd, "omx-ran");
+			const omxHook = join(wd, "current-notify-hook.js");
+			writeFileSync(omxHook, `import { appendFileSync } from "node:fs"; appendFileSync(${JSON.stringify(omxMarker)}, "omx|");\n`);
+			const metadataPath = join(wd, "notify-dispatch.json");
+			writeFileSync(metadataPath, JSON.stringify({ managedBy: "oh-my-codex", version: 1, omxNotify: [process.execPath, omxHook] }));
+
+			runDispatcher(metadataPath, { type: "agent-turn-complete", thread_id: "desktop-thread-a", turn_id: "queued-a" });
+			runDispatcher(metadataPath, { type: "agent-turn-complete", thread_id: "desktop-thread-b", turn_id: "queued-b" });
+
+			assert.equal(readFileSync(omxMarker, "utf-8"), "omx|omx|");
+		} finally {
+			rmSync(wd, { recursive: true, force: true });
+		}
+	});
+
+	it("coalesces same-identity turn-ended callbacks after a slow notify hook completes", () => {
+		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-slow-"));
+		try {
+			const omxMarker = join(wd, "omx-ran");
+			const omxHook = join(wd, "current-notify-hook.js");
+			writeFileSync(omxHook, `import { appendFileSync } from "node:fs"; await new Promise((resolve) => setTimeout(resolve, 1500)); appendFileSync(${JSON.stringify(omxMarker)}, "omx|");\n`);
+			const metadataPath = join(wd, "notify-dispatch.json");
+			writeFileSync(metadataPath, JSON.stringify({ managedBy: "oh-my-codex", version: 1, omxNotify: [process.execPath, omxHook] }));
+			const env = { OMX_NOTIFY_DISPATCH_MIN_INTERVAL_MS: "1000" };
+
+			runDispatcher(metadataPath, { type: "agent-turn-complete", thread_id: "slow-thread", turn_id: "queued-a" }, env);
+			runDispatcher(metadataPath, { type: "agent-turn-complete", thread_id: "slow-thread", turn_id: "queued-b" }, env);
+
+			assert.equal(readFileSync(omxMarker, "utf-8"), "omx|");
+		} finally {
+			rmSync(wd, { recursive: true, force: true });
+		}
+	});
+
+	it("prunes expired turn-ended identity guard state", () => {
+		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-prune-"));
+		try {
+			const omxMarker = join(wd, "omx-ran");
+			const omxHook = join(wd, "current-notify-hook.js");
+			writeFileSync(omxHook, `import { appendFileSync } from "node:fs"; appendFileSync(${JSON.stringify(omxMarker)}, "omx|");\n`);
+			const metadataPath = join(wd, "notify-dispatch.json");
+			const guardPath = join(wd, "notify-dispatch.guard.json");
+			writeFileSync(metadataPath, JSON.stringify({ managedBy: "oh-my-codex", version: 1, omxNotify: [process.execPath, omxHook] }));
+			writeFileSync(guardPath, JSON.stringify({
+				lastDispatchByIdentity: {
+					"thread_id:expired": Date.now() - 11 * 60_000,
+					"thread_id:recent": Date.now(),
+				},
+			}));
+
+			runDispatcher(metadataPath, { type: "agent-turn-complete", thread_id: "fresh-thread", turn_id: "queued-fresh" });
+
+			const guard = JSON.parse(readFileSync(guardPath, "utf-8"));
+			assert.equal("thread_id:expired" in guard.lastDispatchByIdentity, false);
+			assert.equal(typeof guard.lastDispatchByIdentity["thread_id:recent"], "number");
+			assert.equal(typeof guard.lastDispatchByIdentity["thread_id:fresh-thread"], "number");
+		} finally {
+			rmSync(wd, { recursive: true, force: true });
+		}
+	});
+
+	it("drops stale turn-ended dispatcher callbacks before spawning notify hooks", () => {
+		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-stale-event-"));
+		try {
+			const omxMarker = join(wd, "omx-ran");
+			const omxHook = join(wd, "current-notify-hook.js");
+			writeFileSync(omxHook, `import { writeFileSync } from "node:fs"; writeFileSync(${JSON.stringify(omxMarker)}, "ran");\n`);
+			const metadataPath = join(wd, "notify-dispatch.json");
+			writeFileSync(metadataPath, JSON.stringify({ managedBy: "oh-my-codex", version: 1, omxNotify: [process.execPath, omxHook] }));
+
+			runDispatcher(metadataPath, {
+				type: "agent-turn-complete",
+				timestamp: new Date(Date.now() - 10 * 60_000).toISOString(),
+				thread_id: "desktop-thread",
+				turn_id: "stale-turn",
+			});
+
+			assert.equal(existsSync(omxMarker), false);
+		} finally {
+			rmSync(wd, { recursive: true, force: true });
+		}
+	});
+
+	it("preserves normal non-turn notify dispatches", () => {
+		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-normal-"));
+		try {
+			const omxMarker = join(wd, "omx-ran");
+			const omxHook = join(wd, "current-notify-hook.js");
+			writeFileSync(omxHook, `import { appendFileSync } from "node:fs"; appendFileSync(${JSON.stringify(omxMarker)}, "omx|");\n`);
+			const metadataPath = join(wd, "notify-dispatch.json");
+			writeFileSync(metadataPath, JSON.stringify({ managedBy: "oh-my-codex", version: 1, omxNotify: [process.execPath, omxHook] }));
+
+			runDispatcher(metadataPath, { type: "test", id: 1 });
+			runDispatcher(metadataPath, { type: "test", id: 2 });
+
+			assert.equal(readFileSync(omxMarker, "utf-8"), "omx|omx|");
+		} finally {
+			rmSync(wd, { recursive: true, force: true });
+		}
+	});
+});
+
 describe("notify dispatcher previousNotify guard", () => {
 	it("skips stale OMX-managed previousNotify dispatcher entries", () => {
 		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-stale-"));

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

@@ -147,4 +147,71 @@ describe('run-test-files diagnostics', () => {
       rmSync(wd, { recursive: true, force: true });
     }
   });
+
+  it('sanitizes live OMX runtime state env from child test processes by default', () => {
+    const wd = mkdtempSync(join(tmpdir(), 'omx-run-test-files-'));
+    try {
+      const testsDir = join(wd, '__tests__');
+      mkdirSync(testsDir, { recursive: true });
+      writeFileSync(
+        join(testsDir, 'env-clean.test.js'),
+        [
+          "import { test } from 'node:test';",
+          "import assert from 'node:assert/strict';",
+          "test('runtime env is clean', () => {",
+          "  assert.equal(process.env.OMX_ROOT, undefined);",
+          "  assert.equal(process.env.OMX_STATE_ROOT, undefined);",
+          "  assert.equal(process.env.OMX_TEAM_STATE_ROOT, undefined);",
+          "  assert.equal(process.env.OMX_SESSION_ID, undefined);",
+          "  assert.equal(process.env.CODEX_SESSION_ID, undefined);",
+          "  assert.equal(process.env.SESSION_ID, undefined);",
+          "});",
+          '',
+        ].join('\n'),
+      );
+
+      const result = runCompiledRunner(wd, {
+        OMX_ROOT: '/tmp/live-omx-root',
+        OMX_STATE_ROOT: '/tmp/live-omx-state-root',
+        OMX_TEAM_STATE_ROOT: '/tmp/live-team-state-root',
+        OMX_SESSION_ID: 'live-omx-session',
+        CODEX_SESSION_ID: 'live-codex-session',
+        SESSION_ID: 'live-shell-session',
+      });
+
+      assert.equal(result.status, 0, result.stderr || result.stdout);
+    } finally {
+      rmSync(wd, { recursive: true, force: true });
+    }
+  });
+
+  it('can preserve live OMX runtime state env for explicit diagnostics', () => {
+    const wd = mkdtempSync(join(tmpdir(), 'omx-run-test-files-'));
+    try {
+      const testsDir = join(wd, '__tests__');
+      mkdirSync(testsDir, { recursive: true });
+      writeFileSync(
+        join(testsDir, 'env-preserve.test.js'),
+        [
+          "import { test } from 'node:test';",
+          "import assert from 'node:assert/strict';",
+          "test('runtime env is preserved', () => {",
+          "  assert.equal(process.env.OMX_ROOT, '/tmp/live-omx-root');",
+          "  assert.equal(process.env.OMX_SESSION_ID, 'live-omx-session');",
+          "});",
+          '',
+        ].join('\n'),
+      );
+
+      const result = runCompiledRunner(wd, {
+        OMX_NODE_TEST_PRESERVE_RUNTIME_ENV: '1',
+        OMX_ROOT: '/tmp/live-omx-root',
+        OMX_SESSION_ID: 'live-omx-session',
+      });
+
+      assert.equal(result.status, 0, result.stderr || result.stdout);
+    } finally {
+      rmSync(wd, { recursive: true, force: true });
+    }
+  });
 });

package/src/scripts/__tests__/smoke-packed-install.test.ts

@@ -7,10 +7,13 @@ import { test } from 'node:test';
 import {
   ensureRepoDependencies,
   hasUsableNodeModules,
+  buildNativeHookSmokePayload,
+  PACKED_INSTALL_NATIVE_HOOK_SMOKE_EVENTS,
   PACKED_INSTALL_SMOKE_CORE_COMMANDS,
   parseNpmPackJsonOutput,
   resolveGitCommonDir,
   resolveReusableNodeModulesSource,
+  validateHookStdout,
 } from '../smoke-packed-install.js';
 
 test('packed install smoke stays limited to boot + core commands', () => {
@@ -30,6 +33,34 @@ test('packed install smoke stays limited to boot + core commands', () => {
   );
 });
 
+test('packed install smoke covers every installed native hook event with minimal payloads', () => {
+  assert.deepEqual(PACKED_INSTALL_NATIVE_HOOK_SMOKE_EVENTS, [
+    'SessionStart',
+    'PreToolUse',
+    'PostToolUse',
+    'UserPromptSubmit',
+    'PreCompact',
+    'PostCompact',
+    'Stop',
+  ]);
+
+  for (const eventName of PACKED_INSTALL_NATIVE_HOOK_SMOKE_EVENTS) {
+    const payload = buildNativeHookSmokePayload(eventName, '/tmp/omx-packed-hook-smoke');
+    assert.equal(payload.hook_event_name, eventName);
+    assert.equal(typeof payload.session_id, 'string');
+    assert.equal(payload.cwd, '/tmp/omx-packed-hook-smoke');
+  }
+});
+
+test('packed install native hook stdout validation allows empty or JSON output only', () => {
+  assert.doesNotThrow(() => validateHookStdout('PostCompact', ''));
+  assert.doesNotThrow(() => validateHookStdout('Stop', '{}\n'));
+  assert.throws(
+    () => validateHookStdout('UserPromptSubmit', '{not json'),
+    /native hook UserPromptSubmit emitted invalid JSON stdout/,
+  );
+});
+
 test('parseNpmPackJsonOutput ignores prepack logs before npm pack JSON', () => {
   const parsed = parseNpmPackJsonOutput([
     '[sync-plugin-mirror] synced 29 canonical skill directories and plugin metadata',

package/src/scripts/__tests__/verify-native-agents.test.ts

@@ -53,7 +53,7 @@ describe("verify-native-agents", () => {
       ]),
       definitions: { executor: definition, "style-reviewer": { ...definition, name: "style-reviewer" } },
       promptNames: new Set(["executor", "style-reviewer", "explore-harness"]),
-      pluginManifest: { skills: "./skills/" },
+      pluginManifest: { skills: "./skills/", hooks: "./hooks/hooks.json" },
     });
 
     assert.deepEqual(result.installableAgentNames, ["executor"]);
@@ -174,15 +174,35 @@ describe("verify-native-agents", () => {
     );
   });
 
-  it("fails if the plugin manifest declares setup-owned native-agent fields", async () => {
+  it("allows plugin-scoped hooks but fails if the plugin manifest declares setup-owned native-agent fields", async () => {
     await rejectsWithCode("native_agent_plugin_boundary_violation", () =>
       verifyNativeAgents({
         manifest: manifest([{ name: "executor", category: "build", status: "active" }]),
         definitions: { executor: definition },
         promptNames: new Set(["executor"]),
-        pluginManifest: { agents: "./agents/" },
+        pluginManifest: { agents: "./agents/", hooks: "./hooks/hooks.json" },
       }),
     );
+
+    await rejectsWithCode("native_agent_plugin_boundary_violation", () =>
+      verifyNativeAgents({
+        manifest: manifest([{ name: "executor", category: "build", status: "active" }]),
+        definitions: { executor: definition },
+        promptNames: new Set(["executor"]),
+        pluginManifest: { prompts: "./prompts/" },
+      }),
+    );
+  });
+
+  it("allows plugin-scoped lifecycle hooks without treating them as native agents", async () => {
+    const result = await verifyNativeAgents({
+      manifest: manifest([{ name: "executor", category: "build", status: "active" }]),
+      definitions: { executor: definition },
+      promptNames: new Set(["executor"]),
+      pluginManifest: { hooks: "./hooks/hooks.json" },
+    });
+
+    assert.deepEqual(result.installableAgentNames, ["executor"]);
   });
 
   it("keeps merged prompt-backed agents out of the installable set", () => {

package/src/scripts/cleanup-explore-harness.ts

@@ -12,6 +12,7 @@ for (const path of [
   join(root, 'bin', 'omx-explore-harness.exe'),
   join(root, 'bin', 'omx-explore-harness.meta.json'),
   join(root, 'bin', 'native'),
+  join(root, 'crates', 'omx-sparkshell', '.omx'),
 ]) {
   await rm(path, { recursive: true, force: true });
 }