@haposoft/cafekit 0.18.2 → 0.18.3

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

@@ -0,0 +1,220 @@
+'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 crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+const BUILD = path.resolve(__dirname, '../../scripts/build-codex-plugin.mjs');
+const INSTALL = path.resolve(__dirname, '../install.js');
+const UID = typeof process.getuid === 'function' ? process.getuid() : 'user';
+let lib;
+let work;
+let tree;
+let handlers;
+
+function walk(root) {
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(root, entry.name);
+    return entry.isDirectory() ? [`${full}/`, ...walk(full)] : [full];
+  }).sort();
+}
+
+function git(cwd, ...args) {
+  const run = spawnSync('git', ['-c', 'user.email=t@t', '-c', 'user.name=t', ...args], { cwd, encoding: 'utf8' });
+  assert.equal(run.status, 0, run.stderr);
+  return run.stdout.trim();
+}
+
+function repo(name, setup = () => {}) {
+  const dir = path.join(work, name);
+  fs.mkdirSync(dir, { recursive: true });
+  git(dir, 'init', '-q');
+  fs.writeFileSync(path.join(dir, 'README.md'), '# demo\n');
+  fs.writeFileSync(path.join(dir, '.env'), 'EXAMPLE=placeholder\n');
+  setup(dir);
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '-qm', 'fixture');
+  return dir;
+}
+
+function packet(dir, status) {
+  fs.mkdirSync(path.join(dir, 'specs/demo'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'specs/demo/plan.md'), '# Demo\nSpecs-Contract: process-first-ready-v1\n\n## Tasks\n| # | Task | Status |\n|---|---|---|\n| 01 | Demo | pending |\n');
+  fs.writeFileSync(path.join(dir, 'specs/demo/task-01-demo.md'), `# Task 01 — Demo\n\nStatus: ${status}\n\n## Dependencies\n- none\n\n## Verification Plan\n- Command: \`test -f README.md\`\n\n## Receipt\n`);
+}
+
+function handler(event, script) {
+  const found = handlers.find((h) => h.event === event && h.command.includes(`/hooks/${script}"`));
+  assert.ok(found, `no ${event} handler for ${script}`);
+  return found.command;
+}
+
+// Runs one plugin hook through its generated launcher, the way Codex starts it.
+function run(event, script, cwd, payload = {}, env = {}) {
+  const result = spawnSync('sh', ['-c', handler(event, script)], {
+    cwd,
+    input: JSON.stringify({ session_id: 'plugin-hooks-test', hook_event_name: event, cwd, ...payload }),
+    encoding: 'utf8',
+    timeout: 20000,
+    env: { ...process.env, HOME: path.join(work, 'home'), PLUGIN_ROOT: tree, CLAUDE_PLUGIN_ROOT: tree, PLUGIN_DATA: path.join(work, 'data'), CLAUDE_PLUGIN_DATA: path.join(work, 'data'), ...env },
+  });
+  return result;
+}
+
+const ALL = [
+  ['SessionStart', 'session.cjs', { source: 'startup' }],
+  ['UserPromptSubmit', 'rules.cjs', { prompt: 'hello' }],
+  ['PreToolUse', 'privacy-block.cjs', { tool_name: 'Bash', tool_input: { command: 'ls' } }],
+  ['PreToolUse', 'inspect-block.cjs', { tool_name: 'Bash', tool_input: { command: 'ls' } }],
+  ['PostToolUse', 'spec-state.cjs', { tool_name: 'apply_patch', tool_input: { command: '' }, tool_response: {} }],
+  ['PreCompact', 'precompact.cjs', { trigger: 'manual' }],
+  ['Stop', 'spec-gate.cjs', { stop_hook_active: false }],
+  ['Stop', 'state.cjs', { stop_hook_active: false }],
+];
+
+before(async () => {
+  lib = await import(BUILD);
+  work = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-codex-plugin-hooks-'));
+  tree = lib.build(path.join(work, 'plugin', 'cf-codex'));
+  const { hooks } = JSON.parse(fs.readFileSync(path.join(tree, 'hooks/hooks.json'), 'utf8'));
+  handlers = Object.entries(hooks).flatMap(([event, groups]) => groups.flatMap((g) => g.hooks.map((h) => ({ event, ...h }))));
+});
+
+after(() => fs.rmSync(work, { recursive: true, force: true }));
+
+test('gate-blocks-in-payload-repo: Stop blocks a done task without a receipt in the payload repository', () => {
+  const dir = repo('gate', (d) => packet(d, 'done'));
+  const result = run('Stop', 'spec-gate.cjs', dir, { stop_hook_active: false });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /"decision":"block"/);
+  assert.match(result.stdout, /task-01-demo\.md/);
+});
+
+test('privacy-uses-payload-repo: reading the payload repository .env is denied and the approval is keyed to it', () => {
+  const dir = repo('privacy');
+  const data = path.join(work, 'privacy-data');
+  const result = run('PreToolUse', 'privacy-block.cjs', dir, { tool_name: 'Bash', tool_input: { command: 'cat .env' } }, { PLUGIN_DATA: data, CLAUDE_PLUGIN_DATA: data });
+  assert.match(result.stdout, /"permissionDecision":"deny"/);
+  const key = crypto.createHash('sha256').update(fs.realpathSync(dir)).digest('hex').slice(0, 16);
+  assert.ok(walk(path.join(data, 'projects', key, 'privacy')).some((p) => !p.endsWith('/')), 'no pending approval stored for this repository');
+});
+
+test('nothing-written-outside-data: every hook leaves the repository, the plugin tree and its parent unchanged', () => {
+  const dir = repo('clean', (d) => fs.mkdirSync(path.join(d, '.codex')) || fs.writeFileSync(path.join(d, '.codex/runtime.json'), '{}\n'));
+  const data = path.join(work, 'clean-data');
+  // Git's own .git/ files (an index refresh, a lock left by a timed-out git call) are not
+  // CafeKit state, so the working tree is compared and git must report it clean.
+  const worktree = () => walk(dir).filter((p) => !p.startsWith(path.join(dir, '.git') + path.sep) && p !== `${path.join(dir, '.git')}/`);
+  const before = [worktree(), walk(path.join(work, 'plugin'))];
+  for (const [event, script, payload] of ALL) {
+    const result = run(event, script, dir, payload, { PLUGIN_DATA: data, CLAUDE_PLUGIN_DATA: data });
+    assert.equal(result.status, 0, `${script}: ${result.stderr}`);
+  }
+  assert.deepEqual([worktree(), walk(path.join(work, 'plugin'))], before);
+  assert.equal(git(dir, 'status', '--porcelain'), '', 'the hooks left changes in the repository');
+  assert.ok(walk(data).some((p) => !p.endsWith('/')), 'no state under PLUGIN_DATA');
+});
+
+test('tmp-root-0700: without PLUGIN_DATA, state goes to a private per-user temp directory', () => {
+  const dir = repo('tmp');
+  const tmp = fs.mkdtempSync(path.join(work, 'tmp-'));
+  for (const [event, script, payload] of ALL) run(event, script, dir, payload, { PLUGIN_DATA: '', CLAUDE_PLUGIN_DATA: '', TMPDIR: tmp });
+  const root = path.join(tmp, `cafekit-codex-plugin-${UID}`);
+  assert.ok(fs.lstatSync(root).isDirectory());
+  assert.equal(fs.statSync(root).mode & 0o777, 0o700);
+});
+
+test('foreign-tmp-fail-closed: a temp state root this user does not safely own makes privacy deny', () => {
+  const dir = repo('foreign');
+  const tmp = fs.mkdtempSync(path.join(work, 'tmp-foreign-'));
+  const elsewhere = fs.mkdtempSync(path.join(work, 'elsewhere-'));
+  fs.symlinkSync(elsewhere, path.join(tmp, `cafekit-codex-plugin-${UID}`));
+  const result = run('PreToolUse', 'privacy-block.cjs', dir, { tool_name: 'Bash', tool_input: { command: 'cat .env' } }, { PLUGIN_DATA: '', CLAUDE_PLUGIN_DATA: '', TMPDIR: tmp });
+  assert.match(result.stdout, /"permissionDecision":"deny"/);
+  assert.deepEqual(walk(elsewhere), [], 'state was written through the planted symlink');
+});
+
+test('no-npx-notice: the plugin session hook prints no npx update notice and keeps the update cache', () => {
+  const dir = repo('notice', (d) => {
+    fs.mkdirSync(path.join(d, '.codex'));
+    fs.writeFileSync(path.join(d, '.codex/cafekit.json'), JSON.stringify({ version: '0.0.1' }));
+  });
+  const cache = path.join(dir, '.codex/.cafekit-update-cache.json');
+  const bytes = JSON.stringify({ ts: Date.now(), latest: '99.0.0' });
+  fs.writeFileSync(cache, bytes);
+  const result = run('SessionStart', 'session.cjs', dir, { source: 'startup' });
+  assert.equal(result.status, 0, result.stderr);
+  assert.doesNotMatch(result.stdout, /npx @haposoft\/cafekit/);
+  assert.equal(fs.readFileSync(cache, 'utf8'), bytes);
+});
+
+test('defaults-without-runtime: without .codex/runtime.json the rules hook still injects the repository paths', () => {
+  const dir = repo('defaults');
+  const result = run('UserPromptSubmit', 'rules.cjs', dir, { prompt: 'hello', session_id: 'defaults-session' });
+  assert.equal(result.status, 0, result.stderr);
+  assert.ok(result.stdout.includes(path.join(fs.realpathSync(dir), 'specs')), result.stdout);
+});
+
+function npxRepo(name) {
+  const dir = repo(name);
+  const install = spawnSync('node', [INSTALL, '--platform', 'codex', '-y'], { cwd: dir, encoding: 'utf8', env: { ...process.env, HOME: path.join(work, `home-${name}`) } });
+  assert.equal(install.status, 0, install.stderr || install.stdout);
+  return dir;
+}
+
+test('silent-beside-npx: with the npx Codex hooks active in the repository, plugin hooks stand down and say so once', () => {
+  const dir = npxRepo('beside');
+  const session = run('SessionStart', 'session.cjs', dir, { source: 'startup' });
+  assert.equal(session.status, 0, session.stderr);
+  assert.match(session.stdout, /CafeKit plugin is idle/);
+  assert.match(session.stdout, /\$cf-/, 'the notice names the duplicate skills');
+  assert.match(session.stdout, /trusted in \/hooks/, 'the notice says the gates depend on trusting the npx hooks');
+  assert.ok(session.stdout.includes('npx @haposoft/cafekit@latest migrate'), 'the notice names the migrate command with @latest');
+  const privacy = run('PreToolUse', 'privacy-block.cjs', dir, { tool_name: 'Bash', tool_input: { command: 'cat .env' } });
+  assert.equal(privacy.status, 0);
+  assert.equal(privacy.stdout, '', 'the plugin hook acted beside the npx hooks');
+  const rules = run('UserPromptSubmit', 'rules.cjs', dir, { prompt: 'hi', session_id: 'beside-rules' });
+  assert.equal(rules.stdout, '');
+});
+
+test('planted-hooks-json-keeps-gates: a hooks.json without real npx hooks behind it does not switch the plugin off', () => {
+  const cases = {
+    planted: { description: 'x /.codex/hooks/ x', hooks: {} },
+    foreignMachine: { hooks: { PreToolUse: [{ hooks: [{ type: 'command', command: "node '/Users/someone-else/project/.codex/hooks/privacy-block.cjs'" }] }] } },
+    relativeScript: { hooks: { PreToolUse: [{ hooks: [{ type: 'command', command: "node './.codex/hooks/noop.cjs'" }] }] } },
+  };
+  // Absolute paths that still reach the repository's own hooks only through `..` or a
+  // symlinked alias; on Linux /proc/self/cwd does the same through the hook's cwd.
+  const alias = path.join(work, 'planted-alias-link');
+  const command = (script) => ({ hooks: { PreToolUse: [{ hooks: [{ type: 'command', command: `node '${script}'` }] }] } });
+  cases.dotDot = (d) => command(`${fs.realpathSync(d)}/.codex/hooks/../hooks/noop.cjs`);
+  cases.symlinkAlias = (d) => { fs.symlinkSync(fs.realpathSync(d), alias); return command(`${alias}/.codex/hooks/noop.cjs`); };
+  for (const [name, entry] of Object.entries(cases)) {
+    const dir = repo(`planted-${name}`, (d) => {
+      const config = typeof entry === 'function' ? entry(d) : entry;
+      fs.mkdirSync(path.join(d, '.codex/hooks'), { recursive: true });
+      fs.writeFileSync(path.join(d, '.codex/hooks/noop.cjs'), '\n');
+      fs.writeFileSync(path.join(d, '.codex/hooks.json'), JSON.stringify(config));
+    });
+    const result = run('PreToolUse', 'privacy-block.cjs', dir, { tool_name: 'Bash', tool_input: { command: 'cat .env' } });
+    assert.match(result.stdout, /"permissionDecision":"deny"/, `${name}: the plugin stood down`);
+  }
+});
+
+test('npx-installed-tree: npx-installed hooks keep their behavior, even with a plugin root inherited from the parent', () => {
+  const dir = npxRepo('npx');
+  for (const inherited of [false, true]) {
+    const env = { ...process.env, HOME: path.join(work, 'home-npx') };
+    delete env.PLUGIN_ROOT; delete env.CLAUDE_PLUGIN_ROOT; delete env.PLUGIN_DATA; delete env.CLAUDE_PLUGIN_DATA;
+    if (inherited) Object.assign(env, { PLUGIN_ROOT: tree, CLAUDE_PLUGIN_ROOT: tree });
+    const payload = { session_id: `npx-${inherited}`, hook_event_name: 'PreToolUse', cwd: dir, tool_name: 'Bash', tool_input: { command: 'cat .env' } };
+    const result = spawnSync('node', [path.join(dir, '.codex/hooks/privacy-block.cjs')], { cwd: dir, input: JSON.stringify(payload), encoding: 'utf8', env });
+    assert.match(result.stdout, /"permissionDecision":"deny"/, `inherited=${inherited}`);
+    assert.ok(fs.existsSync(path.join(dir, '.codex/hooks/.privacy')), 'npx privacy state left its project location');
+  }
+});

