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

package/slave/relay.mjs

@@ -0,0 +1,1351 @@
+#!/usr/bin/env node
+/**
+ * relay.mjs -- SLAVE side of dsh-plugin-remote-use.
+ *
+ * The relay is the plugin host on the worker. It bridges a WebSocket to a
+ * `dsh --profile acp` child process over stdio AND serves the plugin's own RPC
+ * methods, so the master can ask questions ACP has no method for:
+ *
+ *   ws client <--text frames (NDJSON)--> relay --+--> dsh-remote/*   (handled here)
+ *                                                +--> everything else --> dsh --profile acp
+ *
+ * The `dsh-remote/*` methods are `ping`, `selfcheck`, `pairing`, `screenshot`, `shotcache`, `stat` and
+ * `list`. `shotcache` is the odd one out: it is the only method that both reports AND deletes (the
+ * worker's own captured PNGs), which is why its rules live in `prune-shots.mjs` with their own
+ * tests rather than inline here. `stat`/`list` are the metadata half of file transfer, whose byte
+ * half is HTTP (`/file`, `/file/commit`) for the reason /screenshot is: see file-transfer.mjs.
+ *
+ * WHY THE RELAY OWNS SELF-CHECK: the readiness report has session-level checks
+ * (`S7` unlocked, `S8` live input injection) that only mean anything in an
+ * INTERACTIVE session -- in the services session `EnumDisplayDevices` returns nothing
+ * and `SendInput` reports 0/3 even though the worker is perfectly healthy
+ * (DESIGN §5.10.2.1 constraint B). The relay runs as the credential-owning user in
+ * that interactive session, so a PowerShell child of the relay lands in the right
+ * session and the report is real.
+ *
+ * Depends only on `ws` + Node builtins, deliberately: the worker should need the
+ * smallest possible dependency surface.
+ *
+ * Usage:
+ *   node relay.mjs --port 7331 --token <secret> --cmd-file <agent-spec.json>
+ *                  [--selfcheck-script selfcheck.ps1] [--selfcheck-cache-ms 30000]
+ *                  [--screenshot-script screenshot.ps1] [--shot-dir <dir>]
+ *                  [--keep-shots <n>] [--keep-shot-bytes <n>]
+ *                  [--max-transfer-bytes <n>]
+ *                  [--settings-file <settings.json>]
+ *                  [--repair-integrity] [--no-integrity-repair]
+ *                  [--allow-no-auth] [--verbose]
+ */
+import { spawn, spawnSync } from 'node:child_process'
+import { createServer } from 'node:http'
+import { createReadStream, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { homedir, networkInterfaces } from 'node:os'
+import { timingSafeEqual } from 'node:crypto'
+import { pipeline } from 'node:stream/promises'
+import { fileURLToPath } from 'node:url'
+import { WebSocketServer } from 'ws'
+// Sibling file, not a package: it ships next to this one so a worker needs no install step.
+import { RELAY_SHOT_PATTERN, pruneShots, shotUsage } from './prune-shots.mjs'
+import { encodePairing } from './pairing.mjs'
+import { bestAddress } from './net-address.mjs'
+import { effectiveSessionMode, sessionModeCheck, sessionModeConsistency } from './permission-pairing.mjs'
+import { repairWorkspaceIntegrity } from './workspace-integrity.mjs'
+import {
+  DEFAULT_MAX_TRANSFER_BYTES,
+  commitPart,
+  deletePart,
+  listDir,
+  maxTransferBytesOf,
+  putChunk,
+  rangeOf,
+  readJsonBody,
+  resolveTransferPath,
+  sha256File,
+  statTarget,
+} from './file-transfer.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+// ---------- args ----------
+const argv = process.argv.slice(2)
+function arg(name, fallback) {
+  const i = argv.indexOf(`--${name}`)
+  return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : fallback
+}
+const PORT = Number(arg('port', '7331'))
+const HOST = arg('host', '0.0.0.0')
+const TOKEN = arg('token', '')
+const CMD_FILE = arg('cmd-file', '')
+const DSH_CMD = arg('dsh', 'dsh --profile acp')
+const SELFCHECK_SCRIPT = arg('selfcheck-script', join(HERE, 'selfcheck.ps1'))
+const SELFCHECK_CACHE_MS = Number(arg('selfcheck-cache-ms', '30000'))
+const ALLOW_NO_AUTH = argv.includes('--allow-no-auth')
+const VERBOSE = argv.includes('--verbose')
+
+/**
+ * The settings file the plugin writes on THIS machine.
+ *
+ * A supervised relay is started by the plugin, so the plugin already knows the mode; a hand-managed
+ * relay (a scheduled task with a fixed `--cmd-file`) does not. Reading the same file gives both
+ * deployments one place to compare "what is configured" against "what this relay will spawn".
+ */
+const CONFIGURED_SETTINGS_FILE = arg('settings-file', join(
+  process.env.DSH_HOME ?? join(homedir(), '.dsh'),
+  'storages', 'dsh-plugin-remote-use', 'settings.json',
+))
+
+/**
+ * Clear a stale Low mandatory label from the task directory when the session is full access.
+ *
+ * Measured 2026-10-19 on a real worker: `workspace-write` leaves an inheritable Low label on the
+ * workspace, and Windows launches a Low-labelled image at Low integrity even from a High token --
+ * so a GUI app copied into the tree cannot write `%LOCALAPPDATA%`. Full access is exactly the mode
+ * in which that label is no longer protecting anything. The repair is opt-out so an operator can
+ * keep the label deliberately.
+ */
+const REPAIR_INTEGRITY = argv.includes('--repair-integrity')
+const NO_INTEGRITY_REPAIR = argv.includes('--no-integrity-repair')
+const INTEGRITY_REPAIR_TIMEOUT_MS = Number(arg('integrity-repair-timeout-ms', '60000'))
+
+// ---------- file transfer ----------
+/**
+ * The hard write ceiling for `PUT /file`, and the same ceiling for reading one back out.
+ *
+ * WHY THE WORKER GETS ITS OWN CEILING AT ALL: the master has a budget too, but the master is the side
+ * that decided to start the transfer, and a token that leaked -- or a second master that paired with
+ * this worker -- would otherwise be able to fill this disk. A ceiling this process enforces is the
+ * only one that holds when the other side does not cooperate. Both ends default to 8 GiB so a
+ * transfer that never touched a flag does not die at the last chunk.
+ *
+ * Unusable values keep the default rather than removing the ceiling: see `maxTransferBytesOf` in
+ * file-transfer.mjs for why `0` must not mean "no limit" here.
+ */
+const MAX_TRANSFER_BYTES = maxTransferBytesOf(Number(arg('max-transfer-bytes', String(DEFAULT_MAX_TRANSFER_BYTES))))
+
+/**
+ * The task directory: where a RELATIVE transfer path resolves.
+ *
+ * IT IS PASSED IN, NOT INFERRED FROM `process.cwd()`. Measured 2026-10-16 on the reference worker:
+ * a SUPERVISED relay starts with its working directory set to the DSH profile directory -- the plugin
+ * spawns it without a `cwd`, so it inherits the desktop process's -- which is NOT the directory the
+ * operator armed. The consequence was the worst shape there is: `remotePath: "note.txt"` reported
+ * success while the bytes landed in `...\.dsh\profiles\desktop\`, and the master had no way to see it
+ * (`--task-dir` now carries the armed value, the same one the pairing string advertises, and the
+ * master echoes back what the relay resolved).
+ *
+ * Capturing it once is still deliberate: a `process.chdir` later would silently re-point every
+ * relative transfer at a different directory.
+ */
+const TASK_DIR = (() => {
+  const given = arg('task-dir', '')
+  return given === '' ? process.cwd() : resolve(given)
+})()
+/** Which source `TASK_DIR` came from. Reported at startup, because "where did this come from" is
+ *  exactly the question the bug above made unanswerable. */
+const TASK_DIR_SOURCE = arg('task-dir', '') === '' ? 'process.cwd()' : '--task-dir'
+/**
+ * What a RELATIVE transfer path may resolve against: a directory someone actually chose, or nothing.
+ *
+ * `null` means no `--task-dir` was given, and the transfer layer then REFUSES a relative path. The old
+ * behaviour fell back to `process.cwd()`, which for a supervised relay is the DSH profile directory --
+ * so a relative upload landed there and reported success (PITFALLS F40). Absolute paths are unaffected;
+ * a hand-started relay that wants relative paths passes `--task-dir .`.
+ */
+const DECLARED_TASK_DIR = TASK_DIR_SOURCE === '--task-dir' ? TASK_DIR : null
+
+// ---------- screenshot ----------
+const SCREENSHOT_SCRIPT = arg('screenshot-script', join(HERE, 'screenshot.ps1'))
+const SHOT_DIR = arg('shot-dir', join(HERE, 'shots'))
+/** The capture script writes its geometry report here; it sits next to the script. */
+const SCREENSHOT_REPORT = join(dirname(SCREENSHOT_SCRIPT), 'screenshot-report.txt')
+/**
+ * How many captures to keep on the worker, newest first.
+ *
+ * WHY THE WORKER PRUNES ITS OWN: a capture is a full-resolution PNG (measured ~9.5 MB on the
+ * reference worker), and this directory had reached 56.9 MB across six captures before anyone
+ * looked. The host keeps its own copies too and could try to delete these over HTTP, but a
+ * worker that cleans up after itself needs no new protocol surface and keeps working when the
+ * host is the thing that went away. A negative value disables pruning.
+ */
+const KEEP_SHOTS = Number(arg('keep-shots', '20'))
+
+/**
+ * Byte ceiling for those captures, enforced oldest-first after the count budget.
+ *
+ * WHY THIS EXISTS ON TOP OF THE COUNT: a count bounds FILES, not DISK. The same worker that
+ * reached 56.9 MB across six captures had a count budget of 20, which reads as "under control"
+ * while the directory it describes is 190 MB. 0 means "no byte budget", and that is the default
+ * deliberately: a relay upgraded by a master that knows nothing about this flag must keep
+ * behaving exactly as it did. A non-finite or negative value is also "no budget" -- never
+ * "delete everything" (see prune-shots.mjs).
+ */
+const KEEP_SHOT_BYTES = Number(arg('keep-shot-bytes', '0'))
+
+/**
+ * The address to advertise in a pairing string.
+ *
+ * `--host 0.0.0.0` (the default) means "listen everywhere", which is not an address a master
+ * can dial. So the advertised host is either an explicit `--advertise-host`, or the machine's
+ * best guess at its LAN address.
+ *
+ * WHY "BEST GUESS" RATHER THAN "FIRST IPv4": a Windows machine with Hyper-V, WSL, Docker or
+ * VirtualBox installed has several non-internal IPv4 addresses, and they are enumerated in no
+ * useful order. Picking the first one produced `172.20.0.1` on the development host -- a
+ * Hyper-V switch that no peer can reach -- so the pairing string was well-formed and useless.
+ * The heuristic below prefers an ordinary LAN address and skips interfaces whose names give
+ * them away as virtual.
+ *
+ * It is still a heuristic, which is why `--advertise-host` exists and why the choice is logged.
+ */
+const ADVERTISE_HOST = arg('advertise-host', '')
+
+function advertisableHost() {
+  if (ADVERTISE_HOST !== '') return ADVERTISE_HOST
+  if (HOST !== '0.0.0.0' && HOST !== '::' && HOST !== '') return HOST
+
+  // Shared with the plugin's arming path so the two cannot disagree about which address is the
+  // real LAN one. See slave/net-address.mjs for why the first non-internal IPv4 is not enough.
+  return bestAddress(networkInterfaces()) || '127.0.0.1'
+}
+
+/**
+ * The pairing string for this relay, or '' when it cannot be produced.
+ *
+ * Returns '' rather than a plausible-looking string when there is no token: an unauthenticated
+ * relay would otherwise emit a pairing string that pairs a master to an open worker.
+ */
+function pairingString() {
+  if (TOKEN === '') return ''
+  return encodePairing({
+    url: `ws://${advertisableHost()}:${PORT}`,
+    token: TOKEN,
+    name: arg('pairing-name', ''),
+  })
+}
+
+/**
+ * Where the pairing string is left for an operator who cannot read this process's console.
+ *
+ * `--pairing-file ''` disables it. That matters when the relay is spawned by the plugin rather
+ * than run by hand: `HERE` is then the plugin's own `slave/` directory, and writing there means
+ * an installed plugin modifies its own installation -- which on a `link:` install is the
+ * operator's source checkout. Found by running the supervised listener and looking at the repo.
+ */
+const PAIRING_FILE = arg('pairing-file', join(HERE, 'pairing.txt'))
+
+/**
+ * `--print-pairing`: print the pairing string and exit.
+ *
+ * This is the path a person actually uses -- they are already on the worker to start it, so
+ * printing costs nothing and beats going to fetch a file. It deliberately does NOT print the
+ * token in any other form: one line of output, one paste at the master.
+ */
+if (argv.includes('--print-pairing')) {
+  const pairing = pairingString()
+  if (pairing === '') {
+    process.stderr.write('cannot build a pairing string: this relay has no --token, so a master would pair with an unauthenticated worker\n')
+    process.exit(2)
+  }
+  process.stdout.write(`${pairing}\n`)
+  process.exit(0)
+}
+
+/** Plugin RPC namespace. Anything here is handled locally, never forwarded to ACP. */
+const PLUGIN_PREFIX = 'dsh-remote/'
+
+/**
+ * Load the ACP agent launch spec.
+ *
+ * Preferred: a JSON file `{command, args, env}`. Spawning an executable with an argv
+ * ARRAY avoids every Windows quoting hazard: `cmd.exe /c` loses quotes through the
+ * PowerShell->node hand-off, and Node refuses to spawn a `.cmd` without a shell
+ * (EINVAL). The spec must point at `<install>\DeepSeek Harness.exe` and replicate what
+ * `dsh.cmd` does, rather than launching the shim (DESIGN §13.1).
+ */
+function loadLaunchSpec() {
+  if (CMD_FILE !== '') {
+    const raw = readFileSync(CMD_FILE, 'utf8').replace(/^\uFEFF/, '')
+    const spec = JSON.parse(raw)
+    if (typeof spec?.command !== 'string' || !Array.isArray(spec?.args)) {
+      throw new Error(`--cmd-file ${CMD_FILE} must contain {"command":string,"args":string[]}`)
+    }
+    return { command: spec.command, args: spec.args, env: spec.env ?? {} }
+  }
+  const parts = (DSH_CMD.match(/"[^"]*"|\S+/g) ?? []).map((s) => s.replace(/^"|"$/g, ''))
+  return { command: parts[0], args: parts.slice(1), env: {} }
+}
+
+const LAUNCH = loadLaunchSpec()
+
+const log = (...a) => console.log(`[relay ${new Date().toISOString().slice(11, 23)}]`, ...a)
+const vlog = (...a) => { if (VERBOSE) log(...a) }
+
+/**
+ * Read a text file, tolerating the encoding Windows PowerShell actually produces.
+ *
+ * `Tee-Object -FilePath` and `Out-File` write UTF-16LE with a BOM in PowerShell 5.1, while
+ * `Set-Content -Encoding UTF8` writes UTF-8. A pure-UTF-8 reader silently sees NUL bytes
+ * interleaved and every prefix match fails -- that is how the screenshot geometry came back
+ * as 0x0 even though the report was correct on disk. Detect instead of assuming.
+ *
+ * @param {string} path
+ * @returns {string} decoded text without a BOM, or '' when unreadable
+ */
+function readTextFile(path) {
+  let buf
+  try { buf = readFileSync(path) } catch { return '' }
+  if (buf.length >= 2 && buf[0] === 0xFF && buf[1] === 0xFE) {
+    return buf.subarray(2).toString('utf16le')
+  }
+  if (buf.length >= 2 && buf[0] === 0xFE && buf[1] === 0xFF) {
+    // UTF-16BE: swap to LE, then decode.
+    const swapped = Buffer.from(buf.subarray(2))
+    swapped.swap16()
+    return swapped.toString('utf16le')
+  }
+  let start = 0
+  if (buf.length >= 3 && buf[0] === 0xEF && buf[1] === 0xBB && buf[2] === 0xBF) start = 3
+  return buf.subarray(start).toString('utf8')
+}
+
+/** mtime of a path, or 0 when it does not exist / cannot be read. */
+function mtimeOf(path) {
+  if (typeof path !== 'string' || path === '') return 0
+  try { return statSync(path).mtimeMs } catch { return 0 }
+}
+
+/** The plugin's settings file, as text. '' means absent or unreadable. */
+function readSettingsText() {
+  return readTextFile(CONFIGURED_SETTINGS_FILE)
+}
+
+/**
+ * What this relay will ACTUALLY spawn, next to what the machine is configured for.
+ *
+ * Two different truths, deliberately reported together: `effective` is the spec the child gets,
+ * `configured` is the settings-page value. A manual relay can make them disagree for hours, which is
+ * exactly the F38 failure -- one side says full access, the other runs workspace-write, and neither
+ * surface says so. `mismatch` is the field that makes that visible.
+ */
+function sessionModeSnapshot() {
+  const consistency = sessionModeConsistency({
+    specEnv: LAUNCH.env,
+    env: process.env,
+    settingsText: readSettingsText(),
+  })
+  return {
+    consistency,
+    state: {
+      sessionMode: consistency.effective.mode,
+      sessionModeFrom: consistency.effective.from,
+      effectiveSessionMode: consistency.effectiveMode,
+      configuredSessionMode: consistency.configured,
+      sessionModeMismatch: consistency.mismatch,
+      sessionModeSettingsError: consistency.settingsError,
+      settingsFile: CONFIGURED_SETTINGS_FILE,
+      settingsMtime: mtimeOf(CONFIGURED_SETTINGS_FILE),
+      launchSpec: {
+        path: CMD_FILE,
+        mtime: mtimeOf(CMD_FILE),
+        mode: typeof LAUNCH.env?.DSH_PERMISSION_MODE === 'string' ? LAUNCH.env.DSH_PERMISSION_MODE : '',
+      },
+      integrityRepair: INTEGRITY_REPAIR,
+    },
+  }
+}
+
+/** The subset of the mode state that `/healthz` may expose without authentication. */
+function healthModeState() {
+  const { state } = sessionModeSnapshot()
+  return {
+    sessionMode: state.sessionMode,
+    sessionModeFrom: state.sessionModeFrom,
+    effectiveSessionMode: state.effectiveSessionMode,
+    configuredSessionMode: state.configuredSessionMode,
+    sessionModeMismatch: state.sessionModeMismatch,
+    integrityRepair: {
+      applied: state.integrityRepair.applied,
+      skipped: state.integrityRepair.skipped,
+      reason: state.integrityRepair.reason,
+    },
+  }
+}
+
+/**
+ * Add the configured/effective check to a self-check report and recompute its counts.
+ *
+ * The report came from PowerShell, which cannot see the launch spec or the settings file. The relay
+ * can, so the check is appended here rather than in the script. Recomputing the verdict is not
+ * optional: a `warn` row with `verdict: ready` is the "report lies" shape this project keeps fixing.
+ */
+function withSessionModeCheck(report, snapshot) {
+  const base = { ...report, ...snapshot.state }
+  const check = sessionModeCheck(snapshot.consistency, { specPath: CMD_FILE })
+  if (check === null) return base
+  const checks = [...(Array.isArray(report.checks) ? report.checks : []), check]
+  const blockingFailures = checks.filter((c) => c.severity === 'blocking' && c.status === 'fail').length
+  const warnings = checks.filter((c) => (c.severity === 'blocking' || c.severity === 'warning') && c.status === 'warn').length
+  const unchecked = checks.filter((c) => c.status === 'unchecked').length
+  const verdict = blockingFailures > 0
+    ? 'blocked'
+    : unchecked > 0
+      ? 'partial'
+      : warnings > 0
+        ? 'warn'
+        : 'ready'
+  return { ...base, checks, blockingFailures, warnings, unchecked, verdict }
+}
+
+/**
+ * Repair the workspace label BEFORE the port opens.
+ *
+ * Doing it at module load rather than on the first connection is deliberate: a GUI task can start
+ * immediately after arming, and a repair that races it would leave the first launch Low. A large
+ * workspace makes this pass take longer; the timeout and the result are reported either way.
+ */
+const EARLY_MODE = effectiveSessionMode({ specEnv: LAUNCH.env, env: process.env })
+const EFFECTIVE_MODE = EARLY_MODE.mode === '' ? 'workspace-write' : EARLY_MODE.mode
+if (EFFECTIVE_MODE === 'danger-full-access' && DECLARED_TASK_DIR !== null) {
+  // Say it BEFORE a potentially slow recursive pass, so a relay that takes a few extra seconds to
+  // listen is explainable from its own output.
+  log(`workspace integrity: checking ${TASK_DIR} for a stale Low label ...`)
+}
+const INTEGRITY_REPAIR = NO_INTEGRITY_REPAIR
+  ? { applied: false, skipped: true, reason: 'disabled with --no-integrity-repair', error: '', dir: '', durationMs: 0, timedOut: false }
+  : repairWorkspaceIntegrity({
+    mode: EFFECTIVE_MODE,
+    dir: TASK_DIR,
+    declared: DECLARED_TASK_DIR !== null,
+    force: REPAIR_INTEGRITY,
+    timeoutMs: Number.isFinite(INTEGRITY_REPAIR_TIMEOUT_MS) ? INTEGRITY_REPAIR_TIMEOUT_MS : 60_000,
+  })
+if (INTEGRITY_REPAIR.applied) {
+  log(`workspace integrity: ${INTEGRITY_REPAIR.reason} (${INTEGRITY_REPAIR.dir}, ${INTEGRITY_REPAIR.durationMs} ms${INTEGRITY_REPAIR.timedOut ? ', TIMED OUT' : ''})`)
+} else if (INTEGRITY_REPAIR.error !== '') {
+  log(`WARNING: workspace integrity repair failed for ${INTEGRITY_REPAIR.dir}: ${INTEGRITY_REPAIR.error}`)
+} else if (EFFECTIVE_MODE === 'danger-full-access') {
+  log(`workspace integrity: not repaired -- ${INTEGRITY_REPAIR.reason}`)
+}
+
+// Say it at startup, not only when someone opens the report: a hand-managed relay can otherwise run
+// at the wrong level indefinitely while the settings page shows the intended one.
+const STARTUP_MODE = sessionModeSnapshot()
+if (STARTUP_MODE.consistency.mismatch) {
+  log(`WARNING: configured session mode ${STARTUP_MODE.consistency.configured} does not match the `
+    + `launch spec's effective ${STARTUP_MODE.consistency.effectiveMode}; this relay will spawn the SPEC's mode. `
+    + `Re-generate the spec from the saved setting and restart the relay.`)
+} else if (STARTUP_MODE.consistency.settingsError !== '') {
+  log(`WARNING: ${STARTUP_MODE.consistency.settingsError} (${CONFIGURED_SETTINGS_FILE})`)
+}
+
+// ---------------------------------------------------------------------------
+// plugin RPC: dsh-remote/selfcheck
+// ---------------------------------------------------------------------------
+
+/** @type {{ at: number, report: object } | undefined} */
+let selfcheckCache
+
+/**
+ * Run the readiness script and return its JSON report.
+ *
+ * The report is cached because `S8` genuinely moves the mouse: re-running it before
+ * every delegation would fight the task being dispatched. A caller passes
+ * `maxAgeMs: 0` to force a fresh run (the settings page does this).
+ *
+ * @param {number} maxAgeMs
+ * @returns {Promise<object>}
+ */
+async function runSelfCheck(maxAgeMs) {
+  const now = Date.now()
+  if (selfcheckCache !== undefined && maxAgeMs > 0 && now - selfcheckCache.at <= maxAgeMs) {
+    return { ...selfcheckCache.report, fresh: false, cachedAgeMs: now - selfcheckCache.at }
+  }
+
+  let exists = false
+  try { exists = statSync(SELFCHECK_SCRIPT).isFile() } catch { exists = false }
+  const degraded = (check) => ({
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    verdict: 'blocked',
+    sessionSegment: 'unavailable',
+    blockingFailures: 1,
+    warnings: 0,
+    unchecked: 0,
+    checks: [check],
+    fresh: true,
+  })
+  if (!exists) {
+    return degraded({
+      id: 'S0', name: 'self-check script present', severity: 'blocking', status: 'fail',
+      expected: SELFCHECK_SCRIPT, actual: 'missing',
+      fix: 'deploy selfcheck.ps1 next to relay.mjs, or pass --selfcheck-script',
+    })
+  }
+
+  const run = await new Promise((resolve) => {
+    // The task directory is where remote work actually runs, so it is the tree S20 must measure.
+    // Only under `danger-full-access`: a `workspace-write` workspace is SUPPOSED to be Low, and
+    // warning about it there would teach the operator to ignore the warning. Only an EXPLICIT
+    // `--task-dir` is passed: an inherited cwd can be System32 (the launcher comment above explains
+    // why), and probing an arbitrary inherited directory is worse than reporting no workspace at all.
+    const selfcheckArgs = [...PS_BASE_ARGS, '-File', SELFCHECK_SCRIPT]
+    if (DECLARED_TASK_DIR !== null && EFFECTIVE_MODE === 'danger-full-access') {
+      selfcheckArgs.push('-Workspace', DECLARED_TASK_DIR)
+    }
+    const ps = spawn(PS_EXE, selfcheckArgs,
+      { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
+    let out = ''
+    let err = ''
+    ps.stdout.on('data', (d) => { out += d.toString('utf8') })
+    // stderr is kept because "the script produced no JSON" is usually answered by it (a parse
+    // error, an execution-policy refusal, a missing assembly). Discarding it is what made this
+    // failure read as a JSON error instead of "PowerShell could not start".
+    ps.stderr.on('data', (d) => { err += d.toString('utf8') })
+    ps.on('error', (e) => resolve({ error: e.message, out, err }))
+    ps.on('exit', (code) => resolve({ code, out, err }))
+    setTimeout(() => { try { ps.kill() } catch { /* already gone */ } }, 60_000)
+  })
+
+  // A SPAWN FAILURE means the script never ran at all. Say THAT, with the interpreter it tried:
+  // reporting it as a JSON parse error is how a machine without PowerShell 7 looked like a worker
+  // producing a malformed report (measured 2026-11-05 on a fresh worker).
+  if (run.error !== undefined) {
+    log(`self-check spawn error: ${run.error}`)
+    return degraded({
+      id: 'S0', name: 'self-check script ran', severity: 'blocking', status: 'fail',
+      expected: PS_EXE, actual: String(run.error).slice(0, 200),
+      fix: 'this machine needs PowerShell 7 (install pwsh) or a runnable powershell.exe; the self-check cannot produce a report without one',
+    })
+  }
+
+  // The script writes selfcheck.json next to itself; prefer that over stdout, which
+  // also carries the human-readable twin.
+  const jsonPath = join(dirname(SELFCHECK_SCRIPT), 'selfcheck.json')
+  let parsed
+  try {
+    parsed = JSON.parse(readTextFile(jsonPath).replace(/^\uFEFF/, ''))
+  } catch (e) {
+    // The exit code and the script's own stderr answer the question this message raises; without
+    // them "Unexpected end of JSON input" is the only clue an operator gets.
+    const stderrTail = String(err ?? '').trim().split(/\r?\n/u).slice(-2).join(' / ')
+    const detail = [String(e.message), run.code === undefined ? '' : `exit ${run.code}`, stderrTail]
+      .filter((part) => part !== '').join(' | ')
+    return degraded({
+      id: 'S0', name: 'self-check produced a report', severity: 'blocking', status: 'fail',
+      expected: jsonPath, actual: detail.slice(0, 300),
+      fix: `run ${SELFCHECK_SCRIPT} by hand to see the failure`,
+    })
+  }
+
+  selfcheckCache = { at: Date.now(), report: parsed }
+  return { ...parsed, fresh: true, cachedAgeMs: 0 }
+}
+
+/**
+ * Handle a plugin RPC locally.
+ * @returns {Promise<object|null>} a JSON-RPC response, or null to forward to ACP
+ */
+async function handleLocalRpc(msg) {
+  const id = msg.id
+  const reply = (result) => ({ jsonrpc: '2.0', id, result })
+  const fail = (code, message) => ({ jsonrpc: '2.0', id, error: { code, message } })
+
+  switch (msg.method) {
+    case `${PLUGIN_PREFIX}ping`:
+      // The heartbeat reply is deliberately I/O-free. The master pings every 15 s, and a
+      // directory scan on every one of those is pure waste -- the shot cache changes only when
+      // someone captures or cleans up. `cache: true` is the master saying it is about to draw
+      // or resize the cache, which is the only moment the scan buys anything.
+      return reply({
+        pong: true,
+        at: new Date().toISOString(),
+        pid: process.pid,
+        ...(msg.params?.cache === true
+          ? {
+              shotCache: {
+                ...shotUsage(SHOT_DIR, RELAY_SHOT_PATTERN),
+                keepShots: KEEP_SHOTS,
+                maxBytes: KEEP_SHOT_BYTES,
+              },
+            }
+          : {}),
+      })
+
+    case `${PLUGIN_PREFIX}selfcheck`: {
+      const maxAgeMs = Number.isFinite(msg.params?.maxAgeMs) ? Number(msg.params.maxAgeMs) : SELFCHECK_CACHE_MS
+      try {
+        // The session mode rides along with the report the master ALREADY renders. It is the answer
+        // to "which permission level is this worker actually at", which until now could only be
+        // guessed from a spec file that this process may never have read (see effectiveSessionMode).
+        //
+        // The settings file is read on EVERY call, not cached at startup: the settings page can be
+        // saved while this relay keeps running, and a mismatch that only appears after a restart is
+        // exactly the "both are true for hours" failure this check exists to end.
+        const snapshot = sessionModeSnapshot()
+        return reply(withSessionModeCheck(await runSelfCheck(maxAgeMs), snapshot))
+      } catch (e) {
+        return fail(-32603, `self-check failed: ${e instanceof Error ? e.message : String(e)}`)
+      }
+    }
+
+    case `${PLUGIN_PREFIX}pairing`: {
+      // The master asking for a pairing string, e.g. to re-pair after a settings reset. It is
+      // already authenticated -- this RPC arrives over the token-checked WebSocket -- so
+      // returning the credential here is not a new exposure.
+      const pairing = pairingString()
+      if (pairing === '') return fail(-32603, 'this relay has no token, so it cannot produce a pairing string')
+      return reply({ ok: true, pairing })
+    }
+
+    case `${PLUGIN_PREFIX}screenshot`: {
+      try {
+        const shot = await captureScreenshot()
+        // Metadata only. The bytes come back over GET /screenshot: base64 in a JSON-RPC
+        // result would inflate a multi-megabyte PNG by a third and would have to travel
+        // through the ACP message pump, which exists for small control frames.
+        return reply({
+          ok: true,
+          width: shot.width,
+          height: shot.height,
+          bytes: shot.bytes,
+          displays: shot.displays,
+          capturedAt: shot.capturedAt,
+          path: shot.path,
+          downloadPath: '/screenshot',
+        })
+      } catch (e) {
+        return fail(-32603, `screenshot failed: ${e instanceof Error ? e.message : String(e)}`)
+      }
+    }
+
+    case `${PLUGIN_PREFIX}shotcache`: {
+      // The master's view of -- and lever on -- this worker's screenshot cache. The numbers are a
+      // handful of integers and travel over the JSON-RPC channel the plugin already owns, so this
+      // needs no new endpoint and no second thing to keep authenticated.
+      try {
+        const params = msg.params ?? {}
+        // The ceiling travels WITH the call rather than being stored: the master is the side that
+        // knows the budget it wants now, and a relay that remembered the last one would keep
+        // enforcing a value an operator has already changed. Anything unusable falls back to the
+        // command line, so this also works against a worker started with the flag.
+        const maxBytes = Number.isFinite(params.maxBytes) ? Number(params.maxBytes) : KEEP_SHOT_BYTES
+        let usage
+        let pruned
+        if (params.clear === true) {
+          // "Enforce the budget" and "clear the cache" are two different operations and only the
+          // first is automatic. `maxBytes: 0` cannot express the second -- it means "no budget" --
+          // so clearing gets its own flag, and it wins if a caller sends both.
+          pruned = clearShots()
+        } else if (params.prune === true) {
+          pruned = pruneOldShots(maxBytes)
+        } else {
+          // Report only: nothing was asked for, so nothing was removed and `kept` describes what
+          // is on disk (a 0 there would read as "the cache is empty", the opposite of the case an
+          // operator opens this screen for). `overBudgetBytes` still tells the truth, which is
+          // what shows the master that a `prune: true` would reclaim something.
+          usage = shotUsage(SHOT_DIR, RELAY_SHOT_PATTERN)
+          pruned = {
+            removed: 0,
+            kept: usage.files,
+            freedBytes: 0,
+            overBudgetBytes: maxBytes > 0 ? Math.max(0, usage.bytes - maxBytes) : 0,
+          }
+        }
+        // Measured AFTER any deletion (or reused from the report-only branch above), so what comes
+        // back describes the state the master will actually find.
+        usage ??= shotUsage(SHOT_DIR, RELAY_SHOT_PATTERN)
+        return reply({
+          ok: true,
+          dir: SHOT_DIR,
+          files: usage.files,
+          bytes: usage.bytes,
+          newestAt: usage.newestAt,
+          oldestAt: usage.oldestAt,
+          keepShots: KEEP_SHOTS,
+          maxBytes,
+          pruned,
+        })
+      } catch (e) {
+        return fail(-32603, `shot cache failed: ${e instanceof Error ? e.message : String(e)}`)
+      }
+    }
+
+    case `${PLUGIN_PREFIX}stat`: {
+      // The pre-flight question every transfer starts with: is it there, how big is it, and when was
+      // it last written. It travels over the RPC channel rather than HTTP because the answer is four
+      // fields, and a HEAD would have to be asked on a path this side parsed anyway.
+      const resolved = resolveTransferPath(msg.params?.path, DECLARED_TASK_DIR)
+      if (!resolved.ok) return fail(-32602, resolved.error)
+      try {
+        // `hash: true` is opt-in: a stat is what the master asks before deciding whether to transfer
+        // anything, and hashing an 8 GiB file to answer that would cost more than the transfer.
+        const info = await statTarget(resolved.path, { hash: msg.params?.hash === true })
+        return reply({
+          ok: true,
+          path: resolved.path,
+          exists: info.exists,
+          isDir: info.isDir,
+          size: info.size,
+          mtime: info.mtime,
+          // Absent rather than null when it was not asked for: "not computed" and "computed and
+          // there is no such thing" are different answers, and only one of them is about the file.
+          ...(info.sha256 !== undefined ? { sha256: info.sha256 } : {}),
+        })
+      } catch (e) {
+        return fail(-32603, `stat failed: ${e instanceof Error ? e.message : String(e)}`)
+      }
+    }
+
+    case `${PLUGIN_PREFIX}list`: {
+      const resolved = resolveTransferPath(msg.params?.path, DECLARED_TASK_DIR)
+      if (!resolved.ok) return fail(-32602, resolved.error)
+      try {
+        const listed = await listDir(resolved.path, { limit: msg.params?.limit })
+        // A path that is not a directory is an error, not an empty listing: "there is nothing there"
+        // and "that is a file" lead an operator to opposite conclusions.
+        if (!listed.ok) return fail(-32602, `${listed.error} (path=${resolved.path})`)
+        return reply({ ok: true, path: resolved.path, entries: listed.entries, truncated: listed.truncated })
+      } catch (e) {
+        return fail(-32603, `list failed: ${e instanceof Error ? e.message : String(e)}`)
+      }
+    }
+
+    default:
+      // Unknown dsh-remote/* method: answer explicitly, never silently forward. A
+      // silent forward would make a future protocol addition look like a no-op.
+      return fail(-32601, `unknown plugin method "${msg.method}"`)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// screenshot capture
+// ---------------------------------------------------------------------------
+
+let shotSeq = 0
+/** Single-flight: two captures must not race on the same report file or output path. */
+let capturing
+
+/**
+ * Capture the worker desktop with the sidecar script.
+ *
+ * MUST run in the interactive session -- in session 0 there is no desktop and the capture
+ * is empty (the same false negative the display checks have). The relay runs as the
+ * logged-in user, so a child process inherits the right session; that is precisely why
+ * the relay owns this rather than an SSH-invoked helper.
+ *
+ * @returns {Promise<{path:string,width:number,height:number,bytes:number,displays:string[],capturedAt:string}>}
+ */
+/**
+ * The PowerShell to run the helper scripts with, and the arguments that must precede `-File`.
+ *
+ * WHY `pwsh` IS PREFERRED, measured on this machine and not assumed:
+ *
+ * `screenshot.ps1` and `selfcheck.ps1` are launched by this relay, and on Windows they used to be
+ * launched with `powershell.exe` (5.1). That works when the scripts sit on a plain local volume.
+ * It does NOT work when they sit on the F: ReFS volume this project is developed on:
+ *
+ *   powershell.exe -NoProfile -ExecutionPolicy Bypass -File F:\...\screenshot.ps1
+ *     -> "The file ... is not digitally signed. You cannot run this script on the current system."
+ *
+ * The SAME file, the SAME arguments, from C:\Temp, runs. And `-ExecutionPolicy Bypass` does not
+ * help -- a WDAC/AppLocker-style rule blocks PowerShell 5.1 by PATH, independently of the
+ * execution policy. `pwsh` (7) is not subject to it and runs the identical script.
+ *
+ * The consequence was worse for the self-check than for the screenshot. The screenshot returned a
+ * loud 500; the self-check returned a FALLBACK REPORT (`{ verdict: 'blocked', checks: [{ id: 'S0',
+ * actual: 'Unexpected end of JSON input' }] }`), which is report-shaped enough that a caller
+ * checking `report.verdict !== undefined` saw a successful self-check. That is how it went unnoticed
+ * for eleven rounds.
+ *
+ * So: prefer `pwsh` when it exists, fall back to `powershell.exe` (which is what a worker without
+ * PowerShell 7 installed has).
+ */
+const PS_EXE = (() => {
+  if (process.platform !== 'win32') return 'pwsh'
+  const pf = process.env.ProgramFiles ?? 'C:\\Program Files'
+  const candidates = [
+    join(pf, 'PowerShell', '7', 'pwsh.exe'),
+    join(process.env.LOCALAPPDATA ?? '', 'Microsoft', 'WindowsApps', 'pwsh.exe'),
+  ]
+  for (const c of candidates) {
+    try {
+      const info = statSync(c)
+      // A Microsoft Store EXECUTION ALIAS is a 0-byte reparse point. Spawning it opens the Store
+      // instead of running PowerShell, which would look like "the script produced nothing" again.
+      // Only a real image with bytes counts as an installed PowerShell 7.
+      if (info.isFile() && info.size > 0) return c
+    } catch { /* not there */ }
+  }
+  // FALLBACK: Windows always ships Windows PowerShell 5.1. Returning 'pwsh' here made a worker
+  // WITHOUT PowerShell 7 spawn nothing at all -- the self-check wrote no JSON and S0 read
+  // "Unexpected end of JSON input" (measured 2026-11-05 on a fresh worker). 5.1 is blocked by a
+  // PATH-based rule on some volumes (see the note above); when that happens the spawn error is now
+  // reported as its own S0 with the error text, never as a JSON parse failure.
+  return 'powershell.exe'
+})()
+
+/** `-ExecutionPolicy Bypass` is kept for the 5.1 fallback, where it does help. */
+const PS_BASE_ARGS = process.platform === 'win32'
+  ? ['-NoProfile', '-ExecutionPolicy', 'Bypass']
+  : ['-NoProfile']
+
+async function captureScreenshot() {
+  if (capturing !== undefined) return await capturing
+  capturing = (async () => {
+    try { statSync(SCREENSHOT_SCRIPT) } catch {
+      throw new Error(`screenshot script not found at ${SCREENSHOT_SCRIPT}; pass --screenshot-script`)
+    }
+    try { mkdirSync(SHOT_DIR, { recursive: true }) } catch { /* exists */ }
+
+    // Prune BEFORE capturing, not after. `GET /screenshot?fresh=1` captures and then reads the
+    // file straight away, so a prune running afterwards could delete the very image the host
+    // is about to download whenever the budget is 0. Trimming first makes that impossible: the
+    // new file does not exist yet. The directory therefore holds up to KEEP_SHOTS + 1 files
+    // between a capture and the next one, which is the price of never racing the download.
+    const pruned = pruneOldShots()
+
+    const out = join(SHOT_DIR, `shot-${Date.now()}-${++shotSeq}.png`)
+
+    const run = await new Promise((resolve) => {
+      const isWin = process.platform === 'win32'
+      // `-WindowStyle Hidden` is not cosmetic: a visible console is captured into the
+      // frame AND can take focus, corrupting exactly the GUI measurements a screenshot
+      // exists to support. An earlier capture of this worker had the script's own
+      // PowerShell window in it.
+      // `-WindowStyle Hidden` stays: a visible console is captured into the frame AND can take
+      // focus, corrupting the very measurements a screenshot exists to support.
+      const args = process.platform === 'win32'
+        ? [...PS_BASE_ARGS, '-WindowStyle', 'Hidden', '-File', SCREENSHOT_SCRIPT, '-Out', out]
+        : [...PS_BASE_ARGS, '-File', SCREENSHOT_SCRIPT, '-Out', out]
+      const ps = spawn(PS_EXE, args, {
+        windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'],
+      })
+      let text = ''
+      ps.stdout.on('data', (d) => { text += d.toString('utf8') })
+      ps.stderr.on('data', (d) => { text += d.toString('utf8') })
+      ps.on('error', (e) => resolve({ error: e.message, text }))
+      ps.on('exit', (code) => resolve({ code, text }))
+      setTimeout(() => { try { ps.kill() } catch { /* gone */ } }, 60_000)
+    })
+
+    if (run.error !== undefined) throw new Error(`could not run capture: ${run.error}`)
+    let stat
+    try { stat = statSync(out) } catch { stat = undefined }
+    if (stat === undefined || stat.size === 0) {
+      throw new Error(`capture produced no image (exit ${run.code}); output: ${String(run.text).trim().slice(-300)}`)
+    }
+
+    // Geometry, because a screenshot is only interpretable next to it. readTextFile rather
+    // than a plain utf8 read: see the note on that helper.
+    const report = readTextFile(SCREENSHOT_REPORT)
+    const lines = report.split(/\r?\n/)
+    const displays = lines.filter((l) => l.startsWith('screen '))
+    const m = /w=(\d+)\s+h=(\d+)/.exec(lines.find((l) => l.startsWith('virtualscreen ')) ?? '')
+
+    return {
+      path: out,
+      width: m ? Number(m[1]) : 0,
+      height: m ? Number(m[2]) : 0,
+      bytes: stat.size,
+      displays,
+      capturedAt: new Date().toISOString(),
+      pruned,
+    }
+  })().finally(() => { capturing = undefined })
+  return await capturing
+}
+
+/**
+ * Delete captures this relay wrote until they fit the count and byte budgets.
+ *
+ * The rules live in `prune-shots.mjs`, which exists as its own file so they can be tested:
+ * this relay is a long-lived script with no harness of its own. The `--shot-dir` is
+ * configurable, so being explicit about which filenames may be deleted is what keeps a
+ * mistyped path from becoming data loss.
+ *
+ * Both budgets are applied in one call, count first: the count is what the operator asked to
+ * keep, and the byte ceiling trims further into it only when it has to. The newest capture is
+ * never removed, even when it alone is over the ceiling, because the master is about to download
+ * exactly that file (see `captureScreenshot`).
+ *
+ * @param {number} [maxBytes] byte ceiling; <= 0 means only the count budget applies
+ * @returns {{removed: number, kept: number, freedBytes: number, overBudgetBytes: number}}
+ */
+function pruneOldShots(maxBytes = KEEP_SHOT_BYTES) {
+  return pruneShots(SHOT_DIR, KEEP_SHOTS, RELAY_SHOT_PATTERN, { maxBytes })
+}
+
+/**
+ * Delete EVERY capture this relay wrote.
+ *
+ * This is the master's explicit "clear the cache" action: unlike `pruneOldShots` it keeps
+ * nothing, including the newest file. `keep: 0` is what the count pass calls "keep none", so the
+ * deletion goes through the one path that is already tested for pattern safety and for never
+ * throwing -- a second delete loop for the same job is how the two drift apart.
+ *
+ * @returns {{removed: number, kept: number, freedBytes: number, overBudgetBytes: number}}
+ */
+function clearShots() {
+  return pruneShots(SHOT_DIR, 0, RELAY_SHOT_PATTERN, {})
+}
+
+// ---------------------------------------------------------------------------
+// auth
+// ---------------------------------------------------------------------------
+function tokenOk(provided) {
+  if (TOKEN === '') return true
+  if (typeof provided !== 'string' || provided === '') return false
+  const a = Buffer.from(provided)
+  const b = Buffer.from(TOKEN)
+  if (a.length !== b.length) return false
+  return timingSafeEqual(a, b)
+}
+
+function bearerOf(req) {
+  const h = req.headers['authorization']
+  if (typeof h === 'string' && h.toLowerCase().startsWith('bearer ')) return h.slice(7).trim()
+  try { return new URL(req.url, 'http://x').searchParams.get('token') ?? '' } catch { return '' }
+}
+
+if (TOKEN === '' && !ALLOW_NO_AUTH) {
+  console.error('[relay] refusing to start: no --token given (pass --allow-no-auth to override)')
+  process.exit(2)
+}
+
+// ---------------------------------------------------------------------------
+// http + ws
+// ---------------------------------------------------------------------------
+
+/** Last capture, reused by /screenshot so an RPC followed by a download is one capture. */
+let lastShot
+
+// ---------------------------------------------------------------------------
+// file transfer, over HTTP
+//
+// WHY THESE LIVE NEXT TO /screenshot AND NOT ON THE RPC CHANNEL: the WebSocket carries the ACP pump
+// and the plugin's own control frames on one socket, so a file body on it would queue every GUI
+// control frame behind the bytes -- the same reason the screenshot moved here. What is in this
+// section is only the HTTP shape; every rule it obeys (ranges, `.part` staging, hashing, the commit
+// check) lives in file-transfer.mjs, where a test can reach it.
+// ---------------------------------------------------------------------------
+
+/** Write a JSON response. `content-length` is set explicitly so a truncated reply cannot be mistaken
+ *  for a complete one by a client that is reading a transfer protocol. */
+function jsonOut(res, status, body) {
+  const text = JSON.stringify(body)
+  res.writeHead(status, {
+    'content-type': 'application/json',
+    'content-length': String(Buffer.byteLength(text)),
+    'cache-control': 'no-store',
+  })
+  res.end(text)
+}
+
+/**
+ * One audit line per transfer request, on the worker.
+ *
+ * The master keeps the durable audit log; this is the worker's own record, and it exists because the
+ * resolved path is the only place the truth lives. A relative path from a master is meaningless
+ * later -- "which file did that 4 GiB write actually land in" is answerable only from this side, and
+ * there is no cage here (see resolveTransferPath), so the echo IS the safety mechanism.
+ */
+function audit(req, direction, detail) {
+  log(`transfer ${direction} peer=${req.socket.remoteAddress ?? '?'} ${detail}`)
+}
+
+/**
+ * `GET`/`HEAD /file?path=<p>[&offset=<n>]`.
+ *
+ * The WHOLE-FILE sha256 is computed before the headers, in a streaming pre-pass, and that ordering is
+ * forced by the protocol rather than chosen: the digest is a HEADER, so it must be known before the
+ * first body byte, and a header cannot be filled in from the bytes that follow it. The alternatives
+ * were worse -- buffering the file (the one thing this feature may not do) or sending the digest as
+ * an HTTP trailer, which no client of this protocol reads. On a resume (`206`) the file is therefore
+ * read twice, once to hash and once to send; no byte is ever held in memory either way.
+ *
+ * `HEAD` IS THE EXCEPTION, and it has to be: the whole point of asking for headers alone is to learn
+ * the size cheaply, and hashing first would make a probe of a 2 GiB file read 2 GiB. The host's
+ * pre-flight reads only `x-file-size` and the 413, so `HEAD` skips the digest unless `hash=1` asks
+ * for it -- the header is then simply absent, which a caller cannot mistake for a wrong digest.
+ */
+async function serveFileDownload(req, res, url) {
+  const resolved = resolveTransferPath(url.searchParams.get('path'), DECLARED_TASK_DIR)
+  if (!resolved.ok) { jsonOut(res, 400, { ok: false, error: resolved.error }); return }
+
+  const info = await statTarget(resolved.path)
+  if (!info.exists || info.isDir) {
+    jsonOut(res, 404, {
+      ok: false,
+      error: info.isDir ? `${resolved.path} is a directory` : `${resolved.path} does not exist`,
+    })
+    return
+  }
+  // The same ceiling as `PUT`, applied to reads. It is not about this worker's disk -- it is about
+  // the master: a hard limit the receiving side sets is the only one that holds when the other side
+  // is a token someone else holds, and "over the limit" must be the same answer in both directions.
+  if (info.size > MAX_TRANSFER_BYTES) {
+    jsonOut(res, 413, {
+      ok: false,
+      error: `${resolved.path} is ${info.size} bytes, over the ${MAX_TRANSFER_BYTES}-byte ceiling (--max-transfer-bytes)`,
+      limit: MAX_TRANSFER_BYTES,
+    })
+    return
+  }
+
+  const range = rangeOf(info.size, url.searchParams.get('offset'))
+  if (!range.ok) { jsonOut(res, range.status, { ok: false, error: range.error }); return }
+
+  const started = Date.now()
+  // A `HEAD` that hashes the file is NOT a cheap probe: it reads every byte. The host's pre-flight
+  // needs two things -- the size, and whether the ceiling already refuses it -- so the digest is
+  // computed for `GET` (where the receiver verifies against it) and skipped for `HEAD` unless the
+  // caller explicitly asks with `hash=1`.
+  const wantsHash = req.method !== 'HEAD' || url.searchParams.get('hash') === '1'
+  const sha256 = wantsHash ? (await sha256File(resolved.path)).sha256 : ''
+  /** @type {Record<string,string>} */
+  const headers = {
+    // Deliberately generic: this is bytes, not an image or a document, and guessing a type would make
+    // some clients helpfully transform them.
+    'content-type': 'application/octet-stream',
+    'content-length': String(range.length),
+    'cache-control': 'no-store',
+    'x-file-size': String(info.size),
+    'x-file-path': resolved.path,
+    'x-file-mtime': info.mtime ?? '',
+    ...(wantsHash ? { 'x-file-sha256': sha256 } : {}),
+    'x-file-offset': String(range.offset),
+  }
+  if (range.contentRange !== undefined) headers['content-range'] = range.contentRange
+  res.writeHead(range.status, headers)
+  audit(req, 'download', `path=${resolved.path} offset=${range.offset} bytes=${range.length} sha256=${sha256 === '' ? 'not-requested' : sha256} ms=${Date.now() - started}`)
+
+  if (req.method === 'HEAD' || range.length === 0) { res.end(); return }
+  try {
+    // `end` is inclusive and only valid for a non-empty range, which the branch above guarantees.
+    await pipeline(createReadStream(resolved.path, { start: range.offset, end: info.size - 1 }), res)
+  } catch (error) {
+    // A client that hung up mid-download is the ordinary way a transfer is cancelled, and the master
+    // resumes with `offset=`. Nothing on disk changed, so this is a line, not a failure.
+    log(`download of ${resolved.path} interrupted: ${error.message}`)
+    res.destroy()
+  }
+}
+
+/**
+ * `PUT /file?path=<p>&offset=<n>`.
+ *
+ * No method check beyond the route table below: a chunk that arrives out of order is answered with the
+ * offset `.part` actually holds (see putChunk), which is what makes a retry after a dropped
+ * connection continue instead of restart.
+ */
+async function acceptFileChunk(req, res, url) {
+  const resolved = resolveTransferPath(url.searchParams.get('path'), DECLARED_TASK_DIR)
+  if (!resolved.ok) { jsonOut(res, 400, { ok: false, error: resolved.error }); return }
+
+  // A chunked body has no declared length, and the contract makes that a 411 rather than a guess:
+  // without it the receiver cannot tell a complete chunk from a truncated one, and the ceiling cannot
+  // be checked before the bytes are on disk.
+  const chunked = String(req.headers['transfer-encoding'] ?? '').toLowerCase().includes('chunked')
+  const started = Date.now()
+  const result = await putChunk({
+    target: resolved.path,
+    offset: url.searchParams.get('offset') ?? 0,
+    contentLength: chunked ? undefined : req.headers['content-length'],
+    body: req,
+    maxBytes: MAX_TRANSFER_BYTES,
+  })
+
+  if (result.aborted === true) {
+    // There is no client left to answer. `.part` keeps whatever arrived -- those bytes are the resume
+    // point -- and this line is the only record that the transfer stopped short.
+    audit(req, 'upload-interrupted', `path=${resolved.path} received=${result.received} ${result.json.error}`)
+    res.destroy()
+    return
+  }
+  audit(req, 'upload', `path=${resolved.path} offset=${result.json.offset} received=${result.json.received} partBytes=${result.json.partBytes} status=${result.status} ms=${Date.now() - started}`)
+  jsonOut(res, result.status, result.json)
+}
+
+/** `POST /file/commit` -- the only step that can publish a file under its real name. */
+async function acceptFileCommit(req, res) {
+  const parsed = await readJsonBody(req)
+  if (!parsed.ok) { jsonOut(res, parsed.status, parsed.json); return }
+
+  const resolved = resolveTransferPath(parsed.value.path, DECLARED_TASK_DIR)
+  if (!resolved.ok) { jsonOut(res, 400, { ok: false, error: resolved.error }); return }
+
+  const started = Date.now()
+  const result = await commitPart({
+    target: resolved.path,
+    sha256: parsed.value.sha256,
+    size: parsed.value.size,
+    overwrite: parsed.value.overwrite === true,
+  })
+  audit(req, 'commit', [
+    `path=${resolved.path}`,
+    `ok=${result.ok}`,
+    `bytes=${result.json.bytes ?? result.json.actualSize ?? 0}`,
+    `sha256=${result.json.sha256 ?? result.json.actual ?? ''}`,
+    `status=${result.status}`,
+    `ms=${Date.now() - started}`,
+  ].join(' '))
+  jsonOut(res, result.status, result.json)
+}
+
+/** `DELETE /file?path=<p>` -- drops the staging file and never the target. */
+async function dropFilePart(req, res, url) {
+  const resolved = resolveTransferPath(url.searchParams.get('path'), DECLARED_TASK_DIR)
+  if (!resolved.ok) { jsonOut(res, 400, { ok: false, error: resolved.error }); return }
+  const result = await deletePart(resolved.path)
+  audit(req, 'abort', `path=${resolved.path} removed=${result.json.removed} part=${result.json.part}`)
+  jsonOut(res, result.status, result.json)
+}
+
+/** The four `/file` endpoints, dispatched by path and method. */
+async function handleFileRequest(req, res, url) {
+  if (url.pathname === '/file/commit') {
+    if (req.method !== 'POST') {
+      res.setHeader('allow', 'POST')
+      jsonOut(res, 405, { ok: false, error: `${req.method} is not allowed on /file/commit` })
+      return
+    }
+    await acceptFileCommit(req, res)
+    return
+  }
+
+  switch (req.method) {
+    case 'GET':
+    case 'HEAD':
+      await serveFileDownload(req, res, url)
+      return
+    case 'PUT':
+      await acceptFileChunk(req, res, url)
+      return
+    case 'DELETE':
+      await dropFilePart(req, res, url)
+      return
+    default:
+      // Explicit, so a POST or PATCH to /file is a named refusal rather than the "/file" handler
+      // silently doing something it was not asked to do.
+      res.setHeader('allow', 'GET, HEAD, PUT, DELETE')
+      jsonOut(res, 405, { ok: false, error: `${req.method} is not allowed on /file` })
+  }
+}
+
+const server = createServer((req, res) => {
+  const url = (() => { try { return new URL(req.url, 'http://x') } catch { return undefined } })()
+
+  if (url !== undefined && url.pathname === '/healthz') {
+    res.writeHead(200, { 'content-type': 'application/json' })
+    res.end(JSON.stringify({
+      ok: true,
+      agent: LAUNCH.command,
+      auth: TOKEN !== '',
+      // The agent inherits THIS working directory, and dsh-base's sandbox-policy uses
+      // `process.cwd()` as its workspaceRoot. A launcher that leaves the cwd at
+      // C:\Windows\System32 therefore hands the sandbox System32 as the workspace, which
+      // breaks child process creation (pwsh dies with 0xC0000142 / STATUS_DLL_INIT_FAILED).
+      // Surfacing it here makes that misconfiguration visible instead of mysterious.
+      cwd: TASK_DIR,
+      // WHERE THAT DIRECTORY CAME FROM. `cwd` alone cannot distinguish "the operator armed this
+      // directory" from "the relay inherited whatever the DSH process had", and that ambiguity is what
+      // let a relative upload land in the profile directory while every surface reported success.
+      taskDirSource: TASK_DIR_SOURCE,
+      // The mode the child this relay spawns will actually run at, plus the mode this machine is
+      // configured for. A mismatch between the two is the F38 failure, and it is visible from either
+      // side without reading a file by hand.
+      ...healthModeState(),
+      pluginRpc: [`${PLUGIN_PREFIX}ping`, `${PLUGIN_PREFIX}selfcheck`, `${PLUGIN_PREFIX}screenshot`, `${PLUGIN_PREFIX}stat`, `${PLUGIN_PREFIX}list`],
+      http: ['/healthz', '/screenshot', '/file', '/file/commit'],
+      // A master that has just paired can see, before it tries anything, which byte ceiling this
+      // worker will hold it to -- the number a `413` would otherwise announce mid-transfer.
+      maxTransferBytes: MAX_TRANSFER_BYTES,
+    }))
+    return
+  }
+
+  // The PNG comes back here rather than inside the RPC result: base64 would inflate a
+  // multi-megabyte frame by a third and would have to pass through the ACP pump, which
+  // is there for small control messages.
+  if (url !== undefined && url.pathname === '/screenshot') {
+    if (!tokenOk(bearerOf(req))) {
+      res.writeHead(401, { 'content-type': 'application/json' })
+      res.end(JSON.stringify({ ok: false, error: 'unauthorized' }))
+      return
+    }
+    const fresh = url.searchParams.get('fresh') === '1'
+    const started = Date.now()
+    ;(async () => {
+      let shot = lastShot
+      if (fresh || shot === undefined) shot = lastShot = await captureScreenshot()
+      const body = readFileSync(shot.path)
+      res.writeHead(200, {
+        'content-type': 'image/png',
+        'content-length': String(body.length),
+        'cache-control': 'no-store',
+        // Headers rather than a JSON envelope so the response IS the image, which makes
+        // it usable with any HTTP client (and with a browser).
+        'x-shot-width': String(shot.width),
+        'x-shot-height': String(shot.height),
+        'x-shot-bytes': String(shot.bytes),
+        'x-shot-captured-at': shot.capturedAt,
+        'x-shot-displays': String(shot.displays.length),
+        'x-shot-ms': String(Date.now() - started),
+      })
+      res.end(body)
+    })().catch((error) => {
+      log(`/screenshot failed: ${error.message}`)
+      if (!res.headersSent) {
+        res.writeHead(500, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ ok: false, error: error.message }))
+      } else {
+        try { res.end() } catch { /* already sent */ }
+      }
+    })
+    return
+  }
+
+  // The transfer surface. One token check for all four endpoints, exactly as /screenshot does it, so
+  // a new endpoint cannot be added here without passing through the same gate.
+  if (url !== undefined && (url.pathname === '/file' || url.pathname === '/file/commit')) {
+    if (!tokenOk(bearerOf(req))) {
+      jsonOut(res, 401, { ok: false, error: 'unauthorized' })
+      return
+    }
+    handleFileRequest(req, res, url).catch((error) => {
+      // A throw from here is a local failure -- a disk that refused, a path that vanished mid-flight.
+      // It must be LOUD: answering 200 for a transfer that did not land is the silent-failure class
+      // this whole feature is built to avoid, and the master's commit check cannot catch what it was
+      // never told.
+      log(`/file failed: ${error?.stack ?? error}`)
+      if (!res.headersSent) jsonOut(res, 500, { ok: false, error: error instanceof Error ? error.message : String(error) })
+      else { try { res.end() } catch { /* already gone */ } }
+    })
+    return
+  }
+
+  res.writeHead(404); res.end('not found')
+})
+
+const wss = new WebSocketServer({ noServer: true })
+
+server.on('upgrade', (req, socket, head) => {
+  if (!tokenOk(bearerOf(req))) {
+    log('rejected: bad token from', req.socket.remoteAddress)
+    socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n')
+    socket.destroy()
+    return
+  }
+  wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req))
+})
+
+let connSeq = 0
+
+wss.on('connection', (ws, req) => {
+  const id = ++connSeq
+  log(`#${id} connected from ${req.socket.remoteAddress}`)
+
+  const child = spawn(LAUNCH.command, LAUNCH.args, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+    env: { ...process.env, ...LAUNCH.env },
+  })
+  log(`#${id} spawned pid=${child.pid}: ${LAUNCH.command} ${LAUNCH.args.join(' ')}`)
+
+  let childAlive = true
+  let stdoutBuf = ''
+  child.stdout.on('data', (chunk) => {
+    stdoutBuf += chunk.toString('utf8')
+    let nl
+    while ((nl = stdoutBuf.indexOf('\n')) >= 0) {
+      const line = stdoutBuf.slice(0, nl).replace(/\r$/, '')
+      stdoutBuf = stdoutBuf.slice(nl + 1)
+      if (line.trim() === '') continue
+      if (ws.readyState === ws.OPEN) { ws.send(line); vlog(`#${id} <- ${line.slice(0, 160)}`) }
+    }
+  })
+  child.stderr.on('data', (c) => log(`#${id} [stderr] ${c.toString('utf8').trim().slice(0, 400)}`))
+
+  let closed = false
+  const shutdown = (why) => {
+    if (closed) return
+    closed = true
+    childAlive = false
+    log(`#${id} shutdown: ${why}`)
+    try { child.stdin.end() } catch { /* already closed */ }
+    setTimeout(() => { try { child.kill() } catch { /* already gone */ } }, 500)
+    try { ws.close() } catch { /* already closed */ }
+  }
+
+  child.on('exit', (code, sig) => { log(`#${id} child exited code=${code} sig=${sig}`); shutdown('child exit') })
+  child.on('error', (e) => { log(`#${id} child error: ${e.message}`); shutdown('child error') })
+
+  ws.on('message', (data, isBinary) => {
+    // ACP's WebSocket transport is text-only; the SDK would silently drop a binary
+    // frame, so make it loud here instead (DESIGN §6.6).
+    if (isBinary) { log(`#${id} WARNING: binary frame dropped (ACP is text-only)`); return }
+    const text = data.toString('utf8')
+    for (const rawLine of text.split('\n')) {
+      const line = rawLine.replace(/\r$/, '')
+      if (line.trim() === '') continue
+
+      let msg
+      try { msg = JSON.parse(line) } catch {
+        log(`#${id} dropping unparseable frame: ${line.slice(0, 120)}`)
+        continue
+      }
+
+      if (typeof msg.method === 'string' && msg.method.startsWith(PLUGIN_PREFIX)) {
+        if (msg.id === undefined) { vlog(`#${id} plugin notification ${msg.method}`); continue }
+        void handleLocalRpc(msg).then((response) => {
+          if (response !== null && ws.readyState === ws.OPEN) {
+            ws.send(JSON.stringify(response))
+            vlog(`#${id} plugin reply -> ${JSON.stringify(response).slice(0, 200)}`)
+          }
+        })
+        continue
+      }
+
+      if (!childAlive) { log(`#${id} dropping ACP frame: child is gone`); continue }
+      try { child.stdin.write(line + '\n'); vlog(`#${id} -> ${line.slice(0, 160)}`) }
+      catch (e) { log(`#${id} write to child failed: ${e.message}`); shutdown('write failed'); return }
+    }
+  })
+
+  ws.on('close', () => shutdown('ws closed'))
+  ws.on('error', (e) => { log(`#${id} ws error: ${e.message}`); shutdown('ws error') })
+})
+
+server.listen(PORT, HOST, () => {
+  log(`listening on ${HOST}:${PORT}  (health: GET /healthz)`)
+  log(`agent: ${LAUNCH.command}`)
+  log(`       ${LAUNCH.args.join(' ')}`)
+  log(`self-check script: ${SELFCHECK_SCRIPT} (cache ${SELFCHECK_CACHE_MS}ms)`)
+  // Printed because it is the one setting that turns a working transfer into a 413 at an arbitrary
+  // byte, and the operator's only other clue is that status code.
+  log(`file transfer: task dir ${TASK_DIR} (from ${TASK_DIR_SOURCE}), ceiling ${MAX_TRANSFER_BYTES} bytes`)
+  if (TOKEN === '') log('WARNING: auth disabled')
+  // Leave the pairing string where an operator can find it. It is written on every start so it
+  // cannot go stale against a rotated token -- a pairing string with the OLD token fails with
+  // an authentication error that looks like a network problem.
+  //
+  // `--pairing-file ''` skips this entirely, which is what the plugin does: it spawns this relay
+  // from inside the plugin's own directory, and a relay that wrote next to itself would have an
+  // installed plugin modifying its installation.
+  const pairing = PAIRING_FILE === '' ? '' : pairingString()
+  if (PAIRING_FILE === '') {
+    // Nothing to do, and deliberately not logged as a problem.
+  } else if (pairing === '') {
+    log('no pairing string: this relay has no token, so a pairing string would pair a master with an unauthenticated worker')
+  } else {
+    try {
+      writeFileSync(PAIRING_FILE, `${pairing}\n`, { encoding: 'utf8', mode: 0o600 })
+      log(`pairing string written to ${PAIRING_FILE}  (${advertisableHost()}:${PORT})`)
+    } catch (error) {
+      // Not fatal: `--print-pairing` covers the case where the file cannot be written.
+      log(`could not write ${PAIRING_FILE}: ${error instanceof Error ? error.message : String(error)}`)
+      log('run the relay with --print-pairing to get the string instead')
+    }
+  }
+})