dsh-context 0.69.1 → 0.70.0

package/lib/index.d.ts

@@ -57,6 +57,9 @@ interface TimelineState {
   provider?: string;
   lastModel?: string;
   contextWindow?: number;
+  /** The newest `request/header` envelope's routed output cap (dsh materializes the adapter default
+   * into it). Last-wins: a header omitting the cap clears it. */
+  maxOutputTokens?: number;
   requests: RequestRecord[];
   /** The number of turn runs in `requests` (a run = consecutive records sharing one `turn`). Maintained
    * incrementally at the single append site and recomputed when a trim replaces the array, so the retention
@@ -249,6 +252,9 @@ interface Snapshot {
   model?: string;
   provider?: string;
   contextWindow?: number;
+  /** The newest request envelope's routed output cap, which auto-compaction reserves before pricing
+   * its pressure trigger. Absent = no cap in the log (or a row folded before the field existed). */
+  maxOutputTokens?: number;
   current: {
     system: number;
     tools: number;

package/lib/index.js

@@ -1,30 +1,36 @@
 /**
- * dsh-context v0.69.1
+ * dsh-context v0.70.0
  * A DeepSeek Harness plugin for context insight and management, with context dashboard and context command, for understanding how the context is made of, and how it evolves.
  * @author bowenliang123
  * @license Apache-2.0
  * @homepage https://github.com/bowenliang123/dsh-context
- * @built 2026-10-12T00:44:06+00:00
- * @commit f6ab4a29ff9d
- * @commit-date 2026-10-12T08:40:43+08:00
+ * @built 2026-10-13T23:50:32+00:00
+ * @commit 854ce14aad18
+ * @commit-date 2026-10-14T07:45:49+08:00
  */
 
 import { createRequire } from "node:module";
 import { z } from "zod";
 import { deriveEventMessage, interruptedTurnClosers } from "@deepseek-ai/dsh-session";
 import z$1 from "@deepseek-ai/schemastery";
+import { copyFile, link, mkdir } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, normalize, relative } from "node:path";
+import { getHeapStatistics } from "node:v8";
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, isAbsolute, join, normalize, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getHeapStatistics } from "node:v8";
+import { performance } from "node:perf_hooks";
 import { randomUUID } from "node:crypto";
 //#region src/shared/estimate.ts
 const CHARS_PER_TOKEN$1 = 4;
 const ROLE_OVERHEAD$1 = 4;
+const BLOCK_OVERHEAD$1 = 4;
 function estimateSystemTokens(text) {
 	if (typeof text !== "string" || text.length === 0) return 0;
 	return Math.ceil(text.length / CHARS_PER_TOKEN$1) + ROLE_OVERHEAD$1;
 }
