@gajae-code/coding-agent 0.16.0 → 0.16.3

package/src/session/session-manager.ts

@@ -23,7 +23,19 @@ function nativeSessionManager(): typeof import("@gajae-code/natives") {
 	return require("@gajae-code/natives") as typeof import("@gajae-code/natives");
 }
 const cwdTransitionAls = new AsyncLocalStorage<symbol>();
-type CwdReadLeaseContext = { active: boolean; owner: symbol };
+type CwdReadLeaseContext = {
+	active: boolean;
+	released: boolean;
+	owner: symbol;
+	suspendedMoveCount: number;
+	committedMoveGeneration?: number;
+	/** Execution-local lineage; sibling tool executions never share this context. */
+	parent?: CwdReadLeaseContext;
+	root?: CwdReadLeaseContext;
+	executionId: symbol;
+	activeBranches: number;
+	suspendedMoveOwner?: symbol;
+};
 const cwdReadLeaseAls = new AsyncLocalStorage<CwdReadLeaseContext>();
 const CWD_NOFOLLOW_OPEN_FLAGS =
 	fs.constants.O_RDONLY |
@@ -246,6 +258,8 @@ export interface SessionHeader {
 	id: string;
 	title?: string; // Auto-generated title from first message
 	titleSource?: "auto" | "user";
+	starredPatchVersion?: 1;
+	starred?: boolean;
 	timestamp: string;
 	cwd: string;
 	parentSession?: string;
@@ -931,7 +945,7 @@ export type SessionEntry =
 /** Append-only replacement for mutable fields on the session header. */
 export interface HeaderPatchRecord {
 	type: "header_patch";
-	patch: Partial<Pick<SessionHeader, "title" | "titleSource" | "cwd">>;
+	patch: Partial<Pick<SessionHeader, "title" | "titleSource" | "cwd" | "starred">>;
 }
 
 /** Append-only replacement for replay metadata on one existing session entry. */
@@ -2390,6 +2404,7 @@ export interface SessionInfo {
 	/** Working directory where the session was started. Empty string for old sessions. */
 	cwd: string;
 	title?: string;
+	starred: boolean;
 	/** Path to the parent session (if this session was forked). */
 	parentSessionPath?: string;
 	created: Date;
@@ -2699,12 +2714,13 @@ function isHeaderPatchRecord(record: SessionPatchRecord): record is HeaderPatchR
 	)
 		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;
+	if (!keys.every(key => key === "cwd" || key === "title" || key === "titleSource" || key === "starred")) return false;
+	const { cwd, title, titleSource, starred } = record.patch;
 	return (
 		(cwd === undefined || typeof cwd === "string") &&
 		(title === undefined || typeof title === "string") &&
-		(titleSource === undefined || titleSource === "auto" || titleSource === "user")
+		(titleSource === undefined || titleSource === "auto" || titleSource === "user") &&
+		(starred === undefined || typeof starred === "boolean")
 	);
 }
 
