@gajae-code/coding-agent 0.16.1 → 0.16.4

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

@@ -136,7 +136,7 @@ export type ChatDaemonAction = "stop" | "reload";
  */
 export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
 	discord: 73,
-	slack: 77,
+	slack: 79,
 };
 
 export function chatDaemonGeneration(kind: ChatDaemonKind): number {

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

@@ -92,6 +92,36 @@ function isReservedIdentity(name: string | undefined): boolean {
 	return isLifecycleEvent(name) || isControlPlaneFrameType(name);
 }
 
+/**
+ * Chat notifications in lean mode are an answer surface, not a mirror of the
+ * session protocol. Lifecycle, identity, and activity frames remain available
+ * to verbose consumers, while finalized answers and action-needed events are
+ * delivered in lean mode.
+ */
+export function shouldPublishChatFrame(
+	frame: Record<string, unknown>,
+	verbosity: "lean" | "verbose" | undefined,
+): boolean {
+	if (verbosity !== "lean") return frame.type !== "turn_stream" || frame.phase !== "live";
+	return frame.type === "turn_stream" && frame.phase === "finalized" && frame.finalAnswer === true;
+}
+
+/**
+ * A final answer's message ref identifies its one rendered message even when
+ * the SDK transport delivers an unpositioned duplicate frame.
+ */
+export function publicationIdForFinalChatAnswer(sessionId: string, frame: Record<string, unknown>): string | undefined {
+	if (
+		frame.type !== "turn_stream" ||
+		frame.phase !== "finalized" ||
+		frame.finalAnswer !== true ||
+		typeof frame.messageRef !== "string" ||
+		frame.messageRef.length === 0
+	)
+		return undefined;
+	return `turn:${sessionId}:${frame.messageRef}`;
+}
+
 /** One delivered frame reduced to a single event identity. */
 type CorrelatedFrame = SessionRouterFrame;
 
@@ -471,7 +501,14 @@ 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 () => {
@@ -564,8 +601,9 @@ export class ChatDaemonRuntime {
 		if (this.#attachments.get(attachment.sessionId) !== attachment) return;
 		await this.#attachmentBarriers.get(attachment.sessionId);
 		if (this.#attachments.get(attachment.sessionId) !== attachment) return;
-		const publicationId = correlated.publicationId;
 		const normalizedFrame = correlated.body;
+		const publicationId =
+			publicationIdForFinalChatAnswer(attachment.sessionId, normalizedFrame) ?? correlated.publicationId;
 		const bodyType = typeof normalizedFrame.type === "string" ? normalizedFrame.type : undefined;
 		if (isControlPlaneFrameType(correlated.name) || isControlPlaneFrameType(bodyType)) return;
 		if (normalizedFrame.type === "turn_stream" && normalizedFrame.phase === "live") return;
@@ -600,6 +638,11 @@ export class ChatDaemonRuntime {
 			return;
 		}
 		if (!notification) return;
+		if (
+			notification.type === "frame" &&
+			!shouldPublishChatFrame(normalizedFrame, this.input.config.presentation?.verbosity)
+		)
+			return;
 		const payload = this.#presentation?.fanout(notification)[0];
 		const body = payload?.body;
 		const content =

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

@@ -58,7 +58,9 @@ function slackPublicationClientMsgId(publicationId: string): string {
 
 // Durable filesystem publication leases must outlast one event-loop and persistence turn.
 const MIN_PUBLICATION_LEASE_MS = 100;
+const INBOUND_REACTION_DEADLINE_MS = 5_000;
 const RETIREMENT_DRAIN_MS = 5_000;
+const INBOUND_REACTION = "eyes";
 
 type SlackProviderWorkScope = {
 	sessionId: string;
@@ -70,6 +72,8 @@ type SlackProviderWork = {
 	scopeKey: string;
 	invalidate(): Promise<void>;
 	abort(): void;
+	/** Best-effort work is aborted before the graceful shutdown drain. */
+	abortOnStop?: boolean;
 	terminalize(): Promise<void>;
 	settled: Promise<void>;
 };
@@ -362,6 +366,7 @@ export class SlackNotificationDaemon {
 		this.#startedGeneration = undefined;
 		if (this.#providerRunningGeneration === lifecycleGeneration) this.#providerRunningGeneration = undefined;
 		this.#clearLeaseRecoveryTimer();
+		for (const work of this.#workInvalidators) if (work.abortOnStop) work.abort();
 		if (stopProvider) this.#providerStopRequestedGenerations.add(lifecycleGeneration);
 		const providerStop = stopProvider ? Promise.resolve().then(() => this.options.provider.stop()) : undefined;
 		const providerStopResult = providerStop?.then(
@@ -449,6 +454,7 @@ export class SlackNotificationDaemon {
 
 	/** Accepted inbound effects are durably claimed before their Socket Mode ACK. */
 	async handleEnvelope(envelope: SlackSocketEnvelope): Promise<boolean> {
+		const lifecycleGeneration = this.#lifecycleGeneration;
 		if (!text(envelope.envelope_id)) return false;
 		const inbound = messageFromEnvelope(envelope.payload);
 		if (!inbound || inbound.teamId !== this.options.teamId || inbound.channelId !== this.options.channelId) {
@@ -479,6 +485,15 @@ export class SlackNotificationDaemon {
 		this.#inflightInbound.add(inflightKey);
 		try {
 			await this.options.provider.ack(envelope.envelope_id);
+			const messageTs = text(inbound.event.ts);
+			if (messageTs)
+				this.#scheduleInboundReaction(
+					claim.sessionId,
+					claim.endpoint,
+					inbound.channelId,
+					messageTs,
+					lifecycleGeneration,
+				);
 			return await this.#dispatchInbound(claim);
 		} finally {
 			this.#inflightInbound.delete(inflightKey);
@@ -491,6 +506,76 @@ export class SlackNotificationDaemon {
 		return work.finally(() => this.#activeWork.delete(work));
 	}
 
+	/** Track the best-effort acknowledgement in the owning attachment's provider-work scope. */
+	#scheduleInboundReaction(
+		sessionId: string,
+		endpoint: SessionAttachment,
+		channel: string,
+		timestamp: string,
+		lifecycleGeneration: number,
+	): void {
+		const scope: SlackProviderWorkScope = {
+			sessionId,
+			endpointGeneration: endpoint.generation,
+			...(endpoint.authorityId === undefined ? {} : { attachmentAuthorityId: endpoint.authorityId }),
+		};
+		const scopeKey = slackProviderWorkScopeKey(scope);
+		const workGeneration = this.#workGeneration;
+		const controller = new AbortController();
+		const settled = Promise.withResolvers<void>();
+		let abortKind: "deadline" | "lifecycle" | undefined;
+		const abort = (kind: "deadline" | "lifecycle"): void => {
+			abortKind ??= kind;
+			controller.abort();
+		};
+		const work: SlackProviderWork = {
+			scopeKey,
+			invalidate: async () => abort("lifecycle"),
+			abort: () => abort("lifecycle"),
+			abortOnStop: true,
+			terminalize: async () => abort("lifecycle"),
+			settled: settled.promise,
+		};
+		this.#workInvalidators.add(work);
+		const reaction = (async () => {
+			const deadline = setTimeout(() => abort("deadline"), INBOUND_REACTION_DEADLINE_MS);
+			try {
+				if (
+					workGeneration !== this.#workGeneration ||
+					lifecycleGeneration !== this.#lifecycleGeneration ||
+					this.#retiredProviderWorkScopes.has(scopeKey) ||
+					!endpoint.isCurrent()
+				) {
+					abort("lifecycle");
+					return;
+				}
+				await this.options.provider.addReaction({
+					channel,
+					timestamp,
+					name: INBOUND_REACTION,
+					signal: controller.signal,
+				});
+				if (abortKind === "deadline")
+					logger.warn(
+						`Slack inbound acknowledgement reaction exceeded the ${INBOUND_REACTION_DEADLINE_MS}ms deadline and was aborted.`,
+					);
+			} catch {
+				if (abortKind !== "lifecycle")
+					logger.warn(
+						abortKind === "deadline"
+							? `Slack inbound acknowledgement reaction exceeded the ${INBOUND_REACTION_DEADLINE_MS}ms deadline and was aborted.`
+							: "Slack inbound acknowledgement reaction failed.",
+					);
+			} finally {
+				clearTimeout(deadline);
+				this.#workInvalidators.delete(work);
+				settled.resolve();
+				this.#tryReleaseRetiredProviderWorkScope(scopeKey);
+			}
+		})();
+		void this.#track(reaction);
+	}
+
 	async #invalidateActiveWork(): Promise<void> {
 		this.#workGeneration += 1;
 		await Promise.allSettled([...this.#workInvalidators].map(work => work.invalidate()));
@@ -1496,7 +1581,11 @@ export class SlackNotificationDaemon {
 				updatedAt: this.#now(),
 			});
 		});
-		return sessionId && receipt ? { key, endpoint, sessionId, receipt } : undefined;
+		if (!sessionId || !receipt) {
+			await this.#journal.terminalize(effectId, { status: "rejected" });
+			return undefined;
+		}
+		return { key, endpoint, sessionId, receipt };
 	}
 
 	async #dispatchInbound(claim: {
@@ -2020,7 +2109,8 @@ export class SlackNotificationDaemon {
 				current.seenEventIds.includes(routing.eventId) ||
 				current.seenInteractionIds.includes(routing.interactionId) ||
 				current.seenRetryKeys.includes(routing.retryKey) ||
-				(routing.kind === "action" && replyableActionId(current.pendingActionId) !== routing.actionId)
+				(routing.kind === "action" && replyableActionId(current.pendingActionId) !== routing.actionId) ||
+				(routing.kind === "message" && replyableActionId(current.pendingActionId) !== undefined)
 			)
 				return current;
 			receipt = {

package/src/sdk/bus/slack-live-provider.ts

@@ -294,6 +294,18 @@ export class SlackLiveProvider implements SlackProviderClient, SlackDiagnosticPr
 		return message;
 	}
 
+	async addReaction(input: { channel: string; timestamp: string; name: string; signal?: AbortSignal }): Promise<void> {
+		await this.#api(
+			"reactions.add",
+			{
+				channel: input.channel,
+				timestamp: input.timestamp,
+				name: input.name,
+			},
+			input.signal,
+		);
+	}
+
 	async findMessageByClientMsgId(input: {
 		channel: string;
 		clientMsgId: string;

package/src/sdk/bus/slack-provider.ts

@@ -57,6 +57,7 @@ export interface SlackProviderClient {
 		threadTs?: string;
 		signal?: AbortSignal;
 	}): Promise<SlackMessageSearchResult | null>;
+	addReaction?(input: { channel: string; timestamp: string; name: string; signal?: AbortSignal }): Promise<void>;
 	/**
 	 * Prove that an operator-supplied timestamp addresses a real message in the
 	 * requested channel. Adoption of an existing root is refused when a client
@@ -108,6 +109,10 @@ export class SlackProvider {
 		return (await this.client.findMessageByClientMsgId?.(input)) ?? null;
 	}
 
+	async addReaction(input: { channel: string; timestamp: string; name: string; signal?: AbortSignal }): Promise<void> {
+		await this.client.addReaction?.(input);
+	}
+
 	/** Fail-closed root verification: a client without this capability can never confirm a root. */
 	async findMessageByTimestamp(input: { channel: string; ts: string }): Promise<SlackMessageSearchResult | null> {
 		return (await this.client.findMessageByTimestamp?.(input)) ?? null;

package/src/sdk/cli/rows.ts

@@ -78,6 +78,43 @@ export interface SdkTailEnvelopeV1 {
 	items: SdkTailItemV1[];
 }
 
+export function tailItemKey(item: SdkTailItemV1): string {
+	// (generation, seq) restarts per revision; without the revision two turns'
+	// first frames share "1:1" and the second is silently dropped (#5200).
+	if (item.generation !== undefined && item.seq !== undefined) {
+		if (item.revision === undefined || !Number.isSafeInteger(item.revision) || item.revision < 0)
+			throw new Error("Cannot key a positioned tail item without its authoritative revision.");
+		return `${item.kind}\u0000${item.revision}\u0000${item.generation}\u0000${item.seq}`;
+	}
+	if (item.id !== undefined) return `${item.kind}\u0000${item.id}`;
+	return `${item.kind}\u0000${JSON.stringify(item.payload)}`;
+}
+
+/** Holds positioned live frames until the checkpoint can stamp their authoritative revision. */
+export class TailRevisionBuffer {
+	#pending: SdkTailItemV1[] = [];
+	#resolved = false;
+
+	push(item: SdkTailItemV1): SdkTailItemV1[] {
+		if (item.revision !== undefined || item.generation === undefined || item.seq === undefined) return [item];
+		if (!this.#resolved) {
+			this.#pending.push(item);
+			return [];
+		}
+		throw new Error("A positioned live tail item arrived without an authoritative revision after checkpoint.");
+	}
+
+	resolve(revision: number): SdkTailItemV1[] {
+		if (!Number.isSafeInteger(revision) || revision < 0)
+			throw new Error("Tail revision must be a non-negative integer.");
+		this.#resolved = true;
+		const pending = this.#pending;
+		this.#pending = [];
+		for (const item of pending) item.revision = revision;
+		return pending;
+	}
+}
+
 const SECRET_FIELD = /(?:secret|token|password|credential|authorization|api[_-]?key)/i;
 
 /** Recursively removes secret-shaped fields (defense in depth for DTO output). */
@@ -228,12 +265,20 @@ export function toTailItemV1(
 	const item: SdkTailItemV1 = {
 		kind,
 		...(payloadId !== undefined ? { id: payloadId } : id !== undefined ? { id } : {}),
-		...(typeof value.revision === "number" ? { revision: value.revision } : {}),
+		...(typeof value.revision === "number" && Number.isSafeInteger(value.revision) && value.revision >= 0
+			? { revision: value.revision }
+			: {}),
 		...(typeof value.generation === "number" ? { generation: value.generation } : {}),
 		...(typeof value.seq === "number" ? { seq: value.seq } : {}),
 		payload: stripSecretFields(payload),
 	};
-	if (fallback.revision !== undefined && item.revision === undefined) item.revision = fallback.revision;
+	if (
+		fallback.revision !== undefined &&
+		Number.isSafeInteger(fallback.revision) &&
+		fallback.revision >= 0 &&
+		item.revision === undefined
+	)
+		item.revision = fallback.revision;
 	if (fallback.generation !== undefined && item.generation === undefined) item.generation = fallback.generation;
 	if (fallback.seq !== undefined && item.seq === undefined) item.seq = fallback.seq;
 	return item;

package/src/sdk/cli/session-cli.ts

@@ -38,10 +38,13 @@ import { SESSION_REQUEST_TIMEOUT_MS } from "../session-reconnect";
 import {
 	type SdkCheckpointRecordV1,
 	type SdkRetentionGapV1,
+	type SdkRingPositionV1,
 	type SdkSessionRowV1,
 	type SdkTailItemV1,
 	SESSION_ROWS_VERSION,
 	stripSecretFields,
+	TailRevisionBuffer,
+	tailItemKey,
 	toCheckpointRecordV1,
 	toRetentionGapV1,
 	toSessionRowV1,
@@ -331,13 +334,14 @@ function throwResponseFailure(response: unknown): void {
 async function paginatedSessionList(
 	router: SessionRouter,
 	input: JsonRecord = {},
-	requestKey = `${SDK_SESSION_CLI_LIFECYCLE_ACTOR.namespace}:session.list`,
+	requestKey = `${SDK_SESSION_CLI_LIFECYCLE_ACTOR.namespace}:session.list:${randomBytes(12).toString("hex")}`,
 ): Promise<unknown> {
 	try {
 		const pages = await traverseSessionList(
 			input,
 			async pageInput => {
-				const response = object(await router.listBrokerSessions(pageInput, requestKey));
+				const cursor = typeof pageInput.cursor === "string" ? pageInput.cursor : "initial";
+				const response = object(await router.listBrokerSessions(pageInput, `${requestKey}:${cursor}`));
 				if (response?.ok === false) {
 					const failure = object(response.error);
 					throw new SdkClientError(
@@ -372,10 +376,10 @@ type SessionRows = {
 	sessions: SdkSessionRowV1[];
 };
 
-async function sessionRows(agentDir: string): Promise<SessionRows> {
+async function sessionRows(agentDir: string, input: JsonRecord = {}): Promise<SessionRows> {
 	await ensureBroker({ agentDir });
 	return await withRouter(agentDir, async router => {
-		const response = await paginatedSessionList(router);
+		const response = await paginatedSessionList(router, input);
 		const result = resultObject(response) ?? {};
 		let sessions: SdkSessionRowV1[];
 		try {
@@ -686,7 +690,7 @@ async function runList(agentDir: string, args: SdkSessionCliArgs): Promise<unkno
 }
 
 async function runInspect(agentDir: string, sessionId: string): Promise<unknown> {
-	const listing = await sessionRows(agentDir);
+	const listing = await sessionRows(agentDir, { resolveSessionId: sessionId });
 	const session = listing.sessions.find(candidate => candidate.sessionId === sessionId);
 	if (!session)
 		throw new SdkSessionCliError("session_unavailable", `Session ${sessionId} is not indexed by the broker.`, 1);
@@ -985,13 +989,6 @@ function extractTranscriptPage(response: unknown): { items: unknown[]; complete:
 	};
 }
 
-function tailItemKey(item: SdkTailItemV1): string {
-	if (item.generation !== undefined && item.seq !== undefined)
-		return `${item.kind}\u0000${item.generation}\u0000${item.seq}`;
-	if (item.id !== undefined) return `${item.kind}\u0000${item.id}`;
-	return `${item.kind}\u0000${JSON.stringify(item.payload)}`;
-}
-
 function mergeTailItems(
 	target: SdkTailItemV1[],
 	seen: Set<string>,
@@ -1006,8 +1003,9 @@ function mergeTailItems(
 	}
 }
 
-/** Canonical ring position of an event item, when the host stated one. */
-type TailSeqKey = { generation: number; seq: number };
+/** Canonical session-wide ring position of an event item, when the host stated one. */
+type TailSeqKey = SdkRingPositionV1;
+type TailLocalPosition = Pick<SdkRingPositionV1, "generation" | "seq">;
 
 function isPositionCoordinate(value: unknown): value is number {
 	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
@@ -1057,7 +1055,7 @@ function classifyRawEventPosition(event: unknown): "unpositioned" | "malformed"
  * it is never silently downgraded to unpositioned. Claiming neither coordinate
  * is a genuine unpositioned event.
  */
-function classifyTailPosition(item: SdkTailItemV1): TailSeqKey | "unpositioned" | "malformed" {
+function classifyTailPosition(item: SdkTailItemV1): TailLocalPosition | "unpositioned" | "malformed" {
 	if (item.generation === undefined && item.seq === undefined) return "unpositioned";
 	if (!isPositionCoordinate(item.generation) || !isPositionCoordinate(item.seq)) return "malformed";
 	return { generation: item.generation, seq: item.seq };
@@ -1065,10 +1063,13 @@ function classifyTailPosition(item: SdkTailItemV1): TailSeqKey | "unpositioned"
 
 function tailSeqKey(item: SdkTailItemV1): TailSeqKey | undefined {
 	const position = classifyTailPosition(item);
-	return typeof position === "string" ? undefined : position;
+	return typeof position === "string" || !isPositionCoordinate(item.revision)
+		? undefined
+		: { revision: item.revision, ...position };
 }
 
 function compareTailSeqKeys(left: TailSeqKey, right: TailSeqKey): number {
+	if (left.revision !== right.revision) return left.revision - right.revision;
 	return left.generation !== right.generation ? left.generation - right.generation : left.seq - right.seq;
 }
 
@@ -1112,10 +1113,12 @@ function mergeEventTailItems(
 			target.unpositioned.push(item);
 			continue;
 		}
+		const orderedPosition = tailSeqKey(item);
+		if (orderedPosition === undefined) throw new Error("A positioned tail item has no authoritative revision.");
 		let index = target.positioned.length;
 		for (; index > 0; index--) {
 			const previous = tailSeqKey(target.positioned[index - 1]!);
-			if (previous === undefined || compareTailSeqKeys(previous, position) <= 0) break;
+			if (previous === undefined || compareTailSeqKeys(previous, orderedPosition) <= 0) break;
 		}
 		target.positioned.splice(index, 0, item);
 	}
@@ -1158,11 +1161,13 @@ function tailItemFromRouterFrame(frame: SessionRouterFrame): SdkTailItemV1 | und
 	return toTailItemV1(
 		{
 			kind: frame.name,
+			...(frame.revision === undefined ? {} : { revision: frame.revision }),
 			...(seq === undefined ? {} : { generation: frame.generation, seq }),
 			payload: frame.body,
 		},
 		{
 			kind: frame.name,
+			...(frame.revision === undefined ? {} : { revision: frame.revision }),
 			...(seq === undefined ? {} : { generation: frame.generation, seq }),
 		},
 	);
@@ -1406,6 +1411,7 @@ async function runLiveTail(
 	// evidence.
 	const seenTranscript = new Set<string>();
 	const seenEvents = new Set<string>();
+	const liveRevisionBuffer = new TailRevisionBuffer();
 	let checkpoint: SdkCheckpointRecordV1 | undefined;
 	let gap: SdkRetentionGapV1 | undefined;
 	let liveReason: TailExitReason | undefined;
@@ -1445,7 +1451,7 @@ async function runLiveTail(
 				// close at a contested position win instead of failing closed, and
 				// checking it after the monotonic guard would silently skip a
 				// conflicting kind at an already-decided position.
-				const positionKey = `${position.generation}\u0000${position.seq}`;
+				const positionKey = `${position.revision}\u0000${position.generation}\u0000${position.seq}`;
 				const claimed = claimedLifecycleKinds.get(positionKey);
 				if (claimed !== undefined && claimed !== item.kind) {
 					malformed ??= new SdkSessionCliError(
@@ -1487,9 +1493,17 @@ async function runLiveTail(
 		if (attachment.sessionId !== sessionId) return;
 		const item = tailItemFromRouterFrame(frame);
 		if (!item) return;
-		if (item.revision === undefined && checkpoint?.revision !== undefined) item.revision = checkpoint.revision;
-		// If checkpoint was undefined, queue for later stamping? For now leave without rev
-		applyLifecycle(mergeEventTailItems(eventItems, seenEvents, [item], include));
+		try {
+			applyLifecycle(mergeEventTailItems(eventItems, seenEvents, liveRevisionBuffer.push(item), include));
+		} catch (error) {
+			malformed ??= new SdkSessionCliError(
+				"protocol_error",
+				error instanceof Error ? error.message : "A live tail item had no authoritative revision.",
+				1,
+				{ sessionId, kind: item.kind, generation: item.generation, seq: item.seq },
+			);
+			rejectLive?.(malformed);
+		}
 	};
 
 	return await withRouter(
@@ -1511,6 +1525,10 @@ async function runLiveTail(
 			const extraction = extractCheckpoint(checkpointResponse);
 			checkpoint = extraction.record;
 			gap = extraction.gap;
+			if (checkpoint !== undefined)
+				applyLifecycle(
+					mergeEventTailItems(eventItems, seenEvents, liveRevisionBuffer.resolve(checkpoint.revision), include),
+				);
 			if (gap !== undefined && args.strict === true)
 				throw new SdkSessionCliError(
 					"retention_gap",
@@ -1595,7 +1613,11 @@ async function runLiveTail(
 			applyLifecycle(mergeEventTailItems(eventItems, seenEvents, replayItems, include));
 			if (malformed !== undefined) throw malformed;
 			if (checkpoint !== undefined) {
-				const checkpointKey = { generation: checkpoint.generation, seq: checkpoint.seq };
+				const checkpointKey = {
+					revision: checkpoint.revision,
+					generation: checkpoint.generation,
+					seq: checkpoint.seq,
+				};
 				if (turnStateKey === undefined || compareTailSeqKeys(checkpointKey, turnStateKey) >= 0) {
 					turnStateKey = checkpointKey;
 					turnIdle = checkpoint.idle;
@@ -1650,7 +1672,9 @@ export async function runTail(
 	sessionId: string,
 	args: SdkSessionCliArgs,
 ): Promise<unknown> {
-	const row = (await sessionRows(agentDir)).sessions.find(candidate => candidate.sessionId === sessionId);
+	const row = (await sessionRows(agentDir, { resolveSessionId: sessionId })).sessions.find(
+		candidate => candidate.sessionId === sessionId,
+	);
 	if (!row)
 		throw new SdkSessionCliError("session_unavailable", `Session ${sessionId} is not indexed by the broker.`, 1);
 	if (row.deleted)

package/src/sdk/host/events.ts

@@ -32,11 +32,20 @@ export class SessionEventStream {
 	#frames: EventFrame[] = [];
 	readonly #ringSize: number;
 	readonly #resyncQueries: string[];
+	readonly #revisionProvider: (() => number | undefined) | undefined;
 
-	constructor(options: { generation?: number; ringSize?: number; resyncQueryIds?: string[] } = {}) {
+	constructor(
+		options: {
+			generation?: number;
+			ringSize?: number;
+			resyncQueryIds?: string[];
+			revisionProvider?: () => number | undefined;
+		} = {},
+	) {
 		this.#generation = options.generation ?? 0;
 		this.#ringSize = options.ringSize ?? 256;
 		this.#resyncQueries = options.resyncQueryIds ?? ["Q01", "Q02", "Q03"];
+		this.#revisionProvider = options.revisionProvider;
 	}
 
 	get generation(): number {
@@ -54,7 +63,21 @@ export class SessionEventStream {
 	}
 
 	emit(frame: SdkFrame): EventFrame {
-		const event: EventFrame = { ...frame, type: "event", generation: this.#generation, seq: ++this.#seq };
+		const suppliedRevision = frame.revision;
+		const providedRevision = this.#revisionProvider?.();
+		const revision =
+			typeof suppliedRevision === "number" && Number.isSafeInteger(suppliedRevision) && suppliedRevision >= 0
+				? suppliedRevision
+				: typeof providedRevision === "number" && Number.isSafeInteger(providedRevision) && providedRevision >= 0
+					? providedRevision
+					: undefined;
+		const event: EventFrame = {
+			...frame,
+			type: "event",
+			...(revision === undefined ? {} : { revision }),
+			generation: this.#generation,
+			seq: ++this.#seq,
+		};
 		this.#frames.push(event);
 		if (this.#frames.length > this.#ringSize) this.#frames.shift();
 		return event;

package/src/sdk/host/host.ts

@@ -47,6 +47,8 @@ export type SessionActivationGate = (input: { sessionId: string; generation: num
 export interface SessionSdkHostOptions extends HostEndpointAdapters {
 	control?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
 	query?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
+	/** Supplies the durable transcript revision stamped on ordinary emitted events. */
+	eventRevision?: () => number | undefined;
 	/** Test/lifecycle seam invoked synchronously before fire-and-forget dispatch. */
 	onFrameAdmitted?: (connectionId: string, frame: SdkFrame) => void;
 	/** Synchronously rejects external input while a runtime is being replaced. */
@@ -199,7 +201,7 @@ function has(frame: SdkFrame, field: string): boolean {
 
 /** Adapter-based session host; bus wiring owns NotificationServer creation and transport framing. */
 export class SessionSdkHost {
-	readonly events = new SessionEventStream();
+	readonly events: SessionEventStream;
 	readonly reverse: ReverseLeaseRuntime;
 	readonly #options: SessionSdkHostOptions;
 	#started = false;
@@ -214,6 +216,7 @@ export class SessionSdkHost {
 
 	constructor(options: SessionSdkHostOptions) {
 		this.#options = options;
+		this.events = new SessionEventStream({ revisionProvider: options.eventRevision });
 		this.reverse = new ReverseLeaseRuntime({
 			sendFrame: options.sendFrame,
 			installDefinitions: options.installProviderDefinitions,