@prometheus-ai/agent 0.5.0

package/src/memories/index.ts

@@ -0,0 +1,2227 @@
+import type { Database } from "bun:sqlite";
+import type * as fsNode from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { AgentMessage } from "@prometheus-ai/agent-core";
+import { clampThinkingLevelForModel, completeSimple, Effort, type Model } from "@prometheus-ai/ai";
+import { getAgentDbPath, getMemoriesDir, logger, parseJsonlLenient, prompt } from "@prometheus-ai/utils";
+import { readFile, walkUp } from "../capability/fs";
+import type { ModelRegistry } from "../config/model-registry";
+import { resolveModelRoleValue } from "../config/model-resolver";
+import type { Settings } from "../config/settings";
+import { SOURCE_PATHS } from "../discovery/helpers";
+import consolidationTemplate from "../prompts/memories/consolidation.md" with { type: "text" };
+import identityReviewTemplate from "../prompts/memories/identity_review.md" with { type: "text" };
+import postTurnReviewTemplate from "../prompts/memories/post_turn_review.md" with { type: "text" };
+import readPathTemplate from "../prompts/memories/read-path.md" with { type: "text" };
+import stageOneInputTemplate from "../prompts/memories/stage_one_input.md" with { type: "text" };
+import stageOneSystemTemplate from "../prompts/memories/stage_one_system.md" with { type: "text" };
+import type { AgentSession } from "../session/agent-session";
+import {
+	claimStage1Jobs,
+	clearMemoryData as clearMemoryDataInDb,
+	closeMemoryDb,
+	enqueueGlobalWatermark,
+	heartbeatGlobalJob,
+	listStage1OutputsForGlobal,
+	type MemoryThread,
+	markGlobalPhase2Failed,
+	markGlobalPhase2FailedUnowned,
+	markGlobalPhase2Succeeded,
+	markStage1Failed,
+	markStage1SucceededNoOutput,
+	markStage1SucceededWithOutput,
+	openMemoryDb,
+	recordBackgroundStage1Output,
+	type Stage1Claim,
+	type Stage1OutputRow,
+	tryClaimGlobalPhase2Job,
+	upsertThreads,
+} from "./storage";
+
+interface MemoryRuntimeConfig {
+	enabled: boolean;
+	selfImprovementMode: "memory-and-skills" | "off";
+	backgroundReviewMode: "memory-and-skills" | "off";
+	backgroundReviewEveryNTurns: number;
+	identityReviewMode: "propose" | "off";
+	curatorMode: "dry-run" | "off";
+	generatedSkillStaleAfterDays: number;
+	generatedSkillArchiveAfterDays: number;
+	maxRolloutsPerStartup: number;
+	maxRolloutAgeDays: number;
+	minRolloutIdleHours: number;
+	threadScanLimit: number;
+	maxRawMemoriesForGlobal: number;
+	stage1Concurrency: number;
+	stage1LeaseSeconds: number;
+	stage1RetryDelaySeconds: number;
+	phase2LeaseSeconds: number;
+	phase2RetryDelaySeconds: number;
+	phase2HeartbeatSeconds: number;
+	rolloutPayloadPercent: number;
+	phase1InputTokenLimit: number;
+	fallbackTokenLimit: number;
+	summaryInjectionTokenLimit: number;
+}
+
+const DEFAULTS: MemoryRuntimeConfig = {
+	enabled: false,
+	selfImprovementMode: "memory-and-skills",
+	backgroundReviewMode: "memory-and-skills",
+	backgroundReviewEveryNTurns: 10,
+	identityReviewMode: "propose",
+	curatorMode: "dry-run",
+	generatedSkillStaleAfterDays: 30,
+	generatedSkillArchiveAfterDays: 90,
+	maxRolloutsPerStartup: 64,
+	maxRolloutAgeDays: 30,
+	minRolloutIdleHours: 12,
+	threadScanLimit: 300,
+	maxRawMemoriesForGlobal: 200,
+	stage1Concurrency: 8,
+	stage1LeaseSeconds: 120,
+	stage1RetryDelaySeconds: 120,
+	phase2LeaseSeconds: 180,
+	phase2RetryDelaySeconds: 180,
+	phase2HeartbeatSeconds: 30,
+	rolloutPayloadPercent: 0.7,
+	phase1InputTokenLimit: 4_000,
+	fallbackTokenLimit: 16_000,
+	summaryInjectionTokenLimit: 5_000,
+};
+
+const GENERATED_MEMORY_SKILL_INDEX_LIMIT = 50;
+
+interface Stage1Stats {
+	claimed: number;
+	succeeded: number;
+	succeededNoOutput: number;
+	failed: number;
+	produced: number;
+	usage: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+		total: number;
+	};
+}
+
+interface Stage1OutputSchema {
+	raw_memory: string;
+	rollout_summary: string;
+	rollout_slug: string | null;
+}
+
+interface PostTurnReviewMessage {
+	role: "user" | "assistant";
+	content: string;
+}
+
+interface ConsolidationSkillFileSchema {
+	path: string;
+	content: string;
+}
+
+interface ConsolidationSkillSchema {
+	name: string;
+	content?: string;
+	scripts?: ConsolidationSkillFileSchema[];
+	templates?: ConsolidationSkillFileSchema[];
+	examples?: ConsolidationSkillFileSchema[];
+}
+interface ConsolidationOutputSchema {
+	memory_md: string;
+	user_md: string;
+	memory_summary: string;
+	skills: ConsolidationSkillSchema[];
+}
+
+type GeneratedMemorySkillState = "active" | "stale" | "archived";
+type GeneratedMemorySkillEvent = "use" | "view" | "patch";
+
+interface GeneratedMemorySkillUsageRecord {
+	schemaVersion: 1;
+	name: string;
+	source: "memory-consolidation";
+	state: GeneratedMemorySkillState;
+	pinned: boolean;
+	createdAt: string;
+	updatedAt: string;
+	lastSeenInConsolidationAt: string | null;
+	archivedAt: string | null;
+	archiveReason: string | null;
+	useCount: number;
+	viewCount: number;
+	patchCount: number;
+	lastUsedAt: string | null;
+	lastViewedAt: string | null;
+	lastPatchedAt: string | null;
+}
+
+interface GeneratedMemorySkillUsageFile {
+	schemaVersion: 1;
+	skills: Record<string, GeneratedMemorySkillUsageRecord>;
+}
+
+interface IdentityReviewResult {
+	soulProposal: string;
+	nativeSoulPath: string | null;
+	error?: string;
+}
+
+interface SkillCurationResult {
+	usage: GeneratedMemorySkillUsageFile;
+	active: string[];
+	pinnedStale: string[];
+	archived: string[];
+	staleCandidates: string[];
+	archiveCandidates: string[];
+	markedStale: string[];
+	reactivated: string[];
+	report: string;
+}
+
+export const MEMORY_ARTIFACTS = {
+	summary: "memory_summary.md",
+	memory: "MEMORY.md",
+	user: "USER.md",
+	selfImprovementReport: "self_improvement_report.md",
+	skillUsage: "skill_usage.json",
+	skillCuratorReport: "skill_curator_report.md",
+	soulProposal: "SOUL.proposed.md",
+} as const;
+
+const USER_PROFILE_OPEN_TAG = '<user_profile role="durable_user_context">';
+const USER_PROFILE_CLOSE_TAG = "</user_profile>";
+const POST_TURN_REVIEW_THREAD_PREFIX = "post-turn-review";
+const postTurnReviewStates = new WeakMap<
+	AgentSession,
+	{ lastReviewedUserTurns: number; running: boolean; unsubscribe: () => void }
+>();
+
+const FORBIDDEN_IDENTITY_ARTIFACT_PATTERNS: ReadonlyArray<{ label: string; pattern: RegExp }> = [
+	{ label: "soul_md", pattern: /\bsoul_md\b/i },
+	{ label: "SOUL.md", pattern: /\bSOUL\.md\b/i },
+	{ label: "SOUL.proposed.md", pattern: /\bSOUL\.proposed\.md\b/i },
+	{ label: "<soul>", pattern: /<\s*\/?\s*soul\b/i },
+	{ label: "<soul_proposal>", pattern: /<\s*\/?\s*soul[_-]?proposal\b/i },
+	{ label: "<soul_proposed>", pattern: /<\s*\/?\s*soul[_-]?proposed\b/i },
+	{ label: "<identity>", pattern: /<\s*\/?\s*identity\b/i },
+	{ label: "<personality>", pattern: /<\s*\/?\s*personality\b/i },
+	{ label: "agent_identity", pattern: /\bagent_identity\b/i },
+	{ label: "assistant_identity", pattern: /\bassistant_identity\b/i },
+	{ label: "prometheus_identity", pattern: /\bprometheus_identity\b/i },
+	{ label: "identity_md", pattern: /\bidentity_md\b/i },
+	{ label: "persona_md", pattern: /\bpersona_md\b/i },
+	{ label: "personality_md", pattern: /\bpersonality_md\b/i },
+	{ label: "agent_personality", pattern: /\bagent_personality\b/i },
+	{ label: "assistant_personality", pattern: /\bassistant_personality\b/i },
+	{ label: "prometheus_personality", pattern: /\bprometheus_personality\b/i },
+];
+
+/**
+ * Start the background memory startup pipeline.
+ *
+ * Skips for ephemeral sessions, subagent sessions, disabled settings, or DB failures.
+ */
+export function startMemoryStartupTask(options: {
+	session: AgentSession;
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	agentDir: string;
+	taskDepth: number;
+}): void {
+	const { session, settings, modelRegistry, agentDir, taskDepth } = options;
+	const cfg = loadMemoryConfig(settings);
+	if (!cfg.enabled) return;
+	if (taskDepth > 0) return;
+	if (!session.sessionManager.getSessionFile()) return;
+
+	const dbPath = getAgentDbPath(agentDir);
+	try {
+		const db = openMemoryDb(dbPath);
+		closeMemoryDb(db);
+	} catch (error) {
+		logger.debug("Memory startup skipped: state DB unavailable", { error: String(error) });
+		return;
+	}
+
+	attachPostTurnBackgroundReview({ session, settings, modelRegistry, agentDir, config: cfg });
+
+	void runMemoryStartup({ session, settings, modelRegistry, agentDir, config: cfg }).catch(error => {
+		logger.warn("Memory startup failed", { error: String(error) });
+	});
+}
+
+/**
+ * Build memory usage instructions for prompt injection.
+ */
+export async function buildMemoryToolDeveloperInstructions(
+	agentDir: string,
+	settings: Settings,
+): Promise<string | undefined> {
+	const cfg = loadMemoryConfig(settings);
+	if (!cfg.enabled) return undefined;
+	const memoryRoot = getMemoryRoot(agentDir, settings.getCwd());
+	const summaryPath = path.join(memoryRoot, MEMORY_ARTIFACTS.summary);
+
+	let text: string;
+	try {
+		text = await Bun.file(summaryPath).text();
+	} catch {
+		return undefined;
+	}
+
+	const summary = text.trim();
+	if (!summary) return undefined;
+	const truncated = truncateByApproxTokens(summary, cfg.summaryInjectionTokenLimit);
+	if (!truncated.trim()) return undefined;
+	const generatedMemorySkills = await buildGeneratedMemorySkillIndex(memoryRoot);
+
+	return prompt.render(readPathTemplate, {
+		memory_summary: truncated,
+		generated_memory_skills: generatedMemorySkills,
+	});
+}
+
+async function buildGeneratedMemorySkillIndex(memoryRoot: string): Promise<string> {
+	const skillsDir = path.join(memoryRoot, "skills");
+	const dirents = await fs.readdir(skillsDir, { withFileTypes: true }).catch(() => []);
+	const names: string[] = [];
+	for (const dirent of dirents) {
+		if (!dirent.isDirectory()) continue;
+		const skillPath = path.join(skillsDir, dirent.name, "SKILL.md");
+		if (await Bun.file(skillPath).exists()) names.push(dirent.name);
+	}
+	names.sort((a, b) => a.localeCompare(b));
+	if (names.length === 0) return "None yet.";
+	const visible = names.slice(0, GENERATED_MEMORY_SKILL_INDEX_LIMIT);
+	const lines = visible.map(name => `- memory://root/skills/${name}/SKILL.md`);
+	const hidden = names.length - visible.length;
+	if (hidden > 0) {
+		lines.push(`- ... ${hidden} more generated memory skill${hidden === 1 ? "" : "s"} not listed`);
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Clear all persisted memory state and generated artifacts.
+ */
+export async function clearMemoryData(agentDir: string, cwd: string): Promise<void> {
+	const db = openMemoryDb(getAgentDbPath(agentDir));
+	try {
+		clearMemoryDataInDb(db);
+	} finally {
+		closeMemoryDb(db);
+	}
+	await fs.rm(getMemoryRoot(agentDir, cwd), { recursive: true, force: true });
+}
+
+/**
+ * Force-enqueue global consolidation maintenance work.
+ */
+export function enqueueMemoryConsolidation(agentDir: string, cwd: string, sourceUpdatedAt = unixNow()): void {
+	const db = openMemoryDb(getAgentDbPath(agentDir));
+	try {
+		enqueueGlobalWatermark(db, sourceUpdatedAt, cwd, { forceDirtyWhenNotAdvanced: true });
+	} finally {
+		closeMemoryDb(db);
+	}
+}
+
+async function runMemoryStartup(options: {
+	session: AgentSession;
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	agentDir: string;
+	config: MemoryRuntimeConfig;
+}): Promise<void> {
+	await runPhase1(options);
+	await runPhase2(options);
+	await options.session.refreshBaseSystemPrompt?.();
+}
+
+function attachPostTurnBackgroundReview(options: {
+	session: AgentSession;
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	agentDir: string;
+	config: MemoryRuntimeConfig;
+}): void {
+	const { session, config } = options;
+	if (config.backgroundReviewMode === "off") return;
+	if (config.backgroundReviewEveryNTurns <= 0) return;
+	if (postTurnReviewStates.has(session)) return;
+	if (typeof session.subscribe !== "function") return;
+
+	const state = { lastReviewedUserTurns: 0, running: false, unsubscribe: () => {} };
+	state.unsubscribe = session.subscribe(event => {
+		if (event.type !== "agent_end") return;
+		void maybeRunPostTurnBackgroundReview(options);
+	});
+	postTurnReviewStates.set(session, state);
+}
+
+async function maybeRunPostTurnBackgroundReview(options: {
+	session: AgentSession;
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	agentDir: string;
+	config: MemoryRuntimeConfig;
+}): Promise<void> {
+	const { session, modelRegistry, agentDir, config } = options;
+	const state = postTurnReviewStates.get(session);
+	if (!state || state.running) return;
+
+	const messages = extractPostTurnReviewMessages(session);
+	const userTurns = messages.filter(message => message.role === "user").length;
+	if (userTurns <= 0) return;
+	if (userTurns - state.lastReviewedUserTurns < config.backgroundReviewEveryNTurns) return;
+
+	state.running = true;
+	try {
+		const model = await resolveMemoryModel({ modelRegistry, session, fallbackRole: "default" });
+		if (!model) {
+			logger.debug("Post-turn memory review skipped: no model available");
+			return;
+		}
+		const apiKey = await modelRegistry.getApiKey(model, session.sessionId);
+		if (!apiKey) {
+			logger.debug("Post-turn memory review skipped: no API key", {
+				provider: model.provider,
+				model: model.id,
+			});
+			return;
+		}
+
+		const result = await runPostTurnReviewModel({
+			session,
+			messages,
+			userTurns,
+			model,
+			apiKey,
+			modelMaxTokens: computeModelTokenBudget(model, config),
+			config,
+			metadata: session.agent?.metadataForProvider(model.provider),
+		});
+		if (result.kind === "failed") {
+			logger.warn("Post-turn memory review failed", { reason: result.reason });
+			return;
+		}
+		if (result.kind === "no_output") {
+			state.lastReviewedUserTurns = userTurns;
+			return;
+		}
+
+		const sourceUpdatedAt = unixNow();
+		const threadId = buildPostTurnReviewThreadId(session.sessionManager.getSessionId(), userTurns);
+		const db = openMemoryDb(getAgentDbPath(agentDir));
+		try {
+			recordBackgroundStage1Output(db, {
+				threadId,
+				sourceUpdatedAt,
+				rolloutPath: session.sessionManager.getSessionFile() ?? threadId,
+				cwd: session.sessionManager.getCwd(),
+				rawMemory: result.output.rawMemory,
+				rolloutSummary: result.output.rolloutSummary,
+				rolloutSlug: result.output.rolloutSlug,
+				nowSec: sourceUpdatedAt,
+			});
+		} finally {
+			closeMemoryDb(db);
+		}
+		state.lastReviewedUserTurns = userTurns;
+
+		await runPhase2(options);
+		await session.refreshBaseSystemPrompt?.();
+		session.emitNotice("info", "Self-improvement review captured durable memory.", "Memory");
+	} catch (error) {
+		logger.warn("Post-turn memory review failed", { error: String(error) });
+	} finally {
+		state.running = false;
+	}
+}
+
+async function runPhase1(options: {
+	session: AgentSession;
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	agentDir: string;
+	config: MemoryRuntimeConfig;
+}): Promise<void> {
+	const { session, modelRegistry, agentDir, config } = options;
+	const db = openMemoryDb(getAgentDbPath(agentDir));
+	const nowSec = unixNow();
+	const workerId = `memory-${process.pid}`;
+	const memoryRoot = getMemoryRoot(agentDir, session.sessionManager.getCwd());
+	const currentThreadId = session.sessionManager.getSessionId();
+
+	try {
+		const threads = await collectThreads(session, currentThreadId);
+		upsertThreads(db, threads);
+
+		const phase1Model = await resolveMemoryModel({
+			modelRegistry,
+			session,
+			fallbackRole: "default",
+		});
+		if (!phase1Model) {
+			logger.debug("Phase1 skipped: no model available");
+			return;
+		}
+		const phase1ApiKey = await modelRegistry.getApiKey(phase1Model, session.sessionId);
+		if (!phase1ApiKey) {
+			logger.debug("Phase1 skipped: no API key for phase1 model", {
+				provider: phase1Model.provider,
+				model: phase1Model.id,
+			});
+			return;
+		}
+
+		const claims = claimStage1Jobs(db, {
+			nowSec,
+			threadScanLimit: config.threadScanLimit,
+			maxRolloutsPerStartup: config.maxRolloutsPerStartup,
+			maxRolloutAgeDays: config.maxRolloutAgeDays,
+			minRolloutIdleHours: config.minRolloutIdleHours,
+			leaseSeconds: config.stage1LeaseSeconds,
+			runningConcurrencyCap: config.stage1Concurrency,
+			workerId,
+			excludeThreadIds: currentThreadId ? [currentThreadId] : [],
+		});
+		if (claims.length === 0) return;
+
+		const stats: Stage1Stats = {
+			claimed: claims.length,
+			succeeded: 0,
+			succeededNoOutput: 0,
+			failed: 0,
+			produced: 0,
+			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		};
+
+		await runWithConcurrency(claims, config.stage1Concurrency, async claim => {
+			const result = await runStage1Job({
+				claim,
+				model: phase1Model,
+				apiKey: phase1ApiKey,
+				modelMaxTokens: computeModelTokenBudget(phase1Model, config),
+				config,
+				metadata: session.agent?.metadataForProvider(phase1Model.provider),
+			});
+
+			if (result.kind === "failed") {
+				logger.error("Memory phase1 stage1 job failed", {
+					threadId: claim.threadId,
+					rolloutPath: claim.rolloutPath,
+					reason: result.reason,
+				});
+				markStage1Failed(db, {
+					threadId: claim.threadId,
+					ownershipToken: claim.ownershipToken,
+					retryDelaySeconds: config.stage1RetryDelaySeconds,
+					reason: result.reason,
+					nowSec: unixNow(),
+				});
+				stats.failed += 1;
+				return;
+			}
+
+			if (result.kind === "no_output") {
+				markStage1SucceededNoOutput(db, {
+					threadId: claim.threadId,
+					ownershipToken: claim.ownershipToken,
+					sourceUpdatedAt: claim.sourceUpdatedAt,
+					nowSec: unixNow(),
+					cwd: claim.cwd,
+				});
+				stats.succeededNoOutput += 1;
+				return;
+			}
+
+			markStage1SucceededWithOutput(db, {
+				threadId: claim.threadId,
+				ownershipToken: claim.ownershipToken,
+				sourceUpdatedAt: claim.sourceUpdatedAt,
+				rawMemory: result.output.rawMemory,
+				rolloutSummary: result.output.rolloutSummary,
+				rolloutSlug: result.output.rolloutSlug,
+				nowSec: unixNow(),
+				cwd: claim.cwd,
+			});
+			stats.succeeded += 1;
+			stats.produced += 1;
+			if (result.usage) {
+				stats.usage.input += result.usage.input;
+				stats.usage.output += result.usage.output;
+				stats.usage.cacheRead += result.usage.cacheRead;
+				stats.usage.cacheWrite += result.usage.cacheWrite;
+				stats.usage.total += result.usage.totalTokens || 0;
+			}
+		});
+
+		logger.debug("Memory phase1 completed", {
+			memoryRoot,
+			claimed: stats.claimed,
+			succeeded: stats.succeeded,
+			succeededNoOutput: stats.succeededNoOutput,
+			failed: stats.failed,
+			produced: stats.produced,
+			usage: stats.usage,
+		});
+	} finally {
+		closeMemoryDb(db);
+	}
+}
+
+async function runPhase2(options: {
+	session: AgentSession;
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	agentDir: string;
+	config: MemoryRuntimeConfig;
+}): Promise<void> {
+	const { session, modelRegistry, agentDir, config } = options;
+	const cwd = session.sessionManager.getCwd();
+	const db = openMemoryDb(getAgentDbPath(agentDir));
+	const nowSec = unixNow();
+	const workerId = `memory-${process.pid}`;
+	const memoryRoot = getMemoryRoot(agentDir, cwd);
+
+	try {
+		const claimResult = tryClaimGlobalPhase2Job(db, {
+			workerId,
+			leaseSeconds: config.phase2LeaseSeconds,
+			nowSec,
+			cwd,
+		});
+		if (claimResult.kind !== "claimed") return;
+
+		const claim = claimResult.claim;
+		const outputs = listStage1OutputsForGlobal(db, config.maxRawMemoriesForGlobal, cwd);
+		const newWatermark = computeCompletionWatermark(claim.inputWatermark, outputs);
+
+		await syncPhase2Artifacts(memoryRoot, outputs);
+		if (outputs.length === 0) {
+			await cleanupConsolidatedArtifacts(memoryRoot);
+			const marked = markGlobalPhase2Succeeded(db, {
+				ownershipToken: claim.ownershipToken,
+				newWatermark,
+				nowSec: unixNow(),
+				cwd,
+			});
+			if (!marked) {
+				logger.warn("Phase2 empty-input completion lost ownership", { memoryRoot });
+			}
+			return;
+		}
+
+		const phase2Model = await resolveMemoryModel({
+			modelRegistry,
+			session,
+			fallbackRole: "smol",
+		});
+		if (!phase2Model) {
+			markPhase2FailureWithFallback(db, {
+				claim,
+				retryDelaySeconds: config.phase2RetryDelaySeconds,
+				reason: "No model available for phase2",
+				memoryRoot,
+				cwd,
+			});
+			return;
+		}
+		const phase2ApiKey = await modelRegistry.getApiKey(phase2Model, session.sessionId);
+		if (!phase2ApiKey) {
+			markPhase2FailureWithFallback(db, {
+				claim,
+				retryDelaySeconds: config.phase2RetryDelaySeconds,
+				reason: "No API key available for phase2",
+				memoryRoot,
+				cwd,
+			});
+			return;
+		}
+
+		let heartbeatLostOwnership = false;
+		const heartbeat = setInterval(() => {
+			const ok = heartbeatGlobalJob(db, {
+				ownershipToken: claim.ownershipToken,
+				leaseSeconds: config.phase2LeaseSeconds,
+				nowSec: unixNow(),
+				cwd,
+			});
+			if (!ok) {
+				heartbeatLostOwnership = true;
+				clearInterval(heartbeat);
+			}
+		}, config.phase2HeartbeatSeconds * 1000);
+
+		try {
+			const consolidated = await runConsolidationModel({
+				memoryRoot,
+				model: phase2Model,
+				apiKey: phase2ApiKey,
+				metadata: session.agent?.metadataForProvider(phase2Model.provider),
+			});
+			const identityReview = await runIdentityReviewModel({
+				cwd,
+				memoryRoot,
+				model: phase2Model,
+				apiKey: phase2ApiKey,
+				metadata: session.agent?.metadataForProvider(phase2Model.provider),
+				consolidated,
+				enabled: config.identityReviewMode === "propose",
+			});
+			await applyConsolidation(memoryRoot, consolidated, {
+				identityReview,
+				curatorMode: config.curatorMode,
+				generatedSkillStaleAfterDays: config.generatedSkillStaleAfterDays,
+				generatedSkillArchiveAfterDays: config.generatedSkillArchiveAfterDays,
+			});
+			if (heartbeatLostOwnership) {
+				throw new Error("Phase2 lease ownership lost before completion");
+			}
+			const marked = markGlobalPhase2Succeeded(db, {
+				ownershipToken: claim.ownershipToken,
+				newWatermark,
+				nowSec: unixNow(),
+				cwd,
+			});
+			if (!marked) {
+				throw new Error("Phase2 could not mark success: ownership lost");
+			}
+		} catch (error) {
+			markPhase2FailureWithFallback(db, {
+				claim,
+				retryDelaySeconds: config.phase2RetryDelaySeconds,
+				reason: String(error),
+				memoryRoot,
+				cwd,
+				error,
+			});
+		} finally {
+			clearInterval(heartbeat);
+		}
+	} finally {
+		closeMemoryDb(db);
+	}
+}
+
+function markPhase2FailureWithFallback(
+	db: Database,
+	params: {
+		claim: { ownershipToken: string; inputWatermark: number };
+		retryDelaySeconds: number;
+		reason: string;
+		memoryRoot: string;
+		cwd: string;
+		error?: unknown;
+	},
+): void {
+	const { claim, retryDelaySeconds, reason, memoryRoot, cwd, error } = params;
+	const nowSec = unixNow();
+	const strictFailed = markGlobalPhase2Failed(db, {
+		ownershipToken: claim.ownershipToken,
+		retryDelaySeconds,
+		reason,
+		nowSec,
+		cwd,
+	});
+	if (strictFailed) return;
+
+	const unownedFailed = markGlobalPhase2FailedUnowned(db, {
+		retryDelaySeconds,
+		reason,
+		nowSec,
+		cwd,
+	});
+	if (!unownedFailed) {
+		logger.warn("Phase2 could not mark failure (ownership lost and unowned fallback skipped)", {
+			error: error ? String(error) : undefined,
+			memoryRoot,
+			reason,
+			inputWatermark: claim.inputWatermark,
+		});
+	}
+}
+
+async function collectThreads(session: AgentSession, currentThreadId?: string): Promise<MemoryThread[]> {
+	const sessionDir = session.sessionManager.getSessionDir();
+	const files = await fs.readdir(sessionDir);
+	const threads: MemoryThread[] = [];
+	for (const name of files) {
+		if (!name.endsWith(".jsonl")) continue;
+		const fullPath = path.join(sessionDir, name);
+		let stat: fsNode.Stats;
+		try {
+			stat = await fs.stat(fullPath);
+		} catch {
+			continue;
+		}
+		let cwd = "";
+		let id = name.slice(0, -6);
+		try {
+			const fileText = await Bun.file(fullPath).text();
+			const firstLine = fileText.split("\n", 1)[0] ?? "";
+			const parsed = parseJsonlLenient(firstLine);
+			const header = Array.isArray(parsed) && parsed.length > 0 ? (parsed[0] as Record<string, unknown>) : undefined;
+			if (header && header.type === "session") {
+				if (typeof header.cwd === "string") cwd = header.cwd;
+				if (typeof header.id === "string") id = header.id;
+			}
+		} catch {
+			// ignore malformed session files
+		}
+
+		if (currentThreadId && id === currentThreadId) continue;
+		threads.push({
+			id,
+			updatedAt: Math.floor(stat.mtimeMs / 1000),
+			rolloutPath: fullPath,
+			cwd,
+			sourceKind: "cli",
+		});
+	}
+	return threads;
+}
+
+function shouldPersistResponseItemForMemories(message: AgentMessage): boolean {
+	const role = (message as { role: string }).role;
+	if (role === "system" || role === "developer" || role === "user" || role === "assistant") {
+		return true;
+	}
+	if (role !== "toolResult") return false;
+	const toolName = (message as { toolName?: string }).toolName;
+	if (toolName === "bash" || toolName === "eval" || toolName === "read" || toolName === "search") {
+		const text = extractMessageText(message);
+		return text.length > 0 && text.length <= 32_000;
+	}
+	return false;
+}
+
+function extractPersistableMessages(payload: string): AgentMessage[] {
+	const rows = parseJsonlLenient(payload);
+	if (!Array.isArray(rows)) return [];
+	const messages: AgentMessage[] = [];
+	for (const row of rows) {
+		if (!row || typeof row !== "object") continue;
+		const entry = row as Record<string, unknown>;
+		if (entry.type !== "message") continue;
+		const maybeMessage = entry.message;
+		if (!maybeMessage || typeof maybeMessage !== "object") continue;
+		const message = maybeMessage as AgentMessage;
+		if (shouldPersistResponseItemForMemories(message)) {
+			messages.push(message);
+		}
+	}
+	return messages;
+}
+
+async function runPostTurnReviewModel(options: {
+	session: AgentSession;
+	messages: PostTurnReviewMessage[];
+	userTurns: number;
+	model: Model;
+	apiKey: string;
+	modelMaxTokens: number;
+	config: MemoryRuntimeConfig;
+	metadata?: Record<string, unknown>;
+}): Promise<
+	| {
+			kind: "output";
+			output: { rawMemory: string; rolloutSummary: string; rolloutSlug: string | null };
+	  }
+	| { kind: "no_output" }
+	| { kind: "failed"; reason: string }
+> {
+	const { session, messages, userTurns, model, apiKey, modelMaxTokens, config } = options;
+	try {
+		const budgetTokens = Math.min(
+			config.phase1InputTokenLimit,
+			Math.floor(modelMaxTokens * config.rolloutPayloadPercent),
+		);
+		const input = prompt.render(postTurnReviewTemplate, {
+			thread_id: session.sessionManager.getSessionId() ?? "unknown",
+			cwd: session.sessionManager.getCwd(),
+			user_turns: String(userTurns),
+			review_every_n_turns: String(config.backgroundReviewEveryNTurns),
+			conversation_json: truncateByApproxTokens(JSON.stringify(messages), budgetTokens),
+		});
+		const response = await completeSimple(
+			model,
+			{
+				messages: [{ role: "user", content: [{ type: "text", text: input }], timestamp: Date.now() }],
+			},
+			{
+				apiKey,
+				metadata: options.metadata,
+				maxTokens: Math.max(1024, Math.min(4096, Math.floor(modelMaxTokens * 0.2))),
+				reasoning: clampThinkingLevelForModel(model, Effort.Low),
+			},
+		);
+
+		if (response.stopReason === "error") {
+			return { kind: "failed", reason: response.errorMessage || "post-turn review model error" };
+		}
+		const text = response.content
+			.filter((c): c is { type: "text"; text: string } => c.type === "text")
+			.map(c => c.text)
+			.join("\n")
+			.trim();
+		const parsed = parseJsonObject(text);
+		if (!parsed) {
+			return { kind: "failed", reason: "post-turn review JSON parse failure" };
+		}
+		const schemaOutput = parseStage1OutputSchema(parsed);
+		if (!schemaOutput) {
+			return { kind: "failed", reason: "post-turn review JSON schema validation failure" };
+		}
+
+		const rawMemory = redactSecrets(schemaOutput.raw_memory).trim();
+		const rolloutSummary = redactSecrets(schemaOutput.rollout_summary).trim();
+		const rolloutSlug = schemaOutput.rollout_slug === null ? null : redactSecrets(schemaOutput.rollout_slug).trim();
+		if (!rawMemory || !rolloutSummary) return { kind: "no_output" };
+		return {
+			kind: "output",
+			output: {
+				rawMemory,
+				rolloutSummary,
+				rolloutSlug: rolloutSlug || null,
+			},
+		};
+	} catch (error) {
+		return { kind: "failed", reason: String(error) };
+	}
+}
+
+async function runStage1Job(options: {
+	claim: Stage1Claim;
+	model: Model;
+	apiKey: string;
+	modelMaxTokens: number;
+	config: MemoryRuntimeConfig;
+	metadata?: Record<string, unknown>;
+}): Promise<
+	| {
+			kind: "output";
+			output: { rawMemory: string; rolloutSummary: string; rolloutSlug: string | null };
+			usage?: { input: number; output: number; cacheRead: number; cacheWrite: number; totalTokens?: number };
+	  }
+	| { kind: "no_output" }
+	| { kind: "failed"; reason: string }
+> {
+	const { claim, model, apiKey, modelMaxTokens, config } = options;
+	try {
+		const rolloutRaw = await Bun.file(claim.rolloutPath).text();
+		const persisted = extractPersistableMessages(rolloutRaw);
+		const serializedItems = JSON.stringify(persisted);
+		const budgetTokens = Math.min(
+			config.phase1InputTokenLimit,
+			Math.floor(modelMaxTokens * config.rolloutPayloadPercent),
+		);
+		const truncatedItems = truncateByApproxTokens(serializedItems, budgetTokens);
+		const inputPrompt = prompt.render(stageOneInputTemplate, {
+			thread_id: claim.threadId,
+			response_items_json: truncatedItems,
+		});
+
+		const response = await completeSimple(
+			model,
+			{
+				systemPrompt: [stageOneSystemTemplate],
+				messages: [{ role: "user", content: [{ type: "text", text: inputPrompt }], timestamp: Date.now() }],
+			},
+			{
+				apiKey,
+				metadata: options.metadata,
+				maxTokens: Math.max(1024, Math.min(4096, Math.floor(modelMaxTokens * 0.2))),
+				reasoning: clampThinkingLevelForModel(model, Effort.Low),
+			},
+		);
+
+		if (response.stopReason === "error") {
+			return { kind: "failed", reason: response.errorMessage || "stage1 model error" };
+		}
+		const text = response.content
+			.filter((c): c is { type: "text"; text: string } => c.type === "text")
+			.map(c => c.text)
+			.join("\n")
+			.trim();
+		const parsed = parseJsonObject(text);
+		if (!parsed) {
+			return { kind: "failed", reason: "stage1 JSON parse failure" };
+		}
+		const schemaOutput = parseStage1OutputSchema(parsed);
+		if (!schemaOutput) {
+			return { kind: "failed", reason: "stage1 JSON schema validation failure" };
+		}
+
+		const rawMemory = redactSecrets(schemaOutput.raw_memory).trim();
+		const rolloutSummary = redactSecrets(schemaOutput.rollout_summary).trim();
+		const rolloutSlug = schemaOutput.rollout_slug === null ? null : redactSecrets(schemaOutput.rollout_slug).trim();
+		if (!rawMemory || !rolloutSummary) {
+			return { kind: "no_output" };
+		}
+		return {
+			kind: "output",
+			output: {
+				rawMemory,
+				rolloutSummary,
+				rolloutSlug: rolloutSlug || null,
+			},
+			usage: response.usage,
+		};
+	} catch (error) {
+		return { kind: "failed", reason: String(error) };
+	}
+}
+
+async function syncPhase2Artifacts(memoryRoot: string, outputs: Stage1OutputRow[]): Promise<void> {
+	const summariesDir = path.join(memoryRoot, "rollout_summaries");
+	await fs.mkdir(summariesDir, { recursive: true });
+
+	const keepFiles = new Set<string>();
+	for (const row of outputs) {
+		const stem = formatRolloutFilename(row.threadId, row.rolloutSlug);
+		const filename = `${stem}.md`;
+		keepFiles.add(filename);
+		const body = [`thread_id: ${row.threadId}`, `updated_at: ${row.sourceUpdatedAt}`, "", row.rolloutSummary].join(
+			"\n",
+		);
+		await Bun.write(path.join(summariesDir, filename), `${body.trim()}\n`);
+	}
+
+	const currentFiles = await fs.readdir(summariesDir).catch(() => [] as string[]);
+	for (const file of currentFiles) {
+		if (!file.endsWith(".md")) continue;
+		if (keepFiles.has(file)) continue;
+		await fs.rm(path.join(summariesDir, file), { force: true });
+	}
+
+	const rawBody = buildRawMemoriesMarkdown(outputs);
+	await Bun.write(path.join(memoryRoot, "raw_memories.md"), rawBody);
+}
+
+async function cleanupConsolidatedArtifacts(memoryRoot: string): Promise<void> {
+	await fs.rm(path.join(memoryRoot, MEMORY_ARTIFACTS.memory), { force: true });
+	await fs.rm(path.join(memoryRoot, MEMORY_ARTIFACTS.user), { force: true });
+	await fs.rm(path.join(memoryRoot, MEMORY_ARTIFACTS.summary), { force: true });
+	await fs.rm(path.join(memoryRoot, MEMORY_ARTIFACTS.selfImprovementReport), { force: true });
+	await fs.rm(path.join(memoryRoot, MEMORY_ARTIFACTS.skillUsage), { force: true });
+	await fs.rm(path.join(memoryRoot, MEMORY_ARTIFACTS.skillCuratorReport), { force: true });
+	await fs.rm(path.join(memoryRoot, "skills"), { recursive: true, force: true });
+}
+
+function buildRawMemoriesMarkdown(outputs: Stage1OutputRow[]): string {
+	if (outputs.length === 0) {
+		return "# Raw Memories\n\nNo raw memories yet.\n";
+	}
+
+	const blocks = outputs.map(row => {
+		const header = [`## ${row.threadId}`, `updated_at: ${row.sourceUpdatedAt}`, ""].join("\n");
+		return `${header}${row.rawMemory.trim()}\n`;
+	});
+	return `# Raw Memories\n\n${blocks.join("\n")}`;
+}
+
+async function readRolloutSummaries(memoryRoot: string): Promise<string> {
+	const summariesDir = path.join(memoryRoot, "rollout_summaries");
+	const names = await fs.readdir(summariesDir).catch(() => [] as string[]);
+	const summaryNames = names.filter(name => name.endsWith(".md")).sort((a, b) => a.localeCompare(b));
+	if (summaryNames.length === 0) return "No rollout summaries yet.";
+
+	const blocks: string[] = [];
+	for (const name of summaryNames) {
+		const text = await Bun.file(path.join(summariesDir, name))
+			.text()
+			.catch(() => "");
+		if (!text.trim()) continue;
+		blocks.push(`--- ${name} ---\n${text.trim()}`);
+	}
+	if (blocks.length === 0) return "No rollout summaries yet.";
+	return blocks.join("\n\n");
+}
+
+async function runConsolidationModel(options: {
+	memoryRoot: string;
+	model: Model;
+	apiKey: string;
+	metadata?: Record<string, unknown>;
+}): Promise<{
+	memoryMd: string;
+	userMd: string;
+	memorySummary: string;
+	skills: Array<{
+		name: string;
+		content: string;
+		scripts: ConsolidationSkillFileSchema[];
+		templates: ConsolidationSkillFileSchema[];
+		examples: ConsolidationSkillFileSchema[];
+	}>;
+}> {
+	const { memoryRoot, model, apiKey } = options;
+	const rawMemories = await Bun.file(path.join(memoryRoot, "raw_memories.md")).text();
+	const rolloutSummaries = await readRolloutSummaries(memoryRoot);
+	const input = prompt.render(consolidationTemplate, {
+		raw_memories: truncateByApproxTokens(rawMemories, 20_000),
+		rollout_summaries: truncateByApproxTokens(rolloutSummaries, 12_000),
+	});
+
+	const response = await completeSimple(
+		model,
+		{
+			messages: [{ role: "user", content: [{ type: "text", text: input }], timestamp: Date.now() }],
+		},
+		{
+			apiKey,
+			metadata: options.metadata,
+			maxTokens: 8192,
+			reasoning: clampThinkingLevelForModel(model, Effort.Medium),
+		},
+	);
+	if (response.stopReason === "error") {
+		throw new Error(response.errorMessage || "phase2 model error");
+	}
+	const text = response.content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map(c => c.text)
+		.join("\n")
+		.trim();
+	const parsed = parseJsonObject(text);
+	if (!parsed) throw new Error("phase2 JSON parse failure");
+	const schemaOutput = parseConsolidationOutputSchema(parsed);
+	if (!schemaOutput) throw new Error("phase2 JSON schema validation failure");
+	assertNoIdentityArtifactLeak([
+		{ field: "memory_md", value: schemaOutput.memory_md },
+		{ field: "user_md", value: schemaOutput.user_md },
+		{ field: "memory_summary", value: schemaOutput.memory_summary },
+		...schemaOutput.skills.flatMap((skill, index) => [
+			{ field: `skills[${index}].name`, value: skill.name },
+			{ field: `skills[${index}].content`, value: skill.content ?? "" },
+			...(skill.scripts ?? []).map(file => ({
+				field: `skills[${index}].scripts.${file.path}`,
+				value: `${file.path}\n${file.content}`,
+			})),
+			...(skill.templates ?? []).map(file => ({
+				field: `skills[${index}].templates.${file.path}`,
+				value: `${file.path}\n${file.content}`,
+			})),
+			...(skill.examples ?? []).map(file => ({
+				field: `skills[${index}].examples.${file.path}`,
+				value: `${file.path}\n${file.content}`,
+			})),
+		]),
+	]);
+	const memoryMd = redactSecrets(schemaOutput.memory_md).trim();
+	const userMd = normalizeConsolidatedUserProfile(redactSecrets(schemaOutput.user_md));
+	const memorySummary = redactSecrets(schemaOutput.memory_summary).trim();
+	const skills = schemaOutput.skills
+		.map(item => {
+			const name = sanitizeSkillName(item.name.trim());
+			const content = redactSecrets(item.content ?? "").trim();
+			if (!name || !content) return null;
+			return {
+				name,
+				content,
+				scripts: sanitizeConsolidationSkillFiles(item.scripts, "scripts"),
+				templates: sanitizeConsolidationSkillFiles(item.templates, "templates"),
+				examples: sanitizeConsolidationSkillFiles(item.examples, "examples"),
+			};
+		})
+		.filter(
+			(
+				item,
+			): item is {
+				name: string;
+				content: string;
+				scripts: ConsolidationSkillFileSchema[];
+				templates: ConsolidationSkillFileSchema[];
+				examples: ConsolidationSkillFileSchema[];
+			} => item !== null,
+		);
+	assertNoIdentityArtifactLeak([
+		{ field: "memory_md", value: memoryMd },
+		{ field: "user_md", value: userMd },
+		{ field: "memory_summary", value: memorySummary },
+		...skills.flatMap(skill => [
+			{ field: `skills.${skill.name}.name`, value: skill.name },
+			{ field: `skills.${skill.name}.content`, value: skill.content },
+			...skill.scripts.map(file => ({
+				field: `skills.${skill.name}.scripts.${file.path}`,
+				value: `${file.path}\n${file.content}`,
+			})),
+			...skill.templates.map(file => ({
+				field: `skills.${skill.name}.templates.${file.path}`,
+				value: `${file.path}\n${file.content}`,
+			})),
+			...skill.examples.map(file => ({
+				field: `skills.${skill.name}.examples.${file.path}`,
+				value: `${file.path}\n${file.content}`,
+			})),
+		]),
+	]);
+	if (!memoryMd || !memorySummary) {
+		throw new Error("phase2 returned empty consolidated memory");
+	}
+	return { memoryMd, userMd, memorySummary, skills };
+}
+
+async function runIdentityReviewModel(options: {
+	cwd: string;
+	memoryRoot: string;
+	model: Model;
+	apiKey: string;
+	metadata?: Record<string, unknown>;
+	enabled: boolean;
+	consolidated: {
+		userMd: string;
+		memorySummary: string;
+		skills: Array<{ name: string }>;
+	};
+}): Promise<IdentityReviewResult> {
+	const nativeSoul = await readNativeSoulContext(options.cwd);
+	if (!options.enabled) {
+		return { soulProposal: "", nativeSoulPath: nativeSoul.path };
+	}
+
+	try {
+		const input = prompt.render(identityReviewTemplate, {
+			native_soul_path: nativeSoul.path ?? "No native SOUL.md found.",
+			native_soul: truncateByApproxTokens(nativeSoul.content || "No native SOUL.md found.", 8_000),
+			user_md: truncateByApproxTokens(options.consolidated.userMd || "No durable USER.md profile.", 4_000),
+			memory_summary: truncateByApproxTokens(options.consolidated.memorySummary, 4_000),
+			generated_skills:
+				options.consolidated.skills.length === 0
+					? "None."
+					: options.consolidated.skills
+							.map(skill => `- memory://root/skills/${skill.name}/SKILL.md`)
+							.sort((a, b) => a.localeCompare(b))
+							.join("\n"),
+		});
+
+		const response = await completeSimple(
+			options.model,
+			{
+				messages: [{ role: "user", content: [{ type: "text", text: input }], timestamp: Date.now() }],
+			},
+			{
+				apiKey: options.apiKey,
+				metadata: options.metadata,
+				maxTokens: 4096,
+				reasoning: clampThinkingLevelForModel(options.model, Effort.Low),
+			},
+		);
+		if (response.stopReason === "error") {
+			return {
+				soulProposal: "",
+				nativeSoulPath: nativeSoul.path,
+				error: response.errorMessage || "identity review model error",
+			};
+		}
+		const text = response.content
+			.filter((c): c is { type: "text"; text: string } => c.type === "text")
+			.map(c => c.text)
+			.join("\n")
+			.trim();
+		const parsed = parseJsonObject(text);
+		if (!parsed) {
+			return { soulProposal: "", nativeSoulPath: nativeSoul.path, error: "identity review JSON parse failure" };
+		}
+		const proposal = parseIdentityReviewOutputSchema(parsed);
+		if (proposal === undefined) {
+			return { soulProposal: "", nativeSoulPath: nativeSoul.path, error: "identity review JSON schema failure" };
+		}
+		return { soulProposal: proposal, nativeSoulPath: nativeSoul.path };
+	} catch (error) {
+		return { soulProposal: "", nativeSoulPath: nativeSoul.path, error: String(error) };
+	}
+}
+
+async function readNativeSoulContext(cwd: string): Promise<{ path: string | null; content: string }> {
+	const projectConfigDir = await walkUp(cwd, SOURCE_PATHS.native.projectDir, { file: false, dir: true });
+	if (!projectConfigDir) return { path: null, content: "" };
+	const soulPath = path.join(projectConfigDir, "SOUL.md");
+	const content = await readFile(soulPath);
+	return { path: soulPath, content: content ?? "" };
+}
+
+async function applyConsolidation(
+	memoryRoot: string,
+	consolidated: {
+		memoryMd: string;
+		userMd: string;
+		memorySummary: string;
+		skills: Array<{
+			name: string;
+			content: string;
+			scripts: ConsolidationSkillFileSchema[];
+			templates: ConsolidationSkillFileSchema[];
+			examples: ConsolidationSkillFileSchema[];
+		}>;
+	},
+	options: {
+		identityReview: IdentityReviewResult;
+		curatorMode: "dry-run" | "off";
+		generatedSkillStaleAfterDays: number;
+		generatedSkillArchiveAfterDays: number;
+	},
+): Promise<void> {
+	await Bun.write(path.join(memoryRoot, MEMORY_ARTIFACTS.memory), `${consolidated.memoryMd.trim()}\n`);
+	await Bun.write(path.join(memoryRoot, MEMORY_ARTIFACTS.user), `${consolidated.userMd.trim()}\n`);
+	await Bun.write(path.join(memoryRoot, MEMORY_ARTIFACTS.summary), `${consolidated.memorySummary.trim()}\n`);
+	const curation = await applyGeneratedMemorySkills(memoryRoot, consolidated.skills, {
+		curatorMode: options.curatorMode,
+		staleAfterDays: options.generatedSkillStaleAfterDays,
+		archiveAfterDays: options.generatedSkillArchiveAfterDays,
+	});
+
+	if (options.identityReview.soulProposal.trim()) {
+		await Bun.write(
+			path.join(memoryRoot, MEMORY_ARTIFACTS.soulProposal),
+			`${options.identityReview.soulProposal.trim()}\n`,
+		);
+	}
+
+	await Bun.write(
+		path.join(memoryRoot, MEMORY_ARTIFACTS.selfImprovementReport),
+		buildSelfImprovementReport(consolidated, {
+			identityReview: options.identityReview,
+			curation,
+		}),
+	);
+}
+
+function buildSelfImprovementReport(
+	consolidated: {
+		memoryMd: string;
+		userMd: string;
+		memorySummary: string;
+		skills: Array<{ name: string }>;
+	},
+	options: {
+		identityReview: IdentityReviewResult;
+		curation: SkillCurationResult;
+	},
+): string {
+	const skillNames = consolidated.skills.map(skill => skill.name).sort((a, b) => a.localeCompare(b));
+	const generatedSkills = skillNames.length === 0 ? "- None" : skillNames.map(name => `- ${name}`).join("\n");
+	const userProfileState = consolidated.userMd.trim() ? "updated" : "empty";
+	const identityLines = options.identityReview.soulProposal.trim()
+		? [
+				"- SOUL proposal: written to memory://root/SOUL.proposed.md",
+				`- Native SOUL source: ${options.identityReview.nativeSoulPath ?? "none"}`,
+			]
+		: ["- SOUL proposal: none written", `- Native SOUL source: ${options.identityReview.nativeSoulPath ?? "none"}`];
+	if (options.identityReview.error) {
+		identityLines.push(`- Identity review warning: ${options.identityReview.error}`);
+	}
+	const curatorLines = options.curation.report.trim()
+		? [`- Skill curator dry-run report: memory://root/${MEMORY_ARTIFACTS.skillCuratorReport}`]
+		: ["- Skill curator: off"];
+
+	return [
+		"# Self-Improvement Report",
+		"",
+		"Trajectory: Hermes-style native Prometheus learning.",
+		"",
+		"Automatic write scope:",
+		"- MEMORY.md: project and operational memory",
+		"- USER.md: durable user profile",
+		"- skills/: generated procedural playbooks",
+		"",
+		"Stable identity boundary:",
+		"- SOUL.md is not generated or rewritten by memory consolidation.",
+		"- SOUL.proposed.md is reserved for an explicit identity-review flow.",
+		"- Do not present memory artifacts as Prometheus identity.",
+		"",
+		"Dry-run review:",
+		"- Memory/profile/skill consolidation completed through the native Prometheus memory pipeline.",
+		...identityLines,
+		...curatorLines,
+		"",
+		"Current artifacts:",
+		`- MEMORY.md chars: ${consolidated.memoryMd.trim().length}`,
+		`- USER.md state: ${userProfileState}`,
+		`- memory_summary.md chars: ${consolidated.memorySummary.trim().length}`,
+		`- skill_usage.json records: ${Object.keys(options.curation.usage.skills).length}`,
+		"",
+		"Generated skills:",
+		generatedSkills,
+		"",
+		"Skill lifecycle:",
+		`- Active generated skills: ${options.curation.active.length}`,
+		`- Pinned stale skills preserved: ${options.curation.pinnedStale.length}`,
+		`- Archived stale skills: ${options.curation.archived.length}`,
+		`- Dry-run stale candidates: ${options.curation.staleCandidates.length}`,
+		`- Dry-run archive candidates: ${options.curation.archiveCandidates.length}`,
+		"",
+	].join("\n");
+}
+
+async function applyGeneratedMemorySkills(
+	memoryRoot: string,
+	skills: Array<{
+		name: string;
+		content: string;
+		scripts: ConsolidationSkillFileSchema[];
+		templates: ConsolidationSkillFileSchema[];
+		examples: ConsolidationSkillFileSchema[];
+	}>,
+	options: {
+		curatorMode: "dry-run" | "off";
+		staleAfterDays: number;
+		archiveAfterDays: number;
+	},
+): Promise<SkillCurationResult> {
+	const skillsDir = path.join(memoryRoot, "skills");
+	await fs.mkdir(skillsDir, { recursive: true });
+	const usage = await readGeneratedMemorySkillUsage(memoryRoot);
+	const now = new Date().toISOString();
+	const keep = new Set<string>();
+	const active: string[] = [];
+	const pinnedStale: string[] = [];
+	const archived: string[] = [];
+	const staleCandidates: string[] = [];
+	const archiveCandidates: string[] = [];
+	const markedStale: string[] = [];
+	const reactivated: string[] = [];
+
+	for (const skill of skills) {
+		const dir = path.join(skillsDir, skill.name);
+		const files = buildSkillFileMap(skill);
+		const existed = await Bun.file(path.join(dir, "SKILL.md")).exists();
+		const changed = await skillFilesChanged(dir, files);
+		keep.add(skill.name);
+		active.push(skill.name);
+
+		await fs.mkdir(dir, { recursive: true });
+		for (const [relativePath, content] of [...files.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+			const filePath = path.join(dir, ...relativePath.split("/"));
+			await fs.mkdir(path.dirname(filePath), { recursive: true });
+			await Bun.write(filePath, content);
+		}
+
+		const keepFiles = new Set(files.keys());
+		const existingFiles = await listRelativeFiles(dir);
+		for (const relativePath of existingFiles) {
+			if (keepFiles.has(relativePath)) continue;
+			await fs.rm(path.join(dir, ...relativePath.split("/")), { force: true });
+		}
+		await pruneEmptyDirectories(dir);
+		await fs.rm(path.join(skillsDir, ".archive", skill.name), { recursive: true, force: true });
+
+		const record = normalizeGeneratedMemorySkillRecord(usage.skills[skill.name], skill.name, now);
+		record.state = "active";
+		record.updatedAt = now;
+		record.lastSeenInConsolidationAt = now;
+		record.archivedAt = null;
+		record.archiveReason = null;
+		if (existed && changed) {
+			record.patchCount += 1;
+			record.lastPatchedAt = now;
+		}
+		usage.skills[skill.name] = record;
+	}
+
+	const dirs = await fs.readdir(skillsDir, { withFileTypes: true }).catch(() => []);
+	for (const dirent of dirs) {
+		if (!dirent.isDirectory()) continue;
+		if (dirent.name === ".archive") continue;
+		if (keep.has(dirent.name)) continue;
+
+		const record = normalizeGeneratedMemorySkillRecord(usage.skills[dirent.name], dirent.name, now);
+		record.updatedAt = now;
+		if (record.pinned) {
+			record.state = "stale";
+			pinnedStale.push(dirent.name);
+			usage.skills[dirent.name] = record;
+			continue;
+		}
+
+		await archiveGeneratedMemorySkillDir(skillsDir, dirent.name);
+		record.state = "archived";
+		record.archivedAt = record.archivedAt ?? now;
+		record.archiveReason = record.archiveReason ?? "Omitted by memory consolidation; archived instead of deleted.";
+		archived.push(dirent.name);
+		usage.skills[dirent.name] = record;
+	}
+
+	if (options.curatorMode === "dry-run") {
+		applyGeneratedSkillDryRunClassification(usage, {
+			now,
+			staleAfterDays: options.staleAfterDays,
+			archiveAfterDays: options.archiveAfterDays,
+			staleCandidates,
+			archiveCandidates,
+			markedStale,
+			reactivated,
+		});
+	}
+
+	const sortedUsage = sortGeneratedMemorySkillUsage(usage);
+	await writeGeneratedMemorySkillUsage(memoryRoot, sortedUsage);
+	const report =
+		options.curatorMode === "dry-run"
+			? buildSkillCuratorReport(sortedUsage, {
+					active,
+					pinnedStale,
+					archived,
+					staleCandidates,
+					archiveCandidates,
+					markedStale,
+					reactivated,
+					curatorMode: options.curatorMode,
+					staleAfterDays: options.staleAfterDays,
+					archiveAfterDays: options.archiveAfterDays,
+				})
+			: "";
+	if (report.trim()) {
+		await Bun.write(path.join(memoryRoot, MEMORY_ARTIFACTS.skillCuratorReport), report);
+	} else {
+		await fs.rm(path.join(memoryRoot, MEMORY_ARTIFACTS.skillCuratorReport), { force: true });
+	}
+	return {
+		usage: sortedUsage,
+		active: active.sort((a, b) => a.localeCompare(b)),
+		pinnedStale: pinnedStale.sort((a, b) => a.localeCompare(b)),
+		archived: archived.sort((a, b) => a.localeCompare(b)),
+		staleCandidates: staleCandidates.sort((a, b) => a.localeCompare(b)),
+		archiveCandidates: archiveCandidates.sort((a, b) => a.localeCompare(b)),
+		markedStale: markedStale.sort((a, b) => a.localeCompare(b)),
+		reactivated: reactivated.sort((a, b) => a.localeCompare(b)),
+		report,
+	};
+}
+
+function buildSkillFileMap(skill: {
+	content: string;
+	scripts: ConsolidationSkillFileSchema[];
+	templates: ConsolidationSkillFileSchema[];
+	examples: ConsolidationSkillFileSchema[];
+}): Map<string, string> {
+	const files = new Map<string, string>();
+	files.set("SKILL.md", `${skill.content.trim()}\n`);
+	for (const item of skill.scripts) {
+		files.set(path.posix.join("scripts", item.path), `${item.content.trim()}\n`);
+	}
+	for (const item of skill.templates) {
+		files.set(path.posix.join("templates", item.path), `${item.content.trim()}\n`);
+	}
+	for (const item of skill.examples) {
+		files.set(path.posix.join("examples", item.path), `${item.content.trim()}\n`);
+	}
+	return files;
+}
+
+async function skillFilesChanged(dir: string, desired: Map<string, string>): Promise<boolean> {
+	const existing = await listRelativeFiles(dir);
+	if (existing.length !== desired.size) return true;
+	for (const relativePath of existing) {
+		const wanted = desired.get(relativePath);
+		if (wanted === undefined) return true;
+		const current = await Bun.file(path.join(dir, ...relativePath.split("/")))
+			.text()
+			.catch(() => undefined);
+		if (current !== wanted) return true;
+	}
+	return false;
+}
+
+async function readGeneratedMemorySkillUsage(memoryRoot: string): Promise<GeneratedMemorySkillUsageFile> {
+	const fallback: GeneratedMemorySkillUsageFile = { schemaVersion: 1, skills: {} };
+	const text = await Bun.file(path.join(memoryRoot, MEMORY_ARTIFACTS.skillUsage))
+		.text()
+		.catch(() => "");
+	if (!text.trim()) return fallback;
+	try {
+		const parsed = JSON.parse(text) as unknown;
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return fallback;
+		const data = parsed as Record<string, unknown>;
+		if (data.schemaVersion !== 1 || !data.skills || typeof data.skills !== "object" || Array.isArray(data.skills)) {
+			return fallback;
+		}
+		const skills: Record<string, GeneratedMemorySkillUsageRecord> = {};
+		const now = new Date().toISOString();
+		for (const [name, record] of Object.entries(data.skills as Record<string, unknown>)) {
+			const sanitized = sanitizeSkillName(name);
+			if (!sanitized) continue;
+			skills[sanitized] = normalizeGeneratedMemorySkillRecord(record, sanitized, now);
+		}
+		return { schemaVersion: 1, skills };
+	} catch {
+		return fallback;
+	}
+}
+
+async function writeGeneratedMemorySkillUsage(memoryRoot: string, usage: GeneratedMemorySkillUsageFile): Promise<void> {
+	await Bun.write(
+		path.join(memoryRoot, MEMORY_ARTIFACTS.skillUsage),
+		`${JSON.stringify(sortGeneratedMemorySkillUsage(usage), null, 2)}\n`,
+	);
+}
+
+function sortGeneratedMemorySkillUsage(usage: GeneratedMemorySkillUsageFile): GeneratedMemorySkillUsageFile {
+	const sorted: Record<string, GeneratedMemorySkillUsageRecord> = {};
+	for (const name of Object.keys(usage.skills).sort((a, b) => a.localeCompare(b))) {
+		sorted[name] = usage.skills[name]!;
+	}
+	return { schemaVersion: 1, skills: sorted };
+}
+
+function normalizeGeneratedMemorySkillRecord(
+	value: unknown,
+	name: string,
+	now: string,
+): GeneratedMemorySkillUsageRecord {
+	const input = value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+	const state = parseGeneratedMemorySkillState(input.state) ?? "active";
+	return {
+		schemaVersion: 1,
+		name,
+		source: "memory-consolidation",
+		state,
+		pinned: input.pinned === true,
+		createdAt: parseString(input.createdAt) ?? now,
+		updatedAt: parseString(input.updatedAt) ?? now,
+		lastSeenInConsolidationAt: parseString(input.lastSeenInConsolidationAt),
+		archivedAt: parseString(input.archivedAt),
+		archiveReason: parseString(input.archiveReason),
+		useCount: parseNonNegativeInteger(input.useCount),
+		viewCount: parseNonNegativeInteger(input.viewCount),
+		patchCount: parseNonNegativeInteger(input.patchCount),
+		lastUsedAt: parseString(input.lastUsedAt),
+		lastViewedAt: parseString(input.lastViewedAt),
+		lastPatchedAt: parseString(input.lastPatchedAt),
+	};
+}
+
+function parseGeneratedMemorySkillState(value: unknown): GeneratedMemorySkillState | undefined {
+	return value === "active" || value === "stale" || value === "archived" ? value : undefined;
+}
+
+function parseString(value: unknown): string | null {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed || null;
+}
+
+function parseNonNegativeInteger(value: unknown): number {
+	const parsed = typeof value === "number" ? value : Number(value);
+	if (!Number.isFinite(parsed) || parsed < 0) return 0;
+	return Math.floor(parsed);
+}
+
+function applyGeneratedSkillDryRunClassification(
+	usage: GeneratedMemorySkillUsageFile,
+	options: {
+		now: string;
+		staleAfterDays: number;
+		archiveAfterDays: number;
+		staleCandidates: string[];
+		archiveCandidates: string[];
+		markedStale: string[];
+		reactivated: string[];
+	},
+): void {
+	const nowMs = Date.parse(options.now);
+	const staleCutoff = nowMs - options.staleAfterDays * 24 * 60 * 60 * 1000;
+	const archiveCutoff = nowMs - options.archiveAfterDays * 24 * 60 * 60 * 1000;
+	for (const record of Object.values(usage.skills)) {
+		if (record.state === "archived" || record.pinned) continue;
+		const anchor = Date.parse(latestGeneratedMemorySkillActivity(record) ?? record.createdAt);
+		if (!Number.isFinite(anchor)) continue;
+		if (anchor <= archiveCutoff) {
+			options.archiveCandidates.push(record.name);
+			if (record.state === "active") {
+				options.markedStale.push(record.name);
+			}
+			continue;
+		}
+		if (anchor <= staleCutoff) {
+			options.staleCandidates.push(record.name);
+			if (record.state === "active") {
+				options.markedStale.push(record.name);
+			}
+			continue;
+		}
+		if (record.state === "stale") {
+			options.reactivated.push(record.name);
+		}
+	}
+}
+
+function latestGeneratedMemorySkillActivity(record: GeneratedMemorySkillUsageRecord): string | null {
+	const values = [record.lastUsedAt, record.lastViewedAt, record.lastPatchedAt].filter(
+		(value): value is string => typeof value === "string" && value.length > 0,
+	);
+	values.sort((a, b) => b.localeCompare(a));
+	return values[0] ?? record.lastSeenInConsolidationAt ?? null;
+}
+
+function buildSkillCuratorReport(
+	usage: GeneratedMemorySkillUsageFile,
+	options: {
+		active: string[];
+		pinnedStale: string[];
+		archived: string[];
+		staleCandidates: string[];
+		archiveCandidates: string[];
+		markedStale: string[];
+		reactivated: string[];
+		curatorMode: "dry-run" | "off";
+		staleAfterDays: number;
+		archiveAfterDays: number;
+	},
+): string {
+	const records = Object.values(usage.skills).sort((a, b) => a.name.localeCompare(b.name));
+	const recordLines =
+		records.length === 0
+			? ["- None"]
+			: records.map(
+					record =>
+						`- ${record.name}: state=${record.state}, pinned=${record.pinned ? "yes" : "no"}, ` +
+						`use=${record.useCount}, view=${record.viewCount}, patch=${record.patchCount}`,
+				);
+
+	return [
+		"# Generated Skill Curator Report",
+		"",
+		`Mode: ${options.curatorMode}`,
+		"Scope: generated memory skills only.",
+		"Mutation boundary: dry-run curation reports suggestions; stale skills removed by consolidation are archived, not deleted.",
+		`Stale threshold days: ${options.staleAfterDays}`,
+		`Archive threshold days: ${options.archiveAfterDays}`,
+		"",
+		"Current pass:",
+		`- Active generated skills: ${options.active.length ? options.active.sort((a, b) => a.localeCompare(b)).join(", ") : "none"}`,
+		`- Pinned stale skills preserved: ${
+			options.pinnedStale.length ? options.pinnedStale.sort((a, b) => a.localeCompare(b)).join(", ") : "none"
+		}`,
+		`- Archived stale skills: ${options.archived.length ? options.archived.sort((a, b) => a.localeCompare(b)).join(", ") : "none"}`,
+		"",
+		"Dry-run candidates:",
+		`- Would mark stale: ${options.markedStale.length ? options.markedStale.sort((a, b) => a.localeCompare(b)).join(", ") : "none"}`,
+		`- Would reactivate: ${options.reactivated.length ? options.reactivated.sort((a, b) => a.localeCompare(b)).join(", ") : "none"}`,
+		`- Stale candidates: ${options.staleCandidates.length ? options.staleCandidates.sort((a, b) => a.localeCompare(b)).join(", ") : "none"}`,
+		`- Archive candidates: ${options.archiveCandidates.length ? options.archiveCandidates.sort((a, b) => a.localeCompare(b)).join(", ") : "none"}`,
+		"",
+		"Lifecycle policy:",
+		"- pinned=true prevents automatic archive.",
+		"- state=stale means omitted by latest consolidation while pinned, or inactive past the stale threshold.",
+		"- state=archived means moved to memory://root/skills/.archive/<name>/ for recoverable restore.",
+		"",
+		"Usage records:",
+		...recordLines,
+		"",
+	].join("\n");
+}
+
+async function archiveGeneratedMemorySkillDir(skillsDir: string, name: string): Promise<void> {
+	const source = path.join(skillsDir, name);
+	if (!(await Bun.file(path.join(source, "SKILL.md")).exists())) return;
+	const archiveRoot = path.join(skillsDir, ".archive");
+	const target = path.join(archiveRoot, name);
+	await fs.mkdir(archiveRoot, { recursive: true });
+	await fs.rm(target, { recursive: true, force: true });
+	await fs.rename(source, target);
+}
+
+export async function recordGeneratedMemorySkillEvent(
+	memoryRoot: string,
+	rawName: string,
+	event: GeneratedMemorySkillEvent,
+): Promise<boolean> {
+	const name = sanitizeSkillName(rawName);
+	if (!name) return false;
+	const usage = await readGeneratedMemorySkillUsage(memoryRoot);
+	const now = new Date().toISOString();
+	const record = normalizeGeneratedMemorySkillRecord(usage.skills[name], name, now);
+	const activeSkillPath = path.join(memoryRoot, "skills", name, "SKILL.md");
+	if (!(await Bun.file(activeSkillPath).exists()) && record.state !== "archived") return false;
+	record.updatedAt = now;
+	if (event === "use") {
+		record.useCount += 1;
+		record.lastUsedAt = now;
+	} else if (event === "view") {
+		record.viewCount += 1;
+		record.lastViewedAt = now;
+	} else {
+		record.patchCount += 1;
+		record.lastPatchedAt = now;
+	}
+	usage.skills[name] = record;
+	await writeGeneratedMemorySkillUsage(memoryRoot, usage);
+	return true;
+}
+
+export async function pinGeneratedMemorySkill(memoryRoot: string, rawName: string, pinned = true): Promise<boolean> {
+	const name = sanitizeSkillName(rawName);
+	if (!name) return false;
+	const usage = await readGeneratedMemorySkillUsage(memoryRoot);
+	const now = new Date().toISOString();
+	const record = normalizeGeneratedMemorySkillRecord(usage.skills[name], name, now);
+	const activeSkillPath = path.join(memoryRoot, "skills", name, "SKILL.md");
+	const archivedSkillPath = path.join(memoryRoot, "skills", ".archive", name, "SKILL.md");
+	if (!(await Bun.file(activeSkillPath).exists()) && !(await Bun.file(archivedSkillPath).exists())) return false;
+	record.pinned = pinned;
+	record.updatedAt = now;
+	usage.skills[name] = record;
+	await writeGeneratedMemorySkillUsage(memoryRoot, usage);
+	return true;
+}
+
+export async function archiveGeneratedMemorySkill(
+	memoryRoot: string,
+	rawName: string,
+	reason: string,
+): Promise<boolean> {
+	const name = sanitizeSkillName(rawName);
+	if (!name) return false;
+	const skillsDir = path.join(memoryRoot, "skills");
+	const sourceSkillPath = path.join(skillsDir, name, "SKILL.md");
+	if (!(await Bun.file(sourceSkillPath).exists())) return false;
+	const usage = await readGeneratedMemorySkillUsage(memoryRoot);
+	const now = new Date().toISOString();
+	const existingRecord = normalizeGeneratedMemorySkillRecord(usage.skills[name], name, now);
+	if (existingRecord.pinned) return false;
+	await archiveGeneratedMemorySkillDir(skillsDir, name);
+	const record = existingRecord;
+	record.state = "archived";
+	record.updatedAt = now;
+	record.archivedAt = now;
+	record.archiveReason = reason.trim() || "Archived by native generated-skill lifecycle.";
+	usage.skills[name] = record;
+	await writeGeneratedMemorySkillUsage(memoryRoot, usage);
+	return true;
+}
+
+export async function restoreGeneratedMemorySkill(memoryRoot: string, rawName: string): Promise<boolean> {
+	const name = sanitizeSkillName(rawName);
+	if (!name) return false;
+	const skillsDir = path.join(memoryRoot, "skills");
+	const source = path.join(skillsDir, ".archive", name);
+	const target = path.join(skillsDir, name);
+	if (!(await Bun.file(path.join(source, "SKILL.md")).exists())) return false;
+	if (await Bun.file(path.join(target, "SKILL.md")).exists()) return false;
+	await fs.mkdir(skillsDir, { recursive: true });
+	await fs.rename(source, target);
+	const usage = await readGeneratedMemorySkillUsage(memoryRoot);
+	const now = new Date().toISOString();
+	const record = normalizeGeneratedMemorySkillRecord(usage.skills[name], name, now);
+	record.state = "active";
+	record.updatedAt = now;
+	record.archivedAt = null;
+	record.archiveReason = null;
+	usage.skills[name] = record;
+	await writeGeneratedMemorySkillUsage(memoryRoot, usage);
+	return true;
+}
+
+function normalizeConsolidatedUserProfile(input: string): string {
+	const trimmed = input.trim();
+	if (!trimmed) return "";
+	if (!trimmed.startsWith(USER_PROFILE_OPEN_TAG) || !trimmed.endsWith(USER_PROFILE_CLOSE_TAG)) {
+		throw new Error(
+			`phase2 user_md must be empty or a complete ${USER_PROFILE_OPEN_TAG}...${USER_PROFILE_CLOSE_TAG} block`,
+		);
+	}
+	return trimmed;
+}
+
+function assertNoIdentityArtifactLeak(fields: ReadonlyArray<{ field: string; value: string }>): void {
+	for (const { field, value } of fields) {
+		for (const { label, pattern } of FORBIDDEN_IDENTITY_ARTIFACT_PATTERNS) {
+			if (pattern.test(value)) {
+				throw new Error(
+					`phase2 attempted to write approval-gated identity artifact ${label} in ${field}; ` +
+						`${MEMORY_ARTIFACTS.soulProposal} must be proposed only by an explicit identity-review flow`,
+				);
+			}
+		}
+	}
+}
+
+async function listRelativeFiles(rootDir: string, prefix = ""): Promise<string[]> {
+	const entries = await fs.readdir(rootDir, { withFileTypes: true }).catch(() => []);
+	const files: string[] = [];
+	for (const entry of entries) {
+		const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+		if (entry.isDirectory()) {
+			files.push(...(await listRelativeFiles(path.join(rootDir, entry.name), relative)));
+			continue;
+		}
+		if (entry.isFile()) files.push(relative);
+	}
+	return files;
+}
+
+async function pruneEmptyDirectories(rootDir: string): Promise<void> {
+	const entries = await fs.readdir(rootDir, { withFileTypes: true }).catch(() => []);
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const child = path.join(rootDir, entry.name);
+		await pruneEmptyDirectories(child);
+		const childEntries = await fs.readdir(child).catch(() => []);
+		if (childEntries.length === 0) {
+			await fs.rm(child, { recursive: true, force: true });
+		}
+	}
+}
+
+function computeCompletionWatermark(claimedInputWatermark: number, outputs: Stage1OutputRow[]): number {
+	const maxOutputWatermark = outputs.reduce((max, row) => Math.max(max, row.sourceUpdatedAt), claimedInputWatermark);
+	return Math.max(claimedInputWatermark, maxOutputWatermark);
+}
+
+function formatRolloutFilename(threadId: string, rolloutSlug: string | null): string {
+	if (!rolloutSlug) return threadId;
+	const normalized = rolloutSlug
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "_")
+		.replace(/_+$/g, "")
+		.slice(0, 20);
+	if (!normalized) return threadId;
+	return `${threadId}-${normalized}`;
+}
+
+function parseJsonObject(text: string): Record<string, unknown> | undefined {
+	if (!text) return undefined;
+	try {
+		const parsed = JSON.parse(text) as unknown;
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+			return parsed as Record<string, unknown>;
+		}
+	} catch {
+		const match = text.match(/\{[\s\S]*\}/);
+		if (!match) return undefined;
+		try {
+			const parsed = JSON.parse(match[0]) as unknown;
+			if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+				return parsed as Record<string, unknown>;
+			}
+		} catch {
+			return undefined;
+		}
+	}
+	return undefined;
+}
+
+function parseStage1OutputSchema(value: Record<string, unknown>): Stage1OutputSchema | undefined {
+	if (!hasExactKeys(value, ["rollout_summary", "rollout_slug", "raw_memory"])) return undefined;
+	if (typeof value.rollout_summary !== "string") return undefined;
+	if (!(typeof value.rollout_slug === "string" || value.rollout_slug === null)) return undefined;
+	if (typeof value.raw_memory !== "string") return undefined;
+	return {
+		rollout_summary: value.rollout_summary,
+		rollout_slug: value.rollout_slug,
+		raw_memory: value.raw_memory,
+	};
+}
+
+function parseConsolidationOutputSchema(value: Record<string, unknown>): ConsolidationOutputSchema | undefined {
+	if (!hasExactKeys(value, ["memory_md", "user_md", "memory_summary", "skills"], true)) return undefined;
+	if (typeof value.memory_md !== "string") return undefined;
+	if (!(value.user_md === undefined || typeof value.user_md === "string")) return undefined;
+	if (typeof value.memory_summary !== "string") return undefined;
+	if (!Array.isArray(value.skills)) return undefined;
+	const skills: ConsolidationSkillSchema[] = [];
+	for (const item of value.skills) {
+		if (!item || typeof item !== "object" || Array.isArray(item)) return undefined;
+		const data = item as Record<string, unknown>;
+		if (!hasExactKeys(data, ["name", "content", "scripts", "templates", "examples"], true)) return undefined;
+		if (typeof data.name !== "string") return undefined;
+		if (!(typeof data.content === "string" || data.content === undefined)) return undefined;
+		const scripts = parseConsolidationSkillFileArray(data.scripts);
+		const templates = parseConsolidationSkillFileArray(data.templates);
+		const examples = parseConsolidationSkillFileArray(data.examples);
+		if (!scripts || !templates || !examples) return undefined;
+		skills.push({
+			name: data.name,
+			content: data.content,
+			scripts,
+			templates,
+			examples,
+		});
+	}
+	return {
+		memory_md: value.memory_md,
+		user_md: value.user_md ?? "",
+		memory_summary: value.memory_summary,
+		skills,
+	};
+}
+
+function parseIdentityReviewOutputSchema(value: Record<string, unknown>): string | undefined {
+	if (!hasExactKeys(value, ["soul_proposal"])) return undefined;
+	if (typeof value.soul_proposal !== "string") return undefined;
+	const proposal = redactSecrets(value.soul_proposal).trim();
+	if (!proposal) return "";
+	if (!proposal.startsWith("<soul_proposal") || !proposal.endsWith("</soul_proposal>")) return undefined;
+	if (/<\s*\/?\s*soul\b/i.test(proposal)) return undefined;
+	if (/<\s*\/?\s*identity\b/i.test(proposal)) return undefined;
+	if (/<\s*\/?\s*personality\b/i.test(proposal)) return undefined;
+	return proposal;
+}
+
+function hasExactKeys(value: Record<string, unknown>, expectedKeys: string[], allowMissing = false): boolean {
+	const sortedKeys = Object.keys(value).sort();
+	const sortedExpected = [...expectedKeys].sort();
+	if (!allowMissing && sortedKeys.length !== sortedExpected.length) return false;
+	for (const key of sortedKeys) {
+		if (!sortedExpected.includes(key)) return false;
+	}
+	if (allowMissing) return true;
+	for (let i = 0; i < sortedExpected.length; i += 1) {
+		if (sortedKeys[i] !== sortedExpected[i]) return false;
+	}
+	return true;
+}
+
+function redactSecrets(input: string): string {
+	let out = input;
+	const patterns = [
+		/(?:sk|pk|rk|tok|key|secret|token|password)[-_A-Za-z0-9]{12,}/g,
+		/[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/g,
+		/(?:AKIA|ASIA)[A-Z0-9]{16}/g,
+	];
+	for (const pattern of patterns) {
+		out = out.replace(pattern, "[REDACTED]");
+	}
+	return out;
+}
+
+function sanitizeSkillName(name: string): string {
+	return name
+		.toLowerCase()
+		.replace(/[^a-z0-9_-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 64);
+}
+
+function parseConsolidationSkillFileArray(value: unknown): ConsolidationSkillFileSchema[] | undefined {
+	if (value === undefined) return [];
+	if (!Array.isArray(value)) return undefined;
+	const files: ConsolidationSkillFileSchema[] = [];
+	for (const item of value) {
+		if (!item || typeof item !== "object" || Array.isArray(item)) return undefined;
+		const data = item as Record<string, unknown>;
+		if (!hasExactKeys(data, ["path", "content"])) return undefined;
+		if (typeof data.path !== "string" || typeof data.content !== "string") return undefined;
+		files.push({ path: data.path, content: data.content });
+	}
+	return files;
+}
+
+function sanitizeConsolidationSkillFiles(
+	files: ConsolidationSkillFileSchema[] | undefined,
+	bucket: "scripts" | "templates" | "examples",
+): ConsolidationSkillFileSchema[] {
+	if (!files || files.length === 0) return [];
+	const sanitized = new Map<string, string>();
+	for (const file of files) {
+		const relativePath = sanitizeSkillRelativePath(file.path);
+		if (!relativePath) continue;
+		const content = redactSecrets(file.content).trim();
+		if (!content) continue;
+		sanitized.set(path.posix.join(bucket, relativePath), content);
+	}
+	return [...sanitized.entries()]
+		.sort(([a], [b]) => a.localeCompare(b))
+		.map(([fullPath, content]) => ({
+			path: fullPath.slice(bucket.length + 1),
+			content,
+		}));
+}
+
+function sanitizeSkillRelativePath(rawPath: string): string | undefined {
+	const normalized = rawPath.replace(/\\/g, "/").trim();
+	if (!normalized) return undefined;
+	if (normalized.startsWith("/")) return undefined;
+	if (normalized.includes("\0")) return undefined;
+	if (normalized.includes(":")) return undefined;
+	const parts = normalized.split("/").filter(Boolean);
+	if (parts.length === 0) return undefined;
+	for (const part of parts) {
+		if (part === "." || part === "..") return undefined;
+		if (!/^[A-Za-z0-9._-]+$/.test(part)) return undefined;
+	}
+	return parts.join("/");
+}
+
+function extractMessageText(message: AgentMessage): string {
+	const content = (message as { content?: unknown }).content;
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map(item => {
+			if (item.type === "text") return item.text;
+			if (item.type === "toolCall") return `${item.toolName} ${JSON.stringify(item.arguments)}`;
+			return "";
+		})
+		.join("\n");
+}
+
+function extractPostTurnReviewMessages(session: AgentSession): PostTurnReviewMessage[] {
+	const manager = session.sessionManager as {
+		getEntries?: () => Array<{ type?: string; message?: { role?: unknown; content?: unknown } }>;
+	};
+	const entries = manager.getEntries?.();
+	if (!entries) return [];
+	const messages: PostTurnReviewMessage[] = [];
+	for (const entry of entries) {
+		if (entry.type !== "message") continue;
+		const message = entry.message;
+		if (!message) continue;
+		const role = message.role;
+		if (role !== "user" && role !== "assistant") continue;
+		const content =
+			role === "user" ? extractPostTurnUserText(message.content) : extractPostTurnAssistantText(message.content);
+		const trimmed = content.trim();
+		if (!trimmed) continue;
+		messages.push({ role, content: trimmed });
+	}
+	return messages;
+}
+
+function extractPostTurnUserText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const item of content) {
+		if (!item || typeof item !== "object") continue;
+		const block = item as { type?: unknown; text?: unknown };
+		if (block.type === "text" && typeof block.text === "string") {
+			parts.push(block.text);
+		}
+	}
+	return parts.join("\n");
+}
+
+function extractPostTurnAssistantText(content: unknown): string {
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const item of content) {
+		if (!item || typeof item !== "object") continue;
+		const block = item as { type?: unknown; text?: unknown };
+		if (block.type === "text" && typeof block.text === "string") {
+			parts.push(block.text);
+		}
+	}
+	return parts.join("\n");
+}
+
+function buildPostTurnReviewThreadId(sessionId: string | undefined, userTurns: number): string {
+	const rawId = sessionId?.trim() || "unknown-session";
+	const safeSessionId =
+		rawId
+			.replace(/[^A-Za-z0-9_-]+/g, "_")
+			.replace(/^_+|_+$/g, "")
+			.slice(0, 80) || "unknown-session";
+	return `${POST_TURN_REVIEW_THREAD_PREFIX}-${safeSessionId}-${userTurns}`;
+}
+
+function truncateByApproxTokens(text: string, tokenLimit: number): string {
+	if (tokenLimit <= 0) return "";
+	const maxChars = tokenLimit * 4;
+	if (text.length <= maxChars) return text;
+	const head = Math.floor(maxChars * 0.6);
+	const tail = maxChars - head;
+	return `${text.slice(0, head)}\n\n...[truncated]...\n\n${text.slice(-tail)}`;
+}
+
+function computeModelTokenBudget(model: Model, config: MemoryRuntimeConfig): number {
+	const maxTokens =
+		Number.isFinite(model.contextWindow) && model.contextWindow > 0 ? model.contextWindow : config.fallbackTokenLimit;
+	return Math.max(2048, Math.floor(maxTokens));
+}
+
+async function resolveMemoryModel(options: {
+	modelRegistry: ModelRegistry;
+	session: AgentSession;
+	fallbackRole: string;
+}): Promise<Model | undefined> {
+	const { modelRegistry, session, fallbackRole } = options;
+	const requestedModel = session.settings.getModelRole(fallbackRole) || session.settings.getModelRole("default");
+	if (requestedModel) {
+		const resolved = resolveModelRoleValue(requestedModel, modelRegistry.getAll(), {
+			settings: session.settings,
+			matchPreferences: { usageOrder: session.settings.getStorage()?.getModelUsageOrder() },
+			modelRegistry,
+		});
+		if (resolved.model) return resolved.model;
+	}
+	return session.model ?? modelRegistry.getAll()[0];
+}
+
+function loadMemoryConfig(settings: Settings): MemoryRuntimeConfig {
+	const selfImprovementMode = settings.get("selfImprovement.mode") ?? DEFAULTS.selfImprovementMode;
+	const backgroundReviewMode = settings.get("selfImprovement.backgroundReviewMode") ?? DEFAULTS.backgroundReviewMode;
+	const backgroundReviewEveryNTurns =
+		settings.get("selfImprovement.backgroundReviewEveryNTurns") ?? DEFAULTS.backgroundReviewEveryNTurns;
+	const identityReviewMode = settings.get("selfImprovement.identityReviewMode") ?? DEFAULTS.identityReviewMode;
+	const curatorMode = settings.get("selfImprovement.curatorMode") ?? DEFAULTS.curatorMode;
+	const generatedSkillStaleAfterDays =
+		settings.get("selfImprovement.generatedSkillStaleAfterDays") ?? DEFAULTS.generatedSkillStaleAfterDays;
+	const generatedSkillArchiveAfterDays =
+		settings.get("selfImprovement.generatedSkillArchiveAfterDays") ?? DEFAULTS.generatedSkillArchiveAfterDays;
+	const localMemoryRequested = settings.get("memory.backend") === "local" || settings.get("memories.enabled") === true;
+	return {
+		enabled: selfImprovementMode !== "off" && localMemoryRequested,
+		selfImprovementMode,
+		backgroundReviewMode,
+		backgroundReviewEveryNTurns: Number.isFinite(backgroundReviewEveryNTurns)
+			? Math.max(0, Math.floor(backgroundReviewEveryNTurns))
+			: DEFAULTS.backgroundReviewEveryNTurns,
+		identityReviewMode,
+		curatorMode,
+		generatedSkillStaleAfterDays,
+		generatedSkillArchiveAfterDays,
+		maxRolloutsPerStartup: settings.get("memories.maxRolloutsPerStartup") ?? DEFAULTS.maxRolloutsPerStartup,
+		maxRolloutAgeDays: settings.get("memories.maxRolloutAgeDays") ?? DEFAULTS.maxRolloutAgeDays,
+		minRolloutIdleHours: settings.get("memories.minRolloutIdleHours") ?? DEFAULTS.minRolloutIdleHours,
+		threadScanLimit: settings.get("memories.threadScanLimit") ?? DEFAULTS.threadScanLimit,
+		maxRawMemoriesForGlobal: settings.get("memories.maxRawMemoriesForGlobal") ?? DEFAULTS.maxRawMemoriesForGlobal,
+		stage1Concurrency: settings.get("memories.stage1Concurrency") ?? DEFAULTS.stage1Concurrency,
+		stage1LeaseSeconds: settings.get("memories.stage1LeaseSeconds") ?? DEFAULTS.stage1LeaseSeconds,
+		stage1RetryDelaySeconds: settings.get("memories.stage1RetryDelaySeconds") ?? DEFAULTS.stage1RetryDelaySeconds,
+		phase2LeaseSeconds: settings.get("memories.phase2LeaseSeconds") ?? DEFAULTS.phase2LeaseSeconds,
+		phase2RetryDelaySeconds: settings.get("memories.phase2RetryDelaySeconds") ?? DEFAULTS.phase2RetryDelaySeconds,
+		phase2HeartbeatSeconds: settings.get("memories.phase2HeartbeatSeconds") ?? DEFAULTS.phase2HeartbeatSeconds,
+		rolloutPayloadPercent: settings.get("memories.rolloutPayloadPercent") ?? DEFAULTS.rolloutPayloadPercent,
+		phase1InputTokenLimit: settings.get("memories.phase1InputTokenLimit") ?? DEFAULTS.phase1InputTokenLimit,
+		fallbackTokenLimit: settings.get("memories.fallbackTokenLimit") ?? DEFAULTS.fallbackTokenLimit,
+		summaryInjectionTokenLimit:
+			settings.get("memories.summaryInjectionTokenLimit") ?? DEFAULTS.summaryInjectionTokenLimit,
+	};
+}
+
+export function getMemoryRoot(agentDir: string, cwd: string): string {
+	return path.join(getMemoriesDir(agentDir), encodeProjectPath(cwd));
+}
+
+function encodeProjectPath(cwd: string): string {
+	return `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+}
+
+function unixNow(): number {
+	return Math.floor(Date.now() / 1000);
+}
+
+async function runWithConcurrency<T>(
+	items: T[],
+	concurrency: number,
+	worker: (item: T) => Promise<void>,
+): Promise<void> {
+	const queue = [...items];
+	const workers = new Array(Math.max(1, concurrency)).fill(0).map(async () => {
+		while (queue.length > 0) {
+			const item = queue.shift();
+			if (!item) return;
+			await worker(item);
+		}
+	});
+	await Promise.all(workers);
+}