@gestaltrun/dsh-workspace-bundle 0.1.0 → 0.1.1

package/lib/types/agent-config-source.js

@@ -3,10 +3,13 @@ import { chmod, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from
 import { dirname, join } from 'node:path';
 import { brandString } from '@deepseek-ai/dsh-brand';
 import { z } from 'zod';
+import semver from 'semver';
+import { WorkspaceBundleError } from "./errors.js";
 import { AgentConfigDescriptorSchema, AgentConfigError, HOST_AGENT_CONFIG_API_VERSION, decodeAgentConfig } from "./agent-config-format.js";
 import { loadVerifiedManifest, overallDigest } from "./digest.js";
 import { createNodeFs } from "./filesystem.js";
 import { bundledDirectory } from "./paths.js";
+import { journalAgentConfigSha256 } from "./bundled-agent-config.js";
 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 }),
@@ -32,6 +35,7 @@ export class WorkspaceAgentConfigSourceOwner {
     spec;
     report;
     download;
+    recoverIdle;
     lifetime = new AbortController();
     inFlight;
     requestAbort;
@@ -41,22 +45,32 @@ export class WorkspaceAgentConfigSourceOwner {
     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.selected = { template: registration.template, sha256: null };
+        this.recoverIdle = recoverIdle;
+        this.selected = { template: registration.template, sha256: registration.template.agentConfigSha256 ?? null };
         this.root = bundledDirectory(join(spec.templateCacheRoot, 'agent-config-versions'), registration.source.identity);
     }
-    /** @returns 已应用版本、候选版本和最近一次失败。 */
+    /** @returns 已应用/候选版本、执行阻断及当前作用域的最近失败和拒绝。 */
     state() {
         if (this.candidate !== undefined && this.candidate.revision !== this.registration.source.revision())
             this.candidate = undefined;
-        return { current: publicVersion(this.selected.template, this.selected.sha256),
-            pending: this.candidate === undefined ? null : publicVersion(this.candidate.template, this.candidate.sha256), failure: this.failure };
+        if (this.lifetime.signal.aborted || this.rejection?.revision !== this.registration.source.revision())
+            this.rejection = undefined;
+        return { lastRejection: this.rejection?.value ?? null, blocked: this.admissionFailure !== undefined,
+            blockingFailure: this.admissionFailure === undefined ? null : { code: this.admissionFailure.code }, current: this.blockedVersion ?? publicVersion(this.selected.template, this.selected.sha256),
+            pending: this.candidate === undefined ? null : publicVersion(this.candidate.template, this.candidate.sha256),
+            failure: this.admissionFailure === undefined ? this.failure : { code: this.admissionFailure.code, message: this.admissionFailure.message } };
     }
     /**
      * 从 journal 已提交的摘要定位只读缓存，不从 server 的无分配回答推导降级。
@@ -66,14 +80,54 @@ export class WorkspaceAgentConfigSourceOwner {
      * @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 = undefined;
+            return template;
+        }
+        catch (error) {
+            if (digest !== undefined && version !== undefined)
+                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 ?? undefined);
+            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 = undefined;
+        this.admissionFailure = undefined;
+        if (this.candidate?.sha256 === this.selected.sha256)
+            this.candidate = undefined;
+        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 === undefined || sha256 === undefined || sha256 === null) {
-            this.selected = { template: this.registration.template, sha256: null };
-            return this.selected.template;
+            const template = this.registration.template;
+            return { template, range: template.agentConfigReceipt?.hostAgentConfigApiRange,
+                ...(template.agentConfigReceipt?.runtimeApiRange === undefined ? {} : { runtimeApiRange: template.agentConfigReceipt.runtimeApiRange }) };
         }
-        if (digest === this.selected.template.manifest.digest
-            && (version === undefined || 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();
@@ -86,16 +140,44 @@ export class WorkspaceAgentConfigSourceOwner {
         if (manifest.digest !== digest || version !== undefined && 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 = undefined;
-        return this.selected.template;
+        const { bundleId, workspaceKey, title } = this.registration.template;
+        return { template: { bundleId, workspaceKey, title, sourceRoot: join(directory, receipt.version), manifest,
+                agentConfigSha256: receipt.sha256 }, range: receipt.hostAgentConfigApiRange,
+            ...(receipt.runtimeApiRange === undefined ? {} : { runtimeApiRange: receipt.runtimeApiRange }) };
+    }
+    assertCompatible(range, runtimeApiRange) {
+        if (range !== undefined && !semver.satisfies(HOST_AGENT_CONFIG_API_VERSION, range, { includePrerelease: true }))
+            throw new AgentConfigError('AGENT_CONFIG_INCOMPATIBLE');
+        const runtime = this.registration.source.runtimeApiVersion;
+        if (runtimeApiRange !== undefined && (runtime === undefined || !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) {
+            // stderr remains available if the Cordis reporter has already been released.
+            process.stderr.write(`${error.code}: ${error.message}\n`);
+        }
     }
-    /** 注册者调用一次以启动查询，并按配置间隔继续。 */
-    start() {
+    /** @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(() => { void tick(); }, this.spec.agentConfigPollIntervalMs);
         };
@@ -103,6 +185,9 @@ export class WorkspaceAgentConfigSourceOwner {
     }
     /** @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();
@@ -118,13 +203,22 @@ export class WorkspaceAgentConfigSourceOwner {
         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 !== undefined && this.candidate !== undefined)
+                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 = undefined;
-            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 = undefined; this.requestAbort = undefined; this.requestRevision = undefined; });
         this.inFlight = run;
         return run;
@@ -133,8 +227,31 @@ export class WorkspaceAgentConfigSourceOwner {
     template() {
         if (this.candidate !== undefined && this.candidate.revision !== this.registration.source.revision())
             this.candidate = undefined;
+        if (this.candidate === undefined && this.admissionFailure !== undefined)
+            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 !== undefined)
+            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);
@@ -143,7 +260,7 @@ export class WorkspaceAgentConfigSourceOwner {
     }
     /** @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 恢复结果决定。
@@ -153,18 +270,20 @@ export class WorkspaceAgentConfigSourceOwner {
     failedApply(template, cause) {
         if (this.candidate?.template === template)
             this.candidate = undefined;
-        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 = undefined;
         this.candidate = undefined;
         if (this.timer !== undefined)
             clearTimeout(this.timer);
-        await this.inFlight;
+        await Promise.all([this.startup, this.inFlight, this.observation?.dispose()]);
         this.candidate = undefined;
     }
     versionDirectory(version, sha256) {
@@ -173,14 +292,25 @@ export class WorkspaceAgentConfigSourceOwner {
             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 = undefined;
+            return;
+        }
+        if (error.code === 'AGENT_CONFIG_QUERY_FAILED')
+            return;
+        this.rejection = { revision, value: { code: error.code, ...(version === undefined ? {} : { version }), ...(sha256 === undefined ? {} : { sha256 }) } };
+    }
+    async fetchCandidate(revision, requestSignal, attempt) {
         const signal = AbortSignal.any([this.lifetime.signal, requestSignal, AbortSignal.timeout(this.spec.agentConfigRequestTimeoutMs)]);
         let value;
         try {
             value = await this.registration.source.query(signal);
         }
         catch (error) {
-            throw 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)
@@ -188,14 +318,22 @@ export class WorkspaceAgentConfigSourceOwner {
         if (assignment.data.source === 'builtin') {
             this.candidate = undefined;
             this.failure = null;
+            this.rejection = undefined;
             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 = undefined;
         if (descriptor.workspaceKind !== assignment.data.workspaceKind)
             throw new AgentConfigError('AGENT_CONFIG_INVALID');
-        if (descriptor.sha256 === this.selected.sha256) {
+        this.assertCompatible(descriptor.hostAgentConfigApiRange, descriptor.runtimeApiRange);
+        // Blocked journal content remains current even when the registered template has a newer digest.
+        if (descriptor.sha256 === (this.blockedVersion?.sha256 ?? this.selected.sha256)) {
             this.candidate = undefined;
             this.failure = null;
+            this.rejection = undefined;
             return;
         }
         if (descriptor.sizeBytes > this.spec.agentConfigMaxDownloadBytes)
@@ -260,9 +398,14 @@ export class WorkspaceAgentConfigSourceOwner {
             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 };
+        const { bundleId, workspaceKey, title } = this.registration.template;
+        const template = { bundleId, workspaceKey, title, sourceRoot: tree, manifest, agentConfigSha256: descriptor.sha256 };
+        await this.registration.source.validate?.(template, signal);
+        if (signal.aborted || revision !== this.registration.source.revision())
+            return;
         this.preparedRevisions.set(template, revision);
         this.candidate = { template, sha256: descriptor.sha256, revision };
         this.failure = null;
+        this.rejection = undefined;
     }
 }

package/lib/types/agent-config-types.d.ts

@@ -1,13 +1,26 @@
 /** Workspace Agent 配置版本来源和 turn 记录的 Host 接口。 */
 import type { WorkspaceBundleIdentity, WorkspaceTemplate } from './types.ts';
 import type { AgentConfigErrorCode } from './agent-config-format.ts';
+import type { WorkspaceAgentConfigObservation } from './agent-config-observation.ts';
+import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
 /** 调用方负责通过自身鉴权能力查询 server，不向此服务交出凭据。 */
 export interface WorkspaceAgentConfigSource {
     readonly identity: WorkspaceBundleIdentity;
+    /** Fixed consumer runtime API, when this module accepts descriptors with runtime requirements. */
+    readonly runtimeApiVersion?: string;
+    /** Optional authenticated module reporter; its lifetime is owned by this source registration. */
+    readonly observation?: (read: () => WorkspaceAgentConfigState) => WorkspaceAgentConfigObservation;
     /** @returns 随登录、租户或其他分配身份改变的进程内代次。 */
     revision(): number;
     /** @param signal - 源卸载或请求超时取消。 @returns #86 的 builtin / registry 分配。 */
     query(signal: AbortSignal): Promise<unknown>;
+    /**
+     * Consumer validation before candidate publication, adoption and restored execution; omission keeps generic archive checks.
+     * @param template - Verified template within this source's controlled tree.
+     * @param signal - Source disposal or request deadline.
+     * @throws AgentConfigError for invalid consumer metadata or bytes; no content may execute after failure.
+     */
+    validate?(template: WorkspaceTemplate, signal: AbortSignal): void | Promise<void>;
 }
 /** 下一个 turn 可使用的完整 Agent 配置版本，路径指向已经校验的不可变文件。 */
 export interface WorkspaceAgentConfigVersion {
@@ -18,14 +31,34 @@ export interface WorkspaceAgentConfigVersion {
     readonly templateDigest: string;
     readonly sourceRoot: string;
 }
+/** Verified content held by one activity; each retained handle owns a separate release. */
+export interface WorkspaceAgentConfigHandle extends WorkspaceAgentConfigVersion {
+    readonly workspaceId: WorkspaceId;
+    /** @returns another synchronous lease of these exact bytes, including after the parent activity ends. @throws WorkspaceBundleError when this handle was released or the Provider is unloading. */
+    retain(): WorkspaceAgentConfigHandle;
+    /** Release this activity once; retained consumers keep the content leased. */
+    release(): void;
+}
 /** 内容更新的当前可观察状态；错误只包含固定诊断。 */
 export interface WorkspaceAgentConfigState {
+    /** True when committed content has failed execution validation; current is diagnostic only until compatible replacement. */
+    readonly blocked: boolean;
+    /** Execution refusal for current content; candidate and query failures cannot clear it. */
+    readonly blockingFailure: {
+        readonly code: AgentConfigErrorCode;
+    } | null;
     readonly current: WorkspaceAgentConfigVersion;
     readonly pending: WorkspaceAgentConfigVersion | null;
     readonly failure: {
         readonly code: AgentConfigErrorCode;
         readonly message: string;
     } | null;
+    /** Latest same-scope content refusal; query/scope failures are excluded. Null means no applicable refusal. */
+    readonly lastRejection: {
+        readonly code: AgentConfigErrorCode;
+        readonly version?: string;
+        readonly sha256?: string;
+    } | null;
 }
 /** 注册时固定的内置版本；源查询失败不能使它不可用。 */
 export interface WorkspaceAgentConfigRegistration {

package/lib/types/bundled-agent-config.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import type { WorkspaceTemplate } from './types.ts';
+/** Public metadata of the exact published gzip installed as a bundled template. */
+export declare const BundledAgentConfigReceiptSchema: z.ZodObject<{
+    workspaceKind: z.ZodString;
+    version: z.ZodString;
+    sha256: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    hostAgentConfigApiRange: z.ZodString;
+    runtimeApiRange: z.ZodOptional<z.ZodString>;
+    formatVersion: z.ZodLiteral<1>;
+    templateDigest: z.ZodString;
+}, z.core.$strict>;
+/** Parsed identity and compatibility of a published bundled template. */
+export type BundledAgentConfigReceipt = z.infer<typeof BundledAgentConfigReceiptSchema>;
+/**
+ * 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.
+ */
+export declare function loadBundledAgentConfigSync(template: WorkspaceTemplate): WorkspaceTemplate;
+/**
+ * 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.
+ */
+export declare function journalAgentConfigSha256(template: WorkspaceTemplate, registered: WorkspaceTemplate | undefined): string | null;

package/lib/types/bundled-agent-config.js

@@ -0,0 +1,47 @@
+/** Published package receipts beside shipped templates, separate from model-visible files. */
+import { readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { z } from 'zod';
+import { AgentConfigDescriptorSchema, AgentConfigError, AgentConfigSha256 } from "./agent-config-format.js";
+/** Public metadata of the exact published gzip installed as a bundled template. */
+export 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.
+ */
+export 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.
+ */
+export function journalAgentConfigSha256(template, registered) {
+    return template === registered ? null : template.agentConfigSha256 ?? null;
+}

package/lib/types/definition.d.ts

@@ -1,8 +1,10 @@
 /** `WorkspaceBundles` Service Definition: Host-only template registration and stable Workspace materialize. */
+import { type LocalHostReplacement } from './local-host-replacement.ts';
+import { type LocalHostIdentity } from './local-host-identity.ts';
 import { Context, Service } from '@deepseek-ai/cordis';
 import type { Workspace, WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
 import type { WorkspaceBundleIdentity, WorkspaceBundleRecord, WorkspaceTemplate } from './types.ts';
-import type { WorkspaceAgentConfigSource, WorkspaceAgentConfigState } from './agent-config-types.ts';
+import type { WorkspaceAgentConfigHandle, WorkspaceAgentConfigSource, WorkspaceAgentConfigState } from './agent-config-types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         /** Bundled Workspace templates and their stable materialize. */
@@ -22,8 +24,12 @@ declare module '@deepseek-ai/cordis' {
  * replace its tree as a whole. Registration is an effect; the returned disposer forbids later acquire.
  */
 export declare abstract class WorkspaceBundles extends Service {
-    /** @param ctx - context owning this Provider. */
-    constructor(ctx: Context);
+    /** One member-level fence shared by every local module. */
+    readonly localHostReplacement: LocalHostReplacement;
+    /** One persisted local Host identity per server and member, published by the module that owns the installation identity. */
+    readonly localHostIdentity: 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: Context, replacementPath?: string | null, identityPath?: string | null);
     /**
      * Make a template available for {@link ensure} and {@link acquire}.
      * @param template - verified catalog and source root.
@@ -36,7 +42,7 @@ export declare abstract class WorkspaceBundles extends Service {
      * @returns 撤销轮询并等待下载停止的 disposer。
      */
     abstract registerAgentConfigSource(source: WorkspaceAgentConfigSource): () => Promise<void>;
-    /** @param identity - 内置 Workspace 身份。 @returns 已安装版本、候选和固定失败诊断；未注册来源时为 undefined。 */
+    /** @param identity - 内置 Workspace 身份。 @returns 已安装版本、候选、执行阻断、固定诊断与同作用域最近拒绝；blocked 时 current 只供诊断，未注册来源时为 undefined。 */
     abstract agentConfig(identity: WorkspaceBundleIdentity): WorkspaceAgentConfigState | undefined;
     /** @param identity - 内置 Workspace 身份。 @returns 该来源本次查询与下载完成，失败保留在 agentConfig 中。 */
     abstract refreshAgentConfig(identity: WorkspaceBundleIdentity): Promise<void>;
@@ -45,6 +51,7 @@ export declare abstract class WorkspaceBundles extends Service {
      * Unchanged trees reuse the existing Workspace id and path.
      * @param identity - branded pair.
      * @returns the Workspace after the tree is wholly old or wholly new.
+     * @throws AgentConfigError when committed remote content cannot execute; only a compatible validated candidate may repair it.
      */
     abstract ensure(identity: WorkspaceBundleIdentity): Promise<Workspace>;
     /**
@@ -53,6 +60,13 @@ export declare abstract class WorkspaceBundles extends Service {
      * @returns disposer of the lease.
      */
     abstract acquire(workspaceId: WorkspaceId): Promise<() => void>;
+    /**
+     * Adopt and verify content, then lease its exact identity before another adoption can run.
+     * @param identity - registered bundled Workspace.
+     * @returns a handle whose immutable source root and version match the committed Workspace; release after all activity and persistence finish.
+     * @throws WorkspaceBundleError or AgentConfigError when registration, content, scope or compatibility validation fails; no lease is returned.
+     */
+    abstract acquireAgentConfig(identity: WorkspaceBundleIdentity): Promise<WorkspaceAgentConfigHandle>;
     /**
      * Read the durable product record when one exists.
      * @param identity - branded pair.

package/lib/types/definition.js

@@ -1,12 +1,20 @@
 /** `WorkspaceBundles` Service Definition: Host-only template registration and stable Workspace materialize. */
+import { LocalHostReplacementState } from "./local-host-replacement.js";
+import { LocalHostIdentityState } from "./local-host-identity.js";
 import { Service } from '@deepseek-ai/cordis';
 /**
  * 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.
  */
 export class WorkspaceBundles 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);
     }
 }

package/lib/types/index.d.ts

@@ -15,6 +15,14 @@ export type * from './types.ts';
 export type * from './agent-config-types.ts';
 export type { WorkspaceAgentConfigVersionEvent } from './session-events.ts';
 export { recordWorkspaceAgentConfigVersion } from './session-events.ts';
-export { HOST_AGENT_CONFIG_API_VERSION, AgentConfigError, agentConfigSha256, decodeAgentConfig, AgentConfigDescriptorSchema } from './agent-config-format.ts';
+export { HOST_AGENT_CONFIG_API_VERSION, AgentConfigError, agentConfigSha256, decodeAgentConfig, AgentConfigDescriptorSchema, isAgentConfigVersion } from './agent-config-format.ts';
 export type { AgentConfigDescriptor, AgentConfigErrorCode } from './agent-config-format.ts';
+export { BundledAgentConfigReceiptSchema, loadBundledAgentConfigSync } from './bundled-agent-config.ts';
+export type { BundledAgentConfigReceipt } from './bundled-agent-config.ts';
 export default GestaltWorkspaceBundles;
+export { getModuleAgentConfigAssignment } from './agent-config-contract/agent-configs.ts';
+export { agentConfigHostObservation, sandboxAgentConfigHostObservation } from './agent-config-observation.ts';
+export type { WorkspaceAgentConfigObservation, WorkspaceAgentConfigObservationOptions, WorkspaceAgentConfigHostId, WorkspaceAgentConfigSandbox } from './agent-config-observation.ts';
+export type { LocalHostReplacement, LocalHostMember } from './local-host-replacement.ts';
+export { LocalHostIdentityLoadError, LocalHostIdentityWriteError, sharedLocalHostId } from './local-host-identity.ts';
+export type { LocalHostIdentity, LocalHostIdentityScope, LocalHostIdentitySources, LocalHostIdentityValue } from './local-host-identity.ts';

package/lib/types/index.js

@@ -11,5 +11,9 @@ export { encodeBundleSegment, bundledDirectory, assertTemplateRelativePath, iden
 export { createNodeFs, crashableFs } from "./filesystem.js";
 export { GestaltWorkspaceBundles } from "./provider.js";
 export { recordWorkspaceAgentConfigVersion } from "./session-events.js";
-export { HOST_AGENT_CONFIG_API_VERSION, AgentConfigError, agentConfigSha256, decodeAgentConfig, AgentConfigDescriptorSchema } from "./agent-config-format.js";
+export { HOST_AGENT_CONFIG_API_VERSION, AgentConfigError, agentConfigSha256, decodeAgentConfig, AgentConfigDescriptorSchema, isAgentConfigVersion } from "./agent-config-format.js";
+export { BundledAgentConfigReceiptSchema, loadBundledAgentConfigSync } from "./bundled-agent-config.js";
 export default GestaltWorkspaceBundles;
+export { getModuleAgentConfigAssignment } from "./agent-config-contract/agent-configs.js";
+export { agentConfigHostObservation, sandboxAgentConfigHostObservation } from "./agent-config-observation.js";
+export { LocalHostIdentityLoadError, LocalHostIdentityWriteError, sharedLocalHostId } from "./local-host-identity.js";