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

package/lib/types/registry.d.ts

@@ -0,0 +1,293 @@
+/**
+ * `MultiRootRegistry`: the durable answer to "which directories are extra
+ * writable roots of this workspace".
+ *
+ * It is the M3 data source the M2 providers were already written against: the
+ * registry owns the records, validates every mutation, re-validates everything
+ * it reads back, and feeds the ONE place enforcement resolves from
+ * (`ctx.multiRootScope`). Neither provider learns that a registry exists —
+ * `setAdditionalRoots()` stays the scope's only write port.
+ *
+ * Four 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
+ *   from the scope: handing a nonexistent root to bwrap or Landlock would fail
+ *   the confined command instead of merely not granting it. A registration
+ *   whose path now resolves to a DIFFERENT directory is `redirected` and is
+ *   withheld for the same reason it was never granted: re-resolving a path is
+ *   not re-authorizing it (see `src/scope.ts`).
+ * - **Nothing is deleted on the operator's behalf.** A record that violates a
+ *   rule is reported as `invalid` and excluded from the scope; it disappears
+ *   only when the operator removes it (or when the store is repaired). Storage
+ *   that cannot be parsed at all is backed up and skipped by the domain layer,
+ *   with a warning.
+ * - **Mutations are serialized per primary root.** Every mutation runs its
+ *   whole read → validate → persist sequence inside one queue per key. The
+ *   storage domain serializes individual `put()`/`delete()` calls, which is not
+ *   enough: two concurrent `add()` calls would both read the same snapshot and
+ *   the later write would drop the earlier one, and a removal racing an add
+ *   could write a deleted record back.
+ * - **Reads re-check, but never write.** {@link MultiRootRegistry.refresh} is
+ *   the one revalidation entry point the command and the panel both call: it
+ *   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.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/registry
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox';
+import { z } from 'zod';
+import { type AdditionalRootId, type RegisteredRoot, type RootRef, type RootStatus } from './roots.ts';
+/** The domain name; also the store file stem (`$DSH_HOME/storages/<name>.json`). */
+export declare const DOMAIN_NAME = "multi_root_workspace";
+/** The single table name inside the domain. */
+export declare const TABLE_NAME = "roots";
+/** Longest accepted display alias. */
+export declare const MAX_ALIAS_LENGTH = 120;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        multiRootRegistry: MultiRootRegistry;
+    }
+}
+/**
+ * One primary root's whole registration list. The domain's `single` layout
+ * stores the entire unit as one document, so keys stay opaque strings — which
+ * is exactly what lets the canonical primary root itself be the key.
+ */
+declare const persistedPrimaryRoot: z.ZodObject<{
+    roots: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        recordedPath: z.ZodOptional<z.ZodString>;
+        alias: z.ZodOptional<z.ZodString>;
+        addedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Stored shape of one primary root's records. */
+export type PersistedPrimaryRoot = z.infer<typeof persistedPrimaryRoot>;
+/**
+ * The domain declaration: version 1, `single` layout, one `roots` table keyed
+ * by the canonical primary root. Records that fail validation are backed up and
+ * skipped rather than blocking the whole harness from starting (see
+ * docs/decisions/ADR-0004).
+ */
+export declare const multiRootDomainSpec: {
+    name: string;
+    version: number;
+    invalidRecords: "backup-and-skip";
+    tables: {
+        roots: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            roots: {
+                id: string;
+                path: string;
+                addedAt: string;
+                recordedPath?: string | undefined;
+                alias?: string | undefined;
+            }[];
+        }>;
+    };
+};
+/** Registration request for one new additional root. */
+export interface AddRootInput {
+    /** The directory, as typed by the operator (a leading `~` is expanded). */
+    readonly path: string;
+    /** Optional display alias. */
+    readonly alias?: string;
+}
+/** 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?;
+    /** 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;
+    /** Change listeners, keyed by their own disposer identity. */
+    private readonly listeners;
+    /**
+     * @param ctx - the host context; `storageDomain` and `multiRootScope` are injected.
+     */
+    constructor(ctx: Context);
+    /**
+     * 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.
+     */
+    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.
+     */
+    get unavailable(): string | undefined;
+    /**
+     * Every registration of one primary root, in registry order, as last
+     * classified. A READ of the in-memory state: it never touches the filesystem
+     * and never writes. Surfaces that must re-check the directories first call
+     * {@link MultiRootRegistry.refresh}.
+     * @param primaryRoot - the session workspace root (any spelling).
+     * @returns the statuses; empty when nothing is registered.
+     */
+    list(primaryRoot: string): readonly RootStatus[];
+    /**
+     * Re-examine every registration of one primary root WITHOUT writing storage:
+     * re-`stat` every directory, re-resolve every path against its recorded
+     * directory, re-judge every rule, then republish the scope and notify
+     * listeners.
+     *
+     * This is the one revalidation entry point the command (`/workspace-folders
+     * list`) and the panel (`list` endpoint) both call, so "what the list shows"
+     * and "what is granted" cannot drift: a directory deleted after registration
+     * becomes `missing` and loses its grant, and a directory that came back is
+     * granted again — without either surface asking for a restart.
+     *
+     * The serialized queue is shared with the mutations, so a refresh never
+     * interleaves with a write that is mid-flight.
+     * @param primaryRoot - the session workspace root to re-check.
+     * @returns the refreshed status list.
+     */
+    refresh(primaryRoot: string): Promise<readonly RootStatus[]>;
+    /**
+     * Registers one additional root.
+     * @param primaryRoot - the session workspace root the root belongs to.
+     * @param input - the directory and optional alias.
+     * @returns the updated status list.
+     * @throws {RootValidationError} when the candidate violates a root rule.
+     */
+    add(primaryRoot: string, input: AddRootInput): Promise<readonly RootStatus[]>;
+    /**
+     * Remove one registration.
+     * @param primaryRoot - the session workspace root the root belongs to.
+     * @param ref - which registered root to remove.
+     * @returns the updated status list.
+     * @throws {RootValidationError} `not-found` when the reference matches nothing.
+     */
+    remove(primaryRoot: string, ref: RootRef): Promise<readonly RootStatus[]>;
+    /**
+     * Remove exactly one registration — the one the reference names.
+     *
+     * Unlike a filter by id, this removes a single record, so a store holding two
+     * records that share an id can be cleaned up one entry at a time instead of
+     * losing both to one click.
+     * @param primaryRoot - the session workspace root the root belongs to.
+     * @param ref - which registered root to remove.
+     * @returns the updated status list.
+     * @throws {RootValidationError} `not-found` when the reference matches nothing.
+     */
+    removeAt(primaryRoot: string, ref: RootRef): Promise<readonly RootStatus[]>;
+    /**
+     * Set or clear one registration's display alias.
+     * @param primaryRoot - the session workspace root the root belongs to.
+     * @param ref - which registered root to rename.
+     * @param alias - the new alias; empty or absent clears it.
+     * @returns the updated status list.
+     * @throws {RootValidationError} `not-found`/`invalid-alias`.
+     */
+    setAlias(primaryRoot: string, ref: RootRef, alias: string | undefined): Promise<readonly RootStatus[]>;
+    /**
+     * Move one registration within the display order.
+     * @param primaryRoot - the session workspace root the root belongs to.
+     * @param ref - which registered root to move.
+     * @param beforeRef - the anchor to move in front of; absent moves it to the end.
+     * @returns the updated status list.
+     * @throws {RootValidationError} `not-found` when either reference matches nothing.
+     */
+    move(primaryRoot: string, ref: RootRef, beforeRef?: RootRef): Promise<readonly RootStatus[]>;
+    /**
+     * Re-examine every registration of one primary root and persist what the
+     * re-examination produced — {@link MultiRootRegistry.refresh} plus one durable
+     * write. The recovery path after a directory was restored by hand, and the
+     * only read-shaped operation that is allowed to touch the store.
+     * @param primaryRoot - the session workspace root to re-check.
+     * @returns the refreshed status list.
+     */
+    recheck(primaryRoot: string): Promise<readonly RootStatus[]>;
+    /**
+     * Observe registry changes.
+     * @param listener - called with the canonical primary root after each durable change.
+     * @returns the disposer that stops observing.
+     */
+    onChange(listener: (primaryRoot: string) => void): () => void;
+    /**
+     * The scope the registry publishes: only usable roots, in registry order.
+     * @param primaryRoot - the session workspace root (any spelling).
+     * @returns the canonical paths of every `available` root.
+     */
+    granted(primaryRoot: string): readonly string[];
+    /**
+     * The scope the registry publishes: only usable roots, in registry order.
+     * @param policy - the per-call policy; its workspace root is the primary root.
+     * @returns the granted canonical roots.
+     */
+    grantedFor(policy: SandboxExecutionPolicy): readonly string[];
+    /** Classify one stored record set and cache it. */
+    private accept;
+    /**
+     * The statuses of one key, from memory where possible: the cache, else what
+     * storage holds, else empty. A cached answer is never re-checked here — that
+     * is {@link MultiRootRegistry.reclassify}, which the read surfaces and
+     * {@link MultiRootRegistry.refresh} call deliberately.
+     */
+    private statusesOf;
+    /**
+     * The stored record set of one key, or `undefined` when there is none (or
+     * when the store itself could not be read: an unusable store reads as
+     * "nothing registered" so reads stay answerable and the surfaces can explain
+     * the situation, while every write fails loudly in `requireTable()`).
+     */
+    private lookupRecords;
+    /**
+     * Re-classify one key from its stored records: every directory is `stat`ed
+     * again and every path is resolved again against its recorded canonical
+     * directory. Updates the cache, republishes the scope, and returns the new
+     * list — the shared body of the read-path re-checks.
+     */
+    private reclassify;
+    /**
+     * Persist one status list, then republish it into the scope and to listeners.
+     * The durable write happens first: a failed write must not leave the running
+     * scope granting something storage does not hold.
+     */
+    private persist;
+    /**
+     * Run one job for one primary root after every job already queued for that
+     * root. The whole read → validate → write sequence belongs inside the job:
+     * the storage domain serializes individual writes, so without this the loser
+     * of a race reads a snapshot that is already stale and writes it back.
+     */
+    private serialize;
+    /**
+     * Push one status list into the scope and notify listeners.
+     *
+     * What is published is the effective GRANT — only `available` roots, so a
+     * withheld registration can never reach a provider. When the grant and the
+     * withheld set are unchanged (the common case for a read-path refresh on a
+     * healthy workspace) the scope is left alone and no listener fires: a refresh
+     * exists to keep the two in sync, not to churn on every listing — and, since
+     * the scope rebuilds its root table on each call, skipping the no-op write is
+     * also what keeps the read path cheap.
+     */
+    private publish;
+    /**
+     * 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.
+     */
+    private requireTable;
+}
+export type { AdditionalRootId, RegisteredRoot, RootRef, RootStatus };
+export default MultiRootRegistry;

