@gestaltrun/dsh-workspace-bundle 0.1.0 → 0.1.1

package/lib/index.js

@@ -1,13 +1,14 @@
 import { basename, dirname, isAbsolute, join, normalize, posix, sep } from "node:path";
-import { brandString } from "@deepseek-ai/dsh-brand";
-import Schema from "@deepseek-ai/schemastery";
-import { Service } from "@deepseek-ai/cordis";
-import { createHash } from "node:crypto";
 import { constants, existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
-import { access, chmod, copyFile, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 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 {
@@ -36,6 +37,214 @@ var WorkspaceBundleError = class extends Error {
 	}
 };
 //#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. */
 /**
@@ -81,6 +290,236 @@ function resolveWorkspaceBundlesSpec(config = {}) {
 	};
 }
 //#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. */
 /**
@@ -88,56 +527,18 @@ function resolveWorkspaceBundlesSpec(config = {}) {
 * replace its tree as a whole. Registration is an effect; the returned disposer forbids later acquire.
 */
 var WorkspaceBundles = class extends Service {
-	/** @param ctx - context owning this Provider. */
-	constructor(ctx) {
+	/** 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/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/digest.js
 /** Template manifest parsing and per-file / overall digest verification. */
 const SHA256 = /^[0-9a-f]{64}$/u;
@@ -456,153 +857,37 @@ 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-format.js
-/** 内置 Workspace Agent 配置的文件校验；目录和压缩字节的大小均由部署配置限制。 */
-/** 本 Host 实现的 Agent 配置接口版本；白名单与写操作授权由 Host 保持。 */
-const HOST_AGENT_CONFIG_API_VERSION = "1.0.0";
-/** Agent 配置 SHA-256 的十六进制编码。 */
-const AgentConfigSha256 = z.string().regex(/^[a-f0-9]{64}$/u);
-/** 内置 Workspace 种类；不含路径分隔符。 */
-const WorkspaceKind = 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,
-	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),
-	releaseNotes: z.string().min(1).max(2e4)
-});
-/** 包内逐文件摘要与字节数，文件路径相对版本目录。 */
-const AgentConfigManifestSchema = z.strictObject({
-	formatVersion: z.literal(1),
-	workspaceKind: WorkspaceKind,
-	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 - 失败类别。 */
-	constructor(code) {
-		super({
-			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");
+		[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}`);
 }
 /**
-* 拒绝无法在各 Host 文件系统安全表达的相对路径。
-* @param path - 包内 POSIX 路径。
-* @returns 原始路径。
+* 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.
 */
-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;
+async function writeJournal(fs, path, record, journal) {
+	const next = {
+		...record,
+		journal
+	};
+	await writeRecord(fs, path, next);
+	return next;
 }
 /**
-* 同时认证压缩包和逐文件字节，任何失败均发生在版本目录写入前。
-* @param bytes - 下载的完整 gzip 字节。
-* @param descriptor - server 经鉴权查询给出的登记信息。
-* @param maxExpandedBytes - 解压 JSON 和文件总字节上限。
-* @returns 清单和已校验文件。
+* 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 decodeAgentConfig(bytes, descriptor, maxExpandedBytes) {
-	if (bytes.length !== descriptor.sizeBytes || agentConfigSha256(bytes) !== descriptor.sha256) throw new AgentConfigError("AGENT_CONFIG_DIGEST_MISMATCH");
-	if (!semver.satisfies("1.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 = "";
+function committedRecord(record, digest, pluginVersion) {
 	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
-			};
-		})
+		...record,
+		pluginVersion,
+		templateDigest: digest,
+		journal: idleJournal(),
+		lastFailure: null
 	};
 }
 //#endregion
@@ -644,6 +929,7 @@ var WorkspaceAgentConfigSourceOwner = class {
 	spec;
 	report;
 	download;
+	recoverIdle;
 	lifetime = new AbortController();
 	inFlight;
 	requestAbort;
@@ -653,26 +939,39 @@ var WorkspaceAgentConfigSourceOwner = class {
 	selected;
 	candidate;
 	failure = null;
+	rejection;
+	admissionFailure;
 	root;
-	/** @param registration - 内置模板及鉴权查询回调。 @param spec - 部署预算。 @param report - 固定失败诊断的报告者。 @param download - 文件 HTTP 传输。 */
-	constructor(registration, spec, report, download = fetch) {
+	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: null
+			sha256: registration.template.agentConfigSha256 ?? null
 		};
 		this.root = bundledDirectory(join(spec.templateCacheRoot, "agent-config-versions"), registration.source.identity);
 	}
-	/** @returns 已应用版本、候选版本和最近一次失败。 */
+	/** @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 {
-			current: publicVersion(this.selected.template, this.selected.sha256),
+			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.failure
+			failure: this.admissionFailure === void 0 ? this.failure : {
+				code: this.admissionFailure.code,
+				message: this.admissionFailure.message
+			}
 		};
 	}
 	/**
@@ -683,14 +982,57 @@ var WorkspaceAgentConfigSourceOwner = class {
 	* @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) {
-			this.selected = {
-				template: this.registration.template,
-				sha256: null
+			const template = this.registration.template;
+			return {
+				template,
+				range: template.agentConfigReceipt?.hostAgentConfigApiRange,
+				...template.agentConfigReceipt?.runtimeApiRange === void 0 ? {} : { runtimeApiRange: template.agentConfigReceipt.runtimeApiRange }
 			};
-			return this.selected.template;
 		}
-		if (digest === this.selected.template.manifest.digest && (version === void 0 || version === this.selected.template.manifest.pluginVersion) && sha256 === this.selected.sha256) return this.selected.template;
 		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")));
@@ -698,22 +1040,46 @@ var WorkspaceAgentConfigSourceOwner = class {
 		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");
-		this.selected = {
+		const { bundleId, workspaceKey, title } = this.registration.template;
+		return {
 			template: {
-				...this.registration.template,
+				bundleId,
+				workspaceKey,
+				title,
 				sourceRoot: join(directory, receipt.version),
 				manifest,
 				agentConfigSha256: receipt.sha256
 			},
-			sha256: receipt.sha256
+			range: receipt.hostAgentConfigApiRange,
+			...receipt.runtimeApiRange === void 0 ? {} : { runtimeApiRange: receipt.runtimeApiRange }
 		};
-		if (this.candidate?.sha256 === receipt.sha256) this.candidate = void 0;
-		return this.selected.template;
 	}
-	/** 注册者调用一次以启动查询，并按配置间隔继续。 */
-	start() {
+	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 () => {
-			await this.refresh();
+			try {
+				await this.refresh();
+			} catch (error) {
+				this.reportFailure(this.configError(error));
+			}
 			if (!this.lifetime.signal.aborted) this.timer = setTimeout(() => {
 				tick();
 			}, this.spec.agentConfigPollIntervalMs);
@@ -722,6 +1088,9 @@ var WorkspaceAgentConfigSourceOwner = class {
 	}
 	/** @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;
@@ -734,15 +1103,21 @@ var WorkspaceAgentConfigSourceOwner = class {
 		const abort = new AbortController();
 		this.requestAbort = abort;
 		this.requestRevision = revision;
-		const run = this.fetchCandidate(revision, abort.signal).catch((error) => {
+		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 = error instanceof AgentConfigError ? error : new AgentConfigError("AGENT_CONFIG_INVALID");
+			const failure = this.configError(error);
 			this.failure = {
 				code: failure.code,
 				message: failure.message
 			};
-			this.report(failure);
+			this.rememberRejection(failure, attempt.version, revision, attempt.sha256);
+			this.reportFailure(failure);
 		}).finally(() => {
 			this.inFlight = void 0;
 			this.requestAbort = void 0;
@@ -754,8 +1129,28 @@ var WorkspaceAgentConfigSourceOwner = class {
 	/** @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);
@@ -763,7 +1158,7 @@ var WorkspaceAgentConfigSourceOwner = class {
 	}
 	/** @param template - 已通过 Workspace 整体替换提交的模板。 */
 	async committed(template) {
-		await this.recover(template.manifest.digest, template.manifest.pluginVersion, template.agentConfigSha256 ?? null);
+		await this.recover(template.manifest.digest, template.manifest.pluginVersion, journalAgentConfigSha256(template, this.registration.template));
 	}
 	/**
 	* 清除未提交候选，报告整体替换失败；已提交状态由 journal 恢复结果决定。
@@ -772,26 +1167,49 @@ var WorkspaceAgentConfigSourceOwner = class {
 	*/
 	failedApply(template, cause) {
 		if (this.candidate?.template === template) this.candidate = void 0;
-		const error = cause instanceof AgentConfigError && cause.code === "AGENT_CONFIG_SCOPE_CHANGED" ? cause : new AgentConfigError("AGENT_CONFIG_APPLY_FAILED");
+		const error = cause instanceof AgentConfigError ? cause : new AgentConfigError("AGENT_CONFIG_APPLY_FAILED");
 		this.failure = {
 			code: error.code,
 			message: error.message
 		};
-		this.report(error);
+		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 this.inFlight;
+		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);
 	}
-	async fetchCandidate(revision, requestSignal) {
+	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,
@@ -801,20 +1219,26 @@ var WorkspaceAgentConfigSourceOwner = class {
 		try {
 			value = await this.registration.source.query(signal);
 		} catch (error) {
-			throw new AgentConfigError("AGENT_CONFIG_QUERY_FAILED");
+			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");
-		if (descriptor.sha256 === this.selected.sha256) {
+		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");
@@ -892,12 +1316,17 @@ var WorkspaceAgentConfigSourceOwner = class {
 		}));
 		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 = {
-			...this.registration.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,
@@ -905,6 +1334,7 @@ var WorkspaceAgentConfigSourceOwner = class {
 			revision
 		};
 		this.failure = null;
+		this.rejection = void 0;
 	}
 };
 //#endregion
@@ -948,6 +1378,7 @@ var GestaltWorkspaceBundles = class extends WorkspaceBundles {
 	chain = Promise.resolve();
 	recycle = /* @__PURE__ */ new Map();
 	recycleWork = /* @__PURE__ */ new Map();
+	contentDrains = /* @__PURE__ */ new Set();
 	closed = false;
 	download;
 	/**
@@ -958,8 +1389,9 @@ var GestaltWorkspaceBundles = class extends WorkspaceBundles {
 	* @param options.fetch - 文件 HTTP 传输；默认使用 Host fetch。
 	*/
 	constructor(ctx, config = {}, options = {}) {
-		super(ctx);
-		this.spec = resolveWorkspaceBundlesSpec(config);
+		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 () => {
@@ -968,6 +1400,7 @@ var GestaltWorkspaceBundles = class extends WorkspaceBundles {
 			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");
@@ -1010,9 +1443,23 @@ var GestaltWorkspaceBundles = class extends WorkspaceBundles {
 			source
 		}, this.spec, (error) => {
 			this.ctx.logger.warn("%s：%s", error.code, error.message);
-		}, this.download);
+		}, 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();
+		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);
@@ -1034,11 +1481,69 @@ var GestaltWorkspaceBundles = class extends WorkspaceBundles {
 		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) {
@@ -1066,9 +1571,15 @@ var GestaltWorkspaceBundles = class extends WorkspaceBundles {
 	* 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(() => this.recoverOne(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);
@@ -1078,14 +1589,18 @@ var GestaltWorkspaceBundles = class extends WorkspaceBundles {
 	async ensureOne(identity) {
 		let template = this.requireTemplate(identity);
 		const source = this.agentConfigSources.get(keyOf(identity));
-		const stored = this.records.get(keyOf(identity)) ?? await this.loadStored(identity);
-		if (source !== void 0) template = await source.recover(stored?.templateDigest, stored?.pluginVersion, stored?.agentConfigSha256);
 		const recovered = await this.recoverOne(identity);
 		const record = this.records.get(keyOf(identity));
-		if (source !== void 0) template = await source.recover(record?.templateDigest, record?.pluginVersion, record?.agentConfigSha256);
+		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) === (template.agentConfigSha256 ?? null) && record.journal.phase === "idle") return recovered;
+		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;
@@ -1190,10 +1705,10 @@ var GestaltWorkspaceBundles = class extends WorkspaceBundles {
 		const toDigest = record.journal.toDigest;
 		try {
 			const source = this.agentConfigSources.get(keyOf(identity));
-			if (source !== void 0 && toDigest !== null) template = await source.recover(toDigest, record.journal.pluginVersion ?? void 0, record.journal.agentConfigSha256);
+			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 this.commit(identity, record, template);
+				return await this.commit(identity, record, template);
 			}
 			if (toDigest !== null && template === void 0) {
 				const cached = bundledDirectory(this.spec.templateCacheRoot, identity);
@@ -1207,10 +1722,10 @@ var GestaltWorkspaceBundles = class extends WorkspaceBundles {
 						sourceRoot: cached,
 						manifest
 					};
-					return this.commit(identity, record, synthetic);
+					return await this.commit(identity, record, synthetic);
 				}
 			}
-		} catch {}
+		} catch (error) {}
 		return this.restoreOld(identity, record);
 	}
 	async replace(template, existing, assertApplicable) {
@@ -1247,7 +1762,7 @@ var GestaltWorkspaceBundles = class extends WorkspaceBundles {
 			stagingPath: staging,
 			backupPath: await this.fs.exists(root) ? backup : null,
 			swapComplete: false,
-			...template.agentConfigSha256 === void 0 ? {} : { agentConfigSha256: template.agentConfigSha256 }
+			agentConfigSha256: journalAgentConfigSha256(template, this.requireTemplate(identity))
 		};
 		const updating = await writeJournal(this.fs, this.recordFile(identity), {
 			...record,
@@ -1291,7 +1806,7 @@ var GestaltWorkspaceBundles = class extends WorkspaceBundles {
 			workspaceId: workspace.id,
 			path: workspace.path,
 			registered: true,
-			...this.agentConfigSources.has(keyOf(identity)) ? { agentConfigSha256: template.agentConfigSha256 ?? null } : {}
+			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);
@@ -1358,6 +1873,991 @@ function recordWorkspaceAgentConfigVersion(session, current) {
 	});
 }
 //#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.
@@ -1365,4 +2865,4 @@ function recordWorkspaceAgentConfigVersion(session, current) {
 */
 var types_default = GestaltWorkspaceBundles;
 //#endregion
-export { AgentConfigDescriptorSchema, AgentConfigError, Config, GestaltWorkspaceBundles, HOST_AGENT_CONFIG_API_VERSION, WorkspaceBundleError, WorkspaceBundles, WorkspaceBundlesConfigError, agentConfigSha256, assertTemplateRelativePath, bundledDirectory, crashableFs, createNodeFs, decodeAgentConfig, types_default as default, digestOf, encodeBundleSegment, identityOf, loadVerifiedManifest, loadVerifiedManifestSync, overallDigest, parseTemplateManifest, recordWorkspaceAgentConfigVersion, resolveWorkspaceBundlesSpec, verifyTemplateTree };
+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 };