first-tree-staging 0.5.7-staging.366.1 → 0.5.7-staging.367.1

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $ as documentContextSchema, At as loadAgents, B as printResults, Bt as SdkError, Ct as agentConfigSchema, Dt as defaultHome, Et as defaultDataDir, F as checkBackgroundService, Ft as channelConfig, G as isServiceUnitDriftDetected, Gt as probeCapabilities, H as getClientServiceStatus, Ht as buildMessageDocumentSnapshots, I as checkClientConfig, It as resetConfig, J as startClientService, Jt as configureClientLoggerForService, Kt as setCliBinding, L as checkNodeVersion, Lt as ClientOrgMismatchError, M as createApiNameResolver, Mt as resetConfigMeta, N as migrateLocalAgentDirs, Nt as resolveConfigReadonly, Ot as getConfigValue, P as checkAgentConfigs, Pt as setConfigValue, Q as canonicalizeResourceRepoUrl, R as checkServerReachable, Rt as ClientUserMismatchError, Tt as defaultConfigDir, U as installClientService, Ut as cleanWorkspaces, V as reconcileAgentConfigs, Vt as SessionRegistry, W as isServiceSupported, Wt as discoverClaudeCodeSkills, Y as stopClientService, Z as ClientRuntime, _ as uploadClientCapabilities, _t as removeLocalAgent, a as declineUpdate, at as ensureFreshAccessToken, b as promptMissingFields, bt as print, c as PACKAGE_NAME, d as fetchServerCommandVersion, dt as saveCredentials, et as findAssembledBriefingFingerprint, f as installGlobalLatest, ft as cliFetch, g as uploadAgentSkills, gt as formatStaleReason, h as reconcileLocalRuntimeProviders, ht as findStaleAliases, i as createExecuteUpdate, jt as readConfigFile, kt as initConfig, l as detectInstallMode, lt as resolveServerUrl, m as listPinnedAgents, mt as COMMAND_VERSION, n as decodeJwtPayload, nt as rotateClientIdWithBackup, o as promptUpdate, ot as ensureFreshAdminToken, p as installGlobalSpec, pt as CLI_USER_AGENT, q as restartClientService, qt as applyClientLoggerConfig, r as deriveHubUrlFromToken, s as refreshServerUpdateTarget, st as loadCredentials, t as HubUrlDerivationError, tt as handleClientOrgMismatch, u as fetchLatestVersion, ut as saveAgentConfig, wt as clientConfigSchema, xt as setJsonMode, y as promptAddAgent, yt as isJsonMode, z as checkWebSocket, zt as FirstTreeHubSDK } from "../connect-token-B-RM1nMS.mjs";
+import { $ as documentContextSchema, At as loadAgents, B as printResults, Bt as SdkError, Ct as agentConfigSchema, Dt as defaultHome, Et as defaultDataDir, F as checkBackgroundService, Ft as channelConfig, G as isServiceUnitDriftDetected, Gt as probeCapabilities, H as getClientServiceStatus, Ht as buildMessageDocumentSnapshots, I as checkClientConfig, It as resetConfig, J as startClientService, Jt as configureClientLoggerForService, Kt as setCliBinding, L as checkNodeVersion, Lt as ClientOrgMismatchError, M as createApiNameResolver, Mt as resetConfigMeta, N as migrateLocalAgentDirs, Nt as resolveConfigReadonly, Ot as getConfigValue, P as checkAgentConfigs, Pt as setConfigValue, Q as canonicalizeResourceRepoUrl, R as checkServerReachable, Rt as ClientUserMismatchError, Tt as defaultConfigDir, U as installClientService, Ut as cleanWorkspaces, V as reconcileAgentConfigs, Vt as SessionRegistry, W as isServiceSupported, Wt as discoverClaudeCodeSkills, Y as stopClientService, Z as ClientRuntime, _ as uploadClientCapabilities, _t as removeLocalAgent, a as declineUpdate, at as ensureFreshAccessToken, b as promptMissingFields, bt as print, c as PACKAGE_NAME, d as fetchServerCommandVersion, dt as saveCredentials, et as findAssembledBriefingFingerprint, f as installGlobalLatest, ft as cliFetch, g as uploadAgentSkills, gt as formatStaleReason, h as reconcileLocalRuntimeProviders, ht as findStaleAliases, i as createExecuteUpdate, jt as readConfigFile, kt as initConfig, l as detectInstallMode, lt as resolveServerUrl, m as listPinnedAgents, mt as COMMAND_VERSION, n as decodeJwtPayload, nt as rotateClientIdWithBackup, o as promptUpdate, ot as ensureFreshAdminToken, p as installGlobalSpec, pt as CLI_USER_AGENT, q as restartClientService, qt as applyClientLoggerConfig, r as deriveHubUrlFromToken, s as refreshServerUpdateTarget, st as loadCredentials, t as HubUrlDerivationError, tt as handleClientOrgMismatch, u as fetchLatestVersion, ut as saveAgentConfig, wt as clientConfigSchema, xt as setJsonMode, y as promptAddAgent, yt as isJsonMode, z as checkWebSocket, zt as FirstTreeHubSDK } from "../connect-token-Cd0Z_mdb.mjs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, unlinkSync } from "node:fs";
 import "node:crypto";

package/dist/{connect-token-B-RM1nMS.mjs → connect-token-Cd0Z_mdb.mjs}

@@ -14401,20 +14401,22 @@ const createClaudeCodeHandler = (config) => {
 		consumerDone = consumeOutput(sessionCtx);
 	}
 	/**
-	* Single helper for "turn closed → ack the pending inbox message AND
+	* Single helper for "turn closed → finish the pending inbox message AND
 	* drop the replay stash". The two operations are paired everywhere a
 	* turn finishes (success / sniff-permanent / forward-error / no-result /
 	* non-success subtype / MAX_RETRIES / respawn-fail) — folding them into
 	* one call keeps the invariant "stash lives only as long as the turn
 	* still might need a replay" enforced in one place. Use the raw
-	* `markMessagesCompleted(message)` directly for per-message terminal
+	* `finishTurn(message, ...)` directly for per-message terminal
 	* failures (e.g. inject's `toSDKUserMessage` catch) where the semantics is
 	* "commit this single inbox message, NOT close the active SDK turn".
 	*/
-	function ackTurnClose(sessionCtx) {
+	async function ackTurnClose(sessionCtx, status) {
 		const message = pendingAckMessages.shift();
-		if (message) sessionCtx.markMessagesCompleted(message);
-		else sessionCtx.markCompleted();
+		if (message) await sessionCtx.finishTurn(message, {
+			status,
+			terminal: true
+		});
 		markCurrentPendingMessageConsumed(sessionCtx);
 		stashedSdkMessage = null;
 	}
@@ -14440,7 +14442,11 @@ const createClaudeCodeHandler = (config) => {
 			pushPendingAckMessage(message, sessionCtx);
 		} catch (err) {
 			sessionCtx.log(`toSDKUserMessage errored: ${err instanceof Error ? err.message : String(err)}`);
-			sessionCtx.markMessagesCompleted(message);
+			await sessionCtx.finishTurn(message, {
+				status: "error",
+				terminal: true,
+				errorKind: "deterministic"
+			});
 		}
 	}
 	function scheduleInjectedMessagesDrain(sessionCtx, sessionId) {
@@ -14568,9 +14574,8 @@ const createClaudeCodeHandler = (config) => {
 			while (true) {
 				if (!currentQuery) return;
 				try {
-					sessionCtx.setRuntimeState("working");
 					for await (const message of currentQuery) {
-						sessionCtx.touch();
+						sessionCtx.recordProviderActivity();
 						toolCallProcessor.onMessage(message);
 						const authFailure = detectClaudeAuthFailure(message);
 						if (authFailure && !authHintEmitted) {
@@ -14614,7 +14619,7 @@ const createClaudeCodeHandler = (config) => {
 										kind: "turn_end",
 										payload: { status: "error" }
 									});
-									ackTurnClose(sessionCtx);
+									await ackTurnClose(sessionCtx, "error");
 								} else {
 									retryCount = 0;
 									try {
@@ -14624,7 +14629,7 @@ const createClaudeCodeHandler = (config) => {
 											kind: "turn_end",
 											payload: { status: "success" }
 										});
-										ackTurnClose(sessionCtx);
+										await ackTurnClose(sessionCtx, "success");
 									} catch (err) {
 										const reason = err instanceof Error ? err.message : String(err);
 										sessionCtx.log(`Failed to forward result: ${reason}`);
@@ -14641,7 +14646,7 @@ const createClaudeCodeHandler = (config) => {
 											payload: { status: "error" }
 										});
 										retryCount = 0;
-										ackTurnClose(sessionCtx);
+										await ackTurnClose(sessionCtx, "error");
 									}
 								}
 							} else {
@@ -14650,7 +14655,7 @@ const createClaudeCodeHandler = (config) => {
 									kind: "turn_end",
 									payload: { status: "success" }
 								});
-								ackTurnClose(sessionCtx);
+								await ackTurnClose(sessionCtx, "success");
 							}
 							else {
 								const errors = message.errors ? message.errors.join("; ") : message.subtype;
@@ -14667,13 +14672,11 @@ const createClaudeCodeHandler = (config) => {
 									kind: "turn_end",
 									payload: { status: "error" }
 								});
