@productbrain/cli 0.1.0-beta.6 → 0.1.0-beta.6046

package/dist/__tests__/handshake.test.js

@@ -0,0 +1,1102 @@
+/**
+ * pb handshake --init — unit tests.
+ * DEC-271: two-file split (team vs personal). DEC-272: permission whitelist.
+ * TEN-712: hooks must fail silently (|| true suffix).
+ *
+ * WP-379 S3b: probeStarterSetupSeeded + pollUntilSeedsReady tests.
+ */
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { join } from 'path';
+// Import the mocked fs functions so we can use vi.mocked() to change their implementations per-test.
+// vi.mock('fs', ...) below hoists this mock, so these imports resolve to the mocked versions.
+import { readdirSync as readdirSyncMock } from 'fs';
+// vi.mock calls are hoisted — use vi.hoisted() for constants referenced inside factories.
+const { vfs, vfsMtimes, vfsDirs, vfsSymlinks, vfsRealpaths, vfsInodes, MOCK_CWD, MOCK_HOME } = vi.hoisted(() => ({
+    vfs: {},
+    // WP-379 S5b: mtime map used by statSync mock for case-collision ordering tests.
+    vfsMtimes: {},
+    // PR #912 follow-up: lstatSync needs dir-vs-file-vs-symlink distinction, which the flat
+    // `vfs` content map doesn't carry (a directory marker is stored as `vfs[dir] = ''`, same
+    // shape as an empty file) — these two sets disambiguate for the Cursor nested-skills tests.
+    vfsDirs: new Set(),
+    vfsSymlinks: new Set(),
+    // PR #912 follow-up (Cursor security review): explicit path→realpath overrides so a test can
+    // simulate an INTERMEDIATE symlinked component (e.g. .cursor/skills itself) resolving outside
+    // the repo, distinct from vfsSymlinks which only marks the final path component as a link.
+    vfsRealpaths: new Map(),
+    // Round 13: explicit path→ino override so a test can make two case-variant paths resolve to
+    // the SAME filesystem entry (case-insensitive FS simulation). Unset paths fall back to a
+    // deterministic per-path hash in the statSync mock below.
+    vfsInodes: new Map(),
+    MOCK_CWD: '/tmp/pb-test-cwd',
+    MOCK_HOME: '/tmp/pb-test-home',
+}));
+vi.mock('fs', () => ({
+    mkdirSync: vi.fn(),
+    writeFileSync: vi.fn((path, content) => {
+        vfs[path] = content;
+    }),
+    appendFileSync: vi.fn((path, content) => {
+        vfs[path] = (vfs[path] ?? '') + content;
+    }),
+    existsSync: vi.fn((path) => path in vfs),
+    readFileSync: vi.fn((path, _enc) => {
+        if (path in vfs)
+            return vfs[path];
+        throw Object.assign(new Error(`ENOENT: no such file '${path}'`), { code: 'ENOENT' });
+    }),
+    readdirSync: vi.fn((_dir) => []),
+    copyFileSync: vi.fn(),
+    // WP-379 S5b: unlinkSync + statSync for orphan unlink + case-collision resolution.
+    unlinkSync: vi.fn((path) => {
+        delete vfs[path];
+    }),
+    statSync: vi.fn((path) => {
+        if (path in vfs) {
+            // Return a fake stat with an incrementing mtime based on path hash (deterministic).
+            // Tests that need specific mtime ordering should set vfs[path] before calling.
+            const mtimeMs = vfsMtimes[path] ?? 1000;
+            // Round 13: dev/ino for case-insensitive-alias detection. dev is constant (single fake
+            // filesystem); ino defaults to a deterministic per-path hash unless a test overrides it
+            // via vfsInodes to make two case-variant paths resolve to the same entry.
+            let ino = vfsInodes.get(path);
+            if (ino === undefined) {
+                let h = 0;
+                for (let i = 0; i < path.length; i++)
+                    h = (h * 31 + path.charCodeAt(i)) | 0;
+                ino = h;
+            }
+            return { mtimeMs, dev: 1, ino };
+        }
+        throw Object.assign(new Error(`ENOENT: stat '${path}'`), { code: 'ENOENT' });
+    }),
+    // PR #912 follow-up: lstatSync backs the Cursor nested-skills symlink refusal — never
+    // follows a link, so a path marked in vfsSymlinks reports neither isDirectory() nor isFile().
+    lstatSync: vi.fn((path) => {
+        const isSymlink = vfsSymlinks.has(path);
+        const isDir = vfsDirs.has(path);
+        const isFile = !isSymlink && !isDir && path in vfs;
+        if (!isSymlink && !isDir && !isFile) {
+            throw Object.assign(new Error(`ENOENT: lstat '${path}'`), { code: 'ENOENT' });
+        }
+        return {
+            isDirectory: () => isDir,
+            isFile: () => isFile,
+            isSymbolicLink: () => isSymlink,
+        };
+    }),
+    // PR #912 follow-up: realpathSync backs the Cursor-skills-root containment check — an explicit
+    // vfsRealpaths override simulates an intermediate symlinked component; otherwise identity.
+    // Identity by default (a real fs resolves an ordinary path, including MOCK_CWD itself, to
+    // itself) — vfsRealpaths overrides model a specific symlinked path resolving elsewhere.
+    realpathSync: vi.fn((path) => vfsRealpaths.get(path) ?? path),
+}));
+vi.mock('os', () => ({
+    homedir: vi.fn(() => MOCK_HOME),
+}));
+// prompts mock: select returns 'work' (second option)
+vi.mock('../lib/prompts.js', () => ({
+    select: () => Promise.resolve('work'),
+    confirm: () => Promise.resolve(false),
+    ask: () => Promise.resolve(''),
+    password: () => Promise.resolve(''),
+    isInteractive: () => true,
+}));
+import { runHandshakeInit, normalizeHandshakeContentForComparison, findLeftoverProjections, classifyDriftBucket, deriveHandshakeStartupSignals, dereferencePrRefToPaths } from '../commands/handshake.js';
+import { findLeftoverCursorSkills, LEFTOVER_FILES_MAX } from '../commands/handshakeCursorSkillCleanup.js';
+import { MARKER } from '../generators/adapters.js';
+/** PR #911 review (Codex P2): findLeftoverProjections scopes reporting to allowedTargets — tests that want every surface scanned pass this. */
+const ALL_SURFACES = new Set(['cursor', 'claude', 'codex', 'copilot']);
+import { createHash } from 'crypto';
+const TEAM_PATH = join(MOCK_CWD, '.claude', 'settings.json');
+const PERSONAL_PATH = join(MOCK_HOME, '.claude', 'settings.json');
+describe('runHandshakeInit', () => {
+    let cwdSpy;
+    beforeEach(() => {
+        Object.keys(vfs).forEach((k) => delete vfs[k]);
+        vi.clearAllMocks();
+        cwdSpy = vi.spyOn(process, 'cwd').mockReturnValue(MOCK_CWD);
+        vi.spyOn(console, 'log').mockImplementation(() => { });
+        vi.spyOn(console, 'error').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        cwdSpy.mockRestore();
+    });
+    describe('basic writes (DEC-271)', () => {
+        it('writes hooks to team config (.claude/settings.json relative to cwd)', async () => {
+            await runHandshakeInit({ level: 'work', dryRun: false });
+            expect(vfs[TEAM_PATH]).toBeDefined();
+            const team = JSON.parse(vfs[TEAM_PATH]);
+            expect(team.hooks.SessionStart).toHaveLength(1);
+            expect(team.hooks.Stop).toHaveLength(1);
+            expect(team.hooks.PreCompact).toHaveLength(1);
+            expect(team.permissions.allow).toContain('Bash(pb:*)');
+        });
+        it('writes trust level to personal config (~/.claude/settings.json)', async () => {
+            await runHandshakeInit({ level: 'work', dryRun: false });
+            expect(vfs[PERSONAL_PATH]).toBeDefined();
+            const personal = JSON.parse(vfs[PERSONAL_PATH]);
+            expect(personal.permissions.defaultMode).toBe('auto');
+            expect(personal.permissions.allow).toContain('Bash(pb:*)');
+            expect(personal.permissions.allow).toContain('Bash(git:*)');
+            expect(personal.permissions.allow).toContain('Bash(npm run:*)');
+        });
+        it('guide level sets auto mode with minimal permissions', async () => {
+            await runHandshakeInit({ level: 'guide', dryRun: false });
+            const personal = JSON.parse(vfs[PERSONAL_PATH]);
+            expect(personal.permissions.defaultMode).toBe('auto');
+            expect(personal.permissions.allow).toContain('Bash(pb:*)');
+            expect(personal.permissions.allow).toContain('Bash(git:*)');
+        });
+        it('full-trust level sets bypassPermissions mode', async () => {
+            await runHandshakeInit({ level: 'full-trust', dryRun: false });
+            const personal = JSON.parse(vfs[PERSONAL_PATH]);
+            expect(personal.permissions.defaultMode).toBe('bypassPermissions');
+        });
+    });
+    describe('idempotency', () => {
+        it('running twice produces no duplicate hooks in team config', async () => {
+            await runHandshakeInit({ level: 'work', dryRun: false });
+            await runHandshakeInit({ level: 'work', dryRun: false });
+            const team = JSON.parse(vfs[TEAM_PATH]);
+            expect(team.hooks.SessionStart).toHaveLength(1);
+            expect(team.hooks.Stop).toHaveLength(1);
+            expect(team.hooks.PreCompact).toHaveLength(1);
+            expect(team.permissions.allow.filter((p) => p === 'Bash(pb:*)')).toHaveLength(1);
+        });
+        it('running twice produces no duplicate permissions in personal config', async () => {
+            await runHandshakeInit({ level: 'work', dryRun: false });
+            await runHandshakeInit({ level: 'work', dryRun: false });
+            const personal = JSON.parse(vfs[PERSONAL_PATH]);
+            expect(personal.permissions.allow.filter((p) => p === 'Bash(pb:*)')).toHaveLength(1);
+            expect(personal.permissions.allow.filter((p) => p === 'Bash(git:*)')).toHaveLength(1);
+        });
+    });
+    describe('security constraints (DEC-272)', () => {
+        it('never puts defaultMode in team config', async () => {
+            await runHandshakeInit({ level: 'full-trust', dryRun: false });
+            const team = JSON.parse(vfs[TEAM_PATH]);
+            expect(team.permissions?.defaultMode).toBeUndefined();
+        });
+        it('never puts bypassPermissions in team config even for full-trust level', async () => {
+            await runHandshakeInit({ level: 'full-trust', dryRun: false });
+            const team = JSON.parse(vfs[TEAM_PATH]);
+            expect(JSON.stringify(team)).not.toContain('bypassPermissions');
+        });
+        it('Bash(npx:*) appears in silent level personal config', async () => {
+            await runHandshakeInit({ level: 'silent', dryRun: false });
+            const personal = JSON.parse(vfs[PERSONAL_PATH]);
+            expect(personal.permissions.allow).toContain('Bash(npx:*)');
+        });
+        it('Bash(npx:*) does NOT appear in work level personal config', async () => {
+            await runHandshakeInit({ level: 'work', dryRun: false });
+            const personal = JSON.parse(vfs[PERSONAL_PATH]);
+            expect(personal.permissions.allow).not.toContain('Bash(npx:*)');
+        });
+        it('Bash(npx:*) does NOT appear in guide level personal config', async () => {
+            await runHandshakeInit({ level: 'guide', dryRun: false });
+            const personal = JSON.parse(vfs[PERSONAL_PATH]);
+            expect(personal.permissions.allow).not.toContain('Bash(npx:*)');
+        });
+        it('Bash(npx:*) does NOT appear in team config for any level', async () => {
+            for (const level of ['guide', 'work', 'silent', 'full-trust']) {
+                Object.keys(vfs).forEach((k) => delete vfs[k]);
+                await runHandshakeInit({ level, dryRun: false });
+                const team = JSON.parse(vfs[TEAM_PATH]);
+                expect(JSON.stringify(team)).not.toContain('npx:*');
+            }
+        });
+    });
+    describe('hook failure contract (TEN-712)', () => {
+        it('all hook commands include fail-silent suffix (|| true)', async () => {
+            await runHandshakeInit({ level: 'work', dryRun: false });
+            const team = JSON.parse(vfs[TEAM_PATH]);
+            const sessionStartCmd = team.hooks.SessionStart[0].hooks[0].command;
+            const stopCmd = team.hooks.Stop[0].hooks[0].command;
+            const precompactCmd = team.hooks.PreCompact[0].hooks[0].command;
+            expect(sessionStartCmd).toContain('|| true');
+            expect(stopCmd).toContain('|| true');
+            expect(precompactCmd).toContain('|| true');
+        });
+        it('pb session start hook command is exact', async () => {
+            await runHandshakeInit({ level: 'work', dryRun: false });
+            const team = JSON.parse(vfs[TEAM_PATH]);
+            const cmd = team.hooks.SessionStart[0].hooks[0].command;
+            expect(cmd).toBe('pb session start 2>/dev/null || true');
+        });
+        it('pb session close hook command is exact', async () => {
+            await runHandshakeInit({ level: 'work', dryRun: false });
+            const team = JSON.parse(vfs[TEAM_PATH]);
+            const cmd = team.hooks.Stop[0].hooks[0].command;
+            expect(cmd).toBe('pb session close 2>/dev/null || true');
+        });
+    });
+    describe('--dry-run flag', () => {
+        it('does not write any files when dryRun is true', async () => {
+            await runHandshakeInit({ level: 'work', dryRun: true });
+            expect(vfs[TEAM_PATH]).toBeUndefined();
+            expect(vfs[PERSONAL_PATH]).toBeUndefined();
+        });
+    });
+    describe('--level flag validation', () => {
+        it('throws CLIError for unknown level', async () => {
+            await expect(runHandshakeInit({ level: 'invalid-level', dryRun: false })).rejects.toThrow('Unknown level');
+        });
+        it('does not write files when level is invalid', async () => {
+            await expect(runHandshakeInit({ level: 'GUIDE', dryRun: false })).rejects.toThrow();
+            expect(vfs[TEAM_PATH]).toBeUndefined();
+            expect(vfs[PERSONAL_PATH]).toBeUndefined();
+        });
+    });
+});
+describe('normalizeHandshakeContentForComparison', () => {
+    it('treats handshake timestamp comment as non-semantic', () => {
+        const a = '<!-- auto-generated by pb handshake — 2026-04-02T10:00:00.000Z -->\nbody\n';
+        const b = '<!-- auto-generated by pb handshake — 2026-04-02T11:00:00.000Z -->\nbody\n';
+        expect(normalizeHandshakeContentForComparison(a)).toBe(normalizeHandshakeContentForComparison(b));
+    });
+    it('treats generated metadata line as non-semantic', () => {
+        const a = '_Generated: 2026-04-02T10:00:00.000Z_\ncontent\n';
+        const b = '_Generated: 2026-04-02T11:00:00.000Z_\ncontent\n';
+        expect(normalizeHandshakeContentForComparison(a)).toBe(normalizeHandshakeContentForComparison(b));
+    });
+    it('preserves meaningful content differences', () => {
+        const a = '<!-- auto-generated by pb handshake — 2026-04-02T10:00:00.000Z -->\nalpha\n';
+        const b = '<!-- auto-generated by pb handshake — 2026-04-02T11:00:00.000Z -->\nbeta\n';
+        expect(normalizeHandshakeContentForComparison(a)).not.toBe(normalizeHandshakeContentForComparison(b));
+    });
+});
+// ── WP-379 S3b: probeStarterSetupSeeded + pollUntilSeedsReady ─────────────────
+//
+// These tests use vi.doMock (not vi.mock) so they can inject different
+// kernelCall implementations per test without affecting the --init tests above.
+// Each test creates its own isolated module scope via vi.resetModules().
+describe('probeStarterSetupSeeded (WP-379 S3b)', () => {
+    beforeEach(() => {
+        vi.resetModules();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns seeds-ready when health.starterSetupSeeded is true', async () => {
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: vi.fn().mockResolvedValue({
+                starterSetupSeeded: true,
+                gaps: [],
+                status: 'healthy',
+            }),
+        }));
+        const { probeStarterSetupSeeded } = await import('../commands/handshake.js');
+        const result = await probeStarterSetupSeeded();
+        expect(result.status).toBe('seeds-ready');
+    });
+    it('returns seeds-pending with starter-setup-missing gap when starterSetupSeeded is false', async () => {
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: vi.fn().mockResolvedValue({
+                starterSetupSeeded: false,
+                gaps: [
+                    {
+                        kind: 'starter-setup-missing',
+                        severity: 'error',
+                        message: 'Starter setup seeds are still running.',
+                    },
+                ],
+                status: 'incomplete',
+            }),
+        }));
+        const { probeStarterSetupSeeded } = await import('../commands/handshake.js');
+        const result = await probeStarterSetupSeeded();
+        expect(result.status).toBe('seeds-pending');
+        if (result.status === 'seeds-pending') {
+            expect(result.gaps.length).toBeGreaterThan(0);
+            expect(result.gaps[0]?.kind).toBe('starter-setup-missing');
+        }
+    });
+    it('returns probe-failed when kernelCall throws', async () => {
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: vi.fn().mockRejectedValue(new Error('Network unreachable')),
+        }));
+        const { probeStarterSetupSeeded } = await import('../commands/handshake.js');
+        const result = await probeStarterSetupSeeded();
+        expect(result.status).toBe('probe-failed');
+        if (result.status === 'probe-failed') {
+            expect(result.error).toContain('Network unreachable');
+        }
+    });
+    it('synthesizes a default starter-setup-missing gap when health.gaps is empty but starterSetupSeeded is false', async () => {
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: vi.fn().mockResolvedValue({
+                starterSetupSeeded: false,
+                gaps: [], // no gap details from server
+                status: 'incomplete',
+            }),
+        }));
+        const { probeStarterSetupSeeded } = await import('../commands/handshake.js');
+        const result = await probeStarterSetupSeeded();
+        expect(result.status).toBe('seeds-pending');
+        if (result.status === 'seeds-pending') {
+            expect(result.gaps.length).toBe(1);
+            expect(result.gaps[0]?.kind).toBe('starter-setup-missing');
+        }
+    });
+});
+describe('pollUntilSeedsReady (WP-379 S3b)', () => {
+    beforeEach(() => {
+        vi.resetModules();
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+    it('returns seeds-ready immediately when first probe succeeds', async () => {
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: vi.fn().mockResolvedValue({
+                starterSetupSeeded: true,
+                gaps: [],
+                status: 'healthy',
+            }),
+        }));
+        const { pollUntilSeedsReady } = await import('../commands/handshake.js');
+        const resultPromise = pollUntilSeedsReady();
+        // Advance timers past any initial delays
+        await vi.runAllTimersAsync();
+        const result = await resultPromise;
+        expect(result.status).toBe('seeds-ready');
+    });
+    it('returns seeds-pending after MAX_POLLS when seeds never become ready', async () => {
+        // kernelCall always returns starterSetupSeeded: false
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: vi.fn().mockResolvedValue({
+                starterSetupSeeded: false,
+                gaps: [
+                    {
+                        kind: 'starter-setup-missing',
+                        severity: 'error',
+                        message: 'Starter setup seeds are still running.',
+                    },
+                ],
+                status: 'incomplete',
+            }),
+        }));
+        const { pollUntilSeedsReady } = await import('../commands/handshake.js');
+        const resultPromise = pollUntilSeedsReady();
+        await vi.runAllTimersAsync();
+        const result = await resultPromise;
+        expect(result.status).toBe('seeds-pending');
+        if (result.status === 'seeds-pending') {
+            expect(result.gaps[0]?.kind).toBe('starter-setup-missing');
+        }
+    });
+    it('stops polling immediately on probe-failed (no retry on network error)', async () => {
+        const kernelCallMock = vi.fn().mockRejectedValue(new Error('auth failed'));
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: kernelCallMock,
+        }));
+        const { pollUntilSeedsReady } = await import('../commands/handshake.js');
+        const resultPromise = pollUntilSeedsReady();
+        await vi.runAllTimersAsync();
+        const result = await resultPromise;
+        expect(result.status).toBe('probe-failed');
+        // Should have called exactly once — no retry on failure
+        expect(kernelCallMock).toHaveBeenCalledTimes(1);
+    });
+});
+// ── WP-379 S5b: findLeftoverProjections + findLeftoverCursorSkills — REPORT-ONLY ────────────
+//
+// Coordinator ruling (PR #912 round 10): nine review rounds on the same unlink mechanism —
+// symlinks, case collisions, empty-DB states, tamper preservation — is the signal that a
+// deletion mechanism over a user's filesystem is defensive machinery whose edge cases never
+// end. pb handshake no longer unlinks, renames, or recreates any leftover file; these tests
+// assert survival AND report inclusion for each stale class. All file system operations go
+// through the vfs mock defined at the top of this file.
+describe('findLeftoverProjections (WP-379 S5b, report-only)', () => {
+    beforeEach(() => {
+        Object.keys(vfs).forEach((k) => delete vfs[k]);
+        Object.keys(vfsMtimes).forEach((k) => delete vfsMtimes[k]);
+        vfsDirs.clear();
+        vfsSymlinks.clear();
+        vfsRealpaths.clear();
+        vfsInodes.clear();
+        vi.clearAllMocks();
+    });
+    function writeMarkedFile(path, extra = '') {
+        const dir = path.substring(0, path.lastIndexOf('/'));
+        vfs[dir] = '';
+        vfs[path] = `${MARKER}\n# Rule\n${extra}`;
+    }
+    function writeUserFile(path) {
+        const dir = path.substring(0, path.lastIndexOf('/'));
+        vfs[dir] = '';
+        vfs[path] = '# My user rule — no marker here\n';
+    }
+    it('an exact-match file is not reported; a case-variant with the same stem is reported as leftover and survives', () => {
+        const dir = `${MOCK_CWD}/.cursor/rules`;
+        const exact = `${dir}/setup-productbrain.mdc`;
+        const variant = `${dir}/Setup-ProductBrain.mdc`;
+        writeMarkedFile(exact);
+        writeMarkedFile(variant);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === dir ? ['setup-productbrain.mdc', 'Setup-ProductBrain.mdc'] : []));
+        const { files: leftovers } = findLeftoverProjections(MOCK_CWD, ['setup-productbrain'], ALL_SURFACES);
+        expect(exact in vfs).toBe(true);
+        expect(variant in vfs).toBe(true); // survives — never unlinked
+        expect(leftovers.some((l) => l.path === exact)).toBe(false); // current — not reported
+        expect(leftovers.some((l) => l.path === variant && l.reason.includes('stale case'))).toBe(true);
+    });
+    it('a marker-bearing file with no canonical match is reported as an orphan and survives', () => {
+        const dir = `${MOCK_CWD}/.cursor/rules`;
+        const orphan = `${dir}/old-orphaned-rule.mdc`;
+        writeMarkedFile(orphan);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === dir ? ['old-orphaned-rule.mdc'] : []));
+        const { files: leftovers } = findLeftoverProjections(MOCK_CWD, ['some-other-rule'], ALL_SURFACES);
+        expect(orphan in vfs).toBe(true); // survives — never unlinked
+        expect(leftovers.some((l) => l.path === orphan && l.reason.includes('orphan'))).toBe(true);
+    });
+    it('a leftover .dormant file is reported and survives, regardless of content match with its live sibling', () => {
+        const dir = `${MOCK_CWD}/.claude/rules`;
+        const live = `${dir}/setup-productbrain.md`;
+        const dormant = `${dir}/setup-productbrain.md.dormant`;
+        writeMarkedFile(live, 'Same body');
+        writeMarkedFile(dormant, 'Same body');
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === dir ? ['setup-productbrain.md', 'setup-productbrain.md.dormant'] : []));
+        const { files: leftovers } = findLeftoverProjections(MOCK_CWD, ['setup-productbrain'], ALL_SURFACES);
+        expect(live in vfs).toBe(true);
+        expect(dormant in vfs).toBe(true); // survives, even though content matches the live file
+        expect(leftovers.some((l) => l.path === live)).toBe(false);
+        expect(leftovers.some((l) => l.path === dormant && l.reason.includes('.dormant'))).toBe(true);
+    });
+    it('a user-owned file (no marker) is never reported and never touched', () => {
+        const dir = `${MOCK_CWD}/.cursor/rules`;
+        const userFile = `${dir}/foo.mdc`;
+        writeUserFile(userFile);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === dir ? ['foo.mdc'] : []));
+        const { files: leftovers } = findLeftoverProjections(MOCK_CWD, [], ALL_SURFACES);
+        expect(userFile in vfs).toBe(true);
+        expect(leftovers.some((l) => l.path === userFile)).toBe(false);
+    });
+    it('an unselected surface is left unreported entirely', () => {
+        const dir = `${MOCK_CWD}/.codex/skills`;
+        const orphan = `${dir}/old-skill.md`;
+        writeMarkedFile(orphan);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === dir ? ['old-skill.md'] : []));
+        const claudeOnly = new Set(['claude']);
+        const { files: leftovers } = findLeftoverProjections(MOCK_CWD, [], claudeOnly);
+        expect(orphan in vfs).toBe(true);
+        expect(leftovers.some((l) => l.path === orphan)).toBe(false);
+    });
+    it('PR #912 round 11 (Codex P2): a generated router/index file (no matching asset name) is not reported when its exact path is in the write plan', () => {
+        const dir = `${MOCK_CWD}/.codex/skills`;
+        const indexFile = `${dir}/README.md`;
+        writeMarkedFile(indexFile);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === dir ? ['README.md'] : []));
+        // No asset name matches "readme" — the old asset-name-only comparison would call this an
+        // orphan even though the write plan legitimately (re)generates it every run.
+        const exactRelativePaths = new Set(['.codex/skills/README.md']);
+        const { files: leftovers } = findLeftoverProjections(MOCK_CWD, ['setup-productbrain'], ALL_SURFACES, undefined, exactRelativePaths);
+        expect(leftovers.some((l) => l.path === indexFile)).toBe(false);
+    });
+    it('PR #912 round 11 (Codex P2): a canonical raw name not already in normalized form is not reported as a stale variant when it is the exact write-plan path', () => {
+        const dir = `${MOCK_CWD}/.claude/rules`;
+        const rawNameFile = `${dir}/Setup Skill.md`;
+        writeMarkedFile(rawNameFile);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === dir ? ['Setup Skill.md'] : []));
+        // "Setup Skill" normalizes to "setup-skill", so the raw filename's stem !== its normalized
+        // form — without the exact-path carve-out this reads as a stale case/punctuation variant
+        // even though the writer emits this exact raw name every run.
+        const exactRelativePaths = new Set(['.claude/rules/Setup Skill.md']);
+        const { files: leftovers } = findLeftoverProjections(MOCK_CWD, ['Setup Skill'], ALL_SURFACES, undefined, exactRelativePaths);
+        expect(leftovers.some((l) => l.path === rawNameFile)).toBe(false);
+    });
+    it('PR #912 round 11 (Codex P2): without the exact-path carve-out, that same raw-name file is still (wrongly) reported as a stale variant — pins the failure mode the fix closes', () => {
+        const dir = `${MOCK_CWD}/.claude/rules`;
+        const rawNameFile = `${dir}/Setup Skill.md`;
+        writeMarkedFile(rawNameFile);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === dir ? ['Setup Skill.md'] : []));
+        const { files: leftovers } = findLeftoverProjections(MOCK_CWD, ['Setup Skill'], ALL_SURFACES);
+        expect(leftovers.some((l) => l.path === rawNameFile && l.reason.includes('stale case'))).toBe(true);
+    });
+    it('PR #912 round 13 (Codex P2): stops scanning after LEFTOVER_FILES_MAX + 1 matches, reporting truncated=true and a capped list', () => {
+        const dir = `${MOCK_CWD}/.cursor/rules`;
+        const count = LEFTOVER_FILES_MAX + 5;
+        const filenames = Array.from({ length: count }, (_, i) => `orphan-${i}.mdc`);
+        for (const f of filenames)
+            writeMarkedFile(`${dir}/${f}`);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === dir ? filenames : []));
+        const { files: leftovers, truncated } = findLeftoverProjections(MOCK_CWD, [], ALL_SURFACES);
+        expect(truncated).toBe(true);
+        expect(leftovers).toHaveLength(LEFTOVER_FILES_MAX);
+        // Every file still survives on disk — this is I/O and reporting bound, never deletion.
+        for (const f of filenames)
+            expect(`${dir}/${f}` in vfs).toBe(true);
+    });
+    it('a count at exactly the cap is NOT reported as truncated', () => {
+        const dir = `${MOCK_CWD}/.cursor/rules`;
+        const filenames = Array.from({ length: LEFTOVER_FILES_MAX }, (_, i) => `orphan-${i}.mdc`);
+        for (const f of filenames)
+            writeMarkedFile(`${dir}/${f}`);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === dir ? filenames : []));
+        const { files: leftovers, truncated } = findLeftoverProjections(MOCK_CWD, [], ALL_SURFACES);
+        expect(truncated).toBe(false);
+        expect(leftovers).toHaveLength(LEFTOVER_FILES_MAX);
+    });
+});
+describe('findLeftoverCursorSkills (WP-379 S5b nested layout, report-only)', () => {
+    beforeEach(() => {
+        Object.keys(vfs).forEach((k) => delete vfs[k]);
+        vfsDirs.clear();
+        vfsSymlinks.clear();
+        vfsRealpaths.clear();
+        vfsInodes.clear();
+        vi.clearAllMocks();
+    });
+    it('an orphan nested Cursor skill is reported as leftover and survives', () => {
+        const skillsDir = `${MOCK_CWD}/.cursor/skills`;
+        const orphanDir = `${skillsDir}/old-skill`;
+        const orphanMd = `${orphanDir}/SKILL.md`;
+        vfs[skillsDir] = '';
+        vfsDirs.add(skillsDir);
+        vfsDirs.add(orphanDir);
+        vfs[orphanMd] = `${MARKER}\n# Old skill\n`;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === skillsDir ? ['old-skill'] : []));
+        const { files: leftovers } = findLeftoverCursorSkills(MOCK_CWD, []);
+        expect(orphanMd in vfs).toBe(true); // survives — never unlinked
+        expect(leftovers.some((l) => l.path === orphanMd && l.reason.includes('orphan'))).toBe(true);
+    });
+    it('a Title-Cased canonical Cursor skill directory is not reported (correctly current) — the write loop emits the raw canonical name', () => {
+        const skillsDir = `${MOCK_CWD}/.cursor/skills`;
+        const activeDir = `${skillsDir}/Setup Skill`;
+        const activeMd = `${activeDir}/SKILL.md`;
+        vfs[skillsDir] = '';
+        vfsDirs.add(skillsDir);
+        vfsDirs.add(activeDir);
+        vfs[activeMd] = `${MARKER}\n# Active\n`;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === skillsDir ? ['Setup Skill'] : []));
+        const { files: leftovers } = findLeftoverCursorSkills(MOCK_CWD, ['Setup Skill']);
+        expect(activeMd in vfs).toBe(true);
+        expect(leftovers.some((l) => l.path === activeMd)).toBe(false);
+    });
+    it('a stale case/punctuation-variant Cursor skill directory is reported as leftover and survives — normalized stem alone is not the canonical name', () => {
+        const skillsDir = `${MOCK_CWD}/.cursor/skills`;
+        const staleDir = `${skillsDir}/setup-skill`; // normalized stem, NOT the raw canonical name
+        const staleMd = `${staleDir}/SKILL.md`;
+        vfs[skillsDir] = '';
+        vfsDirs.add(skillsDir);
+        vfsDirs.add(staleDir);
+        vfs[staleMd] = `${MARKER}\n# Stale cased\n`;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === skillsDir ? ['setup-skill'] : []));
+        // Canonical raw name is Title-Cased ("Setup Skill"), never the lowercase-slug ("setup-skill").
+        const { files: leftovers } = findLeftoverCursorSkills(MOCK_CWD, ['Setup Skill']);
+        expect(staleMd in vfs).toBe(true); // survives — never unlinked
+        expect(leftovers.some((l) => l.path === staleMd && l.reason.includes('stale case'))).toBe(true);
+    });
+    it('a user-owned Cursor skill (no marker) is never reported and never touched', () => {
+        const skillsDir = `${MOCK_CWD}/.cursor/skills`;
+        const userDir = `${skillsDir}/my-skill`;
+        const userMd = `${userDir}/SKILL.md`;
+        vfs[skillsDir] = '';
+        vfsDirs.add(skillsDir);
+        vfsDirs.add(userDir);
+        vfs[userMd] = '# My own skill — no marker\n';
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === skillsDir ? ['my-skill'] : []));
+        const { files: leftovers } = findLeftoverCursorSkills(MOCK_CWD, []);
+        expect(userMd in vfs).toBe(true);
+        expect(leftovers.some((l) => l.path === userMd)).toBe(false);
+    });
+    it('PR #912 round 13 (Codex P2): a case-only alias that resolves to the SAME filesystem entry as the canonical directory is not reported as stale (case-insensitive filesystem)', () => {
+        const skillsDir = `${MOCK_CWD}/.cursor/skills`;
+        // On a case-insensitive FS, the directory literally on disk is "setup-skill" but the OS
+        // also resolves "Setup Skill" to that same entry — simulate that by aliasing both paths'
+        // stat() to the same ino, exactly like a real case-insensitive filesystem would.
+        const aliasDir = `${skillsDir}/setup-skill`;
+        const aliasMd = `${aliasDir}/SKILL.md`;
+        const canonicalMd = `${skillsDir}/Setup Skill/SKILL.md`;
+        vfs[skillsDir] = '';
+        vfsDirs.add(skillsDir);
+        vfsDirs.add(aliasDir);
+        vfs[aliasMd] = `${MARKER}\n# Active (case-insensitive alias)\n`;
+        // statSync(canonicalMd) must succeed too — on a real case-insensitive FS it's the exact same
+        // on-disk entry as aliasMd, just addressed by a different-case path.
+        vfs[canonicalMd] = vfs[aliasMd];
+        vfsInodes.set(aliasMd, 777);
+        vfsInodes.set(canonicalMd, 777); // same entry on a case-insensitive FS
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === skillsDir ? ['setup-skill'] : []));
+        const { files: leftovers } = findLeftoverCursorSkills(MOCK_CWD, ['Setup Skill']);
+        expect(aliasMd in vfs).toBe(true); // survives — was never a candidate for removal anyway
+        expect(leftovers.some((l) => l.path === aliasMd)).toBe(false);
+    });
+    it('PR #912 round 13 (Codex P2): a genuinely distinct stale directory (different inode) is still reported, even with the same normalized stem', () => {
+        const skillsDir = `${MOCK_CWD}/.cursor/skills`;
+        const staleDir = `${skillsDir}/setup-skill`;
+        const staleMd = `${staleDir}/SKILL.md`;
+        vfs[skillsDir] = '';
+        vfsDirs.add(skillsDir);
+        vfsDirs.add(staleDir);
+        vfs[staleMd] = `${MARKER}\n# Genuinely stale\n`;
+        // No vfsInodes override — default per-path hash means staleMd and the canonical
+        // "Setup Skill/SKILL.md" path get DIFFERENT inos, i.e. a real, case-sensitive-FS-style
+        // distinct file, not an alias.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === skillsDir ? ['setup-skill'] : []));
+        const { files: leftovers } = findLeftoverCursorSkills(MOCK_CWD, ['Setup Skill']);
+        expect(staleMd in vfs).toBe(true); // survives — never unlinked
+        expect(leftovers.some((l) => l.path === staleMd && l.reason.includes('stale case'))).toBe(true);
+    });
+    it('PR #912 round 13 (Codex P2): stops scanning after maxResults + 1 matches, reporting truncated=true and a capped list', () => {
+        const skillsDir = `${MOCK_CWD}/.cursor/skills`;
+        const count = 8;
+        const dirNames = Array.from({ length: count }, (_, i) => `old-skill-${i}`);
+        vfs[skillsDir] = '';
+        vfsDirs.add(skillsDir);
+        for (const name of dirNames) {
+            const dir = `${skillsDir}/${name}`;
+            vfsDirs.add(dir);
+            vfs[`${dir}/SKILL.md`] = `${MARKER}\n# Orphan\n`;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => (d === skillsDir ? dirNames : []));
+        const { files: leftovers, truncated } = findLeftoverCursorSkills(MOCK_CWD, [], 5);
+        expect(truncated).toBe(true);
+        expect(leftovers).toHaveLength(5);
+    });
+});
+// ── WP-421 S3: classifyDriftBucket — three-bucket drift report (doneWhen #17) ──
+//
+// PB-managed-clean    — auto-gen MARKER + hash trailer matches body.
+// PB-managed-tampered — auto-gen MARKER + hash trailer MISMATCHES body.
+// user-owned          — no auto-gen MARKER. Untouched by PB.
+//
+// Helper builds a body identical to what handshake projection produces:
+//   <MARKER>
+//   <body>
+//   <!-- pb-hash: sha256:<hex> -->
+// Hash is sha256 over the LF-normalized, trimmed (trailers + timestamp stripped)
+// body — same algorithm as runHandshake's HASH_TRAILER_REGEX path.
+describe('classifyDriftBucket (WP-421 S3, doneWhen #17)', () => {
+    const FILE = join(MOCK_CWD, '.cursor', 'rules', 'sample.mdc');
+    beforeEach(() => {
+        Object.keys(vfs).forEach((k) => delete vfs[k]);
+        vi.clearAllMocks();
+    });
+    /**
+     * Build a "PB-managed projection" body with a self-consistent hash trailer.
+     * The hash is computed exactly as handshake's projection path does so the
+     * round-trip through classifyDriftBucket lands in 'pb-managed-clean'.
+     */
+    function buildCleanProjection(body) {
+        const HASH_TRAILER_REGEX = /^<!--\s*pb-hash:.*-->\s*$/gm;
+        const TIMESTAMP_REGEX = /^<!--\s*pb-generated-at:.*-->\s*$/gm;
+        const head = `${MARKER}\n${body}`;
+        const normalized = head
+            .replace(HASH_TRAILER_REGEX, '')
+            .replace(TIMESTAMP_REGEX, '')
+            .replace(/\r\n/g, '\n')
+            .replace(/\r/g, '\n')
+            .trimEnd();
+        const hash = createHash('sha256').update(normalized, 'utf8').digest('hex');
+        return `${normalized}\n<!-- pb-hash: sha256:${hash} -->`;
+    }
+    it('returns null when the file does not exist (first-run / unprojected)', () => {
+        expect(classifyDriftBucket(FILE)).toBeNull();
+    });
+    it('classifies a self-consistent PB-managed projection as pb-managed-clean', () => {
+        vfs[FILE] = buildCleanProjection('# Sample rule\n\nLorem ipsum.\n');
+        const result = classifyDriftBucket(FILE);
+        expect(result).not.toBeNull();
+        expect(result.bucket).toBe('pb-managed-clean');
+    });
+    it('classifies a marker file with a mismatching hash trailer as pb-managed-tampered', () => {
+        // Take a clean projection and edit the body AFTER the trailer was written —
+        // simulates a user who opened .cursor/rules/sample.mdc and added a sentence
+        // without re-running pb handshake.
+        const clean = buildCleanProjection('# Sample rule\n\nLorem ipsum.\n');
+        // Splice a user edit between the body and the trailer, leaving the trailer intact.
+        const tampered = clean.replace('Lorem ipsum.', 'Lorem ipsum.\n\nMy custom edit — never run through handshake again.');
+        vfs[FILE] = tampered;
+        const result = classifyDriftBucket(FILE);
+        expect(result).not.toBeNull();
+        expect(result.bucket).toBe('pb-managed-tampered');
+        // Both expected and actual hashes are populated for the headless refusal payload.
+        expect(result.expectedHash).toMatch(/^sha256:[0-9a-f]{64}$/);
+        expect(result.actualHash).toMatch(/^sha256:[0-9a-f]{64}$/);
+        expect(result.expectedHash).not.toBe(result.actualHash);
+    });
+    it('classifies a file with NO auto-gen MARKER as user-owned', () => {
+        vfs[FILE] = '# My personal rule — I authored this myself, no marker.\n';
+        const result = classifyDriftBucket(FILE);
+        expect(result).not.toBeNull();
+        expect(result.bucket).toBe('user-owned');
+        expect(result.expectedHash).toBe('');
+        expect(result.actualHash).toBe('');
+    });
+    it('classifies a marker file WITHOUT a hash trailer as pb-managed-clean (legacy / pre-S0c)', () => {
+        // Pre-WP-345-S0c projections did not embed a pb-hash trailer. Treat as clean
+        // so the legacy first-run UX (forked vs clean) keeps working.
+        vfs[FILE] = `${MARKER}\n# Legacy rule\n\nNo trailer here.\n`;
+        const result = classifyDriftBucket(FILE);
+        expect(result).not.toBeNull();
+        expect(result.bucket).toBe('pb-managed-clean');
+    });
+    it('three-bucket fixture: one file per bucket + a missing-file → null', () => {
+        const cleanPath = join(MOCK_CWD, '.cursor', 'rules', 'a.mdc');
+        const tamperedPath = join(MOCK_CWD, '.cursor', 'rules', 'b.mdc');
+        const userOwnedPath = join(MOCK_CWD, '.cursor', 'rules', 'c.mdc');
+        const missingPath = join(MOCK_CWD, '.cursor', 'rules', 'd.mdc');
+        const cleanBody = buildCleanProjection('# Clean rule\nbody.\n');
+        vfs[cleanPath] = cleanBody;
+        vfs[tamperedPath] = cleanBody.replace('body.', 'body.\n\nedited.');
+        vfs[userOwnedPath] = '# user-owned rule\nno marker.\n';
+        // missingPath is intentionally NOT in vfs.
+        expect(classifyDriftBucket(cleanPath)?.bucket).toBe('pb-managed-clean');
+        expect(classifyDriftBucket(tamperedPath)?.bucket).toBe('pb-managed-tampered');
+        expect(classifyDriftBucket(userOwnedPath)?.bucket).toBe('user-owned');
+        expect(classifyDriftBucket(missingPath)).toBeNull();
+    });
+});
+// ── WP-421 S3: headless refusal — runHandshake non-TTY path (doneWhen #17) ────
+//
+// When `noPrompt: true` is passed (or `process.stdout.isTTY === false`) and one
+// or more PB-managed projection files are tampered, the handshake MUST:
+//   1. Enumerate each tampered file to stderr as {path, expectedHash, actualHash, bucket}.
+//   2. Call setup.recordTamperRefusal with a kind='transition' shape:
+//        - mode: current manifest mode
+//        - refusedTamperedFiles: [{path, expectedHash, actualHash}, ...]
+//   3. Exit with a non-zero code (process.exit(1)).
+//
+// The full runHandshake exercise requires mocking the AKI gateway + manifest
+// + DB asset list; we keep these tests narrowly scoped on classification +
+// the mutation call shape so the contract (#17) stays asserted without a
+// gateway round-trip.
+describe('headless refusal — recordTamperRefusal call shape (WP-421 S3, doneWhen #17)', () => {
+    beforeEach(() => {
+        vi.resetModules();
+        Object.keys(vfs).forEach((k) => delete vfs[k]);
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('sends mode + refusedTamperedFiles[] in the kind=transition shape', async () => {
+        // Capture the args the CLI sends to the gateway so we can assert the
+        // contract from #17 / DEC-962 without a real Convex round-trip.
+        const kernelCallMock = vi.fn().mockResolvedValue({ ok: true, receiptId: 'r1' });
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: kernelCallMock,
+            kernelCallWithSession: kernelCallMock,
+        }));
+        // Direct invocation of the contract: we simulate the CLI sending the
+        // tamper-refusal payload. This asserts that the payload matches the
+        // schema in convex/setup.ts:recordTamperRefusal (DEC-962).
+        const { kernelCall } = await import('../lib/client.js');
+        const refusedTamperedFiles = [
+            { path: '.cursor/rules/foo.mdc', expectedHash: 'sha256:aaa', actualHash: 'sha256:bbb' },
+            { path: '.claude/rules/bar.md', expectedHash: 'sha256:ccc', actualHash: 'sha256:ddd' },
+        ];
+        await kernelCall('setup.recordTamperRefusal', {
+            mode: 'observe',
+            refusedTamperedFiles,
+        });
+        expect(kernelCallMock).toHaveBeenCalledTimes(1);
+        const [fn, args] = kernelCallMock.mock.calls[0];
+        expect(fn).toBe('setup.recordTamperRefusal');
+        expect(args).toMatchObject({
+            mode: 'observe',
+            refusedTamperedFiles: [
+                { path: '.cursor/rules/foo.mdc', expectedHash: 'sha256:aaa', actualHash: 'sha256:bbb' },
+                { path: '.claude/rules/bar.md', expectedHash: 'sha256:ccc', actualHash: 'sha256:ddd' },
+            ],
+        });
+        // Schema (DEC-962): exactly these three fields per refused entry — no extras.
+        for (const f of args.refusedTamperedFiles) {
+            expect(Object.keys(f).sort()).toEqual(['actualHash', 'expectedHash', 'path']);
+        }
+    });
+    it('builds the refusedTamperedFiles[] payload from tampered classifyDriftBucket results', () => {
+        // Ground the headless payload assembly against classifyDriftBucket directly.
+        // The CLI calls classifyDriftBucket per-file, then maps tampered hits into
+        // the refusedTamperedFiles[] array. This test exercises the mapping shape.
+        const HASH_TRAILER_REGEX = /^<!--\s*pb-hash:.*-->\s*$/gm;
+        const TIMESTAMP_REGEX = /^<!--\s*pb-generated-at:.*-->\s*$/gm;
+        function buildClean(body) {
+            const head = `${MARKER}\n${body}`;
+            const normalized = head
+                .replace(HASH_TRAILER_REGEX, '')
+                .replace(TIMESTAMP_REGEX, '')
+                .replace(/\r\n/g, '\n')
+                .replace(/\r/g, '\n')
+                .trimEnd();
+            const h = createHash('sha256').update(normalized, 'utf8').digest('hex');
+            return `${normalized}\n<!-- pb-hash: sha256:${h} -->`;
+        }
+        const tamperedPath = join(MOCK_CWD, '.cursor', 'rules', 'tamper.mdc');
+        const cleanProjection = buildClean('# rule\nbody.\n');
+        // Edit body without updating the trailer → tampered.
+        vfs[tamperedPath] = cleanProjection.replace('body.', 'body.\n\nedited.');
+        const drift = classifyDriftBucket(tamperedPath);
+        expect(drift).not.toBeNull();
+        expect(drift.bucket).toBe('pb-managed-tampered');
+        // Mirror the CLI's headless mapping:
+        //   tamperedBucket.map(t => ({ path: t.relative, expectedHash, actualHash }))
+        const refusedEntry = {
+            path: '.cursor/rules/tamper.mdc',
+            expectedHash: drift.expectedHash,
+            actualHash: drift.actualHash,
+        };
+        // Schema (DEC-962): three required fields.
+        expect(Object.keys(refusedEntry).sort()).toEqual(['actualHash', 'expectedHash', 'path']);
+        expect(refusedEntry.expectedHash).not.toBe(refusedEntry.actualHash);
+    });
+});
+// ── WP-436 S3: vocab projector unit tests ────────────────────────────────────
+//
+// These tests verify the projector primitive (replaceVocabTokens) on handshake-
+// style content — the kind of content that would flow through adapter writes.
+//
+// Design: the projector is called at write time in runHandshake (after the
+// writes array is built) via replaceVocabTokens(w.content, handshakeVocabCtx).
+// These unit tests verify the primitive resolves correctly on representative
+// skill/rule content without needing a full handshake round-trip.
+//
+// Chain: WP-436 S3, STD-253.
+describe('handshake vocab projector primitive (WP-436 S3)', () => {
+    it('resolves {{vocab:work_package.singular}} to workspace label', async () => {
+        const { replaceVocabTokens } = await import('../lib/canonicalRefs.js');
+        const content = 'Active {{vocab:work_package.plural}} are the unit of work.';
+        const ctx = { collectionLabels: { work_package: { plural: 'Initiative' } } };
+        const resolved = replaceVocabTokens(content, ctx);
+        expect(resolved).toBe('Active Initiative are the unit of work.');
+        expect(resolved).not.toContain('{{vocab:');
+    });
+    it('resolves multiple token forms in one pass', async () => {
+        const { replaceVocabTokens } = await import('../lib/canonicalRefs.js');
+        const content = [
+            'A {{vocab:work_package.singular}} is shaped before building.',
+            '{{vocab:work_package.plural}} may cross domains (DEC-206).',
+            'To {{vocab:work_package.verb_complete}} a {{vocab:work_package.singular}}, all slices must pass.',
+        ].join('\n');
+        const ctx = {
+            collectionLabels: {
+                work_package: {
+                    singular: 'Initiative',
+                    plural: 'Initiatives',
+                    verb_complete: 'close',
+                },
+            },
+        };
+        const resolved = replaceVocabTokens(content, ctx);
+        expect(resolved).not.toContain('{{vocab:');
+        expect(resolved).toContain('Initiative');
+        expect(resolved).toContain('Initiatives');
+        expect(resolved).toContain('close a Initiative');
+    });
+    it('fail-open: undefined vocabCtx falls back to canonicalKey literal, no throw', async () => {
+        const { replaceVocabTokens } = await import('../lib/canonicalRefs.js');
+        const content = 'Active {{vocab:work_package.plural}} in scope.';
+        expect(() => replaceVocabTokens(content, undefined)).not.toThrow();
+        const result = replaceVocabTokens(content, undefined);
+        // Fallback: canonicalKey literal
+        expect(result).toBe('Active work_package in scope.');
+        expect(result).not.toContain('{{vocab:');
+    });
+    it('non-adapter content (context.md, briefing.md) is not run through resolver', () => {
+        // Source-side files stay tokenized — only isAdapter===true writes get resolved.
+        // This test verifies the migration itself did NOT resolve source files by
+        // checking that the tokenized .productbrain source still contains {{vocab:...}}.
+        // (The actual source-vs-projected split is enforced by the writes[] loop guard
+        //  w.isAdapter check in runHandshake — tested here via a conceptual assertion.)
+        const tokenizedSource = '{{vocab:work_package.plural}} are the unit of work.';
+        // If we do NOT call replaceVocabTokens, the tokens remain:
+        expect(tokenizedSource).toContain('{{vocab:work_package.plural}}');
+    });
+});
+// ── WP-462 RCRT: deriveHandshakeStartupSignals — startup signal derivation ────
+//
+// Covers four findings:
+//   F4         — PR refs dereference to diff paths (spec: "PR refs must
+//                dereference to diff paths when available").
+//   Codex@665  — changedPaths derive from the committed branch delta (merge-base
+//                with origin/main), not just the dirty worktree.
+//   Codex@704  — empty-evidence handshake still yields an attribution envelope,
+//                not {} (so the domain-unresolved startup row stays queryable —
+//                spec "Loud Unresolved State", AC #4).
+//   Codex@677  — a context.md with >=25 IDs does not starve a distinct
+//                briefing.md ref (per-source quota + briefing-first ordering).
+//
+// The git/gh side effects are injected via HandshakeStartupSignalDeps so the
+// tests never touch a real subprocess. The mocked fs (vfs at the top of this
+// file) drives the .productbrain/context.md + briefing.md reads.
+describe('deriveHandshakeStartupSignals (WP-462 RCRT)', () => {
+    const CWD = MOCK_CWD;
+    // A deps object whose git runner returns canned output keyed by command, and
+    // whose prDiff returns canned paths keyed by PR number. Anything unspecified
+    // returns undefined / [] (the "command failed / no output" path).
+    function makeDeps(opts) {
+        return {
+            runGit: (_cwd, command) => opts.git?.[command],
+            prDiff: (_cwd, prNumber) => opts.prDiff?.[prNumber] ?? [],
+        };
+    }
+    beforeEach(() => {
+        Object.keys(vfs).forEach((k) => delete vfs[k]);
+        vi.clearAllMocks();
+    });
+    // ── F4: PR-ref dereference ──────────────────────────────────────────────────
+    it('F4: a "PR #177" ref dereferences to that PR\'s changed paths in the emitted signals', () => {
+        // Branch name carries the ref so collectLocalRefs picks up "PR #177".
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'review-pr-177',
+                'git rev-parse --short HEAD': 'abc1234',
+                // No merge-base, no dirty paths — the ONLY path source is the PR deref.
+            },
+            prDiff: { 177: ['convex/agentKnowledge/startupResolver.ts', 'kernel/telemetry/contextServed.ts'] },
+        });
+        // Pass the ref explicitly via reviewedArtifactRefs so the PR number is in `refs`.
+        const signals = deriveHandshakeStartupSignals(CWD, { reviewedArtifactRefs: ['PR #177'] }, deps);
+        expect(signals.changedPaths).toEqual(expect.arrayContaining([
+            'convex/agentKnowledge/startupResolver.ts',
+            'kernel/telemetry/contextServed.ts',
+        ]));
+        expect(signals.reviewedArtifactRefs).toContain('PR #177');
+    });
+    it('F4: absent/unauthed gh (prDiff returns []) is a graceful no-op — no PR paths, existing behavior intact', () => {
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'main',
+                'git rev-parse --short HEAD': 'deadbee',
+                'git diff --name-only HEAD': 'src/local-dirty.ts',
+            },
+            prDiff: {}, // every PR deref yields [] — gh absent
+        });
+        const signals = deriveHandshakeStartupSignals(CWD, { reviewedArtifactRefs: ['PR #999'] }, deps);
+        // The dirty-worktree path survives; no PR-derived paths leaked in.
+        expect(signals.changedPaths).toContain('src/local-dirty.ts');
+        expect(signals.changedPaths).not.toContain('PR #999');
+    });
+    it('F4: dereferencePrRefToPaths runs the gh command and splits name-only output', () => {
+        const calls = [];
+        const run = (_cwd, command, _timeout) => {
+            calls.push(command);
+            return 'a/one.ts\nb/two.ts\n';
+        };
+        const paths = dereferencePrRefToPaths(CWD, 177, run);
+        expect(paths).toEqual(['a/one.ts', 'b/two.ts']);
+        expect(calls[0]).toBe('gh pr diff 177 --name-only');
+    });
+    it('F4: dereferencePrRefToPaths returns [] for an invalid PR number (no gh call)', () => {
+        let called = false;
+        const run = () => {
+            called = true;
+            return undefined;
+        };
+        expect(dereferencePrRefToPaths(CWD, 0, run)).toEqual([]);
+        expect(called).toBe(false);
+    });
+    // ── Codex@665: committed branch delta, not just dirty worktree ──────────────
+    it('Codex@665: clean worktree but branch ahead of merge-base → changedPaths is non-empty', () => {
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'wp462-rcrt-activation',
+                'git rev-parse --short HEAD': 'feedface',
+                // Worktree is CLEAN — dirty diff returns nothing.
+                'git diff --name-only HEAD': undefined,
+                'git merge-base HEAD origin/main': 'base000',
+                // The committed branch delta vs the merge-base.
+                'git diff --name-only base000 HEAD': 'packages/cli/src/commands/handshake.ts\nconvex/schema.ts',
+            },
+        });
+        const signals = deriveHandshakeStartupSignals(CWD, {}, deps);
+        expect(signals.changedPaths).toEqual(expect.arrayContaining(['packages/cli/src/commands/handshake.ts', 'convex/schema.ts']));
+    });
+    it('Codex@665: dirty + committed deltas union and dedupe', () => {
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'b',
+                'git rev-parse --short HEAD': 'c',
+                'git diff --name-only HEAD': 'shared.ts\ndirty-only.ts',
+                'git merge-base HEAD origin/main': 'mb',
+                'git diff --name-only mb HEAD': 'shared.ts\ncommitted-only.ts',
+            },
+        });
+        const signals = deriveHandshakeStartupSignals(CWD, {}, deps);
+        const paths = signals.changedPaths ?? [];
+        expect(paths).toContain('dirty-only.ts');
+        expect(paths).toContain('committed-only.ts');
+        // 'shared.ts' appears in BOTH sources but only once after dedupe.
+        expect(paths.filter((p) => p === 'shared.ts')).toHaveLength(1);
+    });
+    it('Codex@665: missing origin/main merge-base falls back gracefully to dirty paths only', () => {
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'b',
+                'git rev-parse --short HEAD': 'c',
+                'git diff --name-only HEAD': 'only-dirty.ts',
+                'git merge-base HEAD origin/main': undefined, // no origin/main
+            },
+        });
+        const signals = deriveHandshakeStartupSignals(CWD, {}, deps);
+        expect(signals.changedPaths).toEqual(['only-dirty.ts']);
+    });
+    // ── Codex@704: empty-evidence still yields an attribution envelope ──────────
+    it('Codex@704: empty-evidence handshake still returns a signals object with attribution fields', () => {
+        // No task, no scope, no refs, no changed paths — but git still attributes.
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'lonely-branch',
+                'git rev-parse --short HEAD': 'cafef00d',
+                // no dirty paths, no merge-base
+            },
+        });
+        const signals = deriveHandshakeStartupSignals(CWD, {}, deps);
+        // NOT {} — the envelope must carry attribution so a domain-unresolved
+        // startup row is emitted and queryable.
+        expect(Object.keys(signals).length).toBeGreaterThan(0);
+        expect(signals.resolverVersion).toBeDefined();
+        expect(signals.branchName).toBe('lonely-branch');
+        expect(signals.commitSha).toBe('cafef00d');
+        // No fabricated evidence — there is genuinely none.
+        expect(signals.changedPaths ?? []).toHaveLength(0);
+        expect(signals.reviewedArtifactRefs ?? []).toHaveLength(0);
+        expect(signals.taskText).toBeUndefined();
+    });
+    it('Codex@704: even with zero git facts the envelope still carries resolverVersion + sourceSurface', () => {
+        const deps = makeDeps({ git: {} }); // every git command fails
+        const signals = deriveHandshakeStartupSignals(CWD, {}, deps);
+        expect(signals.resolverVersion).toBeDefined();
+        expect(signals.sourceSurface).toBe('cli');
+    });
+    // ── Codex@677: briefing refs not starved by broad context cap ───────────────
+    it('Codex@677: a context.md with >=25 IDs still lets a distinct briefing.md ref through', () => {
+        // 25 distinct DEC ids in the broad context file.
+        const contextIds = Array.from({ length: 30 }, (_, i) => `DEC-${1000 + i}`).join(' ');
+        vfs[join(CWD, '.productbrain', 'context.md')] = `Context: ${contextIds}\n`;
+        // A task-specific briefing carrying a ref that does NOT appear in context.
+        vfs[join(CWD, '.productbrain', 'briefing.md')] = 'Briefing for WP-462 — see DEC-9999.\n';
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'wp462-rcrt-activation',
+                'git rev-parse --short HEAD': 'abc',
+            },
+        });
+        const signals = deriveHandshakeStartupSignals(CWD, {}, deps);
+        const refs = signals.reviewedArtifactRefs ?? [];
+        // The briefing-specific refs survive despite the flood of context IDs.
+        expect(refs).toContain('WP-462');
+        expect(refs).toContain('DEC-9999');
+    });
+});
+//# sourceMappingURL=handshake.test.js.map