@roj-ai/sdk 0.1.33 → 0.1.35

package/src/plugins/services/service.ts

@@ -13,6 +13,7 @@ import { Err, Ok } from '~/lib/utils/result.js'
 import type { FileSystem } from '~/platform/fs.js'
 import type { ChildProcess, ProcessRunner } from '~/platform/process.js'
 import type { PortPool } from '~/plugins/services/port-pool.js'
+import type { ServicePidRegistry } from '~/plugins/services/pid-registry.js'
 import type { ServiceConfig, ServiceStartArgs, ServiceStatus } from '~/plugins/services/schema.js'
 import type { ToolError } from '../../core/tools/executor.js'
 import type { Logger } from '../../lib/logger/logger.js'
@@ -69,6 +70,17 @@ export interface ServiceStatusChangeDetails {
 	pidStartTime?: number
 	cwd?: string
 	command?: string
+	/** Set on a `failed` change that already has a revival queued — see ServiceEntry.restartAt. */
+	restartAt?: number
+	restartAttempt?: number
+	restartMaxRetries?: number
+}
+
+/** A revival the policy has queued, as reported on the `failed` status change. */
+interface ScheduledRestart {
+	restartAt: number
+	restartAttempt: number
+	restartMaxRetries: number
 }
 
 /** Matches a port bind-conflict across the Node and Bun runtimes. */
@@ -82,6 +94,12 @@ const PORT_CONFLICT_PATTERN = /EADDRINUSE|address already in use/i
  */
 const MAX_PORT_CONFLICT_RETRIES = 3
 
+/** `restartPolicy` defaults — see ServiceConfig.restartPolicy for the rationale. */
+const DEFAULT_MAX_RESTART_RETRIES = 3
+const DEFAULT_RESTART_DELAY_MS = 1000
+const DEFAULT_MAX_RESTART_DELAY_MS = 30_000
+const DEFAULT_RESTART_HEALTHY_AFTER_MS = 60_000
+
 // ============================================================================
 // ServiceExecutor
 // ============================================================================