-								ackTurnClose(sessionCtx);
+								await ackTurnClose(sessionCtx, "error");
 							}
-							sessionCtx.setRuntimeState("idle");
 							if (message.subtype === "success") authHintEmitted = false;
 						}
 					}
-					sessionCtx.setRuntimeState("idle");
 					return;
 				} catch (err) {
 					const errMsg = err instanceof Error ? err.message : String(err);
@@ -14704,8 +14707,7 @@ const createClaudeCodeHandler = (config) => {
 						} catch (emitErr) {
 							sessionCtx.log(`Failed to emit retry-exhaustion error event: ${emitErr instanceof Error ? emitErr.message : String(emitErr)}`);
 						}
-						sessionCtx.setRuntimeState("error");
-						ackTurnClose(sessionCtx);
+						await ackTurnClose(sessionCtx, "error");
 						return;
 					}
 					toolCallProcessor.flush();
@@ -14731,8 +14733,7 @@ const createClaudeCodeHandler = (config) => {
 						} catch (emitErr) {
 							sessionCtx.log(`Failed to emit auto-resume error event: ${emitErr instanceof Error ? emitErr.message : String(emitErr)}`);
 						}
-						sessionCtx.setRuntimeState("error");
-						ackTurnClose(sessionCtx);
+						await ackTurnClose(sessionCtx, "error");
 						return;
 					}
 				}
