@gajae-code/coding-agent 0.9.6 → 0.10.0

package/src/modes/shared/agent-wire/unattended-session.ts

@@ -15,6 +15,7 @@
  * RPC server can route `negotiate_unattended` + `workflow_gate_response` here.
  */
 import type { Model } from "@gajae-code/ai";
+import type { AskSelectedAckOutcome } from "../../../tools";
 import type {
 	RpcCommand,
 	RpcUnattendedAccepted,
@@ -30,7 +31,53 @@ import {
 	type UnattendedAuditEvent,
 	UnattendedRunController,
 } from "./unattended-run-controller";
-import { type GateStore, MemoryGateStore, type OpenGateInput, WorkflowGateBroker } from "./workflow-gate-broker";
+import {
+	type GateStore,
+	MemoryGateStore,
+	type OpenGateInput,
+	type PersistedAckPolicy,
+	type PersistedGate,
+	type PersistedSemanticDisposition,
+	WorkflowGateBroker,
+} from "./workflow-gate-broker";
+
+export interface WorkflowGateTerminalController {
+	completeGateInteractions(gateId: string): void | Promise<void>;
+	cancelGateInteractions(gateId: string, reason: string): void | Promise<void>;
+}
+
+export interface WorkflowGateTerminalEvent {
+	gateId: string;
+	kind: "accepted" | "cancelled";
+	origin?: "rpc" | "bridge" | "other" | "telegram_notification";
+	reason?: string;
+}
+
+export interface NotificationGateResolutionOptions {
+	interactionActionId: string;
+	replyReceiptId: string;
+	answerJson: string;
+	idempotencyKey?: string;
+	requestSelectedAck(input: {
+		replyReceiptId: string;
+		actionId: string;
+		commitKey: string;
+		daemonDeadlineAt: number;
+		hostTimeoutMs: number;
+	}): Promise<AskSelectedAckOutcome>;
+	resolveClaim(): void;
+	closeClaimInvalid(reason: string): void;
+}
+
+export interface AskSelectedAckRecoveryParticipant {
+	requestRecoveredAskSelectedAck(input: {
+		sessionId: string;
+		actionId: string;
+		commitKey: string;
+		deadlineAt: number;
+		hostTimeoutMs: number;
+	}): Promise<AskSelectedAckOutcome>;
+}
 
 /**
  * RPC commands that perform agent/tool work and therefore consume one unit of the
@@ -66,7 +113,13 @@ export interface WorkflowGateEmitter {
 	 */
 	onGateEmitted?(listener: (gate: RpcWorkflowGate) => void): () => void;
 	resolveGate?(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution>;
+	resolveGateFromNotification?(
+		response: RpcWorkflowGateResponse,
+		options: NotificationGateResolutionOptions,
+	): Promise<RpcWorkflowGateResolution>;
+	registerGateTerminalController?(controller: WorkflowGateTerminalController): () => void;
 	listPendingGates?(): RpcWorkflowGate[];
+	setAckRecoveryParticipant?(participant: AskSelectedAckRecoveryParticipant | null): void;
 }
 
 export interface UnattendedSessionOptions {
@@ -91,6 +144,12 @@ export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane,
 	readonly #pending = new Map<string, { resolve: (answer: unknown) => void; reject: (err: Error) => void }>();
 	readonly #earlyAnswers = new Map<string, unknown>();
 	readonly #gateListeners = new Set<(gate: RpcWorkflowGate) => void>();
+	#terminalController: WorkflowGateTerminalController | undefined;
+	#brokerReady = false;
+	#recoveryPromise: Promise<void> | undefined;
+	#disposed = false;
+	#recoveryParticipant: AskSelectedAckRecoveryParticipant | undefined;
+	#participantReady = Promise.withResolvers<void>();
 
 	constructor(private readonly opts: UnattendedSessionOptions) {}
 
@@ -108,6 +167,38 @@ export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane,
 		return this.#controller;
 	}
 
+	registerGateTerminalController(controller: WorkflowGateTerminalController): () => void {
+		if (this.#terminalController && this.#terminalController !== controller) {
+			throw new Error("a workflow gate terminal controller is already registered");
+		}
+		this.#terminalController = controller;
+		return () => {
+			if (this.#terminalController === controller) this.#terminalController = undefined;
+		};
+	}
+
+	setAckRecoveryParticipant(participant: AskSelectedAckRecoveryParticipant | null): void {
+		this.#recoveryParticipant = participant ?? undefined;
+		if (participant) this.#participantReady.resolve();
+		void this.startRecoveryOnce();
+	}
+
+	async #completeGateInteractions(gateId: string): Promise<void> {
+		try {
+			await this.#terminalController?.completeGateInteractions(gateId);
+		} catch (error) {
+			this.opts.audit?.({ event: "gate_interaction_completion_failed", gate_id: gateId, error: String(error) });
+		}
+	}
+
+	async #cancelGateInteractions(gateId: string, reason: string): Promise<void> {
+		try {
+			await this.#terminalController?.cancelGateInteractions(gateId, reason);
+		} catch (error) {
+			this.opts.audit?.({ event: "gate_interaction_cancellation_failed", gate_id: gateId, error: String(error) });
+		}
+	}
+
 	negotiate(declaration: RpcUnattendedDeclaration): RpcUnattendedAccepted {
 		const controller = UnattendedRunController.negotiate(declaration, {
 			runId: this.opts.runId,
@@ -140,7 +231,11 @@ export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane,
 				// openGate returns and the caller starts awaiting.
 				this.#earlyAnswers.set(gate.gate_id, answer);
 			},
+			finalizeAccepted: record => this.#finalizeAcceptedGate(record),
 		});
