@productbrain/cli 0.1.0-beta.1138 → 0.1.0-beta.11385

package/dist/__tests__/config.test.js

@@ -6,7 +6,7 @@
  */
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { mkdirSync, writeFileSync, readFileSync, rmSync } from 'fs';
-import { resolve } from 'path';
+import { dirname, resolve } from 'path';
 import { tmpdir } from 'os';
 import { randomUUID } from 'crypto';
 // Mock the profiles module to prevent real profile config from leaking in
@@ -30,6 +30,7 @@ describe('config resolution', () => {
     const envKeys = ['PRODUCTBRAIN_API_KEY', 'CONVEX_SITE_URL', 'PB_PROFILE', 'PB_ENV'];
     // Import after mock setup
     let resolveConfig;
+    let getConfig;
     let getConfigSafe;
     let resetConfigCache;
     let findProjectRoot;
@@ -49,6 +50,7 @@ describe('config resolution', () => {
         // Dynamic import to get module with mocks applied
         const config = await import('../lib/config.js');
         resolveConfig = config.resolveConfig;
+        getConfig = config.getConfig;
         getConfigSafe = config.getConfigSafe;
         resetConfigCache = config.resetConfigCache;
         findProjectRoot = config.findProjectRoot;
@@ -173,19 +175,127 @@ describe('config resolution', () => {
             expect(result.apiKey).toBe('pb_sk_local_profile_key');
             expect(result.source).toBe('project');
         });
-        it('config.json siteUrl is used as gateway override with global profile', async () => {
-            const { resolveProfileConfig } = await import('../lib/profiles.js');
-            resolveProfileConfig.mockReturnValueOnce({
-                apiKey: 'pb_sk_global_key',
-                siteUrl: 'https://profile.example.com',
+        it('FAILS CLOSED on a dangling repo-local pin — never silently falls through to the global active profile', async () => {
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            // Pin names a profile that no longer resolves (deleted, or never fully set up).
+            resolveNamedProfileConfig.mockReturnValue(null);
+            // A perfectly usable global profile is available — and must NOT be adopted.
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_global_profile_key',
+                siteUrl: 'https://global-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'deleted-workspace' }));
+            expect(() => resolveConfig()).toThrow(/pinned to profile "deleted-workspace"/);
+        });
+        it('dangling repo-local pin throws AUTH_MISSING rather than returning a foreign credential', async () => {
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            // Pin resolves to a profile file that exists but carries no API key.
+            resolveNamedProfileConfig.mockReturnValue({
+                siteUrl: 'https://pinned.example.com',
+            });
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_global_profile_key',
+                siteUrl: 'https://global-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'keyless-workspace' }));
+            let caught;
+            try {
+                resolveConfig();
+            }
+            catch (e) {
+                caught = e;
+            }
+            expect(caught?.code).toBe('AUTH_MISSING');
+        });
+        it('TASK-562: with no key, getConfig and getConfigOrGuide throw the one missing-key sentence getConfigSafe reports, and never ask to paste a key', async () => {
+            const { getConfigOrGuide } = await import('../lib/config.js');
+            const safe = getConfigSafe();
+            expect(safe.ok).toBe(false);
+            if (safe.ok)
+                return;
+            expect(safe.guidance).not.toMatch(/pb login/);
+            let caught;
+            try {
+                getConfig();
+            }
+            catch (e) {
+                caught = e;
+            }
+            expect(caught).toMatchObject({ message: safe.reason, guidance: safe.guidance, code: 'AUTH_MISSING' });
+            const tty = process.stdin.isTTY;
+            Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
+            try {
+                await expect(getConfigOrGuide(async () => { })).rejects.toMatchObject({ message: safe.reason, guidance: safe.guidance });
+            }
+            finally {
+                Object.defineProperty(process.stdin, 'isTTY', { value: tty, configurable: true });
+            }
+        });
+        it('getConfig() refuses a dangling pin — the loadEnv() cascade must not adopt the global profile', async () => {
+            // This is the door ~98 command modules use, and it is a SEPARATE cascade from
+            // resolveConfig() — loadEnv() mutates process.env rather than returning a value.
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue(null);
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_global_profile_key',
+                siteUrl: 'https://global-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'deleted-workspace' }));
+            expect(() => getConfig()).toThrow(/pinned to profile "deleted-workspace"/);
+            // The foreign credential must never become the live binding.
+            expect(process.env.PRODUCTBRAIN_API_KEY).toBeUndefined();
+        });
+        it('a pin whose profile has a malformed key is a broken pin, not a credential', async () => {
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'not-a-pb-key',
+                siteUrl: 'https://pinned.example.com',
+            });
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_global_profile_key',
+                siteUrl: 'https://global-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'malformed-workspace' }));
+            // Names the pin, rather than deferring to a generic "no API key, run pb login".
+            expect(() => resolveConfig()).toThrow(/pinned to profile "malformed-workspace"/);
+        });
+        it('getConfigSafe() REPORTS a dangling pin instead of throwing — diagnostics must still render', async () => {
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue(null);
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_global_profile_key',
+                siteUrl: 'https://global-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'deleted-workspace' }));
+            // `pb doctor` and the bare-`pb` dashboard go through here; they must diagnose, not die.
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            expect(result.reason).toMatch(/pinned to profile "deleted-workspace"/);
+        });
+        it('a pin with no URL of its own goes to DEFAULT_SITE_URL, never config.json siteUrl (TEN-4500)', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValueOnce({
+                apiKey: 'pb_sk_pinned_key',
             });
             const pbDir = resolve(tempDir, '.productbrain');
             mkdirSync(pbDir, { recursive: true });
             writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'https://project-gateway.example.com' }));
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'product-brain' }));
             const result = resolveConfig();
-            expect(result.apiKey).toBe('pb_sk_global_key');
-            expect(result.siteUrl).toBe('https://project-gateway.example.com');
-            expect(result.source).toBe('profile');
+            expect(result.apiKey).toBe('pb_sk_pinned_key');
+            expect(result.siteUrl).toBe('https://gateway.productbrain.io');
+            expect(result.siteUrlSource).toBe('default');
+            expect(result.source).toBe('project');
         });
         it('env vars override project config.local.json', () => {
             process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_env_key';
@@ -204,24 +314,18 @@ describe('config resolution', () => {
             expect(result.siteUrl).toBe('https://gateway.productbrain.io');
             expect(result.source).toBe('default');
         });
-        it('ignores profile field in config.json (legacy migration)', () => {
+        it('ignores profile field in config.json (legacy migration) — not a pin, so the project has no tenant', () => {
             const pbDir = resolve(tempDir, '.productbrain');
             mkdirSync(pbDir, { recursive: true });
-            // Old config.json with profile field — must be ignored
+            // Old config.json with profile field — must be ignored, not treated as a pin
             writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'https://project.example.com', profile: 'should-be-ignored' }));
-            const result = resolveConfig();
-            // profile in config.json must NOT be resolved — no profile mock set up
-            expect(result.apiKey).toBeUndefined();
-            expect(result.source).toBe('default');
+            expect(() => resolveConfig()).toThrow(/no tenant pin/i);
         });
-        it('handles partial project config (only siteUrl, no apiKey)', () => {
+        it('a declared project with only siteUrl and no pin refuses rather than falling through', () => {
             const pbDir = resolve(tempDir, '.productbrain');
             mkdirSync(pbDir, { recursive: true });
             writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'https://partial.example.com' }));
-            const result = resolveConfig();
-            // No apiKey in project config, so it should fall through to default
-            expect(result.apiKey).toBeUndefined();
-            expect(result.source).toBe('default');
+            expect(() => resolveConfig()).toThrow(/no tenant pin/i);
         });
     });
     describe('getConfigSafe()', () => {
@@ -233,6 +337,211 @@ describe('config resolution', () => {
                 expect(result.reason).toContain('No API key');
             }
         });
+        it('names the FILE, not CONVEX_SITE_URL, when a file supplied the non-HTTPS URL', () => {
+            // A file-sourced siteUrl outranks CONVEX_SITE_URL everywhere except an env-key override, so
+            // "set CONVEX_SITE_URL" would send the operator back through the same failure.
+            process.env.CONVEX_SITE_URL = 'https://this-would-never-win.example.com';
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                apiKey: 'pb_sk_preview_key_0123456789abcdef',
+                siteUrl: 'http://insecure.example.com',
+                preview: true,
+            }));
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-url');
+                expect(result.reason).toMatch(/must use HTTPS/i);
+                // The binding supplies its own URL, so the repair is that file alone — naming a profile
+                // it may also pin would point at something that does not control this URL.
+                expect(result.guidance).toContain('.productbrain/config.local.json');
+                expect(result.guidance).not.toMatch(/profile/i);
+                expect(result.guidance).not.toMatch(/CONVEX_SITE_URL/);
+            }
+        });
+        it('names CONVEX_SITE_URL when the environment did supply the non-HTTPS URL', () => {
+            process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_env_key';
+            process.env.CONVEX_SITE_URL = 'http://insecure.example.com';
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-url');
+                expect(result.guidance).toContain('CONVEX_SITE_URL');
+            }
+        });
+        // ── The URL's origin is NOT the credential's origin ────────────────────────────────────
+        //
+        // A key travels only with the URL beside it (TEN-4500), so the repair names that source —
+        // never config.json, whose siteUrl no longer routes any key, and never a sibling file that
+        // happens to sit in the same directory.
+        it('a non-HTTPS config.json siteUrl never reaches a pinned key (TEN-4500)', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_pinned_key',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'http://insecure.example.com' }));
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'product-brain' }));
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(true);
+            if (result.ok)
+                expect(result.siteUrl).toBe('https://gateway.productbrain.io');
+        });
+        it('names the pin — not config.json or a CWD .env — when the pinned profile supplied the URL', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_pinned_key',
+                siteUrl: 'http://pin.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'http://insecure.example.com' }));
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'product-brain' }));
+            writeFileSync(resolve(tempDir, '.env'), 'PRODUCTBRAIN_API_KEY=pb_sk_cwd_key\nCONVEX_SITE_URL=https://cwd-would-have-been-fine.example.com\n');
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-url');
+                expect(result.reason).toContain('http://pin.example.com');
+                expect(result.guidance).toContain('pinned by .productbrain/config.local.json');
+                expect(result.guidance).not.toContain('.productbrain/config.json');
+                expect(result.guidance).not.toMatch(/\.env file/);
+            }
+        });
+        it('names the profile the repo pin points at, not just "the profile it pins"', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_pinned_key_0123456789',
+                siteUrl: 'http://insecure.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'pinned-workspace' }));
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-url');
+                expect(result.guidance).toContain('pinned-workspace');
+            }
+        });
+        it('names the CWD env file that actually won, not the generic .env', () => {
+            // CWD_ENV_PATHS scans .env.mcp first, so a generic "the .env file" label would send the
+            // operator to edit a file the cascade never read.
+            writeFileSync(resolve(tempDir, '.env.mcp'), 'PRODUCTBRAIN_API_KEY=pb_sk_cwd_key\nCONVEX_SITE_URL=http://insecure.example.com\n');
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-url');
+                expect(result.guidance).toContain('.env.mcp');
+            }
+        });
+        it('tells the operator to unset PRODUCTBRAIN_API_KEY — not to run pb login — for a bad exported key', () => {
+            // An exported key wins step 1 of the cascade, and `pb login` writes to a profile or the
+            // legacy home file — both of which lose to it. "Run pb login" would loop forever.
+            process.env.PRODUCTBRAIN_API_KEY = 'bad_prefix_key';
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-key');
+                expect(result.guidance).toMatch(/Unset PRODUCTBRAIN_API_KEY|replace it/);
+                // `pb login` may only be named to explain why it cannot help — never as the instruction.
+                expect(result.guidance).not.toMatch(/Run `pb login`/);
+                expect(result.guidance).toMatch(/cannot repair/);
+                expect(result.nextCommand).not.toBe('pb login');
+            }
+        });
+        it('still points a stored malformed key at pb login — login CAN repair that one', async () => {
+            const { resolveProfileConfig } = await import('../lib/profiles.js');
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'bad_prefix_key',
+                siteUrl: 'https://profile.example.com',
+            });
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-key');
+                expect(result.guidance).toMatch(/pb login/);
+                expect(result.nextCommand).toBe('pb login');
+            }
+        });
+        // ── Which profile actually supplied it ──────────────────────────────────────────────────
+        //
+        // resolveProfileConfig() reaches a credential four ways — PB_PROFILE, the active-profile
+        // marker, a `default` fallback, and the legacy ~/.config/productbrain/.env — and reports the
+        // winner's name. A fixed "the active profile" label sends the operator to edit a profile that
+        // supplied nothing, so the same failure comes straight back.
+        it('names the PB_PROFILE-selected profile, not "the active profile", for its non-HTTPS URL', async () => {
+            const { resolveProfileConfig, getGlobalActiveProfile } = await import('../lib/profiles.js');
+            // A DIFFERENT profile is globally active. PB_PROFILE outranks it in profiles.ts, which
+            // returns the selected name alongside the credential (profiles.ts resolveProfileConfig 1).
+            getGlobalActiveProfile.mockReturnValue('main-workspace');
+            process.env.PB_PROFILE = 'preview-workspace';
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_selected_profile_key',
+                siteUrl: 'http://insecure.example.com',
+                profileName: 'preview-workspace',
+            });
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-url');
+                expect(result.guidance).toContain('the profile "preview-workspace"');
+                expect(result.guidance).not.toContain('the active profile');
+                // The globally active profile did not supply this URL and must not be named.
+                expect(result.guidance).not.toContain('main-workspace');
+            }
+        });
+        it('names the `default` fallback profile for a malformed stored key', async () => {
+            const { resolveProfileConfig } = await import('../lib/profiles.js');
+            // No PB_PROFILE and no active-profile marker: profiles.ts falls back to `default`, which is
+            // a real file the operator can open — "the active profile" is not.
+            resolveProfileConfig.mockReturnValue({
+                apiKey: 'bad_prefix_key',
+                siteUrl: 'https://profile.example.com',
+                profileName: 'default',
+            });
+            resetConfigCache();
+            const result = getConfigSafe();
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.kind).toBe('invalid-key');
+                expect(result.reason).toContain('the profile "default"');
+                expect(result.reason).not.toContain('the active profile');
+            }
+        });
+        it('does NOT call the legacy home config "the active profile" — it is not a named profile', async () => {
+            // resolveConfig() step 4 labels the legacy ~/.config/productbrain/.env `profile`, but it
+            // carries no profile name at all, so naming a profile there would be a fabrication.
+            const { HOME_ENV_PATH } = await import('../lib/config.js');
+            mkdirSync(dirname(HOME_ENV_PATH), { recursive: true });
+            writeFileSync(HOME_ENV_PATH, 'PRODUCTBRAIN_API_KEY=bad_prefix_key\n');
+            try {
+                resetConfigCache();
+                const result = getConfigSafe();
+                expect(result.ok).toBe(false);
+                if (!result.ok) {
+                    expect(result.kind).toBe('invalid-key');
+                    expect(result.reason).not.toContain('the active profile');
+                    expect(result.reason).toContain('the stored profile configuration');
+                }
+            }
+            finally {
+                // The fake home is shared by every test in this file; a stray legacy .env would supply a
+                // credential to the cases that assert none is found.
+                rmSync(HOME_ENV_PATH, { force: true });
+            }
+        });
         it('returns { ok: true } with correct source when key exists in env', () => {
             process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_test_key';
             process.env.CONVEX_SITE_URL = 'https://test.example.com';
@@ -285,19 +594,19 @@ describe('config resolution', () => {
         });
     });
     describe('.productbrain/config.json error handling', () => {
-        it('warns but does not crash on invalid JSON', () => {
+        it('warns on invalid JSON, and still refuses — a damaged declaration is not an escape hatch', () => {
             const pbDir = resolve(tempDir, '.productbrain');
             mkdirSync(pbDir, { recursive: true });
             writeFileSync(resolve(pbDir, 'config.json'), '{ invalid json!!!');
-            // Capture stderr
-            const stderrWrite = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-            const result = resolveConfig();
-            // Should have warned
-            expect(stderrWrite).toHaveBeenCalledWith(expect.stringContaining('invalid JSON'));
-            // Should fall through to default
-            expect(result.apiKey).toBeUndefined();
-            expect(result.source).toBe('default');
-            stderrWrite.mockRestore();
+            // The file is unreadable but PRESENT, so the repo has still declared itself a project.
+            // Falling through here would hand the global profile a workspace precisely when the
+            // committed declaration is corrupt — the wrong-tenant substitution WP-694 S2 closes.
+            //
+            // No stderr assertion: the refusal is reached on the file's EXISTENCE, so nothing parses
+            // config.json on this path and the "invalid JSON" warning never fires. Refusing outright
+            // supersedes warning-then-using-someone-else's-workspace. The sibling test below still
+            // covers the warn-and-continue path for a malformed config.local.json.
+            expect(() => resolveConfig()).toThrow(/no tenant pin/i);
         });
         it('warns but does not crash on invalid config.local.json', () => {
             const pbDir = resolve(tempDir, '.productbrain');
@@ -379,6 +688,17 @@ describe('config resolution', () => {
             const { resolveEffectiveProfile } = await import('../lib/config.js');
             expect(resolveEffectiveProfile()).toEqual({ profile: 'repo-pin', source: 'local' });
         });
+        // The pin's key is bound by resolveConfig() step 2b / loadEnv() step 1b before the profile
+        // system reads PB_PROFILE, so the env name never supplies the credential here. Reporting it
+        // would label every identity surface with a workspace the CLI is not operating against.
+        it('prefers the repo pin over PB_PROFILE, matching which profile supplies the credential', async () => {
+            process.env.PB_PROFILE = 'from-env';
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'repo-pin' }));
+            const { resolveEffectiveProfile } = await import('../lib/config.js');
+            expect(resolveEffectiveProfile()).toEqual({ profile: 'repo-pin', source: 'local' });
+        });
         it('returns global source from the active-profile file when no local pin', async () => {
             const profiles = await import('../lib/profiles.js');
             profiles.getGlobalActiveProfile.mockReturnValue('global-ws');
@@ -446,7 +766,7 @@ describe('config resolution', () => {
             expect(result.apiKey).toBe('pb_sk_profile_key');
             expect(result.source).toBe('project');
         });
-        it('rejects apiKey that does not start with API_KEY_PREFIX', () => {
+        it('rejects a preview binding whose apiKey does not start with API_KEY_PREFIX', () => {
             const pbDir = resolve(tempDir, '.productbrain');
             mkdirSync(pbDir, { recursive: true });
             writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
@@ -455,10 +775,9 @@ describe('config resolution', () => {
                 preview: true,
             }));
             resetConfigCache();
-            const result = resolveConfig();
-            // Should not pick up the invalid-prefix key
-            expect(result.apiKey).toBeUndefined();
-            expect(result.source).toBe('default');
+            // A present-but-malformed key is unusable, not absent — the refusal must say so, or the
+            // operator goes looking for a key that is sitting right there in the file.
+            expect(() => resolveConfig()).toThrow(/incomplete preview binding.*not a valid pb_sk_ key/i);
         });
         it('SF-3: does NOT bind a preview apiKey that has no siteUrl (never borrows config.json gateway)', () => {
             const pbDir = resolve(tempDir, '.productbrain');
@@ -468,12 +787,145 @@ describe('config resolution', () => {
             // Preview key present but its OWN siteUrl is absent (hand-edit / partial preview.json).
             writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ apiKey: 'pb_sk_preview_key_0123456789abcdef', preview: true }));
             resetConfigCache();
+            // The preview key must NOT be bound or allowed to fall through. Pairing it with
+            // config.json's real-dev gateway would send a preview credential to the wrong deployment.
+            expect(() => resolveConfig()).toThrow(/incomplete preview binding.*missing deployment URL/i);
+        });
+        it('S5: an incomplete preview binding is diagnosed before a sibling profile pin', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue(null);
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                profile: 'repo-pin',
+                apiKey: 'pb_sk_preview_key_0123456789abcdef',
+                preview: true,
+                workspaceName: 'Preview Workspace',
+            }));
+            resetConfigCache();
+            expect(() => resolveConfig()).toThrow(/incomplete preview binding.*missing deployment URL/i);
+            expect(() => getConfig()).toThrow(/incomplete preview binding.*missing deployment URL/i);
+        });
+        // ── Marker-less bindings: the claim is the credential, not the `preview` stamp ──────────
+        //
+        // A config.local.json carrying an apiKey is asserting which workspace this repo talks to
+        // whether or not `pb:preview` stamped `preview: true` — a hand-written or partially-scrubbed
+        // file is exactly the case that must not be skipped.
+        it('binds a marker-less apiKey + siteUrl pair and does NOT defer to a sibling profile pin', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            // A perfectly resolvable pin sits in the same file — it names a DIFFERENT tenant, so
+            // adopting it would silently retarget every read and write.
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_sibling_pin_key',
+                siteUrl: 'https://sibling-pin.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                profile: 'sibling-pin',
+                apiKey: 'pb_sk_markerless_key_0123456789',
+                siteUrl: 'https://markerless.convex.site',
+                // no `preview: true` marker
+            }));
+            resetConfigCache();
             const result = resolveConfig();
