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

package/lib/types/client/locales.d.ts

@@ -21,6 +21,7 @@ export declare const zh: {
     'panel.additional': string;
     'panel.empty': string;
     'panel.emptyHint': string;
+    'panel.noSession': string;
     'panel.loading': string;
     'panel.retry': string;
     'panel.close': string;
@@ -54,9 +55,11 @@ export declare const zh: {
     'error.not-found': string;
     'error.invalid-ref': string;
     'error.storage-unavailable': string;
+    'error.registry-contended': string;
     'error.reveal-unavailable': string;
     'error.unavailable': string;
     'error.copy-failed': string;
+    'error.session-not-found': string;
     'error.fallback': string;
 };
 /** The canonical key set. */
@@ -72,6 +75,7 @@ export declare const en: {
     'panel.additional': string;
     'panel.empty': string;
     'panel.emptyHint': string;
+    'panel.noSession': string;
     'panel.loading': string;
     'panel.retry': string;
     'panel.close': string;
@@ -105,9 +109,11 @@ export declare const en: {
     'error.not-found': string;
     'error.invalid-ref': string;
     'error.storage-unavailable': string;
+    'error.registry-contended': string;
     'error.reveal-unavailable': string;
     'error.unavailable': string;
     'error.copy-failed': string;
+    'error.session-not-found': string;
     'error.fallback': string;
 };
 declare module '@deepseek-ai/dsh-client-ui-slots' {

package/lib/types/command.d.ts

@@ -62,5 +62,22 @@ export declare function renderRootsReport(primaryRoot: string, statuses: readonl
  * @param ctx - the host context carrying `commands`, `sandboxPolicy`, and the registry.
  */
 export declare function apply(ctx: Context): void;
+/**
+ * Derive the primary root a panel request may act on.
+ *
+ * The browser names a live session; the host looks that session up and uses
+ * its immutable cwd. There is no client-supplied path and no deployment-default
+ * fallback: a panel call without a real host session has no workspace to
+ * manage. Property access would demand an injected `sessions` dependency this
+ * row does not name, so the lookup stays an explicit sibling `get` (the same
+ * pattern as `directoryPicker` / `subprocess`).
+ *
+ * @param ctx - the host context that may carry `sessions`.
+ * @param sessionId - the id the panel sent; already required by the wire schema.
+ * @returns the canonical cwd of that session.
+ * @throws {RootValidationError} `session-not-found` when the service is absent,
+ *   the id does not name a live session, or that session has no cwd.
+ */
+export declare function resolvePanelPrimaryRoot(ctx: Context, sessionId: string): string;
 /** The per-platform argv that reveals one directory in the OS file manager. */
 export declare function revealArgv(platform: NodeJS.Platform, path: string): readonly string[];

package/lib/types/compat/agent-instructions.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Compatibility adapter for upstream's instruction discovery and rendering.
+ *
+ * `@deepseek-ai/dsh-agent-instructions` renamed its renderer between two
+ * releases this plugin supports, without changing its signature:
+ *
+ * ```text
+ * 0.1.5-rc.2     renderWorkspaceContext(files, options)   RenderedWorkspaceContext
+ * 0.1.6-alpha.1  renderAgentInstructions(files, options)  RenderedAgentInstructions
+ * ```
+ *
+ * `discoverBaselineInstructionFiles` kept both its name and its signature.
+ *
+ * All coupling to that package is concentrated here so the business layer
+ * (`src/instructions.ts`) only ever calls {@link renderInstructions} and
+ * {@link InstructionsApi.discover}. A future rename is one edit in this file,
+ * not a version check sprinkled through the provider.
+ *
+ * The export is picked by NAME rather than by comparing the release string:
+ * a structural probe also copes with upstream keeping both names for a release,
+ * or reshaping within one, which a version comparison does not.
+ *
+ * The package is loaded LAZILY, and its genuine ABSENCE is reported as absence
+ * rather than thrown. It is an optional peer: the default DSH bundle mounts it,
+ * but a minimal composition legitimately has neither it nor an agent, and in
+ * that case this plugin's instruction row must simply contribute nothing. A
+ * package that is present but cannot be evaluated is a different answer, and
+ * one this adapter reports instead of caching as absence.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/compat/agent-instructions
+ */
+import type { InstructionFile, LoadedInstructionFile, TruncatedInstruction } from '@deepseek-ai/dsh-agent-instructions';
+export type { InstructionFile, LoadedInstructionFile, TruncatedInstruction };
+/** Model-facing instruction text plus the byte-budget diagnostics. */
+export interface RenderedInstructions {
+    /** The rendered text, within the requested budget. */
+    readonly text: string;
+    /** Files the budget excluded entirely. */
+    readonly omitted: readonly InstructionFile[];
+    /** Files the budget included only in part. */
+    readonly truncated: readonly TruncatedInstruction[];
+}
+/** The rendering budget, spelled the way both releases spell it. */
+export interface RenderOptions {
+    /** UTF-8 byte cap for the whole rendered batch. */
+    readonly maxBytes: number;
+    /** Whether this batch supersedes a previously visible baseline. */
+    readonly replacePreviousBaseline?: boolean;
+}
+/** Discovery inputs this plugin uses; a subset of upstream's option bag. */
+export interface DiscoverOptions {
+    /** The directory discovery starts from. */
+    readonly cwd: string;
+    /** The root the walk stops at; pinned to the additional root by the caller. */
+    readonly projectRoot?: string;
+    /** Harness home, so the user-global file is discovered from the right place. */
+    readonly dshHome?: string;
+    /** Directory entries that identify a project root. */
+    readonly projectRootMarkers?: readonly string[];
+    /** Ordered same-directory instruction candidates. */
+    readonly instructionFileCandidates?: readonly string[];
+    /** Ordered same-directory local-overlay candidates. */
+    readonly localInstructionFileCandidates?: readonly string[];
+    /** Cancellation for the probes discovery performs. */
+    readonly signal?: AbortSignal;
+}
+/** The upstream surface this plugin depends on, after adaptation. */
+export interface InstructionsApi {
+    /** Discover instruction candidates, in model precedence order. */
+    discover: (options: DiscoverOptions) => Promise<readonly InstructionFile[]>;
+    /** Render loaded files within a byte budget. */
+    render: (files: readonly LoadedInstructionFile[], options: RenderOptions) => RenderedInstructions;
+}
+/**
+ * The shape this adapter probes for. Both renderer names are optional because
+ * exactly one of them exists on any given release.
+ */
+interface UpstreamModule {
+    readonly discoverBaselineInstructionFiles?: (options: DiscoverOptions) => Promise<InstructionFile[]>;
+    readonly renderAgentInstructions?: (files: readonly LoadedInstructionFile[], options: RenderOptions) => RenderedInstructions;
+    readonly renderWorkspaceContext?: (files: readonly LoadedInstructionFile[], options: RenderOptions) => RenderedInstructions;
+}
+/** Raised when the package is present but carries neither renderer name. */
+export declare class DshInstructionApiError extends Error {
+    constructor(message: string);
+}
+/**
+ * Pick the renderer this release exports.
+ * @param module - the loaded upstream module.
+ * @returns the renderer.
+ * @throws {DshInstructionApiError} when neither name is present.
+ */
+export declare function selectRenderer(module: UpstreamModule): NonNullable<UpstreamModule['renderAgentInstructions']>;
+/**
+ * Adapt one loaded upstream module to {@link InstructionsApi}.
+ * @param module - the loaded upstream module.
+ * @returns the adapted surface.
+ * @throws {DshInstructionApiError} when a function this plugin needs is absent.
+ */
+export declare function adaptInstructionsModule(module: UpstreamModule): InstructionsApi;
+/**
+ * Whether one package is installed at all, judged WITHOUT evaluating it.
+ *
+ * This is what separates "the optional peer is absent" from "the optional peer
+ * is installed but its evaluation fails" (a missing transitive dependency, a
+ * broken build). Only a genuine resolvability failure counts as absence: a
+ * resolution that fails for another reason (an `exports` map with no `require`
+ * condition, say) leaves the verdict to the `import()` below, which is the
+ * authority on whether the module can actually be loaded.
+ * @param specifier - the bare package specifier to probe.
+ * @returns whether the package resolves from this module.
+ */
+export declare function isPackageInstalled(specifier: string): boolean;
+/**
+ * Load and adapt the upstream instruction surface, once.
+ *
+ * @returns the adapted surface, or `undefined` when the package is not
+ *   installed. A package that IS installed but exports neither renderer throws
+ *   instead: that is a compatibility break to fix, not an optional seam. So
+ *   does one that is installed but cannot be evaluated at all — a missing
+ *   transitive dependency, a broken build — because reporting that as absence
+ *   would drop every additional root's instructions for the rest of the
+ *   process. See {@link isPackageInstalled} for how the two are told apart.
+ */
+export declare function instructionsApi(): Promise<InstructionsApi | undefined>;
+/**
+ * Render loaded instruction files within a byte budget, through whichever
+ * renderer the installed release exports.
+ *
+ * This is the only rendering entry point the business layer uses.
+ * @param files - loaded files, ordered broadest to most specific.
+ * @param options - the byte budget.
+ * @returns the rendered text and its budget diagnostics.
+ * @throws {DshInstructionApiError} when no usable renderer is installed.
+ */
+export declare function renderInstructions(files: readonly LoadedInstructionFile[], options: RenderOptions): Promise<RenderedInstructions>;
+/** Reset the cached resolution. Tests use it to probe both renderer names. */
+export declare function resetInstructionsApi(): void;

package/lib/types/compat/dsh-version.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The DSH compatibility contract: which upstream releases this plugin is
+ * actually verified against, and how an installation is judged against that
+ * list.
+ *
+ * This module is the ONE place the support matrix is spelled out. It is
+ * deliberately pure — no cordis, no logging, no process exit — so that the
+ * runtime gate (`src/compat.ts`), the static gate (`scripts/check-dsh-compat.mjs`)
+ * and the tests all judge an installation by the same code instead of three
+ * drifting copies of the same list.
+ *
+ * Why a contract exists at all: this plugin replaces `ctx.fs` and `ctx.sandbox`
+ * with subclasses of the upstream providers, and `src/dialects.ts` recognizes
+ * the kernel-sandbox profile by OBSERVING the argv shape `super.confine`
+ * produced (ADR-0003). Both couplings are to pre-stable upstream internals that
+ * carry no semver promise. An npm range like `>=0.1.2-alpha.4 <0.2.0` therefore
+ * promises far more than the code was ever verified against; the allowlist
+ * below promises exactly what CI has run.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/compat/dsh-version
+ */
+/**
+ * The releases this plugin is verified against, as EXACT version strings.
+ *
+ * Not a semver range, on purpose: a range is a prediction about releases that
+ * do not exist yet, and this plugin's coupling to upstream argv shapes makes
+ * that prediction unsafe. Adding an entry is always a human act performed after
+ * the upgrade smoke passed on that exact version — a green CI run on an
+ * unlisted release is evidence, not authorization (ADR-0009).
+ */
+export declare const SUPPORTED_DSH_RELEASES: readonly ["0.1.5-rc.2", "0.1.6-alpha.1"];
+/** One release this plugin claims to support. */
+export type SupportedDshRelease = typeof SUPPORTED_DSH_RELEASES[number];
+/**
+ * Packages whose absence means this plugin cannot function at all: every one of
+ * them is either subclassed, imported for a value, or the owner of a service
+ * key the providers inject.
+ */
+export declare const REQUIRED_CORE_PACKAGES: readonly ["@deepseek-ai/dsh-fs", "@deepseek-ai/dsh-fs-local", "@deepseek-ai/dsh-sandbox", "@deepseek-ai/dsh-sandbox-local", "@deepseek-ai/dsh-sandbox-policy", "@deepseek-ai/dsh-storage-domain"];
+/**
+ * Packages a full composition provides and a minimal one legitimately omits.
+ * Absence is fine; a version that DISAGREES with the required packages is not —
+ * that is the mixed-installation failure this contract exists to catch.
+ */
+export declare const OPTIONAL_CORE_PACKAGES: readonly ["@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-client-connection", "@deepseek-ai/dsh-commands", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-subprocess", "@deepseek-ai/dsh-system-prompt"];
+/** Every package the contract inspects, required first. */
+export declare const CORE_PACKAGES: readonly ["@deepseek-ai/dsh-fs", "@deepseek-ai/dsh-fs-local", "@deepseek-ai/dsh-sandbox", "@deepseek-ai/dsh-sandbox-local", "@deepseek-ai/dsh-sandbox-policy", "@deepseek-ai/dsh-storage-domain", "@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-client-connection", "@deepseek-ai/dsh-commands", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-subprocess", "@deepseek-ai/dsh-system-prompt"];
+/** How this plugin reacts to an installation it does not support. */
+export type CompatEnforcement = 'enforce' | 'warn';
+/** The environment variable that relaxes the gate. */
+export declare const COMPAT_ENFORCEMENT_ENV = "DSH_MULTI_ROOT_COMPAT";
+/** One inspected package and the version actually resolved for it. */
+export interface InspectedPackage {
+    /** The package specifier. */
+    readonly name: string;
+    /** The resolved `version`, or `undefined` when the package is not installed. */
+    readonly version: string | undefined;
+    /** Whether absence alone is a failure. */
+    readonly required: boolean;
+}
+/**
+ * Why an installation was accepted or rejected.
+ *
+ * - `supported` — one release, and it is on the allowlist.
+ * - `incomplete` — a required package could not be resolved.
+ * - `mixed` — the installed core packages do not agree on one release.
+ * - `unsupported` — one release, but not on the allowlist.
+ */
+export type CompatVerdict = 'supported' | 'incomplete' | 'mixed' | 'unsupported';
+/** The judgement passed on one installation. */
+export interface CompatReport {
+    /** The verdict. */
+    readonly verdict: CompatVerdict;
+    /** The single release every inspected package agreed on; absent unless they did. */
+    readonly release: string | undefined;
+    /** Every inspected package, in {@link CORE_PACKAGES} order. */
+    readonly packages: readonly InspectedPackage[];
+    /** Operator-facing explanation, ready to log or print verbatim. */
+    readonly message: string;
+}
+/** Reads the installed version of one package, or `undefined` when absent. */
+export type VersionReader = (packageName: string) => string | undefined;
+/**
+ * Read one package's declared version through Node resolution.
+ *
+ * Resolution runs from THIS module, which is what makes the answer meaningful:
+ * the upstream packages are peer dependencies, so they resolve to the single
+ * copy the host provides — the same copy the providers will subclass at
+ * runtime. A package that cannot be resolved is reported absent rather than
+ * throwing, because "not installed" is a legitimate answer for every optional
+ * package.
+ * @param packageName - the package to inspect.
+ * @returns the declared version, or `undefined` when the package or its
+ *   manifest cannot be resolved.
+ */
+export declare function readInstalledVersion(packageName: string): string | undefined;
+/**
+ * Judge one installation against the contract.
+ *
+ * The three checks run in this order, and the first failure wins, because each
+ * later check would report nonsense about an installation that failed an
+ * earlier one: a missing required package has no version to compare, and a
+ * mixed installation has no single version to look up in the allowlist.
+ * @param readVersion - version reader; defaults to Node resolution. Tests and
+ *   the static checker pass their own.
+ * @returns the report; never throws.
+ */
+export declare function classifyInstallation(readVersion?: VersionReader): CompatReport;
+/**
+ * Read the enforcement mode.
+ *
+ * `warn` exists for exactly one caller: the upgrade smoke, which must run the
+ * whole behavior matrix against a release that is deliberately NOT on the
+ * allowlist yet — that run is how a release earns its place on the list. It is
+ * not a production escape hatch, and the warning says so.
+ * @param env - the environment to read; defaults to this process's.
+ * @returns `warn` only when explicitly requested, `enforce` otherwise.
+ */
+export declare function compatEnforcement(env?: Record<string, string | undefined>): CompatEnforcement;

package/lib/types/compat/llm-message.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Compatibility adapter for the one LLM helper this bundle needs.
+ *
+ * `@deepseek-ai/dsh-llm` is an OPTIONAL peer (see `peerDependenciesMeta`): a
+ * minimal composition legitimately has neither it nor an agent, and the
+ * instruction row then contributes nothing. That makes the load MOMENT part of
+ * the contract — this bundle's business layer is re-exported by the barrel
+ * (`src/index.ts`), which is the module the carrier loader row mounts, so a
+ * static value import of the package would make that row fail to load in a
+ * composition that was never going to build a message at all.
+ *
+ * `createUserMessage` is therefore reached through this module, at the moment a
+ * message actually has to be built. Nothing else in the bundle imports the
+ * package for a value.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/compat/llm-message
+ */
+import type { UserMessage } from '@deepseek-ai/dsh-llm';
+/** One plugin-attributed instruction message to build. */
+export interface InstructionMessageInput {
+    /** The message body. */
+    readonly text: string;
+    /** The plugin credited with the message. */
+    readonly plugin: string;
+}
+/**
+ * Build one `{ kind: 'plugin', form: 'instructions' }` user-role message.
+ * @param input - the body and the plugin attribution.
+ * @returns the frozen message upstream's helper produced.
+ * @throws {Error} when the optional peer is absent: a step that has instruction
+ *   text to deliver cannot be served without it, and staying silent would drop
+ *   user-visible context instead of reporting a misconfigured composition.
+ */
+export declare function createInstructionMessage(input: InstructionMessageInput): Promise<UserMessage>;

package/lib/types/compat/sandbox-confine.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Compatibility adapter for the one upstream signature that changed shape
+ * between two releases this plugin supports.
+ *
+ * ```text
+ * 0.1.5-rc.2     confine(argv, policy): ConfinedArgv
+ * 0.1.6-alpha.1  confine(argv, policy, signal?): Promise<ConfinedArgv>
+ * ```
+ *
+ * The widening itself (`src/dialects.ts`) is pure string work on the argv the
+ * upstream provider produced, so nothing about it needs to be async. The only
+ * problem is the SHAPE of the call: an override must accept what the installed
+ * base class declares and return what its caller expects. This module is where
+ * that is solved, once:
+ *
+ * - the return type is expressed as {@link UpstreamConfined}, derived from the
+ *   installed base class, so it resolves to `ConfinedArgv` on one release and
+ *   `Promise<ConfinedArgv>` on the other without two hand-written signatures;
+ * - {@link widenConfined} preserves the shape it was handed — a synchronous
+ *   base result stays synchronous, a promise stays a promise. It never wraps a
+ *   sync result in a promise, because on `0.1.5-rc.2` that would change
+ *   `ctx.sandbox.confine()` from a value into a thenable for every caller in
+ *   the composition, including the bash executor and the PTY backend.
+ *
+ * The single unavoidable cast lives here too, and nowhere else: `super.confine`
+ * has a different arity per release, so calling it uniformly needs one
+ * assertion to {@link ConfineCall}.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/compat/sandbox-confine
+ */
+import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox';
+import type { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local';
+/**
+ * Whatever the INSTALLED upstream provider's `confine` returns. Resolves to
+ * `ConfinedArgv` on a release with a synchronous `confine`, and to
+ * `Promise<ConfinedArgv>` on a release with an asynchronous one.
+ */
+export type UpstreamConfined = ReturnType<LocalSandboxProvider['confine']>;
+/**
+ * A call into the upstream `confine`, tolerant of both arities. The trailing
+ * `signal` is ignored by a release that does not declare it, which is safe:
+ * extra arguments to a JavaScript function are discarded, and a release without
+ * cancellation support simply never observes it.
+ */
+export type ConfineCall = (argv: readonly string[], policy: SandboxPolicy, signal?: AbortSignal) => ConfinedArgv | Promise<ConfinedArgv>;
+/**
+ * Call the upstream `confine` and widen its result, preserving sync/async shape.
+ *
+ * @param base - the upstream `confine`, already bound to its provider.
+ * @param widen - the pure transformation to apply to the upstream result. It
+ *   runs exactly once per call, on whichever release; it may throw, and the
+ *   throw surfaces synchronously or as a rejection to match the base shape.
+ * @param argv - the caller's argv, forwarded verbatim.
+ * @param policy - the per-call policy, forwarded verbatim.
+ * @param signal - forwarded when the installed release accepts it.
+ * @returns the widened result, in the shape the installed release uses.
+ */
+export declare function widenConfined(base: ConfineCall, widen: (confined: ConfinedArgv) => ConfinedArgv, argv: readonly string[], policy: SandboxPolicy, signal?: AbortSignal): UpstreamConfined;

package/lib/types/compat.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `multi-root-compat`: the startup gate that turns the DSH compatibility
+ * contract from documentation into a precondition.
+ *
+ * The four security-relevant rows of this bundle — `multi-root-fs`,
+ * `multi-root-sandbox`, `multi-root-registry`, `multi-root-instructions` —
+ * inject `multiRootCompat`. Cordis will not start a plugin whose injected
+ * service is absent, so this row is what decides whether they run at all:
+ *
+ * ```text
+ * compat check passes  →  ctx.multiRootCompat exists  →  the providers start
+ * compat check fails   →  the row throws             →  they never start
+ * ```
+ *
+ * That is why the gate is a plain `apply` and not a `Service` subclass mounted
+ * directly: the check has to be able to fail BEFORE the service exists. A
+ * `Service` constructor has already run `super(ctx, name)` — and therefore
+ * already claimed the service key — by the time it could inspect anything.
+ *
+ * The verdict itself, and the allowlist it is judged against, live in
+ * `./compat/dsh-version.ts`. This module owns only the reaction to it.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/compat
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { type CompatEnforcement, type CompatReport } from './compat/dsh-version.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        multiRootCompat: MultiRootCompatService;
+    }
+}
+/**
+ * Raised when the installed DSH release is not one this plugin is verified
+ * against. It is thrown from `apply`, so it surfaces as a plugin load failure
+ * with the full diagnosis attached — never as a silently degraded sandbox.
+ */
+export declare class DshCompatUnsupportedError extends Error {
+    /** The report that produced the refusal. */
+    readonly report: CompatReport;
+    constructor(report: CompatReport);
+}
+/**
+ * The `ctx.multiRootCompat` service: the resolved compatibility verdict, held
+ * where the gated providers can read it.
+ *
+ * It intentionally exposes no per-version capability flags. The adapters under
+ * `./compat/` detect the shape they need STRUCTURALLY — whether a return value
+ * is a thenable, which export name a module carries — because a structural
+ * probe also survives upstream reshaping something within one release, while a
+ * version comparison does not. The release string here is for the gate and for
+ * diagnostics.
+ */
+export declare class MultiRootCompatService extends Service {
+    /** The verdict this composition started under. */
+    readonly report: CompatReport;
+    constructor(ctx: Context, report: CompatReport);
+    /** The single DSH release every inspected core package agreed on. */
+    get release(): string | undefined;
+    /** Whether the installation is on the allowlist. */
+    get supported(): boolean;
+}
+/** This row needs nothing: it is the thing everything else waits for. */
+export declare const inject: string[];
+/**
+ * Apply the gate policy to one report.
+ *
+ * Under `DSH_MULTI_ROOT_COMPAT=warn` exactly one verdict is relaxed: an
+ * `unsupported` release that every inspected package agrees on. That is the
+ * only shape the upgrade smoke probes — a coherent tree on a release the
+ * allowlist does not name yet, which is how a release earns its place there.
+ * `mixed` and `incomplete` describe an installation the contract cannot judge
+ * at all, so they are refused in either mode; production deployments leave the
+ * variable unset and get the refusal for everything.
+ * @param report - the verdict to act on.
+ * @param enforcement - how to react to a non-`supported` verdict.
+ * @returns the warning to log, or `undefined` when there is nothing to say.
+ * @throws {DshCompatUnsupportedError} when refusing to run.
+ */
+export declare function assertSupportedInstallation(report: CompatReport, enforcement: CompatEnforcement): string | undefined;
+/**
+ * Judge the installation, then either refuse to provide the service or provide
+ * it.
+ * @param ctx - the row's context.
+ */
+export declare function apply(ctx: Context): void;

package/lib/types/contract.d.ts

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

package/lib/types/index.d.ts

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