@gajae-code/coding-agent 0.8.0 → 0.8.2

package/src/prompts/tools/computer.md

@@ -6,7 +6,7 @@
 
 - Disabled means disabled: when the tool is disabled (`computer.alwaysOn=false` with `computer.enabled` unset/false) or the platform is unsupported, every action including `screenshot` fails with `COMPUTER_DISABLED` and captures nothing.
 - Callable only on Apple Silicon macOS (`arm64` darwin); available by default there, with `computer.alwaysOn=false` as the off-switch and `computer.enabled=true` as the manual enable path.
-- Native execution remains supervisor-gated. If the stop/suspend supervisor is unavailable, stale, suspended, permissioned off, display-stale, or cancelled, the action fails closed with a `COMPUTER_*` code.
+- Native execution remains supervisor-gated. If the stop/suspend supervisor is unavailable, stale, suspended, permissioned off, display-stale, or cancelled, the action fails closed with a `COMPUTER_*` code. Coordinate actions carry the latest known screenshot display epoch when one is available so display-topology changes fail with `COMPUTER_DISPLAY_STALE`.
 - Respect the user's stop/suspend request immediately. Do not loop desktop actions after a stop/suspend/error.
 - The user can stop or suspend the session at any time with the configured kill-switch hotkey (default `Control+Option+Command+Escape`). If you see `COMPUTER_CANCELLED` or `COMPUTER_SUPERVISOR_NOT_LIVE`, stop and wait for the user.
 
@@ -14,7 +14,7 @@
 
 Coordinates are screenshot pixels, not CSS pixels and not normalized fractions. Use the latest successful `screenshot` dimensions and origin/scale metadata as the coordinate frame. Do not guess coordinates outside the screenshot bounds.
 
-When you send a sequence of actions in one `batch` call, pointer coordinates in later steps are validated against the most recent screenshot from that batch. If a coordinate is out of bounds, the batch stops and reports `COMPUTER_COORD_INVALID`. Always capture a fresh screenshot before acting if the display may have changed.
+For stale-display protection to apply, derive pointer coordinates from a successful screenshot in the same tool session; a screenshot-first `batch` is preferred because later coordinate steps are validated against that screenshot and carry its display epoch into native execution. If a coordinate is out of bounds, the batch stops and reports `COMPUTER_COORD_INVALID`. Always capture a fresh screenshot before acting if the display may have changed.
 
 ## Actions
 

package/src/runtime-api-key.ts

@@ -0,0 +1,16 @@
+export interface RuntimeApiKeyTarget {
+	setRuntimeApiKey(provider: string, apiKey: string): void;
+}
+
+export interface RuntimeApiKeyModel {
+	provider: string;
+}
+
+export function applyCliRuntimeApiKeyOverride(
+	target: RuntimeApiKeyTarget,
+	apiKey: string | undefined,
+	model: RuntimeApiKeyModel | undefined,
+): void {
+	if (!apiKey || !model) return;
+	target.setRuntimeApiKey(model.provider, apiKey);
+}

package/src/sdk.ts

@@ -1214,8 +1214,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 	const agentRegistry = options.agentRegistry ?? AgentRegistry.global();
 	const resolvedAgentId = options.agentId ?? options.parentTaskPrefix ?? MAIN_AGENT_ID;
-	const resolvedAgentDisplayName =
-		options.agentDisplayName ?? ((options.taskDepth ?? 0) > 0 || options.parentTaskPrefix ? "sub" : "main");
+	const isSubSession = taskDepth > 0 || Boolean(options.parentTaskPrefix) || Boolean(options.currentAgentType);
+	const resolvedAgentDisplayName = options.agentDisplayName ?? (isSubSession ? "sub" : "main");
 	const evalKernelOwnerId = `agent-session:${Snowflake.next()}`;
 
 	try {
@@ -1520,12 +1520,20 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		}
 		let notificationCfg: NotificationConfig | undefined;
 		try {
-			notificationCfg = getNotificationConfig(Settings.instance);
+			notificationCfg = getNotificationConfig(settings);
 		} catch {
 			notificationCfg = undefined;
 		}
