@sayknow-cli/coding-agent 0.4.6 → 0.5.0

package/src/session/session-storage.ts

@@ -167,6 +167,8 @@ export interface SessionStorage {
 	readSnapshotSync?(path: string): SessionStorageSnapshot;
 	statSync(path: string): SessionStorageStat;
 	listFilesSync(dir: string, pattern: string): string[];
+	/** List matching files with mtimes without issuing one JavaScript stat call per path. */
+	listFilesByMtime?(dir: string, pattern: string): Promise<Array<{ path: string; mtimeMs: number }>>;
 	/**
 	 * Strict directory scan that never suppresses scan/root errors. Used by strict
 	 * authorization inventory; the forgiving {@link listFilesSync} stays display-only.
@@ -259,6 +261,19 @@ export interface VerifiedSessionDeleteTarget {
 	detachedArtifactsPath?: string;
 	/** Identity-bound quarantine path retained when transcript unlink deferred cleanup. */
 	detachedTranscriptPath?: string;
+	/** Native-retained publisher successor observed during transcript cleanup. */
+	retainedTranscriptSuccessorPath?: string;
+	/** Native-retained exchange placeholder observed during transcript cleanup. */
+	retainedTranscriptPlaceholderPath?: string;
+	/** Native-retained transcript entry whose identity could not be verified. */
+	retainedTranscriptUnknownPath?: string;
+	/** Native-retained publisher successor observed during cleanup. */
+	retainedArtifactsSuccessorPath?: string;
+	/** Native-retained exchange placeholder observed during cleanup. */
+	retainedArtifactsPlaceholderPath?: string;
+	/** Native-retained entry whose identity could not be verified. */
+	retainedArtifactsUnknownPath?: string;
+
 	/** Caller-published, no-replace quarantine pathname for the next artifact detach. */
 	plannedArtifactsPath?: string;
 	/** Caller-published, no-replace quarantine pathname for the next transcript detach. */
@@ -288,6 +303,9 @@ export type VerifiedSessionDeleteResult =
 			artifactsTree: NativeDirectoryTreeSnapshot;
 			/** Transcript identity (unchanged) for retry binding. */
 			transcriptIdentity: SessionStorageFileIdentity;
+			retainedSuccessorPath?: string;
+			retainedPlaceholderPath?: string;
+			retainedUnknownPath?: string;
 	  }
 	| {
 			kind: "cleanup_pending";
@@ -297,6 +315,9 @@ export type VerifiedSessionDeleteResult =
 			transcriptIdentity: SessionStorageFileIdentity;
 			/** Optional identity-bound transcript quarantine path for restart cleanup. */
 			detachedTranscriptPath?: string;
+			retainedSuccessorPath?: string;
+			retainedPlaceholderPath?: string;
+			retainedUnknownPath?: string;
 	  };
 
 /** Default OS-close dispatcher: a direct `fs.closeSync`. */
@@ -306,7 +327,22 @@ const defaultCloseAdapter: SessionStorageWriterCloseAdapter = {
 	},
 };
 
