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

package/lib/index.js

@@ -0,0 +1,1368 @@
+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 { gunzipSync } from "node:zlib";
+import semver from "semver";
+//#region lib/types/errors.js
+/** Misconfiguration of the workspace-bundle row; plugin load fails with it. */
+var WorkspaceBundlesConfigError = class extends Error {
+	code;
+	name = "WorkspaceBundlesConfigError";
+	/**
+	* @param code - stable failure code.
+	* @param message - diagnostic naming the offending field.
+	*/
+	constructor(code, message) {
+		super(`workspace-bundle: ${message} (${code})`);
+		this.code = code;
+	}
+};
+/** Template, path, digest, or upgrade failure; the Host reports it and does not fall back. */
+var WorkspaceBundleError = class extends Error {
+	code;
+	name = "WorkspaceBundleError";
+	/**
+	* @param code - stable failure code.
+	* @param message - diagnostic.
+	*/
+	constructor(code, message) {
+		super(`workspace-bundle: ${message} (${code})`);
+		this.code = code;
+	}
+};
+//#endregion
+//#region lib/types/config.js
+/** workspace-bundle Config: Schemastery field validation and explicit resolution into a Spec. */
+/**
+* Field types and bounds. Path fields are optional here so a missing value reaches
+* {@link resolveWorkspaceBundlesSpec} and fails with its named diagnostic.
+*/
+const Config = Schema.object({
+	materializeRoot: Schema.string().description("Absolute parent of bundled Workspace roots"),
+	templateCacheRoot: Schema.string().description("Absolute parent of immutable template copies"),
+	journalRoot: Schema.string().description("Absolute parent of upgrade journals"),
+	quiesceTimeoutMs: Schema.number().min(1e3).max(6e5).step(1).default(3e4),
+	recycleTimeoutMs: Schema.number().min(0).max(6e5).step(1).default(6e4),
+	agentConfigPollIntervalMs: Schema.number().min(1e3).max(864e5).step(1).default(3e5),
+	agentConfigRequestTimeoutMs: Schema.number().min(100).max(6e5).step(1).default(3e4),
+	agentConfigMaxDownloadBytes: Schema.number().min(1024).max(268435456).step(1).default(67108864),
+	agentConfigMaxExpandedBytes: Schema.number().min(1024).max(536870912).step(1).default(134217728),
+	allowLoopbackAgentConfigHttp: Schema.boolean().default(false)
+});
+function absoluteDirectory(value, field) {
+	if (value === void 0 || value.trim() === "") throw new WorkspaceBundlesConfigError(field === "materializeRoot" ? "WORKSPACE_BUNDLES_MATERIALIZE_ROOT_MISSING" : field === "templateCacheRoot" ? "WORKSPACE_BUNDLES_TEMPLATE_CACHE_ROOT_MISSING" : "WORKSPACE_BUNDLES_JOURNAL_ROOT_MISSING", `${field} is required`);
+	if (!isAbsolute(value) || value.includes("\0") || normalize(value).includes(`..${sep}`) || normalize(value).endsWith(`${sep}..`)) throw new WorkspaceBundlesConfigError("WORKSPACE_BUNDLES_PATH_INVALID", `${field} ${JSON.stringify(value)} must be an absolute path without parent segments`);
+	return normalize(value);
+}
+/**
+* Resolve raw settings into the Spec the Provider runs with.
+* @param config - raw row settings.
+* @returns every field set, with roots normalized.
+* @throws {WorkspaceBundlesConfigError} When a required path is missing or not absolute.
+*/
+function resolveWorkspaceBundlesSpec(config = {}) {
+	const resolved = Config(config);
+	return {
+		materializeRoot: absoluteDirectory(resolved.materializeRoot, "materializeRoot"),
+		templateCacheRoot: absoluteDirectory(resolved.templateCacheRoot, "templateCacheRoot"),
+		journalRoot: absoluteDirectory(resolved.journalRoot, "journalRoot"),
+		quiesceTimeoutMs: resolved.quiesceTimeoutMs,
+		recycleTimeoutMs: resolved.recycleTimeoutMs,
+		agentConfigPollIntervalMs: resolved.agentConfigPollIntervalMs,
+		agentConfigRequestTimeoutMs: resolved.agentConfigRequestTimeoutMs,
+		agentConfigMaxDownloadBytes: resolved.agentConfigMaxDownloadBytes,
+		agentConfigMaxExpandedBytes: resolved.agentConfigMaxExpandedBytes,
+		allowLoopbackAgentConfigHttp: resolved.allowLoopbackAgentConfigHttp
+	};
+}
+//#endregion
+//#region lib/types/definition.js
+/** `WorkspaceBundles` Service Definition: Host-only template registration and stable Workspace materialize. */
+/**
+* Host-only capability: register a packaged template, materialize a stable hidden Workspace, and
+* replace its tree as a whole. Registration is an effect; the returned disposer forbids later acquire.
+*/
+var WorkspaceBundles = class extends Service {
+	/** @param ctx - context owning this Provider. */
+	constructor(ctx) {
+		super(ctx, "workspaceBundles");
+	}
+};
+//#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;
+function fileDigest(bytes) {
+	return brandString(createHash("sha256").update(bytes).digest("hex"));
+}
+/**
+* Digest of the ordered path+file-digest catalog.
+* @param files - sorted catalog.
+*/
+function overallDigest(files) {
+	const hash = createHash("sha256");
+	for (const file of files) hash.update(`${file.path}\0${file.digest}\n`);
+	return brandString(hash.update("").digest("hex"));
+}
+function sourceOf(value) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "object" || value === null) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest source must be an object");
+	const record = value;
+	if (typeof record.repository !== "string" || typeof record.commit !== "string") throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest source must name repository and commit");
+	return {
+		repository: record.repository,
+		commit: record.commit
+	};
+}
+/**
+* Parse and validate a template manifest document.
+* @param value - JSON value.
+*/
+function parseTemplateManifest(value) {
+	if (typeof value !== "object" || value === null) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest must be an object");
+	const record = value;
+	if (record.formatVersion !== 1) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest formatVersion must be 1");
+	if (typeof record.pluginVersion !== "string" || record.pluginVersion === "") throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest pluginVersion is required");
+	if (!Array.isArray(record.files)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest files must be an array");
+	const files = record.files.map((entry, index) => {
+		if (typeof entry !== "object" || entry === null) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", `manifest files[${index}] must be an object`);
+		const file = entry;
+		if (typeof file.path !== "string" || typeof file.bytes !== "number" || typeof file.digest !== "string" || !SHA256.test(file.digest)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", `manifest files[${index}] is incomplete`);
+		assertTemplateRelativePath(file.path);
+		return {
+			path: file.path,
+			bytes: file.bytes,
+			digest: brandString(file.digest)
+		};
+	});
+	const sorted = [...files].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+	if (sorted.some((file, index) => file.path !== files[index]?.path)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest files must be sorted by path");
+	if (sorted.some((file, index) => index > 0 && file.path === sorted[index - 1]?.path)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest files must not repeat a path");
+	if (typeof record.digest !== "string" || !SHA256.test(record.digest)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest digest must be a SHA-256 hex string");
+	const digest = brandString(record.digest);
+	if (digest !== overallDigest(sorted)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_DIGEST_MISMATCH", "manifest overall digest does not match its files");
+	const source = sourceOf(record.source);
+	return source === void 0 ? {
+		formatVersion: 1,
+		pluginVersion: record.pluginVersion,
+		files: sorted,
+		digest
+	} : {
+		formatVersion: 1,
+		pluginVersion: record.pluginVersion,
+		source,
+		files: sorted,
+		digest
+	};
+}
+/**
+* Read every regular file under `root` as a POSIX-relative catalog.
+* @param fs - filesystem.
+* @param root - directory to walk.
+*/
+async function listRegularFiles(fs, root) {
+	const acc = [];
+	const walk = async (directory, prefix) => {
+		let names;
+		try {
+			names = await fs.readdir(directory);
+		} catch (error) {
+			if (error.code === "ENOENT") throw new WorkspaceBundleError("WORKSPACE_BUNDLE_MISSING_ASSET", `template root ${JSON.stringify(root)} is missing`);
+			throw error;
+		}
+		for (const name of [...names].sort()) {
+			const path = join(directory, name);
+			const relative = prefix === "" ? name : `${prefix}/${name}`;
+			const stat = await fs.lstat(path);
+			if (stat.isSymbolicLink()) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_SYMLINK_REJECTED", `template path ${JSON.stringify(relative)} is a symbolic link`);
+			if (stat.isDirectory()) await walk(path, relative);
+			else if (stat.isFile()) {
+				assertTemplateRelativePath(relative);
+				acc.push(relative);
+			} else throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", `template path ${JSON.stringify(relative)} is not a regular file`);
+		}
+	};
+	await walk(root, "");
+	return acc;
+}
+/**
+* Verify every listed file and the overall digest against a directory.
+* @param fs - filesystem.
+* @param root - directory holding the files.
+* @param manifest - expected catalog.
+*/
+async function verifyTemplateTree(fs, root, manifest) {
+	const present = new Set(await listRegularFiles(fs, root));
+	present.delete("manifest.json");
+	for (const file of manifest.files) {
+		if (!present.has(file.path)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_MISSING_ASSET", `template is missing ${JSON.stringify(file.path)}`);
+		const bytes = await fs.readFile(join(root, ...file.path.split("/")));
+		if (bytes.length !== file.bytes || fileDigest(bytes) !== file.digest) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_DIGEST_MISMATCH", `template file ${JSON.stringify(file.path)} digest mismatch`);
+		present.delete(file.path);
+	}
+	if (present.size > 0) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", `template has unexpected files ${[...present].join(", ")}`);
+}
+/**
+* Load `manifest.json` from a template directory and verify the tree.
+* @param fs - filesystem.
+* @param root - template directory.
+*/
+async function loadVerifiedManifest(fs, root) {
+	let raw;
+	try {
+		raw = await fs.readFile(join(root, "manifest.json"));
+	} catch (error) {
+		if (error.code === "ENOENT") throw new WorkspaceBundleError("WORKSPACE_BUNDLE_MISSING_ASSET", "template is missing manifest.json");
+		throw error;
+	}
+	let value;
+	try {
+		value = JSON.parse(raw.toString("utf8"));
+	} catch {
+		throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest.json is not JSON");
+	}
+	const manifest = parseTemplateManifest(value);
+	await verifyTemplateTree(fs, root, manifest);
+	return manifest;
+}
+/** @param bytes - file contents. */
+function digestOf(bytes) {
+	return fileDigest(bytes);
+}
+/**
+* Load and verify a packaged template at plugin construction. A missing or
+* invalid tree fails load instead of registering a half-checked catalog.
+* @param root - template directory.
+*/
+function loadVerifiedManifestSync(root) {
+	const manifestPath = join(root, "manifest.json");
+	if (!existsSync(manifestPath)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_MISSING_ASSET", "template is missing manifest.json");
+	let value;
+	try {
+		value = JSON.parse(readFileSync(manifestPath, "utf8"));
+	} catch {
+		throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "manifest.json is not JSON");
+	}
+	const manifest = parseTemplateManifest(value);
+	const present = /* @__PURE__ */ new Set();
+	const walk = (directory, prefix) => {
+		let names;
+		try {
+			names = readdirSync(directory);
+		} catch (error) {
+			if (error.code === "ENOENT") throw new WorkspaceBundleError("WORKSPACE_BUNDLE_MISSING_ASSET", `template root ${JSON.stringify(root)} is missing`);
+			throw error;
+		}
+		for (const name of [...names].sort()) {
+			const path = join(directory, name);
+			const relative = prefix === "" ? name : `${prefix}/${name}`;
+			const stat = lstatSync(path);
+			if (stat.isSymbolicLink()) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_SYMLINK_REJECTED", `template path ${JSON.stringify(relative)} is a symbolic link`);
+			if (stat.isDirectory()) walk(path, relative);
+			else if (stat.isFile()) {
+				assertTemplateRelativePath(relative);
+				present.add(relative);
+			} else throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", `template path ${JSON.stringify(relative)} is not a regular file`);
+		}
+	};
+	walk(root, "");
+	present.delete("manifest.json");
+	for (const file of manifest.files) {
+		if (!present.has(file.path)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_MISSING_ASSET", `template is missing ${JSON.stringify(file.path)}`);
+		const bytes = readFileSync(join(root, ...file.path.split("/")));
+		if (bytes.length !== file.bytes || fileDigest(bytes) !== file.digest) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_DIGEST_MISMATCH", `template file ${JSON.stringify(file.path)} digest mismatch`);
+		present.delete(file.path);
+	}
+	if (present.size > 0) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", `template has unexpected files ${[...present].join(", ")}`);
+	return manifest;
+}
+//#endregion
+//#region lib/types/filesystem.js
+/** Node filesystem adapter and test crash injection. */
+/**
+* Node.js implementation of {@link WorkspaceBundleFs}.
+* @param options.onPoint - optional test hook; throwing aborts the current step.
+*/
+function createNodeFs(options = {}) {
+	return {
+		async mkdir(path) {
+			await mkdir(path, { recursive: true });
+		},
+		async writeFile(path, data) {
+			await mkdir(dirname(path), { recursive: true });
+			await writeFile(path, data);
+		},
+		readFile(path) {
+			return readFile(path);
+		},
+		rename(from, to) {
+			return rename(from, to);
+		},
+		rm(path, options) {
+			return rm(path, {
+				recursive: options?.recursive === true,
+				force: true
+			});
+		},
+		lstat(path) {
+			return lstat(path);
+		},
+		async readdir(path) {
+			return readdir(path);
+		},
+		realpath(path) {
+			return realpath(path);
+		},
+		copyFile(from, to) {
+			return copyFile(from, to);
+		},
+		async exists(path) {
+			try {
+				await access(path, constants.F_OK);
+				return true;
+			} catch {
+				return false;
+			}
+		}
+	};
+}
+/**
+* Wrap an fs with a crash injector used only by tests.
+* @param inner - real or fake filesystem.
+* @param crashAt - the single point that throws {@link WorkspaceBundleError} `WORKSPACE_BUNDLE_CRASH_INJECTED`.
+*/
+function crashableFs(inner, crashAt) {
+	return {
+		...inner,
+		crash(point) {
+			if (crashAt === point) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_CRASH_INJECTED", point);
+		}
+	};
+}
+//#endregion
+//#region lib/types/journal.js
+/** Durable upgrade journal: staging → updating → swap → verify → commit, with crash recovery. */
+const IDLE = {
+	phase: "idle",
+	fromDigest: null,
+	toDigest: null,
+	pluginVersion: null,
+	stagingPath: null,
+	backupPath: null,
+	swapComplete: false
+};
+/** @returns a journal with no in-flight replacement. */
+function idleJournal() {
+	return IDLE;
+}
+/**
+* @param parent - journal root from Spec.
+* @param identity - bundled Workspace.
+*/
+function recordPath(parent, identity) {
+	return join(bundledDirectory(parent, identity), "record.json");
+}
+async function writeJson(fs, path, value) {
+	const tmp = `${path}.tmp`;
+	await fs.writeFile(tmp, `${JSON.stringify(value)}\n`);
+	await fs.rename(tmp, path);
+}
+/**
+* Persist the product record.
+* @param fs - filesystem.
+* @param path - record.json path.
+* @param record - value.
+*/
+async function writeRecord(fs, path, record) {
+	await writeJson(fs, path, record);
+}
+/**
+* Read a product record when present.
+* @param fs - filesystem.
+* @param path - record.json path.
+*/
+async function readRecord(fs, path) {
+	if (!await fs.exists(path)) return void 0;
+	const value = JSON.parse((await fs.readFile(path)).toString("utf8"));
+	if (value.version !== 1) throw new Error(`workspace-bundle: unsupported record version ${String(value.version)}`);
+	return value;
+}
+async function canonicalPath(fs, path) {
+	try {
+		return await fs.realpath(path);
+	} catch (error) {
+		if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT" || dirname(path) === path) throw error;
+		return join(await canonicalPath(fs, dirname(path)), basename(path));
+	}
+}
+/**
+* Reject stored paths whose canonical locations differ from the identity's controlled directories.
+* @param fs - filesystem used by recovery, including realpath resolution.
+* @param record - stored product record.
+* @param root - materialize directory derived from the requested identity and current Spec.
+* @returns fulfills when every stored path has the same canonical location as its controlled directory.
+* @throws {WorkspaceBundleError} Before recovery mutates files when a stored path differs.
+*/
+async function assertRecordPaths(fs, record, root) {
+	for (const [stored, controlled] of [
+		[record.path, root],
+		[record.journal.stagingPath, `${root}.staging`],
+		[record.journal.backupPath, `${root}.backup`]
+	]) if (stored !== null && await canonicalPath(fs, stored) !== await canonicalPath(fs, controlled)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_PATH_TRAVERSAL", `stored Workspace paths must match the canonical controlled directory ${controlled}`);
+}
+/**
+* Persist the journal as part of the product record.
+* @param fs - filesystem.
+* @param path - record.json path.
+* @param record - current record.
+* @param journal - next journal.
+*/
+async function writeJournal(fs, path, record, journal) {
+	const next = {
+		...record,
+		journal
+	};
+	await writeRecord(fs, path, next);
+	return next;
+}
+/**
+* Mark a replacement as committed: idle journal, new digest and plugin version.
+* @param record - current record.
+* @param digest - verified tree digest.
+* @param pluginVersion - packaged plugin version.
+*/
+function committedRecord(record, digest, pluginVersion) {
+	return {
+		...record,
+		pluginVersion,
+		templateDigest: digest,
+		journal: idleJournal(),
+		lastFailure: null
+	};
+}
+//#endregion
+//#region lib/types/agent-config-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");
+}
+/**
+* 拒绝无法在各 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("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 = "";
+	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/agent-config-source.js
+/** 内容来源的有界拉取和只读版本缓存；此模块不替换运行中的 Workspace。 */
+const AssignmentSchema = z.discriminatedUnion("source", [z.object({
+	source: z.literal("builtin"),
+	workspaceKind: z.string()
+}), z.object({
+	source: z.literal("registry"),
+	workspaceKind: z.string(),
+	agentConfig: AgentConfigDescriptorSchema
+})]);
+const ReceiptSchema = AgentConfigDescriptorSchema.omit({
+	downloadUrl: true,
+	releaseNotes: true
+});
+function publicVersion(template, sha256) {
+	return {
+		workspaceKind: template.bundleId,
+		version: template.manifest.pluginVersion,
+		sha256,
+		hostAgentConfigApiVersion: HOST_AGENT_CONFIG_API_VERSION,
+		templateDigest: template.manifest.digest,
+		sourceRoot: template.sourceRoot
+	};
+}
+async function freezeTree(root) {
+	for (const entry of await readdir(root, { withFileTypes: true })) {
+		const path = join(root, entry.name);
+		if (entry.isDirectory()) await freezeTree(path);
+		else await chmod(path, 292);
+	}
+	await chmod(root, 365);
+}
+/** 一个注册来源的缓存、轮询和候选版本；卸载必须等待所有网络与文件工作结束。 */
+var WorkspaceAgentConfigSourceOwner = class {
+	registration;
+	spec;
+	report;
+	download;
+	lifetime = new AbortController();
+	inFlight;
+	requestAbort;
+	requestRevision;
+	preparedRevisions = /* @__PURE__ */ new WeakMap();
+	timer;
+	selected;
+	candidate;
+	failure = null;
+	root;
+	/** @param registration - 内置模板及鉴权查询回调。 @param spec - 部署预算。 @param report - 固定失败诊断的报告者。 @param download - 文件 HTTP 传输。 */
+	constructor(registration, spec, report, download = fetch) {
+		this.registration = registration;
+		this.spec = spec;
+		this.report = report;
+		this.download = download;
+		this.selected = {
+			template: registration.template,
+			sha256: null
+		};
+		this.root = bundledDirectory(join(spec.templateCacheRoot, "agent-config-versions"), registration.source.identity);
+	}
+	/** @returns 已应用版本、候选版本和最近一次失败。 */
+	state() {
+		if (this.candidate !== void 0 && this.candidate.revision !== this.registration.source.revision()) this.candidate = void 0;
+		return {
+			current: publicVersion(this.selected.template, this.selected.sha256),
+			pending: this.candidate === void 0 ? null : publicVersion(this.candidate.template, this.candidate.sha256),
+			failure: this.failure
+		};
+	}
+	/**
+	* 从 journal 已提交的摘要定位只读缓存，不从 server 的无分配回答推导降级。
+	* @param digest - 已提交 Workspace 模板摘要；undefined 表示首次使用。
+	* @param version - 已提交完整版本，包括构建元数据。
+	* @param sha256 - 已提交包摘要；undefined 支持旧内置记录。
+	* @returns 对应完整模板；缺失已安装缓存时拒绝继续。
+	*/
+	async recover(digest, version, sha256) {
+		if (digest === void 0 || sha256 === void 0 || sha256 === null) {
+			this.selected = {
+				template: this.registration.template,
+				sha256: null
+			};
+			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")));
+		const directory = this.versionDirectory(receipt.version, receipt.sha256);
+		if (receipt.sha256 !== sha256 || receipt.workspaceKind !== this.registration.template.bundleId || (await fs.lstat(directory)).isSymbolicLink() || (await fs.lstat(join(directory, receipt.version))).isSymbolicLink()) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		const manifest = await loadVerifiedManifest(fs, join(directory, receipt.version));
+		if (manifest.digest !== digest || version !== void 0 && receipt.version !== version || manifest.pluginVersion !== receipt.version) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		this.selected = {
+			template: {
+				...this.registration.template,
+				sourceRoot: join(directory, receipt.version),
+				manifest,
+				agentConfigSha256: receipt.sha256
+			},
+			sha256: receipt.sha256
+		};
+		if (this.candidate?.sha256 === receipt.sha256) this.candidate = void 0;
+		return this.selected.template;
+	}
+	/** 注册者调用一次以启动查询，并按配置间隔继续。 */
+	start() {
+		const tick = async () => {
+			await this.refresh();
+			if (!this.lifetime.signal.aborted) this.timer = setTimeout(() => {
+				tick();
+			}, this.spec.agentConfigPollIntervalMs);
+		};
+		tick();
+	}
+	/** @returns 本次查询和完整候选下载结束；失败通过 state 与 report 保留可观察诊断。 */
+	refresh() {
+		if (this.lifetime.signal.aborted) return Promise.resolve();
+		const revision = this.registration.source.revision();
+		if (this.candidate !== void 0 && this.candidate.revision !== revision) this.candidate = void 0;
+		if (this.inFlight !== void 0) {
+			if (revision === this.requestRevision && !this.requestAbort?.signal.aborted) return this.inFlight;
+			this.requestAbort?.abort();
+			this.failure = null;
+			return this.inFlight.then(() => this.refresh());
+		}
+		const abort = new AbortController();
+		this.requestAbort = abort;
+		this.requestRevision = revision;
+		const run = this.fetchCandidate(revision, abort.signal).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");
+			this.failure = {
+				code: failure.code,
+				message: failure.message
+			};
+			this.report(failure);
+		}).finally(() => {
+			this.inFlight = void 0;
+			this.requestAbort = void 0;
+			this.requestRevision = void 0;
+		});
+		this.inFlight = run;
+		return run;
+	}
+	/** @returns 下一个 turn 可应用的候选；没有候选时使用已安装版本。 */
+	template() {
+		if (this.candidate !== void 0 && this.candidate.revision !== this.registration.source.revision()) this.candidate = void 0;
+		return this.candidate?.template ?? this.selected.template;
+	}
+	/** @param template - 即将整体替换的候选。 @throws 来源代次已经改变或已撤销时拒绝应用。 */
+	assertApplicable(template) {
+		const revision = this.preparedRevisions.get(template);
+		if (this.lifetime.signal.aborted || revision !== void 0 && revision !== this.registration.source.revision()) throw new AgentConfigError("AGENT_CONFIG_SCOPE_CHANGED");
+	}
+	/** @param template - 已通过 Workspace 整体替换提交的模板。 */
+	async committed(template) {
+		await this.recover(template.manifest.digest, template.manifest.pluginVersion, template.agentConfigSha256 ?? null);
+	}
+	/**
+	* 清除未提交候选，报告整体替换失败；已提交状态由 journal 恢复结果决定。
+	* @param template - 未能完成提交的模板。
+	* @param cause - 保留来源失效分类；其他原因报告固定应用失败诊断。
+	*/
+	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");
+		this.failure = {
+			code: error.code,
+			message: error.message
+		};
+		this.report(error);
+	}
+	/** 撤销查询、清除后续定时器，并等待下载和目录写入完成。 */
+	async dispose() {
+		this.lifetime.abort();
+		this.candidate = void 0;
+		if (this.timer !== void 0) clearTimeout(this.timer);
+		await this.inFlight;
+		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) {
+		const signal = AbortSignal.any([
+			this.lifetime.signal,
+			requestSignal,
+			AbortSignal.timeout(this.spec.agentConfigRequestTimeoutMs)
+		]);
+		let value;
+		try {
+			value = await this.registration.source.query(signal);
+		} catch (error) {
+			throw 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;
+			return;
+		}
+		const descriptor = assignment.data.agentConfig;
+		if (descriptor.workspaceKind !== assignment.data.workspaceKind) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		if (descriptor.sha256 === this.selected.sha256) {
+			this.candidate = void 0;
+			this.failure = null;
+			return;
+		}
+		if (descriptor.sizeBytes > this.spec.agentConfigMaxDownloadBytes) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		const url = new URL(descriptor.downloadUrl);
+		if (url.username !== "" || url.password !== "" || url.protocol !== "https:" && !(this.spec.allowLoopbackAgentConfigHttp && url.protocol === "http:" && [
+			"localhost",
+			"127.0.0.1",
+			"[::1]"
+		].includes(url.hostname))) throw new AgentConfigError("AGENT_CONFIG_INVALID");
+		let bytes;
+		try {
+			const response = await this.download(url, {
+				signal,
+				redirect: "error"
+			});
+			if (!response.ok || response.body === null || response.headers.get("content-length") !== null && Number(response.headers.get("content-length")) !== descriptor.sizeBytes) throw new AgentConfigError("AGENT_CONFIG_DOWNLOAD_FAILED");
+			const chunks = [];
+			let count = 0;
+			for await (const chunk of response.body) {
+				count += chunk.byteLength;
+				if (count > descriptor.sizeBytes) {
+					await response.body.cancel().catch(() => void 0);
+					throw new AgentConfigError("AGENT_CONFIG_DOWNLOAD_FAILED");
+				}
+				chunks.push(chunk);
+			}
+			bytes = Buffer.concat(chunks);
+		} catch (error) {
+			throw new AgentConfigError("AGENT_CONFIG_DOWNLOAD_FAILED");
+		}
+		const content = decodeAgentConfig(bytes, descriptor, this.spec.agentConfigMaxExpandedBytes);
+		if (signal.aborted || revision !== this.registration.source.revision()) return;
+		await mkdir(this.root, { recursive: true });
+		const directory = this.versionDirectory(descriptor.version, descriptor.sha256);
+		const tree = join(directory, descriptor.version);
+		const fs = createNodeFs();
+		if (!await fs.exists(directory)) {
+			const staging = await mkdtemp(join(this.root, ".staging-"));
+			try {
+				const stagingTree = join(staging, descriptor.version);
+				await mkdir(stagingTree);
+				for (const file of content.files) {
+					const path = join(stagingTree, ...file.path.split("/"));
+					await mkdir(dirname(path), { recursive: true });
+					await writeFile(path, file.bytes, { flag: "wx" });
+				}
+				const files = content.manifest.files.map((file) => ({
+					path: file.path,
+					bytes: file.sizeBytes,
+					digest: brandString(file.sha256)
+				}));
+				await writeFile(join(stagingTree, "manifest.json"), JSON.stringify({
+					formatVersion: 1,
+					pluginVersion: descriptor.version,
+					files,
+					digest: overallDigest(files)
+				}) + "\n");
+				const { downloadUrl: _downloadUrl, releaseNotes: _releaseNotes, ...receipt } = descriptor;
+				await writeFile(join(staging, "receipt.json"), JSON.stringify(ReceiptSchema.parse(receipt)) + "\n");
+				await rename(staging, directory);
+				await freezeTree(tree);
+				await chmod(join(directory, "receipt.json"), 292);
+			} finally {
+				await rm(staging, {
+					recursive: true,
+					force: true
+				});
+			}
+		}
+		const manifest = await loadVerifiedManifest(fs, tree);
+		const files = content.manifest.files.map((file) => ({
+			path: file.path,
+			bytes: file.sizeBytes,
+			digest: brandString(file.sha256)
+		}));
+		if (manifest.pluginVersion !== descriptor.version || manifest.digest !== overallDigest(files)) throw new AgentConfigError("AGENT_CONFIG_DIGEST_MISMATCH");
+		if (signal.aborted || revision !== this.registration.source.revision()) return;
+		const template = {
+			...this.registration.template,
+			sourceRoot: tree,
+			manifest,
+			agentConfigSha256: descriptor.sha256
+		};
+		this.preparedRevisions.set(template, revision);
+		this.candidate = {
+			template,
+			sha256: descriptor.sha256,
+			revision
+		};
+		this.failure = null;
+	}
+};
+//#endregion
+//#region lib/types/provider.js
+/**
+* Host Provider of `WorkspaceBundles`: register a packaged template, materialize a stable
+* hidden Workspace, and replace its tree as a whole with crash recovery.
+*/
+function keyOf(identity) {
+	return `${identity.bundleId}/${identity.workspaceKey}`;
+}
+function originOf(identity) {
+	return {
+		kind: "bundle",
+		bundleId: identity.bundleId,
+		workspaceKey: identity.workspaceKey
+	};
+}
+async function copyTree(fs, from, to, files) {
+	await fs.rm(to, { recursive: true });
+	await fs.mkdir(to);
+	for (const file of files) {
+		const relative = file.path.split("/");
+		const destination = join(to, ...relative);
+		await fs.mkdir(join(destination, ".."));
+		await fs.copyFile(join(from, ...relative), destination);
+	}
+}
+/** Provider for packaged Workspace templates. */
+var GestaltWorkspaceBundles = class extends WorkspaceBundles {
+	static inject = ["workspaceRegistry"];
+	static Config = Config;
+	/** Deployment settings resolved at load. */
+	spec;
+	fs;
+	templates = /* @__PURE__ */ new Map();
+	agentConfigSources = /* @__PURE__ */ new Map();
+	records = /* @__PURE__ */ new Map();
+	leases = /* @__PURE__ */ new Map();
+	waiters = /* @__PURE__ */ new Map();
+	chain = Promise.resolve();
+	recycle = /* @__PURE__ */ new Map();
+	recycleWork = /* @__PURE__ */ new Map();
+	closed = false;
+	download;
+	/**
+	* @param ctx - Host context with the Workspace registry.
+	* @param config - raw row settings.
+	* @param options.fs - filesystem; tests inject crashes through `crashAt`.
+	* @param options.crashAt - single crash point; production omits it.
+	* @param options.fetch - 文件 HTTP 传输；默认使用 Host fetch。
+	*/
+	constructor(ctx, config = {}, options = {}) {
+		super(ctx);
+		this.spec = resolveWorkspaceBundlesSpec(config);
+		this.fs = crashableFs(options.fs ?? createNodeFs(), options.crashAt);
+		this.download = options.fetch ?? fetch;
+		ctx.effect(() => async () => {
+			this.closed = true;
+			for (const timer of this.recycle.values()) clearTimeout(timer);
+			this.recycle.clear();
+			await Promise.all([...this.agentConfigSources.values()].map((source) => source.dispose()));
+			await this.chain;
+			await Promise.all(this.recycleWork.values());
+			this.agentConfigSources.clear();
+		}, "workspace-bundle: recycle timers");
+	}
+	/** @inheritdoc */
+	register(template) {
+		if (this.closed) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Workspace 内容服务已停止");
+		identityOf(template.bundleId, template.workspaceKey);
+		const key = keyOf(template);
+		this.templates.set(key, template);
+		const record = this.records.get(key);
+		if (record !== void 0) this.records.set(key, {
+			...record,
+			registered: true
+		});
+		return () => {
+			if (this.templates.get(key) !== template) return;
+			this.templates.delete(key);
+			const current = this.records.get(key);
+			if (current !== void 0) this.records.set(key, {
+				...current,
+				registered: false
+			});
+		};
+	}
+	/** @inheritdoc */
+	ensure(identity) {
+		if (this.closed) return Promise.reject(new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Workspace 内容服务已停止"));
+		identityOf(identity.bundleId, identity.workspaceKey);
+		return this.enqueue(() => this.ensureOne(identity));
+	}
+	/** @inheritdoc */
+	registerAgentConfigSource(source) {
+		if (this.closed) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Workspace 内容服务已停止");
+		const key = keyOf(source.identity);
+		const template = this.requireTemplate(source.identity);
+		if (this.agentConfigSources.has(key)) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_TEMPLATE_INVALID", "Agent 配置版本来源已注册");
+		const owner = new WorkspaceAgentConfigSourceOwner({
+			template,
+			source
+		}, this.spec, (error) => {
+			this.ctx.logger.warn("%s：%s", error.code, error.message);
+		}, this.download);
+		this.agentConfigSources.set(key, owner);
+		owner.start();
+		return async () => {
+			await owner.dispose();
+			if (this.agentConfigSources.get(key) === owner) this.agentConfigSources.delete(key);
+		};
+	}
+	/** @inheritdoc */
+	agentConfig(identity) {
+		return this.agentConfigSources.get(keyOf(identity))?.state();
+	}
+	/** @inheritdoc */
+	async refreshAgentConfig(identity) {
+		const source = this.agentConfigSources.get(keyOf(identity));
+		if (source === void 0) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Agent 配置版本来源未注册");
+		await source.refresh();
+	}
+	/** @inheritdoc */
+	async acquire(workspaceId) {
+		if (this.closed) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", "Workspace 内容服务已停止");
+		if ([...this.records.values()].some((record) => record.workspaceId === workspaceId && record.journal.phase === "updating")) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", `workspace ${workspaceId} is updating`);
+		return this.enqueue(() => this.acquireOne(workspaceId));
+	}
+	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);
+		const token = Symbol("workspace-bundle-lease");
+		let leases = this.leases.get(workspaceId);
+		if (leases === void 0) {
+			leases = /* @__PURE__ */ new Set();
+			this.leases.set(workspaceId, leases);
+		}
+		leases.add(token);
+		return () => {
+			leases.delete(token);
+			if (leases.size === 0) this.leases.delete(workspaceId);
+			const waiters = this.waiters.get(workspaceId);
+			if (waiters !== void 0) for (const waiter of waiters) waiter();
+		};
+	}
+	/** @inheritdoc */
+	record(identity) {
+		return this.records.get(keyOf(identity));
+	}
+	/** @inheritdoc */
+	pathOf(identity) {
+		identityOf(identity.bundleId, identity.workspaceKey);
+		return bundledDirectory(this.spec.materializeRoot, identity);
+	}
+	/**
+	* Replay an interrupted journal before serving the Workspace.
+	* @param identity - branded pair.
+	* @throws {WorkspaceBundleError} Before any rename or deletion if stored paths differ from this identity's controlled paths.
+	*/
+	async recover(identity) {
+		return this.enqueue(() => this.recoverOne(identity));
+	}
+	enqueue(work) {
+		const run = this.chain.then(work, work);
+		this.chain = run.then(() => void 0, () => void 0);
+		return run;
+	}
+	async ensureOne(identity) {
+		let template = this.requireTemplate(identity);
+		const source = this.agentConfigSources.get(keyOf(identity));
+		const 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 && (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;
+		try {
+			const workspace = await this.replace(template, record, source === void 0 ? void 0 : () => source.assertApplicable(template));
+			await source?.committed(template);
+			return workspace;
+		} catch (error) {
+			if (source === void 0) throw error;
+			if (error instanceof AgentConfigError && error.code === "AGENT_CONFIG_SCOPE_CHANGED") await this.rollbackAgentConfig(identity, record);
+			else await this.recoverOne(identity);
+			const restored = this.records.get(keyOf(identity));
+			await source.recover(restored?.templateDigest, restored?.pluginVersion, restored?.agentConfigSha256);
+			source.failedApply(template, error);
+			if (error instanceof AgentConfigError && error.code === "AGENT_CONFIG_SCOPE_CHANGED" && !this.closed) return (restored === void 0 || !await this.fs.exists(this.pathOf(identity)) ? void 0 : await this.workspaceOf(restored)) ?? this.replace(this.requireTemplate(identity), restored);
+			this.ctx.logger.warn("Agent 配置应用失败，已尝试按 journal 恢复；当前版本未确认。");
+			throw error;
+		}
+	}
+	async rollbackAgentConfig(identity, previous) {
+		const current = this.records.get(keyOf(identity));
+		if (current === void 0) {
+			await this.fs.rm(this.stagingOf(identity), { recursive: true });
+			return;
+		}
+		if (current === previous && current.journal.phase === "idle") {
+			await this.fs.rm(this.stagingOf(identity), { recursive: true });
+			return;
+		}
+		const builtin = this.requireTemplate(identity);
+		const rollback = {
+			...previous ?? {
+				...current,
+				pluginVersion: builtin.manifest.pluginVersion,
+				templateDigest: brandString("0".repeat(64)),
+				agentConfigSha256: null
+			},
+			journal: {
+				...current.journal,
+				phase: "updating",
+				fromDigest: previous?.templateDigest ?? null,
+				toDigest: current.templateDigest,
+				backupPath: await this.fs.exists(this.backupOf(identity)) ? this.backupOf(identity) : null,
+				stagingPath: this.stagingOf(identity),
+				swapComplete: false
+			}
+		};
+		this.records.set(keyOf(identity), rollback);
+		await writeRecord(this.fs, this.recordFile(identity), rollback);
+		await this.restoreOld(identity, rollback);
+	}
+	requireTemplate(identity) {
+		const template = this.templates.get(keyOf(identity));
+		if (template === void 0) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_NOT_REGISTERED", `${keyOf(identity)} is not registered`);
+		return template;
+	}
+	stagingOf(identity) {
+		return `${this.pathOf(identity)}.staging`;
+	}
+	backupOf(identity) {
+		return `${this.pathOf(identity)}.backup`;
+	}
+	recordFile(identity) {
+		return recordPath(this.spec.journalRoot, identity);
+	}
+	async loadStored(identity) {
+		const stored = await readRecord(this.fs, this.recordFile(identity));
+		if (stored !== void 0) this.records.set(keyOf(identity), stored);
+		return stored;
+	}
+	async recoverOne(identity) {
+		const stored = this.records.get(keyOf(identity)) ?? await this.loadStored(identity);
+		if (stored === void 0) return void 0;
+		await assertRecordPaths(this.fs, stored, this.pathOf(identity));
+		if (stored.journal.phase === "idle") return this.workspaceOf(stored);
+		return stored.journal.swapComplete ? this.finishNew(identity, stored) : this.restoreOld(identity, stored);
+	}
+	async workspaceOf(record) {
+		if (record.workspaceId === null) return void 0;
+		return this.ctx.workspaceRegistry.get(record.workspaceId) ?? await this.ctx.workspaceRegistry.create(record.path, void 0, originOf({
+			bundleId: record.bundleId,
+			workspaceKey: record.workspaceKey
+		}));
+	}
+	async restoreOld(identity, record) {
+		const root = this.pathOf(identity);
+		const backup = record.journal.backupPath ?? this.backupOf(identity);
+		const staging = record.journal.stagingPath ?? this.stagingOf(identity);
+		if (await this.fs.exists(backup)) {
+			if (await this.fs.exists(root)) await this.fs.rm(root, { recursive: true });
+			await this.fs.rename(backup, root);
+		} else if (record.journal.fromDigest === null && await this.fs.exists(root)) await this.fs.rm(root, { recursive: true });
+		if (await this.fs.exists(staging)) await this.fs.rm(staging, { recursive: true });
+		const next = {
+			...record,
+			journal: idleJournal(),
+			lastFailure: record.lastFailure
+		};
+		await writeRecord(this.fs, this.recordFile(identity), next);
+		this.records.set(keyOf(identity), next);
+		return this.workspaceOf(next);
+	}
+	async finishNew(identity, record) {
+		let template = this.templates.get(keyOf(identity));
+		const root = this.pathOf(identity);
+		const toDigest = record.journal.toDigest;
+		try {
+			const source = this.agentConfigSources.get(keyOf(identity));
+			if (source !== void 0 && toDigest !== null) template = await source.recover(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);
+			}
+			if (toDigest !== null && template === void 0) {
+				const cached = bundledDirectory(this.spec.templateCacheRoot, identity);
+				const manifest = await loadVerifiedManifest(this.fs, cached);
+				if (manifest.digest === toDigest) {
+					await verifyTemplateTree(this.fs, root, manifest);
+					const synthetic = {
+						bundleId: identity.bundleId,
+						workspaceKey: identity.workspaceKey,
+						title: "Workspace",
+						sourceRoot: cached,
+						manifest
+					};
+					return this.commit(identity, record, synthetic);
+				}
+			}
+		} catch {}
+		return this.restoreOld(identity, record);
+	}
+	async replace(template, existing, assertApplicable) {
+		const identity = identityOf(template.bundleId, template.workspaceKey);
+		assertApplicable?.();
+		await loadVerifiedManifest(this.fs, template.sourceRoot);
+		const cache = bundledDirectory(this.spec.templateCacheRoot, identity);
+		await copyTree(this.fs, template.sourceRoot, cache, [...template.manifest.files, { path: "manifest.json" }]);
+		const staging = this.stagingOf(identity);
+		await copyTree(this.fs, template.sourceRoot, staging, template.manifest.files);
+		assertApplicable?.();
+		this.fs.crash("after-staging");
+		const root = this.pathOf(identity);
+		const backup = this.backupOf(identity);
+		await this.prepareBackup(backup);
+		if (await this.fs.exists(backup)) await this.fs.rm(backup, { recursive: true });
+		const record = existing ?? {
+			version: 1,
+			bundleId: identity.bundleId,
+			workspaceKey: identity.workspaceKey,
+			workspaceId: null,
+			path: root,
+			pluginVersion: template.manifest.pluginVersion,
+			templateDigest: brandString("0".repeat(64)),
+			registered: true,
+			journal: idleJournal(),
+			lastFailure: null
+		};
+		const journal = {
+			phase: "updating",
+			fromDigest: existing?.templateDigest ?? null,
+			toDigest: template.manifest.digest,
+			pluginVersion: template.manifest.pluginVersion,
+			stagingPath: staging,
+			backupPath: await this.fs.exists(root) ? backup : null,
+			swapComplete: false,
+			...template.agentConfigSha256 === void 0 ? {} : { agentConfigSha256: template.agentConfigSha256 }
+		};
+		const updating = await writeJournal(this.fs, this.recordFile(identity), {
+			...record,
+			registered: true,
+			path: root
+		}, journal);
+		this.records.set(keyOf(identity), updating);
+		this.fs.crash("after-journal-updating");
+		if (updating.workspaceId !== null) await this.ctx.serial("workspace-bundle/quiesce", updating.workspaceId);
+		await this.quiesce(updating.workspaceId);
+		assertApplicable?.();
+		this.fs.crash("after-quiesce");
+		await this.fs.mkdir(join(root, ".."));
+		if (await this.fs.exists(root)) {
+			if (await this.fs.exists(backup)) await this.fs.rm(backup, { recursive: true });
+			await this.fs.rename(root, backup);
+		}
+		this.fs.crash("after-rename-backup");
+		assertApplicable?.();
+		await this.fs.rename(staging, root);
+		const swapped = await writeJournal(this.fs, this.recordFile(identity), updating, {
+			...journal,
+			swapComplete: true,
+			stagingPath: null
+		});
+		this.records.set(keyOf(identity), swapped);
+		this.fs.crash("after-rename-staging");
+		await verifyTemplateTree(this.fs, root, template.manifest);
+		this.fs.crash("after-verify");
+		assertApplicable?.();
+		const workspace = await this.commit(identity, swapped, template);
+		assertApplicable?.();
+		this.fs.crash("after-journal-commit");
+		this.scheduleRecycle(backup);
+		return workspace;
+	}
+	async commit(identity, record, template) {
+		const workspace = await this.ctx.workspaceRegistry.create(record.path, template.title, originOf(identity));
+		const next = committedRecord({
+			...record,
+			workspaceId: workspace.id,
+			path: workspace.path,
+			registered: true,
+			...this.agentConfigSources.has(keyOf(identity)) ? { agentConfigSha256: template.agentConfigSha256 ?? null } : {}
+		}, template.manifest.digest, template.manifest.pluginVersion);
+		await writeRecord(this.fs, this.recordFile(identity), next);
+		this.records.set(keyOf(identity), next);
+		return workspace;
+	}
+	async quiesce(workspaceId) {
+		if (workspaceId === null) return;
+		const deadline = Date.now() + this.spec.quiesceTimeoutMs;
+		while ((this.leases.get(workspaceId)?.size ?? 0) > 0) {
+			if (Date.now() >= deadline) throw new WorkspaceBundleError("WORKSPACE_BUNDLE_QUIESCE_TIMEOUT", `workspace ${workspaceId} still has active leases`);
+			await new Promise((resolve) => {
+				let waiters = this.waiters.get(workspaceId);
+				if (waiters === void 0) {
+					waiters = /* @__PURE__ */ new Set();
+					this.waiters.set(workspaceId, waiters);
+				}
+				const timer = setTimeout(resolve, 25);
+				const waiter = () => {
+					clearTimeout(timer);
+					waiters.delete(waiter);
+					resolve();
+				};
+				waiters.add(waiter);
+			});
+		}
+	}
+	scheduleRecycle(backup) {
+		if (this.closed) return;
+		const timer = setTimeout(() => {
+			this.recycle.delete(backup);
+			const work = this.fs.rm(backup, { recursive: true }).catch((error) => {
+				this.ctx.logger.warn("旧 Workspace 备份清理失败，请检查磁盘；当前版本保持可用。");
+			}).finally(() => {
+				this.recycleWork.delete(backup);
+			});
+			this.recycleWork.set(backup, work);
+		}, this.spec.recycleTimeoutMs);
+		this.recycle.set(backup, timer);
+	}
+	async prepareBackup(backup) {
+		const timer = this.recycle.get(backup);
+		if (timer !== void 0) clearTimeout(timer);
+		this.recycle.delete(backup);
+		await this.recycleWork.get(backup);
+	}
+};
+//#endregion
+//#region lib/types/session-events.js
+/**
+* 在每个 Session 首次使用一个不同 Agent 配置版本的 turn 写入身份，重复 step 不重复记录。
+* @param session - 即将请求模型的 Session。
+* @param current - 当前租约固定的完整版本。
+*/
+function recordWorkspaceAgentConfigVersion(session, current) {
+	const previous = session.snapshotEvents().findLast((event) => event.type === "workspace-bundle/agent-config-version");
+	if (previous?.type === "workspace-bundle/agent-config-version" && previous.data.version === current.version && previous.data.agentConfigSha256 === current.sha256 && previous.data.templateDigest === current.templateDigest) return;
+	session.append("workspace-bundle/agent-config-version", {
+		workspaceKind: current.workspaceKind,
+		version: current.version,
+		previousVersion: previous?.type === "workspace-bundle/agent-config-version" ? previous.data.version : null,
+		templateDigest: current.templateDigest,
+		agentConfigSha256: current.sha256,
+		hostAgentConfigApiVersion: current.hostAgentConfigApiVersion
+	});
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* `WorkspaceBundles` Service Definition (`ctx.workspaceBundles`) and its Provider.
+* The Provider resolves its Config at load, so missing materialize roots fail plugin load.
+*/
+var types_default = GestaltWorkspaceBundles;
+//#endregion
+export { AgentConfigDescriptorSchema, AgentConfigError, 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 };