-            // The preview key must NOT be bound — pairing it with config.json's real-dev gateway would
-            // send a preview credential to a non-preview deployment (STD-261). Branch is skipped entirely.
-            expect(result.apiKey).not.toBe('pb_sk_preview_key_0123456789abcdef');
-            expect(result.apiKey).toBeUndefined();
-            expect(result.source).toBe('default');
+            expect(result.apiKey).toBe('pb_sk_markerless_key_0123456789');
+            expect(result.siteUrl).toBe('https://markerless.convex.site');
+            expect(result.source).toBe('project');
+        });
+        it('refuses a marker-less apiKey with no siteUrl instead of resolving to the default gateway', () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ apiKey: 'pb_sk_markerless_key_0123456789' }));
+            resetConfigCache();
+            // Silently falling through would send this credential to the production gateway (STD-261).
+            expect(() => resolveConfig()).toThrow(/incomplete preview binding.*missing deployment URL/i);
+        });
+        it('S5: the marker-less refusal also holds through the loadEnv() cascade', () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ apiKey: 'pb_sk_markerless_key_0123456789' }));
+            resetConfigCache();
+            expect(() => getConfig()).toThrow(/incomplete preview binding.*missing deployment URL/i);
+            // The refusal must not leave a half-bound credential behind for the next caller.
+            expect(process.env.PRODUCTBRAIN_API_KEY).toBeUndefined();
+        });
+        // A present-but-non-string apiKey is a corrupt or hand-written binding, not an absent one.
+        // Treating it as absent would let the sibling profile pin supply a DIFFERENT tenant's
+        // credential — the workspace substitution this path exists to prevent.
+        it.each([
+            ['a number', 12345],
+            ['an empty string', ''],
+            ['a boolean', true],
+            ['an object', { key: 'pb_sk_nested' }],
+        ])('refuses a marker-less binding whose apiKey is %s, rather than adopting the sibling pin', async (_label, apiKey) => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            // A perfectly resolvable pin naming a DIFFERENT tenant sits in the same file.
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_sibling_pin_key',
+                siteUrl: 'https://sibling-pin.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'sibling-pin', apiKey, siteUrl: 'https://markerless.convex.site' }));
+            resetConfigCache();
+            expect(() => resolveConfig()).toThrow(/not a valid pb_sk_ key/i);
+        });
+        it('treats an explicitly null apiKey as absent — JSON null means "no value"', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_pin_key',
+                siteUrl: 'https://pinned.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'pinned-workspace', apiKey: null }));
+            resetConfigCache();
+            const result = resolveConfig();
+            expect(result.apiKey).toBe('pb_sk_pin_key');
+            expect(result.source).toBe('project');
+        });
+        it('leaves the ordinary pin-only path untouched — the widened claim test must not swallow it', async () => {
+            const { resolveNamedProfileConfig } = await import('../lib/profiles.js');
+            resolveNamedProfileConfig.mockReturnValue({
+                apiKey: 'pb_sk_pin_only_key',
+                siteUrl: 'https://pinned-profile.example.com',
+            });
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            // Committed config.json + a pin whose profile stores its own URL: the pin path's normal
+            // shape (pb connect writes the URL into the profile). config.json's siteUrl routes nothing.
+            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: 'https://project-gateway.example.com' }));
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'pin-only-workspace' }));
+            resetConfigCache();
+            const result = resolveConfig();
+            expect(result.apiKey).toBe('pb_sk_pin_only_key');
+            expect(result.siteUrl).toBe('https://pinned-profile.example.com');
+            expect(result.source).toBe('project');
+        });
+    });
+    describe('readLocalProjectConfig() — apiKey validity', () => {
+        it('withholds a malformed apiKey and flags it so diagnostics can name the fault', async () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ apiKey: 'sk_bad_prefix_key', siteUrl: 'https://my-preview.convex.site' }));
+            const { readLocalProjectConfig } = await import('../lib/config.js');
+            const local = readLocalProjectConfig();
+            // Withheld from `apiKey` so it can never bind, but not reported as absent either.
+            expect(local?.apiKey).toBeUndefined();
+            expect(local?.apiKeyMalformed).toBe(true);
+        });
+        it('loads a valid apiKey with no malformed flag', async () => {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({
+                apiKey: 'pb_sk_preview_key_0123456789abcdef',
+                siteUrl: 'https://my-preview.convex.site',
+            }));
+            const { readLocalProjectConfig } = await import('../lib/config.js');
+            const local = readLocalProjectConfig();
+            expect(local?.apiKey).toBe('pb_sk_preview_key_0123456789abcdef');
+            expect(local?.apiKeyMalformed).toBeUndefined();
         });
     });
     describe('getPreviewBinding()', () => {
@@ -562,5 +1014,96 @@ describe('config resolution', () => {
             stderrWrite.mockRestore();
         });
     });
