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

package/dist/__tests__/gateway-timeout-body-phase.test.js

@@ -0,0 +1,121 @@
+/**
+ * gateway-timeout-body-phase.test.ts — WP-575 (TEN-2917, TEN-1126), PR #533 review round.
+ *
+ * THE DEFECT THIS PINS: `fetch` resolves as soon as HEADERS arrive, while the budget's
+ * AbortSignal is still live. A server that returns `200` and then stalls mid-body therefore
+ * aborts during `res.json()` — NOT during `fetch` — which put it outside the caller's
+ * timeout-classification `try`. The old blanket `.catch(() => ({}))` in `parseKernelEnvelope`
+ * swallowed that abort into an empty envelope, and a `200` status then read it as SUCCESS
+ * with `undefined` data. A timed-out write reported as completed: exactly the false-outcome
+ * this work package exists to remove, running in reverse.
+ *
+ * The mcp-server connector had the identical hole and it was fixed there earlier in this same
+ * PR (`throwClassifiedGatewayFailure`, mcp-server/src/gatewaySeam.ts). The CLI's three
+ * kernel-call variants were the unswept siblings — so all three are asserted here, not just
+ * the one the reviewer named.
+ */
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { kernelCall, kernelCallEnvelope } from '../lib/client.js';
+import { CLIError, ErrorCode } from '../lib/errors.js';
+import { latencyBudgetMsForRoute } from '../generated/routeLatencyBudget.generated.js';
+const realFetch = global.fetch;
+/**
+ * A `Response` whose headers have already arrived but whose BODY rejects the way
+ * `AbortSignal.timeout` really does — a DOMException named "TimeoutError". The client
+ * discriminates on that `name`, so a plain `new Error()` would not exercise the branch.
+ */
+function responseThatStallsMidBody(status = 200, abortName = 'TimeoutError') {
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        statusText: 'OK',
+        headers: { get: () => null },
+        json: async () => {
+            const err = new Error('The operation was aborted due to timeout');
+            err.name = abortName;
+            throw err;
+        },
+    };
+}
+describe('CLI budget abort during the RESPONSE BODY (WP-575, PR #533 review)', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        process.env.CONVEX_SITE_URL = 'https://example.convex.site';
+        process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_test';
+        global.fetch = vi.fn(async () => responseThatStallsMidBody());
+    });
+    afterEach(() => {
+        global.fetch = realFetch;
+    });
+    it('kernelCall surfaces the timeout instead of returning undefined as success', async () => {
+        // The regression in one line: this used to RESOLVE with `undefined`.
+        const err = (await kernelCall('chain.createEntry', {}).catch((e) => e));
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.NETWORK_TIMEOUT);
+    });
+    it('kernelCallEnvelope surfaces it too — the sibling variant, swept in the same round', async () => {
+        const err = (await kernelCallEnvelope('chain.createEntry', {}).catch((e) => e));
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.NETWORK_TIMEOUT);
+    });
+    it('classifies an AbortError body abort too, matching the mcp-server twin', async () => {
+        // Depending on where in undici the budget signal is observed, a body-phase abort can
+        // surface as "AbortError" rather than "TimeoutError". Matching only the latter left that
+        // case falling through to an empty envelope, which a 200 reads as success with
+        // `undefined` data — this work package's own defect, surviving in one phase.
+        // `throwClassifiedGatewayFailure` (mcp-server/src/gatewaySeam.ts) has always accepted both.
+        global.fetch = vi.fn(async () => responseThatStallsMidBody(200, 'AbortError'));
+        const err = (await kernelCall('chain.createEntry', {}).catch((e) => e));
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.NETWORK_TIMEOUT);
+    });
+    it('a NON-OK status keeps its own error — a stalled error body is not a budget timeout', async () => {
+        // The server reached a verdict and said so; only its error body stalled. Reporting a
+        // budget timeout here would trade a real status for "may have completed anyway, search
+        // before retrying" about a call the server explicitly failed (PR #533 review round 5).
+        global.fetch = vi.fn(async () => responseThatStallsMidBody(429));
+        const err = (await kernelCall('chain.createEntry', {}).catch((e) => e));
+        expect(err.code).not.toBe(ErrorCode.NETWORK_TIMEOUT);
+        expect(err.message).not.toMatch(/latency budget/i);
+    });
+    it('is a TIMEOUT, never NETWORK_UNREACHABLE — the host answered', async () => {
+        // The whole point of the distinction: the connection succeeded and the server began
+        // responding. Reporting "could not reach" would be a false statement about the server
+        // and would imply nothing ran.
+        const err = (await kernelCall('chain.createEntry', {}).catch((e) => e));
+        expect(err.code).not.toBe(ErrorCode.NETWORK_UNREACHABLE);
+        expect(err.message).not.toMatch(/could not reach/i);
+    });
+    it('reports the budget the call was actually judged by, not a hardcoded number', async () => {
+        const err = (await kernelCall('chain.createEntry', {}).catch((e) => e));
+        expect(err.message).toContain(String(latencyBudgetMsForRoute('chain.createEntry')));
+    });
+    it('says the write MAY HAVE COMPLETED — a body-phase abort leaves the outcome unknown', async () => {
+        // The server accepted the request and began responding; only the client stopped
+        // waiting. Telling the agent "it failed" is what invites the duplicating retry
+        // (TEN-1126's ghost entries).
+        const err = (await kernelCall('chain.createEntry', {}).catch((e) => e));
+        expect(err.guidance).toMatch(/may have\s+COMPLETED/i);
+        expect(err.guidance).toMatch(/duplicate/i);
+    });
+    it('a read route is told nothing was written — safe to retry, nothing to duplicate', async () => {
+        const err = (await kernelCall('resolveWorkspace', {}).catch((e) => e));
+        expect(err.guidance).toMatch(/nothing\s+was written/i);
+        expect(err.guidance).toMatch(/safe to retry/i);
+    });
+    it('a NON-timeout parse failure keeps the lenient empty-envelope path', async () => {
+        // Deliberately unchanged: a non-JSON or empty body is already handled by the ok/status
+        // checks every caller runs, and narrowing it here would change unrelated error paths.
+        global.fetch = vi.fn(async () => ({
+            ok: false,
+            status: 500,
+            statusText: 'Internal Server Error',
+            headers: { get: () => null },
+            json: async () => {
+                throw new SyntaxError('Unexpected token < in JSON at position 0');
+            },
+        }));
+        await expect(kernelCall('chain.createEntry', {})).rejects.toThrow(/Internal Server Error/);
+    });
+});
+//# sourceMappingURL=gateway-timeout-body-phase.test.js.map

