session-orchestrator 3.24.0 → 4.0.1

package/scripts/lib/validate/check-codex-skills.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// Independently inspect Codex discovery artifacts; generator freshness alone
+// cannot detect a generator that consistently emits an invalid skill contract.
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import yaml from 'js-yaml';
+
+const SKILL_ROOT = '.codex-plugin/skills';
+const FRONTMATTER_KEYS = new Set([
+  'name', 'description', 'license', 'compatibility', 'metadata', 'allowed-tools',
+]);
+
+/** @param {unknown} value */
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Read emitted artifacts against their source contract without importing the
+ * generator or comparing its prose. Paths are resolved as installed files.
+ * @param {string} pluginRoot
+ * @returns {{skills: string[], violations: string[]}}
+ */
+export function validateCodexSkills(pluginRoot) {
+  const root = realpathSync(pluginRoot);
+  const violations = [];
+  const sources = new Map();
+  const skills = [];
+  const label = (file) => relative(root, file).split(sep).join('/');
+
+  function text(file) {
+    try {
+      const actual = realpathSync(file);
+      if (!actual.startsWith(`${root}${sep}`)) {
+        violations.push(`${label(file)}: outside the plugin package`);
+        return null;
+      }
+      return readFileSync(file, 'utf8');
+    } catch (error) {
+      violations.push(`${label(file)}: missing or unreadable (${error.code ?? error.message})`);
+      return null;
+    }
+  }
+
+  function mapping(raw, file) {
+    if (raw === null) return null;
+    try {
+      const parsed = yaml.load(raw, { schema: yaml.CORE_SCHEMA });
+      if (!isRecord(parsed)) throw new Error('expected a YAML mapping');
+      return parsed;
+    } catch (error) {
+      violations.push(`${label(file)}: invalid YAML (${error.message.split('\n')[0]})`);
+      return null;
+    }
+  }
+
+  function frontmatter(file) {
+    const raw = text(file);
+    if (raw === null) return null;
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+    if (!match) {
+      violations.push(`${label(file)}: missing YAML frontmatter`);
+      return null;
+    }
+    const fm = mapping(match[1], file);
+    return fm && { fm, body: raw.slice(match[0].length) };
+  }
+
+  // Codex's Agent Plugins loader fixes skills to ./skills; its native overlay
+  // cannot override skills or version. A valid native manifest alone is not
+  // enough when a standard root manifest intercepts discovery (CLI 0.153.3/4).
+  const rootManifestFile = join(root, 'plugin.json');
+  if (existsSync(rootManifestFile)) {
+    try {
+      const manifest = JSON.parse(text(rootManifestFile));
+      if (typeof manifest?.$schema === 'string' && manifest.$schema.startsWith('https://agent-plugins.org/schemas/')) {
+        violations.push('Root Agent Plugins manifest overrides native Codex skills and cache version; use the native harness manifests');
+      }
+    } catch (error) {
+      violations.push(`Root plugin manifest: invalid JSON (${error.message})`);
+    }
+  }
+
+  const manifestFile = join(root, '.codex-plugin/plugin.json');
+  try {
+    const raw = text(manifestFile);
+    const manifest = raw === null ? null : JSON.parse(raw);
+    if (manifest?.skills !== `./${SKILL_ROOT}/`) {
+      violations.push(`Codex manifest skills must register only ./${SKILL_ROOT}/`);
+    }
+    if (!Array.isArray(manifest?.commands) || manifest.commands.length !== 0) {
+      violations.push('Codex manifest commands must be an explicit empty array to disable automatic command migration');
+    }
+  } catch (error) {
+    violations.push(`Codex manifest: invalid JSON (${error.message})`);
+  }
+
+  // Skill first, command second: a command owns the public entry on overlap.
+  for (const kind of ['skill', 'command']) {
+    const directory = join(root, kind === 'skill' ? 'skills' : 'commands');
+    if (!existsSync(directory)) {
+      violations.push(`${label(directory)}: canonical source directory is missing`);
+      continue;
+    }
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const name = kind === 'command' ? entry.name.replace(/\.md$/, '') : entry.name;
+      if (name.startsWith('.') || name.startsWith('_')) continue;
+      if (kind === 'command' && !entry.name.endsWith('.md')) continue;
+      const file = kind === 'command' ? join(directory, entry.name) : join(directory, name, 'SKILL.md');
+      if (kind === 'skill' && !existsSync(file)) continue;
+      const source = frontmatter(file);
+      sources.set(name, { kind, file, fm: source?.fm });
+    }
+  }
+  if (sources.size === 0) violations.push('No canonical commands or skills found');
+
+  const generated = join(root, SKILL_ROOT);
+  const actualNames = existsSync(generated)
+    ? readdirSync(generated, { withFileTypes: true })
+      .filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) && existsSync(join(generated, entry.name, 'SKILL.md')))
+      .map((entry) => entry.name)
+    : [];
+  for (const name of [...new Set([...sources.keys(), ...actualNames])].sort()) {
+    const source = sources.get(name);
+    if (!source) {
+      violations.push(`${SKILL_ROOT}/${name}: no canonical source`);
+      continue;
+    }
+    const file = join(generated, name, 'SKILL.md');
+    const artifact = frontmatter(file);
+    if (!artifact) continue;
+    skills.push(name);
+    const { fm, body } = artifact;
+    if (fm.name !== name) violations.push(`${label(file)}: name must equal ${name}`);
+    if (typeof fm.description !== 'string' || !fm.description.trim() || fm.description.length > 1024) {
+      violations.push(`${label(file)}: description must be a non-empty string of at most 1024 characters`);
+    }
+    for (const key of Object.keys(fm)) {
+      if (!FRONTMATTER_KEYS.has(key)) violations.push(`${label(file)}: unsupported frontmatter key ${key}`);
+    }
+    if (fm.metadata !== undefined && (!isRecord(fm.metadata) || Object.values(fm.metadata).some((value) => typeof value !== 'string'))) {
+      violations.push(`${label(file)}: metadata must contain string values`);
+    }
+    const links = [...body.matchAll(/\]\(([^\s)]+)\)/g)].map((match) => match[1]);
+    if (!links.some((target) => !target.includes(':') && !target.startsWith('/') && resolve(dirname(file), target) === source.file)) {
+      violations.push(`${label(file)}: missing canonical link to ${label(source.file)}`);
+    }
+    if (source.kind === 'command' && source.fm) {
+      const disabled = source.fm['disable-model-invocation'];
+      if (disabled !== undefined && typeof disabled !== 'boolean') {
+        violations.push(`${label(source.file)}: disable-model-invocation must be boolean`);
+      }
+      const policyFile = join(generated, name, 'agents/openai.yaml');
+      const sidecar = mapping(text(policyFile), policyFile);
+      if (sidecar && (typeof sidecar.policy?.allow_implicit_invocation !== 'boolean'
+        || sidecar.policy.allow_implicit_invocation !== (disabled !== true))) {
+        violations.push(`${label(policyFile)}: allow_implicit_invocation must preserve the command's boolean policy`);
+      }
+    }
+  }
+  return { skills, violations };
+}
+
+async function main(pluginRoot) {
+  if (!pluginRoot) throw new Error('Usage: check-codex-skills.mjs <plugin-root>');
+  console.log('--- Check: Codex command skills and generated freshness ---');
+  const { skills, violations } = validateCodexSkills(pluginRoot);
+  if (violations.length === 0) {
+    // Invoke the function directly: a child CLI that silently skips its entry
+    // point must never turn a missing freshness comparison into success.
+    const { generateCodexSurface } = await import('../../generate-codex-skills.mjs');
+    const fresh = generateCodexSurface({ pluginRoot, check: true });
+    if (!fresh.ok || !Array.isArray(fresh.files) || fresh.files.length === 0) {
+      violations.push(...(fresh.drift ?? []), ...(fresh.errors ?? []));
+      if (violations.length === 0) violations.push('Codex generator did not report a successful artifact comparison');
+    }
+  }
+  for (const violation of violations) console.log(`  FAIL: ${violation}`);
+  if (violations.length === 0) console.log(`  PASS: ${skills.length} unique Codex skills, command policies and generated files in sync`);
+  console.log(`Results: ${violations.length === 0 ? 1 : 0} passed, ${violations.length} failed`);
+  if (violations.length) console.log('Remedy: node scripts/generate-codex-skills.mjs');
+  process.exitCode = violations.length ? 1 : 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  main(process.argv[2]).catch((error) => {
+    console.error(`FAIL: Codex skills check: ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/scripts/lib/validate/check-cursor-adapter.mjs

@@ -4,99 +4,261 @@
 // Exit 0 = all checks passed, 1 = at least one failure.
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import yaml from 'js-yaml';
 
 import { CURSOR_TO_CANONICAL_EVENT } from '../cursor-hook-bridge.mjs';
 
-const pluginRoot = process.argv[2];
-if (!pluginRoot) {
-  console.error('Usage: check-cursor-adapter.mjs <plugin-root>');
-  process.exit(1);
-}
+/** agentskills.io caps a skill/command description at 1024 characters. */
+const DESCRIPTION_MAX = 1024;
 
-let passed = 0;
-let failed = 0;
-
-function pass(msg) { console.log(`  PASS: ${msg}`); passed += 1; }
-function fail(msg) { console.log(`  FAIL: ${msg}`); failed += 1; }
-
-console.log('--- Check 1: generated Cursor command and skill wrappers ---');
-
-const generator = join(pluginRoot, 'scripts', 'generate-cursor-adapter.mjs');
-if (!existsSync(generator)) {
-  fail('scripts/generate-cursor-adapter.mjs exists');
-} else {
-  const result = spawnSync(process.execPath, [generator, '--check'], {
-    cwd: pluginRoot,
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-  if (result.status === 0) {
-    pass('.cursor/commands and .cursor/skills are up to date with commands/ and skills/');
-  } else {
-    const detail = ((result.stdout ?? '') + (result.stderr ?? '')).trim();
-    fail(`Cursor adapter wrappers are stale${detail ? `: ${detail}` : ''}`);
+/**
+ * Locate a top-level frontmatter key's line number (1-based) so a violation can
+ * be reported as `file:line` rather than `file`.
+ *
+ * @param {string} content raw file content
+ * @param {string} key frontmatter key
+ * @returns {number} 1-based line number, or 1 when the key is absent
+ */
+function frontmatterKeyLine(content, key) {
+  const lines = content.split('\n');
+  const needle = new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*:`);
+  for (let i = 0; i < lines.length; i += 1) {
+    if (i > 0 && lines[i] === '---') break; // end of frontmatter
+    if (needle.test(lines[i])) return i + 1;
   }
+  return 1;
 }
 
-console.log('');
-console.log('--- Check 2: .cursor/hooks.json native manifest ---');
+/**
+ * Validate ONE generated artefact's frontmatter against the Cursor/agentskills
+ * spec, independent of the generator that produced it.
+ *
+ * @param {string} filePath absolute path to the artefact
+ * @param {string} rel path to report violations against
+ * @param {{requireName: boolean}} opts
+ * @returns {string[]} violation strings, empty when the artefact is conformant
+ */
+function validateArtefactFrontmatter(filePath, rel, { requireName }) {
+  const violations = [];
+  const content = readFileSync(filePath, 'utf8');
+
+  if (!content.startsWith('---\n')) {
+    return [`${rel}:1 — no YAML frontmatter block (file must start with '---')`];
+  }
+  const end = content.indexOf('\n---\n', 3);
+  if (end === -1) {
+    return [`${rel}:1 — frontmatter block is never closed`];
+  }
 
-const hooksPath = join(pluginRoot, '.cursor', 'hooks.json');
-if (!existsSync(hooksPath)) {
-  fail('.cursor/hooks.json exists');
-} else {
-  let hooksJson;
+  let fm;
   try {
-    hooksJson = JSON.parse(readFileSync(hooksPath, 'utf8'));
-    pass('.cursor/hooks.json is valid JSON');
+    fm = yaml.load(content.slice(4, end + 1), { schema: yaml.CORE_SCHEMA });
   } catch (err) {
-    fail(`.cursor/hooks.json is not valid JSON: ${err.message}`);
-    hooksJson = null;
+    return [`${rel}:1 — frontmatter is not parseable YAML: ${err.message.split('\n')[0]}`];
+  }
+  if (fm === null || typeof fm !== 'object' || Array.isArray(fm)) {
+    return [`${rel}:1 — frontmatter does not parse to a mapping`];
   }
 
-  if (hooksJson) {
-    if (hooksJson.version === 1) {
-      pass('.cursor/hooks.json version is 1');
-    } else {
-      fail('.cursor/hooks.json version must be 1');
+  // `argument-hint`, when present, MUST be a string. Its canonical authored
+  // form is `[mode] [--flag]`, which YAML reads as a flow SEQUENCE unless the
+  // generator quotes it — GH#54, which made Copilot CLI >= 1.0.65 silently drop
+  // the file. Type, not presence, is the assertion: an array here is the bug.
+  if (Object.hasOwn(fm, 'argument-hint')) {
+    const hint = fm['argument-hint'];
+    if (typeof hint !== 'string') {
+      violations.push(
+        `${rel}:${frontmatterKeyLine(content, 'argument-hint')} — argument-hint must be a string, got ${Array.isArray(hint) ? 'array' : typeof hint} (GH#54: an unquoted [a] [b] is a YAML flow sequence)`,
+      );
+    } else if (hint.trim() === '') {
+      violations.push(`${rel}:${frontmatterKeyLine(content, 'argument-hint')} — argument-hint is present but empty`);
     }
+  }
 
-    const declared = Object.keys(hooksJson.hooks || {});
-    const expected = Object.keys(CURSOR_TO_CANONICAL_EVENT);
-    const missing = expected.filter((event) => !declared.includes(event));
-    const extra = declared.filter((event) => !expected.includes(event));
-    if (missing.length === 0 && extra.length === 0) {
-      pass(`.cursor/hooks.json events match CURSOR_TO_CANONICAL_EVENT (${expected.length})`);
-    } else {
-      if (missing.length > 0) fail(`.cursor/hooks.json missing events: ${missing.join(', ')}`);
-      if (extra.length > 0) fail(`.cursor/hooks.json extra events: ${extra.join(', ')}`);
+  const required = requireName ? ['name', 'description'] : ['description'];
+  for (const key of required) {
+    const value = fm[key];
+    if (typeof value !== 'string' || value.trim() === '') {
+      violations.push(
+        `${rel}:${frontmatterKeyLine(content, key)} — ${key} must be a non-empty string, got ${value === undefined ? 'nothing' : (Array.isArray(value) ? 'array' : typeof value)}`,
+      );
+    }
+  }
+
+  if (typeof fm.description === 'string' && fm.description.length > DESCRIPTION_MAX) {
+    violations.push(
+      `${rel}:${frontmatterKeyLine(content, 'description')} — description is ${fm.description.length} chars, over the ${DESCRIPTION_MAX} limit (agentskills.io)`,
+    );
+  }
+
+  return violations;
+}
+
+/**
+ * Validate every generated Cursor artefact under `<pluginRoot>/.cursor`.
+ *
+ * This deliberately does NOT run the generator. Comparing generator output to
+ * generator output — which is all `--check` does — cannot see a defect the
+ * generator itself emits: it would report "up to date" while every file is
+ * broken, and a snapshot-style guard would freeze the broken files as the
+ * expectation. This reads the artefacts and judges them against the spec.
+ *
+ * @param {string} pluginRoot
+ * @returns {{files: number, violations: string[]}}
+ */
+export function validateCursorArtefacts(pluginRoot) {
+  const violations = [];
+  let files = 0;
+
+  const commandsDir = join(pluginRoot, '.cursor', 'commands');
+  if (existsSync(commandsDir)) {
+    for (const name of readdirSync(commandsDir).filter((n) => n.endsWith('.md')).sort()) {
+      const filePath = join(commandsDir, name);
+      files += 1;
+      violations.push(
+        ...validateArtefactFrontmatter(filePath, relative(pluginRoot, filePath), { requireName: false }),
+      );
     }
+  }
+
+  const skillsDir = join(pluginRoot, '.cursor', 'skills');
+  if (existsSync(skillsDir)) {
+    for (const name of readdirSync(skillsDir).sort()) {
+      const filePath = join(skillsDir, name, 'SKILL.md');
+      let isDir;
+      try { isDir = statSync(join(skillsDir, name)).isDirectory(); } catch { isDir = false; }
+      if (!isDir || !existsSync(filePath)) continue;
+      files += 1;
+      violations.push(
+        ...validateArtefactFrontmatter(filePath, relative(pluginRoot, filePath), { requireName: true }),
+      );
+    }
+  }
+
+  return { files, violations };
+}
 
-    const bridgeRef = 'scripts/lib/cursor-hook-bridge.mjs';
-    const allPointAtBridge = declared.every((event) => {
-      const entries = Array.isArray(hooksJson.hooks[event]) ? hooksJson.hooks[event] : [];
-      return entries.some((entry) => typeof entry.command === 'string' && entry.command.includes(bridgeRef) && entry.command.includes(`--event ${event}`));
+/**
+ * CLI entry point. Kept behind a direct-invocation guard so the module can be
+ * imported for {@link validateCursorArtefacts} without running (and exiting).
+ *
+ * @param {string|undefined} pluginRoot
+ * @returns {never}
+ */
+function runCli(pluginRoot) {
+  if (!pluginRoot) {
+    console.error('Usage: check-cursor-adapter.mjs <plugin-root>');
+    process.exit(1);
+  }
+
+  let passed = 0;
+  let failed = 0;
+
+  function pass(msg) { console.log(`  PASS: ${msg}`); passed += 1; }
+  function fail(msg) { console.log(`  FAIL: ${msg}`); failed += 1; }
+
+  console.log('--- Check 1: generated Cursor command and skill wrappers ---');
+
+  const generator = join(pluginRoot, 'scripts', 'generate-cursor-adapter.mjs');
+  if (!existsSync(generator)) {
+    fail('scripts/generate-cursor-adapter.mjs exists');
+  } else {
+    const result = spawnSync(process.execPath, [generator, '--check'], {
+      cwd: pluginRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
     });
-    if (allPointAtBridge) {
-      pass('.cursor/hooks.json commands invoke cursor-hook-bridge.mjs with --event');
+    if (result.status === 0) {
+      pass('.cursor/commands and .cursor/skills are up to date with commands/ and skills/');
     } else {
-      fail('.cursor/hooks.json commands must invoke scripts/lib/cursor-hook-bridge.mjs --event <name>');
+      const detail = ((result.stdout ?? '') + (result.stderr ?? '')).trim();
+      fail(`Cursor adapter wrappers are stale${detail ? `: ${detail}` : ''}`);
     }
   }
-}
 
-console.log('');
-console.log('--- Check 3: Cursor hook bridge module ---');
+  console.log('');
+  console.log('--- Check 1b: generated artefacts conform to the frontmatter spec ---');
+
+  // Check 1 above runs the generator against its own output. That comparison is
+  // structurally blind to a defect the generator EMITS — it reported "up to
+  // date" while 24 of 28 command wrappers carried an array-shaped
+  // `argument-hint` (GH#54). Check 1b judges the artefacts against the spec
+  // instead, so a generator bug surfaces as a failure rather than as a snapshot.
+  const { files: artefactCount, violations } = validateCursorArtefacts(pluginRoot);
+  if (violations.length === 0) {
+    pass(`${artefactCount} generated Cursor artefact(s) have spec-conformant frontmatter`);
+  } else {
+    for (const violation of violations) process.stderr.write(`FAIL: ${violation}\n`);
+    fail(`${violations.length} generated Cursor artefact(s) violate the frontmatter spec (see stderr for file:line)`);
+  }
+
+  console.log('');
+  console.log('--- Check 2: .cursor/hooks.json native manifest ---');
+
+  const hooksPath = join(pluginRoot, '.cursor', 'hooks.json');
+  if (!existsSync(hooksPath)) {
+    fail('.cursor/hooks.json exists');
+  } else {
+    let hooksJson;
+    try {
+      hooksJson = JSON.parse(readFileSync(hooksPath, 'utf8'));
+      pass('.cursor/hooks.json is valid JSON');
+    } catch (err) {
+      fail(`.cursor/hooks.json is not valid JSON: ${err.message}`);
+      hooksJson = null;
+    }
+
+    if (hooksJson) {
+      if (hooksJson.version === 1) {
+        pass('.cursor/hooks.json version is 1');
+      } else {
+        fail('.cursor/hooks.json version must be 1');
+      }
+
+      const declared = Object.keys(hooksJson.hooks || {});
+      const expected = Object.keys(CURSOR_TO_CANONICAL_EVENT);
+      const missing = expected.filter((event) => !declared.includes(event));
+      const extra = declared.filter((event) => !expected.includes(event));
+      if (missing.length === 0 && extra.length === 0) {
+        pass(`.cursor/hooks.json events match CURSOR_TO_CANONICAL_EVENT (${expected.length})`);
+      } else {
+        if (missing.length > 0) fail(`.cursor/hooks.json missing events: ${missing.join(', ')}`);
+        if (extra.length > 0) fail(`.cursor/hooks.json extra events: ${extra.join(', ')}`);
+      }
+
+      const bridgeRef = 'scripts/lib/cursor-hook-bridge.mjs';
+      const allPointAtBridge = declared.every((event) => {
+        const entries = Array.isArray(hooksJson.hooks[event]) ? hooksJson.hooks[event] : [];
+        return entries.some((entry) => typeof entry.command === 'string' && entry.command.includes(bridgeRef) && entry.command.includes(`--event ${event}`));
+      });
+      if (allPointAtBridge) {
+        pass('.cursor/hooks.json commands invoke cursor-hook-bridge.mjs with --event');
+      } else {
+        fail('.cursor/hooks.json commands must invoke scripts/lib/cursor-hook-bridge.mjs --event <name>');
+      }
+    }
+  }
+
+  console.log('');
+  console.log('--- Check 3: Cursor hook bridge module ---');
+
+  const bridgePath = join(pluginRoot, 'scripts', 'lib', 'cursor-hook-bridge.mjs');
+  if (existsSync(bridgePath)) {
+    pass('scripts/lib/cursor-hook-bridge.mjs exists');
+  } else {
+    fail('scripts/lib/cursor-hook-bridge.mjs exists');
+  }
 
-const bridgePath = join(pluginRoot, 'scripts', 'lib', 'cursor-hook-bridge.mjs');
-if (existsSync(bridgePath)) {
-  pass('scripts/lib/cursor-hook-bridge.mjs exists');
-} else {
-  fail('scripts/lib/cursor-hook-bridge.mjs exists');
+  console.log('');
+  console.log(`Results: ${passed} passed, ${failed} failed`);
+  process.exit(failed > 0 ? 1 : 0);
 }
 
-console.log('');
-console.log(`Results: ${passed} passed, ${failed} failed`);
-process.exit(failed > 0 ? 1 : 0);
+// Direct invocation only — importing this module must not run the CLI.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runCli(process.argv[2]);
+}

package/scripts/lib/validate/check-hooks-symmetry.mjs

@@ -66,11 +66,33 @@ const DOCUMENTED_ASYMMETRIES = {
   // A handler missing on a shared event and NOT listed here → FAIL.
   handlerAsymmetries: {
     codex: {
-      // Codex 0.144.4 has no payload adapter (docs/codex-setup.md § Hook
-      // Surface and Trust): Edit/Write handlers expect Claude payload shapes,
-      // Bash guards expect tool_name === 'Bash'. Wiring them would be a silent
-      // no-op, not enforcement (#919-P2 class) — "pretending the payloads are
-      // compatible would create false enforcement".
+      // WHY these stay unwired — corrected 2026-09-06 against the shipped
+      // codex-cli 0.144.4 binary, because the previous rationale here was
+      // measurably wrong and pointed at the wrong repair.
+      //
+      // REFUTED: "no Codex bridge delivers tool_name (grep scripts/lib/codex/
+      // *.mjs -> 0 matches)". That grep measured OUR adapter code, not the
+      // Codex payload contract. There is no bridge because none is needed:
+      // `pre-tool-use.command.input`, embedded verbatim in the binary, lists
+      // `tool_name` and `tool_input` among its REQUIRED fields (with `cwd`,
+      // `hook_event_name`, `model`, `permission_mode`, `session_id`,
+      // `tool_use_id`, `transcript_path`, `turn_id`). The output envelope is
+      // `hookSpecificOutput.{hookEventName,permissionDecision,
+      // permissionDecisionReason}` — byte-identical to what `emitDeny()`
+      // writes, and Codex's own error strings show it enforces exactly that
+      // shape ("PreToolUse hook returned permissionDecision:deny without a
+      // non-empty permissionDecisionReason").
+      //
+      // THE ACTUAL BLOCKER is the tool-name VOCABULARY, not the payload shape.
+      // Codex ships no `Bash`, `Edit`, `Write` or `MultiEdit` tool — it has
+      // `shell` / `exec_command` / `unified_exec` / `apply_patch`
+      // (`strings -a <codex> | grep -c '"Bash"'` -> 0). Every handler below
+      // opens with an equality gate on a Claude tool name and returns
+      // `emitAllow()` otherwise, so wiring one produces a hook that runs,
+      // matches nothing and allows everything: FALSE enforcement, which is
+      // strictly worse than the registered gap (#919-P2 class). The repair is
+      // a tool-name map (see CODEX_TOOL_NAMES in scripts/lib/codex/
+      // plugin-contract.mjs), not a manifest entry.
       PreToolUse: [
         // pre-task-scope-disjoint (#1020): NOT ported by construction. The hook
         // matches the `Agent` dispatch tool, which this platform does not have —
@@ -94,25 +116,32 @@ const DOCUMENTED_ASYMMETRIES = {
         'pre-bash-destructive-guard.mjs',
         'pre-bash-staging-fence.mjs',
         'pre-bash-memory-propose-audit.mjs',
-        // pre-bash-sessions-ledger-guard (#958): same Bash-payload dependency
-        // as the guards above — it reads tool_name === 'Bash' and
-        // tool_input.command, neither of which any Codex bridge delivers
-        // (measured 2026-07-31: `grep -rn "tool_name" scripts/lib/codex/*.mjs`
-        // → 0 matches, exit 1). A manifest entry would be a silent no-op, not
-        // enforcement — #919-P2 class. Gap registered, not faked.
+        // pre-bash-sessions-ledger-guard (#958): same tool-name-vocabulary
+        // dependency as the guards above — it gates on tool_name === 'Bash',
+        // and Codex names its shell tools `shell` / `exec_command` /
+        // `unified_exec`. The fields it reads ARE delivered; the value it
+        // compares against never occurs. A manifest entry would be a silent
+        // no-op, not enforcement — #919-P2 class. Gap registered, not faked.
         'pre-bash-sessions-ledger-guard.mjs',
         'pre-bash-templates-first.mjs',
         'pre-bash-issue-budget.mjs',
         'enforce-commands.mjs',
       ],
-      // post-bash-write-verify (#942): needs tool_name === 'Bash', which no
-      // Codex bridge delivers — documented exception until an adapter exists.
-      // Measured 2026-07-31: `grep -rn "tool_name" scripts/lib/codex/*.mjs`
-      // → 0 matches (exit 1), so a manifest entry here would be a silent
-      // no-op, not enforcement. Same #919-P2 class as the PreToolUse block.
+      // post-bash-write-verify (#942): gates on tool_name === 'Bash', a value
+      // Codex never emits (its shell tools are `shell` / `exec_command` /
+      // `unified_exec`). Documented exception until a tool-name map exists —
+      // a manifest entry today would be a silent no-op, not enforcement. Same
+      // #919-P2 class as the PreToolUse block. `post-tool-use.command.input`
+      // at 0.144.4 does require `tool_name`, `tool_input` AND `tool_response`,
+      // so the port is a rename map, not a payload bridge.
       PostToolUse: [
         'post-edit-validate.mjs',
         'post-tooluse-frontend-slop.mjs',
+        // post-edit-import-probe (#1224): same missing Edit/Write payload
+        // adapter as post-edit-validate — the hook reads tool_name and
+        // tool_input.file_path, neither of which any Codex bridge delivers.
+        // A manifest entry would be a silent no-op, not enforcement.
+        'post-edit-import-probe.mjs',
         'post-bash-write-verify.mjs',
       ],
       SubagentStart: ['subagent-telemetry.mjs'],