@namzu/sdk 48.0.0 → 48.2.0

package/src/connector/mcp/streamable-http.ts

@@ -7,7 +7,11 @@ import type {
 } from '../../types/connector/index.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
-import { ConnectorHttpOperation, validateConnectorTimeoutMs } from '../http-operation.js'
+import {
+	ConnectorHttpOperation,
+	readConnectorResponseBody,
+	validateConnectorTimeoutMs,
+} from '../http-operation.js'
 import { MCPHttpStatusError } from './errors.js'
 import { refuseMcpHttpRedirect } from './http-redirect.js'
 
@@ -21,6 +25,23 @@ const DEFAULT_TIMEOUT_MS = 30_000
  * an unresponsive peer does not accumulate as a dangling request forever.
  */
 const SESSION_DELETE_TIMEOUT_MS = 5_000
+/** SSE streams may live for hours; bound each event and read rather than their lifetime. */
+const MAX_SSE_EVENT_CHARS = 1_048_576
+const MAX_SSE_CHUNK_BYTES = 8_388_608
+/** A single event may contain a JSON-RPC batch; bound its dispatch work too. */
+const MAX_RESPONSE_SSE_MESSAGES_PER_EVENT = 256
+const MAX_SUBSCRIPTION_ERROR_BODY_BYTES = 65_536
+
+/** A successful HTTP status can still carry a JSON-RPC listen refusal. */
+export class MCPSubscriptionResponseError extends Error {
+	readonly bodyText: string
+
+	constructor(bodyText: string) {
+		super('MCP subscriptions/listen returned JSON instead of an SSE response stream')
+		this.name = 'MCPSubscriptionResponseError'
+		this.bodyText = bodyText
+	}
+}
 
 export class StreamableHttpTransport implements MCPTransport {
 	private messageHandlers: Array<(message: MCPJsonRpcMessage) => void> = []
@@ -202,7 +223,7 @@ export class StreamableHttpTransport implements MCPTransport {
 			// POST capable of poisoning every later request on this connection.
 			if (message.method === 'initialize') this.captureSessionId(response)
 
-			await this.dispatchResponseMessages(response, operation, owned.generation)
+			await this.dispatchResponseMessages(response, operation, owned.generation, message.id)
 		} finally {
 			// A streamable HTTP send owns one POST; its rejection is delivered to
 			// that caller. It is not evidence that the logical MCP session died.
@@ -213,6 +234,124 @@ export class StreamableHttpTransport implements MCPTransport {
 		}
 	}
 
+	/**
+	 * Modern MCP subscriptions are long-lived POST response streams. The ordinary
+	 * `send` has a request deadline and stops at its terminal reply; a
+	 * subscription may remain open indefinitely. The client owns the initial
+	 * acknowledgment deadline and this stream's abort signal.
+	 */
+	async sendSubscription(
+		message: MCPJsonRpcMessage,
+		options: MCPTransportSendOptions,
+		onMessage?: (message: MCPJsonRpcMessage) => void,
+	): Promise<void> {
+		if (message.method !== 'subscriptions/listen' || message.id === undefined) {
+			throw new Error('sendSubscription requires a subscriptions/listen request')
+		}
+		if (!this.connected) throw new Error('StreamableHttpTransport: not connected')
+		const owned = this.beginSend(options.signal)
+		try {
+			const response = await this.fetchImpl(this.config.url, {
+				method: 'POST',
+				headers: this.buildHeaders(options.headers),
+				body: JSON.stringify(message),
+				redirect: 'manual',
+				signal: owned.controller.signal,
+			})
+			refuseMcpHttpRedirect(response, message.method)
+			if (!response.ok) {
+				throw new MCPHttpStatusError(
+					'StreamableHttpTransport',
+					response.status,
+					response.statusText,
+					await readSubscriptionErrorBody(response, owned.controller.signal, this.timeoutMs),
+				)
+			}
+			const mediaType = (response.headers.get('content-type') ?? '')
+				.split(';', 1)[0]
+				?.trim()
+				.toLowerCase()
+			if (mediaType !== 'text/event-stream' || !response.body) {
+				// A 200 JSON response can be a valid in-band JSON-RPC refusal.
+				// Read it under the same byte and time bounds as a failed HTTP
+				// response, then release its body before retry classification.
+				if (mediaType === 'application/json' && response.body) {
+					throw new MCPSubscriptionResponseError(
+						await readSubscriptionErrorBody(response, owned.controller.signal, this.timeoutMs),
+					)
+				}
+				// Unknown response media types still own a body. Never leave a
+				// held POST open while the client schedules its next attempt.
+				void response.body?.cancel().catch(() => undefined)
+				throw new Error('MCP subscriptions/listen did not return an SSE response stream')
+			}
+
+			const reader = response.body.getReader()
+			const decoder = new TextDecoder()
+			let buffer = ''
+			let previousChunkEndedWithCr = false
+			const cancelReader = (): void => {
+				void reader.cancel().catch(() => undefined)
+			}
+			owned.controller.signal.addEventListener('abort', cancelReader, { once: true })
+			if (owned.controller.signal.aborted) cancelReader()
+			try {
+				while (this.connected && owned.generation === this.generation) {
+					const { done, value } = await reader.read()
+					if (done) break
+					if (
+						!this.connected ||
+						owned.generation !== this.generation ||
+						owned.controller.signal.aborted
+					)
+						break
+					if (value.byteLength > MAX_SSE_CHUNK_BYTES) {
+						throw new Error('MCP subscription SSE chunk exceeds its size limit')
+					}
+					const oldLength = buffer.length
+					let chunk = decoder.decode(value, { stream: true })
+					// SSE permits LF, CRLF, and bare CR. A CRLF split across chunks
+					// still counts as one line break, not an empty line.
+					if (previousChunkEndedWithCr && chunk.startsWith('\n')) chunk = chunk.slice(1)
+					previousChunkEndedWithCr = chunk.endsWith('\r')
+					buffer += chunk.replace(/\r\n|\r/g, '\n')
+					let searchFrom = Math.max(0, oldLength - 1)
+					while (true) {
+						const boundary = findSseEventBoundary(buffer, searchFrom)
+						if (!boundary) break
+						if (boundary.start > MAX_SSE_EVENT_CHARS) {
+							throw new Error('MCP subscription SSE event exceeds its size limit')
+						}
+						const event = buffer.slice(0, boundary.start)
+						buffer = buffer.slice(boundary.end)
+						searchFrom = 0
+						for (const frame of parseSseMessages(event).messages) {
+							if (
+								!this.connected ||
+								owned.generation !== this.generation ||
+								owned.controller.signal.aborted
+							)
+								return
+							if (onMessage) onMessage(frame)
+							else for (const handler of [...this.messageHandlers]) handler(frame)
+						}
+					}
+					if (buffer.length > MAX_SSE_EVENT_CHARS) {
+						throw new Error('MCP subscription SSE event exceeds its size limit')
+					}
+				}
+				// A dangling partial event is not a notification. It cannot be
+				// forwarded as a complete JSON-RPC frame when the stream closes.
+			} finally {
+				owned.controller.signal.removeEventListener('abort', cancelReader)
+				cancelReader()
+				reader.releaseLock()
+			}
+		} finally {
+			owned.dispose()
+		}
+	}
+
 	onMessage(handler: (message: MCPJsonRpcMessage) => void): void {
 		this.messageHandlers.push(handler)
 	}
@@ -300,22 +439,119 @@ export class StreamableHttpTransport implements MCPTransport {
 		response: Response,
 		operation: ConnectorHttpOperation,
 		generation: number,
+		requestId: string | number | undefined,
 	): Promise<void> {
+		const contentType = response.headers.get('content-type') ?? ''
+		if (contentType.includes('text/event-stream') && response.body) {
+			await this.dispatchSseResponseMessages(response.body, operation, generation, requestId)
+			return
+		}
 		const text = await operation.run(() => response.text())
 		this.assertCurrent(generation, operation)
 		if (text.trim().length === 0) return
 
-		const contentType = response.headers.get('content-type') ?? ''
 		const messages = contentType.includes('text/event-stream')
 			? this.parseSseAndCaptureEventId(text)
 			: parseJsonMessages(text)
 
 		for (const message of messages) {
+			this.dispatchMessage(message, operation, generation)
+		}
+	}
+
+	private dispatchMessage(
+		message: MCPJsonRpcMessage,
+		operation: ConnectorHttpOperation,
+		generation: number,
+	): void {
+		this.assertCurrent(generation, operation)
+		for (const handler of [...this.messageHandlers]) {
 			this.assertCurrent(generation, operation)
-			for (const handler of [...this.messageHandlers]) {
+			handler(message)
+		}
+	}
+
+	/** Dispatch a complete SSE event as it arrives, without waiting for EOF. */
+	private async dispatchSseResponseMessages(
+		body: ReadableStream<Uint8Array>,
+		operation: ConnectorHttpOperation,
+		generation: number,
+		requestId: string | number | undefined,
+	): Promise<void> {
+		const reader = body.getReader()
+		const decoder = new TextDecoder()
+		let buffer = ''
+		let previousChunkEndedWithCr = false
+		const dispatchEvent = (event: string): boolean => {
+			if (event.length > MAX_SSE_EVENT_CHARS) {
+				throw new Error('MCP response SSE event exceeds its size limit')
+			}
+			if (sseBatchExceedsMessageLimit(event, MAX_RESPONSE_SSE_MESSAGES_PER_EVENT)) {
+				throw new Error('MCP response SSE event exceeds its message limit')
+			}
+			const parsed = parseSseMessages(event)
+			if (parsed.lastEventId !== undefined) this.lastEventId = parsed.lastEventId
+			if (parsed.messages.length > MAX_RESPONSE_SSE_MESSAGES_PER_EVENT) {
+				throw new Error('MCP response SSE event exceeds its message limit')
+			}
+			for (const message of parsed.messages) {
+				this.dispatchMessage(message, operation, generation)
+				if (
+					requestId !== undefined &&
+					message.id === requestId &&
+					message.method === undefined &&
+					(Object.hasOwn(message, 'result') || Object.hasOwn(message, 'error'))
+				) {
+					// The request is complete even if the peer keeps its SSE body open.
+					return true
+				}
+			}
+			return false
+		}
+		const appendChunk = (decoded: string): boolean => {
+			if (!decoded) return false
+			let chunk = decoded
+			// A CRLF split across reads is one line break; LF, CRLF and bare
+			// CR all delimit SSE lines.
+			if (previousChunkEndedWithCr && chunk.startsWith('\n')) chunk = chunk.slice(1)
+			previousChunkEndedWithCr = chunk.endsWith('\r')
+			buffer += chunk.replace(/\r\n|\r/g, '\n')
+			while (true) {
+				const boundary = findSseEventBoundary(buffer, 0)
+				if (!boundary) break
+				if (boundary.start > MAX_SSE_EVENT_CHARS) {
+					throw new Error('MCP response SSE event exceeds its size limit')
+				}
+				const event = buffer.slice(0, boundary.start)
+				buffer = buffer.slice(boundary.end)
+				if (dispatchEvent(event)) return true
+			}
+			if (buffer.length > MAX_SSE_EVENT_CHARS) {
+				throw new Error('MCP response SSE event exceeds its size limit')
+			}
+			return false
+		}
+		try {
+			while (true) {
+				const { done, value } = await operation.run(() => reader.read())
 				this.assertCurrent(generation, operation)
-				handler(message)
+				if (done) {
+					if (appendChunk(decoder.decode())) return
+					// Retain the old whole-body reader's acceptance of a final event
+					// without a trailing blank line when the peer actually closes.
+					if (buffer.trim()) dispatchEvent(buffer)
+					return
+				}
+				if (value.byteLength > MAX_SSE_CHUNK_BYTES) {
+					throw new Error('MCP response SSE chunk exceeds its size limit')
+				}
+				if (appendChunk(decoder.decode(value, { stream: true }))) return
 			}
+		} finally {
+			// Cancelling is best effort: a hostile or custom body must not hold
+			// send() open after a terminal reply, timeout, or caller abort.
+			void reader.cancel().catch(() => undefined)
+			reader.releaseLock()
 		}
 	}
 
@@ -334,6 +570,67 @@ export class StreamableHttpTransport implements MCPTransport {
 	}
 }
 
+/** Count only top-level JSON-array separators, skipping nested values and strings. */
+function sseBatchExceedsMessageLimit(event: string, limit: number): boolean {
+	const data = event
+		.split('\n')
+		.filter((line) => line.startsWith('data:'))
+		.map((line) => line.slice('data:'.length).trimStart())
+		.join('\n')
+		.trimStart()
+	if (!data.startsWith('[')) return false
+	let depth = 0
+	let inString = false
+	let escaped = false
+	let separators = 0
+	for (const character of data) {
+		if (inString) {
+			if (escaped) escaped = false
+			else if (character === '\\') escaped = true
+			else if (character === '"') inString = false
+			continue
+		}
+		if (character === '"') inString = true
+		else if (character === '[' || character === '{') depth++
+		else if (character === ']' || character === '}') depth--
+		else if (character === ',' && depth === 1 && ++separators >= limit) return true
+	}
+	return false
+}
+
+/** Find an SSE blank line after line endings have been normalized to LF. */
+function findSseEventBoundary(
+	value: string,
+	from: number,
+): { start: number; end: number } | undefined {
+	const start = value.indexOf('\n\n', from)
+	return start < 0 ? undefined : { start, end: start + 2 }
+}
+
+/** Keep a rejected listen response useful for diagnosis without buffering an unbounded body. */
+async function readSubscriptionErrorBody(
+	response: Response,
+	signal: AbortSignal,
+	timeoutMs: number,
+): Promise<string> {
+	const operation = new ConnectorHttpOperation(signal, timeoutMs, 'MCP subscription error body')
+	try {
+		const body = await readConnectorResponseBody(
+			response,
+			operation,
+			MAX_SUBSCRIPTION_ERROR_BODY_BYTES,
+		)
+		return typeof body === 'string' ? body : (JSON.stringify(body) ?? '')
+	} catch {
+		// The status is still the answer when a peer sends an unreadable,
+		// oversized, or stalled error body.
+		return ''
+	} finally {
+		operation.close()
+		void response.body?.cancel().catch(() => undefined)
+	}
+}
+
 /**
  * The body of a failed response, or an empty string.
  *

package/src/manager/agent/lifecycle.ts

@@ -1,4 +1,5 @@
-import { rm } from 'node:fs/promises'
+import { realpath, rm, stat } from 'node:fs/promises'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
 import { AGENT_MANAGER_DEFAULTS } from '../../constants/agent/index.js'
 import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
 import { GENAI } from '../../constants/telemetry/index.js'
@@ -9,6 +10,7 @@ import {
 } from '../../session/handoff/capacity.js'
 import type { SessionLocator, SessionPaths } from '../../session/paths.js'
 import type { SessionSummaryMaterializer } from '../../session/summary/materialize.js'
+import type { WorkspaceBackendDriver } from '../../session/workspace/driver.js'
 import type { WorkspaceBackendRegistry } from '../../session/workspace/registry.js'
 import {
 	DiskSessionLog,
@@ -151,6 +153,7 @@ interface ChildSpawnRecord {
 	/** Removes the child's log from the process-local lookup. */
 	releaseLog?: () => void
 	workspaceRef?: WorkspaceRef
+	workspaceRetention?: 'retain'
 	/**
 	 * What this child was actually granted, after the ancestor union.
 	 *
@@ -180,6 +183,81 @@ function mergeEnv(
 	return { ...base, ...override }
 }
 
+/** A requested isolated child must never resolve to its caller's directory. */
+async function requireIsolatedWorktreePath(
+	ref: WorkspaceRef | undefined,
+	callerCwd?: string,
+	subdirectory?: string,
+): Promise<string> {
+	const meta = ref?.meta
+	if (
+		typeof ref?.id !== 'string' ||
+		ref.id.length === 0 ||
+		meta?.backend !== 'git-worktree' ||
+		typeof meta.repoRoot !== 'string' ||
+		!isAbsolute(meta.repoRoot) ||
+		typeof meta.branch !== 'string' ||
+		meta.branch.length === 0 ||
+		typeof meta.worktreePath !== 'string' ||
+		!isAbsolute(meta.worktreePath) ||
+		resolve(meta.worktreePath) === resolve(callerCwd ?? process.cwd())
+	) {
+		throw new Error('Isolated git-worktree driver returned an invalid workspace ref or path')
+	}
+	// A custom driver can return a different absolute spelling of the same
+	// directory (for example, a symlink to the caller). Both paths must exist
+	// before the child is admitted, and their physical roots must differ.
+	let physicalPaths: [string, string]
+	try {
+		physicalPaths = await Promise.all([
+			realpath(meta.worktreePath),
+			realpath(resolve(callerCwd ?? process.cwd())),
+		])
+		if (!(await stat(physicalPaths[0])).isDirectory()) {
+			throw new Error('The worktree path is not a directory')
+		}
+	} catch (cause) {
+		throw new Error('Isolated git-worktree driver returned an invalid workspace ref or path', {
+			cause,
+		})
+	}
+	if (physicalPaths[0] === physicalPaths[1]) {
+		throw new Error('Isolated git-worktree driver returned an invalid workspace ref or path')
+	}
+	if (subdirectory === undefined) return meta.worktreePath
+	if (typeof subdirectory !== 'string' || subdirectory.length === 0 || isAbsolute(subdirectory)) {
+		throw new Error('Isolated workspace subdirectory must be a nonempty relative path')
+	}
+	const lexicalChild = resolve(meta.worktreePath, subdirectory)
+	const lexicalRelative = relative(resolve(meta.worktreePath), lexicalChild)
+	if (
+		isAbsolute(lexicalRelative) ||
+		lexicalRelative === '..' ||
+		lexicalRelative.startsWith(`..${sep}`)
+	) {
+		throw new Error('Isolated workspace subdirectory escapes the worktree')
+	}
+	let physicalChild: string
+	try {
+		physicalChild = await realpath(lexicalChild)
+		if (!(await stat(physicalChild)).isDirectory()) {
+			throw new Error('The selected worktree path is not a directory')
+		}
+	} catch (cause) {
+		throw new Error('Isolated workspace subdirectory is missing or not a directory', { cause })
+	}
+	const physicalRelative = relative(physicalPaths[0], physicalChild)
+	if (
+		physicalRelative === '' ||
+		isAbsolute(physicalRelative) ||
+		physicalRelative === '..' ||
+		physicalRelative.startsWith(`..${sep}`)
+	) {
+		throw new Error('Isolated workspace subdirectory resolves outside its worktree')
+	}
+	return physicalChild
+}
+
 /**
  * One `reviewAllowedCalls` that answers `true` when any of `sources` does.
  *
@@ -283,7 +361,9 @@ export class AgentManager {
 			if (task.context === context || context.parentAbortController.signal.aborted)
 				this.cancel(task.taskId, 'parent')
 		}
-		task.childAbortController.signal.addEventListener('abort', onAbort, { once: true })
+		task.childAbortController.signal.addEventListener('abort', onAbort, {
+			once: true,
+		})
 		const entry: PendingSpawn = {
 			ready: false,
 			task,
@@ -522,9 +602,25 @@ export class AgentManager {
 			await childBudget.flush()
 			throw error
 		}
+		let childOptions: SendMessageOptions = options
 		let childAbortController: AbortController | undefined
 		let agentTask: AgentTask | undefined
 		try {
+			// Explicit isolation is the child's execution root, not a side
+			// resource. Keep validation in this rollback envelope too.
+			if (options.workspace?.mode === 'isolated') {
+				childOptions = {
+					...options,
+					input: {
+						...options.input,
+						workingDirectory: await requireIsolatedWorktreePath(
+							spawnRecord.workspaceRef,
+							options.input.workingDirectory,
+							options.workspace.subdirectory,
+						),
+					},
+				}
+			}
 			childAbortController =
 				queuedTask?.childAbortController ??
 				createChildAbortController(context.parentAbortController)
@@ -599,6 +695,7 @@ export class AgentManager {
 				state: 'pending',
 				pendingMessages: queuedTask?.pendingMessages ?? [],
 				createdAt: queuedTask?.createdAt ?? Date.now(),
+				workspace: options.workspace?.mode === 'isolated' ? spawnRecord.workspaceRef : undefined,
 				sessionEventListener: listener,
 			} satisfies AgentTask)
 
@@ -676,6 +773,7 @@ export class AgentManager {
 						...(context.factoryOptions ?? {}),
 						tokenBudget: allocatedTokens,
 						timeoutMs: options.budgetAllocation?.timeoutMs ?? this.config.childTimeoutMs,
+						workingDirectory: childOptions.input.workingDirectory,
 						sessionId: spawnRecord.childSessionId,
 						parentSessionId: spawnRecord.parentSessionId,
 						parentTurnId: spawnRecord.parentTurnId,
@@ -872,11 +970,11 @@ export class AgentManager {
 				spawnRecord,
 				childConfig,
 				context,
-				options,
+				childOptions,
 				taskId,
 			)
 			if (childLog) {
-				await this.startChildSessionLog(childLog, spawnRecord, context, options, taskId, {
+				await this.startChildSessionLog(childLog, spawnRecord, context, childOptions, taskId, {
 					id: agent.metadata.id,
 					name: agent.metadata.name,
 				})
@@ -903,7 +1001,7 @@ export class AgentManager {
 			childAbortController.signal.throwIfAborted()
 			this.executingTasks.add(taskId)
 			const runningTask = agentTask
-			this.runChild(runningTask, options, childConfig, listener)
+			this.runChild(runningTask, childOptions, childConfig, listener)
 				.catch(async (err) => {
 					// A thrown invocation supplied no final usage receipt. Keep its
 					// reservation, including when its task handle was canceled or evicted.
@@ -999,6 +1097,9 @@ export class AgentManager {
 			this.scheduleEviction(agentTask.taskId)
 		} else this.instances.delete(agentTask.taskId)
 		this.dropSpawnRecord(agentTask.taskId)
+		// Admission never completed. The checkout is rollback-owned, not a
+		// retained result that a terminal handle may advertise.
+		agentTask.workspace = undefined
 		this.resolveCompletionCallbacks(agentTask.taskId)
 		await this.rollbackSpawnResources(spawnRecord)
 	}
@@ -1015,7 +1116,7 @@ export class AgentManager {
 				}),
 			)
 		}
-		await this.disposeChildWorkspace(spawnRecord)
+		await this.disposeChildWorkspace({ ...spawnRecord, workspaceRetention: undefined })
 		try {
 			// The edge must be removed before its child: stores reject deletion
 			// of a session that still has a subsession reference.
@@ -1135,7 +1236,10 @@ export class AgentManager {
 		taskId: TaskId,
 		agent: { readonly id: string; readonly name: string },
 	): Promise<void> {
-		const lease = await log.claim({ holder: `namzu:agent-manager:${taskId}`, ttlMs: 30_000 })
+		const lease = await log.claim({
+			holder: `namzu:agent-manager:${taskId}`,
+			ttlMs: 30_000,
+		})
 		if (lease === null) {
 			throw new Error(`Child session ${spawnRecord.childSessionId} is already leased`)
 		}
@@ -1459,6 +1563,7 @@ export class AgentManager {
 		// parent but counted against `maxDelegationWidth`.
 		let subSession: Awaited<ReturnType<typeof store.createSubSession>> | undefined
 		let workspaceRef: WorkspaceRef | undefined
+		let workspaceDriver: WorkspaceBackendDriver | undefined
 		try {
 			// Flip to 'active' so the materializer's atomic write + status flip
 			// lands on terminal — §5.3: pending→active→idle.
@@ -1483,10 +1588,30 @@ export class AgentManager {
 			// provisioning: an unregistered backend leaves `workspaceRef:
 			// undefined` on the spawn record, not a hard error — the registry
 			// is the capability surface.
-			const backend = options.workspaceBackend ?? 'git-worktree'
-			if (this.deps.workspaceRegistry.has(backend)) {
+			const request = options.workspace
+			const backend =
+				request?.mode === 'shared'
+					? undefined
+					: request?.mode === 'isolated'
+						? request.backend
+						: (options.workspaceBackend ??
+							(this.config.workspaceDefault === 'shared' ? undefined : 'git-worktree'))
+			if (request?.mode === 'isolated' && !this.deps.workspaceRegistry.has(request.backend)) {
+				throw new Error(`Isolated workspace backend ${request.backend} is unavailable`)
+			}
+			if (backend && this.deps.workspaceRegistry.has(backend)) {
 				const driver = this.deps.workspaceRegistry.get(backend)
-				workspaceRef = await driver.create({ label: subSession.id })
+				workspaceDriver = driver
+				workspaceRef = await driver.create({
+					label: subSession.id,
+					...(request?.mode === 'isolated' && request.baseRef ? { baseRef: request.baseRef } : {}),
+				})
+				if (request?.mode === 'isolated')
+					await requireIsolatedWorktreePath(
+						workspaceRef,
+						options.input.workingDirectory,
+						request.subdirectory,
+					)
 
 				// Write the workspace onto the record that outlives this process.
 				//
@@ -1503,16 +1628,23 @@ export class AgentManager {
 				// exist before the record it is named after. Inside the try, so
 				// the compensating rollback below covers it like every other
 				// mutation here.
-				subSession = { ...subSession, workspaceId: workspaceRef.id }
+				subSession = {
+					...subSession,
+					workspaceId: workspaceRef.id,
+					...(request?.mode === 'isolated' && request.retention === 'retain'
+						? { workspaceRetention: 'retain' as const }
+						: {}),
+				}
 				await store.updateSubSession(subSession, context.tenantId)
 			}
 		} catch (err) {
-			if (workspaceRef && subSession) {
-				await this.disposeChildWorkspace({
-					workspaceRef,
-					subSessionId: subSession.id,
-				})
-			}
+			if (workspaceRef && workspaceDriver)
+				await workspaceDriver.dispose(workspaceRef).catch((disposeErr) =>
+					this.log.warn('Unstarted workspace dispose failed', {
+						'namzu.sub_session.id': subSession?.id,
+						'exception.message': toErrorMessage(disposeErr),
+					}),
+				)
 			// Compensating rollback order is mandated by the store's
 			// deny-by-default cascade policy (Convention #5): `deleteSession`
 			// throws when any subsession still references it, so the subsession
@@ -1540,6 +1672,9 @@ export class AgentManager {
 			ancestry: parentAncestry,
 			childDepth,
 			workspaceRef,
+			...(options.workspace?.mode === 'isolated' && options.workspace.retention === 'retain'
+				? { workspaceRetention: 'retain' as const }
+				: {}),
 		}
 	}
 
@@ -1769,7 +1904,10 @@ export class AgentManager {
 			status: 'failed',
 			usage: agentTask.context.budget.ownUsage,
 			budget: agentTask.context.budget.summary(),
-			cost: { ...ZERO_COST, unpricedTokens: agentTask.context.budget.ownTokens },
+			cost: {
+				...ZERO_COST,
+				unpricedTokens: agentTask.context.budget.ownTokens,
+			},
 			iterations: 0,
 			durationMs: Date.now() - agentTask.createdAt,
 			messages: [],
@@ -1835,8 +1973,9 @@ export class AgentManager {
 	 * removed is an operator's problem and silence is how it stays one.
 	 */
 	private async disposeChildWorkspace(
-		spawnRecord: Pick<ChildSpawnRecord, 'workspaceRef' | 'subSessionId'>,
+		spawnRecord: Pick<ChildSpawnRecord, 'workspaceRef' | 'workspaceRetention' | 'subSessionId'>,
 	): Promise<void> {
+		if (spawnRecord.workspaceRetention === 'retain') return
 		if (!spawnRecord.workspaceRef) return
 		const backend = spawnRecord.workspaceRef.meta.backend
 		if (!this.deps.workspaceRegistry.has(backend)) return

package/src/scheduler/local.ts

@@ -113,6 +113,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 			{
 				agentId: options.agentId,
 				beforeStart: options.beforeStart,
+				...(options.workspace ? { workspace: options.workspace } : {}),
 				...(options.planId ? { planId: options.planId } : {}),
 				...(options.planStepId ? { planStepId: options.planStepId } : {}),
 				// Display grouping travels with the spawn so the manager can put it
@@ -468,5 +469,6 @@ function toHandle(task: import('../types/agent/task.js').AgentTask): TaskHandle
 		result: task.result,
 		createdAt: task.createdAt,
 		completedAt: task.completedAt,
+		...(task.workspace ? { workspace: task.workspace } : {}),
 	}
 }