package/bin/__tests__/codex-runtime-layout.test.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SRC = path.resolve(__dirname, '../../src');
+const SHIM = /^(?:['"]use strict['"];?\s*)?module\.exports\s*=\s*require\(['"]\.\.\/\.\.\/\.\.\/claude\/hooks\/lib\/([^'"/]+)['"]\);?\s*$/;
+
+function layout() {
+  return require('../phases/codex-runtime').codexRuntimeLayout();
+}
+
+const destinations = (entries) => entries.map((entry) => entry.dest);
+
+test('shims-resolved: every shim lib ships as the real Claude library, never as the shim', () => {
+  const libDir = path.join(SRC, 'codex/hooks/lib');
+  const shims = fs.readdirSync(libDir).filter((name) => (fs.readFileSync(path.join(libDir, name), 'utf8').match(SHIM) || [])[1] === name);
+  assert.equal(shims.length, 8, `expected 8 shim libraries, found ${shims.join(', ')}`);
+  const entries = layout();
+  for (const name of shims) {
+    const shipped = entries.filter((entry) => entry.dest === `hooks/lib/${name}`);
+    assert.equal(shipped.length, 1, `hooks/lib/${name} shipped ${shipped.length} times`);
+    assert.equal(shipped[0].src, path.join(SRC, 'claude/hooks/lib', name));
+  }
+});
+
+test('hooks-copied: every non-shim Codex hook file ships from the Codex source', () => {
+  const entries = layout();
+  const hooksDir = path.join(SRC, 'codex/hooks');
+  for (const name of fs.readdirSync(hooksDir).filter((n) => n !== 'lib')) {
+    const entry = entries.find((e) => e.dest === `hooks/${name}`);
+    assert.ok(entry, `hooks/${name} missing`);
+    assert.equal(entry.src, path.join(hooksDir, name));
+  }
+  const libDir = path.join(hooksDir, 'lib');
+  for (const name of fs.readdirSync(libDir).filter((n) => !SHIM.test(fs.readFileSync(path.join(libDir, n), 'utf8')))) {
+    const entry = entries.find((e) => e.dest === `hooks/lib/${name}`);
+    assert.ok(entry, `hooks/lib/${name} missing`);
+    assert.equal(entry.src, path.join(libDir, name));
+  }
+});
+
+test('groups-installed: every layout group is one the installer writes', () => {
+  const { LAYOUT_GROUPS } = require('../phases/codex-runtime');
+  const known = LAYOUT_GROUPS.map(([name]) => name);
+  for (const entry of layout()) assert.ok(known.includes(entry.group), `${entry.dest} has unknown group ${entry.group}`);
+});
+
+test('rules-composed: Claude rules minus Codex overrides, plus Codex rules, with the right transform', () => {
+  const entries = layout().filter((entry) => entry.dest.startsWith('rules/'));
+  const overrides = fs.readdirSync(path.join(SRC, 'codex/rules'));
+  const claudeRules = fs.readdirSync(path.join(SRC, 'claude/rules')).filter((name) => !overrides.includes(name));
+  assert.deepEqual(destinations(entries).sort(), [...claudeRules, ...overrides].map((name) => `rules/${name}`).sort());
+  for (const entry of entries) {
+    const override = overrides.includes(path.basename(entry.dest));
+    assert.equal(entry.src, path.join(SRC, override ? 'codex/rules' : 'claude/rules', path.basename(entry.dest)));
+    assert.equal(entry.transform, override ? null : 'codex-body', `${entry.dest} transform`);
+  }
+});
+
+test('styles-and-schema: output styles carry the Codex transform and the schema ships once', () => {
+  const entries = layout();
+  const styles = entries.filter((entry) => entry.dest.startsWith('output-styles/'));
+  assert.deepEqual(destinations(styles).sort(), fs.readdirSync(path.join(SRC, 'claude/output-styles')).map((n) => `output-styles/${n}`).sort());
+  assert.ok(styles.every((entry) => entry.transform === 'codex-body'));
+  const schema = entries.filter((entry) => entry.dest === 'runtime.schema.json');
+  assert.equal(schema.length, 1);
+  assert.equal(schema[0].src, path.join(SRC, 'claude/runtime.schema.json'));
+});
+
+test('sources-exist: every layout source is a regular file and every destination is unique and relative', () => {
+  const entries = layout();
+  assert.equal(new Set(destinations(entries)).size, entries.length, 'duplicate destination');
+  for (const entry of entries) {
+    assert.ok(fs.lstatSync(entry.src).isFile(), `${entry.src} is not a regular file`);
+    assert.ok(!path.isAbsolute(entry.dest) && !entry.dest.split('/').includes('..'), `${entry.dest} escapes the runtime root`);
+    assert.equal(typeof entry.group, 'string');
+  }
+});

package/bin/__tests__/codex-setup-agents.test.js

@@ -0,0 +1,216 @@
+'use strict';
+
+// Codex loads no agents from a plugin, so the plugin ships them as TOML with an
+// ownership marker and a script copies them into the user's Codex agents directory.
+// The script replaces only files whose marker hash still matches their body.
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const SCRIPTS = path.resolve(__dirname, '../../scripts');
+const SRC = path.resolve(__dirname, '../../src');
+const { convertCodexAgentContent, codexAgentName } = require('../lib/codex-install.js');
+const { CODEX_POLICY_FILE, CODEX_EXPLICIT_ONLY_POLICY } = require('../phases/copy-payload.js');
+const MARKER = /^# CafeKit agent: plugin=(\S+) version=(\S+) sha256=([0-9a-f]{64})\n/;
+const REAL_AGENTS = path.join(os.homedir(), '.codex', 'agents');
+let work;
+let tree;
+let agentNames;
+let realBefore;
+
+const sha256 = (text) => crypto.createHash('sha256').update(text).digest('hex');
+
+function realState() {
+  try {
+    const stat = fs.statSync(REAL_AGENTS);
+    return `${stat.mtimeMs}:${fs.readdirSync(REAL_AGENTS).sort().join(',')}`;
+  } catch {
+    return 'absent';
+  }
+}
+
+before(async () => {
+  realBefore = realState();
+  work = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ck-codex-agents-')));
+  const lib = await import(path.join(SCRIPTS, 'build-codex-plugin.mjs'));
+  const claudeLib = await import(path.join(SCRIPTS, 'build-claude-plugin.mjs'));
+  agentNames = claudeLib.inScopeAgents();
+  tree = lib.build(path.join(work, 'plugin', 'cf-codex'));
+});
+
+after(() => {
+  fs.rmSync(work, { recursive: true, force: true });
+  assert.equal(realState(), realBefore, 'the real ~/.codex/agents changed');
+});
+
+let caseCount = 0;
+function setup() {
+  const dir = path.join(work, `case-${++caseCount}`);
+  const home = path.join(dir, 'home');
+  const repo = path.join(dir, 'repo');
+  fs.mkdirSync(home, { recursive: true });
+  fs.mkdirSync(repo, { recursive: true });
+  spawnSync('git', ['init', '-q'], { cwd: repo });
+  return { home, repo, agents: path.join(home, '.codex', 'agents') };
+}
+
+function setupAgents({ home, repo }, args = [], codexHome) {
+  const env = { ...process.env, HOME: home };
+  delete env.CODEX_HOME;
+  if (codexHome !== undefined) env.CODEX_HOME = codexHome;
+  return spawnSync('node', [path.join(tree, 'scripts/setup-agents.cjs'), ...args], { cwd: repo, encoding: 'utf8', env });
+}
+
+function shipped(name) {
+  return fs.readFileSync(path.join(tree, 'agents', name), 'utf8');
+}
+
+// An older CafeKit release of the same agent: a valid marker over a different body.
+function olderOwn(name) {
+  const body = `name = "${name.replace(/\.toml$/, '')}"\ndescription = "an older release"\ndeveloper_instructions = "old"\n`;
+  return `# CafeKit agent: plugin=cf version=0.0.1 sha256=${sha256(body)}\n${body}`;
+}
+
+test('agents-built-with-hash-marker: every in-scope agent ships as TOML whose marker hashes its body', () => {
+  const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../../package.json'), 'utf8'));
+  const files = fs.readdirSync(path.join(tree, 'agents')).sort();
+  assert.deepEqual(files, agentNames.map((agent) => `${codexAgentName(agent)}.toml`).sort());
+  for (const agent of agentNames) {
+    const text = shipped(`${codexAgentName(agent)}.toml`);
+    const [marker, plugin, version, digest] = text.match(MARKER) || [];
+    assert.ok(marker, `${agent} has no marker`);
+    assert.equal(plugin, 'cf');
+    assert.equal(version, pkg.version);
+    const body = text.slice(marker.length);
+    assert.equal(sha256(body), digest, agent);
+    assert.equal(body, convertCodexAgentContent(fs.readFileSync(path.join(SRC, 'claude/agents', `${agent}.md`), 'utf8'), `${agent}.md`), `${agent} differs from the npx conversion`);
+  }
+});
+
+test('write-when-absent: an empty agents directory receives every shipped agent', () => {
+  const ctx = setup();
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  const files = fs.readdirSync(path.join(tree, 'agents')).sort();
+  assert.deepEqual(fs.readdirSync(ctx.agents).sort(), files);
+  for (const file of files) assert.equal(fs.readFileSync(path.join(ctx.agents, file), 'utf8'), shipped(file), file);
+  assert.equal(result.stdout.match(/^written: /gm).length, files.length);
+});
+
+test('replace-own-unmodified: an unedited agent from an older release is replaced', () => {
+  const ctx = setup();
+  fs.mkdirSync(ctx.agents, { recursive: true });
+  fs.writeFileSync(path.join(ctx.agents, 'test_runner.toml'), olderOwn('test_runner.toml'));
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(fs.readFileSync(path.join(ctx.agents, 'test_runner.toml'), 'utf8'), shipped('test_runner.toml'));
+  assert.match(result.stdout, /^replaced: .*test_runner\.toml$/m);
+});
+
+test('keep-modified-own: an agent whose body was edited under the marker keeps its bytes', () => {
+  const ctx = setup();
+  fs.mkdirSync(ctx.agents, { recursive: true });
+  const edited = `${shipped('code_auditor.toml')}# my own note\n`;
+  fs.writeFileSync(path.join(ctx.agents, 'code_auditor.toml'), edited);
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(sha256(fs.readFileSync(path.join(ctx.agents, 'code_auditor.toml'), 'utf8')), sha256(edited));
+  assert.match(result.stdout, /^kept \(modified\): .*code_auditor\.toml$/m);
+});
+
+test('keep-foreign: a file CafeKit did not install keeps its bytes', () => {
+  const ctx = setup();
+  fs.mkdirSync(ctx.agents, { recursive: true });
+  const foreign = 'name = "debugger"\ndescription = "mine"\ndeveloper_instructions = "mine"\n';
+  fs.writeFileSync(path.join(ctx.agents, 'debugger.toml'), foreign);
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(fs.readFileSync(path.join(ctx.agents, 'debugger.toml'), 'utf8'), foreign);
+  assert.match(result.stdout, /^kept \(not installed by CafeKit\): .*debugger\.toml$/m);
+});
+
+test('mode-preserved: replacing an owned agent keeps its file mode', () => {
+  const ctx = setup();
+  fs.mkdirSync(ctx.agents, { recursive: true });
+  const file = path.join(ctx.agents, 'implementer.toml');
+  fs.writeFileSync(file, olderOwn('implementer.toml'), { mode: 0o600 });
+  fs.chmodSync(file, 0o600);
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(fs.readFileSync(file, 'utf8'), shipped('implementer.toml'));
+  assert.equal(fs.statSync(file).mode & 0o777, 0o600);
+  assert.deepEqual(fs.readdirSync(ctx.agents).filter((f) => f.endsWith('.tmp')), [], 'a temp file was left behind');
+});
+
+test('codex-home-honored: an absolute CODEX_HOME receives the agents and a relative one is refused', () => {
+  const ctx = setup();
+  const codexHome = path.join(ctx.home, 'custom-codex-home');
+  const result = setupAgents(ctx, [], codexHome);
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(fs.readdirSync(path.join(codexHome, 'agents')).sort(), fs.readdirSync(path.join(tree, 'agents')).sort());
+  assert.ok(!fs.existsSync(path.join(ctx.home, '.codex')), 'agents also went to ~/.codex');
+  const refused = setup();
+  const relative = setupAgents(refused, [], 'relative-home');
+  assert.equal(relative.status, 1);
+  assert.match(relative.stderr, /CODEX_HOME must be an absolute path/);
+  assert.ok(!fs.existsSync(path.join(refused.repo, 'relative-home')) && !fs.existsSync(path.join(refused.home, '.codex')), 'a refused CODEX_HOME still wrote');
+});
+
+test('unreadable-kept: a file it cannot read is kept and the other agents still install', { skip: process.getuid?.() === 0 }, () => {
+  const ctx = setup();
+  fs.mkdirSync(ctx.agents, { recursive: true });
+  const locked = path.join(ctx.agents, 'debugger.toml');
+  fs.writeFileSync(locked, 'mine\n');
+  fs.chmodSync(locked, 0o000);
+  try {
+    const result = setupAgents(ctx);
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /^kept \(unreadable\): .*debugger\.toml$/m);
+    assert.equal(fs.readdirSync(ctx.agents).length, fs.readdirSync(path.join(tree, 'agents')).length);
+  } finally {
+    fs.chmodSync(locked, 0o600);
+  }
+  assert.equal(fs.readFileSync(locked, 'utf8'), 'mine\n');
+});
+
+test('symlink-kept: a symlinked agent stays a symlink and its target is untouched', () => {
+  const ctx = setup();
+  fs.mkdirSync(ctx.agents, { recursive: true });
+  const elsewhere = path.join(ctx.home, 'dotfiles-researcher.toml');
+  fs.writeFileSync(elsewhere, olderOwn('researcher.toml'));
+  const before = fs.readFileSync(elsewhere, 'utf8');
+  fs.symlinkSync(elsewhere, path.join(ctx.agents, 'researcher.toml'));
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  assert.ok(fs.lstatSync(path.join(ctx.agents, 'researcher.toml')).isSymbolicLink());
+  assert.equal(fs.readlinkSync(path.join(ctx.agents, 'researcher.toml')), elsewhere);
+  assert.equal(fs.readFileSync(elsewhere, 'utf8'), before);
+  assert.match(result.stdout, /^kept \(symlink\): .*researcher\.toml$/m);
+});
+
+test('repo-collision-reported: an agent of the same name in the repository is reported', () => {
+  const ctx = setup();
+  fs.mkdirSync(path.join(ctx.repo, '.codex/agents'), { recursive: true });
+  fs.writeFileSync(path.join(ctx.repo, '.codex/agents/test_runner.toml'), 'name = "test_runner"\n');
+  const result = setupAgents(ctx);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /^collision: .*\.codex\/agents\/test_runner\.toml/m);
+  assert.equal((result.stdout.match(/^collision: /gm) || []).length, 1);
+});
+
+test('skill-explicit-no-target: the skill is explicit-only and the script refuses any argument', () => {
+  const skill = fs.readFileSync(path.join(tree, 'skills/setup-agents/SKILL.md'), 'utf8');
+  assert.match(skill, /^---\nname: cf-setup-agents\n/);
+  assert.match(skill, /\{cafekit:setup-agents\}/);
+  assert.equal(fs.readFileSync(path.join(tree, 'skills/setup-agents', CODEX_POLICY_FILE), 'utf8'), CODEX_EXPLICIT_ONLY_POLICY);
+  const ctx = setup();
+  const target = path.join(ctx.home, 'elsewhere');
+  const result = setupAgents(ctx, [target]);
+  assert.equal(result.status, 2);
+  assert.ok(!fs.existsSync(target) && !fs.existsSync(ctx.agents), 'the script wrote with an argument');
+});

package/bin/__tests__/legacy-hooks-retired.test.js

@@ -4,7 +4,7 @@
 // review authority and the scaffold guard) are gone from every runtime. Each case pins one way
 // they could survive: a fresh install, an upgrade on Claude (settings prune matches by substring,
 // so a user's own hook with the same file name must stay), an upgrade on Codex (whose tracker
-// keys are `.codex/…` and whose handlers come in three shapes), an upgrade on omp, an omp bridge
+// keys are `.codex/…` and whose handlers come in three shapes), an upgrade on omp (hash-checked like Codex), an omp bridge
 // that still lists the removed gates, and the source lists themselves.
 
 const assert = require('node:assert/strict');
@@ -21,7 +21,7 @@ const SRC = path.join(PACKAGE_ROOT, 'src');
 const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
 const MANIFEST = readJson(path.join(SRC, 'claude/migration-manifest.json'));
 const SOURCE_SETTINGS = readJson(path.join(SRC, 'claude/settings/settings.json'));
-const SOURCE_BRIDGE_PATH = path.join(SRC, 'omp/extensions/cafekit-bridge.mjs');
+const SOURCE_BRIDGE_PATH = path.join(SRC, 'omp/extensions/cafekit-bridge.js');
 
 const NAMES = [
   'completion-authority.cjs',
@@ -70,7 +70,7 @@ test('fresh installs ship and register none of the five legacy hooks', () => {
     const claude = commands(readJson(path.join(root, '.claude', 'settings.json')));
     const codex = commands(readJson(path.join(root, '.codex', 'hooks.json')));
     for (const command of [...claude, ...codex]) assert.deepEqual(mentionsName(command), [], command);
-    const bridge = fs.readFileSync(path.join(root, '.omp', 'extensions', 'cafekit-bridge.mjs'), 'utf8');
+    const bridge = fs.readFileSync(path.join(root, '.omp', 'extensions', 'cafekit-bridge.js'), 'utf8');
     assert.deepEqual(mentionsName(bridge), []);
   });
 });
