@oh-my-pi/pi-coding-agent 15.9.1 → 15.9.5

package/src/extensibility/plugins/legacy-pi-compat.ts

@@ -41,10 +41,15 @@ const PI_SUBPATH_REMAPS: ReadonlyMap<string, string> = new Map<string, string>([
 
 const LEGACY_PI_SPECIFIER_FILTER = new RegExp(`^@(?:${PI_SCOPE_ALTERNATION})/(?:${PI_PACKAGE_ALTERNATION})(?:/.*)?$`);
 const LEGACY_PI_IMPORT_SPECIFIER_REGEX = new RegExp(
-	`((?:from\\s+|import\\s*\\(\\s*)["'])(@(?:${PI_SCOPE_ALTERNATION})/(?:${PI_PACKAGE_ALTERNATION})(?:/[^"'()\\s]+)?)(["'])`,
+	`((?:from\\s+|import\\s+|import\\s*\\(\\s*)["'])(@(?:${PI_SCOPE_ALTERNATION})/(?:${PI_PACKAGE_ALTERNATION})(?:/[^"'()\\s]+)?)(["'])`,
 	"g",
 );
 const resolvedSpecifierFallbacks = new Map<string, string>();
+const SOURCE_MODULE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"] as const;
+const SUPPORTED_PACKAGE_IMPORT_CONDITIONS = new Set(["bun", "node", "import", "default"]);
+const packageRootCache = new Map<string, string | null>();
+const packageImportsCache = new Map<string, Record<string, unknown> | null>();
+const PACKAGE_IMPORT_EXCLUDED = Symbol("packageImportExcluded");
 
 // Extensions that imported `@sinclair/typebox` directly used to resolve against a
 // real `@sinclair/typebox` install. The runtime dep was replaced with the Zod-backed
@@ -221,33 +226,245 @@ function rewriteLegacyPiImports(source: string): string {
 // Match the bare `@sinclair/typebox` import specifier (static + dynamic).
 // Subpath imports like `@sinclair/typebox/compiler` are intentionally excluded —
 // they expose TypeBox-only APIs the Zod-backed shim does not provide.
-const TYPEBOX_IMPORT_SPECIFIER_REGEX = /((?:from\s+|import\s*\(\s*)["'])(@sinclair\/typebox)(["'])/g;
+const TYPEBOX_IMPORT_SPECIFIER_REGEX = /((?:from\s+|import\s+|import\s*\(\s*)["'])(@sinclair\/typebox)(["'])/g;
 
 /**
- * Rewrite the legacy specifiers a Pi extension may import — `@(scope)/pi-*` and
- * the bare `@sinclair/typebox` root — to absolute `file://` URLs pointing at the
- * bundled package or compat shim. Every other specifier (relative siblings, the
- * extension's own bare dependencies) is left untouched so Bun resolves it
+ * Rewrite the extension-owned specifiers OMP must host-resolve — legacy
+ * `@(scope)/pi-*`, bare `@sinclair/typebox`, and package `imports` aliases like
+ * `#src/*` — to absolute `file://` URLs. Every other specifier (relative
+ * siblings and third-party dependencies) is left untouched so Bun resolves it
  * natively from the extension's real on-disk location.
  */
-function rewriteLegacyExtensionSource(source: string): string {
+async function rewriteLegacyExtensionSource(source: string, importerPath: string): Promise<string> {
 	const withPi = rewriteLegacyPiImports(source);
-	return withPi.replace(
+	const withTypeBox = withPi.replace(
 		TYPEBOX_IMPORT_SPECIFIER_REGEX,
 		(_match, prefix: string, _specifier: string, suffix: string) => {
 			return `${prefix}${toImportSpecifier(TYPEBOX_SHIM_PATH)}${suffix}`;
 		},
 	);
+	return rewriteExtensionPackageImports(withTypeBox, importerPath);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function pathExists(p: string): Promise<boolean> {
+	try {
+		await fs.stat(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function hasSourceModuleExtension(p: string): boolean {
+	const ext = path.extname(p).toLowerCase();
+	return (SOURCE_MODULE_EXTENSIONS as readonly string[]).includes(ext);
+}
+
+async function resolveSourceModuleFile(basePath: string): Promise<string | null> {
+	try {
+		const stats = await fs.stat(basePath);
+		if (stats.isFile()) {
+			// Non-source files (JSON, WASM, text assets, etc.) bypass the on-load
+			// rewrite hook so Bun's native loaders handle them; our hook would
+			// otherwise pass them through `getLoader()` which falls back to `js`.
+			return hasSourceModuleExtension(basePath) ? realpathOrSelf(basePath) : null;
+		}
+		if (stats.isDirectory()) {
+			for (const extension of SOURCE_MODULE_EXTENSIONS) {
+				const resolved = await resolveSourceModuleFile(path.join(basePath, `index${extension}`));
+				if (resolved) return resolved;
+			}
+		}
+	} catch {
+		// Fall through to extension candidates below.
+	}
+
+	if (path.extname(basePath)) {
+		return null;
+	}
+
+	for (const extension of SOURCE_MODULE_EXTENSIONS) {
+		const resolved = await resolveSourceModuleFile(`${basePath}${extension}`);
+		if (resolved) return resolved;
+	}
+	return null;
+}
+
+async function findPackageRoot(importerPath: string): Promise<string | null> {
+	let dir = path.dirname(importerPath);
+	while (true) {
+		const cached = packageRootCache.get(dir);
+		if (cached !== undefined) {
+			return cached;
+		}
+
+		if (await pathExists(path.join(dir, "package.json"))) {
+			packageRootCache.set(path.dirname(importerPath), dir);
+			return dir;
+		}
+
+		const parent = path.dirname(dir);
+		if (parent === dir) {
+			packageRootCache.set(path.dirname(importerPath), null);
+			return null;
+		}
+		dir = parent;
+	}
+}
+
+async function readPackageImports(packageRoot: string): Promise<Record<string, unknown> | null> {
+	const cached = packageImportsCache.get(packageRoot);
+	if (cached !== undefined) {
+		return cached;
+	}
+
+	let imports: Record<string, unknown> | null = null;
+	try {
+		const pkg = await Bun.file(path.join(packageRoot, "package.json")).json();
+		if (isRecord(pkg) && isRecord(pkg.imports)) {
+			imports = pkg.imports;
+		}
+	} catch {
+		imports = null;
+	}
+	packageImportsCache.set(packageRoot, imports);
+	return imports;
+}
+
+type PackageImportTargetSelection = string | typeof PACKAGE_IMPORT_EXCLUDED | null;
+type ResolvedPackageImportTargetSelection = string | typeof PACKAGE_IMPORT_EXCLUDED;
+
+function selectPackageImportTarget(entry: unknown): PackageImportTargetSelection {
+	if (entry === null) {
+		return PACKAGE_IMPORT_EXCLUDED;
+	}
+	if (typeof entry === "string") {
+		return entry;
+	}
+	if (Array.isArray(entry)) {
+		for (const item of entry) {
+			const target = selectPackageImportTarget(item);
+			if (target !== null) return target;
+		}
+		return null;
+	}
+	if (!isRecord(entry)) {
+		return null;
+	}
+	for (const [condition, value] of Object.entries(entry)) {
+		if (!SUPPORTED_PACKAGE_IMPORT_CONDITIONS.has(condition)) {
+			continue;
+		}
+		const target = selectPackageImportTarget(value);
+		if (target !== null) return target;
+	}
+	return null;
+}
+
+async function resolvePackageImportTarget(
+	packageRoot: string,
+	target: string,
+	wildcard: string | null,
+): Promise<string | null> {
+	if (!target.startsWith("./")) {
+		return null;
+	}
+	const substituted = wildcard === null ? target : target.replaceAll("*", wildcard);
+	return resolveSourceModuleFile(path.resolve(packageRoot, substituted));
+}
+
+async function resolvePackageImportSpecifier(specifier: string, importerPath: string): Promise<string | null> {
+	if (!specifier.startsWith("#")) {
+		return null;
+	}
+
+	const packageRoot = await findPackageRoot(importerPath);
+	if (!packageRoot) {
+		return null;
+	}
+
+	const imports = await readPackageImports(packageRoot);
+	if (!imports) {
+		return null;
+	}
+
+	const exactTarget = selectPackageImportTarget(imports[specifier]);
+	if (exactTarget === PACKAGE_IMPORT_EXCLUDED) {
+		return null;
+	}
+	if (exactTarget !== null) {
+		return resolvePackageImportTarget(packageRoot, exactTarget, null);
+	}
+
+	let bestMatch: { keyLength: number; target: ResolvedPackageImportTargetSelection; wildcard: string } | null = null;
+	for (const [key, entry] of Object.entries(imports)) {
+		const starIndex = key.indexOf("*");
+		if (starIndex === -1) continue;
+
+		const prefix = key.slice(0, starIndex);
+		const suffix = key.slice(starIndex + 1);
+		if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix)) {
+			continue;
+		}
+
+		const target = selectPackageImportTarget(entry);
+		if (target === null) {
+			continue;
+		}
+
+		if (!bestMatch || key.length > bestMatch.keyLength) {
+			bestMatch = {
+				keyLength: key.length,
+				target,
+				wildcard: specifier.slice(prefix.length, specifier.length - suffix.length),
+			};
+		}
+	}
+
+	if (!bestMatch || bestMatch.target === PACKAGE_IMPORT_EXCLUDED) {
+		return null;
+	}
+	return resolvePackageImportTarget(packageRoot, bestMatch.target, bestMatch.wildcard);
+}
+
+const PACKAGE_IMPORT_SPECIFIER_REGEX = /((?:from\s+|import\s+|import\s*\(\s*)["'])(#[^"'()\s]+)(["'])/g;
+
+async function rewriteExtensionPackageImports(source: string, importerPath: string): Promise<string> {
+	let rewritten = "";
+	let lastIndex = 0;
+	for (const match of source.matchAll(PACKAGE_IMPORT_SPECIFIER_REGEX)) {
+		const matchIndex = match.index;
+		if (matchIndex === undefined) continue;
+
+		const [fullMatch, prefix, specifier, suffix] = match;
+		if (!prefix || !specifier || !suffix) continue;
+
+		const resolved = await resolvePackageImportSpecifier(specifier, importerPath);
+		if (!resolved) continue;
+
+		rewritten += source.slice(lastIndex, matchIndex);
+		rewritten += `${prefix}${toImportSpecifier(resolved)}${suffix}`;
+		lastIndex = matchIndex + fullMatch.length;
+	}
+
+	if (lastIndex === 0) {
+		return source;
+	}
+	return `${rewritten}${source.slice(lastIndex)}`;
 }
 
 function escapeRegExp(value: string): string {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-// Match relative import specifiers (static `from "./…"` and dynamic
-// `import("./…")`). Used to walk an extension's own module graph; bare and
-// absolute specifiers are deliberately excluded.
-const RELATIVE_IMPORT_SPECIFIER_REGEX = /(?:from\s+|import\s*\(\s*)["'](\.\.?\/[^"']+)["']/g;
+// Match source modules in an extension graph (relative imports and package
+// `imports` aliases such as `#src/*`). Bare third-party dependencies remain
+// native Bun resolutions.
+const EXTENSION_GRAPH_SPECIFIER_REGEX = /(?:from\s+|import\s+|import\s*\(\s*)["']((?:\.\.?\/|#)[^"']+)["']/g;
 
 // Extension entry realpaths that already have a load-time rewrite hook
 // installed. Each `Bun.plugin()` registration is process-global and permanent,
@@ -287,10 +504,14 @@ async function collectExtensionModules(entryRealPath: string): Promise<Set<strin
 		}
 		modules.add(file);
 		const dir = path.dirname(file);
-		for (const match of source.matchAll(RELATIVE_IMPORT_SPECIFIER_REGEX)) {
+		for (const match of source.matchAll(EXTENSION_GRAPH_SPECIFIER_REGEX)) {
+			const specifier = match[1];
+			if (!specifier) continue;
 			try {
-				const resolved = await realpathOrSelf(Bun.resolveSync(match[1], dir));
-				if (!modules.has(resolved)) {
+				const resolved = specifier.startsWith("#")
+					? await resolvePackageImportSpecifier(specifier, file)
+					: await realpathOrSelf(Bun.resolveSync(specifier, dir));
+				if (resolved && !modules.has(resolved)) {
 					queue.push(resolved);
 				}
 			} catch {
@@ -303,11 +524,12 @@ async function collectExtensionModules(entryRealPath: string): Promise<Set<strin
 
 /**
  * Install a `Bun.plugin()` `onLoad` hook scoped to exactly the modules in an
- * extension's relative-import graph, so their legacy `@(scope)/pi-*` and bare
- * `@sinclair/typebox` imports are rewritten at load time. A runtime `onLoad`
- * cannot fall through (Bun requires a result object), so the filter is an
- * exact-path alternation of the graph's realpaths — it never matches the host,
- * other extensions, `node_modules` deps, or unrelated project source.
+ * extension's source graph, so their legacy `@(scope)/pi-*`, bare
+ * `@sinclair/typebox`, and local package-import aliases are rewritten at load
+ * time. A runtime `onLoad` cannot fall through (Bun requires a result object),
+ * so the filter is an exact-path alternation of the graph's realpaths — it
+ * never matches the host, other extensions, `node_modules` deps, or unrelated
+ * project source.
  */
 async function ensureExtensionGraphHook(entryRealPath: string): Promise<void> {
 	if (hookedExtensionEntries.has(entryRealPath)) {
@@ -322,9 +544,8 @@ async function ensureExtensionGraphHook(entryRealPath: string): Promise<void> {
 		name: `omp:legacy-pi-ext:${Bun.hash(entryRealPath).toString(36)}`,
 		setup(build) {
 			build.onLoad({ filter, namespace: "file" }, async args => {
-				// Re-read on every load so a `?mtime` reload picks up edited source.
 				const raw = await Bun.file(args.path).text();
-				return { contents: rewriteLegacyExtensionSource(raw), loader: getLoader(args.path) };
+				return { contents: await rewriteLegacyExtensionSource(raw, args.path), loader: getLoader(args.path) };
 			});
 		},
 	});
@@ -337,9 +558,8 @@ async function ensureExtensionGraphHook(entryRealPath: string): Promise<void> {
  * and `__dirname`-relative `readFileSync` asset loads (HTML/CSS bundled next to
  * the entry) resolve exactly as they do under the original Pi runtime — no
  * temp-directory mirroring and no asset copying. An `onLoad` hook scoped to the
- * entry's relative-import graph rewrites only the legacy `@(scope)/pi-*` and
- * `@sinclair/typebox` imports in the extension's own source; everything else
- * resolves natively.
+ * entry's source graph rewrites only host-resolved compatibility imports in the
+ * extension's own source; everything else resolves natively.
  */
 export async function loadLegacyPiModule(resolvedPath: string): Promise<unknown> {
 	// Bun reports the realpath of a loaded module to `onLoad` and exposes it as

package/src/hindsight/backend.ts

@@ -9,10 +9,10 @@
 
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import { logger } from "@oh-my-pi/pi-utils";
-import type { Settings } from "../config/settings";
+import { onHindsightScopeChanged, type Settings } from "../config/settings";
 import type { MemoryBackend, MemoryBackendStartOptions } from "../memory-backend/types";
 import type { AgentSession } from "../session/agent-session";
-import { computeBankScope } from "./bank";
+import { type BankScope, computeBankScope } from "./bank";
 import { createHindsightClient } from "./client";
 import { isHindsightConfigured, loadHindsightConfig } from "./config";
 import type { HindsightMessage } from "./content";
@@ -60,12 +60,16 @@ export const hindsightBackend: MemoryBackend = {
 					recallTagsMatch: parent.recallTagsMatch,
 					config: parent.config,
 					session,
-					missionsSet: parent.missionsSet,
+					banksSet: parent.banksSet,
 					lastRetainedTurn: 0,
 					hasRecalledForFirstTurn: true,
 					aliasOf: parent,
 				}),
 			);
+			// Aliases don't run auto-recall/auto-retain, so any pending retain
+			// queue belongs to the previous alias and is safe to drop after a
+			// best-effort flush (`flushRetainQueue` is no-op when empty).
+			await previous?.flushRetainQueue();
 			previous?.dispose();
 			return;
 		}
@@ -76,38 +80,7 @@ export const hindsightBackend: MemoryBackend = {
 			return;
 		}
 
-		const client = createHindsightClient(config);
-		const scope = computeBankScope(config, session.sessionManager.getCwd());
-
-		const state = new HindsightSessionState({
-			sessionId,
-			client,
-			bankId: scope.bankId,
-			retainTags: scope.retainTags,
-			recallTags: scope.recallTags,
-			recallTagsMatch: scope.recallTagsMatch,
-			config,
-			session,
-			missionsSet: new Set(),
-			lastRetainedTurn: 0,
-			hasRecalledForFirstTurn: false,
-		});
-
-		// Cleanup any stale state for this session (defensive — prevents leaks
-		// when a session is reused without going through dispose).
-		const previous = session.setHindsightSessionState(state);
-		previous?.dispose();
-		state.attachSessionListeners();
-
-		// Kick off mental-model bootstrap. Resolves asynchronously; the first
-		// turn races and is covered in `beforeAgentStartPrompt` via
-		// `mentalModelsLoadPromise`. Subsequent turns see the populated cache
-		// because `runMentalModelLoad` calls `refreshBaseSystemPrompt`.
-		if (config.mentalModelsEnabled) {
-			state.mentalModelsLoadPromise = state.runMentalModelLoad(scope).catch(err => {
-				logger.debug("Hindsight: mental-model bootstrap failed", { bankId: state.bankId, error: String(err) });
-			});
-		}
+		await installPrimaryState(session, settings, new Set());
 	},
 
 	async buildDeveloperInstructions(_agentDir, settings, session): Promise<string | undefined> {
@@ -173,6 +146,182 @@ export const hindsightBackend: MemoryBackend = {
 		return await state.recallForCompaction(flat);
 	},
 };
+interface PrimaryRebuildTask {
+	pending: boolean;
+}
+
+const primaryRebuildTasks = new WeakMap<AgentSession, PrimaryRebuildTask>();
+
+/**
+ * Coalesce and serialize live scope rebuilds for one session. Cwd reloads fire
+ * all settings hooks synchronously; running every callback immediately would
+ * let multiple rebuilds capture the same old state and leak the fresh states
+ * installed by earlier continuations.
+ */
+function schedulePrimaryStateRebuild(session: AgentSession): void {
+	const task = primaryRebuildTasks.get(session);
+	if (task) {
+		task.pending = true;
+		return;
+	}
+
+	const nextTask: PrimaryRebuildTask = { pending: true };
+	primaryRebuildTasks.set(session, nextTask);
+	void Promise.resolve()
+		.then(async () => {
+			while (nextTask.pending) {
+				nextTask.pending = false;
+				try {
+					await rebuildPrimaryStateOnScopeChange(session);
+				} catch (err) {
+					logger.warn("Hindsight: scope rebuild failed", { error: String(err) });
+				}
+			}
+		})
+		.finally(() => {
+			if (primaryRebuildTasks.get(session) === nextTask) {
+				primaryRebuildTasks.delete(session);
+			}
+		});
+}
+
+/**
+ * Build (or rebuild) the primary `HindsightSessionState` for `session` from
+ * the current settings and install it. Disposes any previous primary state
+ * after flushing its retain queue so in-flight tool-initiated retains land in
+ * the bank that was selected when they were enqueued, not in the new bank.
+ *
+ * The created state takes ownership of the `onHindsightScopeChanged`
+ * subscription so subsequent `hindsight.bankId` / `bankIdPrefix` / `scoping`
+ * edits trigger another rebuild from the same wiring.
+ */
+async function installPrimaryState(
+	session: AgentSession,
+	settings: Settings,
+	banksSet: Set<string>,
+): Promise<HindsightSessionState | undefined> {
+	const sessionId = session.sessionId;
+	if (!sessionId) return undefined;
+
+	const config = loadHindsightConfig(settings);
+	if (!isHindsightConfigured(config)) return undefined;
+
+	const client = createHindsightClient(config);
+	const scope = computeBankScope(config, session.sessionManager.getCwd());
+
+	// Cleanup any stale state for this session (defensive — prevents leaks
+	// when a session is reused without going through dispose). Flush the
+	// previous state's retain queue BEFORE clearing it, otherwise
+	// `HindsightRetainQueue.#doFlush` sees `session.getHindsightSessionState()
+	// !== state` and drops the batch. Re-read after the await so a concurrent
+	// owner cannot leave the actual current state undisposed.
+	let previous = session.getHindsightSessionState();
+	if (previous) {
+		await previous.flushRetainQueue();
+	}
+	const latest = session.getHindsightSessionState();
+	if (latest && latest !== previous) {
+		previous?.dispose();
+		previous = latest;
+		await previous.flushRetainQueue();
+	}
+
+	const state = new HindsightSessionState({
+		sessionId,
+		client,
+		bankId: scope.bankId,
+		retainTags: scope.retainTags,
+		recallTags: scope.recallTags,
+		recallTagsMatch: scope.recallTagsMatch,
+		config,
+		session,
+		banksSet,
+		lastRetainedTurn: 0,
+		hasRecalledForFirstTurn: false,
+	});
+
+	// Subscribe BEFORE installing: if the operator manages to flip another
+	// setting between install and subscribe, we'd miss the edge.
+	state.unsubscribeScope = onHindsightScopeChanged(() => {
+		schedulePrimaryStateRebuild(session);
+	});
+
+	const displaced = session.setHindsightSessionState(state);
+	if (displaced && displaced !== previous) {
+		await displaced.flushRetainQueue();
+		displaced.dispose();
+	}
+	previous?.dispose();
+	state.attachSessionListeners();
+
+	// Kick off mental-model bootstrap. Resolves asynchronously; the first
+	// turn races and is covered in `beforeAgentStartPrompt` via
+	// `mentalModelsLoadPromise`. Subsequent turns see the populated cache
+	// because `runMentalModelLoad` calls `refreshBaseSystemPrompt`.
+	if (config.mentalModelsEnabled) {
+		state.mentalModelsLoadPromise = state.runMentalModelLoad(scope).catch(err => {
+			logger.debug("Hindsight: mental-model bootstrap failed", { bankId: state.bankId, error: String(err) });
+		});
+	}
+
+	return state;
+}
+
+/**
+ * `onHindsightScopeChanged` handler: re-evaluate the bank scope from current
+ * settings and rebuild the primary state when it has actually drifted. No-op
+ * when the scope is unchanged or the session is no longer hosting a primary
+ * state (e.g. it was wiped to `undefined`, or this is a subagent alias).
+ */
+async function rebuildPrimaryStateOnScopeChange(session: AgentSession): Promise<void> {
+	const current = session.getHindsightSessionState();
+	if (!current || current.aliasOf) return;
+
+	const settings = session.settings;
+	const config = loadHindsightConfig(settings);
+	if (!isHindsightConfigured(config)) {
+		// Hindsight effectively unwired mid-session. Flush before clearing so
+		// queued retains don't get dropped by `HindsightRetainQueue.#doFlush`.
+		await current.flushRetainQueue();
+		const previous = session.setHindsightSessionState(undefined);
+		previous?.dispose();
+		return;
+	}
+
+	const next = computeBankScope(config, session.sessionManager.getCwd());
+	if (bankScopesEqual(next, current)) return;
+
+	// Preserve the banksSet so we don't re-PUT banks we've already confirmed.
+	await installPrimaryState(session, settings, current.banksSet);
+}
+
+/** Tag-array equality: order matters because we never reorder on the way in. */
+function stringArraysEqual(a: string[] | undefined, b: string[] | undefined): boolean {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) {
+		if (a[i] !== b[i]) return false;
+	}
+	return true;
+}
+
+/**
+ * Structural compare of a freshly resolved `BankScope` against a live state's
+ * bank routing. Used by the scope-change handler to skip rebuilds that don't
+ * actually move the bank or its tag filters.
+ */
+function bankScopesEqual(
+	scope: BankScope,
+	state: Pick<HindsightSessionState, "bankId" | "retainTags" | "recallTags" | "recallTagsMatch">,
+): boolean {
+	return (
+		scope.bankId === state.bankId &&
+		stringArraysEqual(scope.retainTags, state.retainTags) &&
+		stringArraysEqual(scope.recallTags, state.recallTags) &&
+		scope.recallTagsMatch === state.recallTagsMatch
+	);
+}
 
 /** Reduce arbitrary AgentMessages into the Hindsight flat-text shape. */
 function flattenMessagesForRecall(messages: AgentMessage[]): HindsightMessage[] {

package/src/hindsight/bank.ts

@@ -1,5 +1,5 @@
 /**
- * Bank ID derivation, project-tag scoping, and first-use mission setup.
+ * Bank ID derivation, project-tag scoping, and first-use bank setup.
  *
  * Three scoping modes (`HindsightConfig.scoping`):
  *   - `global`              — single shared bank, no per-project filter.
@@ -11,10 +11,13 @@
  * The base bank id is `bankIdPrefix-bankId` (default `omp`). Per-project mode
  * appends `-<project>`; tagged mode leaves the bank untouched and uses tags.
  *
- * Mission setup is idempotent at module level — a missionsSet keeps track of
- * banks we've already POSTed to so each session boundary doesn't fire a fresh
- * `createBank` call. Failures are swallowed: missions are an optimisation, not
- * a precondition for retain/recall.
+ * Bank existence is idempotent at module level — a banksSet keeps track of
+ * banks we've already PUT so each session boundary doesn't fire a fresh
+ * `createBank` call. The PUT is idempotent server-side, so re-firing on a hot
+ * path would only burn round-trips. Failures are swallowed: missing the
+ * mission patch is an optimisation, but the bank ITSELF must exist before
+ * mental-model bootstrap or the first retain, otherwise the very first POST
+ * lands against a missing bank.
  */
 
 import * as path from "node:path";
@@ -93,39 +96,46 @@ export function deriveBankId(config: HindsightConfig, directory: string): string
 }
 
 /**
- * Ensure a bank's reflect/retain mission is set, exactly once per process.
+ * Ensure a bank exists, and patch its reflect/retain mission on first use.
  *
- * Tracked via the supplied set; on overflow we drop the oldest half so the set
- * cannot grow unboundedly across long-lived processes.
+ * Idempotent: skips the PUT when the bank id is already in the supplied set.
+ * The mission body is optional — when `bankMission` is blank we still PUT to
+ * make sure the bank itself is created, so mental-model bootstrap and the
+ * first retain don't land against a non-existent bank.
+ *
+ * The set is capped; on overflow we drop the oldest half so it cannot grow
+ * unboundedly across long-lived processes.
  */
-export async function ensureBankMission(
+export async function ensureBankExists(
 	client: HindsightApi,
 	bankId: string,
 	config: HindsightConfig,
-	missionsSet: Set<string>,
+	banksSet: Set<string>,
 ): Promise<void> {
+	if (banksSet.has(bankId)) return;
+
 	const mission = config.bankMission?.trim();
-	if (!mission) return;
-	if (missionsSet.has(bankId)) return;
+	const retainMission = config.retainMission?.trim();
 
 	try {
 		await client.createBank(bankId, {
-			reflectMission: mission,
-			retainMission: config.retainMission?.trim() || undefined,
+			reflectMission: mission || undefined,
+			retainMission: retainMission || undefined,
 		});
-		missionsSet.add(bankId);
-		if (missionsSet.size > MISSION_SET_CAP) {
-			const keys = [...missionsSet].sort();
+		banksSet.add(bankId);
+		if (banksSet.size > MISSION_SET_CAP) {
+			const keys = [...banksSet].sort();
 			for (const key of keys.slice(0, keys.length >> 1)) {
-				missionsSet.delete(key);
+				banksSet.delete(key);
 			}
 		}
 		if (config.debug) {
-			logger.debug("Hindsight: set mission for bank", { bankId });
+			logger.debug("Hindsight: ensured bank", { bankId, mission: Boolean(mission) });
 		}
 	} catch (err) {
-		// Mission set is best-effort; the bank may not exist yet, or the API may
-		// reject the call. Either way, retain/recall still work, so swallow.
-		logger.debug("Hindsight: ensureBankMission failed", { bankId, error: String(err) });
+		// Bank creation is best-effort; the server may already have it, or the
+		// API may reject the call. Either way, downstream retain/recall calls
+		// will surface a clearer error if the bank really is missing.
+		logger.debug("Hindsight: ensureBankExists failed", { bankId, error: String(err) });
 	}
 }

package/src/hindsight/mental-models.ts

@@ -112,7 +112,7 @@ function dedupe<T>(items: T[]): T[] {
  * Idempotently create any seed mental models that don't already exist on the
  * bank. Best-effort: a list/create failure does not throw — mental models are
  * an optimization, not a precondition for retain/recall, and we mirror the
- * swallow-on-failure pattern used by `ensureBankMission`.
+ * swallow-on-failure pattern used by `ensureBankExists`.
  *
  * Existing models are NEVER modified. See module docstring.
  */