@gajae-code/coding-agent 0.15.5 → 0.16.0

package/src/sdk/session.ts

@@ -17,6 +17,8 @@ import {
 	type AuthCredentialSelector,
 	type CredentialDisabledEvent,
 	codexToolWireName,
+	DEFAULT_MODEL_PER_PROVIDER,
+	type KnownProvider,
 	type Message,
 	type Model,
 	type ProviderSessionState,
@@ -65,11 +67,14 @@ import {
 	resolveModelRoleValue,
 	type ScopedModelSelection,
 } from "../config/model-resolver";
+import { normalizeModelSelectorValue } from "../config/model-selector-value";
 import { loadPromptTemplates as loadPromptTemplatesInternal, type PromptTemplate } from "../config/prompt-templates";
 import { Settings, type SkillsSettings } from "../config/settings";
 import { resolveEagerTaskDelegation } from "../config/task-delegation";
 import { CursorExecHandlers } from "../cursor";
 import { EditTool } from "../edit";
+import type { MasterModeContext } from "../master-mode/context";
+import { describeFoldReceipt } from "../session/fold-coordinator";
 import type { BashRestrictionProfile } from "../tools/bash-allowed-prefixes";
 import { SearchTool } from "../tools/search";
 import "../discovery";
@@ -119,7 +124,9 @@ import { normalizePluginHook } from "../hooks/normalize";
 import { initializeLocalRoot, LocalProtocolHandler, type LocalProtocolOptions } from "../internal-urls";
 import type { LspStartupServerInfo } from "../lsp";
 import { shutdownAll as shutdownAllLspClients } from "../lsp/client";
+import { createMasterPeerSnapshotContributor, MASTER_PEER_SNAPSHOT_CUSTOM_TYPE } from "../master-mode/first-request";
 import btwUserPrompt from "../prompts/system/btw-user.md" with { type: "text" };
+import masterModeTemplate from "../prompts/system/master-mode.md" with { type: "text" };
 import asyncResultTemplate from "../prompts/tools/async-result.md" with { type: "text" };
 import { AgentRegistry, MAIN_AGENT_ID } from "../registry/agent-registry";
 import { createLazyService } from "../runtime/lazy-service";
@@ -188,6 +195,7 @@ import { guardToolForUltragoalAsk } from "../tools/ultragoal-ask-guard";
 import { EventBus } from "../utils/event-bus";
 import { buildNamedToolChoice, buildNamedToolChoiceResult } from "../utils/tool-choice";
 import type { WorkspaceTree } from "../workspace-tree";
+import { createSessionLifecycleService } from "./lifecycle/client";
 import {
 	attachLifecycleStartupCapability,
 	lifecycleMcpStartupTimeoutOption,
@@ -524,6 +532,8 @@ export interface CreateAgentSessionOptions {
 	 * @internal CLI-only startup optimization; SDK callers retain synchronous loading by default.
 	 */
 	deferMcpConfigStartup?: boolean;
+	/** Process-local master authority. Never persist or pass to lifecycle children. */
+	masterModeContext?: MasterModeContext;
 	/**
 	 * Defer memory backend startup until the caller has applied startup model profiles.
 	 * @internal CLI-only ordering guard; SDK callers retain immediate startup by default.
@@ -1281,6 +1291,45 @@ function findDeferredExactMcpToolNameCollisions(
 	return [...collisions];
 }
 
+/**
+ * Order candidates so each known provider's curated default model is tried
+ * before the rest of the catalog.
+ *
+ * Provider catalogs are not ranked by fitness — a withdrawn model whose ID
+ * carries an older date suffix sorts ahead of its current replacement — so
+ * picking the first credentialed entry can start an unconfigured install on a
+ * model the provider no longer serves. `DEFAULT_MODEL_PER_PROVIDER` is the
+ * curated table `findInitialModel` already sweeps for the same purpose;
+ * reusing it keeps both unconfigured paths on one source of truth. Candidates
+ * that are not a provider default keep their original relative order.
+ */
+export function orderByProviderDefaultFirst(
+	candidates: readonly Model[],
+	providerOrder: readonly string[] = Object.keys(DEFAULT_MODEL_PER_PROVIDER),
+): Model[] {
+	const preferred: Model[] = [];
+	const rest: Model[] = [];
+	const preferredCandidates = new Set<Model>();
+	const seenProviders = new Set<string>();
+	for (const rawProvider of [...providerOrder, ...Object.keys(DEFAULT_MODEL_PER_PROVIDER)]) {
+		const provider = rawProvider.trim().toLowerCase();
+		if (!provider || seenProviders.has(provider) || !(provider in DEFAULT_MODEL_PER_PROVIDER)) continue;
+		seenProviders.add(provider);
+		const defaultId = DEFAULT_MODEL_PER_PROVIDER[provider as KnownProvider];
+		for (const candidate of candidates) {
+			if (candidate.provider.trim().toLowerCase() === provider && candidate.id === defaultId) {
+				preferred.push(candidate);
+				preferredCandidates.add(candidate);
+			}
+		}
+	}
+	if (preferred.length === 0) return [...candidates];
+	for (const candidate of candidates) {
+		if (!preferredCandidates.has(candidate)) rest.push(candidate);
+	}
+	return [...preferred, ...rest];
+}
+
 const AUTOMATION_TOOL_NAMES = new Set<AutomationToolName>(["browser", "computer"]);
 
 function validateAutomationTools(options: CreateAgentSessionOptions): AutomationTools {
@@ -1306,6 +1355,7 @@ function validateAutomationTools(options: CreateAgentSessionOptions): Automation
 
 export async function createAgentSession(options: CreateAgentSessionOptions = {}): Promise<CreateAgentSessionResult> {
 	const automationTools = validateAutomationTools(options);
+	const masterModeContext = options.masterModeContext;
 	const lifecycleStartupCapability = (
 		options as CreateAgentSessionOptions & { [lifecycleStartupCapabilityOption]?: SdkStartupCapability }
 	)[lifecycleStartupCapabilityOption];
@@ -1345,14 +1395,19 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const startupAuthConfig = hasInjectedAuth
 		? undefined
 		: (options.startupAuthConfig ?? (await resolveStartupAuthConfig(agentDir)));
+	const ownsModelRegistry = options.modelRegistry === undefined;
 	const ownsAuthStorage = options.modelRegistry === undefined && options.authStorage === undefined;
 	const modelRegistry =
 		options.modelRegistry ??
 		new ModelRegistry(
 			options.authStorage ??
 				(await logger.time("discoverModels", () => discoverAuthStorage(agentDir, startupAuthConfig))),
+			path.join(agentDir, "models.yml"),
+			undefined,
+			{ agentDir },
 		);
 	const authStorage = modelRegistry.authStorage;
+	const authStorageOwner = modelRegistry.getAuthStorageOwner();
 	if (options.authStorage && options.authStorage !== authStorage) {
 		throw new Error(
 			"options.authStorage and options.modelRegistry.authStorage must be the same instance when both are provided",
@@ -1360,6 +1415,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	}
 
 	let agent: Agent;
+	let sessionAgent: Agent | undefined;
 	let session!: AgentSession;
 	let sessionManager!: SessionManager;
 	let hasSession = false;
@@ -1390,7 +1446,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	let credentialScopeId: string | undefined;
 	let credentialScopeLeased = false;
 	let closeOwnedSettings: () => Promise<void> = async () => {};
-	const closeOwnedAuthStorage = (): void => {
+	const closeOwnedAuthStorage = async (): Promise<void> => {
+		if (ownsModelRegistry) await modelRegistry.dispose();
 		if (!hasSession && credentialScopeLeased && credentialScopeId) {
 			authStorage.releaseCredentialScope(credentialScopeId);
 			credentialScopeLeased = false;
@@ -1422,10 +1479,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			}
 		});
 		const applyCredentialSelector = (scopeId: string, provider: string, selector: AuthCredentialSelector): void => {
-			authStorage.setSessionCredentialSelector(scopeId, provider, selector);
+			authStorage.setSessionCredentialSelector(scopeId, provider, selector, authStorageOwner);
 		};
 		const ownsScopedSettings = options.settings === undefined;
 		const settings = options.settings ?? (await logger.time("settings", Settings.loadForScope, { cwd, agentDir }));
+		if (ownsModelRegistry) modelRegistry.setScopedSettings(settings);
 		const autoroutingInactive =
 			settings.get("task.autorouting.enabled") === true && !settings.getEffectiveAutorouting().active;
 		closeOwnedSettings = async (): Promise<void> => {
@@ -1695,10 +1753,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					) {
 						throw new Error("Durable numeric credential pin authority changed");
 					}
-					authStorage.setSessionCredentialSelector(credentialSessionId, record.provider, {
-						kind: pin.kind,
-						value: pin.value,
-					});
+					authStorage.setSessionCredentialSelector(
+						credentialSessionId,
+						record.provider,
+						{
+							kind: pin.kind,
+							value: pin.value,
+						},
+						authStorageOwner,
+					);
 					staleDurableCredentialPins.delete(resolveOAuthStorageProvider(record.provider));
 				}
 			} catch {
@@ -1770,8 +1833,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				credentialSessionId,
 			}),
 		);
+		const configuredDefaultPatterns = normalizeModelSelectorValue(settings.getModelRole("default"));
 		let model = options.model;
 		let modelFallbackMessage: string | undefined;
+		if (!hasExplicitModel && configuredDefaultPatterns.length > 0 && !defaultRoleSpec.model) {
+			modelFallbackMessage = `Model ${configuredDefaultPatterns.join(" -> ")} not found`;
+		}
 		const resumeModelBehavior = settings.get("session.resumeModelBehavior");
 		const persistedDefaultChain = existingSession.configuredModelChains.default;
 		const defaultModelEntries =
@@ -2066,13 +2133,49 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 							if (asyncJobManager!.isDeliverySuppressed(jobId, job?.generation)) return;
 							const deniedOwnedDelivery =
 								ownedCompletion !== undefined && !isOwnedCompletionEnvelopeAllowed(ownedCompletion);
+							// Fold disposition is decided by the coordinator's durable slot state.
+							// `parked` means the fold transaction has not finished capturing its
+							// receipt yet; it replays this completion itself, so enqueuing here
+							// would double-deliver.
+							const foldDisposition = job
+								? session.foldCoordinator.onDelivery(job, result)
+								: ({ kind: "ordinary" } as const);
+							if (foldDisposition.kind === "parked") {
+								if (job) asyncJobManager?.retainParkedDelivery(job, result);
+								return;
+							}
 							const formattedResult = await formatAsyncResultForFollowUp(result, !deniedOwnedDelivery);
+							if (
+								foldDisposition.kind === "receipt" &&
+								job &&
+								!session.foldCoordinator.claimCompletionDelivery(job)
+							)
+								return;
+							// A folded job's result must arrive with its receipt so the wake turn
+							// completes the original task rather than merely reporting output.
+							const deliveredResult =
+								foldDisposition.kind === "receipt"
+									? `${formattedResult}\n\n${describeFoldReceipt(foldDisposition.receipt)}`
+									: formattedResult;
+							// Exactly one transcript notice per completion: a retried delivery
+							// reuses the same job object, so the claim guards against repeats.
+							if (
+								foldDisposition.kind === "receipt" &&
+								job &&
+								session.foldCoordinator.claimCompletionNotice(job)
+							) {
+								session.emitNotice(
+									"info",
+									`Folded job ${foldDisposition.receipt.jobId} (${foldDisposition.receipt.label}) finished.`,
+									"fold",
+								);
+							}
 
 							const durationMs = job ? jobElapsedMs(job) : undefined;
 							session.yieldQueue.enqueue<AsyncResultEntry>("async-result", {
 								jobId,
 								generation: job?.generation ?? "",
-								result: formattedResult,
+								result: deliveredResult,
 								job,
 								durationMs,
 								...(ownedCompletion
@@ -2085,6 +2188,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 										}
 									: {}),
 							});
+							if (job) asyncJobManager?.retainDeliveryClaim(job);
 						},
 					})
 				: options.inheritedAsyncJobManager;
