@gestaltrun/dsh-workspace-bundle 0.1.0 → 0.1.1

package/lib/types/local-host-identity.d.ts

@@ -0,0 +1,65 @@
+import type { MerchantHostIdentity } from '@gestaltrun/dsh-merchant-account';
+import type { WorkspaceAgentConfigHostId } from './agent-config-observation.ts';
+/** Server and member whose local modules report under one identity; the server keeps one current local Host per member and module. */
+export type LocalHostIdentityScope = Pick<MerchantHostIdentity, 'serverOrigin' | 'userId'>;
+/** Identity read from its owning module when a queued publish commits. */
+export interface LocalHostIdentityValue {
+    readonly hostId: WorkspaceAgentConfigHostId;
+    /** The server confirmed this identity against the installation key; a confirmed identity is never replaced. */
+    readonly confirmed: boolean;
+}
+/** Shared identity exposed by the WorkspaceBundles owner. */
+export interface LocalHostIdentity {
+    /** @param scope - signed-in server and member. @returns the persisted identity, or undefined before its owner published one. */
+    get(scope: LocalHostIdentityScope): WorkspaceAgentConfigHostId | undefined;
+    /**
+     * Persist the owner's identity after earlier publishes; readers observe it only after the write succeeds.
+     * A different identity replaces only an unconfirmed one, so readers never return to an identity the server already replaced.
+     * @param scope - member the identity belongs to.
+     * @param read - owner's identity for that scope, read when this publish commits; undefined skips the write, for an owner disposed meanwhile.
+     * @returns whether readers now observe a different identity.
+     */
+    publish(scope: LocalHostIdentityScope, read: () => LocalHostIdentityValue | undefined): Promise<boolean>;
+}
+/** Load stops instead of letting modules report under their own identities, which the server may already have replaced. */
+export declare class LocalHostIdentityLoadError extends Error {
+    /** @param path - state file that could not be read or parsed. @param cause - underlying read or validation failure. */
+    constructor(path: string, cause: unknown);
+}
+/** The previous identity remains visible; the owner reports this failure and keeps its own reporting. */
+export declare class LocalHostIdentityWriteError extends Error {
+    /** @param cause - underlying private filesystem failure. */
+    constructor(cause: unknown);
+}
+/** Loads synchronously so the first module report already reads the persisted identity. */
+export declare class LocalHostIdentityState implements LocalHostIdentity {
+    private readonly path;
+    private state;
+    private writes;
+    /** @param path - owner-only state file; null creates an explicit in-memory owner. An unreadable or invalid file fails load instead of exposing no identity. */
+    constructor(path: string | null);
+    /** @inheritdoc */
+    get(scope: LocalHostIdentityScope): WorkspaceAgentConfigHostId | undefined;
+    /** @inheritdoc */
+    publish(scope: LocalHostIdentityScope, read: () => LocalHostIdentityValue | undefined): Promise<boolean>;
+    private save;
+}
+/** Merchant session and WorkspaceBundles members read by {@link sharedLocalHostId}; a Host context satisfies it. */
+export interface LocalHostIdentitySources {
+    readonly merchantAccount: {
+        captureIdentity(): {
+            readonly identity: LocalHostIdentityScope;
+        } | null;
+    };
+    readonly workspaceBundles: {
+        readonly localHostIdentity: LocalHostIdentity;
+    };
+}
+/**
+ * Identity getter for a local module reporter: the shared identity of the signed-in member, otherwise the module's own identity.
+ * Pass it as `hostId` and keep the fallback fixed; once an identity is shared, the reporter never returns to the fallback.
+ * @param ctx - context with the merchant session and WorkspaceBundles.
+ * @param fallback - module identity used before any local module published a shared one.
+ * @returns getter read before each registration.
+ */
+export declare function sharedLocalHostId(ctx: LocalHostIdentitySources, fallback: WorkspaceAgentConfigHostId): () => WorkspaceAgentConfigHostId;

package/lib/types/local-host-identity.js

