@yandy0725/pi-memory 2.0.0 → 2.1.1

package/index.ts

@@ -1,12 +1,12 @@
-import { readFile, unlink } from "node:fs/promises";
+import { unlink } from "node:fs/promises";
 import { join } from "node:path";
-import type { ExtensionAPI, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
-import { loadConfig, type MemoryConfig, type SessionPersistenceConfig } from "./src/config";
+import { loadConfig, modelConfigErrors, requiredModel, type MemoryConfig, type SessionPersistenceConfig } from "./src/config";
 import { runDream } from "./src/dream";
 import { indexCapacity, parseEntryIndex } from "./src/entry-index";
 import { runExtract } from "./src/extract";
-import { readLockStatus } from "./src/fs-lock";
+import { readLockStatus, type LockInfo } from "./src/fs-lock";
 import { readRecordedMemoryIndex } from "./src/index-source";
 import { applyIndexSection, buildIndexSection, buildInjection, injectSurfacedContent, runSideQuery, scanEntries } from "./src/inject";
 import {
@@ -16,7 +16,7 @@ import {
 	type MemoryToolDeps,
 } from "./src/memory-tool";
 import { LOCK_FILE, MemoryStore } from "./src/memory-store";
-import { MIGRATED_FILE, migrateIfNeeded } from "./src/migrate";
+import { resolveModel } from "./src/model-resolver";
 import { readDreamMeta, shouldNudge, writeDreamMeta } from "./src/nudge";
 import { resolveMemoryDir } from "./src/paths";
 import { searchSessions } from "./src/session-search";
@@ -68,58 +68,41 @@ function countInjectedBlocks(content: string): number {
 	return Math.max(0, content.split("\n## ").length - 1);
 }
 
-/**
- * `/memory` 的迁移状态行（spec §14）。`.migrated` 由迁移在**最后一步**写（§15.3 步骤 6），
- * 所以「标记不在」= 还没迁完 = `pending`（下次 session_start 会重试）；
- * 标记读不懂也按 `pending` 报 —— 宁可让用户多看到一次重试，不可假装已经迁完。
- * `files`/`entries` 都是 0 则是「扫过了、根本没东西要迁」= `not needed`。
- */
-async function readMigrationStatus(memoryDir: string): Promise<string> {
-	try {
-		const marker = JSON.parse(await readFile(join(memoryDir, MIGRATED_FILE), "utf8")) as {
-			migratedAt?: unknown;
-			entries?: unknown;
-			files?: unknown;
-		};
-		if (
-			typeof marker.migratedAt !== "string" ||
-			typeof marker.entries !== "number" ||
-			typeof marker.files !== "number"
-		) {
-			return "pending";
-		}
-		if (marker.files === 0 && marker.entries === 0) return "not needed";
-		return `migrated at ${marker.migratedAt} (${marker.entries} entries from ${marker.files} files)`;
-	} catch {
-		return "pending";
-	}
+/** `<op> (pid N on <hostname>, started <ISO>)` —— `/memory` 的 Lock 行与 unlock 确认框共用同一份描述。 */
+function describeHolder(holder: LockInfo): string {
+	return `${holder.op} (pid ${holder.pid} on ${holder.hostname}, started ${holder.startedAt})`;
 }
 
 /**
  * `/memory` 的锁状态行。只读不碰 —— `.lock` **永不自动回收**（spec §5.1），
  * 人工清除只有 `/memory unlock` 一个入口。
+ * 带 hostname：`.lock` 是目录里的普通文件，同一份目录可能被挂载到多台机器（spec §19），
+ * 只看 pid 无法判断持有者是不是“本机的另一个进程”。
  */
 async function lockStatusLine(memoryDir: string): Promise<string> {
 	const status = await readLockStatus(join(memoryDir, LOCK_FILE));
 	if (status.kind === "absent") return "free";
 	if (status.kind === "unreadable") return "unreadable — run /memory unlock";
-	return `held by ${status.holder.op} (pid ${status.holder.pid}, started ${status.holder.startedAt})`;
+	return `held by ${describeHolder(status.holder)}`;
 }
 
 /**
  * `/memory unlock`：崩溃遗留的 `.lock` 的**唯一**人工清除入口（spec §19 风险表）。
  * 必须显式 confirm，而且只删 `.lock` 本身 —— 删错了就是两个写入者同时持有锁。
+ * confirm 正文在 `held` 时点名持有者：只有人能把「本机已死的进程」与「别的机器正在跑」区分开。
  */
 async function unlockMemory(memoryDir: string, ui: ExtensionUIContext): Promise<void> {
 	const lockPath = join(memoryDir, LOCK_FILE);
-	if ((await readLockStatus(lockPath)).kind === "absent") {
+	const status = await readLockStatus(lockPath);
+	if (status.kind === "absent") {
 		ui.notify("No lock present.", "info");
 		return;
 	}
-	const ok = await ui.confirm(
-		"Memory lock",
-		"Remove the memory lock file? Only do this if no memory operation is running.",
-	);
+	const question =
+		status.kind === "held"
+			? `Remove the memory lock file? It is held by ${describeHolder(status.holder)}. Only do this if no memory operation is running.`
+			: "Remove the memory lock file? Only do this if no memory operation is running.";
+	const ok = await ui.confirm("Memory lock", question);
 	if (!ok) return;
 	try {
 		await unlink(lockPath);
@@ -134,9 +117,7 @@ async function unlockMemory(memoryDir: string, ui: ExtensionUIContext): Promise<
 	}
 }
 
-function resolveDefault(cfg: MemoryConfig, task: "dream" | "autoSurfacing" | "extractMemories", key: "model"): string | undefined;
-function resolveDefault(cfg: MemoryConfig, task: "dream" | "autoSurfacing" | "extractMemories", key: "sessionPersistence"): SessionPersistenceConfig | undefined;
-function resolveDefault(cfg: MemoryConfig, task: "dream" | "autoSurfacing" | "extractMemories", key: "model" | "sessionPersistence"): string | SessionPersistenceConfig | undefined {
+function resolveDefault(cfg: MemoryConfig, task: "dream" | "autoSurfacing" | "extractMemories", key: "sessionPersistence"): SessionPersistenceConfig | undefined {
 	const perTask = cfg[task][key];
 	if (perTask !== undefined) return perTask;
 	return cfg.defaults?.[key];
@@ -147,6 +128,8 @@ export default function (pi: ExtensionAPI) {
 	let config: MemoryConfig | null = null;
 	/** 唯一写入通道（D4）。session_start 里建，之后工具 / extract / dream 都只经它读写。 */
 	let store: MemoryStore | null = null;
+	/** 配置错误态（模型校验失败或初始化失败）。/memory 重复显示它，直到用户改好配置并重启。 */
+	let configError: string | null = null;
 	let indexSnapshot = "";
 	let toolRegistered = false;
 	let currentCwd = "";
@@ -161,6 +144,28 @@ export default function (pi: ExtensionAPI) {
 	 */
 	const inFlight = new Set<Promise<unknown>>();
 
+	/** `enabled: false` 时给用户的唯一动作。工具文案与 `/memory` 状态共用同一份，避免两处漂移。 */
+	const ENABLE_HINT = 'set "enabled": true in memory.json and restart';
+
+	/**
+	 * 清空本 session 的运行时状态。三条早退路径（disabled / 配置错误 / 初始化失败）共用：
+	 * 残留上一 session 的 store 会让后续写入落到别的项目目录（Plan C ledger R51）。
+	 */
+	function resetSessionState(): void {
+		memoryDir = null;
+		store = null;
+		indexSnapshot = "";
+		injectedFiles.clear();
+	}
+
+	/** 统一的配置错误态：记录 → 清空运行时 → 通知。无 UI 时只记录（`/memory` 仍可读到）。 */
+	function failConfig(errors: string[], ctx: ExtensionContext): void {
+		configError = errors.join("\n");
+		resetSessionState();
+		if (!ctx.hasUI) return;
+		ctx.ui.notify(`pi-memory config error:\n${errors.map((e) => `- ${e}`).join("\n")}`, "error");
+	}
+
 	/** 登记一个后台 promise，settle 后自动摘掉；返回同一个 promise 以便调用方继续链式处理。 */
 	function track<T>(promise: Promise<T>): Promise<T> {
 		inFlight.add(promise);
@@ -177,44 +182,36 @@ export default function (pi: ExtensionAPI) {
 		getStore: () => store,
 		// biome-ignore lint/style/noNonNullAssertion: config 在 session_start 里赋值，工具执行必然晚于它
 		getConfig: () => config!,
-		getEnabled: () => config?.enabled ?? false,
+		getUnavailableMessage: () =>
+			configError
+				? `Memory not initialized — ${configError.split("\n")[0]}; run /memory for details`
+				: config?.enabled === false
+					? `Memory is disabled — ${ENABLE_HINT}`
+					: null,
 		searchSessions,
 		cwd: () => currentCwd,
 	};
 
-	pi.on("session_start", async (event, ctx) => {
-		// 先重置限流配额：本 session 若以 disabled 启动（下面提前 return），用户中途
-		// `/memory on` 之后仍应拿到一次失败通知 —— 否则上一 session 残留的 true 会一直吞掉它。
-		extractErrorNotified = false;
-		config = await loadConfig(ctx);
-		if (!config.enabled) return;
+	/**
+	 * 建立本 session 的记忆运行时：目录 → store → 索引来源 → 注册工具。
+	 *
+	 * 只在 `session_start` 调用，且调用方已确认 `config.enabled`（中途启用路径已随 `/memory on` 删除）。
+	 * 抛错 = 初始化失败，由调用方转成配置错误态（`configError`）。
+	 * `reason` 只有 `session_start` 会传：resume / fork / reload 用 transcript 的录制值（D14）。
+	 */
+	async function initMemory(ctx: ExtensionContext, reason?: string): Promise<void> {
+		// biome-ignore lint/style/noNonNullAssertion: 调用方已确认 enabled
+		const cfg = config!;
 		currentCwd = ctx.cwd;
-		memoryDir = await resolveMemoryDir(config, ctx.cwd);
-		store = new MemoryStore({
-			memoryDir,
-			indexMaxLines: config.memIndexMaxLines,
-			indexMaxBytes: config.memIndexMaxBytes,
-			lock: config.lock,
+		const dir = await resolveMemoryDir(cfg, ctx.cwd);
+		const activeStore = new MemoryStore({
+			memoryDir: dir,
+			indexMaxLines: cfg.memIndexMaxLines,
+			indexMaxBytes: cfg.memIndexMaxBytes,
+			lock: cfg.lock,
 		});
-
-		// v1 → v2 的自动迁移（spec §15 / D10）。必须在读 indexSnapshot **之前**：
-		// 否则本会话注入的是迁移前的旧索引。
-		// 失败不能拖垮 session_start：记忆迁移不了也比整个会话起不来好，而且 `.migrated`
-		// 未写 → 下次 session_start 会重试（spec §15.4）。
-		try {
-			const migration = await migrateIfNeeded(store);
-			if (migration && ctx.hasUI) {
-				ctx.ui.notify(
-					`Migrated ${migration.entries} memories from ${migration.files} topic files. Backup at ${migration.backupDir}`,
-					"info",
-				);
-			}
-		} catch (e) {
-			if (ctx.hasUI) {
-				// biome-ignore lint/suspicious/noExplicitAny: error catch
-				ctx.ui.notify(`Memory migration failed: ${(e as any).message}`, "error");
-			}
-		}
+		memoryDir = dir;
+		store = activeStore;
 
 		// D13 / D14：索引值在整个 session 内**冻结**。resume / fork / reload 必须用 transcript 里的
 		// 录制值 —— 否则被恢复会话的 system prompt 头部会被改写，而 memory_index 是头部的最后一段，
@@ -222,11 +219,10 @@ export default function (pi: ExtensionAPI) {
 		// sessionEntryToContextMessages）才回退磁盘读。
 		// 录制值**不再 re-sanitize**：写入当年已经净化过，而 sanitizeForInjection 是幂等的 ——
 		// 保持字节恒等更利于缓存。
-		const reason = (event as { reason?: string }).reason ?? "startup";
 		const useRecorded = reason === "resume" || reason === "fork" || reason === "reload";
 		const recorded = useRecorded ? readRecordedMemoryIndex(ctx.sessionManager) : null;
 		indexSnapshot =
-			recorded ?? (await buildIndexSection(store, config.memIndexInjectMaxLines, config.memIndexInjectMaxBytes));
+			recorded ?? (await buildIndexSection(activeStore, cfg.memIndexInjectMaxLines, cfg.memIndexInjectMaxBytes));
 
 		// register memory tool once
 		if (!toolRegistered) {
@@ -236,12 +232,52 @@ export default function (pi: ExtensionAPI) {
 			);
 			toolRegistered = true;
 		}
+	}
+	pi.on("session_start", async (event, ctx) => {
+		// 复位必须在**任何可能抛错的调用之前**跑完：冷启动与 disabled 会话都要有干净的一次失败通知
+		// 配额、干净的错误态，以及**清空的运行时**。loadConfig（里面的 getAgentDir）与下面的
+		// modelConfigErrors（宿主给的 registry 可能既没有 getAvailable 也没有 getAll）都属于宿主契约
+		// 之外的部分：它们一旦抛出而复位还没跑，上一 session 的 store / memoryDir 就会留在**已经注册**
+		// 的 `memory` 工具背后 —— 项目 B 的 agent 能写进项目 A 的目录（Plan C ledger R51）。
+		extractErrorNotified = false;
+		configError = null;
+		resetSessionState();
+		// `loadConfig` 抛错（`getAgentDir` / `isProjectTrusted` 属宿主契约）与初始化失败同一处理：
+		// 转成配置错误态，不把裸 reject 冒给宿主（spec §2.4）。用局部变量承接是为了让后面的收窄
+		// 不受 `config` 这个工厂作用域 let 影响。（nudge 块仍可能抛错，属既有暴露面，不在本次范围。）
+		let loaded: MemoryConfig;
+		try {
+			loaded = await loadConfig(ctx);
+		} catch (e) {
+			failConfig([`Failed to load memory config: ${e instanceof Error ? e.message : String(e)}`], ctx);
+			return;
+		}
+		config = loaded;
+		// 状态已经干净，disabled 直接早退即可。
+		if (!loaded.enabled) return;
+		try {
+			// 启动校验（spec §2.3）：模型键缺失 / 不可解析 → 本会话**完全不初始化**
+			//（不解析目录、不建 store、不注册工具），错误态由 `/memory` 重复显示。
+			// 校验本身抛错（registry 不合契约）也走同一个 catch：failConfig 自己会复位运行时。
+			const errors = modelConfigErrors(loaded, (value) => resolveModel(value, ctx.modelRegistry) !== undefined);
+			if (errors.length > 0) {
+				failConfig(errors, ctx);
+				return;
+			}
+			await initMemory(ctx, (event as { reason?: string }).reason);
+		} catch (e) {
+			// spec §2.4：初始化失败走同一个错误态，不冒泡给宿主（那只会变成一条裸报错）。
+			failConfig([`Failed to initialize memory: ${e instanceof Error ? e.message : String(e)}`], ctx);
+			return;
+		}
 
 		// nudge
-		if (ctx.hasUI) {
+		// 先拷到 const：initMemory 里赋的值，TS 在本函数的控制流里看不到收窄。
+		const nudgeDir = memoryDir;
+		if (ctx.hasUI && nudgeDir) {
 			// 同步段快照：shouldNudge / confirm 之后的 fire-and-forget 链不再碰 ctx（见 notifyDream）。
 			const ui = ctx.ui;
-			const { nudge, message, sessions } = await shouldNudge(memoryDir, config, ctx.cwd);
+			const { nudge, message, sessions } = await shouldNudge(nudgeDir, config, ctx.cwd);
 			if (nudge) {
 				const ok = await ui.confirm("Memory Consolidation", `${message}\n\nConsolidate memory files now?`);
 				// dream 需要 store（整轮逻辑锁 + 快照都挂在它上面）；这里必然非空，但 const 拷贝让 TS 也能看到。
@@ -249,9 +285,9 @@ export default function (pi: ExtensionAPI) {
 				if (ok && activeStore) {
 					// Fire-and-forget: does not block session_start. The headless
 					// dream agent runs independently; completion notifies the user.
-					const dreamModel = resolveDefault(config, "dream", "model");
+					const dreamModel = requiredModel(config, "dream");
 					const dreamThinkLevel = config.dream.thinkLevel;
-					const dir = memoryDir;
+					const dir = nudgeDir;
 					ui.setStatus("dream", "Consolidating memory...");
 					const dreamRun = runDream({
 						model: dreamModel,
@@ -260,7 +296,6 @@ export default function (pi: ExtensionAPI) {
 						store: activeStore,
 						maxLines: config.memIndexMaxLines,
 						modelRegistry: ctx.modelRegistry,
-						parentModel: ctx.model,
 						sessionPersistence: resolveDefault(config, "dream", "sessionPersistence"),
 						// dream 的 7 个 action 只注入它自己的 headless session（D12）；整轮持锁与
 						// 进入时的全目录快照都在 runDream 里，所以内部原语两个选项都跳过。
@@ -327,9 +362,8 @@ export default function (pi: ExtensionAPI) {
 						injectedFiles,
 						autoSurfacing.maxFiles,
 						autoSurfacing.thinkLevel,
-						resolveDefault(config, "autoSurfacing", "model"),
+						requiredModel(config, "autoSurfacing"),
 						ctx.modelRegistry,
-						ctx.model,
 						memoryDir,
 						resolveDefault(config, "autoSurfacing", "sessionPersistence"),
 					);
@@ -404,6 +438,9 @@ export default function (pi: ExtensionAPI) {
 		const extractConfig = config.extractMemories;
 		if (!extractConfig?.enabled) return;
 		if (!event.messages || event.messages.length === 0) return;
+		// 守卫之后立刻取值：requiredModel 抛错必须发生在这里（agent_end 直接失败），而不是在
+		// runExtract({...}) 的字面量求值中途 —— 那时 track / .then 的收尾链已经无从挂上。
+		const extractModel = requiredModel(config, "extractMemories");
 		// 本轮经 extract 的工具真实写入了几条（工具的 onWrite 回调计数，spec §14）。
 		let written = 0;
 		// pi 的 `ExtensionContext` 是代理：`hasUI` / `ui` 的 getter 会先 `runner.assertActive()`，
@@ -413,7 +450,7 @@ export default function (pi: ExtensionAPI) {
 		const ui = ctx.hasUI ? ctx.ui : undefined;
 		const extractRun = runExtract({
 			agentsMdBlocks: extractAgentsMdBlocks(lastSystemPrompt),
-			model: resolveDefault(config, "extractMemories", "model"),
+			model: extractModel,
 			thinkLevel: extractConfig.thinkLevel,
 			memoryDir: dir,
 			store: activeStore,
@@ -424,7 +461,6 @@ export default function (pi: ExtensionAPI) {
 			maxToolResultChars: extractConfig.maxToolResultChars,
 			maxAssistantChars: extractConfig.maxAssistantChars,
 			modelRegistry: ctx.modelRegistry,
-			parentModel: ctx.model,
 			// extract 的工具集与主 agent 相同（5 个 action，D12），且**只**注入它自己的 headless session。
 			// 不开 skipSnapshot：extract 没有整轮快照，它的每次写入都该留下自己的回滚点。
 			customTools: [
@@ -467,20 +503,51 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("memory", {
-		description: "Show memory status, toggle enabled, or remove a stale lock",
+		description: "Show memory status or remove a stale lock",
 		handler: async (args, ctx) => {
-			const activeStore = store;
-			if (!config || !memoryDir || !activeStore) {
+			// 配置都读不出来（`loadConfig` 抛错）时也要报真实原因，而不是笼统的「未初始化」——
+			// `/memory` 是重读错误态的唯一入口。首次会话就失败时 `config` 仍是 null，所以这里先看错误态。
+			if (!config) {
+				if (configError) {
+					ctx.ui.notify(
+						["Memory: misconfigured", "Dir: not initialized", ...configError.split("\n").map((e) => `- ${e}`)].join("\n"),
+						"info",
+					);
+					return;
+				}
 				ctx.ui.notify("Memory not initialized.", "info");
 				return;
 			}
-			if (args === "off" || args === "on") {
-				config = { ...config, enabled: args === "on" };
-				ctx.ui.notify(`Memory ${args}`, "info");
+			if (args === "unlock") {
+				// `unlock` 只需要**目录**、不需要 store：以 disabled 启动的会话也要能清锁
+				//（它是崩溃遗留 `.lock` 的唯一人工入口，spec §19）。
+				let dir = memoryDir;
+				if (!dir) {
+					// 目录解析本身可能失败（HOME 不可写 / git 探测炸了）：失败要变成一条可读的 error
+					// 通知，不能冒泡成命令 handler 抛错（那只会变成一条裸的宿主报错）。
+					try {
+						dir = await resolveMemoryDir(config, ctx.cwd);
+					} catch (e) {
+						ctx.ui.notify(
+							`Failed to resolve memory dir: ${e instanceof Error ? e.message : String(e)}`,
+							"error",
+						);
+						return;
+					}
+				}
+				await unlockMemory(dir, ctx.ui);
 				return;
 			}
-			if (args === "unlock") {
-				await unlockMemory(memoryDir, ctx.ui);
+			// 先拷到 const：`store` / `memoryDir` 是工厂作用域的 let，异步回调里 TS 不保留外层收窄。
+			const activeStore = store;
+			const dir = memoryDir;
+			if (!dir || !activeStore) {
+				// configError 非空 = 校验或初始化失败（`/memory` 是用户重读错误的唯一入口）；
+				// 否则只可能是配置里 enabled 为假。
+				const lines = configError
+					? ["Memory: misconfigured", "Dir: not initialized", ...configError.split("\n").map((e) => `- ${e}`)]
+					: ["Memory: disabled", `Dir: not initialized — ${ENABLE_HINT}`];
+				ctx.ui.notify(lines.join("\n"), "info");
 				return;
 			}
 			// 容量用写入那一侧的口径（memIndexMax*）：用户要知道的是「还能不能写」，
@@ -490,12 +557,11 @@ export default function (pi: ExtensionAPI) {
 			const cap = indexCapacity(indexRaw, config.memIndexMaxLines, config.memIndexMaxBytes);
 			const summary = [
 				`Memory: ${config.enabled ? "enabled" : "disabled"}`,
-				`Dir: ${memoryDir}`,
+				`Dir: ${dir}`,
 				`Index: ${cap.lineCount}/${config.memIndexMaxLines} lines, ${cap.byteLength}/${config.memIndexMaxBytes} bytes, ${parseEntryIndex(indexRaw).unrecognized} unrecognized lines`,
 				`Entries: ${(await activeStore.listEntries()).length}`,
-				`Last dream: ${(await readDreamMeta(memoryDir))?.lastDreamAt ?? "never"}`,
-				`Migration: ${await readMigrationStatus(memoryDir)}`,
-				`Lock: ${await lockStatusLine(memoryDir)}`,
+				`Last dream: ${(await readDreamMeta(dir))?.lastDreamAt ?? "never"}`,
+				`Lock: ${await lockStatusLine(dir)}`,
 			].join("\n");
 			ctx.ui.notify(summary, "info");
 		},
@@ -516,15 +582,16 @@ export default function (pi: ExtensionAPI) {
 			const ok = await ctx.ui.confirm("Dream", "Consolidate all memory files? This rewrites them in-place.");
 			if (!ok) return;
 			const dir = memoryDir;
+			// 先取模型再改状态：requiredModel 抛错时不能把 "dream" 状态留在那儿（这条链没有 .finally）。
+			const dreamModel = requiredModel(config, "dream");
 			ui?.setStatus("dream", "Consolidating memory...");
 			const dreamRun = runDream({
-				model: resolveDefault(config, "dream", "model"),
+				model: dreamModel,
 				thinkLevel: config.dream.thinkLevel,
 				memoryDir,
 				store: activeStore,
 				maxLines: config.memIndexMaxLines,
 				modelRegistry: ctx.modelRegistry,
-				parentModel: ctx.model,
 				sessionPersistence: resolveDefault(config, "dream", "sessionPersistence"),
 				customTools: [
 					createMemoryTool(toolDeps, {

package/package.json

@@ -3,7 +3,7 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"version": "2.0.0",
+	"version": "2.1.1",
 	"description": "File-system driven persistent memory layer for pi coding agent",
 	"license": "MIT",
 	"repository": {
@@ -39,9 +39,9 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.14",
-		"@types/node": "^26.6.2",
+		"@types/node": "^26.6.3",
 		"typebox": "^1.3.34",
 		"typescript": "~7.0.2",
-		"vitest": "^5.0.1"
+		"vitest": "^5.0.2"
 	}
 }

package/src/agent-runner.ts

@@ -1,4 +1,3 @@
-import type { Model } from "@earendil-works/pi-ai";
 import { join } from "node:path";
 import {
 	type AgentSession,
@@ -18,8 +17,8 @@ export interface HeadlessAgentOpts {
 	task: string;
 	cwd: string;
 	modelRegistry: import("@earendil-works/pi-coding-agent").ModelRegistry;
-	model?: string;
-	parentModel?: Model<any>;
+	/** 必填：模型必须来自显式配置（启动校验已经保证可解析），没有父模型回退。 */
+	model: string;
 	thinkLevel?: ThinkLevel;
 	maxTurns?: number;
 	signal?: AbortSignal;
@@ -56,10 +55,12 @@ const GRACE_TURNS = 1;
  * so pi-memory's own before_agent_start cannot recurse.
  */
 export async function runHeadlessAgent(opts: HeadlessAgentOpts): Promise<string> {
-	// 1. Resolve model: undefined → parentModel; otherwise fuzzy resolve (fallback parent)
-	const resolvedModel = !opts.model
-		? opts.parentModel
-		: (resolveModel(opts.model, opts.modelRegistry) ?? opts.parentModel);
+	// 模型必须显式配置且可解析：启动校验之外再挡一次（会话中途凭据被移除等），
+	// 结果是显式失败，而不是静默用父会话模型跑一个用户没选的模型。
+	const resolvedModel = resolveModel(opts.model, opts.modelRegistry);
+	if (!resolvedModel) {
+		throw new Error(`model "${opts.model}" is not resolvable (unknown id or missing credentials)`);
+	}
 
 	// 2. Build a pure resource loader (no extensions/skills/context files/etc.)
 	const settingsManager = SettingsManager.inMemory();

package/src/config.ts

@@ -15,6 +15,7 @@ export interface SessionPersistenceConfig {
 
 /** Shared defaults that per-task configs inherit. Per-task fields override these. */
 export interface DefaultsConfig {
+	/** 共享模型：per-task 未指定时生效。**没有默认值** —— 必须由用户显式配置。 */
 	model?: string;
 	sessionPersistence?: SessionPersistenceConfig;
 }
@@ -86,6 +87,7 @@ export interface MemoryConfig {
 export const DEFAULT_CONFIG: MemoryConfig = {
 	enabled: true,
 	// headless 子会话默认只在内存里跑：extract / dream / 侧查询都不该往用户的 sessions 目录里落盘。
+	// **没有模型默认值**：model 必须由用户显式配置（defaults.model 或 per-task），否则 session_start 报错。
 	defaults: { sessionPersistence: { enabled: false } },
 	memoryDir: join(homedir(), CONFIG_DIR_NAME, "memory"),
 	memIndexMaxLines: 200,
@@ -112,6 +114,54 @@ export const DEFAULT_CONFIG: MemoryConfig = {
 	},
 };
 
+/** 需要显式模型的子任务。顺序固定：dream → extractMemories → autoSurfacing（校验信息按此顺序输出）。 */
+export type ModelTask = "dream" | "extractMemories" | "autoSurfacing";
+
+/** 某任务的模型值：per-task 优先，其次共享的 defaults.model。 */
+function taskModel(cfg: MemoryConfig, task: ModelTask): string | undefined {
+	return cfg[task].model ?? cfg.defaults?.model;
+}
+
+/**
+ * 会执行的任务及其模型值。`enabled: false` 的会话不执行任何一个任务 —— 包括 dream，
+ * 因为 `/dream` 命令与 nudge 都被 `config.enabled` 挡住。
+ */
+export function requiredModels(cfg: MemoryConfig): Array<{ task: ModelTask; value: string | undefined }> {
+	if (!cfg.enabled) return [];
+	const out: Array<{ task: ModelTask; value: string | undefined }> = [
+		{ task: "dream", value: taskModel(cfg, "dream") },
+	];
+	if (cfg.extractMemories.enabled) out.push({ task: "extractMemories", value: taskModel(cfg, "extractMemories") });
+	if (cfg.autoSurfacing.enabled) out.push({ task: "autoSurfacing", value: taskModel(cfg, "autoSurfacing") });
+	return out;
+}
+
+/**
+ * 启动校验：空数组 = 通过。
+ * `resolve` 由调用方注入（生产时是 `(v) => resolveModel(v, ctx.modelRegistry) !== undefined`），
+ * 因此本函数不依赖 SDK 的 registry 类型，可用假 resolve 单测。
+ */
+export function modelConfigErrors(cfg: MemoryConfig, resolve: (value: string) => boolean): string[] {
+	const errors: string[] = [];
+	for (const { task, value } of requiredModels(cfg)) {
+		if (value === undefined) {
+			errors.push(`no model for ${task} — set "${task}.model" or "defaults.model" in memory.json`);
+		} else if (!resolve(value)) {
+			errors.push(`model "${value}" for ${task} is not resolvable (unknown id or missing credentials)`);
+		}
+	}
+	return errors;
+}
+
+/** 已通过启动校验的模型值；缺失时抛错（真正的守卫在 session_start，这里是防御）。 */
+export function requiredModel(cfg: MemoryConfig, task: ModelTask): string {
+	const value = taskModel(cfg, task);
+	if (value === undefined) {
+		throw new Error(`no model for ${task} — set "${task}.model" or "defaults.model" in memory.json`);
+	}
+	return value;
+}
+
 function expandTilde(p: string): string {
 	if (p === "~") return homedir();
 	if (p.startsWith("~/")) return join(homedir(), p.slice(2));

package/src/dream.ts

@@ -1,6 +1,5 @@
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
-import type { Model } from "@earendil-works/pi-ai";
 import type { ModelRegistry, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { runHeadlessAgent } from "./agent-runner";
 import type { SessionPersistenceConfig, ThinkLevel } from "./config";
@@ -52,7 +51,8 @@ Work only through the \`memory\` tool. When done, output a concise summary of wh
 }
 
 export interface RunDreamOpts {
-	model?: string;
+	/** 必填：模型来自显式配置（启动校验已保证可解析），没有父模型回退。 */
+	model: string;
 	thinkLevel: ThinkLevel;
 	memoryDir: string;
 	/** 唯一写入通道。dream 的整轮互斥与快照都挂在它上面。 */
@@ -60,7 +60,6 @@ export interface RunDreamOpts {
 	/** 索引行数硬上限（= `config.memIndexMaxLines`），写进 prompt 让 dream 承担容量管理。 */
 	maxLines: number;
 	modelRegistry: ModelRegistry;
-	parentModel?: Model<any>;
 	sessionPersistence?: SessionPersistenceConfig;
 	/** dream 专属的 7-action `memory` 工具（D12）：只注入这个 headless session，不进主 agent 的 schema。 */
 	customTools: ToolDefinition[];
@@ -72,7 +71,7 @@ export interface RunDreamOpts {
  * - `.backups`（目录）跳过 —— 快照不套快照；不带 `withFileTypes` 时它会被 `cp` 递归复制。
  * - `sessions/`（目录，`sessionPersistence.enabled` 时存在）跳过 —— 同理，而且它可能很大。
  *   `createSnapshot` 的 `cp` 遇到目录会抛 `ERR_FS_EISDIR`（非 ENOENT → fail-closed 上抛 → dream 直接失败）。
- * - `.lock` / `.migrated` / `.dream-meta.json` 跳过（都是 dotfile）：锁记录与标记不属于记忆内容。
+ * - `.lock` / `.dream-meta.json` 跳过（都是 dotfile）：锁记录与元数据不属于记忆内容。
  * - 其余全部 `*.md`（entry 文件 + `MEMORY.md`）都会被快照。
  */
 async function snapshotFiles(memoryDir: string): Promise<string[]> {
@@ -112,7 +111,6 @@ export async function runDream(opts: RunDreamOpts): Promise<string> {
 			cwd: opts.memoryDir,
 			modelRegistry: opts.modelRegistry,
 			model: opts.model,
-			parentModel: opts.parentModel,
 			thinkLevel: opts.thinkLevel,
 			maxTurns: undefined,
 			timeoutMs: 600_000,