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

package/lib/types/contract.d.ts

@@ -13,7 +13,7 @@
  *   from endpoint to response type, so the panel cannot silently decode one
  *   endpoint's answer as another's. `reveal` answers with
  *   {@link RevealedView}; root-management endpoints answer with
- *   {@link RootsView}, and browsing returns {@link FilesView} or {@link FilePreview}.
+ *   {@link RootsView}.
  *   The host builds those answers in `command.ts` and the
  *   panel parses them here — one definition, two consumers.
  * - **Runtime validation at the boundary.** The payload arrives from a browser
@@ -31,21 +31,9 @@
 /** The absolute logical channel both halves speak over. */
 export declare const PANEL_CHANNEL = "/multi-root-workspace";
 /** Endpoint names, relative to {@link PANEL_CHANNEL}. */
-export type PanelEndpoint = 'list' | 'add' | 'remove' | 'alias' | 'move' | 'reveal' | 'files' | 'readFile';
+export type PanelEndpoint = 'list' | 'add' | 'remove' | 'alias' | 'move' | 'setAccess' | 'reveal';
 /** Every endpoint name, for exhaustive iteration in tests and callers. */
 export declare const PANEL_ENDPOINTS: readonly PanelEndpoint[];
-export interface FilesView {
-    readonly path: string;
-    readonly entries: readonly {
-        readonly name: string;
-        readonly type: 'file' | 'directory' | 'other';
-    }[];
-    readonly truncated: boolean;
-}
-export interface FilePreview {
-    readonly text: string;
-    readonly eof: boolean;
-}
 /**
  * How one registered root currently stands, as the panel renders it. Kept in
  * step with the root vocabulary in `src/roots.ts` deliberately: this module is
@@ -53,6 +41,17 @@ export interface FilePreview {
  * value the two sides share is spelled out rather than imported.
  */
 export type RootState = 'available' | 'missing' | 'redirected' | 'invalid';
