@productbrain/cli 0.1.0-beta.109 → 0.1.0-beta.10908

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

@@ -0,0 +1,191 @@
+/**
+ * WP-579 — rate-limit resilience: touch throttle + backoff/retry (TEN-2923, TEN-2924).
+ * DEC-2108 (TASK-883): one back-off per command, honouring Retry-After, never one per sub-call.
+ *
+ * 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, resetRateLimitBackoff, 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('kernelCall — one back-off per command on 429 (DEC-2108, TEN-5073)', () => {
+    let stderr;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.useFakeTimers();
+        resetRateLimitBackoff();
+        stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    });
+    afterEach(() => stderr.mockRestore());
+    it('waits the server-given seconds once, says so, then retries and succeeds', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return callCount === 1 ? rateLimitedResponse(7) : successResponse({ id: 'ENT-1' });
+        });
+        const resultPromise = kernelCall('chain.getEntry', {});
+        await vi.advanceTimersByTimeAsync(6_900);
+        expect(callCount).toBe(1); // still waiting: Retry-After is honoured, not guessed
+        await vi.advanceTimersByTimeAsync(400);
+        expect(await resultPromise).toEqual({ id: 'ENT-1' });
+        expect(callCount).toBe(2);
+        expect(stderr).toHaveBeenCalledWith('Rate limited: waiting 7s once, then retrying.\n');
+    });
+    it('a call still refused after the back-off fails with the kernel message, two attempts in all', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return rateLimitedResponse(1);
+        });
+        const resultPromise = kernelCall('chain.getEntry', {}).catch((err) => err);
+        await vi.advanceTimersByTimeAsync(20_000);
+        const err = await resultPromise;
+        expect(err.message).toBe('Rate limit exceeded for this API key. Retry after 1s.');
+        expect(callCount).toBe(2);
+    });
+    it('a later sub-call in the same command fails at once: no second back-off, no timer', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return callCount === 1 ? rateLimitedResponse(1) : callCount === 2 ? successResponse({}) : rateLimitedResponse(1);
+        });
+        const first = kernelCall('chain.listCollections', {});
+        await vi.advanceTimersByTimeAsync(1_500);
+        await first;
+        expect(callCount).toBe(2);
+        const err = await kernelCall('chain.createEntry', {}).catch((e) => e);
+        expect(err.message).toContain('Rate limit exceeded');
+        expect(callCount).toBe(3);
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    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('does not sit on a Retry-After over 60 s: surfaces it instead of sleeping', async () => {
+        let callCount = 0;
+        global.fetch = vi.fn(async () => {
+            callCount += 1;
+            return rateLimitedResponse(86_400);
+        });
+        const err = await kernelCall('chain.getEntry', {}).catch((e) => e);
+        expect(err.message).toContain('Rate limit exceeded');
+        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();
+        resetRateLimitBackoff();
+        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 () => {
+        // TASK-894: the session touch rides the write as a header, so every request here is the write.
+        let writeCalls = 0;
+        global.fetch = vi.fn(async () => {
+            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,125 @@
+/**
+ * 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` 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`/`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, 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('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

@@ -2,8 +2,16 @@
  * 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 { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { runRelate, runUnrelate } from '../commands/relate.js';
+import { CLIError } from '../lib/errors.js';
+import { setOutputMode } from '../lib/runner.js';
+// WP-744 / 1e-B: auto mode no longer infers JSON from a non-TTY stdout (the test runner's own
+// stdout), so any test asserting the raw JSON shape of the RelateResult must force JSON mode
+// explicitly rather than relying on that old ambient behavior.
+afterEach(() => {
+    setOutputMode('auto');
+});
 const kernelCallWithSessionMock = vi.fn();
 vi.mock('../lib/client.js', () => ({
     kernelCallWithSession: (...args) => kernelCallWithSessionMock(...args),
@@ -48,27 +56,42 @@ describe('runRelate', () => {
     });
     it('handles alreadyExists=true response gracefully and reflects it in output', async () => {
         kernelCallWithSessionMock.mockResolvedValue({ alreadyExists: true });
+        setOutputMode('json'); // this test asserts the raw JSON field name, not the pretty receipt
         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('');
         writeSpy.mockRestore();
-        // Output (JSON or pretty) should include the alreadyExists signal
         expect(output).toContain('alreadyExists');
     });
-    it('surfaces proposal_created when backend returns a proposal instead of a relation', async () => {
+    // 'surfaces proposal_created when backend returns a proposal instead of a relation' deleted
+    // (WP-776 S2a, DEC-1771): runRelate no longer branches on `result.status` at all — a real
+    // write is always 'related' now, since the relation-consent proposal system this test
+    // exercised is deleted.
+    // WP-753 O4 (TEN-3651): chain.createEntryRelation now RETURNS `{outcome:'refused',
+    // refusal}` on an organisational-authority refusal (never throws) — the exact shape
+    // update.ts's runUpdate already guards against. Before this fix, runRelate had no check
+    // for this shape at all and fell through to the plain success branch below, reporting
+    // action:'related' for a write the server refused.
+    it('a refused write throws, never reads as a successful "related" receipt', async () => {
         kernelCallWithSessionMock.mockResolvedValue({
-            status: 'proposal_created',
-            proposalId: 'prop-123',
-            fromEntryId: 'STD-2',
-            toEntryId: 'ARCH-27',
-            message: 'Governs relation requires async consent.',
+            outcome: 'refused',
+            refusal: {
+                category: 'auth',
+                code: 'role_not_owner',
+                reason: 'Refused: you do not hold the role this record’s authority resolves to.',
+                requiredAction: 'Ask the Team Lead of the team this record sits under.',
+            },
         });
-        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
-        await runRelate({ fromId: 'STD-2', type: 'governs', toId: 'ARCH-27' });
-        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
-        writeSpy.mockRestore();
-        expect(output).toContain('proposal_created');
-        expect(output).not.toContain('"action":"related"');
+        await expect(runRelate({ fromId: 'OBJ-1', type: 'related_to', toId: 'STR-1' }))
+            .rejects.toThrow('Refused: you do not hold the role');
+    });
+    it('surfaces a refused write as category "auth" (AUTH_DENIED), not a generic validation error', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            outcome: 'refused',
+            refusal: { category: 'auth', code: 'role_not_owner', reason: 'Refused.', requiredAction: 'Ask the Team Lead.' },
+        });
+        await expect(runRelate({ fromId: 'OBJ-1', type: 'related_to', toId: 'STR-1' }))
+            .rejects.toMatchObject({ category: 'auth' });
     });
     it('throws CLIError with no active session', async () => {
         mockSession = null;
@@ -79,6 +102,215 @@ describe('runRelate', () => {
         await expect(runRelate({ fromId: '', type: 'x', toId: 'B' })).rejects.toThrow('All arguments required');
         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');
+    });
+    // WP-745 (DEC-1681, TASK-159, round 4 M2): do NOT copy update.ts's invalid_option branch
+    // verbatim — the server's message already names task + the 12 verbs, and must survive intact,
+    // with the structured validOptions line appended (never substituted).
+    it('renders the door\'s refusal message first, then a validOptions line, when the door throws (REL-LEGAL-2 shape)', async () => {
+        const twelveVerbs = [
+            'constrains', 'informs', 'related_to', 'depends_on', 'addresses', 'implements',
+            'commits_to', 'realizes', 'validates', 'surfaces_tension_in', 'conflicts_with', 'fills_slot',
+        ];
+        const serverMessage = 'A work package is never part_of another work package — capture the smaller piece as a task and relate it part_of this work package. Legal relation types toward this work package: ' + twelveVerbs.join(', ');
+        const refusalError = Object.assign(new Error(serverMessage), {
+            name: 'McpError',
+            details: [{
+                    fieldKey: 'type', fieldLabel: 'Relation Type', invalidValue: 'part_of', errorType: 'invalid_option',
+                    message: serverMessage, validOptions: twelveVerbs,
+                }],
+        });
+        kernelCallWithSessionMock.mockRejectedValue(refusalError);
+        let caught;
+        try {
+            await runRelate({ fromId: 'WP-2', type: 'part_of', toId: 'WP-1' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        expect(caught).toBeInstanceOf(Error);
+        const message = caught.message;
+        const lines = message.split('\n');
+        expect(lines[0]).toBe(serverMessage);
+        expect(lines[0]).toContain('capture the smaller piece as a task');
+        expect(lines[1]).toBe(`Legal relation types toward this work package: ${twelveVerbs.join(', ')}`);
+        expect(lines[1]).not.toContain('part_of');
+    });
+    it('passes a plain (non-McpError) rejection straight through, unmodified', async () => {
+        const plainError = new Error('network exploded');
+        kernelCallWithSessionMock.mockRejectedValue(plainError);
+        await expect(runRelate({ fromId: 'A', type: 'informs', toId: 'B' })).rejects.toThrow('network exploded');
+    });
+    // PR #896 review (Copilot + Codex): the REL-LEGAL-2 catch must not swallow every McpError —
+    // an auth denial, a rate limit, or any OTHER validation failure carries its own code/category/
+    // guidance and must survive unchanged, never reclassified to VALIDATION_FAILED.
+    it('rethrows a non-REL-LEGAL-2 McpError (no validOptions detail) unchanged, preserving its own code', async () => {
+        // A real CLIError instance (not a plain Error) so runCliCommand's own `err instanceof
+        // CLIError` pass-through recognizes it — a plain-Error stand-in would get re-wrapped by
+        // that outer layer regardless of what relate.ts's own catch does, testing the wrong thing.
+        const authError = Object.assign(new CLIError('You do not have permission to write to this workspace.', {
+            code: 'AUTH_DENIED', category: 'auth', guidance: 'Ask a workspace admin for access.',
+        }), { name: 'McpError', details: undefined });
+        kernelCallWithSessionMock.mockRejectedValue(authError);
+        let caught;
+        try {
+            await runRelate({ fromId: 'WP-2', type: 'part_of', toId: 'WP-1' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        expect(caught).toBe(authError);
+        expect(caught.code).toBe('AUTH_DENIED');
+    });
+    it('rethrows an McpError whose details carry no invalid_option/validOptions unchanged', async () => {
+        const otherError = Object.assign(new CLIError('Rate limit exceeded.', { code: 'rate-limited', category: 'network' }), {
+            name: 'McpError',
+            details: [{ fieldKey: 'x', fieldLabel: 'X', invalidValue: 'y', errorType: 'required', message: 'x is required' }],
+        });
+        kernelCallWithSessionMock.mockRejectedValue(otherError);
+        let caught;
+        try {
+            await runRelate({ fromId: 'A', type: 'informs', toId: 'B' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        expect(caught).toBe(otherError);
+    });
+    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 });
+            setOutputMode('json'); // asserts the raw JSON action value below
+            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.',
+            });
+            setOutputMode('json'); // asserts the raw JSON wouldBlock field below
+            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' }],
+            });
+            setOutputMode('json'); // asserts the raw JSON action/chainDebtPrevented fields below
+            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 });
+            setOutputMode('json'); // asserts the raw JSON alreadyExists field below
+            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(() => {