@@ -89,6 +107,8 @@ const MAX_PORT_CONFLICT_RETRIES = 3
 export interface ServiceExecutorDeps {
 	fs: FileSystem
 	process: ProcessRunner
+	/** Durable pid record, swept at agent boot. Optional so embedders without a data dir still work. */
+	pidRegistry?: ServicePidRegistry
 }
 
 export class ServiceExecutor {
@@ -99,10 +119,15 @@ export class ServiceExecutor {
 	private readonly startInFlight = new Map<string, Promise<Result<void, ToolError>>>()
 	/** Per-type counter bounding automatic EADDRINUSE port re-allocation retries. */
 	private readonly portConflictRetries = new Map<string, number>()
+	/** Per-type counter bounding `restartPolicy` revivals after an unexpected exit. */
+	private readonly restartRetries = new Map<string, number>()
+	/** Pending `restartPolicy` timers, cancelled when someone stops or starts the service by hand. */
+	private readonly restartTimers = new Map<string, ReturnType<typeof setTimeout>>()
 	private readonly logger: Logger
 	private readonly portPool: PortPool
 	private readonly fs: FileSystem
 	private readonly processRunner: ProcessRunner
+	private readonly pidRegistry?: ServicePidRegistry
 
 	/** Optional callback invoked on every service status change */
 	onStatusChanged?: (
@@ -117,6 +142,7 @@ export class ServiceExecutor {
 		this.portPool = portPool
 		this.fs = deps.fs
 		this.processRunner = deps.process
+		this.pidRegistry = deps.pidRegistry
 	}
 
 	private notifyStatusChanged(
@@ -249,6 +275,9 @@ export class ServiceExecutor {
 		workspaceDir?: string,
 		preferredPort?: number,
 	): Promise<Result<void, ToolError>> {
+		// This start supersedes any revival the policy had queued.
+		this.cancelPendingRestart(config.type)
+
 		const existing = this.services.get(config.type)
 		if (existing && (existing.status === 'starting' || existing.status === 'ready')) {
 			return Ok(undefined)
@@ -354,6 +383,11 @@ export class ServiceExecutor {
 		// "our process" from "an unrelated process that grabbed this PID after ours died"
 		const pidStartTime = await getProcessStartTime(this.fs, child.pid)
 
+		// Durably record the process so a future agent can reap it if we die before the
+		// `close` handler gets to forget it. The session projection cannot serve that
+		// purpose — see ServicePidRegistry.
+		await this.pidRegistry?.record({ sessionId: String(sessionId), serviceType: config.type, pid: child.pid, pidStartTime, command })
+
 		// Emit starting event with PID, port, resolved cwd/command, and start time.
 		this.notifyStatusChanged(sessionId, config.type, 'starting', { port, pid: child.pid, pidStartTime, cwd, command })
 
@@ -512,6 +546,8 @@ export class ServiceExecutor {
 		// Handle unexpected exit
 		child.on('close', (code) => {
 			clearReadinessTimers()
+			// The process is gone, so its durable record has nothing left to reap.
+			void this.pidRegistry?.forget(String(sessionId), config.type)
 			// Flush remaining partial lines
 			if (stdoutPartial) {
 				processLine(stdoutPartial)
@@ -555,17 +591,21 @@ export class ServiceExecutor {
 				// Unexpected exit
 				current.status = 'failed'
 				const errorMsg = `Process exited unexpectedly with code ${code}`
+				this.portConflictRetries.delete(config.type)
+				// Queue the revival first so the `failed` change can carry it — a
+				// consumer that sees a bare `failed` is entitled to treat it as terminal.
+				const revival = this.scheduleRestart(config, sessionId, workspaceDir, Date.now() - startTime, code)
 				this.notifyStatusChanged(sessionId, config.type, 'failed', {
 					port: current.port,
 					cwd: current.cwd,
 					command: current.command,
 					error: errorMsg,
+					...revival,
 				})
 				this.logger.warn('Service process exited unexpectedly', {
 					serviceType: config.type,
 					code,
 				})
-				this.portConflictRetries.delete(config.type)
 			}
 		})
 
@@ -587,16 +627,96 @@ export class ServiceExecutor {
 		return Ok(undefined)
 	}
 
+	/**
+	 * Bring a crashed service back if its `restartPolicy` allows it. The port
+	 * allocation is kept on purpose — the preview URL has to survive the bounce.
+	 *
+	 * Returns the queued revival so the caller can put it on the `failed` status
+	 * change, or undefined when the service is left failed for good.
+	 */
+	private scheduleRestart(
+		config: ServiceConfig,
+		sessionId: SessionId,
+		workspaceDir: string | undefined,
+		uptimeMs: number,
+		exitCode: number | null,
+	): ScheduledRestart | undefined {
+		const policy = config.restartPolicy
+		if (!policy) return undefined
+
+		// A service that ran for a while and then died is a new problem, not the
+		// continuation of a boot loop — give it a full budget again.
+		if (uptimeMs >= (policy.healthyAfterMs ?? DEFAULT_RESTART_HEALTHY_AFTER_MS)) {
+			this.restartRetries.delete(config.type)
+		}
+
+		const attempt = this.restartRetries.get(config.type) ?? 0
+		const maxRetries = policy.maxRetries ?? DEFAULT_MAX_RESTART_RETRIES
+		if (attempt >= maxRetries) {
+			this.logger.warn('Service left failed — automatic restart budget spent', {
+				serviceType: config.type,
+				attempts: attempt,
+				exitCode,
+			})
+			this.restartRetries.delete(config.type)
+			return undefined
+		}
+
+		const initialDelayMs = policy.initialDelayMs ?? DEFAULT_RESTART_DELAY_MS
+		const delayMs = Math.min(initialDelayMs * 2 ** attempt, policy.maxDelayMs ?? DEFAULT_MAX_RESTART_DELAY_MS)
+		this.restartRetries.set(config.type, attempt + 1)
+		this.logger.info('Restarting service after unexpected exit', {
+			serviceType: config.type,
+			attempt: attempt + 1,
+			maxRetries,
+			delayMs,
+			exitCode,
+		})
+
+		const timer = setTimeout(() => {
+			this.restartTimers.delete(config.type)
+			void this.start(config, sessionId, workspaceDir)
+		}, delayMs)
+		// A pending revival must not keep the process alive on its own.
+		timer.unref?.()
+		this.restartTimers.set(config.type, timer)
+
+		return { restartAt: Date.now() + delayMs, restartAttempt: attempt + 1, restartMaxRetries: maxRetries }
+	}
+
+	/** Drop a pending automatic restart — an explicit start or stop wins over it. Returns true if one was queued. */
+	private cancelPendingRestart(serviceType: string): boolean {
+		const timer = this.restartTimers.get(serviceType)
+		if (!timer) return false
+		clearTimeout(timer)
+		this.restartTimers.delete(serviceType)
+		return true
+	}
+
+	/** Whether a `restartPolicy` revival is queued — the service is down but coming back. */
+	hasScheduledRestart(serviceType: string): boolean {
+		return this.restartTimers.has(serviceType)
+	}
+
 	/**
 	 * Stop a running service gracefully.
 	 * Port is NOT released — kept for session-level stability across restarts.
 	 */
 	async stop(serviceType: string, sessionId: SessionId): Promise<Result<void, ToolError>> {
+		const hadPendingRestart = this.cancelPendingRestart(serviceType)
+		this.restartRetries.delete(serviceType)
 		const entry = this.services.get(serviceType)
 		if (!entry) {
 			return Err({ message: `Service '${serviceType}' not found`, recoverable: false })
 		}
 		if (entry.status !== 'starting' && entry.status !== 'ready' && entry.status !== 'paused') {
+			// A failed service with a revival queued is really "about to restart",
+			// and calling that off is a legitimate stop rather than an error.
+			if (hadPendingRestart) {
+				entry.status = 'stopped'
+				this.notifyStatusChanged(sessionId, serviceType, 'stopped')
+				return Ok(undefined)
+			}
 			return Err({ message: `Service '${serviceType}' is ${entry.status}, cannot stop`, recoverable: false })
 		}
 
@@ -751,6 +871,10 @@ export class ServiceExecutor {
 	 * Called on session close.
 	 */
 	async shutdown(): Promise<void> {
+		// Nothing queued may spawn after the executor is gone.
+		for (const serviceType of [...this.restartTimers.keys()]) this.cancelPendingRestart(serviceType)
+		this.restartRetries.clear()
+
 		const promises: Promise<void>[] = []
 
 		for (const [serviceType, entry] of this.services) {

package/src/plugins/services/services.integration.test.ts

@@ -15,6 +15,7 @@ import type { ServiceAgentConfig, ServicePluginConfig } from './plugin.js'
 import { PortPool } from './port-pool.js'
 import { buildServiceStatusMessage } from './prompt.js'
 import type { ServiceCommandArgs, ServiceConfig, ServiceCwdArgs, ServiceEntry, ServiceStatus } from './schema.js'
+import type { ServiceStatusChangeDetails } from './service.js'
 import { ServiceExecutor } from './service.js'
 
 // ============================================================================
@@ -823,6 +824,275 @@ describe('services plugin', () => {
 		})
 	})
 
+	// =========================================================================
+	// restartPolicy — reviving a service that exited on its own
+	// =========================================================================
+
+	describe('restartPolicy', () => {
+		const waitUntil = async (predicate: () => boolean, timeoutMs = 8000): Promise<void> => {
+			const deadline = Date.now() + timeoutMs
+			while (Date.now() < deadline) {
+				if (predicate()) return
+				await new Promise((r) => setTimeout(r, 20))
+			}
+		}
+
+		const waitUntilAsync = async (predicate: () => Promise<boolean>, timeoutMs = 8000): Promise<void> => {
+			const deadline = Date.now() + timeoutMs
+			while (Date.now() < deadline) {
+				if (await predicate()) return
+				await new Promise((r) => setTimeout(r, 20))
+			}
+		}
+
+		const marker = (name: string) => join(tmpdir(), `roj-restart-${name}-${Date.now()}-${Math.floor(Math.random() * 1e6)}`)
+		/** Records every spawn, then crashes or stays up depending on the run count. */
+		const crashCommand = (path: string, crashRuns: number) =>
+			`echo x >> ${path}; runs=$(wc -l < ${path} | tr -d ' '); if [ "$runs" -le ${crashRuns} ]; then exit 1; fi; echo "listening READY"; sleep 30`
+		const spawnCount = async (path: string): Promise<number> => {
+			try {
+				return (await readFile(path, 'utf-8')).split('\n').filter((l) => l.length > 0).length
+			} catch {
+				return 0
+			}
+		}
+
+		it('revives a crashed service on the port it already holds', async () => {
+			const platform = createNodePlatform()
+			const executor = new ServiceExecutor(silentLogger, new PortPool(), { fs: platform.fs, process: platform.process })
+			const path = marker('revive')
+			const config: ServiceConfig = {
+				type: 'revive-svc',
+				description: 'crashes once, then stays up',
+				command: crashCommand(path, 1),
+				readyPattern: 'READY',
+				startupTimeoutMs: 5000,
+				restartPolicy: { maxRetries: 3, initialDelayMs: 20 },
+			}
+			const ports: number[] = []
+			executor.onStatusChanged = (_s, _t, status, details) => {
+				if (status === 'starting' && details.port !== undefined) ports.push(details.port)
+			}
+
+			try {
+				await executor.start(config, SessionId('s-revive'))
+				await waitUntil(() => executor.getStatus('revive-svc') === 'ready')
+				expect(executor.getStatus('revive-svc')).toBe('ready')
+				expect(await spawnCount(path)).toBe(2)
+				// The preview URL must survive the bounce.
+				expect(new Set(ports).size).toBe(1)
+			} finally {
+				await executor.shutdown()
+				await rm(path, { force: true })
+			}
+		})
+
+		it('leaves the service failed once the retry budget is spent', async () => {
+			const platform = createNodePlatform()
+			const executor = new ServiceExecutor(silentLogger, new PortPool(), { fs: platform.fs, process: platform.process })
+			const path = marker('budget')
+			const config: ServiceConfig = {
+				type: 'budget-svc',
+				description: 'always crashes',
+				command: crashCommand(path, 99),
+				readyPattern: 'READY',
+				startupTimeoutMs: 5000,
+				restartPolicy: { maxRetries: 2, initialDelayMs: 20 },
+			}
+
+			try {
+				await executor.start(config, SessionId('s-budget'))
+				// One initial spawn plus two retries, then it stays down.
+				await waitUntilAsync(async () => (await spawnCount(path)) >= 3 && executor.getStatus('budget-svc') === 'failed')
+				await new Promise((r) => setTimeout(r, 300))
+				expect(await spawnCount(path)).toBe(3)
+				expect(executor.getStatus('budget-svc')).toBe('failed')
+			} finally {
+				await executor.shutdown()
+				await rm(path, { force: true })
+			}
+		})
+
+		it('without a policy a crash stays a crash', async () => {
+			const platform = createNodePlatform()
+			const executor = new ServiceExecutor(silentLogger, new PortPool(), { fs: platform.fs, process: platform.process })
+			const path = marker('nopolicy')
+			const config: ServiceConfig = {
+				type: 'nopolicy-svc',
+				description: 'always crashes, no restartPolicy',
+				command: crashCommand(path, 99),
+				readyPattern: 'READY',
+				startupTimeoutMs: 5000,
+			}
+
+			try {
+				await executor.start(config, SessionId('s-nopolicy'))
+				await waitUntil(() => executor.getStatus('nopolicy-svc') === 'failed')
+				await new Promise((r) => setTimeout(r, 300))
+				expect(await spawnCount(path)).toBe(1)
+			} finally {
+				await executor.shutdown()
+				await rm(path, { force: true })
+			}
+		})
+
+		it('a queued revival rides along on the failed status change', async () => {
+			const platform = createNodePlatform()
+			const executor = new ServiceExecutor(silentLogger, new PortPool(), { fs: platform.fs, process: platform.process })
+			const path = marker('event')
+			const config: ServiceConfig = {
+				type: 'event-svc',
+				description: 'crashes once, then stays up',
+				command: crashCommand(path, 1),
+				readyPattern: 'READY',
+				startupTimeoutMs: 5000,
+				restartPolicy: { maxRetries: 3, initialDelayMs: 20 },
+			}
+			const changes: Array<{ status: ServiceStatus; details: ServiceStatusChangeDetails }> = []
+			executor.onStatusChanged = (_s, _t, status, details) => {
+				changes.push({ status, details })
+			}
+
+			try {
+				await executor.start(config, SessionId('s-event'))
+				await waitUntil(() => executor.getStatus('event-svc') === 'ready')
+
+				const failedIndex = changes.findIndex((c) => c.status === 'failed')
+				expect(failedIndex).toBeGreaterThanOrEqual(0)
+				const failed = changes[failedIndex]!
+				expect(failed.details.restartAttempt).toBe(1)
+				expect(failed.details.restartMaxRetries).toBe(3)
+				expect(failed.details.restartAt).toBeGreaterThan(0)
+
+				// The revival's own start must not carry the intent it just honoured.
+				const revivalStart = changes.slice(failedIndex + 1).find((c) => c.status === 'starting')
+				expect(revivalStart).toBeDefined()
+				expect(revivalStart!.details.restartAt).toBeUndefined()
+			} finally {
+				await executor.shutdown()
+				await rm(path, { force: true })
+			}
+		})
+
+		it('the failure that spends the budget carries no revival', async () => {
+			const platform = createNodePlatform()
+			const executor = new ServiceExecutor(silentLogger, new PortPool(), { fs: platform.fs, process: platform.process })
+			const path = marker('terminal')
+			const config: ServiceConfig = {
+				type: 'terminal-svc',
+				description: 'always crashes',
+				command: crashCommand(path, 99),
+				readyPattern: 'READY',
+				startupTimeoutMs: 5000,
+				restartPolicy: { maxRetries: 1, initialDelayMs: 20 },
+			}
+			const failures: ServiceStatusChangeDetails[] = []
+			executor.onStatusChanged = (_s, _t, status, details) => {
+				if (status === 'failed') failures.push(details)
+			}
+
+			try {
+				await executor.start(config, SessionId('s-terminal'))
+				await waitUntilAsync(async () => (await spawnCount(path)) >= 2 && failures.length >= 2)
+				expect(failures[0]?.restartAttempt).toBe(1)
+				expect(failures[1]?.restartAt).toBeUndefined()
+				expect(failures[1]?.restartAttempt).toBeUndefined()
+			} finally {
+				await executor.shutdown()
+				await rm(path, { force: true })
+			}
+		})
+
+		it('session state shows the queued revival and drops it once called off', async () => {
+			const portPool = new PortPool()
+			const config: ServiceConfig = {
+				type: 'reviving',
+				description: 'crashes early, revival queued behind a long delay',
+				// The sleep keeps the exit from beating the executor's close listener.
+				command: 'sleep 0.2; exit 1',
+				restartPolicy: { maxRetries: 3, initialDelayMs: 3000 },
+			}
+			const harness = createServicesHarness({
+				presets: [createServicesPreset([config], ['reviving'], portPool)],
+			})
+			const session = await harness.createSession('test')
+
+			await session.callPluginMethod('services.start', { serviceType: 'reviving' })
+			await waitForServiceStateStatus(session, 'reviving', 'failed')
+
+			const entry = selectPluginState<Map<string, ServiceEntry>>(session.state, 'services')?.get('reviving')
+			expect(entry?.status).toBe('failed')
+			expect(entry?.restartAt).toBeGreaterThan(Date.now())
+			expect(entry?.restartAttempt).toBe(1)
+			expect(entry?.restartMaxRetries).toBe(3)
+
+			const stopped = await session.callPluginMethod('services.stop', { serviceType: 'reviving' })
+			expect(stopped.ok).toBe(true)
+			await waitForServiceStateStatus(session, 'reviving', 'stopped')
+
+			const after = selectPluginState<Map<string, ServiceEntry>>(session.state, 'services')?.get('reviving')
+			expect(after?.status).toBe('stopped')
+			expect(after?.restartAt).toBeUndefined()
+			expect(after?.restartAttempt).toBeUndefined()
+		})
+
+		it('closing the session calls off a queued revival', async () => {
+			const portPool = new PortPool()
+			const path = marker('close')
+			const config: ServiceConfig = {
+				type: 'close-svc',
+				description: 'crashes early, revival queued behind a delay',
+				// The sleep keeps the exit from beating the executor's close listener.
+				command: `echo x >> ${path}; sleep 0.2; exit 1`,
+				restartPolicy: { maxRetries: 3, initialDelayMs: 800 },
+			}
+			const harness = createServicesHarness({
+				presets: [createServicesPreset([config], ['close-svc'], portPool)],
+			})
+			const session = await harness.createSession('test')
+
+			try {
+				await session.callPluginMethod('services.start', { serviceType: 'close-svc' })
+				await waitForServiceStateStatus(session, 'close-svc', 'failed')
+				expect(await spawnCount(path)).toBe(1)
+
+				await session.close()
+				// Long enough for the revival to have fired had nothing called it off.
+				await new Promise((r) => setTimeout(r, 1500))
+				expect(await spawnCount(path)).toBe(1)
+			} finally {
+				await rm(path, { force: true })
+			}
+		})
+
+		it('an explicit stop calls off a queued revival', async () => {
+			const platform = createNodePlatform()
+			const executor = new ServiceExecutor(silentLogger, new PortPool(), { fs: platform.fs, process: platform.process })
+			const path = marker('stop')
+			const config: ServiceConfig = {
+				type: 'stop-svc',
+				description: 'always crashes, revival queued behind a long delay',
+				command: crashCommand(path, 99),
+				readyPattern: 'READY',
+				startupTimeoutMs: 5000,
+				restartPolicy: { maxRetries: 3, initialDelayMs: 1500 },
+			}
+
+			try {
+				await executor.start(config, SessionId('s-stop'))
+				await waitUntil(() => executor.getStatus('stop-svc') === 'failed')
+				const stopped = await executor.stop('stop-svc', SessionId('s-stop'))
+				expect(stopped.ok).toBe(true)
+				expect(executor.getStatus('stop-svc')).toBe('stopped')
+				await new Promise((r) => setTimeout(r, 2000))
+				expect(await spawnCount(path)).toBe(1)
+			} finally {
+				await executor.shutdown()
+				await rm(path, { force: true })
+			}
+		})
+	})
+
 	// =========================================================================
 	// agentVisible: false — infrastructure services hidden from agents
 	// =========================================================================

package/src/plugins/session-lifecycle/plugin.ts

@@ -11,8 +11,9 @@ import { agentIdSchema } from '~/core/agents'
 import { COMMUNICATOR_ROLE, ORCHESTRATOR_ROLE } from '~/core/agents/agent-roles.js'
 import { type DomainError, PresetErrors, SessionErrors, ValidationErrors } from '~/core/errors.js'
 import { definePlugin } from '~/core/plugins/index.js'
+import { knownDefinitionNames, unknownOverrideTargets } from '~/core/preset/overrides.js'
 import { SessionId, sessionIdSchema } from '~/core/sessions/schema.js'
-import { getEntryAgentId, sessionEvents } from '~/core/sessions/state.js'
+import { agentOverridesSchema, getEntryAgentId, sessionEvents, sessionOverridesPatchSchema } from '~/core/sessions/state.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 
 // ============================================================================
@@ -115,6 +116,7 @@ export const sessionLifecyclePlugin = definePlugin('sessions')
 			presetId: z4.string().min(1),
 			workspaceDir: z4.string().optional(),
 			sessionId: z4.string().optional(),
+			overrides: sessionOverridesPatchSchema.optional(),
 		}),
 		output: z4.object({
 			sessionId: sessionIdSchema,
@@ -126,11 +128,13 @@ export const sessionLifecyclePlugin = definePlugin('sessions')
 				presetId: input.presetId,
 				workspaceDir: input.workspaceDir ?? null,
 				sessionId: input.sessionId ?? null,
+				overrides: input.overrides ?? null,
 			})
 
 			const sessionResult = await sm.createSession(input.presetId, {
 				workspaceDir: input.workspaceDir,
 				sessionId: input.sessionId,
+				overrides: input.overrides,
 			})
 			if (!sessionResult.ok) return sessionResult
 
@@ -183,6 +187,12 @@ export const sessionLifecyclePlugin = definePlugin('sessions')
 			closedAt: z4.number().optional(),
 			agentCount: z4.number(),
 			entryAgentId: agentIdSchema.nullable(),
+			// Reported back so a caller can tell "the override did not apply" from
+			// "this build predates overrides and dropped the field on input".
+			overrides: z4.object({
+				defaults: agentOverridesSchema.optional(),
+				agents: z4.record(z4.string(), agentOverridesSchema),
+			}),
 		}),
 		handler: async (ctx) => {
 			const state = ctx.sessionState
@@ -194,6 +204,54 @@ export const sessionLifecyclePlugin = definePlugin('sessions')
 				closedAt: state.closedAt,
 				agentCount: state.agents.size,
 				entryAgentId: getEntryAgentId(state),
+				overrides: {
+					defaults: state.overrides.defaults,
+					agents: Object.fromEntries(state.overrides.agents),
+				},
+			})
+		},
+	})
+	// A manager method, not a session method, purely so it can see the preset and
+	// reject unknown agent names — session method contexts carry no preset.
+	// `presets.getAgents` is a manager method for the same reason.
+	.managerMethod('setOverrides', {
+		input: z4.object({
+			sessionId: sessionIdSchema,
+			overrides: sessionOverridesPatchSchema,
+		}),
+		output: z4.object({
+			agents: z4.record(z4.string(), agentOverridesSchema),
+			defaults: agentOverridesSchema.optional(),
+		}),
+		handler: async (ctx, input) => {
+			const sm = ctx.sessionManager
+			const sessionId = SessionId(input.sessionId)
+
+			const sessionResult = await sm.getSession(sessionId)
+			if (!sessionResult.ok) return sessionResult
+			const session = sessionResult.value
+
+			const preset = ctx.presets.get(session.state.presetId)
+			if (!preset) return Err(PresetErrors.notFound(session.state.presetId))
+
+			const unknown = unknownOverrideTargets(preset, input.overrides)
+			if (unknown.length > 0) {
+				return Err(ValidationErrors.invalid(
+					`Unknown agent definitions in overrides: ${unknown.join(', ')}. Preset '${preset.id}' defines: ${knownDefinitionNames(preset).join(', ')}`,
+				))
+			}
+
+			await session.setOverrides(input.overrides)
+
+			// Agents already mid-turn finish on the model they started with: the
+			// override is read when the next inference request is built, not applied
+			// retroactively to one in flight.
+			ctx.logger.info('Session overrides set', { sessionId, overrides: input.overrides })
+
+			const state = session.state
+			return Ok({
+				agents: Object.fromEntries(state.overrides.agents),
+				defaults: state.overrides.defaults,
 			})
 		},
 	})

package/src/testing/test-harness.ts

@@ -13,7 +13,7 @@ import { selectPluginState } from '~/core/sessions/reducer.js'
 import type { SessionId } from '~/core/sessions/schema.js'
 import { SessionManager } from '~/core/sessions/session-manager.js'
 import type { Session } from '~/core/sessions/session.js'
-import type { SessionState } from '~/core/sessions/state.js'
+import type { SessionOverridesPatch, SessionState } from '~/core/sessions/state.js'
 import { ToolExecutor } from '~/core/tools/executor.js'
 import { silentLogger } from '~/lib/logger/logger.js'
 import { createNodePlatform } from './node-platform.js'
@@ -145,14 +145,25 @@ export class TestHarness {
 	/**
 	 * Create a session and return a TestSession wrapper.
 	 */
-	async createSession(presetId: string): Promise<TestSession> {
-		const result = await this.sessionManager.createSession(presetId)
+	async createSession(
+		presetId: string,
+		options?: { workspaceDir?: string; overrides?: SessionOverridesPatch },
+	): Promise<TestSession> {
+		const result = await this.sessionManager.createSession(presetId, options)
 		if (!result.ok) {
 			throw new Error(`Failed to create session: ${result.error.type} — ${result.error.message}`)
 		}
 		return new TestSession(result.value, this)
 	}
 
+	/** Create a session expecting failure, returning the error instead of throwing. */
+	async createSessionResult(
+		presetId: string,
+		options?: { workspaceDir?: string; overrides?: SessionOverridesPatch },
+	): Promise<Result<Session, DomainError>> {
+		return this.sessionManager.createSession(presetId, options)
+	}
+
 	/**
 	 * Open an existing session from the event store (replays events, runs onSessionReady hooks).
 	 * Used to simulate server restart by pairing with another harness over the same eventStore.
@@ -218,6 +229,14 @@ export class TestSession {
 		await waitForAllAgentsIdle(this.session, opts)
 	}
 
+	/** Patch session overrides (see Session.setOverrides). */
+	async setOverrides(patch: SessionOverridesPatch): Promise<void> {
+		const result = await this.session.setOverrides(patch)
+		if (!result.ok) {
+			throw new Error(`setOverrides failed: ${result.error.type} — ${result.error.message}`)
+		}
+	}
+
 	/**
 	 * Send a message and wait for all agents to become idle.
 	 */