@@ -2712,6 +2728,7 @@ function applyHeaderPatch(header: SessionHeader, patch: HeaderPatchRecord["patch
 	if (patch.cwd !== undefined) header.cwd = patch.cwd;
 	if (patch.title !== undefined) header.title = patch.title;
 	if (patch.titleSource !== undefined) header.titleSource = patch.titleSource;
+	if (header.starredPatchVersion === 1 && patch.starred !== undefined) header.starred = patch.starred;
 }
 
 function isEntryPatchRecord(record: SessionPatchRecord): record is EntryPatchRecord {
@@ -4654,7 +4671,7 @@ async function getSortedSessions(
 						)
 							return undefined;
 						if (typeof header.version === "number" && header.version >= 4) {
-							for (const patch of await readSessionListTrailingPatches(candidate.path, storage)) {
+							for (const patch of await readSessionListTrailingPatches(candidate.path, storage, false)) {
 								applySessionListHeaderPatch(header as unknown as SessionListHeader, patch);
 							}
 						}
@@ -6413,6 +6430,10 @@ async function collectProjectSessions(cwd: string, storage: FileSessionStorage):
 	return await collectSessionsFromFiles(listProjectSessionTranscriptFiles(cwd), storage);
 }
 
+export function prioritizeStarredSessions(sessions: readonly SessionInfo[]): SessionInfo[] {
+	return [...sessions.filter(session => session.starred), ...sessions.filter(session => !session.starred)];
+}
+
 function mergeSessionInventories(...inventories: SessionInfo[][]): SessionInfo[] {
 	const sessions = new Map<string, SessionInfo>();
 	for (const inventory of inventories) {
@@ -6574,36 +6595,41 @@ async function readSessionListPrefix(file: string, storage: SessionStorage, buff
 async function readSessionListTrailingPatches(
 	file: string,
 	storage: SessionStorage,
+	includeStarred: boolean,
 ): 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 }] : [];
+		return header?.type === "session"
+			? [{ cwd: header.cwd, title: header.title, ...(includeStarred ? { starred: header.starred } : {}) }]
+			: [];
 	}
 
 	const size = storage.statSync(file).size;
 	if (size <= SESSION_LIST_PREFIX_BYTES) return [];
 	const latest: HeaderPatchRecord["patch"] = {};
 	let position = size;
-	// Reverse-scan from EOF in fixed chunks. Stop once both cwd and title
-	// resolve so recent patches stay cheap. Continue past the historical 16 KiB
+	// Reverse-scan from EOF in fixed chunks. Stop once every requested mutable list field
+	// resolves so recent patches stay cheap. Continue past the historical 16 KiB
 	// window when a field is still missing so a buried but canonically valid
 	// header_patch remains listable without a full sequential JSONL parse (#3633).
 	// Chunks that cannot contain a header_patch marker skip JSON parsing.
 	//
-	// The scan owns its buffer instead of borrowing the caller's 4 KiB prefix
-	// buffer. A transcript with no header_patch at all — the common case, since
-	// only /rename and workspace moves emit one — cannot be recognized without
-	// reaching BOF, so the chunk size sets how many read syscalls a resume costs
-	// per transcript byte.
+	// The scan owns its buffer instead of borrowing the caller's 4 KiB prefix.
+	// A transcript with no header_patch at all — the common case — cannot be
+	// recognized as such without reaching BOF, so the chunk size sets how many
+	// read syscalls a resume costs per transcript byte.
 	let trailingFragment = Buffer.alloc(0);
 	const chunkSize = Math.min(size, SESSION_LIST_TRAILING_PATCH_BYTES);
 	const buffer = Buffer.allocUnsafe(chunkSize);
 	const headerPatchMarker = Buffer.from("header_patch");
 	const handle = await fs.promises.open(file, "r");
 	try {
-		while (position > 0 && (latest.cwd === undefined || latest.title === undefined)) {
+		while (
+			position > 0 &&
+			(latest.cwd === undefined || latest.title === undefined || (includeStarred && latest.starred === undefined))
+		) {
 			const start = Math.max(0, position - chunkSize);
 			const length = position - start;
 			const { bytesRead } = await handle.read(buffer, 0, length, start);
@@ -6636,6 +6662,8 @@ async function readSessionListTrailingPatches(
 						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;
+						if (includeStarred && latest.starred === undefined && typeof record.patch.starred === "boolean")
+							latest.starred = record.patch.starred;
 					} catch {
 						// Ignore malformed or partial records exactly as the canonical loader does.
 					}
@@ -6643,7 +6671,7 @@ async function readSessionListTrailingPatches(
 			}
 			position = start;
 		}
-		return latest.cwd === undefined && latest.title === undefined ? [] : [latest];
+		return latest.cwd === undefined && latest.title === undefined && latest.starred === undefined ? [] : [latest];
 	} finally {
 		await handle.close();
 	}
@@ -6652,6 +6680,7 @@ async function readSessionListTrailingPatches(
 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;
+	if (typeof patch.starred === "boolean") header.starred = patch.starred;
 }
 function decodeJsonStringFragment(value: string): string {
 	const safeValue = value.endsWith("\\") ? value.slice(0, -1) : value;
@@ -6702,6 +6731,79 @@ function extractStringProperty(source: string, name: string, startIndex = 0): st
 	return decodeJsonStringFragment(source.slice(valueStart));
 }
 
+function extractTopLevelPrimitiveProperty(source: string, name: string): string | undefined {
+	let depth = 0;
+	let latest: string | undefined;
+	for (let index = 0; index < source.length; index++) {
+		const char = source.charCodeAt(index);
+		if (char === 0x7b || char === 0x5b) {
+			depth++;
+			continue;
+		}
+		if (char === 0x7d || char === 0x5d) {
+			depth--;
+			continue;
+		}
+		if (char !== 0x22) continue;
+
+		const keyStart = index;
+		let escaped = false;
+		for (index++; index < source.length; index++) {
+			const stringChar = source.charCodeAt(index);
+			if (escaped) {
+				escaped = false;
+				continue;
+			}
+			if (stringChar === 0x5c) {
+				escaped = true;
+				continue;
+			}
+			if (stringChar === 0x22) break;
+		}
+		if (index >= source.length || depth !== 1) continue;
+
+		let key: unknown;
+		try {
+			key = JSON.parse(source.slice(keyStart, index + 1));
+		} catch {
+			continue;
+		}
+		if (key !== name) continue;
+
+		let valueStart = index + 1;
+		while (valueStart < source.length && /\s/.test(source[valueStart]!)) valueStart++;
+		if (source.charCodeAt(valueStart) !== 0x3a) continue;
+		valueStart++;
+		while (valueStart < source.length && /\s/.test(source[valueStart]!)) valueStart++;
+
+		let valueEnd = valueStart;
+		while (
+			valueEnd < source.length &&
+			source[valueEnd] !== "," &&
+			source[valueEnd] !== "}" &&
+			!/\s/.test(source[valueEnd]!)
+		)
+			valueEnd++;
+		latest = source.slice(valueStart, valueEnd);
+		index = valueEnd - 1;
+	}
+	return latest;
+}
+
+function extractTopLevelIntegerProperty(source: string, name: string): number | undefined {
+	const token = extractTopLevelPrimitiveProperty(source, name);
+	if (token === undefined || !/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(token)) return undefined;
+	const value = Number(token);
+	return Number.isSafeInteger(value) ? value : undefined;
+}
+
+function extractTopLevelBooleanProperty(source: string, name: string): boolean | undefined {
+	const token = extractTopLevelPrimitiveProperty(source, name);
+	if (token === "true") return true;
+	if (token === "false") return false;
+	return undefined;
+}
+
 function countMessageMarkers(content: string): number {
 	let count = 0;
 	let index = 0;
@@ -6740,6 +6842,8 @@ interface SessionListHeader {
 
 	cwd?: string;
 	title?: string;
+	starredPatchVersion?: 1;
+	starred?: boolean;
 	parentSession?: string;
 	timestamp?: string;
 }
@@ -6748,6 +6852,10 @@ function parseSessionListHeader(
 	content: string,
 	entries: Array<Record<string, unknown>>,
 ): SessionListHeader | undefined {
+	const firstLineEnd = content.indexOf("\n");
+	const firstLine = firstLineEnd === -1 ? content : content.slice(0, firstLineEnd);
+	const inlineStarred = extractTopLevelBooleanProperty(firstLine, "starred");
+	const starredPatchVersion = extractTopLevelIntegerProperty(firstLine, "starredPatchVersion") === 1 ? 1 : undefined;
 	const parsedHeader = entries[0];
 	if (parsedHeader?.type === "session" && typeof parsedHeader.id === "string") {
 		return {
@@ -6756,13 +6864,13 @@ function parseSessionListHeader(
 			version: typeof parsedHeader.version === "number" ? parsedHeader.version : undefined,
 			cwd: typeof parsedHeader.cwd === "string" ? parsedHeader.cwd : undefined,
 			title: typeof parsedHeader.title === "string" ? parsedHeader.title : undefined,
+			starredPatchVersion: parsedHeader.starredPatchVersion === 1 ? 1 : starredPatchVersion,
+			starred: typeof parsedHeader.starred === "boolean" ? parsedHeader.starred : inlineStarred,
 			parentSession: typeof parsedHeader.parentSession === "string" ? parsedHeader.parentSession : undefined,
 			timestamp: typeof parsedHeader.timestamp === "string" ? parsedHeader.timestamp : undefined,
 		};
 	}
 
-	const firstLineEnd = content.indexOf("\n");
-	const firstLine = firstLineEnd === -1 ? content : content.slice(0, firstLineEnd);
 	if (extractStringProperty(firstLine, "type") !== "session") return undefined;
 
 	const id = extractStringProperty(firstLine, "id");
@@ -6771,9 +6879,11 @@ function parseSessionListHeader(
 	return {
 		type: "session",
 		id,
-		version: Number(extractStringProperty(firstLine, "version")) || undefined,
+		version: extractTopLevelIntegerProperty(firstLine, "version"),
 		cwd: extractStringProperty(firstLine, "cwd"),
 		title: extractStringProperty(firstLine, "title"),
+		starred: inlineStarred,
+		starredPatchVersion,
 		parentSession: extractStringProperty(firstLine, "parentSession"),
 		timestamp: extractStringProperty(firstLine, "timestamp"),
 	};
@@ -6798,8 +6908,9 @@ async function collectSessionFromFile(
 		const entries = parseSessionEntries(content).map(entry => entry as unknown as Record<string, unknown>);
 		const header = parseSessionListHeader(content, entries);
 		if (!header) return undefined;
+		if (header.starredPatchVersion !== 1) header.starred = undefined;
 		if (typeof header.version === "number" && header.version >= 4 && header.version <= CURRENT_SESSION_VERSION) {
-			for (const patch of await readSessionListTrailingPatches(file, storage)) {
+			for (const patch of await readSessionListTrailingPatches(file, storage, header.starredPatchVersion === 1)) {
 				applySessionListHeaderPatch(header, patch);
 			}
 		}
@@ -6841,6 +6952,7 @@ async function collectSessionFromFile(
 			id: header.id,
 			cwd: header.cwd ?? "",
 			title: header.title ?? shortSummary,
+			starred: header.starred === true,
 			parentSessionPath: header.parentSession,
 			created: new Date(header.timestamp ?? ""),
 			modified: stats.mtime,
@@ -7268,6 +7380,7 @@ export class SessionManager {
 	#flushed: boolean = false;
 	#needsFullRewriteOnNextPersist: boolean = false;
 	#readOnlyResume = false;
+	#strictResumeMutationPending = false;
 	#resumedDraftConsumed = false;
 	#ensuredOnDisk: boolean = false;
 	#recoveryHydrationContext: RecoveryHydrationContext | undefined;
@@ -7296,10 +7409,16 @@ export class SessionManager {
 	/** Defense-in-depth (#4443): one-shot warn for adjacent private thinking blocks in persisted assistant transcripts. */
 	#warnedAdjacentThinkingPersist = false;
 	#closeRetryPending = false;
+	#strictClosePending = false;
 	/** Serializes model, SDK, and ACP cwd transitions; dispose joins this tail. */
 	#cwdTransitionTail: Promise<void> = Promise.resolve();
 	#cwdTransitionOwner: symbol | undefined;
+	#cwdMoveAdmissionClosing = false;
 	#cwdMoveAdmissionClosed = false;
+	#pendingCwdMoveAdmissions = new Set<AbortController>();
+	#cwdMoveAdmittedAdmissions = new Set<AbortController>();
+	#cwdMoveAdmittedOwners = new Set<symbol>();
+	#cwdMoveAdmittedOwnerCounts = new Map<symbol, number>();
 	#cwdReadLeaseOwner = Symbol("cwd-read-lease-owner");
 	#cwdGeneration = 0;
 	/**
@@ -8165,6 +8284,7 @@ export class SessionManager {
 			header: {
 				type: "session",
 				version: CURRENT_SESSION_VERSION,
+				starredPatchVersion: 1,
 				id: sessionId,
 				timestamp,
 				cwd: this.cwd,
@@ -9721,6 +9841,7 @@ export class SessionManager {
 		const header: SessionHeader = {
 			type: "session",
 			version: CURRENT_SESSION_VERSION,
+			starredPatchVersion: 1,
 			id: sessionId,
 			timestamp,
 			cwd: this.cwd,
@@ -9929,6 +10050,7 @@ export class SessionManager {
 		const header: SessionHeader = {
 			type: "session",
 			version: CURRENT_SESSION_VERSION,
+			starredPatchVersion: 1,
 			id: sessionId,
 			title: this.#sessionName,
 			titleSource: this.#titleSource,
@@ -9997,6 +10119,7 @@ export class SessionManager {
 		const header: SessionHeader = {
 			type: "session",
 			version: CURRENT_SESSION_VERSION,
+			starredPatchVersion: 1,
 			id: sessionId,
 			timestamp,
 			cwd: this.cwd,
@@ -10319,6 +10442,7 @@ export class SessionManager {
 		const newHeader: SessionHeader = {
 			type: "session",
 			version: CURRENT_SESSION_VERSION,
+			starredPatchVersion: 1,
 			id: newSessionId,
 			title: oldHeader?.title ?? this.#sessionName,
 			titleSource: oldHeader?.titleSource ?? this.#titleSource,
@@ -10691,11 +10815,32 @@ export class SessionManager {
 	 * only for the async context that already owns the lock — unrelated callers
 	 * queue on the tail instead of skipping it.
 	 */
-	async runExclusiveCwdTransition<T>(fn: () => Promise<T>): Promise<T> {
+	async runExclusiveCwdTransition<T>(fn: () => Promise<T>, options?: { signal?: AbortSignal }): Promise<T> {
 		const owner = this.#cwdTransitionOwner;
 		if (owner !== undefined && cwdTransitionAls.getStore() === owner) {
 			return fn();
 		}
+		const signal = options?.signal;
+		const throwIfAborted = (): void => {
+			if (!signal?.aborted) return;
+			throw signal.reason instanceof Error ? signal.reason : new Error("Session cwd move admission is closed.");
+		};
+		const waitAbortably = async (promise: Promise<void>): Promise<void> => {
+			throwIfAborted();
+			if (!signal) {
+				await promise;
+				return;
+			}
+			const aborted = Promise.withResolvers<void>();
+			const onAbort = () => aborted.resolve();
+			signal.addEventListener("abort", onAbort, { once: true });
+			try {
+				await Promise.race([promise, aborted.promise]);
+			} finally {
+				signal.removeEventListener("abort", onAbort);
+			}
+			throwIfAborted();
+		};
 		const previous = this.#cwdTransitionTail;
 		const { promise, resolve } = Promise.withResolvers<void>();
 		this.#cwdTransitionTail = previous.then(
@@ -10707,11 +10852,11 @@ export class SessionManager {
 		this.#cwdWriterPending += 1;
 		const token = Symbol("cwd-transition");
 		try {
-			await previous.catch(() => {});
+			await waitAbortably(previous.catch(() => {}));
 			// A reader that entered before this writer was announced still holds the
 			// old cwd; the transition may not commit until every such lease is
 			// released, otherwise an in-flight tool resolves paths across the move.
-			while (this.#cwdReaderCount > 0) await this.#cwdReadersIdle;
+			while (this.#cwdReaderCount > 0) await waitAbortably(this.#cwdReadersIdle);
 			this.#cwdTransitionOwner = token;
 			return await cwdTransitionAls.run(token, fn);
 		} finally {
@@ -10721,6 +10866,90 @@ export class SessionManager {
 		}
 	}
 
+	async runExclusiveCwdMoveTransition<T>(fn: () => Promise<T>): Promise<T> {
+		if (this.#cwdMoveAdmissionClosing || this.#cwdMoveAdmissionClosed)
+			throw new Error("Session cwd move admission is closed.");
+		const transitionOwner = this.#cwdTransitionOwner;
+		if (
+			this.#strictClosePending &&
+			(transitionOwner === undefined || cwdTransitionAls.getStore() !== transitionOwner)
+		)
+			throw new Error("Session manager is closing.");
+		const readLease = cwdReadLeaseAls.getStore();
+		const rootLease =
+			readLease?.owner === this.#cwdReadLeaseOwner && !readLease.released
+				? (readLease.root ?? readLease)
+				: undefined;
+		const suspendedOwnReadLease = rootLease !== undefined;
+		if (rootLease) {
+			// A move may suspend the shared root lease only when this execution is
+			// the sole active descendant. If a sibling tool is still fenced by the
+			// lease, returning a retry error is safer than restoring the lease while
+			// that sibling continues against the old cwd.
+			const activeBranchLimit = readLease === rootLease ? 1 : 2;
+			if (
+				rootLease.activeBranches > activeBranchLimit ||
+				(rootLease.suspendedMoveOwner !== undefined && rootLease.suspendedMoveOwner !== readLease?.executionId)
+			)
+				throw new Error("Session working directory changed while this tool executed; retry against the new cwd.");
+			rootLease.suspendedMoveCount += 1;
+			rootLease.suspendedMoveOwner ??= readLease?.executionId;
+			if (rootLease.active) {
+				rootLease.active = false;
+				this.#cwdReaderCount -= 1;
+				if (this.#cwdReaderCount === 0) {
+					const drained = this.#cwdReadersDrained;
+					this.#cwdReadersDrained = undefined;
+					drained?.();
+				}
+			}
+		}
+		const admittedBeforeClose = this.#cwdWriterPending === 0 && this.#cwdReaderCount === 0;
+		const admission = new AbortController();
+		this.#pendingCwdMoveAdmissions.add(admission);
+		if (admittedBeforeClose) this.#cwdMoveAdmittedAdmissions.add(admission);
+		try {
+			return await this.runExclusiveCwdTransition(
+				async () => {
+					const owner = this.#cwdTransitionOwner;
+					if (owner === undefined) throw new Error("Session cwd move transition owner is unavailable.");
+					this.#cwdMoveAdmittedAdmissions.add(admission);
+					this.#cwdMoveAdmittedOwners.add(owner);
+					this.#cwdMoveAdmittedOwnerCounts.set(owner, (this.#cwdMoveAdmittedOwnerCounts.get(owner) ?? 0) + 1);
+					try {
+						return await fn();
+					} finally {
+						this.#cwdMoveAdmittedAdmissions.delete(admission);
+						const count = this.#cwdMoveAdmittedOwnerCounts.get(owner) ?? 0;
+						if (count <= 1) {
+							this.#cwdMoveAdmittedOwnerCounts.delete(owner);
+							this.#cwdMoveAdmittedOwners.delete(owner);
+						} else {
+							this.#cwdMoveAdmittedOwnerCounts.set(owner, count - 1);
+						}
+					}
+				},
+				{ signal: admission.signal },
+			);
+		} finally {
+			this.#pendingCwdMoveAdmissions.delete(admission);
+			this.#cwdMoveAdmittedAdmissions.delete(admission);
+			if (suspendedOwnReadLease && rootLease) {
+				rootLease.suspendedMoveCount -= 1;
+				if (rootLease.suspendedMoveCount === 0 && !rootLease.released) {
+					if (this.#cwdReaderCount === 0) {
+						const { promise, resolve } = Promise.withResolvers<void>();
+						this.#cwdReadersIdle = promise;
+						this.#cwdReadersDrained = resolve;
+					}
+					this.#cwdReaderCount += 1;
+					rootLease.active = true;
+					rootLease.suspendedMoveOwner = undefined;
+				}
+			}
+		}
+	}
+
 	/**
 	 * Run `fn` under a shared read lease on `cwd`.
 	 *
@@ -10734,14 +10963,39 @@ export class SessionManager {
 	async runWithCwdReadLease<T>(fn: () => Promise<T>): Promise<T> {
 		const activeReadLease = cwdReadLeaseAls.getStore();
 		// Nested tool dispatch (for example eval -> tool bridge) inherits the
-		// outer lease's async context. Re-entering that lease must not wait behind
-		// a writer that is already queued: the writer is waiting for the outer
-		// lease, and waiting here would deadlock the session permanently.
-		if (activeReadLease?.active && activeReadLease.owner === this.#cwdReadLeaseOwner) return fn();
+		// outer lease's cwd authority, but receives an execution-local context so
+		// sibling descendants cannot attribute one another's nested move.
+		if (activeReadLease?.owner === this.#cwdReadLeaseOwner && !activeReadLease.released) {
+			const rootLease = activeReadLease.root ?? activeReadLease;
+			if (rootLease.suspendedMoveOwner !== undefined)
+				throw new Error("Session working directory changed while this tool executed; retry against the new cwd.");
+			rootLease.activeBranches += 1;
+			const nestedReadLease: CwdReadLeaseContext = {
+				active: true,
+				released: false,
+				owner: this.#cwdReadLeaseOwner,
+				parent: activeReadLease,
+				root: rootLease,
+				executionId: Symbol("cwd-read-execution"),
+				activeBranches: 0,
+				suspendedMoveCount: 0,
+			};
+			return cwdReadLeaseAls.run(nestedReadLease, async () => {
+				try {
+					return await fn();
+				} finally {
+					if (nestedReadLease.committedMoveGeneration !== undefined)
+						activeReadLease.committedMoveGeneration = nestedReadLease.committedMoveGeneration;
+					nestedReadLease.released = true;
+					rootLease.activeBranches -= 1;
+				}
+			});
+		}
 		const owner = this.#cwdTransitionOwner;
 		// The writer's own async context already holds exclusive access; taking a
 		// read lease there would wait on itself.
 		if (owner !== undefined && cwdTransitionAls.getStore() === owner) return fn();
+		if (this.#strictClosePending || this.#cwdMoveAdmissionClosed) throw new Error("Session manager is closing.");
 		while (this.#cwdWriterPending > 0) await this.#cwdTransitionTail.catch(() => {});
 		if (this.#cwdReaderCount === 0) {
 			const { promise, resolve } = Promise.withResolvers<void>();
@@ -10749,18 +11003,29 @@ export class SessionManager {
 			this.#cwdReadersDrained = resolve;
 		}
 		this.#cwdReaderCount += 1;
-		const readLease: CwdReadLeaseContext = { active: true, owner: this.#cwdReadLeaseOwner };
+		const readLease: CwdReadLeaseContext = {
+			active: true,
+			released: false,
+			owner: this.#cwdReadLeaseOwner,
+			suspendedMoveCount: 0,
+			executionId: Symbol("cwd-read-execution"),
+			activeBranches: 1,
+		};
+		readLease.root = readLease;
 		return cwdReadLeaseAls.run(readLease, async () => {
 			try {
 				return await fn();
 			} finally {
-				readLease.active = false;
-				this.#cwdReaderCount -= 1;
-				if (this.#cwdReaderCount === 0) {
-					const drained = this.#cwdReadersDrained;
-					this.#cwdReadersDrained = undefined;
-					drained?.();
+				if (readLease.active) {
+					readLease.active = false;
+					this.#cwdReaderCount -= 1;
+					if (this.#cwdReaderCount === 0) {
+						const drained = this.#cwdReadersDrained;
+						this.#cwdReadersDrained = undefined;
+						drained?.();
+					}
 				}
+				readLease.released = true;
 			}
 		});
 	}
@@ -10770,15 +11035,36 @@ export class SessionManager {
 		await this.#cwdTransitionTail;
 	}
 
+	async joinCwdReaders(): Promise<void> {
+		while (this.#cwdReaderCount > 0) await this.#cwdReadersIdle;
+	}
+
 	async closeCwdMoveAdmission(): Promise<void> {
-		await this.runExclusiveCwdTransition(async () => {
-			this.#cwdMoveAdmissionClosed = true;
-		});
+		if (this.#cwdMoveAdmissionClosed) return;
+		if (this.#cwdMoveAdmissionClosing) return;
+		this.#cwdMoveAdmissionClosing = true;
+		this.#cwdMoveAdmissionClosed = true;
+		// Preserve moves that already acquired exclusive ownership, but cancel every
+		// queued admission. A queued writer can otherwise pass the initial admission
+		// check after an earlier writer finishes and mutate the closed session.
+		for (const admission of this.#pendingCwdMoveAdmissions) {
+			if (!this.#cwdMoveAdmittedAdmissions.has(admission)) {
+				admission.abort(new Error("Session cwd move admission is closed."));
+			}
+		}
 	}
 	getCwdGeneration(): number {
 		return this.#cwdGeneration;
 	}
 
+	/** Consume a move committed by a nested move_session call in this read lease. */
+	consumeNestedCwdMove(admittedGeneration: number): boolean {
+		const readLease = cwdReadLeaseAls.getStore();
+		const committed = readLease?.committedMoveGeneration;
+		if (readLease) readLease.committedMoveGeneration = undefined;
+		return committed !== undefined && committed !== admittedGeneration && committed === this.#cwdGeneration;
+	}
+
 	/**
 	 * Register a listener invoked after every committed `moveTo`. Returns an idempotent
 	 * unregister handle. Every move surface funnels through `moveTo`, so a single
@@ -10976,10 +11262,13 @@ export class SessionManager {
 			sourceHandle?: { stat: (opts: { bigint: true }) => Promise<fs.BigIntStats> };
 		},
 	): Promise<void> {
+		if (this.#strictClosePending && !this.#ownsCwdTransition()) throw new Error("Session manager is closing.");
 		if (!this.#ownsCwdTransition()) {
-			return this.runExclusiveCwdTransition(() => this.moveTo(newCwd, options));
+			return this.runExclusiveCwdMoveTransition(() => this.moveTo(newCwd, options));
 		}
-		if (this.#cwdMoveAdmissionClosed) throw new Error("Session cwd move admission is closed.");
+		const owner = this.#cwdTransitionOwner;
+		if (this.#cwdMoveAdmissionClosed && (owner === undefined || !this.#cwdMoveAdmittedOwners.has(owner)))
+			throw new Error("Session cwd move admission is closed.");
 		if (!options?.sourceHandle) {
 			const sourceHandle = await SessionManager.openNoFollowDirectory(this.cwd);
 			try {
@@ -11366,6 +11655,12 @@ export class SessionManager {
 			}
 		}
 		this.#cwdGeneration += 1;
+		const readLease = cwdReadLeaseAls.getStore();
+		if (readLease?.owner === this.#cwdReadLeaseOwner) {
+			readLease.committedMoveGeneration = this.#cwdGeneration;
+			for (let parent = readLease.parent; parent; parent = parent.parent)
+				parent.committedMoveGeneration = this.#cwdGeneration;
+		}
 		this.cwd = resolvedCwd;
 		this.sessionDir = newSessionDir;
 		this.destination = nextDestination;
@@ -11384,13 +11679,13 @@ export class SessionManager {
 		const hasAssistant = this.#fileEntries.some(e => e.type === "message" && e.message.role === "assistant");
 		try {
 			if (this.persist && this.#sessionFile && hadSessionFile) {
-				await this.#appendHeaderPatch({ cwd: resolvedCwd });
+				await this.#appendHeaderPatch({ cwd: resolvedCwd }, { allowStrictClose: true });
 				await this.#rewriteFile();
 			} else if (this.persist && this.#sessionFile && (hasAssistant || (!hadSessionFile && hadPersistedSession))) {
-				await this.#appendHeaderPatch({ cwd: resolvedCwd });
+				await this.#appendHeaderPatch({ cwd: resolvedCwd }, { allowStrictClose: true });
 				await this.#rewriteFile();
 			} else {
-				await this.#appendHeaderPatch({ cwd: resolvedCwd });
+				await this.#appendHeaderPatch({ cwd: resolvedCwd }, { allowStrictClose: true });
 			}
 		} catch (error) {
 			residentTransition?.dispose();
@@ -15797,6 +16092,7 @@ export class SessionManager {
 	 * Used by ACP mode where session/new must create a discoverable session immediately.
 	 */
 	async ensureOnDisk(): Promise<void> {
+		this.#assertRecoveryHydrationWritable();
 		if (!this.persist || !this.#sessionFile) return;
 		if (this.#readOnlyResume) return;
 		if (this.#flushed && !this.#needsFullRewriteOnNextPersist) return;
@@ -15906,7 +16202,9 @@ export class SessionManager {
 
 	/** Close the persistent writer after flushing all pending data. */
 	async close(): Promise<void> {
+		await this.closeCwdMoveAdmission();
 		await this.joinCwdTransition();
+		await this.joinCwdReaders();
 		SessionManager.releaseProcessCwdOwnership(this);
 		// Drain any uncommitted prepared successors before releasing resources so
 		// dispose/shutdown retains exact cleanup authority (#3138).
@@ -15948,10 +16246,16 @@ export class SessionManager {
 	}
 	/** Flush while open, then strictly close; retryable close skips the invalid second flush. */
 	async flushAndCloseStrict(): Promise<SessionManagerCloseOutcome> {
+		let priorFlushError: Error | undefined;
 		if (this.#persistWriter?.getCloseState() !== "close_failed_retryable") {
-			await this.flush();
+			try {
+				await this.flush();
+			} catch (error) {
+				priorFlushError = toError(error);
+			}
 		}
-		return this.closeStrict();
+		const outcome = await this.closeStrict();
+		return priorFlushError && outcome.kind === "closed" ? { kind: "close_unknown", error: priorFlushError } : outcome;
 	}
 
 	/**
@@ -15961,45 +16265,114 @@ export class SessionManager {
 	 * writer closure before any destructive operation.
 	 */
 	async closeStrict(): Promise<SessionManagerCloseOutcome> {
+		this.#strictClosePending = true;
+		await this.closeCwdMoveAdmission();
+		await this.joinCwdTransition();
+		await this.joinCwdReaders();
 		// Drain staged successors on the strict ACP dispose path as well as best-effort close (#3138).
+		let preparedCleanupError: Error | undefined;
 		try {
 			await this.#retryPreparedNewSessionCleanups();
 		} catch (error) {
+			preparedCleanupError = toError(error);
 			logger.warn("Prepared session cleanup during closeStrict failed; retained for retry", {
-				error: toError(error).message,
+				error: preparedCleanupError.message,
 			});
 		}
-		let outcome: SessionManagerCloseOutcome = { kind: "closed" };
-		await this.#queuePersistTask(async () => {
-			const writer = this.#persistWriter;
-			if (!writer) {
-				this.#flushed = true;
-				return;
+		if (preparedCleanupError) return { kind: "close_failed_retryable", error: preparedCleanupError };
+		let priorPersistError = this.#persistError;
+		if (this.#needsFullRewriteOnNextPersist && (!this.#readOnlyResume || this.#strictResumeMutationPending)) {
+			await this.#persistChain.catch(() => {});
+			try {
+				await this.#rewriteFileContents();
+				if (this.#strictResumeMutationPending && this.#readOnlyResume && this.#sessionFile) {
+					writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
+					this.#readOnlyResume = false;
+				}
+				this.#strictResumeMutationPending = false;
+			} catch (error) {
+				priorPersistError ??= toError(error);
+				return { kind: "close_failed_retryable", error: priorPersistError };
 			}
+		}
+		let outcome: SessionManagerCloseOutcome = { kind: "closed" };
+		const closePublicationRevision = {
+			entry: this.#entryRevision,
+			header: this.#headerExportRevision,
+			residentBlob: this.#residentBlobRevision,
+		};
+		await this.#queuePersistTask(
+			async () => {
+				const writer = this.#persistWriter;
+				if (!writer) {
+					this.#flushed = true;
+					return;
+				}
+				try {
+					await writer.close();
+				} catch {
+					// Outcome is captured from the underlying writer's close state below.
+				}
+				outcome = this.#closeOutcomeFromWriter(writer);
+				if (outcome.kind === "closed") {
+					this.#flushed = true;
+					// Confirmed closed: release writer ownership.
+					this.#persistWriter = undefined;
+					this.#persistWriterPath = undefined;
+				} else if (outcome.kind === "close_unknown") {
+					// Quarantined (terminal): release ownership so no retry/finalizer
+					// touches the uncertain fd again.
+					this.#persistWriter = undefined;
+					this.#persistWriterPath = undefined;
+				}
+				// close_failed_retryable: RETAIN the writer so a later closeStrict() call
+				// can actually re-dispatch the OS close (ownership stays proven). The
+				// wrapper must not manufacture success or surrender a retryable fd.
+			},
+			{ ignoreError: true },
+		);
+		// A mutation that entered before strict-close admission can finish its
+		// asynchronous preparation after the initial rewrite check. Re-check the
+		// publication debt after writer closure and repair it before releasing any
+		// resident state; strict admission prevents new callers from creating a
+		// second race while this repair is in flight.
+		let observedPersistError = priorPersistError ?? this.#persistError;
+		const mutationDuringWriterClose =
+			this.#entryRevision !== closePublicationRevision.entry ||
+			this.#headerExportRevision !== closePublicationRevision.header ||
+			this.#residentBlobRevision !== closePublicationRevision.residentBlob;
+		if (mutationDuringWriterClose) {
+			this.#needsFullRewriteOnNextPersist = true;
+			if (this.#readOnlyResume) this.#strictResumeMutationPending = true;
+		}
+		const lateRewriteDebt =
+			(this.#needsFullRewriteOnNextPersist || this.#strictResumeMutationPending) &&
+			(!this.#readOnlyResume || this.#strictResumeMutationPending);
+		if (!observedPersistError && outcome.kind === "closed" && !this.#persistWriter && lateRewriteDebt) {
 			try {
-				await writer.close();
-			} catch {
-				// Outcome is captured from the underlying writer's close state below.
+				await this.#rewriteFileContents();
+				if (this.#strictResumeMutationPending && this.#readOnlyResume && this.#sessionFile) {
+					writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
+					this.#readOnlyResume = false;
+				}
+				this.#strictResumeMutationPending = false;
+			} catch (error) {
+				observedPersistError = toError(error);
+				outcome = { kind: "close_failed_retryable", error: observedPersistError };
 			}
-			outcome = this.#closeOutcomeFromWriter(writer);
-			if (outcome.kind === "closed") {
-				this.#flushed = true;
-				// Confirmed closed: release writer ownership.
-				this.#persistWriter = undefined;
-				this.#persistWriterPath = undefined;
-			} else if (outcome.kind === "close_unknown") {
-				// Quarantined (terminal): release ownership so no retry/finalizer
-				// touches the uncertain fd again.
-				this.#persistWriter = undefined;
-				this.#persistWriterPath = undefined;
-			}
-			// close_failed_retryable: RETAIN the writer so a later closeStrict() call
-			// can actually re-dispatch the OS close (ownership stays proven). The
-			// wrapper must not manufacture success or surrender a retryable fd.
-		});
+		}
+		const unpublishedMutation =
+			this.persist &&
+			(this.#strictResumeMutationPending || (this.#needsFullRewriteOnNextPersist && !this.#readOnlyResume));
 		// Only tear down the resident blob store on a terminal outcome; a retryable
 		// close leaves the session live for a genuine retry.
-		if (!this.#persistWriter) {
+		if (
+			!observedPersistError &&
+			!this.#persistWriter &&
+			(!this.persist ||
+				(this.#readOnlyResume && !this.#strictResumeMutationPending) ||
+				(!this.#needsFullRewriteOnNextPersist && !this.#strictResumeMutationPending))
+		) {
 			this.#releaseResidentTextStore();
 			this.#retireEphemeralArtifacts();
 			try {
@@ -16010,6 +16383,15 @@ export class SessionManager {
 			if (this.#preparedNewSessions.size === 0) this.#releaseOwnedManagedAuthority();
 			this.#releaseClosedSessionState();
 		}
+		if (!observedPersistError && !this.#persistWriter && unpublishedMutation && outcome.kind === "closed") {
+			outcome = {
+				kind: "close_failed_retryable",
+				error: new Error("Session manager has unpublished state."),
+			};
+		}
+		if (observedPersistError && outcome.kind === "closed") {
+			return { kind: "close_unknown", error: observedPersistError };
+		}
 		return outcome;
 	}
 
@@ -16888,6 +17270,49 @@ export class SessionManager {
 		return this.#sessionName;
 	}
 
+	isSessionStarred(): boolean {
+		const header = this.#fileEntries.find(entry => entry.type === "session") as SessionHeader | undefined;
+		return header?.starredPatchVersion === 1 && header.starred === true;
+	}
+
+	async setSessionStarred(starred: boolean): Promise<boolean> {
+		this.#assertRecoveryHydrationWritable();
+		const header = this.#fileEntries.find(entry => entry.type === "session") as SessionHeader | undefined;
+		if (!header || this.isSessionStarred() === starred) return false;
+		await this.#ensureStarPatchCapability(header);
+		const previous = header.starred;
+		try {
+			await this.#appendHeaderPatch({ starred });
+			return true;
+		} catch (error) {
+			if (previous === undefined) delete header.starred;
+			else header.starred = previous;
+			this.#headerExportRevision++;
+			throw error;
+		}
+	}
+
+	async #ensureStarPatchCapability(header: SessionHeader): Promise<void> {
+		if (header.starredPatchVersion === 1) return;
+		const previousStarred = header.starred;
+		const previousRewriteRequired = this.#needsFullRewriteOnNextPersist;
+		header.starredPatchVersion = 1;
+		delete header.starred;
+		this.#headerExportRevision++;
+		if (!this.persist || !this.#sessionFile || !this.#storage.existsSync(this.#sessionFile)) return;
+		this.#needsFullRewriteOnNextPersist = true;
+		try {
+			await this.#persistPatches([{ type: "header_patch", patch: {} }]);
+		} catch (error) {
+			delete header.starredPatchVersion;
+			if (previousStarred === undefined) delete header.starred;
+			else header.starred = previousStarred;
+			this.#needsFullRewriteOnNextPersist = previousRewriteRequired;
+			this.#headerExportRevision++;
+			throw error;
+		}
+	}
+
 	/** Strip C0/C1 control characters (includes ESC, so removes ANSI sequences) and collapse whitespace. */
 	static #sanitizeName(name: string): string {
 		return name
@@ -16904,6 +17329,7 @@ export class SessionManager {
 	 */
 	#assertRecoveryHydrationWritable(): void {
 		if (this.#recoveryHydrationContext) throw new Error("recovery_hydration_not_promoted");
+		if (this.#strictClosePending) throw new Error("Session manager is closing.");
 	}
 	async setSessionName(name: string, source: "auto" | "user" = "auto"): Promise<boolean> {
 		this.#assertRecoveryHydrationWritable();
@@ -16919,12 +17345,25 @@ export class SessionManager {
 		return true;
 	}
 
-	async #appendHeaderPatch(patch: HeaderPatchRecord["patch"]): Promise<void> {
+	async #appendHeaderPatch(
+		patch: HeaderPatchRecord["patch"],
+		options?: { allowStrictClose?: boolean },
+	): Promise<void> {
+		if (options?.allowStrictClose) {
+			if (this.#recoveryHydrationContext) throw new Error("recovery_hydration_not_promoted");
+		} else this.#assertRecoveryHydrationWritable();
 		const header = this.#fileEntries.find(entry => entry.type === "session") as SessionHeader | undefined;
 		if (!header) return;
 		applyHeaderPatch(header, patch);
 		this.#headerExportRevision++;
-		await this.#persistPatch({ type: "header_patch", patch });
+		const records: HeaderPatchRecord[] =
+			header.starredPatchVersion === 1 && patch.starred === undefined
+				? [
+						{ type: "header_patch", patch: { starred: header.starred === true } },
+						{ type: "header_patch", patch },
+					]
+				: [{ type: "header_patch", patch }];
+		await this.#persistPatches(records);
 	}
 
 	#appendManagedRecordsSync(records: readonly (FileEntry | SessionPatchRecord)[]): void {
@@ -16957,10 +17396,6 @@ export class SessionManager {
 		});
 	}
 
-	async #persistPatch(record: SessionPatchRecord): Promise<void> {
-		await this.#persistPatches([record]);
-	}
-
 	async #persistPatches(records: readonly SessionPatchRecord[]): Promise<void> {
 		if (records.length === 0) return;
 		if (this.#coldSidecarActive()) this.#deactivateColdForBranchMutation();
@@ -17027,6 +17462,7 @@ export class SessionManager {
 	}
 	_persist(entry: SessionEntry): void {
 		if (!this.persist || !this.#sessionFile) return;
+		if (this.#strictClosePending) throw new Error("Session manager is closing.");
 		const publishResumeBreadcrumb = this.#readOnlyResume;
 		if (this.#persistError) throw this.#persistError;
 
@@ -17615,6 +18051,7 @@ export class SessionManager {
 	 */
 	applyEntryMessageUpdates(entries: readonly SessionMessageEntry[]): void {
 		this.#assertRecoveryHydrationWritable();
+		if (this.#readOnlyResume) this.#strictResumeMutationPending = true;
 		this.#deactivateColdForBranchMutation();
 		for (const updated of entries) {
 			const canonical = this.#byId.get(updated.id);
@@ -17636,6 +18073,7 @@ export class SessionManager {
 		options: { preserveEvictedContent?: boolean } = {},
 	): void {
 		this.#assertRecoveryHydrationWritable();
+		if (this.#readOnlyResume) this.#strictResumeMutationPending = true;
 		this.#deactivateColdForBranchMutation();
 		for (const updated of entries) {
 			const canonical = this.#byId.get(updated.id);
@@ -17663,6 +18101,7 @@ export class SessionManager {
 	 * boundary for both managed and explicit persistent destinations.
 	 */
 	async recoverPersistenceFailure(): Promise<void> {
+		this.#assertRecoveryHydrationWritable();
 		const persistenceError = this.#persistError;
 		if (!persistenceError) return;
 		if (!this.#sessionFile) throw persistenceError;
@@ -18814,6 +19253,7 @@ export class SessionManager {
 		const header: SessionHeader = {
 			type: "session",
 			version: CURRENT_SESSION_VERSION,
+			starredPatchVersion: 1,
 			id: newSessionId,
 			timestamp,
 			cwd: this.cwd,