dsh-wsl-desktop 0.8.0 → 0.8.1

package/README.en.md

@@ -133,10 +133,19 @@ These are real boundaries, not a disclaimer list. Each one tells you where to re
   target is invalidated by entry changes only** — adds, removes and renames are seen, a content change
   of a file inside it is not; watch that file's own path to follow content. Mechanisms and
   measurements are in [WSL file watching](docs/WATCH.md).
+- **Confined mode needs passwordless sudo; without it there is no fence, and it fails loudly.** The
+  default permission mode is `workspace-write`, which has to build a mount namespace inside the
+  distro — and the WSL kernel does not allow bind mounts in a user namespace, so `sudo -n` is the only
+  way. Without that grant a confined command **fails outright** (with a structured error code, never a
+  silent unfenced run). Two ways out: give the session user NOPASSWD sudo, or switch the permission
+  mode to full access, which needs no sudo at all. See
+  [Linux-side confinement](docs/CONFINEMENT.md).
 - **A desktop update can break the plugin.** The plugin depends on the desktop framework's APIs — the
   harness — and changes to them interrupt it (0.1.6 → 0.1.7 broke four places in one go). So after
-  updating the desktop, run `node scripts/verify-post-restart.mjs` once and only keep going when
-  everything is green.
+  updating the desktop, open the W dialog once and confirm it lists your distributions, that
+  `bootstrap` reports the `pluginVersion` you just installed, and that `capabilities.status` is not
+  `degraded`; if any of those is wrong, take the desktop and the plugin back to a matching pair — the
+  order is in [Compatibility and upgrades](docs/COMPATIBILITY.md).
 - **Failures now carry a code, so you can diagnose first.** The browser receives a stable code and
   the whitelisted params, never the host message, stderr or resolved paths; after the user is
   confirmed, the W dialog shows an advisory health check whose failed rows carry the fix. Codes,
@@ -164,9 +173,10 @@ These are real boundaries, not a disclaimer list. Each one tells you where to re
 - [Engineering notes](docs/ENGINEERING-NOTES.md) — measured constraints, repository layout, release flow, install shape
 - [Distro support matrix](docs/DISTRO-SUPPORT.md) — which distros were verified, and what each one needs
 - [Compatibility and upgrades](docs/COMPATIBILITY.md) — plugin/desktop version relation, upgrade order, rollback steps
-- [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) — the two proposals to the harness upstream
+- [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) — the proposals to the harness upstream, including the record that an execution-world plugin cannot declare its session's initial permission posture
 - [Upstream defect reports](issues/README.md) — the harness issues filed, their measured evidence, and how the local workarounds relate
 - [Architecture and flow diagrams](docs/diagrams.md) — interactive architecture, sequence and lifecycle diagrams
+- [Real-machine acceptance runbook](docs/ACCEPTANCE-RUNBOOK.md) — the checks that only run on Windows + WSL2, their expected output, and the misjudgement list (Chinese only)
 
 Three of the linked documents — the distro support matrix, the upstream proposals and the diagram
 index — are **Chinese-only**, because no English text for them exists. Translating them is a separate

package/README.md

@@ -107,9 +107,16 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
   文件每 300ms `stat` 一次。**目录目标只对条目变化生效**——新增、删除、改名可见，目录里某个文件的
   内容变化不可见；要盯内容就按文件路径监听它。机制与实测见
   [WSL 文件变更监听](docs/WATCH.md)。
+- **受限模式要免密 sudo；没有就当不了围栏，而且会明确失败。** 默认权限模式是
+  `workspace-write`，它要求在发行版里搭 mount namespace，而 WSL 内核不允许在 user namespace
+  里做 bind mount，所以只能用 `sudo -n`。缺这份授权时受限命令**直接失败**（结构化错误码，
+  不是静默裸跑）。两条出路：给会话用户配 NOPASSWD sudo，或者把权限模式切到「完全权限」——
+  后者不需要任何 sudo。详见 [Linux 侧约束](docs/CONFINEMENT.md)。
 - **桌面更新后插件可能失效。** 插件依赖桌面内部的框架（harness）的 API，这些 API 变化会打断它
