@dsh-electron/dsh-plugin-multi-root-workspace 0.1.6 → 0.1.7

package/lib/types/registry.d.ts

@@ -37,14 +37,15 @@
  *   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}.
+ *   scope marked `authority: 'unavailable'` — under which Full-access is
+ *   limited to primary-root-only writes — rejects mutations, and retries the lease
+ *   from {@link MultiRootRegistry.refresh}.
  *
  * @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';
+import { type AdditionalRootId, type RegisteredRoot, type RootAccess, 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. */
@@ -56,10 +57,20 @@ export declare const MAX_ALIAS_LENGTH = 120;
  * 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.";
+/**
+ * Default cap on stored additional-root records per primary root. The bench
+ * evidence for this default lives in `docs/reference/bench-root-scale-*.json`
+ * (`pnpm bench:roots`): classification and argv widening stay flat far beyond
+ * it, so the cap exists to bound the operator-facing list and the widened
+ * profile size, not to protect the classifier.
+ */
+export declare const DEFAULT_MAX_ADDITIONAL_ROOTS = 16;
+/** Hard ceiling for `maxAdditionalRoots`: values above it are config-invalid. */
+export declare const MAX_ADDITIONAL_ROOTS_CEILING = 64;
 /**
  * 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.
+ * empty, is marked `authority: 'unavailable'`, and mutations reject.
  */
 export type RegistryAuthorityState = {
     readonly kind: 'active';
@@ -68,6 +79,9 @@ export type RegistryAuthorityState = {
 } | {
     readonly kind: 'storage-failed';
     readonly reason: string;
+} | {
+    readonly kind: 'config-invalid';
+    readonly reason: string;
 };
 /**
  * Plugin configuration for the registry row. `leasePath` must sit beside the
@@ -78,6 +92,16 @@ export type RegistryAuthorityState = {
 export interface Config {
     /** Absolute path of the store-wide kernel lock file. */
     readonly leasePath?: string;
+    /**
+     * Cap on STORED additional-root records per primary root (every state
+     * counts, including withheld and unusable ones, so the count is stable and
+     * independent of the filesystem). Must be an integer in
+     * 1..{@link MAX_ADDITIONAL_ROOTS_CEILING}; an invalid value puts the
+     * registry in the fail-closed `config-invalid` state instead of throwing.
+     * A store that already exceeds the limit keeps every record and grants
+     * exactly what classification grants — only new adds are refused.
+     */
+    readonly maxAdditionalRoots?: number;
 }
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -85,21 +109,54 @@ declare module '@deepseek-ai/cordis' {
     }
 }
 /**
- * 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.
+ * Stored shape of one root record.
+ *
+ * The access level is expressed by WHICH grant key is present, never by an
+ * `access` field on the same `recordedPath` (ADR-0017):
+ *
+ * - `recordedPath` means `inherit` — the historical writable grant, which
+ *   under B9 keeps following the session mode. Upgrading a legacy record to
+ *   `inherit` changes nothing about its effective authority.
+ * - `readOnlyRecordedPath` means `read-only`.
+ * - `readWriteRecordedPath` means fixed `read-write` (B9).
+ *
+ * That split is what makes this single layout downgrade-safe at domain
+ * version 1 (the JSON backend checks the version with strict equality, so a
+ * bump would break both upgrade and downgrade):
+ *
+ * - an OLDER plugin version parses this record with a schema that strips
+ *   unknown keys, so a read-only or fixed read-write record loses its grant
+ *   field and arrives with NO `recordedPath`; the old classification reports
+ *   it `invalid` and grants nothing — a downgrade can never escalate either
+ *   restricted level into a write grant. A fixed read-write record must
+ *   therefore NEVER also write `recordedPath`: an older plugin would see the
+ *   legacy field and grant it as plain read-write;
+ * - a record with `recordedPath` only is the writable grant it always was,
+ *   so upgrading changes nothing for legacy records.
  */
