@gajae-code/coding-agent 0.14.2 → 0.15.0

package/src/session/session-manager.ts

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 
@@ -21,6 +22,13 @@ import type * as native from "@gajae-code/natives";
 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 };
+const cwdReadLeaseAls = new AsyncLocalStorage<CwdReadLeaseContext>();
+const CWD_NOFOLLOW_OPEN_FLAGS =
+	fs.constants.O_RDONLY |
+	(typeof fs.constants.O_DIRECTORY === "number" ? fs.constants.O_DIRECTORY : 0) |
+	(process.platform === "win32" ? 0 : (fs.constants.O_NOFOLLOW ?? 0));
 
 import { getTerminalId } from "@gajae-code/tui";
 import {
@@ -194,6 +202,7 @@ import {
 	stripInternalDetailsFields,
 } from "./messages";
 import { type SessionManagerReadAccess, sessionManagerReadCapability } from "./session-manager-internal";
+import { isStagedSessionPath, SESSION_STAGING_DIRNAME } from "./session-staging-paths";
 import type {
 	ManagedSessionSecurityContext,
 	SessionStorage,
@@ -281,6 +290,103 @@ interface PreparedNewSessionState extends PreparedNewSession {
 type ResidentTransitionFailurePolicy = "install-staged" | "memory-fallback" | "retain-and-throw" | "memory-only";
 type ResidentBlobMissingPolicy = "throw" | "placeholder";
 
+const MAX_STAGED_ATTEMPT_ID_LENGTH = 128;
+
+function assertSafeStagedAttemptId(attemptId: string): void {
+	if (!/^[A-Za-z0-9_-]{1,128}$/.test(attemptId) || attemptId.length > MAX_STAGED_ATTEMPT_ID_LENGTH)
+		throw new Error("Unsafe artifact attempt id");
+}
+
+const ATTEMPT_REMAP_STRUCTURAL_KEYS = new Set(["id", "parentId", "timestamp"]);
+const ARTIFACT_REFERENCE_KEYS = new Set([
+	"artifactId",
+	"artifactIds",
+	"artifactRef",
+	"artifactRefs",
+	"agentId",
+	"agentIds",
+	"agentRef",
+	"agentRefs",
+]);
+/**
+ * Trailing-selector grammar mirrored from `splitPathAndSel` / `splitInternalUrlSel` in
+ * `src/tools/path-utils.ts`. It is duplicated rather than imported because `path-utils` pulls in
+ * `internal-urls`, which reaches back into the session layer and would create an import cycle.
+ * The boundary red-team suite cross-checks these against the real parser so drift fails a test.
+ */
+const SELECTOR_RANGE_RE = /^L?\d+(?:[-+]L?\d+|-)?(?:,L?\d+(?:[-+]L?\d+|-)?)*$/i;
+const SELECTOR_TAIL_RE = /^(?:L?\d+(?:[-+]L?\d+|-)?(?:,L?\d+(?:[-+]L?\d+|-)?)*|raw|conflicts)$/i;
+
+/**
+ * Decide whether a `:` directly after `<scheme>://<id>` terminates the id (so the id is a remappable
+ * reference and the tail is an opaque selector) or is part of an opaque authority (so the id must be
+ * left alone). `artifact://` splits unconditionally at the first colon; every other scheme requires a
+ * strict selector tail, so `agent://3:bogus` keeps `3:bogus` as the authority and must NOT be remapped.
+ */
+function colonTerminatesUriId(scheme: string, tail: string): boolean {
+	if (scheme.toLowerCase() === "artifact") return true;
+	if (SELECTOR_TAIL_RE.test(tail)) return true;
+	const innerColon = tail.lastIndexOf(":");
+	if (innerColon <= 0) return false;
+	const head = tail.slice(0, innerColon);
+	const last = tail.slice(innerColon + 1);
+	const headIsRaw = /^raw$/i.test(head);
+	const lastIsRaw = /^raw$/i.test(last);
+	return (headIsRaw && SELECTOR_RANGE_RE.test(last)) || (SELECTOR_RANGE_RE.test(head) && lastIsRaw);
+}
+
+function remapArtifactReferenceString(value: string, idMap: ReadonlyMap<string, string>, exactId = false): string {
+	const exact = exactId ? idMap.get(value) : undefined;
+	if (exact !== undefined) return exact;
+	// Only re-key when the ENTIRE value is a single URI reference token. A string carrying prose or
+	// multiple tokens is opaque content we do not own, and rewriting inside it caused real corruption
+	// in earlier revisions. Everything after the id (selector, query, fragment) is likewise opaque and
+	// is preserved verbatim, so nested ids inside those payloads are never re-keyed.
+	if (/[\s"'<>]/.test(value)) return value;
+	const head = value.match(/^(artifact|agent):\/\/([0-9]+)/i);
+	if (!head) return value;
+	const protocol = head[1];
+	const mapped = idMap.get(head[2]);
+	if (mapped === undefined) return value;
+	const rest = value.slice(head[0].length);
+	if (rest !== "" && !/^[:/?#]/.test(rest)) return value;
+	if (rest.startsWith(":") && !colonTerminatesUriId(protocol, rest.slice(1))) return value;
+	return `${protocol}://${mapped}${rest}`;
+}
+
+function remapAttemptReferencesInEntries(entries: readonly FileEntry[], idMap: ReadonlyMap<string, string>): void {
+	if (idMap.size === 0) return;
+	const seen = new WeakSet<object>();
+	const visit = (value: unknown, key?: string): unknown => {
+		if (
+			typeof value === "number" &&
+			key !== undefined &&
+			ARTIFACT_REFERENCE_KEYS.has(key) &&
+			Number.isSafeInteger(value)
+		) {
+			const mapped = idMap.get(String(value));
+			return mapped === undefined ? value : Number(mapped);
+		}
+		if (typeof value === "string") {
+			return remapArtifactReferenceString(value, idMap, key !== undefined && ARTIFACT_REFERENCE_KEYS.has(key));
+		}
+		if (!value || typeof value !== "object" || seen.has(value)) return value;
+		seen.add(value);
+		if (Array.isArray(value)) {
+			for (let index = 0; index < value.length; index++) value[index] = visit(value[index], key);
+			return value;
+		}
+		const record = value as Record<string, unknown>;
+		for (const [childKey, child] of Object.entries(record)) {
+			if (ATTEMPT_REMAP_STRUCTURAL_KEYS.has(childKey)) continue;
+			const next = visit(child, childKey);
+			if (next !== child) record[childKey] = next;
+		}
+		return value;
+	};
+	for (const entry of entries) visit(entry);
+}
+
 type ResidentTransitionSource =
 	| {
 			mode: "materialize";
@@ -3395,6 +3501,7 @@ async function readTerminalBreadcrumb(cwd: string): Promise<string | null> {
 			return null;
 		}
 
+		if (isStagedSessionPath(sessionFile)) return null;
 		const inspected = inspectResumeSessionFile(sessionFile, new FileSessionStorage());
 		if ("kind" in inspected) {
 			if (inspected.reason !== "missing") return null;
@@ -3408,7 +3515,8 @@ async function readTerminalBreadcrumb(cwd: string): Promise<string | 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),
+				candidate =>
+					!isStagedSessionPath(candidate.path) && path.basename(candidate.path) === path.basename(sessionFile),
 			);
 			return migrated.length === 1 ? migrated[0]!.path : null;
 		}
@@ -3423,9 +3531,14 @@ async function readTerminalBreadcrumb(cwd: string): Promise<string | null> {
 		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));
+		const exact = listing.owned.find(
+			candidate =>
+				!isStagedSessionPath(candidate.path) && path.resolve(candidate.path) === path.resolve(sessionFile),
+		);
 		if (exact) return exact.path;
-		const byIdentity = listing.owned.find(candidate => candidate.sessionId === header.id);
+		const byIdentity = listing.owned.find(
+			candidate => !isStagedSessionPath(candidate.path) && candidate.sessionId === header.id,
+		);
 		if (byIdentity) return byIdentity.path;
 		return pathIsWithin(sessionsRoot, path.resolve(sessionFile)) ? null : path.resolve(sessionFile);
 	} catch (err) {
@@ -6237,9 +6350,11 @@ const PROJECT_SESSION_SCAN_MAX_DIRECTORIES = 4096;
 const PROJECT_SESSION_SCAN_MAX_FILES = 1000;
 
 function isProjectSessionTranscriptPath(projectGjcDir: string, filePath: string): boolean {
+	if (isStagedSessionPath(filePath)) return false;
 	const relative = path.relative(projectGjcDir, filePath);
 	if (relative.startsWith("..") || path.isAbsolute(relative)) return false;
 	const segments = relative.split(path.sep);
+	if (segments.includes(SESSION_STAGING_DIRNAME)) return false;
 	if (segments.length === 1) return true;
 	const parent = segments.at(-2);
 	return parent === "agent-session" || segments.includes("sessions");
@@ -6250,7 +6365,7 @@ function isProjectSessionTranscriptPath(projectGjcDir: string, filePath: string)
  * Runtime token/audit JSONL files are excluded by requiring a known transcript
  * container (`agent-session` or `sessions`).
  */
-function listProjectSessionTranscriptFiles(cwd: string): string[] {
+export function listProjectSessionTranscriptFiles(cwd: string): string[] {
 	const projectGjcDir = path.join(path.resolve(cwd), ".gjc");
 	let rootStat: fs.Stats;
 	try {
@@ -6276,6 +6391,7 @@ function listProjectSessionTranscriptFiles(cwd: string): string[] {
 			if (entry.isSymbolicLink()) continue;
 			const entryPath = path.join(directory, entry.name);
 			if (entry.isDirectory()) {
+				if (entry.name === SESSION_STAGING_DIRNAME) continue;
 				directories.push(entryPath);
 				continue;
 			}
@@ -7180,11 +7296,48 @@ export class SessionManager {
 	/** Defense-in-depth (#4443): one-shot warn for adjacent private thinking blocks in persisted assistant transcripts. */
 	#warnedAdjacentThinkingPersist = false;
 	#closeRetryPending = false;
+	/** Serializes model, SDK, and ACP cwd transitions; dispose joins this tail. */
+	#cwdTransitionTail: Promise<void> = Promise.resolve();
+	#cwdTransitionOwner: symbol | undefined;
+	#cwdReadLeaseOwner = Symbol("cwd-read-lease-owner");
+	#cwdGeneration = 0;
+	/** Number of tool executions currently holding a shared read lease on `cwd`. */
+	#cwdReaderCount = 0;
+	/** Resolved when the last outstanding read lease is released. */
+	#cwdReadersDrained: (() => void) | undefined;
+	#cwdReadersIdle: Promise<void> = Promise.resolve();
+	/** Set while a writer is queued or running so new readers do not starve it. */
+	#cwdWriterPending = 0;
 	/** Depth of the non-yielding same-session persistence fence (reentrancy counter). */
 	#persistenceFenceDepth = 0;
 	/** Publication fence counter carried by the mutable `.spill.commit` marker. */
 	#commitGen = 0;
 	/** Failed staged persistence retains its exact writer and temporary pathname for retryable cleanup. */
+	/** Candidate-owned session publication state; set only by staged factories. */
+	#stagedPublication:
+		| {
+				finalSessionFile: string;
+				stagedSessionFile: string;
+				finalDestination: SessionDestination;
+				managedParentStore?: ManagedSessionDescendantStore;
+				/** Subtree store bound to the staging directory; basename reads stay authority-safe. */
+				managedStagingStore?: ManagedSessionDescendantStore;
+				attemptId: string;
+				committed: boolean;
+				discarded: boolean;
+				publishedFinalSnapshot?: ManagedFileSnapshot;
+				publishedFinalBytes?: Buffer;
+				deferArtifactFinalize?: boolean;
+				/**
+				 * A publish that native code could neither prove nor disprove. The transcript may
+				 * already be visible at the destination, so no later cleanup may reclaim the
+				 * staging or artifacts it references.
+				 */
+				preservedUnproven?: boolean;
+		  }
+		| undefined;
+	#stagedArtifactParent: ArtifactManager | null = null;
+	#stagedCommitArtifactParent: ArtifactManager | null = null;
 	#preparedNewSessionCleanupInProgress = false;
 	/** Active cold-sidecar runtime (retirement + lazy resolution). Undefined when disabled. */
 	#sidecarRuntime: SessionMemorySidecarRuntime | undefined = undefined;
@@ -9141,7 +9294,7 @@ export class SessionManager {
 			this.#effectiveSessionMemoryMode(transcriptSize) === "enabled" &&
 			this.#storage.existsSync(`${sidecarRoot}/.session-memory.spill.commit`);
 		if (boundedTranscriptAdmitted && (await this.#tryInitSessionFileFromSidecar(resolvedSessionFile))) {
-			writeTerminalBreadcrumb(this.cwd, resolvedSessionFile);
+			this.#writeTerminalBreadcrumb(resolvedSessionFile);
 			revalidateStrictResume();
 			return;
 		}
@@ -9151,7 +9304,7 @@ export class SessionManager {
 				this.#sessionMemoryMode = "shadow";
 				this.#sessionMemoryAutoDisabledReason = "sidecar_reload_failures";
 			}
-			writeTerminalBreadcrumb(this.cwd, resolvedSessionFile);
+			this.#writeTerminalBreadcrumb(resolvedSessionFile);
 			revalidateStrictResume();
 			return;
 		}
@@ -9167,7 +9320,7 @@ export class SessionManager {
 			this.#applyFreshSessionMetadata(fresh);
 			this.#commitResidentTextStoreTransition(prepared);
 			this.#retireEphemeralArtifacts();
-			writeTerminalBreadcrumb(this.cwd, resolvedSessionFile);
+			this.#writeTerminalBreadcrumb(resolvedSessionFile);
 			await this.#rewriteFile();
 			this.#flushed = true;
 			this.#ensuredOnDisk = true;
@@ -9195,7 +9348,7 @@ export class SessionManager {
 			this.#applyFreshSessionMetadata(fresh);
 			this.#commitResidentTextStoreTransition(prepared);
 			this.#retireEphemeralArtifacts();
-			writeTerminalBreadcrumb(this.cwd, resolvedSessionFile);
+			this.#writeTerminalBreadcrumb(resolvedSessionFile);
 			await this.#rewriteFile();
 			this.#flushed = true;
 			this.#ensuredOnDisk = true;
@@ -9228,7 +9381,7 @@ export class SessionManager {
 		this.#titleSource = header?.titleSource;
 		this.#needsFullRewriteOnNextPersist = migrationApplied;
 		this.#commitResidentTextStoreTransition(prepared);
-		writeTerminalBreadcrumb(this.cwd, resolvedSessionFile);
+		this.#writeTerminalBreadcrumb(resolvedSessionFile);
 		this.#flushed = true;
 		this.#ensuredOnDisk = true;
 		this.#adoptManagedPersistIdentity(resolvedSessionFile);
@@ -9240,6 +9393,11 @@ export class SessionManager {
 		}
 	}
 
+	#writeTerminalBreadcrumb(sessionFile: string): void {
+		if (this.#stagedPublication && !this.#stagedPublication.committed) return;
+		writeTerminalBreadcrumb(this.cwd, sessionFile);
+	}
+
 	async #hydrateExistingSession(
 		sessionFile: string,
 		entries: FileEntry[],
@@ -10449,13 +10607,209 @@ export class SessionManager {
 		}
 	}
 
+	async #assertCwdTargetIdentity(
+		resolvedCwd: string,
+		options: {
+			expectedIdentity?: { dev: bigint; ino: bigint };
+			targetHandle?: { stat: (opts: { bigint: true }) => Promise<fs.BigIntStats> };
+		},
+	): Promise<void> {
+		let opened: fs.BigIntStats | undefined;
+		if (options.targetHandle) {
+			opened = await options.targetHandle.stat({ bigint: true });
+			if (!opened.isDirectory()) {
+				throw new Error(
+					`Refusing to move through a replaced path: ${resolvedCwd} is no longer the validated directory.`,
+				);
+			}
+		}
+		let observed: fs.BigIntStats;
+		try {
+			observed = await fs.promises.lstat(resolvedCwd, { bigint: true });
+		} catch {
+			throw new Error(`Directory identity unavailable at state-changing boundary: ${resolvedCwd}`);
+		}
+		if (observed.isSymbolicLink() || !observed.isDirectory()) {
+			throw new Error(
+				`Refusing to move through a replaced path: ${resolvedCwd} is no longer the validated directory.`,
+			);
+		}
+		if (opened && (observed.dev !== opened.dev || observed.ino !== opened.ino)) {
+			throw new Error(`Refusing to move: target identity changed at ${resolvedCwd}.`);
+		}
+		const expected = options.expectedIdentity;
+		const pinned = opened ?? observed;
+		if (expected && (pinned.dev !== expected.dev || pinned.ino !== expected.ino)) {
+			throw new Error(`Refusing to move: target identity changed at ${resolvedCwd}.`);
+		}
+	}
+
+	/**
+	 * Serialize every cwd transition (model, TUI, SDK/ACP). Re-entry is allowed
+	 * 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> {
+		const owner = this.#cwdTransitionOwner;
+		if (owner !== undefined && cwdTransitionAls.getStore() === owner) {
+			return fn();
+		}
+		const previous = this.#cwdTransitionTail;
+		const { promise, resolve } = Promise.withResolvers<void>();
+		this.#cwdTransitionTail = previous.then(
+			() => promise,
+			() => promise,
+		);
+		// Announce the writer BEFORE awaiting the queue so readers arriving during
+		// the wait queue behind it rather than starving it indefinitely.
+		this.#cwdWriterPending += 1;
+		const token = Symbol("cwd-transition");
+		try {
+			await 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;
+			this.#cwdTransitionOwner = token;
+			return await cwdTransitionAls.run(token, fn);
+		} finally {
+			if (this.#cwdTransitionOwner === token) this.#cwdTransitionOwner = undefined;
+			this.#cwdWriterPending -= 1;
+			resolve();
+		}
+	}
+
+	/**
+	 * Run `fn` under a shared read lease on `cwd`.
+	 *
+	 * Tools that resolve relative paths against the session cwd must hold this
+	 * lease across their WHOLE execution, not merely re-check a generation before
+	 * they start: the check-then-yield shape lets a move commit inside the tool's
+	 * first `await`, so a command admitted for root A would execute in root B.
+	 * Writers wait for outstanding leases to drain, so the cwd observed at lease
+	 * acquisition stays authoritative until the lease is released.
+	 */
+	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();
+		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();
+		while (this.#cwdWriterPending > 0) await this.#cwdTransitionTail.catch(() => {});
+		if (this.#cwdReaderCount === 0) {
+			const { promise, resolve } = Promise.withResolvers<void>();
+			this.#cwdReadersIdle = promise;
+			this.#cwdReadersDrained = resolve;
+		}
+		this.#cwdReaderCount += 1;
+		const readLease: CwdReadLeaseContext = { active: true, owner: this.#cwdReadLeaseOwner };
+		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?.();
+				}
+			}
+		});
+	}
+
+	/** Wait for any in-flight exclusive cwd transition to settle. */
+	async joinCwdTransition(): Promise<void> {
+		await this.#cwdTransitionTail;
+	}
+	getCwdGeneration(): number {
+		return this.#cwdGeneration;
+	}
+
+	#ownsCwdTransition(): boolean {
+		const owner = this.#cwdTransitionOwner;
+		return owner !== undefined && cwdTransitionAls.getStore() === owner;
+	}
+	static async openNoFollowDirectory(dir: string): Promise<fs.promises.FileHandle> {
+		return fs.promises.open(dir, CWD_NOFOLLOW_OPEN_FLAGS);
+	}
+
+	/**
+	 * Owner of this process's cwd, or undefined when no session has claimed it.
+	 *
+	 * `process.chdir` and the caches keyed off it are process-global, so only one
+	 * session may drive them. Ownership is an explicit claim rather than an
+	 * inference from `process.cwd() === session.cwd`: two sessions launched at the
+	 * same root both satisfy that comparison, and letting either one act on it
+	 * lets a move in one session chdir the process under its sibling.
+	 */
+	static #processCwdOwner: WeakRef<SessionManager> | undefined;
+
+	/**
+	 * Claim process-cwd authority for `manager` when it is unowned or the prior
+	 * owner has been collected. Returns whether `manager` holds the claim.
+	 */
+	static claimProcessCwdOwnership(manager: SessionManager): boolean {
+		const current = SessionManager.#processCwdOwner?.deref();
+		if (current === manager) return true;
+		if (current !== undefined) return false;
+		SessionManager.#processCwdOwner = new WeakRef(manager);
+		return true;
+	}
+
+	static isProcessCwdOwner(manager: SessionManager): boolean {
+		return SessionManager.#processCwdOwner?.deref() === manager;
+	}
+
+	static releaseProcessCwdOwnership(manager: SessionManager): void {
+		if (SessionManager.#processCwdOwner?.deref() === manager) SessionManager.#processCwdOwner = undefined;
+	}
+
+	/**
+	 * Verify that `process.cwd()` is the directory pinned by `expectedIdentity`.
+	 *
+	 * `process.chdir` resolves a NAME, so a path replaced after the last
+	 * name-based comparison lands the process outside the validated directory —
+	 * the exact confinement `move_session` exists to enforce. Node exposes no
+	 * `fchdir`, so the handle cannot be the chdir authority directly; comparing
+	 * the resulting cwd's identity to the pinned handle closes the same gap.
+	 */
+	static async assertProcessCwdIdentity(expectedIdentity: { dev: bigint; ino: bigint }): Promise<void> {
+		const observed = await fs.promises.stat(process.cwd(), { bigint: true });
+		if (observed.dev !== expectedIdentity.dev || observed.ino !== expectedIdentity.ino) {
+			throw new Error(
+				`Refusing to rescope: process cwd ${process.cwd()} is not the validated target directory (identity changed).`,
+			);
+		}
+	}
+
 	/**
 	 * Move the session to a new working directory.
 	 * Moves session files and artifacts on disk, updates all internal references,
 	 * and rewrites the session header with the new cwd.
+	 *
+	 * All callers (model `move_session`, TUI `/move`, SDK/ACP `session.cwd.move`)
+	 * share this exclusive transition so concurrent moves cannot interleave.
 	 */
-	async moveTo(newCwd: string): Promise<void> {
+	async moveTo(
+		newCwd: string,
+		options?: {
+			expectedIdentity?: { dev: bigint; ino: bigint };
+			targetHandle?: { stat: (opts: { bigint: true }) => Promise<fs.BigIntStats> };
+		},
+	): Promise<void> {
+		if (!this.#ownsCwdTransition()) {
+			return this.runExclusiveCwdTransition(() => this.moveTo(newCwd, options));
+		}
 		const resolvedCwd = path.resolve(newCwd);
+		if (options?.expectedIdentity || options?.targetHandle) {
+			await this.#assertCwdTargetIdentity(resolvedCwd, options);
+		}
 		if (resolvedCwd === this.cwd) return;
 		const previousCwd = this.cwd;
 		const previousSessionDir = this.sessionDir;
@@ -10700,6 +11054,10 @@ export class SessionManager {
 
 		// Update cwd and sessionDir after physical publication succeeds. Metadata failures restore the source
 		// authority but deliberately retain any destination publication evidence rather than deleting it.
+		if (options?.expectedIdentity || options?.targetHandle) {
+			await this.#assertCwdTargetIdentity(resolvedCwd, options);
+		}
+		this.#cwdGeneration += 1;
 		this.cwd = resolvedCwd;
 		this.sessionDir = newSessionDir;
 		this.destination = nextDestination;
@@ -15216,6 +15574,8 @@ export class SessionManager {
 
 	/** Close the persistent writer after flushing all pending data. */
 	async close(): Promise<void> {
+		await this.joinCwdTransition();
+		SessionManager.releaseProcessCwdOwnership(this);
 		// Drain any uncommitted prepared successors before releasing resources so
 		// dispose/shutdown retains exact cleanup authority (#3138).
 		try {
@@ -15814,8 +16174,9 @@ export class SessionManager {
 	 * Adopt an externally-owned ArtifactManager. Used by subagents to share
 	 * the parent session's artifact directory and ID counter.
 	 */
-	adoptArtifactManager(manager: ArtifactManager): void {
+	adoptArtifactManager(manager: ArtifactManager, parent?: ArtifactManager): void {
 		this.#adoptedArtifactManager = manager;
+		if (parent) this.#stagedArtifactParent = parent;
 	}
 
 	/** Release only the matching externally adopted manager. */
@@ -17019,6 +17380,15 @@ export class SessionManager {
 		}
 	}
 
+	/** Remap artifact references in an unpublished candidate before its publication fence. */
+	async remapStagedArtifactReferences(idMap: ReadonlyMap<string, string>): Promise<void> {
+		const staged = this.#stagedPublication;
+		if (!staged || staged.committed || staged.discarded) throw new Error("Staged session is unavailable");
+		remapAttemptReferencesInEntries(this.#fileEntries, idMap);
+		this.#needsFullRewriteOnNextPersist = true;
+		await this.#rewriteFileContents();
+	}
+
 	/**
 	 * Append a custom message entry (for extensions) that participates in LLM context.
 	 * @param customType Hook identifier for filtering on reload
@@ -17878,7 +18248,7 @@ export class SessionManager {
 
 	async #sanitizeLoadedOpenAIResponsesReplayMetadataAndPersist(): Promise<boolean> {
 		const patches = this.#sanitizeLoadedOpenAIResponsesReplayMetadata();
-		await this.#persistPatches(patches);
+		if (!this.isManagedDestination()) await this.#persistPatches(patches);
 		return patches.length > 0;
 	}
 
@@ -18951,6 +19321,383 @@ export class SessionManager {
 	 * @param path Path to session file
 	 * @param sessionDir Optional session directory for /new or /branch. If omitted, derives from file's parent.
 	 */
+	/** Open an unpublished candidate transcript below the reserved staging directory. */
+	static async openStaged(
+		finalSessionFile: string,
+		storage: SessionStorage = new FileSessionStorage(),
+		attemptId: string = crypto.randomUUID(),
+	): Promise<SessionManager> {
+		assertSafeStagedAttemptId(attemptId);
+
+		if (isStagedSessionPath(finalSessionFile)) throw new Error("Final session path cannot be staged");
+		const finalPath =
+			storage instanceof FileSessionStorage ? canonicalizeTrustedPath(finalSessionFile) : finalSessionFile;
+		const finalDestination = explicitDestination(path.dirname(finalPath));
+		const stagingDir = path.join(path.dirname(finalPath), SESSION_STAGING_DIRNAME);
+		await fs.promises.mkdir(stagingDir, { recursive: true, mode: 0o700 });
+		const stagedSessionFile = path.join(stagingDir, `${attemptId}.jsonl`);
+		if (path.resolve(stagedSessionFile) === path.resolve(finalPath))
+			throw new Error("Staged session path collides with final transcript");
+
+		const manager = new SessionManager(getProjectDir(), stagingDir, true, storage, finalDestination);
+		manager.#stagedPublication = {
+			finalSessionFile: finalPath,
+			stagedSessionFile,
+			finalDestination,
+			attemptId,
+			committed: false,
+			discarded: false,
+		};
+		if (fs.existsSync(stagedSessionFile)) throw new Error("Staged session attempt already exists");
+		try {
+			await manager.#initSessionFile(stagedSessionFile, true);
+			const parentArtifacts = new ArtifactManager(finalPath.endsWith(".jsonl") ? finalPath.slice(0, -6) : finalPath);
+			manager.adoptArtifactManager(parentArtifacts.createAttemptStaging(attemptId), parentArtifacts);
+			return manager;
+		} catch (error) {
+			try {
+				await manager.discardStaged();
+			} catch (cleanupError) {
+				throw new AggregateError(
+					[toError(error), toError(cleanupError)],
+					"Staged session open and cleanup both failed.",
+				);
+			}
+			throw error;
+		}
+	}
+
+	/** Managed-authority variant of {@link openStaged}. */
+	static async stagedNestedManaged(
+		finalSessionFile: string,
+		destination: SessionDestination,
+		store: ManagedSessionDescendantStore,
+		storage: SessionStorage = new FileSessionStorage(),
+		attemptId: string = crypto.randomUUID(),
+	): Promise<SessionManager> {
+		assertSafeStagedAttemptId(attemptId);
+
+		if (destination.kind !== "managed" || !trustedSessionDestinations.has(destination))
+			throw new Error("Nested managed session authority is unavailable");
+		if (isStagedSessionPath(finalSessionFile)) throw new Error("Final session path cannot be staged");
+		store.assertBound();
+		const finalPath = path.resolve(finalSessionFile);
+		if (path.dirname(finalPath) !== path.resolve(destination.directory))
+			throw new Error("Nested managed session escaped retained authority");
+		const stagingStore = store.deriveSubtree(SESSION_STAGING_DIRNAME);
+		const stagedDir = stagingStore.dir;
+		const stagedSessionFile = path.join(stagedDir, `${attemptId}.jsonl`);
+		if (path.resolve(stagedSessionFile) === path.resolve(finalPath))
+			throw new Error("Staged session path collides with final transcript");
+		const stagedDestination = SessionManager.nestedManagedDestination(stagingStore, stagedDir);
+		const manager = new SessionManager(getProjectDir(), stagedDir, true, storage, stagedDestination);
+		manager.#stagedPublication = {
+			finalSessionFile: finalPath,
+			stagedSessionFile,
+			finalDestination: destination,
+			managedParentStore: store,
+			managedStagingStore: stagingStore,
+			attemptId,
+			committed: false,
+			discarded: false,
+		};
+		if (fs.existsSync(stagedSessionFile)) throw new Error("Staged session attempt already exists");
+		try {
+			await manager.#initSessionFile(stagedSessionFile, true);
+			const parentArtifacts = new ArtifactManager(store);
+			manager.adoptArtifactManager(parentArtifacts.createAttemptStaging(attemptId), parentArtifacts);
+			store.assertBound();
+			return manager;
+		} catch (error) {
+			try {
+				await manager.discardStaged();
+			} catch (cleanupError) {
+				throw new AggregateError(
+					[toError(error), toError(cleanupError)],
+					"Staged session open and cleanup both failed.",
+				);
+			}
+			throw error;
+		}
+	}
+	/** Publish the candidate-owned staged transcript and artifacts at the real accept fence. */
+	static async openStagedNestedManaged(
+		finalSessionFile: string,
+		destination: SessionDestination,
+		store: ManagedSessionDescendantStore,
+		storage: SessionStorage = new FileSessionStorage(),
+		attemptId: string = crypto.randomUUID(),
+	): Promise<SessionManager> {
+		return SessionManager.stagedNestedManaged(finalSessionFile, destination, store, storage, attemptId);
+	}
+
+	async commitStaged(options?: { deferArtifactFinalize?: boolean }): Promise<void> {
+		const staged = this.#stagedPublication;
+		if (!staged || staged.discarded) throw new Error("Staged session is unavailable");
+		if (staged.committed) return;
+		staged.deferArtifactFinalize = options?.deferArtifactFinalize === true;
+		await this.flush();
+		await this.#closePersistWriter();
+		const stagedManager = this.#adoptedArtifactManager ?? this.#artifactManager;
+		// Lifecycle invariant: while a staged publication is uncommitted, the session must
+		// carry exactly the attempt-rooted staging manager it opened with. openStaged,
+		// stagedNestedManaged, and openStagedSession all pre-adopt an attempt-rooted
+		// manager, so an adopted manager that is absent or foreign means a second root
+		// replaced the first — orphaning the original from commit/discard cleanup.
+		if (this.#adoptedArtifactManager?.getAttemptId() !== staged.attemptId)
+			throw new Error("Staged session artifact root does not match the staged attempt.");
+		const parentArtifacts =
+			this.#stagedArtifactParent ??
+			new ArtifactManager(
+				staged.finalSessionFile.endsWith(".jsonl") ? staged.finalSessionFile.slice(0, -6) : staged.finalSessionFile,
+			);
+		this.#stagedCommitArtifactParent = parentArtifacts;
+		let published = false;
+		try {
+			if (stagedManager?.getAttemptId() === staged.attemptId) {
+				const stagedArtifactFiles = await stagedManager.listFiles();
+				if (stagedArtifactFiles.length > 0 || stagedManager.getAllocatedIds().length > 0) {
+					await parentArtifacts.commitAttemptStaging(stagedManager, staged.attemptId, {
+						beforePublish: idMap => this.remapStagedArtifactReferences(idMap),
+					});
+				} else await stagedManager.discardAttemptStaging();
+			}
+			if (staged.managedParentStore && staged.managedStagingStore) {
+				const stagedName = path.basename(staged.stagedSessionFile);
+				const relative = path.posix.join(SESSION_STAGING_DIRNAME, stagedName);
+				const expected = staged.managedStagingStore.readExpected(stagedName);
+				if (!expected) throw new Error("staged_session_missing");
+				staged.managedParentStore.moveFileNoReplace(relative, path.basename(staged.finalSessionFile), expected, {
+					sourceStore: staged.managedStagingStore,
+					sourceStoreRelativePath: stagedName,
+				});
+			} else {
+				const outcome = classifyNativePublishOutcome(
+					nativeSessionManager().renameNoReplacePath(staged.stagedSessionFile, staged.finalSessionFile),
+				);
+				if (!outcome.ok) throw new Error(outcome.code ?? "staged_session_publish_failed");
+			}
+			published = true;
+			if (staged.managedParentStore) {
+				staged.publishedFinalSnapshot =
+					staged.managedParentStore.readExpected(path.basename(staged.finalSessionFile)) ?? undefined;
+				if (!staged.publishedFinalSnapshot) throw new Error("staged_session_publish_missing");
+			} else staged.publishedFinalBytes = await fs.promises.readFile(staged.finalSessionFile);
+
+			const finalStat = fs.lstatSync(staged.finalSessionFile, { bigint: true });
+			if (!finalStat.isFile() || finalStat.isSymbolicLink()) throw new Error("staged_session_identity_changed");
+			this.sessionDir = path.dirname(staged.finalSessionFile);
+			this.destination = staged.finalDestination;
+			this.#managedTranscriptStoreCache = staged.managedParentStore
+				? { directory: path.dirname(staged.finalSessionFile), store: staged.managedParentStore }
+				: null;
+			this.#sessionFile = staged.finalSessionFile;
+			this.#artifactManager = parentArtifacts;
+			this.#artifactManagerSessionFile = staged.finalSessionFile;
+			this.#adoptedArtifactManager = parentArtifacts;
+			staged.committed = true;
+			if (!staged.deferArtifactFinalize) {
+				writeTerminalBreadcrumb(this.cwd, staged.finalSessionFile);
+				parentArtifacts.finalizeLastAttemptCommit(staged.attemptId);
+			}
+		} catch (error) {
+			const cleanupErrors: Error[] = [];
+			// A managed move can commit and still report failure when native code cannot
+			// prove durability or terminal identity. Treating that as unpublished would
+			// roll the artifacts back underneath a transcript that is already visible at
+			// the destination, so probe the destination first and preserve every owned
+			// artifact when the mutation may have landed.
+			if (!published && staged.managedParentStore && !mayCleanManagedTreeStaging(error)) {
+				const probeErrors: Error[] = [];
+				let destination: ManagedFileSnapshot | null = null;
+				try {
+					destination = staged.managedParentStore.readExpected(path.basename(staged.finalSessionFile));
+				} catch (probeError) {
+					probeErrors.push(toError(probeError));
+				}
+				// Absence must be proven; an unreadable destination stays fail-closed.
+				if (destination || probeErrors.length > 0) {
+					staged.publishedFinalSnapshot = destination ?? undefined;
+					// Latch the uncertainty so no later compensation reclaims what a possibly
+					// published transcript references.
+					staged.preservedUnproven = true;
+					throw new AggregateError(
+						[toError(error), ...probeErrors],
+						"Staged publication may have committed without proof; artifacts and staging were preserved for recovery.",
+					);
+				}
+			}
+			if (published) {
+				try {
+					if (staged.managedParentStore) {
+						const finalSnapshot = staged.managedParentStore.readExpected(path.basename(staged.finalSessionFile));
+						if (finalSnapshot)
+							staged.managedParentStore.removeExpected(path.basename(staged.finalSessionFile), finalSnapshot);
+					} else await fs.promises.rm(staged.finalSessionFile, { force: true });
+				} catch (cleanupError) {
+					cleanupErrors.push(toError(cleanupError));
+				}
+			}
+			try {
+				await parentArtifacts.rollbackLastAttemptCommit(staged.attemptId);
+			} catch (cleanupError) {
+				cleanupErrors.push(toError(cleanupError));
+			}
+			try {
+				await this.discardStaged();
+			} catch (cleanupError) {
+				cleanupErrors.push(toError(cleanupError));
+			}
+			if (cleanupErrors.length > 0)
+				throw new AggregateError([toError(error), ...cleanupErrors], "Staged publication and cleanup both failed.");
+			throw error;
+		}
+	}
+
+	/** Finalize a staged publication whose post-fence publisher completed successfully. */
+	finalizeStagedCommit(): void {
+		const staged = this.#stagedPublication;
+		if (!staged?.committed || !staged.deferArtifactFinalize) return;
+		this.#stagedCommitArtifactParent?.finalizeLastAttemptCommit(staged.attemptId);
+		writeTerminalBreadcrumb(this.cwd, staged.finalSessionFile);
+		staged.deferArtifactFinalize = false;
+	}
+
+	/** Roll back a staged publication when post-fence visibility setup fails. */
+	async rollbackCommittedStaged(): Promise<void> {
+		const staged = this.#stagedPublication;
+		if (!staged?.committed) return;
+		if (staged.managedParentStore) {
+			const current = staged.managedParentStore.readExpected(path.basename(staged.finalSessionFile));
+			if (
+				current &&
+				staged.publishedFinalSnapshot &&
+				current.identity.dev === staged.publishedFinalSnapshot.identity.dev &&
+				current.identity.ino === staged.publishedFinalSnapshot.identity.ino
+			) {
+				if (this.#stagedCommitArtifactParent) {
+					const removed = await this.#stagedCommitArtifactParent.removeNamedBestEffort(
+						path.basename(staged.finalSessionFile),
+					);
+					if (!removed) throw new Error("staged_final_cleanup_failed");
+				} else staged.managedParentStore.removeExpected(path.basename(staged.finalSessionFile), current);
+			}
+		} else if (staged.publishedFinalBytes) {
+			const current = await fs.promises.readFile(staged.finalSessionFile).catch(() => undefined);
+			if (current?.equals(staged.publishedFinalBytes))
+				await fs.promises.rm(staged.finalSessionFile, { force: true });
+		}
+		await this.#stagedCommitArtifactParent?.rollbackLastAttemptCommit(staged.attemptId);
+		staged.committed = false;
+		staged.discarded = true;
+		staged.deferArtifactFinalize = false;
+	}
+
+	/** Refresh the owned final snapshot after post-fence session metadata is appended. */
+	async refreshStagedCommitSnapshot(): Promise<void> {
+		const staged = this.#stagedPublication;
+		if (!staged?.committed) return;
+		if (staged.managedParentStore) {
+			staged.publishedFinalSnapshot =
+				staged.managedParentStore.readExpected(path.basename(staged.finalSessionFile)) ?? undefined;
+			if (!staged.publishedFinalSnapshot) throw new Error("staged_session_publish_missing");
+		} else staged.publishedFinalBytes = await fs.promises.readFile(staged.finalSessionFile);
+	}
+
+	/** Idempotently remove an unpublished staged transcript and its owned artifacts. */
+	async discardStaged(): Promise<void> {
+		const staged = this.#stagedPublication;
+		if (!staged || staged.committed || staged.discarded) return;
+		// An unproven publish may already be visible at the destination; reclaiming its
+		// staging or artifacts would strand that transcript with dangling references.
+		if (staged.preservedUnproven) return;
+		const cleanupErrors: Error[] = [];
+		// Same strict single-root invariant as commitStaged: an absent or foreign adopted
+		// manager means the publication's own attempt root was replaced or released.
+		if (this.#adoptedArtifactManager?.getAttemptId() !== staged.attemptId) {
+			cleanupErrors.push(new Error("Staged session artifact root does not match the staged attempt."));
+		}
+		const captureCleanupError = (error: unknown): void => {
+			const normalized = toError(error);
+			if (normalized.message !== "not_found" && !isAuthorizedPendingCleanup(normalized))
+				cleanupErrors.push(normalized);
+		};
+		try {
+			await this.#closePersistWriter();
+		} catch (error) {
+			captureCleanupError(error);
+		}
+		let managedStagingBefore: ReturnType<ManagedSessionDescendantStore["captureTree"]> | undefined;
+		if (staged.managedParentStore) {
+			try {
+				managedStagingBefore = staged.managedParentStore.captureTree(SESSION_STAGING_DIRNAME);
+			} catch (error) {
+				captureCleanupError(error);
+			}
+		}
+
+		const stagedManager = this.#adoptedArtifactManager ?? this.#artifactManager;
+		if (stagedManager?.getAttemptId() === staged.attemptId) {
+			try {
+				await stagedManager.discardAttemptStaging();
+			} catch (error) {
+				captureCleanupError(error);
+			}
+		}
+		if (staged.managedParentStore) {
+			const stagedName = path.basename(staged.stagedSessionFile);
+			try {
+				const stagingStore = staged.managedStagingStore;
+				if (stagingStore) {
+					const expected = stagingStore.readExpected(stagedName);
+					if (expected) stagingStore.removeExpected(stagedName, expected);
+				}
+			} catch (error) {
+				captureCleanupError(error);
+			}
+			if (managedStagingBefore) {
+				try {
+					const after = staged.managedParentStore.captureTree(SESSION_STAGING_DIRNAME);
+					const beforePaths = new Set(managedStagingBefore.entries.map(entry => entry.relativePath));
+					for (const entry of after.entries) {
+						if (
+							entry.relativePath.length === 0 ||
+							beforePaths.has(entry.relativePath) ||
+							(!/^\.gjc-/u.test(path.posix.basename(entry.relativePath)) &&
+								!/\.removing$/u.test(path.posix.basename(entry.relativePath)))
+						)
+							continue;
+						try {
+							await fs.promises.rm(
+								path.join(staged.managedParentStore.dir, SESSION_STAGING_DIRNAME, entry.relativePath),
+								{ recursive: entry.kind === "directory", force: true },
+							);
+						} catch (error) {
+							captureCleanupError(error);
+						}
+					}
+				} catch (error) {
+					captureCleanupError(error);
+				}
+			}
+		} else {
+			try {
+				await fs.promises.rm(staged.stagedSessionFile, { force: true });
+			} catch (error) {
+				captureCleanupError(error);
+			}
+		}
+		if (cleanupErrors.length > 0) throw new AggregateError(cleanupErrors, "Staged session cleanup failed.");
+		staged.discarded = true;
+	}
+	async commitStagedNestedManaged(): Promise<void> {
+		return this.commitStaged();
+	}
+
+	async discardStagedNestedManaged(): Promise<void> {
+		return this.discardStaged();
+	}
+
 	static async open(
 		filePath: string,
 		destinationInput?: SessionDestinationInput,
@@ -18958,6 +19705,7 @@ export class SessionManager {
 		migrationPolicy: SessionDirectoryMigrationPolicy = "copy-retain",
 		sessionMemoryMode: SessionMemoryMode = "shadow",
 	): Promise<SessionManager> {
+		if (isStagedSessionPath(filePath)) throw new Error("Staged session paths are not resumable");
 		const destination =
 			destinationInput === undefined
 				? explicitDestination(path.dirname(filePath))
@@ -19446,7 +20194,7 @@ export class SessionManager {
 		const listing = listManagedCandidates(resolved.scope);
 		if (listing.kind === "error") return [];
 		const managed = await collectSessionsFromFiles(
-			listing.owned.map(candidate => candidate.path),
+			listing.owned.filter(candidate => !isStagedSessionPath(candidate.path)).map(candidate => candidate.path),
 			storage,
 		);
 		return mergeSessionInventories(managed, await collectProjectSessions(cwd, storage));
@@ -19464,7 +20212,10 @@ export class SessionManager {
 	): Promise<SessionInfo[]> {
 		if (!sessionDir) return await SessionManager.listManagedForResumePickerReadOnly(cwd, undefined, storage);
 		try {
-			return await collectSessionsFromFiles(storage.listFilesSync(sessionDir, "*.jsonl"), storage);
+			return await collectSessionsFromFiles(
+				storage.listFilesSync(sessionDir, "*.jsonl").filter(file => !isStagedSessionPath(file)),
+				storage,
+			);
 		} catch {
 			return [];
 		}
@@ -20184,7 +20935,13 @@ export class SessionManager {
 			await manager.close();
 			return ownershipInspection;
 		}
-		manager.#sanitizeLoadedOpenAIResponsesReplayMetadata();
+		try {
+			await manager.#sanitizeLoadedOpenAIResponsesReplayMetadataAndPersist();
+			writeTerminalBreadcrumb(manager.cwd, sessionPath);
+		} catch (error) {
+			await manager.close();
+			throw error;
+		}
 		return { kind: "opened", manager };
 	}
 
@@ -20368,7 +21125,8 @@ export class SessionManager {
 					logger.warn("Ignored invalid managed session candidates during global listing", {
 						count: listing.invalid.length,
 					});
-				for (const candidate of listing.owned) logicalFiles.add(candidate.path);
+				for (const candidate of listing.owned)
+					if (!isStagedSessionPath(candidate.path)) logicalFiles.add(candidate.path);
 			}
 			return await collectSessionsFromFiles([...logicalFiles], storage);
 		} catch {
@@ -20427,6 +21185,7 @@ export class SessionManager {
 				const failures: StrictInventoryFailure[] = [];
 				const candidates: StrictInventoryCandidate[] = [];
 				for (const managedCandidate of listing.owned) {
+					if (isStagedSessionPath(managedCandidate.path)) continue;
 					const candidate = inventoryReadCandidate(
 						storage,
 						managedCandidate.path,