-  （0.1.6 → 0.1.7 一次断了四处）。所以更新桌面之后先跑一次
-  `node scripts/verify-post-restart.mjs`，全绿再继续用。
+  （0.1.6 → 0.1.7 一次断了四处）。所以更新桌面之后，先打开一次 W 对话框确认它能列出你的
+  发行版、`bootstrap` 里的 `pluginVersion` 是你刚装的版本、`capabilities.status` 不是
+  `degraded`；任何一项不对就把桌面和插件退回彼此匹配的版本，
+  顺序见 [兼容性与升级](docs/COMPATIBILITY.md)。
 - **失败现在带 code，可以先自己诊断。** 浏览器侧的错误只回稳定 code 与允许的 params，
   宿主 message、stderr 与解析后的路径不会过线；W 对话框在确认用户后会显示一条建议性的
   「环境检查」，失败项带修复命令。错误码、检查项与降级行为见 [诊断](docs/DIAGNOSTICS.md)。
@@ -134,9 +141,10 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
 - [工程笔记](docs/ENGINEERING-NOTES.md) — 实测约束、仓库布局、发版流程、安装形态
 - [发行版支持矩阵](docs/DISTRO-SUPPORT.md) — 哪些发行版验证过，每种缺什么
 - [兼容性与升级](docs/COMPATIBILITY.md) — 插件与桌面的版本关系、升级顺序、回退步骤
-- [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) — 对 harness 上游的两项提案
+- [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) — 对 harness 上游的提案（含执行世界类插件无法声明初始权限姿态的记录）
 - [上游缺陷记录](issues/README.md) — 已上报 harness 的问题、实测证据与本地规避的关系
 - [架构与流程图](docs/diagrams.md) — 可交互的架构、时序与生命周期图
+- [真实机器验收手册](docs/ACCEPTANCE-RUNBOOK.md) — 只能在 Windows + WSL2 上跑的检查项、期望输出与误判清单
 
 其中三份——发行版支持矩阵、上游 API 提案、架构与流程图索引——**只有中文版**，因为目前没有对应的
 英文文本。把它们翻成英文是一件独立的工作，不是改个文件名。

package/lib/client.js

