@haposoft/cafekit 0.18.1 → 0.18.3

package/bin/__tests__/codex-native.test.js

@@ -260,6 +260,99 @@ function parseGeneratedTomlString(content, key) {
   return JSON.parse(match[1]);
 }
 
+test('installed Codex instructions reference all ten runtime rules', () => {
+  inTempProject(root => {
+    const result = install(root);
+    assert.equal(result.status, 0, result.stderr);
+    const instructions = fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8');
+    const rules = ['workflow', 'ai-dev-rules', 'orchestrator', 'manage-docs', 'skill-workflow-routing', 'skill-domain-routing', 'review-audit-self-decision', 'process-management', 'state-sync', 'hook-protocols'];
+    for (const rule of rules) {
+      assert.ok(instructions.includes(`.codex/rules/${rule}.md`), rule);
+      assert.ok(fs.existsSync(path.join(root, '.codex/rules', `${rule}.md`)), rule);
+    }
+  });
+});
+
+test('installed Codex orchestrator describes high reasoning on the session model', () => {
+  inTempProject(root => {
+    const source = fs.readFileSync(path.join(PACKAGE_ROOT, 'src/claude/rules/orchestrator.md'));
+    const result = install(root);
+    assert.equal(result.status, 0, result.stderr);
+    const content = fs.readFileSync(path.join(root, '.codex/rules/orchestrator.md'), 'utf8');
+    assert.doesNotMatch(content, /strongest|below[^\n]*fable/);
+    assert.match(content, /high reasoning effort/);
+    assert.match(content, /session model unless[^.]*configur/i);
+    assert.deepEqual(fs.readFileSync(path.join(PACKAGE_ROOT, 'src/claude/rules/orchestrator.md')), source);
+  });
+});
+
+test('installed hook protocols share malformed-output handling and Codex receipt guidance', () => {
+  inTempProject(root => {
+    const result = installPlatforms(root, ['claude', 'codex']);
+    assert.equal(result.status, 0, result.stderr);
+    const sentence = 'If hook output is malformed, stop and report the exact failure instead of guessing.';
+    for (const runtime of ['.claude', '.codex']) {
+      const content = fs.readFileSync(path.join(root, runtime, 'rules/hook-protocols.md'), 'utf8');
+      assert.ok(content.includes(sentence), runtime);
+    }
+    assert.match(fs.readFileSync(path.join(root, '.codex/rules/hook-protocols.md'), 'utf8'), /state-sync\.md/);
+  });
+});
+
+test('installed Claude ignore rules preserve env samples and ignore temporary files', () => {
+  inTempProject(root => {
+    const result = installPlatforms(root, ['claude']);
+    assert.equal(result.status, 0, result.stderr);
+    const lines = fs.readFileSync(path.join(root, '.claude/.gitignore'), 'utf8').split(/\r?\n/);
+    for (const line of ['!.env.sample', '!.env.template', '*.tmp']) assert.ok(lines.includes(line), line);
+  });
+});
+
+const READ_ONLY_ROLE_SUFFIX = '\n\n## Read-only role\n\nRead-only role: never create, never edit, and never delete files, and never run commands that write to disk; return findings in your reply.';
+
+function assertInstalledAgentFields(content, name) {
+  const source = fs.readFileSync(path.join(PACKAGE_ROOT, 'src/claude/agents', `${name.replace(/_/g, '-')}.md`), 'utf8');
+  const { frontmatter, body } = require('../lib/codex-frontmatter').splitFrontmatter(source);
+  for (const key of ['name', 'description', 'developer_instructions']) {
+    assert.equal((content.match(new RegExp(`^${key} =`, 'gm')) || []).length, 1);
+  }
+  assert.equal(parseGeneratedTomlString(content, 'name'), name);
+  assert.equal(parseGeneratedTomlString(content, 'description'), normalizeCodexBody(frontmatter.description));
+  const suffix = ['brainstormer', 'code_auditor', 'inspector', 'researcher'].includes(name)
+    ? READ_ONLY_ROLE_SUFFIX : '';
+  const expectedBody = name === 'git_ops'
+    ? body.slice(0, body.indexOf('When instantiated as a team member'))
+      + body.split('\n').find(line => line.includes('NEVER arbitrarily use `force push`')).replace(/^3\. /, '- ') + '\n'
+    : body;
+  assert.equal(parseGeneratedTomlString(content, 'developer_instructions'), normalizeCodexBody(expectedBody).trim() + suffix);
+}
+
+for (const name of ['brainstormer', 'code_auditor', 'inspector', 'researcher']) {
+  test(`installed ${name} agent has exactly one read-only sandbox setting`, () => {
+    inTempProject(root => {
+      const result = install(root);
+      assert.equal(result.status, 0, result.stderr);
+      const content = fs.readFileSync(path.join(root, '.codex/agents', `${name}.toml`), 'utf8');
+      assert.deepEqual(content.match(/^sandbox_mode\s*=.*$/gm) || [], ['sandbox_mode = "read-only"']);
+      assert.ok(parseGeneratedTomlString(content, 'developer_instructions').endsWith(READ_ONLY_ROLE_SUFFIX));
+      assertInstalledAgentFields(content, name);
+    });
+  });
+}
+
+test('installed implementation agents retain their sandbox defaults', () => {
+  inTempProject(root => {
+    const result = install(root);
+    assert.equal(result.status, 0, result.stderr);
+    for (const name of ['implementer', 'test_runner', 'debugger', 'git_ops']) {
+      const content = fs.readFileSync(path.join(root, '.codex/agents', `${name}.toml`), 'utf8');
+      assert.doesNotMatch(content, /^sandbox_mode\s*=/m);
+      assert.doesNotMatch(parseGeneratedTomlString(content, 'developer_instructions'), /## Read-only role/);
+      assertInstalledAgentFields(content, name);
+    }
+  });
+});
+
 function replaceGeneratedTomlString(content, key, value) {
   const pattern = new RegExp(`^${key} = .+$`, 'gm');
   const matches = [...content.matchAll(pattern)];
@@ -816,7 +909,7 @@ function brainstormProjectionIssues(files) {
   }
   if (!skill.includes('Persist only approved decisions and semantics, only with user authority')
     || !skill.includes('redact live secrets, credentials, private keys, access tokens, and unnecessary PII;')
-    || !framework.includes('Do not write "user selected" unless direct user text or the native input tool confirms it.')) {
+    || !framework.includes('Do not write "user selected" unless direct user text or the question in the turn\'s final answer confirms it.')) {
     issues.add('approval-persistence');
   }
   for (const [issue, clause] of Object.entries(adaptiveClauses)) {
@@ -824,9 +917,9 @@ function brainstormProjectionIssues(files) {
   }
   const visible = `${skill}\n${framework}\n${agent}`;
   if (/\bAskUserQuestion\b/.test(visible)
-    || /\b(?:a|an|one|each|every|another|this|that|the|[0-9]+)\s+a structured user-input request\b/i.test(visible)
-    || /\ban structured user-input request\b/i.test(visible)
-    || /\ba structured user-input request\s+(?:calls|batches)\b/i.test(visible)) {
+    || /\b(?:a|an|one|each|every|another|this|that|the|[0-9]+)\s+a question in the turn\'s final answer\b/i.test(visible)
+    || /\ban question in the turn\'s final answer\b/i.test(visible)
+    || /\ba question in the turn\'s final answer\s+(?:calls|batches)\b/i.test(visible)) {
     issues.add('projection-grammar');
   }
   return [...issues].sort();
@@ -1379,26 +1472,26 @@ test('Codex payload transform emits native skill and subagent syntax', () => {
 
 test('Codex payload transform keeps structured user-input grammar across determiners', () => {
   const cases = [
-    ['standalone bare token', 'AskUserQuestion', 'a structured user-input request'],
-    ['standalone code token', '`AskUserQuestion`', 'a structured user-input request'],
-    ['standalone multi-backtick token', '``AskUserQuestion``', 'a structured user-input request'],
-    ['standalone padded multi-backtick token', '`` AskUserQuestion ``', 'a structured user-input request'],
-    ['one', 'one AskUserQuestion call', 'one structured user-input request call'],
-    ['one multi-backtick', 'one ``AskUserQuestion`` call', 'one structured user-input request call'],
-    ['one padded multi-backtick', 'one `` AskUserQuestion `` call', 'one structured user-input request call'],
-    ['each', 'each AskUserQuestion call', 'each structured user-input request call'],
-    ['every', 'every AskUserQuestion batch', 'every structured user-input request batch'],
-    ['another', 'another AskUserQuestion call', 'another structured user-input request call'],
-    ['this', 'this AskUserQuestion call', 'this structured user-input request call'],
-    ['that', 'that AskUserQuestion call', 'that structured user-input request call'],
-    ['a', 'a AskUserQuestion call', 'a structured user-input request call'],
-    ['an', 'an AskUserQuestion call', 'a structured user-input request call'],
-    ['capitalized each', 'Each AskUserQuestion call', 'Each structured user-input request call'],
-    ['capitalized an', 'An AskUserQuestion call', 'A structured user-input request call'],
-    ['the', 'the AskUserQuestion call', 'the structured user-input request call'],
-    ['numeric', '27 AskUserQuestion calls', '27 structured user-input request calls'],
-    ['plural calls', 'AskUserQuestion calls', 'structured user-input request calls'],
-    ['plural batches', 'AskUserQuestion batches', 'structured user-input request batches']
+    ['standalone bare token', 'AskUserQuestion', 'a question in the turn\'s final answer'],
+    ['standalone code token', '`AskUserQuestion`', 'a question in the turn\'s final answer'],
+    ['standalone multi-backtick token', '``AskUserQuestion``', 'a question in the turn\'s final answer'],
+    ['standalone padded multi-backtick token', '`` AskUserQuestion ``', 'a question in the turn\'s final answer'],
+    ['one', 'one AskUserQuestion call', 'one question in the turn\'s final answer call'],
+    ['one multi-backtick', 'one ``AskUserQuestion`` call', 'one question in the turn\'s final answer call'],
+    ['one padded multi-backtick', 'one `` AskUserQuestion `` call', 'one question in the turn\'s final answer call'],
+    ['each', 'each AskUserQuestion call', 'each question in the turn\'s final answer call'],
+    ['every', 'every AskUserQuestion batch', 'every question in the turn\'s final answer batch'],
+    ['another', 'another AskUserQuestion call', 'another question in the turn\'s final answer call'],
+    ['this', 'this AskUserQuestion call', 'this question in the turn\'s final answer call'],
+    ['that', 'that AskUserQuestion call', 'that question in the turn\'s final answer call'],
+    ['a', 'a AskUserQuestion call', 'a question in the turn\'s final answer call'],
+    ['an', 'an AskUserQuestion call', 'a question in the turn\'s final answer call'],
+    ['capitalized each', 'Each AskUserQuestion call', 'Each question in the turn\'s final answer call'],
+    ['capitalized an', 'An AskUserQuestion call', 'A question in the turn\'s final answer call'],
+    ['the', 'the AskUserQuestion call', 'the question in the turn\'s final answer call'],
+    ['numeric', '27 AskUserQuestion calls', '27 question in the turn\'s final answer calls'],
+    ['plural calls', 'AskUserQuestion calls', 'question in the turn\'s final answer calls'],
+    ['plural batches', 'AskUserQuestion batches', 'question in the turn\'s final answer batches']
   ];
 
   for (const [name, input, expected] of cases) {
@@ -1406,27 +1499,27 @@ test('Codex payload transform keeps structured user-input grammar across determi
     assert.equal(actual, expected, name);
     assert.equal(normalizeCodexBody(actual, '/fixture/instructions.md'), expected, `${name} idempotence`);
     assert.doesNotMatch(actual, /\bAskUserQuestion\b/, `${name} Claude-only token`);
-    assert.doesNotMatch(actual, /\ban structured user-input request\b/i, `${name} incompatible article`);
+    assert.doesNotMatch(actual, /\ban question in the turn\'s final answer\b/i, `${name} incompatible article`);
     assert.doesNotMatch(
       actual,
-      /\b(?:a|an|one|each|every|another|this|that|the|[0-9]+)\s+a structured user-input request\b/i,
+      /\b(?:a|an|one|each|every|another|this|that|the|[0-9]+)\s+a question in the turn\'s final answer\b/i,
       `${name} doubled article`
     );
   }
 
   assert.equal(
     normalizeCodexBody('one\nAskUserQuestion call', '/fixture/instructions.md'),
-    'one\nstructured user-input request call',
+    'one\nquestion in the turn\'s final answer call',
     'a single Markdown soft break must preserve its determiner relationship'
   );
   assert.equal(
     normalizeCodexBody('AskUserQuestion\nCalls', '/fixture/instructions.md'),
-    'structured user-input request\nCalls',
+    'question in the turn\'s final answer\nCalls',
     'a single Markdown soft break must preserve a plural relationship'
   );
   assert.equal(
     normalizeCodexBody('one\n\nAskUserQuestion call', '/fixture/instructions.md'),
-    'one\n\na structured user-input request call',
+    'one\n\na question in the turn\'s final answer call',
     'a paragraph break must not bind a prior determiner'
   );
   assert.equal(
@@ -1504,9 +1597,9 @@ test('Codex structured-input corpus oracle stays differential and production-awa
   assert.deepEqual(actualPaths, expectedPaths, 'every source occurrence needs an explicit projection oracle');
 
   const instructionExpectedSnippets = new Map([
-    ['src/claude/skills/git/SKILL.md', 'Present options via a structured user-input request — header'],
-    ['src/claude/skills/scout/SKILL.md', '**Fallback to a structured user-input request:**'],
-    ['src/claude/skills/sync/references/rebind-and-audit.md', 'End by asking with a structured user-input request when the host has']
+    ['src/claude/skills/git/SKILL.md', 'Present options via a question in the turn\'s final answer — header'],
+    ['src/claude/skills/scout/SKILL.md', '**Fallback to a question in the turn\'s final answer:**'],
+    ['src/claude/skills/sync/references/rebind-and-audit.md', 'End by asking with a question in the turn\'s final answer when the host has']
   ]);
   for (const [relativePath, expectedSnippet] of instructionExpectedSnippets) {
     const sourcePath = path.join(PACKAGE_ROOT, relativePath);
@@ -1515,7 +1608,7 @@ test('Codex structured-input corpus oracle stays differential and production-awa
     const withSentinel = source.replace(/`?\bAskUserQuestion\b`?/g, sentinel);
     assert.notEqual(withSentinel, source, `${relativePath} differential control must replace a token`);
     const expected = normalizeCodexBody(withSentinel, sourcePath)
-      .replaceAll(sentinel, 'a structured user-input request');
+      .replaceAll(sentinel, 'a question in the turn\'s final answer');
     const actual = normalizeCodexBody(source, sourcePath);
     assert.equal(actual, expected, `${relativePath} independent differential oracle`);
     assert.match(actual, new RegExp(expectedSnippet.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
@@ -1524,7 +1617,7 @@ test('Codex structured-input corpus oracle stays differential and production-awa
   const specMaker = fs.readFileSync(SPEC_MAKER_SOURCE_PATH, 'utf8');
   const convertedAgent = convertCodexAgentContent(specMaker, path.basename(SPEC_MAKER_SOURCE_PATH));
   assert.doesNotMatch(convertedAgent, /\bAskUserQuestion\b/);
-  assert.doesNotMatch(convertedAgent, /structured user-input request/);
+  assert.doesNotMatch(convertedAgent, /question in the turn\'s final answer/);
 
   const sessionPath = path.join(PACKAGE_ROOT, 'src/claude/hooks/session.cjs');
   const session = normalizeCodexBody(fs.readFileSync(sessionPath, 'utf8'), sessionPath);
@@ -1996,6 +2089,45 @@ function sessionLauncher(projectRoot) {
   return { config, command: config.hooks.SessionStart[0].hooks[0].command };
 }
 
+test('parity regression: moved Codex checkout rebinds both launcher fields and preserves metadata', () => {
+  inTempProject((root) => {
+    const oldRoot = path.join(root, "old ' quoted project"), newRoot = path.join(root, "new ' quoted project");
+    fs.mkdirSync(oldRoot);
+    assert.equal(install(oldRoot).status, 0);
+    const configPath = path.join(oldRoot, '.codex/hooks.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    config.hooks.SessionStart[0].matcher = 'custom-startup';
+    config.hooks.SessionStart[0].hooks[0].timeout = 41;
+    fs.writeFileSync(configPath, JSON.stringify(config));
+    fs.renameSync(oldRoot, newRoot);
+    const movedConfig = path.join(newRoot, '.codex/hooks.json');
+    const before = fs.readFileSync(movedConfig, 'utf8');
+    assert.equal(install(newRoot, ['--dry-run']).status, 0);
+    assert.equal(fs.readFileSync(movedConfig, 'utf8'), before, 'dry run modified launchers');
+    const upgraded = install(newRoot);
+    assert.equal(upgraded.status, 0, `${upgraded.stdout}\n${upgraded.stderr}`);
+    const rebound = sessionLauncher(newRoot);
+    assert.equal(rebound.config.hooks.SessionStart[0].matcher, 'custom-startup');
+    assert.equal(rebound.config.hooks.SessionStart[0].hooks[0].timeout, 41);
+    const launched = runPosixLauncher(rebound.command, newRoot);
+    assert.equal(launched.status, 0, launched.stderr);
+    assert.match(launched.stdout, /Session startup\./);
+    const windowsCommand = rebound.config.hooks.SessionStart[0].hooks[0].commandWindows.replace(/^node /, `"${process.execPath}" `);
+    const launchedWindows = spawnSync(windowsCommand, { cwd: newRoot, encoding: 'utf8', input: JSON.stringify({ session_id: 'moved-windows', hook_event_name: 'SessionStart', source: 'startup', cwd: newRoot }), shell: true });
+    assert.equal(launchedWindows.status, 0, launchedWindows.stderr);
+    assert.match(launchedWindows.stdout, /Session startup\./);
+    for (const { handler } of allHookLaunchers(rebound.config)) {
+      const encoded = handler.commandWindows.match(/\s([A-Za-z0-9_-]+)$/)?.[1];
+      assert.ok(encoded);
+      const target = Buffer.from(encoded, 'base64url').toString('utf8');
+      assert.equal(path.dirname(target), fs.realpathSync(path.join(newRoot, '.codex/hooks')));
+    }
+    const stable = fs.readFileSync(movedConfig, 'utf8');
+    assert.equal(install(newRoot).status, 0);
+    assert.equal(fs.readFileSync(movedConfig, 'utf8'), stable, 'reinstall changed stable hooks config');
+  });
+});
+
 test('Codex POSIX hook launchers run without Git and outside the repository root', () => {
   inTempProject((root) => {
     // A launcher that asks Git for its root gets nothing here and the outer root one
@@ -2194,7 +2326,10 @@ test('Codex installed Specs and spec-maker reject adaptive coverage mutations',
     );
     assert.equal(catalog.status, 0, catalog.stderr);
     const catalogData = JSON.parse(catalog.stdout);
-    assert.equal(catalogData.total, skillNames.length);
+    // Explicit-only skills run only when named, so the catalog leaves them out of automatic routing.
+    const explicitOnly = skillFiles.filter((file) => /^disable-model-invocation:\s*true\s*$/m.test(fs.readFileSync(file, 'utf8')));
+    assert.ok(explicitOnly.length >= 1);
+    assert.equal(catalogData.total, skillNames.length - explicitOnly.length);
     assert.equal(
       catalogData.root,
       fs.realpathSync(path.join(root, '.agents', 'skills'))
@@ -2248,7 +2383,7 @@ test('Codex installed Specs and spec-maker reject adaptive coverage mutations',
     const questionSkill = path.join(root, '.agents', 'skills', 'ask', 'SKILL.md');
     fs.appendFileSync(questionSkill, '\nUSER-CODEX-SENTINEL\n');
     // Fresh installs are exact. Refresh/upgrade intentionally documents the
-    // A skill file the manifest lists as obsolete is removed on refresh; edited skills stay.
+    // Untracked obsolete files and edited current skills both stay on refresh.
     const obsoleteSpecsRule = path.join(
       root, '.agents', 'skills', 'specs', 'rules', 'design-principles.md'
     );
@@ -2261,8 +2396,8 @@ test('Codex installed Specs and spec-maker reject adaptive coverage mutations',
     assert.match(fs.readFileSync(questionSkill, 'utf8'), /USER-CODEX-SENTINEL/);
     assert.equal(
       fs.existsSync(obsoleteSpecsRule),
-      false,
-      'Codex refresh removes obsolete skill files'
+      true,
+      'Codex refresh preserves untracked obsolete skill files'
     );
 
     const metadataPath = path.join(root, '.codex', 'cafekit.json');
@@ -2277,9 +2412,11 @@ test('Codex installed Specs and spec-maker reject adaptive coverage mutations',
     assert.match(fs.readFileSync(questionSkill, 'utf8'), /USER-CODEX-SENTINEL/);
     assert.equal(
       fs.existsSync(obsoleteSpecsRule),
-      false,
-      'Codex upgrade removes obsolete skill files'
+      true,
+      'Codex upgrade preserves untracked obsolete skill files'
     );
+    assert.match(sameVersion.stdout + sameVersion.stderr, /Preserved 1 obsolete runtime/);
+    assert.match(upgrade.stdout + upgrade.stderr, /Preserved 1 obsolete runtime/);
     assert.ok(fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8').startsWith(userInstructions));
 
     const forced = install(root, ['--force-overwrite']);
@@ -2509,7 +2646,7 @@ test('Codex installed Brainstorm skill reference and agent preserve proportional
       {
         name: 'decision-provenance-removed',
         source: 'framework',
-        from: 'Do not write "user selected" unless direct user text or the native input tool\n  confirms it.',
+        from: 'Do not write "user selected" unless direct user text or the question in the turn\'s final answer\n  confirms it.',
         to: 'Write "user selected" for inferred defaults.',
         expected: ['approval-persistence']
       },
@@ -2517,7 +2654,7 @@ test('Codex installed Brainstorm skill reference and agent preserve proportional
         name: 'installed-grammar-corruption',
         source: 'skill',
         from: '## Completion bar',
-        to: 'one a structured user-input request call\n\n## Completion bar',
+        to: 'one a question in the turn\'s final answer call\n\n## Completion bar',
         expected: ['projection-grammar']
       }
     ];
@@ -3079,28 +3216,32 @@ test('Codex installed code_auditor carries no Strict attestation marker', () =>
   });
 });
 
-test('reinstall removes obsolete scripts and skill files from Codex and omp installs', () => {
-  inTempProject((root) => {
+test('reinstall preserves untracked Codex and omp runtime files', () => {
+  for (const platform of ['codex', 'omp']) inTempProject(root => {
     const first = installPlatforms(root, ['codex', 'omp']);
     assert.equal(first.status, 0, `${first.stdout}\n${first.stderr}`);
+    const runtime = `.${platform}`;
     const retired = ['change-firewall.cjs', 'spec-final-state.cjs'];
-    for (const runtime of ['.codex', '.omp']) {
-      for (const name of retired) fs.writeFileSync(path.join(root, runtime, 'scripts', name), 'legacy\n');
-    }
+    for (const name of retired) fs.writeFileSync(path.join(root, runtime, 'scripts', name), 'legacy\n');
+    // omp installs no skills, so a reinstall of omp alone must leave .agents/skills to Codex.
     const retiredSkillFiles = ['code-review/references/verification-gate.md', 'specs/references/archive-workflow.md'];
-    for (const rel of retiredSkillFiles) fs.writeFileSync(path.join(root, '.agents', 'skills', rel), 'legacy\n');
-    const again = installPlatforms(root, ['codex', 'omp'], ['--force-overwrite']);
-    assert.equal(again.status, 0, `${again.stdout}\n${again.stderr}`);
     for (const rel of retiredSkillFiles) {
-      assert.equal(fs.existsSync(path.join(root, '.agents', 'skills', rel)), false, `.agents/skills/${rel} must be removed`);
+      const target = path.join(root, '.agents/skills', rel);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, 'legacy\n');
     }
-    assert.equal(fs.existsSync(path.join(root, '.agents', 'skills', 'code-review', 'SKILL.md')), true, 'the code-review skill stays');
-    for (const runtime of ['.codex', '.omp']) {
-      for (const name of retired) {
-        assert.equal(fs.existsSync(path.join(root, runtime, 'scripts', name)), false, `${runtime}/scripts/${name} must be removed`);
-      }
-      assert.equal(fs.existsSync(path.join(root, runtime, 'scripts', 'spec-resolver.cjs')), true, `${runtime} keeps the resolver`);
+    const again = installPlatforms(root, [platform], ['--force-overwrite']);
+    assert.equal(again.status, 0, `${again.stdout}\n${again.stderr}`);
+    const output = again.stdout + again.stderr;
+    for (const rel of retiredSkillFiles) assert.equal(fs.existsSync(path.join(root, '.agents/skills', rel)), true, rel);
+    for (const name of retired) assert.equal(fs.existsSync(path.join(root, runtime, 'scripts', name)), true, name);
+    if (platform === 'codex') assert.match(output, /Preserved 4 obsolete runtime/);
+    else {
+      assert.match(output, /Preserved 2 obsolete runtime/);
+      assert.doesNotMatch(output, /\.agents\/skills/);
     }
+    assert.equal(fs.existsSync(path.join(root, '.agents/skills/code-review/SKILL.md')), true);
+    assert.equal(fs.existsSync(path.join(root, runtime, 'scripts/spec-resolver.cjs')), true);
   });
 });
 
@@ -3222,4 +3363,3 @@ test('Claude and Codex installed rules preserve the ported review and process gu
     }
   });
 });
-

package/bin/__tests__/codex-plugin-build.test.js

@@ -0,0 +1,230 @@
+'use strict';
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const REPO = path.resolve(__dirname, '../../../..');
+const SRC = path.resolve(__dirname, '../../src');
+const SCRIPT = path.resolve(__dirname, '../../scripts/build-codex-plugin.mjs');
+let lib;
+let claudeLib;
+let work;
+let tree;
+
+function walk(root, base = root) {
+  return fs.readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(root, entry.name);
+    return entry.isDirectory() ? walk(full, base) : [path.relative(base, full)];
+  });
+}
+
+before(async () => {
+  lib = await import(SCRIPT);
+  claudeLib = await import(path.resolve(__dirname, '../../scripts/build-claude-plugin.mjs'));
+  work = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-codex-plugin-build-'));
+  tree = lib.build(path.join(work, 'cf-codex'));
+});
+
+after(() => fs.rmSync(work, { recursive: true, force: true }));
+
+test('inventory-and-policy: the Claude plugin skill list, Codex names, and explicit-only policies', () => {
+  const skills = fs.readdirSync(path.join(tree, 'skills')).sort();
+  // The Claude plugin's skills plus the Codex-only ones.
+  assert.deepEqual(skills, [...claudeLib.inScopeSkills(), ...lib.CODEX_ONLY_SKILLS].sort());
+  const { isExplicitOnlySkill, CODEX_POLICY_FILE, CODEX_EXPLICIT_ONLY_POLICY } = require('../phases/copy-payload');
+  for (const skill of skills) {
+    const text = fs.readFileSync(path.join(tree, 'skills', skill, 'SKILL.md'), 'utf8');
+    assert.match(text, new RegExp(`^---\\nname: cf-${skill}\\n`), `${skill} keeps the installer's Codex name`);
+    const policy = path.join(tree, 'skills', skill, CODEX_POLICY_FILE);
+    const skillSource = lib.CODEX_ONLY_SKILLS.includes(skill) ? path.join(SRC, 'codex/plugin/skills', skill) : path.join(SRC, 'claude/skills', skill);
+    if (isExplicitOnlySkill(skillSource)) {
+      assert.equal(fs.readFileSync(policy, 'utf8'), CODEX_EXPLICIT_ONLY_POLICY, `${skill} policy`);
+    } else {
+      assert.ok(!fs.existsSync(policy), `${skill} has an unexpected policy file`);
+    }
+  }
+});
+
+test('path-allowlist: Markdown reaches plugin files through {CAFEKIT_ROOT}, never an install path', () => {
+  const offenders = [];
+  for (const file of walk(tree).filter((f) => f.endsWith('.md'))) {
+    const text = fs.readFileSync(path.join(tree, file), 'utf8');
+    if (/\.codex[/\\](skills|references|scripts|rules|hooks|output-styles)\b/.test(text)) offenders.push(`${file}: .codex runtime path`);
+    if (/\.agents[/\\]skills\b/.test(text)) offenders.push(`${file}: .agents/skills path`);
+    if (/(?<!~\/)\.codex\/agents\//.test(text)) offenders.push(`${file}: project .codex/agents path`);
+    if (/\.claude[/\\](skills|references|scripts|rules)\b/.test(text)) offenders.push(`${file}: .claude runtime path`);
+    if (/\{CAFEKIT_ROOT\}\/scripts\//.test(text)) offenders.push(`${file}: script reached by path instead of {cafekit:<name>}`);
+    for (const [, rel] of text.matchAll(/\{CAFEKIT_ROOT\}\/([^\s`'")]+)/g)) {
+      const target = rel.replace(/[.,:;]+$/, '');
+      if (/[<*]/.test(target)) continue;
+      if (!fs.existsSync(path.join(tree, target))) offenders.push(`${file}: {CAFEKIT_ROOT}/${target} does not exist`);
+    }
+  }
+  assert.deepEqual(offenders, []);
+  const commands = lib.scriptCommands(tree);
+  assert.ok(commands.includes('provenance'), 'provenance is not in the command table');
+  for (const name of commands) assert.ok(fs.existsSync(path.join(tree, 'scripts', `${name}.cjs`)), `${name} has no script`);
+});
+
+test('manifest-and-marketplace: plugin.json and the repo marketplace carry the keys Codex reads', () => {
+  const manifest = JSON.parse(fs.readFileSync(path.join(tree, '.codex-plugin/plugin.json'), 'utf8'));
+  assert.equal(manifest.name, 'cf');
+  assert.equal(manifest.version, require('../../package.json').version);
+  for (const key of ['description', 'author', 'license', 'interface']) assert.ok(manifest[key], `plugin.json lacks ${key}`);
+  const market = lib.marketplace();
+  assert.equal(typeof market.name, 'string');
+  const entry = market.plugins.find((p) => p.name === 'cf');
+  assert.deepEqual(entry.source, { source: 'local', path: './plugins/cf-codex' });
+  assert.ok(entry.policy?.installation && entry.policy?.authentication && entry.category, 'entry lacks policy or category');
+});
+
+test('marketplace-not-ignored: git can commit .agents/plugins/marketplace.json', () => {
+  // --no-index: a tracked file would otherwise always read as not ignored.
+  const run = spawnSync('git', ['check-ignore', '-q', '--no-index', '.agents/plugins/marketplace.json'], { cwd: REPO });
+  assert.equal(run.status, 1, 'the marketplace file is ignored by git');
+  const skills = spawnSync('git', ['check-ignore', '-q', '--no-index', '.agents/skills/specs/SKILL.md'], { cwd: REPO });
+  assert.equal(skills.status, 0, 'npx-installed .agents/skills must stay ignored');
+  // A reinstall must not append `.agents/` after `!.agents/plugins/` and hide the marketplace again.
+  const { hasPattern } = require('../phases/root-config');
+  assert.ok(hasPattern(['.agents/*', '!.agents/plugins/'], '.agents/'));
+});
+
+test('claude-marketplace-guard: the Codex marketplace never points at the Claude plugin tree', () => {
+  const entry = lib.marketplace().plugins.find((p) => p.name === 'cf');
+  assert.notEqual(path.normalize(entry.source.path), path.normalize('./plugins/cf'));
+  assert.ok(!fs.existsSync(path.join(REPO, 'plugins/cf/.codex-plugin')), 'the Claude tree must not carry a Codex manifest');
+});
+
+test('check-detects-drift: --check fails after one byte changes in a fresh copy', () => {
+  const copy = lib.build(path.join(work, 'copy'));
+  const clean = spawnSync('node', [SCRIPT, '--check', copy], { encoding: 'utf8' });
+  assert.equal(clean.status, 0, clean.stderr);
+  fs.appendFileSync(path.join(copy, 'skills/specs/SKILL.md'), 'x');
+  const drift = spawnSync('node', [SCRIPT, '--check', copy], { encoding: 'utf8' });
+  assert.equal(drift.status, 1);
+  assert.match(drift.stderr, /changed skills\/specs\/SKILL\.md/);
+});
+
+// ── Runtime and hooks.json ─────────────────────────────────────────────────────
+
+const RUNTIME_DIRS = ['hooks', 'rules', 'output-styles'];
+
+function npxInstall() {
+  const repo = fs.mkdtempSync(path.join(work, 'npx-'));
+  spawnSync('git', ['init', '-q'], { cwd: repo });
+  const run = spawnSync('node', [path.resolve(__dirname, '../install.js'), '--platform', 'codex', '-y'], {
+    cwd: repo, encoding: 'utf8', env: { ...process.env, HOME: fs.mkdtempSync(path.join(work, 'home-')) },
+  });
+  assert.equal(run.status, 0, run.stderr || run.stdout);
+  return repo;
+}
+
+function runtimeFiles(root) {
+  return RUNTIME_DIRS.flatMap((dir) => (fs.existsSync(path.join(root, dir)) ? walk(path.join(root, dir)).map((f) => `${dir}/${f}`) : []))
+    .concat(fs.existsSync(path.join(root, 'runtime.schema.json')) ? ['runtime.schema.json'] : [])
+    .filter((f) => f !== 'hooks/hooks.json' && !f.includes('/.logs/'))
+    .sort();
+}
+
+test('runtime-matches-npx: the plugin runtime holds the same files and bytes as an npx Codex install', () => {
+  const installed = path.join(npxInstall(), '.codex');
+  const expected = runtimeFiles(installed);
+  assert.deepEqual(runtimeFiles(tree), expected);
+  for (const file of expected) {
+    assert.ok(fs.readFileSync(path.join(tree, file)).equals(fs.readFileSync(path.join(installed, file))), `${file} differs from the npx install`);
+  }
+});
+
+test('requires-resolve: every relative require in the plugin hooks resolves inside the tree', () => {
+  const missing = [];
+  for (const file of walk(path.join(tree, 'hooks')).filter((f) => f.endsWith('.cjs'))) {
+    const full = path.join(tree, 'hooks', file);
+    for (const [, spec] of fs.readFileSync(full, 'utf8').matchAll(/require\(\s*['"](\.{1,2}\/[^'"]+)['"]\s*\)/g)) {
+      const target = path.resolve(path.dirname(full), spec);
+      if (![target, `${target}.cjs`, `${target}.js`].some((t) => fs.existsSync(t))) missing.push(`hooks/${file} → ${spec}`);
+    }
+  }
+  assert.deepEqual(missing, []);
+});
+
+function pluginHandlers() {
+  const { hooks } = JSON.parse(fs.readFileSync(path.join(tree, 'hooks/hooks.json'), 'utf8'));
+  return Object.entries(hooks).flatMap(([event, groups]) => groups.flatMap((group) => group.hooks.map((h) => ({ event, ...h }))));
+}
+
+test('hook-commands-fallback: every plugin hook has a POSIX command with a node PATH fallback and a Windows command', () => {
+  const template = JSON.parse(fs.readFileSync(path.join(SRC, 'codex/hooks.json'), 'utf8')).hooks;
+  const handlers = pluginHandlers();
+  // The template's runtime hooks plus the one plugin-only SessionStart hook.
+  const pluginOnly = handlers.filter((h) => h.command.includes('/plugin/hooks/'));
+  assert.deepEqual(pluginOnly.map((h) => h.event), ['SessionStart']);
+  assert.equal(handlers.length - pluginOnly.length, Object.values(template).flat().flatMap((g) => g.hooks).length);
+  for (const handler of handlers) {
+    const [, dir, script] = handler.command.match(/((?:plugin\/)?hooks)\/([a-z0-9-]+\.cjs)"$/) || [];
+    assert.ok(script && fs.existsSync(path.join(tree, dir, script)), `bad command ${handler.command}`);
+    assert.match(handler.command, /^PATH="\$PATH":'[^']+'(:'[^']+')* node "\$\{PLUGIN_ROOT\}\/(plugin\/)?hooks\/[a-z0-9-]+\.cjs"$/);
+    assert.equal(typeof handler.commandWindows, 'string');
+    assert.ok(handler.commandWindows.includes(script) && handler.commandWindows.includes('PLUGIN_ROOT'), handler.commandWindows);
+  }
+});
+
+test('no-build-machine-paths: hooks.json names no absolute path of the machine that built it', () => {
+  const text = fs.readFileSync(path.join(tree, 'hooks/hooks.json'), 'utf8');
+  for (const local of [REPO, os.homedir(), path.dirname(process.execPath)]) assert.ok(!text.includes(local), `hooks.json contains ${local}`);
+  const windows = pluginHandlers()[0].commandWindows;
+  const decoded = spawnSync('node', ['-e', `${windows.replace(/^node -e "|"$/g, '').replace(/require\('module'\)\.runMain\(\)/, 'console.log(process.argv[1])')}`], {
+    encoding: 'utf8', env: { ...process.env, PLUGIN_ROOT: path.join(work, 'win-root') },
+  });
+  assert.equal(decoded.stdout.trim(), path.join(work, 'win-root', 'hooks', pluginHandlers()[0].command.match(/hooks\/([a-z0-9-]+\.cjs)"$/)[1]));
+});
+
+test('npx-hook-commands-unchanged: the npx install still gets absolute project launchers', () => {
+  const repo = npxInstall();
+  const { hooks } = JSON.parse(fs.readFileSync(path.join(repo, '.codex/hooks.json'), 'utf8'));
+  for (const handler of Object.values(hooks).flat().flatMap((g) => g.hooks)) {
+    assert.match(handler.command, /node '[^']+\/\.codex\/hooks\/[a-z0-9-]+\.cjs'$/);
+    assert.ok(handler.command.includes(fs.realpathSync(repo)));
+    assert.ok(!handler.command.includes('PLUGIN_ROOT'));
+    const encoded = handler.commandWindows.split(' ').pop();
+    assert.ok(Buffer.from(encoded, 'base64url').toString('utf8').startsWith(path.join(fs.realpathSync(repo), '.codex', 'hooks')), 'npx Windows launcher lost its project path');
+  }
+});
+
+const SAMPLE_PAYLOADS = {
+  SessionStart: { source: 'startup' },
+  UserPromptSubmit: { prompt: 'hello' },
+  PreToolUse: { tool_name: 'Bash', tool_input: { command: 'ls' } },
+  PermissionRequest: { tool_name: 'Bash', tool_input: { command: 'ls' } },
+  PostToolUse: { tool_name: 'apply_patch', tool_input: { command: '' }, tool_response: {} },
+  Stop: { stop_hook_active: false },
+  SubagentStart: { agent_type: 'debugger' },
+  SubagentStop: { agent_type: 'debugger', stop_hook_active: false },
+  PreCompact: { trigger: 'manual' },
+};
+
+test('hook-smoke: every generated plugin launcher runs its hook to exit 0 without a crash log', () => {
+  // A private root holding the tree, so every crash log a hook writes lands under it.
+  const sandbox = fs.mkdtempSync(path.join(work, 'smoke-'));
+  const smokeTree = lib.build(path.join(sandbox, 'plugin', 'cf-codex'));
+  const repo = path.join(sandbox, 'repo');
+  fs.mkdirSync(repo);
+  spawnSync('git', ['init', '-q'], { cwd: repo });
+  const data = path.join(sandbox, 'data');
+  const failures = [];
+  for (const handler of pluginHandlers()) {
+    const payload = { session_id: 'codex-smoke', hook_event_name: handler.event, cwd: repo, ...(SAMPLE_PAYLOADS[handler.event] || {}) };
+    const run = spawnSync('sh', ['-c', handler.command], {
+      cwd: repo, input: JSON.stringify(payload), encoding: 'utf8', timeout: 20000,
+      env: { ...process.env, HOME: path.join(sandbox, 'home'), PLUGIN_ROOT: smokeTree, PLUGIN_DATA: data, CLAUDE_PLUGIN_ROOT: smokeTree, CLAUDE_PLUGIN_DATA: data },
+    });
+    if (run.status !== 0) failures.push(`${handler.event} ${handler.command}: exit ${run.status} ${run.stderr.slice(0, 200)}`);
+  }
+  const crashLogs = walk(sandbox).filter((f) => f.endsWith('hook-log.jsonl'))
+    .filter((f) => /"status":"crash"/.test(fs.readFileSync(path.join(sandbox, f), 'utf8')));
+  for (const log of crashLogs) failures.push(`crash logged in ${log}: ${fs.readFileSync(path.join(sandbox, log), 'utf8').slice(0, 200)}`);
+  assert.deepEqual(failures, []);
+});