dsh-plugin-wsl-env 0.8.0 → 0.9.0

package/docs/UPSTREAM-TERMINAL-TITLE.md

@@ -2,17 +2,24 @@
 
 Status: proposed upstream as
 [deepseek-ai/deepseek-harness#8769](https://github.com/deepseek-ai/deepseek-harness/discussions/8769)
-(targeting `packages/api/terminal-controller`, version line `0.2.0-rc.x`). This
-is the record of a gap this plugin worked around, could not work around, and
-now documents: the GUI terminal titles every tab from the composition's single
-shell profile, so a per-session shell choice is invisible in the title.
+(targeting `packages/api/terminal-controller`, version line `0.2.0-rc.x`). The
+plugin worked around the execution half of this gap — a Windows-folder
+session's terminal runs a host shell (`subprocess-wsl.hostSessions`) — and
+could not work around the title half. This is the record: the GUI titles every
+tab from the composition's single shell profile, so a per-session shell choice
+is invisible in the title.
 
 ## The gap
 
-`TerminalController.spawn` fixes a terminal's display title from the resolved
-shell profile before the provider is ever consulted:
+The display title is fixed from the resolved shell profile and never revisited.
+The private `TerminalController.spawn` builds `info`, with `title: shell.name`,
+only after `await subprocess.spawnTerminal(...)` has returned, and it does not
+read back what that call started:
 
 ```ts
+const handle = await subprocess.spawnTerminal({
+  argv: [shell.path, ...shell.args], cwd: environment.cwd, cols: request.cols, ...
+})
 const info: WebTerminalInfo = {
   id: request.id, shell, title: shell.name, cwd: environment.cwd, ...
 }
@@ -48,10 +55,15 @@ Three escape hatches were evaluated against `0.2.0-rc.2` and each is closed:
    inserts `terminal-controller`, and the client model that the
    `dsh-client-ui-sidebar-terminal` entry waits for mounts with
    `inject = ['remote', 'remote.terminal']` — the `terminal` namespace the host
-   controller registers in its constructor. Disabling the row fails web boot:
-   `1 entry did not activate: @deepseek-ai/dsh-client-ui-sidebar-terminal:
-   pending (waiting for service: webTerminals)`. Verified live against
-   `dsh-desktop 0.2.0-rc.2`.
+   controller registers in its constructor. Disabling the row fails web boot
+   with this two-line error:
+
+   ```text
+   web boot: 1 entry did not activate
+   @deepseek-ai/dsh-client-ui-sidebar-terminal: pending (waiting for service: webTerminals)
+   ```
+
+   Verified live against `dsh-desktop 0.2.0-rc.2` (Electron 44.0.0).
 3. **Per-session config.** The `shell` profile is composition state; `!!js`
    expressions evaluate once at config resolution and reach no Session
    identity.
@@ -62,7 +74,7 @@ Any one of these closes the gap; the first is the smallest and keeps the
 profile name as the fallback:
 
 - `SubprocessTerminalSpawnSpec` gains an optional `displayTitle` (or the handle
-  exposes the launched `argv`), and `create()` uses it for `info.title` when
+  exposes the launched `argv`), and `spawn()` uses it for `info.title` when
   present — falling back to `shell.name`. A provider that rewrites a launch
   states the program it started; every other launch keeps the profile name.
 - Alternatively, the controller derives the title from the effective program
@@ -71,11 +83,34 @@ profile name as the fallback:
 
 With either, this plugin deletes the limitation paragraph in
 [LIMITATIONS.md](LIMITATIONS.md) and the `WSL`-over-PowerShell title, for any
-provider that rewrites launches — not just WSL.
+provider that rewrites launches — not just WSL. The same limitation is stated
+as current fact in four places. Three go stale the day the proposal lands; the
+fourth is already out of step and needs the corrections above whenever it is
+next touched:
+
+- the GUI-terminal comment block in [`cordis.patch.yml`](../cordis.patch.yml);
+- the closing paragraph of "Why the terminal provider is app-level" in
+  [ARCHITECTURE.md](ARCHITECTURE.md);
+- R4's `残差` (residual) column in [REQUIREMENTS.zh.md](REQUIREMENTS.zh.md);
+- the `WSL` tab-title bullet under "Terminals" in
+  [LIMITATIONS.md](LIMITATIONS.md) — the paragraph named just above. It says
+  the controller titles a tab *before* the provider rewrites the launch, the
+  reverse of the ordering corrected at the top of this file, and it carries the
+  one-line `shellCandidates` workaround that drops the row's `shell` block.
 
 ## Workarounds until then
 
 - Double-click a tab's title to rename it (a shipped client feature; the
   controller's `rename` Remote API accepts 1–120 characters).
-- Add `shellCandidates` to the `terminal-controller` row in a user layer: a
-  manually selected shell is titled after itself.
+- Re-declare the `terminal-controller` row in a user layer with a non-empty
+  `shellCandidates`: a manually selected shell is titled after itself. A patch
+  config replaces the whole config rather than deep-merging it
+  (`packages/boot/app-boot/src/config-schema/document.ts`), so the override has
+  to carry this plugin's `shell` block verbatim — `path: wsl.exe`, `name: WSL`,
+  `args: []` — or the terminal stops being a distro terminal. Expect the menu
+  to grow the host shells discovery finds on the root provider, which receives
+  no directory: executables this terminal never starts (the second bullet of
+  the GUI-terminal comment in [`cordis.patch.yml`](../cordis.patch.yml)).
+  [LIMITATIONS.md](LIMITATIONS.md) still carries the older one-line form of
+  this tip, which drops the `shell` block; the version above is the one that
+  works.

package/lib/index.js

@@ -47,6 +47,7 @@ import { canonicalPath, classifyRunnerFailure, isRunnerSpawnFailure, matchesSign
 import { isAnotherDistrosUnc, isRelativeWorldPath, isWorldPathUnder, isWslUnc, posixToUnc, toLinuxPath, toWorldPath, uncToPosix, windowsToLinuxMount } from "./paths.js";
 import { isConfinedMutation, mutationModeRefusal, outsideDistroRefusal, shareSubstrateRefusal, substrateFailure, workspaceWriteDenial } from "./fs-decisions.js";
 import { WslSandbox } from "./sandbox.js";
+import { bwrapFailure, missingBwrapRemedy, withBwrapHint } from "./sandbox-core.js";
 import { armDistroWatcher } from "./watcher.js";
 import { AgentUnavailableError } from "./agent-errors.js";
 import { agentExecutionHandle } from "./agent-exec.js";
@@ -649,7 +650,10 @@ export class WslShellExecutor extends LocalBashExecutor {
             const { enforcement, denialSignatures, runnerFailureRules, windowsDrive } = confined;
             const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
             if (runnerFailure !== undefined) {
-                throw new SandboxUnavailableError(mode, runnerFailure.detail);
+                // This path computes `mode` as `policy?.mode`, which the seam spells as
+                // the wider union: a runner failure is only ever thrown under a
+                // confinement, and there the mode is one of the two confined ones.
+                throw new SandboxUnavailableError(mode, withBwrapHint(runnerFailure.detail, distro));
             }
             return ({
                 ...result,
@@ -732,7 +736,7 @@ export class WslShellExecutor extends LocalBashExecutor {
             // Runner failure outranks denial because the command did not run at all.
             const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
             if (runnerFailure !== undefined)
-                throw new SandboxUnavailableError(mode, runnerFailure.detail);
+                throw new SandboxUnavailableError(mode, withBwrapHint(runnerFailure.detail, distro));
             return ({
                 ...result,
                 sandbox: {
@@ -747,7 +751,7 @@ export class WslShellExecutor extends LocalBashExecutor {
             if (resolved.signal?.aborted === true)
                 resolved.signal.throwIfAborted();
             if (confined !== undefined && isRunnerSpawnFailure(error, confined.argv[0], resolved.workdir)) {
-                throw new SandboxUnavailableError(mode, String(error));
+                throw new SandboxUnavailableError(mode, withBwrapHint(String(error), distro));
             }
             throw error;
         });
@@ -903,9 +907,10 @@ export class WslFileSystem extends LocalFileSystem {
         const confinedPolicy = policy;
         const distro = await this.distro();
         if (!(await this.sandbox.usable(distro))) {
-            throw new SandboxUnavailableError(confinedPolicy.mode, `bwrap is not usable inside distro "${distro}". Install it with ` +
-                `"scripts/bootstrap.sh ${distro} --install" (from the package), or directly: ` +
-                `wsl.exe -d ${distro} -u root -- apt-get install -y bubblewrap`);
+            // The probe's classified remedy — missing vs present-but-broken, with the
+            // distro's own package family — is what every other refusal surfaces;
+            // this path has the same failure, so it carries the same text.
+            throw new SandboxUnavailableError(confinedPolicy.mode, bwrapFailure(config.wslPath, distro) ?? missingBwrapRemedy(distro));
         }
         return confinedAgent({ distro, wslPath: config.wslPath, policy: confinedPolicy, maskWindowsDrive: config.maskWindowsDrive });
     }

package/lib/preflight.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Session-start sandbox preflight: surface a missing or broken `bwrap` when a
+ * distro session OPENS, not when its first command fails closed.
+ *
+ * Without this the discovery moment is the model's first command, whose
+ * `SANDBOX_UNAVAILABLE` error scrolls past as one tool failure among many; the
+ * operator may not read it until several commands have failed the same way.
+ * The probe itself is not new — it is the providers' own usability probe, run
+ * through the same shared cache (`lib/sandbox-core.js`), so a session-start
+ * check costs a real probe only once per process, and the first confined
+ * command after it pays nothing. Nothing else changes: the failure semantics
+ * stay exactly as fail-closed as before, this service only MOVES THE NEWS.
+ *
+ * Advisory by construction. A preflight that cannot run (no WSL, a wedged
+ * `wsl.exe`) degrades to a log line; it must never fail a session that has not
+ * even asked for confinement yet. It also never installs anything: the remedy
+ * it prints is the same one the refusals carry, and running an installer under
+ * root uninvited would be a posture this plugin explicitly rejects.
+ *
+ * This is a TypeScript source built to `lib/preflight.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/preflight
+ */
+import z from "@deepseek-ai/schemastery";
+import type { Context } from "@deepseek-ai/cordis";
+export declare const name = "wsl-preflight";
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    /** Distro to preflight; empty means this machine's default distro. */
+    distro: z<string, string, "defined">;
+    /** The `wsl.exe` path the probe spawns; keep in step with the providers' `wslPath`. */
+    wslPath: z<string, string, "defined">;
+    /** Whether the session-start sandbox preflight runs at all. */
+    sandbox: z<boolean, boolean, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    /** Distro to preflight; empty means this machine's default distro. */
+    distro: z<string, string, "defined">;
+    /** The `wsl.exe` path the probe spawns; keep in step with the providers' `wslPath`. */
+    wslPath: z<string, string, "defined">;
+    /** Whether the session-start sandbox preflight runs at all. */
+    sandbox: z<boolean, boolean, "defined">;
+}>>, "plain">;
+/** The config schema's validated output. */
+export interface PreflightConfig {
+    /** Distro to preflight; empty means this machine's default distro. */
+    distro?: string;
+    /** The `wsl.exe` path the probe spawns. */
+    wslPath?: string;
+    /** Whether the session-start sandbox preflight runs at all. */
+    sandbox?: boolean;
+}
+/**
+ * The slice of a created agent this service inspects; the harness's agent
+ * object is structural here, the same view `auto-preset` uses.
+ */
+export interface PreflightAgent {
+    /** The agent's id. */
+    id: string;
+    /** The session stub, when mounted. */
+    session?: {
+        header?: {
+            cwd?: string | undefined;
+        };
+    } | undefined;
+}
+/**
+ * The cordis context extended with the slices this service consumes. `logger`
+ * and the agent service belong to the harness, whose declarations are not
+ * visible to this plugin, so they are spelled structurally on top of the
+ * framework's {@link Context}.
+ */
+export type PreflightContext = Context & {
+    logger?: {
+        debug?: (message: string) => void;
+        warn?: (message: string) => void;
+    };
+    agents?: {
+        list: () => PreflightAgent[];
+    };
+    on: (event: "agent/created", listener: (payload: {
+        agent?: PreflightAgent;
+    } | undefined) => void) => () => boolean;
+};
+/**
+ * Mount the preflight service.
+ *
+ * @param ctx - the cordis context.
+ * @param config - the schema-validated plugin config.
+ */
+export declare function apply(ctx: PreflightContext, config?: PreflightConfig): Promise<void>;

