@gajae-code/coding-agent 0.15.2 → 0.15.4

package/src/sdk/broker/session-index.ts

@@ -915,6 +915,91 @@ interface SessionIndexOpenGroup {
 	promise: Promise<void>;
 	closed: boolean;
 }
+
+type SessionIdentityExpectation = {
+	sessionId: string;
+	stateRoot: string;
+	endpointGeneration: number;
+	pid: number;
+	processIncarnation?: string;
+	hostIncarnation?: string;
+	endpointMtimeMs?: number;
+	lifecycleRequestId?: string;
+};
+
+function sameSessionTuple(
+	event: SessionIndexEvent,
+	expected: SessionIdentityExpectation,
+	expectedRoot: string,
+): boolean {
+	return (
+		event.sessionId === expected.sessionId &&
+		event.endpointGeneration === expected.endpointGeneration &&
+		resolveEquivalentPath(event.locator.stateRoot) === expectedRoot
+	);
+}
+
+function sameSessionIdentity(
+	event: SessionIndexEvent,
+	expected: SessionIdentityExpectation,
+	expectedRoot: string,
+): boolean {
+	return (
+		sameSessionTuple(event, expected, expectedRoot) &&
+		event.pid === expected.pid &&
+		event.processIncarnation === expected.processIncarnation &&
+		event.hostIncarnation === expected.hostIncarnation &&
+		event.endpointMtimeMs === expected.endpointMtimeMs &&
+		event.lifecycleRequestId === expected.lifecycleRequestId
+	);
+}
+
+function supersededAtForIdentity(
+	events: readonly SessionIndexEvent[],
+	expected: SessionIdentityExpectation,
+): number | undefined {
+	const expectedRoot = resolveEquivalentPath(expected.stateRoot);
+	const targetRegistration = events.findLast(
+		event => event.type === "host_registered" && sameSessionIdentity(event, expected, expectedRoot),
+	);
+	const targetAnchor =
+		targetRegistration?.indexSeq ??
+		events.find(event => sameSessionIdentity(event, expected, expectedRoot))?.indexSeq;
+	if (targetAnchor === undefined) return undefined;
+	return events
+		.filter(
+			event =>
+				event.type === "host_registered" &&
+				sameSessionTuple(event, expected, expectedRoot) &&
+				!sameSessionIdentity(event, expected, expectedRoot) &&
+				event.indexSeq > targetAnchor,
+		)
+		.map(event => event.indexSeq)
+		.sort((a, b) => a - b)[0];
+}
+
+function followsApplicableTombstone(
+	events: readonly SessionIndexEvent[],
+	candidate: SessionIndexEvent,
+	expected: SessionIdentityExpectation,
+	expectedRoot: string,
+): boolean {
+	const tombstone = events.findLast(
+		event =>
+			event.type === "session_deleted" &&
+			event.indexSeq < candidate.indexSeq &&
+			sameSessionIdentity(event, expected, expectedRoot),
+	);
+	if (tombstone === undefined) return false;
+	const reRegistration = events.findLast(
+		event =>
+			event.type === "host_registered" &&
+			event.indexSeq < candidate.indexSeq &&
+			sameSessionIdentity(event, expected, expectedRoot),
+	);
+	return reRegistration === undefined || reRegistration.indexSeq < tombstone.indexSeq;
+}
+
 export class SessionIndex {
 	static #operations = new Map<string, Promise<void>>();
 	static #openGroups = new Map<string, SessionIndexOpenGroup>();
@@ -1774,6 +1859,167 @@ export class SessionIndex {
 		return reduceEvents(this.#events, this.#policy.clock(), this.#agentDir, probedIncarnations).identities;
 	}
 
+	/** Reconstructs a receipt-bound identity even when admission superseded it. */
+	findHistoricalSessionIdentity(expected: {
+		sessionId: string;
+		stateRoot: string;
+		endpointGeneration: number;
+		pid: number;
+		processIncarnation?: string;
+		hostIncarnation?: string;
+		endpointMtimeMs?: number;
+		lifecycleRequestId?: string;
+	}): IndexedSession | undefined {
+		const expectedRoot = resolveEquivalentPath(expected.stateRoot);
+		const supersededAt = supersededAtForIdentity(this.#events, expected);
+		const matching = this.#events.filter(
+			event =>
+				(supersededAt === undefined || event.indexSeq < supersededAt) &&
+				sameSessionIdentity(event, expected, expectedRoot),
+		);
+		const latest = matching.findLast(event => event.type !== "host_heartbeat");
+		if (latest === undefined) return undefined;
+		return projectIdentity(
+			{
+				identity: identityKey(latest),
+				latest,
+				heartbeat: matching.findLast(event => event.type === "host_heartbeat"),
+			},
+			false,
+			this.#policy.clock(),
+		);
+	}
+
+	/** Returns the latest identity-bound terminal event, if retained. */
+	findSessionTerminalEvidence(
+		expected: Pick<
+			IndexedSession,
+			| "sessionId"
+			| "locator"
+			| "endpointGeneration"
+			| "pid"
+			| "processIncarnation"
+			| "hostIncarnation"
+			| "endpointMtimeMs"
+			| "lifecycleRequestId"
+		>,
+	): { type: "host_unregistered" | "session_closed" | "session_deleted"; indexSeq: number } | undefined {
+		const expectedRoot = resolveEquivalentPath(expected.locator.stateRoot);
+		const expectedIncarnation = expected.hostIncarnation ?? expected.processIncarnation;
+		const supersededAt = supersededAtForIdentity(this.#events, {
+			sessionId: expected.sessionId,
+			stateRoot: expected.locator.stateRoot,
+			endpointGeneration: expected.endpointGeneration,
+			pid: expected.pid,
+			processIncarnation: expected.processIncarnation,
+			hostIncarnation: expected.hostIncarnation,
+			endpointMtimeMs: expected.endpointMtimeMs,
+			lifecycleRequestId: expected.lifecycleRequestId,
+		});
+		const event = this.#events.findLast(
+			event =>
+				(event.type === "host_unregistered" ||
+					event.type === "session_closed" ||
+					event.type === "session_deleted") &&
+				(event.hostIncarnation ?? event.processIncarnation) === expectedIncarnation &&
+				(supersededAt === undefined || event.indexSeq < supersededAt) &&
+				!followsApplicableTombstone(
+					this.#events,
+					event,
+					{
+						sessionId: expected.sessionId,
+						stateRoot: expected.locator.stateRoot,
+						endpointGeneration: expected.endpointGeneration,
+						pid: expected.pid,
+						processIncarnation: expected.processIncarnation,
+						hostIncarnation: expected.hostIncarnation,
+						endpointMtimeMs: expected.endpointMtimeMs,
+						lifecycleRequestId: expected.lifecycleRequestId,
+					},
+					expectedRoot,
+				) &&
+				sameSessionIdentity(
+					event,
+					{
+						sessionId: expected.sessionId,
+						stateRoot: expected.locator.stateRoot,
+						endpointGeneration: expected.endpointGeneration,
+						pid: expected.pid,
+						processIncarnation: expected.processIncarnation,
+						hostIncarnation: expected.hostIncarnation,
+						endpointMtimeMs: expected.endpointMtimeMs,
+						lifecycleRequestId: expected.lifecycleRequestId,
+					},
+					expectedRoot,
+				),
+		);
+		return event &&
+			(event.type === "host_unregistered" || event.type === "session_closed" || event.type === "session_deleted")
+			? { type: event.type, indexSeq: event.indexSeq }
+			: undefined;
+	}
+
+	/** Returns the latest identity-bound session_closed evidence, even after a tombstone. */
+	findSessionClosedEvidence(
+		expected: Pick<
+			IndexedSession,
+			| "sessionId"
+			| "locator"
+			| "endpointGeneration"
+			| "pid"
+			| "processIncarnation"
+			| "hostIncarnation"
+			| "endpointMtimeMs"
+			| "lifecycleRequestId"
+		>,
+	): number | undefined {
+		const expectedRoot = resolveEquivalentPath(expected.locator.stateRoot);
+		const supersededAt = supersededAtForIdentity(this.#events, {
+			sessionId: expected.sessionId,
+			stateRoot: expected.locator.stateRoot,
+			endpointGeneration: expected.endpointGeneration,
+			pid: expected.pid,
+			processIncarnation: expected.processIncarnation,
+			hostIncarnation: expected.hostIncarnation,
+			endpointMtimeMs: expected.endpointMtimeMs,
+			lifecycleRequestId: expected.lifecycleRequestId,
+		});
+		return this.#events.findLast(
+			event =>
+				event.type === "session_closed" &&
+				(supersededAt === undefined || event.indexSeq < supersededAt) &&
+				!followsApplicableTombstone(
+					this.#events,
+					event,
+					{
+						sessionId: expected.sessionId,
+						stateRoot: expected.locator.stateRoot,
+						endpointGeneration: expected.endpointGeneration,
+						pid: expected.pid,
+						processIncarnation: expected.processIncarnation,
+						hostIncarnation: expected.hostIncarnation,
+						endpointMtimeMs: expected.endpointMtimeMs,
+						lifecycleRequestId: expected.lifecycleRequestId,
+					},
+					expectedRoot,
+				) &&
+				sameSessionIdentity(
+					event,
+					{
+						sessionId: expected.sessionId,
+						stateRoot: expected.locator.stateRoot,
+						endpointGeneration: expected.endpointGeneration,
+						pid: expected.pid,
+						processIncarnation: expected.processIncarnation,
+						hostIncarnation: expected.hostIncarnation,
+						endpointMtimeMs: expected.endpointMtimeMs,
+						lifecycleRequestId: expected.lifecycleRequestId,
+					},
+					expectedRoot,
+				),
+		)?.indexSeq;
+	}
+
 	/**
 	 * Production coalesced heartbeat checkpoint pass (C2): appends one
 	 * `host_heartbeat` per session at most once per {@link SESSION_HEARTBEAT_INTERVAL_MS}.

package/src/sdk/broker/transport.ts

@@ -14,6 +14,7 @@ const BROKER_OPERATIONS = new Set([
 	"session.resume",
 	"session.close",
 	"session.delete",
+	"session.reconcile_uncertain",
 	"broker.shutdown",
 	"session.control",
 	"broker.lookup_lifecycle",

package/src/sdk/bus/index.ts

@@ -166,6 +166,7 @@ import {
 	ASK_SELECTED_ACK_CAPABILITY,
 	type EnsureDaemonResult,
 	ensureTelegramDaemonRunningDetailed,
+	POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY,
 } from "./telegram-daemon";
 
 export type {
@@ -1176,7 +1177,10 @@ interface SessionRuntime {
 	host: SessionSdkHost;
 	/** Delivers one ring-positioned event envelope to every attached subscriber
 	 *  connection, applying the same capability gate as event replay. */