@@ -362,9 +362,24 @@ window.__ModuleLoader__.load({
     function routeFailure(method, status, envelope) {
       const error = new Error(envelope?.error ?? `${method} failed (HTTP ${status})`)
       error.code = typeof envelope?.code === 'string' ? envelope.code : status === 0 ? 'transport' : 'internal'
-      error.params = envelope !== null && typeof envelope?.params === 'object' && envelope?.params !== null
-        ? envelope.params
-        : {}
+      // A refusal the route never answered carries no envelope — the transport
+      // fence answers an empty-bodied 401/403, and the webserver's own admission
+      // answers 401/403/503 the same way. Without the status this collapsed to a
+      // bare `internal` with empty params, which is what a real GUI check hit on
+      // Desktop 0.2.2-rc.3: every method failed and the diagnostic said nothing.
+      // The status is the ONE fact that separates "not authenticated" from
+      // "not permitted" from "host has no admission provider", so it is carried
+      // in the params the copyable report prints. It is produced locally, so it
+      // is not subject to the wire param allowlist.
+      const carried = envelope !== null && typeof envelope?.params === 'object' && envelope?.params !== null
+      if (carried) {
+        error.params = envelope.params
+      } else {
+        // No envelope means the route never answered in its own vocabulary; the
+        // HTTP status is then the only fact that separates "not authenticated"
+        // from "not permitted" from "the host has no admission provider".
+        error.params = status === 0 ? {} : { status }
+      }
       return error
     }
 

package/lib/host/http.js

@@ -9,11 +9,14 @@
  */
 
 import { randomBytes, timingSafeEqual } from 'node:crypto'
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { MAX_BODY_BYTES, DEV_TOKEN_HEADER, tokenMatches } from '../http-admission.js'
 
+/** Ceiling for the route-failure log, so a repeated failure cannot fill the disk. */
+const ROUTE_LOG_MAX_BYTES = 256 * 1024
+
 /**
  * The harness home that holds the user preset root.
  * @returns {string} the resolved `$DSH_HOME`.
@@ -67,11 +70,62 @@ export function sendRejection(res, rejection) {
   sendJson(res, rejection.status, { ok: false, code: rejection.code, error: rejection.message })
 }
 
-/** Trust surface consumed here; the browser-side connection package owns the full type. */
+/**
+ * Trust surface consumed here; the browser-side connection package owns the full type.
+ *
+ * `ctx.connection` is the only spelling that works, and it works because this
+ * plugin declares `connection` in its `inject` list. There is deliberately NO
+ * `ctx.get` fallback: Cordis resolves a service property against the CALLING
+ * context and THROWS for a service the caller never injected (`cannot get
+ * property "connection" without inject`) rather than returning `undefined`, so a
+ * fallback could not rescue that case — and when the service is genuinely
+ * unprovided, `ctx.get` returns `undefined` too, which the caller already
+ * handles. A fallback here would suggest a protection that does not exist.
+ * @param {object} ctx - the plugin context.
+ * @returns {object | undefined} the connection handle, when this composition has one.
+ */
 export function connectionOf(ctx) {
   return Reflect.get(ctx, 'connection')
 }
 
+/**
+ * Append one route failure to a log the operator can read.
+ *
+ * The route answers the browser with a code and nothing else — deliberately, so
+ * a host path or a wsl.exe stderr never crosses the wire. That is right for
+ * production and useless when the ROUTE ITSELF throws before it can name a
+ * reason: the browser shows `internal`, the host logs through a channel the
+ * desktop does not surface, and the only remaining evidence is this file. It is
+ * written on the operator's own disk, never sent anywhere.
+ * @param {string} step - the admission step that failed.
+ * @param {unknown} error - the thrown value.
+ * @returns {Promise<void>} settlement; a logging failure never masks the refusal.
+ */
+export async function logRouteFailure(step, error) {
+  try {
+    const path = join(dshHome(), 'wsl-desktop-route-error.log')
+    const detail = error instanceof Error ? (error.stack ?? error.message) : String(error)
+    const line = `${new Date().toISOString()} [${step}] ${detail}\n`
+    await mkdir(dirname(path), { recursive: true })
+    // Bounded, because a route that fails on every request would otherwise fill
+    // the operator's disk. Crossing the cap restarts the file with a note, so
+    // the NEWEST failure is always present and the file never grows without
+    // limit. A silently truncated diagnostic is worse than a fresh one.
+    let size = 0
+    try {
+      size = (await stat(path)).size
+    } catch {
+      size = 0
+    }
+    if (size + Buffer.byteLength(line) > ROUTE_LOG_MAX_BYTES) {
+      await writeFile(path, `[truncated above ${ROUTE_LOG_MAX_BYTES} bytes]\n`, 'utf8')
+    }
+    await writeFile(path, line, { flag: 'a' })
+  } catch {
+    // A diagnostic that throws must not change the response the caller gets.
+  }
+}
+
 /**
  * This installation's development token, minted on first use.
  *

package/lib/host/state.js

@@ -56,3 +56,37 @@ export const bindingTape = (() => {
     },
   }
 })()
+
+/**
+ * Wait briefly for a session's agent to appear in the registry.
+ *
+ * `api-session/added` fires BEFORE the harness registers the session's agent, so
+ * the post-hoc preset fallback raced it: `agents.get(sessionId)` was `undefined`,
+ * the fallback recorded "agent not registered" and returned — leaving a session
+ * whose cwd is a WSL path running in the WINDOWS world, permanently, because the
+ * harness fixes a preset at creation and refuses a later select. Measured on
+ * Desktop 0.2.2-rc.3 (a session in a WSL-UNC workspace, `ok:false` in the binding
+ * log). A bounded wait turns a guaranteed loss into a wait the registry wins.
+ *
+ * `now` and `sleep` are injectable so the wait is testable without real time.
+ * @param {{ get: (sessionId: unknown) => unknown }} agents - the agents registry.
+ * @param {unknown} sessionId - the session whose agent is wanted.
+ * @param {{ deadlineMs?: number, pollMs?: number, now?: () => number, sleep?: (ms: number) => Promise<void> }} [options] -
+ *   the bound, the poll interval, and the clock/sleeper (defaults are real).
+ * @returns {Promise<unknown>} the agent, or `undefined` when the bound expires.
+ */
+export async function waitForAgent(agents, sessionId, options = {}) {
+  const deadlineMs = options.deadlineMs ?? 2_000
+  const pollMs = options.pollMs ?? 50
+  const now = options.now ?? Date.now
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => { setTimeout(resolve, ms) }))
+  const startedAt = now()
+  for (;;) {
+    const agent = agents.get(sessionId)
+    if (agent !== undefined) return agent
+    // Checked AFTER a read so an already-registered agent never waits at all, and
+    // so the deadline is a bound on waiting rather than on attempts.
+    if (now() - startedAt >= deadlineMs) return undefined
+    await sleep(pollMs)
+  }
+}

