@gajae-code/coding-agent 0.16.0 → 0.16.3

package/src/sdk/bus/chat-daemon-runtime.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { logger } from "@gajae-code/utils";
 import { SdkClientError } from "../client/client";
 import { SESSION_PREPARED_EVENT } from "../host/host";
 
@@ -260,6 +261,9 @@ export class ChatDaemonRuntime {
 	readonly #cleanupWork = new Map<string, Promise<void>>();
 	readonly #retirementWork = new Map<string, Promise<void>>();
 	readonly #attachmentBarriers = new Map<string, Promise<void>>();
+	readonly #cleanupFailures = new Map<string, unknown>();
+	#replayReady: Promise<void> = Promise.resolve();
+	#stopping = false;
 	#discord: DiscordNotificationDaemon | undefined;
 	#slack: SlackNotificationDaemon | undefined;
 	#presentation: NotificationPresentationEngine | undefined;
@@ -276,24 +280,40 @@ export class ChatDaemonRuntime {
 				...deps.routerDeps,
 				onFrame: async (attachment, frame) => await this.#handleFrame(attachment, frame),
 				onAttachment: async attachment => this.#onAttachment(attachment),
+				onReplayReady: async () => await this.#replayReady,
 				onSessionRemoved: async (attachment, reason) => await this.#onSessionRemoved(attachment, reason),
 			},
 		});
 	}
 
 	async start(): Promise<void> {
+		const replayReady = Promise.withResolvers<void>();
+		this.#replayReady = replayReady.promise;
+		// Startup can fail before any attachment observes the replay barrier. Mark
+		// the rejection handled without changing what actual waiters observe.
+		void this.#replayReady.catch(() => undefined);
 		if (this.#cleanupWork.size > 0 || this.#retirementWork.size > 0) {
 			const retirements = [...this.#retirementWork.entries()];
+			const cleanup = [...this.#cleanupWork.values()];
+			const retirement = retirements.map(([, work]) => work);
 			const settled = await Promise.race([
-				Promise.all([
-					Promise.allSettled([...this.#cleanupWork.values()]),
-					Promise.all(retirements.map(([, retirement]) => retirement)),
-				]).then(() => true),
+				Promise.all([Promise.allSettled(cleanup), Promise.allSettled(retirement)]).then(() => true),
 				Bun.sleep(5_000).then(() => false),
 			]);
 			if (!settled) throw new Error("Prior provider cleanup did not settle before chat daemon restart.");
-			for (const [sessionId, retirement] of retirements)
-				if (this.#retirementWork.get(sessionId) === retirement) this.#retirementWork.delete(sessionId);
+			const failures = await Promise.all([Promise.allSettled(cleanup), Promise.allSettled(retirement)]);
+			const rejected = failures
+				.flat()
+				.filter((result): result is PromiseRejectedResult => result.status === "rejected");
+			if (rejected.length > 0) {
+				logger.warn(`SDK chat daemon retained ${rejected.length} prior cleanup failure(s) for recovery.`);
+			}
+			for (const [sessionId, work] of retirements)
+				if (this.#retirementWork.get(sessionId) === work && !rejected.some(result => result.status === "rejected"))
+					this.#retirementWork.delete(sessionId);
+			for (const [sessionId, work] of [...this.#cleanupWork.entries()])
+				if (work !== undefined && !rejected.some(result => result.status === "rejected"))
+					this.#cleanupWork.delete(sessionId);
 		}
 		this.#attachments.clear();
 		const retainedProvider =
@@ -308,8 +328,10 @@ export class ChatDaemonRuntime {
 			try {
 				await this.#router.start();
 				await retainedProvider.start();
+				replayReady.resolve();
 				return;
 			} catch (error) {
+				replayReady.reject(error);
 				await this.#router.stop().catch(() => undefined);
 				throw error;
 			}
@@ -370,7 +392,9 @@ export class ChatDaemonRuntime {
 			await this.#router.start();
 			if (this.#discord) await this.#discord.start();
 			if (this.#slack) await this.#slack.start();
+			replayReady.resolve();
 		} catch (error) {
+			replayReady.reject(error);
 			await this.stop();
 			throw error;
 		}
@@ -386,6 +410,20 @@ export class ChatDaemonRuntime {
 	}
 
 	async stop(): Promise<void> {
+		this.#stopping = true;
+		let routerError: unknown;
+		try {
+			await this.#router.stop();
+		} catch (error) {
+			routerError = error;
+		}
+		const cleanupDrain = Promise.allSettled([...this.#cleanupWork.values(), ...this.#retirementWork.values()]);
+		const cleanupSettled = await Promise.race([cleanupDrain.then(() => true), Bun.sleep(5_000).then(() => false)]);
+		const cleanupResults = cleanupSettled
+			? await cleanupDrain
+			: [{ status: "rejected" as const, reason: new Error("Provider cleanup exceeded shutdown drain.") }];
+		if (!cleanupSettled)
+			logger.warn("SDK chat daemon cleanup exceeded the shutdown drain; provider stop will invalidate it.");
 		const providerResults = await Promise.allSettled([this.#discord?.stop(), this.#slack?.stop()]);
 		const discordRestartBlocked = this.#discord?.restartBlocked() ?? false;
 		const slackRestartBlocked = this.#slack?.restartBlocked() ?? false;
@@ -395,10 +433,12 @@ export class ChatDaemonRuntime {
 			this.#presentation = undefined;
 			this.#transportHealthy = undefined;
 		}
-		await this.#router.stop();
-		const failures = providerResults.filter(
-			(result): result is PromiseRejectedResult => result.status === "rejected",
-		);
+		this.#stopping = false;
+		const failures = [
+			...(routerError === undefined ? [] : [{ status: "rejected" as const, reason: routerError }]),
+			...cleanupResults,
+			...providerResults,
+		].filter((result): result is PromiseRejectedResult => result.status === "rejected");
 		if (failures.length > 0)
 			throw new AggregateError(
 				failures.map(result => result.reason),
@@ -431,19 +471,45 @@ export class ChatDaemonRuntime {
 	}
 
 	async #onAttachment(attachment: SessionAttachment): Promise<void> {
+		const revivedTransport = this.#attachments.get(attachment.sessionId) === attachment;
 		this.#attachments.set(attachment.sessionId, attachment);
+		if (revivedTransport) {
+			this.#presentation?.connectSession(attachment.sessionId, {
+				sendReply: route => attachment.send({ type: "reply", id: route.actionId, answer: route.answer }),
+			});
+			return;
+		}
 		const discord = this.#discord;
 		const slack = this.#slack;
 		const barrier = (async () => {
 			const retirement = this.#retirementWork.get(attachment.sessionId);
+			let retirementFailure: unknown;
 			if (retirement) {
-				await retirement;
-				if (this.#retirementWork.get(attachment.sessionId) === retirement)
-					this.#retirementWork.delete(attachment.sessionId);
+				try {
+					await retirement;
+				} catch (error) {
+					retirementFailure = error;
+					logger.warn(`SDK chat daemon retirement cleanup failed before successor attachment: ${String(error)}`);
+				}
+			}
+			const cleanup = this.#cleanupWork.get(attachment.sessionId);
+			if (cleanup) await cleanup.catch(error => logger.warn(`SDK cleanup retry pending: ${String(error)}`));
+			const [discordRecovered, slackRecovered] = await Promise.all([
+				discord?.recoverCleanup(attachment.sessionId, attachment.generation, attachment.authorityId) ?? true,
+				slack?.recoverCleanup(attachment.sessionId, attachment.generation, attachment.authorityId) ?? true,
+			]);
+			if (!discordRecovered || !slackRecovered)
+				throw new Error("successor_attachment_blocked_until_retirement_is_verified");
+			if (cleanup !== undefined && this.#cleanupWork.get(attachment.sessionId) === cleanup) {
+				this.#cleanupWork.delete(attachment.sessionId);
+				this.#cleanupFailures.delete(attachment.sessionId);
 			}
-			await this.#cleanupWork.get(attachment.sessionId)?.catch(() => undefined);
-			await discord?.recoverCleanup(attachment.sessionId, attachment.generation);
-			await slack?.recoverCleanup(attachment.sessionId, attachment.generation);
+			if (
+				retirementFailure !== undefined &&
+				retirement &&
+				this.#retirementWork.get(attachment.sessionId) === retirement
+			)
+				this.#retirementWork.delete(attachment.sessionId);
 		})();
 		this.#attachmentBarriers.set(attachment.sessionId, barrier);
 		try {
@@ -470,7 +536,7 @@ export class ChatDaemonRuntime {
 			return;
 		}
 		this.#attachments.delete(attachment.sessionId);
-		if (reason === "removed") await this.#trackCleanup(attachment);
+		if (reason === "removed" && !this.#stopping) await this.#trackCleanup(attachment);
 	}
 
 	#trackRetirement(attachment: SessionAttachment): Promise<void> {
@@ -478,7 +544,13 @@ export class ChatDaemonRuntime {
 		const discord = this.#discord;
 		const slack = this.#slack;
 		const previous = this.#retirementWork.get(sessionId);
-		const work = (previous ?? Promise.resolve()).then(async () => {
+		const work = (
+			previous
+				? previous.catch(error => {
+						this.#cleanupFailures.set(sessionId, error);
+					})
+				: Promise.resolve()
+		).then(async () => {
 			// Capture the predecessor providers before stop() can clear the runtime
 			// fields. The successor barrier owns this promise until every retirement
 			// waiter settles, even when takeover overlaps worker shutdown.
@@ -486,6 +558,12 @@ export class ChatDaemonRuntime {
 			await slack?.retireAttachment(sessionId, attachment.generation);
 		});
 		this.#retirementWork.set(sessionId, work);
+		void work.then(
+			() => {
+				if (this.#retirementWork.get(sessionId) === work) this.#retirementWork.delete(sessionId);
+			},
+			() => undefined,
+		);
 		return work;
 	}
 
@@ -507,7 +585,10 @@ export class ChatDaemonRuntime {
 		}
 		if (name === SESSION_PREPARED_EVENT || bodyType === SESSION_PREPARED_EVENT) return;
 		if (name === "session_ready") {
-			if (correlated.generation !== attachment.generation) return;
+			// The attachment itself is the endpoint-generation authority. An
+			// unpositioned session_ready frame deliberately carries no ring
+			// generation; reject only an explicit, conflicting Router-owned value.
+			if (correlated.generation !== undefined && correlated.generation !== attachment.generation) return;
 			await this.#resume(
 				sessionId,
 				attachment.generation,
@@ -550,7 +631,7 @@ export class ChatDaemonRuntime {
 			await this.#slack.notify(
 				sessionId,
 				content,
-				notification.type === "action_needed" ? notification.id : undefined,
+				notification.type === "action_needed" && notification.kind === "ask" ? notification.id : undefined,
 				attachment.generation,
 				publicationId,
 			);
@@ -559,13 +640,26 @@ export class ChatDaemonRuntime {
 	#trackCleanup(attachment: SessionAttachment): Promise<void> {
 		const sessionId = attachment.sessionId;
 		const previous = this.#cleanupWork.get(sessionId);
-		const work = (previous ? previous.catch(() => undefined) : Promise.resolve()).then(async () => {
+		const work = (
+			previous
+				? previous.catch(error => {
+						this.#cleanupFailures.set(sessionId, error);
+					})
+				: Promise.resolve()
+		).then(async () => {
 			await this.#closeProviders(attachment);
 		});
 		this.#cleanupWork.set(sessionId, work);
-		return work.finally(() => {
-			if (this.#cleanupWork.get(sessionId) === work) this.#cleanupWork.delete(sessionId);
-		});
+		void work.then(
+			() => {
+				if (this.#cleanupWork.get(sessionId) === work) {
+					this.#cleanupWork.delete(sessionId);
+					this.#cleanupFailures.delete(sessionId);
+				}
+			},
+			() => undefined,
+		);
+		return work;
 	}
 	async #closeProviders(attachment: SessionAttachment): Promise<void> {
 		const discord = this.#discord;

package/src/sdk/bus/discord-daemon.ts

@@ -166,8 +166,9 @@ export class DiscordNotificationDaemon {
 		expectedGeneration?: number,
 	) => SessionAttachment | null | Promise<SessionAttachment | null>;
 	readonly #effects: ChatEffectJournal;
-	readonly #activeWork = new Set<Promise<unknown>>();
+	readonly #activeWork = new Map<Promise<unknown>, string | undefined>();
 	readonly #workInvalidators = new Set<() => Promise<void>>();
+	readonly #sessionInvalidators = new Map<string, Set<() => Promise<void>>>();
 	readonly #inflightInbound = new Set<string>();
 	#started = false;
 	#lifecycleGeneration = 0;
@@ -264,7 +265,8 @@ export class DiscordNotificationDaemon {
 				await this.options.provider.start(
 					async event => {
 						if (lifecycleGeneration !== this.#lifecycleGeneration || !this.#started) return;
-						await this.#track(this.handleInbound(event));
+						const record = await this.#byThread(event.guildId, event.parentId, event.threadId);
+						await this.#track(this.handleInbound(event), record?.sessionId);
 					},
 					() => {},
 				);
@@ -375,6 +377,9 @@ export class DiscordNotificationDaemon {
 		this.#workGeneration += 1;
 		await Promise.allSettled([...this.#workInvalidators].map(invalidate => invalidate()));
 	}
+	async #invalidateSessionWork(sessionId: string): Promise<void> {
+		await Promise.allSettled([...(this.#sessionInvalidators.get(sessionId) ?? [])].map(invalidate => invalidate()));
+	}
 
 	async #drainActiveWork(deadline: number): Promise<void> {
 		while (this.#activeWork.size > 0) {
@@ -385,7 +390,7 @@ export class DiscordNotificationDaemon {
 				return;
 			}
 			const settled = await Promise.race([
-				Promise.allSettled([...this.#activeWork]).then(() => true),
+				Promise.allSettled([...this.#activeWork.keys()]).then(() => true),
 				Bun.sleep(remaining).then(() => false),
 			]);
 			if (!settled) {
@@ -395,6 +400,17 @@ export class DiscordNotificationDaemon {
 			}
 		}
 	}
+	async #drainSessionWork(sessionId: string, deadline: number): Promise<void> {
+		while (true) {
+			const work = [...this.#activeWork.entries()]
+				.filter(([, activeSessionId]) => activeSessionId === sessionId)
+				.map(([promise]) => promise);
+			if (work.length === 0) return;
+			const remaining = deadline - this.#now();
+			if (remaining <= 0) return;
+			await Promise.race([Promise.allSettled(work), Bun.sleep(remaining)]);
+		}
+	}
 
 	#recordProviderLifecycleError(error: unknown): void {
 		this.#providerLifecycleError = error;
@@ -422,7 +438,7 @@ export class DiscordNotificationDaemon {
 	 * legitimate create into a spurious teardown rejection.
 	 */
 	async notify(input: DiscordNotificationInput): Promise<DiscordConversation> {
-		return await this.#track(this.#notify(input));
+		return await this.#track(this.#notify(input), input.sessionId);
 	}
 	async #notify(input: DiscordNotificationInput): Promise<DiscordConversation> {
 		await this.#requireLiveBinding(input.sessionId, input.endpointGeneration, input.attachmentAuthorityId);
@@ -457,7 +473,7 @@ export class DiscordNotificationDaemon {
 
 	/** Posts a safe command outcome to the active mapped conversation. */
 	async postCommandResult(sessionId: string, content: string): Promise<boolean> {
-		return await this.#track(this.#postCommandResult(sessionId, content));
+		return await this.#track(this.#postCommandResult(sessionId, content), sessionId);
 	}
 	async #postCommandResult(sessionId: string, content: string): Promise<boolean> {
 		const record = await this.#bySession(sessionId);
@@ -471,13 +487,20 @@ export class DiscordNotificationDaemon {
 		if (closing) await this.#driveClose(closing);
 	}
 
-	async recoverCleanup(sessionId: string, endpointGeneration: number): Promise<void> {
+	async recoverCleanup(sessionId: string, endpointGeneration: number, authorityId?: string): Promise<boolean> {
 		const record = await this.#bySession(sessionId);
-		if (record?.endpointGeneration !== endpointGeneration || !closingIntent(record)) return;
+		if (record?.endpointGeneration !== endpointGeneration) return true;
+		if (record?.state === "closed" || record?.state === "archived" || record?.state === "resuming") return true;
+		if (!closingIntent(record) && record?.state === "active" && record.attachmentAuthorityId === authorityId)
+			return true;
+		if (!closingIntent(record)) return false;
 		await this.#driveClose(record);
+		return true;
 	}
 
 	async retireAttachment(sessionId: string, endpointGeneration: number): Promise<void> {
+		await this.#invalidateSessionWork(sessionId);
+		await this.#drainSessionWork(sessionId, this.#now() + 5_000);
 		const intentKey = this.#intentKey(sessionId);
 		const now = this.#now();
 		await this.#store.transact(intentKey, current => {
@@ -548,7 +571,7 @@ export class DiscordNotificationDaemon {
 		endpointGeneration: number,
 		attachmentAuthorityId?: string,
 	): Promise<DiscordConversation | undefined> {
-		return await this.#track(this.#resumeAdmission(sessionId, endpointGeneration, attachmentAuthorityId));
+		return await this.#track(this.#resumeAdmission(sessionId, endpointGeneration, attachmentAuthorityId), sessionId);
 	}
 	async #resumeAdmission(
 		sessionId: string,
@@ -665,8 +688,8 @@ export class DiscordNotificationDaemon {
 		}
 	}
 
-	#track<T>(work: Promise<T>): Promise<T> {
-		this.#activeWork.add(work);
+	#track<T>(work: Promise<T>, sessionId?: string): Promise<T> {
+		this.#activeWork.set(work, sessionId);
 		return work.finally(() => this.#activeWork.delete(work));
 	}
 
@@ -1871,6 +1894,11 @@ export class DiscordNotificationDaemon {
 	#intentKey(sessionId: string): string {
 		return `${this.options.provider.applicationId}:${this.options.guildId}:${this.options.parentChannelId}:creating:${sessionId}`;
 	}
+	#removeSessionInvalidator(sessionId: string, set: Set<() => Promise<void>>, invalidate: () => Promise<void>): void {
+		set.delete(invalidate);
+		if (set.size === 0 && this.#sessionInvalidators.get(sessionId) === set)
+			this.#sessionInvalidators.delete(sessionId);
+	}
 	async #withCreateIntentLease<T>(intent: DiscordConversation, work: () => Promise<T>): Promise<T> {
 		let lost = false;
 		let renewal: Promise<boolean> | undefined;
@@ -1886,6 +1914,9 @@ export class DiscordNotificationDaemon {
 			await abandonCurrent();
 		};
 		this.#workInvalidators.add(invalidate);
+		const sessionInvalidators = this.#sessionInvalidators.get(intent.sessionId!) ?? new Set<() => Promise<void>>();
+		sessionInvalidators.add(invalidate);
+		this.#sessionInvalidators.set(intent.sessionId!, sessionInvalidators);
 		const renew = async (): Promise<boolean> => {
 			if (lost || workGeneration !== this.#workGeneration) {
 				await invalidate();
@@ -1953,6 +1984,7 @@ export class DiscordNotificationDaemon {
 		} finally {
 			clearInterval(timer);
 			this.#workInvalidators.delete(invalidate);
+			this.#removeSessionInvalidator(intent.sessionId!, sessionInvalidators, invalidate);
 		}
 	}
 	async #clearPending(record: DiscordConversation, actionId: string, actionNonce: string): Promise<void> {
@@ -2076,6 +2108,12 @@ export class DiscordNotificationDaemon {
 			);
 		};
 		this.#workInvalidators.add(invalidate);
+		let sessionInvalidators: Set<() => Promise<void>> | undefined;
+		if (sessionId !== undefined) {
+			sessionInvalidators = this.#sessionInvalidators.get(sessionId) ?? new Set<() => Promise<void>>();
+			sessionInvalidators.add(invalidate);
+			this.#sessionInvalidators.set(sessionId, sessionInvalidators);
+		}
 		const renewLease = async (): Promise<boolean> => {
 			if (renewalLost || workGeneration !== this.#workGeneration) {
 				renewalLost = true;
@@ -2136,6 +2174,8 @@ export class DiscordNotificationDaemon {
 		} finally {
 			clearInterval(timer);
 			this.#workInvalidators.delete(invalidate);
+			if (sessionId !== undefined && sessionInvalidators !== undefined)
+				this.#removeSessionInvalidator(sessionId, sessionInvalidators, invalidate);
 		}
 	}
 

package/src/sdk/bus/index.ts

@@ -374,6 +374,8 @@ export type LifecycleErrorReason =
 	| "spawn_failed"
 	| "discovery_timeout"
 	| "readiness_timeout"
+	| "worktree_preparation_timeout"
+	| "dependency_preparation_timeout"
 	| "close_refused"
 	| "not_found"
 	| "terminal_uncertain"
@@ -1223,6 +1225,8 @@ interface SessionRuntime {
 	disposeGateTerminalController: () => void;
 	disposeAckRecoveryParticipant: () => void;
 	disposeGateEmitterListener: () => void;
+	/** Deregisters this session's job-fold listener (`bash_folded`). */
+	disposeFoldListener: () => void;
 	/** Aborts and fences side turns while notification delivery is disabled. */
 	disableEphemeralTurns: () => void;
 	waitForGateResolutionQuiescence: () => Promise<void>;
@@ -2384,6 +2388,7 @@ function sdkQuerySurface(
 	steerStatusLookup: (selector: { commandId?: string; turnId?: string; clientRef?: string }) => unknown = () => ({
 		status: "unknown",
 	}),
+	getRuntimeHost: () => SessionSdkHost | undefined = () => undefined,
 ): SessionSurface {
 	return createSdkSurfaceFactory({
 		ctx,
@@ -2396,6 +2401,7 @@ function sdkQuerySurface(
 		turnResultLookup,
 		steerStatusLookup,
 		hostTools: () => getInstalledDefinitions("host_tools") !== undefined,
+		getRuntimeHost,
 	}).query;
 }
 
@@ -3522,7 +3528,7 @@ function sdkControlSurface(
 		setQueueMode: (kind, mode) => {
 			if (!bindings.has("setQueueMode"))
 				return unavailable(`queue.${kind}_mode.set`, "no session queue-mode seam is installed")();
-			if (!ctx.setQueueMode(kind as "steering" | "follow_up" | "interrupt", mode))
+			if (!ctx.setQueueMode(kind as "steering" | "follow_up" | "tool_interrupt", mode))
 				throw Object.assign(new Error("Invalid queue mode."), { code: "invalid_input" });
 			return { changed: true };
 		},
@@ -4378,8 +4384,14 @@ export function createNotificationsExtension(
 			rt.workflowGate?.setRuntimeTurnProvider?.(null);
 		} catch {}
 		try {
+			const attachedClients = rt.server.clientCount();
 			const delivered = await pushTerminalSessionFrame(rt, { type: "session_closed", sessionId: id });
-			if (!delivered) logger.warn("notifications: session_closed socket delivery was not acknowledged");
+			if (!delivered) {
+				const fields = { sessionId: id, endpointScope: rt.endpointScope, attachedClients };
+				if (attachedClients > 0)
+					logger.warn("notifications: session_closed socket delivery was not acknowledged", fields);
+				else logger.debug("notifications: session_closed had no attached client to acknowledge", fields);
+			}
 		} catch (e) {
 			logger.warn(`notifications: session_closed failed: ${String(e)}`);
 		}
@@ -4390,6 +4402,9 @@ export function createNotificationsExtension(
 		try {
 			rt.disposeGateEmitterListener();
 		} catch {}
+		try {
+			rt.disposeFoldListener();
+		} catch {}
 		rt.gatePresentations?.dispose();
 		try {
 			rt.disposeGateTerminalController();
@@ -5282,7 +5297,6 @@ export function createNotificationsExtension(
 					submission.reconciliationKind,
 					correlation,
 					winner,
-					undefined,
 					extra?.error,
 					extra?.finalText,
 				);
@@ -5454,6 +5468,7 @@ export function createNotificationsExtension(
 				settings,
 				selector => kindReconciliation.lookupResult(selector.kind, selector),
 				selector => kindReconciliation.lookupSteer(selector),
+				() => host,
 			),
 			id,
 			revisions,
@@ -6985,6 +7000,7 @@ export function createNotificationsExtension(
 				]);
 			},
 			disposeGateEmitterListener: () => {},
+			disposeFoldListener: () => {},
 			trackGateResolution,
 			waitForGateResolutionQuiescence: async () => {
 				await Promise.allSettled(inFlightGateResolutions);
@@ -8009,6 +8025,20 @@ export function createNotificationsExtension(
 			};
 			activeRuntime.disposeGateEmitterListener = registerWorkflowGateEmitterListener(id, attachWorkflowGate);
 			if (ctx.workflowGate) attachWorkflowGate(ctx.workflowGate);
+			// Every fold (steer, chord, auto-background timer, `bash.background`)
+			// publishes one replayable `bash_folded` frame. `runtime.jobs.list`
+			// `foldReason` remains the source of truth clients reconcile against after
+			// a replay, since a replayed frame may describe a job that has since ended.
+			activeRuntime.disposeFoldListener =
+				ctx.onJobFold?.(event => {
+					emitSessionEvent(activeRuntime, {
+						type: "bash_folded",
+						sessionId: id,
+						jobId: event.jobId,
+						generation: event.generation,
+						reason: event.reason,
+					});
+				}) ?? (() => {});
 			finishStartup({ status: "started", runtime: initializedRuntime });
 			return { status: "started", runtime: initializedRuntime };
 		} catch (e) {