@@ -15376,9 +15377,8 @@ var TranscriptTailer = class {
 * is NOT a success. claude was interrupted before reaching idle, so we cannot
 * confirm the work completed. Acking it would silently consume the user's
 * message with no replay path — exactly the bug this function guards. So a
-* timeout reports `turn_end: error`, leaves the inbox entries un-acked (the
-* server redelivers them on reconnect/restart for a genuine retry), and surfaces
-* an `error` runtime state.
+* timeout reports `turn_end: error` and leaves the inbox entries un-acked (the
+* server redelivers them on reconnect/restart for a genuine retry).
 *
 * Ack policy otherwise mirrors the SDK handler's `ackTurnClose`: a clean close
 * acks even on a plain forward failure (claude finished; re-running yields the
@@ -15395,8 +15395,7 @@ function resolveTurnDisposition(outcome) {
 	return {
 		status: turnFailed || forwardFailed || timedOut ? "error" : "success",
 		ack: consume,
-		forward: consume,
-		runtimeState: turnFailed || timedOut ? "error" : "idle"
+		forward: consume
 	};
 }
 const TURN_TIMEOUT_MS = 600 * 1e3;
@@ -15596,7 +15595,6 @@ const createClaudeCodeTuiHandler = (config) => {
 	async function runTurn(text, sessionCtx, messages) {
 		if (!tmuxSessionName || !transcriptTailer) throw new Error("runTurn called before session was prepared");
 		sessionCtx.markMessagesConsumed(messages);
-		sessionCtx.setRuntimeState("working");
 		turnAborted = false;
 		const state = { finalTexts: [] };
 		let turnFailed = false;
@@ -15606,11 +15604,11 @@ const createClaudeCodeTuiHandler = (config) => {
 		try {
 			transcriptTailer.drainEntries();
 			await pasteText(tmuxSessionName, text);
-			sessionCtx.touch();
+			sessionCtx.recordProviderActivity();
 			const startTs = Date.now();
 			while (Date.now() - startTs < TURN_TIMEOUT_MS) {
 				if (turnAborted) break;
-				sessionCtx.touch();
+				sessionCtx.recordProviderActivity();
 				await drainAndConsume(sessionCtx, state);
 				const working = (await capturePane(tmuxSessionName)).includes(WORKING_MARKER);
 				if (working) everSawWorking = true;
@@ -15680,12 +15678,14 @@ const createClaudeCodeTuiHandler = (config) => {
 			kind: "turn_end",
 			payload: { status: disposition.status }
 		});
-		if (disposition.ack) sessionCtx.markMessagesCompleted(messages);
+		if (disposition.ack) await sessionCtx.finishTurn(messages, {
+			status: disposition.status,
+			terminal: true
+		});
 		else {
 			const reason = timedOut ? "turn_timeout" : turnAborted ? "turn_aborted" : "turn_retryable";
-			sessionCtx.markMessagesRetryable(messages, reason);
+			sessionCtx.retryTurn(messages, reason);
 		}
-		sessionCtx.setRuntimeState(disposition.runtimeState);
 		resetProcessor();
 	}
 	/**
@@ -15710,7 +15710,11 @@ const createClaudeCodeTuiHandler = (config) => {
 				sessionCtx.log(`tui inject formatInboundContent failed: ${err instanceof Error ? err.message : String(err)}`);
 			}
 			if (inputs.length === 0) {
-				sessionCtx.markMessagesCompleted(drained);
+				await sessionCtx.finishTurn(drained, {
+					status: "error",
+					terminal: true,
+					errorKind: "deterministic"
+				});
 				return;
 			}
 			await runTurn(inputs.join("\n\n"), sessionCtx, drained);
@@ -16363,7 +16367,6 @@ const createCodexHandler = (config) => {
 		sessionCtx.markMessagesConsumed(messages);
 		const abort = new AbortController();
 		currentAbort = abort;
-		sessionCtx.setRuntimeState("working");
 		let finalResponse = "";
 		let turnFailed = false;
 		let userVisibleEmitted = false;
@@ -16383,7 +16386,7 @@ const createCodexHandler = (config) => {
 						const streamed = await activeThread.runStreamed(input, { signal: attemptAbort.signal });
 						for await (const event of streamed.events) {
 							if (attemptAbort.signal.aborted) break;
-							sessionCtx.touch();
+							sessionCtx.recordProviderActivity();
 							if (event.type === "thread.started") threadId = event.thread_id;
 							else if (event.type === "turn.started") {} else if (event.type === "item.completed") {
 								const text = processItem(event.item, sessionCtx);
@@ -16526,8 +16529,10 @@ const createCodexHandler = (config) => {
 			kind: "turn_end",
 			payload: { status: succeeded ? "success" : "error" }
 		});
-		sessionCtx.setRuntimeState("idle");
-		sessionCtx.markMessagesCompleted(messages);
+		await sessionCtx.finishTurn(messages, {
+			status: succeeded ? "success" : "error",
+			terminal: true
+		});
 		if (perTurnUsage) sessionCtx.log(`codex usage chatId=${sessionCtx.chatId} duration_ms=${Date.now() - turnStartedAt} input_tokens=${Math.max(0, perTurnUsage.input_tokens - perTurnUsage.cached_input_tokens)} cached_input_tokens=${perTurnUsage.cached_input_tokens} output_tokens=${perTurnUsage.output_tokens} reasoning_output_tokens=${perTurnUsage.reasoning_output_tokens} status=${succeeded ? "success" : "error"}`);
 		scheduleQueuedMessagesDrain();
 	}
@@ -16558,7 +16563,11 @@ const createCodexHandler = (config) => {
 			sessionCtx.log(`codex inject formatInboundContent failed: ${err instanceof Error ? err.message : String(err)}`);
 		}
 		if (inputs.length === 0) {
-			sessionCtx.markMessagesCompleted(drained);
+			await sessionCtx.finishTurn(drained, {
+				status: "error",
+				terminal: true,
+				errorKind: "deterministic"
+			});
 			return;
 		}
 		await runTurn(inputs.join("\n\n"), sessionCtx, drained);
@@ -16992,7 +17001,7 @@ var Deduplicator = class {
 	/**
 	* Drop every recorded id that starts with `prefix`. Used by the runtime
 	* when a chat is LRU-evicted: the in-flight entries for that chat won't
-	* be acked (no handler will run `markCompleted`), and the server will
+	* be acked (no handler will run `finishTurn`), and the server will
 	* resend the same `(chatId, messageId)` pairs against a fresh session.
 	* Leaving the keys in the dedup set would cause the resend to be
 	* mis-classified as a duplicate — and (post-#1-fix) re-acked, which
@@ -17022,6 +17031,361 @@ var Deduplicator = class {
 		return this.seen.size;
 	}
 };
+var InboxDeliveryCoordinator = class {
+	config;
+	deduplicator = new Deduplicator(1e3);
+	ledgers = /* @__PURE__ */ new Map();
+	recoveringChats = /* @__PURE__ */ new Map();
+	constructor(config) {
+		this.config = config;
+	}
+	receive(entry) {
+		const chatId = entry.chatId ?? entry.message.chatId;
+		const messageId = entry.message.id;
+		const ledger = this.ledger(chatId);
+		if (ledger.recoveryDebt !== "none") return { kind: "recovering" };
+		const dedupKey = this.dedupKey(chatId, messageId);
+		if (this.deduplicator.isDuplicate(dedupKey)) {
+			const stillInFlight = ledger.entries.some((tracked) => tracked.entryId === entry.id);
+			this.config.log.debug({
+				chatId,
+				messageId,
+				entryId: entry.id,
+				stillInFlight
+			}, "duplicate message observed");
+			if (stillInFlight) return { kind: "duplicate-in-flight" };
+			this.config.log.debug({
+				chatId,
+				messageId,
+				entryId: entry.id
+			}, "duplicate key is not tied to an active entry; reprocessing redelivery");
+		}
+		ledger.entries.push({
+			entryId: entry.id,
+			messageId,
+			dedupKey,
+			phase: "tracked"
+		});
+		ledger.entries.sort((a, b) => a.entryId - b.entryId);
+		this.emitWorkChanged(chatId);
+		return {
+			kind: "deliver",
+			work: {
+				chatId,
+				entryId: entry.id,
+				messageId
+			}
+		};
+	}
+	shouldRecoverBeforeDispatch(chatId, hasHealthyLiveHandler, hasLocalSessionRecord) {
+		const ledger = this.ledgers.get(chatId);
+		if (ledger?.recoveryActivationReady) {
+			ledger.recoveryActivationReady = false;
+			this.cleanupLedger(chatId);
+			return false;
+		}
+		if (ledger?.recoveryDebt === "required" || ledger?.recoveryDebt === "running") return true;
+		return Boolean(this.config.recoverChat) && hasLocalSessionRecord && !hasHealthyLiveHandler;
+	}
+	async recoverIfNeeded(chatId, reason) {
+		await this.requestRecovery(chatId, reason);
+	}
+	async requestRecovery(chatId, reason) {
+		const existing = this.recoveringChats.get(chatId);
+		if (existing) {
+			await existing;
+			return;
+		}
+		const recoverChat = this.config.recoverChat;
+		const ledger = this.ledger(chatId);
+		if (!recoverChat) {
+			ledger.recoveryDebt = "required";
+			this.emitWorkChanged(chatId);
+			this.config.log.error({
+				chatId,
+				reason
+			}, "chat requires inbox recovery but no recoverChat callback is configured");
+			return;
+		}
+		ledger.recoveryDebt = "running";
+		this.emitWorkChanged(chatId);
+		let recovery;
+		recovery = recoverChat(chatId).then(() => {
+			this.clearEntriesForRecoverySuccess(chatId);
+			const current = this.ledger(chatId);
+			current.recoveryDebt = "none";
+			current.recoveryActivationReady = true;
+			this.config.log.debug({
+				chatId,
+				reason
+			}, "chat inbox recovery accepted before dispatch");
+		}).catch((err) => {
+			const current = this.ledger(chatId);
+			current.recoveryDebt = "required";
+			this.config.log.warn({
+				chatId,
+				reason,
+				err
+			}, "chat inbox recovery failed before dispatch");
+		}).finally(() => {
+			if (this.recoveringChats.get(chatId) === recovery) this.recoveringChats.delete(chatId);
+			this.emitWorkChanged(chatId);
+		});
+		this.recoveringChats.set(chatId, recovery);
+		await recovery;
+	}
+	async runAdmission(work, op) {
+		const ledger = this.ledger(work.chatId);
+		const next = (ledger.admissionQueue ?? Promise.resolve()).then(op, op);
+		const queueMarker = next.then(() => {}, () => {});
+		ledger.admissionQueue = queueMarker;
+		this.emitWorkChanged(work.chatId);
+		const cleanup = () => {
+			if (ledger.admissionQueue === queueMarker) {
+				ledger.admissionQueue = null;
+				this.cleanupLedger(work.chatId);
+				this.emitWorkChanged(work.chatId);
+			}
+		};
+		next.then(cleanup, cleanup);
+		return next;
+	}
+	markAccepted(work) {
+		const tracked = this.findEntry(work.chatId, work.entryId);
+		if (!tracked) return false;
+		if (tracked.phase === "tracked") {
+			tracked.phase = "accepted";
+			this.emitWorkChanged(work.chatId);
+		}
+		return true;
+	}
+	hasEntry(work) {
+		return this.findEntry(work.chatId, work.entryId) !== null;
+	}
+	markConsumed(chatId, messages) {
+		const ledger = this.ledgers.get(chatId);
+		if (!ledger || ledger.entries.length === 0) return;
+		const consumedIds = this.messageEntryIds(chatId, messages);
+		if (consumedIds.size === 0) return;
+		let changed = false;
+		for (const tracked of ledger.entries) {
+			if (!consumedIds.has(tracked.entryId)) continue;
+			if (tracked.phase === "tracked" || tracked.phase === "accepted") {
+				tracked.phase = "consumed";
+				changed = true;
+			}
+		}
+		if (changed) this.emitWorkChanged(chatId);
+	}
+	async finishTurn(chatId, messages, _outcome) {
+		this.markConsumed(chatId, messages);
+		const throughEntryId = this.lastMessageEntryId(chatId, messages);
+		if (throughEntryId === void 0) {
+			this.config.log.warn({ chatId }, "turn completion ignored because no inboxEntryId was provided");
+			return;
+		}
+		await this.ackThrough(chatId, throughEntryId, "finish_turn", { requireConsumedPrefix: true });
+	}
+	retryTurn(chatId, messages, reason) {
+		const entryIds = this.messageEntryIds(chatId, messages);
+		if (entryIds.size === 0) return;
+		if (!this.ledgers.get(chatId)?.entries.some((entry) => entryIds.has(entry.entryId))) return;
+		this.markRecoveryDebt(chatId, reason);
+	}
+	async prepareSuspend(chatId, reason) {
+		const ledger = this.ledgers.get(chatId);
+		if (!ledger || ledger.entries.length === 0) return;
+		let consumedPrefixCount = 0;
+		for (const tracked of ledger.entries) {
+			if (tracked.phase !== "consumed" && tracked.phase !== "ackPending") break;
+			consumedPrefixCount++;
+		}
+		if (consumedPrefixCount > 0) {
+			const lastConsumed = ledger.entries[consumedPrefixCount - 1];
+			if (lastConsumed) await this.ackThrough(chatId, lastConsumed.entryId, `${reason}:consumed_prefix`, { requireConsumedPrefix: true });
+		}
+		if ((this.ledgers.get(chatId)?.entries ?? []).length > 0) await this.markRecoveryDebt(chatId, reason);
+	}
+	prepareEvict(chatId, reason) {
+		const ledger = this.ledgers.get(chatId);
+		if (!ledger || ledger.entries.length === 0) return;
+		this.markRecoveryDebt(chatId, reason);
+	}
+	async drainForTerminate(chatId) {
+		const ledger = this.ledgers.get(chatId);
+		if (!ledger || ledger.entries.length === 0) return;
+		let acceptedPrefixCount = 0;
+		for (const tracked of ledger.entries) {
+			if (tracked.phase === "tracked") break;
+			acceptedPrefixCount++;
+		}
+		if (acceptedPrefixCount > 0) {
+			const lastAccepted = ledger.entries[acceptedPrefixCount - 1];
+			if (lastAccepted) await this.ackThrough(chatId, lastAccepted.entryId, "terminate");
+		}
+		if ((this.ledgers.get(chatId)?.entries ?? []).length > 0) await this.markRecoveryDebt(chatId, "terminate_unaccepted_remainder");
+	}
+	hasUnsettledWork(chatId) {
+		const ledger = this.ledgers.get(chatId);
+		if (!ledger) return false;
+		return ledger.entries.length > 0 || ledger.recoveryDebt !== "none" || ledger.admissionQueue !== null;
+	}
+	snapshot(chatId) {
+		const ledger = this.ledgers.get(chatId);
+		return {
+			entries: (ledger?.entries ?? []).map((entry) => ({
+				entryId: entry.entryId,
+				messageId: entry.messageId,
+				phase: entry.phase
+			})),
+			recoveryDebt: ledger?.recoveryDebt ?? "none",
+			admissionPending: ledger?.admissionQueue !== null
+		};
+	}
+	async ackThrough(chatId, throughEntryId, reason, opts = {}) {
+		const ledger = this.ledgers.get(chatId);
+		if (!ledger) return;
+		const next = (ledger.ackQueue ?? Promise.resolve()).catch(() => void 0).then(() => this.ackThroughNow(chatId, throughEntryId, reason, opts));
+		const queueMarker = next.then(() => {}, () => {});
+		ledger.ackQueue = queueMarker;
+		this.emitWorkChanged(chatId);
+		try {
+			await next;
+		} finally {
+			if (ledger.ackQueue === queueMarker) {
+				ledger.ackQueue = null;
+				this.cleanupLedger(chatId);
+				this.emitWorkChanged(chatId);
+			}
+		}
+	}
+	async ackThroughNow(chatId, throughEntryId, reason, opts) {
+		const ledger = this.ledgers.get(chatId);
+		if (!ledger || ledger.entries.length === 0) return;
+		if (ledger.recoveryDebt !== "none") {
+			this.config.log.debug({
+				chatId,
+				throughEntryId,
+				reason
+			}, "ACK-through deferred because chat recovery is required");
+			return;
+		}
+		const index = ledger.entries.findIndex((tracked) => tracked.entryId === throughEntryId);
+		if (index < 0) {
+			this.config.log.warn({
+				chatId,
+				throughEntryId,
+				reason
+			}, "attempt completion ignored for untracked inbox entry");
+			return;
+		}
+		const ackPrefix = ledger.entries.slice(0, index + 1);
+		if (opts.requireConsumedPrefix && ackPrefix.some((tracked) => tracked.phase === "tracked" || tracked.phase === "accepted")) {
+			this.config.log.warn({
+				chatId,
+				throughEntryId,
+				reason,
+				prefix: ackPrefix.map((entry) => ({
+					entryId: entry.entryId,
+					phase: entry.phase
+				}))
+			}, "ACK-through blocked because delivery prefix has unconsumed entries");
+			await this.markRecoveryDebt(chatId, `${reason}:unconsumed_prefix_gap`);
+			return;
+		}
+		let changed = false;
+		for (const tracked of ackPrefix) if (tracked.phase !== "ackPending") {
+			tracked.phase = "ackPending";
+			changed = true;
+		}
+		if (changed) this.emitWorkChanged(chatId);
+		try {
+			await this.config.ackEntry(throughEntryId);
+		} catch (err) {
+			this.config.log.warn({
+				chatId,
+				entryId: throughEntryId,
+				reason,
+				err
+			}, "ACK-through failed; retaining ledger");
+			const current = this.ledgers.get(chatId);
+			if (current) {
+				for (const tracked of current.entries) if (tracked.entryId <= throughEntryId && tracked.phase === "ackPending") tracked.phase = "consumed";
+			}
+			this.emitWorkChanged(chatId);
+			this.markRecoveryDebt(chatId, `${reason}:ack_failed`);
+			return;
+		}
+		const current = this.ledgers.get(chatId);
+		if (!current) return;
+		const committed = current.entries.filter((tracked) => tracked.entryId <= throughEntryId);
+		current.entries = current.entries.filter((tracked) => tracked.entryId > throughEntryId);
+		for (const tracked of committed) this.deduplicator.drop(tracked.dedupKey);
+		if (current.entries.length === 0 && current.recoveryDebt === "required") current.recoveryDebt = "none";
+		this.cleanupLedger(chatId);
+		this.emitWorkChanged(chatId);
+	}
+	async markRecoveryDebt(chatId, reason) {
+		const ledger = this.ledger(chatId);
+		if (ledger.recoveryDebt !== "required") {
+			ledger.recoveryDebt = "required";
+			this.emitWorkChanged(chatId);
+		}
+		this.config.log.warn({
+			chatId,
+			reason,
+			entryIds: ledger.entries.map((entry) => entry.entryId)
+		}, "chat has unsettled inbox work; waiting for recovery redelivery");
+		await this.requestRecovery(chatId, reason);
+	}
+	clearEntriesForRecoverySuccess(chatId) {
+		const ledger = this.ledger(chatId);
+		for (const tracked of ledger.entries) this.deduplicator.drop(tracked.dedupKey);
+		ledger.entries = [];
+	}
+	findEntry(chatId, entryId) {
+		return this.ledgers.get(chatId)?.entries.find((entry) => entry.entryId === entryId) ?? null;
+	}
+	messageEntryIds(chatId, messages) {
+		const batch = Array.isArray(messages) ? messages : [messages];
+		const entryIds = /* @__PURE__ */ new Set();
+		for (const message of batch) if (message.chatId === chatId && message.inboxEntryId !== void 0) entryIds.add(message.inboxEntryId);
+		return entryIds;
+	}
+	lastMessageEntryId(chatId, messages) {
+		const batch = Array.isArray(messages) ? messages : [messages];
+		let throughEntryId;
+		for (const message of batch) {
+			if (message.chatId !== chatId) continue;
+			if (message.inboxEntryId !== void 0) throughEntryId = message.inboxEntryId;
+		}
+		return throughEntryId;
+	}
+	ledger(chatId) {
+		const existing = this.ledgers.get(chatId);
+		if (existing) return existing;
+		const ledger = {
+			entries: [],
+			recoveryDebt: "none",
+			recoveryActivationReady: false,
+			admissionQueue: null,
+			ackQueue: null
+		};
+		this.ledgers.set(chatId, ledger);
+		return ledger;
+	}
+	cleanupLedger(chatId) {
+		const ledger = this.ledgers.get(chatId);
+		if (!ledger) return;
+		if (ledger.entries.length === 0 && ledger.recoveryDebt === "none" && !ledger.recoveryActivationReady && ledger.admissionQueue === null && ledger.ackQueue === null) this.ledgers.delete(chatId);
+	}
+	emitWorkChanged(chatId) {
+		this.config.onWorkChanged(chatId);
+	}
+	dedupKey(chatId, messageId) {
+		return `${chatId}:${messageId}`;
+	}
+};
 /**
 * Sanitize an `err.message` (or any free-text preview) before it leaves the
 * `safe to embed in logs but NOT chat` boundary established by
@@ -17848,9 +18212,9 @@ var SessionManager = class {
 	sessions = /* @__PURE__ */ new Map();
 	evictedMappings = /* @__PURE__ */ new Map();
 	config;
+	inboxDelivery;
 	/** Last lazy Context-Tree re-resolution attempt (epoch ms); see `TREE_RERESOLVE_INTERVAL_MS`. */
 	lastTreeResolveAttemptAt = 0;
-	deduplicator = new Deduplicator(1e3);
 	/**
 	* Current trigger (messageId + senderId) per chat — the message that kicked
 	* off the current or most-recent turn. Read by `forwardResult` (via the
@@ -17860,38 +18224,6 @@ var SessionManager = class {
 	*/
 	currentTrigger = /* @__PURE__ */ new Map();
 	registry;
-	/**
-	* In-flight inbox entries per chat — delivered entries that this process
-	* has handed toward a handler and has not yet committed. Completion is
-	* identity based: handlers report the concrete SessionMessage or fused
-	* batch they actually consumed, and the runtime sends one ack-through for
-	* that batch's last inbox entry.
-	*
-	* Kept here (not on `SessionEntry`) because dispatch may push an entryId
-	* before any session record exists for the chat (`startNewSession` runs
-	* `routeMessage` first), and the queue must survive a session being
-	* suspended / evicted between dispatch and markCompleted.
-	*
-	* Sized small in practice: usually 1, briefly up to N when several
-	* messages land while a turn is mid-flight. Entries that were delivered
-	* but only queued inside a handler remain tracked until the handler's
-	* actual consuming turn calls `markMessagesCompleted`.
-	* See
-	* docs/inflight-message-recovery-design.md §4.
-	*/
-	inFlightEntries = /* @__PURE__ */ new Map();
-	/**
-	* Per-chat admission barrier. It serializes the pre-handler admission phase
-	* only: config refresh, eager asset fetch, marking the entry accepted, and
-	* invoking `routeMessage()`. It deliberately does NOT wait for the handler's
-	* turn promise to settle, so A2 can still be appended/injected while A1's
-	* attempt is running; it just cannot overtake A1 before A1 reaches handler
-	* membership.
-	*/
-	admissionQueues = /* @__PURE__ */ new Map();
-	recoveringChats = /* @__PURE__ */ new Map();
-	recoveryActivationReady = /* @__PURE__ */ new Set();
-	requiresInboxRecovery = /* @__PURE__ */ new Set();
 	pendingQueue = [];
 	lastReportedStates = /* @__PURE__ */ new Map();
 	sessionRuntimeStates = /* @__PURE__ */ new Map();
@@ -17901,6 +18233,12 @@ var SessionManager = class {
 	_activeCount = 0;
 	constructor(config) {
 		this.config = config;
+		this.inboxDelivery = new InboxDeliveryCoordinator({
+			ackEntry: config.ackEntry,
+			recoverChat: config.recoverChat,
+			onWorkChanged: (chatId) => this.projectSessionRuntime(chatId),
+			log: config.log
+		});
 		this.registry = config.registryPath ? new SessionRegistry(config.registryPath) : null;
 		this.idleTimer = setInterval(() => this.evictIdle(), 1e4);
 		if (config.onSessionRuntimeChange) {
@@ -17916,7 +18254,7 @@ var SessionManager = class {
 	}
 	/**
 	* Dispatch an inbox entry. ACK is deferred until the handler reports a
-	* completed turn via `ctx.markMessagesCompleted(...)`.
+	* completed turn via `ctx.finishTurn(...)`.
 	*
 	* Delayed ACK semantics (post inflight-message-recovery): the entry stays
 	* `delivered` server-side until forwardResult succeeds (or the handler
@@ -17933,40 +18271,16 @@ var SessionManager = class {
 	async dispatch(entry) {
 		const chatId = entry.chatId ?? entry.message.chatId;
 		const messageId = entry.message.id;
-		if (this.shouldRecoverBeforeDispatch(chatId)) {
-			await this.recoverChatBeforeDispatch(chatId, entry.id, messageId);
+		if (this.inboxDelivery.shouldRecoverBeforeDispatch(chatId, this.hasHealthyLiveHandler(chatId) || this.hasPendingTransientRetry(chatId), this.hasLocalSessionRecord(chatId))) {
+			await this.inboxDelivery.recoverIfNeeded(chatId, `before_dispatch:${entry.id}:${messageId}`);
 			return;
 		}
-		const dedupKey = `${chatId}:${messageId}`;
-		if (this.deduplicator.isDuplicate(dedupKey)) {
-			const queue = this.inFlightEntries.get(chatId);
-			const stillInFlight = queue ? queue.some((tracked) => tracked.entryId === entry.id) : false;
-			this.config.log.debug({
-				chatId,
-				messageId,
-				entryId: entry.id,
-				stillInFlight
-			}, "duplicate message observed");
-			if (stillInFlight) return;
-			this.config.log.debug({
-				chatId,
-				messageId,
-				entryId: entry.id
-			}, "duplicate key is not tied to an active entry; reprocessing redelivery");
-		}
-		const queue = this.inFlightEntries.get(chatId);
-		const tracked = {
-			entryId: entry.id,
-			messageId,
-			dedupKey,
-			accepted: false,
-			consumed: false
-		};
-		if (queue) queue.push(tracked);
-		else this.inFlightEntries.set(chatId, [tracked]);
+		const decision = this.inboxDelivery.receive(entry);
+		if (decision.kind !== "deliver") return;
+		const { work } = decision;
 		let routePromise;
-		await this.withAdmissionBarrier(chatId, async () => {
-			if (!this.isTrackedEntry(chatId, entry.id)) return;
+		await this.inboxDelivery.runAdmission(work, async () => {
+			if (!this.inboxDelivery.hasEntry(work)) return;
 			if (this.config.agentConfigCache) try {
 				await this.config.agentConfigCache.refreshIfNewer(this.config.agentIdentity.agentId, entry.message.configVersion);
 			} catch (err) {
@@ -17977,13 +18291,13 @@ var SessionManager = class {
 					err
 				}, "config version mismatch — skipping refresh");
 			}
-			if (!this.isTrackedEntry(chatId, entry.id)) return;
+			if (!this.inboxDelivery.hasEntry(work)) return;
 			const message = this.extractMessage(entry);
 			await this.ensureImagesLocal(message);
-			if (!this.markTrackedEntryAccepted(chatId, entry.id)) return;
+			if (!this.inboxDelivery.markAccepted(work)) return;
 			if (!this.hasHealthyLiveHandler(chatId)) await this.ensureContextTreeBinding();
 			routePromise = this.routeMessage(chatId, message).catch((err) => {
-				if (this.isTrackedEntry(chatId, entry.id)) this.clearInFlightForRecovery(chatId, "route_message_failed");
+				if (this.inboxDelivery.hasEntry(work)) this.inboxDelivery.retryTurn(chatId, message, "route_message_failed");
 				throw err;
 			});
 		});
@@ -18048,7 +18362,7 @@ var SessionManager = class {
 			this.lastReportedStates.delete(chatId);
 			this.currentTrigger.delete(chatId);
 			for (let i = this.pendingQueue.length - 1; i >= 0; i--) if (this.pendingQueue[i]?.chatId === chatId) this.pendingQueue.splice(i, 1);
-			this.drainAllInFlightEntries(chatId);
+			await this.inboxDelivery.drainForTerminate(chatId);
 			this.recomputeRuntimeState();
 			this.persistRegistry();
 			this.drainPendingQueue();
@@ -18139,92 +18453,33 @@ var SessionManager = class {
 	/**
 	* Compatibility hook for AgentSlot's bind listener. Bind-time recovery is
 	* now server-driven; chat-scoped same-socket recovery is requested lazily
-	* by `dispatch` when no healthy live handler exists.
+	* by `dispatch` when a locally held chat has no healthy live handler.
 	*/
 	noteBindRecoveryComplete() {}
-	async withAdmissionBarrier(chatId, op) {
-		const next = (this.admissionQueues.get(chatId) ?? Promise.resolve()).then(op, op);
-		this.admissionQueues.set(chatId, next);
-		const cleanup = () => {
-			if (this.admissionQueues.get(chatId) === next) this.admissionQueues.delete(chatId);
-		};
-		next.then(cleanup, cleanup);
-		await next;
-	}
-	isTrackedEntry(chatId, entryId) {
-		return this.inFlightEntries.get(chatId)?.some((tracked) => tracked.entryId === entryId) ?? false;
-	}
-	markTrackedEntryAccepted(chatId, entryId) {
-		const tracked = this.inFlightEntries.get(chatId)?.find((entry) => entry.entryId === entryId);
-		if (!tracked) return false;
-		tracked.accepted = true;
-		return true;
-	}
 	hasHealthyLiveHandler(chatId) {
 		const entry = this.sessions.get(chatId);
 		return entry?.status === "active" && entry.suspending === null;
 	}
-	shouldRecoverBeforeDispatch(chatId) {
-		if (this.recoveryActivationReady.has(chatId)) {
-			this.recoveryActivationReady.delete(chatId);
-			return false;
-		}
-		if (this.requiresInboxRecovery.has(chatId)) return true;
-		return Boolean(this.config.recoverChat) && !this.hasHealthyLiveHandler(chatId);
+	hasPendingTransientRetry(chatId) {
+		const entry = this.sessions.get(chatId);
+		return Boolean(entry && entry.retryAttempt > 0);
 	}
-	async recoverChatBeforeDispatch(chatId, entryId, messageId) {
-		const existing = this.recoveringChats.get(chatId);
-		if (existing) {
-			await existing;
-			return;
-		}
-		const recoverChat = this.config.recoverChat;
-		if (!recoverChat) {
-			this.config.log.error({
-				chatId,
-				entryId,
-				messageId
-			}, "chat requires inbox recovery but no recoverChat callback is configured; deferring dispatch");
-			return;
-		}
-		let recovery;
-		recovery = recoverChat(chatId).then(() => {
-			this.requiresInboxRecovery.delete(chatId);
-			this.recoveryActivationReady.add(chatId);
-			this.config.log.debug({
-				chatId,
-				entryId,
-				messageId
-			}, "chat inbox recovery accepted before dispatch");
-		}).catch((err) => {
-			this.config.log.warn({
-				chatId,
-				entryId,
-				messageId,
-				err
-			}, "chat inbox recovery failed before dispatch");
-		}).finally(() => {
-			if (this.recoveringChats.get(chatId) === recovery) this.recoveringChats.delete(chatId);
-		});
-		this.recoveringChats.set(chatId, recovery);
-		await recovery;
+	hasLocalSessionRecord(chatId) {
+		return this.sessions.has(chatId) || this.evictedMappings.has(chatId);
 	}
 	async routeMessage(chatId, message) {
-		if (message.id) this.currentTrigger.set(chatId, {
-			messageId: message.id,
-			senderId: message.senderId
-		});
 		const existing = this.sessions.get(chatId);
 		if (existing && existing.retryAttempt > 0) {
-			existing.startMessage = message;
+			existing.retryQueuedMessages.push(message);
 			this.triggerImmediateRetry(chatId);
 			return;
 		}
 		if (existing) switch (existing.status) {
 			case "active":
+				this.setCurrentTrigger(chatId, message);
 				existing.handler.inject(message);
 				existing.lastActivity = Date.now();
-				this.setSessionRuntimeState(chatId, "working");
+				this.projectSessionRuntime(chatId);
 				this.config.log.debug({ chatId }, "message injected");
 				return;
 			case "suspended":
@@ -18285,13 +18540,16 @@ var SessionManager = class {
 			lastRetryReason: null,
 			lastRetryRawError: null,
 			startMessage: message,
+			retryQueuedMessages: [],
 			retryFromEvicted: evicted ?? null
 		};
 		this.sessions.set(chatId, entry);
 		this._activeCount++;
 		if (evicted) this.evictedMappings.delete(chatId);
 		this.notifySessionState(chatId, "active");
+		this.projectSessionRuntime(chatId);
 		try {
+			this.setCurrentTrigger(chatId, message);
 			if (evicted) {
 				const sessionId = await handler.resume(message, evicted.claudeSessionId, ctx);
 				entry.claudeSessionId = sessionId;
@@ -18318,7 +18576,7 @@ var SessionManager = class {
 				phase,
 				classification
 			})) {
-				this.drainAllInFlightEntries(chatId);
+				await this.inboxDelivery.drainForTerminate(chatId);
 				this.sessions.delete(chatId);
 				this.sessionRuntimeStates.delete(chatId);
 				this.recomputeRuntimeState();
@@ -18342,7 +18600,9 @@ var SessionManager = class {
 		this._activeCount++;
 		entry.lastActivity = Date.now();
 		this.notifySessionState(entry.chatId, "active");
+		this.projectSessionRuntime(entry.chatId);
 		try {
+			if (message) this.setCurrentTrigger(entry.chatId, message);
 			entry.claudeSessionId = await entry.handler.resume(message ?? void 0, entry.claudeSessionId, ctx);
 			this.config.log.info({
 				chatId: entry.chatId,
@@ -18358,7 +18618,7 @@ var SessionManager = class {
 				phase: "resume",
 				classification
 			})) {
-				this.drainAllInFlightEntries(entry.chatId);
+				await this.inboxDelivery.drainForTerminate(entry.chatId);
 				this.sessions.delete(entry.chatId);
 				this.sessionRuntimeStates.delete(entry.chatId);
 				this.recomputeRuntimeState();
@@ -18396,6 +18656,7 @@ var SessionManager = class {
 			this._activeCount--;
 			entry.status = "suspended";
 			this.sessionRuntimeStates.delete(chatId);
+			this.projectSessionRuntime(chatId);
 			this.recomputeRuntimeState();
 			this.config.log.info({
 				chatId,
@@ -18437,7 +18698,9 @@ var SessionManager = class {
 			}, delayMs);
 			return true;
 		}
+		entry.status = "errored";
 		this.notifySessionState(chatId, "errored");
+		this.projectSessionRuntime(chatId);
 		try {
 			const preview = redactErrorPreview(errMsg, 800);
 			ctx.emitEvent({
@@ -18514,9 +18777,11 @@ var SessionManager = class {
 		entry.handler = newHandler;
 		const ctx = this.buildSessionContext(chatId);
 		this.notifySessionState(chatId, "active");
+		this.projectSessionRuntime(chatId);
 		try {
 			const resumeMessage = entry.startMessage ?? null;
 			const previousSessionId = entry.claudeSessionId || entry.retryFromEvicted?.claudeSessionId || "";
+			if (resumeMessage) this.setCurrentTrigger(chatId, resumeMessage);
 			if (previousSessionId) entry.claudeSessionId = await newHandler.resume(resumeMessage ?? void 0, previousSessionId, ctx);
 			else {
 				const message = resumeMessage ?? buildEmptySessionMessage(chatId);
@@ -18546,6 +18811,7 @@ var SessionManager = class {
 					emitErr
 				}, "resilience retry_succeeded emit failed");
 			}
+			this.drainRetryQueuedMessages(entry);
 			this.persistRegistry();
 		} catch (err) {
 			const classification = classify(err, { source: "session" });
@@ -18556,7 +18822,7 @@ var SessionManager = class {
 				phase: previousAvailable(entry) ? "resume" : "start",
 				classification
 			})) {
-				this.drainAllInFlightEntries(chatId);
+				await this.inboxDelivery.drainForTerminate(chatId);
 				this.sessions.delete(chatId);
 				this.sessionRuntimeStates.delete(chatId);
 				this.recomputeRuntimeState();
@@ -18579,13 +18845,40 @@ var SessionManager = class {
 		}
 		this.runRetry(chatId);
 	}
+	drainRetryQueuedMessages(entry) {
+		if (entry.retryQueuedMessages.length === 0) return;
+		const queued = entry.retryQueuedMessages.splice(0);
+		for (const message of queued) {
+			this.setCurrentTrigger(entry.chatId, message);
+			try {
+				entry.handler.inject(message);
+				entry.lastActivity = Date.now();
+			} catch (err) {
+				this.config.log.warn({
+					chatId: entry.chatId,
+					messageId: message.id,
+					err
+				}, "retry queued inject failed");
+				this.inboxDelivery.retryTurn(entry.chatId, message, "retry_queued_inject_failed");
+				break;
+			}
+		}
+		this.projectSessionRuntime(entry.chatId);
+	}
+	setCurrentTrigger(chatId, message) {
+		if (!message.id) return;
+		this.currentTrigger.set(chatId, {
+			messageId: message.id,
+			senderId: message.senderId
+		});
+	}
 	/**
 	* Try to acquire an active slot. If at concurrency limit:
 	* 1. Suspend the least-recently-active session to free a slot
 	* 2. If no candidates, queue the message
 	*
 	* Returns true if slot acquired, false if queued. The in-flight entryId
-	* is tracked separately in `inFlightEntries` (populated at dispatch),
+	* is tracked separately in `InboxDeliveryCoordinator` (populated at dispatch),
 	* so the queue doesn't carry inbox metadata.
 	*/
 	acquireActiveSlot(chatId, message) {
@@ -18598,7 +18891,10 @@ var SessionManager = class {
 		}
 		if (oldestActive) {
 			this.config.log.info({ chatId: oldestActive.chatId }, "session preempted for concurrency");
-			this.suspendSession(oldestActive);
+			this.suspendSession(oldestActive, {
+				reason: "concurrency_preempted",
+				ackConsumedPrefix: false
+			});
 			return true;
 		}
 		this.config.log.info({ chatId }, "concurrency limit reached, queuing");
@@ -18608,14 +18904,21 @@ var SessionManager = class {
 		});
 		return false;
 	}
-	suspendSession(entry) {
-		this.ackConsumedInFlightForSuspend(entry.chatId);
-		this.clearInFlightForRecovery(entry.chatId, "session_suspended_unconsumed_tail");
+	suspendSession(entry, opts = {
+		reason: "session_suspended",
+		ackConsumedPrefix: true
+	}) {
+		const prepare = opts.ackConsumedPrefix ? this.inboxDelivery.prepareSuspend(entry.chatId, opts.reason) : Promise.resolve(this.inboxDelivery.prepareEvict(entry.chatId, opts.reason));
 		entry.status = "suspended";
 		this._activeCount--;
 		this.sessionRuntimeStates.delete(entry.chatId);
 		this.recomputeRuntimeState();
-		entry.suspending = entry.handler.suspend().catch((err) => {
+		entry.suspending = prepare.then(() => entry.handler.suspend()).catch((err) => {
+			this.config.log.warn({
+				chatId: entry.chatId,
+				err
+			}, "suspend preparation error");
+		}).then(() => void 0).catch((err) => {
 			this.config.log.warn({
 				chatId: entry.chatId,
 				err
@@ -18671,7 +18974,7 @@ var SessionManager = class {
 			this.sessions.delete(candidate.key);
 			this.sessionRuntimeStates.delete(candidate.key);
 			this.currentTrigger.delete(candidate.key);
-			this.clearInFlightForRecovery(candidate.key, "session_evicted");
+			this.inboxDelivery.prepareEvict(candidate.key, "session_evicted");
 			this.recomputeRuntimeState();
 			this.persistRegistry();
 		}
@@ -18682,28 +18985,12 @@ var SessionManager = class {
 	* Invariants this routine relies on:
 	*   1. `lastActivity` is monotonic per session and is bumped by every
 	*      inbound activity — `dispatch` (new chat / resume), `inject`
-	*      (mid-turn message), and the handler's `touch()` on each SDK event.
-	*   2. `runtimeState` reflects what the agent is currently doing as best
-	*      the runtime can tell:
-	*        - `working` — a turn is in flight. Set by the handler at the top
-	*          of its consume loop AND by `SessionManager` on every `inject`
-	*          (because the handler can't observe inject from inside the SDK
-	*          for-await — see #536). Cleared back to `idle` on each
-	*          `result` message from the SDK.
-	*        - `blocked` — only reachable if a handler chooses to set it
-	*          explicitly. The runtime no longer auto-migrates `working` →
-	*          `blocked` on inactivity: with reasoning models a 2-minute
-	*          quiet stretch is normal deep-thinking, not a stuck process,
-	*          and the auto-migration was producing false-positive UI
-	*          warnings. State kept as a semantic slot for future use
-	*          (e.g. if/when the SDK transport exposes a real stuck signal).
-	*        - `idle` — no work in flight.
-	*      If you add a new way to wake the session up, you MUST also set
-	*      `runtimeState` to `working` from that path, or this guard will
-	*      treat the chat as idle and reap it.
-	*   3. `working_grace_seconds` is an UPPER bound on how long a `working`
-	*      / `blocked` chat can hold a slot past `idle_timeout` — defends
-	*      against a stuck handler that never flips back to `idle`.
+	*      (mid-turn message), and the handler's provider-activity callback.
+	*   2. The coordinator is the source of truth for unsettled delivery work.
+	*      If a chat has tracked / consumed / ACK-pending entries or recovery
+	*      debt, the reaper must not treat it as idle before the hard cap.
+	*   3. `working_grace_seconds` is an UPPER bound on how long unsettled work
+	*      can hold a slot past `idle_timeout`.
 	*/
 	evictIdle() {
 		const timeoutMs = this.config.session.idle_timeout * 1e3;
@@ -18714,14 +19001,15 @@ var SessionManager = class {
 			const inactiveMs = now - session.lastActivity;
 			if (inactiveMs <= timeoutMs) continue;
 			const currentState = this.sessionRuntimeStates.get(session.chatId);
+			const hasUnsettledWork = this.inboxDelivery.hasUnsettledWork(session.chatId);
 			const pastHardCap = inactiveMs >= timeoutMs + workingGraceMs;
-			if ((currentState === "working" || currentState === "blocked") && !pastHardCap) {
+			if (hasUnsettledWork && !pastHardCap) {
 				this.config.log.info({
 					chatId: session.chatId,
 					runtimeState: currentState,
 					inactiveSec: Math.round(inactiveMs / 1e3),
 					graceSec: this.config.session.working_grace_seconds
-				}, "session idle threshold reached but still working — skipping suspend");
+				}, "session idle threshold reached but inbox work is unsettled — skipping suspend");
 				continue;
 			}
 			this.config.log.info({
@@ -18748,104 +19036,6 @@ var SessionManager = class {
 		this.lastReportedStates.set(chatId, state);
 		this.config.onStateChange(chatId, state);
 	}
-	ackThroughTrackedEntry(chatId, throughEntryId) {
-		const queue = this.inFlightEntries.get(chatId);
-		if (!queue || queue.length === 0) return;
-		const index = queue.findIndex((tracked) => tracked.entryId === throughEntryId);
-		if (index < 0) {
-			this.config.log.warn({
-				chatId,
-				throughEntryId
-			}, "attempt completion ignored for untracked inbox entry");
-			return;
-		}
-		const committed = queue.splice(0, index + 1);
-		for (const tracked of committed) this.deduplicator.drop(tracked.dedupKey);
-		if (queue.length === 0) this.inFlightEntries.delete(chatId);
-		this.config.ackEntry(throughEntryId).catch((err) => {
-			this.config.log.warn({
-				chatId,
-				entryId: throughEntryId,
-				err
-			}, "ACK-through failed, continuing");
-		});
-	}
-	ackOldestTrackedEntry(chatId) {
-		const entryId = this.inFlightEntries.get(chatId)?.[0]?.entryId;
-		if (entryId !== void 0) this.ackThroughTrackedEntry(chatId, entryId);
-	}
-	clearInFlightForRecovery(chatId, reason) {
-		const queue = this.inFlightEntries.get(chatId);
-		if (!queue || queue.length === 0) return;
-		this.inFlightEntries.delete(chatId);
-		this.deduplicator.dropByPrefix(`${chatId}:`);
-		this.requiresInboxRecovery.add(chatId);
-		this.config.log.warn({
-			chatId,
-			reason,
-			entryIds: queue.map((entry) => entry.entryId)
-		}, "cleared local in-flight inbox entries; waiting for recovery redelivery");
-	}
-	ackConsumedInFlightForSuspend(chatId) {
-		const queue = this.inFlightEntries.get(chatId);
-		if (!queue || queue.length === 0) return;
-		let consumedPrefixCount = 0;
-		for (const tracked of queue) {
-			if (!tracked.consumed) break;
-			consumedPrefixCount++;
-		}
-		if (consumedPrefixCount === 0) return;
-		const lastConsumed = queue[consumedPrefixCount - 1];
-		if (lastConsumed) this.ackThroughTrackedEntry(chatId, lastConsumed.entryId);
-	}
-	markMessagesConsumed(chatId, messages) {
-		const queue = this.inFlightEntries.get(chatId);
-		if (!queue || queue.length === 0) return;
-		const batch = Array.isArray(messages) ? messages : [messages];
-		const consumedIds = /* @__PURE__ */ new Set();
-		for (const message of batch) if (message.chatId === chatId && message.inboxEntryId !== void 0) consumedIds.add(message.inboxEntryId);
-		if (consumedIds.size === 0) return;
-		for (const tracked of queue) if (consumedIds.has(tracked.entryId)) tracked.consumed = true;
-	}
-	markMessagesCompleted(chatId, messages) {
-		const batch = Array.isArray(messages) ? messages : [messages];
-		let throughEntryId;
-		for (const message of batch) {
-			if (message.chatId !== chatId) continue;
-			if (message.inboxEntryId !== void 0) throughEntryId = message.inboxEntryId;
-		}
-		if (throughEntryId === void 0) {
-			this.config.log.warn({ chatId }, "attempt completion ignored because no inboxEntryId was provided");
-			return;
-		}
-		this.ackThroughTrackedEntry(chatId, throughEntryId);
-	}
-	markMessagesRetryable(chatId, messages, reason) {
-		if (!(Array.isArray(messages) ? messages : [messages]).some((message) => message.chatId === chatId && message.inboxEntryId !== void 0 && (this.inFlightEntries.get(chatId) ?? []).some((entry) => entry.entryId === message.inboxEntryId))) return;
-		this.clearInFlightForRecovery(chatId, reason);
-	}
-	/**
-	* Drain every in-flight entry for this chat and ack them all. Used by
-	* the runtime on `session:terminate` (operator intent — every queued
-	* entry is doomed) and on permanent `handler.start` / `handler.resume`
-	* failure (re-handling on redelivery would re-hit the same permanent
-	* error, so acking avoids a loop). NOT to be called from handlers — the
-	* per-turn pairing path is `markMessagesCompleted(messageOrBatch)`.
-	*/
-	drainAllInFlightEntries(chatId) {
-		const queue = this.inFlightEntries.get(chatId);
-		if (!queue || queue.length === 0) return;
-		let acceptedPrefixCount = 0;
-		for (const tracked of queue) {
-			if (!tracked.accepted) break;
-			acceptedPrefixCount++;
-		}
-		if (acceptedPrefixCount > 0) {
-			const lastAccepted = queue[acceptedPrefixCount - 1];
-			if (lastAccepted) this.ackThroughTrackedEntry(chatId, lastAccepted.entryId);
-		}
-		if (this.inFlightEntries.has(chatId)) this.clearInFlightForRecovery(chatId, "drain_unaccepted_remainder");
-	}
 	buildSessionContext(chatId) {
 		const sessionLog = this.config.log.child({ chatId });
 		const log = (msg) => sessionLog.info(msg);
@@ -18886,28 +19076,22 @@ var SessionManager = class {
 			sdk: this.config.sdk,
 			log,
 			chatId,
-			touch: () => {
+			recordProviderActivity: () => {
 				const entry = this.sessions.get(chatId);
 				if (entry && entry.status === "active") entry.lastActivity = Date.now();
 			},
-			setRuntimeState: (state) => {
-				this.setSessionRuntimeState(chatId, state);
-			},
 			emitEvent: (event) => {
 				this.config.onSessionEvent?.(chatId, event);
 			},
 			forwardResult,
-			markCompleted: () => {
-				this.ackOldestTrackedEntry(chatId);
-			},
 			markMessagesConsumed: (messages) => {
-				this.markMessagesConsumed(chatId, messages);
+				this.inboxDelivery.markConsumed(chatId, messages);
 			},
-			markMessagesCompleted: (messages) => {
-				this.markMessagesCompleted(chatId, messages);
+			finishTurn: (messages, outcome) => {
+				return this.inboxDelivery.finishTurn(chatId, messages, outcome);
 			},
-			markMessagesRetryable: (messages, reason) => {
-				this.markMessagesRetryable(chatId, messages, reason);
+			retryTurn: (messages, reason) => {
+				this.inboxDelivery.retryTurn(chatId, messages, reason);
 			},
 			buildAgentEnv: (parentEnv) => buildAgentEnv(parentEnv, envCtx),
 			formatInboundContent: (message) => formatInboundContent(message, participants),
@@ -18925,14 +19109,24 @@ var SessionManager = class {
 			return { agentHome: sessionRoot };
 		}
 	}
-	/** Update per-session runtime state and recompute aggregate. Only active sessions may update. */
-	setSessionRuntimeState(chatId, state) {
+	projectSessionRuntime(chatId) {
 		const session = this.sessions.get(chatId);
-		if (!session || session.status !== "active") return;
+		const state = this.projectedRuntimeState(chatId, session ?? null);
+		if (!state) {
+			if (this.sessionRuntimeStates.delete(chatId)) this.recomputeRuntimeState();
+			return;
+		}
+		if (this.sessionRuntimeStates.get(chatId) === state) return;
 		this.sessionRuntimeStates.set(chatId, state);
 		this.config.onSessionRuntimeChange?.(chatId, state);
 		this.recomputeRuntimeState();
 	}
+	projectedRuntimeState(chatId, session) {
+		if (!session) return null;
+		if (session.status === "errored") return "error";
+		if (session.status !== "active") return null;
+		return this.inboxDelivery.hasUnsettledWork(chatId) ? "working" : "idle";
+	}
 	/**
 	* Re-affirm working / blocked / error sessions so the server-side
 	* freshness stamp doesn't lapse mid-turn. Reports only — does NOT
@@ -18944,9 +19138,9 @@ var SessionManager = class {
 	reaffirmRuntimeStates() {
 		if (!this.config.onSessionRuntimeChange) return;
 		for (const [chatId, session] of this.sessions) {
-			if (session.status !== "active") continue;
+			if (session.status !== "active" && session.status !== "errored") continue;
 			const state = this.sessionRuntimeStates.get(chatId);
-			if (state === "working" || state === "blocked" || state === "error") this.config.onSessionRuntimeChange(chatId, state);
+			if (state === "working" || state === "error") this.config.onSessionRuntimeChange(chatId, state);
 		}
 	}
 	/**
@@ -18959,10 +19153,11 @@ var SessionManager = class {
 	getSessionRuntimeStates() {
 		const out = [];
 		for (const [chatId, session] of this.sessions) {
-			if (session.status !== "active") continue;
+			const runtimeState = this.projectedRuntimeState(chatId, session);
+			if (!runtimeState) continue;
 			out.push({
 				chatId,
-				runtimeState: this.sessionRuntimeStates.get(chatId) ?? "idle"
+				runtimeState
 			});
 		}
 		return out;
@@ -19288,7 +19483,7 @@ var AgentSlot = class {
 	* Ack happens INSIDE the SessionManager via the `ackEntry` callback we
 	* pinned at construction time — `clientConnection.sendInboxAck`. Post
 	* inflight-message-recovery the ack is deferred until the handler closes
-	* the turn via `ctx.markCompleted()`. Sending an additional ack here
+	* the turn via `ctx.finishTurn(...)`. Sending an additional ack here
 	* would double-ack: a WS frame the server cannot match against any
 	* `delivered` row, which leaks the server's per-agent in-flight counter
 	* and stalls push after `inboxMaxInFlightPerAgent` messages.

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { A as readWorkspaceManifest, B as printResults, Bt as SdkError, C as onboardCreate, D as computeWorkspaceStatus, E as promoteToWorkspace, H as getClientServiceStatus, I as checkClientConfig, J as startClientService, K as resolveCliInvocation, L as checkNodeVersion, O as discoverWorkspaceRoot, P as checkAgentConfigs, R as checkServerReachable, S as onboardCheck, St as status, T as migrateWorkspaceToW1, U as installClientService, W as isServiceSupported, X as uninstallClientService, Y as stopClientService, Z as ClientRuntime, at as ensureFreshAccessToken, b as promptMissingFields, ct as resolveAccessToken, it as AuthRefreshRateLimitedError, j as writeWorkspaceManifest, k as pickImmediateWorkspaceSources, lt as resolveServerUrl, nt as rotateClientIdWithBackup, ot as ensureFreshAdminToken, q as restartClientService, r as deriveHubUrlFromToken, rt as AuthRefreshFailedError, t as HubUrlDerivationError, tt as handleClientOrgMismatch, v as isInteractive, vt as blank, w as detectMigrationState, x as formatCheckReport, y as promptAddAgent, z as checkWebSocket, zt as FirstTreeHubSDK } from "./connect-token-B-RM1nMS.mjs";
+import { A as readWorkspaceManifest, B as printResults, Bt as SdkError, C as onboardCreate, D as computeWorkspaceStatus, E as promoteToWorkspace, H as getClientServiceStatus, I as checkClientConfig, J as startClientService, K as resolveCliInvocation, L as checkNodeVersion, O as discoverWorkspaceRoot, P as checkAgentConfigs, R as checkServerReachable, S as onboardCheck, St as status, T as migrateWorkspaceToW1, U as installClientService, W as isServiceSupported, X as uninstallClientService, Y as stopClientService, Z as ClientRuntime, at as ensureFreshAccessToken, b as promptMissingFields, ct as resolveAccessToken, it as AuthRefreshRateLimitedError, j as writeWorkspaceManifest, k as pickImmediateWorkspaceSources, lt as resolveServerUrl, nt as rotateClientIdWithBackup, ot as ensureFreshAdminToken, q as restartClientService, r as deriveHubUrlFromToken, rt as AuthRefreshFailedError, t as HubUrlDerivationError, tt as handleClientOrgMismatch, v as isInteractive, vt as blank, w as detectMigrationState, x as formatCheckReport, y as promptAddAgent, z as checkWebSocket, zt as FirstTreeHubSDK } from "./connect-token-Cd0Z_mdb.mjs";
 export { AuthRefreshFailedError, AuthRefreshRateLimitedError, ClientRuntime, FirstTreeHubSDK, FirstTreeHubSDK as FirstTreeSDK, HubUrlDerivationError, SdkError, blank, checkAgentConfigs, checkClientConfig, checkNodeVersion, checkServerReachable, checkWebSocket, computeWorkspaceStatus, deriveHubUrlFromToken, detectMigrationState, discoverWorkspaceRoot, ensureFreshAccessToken, ensureFreshAdminToken, formatCheckReport, getClientServiceStatus, handleClientOrgMismatch, installClientService, isInteractive, isServiceSupported, migrateWorkspaceToW1, onboardCheck, onboardCreate, pickImmediateWorkspaceSources, printResults, promoteToWorkspace, promptAddAgent, promptMissingFields, readWorkspaceManifest, resolveAccessToken, resolveCliInvocation, resolveServerUrl, restartClientService, rotateClientIdWithBackup, startClientService, status, stopClientService, uninstallClientService, writeWorkspaceManifest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "first-tree-staging",
-  "version": "0.5.7-staging.366.1",
+  "version": "0.5.7-staging.367.1",
   "type": "module",
   "description": "First Tree — unified CLI for Context Tree onboarding, agent management, and team messaging. (Source-tree dev build; CI rewrites `name` and `bin` for prod / staging publishes — see docs/local-dev-isolation.md.)",
   "keywords": [