@oh-my-pi/pi-coding-agent 17.2.4 → 17.2.6

package/src/session/session-paths.ts

@@ -2,10 +2,17 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { getTerminalId } from "@oh-my-pi/pi-tui";
-import { getSessionsDir, getTerminalSessionsDir, isEnoent, logger, resolveEquivalentPath } from "@oh-my-pi/pi-utils";
+import {
+	getSessionsDir,
+	getTerminalSessionsDir,
+	isEnoent,
+	isRecord,
+	logger,
+	resolveEquivalentPath,
+} from "@oh-my-pi/pi-utils";
 import type { SessionStorage } from "./session-storage";
 
-const migratedSessionRoots = new Set<string>();
+const SESSION_HEADER_PREFIX_BYTES = 4096;
 
 /**
  * Merge or rename a legacy session directory into its canonical target.
@@ -35,12 +42,16 @@ function encodeLegacyAbsoluteSessionDirName(cwd: string): string {
 	return `--${resolvedCwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
 }
 
-function encodeRelativeSessionDirName(prefix: string, relative: string): string {
+function encodeLegacyRelativeSessionDirName(prefix: string, relative: string): string {
 	const encoded = relative.replace(/[/\\:]/g, "-");
 	return encoded ? (prefix.endsWith("-") ? `${prefix}${encoded}` : `${prefix}-${encoded}`) : prefix;
 }
 
-function getDefaultSessionDirName(cwd: string): { encodedDirName: string; resolvedCwd: string } {
+function getDefaultSessionDirName(cwd: string): {
+	encodedDirName: string;
+	legacyRelativeDirName: string | undefined;
+	resolvedCwd: string;
+} {
 	const resolvedCwd = path.resolve(cwd);
 	const canonicalCwd = resolveEquivalentPath(resolvedCwd);
 	const home = os.homedir();
@@ -49,72 +60,111 @@ function getDefaultSessionDirName(cwd: string): { encodedDirName: string; resolv
 	const canonicalTempRoot = resolveEquivalentPath(tempRoot);
 	const homeRelative = path.relative(canonicalHome, canonicalCwd);
 	const tempRelative = path.relative(canonicalTempRoot, canonicalCwd);
-	const encodedDirName =
-		homeRelative === "" || (!homeRelative.startsWith("..") && !path.isAbsolute(homeRelative))
-			? encodeRelativeSessionDirName("-", homeRelative)
-			: tempRelative === "" || (!tempRelative.startsWith("..") && !path.isAbsolute(tempRelative))
-				? encodeRelativeSessionDirName("-tmp", tempRelative)
-				: encodeLegacyAbsoluteSessionDirName(canonicalCwd);
-	return { encodedDirName, resolvedCwd };
-}
 
-/**
- * Migrate old `--<home-encoded>-*--` session dirs to the new `-*` format.
- * Runs once per sessions root on first access, best-effort.
- */
-function migrateHomeSessionDirs(sessionsRoot: string): void {
-	if (migratedSessionRoots.has(sessionsRoot)) return;
-	migratedSessionRoots.add(sessionsRoot);
+	let scope: "home" | "tmp" | "abs";
+	let legacyRelativeDirName: string | undefined;
+	if (homeRelative === "" || (!homeRelative.startsWith("..") && !path.isAbsolute(homeRelative))) {
+		scope = "home";
+		legacyRelativeDirName = encodeLegacyRelativeSessionDirName("-", homeRelative);
+	} else if (tempRelative === "" || (!tempRelative.startsWith("..") && !path.isAbsolute(tempRelative))) {
+		scope = "tmp";
+		legacyRelativeDirName = encodeLegacyRelativeSessionDirName("-tmp", tempRelative);
+	} else {
+		scope = "abs";
+	}
 
-	const home = os.homedir();
-	const homeEncoded = home.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-");
-	const oldPrefix = `--${homeEncoded}-`;
-	const oldExact = `--${homeEncoded}--`;
+	const normalized = canonicalCwd.replaceAll("\\", "/");
+	const readable = path
+		.basename(canonicalCwd)
+		.replace(/[^a-zA-Z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(-80);
+	const digest = Bun.SHA256.hash(normalized, "hex");
+	const encodedDirName = `${scope}-${readable || "project"}-${digest}`;
+	return { encodedDirName, legacyRelativeDirName, resolvedCwd };
+}
 
-	let entries: string[];
+function readSessionCwd(sessionFile: string, buffer: Buffer): string | undefined {
+	let descriptor: number | undefined;
 	try {
-		entries = fs.readdirSync(sessionsRoot);
+		descriptor = fs.openSync(sessionFile, "r");
+		const bytesRead = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
+		const prefix = buffer.toString("utf8", 0, bytesRead);
+		for (const line of prefix.split(/\r?\n/, 3)) {
+			try {
+				const record: unknown = JSON.parse(line);
+				if (isRecord(record) && record.type === "session" && typeof record.cwd === "string") {
+					return record.cwd;
+				}
+			} catch {
+				// Ignore title slots or truncated/corrupt headers.
+			}
+		}
 	} catch {
-		return;
+		// Best-effort migration leaves unreadable sessions in the current bucket.
+	} finally {
+		if (descriptor !== undefined) fs.closeSync(descriptor);
 	}
+	return undefined;
+}
 
+function moveSessionBundle(sourceDir: string, targetDir: string, sessionName: string, entries: string[]): void {
+	fs.mkdirSync(targetDir, { recursive: true });
+	const artifactsName = path.basename(sessionName, ".jsonl");
 	for (const entry of entries) {
-		let remainder: string;
-		if (entry === oldExact) {
-			remainder = "";
-		} else if (entry.startsWith(oldPrefix) && entry.endsWith("--")) {
-			remainder = entry.slice(oldPrefix.length, -2);
+		if (entry !== sessionName && entry !== artifactsName && !entry.startsWith(`${sessionName}.`)) continue;
+		const source = path.join(sourceDir, entry);
+		if (!fs.existsSync(source)) continue;
+		const target = path.join(targetDir, entry);
+		const existing = fs.statSync(target, { throwIfNoEntry: false });
+		if (!existing) {
+			fs.renameSync(source, target);
+		} else if (existing.isDirectory() && fs.statSync(source).isDirectory()) {
+			migrateSessionDirPath(source, target);
 		} else {
-			continue;
-		}
-
-		const newName = remainder ? `-${remainder}` : "-";
-		const oldPath = path.join(sessionsRoot, entry);
-		const newPath = path.join(sessionsRoot, newName);
-
-		try {
-			migrateSessionDirPath(oldPath, newPath);
-		} catch {
-			// Best effort
+			fs.rmSync(source, { recursive: true, force: true });
 		}
 	}
 }
 
-function migrateLegacyAbsoluteSessionDir(cwd: string, sessionDir: string, sessionsRoot: string): void {
-	const legacyDir = path.join(sessionsRoot, encodeLegacyAbsoluteSessionDirName(cwd));
-	if (legacyDir === sessionDir || !fs.existsSync(legacyDir)) return;
-
-	try {
-		migrateSessionDirPath(legacyDir, sessionDir);
-	} catch {
-		// Best effort
+function rerouteCollidingSessions(
+	cwd: string,
+	legacyDir: string,
+	sessionsRoot: string,
+	kind: "relative" | "absolute",
+): void {
+	const entries = fs.readdirSync(legacyDir);
+	const currentCwd = resolveEquivalentPath(path.resolve(cwd));
+	const buffer = Buffer.allocUnsafe(SESSION_HEADER_PREFIX_BYTES);
+	for (const entry of entries) {
+		if (!entry.endsWith(".jsonl")) continue;
+		const recordedCwd = readSessionCwd(path.join(legacyDir, entry), buffer);
+		if (!recordedCwd) continue;
+		const recordedCanonical = resolveEquivalentPath(path.resolve(recordedCwd));
+		if (
+			recordedCanonical === currentCwd ||
+			!fs.statSync(recordedCanonical, { throwIfNoEntry: false })?.isDirectory()
+		) {
+			continue;
+		}
+		const recordedNames = getDefaultSessionDirName(recordedCanonical);
+		const recordedLegacyName =
+			kind === "relative"
+				? recordedNames.legacyRelativeDirName
+				: encodeLegacyAbsoluteSessionDirName(recordedCanonical);
+		if (recordedLegacyName !== path.basename(legacyDir)) continue;
+		moveSessionBundle(legacyDir, path.join(sessionsRoot, recordedNames.encodedDirName), entry, entries);
 	}
 }
 
 export function resolveManagedSessionRoot(sessionDir: string, cwd: string): string | undefined {
 	const currentDirName = path.basename(sessionDir);
-	const { encodedDirName } = getDefaultSessionDirName(cwd);
-	if (currentDirName !== encodedDirName && currentDirName !== encodeLegacyAbsoluteSessionDirName(cwd)) {
+	const { encodedDirName, legacyRelativeDirName } = getDefaultSessionDirName(cwd);
+	if (
+		currentDirName !== encodedDirName &&
+		currentDirName !== legacyRelativeDirName &&
+		currentDirName !== encodeLegacyAbsoluteSessionDirName(cwd)
+	) {
 		return undefined;
 	}
 	return path.dirname(sessionDir);
@@ -130,10 +180,23 @@ export function computeDefaultSessionDir(
 	storage: SessionStorage,
 	sessionsRoot: string = getSessionsDir(),
 ): string {
-	const { encodedDirName, resolvedCwd } = getDefaultSessionDirName(cwd);
-	migrateHomeSessionDirs(sessionsRoot);
+	const { encodedDirName, legacyRelativeDirName, resolvedCwd } = getDefaultSessionDirName(cwd);
 	const sessionDir = path.join(sessionsRoot, encodedDirName);
-	migrateLegacyAbsoluteSessionDir(resolvedCwd, sessionDir, sessionsRoot);
+	const legacyDirs: Array<{ kind: "relative" | "absolute"; name: string | undefined }> = [
+		{ kind: "relative", name: legacyRelativeDirName },
+		{ kind: "absolute", name: encodeLegacyAbsoluteSessionDirName(resolvedCwd) },
+	];
+	for (const legacy of legacyDirs) {
+		if (!legacy.name) continue;
+		const legacyDir = path.join(sessionsRoot, legacy.name);
+		if (legacyDir === sessionDir || !fs.existsSync(legacyDir)) continue;
+		try {
+			rerouteCollidingSessions(resolvedCwd, legacyDir, sessionsRoot, legacy.kind);
+			migrateSessionDirPath(legacyDir, sessionDir);
+		} catch {
+			// Best effort
+		}
+	}
 	storage.ensureDirSync(sessionDir);
 	return sessionDir;
 }

package/src/session/session-stats.ts

@@ -34,6 +34,11 @@ export interface SessionStatsTrackerHost {
 	sessionId(): string;
 }
 
+function correctedPromptTokens(assistant: AssistantMessage): number {
+	const providerPromptTokens = assistant.contextSnapshot?.promptTokens ?? calculatePromptTokens(assistant.usage);
+	return Math.max(0, providerPromptTokens - (assistant.contextSnapshot?.historyRewriteTokensRemoved ?? 0));
+}
+
 /** Computes session totals and tracks the in-flight context estimate. */
 export class SessionStatsTracker {
 	readonly #host: SessionStatsTrackerHost;
@@ -160,8 +165,7 @@ export class SessionStatsTracker {
 		const useAnchor =
 			anchorAssistant !== undefined && anchorIndex !== -1 && (!pending || anchorIndex >= pending.cutoffCount);
 		if (useAnchor && anchorAssistant) {
-			const promptTokens =
-				anchorAssistant.contextSnapshot?.promptTokens ?? calculatePromptTokens(anchorAssistant.usage);
+			const promptTokens = correctedPromptTokens(anchorAssistant);
 			const nonMessageTokens =
 				anchorAssistant.contextSnapshot?.nonMessageTokens ?? computeNonMessageTokens(this.#host.session);
 			anchored = true;
@@ -199,7 +203,7 @@ export class SessionStatsTracker {
 				) {
 					continue;
 				}
-				const promptTokens = message.contextSnapshot?.promptTokens ?? calculatePromptTokens(message.usage);
+				const promptTokens = correctedPromptTokens(message);
 				const nonMessageTokens =
 					message.contextSnapshot?.nonMessageTokens ?? computeNonMessageTokens(this.#host.session);
 				let tailTokens = 0;
@@ -256,6 +260,47 @@ export class SessionStatsTracker {
 		return this.#pendingContextSnapshot?.nonMessageTokens;
 	}
 
+	/**
+	 * Apply an estimated prompt-prefix reduction to the current provider anchor.
+	 *
+	 * History after the anchor is estimated live by {@link getContextBreakdown};
+	 * callers must pass only savings from entries already included in the
+	 * anchor's provider-reported prompt. Persisting the correction on the
+	 * assistant snapshot keeps reloads accurate, and the next successful
+	 * assistant response naturally replaces it with a fresh provider anchor.
+	 */
+	recordAnchoredHistoryRewrite(tokensRemoved: number): void {
+		if (!Number.isFinite(tokensRemoved) || tokensRemoved <= 0) return;
+
+		const branchEntries = this.#host.sessionManager.getBranch();
+		const latestCompaction = getLatestCompactionEntry(branchEntries);
+		const compactionIndex = latestCompaction ? branchEntries.lastIndexOf(latestCompaction) : -1;
+		for (let index = branchEntries.length - 1; index > compactionIndex; index--) {
+			const entry = branchEntries[index];
+			if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+			const assistant = entry.message;
+			if (
+				assistant.stopReason === "aborted" ||
+				assistant.stopReason === "error" ||
+				!assistant.usage ||
+				!hasContextTokenUsage(assistant.usage)
+			) {
+				continue;
+			}
+
+			if (!assistant.contextSnapshot) {
+				assistant.contextSnapshot = {
+					promptTokens: calculatePromptTokens(assistant.usage),
+					nonMessageTokens: computeNonMessageTokens(this.#host.session),
+				};
+			}
+			const snapshot = assistant.contextSnapshot;
+			snapshot.historyRewriteTokensRemoved = (snapshot.historyRewriteTokensRemoved ?? 0) + Math.floor(tokensRemoved);
+			this.#contextUsageRevision++;
+			return;
+		}
+	}
+
 	/** Sets or clears the in-flight context snapshot. */
 	setPendingSnapshot(snapshot: PendingContextSnapshot | undefined): void {
 		this.#pendingContextSnapshot = snapshot;

package/src/session/session-storage.ts

@@ -14,13 +14,25 @@ export interface SessionStorageStat {
 
 export interface SessionStorageWriter {
 	/**
-	 * Append one newline-terminated line. File storage batches same-turn appends
-	 * until its microtask boundary; memory storage updates in-body; indexed
-	 * backends queue in call order.
+	 * Append one newline-terminated line.
+	 *
+	 * File and memory storage apply the line synchronously before the returned
+	 * promise settles, so a software crash after `append` returns (or after a
+	 * fire-and-forget call begins) still sees the entry on disk / in body. No
+	 * `fsync` — power loss may still drop the last page. Indexed backends update
+	 * the local index immediately and queue the remote publish in call order.
 	 *
 	 * `line` MUST include the trailing newline.
 	 */
 	append(line: string): Promise<void>;
+	/**
+	 * Synchronous append when the backend can apply the line before return.
+	 * File and memory implement this so {@link SessionManager} can latch the
+	 * first write failure before the appending call returns (surfaced by a later
+	 * flushSync/close/next append — the turn loop does not throw from append).
+	 * Indexed backends update the local index immediately and queue remote I/O.
+	 */
+	appendSync?(line: string): void;
 	/** Resolve once all queued appends complete. No fsync. */
 	flush(): Promise<void>;
 	/** Drain synchronously flushable queued work when the backend supports it. No fsync. */
@@ -93,8 +105,6 @@ class FileSessionStorageWriter implements SessionStorageWriter {
 	#closed = false;
 	#error: Error | undefined;
 	#onError: ((err: Error) => void) | undefined;
-	#pending = "";
-	#flushScheduled = false;
 
 	constructor(fpath: string, options?: { flags?: "a" | "w"; onError?: (err: Error) => void }) {
 		this.#onError = options?.onError;
@@ -129,34 +139,29 @@ class FileSessionStorageWriter implements SessionStorageWriter {
 		}
 	}
 
-	#flushPendingNow(): void {
-		this.#flushScheduled = false;
-		if (this.#pending.length === 0) return;
-		const pending = this.#pending;
-		this.#pending = "";
+	appendSync(line: string): void {
+		if (this.#closed) throw new Error("Writer closed");
+		if (this.#error) throw this.#error;
+		// Write in-body so software crash after the call still sees the entry.
+		// Microtask batching used to leave completed transcript lines only in
+		// memory until the next event-loop turn; process crash then lost every
+		// post-checkpoint event. flush/flushSync remain no-op drains (no fsync).
 		try {
-			this.#writeNow(pending);
+			this.#writeNow(line);
 		} catch (err) {
-			this.#recordError(err);
+			throw this.#recordError(err);
 		}
 	}
 
 	async append(line: string): Promise<void> {
-		if (this.#closed) throw new Error("Writer closed");
-		if (this.#error) throw this.#error;
-		this.#pending += line;
-		if (this.#flushScheduled) return;
-		this.#flushScheduled = true;
-		queueMicrotask(() => this.#flushPendingNow());
+		this.appendSync(line);
 	}
 
 	async flush(): Promise<void> {
-		this.#flushPendingNow();
 		if (this.#error) throw this.#error;
 	}
 
 	flushSync(): void {
-		this.#flushPendingNow();
 		if (this.#error) throw this.#error;
 	}
 
@@ -166,7 +171,6 @@ class FileSessionStorageWriter implements SessionStorageWriter {
 
 	async close(): Promise<void> {
 		if (this.#closed) return;
-		this.#flushPendingNow();
 		this.#closed = true;
 		// Unregister from finalization - we're closing properly
 		writerRegistry.unregister(this);
@@ -487,7 +491,7 @@ class MemorySessionStorageWriter implements SessionStorageWriter {
 		return error;
 	}
 
-	async append(line: string): Promise<void> {
+	appendSync(line: string): void {
 		if (this.#closed) throw new Error("Writer closed");
 		if (this.#error) throw this.#error;
 		try {
@@ -498,6 +502,10 @@ class MemorySessionStorageWriter implements SessionStorageWriter {
 		}
 	}
 
+	async append(line: string): Promise<void> {
+		this.appendSync(line);
+	}
+
 	async flush(): Promise<void> {
 		if (this.#error) throw this.#error;
 	}

package/src/session/stream-guards.ts

@@ -164,7 +164,7 @@ export class StreamingEditGuard {
 		const toolCall = messageContent[contentIndex] as ToolCall;
 		if (toolCall.name !== "edit") return undefined;
 		const args = toolCall.arguments;
-		if (!args || typeof args !== "object" || Array.isArray(args) || "old_text" in args || "new_text" in args) {
+		if (!args || typeof args !== "object" || Array.isArray(args) || "old_string" in args || "new_string" in args) {
 			return undefined;
 		}
 		const filePath = typeof args.path === "string" ? args.path : undefined;

package/src/session/yield-queue.ts

@@ -1,4 +1,4 @@
-import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import { type AgentMessage, ASIDE_MESSAGE_COMMIT, ASIDE_MESSAGE_DISCARD } from "@oh-my-pi/pi-agent-core";
 import { logger } from "@oh-my-pi/pi-utils";
 
 export interface YieldDispatcher<P> {
@@ -25,6 +25,17 @@ interface StoredDispatcher {
 	skipIdleFlush?: boolean;
 }
 
+interface StoredEntry {
+	value: unknown;
+	resolve?: () => void;
+	reject?: (error: Error) => void;
+}
+
+interface BuiltMessage {
+	message: AgentMessage;
+	entries: StoredEntry[];
+}
+
 function formatError(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
@@ -32,7 +43,7 @@ function formatError(error: unknown): string {
 export class YieldQueue {
 	readonly #options: YieldQueueOptions;
 	readonly #dispatchers = new Map<string, StoredDispatcher>();
-	readonly #entries = new Map<string, unknown[]>();
+	readonly #entries = new Map<string, StoredEntry[]>();
 	#idleFlushPending = false;
 
 	constructor(options: YieldQueueOptions) {
@@ -49,14 +60,27 @@ export class YieldQueue {
 		return () => {
 			if (this.#dispatchers.get(kind) !== stored) return;
 			this.#dispatchers.delete(kind);
+			this.#rejectEntries(this.#entries.get(kind) ?? [], new Error(`Yield queue dispatcher removed: ${kind}`));
 			this.#entries.delete(kind);
 		};
 	}
 
 	enqueue<P>(kind: string, entry: P): void {
+		this.#enqueue(kind, { value: entry });
+	}
+
+	enqueueWithReceipt<P>(kind: string, entry: P): Promise<void> {
+		const { promise, resolve, reject } = Promise.withResolvers<void>();
+		if (!this.#enqueue(kind, { value: entry, resolve, reject })) {
+			reject(new Error(`Yield queue entry ignored for unregistered kind: ${kind}`));
+		}
+		return promise;
+	}
+
+	#enqueue(kind: string, entry: StoredEntry): boolean {
 		if (!this.#dispatchers.has(kind)) {
 			logger.warn("Yield queue entry ignored for unregistered kind", { kind });
-			return;
+			return false;
 		}
 		let entries = this.#entries.get(kind);
 		if (!entries) {
@@ -67,6 +91,7 @@ export class YieldQueue {
 		if (!this.#options.isStreaming() && !this.#dispatchers.get(kind)!.skipIdleFlush) {
 			this.#scheduleIdleFlush();
 		}
+		return true;
 	}
 
 	has(kind?: string): boolean {
@@ -77,30 +102,55 @@ export class YieldQueue {
 		return false;
 	}
 
+	/** Arrange an idle flush for entries queued near the end of a streaming run. */
+	requestIdleFlush(): void {
+		for (const [kind, dispatcher] of this.#dispatchers) {
+			if (!dispatcher.skipIdleFlush && this.has(kind)) {
+				this.#scheduleIdleFlush();
+				return;
+			}
+		}
+	}
+
 	async flush(mode: YieldFlushMode): Promise<void> {
 		if (mode === "idle") {
 			this.#idleFlushPending = false;
 		}
-		const idleMessages: AgentMessage[] = [];
+		const idleMessages: BuiltMessage[] = [];
 		for (const [kind, dispatcher] of this.#dispatchers) {
+			if (mode === "idle" && dispatcher.skipIdleFlush) continue;
 			const entries = this.#drain(kind);
 			if (entries.length === 0) continue;
-			const message = this.#build(kind, dispatcher, entries);
-			if (!message) continue;
+			const built = this.#build(kind, dispatcher, entries);
+			if (!built) continue;
 			if (mode === "streaming") {
 				try {
-					this.#options.injectStreaming?.(message);
+					if (!this.#options.injectStreaming) throw new Error("Streaming injection is unavailable");
+					this.#options.injectStreaming(built.message);
+					this.#resolveEntries(built.entries);
 				} catch (error) {
+					const dispatchError = error instanceof Error ? error : new Error(String(error));
+					this.#rejectEntries(built.entries, dispatchError);
 					logger.warn("Yield queue streaming dispatch failed", { kind, error: formatError(error) });
 				}
 			} else {
-				idleMessages.push(message);
+				idleMessages.push(built);
 			}
 		}
 		if (mode === "idle" && idleMessages.length > 0) {
+			for (const item of idleMessages) this.#attachEntrySettlement(item);
 			try {
-				await this.#options.injectIdle(idleMessages);
+				await this.#options.injectIdle(idleMessages.map(item => item.message));
+				for (const item of idleMessages) {
+					(item.message as AgentMessage & { [ASIDE_MESSAGE_COMMIT]?: () => void })[ASIDE_MESSAGE_COMMIT]?.();
+				}
 			} catch (error) {
+				const dispatchError = error instanceof Error ? error : new Error(String(error));
+				for (const item of idleMessages) {
+					(item.message as AgentMessage & { [ASIDE_MESSAGE_DISCARD]?: (error: Error) => void })[
+						ASIDE_MESSAGE_DISCARD
+					]?.(dispatchError);
+				}
 				logger.warn("Yield queue idle dispatch failed", { error: formatError(error) });
 			}
 		}
@@ -119,7 +169,12 @@ export class YieldQueue {
 		for (const [kind, dispatcher] of this.#dispatchers) {
 			const entries = this.#drain(kind);
 			if (entries.length === 0) continue;
-			thunks.push(() => this.#build(kind, dispatcher, entries));
+			thunks.push(() => {
+				const built = this.#build(kind, dispatcher, entries);
+				if (!built) return null;
+				this.#attachEntrySettlement(built);
+				return built.message;
+			});
 		}
 		return thunks;
 	}
@@ -127,14 +182,22 @@ export class YieldQueue {
 	/** Drop queued entries. With `kind`, drop only that kind's entries (leaving
 	 *  any pending idle-flush for other kinds intact); otherwise drop everything. */
 	clear(kind?: string): void {
+		const error = new Error("Yield queue entry cleared before dispatch");
 		if (kind !== undefined) {
+			this.#rejectEntries(this.#entries.get(kind) ?? [], error);
 			this.#entries.delete(kind);
 			return;
 		}
+		for (const entries of this.#entries.values()) this.#rejectEntries(entries, error);
 		this.#entries.clear();
 		this.#idleFlushPending = false;
 	}
 
+	/** Clear a scheduled-flush latch when its host task is cancelled before running. */
+	cancelIdleFlushScheduling(): void {
+		this.#idleFlushPending = false;
+	}
+
 	#scheduleIdleFlush(): void {
 		if (this.#idleFlushPending) return;
 		this.#idleFlushPending = true;
@@ -150,34 +213,76 @@ export class YieldQueue {
 		}
 	}
 
-	#drain(kind: string): unknown[] {
+	#drain(kind: string): StoredEntry[] {
 		const entries = this.#entries.get(kind);
 		if (!entries || entries.length === 0) return [];
 		this.#entries.delete(kind);
 		return entries;
 	}
 
-	#build(kind: string, dispatcher: StoredDispatcher, entries: unknown[]): AgentMessage | null {
-		const survivors: unknown[] = [];
+	#build(kind: string, dispatcher: StoredDispatcher, entries: StoredEntry[]): BuiltMessage | null {
+		const survivors: StoredEntry[] = [];
 		for (const entry of entries) {
 			if (dispatcher.isStale) {
 				let stale: boolean;
 				try {
-					stale = dispatcher.isStale(entry);
+					stale = dispatcher.isStale(entry.value);
 				} catch (error) {
+					const staleError = error instanceof Error ? error : new Error(String(error));
+					entry.reject?.(staleError);
 					logger.warn("Yield queue stale check failed", { kind, error: formatError(error) });
 					continue;
 				}
-				if (stale) continue;
+				if (stale) {
+					entry.reject?.(new Error(`Yield queue entry became stale: ${kind}`));
+					continue;
+				}
 			}
 			survivors.push(entry);
 		}
 		if (survivors.length === 0) return null;
 		try {
-			return dispatcher.build(survivors);
+			const message = dispatcher.build(survivors.map(entry => entry.value));
+			if (!message) {
+				this.#rejectEntries(survivors, new Error(`Yield queue dispatcher skipped entry: ${kind}`));
+				return null;
+			}
+			return { message, entries: survivors };
 		} catch (error) {
+			const buildError = error instanceof Error ? error : new Error(String(error));
+			this.#rejectEntries(survivors, buildError);
 			logger.warn("Yield queue build failed", { kind, error: formatError(error) });
 			return null;
 		}
 	}
+
+	#attachEntrySettlement(built: BuiltMessage): void {
+		let settled = false;
+		Object.defineProperties(built.message, {
+			[ASIDE_MESSAGE_COMMIT]: {
+				configurable: true,
+				value: () => {
+					if (settled) return;
+					settled = true;
+					this.#resolveEntries(built.entries);
+				},
+			},
+			[ASIDE_MESSAGE_DISCARD]: {
+				configurable: true,
+				value: (error: Error) => {
+					if (settled) return;
+					settled = true;
+					this.#rejectEntries(built.entries, error);
+				},
+			},
+		});
+	}
+
+	#resolveEntries(entries: StoredEntry[]): void {
+		for (const entry of entries) entry.resolve?.();
+	}
+
+	#rejectEntries(entries: StoredEntry[], error: Error): void {
+		for (const entry of entries) entry.reject?.(error);
+	}
 }