@vanillagreen/pi-claude-bridge 2.0.0 → 3.2.2

package/src/bridge-state.ts

@@ -1,12 +1,35 @@
 import { type ExtensionAPI, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
-import { debug, diagDump, diagLogPath } from "./debug.js";
+import { debug, diagDump, diagGuidance } from "./debug.js";
 import { type QueryContext } from "./query-state.js";
+import { currentRequestLaneId } from "./request-lane.js";
 import { summarizeMissingToolNames, type MissingToolResult } from "./tool-pairing-audit.js";
 
 export interface SessionState {
 	sessionId: string;
 	cursor: number;
 	cwd: string;
+	// Claude Code session files and resume IDs are credential-profile scoped.
+	// Missing values mean the legacy/default Claude profile (process env rules).
+	// `claudeConfigDir` is the RESOLVED dir (see claudeDirForProfile) and is
+	// in-memory only — persistence strips it and keeps just the opaque profile
+	// id, re-deriving the dir through the router on restore.
+	accountProfileId?: string;
+	claudeConfigDir?: string;
+	// Identity anchor of the pi conversation this record belongs to, encoded
+	// component-wise as `u:<12hex>` or `u:<12hex>|a:<12hex>` (see
+	// conversationFingerprint in session-persistence.ts): a short sha256 of the
+	// FIRST user message's normalized text, plus — once the conversation has
+	// one — of the FIRST assistant message's normalized text. Pi histories
+	// never rewrite those opening messages — compact/tree-nav mutations set
+	// needsRebuild instead — so a component mismatch marks a FOREIGN
+	// conversation (a subagent-shaped query arriving while the parent is idle,
+	// vstack#1001) that must run as a clean one-shot without touching this
+	// record. The user component must always match; the assistant component is
+	// compared only when BOTH sides carry one, so a record stamped on turn 1
+	// (no assistant yet) still matches its own grown conversation and upgrades
+	// to the two-component form on the next REUSE. Absent on records restored
+	// from pre-3.1.1 markers → identity unknown, pre-fingerprint behavior.
+	conversationFingerprint?: string;
 	// Force the next syncSharedSession call down the REBUILD path. Set when
 	// pi has mutated its messages array out from under us (compact, tree
 	// navigation) or after an abort left the JSONL in an indeterminate state.
@@ -23,16 +46,101 @@ export interface SessionState {
 	forceRotate?: boolean;
 }
 
-// Shared mutable bridge state. Lives in its own module so the extracted
-// modules and index.ts observe the SAME state: ESM live bindings let every
-// importer READ these `let` bindings live, but only this module may assign
-// them — cross-module writes must go through the setters below.
-export let sharedSession: SessionState | null = null;
+// Claude session state is scoped to Pi's provider `sessionId`. Parent and child
+// agents can load separate copies of the extension module while sharing the
+// primary provider closure, so the lane registry must live on globalThis rather
+// than in one module instance. The versioned symbol prevents an incompatible
+// future store shape from being mistaken for this one.
+interface SharedSessionLaneStoreV1 {
+	defaultSession: SessionState | null;
+	sessions: Map<string, SessionState | null>;
+}
+
+const SHARED_SESSION_LANES_SYMBOL = Symbol.for("vstack.pi.claude-bridge.shared-session-lanes.v1");
+
+function sharedSessionLaneStore(): SharedSessionLaneStoreV1 {
+	const host = globalThis as Record<symbol, unknown>;
+	let store = host[SHARED_SESSION_LANES_SYMBOL] as SharedSessionLaneStoreV1 | undefined;
+	if (!store) {
+		store = { defaultSession: null, sessions: new Map() };
+		host[SHARED_SESSION_LANES_SYMBOL] = store;
+	}
+	return store;
+}
+
 export let extensionApi: ExtensionAPI | undefined;
 export let piUI: ExtensionUIContext | undefined;
 
+export function getSharedSession(): SessionState | null {
+	const store = sharedSessionLaneStore();
+	const sessionId = currentRequestLaneId();
+	return sessionId === undefined
+		? store.defaultSession
+		: (store.sessions.get(sessionId) ?? null);
+}
+
 export function setSharedSession(next: SessionState | null): void {
-	sharedSession = next;
+	const store = sharedSessionLaneStore();
+	const sessionId = currentRequestLaneId();
+	if (sessionId === undefined) store.defaultSession = next;
+	else store.sessions.set(sessionId, next);
+}
+
+export function deleteSharedSessionLane(sessionId: string | undefined): void {
+	const store = sharedSessionLaneStore();
+	if (sessionId === undefined) store.defaultSession = null;
+	else store.sessions.delete(sessionId);
+}
+
+export function clearSharedSessionLanes(): void {
+	const store = sharedSessionLaneStore();
+	store.sessions.clear();
+	store.defaultSession = null;
+}
+
+// The lane each pi session started in, keyed by its SessionManager. An in-memory
+// session (`pi --no-session`) forks by mutating the SAME SessionManager's id
+// before session_shutdown fires, so the live id there names the fork rather than
+// the session being torn down, and the fallback to it would prune a live
+// sibling. Keyed per manager (not one slot) so overlapping parent/child
+// session_start events keep their own entries, and on globalThis like the
+// registry above because session_start and session_shutdown can reach different
+// module instances (`/reload` mid-session, a child agent's own copy) and both
+// must see the same entry.
+const STARTED_LANES_SYMBOL = Symbol.for("vstack.pi.claude-bridge.started-lanes.v1");
+
+function startedLaneStore(): WeakMap<object, string> {
+	const host = globalThis as Record<symbol, unknown>;
+	let store = host[STARTED_LANES_SYMBOL] as WeakMap<object, string> | undefined;
+	if (!store) {
+		store = new WeakMap<object, string>();
+		host[STARTED_LANES_SYMBOL] = store;
+	}
+	return store;
+}
+
+export function recordStartedLane(sessionManager: object, sessionId: string): void {
+	startedLaneStore().set(sessionManager, sessionId);
+}
+
+/** The lane recorded at this manager's session_start, removed as it is read —
+ *  one shutdown per start. Undefined when no start was recorded (the caller
+ *  falls back to the manager's live id). */
+export function takeStartedLane(sessionManager: object): string | undefined {
+	const store = startedLaneStore();
+	const sessionId = store.get(sessionManager);
+	store.delete(sessionManager);
+	return sessionId;
+}
+
+/** Force the next syncSharedSession down the REBUILD path (no-op without a
+ *  session). `forceRotate` additionally rotates the session UUID — set it when
+ *  a concurrent CC writer may still be flushing (abort, idle kill); see the
+ *  field docs on SessionState. */
+export function markSessionForRebuild(opts: { forceRotate?: boolean } = {}): void {
+	const sharedSession = getSharedSession();
+	if (!sharedSession) return;
+	setSharedSession({ ...sharedSession, needsRebuild: true, ...(opts.forceRotate ? { forceRotate: true } : {}) });
 }
 
 export function setExtensionApi(next: ExtensionAPI | undefined): void {
@@ -110,7 +218,7 @@ export function reportSyntheticToolResultRepair(missing: MissingToolResult[], co
 		safeNotify(
 			`Claude bridge: ${missing.length} missing tool result(s) repaired with an explicit error placeholder` +
 			`${toolNameSummary.length ? ` for ${toolNameSummary.join(", ")}` : ""}. ` +
-			`Real tool output was lost before Claude session import; see ${diagLogPath()}.`,
+			`Real tool output was lost before Claude session import; ${diagGuidance()}.`,
 			"error",
 		);
 	} catch (error) {
@@ -118,7 +226,12 @@ export function reportSyntheticToolResultRepair(missing: MissingToolResult[], co
 	}
 }
 
-export function reportToolResultMismatch(queryCtx: QueryContext, reason: string, cwd: string | undefined, opts: { forceRotate?: boolean } = {}): boolean {
+export function reportToolResultMismatch(
+	queryCtx: QueryContext,
+	reason: string,
+	cwd: string | undefined,
+	opts: { expectedInterruption?: boolean; forceRotate?: boolean } = {},
+): boolean {
 	try {
 		if (queryCtx.reportedToolResultMismatch) return false;
 		const progress = queryCtx.toolResultProgress();
@@ -127,15 +240,33 @@ export function reportToolResultMismatch(queryCtx: QueryContext, reason: string,
 			: progress.waitingCount > 0 || progress.queuedCount > 0 || progress.unmatchedResultCount > 0;
 		if (!hasMismatch) return false;
 		queryCtx.reportedToolResultMismatch = true;
-		if (sharedSession) {
-			sharedSession = { ...sharedSession, needsRebuild: true, ...(opts.forceRotate ? { forceRotate: true } : {}) };
+		// The single choke point every mismatch path funnels through (abort,
+		// unmatched result, stream-idle, teardown). A context with no claim on
+		// the shared record (reentrant subagent or foreign one-shot, vstack#1001)
+		// still gets the full diagnostics below, but its unresolved tool state is
+		// its own — marking the PARENT's record needsRebuild/forceRotate here
+		// would flush the parent's prompt cache for a query that never touched
+		// its session.
+		if (!queryCtx.detachedFromSharedSession) markSessionForRebuild(opts);
+		// A user abort interrupting in-flight tool calls is expected teardown, not
+		// an integrity fault: mark the rebuild but skip the diag dump and toast.
+		if (opts.expectedInterruption) {
+			debug(
+				`tool result delivery interrupted as expected during ${reason}; ` +
+				`delivered=${progress.deliveredCount}/${progress.expectedCount} ` +
+				`resolved=${progress.resolvedCount}/${progress.expectedCount} ` +
+				`waiting=${progress.waitingCount} queued=${progress.queuedCount}`,
+			);
+			return true;
 		}
 		const toolNameSummary = compactToolNameSummary(progress.toolNames);
+		const sharedSession = getSharedSession();
 		diagDump("tool_result_delivery_mismatch", {
 			reason,
 			cwd,
 			progress,
 			activeQueryExists: queryCtx.activeQuery !== null,
+			detachedFromSharedSession: queryCtx.detachedFromSharedSession,
 			sharedSession: sharedSession ? {
 				sessionId: sharedSession.sessionId.slice(0, 8),
 				cursor: sharedSession.cursor,
@@ -158,7 +289,9 @@ export function reportToolResultMismatch(queryCtx: QueryContext, reason: string,
 			`delivered ${progress.deliveredCount}/${progress.expectedCount}, resolved ${progress.resolvedCount}/${progress.expectedCount}, ` +
 			`waiting=${progress.waitingCount}, queued=${progress.queuedCount}, unmatched=${progress.unmatchedResultCount}` +
 			`${toolNameSummary.length ? `, tools=${toolNameSummary.join(", ")}` : ""}. ` +
-			`Claude session will rebuild before the next turn; see ${diagLogPath()}.`,
+			(queryCtx.detachedFromSharedSession
+				? `Detached one-shot query — shared Claude session record left untouched; ${diagGuidance()}.`
+				: `Claude session will rebuild before the next turn; ${diagGuidance()}.`),
 			"error",
 		);
 		return true;
@@ -170,9 +303,19 @@ export function reportToolResultMismatch(queryCtx: QueryContext, reason: string,
 
 export function __testSetBridgeIntegrityState(state: { ui?: Pick<ExtensionUIContext, "notify"> | null; sharedSession?: SessionState | null }): void {
 	if ("ui" in state) piUI = state.ui as ExtensionUIContext | undefined;
-	if ("sharedSession" in state) sharedSession = state.sharedSession ?? null;
+	if ("sharedSession" in state) {
+		if (currentRequestLaneId() !== undefined) setSharedSession(state.sharedSession ?? null);
+		else {
+			clearSharedSessionLanes();
+			sharedSessionLaneStore().defaultSession = state.sharedSession ?? null;
+		}
+	}
 }
 
 export function __testGetBridgeIntegrityState(): { sharedSession: SessionState | null } {
-	return { sharedSession };
+	return { sharedSession: getSharedSession() };
+}
+
+export function __testSharedSessionLaneCount(): number {
+	return sharedSessionLaneStore().sessions.size;
 }

package/src/config.ts

@@ -7,10 +7,18 @@
 import type { SettingSource } from "@anthropic-ai/claude-agent-sdk";
 import { existsSync, readFileSync } from "fs";
 import { homedir } from "os";
-import { dirname, join, resolve } from "path";
+import { dirname, join, resolve, sep } from "path";
+import { debug } from "./debug.js";
 
 export const PACKAGE_ID = "@vanillagreen/pi-claude-bridge";
 
+/**
+ * Registry the vstack extension manager reads to display the value an
+ * extension actually resolves for a manifest key, for extensions whose config
+ * has channels the manager does not own. Keyed by package id.
+ */
+const EXTERNAL_CONFIG_RESOLVER_SYMBOL = Symbol.for("vstack.pi.extension-config-resolver");
+
 export type BridgeEffortLevel = "low" | "medium" | "high" | "xhigh" | "max";
 
 const VALID_EFFORT_LEVELS = new Set<BridgeEffortLevel>(["low", "medium", "high", "xhigh", "max"]);
@@ -28,13 +36,20 @@ export interface Config {
 	/** Low-level Claude Agent SDK plumbing. Most users won't need these. */
 	provider?: {
 		appendSystemPrompt?: boolean;
-		allowExtraUsage?: boolean;
 		/** Enable Claude Code fast mode for bridge requests. */
 		fastMode?: boolean;
 		/** Force this Claude Code effort level for every bridge request. */
 		forceEffort?: BridgeEffortLevel;
 		/** Per-model Claude Code effort overrides keyed by model id (e.g. claude-opus-4-8). */
 		modelEffortOverrides?: Record<string, BridgeEffortLevel>;
+		/**
+		 * Verbatim override for the child's filesystem setting sources.
+		 * Defaults (see settingSourcesForQuery in connectors.ts): connectors
+		 * mode uses ["user"] only, so repo-controlled `.claude/settings.json`
+		 * (project/local scope) cannot inject `env`/`apiKeyHelper` into the
+		 * child. Listing "project"/"local" here reopens that surface — only do
+		 * so for checkouts you trust.
+		 */
 		settingSources?: SettingSource[];
 		strictMcpConfig?: boolean;
 		pathToClaudeCodeExecutable?: string;
@@ -43,7 +58,9 @@ export interface Config {
 		 * connectors (Gmail / Google Calendar / Google Drive, etc.) to the model.
 		 * Off by default so Pi owns tool execution and tokens stay lean. Also
 		 * settable via the CLAUDE_BRIDGE_ENABLE_CONNECTORS env var (env OR config
-		 * enables it). See docs/plans/claude-bridge-google-connectors.md.
+		 * enables it). Resolved from USER-scope config and env only — a project's
+		 * checked-in settings cannot enable it (see USER_SCOPE_ONLY_PROVIDER_KEYS).
+		 * See the Connectors section of this package's README.
 		 */
 		enableConnectors?: boolean;
 		/**
@@ -56,7 +73,8 @@ export interface Config {
 		 * one-shot approved-write executor process. Also settable via
 		 * CLAUDE_BRIDGE_CONNECTOR_WRITE=deny|allow (env wins over config). Any
 		 * value but exact `allow` is treated as `deny`. Ignored when connectors
-		 * are disabled.
+		 * are disabled. Like enableConnectors, resolved from USER-scope config
+		 * and env only (see USER_SCOPE_ONLY_PROVIDER_KEYS).
 		 */
 		connectorWriteMode?: ConnectorWriteMode;
 	};
@@ -178,29 +196,57 @@ export function tryParseJson(path: string): Partial<Config> {
 	if (!existsSync(path)) return {};
 	try {
 		return JSON.parse(readFileSync(path, "utf-8"));
-	} catch {
+	} catch (error) {
 		// Malformed optional config should not write raw terminal diagnostics;
-		// stdout/stderr output can corrupt active Pi TUI widgets.
+		// stdout/stderr output can corrupt active Pi TUI widgets. The debug log is
+		// the one place a silently-ignored file explains itself.
+		debug(`config: ignoring malformed ${path}:`, error instanceof Error ? error.message : String(error));
 		return {};
 	}
 }
 
 function readManagerConfig(cwd: string): SettingsRecord {
 	const merged: SettingsRecord = {};
+	const userPath = join(piUserDir(), "settings.json");
 	for (const path of settingsPaths(cwd)) {
 		if (!existsSync(path)) continue;
 		try {
 			const parsed = JSON.parse(readFileSync(path, "utf8"));
 			const configRoot = asRecord(asRecord(asRecord(parsed?.vstack)?.extensionManager)?.config);
 			const config = asRecord(configRoot?.[PACKAGE_ID]);
-			if (config) mergeDeep(merged, config);
-		} catch {
-			// Ignore malformed optional manager config; Pi will surface settings issues elsewhere.
+			if (config) mergeDeep(merged, path === userPath ? config : withoutUserScopeOnlyKeys(config));
+		} catch (error) {
+			// Ignore malformed optional manager config; Pi will surface settings
+			// issues elsewhere. Still say so in the debug log.
+			debug(`config: ignoring malformed manager config ${path}:`, error instanceof Error ? error.message : String(error));
 		}
 	}
 	return merged;
 }
 
+// Connector enablement and write mode decide whether the child claude gains
+// access to the account's live connectors (mail, calendar, files) and whether
+// their WRITE tools are exposed. A repo-controlled channel (a checkout's
+// `.pi/settings.json` or `.pi/claude-bridge.json`, even when the project is
+// trusted for ordinary options) must not be able to flip them: these two keys
+// resolve from USER scope and the env vars only, mirroring the
+// settingSourcesForQuery rationale — whoever writes user scope already owns
+// the process.
+const USER_SCOPE_ONLY_PROVIDER_KEYS = ["enableConnectors", "connectorWriteMode"] as const;
+
+function withoutUserScopeOnlyKeys(raw: SettingsRecord): SettingsRecord {
+	const out = { ...raw };
+	for (const key of USER_SCOPE_ONLY_PROVIDER_KEYS) delete out[key];
+	return out;
+}
+
+function stripUserScopeOnlyProviderKeys(config: Partial<Config>): Partial<Config> {
+	if (!config.provider) return config;
+	const provider = { ...config.provider };
+	for (const key of USER_SCOPE_ONLY_PROVIDER_KEYS) delete provider[key];
+	return { ...config, provider };
+}
+
 function boolFrom(raw: SettingsRecord, key: string): boolean | undefined {
 	return typeof raw[key] === "boolean" ? raw[key] as boolean : undefined;
 }
@@ -277,8 +323,6 @@ function managerToConfig(raw: SettingsRecord): Partial<Config> {
 
 	const appendSystemPrompt = boolFrom(raw, "appendSystemPrompt");
 	if (appendSystemPrompt !== undefined) provider.appendSystemPrompt = appendSystemPrompt;
-	const allowExtraUsage = boolFrom(raw, "allowExtraUsage");
-	if (allowExtraUsage !== undefined) provider.allowExtraUsage = allowExtraUsage;
 	const fastMode = boolFrom(raw, "fastMode");
 	if (fastMode !== undefined) provider.fastMode = fastMode;
 	if (hasOwn(raw, "forceEffort")) {
@@ -312,17 +356,123 @@ function managerToConfig(raw: SettingsRecord): Partial<Config> {
 	};
 }
 
+/**
+ * A `claude-bridge.json` file. Legacy files nest provider options under
+ * `provider` and prompt-context flags under `promptContext`; the manifest's flat
+ * key shape is accepted too, so a file written either way resolves the same.
+ * Nested wins when a file carries both shapes for one key.
+ */
+function legacyFileConfig(path: string): Partial<Config> {
+	const raw = asRecord(tryParseJson(path)) ?? {};
+	const flat = managerToConfig(raw);
+	const provider = { ...flat.provider, ...asRecord(raw.provider) } as Config["provider"];
+	const promptContext = { ...flat.promptContext, ...asRecord(raw.promptContext) } as Config["promptContext"];
+	return {
+		...(flat.enabled !== undefined ? { enabled: flat.enabled } : {}),
+		...(Object.keys(provider ?? {}).length ? { provider } : {}),
+		...(Object.keys(promptContext ?? {}).length ? { promptContext } : {}),
+	};
+}
+
+interface LegacyLayer {
+	path: string;
+	config: Partial<Config>;
+}
+
+/** Legacy config layers, lowest precedence first. */
+function legacyLayers(cwd: string): LegacyLayer[] {
+	const globalPath = join(piUserDir(), "claude-bridge.json");
+	const layers: LegacyLayer[] = [{ path: globalPath, config: legacyFileConfig(globalPath) }];
+	if (isolatedFromEnv()) return layers;
+	const projectSettings = projectSettingsPath(cwd);
+	if (!projectSettingsTrusted(projectSettings)) return layers;
+	const projectPath = join(dirname(projectSettings), "claude-bridge.json");
+	// Project trust covers ordinary options only; the connector keys stay
+	// user-scope/env (see USER_SCOPE_ONLY_PROVIDER_KEYS).
+	return [...layers, { path: projectPath, config: stripUserScopeOnlyProviderKeys(legacyFileConfig(projectPath)) }];
+}
+
+function mergeLayers(layers: LegacyLayer[]): Partial<Config> {
+	const merged: Partial<Config> = { provider: {}, promptContext: {} };
+	for (const layer of layers) {
+		if (layer.config.enabled !== undefined) merged.enabled = layer.config.enabled;
+		merged.provider = { ...merged.provider, ...layer.config.provider };
+		merged.promptContext = { ...merged.promptContext, ...layer.config.promptContext };
+	}
+	return merged;
+}
+
 export function loadConfig(cwd: string): Config {
-	const global = tryParseJson(join(piUserDir(), "claude-bridge.json"));
-	const isolated = isolatedFromEnv();
-	const projectSettings = isolated ? undefined : projectSettingsPath(cwd);
-	const trustedProject = projectSettings !== undefined && projectSettingsTrusted(projectSettings);
-	const project = trustedProject ? tryParseJson(join(dirname(projectSettings), "claude-bridge.json")) : {};
-	const manager: Partial<Config> = isolated ? {} : managerToConfig(readManagerConfig(cwd));
-	const provider = normalizeProviderConfig({ ...global.provider, ...project.provider, ...manager.provider });
+	const legacy = mergeLayers(legacyLayers(cwd));
+	const manager: Partial<Config> = isolatedFromEnv() ? {} : managerToConfig(readManagerConfig(cwd));
+	const provider = normalizeProviderConfig({ ...legacy.provider, ...manager.provider });
 	return {
-		enabled: manager.enabled ?? project.enabled ?? global.enabled ?? true,
+		enabled: manager.enabled ?? legacy.enabled ?? true,
 		provider,
-		promptContext: { ...global.promptContext, ...project.promptContext, ...manager.promptContext },
+		promptContext: { ...legacy.promptContext, ...manager.promptContext },
 	};
 }
+
+const PROVIDER_KEYS = new Set([
+	"appendSystemPrompt",
+	"connectorWriteMode",
+	"enableConnectors",
+	"fastMode",
+	"forceEffort",
+	"modelEffortOverrides",
+	"pathToClaudeCodeExecutable",
+	"strictMcpConfig",
+]);
+
+const PROMPT_CONTEXT_KEYS = new Set([
+	"includeAppendSystemPromptMd",
+	"includeCavemanHook",
+	"includeProjectAgentsHook",
+	"includeTaskPanelHook",
+]);
+
+function configValueForKey(config: Partial<Config>, key: string): unknown {
+	if (key === "enabled") return config.enabled;
+	if (PROVIDER_KEYS.has(key)) return normalizeProviderConfig(config.provider)?.[key as keyof NonNullable<Config["provider"]>];
+	if (PROMPT_CONTEXT_KEYS.has(key)) return config.promptContext?.[key as keyof NonNullable<Config["promptContext"]>];
+	return undefined;
+}
+
+/** Home-relative when possible — for user-facing path mentions (what to edit,
+ *  what to paste into an issue) where an absolute path would leak the username. */
+export function displayPath(path: string): string {
+	const home = homedir();
+	return home && path.startsWith(home + sep) ? `~${path.slice(home.length)}` : path;
+}
+
+export interface ExternalConfigResolution {
+	explicit: boolean;
+	value: unknown;
+	source?: string;
+}
+
+/**
+ * The effective value of a manifest key from the config channels the extension
+ * manager does not own — the legacy `claude-bridge.json` files. Manager config
+ * outranks these, so the manager consults this only when neither of its own
+ * scopes holds the key.
+ */
+export function resolveExternalConfigValue(key: string, cwd: string): ExternalConfigResolution {
+	const layers = legacyLayers(cwd);
+	const value = configValueForKey(mergeLayers(layers), key);
+	if (value === undefined) return { explicit: false, value: undefined };
+	const source = [...layers].reverse().find((layer) => configValueForKey(layer.config, key) !== undefined)?.path;
+	return { explicit: true, value, ...(source ? { source: displayPath(source) } : {}) };
+}
+
+/**
+ * Publish the resolver before any early return, so a bridge disabled by a
+ * legacy file still explains itself in the settings editor.
+ */
+export function registerExternalConfigResolver(): void {
+	const host = globalThis as unknown as Record<PropertyKey, unknown>;
+	const existing = asRecord(host[EXTERNAL_CONFIG_RESOLVER_SYMBOL]);
+	const registry = existing ?? {};
+	if (!existing) host[EXTERNAL_CONFIG_RESOLVER_SYMBOL] = registry;
+	registry[PACKAGE_ID] = (key: string, cwd: string) => resolveExternalConfigValue(key, cwd);
+}

package/src/connector-cache.ts

@@ -22,8 +22,11 @@
 // bundle to its sidecar process, so rather than calling `listAccountConnectors`
 // in-process it re-implements the reader half — path
 // `<piUserDir()>/connector-cache/<sha256(CLAUDE_CONFIG_DIR).hex[0..16]>.json`,
-// payload `{version, scope, savedAt, connectors}`, 7-day max age — as the
-// "is this connector installed" half of its write gate.
+// payload `{version, scope, savedAt, connectors}` where `scope` is the FULL
+// sha256 hex of the scope key (version 2; version 1 stored the raw
+// CLAUDE_CONFIG_DIR path, which is account-identifying and does not belong in
+// a state file), 7-day max age — as the "is this connector installed" half of
+// its write gate.
 //
 // That coupling fails OPEN on drift by design, so a format change degrades them
 // from two gates to one rather than breaking them. It is still worth making the
@@ -34,9 +37,10 @@ import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { piUserDir } from "./config.js";
+import { debug } from "./debug.js";
 import type { ConnectorEntry } from "./connector-inventory.js";
 
-const CACHE_VERSION = 1;
+const CACHE_VERSION = 2;
 /** Long enough to be useful across a machine's lifetime, short enough that a
  *  removed connector stops being declared without needing a manual purge. A
  *  stale entry is not dangerous — a connector that no longer resolves simply
@@ -44,8 +48,26 @@ const CACHE_VERSION = 1;
  *  correctness boundary. */
 const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 
+/**
+ * THE canonical credential-scope key: a trimmed CLAUDE_CONFIG_DIR, or the
+ * `"<default>"` sentinel for the default account. The on-disk cache format has
+ * an external reader (see the module header), and the in-memory prime cache in
+ * connector-runtime.ts keys the same scopes — both MUST agree on this rule, so
+ * there is exactly one implementation.
+ */
+export function scopeKeyFor(claudeConfigDir?: string): string {
+	return claudeConfigDir?.trim() || "<default>";
+}
+
 export function connectorCacheScopeKey(env: NodeJS.ProcessEnv = process.env): string {
-	return env.CLAUDE_CONFIG_DIR?.trim() || "<default>";
+	return scopeKeyFor(env.CLAUDE_CONFIG_DIR);
+}
+
+// Full sha256 hex of a scope key. The filename keeps only the first 16 chars;
+// the payload stores the whole digest so a truncated-hash collision (or a
+// hand-copied file) is still caught by the scope check in readCachedConnectors.
+function connectorCacheScopeDigest(scopeKey: string): string {
+	return createHash("sha256").update(scopeKey).digest("hex");
 }
 
 /**
@@ -55,7 +77,7 @@ export function connectorCacheScopeKey(env: NodeJS.ProcessEnv = process.env): st
  * dir is an arbitrary absolute path.
  */
 export function connectorCachePath(scopeKey: string = connectorCacheScopeKey()): string {
-	const digest = createHash("sha256").update(scopeKey).digest("hex").slice(0, 16);
+	const digest = connectorCacheScopeDigest(scopeKey).slice(0, 16);
 	return join(piUserDir(), "connector-cache", `${digest}.json`);
 }
 
@@ -78,15 +100,20 @@ export function readCachedConnectors(
 	let parsed: any;
 	try {
 		parsed = JSON.parse(raw);
-	} catch {
+	} catch (error) {
+		// A corrupt cache degrades to the no-cache path by contract, but silently
+		// doing so on every turn is how a bad file hides forever.
+		debug(`connector-cache: corrupt cache ${connectorCachePath(scopeKey)}:`, error instanceof Error ? error.message : String(error));
 		return undefined;
 	}
 	if (parsed?.version !== CACHE_VERSION) return undefined;
-	// Scope is stored as well as hashed into the path: a hash collision or a
-	// hand-copied file would otherwise hand one account another's connectors,
-	// which is the exact failure the token-scoping note in connector-inventory.ts
-	// warns about.
-	if (parsed?.scope !== scopeKey) return undefined;
+	// The scope digest is stored as well as hashed into the path: a truncated-
+	// hash collision or a hand-copied file would otherwise hand one account
+	// another's connectors, which is the exact failure the token-scoping note in
+	// connector-inventory.ts warns about. The payload carries the digest, never
+	// the raw scope key — a config-dir path is account-identifying and the
+	// filename is already hashed for the same reason.
+	if (parsed?.scope !== connectorCacheScopeDigest(scopeKey)) return undefined;
 	const savedAt = typeof parsed?.savedAt === "number" ? parsed.savedAt : 0;
 	if (!savedAt || now - savedAt > MAX_AGE_MS || savedAt > now) return undefined;
 	if (!Array.isArray(parsed?.connectors)) return undefined;
@@ -108,11 +135,14 @@ export function writeCachedConnectors(
 		mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
 		writeFileSync(
 			path,
-			JSON.stringify({ version: CACHE_VERSION, scope: scopeKey, savedAt: now, connectors }),
+			JSON.stringify({ version: CACHE_VERSION, scope: connectorCacheScopeDigest(scopeKey), savedAt: now, connectors }),
 			{ mode: 0o600 },
 		);
 		return true;
-	} catch {
+	} catch (error) {
+		// Best-effort by contract, but a persistent write failure means every cold
+		// process re-loses the turn-1 race this cache exists to win — say so.
+		debug(`connector-cache: write failed ${path}:`, error instanceof Error ? error.message : String(error));
 		return false;
 	}
 }

package/src/connector-inventory.ts

@@ -140,16 +140,23 @@ export function connectorServerNamespace(connectorName: string): string {
 }
 
 // Candidate credential files, in precedence order. CLAUDE_CONFIG_DIR is set
-// per-account by hosts that run one sidecar per Claude account, so it must win
-// over the home-directory default or a multi-account host reads the wrong
-// account's connectors. Both file names are probed under each root because the
-// token and the org UUID do not reliably live in the same file across versions.
+// per-account by hosts that run one sidecar per Claude account, so when it is
+// set that root is probed EXCLUSIVELY: falling through to `~/.claude`/$HOME
+// would silently borrow the DEFAULT account's token for a managed profile
+// whose own `.credentials.json` is missing — a confident, well-formed answer
+// for the wrong account (see the token-scoping note above). Only the
+// no-config-dir default probes the home locations. Both file names are probed
+// under each root because the token and the org UUID do not reliably live in
+// the same file across versions.
 export function credentialCandidatePaths(env: NodeJS.ProcessEnv = process.env): string[] {
 	const roots: string[] = [];
 	const configDir = env.CLAUDE_CONFIG_DIR?.trim();
-	if (configDir) roots.push(configDir);
-	const home = env.HOME?.trim();
-	if (home) roots.push(`${home}/.claude`, home);
+	if (configDir) {
+		roots.push(configDir);
+	} else {
+		const home = env.HOME?.trim();
+		if (home) roots.push(`${home}/.claude`, home);
+	}
 	const seen = new Set<string>();
 	const paths: string[] = [];
 	for (const root of roots) {