@productbrain/cli 0.1.0-beta.55 → 0.1.0-beta.5504

package/dist/__tests__/rate-limit-resilience.test.js

@@ -0,0 +1,209 @@
+/**
+ * WP-579 — rate-limit resilience: touch throttle + backoff/retry (TEN-2923, TEN-2924).
+ *
+ * Mirrors the mock/module-mock conventions of envelope-contract.test.ts.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+// ─── Module mocks (must precede imports that trigger side effects) ────────────
+vi.mock('../lib/config.js', () => ({
+    getConfig: vi.fn(() => ({
+        apiKey: 'pb_sk_test',
+        siteUrl: 'https://example.convex.site',
+    })),
+}));
+vi.mock('../lib/adminConfig.js', () => ({
+    resolveAdminConfig: vi.fn(),
+}));
+let mockSession = { sessionId: 'session-1' };
+vi.mock('../lib/session.js', () => ({
+    readSession: vi.fn(() => mockSession),
+    writeSession: vi.fn(),
+    clearSession: vi.fn(),
+    addCapturedEntry: vi.fn(),
+}));
+vi.mock('../lib/spinner.js', () => ({
+    withSpinner: vi.fn((_label, fn) => fn()),
+}));
+vi.mock('../lib/update-check.js', () => ({
+    recordServerLatest: vi.fn(),
+}));
+// ─── Imports (after mocks) ────────────────────────────────────────────────────
+import { kernelCall, kernelCallWithSession, resetTouchThrottle } from '../lib/client.js';
+function successResponse(data = {}) {
+    return {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        json: async () => ({ ok: true, data }),
+        headers: { get: () => null },
+    };
+}
+function rateLimitedResponse(retryAfterSeconds) {
+    return {
+        ok: false,
+        status: 429,
+        statusText: 'Too Many Requests',
+        json: async () => ({
+            ok: false,
+            code: 'rate-limited',
+            message: `Rate limit exceeded for this API key. Retry after ${retryAfterSeconds}s.`,
+            retryAfterSeconds,
+        }),
+        headers: { get: (name) => (name === 'Retry-After' ? String(retryAfterSeconds) : null) },
+    };
+}
+function validationFailedResponse() {
+    return {
+        ok: false,
+        status: 400,
+        statusText: 'Bad Request',
+        json: async () => ({ ok: false, code: 'VALIDATION_FAILED', message: 'Bad input' }),
+        headers: { get: () => null },
+    };
+}
+// Two describes below switch on fake timers. Restore real ones after every test so timer
+// state can't leak into a later test in this file (the throttle describe runs first today,
+// but that ordering is not a contract).
+afterEach(() => {
+    vi.useRealTimers();
+});
+describe('kernelCallWithSession — touch throttle (TEN-2923)', () => {
+    let fetchCalls = [];
+    beforeEach(() => {
+        vi.clearAllMocks();
+        resetTouchThrottle();
+        mockSession = { sessionId: 'session-1' };
+        fetchCalls = [];
+        global.fetch = vi.fn(async (_url, init) => {
+            const body = JSON.parse(String(init?.body ?? '{}'));
+            fetchCalls.push(body.fn ?? '');
+            if (body.fn === 'agent.touchSession')
+                return successResponse();
+            return successResponse({ ok: true });
+        });
+    });
+    it('does not send a touchSession call within 5s of the previous one for the same session', async () => {
+        await kernelCallWithSession('chain.createEntry', {});
+        await kernelCallWithSession('chain.createEntry', {});
+        const touchCalls = fetchCalls.filter((fn) => fn === 'agent.touchSession');
+        expect(touchCalls).toHaveLength(1);
+    });
+    it('isolates the throttle window per session id', async () => {
+        mockSession = { sessionId: 'session-a' };
+        await kernelCallWithSession('chain.createEntry', {});
+        mockSession = { sessionId: 'session-b' };
+        await kernelCallWithSession('chain.createEntry', {});
+        const touchCalls = fetchCalls.filter((fn) => fn === 'agent.touchSession');
+        expect(touchCalls).toHaveLength(2);
+    });
+});
+describe('kernelCall — bounded retry on 429 rate-limited (TEN-2924)', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.useFakeTimers();
+    });
+    it('retries a rate-limited call once the server-given wait elapses, and succeeds', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return callCount === 1 ? rateLimitedResponse(1) : successResponse({ id: 'ENT-1' });
+        });
+        const resultPromise = kernelCall('chain.getEntry', {});
+        await vi.advanceTimersByTimeAsync(2000);
+        const result = await resultPromise;
+        expect(result).toEqual({ id: 'ENT-1' });
+        expect(callCount).toBe(2);
+    });
+    it('never retries a non-rate-limited failure (e.g. VALIDATION_FAILED)', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return validationFailedResponse();
+        });
+        await expect(kernelCall('chain.createEntry', {})).rejects.toThrow('Bad input');
+        expect(callCount).toBe(1);
+    });
+    it('gives up after the bounded retry cap and surfaces the rate-limited error', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return rateLimitedResponse(1);
+        });
+        const resultPromise = kernelCall('chain.getEntry', {}).catch((err) => err);
+        // Advance past every possible retry wait.
+        await vi.advanceTimersByTimeAsync(20_000);
+        const err = await resultPromise;
+        expect(err).toBeInstanceOf(Error);
+        expect(err.message).toContain('Rate limit exceeded');
+        // Bounded: the initial attempt plus at most 3 retries, never unbounded.
+        expect(callCount).toBeLessThanOrEqual(4);
+        expect(callCount).toBeGreaterThan(1);
+    });
+    it('does not sit on a day-window Retry-After — surfaces it instead of sleeping for hours', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            // The server clamps a day-window denial to the full window (86_400s).
+            return rateLimitedResponse(86_400);
+        });
+        const err = await kernelCall('chain.getEntry', {}).catch((e) => e);
+        expect(err).toBeInstanceOf(Error);
+        expect(err.message).toContain('Rate limit exceeded');
+        // Failed fast on the first attempt — no timer was ever armed.
+        expect(callCount).toBe(1);
+        expect(vi.getTimerCount()).toBe(0);
+    });
+});
+describe('kernelCallWithSession — background calls opt out of retry (TEN-2924)', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.useFakeTimers();
+        resetTouchThrottle();
+        mockSession = { sessionId: 'session-1' };
+    });
+    it('never arms a retry timer when retryOnRateLimit is false', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return rateLimitedResponse(1);
+        });
+        const err = await kernelCallWithSession('chain.recordGroundingOutcome', {}, { retryOnRateLimit: false }).catch((e) => e);
+        expect(err).toBeInstanceOf(Error);
+        // One attempt, and crucially no pending timer left holding the event loop open.
+        expect(callCount).toBe(1);
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    // Codex round 2 found capture.ts was not the only detached call site. Sweep of every
+    // kernelCall* whose promise is neither awaited nor returned: capture.ts (grounding),
+    // brief.ts (recordBriefRun), handshake.ts x2 (drift + collision TENs). All four now opt
+    // out. This pins the class rather than the instances — a detached call that keeps the
+    // retry arms timers that outlive the command's foreground work.
+    it('arms no timer for kernelCall either — the detached brief.ts/handshake.ts shape', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return rateLimitedResponse(1);
+        });
+        const err = await kernelCall('chain.recordBriefRun', {}, { retryOnRateLimit: false }).catch((e) => e);
+        expect(err).toBeInstanceOf(Error);
+        expect(callCount).toBe(1);
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it('still retries by default when no options are passed', async () => {
+        // Count only the gateway call — kernelCallWithSession also fires an unawaited
+        // agent.touchSession afterwards, which would race a bare counter.
+        let writeCalls = 0;
+        global.fetch = vi.fn(async (_url, init) => {
+            const body = JSON.parse(String(init?.body ?? '{}'));
+            if (body.fn === 'agent.touchSession')
+                return successResponse();
+            writeCalls += 1;
+            return writeCalls === 1 ? rateLimitedResponse(1) : successResponse({ id: 'ENT-2' });
+        });
+        const resultPromise = kernelCallWithSession('chain.createEntry', {});
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(await resultPromise).toEqual({ id: 'ENT-2' });
+        expect(writeCalls).toBe(2);
+    });
+});
+//# sourceMappingURL=rate-limit-resilience.test.js.map

package/dist/__tests__/rate-limit-resilience.test.js.map

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

package/dist/__tests__/read-target-notice.test.d.ts

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

package/dist/__tests__/read-target-notice.test.d.ts.map

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

package/dist/__tests__/read-target-notice.test.js

@@ -0,0 +1,129 @@
+/**
+ * WP-714 S3 — read commands announce their effective tenant too.
+ * TEN-3398 (WP-711 follow-up) — the write path (`kernelCallWithSession`) announces too, closing
+ * the gap this file used to assert as intentional (see the last two tests below).
+ *
+ * Before WP-714 S3, `emitEffectiveTenantNotice` was called only from the 8 explicit write call
+ * sites (relate x2, restore, organisationWrite, promote, capture, session, update) — every
+ * plain read (`pb get`/`search`/`orient`/`context`/`brief`/`constellation`/...) went through
+ * `client.ts`'s `kernelCall`/`kernelCallEnvelope` silently. Before TEN-3398, `kernelCallWithSession`
+ * itself never called the notice at all — a write command that was not one of those 8 explicit
+ * call sites (e.g. `chain.verifyEntry`/`rework.report`) was silent. This file exercises the REAL
+ * `kernelCall`/`kernelCallEnvelope`/`kernelCallWithSession` implementations from client.ts —
+ * only their dependencies (config, session, sessionBinding, reportedProfile, fetch) are
+ * mocked — so removing the notice call from either path, or the once-per-process guard, turns
+ * one of these red. Mirrors the mocking shape of `client-binding-guard.test.ts` (WP-711/712),
+ * which proved the binding guard the same way.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const assertSessionStillBoundMock = vi.fn();
+const readSessionMock = vi.fn();
+const readSessionBySessionIdMock = vi.fn();
+const getConfigMock = vi.fn();
+const resolveEffectiveProfileMock = vi.fn();
+vi.mock('../lib/config.js', () => ({
+    getConfig: (...args) => getConfigMock(...args),
+    resolveEffectiveProfile: (...args) => resolveEffectiveProfileMock(...args),
+}));
+vi.mock('../lib/session.js', () => ({
+    readSession: (...args) => readSessionMock(...args),
+    readSessionBySessionId: (...args) => readSessionBySessionIdMock(...args),
+}));
+vi.mock('../lib/sessionBinding.js', () => ({
+    assertSessionStillBound: (...args) => assertSessionStillBoundMock(...args),
+}));
+const effectiveState = { value: { profile: 'funcode', source: 'local' } };
+vi.mock('../lib/reportedProfile.js', () => ({
+    resolveReportedProfile: () => effectiveState.value,
+}));
+// `readLocalProjectConfig` is only reached via `resolveShadowedPin` (env-key/cwd-key/local-key
+// sources, none of which this file exercises) — kept inert so these tests isolate the read-path
+// wiring.
+vi.mock('../lib/projectConfig.js', () => ({ readLocalProjectConfig: () => null }));
+import { kernelCall, kernelCallEnvelope, kernelCallWithSession } from '../lib/client.js';
+import { resetEffectiveTenantNoticeForTests } from '../lib/workspaceNotice.js';
+import { setOutputMode } from '../lib/runner.js';
+describe('read path announces the effective tenant (WP-714 S3)', () => {
+    let fetchSpy;
+    let stderr;
+    let stderrSpy;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        resetEffectiveTenantNoticeForTests();
+        assertSessionStillBoundMock.mockImplementation(() => { });
+        getConfigMock.mockReturnValue({ apiKey: 'pb_sk_test', siteUrl: 'https://test.convex.site' });
+        readSessionMock.mockReturnValue(null);
+        effectiveState.value = { profile: 'funcode', source: 'local' };
+        setOutputMode('pretty'); // deterministic: not gated by TTY auto-detection in a test runner.
+        fetchSpy = vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            headers: { get: () => null },
+            json: async () => ({ ok: true, data: { hello: 'world' } }),
+        });
+        vi.stubGlobal('fetch', fetchSpy);
+        stderr = [];
+        stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation((c) => { stderr.push(String(c)); return true; });
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        stderrSpy.mockRestore();
+        setOutputMode('auto');
+    });
+    it('doneWhen 1/6: kernelCall (the plain read path) announces the effective tenant — delete the call and this goes red', async () => {
+        await kernelCall('chain.getEntry', { entryId: 'X-1' });
+        expect(stderr.join('')).toBe('→ funcode\n');
+    });
+    it('kernelCallEnvelope (the other read wrapper, e.g. `pb shape`) announces too', async () => {
+        await kernelCallEnvelope('chain.someRoute', {});
+        expect(stderr.join('')).toBe('→ funcode\n');
+    });
+    it('doneWhen 4: a command making several kernel calls (like `pb orient`) emits exactly one notice', async () => {
+        await kernelCall('chain.getVocabulary', {});
+        await kernelCall('chain.getOrientView', { tier: 'standard' });
+        await kernelCall('agent.markOriented', { sessionId: 'sess-1' });
+        expect(fetchSpy).toHaveBeenCalledTimes(3); // three real kernel calls happened...
+        const lines = stderr.join('').split('\n').filter((l) => l.startsWith('→'));
+        expect(lines).toHaveLength(1); // ...but the notice printed exactly once.
+    });
+    // WP-721 (reverses WP-714 S3's doneWhen 5, which asserted the OPPOSITE): a `--json` read on an
+    // explicit (local) binding announces its tenant on stderr, identically to the pretty read.
+    // The suppressed form shipped live on `@productbrain/cli@0.1.0-beta.5421` as a ZERO-BYTE
+    // stderr for `pb get WP-711 --json` in a correctly pinned repo — no tenant signal at all for
+    // the CLI's primary consumer. This is the read-path half of the regression pin in
+    // workspaceNotice.test.ts; delete the fix and this goes red at `jsonStderr`.
+    it('WP-721: a --json read on an explicit (local) binding announces its tenant — same stderr as pretty', async () => {
+        setOutputMode('pretty');
+        await kernelCall('chain.getEntry', { entryId: 'X-1' });
+        const prettyStderr = stderr.join('');
+        resetEffectiveTenantNoticeForTests();
+        stderr.length = 0;
+        setOutputMode('json');
+        await kernelCall('chain.getEntry', { entryId: 'X-1' });
+        const jsonStderr = stderr.join('');
+        expect(prettyStderr).toBe('→ funcode\n');
+        expect(jsonStderr).toBe('→ funcode\n');
+        // The identity line is mode-independent now: the ONLY thing `--json` ever governed here was
+        // whether an agent could see which Chain its read hit.
+        expect(jsonStderr).toBe(prettyStderr);
+    });
+    // TEN-3398 (WP-711 follow-up): this used to assert the OPPOSITE — that kernelCallWithSession
+    // never announces, because "every write command already calls this explicitly" (a premise
+    // that was false: verify.ts, rework.ts, and 9 other write commands never called it at all —
+    // see the corrected doc comment on workspaceNotice.ts's emitEffectiveTenantNotice). The write
+    // path now shares the SAME notice call site as the read path.
+    it('DOES auto-announce from kernelCallWithSession too — the write path shares the read path\'s notice call site (TEN-3398)', async () => {
+        resolveEffectiveProfileMock.mockReturnValue({ profile: 'funcode', source: 'local' });
+        await kernelCallWithSession('chain.createEntry', { description: 'x' });
+        expect(stderr.join('')).toBe('→ funcode\n');
+    });
+    it('the 8 pre-existing explicit write call sites still print exactly once — kernelCallWithSession\'s own (later) attempt is a no-op under the once-per-process guard', async () => {
+        // Mirrors what capture.ts/relate.ts/etc. do: call the notice explicitly BEFORE the write.
+        const { emitEffectiveTenantNotice } = await import('../lib/workspaceNotice.js');
+        await emitEffectiveTenantNotice(); // the command's own explicit, earlier call
+        await kernelCallWithSession('chain.createEntry', { description: 'x' }); // its internal call
+        const lines = stderr.join('').split('\n').filter((l) => l.startsWith('→'));
+        expect(lines).toHaveLength(1);
+    });
+});
+//# sourceMappingURL=read-target-notice.test.js.map

package/dist/__tests__/read-target-notice.test.js.map

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

package/dist/__tests__/relate.test.js

@@ -1,12 +1,12 @@
 /**
- * pb relate / pb unrelate — verify mcpCallWithSession sequence and args.
+ * pb relate / pb unrelate — verify kernelCallWithSession sequence and args.
  * TEN-341 test contract: happy paths, no session.
  */
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { runRelate, runUnrelate } from '../commands/relate.js';
-const mcpCallWithSessionMock = vi.fn();
+const kernelCallWithSessionMock = vi.fn();
 vi.mock('../lib/client.js', () => ({
-    mcpCallWithSession: (...args) => mcpCallWithSessionMock(...args),
+    kernelCallWithSession: (...args) => kernelCallWithSessionMock(...args),
 }));
 vi.mock('../lib/config.js', () => ({
     getConfigOrGuide: vi.fn(() => Promise.resolve({ apiKey: 'pb_sk_test', siteUrl: 'https://test.convex.site' })),
@@ -19,11 +19,11 @@ describe('runRelate', () => {
     beforeEach(() => {
         vi.clearAllMocks();
         mockSession = { sessionId: 'sess-test' };
-        mcpCallWithSessionMock.mockResolvedValue({});
+        kernelCallWithSessionMock.mockResolvedValue({});
     });
     it('calls chain.createEntryRelation with correct args', async () => {
         await runRelate({ fromId: 'BET-151', type: 'informed_by', toId: 'DEC-264' });
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
             fromEntryId: 'BET-151',
             toEntryId: 'DEC-264',
             type: 'informed_by',
@@ -31,7 +31,7 @@ describe('runRelate', () => {
     });
     it('passes ifMissing=true when --if-missing flag is set', async () => {
         await runRelate({ fromId: 'BET-151', type: 'part_of', toId: 'FEAT-77', ifMissing: true });
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
             fromEntryId: 'BET-151',
             toEntryId: 'FEAT-77',
             type: 'part_of',
@@ -40,14 +40,14 @@ describe('runRelate', () => {
     });
     it('does not pass ifMissing when flag is not set', async () => {
         await runRelate({ fromId: 'BET-151', type: 'part_of', toId: 'FEAT-77' });
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
             fromEntryId: 'BET-151',
             toEntryId: 'FEAT-77',
             type: 'part_of',
         });
     });
     it('handles alreadyExists=true response gracefully and reflects it in output', async () => {
-        mcpCallWithSessionMock.mockResolvedValue({ alreadyExists: true });
+        kernelCallWithSessionMock.mockResolvedValue({ alreadyExists: true });
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         await runRelate({ fromId: 'BET-151', type: 'part_of', toId: 'FEAT-77', ifMissing: true });
         const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
@@ -56,7 +56,7 @@ describe('runRelate', () => {
         expect(output).toContain('alreadyExists');
     });
     it('surfaces proposal_created when backend returns a proposal instead of a relation', async () => {
-        mcpCallWithSessionMock.mockResolvedValue({
+        kernelCallWithSessionMock.mockResolvedValue({
             status: 'proposal_created',
             proposalId: 'prop-123',
             fromEntryId: 'STD-2',
@@ -73,22 +73,154 @@ describe('runRelate', () => {
     it('throws CLIError with no active session', async () => {
         mockSession = null;
         await expect(runRelate({ fromId: 'A', type: 'x', toId: 'B' })).rejects.toThrow('No active session');
-        expect(mcpCallWithSessionMock).not.toHaveBeenCalled();
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
     });
     it('throws CLIError with empty args', async () => {
         await expect(runRelate({ fromId: '', type: 'x', toId: 'B' })).rejects.toThrow('All arguments required');
-        expect(mcpCallWithSessionMock).not.toHaveBeenCalled();
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
+    // WP-625 (S3 of WP-618, DEC-1546, TEN-3037): the relate door's advisory legality + altitude
+    // findings must survive the CLI's closed cast + field list + printer — the whole point of
+    // this slice's CLI deliverable.
+    it('surfaces the relate door\'s advisories in the pretty-printed receipt', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            advisories: [{
+                    ruleId: 'REL-LEGAL-1',
+                    ruleText: 'REL-LEGAL-1: relation type "depends_on" is not declared valid for "vision" (declared: informs, governs, belongs_to).',
+                    severity: 'advisory',
+                    stage: 'discovering',
+                }],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runRelate({ fromId: 'STR-1', type: 'depends_on', toId: 'STR-2' });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(output).toContain('REL-LEGAL-1');
+        expect(output).toContain('not declared valid for');
+        expect(output).toContain('vision');
+    });
+    it('omits advisories from the output when the backend returns none', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({});
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runRelate({ fromId: 'BET-151', type: 'informed_by', toId: 'DEC-264' });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(output).not.toContain('advisories');
+    });
+    // WP-688 S2a: --dry-run threads preview:true to the door and writes NOTHING — the measurement
+    // door element 6a/doneWhen 7 depend on. --if-missing's alreadyExists early return needs the
+    // pair to already exist, so it is NOT a dry run; --dry-run is the genuinely non-mutating door.
+    // Nested inside describe('runRelate') so it shares the SAME beforeEach mock reset.
+    describe('--dry-run (WP-688 S2a)', () => {
+        it('passes preview=true, never alreadyExists/ifMissing semantics, to chain.createEntryRelation', async () => {
+            await runRelate({ fromId: 'TEN-1', type: 'surfaces_tension_in', toId: 'FEAT-1', dryRun: true });
+            expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
+                fromEntryId: 'TEN-1',
+                toEntryId: 'FEAT-1',
+                type: 'surfaces_tension_in',
+                preview: true,
+            }, { skipSessionTouch: true });
+        });
+        it('opts out of the session-touch heartbeat entirely (thread bb1oj) — dry-run must not write, even a telemetry write', async () => {
+            await runRelate({ fromId: 'TEN-1', type: 'surfaces_tension_in', toId: 'FEAT-1', dryRun: true });
+            const call = kernelCallWithSessionMock.mock.calls[0];
+            expect(call?.[2]).toEqual({ skipSessionTouch: true });
+        });
+        it('does not pass preview when --dry-run is not set', async () => {
+            await runRelate({ fromId: 'TEN-1', type: 'surfaces_tension_in', toId: 'FEAT-1' });
+            const call = kernelCallWithSessionMock.mock.calls[0]?.[1];
+            expect(call).not.toHaveProperty('preview');
+        });
+        it('reports action "dry_run", never "related" — the door never wrote', async () => {
+            kernelCallWithSessionMock.mockResolvedValue({ preview: true, advisories: undefined });
+            const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+            await runRelate({ fromId: 'TEN-1', type: 'surfaces_tension_in', toId: 'FEAT-1', dryRun: true });
+            const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+            writeSpy.mockRestore();
+            expect(output).toContain('dry_run');
+            expect(output).not.toContain('"action":"related"');
+        });
+        it('surfaces wouldBlock/blockingReason from the preview door', async () => {
+            kernelCallWithSessionMock.mockResolvedValue({
+                preview: true,
+                wouldBlock: true,
+                blockingReason: 'anchored_to would collapse scope onto the wrong product.',
+            });
+            const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+            await runRelate({ fromId: 'STR-1', type: 'anchored_to', toId: 'PROD-2', dryRun: true });
+            const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+            writeSpy.mockRestore();
+            expect(output).toContain('wouldBlock');
+            expect(output).toContain('anchored_to would collapse scope');
+        });
+        it('surfaces advisories from the preview door, same shape as a real write', async () => {
+            kernelCallWithSessionMock.mockResolvedValue({
+                preview: true,
+                advisories: [{
+                        ruleId: 'REL-LEGAL-1',
+                        ruleText: 'REL-LEGAL-1: relation type "conflicts_with" is not declared valid for "business_rule".',
+                        severity: 'advisory',
+                        stage: 'discovering',
+                    }],
+            });
+            const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+            await runRelate({ fromId: 'BR-1', type: 'conflicts_with', toId: 'DEC-1', dryRun: true });
+            const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+            writeSpy.mockRestore();
+            expect(output).toContain('REL-LEGAL-1');
+            expect(output).toContain('conflicts_with');
+        });
+        // WP-688 S2a review fix (thread bbzfq): the server now evaluates the chain-debt misuse gate
+        // regardless of preview, returning `preview: true, chainDebtPrevented: true` instead of
+        // creating a proposal. The dry-run receipt must reflect the predicted diversion, never a
+        // plain clean 'dry_run' result, and must NEVER claim `action: 'proposal_created'` (nothing
+        // was actually created).
+        it('reports chainDebtPrevented as a PREDICTED outcome in dry-run, never a real proposal_created', async () => {
+            kernelCallWithSessionMock.mockResolvedValue({
+                preview: true,
+                chainDebtPrevented: true,
+                originalType: 'depends_on',
+                suggestedAlternatives: [{ type: 'informs', reason: 'weaker coupling' }],
+            });
+            const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+            await runRelate({ fromId: 'STR-1', type: 'depends_on', toId: 'STR-2', dryRun: true });
+            const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+            writeSpy.mockRestore();
+            expect(output).toContain('"action":"dry_run"');
+            expect(output).toContain('chainDebtPrevented');
+            expect(output).not.toContain('proposal_created');
+            expect(output).not.toContain('"proposalId"');
+        });
+        // WP-688 S2a review fix (thread bb38B): --if-missing's alreadyExists early return
+        // (relations.ts:86-92) is itself non-mutating regardless of preview, so its outcome must
+        // survive into the dry-run receipt rather than being reported as an ordinary clean write.
+        it('preserves the --if-missing alreadyExists outcome in a dry-run receipt', async () => {
+            kernelCallWithSessionMock.mockResolvedValue({ relationId: 'rel-1', alreadyExists: true });
+            const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+            await runRelate({ fromId: 'BET-151', type: 'part_of', toId: 'FEAT-77', ifMissing: true, dryRun: true });
+            const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+            writeSpy.mockRestore();
+            expect(output).toContain('"alreadyExists":true');
+        });
+        it('does not surface alreadyExists in a dry-run receipt when --if-missing was not passed', async () => {
+            kernelCallWithSessionMock.mockResolvedValue({});
+            const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+            await runRelate({ fromId: 'BET-151', type: 'part_of', toId: 'FEAT-77', dryRun: true });
+            const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+            writeSpy.mockRestore();
+            expect(output).not.toContain('alreadyExists');
+        });
     });
 });
 describe('runUnrelate', () => {
     beforeEach(() => {
         vi.clearAllMocks();
         mockSession = { sessionId: 'sess-test' };
-        mcpCallWithSessionMock.mockResolvedValue({});
+        kernelCallWithSessionMock.mockResolvedValue({});
     });
     it('calls chain.removeEntryRelation with correct args', async () => {
         await runUnrelate({ fromId: 'BET-151', type: 'part_of', toId: 'FEAT-77' });
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.removeEntryRelation', {
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.removeEntryRelation', {
             fromEntryId: 'BET-151',
             toEntryId: 'FEAT-77',
             type: 'part_of',
@@ -97,7 +229,7 @@ describe('runUnrelate', () => {
     it('throws CLIError with no active session', async () => {
         mockSession = null;
         await expect(runUnrelate({ fromId: 'A', type: 'x', toId: 'B' })).rejects.toThrow('No active session');
-        expect(mcpCallWithSessionMock).not.toHaveBeenCalled();
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
     });
 });
 //# sourceMappingURL=relate.test.js.map