package/lib/preflight.js

@@ -0,0 +1,94 @@
+/**
+ * Session-start sandbox preflight: surface a missing or broken `bwrap` when a
+ * distro session OPENS, not when its first command fails closed.
+ *
+ * Without this the discovery moment is the model's first command, whose
+ * `SANDBOX_UNAVAILABLE` error scrolls past as one tool failure among many; the
+ * operator may not read it until several commands have failed the same way.
+ * The probe itself is not new — it is the providers' own usability probe, run
+ * through the same shared cache (`lib/sandbox-core.js`), so a session-start
+ * check costs a real probe only once per process, and the first confined
+ * command after it pays nothing. Nothing else changes: the failure semantics
+ * stay exactly as fail-closed as before, this service only MOVES THE NEWS.
+ *
+ * Advisory by construction. A preflight that cannot run (no WSL, a wedged
+ * `wsl.exe`) degrades to a log line; it must never fail a session that has not
+ * even asked for confinement yet. It also never installs anything: the remedy
+ * it prints is the same one the refusals carry, and running an installer under
+ * root uninvited would be a posture this plugin explicitly rejects.
+ *
+ * This is a TypeScript source built to `lib/preflight.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/preflight
+ */
+import z from "@deepseek-ai/schemastery";
+import { isWslUnc } from "./paths.js";
+import { defaultDistro } from "./wsl.js";
+import { bwrapFailure, bwrapUsable, missingBwrapRemedy } from "./sandbox-core.js";
+export const name = "wsl-preflight";
+export const Config = z.object({
+    /** Distro to preflight; empty means this machine's default distro. */
+    distro: z.string().default(""),
+    /** The `wsl.exe` path the probe spawns; keep in step with the providers' `wslPath`. */
+    wslPath: z.string().default("wsl.exe"),
+    /** Whether the session-start sandbox preflight runs at all. */
+    sandbox: z.boolean().default(true),
+});
+/**
+ * Mount the preflight service.
+ *
+ * @param ctx - the cordis context.
+ * @param config - the schema-validated plugin config.
+ */
+export async function apply(ctx, config = {}) {
+    if (!(config.sandbox ?? true))
+        return;
+    const wslPath = config.wslPath ?? "wsl.exe";
+    const warn = (message) => ctx.logger?.warn?.(message);
+    /**
+     * Probe the distro once and surface an unusable `bwrap` as a warning.
+     *
+     * @param agent - the session that just opened, for the workspace scope.
+     */
+    const check = async (agent) => {
+        // Only a distro workspace has commands that confine: a host session would
+        // warn about a sandbox it never uses.
+        const cwd = agent?.session?.header?.cwd;
+        if (cwd === undefined || !isWslUnc(cwd))
+            return;
+        let distro = config.distro ?? "";
+        if (distro.length === 0) {
+            try {
+                distro = await defaultDistro({ wslPath });
+            }
+            catch (error) {
+                // No WSL at all is the missing-wsl probe's territory; the first
+                // command's own error is the precise one. Stay quiet at warn level.
+                ctx.logger?.debug?.(`wsl-preflight: no default distro to preflight (${error?.message ?? error})`);
+                return;
+            }
+        }
+        // bwrapUsable answers false on a failed probe — it never rejects — so
+        // nothing here can throw except a broken context, which is the caller's
+        // bug, not the session's.
+        const usable = await bwrapUsable({ wslPath, distro });
+        if (usable) {
+            ctx.logger?.debug?.(`wsl-preflight: bwrap is usable inside distro "${distro}"`);
+            return;
+        }
+        warn(`wsl-preflight: ${bwrapFailure(wslPath, distro) ?? missingBwrapRemedy(distro)}`);
+    };
+    ctx.on("agent/created", (payload) => void check(payload?.agent));
+    // Mount order is not a guarantee: a session created during startup can finish
+    // before this service mounts and miss the event entirely (dsh-headless does
+    // exactly that, and auto-preset sweeps for the same reason).
+    try {
+        for (const agent of ctx.agents?.list() ?? [])
+            void check(agent);
+    }
+    catch (error) {
+        ctx.logger?.debug?.(`wsl-preflight: could not sweep already-live agents: ${error?.message ?? error}`);
+    }
+}