package/dist/__tests__/gateway-timeout-body-phase.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-timeout-body-phase.test.js","sourceRoot":"","sources":["../../src/__tests__/gateway-timeout-body-phase.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/glossary.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=glossary.test.d.ts.map

package/dist/__tests__/glossary.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glossary.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/glossary.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/glossary.test.js

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { GLOSSARY, formatGlossary } from '../lib/glossary.js';
+describe('glossary', () => {
+    it('has non-empty entries', () => {
+        expect(GLOSSARY.length).toBeGreaterThan(0);
+        for (const entry of GLOSSARY) {
+            expect(entry.term.length).toBeGreaterThan(0);
+            expect(entry.definition.length).toBeGreaterThan(0);
+        }
+    });
+    const requiredTerms = ['workspace', 'entry', 'collection', 'relation', 'session', 'capture', 'profile'];
+    it.each(requiredTerms)('includes required term: %s', (term) => {
+        const found = GLOSSARY.find((g) => g.term === term);
+        expect(found).toBeDefined();
+        expect(found.definition.length).toBeGreaterThan(0);
+    });
+    it('formatGlossary produces formatted multi-line output', () => {
+        const output = formatGlossary();
+        expect(output).toContain('workspace');
+        expect(output).toContain('entry');
+        expect(output).toContain('collection');
+        // Should have multiple lines (one per term)
+        const lines = output.split('\n');
+        expect(lines.length).toBe(GLOSSARY.length);
+    });
+    it('all terms are unique', () => {
+        const terms = GLOSSARY.map((g) => g.term);
+        const unique = new Set(terms);
+        expect(unique.size).toBe(terms.length);
+    });
+});
+//# sourceMappingURL=glossary.test.js.map