package/lib/index.js

@@ -22,12 +22,12 @@ import {
   MAX_BODY_BYTES, DEV_TOKEN_HEADER, bodyAdmission, dispatchAdmission, fenceRejection, methodAdmission, preflight, tokenMatches,
 } from './http-admission.js'
 import {
-  connectionOf, devToken, isDeveloperCaller, readJsonBody, sendJson, sendRejection,
+  connectionOf, devToken, isDeveloperCaller, logRouteFailure, readJsonBody, sendJson, sendRejection,
 } from './host/http.js'
 import {
   GENERATED_PREFIX, basePluginsOf, runShellSpec, sourceDirFor, variantIdFor,
 } from './host/presets.js'
-import { bindingTape, hostSession, presetRun } from './host/state.js'
+import { bindingTape, hostSession, presetRun, waitForAgent } from './host/state.js'
 import { buildVariantPlugins } from './wsl/preset.js'
 import { setLocalSubprocess } from './wsl/host-refs.js'
 import { checkLinuxPath, defaultWorkspaceUnc, listLinuxDir, resolveDistroHome, runWslShell } from './wsl/world.js'
@@ -49,8 +49,17 @@ export const name = 'wsl-desktop'
  * carries the composition's trust fence: its Host/Origin check defeats DNS
  * rebinding, and its browser authentication (the login-token cookie) gates every
  * caller before any method runs.
+ *
+ * `connection.authentication` is a SERVICE IN ITS OWN RIGHT (`super(ctx,
+ * 'connection.authentication')`), and `connection.admit` reads it internally.
+ * Cordis resolves that read against the CALLING context, so a plugin that calls
+ * `admit` must inject it too — otherwise the call dies with `cannot get property
+ * "connection.authentication" without inject`, thrown from inside `admit`
+ * itself. That is exactly how the whole W dialog broke on Desktop 0.2.2-rc.3:
+ * the route was reachable, admission threw, and the host's last-resort listener
+ * answered an empty-bodied 400 that the browser could only call `internal`.
  */