package/lib/probe-cache.d.ts

@@ -25,10 +25,21 @@ export interface ProbeCache {
      *
      * @param key - the probe's cache key.
      * @param probe - the probe to run on a miss. A throw is a failed probe, never
-     *   a propagated error.
+     *   a propagated error; its message is remembered for {@link failure}.
      * @returns the verdict; a success is remembered, a failure is not.
      */
     run(key: string, probe: () => Promise<boolean> | boolean): Promise<boolean>;
+    /**
+     * The message of the probe failure the key last recorded, if any. A failed
+     * verdict is not remembered as a verdict, but its reason outlives the miss:
+     * the remedy a caller prints is composed from WHY the probe failed, and the
+     * next caller — often the very next command — must still see it.
+     *
+     * @param key - the probe's cache key.
+     * @returns the thrown error's message, or undefined while no failure is
+     *   recorded; cleared on the key's next success.
+     */
+    failure(key: string): string | undefined;
     /** Remembered successes, for tests and diagnostics. */
     readonly size: number;
 }

package/lib/probe-cache.js

@@ -25,6 +25,7 @@
  */
 export function createProbeCache() {
     const verdicts = new Map();
+    const failures = new Map();
     return {
         async run(key, probe) {
             const cached = verdicts.get(key);
@@ -34,18 +35,25 @@ export function createProbeCache() {
                 try {
                     return await probe();
                 }
-                catch {
+                catch (error) {
+                    failures.set(key, error instanceof Error ? error.message : String(error));
                     return false;
                 }
             })();
             verdicts.set(key, pending);
             const verdict = await pending;
-            if (verdict)
+            if (verdict) {
                 verdicts.set(key, true);
-            else
+                failures.delete(key);
+            }
+            else {
                 verdicts.delete(key);
+            }
             return verdict;
         },
+        failure(key) {
+            return failures.get(key);
+        },
         /** Remembered successes, for tests and diagnostics. */
         get size() {
             return verdicts.size;

package/lib/sandbox-core.d.ts

@@ -16,6 +16,76 @@
  *
  * @module dsh-plugin-wsl/sandbox-core
  */
+/**
+ * The canonical remedy for a distro whose `bwrap` is missing — also the
+ * fallback for callers that know only "the probe failed", without a classified
+ * reason. The direct command is family-aware when the caller knows the family;
+ * the bootstrap script is always the first-choice path because it detects the
+ * family itself.
+ *
+ * @param distro - the distro to install into.
+ * @param family - the detected package family, when known.
+ * @returns the operator-facing remedy text.
+ */
+export declare function missingBwrapRemedy(distro: string, family?: string): string;
+/**
+ * The remedy for a bwrap that PROBED healthy but failed a run — the runtime
+ * twin of {@link missingBwrapRemedy}. No family knowledge exists on this path
+ * (the probe succeeded, so no family probe ever ran), and reinstalling is only
+ * one of the plausible fixes, so the hint leads with diagnosis.
+ *
+ * @param distro - the distro whose bwrap failed at run time.
+ * @returns the operator-facing hint text.
+ */
+export declare function bwrapInstallHint(distro: string): string;
+/**
+ * Append {@link bwrapInstallHint} to a runner-failure detail that names bwrap.
+ * A probe-time failure composes its own classified remedy; this covers the
+ * OTHER order — bwrap probed healthy, then failed a real command — where no
+ * probe failure is on record and the raw `bwrap: …` line is all the model
+ * would see. Details that do not name bwrap pass through untouched: the
+ * runner-failure rules match the confinement runner, and the confinement
+ * runner is always bwrap here, but the wording stays the decider so a future
+ * rule change cannot attach a bwrap remedy to a foreign failure.
+ *
+ * @param detail - the classified runner-failure detail.
+ * @param distro - the distro the command ran in.
+ * @returns the detail, with the remedy appended when it names bwrap.
+ */
+export declare function withBwrapHint(detail: string, distro: string): string;
+/**
+ * Probe one distro's `bwrap` under the shared verdict cache. The probe mirrors
+ * upstream's: apply the real read-only profile around `true`, and treat a zero
+ * exit as the kernel having accepted and enforced it. A missing `bwrap` fails
+ * the spawn and probes unusable, which is what makes the providers fail closed
+ * rather than silently run unconfined.
+ *
+ * A success is remembered for the process lifetime; a failure is not, so a
+ * `bubblewrap` installed while the app is running is believed on the next
+ * command. The failure's composed remedy stays readable through
+ * {@link bwrapFailure}, which is how every refusal and the preflight surface it.
+ *
+ * @param options - the `wsl.exe` path and the distro to probe.
+ * @param options.wslPath - the `wsl.exe` path.
+ * @param options.distro - the distro to probe.
+ * @param options.signal - optional cancellation.
+ * @returns true when a confined command can run there.
+ */
+export declare function bwrapUsable(options: {
+    wslPath: string;
+    distro: string;
+    signal?: AbortSignal | undefined;
+}): Promise<boolean>;
+/**
+ * The remedy text of a key's last failed probe, as {@link bwrapUsable} composed
+ * it — the same string the providers' refusals carry. Undefined while the probe
+ * never failed (or last succeeded).
+ *
+ * @param wslPath - the `wsl.exe` path the probe used.
+ * @param distro - the distro the probe ran in.
+ * @returns the composed remedy, or undefined.
+ */
+export declare function bwrapFailure(wslPath: string, distro: string): string | undefined;
 /**
  * The seam's `ConfinedArgv` settlement facts, plus this core's `windowsDrive`
  * mitigation flag.