@openclaw/codex 2026.9.5 → 2026.9.7

package/dist/.setup/{session-catalog-index-B141u15s.mjs → session-catalog-index-CZvDzC6z.mjs}

@@ -1,38 +1,105 @@
-import { C as codexCatalogThreadName, D as normalizeLimit, M as readControlCursor, T as filterCatalogPageByTitle, V as CODEX_CATALOG_MAX_ROWS, c as getCodexCatalogSource, g as CatalogParamsError, r as projectCodexCatalogNativeThread, u as setCodexCatalogSource, v as MAX_CWD_LENGTH, w as codexCatalogThreadStatus, x as boundedCatalogString } from "./session-catalog-native-projection-ChV3cCtm.mjs";
-import { i as retainCodexCatalogRow, n as codexCatalogRowRecency, r as compareCodexCatalogRows, t as CodexCatalogOrdering } from "./session-catalog-index-order-Cc5BzlQr.mjs";
-import { n as CodexCatalogPersistence, r as codexCatalogMetadataPage } from "./session-catalog-index-state-BAuDztHN.mjs";
-import { a as withCodexCatalogListRequest, s as CodexCatalogAvailability } from "./session-catalog-fUdWDx-U.mjs";
-import { i as subscribeCodexCatalogEvents } from "./session-catalog-events-jMcYfQyd.mjs";
-import { CodexCatalogProjectionCapacityError, CodexCatalogProjections, i as scanCodexCatalogRollouts, mergeCodexCatalogRolloutRow, n as isCodexCatalogRolloutPathCovered, projectCodexCatalogThread, r as readCodexCatalogRollout, t as codexCatalogRolloutLogicalPath } from "./session-catalog-projection-C1Bj9Jl-.mjs";
+import { S as readControlCursor, _ as normalizeLimit, c as MAX_CWD_LENGTH, d as boundedCatalogString, h as filterCatalogPageByTitle, m as codexCatalogThreadStatus, o as CatalogParamsError, p as codexCatalogThreadName } from "./session-catalog-parsing-CPGaPYr-.mjs";
+import { t as CODEX_CATALOG_MAX_ROWS } from "./session-catalog-limits-DDxOsQeC.mjs";
+import { i as retainCodexCatalogRow, n as codexCatalogRowRecency, r as compareCodexCatalogRows, t as CodexCatalogOrdering } from "./session-catalog-index-order-BcQpHks3.mjs";
+import { n as CodexCatalogPersistence, r as codexCatalogMetadataPage } from "./session-catalog-index-state-TeO7EyO-.mjs";
+import { i as CodexCatalogAvailability, r as withCodexCatalogListRequest } from "./session-catalog-list-request-CvtxrYSe.mjs";
+import { a as reportCodexCatalogSpawnFailure, n as findCodexAppServerSpawnError } from "./spawn-error-CL3n6MAa.mjs";
+import { l as getCodexCatalogSource, p as setCodexCatalogSource, r as projectCodexCatalogNativeThread, u as hasLiveCodexCatalogSource } from "./session-catalog-native-projection-DjhwGL6x.mjs";
+import { i as subscribeCodexCatalogEvents } from "./session-catalog-events-DePDzzjc.mjs";
+import { CodexCatalogProjectionCapacityError, CodexCatalogProjections, a as resolveCodexCatalogRolloutFingerprint, i as readCodexCatalogRollout, mergeCodexCatalogRolloutRow, n as indexCodexCatalogRowsByRollout, o as scanCodexCatalogRollouts, projectCodexCatalogThread, r as isCodexCatalogRolloutPathCovered, t as codexCatalogRolloutLogicalPath } from "./session-catalog-projection-Cr5qP5Dj.mjs";
 import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { embeddedAgentLog } from "openclaw/plugin-sdk/agent-harness-registration";
+import { coerceErrorMessage, toErrorObject } from "openclaw/plugin-sdk/error-runtime";
 import { setImmediate as setImmediate$1 } from "node:timers/promises";
-import { toErrorObject } from "openclaw/plugin-sdk/error-runtime";
 import { sanitizeTerminalText } from "openclaw/plugin-sdk/text-chunking";
 //#region extensions/codex/src/session-catalog-currency.ts