@@ -0,0 +1,87 @@
+/** One durable local Host identity per server and member, reused by every local module observation. */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { brandString } from '@deepseek-ai/dsh-brand';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { z } from 'zod';
+const State = z.strictObject({ version: z.literal(1), scopes: z.record(z.string().regex(/^[a-f0-9]{64}$/u), z.strictObject({ hostId: z.uuid(), confirmed: z.boolean() })) });
+function keyOf(scope) {
+    return createHash('sha256').update(JSON.stringify([scope.serverOrigin, scope.userId])).digest('hex');
+}
+/** Load stops instead of letting modules report under their own identities, which the server may already have replaced. */
+export class LocalHostIdentityLoadError extends Error {
+    /** @param path - state file that could not be read or parsed. @param cause - underlying read or validation failure. */
+    constructor(path, cause) {
+        super(`The shared local Host identity file ${path} cannot be read or is invalid. Restore it from a backup or fix its permissions; deleting it makes local modules report under their own identities and may require reactivating local hosting.`, { cause });
+    }
+}
+/** The previous identity remains visible; the owner reports this failure and keeps its own reporting. */
+export class LocalHostIdentityWriteError extends Error {
+    /** @param cause - underlying private filesystem failure. */
+    constructor(cause) { super('LOCAL_HOST_IDENTITY_WRITE_FAILED', { cause }); }
+}
+/** Loads synchronously so the first module report already reads the persisted identity. */
+export class LocalHostIdentityState {
+    path;
+    state = { version: 1, scopes: {} };
+    writes = Promise.resolve();
+    /** @param path - owner-only state file; null creates an explicit in-memory owner. An unreadable or invalid file fails load instead of exposing no identity. */
+    constructor(path) {
+        this.path = path;
+        if (path === null)
+            return;
+        try {
+            this.state = State.parse(JSON.parse(readFileSync(path, 'utf8')));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw new LocalHostIdentityLoadError(path, error);
+        }
+    }
+    /** @inheritdoc */
+    get(scope) {
+        const entry = this.state.scopes[keyOf(scope)];
+        return entry === undefined ? undefined : brandString(entry.hostId);
+    }
+    /** @inheritdoc */
+    publish(scope, read) {
+        const work = this.writes.then(async () => {
+            const key = keyOf(scope), previous = this.state.scopes[key], next = read();
+            if (next === undefined)
+                return false;
+            if (previous !== undefined && (previous.hostId === next.hostId ? previous.confirmed || !next.confirmed : previous.confirmed))
+                return false;
+            const state = { ...this.state, scopes: { ...this.state.scopes, [key]: { hostId: next.hostId, confirmed: next.confirmed } } };
+            await this.save(state);
+            this.state = state;
+            return previous?.hostId !== next.hostId;
+        });
+        // Each returned publish reports its own failure; later publishes must still run.
+        this.writes = work.then(() => { }, (error) => { void error; });
+        return work;
+    }
+    async save(state) {
+        if (this.path === null)
+            return;
+        try {
+            await writeFileAtomic(this.path, JSON.stringify(state) + '\n', { mode: 0o600, dirMode: 0o700 });
+        }
+        catch (error) {
+            throw new LocalHostIdentityWriteError(error);
+        }
+    }
+}
+/**
+ * Identity getter for a local module reporter: the shared identity of the signed-in member, otherwise the module's own identity.
+ * Pass it as `hostId` and keep the fallback fixed; once an identity is shared, the reporter never returns to the fallback.
+ * @param ctx - context with the merchant session and WorkspaceBundles.
+ * @param fallback - module identity used before any local module published a shared one.
+ * @returns getter read before each registration.
+ */
+export function sharedLocalHostId(ctx, fallback) {
+    return () => {
+        const scope = ctx.merchantAccount.captureIdentity()?.identity;
+        return (scope === undefined ? undefined : ctx.workspaceBundles.localHostIdentity.get(scope)) ?? fallback;
+    };
+}

package/lib/types/local-host-replacement.d.ts

