@gajae-code/coding-agent 0.16.0 → 0.16.3

package/src/sdk/bus/reconciliation-store.ts

@@ -14,7 +14,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { PromptReconciliationStatus, SdkPromptTerminalOutcome } from "../prompt-status";
 import type { ReceiptState } from "../receipt-state";
-import { TURN_RESULT_CONTENT_MAX_BYTES, type TurnResultContent } from "../turn-result";
+import { reportableTurnResultContent, TURN_RESULT_CONTENT_MAX_BYTES, type TurnResultContent } from "../turn-result";
 import type { PromptCorrelation } from "./prompt-reconciliation";
 
 export const RECONCILIATION_STORE_VERSION = 2;
@@ -25,6 +25,16 @@ export const RECONCILIATION_DIR_NAME = ".sdk-reconciliation";
 // durable document can never match a real retry and would make the reserved key
 // invisible (and reusable for an unrelated later abort), so reload rejects it.
 const SHA256_RE = /^[0-9a-f]{64}$/;
+const SAFE_FAILURE_CODE_RE = /^[A-Za-z0-9._-]{1,64}$/;
+const DURABLE_FAILURE_MESSAGE_MAX_BYTES = 4_096;
+
+function isSafeFailureDiagnostic(value: unknown): value is { code: string; message: string } {
+	if (!isRecord(value) || typeof value.code !== "string" || !SAFE_FAILURE_CODE_RE.test(value.code)) return false;
+	return (
+		typeof value.message === "string" &&
+		new TextEncoder().encode(value.message).length <= DURABLE_FAILURE_MESSAGE_MAX_BYTES
+	);
+}
 
 export function resolveReconciliationSessionFile(
 	sessionFile: string | undefined | null,
@@ -207,11 +217,7 @@ function isValidRecord(value: unknown): boolean {
 		const settled = value.status !== "dispatching";
 		if (settled !== (typeof value.settledAt === "number" && Number.isFinite(value.settledAt))) return false;
 		if ((value.status === "rejected" || value.status === "uncertain") !== (value.error !== undefined)) return false;
-		if (
-			value.error !== undefined &&
-			(!isRecord(value.error) || typeof value.error.code !== "string" || typeof value.error.message !== "string")
-		)
-			return false;
+		if (value.error !== undefined && !isSafeFailureDiagnostic(value.error)) return false;
 		return value.receiptState === undefined && value.outcome === undefined;
 	}
 	if (kind !== "prompt" && kind !== "skill") return false;
@@ -274,8 +280,7 @@ function isValidRecord(value: unknown): boolean {
 			return false;
 	}
 	if (value.error !== undefined) {
-		if (!isRecord(value.error)) return false;
-		if (typeof value.error.code !== "string" || typeof value.error.message !== "string") return false;
+		if (!isSafeFailureDiagnostic(value.error)) return false;
 	}
 	return [outcome, pendingOutcome].every(candidate => {
 		if (candidate === undefined) return true;
@@ -286,12 +291,13 @@ function isValidRecord(value: unknown): boolean {
 					candidate.reason as string,
 				) && ["agent", "client_cancel"].includes(candidate.provenance as string)
 			);
-		return (
-			candidate.kind === "failed" &&
-			["prompt_failed", "prompt_deadline_exceeded"].includes(candidate.code as string) &&
-			typeof candidate.message === "string" &&
-			["agent_failed", "deadline"].includes(candidate.provenance as string)
-		);
+		if (
+			candidate.kind !== "failed" ||
+			!["prompt_failed", "prompt_deadline_exceeded"].includes(candidate.code as string) ||
+			!["agent_failed", "deadline"].includes(candidate.provenance as string)
+		)
+			return false;
+		return isSafeFailureDiagnostic({ code: candidate.code, message: candidate.message });
 	});
 }
 /** Terminal scope validation: bounded origin/fence/settlement fields only. */