+    // ── TEN-4500 / TASK-640: a key travels only with the site URL stored or exported beside it ──
+    //
+    // `.productbrain/config.json` is committed, so a cloned repo controls its siteUrl. A key from
+    // anywhere else must never be sent there: with no URL of its own it goes to DEFAULT_SITE_URL.
+    describe('a key travels only with its own site URL (TEN-4500)', () => {
+        const DEFAULT = 'https://gateway.productbrain.io';
+        const COMMITTED = 'https://cloned-repo.example.com';
+        function commitProjectSiteUrl() {
+            const pbDir = resolve(tempDir, '.productbrain');
+            mkdirSync(pbDir, { recursive: true });
+            writeFileSync(resolve(pbDir, 'config.json'), JSON.stringify({ siteUrl: COMMITTED }));
+            return pbDir;
+        }
+        it('an exported key with no exported site URL is sent to DEFAULT_SITE_URL, never config.json siteUrl', () => {
+            process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_env_key';
+            commitProjectSiteUrl();
+            expect(getConfig().siteUrl).toBe(DEFAULT);
+        });
+        it('loadEnv and resolveConfig name the same site URL for the same inputs', async () => {
+            const { resolveNamedProfileConfig, resolveProfileConfig } = await import('../lib/profiles.js');
+            const named = resolveNamedProfileConfig;
+            const active = resolveProfileConfig;
+            const cases = [
+                {
+                    name: 'env key, no env URL, committed config.json',
+                    arrange: () => {
+                        process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_env_key';
+                        commitProjectSiteUrl();
+                    },
+                    expected: DEFAULT,
+                },
+                {
+                    name: 'env key with env URL, committed config.json',
+                    arrange: () => {
+                        process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_env_key';
+                        process.env.CONVEX_SITE_URL = 'https://env.example.com';
+                        commitProjectSiteUrl();
+                    },
+                    expected: 'https://env.example.com',
+                },
+                {
+                    name: 'pinned profile with its own URL, exported URL, committed config.json',
+                    arrange: () => {
+                        named.mockReturnValue({ apiKey: 'pb_sk_pinned_key', siteUrl: 'https://pinned.example.com' });
+                        process.env.CONVEX_SITE_URL = 'https://env.example.com';
+                        const pbDir = commitProjectSiteUrl();
+                        writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'product-brain' }));
+                    },
+                    expected: 'https://pinned.example.com',
+                },
+                {
+                    name: 'pinned profile with no URL, committed config.json',
+                    arrange: () => {
+                        named.mockReturnValue({ apiKey: 'pb_sk_pinned_key' });
+                        const pbDir = commitProjectSiteUrl();
+                        writeFileSync(resolve(pbDir, 'config.local.json'), JSON.stringify({ profile: 'product-brain' }));
+                    },
+                    expected: DEFAULT,
+                },
+                {
+                    name: 'unpinned profile with its own URL, exported URL',
+                    arrange: () => {
+                        active.mockReturnValue({ apiKey: 'pb_sk_profile_key', siteUrl: 'https://profile.example.com', profileName: 'p' });
+                        process.env.CONVEX_SITE_URL = 'https://env.example.com';
+                    },
+                    expected: 'https://profile.example.com',
+                },
+                {
+                    name: 'unpinned profile with no URL, exported URL',
+                    arrange: () => {
+                        active.mockReturnValue({ apiKey: 'pb_sk_profile_key', profileName: 'p' });
+                        process.env.CONVEX_SITE_URL = 'https://env.example.com';
+                    },
+                    expected: DEFAULT,
+                },
+            ];
+            const observed = cases.map(({ name, arrange }) => {
+                named.mockReset();
+                active.mockReset();
+                delete process.env.PRODUCTBRAIN_API_KEY;
+                delete process.env.CONVEX_SITE_URL;
+                rmSync(resolve(tempDir, '.productbrain'), { recursive: true, force: true });
+                arrange();
+                const resolved = resolveConfig().siteUrl;
+                resetConfigCache();
+                const loaded = getConfig().siteUrl;
+                return { name, resolved, loaded };
+            });
+            expect(observed).toEqual(cases.map(({ name, expected }) => ({ name, resolved: expected, loaded: expected })));
+        });
+    });
 });
 //# sourceMappingURL=config.test.js.map