-type NativeExactUnlinkResult = { ok: true; detachedPath?: string } | { ok: false; code: string; detachedPath?: string };
+type NativeExactUnlinkResult =
+	| {
+			ok: true;
+			detachedPath?: string;
+			retainedSuccessorPath?: string;
+			retainedPlaceholderPath?: string;
+			retainedUnknownPath?: string;
+	  }
+	| {
+			ok: false;
+			code: string;
+			detachedPath?: string;
+			retainedSuccessorPath?: string;
+			retainedPlaceholderPath?: string;
+			retainedUnknownPath?: string;
+	  };
 type NativeExactUnlink = (
 	path: string,
 	identity: {
@@ -671,6 +707,21 @@ export class FileSessionStorage implements SessionStorage {
 			return [];
 		}
 	}
+	async listFilesByMtime(dir: string, pattern: string): Promise<Array<{ path: string; mtimeMs: number }>> {
+		const result = await native.glob({
+			path: dir,
+			pattern,
+			fileType: native.FileType.File,
+			recursive: false,
+			hidden: false,
+			gitignore: false,
+			sortByMtime: true,
+		});
+		return result.matches.map(match => ({
+			path: path.join(dir, match.path),
+			mtimeMs: match.mtime ?? 0,
+		}));
+	}
 
 	listFilesStrictSync(dir: string, pattern: string): string[] {
 		// Strict: never suppress scan/root errors. Authorization inventory depends on
@@ -766,7 +817,13 @@ export class FileSessionStorage implements SessionStorage {
 			expectedArtifactsIdentity,
 			expectedArtifactsTree,
 			detachedArtifactsPath,
+			retainedArtifactsSuccessorPath,
+			retainedArtifactsPlaceholderPath,
+			retainedArtifactsUnknownPath,
 			detachedTranscriptPath,
+			retainedTranscriptSuccessorPath,
+			retainedTranscriptPlaceholderPath,
+			retainedTranscriptUnknownPath,
 			plannedArtifactsPath,
 			plannedTranscriptPath,
 			artifactsRemoved,
@@ -847,7 +904,8 @@ export class FileSessionStorage implements SessionStorage {
 			if (
 				!expectedArtifactsIdentity ||
 				path.dirname(detachedArtifactsPath) !== path.dirname(transcriptPath) ||
-				!path.basename(detachedArtifactsPath).startsWith(".skc-delete-")
+				(!path.basename(detachedArtifactsPath).startsWith(".skc-delete-") &&
+					!detachedArtifactsPath.endsWith(".removing"))
 			) {
 				throw new SessionDeleteVerificationError("artifacts", "Detached artifact cleanup evidence is invalid");
 			}
@@ -882,17 +940,20 @@ export class FileSessionStorage implements SessionStorage {
 					artifactsIdentity: expectedArtifactsIdentity,
 					detachedArtifactsPath: retainedRoot,
 					artifactsTree: expectedArtifactsTree,
+					...((removal.retainedSuccessorPath ?? retainedArtifactsSuccessorPath)
+						? { retainedSuccessorPath: removal.retainedSuccessorPath ?? retainedArtifactsSuccessorPath }
+						: {}),
+					...((removal.retainedPlaceholderPath ?? retainedArtifactsPlaceholderPath)
+						? { retainedPlaceholderPath: removal.retainedPlaceholderPath ?? retainedArtifactsPlaceholderPath }
+						: {}),
+					...((removal.retainedUnknownPath ?? retainedArtifactsUnknownPath)
+						? { retainedUnknownPath: removal.retainedUnknownPath ?? retainedArtifactsUnknownPath }
+						: {}),
 					transcriptIdentity,
 				};
 			}
 		}
 
-		if (artifactsRemoved && (detachedArtifactsPath || expectedArtifactsIdentity)) {
-			throw new SessionDeleteVerificationError(
-				"artifacts",
-				"Artifact phase receipt conflicts with pending artifact cleanup",
-			);
-		}
 		const artifactsDir = transcriptPath.slice(0, -6);
 		const artifactsIdentity = this.#optionalDirectoryIdentity(artifactsDir);
 		if (artifactsRemoved && artifactsIdentity) {
@@ -947,12 +1008,48 @@ export class FileSessionStorage implements SessionStorage {
 				directory: true,
 				quarantineName: path.basename(plannedArtifactsPath),
 			});
-			if (!detach.ok || !detach.detachedPath) {
+			if (!detach.detachedPath) {
 				throw new SessionDeleteVerificationError(
 					"artifacts",
 					`Exact artifact detach rejected: ${detach.ok ? "missing_path" : detach.code}`,
 				);
 			}
+			if (!detach.ok && process.platform !== "win32") {
+				let descriptor: number | undefined;
+				try {
+					descriptor = fs.openSync(
+						path.dirname(transcriptPath),
+						fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW,
+					);
+					const durableParent = fs.fstatSync(descriptor, { bigint: true });
+					if (
+						!durableParent.isDirectory() ||
+						durableParent.dev !== parentIdentity.dev ||
+						durableParent.ino !== parentIdentity.ino
+					)
+						throw new Error("parent_changed");
+					fs.fsyncSync(descriptor);
+				} catch (error) {
+					throw new SessionDeleteVerificationError("artifacts", "durability_failed", { cause: toError(error) });
+				} finally {
+					if (descriptor !== undefined) fs.closeSync(descriptor);
+				}
+			}
+			if (!detach.ok) {
+				return {
+					kind: "cleanup_pending",
+					phase: "artifacts",
+					error: new SessionDeleteVerificationError("artifacts", `Exact artifact detach retained: ${detach.code}`),
+					artifactsIdentity,
+					detachedArtifactsPath: detach.detachedPath,
+					artifactsTree,
+					...(detach.retainedSuccessorPath ? { retainedSuccessorPath: detach.retainedSuccessorPath } : {}),
+					...(detach.retainedPlaceholderPath ? { retainedPlaceholderPath: detach.retainedPlaceholderPath } : {}),
+					...(detach.retainedUnknownPath ? { retainedUnknownPath: detach.retainedUnknownPath } : {}),
+
+					transcriptIdentity,
+				};
+			}
 			const removal = removeDirectoryTreeExact(detach.detachedPath, artifactsTree);
 			if (!removal.ok) {
 				const retainedRoot = removal.detachedPath ?? detach.detachedPath;
@@ -971,6 +1068,15 @@ export class FileSessionStorage implements SessionStorage {
 					artifactsIdentity,
 					detachedArtifactsPath: retainedRoot,
 					artifactsTree,
+					...((removal.retainedSuccessorPath ?? retainedArtifactsSuccessorPath)
+						? { retainedSuccessorPath: removal.retainedSuccessorPath ?? retainedArtifactsSuccessorPath }
+						: {}),
+					...((removal.retainedPlaceholderPath ?? retainedArtifactsPlaceholderPath)
+						? { retainedPlaceholderPath: removal.retainedPlaceholderPath ?? retainedArtifactsPlaceholderPath }
+						: {}),
+					...((removal.retainedUnknownPath ?? retainedArtifactsUnknownPath)
+						? { retainedUnknownPath: removal.retainedUnknownPath ?? retainedArtifactsUnknownPath }
+						: {}),
 					transcriptIdentity,
 				};
 			}
@@ -1010,13 +1116,27 @@ export class FileSessionStorage implements SessionStorage {
 			});
 			if (!deletion.ok) {
 				const error = exactUnlinkFailure(deletion);
-				if (error.kind === "identity" || error.kind === "symlink") throw error;
+				const retainedAuthority =
+					deletion.detachedPath ||
+					deletion.retainedSuccessorPath ||
+					deletion.retainedPlaceholderPath ||
+					deletion.retainedUnknownPath;
+				if ((error.kind === "identity" || error.kind === "symlink") && !retainedAuthority) throw error;
 				return {
 					kind: "cleanup_pending",
 					phase: "transcript",
 					error,
 					transcriptIdentity,
 					detachedTranscriptPath: deletion.detachedPath ?? detachedTranscriptPath,
+					...((deletion.retainedSuccessorPath ?? retainedTranscriptSuccessorPath)
+						? { retainedSuccessorPath: deletion.retainedSuccessorPath ?? retainedTranscriptSuccessorPath }
+						: {}),
+					...((deletion.retainedPlaceholderPath ?? retainedTranscriptPlaceholderPath)
+						? { retainedPlaceholderPath: deletion.retainedPlaceholderPath ?? retainedTranscriptPlaceholderPath }
+						: {}),
+					...((deletion.retainedUnknownPath ?? retainedTranscriptUnknownPath)
+						? { retainedUnknownPath: deletion.retainedUnknownPath ?? retainedTranscriptUnknownPath }
+						: {}),
 				};
 			}
 			return { kind: "deleted" };
@@ -1058,13 +1178,27 @@ export class FileSessionStorage implements SessionStorage {
 		});
 		if (!deletion.ok) {
 			const error = exactUnlinkFailure(deletion);
-			if (error.kind === "identity" || error.kind === "symlink") throw error;
+			const retainedAuthority =
+				deletion.detachedPath ||
+				deletion.retainedSuccessorPath ||
+				deletion.retainedPlaceholderPath ||
+				deletion.retainedUnknownPath;
+			if ((error.kind === "identity" || error.kind === "symlink") && !retainedAuthority) throw error;
 			return {
 				kind: "cleanup_pending",
 				phase: "transcript",
 				error,
 				transcriptIdentity,
 				detachedTranscriptPath: deletion.detachedPath,
+				...((deletion.retainedSuccessorPath ?? retainedTranscriptSuccessorPath)
+					? { retainedSuccessorPath: deletion.retainedSuccessorPath ?? retainedTranscriptSuccessorPath }
+					: {}),
+				...((deletion.retainedPlaceholderPath ?? retainedTranscriptPlaceholderPath)
+					? { retainedPlaceholderPath: deletion.retainedPlaceholderPath ?? retainedTranscriptPlaceholderPath }
+					: {}),
+				...((deletion.retainedUnknownPath ?? retainedTranscriptUnknownPath)
+					? { retainedUnknownPath: deletion.retainedUnknownPath ?? retainedTranscriptUnknownPath }
+					: {}),
 			};
 		}
 		return { kind: "deleted" };
@@ -1353,6 +1487,12 @@ export class MemorySessionStorage implements SessionStorage {
 		}
 		return files;
 	}