-export const inject = ['webServer', 'connection']
+export const inject = ['webServer', 'connection', 'connection.authentication']
 
 /** Plugin config. */
 export const Config = z.object({
@@ -1484,6 +1493,17 @@ export function apply(ctx, config) {
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: config.routePath,
+    // Admission is this handler's job, so the route must not also be gated by
+    // the webserver. Harness 0.2.2-rc.3 (commit 71753fdf91, "centralize route
+    // admission with required policy") added this field and defaults an omitted
+    // one to `required` — which refuses the request BEFORE this handler runs.
+    // The observable result was a silent total failure: the W dialog rendered,
+    // every method answered an empty-bodied 401, and the browser half could only
+    // report it as `internal`. Declaring `anonymous` hands admission back to the
+    // fence below, which applies the same two arms and additionally lets a
+    // development token replace the 401 (a script cannot present a browser
+    // cookie). The host still applies its Host/Origin check to anonymous routes.
+    auth: 'anonymous',
     handler: async (req, res) => {
       // The fence first, exactly as every shipped host route does it: without
       // this, a cross-site `text/plain` POST is a CORS-simple request with no
@@ -1493,14 +1513,66 @@ export function apply(ctx, config) {
       // replaces the SECOND arm only — a local script cannot present a browser
       // cookie — and never the first: a token holder gains nothing from a
       // trusted Host, but a foreign Host must stay refused for every caller.
-      const developer = await isDeveloperCaller(req, config)
-      const rejection = fenceRejection({
-        rejection: connectionOf(ctx).requestRejection(req),
-        developer,
-      })
-      if (rejection !== undefined) {
-        res.writeHead(rejection, { 'content-type': 'text/plain; charset=utf-8' })
-        res.end()
+      //
+      // `admit` is the accessor to use: `requestRejection` was the same two arms
+      // and was REMOVED in the same 0.2.2-rc.3 commit. `admit` predates it and
+      // survives it, so this call site works on both generations.
+      // EVERYTHING from here to the response is inside one guard, because the
+      // host's last-resort listener turns an escaping throw into an EMPTY-bodied
+      // 400 (`webserver/src/index.ts`: `dispatch().catch(() => res.writeHead(400)`).
+      // That answer is indistinguishable, at the browser, from a transport
+      // refusal: the client's `json()` throws and the dialog shows only
+      // `internal`. Measured on Desktop 0.2.2-rc.3, where admission threw and the
+      // whole W dialog became an opaque "plugin internal error" — the single
+      // hardest failure to diagnose this route has produced. A JSON answer keeps
+      // the code, the ref and (for a developer caller) the message.
+      let developer = false
+      // The step is tracked so the refusal can NAME where admission broke. A
+      // browser cannot present the development token (it is a header a page
+      // never sends), so `developer` is false for every real page and the
+      // response can carry nothing about the cause — the file log is the only
+      // channel left. `step` itself is a fixed vocabulary word, not host data,
+      // so it is safe to return.
+      let step = 'developer'
+      try {
+        developer = await isDeveloperCaller(req, config)
+        step = 'connection'
+        const connection = connectionOf(ctx)
+        if (connection === undefined || typeof connection.admit !== 'function') {
+          throw new Error(`the composition exposes no connection admission (got ${connection === undefined ? 'undefined' : typeof connection})`)
+        }
+        step = 'admit'
+        const admission = connection.admit(req)
+        step = 'fence'
+        const rejection = fenceRejection({
+          rejection: 'rejection' in admission ? admission.rejection : undefined,
+          developer,
+        })
+        if (rejection !== undefined) {
+          res.writeHead(rejection, { 'content-type': 'text/plain; charset=utf-8' })
+          res.end()
+          return
+        }
+      } catch (error) {
+        // The stack goes to the operator's disk; the browser gets the shared
+        // classifier's envelope. The `step` is carried INSIDE a WslRouteError so
+        // it passes through `browserFailure`'s SAFE_PARAMS filter like every
+        // other param — appending it afterwards would make the allowlist entry
+        // decorative and the filter a lie. The constructor also supplies the
+        // correlation `ref` that `internal` always carries. The message itself
+        // is never sent — that is where host paths live — which is why the file
+        // log above exists.
+        //
+        // `internal` is stated rather than inferred, because the four steps above
+        // are admission plumbing: they raise TypeErrors and plain Errors, never a
+        // WslDomainError whose code would mean something to the browser. Passing
+        // the original as `cause` keeps it attached for anything that inspects the
+        // error object, without letting it change the wire code.
+        void logRouteFailure(step, error)
+        sendJson(res, 500, {
+          ok: false,
+          ...browserFailure(new WslRouteError('internal', { step }, { cause: error }), { discovery: false }),
+        })
         return
       }
       const early = preflight({ httpMethod: req.method, contentType: req.headers['content-type'] })
@@ -1643,9 +1715,15 @@ async function bindWslSession(ctx, summary) {
   if (parseWslUnc(cwd) === null) return
   const agents = ctx.get('agents')
   if (agents === undefined) return
-  const agent = agents.get(summary?.sessionId)
+  // WAIT, do not give up. `api-session/added` fires before the agent is
+  // registered, so the immediate `agents.get` below used to lose that race EVERY
+  // time: the fallback recorded "agent not registered" and returned, and the
+  // session stayed in the Windows world for good (the harness fixes a preset at
+  // creation). A bounded wait is the difference between a guaranteed loss and a
+  // wait the registry wins.
+  const agent = await waitForAgent(agents, summary?.sessionId)
   if (agent === undefined) {
-    recordBinding({ sessionId: String(summary?.sessionId), cwd, ok: false, error: 'agent 尚未注册' })
+    recordBinding({ sessionId: String(summary?.sessionId), cwd, ok: false, error: 'agent 尚未注册（已等待注册上限）' })
     return
   }
   await bindWslPreset(ctx, agent, cwd, String(summary?.sessionId))

package/lib/protocol.js

@@ -197,8 +197,8 @@ export const CHECK_REMEDIES = deepFreeze({
   },
   runner: {
     kind: 'text',
-    zh: '受限模式需要免密 sudo + unshare/setpriv，或安装 dsh-wsl-confine helper；danger-full-access 不受影响。',
-    en: 'Restricted mode needs passwordless sudo plus unshare/setpriv, or the dsh-wsl-confine helper; danger-full-access is unaffected.',
+    zh: '受限模式需要免密 sudo + unshare/setpriv，或安装 dsh-wsl-confine helper。两条出路：给会话用户配 NOPASSWD sudo，或在权限菜单里选「完全权限」（后者不需要任何 sudo，也不再受文件围栏约束）。',
+    en: 'Restricted mode needs passwordless sudo plus unshare/setpriv, or the dsh-wsl-confine helper. Two ways out: give the session user NOPASSWD sudo, or pick full access in the permission menu — that needs no sudo at all, and is no longer governed by the file fence.',
   },
   helper: {
     kind: 'text',
@@ -236,7 +236,12 @@ export const SAFE_PARAMS = deepFreeze({
   'host-capability-missing': ['feature'],
   'host-plugin-stale': ['method'],
   'too-busy': [],
-  internal: ['ref'],
+  // `step` names WHICH admission step refused the request (a fixed vocabulary:
+  // developer / connection / admit / fence). It exists because the route can
+  // throw before it has any other way to say where — and a browser caller can
+  // never be told the message, since that is where host paths live. It is a
+  // vocabulary word, not host data, which is what makes it safe to send.
+  internal: ['ref', 'step'],
   transport: [],
   'catalog-unavailable': [],
 })

package/lib/release-check.js

@@ -67,3 +67,80 @@ export function installWindow({ publishedAt, minimumReleaseAgeMinutes, now = new
       : `inside the minimumReleaseAge window until ${readyAt.toISOString()}`,
   }
 }
+
+/** The receipt schema this check knows how to read. */
+const RECEIPT_VERSION = 1
+
+/**
+ * The one suite that reaches the route handler, and therefore the only evidence
+ * that the seam works on the installed plugin. Its admitted `bootstrap` check is
+ * what failed to run before 2026-11-14 while the offline gate stayed green.
+ */
+const COVERING_SUITE = 'verify-route.mjs'
+
+/**
+ * Decide whether a recorded gate run may vouch for this release.
+ *
+ * The route-admission seam is covered ONLY by the live suites: an offline run
+ * cannot execute the handler at all, because reaching it needs a browser cookie
+ * or the development token. On 2026-11-14 a host change broke every route call
+ * while the offline gate stayed green at 25/27 — `verify-route.mjs` already
+ * asserted the admitted `bootstrap`, it simply never ran, because it sits in the
+ * LIVE list. The test was there; the release path never demanded it.
+ *
+ * So the release path now demands the receipt of a run that INCLUDED the live
+ * suites, describes the version being released, and failed nothing. The version
+ * comparison is what stops a receipt from an older build vouching for this one.
+ *
+ * `receipt.version` is read from the REPOSITORY manifest, while the live suites
+ * exercise the INSTALLED plugin — so the two could describe different code. They
+ * cannot here, and the reason is transitive: `verify-live-env.mjs` compares the
+ * running host's reported `pluginVersion` against that same manifest and turns a
+ * mismatch into a FAILED check, which lands in `counts.failed` and trips the
+ * rule above. A stale install therefore cannot produce a usable receipt; it
+ * produces a red one.
+ * @param {{ receipt: object|null, target: string }} input - the parsed receipt, or null when absent.
+ * @returns {{ ready: boolean, blockers: string[] }} the verdict.
+ */
+export function liveGateEvidence({ receipt, target }) {
+  if (receipt === null || typeof receipt !== 'object') {
+    return {
+      ready: false,
+      blockers: ['no gate receipt: run `node scripts/verify-all.mjs --live --receipt` before releasing'],
+    }
+  }
+  const blockers = []
+  // The schema version is checked FIRST because every rule below reads fields this
+  // function assumes it understands. A future receipt that redefines `counts` or
+  // `liveRan` would otherwise be interpreted as if it still meant the old thing.
+  if (receipt.receiptVersion !== RECEIPT_VERSION) {
+    blockers.push(`the receipt is schema version ${String(receipt.receiptVersion)}, and this check understands ${RECEIPT_VERSION}`)
+    return { ready: false, blockers }
+  }
+  if (receipt.liveRan !== true) {
+    blockers.push('the recorded gate run did NOT include the live suites (--live), and those are the only cover for the route-admission seam')
+  }
+  const failed = receipt?.counts?.failed
+  if (typeof failed !== 'number' || failed > 0) {
+    blockers.push(`the recorded gate run reported ${typeof failed === 'number' ? failed : 'an unreadable number of'} failure(s)`)
+  }
+  if (receipt.version !== target) {
+    blockers.push(`the receipt describes version ${String(receipt.version)}, not the target ${target} — re-run the gate after the version bump`)
+  }
+  // `liveRan` records the FLAG, not that anything ran. Without this the gate would
+  // accept a receipt whose live suites all skipped — a run that never reached the
+  // host — which is the "a green summary hides what did not run" failure this
+  // whole artefact exists to prevent, reintroduced one layer up.
+  const rows = Array.isArray(receipt.rows) ? receipt.rows : null
+  if (rows === null) {
+    blockers.push('the receipt carries no per-suite rows, so it cannot show that the suite covering the route-admission seam passed')
+  } else {
+    const covering = rows.find((row) => row?.suite === COVERING_SUITE)
+    if (covering === undefined) {
+      blockers.push(`the receipt has no row for ${COVERING_SUITE}, the only suite that reaches the route handler`)
+    } else if (covering.outcome !== 'passed') {
+      blockers.push(`${COVERING_SUITE} is recorded as ${String(covering.outcome)}${covering.reason === undefined || covering.reason === '' ? '' : ` (${covering.reason})`}, and it is the only suite that reaches the route handler`)
+    }
+  }
+  return { ready: blockers.length === 0, blockers }
+}

package/lib/wsl/preset.js

@@ -97,6 +97,14 @@ export const VERDICTED_KEPT_MODULES = new Set([
   '@deepseek-ai/dsh-tool-web',
   '@deepseek-ai/dsh-tool-cordis',
   '@deepseek-ai/dsh-tool-present',
+  // Added when harness 0.2.2-rc.3 shipped it (measured 2026-11-15: a `wsl-standard`
+  // and a `wsl-ptc` row survived unclassified). KEPT, and the reason is its inject
+  // list: `['tools', 'fs', 'workingDirectory', 'agents']` — it reaches files through
+  // the `fs` SERVICE, which a WSL preset mounts from this plugin, and its source
+  // carries no `node:fs`, no `spawn` and no `execFile`. So it neither runs a host
+  // command nor touches host files behind the model's back: it is world-agnostic,
+  // unlike `dsh-tool-executor-ptc`, which injects a host runtime and is removed.
+  '@deepseek-ai/dsh-tool-office',
 ])
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-wsl-desktop",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./lib/icon.svg",
@@ -13,8 +13,19 @@
     "prepack": "node -e \"const fs=require('node:fs'),p=require('node:path');(function w(d){for(const e of fs.readdirSync(d,{withFileTypes:true})){if(e.isDirectory()){const f=p.join(d,e.name);if(e.name==='__pycache__'){fs.rmSync(f,{recursive:true,force:true})}else{w(f)}}}})('lib')\""
   },
   "engines": {
-    "node": ">=22.19"
+    "node": ">=22.19",
+    "dsh": ">=0.1.7-0"
   },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "wsl",
+    "wsl2",
+    "workspace",
+    "execution-world",
+    "windows"
+  ],
   "files": [
     "lib",
     "cordis.patch.yml",