+/**
+ * The write authority one registration carries (B9 three-state), spelled out
+ * rather than imported: this module is inlined into the browser bundle and
+ * must not pull in `node:*`, so the one value the two sides share is
+ * duplicated here.
+ */
+export type RootAccess = 'inherit' | 'read-write' | 'read-only';
+export type WorkspaceMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+export type EffectiveRootAccess = 'read-only' | 'read-write' | 'full-access' | 'unavailable';
+/** The shared nine-cell rule; tool dispatch may subsequently narrow writes. */
+export declare function effectiveRootAccess(access: RootAccess, mode: WorkspaceMode): EffectiveRootAccess;
 /** One root as the panel renders it. */
 export interface RootView {
     /** 1-based position in the returned snapshot. */
@@ -67,6 +66,10 @@ export interface RootView {
     readonly addedAt: string;
     /** Whether the directory is writable right now, withheld, or unusable. */
     readonly state: RootState;
+    /** The write authority the registration carries. */
+    readonly access: RootAccess;
+    /** Host-derived session permission, before any per-tool cap. */
+    readonly effectiveAccess?: EffectiveRootAccess;
     /** Why the root is not `available`; a code the panel localizes. */
     readonly detail?: string;
 }
@@ -89,8 +92,18 @@ export interface RootsView {
     readonly primaryName?: string;
     /** Execution directory only; never a registry key or an authorization grant. */
     readonly effectiveCwd?: string;
+    readonly mode?: WorkspaceMode;
+    readonly cappedTools?: readonly string[];
+    readonly toolAccessInvalid?: boolean;
     /** The additional roots, in registry order. */
     readonly roots: readonly RootView[];
+    /** The host cap; MAX_SAFE_INTEGER means a legacy host reported no limit. */
+    readonly limit: number;
+    /**
+     * How many records are stored, in every state. `count > limit` is a
+     * historical over-limit store: everything stays granted, only adds refuse.
+     */
+    readonly count: number;
     /** Set when the store itself could not be read; the panel shows this verbatim. */
     readonly unavailable?: string;
 }
@@ -106,9 +119,8 @@ export interface PanelResponseMap {
     readonly remove: RootsView;
     readonly alias: RootsView;
     readonly move: RootsView;
+    readonly setAccess: RootsView;
     readonly reveal: RevealedView;
-    readonly files: FilesView;
-    readonly readFile: FilePreview;
 }
 /**
  * The fields a request may carry. `sessionId` is required on every endpoint:
@@ -123,10 +135,12 @@ export interface PanelRequest {
     readonly entry?: RootEntryView;
     /** Compatibility reference; accepted only when the id is unique. */
     readonly id?: string;
-    /** Candidate directory (add), or root-relative browsing path (files/readFile). */
+    /** Candidate directory (add). */
     readonly path?: string;
     /** Display alias (add/alias); empty clears it. */
     readonly alias?: string;
+    /** Write authority (add — defaults to `inherit` — and setAccess). */
+    readonly access?: RootAccess;
     /** Exact anchor row (move): the target is placed in front of it; absent moves it last. */
     readonly beforeEntry?: RootEntryView;
     /** Compatibility anchor; accepted only when the id is unique. */
@@ -152,8 +166,6 @@ export type Parsed<T> = {
     readonly ok: false;
     readonly message: string;
 };
-export declare function parseFilesView(value: unknown): Parsed<FilesView>;
-export declare function parseFilePreview(value: unknown): Parsed<FilePreview>;
 /**
  * Validate the payload the host received for one endpoint.
  * @param endpoint - the endpoint the channel dispatched (the RPC method).

package/lib/types/dialects.d.ts

@@ -35,16 +35,20 @@
  * @module @dsh-electron/dsh-plugin-multi-root-workspace/dialects
  */
 import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox';
+import { DialectUnrecognizedError } from './windows-runner-contract.ts';
 /** The kernel runner dialects a confined argv can speak. */
 export type RunnerDialect = 'seatbelt' | 'bwrap' | 'landlock' | 'windows-acl';
 /**
  * Raised when a confined argv cannot be recognized or widened. The provider
  * converts this into the fail-closed `SandboxUnavailableError`: an unrecognized
  * dialect must never degrade into "the primary root was granted after all".
+ *
+ * The class itself lives in `windows-runner-contract.ts`: the standalone
+ * Windows runner's module graph may import node builtins only, so the shared
+ * error type cannot sit in a module that (even type-only) references upstream
+ * packages. Re-exported here unchanged — `instanceof` identity is preserved.
  */
-export declare class DialectUnrecognizedError extends Error {
-    constructor(message: string);
-}
+export { DialectUnrecognizedError };
 /** One wrapped argv split into its runner/profile part and the caller's argv. */
 export interface ConfinedShape {
     /** The recognized dialect. */
@@ -90,3 +94,95 @@ export declare function detectDialect(profileArgs: readonly string[]): RunnerDia
  * @returns the widened profile arguments.
  */
 export declare function widenProfileArgs(dialect: RunnerDialect, profileArgs: readonly string[], policy: SandboxPolicy, additionalRoots: readonly string[]): string[];
+/**
+ * Graft writable grants onto a `read-only` profile — the B9 cell where a fixed
+ * `read-write` additional root stays writable while the session mode denies
+ * every other write. Each dialect appends its own grant spelling AFTER
+ * upstream's deny-all baseline, so the appended form wins:
+ *
+ * - seatbelt: SBPL is last-match-wins — a trailing `(allow file-write*
+ *   (subpath …))` overrides the blanket `(deny file-write*)` for those roots;
+ * - bwrap: mounts apply in order — a `--bind W W` after `--ro-bind / /`
+ *   re-mounts that subtree writable inside the read-only namespace;
+ * - landlock: grants union — an extra `--rw W` widens exactly that subtree.
+ *
+ * `windows-acl` cannot be spelled this way and goes through
+ * `widenWindowsProfile` (the standalone runner grants only the listed roots).
+ * @param dialect - the recognized dialect.
+ * @param profileArgs - the upstream read-only profile arguments.
+ * @param additionalRoots - canonical roots the effective scope keeps writable.
+ * @returns the grafted profile arguments.
+ */
+export declare function graftProfileArgs(dialect: RunnerDialect, profileArgs: readonly string[], additionalRoots: readonly string[]): string[];
+/**
+ * Deny `deniedRoots` inside an upstream `workspace-write` profile — the B9 edge
+ * where an explicit `read-only` (or tool-capped) additional root sits under a
+ * directory the profile grants writable (the platform temp area, which an
+ * additional root may legitimately be registered beneath).
+ *
+ * A denied root outside every grant needs no profile work at all: the mode
+ * already denies it. Per dialect:
+ *
+ * - seatbelt appends a trailing `(deny file-write* (subpath …) (literal …))`
+ *   form — last match wins over every earlier allow, and a redundant deny on
+ *   an ungranted root is harmless. The literals pin every ancestor of a denied
+ *   root: Seatbelt checks the operated path only, so `rename`ing an ancestor
+ *   would otherwise move the whole tree out from under its `subpath` deny;
+ * - bwrap re-mounts the root `--ro-bind` AFTER the writable mounts (a later
+ *   mount wins inside the namespace). The source is mandatory: if a denied
+ *   root disappears, namespace setup fails before the command can recreate it.
+ *   This also restores read access to denied roots under a `--tmpfs` target.
+ *   Ancestors of a denied root that lie strictly inside a writable BIND target
+ *   are self-bound (`--bind A A`) BEFORE the ro-binds: the kernel refuses to
+ *   rename a mountpoint, so the deny can no longer be walked off by renaming
+ *   the tree's parent. Ancestors inside a `--tmpfs` target are never bound —
+ *   a rename there only moves namespace-private mounts, while the self-bind
+ *   would expose and make writable the host content the tmpfs hides — and
+ *   ancestors outside every writable target are not renamable anyway;
+ * - landlock cannot subtract: a denied root under an `--rw` grant throws —
+ *   union semantics have no deny primitive;
+ * - windows-acl goes through `widenWindowsProfile`, whose runner-side ACL
+ *   grant cannot subtract either — its caller checks the same overlap. The
+ *   deny ACE does follow its directory object through a parent rename, but
+ *   the moved tree's NEW path no longer matches the recorded deny set — so
+ *   the ambient deny runner pins every ancestor of each deny root with a
+ *   non-delete-sharing handle for the child lifetime (`windows-path-guard.ts`,
+ *   `windows-deny.ts`).
+ * @param dialect - the recognized dialect.
+ * @param profileArgs - the upstream workspace-write profile arguments.
+ * @param deniedRoots - canonical roots this call must not write.
+ * @returns the profile arguments with the in-profile denies applied.
+ */
+export declare function denyProfileArgs(dialect: RunnerDialect, profileArgs: readonly string[], deniedRoots: readonly string[]): string[];
+/**
+ * Restrict an ambient-writable execution to everything EXCEPT `deniedRoots` —
+ * the B9 cell `danger-full-access` + explicit `read-only`. The consumers of
+ * this profile (shell, PTY, PTC) bypass `confine()` entirely under that mode,
+ * so the process fence builds this profile from an upstream skeleton instead:
+ * the caller probes `confine` once under `read-only` to obtain the runner's
+ * argument prefix, and this function rewrites the file-effect part.
+ *
+ * - seatbelt: `(version 1) (allow default)` kept from the profile head, plus a
+ *   trailing `(deny file-write* (subpath …) (literal …))` — allow-default with
+ *   subpath carve-outs, the inverse of the confined profiles. The literals
+ *   pin every ancestor of a denied root, so `rename`ing the tree's parent
+ *   cannot walk it out from under the deny (Seatbelt checks the operated
+ *   path only — verified natively on macOS);
+ * - bwrap: `--ro-bind / /` becomes `--bind / /` (ambient writable namespace),
+ *   each denied root is re-mounted `--ro-bind` after it, and every ancestor
+ *   of a denied root is self-bound `--bind A A` between the root mount and the
+ *   ro-binds — a mountpoint cannot be renamed (EBUSY), so the deny follows no
+ *   rename of the tree's ancestors. A missing source fails the launch,
+ *   retaining the registered negative authorization;
+ * - landlock cannot express "everything except" — its launcher only unions
+ *   allowlists, so it throws. windows-acl expresses the cell through the
+ *   standalone ambient-deny runner instead of this profile rewrite: standing
+ *   deny ACEs on every denied object, plus ancestor pin handles held through
+ *   the child and its drained Job descendants so no rename can vacate the
+ *   registered spelling (`windows-deny.ts`, `windows-path-guard.ts`).
+ * @param dialect - the recognized dialect.
+ * @param profileArgs - the upstream read-only skeleton's profile arguments.
+ * @param deniedRoots - canonical roots the execution must not write.
+ * @returns the restricted profile arguments.
+ */
+export declare function restrictProfileArgs(dialect: RunnerDialect, profileArgs: readonly string[], deniedRoots: readonly string[]): string[];

package/lib/types/fs.d.ts

@@ -65,22 +65,44 @@ export declare class MultiRootFileSystem extends LocalFileSystem {
         version: FsVersion;
     }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsEditOutcome>;
     /**
-     * The writable roots of one workspace-write call: the upstream derivation
-     * (primary root plus the platform temp areas, canonical and deduplicated)
-     * widened by the scope's additional roots, in scope order.
+     * The writable roots of one confined call: the upstream derivation (primary
+     * root plus the platform temp areas, canonical and deduplicated — empty
+     * under `read-only`) widened by the scope's EFFECTIVE writable members.
+     * Under `read-only` that is exactly the fixed `read-write` roots (the tool
+     * cap may already have emptied the scope's list), so an explicit grant
+     * survives a globally read-only session. An unavailable registry authority
+     * never contributes members: a process that cannot read the store grants
+     * only the primary root (and no shared temp grant).
      * @param policy - the per-call policy.
      * @param scope - the scope resolved once for this call; both the fence and
      *   the denial message below share it instead of re-resolving.
-     * @returns the canonical writable roots; empty under `read-only`.
+     * @returns the canonical writable roots; possibly empty.
      */
     private rootsFor;
     /**
-     * Enforce the per-call policy against `target` and return the EXACT target the
-     * mutation must use, so the checked identity is the mutated one (no
-     * check-here-write-there TOCTOU). `read-only` denies; `workspace-write`
-     * re-canonicalizes NOW (reflecting a concurrently swapped symlink ancestor),
-     * requires containment under one of the scope's writable roots, and returns
-     * THAT fresh target; `danger-full-access` returns the caller's target unfenced.
+     * Enforce the per-call policy against `target` and return the EXACT target
+     * the mutation must use, so the checked identity is the mutated one (no
+     * check-here-write-there TOCTOU). Deny precedes containment: a root in
+     * `scope.deniedRoots` — an explicit `read-only` root, or any member when the
+     * call is tool-capped — refuses writes under EVERY mode, including
+     * `danger-full-access` and where a broader grant (the platform temp area)
+     * would otherwise cover the path. `read-only` then grants only the fixed
+     * `read-write` members; `workspace-write` requires containment under the
+     * widened writable set.
+     *
+     * `danger-full-access` is the only mode with a fast path, and only while
+     * the deny set is empty: it then returns the caller's target untouched,
+     * upstream-exact. Once ANY deny boundary exists the caller's `FsTarget` may
+     * be stale — the directory it resolved through can since have been replaced
+     * by a symlink into a denied root — so the fence re-resolves
+     * `target.displayPath`, checks the FRESH target key, and mutates that fresh
+     * target rather than the stale one the caller resolved earlier.
+     *
+     * One more Full-access rule: while the registry authority is `unavailable`
+     * the empty deny set is not trustworthy — the store this process cannot
+     * read may hold explicit `read-only` registrations — so the mode degrades
+     * 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.
      * @returns the fresh canonical target the mutation must use.

package/lib/types/index.d.ts

@@ -25,12 +25,16 @@ export { classifyInstallation, compatEnforcement, CORE_PACKAGES, OPTIONAL_CORE_P
 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 { AGENT_PTY_MARKER, agentPtyMarkerVerdict, assertAgentPtyMarker, PtyMarkerContractError } from './compat/pty-marker.ts';
+export type { AgentPtyMarkerIo, AgentPtyMarkerVerdict } from './compat/pty-marker.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 { MultiRootProviders, brandMultiRootProvider, isMultiRootProvider, MULTI_ROOT_PROVIDER_BRAND } from './providers.ts';
+export type { ProviderKind } from './providers.ts';
 export { MultiRootFileSystem } from './fs.ts';
 export type { Config as FileSystemConfig } from './fs.ts';
 export { MultiRootSandboxProvider } from './sandbox.ts';
@@ -38,14 +42,15 @@ 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, REGISTRY_CONTENDED_MESSAGE, multiRootDomainSpec } from './registry.ts';
+export { DEFAULT_MAX_ADDITIONAL_ROOTS, MAX_ADDITIONAL_ROOTS_CEILING } 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, resolvePanelPrimaryRoot, revealArgv } from './command.ts';
 export type { FoldersCommand } from './command.ts';
-export { PANEL_CHANNEL, PANEL_ENDPOINTS, parsePanelCall, parseRevealedView, parseRootsView, parseFilesView, parseFilePreview } from './contract.ts';
-export type { FilesView, FilePreview, PanelCall, PanelEndpoint, PanelFailure, PanelRequest, PanelResponseMap, RevealedView, RootView, RootsView, } from './contract.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';
 /**
  * Carrier plugin face for the bare-package-name loader row (see the module
  * doc). It deliberately provides nothing: every host responsibility is owned

package/lib/types/process-fence.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `multi-root-process-fence`: the B9 seam for the one cell `ctx.sandbox.confine`
+ * never sees — `danger-full-access` with explicit `read-only` additional roots.
+ *
+ * Upstream, every confined consumer routes through `ctx.sandbox.confine`, which
+ * this bundle's provider already widens (grants, the read-only fixed-write
+ * graft, and the workspace-write deny edge). But the shell executor, the PTC
+ * runtime and the PTY backend all short-circuit that mode: `policy.mode ===
+ * 'danger-full-access'` returns the bare argv, so an explicit `read-only` root
+ * would silently stay writable. This row closes the gap without touching any
+ * upstream executor:
+ *
+ * - `ctx.subprocess.spawn` is wrapped to prepend a precomputed restricted
+ *   profile whenever the AsyncLocalStorage below carries one. `spawn` is
+ *   synchronous, so the profile — which never depends on the callee's argv —
+ *   is built by the wrapping consumer, not here.
+ * - `ctx.shell.execute` (bash and pwsh alike, and `start` where an older
+ *   release still exposes it — `compat/process-entrypoints.ts` owns which
+ *   entries a mounted executor actually carries) resolves the per-call policy
+ *   exactly the way the executor itself does, and — under Full-access with
+ *   deny roots — asks the sandbox provider for the restricted prefix and runs
+ *   the call inside the store, so every subprocess the executor launches is
+ *   confined.
+ * - `ctx.ptcRuntime.run` does the same for `run_code`.
+ * - `ctx.subprocess.spawnTerminal` keys on the `DSH_PTY_SESSION_ID` marker:
+ *   every supported `dsh-terminal-bash` backend stamps it (alongside
+ *   `DSH_SESSION_ID`) when it launches an agent's PTY, and no other caller —
+ *   above all the panel's terminal controller — ever sets it. A spec without
+ *   the marker is a USER terminal, passed through untouched in every mode:
+ *   the sandbox protects agent behavior, and upstream never confines the
+ *   user's own terminal. Because that marker is the ONLY discriminator, the
+ *   `multi-root-compat` gate asserts it at boot (`compat/pty-marker.ts`):
+ *   an installed backend whose emitted code no longer stamps it fails the
+ *   plugin load rather than silently reclassifying agent PTYs as the user's.
+ *   `ctx.terminals` itself is deliberately NOT wrapped:
+ *   upstream mounts it inside `optional-persistent-terminals` with
+ *   `isolate: { terminals: true }`, so the registry entry is unreachable from
+ *   this row — the shared `spawnTerminal` seam plus the env discriminator
+ *   covers both the un-isolated SDK mount and the isolated web mount.
+ *
+ * The same seam carries the unknown-authority downgrade: while the scope
+ * reports `authority: 'unavailable'` — a contended, storage-failed or
+ * config-invalid registry publishes an empty deny set that is NOT evidence —
+ * `danger-full-access` executions run inside a primary-root-only
+ * profile (with the deny set applied) instead of ambient.
+ *
+ * Windows uses the standalone ambient deny-token runner. Landlock cannot subtract a subtree, so that combination selects bubblewrap.
+ * An unusable mount runner fails without starting an unconfined process.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/process-fence
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/types/profile-isolation.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Profile pnpm import isolation — the host-side maintenance behind
+ * `/workspace-folders isolate-profiles` (branch review Phase C2, finding R4).
+ *
+ * Why it exists: a Windows deny ACE applies to the file OBJECT, not to one
+ * hardlink name. The pnpm profile defaults upstream writes (`initProfile` in
+ * dsh-app-boot) never set `packageImportMethod`, so `dsh plugin add` imports
+ * the store into `<home>/profiles/<name>/node_modules` BY HARDLINK. Denying
+ * `$DSH_HOME` then rewrites security descriptors shared with every other name
+ * of the same objects — including the global pnpm store and other projects
+ * linking it. The C1 preflight therefore refuses such a home before any ACL
+ * write; this module is the remediation it points at: it detects the confirmed
+ * profiles, writes `packageImportMethod: copy` conservatively, and scans the
+ * whole home for the multi-link files that still need a reinstall.
+ *
+ * Boundaries of the subset it touches:
+ * - profile identification is conservative — only a directory under
+ *   `profiles/` whose `package.json` parses to an object carrying
+ *   `dsh.profile` as an object counts; everything else is enumerated but
+ *   never written;
+ * - the YAML handling is a strict SUBSET scanner, not a parser substitute —
+ *   the runtime cannot depend on a YAML package, so anything ambiguous is
+ *   reported as a conflict and refused instead of guessed;
+ * - every write is atomic (temp sibling + rename) and never crosses a reparse
+ *   point;
+ * - the whole-home scan never descends a reparse point: with plain `lstat` a
+ *   symlink/junction reports as a link, and other reparse flavours still fall
+ *   under the runner's own Win32-attribute preflight, which remains the
+ *   authoritative gate;
+ * - the command sets configuration — it never deletes `node_modules`, never
+ *   runs pnpm, and never repairs ACLs or ownership written in the past.
+ *
+ * @module profile-isolation
+ */
+/**
+ * Mirrors `PROFILE_PNPM_WORKSPACE` written by `initProfile` in
+ * `@deepseek-ai/dsh-app-boot`; that constant is not exported, so the template
+ * is duplicated here and must stay in sync with upstream.
+ */
+export declare const PROFILE_PNPM_WORKSPACE = "packages:\n  - .\n\nnodeLinker: hoisted\nautoInstallPeers: false\n";
+/** One accepted top-level `key: value` line, located in the source text. */
+export interface WorkspaceYamlEntry {
+    /** The unquoted scalar when the value is one; `undefined` for block/complex. */
+    readonly value: string | undefined;
+    /**
+     * `scalar` — a same-line plain or quoted scalar; `block` — the value is
+     * empty, so a nested block (or an explicit comment) follows; `complex` —
+     * the value opens with a YAML node property or collection marker
+     * (`&`, `*`, `!`, `|`, `>`, `{`, `[`) or is a malformed scalar the subset
+     * refuses to interpret.
+     */
+    readonly kind: 'scalar' | 'block' | 'complex';
+    /** 1-based line number the key sits on. */
+    readonly line: number;
+    /** UTF-16 code-unit offset where the value token begins. */
+    readonly valueStart: number;
+    /** UTF-16 code-unit offset just past the value token (before ` #comment` or EOL). */
+    readonly valueEnd: number;
+}
+/**
+ * Read the top-level `key: value` lines of a `pnpm-workspace.yaml` text.
+ *
+ * This is a strict subset scanner, deliberately NOT a YAML parser: it accepts
+ * only top-level `key:` lines (plain or quoted keys) plus indented nested
+ * content it never interprets, and throws — naming the file and the 1-based
+ * line — on an indented first entry, tabs in indentation, `%` / `---` / `...` directives, duplicate
+ * top-level keys, or any other non-indented content line outside the key
+ * form. A `#` preceded by whitespace ends a plain scalar; quoted scalars are
+ * unquoted for the reported value. `valueStart`/`valueEnd` are the UTF-16
+ * offsets of the value token itself, so a caller can replace exactly the
+ * scalar while comments and line endings survive untouched.
+ *
+ * @param text - the yaml text to scan.
+ * @param path - the file name used in rejection messages.
+ * @returns the top-level entries keyed by their unquoted names.
+ */
+export declare function parseWorkspaceYamlKeys(text: string, path?: string): ReadonlyMap<string, WorkspaceYamlEntry>;
+/** What one confirmed profile's `pnpm-workspace.yaml` says about imports. */
+export interface ProfileYamlReport {
+    /**
+     * `absent` — `packageImportMethod` is not configured (the file may still
+     * exist); `copy` — it is a same-line scalar `copy`; `conflict` — it exists
+     * but is not a plain `copy` scalar, or the yaml exists but is a reparse
+     * point / non-file; `unreadable` — the file cannot be read or the subset
+     * scanner rejected it.
+     */
+    readonly state: 'absent' | 'copy' | 'conflict' | 'unreadable';
+    /** Human-readable reason for `conflict`/`unreadable`. */
+    readonly detail?: string;
+}
+/** One confirmed profile and its yaml verdict. */
+export interface ProfileReport {
+    /** The profile directory name under `profiles/`. */
+    readonly name: string;
+    /** The profile's absolute path under the canonical home. */
+    readonly path: string;
+    /** The `packageImportMethod` verdict for its workspace yaml. */
+    readonly yaml: ProfileYamlReport;
+}
+/** The read-only whole-home scan accompanying every report. */
+export interface HomeScan {
+    /** Directories successfully listed (including the home itself). */
+    readonly directories: number;
+    /** Non-directory entries inspected — plain files and reparse leaves alike. */
+    readonly files: number;
+    /** Plain files carrying more than one name (`st_nlink > 1`). */
+    readonly multiLinkTotal: number;
+    /** Up to {@link SAMPLE_CAP} absolute paths of multi-link files. */
+    readonly multiLinkPaths: readonly string[];
+    /** Entries `lstat`/`readdir` failed on (first {@link SAMPLE_CAP}). */
+    readonly uninspectable: readonly {
+        path: string;
+        reason: string;
+    }[];
+    /** Total uninspectable entries — may exceed the retained paths. */
+    readonly uninspectableTotal: number;
+}
+/** The read-only verdict for one canonical home. */
+export interface IsolateReport {
+    /** The canonical DSH home the report covers. */
+    readonly home: string;
+    /** Confirmed profiles only; non-profile entries are listed separately. */
+    readonly profiles: readonly ProfileReport[];
+    /** `profiles/` entries that are not confirmed profiles — never written. */
+    readonly nonProfileEntries: readonly string[];
+    /** The whole-home link/uninspectable counts. */
+    readonly scan: HomeScan;
+    /** True whenever anything could not be inspected — never a clean result. */
+    readonly incomplete: boolean;
+}
+/** The per-profile outcome of one `--apply` run. */
+export interface ProfileAction {
+    readonly name: string;
+    /**
+     * `written` — the yaml was created or gained the key; `replaced` — a
+     * same-line scalar was swapped in place; `noop` — already `copy`;
+     * `refused` — a conflict/unreadable file the command will not guess at.
+     */
+    readonly action: 'written' | 'replaced' | 'noop' | 'refused';
+    readonly detail?: string;
+}
+/** The report of one `--apply` run: the read verdict plus the actions. */
+export interface ApplyReport extends IsolateReport {
+    readonly actions: readonly ProfileAction[];
+}
+/**
+ * Read-only inspection of a DSH home: confirmed profiles under `profiles/`,
+ * each one's `packageImportMethod` verdict, and a whole-home `lstat` scan
+ * counting directories, files, multi-link files, and uninspectable entries.
+ * Nothing is written. The report is `incomplete` — never clean — whenever any
+ * entry could not be inspected.
+ * @param home - the DSH home to inspect (canonicalized).
+ * @returns the isolation report.
+ */
+export declare function isolateReport(home: string): IsolateReport;
+/**
+ * Write `packageImportMethod: copy` into every fixable confirmed profile.
+ * A missing file receives the upstream profile template plus the copy line;
+ * a missing key is appended; a same-line non-`copy` scalar is replaced by
+ * byte range so comments and CRLF survive; a block/complex/duplicate-key or
+ * unreadable file is refused untouched. Every write lands atomically through
+ * a sibling temp file + rename, and the command never descends or writes
+ * through a reparse point.
+ * @param home - the DSH home to migrate (canonicalized).
+ * @returns the read verdict plus one action per confirmed profile.
+ */
+export declare function applyIsolateConfig(home: string): ApplyReport;
+/**
+ * The remediation steps the user must run by hand — this command writes
+ * configuration only. For every confirmed profile whose dependencies still
+ * need re-installing as copies (config changed under it, or links were seen
+ * inside it), the steps say: quit the hosts using it, remove its
+ * `node_modules` yourself, reinstall from its lockfile. Refused profiles get
+ * a manual-resolution line instead of automated steps.
+ * @param report - the {@link ApplyReport} (or a check report) to explain.
+ * @returns the guidance lines, in English.
+ */
+export declare function remediationSteps(report: IsolateReport): string[];

package/lib/types/providers.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `MultiRootProviders`: the fail-loud guard that proves the services mounted as
+ * `ctx.fs` and `ctx.sandbox` are THIS bundle's providers — the only ones whose
+ * widening the registry, the instruction row, LSP routing and workspace-files
+ * are allowed to attach to.
+ *
+ * Why a brand and not `instanceof`: the plugin may be installed twice (a
+ * duplicated install forks the class identity), and cordis private fields are
+ * not a public contract. A well-known symbol survives both. The brand is
+ * non-enumerable so it never leaks into spreads, JSON, or surface payloads.
+ *
+ * Deterministic outcome under a provider conflict: cordis refuses a second
+ * `ctx.provide` of an already-registered key, so whoever mounts the colliding
+ * provider second loses loudly — but a conflicting plugin can also DISABLE this
+ * bundle's rows (the same mechanism this bundle uses on upstream), leaving a
+ * foreign `ctx.fs`/`ctx.sandbox` in place. In that case this service's
+ * `[Service.init]` logs which service is foreign and throws: the row never
+ * activates, so every row injecting `multiRootProviders` — the registry above
+ * all — never starts, the scope stays empty, and nothing is ever granted,
+ * regardless of patch order. Cordis re-evaluates an injecting fiber when an
+ * injected service is unprovided and re-provided, so a LATE replacement re-runs
+ * the same check.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/providers
+ */
+import { Service } from '@deepseek-ai/cordis';
+/**
+ * The well-known brand key both providers carry. `Symbol.for` makes it
+ * identical across duplicated installs of this package.
+ */
+export declare const MULTI_ROOT_PROVIDER_BRAND: unique symbol;
+/** The two service keys this bundle takes over. */
+export type ProviderKind = 'fs' | 'sandbox';
+/**
+ * Stamp the multi-root provider brand on a service value. Non-enumerable:
+ * the mark must not travel into structural copies.
+ * @param value - the service instance being mounted.
+ * @param kind - which provider key it claims.
+ * @returns the same value, branded.
+ */
+export declare function brandMultiRootProvider<T>(value: T, kind: ProviderKind): T;
+/**
+ * Whether `value` is this bundle's provider of `kind`. Structural on purpose:
+ * no `instanceof`, so a duplicated install still recognizes the brand.
+ * @param value - the service mounted under the key.
+ * @param kind - the provider key being checked.
+ */
+export declare function isMultiRootProvider(value: unknown, kind: ProviderKind): boolean;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        multiRootProviders: MultiRootProviders;
+    }
+}
+/**
+ * The conflict gate: `ctx.multiRootProviders` exists only while `ctx.fs` and
+ * `ctx.sandbox` are this bundle's branded providers. Every row that widens an
+ * authority surface injects it, so a foreign provider composition loses the
+ * whole gated set instead of silently widening an unverified one.
+ */
+export declare class MultiRootProviders extends Service {
+    static provide: string;
+    static inject: string[];
+    /**
+     * Verify the provider identities once per activation. A foreign service is
+     * named in the log and the throw leaves this row — and every dependent —
+     * unstarted: fail loud, never a widened grant.
+     */
+    protected [Service.init](): void;
+}
+export default MultiRootProviders;