@namzu/sdk 32.0.0 → 33.0.0

package/src/connector/mcp/image-admission.ts

@@ -0,0 +1,272 @@
+import type { MCPContentBlock } from '../../types/connector/index.js'
+
+const MAX_ENCODED_BYTES = 24 * 1024 * 1024
+const MAX_DIMENSION = 16_384
+const MAX_PIXELS = 40_000_000
+
+type MCPImageBlock = Extract<MCPContentBlock, { type: 'image' }>
+type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif'
+
+const IMAGE_MEDIA_TYPES = new Set<ImageMediaType>([
+	'image/png',
+	'image/jpeg',
+	'image/webp',
+	'image/gif',
+])
+
+function isImageMediaType(value: string): value is ImageMediaType {
+	return IMAGE_MEDIA_TYPES.has(value as ImageMediaType)
+}
+
+function decodeCanonicalBase64(value: string): Uint8Array | null {
+	if (value.length === 0 || value.length > MAX_ENCODED_BYTES) return null
+	if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+		return null
+	}
+	const decoded = Buffer.from(value, 'base64')
+	return decoded.toString('base64') === value ? decoded : null
+}
+
+function dimensionsAreSafe(width: number, height: number): boolean {
+	return (
+		Number.isSafeInteger(width) &&
+		Number.isSafeInteger(height) &&
+		width > 0 &&
+		height > 0 &&
+		width <= MAX_DIMENSION &&
+		height <= MAX_DIMENSION &&
+		width * height <= MAX_PIXELS
+	)
+}
+
+const crcTable = (() => {
+	const table = new Uint32Array(256)
+	for (let n = 0; n < 256; n += 1) {
+		let value = n
+		for (let bit = 0; bit < 8; bit += 1) {
+			value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1
+		}
+		table[n] = value >>> 0
+	}
+	return table
+})()
+
+function crc32(bytes: Uint8Array, start: number, end: number): number {
+	let crc = 0xffffffff
+	for (let offset = start; offset < end; offset += 1) {
+		crc = (crcTable[(crc ^ (bytes[offset] ?? 0)) & 0xff] ?? 0) ^ (crc >>> 8)
+	}
+	return (crc ^ 0xffffffff) >>> 0
+}
+
+function isPng(bytes: Uint8Array): boolean {
+	const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+	if (bytes.length < 45 || !buffer.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) {
+		return false
+	}
+	let offset = 8
+	let sawHeader = false
+	let sawData = false
+	while (offset + 12 <= bytes.length) {
+		const length = buffer.readUInt32BE(offset)
+		const typeStart = offset + 4
+		const dataStart = typeStart + 4
+		const dataEnd = dataStart + length
+		const chunkEnd = dataEnd + 4
+		if (dataEnd < dataStart || chunkEnd > bytes.length) return false
+		const type = buffer.toString('ascii', typeStart, dataStart)
+		if (buffer.readUInt32BE(dataEnd) !== crc32(bytes, typeStart, dataEnd)) return false
+		if (!sawHeader) {
+			if (type !== 'IHDR' || length !== 13) return false
+			const width = buffer.readUInt32BE(dataStart)
+			const height = buffer.readUInt32BE(dataStart + 4)
+			if (!dimensionsAreSafe(width, height)) return false
+			sawHeader = true
+		} else if (type === 'IHDR') return false
+		if (type === 'IDAT') sawData = true
+		if (type === 'IEND') return length === 0 && sawHeader && sawData && chunkEnd === bytes.length
+		offset = chunkEnd
+	}
+	return false
+}
+
+const JPEG_SOF_MARKERS = new Set([
+	0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+])
+
+function isJpeg(bytes: Uint8Array): boolean {
+	const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+	if (bytes.length < 11 || bytes[0] !== 0xff || bytes[1] !== 0xd8) return false
+	let offset = 2
+	let sawFrame = false
+	let sawScan = false
+	let inScan = false
+	while (offset < bytes.length) {
+		if (inScan && bytes[offset] !== 0xff) {
+			offset += 1
+			continue
+		}
+		if (bytes[offset] !== 0xff) return false
+		while (offset < bytes.length && bytes[offset] === 0xff) offset += 1
+		if (offset >= bytes.length) return false
+		const marker = bytes[offset] ?? 0
+		offset += 1
+		if (inScan && (marker === 0x00 || (marker >= 0xd0 && marker <= 0xd7))) continue
+		inScan = false
+		if (marker === 0xd9) return sawFrame && sawScan && offset === bytes.length
+		if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) continue
+		if (offset + 2 > bytes.length) return false
+		const length = buffer.readUInt16BE(offset)
+		if (length < 2 || offset + length > bytes.length) return false
+		if (JPEG_SOF_MARKERS.has(marker)) {
+			if (length < 8) return false
+			const height = buffer.readUInt16BE(offset + 3)
+			const width = buffer.readUInt16BE(offset + 5)
+			if (!dimensionsAreSafe(width, height)) return false
+			sawFrame = true
+		}
+		offset += length
+		if (marker === 0xda) {
+			sawScan = true
+			inScan = true
+		}
+	}
+	return false
+}
+
+function skipGifSubBlocks(bytes: Uint8Array, start: number): number | null {
+	let offset = start
+	while (offset < bytes.length) {
+		const length = bytes[offset] ?? 0
+		offset += 1
+		if (length === 0) return offset
+		if (offset + length > bytes.length) return null
+		offset += length
+	}
+	return null
+}
+
+function isGif(bytes: Uint8Array): boolean {
+	const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+	if (bytes.length < 14) return false
+	const signature = buffer.toString('ascii', 0, 6)
+	if (signature !== 'GIF87a' && signature !== 'GIF89a') return false
+	if (!dimensionsAreSafe(buffer.readUInt16LE(6), buffer.readUInt16LE(8))) return false
+	let offset = 13
+	const packed = bytes[10] ?? 0
+	if ((packed & 0x80) !== 0) offset += 3 * 2 ** ((packed & 0x07) + 1)
+	if (offset > bytes.length) return false
+	let sawImage = false
+	while (offset < bytes.length) {
+		const marker = bytes[offset] ?? 0
+		offset += 1
+		if (marker === 0x3b) return sawImage && offset === bytes.length
+		if (marker === 0x21) {
+			if (offset >= bytes.length) return false
+			offset += 1
+			const next = skipGifSubBlocks(bytes, offset)
+			if (next === null) return false
+			offset = next
+			continue
+		}
+		if (marker !== 0x2c || offset + 9 > bytes.length) return false
+		const width = buffer.readUInt16LE(offset + 4)
+		const height = buffer.readUInt16LE(offset + 6)
+		if (!dimensionsAreSafe(width, height)) return false
+		const imagePacked = bytes[offset + 8] ?? 0
+		offset += 9
+		if ((imagePacked & 0x80) !== 0) offset += 3 * 2 ** ((imagePacked & 0x07) + 1)
+		if (offset >= bytes.length) return false
+		offset += 1
+		const next = skipGifSubBlocks(bytes, offset)
+		if (next === null) return false
+		offset = next
+		sawImage = true
+	}
+	return false
+}
+
+function readUInt24LE(bytes: Uint8Array, offset: number): number {
+	return (bytes[offset] ?? 0) | ((bytes[offset + 1] ?? 0) << 8) | ((bytes[offset + 2] ?? 0) << 16)
+}
+
+function webpDimensions(type: string, data: Uint8Array): readonly [number, number] | null {
+	const buffer = Buffer.from(data.buffer, data.byteOffset, data.byteLength)
+	if (type === 'VP8X') {
+		if (data.length < 10) return null
+		return [readUInt24LE(data, 4) + 1, readUInt24LE(data, 7) + 1]
+	}
+	if (type === 'VP8L') {
+		if (data.length < 5 || data[0] !== 0x2f) return null
+		const bits = buffer.readUInt32LE(1)
+		return [(bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1]
+	}
+	if (type === 'VP8 ') {
+		if (data.length < 10 || data[3] !== 0x9d || data[4] !== 0x01 || data[5] !== 0x2a) {
+			return null
+		}
+		return [buffer.readUInt16LE(6) & 0x3fff, buffer.readUInt16LE(8) & 0x3fff]
+	}
+	return null
+}
+
+function isWebp(bytes: Uint8Array): boolean {
+	const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+	if (
+		bytes.length < 20 ||
+		buffer.toString('ascii', 0, 4) !== 'RIFF' ||
+		buffer.readUInt32LE(4) + 8 !== bytes.length ||
+		buffer.toString('ascii', 8, 12) !== 'WEBP'
+	) {
+		return false
+	}
+	let offset = 12
+	let dimensions: readonly [number, number] | null = null
+	let sawImagePayload = false
+	while (offset + 8 <= bytes.length) {
+		const type = buffer.toString('ascii', offset, offset + 4)
+		const length = buffer.readUInt32LE(offset + 4)
+		const dataStart = offset + 8
+		const dataEnd = dataStart + length
+		if (dataEnd < dataStart || dataEnd > bytes.length) return false
+		const current = webpDimensions(type, bytes.subarray(dataStart, dataEnd))
+		if (current && dimensions === null) dimensions = current
+		if (type === 'VP8 ' || type === 'VP8L') sawImagePayload = current !== null
+		offset = dataEnd + (length & 1)
+	}
+	return (
+		offset === bytes.length &&
+		dimensions !== null &&
+		sawImagePayload &&
+		dimensionsAreSafe(dimensions[0], dimensions[1])
+	)
+}
+
+function imageIsAdmitted(block: MCPImageBlock): boolean {
+	if (!isImageMediaType(block.mimeType)) return false
+	const bytes = decodeCanonicalBase64(block.data)
+	if (!bytes) return false
+	switch (block.mimeType) {
+		case 'image/png':
+			return isPng(bytes)
+		case 'image/jpeg':
+			return isJpeg(bytes)
+		case 'image/gif':
+			return isGif(bytes)
+		case 'image/webp':
+			return isWebp(bytes)
+	}
+}
+
+/**
+ * Admit an MCP image batch atomically before any member becomes model input.
+ *
+ * A remote server controls the declared MIME and bytes. Canonical base64 is
+ * only an encoding property; the decoded value must also be a complete,
+ * bounded raster container whose format agrees with that declaration. One bad
+ * member withholds the complete batch so a model is never shown a partial
+ * result while the host retains every raw block for inspection.
+ */
+export function admitMcpImageBatch(images: readonly MCPImageBlock[]): boolean {
+	return images.length === 0 || images.every(imageIsAdmitted)
+}

package/src/connector/mcp/stdio.ts

@@ -95,6 +95,10 @@ export class StdioTransport implements MCPTransport {
 	private closeHandlers: Array<() => void> = []
 	private errorHandlers: Array<(error: Error) => void> = []
 	private connected = false
+	/** The response channel ended for this process generation. */
+	private retired = false
+	/** Prevents a late event from an old child retiring its replacement. */
+	private generation = 0
 	/** True between kill and the process's own `close` event. */
 	private exitPending = false
 	private buffer = ''
@@ -109,38 +113,47 @@ export class StdioTransport implements MCPTransport {
 
 	async connect(): Promise<void> {
 		if (this.connected) return
+		// A protocol channel can end while its process stays alive. Reconnect
+		// must reap that old owner before publishing a new generation; otherwise
+		// both children remain live and teardown owns only the newest one.
+		if (this.process) await this.close()
+		const generation = ++this.generation
+		this.retired = false
+		this.buffer = ''
 
-		this.process = spawn(this.config.command, this.config.args ?? [], {
+		const child = spawn(this.config.command, this.config.args ?? [], {
 			env: buildChildEnv(this.config),
 			cwd: this.config.cwd,
 			stdio: ['pipe', 'pipe', 'pipe'],
 		})
+		this.process = child
 
-		this.process.stdout?.on('data', (chunk: Buffer) => {
+		child.stdout?.on('data', (chunk: Buffer) => {
+			if (generation !== this.generation || this.retired) return
 			this.buffer += chunk.toString('utf-8')
 			this.processBuffer()
 		})
+		child.stdout?.once('end', () => this.retire(generation, 'close'))
+		child.stdout?.once('close', () => this.retire(generation, 'close'))
+		child.stdout?.once('error', (err) => this.retire(generation, 'error', err))
 
-		this.process.stderr?.on('data', (chunk: Buffer) => {
+		child.stderr?.on('data', (chunk: Buffer) => {
 			this.log.warn('MCP server stderr', {
 				'namzu.mcp.stderr': chunk.toString('utf-8').trim(),
 			})
 		})
 
-		this.process.on('close', (code) => {
-			this.connected = false
-			this.log.info('MCP server process exited', { 'namzu.mcp.exit_code': code })
-			for (const handler of this.closeHandlers) handler()
-			// After the notification, not before it: this event is what tells
-			// `MCPClient` the session ended.
+		child.stdin?.once('close', () => this.retire(generation, 'close'))
+		child.stdin?.once('error', (err) => this.retire(generation, 'error', err))
+
+		child.on('close', (code) => {
+			if (this.process === child) this.process = null
 			this.exitPending = false
-			this.clearHandlers()
+			this.log.info('MCP server process exited', { 'namzu.mcp.exit_code': code })
+			this.retire(generation, 'close')
 		})
 
-		this.process.on('error', (err) => {
-			this.connected = false
-			for (const handler of this.errorHandlers) handler(err)
-		})
+		child.on('error', (err) => this.retire(generation, 'error', err))
 
 		this.connected = true
 		this.log.info('StdioTransport connected', {
@@ -175,7 +188,10 @@ export class StdioTransport implements MCPTransport {
 		// so both settle this, and two timers make a hang impossible: the
 		// first escalates to SIGKILL for a child ignoring SIGTERM, the second
 		// gives up waiting. Neither holds the event loop open.
-		if (child.pid === undefined) return
+		if (child.pid === undefined) {
+			this.exitPending = false
+			return
+		}
 		await new Promise<void>((resolve) => {
 			let settled = false
 			const finish = (): void => {
@@ -185,18 +201,20 @@ export class StdioTransport implements MCPTransport {
 				clearTimeout(giveUp)
 				resolve()
 			}
-			child.once('exit', finish)
+			child.once('close', finish)
 			child.once('error', finish)
-			child.kill('SIGTERM')
+			if (child.exitCode === null && child.signalCode === null) {
+				child.kill('SIGTERM')
+			}
 			const escalate = setTimeout(() => child.kill('SIGKILL'), TERMINATE_GRACE_MS)
 			const giveUp = setTimeout(finish, TERMINATE_GRACE_MS * 2)
 			escalate.unref?.()
 			giveUp.unref?.()
 		})
-		// The handlers deliberately survive this call. `process.on('close')`
-		// fires them when the process actually exits, and dropping them here
-		// would leave `MCPClient` believing it is still connected — so its next
-		// `connect()` would be refused with "already connected".
+		this.exitPending = false
+		// The active generation's terminal stream/process event owns handler
+		// retirement. A reconnect can register its handlers before `connect()`
+		// reaps an already-retired child, so `close()` must not clear them here.
 	}
 
 	/**
@@ -214,6 +232,30 @@ export class StdioTransport implements MCPTransport {
 		this.errorHandlers = []
 	}
 
+	/**
+	 * Publish one terminal result for the current response channel.
+	 *
+	 * A child may close stdout and keep running. That is just as terminal for
+	 * JSON-RPC as process exit: no pending or future request can receive a
+	 * response. Keeping the child handle is intentional; `close()` still owns
+	 * and reaps that process after the protocol session has been retired.
+	 */
+	private retire(generation: number, kind: 'close' | 'error', error?: Error): void {
+		if (generation !== this.generation || this.retired) return
+		this.retired = true
+		this.connected = false
+		this.buffer = ''
+		const closeHandlers = this.closeHandlers
+		const errorHandlers = this.errorHandlers
+		this.clearHandlers()
+		if (kind === 'error') {
+			const reason = error ?? new Error('MCP stdio transport failed')
+			for (const handler of errorHandlers) handler(reason)
+			return
+		}
+		for (const handler of closeHandlers) handler()
+	}
+
 	async send(message: MCPJsonRpcMessage, options?: MCPTransportSendOptions): Promise<void> {
 		options?.signal?.throwIfAborted()
 		if (!this.process?.stdin?.writable) {

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

@@ -7,6 +7,7 @@ import type {
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { ConnectorHttpOperation, validateConnectorTimeoutMs } from '../http-operation.js'
+import { refuseMcpHttpRedirect } from './http-redirect.js'
 
 const DEFAULT_TIMEOUT_MS = 30_000
 
@@ -83,10 +84,12 @@ export class StreamableHttpTransport implements MCPTransport {
 					method: 'POST',
 					headers: this.buildHeaders(),
 					body: JSON.stringify(message),
+					redirect: 'manual',
 					signal: operation.signal,
 				}),
 			)
 
+			refuseMcpHttpRedirect(response, message.method)
 			if (!response.ok) {
 				throw new Error(`StreamableHttpTransport: HTTP ${response.status}: ${response.statusText}`)
 			}

package/src/constants/tools/index.ts

@@ -1,4 +1,4 @@
-// Patterns the verification gate's `deny_dangerous_patterns` rule
+// Patterns the authorization gate's `deny_dangerous_patterns` rule
 // matches against the JSON-serialised tool input. The list is
 // intentionally short and high-signal: the goal is to catch the
 // canonical "I will brick the host" mistakes (filesystem wipes,

package/src/execution/base.ts

@@ -12,6 +12,21 @@ export interface BaseExecutionEvent {
 
 export type ExecutionEventListener = (event: BaseExecutionEvent) => void
 
+type ExecutionLifecycleState =
+	| 'idle'
+	| 'initializing'
+	| 'ready'
+	| 'tearing-down'
+	| 'teardown-failed'
+	| 'torn-down'
+
+class InitializationSupersededError extends Error {
+	constructor(contextId: string) {
+		super(`Execution context "${contextId}" initialization was superseded by teardown`)
+		this.name = 'InitializationSupersededError'
+	}
+}
+
 export abstract class BaseExecutionContext implements ExecutionContextLifecycle {
 	abstract readonly id: string
 	abstract readonly environment: ExecutionEnvironment
@@ -19,6 +34,9 @@ export abstract class BaseExecutionContext implements ExecutionContextLifecycle
 	protected log: Logger
 	protected ready = false
 	private listeners: ExecutionEventListener[] = []
+	private lifecycleState: ExecutionLifecycleState = 'idle'
+	private initializationOperation: Promise<void> | undefined
+	private teardownOperation: Promise<void> | undefined
 
 	constructor(log?: Logger) {
 		this.log = resolveLogger(log).child({
@@ -27,17 +45,62 @@ export abstract class BaseExecutionContext implements ExecutionContextLifecycle
 		})
 	}
 
-	async initialize(): Promise<void> {
+	initialize(): Promise<void> {
+		if (this.lifecycleState === 'ready') return Promise.resolve()
+		if (this.lifecycleState === 'initializing' && this.initializationOperation) {
+			return this.initializationOperation
+		}
+		if (this.lifecycleState === 'tearing-down') {
+			return Promise.reject(
+				new Error(`Execution context "${this.id}" cannot initialize while teardown is in progress`),
+			)
+		}
+		if (this.lifecycleState === 'teardown-failed') {
+			return Promise.reject(
+				new Error(
+					`Execution context "${this.id}" cannot initialize until its failed teardown is retried`,
+				),
+			)
+		}
+
+		this.lifecycleState = 'initializing'
+		const operation = this.performInitialize()
+		this.initializationOperation = operation
+		void operation.then(
+			() => this.releaseInitialization(operation),
+			() => this.releaseInitialization(operation),
+		)
+		return operation
+	}
+
+	private async performInitialize(): Promise<void> {
 		try {
+			this.onInitializationStarted()
 			await this.doInitialize()
+			if (this.lifecycleState !== 'initializing') {
+				throw new InitializationSupersededError(this.id)
+			}
+			this.onInitializationCommitted()
+			if (this.lifecycleState !== 'initializing') {
+				throw new InitializationSupersededError(this.id)
+			}
 			this.ready = true
-			this.emit({ type: 'context_initialized', contextId: this.id, environment: this.environment })
-			this.emit({ type: 'context_ready', contextId: this.id })
+			this.lifecycleState = 'ready'
 			this.log.info('Execution context initialized', {
 				'namzu.execution.context_id': this.id,
 				'namzu.execution.environment': this.environment,
 			})
+			this.emit({
+				type: 'context_initialized',
+				contextId: this.id,
+				environment: this.environment,
+			})
+			if (this.lifecycleState !== 'ready') return
+			this.emit({ type: 'context_ready', contextId: this.id })
 		} catch (err) {
+			if (err instanceof InitializationSupersededError) throw err
+			this.ready = false
+			if (this.lifecycleState === 'initializing') this.lifecycleState = 'idle'
 			const message = toErrorMessage(err)
 			this.emit({ type: 'context_error', contextId: this.id, error: message })
 			this.log.error('Execution context initialization failed', {
@@ -48,20 +111,65 @@ export abstract class BaseExecutionContext implements ExecutionContextLifecycle
 		}
 	}
 
+	private releaseInitialization(operation: Promise<void>): void {
+		if (this.initializationOperation === operation) this.initializationOperation = undefined
+	}
+
 	isReady(): boolean {
 		return this.ready
 	}
 
-	async teardown(): Promise<void> {
+	teardown(): Promise<void> {
+		if (this.lifecycleState === 'tearing-down' && this.teardownOperation) {
+			return this.teardownOperation
+		}
+		if (this.lifecycleState === 'torn-down') return Promise.resolve()
+
+		this.ready = false
+		this.lifecycleState = 'tearing-down'
+		const operation = this.performTeardown(this.initializationOperation)
+		this.teardownOperation = operation
+		void operation.then(
+			() => this.releaseTeardown(operation),
+			() => this.releaseTeardown(operation),
+		)
+		return operation
+	}
+
+	private async performTeardown(pendingInitialization: Promise<void> | undefined): Promise<void> {
 		try {
+			// Runs before the first await. Subclasses close public admission here so
+			// work cannot slip behind an initialization this teardown must await.
+			this.onTeardownRequested()
+			if (pendingInitialization) {
+				try {
+					await pendingInitialization
+				} catch {
+					// Initialization errors are reported by their owner. Cleanup still runs.
+				}
+			}
 			await this.doTeardown()
-		} finally {
-			this.ready = false
+			this.lifecycleState = 'torn-down'
+			this.log.info('Execution context torn down', {
+				'namzu.execution.context_id': this.id,
+			})
 			this.emit({ type: 'context_teardown', contextId: this.id })
-			this.log.info('Execution context torn down', { 'namzu.execution.context_id': this.id })
+		} catch (err) {
+			this.lifecycleState = 'teardown-failed'
+			const message = toErrorMessage(err)
+			this.emit({ type: 'context_error', contextId: this.id, error: message })
+			this.log.error('Execution context teardown failed', {
+				'namzu.execution.context_id': this.id,
+				'exception.message': message,
+			})
+			throw err
 		}
 	}
 
+	private releaseTeardown(operation: Promise<void>): void {
+		if (this.teardownOperation === operation) this.teardownOperation = undefined
+	}
+
 	on(listener: ExecutionEventListener): void {
 		this.listeners.push(listener)
 	}
@@ -85,4 +193,13 @@ export abstract class BaseExecutionContext implements ExecutionContextLifecycle
 
 	protected abstract doInitialize(): Promise<void>
 	protected abstract doTeardown(): Promise<void>
+
+	/** Fence subclass-owned public admission before initialization begins. */
+	protected onInitializationStarted(): void {}
+
+	/** Reopen admission only after Base has proved initialization was not superseded. */
+	protected onInitializationCommitted(): void {}
+
+	/** Fence subclass-owned public admission synchronously when teardown is requested. */
+	protected onTeardownRequested(): void {}
 }

package/src/execution/errors.ts

@@ -0,0 +1,24 @@
+export class CommandCancellationUnsupportedError extends Error {
+	readonly code = 'command_cancellation_unsupported' as const
+
+	constructor(readonly contextId: string) {
+		super(
+			`Remote execution context "${contextId}" cannot accept command cancellation because its generic executor has no reservation and terminal-acknowledgement protocol. No remote command was started. Use the Sandbox.exec() contract for cancellable remote command execution.`,
+		)
+		this.name = 'CommandCancellationUnsupportedError'
+	}
+}
+
+export class RemoteExecutionBusyError extends Error {
+	readonly code = 'remote_execution_busy' as const
+
+	constructor(
+		readonly contextId: string,
+		readonly activeCommandCount: number,
+	) {
+		super(
+			`Remote execution context "${contextId}" still owns ${activeCommandCount} active command${activeCommandCount === 1 ? '' : 's'}. Disconnect or teardown was refused; wait for the command${activeCommandCount === 1 ? '' : 's'} to settle, then retry.`,
+		)
+		this.name = 'RemoteExecutionBusyError'
+	}
+}

package/src/execution/factory.ts

@@ -15,6 +15,7 @@ export class ExecutionContextFactory {
 					envVars: config.envVars,
 					capabilities: config.capabilities,
 					shell: config.shell,
+					maxOutputBytes: config.maxOutputBytes,
 				})
 
 			case 'remote':