dsh-mnemon 0.3.4 → 0.3.6

package/lib/index.js

@@ -23,6 +23,17 @@ const MNEMON_SETTINGS_CHANNEL = "/dsh-mnemon-settings";
 const MNEMON_SETTINGS_NAMESPACE = "mnemon";
 const DEFAULT_EMBEDDING_ENDPOINT = "http://localhost:11434";
 const DEFAULT_EMBEDDING_MODEL = "nomic-embed-text";
+const EMBEDDING_PROTOCOL_AUTO = "auto";
+const EMBEDDING_PROTOCOL_OLLAMA = "ollama";
+const EMBEDDING_PROTOCOL_OPENAI = "openai";
+/** Default protocol defers to Mnemon's /v1 auto-detection. */
+const DEFAULT_EMBEDDING_PROTOCOL = EMBEDDING_PROTOCOL_AUTO;
+/** Wire protocols accepted by the embedding protocol override; single source for schema, resolver, and UI validation. */
+const MNEMON_EMBEDDING_PROTOCOLS = [
+	EMBEDDING_PROTOCOL_AUTO,
+	EMBEDDING_PROTOCOL_OLLAMA,
+	EMBEDDING_PROTOCOL_OPENAI
+];
 const CATEGORIES = [
 	"preference",
 	"decision",
@@ -114,7 +125,9 @@ const TaskAgentModelSchema = z.object({
 const MnemonEmbeddingSchema = z.object({
 	enabled: z.boolean().default(false),
 	endpoint: z.string().default(DEFAULT_EMBEDDING_ENDPOINT),
-	model: z.string().default(DEFAULT_EMBEDDING_MODEL)
+	model: z.string().default(DEFAULT_EMBEDDING_MODEL),
+	apiKey: z.string().default(""),
+	protocol: z.union(MNEMON_EMBEDDING_PROTOCOLS).default(DEFAULT_EMBEDDING_PROTOCOL)
 });
 const RecallQualitySchema = z.object({
 	policy: z.string().default(DEFAULT_RECALL_QUALITY_POLICY),
@@ -175,7 +188,9 @@ const Config = z.object({
 	embedding: MnemonEmbeddingSchema.default({
 		enabled: false,
 		endpoint: DEFAULT_EMBEDDING_ENDPOINT,
-		model: DEFAULT_EMBEDDING_MODEL
+		model: DEFAULT_EMBEDDING_MODEL,
+		apiKey: "",
+		protocol: DEFAULT_EMBEDDING_PROTOCOL
 	}),
 	memoryTopology: MemoryTopologySchema,
 	recallQuality: RecallQualitySchema.default({
@@ -325,10 +340,16 @@ function resolveEmbedding(value) {
 	const normalizedEndpoint = endpoint.replace(/\/+$/u, "");
 	const model = optionalText$1(value?.model) ?? "nomic-embed-text";
 	if (model.length > 200 || /[\u0000-\u001f\u007f]/u.test(model)) throw new Error("dsh-mnemon: embedding model must contain 1..200 characters without control characters");
+	const apiKey = optionalText$1(value?.apiKey) ?? "";
+	if (apiKey.length > 2048 || /[\u0000-\u001f\u007f]/u.test(apiKey)) throw new Error("dsh-mnemon: embedding API key must contain 0..2048 characters without control characters");
+	const protocol = value?.protocol ?? "auto";
+	if (!MNEMON_EMBEDDING_PROTOCOLS.includes(protocol)) throw new Error(`dsh-mnemon: unsupported embedding protocol: ${String(protocol)}`);
 	return {
 		enabled: value?.enabled === true,
 		endpoint: normalizedEndpoint,
-		model
+		model,
+		apiKey,
+		protocol
 	};
 }
 function resolveRecallQuality(value) {
@@ -1930,20 +1951,7 @@ function applyAgentMemoryViewWake(assembly, wake) {
 		name: RUNTIME_MEMORY_PROTOCOL_SECTION_NAME,
 		text: protocol
 	});
-	const rendered = wake === void 0 ? "" : memoryPromptText(wake.text);
-	let found = false;
-	const contexts = assembly.contexts.map((context) => {
-		if (context.name !== "mnemon:runtime-memory") return context;
-		found = true;
-		return {
-			...context,
-			text: rendered
-		};
-	});
-	if (!found) contexts.push({
-		name: RUNTIME_MEMORY_CONTEXT_NAME,
-		text: rendered
-	});
+	const contexts = assembly.contexts.filter((context) => context.name !== RUNTIME_MEMORY_CONTEXT_NAME);
 	return {
 		...assembly,
 		sections,
@@ -1963,21 +1971,12 @@ function registerGuidance(ctx, config) {
 }
 /** Project only the immutable Wake pinned by the root Agent lifecycle. */
 function registerAgentMemoryViewContext(agent, wake) {
-	const prompt = scopedSystemPrompt(agent);
-	const stopProtocol = prompt?.section?.({
+	const stopProtocol = scopedSystemPrompt(agent)?.section?.({
 		name: RUNTIME_MEMORY_PROTOCOL_SECTION_NAME,
 		order: 145,
 		text: () => wakeHasRuntimeMemory(wake()) ? RUNTIME_MEMORY_PROTOCOL : ""
 	});
-	const stopContext = prompt?.context?.({
-		name: RUNTIME_MEMORY_CONTEXT_NAME,
-		order: 145,
-		text: () => {
-			const current = wake();
-			return current === void 0 ? "" : memoryPromptText(current.text);
-		}
-	});
-	return disposer(stopProtocol, stopContext);
+	return disposer(stopProtocol);
 }
 //#endregion
 //#region src/pack.ts
@@ -2820,20 +2819,25 @@ function findMnemonCommand(config, options = {}) {
 	const env = options.env ?? process.env;
 	const home = options.home ?? homedir();
 	const isExecutable = options.isExecutable ?? ((path) => executable$1(path, platform));
-	if (config.cliPath !== void 0) return expandHome$1(config.cliPath, home, platform);
-	const envPath = envValue(env, "MNEMON_CLI_PATH", platform)?.trim();
-	if (envPath !== void 0 && envPath !== "") {
-		const path = expandHome$1(envPath, home, platform);
-		if (isExecutable(path)) return path;
-	}
 	const paths = pathApi(platform);
-	for (const directory of (envValue(env, "PATH", platform) ?? "").split(paths.delimiter)) {
-		if (directory === "") continue;
-		for (const name of platform === "win32" ? ["mnemon.exe"] : ["mnemon"]) {
+	const resolveCommand = (command) => {
+		const expanded = expandHome$1(command, home, platform);
+		if (expanded.includes("/") || expanded.includes("\\")) return expanded;
+		const name = platform === "win32" && paths.extname(expanded) === "" ? `${expanded}.exe` : expanded;
+		for (const directory of (envValue(env, "PATH", platform) ?? "").split(paths.delimiter)) {
+			if (directory === "") continue;
 			const path = paths.join(directory, name);
 			if (isExecutable(path)) return path;
 		}
+	};
+	if (config.cliPath !== void 0) return resolveCommand(config.cliPath);
+	const envPath = envValue(env, "MNEMON_CLI_PATH", platform)?.trim();
+	if (envPath !== void 0 && envPath !== "") {
+		const path = resolveCommand(envPath);
+		if (path !== void 0 && isExecutable(path)) return path;
 	}
+	const fromPath = resolveCommand("mnemon");
+	if (fromPath !== void 0) return fromPath;
 	for (const path of commonCliPaths(platform, env, home)) if (isExecutable(path)) return path;
 }
 var MnemonCliError = class extends Error {
@@ -2846,19 +2850,25 @@ var MnemonCliError = class extends Error {
 		this.stderr = stderr;
 	}
 };
-const EMBEDDING_ENVIRONMENT_KEYS = /* @__PURE__ */ new Set(["MNEMON_EMBED_ENDPOINT", "MNEMON_EMBED_MODEL"]);
+const EMBEDDING_ENVIRONMENT_KEYS = /* @__PURE__ */ new Set([
+	"MNEMON_EMBED_ENDPOINT",
+	"MNEMON_EMBED_MODEL",
+	"MNEMON_EMBED_API_KEY",
+	"MNEMON_EMBED_PROTOCOL"
+]);
 /** Preserve the Host environment while making saved embedding overrides authoritative. */
 function processEnvironment(config) {
 	if (!config.embedding.enabled) return void 0;
 	return {
 		...Object.fromEntries(Object.entries(process.env).filter(([key]) => !EMBEDDING_ENVIRONMENT_KEYS.has(key.toUpperCase()))),
 		MNEMON_EMBED_ENDPOINT: config.embedding.endpoint,
-		MNEMON_EMBED_MODEL: config.embedding.model
+		MNEMON_EMBED_MODEL: config.embedding.model,
+		MNEMON_EMBED_API_KEY: config.embedding.apiKey,
+		...config.embedding.protocol === "auto" ? {} : { MNEMON_EMBED_PROTOCOL: config.embedding.protocol }
 	};
 }
 function createRunner(config, processRunner = runProcess, workspaceRoot) {
-	const found = findMnemonCommand(config);
-	const command = found ?? config.cliPath ?? "mnemon";
+	const currentCommand = () => findMnemonCommand(config) ?? config.cliPath ?? "mnemon";
 	let processQueue = Promise.resolve();
 	const globalArgs = (store) => {
 		const args = [];
@@ -2891,7 +2901,7 @@ function createRunner(config, processRunner = runProcess, workspaceRoot) {
 		};
 		let result;
 		try {
-			result = await processRunner(command, argv, processOptions);
+			result = await processRunner(currentCommand(), argv, processOptions);
 		} catch (error) {
 			throw new MnemonCliError(`${error instanceof Error ? error.message : String(error)}. ${process.platform === "win32" ? "Install the official Mnemon Windows release, ensure mnemon.exe is on PATH or under %LOCALAPPDATA%\\Programs\\mnemon, or set MNEMON_CLI_PATH or mnemon.cliPath to its absolute path." : "Install Mnemon and ensure \"mnemon\" is on PATH, or set MNEMON_CLI_PATH or mnemon.cliPath."}`);
 		}
@@ -2907,8 +2917,13 @@ function createRunner(config, processRunner = runProcess, workspaceRoot) {
 		return result;
 	};
 	return {
-		command,
-		commandFound: found !== void 0 && executable$1(found),
+		get command() {
+			return currentCommand();
+		},
+		get commandFound() {
+			const found = findMnemonCommand(config);
+			return found !== void 0 && executable$1(found);
+		},
 		config,
 		async runJson(args, options) {
 			const stdout = await execute(args, options);
@@ -4318,8 +4333,9 @@ var MnemonService = class {
 	/** Probe the effective Mnemon embedding runtime and its default Store coverage. */
 	async embeddingStatus(signal) {
 		const output = record$1(await this.runner.runJson(["embed", "--status"], signal === void 0 ? {} : { signal }));
-		const available = output?.ollama_available;
+		const available = output?.embedding_available ?? output?.ollama_available;
 		const model = text$1(output?.model)?.trim();
+		const protocol = text$1(output?.protocol)?.trim();
 		const totalInsights = number(output?.total_insights);
 		const embedded = number(output?.embedded);
 		const coverage = text$1(output?.coverage)?.trim();
@@ -4329,7 +4345,8 @@ var MnemonService = class {
 			model,
 			totalInsights,
 			embedded,
-			coverage
+			coverage,
+			...protocol !== void 0 && protocol.length <= 32 && !/[\u0000-\u001f\u007f]/u.test(protocol) ? { protocol } : {}
 		};
 	}
 	async status(signal) {
@@ -6412,8 +6429,16 @@ function boundedModelText(value, maximum) {
 function insightDigest(result) {
 	return sha256(result.content.trim().replace(/\s+/gu, " "));
 }
-function recallQueryDigest(query) {
-	return sha256((query.match(/[\p{L}\p{N}]+/gu) ?? []).join(" ").toLocaleLowerCase());
+function recallQueryDigest(request) {
+	const lexical = (request.query.match(/[\p{L}\p{N}]+/gu) ?? []).join(" ").toLocaleLowerCase();
+	return sha256(JSON.stringify({
+		query: lexical,
+		memoryBodyIds: [...request.memoryBodyIds ?? []].sort()
+	}));
+}
+/** A replay must still respect the current call's selected Source subset. */
+function replayEvidence(results, memoryBodyIds) {
+	return structuredClone(memoryBodyIds === void 0 ? results : results.filter((result) => result.memoryBodyId !== void 0 && memoryBodyIds.includes(result.memoryBodyId)));
 }
 /** Admit a small, deduplicated evidence envelope after Provider quality policy. */
 function boundedModelInsights(results, admission = {}) {
@@ -6863,7 +6888,7 @@ var MnemonSubagentCoordinator = class {
 	};
 	runtimeQueue = Promise.resolve();
 	documentQueue = Promise.resolve();
-	retrievalTurns = /* @__PURE__ */ new Map();
+	retrievalTurns = /* @__PURE__ */ new WeakMap();
 	constructor(subagents, runtimeMemoryOrSource, documents, resultRuntime, taskAgentModelResolver, runtimeMaintenanceMaxTokensResolver) {
 		this.subagents = subagents;
 		this.runtimeMemoryOrSource = runtimeMemoryOrSource;
@@ -6887,17 +6912,19 @@ var MnemonSubagentCoordinator = class {
 			...limit === void 0 ? {} : { limit }
 		});
 	}
-	/** Admit at most one model-facing Documents query for one root turn. */
+	/** Admit at most one model-facing Documents query for one executing turn. */
 	claimDocumentSearch(parent) {
 		const authority = this.turnAuthority(parent, false);
 		if (authority === void 0) return true;
-		const retrieval = this.turnRetrievalState(authority.turnId);
+		const retrieval = this.turnRetrievalState(authority.context);
 		if (retrieval.documentSearchClaimed === true) return false;
 		retrieval.documentSearchClaimed = true;
 		return true;
 	}
 	async recall(parent, request, signal, options = {}) {
+		signal.throwIfAborted();
 		const authority = this.recallAuthority(parent, options.requirePinnedView === true);
+		const service = authority?.service ?? this.serviceFor(parent);
 		const limited = {
 			query: request.query,
 			...request.mode === void 0 ? {} : { mode: request.mode },
@@ -6905,15 +6932,15 @@ var MnemonSubagentCoordinator = class {
 			...request.memoryBodyIds === void 0 ? {} : { memoryBodyIds: request.memoryBodyIds }
 		};
 		const scoped = this.scopeRecallWithAuthority(limited, authority);
-		const digest = authority === void 0 ? void 0 : recallQueryDigest(scoped.query);
-		const retrieval = authority === void 0 ? void 0 : this.turnRetrievalState(authority.turnId);
+		const digest = authority === void 0 ? void 0 : recallQueryDigest(scoped);
+		const retrieval = authority === void 0 ? void 0 : this.turnRetrievalState(authority.context);
 		const repeated = digest === void 0 ? void 0 : retrieval?.recallAttempts.find((attempt) => attempt.queryDigest === digest);
 		if (repeated !== void 0) {
 			const previous = repeated.result ?? await repeated.pending;
 			return {
 				query: previous?.query ?? scoped.query,
 				mode: previous?.mode ?? scoped.mode ?? "smart",
-				results: structuredClone(previous?.results ?? []),
+				results: replayEvidence(previous?.results ?? [], scoped.memoryBodyIds),
 				hint: retrieval?.recallAttempts.length === MODEL_RECALL_ATTEMPT_LIMIT ? "This Recall query already ran. The Host replayed its admitted evidence without another Provider query. The turn Recall budget is closed; stop retrieval and answer from the evidence or state what remains unknown." : "This Recall query already ran. The Host replayed its admitted evidence without another Provider query. If this evidence is insufficient, use at most one materially different focused query; otherwise stop retrieval."
 			};
 		}
@@ -6923,7 +6950,7 @@ var MnemonSubagentCoordinator = class {
 			return {
 				query: previous?.query ?? scoped.query,
 				mode: previous?.mode ?? scoped.mode ?? "smart",
-				results: structuredClone(previous?.results ?? []),
+				results: replayEvidence(previous?.results ?? [], scoped.memoryBodyIds),
 				hint: "The two-query turn Recall budget is exhausted. The Host replayed the latest admitted evidence without another Provider query; stop retrieval and answer from the evidence or state what remains unknown."
 			};
 		}
@@ -6933,7 +6960,8 @@ var MnemonSubagentCoordinator = class {
 		if (attempt !== void 0 && retrieval !== void 0) retrieval.recallAttempts.push(attempt);
 		const operation = (async () => {
 			if (predecessor !== void 0) await predecessor;
-			const result = await this.serviceFor(parent).search(scoped, signal);
+			signal.throwIfAborted();
+			const result = await service.search(scoped, signal);
 			const priorResults = (retrieval?.recallAttempts.slice(0, attemptIndex) ?? []).flatMap((entry) => entry.result?.results ?? []);
 			const priorContentCharacters = priorResults.reduce((total, insight) => total + insight.content.length, 0);
 			const requestedLimit = Math.min(limited.limit ?? MODEL_RECALL_RESULT_LIMIT, MODEL_RECALL_RESULT_LIMIT);
@@ -6974,7 +7002,7 @@ var MnemonSubagentCoordinator = class {
 			if (attempt?.pending === operation) delete attempt.pending;
 		}
 	}
-	/** Bind a model read to the Source state pinned by its root turn. */
+	/** Bind a model read to the Source state pinned by its own executing turn. */
 	scopeRecallRequest(agent, request, requirePinnedView = false) {
 		const authority = this.recallAuthority(agent, requirePinnedView);
 		return this.scopeRecallWithAuthority(request, authority);
@@ -7004,9 +7032,11 @@ var MnemonSubagentCoordinator = class {
 		return requested;
 	}
 	async related(parent, id, memoryBodyId, signal, options = {}) {
+		signal.throwIfAborted();
 		const authority = this.recallAuthority(parent, options.requirePinnedView === true);
+		const service = authority?.service ?? this.serviceFor(parent);
 		const selected = this.scopeRelatedWithAuthority(memoryBodyId, authority);
-		const retrieval = authority === void 0 ? void 0 : this.turnRetrievalState(authority.turnId);
+		const retrieval = authority === void 0 ? void 0 : this.turnRetrievalState(authority.context);
 		const reference = `${selected ?? ""}/${id}`;
 		if (retrieval !== void 0 && !retrieval.evidenceReferences.has(reference)) return {
 			query: `related:${id}`,
@@ -7025,13 +7055,13 @@ var MnemonSubagentCoordinator = class {
 			return {
 				query: previous?.query ?? `related:${id}`,
 				mode: previous?.mode ?? "related",
-				results: structuredClone(previous?.results ?? []),
+				results: replayEvidence(previous?.results ?? [], selected === void 0 ? void 0 : [selected]),
 				hint: retrieval.relatedDigest === digest ? "This exact Related traversal already ran. The Host replayed its admitted evidence without another Provider query; stop retrieval and answer from it." : "Related traversal is complete for this turn. The Host replayed the admitted evidence; stop retrieval and answer from it."
 			};
 		}
 		if (retrieval !== void 0 && digest !== void 0) retrieval.relatedDigest = digest;
 		const operation = (async () => {
-			const admitted = boundedModelInsights(await this.serviceFor(parent).related(id, options.depth, options.edge, signal, selected), {
+			const admitted = boundedModelInsights(await service.related(id, options.depth, options.edge, signal, selected), {
 				resultLimit: 4,
 				totalContentLimit: 4e3,
 				mediumLimit: 4,
@@ -7630,45 +7660,38 @@ Completion protocol: call \`${resultToolName}\` exactly once with the final resu
 	}
 	recallAuthority(agent, required) {
 		const authority = this.turnAuthority(agent, required);
-		if (authority === void 0 || !isAgentRuntimeSource$1(this.runtimeMemoryOrSource)) return void 0;
-		const value = optionalObject(this.runtimeMemoryOrSource.forAgent(agent).memoryViews.sourceState(authority.viewId, "memory-spaces"));
-		if (value === void 0 || !Array.isArray(value.memoryBodyIds) || value.memoryBodyIds.some((id) => typeof id !== "string" || id.trim() === "")) throw new Error(`pinned MemorySource has invalid recall authority: ${authority.viewId}`);
+		if (authority === void 0) return void 0;
+		const { context, graph } = authority;
+		const value = optionalObject(graph.memoryViews.sourceState(context.viewId, "memory-spaces"));
+		if (value === void 0 || !Array.isArray(value.memoryBodyIds) || value.memoryBodyIds.some((id) => typeof id !== "string" || id.trim() === "")) throw new Error(`pinned MemorySource has invalid recall authority: ${context.viewId}`);
 		const memoryBodyIds = [...new Set(value.memoryBodyIds.map((id) => String(id).trim()))];
-		if (memoryBodyIds.length === 0) throw new Error(`pinned MemorySource has no recall-authorized Memory Spaces: ${authority.viewId}`);
+		if (memoryBodyIds.length === 0) throw new Error(`pinned MemorySource has no recall-authorized Memory Spaces: ${context.viewId}`);
 		return {
-			...authority,
-			memoryBodyIds
+			context,
+			viewId: context.viewId,
+			memoryBodyIds,
+			service: graph.service
 		};
 	}
 	turnAuthority(agent, required) {
 		if (!isAgentRuntimeSource$1(this.runtimeMemoryOrSource)) return void 0;
-		const views = this.runtimeMemoryOrSource.forAgent(agent).memoryViews;
-		const parentId = isSubagent(agent) ? agent.session.header?.parentSession?.trim() : void 0;
-		const ownerId = parentId === void 0 || parentId === "" ? agent.id : parentId;
-		const pinned = views.activeTurn(ownerId);
-		if (pinned === void 0) {
-			if (required) throw new Error("Recall requires the MemorySource generation pinned to the current turn");
-			return;
-		}
-		return {
-			turnId: pinned.turnId,
-			viewId: pinned.viewId
+		const graph = this.runtimeMemoryOrSource.forAgent(agent);
+		const context = graph.memoryViews.activeTurn(agent.id);
+		if (context !== void 0) return {
+			context,
+			graph
 		};
+		if (required) throw new Error("Recall requires the MemorySource generation pinned to the current turn");
 	}
-	turnRetrievalState(turnId) {
-		const current = this.retrievalTurns.get(turnId);
+	turnRetrievalState(context) {
+		const current = this.retrievalTurns.get(context);
 		if (current !== void 0) return current;
-		while (this.retrievalTurns.size >= 128) {
-			const oldest = this.retrievalTurns.keys().next().value;
-			if (oldest === void 0) break;
-			this.retrievalTurns.delete(oldest);
-		}
 		const created = {
 			recallAttempts: [],
 			evidenceDigests: /* @__PURE__ */ new Set(),
 			evidenceReferences: /* @__PURE__ */ new Set()
 		};
-		this.retrievalTurns.set(turnId, created);
+		this.retrievalTurns.set(context, created);
 		return created;
 	}
 	recordRecall() {
@@ -7829,6 +7852,148 @@ var TurnActivityProjection = class {
 	}
 };
 //#endregion
+//#region src/agent-memory-turn.ts
+function agentMemoryScope(agent, graph) {
+	const cwd = agent.session.header?.cwd?.trim();
+	return {
+		storage: graph.config.storageScope,
+		...cwd === void 0 || cwd === "" ? {} : { workspaceId: resolve(cwd) },
+		sessionId: agent.id,
+		agentId: agent.id
+	};
+}
+/** The durable log, not a parent session id, identifies the executing turn. */
+function openAgentTurn(agent) {
+	let open;
+	for (const event of agent.session.events) {
+		const turn = typeof event.data.turn === "number" ? event.data.turn : void 0;
+		if (event.type === "turn/start" && turn !== void 0) open = turn;
+		else if (event.type === "turn/end" && turn === open) open = void 0;
+	}
+	return open;
+}
+/**
+* One Agent owns each turn pin. A child additionally retains its delegation
+* across parent completion, collection, and runtime swaps until it is disposed.
+*/
+var AgentMemoryTurn = class {
+	agent;
+	runtime;
+	delegation;
+	pinned;
+	pending;
+	generation = 0;
+	closed = false;
+	releaseDelegation;
+	constructor(agent, runtime, delegation) {
+		this.agent = agent;
+		this.runtime = runtime;
+		this.delegation = delegation;
+		if (delegation === void 0) return;
+		const releaseView = delegation.viewId === void 0 ? void 0 : delegation.graph.memoryViews.retainView(delegation.viewId);
+		try {
+			const releaseRuntime = runtime.bindAgentRuntime(agent.id, delegation.graph);
+			this.releaseDelegation = () => {
+				try {
+					releaseView?.();
+				} finally {
+					releaseRuntime();
+				}
+			};
+		} catch (error) {
+			releaseView?.();
+			throw error;
+		}
+	}
+	get current() {
+		return this.pinned;
+	}
+	/** Capture now; descendants must not resolve a later parent turn on demand. */
+	delegate() {
+		if (this.closed) throw new Error("memory Agent lifetime has ended");
+		if (this.pinned !== void 0) return {
+			graph: this.pinned.graph,
+			scope: this.pinned.context.scope,
+			viewId: this.pinned.context.viewId
+		};
+		if (this.delegation !== void 0) return this.delegation;
+		const graph = this.runtime.forAgent(this.agent);
+		return {
+			graph,
+			scope: agentMemoryScope(this.agent, graph)
+		};
+	}
+	async begin(turn, signal) {
+		if (this.closed) throw new Error("memory Agent lifetime has ended");
+		signal?.throwIfAborted();
+		if (this.pinned?.turn === turn) return;
+		if (this.pending?.turn === turn) return this.pending.result;
+		this.end();
+		const generation = this.generation;
+		const result = this.pin(turn, generation, signal);
+		this.pending = {
+			turn,
+			generation,
+			result
+		};
+		try {
+			await result;
+		} finally {
+			if (this.pending?.generation === generation) this.pending = void 0;
+		}
+	}
+	end(turn) {
+		if (turn !== void 0 && this.pinned?.turn !== turn && this.pending?.turn !== turn) return;
+		this.generation += 1;
+		this.pending = void 0;
+		const pinned = this.pinned;
+		this.pinned = void 0;
+		if (pinned === void 0) return;
+		try {
+			if (pinned.manager.turn(pinned.context.turnId) === pinned.context) pinned.manager.endTurn(pinned.context.turnId);
+		} finally {
+			pinned.releaseRuntime?.();
+		}
+	}
+	dispose() {
+		if (this.closed) return;
+		this.closed = true;
+		try {
+			this.end();
+		} finally {
+			this.releaseDelegation?.();
+		}
+	}
+	async pin(turn, generation, signal) {
+		const graph = this.delegation?.graph ?? this.runtime.forAgent(this.agent);
+		const manager = graph.memoryViews;
+		const scope = this.delegation === void 0 ? agentMemoryScope(this.agent, graph) : {
+			...this.delegation.scope,
+			sessionId: this.agent.id,
+			agentId: this.agent.id
+		};
+		const turnId = `${this.agent.id}:${turn}`;
+		const context = this.delegation?.viewId === void 0 ? await manager.beginTurn(turnId, scope) : manager.pinTurn(turnId, scope, this.delegation.viewId);
+		let releaseRuntime;
+		try {
+			if (this.closed || this.generation !== generation) throw new Error("memory turn ended during View preparation");
+			signal?.throwIfAborted();
+			if (this.delegation === void 0) releaseRuntime = this.runtime.bindAgentRuntime(this.agent.id, graph);
+			this.pinned = {
+				turn,
+				graph,
+				manager,
+				context,
+				...releaseRuntime === void 0 ? {} : { releaseRuntime }
+			};
+		} catch (error) {
+			if (manager.turn(context.turnId) === context) manager.endTurn(context.turnId);
+			releaseRuntime?.();
+			throw error;
+		}
+	}
+};
+//#endregion
 //#region src/lifecycle.ts
 function modelService(value) {
 	if (typeof value !== "object" || value === null || !("currentSelection" in value) || typeof value.currentSelection !== "function") return void 0;
@@ -7935,7 +8100,7 @@ var MnemonAgentLifecycle = class {
 	coordinator;
 	config;
 	counters;
-	runtimeSource;
+	memoryTurn;
 	primePending = true;
 	startSource;
 	guidedTurns = /* @__PURE__ */ new Set();
@@ -7947,6 +8112,14 @@ var MnemonAgentLifecycle = class {
 	* actually see, which is what makes a rewind self-correcting.
 	*/
 	cueInjected = false;
+	/**
+	* Text of the runtime memory snapshot most recently injected as this
+	* plugin's own message. `.context()` used to get supersede-on-change for free
+	* from the host's runtime-context projection; carrying the snapshot as an own
+	* message means re-emitting on change is this plugin's responsibility, and
+	* the rendered text (which carries the revision digest) is the key.
+	*/
+	injectedMemoryText;
 	idleReviewTimer;
 	reviewController;
 	reviewRunning = false;
@@ -7957,13 +8130,12 @@ var MnemonAgentLifecycle = class {
 	lastPhase = "idle";
 	lastAt;
 	lastError;
-	pinnedView;
-	constructor(agent, coordinator, config, counters, source, runtimeSource) {
+	constructor(agent, coordinator, config, counters, source, memoryTurn) {
 		this.agent = agent;
 		this.coordinator = coordinator;
 		this.config = config;
 		this.counters = counters;
-		this.runtimeSource = runtimeSource;
+		this.memoryTurn = memoryTurn;
 		this.startSource = source;
 	}
 	start() {
@@ -7981,7 +8153,7 @@ var MnemonAgentLifecycle = class {
 			})),
 			this.agent.ctx.on("session/event", ((session, event) => this.sessionEvent(session, event))),
 			this.agent.ctx.on("system-prompt/assemble", ((assembly, context, next) => this.assemblePrompt(assembly, context, next))),
-			this.agent.ctx.on("agent/pre-step", ((payload, next) => this.preStep(payload, next))),
+			this.agent.ctx.on("agent/pre-step", ((payload, next) => this.preStep(payload, next)), { prepend: true }),
 			this.agent.ctx.on("agent/turn-stopping", ((payload) => this.finishTurn(payload)))
 		];
 		return () => {
@@ -8023,7 +8195,7 @@ var MnemonAgentLifecycle = class {
 		return assistantMessageText(this.agent.session.events, messageId);
 	}
 	memoryWake() {
-		const pinned = this.pinnedView;
+		const pinned = this.memoryTurn?.current;
 		return pinned === void 0 ? void 0 : pinned.manager.wake(pinned.context.viewId);
 	}
 	/**
@@ -8044,6 +8216,23 @@ var MnemonAgentLifecycle = class {
 		for (const seq of nodes) if (isOwnUserMessageEvent(this.agent.session.events[seq])) return true;
 		return false;
 	}
+	/**
+	* The runtime memory snapshot, as this plugin's own message, when it changed.
+	*
+	* `.context()` used to carry this inside the host's shared runtime-context
+	* projection. Carrying it here instead attributes it to dsh-mnemon and keeps
+	* a memory write from re-emitting other contributors' sections; supersede
+	* stays intact because the block is still a complete state replacing its
+	* predecessor, keyed on the rendered text's revision digest.
+	*/
+	memorySnapshotMessage() {
+		const wake = this.memoryWake();
+		if (wake === void 0) return void 0;
+		const text = memoryPromptText(wake.text);
+		if (text.trim() === "" || text === this.injectedMemoryText) return void 0;
+		this.injectedMemoryText = text;
+		return createPluginMessage(text, "recall", "Runtime memory snapshot");
+	}
 	async preStep(payload, next) {
 		if (payload.step === 1) this.cancelIdleReview(true);
 		const decision = await next();
@@ -8059,14 +8248,22 @@ var MnemonAgentLifecycle = class {
 			return source.kind === "plugin" && source.plugin === "dsh-mnemon";
 		})) return decision;
 		if (decision.messages.length === 0) return decision;
+		const snapshot = this.memorySnapshotMessage();
+		const withSnapshot = (messages) => snapshot === void 0 ? messages : [...messages, snapshot];
 		if (this.primePending) {
 			this.primePending = false;
 			this.counters.primes += 1;
 			this.mark("prime");
 		}
-		if (this.cueAlreadyVisible()) return decision;
+		if (this.cueAlreadyVisible()) return {
+			kind: "enter",
+			messages: withSnapshot(decision.messages)
+		};
 		const reminder = guidedReminder(this.config);
-		if (reminder === void 0) return decision;
+		if (reminder === void 0) return {
+			kind: "enter",
+			messages: withSnapshot(decision.messages)
+		};
 		this.cueInjected = true;
 		this.guidedTurns.add(payload.turn);
 		if (this.config.recallMode === "guided") this.counters.recallCues += 1;
@@ -8074,63 +8271,21 @@ var MnemonAgentLifecycle = class {
 		this.mark(this.config.recallMode === "guided" ? "recall" : "writeback");
 		return {
 			kind: "enter",
-			messages: [...decision.messages, createPluginMessage(reminder, "instructions", "Optional memory recall and remember reminder")]
+			messages: withSnapshot([...decision.messages, createPluginMessage(reminder, "instructions", "Optional memory recall and remember reminder")])
 		};
 	}
 	async assemblePrompt(assembly, context, next) {
 		if (context.agent !== void 0 && context.agent.id !== this.agent.id) return next();
 		const turn = this.openTurn();
 		if (turn === void 0 || context.signal?.aborted === true) return next();
-		await this.pinView(turn);
+		await this.memoryTurn?.begin(turn, context.signal);
 		return applyAgentMemoryViewWake(await next(), this.memoryWake());
 	}
 	openTurn() {
-		let open;
-		for (const event of this.agent.session.events) {
-			const turn = eventTurn(event);
-			if (event.type === "turn/start" && turn !== void 0) open = turn;
-			else if (event.type === "turn/end" && turn === open) open = void 0;
-		}
-		return open;
-	}
-	async pinView(turn) {
-		if (this.pinnedView?.turn === turn) return;
-		this.releaseView();
-		const graph = this.runtimeSource?.forAgent(this.agent);
-		const manager = graph?.memoryViews;
-		if (manager === void 0 || graph === void 0 || this.runtimeSource === void 0) return;
-		const cwd = this.agent.session.header?.cwd?.trim();
-		const scope = {
-			storage: this.config.storageScope,
-			...cwd === void 0 || cwd === "" ? {} : { workspaceId: resolve(cwd) },
-			sessionId: this.agent.id,
-			agentId: this.agent.id
-		};
-		const context = await manager.beginTurn(`${this.agent.id}:${turn}`, scope);
-		let releaseRuntime;
-		try {
-			releaseRuntime = this.runtimeSource.bindAgentRuntime(this.agent.id, graph);
-			this.pinnedView = {
-				turn,
-				manager,
-				context,
-				releaseRuntime
-			};
-		} catch (error) {
-			manager.endTurn(context.turnId);
-			releaseRuntime?.();
-			throw error;
-		}
+		return openAgentTurn(this.agent);
 	}
 	releaseView(turn) {
-		const pinned = this.pinnedView;
-		if (pinned === void 0 || turn !== void 0 && pinned.turn !== turn) return;
-		this.pinnedView = void 0;
-		try {
-			pinned.manager.endTurn(pinned.context.turnId);
-		} finally {
-			pinned.releaseRuntime();
-		}
+		this.memoryTurn?.end(turn);
 	}
 	async finishTurn(payload) {
 		this.scheduleIdleReview(payload.turn);
@@ -8138,7 +8293,8 @@ var MnemonAgentLifecycle = class {
 	sessionEvent(session, event) {
 		if (session !== this.agent.session || event.type !== "turn/end") return;
 		const turn = eventTurn(event);
-		const pinned = turn === void 0 || this.pinnedView?.turn !== turn ? void 0 : this.pinnedView;
+		const current = this.memoryTurn?.current;
+		const pinned = turn === void 0 || current?.turn !== turn ? void 0 : current;
 		if (pinned === void 0) return;
 		this.releaseView(turn);
 		pinned.manager.reconcile(pinned.context.scope).catch((error) => this.fail(error));
@@ -8267,6 +8423,8 @@ var MnemonLifecycle = class {
 	config;
 	runtimeSource;
 	owners = /* @__PURE__ */ new Map();
+	children = /* @__PURE__ */ new Map();
+	memoryTurns = /* @__PURE__ */ new Map();
 	counters = {
 		primes: 0,
 		recallCues: 0,
@@ -8291,8 +8449,11 @@ var MnemonLifecycle = class {
 		for (const agent of this.ctx.agents.roots()) this.install(agent, "adopted");
 		return () => {
 			stopCreated();
+			for (const dispose of [...this.children.values()].reverse()) dispose();
 			for (const owner of [...this.owners.values()].reverse()) owner.dispose();
+			this.children.clear();
 			this.owners.clear();
+			this.memoryTurns.clear();
 		};
 	}
 	snapshot(sessionId, workspaceRoot) {
@@ -8634,22 +8795,93 @@ var MnemonLifecycle = class {
 		return this.taskAgentModelRoute(fallbackSessionId, workspaceRoot)?.options;
 	}
 	install(agent, source) {
-		if (this.taskAgentIds.has(agent.id) || this.owners.has(agent) || !this.ctx.agents.roots().includes(agent)) return;
-		const lifecycle = new MnemonAgentLifecycle(agent, this.coordinator, this.config, this.counters, source, this.runtimeSource);
+		if (this.taskAgentIds.has(agent.id) || this.owners.has(agent) || this.children.has(agent)) return;
+		if (agent.session.header?.origin === "subagent") {
+			this.installChild(agent);
+			return;
+		}
+		if (!this.ctx.agents.roots().includes(agent)) return;
+		const memoryTurn = this.runtimeSource === void 0 ? void 0 : new AgentMemoryTurn(agent, this.runtimeSource);
+		const lifecycle = new MnemonAgentLifecycle(agent, this.coordinator, this.config, this.counters, source, memoryTurn);
 		let dispose;
 		dispose = agent.ctx.effect(() => {
 			const stop = lifecycle.start();
 			const stopRuntimeContext = this.runtimeSource === void 0 ? () => {} : registerAgentMemoryViewContext(agent, () => lifecycle.memoryWake());
 			return () => {
-				stopRuntimeContext();
-				stop();
-				if (this.owners.get(agent)?.dispose === dispose) this.owners.delete(agent);
+				try {
+					stopRuntimeContext();
+					stop();
+				} finally {
+					memoryTurn?.dispose();
+					if (this.owners.get(agent)?.dispose === dispose) this.owners.delete(agent);
+					if (this.memoryTurns.get(agent) === memoryTurn) this.memoryTurns.delete(agent);
+				}
 			};
 		}, "dsh-mnemon.lifecycle()");
 		this.owners.set(agent, {
 			lifecycle,
 			dispose
 		});
+		if (memoryTurn !== void 0) this.memoryTurns.set(agent, memoryTurn);
+	}
+	/** Child memory ownership is independent of root-only reminders and idle review. */
+	installChild(agent) {
+		const runtime = this.runtimeSource;
+		const parentId = agent.session.header?.parentSession?.trim();
+		const parent = parentId === void 0 || parentId === "" ? void 0 : this.ctx.agents.get(parentId);
+		if (runtime === void 0 || parent === void 0 || parent === agent) return;
+		const parentMemory = this.memoryTurns.get(parent);
+		let delegation;
+		if (parentMemory !== void 0) delegation = parentMemory.delegate();
+		else {
+			const graph = runtime.forAgent(parent);
+			const parentPin = graph.memoryViews.activeTurn(parent.id);
+			delegation = {
+				graph,
+				scope: parentPin?.scope ?? agentMemoryScope(parent, graph),
+				...parentPin === void 0 ? {} : { viewId: parentPin.viewId }
+			};
+		}
+		let dispose;
+		dispose = agent.ctx.effect(() => {
+			const memory = new AgentMemoryTurn(agent, runtime, delegation);
+			this.memoryTurns.set(agent, memory);
+			const stops = [];
+			const cleanup = () => {
+				try {
+					for (const stop of stops.reverse()) stop();
+				} finally {
+					try {
+						memory.dispose();
+					} finally {
+						if (this.memoryTurns.get(agent) === memory) this.memoryTurns.delete(agent);
+						if (this.children.get(agent) === dispose) this.children.delete(agent);
+					}
+				}
+			};
+			try {
+				stops.push(agent.ctx.on("agent/session-start", (() => memory.end())));
+				stops.push(agent.ctx.on("system-prompt/assemble", (async (_assembly, context, next) => {
+					if (context.agent !== void 0 && context.agent !== agent) return next();
+					const turn = openAgentTurn(agent);
+					if (turn !== void 0) await memory.begin(turn, context.signal);
+					return next();
+				})));
+				stops.push(agent.ctx.on("agent/pre-step", (async (payload, next) => {
+					const decision = await next();
+					if (decision.kind === "reject" || payload.signal.aborted) memory.end(payload.turn);
+					return decision;
+				})));
+				stops.push(agent.ctx.on("session/event", ((session, event) => {
+					if (session === agent.session && event.type === "turn/end") memory.end(eventTurn(event));
+				})));
+			} catch (error) {
+				cleanup();
+				throw error;
+			}
+			return cleanup;
+		}, "dsh-mnemon.child-memory()");
+		this.children.set(agent, dispose);
 	}
 };
 //#endregion
@@ -9324,11 +9556,7 @@ const ACTIVATION_PAYLOAD_FIELDS = /* @__PURE__ */ new Set([
 	"sessionId",
 	"workspaceId"
 ]);
-/**
-* Expose only DSH read-routing activation to trusted Web hosts. Metadata,
-* provider connections, credentials, and durable memory writes stay on the
-* loopback-only write channel.
-*/
+/** Keep activation on a narrow, independently validated control endpoint. */
 function createActivationHandler(input) {
 	return async (endpoint, rawPayload) => {
 		try {
@@ -9566,7 +9794,7 @@ function createWriteHandler(input, lifecycle, runtimeMemory, versions) {
 		}
 	};
 }
-/** Backup payloads contain private memory and use the deployment's management authority. */
+/** Backup payloads contain private memory and stay behind DSH browser authentication. */
 function createPackHandler(input, writeEnabled = true) {
 	return async (endpoint, rawPayload) => {
 		try {
@@ -9585,7 +9813,11 @@ function createPackHandler(input, writeEnabled = true) {
 		}
 	};
 }
-/** Reads and activation use trusted hosts; other privileged channels require explicit promotion. */
+/**
+* Register one call shape across DSH rc.2 and 0.1.2-alpha.1. The former
+* enforces channel authority; the latter ignores the trailing options object
+* after applying its uniform browser-session authentication boundary.
+*/
 function registerRpc(connection, input, lifecycle, runtimeMemory, storage, packs, versions, managementAuthority = "loopback") {
 	const versionManager = versions ?? new VersionUpdateManager({ mnemonCliPath: () => findVersionCli(input) });
 	connection.rpc.handle(MNEMON_READ_CHANNEL, createReadHandler(input, lifecycle, runtimeMemory, storage, versionManager), { authority: "trusted-host" });
@@ -9850,7 +10082,7 @@ function requireAgent(exec) {
 function isAgentRuntimeSource(value) {
 	return "forAgent" in value && typeof value.forAgent === "function";
 }
-/** Root calls delegate to a bounded child; memory-worker calls reach the deterministic service. */
+/** Model tools use the executing Agent's pinned runtime and deterministic service. */
 function registerTools(ctx, serviceOrSource, coordinator, runtimeMemory, documents) {
 	const runtimeFor = (exec) => {
 		if (isAgentRuntimeSource(serviceOrSource)) return serviceOrSource.forAgent(requireAgent(exec));
@@ -10029,7 +10261,7 @@ function registerTools(ctx, serviceOrSource, coordinator, runtimeMemory, documen
 	}));
 	ctx.tools.register(definition({
 		name: "mnemon_document_search",
-		description: "Run one focused search over project-scoped managed Documents before durable Recall. The Host admits only one Documents query for the root turn, shared with child and parallel calls. Results contain bounded query-local evidence, not complete records. Cold archives are excluded unless a known archive reference requires them.",
+		description: "Run one focused search over project-scoped managed Documents before durable Recall. The Host admits only one Documents query per executing Agent turn; parallel calls share that slot, while child turns have independent budgets. Results contain bounded query-local evidence, not complete records. Cold archives are excluded unless a known archive reference requires them.",
 		parameters: {
 			type: "object",
 			properties: {
@@ -10060,7 +10292,7 @@ function registerTools(ctx, serviceOrSource, coordinator, runtimeMemory, documen
 				includeArchived: args.includeArchived === true,
 				notRun: true,
 				results: [],
-				hint: "The root turn already used its Documents search slot, so no second disk query ran. Use the admitted evidence, make one focused mnemon_recall only if exact durable history is still missing, or answer with appropriate uncertainty."
+				hint: "This Agent turn already used its Documents search slot, so no second disk query ran. Use the admitted evidence, make one focused mnemon_recall only if exact durable history is still missing, or answer with appropriate uncertainty."
 			};
 			const result = await controller.search(args.query, {
 				...args.includeArchived === void 0 ? {} : { includeArchived: args.includeArchived },