@roj-ai/sdk 0.1.35 → 0.2.1

package/src/core/sessions/session-manager.ts

@@ -10,8 +10,8 @@
 import { join } from 'node:path'
 import z4 from 'zod/v4'
 import { COMMUNICATOR_ROLE, ORCHESTRATOR_ROLE } from '~/core/agents/agent-roles.js'
-import type { AgentId } from '~/core/agents/schema.js'
-import { generateAgentId } from '~/core/agents/schema.js'
+import { parseAgentWakeKey, parsePluginWakeKey } from '~/core/wake-key.js'
+import { AgentId, generateAgentId } from '~/core/agents/schema.js'
 import { agentEvents } from '~/core/agents/state.js'
 import { type DomainError, PresetErrors, SessionErrors, ValidationErrors } from '~/core/errors.js'
 import { withSessionId } from '~/core/events/test-helpers.js'
@@ -19,18 +19,22 @@ import type { DomainEvent } from '~/core/events/types.js'
 import type { FileStore } from '~/core/file-store/types.js'
 import type { LLMLogger } from '~/core/llm/logger.js'
 import type { LLMProvider } from '~/core/llm/provider.js'
-import type { CallerContext, ConfiguredPlugin, ManagerMethodContext, PluginDefinition } from '~/core/plugins/plugin-builder.js'
+import { DEFAULT_PLUGIN_ORDER } from '~/core/plugins/plugin-builder.js'
+import type { CallerContext, ConfiguredPlugin, ManagerMethodContext, PluginDefinition, SessionCloseReason } from '~/core/plugins/plugin-builder.js'
+import { AGENT_CALLER } from '~/core/plugins/plugin-builder.js'
 import type { Preset } from '~/core/preset/index.js'
 import { knownDefinitionNames, unknownOverrideTargets } from '~/core/preset/overrides.js'
-import type { SessionId } from '~/core/sessions/schema.js'
-import { generateSessionId } from '~/core/sessions/schema.js'
+import type { SessionMetadata } from '~/core/sessions/schema.js'
+import { generateSessionId, isValidSessionId, SessionId } from '~/core/sessions/schema.js'
 import type { SessionCreatedEvent, SessionOverridesPatch } from '~/core/sessions/state.js'
 import { checkRecoveryNeeded, isSessionCreatedEvent, reconstructSessionState, sessionEvents } from '~/core/sessions/state.js'
 import type { ToolExecutor } from '~/core/tools'
-import { FileLogger } from '~/lib/logger/file.js'
+import type { ArchiveLimitOverrides } from '~/lib/archive/index.js'
 import type { Logger } from '~/lib/logger/logger.js'
+import { createSessionLogger } from '~/lib/logger/session-log.js'
 import { TeeLogger } from '~/lib/logger/tee.js'
 import type { Platform } from '~/platform/index.js'
+import { isLiveScheduler } from '~/platform/index.js'
 import type { Result } from '~/lib/utils/result.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 import type { SpawnableAgentInfo } from '~/plugins/agents/index.js'
@@ -44,7 +48,8 @@ import { EventStore } from '../events/event-store.js'
 import { createApplyEvent } from './apply-event.js'
 import { rewriteEventsForFork } from './fork-utils.js'
 import { SessionStore } from './session-store.js'
-import { Session, type UserOutputCallback } from './session.js'
+import { Session, type SessionReopenRegistration, type UserOutputCallback } from './session.js'
+import { SessionRuntimeActivityController } from './runtime-activity.js'
 
 // ============================================================================
 // Errors
