dsh-mnemon 0.3.2 → 0.3.4

package/lib/index.js

@@ -11,7 +11,9 @@ import { createHash, randomUUID } from "node:crypto";
 import { accessSync, closeSync, constants, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { strToU8, unzipSync, zipSync } from "fflate";
+import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { z as z$1 } from "zod";
 //#region src/shared/contracts.ts
 const MNEMON_READ_CHANNEL = "/dsh-mnemon-read";
 const MNEMON_ACTIVATION_CHANNEL = "/dsh-mnemon-activation";
@@ -53,6 +55,11 @@ const DEFAULT_IDLE_REVIEW_MS = 3e4;
 const DEFAULT_RECALL_QUALITY_POLICY = "strict-v1";
 const DEFAULT_RECALL_LOW_SCORE_THRESHOLD = .25;
 const DEFAULT_RECALL_HIGH_SCORE_THRESHOLD = .6;
+const DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES = 10240;
+const DEFAULT_RUNTIME_USER_LIMIT_BYTES = 4096;
+const DEFAULT_RUNTIME_MAINTENANCE_MAX_TOKENS = 8192;
+const MAX_RUNTIME_MEMORY_LIMIT_BYTES = 1048576;
+const MAX_RUNTIME_MAINTENANCE_MAX_TOKENS = 1e6;
 //#endregion
 //#region src/config.ts
 const InteractionConfig = z.object({
@@ -117,6 +124,11 @@ const RecallQualitySchema = z.object({
 	maxMediumResults: z.number().step(1).min(0).max(50).default(4),
 	maxUnknownResults: z.number().step(1).min(0).max(50).default(2)
 });
+const RuntimeMemorySchema = z.object({
+	memoryLimitBytes: z.number().step(1).min(1).max(MAX_RUNTIME_MEMORY_LIMIT_BYTES).default(DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES),
+	userLimitBytes: z.number().step(1).min(1).max(MAX_RUNTIME_MEMORY_LIMIT_BYTES).default(DEFAULT_RUNTIME_USER_LIMIT_BYTES),
+	maintenanceMaxTokens: z.number().step(1).min(1).max(MAX_RUNTIME_MAINTENANCE_MAX_TOKENS).default(DEFAULT_RUNTIME_MAINTENANCE_MAX_TOKENS)
+});
 const MemoryParticipationModeSchema = z.union([
 	"off",
 	"manual",
@@ -143,6 +155,7 @@ const Config = z.object({
 		"workspace",
 		"custom"
 	]),
+	runtimeUserScope: z.union(["storage", "global"]).default("storage"),
 	cliPath: z.string(),
 	dataDir: z.string(),
 	customPackId: z.string(),
@@ -154,6 +167,11 @@ const Config = z.object({
 	store: z.string(),
 	timeoutMs: z.number().step(1).min(100).max(12e4).default(DEFAULT_TIMEOUT_MS),
 	defaultRecallLimit: z.number().step(1).min(1).max(50).default(10),
+	runtimeMemory: RuntimeMemorySchema.default({
+		memoryLimitBytes: DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES,
+		userLimitBytes: DEFAULT_RUNTIME_USER_LIMIT_BYTES,
+		maintenanceMaxTokens: DEFAULT_RUNTIME_MAINTENANCE_MAX_TOKENS
+	}),
 	embedding: MnemonEmbeddingSchema.default({
 		enabled: false,
 		endpoint: DEFAULT_EMBEDDING_ENDPOINT,
@@ -336,6 +354,19 @@ function resolveRecallQuality(value) {
 		maxUnknownResults
 	};
 }
+function resolveRuntimeMemory(value) {
+	const memoryLimitBytes = value?.memoryLimitBytes ?? 10240;
+	const userLimitBytes = value?.userLimitBytes ?? 4096;
+	const maintenanceMaxTokens = value?.maintenanceMaxTokens ?? 8192;
+	if (!Number.isInteger(memoryLimitBytes) || memoryLimitBytes < 1 || memoryLimitBytes > 1048576) throw new Error(`dsh-mnemon: Runtime MEMORY.md limit must be an integer within 1..${MAX_RUNTIME_MEMORY_LIMIT_BYTES} bytes`);
+	if (!Number.isInteger(userLimitBytes) || userLimitBytes < 1 || userLimitBytes > 1048576) throw new Error(`dsh-mnemon: Runtime USER.md limit must be an integer within 1..${MAX_RUNTIME_MEMORY_LIMIT_BYTES} bytes`);
+	if (!Number.isInteger(maintenanceMaxTokens) || maintenanceMaxTokens < 1 || maintenanceMaxTokens > 1e6) throw new Error(`dsh-mnemon: Runtime maintenance maxTokens must be an integer within 1..${MAX_RUNTIME_MAINTENANCE_MAX_TOKENS}`);
+	return {
+		memoryLimitBytes,
+		userLimitBytes,
+		maintenanceMaxTokens
+	};
+}
 const MEMORY_COMPONENT_ID = /^[a-z][a-z0-9-]{0,127}$/u;
 const MEMORY_PARTICIPATION_MODES = /* @__PURE__ */ new Set([
 	"off",
@@ -386,6 +417,8 @@ function resolveConfig(config = {}) {
 	if (requestedPackId !== void 0 && !CUSTOM_PACK_ID.test(requestedPackId)) throw new Error("dsh-mnemon: customPackId is invalid");
 	const store = optionalText$1(config.store);
 	const storageScope = config.storageScope ?? (legacyDataDir === void 0 && legacyPacks.length === 0 ? "global" : "custom");
+	const runtimeUserScope = config.runtimeUserScope ?? "storage";
+	if (runtimeUserScope !== "storage" && runtimeUserScope !== "global") throw new Error(`dsh-mnemon: unsupported Runtime USER.md scope: ${String(runtimeUserScope)}`);
 	const selectedPack = requestedPackId === void 0 ? legacyPacks.find((pack) => pack.dataDir === legacyDataDir) ?? (legacyPacks.length === 1 ? legacyPacks[0] : void 0) : legacyPacks.find((pack) => pack.id === requestedPackId);
 	if (requestedPackId !== void 0 && selectedPack === void 0) throw new Error(`dsh-mnemon: unknown custom Pack: ${requestedPackId}`);
 	const dataDir = selectedPack?.dataDir ?? legacyDataDir;
@@ -393,11 +426,13 @@ function resolveConfig(config = {}) {
 	if (store !== void 0 && !/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(store)) throw new Error("dsh-mnemon: store must match [a-zA-Z0-9][a-zA-Z0-9_-]*");
 	return {
 		storageScope,
+		runtimeUserScope,
 		...cliPath === void 0 ? {} : { cliPath },
 		...dataDir === void 0 ? {} : { dataDir },
 		...store === void 0 ? {} : { store },
 		timeoutMs: config.timeoutMs ?? 1e4,
 		defaultRecallLimit: config.defaultRecallLimit ?? 10,
+		runtimeMemory: resolveRuntimeMemory(config.runtimeMemory),
 		embedding: resolveEmbedding(config.embedding),
 		memoryTopology: resolveMemoryTopology(config.memoryTopology),
 		recallQuality: resolveRecallQuality(config.recallQuality),
@@ -1162,8 +1197,8 @@ var DocumentManager = class {
 };
 const RUNTIME_ENTRY_DELIMITER = "\n§\n";
 const RUNTIME_MEMORY_LIMITS = {
-	memory: 10240,
-	user: 4096
+	memory: DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES,
+	user: DEFAULT_RUNTIME_USER_LIMIT_BYTES
 };
 const RUNTIME_MEMORY_PROTOCOL = `MNEMON RUNTIME MEMORY PROTOCOL
 Runtime Memory keeps compact hot memory available for every turn. The latest MNEMON RUNTIME MEMORY SNAPSHOT in runtime context is a complete projection of USER.md and MEMORY.md and supersedes earlier Runtime Memory snapshots. Apply applicable entries silently and never recite them merely to prove they were read.
@@ -1183,6 +1218,7 @@ WRITE PROTOCOL
 - Choose target="user" only for the user profile and target="memory" only for project/environment knowledge. Use importance="critical" for explicit must/always/never rules or strong preferences, "low" for transient or one-time facts that are still worth keeping, and "normal" otherwise.
 - Entries are separated by a standalone §. old_text must uniquely identify one entry. Tool receipts are sufficient; do not echo either complete file after a successful mutation.
 - If USER.md reaches capacity, the tool conservatively consolidates the local profile without sending preferences to Mnemon Memory Spaces. If MEMORY.md reaches capacity, the tool archives committed working memories into one or more semantically appropriate Memory Spaces, then atomically applies compaction and the pending mutation only when the reviewed revision is still current. Never evade either limit with direct file edits.
+- Branch scoping (target=memory only): pass the optional branches parameter (a list of git branch names) to project an entry only in sessions on those branches; omit it for cross-branch facts. Use it for branch-specific architecture decisions and experiments, and tag new branch-scoped entries with the git branch reported in the snapshot header. On replace, provide branches to change the scope, an empty list to clear it, or omit it to keep the current scope. Non-git workspaces and detached HEAD project every entry regardless of scope.
 
 IMPORTANT: Runtime Memory is always relevant when applicable, after the current request. Use mnemon_runtime_memory only when the criteria above are met; otherwise do not mutate memory.`;
 const LOCK_TIMEOUT_MS$1 = 5e3;
@@ -1218,6 +1254,41 @@ function isTarget(value) {
 function isImportance(value) {
 	return value === "critical" || value === "normal" || value === "low";
 }
+const RUNTIME_BRANCH_NAME_RE = /^[A-Za-z0-9._/-]+$/u;
+/** Validate a model-supplied branch scope. Returns the normalized list; an empty list means "no scope". */
+function normalizeRuntimeBranches(value, field = "branches") {
+	if (!Array.isArray(value)) throw new Error(`${field} must be an array of git branch names`);
+	const branches = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const item of value) {
+		if (typeof item !== "string") throw new Error(`${field} must contain only git branch names`);
+		const branch = item.trim();
+		if (branch === "" || branch.length > 128 || !RUNTIME_BRANCH_NAME_RE.test(branch) || branch === "-" || branch.startsWith("/") || branch.startsWith("-") || branch.endsWith("/") || branch.endsWith(".") || branch.includes("..") || branch.includes("//") || branch.includes("@{")) throw new Error(`${field} must contain git branch names (letters, numbers, dot, underscore, slash, dash)`);
+		if (seen.has(branch)) throw new Error(`${field} must not repeat a branch name`);
+		seen.add(branch);
+		branches.push(branch);
+	}
+	if (branches.length > 16) throw new Error(`${field} supports at most 16 branch names`);
+	return branches;
+}
+/** Parse a stored branch scope. Returns undefined for absent or invalid data. */
+function parseRuntimeBranches(value) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value)) return void 0;
+	const branches = [];
+	for (const item of value) {
+		if (typeof item !== "string" || item === "" || item.length > 128 || !RUNTIME_BRANCH_NAME_RE.test(item)) return void 0;
+		branches.push(item);
+	}
+	return branches;
+}
+function entryMatchesBranch(entry, branch) {
+	return entry.branches === void 0 || entry.branches.length === 0 || entry.branches.includes(branch);
+}
+function scopeBranch(branch) {
+	const value = branch?.trim();
+	return value === void 0 || value === "" ? void 0 : value;
+}
 function normalizeContent(value, field) {
 	const content = value?.trim().replace(/\s+/gu, " ") ?? "";
 	if (content === "") throw new Error(`${field} is required`);
@@ -1231,12 +1302,15 @@ function parseEntry(value) {
 	if (typeof value.created_at !== "string" || typeof value.updated_at !== "string") return void 0;
 	const content = value.content.trim().replace(/\s+/gu, " ");
 	if (content === "" || content.includes("§")) return void 0;
+	if (value.target === "user" && value.branches !== void 0) return void 0;
+	const branches = parseRuntimeBranches(value.branches);
 	return {
 		content,
 		created_at: value.created_at,
 		updated_at: value.updated_at,
 		target: value.target,
-		importance: value.importance
+		importance: value.importance,
+		...branches === void 0 ? {} : { branches }
 	};
 }
 function byteCount(entries, target) {
@@ -1258,6 +1332,8 @@ function prepareMutation(before, request, now) {
 		"remove"
 	].includes(request.action)) throw new Error("action must be add, replace, or remove");
 	if (request.importance !== void 0 && !isImportance(request.importance)) throw new Error("importance must be critical, normal, or low");
+	if (request.target === "user" && request.branches !== void 0) throw new Error("branches applies to target=memory only");
+	const branchScope = request.branches === void 0 ? void 0 : normalizeRuntimeBranches(request.branches);
 	const entries = before.map((entry) => ({ ...entry }));
 	if (request.action === "add") {
 		const content = normalizeContent(request.content, "content");
@@ -1276,7 +1352,8 @@ function prepareMutation(before, request, now) {
 			created_at: now,
 			updated_at: now,
 			target: request.target,
-			importance: request.importance ?? "normal"
+			importance: request.importance ?? "normal",
+			...branchScope !== void 0 && branchScope.length > 0 ? { branches: branchScope } : {}
 		};
 		return {
 			changed: true,
@@ -1304,6 +1381,10 @@ function prepareMutation(before, request, now) {
 			updated_at: now,
 			importance: request.importance ?? previous.importance
 		};
+		if (branchScope !== void 0) {
+			if (branchScope.length === 0) delete pendingEntry.branches;
+			else pendingEntry.branches = branchScope;
+		}
 		entries[index] = pendingEntry;
 		return {
 			changed: true,
@@ -1339,12 +1420,14 @@ function compactionCandidates(compacted, existing, target, now) {
 		if (seen.has(content)) throw new Error("compacted runtime memory contains duplicate entries");
 		seen.add(content);
 		const unchanged = existing.find((current) => current.content === content);
+		const inheritedBranches = entry.branches ?? unchanged?.branches;
 		return {
 			content,
 			created_at: unchanged?.created_at ?? now,
 			updated_at: unchanged?.updated_at ?? now,
 			target,
-			importance: entry.importance
+			importance: entry.importance,
+			...inheritedBranches === void 0 ? {} : { branches: inheritedBranches }
 		};
 	});
 }
@@ -1375,49 +1458,112 @@ function sleepSync$1(milliseconds) {
 * Single authority for hot memory. JSON is the durable source of truth;
 * Markdown files are deterministic projections consumed by prompt assembly.
 */
-var RuntimeMemoryController = class {
+var RuntimeMemoryController = class RuntimeMemoryController {
 	now;
 	recordCommit;
 	directory;
 	sourcePath;
+	userSourcePath;
 	memoryPath;
 	userPath;
 	lockPath;
+	limits;
 	queue = Promise.resolve();
-	constructor(runner, now = () => /* @__PURE__ */ new Date(), recordCommit) {
+	localUserPath;
+	userController;
+	constructor(runner, now = () => /* @__PURE__ */ new Date(), recordCommit, limits = RUNTIME_MEMORY_LIMITS, userRunner) {
 		this.now = now;
 		this.recordCommit = recordCommit;
+		for (const [target, limit] of Object.entries(limits)) if (!Number.isInteger(limit) || limit < 1 || limit > 1048576) throw new Error(`runtime ${target} memory limit must be an integer within 1..${MAX_RUNTIME_MEMORY_LIMIT_BYTES} bytes`);
+		this.limits = {
+			memory: limits.memory,
+			user: limits.user
+		};
 		this.directory = join(runner.effectiveDataDir(), "runtime");
 		this.sourcePath = join(this.directory, "memories.json");
 		this.memoryPath = join(this.directory, "MEMORY.md");
-		this.userPath = join(this.directory, "USER.md");
+		this.localUserPath = join(this.directory, "USER.md");
 		this.lockPath = join(this.directory, ".memories.lock");
+		const userDirectory = userRunner === void 0 ? this.directory : join(userRunner.effectiveDataDir(), "runtime");
+		this.userController = userDirectory === this.directory || userRunner === void 0 ? void 0 : new RuntimeMemoryController(userRunner, now, recordCommit, this.limits);
+		this.userPath = this.userController?.userPath ?? this.localUserPath;
+		this.userSourcePath = this.userController?.sourcePath ?? this.sourcePath;
 		this.initialize();
 	}
 	snapshot() {
-		const file = this.readSource();
-		const entries = file.entries.map((entry) => ({ ...entry }));
-		return {
+		const local = this.readSource();
+		if (this.userController === void 0) return this.snapshotUnlocked(local);
+		const global = this.userController.readSource();
+		return this.snapshotUnlocked({
+			version: 1,
+			entries: [...global.entries.filter((entry) => entry.target === "user"), ...local.entries.filter((entry) => entry.target === "memory")]
+		});
+	}
+	contextText(branch) {
+		return this.contextProjection(branch).text;
+	}
+	/**
+	* Read the exact Runtime revision and its prompt projection from each
+	* configured authority root.
+	* When a git branch is supplied, target=memory entries scoped to other
+	* branches are hidden from the projection; the on-disk Markdown files and
+	* the source JSON always remain complete.
+	*/
+	contextProjection(branch) {
+		const branchScope = scopeBranch(branch);
+		const local = this.localContextProjection(branchScope);
+		const global = this.userController?.localContextProjection();
+		const user = global?.user ?? local.user;
+		const memory = local.memory;
+		const entries = global === void 0 ? local.snapshot.entries : [...global.snapshot.entries.filter((entry) => entry.target === "user"), ...local.snapshot.entries.filter((entry) => entry.target === "memory")];
+		const visibleMemory = local.snapshot.targets.memory;
+		const visibleUser = global?.snapshot.targets.user ?? local.snapshot.targets.user;
+		const snapshot = global === void 0 ? local.snapshot : {
 			directory: this.directory,
 			sourcePath: this.sourcePath,
-			revision: revision(file),
+			revision: revision({
+				version: 1,
+				entries
+			}),
 			generatedAt: this.now().toISOString(),
 			entries,
 			targets: {
-				memory: this.targetView(entries, "memory"),
-				user: this.targetView(entries, "user")
+				memory: {
+					...visibleMemory,
+					markdownPath: this.memoryPath
+				},
+				user: {
+					...visibleUser,
+					markdownPath: this.userPath
+				}
 			}
 		};
+		const storeMemory = this.targetView(entries, "memory");
+		const storeUser = this.targetView(entries, "user");
+		const branchLine = branchScope === void 0 ? "" : `\nGit branch: ${branchScope}${local.hidden > 0 ? ` (${local.hidden} branch-scoped entr${local.hidden === 1 ? "y" : "ies"} hidden)` : ""}`;
+		return {
+			revision: snapshot.revision,
+			text: `MNEMON RUNTIME MEMORY SNAPSHOT
+Revision: ${snapshot.revision}${branchLine}
+
+Contents of USER.md (user profile; entries: ${visibleUser.entryCount}; UTF-8 bytes: ${storeUser.used}/${storeUser.limit})
+<runtime-memory-file name="USER.md">
+${user || "(empty)"}
+</runtime-memory-file>
+
+Contents of MEMORY.md (working reference; entries: ${visibleMemory.entryCount}; UTF-8 bytes: ${storeMemory.used}/${storeMemory.limit})
+<runtime-memory-file name="MEMORY.md">
+${memory || "(empty)"}
+</runtime-memory-file>`
+		};
 	}
-	contextText() {
-		return this.contextProjection().text;
-	}
-	/** Read the exact Runtime revision and its prompt projection under one lock. */
-	contextProjection() {
-		const { snapshot, user, memory } = this.withLock(() => {
+	localContextProjection(branch) {
+		const branchScope = scopeBranch(branch);
+		return this.withLock(() => {
 			const file = this.readSource();
 			this.repairProjections(file);
 			const entries = file.entries.map((entry) => ({ ...entry }));
+			const visible = branchScope === void 0 ? entries : entries.filter((entry) => entry.target === "user" || entryMatchesBranch(entry, branchScope));
 			return {
 				snapshot: {
 					directory: this.directory,
@@ -1426,33 +1572,18 @@ var RuntimeMemoryController = class {
 					generatedAt: this.now().toISOString(),
 					entries,
 					targets: {
-						memory: this.targetView(entries, "memory"),
-						user: this.targetView(entries, "user")
+						memory: this.targetView(visible, "memory"),
+						user: this.targetView(visible, "user")
 					}
 				},
-				user: readFileSync(this.userPath, "utf8").trimEnd(),
-				memory: readFileSync(this.memoryPath, "utf8").trimEnd()
+				user: readFileSync(this.localUserPath, "utf8").trimEnd(),
+				memory: branchScope === void 0 ? readFileSync(this.memoryPath, "utf8").trimEnd() : markdown(visible, "memory").trimEnd(),
+				hidden: branchScope === void 0 ? 0 : entries.length - visible.length
 			};
 		});
-		const userUsage = snapshot.targets.user;
-		const memoryUsage = snapshot.targets.memory;
-		return {
-			revision: snapshot.revision,
-			text: `MNEMON RUNTIME MEMORY SNAPSHOT
-Revision: ${snapshot.revision}
-
-Contents of USER.md (user profile; entries: ${userUsage.entryCount}; UTF-8 bytes: ${userUsage.used}/${userUsage.limit})
-<runtime-memory-file name="USER.md">
-${user || "(empty)"}
-</runtime-memory-file>
-
-Contents of MEMORY.md (working reference; entries: ${memoryUsage.entryCount}; UTF-8 bytes: ${memoryUsage.used}/${memoryUsage.limit})
-<runtime-memory-file name="MEMORY.md">
-${memory || "(empty)"}
-</runtime-memory-file>`
-		};
 	}
 	mutate(request) {
+		if (request.target === "user" && this.userController !== void 0) return this.userController.mutate(request);
 		const operation = this.queue.then(() => this.withLock(() => {
 			const beforeRevision = revision(this.readSource());
 			return {
@@ -1478,12 +1609,13 @@ ${memory || "(empty)"}
 	}
 	/** Resolve exactly which committed entries survive a blocked mutation and are safe to compact. */
 	planMaintenance(request) {
+		if (request.target === "user" && this.userController !== void 0) return this.userController.planMaintenance(request);
 		const operation = this.queue.then(() => this.withLock(() => {
 			const file = this.readSource();
 			const prepared = prepareMutation(file.entries, request, this.now().toISOString());
 			const used = byteCount(file.entries, request.target);
 			const projected = byteCount(prepared.projectedEntries, request.target);
-			const limit = RUNTIME_MEMORY_LIMITS[request.target];
+			const limit = this.limits[request.target];
 			return {
 				revision: revision(file),
 				action: request.action,
@@ -1504,14 +1636,16 @@ ${memory || "(empty)"}
 		return operation;
 	}
 	/** Commit semantic compaction and the original mutation together, or leave every local file unchanged. */
-	compactAndMutate(expectedRevision, request, compacted, maxCompactedBytes = RUNTIME_MEMORY_LIMITS[request.target], lineage = []) {
+	compactAndMutate(expectedRevision, request, compacted, maxCompactedBytes, lineage = []) {
+		if (request.target === "user" && this.userController !== void 0) return this.userController.compactAndMutate(expectedRevision, request, compacted, maxCompactedBytes, lineage);
 		const operation = this.queue.then(() => this.withLock(() => {
 			const file = this.readSource();
 			const beforeRevision = revision(file);
 			if (beforeRevision !== expectedRevision) throw new RuntimeMemoryConflictError();
 			const now = this.now().toISOString();
 			const prepared = prepareMutation(file.entries, request, now);
-			if (!Number.isInteger(maxCompactedBytes) || maxCompactedBytes < 0 || maxCompactedBytes > RUNTIME_MEMORY_LIMITS[request.target]) throw new Error("compaction byte budget is invalid");
+			const compactedByteBudget = maxCompactedBytes ?? this.limits[request.target];
+			if (!Number.isInteger(compactedByteBudget) || compactedByteBudget < 0 || compactedByteBudget > this.limits[request.target]) throw new Error("compaction byte budget is invalid");
 			if (!prepared.changed) return {
 				result: this.result(request.target, prepared.projectedEntries, prepared.fields),
 				beforeRevision,
@@ -1520,10 +1654,10 @@ ${memory || "(empty)"}
 			const replacements = compactionCandidates(compacted, prepared.compactableEntries, request.target, now);
 			if (prepared.pendingEntry !== void 0 && replacements.some((entry) => entry.content === prepared.pendingEntry.content)) throw new Error("compacted runtime memory duplicates the pending mutation");
 			if (prepared.excludedEntry !== void 0 && replacements.some((entry) => entry.content === prepared.excludedEntry.content)) throw new Error("compacted runtime memory reintroduces the replaced or removed entry");
-			const targetEntries = [...packCompactionCandidates(replacements, request.target, maxCompactedBytes), ...prepared.pendingEntry === void 0 ? [] : [prepared.pendingEntry]];
+			const targetEntries = [...packCompactionCandidates(replacements, request.target, compactedByteBudget), ...prepared.pendingEntry === void 0 ? [] : [prepared.pendingEntry]];
 			const entries = [...file.entries.filter((entry) => entry.target !== request.target), ...targetEntries];
 			const used = byteCount(entries, request.target);
-			const limit = RUNTIME_MEMORY_LIMITS[request.target];
+			const limit = this.limits[request.target];
 			if (used > limit) throw new RuntimeMemoryCapacityError(request.target, byteCount(file.entries, request.target), used, limit);
 			const next = {
 				version: 1,
@@ -1559,17 +1693,19 @@ ${memory || "(empty)"}
 		return operation;
 	}
 	/** Apply an LLM-produced compaction only to the exact snapshot it reviewed. */
-	compactTarget(expectedRevision, target, compacted, maxBytes = RUNTIME_MEMORY_LIMITS[target], lineage = []) {
+	compactTarget(expectedRevision, target, compacted, maxBytes, lineage = []) {
+		if (target === "user" && this.userController !== void 0) return this.userController.compactTarget(expectedRevision, target, compacted, maxBytes, lineage).then(() => this.snapshot());
 		const operation = this.queue.then(() => this.withLock(() => {
 			const file = this.readSource();
 			const beforeRevision = revision(file);
 			if (beforeRevision !== expectedRevision) throw new RuntimeMemoryConflictError();
-			if (!Number.isInteger(maxBytes) || maxBytes < 0 || maxBytes > RUNTIME_MEMORY_LIMITS[target]) throw new Error("compaction byte budget is invalid");
+			const byteBudget = maxBytes ?? this.limits[target];
+			if (!Number.isInteger(byteBudget) || byteBudget < 0 || byteBudget > this.limits[target]) throw new Error("compaction byte budget is invalid");
 			const now = this.now().toISOString();
-			const fitted = packCompactionCandidates(compactionCandidates(compacted, file.entries.filter((entry) => entry.target === target), target, now), target, maxBytes);
+			const fitted = packCompactionCandidates(compactionCandidates(compacted, file.entries.filter((entry) => entry.target === target), target, now), target, byteBudget);
 			const entries = [...file.entries.filter((entry) => entry.target !== target), ...fitted];
 			const used = byteCount(entries, target);
-			const limit = RUNTIME_MEMORY_LIMITS[target];
+			const limit = this.limits[target];
 			if (used > limit) throw new RuntimeMemoryCapacityError(target, byteCount(file.entries, target), used, limit);
 			this.persist({
 				version: 1,
@@ -1600,7 +1736,7 @@ ${memory || "(empty)"}
 			return snapshot;
 		});
 		this.queue = operation.catch(() => void 0);
-		return operation;
+		return this.userController === void 0 ? operation : operation.then(() => this.snapshot());
 	}
 	initialize() {
 		mkdirSync(this.directory, {
@@ -1617,7 +1753,7 @@ ${memory || "(empty)"}
 		const prepared = prepareMutation(file.entries, request, this.now().toISOString());
 		if (!prepared.changed) return this.result(request.target, prepared.projectedEntries, prepared.fields);
 		const used = byteCount(prepared.projectedEntries, request.target);
-		const limit = RUNTIME_MEMORY_LIMITS[request.target];
+		const limit = this.limits[request.target];
 		if (used > limit) throw new RuntimeMemoryCapacityError(request.target, byteCount(file.entries, request.target), used, limit);
 		this.persist({
 			version: 1,
@@ -1633,7 +1769,7 @@ ${memory || "(empty)"}
 			entryCount: entries.filter((entry) => entry.target === target).length,
 			usage: {
 				used: byteCount(entries, target),
-				limit: RUNTIME_MEMORY_LIMITS[target]
+				limit: this.limits[target]
 			},
 			...fields.added === void 0 ? {} : { added: fields.added },
 			...fields.replaced === void 0 ? {} : { replaced: fields.replaced },
@@ -1645,7 +1781,7 @@ ${memory || "(empty)"}
 			target,
 			entryCount: entries.filter((entry) => entry.target === target).length,
 			used: byteCount(entries, target),
-			limit: RUNTIME_MEMORY_LIMITS[target],
+			limit: this.limits[target],
 			markdownPath: target === "memory" ? this.memoryPath : this.userPath
 		};
 	}
@@ -1689,7 +1825,7 @@ ${memory || "(empty)"}
 		});
 		const nonce = `${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`;
 		const writes = [
-			[this.userPath, markdown(file.entries, "user")],
+			[this.localUserPath, markdown(file.entries, "user")],
 			[this.memoryPath, markdown(file.entries, "memory")],
 			[this.sourcePath, `${JSON.stringify(file, null, 2)}\n`]
 		];
@@ -1705,7 +1841,7 @@ ${memory || "(empty)"}
 		}
 	}
 	repairProjections(file) {
-		for (const [path, target] of [[this.userPath, "user"], [this.memoryPath, "memory"]]) {
+		for (const [path, target] of [[this.localUserPath, "user"], [this.memoryPath, "memory"]]) {
 			const expected = markdown(file.entries, target);
 			let current;
 			try {
@@ -1950,7 +2086,7 @@ function decodeArchive(base64) {
 	if (bytes.length === 0 || bytes.length > 50331648) throw new Error("Mnemon Pack archive is empty or too large");
 	return bytes;
 }
-function parseArchive(base64) {
+function parseArchive(base64, runtimeLimits = RUNTIME_MEMORY_LIMITS) {
 	const archive = decodeArchive(base64);
 	let count = 0;
 	let expandedBytes = 0;
@@ -1981,8 +2117,8 @@ function parseArchive(base64) {
 		const expected = checksumFiles[path];
 		if (typeof expected !== "string" || expected !== sha256$1(files[path])) throw new Error(`Mnemon Pack checksum mismatch: ${path}`);
 	}
-	validatePackPayload(files, manifest.components);
-	const actualSummary = summaryFor(manifest.components, files);
+	validatePackPayload(files, manifest.components, runtimeLimits);
+	const actualSummary = summaryFor(manifest.components, files, runtimeLimits);
 	return {
 		archiveBytes: archive.length,
 		expandedBytes,
@@ -1993,7 +2129,7 @@ function parseArchive(base64) {
 		}
 	};
 }
-function parseRuntime(value) {
+function parseRuntime(value, limits = RUNTIME_MEMORY_LIMITS) {
 	const source = record$2(value);
 	if (source?.version !== 1 || !Array.isArray(source.entries)) throw new Error("runtime memories.json is invalid");
 	const entries = source.entries.map((raw) => {
@@ -2014,7 +2150,7 @@ function parseRuntime(value) {
 			updated_at: entry.updated_at
 		};
 	});
-	for (const target of ["user", "memory"]) if (runtimeBytes(entries, target) > RUNTIME_MEMORY_LIMITS[target]) throw new Error(`runtime ${target} memory exceeds its ${RUNTIME_MEMORY_LIMITS[target]} byte limit`);
+	for (const target of ["user", "memory"]) if (runtimeBytes(entries, target) > limits[target]) throw new Error(`runtime ${target} memory exceeds its ${limits[target]} byte limit`);
 	return {
 		version: 1,
 		entries
@@ -2089,8 +2225,8 @@ function parseRegistry(value) {
 function validDatabase(bytes, path) {
 	if (bytes.length < 100 || !Buffer.from(bytes.subarray(0, SQLITE_HEADER.length)).equals(SQLITE_HEADER)) throw new Error(`${path} is not a SQLite mnemon.db`);
 }
-function validatePackPayload(files, components) {
-	if (components.includes("runtime")) parseRuntime(json(files["payload/runtime/memories.json"] ?? /* @__PURE__ */ new Uint8Array(), "payload/runtime/memories.json"));
+function validatePackPayload(files, components, runtimeLimits) {
+	if (components.includes("runtime")) parseRuntime(json(files["payload/runtime/memories.json"] ?? /* @__PURE__ */ new Uint8Array(), "payload/runtime/memories.json"), runtimeLimits);
 	if (components.includes("documents")) {
 		const index = parseDocumentIndex(json(files["payload/documents/index.json"] ?? /* @__PURE__ */ new Uint8Array(), "payload/documents/index.json"));
 		for (const document of index.documents) {
@@ -2171,9 +2307,9 @@ function emptyRuntime() {
 		entries: []
 	};
 }
-function readCurrentRuntime(root) {
+function readCurrentRuntime(root, limits = RUNTIME_MEMORY_LIMITS) {
 	const path = join(root, "runtime", "memories.json");
-	return existsSync(path) ? parseRuntime(JSON.parse(readFileSync(path, "utf8"))) : emptyRuntime();
+	return existsSync(path) ? parseRuntime(JSON.parse(readFileSync(path, "utf8")), limits) : emptyRuntime();
 }
 function writeRuntime(directory, file) {
 	mkdirSync(directory, {
@@ -2305,12 +2441,12 @@ function writeRegistry(directory, registry, databases) {
 	}
 	writeFileSync(join(directory, ".dsh-memory-bodies.json"), `${JSON.stringify(registry, null, 2)}\n`, { mode: 384 });
 }
-function componentItems(component, files) {
-	if (component === "runtime") return parseRuntime(json(files["payload/runtime/memories.json"], "payload/runtime/memories.json")).entries.length;
+function componentItems(component, files, runtimeLimits = RUNTIME_MEMORY_LIMITS) {
+	if (component === "runtime") return parseRuntime(json(files["payload/runtime/memories.json"], "payload/runtime/memories.json"), runtimeLimits).entries.length;
 	if (component === "documents") return parseDocumentIndex(json(files["payload/documents/index.json"], "payload/documents/index.json")).documents.length;
 	return parseRegistry(json(files["payload/data/.dsh-memory-bodies.json"], "payload/data/.dsh-memory-bodies.json")).bodies.length;
 }
-function summaryFor(components, files) {
+function summaryFor(components, files, runtimeLimits = RUNTIME_MEMORY_LIMITS) {
 	return components.map((component) => {
 		const prefix = `payload/${COMPONENT_DIRECTORIES[component]}/`;
 		const entries = Object.entries(files).filter(([path]) => path.startsWith(prefix));
@@ -2318,14 +2454,14 @@ function summaryFor(components, files) {
 			component,
 			files: entries.length,
 			bytes: entries.reduce((sum, [, value]) => sum + value.length, 0),
-			items: componentItems(component, files)
+			items: componentItems(component, files, runtimeLimits)
 		};
 	});
 }
-function collectExport(root, components) {
+function collectExport(root, components, runtimeLimits = RUNTIME_MEMORY_LIMITS) {
 	const files = {};
 	if (components.includes("runtime")) {
-		const runtime = readCurrentRuntime(root);
+		const runtime = readCurrentRuntime(root, runtimeLimits);
 		files["payload/runtime/memories.json"] = strToU8(`${JSON.stringify(runtime, null, 2)}\n`);
 		files["payload/runtime/USER.md"] = strToU8(runtimeProjection(runtime.entries, "user"));
 		files["payload/runtime/MEMORY.md"] = strToU8(runtimeProjection(runtime.entries, "memory"));
@@ -2342,9 +2478,9 @@ function collectExport(root, components) {
 	}
 	return files;
 }
-function mergeRuntime(root, pack) {
-	const current = readCurrentRuntime(root);
-	const incoming = parseRuntime(json(pack.files["payload/runtime/memories.json"], "payload/runtime/memories.json"));
+function mergeRuntime(root, pack, runtimeLimits) {
+	const current = readCurrentRuntime(root, runtimeLimits);
+	const incoming = parseRuntime(json(pack.files["payload/runtime/memories.json"], "payload/runtime/memories.json"), runtimeLimits);
 	const keys = new Set(current.entries.map((entry) => `${entry.target}\0${entry.content}`));
 	const entries = [...current.entries];
 	for (const entry of incoming.entries) {
@@ -2357,7 +2493,7 @@ function mergeRuntime(root, pack) {
 	return parseRuntime({
 		version: 1,
 		entries
-	});
+	}, runtimeLimits);
 }
 function mergeDocuments(root, pack) {
 	const current = readCurrentDocuments(root);
@@ -2423,7 +2559,7 @@ function reconcilePersistedStore(root) {
 		rmSync(temporary, { force: true });
 	}
 }
-function stageImport(root, pack, components, mode) {
+function stageImport(root, pack, components, mode, runtimeLimits) {
 	const staging = join(root, `.dsh-pack-stage-${randomUUID()}`);
 	mkdirSync(staging, {
 		recursive: true,
@@ -2431,7 +2567,7 @@ function stageImport(root, pack, components, mode) {
 	});
 	try {
 		if (components.includes("runtime")) {
-			const runtime = mode === "merge" ? mergeRuntime(root, pack) : parseRuntime(json(pack.files["payload/runtime/memories.json"], "payload/runtime/memories.json"));
+			const runtime = mode === "merge" ? mergeRuntime(root, pack, runtimeLimits) : parseRuntime(json(pack.files["payload/runtime/memories.json"], "payload/runtime/memories.json"), runtimeLimits);
 			writeRuntime(join(staging, "runtime"), runtime);
 		}
 		if (components.includes("documents")) {
@@ -2530,12 +2666,17 @@ var MnemonPackManager = class {
 	afterImport;
 	now;
 	root;
+	runtimeLimits;
 	constructor(runner, config, afterImport = () => {}, now = () => /* @__PURE__ */ new Date()) {
 		this.runner = runner;
 		this.config = config;
 		this.afterImport = afterImport;
 		this.now = now;
 		this.root = resolve(runner.effectiveDataDir());
+		this.runtimeLimits = {
+			memory: config.runtimeMemory.memoryLimitBytes,
+			user: config.runtimeMemory.userLimitBytes
+		};
 	}
 	target() {
 		return {
@@ -2548,9 +2689,9 @@ var MnemonPackManager = class {
 		return this.runner.withExclusive(async () => {
 			await new Promise((resolveReady) => setImmediate(resolveReady));
 			return withLocks(this.root, components, () => {
-				const payload = collectExport(this.root, components);
+				const payload = collectExport(this.root, components, this.runtimeLimits);
 				const exportedAt = this.now().toISOString();
-				const summary = summaryFor(components, payload);
+				const summary = summaryFor(components, payload, this.runtimeLimits);
 				const manifest = {
 					format: MNEMON_PACK_FORMAT,
 					version: 1,
@@ -2589,7 +2730,7 @@ var MnemonPackManager = class {
 		});
 	}
 	inspectPack(base64, fileName) {
-		const pack = parseArchive(base64);
+		const pack = parseArchive(base64, this.runtimeLimits);
 		const sanitizedName = safeName(fileName);
 		return {
 			...sanitizedName === void 0 ? {} : { fileName: sanitizedName },
@@ -2602,7 +2743,7 @@ var MnemonPackManager = class {
 		};
 	}
 	async importPack(base64, options) {
-		const pack = parseArchive(base64);
+		const pack = parseArchive(base64, this.runtimeLimits);
 		if (options.mode !== "merge" && options.mode !== "replace") throw new Error("Pack import mode must be merge or replace");
 		if (options.components !== void 0 && (new Set(options.components).size !== options.components.length || options.components.some((component) => !COMPONENT_ORDER.includes(component)))) throw new Error("requested import components are invalid");
 		const components = options.components === void 0 ? pack.manifest.components : COMPONENT_ORDER.filter((component) => options.components.includes(component));
@@ -2614,7 +2755,7 @@ var MnemonPackManager = class {
 				mode: 448
 			});
 			return withLocks(this.root, components, () => {
-				const staging = stageImport(this.root, pack, components, options.mode);
+				const staging = stageImport(this.root, pack, components, options.mode, this.runtimeLimits);
 				commitStaging(this.root, staging, components);
 				this.afterImport(components);
 				return {
@@ -5481,6 +5622,37 @@ function registerBuiltinMemoryAdapters(catalog) {
 	};
 }
 //#endregion
+//#region src/git-branch.ts
+const GIT_BRANCH_TIMEOUT_MS = 2e3;
+/**
+* Resolve the current git branch of a workspace root. Returns undefined when
+* the directory is not a git working tree, HEAD is detached, or the probe
+* fails or times out, so callers fall back to the unfiltered view.
+*/
+function resolveGitBranch(cwd) {
+	const root = cwd?.trim();
+	if (root === void 0 || root === "") return void 0;
+	try {
+		const branch = execFileSync("git", [
+			"-C",
+			root,
+			"branch",
+			"--show-current"
+		], {
+			encoding: "utf8",
+			timeout: GIT_BRANCH_TIMEOUT_MS,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+		return branch === "" ? void 0 : branch;
+	} catch {
+		return;
+	}
+}
+//#endregion
 //#region src/memory-view.ts
 function hash(value) {
 	return createHash("sha256").update(value).digest("hex");
@@ -5489,12 +5661,12 @@ function workspace(scope) {
 	const value = scope?.workspaceId?.trim();
 	return value === void 0 || value === "" ? void 0 : value;
 }
-function runtimeSource(runtimeMemory) {
+function createRuntimeMemorySource(runtimeMemory, resolveBranch = resolveGitBranch) {
 	return {
 		layerId: "runtime",
 		mode: "eager",
-		snapshot: () => {
-			const projection = runtimeMemory.contextProjection();
+		snapshot: (context) => {
+			const projection = runtimeMemory.contextProjection(resolveBranch(workspace(context.scope)));
 			return {
 				revision: projection.revision,
 				wake: projection.text
@@ -5555,9 +5727,9 @@ function memorySpacesSource(service) {
 		}
 	};
 }
-function createDefaultMemoryTurnViewManager(kernel, sources) {
+function createDefaultMemoryTurnViewManager(kernel, sources, options = {}) {
 	return new MemoryTurnViewManager(kernel, [
-		runtimeSource(sources.runtimeMemory),
+		createRuntimeMemorySource(sources.runtimeMemory, options.resolveBranch ?? resolveGitBranch),
 		documentsSource(sources.documents),
 		memorySpacesSource(sources.service)
 	]);
@@ -5654,7 +5826,16 @@ function createRuntimeGraph(config, workspaceRoot, extensions) {
 			return receiptBridge.record(operation);
 		};
 		const service = new MnemonService(runner, config, void 0, void 0, void 0, recordCommit);
-		const runtimeMemory = new RuntimeMemoryController(runner, void 0, recordCommit);
+		const globalUserConfig = {
+			...config,
+			storageScope: "global"
+		};
+		delete globalUserConfig.dataDir;
+		const globalUserRunner = config.runtimeUserScope === "global" ? createRunner(globalUserConfig) : void 0;
+		const runtimeMemory = new RuntimeMemoryController(runner, void 0, recordCommit, {
+			memory: config.runtimeMemory.memoryLimitBytes,
+			user: config.runtimeMemory.userLimitBytes
+		}, globalUserRunner);
 		const documents = new DocumentManager(void 0, void 0, () => runner.effectiveDataDir(), recordCommit);
 		const storage = new StorageScopeInspector(runner, config);
 		const packs = new MnemonPackManager(runner, config, (components) => {
@@ -6360,10 +6541,13 @@ function naturalEvidence(evidence) {
 		return `${index + 1}. [${citation}]${meta === "" ? "" : ` ${meta}`}\n${indentedText(item.content)}`;
 	}).join("\n");
 }
+function runtimeEntryScopeMeta(entry) {
+	return entry.branches && entry.branches.length > 0 ? ` branches=${entry.branches.join(",")}` : "";
+}
 function runtimeSnapshotContext(target, entries) {
 	return `Committed ${target === "memory" ? "MEMORY.md" : "USER.md"} snapshot (read-only run data; numbering is one-based):
 <runtime-memory-snapshot target="${target}">
-${entries.length === 0 ? "(empty)" : entries.map((entry, index) => `${index + 1}. [importance=${entry.importance}] ${entry.content}`).join(RUNTIME_ENTRY_DELIMITER)}
+${entries.length === 0 ? "(empty)" : entries.map((entry, index) => `${index + 1}. [importance=${entry.importance}${runtimeEntryScopeMeta(entry)}] ${entry.content}`).join(RUNTIME_ENTRY_DELIMITER)}
 </runtime-memory-snapshot>`;
 }
 function runtimeRoutingExcerpt(value) {
@@ -6379,7 +6563,7 @@ function runtimeRouteChunks(entries) {
 	let used = 0;
 	for (const [offset, entry] of entries.entries()) {
 		const index = offset + 1;
-		const line = `${index}. [importance=${entry.importance}] ${runtimeRoutingExcerpt(entry.content)}`;
+		const line = `${index}. [importance=${entry.importance}${runtimeEntryScopeMeta(entry)}] ${runtimeRoutingExcerpt(entry.content)}`;
 		const separatorLength = rendered.length === 0 ? 0 : 3;
 		if (rendered.length > 0 && used + separatorLength + line.length > RUNTIME_ROUTE_CHUNK_CHARACTERS) {
 			chunks.push({
@@ -6488,7 +6672,8 @@ function runtimeMigrationSources(revision, entries) {
 		reference: `runtime:${revision}:memory:${offset + 1}`,
 		digest: sha256(JSON.stringify({
 			content: entry.content,
-			importance: entry.importance
+			importance: entry.importance,
+			...entry.branches === void 0 ? {} : { branches: entry.branches }
 		}))
 	}));
 }
@@ -6663,6 +6848,7 @@ var MnemonSubagentCoordinator = class {
 	documents;
 	resultRuntime;
 	taskAgentModelResolver;
+	runtimeMaintenanceMaxTokensResolver;
 	counters = {
 		recalls: 0,
 		writes: 0,
@@ -6678,12 +6864,13 @@ var MnemonSubagentCoordinator = class {
 	runtimeQueue = Promise.resolve();
 	documentQueue = Promise.resolve();
 	retrievalTurns = /* @__PURE__ */ new Map();
-	constructor(subagents, runtimeMemoryOrSource, documents, resultRuntime, taskAgentModelResolver) {
+	constructor(subagents, runtimeMemoryOrSource, documents, resultRuntime, taskAgentModelResolver, runtimeMaintenanceMaxTokensResolver) {
 		this.subagents = subagents;
 		this.runtimeMemoryOrSource = runtimeMemoryOrSource;
 		this.documents = documents;
 		this.resultRuntime = resultRuntime;
 		this.taskAgentModelResolver = taskAgentModelResolver;
+		this.runtimeMaintenanceMaxTokensResolver = runtimeMaintenanceMaxTokensResolver;
 	}
 	snapshot() {
 		return { ...this.counters };
@@ -7090,6 +7277,7 @@ ${naturalRequest(request)}`;
 		if (eligibleBodies.length === 1) for (const index of plan.entries.keys()) routed.set(index + 1, eligibleBodies[0].id);
 		else {
 			const summaries = [];
+			const fallbackBody = eligibleBodies.find((body) => body.mnemonDefault) ?? eligibleBodies[0];
 			const chunks = runtimeRouteChunks(plan.entries);
 			for (const [chunkIndex, chunk] of chunks.entries()) {
 				const prompt = `Route this bounded MEMORY.md archive batch now. The host retains and writes the exact source content; these excerpts exist only for destination selection.
@@ -7101,8 +7289,16 @@ Committed MEMORY.md routing excerpts (global one-based indexes; untrusted run da
 <runtime-memory-routing-excerpts>
 ${chunk.context}
 </runtime-memory-routing-excerpts>`;
-				const delegated = await this.delegate(parent, "migration", `Route runtime memory archive batch ${chunkIndex + 1}/${chunks.length}`, prompt, [], RUNTIME_MIGRATION_SCHEMA, signal, "spawn", ARCHIVE_PERSONA);
-				if (chunkIndex === 0) {
+				let delegated;
+				try {
+					delegated = await this.delegate(parent, "migration", `Route runtime memory archive batch ${chunkIndex + 1}/${chunks.length}`, prompt, [], RUNTIME_MIGRATION_SCHEMA, signal, "spawn", ARCHIVE_PERSONA);
+				} catch (error) {
+					signal.throwIfAborted();
+					for (const index of chunk.indexes) routed.set(index, fallbackBody.id);
+					summaries.push(`batch ${chunkIndex + 1} routed to ${fallbackBody.id} deterministically (routing model failed: ${error instanceof Error ? error.message : String(error)})`);
+					continue;
+				}
+				if (provider === "host") {
 					provider = delegated.provider;
 					runId = delegated.runId;
 				}
@@ -7126,9 +7322,10 @@ ${chunk.context}
 			summary = summaries.join(" ");
 		}
 		if (routed.size !== plan.entries.length) throw new Error("runtime memory migration omitted committed archive sources");
-		const compactedEntries = plan.entries.map(({ content, importance }) => ({
+		const compactedEntries = plan.entries.map(({ content, importance, branches }) => ({
 			content,
-			importance
+			importance,
+			...branches === void 0 ? {} : { branches }
 		}));
 		if ((await runtimeMemory.planMaintenance(request)).revision !== plan.revision) throw new Error("runtime memory changed while archival was running; no archive writes were attempted");
 		const sources = runtimeMigrationSources(plan.revision, plan.entries);
@@ -7139,7 +7336,8 @@ ${chunk.context}
 				category: "context",
 				importance: entry.importance === "critical" ? 5 : entry.importance === "low" ? 1 : 3,
 				source: "agent",
-				memoryBodyId: routed.get(source.index)
+				memoryBodyId: routed.get(source.index),
+				...entry.branches === void 0 || entry.branches.length === 0 ? {} : { tags: entry.branches.map((branch) => `branch:${branch}`) }
 			};
 		}), signal);
 		if (archiveResults.length !== sources.length) throw new Error("runtime archive batch did not return one receipt per source entry");
@@ -7345,7 +7543,7 @@ ${runtimeSnapshotContext("user", plan.entries)}`;
 			const completionPersona = `${persona}
 
 Completion protocol: call \`${resultToolName}\` exactly once with the final result matching its parameter schema. This is the only completion channel for this run. Do not finish with a plain-text answer.`;
-			const perOpMaxTokens = operation === "migration" || operation === "compaction" || operation === "document-archive" ? 8192 : operation === "metadata-maintenance" ? 4096 : void 0;
+			const perOpMaxTokens = operation === "migration" || operation === "compaction" ? this.runtimeMaintenanceMaxTokensResolver?.() ?? 8192 : operation === "document-archive" ? 8192 : operation === "metadata-maintenance" ? 4096 : void 0;
 			const fixed = this.taskAgentModelResolver?.();
 			const baseAgentOptions = perOpMaxTokens === void 0 ? void 0 : { maxTokens: perOpMaxTokens };
 			const resolvedAgentOptions = fixed === void 0 ? baseAgentOptions : {
@@ -7664,6 +7862,16 @@ function createPluginMessage(text, form, summary) {
 function sourceOf(message) {
 	return message.source;
 }
+/**
+* Whether an event is a durable user message this plugin produced.
+*/
+function isOwnUserMessageEvent(event) {
+	if (event?.type !== "user/message") return false;
+	const source = event.data.source;
+	if (typeof source !== "object" || source === null) return false;
+	const { kind, plugin } = source;
+	return kind === "plugin" && plugin === "dsh-mnemon";
+}
 function eventTurn(event) {
 	return typeof event.data.turn === "number" ? event.data.turn : void 0;
 }
@@ -7733,6 +7941,11 @@ var MnemonAgentLifecycle = class {
 	guidedTurns = /* @__PURE__ */ new Set();
 	memoryActivity = new TurnActivityProjection();
 	turnActivity = /* @__PURE__ */ new Map();
+	/**
+	* Fallback presence marker for hosts that publish no surface projection.
+	* A host with a surface answers the question from what the model can
+	* actually see, which is what makes a rewind self-correcting.
+	*/
 	cueInjected = false;
 	idleReviewTimer;
 	reviewController;
@@ -7813,6 +8026,24 @@ var MnemonAgentLifecycle = class {
 		const pinned = this.pinnedView;
 		return pinned === void 0 ? void 0 : pinned.manager.wake(pinned.context.viewId);
 	}
+	/**
+	* Whether the reminder is still visible to the model.
+	*
+	* Read from the surface rather than from `cueInjected`, because a rewind is a
+	* surface replacement inside the same live session: it does not emit
+	* `agent/session-start`, so a session-scoped flag stays set and the reminder
+	* never returns. The durable event log cannot answer this either, since it is
+	* append-only and still contains the discarded message.
+	*
+	* Scanning forward is cheap: the reminder sits near the head of the surface,
+	* so the loop exits after a few nodes even on a long session.
+	*/
+	cueAlreadyVisible() {
+		const nodes = this.agent.session.surface?.nodes;
+		if (nodes === void 0) return this.cueInjected;
+		for (const seq of nodes) if (isOwnUserMessageEvent(this.agent.session.events[seq])) return true;
+		return false;
+	}
 	async preStep(payload, next) {
 		if (payload.step === 1) this.cancelIdleReview(true);
 		const decision = await next();
@@ -7833,7 +8064,7 @@ var MnemonAgentLifecycle = class {
 			this.counters.primes += 1;
 			this.mark("prime");
 		}
-		if (this.cueInjected) return decision;
+		if (this.cueAlreadyVisible()) return decision;
 		const reminder = guidedReminder(this.config);
 		if (reminder === void 0) return decision;
 		this.cueInjected = true;
@@ -9152,12 +9383,16 @@ function createWriteHandler(input, lifecycle, runtimeMemory, versions) {
 					requireLayer(resolved.graph, "runtime", "write");
 					if (resolved.graph.runtimeMemory === void 0) throw new Error("runtime memory is unavailable");
 					{
+						const branches = payload.branches === void 0 ? void 0 : Array.isArray(payload.branches) && payload.branches.every((branch) => typeof branch === "string") ? payload.branches : (() => {
+							throw new Error("branches must be an array of strings");
+						})();
 						const request = {
 							action: String(payload.action ?? ""),
 							target: String(payload.target ?? ""),
 							...payload.content === void 0 ? {} : { content: String(payload.content) },
 							...payload.old_text === void 0 ? {} : { oldText: String(payload.old_text) },
-							...payload.importance === void 0 ? {} : { importance: String(payload.importance) }
+							...payload.importance === void 0 ? {} : { importance: String(payload.importance) },
+							...branches === void 0 ? {} : { branches }
 						};
 						const sessionId = String(payload.sessionId ?? "").trim();
 						return success$1(inspectionDiverged || lifecycle === void 0 || sessionId === "" || resolved.explicitWorkspace && !alignedSession ? await resolved.graph.runtimeMemory.mutate(request) : await lifecycle.runtime(sessionId, request));
@@ -9411,6 +9646,7 @@ function object(value) {
 }
 const MUTABLE_FIELDS = [
 	"storageScope",
+	"runtimeUserScope",
 	"cliPath",
 	"dataDir",
 	"customPackId",
@@ -9418,6 +9654,7 @@ const MUTABLE_FIELDS = [
 	"store",
 	"timeoutMs",
 	"defaultRecallLimit",
+	"runtimeMemory",
 	"embedding",
 	"recallQuality",
 	"routingGuidance",
@@ -9939,7 +10176,7 @@ function registerTools(ctx, serviceOrSource, coordinator, runtimeMemory, documen
 	}));
 	ctx.tools.register(definition({
 		name: "mnemon_runtime_memory",
-		description: "Maintain compact hot memory injected into future turns. Write only new reusable facts supplied or corrected by the user, or information the user explicitly asks to save. Never copy, promote, or summarize evidence returned by Documents, Recall, or Related unless the user explicitly asks to save that exact evidence; answering a read question must stay read-only. add creates one independent fact; replace corrects or consolidates one uniquely matched entry; remove is only for an explicitly withdrawn, obsolete, or wrong entry. target=user is only for who the user is; target=memory is for project/environment/decisions/lessons. Skip questions, guesses, assistant-authored claims, temporary progress, completed-work logs, raw dumps, secrets, rediscoverable facts, and skill-covered guidance. This tool exclusively writes runtime MEMORY.md and USER.md; capacity archival and compaction are automatic.",
+		description: "Maintain compact hot memory injected into future turns. Write only new reusable facts supplied or corrected by the user, or information the user explicitly asks to save. Never copy, promote, or summarize evidence returned by Documents, Recall, or Related unless the user explicitly asks to save that exact evidence; answering a read question must stay read-only. add creates one independent fact; replace corrects or consolidates one uniquely matched entry; remove is only for an explicitly withdrawn, obsolete, or wrong entry. target=user is only for who the user is; target=memory is for project/environment/decisions/lessons. Skip questions, guesses, assistant-authored claims, temporary progress, completed-work logs, raw dumps, secrets, rediscoverable facts, and skill-covered guidance. This tool exclusively writes runtime MEMORY.md and USER.md; capacity archival and compaction are automatic. Optional branches (git branch names, target=memory only) project an entry only in sessions on those branches: use them for branch-specific decisions and experiments, tag new branch-scoped entries with the git branch reported in the snapshot header, omit for cross-branch facts; on replace an empty list clears the scope, and an omitted list keeps the current scope.",
 		parameters: {
 			type: "object",
 			properties: {
@@ -9973,6 +10210,11 @@ function registerTools(ctx, serviceOrSource, coordinator, runtimeMemory, documen
 						"low"
 					],
 					description: "critical for explicit must/always/never rules; low for transient facts; normal by default."
+				},
+				branches: {
+					type: "array",
+					items: { type: "string" },
+					description: "Optional git branch names restricting where a target=memory entry is injected. Omit for cross-branch facts; on replace an empty list clears the scope and an omitted list keeps it. Never accepted for target=user."
 				}
 			},
 			required: ["action", "target"]
@@ -9989,7 +10231,8 @@ function registerTools(ctx, serviceOrSource, coordinator, runtimeMemory, documen
 				target: args.target,
 				...args.content === void 0 ? {} : { content: args.content },
 				...args.old_text === void 0 ? {} : { oldText: args.old_text },
-				...args.importance === void 0 ? {} : { importance: args.importance }
+				...args.importance === void 0 ? {} : { importance: args.importance },
+				...args.branches === void 0 ? {} : { branches: args.branches }
 			};
 			return isSubagent(exec.agent) ? runtime.runtimeMemory.mutate(request) : coordinator.runtime(requireAgent(exec), request, exec.signal);
 		},
@@ -10280,6 +10523,130 @@ function registerTools(ctx, serviceOrSource, coordinator, runtimeMemory, documen
 	}));
 }
 //#endregion
+//#region src/subagent-token-usage.ts
+/**
+* Mnemon-owned projection for provider usage after a subagent descriptor.
+*
+* Fork-backed subagents inherit the parent's durable event prefix. DSH's
+* generic `tokenUsage` projection intentionally totals that complete log, so
+* it cannot also represent the cost of the child shown in the subagent
+* catalog. This independent projection keeps the generic metric untouched
+* and resets at every durable descriptor.
+*/
+const tokenCountSchema = z$1.number().int().nonnegative();
+const tokenUsageSchema = z$1.object({
+	uncachedInputTokens: tokenCountSchema,
+	outputTokens: tokenCountSchema,
+	cacheReadTokens: tokenCountSchema,
+	cacheWriteTokens: tokenCountSchema
+}).strict();
+const tokenUsageStateSchema = z$1.object({
+	descriptorSeen: z$1.boolean(),
+	totals: tokenUsageSchema,
+	last: z$1.object({
+		turn: tokenCountSchema,
+		step: tokenCountSchema,
+		buckets: tokenUsageSchema
+	}).strict().nullable()
+}).strict();
+const emptyTokenUsage = () => ({
+	uncachedInputTokens: 0,
+	outputTokens: 0,
+	cacheReadTokens: 0,
+	cacheWriteTokens: 0
+});
+function nonnegativeInteger(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : void 0;
+}
+function usageBuckets(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const usage = value;
+	const inputTokens = nonnegativeInteger(usage.inputTokens);
+	const outputTokens = nonnegativeInteger(usage.outputTokens);
+	const cacheReadTokens = usage.cacheReadTokens === void 0 ? 0 : nonnegativeInteger(usage.cacheReadTokens);
+	const cacheWriteTokens = usage.cacheWriteTokens === void 0 ? 0 : nonnegativeInteger(usage.cacheWriteTokens);
+	if (inputTokens === void 0 || outputTokens === void 0 || cacheReadTokens === void 0 || cacheWriteTokens === void 0) return void 0;
+	return {
+		uncachedInputTokens: inputTokens,
+		outputTokens,
+		cacheReadTokens,
+		cacheWriteTokens
+	};
+}
+function usageSample(event) {
+	const turn = nonnegativeInteger(event.data.turn);
+	const step = nonnegativeInteger(event.data.step);
+	if (turn === void 0 || step === void 0) return void 0;
+	let rawUsage;
+	if (event.type === "assistant/chunk") {
+		const chunk = event.data.chunk;
+		if (typeof chunk !== "object" || chunk === null || Array.isArray(chunk)) return void 0;
+		const record = chunk;
+		if (record.type !== "usage") return void 0;
+		rawUsage = record.usage;
+	} else if (event.type === "assistant/message") rawUsage = event.data.usage;
+	else return;
+	const buckets = usageBuckets(rawUsage);
+	return buckets === void 0 ? void 0 : {
+		turn,
+		step,
+		buckets
+	};
+}
+function equalTokenUsage(left, right) {
+	return left.uncachedInputTokens === right.uncachedInputTokens && left.outputTokens === right.outputTokens && left.cacheReadTokens === right.cacheReadTokens && left.cacheWriteTokens === right.cacheWriteTokens;
+}
+function replaceTokenUsage(totals, previous, next) {
+	return {
+		uncachedInputTokens: totals.uncachedInputTokens - (previous?.uncachedInputTokens ?? 0) + next.uncachedInputTokens,
+		outputTokens: totals.outputTokens - (previous?.outputTokens ?? 0) + next.outputTokens,
+		cacheReadTokens: totals.cacheReadTokens - (previous?.cacheReadTokens ?? 0) + next.cacheReadTokens,
+		cacheWriteTokens: totals.cacheWriteTokens - (previous?.cacheWriteTokens ?? 0) + next.cacheWriteTokens
+	};
+}
+/**
+* Fold provider usage after the latest subagent descriptor. A fork may carry
+* an ancestor descriptor as part of its seed, so every descriptor resets the
+* fold and the child's own descriptor becomes the final authoritative origin.
+*/
+const mnemonSubagentTokenUsageProjectionDefinition = {
+	key: "mnemonSubagentTokenUsage",
+	stateVersion: 1,
+	stateSchema: tokenUsageStateSchema,
+	init: () => ({
+		descriptorSeen: false,
+		totals: emptyTokenUsage(),
+		last: null
+	}),
+	apply: (state, event) => {
+		if (event.type === "subagent/descriptor") return {
+			descriptorSeen: true,
+			totals: emptyTokenUsage(),
+			last: null
+		};
+		if (!state.descriptorSeen) return state;
+		const sample = usageSample(event);
+		if (sample === void 0) return state;
+		const previous = state.last !== null && state.last.turn === sample.turn && state.last.step === sample.step ? state.last.buckets : void 0;
+		if (previous !== void 0 && equalTokenUsage(previous, sample.buckets)) return state;
+		return {
+			descriptorSeen: true,
+			totals: replaceTokenUsage(state.totals, previous, sample.buckets),
+			last: sample
+		};
+	},
+	wire: {
+		viewSchema: tokenUsageSchema.nullable(),
+		view: (state) => state.descriptorSeen ? state.totals : null
+	}
+};
+/** Register lazily when the optional DSH projection service is present. */
+function registerMnemonSubagentTokenUsageProjection(ctx) {
+	ctx.inject(["sessionProjections"], (rawContext) => {
+		rawContext.sessionProjections?.register(mnemonSubagentTokenUsageProjectionDefinition);
+	});
+}
+//#endregion
 //#region src/index.ts
 const name = "dsh-mnemon";
 const provide = ["mnemonMemory"];
@@ -10301,6 +10668,7 @@ function optionalWorkspaceRegistry(ctx) {
 /** Mount native model tools on every DSH surface and UI RPC only when Web connection exists. */
 function apply(rawContext, config = {}) {
 	const ctx = rawContext;
+	registerMnemonSubagentTokenUsageProjection(ctx);
 	const extensions = memoryBoot;
 	ctx.provide?.("mnemonMemory", extensions);
 	const prepared = /* @__PURE__ */ new Map();
@@ -10350,7 +10718,7 @@ function apply(rawContext, config = {}) {
 			provider,
 			model
 		};
-	});
+	}, () => runtime.config.runtimeMemory.maintenanceMaxTokens);
 	const lifecycle = new MnemonLifecycle(ctx, coordinator, runtime.config, runtime);
 	ctx.effect(() => {
 		const stop = lifecycle.start();