package/lib/types/roots.d.ts

@@ -0,0 +1,238 @@
+/**
+ * The root vocabulary: identities, the durable record shape, the status a
+ * stored record is reported with, and the validation rules every write and
+ * every startup re-read passes through.
+ *
+ * This module is the single home of "what makes a directory a legal additional
+ * root" (requirement §15). Both the registry (which persists) and the command
+ * and panel surfaces (which report) speak these types, so a rule can never be
+ * enforced on one path and forgotten on another.
+ *
+ * Rules, applied in this order — the first failure names the reason:
+ *
+ * 1. `not-absolute` — a relative input (after `~` expansion) is a
+ *    misconfiguration, not a path to guess at.
+ * 2. `missing` — the directory does not exist.
+ * 3. `not-a-directory` — it exists but is not a directory.
+ * 4. `equals-primary` — the canonical candidate IS the session's workspace
+ *    root, which is already granted by the upstream policy.
+ * 5. `primary-overlap` — the candidate lies under the workspace root, or
+ *    contains it. The union grants nothing new, and the displayed list would
+ *    stop matching the enforced root set.
+ * 6. `duplicate` — another registered root canonicalizes to the same path.
+ * 7. `nested` — the candidate lies under a registered root, or contains one.
+ *    Same reasoning as rule 5, applied to the additional roots.
+ *
+ * The stored side of the same rules lives in {@link classifyStoredRoots}, which
+ * must never throw: a registration that stopped being usable is REPORTED, not
+ * deleted, so the operator can see it and remove it deliberately.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/roots
+ */
+/**
+ * Stable identity of one registered additional root. A generated uuid, never
+ * the path: a path is re-canonicalized on every read and a display alias may
+ * change, while a reference anchor must stay put. The brand is local to this
+ * package — it is a compile-time distinction only and has no runtime form.
+ */
+export type AdditionalRootId = string & {
+    readonly __multiRootAdditionalRootId: 'AdditionalRootId';
+};
+/**
+ * Brand one generated uuid as an {@link AdditionalRootId}.
+ * @param value - the raw uuid.
+ * @returns the branded id.
+ */
+export declare function additionalRootId(value: string): AdditionalRootId;
+/** One registered additional root exactly as it is persisted. */
+export interface RegisteredRoot {
+    /** Stable registry identity. */
+    readonly id: AdditionalRootId;
+    /** Canonical absolute directory (the `realpath` captured at registration). */
+    readonly path: string;
+    /**
+     * The canonical directory this registration was GRANTED for: the `realpath`
+     * observed when the operator registered it (or the last time the operator
+     * restored it). Authorization is `canonicalPath(path) === recordedPath` — a
+     * root whose current resolution moved somewhere else is reported as
+     * `redirected` and withheld, never silently granted elsewhere.
+     */
+    readonly recordedPath?: string;
+    /** Optional display alias; absent when the operator cleared it. */
+    readonly alias?: string;
+    /** ISO-8601 instant of registration. */
+    readonly addedAt: string;
+}
+/**
+ * How one stored record currently stands.
+ *
+ * - `available` — the directory is there, resolves to the recorded canonical
+ *   directory, and is granted.
+ * - `missing` — the directory is not there right now; kept, withheld.
+ * - `redirected` — the path no longer resolves to the directory it was
+ *   registered for (it was replaced by a symlink, or a symlink in the chain
+ *   changed); kept, withheld, and `recheck` restores it once the original
+ *   directory is back.
+ * - `invalid` — the record violates a rule and can only be removed.
+ */
+export type RootState = 'available' | 'missing' | 'redirected' | 'invalid';
+/** One registered root as the surfaces report it. */
+export interface RootStatus extends RegisteredRoot {
+    /** Whether the root is granted right now, withheld, or unusable. */
+    readonly state: RootState;
+    /** Why the root is not `available`; absent otherwise. */
+    readonly detail?: string;
+}
+/** One status together with the 1-based ordinal the surfaces accept for it. */
+export interface IndexedRootStatus {
+    /** The 1-based position in the registration list. */
+    readonly ordinal: number;
+    /** The record at that position. */
+    readonly status: RootStatus;
+}
+/** How a caller names one registered root, including a verified surface snapshot. */
+export type RootRef = {
+    readonly kind: 'id';
+    readonly id: string;
+} | {
+    readonly kind: 'path';
+    readonly path: string;
+} | {
+    readonly kind: 'ordinal';
+    readonly ordinal: number;
+} | {
+    readonly kind: 'entry';
+    readonly ordinal: number;
+    readonly id: string;
+    readonly path: string;
+    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';
+/** A rejected root operation; `code` is the stable contract, `message` the fallback prose. */
+export declare class RootValidationError extends Error {
+    readonly code: RootValidationCode;
+    readonly detail?: {
+        readonly conflict?: string;
+        readonly reference?: string;
+    } | undefined;
+    /**
+     * @param code - stable failure code.
+     * @param message - human-readable fallback text (English; the panel localizes by code).
+     * @param detail - structured context, e.g. the conflicting root.
+     */
+    constructor(code: RootValidationCode, message: string, detail?: {
+        readonly conflict?: string;
+        readonly reference?: string;
+    } | undefined);
+}
+/**
+ * Expand the one shell shorthand an operator may reasonably type, and nothing
+ * else: a leading `~` (alone or as `~/…`). Every other relative spelling is
+ * left intact so validation can reject it as `not-absolute` instead of
+ * silently resolving it against some unrelated process cwd.
+ * @param raw - the raw operator input.
+ * @param home - the home directory to expand against; defaults to `os.homedir()`.
+ * @returns the expanded path (still unvalidated).
+ */
+export declare function expandRootInput(raw: string, home?: string): string;
+/**
+ * Whether `candidate` is `root` itself or lies beneath it. Both sides must
+ * already be canonical: symlinks are resolved by then, so the lexical test is
+ * exact for the alias cases (8.3 names, casing) the fence handles separately.
+ * @param candidate - canonical path to test.
+ * @param root - canonical root to test against.
+ * @returns whether the candidate is contained by the root.
+ */
+export declare function isCanonicallyUnder(candidate: string, root: string): boolean;
+/**
+ * Canonicalize a directory path the way the enforcement layers do (`realpath`),
+ * leaving an unreachable path untouched so the caller can report it as missing.
+ * @param path - the path to canonicalize.
+ * @returns the canonical path.
+ */
+export declare function canonicalRoot(path: string): string;
+/** Caller-supplied facts one candidate is judged against. */
+export interface RootCandidateContext {
+    /** The session's workspace root; the candidate may not equal or overlap it. */
+    readonly primaryRoot: string;
+    /**
+     * The home directory a leading `~` expands against. Defaults to `os.homedir()`;
+     * a caller that knows which home it means (a test, a probe) may say so instead
+     * of depending on where the host's home directory happens to sit.
+     */
+    readonly home?: string;
+    /**
+     * Canonical paths already granted. Missing and invalid registrations are
+     * deliberately excluded: a withheld root grants nothing, so a candidate may
+     * legitimately sit under it, and an unusable record must not block a store
+     * the operator is trying to make work again.
+     */
+    readonly existing: readonly string[];
+}
+/**
+ * Judge one candidate root and return its canonical spelling.
+ * @param raw - the raw operator input (a path, possibly `~`-prefixed).
+ * @param context - the primary root and the currently granted roots.
+ * @returns the canonical path the caller must store (and record as `recordedPath`).
+ * @throws {RootValidationError} with the first rule that failed.
+ */
+export declare function validateRootCandidate(raw: string, context: RootCandidateContext): string;
+/**
+ * Re-judge every stored record of one primary root — the startup and refresh
+ * path, which must never throw: a registration that stopped being usable is
+ * REPORTED, not deleted, so the operator can see it and remove it deliberately.
+ *
+ * Existence and reachability are the only rules a record may recover from on
+ * its own, hence `missing` and `redirected` (kept, withheld) rather than
+ * `invalid` (kept, unusable).
+ * @param primaryRoot - the session workspace root the records belong to.
+ * @param records - the stored records, in registry order.
+ * @returns one status per record, in the same order.
+ */
+export declare function classifyStoredRoots(primaryRoot: string, records: readonly RegisteredRoot[]): RootStatus[];
+/**
+ * The canonical roots a status list grants, in registry order.
+ * @param statuses - the statuses to project.
+ * @returns the canonical paths of every `available` root.
+ */
+export declare function availableRoots(statuses: readonly RootStatus[]): string[];
+/**
+ * Pair every status with the 1-based ordinal the surfaces accept for it. The
+ * ordinal belongs to the POSITION, so it stays correct even for records whose
+ * id is duplicated or missing — which is exactly the case where a positional
+ * removal is the only unambiguous way to delete one of them.
+ * @param statuses - the statuses to index.
+ * @returns one entry per status, in the same order.
+ */
+export declare function indexedStatuses(statuses: readonly RootStatus[]): IndexedRootStatus[];
+/**
+ * Resolve one operator-supplied reference against a status list.
+ * @param statuses - the statuses to search, in registry order.
+ * @param ref - the reference to resolve.
+ * @returns the matched status.
+ * @throws {RootValidationError} `not-found` when nothing matches.
+ */
+export declare function resolveRootRef(statuses: readonly RootStatus[], ref: RootRef): RootStatus;
+/**
+ * Resolve one reference to its exact position.
+ *
+ * Id/path references are accepted only when unique. An `entry` reference also
+ * verifies the row identity captured by the surface, so a concurrent reorder
+ * cannot turn a click into an operation on a different record.
+ */
+export declare function resolveRootIndex(statuses: readonly RootStatus[], ref: RootRef): number;
+/** Capture a list row as a mutation-safe reference. */
+export declare function entryRootRef(status: RootStatus, ordinal: number): RootRef;
+/**
+ * Remove exactly ONE record — the one the reference names — from a status list.
+ *
+ * Removing by id is rejected when it is ambiguous. Exact entry or ordinal
+ * references address one record, so a duplicate-id pair can be cleaned up one
+ * entry at a time without turning one operation into several.
+ * @param statuses - the statuses to remove from.
+ * @param ref - which record to remove.
+ * @returns a new list without that record, order preserved.
+ * @throws {RootValidationError} `not-found` when the reference matches nothing.
+ */
+export declare function removeStatusAt(statuses: readonly RootStatus[], ref: RootRef): RootStatus[];

package/lib/types/sandbox.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `MultiRootSandboxProvider`: the kernel-sandbox dialect provider mounted as
+ * `ctx.sandbox`.
+ *
+ * Every confined execution in this composition funnels through `confine()` —
+ * the bash executor wraps `['bash','-c',command]`, and the terminal backend
+ * wraps its PTY spawn argv — so widening the grant here is what gives bash, PTY,
+ * and the fs fence one and the same root set (requirement §13). The bash
+ * executor itself is therefore left upstream: it never computes roots.
+ *
+ * The widening itself lives in `./dialects.ts`: the upstream profile builders
+ * are unreachable in the published package, so the additional roots are grafted
+ * onto the profile `super.confine` actually produced (recognize the dialect
+ * structurally, clone its grant spelling, fail loudly when the shape is not
+ * known). This class owns only the policy that decides WHEN to graft:
+ *
+ * 1. with no additional roots, or under any mode other than `workspace-write`,
+ *    the upstream result is returned ELEMENT FOR ELEMENT — same argv, same
+ *    `enforcement`, same `denialSignatures`, same `runnerFailureRules`;
+ * 2. `enforcement`, `denialSignatures`, and `runnerFailureRules` are NEVER
+ *    recomputed here, even when the argv is widened — the bash executor derives
+ *    its denial and enforcement reporting from them;
+ * 3. only `argv` may differ, and a dialect whose shape cannot be extended fails
+ *    loudly (`SandboxUnavailableError`) instead of silently confining to the
+ *    primary root alone.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/sandbox
+ */
+import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox';
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local';
+import type { Config } from '@deepseek-ai/dsh-sandbox-local';
+export type { Config };
+/**
+ * Local process-sandbox provider over the multi-root scope. Registers as
+ * `ctx.sandbox`; the runner chain, probing, denial dialects, and Windows ACL
+ * grant mechanics stay the upstream implementation's.
+ */
+export declare class MultiRootSandboxProvider extends LocalSandboxProvider {
+    static inject: string[];
+    /** Whether the Windows ACL limitation has already been reported (once per provider). */
+    private warnedAboutWindowsAcl;
+    /**
+     * Wrap `argv` so it executes confined under `policy` on this host, granting
+     * the scope's additional roots inside the SAME dialect profile.
+     *
+     * Under `read-only` nothing is added (the mode denies every write, additional
+     * roots included), and `danger-full-access` never reaches here at all: the
+     * 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.
+     * @param argv - the exact argv the caller is about to spawn.
+     * @param policy - the file-effect policy this execution runs under.
+     * @returns the argv to spawn instead, plus the selected backend's facts.
+     */
+    confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv;
+    /**
+     * Report the documented first-release limitation exactly once: the Windows ACL
+     * rung grants through per-workspace write SIDs rather than argv paths, so
+     * additional roots stay unenforced for confined commands there while the
+     * in-process filesystem fence still allows them.
+     * @param rootCount - how many additional roots the scope carries.
+     */
+    private warnAboutWindowsAcl;
+}
+export default MultiRootSandboxProvider;