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

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

@@ -8,7 +8,8 @@
  * 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
+ * POSIX widening lives in `./dialects.ts`, Windows capabilities in
+ * `./windows-profile.ts` and `./windows-runner.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
@@ -26,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';
@@ -38,8 +40,7 @@ export type { Config };
  */
 export declare class MultiRootSandboxProvider extends LocalSandboxProvider {
     static inject: string[];
-    /** Whether the Windows ACL limitation has already been reported (once per provider). */
-    private warnedAboutWindowsAcl;
+    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.
@@ -61,25 +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;
     /**
-     * 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.
+     * 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.
      */
-    private warnAboutWindowsAcl;
+    clampedExecution(policy: SandboxExecutionPolicy, deniedRoots: readonly string[], signal?: AbortSignal): UpstreamConfined;
 }
 export default MultiRootSandboxProvider;

package/lib/types/scope.d.ts

@@ -16,7 +16,8 @@
  * @module @dsh-electron/dsh-plugin-multi-root-workspace/scope
  */
 import { Context, Service } from '@deepseek-ai/cordis';
-import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox';
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox';
+import type { RootAccess } from './roots.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         multiRootScope: MultiRootScopeService;
@@ -37,19 +38,82 @@ export interface AdditionalWorkspaceRoot {
      * ever registered.
      */
     recordedPath: string;
+    /**
+     * The write authority the registration carries (B9 three-state).
+     * `read-only` roots remain workspace members — instructions, LSP,
+     * workspace-file routing, and reads all still see them — but they are never
+     * part of `writableRoots` and never reach a write grant, under ANY mode.
+     * `inherit` follows the session mode; fixed `read-write` stays writable even
+     * under a read-only session.
+     */
+    access: RootAccess;
+    /** Registry withheld the positive grant; retain its recorded deny boundary. */
+    withheld?: boolean;
     /** Optional display alias. */
     alias?: string;
 }
+/** One granted workspace member, with the authority fact the enforcement reads. */
+export interface ScopeRoot {
+    /** Canonical absolute directory. */
+    readonly path: string;
+    /** The write authority the registration carries. */
+    readonly access: RootAccess;
+    /** Optional display alias. */
+    readonly alias?: string;
+    /** Stable registry identity. */
+    readonly id: string;
+}
 /**
  * The resolved scope of one confined call. `primaryRoot` equals the policy's
- * workspace root; `additionalRoots` are canonical, deduplicated, never equal to
- * the primary root, and empty in M1.
+ * workspace root; `additionalRoots` are canonical, deduplicated, never equal
+ * to the primary root.
  */
 export interface FilesystemScope {
     /** The session's workspace root (`session.header.cwd`, canonical). */
     primaryRoot: string;
-    /** Extra writable roots granted inside the same sandbox mechanism. */
+    /** Every granted member — ANY access level — canonical, in registry order. */
     additionalRoots: readonly string[];
+    /** The granted members with their access, in registry order. */
+    roots: readonly ScopeRoot[];
+    /**
+     * The members a write may reach under THIS call — the effective access
+     * (registration policy × session mode) narrowed by the tool cap.
+     */
+    writableRoots: readonly string[];
+    /**
+     * Registered boundaries THIS call must not write, including missing and
+     * redirected registrations. Negative restrictions never create a grant.
+     * It is the deny set enforcement reads: explicit
+     * `read-only` roots under `danger-full-access` (and wherever another grant,
+     * such as the platform temp area, would otherwise cover the same path), and
+     * every member when the call is tool-capped. Read access is unaffected —
+     * these are all still workspace members.
+     */
+    deniedRoots: readonly string[];
+    /**
+     * Whether this process holds the registry authority for the store. While it
+     * is `unavailable` — contended, storage-failed, config-invalid, or torn
+     * down — the empty root table is NOT evidence that nothing is restricted:
+     * the registrations this process cannot see may carry explicit `read-only`
+     * boundaries, so both writable modes limit writes to the primary root
+     * instead of trusting the empty deny set.
+     * A composition with no registry at all never reports `unavailable` — it can
+     * never have registered roots.
+     */
+    authority: 'available' | 'unavailable';
+    /**
+     * The canonical DSH home directory, present exactly when this scope appended
+     * it to `deniedRoots` — i.e. under `danger-full-access` while restrictions
+     * apply (a non-empty deny set or an unavailable authority). `$DSH_HOME`
+     * holds the store, the lease, the profiles and the user's own config: an
+     * ambient Full-access process must not edit them, so once the workspace
+     * carries ANY deny boundary the home joins it. Zero additional roots with a
+     * healthy authority never set this — the empty scope stays upstream-exact.
+     * Never set under `workspace-write` or `read-only`: those modes already
+     * confine writes by containment, so denying home adds nothing but the cost
+     * of a stale `FsTarget` re-resolution on every write.
+     */
+    protectedHome?: string;
 }
 /**
  * Canonicalize and sanitize one root list against a primary root: drop the
@@ -76,15 +140,65 @@ export declare function sanitizeAdditionalRoots(primaryRoot: string, roots: read
  */
 export declare const MULTI_ROOT_CONTEXT_NAME = "multi-root:scope";
 /**
- * Render the workspace topology the model is told about. Only roots are listed
- * (never files), and the sentence states the two facts a denied write would
- * otherwise have to teach: that the additional roots are part of the SAME
- * workspace, and that the session cwd is unchanged (requirement §5, §8).
- * @param primaryRoot - the canonical session workspace root.
- * @param additionalRoots - canonical additional roots, in scope order.
- * @returns the stable topology sentence.
+ * The deterministic sentence the model hears while the registry authority is
+ * unavailable under either writable mode — enforcement is then the
+ * primary-root-only one, which the prompt must not leave implicit.
+ */
+export declare const REGISTRY_UNAVAILABLE_NOTE: string;
+/**
+ * Render the workspace topology the model is told about. Pure: the text
+ * depends only on its inputs, so two consecutive assemblies of the same
+ * session state produce the same contribution byte for byte. Only granted
+ * members are ever listed — withheld, missing, or invalid roots never reach
+ * `roots` in the first place — and no host internals (ids, SIDs, store or
+ * lease paths) are ever named.
+ * @param options.platform - the host platform (`process.platform` of the contribution).
+ * @param options.mode - the session's sandbox mode.
+ * @param options.primaryRoot - the canonical session workspace root.
+ * @param options.roots - the granted additional members, in registry order.
+ * @param options.cappedTools - sorted tool names that can never write an additional root.
+ * @param options.toolAccessInvalid - invalid host config caps every additional-root write.
+ * @param options.authority - the registry-authority fact; `unavailable` under
+ *   `danger-full-access` and `workspace-write` limit writes to the primary root, which the
+ *   model must hear even when there is no topology to describe.
+ * @param options.protectedHome - the canonical DSH home when the scope appended
+ *   it to the deny set (`danger-full-access` with restrictions); stated by path
+ *   so the model can place the refusal.
+ * @returns the stable topology text; empty when there are no additional roots
+ *   and no downgrade to report.
  */
-export declare function renderWorkspaceRootsContext(primaryRoot: string, additionalRoots: readonly string[]): string;
+export declare function renderWorkspaceRootsContext(options: {
+    readonly platform: string;
+    readonly mode: SandboxMode;
+    readonly primaryRoot: string;
+    readonly roots: readonly ScopeRoot[];
+    readonly cappedTools: readonly string[];
+    readonly toolAccessInvalid?: boolean;
+    readonly authority?: 'available' | 'unavailable';
+    readonly protectedHome?: string;
+}): string;
+/**
+ * Plugin configuration for the `multi-root-scope` row.
+ */
+export interface Config {
+    /**
+     * Per-tool write caps: a listed tool may never write ANY additional root
+     * (the primary root and upstream behaviour are unchanged). `read-only` is
+     * the only legal value — a cap restricts, it can never widen past the
+     * root's own access.
+     */
+    readonly toolAccess?: Record<string, 'read-only'>;
+    /**
+     * The resolved DSH home directory (`$DSH_HOME` / `~/.dsh`), which the patch
+     * row fills from `dshHomePath()`. Under `danger-full-access` it joins the
+     * deny set exactly while restrictions apply — a non-empty derived deny set
+     * or an unavailable registry authority — so an ambient agent process cannot
+     * overwrite the store, the lease file, profiles, or the user's own config.
+     * Absent or invalid (non-string, empty, relative) means the boundary simply
+     * does not exist: bare test compositions carry no home.
+     */
+    readonly dshHome?: string;
+}
 /**
  * The `ctx.multiRootScope` service. Providers ask it — never the filesystem —
  * what the current scope is, which is what keeps the fs fence and every kernel
@@ -93,7 +207,38 @@ export declare function renderWorkspaceRootsContext(primaryRoot: string, additio
 export declare class MultiRootScopeService extends Service {
     /** Additional roots keyed by canonical primary root; empty until roots are registered. */
     private readonly rootsByPrimary;
-    constructor(ctx: Context);
+    private readonly listeners;
+    /**
+     * The registry-authority fact the registry row publishes. Defaults to
+     * `available`: a composition without a registry row can never have
+     * registered roots, so nothing is unknown there. The registry sets it false
+     * the moment it cannot prove the store is its own — before the lease is
+     * acquired, while contended or storage-failed, and at teardown — and true
+     * only after the accepted records have been published.
+     */
+    private registryAuthority;
+    /** Validated `toolAccess` row config; empty when no tool is capped. */
+    private readonly caps;
+    /** A malformed `toolAccess` refuses every additional-root write (fail closed). */
+    private readonly capsInvalid;
+    /**
+     * The configured DSH home boundary; `undefined` when the row carries no
+     * `dshHome` (bare test compositions) or one that is not an absolute string —
+     * an invalid value is logged at construction and ignored rather than
+     * treated as evidence.
+     */
+    private readonly dshHome;
+    /** Observe registry publications; consumers still resolve authority from scopeOf(). */
+    subscribe(listener: () => void): () => void;
+    /**
+     * The sorted names of the tools `toolAccess` caps — read-only for the
+     * prompt contribution. An invalid config is not enumerated (it caps every
+     * call but is not a listable tool set).
+     */
+    toolCaps(): readonly string[];
+    /** Whether malformed toolAccess caps every call, including unknown tools. */
+    get toolAccessInvalid(): boolean;
+    constructor(ctx: Context, config?: Config);
     /**
      * Resolve the scope of one confined call.
      * @param policy - the upstream policy whose workspace root is the primary root.
@@ -101,11 +246,45 @@ export declare class MultiRootScopeService extends Service {
      */
     resolve(policy: SandboxExecutionPolicy): FilesystemScope;
     /**
-     * The additional roots registered for one canonical primary root.
+     * Whether THIS call's additional-root writes are capped. Inside a tool
+     * dispatch the AsyncLocalStorage store answers; outside any dispatch (user
+     * PTY, panel, an unknown async boundary) the answer is fail-closed: capped
+     * whenever `toolAccess` names any tool, because an operation whose tool
+     * identity is unknown gets the most restrictive configured cap. Membership
+     * is never affected — only writability.
+     */
+    private capped;
+    /**
+     * The additional roots registered for one canonical primary root — every
+     * granted member, ANY access level (a read-only root is still a member of
+     * the workspace for instructions, LSP, routing, and reads).
      * @param primaryRoot - canonical primary root (or any spelling thereof).
      * @returns the canonical additional roots; empty when none are registered.
      */
     scopeOf(primaryRoot: string): readonly string[];
+    /**
+     * The additional roots a WRITE may reach for one primary root under
+     * `workspace-write` — the members whose effective access is writable there
+     * (`inherit` and fixed `read-write`). Tool caps are per-call and do not
+     * apply to this diagnostic projection.
+     * @param primaryRoot - canonical primary root (or any spelling thereof).
+     * @returns the canonical writable roots; empty when none qualify.
+     */
+    writableOf(primaryRoot: string): readonly string[];
+    /**
+     * Whether ANY registered primary currently publishes an explicit `read-only`
+     * member. The PTY seam resolves its caller through the agent-PTY
+     * environment markers; when that lookup fails this flag is the difference
+     * between pass-through (nothing to deny anywhere on the store) and fail
+     * closed. An unavailable registry authority answers `true` by itself: a
+     * terminal whose session cannot be resolved must not inherit a deny set
+     * this process cannot see.
+     * @returns whether at least one primary holds a restricted root, or the
+     *   registry cannot prove none does.
+     */
+    hasActiveDenyRoots(): boolean;
+    /** The sanitized members of one primary root, in registry order. */
+    private membersOf;
     /**
      * Replace the roots registered for one primary root.
      *
@@ -116,5 +295,15 @@ export declare class MultiRootScopeService extends Service {
      * @param roots - the additional roots, in display order.
      */
     setAdditionalRoots(primaryRoot: string, roots: readonly AdditionalWorkspaceRoot[]): void;
+    /**
+     * Publish the registry-authority fact. This is the REGISTRY's write port —
+     * the counterpart of {@link setAdditionalRoots}: the registry marks the
+     * scope `unavailable` the moment it stops being the store's authority
+     * (before acquisition, on contention or storage failure, at teardown) and
+     * `available` only once its stored records have been published. Nothing
+     * else may call it, and it never touches the root table.
+     * @param available - whether this process holds the registry authority.
+     */
+    setRegistryAuthority(available: boolean): void;
 }
 export default MultiRootScopeService;

package/lib/types/windows-broker.d.ts

@@ -0,0 +1,17 @@
+export declare function brokerPipeName(userSid: string): string;
+/** The broker must acknowledge before any ACL edits or process creation. The
+ * caller independently reads the deny-only groups from the token;
+ * even an impersonated pipe server cannot fabricate that kernel state.
+ */
+export declare function requestDenyToken(userSid: string, tokenHandle: bigint, deniedIds: readonly string[]): Promise<bigint>;
+/** Synchronous, bounded RPC inside the public suspended-create binding. The
+ * caller verifies the child's kernel token before the helper can resume it.
+ */
+export declare function assignDenyToken(userSid: string, processHandle: bigint, threadHandle: bigint, deniedIds: readonly string[], io: {
+    open(pipe: string): unknown;
+    write(pipe: unknown, bytes: Buffer): void;
+    available(pipe: unknown): number;
+    read(pipe: unknown, count: number): Buffer;
+    pause(): void;
+    close(pipe: unknown): void;
+}): void;

package/lib/types/windows-deny.d.ts

@@ -0,0 +1 @@
+export declare function runWindowsDenied(upstreamRunner: string, roots: readonly string[], argv: readonly string[], protectedHome?: string): Promise<number>;

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

@@ -0,0 +1,10 @@
+export { parseWindowsProfile, workspaceScopeSid, type WindowsProfile } from './windows-runner-contract.ts';
+/** Recognize the upstream runner, then select our ambient deny-token path.
+ *
+ * `protectedHome` is a diagnostics label only: when it names one of the deny
+ * roots it is forwarded as `--protected-home` so the runner can word its
+ * hardlink/scan remediation for the protected `$DSH_HOME`. It never changes
+ * which roots are denied or how.
+ */
+export declare function restrictWindowsProfile(profile: readonly string[], deniedRoots: readonly string[], protectedHome?: string): string[];
+export declare function widenWindowsProfile(profile: readonly string[], roots: readonly string[], deniedRoots: readonly string[], primaryRoot?: string): string[];