@dsh-electron/dsh-plugin-multi-root-workspace 0.1.0 → 0.1.2

package/lib/types/contract.d.ts

@@ -94,16 +94,14 @@ export interface PanelResponseMap {
     readonly reveal: RevealedView;
 }
 /**
- * The fields a request may carry. `primaryRoot` and `sessionId` are shared by
- * every endpoint (a client may name the workspace root directly or let the host
- * resolve it from the session); the remaining fields are used per endpoint and
- * the host asserts which ones that endpoint requires.
+ * The fields a request may carry. `sessionId` is required on every endpoint:
+ * the host derives the primary root from that session's immutable cwd and
+ * never accepts a client-named path. The remaining fields are used per
+ * endpoint and the host asserts which ones that endpoint requires.
  */
 export interface PanelRequest {
-    /** The workspace root to act on; the host validates that it is an existing directory. */
-    readonly primaryRoot?: string;
-    /** The session whose workspace root should be used when `primaryRoot` is absent. */
-    readonly sessionId?: string;
+    /** The live host session whose cwd is the primary root this call acts on. */
+    readonly sessionId: string;
     /** Exact target row from the most recent list snapshot. */
     readonly entry?: RootEntryView;
     /** Compatibility reference; accepted only when the id is unique. */

package/lib/types/index.d.ts

@@ -13,22 +13,36 @@
  * whole public surface from a single specifier.
  *
  * The two facts worth remembering about this surface: a registration carries the
- * canonical directory it was GRANTED for (`recordedPath`), and the panel channel
- * has one declared response shape per endpoint (`PanelResponseMap`).
+ * canonical directory it was GRANTED for (`recordedPath`), the panel channel
+ * has one declared response shape per endpoint (`PanelResponseMap`), and the
+ * panel primary root is derived from a live host session — never named by the
+ * browser.
  *
  * @module @dsh-electron/dsh-plugin-multi-root-workspace
  */
+export { DshCompatUnsupportedError, MultiRootCompatService, assertSupportedInstallation } from './compat.ts';
+export { classifyInstallation, compatEnforcement, CORE_PACKAGES, OPTIONAL_CORE_PACKAGES, readInstalledVersion, REQUIRED_CORE_PACKAGES, SUPPORTED_DSH_RELEASES, } from './compat/dsh-version.ts';
+export type { CompatEnforcement, CompatReport, CompatVerdict, InspectedPackage, SupportedDshRelease, VersionReader, } from './compat/dsh-version.ts';
+export { instructionsApi, renderInstructions } from './compat/agent-instructions.ts';
+export type { InstructionsApi, RenderedInstructions } from './compat/agent-instructions.ts';
+export { createInstructionMessage } from './compat/llm-message.ts';
+export type { InstructionMessageInput } from './compat/llm-message.ts';
+export { widenConfined } from './compat/sandbox-confine.ts';
+export type { ConfineCall, UpstreamConfined } from './compat/sandbox-confine.ts';
+export { composeInstructionMessage, DEFAULT_MAX_BYTES, PLUGIN_SOURCE } from './instructions.ts';
+export type { Config as InstructionsConfig } from './instructions.ts';
 export { MultiRootFileSystem } from './fs.ts';
 export type { Config as FileSystemConfig } from './fs.ts';
 export { MultiRootSandboxProvider } from './sandbox.ts';
 export type { Config as SandboxConfig } from './sandbox.ts';
 export { MultiRootScopeService, sanitizeAdditionalRoots, renderWorkspaceRootsContext } from './scope.ts';
 export type { AdditionalWorkspaceRoot, FilesystemScope } from './scope.ts';
-export { MultiRootRegistry, DOMAIN_NAME, MAX_ALIAS_LENGTH, multiRootDomainSpec } from './registry.ts';
-export type { AddRootInput, PersistedPrimaryRoot } from './registry.ts';
+export { MultiRootRegistry, DOMAIN_NAME, MAX_ALIAS_LENGTH, REGISTRY_CONTENDED_MESSAGE, multiRootDomainSpec } from './registry.ts';
+export type { AddRootInput, Config as RegistryConfig, PersistedPrimaryRoot, RegistryAuthorityState } from './registry.ts';
+export { RegistryAuthorityLease, RegistryLeaseContendedError } from './registry-lease.ts';
 export { availableRoots, canonicalRoot, classifyStoredRoots, expandRootInput, indexedStatuses, isCanonicallyUnder, additionalRootId, removeStatusAt, resolveRootRef, RootValidationError, validateRootCandidate, } from './roots.ts';
 export type { AdditionalRootId, RegisteredRoot, RootRef, RootState, RootStatus, RootValidationCode, } from './roots.ts';
-export { COMMAND_NAME, parseFoldersCommand, renderRootsReport, revealArgv } from './command.ts';
+export { COMMAND_NAME, parseFoldersCommand, renderRootsReport, resolvePanelPrimaryRoot, revealArgv } from './command.ts';
 export type { FoldersCommand } from './command.ts';
 export { PANEL_CHANNEL, PANEL_ENDPOINTS, parsePanelCall, parseRevealedView, parseRootsView } from './contract.ts';
 export type { PanelCall, PanelEndpoint, PanelFailure, PanelRequest, PanelResponseMap, RevealedView, RootView, RootsView, } from './contract.ts';

package/lib/types/instructions.d.ts

@@ -0,0 +1,125 @@
+/**
+ * `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';
+/** The `plugin` attribution every message this row produces carries. */
+export declare const PLUGIN_SOURCE = "@dsh-electron/dsh-plugin-multi-root-workspace";
+/**
+ * Total UTF-8 byte budget for the additional-root snapshot, matching the
+ * default the upstream `agent-instructions` row is composed with so that one
+ * extra workspace root costs at most as much as the primary one does.
+ */
+export declare const DEFAULT_MAX_BYTES = 65536;
+/** Largest instruction file this row will read; larger files are ignored. */
+export declare const DEFAULT_MAX_SOURCE_BYTES = 32768;
+/** Plugin configuration for the `multi-root-instructions` row. */
+export interface Config {
+    /** Total budget for ALL additional roots (default {@link DEFAULT_MAX_BYTES}); non-positive disables the row. */
+    readonly maxBytes?: number;
+    /** Per-file source cap (default {@link DEFAULT_MAX_SOURCE_BYTES}). */
+    readonly maxSourceBytes?: number;
+    /** Ordered same-directory instruction candidates; upstream's defaults when omitted. */
+    readonly instructionFileCandidates?: readonly string[];
+    /** Ordered same-directory local-overlay candidates; upstream's defaults when omitted. */
+    readonly localInstructionFileCandidates?: readonly string[];
+}
+/** One root's freshly rendered instruction text. */
+export interface RenderedRoot {
+    /** The canonical additional root. */
+    readonly root: string;
+    /** The rendered instruction text. */
+    readonly text: string;
+}
+/** One instruction file that is no longer present. */
+export interface RemovedScope {
+    /** The additional root it belonged to. */
+    readonly root: string;
+    /** The instruction file's absolute path. */
+    readonly path: string;
+}
+/**
+ * The path one RAW tool call touched.
+ *
+ * `arguments` is the model-produced JSON string, so the path is only known after
+ * parsing it; a call that names no `file_path`, or is not one of the tools whose
+ * success makes a directory relevant, touched nothing this row cares about.
+ * @param name - the tool name the model called.
+ * @param argumentsJson - the tool call's raw arguments, exactly as produced.
+ * @returns the trimmed absolute-or-relative path, or `undefined`.
+ */
+export declare function touchedPathOfToolCall(name: string, argumentsJson: string): string | undefined;
+/**
+ * Compose the model-facing message body for one batch of changes.
+ *
+ * All three halves matter. A newly visible root — or a newly touched
+ * subdirectory — needs its rules; a root that left needs an explicit
+ * revocation; and a file that disappeared needs an explicit withdrawal, because
+ * the instructions it contributed are still sitting in the conversation history
+ * and would otherwise keep applying forever. Silence is not a retraction.
+ * @param rendered - roots whose instruction text is new or changed.
+ * @param revoked - canonical roots that left the workspace scope.
+ * @param removed - instruction files that are no longer present.
+ * @returns the message text, or `undefined` when there is nothing to say.
+ */
+export declare function composeInstructionMessage(rendered: readonly RenderedRoot[], revoked: readonly string[], removed: readonly RemovedScope[]): string | undefined;
+/** This row is gated on the compatibility contract like every other provider. */
+export declare const inject: string[];
+/**
+ * Mount the additional-root instruction provider.
+ *
+ * `fs` is a SOFT dependency, like the scope service's prompt contribution: a
+ * composition with no filesystem seam (headless probes, bare test contexts)
+ * contributes nothing instead of failing to load. The same is true of the
+ * upstream instruction package, which is an optional peer.
+ *
+ * Touch recording is registered OUTSIDE the `fs` injection, so a composition
+ * without a filesystem seam still learns which directories the session worked
+ * in; delivery is what needs the seam.
+ * @param ctx - the row's context.
+ * @param config - the row's configuration.
+ */
+export declare function apply(ctx: Context, config?: Config): void;

package/lib/types/registry-lease-win32.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Windows named-kernel-semaphore adapter for the registry authority lease.
+ *
+ * This follows the same kernel-object contract as upstream
+ * `SessionWriteLease` (published `@deepseek-ai/dsh-session-persistence-jsonl`
+ * 0.1.5-rc.2): a count-1 named semaphore, a zero-timeout wait, and release by
+ * restoring the count then closing the handle — the object dies with its last
+ * handle, including on process death. It is a local reimplementation; it does
+ * not deep-import `session-persistence-jsonl/src/win32.ts` (ADR-0002).
+ *
+ * Koffi is loaded lazily so POSIX processes never load it.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/registry-lease-win32
+ */
+/**
+ * Derive the semaphore name from the physical parent directory, resolving
+ * junctions, symlinks and short path aliases before case folding and hashing.
+ * @param path - the lock path; its parent exists, but the file need not.
+ * @returns the store's kernel-object name.
+ */
+export declare function leaseNameWin32(path: string): string;
+/** Acquire the semaphore for the physical store directory. */
+export declare function acquireLockHandleWin32(path: string): Promise<number>;
+/**
+ * Restore the semaphore count and close the handle (the object dies with its
+ * last handle, including on process death).
+ * @param handle - the open semaphore handle.
+ */
+export declare function releaseLockHandleWin32(handle: number): Promise<void>;

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

@@ -0,0 +1,62 @@
+/**
+ * Store-wide kernel lease for the multi-root registry.
+ *
+ * The JSON storage backend is memory-authoritative after `open`: it reads the
+ * domain document once, then every write is an atomic rewrite of that in-memory
+ * snapshot. Two DSH processes sharing one storage root can therefore each grant
+ * a stale set, and a later rewrite silently drops the other process's mutation.
+ * The in-process `chains` queue in `registry.ts` cannot see that race.
+ *
+ * This lease makes one process the Registry Authority for the whole
+ * `multi_root_workspace` medium. The arbiter is the kernel, matching upstream
+ * session JSONL persistence: POSIX non-blocking `flock(2)` via
+ * `@deepseek-ai/node-addon-system/flock`, Windows a named kernel semaphore.
+ * There is no TTL and no stale-PID algorithm — the kernel releases the lock
+ * when the holder's descriptor (or last object handle) closes, including on
+ * crash. See ADR-0007.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/registry-lease
+ */
+/** Thrown when another live process already holds the registry lease. */
+export declare class RegistryLeaseContendedError extends Error {
+    /** Stable code the registry maps onto `registry-contended`. */
+    readonly code: "registry-contended";
+    /** Absolute lock path that was contended. */
+    readonly leasePath: string;
+    /**
+     * @param leasePath - the store-wide lock path that was contended.
+     */
+    constructor(leasePath: string);
+}
+/**
+ * One held store-wide registry lock. Constructed only by
+ * {@link RegistryAuthorityLease.acquire}; `release` closes the descriptor or
+ * handle, which is what releases the lock.
+ */
+export declare class RegistryAuthorityLease {
+    private readonly held;
+    private released;
+    private constructor();
+    /**
+     * Acquire the exclusive kernel lock for one registry store.
+     *
+     * POSIX opens `leasePath` (creating it and its parent) and takes a
+     * non-blocking exclusive flock. Because flock names an inode, the holder then
+     * verifies the locked inode is still the file at `leasePath` and retries
+     * otherwise — an unlinked-and-recreated lock file carries a fresh inode.
+     * Windows never flocks the file: it holds a named kernel semaphore derived
+     * from the canonical path so readers and directory removal stay free.
+     * @param leasePath - absolute path of the lock file (store-wide, beside the domain JSON).
+     * @returns the held lease.
+     * @throws {RegistryLeaseContendedError} while another holder keeps the lock.
+     */
+    static acquire(leasePath: string): Promise<RegistryAuthorityLease>;
+    /**
+     * Release the kernel lock by closing its descriptor or handle. The POSIX
+     * lock file is never removed: keeping it preserves the stable inode later
+     * lockers verify against. POSIX close is synchronous so a fiber disposer that
+     * does not await this promise still drops the flock before returning.
+     * Idempotent.
+     */
+    release(): Promise<void>;
+}

package/lib/types/registry.d.ts

@@ -8,7 +8,7 @@
  * (`ctx.multiRootScope`). Neither provider learns that a registry exists —
  * `setAdditionalRoots()` stays the scope's only write port.
  *
- * Four deliberate properties:
+ * Five deliberate properties:
  *
  * - **Only usable roots are granted.** A registered directory that is absent
  *   right now stays registered and is reported as `missing`, but is withheld
@@ -33,6 +33,11 @@
  *   re-stats and re-canonicalizes every record, republishes the scope, and
  *   leaves storage untouched — a read must not rewrite the store, and a
  *   read-only refresh must not resurrect anything.
+ * - **One process is the Registry Authority.** The JSON backend is
+ *   memory-authoritative after open, so two DSH processes sharing a storage
+ *   root cannot each keep a live domain snapshot. A store-wide kernel lease
+ *   (ADR-0007) elects one authority; a contended process publishes an empty
+ *   scope, rejects mutations, and retries the lease from {@link MultiRootRegistry.refresh}.
  *
  * @module @dsh-electron/dsh-plugin-multi-root-workspace/registry
  */
@@ -46,6 +51,34 @@ export declare const DOMAIN_NAME = "multi_root_workspace";
 export declare const TABLE_NAME = "roots";
 /** Longest accepted display alias. */
 export declare const MAX_ALIAS_LENGTH = 120;
+/**
+ * Operator-facing English for a contended lease. Host-side commands have no
+ * locale; the panel also shows this string verbatim via `RootsView.unavailable`.
+ */
+export declare const REGISTRY_CONTENDED_MESSAGE = "the root registry is owned by another DSH process; additional roots are not granted here. Close the other process, then retry.";
+/**
+ * Whether this process is the Registry Authority for the store-wide domain
+ * medium. Contended and storage-failed are both fail-closed: the scope stays
+ * empty and mutations reject.
+ */
+export type RegistryAuthorityState = {
+    readonly kind: 'active';
+} | {
+    readonly kind: 'contended';
+} | {
+    readonly kind: 'storage-failed';
+    readonly reason: string;
+};
+/**
+ * Plugin configuration for the registry row. `leasePath` must sit beside the
+ * JSON backend's domain document; the patch default is
+ * `$DSH_HOME/storages/multi_root_workspace.lock`. A custom `storage-json.root`
+ * must override this in lockstep (ADR-0007).
+ */
+export interface Config {
+    /** Absolute path of the store-wide kernel lock file. */
+    readonly leasePath?: string;
+}
 declare module '@deepseek-ai/cordis' {
     interface Context {
         multiRootRegistry: MultiRootRegistry;
@@ -99,40 +132,59 @@ export interface AddRootInput {
 /** The registry service: `ctx.multiRootRegistry`. */
 export declare class MultiRootRegistry extends Service {
     static inject: string[];
-    /** The open table; present once the service has started. */
-    private table?;
-    /** Why the store is unusable, when it is; every mutation then fails loudly. */
-    private failure?;
+    /** Absolute lock path; absent means the row was composed without `leasePath`. */
+    private readonly leasePath;
+    /** Whether this process currently owns the store. */
+    private authorityState;
+    /** Held kernel lease; present once acquire succeeded, including after a failed open. */
+    private lease;
+    /** Open domain handle; present only while {@link authority} is `active`. */
+    private domain;
+    /** The open table; present once this process is the authority. */
+    private table;
     /** Last classified status list per canonical primary root. */
     private readonly cache;
     /** Signature of the last published grant per key, so a no-op refresh stays a no-op. */
     private readonly published;
     /** One promise chain per canonical primary root: mutations never interleave. */
     private readonly chains;
+    /** Store-wide queue for lease acquire / open / release. */
+    private authorityChain;
     /** Change listeners, keyed by their own disposer identity. */
     private readonly listeners;
+    /** True after a contended-lease warning has been emitted, so refresh does not spam. */
+    private loggedContended;
+    /** True once the fiber disposer has run: no further acquisition may happen. */
+    private disposed;
     /**
      * @param ctx - the host context; `storageDomain` and `multiRootScope` are injected.
+     * @param config - the patch row's `leasePath`.
      */
-    constructor(ctx: Context);
+    constructor(ctx: Context, config?: Config);
     /**
-     * Open the domain and publish every stored root into the scope.
+     * Become the Registry Authority if possible: acquire the store-wide lease,
+     * then open the domain and publish every stored root into the scope.
      *
-     * A store this build cannot read (corrupt records, a version written by a
-     * different plugin version) is reported loudly and degrades to the empty
-     * root set instead of failing activation: granting nothing is the safe
-     * direction, and a broken side store must not keep the whole harness from
-     * starting. Every mutation then reports `storage-unavailable` with that
-     * reason until the file is repaired or removed.
+     * A contended lease is fail-closed rather than a stale open: this process
+     * grants nothing and every mutation reports `registry-contended`. A store
+     * this build cannot read is reported loudly and also grants nothing. Neither
+     * case fails activation — a broken or contended side store must not keep the
+     * whole harness from starting. {@link MultiRootRegistry.refresh} retries.
      */
     protected [Service.init](): Promise<void>;
     /**
-     * Why the store is unusable, when it is. Surfaces show this instead of a
-     * silently empty list, so an operator can tell "no roots configured" from
-     * "the configuration could not be read".
-     * @returns the recorded failure text, or `undefined` while the store is healthy.
+     * Why the registry is not granting, when it is not. Surfaces show this
+     * instead of a silently empty list, so an operator can tell "no roots
+     * configured" from "another DSH process owns the store" or "the file could
+     * not be read".
+     * @returns the recorded failure text, or `undefined` while this process is the authority.
      */
     get unavailable(): string | undefined;
+    /**
+     * Whether this process is the Registry Authority for the store-wide medium.
+     * Tests and diagnostics read this; surfaces use {@link unavailable}.
+     */
+    get authority(): RegistryAuthorityState;
     /**
      * Every registration of one primary root, in registry order, as last
      * classified. A READ of the in-memory state: it never touches the filesystem
@@ -156,6 +208,11 @@ export declare class MultiRootRegistry extends Service {
      *
      * The serialized queue is shared with the mutations, so a refresh never
      * interleaves with a write that is mid-flight.
+     *
+     * Refresh is also the takeover path: it calls {@link MultiRootRegistry.ensureAuthority}
+     * first, so a process that started contended can become the authority after
+     * the previous holder exits, re-open the domain from disk, and publish the
+     * last durable state — without a restart.
      * @param primaryRoot - the session workspace root to re-check.
      * @returns the refreshed status list.
      */
@@ -284,10 +341,64 @@ export declare class MultiRootRegistry extends Service {
     /**
      * The open table.
      * @returns the live table.
-     * @throws {RootValidationError} `storage-unavailable` when the store could
-     *   not be opened at activation, or the service has not started.
+     * @throws {RootValidationError} `registry-contended` when another DSH process
+     *   owns the store, `storage-unavailable` when the store could not be opened,
+     *   or an error when the service has not started.
      */
     private requireTable;
+    /**
+     * Reject mutations unless this process is the Registry Authority.
+     * Called before path validation so a contended process never mis-reports
+     * `missing` / `not-absolute` for a directory it is not allowed to register.
+     */
+    private requireActive;
+    /**
+     * Acquire the store-wide lease if this process does not already hold it, then
+     * open the domain from disk. Idempotent while active. A contended process
+     * retries here (the command `list` and the panel Retry button both call
+     * {@link MultiRootRegistry.refresh}).
+     */
+    private ensureAuthority;
+    /**
+     * Open the domain under an already-held lease and publish every stored root.
+     * On failure the lease is kept so a later refresh can retry the open without
+     * letting a second process grant from a stale snapshot.
+     */
+    private openDomain;
+    /** Fail closed: empty scope, no table, contended state. */
+    private enterContended;
+    /** Fail closed: empty scope, no table, storage-failed state. The lease, if held, stays. */
+    private enterStorageFailed;
+    /** Drop every grant this process has published. Idempotent. */
+    private withdrawPublished;
+    /**
+     * Drain every queued mutation, close the domain, then release the kernel
+     * lease — in that order, and inside the authority-transition queue.
+     *
+     * The order is the invariant, not a detail. The lease is what makes "the
+     * store is mine" true, so it must outlive every write this process will ever
+     * make, including the queued writes `close()` itself drains: a successor that
+     * acquired the lease and opened the medium in the window between a release
+     * and a `put()` would read a snapshot missing that mutation. Running the
+     * whole teardown through {@link MultiRootRegistry.serializeAuthority} is the
+     * other half: a `refresh()` that is mid-flight when the fiber disposes must
+     * not finish by opening a domain and a lease that nothing will ever close.
+     */
+    private releaseAuthority;
+    /**
+     * Wait until no per-primary-root mutation is queued or running.
+     *
+     * One pass is enough, and only because the authority state has already been
+     * flipped: no further mutation can be admitted (it would fail in
+     * `requireTable()`), and every mutation admitted earlier put its own tail in
+     * `chains` before it ran.
+     */
+    private drainMutations;
+    /**
+     * Run one authority-transition job after every job already queued. Acquire,
+     * open, and release never interleave with each other.
+     */
+    private serializeAuthority;
 }
 export type { AdditionalRootId, RegisteredRoot, RootRef, RootStatus };
 export default MultiRootRegistry;

package/lib/types/roots.d.ts

@@ -108,7 +108,7 @@ export type RootRef = {
     readonly addedAt: string;
 };
 /** Every way root handling can fail, as a stable code the surfaces localize. */
-export type RootValidationCode = 'not-absolute' | 'missing' | 'not-a-directory' | 'equals-primary' | 'primary-overlap' | 'duplicate' | 'nested' | 'invalid-alias' | 'not-found' | 'invalid-ref' | 'storage-unavailable' | 'reveal-unavailable';
+export type RootValidationCode = 'not-absolute' | 'missing' | 'not-a-directory' | 'equals-primary' | 'primary-overlap' | 'duplicate' | 'nested' | 'invalid-alias' | 'not-found' | 'invalid-ref' | 'storage-unavailable' | 'registry-contended' | 'reveal-unavailable' | 'session-not-found';
 /** A rejected root operation; `code` is the stable contract, `message` the fallback prose. */
 export declare class RootValidationError extends Error {
     readonly code: RootValidationCode;

package/lib/types/sandbox.d.ts

@@ -26,9 +26,10 @@
  *
  * @module @dsh-electron/dsh-plugin-multi-root-workspace/sandbox
  */
-import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox';
+import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox';
 import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local';
 import type { Config } from '@deepseek-ai/dsh-sandbox-local';
+import type { UpstreamConfined } from './compat/sandbox-confine.ts';
 export type { Config };
 /**
  * Local process-sandbox provider over the multi-root scope. Registers as
@@ -48,11 +49,30 @@ export declare class MultiRootSandboxProvider extends LocalSandboxProvider {
      * bash executor and the PTY backend both hand their argv straight to the local
      * runtime in that mode. Widening therefore only ever ADDS the scope's
      * additional roots to an upstream `workspace-write` profile.
+     *
+     * The return shape is the INSTALLED upstream provider's: synchronous on a
+     * release with a synchronous `confine`, a promise on a release with an
+     * asynchronous one. `widenConfined` preserves whichever it is — see
+     * `./compat/sandbox-confine.ts`.
      * @param argv - the exact argv the caller is about to spawn.
      * @param policy - the file-effect policy this execution runs under.
+     * @param signal - cancellation, forwarded to releases that accept it.
      * @returns the argv to spawn instead, plus the selected backend's facts.
      */
-    confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv;
+    confine(argv: readonly string[], policy: SandboxPolicy, signal?: AbortSignal): UpstreamConfined;
+    /**
+     * Graft the scope's additional roots onto one upstream `confine` result.
+     *
+     * Pure with respect to the upstream call: it only ever reads the scope and
+     * rewrites `argv`. `enforcement`, `denialSignatures` and `runnerFailureRules`
+     * are passed through untouched, because the bash executor derives its denial
+     * and enforcement reporting from them.
+     * @param confined - the upstream result for this call.
+     * @param argv - the caller's argv, needed to re-split the wrapped form.
+     * @param policy - the per-call policy.
+     * @returns the upstream result element for element, or one with a widened argv.
+     */
+    private widenForScope;
     /**
      * Report the documented first-release limitation exactly once: the Windows ACL
      * rung grants through per-workspace write SIDs rather than argv paths, so