@productbrain/cli 0.1.0-beta.11277 → 0.1.0-beta.11288

package/dist/__tests__/handshake.test.js

@@ -1,1040 +0,0 @@
-/**
- * pb handshake --init — unit tests.
- * DEC-271: two-file split (team vs personal). DEC-272: permission whitelist.
- * TEN-712: every hook command must end with '|| true' so it never blocks Claude Code from starting.
- */
-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' });
-        }
-        // Round 15: dev/ino for directory-entry-identity comparisons (findLeftoverCursorSkills'
-        // live-alias check). Same default-hash-or-vfsInodes-override scheme as statSync below.
-        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 {
-            isDirectory: () => isDir,
-            isFile: () => isFile,
-            isSymbolicLink: () => isSymlink,
-            dev: 1,
-            ino,
-        };
-    }),
-    // 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.SessionEnd).toHaveLength(1);
-            expect(team.hooks.Stop).toBeUndefined();
-            expect(team.hooks.PreCompact).toBeUndefined();
-            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.SessionEnd).toHaveLength(1);
-            expect(team.hooks.Stop).toBeUndefined();
-            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);
-        });
-    });
-    // TASK-763 (DEC-2038): an older init put pb session close on Stop, which fires after every turn.
-    describe('legacy Stop close migration', () => {
-        const close = { type: 'command', command: 'pb session close 2>/dev/null || true', statusMessage: 'Closing pb session...' };
-        const other = { type: 'command', command: 'echo my-own-stop-hook' };
-        it('removes the Stop close, keeps an unrelated Stop hook, and installs the SessionEnd close once', async () => {
-            vfs[TEAM_PATH] = JSON.stringify({ hooks: { Stop: [{ hooks: [close, other] }] } });
-            await runHandshakeInit({ level: 'work', dryRun: false });
-            await runHandshakeInit({ level: 'work', dryRun: false });
-            const team = JSON.parse(vfs[TEAM_PATH]);
-            expect(team.hooks.Stop).toEqual([{ hooks: [other] }]);
-            expect(team.hooks.SessionEnd).toHaveLength(1);
-            expect(team.hooks.SessionEnd[0].hooks[0]).toMatchObject({ command: close.command, timeout: 15 });
-        });
-        it('drops the Stop event entirely when the close was its only hook', async () => {
-            vfs[TEAM_PATH] = JSON.stringify({ hooks: { Stop: [{ hooks: [close] }] } });
-            await runHandshakeInit({ level: 'work', dryRun: false });
-            const team = JSON.parse(vfs[TEAM_PATH]);
-            expect(team.hooks.Stop).toBeUndefined();
-            expect(team.hooks.SessionEnd).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 sessionEndCmd = team.hooks.SessionEnd[0].hooks[0].command;
-            expect(sessionStartCmd).toContain('|| true');
-            expect(sessionEndCmd).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>&1 || 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.SessionEnd[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's probeStarterSetupSeeded + pollUntilSeedsReady tests deleted at WP-776 S0
-// round-1 review (Codex P1, verified regression): nothing seeds setup-assets any more, so
-// the functions they tested (whose readiness gate was keyed on starterSetupSeeded alone)
-// are deleted from packages/cli/src/commands/handshake.ts.
-// ── 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 15 (Codex P2): a case-only alias that resolves to the SAME directory entry as the canonical path 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 giving both DIRECTORY
-        // paths' lstat() the same dev+ino, exactly like a real case-insensitive filesystem would.
-        const aliasDir = `${skillsDir}/setup-skill`;
-        const canonicalDir = `${skillsDir}/Setup Skill`;
-        const aliasMd = `${aliasDir}/SKILL.md`;
-        vfs[skillsDir] = '';
-        vfsDirs.add(skillsDir);
-        vfsDirs.add(aliasDir);
-        vfsDirs.add(canonicalDir); // same physical entry, reachable under either spelling
-        vfs[aliasMd] = `${MARKER}\n# Active (case-insensitive alias)\n`;
-        vfsInodes.set(aliasDir, 777);
-        vfsInodes.set(canonicalDir, 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 15 (Codex P2): the SOLE on-disk entry being itself a symlink is still a live alias, not a leftover, when both case spellings resolve to it', () => {
-        const skillsDir = `${MOCK_CWD}/.cursor/skills`;
-        // "setup-skill" is the ONLY directory entry, and it happens to be a symlink (e.g. to some
-        // external skill store) — but on a case-insensitive FS, "Setup Skill" resolves to that SAME
-        // entry too. Round 14's "never exempt a symlink" rule wrongly flagged this as stale; round 15
-        // compares lstat identity instead, which correctly treats "same entry" as a live alias
-        // regardless of whether that shared entry happens to be a symlink.
-        const aliasDir = `${skillsDir}/setup-skill`;
-        const canonicalDir = `${skillsDir}/Setup Skill`;
-        const aliasMd = `${aliasDir}/SKILL.md`;
-        vfs[skillsDir] = '';
-        vfsDirs.add(skillsDir);
-        vfsSymlinks.add(aliasDir);
-        vfsSymlinks.add(canonicalDir); // same physical symlink, addressed by either spelling
-        vfs[aliasMd] = `${MARKER}\n# Active (sole entry is a symlink)\n`;
-        vfsInodes.set(aliasDir, 999);
-        vfsInodes.set(canonicalDir, 999); // identical lstat identity — one real entry
-        // 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);
-        expect(leftovers.some((l) => l.path === aliasMd)).toBe(false);
-    });
-    it('PR #912 round 15 (Codex P2): a SYMLINKED case-only alias pointing AT a distinct canonical directory is still reported as stale (case-sensitive filesystem, two real entries)', () => {
-        const skillsDir = `${MOCK_CWD}/.cursor/skills`;
-        // "setup-skill" is a SYMLINK pointing AT the canonical "Setup Skill" directory — TWO
-        // distinct, separately-readdirSync-visible entries. lstat (never follows) on each gives a
-        // DIFFERENT identity: the symlink's own inode vs. the real target directory's inode.
-        const aliasDir = `${skillsDir}/setup-skill`;
-        const canonicalDir = `${skillsDir}/Setup Skill`;
-        const aliasMd = `${aliasDir}/SKILL.md`;
-        vfs[skillsDir] = '';
-        vfsDirs.add(skillsDir);
-        vfsSymlinks.add(aliasDir); // the discovered directory entry IS a symlink
-        vfsDirs.add(canonicalDir); // the canonical directory is a real, distinct entry
-        vfs[aliasMd] = `${MARKER}\n# Symlinked alias\n`;
-        // No vfsInodes override — default per-path hash means aliasDir and canonicalDir get
-        // DIFFERENT inos, matching two genuinely distinct filesystem objects.
-        // 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 — report-only, never unlinked
-        expect(leftovers.some((l) => l.path === aliasMd && l.reason.includes('stale case'))).toBe(true);
-    });
-    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`;
-        // The canonical "Setup Skill" directory doesn't exist in this test at all (lstatSync on it
-        // throws ENOENT, caught, treated as no match) — a real, distinct stale directory, 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