-		if (shouldRegisterNotificationsExtension({ env: process.env, cfg: notificationCfg })) {
-			inlineExtensions.push(createNotificationsExtension);
+		if (
+			shouldRegisterNotificationsExtension({
+				env: process.env,
+				cfg: notificationCfg,
+				taskDepth,
+				parentTaskPrefix: options.parentTaskPrefix,
+				currentAgentType: options.currentAgentType,
+			})
+		) {
+			inlineExtensions.push(api => createNotificationsExtension(api, { settings }));
 		}
 
 		// Extension/module discovery is quarantined; retain only the private
@@ -1632,6 +1640,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				cwd,
 				sessionManager,
 				modelRegistry,
+				{
+					kind: isSubSession ? "sub" : "main",
+					taskDepth,
+					...(options.parentTaskPrefix ? { parentTaskPrefix: options.parentTaskPrefix } : {}),
+					...(options.currentAgentType ? { currentAgentType: options.currentAgentType } : {}),
+				},
 			);
 		}
 
@@ -1924,7 +1938,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		agentRegistry.register({
 			id: resolvedAgentId,
 			displayName: resolvedAgentDisplayName,
-			kind: (options.taskDepth ?? 0) > 0 || options.parentTaskPrefix ? "sub" : "main",
+			kind: isSubSession ? "sub" : "main",
 			parentId: options.parentTaskPrefix,
 			session: null,
 			sessionFile: sessionManager.getSessionFile() ?? null,

package/src/session/agent-session.ts

@@ -905,9 +905,17 @@ function extractPermissionLocations(
  *  `tag` is set only by `enqueueCustomMessageDisplay` (used for skill-prompt
  *  custom messages queued during streaming) and is matched by the custom-role
  *  `message_start` dequeue branch; user-message pushes leave it undefined and
- *  rely on the existing text-equality match. `sequence` preserves cross-queue
- *  insertion order for one-at-a-time dequeue/edit UX. */
+ *  rely on the existing text-equality match. `sequence` gives each queued chip a
+ *  stable edit id while the display arrays preserve delivery order. */
 type QueuedDisplayEntry = { text: string; tag?: string; sequence: number };
+export type QueuedMessageEditMode = "steer" | "followUp";
+
+export interface QueuedMessageEditEntry {
+	id: string;
+	text: string;
+	mode: QueuedMessageEditMode;
+	label: string;
+}
 
 /** A custom message contributed at the before-agent-start point. */
 export type BeforeAgentStartInternalMessage = Pick<
@@ -1134,17 +1142,19 @@ export class AgentSession {
 	#streamingEditFileCache = new Map<string, string>();
 	#promptInFlightCount = 0;
 	// Wire-level agent_end emission deferred until #promptInFlightCount drops to 0.
-	// Internal extension hooks and post-emit work (auto-retry, auto-compaction, todo
-	// checks in #handleAgentEvent) still fire on the original schedule — only the
-	// `#emit(event)` that reaches external subscribers (rpc-mode stdout, ACP bridge,
-	// Cursor exec, TUI listeners) is held back. Without this, a client that resumes
-	// on `agent_end` can fire its next `prompt` before #promptWithMessage's finally
-	// has decremented #promptInFlightCount, hitting AgentBusyError. Flushed from
-	// both #endInFlight (normal) and #resetInFlight (abort).
+	// Local subscribers and extension hooks both receive the deferred event from
+	// #flushPendingAgentEnd(), preserving the local-before-extension ordering used
+	// by #emitSessionEvent while still preventing external clients from resuming
+	// before #promptWithMessage's finally decrements #promptInFlightCount. Without
+	// this, a client that resumes on `agent_end` can fire its next `prompt` while
+	// the session still reports busy and hit AgentBusyError. Flushed from both
+	// #endInFlight (normal) and #resetInFlight (abort).
 	#pendingAgentEndEmit: AgentSessionEvent | undefined;
 	#obfuscator: SecretObfuscator | undefined;
 	#checkpointState: CheckpointState | undefined = undefined;
 	#providerReplaySourceCache = new WeakMap<AgentMessage, ProviderReplaySourceCacheEntry>();
+	#lastOversizedAutoMaintenanceAttemptSignature: string | undefined = undefined;
+
 	#pendingRewindReport: string | undefined = undefined;
 	#lastSuccessfulYieldToolCallId: string | undefined = undefined;
 	#promptGeneration = 0;
@@ -1223,6 +1233,7 @@ export class AgentSession {
 		if (!pending) return;
 		this.#pendingAgentEndEmit = undefined;
 		this.#emit(pending);
+		void this.#queueExtensionEvent(pending);
 	}
 
 	constructor(config: AgentSessionConfig) {
@@ -1533,10 +1544,9 @@ export class AgentSession {
 				recordSkip("unsupported-role");
 				return undefined;
 			}
-			const cloned = cloneJsonValueForForkSeed(message) as Message;
-			if ("providerPayload" in cloned) {
-				delete (cloned as { providerPayload?: unknown }).providerPayload;
-			}
+			const messageWithoutProviderPayload = { ...message } as Message & { providerPayload?: unknown };
+			delete messageWithoutProviderPayload.providerPayload;
+			const cloned = cloneJsonValueForForkSeed(messageWithoutProviderPayload) as Message;
 			if (Array.isArray(cloned.content)) {
 				const sanitizedContent: TextContent[] = [];
 				for (const block of cloned.content) {
@@ -1548,6 +1558,10 @@ export class AgentSession {
 						recordSkip(`unsupported-content-${block.type}`);
 					}
 				}
+				if (sanitizedContent.length === 0) {
+					recordSkip("empty-content");
+					return undefined;
+				}
 				return { ...cloned, content: sanitizedContent } as Message;
 			}
 			return cloned;
@@ -1561,9 +1575,14 @@ export class AgentSession {
 			const sanitized = sanitizeMessage(providerMessages[i]!);
 			if (!sanitized) continue;
 			const messageTokens = estimateMessageTokensHeuristic(sanitized);
+			// Stop at the first message that overflows the token budget. The loop walks
+			// newest→oldest, so `break` keeps the seed a CONTIGUOUS run of the most recent
+			// messages. `continue` here would skip the oversized recent message and scavenge
+			// smaller OLDER ones, yielding a non-contiguous seed that misrepresents the
+			// conversation and violates the recency contract of the receipt/last-turn/bounded modes.
 			if (maxTokens > 0 && approximateTokens + messageTokens > maxTokens) {
 				recordSkip("token-limit");
-				continue;
+				break;
 			}
 			selected.unshift(sanitized);
 			approximateTokens += messageTokens;
@@ -1645,6 +1664,9 @@ export class AgentSession {
 		return entry;
 	}
 
+	#queuedMessageEditId(mode: QueuedMessageEditMode, sequence: number): string {
+		return `${mode}:${sequence}`;
+	}
 	/** Register a compact display string for a custom message that the caller is
 	 *  about to dispatch via `promptCustomMessage` / `sendCustomMessage`.
 	 *  Returns a stable tag the caller MUST embed in
@@ -1752,17 +1774,19 @@ export class AgentSession {
 	}
 
 	async #emitSessionEvent(event: AgentSessionEvent): Promise<void> {
-		await persistCoordinatorRuntimeStateFromEvent(event, {
-			sessionId: this.sessionId,
-			cwd: this.sessionManager.getCwd(),
-			sessionFile: this.sessionManager.getSessionFile(),
-		});
+		const persistRuntimeState = () =>
+			persistCoordinatorRuntimeStateFromEvent(event, {
+				sessionId: this.sessionId,
+				cwd: this.sessionManager.getCwd(),
+				sessionFile: this.sessionManager.getSessionFile(),
+			});
+
 		if (event.type === "message_update") {
 			this.#emit(event);
+			void persistRuntimeState();
 			void this.#queueExtensionEvent(event);
 			return;
 		}
-		await this.#emitExtensionEvent(event);
 		// Hold the wire-level agent_end until in-flight prompts unwind. Subscribers
 		// (rpc-mode, ACP, Cursor) treat agent_end as the "session is idle" signal;
 		// emitting while #promptInFlightCount > 0 lets a client fire its next
@@ -1772,10 +1796,18 @@ export class AgentSession {
 		// supersedes the pending one, which is what subscribers want — they only
 		// care about the final settle.
 		if (event.type === "agent_end" && this.#promptInFlightCount > 0) {
+			void persistRuntimeState();
 			this.#pendingAgentEndEmit = event;
 			return;
 		}
+
+		// Local subscribers are part of the AgentSession control path: retryNow(),
+		// auto-continuation gates, goal reminders, and tests all observe these events
+		// synchronously. Coordinator sidecar writes and extension hooks are secondary
+		// sinks, so they must not delay or suppress local delivery.
 		this.#emit(event);
+		void persistRuntimeState();
+		await this.#emitExtensionEvent(event);
 	}
 
 	// Track last assistant message for auto-compaction check
@@ -3227,11 +3259,15 @@ export class AgentSession {
 				maxAttempts: event.maxAttempts,
 			});
 		} else if (event.type === "goal_updated") {
-			await this.#extensionRunner.emit({
-				type: "goal_updated",
-				goal: event.goal,
-				state: event.state,
-			});
+			try {
+				await this.#extensionRunner.emit({
+					type: "goal_updated",
+					goal: event.goal,
+					state: event.state,
+				});
+			} catch (error) {
+				logger.warn("Goal updated extension hook failed", { error: String(error) });
+			}
 		}
 	}
 
@@ -5715,6 +5751,72 @@ export class AgentSession {
 		};
 	}
 
+	getQueuedMessageEntries(): QueuedMessageEditEntry[] {
+		const entries: QueuedMessageEditEntry[] = [];
+		for (const entry of this.#steeringMessages) {
+			entries.push({
+				id: this.#queuedMessageEditId("steer", entry.sequence),
+				text: entry.text,
+				mode: "steer",
+				label: "Steer",
+			});
+		}
+		for (const entry of this.#followUpMessages) {
+			entries.push({
+				id: this.#queuedMessageEditId("followUp", entry.sequence),
+				text: entry.text,
+				mode: "followUp",
+				label: "Queued",
+			});
+		}
+		return entries;
+	}
+
+	removeQueuedMessageForEditing(id: string): string | undefined {
+		const [mode, sequenceText] = id.split(":");
+		if ((mode !== "steer" && mode !== "followUp") || sequenceText === undefined) return undefined;
+		const sequence = Number(sequenceText);
+		if (!Number.isInteger(sequence)) return undefined;
+
+		const queue = mode === "steer" ? this.#steeringMessages : this.#followUpMessages;
+		const index = queue.findIndex(entry => entry.sequence === sequence);
+		if (index === -1) return undefined;
+
+		const [entry] = queue.splice(index, 1);
+		if (mode === "steer") {
+			this.agent.removeSteerAt(index);
+		} else {
+			this.agent.removeFollowUpAt(index);
+		}
+		return entry?.text;
+	}
+
+	moveQueuedMessageForEditing(id: string, direction: "up" | "down"): boolean {
+		const [mode, sequenceText] = id.split(":");
+		if ((mode !== "steer" && mode !== "followUp") || sequenceText === undefined) return false;
+		const sequence = Number(sequenceText);
+		if (!Number.isInteger(sequence)) return false;
+
+		const queue = mode === "steer" ? this.#steeringMessages : this.#followUpMessages;
+		const fromIndex = queue.findIndex(entry => entry.sequence === sequence);
+		if (fromIndex === -1) return false;
+		const toIndex = direction === "up" ? fromIndex - 1 : fromIndex + 1;
+		const agentMoved =
+			mode === "steer" ? this.agent.moveSteer(fromIndex, toIndex) : this.agent.moveFollowUp(fromIndex, toIndex);
+		if (!agentMoved) return false;
+		return this.#moveQueuedDisplayEntry(queue, fromIndex, toIndex);
+	}
+
+	#moveQueuedDisplayEntry(queue: QueuedDisplayEntry[], fromIndex: number, toIndex: number): boolean {
+		if (fromIndex < 0 || fromIndex >= queue.length) return false;
+		if (toIndex < 0 || toIndex >= queue.length) return false;
+		if (fromIndex === toIndex) return true;
+		const [entry] = queue.splice(fromIndex, 1);
+		if (!entry) return false;
+		queue.splice(toIndex, 0, entry);
+		return true;
+	}
+
 	/**
 	 * Pop the newest queued message across steering and follow-up queues.
 	 * Used by dequeue keybinding to restore messages to editor one at a time.
@@ -5726,15 +5828,11 @@ export class AgentSession {
 		const followUpEntry = this.#followUpMessages.at(-1);
 
 		if (steeringEntry && (!followUpEntry || steeringEntry.sequence > followUpEntry.sequence)) {
-			const entry = this.#steeringMessages.pop();
-			this.agent.popLastSteer();
-			return entry?.text;
+			return this.removeQueuedMessageForEditing(this.#queuedMessageEditId("steer", steeringEntry.sequence));
 		}
 
 		if (followUpEntry) {
-			const entry = this.#followUpMessages.pop();
-			this.agent.popLastFollowUp();
-			return entry?.text;
+			return this.removeQueuedMessageForEditing(this.#queuedMessageEditId("followUp", followUpEntry.sequence));
 		}
 
 		return undefined;
@@ -7672,6 +7770,59 @@ export class AgentSession {
 		return false;
 	}
 
+	#buildAutoMaintenanceAttemptSignature(
+		action: "context-full" | "handoff",
+		preparation: CompactionPreparation,
+		hookPrompt: string | undefined,
+		hookContext: string[] | undefined,
+		candidateModels: readonly Model[],
+	): string {
+		const source = JSON.stringify({
+			action,
+			model: this.model ? this.#getModelKey(this.model) : undefined,
+			candidates: candidateModels.map(model => this.#getModelKey(model)),
+			isSplitTurn: preparation.isSplitTurn,
+			previousSummary: preparation.previousSummary,
+			previousPreserveData: preparation.previousPreserveData,
+			hookPrompt,
+			hookContext,
+			messagesToSummarize: preparation.messagesToSummarize.map(message =>
+				this.#normalizeSessionMessageForProviderReplay(message),
+			),
+			turnPrefixMessages: preparation.turnPrefixMessages.map(message =>
+				this.#normalizeSessionMessageForProviderReplay(message),
+			),
+			recentMessages: preparation.recentMessages.map(message =>
+				this.#normalizeSessionMessageForProviderReplay(message),
+			),
+		});
+		return `${this.#hashProviderReplaySource(source).toString(16)}:${source.length}`;
+	}
+
+	#isOversizedMaintenanceError(errorMessage: string): boolean {
+		return isContextOverflow(
+			{
+				role: "assistant",
+				content: [],
+				api: this.model?.api ?? "anthropic-messages",
+				provider: this.model?.provider ?? "unknown",
+				model: this.model?.id ?? "unknown",
+				stopReason: "error",
+				errorMessage,
+				usage: {
+					input: 0,
+					output: 0,
+					cacheRead: 0,
+					cacheWrite: 0,
+					totalTokens: 0,
+					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+				},
+				timestamp: Date.now(),
+			} as AssistantMessage,
+			this.model?.contextWindow,
+		);
+	}
+
 	#getModelKey(model: Model): string {
 		return `${model.provider}/${model.id}`;
 	}
@@ -7942,6 +8093,7 @@ export class AgentSession {
 		const autoCompactionAbortController = new AbortController();
 		this.#autoCompactionAbortController = autoCompactionAbortController;
 		const autoCompactionSignal = autoCompactionAbortController.signal;
+		let maintenanceAttemptSignature: string | undefined;
 
 		try {
 			if (compactionSettings.strategy === "handoff" && reason !== "overflow") {
@@ -8089,6 +8241,26 @@ export class AgentSession {
 				preserveData = compactionPrep.preserveData;
 			} else {
 				const candidates = this.#getCompactionModelCandidates(availableModels);
+				maintenanceAttemptSignature = this.#buildAutoMaintenanceAttemptSignature(
+					action,
+					preparation,
+					compactionPrep.hookPrompt,
+					compactionPrep.hookContext,
+					candidates,
+				);
+				if (this.#lastOversizedAutoMaintenanceAttemptSignature === maintenanceAttemptSignature) {
+					await this.#emitSessionEvent({
+						type: "auto_compaction_end",
+						action,
+						result: undefined,
+						aborted: false,
+						willRetry: false,
+						skipped: true,
+						errorMessage:
+							"Auto-compaction skipped: previous unchanged maintenance request exceeded the model context window; change or reduce the conversation before retrying maintenance.",
+					});
+					return;
+				}
 				const retrySettings = this.settings.getGroup("retry");
 				const telemetry = resolveTelemetry(this.agent.telemetry, this.sessionId);
 				let compactResult: CompactionResult | undefined;
@@ -8221,6 +8393,8 @@ export class AgentSession {
 				details,
 				preserveData,
 			};
+			this.#lastOversizedAutoMaintenanceAttemptSignature = undefined;
+
 			const continuationSkipReason = willRetry ? this.#detectOverflowRetryContinuationSkip() : undefined;
 			await this.#emitSessionEvent({
 				type: "auto_compaction_end",
@@ -8258,6 +8432,9 @@ export class AgentSession {
 				return;
 			}
 			const errorMessage = error instanceof Error ? error.message : "compaction failed";
+			if (maintenanceAttemptSignature && this.#isOversizedMaintenanceError(errorMessage)) {
+				this.#lastOversizedAutoMaintenanceAttemptSignature = maintenanceAttemptSignature;
+			}
 			await this.#emitSessionEvent({
 				type: "auto_compaction_end",
 				action,
@@ -8382,6 +8559,16 @@ export class AgentSession {
 		);
 	}
 
+	#isRefusalErrorMessage(errorMessage: string): boolean {
+		// Provider safety-refusal stops. Matches the engine-generated Anthropic
+		// labels from packages/ai ("Refusal (<category>): …", "Refusal (no
+		// details provided)", "Content flagged by safety filters") plus generic
+		// usage-policy refusal copy.
+		return /^refusal(\s*\(|:|$)|content flagged by safety filters|blocked under .{0,40}usage policy/i.test(
+			errorMessage,
+		);
+	}
+
 	#extractExplicitHttpStatusFromErrorMessage(errorMessage: string): number | undefined {
 		// Parse only explicit HTTP/status wording. Do not treat generic
 		// `error: 400` as an HTTP status because rate-limit copy can say
@@ -8402,6 +8589,13 @@ export class AgentSession {
 		const contextWindow = this.model?.contextWindow ?? 0;
 		if (isContextOverflow(message, contextWindow)) return "overflow";
 		const err = message.errorMessage;
+		// Provider safety refusals (e.g. Anthropic stop_reason "refusal" /
+		// "sensitive") are deterministic for the submitted context: replaying
+		// the identical conversation re-triggers the identical refusal, so an
+		// auto-retry loop can never succeed and only re-bills the full context
+		// on every attempt (#1655). Surface immediately instead of joining the
+		// unbounded "unknown" retry class.
+		if (this.#isRefusalErrorMessage(err)) return "terminal";
 		if (isLocalModelEndpoint(this.model) && this.#isLocalProviderAvailabilityErrorMessage(err)) {
 			return "local_unavailable";
 		}

package/src/session/agent-storage.ts

@@ -420,6 +420,10 @@ FROM model_usage_legacy
 		this.#authStore.setCache(key, value, expiresAtSec);
 	}
 
+	deleteCachePrefix(prefix: string): void {
+		this.#authStore.deleteCachePrefix?.(prefix);
+	}
+
 	/**
 	 * Deletes expired cache entries. Call periodically for cleanup.
 	 */

package/src/session/session-manager.ts

@@ -1308,6 +1308,45 @@ function isImageBlock(value: unknown): value is { type: "image"; data: string; m
 	);
 }
 
+function stripUndefinedPlainObjectFields(value: unknown, path = "entry"): unknown {
+	if (value === undefined) return undefined;
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) {
+		let changed = false;
+		const result: unknown[] = new Array(value.length);
+		for (let index = 0; index < value.length; index++) {
+			const item = value[index];
+			if (item === undefined) {
+				throw new Error(`Session entry contains undefined array item at ${path}[${index}]`);
+			}
+			const next = stripUndefinedPlainObjectFields(item, `${path}[${index}]`);
+			if (next !== item) changed = true;
+			result[index] = next;
+		}
+		return changed ? result : value;
+	}
+
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return value;
+
+	let changed = false;
+	const entries: Array<readonly [string, unknown]> = [];
+	for (const [key, item] of Object.entries(value)) {
+		if (item === undefined) {
+			changed = true;
+			continue;
+		}
+		const next = stripUndefinedPlainObjectFields(item, `${path}.${key}`);
+		if (next !== item) changed = true;
+		entries.push([key, next]);
+	}
+	return changed ? Object.fromEntries(entries) : value;
+}
+
+function normalizeSessionEntryForStorage(entry: SessionEntry): SessionEntry {
+	return stripUndefinedPlainObjectFields(entry) as SessionEntry;
+}
+
 const RESIDENT_EXTERNALIZE_STRING_EXCLUDED_KEYS = new Set([
 	"id",
 	"type",
@@ -2254,10 +2293,12 @@ class NdjsonFileWriter {
 	}
 }
 
+const DEFAULT_WELCOME_RECENT_SESSION_LIMIT = 20;
+
 /** Get recent sessions for display in welcome screen */
 export async function getRecentSessions(
 	sessionDir: string,
-	limit = 3,
+	limit = DEFAULT_WELCOME_RECENT_SESSION_LIMIT,
 	storage: SessionStorage = new FileSessionStorage(),
 ): Promise<RecentSessionInfo[]> {
 	const sessions = await getSortedSessions(sessionDir, storage);
@@ -3734,7 +3775,8 @@ export class SessionManager {
 	}
 
 	#appendEntry(entry: SessionEntry): void {
-		const residentEntry = prepareEntryForResidentSync(entry, this.#residentBlobStores()) as SessionEntry;
+		const normalizedEntry = normalizeSessionEntryForStorage(entry);
+		const residentEntry = prepareEntryForResidentSync(normalizedEntry, this.#residentBlobStores()) as SessionEntry;
 		this.#fileEntries.push(residentEntry);
 		this.#byId.set(residentEntry.id, residentEntry);
 		this.#leafId = residentEntry.id;