@productbrain/cli 0.1.0-beta.49 → 0.1.0-beta.4902

package/dist/__tests__/update-check.test.js

@@ -0,0 +1,215 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const files = new Map();
+// Controllable npm registry response for resolveLatestVersion's live fetch. `null` => the
+// request yields an empty body (JSON.parse fails) so fetchLatestVersion resolves null.
+let npmResponseVersion = null;
+vi.mock('node:os', () => ({
+    homedir: () => '/mock-home',
+}));
+vi.mock('node:https', () => ({
+    request: (_url, _opts, cb) => {
+        const res = {
+            on: (event, handler) => {
+                if (event === 'data' && npmResponseVersion !== null) {
+                    handler(Buffer.from(JSON.stringify({ version: npmResponseVersion })));
+                }
+                if (event === 'end')
+                    handler();
+                return res;
+            },
+        };
+        cb(res);
+        const req = { on: () => req, setTimeout: () => req, destroy: () => { }, end: () => { } };
+        return req;
+    },
+}));
+vi.mock('node:fs', async () => ({
+    existsSync: (path) => files.has(path),
+    readFileSync: (path) => files.get(path) ?? '',
+    writeFileSync: (path, body) => { files.set(path, body); },
+    mkdirSync: vi.fn(),
+    unlinkSync: (path) => { files.delete(path); },
+    statSync: () => ({ mtimeMs: Date.now() }),
+    readdirSync: () => [...files.keys()].map((p) => p.split('/').pop()),
+    openSync: (path) => { if (files.has(path)) {
+        const e = new Error('EEXIST');
+        e.code = 'EEXIST';
+        throw e;
+    } files.set(path, ''); return 1; },
+    closeSync: vi.fn(),
+}));
+vi.mock('../lib/session.js', () => ({ readSession: () => ({ sessionId: 'sess-test' }) }));
+import { clearPendingUpgradeCache, isNewer, recordServerLatest, readCachedLatestVersion, writeUpgradePendingSentinel, recordNpmLatest, resolveCachedLatest, resolveLatestVersion, checkForUpdate, _resetProcessGuardsForTest, } from '../lib/update-check.js';
+import { setOutputMode } from '../lib/runner.js';
+describe('update-check', () => {
+    const originalEnv = { ...process.env };
+    beforeEach(() => {
+        _resetProcessGuardsForTest();
+        files.clear();
+        npmResponseVersion = null;
+        process.env = { ...originalEnv };
+        setOutputMode('auto');
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        process.env = { ...originalEnv };
+        setOutputMode('auto');
+        vi.restoreAllMocks();
+    });
+    it('compares prerelease channels by alpha < beta < rc < release', () => {
+        expect(isNewer('0.1.0-beta.32', '0.1.0-beta.108')).toBe(true);
+        expect(isNewer('0.1.0-beta.5', '0.1.0-rc.1')).toBe(true);
+        expect(isNewer('0.1.0-rc.1', '0.1.0-beta.5')).toBe(false);
+        expect(isNewer('0.1.0-rc.1', '0.1.0')).toBe(true);
+    });
+    it('recordServerLatest updates cache silently in JSON mode', () => {
+        setOutputMode('json');
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        recordServerLatest('0.1.0-beta.109');
+        expect(readCachedLatestVersion()).toBe('0.1.0-beta.109');
+        expect(stderrSpy).not.toHaveBeenCalled();
+    });
+    it('PB_NO_VERSION_CHECK disables cache writes and output', () => {
+        process.env.PB_NO_VERSION_CHECK = '1';
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        recordServerLatest('0.1.0-beta.109');
+        expect(readCachedLatestVersion()).toBeNull();
+        expect(stderrSpy).not.toHaveBeenCalled();
+    });
+    it('next startup clears upgrade sentinel and stale update cache', () => {
+        recordServerLatest('0.1.0-beta.109');
+        expect(readCachedLatestVersion()).toBe('0.1.0-beta.109');
+        writeUpgradePendingSentinel();
+        clearPendingUpgradeCache();
+        expect(readCachedLatestVersion()).toBeNull();
+    });
+    it('newest of fresh server/npm wins; server still wins only when it is the highest', () => {
+        recordNpmLatest('0.1.0-beta.140', '0.1.0-beta.109'); // (value, installed)
+        recordServerLatest('0.1.0-beta.130'); // fresh server, but LOWER than npm
+        expect(resolveCachedLatest()).toBe('0.1.0-beta.140'); // npm wins — server no longer masks a newer npm
+    });
+    it('a fresh server that LAGS npm cannot mask the true npm latest (TEN-2199 smoke-walk regression)', () => {
+        // The live failure mode: server header advertises the committed cliVersion.ts value (beta.108),
+        // which trails the run-numbered npm publish (beta.958). Newest-wins must surface 958, not 108.
+        recordNpmLatest('0.1.0-beta.958', '0.1.0-beta.109');
+        recordServerLatest('0.1.0-beta.108'); // fresh but stale-valued, < installed
+        expect(resolveCachedLatest()).toBe('0.1.0-beta.958');
+    });
+    it('server still wins when it is genuinely the newest source', () => {
+        recordNpmLatest('0.1.0-beta.140', '0.1.0-beta.109');
+        recordServerLatest('0.1.0-beta.145'); // fresh server, HIGHER than npm
+        expect(resolveCachedLatest()).toBe('0.1.0-beta.145');
+    });
+    it('npm wins when the server header is stale (>48h)', () => {
+        const realNow = Date.now;
+        recordServerLatest('0.1.0-beta.130');
+        Date.now = () => realNow() + 49 * 60 * 60 * 1000;
+        recordNpmLatest('0.1.0-beta.140', '0.1.0-beta.109');
+        expect(resolveCachedLatest()).toBe('0.1.0-beta.140');
+        Date.now = realNow;
+    });
+    it('npm fallback is isNewer-gated against installed (never records older-or-equal)', () => {
+        recordNpmLatest('0.1.0-beta.1', '0.1.0-beta.109'); // stale tag, older than installed
+        expect(resolveCachedLatest()).toBeNull();
+    });
+    it('prints an update line to stderr in JSON mode (agent), once', () => {
+        setOutputMode('json');
+        recordServerLatest('0.1.0-beta.140');
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        checkForUpdate('0.1.0-beta.109');
+        checkForUpdate('0.1.0-beta.109'); // same session => silent second time
+        expect(stderrSpy).toHaveBeenCalledTimes(1);
+        expect(stderrSpy.mock.calls[0][0]).toContain('pb:');
+        expect(stderrSpy.mock.calls[0][0]).toContain('pb upgrade');
+    });
+    it('prints nothing to stdout (stdout stays bare JSON)', () => {
+        setOutputMode('json');
+        recordServerLatest('0.1.0-beta.140');
+        const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        checkForUpdate('0.1.0-beta.109');
+        expect(stdoutSpy).not.toHaveBeenCalled();
+    });
+    it('cold cache → no print', () => {
+        setOutputMode('json');
+        const spy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        checkForUpdate('0.1.0-beta.109');
+        expect(spy).not.toHaveBeenCalled();
+    });
+    it('sentinel records the installed version and suppresses re-notify for it', () => {
+        setOutputMode('json');
+        recordServerLatest('0.1.0-beta.140');
+        writeUpgradePendingSentinel('0.1.0-beta.140'); // just installed 140
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        checkForUpdate('0.1.0-beta.140'); // running 140, latest 140 -> no notice
+        expect(stderrSpy).not.toHaveBeenCalled();
+    });
+    it('resolveLatestVersion serves a within-window npm fallback without refetching (P2)', async () => {
+        recordNpmLatest('0.1.0-beta.140', '0.1.0-beta.109'); // fresh (recordedAt = now)
+        npmResponseVersion = '0.1.0-beta.999'; // would win IF a fetch happened
+        const latest = await resolveLatestVersion('0.1.0-beta.109');
+        expect(latest).toBe('0.1.0-beta.140'); // fresh cache used, no network refresh
+    });
+    it('a lone fresh server header still triggers a live npm fetch — server-only cache is not trusted (P1)', async () => {
+        // Normal steady state: authenticated calls write a fresh server header, but the hot path never
+        // populates npm. If the server lags npm (108 vs 958), the live resolver must fetch npm rather
+        // than short-circuit on the server value, or pb doctor/upgrade would resolve the masked 108.
+        recordServerLatest('0.1.0-beta.108'); // fresh server only; no npm cache entry
+        npmResponseVersion = '0.1.0-beta.958'; // live npm is far newer
+        const latest = await resolveLatestVersion('0.1.0-beta.109');
+        expect(latest).toBe('0.1.0-beta.958'); // fetched + surfaced, not the masked server 108
+    });
+    it('resolveLatestVersion revalidates a stale npm fallback via a fresh fetch (P2)', async () => {
+        const realNow = Date.now;
+        recordNpmLatest('0.1.0-beta.140', '0.1.0-beta.109'); // recordedAt = now
+        Date.now = () => realNow() + 25 * 60 * 60 * 1000; // past the 24h npm window
+        npmResponseVersion = '0.1.0-beta.141'; // registry now serves a newer beta
+        try {
+            const latest = await resolveLatestVersion('0.1.0-beta.109');
+            expect(latest).toBe('0.1.0-beta.141'); // refreshed, not the stale 140
+        }
+        finally {
+            Date.now = realNow;
+        }
+    });
+    it('successful revalidation replaces a stale cache even when the live tag is not newer (P2)', async () => {
+        const realNow = Date.now;
+        recordNpmLatest('0.1.0-beta.140', '0.1.0-beta.109'); // seed npm cache at 140
+        Date.now = () => realNow() + 25 * 60 * 60 * 1000; // age it past the 24h window
+        npmResponseVersion = '0.1.0-beta.142'; // registry now points lower than installed
+        try {
+            // Installed is 145 (post-upgrade). The live tag (142) is <= installed, so recordNpmLatest
+            // refuses to overwrite — but the resolver must return the live truth (142), NOT the disproven
+            // stale 140 it would otherwise fall back to.
+            const latest = await resolveLatestVersion('0.1.0-beta.145');
+            expect(latest).toBe('0.1.0-beta.142');
+        }
+        finally {
+            Date.now = realNow;
+        }
+    });
+    it('falls back to a stale cached value only on fetch failure (offline backstop)', async () => {
+        const realNow = Date.now;
+        recordNpmLatest('0.1.0-beta.140', '0.1.0-beta.109');
+        Date.now = () => realNow() + 25 * 60 * 60 * 1000; // stale npm entry
+        npmResponseVersion = null; // registry unreachable → fetch resolves null
+        try {
+            const latest = await resolveLatestVersion('0.1.0-beta.109');
+            expect(latest).toBe('0.1.0-beta.140'); // offline → stale cache is better than nothing
+        }
+        finally {
+            Date.now = realNow;
+        }
+    });
+    it('hot-path resolveCachedLatest still returns a stale npm value (better than nothing)', () => {
+        const realNow = Date.now;
+        recordNpmLatest('0.1.0-beta.140', '0.1.0-beta.109');
+        Date.now = () => realNow() + 100 * 60 * 60 * 1000; // far past every freshness window
+        try {
+            expect(resolveCachedLatest()).toBe('0.1.0-beta.140'); // sync hot path never blocks/forgets
+        }
+        finally {
+            Date.now = realNow;
+        }
+    });
+});
+//# sourceMappingURL=update-check.test.js.map

