@gajae-code/coding-agent 0.11.1 → 0.11.2

package/src/session/session-manager.ts

@@ -14,6 +14,7 @@ import type {
 	TextContent,
 	Usage,
 } from "@gajae-code/ai";
+import * as native from "@gajae-code/natives";
 import { getTerminalId } from "@gajae-code/tui";
 import {
 	getBlobsDir,
@@ -52,6 +53,16 @@ import {
 	resolveResidentImageDataUrlSync,
 	resolveTextBlobSync,
 } from "./blob-store";
+import {
+	canonicalizeTrustedPath,
+	deleteManagedSessionCandidate,
+	listManagedCandidates,
+	type ManagedMigrationPolicy,
+	openManagedCandidateForWrite,
+	prepareManagedSessionScopeForWriteSync,
+	resolveManagedScope,
+} from "./internal/managed-session-scope";
+
 import {
 	type BashExecutionMessage,
 	type CustomMessage,
@@ -64,6 +75,7 @@ import {
 	sanitizeRehydratedOpenAIResponsesAssistantMessage,
 	stripInternalDetailsFields,
 } from "./messages";
+import { type SessionManagerReadAccess, sessionManagerReadCapability } from "./session-manager-internal";
 import type {
 	SessionStorage,
 	SessionStorageSnapshot,
@@ -75,7 +87,14 @@ import type {
 } from "./session-storage";
 import { FileSessionStorage, MemorySessionStorage } from "./session-storage";
 
-export const CURRENT_SESSION_VERSION = 3;
+export const CURRENT_SESSION_VERSION = 4;
+
+/**
+ * Version 4 adds append-only patch records. New writers emit v4 headers; v1–v3
+ * transcripts remain readable. Older builds do not apply these records, so they
+ * must not be used to edit a session after a v4 writer has updated it.
+ */
+
 function isUnderProjectGjc(cwd: string, targetPath: string): boolean {
 	const relative = path.relative(path.join(path.resolve(cwd), ".gjc"), path.resolve(targetPath));
 	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
@@ -187,6 +206,15 @@ export function getSessionMessageViewportAnchorId(message: AgentMessage): string
 	return sessionMessageViewportAnchorIds.get(message);
 }
 
+/** Returns registered viewport anchors for durable user messages in session order. */
+export function getUserMessageViewportAnchorIds(messages: readonly AgentMessage[]): string[] {
+	return messages.flatMap(message => {
+		if (message.role !== "user" || message.synthetic) return [];
+		const anchorId = getSessionMessageViewportAnchorId(message);
+		return anchorId ? [anchorId] : [];
+	});
+}
+
 export function transferSessionMessageIdentity(source: AgentMessage[], target: AgentMessage[]): void {
 	if (source.length !== target.length) {
 		throw new Error(
@@ -365,7 +393,22 @@ export type SessionEntry =
 	| ModeChangeEntry
 	| ConfiguredModelChainEntry;
 
-/** Raw file entry (includes header) */
+/** Append-only replacement for mutable fields on the session header. */
+export interface HeaderPatchRecord {
+	type: "header_patch";
+	patch: Partial<Pick<SessionHeader, "title" | "titleSource" | "cwd">>;
+}
+
+/** Append-only replacement for replay metadata on one existing session entry. */
+export interface EntryPatchRecord {
+	type: "entry_patch";
+	entryId: string;
+	patch: Partial<Pick<SessionMessageEntry, "message">>;
+}
+
+export type SessionPatchRecord = HeaderPatchRecord | EntryPatchRecord;
+
+/** Resolved file entries; patch records are applied by parseSessionEntries(). */
 export type FileEntry = SessionHeader | SessionEntry;
 
 export type DefaultModelSelectionStage = {
@@ -445,11 +488,32 @@ export interface ResumeTailTerminal {
 
 export interface ResumeTailError {
 	kind: "error";
-	reason: "missing" | "malformed" | "unstable" | "read-failed";
+	reason: "missing" | "malformed" | "unstable" | "read-failed" | "legacy_migration_disabled";
 }
 
-export type ResumeTailInspection = ResumeTailResumable | ResumeTailTerminal | ResumeTailError;
+export type SessionDirectoryMigrationPolicy = ManagedMigrationPolicy;
+
+export class SessionManagedStorageError extends Error {
+	readonly code = "managed_storage_unsupported";
+
+	constructor() {
+		super(
+			"Default managed session storage requires FileSessionStorage; provide an explicit session directory for custom storage.",
+		);
+		this.name = "SessionManagedStorageError";
+	}
+}
+
+export class SessionMigrationPolicyError extends Error {
+	readonly code = "legacy_migration_disabled";
+
+	constructor() {
+		super("Legacy session migration is disabled for this workspace.");
+		this.name = "SessionMigrationPolicyError";
+	}
+}
 
+export type ResumeTailInspection = ResumeTailResumable | ResumeTailTerminal | ResumeTailError;
 export interface StrictSessionOpenSuccess {
 	kind: "opened";
 	manager: SessionManager;
@@ -488,6 +552,8 @@ export interface SessionInfo {
 	created: Date;
 	modified: Date;
 	messageCount: number;
+	/** True when messageCount was counted from only the bounded list prefix. */
+	messageCountIsEstimate?: boolean;
 	/** File size in bytes on disk; used for compact list rendering. */
 	size: number;
 	firstMessage: string;
@@ -544,30 +610,100 @@ export type SessionManagerCloseOutcome =
 	| { kind: "close_failed_retryable"; error: Error }
 	| { kind: "close_unknown"; error: Error };
 
-export type ReadonlySessionManager = Pick<
-	SessionManager,
-	| "getCwd"
-	| "getSessionDir"
-	| "getSessionId"
-	| "getSessionFile"
-	| "getSessionName"
-	| "getArtifactsDir"
-	| "getArtifactManager"
-	| "allocateArtifactPath"
-	| "saveArtifact"
-	| "getArtifactPath"
-	| "getLeafId"
-	| "getLeafEntry"
-	| "getEntry"
-	| "getLabel"
-	| "getBranch"
-	| "getHeader"
-	| "getEntries"
-	| "getTree"
-	| "getUsageStatistics"
-	| "putBlob"
+/** Read-only session state made available to extensions and custom tools. */
+/** Frozen read-only session facade made available to extensions and custom tools. */
+export interface ReadonlySessionManager {
+	getCwd(): string;
+	getSessionDir(): string;
+	getSessionId(): string;
+	getSessionFile(): string | undefined;
+	getSessionName(): string | undefined;
+	getArtifactsDir(): string | null;
+	getArtifactPath(id: string): Promise<string | null>;
+	getLeafId(): string | null;
+	getLeafEntry(): SessionEntry | undefined;
+	getEntry(id: string): SessionEntry | undefined;
+	getLabel(id: string): string | undefined;
+	getBranch(fromId?: string): SessionEntry[];
+	getHeader(): SessionHeader | null;
+	getEntries(): SessionEntry[];
+	getTree(): SessionTreeNode[];
+	getUsageStatistics(): UsageStatistics;
+}
+
+function cloneAndFreezeSnapshot<T>(value: T): T {
+	const cloned = cloneJsonSemantic(value);
+	const freeze = (candidate: unknown, seen = new WeakSet<object>()): void => {
+		if (candidate === null || typeof candidate !== "object" || seen.has(candidate)) return;
+		seen.add(candidate);
+		for (const child of Object.values(candidate)) freeze(child, seen);
+		Object.freeze(candidate);
+	};
+	freeze(cloned);
+	return cloned;
+}
+
+/** Creates an immutable facade that never exposes SessionManager mutation authority. */
+export function createReadonlySessionManager(manager: SessionManager): ReadonlySessionManager {
+	const facade = Object.freeze({
+		getCwd: () => manager.getCwd(),
+		getSessionDir: () => manager.getSessionDir(),
+		getSessionId: () => manager.getSessionId(),
+		getSessionFile: () => manager.getSessionFile(),
+		getSessionName: () => manager.getSessionName(),
+		getArtifactsDir: () => manager.getArtifactsDir(),
+		getArtifactPath: (id: string) => manager.getArtifactPath(id),
+		getLeafId: () => manager.getLeafId(),
+		getLeafEntry: () => {
+			const entry = manager.getLeafEntry();
+			return entry === undefined ? undefined : cloneAndFreezeSnapshot(entry);
+		},
+		getEntry: (id: string) => {
+			const entry = manager.getEntry(id);
+			return entry === undefined ? undefined : cloneAndFreezeSnapshot(entry);
+		},
+		getLabel: (id: string) => manager.getLabel(id),
+		getBranch: (fromId?: string) => cloneAndFreezeSnapshot(manager.getBranch(fromId)),
+		getHeader: () => {
+			const header = manager.getHeader();
+			return header === null ? null : cloneAndFreezeSnapshot(header);
+		},
+		getEntries: () => cloneAndFreezeSnapshot(manager.getEntries()),
+		getTree: () => cloneAndFreezeSnapshot(manager.getTree()),
+		getUsageStatistics: () => cloneAndFreezeSnapshot(manager.getUsageStatistics()),
+	});
+	readonlySessionArtifactCapabilities.set(facade, sessionArtifactCapability(manager)!);
+	return facade;
+}
+
+/** Internal artifact-writing capability. Read-only facades expose it only through a private weak-map lookup. */
+export type SessionArtifactCapability = Readonly<
+	Pick<SessionManager, "allocateArtifactPath" | "saveArtifact" | "putBlob">
 >;
 
+const sessionArtifactCapabilities = new WeakMap<SessionManager, SessionArtifactCapability>();
+const readonlySessionArtifactCapabilities = new WeakMap<ReadonlySessionManager, SessionArtifactCapability>();
+
+/**
+ * Returns the artifact capability for a concrete persistence owner or one of its
+ * immutable read-only facades. Structural lookalikes remain unauthorized.
+ */
+export function sessionArtifactCapability(value: unknown): SessionArtifactCapability | undefined {
+	if (value instanceof SessionManager) {
+		let capability = sessionArtifactCapabilities.get(value);
+		if (!capability) {
+			capability = Object.freeze({
+				allocateArtifactPath: value.allocateArtifactPath.bind(value),
+				saveArtifact: value.saveArtifact.bind(value),
+				putBlob: value.putBlob.bind(value),
+			});
+			sessionArtifactCapabilities.set(value, capability);
+		}
+		return capability;
+	}
+	if (value === null || typeof value !== "object") return undefined;
+	return readonlySessionArtifactCapabilities.get(value as ReadonlySessionManager);
+}
 function createSessionId(): string {
 	return Bun.randomUUIDv7();
 }
@@ -643,18 +779,17 @@ function migrateV2ToV3(entries: FileEntry[]): void {
 }
 
 /**
- * Run all necessary migrations to bring entries to current version.
- * Mutates entries in place. Returns true if any migration was applied.
+ * Run all necessary migrations to bring entries to the current semantic version.
+ * Version 4 adds trailing patch records, so v3 transcripts must be atomically upgraded before they can receive one.
  */
 function migrateToCurrentVersion(entries: FileEntry[]): boolean {
 	const header = entries.find(e => e.type === "session") as SessionHeader | undefined;
 	const version = header?.version ?? 1;
-
 	if (version >= CURRENT_SESSION_VERSION) return false;
-
 	if (version < 2) migrateV1ToV2(entries);
 	if (version < 3) migrateV2ToV3(entries);
-
+	const migratedHeader = entries.find(entry => entry.type === "session") as SessionHeader | undefined;
+	if (migratedHeader) migratedHeader.version = CURRENT_SESSION_VERSION;
 	return true;
 }
 
@@ -663,131 +798,75 @@ export function migrateSessionEntries(entries: FileEntry[]): void {
 	migrateToCurrentVersion(entries);
 }
 
-const migratedSessionRoots = new Set<string>();
-
-/**
- * Merge or rename a legacy session directory into its canonical target.
- * Best effort: callers decide whether migration failures should surface.
- */
-function migrateSessionDirPath(oldPath: string, newPath: string): void {
-	// Session-dir lifecycle migration: moves/removes whole directories, not file content writes.
-	const existing = fs.statSync(newPath, { throwIfNoEntry: false });
-	if (existing?.isDirectory()) {
-		for (const file of fs.readdirSync(oldPath)) {
-			const src = path.join(oldPath, file);
-			const dst = path.join(newPath, file);
-			if (!fs.existsSync(dst)) {
-				fs.renameSync(src, dst);
-			}
-		}
-		fs.rmSync(oldPath, { recursive: true, force: true });
-		return;
-	}
-	if (existing) {
-		fs.rmSync(newPath, { recursive: true, force: true });
-	}
-	fs.renameSync(oldPath, newPath);
-}
-
-function encodeLegacyAbsoluteSessionDirName(cwd: string): string {
-	const resolvedCwd = path.resolve(cwd);
-	return `--${resolvedCwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
-}
-
-function encodeRelativeSessionDirName(prefix: string, root: string, cwd: string): string {
-	const relative = path.relative(root, cwd).replace(/[/\\:]/g, "-");
-	return relative ? (prefix.endsWith("-") ? `${prefix}${relative}` : `${prefix}-${relative}`) : prefix;
-}
-
-function getDefaultSessionDirName(cwd: string): { encodedDirName: string; resolvedCwd: string } {
-	const resolvedCwd = path.resolve(cwd);
-	const canonicalCwd = resolveEquivalentPath(resolvedCwd);
-	const home = resolveEquivalentPath(os.homedir());
-	const tempRoot = resolveEquivalentPath(os.tmpdir());
-	const encodedDirName = pathIsWithin(home, canonicalCwd)
-		? encodeRelativeSessionDirName("-", home, canonicalCwd)
-		: pathIsWithin(tempRoot, canonicalCwd)
-			? encodeRelativeSessionDirName("-tmp", tempRoot, canonicalCwd)
-			: encodeLegacyAbsoluteSessionDirName(canonicalCwd);
-	return { encodedDirName, resolvedCwd };
-}
-
-/** Default and legacy directory candidates for maintenance-free resume discovery. */
-function getReadOnlyDefaultSessionDirs(cwd: string, sessionsRoot: string = getSessionsDir()): string[] {
-	const { encodedDirName, resolvedCwd } = getDefaultSessionDirName(cwd);
-	const canonicalCwd = resolveEquivalentPath(resolvedCwd);
-	return [
-		path.join(sessionsRoot, encodedDirName),
-		path.join(sessionsRoot, encodeLegacyAbsoluteSessionDirName(canonicalCwd)),
-		path.join(sessionsRoot, encodeLegacyAbsoluteSessionDirName(resolvedCwd)),
-	].filter((dir, index, dirs) => dirs.indexOf(dir) === index);
+function resolveManagedSessionRoot(sessionDir: string, cwd: string): string | undefined {
+	const sessionsRoot = path.dirname(sessionDir);
+	const resolved = resolveManagedScope({ cwd, agentDir: path.resolve(sessionsRoot, ".."), sessionsRoot });
+	if (resolved.kind === "error") return undefined;
+	return path.resolve(sessionDir) === path.resolve(resolved.scope.directoryPath) ? sessionsRoot : undefined;
 }
 
-/**
- * Migrate old `--<home-encoded>-*--` session dirs to the new `-*` format.
- * Runs once per sessions root on first access, best-effort.
- */
-function migrateHomeSessionDirs(sessionsRoot: string): void {
-	if (migratedSessionRoots.has(sessionsRoot)) return;
-	migratedSessionRoots.add(sessionsRoot);
-
-	const home = os.homedir();
-	const homeEncoded = home.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-");
-	const oldPrefix = `--${homeEncoded}-`;
-	const oldExact = `--${homeEncoded}--`;
-
-	let entries: string[];
-	try {
-		entries = fs.readdirSync(sessionsRoot);
-	} catch {
-		return;
-	}
-
-	for (const entry of entries) {
-		let remainder: string;
-		if (entry === oldExact) {
-			remainder = "";
-		} else if (entry.startsWith(oldPrefix) && entry.endsWith("--")) {
-			remainder = entry.slice(oldPrefix.length, -2);
-		} else {
+/** Exported for compaction.test.ts */
+export function parseSessionEntries(content: string): FileEntry[] {
+	const records = parseJsonlLenient<FileEntry | SessionPatchRecord>(content);
+	const entries: FileEntry[] = [];
+	const entriesById = new Map<string, SessionEntry>();
+	let header: SessionHeader | undefined;
+
+	for (const record of records) {
+		// Patch records are defined only by v4 transcripts. Ignore them before a
+		// v4 header as well: a truncated or malicious prefix must not mutate a
+		// later header/entry when replay catches up.
+		if (record.type === "header_patch") {
+			if (header?.version === CURRENT_SESSION_VERSION && isHeaderPatchRecord(record))
+				applyHeaderPatch(header, record.patch);
 			continue;
 		}
-
-		const newName = remainder ? `-${remainder}` : "-";
-		const oldPath = path.join(sessionsRoot, entry);
-		const newPath = path.join(sessionsRoot, newName);
-
-		try {
-			migrateSessionDirPath(oldPath, newPath);
-		} catch {
-			// Best effort
+		if (record.type === "entry_patch") {
+			if (header?.version === CURRENT_SESSION_VERSION && isEntryPatchRecord(record)) {
+				const entry = entriesById.get(record.entryId);
+				if (entry?.type === "message" && record.patch.message) entry.message = record.patch.message;
+			}
+			continue;
 		}
+		entries.push(record);
+		if (record.type === "session") header ??= record;
+		else entriesById.set(record.id, record);
 	}
+	return entries;
 }
 
-function migrateLegacyAbsoluteSessionDir(cwd: string, sessionDir: string, sessionsRoot: string): void {
-	const legacyDir = path.join(sessionsRoot, encodeLegacyAbsoluteSessionDirName(cwd));
-	if (legacyDir === sessionDir || !fs.existsSync(legacyDir)) return;
-
-	try {
-		migrateSessionDirPath(legacyDir, sessionDir);
-	} catch {
-		// Best effort
-	}
+function isHeaderPatchRecord(record: SessionPatchRecord): record is HeaderPatchRecord {
+	if (
+		record.type !== "header_patch" ||
+		!isRecord(record.patch) ||
+		!Object.keys(record).every(key => key === "type" || key === "patch")
+	)
+		return false;
+	const keys = Object.keys(record.patch);
+	if (!keys.every(key => key === "cwd" || key === "title" || key === "titleSource")) return false;
+	const { cwd, title, titleSource } = record.patch;
+	return (
+		(cwd === undefined || typeof cwd === "string") &&
+		(title === undefined || typeof title === "string") &&
+		(titleSource === undefined || titleSource === "auto" || titleSource === "user")
+	);
 }
 
-function resolveManagedSessionRoot(sessionDir: string, cwd: string): string | undefined {
-	const currentDirName = path.basename(sessionDir);
-	const { encodedDirName } = getDefaultSessionDirName(cwd);
-	if (currentDirName !== encodedDirName && currentDirName !== encodeLegacyAbsoluteSessionDirName(cwd)) {
-		return undefined;
-	}
-	return path.dirname(sessionDir);
+function applyHeaderPatch(header: SessionHeader, patch: HeaderPatchRecord["patch"]): void {
+	if (patch.cwd !== undefined) header.cwd = patch.cwd;
+	if (patch.title !== undefined) header.title = patch.title;
+	if (patch.titleSource !== undefined) header.titleSource = patch.titleSource;
 }
 
-/** Exported for compaction.test.ts */
-export function parseSessionEntries(content: string): FileEntry[] {
-	return parseJsonlLenient<FileEntry>(content);
+function isEntryPatchRecord(record: SessionPatchRecord): record is EntryPatchRecord {
+	return (
+		record.type === "entry_patch" &&
+		typeof record.entryId === "string" &&
+		isRecord(record.patch) &&
+		Object.keys(record).every(key => key === "type" || key === "entryId" || key === "patch") &&
+		Object.keys(record.patch).every(key => key === "message") &&
+		(record.patch.message === undefined || isRecord(record.patch.message))
+	);
 }
 
 function normalizeConfiguredModelChainEntry(entry: unknown): ConfiguredModelChain | undefined {
@@ -1126,22 +1205,30 @@ function cloneSessionContext(context: SessionContext): SessionContext {
 	};
 }
 
-/**
- * Compute the default session directory for a cwd.
- * Classifies cwd by canonical location so symlink/alias paths resolve to the
- * same home-relative or temp-root directory names as their real targets.
- */
+function freezeInternalReadSnapshot<T>(value: T): T {
+	if (process.env.NODE_ENV !== "test" && process.env.NODE_ENV !== "development") return value;
+	const copy = cloneJsonSemantic(value);
+	const freeze = (item: unknown): void => {
+		if (!item || typeof item !== "object" || Object.isFrozen(item)) return;
+		for (const child of Object.values(item as Record<string, unknown>)) freeze(child);
+		Object.freeze(item);
+	};
+	freeze(copy);
+	return copy;
+}
+
+/** Resolve and prepare the default v2 session scope before any managed writer exists. */
 function computeDefaultSessionDir(
 	cwd: string,
 	storage: SessionStorage,
 	sessionsRoot: string = getSessionsDir(),
 ): string {
-	const { encodedDirName, resolvedCwd } = getDefaultSessionDirName(cwd);
-	migrateHomeSessionDirs(sessionsRoot);
-	const sessionDir = path.join(sessionsRoot, encodedDirName);
-	migrateLegacyAbsoluteSessionDir(resolvedCwd, sessionDir, sessionsRoot);
-	storage.ensureDirSync(sessionDir);
-	return sessionDir;
+	if (!(storage instanceof FileSessionStorage)) throw new SessionManagedStorageError();
+	const resolved = resolveManagedScope({ cwd, agentDir: path.resolve(sessionsRoot, ".."), sessionsRoot });
+	if (resolved.kind === "error") throw new Error(`Could not resolve managed session scope: ${resolved.message}`);
+	const prepared = prepareManagedSessionScopeForWriteSync(resolved.scope);
+	if (prepared.kind === "error") throw new Error(`Could not prepare managed session scope: ${prepared.message}`);
+	return prepared.scope.directoryPath;
 }
 
 // =============================================================================
@@ -1213,9 +1300,39 @@ async function readTerminalBreadcrumb(cwd: string): Promise<string | null> {
 			return null;
 		}
 
-		// Verify the session file still exists
-		const stat = fs.statSync(sessionFile, { throwIfNoEntry: false });
-		if (stat?.isFile()) return sessionFile;
+		const inspected = inspectResumeSessionFile(sessionFile, new FileSessionStorage());
+		if ("kind" in inspected) {
+			if (inspected.reason !== "missing") return null;
+			const sessionsRoot = getSessionsDir();
+			const resolved = resolveManagedScope({
+				cwd: breadcrumbCwd,
+				agentDir: path.resolve(sessionsRoot, ".."),
+				sessionsRoot,
+			});
+			if (resolved.kind !== "resolved") return null;
+			const listing = listManagedCandidates(resolved.scope);
+			if (listing.kind !== "complete") return null;
+			const migrated = listing.owned.filter(
+				candidate => path.basename(candidate.path) === path.basename(sessionFile),
+			);
+			return migrated.length === 1 ? migrated[0]!.path : null;
+		}
+		const header = inspected.entries[0] as SessionHeader;
+		if (resolveEquivalentPath(header.cwd) !== resolveEquivalentPath(breadcrumbCwd)) return null;
+		const sessionsRoot = getSessionsDir();
+		const resolved = resolveManagedScope({
+			cwd: header.cwd,
+			agentDir: path.resolve(sessionsRoot, ".."),
+			sessionsRoot,
+		});
+		if (resolved.kind !== "resolved") return null;
+		const listing = listManagedCandidates(resolved.scope);
+		if (listing.kind !== "complete") return null;
+		const exact = listing.owned.find(candidate => path.resolve(candidate.path) === path.resolve(sessionFile));
+		if (exact) return exact.path;
+		const byIdentity = listing.owned.find(candidate => candidate.sessionId === header.id);
+		if (byIdentity) return byIdentity.path;
+		return pathIsWithin(sessionsRoot, path.resolve(sessionFile)) ? null : path.resolve(sessionFile);
 	} catch (err) {
 		if (!isEnoent(err)) logger.debug("Terminal breadcrumb read failed", { err });
 		// Breadcrumb doesn't exist or is corrupt — fall through
@@ -1235,7 +1352,7 @@ export async function loadEntriesFromFile(
 		if (isEnoent(err)) return [];
 		throw err;
 	}
-	const entries = parseJsonlLenient<FileEntry>(content);
+	const entries = parseSessionEntries(content);
 
 	// Validate session header
 	if (entries.length === 0) return entries;
@@ -1684,11 +1801,17 @@ async function getSortedSessions(sessionDir: string, storage: SessionStorage): P
 		await Promise.all(
 			files.map(async (path: string) => {
 				try {
-					const content = await storage.readTextPrefix(path, 4096);
+					const buffer = Buffer.allocUnsafe(SESSION_LIST_PREFIX_BYTES);
+					const content = await readSessionListPrefix(path, storage, buffer);
 					const entries = parseJsonlLenient<Record<string, unknown>>(content);
 					if (entries.length === 0) return;
 					const header = entries[0] as Record<string, unknown>;
 					if (header.type !== "session" || typeof header.id !== "string") return;
+					if (header.version === CURRENT_SESSION_VERSION) {
+						for (const patch of await readSessionListTrailingPatches(path, storage, buffer)) {
+							applySessionListHeaderPatch(header as unknown as SessionListHeader, patch);
+						}
+					}
 					const mtime = storage.statSync(path).mtimeMs;
 					const firstPrompt = header.title ? undefined : extractFirstUserPrompt(entries);
 					sessions.push(new RecentSessionInfo(path, mtime, header, firstPrompt));
@@ -1725,21 +1848,223 @@ function formatTimeAgo(date: Date): string {
 	return date.toLocaleDateString();
 }
 
-async function movePathAcrossDevicesSafe(source: string, destination: string): Promise<void> {
+async function syncPathAndParent(filePath: string): Promise<void> {
+	const file = await fs.promises.open(filePath, "r");
+	try {
+		await file.sync();
+	} finally {
+		await file.close();
+	}
+	if (process.platform !== "win32") {
+		const parent = await fs.promises.open(path.dirname(filePath), "r");
+		try {
+			await parent.sync();
+		} finally {
+			await parent.close();
+		}
+	}
+}
+
+interface SessionMoveDirectoryHandle {
+	sync(): Promise<void>;
+	close(): Promise<void>;
+}
+
+export async function syncSessionMoveDirectory(
+	directory: string,
+	platform: NodeJS.Platform = process.platform,
+	openDirectory: (directory: string) => Promise<SessionMoveDirectoryHandle> = value => fs.promises.open(value, "r"),
+): Promise<void> {
+	if (platform === "win32") return;
+	const handle = await openDirectory(directory);
 	try {
-		await fs.promises.rename(source, destination);
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+
+/** Durably flush every copied file and directory before an EXDEV source removal. */
+async function syncCopiedTree(treePath: string): Promise<void> {
+	const stat = await fs.promises.lstat(treePath);
+	if (stat.isSymbolicLink()) throw new Error("Refusing to fsync a copied symbolic link during a cross-device move");
+	if (stat.isFile()) {
+		const file = await fs.promises.open(treePath, "r");
+		try {
+			await file.sync();
+		} finally {
+			await file.close();
+		}
 		return;
-	} catch (error) {
-		if (!hasFsCode(error, "EXDEV")) throw error;
 	}
-	const stat = await fs.promises.stat(source);
-	if (stat.isDirectory()) {
-		await fs.promises.cp(source, destination, { recursive: true, force: false, errorOnExist: true });
-		await fs.promises.rm(source, { recursive: true, force: false });
+	if (!stat.isDirectory()) throw new Error("Copied cross-device move contains an unsupported filesystem entry");
+	const directory = await fs.promises.opendir(treePath);
+	try {
+		for (;;) {
+			const entry = await directory.read();
+			if (entry === null) break;
+			await syncCopiedTree(path.join(treePath, entry.name));
+		}
+	} finally {
+		await directory.close();
+	}
+	if (process.platform !== "win32") {
+		const handle = await fs.promises.open(treePath, "r");
+		try {
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+	}
+}
+
+type CrossDeviceTreeIdentity = string;
+
+/** Captures content plus topology; a later capture must match before source removal. */
+async function captureCrossDeviceTreeIdentity(treePath: string): Promise<CrossDeviceTreeIdentity> {
+	const before = await fs.promises.lstat(treePath, { bigint: true });
+	if (before.isSymbolicLink()) throw new Error("Refusing to move a symbolic link across devices");
+	if (before.isFile()) {
+		const bytes = await fs.promises.readFile(treePath);
+		const after = await fs.promises.lstat(treePath, { bigint: true });
+		if (
+			before.dev !== after.dev ||
+			before.ino !== after.ino ||
+			before.size !== after.size ||
+			before.mtimeNs !== after.mtimeNs
+		)
+			throw new Error("Cross-device move source changed while its identity was captured");
+		return `file:${before.dev}:${before.ino}:${before.size}:${before.mtimeNs}:${crypto.createHash("sha256").update(bytes).digest("hex")}`;
+	}
+	if (!before.isDirectory()) throw new Error("Cross-device move contains an unsupported filesystem entry");
+	const directory = await fs.promises.opendir(treePath);
+	const entries: string[] = [];
+	try {
+		for (;;) {
+			const entry = await directory.read();
+			if (entry === null) break;
+			entries.push(entry.name);
+		}
+	} finally {
+		await directory.close();
+	}
+	entries.sort();
+	const children = await Promise.all(
+		entries.map(
+			async name => `${JSON.stringify(name)}=${await captureCrossDeviceTreeIdentity(path.join(treePath, name))}`,
+		),
+	);
+	const after = await fs.promises.lstat(treePath, { bigint: true });
+	if (
+		before.dev !== after.dev ||
+		before.ino !== after.ino ||
+		before.size !== after.size ||
+		before.mtimeNs !== after.mtimeNs
+	)
+		throw new Error("Cross-device move source topology changed while its identity was captured");
+	return `directory:${before.dev}:${before.ino}:${before.size}:${before.mtimeNs}:[${children.join(",")}]`;
+}
+
+async function removeCrossDeviceSourceIfUnchanged(source: string, expected: CrossDeviceTreeIdentity): Promise<void> {
+	if ((await captureCrossDeviceTreeIdentity(source)) !== expected)
+		throw new Error("Cross-device move source changed before removal");
+	const stat = await fs.promises.lstat(source);
+	if (stat.isDirectory()) await fs.promises.rm(source, { recursive: true, force: false });
+	else await fs.promises.unlink(source);
+}
+
+/**
+ * An EXDEV retirement must be driven by a native descriptor/handle-bound
+ * snapshot-copy-verify transaction.  Do not fall back to pathname copy/remove:
+ * that can retire a replacement after a crash or concurrent rename.
+ */
+class CrossDeviceMoveUnsupportedError extends Error {
+	constructor(source: string, destination: string, cause?: unknown) {
+		super(
+			`Cross-device session move is unavailable for ${source} -> ${destination}: native atomic detach/copy/verify support is required.`,
+			{ cause },
+		);
+		this.name = "CrossDeviceMoveUnsupportedError";
+	}
+}
+
+class PathMoveCompletedWithSyncFailure extends Error {
+	constructor(readonly cause: unknown) {
+		super("Path move completed but final source-directory sync failed.", { cause });
+	}
+}
+
+async function movePathAcrossDevicesSafe(source: string, destination: string): Promise<void> {
+	const sourceIdentity = await captureCrossDeviceTreeIdentity(source);
+	const renamed = native.renameNoReplacePath(source, destination);
+	if (renamed.ok) {
+		try {
+			if ((await captureCrossDeviceTreeIdentity(destination)) !== sourceIdentity)
+				throw new Error("Atomic session rename did not preserve the captured source identity");
+			await syncSessionMoveDirectory(path.dirname(destination));
+			if (path.dirname(source) !== path.dirname(destination)) await syncSessionMoveDirectory(path.dirname(source));
+		} catch (error) {
+			throw new PathMoveCompletedWithSyncFailure(error);
+		}
 		return;
 	}
-	await fs.promises.copyFile(source, destination, fs.constants.COPYFILE_EXCL);
-	await fs.promises.unlink(source);
+	if (renamed.code === "quarantine_collision") {
+		const error = new Error(`Session move destination already exists: ${destination}`) as NodeJS.ErrnoException;
+		error.code = "EEXIST";
+		throw error;
+	}
+	if (renamed.code !== "atomic_unavailable")
+		throw new Error(`Atomic session rename failed: ${renamed.code ?? "unknown"}`);
+	const sourceStat = await fs.promises.lstat(source);
+	if (!sourceStat.isDirectory()) {
+		let destinationCreated = false;
+		let sourceRemoved = false;
+		try {
+			try {
+				await fs.promises.link(source, destination);
+				destinationCreated = true;
+			} catch (error) {
+				if (hasFsCode(error, "EXDEV")) throw new CrossDeviceMoveUnsupportedError(source, destination, error);
+				if (
+					!hasFsCode(error, "EPERM") &&
+					!hasFsCode(error, "EACCES") &&
+					!hasFsCode(error, "ENOTSUP") &&
+					!hasFsCode(error, "EOPNOTSUPP")
+				)
+					throw error;
+				await fs.promises.copyFile(source, destination, fs.constants.COPYFILE_EXCL);
+				destinationCreated = true;
+			}
+			await syncPathAndParent(destination);
+			await removeCrossDeviceSourceIfUnchanged(source, sourceIdentity);
+			sourceRemoved = true;
+			await syncSessionMoveDirectory(path.dirname(source));
+			return;
+		} catch (error) {
+			if (!sourceRemoved && destinationCreated) await fs.promises.unlink(destination).catch(() => undefined);
+			if (sourceRemoved && !(error instanceof PathMoveCompletedWithSyncFailure))
+				throw new PathMoveCompletedWithSyncFailure(error);
+			throw error;
+		}
+	}
+
+	const destinationParent = await fs.promises.lstat(path.dirname(destination));
+	if (sourceStat.dev !== destinationParent.dev) throw new CrossDeviceMoveUnsupportedError(source, destination);
+
+	try {
+		await fs.promises.cp(source, destination, { recursive: true, force: false, errorOnExist: true });
+		await syncCopiedTree(destination);
+		await removeCrossDeviceSourceIfUnchanged(source, sourceIdentity);
+		try {
+			await syncSessionMoveDirectory(path.dirname(source));
+		} catch (error) {
+			throw new PathMoveCompletedWithSyncFailure(error);
+		}
+	} catch (error) {
+		if (!(error instanceof PathMoveCompletedWithSyncFailure))
+			await fs.promises.rm(destination, { recursive: true, force: true }).catch(() => undefined);
+		throw error;
+	}
 }
 
 const MAX_PERSIST_CHARS = 500_000;
@@ -2091,19 +2416,12 @@ function cloneJsonSemantic<T>(value: T): T {
 	return cloned as T;
 }
 
-function cloneAgentMessage<T extends AgentMessage>(message: T): T {
-	const cloned = {
-		...message,
-		...("content" in message ? { content: cloneJsonSemantic(message.content) } : {}),
-		...("providerPayload" in message ? { providerPayload: cloneJsonSemantic(message.providerPayload) } : {}),
-	} as T;
-	transferSessionMessageIdentity([message], [cloned]);
-	return cloned;
-}
-
 function cloneSessionEntry(entry: SessionEntry): SessionEntry {
-	if (entry.type !== "message") return { ...entry };
-	return { ...entry, message: cloneAgentMessage(entry.message) } as SessionEntry;
+	const cloned = cloneJsonSemantic(entry);
+	if (entry.type === "message" && cloned.type === "message") {
+		transferSessionMessageIdentity([entry.message], [cloned.message]);
+	}
+	return cloned;
 }
 
 function materializeProviderVisibleEntrySync(entry: SessionEntry, stores: ResidentBlobStores): SessionEntry {
@@ -2725,7 +3043,7 @@ class NdjsonFileWriter {
 	}
 
 	/** Queue a write. Returns a promise so callers can await if needed. */
-	write(entry: FileEntry): Promise<void> {
+	write(entry: FileEntry | SessionPatchRecord): Promise<void> {
 		if (this.#closed || this.#closing) throw new Error("Writer closed");
 		if (this.#error) throw this.#error;
 		const line = `${JSON.stringify(entry)}\n`;
@@ -2741,7 +3059,7 @@ class NdjsonFileWriter {
 	 * queue. Use only when no concurrent async write is in flight (the session-manager
 	 * persist path enforces this via `#flushed`/`#needsFullRewriteOnNextPersist`).
 	 */
-	writeSync(entry: FileEntry): void {
+	writeSync(entry: FileEntry | SessionPatchRecord): void {
 		if (this.#closed || this.#closing) throw new Error("Writer closed");
 		if (this.#error) throw this.#error;
 		const line = `${JSON.stringify(entry)}\n`;
@@ -2936,6 +3254,14 @@ function extractTextFromContent(content: Message["content"]): string {
 }
 
 const SESSION_LIST_PREFIX_BYTES = 4096;
+const SESSION_LIST_TRAILING_PATCH_BYTES = 4096;
+// Hard cap on how many trailing bytes the listers may scan for header patches.
+// moveTo folds cwd patches into line 1 via a full atomic rewrite, so only a
+// recent title patch can live unfolded near EOF; anything buried deeper is
+// folded on the next natural full rewrite. Keeping this bounded preserves the
+// O(SESSION_LIST_PREFIX_BYTES) listing cost that SESSION_LIST_PREFIX_BYTES exists for.
+const SESSION_LIST_TRAILING_PATCH_SCAN_CAP = SESSION_LIST_TRAILING_PATCH_BYTES * 4;
+const SESSION_NAME_MAX_CHARS = 1_000;
 const SESSION_LIST_PARALLEL_THRESHOLD = 64;
 const SESSION_LIST_MAX_WORKERS = 16;
 const sessionListPrefixDecoder = new TextDecoder("utf-8", { fatal: false });
@@ -2955,6 +3281,69 @@ async function readSessionListPrefix(file: string, storage: SessionStorage, buff
 	}
 }
 
+async function readSessionListTrailingPatches(
+	file: string,
+	storage: SessionStorage,
+	buffer: Buffer,
+): Promise<HeaderPatchRecord["patch"][]> {
+	if (!(storage instanceof FileSessionStorage)) {
+		const content = await storage.readText(file);
+		const entries = parseSessionEntries(content);
+		const header = entries[0] as SessionHeader | undefined;
+		return header?.type === "session" ? [{ cwd: header.cwd, title: header.title }] : [];
+	}
+
+	const size = storage.statSync(file).size;
+	if (size <= SESSION_LIST_PREFIX_BYTES) return [];
+	const latest: HeaderPatchRecord["patch"] = {};
+	let position = size;
+	const scanFloor = Math.max(0, size - SESSION_LIST_TRAILING_PATCH_SCAN_CAP);
+	let trailingFragment = Buffer.alloc(0);
+	const chunkSize = Math.min(buffer.byteLength, SESSION_LIST_TRAILING_PATCH_BYTES);
+	const handle = await fs.promises.open(file, "r");
+	try {
+		while (position > scanFloor && (latest.cwd === undefined || latest.title === undefined)) {
+			const start = Math.max(0, position - chunkSize);
+			const length = position - start;
+			const { bytesRead } = await handle.read(buffer, 0, length, start);
+			const combined = Buffer.concat([buffer.subarray(0, bytesRead), trailingFragment]);
+			let complete = combined;
+			if (start > 0) {
+				const firstNewline = combined.indexOf(0x0a);
+				if (firstNewline === -1) {
+					trailingFragment = combined;
+					position = start;
+					continue;
+				}
+				trailingFragment = combined.subarray(0, firstNewline);
+				complete = combined.subarray(firstNewline + 1);
+			}
+			const lines = complete.toString("utf8").split("\n");
+			for (let index = lines.length - 1; index >= 0; index--) {
+				const line = lines[index];
+				if (!line) continue;
+				try {
+					const record = JSON.parse(line) as SessionPatchRecord;
+					if (!isHeaderPatchRecord(record)) continue;
+					if (latest.cwd === undefined && typeof record.patch.cwd === "string") latest.cwd = record.patch.cwd;
+					if (latest.title === undefined && typeof record.patch.title === "string")
+						latest.title = record.patch.title;
+				} catch {
+					// Ignore malformed or partial records exactly as the canonical loader does.
+				}
+			}
+			position = start;
+		}
+		return latest.cwd === undefined && latest.title === undefined ? [] : [latest];
+	} finally {
+		await handle.close();
+	}
+}
+
+function applySessionListHeaderPatch(header: SessionListHeader, patch: HeaderPatchRecord["patch"]): void {
+	if (typeof patch.cwd === "string") header.cwd = patch.cwd;
+	if (typeof patch.title === "string") header.title = patch.title;
+}
 function decodeJsonStringFragment(value: string): string {
 	const safeValue = value.endsWith("\\") ? value.slice(0, -1) : value;
 	try {
@@ -3038,6 +3427,8 @@ function extractFirstUserMessageFromPrefix(content: string): string | undefined
 interface SessionListHeader {
 	type: "session";
 	id: string;
+	version?: number;
+
 	cwd?: string;
 	title?: string;
 	parentSession?: string;
@@ -3053,6 +3444,7 @@ function parseSessionListHeader(
 		return {
 			type: "session",
 			id: parsedHeader.id,
+			version: typeof parsedHeader.version === "number" ? parsedHeader.version : undefined,
 			cwd: typeof parsedHeader.cwd === "string" ? parsedHeader.cwd : undefined,
 			title: typeof parsedHeader.title === "string" ? parsedHeader.title : undefined,
 			parentSession: typeof parsedHeader.parentSession === "string" ? parsedHeader.parentSession : undefined,
@@ -3070,6 +3462,7 @@ function parseSessionListHeader(
 	return {
 		type: "session",
 		id,
+		version: Number(extractStringProperty(firstLine, "version")) || undefined,
 		cwd: extractStringProperty(firstLine, "cwd"),
 		title: extractStringProperty(firstLine, "title"),
 		parentSession: extractStringProperty(firstLine, "parentSession"),
@@ -3093,9 +3486,14 @@ async function collectSessionFromFile(
 ): Promise<SessionInfo | undefined> {
 	try {
 		const content = await readSessionListPrefix(file, storage, buffer);
-		const entries = parseJsonlLenient<Record<string, unknown>>(content);
+		const entries = parseSessionEntries(content).map(entry => entry as unknown as Record<string, unknown>);
 		const header = parseSessionListHeader(content, entries);
 		if (!header) return undefined;
+		if (header.version === CURRENT_SESSION_VERSION) {
+			for (const patch of await readSessionListTrailingPatches(file, storage, buffer)) {
+				applySessionListHeaderPatch(header, patch);
+			}
+		}
 
 		let parsedMessageCount = 0;
 		let firstMessage = "";
@@ -3138,6 +3536,7 @@ async function collectSessionFromFile(
 			created: new Date(header.timestamp ?? ""),
 			modified: stats.mtime,
 			messageCount,
+			messageCountIsEstimate: stats.size > SESSION_LIST_PREFIX_BYTES,
 			size: stats.size,
 			firstMessage: firstMessage || "(no messages)",
 			allMessagesText: allMessages.length > 0 ? allMessages.join(" ") : firstMessage,
@@ -3271,6 +3670,7 @@ export class SessionManager {
 	#persistChain: Promise<void> = Promise.resolve();
 	#persistError: Error | undefined;
 	#persistErrorReported = false;
+
 	#artifactManager: ArtifactManager | null = null;
 	#artifactManagerSessionFile: string | null = null;
 	// When set, take precedence over the lazily-derived per-session manager.
@@ -3293,7 +3693,7 @@ export class SessionManager {
 	#replayMetadataRevision = 0;
 	#materializedEntriesRevision = -1;
 	#materializedEntriesCache: SessionEntry[] | undefined;
-	#sessionContextCache: WeakRef<SessionContext> | undefined;
+	#sessionContextCache: SessionContext | undefined;
 	#sessionContextEntryRevision = -1;
 	#sessionContextLeafRevision = -1;
 	#sessionContextReplayMetadataRevision = -1;
@@ -3307,6 +3707,11 @@ export class SessionManager {
 	#getEntriesMaterializerCallCount = 0;
 	#materializedEntriesCachePopulateCount = 0;
 	#pathOnlyContextBuildCount = 0;
+	#internalReadAccess: SessionManagerReadAccess = {
+		getEntries: () => freezeInternalReadSnapshot(this.#getMaterializedEntriesInternal()),
+		getSessionContext: () => this.#getSessionContextForRead(),
+		getTree: () => this.#getTree(freezeInternalReadSnapshot(this.#getMaterializedEntriesInternal())),
+	};
 
 	private constructor(
 		private cwd: string,
@@ -3318,6 +3723,13 @@ export class SessionManager {
 		this.#residentImageBlobStore = this.#blobStore;
 		if (persist && sessionDir) {
 			this.storage.ensureDirSync(sessionDir);
+			// Canonicalize the trusted session directory (single choke point for every
+			// creation path: create/open/moveTo/fork/SDK) so benign ancestor symlinks
+			// (e.g. macOS `/var -> /private/var`, a symlinked `$HOME`) are resolved to a
+			// symlink-free root before the strict owner-only and reparse guards run.
+			if (this.storage instanceof FileSessionStorage) {
+				this.sessionDir = canonicalizeTrustedPath(sessionDir);
+			}
 		}
 		// Note: call _initSession() or _initSessionFile() after construction
 	}
@@ -3481,19 +3893,19 @@ export class SessionManager {
 	}
 
 	async #hydrateExistingSession(sessionFile: string, entries: FileEntry[], migrationApplied: boolean): Promise<void> {
-		const header = entries[0] as SessionHeader;
-		this.#sessionFile = path.resolve(sessionFile);
+		const ownedEntries = structuredClone(entries) as FileEntry[];
+		const header = ownedEntries[0] as SessionHeader;
+		this.#sessionFile = this.storage instanceof FileSessionStorage ? path.resolve(sessionFile) : sessionFile;
 		this.#sessionId = header.id;
 		this.#sessionName = header.title;
 		this.#titleSource = header.titleSource;
 		this.#needsFullRewriteOnNextPersist = migrationApplied;
-		await resolveBlobRefsInEntries(entries, this.#blobStore);
-		this.#fileEntries = entries;
+		await resolveBlobRefsInEntries(ownedEntries, this.#blobStore);
+		this.#fileEntries = ownedEntries;
 		this.#resetResidentTextBlobStore();
 		this.#fileEntries = this.#fileEntries.map(entry =>
 			prepareEntryForResidentSync(entry, this.#residentBlobStores()),
 		);
-		this.sanitizeLoadedOpenAIResponsesReplayMetadata();
 		this.#buildIndex();
 		this.#bumpAllRevisions();
 		this.#flushed = true;
@@ -3511,7 +3923,7 @@ export class SessionManager {
 		await this.#closePersistWriter();
 		this.#persistError = undefined;
 		this.#persistErrorReported = false;
-		this.#sessionFile = path.resolve(sessionFile);
+		this.#sessionFile = this.storage instanceof FileSessionStorage ? path.resolve(sessionFile) : sessionFile;
 		writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
 		this.#fileEntries = await loadEntriesFromFile(this.#sessionFile, this.storage);
 		if (this.#fileEntries.length > 0) {
@@ -3527,12 +3939,12 @@ export class SessionManager {
 			this.#fileEntries = this.#fileEntries.map(entry =>
 				prepareEntryForResidentSync(entry, this.#residentBlobStores()),
 			);
-			this.sanitizeLoadedOpenAIResponsesReplayMetadata();
 
 			this.#buildIndex();
 			this.#bumpAllRevisions();
 			this.#flushed = true;
 			this.#ensuredOnDisk = true;
+			await this.#sanitizeLoadedOpenAIResponsesReplayMetadataAndPersist();
 		} else {
 			const explicitPath = this.#sessionFile;
 			this.#newSessionSync();
@@ -3554,11 +3966,35 @@ export class SessionManager {
 		return sessionFile;
 	}
 
-	/** Delete a session file and its artifacts. Drains the persist writer first to avoid EPERM on Windows. ENOENT is treated as success. */
+	/** Tombstone and exact-delete managed transcripts, detaching the active transcript first. */
 	async dropSession(sessionPath: string): Promise<void> {
+		const requestedPath = path.resolve(sessionPath);
+		if (this.#sessionFile && path.resolve(this.#sessionFile) === requestedPath) {
+			await this.newSession();
+		}
 		await this.#closePersistWriter();
+		const managedRoot = resolveManagedSessionRoot(this.sessionDir, this.cwd);
 		try {
-			await this.storage.deleteSessionWithArtifacts(sessionPath);
+			if (managedRoot) {
+				if (!pathIsWithin(managedRoot, requestedPath))
+					throw new Error("Managed session deletion is limited to this manager's configured session root.");
+				const resolved = resolveManagedScope({
+					cwd: this.cwd,
+					agentDir: path.resolve(managedRoot, ".."),
+					sessionsRoot: managedRoot,
+				});
+				if (resolved.kind !== "resolved")
+					throw new Error("Managed session storage could not be resolved for this manager.");
+				const listing = listManagedCandidates(resolved.scope);
+				if (listing.kind !== "complete")
+					throw new Error("Managed session storage could not be verified; refusing deletion.");
+				const candidate = listing.owned.find(candidate => path.resolve(candidate.path) === requestedPath);
+				if (!candidate) throw new Error("Managed session deletion requires exact logical authorization.");
+				const deleted = await deleteManagedSessionCandidate(resolved.scope, candidate);
+				if (deleted.kind === "error") throw new Error(`Could not delete managed session: ${deleted.message}`);
+			} else {
+				await this.storage.deleteSessionWithArtifacts(sessionPath);
+			}
 		} catch (err) {
 			if (isEnoent(err)) return;
 			throw err;
@@ -3628,11 +4064,19 @@ export class SessionManager {
 	async moveTo(newCwd: string): Promise<void> {
 		const resolvedCwd = path.resolve(newCwd);
 		if (resolvedCwd === this.cwd) return;
-
-		const managedSessionsRoot = resolveManagedSessionRoot(this.sessionDir, this.cwd);
-		const newSessionDir = managedSessionsRoot
-			? computeDefaultSessionDir(resolvedCwd, this.storage, managedSessionsRoot)
-			: computeDefaultSessionDir(resolvedCwd, this.storage);
+		const previousCwd = this.cwd;
+		const previousSessionDir = this.sessionDir;
+		const previousSessionFile = this.#sessionFile;
+		const previousArtifactDir = previousSessionFile?.slice(0, -6);
+
+		const managedSessionsRoot =
+			this.storage instanceof FileSessionStorage ? resolveManagedSessionRoot(this.sessionDir, this.cwd) : undefined;
+		const newSessionDir =
+			this.storage instanceof FileSessionStorage
+				? managedSessionsRoot
+					? computeDefaultSessionDir(resolvedCwd, this.storage, managedSessionsRoot)
+					: computeDefaultSessionDir(resolvedCwd, this.storage)
+				: this.sessionDir;
 		let hadSessionFile = false;
 
 		if (this.persist && this.#sessionFile) {
@@ -3674,15 +4118,25 @@ export class SessionManager {
 			try {
 				// Guard: session file may not exist yet (no assistant messages persisted)
 				if (hadSessionFile) {
-					await movePathAcrossDevicesSafe(oldSessionFile, newSessionFile);
-					movedSessionFile = true;
+					try {
+						await movePathAcrossDevicesSafe(oldSessionFile, newSessionFile);
+						movedSessionFile = true;
+					} catch (error) {
+						if (error instanceof PathMoveCompletedWithSyncFailure) movedSessionFile = true;
+						throw error;
+					}
 				}
 
 				try {
 					const stat = await fs.promises.stat(oldArtifactDir);
 					if (stat.isDirectory()) {
-						await movePathAcrossDevicesSafe(oldArtifactDir, newArtifactDir);
-						movedArtifactDir = true;
+						try {
+							await movePathAcrossDevicesSafe(oldArtifactDir, newArtifactDir);
+							movedArtifactDir = true;
+						} catch (error) {
+							if (error instanceof PathMoveCompletedWithSyncFailure) movedArtifactDir = true;
+							throw error;
+						}
 					}
 				} catch (err) {
 					if (!isEnoent(err)) throw err;
@@ -3690,7 +4144,7 @@ export class SessionManager {
 			} catch (err) {
 				if (movedArtifactDir) {
 					try {
-						await fs.promises.rename(newArtifactDir, oldArtifactDir);
+						await movePathAcrossDevicesSafe(newArtifactDir, oldArtifactDir);
 					} catch (rollbackErr) {
 						restoreResidentStateAndThrow(
 							new Error(
@@ -3701,7 +4155,7 @@ export class SessionManager {
 				}
 				if (movedSessionFile) {
 					try {
-						await fs.promises.rename(newSessionFile, oldSessionFile);
+						await movePathAcrossDevicesSafe(newSessionFile, oldSessionFile);
 					} catch (rollbackErr) {
 						restoreResidentStateAndThrow(
 							new Error(
@@ -3719,27 +4173,63 @@ export class SessionManager {
 			this.#bumpAllRevisions();
 		}
 
-		// Update cwd and sessionDir after the move succeeds.
+		// Update cwd and sessionDir after the physical move succeeds, but roll the move back if metadata persistence fails.
 		this.cwd = resolvedCwd;
 		this.sessionDir = newSessionDir;
 
-		// Update the session header in fileEntries
-		const header = this.#fileEntries.find(e => e.type === "session") as SessionHeader | undefined;
-		if (header) {
-			header.cwd = resolvedCwd;
-			this.#headerExportRevision++;
-		}
-
-		// Rewrite the session file at its new location with updated header.
-		// hadSessionFile: file existed before move → must rewrite to update cwd
-		// hasAssistant: assistant messages in memory but file missing → recreate from memory
-		// Neither true → fresh session, never written → preserve lazy-persist
 		const hasAssistant = this.#fileEntries.some(e => e.type === "message" && e.message.role === "assistant");
-		if (this.persist && this.#sessionFile && (hadSessionFile || hasAssistant)) {
-			await this.#rewriteFile();
+		try {
+			if (this.persist && this.#sessionFile && hadSessionFile) {
+				await this.#appendHeaderPatch({ cwd: resolvedCwd });
+				await this.#rewriteFile();
+			} else if (this.persist && this.#sessionFile && hasAssistant) {
+				await this.#appendHeaderPatch({ cwd: resolvedCwd });
+				await this.#rewriteFile();
+			} else {
+				await this.#appendHeaderPatch({ cwd: resolvedCwd });
+			}
+		} catch (error) {
+			const failedSessionFile = this.#sessionFile;
+			const failedArtifactDir = failedSessionFile?.slice(0, -6);
+			try {
+				await this.#closePersistWriter().catch(() => {});
+				this.#persistChain = Promise.resolve();
+				this.#persistError = undefined;
+				this.#persistErrorReported = false;
+				if (
+					this.storage instanceof FileSessionStorage &&
+					failedArtifactDir &&
+					previousArtifactDir &&
+					failedArtifactDir !== previousArtifactDir &&
+					fs.existsSync(failedArtifactDir)
+				) {
+					await movePathAcrossDevicesSafe(failedArtifactDir, previousArtifactDir);
+				}
+				if (
+					this.storage instanceof FileSessionStorage &&
+					failedSessionFile &&
+					previousSessionFile &&
+					failedSessionFile !== previousSessionFile &&
+					fs.existsSync(failedSessionFile)
+				) {
+					await movePathAcrossDevicesSafe(failedSessionFile, previousSessionFile);
+				}
+				this.#sessionFile = previousSessionFile;
+				this.cwd = previousCwd;
+				this.sessionDir = previousSessionDir;
+				const header = this.#fileEntries.find(entry => entry.type === "session") as SessionHeader | undefined;
+				if (header) applyHeaderPatch(header, { cwd: previousCwd });
+				this.#headerExportRevision++;
+				if (previousSessionFile && this.storage.existsSync(previousSessionFile)) await this.#rewriteFile();
+			} catch (rollbackError) {
+				throw new Error(`Failed to rollback session move: ${toError(rollbackError).message}`, {
+					cause: toError(error),
+				});
+			}
+			throw error;
 		}
 
-		// Update terminal breadcrumb
+		// Update terminal breadcrumb only after the durable cwd transition succeeds.
 		if (this.#sessionFile) {
 			writeTerminalBreadcrumb(resolvedCwd, this.#sessionFile);
 		}
@@ -3777,6 +4267,9 @@ export class SessionManager {
 		this.#usageStatistics = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, premiumRequests: 0, cost: 0 };
 		this.#inMemoryArtifacts = null;
 		this.#inMemoryArtifactCounter = 0;
+		this.#artifactManager = null;
+		this.#artifactManagerSessionFile = null;
+		this.#adoptedArtifactManager = null;
 
 		if (this.persist) {
 			const fileTimestamp = timestamp.replace(/[:.]/g, "-");
@@ -4104,19 +4597,23 @@ export class SessionManager {
 		}
 	}
 
-	async #rewriteFile(): Promise<void> {
+	async #rewriteFileContents(): Promise<void> {
 		if (!this.persist || !this.#sessionFile) return;
+		await this.#closePersistWriterInternal();
+		const entries = await Promise.all(
+			materializeResidentEntriesForPersistenceSync(this.#fileEntries, this.#residentBlobStores()).map(entry =>
+				prepareEntryForPersistence(entry, this.#blobStore),
+			),
+		);
+		await this.#writeEntriesAtomically(entries);
+		this.#needsFullRewriteOnNextPersist = false;
+		this.#flushed = true;
+		this.#ensuredOnDisk = true;
+	}
+
+	async #rewriteFile(): Promise<void> {
 		await this.#queuePersistTask(async () => {
-			await this.#closePersistWriterInternal();
-			const entries = await Promise.all(
-				materializeResidentEntriesForPersistenceSync(this.#fileEntries, this.#residentBlobStores()).map(entry =>
-					prepareEntryForPersistence(entry, this.#blobStore),
-				),
-			);
-			await this.#writeEntriesAtomically(entries);
-			this.#needsFullRewriteOnNextPersist = false;
-			this.#flushed = true;
-			this.#ensuredOnDisk = true;
+			await this.#rewriteFileContents();
 		});
 	}
 
@@ -4520,7 +5017,8 @@ export class SessionManager {
 		return name
 			.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
 			.replace(/ +/g, " ")
-			.trim();
+			.trim()
+			.slice(0, SESSION_NAME_MAX_CHARS);
 	}
 
 	/**
@@ -4537,23 +5035,40 @@ export class SessionManager {
 
 		this.#sessionName = sanitized;
 		this.#titleSource = source;
+		await this.#appendHeaderPatch({ title: sanitized, titleSource: source });
+		return true;
+	}
 
-		// Update the in-memory header (so first flush includes title)
-		const header = this.#fileEntries.find(e => e.type === "session") as SessionHeader | undefined;
-		if (header) {
-			header.title = sanitized;
-			header.titleSource = source;
-		}
+	async #appendHeaderPatch(patch: HeaderPatchRecord["patch"]): Promise<void> {
+		const header = this.#fileEntries.find(entry => entry.type === "session") as SessionHeader | undefined;
+		if (!header) return;
+		applyHeaderPatch(header, patch);
 		this.#headerExportRevision++;
-
-		// Update the session file header with the title (if already flushed)
-		const sessionFile = this.#sessionFile;
-		if (this.persist && sessionFile && this.storage.existsSync(sessionFile)) {
-			await this.#rewriteFile();
-		}
-		return true;
+		await this.#persistPatch({ type: "header_patch", patch });
 	}
 
+	async #persistPatch(record: SessionPatchRecord): Promise<void> {
+		if (!this.persist || !this.#sessionFile || !this.storage.existsSync(this.#sessionFile)) return;
+		await this.#queuePersistTask(async () => {
+			const header = this.#fileEntries.find(entry => entry.type === "session") as SessionHeader | undefined;
+			if (this.#needsFullRewriteOnNextPersist || !this.#flushed || (header?.version ?? 1) < CURRENT_SESSION_VERSION)
+				return this.#rewriteFileContents();
+			const writer = this.#ensurePersistWriter();
+			if (!writer) return this.#rewriteFileContents();
+			const persistedRecord =
+				record.type === "entry_patch"
+					? (prepareEntryForPersistenceSync(
+							materializeResidentEntryForPersistenceSync(
+								record as unknown as FileEntry,
+								this.#residentBlobStores(),
+								new Map(),
+							),
+							this.#blobStore,
+						) as unknown as SessionPatchRecord)
+					: record;
+			await writer.write(persistedRecord);
+		});
+	}
 	_persist(entry: SessionEntry): void {
 		if (!this.persist || !this.#sessionFile) return;
 		if (this.#persistError) throw this.#persistError;
@@ -4566,6 +5081,7 @@ export class SessionManager {
 			if (!hasAssistant) {
 				// Mark as not flushed so when assistant arrives, all entries get written.
 				this.#flushed = false;
+
 				this.#ensuredOnDisk = false;
 				return;
 			}
@@ -4859,6 +5375,22 @@ export class SessionManager {
 		this.#replayMetadataRevision++;
 	}
 
+	/** Write mutated custom-message entries back into the canonical entry store by id. */
+	applyCustomMessageEntryUpdates(entries: readonly CustomMessageEntry[]): void {
+		for (const updated of entries) {
+			const canonical = this.#byId.get(updated.id);
+			if (canonical?.type !== "custom_message") continue;
+			canonical.content = updated.content;
+			canonical.details = updated.details;
+			// Pruning replaces content permanently; retaining a cold-spill marker would
+			// rehydrate the superseded payload on the next materialization.
+			canonical.evictedContent = undefined;
+		}
+		this.#needsFullRewriteOnNextPersist = true;
+		this.#bumpEntryRevision();
+		this.#replayMetadataRevision++;
+	}
+
 	/**
 	 * Rewrite the session file after in-place entry updates.
 	 * Use sparingly (e.g., pruning old tool outputs).
@@ -4978,7 +5510,9 @@ export class SessionManager {
 	getLeafEntry(): SessionEntry | undefined {
 		if (!this.#leafId) return undefined;
 		const entry = this.#byId.get(this.#leafId);
-		return entry ? materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()) : undefined;
+		return entry
+			? cloneSessionEntry(materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()))
+			: undefined;
 	}
 
 	getResidentImageBytes(): number {
@@ -5163,10 +5697,12 @@ export class SessionManager {
 	getEntryForFidelity(id: string): SessionEntry | undefined {
 		const entry = this.#byId.get(id);
 		return entry
-			? rehydrateColdSpillEntry(
-					materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()),
-					this.#blobStore,
-					this.#residentBlobStoresForColdRehydrate(),
+			? cloneSessionEntry(
+					rehydrateColdSpillEntry(
+						materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()),
+						this.#blobStore,
+						this.#residentBlobStoresForColdRehydrate(),
+					),
 				)
 			: undefined;
 	}
@@ -5180,10 +5716,12 @@ export class SessionManager {
 			if (visited.has(current.id)) break;
 			visited.add(current.id);
 			path.push(
-				rehydrateColdSpillEntry(
-					materializeResidentEntryForReadSync(current, this.#residentBlobStores(), cache),
-					this.#blobStore,
-					this.#residentBlobStoresForColdRehydrate(),
+				cloneSessionEntry(
+					rehydrateColdSpillEntry(
+						materializeResidentEntryForReadSync(current, this.#residentBlobStores(), cache),
+						this.#blobStore,
+						this.#residentBlobStoresForColdRehydrate(),
+					),
 				),
 			);
 			current = current.parentId ? this.#byId.get(current.parentId) : undefined;
@@ -5220,10 +5758,12 @@ export class SessionManager {
 		return this.#fileEntries
 			.filter((entry): entry is SessionEntry => entry.type !== "session")
 			.map(entry =>
-				rehydrateColdSpillEntry(
-					materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), cache),
-					this.#blobStore,
-					this.#residentBlobStoresForColdRehydrate(),
+				cloneSessionEntry(
+					rehydrateColdSpillEntry(
+						materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), cache),
+						this.#blobStore,
+						this.#residentBlobStoresForColdRehydrate(),
+					),
 				),
 			);
 	}
@@ -5232,7 +5772,9 @@ export class SessionManager {
 		this.#publicMaterializerCallCount++;
 		this.#getEntryMaterializerCallCount++;
 		const entry = this.#byId.get(id);
-		return entry ? materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()) : undefined;
+		return entry
+			? cloneSessionEntry(materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()))
+			: undefined;
 	}
 
 	/**
@@ -5243,7 +5785,9 @@ export class SessionManager {
 		const children: SessionEntry[] = [];
 		for (const entry of this.#byId.values()) {
 			if (entry.parentId === parentId) {
-				children.push(materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), cache));
+				children.push(
+					cloneSessionEntry(materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), cache)),
+				);
 			}
 		}
 		return children;
@@ -5298,7 +5842,7 @@ export class SessionManager {
 		while (current) {
 			if (visited.has(current.id)) break;
 			visited.add(current.id);
-			path.push(materializeResidentEntryForReadSync(current, this.#residentBlobStores(), cache));
+			path.push(cloneSessionEntry(materializeResidentEntryForReadSync(current, this.#residentBlobStores(), cache)));
 			current = current.parentId ? this.#byId.get(current.parentId) : undefined;
 		}
 		path.reverse();
@@ -5309,15 +5853,26 @@ export class SessionManager {
 	 * Build the session context (what gets sent to the LLM).
 	 * Uses tree traversal from current leaf.
 	 */
+	/**
+	 * Return a defensive context snapshot for public consumers.
+	 */
 	buildSessionContext(): SessionContext {
-		const cached = this.#sessionContextCache?.deref();
+		return cloneSessionContext(this.#getSessionContextForRead());
+	}
+
+	/**
+	 * Return the revision-keyed context cache for internal read-only consumers.
+	 * The strong reference avoids GC-driven rebuilds during a session.
+	 */
+	#getSessionContextForRead(): Readonly<SessionContext> {
+		const cached = this.#sessionContextCache;
 		if (
 			cached &&
 			this.#sessionContextEntryRevision === this.#entryRevision &&
 			this.#sessionContextLeafRevision === this.#leafRevision &&
 			this.#sessionContextReplayMetadataRevision === this.#replayMetadataRevision
 		) {
-			return cloneSessionContext(cached);
+			return cached;
 		}
 		this.#pathOnlyContextBuildCount++;
 		const context = buildSessionContext(
@@ -5326,11 +5881,12 @@ export class SessionManager {
 			undefined,
 			this.#sessionId,
 		);
-		this.#sessionContextCache = new WeakRef(context);
+		this.#sessionContextCache = freezeInternalReadSnapshot(context);
+		transferSessionMessageIdentity(context.messages, this.#sessionContextCache.messages);
 		this.#sessionContextEntryRevision = this.#entryRevision;
 		this.#sessionContextLeafRevision = this.#leafRevision;
 		this.#sessionContextReplayMetadataRevision = this.#replayMetadataRevision;
-		return cloneSessionContext(context);
+		return this.#sessionContextCache;
 	}
 
 	#getActivePathEntriesForProviderContext(fromId?: string | null): SessionEntry[] {
@@ -5385,28 +5941,33 @@ export class SessionManager {
 		const marker = entry.type === "message" || entry.type === "custom_message" ? entry.evictedContent : undefined;
 		return marker ? Object.keys(marker.payloads ?? {}).length : 0;
 	}
-	/** Strip stale OpenAI Responses assistant replay metadata from loaded in-memory entries. */
+	/** Strip stale OpenAI Responses assistant replay metadata from loaded in-memory entries without persisting it. */
 	sanitizeLoadedOpenAIResponsesReplayMetadata(): boolean {
-		let didSanitize = false;
-		for (const entry of this.#fileEntries) {
-			if (entry.type !== "message" || entry.message.role !== "assistant") {
-				continue;
-			}
+		return this.#sanitizeLoadedOpenAIResponsesReplayMetadata().length > 0;
+	}
 
-			const sanitizedMessage = sanitizeRehydratedOpenAIResponsesAssistantMessage(entry.message);
-			if (sanitizedMessage === entry.message) {
-				continue;
-			}
+	async #sanitizeLoadedOpenAIResponsesReplayMetadataAndPersist(): Promise<boolean> {
+		const patches = this.#sanitizeLoadedOpenAIResponsesReplayMetadata();
+		for (const patch of patches) {
+			await this.#persistPatch(patch);
+		}
+		return patches.length > 0;
+	}
 
+	#sanitizeLoadedOpenAIResponsesReplayMetadata(): EntryPatchRecord[] {
+		const patches: EntryPatchRecord[] = [];
+		for (const entry of this.#fileEntries) {
+			if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+			const sanitizedMessage = sanitizeRehydratedOpenAIResponsesAssistantMessage(entry.message);
+			if (sanitizedMessage === entry.message) continue;
 			entry.message = sanitizedMessage;
-			didSanitize = true;
+			patches.push({ type: "entry_patch", entryId: entry.id, patch: { message: sanitizedMessage } });
 		}
-		if (didSanitize) {
+		if (patches.length > 0) {
 			this.#bumpEntryRevision();
 			this.#replayMetadataRevision++;
 		}
-
-		return didSanitize;
+		return patches;
 	}
 
 	/**
@@ -5418,9 +5979,7 @@ export class SessionManager {
 	}
 
 	/**
-	 * Get all session entries (excludes header). Returns a shallow copy.
-	 * The session is append-only: use appendXXX() to add entries, branch() to
-	 * change the leaf pointer. Entries cannot be modified or deleted.
+	 * Internal materialized entry cache. Public getters clone this snapshot before returning it.
 	 */
 	#getMaterializedEntriesInternal(): SessionEntry[] {
 		if (this.#materializedEntriesRevision === this.#entryRevision && this.#materializedEntriesCache) {
@@ -5446,12 +6005,14 @@ export class SessionManager {
 	}
 
 	/**
-	 * Get the session as a tree structure. Returns a shallow defensive copy of all entries.
+	 * Get the session as a tree structure. Returns defensive copies of all entries.
 	 * A well-formed session has exactly one root (first entry with parentId === null).
 	 * Orphaned entries (broken parent chain) are also returned as roots.
 	 */
 	getTree(): SessionTreeNode[] {
-		const entries = this.getEntries();
+		return this.#getTree(this.getEntries());
+	}
+	#getTree(entries: readonly SessionEntry[]): SessionTreeNode[] {
 		const nodeMap = new Map<string, SessionTreeNode>();
 		const roots: SessionTreeNode[] = [];
 
@@ -5523,7 +6084,9 @@ export class SessionManager {
 
 		return roots;
 	}
-
+	[sessionManagerReadCapability](): SessionManagerReadAccess {
+		return this.#internalReadAccess;
+	}
 	// =========================================================================
 	// Branching
 	// =========================================================================
@@ -5700,9 +6263,16 @@ export class SessionManager {
 
 	/** Resolve the default session directory without creating or migrating storage. */
 	static getDefaultSessionDirReadOnly(cwd: string, agentDir?: string): string {
-		const { encodedDirName } = getDefaultSessionDirName(cwd);
-		return path.join(getSessionsDir(agentDir), encodedDirName);
+		const sessionsRoot = getSessionsDir(agentDir);
+		const resolved = resolveManagedScope({
+			cwd,
+			agentDir: agentDir ?? path.resolve(sessionsRoot, ".."),
+			sessionsRoot,
+		});
+		if (resolved.kind === "error") throw new Error(`Could not resolve managed session scope: ${resolved.message}`);
+		return resolved.scope.directoryPath;
 	}
+
 	/**
 	 * Create a new session.
 	 * @param cwd Working directory (stored in session header)
@@ -5715,6 +6285,59 @@ export class SessionManager {
 		return manager;
 	}
 
+	/** Resolve a default-managed candidate through binding validation and copy-retain migration before mutation. */
+	static async prepareManagedCandidateForWrite(
+		filePath: string,
+		migrationPolicy: SessionDirectoryMigrationPolicy,
+	): Promise<string> {
+		const storage = new FileSessionStorage();
+		const inspected = inspectResumeSessionFile(filePath, storage);
+		if ("kind" in inspected) {
+			if (inspected.reason === "missing") return filePath;
+			throw new Error(`Could not inspect managed session: ${inspected.reason}`);
+		}
+		const header = inspected.entries.find(entry => entry.type === "session") as SessionHeader | undefined;
+		if (!header?.cwd) return filePath;
+		const sessionsRoot = getSessionsDir();
+		const resolvedPath = path.resolve(filePath);
+		const relativeToManagedRoot = path.relative(sessionsRoot, resolvedPath);
+		const isManagedPath =
+			relativeToManagedRoot === "" ||
+			(!relativeToManagedRoot.startsWith("..") && !path.isAbsolute(relativeToManagedRoot));
+
+		if (!isManagedPath) return filePath;
+		const resolved = resolveManagedScope({
+			cwd: header.cwd,
+			agentDir: path.resolve(sessionsRoot, ".."),
+			sessionsRoot,
+		});
+		if (resolved.kind === "error") throw new Error(`Could not resolve managed session scope: ${resolved.message}`);
+
+		const listing = listManagedCandidates(resolved.scope);
+		if (listing.kind !== "complete") throw new Error(`Managed session scan failed: ${listing.message}`);
+
+		const candidate = listing.owned.find(item => path.resolve(item.path) === resolvedPath);
+		if (!candidate) throw new Error("Session is inside managed storage but is not an authorized managed candidate.");
+		const revalidated = inspectResumeSessionFile(filePath, storage);
+		if (
+			"kind" in revalidated ||
+			!sameResumeIdentity(inspected.identity, revalidated.identity) ||
+			candidate.identity.dev !== inspected.identity.dev ||
+			candidate.identity.ino !== inspected.identity.ino ||
+			candidate.identity.size !== inspected.identity.size ||
+			candidate.identity.mtimeNs !== inspected.identity.mtimeNs ||
+			candidate.identity.mtimeMs !== inspected.identity.mtimeMs ||
+			candidate.identity.sha256 !== inspected.identity.sha256
+		)
+			throw new Error("Managed session changed before migration authority was adopted.");
+		const opened = await openManagedCandidateForWrite(resolved.scope, candidate, migrationPolicy);
+		if (opened.kind === "error") {
+			if (opened.code === "legacy_migration_disabled") throw new SessionMigrationPolicyError();
+			throw new Error(`Could not open managed session: ${opened.message}`);
+		}
+		return opened.path;
+	}
+
 	/**
 	 * Fork a session into the current project directory.
 	 * Copies history from another session file while creating a new session file in the current sessionDir.
@@ -5724,10 +6347,15 @@ export class SessionManager {
 		cwd: string,
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
+		migrationPolicy: SessionDirectoryMigrationPolicy = "copy-retain",
 	): Promise<SessionManager> {
+		const managedSourcePath =
+			!sessionDir && storage instanceof FileSessionStorage
+				? await SessionManager.prepareManagedCandidateForWrite(sourcePath, migrationPolicy)
+				: sourcePath;
 		const dir = sessionDir ?? SessionManager.getDefaultSessionDir(cwd, undefined, storage);
 		const manager = new SessionManager(cwd, dir, true, storage);
-		const forkEntries = structuredClone(await loadEntriesFromFile(sourcePath, storage)) as FileEntry[];
+		const forkEntries = structuredClone(await loadEntriesFromFile(managedSourcePath, storage)) as FileEntry[];
 		migrateToCurrentVersion(forkEntries);
 		await resolveBlobRefsInEntries(forkEntries, manager.#blobStore);
 		manager.#fileEntries = forkEntries;
@@ -5762,16 +6390,48 @@ export class SessionManager {
 		filePath: string,
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
+		migrationPolicy: SessionDirectoryMigrationPolicy = "copy-retain",
 	): Promise<SessionManager> {
-		// Extract cwd from session header if possible, otherwise use getProjectDir()
-		const entries = await loadEntriesFromFile(filePath, storage);
-		const header = entries.find(e => e.type === "session") as SessionHeader | undefined;
-		const cwd = header?.cwd ?? getProjectDir();
-		// If no sessionDir provided, derive from file's parent directory
-		const dir = sessionDir ?? path.resolve(filePath, "..");
-		const manager = new SessionManager(cwd, dir, true, storage);
-		await manager.#initSessionFile(filePath);
-		return manager;
+		// Canonicalize benign ancestor symlinks in the caller-supplied path (e.g.
+		// macOS `/var -> /private/var`, a symlinked `$HOME`/project) so explicit
+		// session files land under a symlink-free trusted root that the strict
+		// owner-only and reparse guards accept.
+		if (storage instanceof FileSessionStorage) filePath = canonicalizeTrustedPath(filePath);
+		if (sessionDir || !(storage instanceof FileSessionStorage)) {
+			const entries = await loadEntriesFromFile(filePath, storage);
+			const header = entries.find(entry => entry.type === "session") as SessionHeader | undefined;
+			const manager = new SessionManager(
+				header?.cwd ?? getProjectDir(),
+				sessionDir ??
+					(storage instanceof FileSessionStorage ? path.resolve(filePath, "..") : path.dirname(filePath)),
+				true,
+				storage,
+			);
+			await manager.#initSessionFile(filePath);
+			return manager;
+		}
+
+		const managedPath =
+			!sessionDir && storage instanceof FileSessionStorage
+				? await SessionManager.prepareManagedCandidateForWrite(filePath, migrationPolicy)
+				: filePath;
+		const inspected = inspectResumeSessionFile(managedPath, storage);
+		if ("kind" in inspected) {
+			if (inspected.reason === "missing" && path.resolve(managedPath) === path.resolve(filePath)) {
+				const manager = new SessionManager(getProjectDir(), path.resolve(filePath, ".."), true, storage);
+				await manager.#initSessionFile(filePath);
+				return manager;
+			}
+			throw new Error(`Could not open session: ${inspected.reason}`);
+		}
+		const opened = await SessionManager.openExistingStrict(
+			inspected.identity,
+			sessionDir ?? path.resolve(managedPath, ".."),
+			storage,
+			migrationPolicy,
+		);
+		if (opened.kind === "error") throw new Error(`Could not open session: ${opened.reason}`);
+		return opened.manager;
 	}
 
 	/**
@@ -5782,16 +6442,60 @@ export class SessionManager {
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
 	): Promise<SessionInfo[]> {
-		const dirs = sessionDir ? [sessionDir] : getReadOnlyDefaultSessionDirs(cwd);
+		if (!sessionDir && !(storage instanceof FileSessionStorage)) return [];
+		if (sessionDir && !resolveManagedSessionRoot(sessionDir, cwd)) {
+			try {
+				return await collectSessionsFromFiles(storage.listFilesSync(sessionDir, "*.jsonl"), storage);
+			} catch {
+				return [];
+			}
+		}
+		const sessionsRoot = sessionDir
+			? (resolveManagedSessionRoot(sessionDir, cwd) ?? getSessionsDir())
+			: getSessionsDir();
+		const resolved = resolveManagedScope({ cwd, agentDir: path.resolve(sessionsRoot, ".."), sessionsRoot });
+		if (resolved.kind === "error") return [];
+		if (storage instanceof FileSessionStorage) {
+			const listing = listManagedCandidates(resolved.scope);
+			if (listing.kind === "error") return [];
+			return await collectSessionsFromFiles(
+				listing.owned.map(candidate => candidate.path),
+				storage,
+			);
+		}
+		const legacyDirectory = `--${resolved.scope.canonicalCwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+		const files = new Set<string>();
 		try {
-			const files = new Set<string>();
-			for (const dir of dirs) {
-				for (const filePath of storage.listFilesSync(dir, "*.jsonl")) files.add(filePath);
+			for (const directory of [resolved.scope.directoryPath, path.join(sessionsRoot, legacyDirectory)]) {
+				for (const file of storage.listFilesSync(directory, "*.jsonl")) files.add(file);
 			}
-			return await collectSessionsFromFiles([...files], storage);
 		} catch {
 			return [];
 		}
+		return (await collectSessionsFromFiles([...files], storage)).filter(
+			session => resolveEquivalentPath(session.cwd) === resolved.scope.canonicalCwd,
+		);
+	}
+
+	/** Tombstone and exact-delete a default-managed 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.");
+		const sessionsRoot = path.resolve(sessionPath, "../..");
+		const resolved = resolveManagedScope({
+			cwd: header.cwd,
+			agentDir: path.resolve(sessionsRoot, ".."),
+			sessionsRoot,
+		});
+		if (resolved.kind === "error") throw new Error(`Could not resolve managed session scope: ${resolved.message}`);
+		const listing = listManagedCandidates(resolved.scope);
+		if (listing.kind !== "complete") throw new Error("Managed session scan did not grant deletion authority.");
+		const candidate = listing.owned.find(item => path.resolve(item.path) === path.resolve(sessionPath));
+		if (!candidate) throw new Error("Session is not an authorized managed candidate.");
+		const deleted = await deleteManagedSessionCandidate(resolved.scope, candidate);
+		if (deleted.kind === "error") throw new Error(`Could not delete managed session: ${deleted.message}`);
 	}
 
 	/** Capture exact source content for a strict fork without granting write ownership. */
@@ -5821,6 +6525,7 @@ export class SessionManager {
 		snapshot: CapturedSessionTranscriptSnapshot,
 		cwd: string,
 		sessionDir?: string,
+		_migrationPolicy: SessionDirectoryMigrationPolicy = "copy-retain",
 	): Promise<StrictSessionForkResult> {
 		if (crypto.createHash("sha256").update(snapshot.content).digest("hex") !== snapshot.identity.sha256) {
 			return { kind: "error", reason: "identity-mismatch" };
@@ -5884,6 +6589,15 @@ export class SessionManager {
 				throw new Error("Captured fork source authority changed before destination write.");
 			}
 			await manager.#rewriteFile();
+			const afterWrite = inspectResumeSessionFile(snapshot.sourcePath, snapshot.storage);
+			if ("kind" in afterWrite) {
+				authorityFailure = afterWrite;
+				throw new Error("Captured fork source authority changed during destination write.");
+			}
+			if (!sameResumeIdentity(snapshot.identity, afterWrite.identity)) {
+				authorityFailure = { kind: "error", reason: "identity-mismatch" };
+				throw new Error("Captured fork source authority changed during destination write.");
+			}
 			if (manager.#sessionFile) writeTerminalBreadcrumb(manager.cwd, manager.#sessionFile);
 			return { kind: "forked", manager };
 		} catch (error) {
@@ -5968,27 +6682,48 @@ export class SessionManager {
 		identity: ResumeSessionIdentity,
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
+		migrationPolicy: SessionDirectoryMigrationPolicy = "copy-retain",
 	): Promise<StrictSessionOpenResult> {
-		const inspected = inspectResumeSessionFile(identity.canonicalPath, storage);
+		let sessionPath = identity.canonicalPath;
+		if (!sessionDir && storage instanceof FileSessionStorage) {
+			try {
+				sessionPath = await SessionManager.prepareManagedCandidateForWrite(sessionPath, migrationPolicy);
+			} catch (error) {
+				if (error instanceof SessionMigrationPolicyError)
+					return { kind: "error", reason: "legacy_migration_disabled" };
+				throw error;
+			}
+		}
+		const inspected = inspectResumeSessionFile(sessionPath, storage);
 		if ("kind" in inspected) return inspected;
-		if (!sameResumeIdentity(identity, inspected.identity)) {
+		if (
+			(sessionPath === identity.canonicalPath && !sameResumeIdentity(identity, inspected.identity)) ||
+			(sessionPath !== identity.canonicalPath &&
+				(identity.sessionId !== inspected.identity.sessionId || identity.sha256 !== inspected.identity.sha256))
+		) {
 			return { kind: "error", reason: "identity-mismatch" };
 		}
-		const entries = structuredClone(inspected.entries) as FileEntry[];
+		const entries = inspected.entries;
 		const header = entries[0] as SessionHeader;
-		const dir = sessionDir ?? path.resolve(identity.canonicalPath, "..");
+		const dir = sessionDir ?? path.resolve(sessionPath, "..");
 		const manager = new SessionManager(header.cwd || getProjectDir(), dir, true, storage);
-		await manager.#hydrateExistingSession(identity.canonicalPath, entries, inspected.migrationApplied);
-		const ownershipInspection = inspectResumeSessionFile(identity.canonicalPath, storage);
+		await manager.#hydrateExistingSession(sessionPath, entries, inspected.migrationApplied);
+		const ownershipInspection = inspectResumeSessionFile(sessionPath, storage);
 		if ("kind" in ownershipInspection) {
 			await manager.close();
 			return ownershipInspection;
 		}
-		if (!sameResumeIdentity(identity, ownershipInspection.identity)) {
+		if (!sameResumeIdentity(inspected.identity, ownershipInspection.identity)) {
 			await manager.close();
 			return { kind: "error", reason: "identity-mismatch" };
 		}
-		writeTerminalBreadcrumb(manager.cwd, identity.canonicalPath);
+		try {
+			await manager.#sanitizeLoadedOpenAIResponsesReplayMetadataAndPersist();
+			writeTerminalBreadcrumb(manager.cwd, sessionPath);
+		} catch (error) {
+			await manager.close();
+			throw error;
+		}
 		return { kind: "opened", manager };
 	}
 
@@ -6001,24 +6736,42 @@ export class SessionManager {
 		cwd: string,
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
+		migrationPolicy: SessionDirectoryMigrationPolicy = "copy-retain",
 	): Promise<SessionManager> {
 		const dir = sessionDir ?? SessionManager.getDefaultSessionDir(cwd, undefined, storage);
-		// Prefer terminal-scoped breadcrumb (handles concurrent sessions correctly)
+		const openSelectedStrictly = async (selectedPath: string): Promise<SessionManager | undefined> => {
+			const inspected = await SessionManager.inspectSessionTailReadOnly(selectedPath, storage);
+			if (inspected.kind === "error") return undefined;
+			const opened = await SessionManager.openExistingStrict(
+				inspected.identity,
+				sessionDir,
+				storage,
+				migrationPolicy,
+			);
+			if (opened.kind === "error") {
+				if (opened.reason === "legacy_migration_disabled") throw new SessionMigrationPolicyError();
+				return undefined;
+			}
+			return opened.manager;
+		};
+		// Legacy paths are candidates only: the managed scan validates each transcript
+		// header cwd before it can affect default resume authority.
+		const managedCandidates = sessionDir
+			? []
+			: await SessionManager.listForResumePickerReadOnly(cwd, undefined, storage);
 		const terminalSession = await readTerminalBreadcrumb(cwd);
-		const mostRecent = terminalSession ?? (await findMostRecentSession(dir, storage));
+		if (terminalSession) {
+			const opened = await openSelectedStrictly(terminalSession);
+			if (opened) return opened;
+		}
+		for (const candidate of managedCandidates) {
+			const opened = await openSelectedStrictly(candidate.path);
+			if (opened) return opened;
+		}
+		const mostRecent = await findMostRecentSession(dir, storage);
 		if (mostRecent) {
-			// Adopt the resumed session's recorded cwd and its own directory. A
-			// `--worktree` session lives in a linked worktree whose path differs from
-			// the invocation cwd; binding the manager (and HUD) to `cwd` would leave
-			// it on the main checkout instead of the worktree it was created in.
-			const header = (await loadEntriesFromFile(mostRecent, storage)).find(e => e.type === "session") as
-				| SessionHeader
-				| undefined;
-			const resumeCwd = header?.cwd || cwd;
-			const resumeDir = sessionDir ?? path.resolve(mostRecent, "..");
-			const manager = new SessionManager(resumeCwd, resumeDir, true, storage);
-			await manager.#initSessionFile(mostRecent);
-			return manager;
+			const opened = await openSelectedStrictly(mostRecent);
+			if (opened) return opened;
 		}
 		const manager = new SessionManager(cwd, dir, true, storage);
 		manager.#initNewSession();
@@ -6045,11 +6798,10 @@ export class SessionManager {
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
 	): Promise<SessionInfo[]> {
-		const dir = sessionDir ?? SessionManager.getDefaultSessionDir(cwd, undefined, storage);
+		if (!sessionDir) return await SessionManager.listForResumePickerReadOnly(cwd, undefined, storage);
 		try {
-			await recoverOrphanedBackups(dir, storage);
-			const files = storage.listFilesSync(dir, "*.jsonl");
-			return await collectSessionsFromFiles(files, storage);
+			await recoverOrphanedBackups(sessionDir, storage);
+			return await collectSessionsFromFiles(storage.listFilesSync(sessionDir, "*.jsonl"), storage);
 		} catch {
 			return [];
 		}
@@ -6059,12 +6811,39 @@ export class SessionManager {
 	 * List all sessions across all project directories.
 	 */
 	static async listAll(storage: SessionStorage = new FileSessionStorage()): Promise<SessionInfo[]> {
+		if (!(storage instanceof FileSessionStorage)) return [];
 		const sessionsRoot = path.join(getDefaultAgentDir(), "sessions");
 		try {
-			const files = await Array.fromAsync(new Bun.Glob("*/*.jsonl").scan(sessionsRoot), name =>
-				path.join(sessionsRoot, name),
-			);
-			return await collectSessionsFromFiles(files, storage);
+			const directories = await fs.promises.readdir(sessionsRoot, { withFileTypes: true });
+			const seedFiles = directories
+				.filter(entry => entry.isDirectory())
+				.flatMap(entry => storage.listFilesSync(path.join(sessionsRoot, entry.name), "*.jsonl"));
+			const seedSessions = await collectSessionsFromFiles(seedFiles, storage);
+			const logicalFiles = new Set<string>();
+			for (const cwd of new Set(seedSessions.map(session => session.cwd).filter(Boolean))) {
+				const scope = resolveManagedScope({
+					cwd,
+					agentDir: path.resolve(sessionsRoot, ".."),
+					sessionsRoot,
+				});
+				if (scope.kind !== "resolved") {
+					logger.warn("Skipped invalid managed session scope during global listing", { message: scope.message });
+					continue;
+				}
+				const listing = listManagedCandidates(scope.scope);
+				if (listing.kind !== "complete") {
+					logger.warn("Skipped unreadable managed session scope during global listing", {
+						message: listing.message,
+					});
+					continue;
+				}
+				if (listing.invalid.length > 0)
+					logger.warn("Ignored invalid managed session candidates during global listing", {
+						count: listing.invalid.length,
+					});
+				for (const candidate of listing.owned) logicalFiles.add(candidate.path);
+			}
+			return await collectSessionsFromFiles([...logicalFiles], storage);
 		} catch {
 			return [];
 		}