oh-my-codex 0.18.6 → 0.18.8

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

@@ -1,9 +1,10 @@
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
 import { readdirSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
 const DEFAULT_TEST_TIMEOUT_MS = 0;
 const DEFAULT_RUNNER_TIMEOUT_MS = 30 * 60 * 1_000;
+const DEFAULT_FORCE_EXIT_GRACE_MS = 30_000;
 const DEFAULT_CI_TEST_CONCURRENCY = 1;
 const RUNTIME_STATE_ENV_KEYS = [
   'OMX_ROOT',
@@ -47,6 +48,10 @@ function parseTimeoutMs(value: string | undefined, defaultTimeoutMs: number): nu
   return Math.floor(parsed);
 }
 
+function isWindows(): boolean {
+  return process.platform === 'win32';
+}
+
 function parseTestConcurrency(env: NodeJS.ProcessEnv): number | undefined {
   const rawValue = env.OMX_NODE_TEST_CONCURRENCY;
   if (rawValue) {
@@ -74,6 +79,7 @@ if (files.length === 0) {
 
 const testTimeoutMs = parseTimeoutMs(process.env.OMX_NODE_TEST_TIMEOUT_MS, DEFAULT_TEST_TIMEOUT_MS);
 const runnerTimeoutMs = parseTimeoutMs(process.env.OMX_NODE_TEST_RUNNER_TIMEOUT_MS, DEFAULT_RUNNER_TIMEOUT_MS);
+const forceExitGraceMs = parseTimeoutMs(process.env.OMX_NODE_TEST_FORCE_EXIT_GRACE_MS, DEFAULT_FORCE_EXIT_GRACE_MS);
 const testConcurrency = parseTestConcurrency(process.env);
 const forceExit = parseBooleanEnv(process.env.OMX_NODE_TEST_FORCE_EXIT);
 const testArgs = ['--test'];
@@ -84,7 +90,7 @@ if (testConcurrency) {
   testArgs.push(`--test-concurrency=${testConcurrency}`);
 }
 if (forceExit) {
-  testArgs.push('--test-force-exit');
+  testArgs.push('--test-force-exit', '--test-reporter=tap');
 }
 testArgs.push(...files);
 
@@ -92,7 +98,7 @@ console.error(
   `[run-test-files] running ${files.length} test file(s) from ${targets.join(', ')}${
     testTimeoutMs > 0 ? ` with per-test timeout ${testTimeoutMs}ms` : ' with per-test timeout disabled'
   }${testConcurrency ? `, test concurrency ${testConcurrency}` : ', default test concurrency'}${
-    forceExit ? ', force exit enabled' : ', force exit disabled'
+    forceExit ? `, force exit enabled with ${forceExitGraceMs}ms completion grace` : ', force exit disabled'
   }${runnerTimeoutMs > 0 ? `, and runner timeout ${runnerTimeoutMs}ms` : ', and runner timeout disabled'}`,
 );
 
@@ -105,26 +111,190 @@ if (!parseBooleanEnv(process.env.OMX_NODE_TEST_PRESERVE_RUNTIME_ENV)) {
   }
 }
 
-const result = spawnSync(process.execPath, testArgs, {
-  stdio: 'inherit',
-  env: childEnv,
-  timeout: runnerTimeoutMs > 0 ? runnerTimeoutMs : undefined,
-  killSignal: 'SIGTERM',
-});
+function reportAbnormalExit(signal: NodeJS.Signals | null, errorMessage?: string): void {
+  if (errorMessage) {
+    console.error(`[run-test-files] node --test error: ${errorMessage}`);
+  }
+  console.error(
+    `[run-test-files] node --test did not exit normally${signal ? ` (signal: ${signal})` : ''}. `
+      + `Roots: ${targets.join(', ')}. Test files: ${files.length}. `
+      + `Per-test timeout: ${testTimeoutMs > 0 ? `${testTimeoutMs}ms` : 'disabled'}. `
+      + `Test concurrency: ${testConcurrency ?? 'default'}. `
+      + `Force exit: ${forceExit ? 'enabled' : 'disabled'}. `
+      + `Runner timeout: ${runnerTimeoutMs > 0 ? `${runnerTimeoutMs}ms` : 'disabled'}.`,
+  );
+}
 
-if (typeof result.status === 'number') {
-  process.exit(result.status);
+function signalChild(child: ChildProcess, signal: NodeJS.Signals): void {
+  try {
+    if (!isWindows() && child.pid) {
+      process.kill(-child.pid, signal);
+    } else {
+      child.kill(signal);
+    }
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {
+      // Ignore kill races. The child might have exited between detection and termination.
+    }
+  }
 }
 
-if (result.error) {
-  console.error(`[run-test-files] node --test error: ${result.error.message}`);
+function terminateChild(child: ChildProcess): void {
+  signalChild(child, 'SIGTERM');
+  signalChild(child, 'SIGKILL');
+}
+
+function runWithCompletionForceExit(): void {
+  let finished = false;
+  let sawFailure = false;
+  let lastTapOk = 0;
+  let tapTests: number | undefined;
+  let tapPass: number | undefined;
+  let tapFail = 0;
+  let tapCancelled = 0;
+  let completedFromSummary = false;
+  let completionTimer: NodeJS.Timeout | undefined;
+  let runnerTimer: NodeJS.Timeout | undefined;
+  let stdoutRemainder = '';
+  let stderrRemainder = '';
+
+  const child = spawn(process.execPath, testArgs, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: childEnv,
+    detached: !isWindows(),
+  });
+
+  function finish(exitCode: number, reason: string): void {
+    if (finished) return;
+    finished = true;
+    if (completionTimer) clearTimeout(completionTimer);
+    if (runnerTimer) clearTimeout(runnerTimer);
+    console.error(`[run-test-files] ${reason}; exiting with status ${exitCode}`);
+    terminateChild(child);
+    child.stdout?.destroy();
+    child.stderr?.destroy();
+    child.unref();
+    process.exit(exitCode);
+  }
+
+  function markFailure(): void {
+    sawFailure = true;
+    if (completionTimer) {
+      clearTimeout(completionTimer);
+      completionTimer = undefined;
+    }
+  }
+
+  function armCompletionTimer(reason: string): void {
+    if (sawFailure) return;
+    if (completionTimer) clearTimeout(completionTimer);
+    completionTimer = setTimeout(() => {
+      if (sawFailure) return;
+      finish(0, reason);
+    }, forceExitGraceMs);
+  }
+
+  function sawCleanTapSummary(): boolean {
+    if (tapTests === undefined || tapPass === undefined) return false;
+    return tapTests === tapPass && tapFail === 0 && tapCancelled === 0;
+  }
+
+  function parseTapLine(line: string): void {
+    if (/^(?:not ok|Bail out!)/.test(line)) {
+      markFailure();
+      return;
+    }
+
+    const summary = line.match(/^# (tests|pass|fail|cancelled) (\d+)$/);
+    if (summary) {
+      const count = Number(summary[2]);
+      if (summary[1] === 'tests') tapTests = count;
+      if (summary[1] === 'pass') tapPass = count;
+      if (summary[1] === 'fail') tapFail = count;
+      if (summary[1] === 'cancelled') tapCancelled = count;
+      if ((summary[1] === 'fail' || summary[1] === 'cancelled') && count > 0) markFailure();
+      return;
+    }
+
+    const ok = line.match(/^ok (\d+)\b/);
+    if (ok) {
+      lastTapOk = Number(ok[1]);
+      if (lastTapOk >= files.length) {
+        armCompletionTimer(`force-exit completion grace elapsed after TAP ok ${lastTapOk} with no later failures`);
+      }
+      return;
+    }
+
+    const plan = line.match(/^1\.\.(\d+)$/);
+    if (plan && Number(plan[1]) === lastTapOk && !sawFailure) {
+      armCompletionTimer(`force-exit completion grace elapsed after TAP plan ${line}`);
+      return;
+    }
+
+    if (/^# duration_ms /.test(line) && sawCleanTapSummary()) {
+      completedFromSummary = true;
+      armCompletionTimer('force-exit completion grace elapsed after clean TAP summary');
+    }
+  }
+
+  function handleOutput(chunk: Buffer, stream: NodeJS.WriteStream, isStdout: boolean): void {
+    stream.write(chunk);
+    const text = chunk.toString('utf8');
+    let combined = (isStdout ? stdoutRemainder : stderrRemainder) + text;
+    const lines = combined.split(/\r?\n/);
+    combined = lines.pop() ?? '';
+    if (isStdout) {
+      stdoutRemainder = combined;
+    } else {
+      stderrRemainder = combined;
+    }
+    for (const line of lines) parseTapLine(line);
+  }
+
+  child.stdout?.on('data', (chunk: Buffer) => handleOutput(chunk, process.stdout, true));
+  child.stderr?.on('data', (chunk: Buffer) => handleOutput(chunk, process.stderr, false));
+
+  child.on('error', (error) => {
+    reportAbnormalExit(null, error.message);
+    finish(1, 'node --test failed to spawn');
+  });
+
+  child.on('exit', (status, signal) => {
+    if (finished) return;
+    if (stdoutRemainder) parseTapLine(stdoutRemainder);
+    if (stderrRemainder) parseTapLine(stderrRemainder);
+    if (typeof status === 'number') {
+      finish(status, `node --test exited normally${completedFromSummary ? ' after clean TAP summary' : ''}`);
+      return;
+    }
+    reportAbnormalExit(signal);
+    finish(1, 'node --test exited without a numeric status');
+  });
+
+  if (runnerTimeoutMs > 0) {
+    runnerTimer = setTimeout(() => {
+      reportAbnormalExit(null);
+      finish(1, `runner timeout ${runnerTimeoutMs}ms elapsed`);
+    }, runnerTimeoutMs);
+  }
+}
+
+if (forceExit) {
+  runWithCompletionForceExit();
+} else {
+  const result = spawnSync(process.execPath, testArgs, {
+    stdio: 'inherit',
+    env: childEnv,
+    timeout: runnerTimeoutMs > 0 ? runnerTimeoutMs : undefined,
+    killSignal: 'SIGTERM',
+  });
+
+  if (typeof result.status === 'number') {
+    process.exit(result.status);
+  }
+
+  reportAbnormalExit(result.signal, result.error?.message);
+  process.exit(1);
 }
-console.error(
-  `[run-test-files] node --test did not exit normally${result.signal ? ` (signal: ${result.signal})` : ''}. `
-    + `Roots: ${targets.join(', ')}. Test files: ${files.length}. `
-    + `Per-test timeout: ${testTimeoutMs > 0 ? `${testTimeoutMs}ms` : 'disabled'}. `
-    + `Test concurrency: ${testConcurrency ?? 'default'}. `
-    + `Force exit: ${forceExit ? 'enabled' : 'disabled'}. `
-    + `Runner timeout: ${runnerTimeoutMs > 0 ? `${runnerTimeoutMs}ms` : 'disabled'}.`,
-);
-process.exit(1);

package/src/scripts/sync-plugin-mirror.ts

@@ -13,6 +13,7 @@ import {
 	assertSkillMirror,
 	compareSkillMirror,
 } from "../catalog/skill-mirror.js";
+import { MANAGED_HOOK_EVENTS } from "../config/codex-hooks.js";
 import { buildOmxPluginMcpManifest } from "../config/omx-first-party-mcp.js";
 
 export interface SyncPluginMirrorOptions {
@@ -56,6 +57,15 @@ const SETUP_OWNED_PLUGIN_MANIFEST_FIELDS = [
 	"agents",
 	"prompts",
 ] as const;
+const OMX_PLUGIN_HOOK_COMMAND =
+	'node "${PLUGIN_ROOT}/hooks/codex-native-hook.mjs"';
+const OMX_PLUGIN_HOOK_LAUNCHER_CONTRACT_MARKER =
+	"omx-plugin-hook-launcher:v1";
+// Plugin-scoped Codex hooks intentionally mirror the setup-managed lifecycle
+// roster today while using PLUGIN_ROOT-local launch commands. If plugin and
+// setup hook coverage diverge, split this alias into a plugin-owned roster.
+const PLUGIN_HOOK_EVENTS = MANAGED_HOOK_EVENTS;
+type PluginHookEventName = (typeof PLUGIN_HOOK_EVENTS)[number];
 
 async function readJsonFile<T>(path: string): Promise<T> {
 	return JSON.parse(await readFile(path, "utf-8")) as T;
@@ -65,6 +75,35 @@ function stringifyJson(value: unknown): string {
 	return `${JSON.stringify(value, null, 2)}\n`;
 }
 
+function commandHook(timeout?: number): JsonValue {
+	return {
+		type: "command",
+		command: OMX_PLUGIN_HOOK_COMMAND,
+		...(typeof timeout === "number" ? { timeout } : {}),
+	};
+}
+
+function pluginHookEntry(eventName: PluginHookEventName): JsonValue {
+	const base = {
+		hooks: [commandHook(eventName === "Stop" ? 30 : undefined)],
+	};
+	if (eventName === "SessionStart") {
+		return { ...base, matcher: "startup|resume|clear" };
+	}
+	return base;
+}
+
+function buildOmxPluginHooksManifest(): JsonValue {
+	return {
+		hooks: Object.fromEntries(
+			PLUGIN_HOOK_EVENTS.map((eventName) => [
+				eventName,
+				[pluginHookEntry(eventName)],
+			]),
+		),
+	};
+}
+
 function assertDeepJsonEqual(
 	actual: unknown,
 	expected: unknown,
@@ -84,12 +123,36 @@ function assertDeepJsonEqual(
 	}
 }
 
+function assertPluginHookLauncherContractMarkerPresent(
+	path: string,
+	content: string,
+): void {
+	const requiredMarkers = [
+		OMX_PLUGIN_HOOK_LAUNCHER_CONTRACT_MARKER,
+	];
+	const missingMarkers = requiredMarkers.filter(
+		(marker) => !content.includes(marker),
+	);
+	if (missingMarkers.length > 0) {
+		throw new Error(
+			[
+				"plugin_bundle_metadata_out_of_sync",
+				"kind=hook-launcher",
+				`path=${path}`,
+				`missingMarkers=${JSON.stringify(missingMarkers)}`,
+			].join("\n"),
+		);
+	}
+}
+
 function getPluginPaths(root: string): {
 	pluginRoot: string;
 	pluginSkillsDir: string;
 	pluginMcpPath: string;
 	pluginAppsPath: string;
 	pluginManifestPath: string;
+	pluginHooksPath: string;
+	pluginHookLauncherPath: string;
 } {
 	const pluginRoot = join(root, "plugins", PLUGIN_NAME);
 	return {
@@ -98,6 +161,8 @@ function getPluginPaths(root: string): {
 		pluginMcpPath: join(pluginRoot, ".mcp.json"),
 		pluginAppsPath: join(pluginRoot, ".app.json"),
 		pluginManifestPath: join(pluginRoot, ".codex-plugin", "plugin.json"),
+		pluginHooksPath: join(pluginRoot, "hooks", "hooks.json"),
+		pluginHookLauncherPath: join(pluginRoot, "hooks", "codex-native-hook.mjs"),
 	};
 }
 
@@ -188,6 +253,7 @@ async function buildExpectedPluginManifest(
 		skills: "./skills/",
 		mcpServers: "./.mcp.json",
 		apps: "./.app.json",
+		hooks: "./hooks/hooks.json",
 	};
 }
 
@@ -237,16 +303,29 @@ async function assertPluginManifestPolicy(
 }
 
 async function assertPluginMetadata(root: string): Promise<void> {
-	const { pluginMcpPath, pluginAppsPath, pluginManifestPath } =
-		getPluginPaths(root);
-	const [actualMcp, actualApps, actualManifest] = await Promise.all([
-		readJsonFile<unknown>(pluginMcpPath),
-		readJsonFile<unknown>(pluginAppsPath),
-		readJsonFile<PluginManifest>(pluginManifestPath),
-	]);
+	const {
+		pluginMcpPath,
+		pluginAppsPath,
+		pluginManifestPath,
+		pluginHooksPath,
+		pluginHookLauncherPath,
+	} = getPluginPaths(root);
+	const [actualMcp, actualApps, actualManifest, actualHooks, actualHookLauncher] =
+		await Promise.all([
+			readJsonFile<unknown>(pluginMcpPath),
+			readJsonFile<unknown>(pluginAppsPath),
+			readJsonFile<PluginManifest>(pluginManifestPath),
+			readJsonFile<unknown>(pluginHooksPath),
+			readFile(pluginHookLauncherPath, "utf-8"),
+		]);
 
 	assertDeepJsonEqual(actualMcp, buildOmxPluginMcpManifest(), "mcp-manifest");
 	assertDeepJsonEqual(actualApps, { apps: {} }, "apps-manifest");
+	assertDeepJsonEqual(actualHooks, buildOmxPluginHooksManifest(), "hooks-manifest");
+	assertPluginHookLauncherContractMarkerPresent(
+		pluginHookLauncherPath,
+		actualHookLauncher,
+	);
 	await assertPluginManifestPolicy(root, actualManifest);
 }
 
@@ -254,11 +333,16 @@ async function writePluginMetadata(
 	root: string,
 	verbose = false,
 ): Promise<boolean> {
-	const { pluginMcpPath, pluginAppsPath, pluginManifestPath } =
-		getPluginPaths(root);
+	const {
+		pluginMcpPath,
+		pluginAppsPath,
+		pluginManifestPath,
+		pluginHooksPath,
+	} = getPluginPaths(root);
 	const expectedMcp = buildOmxPluginMcpManifest();
 	const expectedApps = { apps: {} };
 	const expectedManifest = await buildExpectedPluginManifest(root);
+	const expectedHooks = buildOmxPluginHooksManifest();
 	const writes = [
 		{
 			path: pluginMcpPath,
@@ -275,6 +359,11 @@ async function writePluginMetadata(
 			content: stringifyJson(expectedManifest),
 			label: "plugin manifest",
 		},
+		{
+			path: pluginHooksPath,
+			content: stringifyJson(expectedHooks),
+			label: "plugin hooks manifest",
+		},
 	];
 	let changed = false;
 

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

@@ -116,13 +116,30 @@ function assertTomlStructure(
     });
   }
 
+  const metadataHeading = "## OMX Agent Metadata";
+  const metadataIndex = instructions.lastIndexOf(metadataHeading);
+  if (metadataIndex < 0) {
+    throw errorBlock("native_agent_toml_invalid", {
+      agent: agentName,
+      field: "developer_instructions",
+      missing: metadataHeading,
+    });
+  }
+  const metadataLines = new Set(
+    instructions
+      .slice(metadataIndex)
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean),
+  );
+
   for (const expected of [
     `- role: ${agentName}`,
     `- posture: ${agent.posture}`,
     `- model_class: ${agent.modelClass}`,
     `- routing_role: ${agent.routingRole}`,
   ]) {
-    if (!instructions.includes(expected)) {
+    if (!metadataLines.has(expected)) {
       throw errorBlock("native_agent_toml_invalid", {
         agent: agentName,
         field: "developer_instructions",
@@ -130,6 +147,53 @@ function assertTomlStructure(
       });
     }
   }
+
+  const leafGuard = "<native_subagent_leaf_guard>";
+  const leafGuardEnd = "</native_subagent_leaf_guard>";
+  const allowedDelegation = "- native_subagent_delegation: allowed";
+  const latestGeneratedPolicyIndex = Math.max(
+    instructions.lastIndexOf("</posture_overlay>", metadataIndex),
+    instructions.lastIndexOf("</model_class_guidance>", metadataIndex),
+    instructions.lastIndexOf("</exact_model_guidance>", metadataIndex),
+  );
+  const leafGuardIndex = instructions.lastIndexOf(leafGuard);
+  const leafGuardEndIndex = instructions.lastIndexOf(leafGuardEnd);
+  const hasGeneratedLeafGuard = leafGuardIndex > latestGeneratedPolicyIndex
+    && leafGuardEndIndex > leafGuardIndex
+    && leafGuardEndIndex < metadataIndex;
+  if (agent.nativeSubagentDelegation === "allowed") {
+    if (!metadataLines.has(allowedDelegation)) {
+      throw errorBlock("native_agent_toml_invalid", {
+        agent: agentName,
+        field: "developer_instructions",
+        missing: allowedDelegation,
+      });
+    }
+    if (hasGeneratedLeafGuard) {
+      throw errorBlock("native_agent_toml_invalid", {
+        agent: agentName,
+        field: "developer_instructions",
+        unexpected: leafGuard,
+        message: "delegation-allowed agents must not receive the leaf-only guard",
+      });
+    }
+  } else {
+    if (!hasGeneratedLeafGuard) {
+      throw errorBlock("native_agent_toml_invalid", {
+        agent: agentName,
+        field: "developer_instructions",
+        missing: leafGuard,
+        message: "leaf native agents must receive the anti-recursion guard",
+      });
+    }
+    if (metadataLines.has(allowedDelegation)) {
+      throw errorBlock("native_agent_toml_invalid", {
+        agent: agentName,
+        field: "developer_instructions",
+        unexpected: allowedDelegation,
+      });
+    }
+  }
 }
 
 export async function verifyNativeAgents(