@haposoft/cafekit 0.18.1 → 0.18.3

package/bin/__tests__/installer-safety.test.js

@@ -97,6 +97,341 @@ function inTempProject(run) {
   }
 }
 
+function runCodexInstaller(root) {
+  return spawnSync(process.execPath, [INSTALLER, '--platform', 'codex', '--yes'], {
+    cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' }
+  });
+}
+
+function rootFileGit(root, args) {
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+  assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+  return result.stdout;
+}
+
+function commitRootFile(root, file) {
+  rootFileGit(root, ['init', '-q']);
+  const content = file === 'AGENTS.md' ? upsertManagedCoreBlock('', SHARED_TEMPLATE) : TEMPLATE;
+  fs.writeFileSync(path.join(root, file), `${content}\n## Project notes\nKeep these project notes.\n`);
+  rootFileGit(root, ['add', '--', file]);
+  rootFileGit(root, ['-c', 'user.name=CafeKit Fixture', '-c', 'user.email=cafekit-fixture@example.invalid',
+    'commit', '--no-gpg-sign', '-qm', 'root file fixture']);
+}
+
+function runRootFileInstaller(root, platform, args = [], env = {}) {
+  return spawnSync(process.execPath,
+    [INSTALLER, '--platform', platform, '--yes', '--without-document-skills', ...args],
+    { cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin', ...env } });
+}
+
+for (const [file, platform, args] of [
+  ['AGENTS.md', 'claude', []], ['CLAUDE.md', 'claude', []],
+  ['AGENTS.md', 'codex', []], ['AGENTS.md', 'omp', []],
+  ['AGENTS.md', 'claude', ['--dry-run']],
+]) {
+  test(`missing tracked ${file} stops ${platform} installation${args.length ? ' in dry-run' : ''} before writes`, () => {
+    inTempProject(root => {
+      commitRootFile(root, file);
+      fs.unlinkSync(path.join(root, file));
+      const before = fs.readdirSync(root).filter(name => name !== '.cafekit.lock');
+      const result = runRootFileInstaller(root, platform, args);
+      const output = `${result.stdout}\n${result.stderr}`;
+      assert.notEqual(result.status, 0, output);
+      assert.ok(output.includes(`git checkout -- ${file}`), output);
+      assert.ok(output.includes(`git rm ${file}`), output);
+      assert.deepEqual(fs.readdirSync(root).filter(name => name !== '.cafekit.lock'), before);
+      for (const name of ['AGENTS.md', 'CLAUDE.md', '.claude', '.codex', '.agents', '.omp', '.cafekit-backup']) {
+        assert.equal(fs.existsSync(path.join(root, name)), false, name);
+      }
+    });
+  });
+}
+
+for (const assumeUnchanged of [false, true]) {
+  test(`missing skip-worktree AGENTS.md permits installation${assumeUnchanged ? ' with assume-unchanged' : ''}`, () => {
+    inTempProject(root => {
+      commitRootFile(root, 'AGENTS.md');
+      rootFileGit(root, ['update-index', '--skip-worktree', '--', 'AGENTS.md']);
+      if (assumeUnchanged) rootFileGit(root, ['update-index', '--assume-unchanged', '--', 'AGENTS.md']);
+      assert.match(rootFileGit(root, ['ls-files', '-v', '--', 'AGENTS.md']), assumeUnchanged ? /^s / : /^S /);
+      fs.unlinkSync(path.join(root, 'AGENTS.md'));
+      const result = runRootFileInstaller(root, 'claude');
+      assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+      assert.ok(fs.existsSync(path.join(root, 'AGENTS.md')));
+    });
+  });
+}
+
+test('a tracked dangling CLAUDE.md symlink is present for the root preflight', () => {
+  inTempProject(root => {
+    rootFileGit(root, ['init', '-q']);
+    fs.mkdirSync(path.join(root, 'notes'));
+    fs.symlinkSync('notes/claude.md', path.join(root, 'CLAUDE.md'));
+    rootFileGit(root, ['add', '--', 'CLAUDE.md']);
+    rootFileGit(root, ['-c', 'user.name=CafeKit Fixture', '-c', 'user.email=cafekit-fixture@example.invalid',
+      'commit', '--no-gpg-sign', '-qm', 'root symlink fixture']);
+    const result = runRootFileInstaller(root, 'claude');
+    const output = `${result.stdout}\n${result.stderr}`;
+    assert.notEqual(result.status, 0, output);
+    assert.doesNotMatch(output, /tracked by git but missing/);
+    assert.match(output, /Refusing to follow symlinked managed path/);
+    assert.equal(fs.readlinkSync(path.join(root, 'CLAUDE.md')), 'notes/claude.md');
+    assert.equal(fs.existsSync(path.join(root, 'notes/claude.md')), false);
+    assert.deepEqual(fs.readdirSync(path.join(root, 'notes')), []);
+  });
+});
+
+test('uncertain git ownership warns and permits a fresh root file', () => {
+  inTempProject(root => {
+    commitRootFile(root, 'AGENTS.md');
+    fs.unlinkSync(path.join(root, 'AGENTS.md'));
+    const result = runRootFileInstaller(root, 'claude', [], {
+      GIT_TEST_ASSUME_DIFFERENT_OWNER: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1',
+    });
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    assert.match(`${result.stdout}\n${result.stderr}`, /Could not confirm git state for AGENTS\.md; installing a fresh copy\./);
+    assert.ok(fs.existsSync(path.join(root, 'AGENTS.md')));
+  });
+});
+
+test('Codex installation leaves a missing tracked CLAUDE.md alone', () => {
+  inTempProject(root => {
+    commitRootFile(root, 'CLAUDE.md');
+    fs.unlinkSync(path.join(root, 'CLAUDE.md'));
+    const result = runRootFileInstaller(root, 'codex');
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    assert.equal(fs.existsSync(path.join(root, 'CLAUDE.md')), false);
+  });
+});
+
+test('a root file removed from the git index can be freshly installed', () => {
+  inTempProject(root => {
+    commitRootFile(root, 'AGENTS.md');
+    rootFileGit(root, ['rm', '--', 'AGENTS.md']);
+    const result = runRootFileInstaller(root, 'claude');
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    assert.ok(fs.existsSync(path.join(root, 'AGENTS.md')));
+    assert.doesNotMatch(`${result.stdout}\n${result.stderr}`, /Could not confirm git state/);
+  });
+});
+
+test('a project outside git installs root files without a git-state warning', () => {
+  inTempProject(root => {
+    const result = runRootFileInstaller(root, 'claude');
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    assert.ok(fs.existsSync(path.join(root, 'AGENTS.md')));
+    assert.doesNotMatch(`${result.stdout}\n${result.stderr}`, /Could not confirm git state/);
+  });
+});
+
+test('an existing tracked root file retains notes after its managed marker', () => {
+  inTempProject(root => {
+    commitRootFile(root, 'AGENTS.md');
+    const result = runRootFileInstaller(root, 'claude');
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    assert.match(fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8'), /CAFEKIT CORE END -->[\s\S]*Keep these project notes\./);
+  });
+});
+
+const NOTES_HOME = 'Project notes (commands, files to leave unchanged, slow or expensive operations) belong in the root AGENTS.md after the CAFEKIT CORE END marker';
+const normalizeWhitespace = text => text.replace(/\s+/g, ' ').trim();
+
+test('the installed Claude block points project notes to the shared root with a quoted import', () => {
+  inTempProject(root => {
+    const result = runRootFileInstaller(root, 'claude');
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    const body = normalizeWhitespace(managedBody(fs.readFileSync(path.join(root, 'CLAUDE.md'), 'utf8'), START, END));
+    assert.ok(body.includes(`${NOTES_HOME}; Claude Code reads them through \`@AGENTS.md\`.`), body);
+    assert.doesNotMatch(body, /@AGENTS\.md\./);
+    assert.doesNotMatch(body, /Codex|\.codex|\$cf-/i);
+  });
+});
+
+test('the installed Codex block points project notes to the shared root directly', () => {
+  inTempProject(root => {
+    const result = runRootFileInstaller(root, 'codex');
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    const body = normalizeWhitespace(managedBody(fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8'), CODEX_START, CODEX_END));
+    assert.ok(body.includes(`${NOTES_HOME}; Codex reads AGENTS.md directly.`), body);
+  });
+});
+
+test('the package README preserves root ownership and names one project-notes home for both hosts', () => {
+  const readme = normalizeWhitespace(fs.readFileSync(path.join(__dirname, '../../README.md'), 'utf8'));
+  const note = `${NOTES_HOME}; Claude Code reads them through \`@AGENTS.md\` and Codex reads AGENTS.md directly.`;
+  const ownership = 'CafeKit owns only its marked block inside the project-root `CLAUDE.md`; project instructions outside that block are preserved across installs and upgrades.';
+  assert.ok(readme.includes(`${ownership} ${note}`));
+  assert.ok(readme.includes(`Claude statusline. ${note}`));
+});
+
+for (const host of ['claude', 'codex']) {
+  for (const state of ['pristine file', 'modified file', 'untracked file', 'external symlink', 'dangling symlink', 'pristine directory', 'directory with an extra file', 'directory with a modified file', 'directory with a symlink']) {
+    test(`${host} obsolete cleanup safely handles a ${state}`, () => {
+      const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-obsolete-outside-'));
+      try {
+        inTempProject(root => {
+          const run = () => spawnSync(process.execPath, [INSTALLER, '--platform', host, '--yes', '--force-overwrite'], {
+            cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' }
+          });
+          const first = run();
+          assert.equal(first.status, 0, first.stderr);
+          const folder = `.${host}`;
+          const manifestPath = path.join(root, folder, 'cafekit-manifest.json');
+          const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+          const directory = state.includes('directory');
+          const relative = directory
+            ? (host === 'codex' ? '.agents/skills/generate-graph' : '.claude/skills/generate-graph')
+            : `${folder}/hooks/usage.cjs`;
+          const target = path.join(root, relative);
+          const keyFor = relative => host === 'codex' ? relative : relative.slice('.claude/'.length);
+          const records = {};
+          const record = (relative, bytes) => {
+            const key = keyFor(relative);
+            records[key] = { sha256: sha256(bytes) };
+            manifest.files[key] = records[key];
+          };
+          const external = path.join(outside, 'target.txt');
+          if (state !== 'dangling symlink') fs.writeFileSync(external, 'outside bytes\n');
+          fs.mkdirSync(path.dirname(target), { recursive: true });
+          if (directory) {
+            fs.mkdirSync(path.join(target, 'nested'), { recursive: true });
+            fs.writeFileSync(path.join(target, 'tracked.txt'), state.includes('modified') ? 'changed\n' : 'installed\n');
+            fs.writeFileSync(path.join(target, 'nested/second.txt'), 'second\n');
+            record(`${relative}/tracked.txt`, 'installed\n');
+            record(`${relative}/nested/second.txt`, 'second\n');
+            if (state.includes('extra')) fs.writeFileSync(path.join(target, 'foreign.txt'), 'user bytes\n');
+            if (state.includes('symlink')) {
+              fs.symlinkSync(external, path.join(target, 'linked.txt'));
+              record(`${relative}/linked.txt`, 'outside bytes\n');
+            }
+          } else if (state.includes('symlink')) {
+            fs.symlinkSync(external, target);
+            record(relative, 'outside bytes\n');
+          } else {
+            fs.writeFileSync(target, state === 'modified file' ? 'changed\n' : 'installed\n');
+            if (state !== 'untracked file') record(relative, 'installed\n');
+          }
+          fs.writeFileSync(manifestPath, JSON.stringify(manifest));
+          const again = run();
+          assert.equal(again.status, 0, `${again.stdout}\n${again.stderr}`);
+          const preserved = !state.startsWith('pristine');
+          assert.equal(fs.existsSync(target) || state === 'dangling symlink' && fs.lstatSync(target).isSymbolicLink(), preserved);
+          const after = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+          for (const [key, value] of Object.entries(records)) {
+            if (preserved) assert.deepEqual(after.files[key], value, key);
+            else assert.equal(after.files[key], undefined, key);
+          }
+          if (state.includes('symlink')) {
+            const link = directory ? path.join(target, 'linked.txt') : target;
+            assert.ok(fs.lstatSync(link).isSymbolicLink());
+            assert.equal(fs.readlinkSync(link), external);
+          }
+          if (state !== 'dangling symlink') assert.equal(fs.readFileSync(external, 'utf8'), 'outside bytes\n');
+          else assert.equal(fs.existsSync(external), false);
+          const warnings = `${again.stdout}\n${again.stderr}`.split('\n').filter(line => /Preserved \d+ obsolete runtime/.test(line));
+          assert.equal(warnings.length, preserved ? 1 : 0);
+          if (preserved) {
+            assert.match(warnings[0], /Preserved 1 obsolete runtime/);
+            assert.match(warnings[0], /manually/i);
+          }
+        });
+      } finally {
+        fs.rmSync(outside, { recursive: true, force: true });
+      }
+    });
+  }
+}
+
+test('combined install emits one aggregate warning for preserved obsolete runtime items', () => {
+  inTempProject(root => {
+    assert.equal(runCombinedInstaller(root).status, 0);
+    for (const host of ['claude', 'codex']) {
+      fs.writeFileSync(path.join(root, `.${host}/hooks/usage.cjs`), 'user bytes\n');
+    }
+    const again = runCombinedInstaller(root);
+    assert.equal(again.status, 0, again.stderr);
+    const warnings = `${again.stdout}\n${again.stderr}`.split('\n').filter(line => /Preserved \d+ obsolete runtime/.test(line));
+    assert.equal(warnings.length, 1);
+    assert.match(warnings[0], /Preserved 2 obsolete runtime/);
+    assert.match(warnings[0], /manually/i);
+    for (const host of ['claude', 'codex']) assert.equal(fs.readFileSync(path.join(root, `.${host}/hooks/usage.cjs`), 'utf8'), 'user bytes\n');
+  });
+});
+
+test('combined install removes pristine obsolete files after each host tracker is available', () => {
+  inTempProject(root => {
+    assert.equal(runCombinedInstaller(root).status, 0);
+    for (const host of ['claude', 'codex']) {
+      const target = path.join(root, `.${host}/hooks/usage.cjs`);
+      fs.writeFileSync(target, 'installed bytes\n');
+      const manifestPath = path.join(root, `.${host}/cafekit-manifest.json`);
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      const key = host === 'codex' ? '.codex/hooks/usage.cjs' : 'hooks/usage.cjs';
+      manifest.files[key] = { sha256: sha256('installed bytes\n') };
+      fs.writeFileSync(manifestPath, JSON.stringify(manifest));
+    }
+    const again = runCombinedInstaller(root);
+    assert.equal(again.status, 0, again.stderr);
+    for (const host of ['claude', 'codex']) {
+      assert.equal(fs.existsSync(path.join(root, `.${host}/hooks/usage.cjs`)), false, host);
+      const manifest = JSON.parse(fs.readFileSync(path.join(root, `.${host}/cafekit-manifest.json`), 'utf8'));
+      assert.equal(manifest.files[host === 'codex' ? '.codex/hooks/usage.cjs' : 'hooks/usage.cjs'], undefined, host);
+    }
+    assert.doesNotMatch(again.stdout + again.stderr, /Preserved \d+ obsolete runtime/);
+  });
+});
+
+test('identical Codex reinstall does not report hook helpers or rules updated', () => {
+  inTempProject(root => {
+    const first = runCodexInstaller(root);
+    assert.equal(first.status, 0, first.stderr);
+    const second = runCodexInstaller(root);
+    assert.equal(second.status, 0, second.stderr);
+    const labels = ['Codex native hooks', 'Codex privacy command analyzer', 'Codex privacy path analyzer',
+      'Codex secret keyword matcher', 'Codex runtime path safety', 'Codex inspection path analyzer',
+      'Codex spec touch helpers', 'Codex update check', 'Codex native rule overrides', 'rules/ directory'];
+    const updates = `${second.stdout}\n${second.stderr}`.split('\n')
+      .filter(line => line.includes('↻') && labels.some(label => line.includes(label)));
+    assert.deepEqual(updates, []);
+  });
+});
+
+test('installed Codex hook libraries match canonical bytes and contain no source shims', () => {
+  inTempProject(root => {
+    const result = runCodexInstaller(root);
+    assert.equal(result.status, 0, result.stderr);
+    const sourceRoot = path.join(__dirname, '../../src');
+    const libs = path.join(sourceRoot, 'codex/hooks/lib');
+    const shim = /^(?:['"]use strict['"];?\s*)?module\.exports\s*=\s*require\(['"]\.\.\/\.\.\/\.\.\/claude\/hooks\/lib\/([^'"]+)['"]\);?\s*$/;
+    for (const name of fs.readdirSync(libs)) {
+      const source = fs.readFileSync(path.join(libs, name), 'utf8');
+      const match = source.match(shim);
+      if (match) assert.equal(match[1], name);
+      const expected = path.join(sourceRoot, match ? 'claude/hooks/lib' : 'codex/hooks/lib', name);
+      const installed = fs.readFileSync(path.join(root, '.codex/hooks/lib', name));
+      assert.doesNotMatch(installed.toString(), shim, name);
+      assert.deepEqual(installed, fs.readFileSync(expected), name);
+    }
+  });
+});
+
+test('installed Claude runtime omits retired usage configuration', () => {
+  inTempProject(root => {
+    const result = runCombinedInstaller(root);
+    assert.equal(result.status, 0, result.stderr);
+    const runtime = JSON.parse(fs.readFileSync(path.join(root, '.claude/runtime.json'), 'utf8'));
+    assert.equal(Object.hasOwn(runtime, 'usage'), false);
+  });
+});
+
+test('multimodal setup scripts keep local resolution without the missing resolver', () => {
+  for (const name of ['check_setup.py', 'gemini_batch_process.py']) {
+    const content = fs.readFileSync(path.join(__dirname, '../../src/claude/skills/ai-multimodal/scripts', name), 'utf8');
+    assert.doesNotMatch(content, /resolve_env|CENTRALIZED_RESOLVER_AVAILABLE/, name);
+    assert.ok(content.includes("os.getenv('GEMINI_API_KEY')"), name);
+  }
+});
+
 test('legacy managed root gitignore migrates A13 plan patterns and preserves user content', () => {
   inTempProject((root) => {
     fs.writeFileSync('.gitignore', [

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',
@@ -48,6 +48,7 @@ function install(root, platforms) {
   const result = spawnSync(process.execPath, [INSTALLER, '--platform', platforms.join(','), '--yes'],
     { cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } });
   assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+  return result;
 }
 
 function commands(settings) {
@@ -69,12 +70,12 @@ 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), []);
   });
 });
 
-test('claude upgrade removes the legacy hooks and their CafeKit entries but keeps foreign ones', () => {
+test('claude upgrade preserves edited legacy hooks while removing their CafeKit entries', () => {
   inTempProject((root) => {
     install(root, ['claude']);
     const settingsPath = path.join(root, '.claude', 'settings.json');
@@ -99,10 +100,11 @@ test('claude upgrade removes the legacy hooks and their CafeKit entries but keep
     settings.hooks.SubagentStop[0].hooks.push({ type: 'command', command: cmd('semantic-review-authority.cjs') });
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 
-    install(root, ['claude']);
-    for (const name of NAMES) assert.equal(fs.existsSync(path.join(root, '.claude', 'hooks', name)), false, name);
+    const upgrade = install(root, ['claude']);
+    assert.match(upgrade.stdout + upgrade.stderr, /Preserved 5 obsolete runtime/);
+    for (const name of NAMES) assert.equal(fs.readFileSync(path.join(root, '.claude', 'hooks', name), 'utf8'), '// user edit\n', name);
     const after = readJson(manifestPath);
-    for (const name of NAMES) assert.equal(Object.prototype.hasOwnProperty.call(after.files, `hooks/${name}`), false, `record ${name}`);
+    for (const name of NAMES) assert.equal(after.files[`hooks/${name}`].sha256, '0'.repeat(64), `record ${name}`);
     const afterCommands = commands(readJson(settingsPath));
     for (const name of REGISTERED) {
       assert.equal(afterCommands.some((command) => command.includes(`.claude/hooks/${name}`)), false, name);
@@ -112,7 +114,7 @@ test('claude upgrade removes the legacy hooks and their CafeKit entries but keep
   });
 });
 
-test('codex upgrade removes the legacy hooks, their records and their CafeKit entries but keeps foreign ones', () => {
+test('codex upgrade preserves edited legacy hooks and prunes only absent records', () => {
   inTempProject((root) => {
     install(root, ['codex']);
     const hooksPath = path.join(root, '.codex', 'hooks.json');
@@ -137,10 +139,18 @@ test('codex upgrade removes the legacy hooks, their records and their CafeKit en
     add('UserPromptSubmit', FOREIGN[0]);
     fs.writeFileSync(hooksPath, JSON.stringify(config, null, 2));
 
-    install(root, ['codex']);
-    for (const name of NAMES) assert.equal(fs.existsSync(path.join(root, '.codex', 'hooks', name)), false, name);
+    const upgrade = install(root, ['codex']);
+    assert.match(upgrade.stdout + upgrade.stderr, /Preserved 4 obsolete runtime/);
+    for (const name of NAMES) {
+      const file = path.join(root, '.codex', 'hooks', name);
+      if (name === 'completion-authority-state.cjs') assert.equal(fs.existsSync(file), false, name);
+      else assert.equal(fs.readFileSync(file, 'utf8'), '// user edit\n', name);
+    }
     const after = readJson(manifestPath);
-    for (const name of NAMES) assert.equal(Object.prototype.hasOwnProperty.call(after.files, `.codex/hooks/${name}`), false, `record ${name}`);
+    for (const name of NAMES) {
+      if (name === 'completion-authority-state.cjs') assert.equal(after.files[`.codex/hooks/${name}`], undefined, `record ${name}`);
+      else assert.equal(after.files[`.codex/hooks/${name}`].sha256, '0'.repeat(64), `record ${name}`);
+    }
     const afterCommands = commands(readJson(hooksPath));
     for (const name of REGISTERED) {
       assert.equal(afterCommands.some((command) => command.includes(`.codex/hooks/${name}`) || command.includes(`.codex\\hooks\\${name}`)), false, name);
@@ -156,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));
 
@@ -171,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}`);