@@ -0,0 +1,49 @@
+import type { AgentConfigModule } from './agent-config-contract/agent-configs.ts';
+import type { MerchantHostIdentity } from '@gestaltrun/dsh-merchant-account';
+/** Server, member and selected shop whose local modules share one activation decision. */
+export type LocalHostMember = Pick<MerchantHostIdentity, 'serverOrigin' | 'userId' | 'currentTenantId'>;
+/** Shared member fence exposed by the WorkspaceBundles owner. */
+export interface LocalHostReplacement {
+    /** @param member - current member. @returns whether explicit activation is required. */
+    isReplaced(member: LocalHostMember): boolean;
+    /** @param listener - reacts to changes. @returns its disposer. */
+    subscribe(listener: () => void): () => void;
+    /** Stop immediately in memory, then persist; a rejection keeps the stop and permits the next call to retry. @param member - rejected member. @returns completion of the durable write. */
+    markReplaced(member: LocalHostMember): Promise<void>;
+    /** @param member - member whose two modules have acknowledged activation. @returns completion of the durable clear; failure keeps reception stopped. */
+    activate(member: LocalHostMember): Promise<void>;
+    /** @param member - current member. @param module - legacy source. @returns whether its state was imported. */
+    migrated(member: LocalHostMember, module: AgentConfigModule): boolean;
+    /** @param member - current member. @param module - legacy source. @param replaced - previous stop flag. @returns completion before any legacy marker may be removed. */
+    importLegacy(member: LocalHostMember, module: AgentConfigModule, replaced: boolean): Promise<void>;
+}
+/** The memory fence remains active; callers retain fallback markers and report this failure. */
+export declare class LocalHostReplacementWriteError extends Error {
+    /** @param cause - underlying private filesystem failure. */
+    constructor(cause: unknown);
+}
+/** Shared by module reporters, lease supervision and checkpoints within one Host. */
+export declare class LocalHostReplacementState implements LocalHostReplacement {
+    private readonly path;
+    private state;
+    private readonly listeners;
+    private persisted;
+    private writes;
+    private readonly rejections;
+    /** @param path - owner-only state file; null creates an explicit in-memory owner. */
+    constructor(path: string | null);
+    /** @param member - current authenticated member. @returns whether explicit activation is required. */
+    isReplaced(member: LocalHostMember): boolean;
+    /** @param listener - reacts to a changed fence. @returns its disposer. */
+    subscribe(listener: () => void): () => void;
+    /** @param member - rejected member. Stops consumers before persistence starts. @returns durable completion; failure permits a later retry. */
+    markReplaced(member: LocalHostMember): Promise<void>;
+    /** @param member - member whose two module registrations have both been acknowledged. @returns durable completion, unless a newer rejection requires another activation. */
+    activate(member: LocalHostMember): Promise<void>;
+    /** @param member - current member. @param module - module whose legacy files were inspected. @returns whether migration is complete. */
+    migrated(member: LocalHostMember, module: AgentConfigModule): boolean;
+    /** @param member - current member. @param module - legacy source. @param replaced - whether any prior installation was stopped. @returns durable completion before the caller removes fallback flags. */
+    importLegacy(member: LocalHostMember, module: AgentConfigModule, replaced: boolean): Promise<void>;
+    private enqueue;
+    private save;
+}

package/lib/types/local-host-replacement.js

