@productbrain/cli 0.1.0-beta.1428 → 0.1.0-beta.14280

package/dist/lib/config.js

@@ -1,8 +1,10 @@
 /**
  * CLI config — reads PRODUCTBRAIN_API_KEY + CONVEX_SITE_URL from:
- * 1. Environment variables (always highest priority)
+ * 0. The profile a subagent's conversation names (conversationKeyProfile below)
+ * 1. Environment variables
  * 2. Project local config: .productbrain/config.local.json (walked up from CWD, machine-local)
- * 3. Project config: .productbrain/config.json (walked up from CWD, siteUrl only — committed)
+ * 3. Project config: .productbrain/config.json (walked up from CWD, committed) — its presence
+ *    declares a project; its siteUrl never routes a key (TEN-4500)
  * 4. Profile system (~/.config/productbrain/profiles/{name}.env)
  * 5. Legacy ~/.config/productbrain/.env (auto-migrated to profiles on first use)
  * 6. CWD .env.mcp / packages/mcp-server/.env.mcp / .env
@@ -12,134 +14,30 @@
  *
  * When key is missing and retry is provided (TTY), runs guided flow per docs/cli-unauthenticated-user-journey.md.
  *
- * Split config design:
- * - config.json (committed): siteUrl only — workspace gateway, safe to share with teammates.
- * - config.local.json (gitignored): profile pin — machine-local, never committed.
+ * The repo's own config files (.productbrain/config.json, config.local.json) are located and
+ * read by projectConfig.ts — this module turns what they declare into a credential.
  */
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync } from 'fs';
+import { writePrivateFile } from './privateFile.js';
 import { resolve } from 'path';
 import { homedir } from 'os';
-import { DEFAULT_SITE_URL, isDevMode } from './constants.js';
-import { API_KEY_PREFIX } from './tokenConstants.js';
+import { DEFAULT_SITE_URL } from './constants.js';
+import { API_KEY_FORMAT_LINE, isApiKeyShaped } from './tokenConstants.js';
+import { isEnvKeyBinding } from './envKeySnapshot.js';
 import { resolveProfileConfig, resolveNamedProfileConfig, getGlobalActiveProfile } from './profiles.js';
+import { findProjectRoot, readBoundPreviewKey, readLocalProjectConfig } from './projectConfig.js';
+import { declaresCompletePreviewBinding, refuseWhenProjectHasNoTenant, resolveLocalBinding, resolvePinnedProfile } from './localBinding.js';
 import { CLIError, ErrorCode } from './errors.js';
-import { confirm as promptConfirm, password as promptPassword } from './prompts.js';
+import { normalizeConversationId } from './conversation.js';
+import { ConfigResolutionError, isInsecureSiteUrl, missingKeyError, pickSiteUrl, resolveConfigResult, } from './configResult.js';
 const HOME_CONFIG_DIR = resolve(homedir(), '.config', 'productbrain');
 const HOME_ENV_PATH = resolve(HOME_CONFIG_DIR, '.env');
 const CWD_ENV_PATHS = ['.env.mcp', 'packages/mcp-server/.env.mcp', '.env'];
-// Short error when not TTY (scripts/pipes must not hang)
-const NON_TTY_MESSAGE = 'No API key. Set PRODUCTBRAIN_API_KEY or run pb login.';
 /** Track whether env has been loaded to avoid redundant file reads. */
 let envLoaded = false;
