@dsh-electron/dsh-plugin-multi-root-workspace 0.1.11 → 0.1.13

package/lib/skills.js

@@ -1,4 +1,5 @@
 import { t as wrapMethod } from "./method-wrapper-CFY3p3j2.js";
+import { c as withRegistryRead } from "./registry-operation-C2ZV3Jhw.js";
 import { r as isPackageInstalled, t as createInstructionMessage } from "./llm-message-fYORacvh.js";
 import { n as skillsMetadataValid } from "./metadata-DgqSdVX_.js";
 import { constants, statSync } from "node:fs";
@@ -6,8 +7,8 @@ import { createHash } from "node:crypto";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { Service } from "@deepseek-ai/cordis";
 import { canonicalPath } from "@deepseek-ai/dsh-sandbox";
-import { lstat, open, readdir, stat } from "node:fs/promises";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { lstat, open, readdir, stat } from "node:fs/promises";
 import z from "@deepseek-ai/schemastery";
 //#region \0@oxc-project+runtime@0.149.0/helpers/esm/usingCtx.js
 function _usingCtx() {
@@ -191,9 +192,10 @@ var SkillReaderPool = class {
 		return this.entries.size;
 	}
 	get roots() {
-		return [...this.entries.keys()];
+		return [...new Set([...this.entries.values()].map((entry) => entry.root))];
 	}
-	async use(key, create, run, signal) {
+	async use(root, create, run, signal, identity = root) {
+		const key = identity;
 		for (;;) {
 			signal?.throwIfAborted();
 			if (this.closing) throw new Error("multi-root skills: reader pool is closing");
@@ -225,6 +227,7 @@ var SkillReaderPool = class {
 				const controller = new AbortController();
 				entry = {
 					key,
+					root,
 					controller,
 					reader: create(controller.signal),
 					busy: 0
@@ -235,7 +238,7 @@ var SkillReaderPool = class {
 			this.entries.set(key, entry);
 			entry.busy++;
 			try {
-				if (entry.stamp === void 0) entry.stamp = await skillTreeStamp(key);
+				if (entry.stamp === void 0) entry.stamp = await skillTreeStamp(entry.root);
 				signal?.throwIfAborted();
 				return await run(await entry.reader);
 			} finally {
@@ -249,7 +252,7 @@ var SkillReaderPool = class {
 		this.polling ??= (async () => {
 			let changed = false;
 			for (const entry of [...this.entries.values()]) {
-				const stamp = await skillTreeStamp(entry.key);
+				const stamp = await skillTreeStamp(entry.root);
 				if (entry.stamp !== void 0 && entry.stamp !== stamp) changed = true;
 				entry.stamp = stamp;
 			}
@@ -285,10 +288,10 @@ var SkillReaderPool = class {
 /** No symlink target outside the Root is read or enumerated. Content reads stay on demand. */
 async function skillTreeStamp(root) {
 	const rows = [canonicalPath(root)];
-	const stamp = async (path) => {
+	const stamp = async (path, identityOnly = false) => {
 		try {
 			const link = await lstat(path, { bigint: true });
-			rows.push(`${path}:${link.dev}:${link.ino}:${link.size}:${link.mtimeNs}:${link.ctimeNs}:${canonicalPath(path)}`);
+			rows.push(identityOnly ? `${path}:${link.dev}:${link.ino}:${link.mode}:${canonicalPath(path)}` : `${path}:${link.dev}:${link.ino}:${link.size}:${link.mtimeNs}:${link.ctimeNs}:${canonicalPath(path)}`);
 			if (!containsPath(root, canonicalPath(path))) return void 0;
 			return await stat(path);
 		} catch {
@@ -296,7 +299,7 @@ async function skillTreeStamp(root) {
 			return;
 		}
 	};
-	await stamp(root);
+	await stamp(root, true);
 	for (const directory of [".dsh/skills", ".agents/skills"]) {
 		const path = join(root, directory);
 		if (!(await stamp(path))?.isDirectory()) continue;
@@ -336,7 +339,7 @@ var AdditionalSkillCatalog = class {
 		return this.generation();
 	}
 	current(primary, id) {
-		if (this.signal.aborted || !this.enabled() || this.ctx.multiRootRegistry.authority.kind !== "active" || this.ctx.multiRootScope.resolve({
+		if (this.signal.aborted || !this.enabled() || !this.ctx.multiRootRegistry.available || this.ctx.multiRootScope.snapshot({
 			mode: "read-only",
 			workspaceRoot: primary
 		}).authority !== "available") return void 0;
@@ -355,13 +358,17 @@ var AdditionalSkillCatalog = class {
 		if (root === void 0) return await run(void 0);
 		return await this.requests.run({
 			primary,
-			id
+			id,
+			epoch: this.ctx.multiRootRegistry.epoch
 		}, () => this.pool.use(root.path, (signal) => rootReader(this.ctx, root.path, AbortSignal.any([signal, this.signal]), () => {
 			const request = this.requests.getStore();
-			return request !== void 0 && this.current(request.primary, request.id)?.path === root.path;
-		}), run, options.signal));
+			return request !== void 0 && request.epoch === this.ctx.multiRootRegistry.epoch && this.current(request.primary, request.id)?.path === root.path;
+		}), run, options.signal, `${this.ctx.multiRootRegistry.epoch ?? "unavailable"}\0${root.path}`));
 	}
 	async list(primary, options) {
+		return withRegistryRead(this.ctx, primary, "skills", () => this.listAdmitted(primary, options));
+	}
+	async listAdmitted(primary, options) {
 		options.signal?.throwIfAborted();
 		if (!this.enabled()) return [];
 		const roots = await this.ctx.multiRootRegistry.refresh(primary);
@@ -381,6 +388,7 @@ var AdditionalSkillCatalog = class {
 					seen.add(candidate.name);
 					const locator = {
 						primary,
+						authorityEpoch: this.ctx.multiRootRegistry.epoch,
 						rootId: root.id,
 						aliasId: root.aliasId,
 						candidate
@@ -408,8 +416,11 @@ var AdditionalSkillCatalog = class {
 	}
 	/** Locators are created here and are not accepted from a client path or object. */
 	async load(primary, entry, options, user) {
+		return withRegistryRead(this.ctx, primary, "skills", () => this.loadAdmitted(primary, entry, options, user));
+	}
+	async loadAdmitted(primary, entry, options, user) {
 		const locator = entry.locator;
-		if (typeof locator !== "object" || locator === null || !this.locators.has(locator) || locator.primary !== primary) return void 0;
+		if (typeof locator !== "object" || locator === null || !this.locators.has(locator) || locator.primary !== primary || locator.authorityEpoch !== this.ctx.multiRootRegistry.epoch) return void 0;
 		const root = this.current(primary, locator.rootId);
 		if (root === void 0 || root.aliasId !== locator.aliasId || entry.name !== internalSkillName(primary, root.id, locator.candidate.name)) return void 0;
 		const revision = this.generation();
@@ -446,14 +457,16 @@ var AdditionalSkillCatalog = class {
 	}
 	async admissionValid(definition) {
 		const receipt = this.loadedReceipts.get(definition);
-		if (receipt === void 0) return false;
-		const current = this.current(receipt.locator.primary, receipt.locator.rootId);
-		if (current === void 0 || current.aliasId !== receipt.locator.aliasId || receipt.revision !== this.generation()) return false;
-		try {
-			return receipt.stamp === await fileStamp(definition.path) && receipt.revision === this.generation() && this.current(receipt.locator.primary, receipt.locator.rootId)?.aliasId === receipt.locator.aliasId;
-		} catch {
-			return false;
-		}
+		if (receipt === void 0 || receipt.locator.authorityEpoch !== this.ctx.multiRootRegistry.epoch) return false;
+		return withRegistryRead(this.ctx, receipt.locator.primary, "skills", async () => {
+			const current = this.current(receipt.locator.primary, receipt.locator.rootId);
+			if (current === void 0 || current.aliasId !== receipt.locator.aliasId || receipt.revision !== this.generation()) return false;
+			try {
+				return receipt.stamp === await fileStamp(definition.path) && receipt.revision === this.generation() && this.current(receipt.locator.primary, receipt.locator.rootId)?.aliasId === receipt.locator.aliasId;
+			} catch {
+				return false;
+			}
+		});
 	}
 	async dispose() {
 		await this.pool.dispose();
@@ -574,16 +587,22 @@ function installSkillRouting(ctx) {
 	fibers.push(ctx.inject(["skills"], (scope) => {
 		const registry = scope.skills;
 		scope.effect(() => wrapMethod(registry, "snapshot", (original) => async function(options = {}) {
-			const result = await original.call(this, optionsFor(options));
-			const primary = skillOrigin(scope, options);
-			if (primary !== void 0) for (const skill of result.skills) {
-				if (skill.provider === "multi-root-workspace") continue;
-				if (scope.multiRootRegistry.list(primary).some((root) => skill.name.startsWith(internalSkillName(primary, root.id, "")))) scope.logger.warn(`multi-root skills: internal ID conflict; native winner retained: ${skill.name} (${skill.provider})`);
-			}
-			return result;
+			const primaryOrigin = skillOrigin(scope, options) ?? cold.getStore();
+			const run = async () => {
+				const result = await original.call(this, optionsFor(options));
+				const primary = skillOrigin(scope, options);
+				if (primary !== void 0) for (const skill of result.skills) {
+					if (skill.provider === "multi-root-workspace") continue;
+					if (scope.multiRootRegistry.list(primary).some((root) => skill.name.startsWith(internalSkillName(primary, root.id, "")))) scope.logger.warn(`multi-root skills: internal ID conflict; native winner retained: ${skill.name} (${skill.provider})`);
+				}
+				return result;
+			};
+			return primaryOrigin === void 0 ? run() : withRegistryRead(scope, primaryOrigin, "skills", run);
 		}));
 		scope.effect(() => wrapMethod(registry, "get", (original) => function(name, options = {}) {
-			return original.call(this, name, optionsFor(options));
+			const primary = skillOrigin(scope, options) ?? cold.getStore();
+			const run = () => original.call(this, name, optionsFor(options));
+			return primary === void 0 ? run() : withRegistryRead(scope, primary, "skills", run);
 		}));
 	}));
 	fibers.push(ctx.inject(["sessionSkillCatalog", "sessionQuery"], (scope) => {

package/lib/types/authority/native-win32.d.ts

@@ -0,0 +1,7 @@
+import type { Channel, Listener } from './native.ts';
+export declare function connectWindows(endpoint: string): Promise<Channel>;
+export declare function listenWindows(endpoint: string, accepted: (channel: Channel) => void): Promise<Listener>;
+export declare function windowsHostAvailability(): Promise<{
+    available: boolean;
+    reason?: string;
+}>;

package/lib/types/authority/native.d.ts

@@ -0,0 +1,23 @@
+import type { EventEmitter } from 'node:events';
+export interface Channel {
+    on: EventEmitter['on'];
+    readonly writableLength?: number;
+    write(data: string): boolean;
+    destroy(): unknown;
+}
+export interface Listener {
+    close(): void;
+}
+export declare function storeIdentity(root: string): {
+    root: string;
+    id: string;
+    endpoint: string;
+};
+export declare function connectNative(endpoint: string): Promise<Channel>;
+/** Called only by the kernel lease holder. Never removes another epoch's socket. */
+export declare function listenNative(endpoint: string, accepted: (channel: Channel) => void): Promise<Listener>;
+/** Capability probe for native tests and diagnostics; not an authorization bypass. */
+export declare function nativeHostAvailability(): Promise<{
+    available: boolean;
+    reason?: string;
+}>;

package/lib/types/authority/protocol.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+declare const methods: readonly ["hello", "snapshot", "admit", "add", "removeAt", "setAccess", "setAlias", "setSkillsEnabled", "setAliasId", "move", "recheck"];
+export type Method = typeof methods[number];
+export declare const snapshotSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    store: z.ZodString;
+    epoch: z.ZodString;
+    revision: z.ZodNumber;
+    primary: z.ZodString;
+    roots: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        access: z.ZodEnum<{
+            inherit: "inherit";
+            "read-only": "read-only";
+            "read-write": "read-write";
+        }>;
+        addedAt: z.ZodString;
+        recordedPath: z.ZodOptional<z.ZodString>;
+        readOnlyRecordedPath: z.ZodOptional<z.ZodString>;
+        readWriteRecordedPath: z.ZodOptional<z.ZodString>;
+        alias: z.ZodOptional<z.ZodString>;
+        aliasId: z.ZodOptional<z.ZodUnknown>;
+        skillsEnabled: z.ZodOptional<z.ZodUnknown>;
+        state: z.ZodEnum<{
+            available: "available";
+            missing: "missing";
+            redirected: "redirected";
+            invalid: "invalid";
+        }>;
+        detail: z.ZodOptional<z.ZodString>;
+        invalidReason: z.ZodOptional<z.ZodLiteral<"membership-conflict">>;
+    }, z.core.$strict>>;
+    available: z.ZodBoolean;
+}, z.core.$strict>;
+export type Snapshot = z.infer<typeof snapshotSchema>;
+export declare class AuthorityRpcError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class AuthorityClient {
+    private readonly channel;
+    private readonly store;
+    private readonly limit;
+    private readonly pending;
+    private closed;
+    epoch: string | undefined;
+    private constructor();
+    static connect(endpoint: string, store: string, limit: number, onChange: (snapshot: Snapshot) => void, disconnected: () => void, signal?: AbortSignal): Promise<AuthorityClient>;
+    request(method: Method, args: readonly unknown[]): Promise<unknown>;
+    close(): void;
+}
+export declare class AuthorityServer {
+    private readonly store;
+    private readonly epoch;
+    private readonly limit;
+    private readonly dispatch;
+    private listener;
+    private readonly peers;
+    private readonly readyPeers;
+    private closed;
+    private inFlight;
+    private constructor();
+    static listen(endpoint: string, store: string, epoch: string, limit: number, dispatch: (method: Method, args: unknown[]) => Promise<unknown>): Promise<AuthorityServer>;
+    private accept;
+    changed(snapshot: Snapshot): void;
+    close(): void;
+}
+export declare function parseArguments(method: Method, args: unknown[]): unknown[];
+export {};

package/lib/types/authority/recovery.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Bounded background retry for the registry authority: one pending timer and
+ * one in-flight attempt per instance, post-completion backoff, and local
+ * cancellation on dispose. The scheduler owns NO policy — the caller supplies
+ * `run` (one recovery attempt) and `eligible` (whether a degraded state still
+ * wants recovery), so the same object can drive contended, follower
+ * resync, and retryable storage failures.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/authority/recovery
+ */
+/** Injectable clock so fake-timer specs can drive the scheduler exactly. */
+export interface RecoveryTimers {
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+    random(): number;
+    now(): number;
+}
+/** What the scheduler is doing, for diagnostics surfaces. */
+export type RecoveryPhase = 'idle' | 'waiting' | 'attempting' | 'disabled';
+export declare class RecoveryScheduler {
+    private readonly run;
+    private readonly eligible;
+    private readonly enabled;
+    private readonly timers;
+    private timer;
+    private inFlight;
+    private disposed;
+    private attempts;
+    private retryAt;
+    constructor(options: {
+        run: () => Promise<void>;
+        eligible: () => boolean;
+        enabled: boolean;
+        timers?: RecoveryTimers;
+    });
+    /**
+     * Ask for a recovery attempt. Called after every `ensureAuthority()` and on
+     * every downgrade event. A healthy state (`!eligible()`) resets the backoff;
+     * a pending timer or in-flight attempt is never duplicated or reset.
+     */
+    arm(): void;
+    /**
+     * Progress event (a follower connection was just adopted): the backoff is
+     * earned, so reset it and run the next attempt immediately — still through
+     * the single pending timer.
+     */
+    kick(): void;
+    /** Stop scheduling. An in-flight attempt is left to finish on its own. */
+    dispose(): void;
+    get state(): {
+        phase: RecoveryPhase;
+        attempts: number;
+        nextRetryAt: number | undefined;
+    };
+    private clearTimer;
+    private delay;
+    private tick;
+}

package/lib/types/client/RootSwitcher.d.ts

@@ -32,9 +32,12 @@
  *   the same element's `closest('[data-dockkit-content]')` — the dockkit
  *   tabHost section — with a generated fallback where the hook is absent.
  *
- * The selected root is component state on purpose: every tab render
- * occurrence gets its own, and reopening the pane resets to the primary
- * root. There is no cross-tab or persisted selection.
+ * The selected root lives in the inject product's session-scoped snapshot,
+ * keyed by that dockkit tab id — component state could not survive the
+ * remount every file open causes (the opened tab takes the pane, the Files
+ * body unmounts with the whole occupant subtree). One selection per tab;
+ * session switches mint a fresh inject product, so no selection crosses
+ * sessions, and a registry eviction reconciles it back to primary.
  *
  * @module @dsh-electron/dsh-plugin-multi-root-workspace/client/RootSwitcher
  */

package/lib/types/client/files-tree/adapter.d.ts

@@ -25,19 +25,72 @@
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
 import type { ClientRemote } from '@deepseek-ai/dsh-api-remotes/client';
-import type { BoundActions } from '@deepseek-ai/dsh-client-store';
+import { type BoundActions, type SnapshotSelectorHook } from '@deepseek-ai/dsh-client-store';
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots';
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit';
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import { type FilesInjected } from './face.ts';
 import { createFilesStore } from './store.ts';
 import { filesTreeSurfaceSupported } from './primitives.ts';
 import type { FilesTreeProps } from './FilesTree.tsx';
+import type { RootView } from '../../contract.ts';
 import { NS } from './locales.ts';
+/**
+ * One session's per-tab additional-root selections, keyed by the pane's
+ * dockkit tab id. An absent entry means the primary root.
+ */
+export type TreeSelection = Readonly<Record<string, RootView>>;
+/**
+ * The lifetimes a selection runs under, keyed by tab like the store bucket:
+ * while an entry's signal is live the tree keeps its loaded levels, watches,
+ * expansion, and scroll — exactly what upstream's tab-record signal gives the
+ * native tree across a body remount (opening a file deactivates this tab,
+ * unmounting its body without ending the record).
+ */
+export interface FilesTreeTakeover {
+    /**
+     * The live signal for (tabId, root); reuses the live entry so a remounted
+     * body finds its bucket and watches intact. A different root — or an entry
+     * already aborted — ends the previous controller before minting the next.
+     * @param tabId - the pane's dockkit tab id.
+     * @param root - absolute path of the root being browsed.
+     * @param section - the dockkit tabHost section the caller mounted under; a
+     *   live entry keeps an observer on it that ends the takeover whenever the
+     *   section leaves the document — the record's real end — including when the
+     *   body that mounted it has long been unmounted itself.
+     * @returns the signal the forked tree lives under.
+     */
+    readonly signal: (tabId: TabId, root: string, section?: Element) => AbortSignal;
+    /**
+     * Abort and drop one tab's takeover: the reader deselected or switched
+     * roots, or the tab record itself went away.
+     * @param tabId - the pane's dockkit tab id.
+     */
+    readonly end: (tabId: TabId) => void;
+}
 /** The inject face the registration composes onto the occupant's props. */
 export interface FilesTreeInjected {
     /** The verbatim files face (list/watch bookkeeping included). */
     readonly face: FilesInjected;
     /** Open one `dsh-resource://file` address in the host viewer. */
     readonly openFile: (address: string) => void;
+    /**
+     * The reserved inject compartment: the slot renderer binds each source to a
+     * `use<Name>` selector hook, so `treeSelection` reaches the component as
+     * `useTreeSelection`, never as a prop under its own key.
+     */
+    readonly hooks: {
+        readonly treeSelection: HostObservable<TreeSelection>;
+    };
+    /**
+     * Persist one pane's selected root; `'primary'` drops its entry. The
+     * session-scoped snapshot survives the body remount a file open causes.
+     * @param tabId - the pane's dockkit tab id.
+     * @param root - the selected root, or `'primary'` to browse the session root.
+     */
+    readonly selectRoot: (tabId: TabId, root: RootView | 'primary') => void;
+    /** The forked tree's lifetimes; see {@link FilesTreeTakeover}. */
+    readonly takeover: FilesTreeTakeover;
 }
 /** Everything `FilesTree` needs that the slot framework does not synthesize. */
 export interface FilesTreeSurface {
@@ -47,6 +100,12 @@ export interface FilesTreeSurface {
     readonly face: FilesInjected;
     readonly openFile: (address: string) => void;
     readonly t: FilesTreeProps['t'];
+    /** Selector hook over this session's per-tab root selections. */
+    readonly useTreeSelection: SnapshotSelectorHook<TreeSelection>;
+    /** The selection's write side; see {@link FilesTreeInjected.selectRoot}. */
+    readonly selectRoot: FilesTreeInjected['selectRoot'];
+    /** The forked tree's lifetimes; see {@link FilesTreeTakeover}. */
+    readonly takeover: FilesTreeTakeover;
 }
 /**
  * A `ClientRemote` stand-in that resolves the real service per call.
@@ -89,6 +148,9 @@ export declare function createFilesTreeSurface(props: {
     readonly actions: FilesTreeSurface['actions'];
     readonly face: FilesInjected | undefined;
     readonly openFile: ((address: string) => void) | undefined;
+    readonly useTreeSelection: FilesTreeSurface['useTreeSelection'] | undefined;
+    readonly selectRoot: FilesTreeSurface['selectRoot'] | undefined;
+    readonly takeover: FilesTreeSurface['takeover'] | undefined;
 }, t: FilesTreeProps['t']): FilesTreeSurface | undefined;
 export { filesTreeSurfaceSupported, NS as FILES_TREE_NS };
 export { FilesTree } from './FilesTree.tsx';

package/lib/types/compat/authority-storage.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { DomainSpec } from '@deepseek-ai/dsh-storage-domain';
+export declare function openAuthorityStorage<S extends DomainSpec>(ctx: Context, root: string, spec: S): Promise<{
+    table: <N extends keyof S["tables"] & string>(name: N) => import("@deepseek-ai/dsh-storage-domain").KvTable<import("@deepseek-ai/dsh-storage-domain").TableKeyOf<S, N>, import("@deepseek-ai/dsh-storage-domain").TableValueOf<S, N>>;
+    close(): Promise<void>;
+}>;

package/lib/types/compat/dsh-version.d.ts

@@ -28,7 +28,7 @@
  * the upgrade smoke passed on that exact version — a green CI run on an
  * unlisted release is evidence, not authorization (ADR-0009).
  */
-export declare const SUPPORTED_DSH_RELEASES: readonly ["0.1.5-rc.2", "0.1.6-alpha.1", "0.1.6-alpha.2", "0.1.7-alpha.1", "0.1.7-alpha.2", "0.1.7-rc.1", "0.1.7-rc.2", "0.2.0-rc.1", "0.2.0-rc.2", "0.2.1-alpha.1", "0.2.1-alpha.2", "0.2.1-alpha.3", "0.2.1-alpha.4", "0.2.1-alpha.5", "0.2.1-rc.1", "0.2.1-rc.2", "0.2.1-rc.3", "0.2.1-rc.4", "0.2.2-alpha.2"];
+export declare const SUPPORTED_DSH_RELEASES: readonly ["0.1.5-rc.2", "0.1.6-alpha.1", "0.1.6-alpha.2", "0.1.7-alpha.1", "0.1.7-alpha.2", "0.1.7-rc.1", "0.1.7-rc.2", "0.2.0-rc.1", "0.2.0-rc.2", "0.2.1-alpha.1", "0.2.1-alpha.2", "0.2.1-alpha.3", "0.2.1-alpha.4", "0.2.1-alpha.5", "0.2.1-rc.1", "0.2.1-rc.2", "0.2.1-rc.3", "0.2.1-rc.4", "0.2.1-rc.5", "0.2.2-alpha.2"];
 /** One release this plugin claims to support. */
 export type SupportedDshRelease = typeof SUPPORTED_DSH_RELEASES[number];
 /**
@@ -42,7 +42,7 @@ export declare const REQUIRED_CORE_PACKAGES: readonly ["@deepseek-ai/dsh-fs", "@
  * Absence is fine; a version that DISAGREES with the required packages is not —
  * that is the mixed-installation failure this contract exists to catch.
  */
-export declare const OPTIONAL_CORE_PACKAGES: readonly ["@deepseek-ai/dsh-skill", "@deepseek-ai/dsh-skill-filesystem", "@deepseek-ai/dsh-settings", "@deepseek-ai/dsh-api-session-controller", "@deepseek-ai/dsh-session-query", "@deepseek-ai/dsh-tools", "@deepseek-ai/dsh-working-directory", "@deepseek-ai/dsh-lsp", "@deepseek-ai/dsh-lsp-stdio", "@deepseek-ai/dsh-api-workspace-files", "@deepseek-ai/dsh-typert-protocol", "@deepseek-ai/dsh-sandbox-windows-acl", "@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-client-connection", "@deepseek-ai/dsh-commands", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-subprocess", "@deepseek-ai/dsh-system-prompt"];
+export declare const OPTIONAL_CORE_PACKAGES: readonly ["@deepseek-ai/dsh-storage-json", "@deepseek-ai/dsh-skill", "@deepseek-ai/dsh-skill-filesystem", "@deepseek-ai/dsh-settings", "@deepseek-ai/dsh-api-session-controller", "@deepseek-ai/dsh-session-query", "@deepseek-ai/dsh-tools", "@deepseek-ai/dsh-working-directory", "@deepseek-ai/dsh-lsp", "@deepseek-ai/dsh-lsp-stdio", "@deepseek-ai/dsh-api-workspace-files", "@deepseek-ai/dsh-typert-protocol", "@deepseek-ai/dsh-sandbox-windows-acl", "@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-client-connection", "@deepseek-ai/dsh-commands", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-subprocess", "@deepseek-ai/dsh-system-prompt"];
 /**
  * The optional packages this plugin loads itself at run time, through dynamic
  * `import()`s inside this package's own modules. The copy this module resolves
@@ -50,7 +50,7 @@ export declare const OPTIONAL_CORE_PACKAGES: readonly ["@deepseek-ai/dsh-skill",
  * private copy inside this package's own tree genuinely loads, and a version
  * that disagrees with the host is a real mixed installation, not a phantom.
  */
-export declare const RUNTIME_OPTIONAL_PACKAGES: readonly ["@deepseek-ai/dsh-skill", "@deepseek-ai/dsh-skill-filesystem", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-typert-protocol"];
+export declare const RUNTIME_OPTIONAL_PACKAGES: readonly ["@deepseek-ai/dsh-storage-json", "@deepseek-ai/dsh-skill", "@deepseek-ai/dsh-skill-filesystem", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-typert-protocol"];
 /**
  * The optional packages this plugin consumes only as mounted host services or
  * ambient types — it never imports them, so a copy inside this package's own
@@ -79,7 +79,7 @@ export declare const HOST_SERVICE_PACKAGES: readonly ["@deepseek-ai/dsh-settings
  */
 export declare const RUNNER_ANCHORED_PACKAGES: readonly ["@deepseek-ai/dsh-sandbox-windows-acl"];
 /** Every package the contract inspects, required first. */
-export declare const CORE_PACKAGES: readonly ["@deepseek-ai/dsh-fs", "@deepseek-ai/dsh-fs-local", "@deepseek-ai/dsh-sandbox", "@deepseek-ai/dsh-sandbox-local", "@deepseek-ai/dsh-sandbox-policy", "@deepseek-ai/dsh-storage-domain", "@deepseek-ai/dsh-skill", "@deepseek-ai/dsh-skill-filesystem", "@deepseek-ai/dsh-settings", "@deepseek-ai/dsh-api-session-controller", "@deepseek-ai/dsh-session-query", "@deepseek-ai/dsh-tools", "@deepseek-ai/dsh-working-directory", "@deepseek-ai/dsh-lsp", "@deepseek-ai/dsh-lsp-stdio", "@deepseek-ai/dsh-api-workspace-files", "@deepseek-ai/dsh-typert-protocol", "@deepseek-ai/dsh-sandbox-windows-acl", "@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-client-connection", "@deepseek-ai/dsh-commands", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-subprocess", "@deepseek-ai/dsh-system-prompt"];
+export declare const CORE_PACKAGES: readonly ["@deepseek-ai/dsh-fs", "@deepseek-ai/dsh-fs-local", "@deepseek-ai/dsh-sandbox", "@deepseek-ai/dsh-sandbox-local", "@deepseek-ai/dsh-sandbox-policy", "@deepseek-ai/dsh-storage-domain", "@deepseek-ai/dsh-storage-json", "@deepseek-ai/dsh-skill", "@deepseek-ai/dsh-skill-filesystem", "@deepseek-ai/dsh-settings", "@deepseek-ai/dsh-api-session-controller", "@deepseek-ai/dsh-session-query", "@deepseek-ai/dsh-tools", "@deepseek-ai/dsh-working-directory", "@deepseek-ai/dsh-lsp", "@deepseek-ai/dsh-lsp-stdio", "@deepseek-ai/dsh-api-workspace-files", "@deepseek-ai/dsh-typert-protocol", "@deepseek-ai/dsh-sandbox-windows-acl", "@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-client-connection", "@deepseek-ai/dsh-commands", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-subprocess", "@deepseek-ai/dsh-system-prompt"];
 /** How this plugin reacts to an installation it does not support. */
 export type CompatEnforcement = 'enforce' | 'warn';
 /** The environment variable that relaxes the gate. */

package/lib/types/compat/open-in-app-device.d.ts

@@ -3,7 +3,7 @@
  * `@deepseek-ai/dsh-client-ui-primitives`.
  *
  * ```text
- * 0.1.5-rc.2 through 0.2.1-rc.4   no `isMobileDevice` export
+ * 0.1.5-rc.2 through 0.2.1-rc.5   no `isMobileDevice` export
  * 0.2.2-alpha.2 +                 `isMobileDevice` exported
  * ```
  *

package/lib/types/compat/process-entrypoints.d.ts

@@ -29,3 +29,5 @@ export declare function shellEntrypoints(shell: object): readonly ProcessEntrypo
  * @returns the present entries — a structural probe only.
  */
 export declare function ptcEntrypoints(runtime: object): readonly ProcessEntrypoint[];
+/** Async public entries can acquire admission before calling their implementation. */
+export declare function isAsyncProcessEntry(entry: unknown): boolean;

package/lib/types/compat/process-profile.d.ts

@@ -0,0 +1,3 @@
+export declare function hasConfinedProfile(argv: readonly string[]): boolean;
+/** Agent PTYs are re-confined after their own fresh admission, never replayed. */
+export declare function originalProcessArgv(argv: readonly string[]): readonly string[];

package/lib/types/compat/sandbox-confine.d.ts

@@ -58,3 +58,5 @@ export declare function mapConfined<T>(value: UpstreamConfined, map: (confined:
  * @returns the widened result, in the shape the installed release uses.
  */
 export declare function widenConfined(base: ConfineCall, widen: (confined: ConfinedArgv) => ConfinedArgv, argv: readonly string[], policy: SandboxPolicy, signal?: AbortSignal): UpstreamConfined;
+/** Public consumer call with the installed provider's arity and return shape. */
+export declare function confineInstalled(provider: Pick<LocalSandboxProvider, 'confine'>, argv: readonly string[], policy: SandboxPolicy, signal?: AbortSignal): ConfinedArgv | Promise<ConfinedArgv>;

package/lib/types/fs.d.ts

@@ -64,6 +64,8 @@ export declare class MultiRootFileSystem extends LocalFileSystem {
     editText(target: FsTarget, edit: FsEditRequest, expected?: {
         version: FsVersion;
     }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsEditOutcome>;
+    /** The provider must also work without the gated registry (ADR-0009). */
+    private withOperation;
     /**
      * The writable roots of one confined call: the upstream derivation (primary
      * root plus the platform temp areas, canonical and deduplicated — empty
@@ -104,7 +106,8 @@ export declare class MultiRootFileSystem extends LocalFileSystem {
      * to primary-root-only writes (no shared temp or additional-root grants)
      * until the authority returns.
      * @param target - the resolved target about to be mutated.
-     * @param sandboxPolicy - the per-call policy; omit for the deployment fallback.
+     * @param policy - the per-call policy captured before admission.
+     * @param scope - the admission snapshot shared by every fence check.
      * @returns the fresh canonical target the mutation must use.
      */
     private checkedTarget;

package/lib/types/instructions.d.ts

@@ -1,50 +1,3 @@
-/**
- * `multi-root-instructions`: the additional roots' own instruction files, made
- * visible to the model.
- *
- * Upstream `agent-instructions` discovers instruction files by walking UP from
- * the session cwd (plus the one user-global file). In a multi-root workspace
- * that walk never reaches an additional root, so `repo-b/AGENTS.md` is
- * invisible to a model that is nevertheless allowed to write `repo-b`. This row
- * closes exactly that gap, and nothing else: the primary root's chain — nested
- * files included — and the user-global file stay upstream's business.
- *
- * Four deliberate choices:
- *
- * 1. **Not a system-prompt contribution.** Instruction text is
- *    producer-supplied context, not system authority, so it enters as a
- *    user-role message tagged `form: 'instructions'`. Through session format 3
- *    the source kind is `plugin`; format 4 retired that shared kind, so the
- *    adapter persists this plugin's own (`multi-root-workspace`). It is also
- *    the only channel that is logged, and model-visible content must be logged.
- * 2. **Injected from `agent/pre-step`, not a session lifecycle event.**
- *    `pre-step` is an awaited waterfall, so discovery, reading and rendering all
- *    complete BEFORE the step it feeds — deterministically, on the first step.
- *    A synchronous prompt callback could not await them, and an emit-mode
- *    lifecycle listener would race the first step. It is also the one hook whose
- *    shape is identical across every supported release, which keeps the
- *    instruction feature out of the compatibility matrix (ADR-0009).
- * 3. **Discovery is pinned to the root.** `projectRoot` is the additional root,
- *    so the walk can never leave it, and every candidate is then required to be
- *    canonically INSIDE that root. That is what keeps `$DSH_HOME/AGENTS.md`, the
- *    primary root's `AGENTS.md`, and any ancestor's file from being injected a
- *    second time by this plugin.
- * 4. **Nested files are driven by the session's own tool activity.** A
- *    subdirectory's `AGENTS.md` only matters once the session has worked in that
- *    subdirectory, so the directories worth examining are derived from the
- *    session's persisted events: `tool/call` and `tool/result` are paired, and a
- *    successful `read`/`write`/`edit` makes the path from the root down to the
- *    touched file's directory relevant (ADR-0010). A file that disappears is
- *    retracted explicitly, because the text it contributed earlier is still in
- *    the conversation and silence does not withdraw it.
- *
- * The byte budget is shared: `maxBytes` bounds the WHOLE additional-root
- * snapshot, not each root, because ten roots must not quietly cost ten budgets
- * of context. Roots consume it in scope order. Retractions are exempt, because a
- * truncated withdrawal is worse than a slightly over-budget message.
- *
- * @module @dsh-electron/dsh-plugin-multi-root-workspace/instructions
- */
 import { Context } from '@deepseek-ai/cordis';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 declare module '@deepseek-ai/cordis' {

package/lib/types/registry-operation.d.ts

@@ -0,0 +1,31 @@
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
+import type { FilesystemScope } from './scope.ts';
+export type RegistryOperationKind = 'fs-write' | 'fs-edit' | 'process' | 'pty' | 'lsp' | 'files' | 'instructions' | 'skills';
+export declare function currentRegistryOperation(proof: object): RegistryOperation | undefined;
+export interface RegistryOperationIdentity {
+    readonly operationId: string;
+    readonly kind: RegistryOperationKind;
+    readonly mode: SandboxMode | undefined;
+    readonly primaryRoot: string;
+    /** Absent when the registry cannot grant additional authority. */
+    readonly authorityEpoch: string | undefined;
+    /** Effective publication revision, meaningful only within this epoch. */
+    readonly revision: number;
+}
+export interface RegistryOperation {
+    readonly identity: RegistryOperationIdentity;
+    /** Only readable during this operation's callback. */
+    readonly scope: FilesystemScope;
+}
+/** Capture by value: neither later publication nor a caller can mutate admission. */
+export declare function freezeOperationScope(scope: FilesystemScope): FilesystemScope;
+/** Execute outside the authority queue; completion also expires async descendants. */
+export declare function runRegistryOperation<T>(scope: FilesystemScope, kind: RegistryOperationKind, authorityEpoch: string | undefined, revision: number, body: (operation: RegistryOperation) => T | Promise<T>, proof?: object, mode?: SandboxMode): Promise<T>;
+/** Optional Registry seam for public consumers; the legacy composition stays exact. */
+export declare function withRegistryRead<T>(ctx: import('@deepseek-ai/cordis').Context, primary: string, kind: RegistryOperationKind, body: () => T | Promise<T>): Promise<T>;
+export declare function withRegistryAdmission<T>(ctx: import('@deepseek-ai/cordis').Context, policy: import('@deepseek-ai/dsh-sandbox').SandboxExecutionPolicy, kind: RegistryOperationKind, body: () => T | Promise<T>): Promise<T>;
+/** Preserve a legacy synchronous entry while granting only the safe primary-root fallback. */
+export declare function runPrimaryOperation<T>(scope: FilesystemScope, mode: SandboxMode, proof: object, body: () => T): T;
+/** Only profiles produced within this exact admission can reach a sync spawn. */
+export declare function rememberOperationProfile(proof: object, argv: readonly string[], capped: boolean): void;
+export declare function operationPermitsProfile(proof: object, argv: readonly string[], capped: boolean): boolean;