@@ -166,9 +166,10 @@ test('omp upgrade removes the legacy hooks and their records', () => {
     const manifestPath = path.join(root, '.omp', 'cafekit-manifest.json');
     const manifest = readJson(manifestPath);
     // omp records keys relative to the project root (recordRoot '.').
+    const shipped = '// shipped by an older CafeKit\n';
     for (const name of NAMES) {
-      fs.writeFileSync(path.join(root, '.omp', 'hooks', name), '// shipped by an older CafeKit\n');
-      manifest.files[`.omp/hooks/${name}`] = { sha256: '0'.repeat(64) };
+      fs.writeFileSync(path.join(root, '.omp', 'hooks', name), shipped);
+      manifest.files[`.omp/hooks/${name}`] = { sha256: crypto.createHash('sha256').update(shipped).digest('hex') };
     }
     fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
 
@@ -181,28 +182,77 @@ test('omp upgrade removes the legacy hooks and their records', () => {
   });
 });
 
-test('omp upgrade replaces a pristine old bridge that still lists the removed gates', () => {
+test('omp upgrade preserves edited legacy hooks and prunes only absent records', () => {
   inTempProject((root) => {
     install(root, ['omp']);
-    const bridgePath = path.join(root, '.omp', 'extensions', 'cafekit-bridge.mjs');
+    const manifestPath = path.join(root, '.omp', 'cafekit-manifest.json');
+    const manifest = readJson(manifestPath);
+    // A record whose file is already gone must leave the manifest too.
+    for (const name of NAMES) {
+      if (name !== 'completion-authority-state.cjs') fs.writeFileSync(path.join(root, '.omp', 'hooks', name), '// user edit\n');
+      manifest.files[`.omp/hooks/${name}`] = { sha256: '0'.repeat(64) };
+    }
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+    const upgrade = install(root, ['omp']);
+    assert.match(`${upgrade.stdout}\n${upgrade.stderr}`, new RegExp(`Preserved ${NAMES.length - 1} obsolete runtime item`));
+    const after = readJson(manifestPath);
+    for (const name of NAMES) {
+      if (name === 'completion-authority-state.cjs') {
+        assert.equal(after.files[`.omp/hooks/${name}`], undefined, `record ${name}`);
+        continue;
+      }
+      assert.equal(fs.readFileSync(path.join(root, '.omp', 'hooks', name), 'utf8'), '// user edit\n', name);
+      assert.equal(after.files[`.omp/hooks/${name}`].sha256, '0'.repeat(64), `record ${name}`);
+    }
+  });
+});
+
+test('omp upgrade removes a pristine old .mjs bridge, which omp never loads', () => {
+  inTempProject((root) => {
+    install(root, ['omp']);
+    const oldPath = path.join(root, '.omp', 'extensions', 'cafekit-bridge.mjs');
     const manifestPath = path.join(root, '.omp', 'cafekit-manifest.json');
     const old = fs.readFileSync(SOURCE_BRIDGE_PATH, 'utf8')
-      .replace("'inspect-block.cjs']", "'inspect-block.cjs', 'task-scaffold-guard.cjs']")
-      .replace("'rules.cjs', 'spec-state.cjs'", "'rules.cjs', 'completion-authority.cjs', 'spec-state.cjs'")
-      .replace("'spec-gate.cjs', 'state.cjs'", "'spec-gate.cjs', 'completion-authority.cjs', 'state.cjs'");
-    assert.deepEqual(mentionsName(old).sort(), ['completion-authority.cjs', 'task-scaffold-guard.cjs'], 'the fixture lists the removed gates');
-    fs.writeFileSync(bridgePath, old);
+      .replace("'inspect-block.cjs']", "'inspect-block.cjs', 'task-scaffold-guard.cjs']");
+    fs.writeFileSync(oldPath, old);
     const manifest = readJson(manifestPath);
     manifest.files['.omp/extensions/cafekit-bridge.mjs'] = { sha256: crypto.createHash('sha256').update(old).digest('hex') };
     fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
 
     install(root, ['omp']);
-    const installed = fs.readFileSync(bridgePath, 'utf8');
+    assert.equal(fs.existsSync(oldPath), false, 'the pristine .mjs bridge is removed');
+    assert.equal(readJson(manifestPath).files['.omp/extensions/cafekit-bridge.mjs'], undefined, 'and its record');
+    const installed = fs.readFileSync(path.join(root, '.omp', 'extensions', 'cafekit-bridge.js'), 'utf8');
     assert.deepEqual(mentionsName(installed), []);
     assert.equal(installed, fs.readFileSync(SOURCE_BRIDGE_PATH, 'utf8'));
   });
 });
 
+test('omp upgrade keeps an edited, untracked or symlinked old .mjs bridge and says so', () => {
+  for (const shape of ['edited', 'untracked', 'symlink']) {
+    inTempProject((root) => {
+      install(root, ['omp']);
+      const oldPath = path.join(root, '.omp', 'extensions', 'cafekit-bridge.mjs');
+      const manifestPath = path.join(root, '.omp', 'cafekit-manifest.json');
+      const manifest = readJson(manifestPath);
+      if (shape === 'symlink') {
+        const target = path.join(root, 'my-bridge.mjs');
+        fs.writeFileSync(target, '// mine\n');
+        fs.symlinkSync(target, oldPath);
+      } else {
+        fs.writeFileSync(oldPath, '// edited by the user\n');
+        if (shape === 'edited') manifest.files['.omp/extensions/cafekit-bridge.mjs'] = { sha256: '0'.repeat(64) };
+      }
+      fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+      const result = install(root, ['omp']);
+      assert.equal(fs.lstatSync(oldPath).isFile() || fs.lstatSync(oldPath).isSymbolicLink(), true, `${shape} .mjs is kept`);
+      assert.match(`${result.stdout}\n${result.stderr}`, /Preserved \d+ obsolete runtime item/, `${shape} is reported`);
+    });
+  }
+});
+
 test('no source ships, registers or bridges the five legacy hooks', () => {
   for (const name of NAMES) {
     assert.equal(fs.existsSync(path.join(SRC, 'claude/hooks', name)), false, `claude ${name}`);