-/**
- * Walk up the directory tree (git-style) to find the nearest CLI project root.
- *
- * A `.productbrain/` directory only counts as a CLI project root when it carries
- * CLI configuration — `config.json` (committed siteUrl gateway) or
- * `config.local.json` (machine-local profile pin or preview binding). A
- * projection-only `.productbrain/` written by `pb handshake` (briefing.md,
- * context.md, rules/, etc.) does NOT count — otherwise a subrepo like
- * `packages/cli/.productbrain/` would shadow the real configuring root and
- * `npm run pb:preview` writes (which always land at the repo-root
- * `.productbrain/`) would be invisible to commands run from the subrepo.
- *
- * Stops at home directory or filesystem root. Returns the directory containing
- * a config-bearing `.productbrain/`, or null if not found.
- */
-export function findProjectRoot(startDir) {
-    let dir = startDir;
-    const home = homedir();
-    while (true) {
-        const pbDir = resolve(dir, '.productbrain');
-        if (existsSync(pbDir) &&
-            (existsSync(resolve(pbDir, 'config.json')) ||
-                existsSync(resolve(pbDir, 'config.local.json')))) {
-            return dir;
-        }
-        const parent = resolve(dir, '..');
-        if (parent === dir || dir === home)
-            return null;
-        dir = parent;
-    }
-}
-/**
- * Read .productbrain/config.json from the walked-up project root.
- * Only reads siteUrl — profile and apiKey fields are ignored (legacy or misplaced).
- * Returns null if file missing or project root not found.
- * Warns to stderr on invalid JSON but does not throw.
- */
-function readProjectConfig() {
-    const projectRoot = findProjectRoot(process.cwd());
-    if (!projectRoot)
-        return null;
-    const configPath = resolve(projectRoot, '.productbrain', 'config.json');
-    if (!existsSync(configPath))
-        return null;
-    try {
-        const raw = readFileSync(configPath, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-            process.stderr.write('Warning: .productbrain/config.json is not a JSON object, skipping.\n');
-            return null;
-        }
-        const result = {};
-        if (typeof parsed.siteUrl === 'string' && parsed.siteUrl) {
-            result.siteUrl = parsed.siteUrl;
-        }
-        // Silently ignore `profile` and `apiKey` in config.json — those must be in config.local.json
-        return result;
-    }
-    catch {
-        process.stderr.write('Warning: .productbrain/config.json contains invalid JSON, skipping.\n');
-        return null;
-    }
-}
-/**
- * Read .productbrain/config.local.json from the walked-up project root.
- * Returns the machine-local pin (`profile`) and any preview-binding fields
- * (`apiKey`, `siteUrl`, `preview`, `workspaceName`) written by
- * `npm run pb:preview` — all gitignored, never committed.
- * Returns null if file missing or project root not found.
- * Warns to stderr on invalid JSON but does not throw.
- */
-export function readLocalProjectConfig() {
-    const projectRoot = findProjectRoot(process.cwd());
-    if (!projectRoot)
-        return null;
-    const configPath = resolve(projectRoot, '.productbrain', 'config.local.json');
-    if (!existsSync(configPath))
-        return null;
-    try {
-        const raw = readFileSync(configPath, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-            process.stderr.write('Warning: .productbrain/config.local.json is not a JSON object, skipping.\n');
-            return null;
-        }
-        const result = {};
-        if (typeof parsed.profile === 'string' && parsed.profile) {
-            result.profile = parsed.profile;
-        }
-        // Preview binding fields — written by `npm run pb:preview`, cleared by `npm run pb:real`.
-        if (typeof parsed.apiKey === 'string' && parsed.apiKey.startsWith(API_KEY_PREFIX)) {
-            result.apiKey = parsed.apiKey;
-        }
-        if (typeof parsed.siteUrl === 'string' && parsed.siteUrl) {
-            result.siteUrl = parsed.siteUrl;
-        }
-        if (parsed.preview === true) {
-            result.preview = true;
-        }
-        if (typeof parsed.workspaceName === 'string' && parsed.workspaceName) {
-            result.workspaceName = parsed.workspaceName;
-        }
-        return result;
-    }
-    catch {
-        process.stderr.write('Warning: .productbrain/config.local.json contains invalid JSON, skipping.\n');
-        return null;
-    }
-}
+// Re-exported so callers keep importing the repo-config readers from here (they are part of
+// this module's long-standing public surface); the implementations live in projectConfig.ts.
+export { findProjectRoot, readLocalProjectConfig } from './projectConfig.js';
 /**
  * Returns the preview binding metadata when pb is currently bound to a throwaway preview,
  * or null when bound to the real Chain (the default).
@@ -161,11 +59,7 @@ export function getPreviewBinding() {
     try {
         if (process.env.PRODUCTBRAIN_API_KEY)
             return null;
-        const localConfig = readLocalProjectConfig();
-        if (localConfig?.preview === true && localConfig.apiKey && localConfig.siteUrl) {
-            return { workspaceName: localConfig.workspaceName ?? null };
-        }
-        return null;
+        return declaresCompletePreviewBinding(readLocalProjectConfig());
     }
     catch {
         return null;
@@ -178,7 +72,7 @@ export function getPreviewBinding() {
  *
  * Co-writer note (SF-2): scripts/pb-binding.mjs is the OTHER writer of config.local.json — it
  * merges/strips the preview-binding keys (apiKey, siteUrl, preview, workspaceName) for
- * `npm run pb:preview` / `npm run pb:real`. Both writers preserve the `profile` pin. If you add
+ * `npm run pb:preview` / `npm run pb:real`, plus previewKey*. Both writers keep the `profile` pin. If you add
  * a preview-scoped key here or in readLocalProjectConfig(), update pb-binding.mjs's PREVIEW_KEYS.
  */
 export function setLocalProfilePin(projectRoot, profile) {
@@ -194,22 +88,22 @@ export function setLocalProfilePin(projectRoot, profile) {
         catch { /* ignore parse errors — we overwrite the pin below */ }
     }
     mkdirSync(configDir, { recursive: true });
-    writeFileSync(localConfigPath, JSON.stringify({ ...existing, profile }, null, 2) + '\n');
+    writePrivateFile(localConfigPath, JSON.stringify({ ...existing, profile }, null, 2) + '\n'); // the file may hold a preview apiKey
 }
 /**
  * WP-458 E2 — one-shot preview apiKey refresh from disk.
  *
- * After a worktree preview is reseeded, seed-preview.mjs Step 6 mints a NEW apiKey into
- * `.productbrain/preview.json`, but `config.local.json` (and the live `process.env` binding it
+ * After a worktree preview is reseeded, seed-preview.mjs Step 6 mints a NEW apiKey into the bound key
+ * file the binding recorded (`previewKey`), but `config.local.json` (and the live `process.env` binding it
  * seeded via loadEnv) still carry the PRE-reseed key — so the next `pb session start` fails auth
- * with an opaque INTERNAL. This re-reads the fresh key from preview.json so the caller can retry
- * ONCE (session.ts). It is deliberately disk-to-disk: it compares preview.json's key against
+ * with an opaque INTERNAL. This re-reads the fresh key from that file so the caller can retry
+ * ONCE (session.ts). It is deliberately disk-to-disk: it compares that file's key against
  * config.local.json's bound key, NOT against process.env (which loadEnv already populated from the
  * stale binding), so it can't be confused by its own prior population. Never throws — any error
  * degrades to 'unavailable'/'not-bound' so it can sit on the session-start path.
  *
  * Co-writer note (SF-2): mirrors pb-binding.mjs / setLocalProfilePin — preserves every sibling key
- * in config.local.json (profile, preview, workspaceName) and only rewrites apiKey + siteUrl.
+ * in config.local.json (profile, preview, workspaceName, previewKey*) and only rewrites apiKey + siteUrl.
  */
 export function refreshPreviewApiKeyFromDisk() {
     try {
@@ -220,28 +114,18 @@ export function refreshPreviewApiKeyFromDisk() {
         // Only act on a real preview binding (preview:true + atomic apiKey+siteUrl pair, SF-3).
         if (!local?.preview || !local.apiKey || !local.siteUrl)
             return 'not-bound';
-        // Never clobber a genuine env override: if the live key is NOT the bound preview key, either
-        // the user exported their own PRODUCTBRAIN_API_KEY (env wins in resolveConfig) or a refresh
-        // already happened — bail either way. An unset env key is fine (loadEnv may not have run yet).
+        // Never clobber a genuine env override. BOTH signals: the value comparison misses an operator
+        // who exported the SAME key the binding holds (Codex P2 r12); the snapshot misses one set
+        // after module load. An unset key is fine — loadEnv may not have run yet.
         const liveKey = process.env.PRODUCTBRAIN_API_KEY;
-        if (liveKey && liveKey !== local.apiKey)
+        if (isEnvKeyBinding() || (liveKey && liveKey !== local.apiKey))
             return 'not-bound';
-        // Read the freshly-minted key from preview.json (seed-preview.mjs Step 6).
-        const previewPath = resolve(projectRoot, '.productbrain', 'preview.json');
-        if (!existsSync(previewPath))
-            return 'unavailable';
-        let fresh;
-        try {
-            const parsed = JSON.parse(readFileSync(previewPath, 'utf8'));
-            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
-                return 'unavailable';
-            fresh = parsed;
-        }
-        catch {
+        // Only the key file pb:preview bound, and only while it still names that person, workspace and seat (TEN-4883).
+        const fresh = local.previewKey ? readBoundPreviewKey(projectRoot, local.previewKey) : null;
+        if (!fresh)
             return 'unavailable';
-        }
         const freshKey = typeof fresh.apiKey === 'string' ? fresh.apiKey : '';
-        if (!freshKey.startsWith(API_KEY_PREFIX))
+        if (!isApiKeyShaped(freshKey))
             return 'unavailable';
         // Same key as the one already bound — retrying would just fail again; the failure is not a
         // stale key, so the caller surfaces the real error rather than relabelling it.
@@ -259,7 +143,7 @@ export function refreshPreviewApiKeyFromDisk() {
             }
             catch { /* overwrite below */ }
         }
-        writeFileSync(localConfigPath, JSON.stringify({ ...existing, apiKey: freshKey, siteUrl: freshSite }, null, 2) + '\n');
+        writePrivateFile(localConfigPath, JSON.stringify({ ...existing, apiKey: freshKey, siteUrl: freshSite }, null, 2) + '\n');
         // Update the live binding + drop the load cache so the next getConfig() uses the fresh key.
         process.env.PRODUCTBRAIN_API_KEY = freshKey;
         process.env.CONVEX_SITE_URL = freshSite.replace(/\/$/, '');
@@ -271,21 +155,40 @@ export function refreshPreviewApiKeyFromDisk() {
     }
 }
 /**
- * Resolve the effective profile NAME + where it came from. The SOURCE-PRECEDENCE
- * ORDER matches resolveConfig() (env > local pin > global > default), but unlike
- * resolveConfig() this reports the *configured* pin name even when that profile is
- * unresolvable (deleted / missing key). That divergence is intentional: a dangling
- * repo pin must be surfaced by `pb whoami`, not silently masked by the global
- * profile — masking it is the TEN-2163 silent-drift bug. Used by `pb whoami` and
- * the inline "now using" prints.
+ * The profile a subagent's conversation runs on (TASK-1177; DEC-2298): the session-start hook saves the profile's NAME, never
+ * a key, in ~/.config/productbrain/conversations/<conversation>, and removes it when the subagent stops. A subagent shares
+ * its parent's env, so only a pb command prefixed with the subagent's own PB_CONVERSATION_ID finds it; that command runs on
+ * the profile's key ahead of the parent's exported key, and one without the prefix stays on the parent's key. In the home
+ * folder, not the repo: a subagent works in another worktree than the one its hook ran in.
+ */
+export function conversationKeyProfile() {
+    const raw = process.env.PB_CONVERSATION_ID?.trim();
+    if (!raw)
+        return null;
+    try {
+        // Line 1 is the profile; line 2 is the hook's (the Claude process it clears the record by).
+        return readFileSync(resolve(HOME_CONFIG_DIR, 'conversations', normalizeConversationId(raw)), 'utf8').split('\n')[0].trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the effective profile NAME + where it came from. PRECEDENCE — local pin > env >
+ * global > default: the pin outranks `PB_PROFILE` because resolveConfig() 2b / loadEnv() 1b
+ * bind the pinned key before the profile system (the only step reading `PB_PROFILE`), so
+ * under both the env name never supplies the credential and must not be reported. Unlike
+ * resolveConfig() this names the *configured* pin even when unresolvable (deleted / missing
+ * key): a dangling pin must be surfaced by `pb whoami`, never masked by the global profile
+ * — the TEN-2163 silent-drift bug. Used by `pb whoami`, session labels, "now using" prints.
  */
 export function resolveEffectiveProfile() {
-    const envProfile = process.env.PB_PROFILE?.trim();
-    if (envProfile)
-        return { profile: envProfile, source: 'env' };
     const localProfile = readLocalProjectConfig()?.profile;
     if (localProfile)
         return { profile: localProfile, source: 'local' };
+    const envProfile = process.env.PB_PROFILE?.trim();
+    if (envProfile)
+        return { profile: envProfile, source: 'env' };
     const globalProfile = getGlobalActiveProfile();
     if (globalProfile)
         return { profile: globalProfile, source: 'global' };
@@ -296,25 +199,43 @@ export function resolveEffectiveProfile() {
 /**
  * Run the full config resolution cascade and return a typed result.
  * Resolution order:
- * 1. Environment variables (highest priority)
+ * 0. The profile this subagent's conversation names (highest priority; it holds no key of its own)
+ * 1. Environment variables
  * 2. config.local.json profile → resolveNamedProfileConfig(profile) for apiKey + siteUrl
- * 2b. config.json siteUrl (gateway override only — no apiKey, no profile)
+ * 2c. Declared project naming no tenant — refuses (config.json names neither a tenant nor a gateway)
  * 3. Profile system (~/.config/productbrain/profiles/{name}.env)
  * 4. Legacy home config (~/.config/productbrain/.env)
  * 5. CWD .env files (.env.mcp, packages/mcp-server/.env.mcp, .env)
  *
- * siteUrl always has a value (falls back to DEFAULT_SITE_URL).
+ * A key travels only with the site URL stored or exported beside it (TEN-4500): every branch
+ * reads its URL from the same source as its key, and a key with no URL of its own goes to
+ * DEFAULT_SITE_URL. `.productbrain/config.json` is committed, so a cloned repo controls its
+ * siteUrl; it never routes a key. Same rule as resolveAdminConfig() (TEN-1334). loadEnv()
+ * exports this function's answer, so `pb doctor` and the command path cannot name different
+ * hosts. `siteUrlSource` records which source supplied the URL.
+ *
+ * THROWS at step 2 rather than substituting a different workspace: CONFIG_INVALID at 2a
+ * (incomplete binding), AUTH_MISSING at 2b (dangling pin), missing-pin at 2c. getConfigSafe()
+ * reports each as `ok: false` with the kind preserved, for callers that must not crash.
  */
-export function resolveConfig() {
-    // 1. Env vars — check directly, don't mutate process.env
-    const envKey = process.env.PRODUCTBRAIN_API_KEY;
+export function resolveConfig(ignoreEnvKey = false) {
+    // 0. A subagent's own role key: never fall back to the parent's key when the named profile is broken.
+    const keyProfile = conversationKeyProfile();
+    if (keyProfile) {
+        const named = resolveNamedProfileConfig(keyProfile);
+        if (!named?.apiKey || !isApiKeyShaped(named.apiKey)) {
+            throw new ConfigResolutionError(`This conversation runs on profile ${keyProfile}, which holds no valid key.`, {
+                code: ErrorCode.AUTH_MISSING, category: 'auth', kind: 'profile-pin',
+                nextCommand: `pb profile create ${keyProfile}`, guidance: `Save the agent's key again: pb profile create ${keyProfile}.`,
+            });
+        }
+        return { apiKey: named.apiKey, source: 'profile', profileName: keyProfile, ...pickSiteUrl([['profile', named.siteUrl]]) };
+    }
+    // 1. Env vars. `ignoreEnvKey`: reporting-only seam, rationale at its call site (TEN-3311).
+    const envKey = ignoreEnvKey ? undefined : process.env.PRODUCTBRAIN_API_KEY;
     const envSite = process.env.CONVEX_SITE_URL;
     if (envKey) {
-        return {
-            apiKey: envKey,
-            siteUrl: (envSite || DEFAULT_SITE_URL).replace(/\/$/, ''),
-            source: 'env',
-        };
+        return { apiKey: envKey, source: 'env', ...pickSiteUrl([['env', envSite]]) };
     }
     // 2. Local project config — check for direct preview binding first, then profile pin.
     const localConfig = readLocalProjectConfig();
@@ -325,39 +246,35 @@ export function resolveConfig() {
     //
     // Atomic apiKey+siteUrl (SF-3): only honor the preview key when its OWN siteUrl is present.
     // Never let a preview key borrow config.json's (real-dev) siteUrl — that would send a
-    // preview credential to a non-preview gateway (STD-261). If siteUrl is absent we skip this
-    // branch and fall through to the profile pin / default, so it is impossible by construction
-    // for a `preview:true` key to be paired with the committed real-dev gateway.
-    if (localConfig?.apiKey && localConfig.siteUrl) {
+    // preview credential to a non-preview gateway (STD-261). A claimed but incomplete binding
+    // refuses before the profile pin, so neither credential nor tenant can silently change.
+    const localBinding = resolveLocalBinding(localConfig);
+    if (localBinding) {
+        // The binding carries its own atomic siteUrl (SF-3), so it is also the URL's origin.
         return {
-            apiKey: localConfig.apiKey,
-            siteUrl: localConfig.siteUrl.replace(/\/$/, ''),
+            apiKey: localBinding.apiKey,
+            siteUrl: localBinding.siteUrl,
             source: 'project',
+            siteUrlSource: 'local-binding',
         };
     }
     // 2b. Profile pin (config.local.json profile field, gitignored)
     if (localConfig?.profile) {
-        const namedConfig = resolveNamedProfileConfig(localConfig.profile);
-        if (namedConfig?.apiKey) {
-            // siteUrl: local.profile.siteUrl || config.json.siteUrl || env || default
-            const projectConfig = readProjectConfig();
-            return {
-                apiKey: namedConfig.apiKey,
-                siteUrl: (namedConfig.siteUrl || projectConfig?.siteUrl || envSite || DEFAULT_SITE_URL).replace(/\/$/, ''),
-                source: 'project',
-            };
-        }
+        const pinned = resolvePinnedProfile(localConfig.profile);
+        return {
+            apiKey: pinned.apiKey,
+            source: 'project', profileName: localConfig.profile,
+            ...pickSiteUrl([['profile-pin', pinned.siteUrl]]),
+        };
     }
-    // 2b. config.json — siteUrl gateway override only (no apiKey, no profile)
-    // Falls through; siteUrl from config.json is used as a tiebreaker below in step 3.
+    refuseWhenProjectHasNoTenant(); // 2c — declared project, no tenant named
     // 3. Profile system
-    const projectConfig = readProjectConfig();
     const profileConfig = resolveProfileConfig();
     if (profileConfig?.apiKey) {
         return {
             apiKey: profileConfig.apiKey,
-            siteUrl: (projectConfig?.siteUrl || profileConfig.siteUrl || envSite || DEFAULT_SITE_URL).replace(/\/$/, ''),
-            source: 'profile',
+            source: 'profile', profileName: profileConfig.profileName ?? undefined,
+            ...pickSiteUrl([['profile', profileConfig.siteUrl]]),
         };
     }
     // 4. Legacy home config
@@ -366,8 +283,8 @@ export function resolveConfig() {
         if (vars['PRODUCTBRAIN_API_KEY']) {
             return {
                 apiKey: vars['PRODUCTBRAIN_API_KEY'],
-                siteUrl: (projectConfig?.siteUrl || vars['CONVEX_SITE_URL'] || envSite || DEFAULT_SITE_URL).replace(/\/$/, ''),
                 source: 'profile',
+                ...pickSiteUrl([['legacy', vars['CONVEX_SITE_URL']]]),
             };
         }
     }
@@ -379,29 +296,18 @@ export function resolveConfig() {
             if (vars['PRODUCTBRAIN_API_KEY']) {
                 return {
                     apiKey: vars['PRODUCTBRAIN_API_KEY'],
-                    siteUrl: (projectConfig?.siteUrl || vars['CONVEX_SITE_URL'] || envSite || DEFAULT_SITE_URL).replace(/\/$/, ''),
                     source: 'cwd',
+                    ...pickSiteUrl([['cwd', vars['CONVEX_SITE_URL'], p]]),
                 };
             }
             break;
         }
     }
-    // 6. No API key found anywhere — return with siteUrl default
-    const resolvedSiteUrl = (projectConfig?.siteUrl || envSite || DEFAULT_SITE_URL).replace(/\/$/, '');
-    // TEN-2382: the published CLI's prod default is intended (WP-301), so we do NOT
-    // warn on prod fall-through in general. The ONE exception is the preview-scrub
-    // misroute — a preview binding whose apiKey is present but whose siteUrl was
-    // scrubbed (the STD-261 atomic guard at step 2a dropped the key), now silently
-    // resolving to the production gateway. That single case is a real misroute.
-    if (localConfig?.apiKey && resolvedSiteUrl === DEFAULT_SITE_URL.replace(/\/$/, '')) {
-        process.stderr.write(`Warning: a preview API key is configured but its deployment URL is missing — ` +
-            `defaulting to the production gateway ${DEFAULT_SITE_URL}. Run ` +
-            `\`npm run pb:preview\` to rebind the preview, or set CONVEX_SITE_URL.\n`);
-    }
+    // 6. No API key found anywhere — siteUrl still resolves so diagnostics can report a gateway.
     return {
         apiKey: undefined,
-        siteUrl: resolvedSiteUrl,
         source: 'default',
+        ...pickSiteUrl([['env', envSite]]),
     };
 }
 /** Parse env file content and return key-value pairs (without mutating process.env). */
@@ -426,53 +332,21 @@ function parseEnvContent(content) {
 function loadEnv() {
     if (envLoaded)
         return;
-    envLoaded = true;
-    // 1. Try local project config first (preview binding or profile pin, config.local.json)
-    const localConfig = readLocalProjectConfig();
-    // 1a. Direct preview binding — set by `npm run pb:preview`, takes priority over profile pin.
-    // Atomic apiKey+siteUrl (SF-3): only bind the preview key when its OWN siteUrl is present —
-    // never let it fall through to config.json's (real-dev) siteUrl (STD-261). Mirror of the
-    // resolveConfig() 2a guard so loadEnv() and resolveConfig() agree on what counts as a binding.
-    if (localConfig?.apiKey && localConfig.siteUrl && !process.env.PRODUCTBRAIN_API_KEY) {
-        process.env.PRODUCTBRAIN_API_KEY = localConfig.apiKey;
-        // SF-3 atomic pair: when we accept the preview key, we MUST pair it with
-        // its OWN siteUrl — even if CONVEX_SITE_URL is already exported. Otherwise
-        // a stale/real exported CONVEX_SITE_URL would silently route the preview
-        // credential to a non-preview gateway. Mirror of resolveConfig() step 2a,
-        // which returns localConfig.siteUrl unconditionally inside this branch.
-        process.env.CONVEX_SITE_URL = localConfig.siteUrl.replace(/\/$/, '');
-    }
-    // 1b. Profile pin
-    if (localConfig?.profile && !process.env.PRODUCTBRAIN_API_KEY) {
-        const namedConfig = resolveNamedProfileConfig(localConfig.profile);
-        if (namedConfig?.apiKey) {
-            process.env.PRODUCTBRAIN_API_KEY = namedConfig.apiKey;
-            if (!process.env.CONVEX_SITE_URL && namedConfig.siteUrl) {
-                process.env.CONVEX_SITE_URL = namedConfig.siteUrl.replace(/\/$/, '');
-            }
-        }
-    }
-    // 1b. Apply siteUrl from config.json (gateway override — no apiKey reading here)
-    const projectConfig = readProjectConfig();
-    if (projectConfig?.siteUrl && !process.env.CONVEX_SITE_URL) {
-        process.env.CONVEX_SITE_URL = projectConfig.siteUrl.replace(/\/$/, '');
-    }
-    // 2. Try profile system (handles auto-migration from legacy .env)
-    const profileConfig = resolveProfileConfig();
-    if (profileConfig) {
-        // Only set if not already set by env vars or project config
-        if (!process.env.PRODUCTBRAIN_API_KEY) {
-            process.env.PRODUCTBRAIN_API_KEY = profileConfig.apiKey;
-        }
-        if (!process.env.CONVEX_SITE_URL && profileConfig.siteUrl) {
-            process.env.CONVEX_SITE_URL = profileConfig.siteUrl.replace(/\/$/, '');
-        }
+    // 1. The credential and its site URL come from resolveConfig() as one pair, so the URL a key
+    // is sent to is decided in one place and `pb doctor` (getConfigSafe) names the same host this
+    // exports (TEN-4500). resolveConfig() throws the same refusals this path must raise: an
+    // incomplete preview binding, a dangling pin, a declared project with no pin.
+    const resolved = resolveConfig();
+    if (resolved.apiKey) {
+        process.env.PRODUCTBRAIN_API_KEY = resolved.apiKey;
+        process.env.CONVEX_SITE_URL = resolved.siteUrl;
     }
-    // 3. Legacy home config (in case profiles didn't find it)
+    // 2. The legacy home file and the first CWD env file still seed any OTHER unset variable they
+    // hold. They cannot move the pair above: both variables are already set whenever a key
+    // resolved, and when none did, resolveConfig() already read these files and found no key.
     if (existsSync(HOME_ENV_PATH)) {
         parseEnvContent(readFileSync(HOME_ENV_PATH, 'utf8'));
     }
-    // 4. CWD env files
     for (const p of CWD_ENV_PATHS) {
         const full = resolve(process.cwd(), p);
         if (existsSync(full)) {
@@ -480,79 +354,35 @@ function loadEnv() {
             break;
         }
     }
+    // Marked loaded only on success: a dangling pin (step 1) throws, and latching the flag
+    // before that would leave the module "loaded" with no credential, so a caller that catches
+    // the refusal and retries would silently get the keyless path instead of the refusal again.
+    envLoaded = true;
 }
 /** Reset env loaded state — used for profile switching. */
 export function resetConfigCache() {
     envLoaded = false;
 }
-/**
- * Guided flow when key is missing (TTY only). Per docs/cli-unauthenticated-user-journey.md.
- * Returns true if we saved and ran retry; false if user said No (caller should exit).
- */
-async function runGuidedFlow(retry) {
-    const hasKey = await promptConfirm({
-        message: 'Do you have an API key from Product Brain?',
-        initialValue: false,
-    });
-    if (!hasKey) {
-        console.log('Get your key: Product Brain app → Settings → API Keys. Then run: pb login');
-        process.exit(0);
-    }
-    let apiKey = await promptPassword({
-        message: `Paste your API key (${API_KEY_PREFIX}...)`,
-        validate: (v) => (!v ? 'Key is required' : undefined),
-    });
-    if (!apiKey.startsWith(API_KEY_PREFIX)) {
-        console.log(`Key must start with ${API_KEY_PREFIX}. Try again or run pb login.`);
-        apiKey = await promptPassword({
-            message: `Paste your API key (${API_KEY_PREFIX}...)`,
-            validate: (v) => (!v || !v.startsWith(API_KEY_PREFIX) ? `Key must start with ${API_KEY_PREFIX}` : undefined),
-        });
-    }
-    if (!apiKey || !apiKey.startsWith(API_KEY_PREFIX)) {
-        console.log('Get your key: Product Brain app → Settings → API Keys. Then run: pb login');
-        process.exit(0);
-    }
-    // Save as a named profile via the profile system
-    const { createProfile, getActiveProfile } = await import('./profiles.js');
-    const profileName = getActiveProfile() || 'default';
-    try {
-        createProfile(profileName, apiKey, DEFAULT_SITE_URL.replace(/\/$/, ''));
-    }
-    catch {
-        // Profile already exists — fall back to legacy path
-        const content = [
-            `# Product Brain CLI — saved by guided setup`,
-            `PRODUCTBRAIN_API_KEY=${apiKey}`,
-            `CONVEX_SITE_URL=${DEFAULT_SITE_URL.replace(/\/$/, '')}`,
-            '',
-        ].join('\n');
-        mkdirSync(HOME_CONFIG_DIR, { recursive: true });
-        writeFileSync(HOME_ENV_PATH, content, { mode: 0o600 });
-    }
-    process.env.PRODUCTBRAIN_API_KEY = apiKey;
-    process.env.CONVEX_SITE_URL = DEFAULT_SITE_URL.replace(/\/$/, '');
-    console.log('Saved your key. Running your command…\n');
-    await retry();
-    return true;
-}
 export function getConfig() {
     loadEnv();
     const apiKey = process.env.PRODUCTBRAIN_API_KEY ?? '';
     const siteUrl = (process.env.CONVEX_SITE_URL ?? DEFAULT_SITE_URL).replace(/\/$/, '');
-    if (!apiKey || !apiKey.startsWith(API_KEY_PREFIX)) {
-        throw new CLIError(NON_TTY_MESSAGE, {
+    // TASK-562: no key throws the one missing-key sentence getConfigSafe reports (configResult.ts).
+    if (!apiKey)
+        throw missingKeyError();
+    if (!isApiKeyShaped(apiKey)) {
+        throw new CLIError(API_KEY_FORMAT_LINE, {
             code: ErrorCode.AUTH_MISSING,
             category: 'auth',
-            guidance: 'Set PRODUCTBRAIN_API_KEY or run `pb login`.',
+            guidance: 'Run `pb doctor` to see which source supplied it.',
         });
     }
-    const allowHttp = isDevMode() && siteUrl.startsWith('http://localhost');
-    if (!siteUrl.startsWith('https://') && !allowHttp) {
-        throw new CLIError(`CONVEX_SITE_URL must use HTTPS (got "${siteUrl.slice(0, 30)}…"). API keys must not be sent over unencrypted connections.`, {
+    if (isInsecureSiteUrl(siteUrl)) {
+        // loadEnv() exports a file-sourced URL into CONVEX_SITE_URL, so only `pb doctor` can name the origin.
+        throw new CLIError(`Site URL must use HTTPS (got "${siteUrl.slice(0, 30)}…"). API keys must not be sent over unencrypted connections.`, {
             code: ErrorCode.CONFIG_INVALID,
             category: 'config',
-            guidance: 'Set CONVEX_SITE_URL to an https:// URL.',
+            guidance: 'Run `pb doctor` to see which source supplied the URL, then set an https:// URL there.',
         });
     }
     return { apiKey, siteUrl };
@@ -567,103 +397,25 @@ export function getConfig() {
  * coexist by design — see WP-303 review (DW#5).
  *
  * Uses resolveConfig() directly (no loadEnv) to avoid env var pollution affecting source attribution.
+ *
+ * A refusal from resolveConfig() (dangling repo pin) is reported as `ok: false` with the
+ * refusal as the reason — NOT rethrown. This surface is what `pb doctor` and the bare-`pb`
+ * dashboard use to *diagnose*, and a diagnostic that dies on the condition it exists to
+ * explain is useless. The refusal keeps its teeth either way: `ok: false` hands out no
+ * credential, so nothing can proceed against the wrong workspace.
  */
 export function getConfigSafe() {
-    const resolved = resolveConfig();
-    if (!resolved.apiKey || !resolved.apiKey.startsWith(API_KEY_PREFIX)) {
-        return { ok: false, reason: 'No API key. Run pb login or set PRODUCTBRAIN_API_KEY.' };
-    }
-    const siteUrl = resolved.siteUrl;
-    const allowHttp = isDevMode() && siteUrl.startsWith('http://localhost');
-    if (!siteUrl.startsWith('https://') && !allowHttp) {
-        return {
-            ok: false,
-            reason: `CONVEX_SITE_URL must use HTTPS (got "${siteUrl.slice(0, 30)}…"). API keys must not be sent over unencrypted connections.`,
-        };
-    }
-    return { ok: true, apiKey: resolved.apiKey, siteUrl, source: resolved.source };
-}
-/**
- * Get config; if key is missing and stdin is a TTY, run guided flow (y/n → paste key → save → retry).
- * @param retry Called after saving key so the original command runs in-process.
- * @returns Config, or null if we ran retry (caller should return without running again).
- */
-export async function getConfigOrGuide(retry) {
-    loadEnv();
-    const apiKey = process.env.PRODUCTBRAIN_API_KEY ?? '';
-    const siteUrl = (process.env.CONVEX_SITE_URL ?? DEFAULT_SITE_URL).replace(/\/$/, '');
-    const allowHttp = isDevMode() && siteUrl.startsWith('http://localhost');
-    if (apiKey.startsWith(API_KEY_PREFIX) && (siteUrl.startsWith('https://') || allowHttp)) {
-        return { apiKey, siteUrl };
-    }
-    if (!process.stdin.isTTY) {
-        throw new CLIError(NON_TTY_MESSAGE, {
-            code: ErrorCode.AUTH_MISSING,
-            category: 'auth',
-            guidance: 'Set PRODUCTBRAIN_API_KEY or run `pb login`.',
-        });
-    }
-    const didRetry = await runGuidedFlow(retry);
-    return didRetry ? null : null;
+    return resolveConfigResult(resolveConfig);
 }
 /**
- * Resolve config for admin operations — profile-only resolution.
- *
- * Admin commands (pb admin ...) must NOT read .productbrain/config.json or CWD env files.
- * The project config intentionally pins the repo to a dev Convex site; admin operations
- * target PROD workspaces via the operator's active profile. Reading project config here
- * would silently route admin calls to the wrong gateway (TEN-1334).
- *
- * Resolution order:
- * 1. Shell env vars (PRODUCTBRAIN_API_KEY / CONVEX_SITE_URL) — always win
- * 2. Active named profile (~/.config/productbrain/profiles/{name}.env)
- * 3. Legacy home config (~/.config/productbrain/.env)
- * 4. DEFAULT_SITE_URL as fallback for siteUrl
- *
- * Throws CLIError with AUTH_MISSING if no API key is found.
+ * Get config for a command that needs auth. TASK-562: the paste-a-key guided flow is deleted; a
+ * missing key throws the same missing-key sentence as getConfig, in a TTY too (connect, never paste).
  */
-export function resolveAdminConfig() {
-    let apiKey;
-    let rawSiteUrl;
-    // 1. Shell env vars — always highest priority
-    const envKey = process.env.PRODUCTBRAIN_API_KEY;
-    if (envKey?.startsWith(API_KEY_PREFIX)) {
-        apiKey = envKey;
-        rawSiteUrl = process.env.CONVEX_SITE_URL;
-    }
-    // 2. Active profile (no project config, no CWD files)
-    if (!apiKey) {
-        const profileConfig = resolveProfileConfig();
-        if (profileConfig?.apiKey?.startsWith(API_KEY_PREFIX)) {
-            apiKey = profileConfig.apiKey;
-            rawSiteUrl = profileConfig.siteUrl;
-        }
-    }
-    // 3. Legacy ~/.config/productbrain/.env
-    if (!apiKey && existsSync(HOME_ENV_PATH)) {
-        const vars = parseEnvVars(readFileSync(HOME_ENV_PATH, 'utf8'));
-        if (vars['PRODUCTBRAIN_API_KEY']?.startsWith(API_KEY_PREFIX)) {
-            apiKey = vars['PRODUCTBRAIN_API_KEY'];
-            rawSiteUrl = vars['CONVEX_SITE_URL'];
-        }
-    }
-    if (!apiKey) {
-        throw new CLIError('No API key found. Run pb login or set PRODUCTBRAIN_API_KEY.', {
-            code: ErrorCode.AUTH_MISSING,
-            category: 'auth',
-            guidance: 'Run `pb login` to set your API key.',
-        });
-    }
-    const siteUrl = (rawSiteUrl || DEFAULT_SITE_URL).replace(/\/$/, '');
-    const allowHttp = isDevMode() && siteUrl.startsWith('http://localhost');
-    if (!siteUrl.startsWith('https://') && !allowHttp) {
-        throw new CLIError(`CONVEX_SITE_URL must use HTTPS for admin operations (got "${siteUrl.slice(0, 30)}…").`, {
-            code: ErrorCode.CONFIG_INVALID,
-            category: 'config',
-            guidance: 'Set CONVEX_SITE_URL to an https:// URL.',
-        });
-    }
-    return { apiKey, siteUrl };
+export async function getConfigOrGuide() {
+    return getConfig();
 }
-export { HOME_CONFIG_DIR, HOME_ENV_PATH, readProjectConfig };
+// resolveAdminConfig() lives in adminConfig.ts (WP-681: split out to stay under the 500-LOC
+// budget). NOT re-exported here — that would be a circular import (adminConfig.ts imports
+// readLocalProjectConfig/HOME_ENV_PATH from this file); every caller imports it directly.
+export { HOME_CONFIG_DIR, HOME_ENV_PATH };
 //# sourceMappingURL=config.js.map