@sayknow-cli/coding-agent 0.2.7 → 0.3.1

package/src/notifications/topic-registry.ts

@@ -0,0 +1,133 @@
+/**
+ * Per-session forum-topic registry for the threaded session surface.
+ *
+ * Each SKC session owns exactly one Telegram forum topic in the paired private
+ * DM. The topic is created once (via `createForumTopic`) and REUSED on resume,
+ * keyed by session id, so a resumed session streams back into its existing
+ * thread/history. The registry also tracks whether the one-time identity header
+ * has already been pinned, so it is sent exactly once per topic even across
+ * reconnects.
+ *
+ * State is a plain serialisable map persisted beside the daemon state files;
+ * topic creation is injected so this module is pure and unit-testable without a
+ * live Bot API.
+ */
+
+/** Persisted record for one session's topic. */
+export interface TopicRecord {
+	/** Telegram forum topic id (message_thread_id). */
+	topicId: string;
+	/** Whether the one-time identity header has been sent/pinned. */
+	identitySent: boolean;
+	/** Creation timestamp (ms epoch). */
+	createdAt: number;
+	/** Last applied topic title (for rename detection). */
+	name?: string;
+}
+
+/** Serialisable shape persisted to disk. */
+export interface TopicRegistryState {
+	/** sessionId -> record. */
+	topics: Record<string, TopicRecord>;
+}
+
+export function emptyTopicRegistryState(): TopicRegistryState {
+	return { topics: {} };
+}
+
+/**
+ * In-memory registry over a serialisable state. Topic creation is injected via
+ * `getOrCreateTopic`'s `create` callback (the daemon supplies a real
+ * `createForumTopic` call); reuse-on-resume is automatic when a record exists.
+ */
+export class TopicRegistry {
+	private readonly topics: Map<string, TopicRecord>;
+	/** Maps topicId -> sessionId for fast inbound routing. */
+	private readonly byTopic = new Map<string, string>();
+	/** In-flight create promises, keyed by session, to dedupe concurrent creates. */
+	private readonly inflight = new Map<string, Promise<TopicRecord>>();
+
+	constructor(state: TopicRegistryState = emptyTopicRegistryState()) {
+		this.topics = new Map(Object.entries(state.topics ?? {}));
+		for (const [sessionId, record] of this.topics) this.byTopic.set(record.topicId, sessionId);
+	}
+
+	/** Merge a serialized state into this registry, preserving all persisted fields. */
+	load(state: TopicRegistryState): void {
+		for (const [sessionId, record] of Object.entries(state.topics ?? {})) {
+			this.topics.set(sessionId, record);
+			this.byTopic.set(record.topicId, sessionId);
+		}
+	}
+
+	/** Resolve the owning session for a topic id (for fail-closed inbound routing). */
+	sessionForTopic(topicId: string): string | undefined {
+		return this.byTopic.get(topicId);
+	}
+
+	/** The existing topic record for a session, if any. */
+	get(sessionId: string): TopicRecord | undefined {
+		return this.topics.get(sessionId);
+	}
+
+	/**
+	 * Return the existing topic for `sessionId`, or create one via `create`
+	 * (called only on first use). Reuse-on-resume: an existing record is
+	 * returned without invoking `create`.
+	 */
+	async getOrCreateTopic(
+		sessionId: string,
+		create: () => Promise<string>,
+		now: () => number = Date.now,
+	): Promise<TopicRecord> {
+		const existing = this.topics.get(sessionId);
+		if (existing) return existing;
+		// Concurrency guard: many session frames (identity/idle/turn/ask) can race
+		// to first-use the same session. Without this, each call passes the
+		// `existing` check before `create()` resolves and creates a DUPLICATE
+		// forum topic. Share a single in-flight create per session id.
+		const pending = this.inflight.get(sessionId);
+		if (pending) return pending;
+		const promise = (async () => {
+			const topicId = await create();
+			const record: TopicRecord = { topicId, identitySent: false, createdAt: now() };
+			this.topics.set(sessionId, record);
+			this.byTopic.set(topicId, sessionId);
+			return record;
+		})();
+		this.inflight.set(sessionId, promise);
+		try {
+			return await promise;
+		} finally {
+			this.inflight.delete(sessionId);
+		}
+	}
+
+	/** Mark the identity header as sent for a session. Idempotent. */
+	markIdentitySent(sessionId: string): void {
+		const record = this.topics.get(sessionId);
+		if (record) record.identitySent = true;
+	}
+
+	/** Whether the identity header still needs sending for this session. */
+	needsIdentity(sessionId: string): boolean {
+		const record = this.topics.get(sessionId);
+		return record ? !record.identitySent : true;
+	}
+
+	/**
+	 * Record the topic's applied title. Returns `true` when it changed (so the
+	 * caller should `editForumTopic`), `false` when already current or unknown.
+	 */
+	applyName(sessionId: string, name: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record || record.name === name) return false;
+		record.name = name;
+		return true;
+	}
+
+	/** Serialise for atomic persistence beside the daemon state. */
+	serialize(): TopicRegistryState {
+		return { topics: Object.fromEntries(this.topics) };
+	}
+}