package/dist/__tests__/update-check.test.js.map

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

package/dist/__tests__/update.test.js

@@ -1,15 +1,15 @@
 /**
- * pb update — verify mcpCallWithSession sequence and args.
+ * pb update — verify kernelCallWithSession sequence and args.
  * TEN-341 test contract: happy path, no session, empty entryId.
  */
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { runUpdate } from '../commands/update.js';
-import { CLIError } from '../lib/errors.js';
-const mcpCallWithSessionMock = vi.fn();
-const mcpCallMock = vi.fn();
+import { CLIError, ErrorCode } from '../lib/errors.js';
+const kernelCallWithSessionMock = vi.fn();
+const kernelCallMock = vi.fn();
 vi.mock('../lib/client.js', () => ({
-    mcpCallWithSession: (...args) => mcpCallWithSessionMock(...args),
-    mcpCall: (...args) => mcpCallMock(...args),
+    kernelCallWithSession: (...args) => kernelCallWithSessionMock(...args),
+    kernelCall: (...args) => kernelCallMock(...args),
     // McpError exported so update.ts can import the type (not used at runtime in tests).
     McpError: class McpError extends Error {
         details;
@@ -50,7 +50,7 @@ describe('runUpdate', () => {
         vi.clearAllMocks();
         mockSession = { sessionId: 'sess-test' };
         // BET-192: updateEntry returns warnings + normalization breakdown (symmetric with createEntry)
-        mcpCallWithSessionMock.mockResolvedValue({
+        kernelCallWithSessionMock.mockResolvedValue({
             id: 'j571abc123def456',
             warnings: [],
             normalization: { remapped: {}, rejected: [], accepted: [] },
@@ -58,7 +58,7 @@ describe('runUpdate', () => {
             validationWarnings: [],
         });
         // Post-update refresh: default to returning a minimal entry.
-        mcpCallMock.mockResolvedValue({
+        kernelCallMock.mockResolvedValue({
             entryId: 'BET-151',
             name: 'Test Entry',
             status: 'active',
@@ -72,7 +72,7 @@ describe('runUpdate', () => {
             note: 'Updated description',
         });
         writeSpy.mockRestore();
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
             entryId: 'BET-151',
             changedBy: 'agent:sess-test',
             data: { description: 'new description' },
@@ -88,7 +88,7 @@ describe('runUpdate', () => {
             note: 'Resolved',
         });
         writeSpy.mockRestore();
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
             entryId: 'TEN-703',
             changedBy: 'agent:sess-test',
             name: 'New name',
@@ -103,12 +103,46 @@ describe('runUpdate', () => {
             workflowStatus: 'shipped',
         });
         writeSpy.mockRestore();
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
             entryId: 'BET-271',
             changedBy: 'agent:sess-test',
             workflowStatus: 'shipped',
         });
     });
+    // WP-640 SWEEP (#653 review): `--reason ""` (present, empty) used to be silently dropped
+    // by a truthy check, so `pb entry archive <id> --reason ""` archived the entry with NO
+    // reason recorded despite the required-reason contract. It must now reach the server so
+    // the DEC-1572 enum guard can reject it explicitly.
+    it('forwards an explicitly-empty archivedReason to the server (does not silently drop it)', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({
+            entryId: 'STD-1',
+            status: 'archived',
+            archivedReason: '',
+        });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+            entryId: 'STD-1',
+            changedBy: 'agent:sess-test',
+            status: 'archived',
+            archivedReason: '',
+        });
+    });
+    it('still passes a real archivedReason value through unchanged', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({
+            entryId: 'STD-1',
+            status: 'archived',
+            archivedReason: 'superseded',
+        });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+            entryId: 'STD-1',
+            changedBy: 'agent:sess-test',
+            status: 'archived',
+            archivedReason: 'superseded',
+        });
+    });
     it('handles --field values containing = signs', async () => {
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         await runUpdate({
@@ -116,7 +150,7 @@ describe('runUpdate', () => {
             field: ['rationale=a=b=c'],
         });
         writeSpy.mockRestore();
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
             entryId: 'DEC-264',
             changedBy: 'agent:sess-test',
             data: { rationale: 'a=b=c' },
@@ -126,21 +160,21 @@ describe('runUpdate', () => {
         mockSession = null;
         await expect(runUpdate({ entryId: 'BET-151', field: ['x=1'] })).rejects.toThrow(CLIError);
         await expect(runUpdate({ entryId: 'BET-151', field: ['x=1'] })).rejects.toThrow('No active session');
-        expect(mcpCallWithSessionMock).not.toHaveBeenCalled();
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
     });
     it('throws CLIError with empty entryId', async () => {
         await expect(runUpdate({ entryId: '  ', field: ['x=1'] })).rejects.toThrow(CLIError);
         await expect(runUpdate({ entryId: '  ', field: ['x=1'] })).rejects.toThrow('Entry ID is required');
-        expect(mcpCallWithSessionMock).not.toHaveBeenCalled();
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
     });
     it('throws CLIError when nothing to update', async () => {
         await expect(runUpdate({ entryId: 'BET-151' })).rejects.toThrow(CLIError);
         await expect(runUpdate({ entryId: 'BET-151' })).rejects.toThrow('Nothing to update');
-        expect(mcpCallWithSessionMock).not.toHaveBeenCalled();
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
     });
     // ── Structured validation error tests ────────────────────────────────────
     it('throws CLIError with structured select field error message', async () => {
-        mcpCallWithSessionMock.mockRejectedValue(makeMcpError("Entry data validation failed: Field \"appetite\" must be one of: small, medium, large. Got: 'Small Batch'. Fix the values and try again.", 'VALIDATION_FAILED', [{
+        kernelCallWithSessionMock.mockRejectedValue(makeMcpError("Entry data validation failed: Field \"appetite\" must be one of: small, medium, large. Got: 'Small Batch'. Fix the values and try again.", 'VALIDATION_FAILED', [{
                 fieldKey: 'appetite',
                 fieldLabel: 'appetite',
                 invalidValue: 'Small Batch',
@@ -154,14 +188,48 @@ describe('runUpdate', () => {
         expect(err.message).toContain("Got: 'Small Batch'");
     });
     it('throws CLIError with plain error message when no structured details', async () => {
-        mcpCallWithSessionMock.mockRejectedValue(makeMcpError('Entry not found.', 'NOT_FOUND'));
+        kernelCallWithSessionMock.mockRejectedValue(makeMcpError('Entry not found.', 'NOT_FOUND'));
         const err = await runUpdate({ entryId: 'BET-999', field: ['x=1'] }).catch((e) => e);
         expect(err).toBeInstanceOf(CLIError);
         expect(err.message).toContain('Entry not found.');
     });
+    it('preserves a server authority refusal as machine-readable AUTH_DENIED', async () => {
+        kernelCallWithSessionMock.mockRejectedValue(makeMcpError('This record belongs to another team.', 'AUTHZ_PERMISSION_DENIED'));
+        const err = await runUpdate({ entryId: 'WP-OTHER-TEAM', field: ['description=no'] }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.AUTH_DENIED);
+        expect(err.category).toBe('auth');
+    });
+    it('preserves a returned organisational refusal and its truthful next action', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            outcome: 'refused',
+            refusal: {
+                category: 'auth',
+                code: 'role_not_owner',
+                reason: 'This person does not hold this record’s exact owning role in its owning team.',
+                requiredAction: 'Route this change to a holder of the record’s exact owning role, or ask the relevant Team Lead to change its ownership.',
+            },
+        });
+        const err = await runUpdate({ entryId: 'WP-OTHER-TEAM', field: ['description=no'] }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.AUTH_DENIED);
+        expect(err.category).toBe('auth');
+        expect(err.guidance).toBe('Route this change to a holder of the record’s exact owning role, or ask the relevant Team Lead to change its ownership.');
+    });
+    it('keeps a returned coherency refusal classified as validation', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            outcome: 'refused',
+            refusal: { code: 'COHERENCY_REFUSED', reason: 'This entry is not linked to the strategic spine.' },
+        });
+        const err = await runUpdate({ entryId: 'WP-UNLINKED', field: ['description=no'] }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(err.category).toBe('validation');
+        expect(err.guidance).toContain('strategic spine');
+    });
     // ── Slice 3: post-update refresh ─────────────────────────────────────────
     it('calls chain.getEntry after successful update and includes entry in output', async () => {
-        mcpCallMock.mockResolvedValue({
+        kernelCallMock.mockResolvedValue({
             entryId: 'BET-151',
             name: 'My Bet',
             status: 'active',
@@ -170,13 +238,13 @@ describe('runUpdate', () => {
         await runUpdate({ entryId: 'BET-151', field: ['description=new'] });
         const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
         writeSpy.mockRestore();
-        expect(mcpCallMock).toHaveBeenCalledWith('chain.getEntry', { entryId: 'BET-151' });
+        expect(kernelCallMock).toHaveBeenCalledWith('chain.getEntry', { entryId: 'BET-151' });
         // Pretty output: receipt then entry block
         expect(output).toContain('Updated BET-151');
         expect(output).toContain('My Bet');
     });
     it('still shows update receipt when post-update getEntry fails (graceful degradation)', async () => {
-        mcpCallMock.mockRejectedValue(new Error('network error'));
+        kernelCallMock.mockRejectedValue(new Error('network error'));
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         await runUpdate({ entryId: 'BET-151', field: ['description=new'] });
         const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
@@ -187,7 +255,7 @@ describe('runUpdate', () => {
     });
     // ── BET-192 / FEAT-575: Normalization warning tests ──────────────────────
     it('throws CLIError when fields are rejected (BET-192, BET-271)', async () => {
-        mcpCallWithSessionMock.mockResolvedValue({
+        kernelCallWithSessionMock.mockResolvedValue({
             id: 'j571abc123def456',
             warnings: ['Unknown field "foo" dropped. Available fields: description, doneWhen'],
             normalization: { remapped: {}, rejected: ['foo'], accepted: ['description'] },
@@ -206,8 +274,49 @@ describe('runUpdate', () => {
         expect(err.guidance).toContain('pb fields');
         writeSpy.mockRestore();
     });
+    // ── WP-475 E1 (FEAT-1346): coaching verdict in the update receipt ─────────
+    it('renders the coaching section when the write response carries a verdict (WP-475 E1)', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['description'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+            coaching: {
+                source: 'heuristic',
+                verdict: {
+                    entryId: 'DEC-77',
+                    canonicalKey: 'decision',
+                    tier: 'assertive',
+                    context: 'capture',
+                    passed: false,
+                    criteria: [
+                        { id: 'has_rationale', passed: true, weight: 3, hint: 'State why.', questionTemplate: 'Why this?' },
+                        { id: 'specificity', passed: false, weight: 2, hint: 'Be specific.', questionTemplate: 'What exactly?' },
+                    ],
+                    weakest: { criterion: 'specificity', hint: 'Be specific.', questionTemplate: 'What exactly?' },
+                    overridden: false,
+                },
+            },
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'DEC-77', field: ['rationale=better reason'] });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(output).toContain('Semantic quality: 1/2 criteria pass for decision (assertive tier)');
+        expect(output).toContain('[ ] specificity — Be specific.');
+        expect(output).toContain('Coaching hint: Be specific.');
+        expect(output).toContain('Consider: What exactly?');
+    });
+    it('renders no coaching section when the write response has none (backward compat)', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'BET-151', field: ['description=new'] });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(output).not.toContain('Semantic quality');
+    });
     it('displays no warnings when all fields are valid (BET-192)', async () => {
-        mcpCallWithSessionMock.mockResolvedValue({
+        kernelCallWithSessionMock.mockResolvedValue({
             id: 'j571abc123def456',
             warnings: [],
             normalization: { remapped: {}, rejected: [], accepted: ['description'] },
@@ -225,4 +334,136 @@ describe('runUpdate', () => {
         expect(output).not.toContain('Validation warnings');
     });
 });
+/**
+ * S5 of WP-634 (TASK-45) — `pb update --type <key>` threads a canonicalKey reclassification
+ * through the EXISTING `chain.updateEntry` door (convex/agentKnowledge/entries.ts:1462, arg
+ * `canonicalKey` at :1471). No new server validation: the typeMap check, BR-55, the cardinality
+ * guards and the post-commit immutability guard (convex/lib/guards.ts:190-200) all already run
+ * there, and their refusal text must reach the operator verbatim rather than being reworded or
+ * pre-empted by a client-side copy of the rule.
+ */
+describe('runUpdate --type (S5 of WP-634, TASK-45)', () => {
+    // Its OWN seeding, mirroring the `runUpdate` suite above (PR #622 review). This block is a
+    // SIBLING of that suite, so its beforeEach never ran here: the tests passed only in a
+    // whole-file run, riding whatever mock state the previous suite's last test left behind, and
+    // failed in isolation with "Cannot read properties of undefined (reading 'outcome')" — a test
+    // that depends on execution order is not a test.
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockSession = { sessionId: 'sess-test' };
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: [] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+        });
+        kernelCallMock.mockResolvedValue({
+            entryId: 'INS-900',
+            name: 'Test Entry',
+            status: 'draft',
+        });
+    });
+    it('relays --type as the canonicalKey arg on chain.updateEntry', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'INS-900', type: 'decision' });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+            entryId: 'INS-900',
+            changedBy: 'agent:sess-test',
+            canonicalKey: 'decision',
+        });
+    });
+    it('counts as something to update on its own — --type alone is a valid write', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: 'decision' })).resolves.toBeUndefined();
+        writeSpy.mockRestore();
+        // The point is that --type alone clears the "Nothing to update" arity check and actually
+        // reaches the write door — not a total call count, which includes other session traffic.
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', expect.objectContaining({
+            canonicalKey: 'decision',
+        }));
+    });
+    it('combines with other updates in one call', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'INS-900', type: 'decision', name: 'Renamed', note: 'Reclassified' });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+            entryId: 'INS-900',
+            changedBy: 'agent:sess-test',
+            name: 'Renamed',
+            canonicalKey: 'decision',
+            changeNote: 'Reclassified',
+        });
+    });
+    it('trims the value — a padded --type must not reach the server as an unmatched key', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'INS-900', type: '  decision  ' });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+            entryId: 'INS-900',
+            changedBy: 'agent:sess-test',
+            canonicalKey: 'decision',
+        });
+    });
+    /**
+     * PROVIDED-but-blank must fail loudly, never be treated as ABSENT (PR #622 review). The
+     * whitespace case is the dangerous one: paired with another flag it used to report a
+     * successful rename while silently discarding the reclassification.
+     */
+    it('refuses a whitespace-only --type instead of silently dropping it alongside another update', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', name: 'Renamed', type: '   ' }))
+            .rejects.toThrow('--type was provided but empty.');
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled(); // refused BEFORE any relay
+    });
+    it('refuses a whitespace-only --type on its own rather than reporting "Nothing to update"', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: '   ' }))
+            .rejects.toThrow('--type was provided but empty.');
+        writeSpy.mockRestore();
+    });
+    it('refuses an empty-string --type', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: '' }))
+            .rejects.toThrow('--type was provided but empty.');
+        writeSpy.mockRestore();
+    });
+    it('omits canonicalKey entirely when --type is not passed', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'INS-900', name: 'Just a rename' });
+        writeSpy.mockRestore();
+        const args = kernelCallWithSessionMock.mock.calls[0][1];
+        expect(args).not.toHaveProperty('canonicalKey');
+    });
+    /**
+     * The two guard texts are the deliverable, so they must arrive UNREWORDED. The CLI must not
+     * carry its own copy of "committed entries cannot be retyped" or of BR-55 — a client-side
+     * pre-check would drift from the server rule and is exactly what "no new server-side
+     * validation, existing guard text verbatim" rules out.
+     */
+    it('surfaces the post-commit immutability guard text verbatim', async () => {
+        const guardText = 'canonicalKey cannot be changed after an entry has been committed. '
+            + 'To reclassify, create a new entry and supersede this one.';
+        kernelCallWithSessionMock.mockRejectedValueOnce(makeMcpError(guardText, 'VALIDATION_FAILED'));
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'DEC-1', type: 'insight' })).rejects.toThrow(guardText);
+        writeSpy.mockRestore();
+    });
+    it('surfaces the BR-55 out-of-collection refusal verbatim', async () => {
+        const br55 = 'Vision and purpose entries must be in the strategy collection. This entry is in "insights".';
+        kernelCallWithSessionMock.mockRejectedValueOnce(makeMcpError(br55, 'VALIDATION_FAILED'));
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: 'vision' })).rejects.toThrow(br55);
+        writeSpy.mockRestore();
+    });
+    it('surfaces the invalid-type refusal verbatim', async () => {
+        const invalid = 'Invalid canonical key "nonsense". Must be one of the 42 canonical types or null/undefined.';
+        kernelCallWithSessionMock.mockRejectedValueOnce(makeMcpError(invalid, 'VALIDATION_FAILED'));
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: 'nonsense' })).rejects.toThrow(invalid);
+        writeSpy.mockRestore();
+    });
+});
 //# sourceMappingURL=update.test.js.map