+	listFilesByMtime(dir: string, pattern: string): Promise<Array<{ path: string; mtimeMs: number }>> {
+		const files = this.listFilesSync(dir, pattern)
+			.map(path => ({ path, mtimeMs: this.statSync(path).mtimeMs }))
+			.sort((a, b) => b.mtimeMs - a.mtimeMs);
+		return Promise.resolve(files);
+	}
 	listFilesStrictSync(dir: string, pattern: string): string[] {
 		// In-memory scan never suppresses; identical to the display scan.
 		return this.listFilesSync(dir, pattern);

package/src/session/streaming-output.ts

@@ -114,8 +114,12 @@ export interface TruncationResult {
 	elidedLines?: number;
 	lastLinePartial?: boolean;
 	firstLineExceedsLimit?: boolean;
+	lastLineExceedsLimit?: boolean;
 }
 
+/** Direction vocabulary used by callers that select which end of content to retain. */
+export type TruncationDirection = "head" | "last" | "both";
+
 export interface TruncationOptions {
 	/** Maximum number of lines (default: 3000) */
 	maxLines?: number;
@@ -131,6 +135,8 @@ export interface TruncationOptions {
 	 * window receives `maxLines - maxHeadLines`. Default `floor(maxLines/2)`.
 	 */
 	maxHeadLines?: number;
+	/** Direction to dispatch through truncateContent (head, last, or both). */
+	direction?: TruncationDirection;
 }
 
 /** Result from byte-level truncation helpers. */
@@ -452,6 +458,7 @@ export function truncateTail(content: string, options: TruncationOptions = {}):
 					outputBytes: tail.bytes,
 					lastLinePartial: true,
 					firstLineExceedsLimit: false,
+					lastLineExceedsLimit: true,
 				};
 			}
 			break;
