@vanillagreen/pi-claude-bridge 1.9.0 → 3.2.2

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-audit.ts

@@ -0,0 +1,203 @@
+// Audit trail for connector calls the `claude` child executes itself.
+//
+// A claude.ai connector tool runs INSIDE the child, on the child's own MCP
+// servers, and is deliberately never mirrored into the Pi stream (see
+// isChildExecutedTool). That is the honest behaviour — mirroring wrote
+// `Tool <name> not found` into the transcript for calls that had SUCCEEDED
+// (drovr#311 / memsira#320) — but it leaves the Pi session with no record that
+// the call happened at all, so "did it really look that up?" could only be
+// answered from the child's own transcript.
+//
+// A pi `CustomEntry` closes that gap without reintroducing the bug: it is
+// persisted in the session file, is NOT a content block, and is documented as
+// "ignored by buildSessionContext", so Pi's agent loop can never dispatch it and
+// `convertPiMessages` (which reads messages, not entries) can never project it
+// back into the child's session. `CustomMessageEntry` is the sibling type that
+// DOES enter context — using it here would recreate the whole problem.
+//
+// The payload is never recorded. A connector result is live account data (mail,
+// messages, documents); the audit answers whether a call happened and what came
+// back, not what it said.
+
+import { extensionApi } from "./bridge-state.js";
+import { debug } from "./debug.js";
+import type { QueryContext, ToolCallDrainCause } from "./query-state.js";
+
+export const CONNECTOR_CALL_CUSTOM_TYPE = "claude-bridge-connector-call";
+
+/**
+ * What the bridge observed of a connector call.
+ *
+ * `unobserved` is the load-bearing one: the call was issued and the query ended
+ * before its result came back. Recording nothing for it would leave an answer in
+ * the transcript with no trace of the call behind it — indistinguishable from a
+ * turn where no call was ever made. Same reasoning as `interruptedToolCallResult`
+ * for Pi-side tools: a call that did not complete says so.
+ */
+export type ConnectorCallOutcome = "ok" | "error" | "unobserved";
+
+export interface ConnectorCallAuditData {
+	/** Raw connector tool name as the child invoked it (`mcp__claude_ai_<Server>__<tool>`). */
+	name: string;
+	/** The child's own `tool_use` id — the join key to its transcript. */
+	toolUseId: string;
+	outcome: ConnectorCallOutcome;
+	/** UTF-8 byte size of the observed result payload. Absent when the result was
+	 *  never observed, or could not be measured — never a confident 0 for
+	 *  something that was not sized. */
+	byteSize?: number;
+	/** Claude Code session that executed the call. Absent when the SDK never
+	 *  reported one for this query. */
+	childSessionId?: string;
+	/** Why an `unobserved` call ended. Absent for observed ones. */
+	reason?: ToolCallDrainCause;
+}
+
+/**
+ * Approximate UTF-8 byte size of a child tool result's payload.
+ *
+ * A string payload is measured directly; any other shape is measured as its JSON
+ * serialization, so a structured or image result reports the size it really
+ * carried. (The debug line this replaces reported `content.length` for an array
+ * payload — a BLOCK count wearing a byte size's name.)
+ *
+ * Returns undefined when there is nothing to measure or the payload cannot be
+ * serialized, so the caller omits the field rather than recording a 0 it did not
+ * measure. The payload itself is never returned or logged.
+ */
+export function connectorResultByteSize(content: unknown): number | undefined {
+	if (content === undefined || content === null) return undefined;
+	if (typeof content === "string") return Buffer.byteLength(content, "utf8");
+	try {
+		const json = JSON.stringify(content);
+		return typeof json === "string" ? Buffer.byteLength(json, "utf8") : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * An ADDITIONAL destination for connector-call records, for a host that embeds
+ * the bridge with no pi session to append to.
+ *
+ * Never throws is the contract on OUR side; a sink that throws anyway is caught
+ * and dropped, because an audit record must not be able to fail a turn.
+ */
+export type ConnectorCallAuditSink = (data: ConnectorCallAuditData) => void;
+
+let auditSink: ConnectorCallAuditSink | undefined;
+
+/**
+ * Install (or clear, with `undefined`) a host sink for connector-call records.
+ *
+ * **The sink ADDS a destination, it never replaces `appendEntry`.** A host that
+ * drives real `AgentSession`s gets the transcript-local entries for free, and a
+ * replacing sink would take those away and reopen the very audit gap this
+ * feature closes (memsira, 2026-07-28 — their `apps/sidecar/src/runtime.ts` is
+ * session-backed, and 122 of their app-chat session files carry the bridge's
+ * `claude-bridge-session` markers). A host with both a session and a sink has
+ * asked for both and gets both.
+ *
+ * It exists because the OTHER embedding shape gets nothing at all: drovr loads
+ * the bundle through a throwaway resource loader over
+ * `createAgentSessionServices` with no session, so `extensionApi` is undefined
+ * and every record it appended went nowhere (drovr #317, measured live). The
+ * sink is the seam such a host can reach without one.
+ *
+ * A callback rather than another `Symbol.for` global on purpose: the bundle
+ * already has one (`claude-bridge:activeStreamSimple`) and hosts document that
+ * coupling as a re-vendor hazard, so a second would be the wrong direction.
+ *
+ * Process-global, matching `setExtensionApi`: one bundle instance serves one
+ * host. A host that runs several conversations in ONE process must therefore
+ * route by `childSessionId` itself, or embed per conversation as drovr does.
+ */
+export function setConnectorCallAuditSink(sink: ConnectorCallAuditSink | undefined): void {
+	auditSink = sink;
+}
+
+/**
+ * Append one audit entry to every destination the host installed. Returns
+ * whether it reached AT LEAST ONE of them, so a caller can log the truth rather
+ * than assume — both are absent whenever the bridge runs outside a pi session
+ * and outside a sink-installing host (tests, the connector-inventory entry
+ * point).
+ *
+ * The two destinations are independent: one throwing must not cost the other
+ * its record. Never throws — an audit record must not be able to fail a turn.
+ */
+export function appendConnectorCallAudit(data: ConnectorCallAuditData): boolean {
+	let delivered = false;
+	if (extensionApi) {
+		try {
+			extensionApi.appendEntry(CONNECTOR_CALL_CUSTOM_TYPE, data);
+			delivered = true;
+		} catch (error) {
+			debug("appendConnectorCallAudit failed:", error);
+		}
+	}
+	if (auditSink) {
+		try {
+			// A COPY, because the sink is host code and `appendEntry` above holds a
+			// reference to the same object: a sink that mutated the record would be
+			// editing what the session already recorded.
+			auditSink({ ...data });
+			delivered = true;
+		} catch (error) {
+			debug("connector call audit sink failed:", error);
+		}
+	}
+	return delivered;
+}
+
+/**
+ * Record the observed result of a child-executed connector call, once.
+ *
+ * Keyed on the tool_use id rather than on the call site: the SDK can re-yield a
+ * `user` message, and an audit trail that counts one call twice is worse than
+ * one that counts it not at all. Returns whether an entry was appended.
+ */
+export function recordConnectorCallResult(
+	queryCtx: QueryContext,
+	toolUseId: string,
+	name: string,
+	isError: boolean,
+	byteSize: number | undefined,
+): boolean {
+	const pending = queryCtx.connectorCallAudit.get(toolUseId);
+	if (pending?.recorded) return false;
+	const childSessionId = pending?.childSessionId ?? queryCtx.childSessionId;
+	queryCtx.connectorCallAudit.set(toolUseId, { ...pending, name, childSessionId, recorded: true });
+	return appendConnectorCallAudit({
+		name,
+		toolUseId,
+		outcome: isError ? "error" : "ok",
+		...(byteSize !== undefined ? { byteSize } : {}),
+		...(childSessionId ? { childSessionId } : {}),
+	});
+}
+
+/**
+ * Record every connector call this query issued whose result never came back,
+ * naming the cause. Runs at query teardown, beside the Pi-side tool drain, and is
+ * idempotent — a call already recorded is skipped, and one recorded here is
+ * marked so a late arrival cannot record it again.
+ *
+ * Returns how many entries were appended.
+ */
+export function flushConnectorCallAudit(queryCtx: QueryContext, reason: ToolCallDrainCause): number {
+	let appended = 0;
+	for (const [toolUseId, state] of queryCtx.connectorCallAudit) {
+		if (state.recorded) continue;
+		queryCtx.connectorCallAudit.set(toolUseId, { ...state, recorded: true });
+		const childSessionId = state.childSessionId ?? queryCtx.childSessionId;
+		if (appendConnectorCallAudit({
+			name: state.name,
+			toolUseId,
+			outcome: "unobserved",
+			reason,
+			...(childSessionId ? { childSessionId } : {}),
+		})) appended++;
+	}
+	return appended;
+}

package/src/connector-cache.ts

@@ -0,0 +1,148 @@
+// Cross-PROCESS cache of the connector inventory (vstack#870).
+//
+// #868 primes the inventory at provider registration, but the fetch takes ~1.5s
+// while the first query is built at ~0.5-0.8s, so turn 1 of a cold sidecar goes
+// out with no declarations and gets exactly the #832 bug it was meant to fix.
+//
+// An in-process cache cannot help the consumer that needs it most. drovr builds
+// a sidecar lazily on the first bridge round and, since their sidecars are
+// per-SESSION, that is a fresh process for every new chat — so their exposure is
+// once per chat, indefinitely, and every one of those is a cold process. The
+// cache therefore has to survive process boundaries.
+//
+// Keyed by credential scope, because that is what selects the account: the org
+// UUID in the inventory request is ignored and only the credential decides whose
+// connectors come back. Two accounts on one host must not share a cache entry.
+//
+// Everything here is best-effort. A missing, unreadable, corrupt, stale, or
+// wrong-version cache returns undefined and the caller falls back to today's
+// behaviour — the same fail-open contract as the inventory call itself.
+//
+// The ON-DISK FORMAT HAS AN EXTERNAL READER (vstack#892). drovr quarantines this
+// 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}` 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
+// change knowingly: bump CACHE_VERSION so their staleness check rejects rather
+// than misreads, and say so in the changelog. `unit-connector-cache.mjs` pins
+// the path shape and payload keys.
+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 = 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
+ *  fails to connect, which is the fail-open path — so this is hygiene, not a
+ *  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 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");
+}
+
+/**
+ * Our own state directory, not the Claude config dir. The credential directory
+ * belongs to the CLI; the scope is encoded in the filename instead so we never
+ * write into someone else's tree. Hashed rather than escaped because a config
+ * dir is an arbitrary absolute path.
+ */
+export function connectorCachePath(scopeKey: string = connectorCacheScopeKey()): string {
+	const digest = connectorCacheScopeDigest(scopeKey).slice(0, 16);
+	return join(piUserDir(), "connector-cache", `${digest}.json`);
+}
+
+/**
+ * Synchronous by design. The query path has no await boundary to hang a read on
+ * — `streamClaudeAgentSdk` returns its stream and claims the SDK query handle in
+ * the same tick — which is the whole reason the in-memory prime loses the race.
+ * A single small `readFileSync` is what makes turn 1 reachable at all.
+ */
+export function readCachedConnectors(
+	scopeKey: string = connectorCacheScopeKey(),
+	now: number = Date.now(),
+): ConnectorEntry[] | undefined {
+	let raw: string;
+	try {
+		raw = readFileSync(connectorCachePath(scopeKey), "utf8");
+	} catch {
+		return undefined;
+	}
+	let parsed: any;
+	try {
+		parsed = JSON.parse(raw);
+	} 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;
+	// 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;
+	const connectors = parsed.connectors.filter(
+		(entry: any) => entry && typeof entry.name === "string" && entry.name.trim(),
+	);
+	return connectors.length > 0 ? (connectors as ConnectorEntry[]) : undefined;
+}
+
+/** Best-effort write; a failure here must never affect the turn. */
+export function writeCachedConnectors(
+	connectors: ConnectorEntry[],
+	scopeKey: string = connectorCacheScopeKey(),
+	now: number = Date.now(),
+): boolean {
+	if (!Array.isArray(connectors) || connectors.length === 0) return false;
+	const path = connectorCachePath(scopeKey);
+	try {
+		mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+		writeFileSync(
+			path,
+			JSON.stringify({ version: CACHE_VERSION, scope: connectorCacheScopeDigest(scopeKey), savedAt: now, connectors }),
+			{ mode: 0o600 },
+		);
+		return true;
+	} 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;
+	}
+}