+const SAFETY_INTERVAL_MS = 9e5;
 /** One periodic reconciliation cycle per home, without a recursive watcher inventory. */
 var CodexCatalogCurrency = class {
 	constructor(options) {
 		this.options = options;
 		this.closed = false;
+		this.nativeDirty = false;
+		this.nextNativeAt = 0;
+		this.nextFilesAt = 0;
+	}
+	hasActiveWork() {
+		return this.hydration !== void 0 || this.initial !== void 0 || this.running !== void 0 || this.safetyRefresh !== void 0;
+	}
+	assertRunnable() {
+		if (this.terminalFailure) throw this.terminalFailure;
+	}
+	stopForTerminalFailure(error) {
+		const failure = findCodexAppServerSpawnError(error);
+		if (!failure) return false;
+		if (!this.closed) {
+			this.terminalFailure = failure;
+			this.close();
+			reportCodexCatalogSpawnFailure(failure);
+		}
+		return true;
+	}
+	scheduleHydration(run) {
+		if (this.closed || this.hydration) return;
+		this.hydration = setImmediate(() => {
+			this.hydration = void 0;
+			(this.options.runBackground ? this.options.runBackground(run) : run()).catch((error) => this.options.report(error));
+		});
+		this.hydration.unref();
+	}
+	cancelHydration() {
+		clearImmediate(this.hydration);
+		this.hydration = void 0;
+	}
+	requestNativeRefresh() {
+		this.nativeDirty = true;
+	}
+	/** Full safety walks serve catalog demand; an idle resident index does not start one. */
+	refreshNativeIfDue() {
+		if (this.closed || !this.timer || Date.now() < this.nextNativeAt) return Promise.resolve();
+		if (this.safetyRefresh) return this.safetyRefresh;
+		const refresh = async () => {
+			if (this.running) await this.running;
+			if (this.closed || Date.now() < this.nextNativeAt) return;
+			const run = () => this.options.reconcileNative(true);
+			await Promise.resolve().then(() => this.options.runBackground ? this.options.runBackground(run) : run()).catch((error) => {
+				this.options.report(new Error(`Codex catalog reconciliation failed; waiting for the next safety interval and catalog demand: ${coerceErrorMessage(error)}`, { cause: error }));
+			});
+			this.nextNativeAt = Date.now() + SAFETY_INTERVAL_MS;
+		};
+		this.safetyRefresh = refresh().finally(() => {
+			this.safetyRefresh = void 0;
+		});
+		return this.safetyRefresh;
 	}
 	start() {
 		if (this.closed || this.timer) return;
+		this.nextNativeAt = Date.now() + SAFETY_INTERVAL_MS;
+		this.nextFilesAt = this.nextNativeAt;
 		this.timer = setInterval(() => {
 			if (this.running) return;
+			const startedAt = Date.now();
+			const filesDue = this.options.local && startedAt >= this.nextFilesAt;
+			const nativeDue = this.nativeDirty && !this.safetyRefresh;
+			if (!filesDue && !nativeDue) return;
+			if (nativeDue) this.nativeDirty = false;
+			if (filesDue) this.nextFilesAt = startedAt + SAFETY_INTERVAL_MS;
 			const run = async () => {
-				await this.options.reconcileFiles();
-				await this.options.reconcileNative();
+				if (filesDue) await this.options.reconcileFiles();
+				if (nativeDue) await this.options.reconcileNative(false);
 			};
-			this.running = (this.options.runBackground ? this.options.runBackground(run) : run()).catch((error) => this.options.report(error)).finally(() => {
+			this.running = (this.options.runBackground ? this.options.runBackground(run) : run()).catch((error) => {
+				this.options.report(new Error(`Codex catalog reconciliation failed; waiting for new activity or the next file safety cycle: ${coerceErrorMessage(error)}`, { cause: error }));
+			}).finally(() => {
 				this.running = void 0;
 			});
 		}, 3e4);
 		this.timer.unref();
 		if (this.options.local) {
 			this.initial = setTimeout(() => {
+				this.initial = void 0;
 				this.options.reconcileFiles().catch((error) => this.options.report(error));
 			}, 0);
 			this.initial.unref();
@@ -40,8 +107,13 @@ var CodexCatalogCurrency = class {
 	}
 	close() {
 		this.closed = true;
+		this.cancelHydration();
 		clearInterval(this.timer);
+		this.timer = void 0;
 		clearTimeout(this.initial);
+		this.initial = void 0;
+		if (this.running && this.safetyRefresh) return Promise.allSettled([this.running, this.safetyRefresh]).then(() => {});
+		return this.running ?? this.safetyRefresh;
 	}
 };
 //#endregion
@@ -118,6 +190,9 @@ var CodexCatalogIndexEvents = class {
 		this.pending = /* @__PURE__ */ new Map();
 		this.upserting = /* @__PURE__ */ new Set();
 	}
+	hasActiveWork() {
+		return this.pending.size > 0 || this.upserting.size > 0;
+	}
 	handle(event, readThread, source) {
 		if (this.closed || !isRecord(event.params)) return;
 		const params = event.params;
@@ -161,7 +236,7 @@ var CodexCatalogIndexEvents = class {
 		}
 		if (event.method === "turn/started" || event.method === "turn/completed" || event.method === "thread/unarchived" || event.method === "thread/reverted") {
 			if (event.method !== "thread/unarchived" && this.owner.get(id)?.archived) return;
-			this.enqueueRefresh(id, readThread, event.method === "turn/started" ? this.owner.reserveTurnStartOrder() : void 0);
+			this.enqueueRefresh(id, readThread, source, event.method === "turn/started" ? this.owner.reserveTurnStartOrder() : void 0);
 		}
 	}
 	hasCapacity() {
@@ -169,10 +244,12 @@ var CodexCatalogIndexEvents = class {
 		this.owner.report(/* @__PURE__ */ new Error("Codex catalog event queue reached its resident row limit"));
 		return false;
 	}
-	enqueueRefresh(id, readThread, sourceOrder) {
+	enqueueRefresh(id, readThread, source, sourceOrder) {
+		this.owner.requestNativeRefresh();
 		const existing = this.pending.get(id);
 		if (existing) {
 			existing.readThread = readThread;
+			existing.source = source;
 			existing.dirty = true;
 			existing.sourceOrder = sourceOrder ?? existing.sourceOrder;
 			return;
@@ -180,6 +257,7 @@ var CodexCatalogIndexEvents = class {
 		if (!this.hasCapacity()) return;
 		const pending = {
 			readThread,
+			source,
 			dirty: true,
 			sourceOrder,
 			promise: Promise.resolve()
@@ -190,12 +268,17 @@ var CodexCatalogIndexEvents = class {
 				while (!this.closed && pending.dirty) {
 					pending.dirty = false;
 					const observedSourceOrder = pending.sourceOrder;
+					const observedSource = pending.source;
 					try {
+						if (observedSource.closed) throw new Error("Codex catalog observation source closed before its metadata read");
 						const published = await this.owner.refresh(id, pending.readThread, observedSourceOrder);
 						if (published && pending.sourceOrder === observedSourceOrder) pending.sourceOrder = void 0;
 						else if (!published && pending.sourceOrder !== void 0) pending.dirty = true;
 					} catch (error) {
-						this.owner.report(error);
+						if (observedSource.closed) {
+							if (pending.source === observedSource) pending.dirty = false;
+							this.owner.report(new Error("Codex catalog observation interrupted by client closure; metadata refresh deferred to the current catalog owner", { cause: error }), "deferred");
+						} else this.owner.report(error);
 					}
 				}
 			} finally {
@@ -288,6 +371,9 @@ var CodexCatalogObservations = class {
 		this.mutations = /* @__PURE__ */ new Map();
 		this.observations = /* @__PURE__ */ new Map();
 	}
+	hasActiveWork() {
+		return this.observations.size > 0;
+	}
 	mark(threadId) {
 		this.revision++;
 		if (this.observations.size) {
@@ -319,6 +405,83 @@ var CodexCatalogObservations = class {
 	}
 };
 //#endregion
+//#region extensions/codex/src/session-catalog-status.ts
+function applyCodexCatalogLiveFields({ status: _storedStatus, activeFlags: _storedFlags, ...session }, live, settings) {
+	return {
+		...session,
+		...settings,
+		status: live?.status ?? "notLoaded",
+		...live?.activeFlags ? { activeFlags: [...live.activeFlags] } : {}
+	};
+}
+const MAX_STATUS_SOURCE_WITNESSES = 64;
+/** Equivalent broadcasts retain at most 64 source witnesses for each bounded resident row. */
+var CodexCatalogStatusIndex = class {
+	constructor() {
+		this.values = new CodexCatalogField();
+	}
+	capture() {
+		return this.values.capture();
+	}
+	update(threadId, status, source) {
+		const next = this.next(threadId, status, source);
+		if (next) this.values.update(threadId, next);
+	}
+	observe(row, revision) {
+		const session = row.page.sessions[0];
+		const source = getCodexCatalogSource(row);
+		if (session && source) {
+			const next = this.next(row.threadId, {
+				status: session.status,
+				...session.activeFlags ? { activeFlags: session.activeFlags } : {}
+			}, source);
+			if (next) this.values.observe(row.threadId, next, revision);
+		}
+	}
+	get(threadId) {
+		const current = this.values.get(threadId);
+		return current && hasLiveCodexCatalogSource(current.sources) ? current.status : void 0;
+	}
+	delete(threadId) {
+		this.values.delete(threadId);
+	}
+	invalidate(source) {
+		if (!source) {
+			this.values.invalidate();
+			return;
+		}
+		this.values.deleteWhere((entry) => {
+			entry.sources.delete(source);
+			return !hasLiveCodexCatalogSource(entry.sources);
+		});
+	}
+	next(threadId, status, source) {
+		if (source.closed) return;
+		const current = this.values.get(threadId);
+		const sources = new Set([...current?.sources ?? []].filter((witness) => !witness.closed));
+		if (status.status === "notLoaded" && current && current.status.status !== "notLoaded" && sources.size) {
+			sources.delete(source);
+			if (sources.size) return {
+				status: current.status,
+				sources
+			};
+		}
+		const flags = status.activeFlags ?? [];
+		const previousFlags = current?.status.activeFlags ?? [];
+		if (current?.status.status === status.status && flags.length === previousFlags.length && flags.every((flag, index) => flag === previousFlags[index])) {
+			if (sources.size < MAX_STATUS_SOURCE_WITNESSES) sources.add(source);
+			return {
+				status,
+				sources
+			};
+		}
+		return {
+			status,
+			sources: /* @__PURE__ */ new Set([source])
+		};
+	}
+};
+//#endregion
 //#region extensions/codex/src/session-catalog-index-query.ts
 /** Keyset pagination remains valid when the anchor row is archived or deleted. */
 function prepareCodexCatalogQuery(params, prepared) {
@@ -331,9 +494,9 @@ function prepareCodexCatalogQuery(params, prepared) {
 		const { complete, frontier } = availability;
 		if (!complete && !frontier) return;
 		if (!complete && frontier && anchor?.backwards && compareCodexCatalogRows(frontier, anchor) < 0) return;
-		const candidates = ordered.filter((row) => {
+		const candidates = complete && !cwd && !search ? ordered : ordered.filter((row) => {
 			const session = row.page.sessions[0];
-			return !row.archived && session && (complete || !frontier || compareCodexCatalogRows(row, frontier) <= 0) && (!cwd || (liveSettings.get(row.threadId)?.cwd ?? session.cwd) === cwd) && (!search || (session.name ?? session.fallbackName)?.toLocaleLowerCase().includes(search));
+			return session && (complete || !frontier || compareCodexCatalogRows(row, frontier) <= 0) && (!cwd || (liveSettings.get(row.threadId)?.cwd ?? session.cwd) === cwd) && (!search || (session.name ?? session.fallbackName)?.toLocaleLowerCase().includes(search));
 		});
 		const selected = anchor?.backwards ? candidates.filter((row) => row.threadId !== anchor.threadId) : candidates;
 		let start = 0;
@@ -360,15 +523,7 @@ function prepareCodexCatalogQuery(params, prepared) {
 			continuation = frontier && (!last || compareCodexCatalogRows(frontier, last) > 0) ? frontier : last;
 		}
 		return {
-			sessions: page.flatMap((row) => row.page.sessions.map(({ status: _storedStatus, activeFlags: _storedFlags, ...session }) => {
-				const live = liveStatus.get(row.threadId);
-				return {
-					...session,
-					...liveSettings.get(row.threadId),
-					status: live?.status ?? "notLoaded",
-					...live?.activeFlags ? { activeFlags: [...live.activeFlags] } : {}
-				};
-			})),
+			sessions: page.flatMap((row) => row.page.sessions.map((session) => applyCodexCatalogLiveFields(session, liveStatus.get(row.threadId), liveSettings.get(row.threadId)))),
 			...continuation ? { nextCursor: cursor(continuation, false) } : {},
 			...first && start > 0 ? { backwardsCursor: cursor(first, true) } : {}
 		};
@@ -376,6 +531,36 @@ function prepareCodexCatalogQuery(params, prepared) {
 }
 //#endregion
 //#region extensions/codex/src/session-catalog-native-page.ts
+/** Background walks share bounded native pages; the index decides when a prefix is current. */
+async function* readCodexCatalogHydrationPages(read, useStateDbOnly) {
+	let cursor;
+	let offset = 0;
+	const cursors = /* @__PURE__ */ new Set();
+	do {
+		const page = await read({
+			archived: false,
+			modelProviders: [],
+			sortKey: "recency_at",
+			sortDirection: "desc",
+			limit: 64,
+			...useStateDbOnly ? { useStateDbOnly } : {},
+			...cursor ? { cursor } : {}
+		}, Math.max(0, CODEX_CATALOG_MAX_ROWS - offset));
+		cursor = readControlCursor(page.nextCursor, "hydration response");
+		if (cursor && cursors.has(cursor)) throw new Error("Codex catalog repeated a hydration cursor");
+		if (cursor) {
+			cursors.add(cursor);
+			if (cursors.size > 2e4) cursors.delete(cursors.values().next().value);
+		}
+		yield {
+			...page,
+			nextCursor: cursor,
+			offset
+		};
+		offset += page.rows.length;
+		await setImmediate$1();
+	} while (cursor);
+}
 /** The resident limit bounds storage, never authoritative discovery. */
 var CodexCatalogNativePages = class {
 	constructor(settings, status) {
@@ -445,13 +630,7 @@ var CodexCatalogNativePages = class {
 				}
 				rows = selected;
 			} else if (!position.cursor && !position.backwards) previous = void 0;
-			const projected = filterCatalogPageByTitle({ sessions: rows.flatMap((row) => row.page.sessions).map(({ status: _storedStatus, activeFlags: _storedFlags, ...session }) => {
-				const live = this.status.get(session.threadId);
-				return Object.assign(session, this.settings.get(session.threadId), {
-					status: live?.status ?? "notLoaded",
-					...live?.activeFlags ? { activeFlags: [...live.activeFlags] } : {}
-				});
-			}).filter((session) => !cwd || session.cwd === cwd) }, params.searchTerm);
+			const projected = filterCatalogPageByTitle({ sessions: rows.flatMap((row) => row.page.sessions).map((session) => applyCodexCatalogLiveFields(session, this.status.get(session.threadId), this.settings.get(session.threadId))).filter((session) => !cwd || session.cwd === cwd) }, params.searchTerm);
 			const continuation = position.backwards ? previous : next;
 			if ((params.searchTerm || filterCwdLocally) && !projected.sessions.length && continuation) {
 				if (encodeCodexNativeCursor(continuation) === encodeCodexNativeCursor(position)) throw new CatalogParamsError("Codex catalog repeated a native continuation");
@@ -503,17 +682,10 @@ var CodexCatalogSettingsIndex = class {
 	}
 	get(threadId) {
 		const current = this.values.get(threadId);
-		if (current) {
-			for (const source of current.sources) if (!source.closed) return current.settings;
-		}
+		return current && hasLiveCodexCatalogSource(current.sources) ? current.settings : void 0;
 	}
 	hasLiveCwd() {
-		return this.values.some(({ settings, sources }) => {
-			if (settings.cwd) {
-				for (const source of sources) if (!source.closed) return true;
-			}
-			return false;
-		});
+		return this.values.some(({ settings, sources }) => Boolean(settings.cwd) && hasLiveCodexCatalogSource(sources));
 	}
 	delete(threadId) {
 		this.values.delete(threadId);
@@ -521,8 +693,7 @@ var CodexCatalogSettingsIndex = class {
 	withdraw(threadId, source) {
 		const current = this.values.get(threadId);
 		if (!current?.sources.delete(source)) return;
-		for (const witness of current.sources) if (!witness.closed) return;
-		this.values.delete(threadId);
+		if (!hasLiveCodexCatalogSource(current.sources)) this.values.delete(threadId);
 	}
 	invalidate(source) {
 		if (!source) {
@@ -531,84 +702,11 @@ var CodexCatalogSettingsIndex = class {
 		}
 		this.values.deleteWhere((entry) => {
 			entry.sources.delete(source);
-			for (const witness of entry.sources) if (!witness.closed) return false;
-			return true;
+			return !hasLiveCodexCatalogSource(entry.sources);
 		});
 	}
 };
 //#endregion
-//#region extensions/codex/src/session-catalog-status.ts
-const MAX_STATUS_SOURCE_WITNESSES = 64;
-/** Equivalent broadcasts retain at most 64 source witnesses for each bounded resident row. */
-var CodexCatalogStatusIndex = class {
-	constructor() {
-		this.values = new CodexCatalogField();
-	}
-	capture() {
-		return this.values.capture();
-	}
-	update(threadId, status, source) {
-		const next = this.next(threadId, status, source);
-		if (next) this.values.update(threadId, next);
-	}
-	observe(row, revision) {
-		const session = row.page.sessions[0];
-		const source = getCodexCatalogSource(row);
-		if (session && source) {
-			const next = this.next(row.threadId, {
-				status: session.status,
-				...session.activeFlags ? { activeFlags: session.activeFlags } : {}
-			}, source);
-			if (next) this.values.observe(row.threadId, next, revision);
-		}
-	}
-	get(threadId) {
-		const current = this.values.get(threadId);
-		if (current) {
-			for (const source of current.sources) if (!source.closed) return current.status;
-		}
-	}
-	delete(threadId) {
-		this.values.delete(threadId);
-	}
-	invalidate(source) {
-		if (!source) {
-			this.values.invalidate();
-			return;
-		}
-		this.values.deleteWhere((entry) => {
-			entry.sources.delete(source);
-			for (const witness of entry.sources) if (!witness.closed) return false;
-			return true;
-		});
-	}
-	next(threadId, status, source) {
-		if (source.closed) return;
-		const current = this.values.get(threadId);
-		const sources = new Set([...current?.sources ?? []].filter((witness) => !witness.closed));
-		if (status.status === "notLoaded" && current && current.status.status !== "notLoaded" && sources.size) {
-			sources.delete(source);
-			if (sources.size) return {
-				status: current.status,
-				sources
-			};
-		}
-		const flags = status.activeFlags ?? [];
-		const previousFlags = current?.status.activeFlags ?? [];
-		if (current?.status.status === status.status && flags.length === previousFlags.length && flags.every((flag, index) => flag === previousFlags[index])) {
-			if (sources.size < MAX_STATUS_SOURCE_WITNESSES) sources.add(source);
-			return {
-				status,
-				sources
-			};
-		}
-		return {
-			status,
-			sources: /* @__PURE__ */ new Set([source])
-		};
-	}
-};
-//#endregion
 //#region extensions/codex/src/session-catalog-index.ts
 /** One home owns resident queries and authoritative overflow discovery. */
 var CodexCatalogIndex = class {
@@ -634,7 +732,7 @@ var CodexCatalogIndex = class {
 		this.currency = new CodexCatalogCurrency({
 			local: Boolean(options.localSessionsRoot),
 			reconcileFiles: () => this.reconcile(),
-			reconcileNative: () => this.reconcileNative(),
+			reconcileNative: (full) => this.reconcileNative(full),
 			runBackground: options.runBackground,
 			report: (error) => this.report(error)
 		});
@@ -647,18 +745,24 @@ var CodexCatalogIndex = class {
 			},
 			updateSettings: (id, settings, source) => this.liveSettings.update(id, settings, source),
 			rename: (id, name) => {
+				this.currency.requestNativeRefresh();
 				this.names.update(id, name);
 				const row = this.rows.get(id);
 				if (row && !this.closed) this.put(row);
 			},
 			upsert: (thread) => this.upsertThread(thread),
 			reserveTurnStartOrder: () => this.ordering.reserveEvent(),
+			requestNativeRefresh: () => this.currency.requestNativeRefresh(),
 			refresh: (id, readThread, sourceOrder) => this.refreshThread(id, readThread, sourceOrder),
 			archive: (id) => this.archive(id),
-			remove: (id) => this.remove(id),
-			report: (error) => this.report(error)
+			remove: (id) => {
+				this.currency.requestNativeRefresh();
+				this.remove(id);
+			},
+			report: (error, disposition) => this.report(error, disposition)
 		});
 		this.unsubscribe = subscribeCodexCatalogEvents(options.homeId, (event, readThread, source) => this.events.handle(event, readThread, source), {
+			onEphemeralThread: (id) => this.remove(id),
 			onClose: (source) => {
 				this.liveStatus.invalidate(source);
 				this.liveSettings.invalidate(source);
@@ -686,8 +790,8 @@ var CodexCatalogIndex = class {
 			throw error;
 		}
 	}
-	report(error) {
-		if (!this.closed) embeddedAgentLog.warn("Codex resident catalog background update failed", { error });
+	report(error, disposition) {
+		if (!this.closed && !this.currency.stopForTerminalFailure(error)) embeddedAgentLog.warn(disposition === "deferred" ? "Codex resident catalog metadata refresh interrupted; deferred for automatic recovery" : "Codex resident catalog background update failed", { error });
 	}
 	withName(row) {
 		const known = this.names.get(row.threadId);
@@ -729,8 +833,8 @@ var CodexCatalogIndex = class {
 	}
 	async initialize() {
 		this.assertCurrent();
-		clearImmediate(this.background);
-		this.background = void 0;
+		this.currency.assertRunnable();
+		this.currency.cancelHydration();
 		if (this.initialized && !this.needsNativeRefresh) return;
 		if (!this.initializing) {
 			this.availability.begin();
@@ -743,7 +847,7 @@ var CodexCatalogIndex = class {
 				if (!this.initialized) {
 					let observedRevision;
 					do
-						observedRevision = await this.observations.observe((isCurrent) => this.hydrate(isCurrent, this.availability.complete));
+						observedRevision = await this.hydrate(this.availability.complete);
 					while (observedRevision !== this.sourceRevision);
 					this.needsNativeRefresh = false;
 				}
@@ -758,6 +862,7 @@ var CodexCatalogIndex = class {
 			})().catch((error) => {
 				this.failure = { error };
 				this.availability.fail(error);
+				this.currency.stopForTerminalFailure(error);
 				throw error;
 			}).finally(() => {
 				this.initializing = void 0;
@@ -800,13 +905,8 @@ var CodexCatalogIndex = class {
 		await this.restoring;
 	}
 	scheduleHydration() {
-		if (this.initialized && !this.needsNativeRefresh || this.initializing || this.background || this.closed) return;
-		this.background = setImmediate(() => {
-			this.background = void 0;
-			const run = () => this.initialize();
-			(this.options.runBackground ? this.options.runBackground(run) : run()).catch((error) => this.report(error));
-		});
-		this.background.unref();
+		if (this.initialized && !this.needsNativeRefresh || this.initializing || this.closed) return;
+		this.currency.scheduleHydration(() => this.initialize());
 	}
 	captureFields() {
 		return {
@@ -823,79 +923,71 @@ var CodexCatalogIndex = class {
 			if (current && current.page.sessions[0]?.name !== session.name) this.put(current);
 		}
 	}
-	reconcileNative() {
+	reconcileNative(full = true) {
 		if (!this.options.localSessionsRoot && this.initializing && !this.initialized) return this.initializing;
-		if (!this.reconcilingNative) {
-			const refresh = this.observations.observe(async (isCurrent) => {
-				await this.hydrate(isCurrent, true);
-			});
-			this.reconcilingNative = refresh.finally(() => {
-				this.reconcilingNative = void 0;
-			});
-		}
+		if (!this.reconcilingNative) this.reconcilingNative = this.hydrate(true, !full).then(() => void 0).finally(() => {
+			this.reconcilingNative = void 0;
+		});
 		return this.reconcilingNative;
 	}
-	async hydrate(isCurrent, useStateDbOnly = false) {
+	hydrate(useStateDbOnly = false, incremental = false) {
+		const run = () => this.observations.observe((isCurrent) => this.hydratePages(isCurrent, useStateDbOnly, incremental));
+		return this.options.runNativeWalk?.(run) ?? run();
+	}
+	async hydratePages(isCurrent, useStateDbOnly, incremental) {
 		this.assertCurrent();
 		const files = this.options.localSessionsRoot && !useStateDbOnly ? (await scanCodexCatalogRollouts(this.options.localSessionsRoot, /* @__PURE__ */ new Set())).files : /* @__PURE__ */ new Map();
-		let cursor;
-		let observedRevision = this.sourceRevision;
-		let firstPage = true;
-		let sourceOrder = 0;
+		let observedRevision;
 		let frontier;
 		const batchOrder = this.ordering.captureBatch(this.availability.complete);
-		const remaining = new Map(this.rows);
-		const cursors = /* @__PURE__ */ new Set();
-		do {
+		const remaining = incremental ? void 0 : new Map(this.rows);
+		const pages = readCodexCatalogHydrationPages(async (params, remainingRows) => {
 			this.assertCurrent();
 			const fieldRevision = this.captureFields();
-			const page = await this.options.readNative({
-				archived: false,
-				modelProviders: [],
-				sortKey: "recency_at",
-				sortDirection: "desc",
-				limit: 64,
-				...useStateDbOnly ? { useStateDbOnly } : {},
-				...cursor ? { cursor } : {}
-			}, Math.max(0, CODEX_CATALOG_MAX_ROWS - sourceOrder));
+			return {
+				...await this.options.readNative(params, remainingRows),
+				fieldRevision,
+				sourceRevision: this.sourceRevision
+			};
+		}, useStateDbOnly);
+		for await (const page of pages) {
 			this.assertCurrent();
-			if (firstPage) {
-				observedRevision = this.sourceRevision;
-				firstPage = false;
+			observedRevision ??= page.sourceRevision;
+			let sourceOrder = page.offset;
+			let changed = false;
+			for (const id of page.excludedThreadIds ?? []) if (isCurrent(id)) {
+				changed ||= this.rows.has(id);
+				this.remove(id);
 			}
-			for (const id of page.excludedThreadIds ?? []) if (isCurrent(id)) this.remove(id);
 			for (const row of page.rows) {
 				const position = sourceOrder++;
 				if (position >= 2e4) continue;
-				remaining.delete(row.threadId);
-				this.observeFields(row, fieldRevision);
-				if (!isCurrent(row.threadId)) continue;
-				const logicalPath = row.rolloutPath && codexCatalogRolloutLogicalPath(row.rolloutPath);
+				remaining?.delete(row.threadId);
 				const previous = this.rows.get(row.threadId);
-				const fingerprint = logicalPath ? files.get(logicalPath) ?? files.get(`${logicalPath}.zst`) ?? (useStateDbOnly && previous?.rolloutPath && codexCatalogRolloutLogicalPath(previous.rolloutPath) === logicalPath ? previous.fingerprint : void 0) : void 0;
+				this.observeFields(row, page.fieldRevision);
+				if (!isCurrent(row.threadId)) {
+					changed = true;
+					continue;
+				}
+				const fingerprint = resolveCodexCatalogRolloutFingerprint(row.rolloutPath, useStateDbOnly ? previous : void 0, files);
 				this.observations.mark(row.threadId);
 				this.put({
 					...row,
 					sourceOrder: batchOrder(row, previous, position),
 					...fingerprint ? { fingerprint } : {}
 				});
+				changed ||= this.rows.get(row.threadId) !== previous;
 				frontier = this.rows.get(row.threadId) ?? frontier;
 			}
-			cursor = readControlCursor(page.nextCursor, "hydration response");
-			if (cursor && cursors.has(cursor)) throw new Error("Codex catalog repeated a hydration cursor");
-			if (cursor) {
-				cursors.add(cursor);
-				if (cursors.size > 2e4) cursors.delete(cursors.values().next().value);
-				this.availability.publish(frontier);
-			}
-			await setImmediate$1();
-		} while (cursor);
-		if (!useStateDbOnly || !this.options.localSessionsRoot) {
+			if (incremental && (!changed && page.rows.length > 0 || sourceOrder >= 2e4)) break;
+			if (page.nextCursor) this.availability.publish(frontier);
+		}
+		if (remaining && (!useStateDbOnly || !this.options.localSessionsRoot)) {
 			for (const [id, row] of remaining) if (isCurrent(id) && this.rows.get(id) === row) this.remove(id);
 		}
 		this.availability.publish(frontier, true);
 		await this.persistence.finishHydration(this.overflow);
-		return observedRevision;
+		return observedRevision ?? this.sourceRevision;
 	}
 	reconcile() {
 		if (!this.reconciling) this.reconciling = this.observations.observe((isCurrent) => this.reconcileFiles(isCurrent)).finally(() => {
@@ -907,7 +999,7 @@ var CodexCatalogIndex = class {
 		const root = this.options.localSessionsRoot;
 		if (!root || !this.initialized || this.closed) return;
 		this.assertCurrent();
-		const byPath = new Map([...this.rows.values()].flatMap((row) => row.rolloutPath ? [[codexCatalogRolloutLogicalPath(row.rolloutPath), row]] : []));
+		const byPath = indexCodexCatalogRowsByRollout(this.rows.values());
 		const { files, present } = await scanCodexCatalogRollouts(root, new Set(byPath.keys()));
 		this.assertCurrent();
 		const observed = new Map(files);
@@ -915,6 +1007,7 @@ var CodexCatalogIndex = class {
 			const previous = byPath.get(codexCatalogRolloutLogicalPath(file));
 			const known = this.observedFiles.get(file) ?? previous?.fingerprint;
 			if (known?.mtimeMs === fingerprint.mtimeMs && known.size === fingerprint.size) continue;
+			this.currency.requestNativeRefresh();
 			observed.delete(file);
 			if (known) observed.set(file, known);
 			let thread;
@@ -951,7 +1044,10 @@ var CodexCatalogIndex = class {
 			this.put(mergeCodexCatalogRolloutRow(row, existing, fingerprint));
 			await setImmediate$1();
 		}
-		for (const row of byPath.values()) if (row.rolloutPath && isCodexCatalogRolloutPathCovered(root, row.rolloutPath) && !present.has(codexCatalogRolloutLogicalPath(row.rolloutPath)) && this.rows.get(row.threadId) === row) this.remove(row.threadId);
+		for (const row of byPath.values()) if (row.rolloutPath && isCodexCatalogRolloutPathCovered(root, row.rolloutPath) && !present.has(codexCatalogRolloutLogicalPath(row.rolloutPath)) && this.rows.get(row.threadId) === row) {
+			this.currency.requestNativeRefresh();
+			this.remove(row.threadId);
+		}
 		this.observedFiles = observed;
 	}
 	upsertThread(thread) {
@@ -962,6 +1058,7 @@ var CodexCatalogIndex = class {
 			return Promise.resolve();
 		}
 		try {
+			this.currency.requestNativeRefresh();
 			return this.upsertPreparedThread(projectCodexCatalogNativeThread(thread, sanitizeTerminalText));
 		} catch (error) {
 			return Promise.reject(toErrorObject(error, "Codex catalog projection failed"));
@@ -996,7 +1093,7 @@ var CodexCatalogIndex = class {
 		if (projected.excludedThreadIds?.includes(thread.id)) this.remove(thread.id);
 		if (row) {
 			const previous = this.rows.get(thread.id);
-			const fingerprint = previous?.rolloutPath && row.rolloutPath && codexCatalogRolloutLogicalPath(previous.rolloutPath) === codexCatalogRolloutLogicalPath(row.rolloutPath) ? previous.fingerprint : void 0;
+			const fingerprint = resolveCodexCatalogRolloutFingerprint(row.rolloutPath, previous);
 			this.observations.mark(thread.id);
 			this.put({
 				...row,
@@ -1008,6 +1105,7 @@ var CodexCatalogIndex = class {
 	}
 	archive(threadId) {
 		if (this.closed) return;
+		this.currency.requestNativeRefresh();
 		this.observations.mark(threadId);
 		this.liveStatus.delete(threadId);
 		this.liveSettings.delete(threadId);
@@ -1022,6 +1120,9 @@ var CodexCatalogIndex = class {
 	get(threadId) {
 		return this.rows.get(threadId);
 	}
+	hasActiveWork() {
+		return Boolean(this.initializing || !this.restored && this.restoring || this.reconciling || this.reconcilingNative || this.currency.hasActiveWork() || this.observations.hasActiveWork() || this.events.hasActiveWork() || this.persistence.hasActiveWork());
+	}
 	async list(params, deadline = performance.now() + (this.options.requestTimeoutMs ?? 6e4)) {
 		return await withCodexCatalogListRequest(async (request) => {
 			const expiresAt = request.constrainDeadline(deadline);
@@ -1035,7 +1136,10 @@ var CodexCatalogIndex = class {
 				const ordered = this.ordering.read(this.rows);
 				const page = query?.(ordered, this.liveStatus, this.liveSettings, this.availability);
 				if (cursor.kind === "native" || this.overflow && (params.cwd || params.searchTerm || page && !page.nextCursor)) return await this.nativePages.list(params, cursor, this.options, request);
-				if (page) return page;
+				if (page) {
+					this.currency.refreshNativeIfDue();
+					return page;
+				}
 				await this.availability.next(expiresAt);
 			}
 		});
@@ -1048,7 +1152,6 @@ var CodexCatalogIndex = class {
 		this.liveSettings.invalidate();
 		this.unsubscribe();
 		this.currency.close();
-		clearImmediate(this.background);
 		return this.persistence.retire();
 	}
 	async close() {
@@ -1058,6 +1161,7 @@ var CodexCatalogIndex = class {
 			this.restoring,
 			this.reconciling,
 			this.reconcilingNative,
+			this.currency.close(),
 			writes,
 			this.events.close()
 		]);