@@ -77,21 +82,48 @@ export interface SessionManagerOptions {
 	dataFileStore: FileStore
 	onUserOutput?: UserOutputCallback
 	preprocessorRegistry?: PreprocessorRegistry
+	uploadArchiveLimits?: ArchiveLimitOverrides
+	resourceArchiveLimits?: ArchiveLimitOverrides
 	llmLogger?: LLMLogger
 	portPool?: PortPool
 	pidRegistry?: ServicePidRegistry
 	/** Host-environment adapters (filesystem, process). */
 	platform: Platform
 	systemPlugins?: readonly PluginDefinition<string, any, any, any, any>[]
+	/** Evict resident runtimes after this idle period. Absent or zero disables eviction. */
+	sessionIdleTimeoutMs?: number
+}
+
+interface SessionCacheEntry {
+	state: 'loading' | 'ready' | 'evicting'
+	promise: Promise<Session>
+	activity: SessionRuntimeActivityController
+	lastAccessAt: number
+	unloadPromise?: Promise<void>
+	listenerCleanup?: () => void
+}
+
+/** Why the manager is dropping a resident runtime — finer-grained than what plugins see. */
+type RuntimeDisposalCause = 'idle' | 'closed' | 'disposed' | 'shutdown'
+
+// Both parking causes map to `evicted`: the session survives and the next access rebuilds its runtime.
+const RUNTIME_DISPOSAL_CLOSE_REASON: Record<RuntimeDisposalCause, SessionCloseReason> = {
+	idle: 'evicted',
+	disposed: 'evicted',
+	closed: 'closed',
+	shutdown: 'shutdown',
+}
+
+export interface AcquiredSessionLease {
+	session: Session
+	release: () => void
 }
 
 /**
  * SessionManager manages session lifecycle and caching.
  */
 export class SessionManager {
-	private readonly sessions = new Map<SessionId, Promise<Session>>()
-	/** Unsubscribe functions for session event listeners, keyed by sessionId */
-	private readonly sessionListenerCleanup = new Map<SessionId, () => void>()
+	private readonly sessions = new Map<SessionId, SessionCacheEntry>()
 	/** Manager-level methods collected from plugin definitions across all presets */
 	private readonly managerMethods: Map<string, {
 		input: z4.ZodType
@@ -109,13 +141,25 @@ export class SessionManager {
 	private readonly dataFileStore: FileStore
 	private readonly onUserOutput?: UserOutputCallback
 	private readonly preprocessorRegistry?: PreprocessorRegistry
+	private readonly uploadArchiveLimits?: ArchiveLimitOverrides
+	private readonly resourceArchiveLimits?: ArchiveLimitOverrides
 	private readonly llmLogger?: LLMLogger
 	private readonly portPool?: PortPool
 	private readonly pidRegistry?: ServicePidRegistry
 	private readonly platform: Platform
 	private readonly systemPlugins: readonly PluginDefinition<string, any, any, any, any>[]
+	private readonly sessionIdleTimeoutMs: number
+	private readonly evictionSweepTimer?: ReturnType<typeof setInterval>
+	private cacheHits = 0
+	private cacheMisses = 0
+	private cacheEvictions = 0
+	/** Set by shutdown(). Also fences wakes: one armed before it must not reload a session after it. */
+	private shuttingDown = false
 
 	constructor(options: SessionManagerOptions) {
+		if (options.sessionIdleTimeoutMs !== undefined && (!Number.isSafeInteger(options.sessionIdleTimeoutMs) || options.sessionIdleTimeoutMs < 0)) {
+			throw new Error(`Invalid sessionIdleTimeoutMs: ${options.sessionIdleTimeoutMs}`)
+		}
 		this.eventStore = options.eventStore
 		this.llmProvider = options.llmProvider
 		this.llmProviders = options.llmProviders ?? new Map()
@@ -126,12 +170,35 @@ export class SessionManager {
 		this.dataFileStore = options.dataFileStore
 		this.onUserOutput = options.onUserOutput
 		this.preprocessorRegistry = options.preprocessorRegistry
+		this.uploadArchiveLimits = options.uploadArchiveLimits
+		this.resourceArchiveLimits = options.resourceArchiveLimits
 		this.llmLogger = options.llmLogger
 		this.portPool = options.portPool
 		this.pidRegistry = options.pidRegistry
 		this.platform = options.platform
 		this.systemPlugins = options.systemPlugins ?? []
+		this.sessionIdleTimeoutMs = options.sessionIdleTimeoutMs ?? 0
 		this.managerMethods = this.collectManagerMethods()
+		if (this.sessionIdleTimeoutMs > 0) {
+			const sweepIntervalMs = Math.min(this.sessionIdleTimeoutMs, 60_000)
+			this.evictionSweepTimer = setInterval(() => {
+				void this.evictIdleSessions()
+			}, sweepIntervalMs)
+			this.evictionSweepTimer.unref()
+		}
+
+		// A live scheduler has nowhere else to deliver. Hosts that wake out-of-band
+		// (a Durable Object alarm) call dispatchWake() from their own handler.
+		const scheduler = this.platform.scheduler
+		if (isLiveScheduler(scheduler)) {
+			scheduler.onWake(async (key) => {
+				try {
+					await this.dispatchWake(key)
+				} catch (error) {
+					this.logger.error('Scheduler wake dispatch failed', error instanceof Error ? error : new Error(String(error)), { key })
+				}
+			})
+		}
 	}
 
 	/** Expose platform adapters (used by Session for building contexts). */
@@ -139,6 +206,76 @@ export class SessionManager {
 		return this.platform
 	}
 
+	/**
+	 * Deliver a scheduler wake that has come due.
+	 *
+	 * The host's entry point back into the SDK — on Cloudflare, called from
+	 * `alarm()` in an isolate that never armed the wake. SessionManager owns it
+	 * because it is the only thing that can turn a session id back into a live
+	 * session, so the key alone is enough input.
+	 *
+	 * Two vocabularies route here: `agent:` wakes re-enter the agent loop,
+	 * `plugin:` wakes call a plugin method. Anything else is a quiet no-op, and so
+	 * is a key naming a session, agent or plugin that is gone — wakes outlive what
+	 * they point at. Only genuinely unexpected failures (event store IO) throw, so
+	 * a host that retries alarms retries those and only those.
+	 */
+	async dispatchWake(key: string): Promise<void> {
+		const agentWake = parseAgentWakeKey(key)
+		if (agentWake) {
+			await this.withWakeTarget(key, agentWake.sessionId, async (session) => {
+				await session.getAgent(agentWake.agentId)?.deliverWake(agentWake.kind)
+			})
+			return
+		}
+
+		const pluginWake = parsePluginWakeKey(key)
+		if (pluginWake) {
+			await this.withWakeTarget(key, pluginWake.sessionId, async (session) => {
+				const result = await session.callPluginMethod(
+					`${pluginWake.pluginName}.${pluginWake.method}`,
+					pluginWake.agentId === undefined ? {} : { agentId: pluginWake.agentId },
+					pluginWake.agentId,
+					AGENT_CALLER,
+				)
+				// A preset that no longer registers the plugin lands here, same as a
+				// missing agent does: the wake points at something that is gone.
+				if (!result.ok) this.logger.debug('Scheduler wake method rejected', { key, error: result.error.type })
+			})
+			return
+		}
+
+		this.logger.debug('Ignoring unrecognized scheduler wake key', { key })
+	}
+
+	/** Run `deliver` against the session a due wake names, under a runtime lease. */
+	private async withWakeTarget(key: string, sessionId: SessionId, deliver: (session: Session) => Promise<void>): Promise<void> {
+		// Nothing armed before shutdown may load a session back in afterwards.
+		if (this.shuttingDown) return
+		// Nor may a wake that lands mid-teardown rebuild what is being torn down —
+		// getSession() would wait out the unload and reload. onSessionReady re-arms.
+		const resident = this.sessions.get(sessionId)
+		if (resident && (resident.state === 'evicting' || resident.activity.getSnapshot().state !== 'ready')) return
+
+		const sessionResult = await this.getSession(sessionId)
+		if (!sessionResult.ok) {
+			this.logger.debug('Scheduler wake for a session that no longer loads', { key, error: sessionResult.error.type })
+			return
+		}
+		const session = sessionResult.value
+		// A closed session's log is sealed; re-entering it would only fail to write.
+		if (session.state.status === 'closed') return
+
+		// Lease the delivery, not the delay before it — an idle session stays evictable while it waits.
+		const release = session.tryAcquireRuntimeLease(`wake:${key}`)
+		if (!release) return
+		try {
+			await deliver(session)
+		} finally {
+			release()
+		}
+	}
+
 	/**
 	 * Create a new session with the given preset.
 	 */
@@ -146,6 +283,7 @@ export class SessionManager {
 		presetId: string,
 		options?: { workspaceDir?: string; sessionId?: string; overrides?: SessionOverridesPatch },
 	): Promise<Result<Session, DomainError>> {
+		if (this.shuttingDown) return Err(ValidationErrors.invalid('Session manager is shutting down'))
 		const preset = this.presets.get(presetId)
 		if (!preset) {
 			return Err(PresetErrors.notFound(presetId))
@@ -160,7 +298,12 @@ export class SessionManager {
 			}
 		}
 
-		const sessionId = options?.sessionId ? (options.sessionId as any) : generateSessionId()
+		// Validate before anything derives a path from it — the id reaches join() for the
+		// session dir, the event log and the file logger, and path.join collapses `..`.
+		if (options?.sessionId !== undefined && !isValidSessionId(options.sessionId)) {
+			return Err(ValidationErrors.invalid(`Invalid session id: ${JSON.stringify(options.sessionId)}`))
+		}
+		const sessionId = options?.sessionId ? SessionId(options.sessionId) : generateSessionId()
 		// First orchestrator gets seq 1
 		const orchestratorId = generateAgentId(ORCHESTRATOR_ROLE, 1)
 
@@ -229,25 +372,40 @@ export class SessionManager {
 			))
 		}
 
-		// Write events to event store
-		await this.eventStore.appendBatch(sessionId, events)
-
-		// Build plugins and composed reducer so plugin state slices are applied
-		const plugins = this.buildPlugins(preset)
-		const composedReducer = createApplyEvent(plugins)
-
-		// Reconstruct state with composed reducer (includes plugin state slices)
-		const state = reconstructSessionState(events, composedReducer)
-		if (!state) {
-			return Err(ValidationErrors.invalid('Failed to reconstruct session'))
+		if (this.sessions.has(sessionId)) return Err(SessionErrors.alreadyExists(String(sessionId)))
+		const activity = new SessionRuntimeActivityController()
+		let entry: SessionCacheEntry
+		const creationPromise = Promise.resolve().then(async () => {
+			if (await this.eventStore.exists(sessionId)) throw new SessionLoadError(SessionErrors.alreadyExists(String(sessionId)))
+			await this.eventStore.appendBatch(sessionId, events)
+			const plugins = this.buildPlugins(preset)
+			const composedReducer = createApplyEvent(plugins)
+			const state = reconstructSessionState(events, composedReducer)
+			if (!state) throw new SessionLoadError(ValidationErrors.invalid('Failed to reconstruct session'))
+			const store = new SessionStore(sessionId, this.eventStore, state, composedReducer)
+			return this.createSessionInstance(store, preset, plugins, entry)
+		})
+		entry = {
+			state: 'loading',
+			promise: creationPromise,
+			activity,
+			lastAccessAt: performance.now(),
 		}
+		this.sessions.set(sessionId, entry)
 
-		// Create store and session (initPluginContexts + onSessionReady hooks run inside)
-		const store = new SessionStore(sessionId, this.eventStore, state, composedReducer)
-		const session = await this.createSessionInstance(store, preset, plugins)
-
-		// Cache session (wrap in resolved promise for consistency)
-		this.sessions.set(sessionId, Promise.resolve(session))
+		let session: Session
+		try {
+			session = await creationPromise
+			if (this.sessions.get(sessionId) === entry && entry.state === 'loading') {
+				entry.state = 'ready'
+				entry.lastAccessAt = performance.now()
+			}
+		} catch (error) {
+			if (this.sessions.get(sessionId) === entry) this.sessions.delete(sessionId)
+			entry.listenerCleanup?.()
+			if (error instanceof SessionLoadError) return Err(error.domainError)
+			throw error
+		}
 
 		this.logger.info('Session created', {
 			sessionId,
@@ -266,8 +424,10 @@ export class SessionManager {
 		sourceSessionId: SessionId,
 		eventIndex: number,
 	): Promise<Result<Session, DomainError>> {
+		if (this.shuttingDown) return Err(ValidationErrors.invalid('Session manager is shutting down'))
 		// Load source events
 		const sourceEvents = await this.eventStore.load(sourceSessionId)
+		if (this.shuttingDown) return Err(ValidationErrors.invalid('Session manager is shutting down'))
 		if (sourceEvents.length === 0) {
 			return Err(SessionErrors.notFound(String(sourceSessionId)))
 		}
@@ -317,43 +477,49 @@ export class SessionManager {
 			})
 		}
 
-		// Write forked events to event store
-		await this.eventStore.appendBatch(newSessionId, forkedEvents)
-
-		// Build plugins and composed reducer so plugin state slices are applied
-		const plugins = this.buildPlugins(preset)
-		const composedReducer = createApplyEvent(plugins)
-
-		// Reconstruct state with composed reducer (includes plugin state slices)
-		const state = reconstructSessionState(forkedEvents, composedReducer)
-		if (!state) {
-			return Err(ValidationErrors.invalid('Failed to reconstruct forked session'))
+		const activity = new SessionRuntimeActivityController()
+		let entry: SessionCacheEntry
+		const forkPromise = Promise.resolve().then(async () => {
+			await this.eventStore.appendBatch(newSessionId, forkedEvents)
+			const plugins = this.buildPlugins(preset)
+			const composedReducer = createApplyEvent(plugins)
+			const state = reconstructSessionState(forkedEvents, composedReducer)
+			if (!state) throw new SessionLoadError(ValidationErrors.invalid('Failed to reconstruct forked session'))
+			const store = new SessionStore(newSessionId, this.eventStore, state, composedReducer)
+			const recoveryData = checkRecoveryNeeded(state)
+			if (recoveryData) {
+				await store.emit(withSessionId(
+					newSessionId,
+					sessionEvents.create('session_restarted', {
+						resetAgentIds: recoveryData.resetAgentIds,
+						clearedToolAgentIds: recoveryData.clearedToolAgentIds,
+					}),
+				))
+			}
+			return this.createSessionInstance(store, preset, plugins, entry)
+		})
+		entry = {
+			state: 'loading',
+			promise: forkPromise,
+			activity,
+			lastAccessAt: performance.now(),
 		}
+		this.sessions.set(newSessionId, entry)
 
-		// Create store
-		const store = new SessionStore(newSessionId, this.eventStore, state, composedReducer)
-
-		// Normalize stuck agents via session_restarted event
-		const recoveryData = checkRecoveryNeeded(state)
-		if (recoveryData) {
-			await store.emit(withSessionId(
-				newSessionId,
-				sessionEvents.create('session_restarted', {
-					resetAgentIds: recoveryData.resetAgentIds,
-					clearedToolAgentIds: recoveryData.clearedToolAgentIds,
-				}),
-			))
+		let session: Session
+		try {
+			session = await forkPromise
+			if (this.sessions.get(newSessionId) === entry && entry.state === 'loading') entry.state = 'ready'
+		} catch (error) {
+			if (this.sessions.get(newSessionId) === entry) this.sessions.delete(newSessionId)
+			entry.listenerCleanup?.()
+			if (error instanceof SessionLoadError) return Err(error.domainError)
+			throw error
 		}
 
-		// Create session instance (auto-start services run via onSessionReady)
-		const session = await this.createSessionInstance(store, preset, plugins)
-
 		// Check for pending agents
 		session.checkPendingAgents()
 
-		// Cache session
-		this.sessions.set(newSessionId, Promise.resolve(session))
-
 		this.logger.info('Session forked', {
 			sourceSessionId,
 			newSessionId,
@@ -369,40 +535,59 @@ export class SessionManager {
 	async getSession(
 		sessionId: SessionId,
 	): Promise<Result<Session, DomainError>> {
-		// Check cache first
-		const cached = this.sessions.get(sessionId)
-		if (cached) {
-			try {
-				return Ok(await cached)
-			} catch (error) {
-				// Previous load failed, remove from cache and try again
-				this.sessions.delete(sessionId)
-				if (error instanceof SessionLoadError) {
-					return Err(error.domainError)
-				}
-				throw error
+		while (true) {
+			if (this.shuttingDown) return Err(ValidationErrors.invalid('Session manager is shutting down'))
+			let entry = this.sessions.get(sessionId)
+			if (entry?.state === 'evicting') {
+				await entry.unloadPromise
+				continue
+			}
+			if (entry?.state === 'ready' && entry.activity.getSnapshot().state !== 'ready') {
+				const session = await entry.promise
+				await this.beginCacheEntryDisposal(sessionId, entry, session, 'disposed')
+				continue
 			}
-		}
 
-		// Store promise immediately to prevent concurrent loads
-		const loadPromise = this.loadSession(sessionId)
-		this.sessions.set(sessionId, loadPromise)
+			if (entry) {
+				this.cacheHits++
+				entry.lastAccessAt = performance.now()
+			} else {
+				this.cacheMisses++
+				const activity = new SessionRuntimeActivityController()
+				let loadingEntry: SessionCacheEntry
+				const promise = Promise.resolve().then(() => this.loadSession(sessionId, loadingEntry))
+				loadingEntry = {
+					state: 'loading',
+					activity,
+					lastAccessAt: performance.now(),
+					promise,
+				}
+				entry = loadingEntry
+				this.sessions.set(sessionId, entry)
+			}
 
-		try {
-			return Ok(await loadPromise)
-		} catch (error) {
-			this.sessions.delete(sessionId)
-			if (error instanceof SessionLoadError) {
-				return Err(error.domainError)
+			try {
+				const session = await entry.promise
+				if (this.sessions.get(sessionId) === entry && entry.state === 'loading') {
+					if (session.state.status === 'closed') this.sessions.delete(sessionId)
+					else {
+						entry.state = 'ready'
+						entry.lastAccessAt = performance.now()
+					}
+				}
+				return Ok(session)
+			} catch (error) {
+				if (this.sessions.get(sessionId) === entry) this.sessions.delete(sessionId)
+				if (error instanceof SessionLoadError) return Err(error.domainError)
+				throw error
 			}
-			throw error
 		}
 	}
 
 	/**
 	 * Internal session loading - throws SessionLoadError on domain errors.
 	 */
-	private async loadSession(sessionId: SessionId): Promise<Session> {
+	private async loadSession(sessionId: SessionId, entry: SessionCacheEntry): Promise<Session> {
 		// We need to peek at events first to determine the preset, so we can build plugins
 		// and compose the reducer before loading the store
 		const events = await this.eventStore.load(sessionId)
@@ -425,7 +610,7 @@ export class SessionManager {
 		const composedReducer = createApplyEvent(plugins)
 
 		// Load store with composed reducer
-		const store = await SessionStore.load(sessionId, this.eventStore, composedReducer)
+		const store = await SessionStore.fromEvents(sessionId, this.eventStore, events, composedReducer)
 		if (!store) {
 			throw new SessionLoadError(SessionErrors.notFound(String(sessionId)))
 		}
@@ -434,11 +619,9 @@ export class SessionManager {
 
 		// Don't cache closed sessions
 		if (state.status === 'closed') {
-			// Remove from cache since we don't cache closed sessions
-			this.sessions.delete(sessionId)
 			// Skip onSessionReady hooks — closed sessions are immutable, firing hooks
 			// would emit events to a sealed event log on every read / restart.
-			return await this.createSessionInstance(store, preset, plugins, { skipReadyHooks: true })
+			return await this.createSessionInstance(store, preset, plugins, entry, { skipReadyHooks: true })
 		}
 
 		// Check if recovery is needed after restart
@@ -460,7 +643,7 @@ export class SessionManager {
 		}
 
 		// Create session (auto-start services run via onSessionReady)
-		const session = await this.createSessionInstance(store, preset, plugins)
+		const session = await this.createSessionInstance(store, preset, plugins, entry)
 
 		// Check for pending agents
 		session.checkPendingAgents()
@@ -482,10 +665,55 @@ export class SessionManager {
 		agentId?: AgentId,
 		caller?: CallerContext,
 	): Promise<Result<unknown, DomainError>> {
-		const sessionResult = await this.getSession(sessionId)
-		if (!sessionResult.ok) return sessionResult
+		return this.withSessionLease(sessionId, `request:${method}`, (session) => (
+			session.callPluginMethod(method, input, agentId, caller)
+		))
+	}
 
-		return sessionResult.value.callPluginMethod(method, input, agentId, caller)
+	/** Run an operation while atomically keeping the selected runtime resident. */
+	async withSessionLease<T>(
+		sessionId: SessionId,
+		reason: string,
+		operation: (session: Session) => Promise<Result<T, DomainError>>,
+	): Promise<Result<T, DomainError>> {
+		const acquired = await this.acquireSessionLease(sessionId, reason)
+		if (!acquired.ok) return acquired
+		try {
+			return await operation(acquired.value.session)
+		} finally {
+			acquired.value.release()
+		}
+	}
+
+	/** Atomically look up a runtime and acquire a caller-managed lease on it. */
+	async acquireSessionLease(
+		sessionId: SessionId,
+		reason: string,
+	): Promise<Result<AcquiredSessionLease, DomainError>> {
+		while (true) {
+			const sessionResult = await this.getSession(sessionId)
+			if (!sessionResult.ok) return sessionResult
+
+			const entry = this.sessions.get(sessionId)
+			if (!entry) return Ok({ session: sessionResult.value, release: () => {} })
+			const release = entry.activity.tryAcquire(reason)
+			if (!release) {
+				if (entry.unloadPromise) await entry.unloadPromise
+				continue
+			}
+
+			entry.lastAccessAt = performance.now()
+			let released = false
+			return Ok({
+				session: sessionResult.value,
+				release: () => {
+					if (released) return
+					released = true
+					entry.lastAccessAt = performance.now()
+					release()
+				},
+			})
+		}
 	}
 
 	/**
@@ -572,6 +800,7 @@ export class SessionManager {
 	 */
 	async getStats(): Promise<{
 		sessionCount: number
+		loadedSessionCount: number
 		pendingAgents: number
 		processingAgents: number
 		lastActivityAt: number | null
@@ -586,9 +815,14 @@ export class SessionManager {
 		let processingAgents = 0
 		let lastActivityAt: number | null = null
 
-		// Wait for all sessions, ignoring failures
+		const metadataResult = await this.eventStore.listSessionsWithMetadata()
+		const openMetadata = metadataResult.sessions.filter((metadata) => metadata.status !== 'closed')
+
+		// Wait for resident sessions, ignoring failed and evicting loads.
 		const sessions = await Promise.all(
-			Array.from(this.sessions.values()).map((p) => p.catch(() => null)),
+			Array.from(this.sessions.values())
+				.filter((entry) => entry.state !== 'evicting')
+				.map((entry) => entry.promise.catch(() => null)),
 		)
 
 		// Filter out closed sessions — they do not contribute to activity
@@ -596,13 +830,8 @@ export class SessionManager {
 			(s): s is Session => s !== null && s.state.status !== 'closed',
 		)
 
-		// Fetch metadata only for open sessions
-		const metadataResults = await Promise.all(
-			openSessions.map((s) => this.eventStore.getMetadata(s.state.id).catch(() => null)),
-		)
-
-		for (const metadata of metadataResults) {
-			if (metadata?.lastActivityAt) {
+		for (const metadata of openMetadata) {
+			if (metadata.lastActivityAt) {
 				if (
 					lastActivityAt === null
 					|| metadata.lastActivityAt > lastActivityAt
@@ -619,6 +848,7 @@ export class SessionManager {
 			metrics: SessionStatsState
 		}> = []
 
+		const loadedById = new Map(openSessions.map((session) => [session.id, session]))
 		for (const session of openSessions) {
 			for (const [agentId, agentState] of session.state.agents) {
 				if (agentState.status === 'pending') {
@@ -635,16 +865,21 @@ export class SessionManager {
 				}
 			}
 
+		}
+
+		for (const metadata of openMetadata) {
+			const loaded = loadedById.get(metadata.sessionId)
 			sessionStats.push({
-				id: session.state.id,
-				presetId: session.state.presetId,
-				status: session.state.status,
-				metrics: selectSessionStats(session.state),
+				id: metadata.sessionId,
+				presetId: metadata.presetId,
+				status: loaded?.state.status ?? metadata.status,
+				metrics: loaded ? selectSessionStats(loaded.state) : statsFromMetadata(metadata),
 			})
 		}
 
 		return {
-			sessionCount: openSessions.length,
+			sessionCount: openMetadata.length,
+			loadedSessionCount: openSessions.length,
 			pendingAgents,
 			processingAgents,
 			lastActivityAt,
@@ -656,36 +891,92 @@ export class SessionManager {
 	 * Shutdown - clean up all sessions.
 	 */
 	async shutdown(): Promise<void> {
-		// Wait for all sessions, ignoring failures
-		const sessions = await Promise.all(
-			Array.from(this.sessions.values()).map((p) => p.catch(() => null)),
-		)
-
-		for (const session of sessions) {
-			if (session) {
-				session.shutdown()
+		this.shuttingDown = true
+		if (this.evictionSweepTimer) clearInterval(this.evictionSweepTimer)
+		await Promise.all([...this.sessions].map(async ([sessionId, entry]) => {
+			try {
+				const session = await entry.promise
+				await this.beginCacheEntryDisposal(sessionId, entry, session, 'shutdown')
+			} catch (error) {
+				entry.listenerCleanup?.()
+				entry.listenerCleanup = undefined
+				this.logger.error(
+					'Failed to dispose session during shutdown',
+					error instanceof Error ? error : new Error(String(error)),
+					{ sessionId },
+				)
 			}
-		}
+		}))
 		this.sessions.clear()
-		for (const cleanup of this.sessionListenerCleanup.values()) {
-			cleanup()
-		}
-		this.sessionListenerCleanup.clear()
 		this.logger.info('SessionManager shutdown complete')
 	}
 
+	/** Narrow runtime-cache diagnostics for lifecycle tests and operational logs. */
+	getRuntimeCacheStats(): {
+		hits: number
+		misses: number
+		evictions: number
+		loadedSessionCount: number
+		sessions: Array<{
+			id: SessionId
+			state: SessionCacheEntry['state']
+			lastAccessAt: number
+			activeLeaseCount: number
+			leaseReasons: Readonly<Record<string, number>>
+		}>
+	} {
+		return {
+			hits: this.cacheHits,
+			misses: this.cacheMisses,
+			evictions: this.cacheEvictions,
+			loadedSessionCount: this.sessions.size,
+			sessions: [...this.sessions].map(([id, entry]) => {
+				const activity = entry.activity.getSnapshot()
+				return {
+					id,
+					state: entry.state,
+					lastAccessAt: Math.max(entry.lastAccessAt, activity.lastActivityAt),
+					activeLeaseCount: activity.activeCount,
+					leaseReasons: activity.reasons,
+				}
+			}),
+		}
+	}
+
+	/**
+	 * Sessions whose runtime is already resident and ready.
+	 *
+	 * Deliberately does not load, and does not refresh `lastAccessAt` — a passive
+	 * reader must not keep a runtime alive or resurrect an evicted one. Use this
+	 * over `getSession()` for read-only sweeps across sessions.
+	 */
+	async listResidentSessions(): Promise<Session[]> {
+		const entries = [...this.sessions].filter(([, entry]) => entry.state === 'ready')
+		const sessions = await Promise.all(entries.map(async ([sessionId, entry]) => {
+			const session = await entry.promise.catch(() => null)
+			// Re-check: the entry can start evicting while we await the resolved promise.
+			if (!session || this.sessions.get(sessionId) !== entry || entry.state !== 'ready') return null
+			return session
+		}))
+		return sessions.filter((session): session is Session => session !== null)
+	}
+
 	// ============================================================================
 	// Private methods
 	// ============================================================================
 
 	/**
-	 * Build ConfiguredPlugin[] for a session.
+	 * Build ConfiguredPlugin[] for a session, in hook order.
 	 *
 	 * Iterates all system-registered plugins. For each:
 	 * 1. Check if preset has explicit SessionPluginConfig → use that config
 	 * 2. If not, try auto-deriving infrastructure config (agents, uploads, services)
 	 * 3. If no config at all → call .create() with no args (void config)
 	 * 4. Check isSessionEnabled — skip plugin if not enabled
+	 *
+	 * The result is sorted by each plugin's declared `.order()` — the precedence
+	 * between plugins that both want the same hook, since most agent hooks stop
+	 * at the first non-null result.
 	 */
 	private buildPlugins(preset: Preset): ConfiguredPlugin[] {
 		// Build a lookup from preset Sessionplugins
@@ -759,7 +1050,8 @@ export class SessionManager {
 			}
 		}
 
-		return plugins
+		// Stable, so plugins that declare no order keep their registration order.
+		return plugins.sort((a, b) => (a.order ?? DEFAULT_PLUGIN_ORDER) - (b.order ?? DEFAULT_PLUGIN_ORDER))
 	}
 
 	/**
@@ -786,8 +1078,13 @@ export class SessionManager {
 		configs.set('uploads', {
 			dataFileStore: this.dataFileStore,
 			preprocessorRegistry: this.preprocessorRegistry,
+			archiveLimits: this.uploadArchiveLimits,
 		})
 
+		if (this.resourceArchiveLimits) {
+			configs.set('resources', { archiveLimits: this.resourceArchiveLimits })
+		}
+
 		// services plugin — collect services from all agent definitions
 		const allAgentConfigs = [preset.orchestrator, ...(preset.communicator ? [preset.communicator] : []), ...preset.agents]
 		const servicesByType = new Map<string, ServiceConfig>()
@@ -816,17 +1113,13 @@ export class SessionManager {
 		store: SessionStore,
 		preset: Preset,
 		plugins: ConfiguredPlugin[],
+		entry: SessionCacheEntry,
 		opts: { skipReadyHooks?: boolean } = {},
 	): Promise<Session> {
-		// Only register cache eviction listener for active sessions (not closed)
-		if (store.getState().status !== 'closed') {
-			this.registerSessionEventListener(store.sessionId, store)
-		}
-
 		const sessionDir = this.getSessionDir(store.sessionId)
 		const sessionLogger = new TeeLogger([
 			this.logger.child({ sessionId: store.sessionId }),
-			new FileLogger(join(sessionDir, 'session.log'), this.platform.fs, { sessionId: String(store.sessionId) }),
+			createSessionLogger(this.platform, String(store.sessionId), join(sessionDir, 'session.log')),
 		])
 
 		// Create session
@@ -843,8 +1136,15 @@ export class SessionManager {
 			eventStore: this.eventStore,
 			llmLogger: this.llmLogger,
 			platform: this.platform,
+			runtimeActivity: entry.activity,
+			registerReopenedSession: (reopenedSession) => this.registerReopenedSession(reopenedSession, entry.activity),
 		})
 
+		// Only register cache eviction listener for active sessions (not closed)
+		if (store.getState().status !== 'closed') {
+			this.registerSessionEventListener(store.sessionId, store, session, entry)
+		}
+
 		// Ensure session and workspace directories exist before plugins run
 		await this.platform.fs.mkdir(sessionDir, { recursive: true })
 		const workspaceDir = store.getState().workspaceDir
@@ -852,14 +1152,17 @@ export class SessionManager {
 			await this.platform.fs.mkdir(workspaceDir, { recursive: true })
 		}
 
-		// Initialize plugin contexts (calls createContext for each plugin).
-		// Safe for closed sessions — createContext is pure local setup, no event emit.
-		await session.initPluginContexts()
+		try {
+			// Safe for closed sessions — createContext is pure local setup, no event emit.
+			await session.initPluginContexts()
 
-		// Call onSessionReady hooks with full context.
-		// Skipped for closed sessions to preserve event log immutability.
-		if (!opts.skipReadyHooks) {
-			await session.callSessionReadyHooks()
+			// Skipped for closed sessions to preserve event log immutability.
+			if (!opts.skipReadyHooks) await session.callSessionReadyHooks()
+		} catch (error) {
+			await session.dispose('evicted')
+			entry.listenerCleanup?.()
+			entry.listenerCleanup = undefined
+			throw error
 		}
 
 		return session
@@ -896,20 +1199,137 @@ export class SessionManager {
 	 * Cleans up any previous listener for this sessionId (from a prior load)
 	 * to prevent duplicate listeners firing on old stores.
 	 */
-	private registerSessionEventListener(sessionId: SessionId, store: SessionStore): void {
-		const prevCleanup = this.sessionListenerCleanup.get(sessionId)
-		if (prevCleanup) prevCleanup()
-
+	private registerSessionEventListener(sessionId: SessionId, store: SessionStore, session: Session, entry: SessionCacheEntry): void {
+		entry.listenerCleanup?.()
 		const unsubscribe = store.onEvent((event) => {
-			if (event.type === 'session_closed' || event.type === 'session_reopened') {
-				this.sessions.delete(sessionId)
-				this.sessionListenerCleanup.delete(sessionId)
+			if (event.type === 'session_closed') {
+				if (this.sessions.get(sessionId) === entry) this.beginCacheEntryDisposal(sessionId, entry, session, 'closed')
+				else void session.dispose('closed')
+			} else if (event.type === 'session_reopened') {
+				if (this.sessions.get(sessionId) === entry) this.sessions.delete(sessionId)
+				unsubscribe()
+				entry.listenerCleanup = undefined
 			}
 		})
-		this.sessionListenerCleanup.set(sessionId, unsubscribe)
+		entry.listenerCleanup = unsubscribe
+	}
+
+	private registerReopenedSession(
+		session: Session,
+		activity: SessionRuntimeActivityController,
+	): Result<SessionReopenRegistration | undefined, DomainError> {
+		if (this.shuttingDown) return Err(ValidationErrors.invalid('Session manager is shutting down'))
+		if (activity.getSnapshot().state !== 'ready') return Ok(undefined)
+		if (this.sessions.has(session.id)) return Err(SessionErrors.alreadyExists(String(session.id)))
+
+		const deferred = Promise.withResolvers<Session>()
+		void deferred.promise.catch(() => {})
+		const entry: SessionCacheEntry = {
+			state: 'loading',
+			promise: deferred.promise,
+			activity,
+			lastAccessAt: performance.now(),
+		}
+		this.sessions.set(session.id, entry)
+
+		return Ok({
+			complete: async () => {
+				if (this.sessions.get(session.id) !== entry) {
+					throw new Error(`Reopened session lost cache ownership: ${session.id}`)
+				}
+				this.registerSessionEventListener(session.id, session.store, session, entry)
+				try {
+					await session.callSessionReadyHooks()
+					session.checkPendingAgents()
+					if (this.sessions.get(session.id) !== entry || entry.state !== 'loading' || activity.getSnapshot().state !== 'ready') {
+						throw new Error(`Reopened session became unavailable during ready hooks: ${session.id}`)
+					}
+					entry.state = 'ready'
+					entry.lastAccessAt = performance.now()
+					deferred.resolve(session)
+				} catch (error) {
+					if (this.sessions.get(session.id) === entry) this.sessions.delete(session.id)
+					entry.listenerCleanup?.()
+					entry.listenerCleanup = undefined
+					deferred.reject(error)
+					await session.dispose('evicted')
+					throw error
+				}
+			},
+			abort: (error) => {
+				if (this.sessions.get(session.id) === entry) this.sessions.delete(session.id)
+				entry.listenerCleanup?.()
+				entry.listenerCleanup = undefined
+				deferred.reject(error)
+			},
+		})
+	}
+
+	private async evictIdleSessions(): Promise<void> {
+		if (this.sessionIdleTimeoutMs === 0) return
+		const now = performance.now()
+		const disposals: Promise<void>[] = []
+		for (const [sessionId, entry] of this.sessions) {
+			if (entry.state !== 'ready') continue
+			const activity = entry.activity.getSnapshot()
+			if (now - Math.max(entry.lastAccessAt, activity.lastActivityAt) < this.sessionIdleTimeoutMs) continue
+			if (!entry.activity.tryBeginUnload()) continue
+			const session = await entry.promise
+			disposals.push(this.beginCacheEntryDisposal(sessionId, entry, session, 'idle'))
+		}
+		await Promise.all(disposals)
+	}
+
+	private beginCacheEntryDisposal(
+		sessionId: SessionId,
+		entry: SessionCacheEntry,
+		session: Session,
+		reason: RuntimeDisposalCause,
+	): Promise<void> {
+		if (entry.unloadPromise) return entry.unloadPromise
+		entry.state = 'evicting'
+		entry.activity.beginForcedUnload()
+		entry.unloadPromise = session.dispose(RUNTIME_DISPOSAL_CLOSE_REASON[reason])
+			.catch((error) => {
+				this.logger.error(
+					'Failed to dispose session runtime',
+					error instanceof Error ? error : new Error(String(error)),
+					{ sessionId, reason },
+				)
+			})
+			.finally(() => {
+				if (this.sessions.get(sessionId) === entry) this.sessions.delete(sessionId)
+				entry.listenerCleanup?.()
+				entry.listenerCleanup = undefined
+				if (reason === 'idle') this.cacheEvictions++
+				this.logger.debug('Session runtime evicted', { sessionId, reason })
+			})
+		return entry.unloadPromise
 	}
 
 	private getSessionDir(sessionId: SessionId): string {
 		return join(this.basePath, 'sessions', String(sessionId))
 	}
 }
+
+function statsFromMetadata(metadata: SessionMetadata): SessionStatsState {
+	return {
+		totalTokens: metadata.metrics?.totalTokens ?? 0,
+		promptTokens: metadata.metrics?.inputTokens ?? 0,
+		completionTokens: metadata.metrics?.outputTokens ?? 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0,
+		totalCost: metadata.metrics?.totalCost ?? 0,
+		llmCalls: metadata.metrics?.totalLLMCalls ?? 0,
+		llmErrors: 0,
+		toolCalls: metadata.metrics?.totalToolCalls ?? 0,
+		toolErrors: 0,
+		userMessages: metadata.metrics?.totalMessages ?? 0,
+		compactions: 0,
+		agentCount: metadata.metrics?.totalAgents ?? 0,
+		firstEventAt: metadata.createdAt,
+		lastEventAt: metadata.lastActivityAt,
+		byProvider: {},
+		byAgent: {},
+	}
+}