@@ -0,0 +1,112 @@
+/** One durable replacement fence per authenticated shop member, independent of installation and module. */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { z } from 'zod';
+const State = z.strictObject({ version: z.literal(1), replaced: z.array(z.string().regex(/^[a-f0-9]{64}$/u)), migrated: z.array(z.string().regex(/^[a-f0-9]{64}\/(cs-hosting|resource-intake)$/u)) });
+function keyOf(member) {
+    return createHash('sha256').update(JSON.stringify([member.serverOrigin, member.userId, member.currentTenantId])).digest('hex');
+}
+/** The memory fence remains active; callers retain fallback markers and report this failure. */
+export class LocalHostReplacementWriteError extends Error {
+    /** @param cause - underlying private filesystem failure. */
+    constructor(cause) { super('LOCAL_HOST_REPLACEMENT_WRITE_FAILED', { cause }); }
+}
+/** Shared by module reporters, lease supervision and checkpoints within one Host. */
+export class LocalHostReplacementState {
+    path;
+    state = { version: 1, replaced: [], migrated: [] };
+    listeners = new Set();
+    persisted = this.state;
+    writes = Promise.resolve();
+    rejections = new Map();
+    /** @param path - owner-only state file; null creates an explicit in-memory owner. */
+    constructor(path) {
+        this.path = path;
+        if (path === null)
+            return;
+        try {
+            this.state = State.parse(JSON.parse(readFileSync(path, 'utf8')));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        this.persisted = this.state;
+    }
+    /** @param member - current authenticated member. @returns whether explicit activation is required. */
+    isReplaced(member) { return this.state.replaced.includes(keyOf(member)); }
+    /** @param listener - reacts to a changed fence. @returns its disposer. */
+    subscribe(listener) { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; }
+    /** @param member - rejected member. Stops consumers before persistence starts. @returns durable completion; failure permits a later retry. */
+    markReplaced(member) {
+        const key = keyOf(member);
+        this.rejections.set(key, (this.rejections.get(key) ?? 0) + 1);
+        if (!this.state.replaced.includes(key)) {
+            this.state = { ...this.state, replaced: [...this.state.replaced, key] };
+            for (const listener of this.listeners)
+                listener();
+        }
+        if (this.persisted === this.state)
+            return Promise.resolve();
+        return this.enqueue(async () => {
+            const state = this.state;
+            await this.save(state);
+            this.persisted = state;
+        });
+    }
+    /** @param member - member whose two module registrations have both been acknowledged. @returns durable completion, unless a newer rejection requires another activation. */
+    activate(member) {
+        const key = keyOf(member), rejection = this.rejections.get(key);
+        if (!this.state.replaced.includes(key))
+            return Promise.resolve();
+        this.persisted = undefined;
+        return this.enqueue(async () => {
+            const previous = this.state;
+            if (!previous.replaced.includes(key))
+                return;
+            if (this.rejections.get(key) !== rejection)
+                throw new Error('LOCAL_HOST_REPLACED');
+            const next = { ...previous, replaced: previous.replaced.filter(value => value !== key) };
+            await this.save(next);
+            if (this.state !== previous || this.rejections.get(key) !== rejection) {
+                await this.save(this.state);
+                throw new Error('LOCAL_HOST_REPLACED');
+            }
+            this.persisted = this.state = next;
+            for (const listener of this.listeners)
+                listener();
+        });
+    }
+    /** @param member - current member. @param module - module whose legacy files were inspected. @returns whether migration is complete. */
+    migrated(member, module) { return this.state.migrated.includes(`${keyOf(member)}/${module}`); }
+    /** @param member - current member. @param module - legacy source. @param replaced - whether any prior installation was stopped. @returns durable completion before the caller removes fallback flags. */
+    async importLegacy(member, module, replaced) {
+        if (replaced)
+            await this.markReplaced(member);
+        if (this.migrated(member, module))
+            return;
+        this.state = { ...this.state, migrated: [...this.state.migrated, `${keyOf(member)}/${module}`] };
+        await this.enqueue(async () => {
+            const state = this.state;
+            await this.save(state);
+            this.persisted = state;
+        });
+    }
+    enqueue(write) {
+        const work = this.writes.then(write);
+        // Each returned operation reports its own failure; later writes must still run.
+        this.writes = work.catch((error) => { void error; });
+        return work;
+    }
+    async save(state) {
+        if (this.path === null)
+            return;
+        try {
+            await writeFileAtomic(this.path, JSON.stringify(state) + '\n', { mode: 0o600, dirMode: 0o700 });
+        }
+        catch (error) {
+            throw new LocalHostReplacementWriteError(error);
+        }
+    }
+}

package/lib/types/provider.d.ts

@@ -2,7 +2,7 @@ import { Context } from '@deepseek-ai/cordis';
 import type { Workspace, WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
 import { Config } from './config.ts';
 import { WorkspaceBundles } from './definition.ts';
-import type { WorkspaceAgentConfigSource, WorkspaceAgentConfigState } from './agent-config-types.ts';
+import type { WorkspaceAgentConfigHandle, WorkspaceAgentConfigSource, WorkspaceAgentConfigState } from './agent-config-types.ts';
 import type { WorkspaceBundleCrashPoint, WorkspaceBundleFs, WorkspaceBundleIdentity, WorkspaceBundleRecord, WorkspaceBundlesSpec, WorkspaceTemplate } from './types.ts';
 /** Provider for packaged Workspace templates. */
 export declare class GestaltWorkspaceBundles extends WorkspaceBundles {
@@ -19,6 +19,7 @@ export declare class GestaltWorkspaceBundles extends WorkspaceBundles {
     private chain;
     private readonly recycle;
     private readonly recycleWork;
+    private readonly contentDrains;
     private closed;
     private readonly download;
     /**
@@ -45,7 +46,11 @@ export declare class GestaltWorkspaceBundles extends WorkspaceBundles {
     refreshAgentConfig(identity: WorkspaceBundleIdentity): Promise<void>;
     /** @inheritdoc */
     acquire(workspaceId: WorkspaceId): Promise<() => void>;
+    /** @inheritdoc */
+    acquireAgentConfig(identity: WorkspaceBundleIdentity): Promise<WorkspaceAgentConfigHandle>;
+    private contentHandle;
     private acquireOne;
+    private holdLease;
     /** @inheritdoc */
     record(identity: WorkspaceBundleIdentity): WorkspaceBundleRecord | undefined;
     /** @inheritdoc */
@@ -54,6 +59,7 @@ export declare class GestaltWorkspaceBundles extends WorkspaceBundles {
      * Replay an interrupted journal before serving the Workspace.
      * @param identity - branded pair.
      * @throws {WorkspaceBundleError} Before any rename or deletion if stored paths differ from this identity's controlled paths.
+     * @throws {AgentConfigError} After physical recovery when committed content fails compatibility or consumer validation.
      */
     recover(identity: WorkspaceBundleIdentity): Promise<Workspace | undefined>;
     private enqueue;

package/lib/types/provider.js

@@ -3,6 +3,7 @@
  * hidden Workspace, and replace its tree as a whole with crash recovery.
  */
 import { join } from 'node:path';
+import { journalAgentConfigSha256 } from "./bundled-agent-config.js";
 import { brandString } from '@deepseek-ai/dsh-brand';
 import { Config, resolveWorkspaceBundlesSpec } from "./config.js";
 import { WorkspaceBundles } from "./definition.js";
@@ -12,7 +13,7 @@ import { crashableFs, createNodeFs } from "./filesystem.js";
 import { assertRecordPaths, committedRecord, idleJournal, readRecord, recordPath, writeJournal, writeRecord } from "./journal.js";
 import { bundledDirectory, identityOf } from "./paths.js";
 import { WorkspaceAgentConfigSourceOwner } from "./agent-config-source.js";
-import { AgentConfigError } from "./agent-config-format.js";
+import { AgentConfigError, HOST_AGENT_CONFIG_API_VERSION } from "./agent-config-format.js";
 function keyOf(identity) {
     return `${identity.bundleId}/${identity.workspaceKey}`;
 }
@@ -44,6 +45,7 @@ export class GestaltWorkspaceBundles extends WorkspaceBundles {
     chain = Promise.resolve();
     recycle = new Map();
     recycleWork = new Map();
+    contentDrains = new Set();
     closed = false;
     download;
     /**
@@ -54,8 +56,9 @@ export class GestaltWorkspaceBundles extends WorkspaceBundles {
      * @param options.fetch - 文件 HTTP 传输；默认使用 Host fetch。
      */
     constructor(ctx, config = {}, options = {}) {
-        super(ctx);
-        this.spec = resolveWorkspaceBundlesSpec(config);
+        const spec = resolveWorkspaceBundlesSpec(config);
+        super(ctx, join(spec.journalRoot, 'local-host-replacement.json'), join(spec.journalRoot, 'local-host-identity.json'));
+        this.spec = spec;
         this.fs = crashableFs(options.fs ?? createNodeFs(), options.crashAt);
         this.download = options.fetch ?? fetch;
         ctx.effect(() => async () => {
@@ -65,6 +68,7 @@ export class GestaltWorkspaceBundles extends WorkspaceBundles {
             this.recycle.clear();
             await Promise.all([...this.agentConfigSources.values()].map(source => source.dispose()));
             await this.chain;
+            await Promise.all(this.contentDrains);
             await Promise.all(this.recycleWork.values());
             this.agentConfigSources.clear();
         }, 'workspace-bundle: recycle timers');
@@ -105,9 +109,28 @@ export class GestaltWorkspaceBundles extends WorkspaceBundles {
             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.download, () => this.enqueue(async () => {
+            if (this.closed || this.agentConfigSources.get(key) !== owner)
+                return;
+            const state = owner.state();
+            const record = this.records.get(key);
+            if (!state.blocked || state.pending === null || record?.workspaceId != null && (this.leases.get(record.workspaceId)?.size ?? 0) > 0)
+                return;
+            await this.ensureOne(source.identity);
+        }));
         this.agentConfigSources.set(key, owner);
-        owner.start();
+        owner.start(() => this.enqueue(async () => {
+            await this.recoverOne(source.identity);
+            const record = this.records.get(key);
+            try {
+                await owner.recover(record?.templateDigest, record?.pluginVersion, record?.agentConfigSha256);
+            }
+            catch (error) {
+                // A refused committed version remains reportable, but cannot grant execution.
+                if (!(error instanceof AgentConfigError))
+                    throw error;
+            }
+        }));
         return async () => {
             await owner.dispose();
             if (this.agentConfigSources.get(key) === owner)
@@ -134,6 +157,64 @@ export class GestaltWorkspaceBundles extends WorkspaceBundles {
         }
         return this.enqueue(() => this.acquireOne(workspaceId));
     }
+    /** @inheritdoc */
+    acquireAgentConfig(identity) {
+        if (this.closed)
+            return Promise.reject(new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'Workspace content service is stopped'));
+        identityOf(identity.bundleId, identity.workspaceKey);
+        return this.enqueue(async () => {
+            if (this.closed)
+                throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'Workspace content service is stopped');
+            const registered = this.requireTemplate(identity);
+            const source = this.agentConfigSources.get(keyOf(identity));
+            const revision = source?.registration.source.revision();
+            const workspace = await this.ensureOne(identity);
+            const record = this.records.get(keyOf(identity));
+            const template = source === undefined ? this.requireTemplate(identity)
+                : await source.recover(record.templateDigest, record.pluginVersion, record.agentConfigSha256);
+            await verifyTemplateTree(this.fs, template.sourceRoot, template.manifest);
+            if (this.closed)
+                throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'Workspace content service is stopped');
+            if (this.requireTemplate(identity) !== registered || this.agentConfigSources.get(keyOf(identity)) !== source
+                || source?.registration.source.revision() !== revision) {
+                throw new AgentConfigError('AGENT_CONFIG_SCOPE_CHANGED');
+            }
+            if (template.manifest.digest !== record.templateDigest || template.manifest.pluginVersion !== record.pluginVersion) {
+                throw new AgentConfigError('AGENT_CONFIG_INVALID');
+            }
+            const version = { workspaceKind: identity.bundleId, workspaceId: workspace.id, version: record.pluginVersion,
+                sha256: template.agentConfigSha256 ?? null, hostAgentConfigApiVersion: HOST_AGENT_CONFIG_API_VERSION,
+                templateDigest: record.templateDigest, sourceRoot: template.sourceRoot };
+            return this.contentHandle(version, this.holdLease(workspace.id));
+        });
+    }
+    contentHandle(version, release) {
+        let references = 0;
+        const drained = Promise.withResolvers();
+        this.contentDrains.add(drained.promise);
+        const retain = () => {
+            references++;
+            let released = false;
+            return Object.freeze({ ...version,
+                retain: () => {
+                    if (released || this.closed)
+                        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'The content activity is closed');
+                    return retain();
+                },
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    if (--references === 0) {
+                        release();
+                        this.contentDrains.delete(drained.promise);
+                        drained.resolve();
+                    }
+                },
+            });
+        };
+        return retain();
+    }
     async acquireOne(workspaceId) {
         const record = [...this.records.values()].find(item => item.workspaceId === workspaceId);
         if (record === undefined || !record.registered) {
@@ -145,6 +226,10 @@ export class GestaltWorkspaceBundles extends WorkspaceBundles {
         if ((this.leases.get(workspaceId)?.size ?? 0) === 0 && this.agentConfigSources.has(keyOf(record))) {
             await this.ensureOne(record);
         }
+        this.agentConfigSources.get(keyOf(record))?.assertExecutionAllowed();
+        return this.holdLease(workspaceId);
+    }
+    holdLease(workspaceId) {
         const token = Symbol('workspace-bundle-lease');
         let leases = this.leases.get(workspaceId);
         if (leases === undefined) {
@@ -175,9 +260,15 @@ export class GestaltWorkspaceBundles extends WorkspaceBundles {
      * Replay an interrupted journal before serving the Workspace.
      * @param identity - branded pair.
      * @throws {WorkspaceBundleError} Before any rename or deletion if stored paths differ from this identity's controlled paths.
+     * @throws {AgentConfigError} After physical recovery when committed content fails compatibility or consumer validation.
      */
     async recover(identity) {
-        return this.enqueue(() => this.recoverOne(identity));
+        return this.enqueue(async () => {
+            const workspace = await this.recoverOne(identity);
+            const record = this.records.get(keyOf(identity));
+            await this.agentConfigSources.get(keyOf(identity))?.recover(record?.templateDigest, record?.pluginVersion, record?.agentConfigSha256);
+            return workspace;
+        });
     }
     enqueue(work) {
         const run = this.chain.then(work, work);
@@ -187,23 +278,30 @@ export class GestaltWorkspaceBundles extends WorkspaceBundles {
     async ensureOne(identity) {
         let template = this.requireTemplate(identity);
         const source = this.agentConfigSources.get(keyOf(identity));
-        const stored = this.records.get(keyOf(identity)) ?? await this.loadStored(identity);
-        if (source !== undefined) {
-            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 !== undefined)
-            template = await source.recover(record?.templateDigest, record?.pluginVersion, record?.agentConfigSha256);
+        if (source !== undefined) {
+            try {
+                template = await source.recover(record?.templateDigest, record?.pluginVersion, record?.agentConfigSha256);
+            }
+            catch (error) {
+                // An unusable committed tree stays on disk; only a validated candidate may replace it.
+                if (!(error instanceof AgentConfigError) || record?.workspaceId !== null && record?.workspaceId !== undefined
+                    && (this.leases.get(record.workspaceId)?.size ?? 0) > 0)
+                    throw error;
+                template = source.template();
+            }
+        }
         if (source !== undefined && (record?.workspaceId === null || record?.workspaceId === undefined
             || (this.leases.get(record.workspaceId)?.size ?? 0) === 0))
             template = source.template();
         if (recovered !== undefined && record !== undefined
             && record.templateDigest === template.manifest.digest && record.pluginVersion === template.manifest.pluginVersion
-            && (record.agentConfigSha256 ?? null) === (template.agentConfigSha256 ?? null) && record.journal.phase === 'idle') {
+            && (record.agentConfigSha256 ?? null) === journalAgentConfigSha256(template, this.requireTemplate(identity)) && record.journal.phase === 'idle') {
             return recovered;
         }
         try {
+            await source?.prepare(template);
             const workspace = await this.replace(template, record, source === undefined ? undefined : () => source.assertApplicable(template));
             await source?.committed(template);
             return workspace;
@@ -317,10 +415,10 @@ export class GestaltWorkspaceBundles extends WorkspaceBundles {
         try {
             const source = this.agentConfigSources.get(keyOf(identity));
             if (source !== undefined && toDigest !== null)
-                template = await source.recover(toDigest, record.journal.pluginVersion ?? undefined, record.journal.agentConfigSha256);
+                template = await source.recoverPhysical(toDigest, record.journal.pluginVersion ?? undefined, record.journal.agentConfigSha256);
             if (template !== undefined && toDigest === template.manifest.digest) {
                 await verifyTemplateTree(this.fs, root, template.manifest);
-                return this.commit(identity, record, template);
+                return await this.commit(identity, record, template);
             }
             if (toDigest !== null && template === undefined) {
                 const cached = bundledDirectory(this.spec.templateCacheRoot, identity);
@@ -331,11 +429,11 @@ export class GestaltWorkspaceBundles extends WorkspaceBundles {
                         bundleId: identity.bundleId, workspaceKey: identity.workspaceKey, title: 'Workspace',
                         sourceRoot: cached, manifest,
                     };
-                    return this.commit(identity, record, synthetic);
+                    return await this.commit(identity, record, synthetic);
                 }
             }
         }
-        catch {
+        catch (error) {
             // Fall through to restore the backup; the tree must be wholly old or wholly new.
         }
         return this.restoreOld(identity, record);
@@ -375,7 +473,7 @@ export class GestaltWorkspaceBundles extends WorkspaceBundles {
             stagingPath: staging,
             backupPath: await this.fs.exists(root) ? backup : null,
             swapComplete: false,
-            ...(template.agentConfigSha256 === undefined ? {} : { agentConfigSha256: template.agentConfigSha256 }),
+            agentConfigSha256: journalAgentConfigSha256(template, this.requireTemplate(identity)),
         };
         const updating = await writeJournal(this.fs, this.recordFile(identity), { ...record, registered: true, path: root }, journal);
         this.records.set(keyOf(identity), updating);
@@ -409,7 +507,7 @@ export class GestaltWorkspaceBundles extends WorkspaceBundles {
     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 } : {}),
+            agentConfigSha256: journalAgentConfigSha256(template, this.templates.get(keyOf(identity))),
         }, template.manifest.digest, template.manifest.pluginVersion);
         await writeRecord(this.fs, this.recordFile(identity), next);
         this.records.set(keyOf(identity), next);

package/lib/types/types.d.ts

@@ -1,6 +1,7 @@
 /** Client-safe types of the WorkspaceBundles seam; importing them loads no Host code. */
 import type { Branded } from '@deepseek-ai/dsh-brand';
 import type { WorkspaceBundleId, WorkspaceBundleKey, WorkspaceId, WorkspaceOrigin } from '@deepseek-ai/dsh-workspace/types';
+import type { BundledAgentConfigReceipt } from './bundled-agent-config.ts';
 export type { WorkspaceBundleId, WorkspaceBundleKey, WorkspaceId, WorkspaceOrigin };
 /** SHA-256 hex digest of one template file. */
 export type WorkspaceTemplateFileDigest = Branded<'WorkspaceTemplateFileDigest'>;
@@ -32,8 +33,10 @@ export interface WorkspaceTemplate {
     readonly title: string;
     readonly sourceRoot: string;
     readonly manifest: WorkspaceTemplateManifest;
-    /** 已下载包的整体摘要；内置模板不携带此字段。 */
+    /** Published gzip digest for downloaded or bundled content; absent for repository templates. */
     readonly agentConfigSha256?: string;
+    /** Publication receipt adjacent to a shipped template, outside its file catalog. */
+    readonly agentConfigReceipt?: BundledAgentConfigReceipt;
 }
 /** Deployment settings the Provider resolves once at load. */
 export interface WorkspaceBundlesSpec {

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Workspace templates",
-    "description": "Register, materialize, and wholly replace packaged Workspace templates"
+    "description": "Create, set up, and update built-in workspace templates"
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "工作区模板",
-    "description": "内置工作区模板的注册、物化与整体升级"
+    "description": "管理内置工作区模板的创建、初始化与版本升级"
   }
 }