@gestaltrun/dsh-workspace-bundle 0.0.0-stage → 0.1.1

package/lib/index.js

@@ -0,0 +1,2868 @@
+import { basename, dirname, isAbsolute, join, normalize, posix, sep } from "node:path";
+import { constants, existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { z } from "zod";
+import { createHash, randomUUID } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+import semver from "semver";
+import { brandString } from "@deepseek-ai/dsh-brand";
+import Schema from "@deepseek-ai/schemastery";
+import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
+import { Service } from "@deepseek-ai/cordis";
+import { access, chmod, copyFile, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+//#region lib/types/errors.js
+/** Misconfiguration of the workspace-bundle row; plugin load fails with it. */
+var WorkspaceBundlesConfigError = class extends Error {
+	code;
+	name = "WorkspaceBundlesConfigError";
+	/**
+	* @param code - stable failure code.
+	* @param message - diagnostic naming the offending field.
+	*/
+	constructor(code, message) {
+		super(`workspace-bundle: ${message} (${code})`);
+		this.code = code;
+	}
+};
+/** Template, path, digest, or upgrade failure; the Host reports it and does not fall back. */
+var WorkspaceBundleError = class extends Error {
+	code;
+	name = "WorkspaceBundleError";
+	/**
+	* @param code - stable failure code.
+	* @param message - diagnostic.
+	*/
+	constructor(code, message) {
+		super(`workspace-bundle: ${message} (${code})`);
+		this.code = code;
+	}
+};
+//#endregion
+//#region lib/types/paths.js
+/** Controlled encoding of branded Workspace bundle identities into Home path segments. */
+const SEGMENT = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
+/**
+* Encode one branded identity as a single path segment.
+* @param value - bundle id or workspace key.
+* @param field - diagnostic name.
+* @returns the same spelling when it is a controlled segment.
+* @throws {WorkspaceBundleError} When the value could traverse or collide with `.` / `..`.
+*/
+function encodeBundleSegment(value, field) {
+	if (!SEGMENT.test(value) || value === "." || value === ".." || value.includes(sep) || value.includes(posix.sep) || value.includes("\0")) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_IDENTITY_INVALID", `${field} ${JSON.stringify(value)} is not a controlled path segment`);
+	return value;
+}
+/**
+* Join a parent with `{bundleId}/{workspaceKey}`.
+* @param parent - absolute parent already validated by Config.
+* @param identity - branded pair.
+* @returns the joined path using the host separator.
+*/
+function bundledDirectory(parent, identity) {
+	return join(parent, encodeBundleSegment(identity.bundleId, "bundleId"), encodeBundleSegment(identity.workspaceKey, "workspaceKey"));
+}
+/**
+* Reject a template-relative path that leaves the root, is absolute, or uses a reserved segment.
+* @param relativePath - POSIX relative path from the manifest.
+* @returns the same spelling.
+* @throws {WorkspaceBundleError} On traversal, absolute paths, empty segments, or backslashes.
+*/
+function assertTemplateRelativePath(relativePath) {
+	if (relativePath === "" || relativePath.startsWith("/") || relativePath.includes("\\") || relativePath.includes("\0")) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_PATH_TRAVERSAL", `template path ${JSON.stringify(relativePath)} is not a relative POSIX path`);
+	if (relativePath.split("/").some((part) => part === "" || part === "." || part === "..")) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_PATH_TRAVERSAL", `template path ${JSON.stringify(relativePath)} contains a reserved segment`);
+	return relativePath;
+}
+/** @param bundleId - branded bundle identity. @param workspaceKey - branded workspace key. */
+function identityOf(bundleId, workspaceKey) {
+	encodeBundleSegment(bundleId, "bundleId");
+	encodeBundleSegment(workspaceKey, "workspaceKey");
+	return {
+		bundleId,
+		workspaceKey
+	};
+}
+//#endregion
+//#region lib/types/agent-config-format.js
+/** 内置 Workspace Agent 配置的文件校验；目录和压缩字节的大小均由部署配置限制。 */
+/** 本 Host 实现的 Agent 配置接口版本；白名单与写操作授权由 Host 保持。 */
+const HOST_AGENT_CONFIG_API_VERSION = "2.0.0";
+/** Agent 配置 SHA-256 的十六进制编码。 */
+const AgentConfigSha256 = z.string().regex(/^[a-f0-9]{64}$/u);
+/** 内置 Workspace 种类；不含路径分隔符。 */
+const WorkspaceKind$1 = z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u).max(80);
+/** @param value - 完整 Agent 配置版本。 @returns 是否为保留构建元数据的规范 SemVer；优先级由 semver 按规范比较。 */
+function isAgentConfigVersion(value) {
+	const parsed = semver.parse(value);
+	return parsed !== null && `${parsed.version}${parsed.build.length === 0 ? "" : `+${parsed.build.join(".")}`}` === value;
+}
+/** server 分配中可公开的包信息，未携带商家凭据。 */
+const AgentConfigDescriptorSchema = z.strictObject({
+	workspaceKind: WorkspaceKind$1,
+	version: z.string().refine(isAgentConfigVersion),
+	sha256: AgentConfigSha256,
+	sizeBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+	downloadUrl: z.url(),
+	hostAgentConfigApiRange: z.string().refine((value) => semver.validRange(value) !== null),
+	runtimeApiRange: z.string().refine((value) => semver.validRange(value) !== null).optional(),
+	releaseNotes: z.string().min(1).max(2e4)
+});
+/** 包内逐文件摘要与字节数，文件路径相对版本目录。 */
+const AgentConfigManifestSchema = z.strictObject({
+	formatVersion: z.literal(1),
+	workspaceKind: WorkspaceKind$1,
+	version: z.string().refine(isAgentConfigVersion),
+	hostAgentConfigApiRange: z.string().refine((value) => semver.validRange(value) !== null),
+	files: z.array(z.strictObject({
+		path: z.string(),
+		sizeBytes: z.number().int().nonnegative(),
+		sha256: AgentConfigSha256
+	})).min(1).max(1e4)
+});
+/** 确定性 gzip JSON Agent 配置：清单和按同序排列的 base64 文件。 */
+const AgentConfigDocumentSchema = z.strictObject({
+	manifest: AgentConfigManifestSchema,
+	files: z.array(z.strictObject({
+		path: z.string(),
+		base64: z.string()
+	})).min(1).max(1e4)
+});
+/** 有界内容更新的结构化失败。 */
+var AgentConfigError = class extends Error {
+	code;
+	/** @param code - 失败类别。 @param disposition - candidate 保留当前版本；blocked 表示已提交内容不可执行。 */
+	constructor(code, disposition = "candidate") {
+		super(disposition === "blocked" ? "已提交的 Agent 配置未通过执行校验，自动客服已阻断；保留工作区与缓存，请重新分配兼容且完整的配置版本后再继续。" : {
+			AGENT_CONFIG_QUERY_FAILED: "Agent 配置版本查询失败，保留当前版本；请检查服务器连接。",
+			AGENT_CONFIG_INVALID: "Agent 配置文件或清单无效，保留当前版本；请重新打包发布。",
+			AGENT_CONFIG_INCOMPATIBLE: "Agent 配置不兼容当前 Host，保留当前版本；请分配兼容版本或升级客户端。",
+			AGENT_CONFIG_DIGEST_MISMATCH: "Agent 配置摘要不匹配，保留当前版本；请核对发布登记。",
+			AGENT_CONFIG_DOWNLOAD_FAILED: "Agent 配置下载失败，保留当前版本；请检查文件服务连接。",
+			AGENT_CONFIG_APPLY_FAILED: "Agent 配置应用失败；请检查工作区恢复状态后再继续。",
+			AGENT_CONFIG_SCOPE_CHANGED: "Agent 配置版本来源已变更，已丢弃旧候选；保留当前版本并重新查询。"
+		}[code]);
+		this.code = code;
+		this.name = "AgentConfigError";
+	}
+};
+/** @param bytes - 完整文件字节。 @returns SHA-256 小写十六进制编码。 */
+function agentConfigSha256(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+* 拒绝无法在各 Host 文件系统安全表达的相对路径。
+* @param path - 包内 POSIX 路径。
+* @returns 原始路径。
+*/
+function contentPath(path) {
+	assertTemplateRelativePath(path);
+	if (path === "manifest.json" || path.split("/").some((part) => /[<>:"|?*\x00-\x1f]/u.test(part) || /[. ]$/u.test(part) || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu.test(part))) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+	return path;
+}
+/**
+* 同时认证压缩包和逐文件字节，任何失败均发生在版本目录写入前。
+* @param bytes - 下载的完整 gzip 字节。
+* @param descriptor - server 经鉴权查询给出的登记信息。
+* @param maxExpandedBytes - 解压 JSON 和文件总字节上限。
+* @returns 清单和已校验文件。
+*/
+function decodeAgentConfig(bytes, descriptor, maxExpandedBytes) {
+	if (bytes.length !== descriptor.sizeBytes || agentConfigSha256(bytes) !== descriptor.sha256) throw new AgentConfigError("AGENT_CONFIG_DIGEST_MISMATCH");
+	if (!semver.satisfies("2.0.0", descriptor.hostAgentConfigApiRange, { includePrerelease: true })) throw new AgentConfigError("AGENT_CONFIG_INCOMPATIBLE");
+	let document;
+	try {
+		document = AgentConfigDocumentSchema.parse(JSON.parse(gunzipSync(bytes, { maxOutputLength: maxExpandedBytes }).toString("utf8")));
+	} catch (error) {
+		throw new AgentConfigError("AGENT_CONFIG_INVALID");
+	}
+	const { manifest } = document;
+	if (manifest.workspaceKind !== descriptor.workspaceKind || manifest.version !== descriptor.version || manifest.hostAgentConfigApiRange !== descriptor.hostAgentConfigApiRange || document.files.length !== manifest.files.length) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+	const seen = /* @__PURE__ */ new Set();
+	let total = 0;
+	let previous = "";
+	return {
+		manifest,
+		files: document.files.map((file, index) => {
+			const entry = manifest.files[index];
+			const path = contentPath(file.path);
+			const normalized = path.toLowerCase();
+			if (entry.path !== path || path <= previous || seen.has(normalized) || [...seen].some((parent) => normalized.startsWith(`${parent}/`) || parent.startsWith(`${normalized}/`))) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+			seen.add(normalized);
+			previous = path;
+			const data = Buffer.from(file.base64, "base64");
+			total += data.length;
+			if (total > maxExpandedBytes || data.toString("base64") !== file.base64 || data.length !== entry.sizeBytes || agentConfigSha256(data) !== entry.sha256) throw new AgentConfigError("AGENT_CONFIG_DIGEST_MISMATCH");
+			return {
+				path,
+				bytes: data
+			};
+		})
+	};
+}
+//#endregion
+//#region lib/types/bundled-agent-config.js
+/** Published package receipts beside shipped templates, separate from model-visible files. */
+/** Public metadata of the exact published gzip installed as a bundled template. */
+const BundledAgentConfigReceiptSchema = AgentConfigDescriptorSchema.omit({
+	downloadUrl: true,
+	releaseNotes: true
+}).extend({
+	formatVersion: z.literal(1),
+	templateDigest: AgentConfigSha256
+});
+/**
+* Attach the adjacent publication receipt to a verified packaged template.
+* @param template - Template whose file catalog has already been verified.
+* @returns The original template when no receipt exists, otherwise its published identity and receipt.
+* @throws AgentConfigError when an existing receipt is unreadable, invalid or identifies different content.
+*/
+function loadBundledAgentConfigSync(template) {
+	let bytes;
+	try {
+		bytes = readFileSync(join(dirname(template.sourceRoot), `${basename(template.sourceRoot)}.agent-config.json`));
+	} catch (error) {
+		if (error.code === "ENOENT") return template;
+		throw new AgentConfigError("AGENT_CONFIG_INVALID");
+	}
+	let receipt;
+	try {
+		receipt = BundledAgentConfigReceiptSchema.parse(JSON.parse(bytes.toString("utf8")));
+	} catch (error) {
+		throw new AgentConfigError("AGENT_CONFIG_INVALID");
+	}
+	if (receipt.workspaceKind !== template.bundleId || receipt.version !== template.manifest.pluginVersion || receipt.templateDigest !== template.manifest.digest) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+	return {
+		...template,
+		agentConfigSha256: receipt.sha256,
+		agentConfigReceipt: receipt
+	};
+}
+/**
+* Identify downloaded content in journals while registered content follows the installation.
+* @param template - Selected template, including a possible downloaded copy.
+* @param registered - This identity's exact registered object, or undefined during recovery without a registration.
+* @returns Null for the registered object or a template without a package digest; otherwise the package digest.
+*/
+function journalAgentConfigSha256(template, registered) {
+	return template === registered ? null : template.agentConfigSha256 ?? null;
+}
+//#endregion
+//#region lib/types/config.js
+/** workspace-bundle Config: Schemastery field validation and explicit resolution into a Spec. */
+/**
+* Field types and bounds. Path fields are optional here so a missing value reaches
+* {@link resolveWorkspaceBundlesSpec} and fails with its named diagnostic.
+*/
+const Config = Schema.object({
+	materializeRoot: Schema.string().description("Absolute parent of bundled Workspace roots"),
+	templateCacheRoot: Schema.string().description("Absolute parent of immutable template copies"),
+	journalRoot: Schema.string().description("Absolute parent of upgrade journals"),
+	quiesceTimeoutMs: Schema.number().min(1e3).max(6e5).step(1).default(3e4),
+	recycleTimeoutMs: Schema.number().min(0).max(6e5).step(1).default(6e4),
+	agentConfigPollIntervalMs: Schema.number().min(1e3).max(864e5).step(1).default(3e5),
+	agentConfigRequestTimeoutMs: Schema.number().min(100).max(6e5).step(1).default(3e4),
+	agentConfigMaxDownloadBytes: Schema.number().min(1024).max(268435456).step(1).default(67108864),
+	agentConfigMaxExpandedBytes: Schema.number().min(1024).max(536870912).step(1).default(134217728),
+	allowLoopbackAgentConfigHttp: Schema.boolean().default(false)
+});
+function absoluteDirectory(value, field) {
+	if (value === void 0 || value.trim() === "") throw new WorkspaceBundlesConfigError(field === "materializeRoot" ? "WORKSPACE_BUNDLES_MATERIALIZE_ROOT_MISSING" : field === "templateCacheRoot" ? "WORKSPACE_BUNDLES_TEMPLATE_CACHE_ROOT_MISSING" : "WORKSPACE_BUNDLES_JOURNAL_ROOT_MISSING", `${field} is required`);
+	if (!isAbsolute(value) || value.includes("\0") || normalize(value).includes(`..${sep}`) || normalize(value).endsWith(`${sep}..`)) throw new WorkspaceBundlesConfigError("WORKSPACE_BUNDLES_PATH_INVALID", `${field} ${JSON.stringify(value)} must be an absolute path without parent segments`);
+	return normalize(value);
+}
+/**
+* Resolve raw settings into the Spec the Provider runs with.
+* @param config - raw row settings.
+* @returns every field set, with roots normalized.
+* @throws {WorkspaceBundlesConfigError} When a required path is missing or not absolute.
+*/
+function resolveWorkspaceBundlesSpec(config = {}) {
+	const resolved = Config(config);
+	return {
+		materializeRoot: absoluteDirectory(resolved.materializeRoot, "materializeRoot"),
+		templateCacheRoot: absoluteDirectory(resolved.templateCacheRoot, "templateCacheRoot"),
+		journalRoot: absoluteDirectory(resolved.journalRoot, "journalRoot"),
+		quiesceTimeoutMs: resolved.quiesceTimeoutMs,
+		recycleTimeoutMs: resolved.recycleTimeoutMs,
+		agentConfigPollIntervalMs: resolved.agentConfigPollIntervalMs,
+		agentConfigRequestTimeoutMs: resolved.agentConfigRequestTimeoutMs,
+		agentConfigMaxDownloadBytes: resolved.agentConfigMaxDownloadBytes,
+		agentConfigMaxExpandedBytes: resolved.agentConfigMaxExpandedBytes,
+		allowLoopbackAgentConfigHttp: resolved.allowLoopbackAgentConfigHttp
+	};
+}
+//#endregion
+//#region lib/types/local-host-replacement.js
+/** One durable replacement fence per authenticated shop member, independent of installation and module. */
+const State$2 = z.strictObject({
+	version: z.literal(1),
+	replaced: z.array(z.string().regex(/^[a-f0-9]{64}$/u)),
+	migrated: z.array(z.string().regex(/^[a-f0-9]{64}\/(cs-hosting|resource-intake)$/u))
+});
+function keyOf$2(member) {
+	return createHash("sha256").update(JSON.stringify([
+		member.serverOrigin,
+		member.userId,
+		member.currentTenantId
+	])).digest("hex");
+}
+/** The memory fence remains active; callers retain fallback markers and report this failure. */
+var LocalHostReplacementWriteError = class extends Error {
+	/** @param cause - underlying private filesystem failure. */
+	constructor(cause) {
+		super("LOCAL_HOST_REPLACEMENT_WRITE_FAILED", { cause });
+	}
+};
+/** Shared by module reporters, lease supervision and checkpoints within one Host. */
+var LocalHostReplacementState = class {
+	path;
+	state = {
+		version: 1,
+		replaced: [],
+		migrated: []
+	};
+	listeners = /* @__PURE__ */ new Set();
+	persisted = this.state;
+	writes = Promise.resolve();
+	rejections = /* @__PURE__ */ new Map();
+	/** @param path - owner-only state file; null creates an explicit in-memory owner. */
+	constructor(path) {
+		this.path = path;
+		if (path === null) return;
+		try {
+			this.state = State$2.parse(JSON.parse(readFileSync(path, "utf8")));
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+		this.persisted = this.state;
+	}
+	/** @param member - current authenticated member. @returns whether explicit activation is required. */
+	isReplaced(member) {
+		return this.state.replaced.includes(keyOf$2(member));
+	}
+	/** @param listener - reacts to a changed fence. @returns its disposer. */
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	/** @param member - rejected member. Stops consumers before persistence starts. @returns durable completion; failure permits a later retry. */
+	markReplaced(member) {
+		const key = keyOf$2(member);
+		this.rejections.set(key, (this.rejections.get(key) ?? 0) + 1);
+		if (!this.state.replaced.includes(key)) {
+			this.state = {
+				...this.state,
+				replaced: [...this.state.replaced, key]
+			};
+			for (const listener of this.listeners) listener();
+		}
+		if (this.persisted === this.state) return Promise.resolve();
+		return this.enqueue(async () => {
+			const state = this.state;
+			await this.save(state);
+			this.persisted = state;
+		});
+	}
+	/** @param member - member whose two module registrations have both been acknowledged. @returns durable completion, unless a newer rejection requires another activation. */
+	activate(member) {
+		const key = keyOf$2(member), rejection = this.rejections.get(key);
+		if (!this.state.replaced.includes(key)) return Promise.resolve();
+		this.persisted = void 0;
+		return this.enqueue(async () => {
+			const previous = this.state;
+			if (!previous.replaced.includes(key)) return;
+			if (this.rejections.get(key) !== rejection) throw new Error("LOCAL_HOST_REPLACED");
+			const next = {
+				...previous,
+				replaced: previous.replaced.filter((value) => value !== key)
+			};
+			await this.save(next);
+			if (this.state !== previous || this.rejections.get(key) !== rejection) {
+				await this.save(this.state);
+				throw new Error("LOCAL_HOST_REPLACED");
+			}
+			this.persisted = this.state = next;
+			for (const listener of this.listeners) listener();
+		});
+	}
+	/** @param member - current member. @param module - module whose legacy files were inspected. @returns whether migration is complete. */
+	migrated(member, module) {
+		return this.state.migrated.includes(`${keyOf$2(member)}/${module}`);
+	}
+	/** @param member - current member. @param module - legacy source. @param replaced - whether any prior installation was stopped. @returns durable completion before the caller removes fallback flags. */
+	async importLegacy(member, module, replaced) {
+		if (replaced) await this.markReplaced(member);
+		if (this.migrated(member, module)) return;
+		this.state = {
+			...this.state,
+			migrated: [...this.state.migrated, `${keyOf$2(member)}/${module}`]
+		};
+		await this.enqueue(async () => {
+			const state = this.state;
+			await this.save(state);
+			this.persisted = state;
+		});
+	}
+	enqueue(write) {
+		const work = this.writes.then(write);
+		this.writes = work.catch((error) => {});
+		return work;
+	}
+	async save(state) {
+		if (this.path === null) return;
+		try {
+			await writeFileAtomic(this.path, JSON.stringify(state) + "\n", {
+				mode: 384,
+				dirMode: 448
+			});
+		} catch (error) {
+			throw new LocalHostReplacementWriteError(error);
+		}
+	}
+};
+//#endregion
+//#region lib/types/local-host-identity.js
+/** One durable local Host identity per server and member, reused by every local module observation. */
+const State$1 = z.strictObject({
+	version: z.literal(1),
+	scopes: z.record(z.string().regex(/^[a-f0-9]{64}$/u), z.strictObject({
+		hostId: z.uuid(),
+		confirmed: z.boolean()
+	}))
+});
+function keyOf$1(scope) {
+	return createHash("sha256").update(JSON.stringify([scope.serverOrigin, scope.userId])).digest("hex");
+}
+/** Load stops instead of letting modules report under their own identities, which the server may already have replaced. */
+var LocalHostIdentityLoadError = class extends Error {
+	/** @param path - state file that could not be read or parsed. @param cause - underlying read or validation failure. */
+	constructor(path, cause) {
+		super(`The shared local Host identity file ${path} cannot be read or is invalid. Restore it from a backup or fix its permissions; deleting it makes local modules report under their own identities and may require reactivating local hosting.`, { cause });
+	}
+};
+/** The previous identity remains visible; the owner reports this failure and keeps its own reporting. */
+var LocalHostIdentityWriteError = class extends Error {
+	/** @param cause - underlying private filesystem failure. */
+	constructor(cause) {
+		super("LOCAL_HOST_IDENTITY_WRITE_FAILED", { cause });
+	}
+};
+/** Loads synchronously so the first module report already reads the persisted identity. */
+var LocalHostIdentityState = class {
+	path;
+	state = {
+		version: 1,
+		scopes: {}
+	};
+	writes = Promise.resolve();
+	/** @param path - owner-only state file; null creates an explicit in-memory owner. An unreadable or invalid file fails load instead of exposing no identity. */
+	constructor(path) {
+		this.path = path;
+		if (path === null) return;
+		try {
+			this.state = State$1.parse(JSON.parse(readFileSync(path, "utf8")));
+		} catch (error) {
+			if (error.code === "ENOENT") return;
+			throw new LocalHostIdentityLoadError(path, error);
+		}
+	}
+	/** @inheritdoc */
+	get(scope) {
+		const entry = this.state.scopes[keyOf$1(scope)];
+		return entry === void 0 ? void 0 : brandString(entry.hostId);
+	}
+	/** @inheritdoc */
+	publish(scope, read) {
+		const work = this.writes.then(async () => {
+			const key = keyOf$1(scope), previous = this.state.scopes[key], next = read();
+			if (next === void 0) return false;
+			if (previous !== void 0 && (previous.hostId === next.hostId ? previous.confirmed || !next.confirmed : previous.confirmed)) return false;
+			const state = {
+				...this.state,
+				scopes: {
+					...this.state.scopes,
+					[key]: {
+						hostId: next.hostId,
+						confirmed: next.confirmed
+					}
+				}
+			};
+			await this.save(state);
+			this.state = state;
+			return previous?.hostId !== next.hostId;
+		});
+		this.writes = work.then(() => {}, (error) => {});
+		return work;
+	}
+	async save(state) {
+		if (this.path === null) return;
+		try {
+			await writeFileAtomic(this.path, JSON.stringify(state) + "\n", {
+				mode: 384,
+				dirMode: 448
+			});
+		} catch (error) {
+			throw new LocalHostIdentityWriteError(error);
+		}
+	}
+};
+/**
+* Identity getter for a local module reporter: the shared identity of the signed-in member, otherwise the module's own identity.
+* Pass it as `hostId` and keep the fallback fixed; once an identity is shared, the reporter never returns to the fallback.
+* @param ctx - context with the merchant session and WorkspaceBundles.
+* @param fallback - module identity used before any local module published a shared one.
+* @returns getter read before each registration.
+*/
+function sharedLocalHostId(ctx, fallback) {
+	return () => {
+		const scope = ctx.merchantAccount.captureIdentity()?.identity;
+		return (scope === void 0 ? void 0 : ctx.workspaceBundles.localHostIdentity.get(scope)) ?? fallback;
+	};
+}
+//#endregion
+//#region lib/types/definition.js
+/** `WorkspaceBundles` Service Definition: Host-only template registration and stable Workspace materialize. */
+/**
+* Host-only capability: register a packaged template, materialize a stable hidden Workspace, and
+* replace its tree as a whole. Registration is an effect; the returned disposer forbids later acquire.
+*/
+var WorkspaceBundles = class extends Service {
+	/** One member-level fence shared by every local module. */
+	localHostReplacement;
+	/** One persisted local Host identity per server and member, published by the module that owns the installation identity. */
+	localHostIdentity;
+	/** @param ctx - context owning this Provider. @param replacementPath - durable fence file, or null for an in-memory provider. @param identityPath - durable shared identity file, or null for an in-memory provider. */
+	constructor(ctx, replacementPath = null, identityPath = null) {
+		super(ctx, "workspaceBundles");
+		this.localHostReplacement = new LocalHostReplacementState(replacementPath);
+		this.localHostIdentity = new LocalHostIdentityState(identityPath);
+	}
+};
+//#endregion
+//#region lib/types/digest.js
+/** Template manifest parsing and per-file / overall digest verification. */
+const SHA256 = /^[0-9a-f]{64}$/u;
+function fileDigest(bytes) {
+	return brandString(createHash("sha256").update(bytes).digest("hex"));
+}
+/**
+* Digest of the ordered path+file-digest catalog.
+* @param files - sorted catalog.
+*/
+function overallDigest(files) {
+	const hash = createHash("sha256");
+	for (const file of files) hash.update(`${file.path}\0${file.digest}\n`);
+	return brandString(hash.update("").digest("hex"));
+}
+function sourceOf(value) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "object" || value === null) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest source must be an object");
+	const record = value;
+	if (typeof record.repository !== "string" || typeof record.commit !== "string") throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest source must name repository and commit");
+	return {
+		repository: record.repository,
+		commit: record.commit
+	};
+}
+/**
+* Parse and validate a template manifest document.
+* @param value - JSON value.
+*/
+function parseTemplateManifest(value) {
+	if (typeof value !== "object" || value === null) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest must be an object");
+	const record = value;
+	if (record.formatVersion !== 1) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest formatVersion must be 1");
+	if (typeof record.pluginVersion !== "string" || record.pluginVersion === "") throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest pluginVersion is required");
+	if (!Array.isArray(record.files)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest files must be an array");
+	const files = record.files.map((entry, index) => {
+		if (typeof entry !== "object" || entry === null) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", `manifest files[${index}] must be an object`);
+		const file = entry;
+		if (typeof file.path !== "string" || typeof file.bytes !== "number" || typeof file.digest !== "string" || !SHA256.test(file.digest)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", `manifest files[${index}] is incomplete`);
+		assertTemplateRelativePath(file.path);
+		return {
+			path: file.path,
+			bytes: file.bytes,
+			digest: brandString(file.digest)
+		};
+	});
+	const sorted = [...files].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+	if (sorted.some((file, index) => file.path !== files[index]?.path)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest files must be sorted by path");
+	if (sorted.some((file, index) => index > 0 && file.path === sorted[index - 1]?.path)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest files must not repeat a path");
+	if (typeof record.digest !== "string" || !SHA256.test(record.digest)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest digest must be a SHA-256 hex string");
+	const digest = brandString(record.digest);
+	if (digest !== overallDigest(sorted)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_DIGEST_MISMATCH", "manifest overall digest does not match its files");
+	const source = sourceOf(record.source);
+	return source === void 0 ? {
+		formatVersion: 1,
+		pluginVersion: record.pluginVersion,
+		files: sorted,
+		digest
+	} : {
+		formatVersion: 1,
+		pluginVersion: record.pluginVersion,
+		source,
+		files: sorted,
+		digest
+	};
+}
+/**
+* Read every regular file under `root` as a POSIX-relative catalog.
+* @param fs - filesystem.
+* @param root - directory to walk.
+*/
+async function listRegularFiles(fs, root) {
+	const acc = [];
+	const walk = async (directory, prefix) => {
+		let names;
+		try {
+			names = await fs.readdir(directory);
+		} catch (error) {
+			if (error.code === "ENOENT") throw new WorkspaceBundleError("WORKSPACE_BUNDLE_MISSING_ASSET", `template root ${JSON.stringify(root)} is missing`);
+			throw error;
+		}
+		for (const name of [...names].sort()) {
+			const path = join(directory, name);
+			const relative = prefix === "" ? name : `${prefix}/${name}`;
+			const stat = await fs.lstat(path);
+			if (stat.isSymbolicLink()) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_SYMLINK_REJECTED", `template path ${JSON.stringify(relative)} is a symbolic link`);
+			if (stat.isDirectory()) await walk(path, relative);
+			else if (stat.isFile()) {
+				assertTemplateRelativePath(relative);
+				acc.push(relative);
+			} else throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", `template path ${JSON.stringify(relative)} is not a regular file`);
+		}
+	};
+	await walk(root, "");
+	return acc;
+}
+/**
+* Verify every listed file and the overall digest against a directory.
+* @param fs - filesystem.
+* @param root - directory holding the files.
+* @param manifest - expected catalog.
+*/
+async function verifyTemplateTree(fs, root, manifest) {
+	const present = new Set(await listRegularFiles(fs, root));
+	present.delete("manifest.json");
+	for (const file of manifest.files) {
+		if (!present.has(file.path)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_MISSING_ASSET", `template is missing ${JSON.stringify(file.path)}`);
+		const bytes = await fs.readFile(join(root, ...file.path.split("/")));
+		if (bytes.length !== file.bytes || fileDigest(bytes) !== file.digest) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_DIGEST_MISMATCH", `template file ${JSON.stringify(file.path)} digest mismatch`);
+		present.delete(file.path);
+	}
+	if (present.size > 0) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", `template has unexpected files ${[...present].join(", ")}`);
+}
+/**
+* Load `manifest.json` from a template directory and verify the tree.
+* @param fs - filesystem.
+* @param root - template directory.
+*/
+async function loadVerifiedManifest(fs, root) {
+	let raw;
+	try {
+		raw = await fs.readFile(join(root, "manifest.json"));
+	} catch (error) {
+		if (error.code === "ENOENT") throw new WorkspaceBundleError("WORKSPACE_BUNDLE_MISSING_ASSET", "template is missing manifest.json");
+		throw error;
+	}
+	let value;
+	try {
+		value = JSON.parse(raw.toString("utf8"));
+	} catch {
+		throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest.json is not JSON");
+	}
+	const manifest = parseTemplateManifest(value);
+	await verifyTemplateTree(fs, root, manifest);
+	return manifest;
+}
+/** @param bytes - file contents. */
+function digestOf(bytes) {
+	return fileDigest(bytes);
+}
+/**
+* Load and verify a packaged template at plugin construction. A missing or
+* invalid tree fails load instead of registering a half-checked catalog.
+* @param root - template directory.
+*/
+function loadVerifiedManifestSync(root) {
+	const manifestPath = join(root, "manifest.json");
+	if (!existsSync(manifestPath)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_MISSING_ASSET", "template is missing manifest.json");
+	let value;
+	try {
+		value = JSON.parse(readFileSync(manifestPath, "utf8"));
+	} catch {
+		throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest.json is not JSON");
+	}
+	const manifest = parseTemplateManifest(value);
+	const present = /* @__PURE__ */ new Set();
+	const walk = (directory, prefix) => {
+		let names;
+		try {
+			names = readdirSync(directory);
+		} catch (error) {
+			if (error.code === "ENOENT") throw new WorkspaceBundleError("WORKSPACE_BUNDLE_MISSING_ASSET", `template root ${JSON.stringify(root)} is missing`);
+			throw error;
+		}
+		for (const name of [...names].sort()) {
+			const path = join(directory, name);
+			const relative = prefix === "" ? name : `${prefix}/${name}`;
+			const stat = lstatSync(path);
+			if (stat.isSymbolicLink()) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_SYMLINK_REJECTED", `template path ${JSON.stringify(relative)} is a symbolic link`);
+			if (stat.isDirectory()) walk(path, relative);
+			else if (stat.isFile()) {
+				assertTemplateRelativePath(relative);
+				present.add(relative);
+			} else throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", `template path ${JSON.stringify(relative)} is not a regular file`);
+		}
+	};
+	walk(root, "");
+	present.delete("manifest.json");
+	for (const file of manifest.files) {
+		if (!present.has(file.path)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_MISSING_ASSET", `template is missing ${JSON.stringify(file.path)}`);
+		const bytes = readFileSync(join(root, ...file.path.split("/")));
+		if (bytes.length !== file.bytes || fileDigest(bytes) !== file.digest) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_DIGEST_MISMATCH", `template file ${JSON.stringify(file.path)} digest mismatch`);
+		present.delete(file.path);
+	}
+	if (present.size > 0) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", `template has unexpected files ${[...present].join(", ")}`);
+	return manifest;
+}
+//#endregion
+//#region lib/types/filesystem.js
+/** Node filesystem adapter and test crash injection. */
+/**
+* Node.js implementation of {@link WorkspaceBundleFs}.
+* @param options.onPoint - optional test hook; throwing aborts the current step.
+*/
+function createNodeFs(options = {}) {
+	return {
+		async mkdir(path) {
+			await mkdir(path, { recursive: true });
+		},
+		async writeFile(path, data) {
+			await mkdir(dirname(path), { recursive: true });
+			await writeFile(path, data);
+		},
+		readFile(path) {
+			return readFile(path);
+		},
+		rename(from, to) {
+			return rename(from, to);
+		},
+		rm(path, options) {
+			return rm(path, {
+				recursive: options?.recursive === true,
+				force: true
+			});
+		},
+		lstat(path) {
+			return lstat(path);
+		},
+		async readdir(path) {
+			return readdir(path);
+		},
+		realpath(path) {
+			return realpath(path);
+		},
+		copyFile(from, to) {
+			return copyFile(from, to);
+		},
+		async exists(path) {
+			try {
+				await access(path, constants.F_OK);
+				return true;
+			} catch {
+				return false;
+			}
+		}
+	};
+}
+/**
+* Wrap an fs with a crash injector used only by tests.
+* @param inner - real or fake filesystem.
+* @param crashAt - the single point that throws {@link WorkspaceBundleError} `WORKSPACE_BUNDLE_CRASH_INJECTED`.
+*/
+function crashableFs(inner, crashAt) {
+	return {
+		...inner,
+		crash(point) {
+			if (crashAt === point) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_CRASH_INJECTED", point);
+		}
+	};
+}
+//#endregion
+//#region lib/types/journal.js
+/** Durable upgrade journal: staging → updating → swap → verify → commit, with crash recovery. */
+const IDLE = {
+	phase: "idle",
+	fromDigest: null,
+	toDigest: null,
+	pluginVersion: null,
+	stagingPath: null,
+	backupPath: null,
+	swapComplete: false
+};
+/** @returns a journal with no in-flight replacement. */
+function idleJournal() {
+	return IDLE;
+}
+/**
+* @param parent - journal root from Spec.
+* @param identity - bundled Workspace.
+*/
+function recordPath(parent, identity) {
+	return join(bundledDirectory(parent, identity), "record.json");
+}
+async function writeJson(fs, path, value) {
+	const tmp = `${path}.tmp`;
+	await fs.writeFile(tmp, `${JSON.stringify(value)}\n`);
+	await fs.rename(tmp, path);
+}
+/**
+* Persist the product record.
+* @param fs - filesystem.
+* @param path - record.json path.
+* @param record - value.
+*/
+async function writeRecord(fs, path, record) {
+	await writeJson(fs, path, record);
+}
+/**
+* Read a product record when present.
+* @param fs - filesystem.
+* @param path - record.json path.
+*/
+async function readRecord(fs, path) {
+	if (!await fs.exists(path)) return void 0;
+	const value = JSON.parse((await fs.readFile(path)).toString("utf8"));
+	if (value.version !== 1) throw new Error(`workspace-bundle: unsupported record version ${String(value.version)}`);
+	return value;
+}
+async function canonicalPath(fs, path) {
+	try {
+		return await fs.realpath(path);
+	} catch (error) {
+		if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT" || dirname(path) === path) throw error;
+		return join(await canonicalPath(fs, dirname(path)), basename(path));
+	}
+}
+/**
+* Reject stored paths whose canonical locations differ from the identity's controlled directories.
+* @param fs - filesystem used by recovery, including realpath resolution.
+* @param record - stored product record.
+* @param root - materialize directory derived from the requested identity and current Spec.
+* @returns fulfills when every stored path has the same canonical location as its controlled directory.
+* @throws {WorkspaceBundleError} Before recovery mutates files when a stored path differs.
+*/
+async function assertRecordPaths(fs, record, root) {
+	for (const [stored, controlled] of [
+		[record.path, root],
+		[record.journal.stagingPath, `${root}.staging`],
+		[record.journal.backupPath, `${root}.backup`]
+	]) if (stored !== null && await canonicalPath(fs, stored) !== await canonicalPath(fs, controlled)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_PATH_TRAVERSAL", `stored Workspace paths must match the canonical controlled directory ${controlled}`);
+}
+/**
+* Persist the journal as part of the product record.
+* @param fs - filesystem.
+* @param path - record.json path.
+* @param record - current record.
+* @param journal - next journal.
+*/
+async function writeJournal(fs, path, record, journal) {
+	const next = {
+		...record,
+		journal
+	};
+	await writeRecord(fs, path, next);
+	return next;
+}
+/**
+* Mark a replacement as committed: idle journal, new digest and plugin version.
+* @param record - current record.
+* @param digest - verified tree digest.
+* @param pluginVersion - packaged plugin version.
+*/
+function committedRecord(record, digest, pluginVersion) {
+	return {
+		...record,
+		pluginVersion,
+		templateDigest: digest,
+		journal: idleJournal(),
+		lastFailure: null
+	};
+}
+//#endregion
+//#region lib/types/agent-config-source.js
+/** 内容来源的有界拉取和只读版本缓存；此模块不替换运行中的 Workspace。 */
+const AssignmentSchema = z.discriminatedUnion("source", [z.object({
+	source: z.literal("builtin"),
+	workspaceKind: z.string()
+}), z.object({
+	source: z.literal("registry"),
+	workspaceKind: z.string(),
+	agentConfig: AgentConfigDescriptorSchema
+})]);
+const ReceiptSchema = AgentConfigDescriptorSchema.omit({
+	downloadUrl: true,
+	releaseNotes: true
+});
+function publicVersion(template, sha256) {
+	return {
+		workspaceKind: template.bundleId,
+		version: template.manifest.pluginVersion,
+		sha256,
+		hostAgentConfigApiVersion: HOST_AGENT_CONFIG_API_VERSION,
+		templateDigest: template.manifest.digest,
+		sourceRoot: template.sourceRoot
+	};
+}
+async function freezeTree(root) {
+	for (const entry of await readdir(root, { withFileTypes: true })) {
+		const path = join(root, entry.name);
+		if (entry.isDirectory()) await freezeTree(path);
+		else await chmod(path, 292);
+	}
+	await chmod(root, 365);
+}
+/** 一个注册来源的缓存、轮询和候选版本；卸载必须等待所有网络与文件工作结束。 */
+var WorkspaceAgentConfigSourceOwner = class {
+	registration;
+	spec;
+	report;
+	download;
+	recoverIdle;
+	lifetime = new AbortController();
+	inFlight;
+	requestAbort;
+	requestRevision;
+	preparedRevisions = /* @__PURE__ */ new WeakMap();
+	timer;
+	selected;
+	candidate;
+	failure = null;
+	rejection;
+	admissionFailure;
+	root;
+	observation;
+	startup = Promise.resolve();
+	blockedVersion;
+	/** @param registration - 内置模板及鉴权查询回调。 @param spec - 部署预算。 @param report - 固定失败诊断的报告者。 @param download - 文件 HTTP 传输。 @param recoverIdle - Provider 串行检查活动租约后恢复已阻断的配置；省略时保留候选等待获取工作区。 */
+	constructor(registration, spec, report, download = fetch, recoverIdle = async () => {}) {
+		this.registration = registration;
+		this.spec = spec;
+		this.report = report;
+		this.download = download;
+		this.recoverIdle = recoverIdle;
+		this.selected = {
+			template: registration.template,
+			sha256: registration.template.agentConfigSha256 ?? null
+		};
+		this.root = bundledDirectory(join(spec.templateCacheRoot, "agent-config-versions"), registration.source.identity);
+	}
+	/** @returns 已应用/候选版本、执行阻断及当前作用域的最近失败和拒绝。 */
+	state() {
+		if (this.candidate !== void 0 && this.candidate.revision !== this.registration.source.revision()) this.candidate = void 0;
+		if (this.lifetime.signal.aborted || this.rejection?.revision !== this.registration.source.revision()) this.rejection = void 0;
+		return {
+			lastRejection: this.rejection?.value ?? null,
+			blocked: this.admissionFailure !== void 0,
+			blockingFailure: this.admissionFailure === void 0 ? null : { code: this.admissionFailure.code },
+			current: this.blockedVersion ?? publicVersion(this.selected.template, this.selected.sha256),
+			pending: this.candidate === void 0 ? null : publicVersion(this.candidate.template, this.candidate.sha256),
+			failure: this.admissionFailure === void 0 ? this.failure : {
+				code: this.admissionFailure.code,
+				message: this.admissionFailure.message
+			}
+		};
+	}
+	/**
+	* 从 journal 已提交的摘要定位只读缓存，不从 server 的无分配回答推导降级。
+	* @param digest - 已提交 Workspace 模板摘要；undefined 表示首次使用。
+	* @param version - 已提交完整版本，包括构建元数据。
+	* @param sha256 - 已提交包摘要；undefined 支持旧内置记录。
+	* @returns 对应完整模板；缺失已安装缓存时拒绝继续。
+	*/
+	async recover(digest, version, sha256) {
+		const revision = this.registration.source.revision();
+		try {
+			const template = await this.recoverExecution(digest, version, sha256);
+			if (this.rejection?.revision === revision && this.rejection.value.version === template.manifest.pluginVersion) this.rejection = void 0;
+			return template;
+		} catch (error) {
+			if (digest !== void 0 && version !== void 0) this.blockedVersion = {
+				...publicVersion(this.registration.template, sha256 ?? null),
+				version,
+				templateDigest: digest
+			};
+			const failure = new AgentConfigError(this.configError(error).code, "blocked");
+			const previous = this.admissionFailure;
+			this.admissionFailure = failure;
+			this.rememberRejection(failure, version, revision, sha256 ?? void 0);
+			if (previous?.code !== failure.code) this.reportFailure(failure);
+			throw failure;
+		}
+	}
+	async recoverExecution(digest, version, sha256) {
+		const restored = await this.restoredTemplate(digest, version, sha256);
+		this.assertCompatible(restored.range, restored.runtimeApiRange);
+		await this.registration.source.validate?.(restored.template, this.lifetime.signal);
+		this.selected = {
+			template: restored.template,
+			sha256: restored.template.agentConfigSha256 ?? null
+		};
+		this.blockedVersion = void 0;
+		this.admissionFailure = void 0;
+		if (this.candidate?.sha256 === this.selected.sha256) this.candidate = void 0;
+		return restored.template;
+	}
+	/**
+	* Load a complete old/new tree only for physical swap recovery; this grants no execution permission.
+	* @param digest - Journal template digest.
+	* @param version - Journal release version, when recorded.
+	* @param sha256 - Journal package digest, absent for builtin.
+	* @returns Physically verified template; consumers must subsequently call recover for execution validation.
+	*/
+	async recoverPhysical(digest, version, sha256) {
+		return (await this.restoredTemplate(digest, version, sha256)).template;
+	}
+	async restoredTemplate(digest, version, sha256) {
+		if (digest === void 0 || sha256 === void 0 || sha256 === null) {
+			const template = this.registration.template;
+			return {
+				template,
+				range: template.agentConfigReceipt?.hostAgentConfigApiRange,
+				...template.agentConfigReceipt?.runtimeApiRange === void 0 ? {} : { runtimeApiRange: template.agentConfigReceipt.runtimeApiRange }
+			};
+		}
+		if (!/^[0-9a-f]{64}$/u.test(sha256)) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		const fs = createNodeFs();
+		const receipt = ReceiptSchema.parse(JSON.parse(await readFile(join(this.root, sha256, "receipt.json"), "utf8")));
+		const directory = this.versionDirectory(receipt.version, receipt.sha256);
+		if (receipt.sha256 !== sha256 || receipt.workspaceKind !== this.registration.template.bundleId || (await fs.lstat(directory)).isSymbolicLink() || (await fs.lstat(join(directory, receipt.version))).isSymbolicLink()) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		const manifest = await loadVerifiedManifest(fs, join(directory, receipt.version));
+		if (manifest.digest !== digest || version !== void 0 && receipt.version !== version || manifest.pluginVersion !== receipt.version) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		const { bundleId, workspaceKey, title } = this.registration.template;
+		return {
+			template: {
+				bundleId,
+				workspaceKey,
+				title,
+				sourceRoot: join(directory, receipt.version),
+				manifest,
+				agentConfigSha256: receipt.sha256
+			},
+			range: receipt.hostAgentConfigApiRange,
+			...receipt.runtimeApiRange === void 0 ? {} : { runtimeApiRange: receipt.runtimeApiRange }
+		};
+	}
+	assertCompatible(range, runtimeApiRange) {
+		if (range !== void 0 && !semver.satisfies("2.0.0", range, { includePrerelease: true })) throw new AgentConfigError("AGENT_CONFIG_INCOMPATIBLE");
+		const runtime = this.registration.source.runtimeApiVersion;
+		if (runtimeApiRange !== void 0 && (runtime === void 0 || !semver.satisfies(runtime, runtimeApiRange, { includePrerelease: true }))) throw new AgentConfigError("AGENT_CONFIG_INCOMPATIBLE");
+	}
+	configError(error) {
+		return error instanceof AgentConfigError ? error : new AgentConfigError(error instanceof WorkspaceBundleError && error.code === "WORKSPACE_BUNDLE_DIGEST_MISMATCH" ? "AGENT_CONFIG_DIGEST_MISMATCH" : "AGENT_CONFIG_INVALID");
+	}
+	reportFailure(error) {
+		try {
+			this.report(error);
+		} catch (reportError) {
+			process.stderr.write(`${error.code}: ${error.message}\n`);
+		}
+	}
+	/** @param restore - Restore this identity's committed journal before starting reports or queries; omission is for an owner without a journal. */
+	start(restore = async () => {}) {
+		this.startup = restore().then(() => {
+			if (!this.lifetime.signal.aborted) this.observation = this.registration.source.observation?.(() => this.state());
+		});
+		const tick = async () => {
+			try {
+				await this.refresh();
+			} catch (error) {
+				this.reportFailure(this.configError(error));
+			}
+			if (!this.lifetime.signal.aborted) this.timer = setTimeout(() => {
+				tick();
+			}, this.spec.agentConfigPollIntervalMs);
+		};
+		tick();
+	}
+	/** @returns 本次查询和完整候选下载结束；失败通过 state 与 report 保留可观察诊断。 */
+	refresh() {
+		return this.startup.then(() => this.refreshReady());
+	}
+	refreshReady() {
+		if (this.lifetime.signal.aborted) return Promise.resolve();
+		const revision = this.registration.source.revision();
+		if (this.candidate !== void 0 && this.candidate.revision !== revision) this.candidate = void 0;
+		if (this.inFlight !== void 0) {
+			if (revision === this.requestRevision && !this.requestAbort?.signal.aborted) return this.inFlight;
+			this.requestAbort?.abort();
+			this.failure = null;
+			return this.inFlight.then(() => this.refresh());
+		}
+		const abort = new AbortController();
+		this.requestAbort = abort;
+		this.requestRevision = revision;
+		const attempt = {};
+		const run = this.fetchCandidate(revision, abort.signal, attempt).then(async () => {
+			if (this.lifetime.signal.aborted || abort.signal.aborted || revision !== this.registration.source.revision()) return;
+			if (this.admissionFailure !== void 0 && this.candidate !== void 0) await this.recoverIdle();
+			if (!this.lifetime.signal.aborted) await this.observation?.refresh();
+		}).catch((error) => {
+			if (this.lifetime.signal.aborted || abort.signal.aborted || revision !== this.registration.source.revision()) return;
+			this.candidate = void 0;
+			const failure = this.configError(error);
+			this.failure = {
+				code: failure.code,
+				message: failure.message
+			};
+			this.rememberRejection(failure, attempt.version, revision, attempt.sha256);
+			this.reportFailure(failure);
+		}).finally(() => {
+			this.inFlight = void 0;
+			this.requestAbort = void 0;
+			this.requestRevision = void 0;
+		});
+		this.inFlight = run;
+		return run;
+	}
+	/** @returns 下一个 turn 可应用的候选；没有候选时使用已安装版本。 */
+	template() {
+		if (this.candidate !== void 0 && this.candidate.revision !== this.registration.source.revision()) this.candidate = void 0;
+		if (this.candidate === void 0 && this.admissionFailure !== void 0) throw this.admissionFailure;
+		return this.candidate?.template ?? this.selected.template;
+	}
+	/** @throws AgentConfigError while committed content is blocked, including when another lease remains active. */
+	assertExecutionAllowed() {
+		if (this.admissionFailure !== void 0) throw this.admissionFailure;
+	}
+	/** @param template - Pending template. @returns After compatibility and consumer validation, without selecting it. */
+	async prepare(template) {
+		try {
+			await this.prepareValidated(template);
+		} catch (error) {
+			throw this.configError(error);
+		}
+	}
+	async prepareValidated(template) {
+		this.assertApplicable(template);
+		const restored = await this.restoredTemplate(template.manifest.digest, template.manifest.pluginVersion, journalAgentConfigSha256(template, this.registration.template));
+		this.assertCompatible(restored.range, restored.runtimeApiRange);
+		await this.registration.source.validate?.(restored.template, this.lifetime.signal);
+		this.assertApplicable(template);
+	}
+	/** @param template - 即将整体替换的候选。 @throws 来源代次已经改变或已撤销时拒绝应用。 */
+	assertApplicable(template) {
+		const revision = this.preparedRevisions.get(template);
+		if (this.lifetime.signal.aborted || revision !== void 0 && revision !== this.registration.source.revision()) throw new AgentConfigError("AGENT_CONFIG_SCOPE_CHANGED");
+	}
+	/** @param template - 已通过 Workspace 整体替换提交的模板。 */
+	async committed(template) {
+		await this.recover(template.manifest.digest, template.manifest.pluginVersion, journalAgentConfigSha256(template, this.registration.template));
+	}
+	/**
+	* 清除未提交候选，报告整体替换失败；已提交状态由 journal 恢复结果决定。
+	* @param template - 未能完成提交的模板。
+	* @param cause - 保留来源失效分类；其他原因报告固定应用失败诊断。
+	*/
+	failedApply(template, cause) {
+		if (this.candidate?.template === template) this.candidate = void 0;
+		const error = cause instanceof AgentConfigError ? cause : new AgentConfigError("AGENT_CONFIG_APPLY_FAILED");
+		this.failure = {
+			code: error.code,
+			message: error.message
+		};
+		const revision = this.preparedRevisions.get(template) ?? this.registration.source.revision();
+		this.rememberRejection(error, template.manifest.pluginVersion, revision, template.agentConfigSha256);
+		this.reportFailure(error);
+	}
+	/** 撤销查询、清除后续定时器，并等待下载和目录写入完成。 */
+	async dispose() {
+		this.lifetime.abort();
+		this.rejection = void 0;
+		this.candidate = void 0;
+		if (this.timer !== void 0) clearTimeout(this.timer);
+		await Promise.all([
+			this.startup,
+			this.inFlight,
+			this.observation?.dispose()
+		]);
+		this.candidate = void 0;
+	}
+	versionDirectory(version, sha256) {
+		if (!AgentConfigDescriptorSchema.shape.version.safeParse(version).success || !/^[0-9a-f]{64}$/u.test(sha256)) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		return join(this.root, sha256);
+	}
+	rememberRejection(error, version, revision, sha256) {
+		if (this.lifetime.signal.aborted || revision !== this.registration.source.revision()) return;
+		if (error.code === "AGENT_CONFIG_SCOPE_CHANGED") {
+			this.rejection = void 0;
+			return;
+		}
+		if (error.code === "AGENT_CONFIG_QUERY_FAILED") return;
+		this.rejection = {
+			revision,
+			value: {
+				code: error.code,
+				...version === void 0 ? {} : { version },
+				...sha256 === void 0 ? {} : { sha256 }
+			}
+		};
+	}
+	async fetchCandidate(revision, requestSignal, attempt) {
+		const signal = AbortSignal.any([
+			this.lifetime.signal,
+			requestSignal,
+			AbortSignal.timeout(this.spec.agentConfigRequestTimeoutMs)
+		]);
+		let value;
+		try {
+			value = await this.registration.source.query(signal);
+		} catch (error) {
+			throw error instanceof AgentConfigError ? error : new AgentConfigError("AGENT_CONFIG_QUERY_FAILED");
+		}
+		const assignment = AssignmentSchema.safeParse(value);
+		if (!assignment.success || assignment.data.workspaceKind !== this.registration.template.bundleId) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		if (assignment.data.source === "builtin") {
+			this.candidate = void 0;
+			this.failure = null;
+			this.rejection = void 0;
+			return;
+		}
+		const descriptor = assignment.data.agentConfig;
+		attempt.version = descriptor.version;
+		attempt.sha256 = descriptor.sha256;
+		if (this.rejection?.value.version !== descriptor.version || this.rejection?.value.sha256 !== descriptor.sha256) this.rejection = void 0;
+		if (descriptor.workspaceKind !== assignment.data.workspaceKind) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		this.assertCompatible(descriptor.hostAgentConfigApiRange, descriptor.runtimeApiRange);
+		if (descriptor.sha256 === (this.blockedVersion?.sha256 ?? this.selected.sha256)) {
+			this.candidate = void 0;
+			this.failure = null;
+			this.rejection = void 0;
+			return;
+		}
+		if (descriptor.sizeBytes > this.spec.agentConfigMaxDownloadBytes) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		const url = new URL(descriptor.downloadUrl);
+		if (url.username !== "" || url.password !== "" || url.protocol !== "https:" && !(this.spec.allowLoopbackAgentConfigHttp && url.protocol === "http:" && [
+			"localhost",
+			"127.0.0.1",
+			"[::1]"
+		].includes(url.hostname))) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		let bytes;
+		try {
+			const response = await this.download(url, {
+				signal,
+				redirect: "error"
+			});
+			if (!response.ok || response.body === null || response.headers.get("content-length") !== null && Number(response.headers.get("content-length")) !== descriptor.sizeBytes) throw new AgentConfigError("AGENT_CONFIG_DOWNLOAD_FAILED");
+			const chunks = [];
+			let count = 0;
+			for await (const chunk of response.body) {
+				count += chunk.byteLength;
+				if (count > descriptor.sizeBytes) {
+					await response.body.cancel().catch(() => void 0);
+					throw new AgentConfigError("AGENT_CONFIG_DOWNLOAD_FAILED");
+				}
+				chunks.push(chunk);
+			}
+			bytes = Buffer.concat(chunks);
+		} catch (error) {
+			throw new AgentConfigError("AGENT_CONFIG_DOWNLOAD_FAILED");
+		}
+		const content = decodeAgentConfig(bytes, descriptor, this.spec.agentConfigMaxExpandedBytes);
+		if (signal.aborted || revision !== this.registration.source.revision()) return;
+		await mkdir(this.root, { recursive: true });
+		const directory = this.versionDirectory(descriptor.version, descriptor.sha256);
+		const tree = join(directory, descriptor.version);
+		const fs = createNodeFs();
+		if (!await fs.exists(directory)) {
+			const staging = await mkdtemp(join(this.root, ".staging-"));
+			try {
+				const stagingTree = join(staging, descriptor.version);
+				await mkdir(stagingTree);
+				for (const file of content.files) {
+					const path = join(stagingTree, ...file.path.split("/"));
+					await mkdir(dirname(path), { recursive: true });
+					await writeFile(path, file.bytes, { flag: "wx" });
+				}
+				const files = content.manifest.files.map((file) => ({
+					path: file.path,
+					bytes: file.sizeBytes,
+					digest: brandString(file.sha256)
+				}));
+				await writeFile(join(stagingTree, "manifest.json"), JSON.stringify({
+					formatVersion: 1,
+					pluginVersion: descriptor.version,
+					files,
+					digest: overallDigest(files)
+				}) + "\n");
+				const { downloadUrl: _downloadUrl, releaseNotes: _releaseNotes, ...receipt } = descriptor;
+				await writeFile(join(staging, "receipt.json"), JSON.stringify(ReceiptSchema.parse(receipt)) + "\n");
+				await rename(staging, directory);
+				await freezeTree(tree);
+				await chmod(join(directory, "receipt.json"), 292);
+			} finally {
+				await rm(staging, {
+					recursive: true,
+					force: true
+				});
+			}
+		}
+		const manifest = await loadVerifiedManifest(fs, tree);
+		const files = content.manifest.files.map((file) => ({
+			path: file.path,
+			bytes: file.sizeBytes,
+			digest: brandString(file.sha256)
+		}));
+		if (manifest.pluginVersion !== descriptor.version || manifest.digest !== overallDigest(files)) throw new AgentConfigError("AGENT_CONFIG_DIGEST_MISMATCH");
+		if (signal.aborted || revision !== this.registration.source.revision()) return;
+		const { bundleId, workspaceKey, title } = this.registration.template;
+		const template = {
+			bundleId,
+			workspaceKey,
+			title,
+			sourceRoot: tree,
+			manifest,
+			agentConfigSha256: descriptor.sha256
+		};
+		await this.registration.source.validate?.(template, signal);
+		if (signal.aborted || revision !== this.registration.source.revision()) return;
+		this.preparedRevisions.set(template, revision);
+		this.candidate = {
+			template,
+			sha256: descriptor.sha256,
+			revision
+		};
+		this.failure = null;
+		this.rejection = void 0;
+	}
+};
+//#endregion
+//#region lib/types/provider.js
+/**
+* Host Provider of `WorkspaceBundles`: register a packaged template, materialize a stable
+* hidden Workspace, and replace its tree as a whole with crash recovery.
+*/
+function keyOf(identity) {
+	return `${identity.bundleId}/${identity.workspaceKey}`;
+}
+function originOf(identity) {
+	return {
+		kind: "bundle",
+		bundleId: identity.bundleId,
+		workspaceKey: identity.workspaceKey
+	};
+}
+async function copyTree(fs, from, to, files) {
+	await fs.rm(to, { recursive: true });
+	await fs.mkdir(to);
+	for (const file of files) {
+		const relative = file.path.split("/");
+		const destination = join(to, ...relative);
+		await fs.mkdir(join(destination, ".."));
+		await fs.copyFile(join(from, ...relative), destination);
+	}
+}
+/** Provider for packaged Workspace templates. */
+var GestaltWorkspaceBundles = class extends WorkspaceBundles {
+	static inject = ["workspaceRegistry"];
+	static Config = Config;
+	/** Deployment settings resolved at load. */
+	spec;
+	fs;
+	templates = /* @__PURE__ */ new Map();
+	agentConfigSources = /* @__PURE__ */ new Map();
+	records = /* @__PURE__ */ new Map();
+	leases = /* @__PURE__ */ new Map();
+	waiters = /* @__PURE__ */ new Map();
+	chain = Promise.resolve();
+	recycle = /* @__PURE__ */ new Map();
+	recycleWork = /* @__PURE__ */ new Map();
+	contentDrains = /* @__PURE__ */ new Set();
+	closed = false;
+	download;
+	/**
+	* @param ctx - Host context with the Workspace registry.
+	* @param config - raw row settings.
+	* @param options.fs - filesystem; tests inject crashes through `crashAt`.
+	* @param options.crashAt - single crash point; production omits it.
+	* @param options.fetch - 文件 HTTP 传输；默认使用 Host fetch。
+	*/
+	constructor(ctx, config = {}, options = {}) {
+		const spec = resolveWorkspaceBundlesSpec(config);
+		super(ctx, join(spec.journalRoot, "local-host-replacement.json"), join(spec.journalRoot, "local-host-identity.json"));
+		this.spec = spec;
+		this.fs = crashableFs(options.fs ?? createNodeFs(), options.crashAt);
+		this.download = options.fetch ?? fetch;
+		ctx.effect(() => async () => {
+			this.closed = true;
+			for (const timer of this.recycle.values()) clearTimeout(timer);
+			this.recycle.clear();
+			await Promise.all([...this.agentConfigSources.values()].map((source) => source.dispose()));
+			await this.chain;
+			await Promise.all(this.contentDrains);
+			await Promise.all(this.recycleWork.values());
+			this.agentConfigSources.clear();
+		}, "workspace-bundle: recycle timers");
+	}
+	/** @inheritdoc */
+	register(template) {
+		if (this.closed) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Workspace 内容服务已停止");
+		identityOf(template.bundleId, template.workspaceKey);
+		const key = keyOf(template);
+		this.templates.set(key, template);
+		const record = this.records.get(key);
+		if (record !== void 0) this.records.set(key, {
+			...record,
+			registered: true
+		});
+		return () => {
+			if (this.templates.get(key) !== template) return;
+			this.templates.delete(key);
+			const current = this.records.get(key);
+			if (current !== void 0) this.records.set(key, {
+				...current,
+				registered: false
+			});
+		};
+	}
+	/** @inheritdoc */
+	ensure(identity) {
+		if (this.closed) return Promise.reject(new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Workspace 内容服务已停止"));
+		identityOf(identity.bundleId, identity.workspaceKey);
+		return this.enqueue(() => this.ensureOne(identity));
+	}
+	/** @inheritdoc */
+	registerAgentConfigSource(source) {
+		if (this.closed) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Workspace 内容服务已停止");
+		const key = keyOf(source.identity);
+		const template = this.requireTemplate(source.identity);
+		if (this.agentConfigSources.has(key)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "Agent 配置版本来源已注册");
+		const owner = new WorkspaceAgentConfigSourceOwner({
+			template,
+			source
+		}, this.spec, (error) => {
+			this.ctx.logger.warn("%s：%s", error.code, error.message);
+		}, this.download, () => this.enqueue(async () => {
+			if (this.closed || this.agentConfigSources.get(key) !== owner) return;
+			const state = owner.state();
+			const record = this.records.get(key);
+			if (!state.blocked || state.pending === null || record?.workspaceId != null && (this.leases.get(record.workspaceId)?.size ?? 0) > 0) return;
+			await this.ensureOne(source.identity);
+		}));
+		this.agentConfigSources.set(key, owner);
+		owner.start(() => this.enqueue(async () => {
+			await this.recoverOne(source.identity);
+			const record = this.records.get(key);
+			try {
+				await owner.recover(record?.templateDigest, record?.pluginVersion, record?.agentConfigSha256);
+			} catch (error) {
+				if (!(error instanceof AgentConfigError)) throw error;
+			}
+		}));
+		return async () => {
+			await owner.dispose();
+			if (this.agentConfigSources.get(key) === owner) this.agentConfigSources.delete(key);
+		};
+	}
+	/** @inheritdoc */
+	agentConfig(identity) {
+		return this.agentConfigSources.get(keyOf(identity))?.state();
+	}
+	/** @inheritdoc */
+	async refreshAgentConfig(identity) {
+		const source = this.agentConfigSources.get(keyOf(identity));
+		if (source === void 0) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Agent 配置版本来源未注册");
+		await source.refresh();
+	}
+	/** @inheritdoc */
+	async acquire(workspaceId) {
+		if (this.closed) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Workspace 内容服务已停止");
+		if ([...this.records.values()].some((record) => record.workspaceId === workspaceId && record.journal.phase === "updating")) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", `workspace ${workspaceId} is updating`);
+		return this.enqueue(() => this.acquireOne(workspaceId));
+	}
+	/** @inheritdoc */
+	acquireAgentConfig(identity) {
+		if (this.closed) return Promise.reject(new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Workspace content service is stopped"));
+		identityOf(identity.bundleId, identity.workspaceKey);
+		return this.enqueue(async () => {
+			if (this.closed) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Workspace content service is stopped");
+			const registered = this.requireTemplate(identity);
+			const source = this.agentConfigSources.get(keyOf(identity));
+			const revision = source?.registration.source.revision();
+			const workspace = await this.ensureOne(identity);
+			const record = this.records.get(keyOf(identity));
+			const template = source === void 0 ? this.requireTemplate(identity) : await source.recover(record.templateDigest, record.pluginVersion, record.agentConfigSha256);
+			await verifyTemplateTree(this.fs, template.sourceRoot, template.manifest);
+			if (this.closed) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Workspace content service is stopped");
+			if (this.requireTemplate(identity) !== registered || this.agentConfigSources.get(keyOf(identity)) !== source || source?.registration.source.revision() !== revision) throw new AgentConfigError("AGENT_CONFIG_SCOPE_CHANGED");
+			if (template.manifest.digest !== record.templateDigest || template.manifest.pluginVersion !== record.pluginVersion) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+			const version = {
+				workspaceKind: identity.bundleId,
+				workspaceId: workspace.id,
+				version: record.pluginVersion,
+				sha256: template.agentConfigSha256 ?? null,
+				hostAgentConfigApiVersion: HOST_AGENT_CONFIG_API_VERSION,
+				templateDigest: record.templateDigest,
+				sourceRoot: template.sourceRoot
+			};
+			return this.contentHandle(version, this.holdLease(workspace.id));
+		});
+	}
+	contentHandle(version, release) {
+		let references = 0;
+		const drained = Promise.withResolvers();
+		this.contentDrains.add(drained.promise);
+		const retain = () => {
+			references++;
+			let released = false;
+			return Object.freeze({
+				...version,
+				retain: () => {
+					if (released || this.closed) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "The content activity is closed");
+					return retain();
+				},
+				release: () => {
+					if (released) return;
+					released = true;
+					if (--references === 0) {
+						release();
+						this.contentDrains.delete(drained.promise);
+						drained.resolve();
+					}
+				}
+			});
+		};
+		return retain();
+	}
+	async acquireOne(workspaceId) {
+		const record = [...this.records.values()].find((item) => item.workspaceId === workspaceId);
+		if (record === void 0 || !record.registered) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", `workspace ${workspaceId} is not an acquired bundle Workspace`);
+		if (record.journal.phase === "updating") throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", `workspace ${workspaceId} is updating`);
+		if ((this.leases.get(workspaceId)?.size ?? 0) === 0 && this.agentConfigSources.has(keyOf(record))) await this.ensureOne(record);
+		this.agentConfigSources.get(keyOf(record))?.assertExecutionAllowed();
+		return this.holdLease(workspaceId);
+	}
+	holdLease(workspaceId) {
+		const token = Symbol("workspace-bundle-lease");
+		let leases = this.leases.get(workspaceId);
+		if (leases === void 0) {
+			leases = /* @__PURE__ */ new Set();
+			this.leases.set(workspaceId, leases);
+		}
+		leases.add(token);
+		return () => {
+			leases.delete(token);
+			if (leases.size === 0) this.leases.delete(workspaceId);
+			const waiters = this.waiters.get(workspaceId);
+			if (waiters !== void 0) for (const waiter of waiters) waiter();
+		};
+	}
+	/** @inheritdoc */
+	record(identity) {
+		return this.records.get(keyOf(identity));
+	}
+	/** @inheritdoc */
+	pathOf(identity) {
+		identityOf(identity.bundleId, identity.workspaceKey);
+		return bundledDirectory(this.spec.materializeRoot, identity);
+	}
+	/**
+	* Replay an interrupted journal before serving the Workspace.
+	* @param identity - branded pair.
+	* @throws {WorkspaceBundleError} Before any rename or deletion if stored paths differ from this identity's controlled paths.
+	* @throws {AgentConfigError} After physical recovery when committed content fails compatibility or consumer validation.
+	*/
+	async recover(identity) {
+		return this.enqueue(async () => {
+			const workspace = await this.recoverOne(identity);
+			const record = this.records.get(keyOf(identity));
+			await this.agentConfigSources.get(keyOf(identity))?.recover(record?.templateDigest, record?.pluginVersion, record?.agentConfigSha256);
+			return workspace;
+		});
+	}
+	enqueue(work) {
+		const run = this.chain.then(work, work);
+		this.chain = run.then(() => void 0, () => void 0);
+		return run;
+	}
+	async ensureOne(identity) {
+		let template = this.requireTemplate(identity);
+		const source = this.agentConfigSources.get(keyOf(identity));
+		const recovered = await this.recoverOne(identity);
+		const record = this.records.get(keyOf(identity));
+		if (source !== void 0) try {
+			template = await source.recover(record?.templateDigest, record?.pluginVersion, record?.agentConfigSha256);
+		} catch (error) {
+			if (!(error instanceof AgentConfigError) || record?.workspaceId !== null && record?.workspaceId !== void 0 && (this.leases.get(record.workspaceId)?.size ?? 0) > 0) throw error;
+			template = source.template();
+		}
+		if (source !== void 0 && (record?.workspaceId === null || record?.workspaceId === void 0 || (this.leases.get(record.workspaceId)?.size ?? 0) === 0)) template = source.template();
+		if (recovered !== void 0 && record !== void 0 && record.templateDigest === template.manifest.digest && record.pluginVersion === template.manifest.pluginVersion && (record.agentConfigSha256 ?? null) === journalAgentConfigSha256(template, this.requireTemplate(identity)) && record.journal.phase === "idle") return recovered;
+		try {
+			await source?.prepare(template);
+			const workspace = await this.replace(template, record, source === void 0 ? void 0 : () => source.assertApplicable(template));
+			await source?.committed(template);
+			return workspace;
+		} catch (error) {
+			if (source === void 0) throw error;
+			if (error instanceof AgentConfigError && error.code === "AGENT_CONFIG_SCOPE_CHANGED") await this.rollbackAgentConfig(identity, record);
+			else await this.recoverOne(identity);
+			const restored = this.records.get(keyOf(identity));
+			await source.recover(restored?.templateDigest, restored?.pluginVersion, restored?.agentConfigSha256);
+			source.failedApply(template, error);
+			if (error instanceof AgentConfigError && error.code === "AGENT_CONFIG_SCOPE_CHANGED" && !this.closed) return (restored === void 0 || !await this.fs.exists(this.pathOf(identity)) ? void 0 : await this.workspaceOf(restored)) ?? this.replace(this.requireTemplate(identity), restored);
+			this.ctx.logger.warn("Agent 配置应用失败，已尝试按 journal 恢复；当前版本未确认。");
+			throw error;
+		}
+	}
+	async rollbackAgentConfig(identity, previous) {
+		const current = this.records.get(keyOf(identity));
+		if (current === void 0) {
+			await this.fs.rm(this.stagingOf(identity), { recursive: true });
+			return;
+		}
+		if (current === previous && current.journal.phase === "idle") {
+			await this.fs.rm(this.stagingOf(identity), { recursive: true });
+			return;
+		}
+		const builtin = this.requireTemplate(identity);
+		const rollback = {
+			...previous ?? {
+				...current,
+				pluginVersion: builtin.manifest.pluginVersion,
+				templateDigest: brandString("0".repeat(64)),
+				agentConfigSha256: null
+			},
+			journal: {
+				...current.journal,
+				phase: "updating",
+				fromDigest: previous?.templateDigest ?? null,
+				toDigest: current.templateDigest,
+				backupPath: await this.fs.exists(this.backupOf(identity)) ? this.backupOf(identity) : null,
+				stagingPath: this.stagingOf(identity),
+				swapComplete: false
+			}
+		};
+		this.records.set(keyOf(identity), rollback);
+		await writeRecord(this.fs, this.recordFile(identity), rollback);
+		await this.restoreOld(identity, rollback);
+	}
+	requireTemplate(identity) {
+		const template = this.templates.get(keyOf(identity));
+		if (template === void 0) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", `${keyOf(identity)} is not registered`);
+		return template;
+	}
+	stagingOf(identity) {
+		return `${this.pathOf(identity)}.staging`;
+	}
+	backupOf(identity) {
+		return `${this.pathOf(identity)}.backup`;
+	}
+	recordFile(identity) {
+		return recordPath(this.spec.journalRoot, identity);
+	}
+	async loadStored(identity) {
+		const stored = await readRecord(this.fs, this.recordFile(identity));
+		if (stored !== void 0) this.records.set(keyOf(identity), stored);
+		return stored;
+	}
+	async recoverOne(identity) {
+		const stored = this.records.get(keyOf(identity)) ?? await this.loadStored(identity);
+		if (stored === void 0) return void 0;
+		await assertRecordPaths(this.fs, stored, this.pathOf(identity));
+		if (stored.journal.phase === "idle") return this.workspaceOf(stored);
+		return stored.journal.swapComplete ? this.finishNew(identity, stored) : this.restoreOld(identity, stored);
+	}
+	async workspaceOf(record) {
+		if (record.workspaceId === null) return void 0;
+		return this.ctx.workspaceRegistry.get(record.workspaceId) ?? await this.ctx.workspaceRegistry.create(record.path, void 0, originOf({
+			bundleId: record.bundleId,
+			workspaceKey: record.workspaceKey
+		}));
+	}
+	async restoreOld(identity, record) {
+		const root = this.pathOf(identity);
+		const backup = record.journal.backupPath ?? this.backupOf(identity);
+		const staging = record.journal.stagingPath ?? this.stagingOf(identity);
+		if (await this.fs.exists(backup)) {
+			if (await this.fs.exists(root)) await this.fs.rm(root, { recursive: true });
+			await this.fs.rename(backup, root);
+		} else if (record.journal.fromDigest === null && await this.fs.exists(root)) await this.fs.rm(root, { recursive: true });
+		if (await this.fs.exists(staging)) await this.fs.rm(staging, { recursive: true });
+		const next = {
+			...record,
+			journal: idleJournal(),
+			lastFailure: record.lastFailure
+		};
+		await writeRecord(this.fs, this.recordFile(identity), next);
+		this.records.set(keyOf(identity), next);
+		return this.workspaceOf(next);
+	}
+	async finishNew(identity, record) {
+		let template = this.templates.get(keyOf(identity));
+		const root = this.pathOf(identity);
+		const toDigest = record.journal.toDigest;
+		try {
+			const source = this.agentConfigSources.get(keyOf(identity));
+			if (source !== void 0 && toDigest !== null) template = await source.recoverPhysical(toDigest, record.journal.pluginVersion ?? void 0, record.journal.agentConfigSha256);
+			if (template !== void 0 && toDigest === template.manifest.digest) {
+				await verifyTemplateTree(this.fs, root, template.manifest);
+				return await this.commit(identity, record, template);
+			}
+			if (toDigest !== null && template === void 0) {
+				const cached = bundledDirectory(this.spec.templateCacheRoot, identity);
+				const manifest = await loadVerifiedManifest(this.fs, cached);
+				if (manifest.digest === toDigest) {
+					await verifyTemplateTree(this.fs, root, manifest);
+					const synthetic = {
+						bundleId: identity.bundleId,
+						workspaceKey: identity.workspaceKey,
+						title: "Workspace",
+						sourceRoot: cached,
+						manifest
+					};
+					return await this.commit(identity, record, synthetic);
+				}
+			}
+		} catch (error) {}
+		return this.restoreOld(identity, record);
+	}
+	async replace(template, existing, assertApplicable) {
+		const identity = identityOf(template.bundleId, template.workspaceKey);
+		assertApplicable?.();
+		await loadVerifiedManifest(this.fs, template.sourceRoot);
+		const cache = bundledDirectory(this.spec.templateCacheRoot, identity);
+		await copyTree(this.fs, template.sourceRoot, cache, [...template.manifest.files, { path: "manifest.json" }]);
+		const staging = this.stagingOf(identity);
+		await copyTree(this.fs, template.sourceRoot, staging, template.manifest.files);
+		assertApplicable?.();
+		this.fs.crash("after-staging");
+		const root = this.pathOf(identity);
+		const backup = this.backupOf(identity);
+		await this.prepareBackup(backup);
+		if (await this.fs.exists(backup)) await this.fs.rm(backup, { recursive: true });
+		const record = existing ?? {
+			version: 1,
+			bundleId: identity.bundleId,
+			workspaceKey: identity.workspaceKey,
+			workspaceId: null,
+			path: root,
+			pluginVersion: template.manifest.pluginVersion,
+			templateDigest: brandString("0".repeat(64)),
+			registered: true,
+			journal: idleJournal(),
+			lastFailure: null
+		};
+		const journal = {
+			phase: "updating",
+			fromDigest: existing?.templateDigest ?? null,
+			toDigest: template.manifest.digest,
+			pluginVersion: template.manifest.pluginVersion,
+			stagingPath: staging,
+			backupPath: await this.fs.exists(root) ? backup : null,
+			swapComplete: false,
+			agentConfigSha256: journalAgentConfigSha256(template, this.requireTemplate(identity))
+		};
+		const updating = await writeJournal(this.fs, this.recordFile(identity), {
+			...record,
+			registered: true,
+			path: root
+		}, journal);
+		this.records.set(keyOf(identity), updating);
+		this.fs.crash("after-journal-updating");
+		if (updating.workspaceId !== null) await this.ctx.serial("workspace-bundle/quiesce", updating.workspaceId);
+		await this.quiesce(updating.workspaceId);
+		assertApplicable?.();
+		this.fs.crash("after-quiesce");
+		await this.fs.mkdir(join(root, ".."));
+		if (await this.fs.exists(root)) {
+			if (await this.fs.exists(backup)) await this.fs.rm(backup, { recursive: true });
+			await this.fs.rename(root, backup);
+		}
+		this.fs.crash("after-rename-backup");
+		assertApplicable?.();
+		await this.fs.rename(staging, root);
+		const swapped = await writeJournal(this.fs, this.recordFile(identity), updating, {
+			...journal,
+			swapComplete: true,
+			stagingPath: null
+		});
+		this.records.set(keyOf(identity), swapped);
+		this.fs.crash("after-rename-staging");
+		await verifyTemplateTree(this.fs, root, template.manifest);
+		this.fs.crash("after-verify");
+		assertApplicable?.();
+		const workspace = await this.commit(identity, swapped, template);
+		assertApplicable?.();
+		this.fs.crash("after-journal-commit");
+		this.scheduleRecycle(backup);
+		return workspace;
+	}
+	async commit(identity, record, template) {
+		const workspace = await this.ctx.workspaceRegistry.create(record.path, template.title, originOf(identity));
+		const next = committedRecord({
+			...record,
+			workspaceId: workspace.id,
+			path: workspace.path,
+			registered: true,
+			agentConfigSha256: journalAgentConfigSha256(template, this.templates.get(keyOf(identity)))
+		}, template.manifest.digest, template.manifest.pluginVersion);
+		await writeRecord(this.fs, this.recordFile(identity), next);
+		this.records.set(keyOf(identity), next);
+		return workspace;
+	}
+	async quiesce(workspaceId) {
+		if (workspaceId === null) return;
+		const deadline = Date.now() + this.spec.quiesceTimeoutMs;
+		while ((this.leases.get(workspaceId)?.size ?? 0) > 0) {
+			if (Date.now() >= deadline) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_QUIESCE_TIMEOUT", `workspace ${workspaceId} still has active leases`);
+			await new Promise((resolve) => {
+				let waiters = this.waiters.get(workspaceId);
+				if (waiters === void 0) {
+					waiters = /* @__PURE__ */ new Set();
+					this.waiters.set(workspaceId, waiters);
+				}
+				const timer = setTimeout(resolve, 25);
+				const waiter = () => {
+					clearTimeout(timer);
+					waiters.delete(waiter);
+					resolve();
+				};
+				waiters.add(waiter);
+			});
+		}
+	}
+	scheduleRecycle(backup) {
+		if (this.closed) return;
+		const timer = setTimeout(() => {
+			this.recycle.delete(backup);
+			const work = this.fs.rm(backup, { recursive: true }).catch((error) => {
+				this.ctx.logger.warn("旧 Workspace 备份清理失败，请检查磁盘；当前版本保持可用。");
+			}).finally(() => {
+				this.recycleWork.delete(backup);
+			});
+			this.recycleWork.set(backup, work);
+		}, this.spec.recycleTimeoutMs);
+		this.recycle.set(backup, timer);
+	}
+	async prepareBackup(backup) {
+		const timer = this.recycle.get(backup);
+		if (timer !== void 0) clearTimeout(timer);
+		this.recycle.delete(backup);
+		await this.recycleWork.get(backup);
+	}
+};
+//#endregion
+//#region lib/types/session-events.js
+/**
+* 在每个 Session 首次使用一个不同 Agent 配置版本的 turn 写入身份，重复 step 不重复记录。
+* @param session - 即将请求模型的 Session。
+* @param current - 当前租约固定的完整版本。
+*/
+function recordWorkspaceAgentConfigVersion(session, current) {
+	const previous = session.snapshotEvents().findLast((event) => event.type === "workspace-bundle/agent-config-version");
+	if (previous?.type === "workspace-bundle/agent-config-version" && previous.data.version === current.version && previous.data.agentConfigSha256 === current.sha256 && previous.data.templateDigest === current.templateDigest) return;
+	session.append("workspace-bundle/agent-config-version", {
+		workspaceKind: current.workspaceKind,
+		version: current.version,
+		previousVersion: previous?.type === "workspace-bundle/agent-config-version" ? previous.data.version : null,
+		templateDigest: current.templateDigest,
+		agentConfigSha256: current.sha256,
+		hostAgentConfigApiVersion: current.hostAgentConfigApiVersion
+	});
+}
+//#endregion
+//#region lib/types/agent-config-contract/ids.js
+/**
+* Branded identifiers. Each is a UUID string; the brand keeps ids of different entities apart at compile time.
+* @module
+*/
+/** Identifier of a user. */
+const UserId = z.uuid().brand();
+/** Identifier of a tenant. */
+const TenantId = z.uuid().brand();
+z.uuid().brand();
+z.uuid().brand();
+z.uuid().brand();
+z.uuid().brand();
+z.uuid().brand();
+z.uuid().brand();
+z.uuid().brand();
+z.uuid().brand();
+z.uuid().brand();
+z.uuid().brand();
+z.uuid().brand();
+z.uuid().brand();
+z.uuid().brand();
+//#endregion
+//#region lib/types/agent-config-contract/cs-hosting.js
+/** 客服托管权、租约与运行状态检查点契约。子账号归属使用本服务 UserId。 @module */
+/** 旺旺账号的稳定、不透明标识；不作昵称或大小写归一化。 */
+const WangwangAccountId = z.string().min(1).max(200).brand();
+/** 本机安装标识，由 Host 产生并持久保存。 */
+const InstallationId = z.uuid().brand();
+/** 云端沙箱标识，不限定执行器的标识格式。 */
+const SandboxId = z.string().min(1).max(200).brand();
+/** 持有者种类参与匹配，相同文本的安装与沙箱不是同一持有者。 */
+const HostingHolder = z.discriminatedUnion("kind", [z.object({
+	kind: z.literal("installation"),
+	id: InstallationId
+}), z.object({
+	kind: z.literal("sandbox"),
+	id: SandboxId
+})]).meta({ id: "HostingHolder" });
+/** 单调递增的 CAS 代次，JSON 安全整数。 */
+const HostingEpoch = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+z.object({
+	tenantId: TenantId,
+	userId: UserId,
+	accountId: WangwangAccountId
+});
+z.strictObject({});
+/** 未开通不保存记录，调用方按本地既有行为继续运行。 */
+const HostingNotEnabled = z.object({
+	cloudEnabled: z.literal(false),
+	serverTime: z.iso.datetime()
+}).meta({ id: "HostingNotEnabled" });
+/** 有效性以 serverTime 为准；到期记录保留持有者与 epoch 供 CAS 接管。 */
+const HostingEnabled = z.object({
+	cloudEnabled: z.literal(true),
+	holder: HostingHolder.nullable(),
+	epoch: HostingEpoch,
+	state: z.enum([
+		"unheld",
+		"active",
+		"expired"
+	]),
+	leaseExpiresAt: z.iso.datetime().nullable(),
+	remainingSeconds: z.number().int().nonnegative(),
+	serverTime: z.iso.datetime(),
+	updatedAt: z.iso.datetime()
+}).meta({ id: "HostingEnabled" });
+const HostingLeaseResponse = z.discriminatedUnion("cloudEnabled", [HostingNotEnabled, HostingEnabled]).meta({ id: "HostingLeaseResponse" });
+z.strictObject({
+	holder: HostingHolder,
+	expectedEpoch: HostingEpoch
+}).meta({ id: "AcquireHostingLeaseRequest" });
+z.strictObject({ holder: z.strictObject({
+	kind: z.literal("sandbox"),
+	id: SandboxId
+}) }).meta({ id: "FirstEnableHostingLeaseRequest" });
+z.strictObject({
+	holder: HostingHolder,
+	epoch: HostingEpoch
+}).meta({ id: "HostingLeaseOwnerRequest" }).extend({ target: HostingHolder }).meta({ id: "HandoffHostingLeaseRequest" });
+const problems = {
+	503: ["SERVICE_UNAVAILABLE"],
+	401: ["SESSION_REQUIRED", "SESSION_EXPIRED"],
+	403: [
+		"NO_CURRENT_TENANT",
+		"NOT_A_MEMBER",
+		"HOSTING_UNAVAILABLE",
+		"HOSTING_USER_MISMATCH"
+	],
+	409: [
+		"TENANT_NOT_CURRENT",
+		"HOSTING_EPOCH_MISMATCH",
+		"HOSTING_HELD",
+		"HOSTING_HOLDER_MISMATCH",
+		"HOSTING_LEASE_EXPIRED"
+	]
+};
+const responses = { 200: {
+	description: "托管权状态；未开通的操作同样返回 cloudEnabled=false，不创建记录",
+	schema: HostingLeaseResponse,
+	headers: { "Cache-Control": {
+		description: "租约状态不得缓存",
+		schema: z.literal("no-store")
+	} }
+} };
+responses[200].headers;
+z.literal("no-store");
+responses[200].headers;
+({ ...problems }), [...problems[409]];
+({ ...problems }), [...problems[403]];
+responses[200].headers;
+({ ...problems }), [...problems[403]], [...problems[409]];
+({ ...problems }), [...problems[409]];
+const whitespace = /\s/u;
+/** 不透明令牌：非空，且不含空白或 ASCII 控制字符。 */
+function opaqueText(value) {
+	if (whitespace.test(value)) return false;
+	for (const char of value) {
+		const code = char.codePointAt(0) ?? 0;
+		if (code < 32 || code === 127) return false;
+	}
+	return true;
+}
+const opaque = (max) => z.string().min(1).max(max).refine(opaqueText);
+const count = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+/** 一条消息流的不透明游标。同一次上报里 streamId 不可重复，不含消息正文。 */
+const HostingStreamCursor = z.strictObject({
+	streamId: opaque(200),
+	cursor: opaque(1024)
+}).meta({ id: "HostingStreamCursor" });
+/** 各消息流游标，最多 64 条。 */
+const HostingStreamCursors = z.array(HostingStreamCursor).max(64).superRefine((items, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	items.forEach((item, index) => {
+		if (!seen.has(item.streamId)) {
+			seen.add(item.streamId);
+			return;
+		}
+		ctx.addIssue({
+			code: "custom",
+			path: [index, "streamId"],
+			message: "Duplicate stream"
+		});
+	});
+});
+/** 已提交事件的 sha256，不是正文摘要。 */
+const HostingCheckpointSession = z.strictObject({
+	id: opaque(200),
+	eventCount: count,
+	digest: z.string().regex(/^[a-f0-9]{64}$/)
+}).meta({ id: "HostingCheckpointSession" });
+/** running 正在自动接待，draining 正在排空，stopped 已停止自动接待，unavailable 无法确认仍在接待。 */
+const HostingCheckpointStatus = z.enum([
+	"running",
+	"draining",
+	"stopped",
+	"unavailable"
+]).meta({ id: "HostingCheckpointStatus" });
+const hostVersion = z.string().regex(/^[0-9A-Za-z][0-9A-Za-z.+_-]{0,99}$/);
+/** 规范 SemVer 2.0，最多 200 字符，保留预发布和构建元数据，不接受前缀或空白。 */
+const AgentConfigSemver = z.string().max(200).regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?(?![\s\S])/);
+/** 与 Host Agent 配置错误分类对齐；查询失败与作用域变化不计采用拒绝。 */
+const AgentConfigErrorCode = z.enum([
+	"AGENT_CONFIG_INCOMPATIBLE",
+	"AGENT_CONFIG_DIGEST_MISMATCH",
+	"AGENT_CONFIG_INVALID",
+	"AGENT_CONFIG_DOWNLOAD_FAILED",
+	"AGENT_CONFIG_APPLY_FAILED",
+	"AGENT_CONFIG_QUERY_FAILED",
+	"AGENT_CONFIG_SCOPE_CHANGED"
+]).meta({ id: "AgentConfigErrorCode" });
+/** 仅包含固定码与已知时的被拒版本，不包含消息、路径、URL 或凭据。 */
+const AgentConfigRejection = z.strictObject({
+	code: AgentConfigErrorCode,
+	version: AgentConfigSemver.optional()
+}).meta({ id: "AgentConfigRejection" });
+z.strictObject({
+	tenantId: TenantId,
+	userId: UserId,
+	accountId: WangwangAccountId,
+	epoch: HostingEpoch,
+	revision: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+	streamCursors: HostingStreamCursors,
+	session: HostingCheckpointSession.nullable(),
+	pendingCount: count,
+	unknownSendCount: count,
+	status: HostingCheckpointStatus,
+	hostVersion,
+	reportedAt: z.iso.datetime()
+}).meta({ id: "HostingCheckpoint" });
+z.strictObject({
+	/** 本地 Host 限制开启时必须提供；与模块名册的 hostId 相同。 */
+	holder: HostingHolder.optional(),
+	epoch: HostingEpoch,
+	expectedRevision: count,
+	streamCursors: HostingStreamCursors,
+	session: HostingCheckpointSession.nullable(),
+	pendingCount: count,
+	unknownSendCount: count,
+	status: HostingCheckpointStatus,
+	hostVersion,
+	/** Host 已经成功应用的 Agent 配置版本；未上报表示未知，不接受以分配版本代替。 */
+	agentConfigVersion: z.string().min(1).max(200).optional(),
+	/** Host 的 Agent 配置 API，独立于应用 hostVersion；缺失表示未知。 */
+	hostAgentConfigApiVersion: AgentConfigSemver.optional(),
+	/** 已提交内容是否禁止执行；缺失不代表 false。 */
+	agentConfigBlocked: z.boolean().optional(),
+	/** null 明确表示没有拒绝，缺失表示未上报；三个新字段齐全才构成完整观测。 */
+	agentConfigRejection: AgentConfigRejection.nullable().optional()
+}).meta({ id: "ReportHostingCheckpointRequest" });
+z.literal("no-store");
+const checkpointProblems = {
+	503: ["SERVICE_UNAVAILABLE"],
+	401: ["SESSION_REQUIRED", "SESSION_EXPIRED"],
+	403: [
+		"NO_CURRENT_TENANT",
+		"NOT_A_MEMBER",
+		"HOSTING_UNAVAILABLE",
+		"HOSTING_USER_MISMATCH"
+	],
+	409: ["TENANT_NOT_CURRENT"]
+};
+({ ...checkpointProblems });
+({ ...checkpointProblems });
+//#endregion
+//#region lib/types/agent-config-contract/agent-configs.js
+/** 内置 workspace Agent 配置：查询本人当前店铺租户的分配，兼容性由 Host 检查。 @module */
+/** 可扩展的内置 workspace 种类；首个种类为 cs-hosting。 */
+const WorkspaceKind = z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/).max(80).meta({ id: "WorkspaceKind" });
+/** Agent 配置登记的完整元数据；sha256 来自经 PR 审阅的规则文件。 */
+const AgentConfig = z.object({
+	workspaceKind: WorkspaceKind,
+	version: z.string().min(1),
+	sha256: z.string().regex(/^[a-f0-9]{64}$/),
+	sizeBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+	downloadUrl: z.url({ protocol: /^https$/ }),
+	hostContentApiRange: z.string().min(1),
+	releaseNotes: z.string().min(1).max(2e4)
+}).meta({ id: "AgentConfig" });
+/** builtin 表示没有分配：已有下载版本时保留当前版本，从未下载时使用安装包内置版本。 */
+const AgentConfigAssignment = z.discriminatedUnion("source", [z.object({
+	source: z.literal("builtin"),
+	tenantId: TenantId,
+	userId: UserId,
+	workspaceKind: WorkspaceKind
+}), z.object({
+	source: z.literal("registry"),
+	tenantId: TenantId,
+	userId: UserId,
+	workspaceKind: WorkspaceKind,
+	agentConfig: AgentConfig
+})]).meta({ id: "AgentConfigAssignment" });
+/** 路径中的租户必须是会话当前租户；用户由会话确定，不接受调用方指定。 */
+const AgentConfigParams = z.object({
+	tenantId: TenantId,
+	workspaceKind: WorkspaceKind
+}).meta({ id: "AgentConfigParams" });
+/** Host 在启动和轮询时查询；不按版本大小排序，回退可返回更低版本；服务不可达时保留当前版本。 */
+const getAgentConfigAssignment = {
+	method: "get",
+	path: "/v1/tenants/{tenantId}/agent-configs/{workspaceKind}",
+	summary: "查询本人内置 workspace Agent 配置分配",
+	auth: "tenant",
+	request: {
+		params: AgentConfigParams,
+		query: z.strictObject({})
+	},
+	responses: { 200: {
+		description: "分配版本或使用内置版本；Host 检查兼容范围并核对下载字节的 sha256",
+		schema: AgentConfigAssignment,
+		headers: { "Cache-Control": {
+			description: "每次读取当前分配，及时观察回退",
+			schema: z.literal("no-store")
+		} }
+	} },
+	problems: {
+		401: ["SESSION_REQUIRED", "SESSION_EXPIRED"],
+		403: [
+			"NO_CURRENT_TENANT",
+			"NOT_A_MEMBER",
+			"AGENT_CONFIGS_UNAVAILABLE"
+		],
+		409: ["TENANT_NOT_CURRENT"]
+	}
+};
+/** 双模块观测与控制仅支持已实现的模块；不设默认种类。 */
+const AgentConfigModule = z.enum(["cs-hosting", "resource-intake"]).meta({ id: "AgentConfigModule" });
+const AgentConfigDigest = z.string().regex(/^[a-f0-9]{64}$/);
+const sequence$1 = z.number().int().min(1).max(Number.MAX_SAFE_INTEGER);
+const generation = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+/** 完整身份包括 build metadata；builtin 没有远端归档摘要。 */
+const AgentConfigCommitted = z.discriminatedUnion("source", [z.strictObject({
+	source: z.literal("builtin"),
+	version: AgentConfigSemver,
+	sha256: z.null()
+}), z.strictObject({
+	source: z.literal("registry"),
+	version: AgentConfigSemver,
+	sha256: AgentConfigDigest
+})]).meta({ id: "AgentConfigCommitted" });
+const AgentConfigTarget = z.strictObject({
+	version: AgentConfigSemver,
+	sha256: AgentConfigDigest
+}).meta({ id: "AgentConfigTarget" });
+/** 已提交版本恢复/采用的独立阻断原因；不随候选目标拒绝变化，不含诊断正文。 */
+const AgentConfigBlockingFailure = z.strictObject({
+	code: AgentConfigErrorCode,
+	committed: AgentConfigCommitted
+}).meta({ id: "AgentConfigBlockingFailure" });
+/** 固定码与精确目标归因；查询失败不能作为采用拒绝。 */
+const ModuleAgentConfigSnapshot = z.strictObject({
+	hostAgentConfigApiVersion: AgentConfigSemver,
+	runtimeApiVersion: AgentConfigSemver.nullable(),
+	current: AgentConfigCommitted,
+	pending: AgentConfigTarget.nullable(),
+	blocked: z.boolean(),
+	lastRejection: z.strictObject({
+		code: AgentConfigErrorCode,
+		target: AgentConfigTarget.nullable()
+	}).nullable(),
+	blockingFailure: AgentConfigBlockingFailure.nullable().optional()
+}).meta({ id: "ModuleAgentConfigSnapshot" });
+/** 服务端从当前有效 sandbox 会话和活动 placement key 解析的绑定；不是调用方可指定的身份。 */
+const AgentConfigSandboxBinding = z.strictObject({
+	sandboxId: z.uuid(),
+	instanceId: z.string().min(1).max(200),
+	sandboxGeneration: generation
+}).meta({ id: "AgentConfigSandboxBinding" });
+/** 云端读回只要求现有 sandbox/instance 配置；代次由服务端提供。 */
+const ReadAgentConfigSandboxHostQuery = AgentConfigSandboxBinding.pick({
+	sandboxId: true,
+	instanceId: true
+}).meta({ id: "ReadAgentConfigSandboxHostQuery" });
+/** 外层绑定为本次认证的当前实例；内层为已存注册，可来自旧实例。null 表示尚无注册。 */
+const AgentConfigSandboxHostReadback = z.strictObject({
+	tenantId: TenantId,
+	userId: UserId,
+	workspaceKind: AgentConfigModule,
+	sandboxBinding: AgentConfigSandboxBinding,
+	registration: z.strictObject({
+		hostId: z.uuid(),
+		generation: sequence$1,
+		bootSequence: sequence$1,
+		sandboxBinding: AgentConfigSandboxBinding
+	}).nullable()
+}).meta({ id: "AgentConfigSandboxHostReadback" });
+/** bootSequence 随 device 持久递增；sandbox 丢失状态时先在本地锁内读回，再携带绑定与明确代次 CAS，不盲目重试。 */
+const RegisterAgentConfigHostRequest = z.strictObject({
+	hostId: z.uuid(),
+	bootId: z.uuid(),
+	requestId: z.uuid(),
+	bootSequence: sequence$1,
+	expectedGeneration: generation,
+	explicitActivation: z.boolean().optional(),
+	sandboxBinding: AgentConfigSandboxBinding.optional()
+}).meta({ id: "RegisterAgentConfigHostRequest" });
+const AgentConfigHostRegistration = z.strictObject({
+	workspaceKind: AgentConfigModule,
+	hostId: z.uuid(),
+	generation: sequence$1,
+	holder: z.strictObject({
+		kind: z.enum(["installation", "sandbox"]),
+		id: z.uuid()
+	})
+}).meta({ id: "AgentConfigHostRegistration" });
+const ReportAgentConfigHostRequest = ModuleAgentConfigSnapshot.extend({
+	generation: sequence$1,
+	sequence: sequence$1
+}).meta({ id: "ReportAgentConfigHostRequest" });
+const AgentConfigHostReceipt = z.strictObject({
+	generation: sequence$1,
+	sequence: sequence$1,
+	reportedAt: z.iso.datetime()
+}).meta({ id: "AgentConfigHostReceipt" });
+const hostProblems = {
+	401: ["SESSION_REQUIRED", "SESSION_EXPIRED"],
+	403: [
+		"NO_CURRENT_TENANT",
+		"NOT_A_MEMBER",
+		"AGENT_CONFIGS_UNAVAILABLE",
+		"SANDBOX_SESSION_UNBOUND"
+	],
+	404: ["NOT_FOUND"],
+	409: [
+		"TENANT_NOT_CURRENT",
+		"VERSION_CONFLICT",
+		"OPERATION_CONFLICT",
+		"LOCAL_HOST_REPLACED"
+	],
+	503: ["SERVICE_UNAVAILABLE"]
+};
+const hostHeaders = { "Cache-Control": {
+	description: "观测与回执不得缓存",
+	schema: z.literal("no-store")
+} };
+const getAgentConfigSandboxHost = {
+	method: "get",
+	path: "/v1/tenants/{tenantId}/agent-configs/{workspaceKind}/hosts/current",
+	summary: "只读本人当前沙箱模块 Host 注册，不允许本机安装调用",
+	auth: "tenant",
+	request: {
+		params: AgentConfigParams,
+		query: ReadAgentConfigSandboxHostQuery
+	},
+	responses: { 200: {
+		description: "sandboxId/instanceId 须匹配当前已认证 sandbox；返回服务端代次及已存注册，读回不授予业务权限，重新注册须携带完整 sandboxBinding 和明确 expectedGeneration",
+		schema: AgentConfigSandboxHostReadback,
+		headers: hostHeaders
+	} },
+	problems: hostProblems
+};
+const registerAgentConfigHost = {
+	method: "post",
+	path: "/v1/tenants/{tenantId}/agent-configs/{workspaceKind}/hosts/register",
+	summary: "注册本人模块 Host 运行，不取得业务写权限",
+	auth: "tenant",
+	request: {
+		params: AgentConfigParams,
+		body: RegisterAgentConfigHostRequest
+	},
+	responses: { 200: {
+		description: "服务端绑定 holder；提供 sandboxBinding 时须在事务内匹配当前 sandbox/instance/代次，installation 不接受该字段；新运行以 bootSequence 和 expectedGeneration 比较更新，旧运行不可复活",
+		schema: AgentConfigHostRegistration,
+		headers: hostHeaders
+	} },
+	problems: hostProblems
+};
+const reportAgentConfigHost = {
+	method: "put",
+	path: "/v1/tenants/{tenantId}/agent-configs/{workspaceKind}/hosts/{hostId}/observation",
+	summary: "上报本人模块 Host 的完整采用快照",
+	auth: "tenant",
+	request: {
+		params: AgentConfigParams.extend({ hostId: z.uuid() }),
+		body: ReportAgentConfigHostRequest
+	},
+	responses: { 200: {
+		description: "同序同内容返回原接收时间，同序异内容或旧代次冲突；时间由服务端确定",
+		schema: AgentConfigHostReceipt,
+		headers: hostHeaders
+	} },
+	problems: hostProblems
+};
+/** 仅新模块契约暴露可选runtime要求；旧assignment显式投影原AgentConfig。 */
+const ModuleAgentConfigMetadata = AgentConfig.extend({ runtimeApiRange: z.string().min(1).optional() }).meta({ id: "ModuleAgentConfigMetadata" });
+const ModuleAgentConfigAssignment = z.discriminatedUnion("source", [z.object({
+	source: z.literal("builtin"),
+	tenantId: TenantId,
+	userId: UserId,
+	workspaceKind: AgentConfigModule
+}), z.object({
+	source: z.literal("registry"),
+	tenantId: TenantId,
+	userId: UserId,
+	workspaceKind: AgentConfigModule,
+	agentConfig: ModuleAgentConfigMetadata
+})]).meta({ id: "ModuleAgentConfigAssignment" });
+const getModuleAgentConfigAssignment = {
+	...getAgentConfigAssignment,
+	path: "/v1/tenants/{tenantId}/agent-configs/{workspaceKind}/module",
+	summary: "查询显式模块分配与runtime要求",
+	responses: { 200: {
+		...getAgentConfigAssignment.responses[200],
+		schema: ModuleAgentConfigAssignment
+	} },
+	problems: hostProblems
+};
+//#endregion
+//#region lib/types/agent-config-observation.js
+const sequence = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const ScopeState = z.strictObject({
+	generation: sequence,
+	replaced: z.boolean().optional(),
+	running: z.strictObject({
+		bootId: z.uuid(),
+		bootSequence: sequence,
+		sequence
+	}).nullable(),
+	pendingRegistration: RegisterAgentConfigHostRequest.nullable(),
+	pendingReport: ReportAgentConfigHostRequest.nullable()
+});
+const State = z.strictObject({
+	version: z.literal(1),
+	hostId: z.uuid(),
+	bootSequence: sequence,
+	scopes: z.record(z.string().regex(/^[a-f0-9]{64}$/u), ScopeState)
+});
+function sameSandbox(left, right) {
+	return left?.sandboxId === right.sandboxId && left.instanceId === right.instanceId && left.sandboxGeneration === right.sandboxGeneration;
+}
+var ObservationError = class extends Error {
+	code;
+	constructor(code) {
+		super(code);
+		this.code = code;
+	}
+};
+/**
+* Build the observation owner when its source is registered; the server owns holder attestation.
+* @param ctx - authenticated merchant transport and scope-change events.
+* @param options - module identity, private persistent directory and resolved scheduling limits.
+* @returns factory bound to the source's actual committed state.
+*/
+function agentConfigHostObservation(ctx, options) {
+	return (read) => new ModuleHostObservation(ctx, options, read);
+}
+/**
+* Cloud-only factory; importing this export rejects older packages that cannot enforce sandbox identity.
+* @param ctx - Authenticated merchant transport and scope-change events.
+* @param options - Required sandbox deployment identity and private reporter settings.
+* @returns factory whose registrations require authenticated sandbox readback.
+*/
+function sandboxAgentConfigHostObservation(ctx, options) {
+	return (read) => new ModuleHostObservation(ctx, options, read);
+}
+var ModuleHostObservation = class {
+	ctx;
+	options;
+	read;
+	lifetime = new AbortController();
+	active;
+	run;
+	stopped;
+	chain = Promise.resolve();
+	timer;
+	stopScope;
+	stopActivation;
+	stopActivated;
+	preparedRevision;
+	preparedHostId;
+	activationRequest = false;
+	stopReplacement;
+	migrated = /* @__PURE__ */ new Set();
+	member() {
+		return this.ctx.merchantAccount.captureIdentity()?.identity;
+	}
+	get replaced() {
+		if (this.options.sandbox !== void 0) return false;
+		const member = this.member();
+		return member !== void 0 && this.options.replacementState.isReplaced(member);
+	}
+	stopIdentity;
+	hostId() {
+		return typeof this.options.hostId === "function" ? this.options.hostId() : this.options.hostId;
+	}
+	constructor(ctx, options, read) {
+		this.ctx = ctx;
+		this.options = options;
+		this.read = read;
+		this.stopReplacement = options.sandbox === void 0 ? options.replacementState.subscribe(() => {
+			if (!this.replaced) return;
+			if (!this.activationRequest) this.active?.abort();
+			this.options.onReplaced?.(this.hostId());
+			this.refresh();
+		}) : () => {};
+		this.stopScope = ctx.on("merchant-account/scope-changed", () => {
+			this.active?.abort();
+			this.refresh();
+		});
+		this.stopIdentity = options.sandbox === void 0 ? ctx.on("workspace-bundle/local-host-identity-changed", () => {
+			this.active?.abort();
+			this.stopped = void 0;
+			return this.refresh();
+		}) : () => {};
+		this.stopActivation = options.sandbox === void 0 ? ctx.on("workspace-bundle/activate-local-host", async (revision, registered) => {
+			await this.activate(revision);
+			registered.add(this.options.workspaceKind);
+		}) : () => {};
+		this.stopActivated = options.sandbox === void 0 ? ctx.on("workspace-bundle/local-host-activated", (revision) => {
+			if (this.preparedRevision !== revision || this.preparedHostId !== this.hostId()) return Promise.reject(new ObservationError("AGENT_CONFIG_HOST_UNAVAILABLE"));
+			const work = this.chain.then(() => this.report(revision, false, true));
+			this.chain = work.catch((error) => {});
+			return work;
+		}) : () => {};
+		this.cycle();
+	}
+	async cycle() {
+		await this.refresh();
+		if (this.lifetime.signal.aborted) return;
+		this.timer = setTimeout(() => {
+			this.cycle();
+		}, this.options.intervalMs);
+		this.timer.unref();
+	}
+	refresh() {
+		if (this.lifetime.signal.aborted) return this.chain;
+		const revision = this.ctx.merchantAccount.getScopeRevision();
+		this.chain = this.chain.then(() => this.report(revision)).catch((error) => {
+			if (this.lifetime.signal.aborted || revision !== this.ctx.merchantAccount.getScopeRevision()) return;
+			if (this.run !== void 0 && this.run.hostId !== this.hostId()) return;
+			const code = error instanceof LocalHostReplacementWriteError ? "LOCAL_HOST_REPLACEMENT_WRITE_FAILED" : error instanceof ObservationError ? error.code : "AGENT_CONFIG_HOST_STATE_INVALID";
+			if (code === "LOCAL_HOST_REPLACEMENT_WRITE_FAILED") {
+				this.ctx.logger.warn("workspace-bundle: %s replacement state could not be saved; reporting remains stopped; check disk space and directory permissions before retrying", this.options.workspaceKind);
+				return;
+			}
+			if (code !== "LOCAL_HOST_REPLACED" && code !== "AGENT_CONFIG_HOST_UNAVAILABLE" && this.run !== void 0) this.stopped = {
+				key: this.run.key,
+				revision
+			};
+			this.ctx.logger.warn("workspace-bundle: %s module observation failed (%s); %s", this.options.workspaceKind, code, code === "AGENT_CONFIG_HOST_UNAVAILABLE" ? "the exact pending request is retained for retry" : "reporting is stopped; restore matching Host state before restarting");
+		});
+		return this.chain;
+	}
+	activate(revision) {
+		if (this.lifetime.signal.aborted || revision !== this.ctx.merchantAccount.getScopeRevision()) return Promise.reject(new ObservationError("AGENT_CONFIG_HOST_UNAVAILABLE"));
+		const work = this.chain.then(() => this.report(revision, true));
+		this.chain = work.catch((error) => {});
+		return work;
+	}
+	scope(revision) {
+		const state = this.ctx.merchantAccount.getState();
+		const identity = state.status === "signed-in" ? state.identity : null;
+		const tenantId = identity?.currentTenantId;
+		if (identity === null || tenantId == null || !identity.memberships.some((member) => member.tenantId === tenantId && member.kind === "shop")) return void 0;
+		if (revision !== this.ctx.merchantAccount.getScopeRevision()) return void 0;
+		const userId = identity.user.id;
+		const key = createHash("sha256").update(JSON.stringify(this.options.sandbox === void 0 ? [
+			tenantId,
+			userId,
+			this.options.workspaceKind
+		] : [
+			this.member()?.serverOrigin,
+			tenantId,
+			userId,
+			this.options.workspaceKind,
+			this.options.sandbox.sandboxId,
+			this.options.sandbox.instanceId
+		])).digest("hex");
+		if (this.stopped?.key === key && this.stopped.revision === revision) return void 0;
+		if (this.run?.key !== key || this.run.revision !== revision || this.run.hostId !== this.hostId()) this.run = {
+			key,
+			tenantId,
+			userId,
+			revision,
+			hostId: this.hostId(),
+			bootId: brandString(randomUUID()),
+			started: false
+		};
+		return this.run;
+	}
+	current(run, signal) {
+		signal.throwIfAborted();
+		const state = this.ctx.merchantAccount.getState();
+		if (run.hostId !== this.hostId() || run.revision !== this.ctx.merchantAccount.getScopeRevision() || state.status !== "signed-in" || state.identity?.currentTenantId !== run.tenantId || state.identity.user.id !== run.userId) throw new ObservationError("AGENT_CONFIG_HOST_UNAVAILABLE");
+	}
+	async load(hostId) {
+		let text;
+		try {
+			text = await readFile(join(this.options.stateRoot, `agent-config-${this.options.workspaceKind}-${hostId}.json`), "utf8");
+		} catch (error) {
+			if (error.code !== "ENOENT") throw new ObservationError("AGENT_CONFIG_HOST_STATE_INVALID");
+			try {
+				text = await readFile(join(this.options.stateRoot, `agent-config-${this.options.workspaceKind}-host.json`), "utf8");
+			} catch (legacyError) {
+				if (legacyError.code !== "ENOENT") throw new ObservationError("AGENT_CONFIG_HOST_STATE_INVALID");
+				return {
+					version: 1,
+					hostId,
+					bootSequence: 0,
+					scopes: {}
+				};
+			}
+			if (State.parse(JSON.parse(text)).hostId !== hostId) return {
+				version: 1,
+				hostId,
+				bootSequence: 0,
+				scopes: {}
+			};
+		}
+		const parsed = State.safeParse(JSON.parse(text));
+		if (!parsed.success || parsed.data.hostId !== hostId) throw new ObservationError("AGENT_CONFIG_HOST_STATE_INVALID");
+		return parsed.data;
+	}
+	async migrate(run, member, explicitActivation) {
+		if (!explicitActivation && this.migrated.has(run.key)) return;
+		await mkdir(this.options.stateRoot, {
+			recursive: true,
+			mode: 448
+		});
+		const paths = (await readdir(this.options.stateRoot)).filter((path) => path.startsWith(`agent-config-${this.options.workspaceKind}-`) && path.endsWith(".json"));
+		const legacy = await Promise.all(paths.map(async (path) => ({
+			path,
+			state: State.parse(JSON.parse(await readFile(join(this.options.stateRoot, path), "utf8")))
+		})));
+		await this.options.replacementState.importLegacy(member, this.options.workspaceKind, legacy.some(({ state }) => state.scopes[run.key]?.replaced === true));
+		for (const { path, state } of legacy) {
+			const record = state.scopes[run.key];
+			if (record?.replaced === void 0) continue;
+			delete record.replaced;
+			await writeFileAtomic(join(this.options.stateRoot, path), JSON.stringify(state) + "\n", {
+				mode: 384,
+				dirMode: 448
+			});
+		}
+		this.migrated.add(run.key);
+	}
+	async save(state) {
+		await writeFileAtomic(join(this.options.stateRoot, `agent-config-${this.options.workspaceKind}-${state.hostId}.json`), JSON.stringify(state) + "\n", {
+			mode: 384,
+			dirMode: 448
+		});
+	}
+	async rememberReplacement(state, record, member) {
+		const saveModule = record.replaced !== true;
+		record.replaced = true;
+		const writes = await Promise.allSettled([saveModule ? this.save(state) : Promise.resolve(), this.options.replacementState.markReplaced(member)]);
+		for (const write of writes) if (write.status === "rejected") throw new LocalHostReplacementWriteError(write.reason);
+	}
+	failure(failure) {
+		if (failure.kind === "server" && failure.status === 409 && failure.code === "LOCAL_HOST_REPLACED") return new ObservationError(this.options.sandbox === void 0 ? "LOCAL_HOST_REPLACED" : "AGENT_CONFIG_HOST_PROTOCOL");
+		if (failure.kind === "server" && failure.status === 409 && failure.code === "VERSION_CONFLICT") return new ObservationError("AGENT_CONFIG_HOST_GENERATION_CONFLICT");
+		if (failure.kind === "contract") return new ObservationError("AGENT_CONFIG_HOST_PROTOCOL");
+		return new ObservationError(failure.kind === "server" && (failure.status === 409 || failure.status === 404) ? "AGENT_CONFIG_HOST_CONFLICT" : "AGENT_CONFIG_HOST_UNAVAILABLE");
+	}
+	async attestSandbox(state, record, run, signal) {
+		const expected = this.options.sandbox;
+		if (expected === void 0) return;
+		this.current(run, signal);
+		const result = await this.ctx.merchantAccount.request(getAgentConfigSandboxHost, {
+			params: {
+				tenantId: run.tenantId,
+				workspaceKind: this.options.workspaceKind
+			},
+			query: {
+				sandboxId: expected.sandboxId,
+				instanceId: expected.instanceId
+			},
+			tenantContextReload: "caller"
+		}, signal).catch(() => {
+			throw new ObservationError("AGENT_CONFIG_HOST_UNAVAILABLE");
+		});
+		this.current(run, signal);
+		if (!result.ok) throw this.failure(result.failure);
+		const value = result.value;
+		if (String(value.tenantId) !== run.tenantId || String(value.userId) !== run.userId || value.workspaceKind !== this.options.workspaceKind || value.sandboxBinding.sandboxId !== expected.sandboxId || value.sandboxBinding.instanceId !== expected.instanceId) throw new ObservationError("AGENT_CONFIG_HOST_PROTOCOL");
+		if (run.started && !sameSandbox(run.sandboxBinding, value.sandboxBinding)) throw new ObservationError("AGENT_CONFIG_HOST_CONFLICT");
+		run.sandboxBinding = value.sandboxBinding;
+		if (record.pendingRegistration !== null && !sameSandbox(record.pendingRegistration.sandboxBinding, value.sandboxBinding)) {
+			record.pendingRegistration = null;
+			record.pendingReport = null;
+			record.running = null;
+		}
+		if (run.started) return;
+		const registration = value.registration;
+		if (record.pendingReport !== null && (registration?.hostId !== run.hostId || registration.generation !== record.pendingReport.generation || !sameSandbox(registration.sandboxBinding, value.sandboxBinding))) record.pendingReport = null;
+		if (record.pendingRegistration === null) record.generation = registration?.generation ?? 0;
+		state.bootSequence = Math.max(state.bootSequence, registration?.bootSequence ?? 0);
+		await this.save(state);
+	}
+	async registration(state, record, run, signal) {
+		const body = record.pendingRegistration;
+		if (body === null) return;
+		if (this.options.sandbox !== void 0 && (run.sandboxBinding === void 0 || !sameSandbox(body.sandboxBinding, run.sandboxBinding))) throw new ObservationError("AGENT_CONFIG_HOST_PROTOCOL");
+		this.current(run, signal);
+		const response = await this.ctx.merchantAccount.request(registerAgentConfigHost, {
+			params: {
+				tenantId: run.tenantId,
+				workspaceKind: this.options.workspaceKind
+			},
+			body,
+			tenantContextReload: "caller"
+		}, signal).catch(() => {
+			throw new ObservationError("AGENT_CONFIG_HOST_UNAVAILABLE");
+		});
+		this.current(run, signal);
+		if (!response.ok) throw this.failure(response.failure);
+		const receipt = response.value;
+		if (receipt.workspaceKind !== this.options.workspaceKind || receipt.hostId !== run.hostId || receipt.generation !== body.expectedGeneration + 1 || receipt.holder.kind === "installation" && receipt.holder.id !== run.hostId || this.options.sandbox !== void 0 && (receipt.holder.kind !== "sandbox" || receipt.holder.id !== this.options.sandbox.sandboxId)) throw new ObservationError("AGENT_CONFIG_HOST_PROTOCOL");
+		run.holder = receipt.holder.kind;
+		record.generation = receipt.generation;
+		record.running = {
+			bootId: body.bootId,
+			bootSequence: body.bootSequence,
+			sequence: 0
+		};
+		record.pendingRegistration = null;
+		await this.save(state);
+	}
+	async observation(state, record, run, signal) {
+		const body = record.pendingReport;
+		if (body === null) return;
+		this.current(run, signal);
+		const response = await this.ctx.merchantAccount.request(reportAgentConfigHost, {
+			params: {
+				tenantId: run.tenantId,
+				workspaceKind: this.options.workspaceKind,
+				hostId: run.hostId
+			},
+			body,
+			tenantContextReload: "caller"
+		}, signal).catch(() => {
+			throw new ObservationError("AGENT_CONFIG_HOST_UNAVAILABLE");
+		});
+		this.current(run, signal);
+		if (!response.ok) throw this.failure(response.failure);
+		const receipt = response.value;
+		if (receipt.generation !== body.generation || receipt.sequence !== body.sequence || record.running === null) throw new ObservationError("AGENT_CONFIG_HOST_PROTOCOL");
+		record.running.sequence = receipt.sequence;
+		record.pendingReport = null;
+		await this.save(state);
+	}
+	/**
+	* Pending reports from an earlier run can be discarded on a generation conflict.
+	* Reporters without an explicit sandbox identity can also rebind a server-attested sandbox run.
+	* An explicitly bound live sandbox run stops on conflict.
+	* @returns whether the report was discarded and the run needs a new registration.
+	*/
+	async replay(state, record, run, signal) {
+		try {
+			await this.observation(state, record, run, signal);
+		} catch (error) {
+			if (!(error instanceof ObservationError) || error.code !== "AGENT_CONFIG_HOST_GENERATION_CONFLICT" || run.started && (this.options.sandbox !== void 0 || run.holder !== "sandbox")) throw error;
+			record.pendingReport = null;
+			if (run.started) {
+				run.bootId = brandString(randomUUID());
+				run.started = false;
+			}
+			await this.save(state);
+			return true;
+		}
+		return false;
+	}
+	snapshot() {
+		const state = this.read();
+		const rejected = state.lastRejection;
+		const current = state.current.sha256 === null ? {
+			source: "builtin",
+			version: state.current.version,
+			sha256: null
+		} : {
+			source: "registry",
+			version: state.current.version,
+			sha256: state.current.sha256
+		};
+		return ModuleAgentConfigSnapshot.parse({
+			hostAgentConfigApiVersion: HOST_AGENT_CONFIG_API_VERSION,
+			runtimeApiVersion: this.options.runtimeApiVersion,
+			current,
+			...this.options.sandbox === void 0 ? {} : { blockingFailure: state.blockingFailure === null ? null : {
+				code: state.blockingFailure.code,
+				committed: current
+			} },
+			pending: state.pending === null ? null : {
+				version: state.pending.version,
+				sha256: state.pending.sha256
+			},
+			blocked: state.blocked,
+			lastRejection: rejected === null ? null : {
+				code: rejected.code,
+				target: rejected.version === void 0 || rejected.sha256 === void 0 ? null : {
+					version: rejected.version,
+					sha256: rejected.sha256
+				}
+			}
+		});
+	}
+	async report(revision, explicitActivation = false, activated = false) {
+		if (this.lifetime.signal.aborted) return;
+		if (explicitActivation) this.stopped = void 0;
+		const run = this.scope(revision);
+		if (run === void 0) {
+			if (explicitActivation) throw new ObservationError("AGENT_CONFIG_HOST_UNAVAILABLE");
+			return;
+		}
+		const member = this.member();
+		if (member === void 0) return;
+		if (this.options.sandbox === void 0) await this.migrate(run, member, explicitActivation);
+		if (explicitActivation) await this.options.replacementState.markReplaced(member);
+		else if (activated && this.preparedHostId !== run.hostId) throw new ObservationError("AGENT_CONFIG_HOST_UNAVAILABLE");
+		this.activationRequest = explicitActivation || activated;
+		const active = this.active = new AbortController();
+		const signal = AbortSignal.any([
+			active.signal,
+			this.lifetime.signal,
+			AbortSignal.timeout(this.options.requestTimeoutMs)
+		]);
+		try {
+			await mkdir(this.options.stateRoot, {
+				recursive: true,
+				mode: 448
+			});
+			await withFileLock(join(this.options.stateRoot, `agent-config-${this.options.workspaceKind}-${run.hostId}.json`), async () => {
+				this.current(run, signal);
+				const state = await this.load(run.hostId);
+				this.current(run, signal);
+				const record = state.scopes[run.key] ??= {
+					generation: 0,
+					running: null,
+					pendingRegistration: null,
+					pendingReport: null
+				};
+				await this.attestSandbox(state, record, run, signal);
+				const uncertainGeneration = record.pendingRegistration?.expectedGeneration;
+				if (explicitActivation) {
+					this.preparedRevision = void 0;
+					this.preparedHostId = void 0;
+					record.pendingRegistration = null;
+					record.pendingReport = null;
+					run.bootId = brandString(randomUUID());
+					run.started = false;
+				} else if (!activated && (this.replaced || record.pendingRegistration?.explicitActivation === true)) {
+					await this.rememberReplacement(state, record, member);
+					this.options.onReplaced?.(run.hostId);
+					return;
+				}
+				try {
+					if (run.started && record.running?.bootId !== run.bootId) throw new ObservationError("AGENT_CONFIG_HOST_CONFLICT");
+					await this.registration(state, record, run, signal);
+					await this.replay(state, record, run, signal);
+					if (record.running?.bootId === run.bootId) run.started = true;
+					for (let rebinds = 0;; rebinds++) {
+						if (!run.started) {
+							if (state.bootSequence >= Number.MAX_SAFE_INTEGER) throw new ObservationError("AGENT_CONFIG_HOST_STATE_INVALID");
+							state.bootSequence++;
+							record.pendingRegistration = {
+								hostId: run.hostId,
+								bootId: run.bootId,
+								requestId: randomUUID(),
+								bootSequence: state.bootSequence,
+								expectedGeneration: explicitActivation ? uncertainGeneration ?? record.generation : record.generation,
+								...run.sandboxBinding === void 0 ? {} : { sandboxBinding: run.sandboxBinding },
+								...explicitActivation ? { explicitActivation: true } : {}
+							};
+							await this.save(state);
+							try {
+								await this.registration(state, record, run, signal);
+							} catch (error) {
+								if (!explicitActivation || uncertainGeneration === void 0 || !(error instanceof ObservationError) || error.code !== "AGENT_CONFIG_HOST_GENERATION_CONFLICT") throw error;
+								const pending = record.pendingRegistration;
+								record.pendingRegistration = {
+									...pending,
+									requestId: randomUUID(),
+									expectedGeneration: pending.expectedGeneration + 1
+								};
+								await this.save(state);
+								await this.registration(state, record, run, signal);
+							}
+							run.started = true;
+						}
+						if (explicitActivation) {
+							this.preparedRevision = revision;
+							this.preparedHostId = run.hostId;
+							return;
+						}
+						if (record.running === null || record.running.sequence >= Number.MAX_SAFE_INTEGER) throw new ObservationError("AGENT_CONFIG_HOST_STATE_INVALID");
+						record.pendingReport = {
+							...this.snapshot(),
+							generation: record.generation,
+							sequence: record.running.sequence + 1
+						};
+						await this.save(state);
+						if (!await this.replay(state, record, run, signal)) break;
+						if (rebinds > 0) throw new ObservationError("AGENT_CONFIG_HOST_UNAVAILABLE");
+					}
+					delete record.replaced;
+					if (activated) await this.save(state);
+				} catch (error) {
+					if (this.options.sandbox === void 0 && (explicitActivation || error instanceof ObservationError && error.code === "LOCAL_HOST_REPLACED")) {
+						await this.rememberReplacement(state, record, member);
+						this.options.onReplaced?.(run.hostId);
+					}
+					throw error;
+				}
+			}, {
+				signal,
+				waitMs: this.options.requestTimeoutMs
+			});
+		} finally {
+			this.activationRequest = false;
+			if (this.active === active) this.active = void 0;
+		}
+	}
+	async dispose() {
+		this.lifetime.abort();
+		this.active?.abort();
+		if (this.timer !== void 0) clearTimeout(this.timer);
+		this.stopScope();
+		this.stopActivation();
+		this.stopActivated();
+		this.stopIdentity();
+		this.stopReplacement();
+		await this.chain;
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* `WorkspaceBundles` Service Definition (`ctx.workspaceBundles`) and its Provider.
+* The Provider resolves its Config at load, so missing materialize roots fail plugin load.
+*/
+var types_default = GestaltWorkspaceBundles;
+//#endregion
+export { AgentConfigDescriptorSchema, AgentConfigError, BundledAgentConfigReceiptSchema, Config, GestaltWorkspaceBundles, HOST_AGENT_CONFIG_API_VERSION, LocalHostIdentityLoadError, LocalHostIdentityWriteError, WorkspaceBundleError, WorkspaceBundles, WorkspaceBundlesConfigError, agentConfigHostObservation, agentConfigSha256, assertTemplateRelativePath, bundledDirectory, crashableFs, createNodeFs, decodeAgentConfig, types_default as default, digestOf, encodeBundleSegment, getModuleAgentConfigAssignment, identityOf, isAgentConfigVersion, loadBundledAgentConfigSync, loadVerifiedManifest, loadVerifiedManifestSync, overallDigest, parseTemplateManifest, recordWorkspaceAgentConfigVersion, resolveWorkspaceBundlesSpec, sandboxAgentConfigHostObservation, sharedLocalHostId, verifyTemplateTree };