@hope_phenom/dsh-plugin-remote-use 0.0.0-stage → 0.2.24

package/lib/core/sandbox-diagnosis.js

@@ -0,0 +1,258 @@
+/**
+ * What this machine is missing before it can be armed as a worker -- and the exact fix.
+ *
+ * WHY THIS IS READ-ONLY, AND WHY THAT IS THE WHOLE DESIGN.
+ *
+ * The arming gate refuses a machine whose sandbox cannot be proven. Proving it needs a
+ * `sandbox` entry in the ACP profile that names a materialized mediator; neither is something
+ * DSH ships, and the profile is created lazily, so a factory-fresh worker has neither. The
+ * previous answer was a paragraph of documentation, and it rotted silently: measured
+ * 2026-11-04 on the development machine, BOTH mediator directories were gone while the page
+ * kept saying nothing at all, because the probe only runs when somebody clicks "check".
+ *
+ * The tempting fix is to materialize the mediator and write the profile from the gate. That
+ * would let a page visit mutate the operator's environment -- writing outside the plugin's own
+ * state (`%DSH_HOME%\profiles\acp`, a mediator directory at a machine path), which is the kind
+ * of silent action this plugin spends most of its comments avoiding. Worse, it would take over
+ * "which DSH build is this mediator for", a question this plugin cannot answer better than the
+ * probe can.
+ *
+ * So the gate stays a gate, and this module answers a different question: WHAT EXACTLY IS
+ * MISSING, AND WHAT IS THE ONE COMMAND THAT FIXES IT. The command is executed by a person or by
+ * an agent they point at it (`lib/tools/prepare-sandbox-mediator.mjs`), and the probe below is
+ * still what decides whether arming is allowed. Nothing here writes, spawns, or caches.
+ */
+import { existsSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { installCandidates } from './self-acp-spec.js'
+import { shimNamedByProfile, subsystemOf } from './sandbox-probe.js'
+import { resolveDshHome } from './settings-store.js'
+
+/** Profile the worker role launches (`dsh --profile acp`). */
+export const WORKER_PROFILE = 'acp'
+
+/** Where the mediator goes when the profile does not already name one. */
+export const DEFAULT_MEDIATOR_LEAF = 'sandbox-mediator'
+
+/** @param {string} home */
+export function acpProfilePath(home) {
+  return join(home, 'profiles', WORKER_PROFILE, 'cordis.patch.yml')
+}
+
+/** The shipped fixer, addressed absolutely so a prompt can be pasted anywhere. */
+export function prepareScriptPath() {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', 'tools', 'prepare-sandbox-mediator.mjs')
+}
+
+/**
+ * The DSH installation this process belongs to.
+ *
+ * `process.execPath` is tried FIRST because it is the one fact that cannot be stale: the running
+ * host IS the installation the worker will spawn. The environment candidates are the fallback for
+ * a process started some other way (a test runner, `node tools/...`).
+ */
+export function resolveInstallDir(deps = {}) {
+  const env = deps.env ?? process.env
+  const exists = deps.exists ?? existsSync
+  const execPath = deps.execPath ?? process.execPath
+  const exe = 'DeepSeek Harness.exe'
+  const fromExec = typeof execPath === 'string' && basename(execPath).toLowerCase() === exe.toLowerCase()
+    ? dirname(execPath)
+    : ''
+  const candidates = [fromExec, env.DSH_INSTALL_DIR, ...installCandidates(env)]
+  const seen = new Set()
+  for (const candidate of candidates) {
+    if (typeof candidate !== 'string' || candidate === '') continue
+    const key = candidate.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    if (exists(join(candidate, exe))) return candidate
+  }
+  return ''
+}
+
+/**
+ * A CONSOLE-subsystem node.exe, which is the entire point of the mediator.
+ *
+ * A GUI-subsystem image (`DeepSeek Harness.exe`, PE subsystem 2) never gets a console, and the
+ * restricted child it creates dies during DLL initialization -- every shell command fails with no
+ * output. So a candidate whose PE subsystem is not 3 is skipped rather than used: picking it would
+ * reproduce the defect while looking configured.
+ */
+export function resolveNodeExe(deps = {}) {
+  const env = deps.env ?? process.env
+  const exists = deps.exists ?? existsSync
+  const subsystem = deps.subsystem ?? subsystemOf
+  const execPath = deps.execPath ?? process.execPath
+  const installDir = deps.installDir ?? ''
+  const candidates = []
+  if (typeof env.DSH_NODE_EXE === 'string' && env.DSH_NODE_EXE !== '') candidates.push(env.DSH_NODE_EXE)
+  if (installDir !== '') {
+    candidates.push(join(installDir, 'resources', 'runtime', 'primary-runtime', 'dependencies', 'node', 'bin', 'node.exe'))
+  }
+  candidates.push(join(env.ProgramFiles ?? 'C:\\Program Files', 'nodejs', 'node.exe'))
+  if (typeof env.LOCALAPPDATA === 'string' && env.LOCALAPPDATA !== '') {
+    candidates.push(join(env.LOCALAPPDATA, 'Programs', 'nodejs', 'node.exe'))
+  }
+  if (typeof execPath === 'string' && /^node(?:\.exe)?$/iu.test(basename(execPath))) candidates.push(execPath)
+  for (const dir of String(env.PATH ?? env.Path ?? '').split(';')) {
+    const trimmed = dir.trim()
+    if (trimmed !== '') candidates.push(join(trimmed, 'node.exe'))
+  }
+  const seen = new Set()
+  for (const candidate of candidates) {
+    if (typeof candidate !== 'string' || candidate === '') continue
+    const key = candidate.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    if (!exists(candidate)) continue
+    if (subsystem(candidate) !== 3) continue
+    return candidate
+  }
+  return ''
+}
+
+/**
+ * Read-only answer to "is the sandbox mediator ready on this machine, and if not, why".
+ *
+ * `ready` means MATERIALIZED, not PROVEN: the profile names a shim that exists next to a runner.
+ * Whether it actually confines is `probeSandbox`'s question, and the two must stay separate --
+ * conflating them is how "the files are there" would read as "the sandbox works".
+ *
+ * States:
+ *   ready        -- materialized and named by the profile; the probe still has the final say
+ *   missing      -- the profile names a mediator (or the default path is in use) and it is absent
+ *   unwired      -- the mediator may exist, but the profile does not name a usable sandbox runner
+ *   unsupported  -- this host/platform/installation cannot have one (nothing to prescribe but the reason)
+ *
+ * @param {object} [deps]
+ * @param {Record<string, string | undefined>} [deps.env]
+ * @param {string} [deps.home]       DSH home; defaults to DSH_HOME or ~/.dsh
+ * @param {string} [deps.profilePath]
+ * @param {string} [deps.installDir]
+ * @param {string} [deps.nodeExe]
+ * @param {string} [deps.platform]
+ * @param {(path: string) => boolean} [deps.exists]
+ * @param {(path: string) => number} [deps.subsystem]
+ * @returns {{ state: string, ready: boolean, reason: string, home: string, profilePath: string,
+ *             profileNamesShim: boolean, profileReason: string, mediatorDir: string, shim: string,
+ *             runner: string, nodeExe: string, installDir: string, platform: string }}
+ */
+export function inspectSandbox(deps = {}) {
+  const env = deps.env ?? process.env
+  const exists = deps.exists ?? existsSync
+  const platform = deps.platform ?? process.platform
+  const home = deps.home ?? resolveDshHome(env)
+  const profilePath = deps.profilePath ?? acpProfilePath(home)
+  const installDir = deps.installDir ?? resolveInstallDir({ env, exists, execPath: deps.execPath })
+  const nodeExe = deps.nodeExe ?? resolveNodeExe({
+    env, exists, execPath: deps.execPath, installDir, subsystem: deps.subsystem,
+  })
+  const named = deps.named ?? shimNamedByProfile(profilePath)
+  const namedShim = named.ok === true ? String(named.shim ?? '') : ''
+  const mediatorDir = namedShim !== '' ? dirname(namedShim) : join(home, DEFAULT_MEDIATOR_LEAF)
+  const shim = namedShim !== '' ? namedShim : join(mediatorDir, 'shim.mjs')
+  const runner = join(mediatorDir, 'node_modules', '@deepseek-ai', 'dsh-sandbox-windows-acl', 'lib', 'runner.js')
+  const materialized = exists(shim) && exists(runner)
+
+  let state = 'ready'
+  let reason = ''
+  if (platform !== 'win32') {
+    state = 'unsupported'
+    reason = `the sandbox mediator is a Windows mechanism and this host is ${platform}`
+  } else if (installDir === '') {
+    state = 'unsupported'
+    reason = 'could not find "DeepSeek Harness.exe"; pass --install with the installation directory'
+  } else if (nodeExe === '') {
+    state = 'unsupported'
+    reason = 'could not find a console-subsystem node.exe (the mediator interpreter); pass DSH_NODE_EXE or install Node'
+  } else if (named.ok !== true) {
+    state = 'unwired'
+    reason = `the ACP profile does not name a usable sandbox runner: ${String(named.reason ?? '')}`
+  } else if (!materialized) {
+    state = 'missing'
+    reason = `the profile names ${shim}, but it is not materialized there (shim=${exists(shim)} runner=${exists(runner)})`
+  }
+
+  return {
+    state,
+    ready: state === 'ready',
+    reason,
+    home,
+    profilePath,
+    profileNamesShim: named.ok === true,
+    profileReason: String(named.reason ?? ''),
+    mediatorDir,
+    shim,
+    runner,
+    nodeExe,
+    installDir,
+    platform,
+  }
+}
+
+/**
+ * The fix, as one command plus the text an operator (or an agent) needs to run it correctly.
+ *
+ * The command is quoting-safe for PowerShell, which is the shell this project's own tooling uses;
+ * the note says what to drop for CMD. Every path is filled in from THIS machine, because a prompt
+ * with a placeholder path is the documentation that already failed.
+ *
+ * @param {ReturnType<typeof inspectSandbox>} diagnosis
+ * @param {{ scriptPath?: string, shell?: 'pwsh' | 'cmd' }} [deps]
+ * @returns {{ command: string, text: string }}
+ */
+export function buildPrescription(diagnosis, deps = {}) {
+  const script = deps.scriptPath ?? prepareScriptPath()
+  const shell = deps.shell ?? 'pwsh'
+  const args = [
+    `"${script}"`,
+    `--dsh-home "${diagnosis.home}"`,
+    `--profile ${WORKER_PROFILE}`,
+    ...(diagnosis.installDir === '' ? [] : [`--install "${diagnosis.installDir}"`]),
+  ]
+  const command = shell === 'cmd'
+    ? `"${diagnosis.nodeExe || 'node'}" ${args.join(' ')}`
+    : `& "${diagnosis.nodeExe || 'node'}" ${args.join(' ')}`
+
+  const lines = [
+    '这台机器要当远程工作节点，但沙箱 mediator 还没就绪：',
+    `  ${diagnosis.reason}`,
+    '',
+    '请在这台机器上执行下面这一条命令（也可以把这段文字连同命令交给本机的 DSH 会话，让它去做）：',
+    '',
+    command,
+    '',
+    '它只做三件事：① 从本机 app.asar 物化沙箱 mediator；② 必要时往该 profile 的 cordis.patch.yml 追加 sandbox 行（已有可用条目就不动）；③ 跑一次六项沙箱校验。',
+    '',
+    '本机事实：',
+    `- DSH home : ${diagnosis.home}`,
+    `- profile  : ${diagnosis.profilePath}`,
+    `- mediator : ${diagnosis.mediatorDir}`,
+    `- node.exe : ${diagnosis.nodeExe === '' ? '(未找到)' : diagnosis.nodeExe}`,
+    '',
+    '注意：',
+    '- 命令必须在这台机器上运行，不是在主机上。',
+    '- DSH 自己的沙箱会拦工作区外的写入；命令被拦时，请改在终端里运行，或在全权会话里运行。',
+    '- 可重复执行：已就绪时它不会改动任何文件。',
+    '',
+    '跑完回到 设置 → 远程工作节点 → 本机角色，点「先检查」，六项都应通过。',
+  ]
+  return { command, text: lines.join('\n') }
+}
+
+/**
+ * The report the settings page renders.
+ *
+ * `prescription` is returned even when `ready` is true: the probe can still fail for a reason the
+ * file checks cannot see (a corrupted runner, a policy change), and in that case the same command
+ * is the right next step. The page decides when to show it.
+ *
+ * @param {object} [deps]
+ */
+export function diagnoseSandbox(deps = {}) {
+  const diagnosis = inspectSandbox(deps)
+  return { ...diagnosis, prescription: buildPrescription(diagnosis, deps) }
+}

package/lib/core/sandbox-probe.js

@@ -0,0 +1,310 @@
+/**
+ * Does this machine's Windows sandbox actually confine a command?
+ *
+ * WHY THIS LIVES IN THE PACKAGE rather than in the tool that first needed it: the arming gate
+ * (§16, "refuse to arm until the sandbox works") and `tools/check-sandbox-ready.mjs` must give
+ * the same answer. Two implementations of "does the sandbox work" would drift, and the drift
+ * would be invisible until a machine was armed on the strength of the wrong one.
+ *
+ * WHY IT IS BEHAVIOURAL. A configuration check -- "the profile names a mediator" -- is
+ * necessary but not sufficient: a mediator that is named and broken passes it. The failure that
+ * motivated all of this depends on the LAUNCH CONTEXT (a console-subsystem process allocates or
+ * inherits a console; a GUI-subsystem one does not), so the only reliable answer comes from
+ * running a command through the configured path and watching what happens.
+ *
+ * WHAT IT DOES NOT PROVE: that DSH will use this mediator. `probeSandbox` reports the config
+ * finding separately for exactly that reason, and the caller is expected to refuse on either.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+/** PE subsystem: 2 is GUI (never allocates a console), 3 is console (allocates one). */
+export function subsystemOf(file) {
+  try {
+    const buf = readFileSync(file)
+    const peOffset = buf.readUInt32LE(0x3C)
+    return buf.readUInt16LE(peOffset + 0x5C)
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * Which shim does the DSH profile name as the sandbox runner?
+ *
+ * THE PROFILE IS THE SOURCE OF TRUTH, and this function exists because treating a hardcoded default
+ * as the requirement was a real defect: a worker whose mediator had been materialized somewhere else
+ * -- and whose acp profile correctly pointed at it -- was refused with
+ *
+ *   the mediator works but DSH will not use it: runnerCommand names a different shim than
+ *   C:\dsh-sandbox-mediator\shim.mjs
+ *
+ * even though running a command through that very shim worked. The deployment location is not the
+ * plugin's business; what matters is that the profile names a shim and that the shim confines.
+ *
+ * A structural scan rather than a YAML parse: the deployment has no YAML dependency on this path, and
+ * the shape it looks for is six lines long.
+ *
+ * @param {string} profilePath
+ * @returns {{ ok: boolean, shim: string, reason: string }}
+ */
+export function shimNamedByProfile(profilePath) {
+  if (typeof profilePath !== 'string' || profilePath === '' || !existsSync(profilePath)) {
+    return { ok: false, shim: '', interpreter: '', reason: `no profile patch at ${profilePath}` }
+  }
+  let text
+  try {
+    text = readFileSync(profilePath, 'utf8')
+  } catch (error) {
+    return { ok: false, shim: '', interpreter: '', reason: `cannot read ${profilePath}: ${error.message}` }
+  }
+  // A file that carries an empty flow array AND list entries is INVALID YAML for this consumer:
+  // `[]` is a complete document, so anything appended after it starts a second document without a
+  // `---` separator, and the ACP child dies with "end of the stream or a document separator is
+  // expected". Measured 2026-11-05: the probe passed (it reads the file structurally), the machine
+  // armed, and every ACP connection then closed -- the master reported only `S0 worker reachable:
+  // fail`. DSH's shipped profile template IS `[]`, so this happens the first time an entry is
+  // appended to a fresh profile. Detected here because this is the one place that reads the file
+  // on the arming path; leaving it to the ACP child is too late (arming would already be allowed).
+  if (/(?:^|\n)[ \t]*\[\][ \t]*(?:\n|$)/u.test(text) && /(?:^|\n)[ \t]*-[ \t]/u.test(text)) {
+    return {
+      ok: false,
+      shim: '',
+      interpreter: '',
+      reason: 'the profile contains an empty list marker `[]` AND entries, which is invalid YAML (two documents) -- the ACP child refuses to start; remove the `[]` line, or run prepare-sandbox-mediator.mjs, which repairs it',
+    }
+  }
+  const entry = /-\s*id:\s*sandbox\b[\s\S]{0,600}?runnerCommand:([\s\S]{0,400}?)(?=\n\S|\n-|$)/u.exec(text)
+  if (entry === null) {
+    // Actionable on purpose: this message is what an operator sees when arming is refused, and the
+    // sandbox case previously said only that something did not match.
+    return {
+      ok: false,
+      shim: '',
+      interpreter: '',
+      reason: `the profile has no sandbox entry with a runnerCommand -- add "- id: sandbox" with a runnerCommand naming a console-subsystem mediator and runnerFailureSignatures (see README, Windows sandbox)`,
+    }
+  }
+  const normalised = entry[1].replace(/\\\\/gu, '\\').replace(/["']/gu, '')
+  const match = /([A-Za-z]:\\[^\r\n"']*shim\.mjs)/u.exec(normalised)
+  if (match === null) {
+    return { ok: false, shim: '', interpreter: '', reason: 'runnerCommand does not name a shim.mjs' }
+  }
+  if (!/runnerFailureSignatures/u.test(text)) {
+    return {
+      ok: false,
+      shim: '',
+      interpreter: '',
+      reason: 'runnerCommand is set without runnerFailureSignatures, which sandbox-local rejects at construction -- add the runner\'s error prefix, e.g. "windows-acl-run: "',
+    }
+  }
+  // The INTERPRETER the profile names, i.e. the first runnerCommand element when it is a node.exe.
+  // The probe runs the shim through it rather than through `process.execPath`: on a GUI-subsystem
+  // host (the DSH desktop app) that executable cannot host the restricted child, so probing it
+  // would answer a question about the HOST while the profile configures a different one -- and the
+  // answer could be "refuse" on a machine DSH would have run correctly (see probeSandbox).
+  const interpreter = /([A-Za-z]:\\[^\r\n"']*node\.exe)/iu.exec(normalised)?.[1] ?? ''
+  return { ok: true, shim: match[1], interpreter, reason: '' }
+}
+
+/**
+ * Does the DSH profile name THIS shim as the sandbox runner?
+ *
+ * Kept as its own primitive because "the profile names exactly this path" is a useful question --
+ * for tests, and for a caller that wants to assert a specific wiring. It is deliberately NOT how
+ * probeSandbox decides which shim to exercise: there the profile's own answer wins.
+ *
+ * @param {string} profilePath
+ * @param {string} shimPath
+ * @returns {{ ok: boolean, reason: string }}
+ */
+export function profileNamesShim(profilePath, shimPath) {
+  const named = shimNamedByProfile(profilePath)
+  if (!named.ok) return { ok: false, reason: named.reason }
+  // The exact path matters here: a stale mediator from a previous install would still look right by
+  // filename while driving an old runner.
+  if (!named.shim.includes(shimPath)) {
+    return { ok: false, reason: `runnerCommand names a different shim than ${shimPath}` }
+  }
+  return { ok: true, reason: '' }
+}
+
+/** The Windows shell the probe payload runs in, preferring the newer one. */
+function shellPath() {
+  const pwsh = 'C:\\Program Files\\PowerShell\\7\\pwsh.exe'
+  return existsSync(pwsh) ? pwsh : 'powershell.exe'
+}
+
+/**
+ * The payload writes the file ITSELF rather than relying on a shell redirect.
+ *
+ * A `cmd /c echo x > "path"` probe was tried first and reported "The filename, directory name,
+ * or volume label syntax is incorrect" -- the quoting does not survive being passed as argv, so
+ * the command failed for a reason unrelated to the sandbox. Worse, the outside-write check then
+ * "passed" for that same bogus reason, because it saw a non-zero exit and no file and concluded
+ * the sandbox had refused. A probe that fails for the wrong reason is worse than no probe: it
+ * reports the answer you were hoping for.
+ */
+function writePayload(path) {
+  return `try { Set-Content -LiteralPath ${JSON.stringify(path)} -Value probe-ok -ErrorAction Stop; Write-Output wrote-ok } catch { Write-Output ("refused: " + $_.Exception.Message); exit 9 }`
+}
+
+/**
+ * Run one command through the configured mediator path.
+ *
+ * The path is the configured `runnerCommand`: `node.exe <shim.mjs>` fed the bubblewrap profile.
+ * Probing the raw runner instead answers a different question, and answered it in a misleading
+ * direction: the raw runner invoked as `node.exe` works in a no-console launch, while DSH's own
+ * default (the GUI-subsystem image) does not.
+ */
+function runConfined(deps, opts, command) {
+  const profile = ['--ro-bind', '/', '/', '--dev', '/dev', '--unshare-pid', '--proc', '/proc', '--die-with-parent']
+  if (opts.readOnly !== true) profile.push('--tmpfs', '/tmp', '--bind', opts.workspace, opts.workspace)
+  const run = deps.spawn(deps.interpreter, [deps.shim, ...profile, '--', ...command], {
+    encoding: 'utf8', timeout: opts.timeoutMs ?? 30_000,
+  })
+  return { code: run.status, stdout: String(run.stdout ?? ''), stderr: String(run.stderr ?? ''), error: run.error?.message ?? '' }
+}
+
+/**
+ * Probe the sandbox through the path DSH is configured to use.
+ *
+ * @param {object} [deps]
+ * @param {string} [deps.mediator]   where the shim and runner were materialized
+ * @param {string} [deps.profile]    the DSH profile patch to read
+ * @param {(file: string, args: string[], opts: object) => object} [deps.spawn] injected for tests
+ * @param {string} [deps.workspace]  the workspace to grant; a temp directory by default
+ * @returns {{ ok: boolean, checks: Array<{name: string, ok: boolean, detail: string}>,
+ *             config: { ok: boolean, reason: string }, reason: string }}
+ */
+export function probeSandbox(deps = {}) {
+  const profile = deps.profile ?? join(process.env.USERPROFILE ?? '', '.dsh', 'profiles', 'desktop', 'cordis.patch.yml')
+  const injectedSpawn = deps.spawn
+  const spawn = injectedSpawn ?? ((file, args, opts) => spawnSync(file, args, opts))
+
+  // WHICH SHIM IS EXERCISED, in precedence order:
+  //
+  //   1. deps.mediator  -- an explicit override. Tests and diagnostics use it to point at a known
+  //                        location regardless of what the profile says.
+  //   2. the PROFILE     -- ★ the source of truth. This is the fix: the plugin used to require the
+  //                        hardcoded default, so a perfectly working mediator materialized anywhere
+  //                        else was refused. See shimNamedByProfile's note.
+  //   3. the default     -- only when the profile names nothing, so the failure is reported against
+  //                        the location an operator would have been told to use.
+  const named = shimNamedByProfile(profile)
+  const defaultMediator = 'C:\\dsh-sandbox-mediator'
+  const mediator = deps.mediator ?? (named.ok ? dirname(named.shim) : defaultMediator)
+  const shim = join(mediator, 'shim.mjs')
+  const runner = join(mediator, 'node_modules', '@deepseek-ai', 'dsh-sandbox-windows-acl', 'lib', 'runner.js')
+  // WHICH EXECUTABLE RUNS THE SHIM: the one the profile names.
+  //
+  // This used to be `process.execPath` unconditionally, which answered a question about the HOST
+  // (a GUI-subsystem desktop process, which may have no console) while the profile configured a
+  // console-subsystem node.exe. The two can disagree, and the disagreement always goes the same
+  // way: a machine DSH would have sandboxed correctly is refused. An explicit `deps.mediator`
+  // (tests, diagnostics) keeps the old behaviour, because there is no profile to read.
+  const interpreterFromProfile = deps.mediator === undefined && named.ok === true && named.interpreter !== ''
+  const interpreter = interpreterFromProfile ? named.interpreter : process.execPath
+  const workspace = deps.workspace ?? join(tmpdir(), 'dsh-sandbox-probe-ws')
+  const tempRoot = join(tmpdir(), 'dsh-sandbox-probe-tmp')
+
+  const checks = []
+  const add = (name, ok, detail = '') => checks.push({ name, ok, detail })
+
+  // `config` answers "does the profile name a usable shim", and it now names the one it found, so a
+  // refusal can say which file to fix instead of only that something did not match.
+  const config = deps.mediator === undefined
+    ? { ok: named.ok, reason: named.reason }
+    : profileNamesShim(profile, shim)
+
+  if (!existsSync(shim) || !existsSync(runner)) {
+    add('the mediator is materialized', false,
+      `shim=${existsSync(shim)} runner=${existsSync(runner)} at ${mediator}`)
+    return {
+      ok: false,
+      checks,
+      config,
+      reason: config.ok
+        ? `the profile names ${shim} but it is not materialized there`
+        : `the sandbox mediator is not materialized: ${config.reason}`,
+    }
+  }
+  add('the mediator is materialized', true)
+
+  // A named interpreter that is not installed is its own failure, not a reason to fall back:
+  // `dsh-sandbox-local` would spawn it too, so the run would fail on the worker side as well --
+  // just with no output, which is the symptom this whole file exists to make visible.
+  if (!existsSync(interpreter)) {
+    add('the mediator interpreter exists', false,
+      `runnerCommand names ${interpreter}, which is not present on this machine`)
+    return {
+      ok: false,
+      checks,
+      config,
+      reason: 'the mediator interpreter is missing: runnerCommand must name a console-subsystem node.exe',
+    }
+  }
+  add('the mediator interpreter exists', true,
+    interpreterFromProfile
+      ? interpreter
+      : deps.mediator === undefined
+        ? 'process.execPath (the profile names no interpreter)'
+        : "process.execPath (an explicit mediator was given, so the profile's interpreter is not used)")
+
+  rmSync(workspace, { recursive: true, force: true })
+  rmSync(tempRoot, { recursive: true, force: true })
+  mkdirSync(workspace, { recursive: true })
+  mkdirSync(tempRoot, { recursive: true })
+
+  const payload = [shellPath(), '-NoProfile', '-NonInteractive', '-Command']
+  const confined = (opts, command) => runConfined({ shim, spawn, interpreter }, { workspace, ...opts }, command)
+
+  try {
+    const alive = confined({}, [...payload, 'Write-Output sandbox-probe-alive'])
+    add('the mediator can execute a command at all', alive.code === 0 && alive.stdout.includes('sandbox-probe-alive'),
+      `exit=${alive.code} ${alive.stderr.trim().slice(0, 120)}`)
+
+    const inside = join(workspace, 'inside.txt')
+    rmSync(inside, { force: true })
+    const insideRun = confined({}, [...payload, writePayload(inside)])
+    add('a write INSIDE the workspace succeeds (the control)',
+      existsSync(inside) && insideRun.stdout.includes('wrote-ok'),
+      `exit=${insideRun.code} exists=${existsSync(inside)}`)
+
+    const outside = join(dirname(tempRoot), 'dsh-sandbox-probe-outside.txt')
+    rmSync(outside, { force: true })
+    const outsideRun = confined({}, [...payload, writePayload(outside)])
+    // Require BOTH: a reported refusal (not an unrelated failure) AND no file.
+    add('a write OUTSIDE the workspace is refused',
+      !existsSync(outside) && outsideRun.stdout.includes('refused:'),
+      existsSync(outside) ? 'the file EXISTS: workspace-write is not confining anything' : `exit=${outsideRun.code}`)
+
+    const readOnlyWrite = join(workspace, 'readonly.txt')
+    rmSync(readOnlyWrite, { force: true })
+    const readOnlyRun = confined({ readOnly: true }, [...payload, writePayload(readOnlyWrite)])
+    add('read-only cannot write the workspace either',
+      !existsSync(readOnlyWrite) && readOnlyRun.stdout.includes('refused:'),
+      existsSync(readOnlyWrite) ? 'read-only wrote the workspace: the tiers are not distinct' : `exit=${readOnlyRun.code}`)
+
+    const readOnlyRead = confined({ readOnly: true }, [...payload, 'Write-Output read-only-alive'])
+    add('read-only can still read',
+      readOnlyRead.code === 0 && readOnlyRead.stdout.includes('read-only-alive'), `exit=${readOnlyRead.code}`)
+
+    // Clean up BEFORE the verdict so a failure cannot leave probe files behind.
+    rmSync(workspace, { recursive: true, force: true })
+    rmSync(tempRoot, { recursive: true, force: true })
+    rmSync(outside, { force: true })
+
+    const failed = checks.filter((c) => !c.ok)
+    if (failed.length > 0) return { ok: false, checks, config, reason: `the sandbox did not confine: ${failed[0].name}` }
+    if (!config.ok) return { ok: false, checks, config, reason: `the mediator works but DSH will not use it: ${config.reason}` }
+    return { ok: true, checks, config, reason: '' }
+  } catch (error) {
+    rmSync(workspace, { recursive: true, force: true })
+    rmSync(tempRoot, { recursive: true, force: true })
+    add('the probe ran to completion', false, error instanceof Error ? error.message : String(error))
+    return { ok: false, checks, config, reason: `the probe could not complete: ${error instanceof Error ? error.message : String(error)}` }
+  }
+}