@sayknow-cli/coding-agent 0.3.5 → 0.3.7

package/src/runtime-mcp/manager.ts

@@ -147,6 +147,8 @@ export interface MCPDiscoverOptions {
 	filterExa?: boolean;
 	/** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
 	filterBrowser?: boolean;
+	/** Only connect servers with autoload !== false (default: false) */
+	autoloadOnly?: boolean;
 	/** Called when starting to connect to servers */
 	onConnecting?: (serverNames: string[]) => void;
 }
@@ -325,6 +327,7 @@ export class MCPManager {
 			enableProjectConfig: options?.enableProjectConfig,
 			filterExa: options?.filterExa,
 			filterBrowser: options?.filterBrowser,
+			autoloadOnly: options?.autoloadOnly,
 		});
 		const result = await this.connectServers(configs, sources, options?.onConnecting);
 		result.exaApiKeys = exaApiKeys;

package/src/runtime-mcp/types.ts

@@ -61,6 +61,12 @@ export interface MCPAuthConfig {
 interface MCPServerConfigBase {
 	/** Whether this server is enabled (default: true) */
 	enabled?: boolean;
+	/**
+	 * Whether to connect this server automatically at session startup (default: true).
+	 * When false the server stays configured-but-disconnected until connected
+	 * explicitly (e.g. `/mcp connect <name>`).
+	 */
+	autoload?: boolean;
 	/** Connection timeout in milliseconds (default: 30000) */
 	timeout?: number;
 	/** Authentication configuration (optional) */

package/src/sdk.ts

@@ -121,6 +121,7 @@ import { AgentOutputManager } from "./task/output-manager";
 import { parseThinkingLevel, resolveThinkingLevelForModel, toReasoningEffort } from "./thinking";
 import { collectDiscoverableTools, type DiscoverableTool } from "./tool-discovery/tool-index";
 import {
+	applyConfiguredSearchTimeout,
 	BashTool,
 	BUILTIN_TOOLS,
 	computeEssentialBuiltinNames,
@@ -129,10 +130,10 @@ import {
 	EditTool,
 	EvalTool,
 	FindTool,
+	getConfiguredSearchProviderPreference,
 	getSearchTools,
 	HIDDEN_TOOLS,
 	isConfigurableSearchProviderId,
-	isSearchProviderPreference,
 	type LspStartupServerInfo,
 	loadSshTool,
 	ReadTool,
@@ -142,7 +143,6 @@ import {
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
 	setSearchFallbackProviders,
-	setSearchHardTimeoutMs,
 	type Tool,
 	type ToolSession,
 	WebSearchTool,
@@ -257,7 +257,7 @@ export interface CreateAgentSessionOptions {
 	thinkingLevel?: ThinkingLevel;
 	/** Runtime substitution metadata for the initial model_change session event. */
 	modelSubstitution?: { requestedModel: Model; reason: string };
-	/** Models available for cycling (Ctrl+P in interactive mode) */
+	/** Models available for cycling (Alt+N in interactive mode) */
 	scopedModels?: ScopedModelSelection[];
 
 	/** System prompt blocks. Array replaces default, function receives default blocks and returns final blocks. */
@@ -934,20 +934,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	slashCommandsPromise.catch(() => {});
 
 	// Initialize provider preferences from settings
-	const webSearchProvider = settings.get("providers.webSearch");
-	if (typeof webSearchProvider === "string" && isSearchProviderPreference(webSearchProvider)) {
-		setPreferredSearchProvider(webSearchProvider);
-	}
+	const webSearchProvider = getConfiguredSearchProviderPreference(settings);
+	setPreferredSearchProvider(webSearchProvider);
 	const webSearchFallback = settings.get("web_search.fallback");
 	if (Array.isArray(webSearchFallback)) {
 		setSearchFallbackProviders(
 			webSearchFallback.filter(value => typeof value === "string" && isConfigurableSearchProviderId(value)),
 		);
 	}
-	const webSearchTimeout = settings.get("web_search.timeout");
-	if (typeof webSearchTimeout === "number" && Number.isFinite(webSearchTimeout) && webSearchTimeout > 0) {
-		setSearchHardTimeoutMs(webSearchTimeout * 1000);
-	}
+	applyConfiguredSearchTimeout(settings);
 
 	const imageProvider = settings.get("providers.image");
 	if (
@@ -1844,6 +1839,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				intentField,
 				mcpDiscoveryMode: false,
 				mcpDiscoveryServerSummaries: [],
+				toolDiscoveryActive: effectiveDiscoveryMode === "all",
+				discoverableTools: discoverableBuiltinTools
+					.map(tool => ({ name: tool.name, summary: tool.summary }))
+					.sort((a, b) => a.name.localeCompare(b.name)),
 				eagerTasks,
 				secretsEnabled,
 				workspaceTree: workspaceTreePromise,

package/src/session/agent-session.ts

@@ -260,6 +260,7 @@ import { type EditMode, resolveEditMode } from "../utils/edit-mode";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import { extractFileMentions, generateFileMentionMessages } from "../utils/file-mentions";
 import { buildNamedToolChoice, buildNamedToolChoiceResult } from "../utils/tool-choice";
+import { buildWorkflowIntentDiff, WORKFLOW_INTENT_DIFF_CUSTOM_TYPE } from "../workflow/workflow-intent-diff";
 import type { AuthStorage } from "./auth-storage";
 import type { ClientBridge, ClientBridgePermissionOption, ClientBridgePermissionOutcome } from "./client-bridge";
 import {
@@ -526,6 +527,15 @@ export interface SessionStats {
 type RetryFallbackChains = Record<string, string[]>;
 
 type RetryFallbackRevertPolicy = "never" | "cooldown-expiry";
+type RetryErrorClassification =
+	| "none"
+	| "overflow"
+	| "terminal"
+	| "usage_limit"
+	| "first_event_timeout"
+	| "transient"
+	| "local_unavailable"
+	| "unknown";
 
 interface RetryFallbackSelector {
 	raw: string;
@@ -563,6 +573,37 @@ function formatRetryFallbackBaseSelector(selector: RetryFallbackSelector): strin
 	return `${selector.provider}/${selector.id}`;
 }
 
+function isLocalModelEndpoint(model: Model | undefined): boolean {
+	if (!model) return false;
+	if (model.provider === "ollama" || model.provider === "lm-studio" || model.provider === "llama.cpp") {
+		return true;
+	}
+	try {
+		const hostname = new URL(model.baseUrl).hostname.toLowerCase();
+		if (
+			hostname === "localhost" ||
+			hostname === "0.0.0.0" ||
+			hostname === "::1" ||
+			hostname === "[::1]" ||
+			hostname.endsWith(".local")
+		) {
+			return true;
+		}
+		if (/^127\./.test(hostname) || /^10\./.test(hostname) || /^192\.168\./.test(hostname)) {
+			return true;
+		}
+		const private172 = /^172\.(\d{1,2})\./.exec(hostname);
+		if (private172) {
+			const secondOctet = Number(private172[1]);
+			return secondOctet >= 16 && secondOctet <= 31;
+		}
+	} catch {
+		// A malformed base URL is configuration, not availability. Keep it visible.
+		return false;
+	}
+	return false;
+}
+
 const IRC_REPLY_MAX_BYTES = 4096;
 
 /**
@@ -862,7 +903,7 @@ function extractPermissionLocations(
  *  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. */
-type QueuedDisplayEntry = { text: string; tag?: string };
+type QueuedDisplayEntry = { text: string; tag?: string; sequence: number };
 
 /** A custom message contributed at the before-agent-start point. */
 export type BeforeAgentStartInternalMessage = Pick<
@@ -916,6 +957,7 @@ export class AgentSession {
 	/** Tracks pending follow-up messages for UI display. Removed when delivered.
 	 *  See `#steeringMessages` for entry shape. */
 	#followUpMessages: QueuedDisplayEntry[] = [];
+	#queuedDisplaySequence = 0;
 	/** Messages queued to be included with the next user prompt as context ("asides"). */
 	#pendingNextTurnMessages: CustomMessage[] = [];
 	#scheduledHiddenNextTurnGeneration: number | undefined = undefined;
@@ -1585,6 +1627,14 @@ export class AgentSession {
 		this.#planCompactAbortPending = false;
 	}
 
+	#createQueuedDisplayEntry(text: string, tag?: string): QueuedDisplayEntry {
+		const entry: QueuedDisplayEntry = { text, sequence: ++this.#queuedDisplaySequence };
+		if (tag !== undefined) {
+			entry.tag = tag;
+		}
+		return entry;
+	}
+
 	/** 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
@@ -1598,7 +1648,7 @@ export class AgentSession {
 		const tag = `skc-cmd-${Date.now()}-${++this.#customDisplayTagCounter}`;
 		const displayText = text.trim();
 		if (!displayText) return tag;
-		const entry: QueuedDisplayEntry = { text: displayText, tag };
+		const entry = this.#createQueuedDisplayEntry(displayText, tag);
 		if (mode === "steer") {
 			this.#steeringMessages.push(entry);
 		} else {
@@ -4769,6 +4819,7 @@ export class AgentSession {
 
 		// Expand file-based prompt templates if requested
 		const expandedText = expandPromptTemplates ? expandPromptTemplate(text, [...this.#promptTemplates]) : text;
+		const workflowIntentDiff = options?.synthetic ? null : buildWorkflowIntentDiff(expandedText);
 
 		// If streaming, queue via steer() or followUp() based on option
 		if (this.isStreaming) {
@@ -4780,9 +4831,16 @@ export class AgentSession {
 			} else {
 				await this.#queueSteer(expandedText, options?.images);
 			}
+			if (workflowIntentDiff) {
+				this.sessionManager.appendCustomEntry(WORKFLOW_INTENT_DIFF_CUSTOM_TYPE, workflowIntentDiff);
+			}
 			return;
 		}
 
+		if (workflowIntentDiff) {
+			this.sessionManager.appendCustomEntry(WORKFLOW_INTENT_DIFF_CUSTOM_TYPE, workflowIntentDiff);
+		}
+
 		// Skip eager todo prelude when the user has already queued a directive
 		const hasPendingUserDirective = this.#toolChoiceQueue.inspect().includes("user-force");
 		const eagerTodoPrelude =
@@ -5236,7 +5294,7 @@ export class AgentSession {
 	 */
 	async #queueSteer(text: string, images?: ImageContent[]): Promise<void> {
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
-		this.#steeringMessages.push({ text: displayText });
+		this.#steeringMessages.push(this.#createQueuedDisplayEntry(displayText));
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
 		if (images && images.length > 0) {
 			content.push(...images);
@@ -5267,7 +5325,7 @@ export class AgentSession {
 	 */
 	async #queueFollowUp(text: string, images?: ImageContent[]): Promise<void> {
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
-		this.#followUpMessages.push({ text: displayText });
+		this.#followUpMessages.push(this.#createQueuedDisplayEntry(displayText));
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
 		if (images && images.length > 0) {
 			content.push(...images);
@@ -5643,18 +5701,21 @@ export class AgentSession {
 	 * record — no orphan state can outlive the queue entry.
 	 */
 	popLastQueuedMessage(): string | undefined {
-		// Pop from steering first (LIFO)
-		if (this.#steeringMessages.length > 0) {
+		const steeringEntry = this.#steeringMessages.at(-1);
+		const followUpEntry = this.#followUpMessages.at(-1);
+
+		if (steeringEntry && (!followUpEntry || steeringEntry.sequence > followUpEntry.sequence)) {
 			const entry = this.#steeringMessages.pop();
 			this.agent.popLastSteer();
 			return entry?.text;
 		}
-		// Then from follow-up
-		if (this.#followUpMessages.length > 0) {
+
+		if (followUpEntry) {
 			const entry = this.#followUpMessages.pop();
 			this.agent.popLastFollowUp();
 			return entry?.text;
 		}
+
 		return undefined;
 	}
 
@@ -8221,6 +8282,12 @@ export class AgentSession {
 	 */
 	#isRetryableError(message: AssistantMessage): boolean {
 		const classification = this.#classifyErrorForRetry(message);
+		if (classification === "local_unavailable") {
+			return this.#hasRetryFallbackCandidate({
+				currentSelector: this.model ? formatRetryFallbackSelector(this.model, this.thinkingLevel) : undefined,
+				requireNonLocal: true,
+			});
+		}
 		return (
 			classification === "usage_limit" ||
 			classification === "transient" ||
@@ -8260,6 +8327,12 @@ export class AgentSession {
 		return /timed?\s*out while waiting for the first event|timeout waiting for first/i.test(errorMessage);
 	}
 
+	#isLocalProviderAvailabilityErrorMessage(errorMessage: string): boolean {
+		return /connection.?refused|econnrefused|timed?\s*out|timeout|fetch failed|network.?error|socket hang up|terminated|service.?unavailable|server.?error|internal.?error|503|model_not_found|model not found|no such model|unknown model|model .*not.*(found|available|loaded)|not ready|not.?ready|warming|loading|currently loading|try again|out of memory|\boom\b|memory guard|insufficient memory|not enough memory|failed to allocate|kv.?cache|malformed (stream|streaming|sse)|invalid (stream|streaming|sse)|stream envelope error|unexpected end of (json|input)|unterminated json|no error details in response/i.test(
+			errorMessage,
+		);
+	}
+
 	/**
 	 * Whether a first-event timeout on the error's provider should fail closed —
 	 * i.e. retry a bounded number of times (capped at retry.maxRetries) and then
@@ -8303,13 +8376,14 @@ export class AgentSession {
 	 * -> usage_limit (rotation) -> first_event_timeout (bounded retry) ->
 	 * transient (retry) -> unknown (retry).
 	 */
-	#classifyErrorForRetry(
-		message: AssistantMessage,
-	): "none" | "overflow" | "terminal" | "usage_limit" | "first_event_timeout" | "transient" | "unknown" {
+	#classifyErrorForRetry(message: AssistantMessage): RetryErrorClassification {
 		if (message.stopReason !== "error" || !message.errorMessage) return "none";
 		const contextWindow = this.model?.contextWindow ?? 0;
 		if (isContextOverflow(message, contextWindow)) return "overflow";
 		const err = message.errorMessage;
+		if (isLocalModelEndpoint(this.model) && this.#isLocalProviderAvailabilityErrorMessage(err)) {
+			return "local_unavailable";
+		}
 		// Stream-envelope errors are only transient in the pre-message_start
 		// variant; any other envelope failure is structural and must surface.
 		if (/anthropic stream envelope error:/i.test(err)) {
@@ -8444,6 +8518,20 @@ export class AgentSession {
 		return chain;
 	}
 
+	#hasRetryFallbackCandidate(options: { currentSelector: string | undefined; requireNonLocal?: boolean }): boolean {
+		if (!options.currentSelector) return false;
+		const role = this.#activeRetryFallback?.role ?? this.#resolveRetryFallbackRole(options.currentSelector);
+		if (!role) return false;
+		for (const selector of this.#findRetryFallbackCandidates(role, options.currentSelector)) {
+			if (this.#isRetryFallbackSelectorSuppressed(selector)) continue;
+			const candidate = this.#modelRegistry.find(selector.provider, selector.id);
+			if (!candidate) continue;
+			if (options.requireNonLocal && isLocalModelEndpoint(candidate)) continue;
+			return true;
+		}
+		return false;
+	}
+
 	#findRetryFallbackCandidates(role: string, currentSelector: string): RetryFallbackSelector[] {
 		const chain = this.#getRetryFallbackEffectiveChain(role);
 		if (chain.length <= 1) return [];
@@ -8497,7 +8585,7 @@ export class AgentSession {
 		});
 	}
 
-	async #tryRetryModelFallback(currentSelector: string): Promise<boolean> {
+	async #tryRetryModelFallback(currentSelector: string, options?: { requireNonLocal?: boolean }): Promise<boolean> {
 		const role = this.#activeRetryFallback?.role ?? this.#resolveRetryFallbackRole(currentSelector);
 		if (!role) return false;
 
@@ -8505,6 +8593,7 @@ export class AgentSession {
 			if (this.#isRetryFallbackSelectorSuppressed(selector)) continue;
 			const candidate = this.#modelRegistry.find(selector.provider, selector.id);
 			if (!candidate) continue;
+			if (options?.requireNonLocal && isLocalModelEndpoint(candidate)) continue;
 			const apiKey = await this.#modelRegistry.getApiKey(candidate, this.sessionId);
 			if (!apiKey) continue;
 			await this.#applyRetryFallbackCandidate(role, selector, currentSelector);
@@ -8615,6 +8704,7 @@ export class AgentSession {
 		if (!retrySettings.enabled) return false;
 		const retryClassification = this.#classifyErrorForRetry(message);
 		const unboundedClass = retryClassification === "transient" || retryClassification === "unknown";
+		const localUnavailable = retryClassification === "local_unavailable";
 
 		const generation = this.#promptGeneration;
 		this.#retryAttempt++;
@@ -8668,7 +8758,7 @@ export class AgentSession {
 		const currentSelector = this.model ? formatRetryFallbackSelector(this.model, this.thinkingLevel) : undefined;
 		if (!switchedCredential && currentSelector) {
 			this.#noteRetryFallbackCooldown(currentSelector, parsedRetryAfterMs, errorMessage);
-			switchedModel = await this.#tryRetryModelFallback(currentSelector);
+			switchedModel = await this.#tryRetryModelFallback(currentSelector, { requireNonLocal: localUnavailable });
 			if (switchedModel) {
 				delayMs = 0;
 			} else if (parsedRetryAfterMs && parsedRetryAfterMs > delayMs) {

package/src/session/session-manager.ts

@@ -1461,9 +1461,25 @@ function materializeResidentEntrySync<T extends FileEntry | SessionEntry>(
 function materializeResidentEntriesSync<T extends FileEntry | SessionEntry>(
 	entries: T[],
 	stores: ResidentBlobStores,
+	missingPolicy: ResidentBlobMissingPolicy = "throw",
 ): T[] {
 	const cache = new Map<string, string>();
-	return entries.map(entry => materializeResidentEntrySync(entry, stores, cache));
+	return entries.map(entry => materializeResidentEntrySync(entry, stores, cache, missingPolicy));
+}
+
+function materializeResidentEntryForReadSync<T extends FileEntry | SessionEntry>(
+	entry: T,
+	stores: ResidentBlobStores,
+	cache: Map<string, string>,
+): T {
+	return materializeResidentEntrySync(entry, stores, cache, "placeholder");
+}
+
+function materializeResidentEntriesForReadSync<T extends FileEntry | SessionEntry>(
+	entries: T[],
+	stores: ResidentBlobStores,
+): T[] {
+	return materializeResidentEntriesSync(entries, stores, "placeholder");
 }
 
 function materializeResidentEntryForPersistenceSync<T extends FileEntry | SessionEntry>(
@@ -1520,12 +1536,24 @@ function cloneSessionEntry(entry: SessionEntry): SessionEntry {
 function materializeProviderVisibleEntrySync(entry: SessionEntry, stores: ResidentBlobStores): SessionEntry {
 	if (entry.type === "compaction") {
 		const cache = new Map<string, string>();
-		const summary = materializeResidentValueSync(entry.summary, stores, "summary", cache);
-		const shortSummary = materializeResidentValueSync(entry.shortSummary, stores, "shortSummary", cache);
+		const summary = materializeResidentValueSync(entry.summary, stores, "summary", cache, "placeholder");
+		const shortSummary = materializeResidentValueSync(
+			entry.shortSummary,
+			stores,
+			"shortSummary",
+			cache,
+			"placeholder",
+		);
 		const remote = entry.preserveData?.openaiRemoteCompaction;
 		const remoteRecord = isRecord(remote) ? remote : undefined;
 		const replacementHistory = remoteRecord
-			? materializeResidentValueSync(remoteRecord.replacementHistory, stores, "replacementHistory", cache)
+			? materializeResidentValueSync(
+					remoteRecord.replacementHistory,
+					stores,
+					"replacementHistory",
+					cache,
+					"placeholder",
+				)
 			: undefined;
 		const preserveData =
 			remoteRecord && replacementHistory !== undefined && replacementHistory !== remoteRecord.replacementHistory
@@ -1545,7 +1573,13 @@ function materializeProviderVisibleEntrySync(entry: SessionEntry, stores: Reside
 		};
 	}
 	if (entry.type === "branch_summary") {
-		const summary = materializeResidentValueSync(entry.summary, stores, "summary", new Map<string, string>());
+		const summary = materializeResidentValueSync(
+			entry.summary,
+			stores,
+			"summary",
+			new Map<string, string>(),
+			"placeholder",
+		);
 		return typeof summary === "string" ? { ...entry, summary } : { ...entry };
 	}
 	return cloneSessionEntry(entry);
@@ -2751,7 +2785,10 @@ export class SessionManager {
 	}
 
 	captureState(): SessionManagerStateSnapshot {
-		const materializedFileEntries = materializeResidentEntriesSync(this.#fileEntries, this.#residentBlobStores());
+		const materializedFileEntries = materializeResidentEntriesForReadSync(
+			this.#fileEntries,
+			this.#residentBlobStores(),
+		);
 		return {
 			sessionId: this.#sessionId,
 			sessionName: this.#sessionName,
@@ -2875,7 +2912,7 @@ export class SessionManager {
 
 		const oldSessionFile = this.#sessionFile;
 		const oldSessionId = this.#sessionId;
-		const materializedEntries = materializeResidentEntriesSync(this.#fileEntries, this.#residentBlobStores());
+		const materializedEntries = materializeResidentEntriesForReadSync(this.#fileEntries, this.#residentBlobStores());
 
 		// Close the current writer
 		await this.#closePersistWriter();
@@ -2947,7 +2984,10 @@ export class SessionManager {
 			hadSessionFile = this.storage.existsSync(oldSessionFile);
 			let movedSessionFile = false;
 			let movedArtifactDir = false;
-			const materializedEntries = materializeResidentEntriesSync(this.#fileEntries, this.#residentBlobStores());
+			const materializedEntries = materializeResidentEntriesForReadSync(
+				this.#fileEntries,
+				this.#residentBlobStores(),
+			);
 			const restoreResidentStateAfterFailure = (): void => {
 				this.#fileEntries = materializedEntries;
 				this.#resetResidentTextBlobStore();
@@ -4006,7 +4046,7 @@ export class SessionManager {
 	getLeafEntry(): SessionEntry | undefined {
 		if (!this.#leafId) return undefined;
 		const entry = this.#byId.get(this.#leafId);
-		return entry ? materializeResidentEntrySync(entry, this.#residentBlobStores(), new Map()) : undefined;
+		return entry ? materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()) : undefined;
 	}
 
 	/**
@@ -4176,7 +4216,7 @@ export class SessionManager {
 		const entry = this.#byId.get(id);
 		return entry
 			? rehydrateColdSpillEntry(
-					materializeResidentEntrySync(entry, this.#residentBlobStores(), new Map()),
+					materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()),
 					this.#blobStore,
 					this.#residentBlobStoresForColdRehydrate(),
 				)
@@ -4193,7 +4233,7 @@ export class SessionManager {
 			visited.add(current.id);
 			path.push(
 				rehydrateColdSpillEntry(
-					materializeResidentEntrySync(current, this.#residentBlobStores(), cache),
+					materializeResidentEntryForReadSync(current, this.#residentBlobStores(), cache),
 					this.#blobStore,
 					this.#residentBlobStoresForColdRehydrate(),
 				),
@@ -4233,7 +4273,7 @@ export class SessionManager {
 			.filter((entry): entry is SessionEntry => entry.type !== "session")
 			.map(entry =>
 				rehydrateColdSpillEntry(
-					materializeResidentEntrySync(entry, this.#residentBlobStores(), cache),
+					materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), cache),
 					this.#blobStore,
 					this.#residentBlobStoresForColdRehydrate(),
 				),
@@ -4244,7 +4284,7 @@ export class SessionManager {
 		this.#publicMaterializerCallCount++;
 		this.#getEntryMaterializerCallCount++;
 		const entry = this.#byId.get(id);
-		return entry ? materializeResidentEntrySync(entry, this.#residentBlobStores(), new Map()) : undefined;
+		return entry ? materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()) : undefined;
 	}
 
 	/**
@@ -4255,7 +4295,7 @@ export class SessionManager {
 		const children: SessionEntry[] = [];
 		for (const entry of this.#byId.values()) {
 			if (entry.parentId === parentId) {
-				children.push(materializeResidentEntrySync(entry, this.#residentBlobStores(), cache));
+				children.push(materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), cache));
 			}
 		}
 		return children;
@@ -4310,7 +4350,7 @@ export class SessionManager {
 		while (current) {
 			if (visited.has(current.id)) break;
 			visited.add(current.id);
-			path.push(materializeResidentEntrySync(current, this.#residentBlobStores(), cache));
+			path.push(materializeResidentEntryForReadSync(current, this.#residentBlobStores(), cache));
 			current = current.parentId ? this.#byId.get(current.parentId) : undefined;
 		}
 		path.reverse();
@@ -4375,7 +4415,7 @@ export class SessionManager {
 		}
 		if (entry.type !== "message" && entry.type !== "custom_message")
 			return materializeProviderVisibleEntrySync(entry, this.#residentBlobStores());
-		const materialized = materializeResidentEntrySync(entry, this.#residentBlobStores(), new Map());
+		const materialized = materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map());
 		const rehydrated = rehydrateColdSpillEntry(
 			materialized,
 			this.#blobStore,
@@ -4434,7 +4474,7 @@ export class SessionManager {
 		const resolvedTextBlobCache = new Map<string, string>();
 		const materializedEntries = this.#fileEntries
 			.filter((e): e is SessionEntry => e.type !== "session")
-			.map(entry => materializeResidentEntrySync(entry, this.#residentBlobStores(), resolvedTextBlobCache));
+			.map(entry => materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), resolvedTextBlobCache));
 		this.#materializedEntriesCache = materializedEntries;
 		this.#materializedEntriesRevision = this.#entryRevision;
 		return materializedEntries;
@@ -4591,7 +4631,7 @@ export class SessionManager {
 
 		// Filter out LabelEntry from path - we'll recreate them from the resolved map
 		const pathWithoutLabels = branchPath.filter(e => e.type !== "label");
-		const materializedPathWithoutLabels = materializeResidentEntriesSync(
+		const materializedPathWithoutLabels = materializeResidentEntriesForReadSync(
 			pathWithoutLabels,
 			this.#residentBlobStores(),
 		);

package/src/skc-runtime/launch-tmux.ts

@@ -6,6 +6,7 @@ import type { Args } from "../cli/args";
 import { tmuxRuntimeSessionPath } from "./session-layout";
 import { SKC_COORDINATOR_SESSION_ID_ENV, SKC_COORDINATOR_SESSION_STATE_FILE_ENV } from "./session-state-sidecar";
 import {
+	buildSkcTmuxExactSessionTarget,
 	buildSkcTmuxProfileCommands,
 	buildSkcTmuxSessionName,
 	buildSkcTmuxSessionSlug,
@@ -21,6 +22,7 @@ import {
 import { findSkcTmuxSessionByName, findSkcTmuxSessionByScope, type SkcTmuxSessionStatus } from "./tmux-sessions";
 
 export {
+	buildSkcTmuxExactSessionTarget,
 	buildSkcTmuxProfileCommands,
 	SKC_DEFAULT_TMUX_SESSION,
 	SKC_TMUX_COMMAND_ENV,
@@ -201,12 +203,24 @@ function buildWindowsPowerShellInnerCommand(context: CommandResolutionContext, r
 	const envLines = Object.entries({ [SKC_TMUX_LAUNCHED_ENV]: "1", ...(context.extraEnv ?? {}) }).map(
 		([key, value]) => `$env:${key} = ${powershellQuote(value)}`,
 	);
-	const invocation = ["&", ...command.map(powershellQuote), ...stripRootTmuxFlag(rawArgs).map(powershellQuote)].join(
-		" ",
-	);
+	// The inner `&` invocation must wrap the resolved skc command in a
+	// script-block so the trailing PowerShell exec-policy flags from the
+	// outer invocation are not forwarded into the bun / node / .bat
+	// binary the skc command resolves to. Without the wrapping, the flags
+	// reach the runtime binary and cause an immediate failure that closes
+	// the psmux pane before the skc --tmux attach can land.
+	const resolvedCommand = command.map(powershellQuote).join(" ");
+	const innerArgs = stripRootTmuxFlag(rawArgs).map(powershellQuote).join(" ");
+	const invocation = `& { ${resolvedCommand} ${innerArgs} }`;
 	const exitLine = "if ($null -ne $LASTEXITCODE) { exit $LASTEXITCODE } else { exit 1 }";
 	const script = [...envLines, invocation, exitLine].join("\n");
-	const encodedCommand = Buffer.from(script, "utf16le").toString("base64");
+	// PowerShell -EncodedCommand requires a UTF-16LE BOM (0xFF 0xFE) at the
+	// start of the decoded buffer; without it pwsh may misinterpret the
+	// leading bytes and reject the script with a parse error, which would
+	// kill the psmux pane before the skc --tmux attach could land.
+	const bom = Buffer.from([0xff, 0xfe]);
+	const body = Buffer.from(script, "utf16le");
+	const encodedCommand = Buffer.concat([bom, body]).toString("base64");
 	return `pwsh -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ${encodedCommand}`;
 }
 
@@ -395,7 +409,11 @@ function readCurrentBranch(cwd: string): string | null {
 }
 
 function cleanupCreatedTmuxSession(plan: TmuxLaunchPlan, spawnSync: TmuxSpawnSync, options: TmuxSpawnOptions): void {
-	spawnSync(plan.tmuxCommand, ["kill-session", "-t", `=${plan.sessionName}`], options);
+	spawnSync(
+		plan.tmuxCommand,
+		["kill-session", "-t", buildSkcTmuxExactSessionTarget(plan.sessionName, { env: options.env })],
+		options,
+	);
 }
 function isTmuxAttachDisconnectError(result: TmuxSpawnResult): boolean {
 	if (result.signalCode === "SIGHUP") return true;
@@ -499,7 +517,11 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 	};
 
 	if (plan.attachSessionName) {
-		const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", `=${plan.attachSessionName}`], options);
+		const attached = spawnSync(
+			plan.tmuxCommand,
+			["attach-session", "-t", buildSkcTmuxExactSessionTarget(plan.attachSessionName, { env })],
+			options,
+		);
 		if (attached.exitCode === 0) return true;
 	}
 
@@ -510,7 +532,7 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 			buildSkcTmuxWindowTitle(plan.project ?? plan.cwd, plan.branch),
 			spawnSync,
 			options,
-			`=${plan.sessionName}`,
+			buildSkcTmuxExactSessionTarget(plan.sessionName, { env }),
 		);
 
 		const profile = applySkcTmuxProfile({
@@ -535,7 +557,11 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 		}
 	}
 	if (created.exitCode !== 0) return false;
-	const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", `=${plan.sessionName}`], options);
+	const attached = spawnSync(
+		plan.tmuxCommand,
+		["attach-session", "-t", buildSkcTmuxExactSessionTarget(plan.sessionName, { env })],
+		options,
+	);
 	if (attached.exitCode === 0) return true;
 	if (isTmuxAttachDisconnectError(attached)) {
 		(context.diagnosticWriter ?? safeStderrWrite)(formatTmuxLaunchDiagnostic("attach disconnected", attached.stderr));