package/src/rlm/index.ts

@@ -240,8 +240,27 @@ async function writeRlmMetadata(input: {
 	}
 }
 
+/**
+ * RLM artifacts are scoped under a SKC session directory and resolving their
+ * paths is a *write* (it must pick a concrete session). When `skc rlm` runs
+ * standalone — no parent agent, no `SKC_SESSION_ID` in the environment — there is
+ * no session to resolve and `resolveSkcSessionForWrite` throws
+ * `missing_for_write`. Establish a dedicated SKC session id in that case and pin
+ * it into the environment so artifact-path resolution, the per-session activity
+ * marker, and the child agent's workflow state all share one writable session.
+ *
+ * Returns the resolved (existing or freshly generated) SKC session id.
+ */
+export function ensureRlmSkcSessionId(): string {
+	const existing = resolveSessionIdFromSources({ envSessionId: process.env.SKC_SESSION_ID })?.skcSessionId;
+	if (existing) return existing;
+	const generated = `rlm-${generateRlmSessionId()}`;
+	process.env.SKC_SESSION_ID = generated;
+	return generated;
+}
 export async function runRlmCommand(argv: string[]): Promise<void> {
 	const cwd = getProjectDir();
+	ensureRlmSkcSessionId();
 	const { dataPath, resumeSessionId, minSuccessfulRuns, rest } = extractRlmFlags(argv);
 	const dataContext = await loadRlmDataContext(cwd, dataPath);
 

package/src/sdk.ts

@@ -81,6 +81,12 @@ import type { HindsightSessionState } from "./hindsight/state";
 import { LocalProtocolHandler, type LocalProtocolOptions } from "./internal-urls";
 import { LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "./lsp/startup-events";
 import { resolveMemoryBackend } from "./memory-backend";
+import { createNotificationsExtension } from "./notifications";
+import {
+	getNotificationConfig,
+	type NotificationConfig,
+	shouldRegisterNotificationsExtension,
+} from "./notifications/config";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
 import { AgentRegistry, MAIN_AGENT_ID } from "./registry/agent-registry";
 import { MCPManager } from "./runtime-mcp";
@@ -1240,6 +1246,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			getPlanModeState: () => session?.getPlanModeState(),
 			getGoalModeState: () => session?.getGoalModeState(),
 			getWorkflowGateEmitter: () => session?.getWorkflowGateEmitter(),
+			getAskAnswerSource: () => session?.getAskAnswerSource(),
 			getGoalRuntime: () => session?.goalRuntime,
 			getClientBridge: () => session?.clientBridge,
 			getCompactContext: () => session.formatCompactContext(),
@@ -1388,6 +1395,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		if (customTools.length > 0) {
 			inlineExtensions.push(createCustomToolsExtension(customTools));
 		}
+		let notificationCfg: NotificationConfig | undefined;
+		try {
+			notificationCfg = getNotificationConfig(Settings.instance);
+		} catch {
+			notificationCfg = undefined;
+		}
+		if (shouldRegisterNotificationsExtension({ env: process.env, cfg: notificationCfg })) {
+			inlineExtensions.push(createNotificationsExtension);
+		}
 
 		// Extension/module discovery is quarantined; retain only the private
 		// runtime needed for bundled product extensions, explicitly supplied SDK

package/src/session/agent-session.ts

@@ -238,8 +238,9 @@ import {
 	type DiscoverableTool,
 	type DiscoverableToolSearchIndex,
 } from "../tool-discovery/tool-index";
-import type { ToolSession } from "../tools";
+import type { AskAnswerSource, ToolSession } from "../tools";
 import { AskTool } from "../tools/ask";
+import { getAskAnswerSource as getAskAnswerSourceFromRegistry } from "../tools/ask-answer-registry";
 import { assertEditableFile } from "../tools/auto-generated-guard";
 import { releaseTabsForOwner } from "../tools/browser/tab-supervisor";
 import type { CheckpointState } from "../tools/checkpoint";
@@ -285,6 +286,8 @@ import { ToolChoiceQueue } from "./tool-choice-queue";
 import { YieldQueue } from "./yield-queue";
 
 /** Session-specific events that extend the core AgentEvent */
+export type AutoCompactionContinuationSkipReason = "auto_continue_disabled_non_resumable_tail";
+
 export type AgentSessionEvent =
 	| AgentEvent
 	| { type: "auto_compaction_start"; reason: "threshold" | "overflow" | "idle"; action: "context-full" | "handoff" }
@@ -297,6 +300,7 @@ export type AgentSessionEvent =
 			errorMessage?: string;
 			/** True when compaction was skipped for a benign reason (no model, no candidates, nothing to compact). */
 			skipped?: boolean;
+			continuationSkipReason?: AutoCompactionContinuationSkipReason;
 	  }
 	| {
 			type: "auto_retry_start";
@@ -313,6 +317,7 @@ export type AgentSessionEvent =
 	| { type: "todo_reminder"; todos: TodoItem[]; attempt: number; maxAttempts: number }
 	| { type: "todo_auto_clear" }
 	| { type: "irc_message"; message: CustomMessage }
+	| { type: "subagent_steer_message"; message: CustomMessage }
 	| { type: "notice"; level: "info" | "warning" | "error"; message: string; source?: string }
 	| { type: "thinking_level_changed"; thinkingLevel: ThinkingLevel | undefined }
 	| { type: "goal_updated"; goal: Goal | null; state?: GoalModeState };
@@ -1867,7 +1872,6 @@ export class AgentSession {
 										this.#resolveTtsrResume();
 										return;
 									}
-									this.#ttsrAbortPending = false;
 									this.#perToolTtsrInjections.clear();
 									const ttsrSettings = this.#ttsrManager?.getSettings();
 									if (ttsrSettings?.contextMode === "discard" && targetAssistantIndex !== -1) {
@@ -1896,11 +1900,22 @@ export class AgentSession {
 										);
 										this.#markTtsrInjected(details.rules);
 									}
-									try {
-										await this.agent.continue();
-									} catch {
-										this.#resolveTtsrResume();
-									}
+									await this.#scheduleAgentContinue({
+										delayMs: 0,
+										generation,
+										shouldContinue: () => {
+											this.#ttsrAbortPending = false;
+											return true;
+										},
+										onSkip: () => {
+											this.#ttsrAbortPending = false;
+											this.#resolveTtsrResume();
+										},
+										onError: () => {
+											this.#ttsrAbortPending = false;
+											this.#resolveTtsrResume();
+										},
+									});
 								},
 								{ delayMs: 50 },
 							);
