@gajae-code/coding-agent 0.11.11 → 0.12.0

package/src/session/session-manager.ts

@@ -31,9 +31,9 @@ import {
 	toError,
 } from "@gajae-code/utils";
 import type { TtsrInjectionRecord } from "../export/ttsr";
+import { assertSafePathComponent } from "../gjc-runtime/session-layout";
 import { writeTextAtomic } from "../gjc-runtime/state-writer";
 import type { ManagedLegacyLocalMigrationSource } from "../internal-urls/local-protocol";
-
 import * as git from "../utils/git";
 import { ArtifactManager } from "./artifacts";
 import {
@@ -79,6 +79,23 @@ import {
 	retainManagedDirectoryAuthority,
 } from "./internal/managed-session-storage";
 import { classifyNativePublishOutcome, formatNativePublishDiagnostic } from "./internal/native-publish-outcome";
+import {
+	hasOnlyKeys as hasOnlyMemoryGuardKeys,
+	isMemoryGuardDecimalString,
+	isMemoryGuardRelativePath,
+	isMemoryGuardSha256Hex,
+	type MemoryGuardCheckpointBlobAuthorityV1,
+	type MemoryGuardCheckpointBlobManifestEntryV1,
+	type MemoryGuardCheckpointBlobManifestV1,
+	type MemoryGuardCreateCheckpointInput,
+	type MemoryGuardParticipantDescriptorV1,
+	type MemoryGuardParticipantIngressLease,
+	type MemoryGuardRestoreInput,
+	type MemoryGuardRestoreResult,
+	type MemoryGuardSessionManagerCheckpointV1,
+	memoryGuardCanonicalJson,
+	memoryGuardSha256Hex,
+} from "./memory-guard-checkpoint-participant";
 
 import {
 	type BashExecutionMessage,
@@ -480,6 +497,238 @@ export type DefaultModelSelectionStage = {
 	readonly tempPath: string | undefined;
 	readonly persistsToExistingFile: boolean;
 };
+export interface SessionManagerRevisionSnapshot {
+	entry: number;
+	leaf: number;
+	headerExport: number;
+	label: number;
+	replayMetadata: number;
+}
+
+export interface SessionManagerCheckpointRevisionStrings {
+	entry: string;
+	leaf: string;
+	headerExport: string;
+	label: string;
+	replayMetadata: string;
+}
+
+function assertMemoryGuardSessionId(sessionId: string): void {
+	assertSafePathComponent(sessionId, "memory guard checkpoint session id");
+}
+
+function memoryGuardParticipantRoot(checkpointRoot: string, sessionId: string): string {
+	assertMemoryGuardSessionId(sessionId);
+	return path.join(checkpointRoot, "participants", sessionId);
+}
+
+function memoryGuardParticipantRelativePath(sessionId: string, suffix: string): string {
+	assertMemoryGuardSessionId(sessionId);
+	return `participants/${sessionId}/${suffix}`;
+}
+
+async function fsyncDirectoryPath(directoryPath: string): Promise<void> {
+	const directory = await fs.promises.open(directoryPath, "r");
+	try {
+		await directory.sync();
+	} finally {
+		await directory.close();
+	}
+}
+
+async function ensureOwnerOnlyDirectory(directoryPath: string): Promise<void> {
+	await fs.promises.mkdir(directoryPath, { recursive: true, mode: 0o700 });
+	await fs.promises.chmod(directoryPath, 0o700).catch(() => undefined);
+	await fsyncDirectoryPath(directoryPath);
+}
+interface CreatedDirectoryIdentity {
+	dev: bigint;
+	ino: bigint;
+}
+
+async function ensureOwnerOnlyDirectoryTracked(directoryPath: string): Promise<CreatedDirectoryIdentity | undefined> {
+	const createdPath = await fs.promises.mkdir(directoryPath, { recursive: true, mode: 0o700 });
+	await fs.promises.chmod(directoryPath, 0o700).catch(() => undefined);
+	await fsyncDirectoryPath(directoryPath);
+	if (createdPath === undefined) return undefined;
+	const stat = await fs.promises.lstat(directoryPath, { bigint: true });
+	return { dev: stat.dev, ino: stat.ino };
+}
+
+async function removeCreatedDirectoryIfEmpty(
+	directoryPath: string,
+	created: CreatedDirectoryIdentity | undefined,
+): Promise<void> {
+	if (!created) return;
+	const stat = await fs.promises.lstat(directoryPath, { bigint: true }).catch(() => undefined);
+	if (!stat || stat.dev !== created.dev || stat.ino !== created.ino) return;
+	await fs.promises.rmdir(directoryPath).catch(() => undefined);
+	await fsyncDirectoryPath(path.dirname(directoryPath)).catch(() => undefined);
+}
+
+async function writeOwnerOnlyFileNoReplace(filePath: string, content: Uint8Array | string): Promise<void> {
+	await ensureOwnerOnlyDirectory(path.dirname(filePath));
+	const handle = await fs.promises.open(filePath, "wx", 0o600);
+	try {
+		await handle.writeFile(content);
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	await fs.promises.chmod(filePath, 0o600).catch(() => undefined);
+	await fsyncDirectoryPath(path.dirname(filePath));
+}
+
+const MEMORY_GUARD_CHECKPOINT_FILE_MAX_BYTES = 64 * 1024 * 1024;
+const MEMORY_GUARD_CHECKPOINT_BLOB_MAX_ENTRIES = 4096;
+const MEMORY_GUARD_CHECKPOINT_BLOB_TOTAL_MAX_BYTES = 64 * 1024 * 1024;
+
+function collectCheckpointBlobRefs(value: unknown, refs: Set<string> = new Set(), key?: string): Set<string> {
+	const addRef = (candidate: unknown): void => {
+		if (typeof candidate === "string" && parseBlobRef(candidate)) refs.add(candidate);
+	};
+	if (Array.isArray(value)) {
+		for (const item of value) collectCheckpointBlobRefs(item, refs, key);
+		return refs;
+	}
+	if (!value || typeof value !== "object") return refs;
+	if (isRecord(value) && value.kind === "cold_spill" && typeof value.ref === "string" && parseBlobRef(value.ref))
+		refs.add(value.ref);
+	if (isImageBlock(value) && key === TEXT_CONTENT_KEY) addRef(value.data);
+	if (hasImageUrl(value)) {
+		if (typeof value.image_url === "string") addRef(value.image_url);
+		else addRef(value.image_url.url);
+	}
+	for (const [childKey, item] of Object.entries(value as Record<string, unknown>)) {
+		if (childKey === "data" && key !== TEXT_CONTENT_KEY) addRef(item);
+		collectCheckpointBlobRefs(item, refs, childKey);
+	}
+	return refs;
+}
+
+function decodeCheckpointUtf8(data: Uint8Array): string | null {
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(data);
+	} catch {
+		return null;
+	}
+}
+
+function validateMemoryGuardBlobAuthority(value: unknown): value is MemoryGuardCheckpointBlobAuthorityV1 {
+	if (
+		!isRecord(value) ||
+		!hasOnlyMemoryGuardKeys(value, ["kind", "manifest_relative_path", "manifest_sha256", "root_relative_path"])
+	)
+		return false;
+	return (
+		value.kind === "checkpoint_blob_tree_v1" &&
+		isMemoryGuardRelativePath(value.manifest_relative_path) &&
+		isMemoryGuardSha256Hex(value.manifest_sha256) &&
+		isMemoryGuardRelativePath(value.root_relative_path)
+	);
+}
+
+function validateMemoryGuardTranscriptDescriptor(
+	value: unknown,
+): value is MemoryGuardSessionManagerCheckpointV1["transcript"] {
+	if (!isRecord(value) || !hasOnlyMemoryGuardKeys(value, ["bytes", "relative_path", "sha256"])) return false;
+	return (
+		isMemoryGuardDecimalString(value.bytes) &&
+		isMemoryGuardRelativePath(value.relative_path) &&
+		isMemoryGuardSha256Hex(value.sha256)
+	);
+}
+
+function validateMemoryGuardRevisions(value: unknown): value is SessionManagerCheckpointRevisionStrings {
+	if (!isRecord(value) || !hasOnlyMemoryGuardKeys(value, ["entry", "leaf", "headerExport", "label", "replayMetadata"]))
+		return false;
+	return (
+		isMemoryGuardDecimalString(value.entry) &&
+		isMemoryGuardDecimalString(value.leaf) &&
+		isMemoryGuardDecimalString(value.headerExport) &&
+		isMemoryGuardDecimalString(value.label) &&
+		isMemoryGuardDecimalString(value.replayMetadata)
+	);
+}
+
+function validateMemoryGuardCheckpoint(value: unknown): value is MemoryGuardSessionManagerCheckpointV1 {
+	if (
+		!isRecord(value) ||
+		!hasOnlyMemoryGuardKeys(value, [
+			"blob_authority",
+			"revisions",
+			"schema_version",
+			"session_id",
+			"session_name",
+			"transcript",
+		])
+	)
+		return false;
+	return (
+		value.schema_version === 1 &&
+		typeof value.session_id === "string" &&
+		value.session_id.length > 0 &&
+		(value.session_name === null || typeof value.session_name === "string") &&
+		validateMemoryGuardBlobAuthority(value.blob_authority) &&
+		validateMemoryGuardRevisions(value.revisions) &&
+		validateMemoryGuardTranscriptDescriptor(value.transcript)
+	);
+}
+
+function validateMemoryGuardBlobManifestEntry(value: unknown): value is MemoryGuardCheckpointBlobManifestEntryV1 {
+	if (!isRecord(value) || !hasOnlyMemoryGuardKeys(value, ["bytes", "relative_path", "sha256"])) return false;
+	return (
+		isMemoryGuardDecimalString(value.bytes) &&
+		isMemoryGuardRelativePath(value.relative_path) &&
+		isMemoryGuardSha256Hex(value.sha256)
+	);
+}
+
+function validateMemoryGuardBlobManifest(value: unknown): value is MemoryGuardCheckpointBlobManifestV1 {
+	if (!isRecord(value) || !hasOnlyMemoryGuardKeys(value, ["entries", "schema_version"])) return false;
+	if (value.schema_version !== 1 || !Array.isArray(value.entries)) return false;
+	return value.entries.every(validateMemoryGuardBlobManifestEntry);
+}
+
+function memoryGuardParticipantMatchesCheckpoint(
+	participant: MemoryGuardParticipantDescriptorV1,
+	checkpoint: MemoryGuardSessionManagerCheckpointV1,
+): boolean {
+	return (
+		participant.session_id === checkpoint.session_id &&
+		participant.session_name === checkpoint.session_name &&
+		JSON.stringify(participant.checkpoint) === JSON.stringify(checkpoint.blob_authority) &&
+		JSON.stringify(participant.revisions) === JSON.stringify(checkpoint.revisions) &&
+		JSON.stringify(participant.transcript) === JSON.stringify(checkpoint.transcript)
+	);
+}
+
+function readCheckpointAuthorityFile(
+	authority: native.RecoveryFsRoot,
+	relativePath: string,
+	maxBytes: number,
+): Uint8Array | null {
+	const result = authority.readManaged(relativePath);
+	if (!result.ok || !result.data || result.data.byteLength > maxBytes) return null;
+	return result.data;
+}
+
+function toCanonicalRevisionString(name: keyof SessionManagerRevisionSnapshot, value: number): string {
+	if (!Number.isSafeInteger(value) || value < 0) throw new Error(`invalid_session_manager_revision:${name}`);
+	return String(value);
+}
+
+export function toSessionManagerCheckpointRevisionStrings(
+	snapshot: SessionManagerRevisionSnapshot,
+): SessionManagerCheckpointRevisionStrings {
+	return {
+		entry: toCanonicalRevisionString("entry", snapshot.entry),
+		leaf: toCanonicalRevisionString("leaf", snapshot.leaf),
+		headerExport: toCanonicalRevisionString("headerExport", snapshot.headerExport),
+		label: toCanonicalRevisionString("label", snapshot.label),
+		replayMetadata: toCanonicalRevisionString("replayMetadata", snapshot.replayMetadata),
+	};
+}
 
 export type DefaultModelSelectionPromotion =
 	| { readonly kind: "promoted" }
@@ -3506,6 +3755,81 @@ class NdjsonFileWriter {
 	}
 }
 
+const PROJECT_SESSION_SCAN_MAX_DIRECTORIES = 4096;
+const PROJECT_SESSION_SCAN_MAX_FILES = 1000;
+
+function isProjectSessionTranscriptPath(projectGjcDir: string, filePath: string): boolean {
+	const relative = path.relative(projectGjcDir, filePath);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) return false;
+	const segments = relative.split(path.sep);
+	if (segments.length === 1) return true;
+	const parent = segments.at(-2);
+	return parent === "agent-session" || segments.includes("sessions");
+}
+
+/**
+ * Discover resumable transcripts intentionally stored inside a project's `.gjc`.
+ * Runtime token/audit JSONL files are excluded by requiring a known transcript
+ * container (`agent-session` or `sessions`).
+ */
+function listProjectSessionTranscriptFiles(cwd: string): string[] {
+	const projectGjcDir = path.join(path.resolve(cwd), ".gjc");
+	let rootStat: fs.Stats;
+	try {
+		rootStat = fs.lstatSync(projectGjcDir);
+	} catch {
+		return [];
+	}
+	if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) return [];
+
+	const directories = [projectGjcDir];
+	const files: string[] = [];
+	let scannedDirectories = 0;
+	while (directories.length > 0 && scannedDirectories < PROJECT_SESSION_SCAN_MAX_DIRECTORIES) {
+		const directory = directories.pop()!;
+		scannedDirectories++;
+		let entries: fs.Dirent[];
+		try {
+			entries = fs.readdirSync(directory, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (entry.isSymbolicLink()) continue;
+			const entryPath = path.join(directory, entry.name);
+			if (entry.isDirectory()) {
+				directories.push(entryPath);
+				continue;
+			}
+			if (
+				entry.isFile() &&
+				!entry.name.startsWith(".") &&
+				entry.name.endsWith(".jsonl") &&
+				isProjectSessionTranscriptPath(projectGjcDir, entryPath)
+			) {
+				files.push(entryPath);
+				if (files.length >= PROJECT_SESSION_SCAN_MAX_FILES) return files;
+			}
+		}
+	}
+	return files;
+}
+
+async function collectProjectSessions(cwd: string, storage: FileSessionStorage): Promise<SessionInfo[]> {
+	return await collectSessionsFromFiles(listProjectSessionTranscriptFiles(cwd), storage);
+}
+
+function mergeSessionInventories(...inventories: SessionInfo[][]): SessionInfo[] {
+	const sessions = new Map<string, SessionInfo>();
+	for (const inventory of inventories) {
+		for (const session of inventory) {
+			const current = sessions.get(session.id);
+			if (!current || session.modified.getTime() > current.modified.getTime()) sessions.set(session.id, session);
+		}
+	}
+	return [...sessions.values()].sort((left, right) => right.modified.getTime() - left.modified.getTime());
+}
+
 const DEFAULT_WELCOME_RECENT_SESSION_LIMIT = 20;
 
 /** Get recent sessions for display in welcome screen */