@@ -474,6 +481,7 @@ export function truncateTail(content: string, options: TruncationOptions = {}):
 					outputBytes: tail.bytes,
 					lastLinePartial: true,
 					firstLineExceedsLimit: false,
+					lastLineExceedsLimit: true,
 				};
 			}
 			break;
@@ -516,14 +524,129 @@ export function formatMiddleElisionMarker(elidedLines: number, elidedBytes: numb
 }
 
 /**
- * Truncate content keeping a head window and a tail window, eliding the middle.
+ * A retained source segment returned by {@link truncateMiddleWindows}.
+ * Line coordinates are 1-indexed and inclusive.
+ */
+export type ReadSegment =
+	| {
+			kind: "lines";
+			content: string;
+			lines: number;
+			bytes: number;
+			origin: { startLine: number; endLine: number };
+			lastLinePartial: false;
+	  }
+	| {
+			kind: "partial-line";
+			content: string;
+			lines: 1;
+			bytes: number;
+			origin: { startLine: number; endLine: number };
+			sourceLineBytes: number;
+			lastLinePartial: true;
+	  };
+
+/** The actual windows retained by middle truncation. */
+export interface ReadWindow {
+	kind: "full" | "head-only" | "tail-only" | "middle";
+	head?: ReadSegment;
+	tail?: ReadSegment;
+	// With normalized head/tail line budgets, an overlap cannot occur: a
+	// source that can fit both windows returns `full`, otherwise their kept
+	// line counts sum to less than the source. Retain this defensive value for
+	// custom/future budgets and wire compatibility.
+	overlap: "disjoint" | "adjacent" | "overlapping";
+	elidedLines: number;
+	elidedBytes: number;
+	totalLines: number;
+	totalBytes: number;
+	/** @deprecated Non-enumerable compatibility reason for older consumers. */
+	truncatedBy?: "lines" | "bytes" | "middle";
+}
+
+function outputLineCount(result: TruncationResult): number {
+	return result.outputLines ?? (result.content.length === 0 ? 0 : countNewlines(result.content) + 1);
+}
+
+function outputByteCount(result: TruncationResult): number {
+	return result.outputBytes ?? Buffer.byteLength(result.content, "utf-8");
+}
+
+function lastSourceLineBytes(content: string): number {
+	const lineStart = content.lastIndexOf(NL) + 1;
+	return Buffer.byteLength(content.slice(lineStart), "utf-8");
+}
+
+function makeReadSegment(
+	result: TruncationResult,
+	startLine: number,
+	totalLines: number,
+	sourceContent: string = result.content,
+): ReadSegment | undefined {
+	const lines = outputLineCount(result);
+	if (lines <= 0) return undefined;
+	const bytes = outputByteCount(result);
+	const endLine = Math.min(totalLines, startLine + lines - 1);
+	if (result.lastLinePartial) {
+		const partialLine = endLine;
+		return {
+			kind: "partial-line",
+			content: result.content,
+			lines: 1,
+			bytes,
+			origin: { startLine: partialLine, endLine: partialLine },
+			sourceLineBytes: lastSourceLineBytes(sourceContent),
+			lastLinePartial: true,
+		};
+	}
+	return {
+		kind: "lines",
+		content: result.content,
+		lines,
+		bytes,
+		origin: { startLine, endLine },
+		lastLinePartial: false,
+	};
+}
+
+function withMiddleWindowReason(windows: ReadWindow, truncatedBy: "lines" | "bytes" | "middle"): ReadWindow {
+	Object.defineProperty(windows, "truncatedBy", { value: truncatedBy, enumerable: false });
+	return windows;
+}
+
+function fullReadWindow(
+	content: string,
+	totalLines: number,
+	totalBytes: number,
+	overlap: ReadWindow["overlap"] = "disjoint",
+): ReadWindow {
+	return {
+		kind: "full",
+		head: {
+			kind: "lines",
+			content,
+			lines: totalLines,
+			bytes: totalBytes,
+			origin: { startLine: 1, endLine: totalLines },
+			lastLinePartial: false,
+		},
+		overlap,
+		elidedLines: 0,
+		elidedBytes: 0,
+		totalLines,
+		totalBytes,
+	};
+}
+
+/**
+ * Truncate content while exposing the exact retained head/tail windows.
  *
- * The combined output is `<head>\n<marker>\n<tail>` when truncation is needed.
- * `maxHeadBytes` defaults to `floor(maxBytes / 2)`; the tail receives the
- * remainder. Falls back to `truncateTail` / `truncateHead` if either side's
- * budget is empty or the content already fits.
+ * The budget split and fallback ordering intentionally mirror truncateMiddle.
+ * The overlap classification is performed before resolving an overlap to a
+ * full window, so callers can distinguish disjoint, adjacent and overlapping
+ * candidate windows even when no marker is needed.
  */