+		this.#brokerReady = true;
+		void this.startRecoveryOnce();
+
 		return {
 			run_id: this.opts.runId,
 			actor: controller.actor,
@@ -190,12 +285,203 @@ export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane,
 	}
 
 	resolveGate(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution> {
+		if (this.#disposed) return Promise.reject(new Error("unattended session is disposed"));
 		if (!this.#broker) {
 			return Promise.reject(new Error("workflow gates are not available until unattended mode is negotiated"));
 		}
 		return this.#broker.resolve(response);
 	}
 
+	async resolveGateFromNotification(
+		response: RpcWorkflowGateResponse,
+		options: NotificationGateResolutionOptions,
+	): Promise<RpcWorkflowGateResolution> {
+		let claimSettled = false;
+		const resolveClaim = () => {
+			if (claimSettled) return;
+			claimSettled = true;
+			try {
+				options.resolveClaim();
+			} catch (error) {
+				this.opts.audit?.({
+					event: "notification_claim_resolution_failed",
+					gate_id: response.gate_id,
+					error: String(error),
+				});
+			}
+		};
+		const closeClaimInvalid = (reason: string) => {
+			if (claimSettled) return;
+			claimSettled = true;
+			try {
+				options.closeClaimInvalid(reason);
+			} catch (error) {
+				this.opts.audit?.({
+					event: "notification_claim_close_failed",
+					gate_id: response.gate_id,
+					error: String(error),
+				});
+			}
+		};
+		if (this.#disposed) {
+			closeClaimInvalid("unattended_session_disposed");
+			throw new Error("unattended session is disposed");
+		}
+		if (!this.#broker) {
+			closeClaimInvalid("workflow_gate_unavailable");
+			throw new Error("workflow gates are not available until unattended mode is negotiated");
+		}
+		try {
+			JSON.parse(options.answerJson);
+		} catch {
+			closeClaimInvalid("invalid_structured_answer");
+			return {
+				gate_id: response.gate_id,
+				status: "rejected",
+				answer_hash: "",
+				resolved_at: new Date().toISOString(),
+				error: this.#broker.validationError(response.gate_id, "json_parse", "invalid structured answer"),
+			};
+		}
+		let disposition: PersistedSemanticDisposition;
+		try {
+			disposition = this.#broker.classifyDisposition(response.gate_id, response.answer);
+		} catch (error) {
+			closeClaimInvalid(error instanceof Error ? error.message : "invalid_answer");
+			return {
+				gate_id: response.gate_id,
+				status: "rejected",
+				answer_hash: "",
+				resolved_at: new Date().toISOString(),
+				error: this.#broker.validationError(
+					response.gate_id,
+					"semantic_disposition",
+					error instanceof Error ? error.message : "invalid answer",
+				),
+			};
+		}
+
+		const commitKey = `${response.gate_id}:${options.idempotencyKey ?? options.replyReceiptId}`;
+		const ackPolicy: PersistedAckPolicy =
+			disposition === "commit"
+				? {
+						kind: "telegram_selected_v1",
+						commitKey,
+						actionId: options.interactionActionId,
+						state: "pending",
+						updatedAt: new Date().toISOString(),
+					}
+				: { kind: "none", reason: "semantic_noncommit" };
+		let resolution: RpcWorkflowGateResolution;
+		try {
+			resolution = await this.#broker.resolve(response, {
+				resolutionOrigin: { kind: "telegram_notification", interactionActionId: options.interactionActionId },
+				ackPolicy,
+				semanticDisposition: disposition,
+
+				beforeAdvance: async () => {
+					if (ackPolicy.kind === "telegram_selected_v1") {
+						this.#broker?.updateAckPolicy(response.gate_id, {
+							...ackPolicy,
+							state: "attempt_started",
+							updatedAt: new Date().toISOString(),
+						});
+						let outcome: AskSelectedAckOutcome;
+						try {
+							outcome = await options.requestSelectedAck({
+								replyReceiptId: options.replyReceiptId,
+								actionId: options.interactionActionId,
+								commitKey,
+								daemonDeadlineAt: Date.now() + 8_000,
+								hostTimeoutMs: 10_000,
+							});
+						} catch {
+							outcome = { status: "unknown", reason: "host_timeout" };
+						}
+						this.#broker?.updateAckPolicy(response.gate_id, {
+							...ackPolicy,
+							state: outcome.status,
+							outcome,
+							updatedAt: new Date().toISOString(),
+						});
+					}
+					resolveClaim();
+				},
+			});
+		} catch (error) {
+			closeClaimInvalid(error instanceof Error ? error.message : "invalid_answer");
+			throw error;
+		}
+		if (resolution.status === "accepted") resolveClaim();
+		else closeClaimInvalid(resolution.error?.code ?? "invalid_answer");
+		return resolution;
+	}
+
+	async startRecoveryOnce(options: { participantGraceMs?: number } = {}): Promise<void> {
+		if (this.#disposed || !this.#brokerReady) return;
+		if (this.#recoveryPromise) return this.#recoveryPromise;
+		this.#recoveryPromise = (async () => {
+			if (!this.#recoveryParticipant) {
+				const grace = options.participantGraceMs ?? 2_000;
+				await Promise.race([
+					this.#participantReady.promise,
+					new Promise<void>(resolve => setTimeout(resolve, grace)),
+				]);
+			}
+			if (!this.#disposed) await this.#broker?.recover();
+		})();
+		return this.#recoveryPromise;
+	}
+
+	async #finalizeAcceptedGate(record: PersistedGate): Promise<void> {
+		const policy = record.ackPolicy;
+		if (policy?.kind === "telegram_selected_v1" && policy.state === "pending") {
+			let outcome: AskSelectedAckOutcome;
+			const participant = this.#recoveryParticipant;
+			if (!participant || !this.opts.sessionId) {
+				outcome = { status: "failed", reason: "no_participant" };
+			} else {
+				this.#broker?.updateAckPolicy(record.gate.gate_id, {
+					...policy,
+					state: "attempt_started",
+					updatedAt: new Date().toISOString(),
+				});
+				try {
+					outcome = await participant.requestRecoveredAskSelectedAck({
+						sessionId: this.opts.sessionId,
+						actionId: policy.actionId,
+						commitKey: policy.commitKey,
+						deadlineAt: Date.now() + 8_000,
+						hostTimeoutMs: 10_000,
+					});
+				} catch {
+					outcome = { status: "unknown", reason: "host_timeout" };
+				}
+			}
+			this.#broker?.updateAckPolicy(record.gate.gate_id, {
+				...policy,
+				state: outcome.status,
+				outcome,
+				updatedAt: new Date().toISOString(),
+			});
+		}
+		if (policy?.kind === "telegram_selected_v1" && policy.state === "attempt_started") {
+			this.#broker?.updateAckPolicy(record.gate.gate_id, {
+				...policy,
+				state: "unknown",
+				outcome: { status: "unknown", reason: "shutdown" },
+				updatedAt: new Date().toISOString(),
+			});
+		}
+		await this.#completeGateInteractions(record.gate.gate_id);
+	}
+
+	dispose(reason = "session_shutdown"): void {
+		this.#disposed = true;
+		for (const gateId of this.#pending.keys()) void this.#cancelGateInteractions(gateId, reason);
+		this.#rejectAllPending(new Error(`unattended session disposed: ${reason}`));
+	}
+
 	listPendingGates(): import("../../rpc/rpc-types").RpcWorkflowGate[] {
 		const store = this.opts.store;
 		if (!store) return [];
@@ -206,6 +492,7 @@ export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane,
 	}
 
 	emitGate(input: OpenGateInput): Promise<unknown> {
+		if (this.#disposed) return Promise.reject(new Error("unattended session is disposed"));
 		if (!this.#broker) {
 			return Promise.reject(new Error("cannot emit a workflow gate before unattended mode is negotiated"));
 		}

package/src/modes/shared/agent-wire/workflow-gate-broker.ts

@@ -13,6 +13,7 @@
  */
 import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
+import type { AskSelectedAckOutcome } from "../../../tools";
 import type {
 	RpcWorkflowGate,
 	RpcWorkflowGateContext,
@@ -20,11 +21,36 @@ import type {
 	RpcWorkflowGateOption,
 	RpcWorkflowGateResolution,
 	RpcWorkflowGateResponse,
+	RpcWorkflowGateValidationError,
 	RpcWorkflowStage,
 } from "../../rpc/rpc-types";
 import { RESERVED_WORKFLOW_STAGES } from "../../rpc/rpc-types";
+import { classifyAskGateDisposition } from "./deep-interview-gate";
 import { answerHashOf, canonicalJson, compileGateSchema, schemaHash, validateGateAnswer } from "./workflow-gate-schema";
 
+export type PersistedSemanticDisposition = "commit" | "resolve_without_commit";
+export type PersistedResolutionOrigin =
+	| { kind: "generic"; channel: "rpc" | "bridge" | "other" }
+	| { kind: "telegram_notification"; interactionActionId: string }
+	| { kind: "legacy_unknown" };
+export type PersistedAckPolicy =
+	| { kind: "none"; reason: "non_telegram" | "semantic_noncommit" | "legacy_unproven" }
+	| {
+			kind: "telegram_selected_v1";
+			commitKey: string;
+			actionId: string;
+			state: "pending" | "attempt_started" | "delivered" | "failed" | "unknown";
+			outcome?: AskSelectedAckOutcome;
+			updatedAt: string;
+	  };
+
+export interface GateResolutionOptions {
+	semanticDisposition?: PersistedSemanticDisposition;
+	resolutionOrigin?: PersistedResolutionOrigin;
+	ackPolicy?: PersistedAckPolicy;
+	beforeAdvance?: () => Promise<void>;
+}
+
 const V1_STAGES: readonly RpcWorkflowStage[] = ["deep-interview", "ralplan", "ultragoal"];
 
 export interface PersistedGate {
@@ -36,6 +62,9 @@ export interface PersistedGate {
 	answer?: unknown;
 	resolution?: RpcWorkflowGateResolution;
 	advanced: boolean;
+	semanticDisposition?: PersistedSemanticDisposition;
+	resolutionOrigin?: PersistedResolutionOrigin;
+	ackPolicy?: PersistedAckPolicy;
 }
 
 export interface GateStore {
@@ -153,6 +182,9 @@ export interface BrokerHooks {
 	 * it for any gate left `accepted` but not `advanced` by a crash.
 	 */
 	advance?(gate: RpcWorkflowGate, answer: unknown): void | Promise<void>;
+	/** Runs after durable acceptance and before advance, including crash recovery. */
+	finalizeAccepted?(record: PersistedGate): Promise<void>;
+
 	/** Append-only audit sink. */
 	audit?(event: GateAuditEvent): void;
 }
@@ -176,12 +208,51 @@ export class WorkflowGateBrokerError extends Error {
 }
 
 export class WorkflowGateBroker {
+	private readonly recovering = new Set<string>();
+	private readonly gateLocks = new Map<string, Promise<void>>();
+
+	private async withGateLock<T>(gateId: string, operation: () => Promise<T>): Promise<T> {
+		const previous = this.gateLocks.get(gateId) ?? Promise.resolve();
+		const release = Promise.withResolvers<void>();
+		const current = previous.then(() => release.promise);
+		this.gateLocks.set(gateId, current);
+		await previous;
+		try {
+			return await operation();
+		} finally {
+			release.resolve();
+			if (this.gateLocks.get(gateId) === current) this.gateLocks.delete(gateId);
+		}
+	}
+
 	constructor(
 		private readonly runId: string,
 		private readonly store: GateStore,
 		private readonly hooks: BrokerHooks = {},
 	) {}
 
+	classifyDisposition(gateId: string, answer: unknown): PersistedSemanticDisposition {
+		const record = this.store.get(gateId);
+		if (!record) throw new WorkflowGateBrokerError("unknown_gate", `no pending gate ${gateId}`);
+		return classifyAskGateDisposition(record.gate, answer);
+	}
+	validationError(gateId: string, keyword: string, message: string): RpcWorkflowGateValidationError {
+		const record = this.store.get(gateId);
+		return {
+			code: "invalid_workflow_gate_answer",
+			gate_id: gateId,
+			schema_hash: record ? schemaHash(record.gate.schema) : "",
+			errors: [{ path: "$", keyword, message }],
+		};
+	}
+
+	updateAckPolicy(gateId: string, ackPolicy: PersistedAckPolicy): void {
+		const record = this.store.get(gateId);
+		if (record?.status !== "accepted")
+			throw new WorkflowGateBrokerError("unknown_gate", `no accepted gate ${gateId}`);
+		this.store.put({ ...record, ackPolicy });
+	}
+
 	private runShort(): string {
 		return this.runId.replace(/[^a-zA-Z0-9]/g, "").slice(-8) || "run";
 	}
@@ -222,7 +293,17 @@ export class WorkflowGateBroker {
 	 * On success the resolution is persisted BEFORE `advance` is invoked exactly
 	 * once. Invalid answers leave the gate pending (per #315 acceptance).
 	 */
-	async resolve(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution> {
+	async resolve(
+		response: RpcWorkflowGateResponse,
+		options: GateResolutionOptions = {},
+	): Promise<RpcWorkflowGateResolution> {
+		return this.withGateLock(response.gate_id, () => this.resolveUnlocked(response, options));
+	}
+
+	private async resolveUnlocked(
+		response: RpcWorkflowGateResponse,
+		options: GateResolutionOptions = {},
+	): Promise<RpcWorkflowGateResolution> {
 		const record = this.store.get(response.gate_id);
 		if (!record) {
 			this.hooks.audit?.({ event: "gate_response_unknown_gate", gate_id: response.gate_id });
@@ -263,6 +344,13 @@ export class WorkflowGateBroker {
 			};
 		}
 
+		const semanticDisposition =
+			options.semanticDisposition ?? classifyAskGateDisposition(record.gate, response.answer);
+		const resolutionOrigin = options.resolutionOrigin ?? { kind: "generic", channel: "rpc" as const };
+		const ackPolicy =
+			options.ackPolicy ??
+			({ kind: "none", reason: semanticDisposition === "commit" ? "non_telegram" : "semantic_noncommit" } as const);
+
 		const resolution: RpcWorkflowGateResolution = {
 			gate_id: response.gate_id,
 			status: "accepted",
@@ -280,18 +368,30 @@ export class WorkflowGateBroker {
 			answer: response.answer,
 			resolution,
 			advanced: false,
+			semanticDisposition,
+			resolutionOrigin,
+			ackPolicy,
 		});
 		this.hooks.audit?.({ event: "gate_response_accepted", gate_id: response.gate_id, answer_hash: answerHash });
-		await this.hooks.advance?.(record.gate, response.answer);
-		this.store.put({
-			gate: record.gate,
-			status: "accepted",
-			idempotencyKey: response.idempotency_key,
-			responseHash,
-			answer: response.answer,
-			resolution,
-			advanced: true,
-		});
+		await options.beforeAdvance?.();
+		await this.hooks.finalizeAccepted?.(this.store.get(response.gate_id) as PersistedGate);
+		const finalized = this.store.get(response.gate_id);
+		if (finalized?.status !== "accepted") {
+			throw new WorkflowGateBrokerError(
+				"unknown_gate",
+				`accepted gate ${response.gate_id} disappeared before advance`,
+			);
+		}
+		if (finalized.advanced) return finalized.resolution ?? resolution;
+		await this.hooks.advance?.(finalized.gate, finalized.answer);
+		const latest = this.store.get(response.gate_id);
+		if (latest?.status !== "accepted") {
+			throw new WorkflowGateBrokerError(
+				"unknown_gate",
+				`accepted gate ${response.gate_id} disappeared after advance`,
+			);
+		}
+		this.store.put({ ...latest, advanced: true });
 		return resolution;
 	}
 
@@ -304,15 +404,25 @@ export class WorkflowGateBroker {
 	async recover(): Promise<string[]> {
 		const recovered: string[] = [];
 		for (const listed of this.store.list()) {
-			if (listed.status !== "accepted" || listed.advanced) continue;
-			// Re-read immediately before advancing so a concurrent recoverer that
-			// already advanced this gate (stale snapshot) cannot double-advance.
-			const rec = this.store.get(listed.gate.gate_id);
-			if (rec?.status !== "accepted" || rec.advanced) continue;
-			await this.hooks.advance?.(rec.gate, rec.answer);
-			this.store.put({ ...rec, advanced: true });
-			this.hooks.audit?.({ event: "gate_advance_recovered", gate_id: rec.gate.gate_id });
-			recovered.push(rec.gate.gate_id);
+			if (listed.status !== "accepted" || listed.advanced || this.recovering.has(listed.gate.gate_id)) continue;
+			this.recovering.add(listed.gate.gate_id);
+			try {
+				await this.withGateLock(listed.gate.gate_id, async () => {
+					const rec = this.store.get(listed.gate.gate_id);
+					if (rec?.status !== "accepted" || rec.advanced) return;
+					await this.hooks.finalizeAccepted?.(rec);
+					const finalized = this.store.get(listed.gate.gate_id);
+					if (finalized?.status !== "accepted" || finalized.advanced) return;
+					await this.hooks.advance?.(finalized.gate, finalized.answer);
+					const latest = this.store.get(listed.gate.gate_id);
+					if (latest?.status !== "accepted" || latest.advanced) return;
+					this.store.put({ ...latest, advanced: true });
+					this.hooks.audit?.({ event: "gate_advance_recovered", gate_id: latest.gate.gate_id });
+					recovered.push(latest.gate.gate_id);
+				});
+			} finally {
+				this.recovering.delete(listed.gate.gate_id);
+			}
 		}
 		return recovered;
 	}

package/src/modes/types.ts

@@ -23,14 +23,18 @@ import type { AssistantMessageComponent } from "./components/assistant-message";
 import type { BashExecutionComponent } from "./components/bash-execution";
 import type { CustomEditor } from "./components/custom-editor";
 import type { EvalExecutionComponent } from "./components/eval-execution";
+import type { PetMode } from "./components/gajae-pet-widget";
 import type { HookEditorComponent } from "./components/hook-editor";
 import type { HookInputComponent } from "./components/hook-input";
 import type { HookSelectorComponent } from "./components/hook-selector";
 import type { StatusLineComponent } from "./components/status-line";
 import type { ToolExecutionHandle } from "./components/tool-execution";
+import type { IrcObservationLedger } from "./irc-observation-ledger";
 import type { OAuthManualInputManager } from "./oauth-manual-input";
 import type { Theme } from "./theme/theme";
+import type { ParsedIrcMessage } from "./utils/irc-message";
 
+export type TranscriptRebuildPolicy = "replace-identity" | "reconcile-same-transcript";
 export type CompactionQueuedMessage = {
 	text: string;
 	mode: "steer" | "followUp";
@@ -60,6 +64,14 @@ export type TodoPhase = {
 	tasks: TodoItem[];
 };
 
+export type IrcArrivalSnapshot = Readonly<{
+	panelVisible: boolean;
+	/** User-requested open state; may be true while the panel yields at narrow widths. */
+	panelRequestedVisible: boolean;
+	sidebarAvailable: boolean;
+	resolvedToggleKey: string | null;
+}>;
+
 export interface InteractiveModeContext {
 	// UI access
 	ui: TUI;
@@ -84,6 +96,7 @@ export interface InteractiveModeContext {
 	mcpManager?: MCPManager;
 	lspServers?: LspStartupServerInfo[];
 
+	readonly ircLedger: IrcObservationLedger;
 	// State
 	isInitialized: boolean;
 	isBackgrounded: boolean;
@@ -163,6 +176,11 @@ export interface InteractiveModeContext {
 	setWorkingMessage(message?: string): void;
 	applyPendingWorkingMessage(): void;
 	ensureLoadingAnimation(): void;
+	setPetMode(mode: PetMode): void;
+	/** Live-preview a pet skin during a selector without persisting. */
+	previewPetMode(mode: PetMode): void;
+	/** Re-mount the composer (pet-aware) after an overlay/selector closes. */
+	restoreComposer(): void;
 	startPendingSubmission(input: {
 		text: string;
 		images?: ImageContent[];
@@ -187,21 +205,34 @@ export interface InteractiveModeContext {
 	withLocalSubmission<T>(text: string, fn: () => Promise<T>, options?: { imageCount?: number }): Promise<T>;
 	isKnownSlashCommand(text: string): boolean;
 	addMessageToChat(message: AgentMessage, options?: { populateHistory?: boolean }): Component[];
+	addLiveIrcObservationToChat(message: ParsedIrcMessage, arrival: IrcArrivalSnapshot): Component[];
+	removeRenderedIrcInlineComponents(observationId: string): readonly Component[] | undefined;
+	resetRenderedIrcInlineComponents(): readonly (readonly Component[])[];
 	renderSessionContext(
 		sessionContext: SessionContext,
 		options?: { updateFooter?: boolean; populateHistory?: boolean },
 	): void;
-	renderInitialMessages(prebuiltContext?: SessionContext, options?: { preserveExistingChat?: boolean }): void;
+	rebuildInitialMessages(
+		policy: TranscriptRebuildPolicy,
+		prebuiltContext?: SessionContext,
+		options?: { preserveExistingChat?: boolean },
+	): void;
 	getUserMessageText(message: Message): string;
+	getAssistantViewportAnchorId?(message: AssistantMessage): string;
 	findLastAssistantMessage(): AssistantMessage | undefined;
 	extractAssistantText(message: AssistantMessage): string;
 	updateEditorTopBorder(): void;
 	updateEditorBorderColor(): void;
-	rebuildChatFromMessages(): void;
+	rebuildChatFromMessages(policy: TranscriptRebuildPolicy): void;
 	setTodos(todos: TodoItem[] | TodoPhase[]): void;
 	reloadTodos(): Promise<void>;
 	toggleTodoExpansion(): void;
 
+	// IRC sidebar
+	toggleIrcSidebar(): void;
+	captureIrcArrivalSnapshot(): IrcArrivalSnapshot;
+	applyIrcSidebarAvailability(enabled: boolean): void;
+	resetIrcSidebarSession(): void;
 	// Command handling
 	handleExportCommand(text: string): Promise<void>;
 	handleShareCommand(): Promise<void>;
@@ -242,6 +273,7 @@ export interface InteractiveModeContext {
 	// Selector handling
 	showSettingsSelector(): void;
 	showThemeSelector(): void;
+	showPetSelector(): void;
 	showHistorySearch(): void;
 	showExtensionsDashboard(): void;
 	showAgentsDashboard(): void;

package/src/modes/utils/hotkeys-markdown.ts

@@ -54,6 +54,7 @@ export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string
 		`| \`${appKey(bindings, "app.editor.external")}\` | Edit message in external editor |`,
 		`| \`${appKey(bindings, "app.clipboard.pasteImage")}\` | Paste image from clipboard |`,
 		`| \`${appKey(bindings, "app.stt.toggle")}\` | Toggle speech-to-text recording |`,
+		`| \`${appKey(bindings, "app.irc.sidebar.toggle")}\` | Toggle IRC sidebar |`,
 		"| `?` | Show help / shortcuts |",
 		"| `#` | Prompt actions (command-palette style actions) |",
 		"| `/` | Slash commands (try `/help` or `/new`) |",