@@ -3517,6 +3841,21 @@ export async function getRecentSessions(
 	return getSortedSessions(sessionDir, storage, limit);
 }
 
+export function getRecentSessionDisplay(
+	sessions: readonly SessionInfo[],
+	limit = DEFAULT_WELCOME_RECENT_SESSION_LIMIT,
+): Array<{ name: string; timeAgo: string }> {
+	return sessions.slice(0, limit).map(session => {
+		const recent = new RecentSessionInfo(
+			session.path,
+			session.modified.getTime(),
+			{ title: session.title, timestamp: session.created.toISOString() },
+			session.firstMessage,
+		);
+		return { name: recent.name, timeAgo: recent.timeAgo };
+	});
+}
+
 /**
  * Manages conversation sessions as append-only trees stored in JSONL files.
  *
@@ -4015,6 +4354,8 @@ export class SessionManager {
 	#needsFullRewriteOnNextPersist: boolean = false;
 	#ensuredOnDisk: boolean = false;
 	#recoveryHydrationContext: RecoveryHydrationContext | undefined;
+	#recoveryPromotionTranscriptPath: string | undefined;
+	#memoryGuardParticipantIngressToken: symbol | undefined;
 	#fileEntries: FileEntry[] = [];
 	#pendingStrictAdoption: { canonicalPath: string; identity: ResumeSessionIdentity } | undefined;
 	#byId: Map<string, SessionEntry> = new Map();
@@ -4049,7 +4390,8 @@ export class SessionManager {
 	#inMemoryArtifactCounter = 0;
 	readonly #blobStore: BlobStore;
 	#residentTextBlobStore: BlobStore = new MemoryBlobStore();
-	readonly #residentImageBlobStore: BlobStore;
+	#residentImageBlobStore: BlobStore;
+	#memoryGuardCheckpointBlobs: Map<string, Buffer> | undefined;
 	#entryRevision = 0;
 	#leafRevision = 0;
 	/** Export/header cache invalidation contract; consumers may arrive after the revision field. */