@@ -361,8 +367,9 @@ function isValidTerminalScope(value: unknown): boolean {
 		responseState !== "failed"
 	)
 		return false;
-	if (typeof responsePayloadHash !== "string" || !responsePayloadHash) return false;
-	if (replayPayloadHash !== undefined && (typeof replayPayloadHash !== "string" || !replayPayloadHash)) return false;
+	if (typeof responsePayloadHash !== "string" || !SHA256_RE.test(responsePayloadHash)) return false;
+	if (replayPayloadHash !== undefined && (typeof replayPayloadHash !== "string" || !SHA256_RE.test(replayPayloadHash)))
+		return false;
 	if (typeof idempotencyKeyHash !== "string" || !SHA256_RE.test(idempotencyKeyHash)) return false;
 	if (typeof idempotencyInputHash !== "string" || !SHA256_RE.test(idempotencyInputHash)) return false;
 	if (terminalPublished !== undefined && typeof terminalPublished !== "boolean") return false;
@@ -406,12 +413,12 @@ function isValidEvictedTerminalKeyEntry(value: unknown): value is EvictedTermina
 		return false;
 	if (
 		value.responsePayloadHash !== undefined &&
-		(typeof value.responsePayloadHash !== "string" || !value.responsePayloadHash)
+		(typeof value.responsePayloadHash !== "string" || !SHA256_RE.test(value.responsePayloadHash))
 	)
 		return false;
 	if (
 		value.replayPayloadHash !== undefined &&
-		(typeof value.replayPayloadHash !== "string" || !value.replayPayloadHash)
+		(typeof value.replayPayloadHash !== "string" || !SHA256_RE.test(value.replayPayloadHash))
 	)
 		return false;
 	if (value.terminalPublished !== undefined && typeof value.terminalPublished !== "boolean") return false;