package/dist/__tests__/glossary.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glossary.test.js","sourceRoot":"","sources":["../../src/__tests__/glossary.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE9D,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;IACxB,EAAE,CAAC,uBAAuB,EAAE,GAAG,EAAE;QAC/B,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QAC3C,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;YAC7C,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QACrD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,aAAa,GAAG,CAAC,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAExG,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,4BAA4B,EAAE,CAAC,IAAI,EAAE,EAAE;QAC5D,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QACpD,MAAM,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;QAC5B,MAAM,CAAC,KAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;QAChC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QACtC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;QACvC,4CAA4C;QAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;QAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC9B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/handshake-augment.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=handshake-augment.test.d.ts.map

package/dist/__tests__/handshake-augment.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake-augment.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/handshake-augment.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/handshake-augment.test.js

@@ -0,0 +1,424 @@
+/**
+ * TEN-2155 — loop-level integration tests for the handshake region-augmentation feature.
+ *
+ * Drives `runHandshake({ apply: true })` against real temp dirs (real fs, real symlinks,
+ * real realpathSync) and asserts on-disk bytes + the returned report.
+ *
+ * Harness approach: mirrors the WP-426 E3 round-trip block in handshake.e2e.test.ts.
+ * vi.doMock() chains stub every kernel/network/generator call; `../generators/region.js`
+ * and `../generators/region-projections.js` are intentionally NOT mocked so the real
+ * augment mechanism is exercised. `runHandshake` is imported dynamically AFTER the mocks.
+ */
+import { mkdtempSync, writeFileSync, readFileSync, existsSync, rmSync, mkdirSync, symlinkSync, } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { REGION_START, REGION_END, REGION_OPT_OUT } from '../generators/region.js';
+// ── Shared mock wiring (replicates WP-426 E3 beforeEach block exactly) ────────
+let augE2eRoot;
+let augCwdSpy;
+/** Set up a fresh tempdir + all kernel/generator stubs, then point cwd there. */
+async function setupAugmentMocks(manifestYaml) {
+    vi.resetModules();
+    augE2eRoot = mkdtempSync(join(tmpdir(), 'pb-ten2155-augment-'));
+    mkdirSync(join(augE2eRoot, '.productbrain'), { recursive: true });
+    writeFileSync(join(augE2eRoot, '.productbrain', 'manifest.yaml'), manifestYaml);
+    augCwdSpy = vi.spyOn(process, 'cwd').mockReturnValue(augE2eRoot);
+    // Silence stdout/stderr — the full handshake writes formatting noise we don't care about.
+    vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    // ── Kernel: no active/dormant assets; just enough to let the loop complete ──
+    vi.doMock('../lib/client.js', () => ({
+        kernelCall: vi.fn().mockImplementation(async (tool) => {
+            if (tool === 'chain.workspaceReadiness')
+                return null;
+            if (tool === 'chain.getOrientView')
+                return null;
+            if (tool === 'chain.searchEntries')
+                return [];
+            if (tool === 'setup.listAssetsForUser') {
+                return { activeAssets: [], dormantAssets: [], hasAnyReceipt: true };
+            }
+            if (tool === 'setup.updateLastProjectedHash')
+                return { ok: true };
+            if (tool === 'setup.getCurrentSetupState')
+                return { effectiveMode: 'project' };
+            if (tool === 'setup.materializeSetup')
+                return { ok: true, assetCount: 0, receiptWritten: true };
+            return null;
+        }),
+        kernelCallWithSession: vi.fn().mockResolvedValue(null),
+    }));
+    vi.doMock('../lib/config.js', () => ({
+        getConfigOrGuide: vi.fn().mockResolvedValue({
+            apiKey: 'pb_sk_augment_test',
+            siteUrl: 'https://test.convex.site',
+        }),
+    }));
+    vi.doMock('../lib/repo-detect.js', () => ({
+        detectRepo: vi.fn().mockReturnValue({ name: 'augment-test-repo', detectedStack: [], repoSlug: null }),
+        extractWorkspaceProfile: vi.fn().mockReturnValue(null),
+    }));
+    // ── Adapter generators: ABSENT file falls through to this whole-file content.
+    //    Contains MARKER so a future classifyAdapterFile call sees 'pb-managed'.
+    //    Case (b) regression guard: the string must contain 'auto-generated by pb handshake'.
+    vi.doMock('../generators/adapters.js', () => ({
+        MARKER: 'auto-generated by pb handshake',
+        generateAgentsMd: vi.fn().mockReturnValue('<!-- auto-generated by pb handshake -->\nagents'),
+        generateClaudeMd: vi.fn().mockReturnValue('<!-- auto-generated by pb handshake -->\nclaude'),
+        generateCursorMdc: vi.fn().mockReturnValue('<!-- auto-generated by pb handshake -->\ncursor'),
+        generateCopilotMd: vi.fn().mockReturnValue('<!-- auto-generated by pb handshake -->\ncopilot'),
+        generateCopilotInstructionFiles: vi.fn().mockReturnValue([]),
+    }));
+    vi.doMock('../generators/portable-knowledge.js', () => ({
+        readCanonicalSkills: vi.fn().mockReturnValue([]),
+        readCanonicalRules: vi.fn().mockReturnValue([]),
+        readPersonalLayer: vi.fn().mockReturnValue([]),
+        readPersonalSkillsLayer: vi.fn().mockReturnValue([]),
+        generateCursorSkill: vi.fn().mockReturnValue(''),
+        generateCursorRule: vi.fn().mockReturnValue(''),
+        generateCodexSkill: vi.fn().mockReturnValue(''),
+        generateClaudeRule: vi.fn().mockReturnValue(''),
+        generateCodexSkillIndex: vi.fn().mockReturnValue(''),
+        generateClaudeSkillRouter: vi.fn().mockReturnValue(''),
+        shouldEmitToTarget: vi.fn().mockReturnValue(false),
+        filterByLevel: vi.fn().mockImplementation((items) => items),
+        evaluateConditions: vi.fn().mockReturnValue({ included: true, reasons: [] }),
+        validateCodexSkills: vi.fn().mockReturnValue([]),
+        STAGE_TO_MAX_LEVEL: {},
+        LEVEL_ORDER: [],
+    }));
+    vi.doMock('../generators/briefing-md.js', () => ({
+        generateBriefingMd: vi.fn().mockReturnValue('briefing content'),
+    }));
+    vi.doMock('../generators/context-md.js', () => ({
+        generateContextMd: vi.fn().mockReturnValue('context content'),
+    }));
+    vi.doMock('../generators/chain-rules.js', () => ({
+        generateChainRules: vi.fn().mockResolvedValue({
+            content: '',
+            rules: [],
+            classified: {},
+            stats: { generatedRules: 0, suppressedByManual: 0, suppressedByZeroEntries: 0 },
+            gaps: [],
+            sentinel: null,
+        }),
+    }));
+    vi.doMock('../generators/handshake-diff.js', () => ({
+        saveHandshakeState: vi.fn(),
+        loadPreviousState: vi.fn().mockReturnValue(null),
+        diffHandshakeState: vi.fn().mockReturnValue({ added: [], updated: [], removed: [] }),
+        formatDiff: vi.fn().mockReturnValue(''),
+        buildCurrentState: vi.fn().mockReturnValue({}),
+    }));
+    vi.doMock('../generators/surface-profiles.js', () => ({
+        resolveSurfaceProfile: vi.fn().mockReturnValue({ level: 'intermediate' }),
+    }));
+    vi.doMock('../generators/boundary-manifest.js', () => ({
+        generateBoundaryManifest: vi.fn().mockReturnValue(null),
+        getBoundaryEnforcementMode: vi.fn().mockReturnValue('advisory'),
+    }));
+    vi.doMock('../formatters/handshake.js', () => ({
+        formatHandshakeReport: vi.fn().mockReturnValue(''),
+    }));
+    vi.doMock('../lib/hook-intents.js', () => ({
+        composeHooksFromIntents: vi.fn().mockReturnValue({}),
+        getHookStatusForSurface: vi.fn().mockReturnValue([]),
+    }));
+    vi.doMock('../lib/method-registry.js', () => ({
+        loadMethodRegistry: vi.fn().mockResolvedValue({ methods: [], source: 'bundled', stale: false }),
+    }));
+    vi.doMock('../lib/workspaceVocabCache.js', () => ({
+        getOrFetchVocabCtx: vi.fn().mockResolvedValue(null),
+    }));
+    vi.doMock('../lib/telemetry.js', () => ({
+        trackEvent: vi.fn(),
+    }));
+    vi.doMock('../lib/session.js', () => ({
+        readSession: vi.fn().mockReturnValue(null),
+    }));
+    // replaceVocabTokens as identity — region content passes through intact.
+    vi.doMock('../lib/canonicalRefs.js', () => ({
+        parseSemanticRefs: vi.fn().mockReturnValue([]),
+        replaceVocabTokens: vi.fn().mockImplementation((content) => content),
+    }));
+    vi.doMock('../surfaces/telemetry.js', () => ({
+        getReverseMapFallbackMessage: vi.fn().mockReturnValue(''),
+        reportReverseMapMissing: vi.fn(),
+    }));
+}
+/** Manifest for materialize: project + both claude + codex surfaces. */
+const PROJECT_MANIFEST = [
+    'version: "0.1"',
+    'materialize: project',
+    'surfaces:',
+    '  - .claude',
+    '  - .codex',
+    '  - .cursor',
+    '',
+].join('\n');
+/** Manifest without materialize (defaults to observe) + both claude + codex surfaces. */
+const OBSERVE_MANIFEST = [
+    'version: "0.1"',
+    'surfaces:',
+    '  - .claude',
+    '  - .codex',
+    '  - .cursor',
+    '',
+].join('\n');
+/** Manifest for materialize: project + codex only (no claude surface). */
+const CODEX_ONLY_MANIFEST = [
+    'version: "0.1"',
+    'materialize: project',
+    'surfaces:',
+    '  - .codex',
+    '  - .cursor',
+    '',
+].join('\n');
+/** Manifest for materialize: project + claude only (no codex surface). */
+const CLAUDE_ONLY_MANIFEST = [
+    'version: "0.1"',
+    'materialize: project',
+    'surfaces:',
+    '  - .claude',
+    '  - .cursor',
+    '',
+].join('\n');
+/** Drive a single runHandshake call after all mocks are set. Always applies. */
+async function run(opts = {}) {
+    const { runHandshake } = await import('../commands/handshake.js');
+    return runHandshake({ apply: true, noPrompt: true, ...opts });
+}
+// ── Test suite ────────────────────────────────────────────────────────────────
+describe('TEN-2155: region augmentation integration matrix', () => {
+    // Each test gets its own tempdir + fresh mocks.
+    beforeEach(() => {
+        // Intentionally empty — setupAugmentMocks() is called inside each test
+        // because the manifest content varies per test.
+    });
+    afterEach(() => {
+        augCwdSpy?.mockRestore();
+        if (augE2eRoot && existsSync(augE2eRoot)) {
+            rmSync(augE2eRoot, { recursive: true, force: true });
+        }
+        vi.restoreAllMocks();
+    });
+    // ── (a) user-owned CLAUDE.md → region appended, user bytes preserved ────────
+    it('(a) user-owned CLAUDE.md → region appended, user bytes preserved', async () => {
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        const userBody = '# Acme rules\n\nUse pnpm. Validate with zod.\n';
+        writeFileSync(claudePath, userBody);
+        await run();
+        const after = readFileSync(claudePath, 'utf8');
+        expect(after.startsWith(userBody), 'user bytes must be at the start').toBe(true);
+        expect(after.includes(REGION_START), 'must contain REGION_START').toBe(true);
+        expect(after.includes(REGION_END), 'must contain REGION_END').toBe(true);
+    });
+    // ── (a) re-run idempotent ───────────────────────────────────────────────────
+    it('(a) re-run idempotent — second apply is byte-identical to first', async () => {
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        writeFileSync(claudePath, '# mine\n');
+        // First apply
+        await run();
+        const firstRead = readFileSync(claudePath, 'utf8');
+        // Reset modules + mocks for the second apply to simulate a fresh CLI invocation.
+        vi.restoreAllMocks();
+        augCwdSpy?.mockRestore();
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        // Second apply
+        await run();
+        const secondRead = readFileSync(claudePath, 'utf8');
+        expect(secondRead, 'second apply must be byte-identical to first').toBe(firstRead);
+    });
+    // ── (b) absent file → whole-file PB-owned (regression guard) ───────────────
+    it('(b) absent CLAUDE.md → whole-file PB-owned content, no REGION_START', async () => {
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        expect(existsSync(claudePath), 'CLAUDE.md must not exist before run').toBe(false);
+        await run();
+        expect(existsSync(claudePath), 'CLAUDE.md must be created').toBe(true);
+        const content = readFileSync(claudePath, 'utf8');
+        expect(content.includes('auto-generated by pb handshake'), 'must contain whole-file MARKER').toBe(true);
+        expect(content.includes(REGION_START), 'REGION_START must NOT be present in whole-file PB-owned write').toBe(false);
+    });
+    // ── user edit OUTSIDE region survives a re-run ─────────────────────────────
+    it('user edit OUTSIDE region survives a re-run', async () => {
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        writeFileSync(claudePath, '# mine\n');
+        // First apply
+        await run();
+        const afterFirst = readFileSync(claudePath, 'utf8');
+        // Insert a user line above the region (i.e. before REGION_START)
+        const regionStartIdx = afterFirst.indexOf(REGION_START);
+        const withUserEdit = afterFirst.slice(0, regionStartIdx) +
+            '## User added section\n\nDo not delete this.\n\n' +
+            afterFirst.slice(regionStartIdx);
+        writeFileSync(claudePath, withUserEdit);
+        // Reset modules + mocks for the second apply
+        vi.restoreAllMocks();
+        augCwdSpy?.mockRestore();
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        // Second apply
+        await run();
+        const afterSecond = readFileSync(claudePath, 'utf8');
+        expect(afterSecond.includes('User added section'), 'user edit outside region must survive').toBe(true);
+        expect(afterSecond.includes('Do not delete this.'), 'user content must survive').toBe(true);
+    });
+    // ── malformed region → file untouched + headless apply refuses ──────────────
+    it('malformed region → file untouched + headless apply throws /malformed/i', async () => {
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        // Start sentinel without matching end sentinel → malformed
+        const malformedContent = `# mine\n${REGION_START}\n(no end sentinel)\n`;
+        writeFileSync(claudePath, malformedContent);
+        await expect(run()).rejects.toThrow(/malformed/i);
+        // File must be completely untouched
+        const afterContent = readFileSync(claudePath, 'utf8');
+        expect(afterContent, 'malformed file must not be touched').toBe(malformedContent);
+    });
+    // ── opt-out sentinel → declines augmentation, left untouched ───────────────
+    // Governance regression guard (TEN-2155): a file carrying pb:no-augment (e.g. this repo's own
+    // committed CLAUDE.md/AGENTS.md constitution) must NEVER be spliced — pre-fix it classified
+    // 'augmentable' and got a region. Routes to the legacy user-owned skip instead.
+    it('pb:no-augment file → not augmented, left byte-identical, reported user-owned', async () => {
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        const optOutBody = `${REGION_OPT_OUT}\n# Acme constitution\n\nHand-maintained. Do not touch.\n`;
+        writeFileSync(claudePath, optOutBody);
+        const report = await run();
+        const after = readFileSync(claudePath, 'utf8');
+        expect(after, 'opt-out file must be byte-identical').toBe(optOutBody);
+        expect(after.includes(REGION_START), 'no PB region may be spliced into an opt-out file').toBe(false);
+        // Reported as user-owned (left untouched), never written.
+        expect(report?.filesWritten ?? [], 'filesWritten must not include CLAUDE.md').not.toContain('CLAUDE.md');
+        const claudeSkip = (report?.filesSkipped ?? []).find((s) => s.path === 'CLAUDE.md');
+        expect(claudeSkip?.reason, 'skip reason must mark it user-owned').toMatch(/user-owned/);
+    });
+    // ── opt-out file in preview mode → still left untouched, never planned to augment ──
+    it('pb:no-augment file in preview mode → byte-identical, no region planned', async () => {
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        const optOutBody = `${REGION_OPT_OUT}\n# Acme constitution\n`;
+        writeFileSync(claudePath, optOutBody);
+        // apply:false → preview = true (no writes at all).
+        await run({ apply: false });
+        const after = readFileSync(claudePath, 'utf8');
+        expect(after, 'opt-out file must be byte-identical in preview').toBe(optOutBody);
+        expect(after.includes(REGION_START), 'no PB region may be added to an opt-out file in preview').toBe(false);
+    });
+    // ── observe + malformed + headless apply → STILL refuses (refusal is applyMode-gated) ──
+    // Regression guard for the writeMode→applyMode fix (TEN-2155): a malformed region is a user-file
+    // integrity fault. Under materialize: observe the augment branch won't WRITE, but the headless
+    // refusal must still fire (STD-263 invariant vi — "headless → non-zero refusal", unqualified).
+    // Pre-fix the writeMode guard suppressed this throw under observe/off and exited 0.
+    it('observe mode + malformed region + headless apply → still refuses (authority does not suppress it)', async () => {
+        await setupAugmentMocks(OBSERVE_MANIFEST);
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        const malformedContent = `# mine\n${REGION_START}\n(no end sentinel)\n`;
+        writeFileSync(claudePath, malformedContent);
+        await expect(run()).rejects.toThrow(/malformed/i);
+        const afterContent = readFileSync(claudePath, 'utf8');
+        expect(afterContent, 'malformed file must remain untouched in observe mode too').toBe(malformedContent);
+    });
+    // ── materialize observe → NO write + reported preview-only ─────────────────
+    it('materialize observe → no write AND filesSkipped contains CLAUDE.md with preview-only reason', async () => {
+        await setupAugmentMocks(OBSERVE_MANIFEST);
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        const userContent = '# mine\n';
+        writeFileSync(claudePath, userContent);
+        const report = await run();
+        expect(report).toBeDefined();
+        // File must not have been modified
+        const after = readFileSync(claudePath, 'utf8');
+        expect(after, 'CLAUDE.md must be unchanged in observe mode').toBe(userContent);
+        // Report must NOT list CLAUDE.md as written
+        expect(report?.filesWritten ?? [], 'filesWritten must not include CLAUDE.md').not.toContain('CLAUDE.md');
+        // Report must list a CLAUDE.md skip with a preview-only reason
+        const claudeSkip = (report?.filesSkipped ?? []).find((s) => s.path === 'CLAUDE.md');
+        expect(claudeSkip, 'filesSkipped must have a CLAUDE.md entry').toBeDefined();
+        expect(claudeSkip?.reason, 'skip reason must match /preview-only/').toMatch(/preview-only/);
+    });
+    // ── symlinked CLAUDE.md → AGENTS.md → augmented exactly once ───────────────
+    it('symlinked CLAUDE.md→AGENTS.md → resolved file augmented exactly once', async () => {
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        const agentsPath = join(augE2eRoot, 'AGENTS.md');
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        writeFileSync(agentsPath, '# shared\n');
+        symlinkSync(agentsPath, claudePath);
+        const report = await run();
+        const body = readFileSync(agentsPath, 'utf8');
+        const regionCount = body.split(REGION_START).length - 1;
+        expect(regionCount, 'REGION_START must appear exactly once in the symlinked file').toBe(1);
+        expect(report.filesSkipped.some((s) => s.path === 'CLAUDE.md' && /symlinked to another augment target/.test(s.reason)), 'CLAUDE.md must be reported as skipped with symlink reason').toBe(true);
+    });
+    // ── non-augmentTarget .cursor/rules/*.mdc → legacy skip, never augmented ───
+    it('non-augmentTarget .cursor/rules/*.mdc → byte-identical, no REGION_START', async () => {
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        const cursorDir = join(augE2eRoot, '.cursor', 'rules');
+        mkdirSync(cursorDir, { recursive: true });
+        const mdcPath = join(cursorDir, 'mine.mdc');
+        const originalContent = '# my cursor rule\n\nSome user content here.\n';
+        writeFileSync(mdcPath, originalContent);
+        await run();
+        const after = readFileSync(mdcPath, 'utf8');
+        expect(after, '.cursor/rules/mine.mdc must be byte-identical').toBe(originalContent);
+        expect(after.includes(REGION_START), 'REGION_START must NOT appear in .mdc file').toBe(false);
+    });
+    // ── CLAUDE.md present but claude NOT in surfaces → filtered, no augment ─────
+    it('claude not in surfaces → CLAUDE.md unchanged, no REGION_START, no throw', async () => {
+        await setupAugmentMocks(CODEX_ONLY_MANIFEST);
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        const userContent = '# mine\n';
+        writeFileSync(claudePath, userContent);
+        // Must resolve (not throw) even though CLAUDE.md exists
+        await expect(run()).resolves.toBeDefined();
+        const after = readFileSync(claudePath, 'utf8');
+        expect(after, 'CLAUDE.md must be unchanged when claude not in surfaces').toBe(userContent);
+        expect(after.includes(REGION_START), 'REGION_START must not appear').toBe(false);
+    });
+    // ── symlinked CLAUDE.md→AGENTS.md with single-surface scope (Fix 1 regression) ──
+    it('symlinked CLAUDE.md→AGENTS.md with single-surface scope → selected surface still augmented', async () => {
+        // Fix 1 regression test (TEN-2155):
+        // CLAUDE.md is a symlink to AGENTS.md; run scoped to claude only (codex filtered out).
+        // Before the fix: the dedupe pre-pass iterated ALL writes including the filtered-out
+        // AGENTS.md (codex), which claimed the shared inode first — so CLAUDE.md was then
+        // skipped as a duplicate → neither file got augmented.
+        // After the fix: only surfaces that will actually be processed participate in dedupe,
+        // so CLAUDE.md (the first surface-included target) claims the inode and is augmented.
+        await setupAugmentMocks(CLAUDE_ONLY_MANIFEST);
+        const agentsPath = join(augE2eRoot, 'AGENTS.md');
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        // Write the shared backing file; symlink CLAUDE.md → AGENTS.md.
+        writeFileSync(agentsPath, '# shared rules\n');
+        symlinkSync(agentsPath, claudePath);
+        await run();
+        // The resolved file (AGENTS.md, which CLAUDE.md points to) must contain exactly one
+        // REGION_START — proving CLAUDE.md was augmented (not skipped as a false duplicate).
+        const body = readFileSync(agentsPath, 'utf8');
+        const regionCount = body.split(REGION_START).length - 1;
+        expect(regionCount, 'REGION_START must appear exactly once — CLAUDE.md was augmented').toBe(1);
+    });
+    // ── CRLF user file → region rendered CRLF; re-run byte-identical ───────────
+    it('CRLF user file → region rendered CRLF; re-run byte-identical; user CRLF preserved', async () => {
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        const claudePath = join(augE2eRoot, 'CLAUDE.md');
+        const userBody = '# mine\r\nuse pnpm\r\n';
+        writeFileSync(claudePath, userBody);
+        // First apply
+        await run();
+        const first = readFileSync(claudePath, 'utf8');
+        expect(first.startsWith(userBody), 'user CRLF bytes must be preserved').toBe(true);
+        expect(first.includes(REGION_START + '\r\n'), 'REGION_START must be followed by CRLF').toBe(true);
+        // Reset mocks + second apply
+        vi.restoreAllMocks();
+        augCwdSpy?.mockRestore();
+        await setupAugmentMocks(PROJECT_MANIFEST);
+        await run();
+        const second = readFileSync(claudePath, 'utf8');
+        expect(second, 'second apply must be byte-identical to first (CRLF idempotent)').toBe(first);
+    });
+});
+//# sourceMappingURL=handshake-augment.test.js.map