@@ -2212,7 +2227,7 @@ export class AgentSession {
 	#schedulePostPromptTask(
 		task: (signal: AbortSignal) => Promise<void>,
 		options?: { delayMs?: number; generation?: number; onSkip?: () => void },
-	): void {
+	): Promise<void> {
 		const delayMs = options?.delayMs ?? 0;
 		const signal = this.#postPromptTasksAbortController.signal;
 		const scheduled = (async () => {
@@ -2234,18 +2249,20 @@ export class AgentSession {
 			await task(signal);
 		})();
 		this.#trackPostPromptTask(scheduled);
+		return scheduled;
 	}
 
 	#scheduleAgentContinue(options?: {
 		delayMs?: number;
 		generation?: number;
+		skipCompactionCheck?: boolean;
 		shouldContinue?: () => boolean;
 		onSkip?: (reason: "generation_changed" | "aborted_signal" | "queue_drained") => void;
 		onError?: (error: unknown) => void;
-	}): void {
+	}): Promise<void> {
 		const scheduledGeneration = options?.generation;
 		const signal = this.#postPromptTasksAbortController.signal;
-		this.#schedulePostPromptTask(
+		return this.#schedulePostPromptTask(
 			async () => {
 				if (signal.aborted) {
 					options?.onSkip?.("aborted_signal");
@@ -2261,6 +2278,9 @@ export class AgentSession {
 				}
 				try {
 					await this.#maybeRestoreRetryFallbackPrimary();
+					if (!options?.skipCompactionCheck) {
+						await this.#checkEstimatedContextBeforePrompt();
+					}
 					await this.agent.continue();
 				} catch (error) {
 					logger.warn("agent.continue failed after scheduling", {
@@ -2305,6 +2325,34 @@ export class AgentSession {
 		}
 	}
 
+	#detectOverflowRetryContinuationSkip(): AutoCompactionContinuationSkipReason | undefined {
+		this.#stripOverflowFailedTurnForRetry();
+		if (this.#isResumableAgentTail()) return undefined;
+		const compactionSettings = this.settings.getGroup("compaction");
+		return compactionSettings.autoContinue === false ? "auto_continue_disabled_non_resumable_tail" : undefined;
+	}
+
+	#scheduleOverflowRetryContinuation(generation: number): void {
+		this.#stripOverflowFailedTurnForRetry();
+		if (this.#isResumableAgentTail()) {
+			this.#scheduleAgentContinue({
+				delayMs: 100,
+				generation,
+				onSkip: reason => this.#logCompactionContinuationSkipped("overflow_retry", reason),
+				onError: error => this.#logCompactionContinuationError("overflow_retry", error),
+			});
+			return;
+		}
+
+		const compactionSettings = this.settings.getGroup("compaction");
+		if (compactionSettings.autoContinue !== false) {
+			this.#scheduleAutoContinuePrompt(generation);
+			return;
+		}
+
+		this.#logCompactionContinuationSkipped("overflow_retry", "auto_continue_disabled_non_resumable_tail");
+	}
+
 	#scheduleAutoContinuePrompt(generation: number): void {
 		const continuePrompt = async () => {
 			await this.#promptWithMessage(
@@ -3050,6 +3098,7 @@ export class AgentSession {
 				willRetry: event.willRetry,
 				errorMessage: event.errorMessage,
 				skipped: event.skipped,
+				continuationSkipReason: event.continuationSkipReason,
 			});
 		} else if (event.type === "auto_retry_start") {
 			await this.#extensionRunner.emit({
@@ -4385,6 +4434,10 @@ export class AgentSession {
 		return this.#workflowGateEmitter;
 	}
 
+	getAskAnswerSource(): AskAnswerSource | undefined {
+		return getAskAnswerSourceFromRegistry(this.sessionId);
+	}
+
 	setWorkflowGateEmitter(emitter: WorkflowGateEmitter | undefined): void {
 		this.#workflowGateEmitter = emitter;
 		if (emitter) {
@@ -5453,6 +5506,16 @@ export class AgentSession {
 			return;
 		}
 
+		// No explicit delivery mode: only a live stream makes prompt() throw
+		// AgentBusyError, so queue the message as steering while streaming.
+		// Compaction is intentionally NOT diverted here: prompt() handles an
+		// in-flight compaction internally, and #queueSteer would otherwise park
+		// the message in the steering queue with no turn to consume it.
+		if (this.isStreaming) {
+			await this.#queueSteer(text, images);
+			return;
+		}
+
 		// Use prompt() with expandPromptTemplates: false to skip command handling and template expansion
 		await this.prompt(text, {
 			expandPromptTemplates: false,
@@ -5856,12 +5919,46 @@ export class AgentSession {
 		return this.#activeModelProfile;
 	}
 
+	/**
+	 * The model selector ("provider/id") that resume restores as the session
+	 * default — the latest session-log `model_change` with role="default".
+	 * Model-profile activation snapshots this before mutating the session so a
+	 * failed-activation rollback can restore the pre-activation resume default
+	 * instead of promoting a transient runtime model to the resume default.
+	 */
+	getSessionDefaultModelSelector(): string | undefined {
+		return this.sessionManager.buildSessionContext().models.default;
+	}
+
+	/**
+	 * Re-assert the session resume default ("provider/id") in the session log
+	 * WITHOUT touching the live runtime model. Appends a `model_change` with
+	 * role="default"; never writes to global settings (apply-for-this-session
+	 * semantics). Used by model-profile activation rollback to neutralize the
+	 * profile main model the failed activation already recorded as the default.
+	 */
+	recordResumeDefaultModel(selector: string): void {
+		this.sessionManager.appendModelChange(selector, "default");
+	}
+
 	/**
 	 * Set model temporarily (for this session only).
 	 * Validates API key, saves to session log but NOT to settings.
+	 *
+	 * The change is recorded in the session log as `role: "temporary"` by
+	 * default, which means it is NOT restored as the session default on resume —
+	 * transient retry/fallback/context-promotion/plan switches must not clobber
+	 * the user's explicit pick (issue #849). Model-profile activation passes
+	 * `persistAsSessionDefault: true` so the profile's main model becomes the
+	 * session default and survives resume, while still not being written to
+	 * global settings (new sessions keep the global default).
 	 * @throws Error if no API key available for the model
 	 */
-	async setModelTemporary(model: Model, thinkingLevel?: ThinkingLevel): Promise<void> {
+	async setModelTemporary(
+		model: Model,
+		thinkingLevel?: ThinkingLevel,
+		options?: { persistAsSessionDefault?: boolean },
+	): Promise<void> {
 		const previousEditMode = this.#resolveActiveEditMode();
 		const apiKey = await this.#modelRegistry.getApiKey(model, this.sessionId);
 		if (!apiKey) {
@@ -5870,7 +5967,10 @@ export class AgentSession {
 
 		this.#clearActiveRetryFallback();
 		this.#setModelWithProviderSessionReset(model);
-		this.sessionManager.appendModelChange(`${model.provider}/${model.id}`, "temporary");
+		this.sessionManager.appendModelChange(
+			`${model.provider}/${model.id}`,
+			options?.persistAsSessionDefault ? "default" : "temporary",
+		);
 		this.settings.getStorage()?.recordModelUsage(`${model.provider}/${model.id}`);
 
 		// Apply explicit thinking level if given; otherwise prefer the model's
@@ -6669,6 +6769,8 @@ export class AgentSession {
 			const compactionSettings = this.settings.getGroup("compaction");
 			if (compactionSettings.enabled && compactionSettings.strategy !== "off") {
 				await this.#runAutoCompaction("overflow", true);
+			} else {
+				this.#scheduleOverflowRetryContinuation(generation);
 			}
 			return;
 		}
@@ -6679,17 +6781,19 @@ export class AgentSession {
 		// Skip if this was an error (non-overflow errors don't have usage data)
 		if (assistantMessage.stopReason === "error") return;
 		let contextTokens = calculateContextTokens(assistantMessage.usage);
-		const maxOutputTokens = this.model?.maxTokens ?? 0;
+		// Model maxTokens is a capability ceiling, not a per-turn reservation.
+		// Auto maintenance should track actual context fullness.
+		const autoCompactionOutputReserveTokens = 0;
 		// Cache-epoch invariant: pruning rewrites already-sent toolResult history,
 		// which breaks the provider prompt-cache prefix mid-epoch. Only prune at a
 		// sanctioned maintenance boundary, i.e. when the un-pruned context already
 		// crosses the compaction threshold. Pruning may then avert full compaction.
-		if (!shouldCompact(contextTokens, contextWindow, compactionSettings, maxOutputTokens)) return;
+		if (!shouldCompact(contextTokens, contextWindow, compactionSettings, autoCompactionOutputReserveTokens)) return;
 		const pruneResult = await this.#pruneToolOutputs();
 		if (pruneResult) {
 			contextTokens = Math.max(0, contextTokens - pruneResult.tokensSaved);
 		}
-		if (shouldCompact(contextTokens, contextWindow, compactionSettings, maxOutputTokens)) {
+		if (shouldCompact(contextTokens, contextWindow, compactionSettings, autoCompactionOutputReserveTokens)) {
 			// Try promotion first — if a larger model is available, switch instead of compacting
 			const promoted = await this.#tryContextPromotion(assistantMessage);
 			if (!promoted) {
@@ -6767,14 +6871,16 @@ export class AgentSession {
 		if (!compactionSettings.enabled || compactionSettings.strategy === "off") return;
 
 		let contextTokens = this.#estimateContextTokensForCompaction(pendingMessages).tokens;
-		const maxOutputTokens = model.maxTokens ?? 0;
-		if (!shouldCompact(contextTokens, contextWindow, compactionSettings, maxOutputTokens)) return;
+		// Model maxTokens is a capability ceiling, not a per-turn reservation.
+		// Auto maintenance should track actual context fullness.
+		const autoCompactionOutputReserveTokens = 0;
+		if (!shouldCompact(contextTokens, contextWindow, compactionSettings, autoCompactionOutputReserveTokens)) return;
 
 		const pruneResult = await this.#pruneToolOutputs();
 		if (pruneResult) {
 			contextTokens = Math.max(0, contextTokens - pruneResult.tokensSaved);
 		}
-		if (shouldCompact(contextTokens, contextWindow, compactionSettings, maxOutputTokens)) {
+		if (shouldCompact(contextTokens, contextWindow, compactionSettings, autoCompactionOutputReserveTokens)) {
 			await this.#runAutoCompaction("threshold", false, false, {
 				continueAfterMaintenance: false,
 				deferHandoffMaintenance: false,
@@ -7677,32 +7783,18 @@ export class AgentSession {
 
 			const preparation = prepareCompaction(pathEntries, compactionSettings);
 			if (!preparation) {
+				const continuationSkipReason = willRetry ? this.#detectOverflowRetryContinuationSkip() : undefined;
 				await this.#emitSessionEvent({
 					type: "auto_compaction_end",
 					action,
 					result: undefined,
 					aborted: false,
-					willRetry: false,
+					willRetry: willRetry && !continuationSkipReason,
 					skipped: true,
+					continuationSkipReason,
 				});
 				if (willRetry) {
-					this.#stripOverflowFailedTurnForRetry();
-					if (this.#isResumableAgentTail()) {
-						this.#scheduleAgentContinue({
-							delayMs: 100,
-							generation,
-							onSkip: skipReason => this.#logCompactionContinuationSkipped("overflow_retry", skipReason),
-							onError: error => this.#logCompactionContinuationError("overflow_retry", error),
-						});
-					} else {
-						const tail = this.agent.state.messages.at(-1) as AssistantMessage | undefined;
-						logger.warn("Auto-compaction continuation skipped", {
-							source: "overflow_retry",
-							reason: "not_resumable_tail",
-							role: tail?.role,
-							stopReason: tail?.stopReason,
-						});
-					}
+					this.#scheduleOverflowRetryContinuation(generation);
 				} else if (continueAfterMaintenance && reason !== "idle" && this.agent.hasQueuedMessages()) {
 					this.#scheduleAgentContinue({
 						delayMs: 100,
@@ -7913,26 +8005,18 @@ export class AgentSession {
 				details,
 				preserveData,
 			};
-			await this.#emitSessionEvent({ type: "auto_compaction_end", action, result, aborted: false, willRetry });
+			const continuationSkipReason = willRetry ? this.#detectOverflowRetryContinuationSkip() : undefined;
+			await this.#emitSessionEvent({
+				type: "auto_compaction_end",
+				action,
+				result,
+				aborted: false,
+				willRetry: willRetry && !continuationSkipReason,
+				continuationSkipReason,
+			});
 
 			if (willRetry) {
-				this.#stripOverflowFailedTurnForRetry();
-				if (!this.#isResumableAgentTail()) {
-					const tail = this.agent.state.messages.at(-1) as AssistantMessage | undefined;
-					logger.warn("Auto-compaction continuation skipped", {
-						source: "overflow_retry",
-						reason: "not_resumable_tail",
-						role: tail?.role,
-						stopReason: tail?.stopReason,
-					});
-				} else {
-					this.#scheduleAgentContinue({
-						delayMs: 100,
-						generation,
-						onSkip: reason => this.#logCompactionContinuationSkipped("overflow_retry", reason),
-						onError: error => this.#logCompactionContinuationError("overflow_retry", error),
-					});
-				}
+				this.#scheduleOverflowRetryContinuation(generation);
 			} else if (continueAfterMaintenance && reason !== "idle" && this.agent.hasQueuedMessages()) {
 				// Auto-compaction can complete while follow-up/steering/custom messages are waiting.
 				// Kick the loop so queued messages are actually delivered.
@@ -9089,6 +9173,63 @@ export class AgentSession {
 		void this.#emitSessionEvent({ type: "irc_message", message: record });
 	}
 
+	emitSubagentSteerObservation(args: { from: string; to: string; body: string; timestamp?: number }): void {
+		const timestamp = args.timestamp ?? Date.now();
+		const observationId = crypto.randomUUID();
+		const message: CustomMessage = {
+			role: "custom",
+			customType: "subagent:steer",
+			content: `[Steer \`${args.from}\` ⇨ \`${args.to}\` (queued)]\n\n${args.body}`,
+			display: true,
+			details: { observationId, from: args.from, to: args.to, body: args.body, state: "queued" },
+			attribution: "agent",
+			timestamp,
+		};
+		void this.#emitSessionEvent({ type: "subagent_steer_message", message });
+		this.#forwardSubagentSteerRelayToMain({
+			from: args.from,
+			to: args.to,
+			body: args.body,
+			observationId,
+			timestamp,
+		});
+	}
+
+	#forwardSubagentSteerRelayToMain(args: {
+		from: string;
+		to: string;
+		body: string;
+		observationId: string;
+		timestamp: number;
+	}): void {
+		const registry = this.#agentRegistry;
+		if (!registry) return;
+		if (this.#agentId === MAIN_AGENT_ID) return;
+		const mainRef = registry.get(MAIN_AGENT_ID);
+		const mainSession = mainRef?.session;
+		if (!mainSession || mainSession === this) return;
+		const record: CustomMessage = {
+			role: "custom",
+			customType: "subagent:steer:relay",
+			content: `[Steer \`${args.from}\` ⇨ \`${args.to}\` (queued)]\n\n${args.body}`,
+			display: true,
+			details: {
+				observationId: args.observationId,
+				from: args.from,
+				to: args.to,
+				body: args.body,
+				state: "queued",
+			},
+			attribution: "agent",
+			timestamp: args.timestamp,
+		};
+		mainSession.emitSubagentSteerRelayObservation(record);
+	}
+
+	emitSubagentSteerRelayObservation(record: CustomMessage): void {
+		void this.#emitSessionEvent({ type: "subagent_steer_message", message: record });
+	}
+
 	/**
 	 * Run a single ephemeral side-channel turn against this session's current
 	 * model + system prompt + history.  No tools are used; the side request

package/src/session/auth-storage.ts

@@ -7,6 +7,9 @@ export type {
 	ApiKeyCredential,
 	AuthCredential,
 	AuthCredentialEntry,
+	AuthCredentialIfAbsentReason,
+	AuthCredentialIfAbsentResult,
+	AuthCredentialIfAbsentSnapshotResult,
 	AuthCredentialStore,
 	AuthStorageData,
 	AuthStorageOptions,