@@ -2346,174 +2450,240 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 										);
 									}
 									const from = sessionManager.getCwd();
-									const resolvedPath = path.resolve(from, target);
-									let canonicalFrom: string;
-									let canonicalTarget: string;
-									try {
-										canonicalFrom = await fs.realpath(from);
-										canonicalTarget = await fs.realpath(resolvedPath);
-									} catch {
-										throw new Error(`Directory does not exist or is not a directory: ${resolvedPath}`);
-									}
-									if (!(await fs.stat(canonicalTarget)).isDirectory()) {
-										throw new Error(`Directory does not exist or is not a directory: ${resolvedPath}`);
-									}
-									const relative = path.relative(canonicalFrom, canonicalTarget);
-									if (relative === "") {
-										throw new Error(
-											`Target ${canonicalTarget} is the current session directory; nothing to move.`,
-										);
+									const sourceHandle = await SessionManager.openNoFollowDirectory(from);
+									const sourceOpened = await sourceHandle.stat({ bigint: true });
+									if (!sourceOpened.isDirectory()) {
+										await sourceHandle.close().catch(() => {});
+										throw new Error(`Current session directory is no longer a directory: ${from}`);
 									}
-									if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-										throw new Error(
-											`Refusing to rescope outside the current session directory: ${canonicalTarget} is not within ${canonicalFrom}. move_session only narrows the session scope; ask the user to restart or /move for a broader relocation.`,
-										);
-									}
-									let targetHandle: nodeFs.promises.FileHandle | undefined;
-									let expectedIdentity: { dev: bigint; ino: bigint };
 									try {
-										targetHandle = await SessionManager.openNoFollowDirectory(canonicalTarget);
-										const opened = await targetHandle.stat({ bigint: true });
-										if (!opened.isDirectory()) {
+										const resolvedPath = path.resolve(from, target);
+										let canonicalFrom: string;
+										let canonicalTarget: string;
+										try {
+											canonicalFrom = await fs.realpath(from);
+											canonicalTarget = await fs.realpath(resolvedPath);
+										} catch (error) {
+											// macOS `realpath(3)` reports EACCES on an unreadable
+											// directory where Linux succeeds and fails later at the
+											// `access` probe; keep both platforms on the access message.
+											const code = (error as NodeJS.ErrnoException)?.code;
+											if (code === "EACCES" || code === "EPERM") {
+												throw new Error(
+													`Directory identity or access unavailable: ${resolvedPath}${
+														error instanceof Error ? ` (${error.message})` : ""
+													}`,
+												);
+											}
 											throw new Error(`Directory does not exist or is not a directory: ${resolvedPath}`);
 										}
-										expectedIdentity = { dev: opened.dev, ino: opened.ino };
-										await fs.access(canonicalTarget, nodeFs.constants.R_OK | nodeFs.constants.X_OK);
-									} catch (error) {
-										await targetHandle?.close().catch(() => {});
-										if (error instanceof Error && error.message.startsWith("Directory does not exist")) {
-											throw error;
+										if (!(await fs.stat(canonicalTarget)).isDirectory()) {
+											throw new Error(`Directory does not exist or is not a directory: ${resolvedPath}`);
 										}
-										throw new Error(
-											`Directory identity or access unavailable: ${canonicalTarget}${
-												error instanceof Error ? ` (${error.message})` : ""
-											}`,
-										);
-									}
-									// Process-cwd authority is an explicit claim, never inferred from
-									// `process.cwd() === from`: sibling sessions launched at the same
-									// root both satisfy that, so acting on it would chdir the process
-									// and clear process-global caches underneath the sibling.
-									const ownsProcessCwd = SessionManager.isProcessCwdOwner(sessionManager);
-									const restoreLaunchRoot = async (failure: unknown): Promise<never> => {
-										const restoreErrors: Error[] = [];
-										if (ownsProcessCwd) {
-											try {
-												setProjectDir(canonicalFrom);
-												if (path.resolve(process.cwd()) !== path.resolve(canonicalFrom)) {
-													throw new Error("Process cwd did not restore to the launch root.");
-												}
-											} catch (error) {
-												restoreErrors.push(error instanceof Error ? error : new Error(String(error)));
+										const relative = path.relative(canonicalFrom, canonicalTarget);
+										if (relative === "") {
+											throw new Error(
+												`Target ${canonicalTarget} is the current session directory; nothing to move.`,
+											);
+										}
+										if (
+											relative === ".." ||
+											relative.startsWith(`..${path.sep}`) ||
+											path.isAbsolute(relative)
+										) {
+											throw new Error(
+												`Refusing to rescope outside the current session directory: ${canonicalTarget} is not within ${canonicalFrom}. move_session only narrows the session scope; ask the user to restart or /move for a broader relocation.`,
+											);
+										}
+										let targetHandle: nodeFs.promises.FileHandle | undefined;
+										let expectedIdentity: { dev: bigint; ino: bigint };
+										try {
+											targetHandle = await SessionManager.openNoFollowDirectory(canonicalTarget);
+											const opened = await targetHandle.stat({ bigint: true });
+											if (!opened.isDirectory()) {
+												throw new Error(`Directory does not exist or is not a directory: ${resolvedPath}`);
 											}
-											try {
-												resetCapabilities();
-												const restoreRegistry = await resolveActiveProjectRegistryPath(canonicalFrom).catch(
-													() => undefined,
+											const revalidatedFrom = await fs.realpath(from);
+											const revalidatedTarget = await fs.realpath(resolvedPath);
+											const revalidatedRelative = path.relative(revalidatedFrom, revalidatedTarget);
+											if (
+												revalidatedFrom !== canonicalFrom ||
+												revalidatedTarget !== canonicalTarget ||
+												revalidatedRelative === "" ||
+												revalidatedRelative === ".." ||
+												revalidatedRelative.startsWith(`..${path.sep}`) ||
+												path.isAbsolute(revalidatedRelative)
+											) {
+												throw new Error(
+													`Directory identity changed during confinement validation: ${resolvedPath}`,
 												);
-												clearPluginRootsAndCaches(restoreRegistry ? [restoreRegistry] : undefined);
-											} catch (error) {
-												restoreErrors.push(error instanceof Error ? error : new Error(String(error)));
 											}
-										}
-										try {
-											await rebindCwdCapturingAuthority(canonicalFrom);
+											const named = await fs.lstat(revalidatedTarget, { bigint: true });
+											const namedSource = await fs.lstat(revalidatedFrom, { bigint: true });
+											if (
+												!namedSource.isDirectory() ||
+												namedSource.isSymbolicLink() ||
+												namedSource.dev !== sourceOpened.dev ||
+												namedSource.ino !== sourceOpened.ino ||
+												!named.isDirectory() ||
+												named.isSymbolicLink() ||
+												named.dev !== opened.dev ||
+												named.ino !== opened.ino
+											) {
+												throw new Error(
+													`Directory identity changed during confinement validation: ${resolvedPath}`,
+												);
+											}
+											expectedIdentity = { dev: opened.dev, ino: opened.ino };
+											await fs.access(canonicalTarget, nodeFs.constants.R_OK | nodeFs.constants.X_OK);
 										} catch (error) {
-											restoreErrors.push(error instanceof Error ? error : new Error(String(error)));
-										}
-										if (restoreErrors.length > 0) {
-											throw new AggregateError(
-												restoreErrors,
-												"Failed to restore launch-root rescope authority.",
-												{
-													cause: failure,
-												},
+											await targetHandle?.close().catch(() => {});
+											if (error instanceof Error && error.message.startsWith("Directory does not exist")) {
+												throw error;
+											}
+											throw new Error(
+												`Directory identity or access unavailable: ${canonicalTarget}${
+													error instanceof Error ? ` (${error.message})` : ""
+												}`,
 											);
 										}
-										throw failure;
-									};
-									try {
-										// Every fallible step that the moved session depends on runs
-										// BEFORE the session-file commit, so a failure here leaves the
-										// session exactly where it was and the tool call is a clean
-										// rejection rather than a half-moved session.
-										if (ownsProcessCwd) {
-											setProjectDir(canonicalTarget);
+										// Process-cwd authority is an explicit claim, never inferred from
+										// `process.cwd() === from`: sibling sessions launched at the same
+										// root both satisfy that, so acting on it would chdir the process
+										// and clear process-global caches underneath the sibling.
+										const ownsProcessCwd = SessionManager.isProcessCwdOwner(sessionManager);
+										const restoreLaunchRoot = async (failure: unknown): Promise<never> => {
+											const restoreErrors: Error[] = [];
+											if (ownsProcessCwd) {
+												try {
+													setProjectDir(canonicalFrom);
+													if (path.resolve(process.cwd()) !== path.resolve(canonicalFrom)) {
+														throw new Error("Process cwd did not restore to the launch root.");
+													}
+													await SessionManager.assertProcessCwdIdentity({
+														dev: sourceOpened.dev,
+														ino: sourceOpened.ino,
+													});
+												} catch (error) {
+													restoreErrors.push(error instanceof Error ? error : new Error(String(error)));
+												}
+												try {
+													resetCapabilities();
+													const restoreRegistry = await resolveActiveProjectRegistryPath(
+														canonicalFrom,
+													).catch(() => undefined);
+													clearPluginRootsAndCaches(restoreRegistry ? [restoreRegistry] : undefined);
+												} catch (error) {
+													restoreErrors.push(error instanceof Error ? error : new Error(String(error)));
+												}
+											}
 											try {
-												// `setProjectDir` chdirs a NAME. Confirm the process actually
-												// landed on the pinned directory, so a path replaced after
-												// the name checks cannot escape the validated descendant.
-												await SessionManager.assertProcessCwdIdentity(expectedIdentity);
+												await rebindCwdCapturingAuthority(canonicalFrom);
 											} catch (error) {
-												setProjectDir(canonicalFrom);
-												throw error;
+												restoreErrors.push(error instanceof Error ? error : new Error(String(error)));
 											}
-										}
-										let rescopeFailure: unknown;
+											if (restoreErrors.length > 0) {
+												throw new AggregateError(
+													restoreErrors,
+													"Failed to restore launch-root rescope authority.",
+													{
+														cause: failure,
+													},
+												);
+											}
+											throw failure;
+										};
 										try {
+											// Every fallible step that the moved session depends on runs
+											// BEFORE the session-file commit, so a failure here leaves the
+											// session exactly where it was and the tool call is a clean
+											// rejection rather than a half-moved session.
 											if (ownsProcessCwd) {
-												resetCapabilities();
-												const projectRegistry = await resolveActiveProjectRegistryPath(canonicalTarget);
-												clearPluginRootsAndCaches(projectRegistry ? [projectRegistry] : undefined);
+												setProjectDir(canonicalTarget);
+												try {
+													// `setProjectDir` chdirs a NAME. Confirm the process actually
+													// landed on the pinned directory, so a path replaced after
+													// the name checks cannot escape the validated descendant.
+													await SessionManager.assertProcessCwdIdentity(expectedIdentity);
+												} catch (error) {
+													setProjectDir(canonicalFrom);
+													await SessionManager.assertProcessCwdIdentity({
+														dev: sourceOpened.dev,
+														ino: sourceOpened.ino,
+													});
+													throw error;
+												}
+											}
+											let rescopeFailure: unknown;
+											try {
+												if (ownsProcessCwd) {
+													resetCapabilities();
+													const projectRegistry = await resolveActiveProjectRegistryPath(canonicalTarget);
+													clearPluginRootsAndCaches(projectRegistry ? [projectRegistry] : undefined);
+												}
+												// Plugin/MCP/Python authority must be rebound successfully
+												// before committing; swallowing a failure here is what leaves
+												// a moved session holding launch-root tool authority.
+												await rebindCwdCapturingAuthority(canonicalTarget);
+											} catch (error) {
+												rescopeFailure = error;
+											}
+											if (rescopeFailure !== undefined) {
+												await restoreLaunchRoot(rescopeFailure);
+											}
+											try {
+												await sessionManager.flush();
+												// Commit last: `moveTo` re-validates the pinned identity through
+												// the still-open handle at the state-changing boundary.
+												await sessionManager.moveTo(canonicalTarget, {
+													expectedIdentity,
+													targetHandle,
+													expectedSourceIdentity: { dev: sourceOpened.dev, ino: sourceOpened.ino },
+													sourceHandle,
+												});
+											} catch (error) {
+												const committedCwd = sessionManager.getCwd();
+												const stayedAtLaunchRoot = path.resolve(committedCwd) === path.resolve(from);
+												if (stayedAtLaunchRoot) await restoreLaunchRoot(error);
+												// SessionManager can publish the durable move before a later metadata
+												// write fails. Treat that state as committed rather than reporting a
+												// rejection after the session has moved.
+												moveConsumed = true;
+												logger.warn("Session rescope committed before finalization failed", {
+													error: safeErrorForLog(error),
+													cwd: committedCwd,
+												});
 											}
-											// Plugin/MCP/Python authority must be rebound successfully
-											// before committing; swallowing a failure here is what leaves
-											// a moved session holding launch-root tool authority.
-											await rebindCwdCapturingAuthority(canonicalTarget);
-										} catch (error) {
-											rescopeFailure = error;
-										}
-										if (rescopeFailure !== undefined) {
-											await restoreLaunchRoot(rescopeFailure);
-										}
-										try {
-											await sessionManager.flush();
-											// Commit last: `moveTo` re-validates the pinned identity through
-											// the still-open handle at the state-changing boundary.
-											await sessionManager.moveTo(canonicalTarget, {
-												expectedIdentity,
-												targetHandle,
-											});
-										} catch (error) {
-											const committedCwd = sessionManager.getCwd();
-											const stayedAtLaunchRoot = path.resolve(committedCwd) === path.resolve(from);
-											if (stayedAtLaunchRoot) await restoreLaunchRoot(error);
-											// SessionManager can publish the durable move before a later metadata
-											// write fails. Treat that state as committed rather than reporting a
-											// rejection after the session has moved.
 											moveConsumed = true;
-											logger.warn("Session rescope committed before finalization failed", {
-												error: safeErrorForLog(error),
-												cwd: committedCwd,
-											});
-										}
-										moveConsumed = true;
-										if (ownsProcessCwd) {
+											if (ownsProcessCwd) {
+												try {
+													await shutdownAllLspClients();
+												} catch (error) {
+													logger.warn("Failed to reset launch-root LSP clients after session rescope", {
+														error: safeErrorForLog(error),
+													});
+												}
+											}
+											// Cwd-derived read-only state the prompt and subagents consume.
+											// Best-effort by design: the move is committed, and a failed
+											// re-discovery must not present a committed move as a failure.
+											await applyRescopedReadState(sessionManager.getCwd());
 											try {
-												await shutdownAllLspClients();
+												await session?.refreshSshTool({ activateIfAvailable: true });
 											} catch (error) {
-												logger.warn("Failed to reset launch-root LSP clients after session rescope", {
+												// Non-fatal: the session has moved; the SSH tool refreshes
+												// on its next activation attempt.
+												logger.warn("Committed session rescope could not refresh the SSH tool", {
 													error: safeErrorForLog(error),
+													cwd: sessionManager.getCwd(),
 												});
 											}
+											return { from, to: sessionManager.getCwd() };
+										} finally {
+											await targetHandle.close().catch(() => {});
 										}
-										// Cwd-derived read-only state the prompt and subagents consume.
-										// Best-effort by design: the move is committed, and a failed
-										// re-discovery must not present a committed move as a failure.
-										await applyRescopedReadState(sessionManager.getCwd());
-										try {
-											await session?.refreshSshTool({ activateIfAvailable: true });
-										} catch (error) {
-											// Non-fatal: the session has moved; the SSH tool refreshes
-											// on its next activation attempt.
-											logger.warn("Committed session rescope could not refresh the SSH tool", {
-												error: safeErrorForLog(error),
-												cwd: sessionManager.getCwd(),
-											});
-										}
-										return { from, to: sessionManager.getCwd() };
 									} finally {
-										await targetHandle.close().catch(() => {});
+										await sourceHandle.close().catch(() => {});
 									}
 								});
 							};
@@ -2540,6 +2710,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			// (review thread P1). For a top-level session this equals the
 			// session id.
 			getSessionId: () => AsyncJobManager.endpointIdOf(asyncJobManager) ?? asyncJobEndpointId,
+			registerForegroundFoldParticipant: adapter =>
+				session?.registerForegroundFoldParticipant(adapter) ?? (() => {}),
+			hasForegroundBashBackgroundRequestHandler: () => session?.hasForegroundBashBackgroundRequestHandler() ?? false,
+			requestForegroundBashBackground: () => Promise.resolve(session?.requestForegroundBashBackground() ?? false),
+
 			getCredentialSessionId: () => session?.credentialSessionId ?? credentialSessionId,
 			getMcpManager: () => mcpManager ?? options.inheritedMcpManager,
 			isManagedSessionDestination: () => sessionManager.isManagedDestination(),
@@ -2568,6 +2743,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			getToolForExecution: name => session?.getToolForExecution(name),
 			agentRegistry,
 			getSessionSpawns: () => options.spawns ?? "*",
+			getMasterBashCapability: () => masterModeContext?.getCapability(),
+			getMasterOwnerSessionId: () => masterModeContext?.ownerSessionId,
 			getModelString: () => (hasExplicitModel && model ? formatModelString(model) : undefined),
 			getActiveModelString,
 			getPlanModeState: () => session?.getPlanModeState(),
@@ -3116,6 +3293,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 							controller: notificationSessionController,
 							spawnedByGjc,
 							sdkHostModeSupported: options.sdkHostModeSupported,
+							...(masterModeContext
+								? {
+										masterCapability: masterModeContext.getCapability(),
+										masterAttestationEpoch: masterModeContext.attestationEpoch,
+										masterOwnerSessionId: masterModeContext.ownerSessionId,
+									}
+								: {}),
 							// INTERNAL terminal-abort seams, threaded directly from the
 							// owning session (NOT on the public extension context).
 							terminalAbortSeams: {
@@ -3163,9 +3347,19 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						createSdkSessionRuntimeExtension(api, {
 							agentDir,
 							brokerRegistrationRequired: lifecycleStartupCapability !== undefined,
+							...(lifecycleStartupCapability?.lifecycleRequestId
+								? { lifecycleRequestId: lifecycleStartupCapability.lifecycleRequestId }
+								: {}),
 							createTransport: input => createSdkWebSocketTransport(input),
 							settings,
 							configOverrides: new Map(),
+							...(masterModeContext
+								? {
+										masterCapability: masterModeContext.getCapability(),
+										masterAttestationEpoch: masterModeContext.attestationEpoch,
+										masterOwnerSessionId: masterModeContext.ownerSessionId,
+									}
+								: {}),
 							// INTERNAL terminal-abort seams, threaded directly from the
 							// owning session (NOT on the public extension context).
 							terminalAbortSeams: {
@@ -3364,11 +3558,38 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// Fall back to first available model with a valid API key, honoring the
 		// path-scoped `enabledModels` allow-list when configured. Skip when the
 		// user explicitly requested a model via --model that wasn't found.
-		if (!model && !options.modelPattern && !startupCredentialModelRejected) {
+		if (
+			!model &&
+			!options.modelPattern &&
+			!startupCredentialModelRejected &&
+			configuredDefaultPatterns.length === 0
+		) {
 			// Re-resolve the allowed set: extension factories above may have
 			// registered providers/models that weren't visible at startup.
-			const fallbackCandidates = await resolveAllowedModels(modelRegistry, settings, modelMatchPreferences);
-			for (const candidate of fallbackCandidates) {
+			const allowedFallbackCandidates = await resolveAllowedModels(modelRegistry, settings, modelMatchPreferences);
+			// A fresh provider discovery can disprove a bundled model while the
+			// general available catalog retains it for offline/profile compatibility.
+			// Exclude only those positively disproved bundled entries from the
+			// unconfigured startup path; explicit model/profile resolution above keeps
+			// its existing precedence and semantics.
+			const profileAvailableKeys = new Set(
+				modelRegistry
+					.getAvailableForProfileActivation()
+					.map(candidate => `${candidate.provider}\u0000${candidate.id}`),
+			);
+			const fallbackCandidates = allowedFallbackCandidates.filter(candidate =>
+				profileAvailableKeys.has(`${candidate.provider}\u0000${candidate.id}`),
+			);
+			// Candidate order is not a quality signal: catalogs sort retired models
+			// ahead of current ones whenever their IDs carry older date suffixes, so
+			// an unconfigured install would otherwise start on a model its provider
+			// has already withdrawn. Sweep each known provider's curated default
+			// first — the same table `findInitialModel` consults — and only then fall
+			// back to catalog order.
+			for (const candidate of orderByProviderDefaultFirst(
+				fallbackCandidates,
+				modelRegistry.automaticProviderOrder(credentialSessionId),
+			)) {
 				if (await hasModelApiKey(candidate)) {
 					model = candidate;
 					break;
@@ -3720,16 +3941,20 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				if (hasSession) session.configWarnings.push(warning);
 				logger.warn("Context file discovery warning", { warning });
 			}
+			// The master doctrine block is appended exactly once, AFTER any custom
+			// system-prompt transformation, and only for the master session itself.
+			const withMasterGuidance = (built: BuildSystemPromptResult): BuildSystemPromptResult =>
+				masterModeContext ? { ...built, systemPrompt: [...built.systemPrompt, masterModeTemplate.trim()] } : built;
 			if (options.systemPrompt === undefined) {
-				return defaultPrompt;
+				return withMasterGuidance(defaultPrompt);
 			}
 			if (Array.isArray(options.systemPrompt)) {
-				return { systemPrompt: options.systemPrompt, warnings: defaultPrompt.warnings };
+				return withMasterGuidance({ systemPrompt: options.systemPrompt, warnings: defaultPrompt.warnings });
 			}
-			return {
+			return withMasterGuidance({
 				systemPrompt: options.systemPrompt(defaultPrompt.systemPrompt),
 				warnings: defaultPrompt.warnings,
-			};
+			});
 		};
 
 		const toolNamesFromRegistry = Array.from(toolRegistry.keys());
@@ -4073,31 +4298,43 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			preferWebsockets: preferOpenAICodexWebsockets,
 			getToolContext: tc => toolContextStore.getContext(tc),
 			getApiKey: async provider => {
-				// Read agent.sessionId at call time so credential selection stays aligned
-				// with metadataResolver after /new, fork, resume, or branch switches.
-				const key = await modelRegistry.getApiKeyForProvider(provider, credentialSessionId);
-				if (!key) {
+				// AgentLoop asks by provider, but the active model carries the
+				// model-scoped credential selector. Read it at call time so model
+				// changes are honored after /new, fork, resume, or branch switches.
+				const liveModel = sessionAgent?.state.model ?? model;
+				const key =
+					liveModel?.provider === provider
+						? await modelRegistry.getApiKey(liveModel, credentialSessionId)
+						: undefined;
+				const providerKey = key ?? (await modelRegistry.getApiKeyForProvider(provider, credentialSessionId));
+				if (!providerKey) {
 					throw new Error(`No API key found for provider "${provider}"`);
 				}
-				return key;
+				return providerKey;
 			},
 			getAuthCredentialType: provider => modelRegistry.getSessionCredentialType(provider, credentialSessionId),
 			streamFn: async (streamModel, context, streamOptions) => {
 				const requestStartedAt = performance.now();
 				let stream: Awaited<ReturnType<typeof streamSimple>>;
 				try {
+					const effectiveApiKey = await modelRegistry.getApiKey(streamModel, credentialSessionId);
 					stream = await streamSimple(streamModel, context, {
 						...streamOptions,
+						apiKey: effectiveApiKey,
+						authCredentialType: modelRegistry.getSessionCredentialType(streamModel.provider, credentialSessionId),
 						onAuthError: async (provider, oldKey, error) => {
 							await modelRegistry.authStorage.invalidateCredentialMatching(provider, oldKey, {
 								signal: streamOptions?.signal,
 								sessionId: credentialSessionId,
+								owner: modelRegistry.getAuthStorageOwner(),
 							});
 							logger.debug("Retrying provider request after credential invalidation", {
 								provider,
 								error: error instanceof Error ? error.message : String(error),
 							});
-							return modelRegistry.getApiKeyForProvider(provider, credentialSessionId);
+							return modelRegistry.getApiKey(streamModel, credentialSessionId, {
+								signal: streamOptions?.signal,
+							});
 						},
 					});
 				} catch (error) {
@@ -4160,6 +4397,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			telemetry: options.telemetry,
 			appendOnlyContext,
 		});
+		sessionAgent = agent;
 
 		cursorEventEmitter = event => agent.emitExternalEvent(event);
 
@@ -4282,10 +4520,39 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// carried by the host replay ring through the internal runtime seam above.
 		if (autoroutingInactive) session.configWarnings.push(AUTOROUTING_INACTIVE_WARNING);
 		hasSession = true;
+		if (masterModeContext) {
+			// One scoped, no-probe peer snapshot immediately before the FIRST accepted
+			// provider request; see createMasterPeerSnapshotContributor for the
+			// discard/reuse/no-duplicate semantics.
+			const capturedSession = session;
+			session.registerBeforeAgentStartContributor(
+				createMasterPeerSnapshotContributor({
+					lifecycle: createSessionLifecycleService(agentDir),
+					ownerSessionId: masterModeContext.ownerSessionId,
+					getSessionId: () => sessionManager.getSessionId(),
+					scope: masterModeContext.scope,
+					getCwd: getLiveCwd,
+					hasPersistedInjection: () =>
+						capturedSession.sessionManager
+							.getBranch()
+							.some(
+								entry =>
+									entry.type === "message" &&
+									(entry.message as { customType?: string }).customType === MASTER_PEER_SNAPSHOT_CUSTOM_TYPE,
+							),
+					onError: error =>
+						logger.debug("master peer snapshot injection failed", { error: safeErrorForLog(error) }),
+				}),
+			);
+		}
 		const sessionAsyncJobManager = asyncJobManager;
 		if (sessionAsyncJobManager) {
 			session.yieldQueue.register<AsyncResultEntry>("async-result", {
-				isStale: entry => sessionAsyncJobManager.isDeliverySuppressed(entry.jobId, entry.generation),
+				isStale: entry => {
+					const stale = sessionAsyncJobManager.isDeliverySuppressed(entry.jobId, entry.generation);
+					if (stale) sessionAsyncJobManager.releaseDeliveryClaim(entry.generation);
+					return stale;
+				},
 				// Build one message per ownership origin so an owned-scope drop of
 				// one turn's message never suppresses other turns'/ordinary
 				// completions batched in the same flush (review thread P2).
@@ -4293,7 +4560,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					entry.ownedCompletion
 						? `${entry.ownedCompletion.lineageIdHash}\u0000${entry.ownedCompletion.promptAttemptEpoch}`
 						: "ordinary",
-				build: buildAsyncResultBatchMessage,
+				build: entries => {
+					try {
+						return buildAsyncResultBatchMessage(entries);
+					} finally {
+						for (const entry of entries) sessionAsyncJobManager.releaseDeliveryClaim(entry.generation);
+					}
+				},
 			});
 		}
 		session.yieldQueue.register<McpNotificationEntry>("mcp-notification", {
@@ -4329,7 +4602,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 							);
 							AsyncJobManager.unregisterManager(asyncJobManager);
 						}
-						closeOwnedAuthStorage();
+						await closeOwnedAuthStorage();
 						await closeOwnedSettings();
 					}
 				}
@@ -4599,7 +4872,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			}
 			releaseLocalProtocolOverride();
 			try {
-				closeOwnedAuthStorage();
+				await closeOwnedAuthStorage();
 			} catch (authCleanupError) {
 				logger.warn("Failed to close owned auth storage after startup error", { error: authCleanupError });
 			}