+function estimateTextTokens(text) {
+	return Math.ceil(text.length / CHARS_PER_TOKEN$1) + BLOCK_OVERHEAD$1;
+}
 function estimateSystemContent(blocks) {
 	if (!Array.isArray(blocks) || blocks.length === 0) return 0;
 	let characters = 0;
@@ -161,7 +167,7 @@ function estimateBlocks(blocks) {
 		switch (block.type) {
 			case "text":
 			case "reasoning":
-				tokens += Math.ceil((block.text || "").length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
+				tokens += estimateTextTokens(block.text || "");
 				break;
 			case "tool-call":
 				tokens += Math.ceil((block.name || "").length / CHARS_PER_TOKEN) + Math.ceil((block.arguments || "").length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
@@ -763,6 +769,7 @@ function headFieldsOf(state) {
 		...state.model !== void 0 ? { model: state.model } : {},
 		...state.provider !== void 0 ? { provider: state.provider } : {},
 		...state.contextWindow !== void 0 ? { contextWindow: state.contextWindow } : {},
+		...state.maxOutputTokens !== void 0 ? { maxOutputTokens: state.maxOutputTokens } : {},
 		current: {
 			system: state.systemTokens,
 			tools: state.toolsTokens,
@@ -1096,6 +1103,9 @@ function applyTimeline(state, event, bounds) {
 				s.toolsTokens = estimateToolsTotal(tools);
 				if (header.config && typeof header.config.model === "string") s.model = header.config.model;
 				if (header.config && typeof header.config.provider === "string") s.provider = header.config.provider;
+				const maxOutputTokens = header.config?.maxTokens;
+				if (typeof maxOutputTokens === "number" && Number.isFinite(maxOutputTokens) && maxOutputTokens > 0) s.maxOutputTokens = maxOutputTokens;
+				else delete s.maxOutputTokens;
 				if ((data?.reason === "change" || data?.reason === "resume") && s.model && s.lastModel && s.model !== s.lastModel) {
 					s.events.push({
 						seq: event.seq,
@@ -1748,6 +1758,7 @@ const contextTimelineSchema = z.object({
 	model: z.string().optional(),
 	provider: z.string().optional(),
 	contextWindow: z.number().optional(),
+	maxOutputTokens: z.number().positive().optional(),
 	current: currentSchema,
 	images: z.number().int().nonnegative().optional(),
 	toolCalls: z.number().int().nonnegative().optional(),
@@ -1787,6 +1798,7 @@ const timelineStateSchema = z.object({
 	provider: z.string().optional(),
 	lastModel: z.string().optional(),
 	contextWindow: z.number().optional(),
+	maxOutputTokens: z.number().positive().optional(),
 	requests: z.array(requestRecordSchema),
 	turnRuns: z.number().int().nonnegative().optional(),
 	events: z.array(contextEventSchema),
@@ -1833,7 +1845,7 @@ function createContextTimelineDefinition(config, slim) {
 		},
 		init: () => createTimelineState(),
 		apply: (state, event) => applyTimeline(state, event, bounds),
-		stateVersion: 27
+		stateVersion: 28
 	};
 }
 //#endregion
@@ -2027,6 +2039,277 @@ function createContextActivityDefinition() {
 		stateVersion: 4
 	};
 }
+//#endregion
+//#region src/shared/attachment.ts
+const EXTENSION_IMAGE = new Set([
+	"png",
+	"jpg",
+	"jpeg",
+	"gif",
+	"webp",
+	"bmp",
+	"ico",
+	"svg"
+]);
+function leafNameOf(name) {
+	return name.slice(Math.max(name.lastIndexOf("/"), name.lastIndexOf("\\")) + 1);
+}
+function attachmentExtension(name) {
+	const base = leafNameOf(name);
+	const dot = base.lastIndexOf(".");
+	return dot < 0 ? "" : base.slice(dot + 1).toLowerCase();
+}
+function isImageName(name) {
+	return EXTENSION_IMAGE.has(attachmentExtension(name));
+}
+function numOf(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function dimensionsOf(value) {
+	if (value === null || typeof value !== "object") return void 0;
+	const dims = value;
+	const width = numOf(dims.width);
+	const height = numOf(dims.height);
+	return width !== void 0 && height !== void 0 ? {
+		width,
+		height
+	} : void 0;
+}
+function attachmentOf(block) {
+	if (block === null || typeof block !== "object") return null;
+	const b = block;
+	const spelling = typeof b.type === "string" ? b.type : b.kind;
+	if (spelling !== "image" && spelling !== "file") return null;
+	if (b.attachment === null || typeof b.attachment !== "object") return null;
+	const a = b.attachment;
+	if (typeof a.attachmentId !== "string" || a.attachmentId === "") return null;
+	const name = typeof a.name === "string" && a.name !== "" ? a.name : void 0;
+	const bytes = numOf(a.bytes);
+	if (spelling === "file") return {
+		kind: "file",
+		attachmentId: a.attachmentId,
+		...name !== void 0 ? { name } : {},
+		...bytes !== void 0 ? { bytes } : {}
+	};
+	const origDims = dimensionsOf(a.originalDimensions);
+	const width = numOf(a.width);
+	const height = numOf(a.height);
+	const mediaType = typeof a.mediaType === "string" && a.mediaType !== "" ? a.mediaType : void 0;
+	return {
+		kind: "image",
+		attachmentId: a.attachmentId,
+		...name !== void 0 ? { name } : {},
+		...mediaType !== void 0 ? { mediaType } : {},
+		...bytes !== void 0 ? { bytes } : {},
+		...width !== void 0 ? { width } : {},
+		...height !== void 0 ? { height } : {},
+		...origDims !== void 0 ? { originalDimensions: origDims } : {}
+	};
+}
+//#endregion
+//#region src/host/coldRead.ts
+const HIGH_WATER = 2 / 3;
+function v8Reading() {
+	const stats = getHeapStatistics();
+	return {
+		used: stats.used_heap_size,
+		limit: stats.heap_size_limit
+	};
+}
+const noop = () => {};
+function makeColdReadGate(reading = v8Reading) {
+	const clear = () => {
+		try {
+			const { used, limit } = reading();
+			if (!Number.isFinite(used) || !Number.isFinite(limit) || limit <= 0) return true;
+			return used < limit * HIGH_WATER;
+		} catch {
+			return true;
+		}
+	};
+	let tail = Promise.resolve();
+	return { admit(read) {
+		const run = tail.then(() => clear() ? read() : void 0);
+		tail = run.then(noop, noop);
+		return run;
+	} };
+}
+//#endregion
+//#region src/host/connection.ts
+function fetchRouteRegistrar(connection) {
+	return typeof connection?.fetch?.register === "function" ? connection.fetch.register.bind(connection.fetch) : void 0;
+}
+function registerPostRoute(c, connection, path, fetch, label) {
+	const register = fetchRouteRegistrar(connection);
+	if (register === void 0) return false;
+	try {
+		c.effect(() => register({
+			path,
+			methods: ["POST"],
+			requestBody: "buffered",
+			fetch
+		}), label);
+	} catch {
+		return false;
+	}
+	return true;
+}
+//#endregion
+//#region src/host/attachment.ts
+const ATTACHMENT_ROUTE = "/api/dsh-context/attachment";
+const IMAGE_MEDIA_EXTENSION = {
+	"image/png": "png",
+	"image/jpeg": "jpg",
+	"image/webp": "webp",
+	"image/gif": "gif"
+};
+function reply$2(value) {
+	return Response.json(value, { headers: { "cache-control": "no-store" } });
+}
+function failure$2(code, message) {
+	return reply$2({
+		ok: false,
+		error: {
+			code,
+			message
+		}
+	});
+}
+function asRecord$2(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+const WALK_MAX_DEPTH = 8;
+function attachmentIn(value, id, depth) {
+	if (depth > WALK_MAX_DEPTH) return null;
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			const hit = attachmentIn(item, id, depth + 1);
+			if (hit !== null) return hit;
+		}
+		return null;
+	}
+	if (value === null || typeof value !== "object") return null;
+	const ref = attachmentOf(value);
+	if (ref !== null && ref.attachmentId === id) return ref;
+	for (const child of Object.values(value)) {
+		const hit = attachmentIn(child, id, depth + 1);
+		if (hit !== null) return hit;
+	}
+	return null;
+}
+function referencedAttachmentOf(events, attachmentId) {
+	for (const entry of events) try {
+		const hit = attachmentIn(entry, attachmentId, 0);
+		if (hit !== null) return hit;
+	} catch {}
+	return null;
+}
+function imagePreviewNameOf(ref) {
+	const leaf = leafNameOf(ref.name ?? "");
+	if (leaf !== "" && isImageName(leaf)) return leaf;
+	const extension = ref.mediaType !== void 0 ? IMAGE_MEDIA_EXTENSION[ref.mediaType] : void 0;
+	return extension === void 0 ? null : `attachment.${extension}`;
+}
+function previewAliasDirOf(objectPath) {
+	const root = dirname(dirname(dirname(objectPath)));
+	if (basename(root) !== "v1" || basename(dirname(root)) !== "attachments") return null;
+	return join(dirname(dirname(root)), "cache", "dsh-context", "previews");
+}
+function filePathOf(store, ref) {
+	if (typeof store?.fileHostPath !== "function") return null;
+	try {
+		const path = store.fileHostPath({
+			attachmentId: ref.attachmentId,
+			name: ref.name ?? "",
+			bytes: ref.bytes ?? 0
+		});
+		return typeof path === "string" && path !== "" ? path : null;
+	} catch {
+		return null;
+	}
+}
+async function imageAliasOf(store, ref) {
+	if (typeof store?.imageHostPath !== "function") return null;
+	let objectPath;
+	try {
+		objectPath = store.imageHostPath({
+			attachmentId: ref.attachmentId,
+			...ref.mediaType !== void 0 ? { mediaType: ref.mediaType } : {},
+			...ref.bytes !== void 0 ? { bytes: ref.bytes } : {},
+			...ref.width !== void 0 ? { width: ref.width } : {},
+			...ref.height !== void 0 ? { height: ref.height } : {},
+			...ref.name !== void 0 ? { name: ref.name } : {}
+		});
+	} catch {
+		return null;
+	}
+	if (typeof objectPath !== "string" || objectPath === "") return null;
+	const name = imagePreviewNameOf(ref);
+	if (name === null) return null;
+	const directory = previewAliasDirOf(objectPath);
+	if (directory === null) return null;
+	const alias = join(directory, basename(dirname(objectPath)), basename(objectPath), name);
+	try {
+		await mkdir(dirname(alias), { recursive: true });
+		try {
+			await link(objectPath, alias);
+		} catch (err) {
+			if (!(err instanceof Error && "code" in err && err.code === "EEXIST")) await copyFile(objectPath, alias);
+		}
+		return alias;
+	} catch {
+		return null;
+	}
+}
+async function previewPathOf(store, ref) {
+	return ref.kind === "file" ? filePathOf(store, ref) : await imageAliasOf(store, ref);
+}
+function watchAttachmentChannel(ctx, coldReads = makeColdReadGate()) {
+	ctx.inject(["connection"], (c) => {
+		const handler = async (request) => {
+			let sessionId;
+			let attachmentId;
+			try {
+				const body = asRecord$2(await request.json());
+				sessionId = body?.sessionId;
+				attachmentId = body?.attachmentId;
+			} catch {
+				return failure$2("dsh-context/bad-request", "body is not JSON");
+			}
+			if (typeof sessionId !== "string" || sessionId === "") return failure$2("dsh-context/bad-request", "missing sessionId");
+			if (typeof attachmentId !== "string" || attachmentId === "") return failure$2("dsh-context/bad-request", "missing attachmentId");
+			try {
+				const query = ctx.get("sessionQuery");
+				const observe = typeof query?.observeSession === "function" ? query.observeSession.bind(query) : void 0;
+				if (observe === void 0) return reply$2({
+					ok: true,
+					value: null
+				});
+				const store = ctx.get("attachments");
+				return reply$2({
+					ok: true,
+					value: await coldReads.admit(async () => {
+						const observation = await observe(sessionId, { projectionMode: "none" });
+						try {
+							const events = observation?.events;
+							if (!Array.isArray(events)) return null;
+							const ref = referencedAttachmentOf(events, attachmentId);
+							if (ref === null) return null;
+							const path = await previewPathOf(store, ref);
+							return path === null ? null : { path };
+						} finally {
+							const dispose = observation?.[Symbol.dispose];
+							if (typeof dispose === "function") dispose.call(observation);
+						}
+					}) ?? null
+				});
+			} catch (err) {
+				return failure$2("gateway/internal", err instanceof Error ? err.message : String(err));
+			}
+		};
+		registerPostRoute(c, c.get("connection"), ATTACHMENT_ROUTE, handler, "dsh-context: attachment route");
+	});
+}
 function mcpServerOf(name) {
 	if (!name.startsWith("mcp__")) return void 0;
 	const cut = name.lastIndexOf("__");
@@ -2192,26 +2475,6 @@ function asRecord$1(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 //#endregion
-//#region src/host/connection.ts
-function fetchRouteRegistrar(connection) {
-	return typeof connection?.fetch?.register === "function" ? connection.fetch.register.bind(connection.fetch) : void 0;
-}
-function registerPostRoute(c, connection, path, fetch, label) {
-	const register = fetchRouteRegistrar(connection);
-	if (register === void 0) return false;
-	try {
-		c.effect(() => register({
-			path,
-			methods: ["POST"],
-			requestBody: "buffered",
-			fetch
-		}), label);
-	} catch {
-		return false;
-	}
-	return true;
-}
-//#endregion
 //#region src/host/balance.ts
 const BALANCE_ROUTE = "/api/dsh-context/balance";
 const DEEPSEEK_SETTINGS_NS = "llm-deepseek";
@@ -2329,37 +2592,17 @@ function watchBalanceChannel(ctx) {
 	});
 }
 //#endregion
-//#region src/host/coldRead.ts
-const HIGH_WATER = 2 / 3;
-function v8Reading() {
-	const stats = getHeapStatistics();
-	return {
-		used: stats.used_heap_size,
-		limit: stats.heap_size_limit
-	};
-}
-const noop = () => {};
-function makeColdReadGate(reading = v8Reading) {
-	const clear = () => {
-		try {
-			const { used, limit } = reading();
-			if (!Number.isFinite(used) || !Number.isFinite(limit) || limit <= 0) return true;
-			return used < limit * HIGH_WATER;
-		} catch {
-			return true;
-		}
-	};
-	let tail = Promise.resolve();
-	return { admit(read) {
-		const run = tail.then(() => clear() ? read() : void 0);
-		tail = run.then(noop, noop);
-		return run;
-	} };
-}
-//#endregion
 //#region src/host/backfill.ts
 const BACKFILL_ROUTE = "/api/dsh-context/backfill";
-const YIELD_MS = 100;
+const MIN_REST_MS = 25;
+const SLICE_EVENTS = 2e3;
+const DEFAULT_PACING = {
+	now: () => performance.now(),
+	sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+	minRestMs: MIN_REST_MS,
+	workBudgetMs: 8e3,
+	roundPauseMs: 2e3
+};
 const UNSUPPORTED_FORMAT = "SessionFormatUnsupported";
 function headerOf(record) {
 	const header = asRecord$1(asRecord$1(record)?.header);
@@ -2403,6 +2646,49 @@ function isLive(sessions, id) {
 		return true;
 	}
 }
+async function coldSnapshotSliced(ctx, faces, sessions, log, signal, rest, now) {
+	const { header, inheritedEventCount, events } = log;
+	let rows = {};
+	let workMs = 0;
+	for (let end = SLICE_EVENTS;; end += SLICE_EVENTS) {
+		const last = end >= events.length;
+		const started = now();
+		rows = asRecord$1(faces.restore(rows, last ? events : events.slice(0, end), 0, header, inheritedEventCount))?.checkpoint ?? {};
+		const sliceCost = now() - started;
+		workMs += sliceCost;
+		if (last) break;
+		await rest(sliceCost);
+		if (signal.aborted) return {
+			outcome: "aborted",
+			workMs
+		};
+	}
+	let prepared;
+	try {
+		prepared = faces.prepare(header.id, {
+			seed: events,
+			meta: structuredClone(header),
+			inheritedEventCount,
+			eventState: "shared-frozen"
+		});
+	} catch (error) {
+		if (isLive(sessions, header.id)) return {
+			outcome: "live",
+			workMs
+		};
+		throw error;
+	}
+	faces.hydrate(prepared, rows, events, 0);
+	try {
+		await faces.write(prepared);
+	} catch (error) {
+		ctx.logger.warn(`dsh-context: projection backfill write-back for "${header.id}" failed (cache stays stale): ${messageOf$1(error)}`);
+	}
+	return {
+		outcome: "done",
+		workMs
+	};
+}
 function isUnsupportedFormat(error) {
 	try {
 		return String(asRecord$1(error)?.name).startsWith(UNSUPPORTED_FORMAT);
@@ -2417,7 +2703,7 @@ function messageOf$1(error) {
 		return "unprintable error";
 	}
 }
-function watchActivityBackfill(ctx, coldReads = makeColdReadGate()) {
+function watchActivityBackfill(ctx, coldReads = makeColdReadGate(), pacing = DEFAULT_PACING) {
 	let requested = false;
 	let started = false;
 	let launch = null;
@@ -2448,6 +2734,13 @@ function watchActivityBackfill(ctx, coldReads = makeColdReadGate()) {
 		if (cache === null || typeof cache.cachedSnapshot !== "function" || typeof cache.coldSnapshot !== "function") return;
 		if (persistence === null || typeof persistence.open !== "function") return;
 		const sessions = asRecord$1(injected.sessions);
+		const registry = asRecord$1(ctx.sessionProjections);
+		const sliceFaces = registry !== null && typeof registry.restore === "function" && typeof registry.hydrate === "function" && sessions !== null && typeof sessions.prepare === "function" && typeof cache.write === "function" ? {
+			restore: registry.restore.bind(registry),
+			hydrate: registry.hydrate.bind(registry),
+			prepare: sessions.prepare.bind(sessions),
+			write: cache.write.bind(cache)
+		} : null;
 		const abort = new AbortController();
 		const run = async () => {
 			const listed = await query.listSessions(abort.signal);
@@ -2455,29 +2748,63 @@ function watchActivityBackfill(ctx, coldReads = makeColdReadGate()) {
 			let folded = 0;
 			let refused = 0;
 			let paused = false;
+			let roundWork = 0;
+			const sleep = async (ms) => {
+				if (abort.signal.aborted) return;
+				let onAbort;
+				try {
+					await Promise.race([pacing.sleep(ms), new Promise((resolve) => {
+						onAbort = () => {
+							resolve();
+						};
+						abort.signal.addEventListener("abort", onAbort, { once: true });
+					})]);
+				} finally {
+					abort.signal.removeEventListener("abort", onAbort);
+				}
+			};
+			const rest = async (costMs) => {
+				roundWork += costMs;
+				if (roundWork >= pacing.workBudgetMs) {
+					roundWork = 0;
+					ctx.logger.info(`dsh-context: projection backfill pausing after ${Math.round(pacing.workBudgetMs / 1e3)}s of fold work; resuming in ${Math.round(pacing.roundPauseMs / 1e3)}s`);
+					await sleep(pacing.roundPauseMs);
+					return;
+				}
+				await sleep(Math.max(pacing.minRestMs, costMs));
+			};
 			for (const record of listed) {
 				if (abort.signal.aborted) return;
 				const header = headerOf(record);
 				if (header === null || typeof header.cwd !== "string") continue;
 				if (isLive(sessions, header.id)) continue;
 				if (servesRows(cache, header)) continue;
+				const started = pacing.now();
+				let slicedWorkMs = 0;
 				try {
-					if (await coldReads.admit(async () => {
+					const admitted = await coldReads.admit(async () => {
 						const log = await readColdLog(persistence, header.id, abort.signal);
+						if (sliceFaces !== null && log.events.length > SLICE_EVENTS) {
+							const sliced = await coldSnapshotSliced(ctx, sliceFaces, sessions, log, abort.signal, rest, pacing.now);
+							slicedWorkMs = sliced.workMs;
+							return sliced.outcome;
+						}
 						cache.coldSnapshot(log.header, log.inheritedEventCount, log.events);
-						return true;
-					}) === void 0) {
+						return "done";
+					});
+					if (admitted === void 0) {
 						paused = true;
 						break;
 					}
-					folded++;
+					if (admitted === "aborted") return;
+					if (admitted === "done") folded++;
 				} catch (error) {
 					if (isUnsupportedFormat(error)) {
 						refused++;
 						ctx.logger.debug(`dsh-context: projection backfill skipped "${header.id}" (${messageOf$1(error)})`);
 					} else ctx.logger.warn(`dsh-context: projection backfill skipped "${header.id}" (${messageOf$1(error)})`);
 				}
-				await new Promise((resolve) => setTimeout(resolve, YIELD_MS));
+				await rest(Math.max(0, pacing.now() - started - slicedWorkMs));
 			}
 			if (folded > 0) ctx.logger.info(`dsh-context: projection rows backfilled for ${folded} session(s)`);
 			if (paused) ctx.logger.info("dsh-context: projection backfill stopped early under heap pressure (remaining sessions refold on their next live activity)");
@@ -2497,6 +2824,12 @@ function watchActivityBackfill(ctx, coldReads = makeColdReadGate()) {
 		for (const fiber of [routeFiber, runnerFiber]) fiber?.dispose?.();
 	};
 }
+const FOLD_YIELD_EVENTS = 1e3;
+const PAYLOAD_CACHE_MAX = 4;
+function revisionOf(observation) {
+	const revision = observation?.revision;
+	return typeof revision === "string" && revision !== "" ? revision : void 0;
+}
 function reply$1(value) {
 	return Response.json(value, { headers: { "cache-control": "no-store" } });
 }
@@ -2511,6 +2844,7 @@ function failure$1(code, message) {
 }
 function watchDetailChannel(ctx, bounds, coldReads = makeColdReadGate()) {
 	const gate = { live: false };
+	const payloads = new Map();
 	ctx.inject(["connection", "sessions"], (c) => {
 		const sessions = c.get("sessions");
 		const getSession = typeof sessions?.get === "function" ? sessions.get.bind(sessions) : void 0;
@@ -2548,16 +2882,43 @@ function watchDetailChannel(ctx, bounds, coldReads = makeColdReadGate()) {
 					ok: true,
 					value: await coldReads.admit(async () => {
 						const observation = await observe(sessionId, { projectionMode: "none" });
-						const events = observation?.events;
-						if (!Array.isArray(events)) return null;
-						let state = createTimelineState();
 						try {
-							for (const ev of events) state = applyTimeline(state, ev, bounds);
+							const persistence = ctx.get("sessionPersistence");
+							const revision = revisionOf(observation);
+							if (revision !== void 0) {
+								const hit = payloads.get(sessionId);
+								if (hit !== void 0 && hit.revision === revision && hit.persistence === persistence) {
+									payloads.delete(sessionId);
+									payloads.set(sessionId, hit);
+									return hit.value;
+								}
+							}
+							const events = observation?.events;
+							if (!Array.isArray(events)) return null;
+							let state = createTimelineState();
+							let folded = 0;
+							for (const ev of events) {
+								state = applyTimeline(state, ev, bounds);
+								if (++folded % FOLD_YIELD_EVENTS === 0) await new Promise((resolve) => setTimeout(resolve, 0));
+							}
+							const detail = buildTimelineDetail(state, bounds);
+							if (revision !== void 0) {
+								payloads.delete(sessionId);
+								payloads.set(sessionId, {
+									persistence,
+									revision,
+									value: detail
+								});
+								for (const oldest of payloads.keys()) {
+									if (payloads.size <= PAYLOAD_CACHE_MAX) break;
+									payloads.delete(oldest);
+								}
+							}
+							return detail;
 						} finally {
 							const dispose = observation?.[Symbol.dispose];
 							if (typeof dispose === "function") dispose.call(observation);
 						}
-						return buildTimelineDetail(state, bounds);
 					}) ?? null
 				});
 			} catch (err) {
@@ -3267,6 +3628,7 @@ function apply(ctx, config) {
 	watchBalanceChannel(ctx);
 	watchSkillCatalog(ctx);
 	watchFleetChannel(ctx, coldReads);
+	watchAttachmentChannel(ctx, coldReads);
 	const harnessVersion = detectHarnessVersion(ctx);
 	if (harnessVersion !== void 0 && !meetsBaseline(harnessVersion)) {
 		ctx.sessionProjections.register(createFallbackTimelineDefinition(harnessVersion));