dsh-plugin-wsl-env 0.11.0 → 0.13.0

package/docs/ROADMAP.md

@@ -6,6 +6,10 @@ measurement; the numbers are in the ADR's
 [FS queue measurement](adr/0002-native-agent.md#fs-queue-measurement-a6-2026-10-18)
 section.
 
+> The product and ecosystem plan toward 1.0 is
+> [ROADMAP-1.0.md](ROADMAP-1.0.md). This file remains the current technical
+> plan for the native agent.
+
 ## Done
 
 | Step | Outcome |

package/docs/UPSTREAM-FILE-REFERENCE-SEAM.md

@@ -0,0 +1,80 @@
+# Upstream seam: `@` references over a WSL workspace
+
+Status: measured and deferred (2026-10-19). The `@` completion in
+`@deepseek-ai/dsh-file-reference-local` walks the workspace with
+`node:fs/promises` (`readdir` + `lstat`) from the **Windows** harness process.
+For a WSL workspace that walk crosses the 9p share on every directory; the
+plugin already has a distro-side traversal, but it cannot be wired until
+upstream exposes the funnel. This note records the cost, the seam, and the
+decision.
+
+## The measured cost
+
+Probe: [`test/probe/file-reference-9p.sh`](../test/probe/file-reference-9p.sh)
+(three runs, `node:fs` readdir walk, no ranking engine). Tree: 20 directories,
+520 files, one level of subdirectories; the same tree walked from Windows over
+`\\wsl.localhost\<distro>` and from inside the distro on ext4.
+
+| Walk | Median | Samples |
+|---|---|---|
+| Windows over 9p (`\\wsl.localhost\...`) | **84.7 ms** | 192.5, 84.7, 63.0 |
+| Distro on ext4 | **1.5 ms** | 2.4, 1.5, 1.3 |
+
+The ratio is ~56× on this tree. Variance on the 9p side is large (63–192 ms
+across three runs), which is itself the point: the cost is per-directory 9p
+traffic, so it grows with the tree and is sensitive to the share's state. A
+synthetic 520-entry tree is a floor for a real repository, not a ceiling.
+
+These numbers are the *traversal* only. The fuzzy ranking, generation and
+invalidation logic is not part of the measurement — it is the upstream code the
+seam must keep.
+
+## The seam
+
+RFC addendum ① (in [rfc-wsl-workspaces.md](upstream/rfc-wsl-workspaces.md))
+proposes exposing the three module-internal funnels as an injectable strategy:
+
+```ts
+interface FileReferenceTraversal {
+  readWorkspaceRoot(absolute: string, signal: AbortSignal): Promise<TraversalDirent[]>
+  readDirectory(absolute: string, signal: AbortSignal): Promise<TraversalDirent[]>
+  resolveDisplayDirectory(root: string, displayDirectory: string, signal: AbortSignal): Promise<string | undefined>
+}
+```
+
+with three semantics that matter for a remote world:
+
+- **Dirent shape**: entries stay `{ name, isDirectory(), isFile() }`; a symlink
+  is neither, so the distro listing uses `find -printf '%y\t%f'` (type char `l`)
+  rather than resolving links.
+- **Errors**: an unreadable directory yields `[]`; an aborted caller propagates
+  the abort.
+- **Coordinates**: the returned absolutes stay in the root's own coordinate
+  system (UNC for a distro workspace), because upstream joins children with the
+  host `node:path` — a POSIX path from the distro layer would be mangled.
+
+## The plugin side is ready
+
+[`src/file-reference-wsl.ts`](../src/file-reference-wsl.ts) implements that
+interface over the resident agent: one `find -printf` per directory, a
+single-exec segment walk for `resolveDisplayDirectory` (instead of N sequential
+`lstat`s), and the UNC/POSIX conversions. It is unit-tested against a fake
+agent and deliberately **not** wired into `cordis.patch.yml`: the funnel
+functions are module-internal, so wiring today would mean subclassing past them
+or re-implementing the ranking engine — the regression path the RFC rules out.
+
+## Decision and trigger
+
+**Fallback: keep the 9p walk.** `@` completion works today; it pays the
+per-directory share cost above. There is no plugin-side optimization that is
+safe without the seam, and the plugin does not replace the upstream module.
+
+Wire `file-reference-wsl` when either happens:
+
+- upstream exposes the traversal strategy (or an equivalent injectable funnel);
+- the plugin's own composition gains a way to supply the strategy without
+  patching module internals.
+
+At that point: wire the consumer, add an `@`-completion latency probe (the
+traversal probe above is the baseline), and only then claim a speed-up. Until
+then neither the README nor the roadmap promises one.

package/docs/UPSTREAM-LSP-SEAM.md

@@ -0,0 +1,90 @@
+# Upstream seam: LSP navigation for a WSL workspace
+
+Status: researched, **prototype deferred** (2026-10-19). No user-facing claim is
+made: the desktop composition does not mount `ctx.lsp` in `0.2.1-rc.2`, so
+`lsp` is not a tool the model can call in this plugin's profiles today. This
+note records what the seam is, what a WSL-backed provider would require, and
+the trigger that turns the prototype back on.
+
+## What exists upstream
+
+The LSP capability is split across three packages in the harness tree
+(`packages/lsp/`):
+
+| Package | Role |
+|---|---|
+| `@deepseek-ai/dsh-lsp` | the `ctx.lsp` service and the provider registry; four read-only operations: `goToDefinition`, `findReferences`, `goToImplementation`, `hover` |
+| `@deepseek-ai/dsh-lsp-stdio` | the generic stdio provider: a configured language-server command per workspace, transient document open, serialized queries |
+| `@deepseek-ai/dsh-tool-lsp` | the model-facing `lsp` tool, which owns the one-based cursor convention |
+
+It is an optional capability, not part of the agent-loop spine: a composition
+must mount the seam, a provider, and the tool; none are in the base profile.
+
+**Checked against `dsh-v0.2.1-rc.2`:** the desktop's
+`@deepseek-ai/dsh-base/cordis.patch.yml` (the app's bundled base layer) has no
+`lsp` row, and `packages/bundle/*` reference neither `dsh-lsp` nor
+`dsh-tool-lsp`. The packages exist and are test-covered upstream, but a
+stock desktop session has no LSP surface.
+
+## The pairing the provider assumes
+
+`dsh-lsp-stdio` declares `inject = ['fs', 'lsp', 'subprocess']`: source files
+are read through `ctx.fs`, and the language server is spawned through
+`ctx.subprocess`. Both must describe **the same execution world**:
+
+- the server's executable is resolved with `ctx.subprocess.resolveExecutable`
+  and spawned with `ctx.subprocess.spawn`;
+- the queried source is read through `ctx.fs`, which also produces the
+  `fileUrl` sent as the transient document's URI;
+- `workspaceRoot` is caller-supplied and canonicalized by the provider.
+
+In a WSL session, `ctx.fs` (the preset's isolated `wsl-fs`) and `ctx.subprocess`
+currently describe **different worlds**: the filesystem is the distro's, the
+subprocess seam is the host's. The plugin's preset isolates `shell` and `fs`
+only; the app-level `subprocess-wsl` row exists for the GUI terminal and is not
+preset-scoped. Mounting `dsh-lsp-stdio` in the WSL preset today would therefore
+launch a Windows language server against distro source and send it URIs it
+cannot open.
+
+## What a WSL-backed provider needs
+
+1. **A preset-scoped `subprocess` implementation.** `resolveExecutable` and
+   `spawn` must run inside the distro (argv, cwd, env in Linux coordinates),
+   with the same lifetime rules as the shell executor's commands. This is the
+   largest piece and has no upstream seam today; the terminal's
+   `subprocess-wsl` is a different, app-level consumer.
+2. **URI and path translation.** The server's world is `file:///home/...`;
+   the harness workspace identity is the UNC target
+   (`\\wsl.localhost\<distro>\...`). The provider/tool boundary must translate
+   both directions (request source, `workspaceFolders`, returned locations),
+   or the seam must gain a path/URI adapter instead of providers doing it
+   ad hoc.
+3. **Confinement and lifecycle.** A language server is a long-lived child of
+   the session: it should run under the same sandbox policy as commands
+   (`bwrap`), die with the session, and be subject to the same idle reclaim as
+   the resident agent. "Same execution world" also implies the server sees the
+   workspace at the same `/home/...` path the commands see.
+4. **Configuration per distro.** The `servers` record (id → command, extension →
+   language id) and executable resolution belong with the session's distro, not
+   the host profile: the same `typescript-language-server` may exist in one
+   distro and not another.
+
+## Prototype decision
+
+**Deferred, with a trigger.** The prototype cost is dominated by item 1 (a
+preset-scoped subprocess provider) and the tool surface does not exist in the
+shipped composition, so building it now would produce an unreachable code path.
+Revisit when any of these happens:
+
+- the desktop/base composition mounts `dsh-lsp` + `dsh-lsp-stdio` +
+  `dsh-tool-lsp` (the tool becomes reachable);
+- upstream proposes a preset-scoped subprocess provider or an fs/URI adapter
+  for providers;
+- a user asks for semantic navigation in a WSL workspace and accepts the
+  dependency on one of the above.
+
+Then, in order: a fake stdio language server running **inside the distro**
+through the new subprocess provider (unit-level), a real
+`typescript-language-server` probe on a Tier 1 image, and only then a docs
+claim. Until that proof exists, the plugin's README and ROADMAP say nothing
+about LSP support.

package/docs/UPSTREAM-SESSION-NOTICE.md

@@ -0,0 +1,95 @@
+# Upstream proposal: a session-visible notice seam for plugin advisories
+
+Status: proposed upstream; **not filed yet** — this environment has no issue
+channel, so the text below is ready for the maintainers to file against
+`deepseek-ai/deepseek-harness` (version line `0.2.1-rc.x`; the gap was checked
+against `dsh-v0.2.1-rc.2` on 2026-10-19). The exact filing payload (title, body,
+command) is [proposal-session-notice.md](upstream/proposal-session-notice.md). The plugin ships the workaround
+described at the end: the advisory goes to the log **and** into the session's
+runtime context, which is model-visible and appears in the session transcript,
+but is not a dedicated banner.
+
+## The gap
+
+A plugin that discovers an environment problem at session start has no way to
+tell the person looking at the session. The available channels are:
+
+- `ctx.logger.warn(...)` — the host log. A user who never opens the log never
+  sees it; `docs/LIMITATIONS.md` records this boundary.
+- a runtime-context entry (`ctx.systemPrompt.context(...)`) — model-visible,
+  reaches the transcript on the next assembly, but is not a notification and
+  has no dismissal or severity semantics.
+- `agent/error` — reserved for failures; an advisory that must never fail a
+  session cannot use it.
+
+There is no `ctx.notices`/`ctx.ui`/toast service in `0.2.1-rc.2`, and no
+client slot for one. The plugin's `wsl-preflight` therefore warns into the log
+and the runtime context, and the full check is `pnpm run doctor`
+([`scripts/doctor.mjs`](../scripts/doctor.mjs)).
+
+## What an advisory needs
+
+`wsl-preflight` runs when a distro session opens. Its findings are advisory:
+a missing `bubblewrap`, a distro without systemd, a missing `systemd-run`, or a
+user manager without Linger. None of them may fail the session — the first
+command fails closed on its own if it must — and none may install anything.
+What the author needs is exactly what the rule says:
+
+- **visible in the session** before the first failed command, not only in the
+  log;
+- **associated with a session**, so the notice appears in the session that
+  triggered the probe (two sessions on two distros can see different notices);
+- **severity and a remedy**, so the UI can render a warning with a
+  copy-pasteable fix rather than a bare string;
+- **disposable**, since a probe re-runs and a fixed environment must not keep
+  the old warning forever;
+- **non-fatal**: no turn is cancelled, no tool result is changed.
+
+## Proposed shape
+
+A small service plus a client slot, mirroring the approval service's
+session-scoped contract:
+
+```ts
+/** One session-scoped advisory. */
+interface SessionNotice {
+  /** Stable producer-owned id; re-notifying replaces by id. */
+  readonly id: string
+  /** `info` or `warning`; errors stay on `agent/error`. */
+  readonly level: 'info' | 'warning'
+  /** One-line text and an optional copy-paste remedy. */
+  readonly text: string
+  readonly remedy?: string
+}
+
+interface NoticeService {
+  /**
+   * Show or replace one notice for a session. Rejects when the session is
+   * not open; the producer owns the id and can dismiss it with `clear`.
+   */
+  notify(session: Session, notice: SessionNotice): Promise<void>
+  /** Remove a notice the producer published earlier. */
+  clear(session: Session, id: string): Promise<void>
+}
+```
+
+The client renders notices in the session header or above the composer with a
+dismiss control; the host keeps the last value per `(session, id)` so a
+reconnect and a replay agree. Nothing is model-visible unless the producer
+also adds a runtime-context entry, which keeps this seam purely presentational.
+
+## What this plugin would do with it
+
+`wsl-preflight` would publish one `SessionNotice` per verdict (`id:
+"wsl-preflight"`, `level: "warning"`, `text` = the one-line finding, `remedy` =
+the existing copy-paste command or `/etc/wsl.conf` change), replace it on the
+next verdict, and `clear` it when the probe passes. The runtime-context entry
+would stay as the model-facing half; the notice would be the human-facing one.
+
+## Workaround until it lands
+
+- `ctx.logger.warn` carries the full remedy.
+- A session-scoped runtime-context entry (`wsl-preflight`) repeats it in the
+  transcript, so it is visible to the model and in the context snapshot.
+- `pnpm run doctor` is the deterministic, human-facing check; its `--json`
+  output is the issue-template ask.

package/lib/agent-errors.d.ts

@@ -10,6 +10,13 @@
  *
  * @module dsh-plugin-wsl/agent-errors
  */
+/**
+ * The abort reason the execution layer uses when its timer fires. The timeout
+ * is enforced in the distro, so the agent layer must not add the out-of-band
+ * USR1 on this path: that signal has no request id and would hit whoever runs
+ * next.
+ */
+export declare const BASH_TIMEOUT_REASON = "BASH_TIMEOUT";
 export declare class AgentUnavailableError extends Error {
     /**
      * @param message - why the agent is out, for the log.
@@ -29,3 +36,15 @@ export declare class CwdError extends Error {
      */
     constructor(linuxPath: string);
 }
+/**
+ * The agent could not spawn the request's process at all (reason `spawn`).
+ * The native agent reports a missing workdir this way, without naming it; the
+ * executor retries such a request on the one-shot path, which can tell a
+ * missing directory from a missing executable and report the path.
+ */
+export declare class SpawnError extends Error {
+    /**
+     * @param message - the agent's spawn diagnostic.
+     */
+    constructor(message: string);
+}

package/lib/agent-errors.js

@@ -10,6 +10,13 @@
  *
  * @module dsh-plugin-wsl/agent-errors
  */
+/**
+ * The abort reason the execution layer uses when its timer fires. The timeout
+ * is enforced in the distro, so the agent layer must not add the out-of-band
+ * USR1 on this path: that signal has no request id and would hit whoever runs
+ * next.
+ */
+export const BASH_TIMEOUT_REASON = "BASH_TIMEOUT";
 export class AgentUnavailableError extends Error {
     /**
      * @param message - why the agent is out, for the log.
@@ -34,3 +41,18 @@ export class CwdError extends Error {
         this.linuxPath = linuxPath;
     }
 }
+/**
+ * The agent could not spawn the request's process at all (reason `spawn`).
+ * The native agent reports a missing workdir this way, without naming it; the
+ * executor retries such a request on the one-shot path, which can tell a
+ * missing directory from a missing executable and report the path.
+ */
+export class SpawnError extends Error {
+    /**
+     * @param message - the agent's spawn diagnostic.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "SpawnError";
+    }
+}

package/lib/agent-exec.js

@@ -28,7 +28,7 @@
  *
  * @module dsh-plugin-wsl/agent-exec
  */
-import { CwdError } from "./agent-errors.js";
+import { BASH_TIMEOUT_REASON, CwdError } from "./agent-errors.js";
 /**
  * A memory-backed output reader in the seam's shape.
  *
@@ -69,7 +69,7 @@ export function agentExecutionHandle({ agent, cwd, argv, timeoutMs = 0, maxOutpu
     if (timeoutMs > 0) {
         setTimeout(() => {
             timedOut = true;
-            controller.abort(new Error("BASH_TIMEOUT"));
+            controller.abort(new Error(BASH_TIMEOUT_REASON));
         }, timeoutMs).unref?.();
     }
     const settle = agent.exec({ cwd, argv, timeoutMs, maxOutputBytes, signal: controller.signal }).then((result) => ({ ok: true, result }), (error) => {

package/lib/agent.d.ts

@@ -10,11 +10,13 @@
  *    command or a write that was in flight has UNKNOWN state — replaying it
  *    would run non-idempotent work twice or report a create that actually
  *    succeeded as a refusal — so it fails instead, and the caller re-reads
- *    before retrying. A second failure marks the agent permanently dead and
- *    every future call rejects with {@link AgentUnavailableError} — the
- *    executor's cue to fall back to the one-shot `wsl.exe` path it shipped
- *    with, so the worst case of the agent is "today's behaviour, plus one
- *    failed round trip".
+ *    before retrying. A failure that spends the rebuild leaves the agent
+ *    `dead` with a bounded revival: the next call after a 2/4/8-second backoff
+ *    gets a fresh transport and its own single rebuild; after three deaths the
+ *    state is permanent and every call rejects with a restart remedy. While
+ *    dead, calls reject with {@link AgentUnavailableError} — the executor's cue
+ *    to fall back to the one-shot `wsl.exe` path it shipped with, so the worst
+ *    case of the agent is "today's behaviour, plus one failed round trip".
  * 2. **The in-distro timeout is the real one.** The EXEC frame carries the
  *    timeout in whole seconds and the agent SIGTERMs the child itself, so a
  *    timed-out command dies where it lives instead of leaving an orphan
@@ -59,6 +61,8 @@ export interface ExecResult {
 export interface PendingRequest {
     /** The request id, as the agent echoes it. */
     id: string;
+    /** The request's numeric sequence; newer requests have a larger one. */
+    seq: number;
     /** Which metric bucket this request belongs to. */
     kind: "fs" | "exec";
     /** When the frame was written, for the queue measurement. */
@@ -87,6 +91,10 @@ export interface PendingRequest {
     cancelled: boolean;
     /** The caller was already settled; a late answer only cleans up. */
     settled: boolean;
+    /** Whether the agent has answered (RES or ERR); a late signal is then unsafe. */
+    answered: boolean;
+    /** The delayed cancel signal, so it can be dropped when the request settles. */
+    signalTimer: NodeJS.Timeout | null;
 }
 /** Per-kind request metrics. */
 export interface RequestMetrics {
@@ -107,6 +115,21 @@ export interface RequestMetrics {
     /** Rejected before tracking: queue full, already aborted, or send failed. */
     rejected: number;
 }
+/** A read-only snapshot of the resident's lifecycle, for diagnostics. */
+export interface AgentStatus {
+    /** The distro served. */
+    distro: string;
+    /** Lifecycle state. */
+    state: "idle" | "starting" | "ready" | "dead";
+    /** The HELLO pid, when one is known and addressable. */
+    pid: number | undefined;
+    /** The last failure, if any. */
+    lastError: string;
+    /** Deaths observed; the revival budget is spent after {@link MAX_REVIVALS}. */
+    deaths: number;
+    /** Requests currently in flight. */
+    pending: number;
+}
 /** The agent's cumulative request metrics. */
 export interface AgentMetrics {
     /** FS frames. */
@@ -227,8 +250,16 @@ export declare class WslAgent {
     nextRequestId: number;
     /** The requests in flight, keyed by their current id. */
     pending: Map<string, PendingRequest>;
+    /** The newest request the agent has ACKed; a cancel older than this is stale. */
+    lastAckedSeq: number;
     /** Whether the one permitted rebuild has been spent. */
     rebuildUsed: boolean;
+    /** Deaths observed; each one past the first consumes the revival budget. */
+    deaths: number;
+    /** When the next revival may start, epoch ms; 0 when not waiting. */
+    deadUntil: number;
+    /** The first revival delay; tests shorten it. */
+    revivalBackoffMs: number;
     /** The idle-shutdown timer. */
     idleTimer: NodeJS.Timeout | null;
     /** The last failure, for `unavailableReason` and log messages. */
@@ -307,6 +338,8 @@ export declare class WslAgent {
         maxPending?: number;
         /** Optional async preparation selecting the entry before the first spawn. */
         prepare?: () => Promise<WslAgentPrepared | undefined>;
+        /** The first revival delay in ms; doubles per death. Tests shorten it. */
+        revivalBackoffMs?: number;
     });
     /**
      * Whether the agent is permanently out — the executor's fallback cue.
@@ -316,6 +349,22 @@ export declare class WslAgent {
     get unavailable(): boolean;
     /** Human-readable reason for the last transition to `dead`, for logging. */
     get unavailableReason(): string;
+    /**
+     * Enter the dead state and schedule the next bounded revival attempt.
+     *
+     * The delay doubles per death (2 s, 4 s, 8 s, … capped at 30 s). After
+     * {@link MAX_REVIVALS} deaths the state stays permanent and the refusal
+     * carries the restart remedy.
+     */
+    markDead(): void;
+    /**
+     * A read-only lifecycle snapshot for diagnostics. Includes the live pid, the
+     * last failure and the remaining revival budget; it never starts or stops
+     * anything.
+     *
+     * @returns the status snapshot.
+     */
+    status(): AgentStatus;
     /**
      * Start the process and wait for the handshake. Re-entrant: concurrent
      * callers share the one start.
@@ -526,6 +575,20 @@ export declare class WslAgent {
      * @param pending - the entry to clear.
      */
     private clearPending;
+    /**
+     * Deliver the out-of-band cancel signal after a short grace, and only while
+     * the request it was meant for is still the agent's current one.
+     *
+     * The signal has no request id: it interrupts whatever command the agent is
+     * blocked in. A timeout request is usually already being killed by the
+     * in-distro watcher, so an immediate signal can land after the agent moved
+     * on — the next request then dies with exit 138 (SIGUSR1) and looks
+     * `completed`. A newer ACK means the agent has answered the old request, so
+     * the signal is dropped; an answered request is dropped too.
+     *
+     * @param pending - the cancelled request.
+     */
+    private armCancelSignal;
 }
 /**
  * Rewrite the request id inside a stored frame so a resent request does not