-export function truncateMiddle(content: string, options: TruncationOptions = {}): TruncationResult {
+export function truncateMiddleWindows(content: string, options: TruncationOptions = {}): ReadWindow {
 	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
 	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
 	const headBytes = options.maxHeadBytes ?? Math.floor(maxBytes / 2);
@@ -533,57 +656,153 @@ export function truncateMiddle(content: string, options: TruncationOptions = {})
 
 	const totalBytes = Buffer.byteLength(content, "utf-8");
 	const totalLines = countNewlines(content) + 1;
+	if (totalBytes <= maxBytes && totalLines <= maxLines) return fullReadWindow(content, totalLines, totalBytes);
+
+	const oneSided = (kind: "head-only" | "tail-only", result: TruncationResult, startLine: number): ReadWindow => {
+		const lines = outputLineCount(result);
+		const bytes = outputByteCount(result);
+		const segment = makeReadSegment(result, startLine, totalLines, content);
+
+		const windows: ReadWindow = {
+			kind,
+			...(kind === "head-only" ? (segment ? { head: segment } : {}) : segment ? { tail: segment } : {}),
+			overlap: "disjoint",
+			elidedLines: Math.max(0, totalLines - lines),
+			elidedBytes: Math.max(0, totalBytes - bytes),
+			totalLines,
+			totalBytes,
+		};
+		return withMiddleWindowReason(windows, result.truncatedBy === "lines" ? "lines" : "bytes");
+	};
 
-	if (totalBytes <= maxBytes && totalLines <= maxLines) {
-		return noTruncResult(content, totalLines, totalBytes);
-	}
-
-	// Degenerate budgets → fall back to one-sided truncation.
+	// Keep this order identical to truncateMiddle: degenerate budgets are
+	// resolved before either one-sided truncator is called.
 	if (headBytes <= 0 || headLines <= 0) {
-		return truncateTail(content, { maxBytes: tailBytes || maxBytes, maxLines: tailLines || maxLines });
+		const tail = truncateTail(content, { maxBytes: tailBytes || maxBytes, maxLines: tailLines || maxLines });
+		return oneSided("tail-only", tail, totalLines - outputLineCount(tail) + 1);
 	}
 	if (tailBytes <= 0 || tailLines <= 0) {
-		return truncateHead(content, { maxBytes: headBytes, maxLines: headLines });
+		const head = truncateHead(content, { maxBytes: headBytes, maxLines: headLines });
+		return oneSided("head-only", head, 1);
 	}
 
 	const head = truncateHead(content, { maxBytes: headBytes, maxLines: headLines });
 	const tail = truncateTail(content, { maxBytes: tailBytes, maxLines: tailLines });
-
-	const headLinesKept = head.outputLines ?? 0;
-	const tailLinesKept = tail.outputLines ?? 0;
-	const headBytesKept = head.outputBytes ?? Buffer.byteLength(head.content, "utf-8");
-	const tailBytesKept = tail.outputBytes ?? Buffer.byteLength(tail.content, "utf-8");
+	const headLinesKept = outputLineCount(head);
+	const tailLinesKept = outputLineCount(tail);
+	const headBytesKept = outputByteCount(head);
+	const tailBytesKept = outputByteCount(tail);
 
 	// Head unusable (first line exceeds budget) → tail-only.
-	if (headLinesKept === 0 || head.firstLineExceedsLimit) return tail;
+	if (headLinesKept === 0 || head.firstLineExceedsLimit) {
+		return oneSided("tail-only", tail, totalLines - tailLinesKept + 1);
+	}
 	// Tail unusable → head-only.
-	if (tailLinesKept === 0) return head;
-	// Windows overlap → no meaningful elision; return content untruncated.
-	if (headLinesKept + tailLinesKept >= totalLines) {
-		return noTruncResult(content, totalLines, totalBytes);
+	if (tailLinesKept === 0) return oneSided("head-only", head, 1);
+
+	const headEnd = headLinesKept;
+	const tailStart = totalLines - tailLinesKept + 1;
+	const overlap: ReadWindow["overlap"] =
+		headEnd + 1 < tailStart ? "disjoint" : headEnd + 1 === tailStart ? "adjacent" : "overlapping";
+	const tailPartial = tail.lastLinePartial === true;
+
+	// Adjacent/overlapping complete windows cover the whole source. Return one
+	// full segment so renderers never insert a marker for an overlap.
+	if (headLinesKept + tailLinesKept >= totalLines && !tailPartial) {
+		return fullReadWindow(content, totalLines, totalBytes, overlap);
 	}
 
-	const elidedLines = totalLines - headLinesKept - tailLinesKept;
-	// `totalBytes - headBytesKept - tailBytesKept` includes newline separators
-	// between the kept windows and the elided region; close enough for a notice.
-	const elidedBytes = Math.max(0, totalBytes - headBytesKept - tailBytesKept);
-	const marker = formatMiddleElisionMarker(elidedLines, elidedBytes);
-	const composed = `${head.content}\n${marker}\n${tail.content}`;
-	const markerBytes = Buffer.byteLength(marker, "utf-8");
+	const headWindow = makeReadSegment(head, 1, totalLines, content);
+	const tailWindow = makeReadSegment(tail, tailStart, totalLines, content);
+	if (!headWindow || !tailWindow) return fullReadWindow(content, totalLines, totalBytes, overlap);
+
+	const partialSourceBytes = tailWindow.kind === "partial-line" ? tailWindow.sourceLineBytes : tailWindow.bytes;
+	const elidedLines = tailPartial
+		? Math.max(0, tailStart - headEnd - 1)
+		: Math.max(0, totalLines - headLinesKept - tailLinesKept);
+	const elidedBytes = tailPartial
+		? Math.max(0, totalBytes - headBytesKept - partialSourceBytes)
+		: Math.max(0, totalBytes - headBytesKept - tailBytesKept);
+	return withMiddleWindowReason(
+		{
+			kind: "middle",
+			head: headWindow,
+			tail: tailWindow,
+			overlap,
+			elidedLines,
+			elidedBytes,
+			totalLines,
+			totalBytes,
+		},
+		"middle",
+	);
+}
 
-	return {
-		content: composed,
-		truncated: true,
-		truncatedBy: "middle",
-		totalLines,
-		totalBytes,
-		outputLines: headLinesKept + tailLinesKept + 1,
-		outputBytes: headBytesKept + tailBytesKept + markerBytes + 2,
-		elidedLines,
-		elidedBytes,
-		lastLinePartial: tail.lastLinePartial,
-		firstLineExceedsLimit: false,
-	};
+/**
+ * Truncate content keeping a head window and a tail window, eliding the middle.
+ * The composed return shape remains field-for-field compatible with the
+ * historical implementation; callers that need coordinates use
+ * truncateMiddleWindows directly.
+ */
+export function truncateMiddle(content: string, options: TruncationOptions = {}): TruncationResult {
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+	const headBytes = options.maxHeadBytes ?? Math.floor(maxBytes / 2);
+	const tailBytes = Math.max(0, maxBytes - headBytes);
+	const headLines = options.maxHeadLines ?? Math.max(1, Math.floor(maxLines / 2));
+	const tailLines = Math.max(0, maxLines - headLines);
+	const windows = truncateMiddleWindows(content, options);
+
+	switch (windows.kind) {
+		case "full":
+			return noTruncResult(content, windows.totalLines, windows.totalBytes);
+		case "tail-only":
+			return truncateTail(content, { maxBytes: tailBytes || maxBytes, maxLines: tailLines || maxLines });
+		case "head-only":
+			return truncateHead(content, { maxBytes: headBytes, maxLines: headLines });
+		case "middle": {
+			const head = windows.head;
+			const tail = windows.tail;
+			if (!head || !tail) return noTruncResult(content, windows.totalLines, windows.totalBytes);
+			if (head.lines + tail.lines >= windows.totalLines)
+				return noTruncResult(content, windows.totalLines, windows.totalBytes);
+			const legacyElidedLines = Math.max(0, windows.totalLines - head.lines - tail.lines);
+			const legacyElidedBytes =
+				tail.kind === "partial-line"
+					? Math.max(0, windows.totalBytes - head.bytes - tail.bytes)
+					: windows.elidedBytes;
+			const marker = formatMiddleElisionMarker(legacyElidedLines, legacyElidedBytes);
+			const markerBytes = Buffer.byteLength(marker, "utf-8");
+			return {
+				content: `${head.content}\n${marker}\n${tail.content}`,
+				truncated: true,
+				truncatedBy: "middle",
+				totalLines: windows.totalLines,
+				totalBytes: windows.totalBytes,
+				outputLines: head.lines + tail.lines + 1,
+				outputBytes: head.bytes + tail.bytes + markerBytes + 2,
+				elidedLines: legacyElidedLines,
+				elidedBytes: legacyElidedBytes,
+				lastLinePartial: tail.lastLinePartial,
+				firstLineExceedsLimit: false,
+				...(tail.lastLinePartial ? { lastLineExceedsLimit: true } : {}),
+			};
+		}
+	}
+}
+
+/**
+ * Dispatch truncation using the caller-facing direction vocabulary.
+ */
+export function truncateContent(content: string, options: TruncationOptions = {}): TruncationResult {
+	switch (options.direction) {
+		case "last":
+			return truncateTail(content, options);
+		case "both":
+			return truncateMiddle(content, options);
+		default:
+			return truncateHead(content, options);
+	}
 }
 
 // =============================================================================