@haposoft/cafekit 0.18.0 → 0.18.2

package/bin/__tests__/docs-sync-on-demand.test.js

@@ -47,29 +47,34 @@ function makeStale(root) {
   execSync('git -c user.email=t@t -c user.name=t add -A && git -c user.email=t@t -c user.name=t commit -qm fixture', { cwd: root });
 }
 
-test('fresh claude install runs no docs-sync at SessionStart', () => {
-  inTempProject((root) => {
-    install(root, ['claude']);
-    const settings = JSON.parse(fs.readFileSync(path.join(root, '.claude', 'settings.json'), 'utf8'));
-    assert.equal(commands(settings, 'SessionStart').some((c) => c.includes('docs-sync.cjs')), false);
-    assert.equal(fs.existsSync(path.join(root, '.claude', 'hooks', 'docs-sync.cjs')), true, 'the hook stays installed for on-demand use');
+for (const [runtime, folder, config] of [['claude', '.claude', 'settings.json'], ['codex', '.codex', 'hooks.json']]) {
+  test(`fresh ${runtime} install runs no docs-sync at SessionStart`, () => {
+    inTempProject((root) => {
+      install(root, [runtime]);
+      const settings = JSON.parse(fs.readFileSync(path.join(root, folder, config), 'utf8'));
+      assert.equal(commands(settings, 'SessionStart').some((c) => c.includes('docs-sync.cjs')), false);
+      assert.equal(fs.existsSync(path.join(root, folder, 'hooks', 'docs-sync.cjs')), true, 'the hook stays installed for on-demand use');
+    });
   });
-});
 
-test('upgrade drops the SessionStart docs-sync entry', () => {
-  inTempProject((root) => {
-    install(root, ['claude']);
-    const settingsPath = path.join(root, '.claude', 'settings.json');
-    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-    const kept = commands(settings, 'SessionStart');
-    settings.hooks.SessionStart[0].hooks.push({ type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/docs-sync.cjs"' });
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-    install(root, ['claude']);
-    const after = commands(JSON.parse(fs.readFileSync(settingsPath, 'utf8')), 'SessionStart');
-    assert.equal(after.some((c) => c.includes('docs-sync.cjs')), false);
-    for (const command of kept) assert.ok(after.includes(command), `kept: ${command}`);
+  test(`${runtime} upgrade drops the managed SessionStart docs-sync entry`, () => {
+    inTempProject((root) => {
+      install(root, [runtime]);
+      const settingsPath = path.join(root, folder, config);
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      const kept = commands(settings, 'SessionStart');
+      const command = runtime === 'claude'
+        ? 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/docs-sync.cjs"'
+        : 'node ".codex/hooks/docs-sync.cjs"';
+      settings.hooks.SessionStart[0].hooks.push({ type: 'command', command });
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+      install(root, [runtime]);
+      const after = commands(JSON.parse(fs.readFileSync(settingsPath, 'utf8')), 'SessionStart');
+      assert.equal(after.some((c) => c.includes('docs-sync.cjs')), false);
+      for (const command of kept) assert.ok(after.includes(command), `kept: ${command}`);
+    });
   });
-});
+}
 
 test('the docs skill runs docs-sync on demand', () => {
   for (const rel of ['SKILL.md', 'references/update-workflow.md']) {

package/bin/__tests__/inspect-paths.test.js

@@ -0,0 +1,183 @@
+'use strict';
+
+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 { test } = require('node:test');
+const SOURCE = path.resolve(__dirname, '../../src');
+
+// Invoke installed-layout hooks with stdin JSON: denial must be real, not a crash.
+function fixture(host, run, variant = '') {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-inspect-'));
+  const root = path.join(temp, 'build/app');
+  const link = path.join(temp, 'project-link');
+  const hooks = path.join(root, `.${host}/hooks`);
+  try {
+    fs.mkdirSync(root, { recursive: true });
+    fs.symlinkSync(root, link, 'dir');
+    fs.cpSync(path.join(SOURCE, `${host}/hooks`), hooks, { recursive: true });
+    if (host === 'codex') {
+      for (const name of ['runtime-path-safety', 'privacy-command-analysis', 'privacy-paths', 'secret-keywords', 'inspect-paths']) {
+        const source = path.join(SOURCE, `claude/hooks/lib/${name}.cjs`);
+        // Before the shared lib exists, exercise the original native implementation.
+        if (fs.existsSync(source)) fs.copyFileSync(source, path.join(hooks, `lib/${name}.cjs`));
+      }
+    }
+    const cwd = variant === 'nested' ? path.join(root, 'packages/x') : root;
+    fs.mkdirSync(cwd, { recursive: true });
+    const projectRoot = variant === 'symlink' ? link : root;
+    run({ root, temp, cwd, hook(tool_name, tool_input, payload = {}) {
+      const log = path.join(hooks, '.logs/hook-log.jsonl');
+      const before = fs.existsSync(log) ? fs.readFileSync(log, 'utf8') : '';
+      const result = spawnSync(process.execPath, [path.join(hooks, 'inspect-block.cjs')], {
+        cwd, encoding: 'utf8', input: JSON.stringify({ cwd, tool_name, tool_input, ...payload }),
+        env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+      });
+      const after = fs.existsSync(log) ? fs.readFileSync(log, 'utf8') : '';
+      assert.doesNotMatch(after.slice(before.length), /"status":"crash"/, result.stderr);
+      return result;
+    } });
+  } finally { fs.rmSync(temp, { recursive: true, force: true }); }
+}
+
+const cases = [];
+function add(name, tool, input, deny = false, variant = '', payload = {}) {
+  cases.push({ name, tool, input, deny, variant, payload });
+}
+function shell(command, deny = false) { add(command, 'Bash', { command }, deny); }
+add('Read node_modules', 'Read', { file_path: 'node_modules/x/index.js' }, true);
+add('Read absolute dist', 'Read', ({ root }) => ({ file_path: `${root}/dist/a.js` }), true);
+add('Glob broad', 'Glob', { pattern: '**/*' }, true);
+add('Glob dist', 'Glob', { pattern: '*.js', path: 'dist' }, true);
+add('Grep path', 'Grep', { pattern: 'foo', path: 'node_modules' }, true);
+add('Grep glob', 'Grep', { pattern: 'foo', glob: 'dist/**' }, true);
+for (const command of [
+  'cat dist/index.js', 'nl -ba dist/a.js', 'sed -n 1,5p build/x',
+  'grep -rn foo node_modules', 'rg foo dist', 'find ./dist', 'ls node_modules',
+  'npm exec cat ./dist/index.js', 'npx cat dist/a.js', 'npm exec -- cat dist/a',
+  'FOO=1 cat dist/a', 'env FOO=1 cat dist/a', 'sudo -u root cat dist/a',
+  'vite build --outDir ./dist $(cat dist/index.js)', 'echo `cat dist/a`', 'echo "$(cat dist/a)"',
+]) shell(command, true);
+add('Bash tilde path', 'Bash', ({ root }) => ({ command: `cat ~/${path.relative(os.homedir(), root)}/dist/a` }), true);
+add('missing tool name', undefined, { path: './dist/index.js' }, true);
+add('exec_command reader', 'exec_command', { cmd: 'cat dist/index.js' }, true);
+for (const tool of ['Edit', 'Write', 'MultiEdit']) {
+  add(`${tool} write`, tool, ({ root }) => ({ file_path: `${root}/scripts/build/release.js` }));
+}
+add('NotebookEdit write', 'NotebookEdit', { notebook_path: 'dist/a.ipynb' });
+add('patch package main', 'apply_patch', { command: '*** Begin Patch\n*** Update File: package.json\n+"main": "./dist/index.js"\n*** End Patch' });
+add('patch Add File', 'apply_patch', { command: '*** Begin Patch\n*** Add File: src/build/config.ts\n+x\n*** End Patch' });
+for (const pattern of ['target', 'node_modules']) add(`Grep regex ${pattern}`, 'Grep', { pattern });
+for (const command of [
+  '.agents/skills/.venv/bin/python3 scripts/search.py q', '.claude/skills/.venv/bin/python3 scripts/x.py',
+  'python3 -m venv .venv', 'source .venv/bin/activate && pytest',
+  'node_modules/.bin/eslint src', 'npx eslint dist/', 'python3 scripts/x.py build/out',
+  'tsc --outDir ./build', 'vite build --outDir ./dist', 'npm run build -- --outDir ./dist',
+  'cargo build --target-dir ./target', 'cd build && cmake ..', 'tree -I node_modules',
+  'grep -rn foo . --exclude-dir node_modules', "rg --glob '!**/node_modules/**' foo",
+  'find . -path ./node_modules -prune -o -print', 'echo concat vendor', "echo '$(cat dist/a)'",
+  "git commit -F - <<'EOF'\nls node_modules cleanup\nEOF",
+]) shell(command);
+add('Grep excluded glob', 'Grep', { pattern: 'foo', glob: '!dist/**' });
+for (const variant of ['', 'nested', 'symlink']) {
+  add(`project above blocked segment ${variant || 'root'}`, 'Read', ({ root }) => ({ file_path: `${fs.realpathSync(root)}/src/a.js` }), false, variant);
+}
+add('Read ordinary', 'Read', { file_path: 'src/a.js' });
+shell('cat src/a.js');
+
+// Wrapper options, nested substitutions, and structured paths.
+for (const command of [
+  'time -p env -u FOO BAR=1 command -- cat dist/a', 'nice -n 5 nohup cat dist/a',
+  'xargs -I {} cat dist/a', 'pnpm exec -- cat dist/a', 'pnpx --yes cat dist/a',
+  'yarn exec -- cat dist/a', 'bunx --bun cat dist/a', 'npx -p cat -- cat dist/a',
+  'echo "$(echo $(cat dist/a))"', 'echo ok; cat dist/a', 'echo ok\ncat dist/a',
+  'echo ok | cat dist/a', 'rg -e foo dist/a', 'awk \'{print $1}\' dist/a',
+  'less dist/a', 'more dist/a', 'bat dist/a', 'wc dist/a', 'du dist', 'file dist/a', 'stat dist/a',
+  'cat -n dist/a', 'wc -c dist/a', 'du -s dist', 'ls -L dist',
+  'echo $( (cat dist/a) )', 'env -S "cat dist/a"', 'env --split-string="cat" dist/a',
+  'npm exec -c "cat dist/a"', 'npx --call="cat dist/a"',
+  'cat src/a <<\\EOF\nprose\nEOF\ncat dist/a', "cat src/a <<E'OF'\nprose\nEOF\ncat dist/a",
+]) shell(command, true);
+for (const command of [
+  'grep --include node_modules foo src', 'rg -e node_modules src',
+  'rg --exclude-dir=node_modules foo src', 'tree -P dist',
+  'echo "cat dist/a"', "echo '`cat dist/a`'", 'cat src/a.js <<EOF\ncat dist/a\nEOF',
+]) shell(command);
+add('nested paths', 'mcp__files__read', { operations: [{ paths: ['dist/a'] }] }, true);
+add('notebook path reader', 'Read', { notebook_path: 'dist/a.ipynb' }, true);
+add('unknown command reader', 'mcp__shell', { command: 'cat dist/a' }, true);
+add('missing name command reader', undefined, { command: 'cat dist/a' }, true);
+add('write skips command too', 'Write', { file_path: 'dist/a', command: 'cat dist/a' });
+
+// Output redirections are writes; search option values are not patterns.
+for (const command of [
+  "cat > dist/index.html <<'EOF'\n<html></html>\nEOF",
+  'ls src > build/files.txt', 'wc -l src/a.ts > coverage/summary.txt',
+  'grep x src 2> build/err', 'ls src >> build/x', 'ls src 2>&1', 'ls src>build/x',
+  'rg --max-depth 2 target src', 'rg -j 4 build src', 'rg -M 200 dist src',
+  'rg --sort path target src', 'grep -rn -d skip build src',
+]) shell(command);
+for (const command of ['cat < dist/a', 'cat <dist/a']) shell(command, true);
+
+add('Grep glob:"**/*.ts", path:"src"', 'Grep', { pattern: 'x', glob: '**/*.ts', path: 'src' });
+add('Glob pattern:"**/*.ts", path:"src"', 'Glob', { pattern: '**/*.ts', path: 'src' });
+shell("rg -g '**/*.ts' x src");
+add('Glob broad without path', 'Glob', { pattern: '**/*' }, true);
+add('Grep glob:"**/*.ts", path:"."', 'Grep', { pattern: 'x', glob: '**/*.ts', path: '.' }, true);
+add('Glob broad absolute project root', 'Glob', ({ root }) => ({ pattern: '**/*.ts', path: root }), true);
+add('Glob broad path:".."', 'Glob', { pattern: '**/*', path: '..' }, true);
+add('Glob broad filesystem root', 'Glob', { pattern: '**/*', path: '/' }, true);
+add('Glob broad home', 'Glob', { pattern: '**/*', path: '~' }, true);
+add('Glob broad normalized project root', 'Glob', { pattern: '**/*', path: 'src/..' }, true);
+add('Glob broad blocked directory', 'Glob', { pattern: '**/*.ts', path: 'node_modules' }, true);
+shell("rg --glob '**/*' symbol .", true);
+shell("rg --glob '**/*' symbol; cat src/file.ts", true);
+shell("cd ..; rg --glob '**/*' symbol src", true);
+shell("env -C .. rg --glob '**/*' symbol src", true);
+for (const command of [
+  "rg -E utf8 -g '**/*' x", "rg --ignore-file .gitignore -g '**/*' x",
+  "rg --engine pcre2 -g '**/*' x", "rg --type-add 'web:*.html' -g '**/*' x",
+  "echo . | xargs rg -g '**/*' x src", "env -C.. rg -g '**/*' x src",
+  "builtin cd .. && rg -g '**/*' x src",
+]) shell(command, true);
+add('Bash broad glob with non-string session cwd', 'Bash', { command: "rg -g '**/*' x src" }, true, '', { cwd: 1 });
+add('Bash broad glob with non-string input cwd', 'Bash', { command: "rg -g '**/*' x src", cwd: 1 }, true);
+for (const key of ['cwd', 'workdir']) {
+  add(`Bash broad glob with ${key}:".."`, 'Bash', { command: "rg -g '**/*' x src", [key]: '..' }, true);
+}
+for (const flag of [
+  '--json', '-S', '--smart-case', '-N', '--no-heading', '--heading', '--column', '--vimgrep',
+  '--follow', '--no-ignore', '--no-ignore-dot', '--no-ignore-exclude', '--no-ignore-files',
+  '--no-ignore-global', '--no-ignore-parent', '--no-ignore-vcs', '--no-ignore-messages',
+  '--no-ignore-file-case-insensitive', '--count-matches', '-b', '--trim',
+  '-C3', '-A2', '-m5', '-tts',
+]) shell(`rg -g '**/*.ts' ${flag} x src`);
+for (const command of [
+  "eval 'cd ..'; rg -g '**/*' x src", "source setup.sh; rg -g '**/*' x src",
+  ". setup.sh; rg -g '**/*' x src", "env -iC.. rg -g '**/*' x src",
+]) shell(command, true);
+
+for (const host of ['claude', 'codex']) {
+  for (const entry of cases) {
+    if (host === 'codex' && entry.payload.cwd === 1) continue;
+    test(`inspect-paths ${host}: ${entry.name}`, () => fixture(host, (context) => {
+      const input = typeof entry.input === 'function' ? entry.input(context) : entry.input;
+      const result = context.hook(entry.tool, input, entry.payload);
+      assert.equal(result.status, entry.deny ? 2 : 0, result.stderr || result.stdout);
+      if (entry.deny) {
+        if (host === 'claude') assert.equal(JSON.parse(result.stdout).hookSpecificOutput.permissionDecision, 'deny');
+        assert.match(result.stderr, /SCOPE LIMIT EXCEEDED/);
+      } else assert.equal(result.stdout, '');
+    }, entry.variant));
+  }
+}
+
+test('inspect-paths lib blocks broad glob with non-string context.cwd', () => {
+  const { inspectInput } = require('../../src/claude/hooks/lib/inspect-paths.cjs');
+  const result = inspectInput('Bash', { command: "rg -g '**/*' x src" }, {
+    cwd: 1, projectRoot: process.cwd(),
+  });
+  assert.equal(result.broadGlob, '**/*');
+});

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-authority-decoupled.test.js

@@ -19,7 +19,6 @@ const LEGACY_FILES = [
   'semantic-review-authority.cjs',
   'task-scaffold-guard.cjs',
 ];
-const MIGRATION = /Legacy spec\.json closeout is no longer supported/;
 
 function inTempProject(run) {
   const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-decoupled-')));
@@ -122,26 +121,24 @@ function checkProcessFirst(kind) {
   });
 }
 
-function checkLegacyCloseout(kind) {
-  for (const status of ['done', 'completed']) {
+// CafeKit no longer reads spec.json packets: a leftover one, closed or mid-execution, never
+// blocks Stop on its own, and beside a process-first packet the decision is that packet's alone.
+function checkLegacyIgnored(kind) {
+  for (const legacy of [{ status: 'done' }, { status: 'completed' }, { status: 'in_progress', doneTask: true }]) {
     inTempProject((root) => {
-      writeLegacy(root, { status });
+      writeLegacy(root, legacy);
       removeLegacyFiles(root);
-      assert.match(blockReason(stopGate(root, kind)), MIGRATION, `${kind} ${status}`);
+      assert.equal(stopGate(root, kind), '', `${kind} ${legacy.status} legacy packet alone`);
+      writeProcessFirst(root, { receipt: false });
+      const reason = blockReason(stopGate(root, kind));
+      assert.match(reason, /missing_receipt/);
+      assert.doesNotMatch(reason, /task-R1-01-legacy\.md/);
+      writeProcessFirst(root, { receipt: true });
+      assert.equal(stopGate(root, kind), '', `${kind} ${legacy.status} legacy packet beside a proven process-first packet`);
     });
   }
 }
 
-function checkLegacyMidExecution(kind) {
-  inTempProject((root) => {
-    writeLegacy(root, { status: 'in_progress', doneTask: true });
-    removeLegacyFiles(root);
-    const reason = blockReason(stopGate(root, kind));
-    assert.doesNotMatch(reason, MIGRATION);
-    assert.match(reason, /task-R1-01-legacy\.md/);
-  });
-}
-
 function checkSession(kind) {
   inTempProject((root) => {
     removeLegacyFiles(root);
@@ -151,9 +148,7 @@ function checkSession(kind) {
 
 test('claude gate passes and blocks process-first with and without the legacy files', () => checkProcessFirst('claude'));
 test('codex gate passes and blocks process-first with and without the legacy files', () => checkProcessFirst('codex'));
-test('claude gate blocks legacy 2.1 closeout with the migration message', () => checkLegacyCloseout('claude'));
-test('codex gate blocks legacy 2.1 closeout with the migration message', () => checkLegacyCloseout('codex'));
-test('claude gate still receipt-checks a legacy 2.1 packet mid-execution', () => checkLegacyMidExecution('claude'));
-test('codex gate still receipt-checks a legacy 2.1 packet mid-execution', () => checkLegacyMidExecution('codex'));
+test('claude gate ignores a leftover legacy packet', () => checkLegacyIgnored('claude'));
+test('codex gate ignores a leftover legacy packet', () => checkLegacyIgnored('codex'));
 test('claude session starts without the legacy files', () => checkSession('claude'));
 test('codex session starts without the legacy files', () => checkSession('codex'));