@gajae-code/coding-agent 0.17.6 → 0.17.7

package/src/session/agent-session.ts

@@ -400,7 +400,11 @@ import type { NotificationSessionController } from "../sdk/bus/session-control";
 import { buildSyntheticModelId, syntheticNamespaceCollision } from "../sdk/model-profile-model";
 import { sanitizePromptFailure } from "../sdk/prompt-failure";
 import type { SecretObfuscator } from "../secrets/obfuscator";
-import { formatNoCredentialOnboardingError, formatNoModelOnboardingError } from "../setup/model-onboarding-guidance";
+import {
+	formatNoCredentialOnboardingError,
+	formatNoModelOnboardingError,
+	NoModelSelectedError,
+} from "../setup/model-onboarding-guidance";
 import {
 	isCanonicalGjcWorkflowSkill,
 	isWorkflowContinuationInert,
@@ -410,6 +414,7 @@ import {
 import { assertWorkflowMutationAllowed } from "../skill-state/workflow-mutation-guard";
 import { invalidateHostMetadata } from "../ssh/connection-manager";
 import { buildVolatileProjectContext } from "../system-prompt";
+import { DelegationHintController } from "../task/delegation-hint";
 import { resolveThinkingLevelForModel, toReasoningEffort } from "../thinking";
 import {
 	buildDiscoverableToolSearchIndex,
@@ -3633,6 +3638,7 @@ export class AgentSession {
 	/** Idempotent unregister handle for this session's resource-GC registration. */
 	#unregisterResourceGc?: () => void;
 	#unregisterRuntimeStateFinalizer?: () => void;
+	#coordinatorRuntimeStateFileOverrideForTests: string | undefined = undefined;
 	#unregisterBeforeMoveListener?: () => void;
 	#unregisterMoveAbortListener?: () => void;
 	#unregisterMovePublicationListener?: () => void;
@@ -3658,6 +3664,7 @@ export class AgentSession {
 		);
 	}
 	#unregisterSessionMemorySettings?: () => void;
+	#unregisterDelegationHintSettings?: () => void;
 	/**
 	 * AsyncJobManager owned by this session (top-level only). Subagents leave
 	 * this undefined and **MUST NOT** dispose the global instance on teardown.
@@ -3830,6 +3837,7 @@ export class AgentSession {
 
 	// TTSR manager for time-traveling stream rules
 	#ttsrManager: TtsrManager | undefined = undefined;
+	#delegationHint: DelegationHintController;
 	#pendingTtsrInjections: Rule[] = [];
 	/** Per-tool TTSR rules whose `interruptMode` opted out of aborting the stream.
 	 *  These are folded into the matched tool call's `toolResult` content as an
@@ -4138,6 +4146,8 @@ export class AgentSession {
 
 	#appendCoordinatorPersist(run: () => Promise<void>): Promise<void> {
 		const queued = this.#coordinatorPersistQueue.then(run, run);
+		const testFailures = this.#coordinatorPersistFailuresForTests;
+		if (testFailures) void queued.catch(error => testFailures.push(error));
 		this.#coordinatorPersistQueue = queued.catch(() => {});
 		return queued;
 	}
@@ -5646,10 +5656,58 @@ export class AgentSession {
 		this.#credentialStoreIdentity = config.credentialStoreIdentity;
 		this.#providerCacheSessionId = config.providerCacheSessionId;
 		this.#asyncJobProviderSessionId = config.asyncJobProviderSessionId;
+		this.#delegationHint = new DelegationHintController({
+			getMode: () => this.settings.get("task.delegationHint.mode"),
+			getAutoroutingEnabled: () => this.settings.getEffectiveAutorouting().active,
+			getAutoroutingTiers: () => this.settings.get("task.autorouting.tiers"),
+			notify: message => this.emitNotice("info", message, "delegation-hint"),
+		});
+		this.#unregisterDelegationHintSettings = this.settings.onChanged(settingPath => {
+			if (settingPath === "task.delegationHint.mode") {
+				this.#delegationHint.setEnabled(this.settings.get("task.delegationHint.mode") === "hint");
+			}
+		});
 		// Per-tool TTSR reminders are folded into the matched tool's result via this hook.
-		this.agent.afterToolCall = ctx => {
+		this.agent.afterToolCall = (ctx, signal) => {
 			settleToolLineageRegistrationWindow(ctx.toolCall.id, this.#ownedRegistrationEndpoint());
-			return this.#ttsrAfterToolCall(ctx);
+			const ttsrResult = this.#ttsrAfterToolCall(ctx);
+			const delegationHintEnabled = this.settings.get("task.delegationHint.mode") === "hint";
+			this.#delegationHint.setEnabled(delegationHintEnabled);
+			if (delegationHintEnabled) {
+				try {
+					this.#delegationHint.observeAfterToolCall(
+						{
+							toolName: ctx.toolCall.name,
+							args: ctx.args,
+							isError: ctx.isError,
+							resultError: ctx.result.isError === true,
+							getRemainingContextRatio: () => {
+								const percent = this.getContextUsage()?.percent;
+								return typeof percent === "number" && Number.isFinite(percent)
+									? Math.min(1, Math.max(0, 1 - percent / 100))
+									: undefined;
+							},
+							getActivePlanStepCount: () => {
+								// Tasks within a phase are peers; do not combine separate ordered phases.
+								return this.getTodoPhases().reduce(
+									(largestPhase, phase) =>
+										Math.max(
+											largestPhase,
+											phase.tasks.filter(
+												task => task.status === "pending" || task.status === "in_progress",
+											).length,
+										),
+									0,
+								);
+							},
+						},
+						signal,
+					);
+				} catch {
+					// Advisory inference never overrides an executed tool result.
+				}
+			}
+			return ttsrResult;
 		};
 		// Bind immutable lineage/attempt metadata to each tool call id before the
 		// tool executes. Background registrations made inside the tool (task, Bash)
@@ -6910,6 +6968,7 @@ export class AgentSession {
 
 	/** Serializes sidecar writes in publication order, independent of write latency. */
 	#coordinatorPersistQueue: Promise<void> = Promise.resolve();
+	#coordinatorPersistFailuresForTests: unknown[] | undefined;
 
 	#recordPostPublicationOutcome(
 		context: CoordinatorRuntimeStatePersistContext,
@@ -6975,6 +7034,9 @@ export class AgentSession {
 	 */
 	#runtimeStateMarkerFile(input: { sessionId: string; cwd: string }): string | null {
 		if (!input.sessionId.trim()) return null;
+		if (this.#coordinatorRuntimeStateFileOverrideForTests) {
+			return this.#coordinatorRuntimeStateFileOverrideForTests;
+		}
 		const pinned = process.env[GJC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim();
 		if (this.taskDepth > 0) return sessionRuntimeStatePath(input.cwd, input.sessionId);
 		return pinned || sessionRuntimeStatePath(input.cwd, input.sessionId);
@@ -7055,6 +7117,7 @@ export class AgentSession {
 					{ event: event.type, ...(attempt > 0 ? { retries: attempt } : {}) },
 				);
 				if (propagateFailure) throw error;
+				this.#coordinatorPersistFailuresForTests?.push(error);
 				return;
 			}
 		}
@@ -7080,11 +7143,18 @@ export class AgentSession {
 	async #emitSessionEvent(event: AgentSessionEvent, eventLease?: RunResourceProducerLease): Promise<void> {
 		const attemptScope = (event as AgentSessionEvent & { scope?: AttemptScope }).scope;
 		if (event.type === "turn_start") {
+			const delegationHintEnabled = this.settings.get("task.delegationHint.mode") === "hint";
+			this.#delegationHint.setEnabled(delegationHintEnabled);
+			if (delegationHintEnabled) this.#delegationHint.onTurnStart();
 			this.#extensionTurnGeneration++;
 			this.#closedExtensionTurnGeneration = undefined;
 		} else if (event.type === "turn_end") {
 			this.#closedExtensionTurnGeneration = this.#extensionTurnGeneration;
 		}
+		if (event.type === "message_end" && event.message.role === "user") {
+			this.#delegationHint.setEnabled(this.settings.get("task.delegationHint.mode") === "hint");
+			this.#delegationHint.onUserMessage();
+		}
 		if (event.type === "message_update") {
 			// Fast path: message_update maps to no sidecar state, so we must not
 			// build the persistRuntimeState closure here (per-token hot path).
@@ -10152,6 +10222,20 @@ export class AgentSession {
 		this.#disposeTimeoutMs = Math.max(0, timeoutMs);
 	}
 
+	/** Bind coordinator runtime-state persistence to this session in tests. */
+	setCoordinatorRuntimeStateFileForTests(stateFile: string): void {
+		if (!path.isAbsolute(stateFile)) {
+			throw new Error("Coordinator runtime-state test path must be absolute.");
+		}
+		this.#coordinatorRuntimeStateFileOverrideForTests = path.resolve(stateFile);
+		this.#registerRuntimeStateFinalizer();
+	}
+
+	/** Read the test-only coordinator runtime-state path bound to this session. */
+	getCoordinatorRuntimeStateFileForTests(): string | undefined {
+		return this.#coordinatorRuntimeStateFileOverrideForTests;
+	}
+
 	trackPostPromptTaskForTests(task: Promise<void>): void {
 		this.#trackPostPromptTask(task, this.#selectionFenceGeneration);
 	}
@@ -10332,6 +10416,8 @@ export class AgentSession {
 		this.#unregisterResourceGc = undefined;
 		this.#unregisterSessionMemorySettings?.();
 		this.#unregisterSessionMemorySettings = undefined;
+		this.#unregisterDelegationHintSettings?.();
+		this.#unregisterDelegationHintSettings = undefined;
 		if (ownerTerminalContextFromEnvironment() === null) this.#unregisterRuntimeStateFinalizer?.();
 		this.#unregisterRuntimeStateFinalizer = undefined;
 		this.#unregisterBeforeMoveListener?.();
@@ -10443,6 +10529,8 @@ export class AgentSession {
 		this.#unregisterResourceGc = undefined;
 		this.#unregisterSessionMemorySettings?.();
 		this.#unregisterSessionMemorySettings = undefined;
+		this.#unregisterDelegationHintSettings?.();
+		this.#unregisterDelegationHintSettings = undefined;
 		const work = Promise.allSettled([
 			// kill:true so a forced exit also reaps spawned-app Chrome we own (headless
 			// always closes; connected/attached browsers only disconnect — never killed).
@@ -10594,6 +10682,11 @@ export class AgentSession {
 		});
 	}
 
+	/** Enable sidecar write failure reporting for retry-test teardown. */
+	trackCoordinatorRuntimeStatePersistenceFailuresForTests(): void {
+		this.#coordinatorPersistFailuresForTests = [];
+	}
+
 	/** Test seam: await all currently admitted coordinator sidecar writes. */
 	async awaitCoordinatorRuntimeStatePersistenceForTests(): Promise<void> {
 		// A terminal abort can schedule a preserved follow-up as a fresh turn after
@@ -10616,6 +10709,11 @@ export class AgentSession {
 		}
 		await this.#coordinatorPersistQueue;
 		await this.#drainUnbarrieredCoordinatorPersists();
+		const failures = this.#coordinatorPersistFailuresForTests;
+		if (failures && failures.length > 0) {
+			this.#coordinatorPersistFailuresForTests = [];
+			throw new AggregateError(failures, "Coordinator runtime-state persistence failed during test");
+		}
 	}
 	queueCoordinatorRuntimeStatePersistForTests(event: AgentSessionEvent, gate: Promise<void>): Promise<void> {
 		this.#agentEventAdmission.set(event, {
@@ -13782,7 +13880,7 @@ export class AgentSession {
 
 			// Validate model
 			if (!this.model) {
-				throw new Error(formatNoModelOnboardingError());
+				throw new NoModelSelectedError();
 			}
 
 			// Validate API key

package/src/session/internal/managed-session-scope.ts

@@ -303,7 +303,7 @@ export type ManagedCandidateListing =
 			scope: ManagedScope;
 			owned: readonly ManagedCandidate[];
 			foreignCount: number;
-			invalid: readonly { code: string }[];
+			invalid: readonly { code: string; sessionId?: string }[];
 	  }
 	| { kind: "error"; code: "scan_failed" | "unsafe_root" | "invalid_candidate"; message: string };
 
@@ -347,6 +347,7 @@ export interface ManagedLockReleaseTestEvent {
 export const ManagedSessionScopeTestHooks: {
 	beforeVerifiedDelete?: (event: ManagedVerifiedDeleteTestEvent) => void | Promise<void>;
 	beforeManagedLockRelease?: (event: ManagedLockReleaseTestEvent) => void | Promise<void>;
+	afterCandidatePreflight?: (event: { readonly sessionId?: string }) => void;
 } = {};
 
 async function deleteSessionVerifiedWithFence(
@@ -801,49 +802,86 @@ export function fsyncCanonicalBinding(bindingPath: string, expected: string): vo
 }
 
 type CandidatePreflight =
-	| { kind: "capture"; identity: { dev: bigint; ino: bigint; size: number; mtimeNs: bigint } }
+	| {
+			kind: "capture";
+			sessionId: string;
+			cwd: string;
+			diagnosticSessionId?: string;
+			identity: Pick<ManagedFileSnapshot["identity"], "dev" | "ino" | "nlink" | "size" | "mtimeNs" | "ctimeNs">;
+	  }
 	| {
 			kind: "foreign";
 	  }
 	| {
 			kind: "invalid";
 			code: string;
+			diagnosticSessionId?: string;
 	  };
 
+function safeManagedCandidateSessionId(value: unknown): string | undefined {
+	return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value) ? value : undefined;
+}
+
+function invalidCandidatePreflight(filePath: string, code: string): CandidatePreflight {
+	const diagnosticSessionId = safeManagedCandidateSessionId(path.basename(filePath, ".jsonl"));
+	return {
+		kind: "invalid",
+		code,
+		...(diagnosticSessionId === undefined ? {} : { diagnosticSessionId }),
+	};
+}
+
 function preflightCandidate(filePath: string, scope: ManagedScope): CandidatePreflight {
 	try {
 		const snapshot = captureManagedFilePrefixNoFollow(filePath, HEADER_MAX_BYTES);
 		const lineEnd = snapshot.bytes.indexOf(0x0a);
-		if (lineEnd < 0) return { kind: "invalid", code: "invalid_header" };
+		if (lineEnd < 0) return invalidCandidatePreflight(filePath, "invalid_header");
 		const value: unknown = JSON.parse(snapshot.bytes.subarray(0, lineEnd).toString("utf8"));
 		if (!value || typeof value !== "object" || Array.isArray(value))
-			return { kind: "invalid", code: "invalid_header" };
+			return invalidCandidatePreflight(filePath, "invalid_header");
 		const header = value as Record<string, unknown>;
 		if (header.type !== "session" || typeof header.id !== "string" || typeof header.cwd !== "string")
-			return { kind: "invalid", code: "invalid_header" };
+			return invalidCandidatePreflight(filePath, "invalid_header");
+		const diagnosticSessionId = safeManagedCandidateSessionId(header.id);
 		const candidateIdentity = identityFor(header.cwd);
 		if (
 			candidateIdentity.ok &&
 			(candidateIdentity.platform !== scope.platform || candidateIdentity.canonicalPath !== scope.canonicalCwd)
 		)
 			return { kind: "foreign" };
-		return { kind: "capture", identity: snapshot.identity };
-	} catch {
-		return { kind: "invalid", code: "unreadable_candidate" };
+		return {
+			kind: "capture",
+			sessionId: header.id,
+			cwd: header.cwd,
+			...(diagnosticSessionId === undefined ? {} : { diagnosticSessionId }),
+			identity: snapshot.identity,
+		};
+	} catch (error) {
+		return invalidCandidatePreflight(
+			filePath,
+			error instanceof Error && error.message === "source_changed" ? "source_changed" : "unreadable_candidate",
+		);
 	}
 }
 
 function matchesPreflightIdentity(candidate: ManagedCandidate, preflight: CandidatePreflight): boolean {
 	return (
 		preflight.kind === "capture" &&
+		candidate.sessionId === preflight.sessionId &&
+		candidate.cwd === preflight.cwd &&
 		candidate.identity.dev === preflight.identity.dev &&
 		candidate.identity.ino === preflight.identity.ino &&
+		candidate.identity.nlink === preflight.identity.nlink &&
 		candidate.identity.size === preflight.identity.size &&
-		candidate.identity.mtimeNs === preflight.identity.mtimeNs
+		candidate.identity.mtimeNs === preflight.identity.mtimeNs &&
+		candidate.identity.ctimeNs === preflight.identity.ctimeNs
 	);
 }
 
-function inspectCandidate(filePath: string, provenance: "v2" | "legacy"): ManagedCandidate | { code: string } {
+function inspectCandidate(
+	filePath: string,
+	provenance: "v2" | "legacy",
+): ManagedCandidate | { code: string; sessionId?: string } {
 	try {
 		const snapshot = inspectManagedFileNoFollow(filePath, HEADER_MAX_BYTES);
 		const lineEnd = snapshot.bytes.subarray(0, HEADER_MAX_BYTES).indexOf(0x0a);
@@ -905,7 +943,7 @@ function discoveredLegacyDirectoryNames(scope: ManagedScope): readonly string[]
 	return [...known, ...discovered];
 }
 
-type CandidateInspection = ManagedCandidate | { code: string } | { foreign: true };
+type CandidateInspection = ManagedCandidate | { code: string; sessionId?: string } | { foreign: true };
 
 function listDirectoryCandidates(
 	directory: string,
@@ -926,11 +964,29 @@ function listDirectoryCandidates(
 		.map(entry => {
 			const filePath = path.join(directory, entry.name);
 			const preflight = preflightCandidate(filePath, scope);
-			if (preflight.kind === "invalid") return { code: preflight.code };
+			if (preflight.kind === "invalid")
+				return {
+					code: preflight.code,
+					...(preflight.diagnosticSessionId === undefined ? {} : { sessionId: preflight.diagnosticSessionId }),
+				};
 			if (preflight.kind === "foreign") return { foreign: true };
+			ManagedSessionScopeTestHooks.afterCandidatePreflight?.({
+				...(preflight.diagnosticSessionId === undefined ? {} : { sessionId: preflight.diagnosticSessionId }),
+			});
 			const candidate = inspectCandidate(filePath, provenance);
-			if ("code" in candidate) return candidate;
-			return matchesPreflightIdentity(candidate, preflight) ? candidate : { code: "source_changed" };
+			if ("code" in candidate)
+				return {
+					...candidate,
+					...(candidate.sessionId === undefined && preflight.diagnosticSessionId !== undefined
+						? { sessionId: preflight.diagnosticSessionId }
+						: {}),
+				};
+			return matchesPreflightIdentity(candidate, preflight)
+				? candidate
+				: {
+						code: "source_changed",
+						...(preflight.diagnosticSessionId === undefined ? {} : { sessionId: preflight.diagnosticSessionId }),
+					};
 		});
 }
 
@@ -1645,7 +1701,7 @@ export function listManagedCandidates(scope: ManagedScope): ManagedCandidateList
 		if (!root.isDirectory() || root.isSymbolicLink())
 			return { kind: "error", code: "unsafe_root", message: "The sessions root is unsafe." };
 		const owned: ManagedCandidate[] = [];
-		const invalid: { code: string }[] = [];
+		const invalid: { code: string; sessionId?: string }[] = [];
 		let foreignCount = 0;
 		const directories: Array<{ path: string; provenance: "v2" | "legacy" }> = [
 			{ path: scope.directoryPath, provenance: "v2" },
@@ -1658,7 +1714,10 @@ export function listManagedCandidates(scope: ManagedScope): ManagedCandidateList
 		for (const directory of directories) {
 			for (const candidate of listDirectoryCandidates(directory.path, directory.provenance, scope)) {
 				if ("code" in candidate) {
-					invalid.push({ code: candidate.code });
+					invalid.push({
+						code: candidate.code,
+						...(candidate.sessionId === undefined ? {} : { sessionId: candidate.sessionId }),
+					});
 					continue;
 				}
 				if ("foreign" in candidate) {
@@ -1667,7 +1726,12 @@ export function listManagedCandidates(scope: ManagedScope): ManagedCandidateList
 				}
 				const candidateIdentity = identityFor(candidate.cwd);
 				if (!candidateIdentity.ok) {
-					invalid.push({ code: `cwd_${candidateIdentity.code}` });
+					invalid.push({
+						code: `cwd_${candidateIdentity.code}`,
+						...(safeManagedCandidateSessionId(candidate.sessionId) === undefined
+							? {}
+							: { sessionId: candidate.sessionId }),
+					});
 					continue;
 				}
 				if (

package/src/session/session-manager.ts

@@ -61,6 +61,12 @@ import {
 	Snowflake,
 	toError,
 } from "@gajae-code/utils";
+import {
+	InvalidModelProfileOwnershipError,
+	MODEL_PROFILE_OWNERSHIP_ENTRY,
+	type ModelProfileOwnershipMarker,
+	validateModelProfileOwnershipMarker,
+} from "../config/model-profile-ownership";
 import { EDIT_SNAPSHOT_EXTERNALIZED_NOTICE, editSnapshotReceipt } from "../edit/renderer";
 import type { TtsrInjectionRecord } from "../export/ttsr";
 import { assertSafePathComponent } from "../gjc-runtime/session-layout";
@@ -1195,20 +1201,25 @@ function isValidPersistedReducerState(value: ReducerState): boolean {
 }
 
 function isProviderStateEntry(entry: SessionEntry): boolean {
-	return [
-		"thinking_level_change",
-		"model_change",
-		"configured_model_chain",
-		"service_tier_change",
-		"mcp_tool_selection",
-		"discovered_builtin_tool_selection",
-		"mode_change",
-		"ttsr_injection",
-	].includes(entry.type);
+	return (
+		(entry.type === "custom" && entry.customType === MODEL_PROFILE_OWNERSHIP_ENTRY) ||
+		[
+			"thinking_level_change",
+			"model_change",
+			"configured_model_chain",
+			"service_tier_change",
+			"mcp_tool_selection",
+			"discovered_builtin_tool_selection",
+			"mode_change",
+			"ttsr_injection",
+		].includes(entry.type)
+	);
 }
 
 function providerStateEntryKey(entry: SessionEntry): string | undefined {
 	if (!isProviderStateEntry(entry)) return undefined;
+	if (entry.type === "custom" && entry.customType === MODEL_PROFILE_OWNERSHIP_ENTRY)
+		return `${entry.type}:${entry.customType}`;
 	return entry.type === "configured_model_chain" ? `${entry.type}:${entry.role}` : entry.type;
 }
 /** Map a session entry to its rolling-tail record kind. */
@@ -2091,6 +2102,8 @@ export interface SessionContext {
 	models: Record<string, string>;
 	/** Configured fallback chains for model roles on the active branch. */
 	configuredModelChains: Record<string, ConfiguredModelChain>;
+	/** Effective-branch profile owner decision; absent means the legacy inherit marker. */
+	modelProfileOwnershipMarker?: ModelProfileOwnershipMarker;
 
 	/** Names of TTSR rules that have been injected this session */
 	injectedTtsrRules: string[];
@@ -2986,6 +2999,7 @@ export function buildSessionContext(
 	let serviceTier: ServiceTier | undefined;
 	const models: Record<string, string> = {};
 	const configuredModelChains: Record<string, ConfiguredModelChain> = {};
+	let modelProfileOwnershipMarker: ModelProfileOwnershipMarker | undefined;
 
 	let compaction: CompactionEntry | null = null;
 	const injectedTtsrRulesSet = new Set<string>();
@@ -3030,6 +3044,10 @@ export function buildSessionContext(
 			} else if (configuredChain) {
 				configuredModelChains[configuredChain.role] = configuredChain;
 			}
+		} else if (entry.type === "custom" && entry.customType === MODEL_PROFILE_OWNERSHIP_ENTRY) {
+			const validated = validateModelProfileOwnershipMarker(entry.data);
+			if (!validated) throw new InvalidModelProfileOwnershipError();
+			modelProfileOwnershipMarker = validated;
 		} else if (entry.type === "service_tier_change") {
 			serviceTier = entry.serviceTier ?? undefined;
 		} else if (entry.type === "message" && entry.message.role === "assistant") {
@@ -3185,6 +3203,7 @@ export function buildSessionContext(
 		serviceTier,
 		models,
 		configuredModelChains,
+		...(modelProfileOwnershipMarker ? { modelProfileOwnershipMarker } : {}),
 
 		injectedTtsrRules,
 		injectedTtsrRuleRecords: injectedTtsrRuleRecordsArray,
@@ -3206,6 +3225,9 @@ function cloneSessionContext(context: SessionContext): SessionContext {
 		...context,
 		messages,
 		models: { ...context.models },
+		modelProfileOwnershipMarker: context.modelProfileOwnershipMarker
+			? { ...context.modelProfileOwnershipMarker }
+			: undefined,
 		configuredModelChains: Object.fromEntries(
 			Object.entries(context.configuredModelChains ?? {}).map(([role, chain]) => [
 				role,
@@ -6063,7 +6085,6 @@ async function truncateForPersistence(obj: unknown, blobStore: BlobStore, key?:
 					changed = true;
 					return [];
 				}
-
 				return [
 					(async () => {
 						if (
@@ -18385,6 +18406,42 @@ export class SessionManager {
 		return entry.id;
 	}
 
+	appendPreparedModelProfileOwnershipMarker(
+		prepared: PreparedNewSession,
+		marker: ModelProfileOwnershipMarker,
+	): string {
+		const validated = validateModelProfileOwnershipMarker(marker);
+		if (!validated) throw new InvalidModelProfileOwnershipError();
+		const stage = this.#getPreparedNewSessionStage(prepared);
+		const entry: CustomEntry<ModelProfileOwnershipMarker> = {
+			type: "custom",
+			customType: MODEL_PROFILE_OWNERSHIP_ENTRY,
+			data: validated,
+			id: this.#nextPreparedNewSessionEntryId(stage),
+			parentId: this.#preparedNewSessionLeafId(stage),
+			timestamp: new Date().toISOString(),
+		};
+		stage.fileEntries.push(entry);
+		return entry.id;
+	}
+
+	appendModelProfileOwnershipMarker(marker: ModelProfileOwnershipMarker): string {
+		const validated = validateModelProfileOwnershipMarker(marker);
+		if (!validated) throw new InvalidModelProfileOwnershipError();
+		return this.appendCustomEntry(MODEL_PROFILE_OWNERSHIP_ENTRY, validated);
+	}
+
+	getModelProfileOwnershipMarker(): ModelProfileOwnershipMarker | undefined {
+		let marker: ModelProfileOwnershipMarker | undefined;
+		for (const entry of this.getBranch()) {
+			if (entry.type !== "custom" || entry.customType !== MODEL_PROFILE_OWNERSHIP_ENTRY) continue;
+			const validated = validateModelProfileOwnershipMarker(entry.data);
+			if (!validated) throw new InvalidModelProfileOwnershipError();
+			marker = validated;
+		}
+		return marker;
+	}
+
 	/**
 	 * Append a root marker that starts a fresh active branch without changing the
 	 * session id or deleting earlier durable entries. Subsequent messages descend
@@ -18392,6 +18449,7 @@ export class SessionManager {
 	 * available for diagnostics/export.
 	 */
 	appendContextClearEntry(data?: Record<string, unknown>): string {
+		const ownershipMarker = this.getModelProfileOwnershipMarker();
 		const entry: CustomEntry = {
 			type: "custom",
 			customType: "context_clear",
@@ -18401,6 +18459,7 @@ export class SessionManager {
 			timestamp: new Date().toISOString(),
 		};
 		this.#appendEntry(entry);
+		if (ownershipMarker) this.appendModelProfileOwnershipMarker(ownershipMarker);
 		return entry.id;
 	}
 

package/src/setup/model-onboarding-guidance.ts

@@ -27,6 +27,32 @@ export function formatNoModelOnboardingError(): string {
 	return `No model selected.\n\n${formatModelOnboardingGuidance()}`;
 }
 
+/** Control-protocol code for a prompt refused because the session has no model. */
+export const MODEL_NOT_SELECTED_CODE = "model_not_selected";
+
+/**
+ * Fixed public text for {@link MODEL_NOT_SELECTED_CODE}. The onboarding
+ * guidance names providers, commands, environment variables and local setup
+ * paths, so it stays local-only; external clients get this constant instead.
+ */
+export const MODEL_NOT_SELECTED_PUBLIC_MESSAGE =
+	"No model is selected for this session. Select a model before submitting a prompt.";
+
+/**
+ * Missing-model prompt preflight failure. The message keeps the full local
+ * onboarding guidance for the TUI and in-process callers; the `code` is what
+ * lets the SDK control surface answer with a safe, known diagnostic instead of
+ * a generic internal error.
+ */
+export class NoModelSelectedError extends Error {
+	readonly code = MODEL_NOT_SELECTED_CODE;
+
+	constructor() {
+		super(formatNoModelOnboardingError());
+		this.name = "NoModelSelectedError";
+	}
+}
+
 export function formatNoCredentialOnboardingError(providerId: string): string {
 	const lines = [
 		`No credentials found for ${providerId}.`,