-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>;
+type PersistedRoot = {
+    id: string;
+    path: string;
+    /**
+     * Absent only in records written before the field existed (or by hand),
+     * and in non-inherit records. Such a record is reported `invalid` rather
+     * than granted on a guess — see classifyStoredRoots.
+     */
+    recordedPath?: string | undefined;
+    readOnlyRecordedPath?: string | undefined;
+    readWriteRecordedPath?: string | undefined;
+    alias?: string | undefined;
+    addedAt: string;
+};
+/**
+ * Stored shape of one primary root's records: the 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.
+ */
+export type PersistedPrimaryRoot = {
+    roots: PersistedRoot[];
+};
 /**
  * The domain declaration: version 1, `single` layout, one `roots` table keyed
  * by the canonical primary root. Records that fail validation are backed up and
@@ -111,15 +168,7 @@ export declare const multiRootDomainSpec: {
     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;
-            }[];
-        }>;
+        roots: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, PersistedPrimaryRoot>;
     };
 };
 /** Registration request for one new additional root. */
@@ -128,6 +177,12 @@ export interface AddRootInput {
     readonly path: string;
     /** Optional display alias. */
     readonly alias?: string;
+    /**
+     * The write authority to register; defaults to `inherit` (the historical
+     * session-following grant). On a REVIVE the existing record keeps its
+     * access unless this field is given explicitly.
+     */
+    readonly access?: RootAccess;
 }
 /** The registry service: `ctx.multiRootRegistry`. */
 export declare class MultiRootRegistry extends Service {
@@ -156,9 +211,13 @@ export declare class MultiRootRegistry extends Service {
     private loggedContended;
     /** True once the fiber disposer has run: no further acquisition may happen. */
     private disposed;
+    /** The validated per-primary-root cap (the default when the row omits it). */
+    private readonly maxRoots;
+    /** Keys already warned about a historical over-limit store (one warning each). */
+    private readonly warnedOverLimit;
     /**
      * @param ctx - the host context; `storageDomain` and `multiRootScope` are injected.
-     * @param config - the patch row's `leasePath`.
+     * @param config - the patch row's `leasePath` and `maxAdditionalRoots`.
      */
     constructor(ctx: Context, config?: Config);
     /**
@@ -185,6 +244,17 @@ export declare class MultiRootRegistry extends Service {
      * Tests and diagnostics read this; surfaces use {@link unavailable}.
      */
     get authority(): RegistryAuthorityState;
+    /**
+     * The configured cap on stored additional-root records per primary root.
+     * Surfaces show it next to the count so "N of LIMIT" is always explainable.
+     */
+    get limit(): number;
+    /**
+     * Whether one primary root's stored record count exceeds {@link limit} — a
+     * historical over-limit store, which stays fully classified and granted.
+     * @param primaryRoot - the session workspace root (any spelling).
+     */
+    overLimit(primaryRoot: string): boolean;
     /**
      * Every registration of one primary root, in registry order, as last
      * classified. A READ of the in-memory state: it never touches the filesystem
@@ -225,6 +295,29 @@ export declare class MultiRootRegistry extends Service {
      * @throws {RootValidationError} when the candidate violates a root rule.
      */
     add(primaryRoot: string, input: AddRootInput): Promise<readonly RootStatus[]>;
+    /**
+     * Change one registration's write authority WITHOUT re-recording its path.
+     *
+     * Re-resolving is not re-authorizing: the grant keeps the canonical
+     * directory it was recorded for; only which persisted field carries it
+     * changes. The three levels are not a total order — `inherit` is weaker
+     * than `read-write` under a read-only session but stronger under
+     * Full-access — so "upgrade" cannot be a single direction. The gate is
+     * therefore: pinning to `read-only` is always allowed (a withheld root may
+     * be restricted while it is withheld), while ANY other target requires the
+     * root to be `available` under the FRESH classification — every
+     * non-read-only level can widen authority under some session mode, and a
+     * root that is not currently granted must not be granted anything by a
+     * metadata change.
+     * @param primaryRoot - the session workspace root the root belongs to.
+     * @param ref - which registered root to change.
+     * @param access - the new write authority.
+     * @returns the updated status list.
+     * @throws {RootValidationError} `not-found` when the reference matches
+     *   nothing, `root-unavailable` when the target is not `available` and the
+     *   new level is not `read-only`.
+     */
+    setAccess(primaryRoot: string, ref: RootRef, access: RootAccess): Promise<readonly RootStatus[]>;
     /**
      * Remove one registration.
      * @param primaryRoot - the session workspace root the root belongs to.
@@ -329,13 +422,21 @@ export declare class MultiRootRegistry extends Service {
     /**
      * 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
+     * What is published is the effective GRANT — membership requires
+     * `available`, so a withheld registration can never reach a provider as a
+     * grant. Withheld entries still publish for their DENY boundary alone;
+     * that includes `membership-conflict` records, whose recorded grant is
+     * intact and trustworthy even though their membership cannot stand. 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.
+     *
+     * Available roots keep registry order: instruction discovery consumes them
+     * under a shared byte budget, so a move must update the live scope immediately.
+     * Aliases and no-op moves still leave the signature unchanged.
      */
     private publish;
     /**

package/lib/types/roots.d.ts

@@ -22,13 +22,23 @@
  * 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.
+ * 8. `unsupported-path` — on Windows, a network or device path (`\\server`,
+ *    `\\?\…`, `\\.\…`): the ACL confinement cannot be shown to cover it, so it
+ *    is rejected lexically before any filesystem touch.
  *
  * 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.
+ * deleted, so the operator can see it and remove it deliberately. It runs in
+ * two passes — every record's own structural trust and availability first,
+ * then overlap between the RECORDED boundaries of all structurally sound
+ * records — so the answer never depends on registry order, and a pair of
+ * records whose grants collide (`membership-conflict`) keeps its trustworthy
+ * negative boundary even while its membership is withheld.
  *
  * @module @dsh-electron/dsh-plugin-multi-root-workspace/roots
  */
+import { isWindowsNetworkOrDevicePath } from './windows-runner-contract.ts';
+export { isWindowsNetworkOrDevicePath };
 /**
  * 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
@@ -44,6 +54,19 @@ export type AdditionalRootId = string & {
  * @returns the branded id.
  */
 export declare function additionalRootId(value: string): AdditionalRootId;
+/**
+ * The write authority one registration carries (B9, ADR-0017).
+ *
+ * - `inherit` — the root follows the session mode: writable under
+ *   `workspace-write` and unrestricted under `danger-full-access`, read-only
+ *   under `read-only`. This is what legacy `recordedPath` records mean.
+ * - `read-only` — the root stays a workspace member (instructions, LSP,
+ *   workspace-file routing, and reads all still see it) but a write is refused
+ *   under EVERY mode, including `danger-full-access`.
+ * - `read-write` — the root is writable under EVERY mode, including a global
+ *   `read-only` session; it does not widen anything beyond its own directory.
+ */
+export type RootAccess = 'inherit' | 'read-write' | 'read-only';
 /** One registered additional root exactly as it is persisted. */
 export interface RegisteredRoot {
     /** Stable registry identity. */
@@ -51,13 +74,35 @@ export interface RegisteredRoot {
     /** 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.
+     * The write authority this registration carries. In memory every record has
+     * exactly one value; on disk it is expressed by WHICH grant field is
+     * present — `recordedPath` means `inherit`, `readOnlyRecordedPath` means
+     * `read-only`, `readWriteRecordedPath` means `read-write` — never by a
+     * separate `access` key (see `registry.ts` for the downgrade safety that
+     * split buys).
+     */
+    readonly access: RootAccess;
+    /**
+     * The canonical directory this INHERIT 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;
+    /**
+     * The canonical directory this READ-ONLY registration was granted for. It
+     * plays exactly the role `recordedPath` plays for an inherit record, kept
+     * under a separate key so the single persisted layout stays downgrade-safe.
+     */
+    readonly readOnlyRecordedPath?: string;
+    /**
+     * The canonical directory this fixed READ-WRITE registration was granted
+     * for. Same role as the other two grant fields, under its own key: an older
+     * plugin strips the unknown field and classifies the record `invalid`
+     * rather than granting it as a legacy `recordedPath` write.
+     */
+    readonly readWriteRecordedPath?: string;
     /** Optional display alias; absent when the operator cleared it. */
     readonly alias?: string;
     /** ISO-8601 instant of registration. */
@@ -73,7 +118,9 @@ export interface RegisteredRoot {
  *   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.
+ * - `invalid` — the record violates a rule and can only be removed. Whether the
+ *   violation also voids the record's negative boundary is told apart by
+ *   {@link RootStatus.invalidReason}.
  */
 export type RootState = 'available' | 'missing' | 'redirected' | 'invalid';
 /** One registered root as the surfaces report it. */
@@ -82,6 +129,20 @@ export interface RootStatus extends RegisteredRoot {
     readonly state: RootState;
     /** Why the root is not `available`; absent otherwise. */
     readonly detail?: string;
+    /**
+     * Distinguishes WHY an `invalid` record is unusable. Internal only: it is
+     * neither persisted nor sent over the panel wire — `state` and `detail`
+     * carry everything a surface needs.
+     *
+     * `'membership-conflict'` means the record passed every structural rule —
+     * including an intact, absolute recorded grant — but its recorded boundary
+     * overlaps another record's. Neither membership may be granted while the
+     * conflict stands, yet the boundary remains a trustworthy negative
+     * restriction, so {@link reservedRootBoundary} keeps it reserved and the
+     * registry publishes the root as a withheld, deny-only entry. Every other
+     * `invalid` verdict left the grant unverifiable, so it contributes nothing.
+     */
+    readonly invalidReason?: 'membership-conflict';
 }
 /** One status together with the 1-based ordinal the surfaces accept for it. */
 export interface IndexedRootStatus {
@@ -108,7 +169,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' | 'registry-contended' | 'reveal-unavailable' | 'session-not-found';
+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' | 'root-limit-reached' | 'config-invalid' | 'reveal-unavailable' | 'session-not-found' | 'unsupported-path' | 'root-unavailable';
 /** A rejected root operation; `code` is the stable contract, `message` the fallback prose. */
 export declare class RootValidationError extends Error {
     readonly code: RootValidationCode;
@@ -163,10 +224,19 @@ export interface RootCandidateContext {
      */
     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.
+     * The platform the rules run for; defaults to `process.platform`. A caller
+     * (a test, a probe) may exercise another platform's rules — notably the
+     * Windows network/device-path refusal — on any host.
+     */
+    readonly platform?: NodeJS.Platform;
+    /**
+     * The recorded boundaries already reserved: {@link reservedRootBoundary}
+     * applied to every other status — available, missing, redirected, and
+     * membership-conflict records alike. A withheld root grants nothing, but
+     * its recorded boundary is the negative restriction a new writable root
+     * must not swallow while the operator has not removed it. Only a
+     * structurally invalid record contributes nothing, and the row being
+     * revived exempts only itself.
      */
     readonly existing: readonly string[];
 }
@@ -188,15 +258,32 @@ export declare function validateRootCandidate(raw: string, context: RootCandidat
  * `invalid` (kept, unusable).
  * @param primaryRoot - the session workspace root the records belong to.
  * @param records - the stored records, in registry order.
+ * @param platform - the platform the rules run for; defaults to `process.platform`.
  * @returns one status per record, in the same order.
  */
-export declare function classifyStoredRoots(primaryRoot: string, records: readonly RegisteredRoot[]): RootStatus[];
+export declare function classifyStoredRoots(primaryRoot: string, records: readonly RegisteredRoot[], platform?: NodeJS.Platform): 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[];
+/**
+ * The recorded boundary one status still RESERVES: the grant it was
+ * registered for, which a new or revived registration may not overlap merely
+ * because the root is currently unusable.
+ *
+ * `available`, `missing`, `redirected`, and membership-conflict statuses all
+ * carry an intact, trustworthy recorded grant; every other `invalid` verdict
+ * means the grant could not be parsed at all, so it reserves — and denies —
+ * nothing. This is not an independent authorization table: it derives the
+ * boundary from the status list {@link classifyStoredRoots} produced, with
+ * the same grant-extraction semantics, so its answer can never disagree with
+ * classification.
+ * @param status - one classified registration.
+ * @returns the absolute recorded boundary, or `undefined` when there is none.
+ */
+export declare function reservedRootBoundary(status: RootStatus): string | undefined;
 /**
  * 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

package/lib/types/sandbox.d.ts

@@ -27,7 +27,8 @@
  *
  * @module @dsh-electron/dsh-plugin-multi-root-workspace/sandbox
  */
-import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox';
+import type { Context } from '@deepseek-ai/cordis';
+import type { SandboxExecutionPolicy, 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';
@@ -39,6 +40,7 @@ export type { Config };
  */
 export declare class MultiRootSandboxProvider extends LocalSandboxProvider {
     static inject: string[];
+    constructor(ctx: Context, config: Config);
     /**
      * Wrap `argv` so it executes confined under `policy` on this host, granting
      * the scope's additional roots inside the SAME dialect profile.
@@ -60,17 +62,71 @@ export declare class MultiRootSandboxProvider extends LocalSandboxProvider {
      */
     confine(argv: readonly string[], policy: SandboxPolicy, signal?: AbortSignal): UpstreamConfined;
     /**
-     * Graft the scope's additional roots onto one upstream `confine` result.
+     * Graft the scope's effective grants and denies 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.
+     *
+     * Mode behavior (B9, R2): `workspace-write` widens the grant with the
+     * effective writable roots AND denies any restricted root the upstream
+     * grants could reach (a `read-only` root registered under the platform
+     * temp). `read-only` grafts the fixed `read-write` roots back onto the
+     * deny-all baseline — the three-state matrix's standout cell — and then
+     * applies the SAME deny pass: a grafted writable parent must not silently
+     * swallow a denied child (Seatbelt appends the deny after the allow, bwrap
+     * adds a mandatory `--ro-bind`, Landlock / windows-acl refuse the
+     * unrepresentable subtraction). `danger-full-access` never reaches
+     * here (consumers bypass `confine`); its deny semantics live in
+     * {@link restrictedArgvPrefix}.
      * @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.
+     * @param scope - the authorization snapshot taken at dispatch.
+     * @returns the upstream result element for element, or one with a rewritten argv.
      */
     private widenForScope;
+    /**
+     * Build the runner-prefix that confines an ambient-writable execution to
+     * everything EXCEPT `deniedRoots` — the `danger-full-access` + explicit
+     * `read-only` cell, which the shell, PTY and PTC consumers never route
+     * through `confine()` at all.
+     *
+     * The restricted profile does not depend on the callee's argv, so the prefix
+     * is computed once per call here and the synchronous `ctx.subprocess.spawn`
+     * seam only has to prepend it. The upstream profile builders stay private:
+     * this probes `confine` under `read-only` for the runner's argument skeleton
+     * and rewrites the file-effect part per dialect. Windows selects the
+     * standalone ambient deny-token runner. Landlock cannot express
+     * "everything except", so this combination selects bubblewrap; unusable
+     * runners fail without spawning an unconfined command.
+     *
+     * The return preserves the installed `confine` shape: a synchronous result
+     * on a synchronous release, a promise on an asynchronous one.
+     * @param policy - the caller's policy (mode must be `danger-full-access`).
+     * @param deniedRoots - canonical roots this execution must not write.
+     * @param signal - cancellation, forwarded to releases that accept it.
+     * @param protectedHome - diagnostics label: which deny root is the
+     *   protected `$DSH_HOME`. Forwarded to the Windows runner only when it is
+     *   a member of `deniedRoots`; it never changes authorization.
+     * @returns the argv prefix, ending at the `--` separator.
+     */
+    restrictedArgvPrefix(policy: SandboxExecutionPolicy, deniedRoots: readonly string[], signal?: AbortSignal, protectedHome?: string): readonly string[] | Promise<readonly string[]>;
+    /** Full-access restriction and the actual selected backend's diagnostics. */
+    restrictedExecution(policy: SandboxExecutionPolicy, deniedRoots: readonly string[], signal?: AbortSignal, protectedHome?: string): UpstreamConfined;
+    /**
+     * Limit an execution with unknown registry authority to the primary root.
+     * Shared temp grants are unsafe: another process may have registered a
+     * read-only root beneath them. Harvest the upstream read-only skeleton and
+     * graft only the primary root, retaining diagnostics and the sync/async shape.
+     * Explicit denies still win; an unrepresentable overlap refuses launch.
+     * @param policy - the caller's execution policy.
+     * @param deniedRoots - known negative boundaries, including protected home.
+     * @param signal - cancellation forwarded to upstream.
+     * @returns the confined prefix ending at `--`, without the caller's command.
+     */
+    clampedExecution(policy: SandboxExecutionPolicy, deniedRoots: readonly string[], signal?: AbortSignal): UpstreamConfined;
 }
 export default MultiRootSandboxProvider;