@@ -4122,6 +4464,9 @@ export class SessionManager {
 			},
 		};
 	}
+	#coldSpillReadStore(): BlobStore {
+		return this.#memoryGuardCheckpointBlobs ? this.#residentImageBlobStore : this.#blobStore;
+	}
 
 	#residentCacheDir(sessionFile: string): string {
 		const instance = ++residentCacheInstanceCounter;
@@ -4178,13 +4523,7 @@ export class SessionManager {
 	 * revision contract). Tests assert the invalidation mapping through this;
 	 * future export/label-view caches key off their respective domains.
 	 */
-	revisionSnapshot(): {
-		entry: number;
-		leaf: number;
-		headerExport: number;
-		label: number;
-		replayMetadata: number;
-	} {
+	revisionSnapshot(): SessionManagerRevisionSnapshot {
 		return {
 			entry: this.#entryRevision,
 			leaf: this.#leafRevision,
@@ -4308,6 +4647,7 @@ export class SessionManager {
 
 	/** Switch to a different session file (used for resume and branching) */
 	async setSessionFile(sessionFile: string): Promise<void> {
+		this.#assertRecoveryHydrationWritable();
 		const resolvedSessionFile = this.storage instanceof FileSessionStorage ? path.resolve(sessionFile) : sessionFile;
 		const strictAdoption = this.#pendingStrictAdoption;
 		this.#pendingStrictAdoption = undefined;
@@ -4361,6 +4701,7 @@ export class SessionManager {
 
 	/** Start a new session. Closes any existing writer first. */
 	async newSession(options?: NewSessionOptions): Promise<string | undefined> {
+		this.#assertRecoveryHydrationWritable();
 		const prepared = await this.prepareNewSession(options);
 		try {
 			this.commitPreparedNewSession(prepared);
@@ -4385,6 +4726,7 @@ export class SessionManager {
 	 * @internal
 	 */
 	async prepareNewSession(options?: NewSessionOptions): Promise<PreparedNewSession> {
+		this.#assertRecoveryHydrationWritable();
 		await this.#retryPreparedNewSessionCleanups();
 		await this.#closePersistWriter();
 		const preallocated = this.#lifecycleIdAdopted ? undefined : lifecyclePreallocatedSessionId();
@@ -4655,6 +4997,7 @@ export class SessionManager {
 
 	/** Prepare a path-only branch successor without publishing it through public manager state. @internal */
 	async prepareBranchedSession(leafId: string): Promise<PreparedNewSession> {
+		this.#assertRecoveryHydrationWritable();
 		await this.#retryPreparedNewSessionCleanups();
 		const branchPath = this.#getCanonicalBranchClones(leafId);
 		if (branchPath.length === 0) throw new Error(`Entry ${leafId} not found`);
@@ -4738,6 +5081,7 @@ export class SessionManager {
 
 	/** Publish a prepared successor synchronously after all readiness awaits succeed. @internal */
 	commitPreparedNewSession(prepared: PreparedNewSession): void {
+		this.#assertRecoveryHydrationWritable();
 		const stage = prepared as PreparedNewSessionState;
 		if (!this.#preparedNewSessions.has(stage) || stage.committed || stage.discarded) {
 			throw new Error("Prepared session is no longer available.");
@@ -6230,6 +6574,160 @@ export class SessionManager {
 		return this.#sessionFile;
 	}
 
+	acquireMemoryGuardParticipantIngressLease(): MemoryGuardParticipantIngressLease {
+		if (this.#memoryGuardParticipantIngressToken)
+			throw new Error("memory_guard_participant_ingress_lease_already_held");
+		const token = Symbol("memory_guard_participant_ingress_lease");
+		this.#memoryGuardParticipantIngressToken = token;
+		let released = false;
+		return Object.freeze({
+			token,
+			release: () => {
+				if (released) return;
+				released = true;
+				if (this.#memoryGuardParticipantIngressToken === token)
+					this.#memoryGuardParticipantIngressToken = undefined;
+			},
+		});
+	}
+
+	#assertMemoryGuardParticipantIngressLease(lease: MemoryGuardParticipantIngressLease): void {
+		if (this.#memoryGuardParticipantIngressToken !== lease.token) {
+			throw new Error("memory_guard_participant_ingress_lease_invalid");
+		}
+	}
+
+	#stageMemoryGuardCheckpointBlobs(blobs: Map<string, Buffer>): void {
+		const stagedImageStore = new MemoryBlobStore();
+		for (const blob of blobs.values()) {
+			this.#residentTextBlobStore.putSync(blob);
+			stagedImageStore.putSync(blob);
+		}
+		this.#residentImageBlobStore = stagedImageStore;
+		this.#memoryGuardCheckpointBlobs = blobs;
+	}
+
+	async createMemoryGuardCheckpoint(
+		input: MemoryGuardCreateCheckpointInput,
+	): Promise<MemoryGuardSessionManagerCheckpointV1> {
+		this.#assertMemoryGuardParticipantIngressLease(input.ingressLease);
+		if (!this.#sessionFile) throw new Error("memory_guard_checkpoint_session_file_unavailable");
+		await this.flush();
+		const captured = SessionManager.captureTranscriptStrict(this.#sessionFile, this.storage);
+		if (captured.kind !== "captured") {
+			throw new Error(`memory_guard_checkpoint_capture_failed:${captured.reason}`);
+		}
+		if (captured.snapshot.content.byteLength > MEMORY_GUARD_CHECKPOINT_FILE_MAX_BYTES)
+			throw new Error("memory_guard_checkpoint_transcript_capacity_exceeded");
+		const transcriptText = decodeCheckpointUtf8(captured.snapshot.content);
+		if (transcriptText === null) throw new Error("memory_guard_checkpoint_transcript_unreadable");
+		const entries = parseSessionEntries(transcriptText);
+		const sessionId = this.getSessionId();
+		assertMemoryGuardSessionId(sessionId);
+		const sessionName = this.getSessionName() ?? null;
+		const revisions = this.revisionSnapshot();
+		const participantRoot = memoryGuardParticipantRoot(input.checkpointRoot, sessionId);
+		const transcriptRelativePath = memoryGuardParticipantRelativePath(sessionId, "transcript.jsonl");
+		const blobRootRelativePath = memoryGuardParticipantRelativePath(sessionId, "blobs");
+		const blobManifestRelativePath = memoryGuardParticipantRelativePath(sessionId, "blob-manifest.json");
+		const refs = [...collectCheckpointBlobRefs(entries)].sort();
+		if (refs.length > MEMORY_GUARD_CHECKPOINT_BLOB_MAX_ENTRIES)
+			throw new Error("memory_guard_checkpoint_blob_count_exceeded");
+		const blobManifestEntries: MemoryGuardCheckpointBlobManifestEntryV1[] = [];
+		const blobWrites: Array<{ data: Buffer; relativePath: string }> = [];
+		let aggregateBlobBytes = 0;
+		for (const ref of refs) {
+			const hash = parseBlobRef(ref);
+			if (!hash) continue;
+			const data =
+				this.#residentTextBlobStore.getCheckedSync(hash) ??
+				this.#residentImageBlobStore.getCheckedSync(hash) ??
+				this.#blobStore.getCheckedSync(hash);
+			if (!data) throw new Error(`memory_guard_checkpoint_blob_missing:${hash}`);
+			if (data.byteLength > MEMORY_GUARD_CHECKPOINT_FILE_MAX_BYTES)
+				throw new Error(`memory_guard_checkpoint_blob_capacity_exceeded:${hash}`);
+			aggregateBlobBytes += data.byteLength;
+			if (aggregateBlobBytes > MEMORY_GUARD_CHECKPOINT_BLOB_TOTAL_MAX_BYTES)
+				throw new Error("memory_guard_checkpoint_blob_total_capacity_exceeded");
+			const relativePath = hash;
+			blobWrites.push({ data, relativePath });
+			blobManifestEntries.push({
+				bytes: String(data.byteLength),
+				relative_path: relativePath,
+				sha256: memoryGuardSha256Hex(data),
+			});
+		}
+		const publishedCheckpointPaths: string[] = [];
+		const cleanupPublishedCheckpointPaths = async (): Promise<void> => {
+			for (const publishedPath of publishedCheckpointPaths.reverse())
+				await fs.promises.rm(publishedPath, { force: true }).catch(() => undefined);
+			await fs.promises.rmdir(path.join(input.checkpointRoot, blobRootRelativePath)).catch(() => undefined);
+			await fs.promises.rmdir(participantRoot).catch(() => undefined);
+		};
+		const publishCheckpointFile = async (filePath: string, data: Uint8Array | string): Promise<void> => {
+			try {
+				await writeOwnerOnlyFileNoReplace(filePath, data);
+				publishedCheckpointPaths.push(filePath);
+			} catch (error) {
+				await cleanupPublishedCheckpointPaths();
+				throw error;
+			}
+		};
+		await ensureOwnerOnlyDirectory(participantRoot);
+		await publishCheckpointFile(path.join(input.checkpointRoot, transcriptRelativePath), captured.snapshot.content);
+		for (const write of blobWrites)
+			await publishCheckpointFile(
+				path.join(input.checkpointRoot, blobRootRelativePath, write.relativePath),
+				write.data,
+			);
+		blobManifestEntries.sort((left, right) => left.relative_path.localeCompare(right.relative_path));
+		const blobManifest: MemoryGuardCheckpointBlobManifestV1 = {
+			entries: blobManifestEntries,
+			schema_version: 1,
+		};
+		const blobManifestText = memoryGuardCanonicalJson(blobManifest);
+		await publishCheckpointFile(path.join(input.checkpointRoot, blobManifestRelativePath), blobManifestText);
+		const checkpoint: MemoryGuardSessionManagerCheckpointV1 = {
+			blob_authority: {
+				kind: "checkpoint_blob_tree_v1",
+				manifest_relative_path: blobManifestRelativePath,
+				manifest_sha256: memoryGuardSha256Hex(blobManifestText),
+				root_relative_path: blobRootRelativePath,
+			},
+			revisions: toSessionManagerCheckpointRevisionStrings(revisions),
+			schema_version: 1,
+			session_id: sessionId,
+			session_name: sessionName,
+			transcript: {
+				bytes: String(captured.snapshot.content.byteLength),
+				relative_path: transcriptRelativePath,
+				sha256: captured.snapshot.identity.sha256,
+			},
+		};
+		const checkpointPath = path.join(
+			input.checkpointRoot,
+			memoryGuardParticipantRelativePath(sessionId, "session-manager.json"),
+		);
+		await publishCheckpointFile(checkpointPath, memoryGuardCanonicalJson(checkpoint));
+		const currentRevisions = this.revisionSnapshot();
+		const recaptured = SessionManager.captureTranscriptStrict(this.#sessionFile, this.storage);
+		if (
+			this.getSessionId() !== sessionId ||
+			(this.getSessionName() ?? null) !== sessionName ||
+			Object.keys(revisions).some(
+				key =>
+					currentRevisions[key as keyof SessionManagerRevisionSnapshot] !==
+					revisions[key as keyof SessionManagerRevisionSnapshot],
+			) ||
+			recaptured.kind !== "captured" ||
+			!sameResumeIdentity(captured.snapshot.identity, recaptured.snapshot.identity)
+		) {
+			await cleanupPublishedCheckpointPaths();
+			throw new Error("memory_guard_checkpoint_state_changed_during_capture");
+		}
+		return checkpoint;
+	}
+
 	/**
 	 * Returns the session artifacts directory path (session file path without .jsonl).
 	 * Returns null when the session is not persisted to a file.
@@ -6491,7 +6989,11 @@ export class SessionManager {
 	 * @param source - "user" for explicit renames (/rename command, RPC); "auto" for generated titles.
 	 *   Auto-generated titles are silently ignored when the user has already set a name.
 	 */
+	#assertRecoveryHydrationWritable(): void {
+		if (this.#recoveryHydrationContext) throw new Error("recovery_hydration_not_promoted");
+	}
 	async setSessionName(name: string, source: "auto" | "user" = "auto"): Promise<boolean> {
+		this.#assertRecoveryHydrationWritable();
 		// User-set names take permanent precedence over auto-generated ones.
 		if (this.#titleSource === "user" && source === "auto") return false;
 
@@ -6617,6 +7119,7 @@ export class SessionManager {
 	}
 
 	#appendEntry(entry: SessionEntry): void {
+		this.#assertRecoveryHydrationWritable();
 		const normalizedEntry = normalizeSessionEntryForStorage(entry);
 		const residentEntry = prepareEntryForResidentSync(normalizedEntry, this.#residentBlobStores()) as SessionEntry;
 		this.#fileEntries.push(residentEntry);
@@ -6835,6 +7338,7 @@ export class SessionManager {
 	 * the canonical store. This applies such mutations for real.
 	 */
 	applyEntryMessageUpdates(entries: readonly SessionMessageEntry[]): void {
+		this.#assertRecoveryHydrationWritable();
 		for (const updated of entries) {
 			const canonical = this.#byId.get(updated.id);
 			if (canonical?.type !== "message") continue;
@@ -6851,6 +7355,7 @@ export class SessionManager {
 
 	/** Write mutated custom-message entries back into the canonical entry store by id. */
 	applyCustomMessageEntryUpdates(entries: readonly CustomMessageEntry[]): void {
+		this.#assertRecoveryHydrationWritable();
 		for (const updated of entries) {
 			const canonical = this.#byId.get(updated.id);
 			if (canonical?.type !== "custom_message") continue;
@@ -6870,6 +7375,7 @@ export class SessionManager {
 	 * Use sparingly (e.g., pruning old tool outputs).
 	 */
 	async rewriteEntries(): Promise<void> {
+		this.#assertRecoveryHydrationWritable();
 		if (!this.persist || !this.#sessionFile) return;
 		await this.#rewriteFile();
 	}
@@ -7035,6 +7541,7 @@ export class SessionManager {
 	}
 
 	evictCompactedContent(firstKeptEntryId: string, compactionEntryId: string): EvictCompactedContentResult {
+		this.#assertRecoveryHydrationWritable();
 		const firstKept = this.#byId.get(firstKeptEntryId);
 		const compaction = this.#byId.get(compactionEntryId);
 		if (!firstKept) throw new Error(`Entry ${firstKeptEntryId} not found`);
@@ -7185,7 +7692,7 @@ export class SessionManager {
 			? cloneSessionEntry(
 					rehydrateColdSpillEntry(
 						materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()),
-						this.#blobStore,
+						this.#coldSpillReadStore(),
 						this.#residentBlobStoresForColdRehydrate(),
 					),
 				)
@@ -7204,7 +7711,7 @@ export class SessionManager {
 				cloneSessionEntry(
 					rehydrateColdSpillEntry(
 						materializeResidentEntryForReadSync(current, this.#residentBlobStores(), cache),
-						this.#blobStore,
+						this.#coldSpillReadStore(),
 						this.#residentBlobStoresForColdRehydrate(),
 					),
 				),
@@ -7246,7 +7753,7 @@ export class SessionManager {
 				cloneSessionEntry(
 					rehydrateColdSpillEntry(
 						materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), cache),
-						this.#blobStore,
+						this.#coldSpillReadStore(),
 						this.#residentBlobStoresForColdRehydrate(),
 					),
 				),
@@ -7412,7 +7919,7 @@ export class SessionManager {
 		const materialized = materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map());
 		const rehydrated = rehydrateColdSpillEntry(
 			materialized,
-			this.#blobStore,
+			this.#coldSpillReadStore(),
 			this.#residentBlobStoresForColdRehydrate(),
 		);
 		if (rehydrated !== materialized) this.#coldSpillReadCount += this.#countColdSpillPayloads(entry);
@@ -7428,6 +7935,7 @@ export class SessionManager {
 	}
 	/** Strip stale OpenAI Responses assistant replay metadata from loaded in-memory entries without persisting it. */
 	sanitizeLoadedOpenAIResponsesReplayMetadata(): boolean {
+		this.#assertRecoveryHydrationWritable();
 		return this.#sanitizeLoadedOpenAIResponsesReplayMetadata().length > 0;
 	}
 
@@ -7583,6 +8091,7 @@ export class SessionManager {
 	 * are not modified or deleted.
 	 */
 	branch(branchFromId: string): void {
+		this.#assertRecoveryHydrationWritable();
 		if (!this.#byId.has(branchFromId)) {
 			throw new Error(`Entry ${branchFromId} not found`);
 		}
@@ -7596,6 +8105,7 @@ export class SessionManager {
 	 * Use this when navigating to re-edit the first user message.
 	 */
 	resetLeaf(): void {
+		this.#assertRecoveryHydrationWritable();
 		this.#leafId = null;
 		this.#leafRevision++;
 	}
@@ -7606,6 +8116,7 @@ export class SessionManager {
 	 * context from the abandoned conversation path.
 	 */
 	branchWithSummary(branchFromId: string | null, summary: string, details?: unknown, fromExtension?: boolean): string {
+		this.#assertRecoveryHydrationWritable();
 		if (branchFromId !== null && !this.#byId.has(branchFromId)) {
 			throw new Error(`Entry ${branchFromId} not found`);
 		}
@@ -7630,6 +8141,7 @@ export class SessionManager {
 	 * Returns the new session file path, or undefined if not persisting.
 	 */
 	createBranchedSession(leafId: string): string | undefined {
+		this.#assertRecoveryHydrationWritable();
 		const previousSessionFile = this.#sessionFile;
 		const branchPath = this.#getCanonicalBranchClones(leafId);
 		if (branchPath.length === 0) {
@@ -8112,10 +8624,11 @@ export class SessionManager {
 		if (resolved.kind === "error") return [];
 		const listing = listManagedCandidates(resolved.scope);
 		if (listing.kind === "error") return [];
-		return await collectSessionsFromFiles(
+		const managed = await collectSessionsFromFiles(
 			listing.owned.map(candidate => candidate.path),
 			storage,
 		);
+		return mergeSessionInventories(managed, await collectProjectSessions(cwd, storage));
 	}
 
 	/**
@@ -8136,12 +8649,35 @@ export class SessionManager {
 		}
 	}
 
-	/** Tombstone and exact-delete a default-managed candidate. */
+	/** Delete an authorized managed or project-local picker candidate. */
 	static async deleteManagedCandidate(sessionPath: string): Promise<void> {
 		const storage = new FileSessionStorage();
 		const entries = await loadEntriesFromFile(sessionPath, storage);
 		const header = entries.find(entry => entry.type === "session") as SessionHeader | undefined;
-		if (!header?.cwd) throw new Error("Session has no valid managed workspace header.");
+		if (!header?.cwd) throw new Error("Session has no valid workspace header.");
+		const projectGjcDir = path.join(path.resolve(header.cwd), ".gjc");
+		if (isProjectSessionTranscriptPath(projectGjcDir, sessionPath)) {
+			const relativePath = path.relative(projectGjcDir, path.resolve(sessionPath)).split(path.sep).join("/");
+			const authority = native.openRecoveryFsRoot(projectGjcDir);
+			try {
+				const captured = authority.readManaged(relativePath);
+				if (!captured.ok || !captured.identity || !captured.data || !captured.identity.sha256)
+					throw new Error("Project session is no longer an authorized candidate.");
+				const removed = authority.removeManaged(
+					relativePath,
+					captured.identity.dev,
+					captured.identity.ino,
+					captured.identity.size,
+					captured.identity.mtimeNs,
+					captured.identity.ctimeNs,
+					captured.identity.sha256,
+				);
+				if (!removed.ok) throw new Error(removed.code ?? "Could not delete project session.");
+				return;
+			} finally {
+				authority.close();
+			}
+		}
 		const sessionsRoot = path.resolve(sessionPath, "../..");
 		const resolved = resolveManagedScope({
 			cwd: header.cwd,
@@ -8349,6 +8885,194 @@ export class SessionManager {
 		}
 	}
 
+	static async restoreMemoryGuardCheckpoint(input: MemoryGuardRestoreInput): Promise<MemoryGuardRestoreResult> {
+		try {
+			assertMemoryGuardSessionId(input.checkpoint.session_id);
+		} catch {
+			return { kind: "blocked", reason: "checkpoint-mismatch" };
+		}
+		if (!validateMemoryGuardCheckpoint(input.checkpoint)) return { kind: "blocked", reason: "checkpoint-mismatch" };
+		if (!memoryGuardParticipantMatchesCheckpoint(input.participant, input.checkpoint)) {
+			return { kind: "blocked", reason: "participant-mismatch" };
+		}
+		const checkpointText = readCheckpointAuthorityFile(
+			input.incidentAuthority,
+			memoryGuardParticipantRelativePath(input.checkpoint.session_id, "session-manager.json"),
+			256 * 1024,
+		);
+		if (!checkpointText) return { kind: "blocked", reason: "checkpoint-mismatch" };
+		const checkpointCanonical = memoryGuardCanonicalJson(input.checkpoint);
+		if (decodeCheckpointUtf8(checkpointText) !== checkpointCanonical) {
+			return { kind: "blocked", reason: "checkpoint-mismatch" };
+		}
+		const transcriptBytes = Number(input.checkpoint.transcript.bytes);
+		if (!Number.isSafeInteger(transcriptBytes) || transcriptBytes < 0) {
+			return { kind: "blocked", reason: "transcript-mismatch" };
+		}
+		const transcriptData = readCheckpointAuthorityFile(
+			input.incidentAuthority,
+			input.checkpoint.transcript.relative_path,
+			transcriptBytes + 1,
+		);
+		if (!transcriptData || transcriptData.byteLength !== transcriptBytes) {
+			return { kind: "blocked", reason: "transcript-mismatch" };
+		}
+		if (memoryGuardSha256Hex(transcriptData) !== input.checkpoint.transcript.sha256) {
+			return { kind: "blocked", reason: "transcript-mismatch" };
+		}
+		const transcriptText = decodeCheckpointUtf8(transcriptData);
+		if (transcriptText === null) return { kind: "blocked", reason: "transcript-mismatch" };
+		let transcriptEntries: FileEntry[];
+		try {
+			transcriptEntries = parseSessionEntries(transcriptText);
+		} catch {
+			return { kind: "blocked", reason: "malformed" };
+		}
+		const transcriptHeader = transcriptEntries[0] as SessionHeader | undefined;
+		if (
+			transcriptHeader?.type !== "session" ||
+			transcriptHeader.id !== input.checkpoint.session_id ||
+			(transcriptHeader.title ?? null) !== input.checkpoint.session_name
+		) {
+			return { kind: "blocked", reason: "transcript-mismatch" };
+		}
+		const manifestData = readCheckpointAuthorityFile(
+			input.incidentAuthority,
+			input.checkpoint.blob_authority.manifest_relative_path,
+			8 * 1024 * 1024,
+		);
+		if (!manifestData) return { kind: "blocked", reason: "blob-authority-mismatch" };
+		if (memoryGuardSha256Hex(manifestData) !== input.checkpoint.blob_authority.manifest_sha256) {
+			return { kind: "blocked", reason: "blob-authority-mismatch" };
+		}
+		const manifestText = decodeCheckpointUtf8(manifestData);
+		if (manifestText === null) return { kind: "blocked", reason: "blob-manifest-mismatch" };
+		let blobManifest: unknown;
+		try {
+			blobManifest = JSON.parse(manifestText);
+		} catch {
+			return { kind: "blocked", reason: "blob-manifest-mismatch" };
+		}
+		if (!validateMemoryGuardBlobManifest(blobManifest)) return { kind: "blocked", reason: "blob-manifest-mismatch" };
+		if (memoryGuardCanonicalJson(blobManifest) !== manifestText)
+			return { kind: "blocked", reason: "blob-manifest-mismatch" };
+		if (blobManifest.entries.length > MEMORY_GUARD_CHECKPOINT_BLOB_MAX_ENTRIES)
+			return { kind: "blocked", reason: "blob-manifest-mismatch" };
+		let checkpointBlobBytes = 0;
+		const seenBlobPaths = new Set<string>();
+		const checkpointBlobs = new Map<string, Buffer>();
+		for (const entry of blobManifest.entries) {
+			if (
+				entry.relative_path !== entry.sha256 ||
+				seenBlobPaths.has(entry.relative_path) ||
+				checkpointBlobs.has(entry.sha256)
+			)
+				return { kind: "blocked", reason: "blob-manifest-mismatch" };
+			seenBlobPaths.add(entry.relative_path);
+			const blobBytes = Number(entry.bytes);
+			if (!Number.isSafeInteger(blobBytes) || blobBytes < 0)
+				return { kind: "blocked", reason: "blob-manifest-mismatch" };
+			checkpointBlobBytes += blobBytes;
+			if (checkpointBlobBytes > MEMORY_GUARD_CHECKPOINT_BLOB_TOTAL_MAX_BYTES)
+				return { kind: "blocked", reason: "blob-manifest-mismatch" };
+			const blobPath = `${input.checkpoint.blob_authority.root_relative_path}/${entry.relative_path}`;
+			const blobData = readCheckpointAuthorityFile(input.incidentAuthority, blobPath, blobBytes + 1);
+			if (!blobData || blobData.byteLength !== blobBytes) return { kind: "blocked", reason: "blob-missing" };
+			if (memoryGuardSha256Hex(blobData) !== entry.sha256) return { kind: "blocked", reason: "blob-hash-mismatch" };
+			checkpointBlobs.set(entry.sha256, Buffer.from(blobData));
+		}
+		for (const ref of collectCheckpointBlobRefs(transcriptEntries)) {
+			const hash = parseBlobRef(ref);
+			if (!hash || !checkpointBlobs.has(hash)) return { kind: "blocked", reason: "blob-manifest-mismatch" };
+		}
+		const storage = new FileSessionStorage();
+		let destination: SessionDestination;
+		try {
+			destination =
+				input.destination === undefined
+					? explicitDestination(path.join(os.tmpdir(), `gjc-memory-guard-${input.checkpoint.session_id}`))
+					: destinationFor(getProjectDir(), input.destination, storage);
+		} catch {
+			return { kind: "blocked", reason: "destination-unavailable" };
+		}
+		const transcriptPath = path.join(
+			destination.directory,
+			`.${input.checkpoint.session_id}.memory-guard.${crypto.randomUUID()}.jsonl`,
+		);
+		const transcriptName = path.basename(transcriptPath);
+		const managedStagingStore =
+			destination.kind === "managed"
+				? managedStoreFromContext(destination.securityContext, destination.directory)
+				: undefined;
+		const cleanupTranscript = async (): Promise<void> => {
+			if (managedStagingStore) {
+				await managedStagingStore.remove(transcriptName);
+				return;
+			}
+			await fs.promises.rm(transcriptPath, { force: true });
+		};
+		let opened: RecoveryHydrationOpenResult;
+		let transcriptIdentity: ResumeSessionIdentity;
+		let createdDestination: CreatedDirectoryIdentity | undefined;
+		try {
+			if (managedStagingStore) await managedStagingStore.publishNoReplace(transcriptName, transcriptData);
+			else {
+				createdDestination = await ensureOwnerOnlyDirectoryTracked(destination.directory);
+				await writeOwnerOnlyFileNoReplace(transcriptPath, transcriptData);
+			}
+			const captured = SessionManager.captureTranscriptStrict(transcriptPath, storage);
+			if (captured.kind !== "captured") {
+				await cleanupTranscript();
+				await removeCreatedDirectoryIfEmpty(destination.directory, createdDestination);
+				return { kind: "blocked", reason: captured.reason };
+			}
+			transcriptIdentity = captured.snapshot.identity;
+			opened = await SessionManager.openExistingForRecoveryHydrationStrict(
+				transcriptIdentity,
+				input.destination,
+				storage,
+			);
+		} catch {
+			await cleanupTranscript();
+			await removeCreatedDirectoryIfEmpty(destination.directory, createdDestination);
+			return { kind: "blocked", reason: "destination-unavailable" };
+		}
+		if (opened.kind === "error") {
+			await cleanupTranscript();
+			await removeCreatedDirectoryIfEmpty(destination.directory, createdDestination);
+			return { kind: "blocked", reason: opened.reason };
+		}
+		if (
+			opened.manager.getSessionId() !== input.checkpoint.session_id ||
+			(opened.manager.getSessionName() ?? null) !== input.checkpoint.session_name
+		) {
+			await opened.manager.close();
+			await cleanupTranscript();
+			await removeCreatedDirectoryIfEmpty(destination.directory, createdDestination);
+			return { kind: "blocked", reason: "transcript-mismatch" };
+		}
+		opened.manager.#stageMemoryGuardCheckpointBlobs(checkpointBlobs);
+		opened.manager.#recoveryPromotionTranscriptPath = path.join(
+			destination.directory,
+			`${new Date().toISOString().replace(/[:.]/g, "-")}_${input.checkpoint.session_id}.jsonl`,
+		);
+		let cleanupConsumed = false;
+		const cleanup = async (): Promise<void> => {
+			if (cleanupConsumed) return;
+			await opened.manager.close();
+			await cleanupTranscript();
+			await removeCreatedDirectoryIfEmpty(destination.directory, createdDestination);
+			cleanupConsumed = true;
+		};
+		return {
+			kind: "staged",
+			manager: opened.manager,
+			hydrationContext: opened.context,
+			transcriptIdentity,
+			cleanup,
+		};
+	}
+
 	/** Inspect a selected session without acquiring write-capable ownership. */
 	static async inspectSessionTailReadOnly(
 		filePath: string,
@@ -8417,8 +9141,31 @@ export class SessionManager {
 		if ("kind" in inspected || !sameResumeIdentity(context.identity, inspected.identity)) {
 			throw new Error("Recovery transcript authority changed before promotion.");
 		}
+		if (this.#memoryGuardCheckpointBlobs) {
+			for (const blob of this.#memoryGuardCheckpointBlobs.values()) this.#blobStore.putImmutableSync(blob);
+			this.#residentImageBlobStore = this.#blobStore;
+			this.#memoryGuardCheckpointBlobs = undefined;
+		}
 		await this.#sanitizeLoadedOpenAIResponsesReplayMetadataAndPersist();
-		writeTerminalBreadcrumb(this.cwd, context.identity.canonicalPath);
+		const promotionPath = this.#recoveryPromotionTranscriptPath;
+		if (!promotionPath) throw new Error("Recovery transcript promotion path is unavailable.");
+		const promotedSource = inspectResumeSessionFile(context.identity.canonicalPath, this.storage);
+		if ("kind" in promotedSource) throw new Error("Recovery transcript became unavailable before publication.");
+		if (this.destination.kind === "managed") {
+			const store = this.#managedTranscriptStore();
+			const sourceName = path.basename(context.identity.canonicalPath);
+			const sourceSnapshot = store.readExpected(sourceName);
+			if (!sourceSnapshot) throw new Error("Recovery transcript authority changed before publication.");
+			await store.publishNoReplace(path.basename(promotionPath), promotedSource.content);
+			store.removeExpected(sourceName, sourceSnapshot);
+		} else {
+			await writeOwnerOnlyFileNoReplace(promotionPath, promotedSource.content);
+			await fs.promises.rm(context.identity.canonicalPath, { force: true });
+			await fsyncDirectoryPath(path.dirname(context.identity.canonicalPath));
+		}
+		this.#sessionFile = promotionPath;
+		this.#recoveryPromotionTranscriptPath = undefined;
+		writeTerminalBreadcrumb(this.cwd, promotionPath);
 		this.#recoveryHydrationContext = undefined;
 	}