@@ -550,6 +557,14 @@ export function settleProcessRestart(
 	records: DurableReconciliationRecord[],
 	now: number,
 ): DurableReconciliationRecord[] {
+	const isDeadlineOutcome = (outcome: SdkPromptTerminalOutcome | undefined): boolean =>
+		outcome?.kind === "failed" && outcome.provenance === "deadline";
+	const providerFailureOutcome = (error: { code: string; message: string }): SdkPromptTerminalOutcome => ({
+		kind: "failed",
+		code: "prompt_failed",
+		message: error.message,
+		provenance: "agent_failed",
+	});
 	return records.map(record => {
 		if (record.kind === "steer") {
 			if (record.status !== "dispatching") return record;
@@ -569,29 +584,38 @@ export function settleProcessRestart(
 			return record;
 		}
 		if (record.pendingOutcome !== undefined || record.kind === "prompt") {
+			const { pendingOutcome, pendingReceiptState, ...settledRecord } = record;
+			const providerErrorRecord = record.error;
+			const providerError =
+				providerErrorRecord !== undefined && providerErrorRecord.code !== "prompt_deadline_exceeded";
+			const preserveProviderError = providerError;
 			const outcome: SdkPromptTerminalOutcome =
-				record.error !== undefined && record.pendingOutcome?.kind !== "failed"
-					? {
-							kind: "failed",
-							code: "prompt_failed",
-							message: record.error.message,
-							provenance: "agent_failed",
-						}
-					: (record.pendingOutcome ?? {
+				providerError &&
+				(pendingOutcome === undefined || isDeadlineOutcome(pendingOutcome) || pendingOutcome.kind === "stopped")
+					? providerFailureOutcome(providerErrorRecord)
+					: (pendingOutcome ?? {
 							kind: "failed",
 							code: "prompt_failed",
 							message: "Prompt did not complete before process restart.",
 							provenance: "agent_failed",
 						});
+			const preservedError =
+				providerError && preserveProviderError
+					? providerErrorRecord
+					: outcome.kind === "failed"
+						? { code: outcome.code, message: outcome.message }
+						: undefined;
+			const receiptState = reportableTurnResultContent(record.content)
+				? "present"
+				: (pendingReceiptState ?? (outcome.kind === "stopped" ? "missing" : "unknown"));
 			return {
-				...record,
+				...settledRecord,
 				status: outcome.kind === "stopped" ? "terminal_ok" : "failed",
 				terminalAt: now,
 				outcome,
-				receiptState: record.pendingReceiptState ?? (outcome.kind === "stopped" ? "missing" : "unknown"),
-				pendingOutcome: undefined,
-				pendingReceiptState: undefined,
-				...(outcome.kind === "failed" ? { error: { code: outcome.code, message: outcome.message } } : {}),
+				receiptState,
+
+				...(preservedError !== undefined ? { error: preservedError } : { error: undefined }),
 			};
 		}
 		return {

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

@@ -6,7 +6,7 @@ export interface SlackInboundDispatchReceipt {
 	interactionId: string;
 	retryKey: string;
 	eventContext?: string;
-	kind: "action" | "command";
+	kind: "action" | "command" | "message";
 	actionId?: string;
 	/** The endpoint generation and SDK effect captured before Socket Mode ACK. */
 	endpointGeneration: number;

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

@@ -145,13 +145,14 @@ type SlackInboundRouting = {
 	interactionId: string;
 	retryKey: string;
 	eventContext?: string;
-	kind: "action" | "command";
+	kind: "action" | "command" | "message";
 	actionId?: string;
 };
 
 type SlackInboundEffectPayload =
 	| { type: "reply"; id: string; answer: string; idempotencyKey: string; routing: SlackInboundRouting }
-	| { type: "command"; content: string; idempotencyKey: string; routing: SlackInboundRouting };
+	| { type: "command"; content: string; idempotencyKey: string; routing: SlackInboundRouting }
+	| { type: "user_message"; sessionId: string; text: string; idempotencyKey: string; routing: SlackInboundRouting };
 
 type SlackRootPublication = {
 	conversation: SlackConversation;
@@ -169,7 +170,11 @@ function messageFromEnvelope(
 	| undefined {
 	if (!payload || typeof payload !== "object") return undefined;
 	const eventPayload = payload as EventsPayload;
-	if (eventPayload.type !== "events_api" || !eventPayload.event || eventPayload.event.type !== "message")
+	if (
+		(eventPayload.type !== "events_api" && eventPayload.type !== "event_callback") ||
+		!eventPayload.event ||
+		eventPayload.event.type !== "message"
+	)
 		return undefined;
 	const eventId = text(eventPayload.event_id);
 	const teamId = text(eventPayload.team_id);
@@ -191,6 +196,10 @@ function nextRecord(record: SlackConversation, update: Partial<SlackConversation
 	return normalizeSlackConversation({ ...record, ...update, generation: record.generation + 1 });
 }
 
+function replyableActionId(actionId: string | undefined): string | undefined {
+	return actionId?.startsWith("idle:") ? undefined : actionId;
+}
+
 /**
  * Slack Socket Mode notification daemon. Accepted inbound SDK effects are
  * persisted before acknowledgement, including their replay payload and captured
@@ -449,7 +458,7 @@ export class SlackNotificationDaemon {
 		const actorId = text(inbound.event.user);
 		if (
 			inbound.event.bot_id ||
-			inbound.event.subtype === "bot_message" ||
+			inbound.event.subtype !== undefined ||
 			actorId === this.options.botUserId ||
 			!actorId ||
 			!(await this.#actorAuthorized(actorId))
@@ -852,7 +861,7 @@ export class SlackNotificationDaemon {
 			publicationId === undefined
 				? undefined
 				: await this.#publicationAttempt(
-						`root:${sessionId}:${publicationId}`,
+						`root:${this.options.teamId}:${this.options.channelId}:${sessionId}:${publicationId}`,
 						clientMsgId => `root:${sessionId}:${clientMsgId}`,
 					);
 		const existing = await this.findSession(sessionId, false);
@@ -1039,16 +1048,21 @@ export class SlackNotificationDaemon {
 		return await this.#track(this.#close(sessionId, marker, true, endpointGeneration));
 	}
 
-	async recoverCleanup(sessionId: string, endpointGeneration: number): Promise<void> {
+	async recoverCleanup(sessionId: string, endpointGeneration: number, authorityId?: string): Promise<boolean> {
 		const found = await this.findSession(sessionId, true);
+		if (!found) return true;
+		if (found.record.endpointGeneration !== endpointGeneration) return true;
+		if (found.record.state === "closed_marker" || found.record.state === "error") return true;
 		if (
-			!found?.record.rootTs ||
-			found.record.state !== "active" ||
-			found.record.endpointGeneration !== endpointGeneration
+			(found.record.state === "posting_root" || found.record.state === "resumed_root") &&
+			found.record.attachmentAuthorityId === authorityId
 		)
-			return;
+			return true;
+		if (found.record.state !== "active") return false;
+		if (!found.record.rootTs) return false;
+		if (found.record.attachmentAuthorityId === authorityId && found.record.cleanupEffectId === undefined) return true;
 		const effectId = `close-marker-cleanup:${sessionId}:${found.record.clientMsgId ?? found.record.rootTs}`;
-		if (found.record.cleanupEffectId !== effectId) return;
+		if (found.record.cleanupEffectId !== effectId) return false;
 		const effect = await this.#journal.read(effectId);
 		if (!effect || (effect.state === "terminal" && !effect.receipt?.messageId && !effect.receipt?.timestamp)) {
 			await this.store.transact(found.key, current =>
@@ -1056,9 +1070,10 @@ export class SlackNotificationDaemon {
 					? nextRecord(current, { cleanupEffectId: undefined, updatedAt: this.#now() })
 					: current,
 			);
-			return;
+			return false;
 		}
 		await this.close(sessionId, "Session closed.", endpointGeneration);
+		return true;
 	}
 
 	async retireAttachment(sessionId: string, endpointGeneration: number): Promise<void> {
@@ -1209,7 +1224,7 @@ export class SlackNotificationDaemon {
 			publicationId === undefined
 				? undefined
 				: await this.#publicationAttempt(
-						`root:${sessionId}:${publicationId}`,
+						`root:${this.options.teamId}:${this.options.channelId}:${sessionId}:${publicationId}`,
 						clientMsgId => `root:${sessionId}:${clientMsgId}`,
 					);
 		return (await this.#resumeWithRootPublication(sessionId, body, endpointGeneration, rootPublication?.clientMsgId))
@@ -1389,7 +1404,10 @@ export class SlackNotificationDaemon {
 		const interactionId = text(inbound.event.client_msg_id) ?? inbound.eventId;
 		const retryKey = `${inbound.eventId}:${interactionId}`;
 		const inboundText = text(inbound.event.text);
-		const command = inboundText?.startsWith("/sdk ") ?? false;
+		if (!inboundText) return undefined;
+		const command = inboundText.startsWith("/sdk ");
+		const actionId = command ? undefined : replyableActionId(record.pendingActionId);
+		const kind: SlackInboundRouting["kind"] = command ? "command" : actionId ? "action" : "message";
 
 		const idempotencyKey = `slack:${inbound.teamId}:${inbound.channelId}:${inbound.rootTs}:${actorId}:${inbound.eventId}:${interactionId}`;
 		const effectId = `inbound:${inbound.teamId}:${inbound.channelId}:${inbound.rootTs}:${actorId}:${inbound.eventId}:${interactionId}`;
@@ -1403,21 +1421,26 @@ export class SlackNotificationDaemon {
 			actorId,
 			retryKey,
 			eventContext: inbound.eventContext,
-			kind: command ? "command" : "action",
-			...(command ? {} : record.pendingActionId ? { actionId: record.pendingActionId } : {}),
+			kind,
+			...(actionId ? { actionId } : {}),
 		};
-		const initialPayload: SlackInboundEffectPayload | undefined = command
-			? { type: "command", content: inboundText!, idempotencyKey, routing }
-			: record.pendingActionId
-				? { type: "reply", id: record.pendingActionId, answer: inboundText ?? "", idempotencyKey, routing }
-				: undefined;
+		const initialPayload: SlackInboundEffectPayload = command
+			? { type: "command", content: inboundText, idempotencyKey, routing }
+			: actionId
+				? { type: "reply", id: actionId, answer: inboundText, idempotencyKey, routing }
+				: { type: "user_message", sessionId: record.sessionId, text: inboundText, idempotencyKey, routing };
 		const existingEffect = await this.#journal.read<SlackInboundEffectPayload>(effectId);
 		const payload = existingEffect?.payload ?? initialPayload;
-		if (!payload) return undefined;
+		const dispatchKind = payload.routing.kind;
 		await this.#rescheduleAfterEffectTransition(
 			this.#journal.enqueue({
 				id: effectId,
-				kind: command ? "sdk.inbound.command" : "sdk.inbound.reply",
+				kind:
+					dispatchKind === "command"
+						? "sdk.inbound.command"
+						: dispatchKind === "action"
+							? "sdk.inbound.reply"
+							: "sdk.inbound.user_message",
 				transport: "slack",
 				sessionId: record.sessionId,
 				endpointGeneration: endpoint.generation,
@@ -1437,8 +1460,7 @@ export class SlackNotificationDaemon {
 				candidate =>
 					candidate.eventId === inbound.eventId ||
 					candidate.interactionId === interactionId ||
-					candidate.retryKey === retryKey ||
-					(inbound.eventContext !== undefined && candidate.eventContext === inbound.eventContext),
+					candidate.retryKey === retryKey,
 			);
 			if (existing) {
 				sessionId = current.sessionId;
@@ -1449,8 +1471,8 @@ export class SlackNotificationDaemon {
 				current.seenEventIds.includes(inbound.eventId) ||
 				current.seenInteractionIds.includes(interactionId) ||
 				current.seenRetryKeys.includes(retryKey) ||
-				(inbound.eventContext !== undefined && current.seenContextIds.includes(inbound.eventContext)) ||
-				(!command && !current.pendingActionId)
+				(dispatchKind === "action" && replyableActionId(current.pendingActionId) !== payload.routing.actionId) ||
+				(dispatchKind === "message" && replyableActionId(current.pendingActionId) !== undefined)
 			)
 				return current;
 			sessionId = current.sessionId;
@@ -1460,8 +1482,8 @@ export class SlackNotificationDaemon {
 				interactionId,
 				retryKey,
 				eventContext: inbound.eventContext,
-				kind: command ? "command" : "action",
-				...(command ? {} : { actionId: current.pendingActionId }),
+				kind: dispatchKind,
+				...(dispatchKind === "action" ? { actionId: payload.routing.actionId } : {}),
 				endpointGeneration: endpoint.generation,
 				...(current.attachmentAuthorityId === undefined
 					? {}
@@ -1747,7 +1769,9 @@ export class SlackNotificationDaemon {
 				effect.transport !== "slack" ||
 				effect.state === "terminal" ||
 				!effect.sessionId ||
-				(effect.kind !== "sdk.inbound.command" && effect.kind !== "sdk.inbound.reply")
+				(effect.kind !== "sdk.inbound.command" &&
+					effect.kind !== "sdk.inbound.reply" &&
+					effect.kind !== "sdk.inbound.user_message")
 			)
 				continue;
 			const adopted = await this.#adoptOrphanInbound(effect as ChatEffect<SlackInboundEffectPayload>);
@@ -1794,7 +1818,9 @@ export class SlackNotificationDaemon {
 			text(routing.interactionId) !== undefined &&
 			routing.retryKey === `${routing.eventId}:${routing.interactionId}` &&
 			(routing.eventContext === undefined || text(routing.eventContext) !== undefined) &&
-			(routing.kind === "command" || (routing.kind === "action" && text(routing.actionId) !== undefined))
+			(routing.kind === "command" ||
+				routing.kind === "message" ||
+				(routing.kind === "action" && text(routing.actionId) !== undefined))
 		);
 	}
 	#matchesInboundEffect(effect: ChatEffect<SlackInboundEffectPayload>, receipt: SlackInboundDispatchReceipt): boolean {
@@ -1828,7 +1854,11 @@ export class SlackNotificationDaemon {
 				(payload.type === "reply" &&
 					routing.kind === "action" &&
 					effect.kind === "sdk.inbound.reply" &&
-					payload.id === routing.actionId))
+					payload.id === routing.actionId) ||
+				(payload.type === "user_message" &&
+					routing.kind === "message" &&
+					effect.kind === "sdk.inbound.user_message" &&
+					payload.sessionId === effect.sessionId))
 		);
 	}
 	#sameInboundReceipt(left: SlackInboundDispatchReceipt, right: SlackInboundDispatchReceipt): boolean {
@@ -1868,7 +1898,9 @@ export class SlackNotificationDaemon {
 			if (
 				effect.transport !== "slack" ||
 				effect.state !== "terminal" ||
-				(effect.kind !== "sdk.inbound.command" && effect.kind !== "sdk.inbound.reply")
+				(effect.kind !== "sdk.inbound.command" &&
+					effect.kind !== "sdk.inbound.reply" &&
+					effect.kind !== "sdk.inbound.user_message")
 			)
 				continue;
 			const payload = effect.payload as SlackInboundEffectPayload;
@@ -1958,7 +1990,11 @@ export class SlackNotificationDaemon {
 				(payload.type === "reply" &&
 					routing.kind === "action" &&
 					effect.kind === "sdk.inbound.reply" &&
-					payload.id === routing.actionId));
+					payload.id === routing.actionId) ||
+				(payload.type === "user_message" &&
+					routing.kind === "message" &&
+					effect.kind === "sdk.inbound.user_message" &&
+					payload.sessionId === effect.sessionId));
 		let receipt: SlackInboundDispatchReceipt | undefined;
 		await this.store.transact(key, current => {
 			if (
@@ -1974,8 +2010,7 @@ export class SlackNotificationDaemon {
 				candidate =>
 					candidate.eventId === routing.eventId ||
 					candidate.interactionId === routing.interactionId ||
-					candidate.retryKey === routing.retryKey ||
-					(routing.eventContext !== undefined && candidate.eventContext === routing.eventContext),
+					candidate.retryKey === routing.retryKey,
 			);
 			if (existing) {
 				if (this.#matchesInboundEffect(effect, existing)) receipt = existing;
@@ -1985,8 +2020,7 @@ export class SlackNotificationDaemon {
 				current.seenEventIds.includes(routing.eventId) ||
 				current.seenInteractionIds.includes(routing.interactionId) ||
 				current.seenRetryKeys.includes(routing.retryKey) ||
-				(routing.eventContext !== undefined && current.seenContextIds.includes(routing.eventContext)) ||
-				(routing.kind === "action" && current.pendingActionId !== routing.actionId)
+				(routing.kind === "action" && replyableActionId(current.pendingActionId) !== routing.actionId)
 			)
 				return current;
 			receipt = {

package/src/sdk/bus/telegram-daemon-contract.ts

@@ -291,7 +291,7 @@ export const SDK_LIFECYCLE_ROUTER_PROTOCOL_VERSION = 1;
  * killing a session's mirroring after one transient rejection and must be
  * replaced across this upgrade.
  */
-export const DAEMON_GENERATION = 180;
+export const DAEMON_GENERATION = 181;
 
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 7

package/src/sdk/cli/rows.ts

@@ -41,16 +41,20 @@ export interface SdkSessionRowV1 {
 	ambiguous?: boolean;
 }
 
-export interface SdkCheckpointRecordV1 {
+export interface SdkRingPositionV1 {
 	revision: number;
 	generation: number;
 	seq: number;
 }
 
+export interface SdkCheckpointRecordV1 extends SdkRingPositionV1 {
+	idle: boolean;
+}
+
 export interface SdkRetentionGapV1 {
 	code: "retention_gap";
 	missing?: { from: number; to: number };
-	resync?: SdkCheckpointRecordV1;
+	resync?: SdkRingPositionV1;
 }
 
 /** One tail item: a retained transcript entry or a live event-ring event. */
@@ -58,6 +62,8 @@ export interface SdkTailItemV1 {
 	/** "transcript" for retained transcript entries, otherwise the event-ring kind. */
 	kind: string;
 	id?: string;
+	/** Durable revision at emission; (revision,generation,seq) is unique per session. generation:seq alone is revision-local. */
+	revision?: number;
 	generation?: number;
 	seq?: number;
 	payload: unknown;
@@ -72,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). */
@@ -165,6 +208,7 @@ export function toCheckpointRecordV1(value: unknown): SdkCheckpointRecordV1 | un
 	const revision = value.revision;
 	const generation = value.generation;
 	const seq = value.seq;
+	const idle = value.idle;
 	if (
 		typeof revision !== "number" ||
 		!Number.isSafeInteger(revision) ||
@@ -174,10 +218,11 @@ export function toCheckpointRecordV1(value: unknown): SdkCheckpointRecordV1 | un
 		generation < 0 ||
 		typeof seq !== "number" ||
 		!Number.isSafeInteger(seq) ||
-		seq < 0
+		seq < 0 ||
+		typeof idle !== "boolean"
 	)
 		return undefined;
-	return { revision, generation, seq };
+	return { revision, generation, seq, idle };
 }
 
 export function toRetentionGapV1(value: unknown): SdkRetentionGapV1 | undefined {
@@ -189,15 +234,28 @@ export function toRetentionGapV1(value: unknown): SdkRetentionGapV1 | undefined
 		if (typeof from === "number" && Number.isSafeInteger(from) && typeof to === "number" && Number.isSafeInteger(to))
 			gap.missing = { from, to };
 	}
-	const resync = toCheckpointRecordV1(value.resync);
-	if (resync !== undefined) gap.resync = resync;
+	if (isRecord(value.resync)) {
+		const { revision, generation, seq } = value.resync;
+		if (
+			typeof revision === "number" &&
+			Number.isSafeInteger(revision) &&
+			revision >= 0 &&
+			typeof generation === "number" &&
+			Number.isSafeInteger(generation) &&
+			generation >= 0 &&
+			typeof seq === "number" &&
+			Number.isSafeInteger(seq) &&
+			seq >= 0
+		)
+			gap.resync = { revision, generation, seq };
+	}
 	return gap;
 }
 
 /** Projects a transcript entry or ring event into a tail item with dedupe keys. */
 export function toTailItemV1(
 	value: unknown,
-	fallback: { kind: string; generation?: number; seq?: number },
+	fallback: { kind: string; revision?: number; generation?: number; seq?: number },
 ): SdkTailItemV1 {
 	if (!isRecord(value)) return { kind: fallback.kind, payload: stripSecretFields(value) };
 	const kind = optionalString(value.kind) ?? fallback.kind;
@@ -207,10 +265,20 @@ export function toTailItemV1(
 	const item: SdkTailItemV1 = {
 		kind,
 		...(payloadId !== undefined ? { id: payloadId } : id !== undefined ? { id } : {}),
+		...(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 &&
+		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;