-	broadcastEventFrame: (event: SdkFrame) => void;
+	broadcastEventFrame: (event: SdkFrame) => string[];
+	/** Delivers one positioned event and returns opaque receipts only for the
+	 *  notification-effect generations that accepted it. */
+	broadcastEventFrameWithReceipts: (event: SdkFrame) => string[];
 	/** Owns stateRoot-backed revisions and removes their spills on terminal shutdown. */
 	revisions: RevisionStore;
 	/** Releases all snapshot pins before the revision store is closed. */
@@ -1403,26 +1407,39 @@ function emitSessionEvent(
 	runtime: Pick<SessionRuntime, "host" | "broadcastEventFrame">,
 	frame: { type: string; [key: string]: unknown },
 	payload: Record<string, unknown> = frame,
-): void {
-	runtime.broadcastEventFrame(runtime.host.emitEvent({ kind: frame.type, payload }));
+): string[] {
+	return runtime.broadcastEventFrame(runtime.host.emitEvent({ kind: frame.type, payload }));
+}
+
+function emitSessionEventWithReceipts(
+	runtime: Pick<SessionRuntime, "host" | "broadcastEventFrameWithReceipts">,
+	frame: { type: string; [key: string]: unknown },
+): string[] {
+	return runtime.broadcastEventFrameWithReceipts(runtime.host.emitEvent({ kind: frame.type, payload: frame }));
 }
 
 function pushSessionFrame(
 	runtime: Pick<SessionRuntime, "server" | "host" | "broadcastEventFrame">,
 	frame: { type: string; [key: string]: unknown },
-): void {
-	emitSessionEvent(runtime, frame);
+): boolean {
+	const positionedRecipients = emitSessionEvent(runtime, frame);
 	if (frame.type === "turn_stream") {
-		runtime.server.pushTurnStreamUnchecked(
+		const rawAccepted = runtime.server.pushTurnStreamUnchecked(
 			String(frame.sessionId),
 			frame.phase === "live" ? "live" : "finalized",
 			String(frame.text),
 			typeof frame.finalAnswer === "boolean" ? frame.finalAnswer : undefined,
 			typeof frame.messageRef === "string" ? frame.messageRef : undefined,
+			positionedRecipients,
 		);
-		return;
+		// A retained lean settlement may be consumed only after either the
+		// positioned or legacy raw transport accepts the lead-in. Older native addons
+		// return undefined here, which deliberately fails closed unless the
+		// positioned leg has already proved acceptance.
+		return positionedRecipients.length > 0 || rawAccepted === true;
 	}
-	runtime.server.pushFrame(JSON.stringify(frame));
+	runtime.server.pushFrame(JSON.stringify(frame), positionedRecipients);
+	return positionedRecipients.length > 0;
 }
 
 async function pushTerminalSessionFrame(
@@ -1430,6 +1447,9 @@ async function pushTerminalSessionFrame(
 	frame: { type: "session_closed"; sessionId: string },
 ): Promise<boolean> {
 	emitSessionEvent(runtime, frame);
+	// Terminal shutdown still uses the acknowledged native leg: the positioned
+	// send is best-effort and the server must not stop before a socket writer has
+	// settled this final frame.
 	return await runtime.server.pushFrameAndWait(JSON.stringify(frame), 1_000);
 }
 
@@ -1438,8 +1458,15 @@ function pushFileAttachment(
 	frame: { type: "file_attachment"; sessionId: string; name: string; mime?: string; caption?: string },
 	data: Buffer,
 ): void {
-	emitSessionEvent(runtime, frame, { ...frame, data: data.toString("base64") });
-	runtime.server.pushFileAttachmentUnchecked(frame.sessionId, frame.name, frame.mime, data, frame.caption);
+	const positionedRecipients = emitSessionEvent(runtime, frame, { ...frame, data: data.toString("base64") });
+	runtime.server.pushFileAttachmentUnchecked(
+		frame.sessionId,
+		frame.name,
+		frame.mime,
+		data,
+		frame.caption,
+		positionedRecipients,
+	);
 }
 
 /** Agent lifecycle is SDK session truth, independent of optional chat delivery. */
@@ -1449,8 +1476,8 @@ function emitAgentLifecycle(
 ): void {
 	try {
 		const json = JSON.stringify(frame);
-		emitSessionEvent(runtime, frame);
-		runtime.server.pushFrame(json);
+		const positionedRecipients = emitSessionEvent(runtime, frame);
+		runtime.server.pushFrame(json, positionedRecipients);
 	} catch (error) {
 		logger.warn(`sdk: lifecycle delivery failed: ${String(error)}`);
 	}
@@ -4743,20 +4770,41 @@ export function createNotificationsExtension(
 		 * or an event replay, which is exactly the attached-subscriber set. Fenced
 		 * connections are excluded like their inbound frames, and capability-gated
 		 * kinds follow the same gate replay applies, so live and replay delivery
-		 * stay one truth per connection.
+		 * stay one truth per connection. Only notification adapters that explicitly
+		 * negotiate positioned-only effects are returned for matching raw exclusion;
+		 * ordinary direct SDK subscribers retain both public surfaces from #4570.
 		 */
-		const broadcastEventFrame = (event: SdkFrame): void => {
+		const broadcastEventFrame = (event: SdkFrame): string[] => {
 			const gated = CAP_GATED_FRAME_KINDS.has(String(event.kind));
 			const json = JSON.stringify(event);
+			const recipients: string[] = [];
 			for (const [connectionId, capabilities] of hostCapCache) {
 				if (fencedConnections.has(connectionId)) continue;
 				if (gated && !capabilities.has(TOOL_ACTIVITY_CAPABILITY)) continue;
 				try {
 					server.sendTo(connectionId, json);
+					if (capabilities.has(POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY)) recipients.push(connectionId);
 				} catch {
 					// Broadcasts are best effort; directed responses surface send failures.
 				}
 			}
+			return recipients;
+		};
+		const broadcastEventFrameWithReceipts = (event: SdkFrame): string[] => {
+			const gated = CAP_GATED_FRAME_KINDS.has(String(event.kind));
+			const json = JSON.stringify(event);
+			const receipts: string[] = [];
+			for (const [connectionId, capabilities] of hostCapCache) {
+				if (fencedConnections.has(connectionId)) continue;
+				if (gated && !capabilities.has(TOOL_ACTIVITY_CAPABILITY)) continue;
+				try {
+					const receipt = server.sendToWithReceipt(connectionId, json);
+					if (capabilities.has(POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY)) receipts.push(receipt);
+				} catch {
+					// Rejected positioned sends remain eligible for the atomic raw fallback.
+				}
+			}
+			return receipts;
 		};
 		let cancelPreflightsForConnection: ((connectionId: string) => Promise<void>) | undefined;
 		const promptTerminalTombstones = new Map<string, { connectionId: string; expiresAt: number }>();
@@ -6836,6 +6884,7 @@ export function createNotificationsExtension(
 			server,
 			host,
 			broadcastEventFrame,
+			broadcastEventFrameWithReceipts,
 			revisions,
 			cursors,
 			id,
@@ -7109,6 +7158,19 @@ export function createNotificationsExtension(
 					"@gajae-code/natives is out of date: missing onNegotiatedCapabilities. Rebuild the native addon (bun --cwd=packages/natives run build).",
 				);
 			}
+			if (
+				typeof server.supportsPositionedRawExclusion !== "function" ||
+				server.supportsPositionedRawExclusion() !== true
+			) {
+				throw new Error(
+					"@gajae-code/natives is out of date: missing positioned raw-fan-out exclusion. Rebuild the native addon (bun --cwd=packages/natives run build).",
+				);
+			}
+			if (typeof server.sendToWithReceipt !== "function" || typeof server.queueIdleAfterDirected !== "function") {
+				throw new Error(
+					"@gajae-code/natives is out of date: missing recipient-bound dependent delivery. Rebuild the native addon (bun --cwd=packages/natives run build).",
+				);
+			}
 			server.onNegotiatedCapabilities((_err, connectionId, capabilities) => {
 				if (connectionId) hostCapCache.set(connectionId, new Set(capabilities));
 			});
@@ -7670,8 +7732,8 @@ export function createNotificationsExtension(
 					sessionId: id,
 					...buildIdentity(ctx.cwd, sessionName, telegramTopicsEnabled()),
 				};
-				emitSessionEvent(initializedRuntime, identity);
-				server.pushFrame(JSON.stringify(identity));
+				const positionedRecipients = emitSessionEvent(initializedRuntime, identity);
+				server.pushFrame(JSON.stringify(identity), positionedRecipients);
 			}, 250);
 			sessionNameObserver.unref?.();
 			runtime.stopSessionNameObserver = () => clearInterval(sessionNameObserver);
@@ -7684,8 +7746,8 @@ export function createNotificationsExtension(
 					sessionId: id,
 					...buildIdentity(ctx.cwd, sessionNameAfterStartup, telegramTopicsEnabled()),
 				};
-				emitSessionEvent(initializedRuntime, identity);
-				server.pushFrame(JSON.stringify(identity));
+				const positionedRecipients = emitSessionEvent(initializedRuntime, identity);
+				server.pushFrame(JSON.stringify(identity), positionedRecipients);
 			}
 			const agentDir = lifecycleAgentDir ?? settings?.getAgentDir?.();
 			if (lifecycleRequired && !agentDir) throw new Error("Lifecycle SDK host requires an agent directory.");
@@ -8463,6 +8525,20 @@ export function createNotificationsExtension(
 	};
 
 	const hasUserSettlementReceipt = (rt: SessionRuntime): boolean => rt.pendingSettled?.receipts[0]?.origin === "user";
+	const composeSettlementText = (receipts: ReadonlyArray<{ text: string }>): string =>
+		receipts.map(receipt => receipt.text).join("\n\n");
+
+	const consumePublishedSettlement = (rt: SessionRuntime, text: string, window: number): void => {
+		const pending = rt.pendingSettled;
+		if (!pending || pending.window !== window) return;
+		if (composeSettlementText(pending.receipts) === text) {
+			rt.pendingSettled = undefined;
+			return;
+		}
+		const receipts = pending.receipts.filter(receipt => receipt.text !== text);
+		if (receipts.length === pending.receipts.length) return;
+		rt.pendingSettled = receipts.length ? { ...pending, receipts } : undefined;
+	};
 
 	const flushPendingFinal = (rt: SessionRuntime, id: string): void => {
 		const pending = rt.pendingFinal;
@@ -8479,7 +8555,7 @@ export function createNotificationsExtension(
 				for (const receipt of pending.receipts)
 					deferLeanReceipt(rt, receipt.text, receipt.messageRef, pending.window, receipt.origin);
 			} else {
-				const text = pending.receipts.map(receipt => receipt.text).join("\n\n");
+				const text = composeSettlementText(pending.receipts);
 				const messageRef = pending.receipts.length === 1 ? pending.receipts[0]?.messageRef : undefined;
 				try {
 					pushSessionFrame(rt, {
@@ -8502,15 +8578,14 @@ export function createNotificationsExtension(
 	const flushPendingSettled = (rt: SessionRuntime, id: string): void => {
 		const settled = rt.pendingSettled;
 		if (!settled?.receipts.length || !rt.notificationsActive || rt.redact || rt.policySuspended) return;
-		rt.pendingSettled = undefined;
-		const text = settled.receipts.map(receipt => receipt.text).join("\n\n");
+		const text = composeSettlementText(settled.receipts);
 		// A composition represents multiple finalized turns. It must be a fresh
 		// terminal message rather than editing either constituent turn's stream.
 		const messageRef = settled.receipts.length === 1 ? settled.receipts[0]?.messageRef : undefined;
 		const previousLiveRef = rt.liveRef;
 		if (messageRef) rt.liveRef = messageRef;
 		try {
-			flushTurnText(rt, id, text, true);
+			if (flushTurnText(rt, id, text, true)) rt.pendingSettled = undefined;
 		} finally {
 			if (!messageRef) rt.liveRef = previousLiveRef;
 		}
@@ -8704,16 +8779,20 @@ export function createNotificationsExtension(
 		const seq = rt.idleSeq++;
 		// Re-assert the identity header so the daemon renames the topic once the
 		// session title has been auto-generated ("{repo}/{branch} - {title}"). The
-		// daemon only renames when the title actually changed.
+		// daemon only renames when the title actually changed. Bind the dependent
+		// idle to the exact connection generations that accepted this positioned
+		// identity; native raw fallbacks enqueue identity and idle as one bounded
+		// writer command for the remaining snapshot cohort.
 		try {
-			pushSessionFrame(rt, {
+			const identity = {
 				type: "identity_header",
 				sessionId: id,
 				...buildIdentity(ctx.cwd, ctx.sessionManager.getSessionName(), telegramTopicsEnabled()),
-			});
-		} catch {}
-		try {
-			rt.server.noteIdle(
+			} as const;
+			const receipts = emitSessionEventWithReceipts(rt, identity);
+			const outcome = rt.server.queueIdleAfterDirected(
+				JSON.stringify(identity),
+				receipts,
 				JSON.stringify(
 					notificationActionPayload(
 						{
@@ -8726,8 +8805,13 @@ export function createNotificationsExtension(
 					),
 				),
 			);
-		} catch (e) {
-			logger.warn(`notifications: noteIdle failed: ${String(e)}`);
+			if (outcome.status === "rejected" || outcome.status === "partial") {
+				logger.warn(
+					`notifications: dependent idle ${outcome.status} (${outcome.queuedCount}/${outcome.recipientCount} recipients queued)`,
+				);
+			}
+		} catch (error) {
+			logger.warn(`notifications: recipient-bound identity/idle delivery failed: ${String(error)}`);
 		}
 
 		// Lean: emit the latest deferred assistant answer exactly once at idle.
@@ -8778,13 +8862,10 @@ export function createNotificationsExtension(
 	// The daemon coalesces/throttles these via its shared rate-limit pool.
 	// Push the in-flight turn's assistant text as a finalized turn_stream, deduped
 	// against what was already flushed for this turn (the pre-ask lead-in).
-	const flushTurnText = (rt: SessionRuntime, id: string, text: string | undefined, finalAnswer: boolean): void => {
-		if (!text || text === rt.preAskFlushedText || !rt.notificationsActive || rt.policySuspended) return;
-		rt.preAskFlushedText = text;
-		// Ask lead-ins supersede any deferred lean settled answer from earlier turns
-		// so agent_end does not re-emit stale intermediate narration (#2863 review).
-		if (!finalAnswer && rt.currentTurnSettlementOrigin !== "autonomous" && !hasUserSettlementReceipt(rt))
-			rt.pendingSettled = undefined;
+	const flushTurnText = (rt: SessionRuntime, id: string, text: string | undefined, finalAnswer: boolean): boolean => {
+		if (!text || text === rt.preAskFlushedText || !rt.notificationsActive || rt.policySuspended) return false;
+		const hadUserSettlementReceipt = hasUserSettlementReceipt(rt);
+		const settlementWindow = rt.currentTurnSettlementWindow ?? rt.settlementWindow;
 		// Decision A: a stream-enabled turn must finalize as an in-place edit of ONE
 		// live message, never a fresh (rich-promotable) send. If live frames were
 		// async-queued and none landed before this flush, reuse the per-turn ref
@@ -8794,7 +8875,7 @@ export function createNotificationsExtension(
 			rt.liveRef = String(rt.turnSeq);
 		}
 		try {
-			pushSessionFrame(rt, {
+			const published = pushSessionFrame(rt, {
 				type: "turn_stream",
 				sessionId: id,
 				phase: "finalized",
@@ -8802,8 +8883,24 @@ export function createNotificationsExtension(
 				text,
 				...(rt.liveRef ? { messageRef: rt.liveRef } : {}),
 			});
+			if (!published) return false;
+			rt.preAskFlushedText = text;
+			if (!finalAnswer) {
+				// A successfully published ask lead-in settles only exact matching
+				// receipts from the same user-request window. Distinct retained user
+				// receipts remain eligible for the idle summary (#4458).
+				consumePublishedSettlement(rt, text, settlementWindow);
+				// Ask lead-ins supersede deferred lean narration from earlier turns so
+				// agent_end does not re-emit stale intermediate text (#2863 review).
+				// Preserve the pre-publish user-receipt decision even when the exact
+				// match above consumed that receipt.
+				if (rt.currentTurnSettlementOrigin !== "autonomous" && !hadUserSettlementReceipt)
+					rt.pendingSettled = undefined;
+			}
+			return true;
 		} catch (e) {
 			logger.warn(`notifications: pushFrame (turn) failed: ${String(e)}`);
+			return false;
 		}
 	};
 

package/src/sdk/bus/natives-augment.d.ts

@@ -21,7 +21,14 @@ declare module "@gajae-code/natives" {
 	interface RetireIfUnclaimedResult {
 		status: "retired" | "already_terminal" | "claimed" | "stale";
 	}
+	interface DependentIdleDeliveryResult {
+		status: "queued" | "no_recipients" | "rejected" | "partial";
+		recipientCount: number;
+		queuedCount: number;
+	}
 	interface NotificationServer {
+		/** Broadcast a validated frame, omitting subscribers that received its positioned event envelope. */
+		pushFrame(json: string, excludedConnectionIds?: string[]): void;
 		/** Register the raw v3 SDK frame callback. Must be called before start. */
 		onSdkFrame(callback: (err: null | Error, frame: SdkFrameEvent) => void): void;
 		/** Register the connection-close callback. Must be called before start. */
@@ -32,6 +39,14 @@ declare module "@gajae-code/natives" {
 		): void;
 		/** Directed delivery of a validated, bounded JSON v3 envelope to one connection. */
 		sendTo(connectionId: string, json: string): void;
+		/** Directed delivery with an opaque exact-generation receipt. */
+		sendToWithReceipt(connectionId: string, json: string): string;
+		/** Queue raw identity fallback and dependent idle on one exact bounded cohort. */
+		queueIdleAfterDirected(
+			prerequisiteJson: string,
+			positionedReceipts: string[],
+			neededJson: string,
+		): DependentIdleDeliveryResult;
 		/** Register a correlated workflow-gate action_needed frame. */
 		registerWorkflowGateAsk(workflowJson: string, repliable: boolean): void;
 		/** Atomically register the single active arbitrated action and return its private lease. */
@@ -45,7 +60,8 @@ declare module "@gajae-code/natives" {
 			text: string,
 			finalAnswer?: boolean,
 			messageRef?: string,
-		): void;
+			excludedConnectionIds?: string[],
+		): boolean;
 		/** Broadcast raw file bytes; Rust encodes the unchanged base64 wire field. */
 		pushFileAttachmentUnchecked(
 			sessionId: string,
@@ -53,11 +69,14 @@ declare module "@gajae-code/natives" {
 			mime: string | undefined,
 			data: Buffer,
 			caption: string | undefined,
+			excludedConnectionIds?: string[],
 		): void;
 		/** Counters for known-good N-API frame crossings. */
 		knownGoodFrameStats(): {
 			knownGoodTurnStreamFrames: number;
 			turnStreamSerdeValidationParses: number;
 		};
+		/** Proves that optional raw fan-out exclusions are enforced by the loaded addon. */
+		supportsPositionedRawExclusion(): boolean;
 	}
 }

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

@@ -280,8 +280,11 @@ export const SDK_LIFECYCLE_ROUTER_PROTOCOL_VERSION = 1;
  * still running the pre-#4689 router keeps the old hot polling loop and its
  * lock contention, so an already-running owner must be replaced rather than
  * retained across this upgrade.
+ * Generation 177 consumes an exact same-window lean settlement receipt only
+ * after its autonomous ask lead-in publishes successfully, preventing idle
+ * replay without changing the serving protocol.
  */
-export const DAEMON_GENERATION = 176;
+export const DAEMON_GENERATION = 178;
 
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 7