@namzu/sdk 48.3.0 → 49.0.0

package/src/connector/mcp/discovery.ts

@@ -55,10 +55,10 @@ export class MCPToolDiscovery {
 	private log: Logger
 	private options: MCPToolDiscoveryOptions
 	/**
-	 * Last admitted tool set per SERVER, for drift detection.
+	 * Last admitted tool set per owner identity, for drift detection.
 	 *
-	 * Keyed by server name rather than client id, and the difference is the
-	 * whole point. A client id is minted per connection, so on the path a
+	 * Plain discovery uses the server name; plugin discovery supplies its
+	 * qualified source id. A client id is minted per connection, so on the path a
 	 * real MCP server actually takes — a plugin enabling, connecting, and
 	 * being disabled again — every discovery was the first one that id had
 	 * ever seen, and drift could not fire however many times the server
@@ -119,9 +119,15 @@ export class MCPToolDiscovery {
 		return results
 	}
 
-	async discoverFrom(client: MCPClient): Promise<MCPDiscoveredTool[]> {
+	async discoverFrom(
+		client: MCPClient,
+		options?: { readonly isCurrent?: () => boolean },
+	): Promise<MCPDiscoveredTool[]> {
 		const state = client.getState()
 		const advertised = await client.listTools()
+		// A newer listing can finish before this one. Do not let the older
+		// generation replace the baseline or emit a drift event after that.
+		if (options?.isCurrent?.() === false) return []
 
 		// The boundary. Without it the REMOTE side decides what enters the
 		// agent's registry, which inverts least privilege: a server could
@@ -144,7 +150,7 @@ export class MCPToolDiscovery {
 			})
 		}
 
-		this.detectDrift(client.id, state.serverName, admitted)
+		this.detectDrift(state.serverName, client.id, state.serverName, admitted)
 
 		return admitted.map((tool) => ({
 			tool,
@@ -153,6 +159,16 @@ export class MCPToolDiscovery {
 		}))
 	}
 
+	/** Record the exact already-admitted snapshot another owner mounted. */
+	recordAdmittedTools(
+		identity: string,
+		clientId: string,
+		serverName: string,
+		admitted: readonly MCPToolDefinition[],
+	): void {
+		this.detectDrift(identity, clientId, serverName, [...admitted])
+	}
+
 	/**
 	 * The prompts a server publishes, through the same admission gate its
 	 * tools go through.
@@ -251,9 +267,14 @@ export class MCPToolDiscovery {
 		})
 	}
 
-	private detectDrift(clientId: string, serverName: string, admitted: MCPToolDefinition[]): void {
-		const previous = this.lastSeen.get(serverName)
-		this.lastSeen.set(serverName, admitted)
+	private detectDrift(
+		identity: string,
+		clientId: string,
+		serverName: string,
+		admitted: MCPToolDefinition[],
+	): void {
+		const previous = this.lastSeen.get(identity)
+		this.lastSeen.set(identity, admitted)
 		if (!previous) return
 
 		const drift = diffTools(previous, admitted)

package/src/connector/mcp/mcp-toolset.ts

@@ -5,7 +5,11 @@ import { NAMZU } from '../../constants/telemetry/index.js'
 import { ToolsetConflictError } from '../../toolsets/combine.js'
 import type { Toolset, ToolsetAvailability } from '../../toolsets/types.js'
 import { deferred } from '../../toolsets/wrappers.js'
-import type { MCPResource, MCPServerCapabilities } from '../../types/connector/index.js'
+import type {
+	MCPResource,
+	MCPServerCapabilities,
+	MCPToolDefinition,
+} from '../../types/connector/index.js'
 import type { ToolContext, ToolDefinition, ToolResult } from '../../types/tool/index.js'
 import type { ToolSource } from '../../types/toolset/index.js'
 import { toErrorMessage } from '../../utils/error.js'
@@ -103,6 +107,8 @@ export interface MCPToolsetOptions {
 	 * added and removed names apply at the next refresh boundary.
 	 */
 	readonly onDrift?: (event: { serverName: string; clientId: string; drift: MCPToolDrift }) => void
+	/** The exact admitted server listing processed at construction and each committed refresh. */
+	readonly onToolsAdmitted?: (tools: readonly MCPToolDefinition[]) => void
 	/** Current tool, prompt and resource names refused by this server's policy. */
 	readonly onRefused?: (event: {
 		serverName: string
@@ -320,14 +326,20 @@ export async function mcpToolset(
 	let promptDefs: ToolDefinition[] = []
 	let mainTools: ToolDefinition[] = []
 	let closed = false
+	let toolRefreshGeneration = 0
+	let admittedToolSnapshot: readonly MCPToolDefinition[] = []
 	const listeners = new Set<() => void>()
 
 	function rebuildMain(): void {
 		mainTools = [...toolDefs, ...promptDefs]
 	}
 
-	async function refreshTools(): Promise<void> {
-		const discovered = await discovery.discoverFrom(client)
+	async function refreshTools(): Promise<boolean> {
+		const generation = ++toolRefreshGeneration
+		const discovered = await discovery.discoverFrom(client, {
+			isCurrent: () => !closed && generation === toolRefreshGeneration,
+		})
+		if (closed || generation !== toolRefreshGeneration) return false
 		const previous = new Map(toolDefs.map((definition) => [definition.name, definition]))
 		toolDefs = discovered.map((d) => {
 			const name = mcpToolsetName(serverName, d.tool.name)
@@ -346,6 +358,8 @@ export async function mcpToolset(
 			if (!discovered.some((entry) => entry.tool.name === name)) heldToolNames.delete(name)
 		}
 		rebuildMain()
+		admittedToolSnapshot = discovered.map((entry) => entry.tool)
+		return true
 	}
 
 	async function refreshPrompts(): Promise<void> {
@@ -414,9 +428,12 @@ export async function mcpToolset(
 		}
 	}
 	assertUnique()
+	options.onToolsAdmitted?.(admittedToolSnapshot)
 
 	const notify = (): void => {
+		if (closed) return
 		assertUnique()
+		options.onToolsAdmitted?.(admittedToolSnapshot)
 		for (const listener of listeners) listener()
 	}
 	const onChange = (listener: () => void): (() => void) => {
@@ -449,7 +466,11 @@ export async function mcpToolset(
 		if (closed) return
 		if (method === 'notifications/tools/list_changed') {
 			if (!currentCapabilities()?.tools?.listChanged) return
-			void refreshTools().then(notify).catch(onRefreshFailure('tools'))
+			void refreshTools()
+				.then((updated) => {
+					if (updated) notify()
+				})
+				.catch(onRefreshFailure('tools'))
 		} else if (method === 'notifications/prompts/list_changed') {
 			if (!currentCapabilities()?.prompts?.listChanged) return
 			void refreshPrompts().then(notify).catch(onRefreshFailure('prompts'))

package/src/connector/mcp/reconnect.ts

@@ -83,6 +83,7 @@ export class MCPReconnectSupervisor {
 	private stopped = false
 	private inFlight = false
 	private timer?: ReturnType<typeof setTimeout>
+	private finishWait?: () => void
 
 	constructor(
 		private readonly client: MCPClient,
@@ -106,7 +107,7 @@ export class MCPReconnectSupervisor {
 
 	/** Begin watching. Idempotent. */
 	start(): void {
-		if (!this.policy().enabled || this.unsubscribe || this.stopped) return
+		if (this.stopped || this.unsubscribe || !this.policy().enabled) return
 		this.unsubscribe = this.client.onLifecycle((event) => {
 			if (event.type !== 'mcp_client_disconnected' && event.type !== 'mcp_client_error') return
 			void this.recover()
@@ -124,8 +125,9 @@ export class MCPReconnectSupervisor {
 		this.stopped = true
 		this.unsubscribe?.()
 		this.unsubscribe = undefined
-		if (this.timer) clearTimeout(this.timer)
-		this.timer = undefined
+		// Clearing the timer alone strands recover() inside an unresolved
+		// promise. Settle it so the stopped check can retire the loop.
+		this.finishWait?.()
 	}
 
 	private async recover(): Promise<void> {
@@ -154,9 +156,22 @@ export class MCPReconnectSupervisor {
 
 				try {
 					await this.client.connect()
+					// A host may stop the supervisor and dispose its live policy
+					// while connect() is still settling. Do not read that policy or
+					// publish a reconnect callback after teardown. A successful
+					// late connect also needs a second close: the host may have
+					// finished its own disconnect before this connect settled.
+					if (this.stopped) {
+						this.closeLateConnection()
+						return
+					}
 					await this.policy().onReconnected?.()
 					return
 				} catch {
+					if (this.stopped) {
+						this.closeLateConnection()
+						return
+					}
 					// Deliberately swallowed: a failed attempt is the normal
 					// case here and the client has already logged and emitted
 					// its own error. Re-raising would surface a routine retry
@@ -164,15 +179,30 @@ export class MCPReconnectSupervisor {
 					delay = Math.min(delay * 2, this.policy().maxDelayMs)
 				}
 			}
+			if (this.stopped) return
 			this.policy().onGaveUp?.(this.policy().maxAttempts)
 		} finally {
 			this.inFlight = false
 		}
 	}
 
+	private closeLateConnection(): void {
+		// A failed handshake can leave an opened transport, too. Stop is
+		// synchronous and the host's disable path has its own bounded close;
+		// keep this late cleanup best-effort without delaying recovery exit.
+		void this.client.disconnect().catch(() => {})
+	}
+
 	private wait(ms: number): Promise<void> {
 		return new Promise((resolve) => {
-			this.timer = setTimeout(resolve, ms)
+			const finish = () => {
+				if (this.timer) clearTimeout(this.timer)
+				this.timer = undefined
+				if (this.finishWait === finish) this.finishWait = undefined
+				resolve()
+			}
+			this.finishWait = finish
+			this.timer = setTimeout(finish, ms)
 		})
 	}
 }

package/src/plugin/lifecycle.ts

@@ -49,6 +49,7 @@ interface PluginContributionRecord {
 	mcpToolsets: Toolset[]
 	mcpUnsubscribers: Array<() => void>
 	mcpNamesBySource: Map<string, Set<string>>
+	configReleases: Array<() => void>
 	/** Namespaced skill names, so rollback and disable can take them back. */
 	skillNames: string[]
 }
@@ -62,6 +63,68 @@ interface PluginAdmission {
 	readonly inCode?: DefinedPlugin
 }
 
+const DEFAULT_PLUGIN_MCP_CONNECT_TIMEOUT_MS = 10_000
+const PLUGIN_MCP_CLOSE_TIMEOUT_MS = 5_000
+
+/** One deadline across handshake and all initial discovery requests. */
+async function beforePluginMcpDeadline<T>(
+	work: () => Promise<T>,
+	deadlineAt: number,
+	timeoutMs: number,
+	serverName: string,
+	onLate?: (value: T) => void,
+	onTimeout?: () => void,
+): Promise<T> {
+	const expired = (): Error =>
+		new Error(`Plugin MCP server "${serverName}" did not answer within ${timeoutMs}ms`)
+	const remaining = deadlineAt - Date.now()
+	if (remaining <= 0) throw expired()
+	let timer: ReturnType<typeof setTimeout> | undefined
+	let timedOut = false
+	try {
+		const pending = work()
+		// A timed-out discovery can still finish after rollback. In particular,
+		// mcpToolset() starts a reconnect supervisor just before it returns.
+		// Close that late result without publishing any of its tools.
+		void pending.then(
+			(value) => {
+				if (timedOut) onLate?.(value)
+			},
+			() => {},
+		)
+		return await Promise.race([
+			pending,
+			new Promise<never>((_, reject) => {
+				timer = setTimeout(() => {
+					timedOut = true
+					onTimeout?.()
+					reject(expired())
+				}, remaining)
+			}),
+		])
+	} finally {
+		if (timer) clearTimeout(timer)
+	}
+}
+
+/** Teardown is best-effort, but one stalled close must not block rollback or disable. */
+async function closePluginMcpWithin(work: () => Promise<void>, label: string): Promise<void> {
+	let timer: ReturnType<typeof setTimeout> | undefined
+	try {
+		await Promise.race([
+			work(),
+			new Promise<never>((_, reject) => {
+				timer = setTimeout(
+					() => reject(new Error(`${label} did not close within ${PLUGIN_MCP_CLOSE_TIMEOUT_MS}ms`)),
+					PLUGIN_MCP_CLOSE_TIMEOUT_MS,
+				)
+			}),
+		])
+	} finally {
+		if (timer) clearTimeout(timer)
+	}
+}
+
 /** Dynamic imports bypass ToolDefinition's TypeScript contract. */
 function assertPluginTool(
 	value: unknown,
@@ -100,6 +163,9 @@ function immutableManifest(manifest: PluginDefinition['manifest']): PluginDefini
 			command: server.command,
 			...(server.args ? { args: Object.freeze([...server.args]) } : {}),
 			...(server.env ? { env: Object.freeze({ ...server.env }) } : {}),
+			...(server.connectTimeoutMs !== undefined
+				? { connectTimeoutMs: server.connectTimeoutMs }
+				: {}),
 		}),
 	)
 	return Object.freeze({
@@ -199,6 +265,8 @@ export class PluginLifecycleManager {
 		}>
 	> = new Map()
 	private pluginContributions: Map<PluginId, PluginContributionRecord> = new Map()
+	/** Reserve each id before async admission so lifecycle calls cannot overlap. */
+	private readonly lifecycleTails = new Map<PluginId, Promise<void>>()
 	/** Immutable executable admissions owned by this manager, never by the mutable registry. */
 	private pluginAdmissions: Map<PluginId, PluginAdmission> = new Map()
 	private hookTimeoutMs: number
@@ -206,18 +274,16 @@ export class PluginLifecycleManager {
 	private readonly scopeRoots: Readonly<Record<PluginScope, string>>
 	private log: Logger
 	/**
-	 * The admission boundary for everything a plugin's MCP servers advertise.
+	 * The cross-enable drift history for each plugin-owned MCP source.
 	 *
-	 * One instance for the whole manager rather than one per plugin, and that
-	 * is the part that matters: the instance is what remembers each server's
-	 * previously admitted tool set, so a server that changes between one
-	 * plugin being disabled and the next being enabled is still noticed. A
-	 * per-plugin instance would forget on every teardown, which is precisely
-	 * the window a rug pull uses.
+	 * The toolset applies policy and performs the only listing. It passes the
+	 * admitted snapshot here after it commits, keyed by its full plugin source.
+	 * Keeping this recorder for the manager lifetime detects a server that
+	 * changes between disable and the next enable without conflating unrelated
+	 * plugins that use the same local server label.
 	 *
-	 * Its client list is deliberately left empty — `discoverFrom` takes the
-	 * client directly, so registering it here would be bookkeeping nothing
-	 * reads.
+	 * Its client list stays empty because this instance records snapshots;
+	 * it never makes a second request to the server.
 	 */
 	private mcpDiscovery: MCPToolDiscovery
 	private readonly mcpToolPolicies?: Readonly<Record<string, MCPToolPolicy>>
@@ -235,8 +301,20 @@ export class PluginLifecycleManager {
 		this.onMCPToolDrift = config.onMCPToolDrift
 		this.log = config.log.child({ [SCOPE_ATTRIBUTE]: 'plugin/lifecycle' })
 		this.mcpDiscovery = new MCPToolDiscovery([], {
-			...(config.mcpToolPolicies ? { policies: config.mcpToolPolicies } : {}),
-			...(config.onMCPToolDrift ? { onDrift: config.onMCPToolDrift } : {}),
+			...(config.onMCPToolDrift
+				? {
+						onDrift: (event) => {
+							try {
+								this.onMCPToolDrift?.(event)
+							} catch (error) {
+								this.log.warn('Plugin MCP drift listener failed', {
+									'namzu.plugin.mcp_server': event.serverName,
+									'exception.message': toErrorMessage(error),
+								})
+							}
+						},
+					}
+				: {}),
 			logger: this.log,
 		})
 	}
@@ -453,6 +531,21 @@ export class PluginLifecycleManager {
 		})
 	}
 
+	private serializeLifecycle<T>(pluginId: PluginId, work: () => Promise<T>): Promise<T> {
+		const previous = this.lifecycleTails.get(pluginId) ?? Promise.resolve()
+		const running = previous.then(work)
+		// A failed enable must not poison later disable, retry or uninstall.
+		const tail = running.then(
+			() => undefined,
+			() => undefined,
+		)
+		this.lifecycleTails.set(pluginId, tail)
+		void tail.then(() => {
+			if (this.lifecycleTails.get(pluginId) === tail) this.lifecycleTails.delete(pluginId)
+		})
+		return running
+	}
+
 	private async readLegacyAdmission(plugin: PluginDefinition): Promise<PluginAdmission> {
 		const rootDir = await resolveWithinReal(this.scopeRoots[plugin.scope], plugin.rootDir)
 		const manifest = immutableManifest(
@@ -482,7 +575,11 @@ export class PluginLifecycleManager {
 		})
 	}
 
-	async enable(pluginId: PluginId): Promise<void> {
+	enable(pluginId: PluginId): Promise<void> {
+		return this.serializeLifecycle(pluginId, () => this.enableOwned(pluginId))
+	}
+
+	private async enableOwned(pluginId: PluginId): Promise<void> {
 		const plugin = this.pluginRegistry.getOrThrow(pluginId)
 		let admission = this.pluginAdmissions.get(pluginId)
 
@@ -543,6 +640,7 @@ export class PluginLifecycleManager {
 			mcpToolsets: [],
 			mcpUnsubscribers: [],
 			mcpNamesBySource: new Map(),
+			configReleases: [],
 			skillNames: [],
 		}
 
@@ -703,30 +801,75 @@ export class PluginLifecycleManager {
 			},
 			logger: this.log,
 		})
-
-		await client.connect()
+		// A failed handshake still owns a transport (and possibly a child
+		// process). Put it under rollback ownership before the first await.
 		contributions.mcpClients.push(client)
+		const timeoutMs = config.connectTimeoutMs ?? DEFAULT_PLUGIN_MCP_CONNECT_TIMEOUT_MS
+		const deadlineAt = Date.now() + timeoutMs
+		const closeLateClient = () => {
+			void closePluginMcpWithin(
+				() => client.disconnect(),
+				`Plugin MCP server "${config.name}" after late connection`,
+			).catch((error) => {
+				this.log.warn('Late MCP disconnect failed', {
+					'namzu.mcp.client_id': client.id,
+					'exception.message': toErrorMessage(error),
+				})
+			})
+		}
+		await beforePluginMcpDeadline(
+			() => client.connect(),
+			deadlineAt,
+			timeoutMs,
+			config.name,
+			closeLateClient,
+		)
 
 		// The toolset owns reconnection and reads this policy on each attempt.
 		const policyScope = this.configRegistry?.register(
-			`mcp.${config.name}`,
+			`mcp.plugin.${pluginName}.${config.name}`,
 			MCPReconnectOptionsSchema,
 		)
-		// Preserve cross-disable drift detection. The live toolset below owns
-		// changes during this enablement; this manager-owned discovery remembers
-		// the server's earlier admission across clients and plugin lifetimes.
-		await this.mcpDiscovery.discoverFrom(client)
+		if (policyScope) contributions.configReleases.push(() => policyScope.dispose())
+		// The toolset performs the only listing. Record precisely the admitted
+		// snapshot it mounts, including later refreshes, under the plugin source.
 		const sourceId = `plugin:${pluginName}/mcp:${config.name}`
 		const policy = this.mcpToolPolicies?.[config.name] ?? this.mcpToolPolicies?.['*']
-		const entries = await mcpToolset(client, {
-			id: sourceId,
-			availability: 'deferred',
-			allow: policy?.allow,
-			deny: policy?.deny,
-			reconnect: policyScope ? () => policyScope.get() : {},
-			onDrift: this.onMCPToolDrift,
-			logger: this.log,
-		})
+		let acceptingSnapshot = true
+		const entries = await beforePluginMcpDeadline(
+			() =>
+				mcpToolset(client, {
+					id: sourceId,
+					availability: 'deferred',
+					allow: policy?.allow,
+					deny: policy?.deny,
+					reconnect: policyScope ? () => policyScope.get() : {},
+					onToolsAdmitted: (tools) => {
+						if (acceptingSnapshot) {
+							this.mcpDiscovery.recordAdmittedTools(sourceId, client.id, config.name, tools)
+						}
+					},
+					logger: this.log,
+				}),
+			deadlineAt,
+			timeoutMs,
+			config.name,
+			(lateEntries) => {
+				for (const entry of lateEntries) {
+					void closePluginMcpWithin(async () => {
+						await entry.close?.()
+					}, `Late MCP toolset ${entry.source.id}`).catch((error) => {
+						this.log.warn('Late MCP toolset close failed', {
+							'namzu.toolset.source_id': entry.source.id,
+							'exception.message': toErrorMessage(error),
+						})
+					})
+				}
+			},
+			() => {
+				acceptingSnapshot = false
+			},
+		)
 		contributions.mcpToolsets.push(...entries)
 		const wrapped = entries.map((entry) =>
 			prefixed(entry, `${pluginName}${PLUGIN_NAMESPACE_SEPARATOR}`),
@@ -779,25 +922,49 @@ export class PluginLifecycleManager {
 		contributions: PluginContributionRecord,
 		operation: 'rollback' | 'disable',
 	): Promise<void> {
-		for (const unsubscribe of contributions.mcpUnsubscribers) unsubscribe()
-		for (const entry of contributions.mcpToolsets) await entry.close?.()
-		for (const client of contributions.mcpClients) {
-			try {
-				await client.disconnect()
-			} catch (error) {
-				this.log.warn('MCP disconnect failed', {
-					'namzu.plugin.operation': operation,
-					'namzu.mcp.client_id': client.id,
-					'exception.message': toErrorMessage(error),
-				})
+		try {
+			for (const unsubscribe of contributions.mcpUnsubscribers) unsubscribe()
+			await Promise.all(
+				contributions.mcpToolsets.map(async (entry) => {
+					try {
+						await closePluginMcpWithin(async () => {
+							await entry.close?.()
+						}, `MCP toolset ${entry.source.id}`)
+					} catch (error) {
+						this.log.warn('MCP toolset close failed', {
+							'namzu.plugin.operation': operation,
+							'namzu.toolset.source_id': entry.source.id,
+							'exception.message': toErrorMessage(error),
+						})
+					}
+				}),
+			)
+			await Promise.all(
+				contributions.mcpClients.map(async (client) => {
+					try {
+						await closePluginMcpWithin(() => client.disconnect(), `MCP client ${client.id}`)
+					} catch (error) {
+						this.log.warn('MCP disconnect failed', {
+							'namzu.plugin.operation': operation,
+							'namzu.mcp.client_id': client.id,
+							'exception.message': toErrorMessage(error),
+						})
+					}
+				}),
+			)
+			for (const names of contributions.mcpNamesBySource.values()) {
+				for (const name of names) this.removeContributedTool(name)
 			}
+		} finally {
+			for (const release of contributions.configReleases) release()
 		}
-		for (const names of contributions.mcpNamesBySource.values()) {
-			for (const name of names) this.removeContributedTool(name)
-		}
 	}
 
-	async disable(pluginId: PluginId): Promise<void> {
+	disable(pluginId: PluginId): Promise<void> {
+		return this.serializeLifecycle(pluginId, () => this.disableOwned(pluginId))
+	}
+
+	private async disableOwned(pluginId: PluginId): Promise<void> {
 		const plugin = this.pluginRegistry.getOrThrow(pluginId)
 		const admission = this.pluginAdmissions.get(pluginId)
 		const contributions = this.pluginContributions.get(pluginId)
@@ -856,12 +1023,16 @@ export class PluginLifecycleManager {
 		})
 	}
 
-	async uninstall(pluginId: PluginId): Promise<void> {
+	uninstall(pluginId: PluginId): Promise<void> {
+		return this.serializeLifecycle(pluginId, () => this.uninstallOwned(pluginId))
+	}
+
+	private async uninstallOwned(pluginId: PluginId): Promise<void> {
 		const plugin = this.pluginRegistry.getOrThrow(pluginId)
 		const admission = this.pluginAdmissions.get(pluginId)
 
 		if (this.pluginContributions.has(pluginId)) {
-			await this.disable(pluginId)
+			await this.disableOwned(pluginId)
 		}
 
 		this.pluginRegistry.unregister(pluginId)

package/src/prompt/resident-learning.ts

@@ -103,7 +103,7 @@ export function createResidentStepContext(
 			...contributions,
 			Object.freeze({
 				id: 'namzu.resident-step.learning-catalogue',
-				placement: 'dynamic' as const,
+				placement: 'context' as const,
 				render: () =>
 					[
 						'## Available evaluated resident skills',
@@ -113,7 +113,7 @@ export function createResidentStepContext(
 			}),
 			Object.freeze({
 				id: 'namzu.resident-step.selected-learning',
-				placement: 'turn' as const,
+				placement: 'context' as const,
 				render: () => {
 					if (!selected.size) return null
 					try {

package/src/prompt/resident-step.ts

@@ -58,8 +58,8 @@ export interface ResidentStepPromptOptions {
  * contributions. Register them on the registry supplied to `query`.
  *
  * The static contribution carries stable work guidance and the host's output
- * contract. The dynamic contribution captures this invocation's state and
- * approved learning, outside the cached prefix. Both remain present on every
+ * contract. The context contribution captures this invocation's state and
+ * approved learning as request-only user-role context. Both remain present on every
  * iteration; build fresh contributions for the next admitted step.
  *
  * Project instructions and authorization remain on their existing host/runtime
@@ -128,14 +128,14 @@ export function createResidentStepContributions(
 		}),
 		Object.freeze({
 			id: 'namzu.resident-step.continuation',
-			placement: 'dynamic' as const,
+			placement: 'context' as const,
 			render: () => snapshot,
 		}),
 		...(boundNames.length
 			? [
 					Object.freeze({
 						id: 'namzu.resident-step.source-bound-learning',
-						placement: 'turn' as const,
+						placement: 'context' as const,
 						render: () => {
 							let sources: readonly ResidentLearningSource[] = []
 							try {

package/src/public-runtime.ts

@@ -506,6 +506,7 @@ export {
 	MEMORY_VERIFY_NOTICE,
 	MemoryContentRejectedError,
 	MemoryNameConflictError,
+	MemoryRevisionConflictError,
 	describeMemoryAge,
 	isMemoryName,
 	memoryIndexLine,
@@ -1143,6 +1144,7 @@ export {
 	MEMORY_TYPES,
 	assertMemoryStatus,
 	assertMemoryType,
+	hasConditionalMemoryWrites,
 	isMemoryType,
 } from './types/memory/index.js'
 export {