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

package/lib/index.js

@@ -0,0 +1,2207 @@
+/**
+ * Host half of dsh-plugin-remote-use.
+ *
+ * Assembles the pieces that let the master drive a paired LAN worker as if it were
+ * a subagent:
+ *
+ *   model --> tool `subagent_remote`  (a normal `dsh-tool-subagent` row)
+ *               --> RemoteProvider    (implements DSH's SubagentProvider seam)
+ *                     --> AcpBridge   (ACP over WebSocket)
+ *                           --> worker relay --> worker `dsh --profile acp`
+ *
+ * NOTHING IN DSH IS MODIFIED: the seam is the published `ctx.subagents` provider
+ * registry, and the control tools are ordinary `ctx.tools` registrations.
+ *
+ * CONFIG MUST BE SCHEMASTERY, NOT ZOD: dsh-app-boot only recognises a Config whose
+ * schema carries `Symbol.for("schemastery") === true`; a zod schema makes the
+ * package report `status: "unsupported"` to `Config.listConfigs`, so the Settings
+ * page cannot render its form (DESIGN §12.2).
+ *
+ * @module dsh-plugin-remote-use
+ */
+
+// NOTE: `@deepseek-ai/schemastery` is deliberately NOT a static import here -- see the
+// defensive resolution below for why a missing schema must not abort the module.
+import { AcpBridge } from './bridge/acp-bridge.js'
+import { PeerConnection, httpBaseOf } from './bridge/peer-connection.js'
+import { TaskRegistry } from './core/task-registry.js'
+import { ToolCallCache } from './core/toolcall-cache.js'
+import { TaskMemory } from './core/task-memory.js'
+import { assertUsableCwd } from './core/task-cwd.js'
+import { OPTION, decideApproval, inferRequiredTier } from './core/review-engine.js'
+import { ApprovalQueue, QUEUE_LEAD_MS } from './core/approval-queue.js'
+import { notifyDesktop, loggerMethods } from './core/desktop-notify.js'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { networkInterfaces } from 'node:os'
+import { AuditLog } from './core/audit-log.js'
+import { WorkerArming } from './core/worker-arming.js'
+import { RelaySupervisor } from './core/relay-supervisor.js'
+import { probeSandbox } from './core/sandbox-probe.js'
+import { diagnoseSandbox } from './core/sandbox-diagnosis.js'
+import { parseWorkerModel, writeWorkerModelOverlay } from './core/acp-model-overlay.js'
+import { runSelfcheck, summarizeReport } from './core/selfcheck-runner.js'
+import { buildEnvironmentPrompt } from './core/environment-prompt.js'
+import { resolveAcpLaunchSpec } from './core/self-acp-spec.js'
+// Decoding lives with the relay that encodes, so the two can never disagree about the format.
+import { decodePairing, deriveWorkerId, describePairing } from '../slave/pairing.mjs'
+import {
+  mergeSettings,
+  normalizeWorker,
+  publicWorker,
+  readSettings,
+  removeWorker as removeWorkerFromList,
+  resolveDshHome,
+  upsertWorker,
+  writeSettings,
+} from './core/settings-store.js'
+import { RemoteProvider } from './provider/remote-provider.js'
+import { limitDiagnostic, verifyAgainstUpstream } from './provider/out-of-process-helpers.js'
+import { makeRemoteTools } from './tools/remote-tools.js'
+
+// NOT the package name, deliberately. This value is only the label DSH gives the plugin's fiber
+// (`ctx.registry.plugin(...)`), and the convention across DSH's own first-party bundles is the
+// SCOPE-STRIPPED name: @deepseek-ai/dsh-client-hmr exports `name = "client-hmr"`. Two of this
+// operator's plugins that run correctly in a live profile do the same
+// (`@hope_phenom/dsh-plugin-code-quality` exports `dsh-plugin-code-quality`). The loader does NOT
+// key anything on it -- unlike the client registration id in lib/client.js, which MUST equal the
+// package name and is the one that actually broke the Web UI.
+export const name = 'dsh-plugin-remote-use'
+
+/** Optional services: stay inert in profiles that lack them. */
+export const inject = ['subagents', 'tools', 'systemPrompt']
+
+/**
+ * Resolve `@deepseek-ai/schemastery` defensively.
+ *
+ * WHY THIS IS NOT A STATIC IMPORT: the host is expected to intercept `@deepseek-ai/*`
+ * for third-party plugins (that is why `dsh-cost-meter` can list `@deepseek-ai/dsh-credentials`
+ * as a peer dependency). But this plugin is linked into the profile, and Node resolves
+ * modules through the package's REAL path — `profiles/node_modules/@deepseek-ai/schemastery`
+ * is not necessarily on that path, and on this machine it is one of the 482 dangling
+ * junctions left by an old npm install. A failed static import would abort the whole
+ * module, so the plugin would not load at all.
+ *
+ * Falling back to a plain object costs only the Settings-page form: dsh-app-boot marks a
+ * non-Schemastery `Config` as `unsupported`, and configuration still arrives from the
+ * patch layer, which is where worker entries are written anyway.
+ */
+const SCHEMA_UNAVAILABLE = 'SCHEMA_UNAVAILABLE'
+let Schema = null
+try {
+  Schema = (await import('@deepseek-ai/schemastery')).default ?? null
+} catch (error) {
+  console.warn(`[remote-use] @deepseek-ai/schemastery not importable (${error instanceof Error ? error.message : String(error)}); `
+    + 'falling back to a plain Config object. Workers must be configured through the profile patch layer, '
+    + 'and the Settings page will not render a form for this plugin.')
+}
+
+/** The default worker shape, shared by the schema and the fallback. */
+const WORKER_DEFAULTS = {
+  name: '',
+  token: '',
+  enabled: true,
+  serialQueue: 1,
+}
+
+/**
+ * Tools this plugin owns — the exact set the per-session gate acts on.
+ *
+ * Listed literally rather than derived from `makeRemoteTools()` so the gate cannot silently
+ * widen if that function ever grows a tool: a new tool would appear in the list only after
+ * someone adds it here, and until then the guard would refuse it (fail-closed).
+ */
+export const REMOTE_TOOL_NAMES = Object.freeze([
+  'remote_agents',
+  'remote_interrupt',
+  'remote_selfcheck',
+  'remote_screenshot',
+  // Moves files across the same paired link the rest of these use. It rides the relay's HTTP surface
+  // rather than the ACP session, so a copy neither waits for the worker's GUI slot nor is governed by
+  // its session sandbox mode -- see DESIGN's transfer section for why that is deliberate.
+  'remote_file',
+  // The delegation entry point. It is in this list for the same reason as the others: the list
+  // drives BOTH the per-session deny mask (hides these tools from a session that has not run
+  // `/remote-use on`) and the fail-closed execution guard. Registering a remote tool without
+  // listing it here would leave it visible AND callable in a session that never asked for remote
+  // work -- proven by mutation: removing this line fails four guards.
+  'remote_subagent',
+])
+
+/** The slash command that switches remote work on and off for one session. */
+export const ENABLE_COMMAND = 'remote-use'
+
+/**
+ * Injected only while a session has remote work switched ON.
+ *
+ * WHY THIS EXISTS AT ALL: enabling the plugin registers the delegation tools, but nothing in
+ * DSH tells the parent agent *when* delegating is appropriate -- the tool description is
+ * generic ("delegate a self-contained task to a subagent"), and DSH's own
+ * `SUBAGENT_DELEGATION` context is addressed to the CHILD, not to the delegating agent.
+ * Without a policy the model has no way to know that this worker is for GUI verification and
+ * not a second development machine.
+ *
+ * Placed at TEAM_POLICY order so the rule is read BEFORE the tool guidance it qualifies,
+ * which is the same placement rationale `dsh-tools` gives for its PTC-only statement.
+ */
+export const DEFAULT_DELEGATION_POLICY = [
+  '## Remote LAN workers (enabled for this session)',
+  '',
+  'A paired worker is available. It exists for GUI verification and testing on a second',
+  'machine, because GUI automation takes over the mouse, keyboard and focus of whichever',
+  'machine runs it.',
+  '',
+  '- Do all code editing, file changes, builds, dependency installs and repository work HERE.',
+  '- Delegate ONLY what needs a real desktop: launching and driving the target application,',
+  '  confirming what the interface shows, reproducing something that only happens on a real',
+  '  display.',
+  '- Do NOT develop on a worker. It cannot see this workspace, so anything written there does',
+  '  not come back.',
+  '',
+  'Call remote_selfcheck before delegating (a worker that fails its readiness check is',
+  'refused by the dispatch gate). Use remote_agents to watch progress, remote_screenshot to',
+  'look at the worker screen, and remote_interrupt to stop a task.',
+].join('\n')
+
+/**
+ * Plugin configuration.
+ *
+ * A worker entry needs the relay's address and shared secret. `cwd` is the worker-side
+ * absolute path a task runs in — it must exist on the worker and is also what the
+ * sandbox scopes writes to.
+ */
+export const Config = Schema !== null
+  ? Schema.object({
+    workers: Schema.array(Schema.object({
+      id: Schema.string().required(),
+      name: Schema.string().default(''),
+      url: Schema.string().required(),
+      token: Schema.string().default(''),
+      cwd: Schema.string().required(),
+      enabled: Schema.boolean().default(true),
+      /** Per-worker serial concurrency. GUI is an exclusive resource: 1. */
+      serialQueue: Schema.number().default(1),
+    })).default([]),
+    approvalTimeoutMs: Schema.number().default(180_000),
+    /** Tier a task needs unless the delegation narrows it. */
+    requiredTier: Schema.string().default('workspace-write'),
+    /** Prefix a remote tool's name; one row per worker uses `<toolPrefix>` + worker id. */
+    toolPrefix: Schema.string().default('subagent_remote'),
+    injectTaskSummary: Schema.boolean().default(true),
+    /** Liveness probe interval per worker, in ms. 0 disables it. */
+    heartbeatMs: Schema.number().default(15000),
+    /**
+     * How long a page load may spend probing readiness before it answers without a report.
+     * Raise it for a slow link; the page renders immediately either way.
+     */
+    reportBudgetMs: Schema.number().default(4000),
+    /** How long the page's explicit "re-check now" may spend. */
+    selfcheckBudgetMs: Schema.number().default(25000),
+    /**
+     * How many screenshots to keep on disk PER WORKER, newest first.
+     *
+     * A worker screenshot is a full-resolution PNG -- ~9.5 MB measured on the reference
+     * worker -- and every capture used to be kept forever. Set 0 to keep none, or a negative
+     * number to disable pruning entirely (for an operator who archives them elsewhere).
+     */
+    keepShots: Schema.number().default(20),
+    /**
+     * Byte ceiling for the screenshots this HOST keeps per worker, and for the ones the worker
+     * keeps in its own shot directory.
+     *
+     * WHY A SECOND BUDGET: the count above bounds the NUMBER of captures, not the disk they take.
+     * Measured 2026-10-15: the host's screenshot directory had reached 218 MB over 30 captures
+     * while `keepShots` was 20 -- the setting looked like a disk bound and was not one. The
+     * operator's actual question is "how much space is this using", so the answer needs a byte
+     * number. Both budgets apply; whichever bites first wins.
+     *
+     * 0 (the default) means NO byte budget, deliberately: an install that upgrades into a byte
+     * ceiling would start deleting captures the operator never agreed to lose. Negative is
+     * treated the same as 0, so a typo can never widen deletion.
+     */
+    shotCacheBytes: Schema.number().default(0),
+    /**
+     * The sandbox mode THIS machine's remote sessions run under, written into the launch spec when
+     * the worker role is armed.
+     *
+     * WHY IT DEFAULTS TO FULL ACCESS: a GUI workflow is many calls, and the failure that keeps it
+     * from starting under a confined token -- `0xC0000142` from a GUI-subsystem child -- is SILENT:
+     * the command returns success, no denial is reported, and the only trace is a dialog on someone's
+     * desktop (PITFALLS F21/F33). A decision that cannot be seen cannot be escalated, so it must not
+     * be left to a per-call judgement. Measured: with the same evidence, one run judged that failure
+     * "a denial" and requested a wider tier, another judged it "environmental" and refused -- a
+     * decision that flips is not a decision.
+     *
+     * It is a DEPLOYMENT value, not a runtime one: it is read when the spec is generated, and a
+     * change governs the next arming. Set `workspace-write` for a worker that only runs confined
+     * work; unknown values are refused when the spec is built rather than silently coerced.
+     */
+    workerSessionMode: Schema.string().default('danger-full-access'),
+    /**
+     * The model this machine's ACP sessions run with, as `provider/model`.
+     *
+     * WHY IT IS A DEPLOYMENT VALUE AND NOT A PER-CALL PARAMETER: `dsh-acp` advertises
+     * `promptCapabilities.image` at `initialize` from the CONFIGURED route, and fixes it for the
+     * connection. A per-session `session/set_config_option` changes the route but not the
+     * advertised capability, so images stay refused. A wrong or missing id therefore disables
+     * image input silently -- both for prompts the master sends and for `read_image` inside the
+     * worker's own agent (DESIGN 14.1).
+     *
+     * Empty means "whatever the `acp` profile configures" (the pre-0.2.24 behaviour). A value here
+     * is applied by a plugin-owned `--patch` overlay at launch, so the operator's profile is not
+     * touched; see `core/acp-model-overlay.js`.
+     */
+    workerModel: Schema.string().default(''),
+    /**
+     * The largest single file the transfer tools will move, in either direction.
+     *
+     * WHY THERE ARE TWO CEILINGS: this one is the HOST's policy and it is checked BEFORE anything is
+     * sent (a `stat`/`HEAD` pre-flight), so an oversized transfer is refused early instead of eating
+     * a disk first. The relay carries its own hard `--max-transfer-bytes`, because this value lives in
+     * the master's config and a worker must not depend on a remote machine's politeness.
+     *
+     * DELIBERATELY NOT ON THE SETTINGS PAGE. Every page-editable key has to be registered in four
+     * places (schema, save route, MANAGED_KEYS, currentSettings) and each omission fails silently --
+     * see PITFALLS F37. These are deployment constants an operator sets once in YAML, so they stay
+     * out of that blast radius.
+     */
+    transferMaxBytes: Schema.number().default(8 * 1024 * 1024 * 1024),
+    /**
+     * How much of a file travels per HTTP request, and therefore the resume granularity.
+     *
+     * 4 MiB is the compromise: large enough that a 1 GiB transfer is ~256 requests rather than
+     * thousands, small enough that a dropped connection costs at most one chunk of re-sending.
+     */
+    transferChunkBytes: Schema.number().default(4 * 1024 * 1024),
+    /**
+     * Rotate the audit trail once the live file reaches this many bytes.
+     *
+     * The trail is append-only, so nothing stops it growing; without a cap it grows for as long as
+     * the plugin is installed. At the measured ~670 bytes a row this is years of ordinary use.
+     * Set 0 (or negative) to disable rotation and keep everything.
+     */
+    auditMaxBytes: Schema.number().default(8 * 1024 * 1024),
+    /**
+     * How many rotated audit files to keep beside the live one. The oldest beyond this is deleted.
+     * Negative keeps every archive (bounded growth is then the operator's business, not ours).
+     */
+    auditKeepFiles: Schema.number().default(5),
+    /**
+     * The division-of-labour policy injected while a session has remote work switched on.
+     * Empty string disables the injection entirely (the tools are still gated).
+     */
+    delegationPolicy: Schema.string().default(DEFAULT_DELEGATION_POLICY),
+  })
+  : {
+    // Rendered as "unsupported" in the Settings page; `normalizeConfig` applies the very
+    // same defaults, so behaviour is identical for a patch-configured install.
+    [SCHEMA_UNAVAILABLE]: true,
+    workers: [],
+    approvalTimeoutMs: 180_000,
+    requiredTier: 'workspace-write',
+    toolPrefix: 'subagent_remote',
+    injectTaskSummary: true,
+    heartbeatMs: 15_000,
+    reportBudgetMs: 4_000,
+    selfcheckBudgetMs: 25_000,
+    keepShots: 20,
+    // No byte budget by default -- see the schema note: a ceiling that appeared on upgrade would
+    // delete captures nobody agreed to lose.
+    shotCacheBytes: 0,
+    // The deployment default for a remote session, and the reason is in the schema above: the GUI
+    // failure it prevents is silent, so it cannot be left to a per-call decision.
+    workerSessionMode: 'danger-full-access',
+    // Empty means "leave the acp profile's model alone" -- the pre-0.2.24 behaviour.
+    workerModel: '',
+    transferMaxBytes: 8 * 1024 * 1024 * 1024,
+    transferChunkBytes: 4 * 1024 * 1024,
+    auditMaxBytes: 8 * 1024 * 1024,
+    auditKeepFiles: 5,
+    delegationPolicy: DEFAULT_DELEGATION_POLICY,
+    _defaults: WORKER_DEFAULTS,
+  }
+
+/**
+ * Plugin body.
+ *
+ * Every registration goes through `ctx.effect`/`ctx.on` so disabling the plugin
+ * releases all of it, including the subagent providers and the tool rows.
+ *
+ * @param {object} ctx
+ * @param {ReturnType<typeof Config>} config
+ */
+export function apply(ctx, config) {
+  const log = makeLogger(ctx)
+  // The settings file is the page's storage and takes precedence over the profile patch for
+  // the keys it contains. Absent (the usual case) it changes nothing.
+  const stored = readSettings()
+  if (stored.error !== '') log.warn(`settings file ignored: ${stored.error}`)
+  const merged = mergeSettings(normalizeConfig(config), stored.settings)
+  let cfg = merged.config
+  if (stored.settings !== null) {
+    log.info(`settings file applies: ${Object.entries(merged.sources).filter(([, s]) => s === 'settings').map(([k]) => k).join(', ') || 'nothing'}`)
+  }
+  const registry = new TaskRegistry({})
+
+  // A single shared cache keyed by `${workerId}:${toolCallId}`; approvals arrive with
+  // only a tool call id, so this is the ONLY source of a tool's name and arguments
+  // (DESIGN §10.0.1).
+  const cache = new ToolCallCache({ maxEntries: 1024 })
+  /** @type {Map<string, object>} */
+  const peers = new Map()
+  /**
+   * Per-worker teardown, so the page can re-pair without a restart.
+   *
+   * `ctx.effect` returns its own disposer, so wiring can be undone on demand rather than
+   * only when the fiber dies. Before this existed, changing a worker meant editing YAML and
+   * restarting DSH -- which is exactly the friction the settings page is meant to remove.
+   * @type {Map<string, () => unknown>}
+   */
+  const unwire = new Map()
+
+  /**
+   * The audit trail and the human-approval queue are PLUGIN-level, not per worker.
+   *
+   * A request waiting for a person concerns the plugin as a whole, and a trail that began
+   * afresh for each worker would not be a trail. Both outlive `reconfigure`, which only ever
+   * diffs connections.
+   */
+  const audit = new AuditLog({
+    log: (level, message) => log[level](message),
+    // Bounded on purpose: an append-only file has no natural stopping point, so an uncapped trail
+    // grows for as long as the plugin is installed (see `auditMaxBytes`).
+    maxBytes: cfg.auditMaxBytes,
+    keepFiles: cfg.auditKeepFiles,
+  })
+  const queue = new ApprovalQueue({
+    // Settle just before the bridge's own timeout, so the outcome the queue records is the
+    // one the worker actually received. If the queue were the slower of the two, the bridge
+    // would reject first and the page would keep a ghost entry nobody could act on.
+    timeoutMs: Math.max(1_000, cfg.approvalTimeoutMs - QUEUE_LEAD_MS),
+    onSettle: (outcome) => {
+      // `gate` says WHICH gate handled it; `by` says who was behind it. They differ for a
+      // timeout: nobody answered, so calling that a human gate is how a silent refusal read as a
+      // human decision in the trail.
+      const noAnswer = outcome.by === 'timeout' || outcome.by === 'disposed' || outcome.by === 'no-answerer'
+      audit.record({ kind: 'approval', gate: noAnswer ? 'timeout' : 'human', ...outcome })
+      log.info(`approval ${outcome.toolCallId} tool=${outcome.toolName} `
+        + `required=${outcome.requiredTier} -> ${outcome.optionId} (gate=${noAnswer ? 'timeout' : 'human'} by=${outcome.by}) `
+        + `waited=${outcome.waitedMs}ms`)
+    },
+  })
+  // Refuse anything still waiting when the plugin unloads, rather than leaving the worker
+  // blocked until its bridge timeout.
+  ctx.effect(() => () => queue.dispose())
+
+  /**
+   * The worker role: this machine accepting remote execution.
+   *
+   * Created here rather than lazily because the page must be able to REPORT the state on first
+   * load. An operator who cannot see whether a listener is open has no way to tell whether they
+   * left one open.
+   *
+   * The supervisor is handed in as `start`/`stop` so the state machine owns the decisions and the
+   * listener owns none -- see `core/worker-arming.js`.
+   */
+  const acpProfile = join(resolveDshHome(), 'profiles', 'acp', 'cordis.patch.yml')
+  /**
+   * Read-only diagnosis of the sandbox mediator, computed on demand.
+   *
+   * WHY IT IS SEPARATE FROM THE PROBE, AND WHY IT RUNS AT PAGE LOAD: the probe answers "does
+   * confinement work", but it only runs when somebody clicks Check -- so a machine whose mediator
+   * directory had been removed kept showing nothing at all, and was discovered only when arming
+   * was attempted (measured 2026-11-04, PITFALLS F44). This answers the cheaper question
+   * ("are the artifacts even there") on every page load and hands back the exact command that
+   * fixes it. It writes nothing and spawns nothing: the fix has to be run by a person or an agent,
+   * because it writes outside this plugin's own state.
+   */
+  const sandboxReport = () => diagnoseSandbox({ env: process.env })
+  /**
+   * The worker-model overlay, written on demand and passed to the ACP child as `--patch`.
+   *
+   * Written when the launch spec is built (arm or restore), so the value that reaches the child is
+   * the one on disk at that moment. A failure to write THROWS: launching without the requested
+   * model would silently turn image capability off, which is the defect this exists to prevent.
+   */
+  const modelPatchFiles = () => {
+    const parsed = parseWorkerModel(cfg.workerModel)
+    if (parsed.ok !== true) {
+      throw new Error(`workerModel "${cfg.workerModel}" is not "provider/model": ${parsed.reason}`)
+    }
+    if (parsed.provider === '') return []
+    const written = writeWorkerModelOverlay({ home: resolveDshHome(), value: cfg.workerModel })
+    if (written.ok !== true) throw new Error(`could not write the worker model overlay: ${written.reason}`)
+    return [written.path]
+  }
+  /**
+   * Validate the configured model against this machine's catalogue, before arming.
+   *
+   * Resolving the id here turns a typo from "images silently off" into a refusal. The catalogue
+   * lives in `llm`; when that service is absent (a stripped deployment) the value is accepted with
+   * a warning rather than refused, because the plugin cannot verify it and the ACP child will
+   * still apply it.
+   *
+   * @returns {Promise<{ ok: boolean, warning: string, error: string }>}
+   */
+  const validateWorkerModel = async () => {
+    const parsed = parseWorkerModel(cfg.workerModel)
+    if (parsed.ok !== true) {
+      return { ok: false, warning: '', error: `workerModel "${cfg.workerModel}" is not "provider/model": ${parsed.reason}` }
+    }
+    if (parsed.provider === '') return { ok: true, warning: '', error: '' }
+    const llm = typeof ctx.get === 'function' ? ctx.get('llm') : undefined
+    if (llm === undefined || typeof llm.resolveModelInfo !== 'function') {
+      return { ok: true, warning: 'the model catalogue is not available here, so the model id was not verified', error: '' }
+    }
+    try {
+      const info = await llm.resolveModelInfo(parsed.provider, parsed.model)
+      const images = Array.isArray(info?.inputModalities) && info.inputModalities.includes('image')
+      return images
+        ? { ok: true, warning: '', error: '' }
+        : { ok: true, warning: `model ${parsed.provider}/${parsed.model} does not declare image input; the master cannot send images to this worker`, error: '' }
+    } catch (error) {
+      return {
+        ok: false,
+        warning: '',
+        error: `the model ${parsed.provider}/${parsed.model} could not be resolved: ${error instanceof Error ? error.message : String(error)}`,
+      }
+    }
+  }
+  /**
+   * Run the worker's OWN readiness self-check, here, on the worker.
+   *
+   * WHY THE WORKER RUNS IT: S1-S12 are facts about THIS machine's session, display and input; the
+   * master can only read the report. Running it in the plugin host means the result reflects the
+   * same interactive session the relay uses, and the operator gets a machine-specific fix prompt
+   * without a round trip.
+   *
+   * WHY IT IS NOT AN ARMING GATE: the session checks depend on somebody being logged in and
+   * unlocked -- an operational state, not a fault -- and S8 moves the mouse. So it runs only when
+   * the page asks for it (the "先检查" button) and it is ADVISORY; the master's dispatch gate
+   * remains the hard gate.
+   */
+  const selfcheckScript = fileURLToPath(new URL('../slave/selfcheck.ps1', import.meta.url))
+  let lastReadiness = null
+  const runReadinessCheck = async ({ taskCwd } = {}) => {
+    const workspace = String(taskCwd ?? '').trim()
+    const run = await runSelfcheck({ scriptPath: selfcheckScript, workspace })
+    const prompt = buildEnvironmentPrompt({
+      report: run.ok === true ? run.report : null,
+      reason: run.ok === true ? '' : run.reason,
+      facts: {
+        scriptPath: selfcheckScript,
+        home: resolveDshHome(),
+        taskCwd: workspace,
+        pluginDir: dirname(dirname(selfcheckScript)),
+      },
+    })
+    if (run.ok !== true) return { ok: false, reason: run.reason, prompt }
+    return { ok: true, ...summarizeReport(run.report), prompt }
+  }
+  const supervisor = new RelaySupervisor({
+    log: { info: (m) => log.info(m), warn: (m) => log.warn(m), error: (m) => log.error(m) },
+    // Read at start time, so a change on the settings page governs the next arming.
+    keepShots: () => cfg.keepShots,
+    // The byte budget travels too, so the WORKER's own shot directory is bounded the same way the
+    // host's is. Without this the page's threshold would govern only the host's copies, and the
+    // larger accumulation -- the one on the worker, which nothing else ever swept -- would be the
+    // one the operator could not control. That asymmetry is exactly what the 218 MB incident was.
+    shotCacheBytes: () => cfg.shotCacheBytes,
+    launchSpec: () => resolveAcpLaunchSpec({ profile: 'acp', permissionMode: cfg.workerSessionMode, patchFiles: modelPatchFiles() }),
+    // The task directory is NOT read through a closure here. `WorkerArming` passes it explicitly
+    // to `start()`, because a restore calls `start()` while `arming` is still being constructed --
+    // a closure referring to it would throw "Cannot access 'arming' before initialization". The
+    // value is still the SAME one the pairing string advertises, so the master and the relay cannot
+    // disagree about it.
+  })
+  const arming = new WorkerArming({
+    interfaces: () => networkInterfaces(),
+    // The WORKER runs under the acp profile, so that is the profile whose sandbox has to
+    // contain -- not the desktop one the interactive session uses. Checking the wrong file
+    // would pass on a machine whose remote execution is unconfined.
+    probe: () => probeSandbox({ profile: acpProfile }),
+    start: (bindAddress, port, token, taskCwd) => supervisor.start(bindAddress, port, token, taskCwd),
+    stop: () => supervisor.stop(),
+    // The page shows the configured mode beside the mode the RUNNING listener was started with.
+    // Without this the two can disagree with no surface saying so -- the defect this change fixes.
+    listenerStatus: () => supervisor.status(),
+    // Persisted through the same settings path as everything else, so it survives a restart and
+    // appears in the documented precedence order.
+    persist: (state) => { persistSettings({ ...currentSettings(), workerRole: state }) },
+    log: { info: (m) => log.info(m), warn: (m) => log.warn(m) },
+    stored: cfg.workerRole,
+  })
+  // Stop the listener on unload WITHOUT persisting: a teardown write would clear the stored
+  // credential and silently invalidate a pairing the operator had already distributed.
+  ctx.effect(() => () => { supervisor.stop() })
+
+  /**
+   * Configured versus effective session mode, for the page.
+   *
+   * `workerSessionMode` is a deployment value: the spec is written when the worker role is armed.
+   * Changing it while a listener runs therefore does NOT change that listener, and the old page only
+   * showed the configured value -- so "I set it to full access" and "it is still running
+   * workspace-write" looked identical from here (PITFALLS F38/F41).
+   */
+  function workerSessionStatus() {
+    const listener = supervisor.status()
+    const running = listener.running === true
+    const rawEffective = running && typeof listener.sessionMode === 'string' ? listener.sessionMode : ''
+    // An empty spec value means dsh-base's own default. Resolving it here is what lets a
+    // `workspace-write` setting match a listener whose spec omits the variable.
+    const effective = running ? (rawEffective === '' ? 'workspace-write' : rawEffective) : ''
+    const configured = cfg.workerSessionMode
+    return {
+      configured,
+      effective,
+      effectiveFrom: running ? listener.sessionModeFrom : 'nothing',
+      running,
+      armed: arming.status().armed,
+      // A stopped listener is not stale: the next arming builds a fresh spec from the setting.
+      reArmRequired: running && effective !== configured,
+      settingsFile: stored.file,
+    }
+  }
+
+  // Validate our frozen capability mirror against the live package. A mismatch means
+  // DSH changed the contract and our advertisement is no longer honest.
+  void verifyAgainstUpstream().then((r) => {
+    if (!r.ok) {
+      log.error('capability mirror does not match @deepseek-ai/dsh-subagent: ' + (r.reason ?? 'unknown')
+        + ' -- refusing to advertise capabilities until this is reconciled')
+    } else if (r.reason !== undefined) {
+      log.info('capability mirror not verified: ' + r.reason)
+    }
+  })
+
+  // ---- per-worker wiring -------------------------------------------------
+  /**
+   * Bring one worker online: build its connection, publish its runtime, and register its
+   * subagent provider. Undone by the disposer recorded in `unwire`.
+   */
+  function wire(worker) {
+    const peerId = worker.id
+    /**
+     * Task memory is PER WORKER, not shared.
+     *
+     * It used to be one map keyed by taskId whose teardown did `memories.clear()`. That was
+     * harmless only because a worker was never removed at runtime; with live re-pairing it
+     * would wipe every OTHER worker's approval memory, making the review engine forget
+     * decisions it had already made. Per-worker ownership removes the footgun structurally.
+     * @type {Map<string, TaskMemory>}
+     */
+    const memories = new Map()
+
+    // The connection is LAZY: nothing connects until something needs the worker. An
+    // eager connect at load time would fail whenever the worker is off or still booting,
+    // and there is no useful moment to retry from. PeerConnection owns the bridge's
+    // lifecycle so a dead link is rebuilt rather than reused.
+    const connection = new PeerConnection({
+      peerId,
+      log: (level, message) => log[level === 'error' ? 'error' : level === 'warn' ? 'warn' : 'info'](message),
+      // Binary payloads (screenshots) come from the relay's HTTP side, not through the ACP
+      // message pump. Derived from the same URL so there is one thing to configure.
+      httpBase: httpBaseOf(worker.url),
+      token: worker.token,
+      // Probe the link periodically so a relay restart is noticed between calls instead of
+      // failing the next one. 0 disables probing.
+      heartbeatMs: cfg.heartbeatMs,
+      keepShots: cfg.keepShots,
+      // The host-side byte ceiling. Captured at construction like `keepShots`, which is why
+      // `policyStamp` includes it: a connection that kept the old ceiling would enforce a budget
+      // the page no longer shows.
+      shotCacheBytes: cfg.shotCacheBytes,
+      // The two transfer ceilings go to the CONNECTION as well as to the tool. The tool passes them
+      // per call, so a direct `connection.sendFile` (or any future caller) would otherwise fall back
+      // to the connection's own defaults and quietly ignore what the operator configured -- a setting
+      // honoured on one path and not the other is the F32 shape.
+      transferMaxBytes: cfg.transferMaxBytes,
+      transferChunkBytes: cfg.transferChunkBytes,
+      createBridge: () => new AcpBridge({
+        url: worker.url,
+        token: worker.token,
+        approvalTimeoutMs: cfg.approvalTimeoutMs,
+        // Explicit mapping rather than passing the event payload straight through: the
+        // cache's contract keys off `title` (which IS the tool name in DSH), and a shape
+        // mismatch here would silently cache `toolName: undefined`, which in turn makes
+        // `allowedTools` never match and leaves the audit trail without a tool name.
+        onUpdate: (evt) => {
+          if (evt.tool === undefined) return
+          const entry = { title: evt.tool.toolName, rawInput: evt.tool.rawInput, status: evt.tool.status }
+          if (evt.kind === 'tool_call') cache.note(evt.tool.toolCallId, entry)
+          else if (evt.kind === 'tool_call_update') cache.update(evt.tool.toolCallId, entry)
+        },
+        // Constructor-level fallback. `RemoteProvider` passes a per-task decider to
+        // `startTask`, and that one wins when present; this keeps the bridge honest if some
+        // other caller uses the bridge without one.
+        //
+        // ⚠️ The decider is ADAPTED, never passed through. It returns a rich decision
+        // ({optionId, source, reason, needsHuman}) because the provider wants the extra
+        // fields for its audit line, while `AcpBridge`'s contract is
+        // `Promise<'allow-once'|'reject-once'>`. Handing the decider over directly made
+        // `normalizeSelected` compare an OBJECT against the string 'allow-once' -- never
+        // true -- so this path silently rejected everything. Fail closed, but wrong, and it
+        // left `allow-once` unreachable for any caller that did not come through the
+        // provider, which is the only path the end-to-end security tests exercise.
+        onApproval: asBridgeOption(makeApprovalDecider({ cfg, worker, memories, log, queue, audit })),
+      }),
+    })
+
+    const workerRuntime = {
+      peerId,
+      name: worker.name === '' ? peerId : worker.name,
+      // The provider and the tools only use startTask/cancel/selfcheck/dispose/connected,
+      // all of which PeerConnection implements, so they cannot tell it is not a bridge.
+      bridge: connection,
+      connection,
+      defaultCwd: worker.cwd,
+      // Echoed back so `reconfigure` can tell whether a live worker still matches its
+      // configuration. `PeerConnection` captures these at construction, so a change to any
+      // of them requires tearing the connection down rather than mutating it.
+      url: worker.url,
+      token: worker.token,
+      cwd: worker.cwd,
+      serialQueue: worker.serialQueue,
+      /**
+       * Ask the worker for a fresh readiness report. Falls back to a synthesised
+       * "unreachable" report so the gate refuses instead of letting dispatch through.
+       */
+      async selfcheck() {
+        try {
+          return await connection.selfcheck()
+        } catch (error) {
+          // `sessionSegment` is about the WORKER'S SESSION, not about reachability. Saying
+          // 'unavailable' here made the dispatch gate report "nobody is logged in" whenever
+          // the relay was merely down -- a wrong diagnosis that sends the operator to check
+          // the login state instead of the link. 'unknown' is honest: the check never ran,
+          // so the blocking S0 failure below is what should decide the gate.
+          return {
+            verdict: 'blocked',
+            sessionSegment: 'unknown',
+            blockingFailures: 1,
+            warnings: 0,
+            unchecked: 0,
+            checks: [{
+              id: 'S0', name: 'worker reachable', severity: 'blocking', status: 'fail',
+              expected: 'relay responds', actual: limitDiagnostic(error instanceof Error ? error.message : String(error)),
+              fix: 'check the worker is powered on, the relay is running, and the token matches',
+            }],
+          }
+        }
+      },
+    }
+    peers.set(peerId, workerRuntime)
+
+    // The provider is captured per worker, but `decideApproval` closes over the LIVE `cfg`,
+    // so a settings change that alters `requiredTier` takes effect on the next decision
+    // without re-wiring anything.
+    const dispose = ctx.effect(() => {
+      const decider = makeApprovalDecider({ cfg, worker, memories, log, queue, audit })
+      const provider = new RemoteProvider({
+        peer: workerRuntime,
+        registry,
+        decideApproval: decider,
+        serialQueue: worker.serialQueue,
+        workspaceRoot: worker.cwd,
+      })
+      const disposeProvider = ctx.subagents.registerProvider(provider)
+      log.info(`registered subagent provider "${provider.name}" -> ${worker.url}`)
+
+      // Hand the SAME provider instance to the model-facing tools.
+      //
+      // `remote_subagent` (lib/tools/remote-tools.js) has to reach the delegation path, and the
+      // provider is where that path lives: it owns the readiness gate, the serial queue, the
+      // TaskRegistry entry and result settling. Building a second one would duplicate the queue and
+      // bypass the gate. The tools read it off the peer runtime they already receive.
+      workerRuntime.provider = provider
+
+      ctx.effect(() => () => { void connection.dispose() }, 'remote-use: connection teardown')
+      return () => {
+        // Clear it FIRST, so a tool called during teardown reports "not ready" instead of calling
+        // into a provider whose registration has just been withdrawn.
+        if (workerRuntime.provider === provider) delete workerRuntime.provider
+        disposeProvider()
+        // Only THIS worker's memory: see the note on `memories` in `wire`.
+        for (const m of memories.values()) m.dispose()
+        memories.clear()
+        log.info(`unregistered subagent provider "${provider.name}"`)
+      }
+    }, `remote-use: provider ${peerId}`)
+
+    unwire.set(peerId, dispose)
+  }
+
+  /** Take one worker offline: dispose its provider, its memory, and its connection. */
+  function unwireWorker(peerId) {
+    const dispose = unwire.get(peerId)
+    unwire.delete(peerId)
+    peers.delete(peerId)
+    if (dispose === undefined) return false
+    dispose()
+    return true
+  }
+
+  /**
+   * Make the live wiring match `workers`.
+   *
+   * Diffed by id, and a worker whose connection details changed is torn down and rebuilt:
+   * `PeerConnection` captures its url, token and httpBase at construction, so editing any
+   * of them cannot be applied to a running instance.
+   *
+   * @param {object[]} workers the desired list
+   * @returns {{ added: string[], removed: string[], changed: string[] }}
+   */
+  function reconfigure(workers) {
+    const desired = new Map()
+    for (const worker of workers) {
+      if (worker?.enabled === false) continue
+      if (typeof worker?.id === 'string' && worker.id !== '') desired.set(worker.id, worker)
+    }
+
+    const removed = []
+    for (const peerId of [...unwire.keys()]) {
+      if (!desired.has(peerId)) { unwireWorker(peerId); removed.push(peerId) }
+    }
+
+    const added = []
+    const changed = []
+    for (const [peerId, worker] of desired) {
+      const existing = peers.get(peerId)
+      if (existing === undefined) {
+        wire(worker)
+        added.push(peerId)
+        continue
+      }
+      // Compare the fields `PeerConnection` and `RemoteProvider` captured at construction.
+      const differs = existing.url !== worker.url
+        || existing.token !== worker.token
+        || existing.cwd !== worker.cwd
+        || existing.serialQueue !== worker.serialQueue
+        || existing.name !== worker.name
+      if (differs) {
+        unwireWorker(peerId)
+        wire(worker)
+        changed.push(peerId)
+      }
+    }
+    return { added, removed, changed }
+  }
+
+  // Bring up whatever the merged configuration asks for.
+  reconfigure(cfg.workers)
+
+  // ---- page-facing configuration control ---------------------------------
+  //
+  // Everything the Settings page may change, plus the persistence and live-apply that make
+  // a change take effect without editing YAML and restarting DSH.
+
+  /** The live configuration's managed subset, i.e. exactly what gets persisted. */
+  function currentSettings() {
+    return {
+      workers: cfg.workers.map((w) => ({ ...w })),
+      requiredTier: cfg.requiredTier,
+      approvalTimeoutMs: cfg.approvalTimeoutMs,
+      heartbeatMs: cfg.heartbeatMs,
+      keepShots: cfg.keepShots,
+      // Sits beside `keepShots` because they are the two halves of one bound. This is the line the
+      // generic guard exists for: it was briefly missing here while present in the schema, the save
+      // route and `publicSettings`, which is exactly the shape that saves correctly and reverts.
+      shotCacheBytes: cfg.shotCacheBytes,
+      // MUST be listed here. A key the route can SAVE but this function omits is written to
+      // disk and then read back as `undefined`, so the page shows the default again -- the
+      // setting appears to work once and silently revert. Caught by the round-trip test.
+      //
+      // RE-CAUGHT 2026-10-15: `auditMaxBytes` and `auditKeepFiles` reached the schema, the save
+      // route and the form, but NOT this list -- so both silently reverted for a whole release,
+      // and no round-trip test existed for them to notice. All three are covered by one now.
+      auditMaxBytes: cfg.auditMaxBytes,
+      auditKeepFiles: cfg.auditKeepFiles,
+      workerSessionMode: cfg.workerSessionMode,
+      // Same rule as the mode above: a key the save route accepts but this projection omits is
+      // written to disk and read back as `undefined`, so the page would show the default again.
+      workerModel: cfg.workerModel,
+      delegationPolicy: cfg.delegationPolicy,
+      // Same rule: `WorkerArming.persist` writes this through `persistSettings`, so omitting it
+      // here would make arming appear to succeed and then vanish on the next read.
+      workerRole: cfg.workerRole,
+    }
+  }
+
+  /**
+   * The policy fields a running worker captured at construction.
+   *
+   * A change to any of these needs a REBUILD rather than a mutation: `PeerConnection` reads
+   * `heartbeatMs` and `keepShots` once, and the approval decider captures the tier policy once.
+   * Omitting one here means the page accepts the edit and nothing happens until a restart.
+   */
+  function policyStamp(settings) {
+    // `keepShots` and `shotCacheBytes` are in the stamp even though the page's threshold controls
+    // apply live: a rebuild is harmless here and it keeps "the page accepted the edit" and "the
+    // running connections agree" from being able to drift apart.
+    return `${settings.requiredTier}|${settings.approvalTimeoutMs}|${settings.heartbeatMs}|${settings.keepShots}|${settings.shotCacheBytes}`
+  }
+
+  /**
+   * Persist a full settings object and make the live wiring match it.
+   *
+   * A change to the approval policy or the heartbeat interval REBUILDS every worker, because
+   * both are captured when a provider or connection is constructed. Rebuilding also discards
+   * remembered approvals, which is the behaviour we want: a decision made under the old
+   * policy must not silently carry into the new one.
+   *
+   * @returns {{ ok: boolean, error?: string, added?: string[], removed?: string[], changed?: string[], rebuilt?: boolean }}
+   */
+  function persistSettings(settings) {
+    const normalized = normalizeConfig(settings)
+    const written = writeSettings(normalized)
+    if (!written.ok) return { ok: false, error: `could not write ${written.file}: ${written.error}` }
+
+    const before = policyStamp(cfg)
+    cfg = mergeSettings(cfg, normalized).config
+
+    if (policyStamp(cfg) !== before) {
+      for (const peerId of [...unwire.keys()]) unwireWorker(peerId)
+      const diff = reconfigure(cfg.workers)
+      log.info(`settings saved: policy changed, rebuilt every worker (${diff.added.length} added, ${diff.removed.length} removed)`)
+      return { ok: true, ...diff, rebuilt: true }
+    }
+
+    const diff = reconfigure(cfg.workers)
+    log.info(`settings saved: ${diff.added.length} added, ${diff.removed.length} removed, ${diff.changed.length} rebuilt`)
+    return { ok: true, ...diff, rebuilt: false }
+  }
+
+  // ---- model-facing tools ------------------------------------------------
+  // The tools are registered UNCONDITIONALLY. They used to be skipped when there were no
+  // workers, which was fine while the worker list was fixed at load time -- but the page can
+  // now add the first worker at runtime, and a session that started with none would then have
+  // no tools to drive it with.
+  for (const def of makeRemoteTools({
+    registry,
+    peers,
+    audit,
+    // The two ceilings are read ONCE here, like `keepShots`: a transfer that started under one policy
+    // should not change its mind halfway through because the config was reloaded.
+    transfer: { maxBytes: cfg.transferMaxBytes, chunkBytes: cfg.transferChunkBytes },
+  })) {
+    ctx.effect(() => ctx.tools.register(def), `remote-use: tool ${def.name}`)
+  }
+
+  // ---- per-session enablement (default OFF) ------------------------------
+  //
+  // Installing the plugin must not route every session through a worker. The tools exist
+  // globally, but each session starts with them ANDDENIED in its own scope; `/remote-use on`
+  // lifts that for the session that asked.
+  //
+  // WHY THE RESTRICTION IS PER-AGENT AND NOT GLOBAL: `tools.restrict()` refuses a
+  // context-global call outright -- "a context-global restriction would mask every agent".
+  // So the only correct shape is to deny inside each agent's own scope, which also means the
+  // restriction is disposed with the agent rather than leaking across sessions.
+  /** Agents the operator switched on. ABSENT means off, which is the default. */
+  const enabledAgents = new Set()
+  /** agent -> the disposer that lifts its restriction. Present means "currently denied". */
+  const restrictions = new Map()
+
+  /** Hide the remote tools from one session's model. Idempotent. */
+  function denyFor(agent) {
+    if (agent === undefined || restrictions.has(agent)) return
+    try {
+      // `agent.ctx` scopes the effect, so the restriction lives and dies with the agent.
+      restrictions.set(agent, agent.ctx.tools.restrict({ deny: [...REMOTE_TOOL_NAMES] }))
+    } catch (error) {
+      // Never let this abort plugin startup. The guard below is the backstop that still
+      // refuses execution, so a failed restriction degrades to "visible but unusable"
+      // rather than to "silently allowed".
+      log.warn(`could not restrict remote tools for one session (${error instanceof Error ? error.message : String(error)}); the execution guard still applies`)
+    }
+  }
+
+  /** Show them again for one session. */
+  function allowFor(agent) {
+    const lift = restrictions.get(agent)
+    restrictions.delete(agent)
+    if (typeof lift === 'function') lift()
+  }
+
+  ctx.on('agent/created', ({ agent } = {}) => {
+    if (agent === undefined) return
+    if (!enabledAgents.has(agent)) denyFor(agent)
+  })
+
+  // FAIL-CLOSED BACKSTOP.
+  //
+  // The restriction above is applied when an agent is created, so an agent that already
+  // existed when this plugin was applied -- a hot reload, or a config change -- would keep
+  // the tools visible. `dsh-tools` exposes no way to enumerate live agents, so that case
+  // cannot be closed by iterating. A plain-context guard applies to EVERY agent instead, and
+  // refuses execution unless the session is switched on. The tool list can then be wrong
+  // without the consequence being wrong.
+  ctx.effect(() => ctx.tools.guard((exec) => {
+    if (!REMOTE_TOOL_NAMES.includes(exec?.name)) return undefined
+    const agent = exec?.agent
+    if (agent !== undefined && enabledAgents.has(agent)) return undefined
+    return `remote-use is off for this session: run /${ENABLE_COMMAND} on to route work to a LAN worker.`
+  }), 'remote-use: enablement guard')
+
+  // ---- the switch itself -------------------------------------------------
+  ctx.inject(['commands'], (child) => {
+    const handler = (invocation) => {
+      const agent = invocation?.agent
+      const argument = String(invocation?.rawInput ?? '').trim().toLowerCase()
+
+      if (argument === '' || argument === 'status') {
+        const state = agent !== undefined && enabledAgents.has(agent) ? 'on' : 'off'
+        return {
+          kind: 'success',
+          text: `remote-use is ${state} for this session.`
+            + (state === 'off'
+              ? ` Nothing routes to a worker and the remote tools are hidden. Use /${ENABLE_COMMAND} on to enable them here.`
+              : ' Work needing a real desktop is delegated; code, builds and repository work stay here.'),
+        }
+      }
+      if (agent === undefined) {
+        return { kind: 'error', text: `/${ENABLE_COMMAND}: this invocation carries no session, so the switch cannot be scoped to it.` }
+      }
+      if (argument === 'on') {
+        enabledAgents.add(agent)
+        allowFor(agent)
+        return {
+          kind: 'success',
+          text: `remote-use is on for this session. The remote tools are available and the delegation policy is in effect;`
+            + ` code, builds and repository work still belong here. /${ENABLE_COMMAND} off reverts.`,
+        }
+      }
+      if (argument === 'off') {
+        enabledAgents.delete(agent)
+        denyFor(agent)
+        return {
+          kind: 'success',
+          text: `remote-use is off for this session. The remote tools are hidden and any further call is refused.`,
+        }
+      }
+      return { kind: 'error', text: `/${ENABLE_COMMAND}: unknown argument "${argument}". Use \`on\`, \`off\` or \`status\`.` }
+    }
+
+    child.effect(() => child.commands.register({
+      name: ENABLE_COMMAND,
+      description: 'Route GUI verification and testing to a paired LAN worker for THIS session (default off)',
+      input: { hint: 'on | off | status' },
+      handler,
+    }), `remote-use: /${ENABLE_COMMAND} command`)
+  })
+
+  // ---- the policy, only while switched on --------------------------------
+  //
+  // Order places the rule BEFORE the tool guidance it qualifies, matching the rationale
+  // dsh-tools gives for its own PTC-only statement. Rendering '' outside `on` means the
+  // section is absent rather than empty when the session has not opted in.
+  if (cfg.delegationPolicy !== '') {
+    ctx.effect(() => ctx.systemPrompt.section({
+      name: 'remote-use:policy',
+      order: ctx.systemPrompt.getSectionOrder('TEAM_POLICY'),
+      text: (context) => {
+        const agent = context?.agent ?? context?.scope
+        return agent !== undefined && enabledAgents.has(agent) ? cfg.delegationPolicy : ''
+      },
+    }), 'remote-use: delegation policy section')
+  }
+
+  // ---- runtime context: stop the model from forgetting remote work --------
+  if (cfg.injectTaskSummary) {
+    ctx.effect(() => ctx.systemPrompt.section({
+      name: 'remote-use:in-flight',
+      order: ctx.systemPrompt.getSectionOrder('TOOL_SUBAGENT'),
+      // The approval notice rides in the same section as the task list because it is the same
+      // fact from the model's side: something of its own is stuck, and only a person can unstick
+      // it. Left on the settings page alone, a blocked task just looks like a hang.
+      text: () => {
+        const parts = [registry.summary()]
+        if (queue !== undefined) parts.push(approvalNotice(queue.list(), queue.timeoutMs))
+        return parts.filter((part) => part !== '').join('\n\n')
+      },
+    }), 'remote-use: task summary section')
+  }
+
+  // ---- settings data route (availability, diagnostics, pairing) ----------
+  ctx.inject(['webServer'], (child) => {
+    child.effect(() => child.webServer.register(makeSettingsRoute({
+      peers,
+      registry,
+      cache,
+      // The approval queue and its trail are plugin-level: created once for the whole
+      // apply(), not per worker, because a request waiting on a person is not about one
+      // worker and a trail that restarted per worker would not be a trail.
+      queue,
+      audit,
+      sessionsEnabled: () => enabledAgents.size,
+      armingStatus: () => arming.status(),
+      // Read-only, cheap, and needed on the FIRST page load: the mediator can be missing while the
+      // role is simply disarmed, and a page that waits for a click to say so hides a broken worker.
+      sandbox: () => sandboxReport(),
+      // The last environment self-check, and the way the page runs a new one. `readinessCheck` is
+      // awaited only when the request asks for it (the "先检查" button), because S8 moves the
+      // mouse and the session checks cost a process per run.
+      readiness: () => lastReadiness,
+      readinessCheck: (opts) => runReadinessCheck(opts),
+      setReadiness: (value) => { lastReadiness = value },
+      // Resolves the configured worker model against this machine's catalogue. Async because the
+      // catalogue lookup is; the route awaits it before arming, which is what turns a typo into a
+      // refusal instead of "images silently off".
+      validateWorkerModel: () => validateWorkerModel(),
+      armWorker: (request) => arming.arm(request),
+      preflightWorker: (request) => arming.preflight(request),
+      disarmWorker: (opts) => arming.disarm(opts),
+      workerSession: () => workerSessionStatus(),
+      log,
+      currentSettings,
+      persistSettings,
+      settingsPath: stored.file,
+      reportBudgetMs: cfg.reportBudgetMs,
+      selfcheckBudgetMs: cfg.selfcheckBudgetMs,
+    })), 'remote-use: settings route')
+  })
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+/** @param {object} ctx */
+function makeLogger(ctx) {
+  const emit = (level, message) => {
+    const target = ctx?.logger?.[level]
+    if (typeof target === 'function') target.call(ctx.logger, message)
+    else if (level === 'error' || level === 'warn') console.warn(`[remote-use] ${message}`)
+    else console.log(`[remote-use] ${message}`)
+  }
+  return {
+    info: (m) => emit('info', m),
+    warn: (m) => emit('warn', m),
+    error: (m) => emit('error', m),
+  }
+}
+
+/** Fill defaults by hand so unit tests can call this without the schema runtime. */
+export function normalizeConfig(config) {
+  const workers = Array.isArray(config?.workers) ? config.workers : []
+  return {
+    workers: workers.map((w) => ({
+      id: String(w.id ?? ''),
+      name: String(w.name ?? ''),
+      url: String(w.url ?? ''),
+      token: String(w.token ?? ''),
+      cwd: String(w.cwd ?? ''),
+      enabled: w.enabled !== false,
+      serialQueue: Number.isFinite(w.serialQueue) ? Math.max(1, Number(w.serialQueue)) : 1,
+    })),
+    approvalTimeoutMs: Number.isFinite(config?.approvalTimeoutMs) ? Number(config.approvalTimeoutMs) : 180_000,
+    requiredTier: String(config?.requiredTier ?? 'workspace-write'),
+    toolPrefix: String(config?.toolPrefix ?? 'subagent_remote'),
+    injectTaskSummary: config?.injectTaskSummary !== false,
+    heartbeatMs: Number.isFinite(config?.heartbeatMs) ? Math.max(0, Number(config.heartbeatMs)) : 15_000,
+    reportBudgetMs: Number.isFinite(config?.reportBudgetMs) ? Math.max(1, Number(config.reportBudgetMs)) : 4_000,
+    selfcheckBudgetMs: Number.isFinite(config?.selfcheckBudgetMs) ? Math.max(1, Number(config.selfcheckBudgetMs)) : 25_000,
+    // NOT clamped at 0: a negative value is the documented way to disable pruning, and each
+    // capture may free tens of megabytes.
+    keepShots: Number.isFinite(config?.keepShots) ? Number(config.keepShots) : 20,
+    // 0/negative is "no byte budget", the same documented direction as `keepShots`: the value is
+    // NOT clamped, because clamping a negative to 0 would silently create a floor that deletes
+    // everything down to nothing, which is the opposite of what a negative means everywhere else.
+    shotCacheBytes: Number.isFinite(config?.shotCacheBytes) ? Number(config.shotCacheBytes) : 0,
+    // NOT validated here: an unknown mode must fail when the launch spec is BUILT, loudly, rather
+    // than be coerced to a default here. Coercing is the dangerous direction -- the default is the
+    // unrestricted mode, so a typo would silently grant the widest access instead of none.
+    workerSessionMode: typeof config?.workerSessionMode === 'string' && config.workerSessionMode !== ''
+      ? config.workerSessionMode
+      : 'danger-full-access',
+    // Trimmed, not validated here: an invalid value must fail loudly when the launch spec is built
+    // (and be refused at save), not be coerced here.
+    workerModel: typeof config?.workerModel === 'string' ? config.workerModel.trim() : '',
+    // Not clamped at 0 for the same reason as `keepShots`: 0 or negative is the documented way to
+    // say "do not rotate / keep every archive", which is a choice, not an invalid value.
+    auditMaxBytes: Number.isFinite(config?.auditMaxBytes) ? Number(config.auditMaxBytes) : 8 * 1024 * 1024,
+    auditKeepFiles: Number.isFinite(config?.auditKeepFiles) ? Number(config.auditKeepFiles) : 5,
+    // CLAMPED, unlike the two audit caps above, because these are not "a budget you can switch off":
+    // `transferMaxBytes: 0` would refuse every file (nonsense dressed as a setting), and a chunk of
+    // 0 would make the resume loop never advance.
+    transferMaxBytes: Number.isFinite(config?.transferMaxBytes) && Number(config.transferMaxBytes) > 0
+      ? Math.floor(Number(config.transferMaxBytes))
+      : 8 * 1024 * 1024 * 1024,
+    transferChunkBytes: Number.isFinite(config?.transferChunkBytes) && Number(config.transferChunkBytes) > 0
+      ? Math.floor(Number(config.transferChunkBytes))
+      : 4 * 1024 * 1024,
+    // `undefined` means "not configured" and takes the default; an explicit empty string is
+    // the operator switching the injection OFF, which must survive. `??` would be wrong here
+    // in the other direction; the check is deliberately about the type.
+    delegationPolicy: typeof config?.delegationPolicy === 'string' ? config.delegationPolicy : DEFAULT_DELEGATION_POLICY,
+    // The worker role is carried through as an opaque blob rather than normalised field by
+    // field: `WorkerArming` owns its shape and validates it on construction. Rebuilding it here
+    // would be a second place that has to agree about the layout of a credential.
+    workerRole: config?.workerRole !== null && typeof config?.workerRole === 'object' ? config.workerRole : {},
+  }
+}
+
+/**
+ * Build the approval decider used by both the provider (per task) and the bridge
+ * (constructor-level fallback).
+ *
+ * ⚠️ `requiredTier` is derived PER APPROVAL, not taken from config once. Using a
+ * fixed tier would still stop `danger-full-access`, but it would miss the quieter
+ * failure mode: a read-only operation asking for `workspace-write`. Deriving it from
+ * the actual call (tool name + target path vs the worker's cwd) is what makes the
+ * tier check mean what DESIGN §8.3 says it means.
+ *
+ * ROUTING RULE: branch on `decision.needsHuman`, never on `source === 'human'`.
+ * `source` is an audit classification; a `danger-full-access` request is classified
+ * `tier-check` but still needs a human, so keying off `source` would silently start
+ * auto-approving it one day.
+ *
+ * @param {{ cfg: object, worker: object, memories: Map<string, any>, log: object }} deps
+ * @returns {(ask: { taskId?: string, toolCallId: string, toolName?: string, rawInput?: unknown }) => { optionId: string, source: string, reason: string, needsHuman: boolean }}
+ */
+export function makeApprovalDecider(deps) {
+  const { cfg, worker, memories, log, queue, audit } = deps
+
+  /**
+   * Append one audit row. Never throws into the approval path: a trail that can veto an
+   * operation is worse than one that reports it could not write.
+   */
+  const record = (entry) => {
+    if (audit === undefined) return
+    try {
+      audit.record(entry)
+    } catch { /* audited elsewhere; never change a decision because logging failed */ }
+  }
+
+  return async function decide(ask) {
+    const taskId = typeof ask?.taskId === 'string' && ask.taskId !== '' ? ask.taskId : 'unattributed'
+    let memory = memories.get(taskId)
+    if (memory === undefined) {
+      memory = new TaskMemory(taskId)
+      memories.set(taskId, memory)
+    }
+
+    const requiredTier = inferRequiredTier(ask?.rawInput, {
+      workspaceRoot: worker.cwd,
+      toolName: ask?.toolName,
+      defaultTier: cfg.requiredTier,
+    })
+    // What the worker ASKED for. `inferRequiredTier` answers "the minimum that would do", which is
+    // what the policy checks -- but the row a HUMAN reads must say what is being requested, or a
+    // danger-full-access request shows up as "needs workspace-write" (PITFALLS F22).
+    const requestedTier = readRequestedTier(ask?.rawInput)
+
+    const engine = decideApproval(
+      { taskId, toolCallId: ask?.toolCallId, toolName: ask?.toolName, rawInput: ask?.rawInput },
+      { memory, policy: { requiredTier, workspaceRoot: worker.cwd } },
+    )
+
+    const toolCallId = String(ask?.toolCallId ?? '')
+    const toolName = String(ask?.toolName ?? '')
+
+    // The engine decided on its own (cache miss, tier check, task memory, policy). Record it
+    // and answer at once: there is nothing a human could add.
+    if (!engine.needsHuman || queue === undefined) {
+      // `needsHuman` with no queue means nobody can be asked, which is a refusal by
+      // construction -- the engine already set the rejection option.
+      const by = engine.needsHuman ? 'no-answerer' : 'engine'
+      log.info(`approval ${toolCallId} tool=${toolName} required=${requiredTier} `
+        + `-> ${engine.optionId} (gate=engine by=${by} source=${engine.source}) ${engine.reason}`)
+      record({
+        kind: 'approval',
+        gate: 'engine',
+        by,
+        peerId: worker.id,
+        taskId,
+        toolCallId,
+        toolName,
+        requiredTier,
+        optionId: engine.optionId,
+        engineSource: engine.source,
+        reason: engine.reason,
+      })
+      return engine
+    }
+
+    // The engine cannot justify this one, so ask. The request is held open until a human
+    // answers or the queue's budget expires -- and expiry is a REFUSAL, which is what makes
+    // this a widening of what is POSSIBLE rather than a loosening of what is ALLOWED.
+    log.info(`approval ${toolCallId} tool=${toolName} required=${requiredTier} `
+      + `[NEEDS HUMAN] queued (${engine.reason})`)
+    const waiting = queue.request({
+      peerId: worker.id,
+      taskId,
+      toolCallId,
+      toolName,
+      rawInput: ask?.rawInput,
+      requiredTier,
+      requestedTier,
+      reason: engine.reason,
+      source: engine.source,
+    })
+    // Announce it before awaiting: the await lasts the whole budget, and a notification sent
+    // after it would arrive once there is nothing left to decide.
+    announceApproval({ queue, log, peerId: worker.id, taskId, toolName, requiredTier, requestedTier })
+    const optionId = await waiting
+
+    // The queue's `onSettle` writes the audit row for this one: it holds the `by` detail
+    // (human / timeout / disposed) that the decision alone cannot express.
+    return optionId === OPTION.ALLOW_ONCE
+      ? { ...engine, optionId: OPTION.ALLOW_ONCE, source: 'human', needsHuman: false, reason: `allowed once by a human (${engine.reason})` }
+      : { ...engine, optionId: OPTION.REJECT_ONCE, source: 'human', needsHuman: false, reason: `refused (${engine.reason})` }
+  }
+}
+
+/**
+ * Adapt a review-engine decider to `AcpBridge`'s optionId contract.
+ *
+ * WHY THIS EXISTS: the decider answers with a rich object (`{optionId, source, reason,
+ * needsHuman}`) because the provider wants those fields for its audit line, while the bridge
+ * wants the optionId STRING. `AcpBridge.normalizeSelected` compares its input against
+ * `'allow-once'`, so handing the decider over unchanged compared an object to a string, which
+ * is never true, and every request silently fell back to the rejection option.
+ *
+ * Fail closed, so never a security hole -- but wrong, and it made `allow-once` unreachable
+ * for any caller that did not go through the provider (the only path the end-to-end tests
+ * cover).
+ *
+ * The result is normalised to exactly one of the two ACP option ids rather than passed
+ * through, so a future decision shape cannot smuggle anything else to the bridge.
+ *
+ * @param {(ask: object) => Promise<{ optionId?: string }> | { optionId?: string }} decide
+ * @returns {(ask: object) => Promise<string>}
+ */
+export function asBridgeOption(decide) {
+  return async (ask) => {
+    const decision = await decide(ask)
+    return decision?.optionId === OPTION.ALLOW_ONCE ? OPTION.ALLOW_ONCE : OPTION.REJECT_ONCE
+  }
+}
+
+/** Largest POST body the Settings page may send. It only carries a small action object. */
+const SETTINGS_MAX_BODY = 16 * 1024
+
+/**
+ * Readiness budget for a page load.
+ *
+ * MEASURED PROBLEM: `selfcheck()` connects first, and against an unreachable worker that
+ * costs a full TCP connect timeout (~20 s). A page load must not pay that: for the whole
+ * time the request was in flight the browser showed its initial state, which read as
+ * "nothing is configured" even though the worker list plainly had one entry. Link state is
+ * knowable immediately, so it is returned regardless and a missing report is reported as
+ * missing rather than as an absence of workers.
+ */
+const REPORT_BUDGET_MS = 4_000
+
+/** An explicit "re-check now" may take longer: the operator asked for it and is waiting. */
+const SELFCHECK_BUDGET_MS = 25_000
+
+/** Sentinel distinguishing "the probe did not finish" from a legitimate `undefined`. */
+const TIMED_OUT = Symbol('timed-out')
+
+/**
+ * Await `promise`, but give up after `budgetMs`.
+ *
+ * The underlying probe is NOT cancelled -- a pending TCP connect cannot be. Its rejection is
+ * swallowed so a late failure cannot surface as an unhandled rejection; the connection's own
+ * `lastError` still records it for the next read.
+ */
+async function within(promise, budgetMs) {
+  let timer
+  const expiry = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(TIMED_OUT), budgetMs)
+    if (typeof timer?.unref === 'function') timer.unref()
+  })
+  promise.catch(() => {})
+  try {
+    return await Promise.race([promise, expiry])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Run a readiness probe under a budget.
+ * @param {object} peer
+ * @param {number} budgetMs
+ * @param {{ maxAgeMs?: number, timeoutMs?: number }} [opts] passed through to `selfcheck`
+ * @returns {Promise<{ report: object | null, error: string }>}
+ */
+async function probeWithin(peer, budgetMs, opts) {
+  const raced = await within(peer.selfcheck(opts), budgetMs)
+  if (raced === TIMED_OUT) {
+    return { report: null, error: `readiness probe did not finish within ${budgetMs} ms` }
+  }
+  return { report: raced, error: '' }
+}
+
+/** Read and parse a JSON request body without letting a huge one exhaust memory. */
+function readJsonBody(req, limit = SETTINGS_MAX_BODY) {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > limit) {
+        reject(new Error(`request body exceeds ${limit} bytes`))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('error', reject)
+    req.on('end', () => {
+      const text = Buffer.concat(chunks).toString('utf8').trim()
+      if (text === '') return resolve({})
+      try {
+        resolve(JSON.parse(text))
+      } catch (error) {
+        reject(new Error(`body is not valid JSON: ${error instanceof Error ? error.message : String(error)}`))
+      }
+    })
+  })
+}
+
+/**
+ * The message to refuse a worker edit with, or '' when its task directory is usable.
+ *
+ * WHY THIS IS A REFUSAL AND NOT A WARNING: `RemoteProvider.start` rejects such a worker before it
+ * creates a session (`REMOTE_BAD_CWD`), so the configuration can never accept a task. Accepting it
+ * would defer a certain failure to the first delegation, which is exactly how a paired worker came
+ * to look fine on the settings page while every dispatch failed (PITFALLS F16).
+ *
+ * The pairing case gets its own wording because the fix is different in kind: nothing is wrong
+ * with what the operator typed -- the string they pasted simply does not carry a directory, and
+ * only they can know a path on the far machine.
+ *
+ * @param {unknown} cwd the directory that WOULD be saved
+ * @param {{ pairing: boolean }} ctx
+ * @returns {string}
+ */
+function rejectUnusableCwd(cwd, ctx) {
+  if (ctx.pairing && String(cwd ?? '').trim() === '') {
+    return 'the pairing string carries no task directory, so supply one: the absolute path ON THE '
+      + 'WORKER where its tasks should run, for example C:\\dsh-remote\\work. It is both where the '
+      + 'task runs and the scope it may write to, so the plugin will not invent one. Nothing has '
+      + 'been saved.'
+  }
+  return assertUsableCwd(cwd)
+}
+
+/**
+ * The tier a tool call ASKED for, when it asked explicitly.
+ *
+ * WHY THIS IS NOT `inferRequiredTier`: that one answers "what is the minimum that would do", which
+ * is what the policy checks. This one answers "what did the worker request", which is what a human
+ * is being asked to approve -- and the two disagree in the case that matters. Measured 2026-10-14:
+ * a request for `danger-full-access` reached the queue and the row the operator was deciding read
+ * `requiredTier: workspace-write`, because the row carried the inference. DSH states the request in
+ * the tool call's own arguments (`sandbox_permissions`, alongside `justification`).
+ *
+ * @param {unknown} rawInput
+ * @returns {string} the requested tier, or '' when the call asked for nothing wider
+ */
+export function readRequestedTier(rawInput) {
+  if (rawInput === null || typeof rawInput !== 'object') return ''
+  const value = rawInput.sandbox_permissions ?? rawInput.sandboxPermissions
+  if (typeof value === 'string') return value.trim()
+  // Defensive: a nested shape would otherwise be silently dropped, which is how the field went
+  // missing in the first place.
+  if (value !== null && typeof value === 'object' && typeof value.mode === 'string') return value.mode.trim()
+  return ''
+}
+
+/**
+ * Tell the MODEL that a person is being waited on.
+ *
+ * WHY THIS IS NOT JUST THE SETTINGS PAGE: the page only reaches someone who is looking at it, and
+ * the model is the one party guaranteed to be talking to that person right now. Measured
+ * 2026-10-14: six approval requests expired unanswered over two days and the operator had never
+ * seen a prompt -- the request had nowhere to go but a page nobody had open.
+ *
+ * English, because it lands in the same injected section as `TaskRegistry.summary()`: the reader
+ * is the model, not the operator. The desktop notification (see `announceApproval`) is the
+ * operator-facing half and is written in Chinese.
+ *
+ * @param {object[]} pending entries from `ApprovalQueue.list()`
+ * @param {number} timeoutMs the queue's budget, used to say how long is left
+ * @returns {string} an injectable block, or '' when nothing is waiting
+ */
+export function approvalNotice(pending, timeoutMs) {
+  const rows = Array.isArray(pending) ? pending.filter((row) => row !== null && typeof row === 'object') : []
+  if (rows.length === 0) return ''
+  const budget = Number.isFinite(Number(timeoutMs)) ? Number(timeoutMs) : 0
+  const lines = rows.map((row) => {
+    const left = Math.max(0, Math.round((budget - Number(row.ageMs ?? 0)) / 1000))
+    const tool = String(row.toolName ?? '?')
+    // The REQUESTED tier, falling back to the inferred minimum: the model repeats this to the
+    // operator, so it has to be the thing they are being asked about (PITFALLS F22).
+    const tier = String(row.requestedTier ?? '') !== '' ? String(row.requestedTier) : String(row.requiredTier ?? '')
+    const task = String(row.taskId ?? '')
+    const peer = String(row.peerId ?? '')
+    return `- ${tool}${tier === '' ? '' : ` needs ${tier}`}${task === '' ? '' : ` for ${task}`}`
+      + `${peer === '' ? '' : ` (peer ${peer})`} -- refused automatically in ~${left}s if nobody answers`
+  })
+  return [
+    `APPROVALS WAITING ON A HUMAN (${rows.length}): the worker stays BLOCKED until someone answers.`,
+    ...lines,
+    'Tell the user to open Settings -> Remote use -> "Approvals waiting on you" and click "Allow once". '
+      + 'If nobody answers, the request is refused and the task will report that failure; it is not a bug to retry.',
+  ].join('\n')
+}
+
+/**
+ * Fire the operator-facing desktop notification for an approval that just started waiting.
+ *
+ * Best-effort by contract: it runs on the approval path, so a missing notifier, a blocked
+ * PowerShell or a full disk must all be silent no-ops. The approval is reachable either way --
+ * on the page, and through the model's injected context.
+ *
+ * @param {object} opts
+ * @param {object} opts.queue
+ * @param {(level: string, message: string) => void} opts.log
+ * @param {(opts: object) => boolean} [opts.notify] injectable so tests never spawn anything
+ */
+export function announceApproval(opts) {
+  const { queue, log } = opts
+  const notify = opts.notify ?? notifyDesktop
+  // Pulled off the object defensively: this runs on the approval path, so a logger that is missing
+  // a method must not be the thing that turns a waiting request into an exception.
+  const { info, warn } = loggerMethods(log)
+  try {
+    const rows = queue.list()
+    const row = rows.length === 0 ? undefined : rows[rows.length - 1]
+    if (row === undefined) return false
+    const seconds = Math.max(0, Math.round((queue.timeoutMs - Number(row.ageMs ?? 0)) / 1000))
+    const asked = String(row.requestedTier ?? '') !== '' ? String(row.requestedTier) : String(row.requiredTier ?? '?')
+    const sent = notify({
+      title: '远程任务：等待你批准',
+      message: `${String(row.toolName ?? '?')} 申请 ${asked}`
+        + `（${String(row.peerId ?? '')}${row.taskId === '' ? '' : ` · ${String(row.taskId)}`}）`
+        + `；请在设置页点「允许一次」，约 ${seconds} 秒后自动按拒绝处理。`,
+      log,
+    })
+    if (sent !== true) info('approval is waiting; no desktop notifier available (settings page + model notice only)')
+    return sent === true
+  } catch (error) {
+    warn(`could not announce the approval: ${error instanceof Error ? error.message : String(error)}`)
+    return false
+  }
+}
+
+/**
+ * Where a decision on the settings route came from.
+ *
+ * WHY THE PAGE DECLARES IT: `queue.decide` used to record every caller as `human`, which made the
+ * audit claim a person had approved a request that this repo's own harness had approved over the
+ * route. The first fix keyed off the `Origin` header -- on the theory that a browser sends it on
+ * every POST -- and **that theory was measured false in this app's own transport**: a real click on
+ * the settings page recorded `by=api`, because the request reached the route with no usable Origin
+ * (PITFALLS F22). So the page now says so itself, in the body.
+ *
+ * THIS IS EVIDENCE, NOT A BOUNDARY. Any caller can claim `via: 'page'`; the alternative was a field
+ * that never once said `page`, which is worse for the question the trail exists to answer. The
+ * threat model for this route is settled elsewhere (see `crossSitePostProblem`): a local process
+ * that can POST here can already do anything to this machine. Never branch an authorization
+ * decision on this value.
+ *
+ * @param {{ headers?: Record<string, unknown> }} req
+ * @param {{ via?: unknown }} [body]
+ * @returns {'page'|'api'}
+ */
+export function requestProvenance(req, body) {
+  if (body !== null && typeof body === 'object' && body.via === 'page') return 'page'
+  // Kept as a corroborating signal: a browser that DOES send a same-origin Origin is still a page
+  // even if an older client build forgot the body marker.
+  const headers = req?.headers ?? {}
+  const origin = typeof headers.origin === 'string' ? headers.origin.trim() : ''
+  return origin === '' || origin.toLowerCase() === 'null' ? 'api' : 'page'
+}
+
+/**
+ * Refuse a cross-site POST to the settings route.
+ *
+ * WHY THIS EXISTS: DSH's web server authenticates the APP SHELL (a bare `GET /` answers 401) but not
+ * a plugin's own API route -- how a route is reached is the plugin's own responsibility. Nothing
+ * checked where a request came from, and `readJsonBody` parses the body as JSON **whatever the
+ * `Content-Type`**, so a page on any site could POST here as a "simple request" (no CORS preflight,
+ * `Content-Type: text/plain`) and have the action EXECUTE. It could not read the reply, but that is
+ * not needed: `interrupt` takes no id, `worker.disarm` takes none either, and `worker.arm` opens a
+ * listener that accepts remote execution. `DESIGN.md` §5.9 promised this check from the first commit
+ * ("自写 `sameOrigin()` 校验、body 上限、原子写"); the body limit and the atomic write were
+ * implemented and the origin check never was (PITFALLS F17).
+ *
+ * WHY ONLY POST, AND WHY A MISSING `Origin` IS ALLOWED:
+ *   * a cross-origin READ is already impossible -- no response carries `Access-Control-Allow-Origin`,
+ *     so a page cannot see the reply at all; GET therefore needs no gate;
+ *   * a browser sends `Origin` on EVERY POST, same-origin ones included, so a MISSING header cannot
+ *     come from a hostile page. It means curl, a script, or this repo's own harness -- callers that
+ *     can already do anything to this machine. Refusing them would break the harness and buy nothing.
+ *
+ * The comparison uses the request's own `Host`, not a configured address, so it holds whether the
+ * operator opened the page as `127.0.0.1:19387` or `localhost:19387`.
+ *
+ * @param {{ headers?: Record<string, unknown> }} req
+ * @returns {string} a refusal message, or '' when the request may proceed
+ */
+export function crossSitePostProblem(req) {
+  const headers = req?.headers ?? {}
+  const origin = typeof headers.origin === 'string' ? headers.origin.trim() : ''
+  // Not a browser. See the doc comment: this cannot be a hostile page.
+  if (origin === '') return ''
+
+  const host = typeof headers.host === 'string' ? headers.host.trim().toLowerCase() : ''
+  if (host === '') {
+    return 'this request carries an Origin but no Host, so it cannot be checked; refusing rather than guessing'
+  }
+  if (origin.toLowerCase() === 'null') {
+    // A sandboxed iframe, a `data:` page or a redirected POST: no origin to compare, so no trust.
+    return 'cross-site request refused: the Origin is opaque (null)'
+  }
+
+  let parsed
+  try {
+    parsed = new URL(origin)
+  } catch {
+    return `cross-site request refused: Origin is not a URL (${origin.slice(0, 60)})`
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return `cross-site request refused: Origin scheme ${parsed.protocol}`
+  }
+  if (parsed.host.toLowerCase() !== host) {
+    return `cross-site request refused: Origin ${parsed.host} is not this server (${host})`
+  }
+  // Browsers also declare how the request relates to its page. Honour it when it is present.
+  const site = typeof headers['sec-fetch-site'] === 'string' ? headers['sec-fetch-site'].trim().toLowerCase() : ''
+  if (site !== '' && site !== 'same-origin') {
+    return `cross-site request refused: Sec-Fetch-Site: ${site}`
+  }
+  return ''
+}
+
+/**
+ * The Settings page's data route.
+ *
+ * GET  reports worker reachability, the readiness report, and the in-flight task list.
+ * POST performs the page's actions (`selfcheck`, `screenshot`, `interrupt`, `ping`).
+ *
+ * Every failure is returned as `{ ok: false, error }` with a 4xx/5xx status rather than
+ * thrown: the browser half renders the message, and an unhandled rejection here would show
+ * the page a bare 500 with nothing to display.
+ *
+ * @param {{ peers: Map<string, any>, registry: TaskRegistry, cache: ToolCallCache,
+ *           currentSettings?: () => object, persistSettings?: (s: object) => object,
+ *           settingsPath?: string, reportBudgetMs?: number, selfcheckBudgetMs?: number }} deps
+ */
+export function makeSettingsRoute(deps) {
+  const { peers, registry, cache, queue, audit } = deps
+  // How many sessions currently have remote work switched on. Injected rather than imported:
+  // the enabled set belongs to `apply()`'s scope, one level up.
+  const sessionsEnabled = typeof deps.sessionsEnabled === 'function' ? deps.sessionsEnabled : () => 0
+  // The worker role lives in apply()'s scope; the route reports it and drives it through these.
+  const armingStatus = typeof deps.armingStatus === 'function' ? deps.armingStatus : () => null
+  const armWorker = typeof deps.armWorker === 'function' ? deps.armWorker : () => ({ ok: false, error: 'this build cannot arm the worker role' })
+  const preflightWorker = typeof deps.preflightWorker === 'function' ? deps.preflightWorker : () => ({ ok: false, blockers: ['this build cannot check the worker role'], probe: { ok: false, reason: '' } })
+  const disarmWorker = typeof deps.disarmWorker === 'function' ? deps.disarmWorker : () => ({ ok: false, error: 'this build cannot disarm the worker role' })
+  // Configured versus effective session mode. Derived on every read (the listener can start or stop
+  // between two page loads), so it is passed as a getter rather than captured.
+  const workerSession = typeof deps.workerSession === 'function' ? deps.workerSession : () => null
+  // The sandbox diagnosis is read-only, so unlike the probe it can run on every page load. Defaulted
+  // to null so a test that constructs this route directly does not have to know about it.
+  const sandbox = typeof deps.sandbox === 'function' ? deps.sandbox : () => null
+  // Resolved lazily (it may need the model catalogue) and awaited by the arming actions only.
+  const validateWorkerModel = typeof deps.validateWorkerModel === 'function'
+    ? deps.validateWorkerModel
+    : async () => ({ ok: true, warning: '', error: '' })
+  // The environment self-check: cached for the page, refreshed only when a check asks for it.
+  const readiness = typeof deps.readiness === 'function' ? deps.readiness : () => null
+  const readinessCheck = typeof deps.readinessCheck === 'function' ? deps.readinessCheck : null
+  const setReadiness = typeof deps.setReadiness === 'function' ? deps.setReadiness : () => {}
+  // The route logs sparingly, but pairing is security-relevant and wants a trace. Injected
+  // rather than imported, and defaulted so this function stays usable on its own in tests.
+  const log = deps.log ?? { info: () => {}, warn: () => {}, error: () => {} }
+  const currentSettings = deps.currentSettings ?? (() => ({ workers: [] }))
+  const persistSettings = deps.persistSettings ?? (() => ({ ok: false, error: 'this build cannot persist settings' }))
+  const settingsFile = deps.settingsPath ?? ''
+  // Injectable so a test can drive the timeout path without waiting the production budget.
+  const reportBudgetMs = Number.isFinite(deps.reportBudgetMs) ? Number(deps.reportBudgetMs) : REPORT_BUDGET_MS
+  const selfcheckBudgetMs = Number.isFinite(deps.selfcheckBudgetMs) ? Number(deps.selfcheckBudgetMs) : SELFCHECK_BUDGET_MS
+
+  /**
+   * The managed configuration as the PAGE sees it: every worker present, tokens replaced by
+   * `tokenSet`/`tokenHint`. The page must be able to render the form without ever holding a
+   * bearer credential for remote execution.
+   */
+  const publicSettings = () => {
+    const settings = currentSettings()
+    return {
+      workers: (Array.isArray(settings.workers) ? settings.workers : []).map(publicWorker),
+      requiredTier: settings.requiredTier,
+      approvalTimeoutMs: settings.approvalTimeoutMs,
+      heartbeatMs: settings.heartbeatMs,
+      keepShots: settings.keepShots,
+      // Shown next to `keepShots` so the page can render both halves of the bound. 0/negative
+      // means "no byte ceiling" and must reach the page as the number, not as `false`.
+      shotCacheBytes: settings.shotCacheBytes,
+      // The mode this machine will arm its own remote sessions with. Shown on the page because
+      // "which permission level is this worker actually deployed at" was, until now, answerable
+      // only by reading a spec file that the running relay may never have read.
+      workerSessionMode: settings.workerSessionMode,
+      // The model the NEXT arming will launch this machine's ACP sessions with, as
+      // `provider/model`; empty means "whatever the acp profile configures". A deployment value:
+      // the image capability is advertised at startup from this route and cannot change per call.
+      workerModel: settings.workerModel,
+      // The same fact split into configured/effective. `workerSessionMode` above is the value the
+      // NEXT arming will use; this carries what the listener that is running NOW was started with,
+      // and whether those two disagree. Derived, never persisted.
+      workerSession: workerSession(),
+      auditMaxBytes: settings.auditMaxBytes,
+      auditKeepFiles: settings.auditKeepFiles,
+      // The delegation policy is editable from the page because getting the wording right is
+      // an operator judgement rather than a code change: it is the text that tells the model
+      // when to hand work to a worker at all. An empty string is a MEANINGFUL value (inject
+      // nothing) and must survive the round trip.
+      delegationPolicy: typeof settings.delegationPolicy === 'string' ? settings.delegationPolicy : DEFAULT_DELEGATION_POLICY,
+      // Per session and not persisted, so the page can say how many sessions currently have
+      // remote work switched on instead of leaving the operator to remember where they typed
+      // `/remote-use on`. Passed in as a getter: the enabled set lives in `apply()`, and this
+      // function is a different scope.
+      sessionsEnabled: sessionsEnabled(),
+      // The worker role as the PAGE sees it. WorkerArming.status() already carries only a
+      // masked credential; nothing here may add the raw one.
+      workerRole: armingStatus(),
+      // Whether this machine's sandbox mediator is ready, and -- when it is not -- the exact command
+      // that fixes it. Shown without clicking Check, because a silently missing mediator is exactly
+      // the state that stays invisible when the answer is only computed on demand.
+      sandbox: sandbox(),
+      // The last environment self-check, so a page reload keeps showing the result until the
+      // operator runs another one. Null until the first check.
+      readiness: readiness(),
+      // The page cannot drive the switch itself -- it has no session identity, and the switch
+      // is per session -- so it points at the real control instead of faking a toggle.
+      enableCommand: `/${ENABLE_COMMAND} on`,
+    }
+  }
+
+  return {
+    kind: 'exact',
+    path: '/api/dsh/dsh-plugin-remote-use',
+    async handler(req, res) {
+      const send = (status, body) => {
+        res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+        res.end(JSON.stringify(body))
+      }
+
+      /** Collect one row per configured worker, including its link state and readiness. */
+      const snapshot = async () => {
+        const workers = []
+        for (const peer of peers.values()) {
+          // Started BEFORE the readiness probe, not after: the probe can spend seconds waiting on
+          // a slow worker, and the cache report is a local directory listing plus (at most) one
+          // small RPC. Overlapping them keeps a page load from paying for both in series.
+          //
+          // Wrapped in an async IIFE that resolves to null on ANY failure, rather than
+          // `method(...).catch(...)`: a connection that does not implement the method at all throws
+          // synchronously, before a `.catch` could ever be attached, and that synchronously-thrown
+          // TypeError used to abort the whole snapshot -- one worker without the capability took
+          // the entire page down. The capability is genuinely optional (a bridge stub, or a
+          // connection built before this feature existed), so it is treated as optional here.
+          //
+          // The capability is asked of the CONNECTION, the same way the `cache` action asks it, so
+          // the page cannot show a worker as unable to report and then let a button on that same
+          // card try anyway.
+          const workerCachePromise = (async () => {
+            try {
+              if (peer.connection?.supportsWorkerShotCache !== true) return null
+              return await peer.connection.workerShotCache({ maxBytes: Number(currentSettings().shotCacheBytes ?? 0) })
+            } catch {
+              return null
+            }
+          })()
+
+          let report = null
+          let error = ''
+          try {
+            const probed = await probeWithin(peer, reportBudgetMs)
+            report = probed.report
+            error = probed.error
+          } catch (e) {
+            error = e instanceof Error ? e.message : String(e)
+          }
+          workers.push({
+            peerId: peer.peerId,
+            name: peer.name,
+            cwd: peer.defaultCwd,
+            report,
+            error,
+            activeTasks: registry.activeCountForPeer(peer.peerId),
+            // Whether this worker's CONFIGURATION can work at all, separate from whether the
+            // machine is reachable or ready. Without it the page showed a row that looked
+            // configured while the only symptom was a `[REMOTE_BAD_CWD]` refusal on the first
+            // delegation -- days later, and on a different screen (PITFALLS F16).
+            configProblem: assertUsableCwd(peer.defaultCwd),
+            // Surface the LINK state separately from the readiness report. Without it a
+            // "not connected" failure looks like a worker fault, which is how the missing
+            // connect() stayed invisible until a real profile load.
+            connection: peer.connection?.stats,
+            // Both halves of "where did the disk go". `hostCache` is a local scan and always
+            // available; `workerCache` needs the worker to be up AND running a relay that knows
+            // the `dsh-remote/shotcache` RPC, so it is reported as unavailable rather than as a
+            // zero -- a zero would read as "the worker holds nothing", which is the opposite of
+            // the case an operator needs to see when the worker is simply too old to say.
+            //
+            // Both are probed for the method rather than called blindly: this is a capability that
+            // a connection may genuinely lack (a stub, or one built before the feature), and an
+            // optional capability that throws when absent turns one worker into a broken page.
+            hostCache: typeof peer.connection?.hostShotCache === 'function'
+              ? peer.connection.hostShotCache()
+              : null,
+            workerCache: await workerCachePromise,
+          })
+        }
+        return {
+          ok: true,
+          workers,
+          // `listForUi`, not `list`: the registry retains each settled task's answer text, and the
+          // page neither renders it nor should receive it on every poll (PITFALLS F15).
+          tasks: registry.listForUi(50),
+          toolCallCache: { size: cache.size, misses: cache.misses },
+          // The vocabulary the page needs to render its own controls, without any secret.
+          settings: publicSettings(),
+          settingsFile,
+          // Approvals waiting for a person, and the trail of what was decided. The pending
+          // list is what makes `danger-full-access` reachable at all: without it the engine's
+          // "needs a human" had nowhere to go but refusal.
+          //
+          // `available: false` rather than an empty list when the queue is absent: the page
+          // must be able to tell "nothing is waiting" from "this build cannot ask".
+          approvals: queue === undefined
+            ? { available: false, pending: [], recent: [], missed: [], missedCount: 0, timeoutMs: 0 }
+            : {
+                available: true,
+                pending: queue.list(),
+                recent: queue.recent(10),
+                // Derived from the append-only trail rather than the queue's in-memory history, so
+                // a request nobody saw is still visible after a restart -- which is the whole point.
+                missed: audit === undefined ? [] : audit.missed(20),
+                missedCount: audit === undefined ? 0 : audit.missedCount,
+                timeoutMs: queue.timeoutMs,
+              },
+          audit: audit === undefined
+            ? { available: false, path: '', error: '', recent: [], bytes: 0, maxBytes: 0, keepFiles: 0, archives: [] }
+            // The caps travel with the snapshot so the page can SHOW that growth is bounded and
+            // where it stands. A limit nobody can see is indistinguishable from no limit.
+            : {
+                available: true,
+                path: audit.file,
+                error: audit.lastError,
+                recent: audit.tail(20),
+                bytes: audit.bytes,
+                maxBytes: audit.maxBytes,
+                keepFiles: audit.keepFiles,
+                archives: audit.archives(),
+              },
+        }
+      }
+
+      if (req.method === 'GET') return send(200, await snapshot())
+      if (req.method !== 'POST') return send(405, { ok: false, error: 'method-not-allowed' })
+
+      // BEFORE the body is read and before any action is dispatched (PITFALLS F17). A 403 here
+      // means nothing ran: no settings written, no listener opened, no task interrupted.
+      const crossSite = crossSitePostProblem(req)
+      if (crossSite !== '') return send(403, { ok: false, error: crossSite })
+
+      let body
+      try {
+        body = await readJsonBody(req)
+      } catch (error) {
+        return send(400, { ok: false, error: error instanceof Error ? error.message : String(error) })
+      }
+      const action = String(body?.action ?? '')
+
+      /** Resolve one peer by id, or reply with a 404 the page can show. */
+      const peerOr = (peerId) => {
+        const peer = peers.get(String(peerId ?? ''))
+        if (peer === undefined) {
+          send(404, { ok: false, error: `no such worker "${peerId}"` })
+          return undefined
+        }
+        return peer
+      }
+
+      try {
+        switch (action) {
+          case 'selfcheck': {
+            // `maxAgeMs: 0` forces a fresh probe. The page's whole point is to answer
+            // "can it run right now", and a cached report cannot answer that.
+            const peer = peerOr(body?.peerId)
+            if (peer === undefined) return
+            // A longer budget than a page load: this is an explicit request and the
+            // operator is watching it, so a connect attempt is allowed to finish.
+            const probed = await probeWithin(peer, selfcheckBudgetMs, { maxAgeMs: 0 })
+            if (probed.report === null && probed.error !== '') {
+              return send(504, { ok: false, error: probed.error, peerId: peer.peerId })
+            }
+            return send(200, { ok: true, peerId: peer.peerId, report: probed.report })
+          }
+
+          case 'screenshot': {
+            const peer = peerOr(body?.peerId)
+            if (peer === undefined) return
+            // The capture path is independent of the ACP link, so it still works when the
+            // worker's agent is busy -- which is exactly when a screenshot is most wanted.
+            //
+            // `peer` here is the worker RUNTIME, not the connection. The runtime exposes
+            // `connection` (and `bridge`, the same object) plus a `selfcheck()` that falls
+            // back to a synthesised report; everything else lives on the connection. Calling
+            // `peer.screenshot()` directly was a TypeError at the button, while the model's
+            // `remote_screenshot` tool -- which goes through `connection` -- worked fine.
+            const shot = await peer.connection.screenshot({ fresh: true })
+            return send(200, { ok: true, peerId: peer.peerId, screenshot: shot })
+          }
+
+          case 'ping': {
+            const peer = peerOr(body?.peerId)
+            if (peer === undefined) return
+            await peer.connection.ensure()
+            return send(200, { ok: true, peerId: peer.peerId, connected: peer.connection.connected })
+          }
+
+          case 'cache': {
+            // Cache housekeeping for ONE worker, host side and worker side in one action, because
+            // the operator's mental model is "this worker's screenshots" rather than "a directory
+            // on this machine plus a directory on that machine". Reporting and acting are the same
+            // call: `scope` picks which side, `op` picks report/clear.
+            const peer = peerOr(body?.peerId)
+            if (peer === undefined) return
+            const scope = String(body?.scope ?? '') === 'worker' ? 'worker' : 'host'
+            // An explicit budget from the page wins; otherwise the saved setting.
+            //
+            // WHY `Number.isFinite` AND NOT A TRUTHINESS TEST: 0 is a MEANINGFUL budget -- it is
+            // how both the page and the CLI spell "no byte ceiling" -- so a truthiness check would
+            // turn "no ceiling" into "use the saved ceiling", and the operator could never clear a
+            // limit from the page. Note the flip side, deliberately accepted: `Number('')` and
+            // `Number(null)` are both 0, so a request carrying an empty value also means "no
+            // ceiling". The page never sends either (a blank field is sent as an explicit 0), and
+            // "no ceiling" is the safe reading of an empty value, so this is the intended
+            // behaviour rather than an accident to route around.
+            const requested = Number(body?.maxBytes)
+            const maxBytes = Number.isFinite(requested) ? requested : Number(currentSettings().shotCacheBytes ?? 0)
+            const clear = String(body?.op ?? '') === 'clear'
+
+            if (scope === 'host') {
+              const hostCache = clear
+                ? peer.connection.clearHostShotCache()
+                : peer.connection.pruneHostShotCache({ maxBytes })
+              return send(200, {
+                ok: true,
+                peerId: peer.peerId,
+                scope,
+                cleared: clear,
+                supported: true,
+                bytes: clear ? hostCache.bytes : peer.connection.hostShotCache({ maxBytes }).bytes,
+                result: hostCache,
+                hostCache: peer.connection.hostShotCache({ maxBytes }),
+              })
+            }
+
+            // Worker side. A worker whose relay predates this RPC answers `supported: false`
+            // rather than failing: the link is healthy and only the report is missing, so
+            // treating it as an error would send the operator to debug a working connection.
+            //
+            // The capability is asked of the CONNECTION rather than probed here, so this path and
+            // the GET snapshot cannot disagree about whether a given worker can report. Before
+            // that, the snapshot reported `null` for such a worker while this path called the
+            // method blindly, turned the TypeError into a 502, and made a healthy worker look
+            // broken the moment someone pressed Clear.
+            const workerCache = peer.connection.supportsWorkerShotCache === true
+              ? await peer.connection.workerShotCache({ maxBytes, prune: !clear, clear })
+              : { supported: false, error: '', files: 0, bytes: 0, newestAt: 0, oldestAt: 0, keep: 0, maxBytes, dir: '', pruned: null }
+            // The HOST half of this reply is always real: it is this machine's own directory, and it
+            // was just read. Only the WORKER half can be "cannot report", so the page is never told
+            // that this machine is unable to describe its own disk.
+            if (workerCache.supported !== true && workerCache.error !== '') {
+              return send(502, { ok: false, error: workerCache.error, peerId: peer.peerId, scope, supported: false })
+            }
+            return send(200, {
+              ok: true,
+              peerId: peer.peerId,
+              scope,
+              cleared: clear,
+              supported: true,
+              workerSupported: workerCache.supported,
+              workerCache,
+            })
+          }
+
+          case 'interrupt': {
+            // Emergency stop. `peerId` narrows it to one worker; omitting it stops every
+            // in-flight task, which is the button a page needs when something has gone
+            // wrong and the user does not want to reason about which worker is which.
+            const only = body?.peerId === undefined ? undefined : String(body.peerId)
+            const active = registry.active()
+            const cancelled = []
+            const failures = []
+            for (const task of active) {
+              if (only !== undefined && task.peerId !== only) continue
+              const peer = peers.get(task.peerId)
+              if (peer === undefined) {
+                failures.push({ taskId: task.taskId, error: `worker "${task.peerId}" is not connected` })
+                continue
+              }
+              try {
+                await peer.bridge.cancel()
+                cancelled.push(task.taskId)
+              } catch (error) {
+                failures.push({ taskId: task.taskId, error: error instanceof Error ? error.message : String(error) })
+              }
+            }
+            return send(200, { ok: true, cancelled, failures, considered: active.length })
+          }
+
+          case 'worker.save': {
+            // Upsert one worker. An absent/blank token means "keep the stored one": the page
+            // never receives tokens, so requiring re-entry to rename a worker would be both
+            // annoying and pointless.
+            const edited = upsertWorker(currentSettings().workers, body?.worker)
+            if (edited.error !== '') return send(400, { ok: false, error: edited.error })
+            // Same rule as pairing, and for the same reason: `upsertWorker` REPLACES the row, so a
+            // form submitted with the field cleared would silently take a working worker offline.
+            // `normalizeWorker` is what produced `edited`, so this is the value that would be saved.
+            const cwdProblem = rejectUnusableCwd(normalizeWorker(body?.worker)?.cwd, { pairing: false })
+            if (cwdProblem !== '') return send(400, { ok: false, error: cwdProblem })
+            const applied = persistSettings({ ...currentSettings(), workers: edited.workers })
+            if (applied.ok !== true) return send(500, { ok: false, error: applied.error })
+            return send(200, { ok: true, applied, settings: publicSettings() })
+          }
+
+          case 'worker.pair': {
+            // Pair from a pasted pairing string: url, token and name all arrive at once, so an
+            // operator never types a bearer token by hand.
+            //
+            // The string is a CREDENTIAL, so it is decoded here and immediately reduced to a
+            // worker entry -- it is never logged, echoed back, or put in an error message. A
+            // bad string is refused rather than partially applied: a worker that connects to
+            // the right host with the wrong token fails much later, far from the paste.
+            const decoded = decodePairing(body?.pairing)
+            if (decoded.ok !== true) return send(400, { ok: false, error: decoded.error })
+
+            const incoming = { ...decoded.worker }
+            // Pairing is a paste; asking the operator to also invent an id would defeat the
+            // point, so one is derived from the worker's own name (or its host) unless the
+            // page supplied one.
+            //
+            // RE-PAIRING AN EXISTING ADDRESS UPDATES THAT WORKER. This is the normal path when a
+            // worker switches from a hand-run relay to the plugin-managed role: the address stays
+            // the same and the token is new. Deriving a fresh id would add a SECOND row for the
+            // same relay, leaving the old token configured forever and making it impossible to
+            // tell which row is live. An explicitly supplied id still wins, so an operator can
+            // intentionally create a second entry.
+            if (typeof body?.id === 'string' && body.id !== '') {
+              incoming.id = body.id
+            } else {
+              const sameUrl = currentSettings().workers.find((w) => w.url === decoded.worker.url)
+              if (sameUrl !== undefined) {
+                incoming.id = sameUrl.id
+                // The pairing string carries url/token/name/cwd only. Re-pairing an existing
+                // worker must not silently reset fields it says nothing about -- a custom serial
+                // queue or a deliberately disabled row would be lost, and a blank cwd in the
+                // string would erase the task directory the operator already configured.
+                if (incoming.name === undefined || incoming.name === '') incoming.name = sameUrl.name
+                if (incoming.cwd === undefined || incoming.cwd === '') incoming.cwd = sameUrl.cwd
+                if (incoming.enabled === undefined) incoming.enabled = sameUrl.enabled
+                if (incoming.serialQueue === undefined) incoming.serialQueue = sameUrl.serialQueue
+              } else {
+                incoming.id = deriveWorkerId(decoded.worker)
+              }
+              if (incoming.id === undefined || incoming.id === '') {
+                return send(400, { ok: false, error: 'could not derive a worker id; supply one explicitly' })
+              }
+            }
+            // The pasted string knows url/token/name; the operator may still want a local cwd.
+            if (typeof body?.cwd === 'string' && body.cwd !== '') incoming.cwd = body.cwd
+
+            // Refuse rather than save-and-warn. `RemoteProvider.start` rejects a worker with no
+            // usable task directory outright (`REMOTE_BAD_CWD`), so this configuration can never
+            // dispatch; saving it would only move a certain failure away from the paste and into
+            // the next delegation, which is how this was found (PITFALLS F16). Nothing is
+            // persisted, so the operator fixes it in the same card and pastes nothing again.
+            const cwdProblem = rejectUnusableCwd(incoming.cwd, { pairing: true })
+            if (cwdProblem !== '') return send(400, { ok: false, error: cwdProblem })
+
+            const edited = upsertWorker(currentSettings().workers, incoming)
+            if (edited.error !== '') return send(400, { ok: false, error: edited.error })
+            const applied = persistSettings({ ...currentSettings(), workers: edited.workers })
+            if (applied.ok !== true) return send(500, { ok: false, error: applied.error })
+            // Report the host only, never the token.
+            log.info(`paired worker from a pairing string: ${describePairing(body?.pairing)}`)
+            return send(200, { ok: true, applied, settings: publicSettings() })
+          }
+
+          case 'worker.remove': {
+            const { workers, removed } = removeWorkerFromList(currentSettings().workers, String(body?.peerId ?? ''))
+            if (!removed) return send(404, { ok: false, error: `no such worker "${body?.peerId}"` })
+            const applied = persistSettings({ ...currentSettings(), workers })
+            if (applied.ok !== true) return send(500, { ok: false, error: applied.error })
+            return send(200, { ok: true, applied, settings: publicSettings() })
+          }
+
+          case 'settings.save': {
+            // Only the managed, non-worker keys. Workers go through `worker.save` so a token
+            // can never be dropped by a form that did not carry one.
+            const incoming = body?.settings ?? {}
+            const priorMode = currentSettings().workerSessionMode
+            const next = { ...currentSettings() }
+            if (incoming.requiredTier !== undefined) next.requiredTier = String(incoming.requiredTier)
+            if (Number.isFinite(incoming.approvalTimeoutMs)) next.approvalTimeoutMs = Number(incoming.approvalTimeoutMs)
+            if (Number.isFinite(incoming.heartbeatMs)) next.heartbeatMs = Number(incoming.heartbeatMs)
+            if (Number.isFinite(incoming.keepShots)) next.keepShots = Number(incoming.keepShots)
+            // Accepted as a raw number of BYTES. The page parses `512MB`-style text before it
+            // sends, so an unusable string is refused at the field rather than silently becoming
+            // 0 here -- and 0 is a meaningful value ("no ceiling"), which is why it is not used
+            // as the error signal.
+            if (Number.isFinite(incoming.shotCacheBytes)) next.shotCacheBytes = Number(incoming.shotCacheBytes)
+            // An unknown mode is accepted here and refused when the spec is built -- see the schema.
+            if (typeof incoming.workerSessionMode === 'string' && incoming.workerSessionMode !== '') {
+              next.workerSessionMode = incoming.workerSessionMode
+            }
+            // Refused here rather than stored: an invalid `provider/model` would only surface as
+            // "images silently off" after the next arming, and a value the page cannot round-trip
+            // is not a setting the operator can reason about.
+            if (typeof incoming.workerModel === 'string') {
+              const parsed = parseWorkerModel(incoming.workerModel)
+              if (parsed.ok !== true) {
+                return send(400, { ok: false, error: `workerModel "${incoming.workerModel}" is not "provider/model": ${parsed.reason}` })
+              }
+              next.workerModel = incoming.workerModel.trim()
+            }
+            if (Number.isFinite(incoming.auditMaxBytes)) next.auditMaxBytes = Number(incoming.auditMaxBytes)
+            if (Number.isFinite(incoming.auditKeepFiles)) next.auditKeepFiles = Number(incoming.auditKeepFiles)
+            // An empty string is a real choice here: it switches the prompt injection off while
+            // leaving the tools gated. `??` would drop it, so the check is about the type.
+            if (typeof incoming.delegationPolicy === 'string') next.delegationPolicy = incoming.delegationPolicy
+            const applied = persistSettings(next)
+            if (applied.ok !== true) return send(500, { ok: false, error: applied.error })
+            const settingsNow = publicSettings()
+            // A listener already running cannot have its launch spec rewritten underneath it. Say
+            // so where the operator changed the value, instead of leaving the page showing the new
+            // mode while the old one keeps running.
+            if (settingsNow.workerSession?.reArmRequired === true && next.workerSessionMode !== priorMode) {
+              log.warn(`workerSessionMode is now ${next.workerSessionMode}, but the running listener was `
+                + `started with ${settingsNow.workerSession.effective}; re-arm (disarm + arm) to apply it. `
+                + `The change from ${priorMode} has NOT reached the live session.`)
+            }
+            return send(200, { ok: true, applied, settings: settingsNow })
+          }
+
+          case 'worker.preflight': {
+            // Decision 6: the page must be able to show the port, the reachable range, the
+            // current confinement state and how to close it BEFORE anything is opened. This runs
+            // the same gate `arm` does and starts nothing, so opening the panel costs a probe
+            // rather than a decision.
+            const result = preflightWorker({ bindAddress: body?.bindAddress, port: body?.port, taskCwd: body?.taskCwd })
+            const status = armingStatus()
+            const sandboxNow = sandbox()
+            // Checked here as well as at arm, so the panel can say "this model id does not resolve"
+            // BEFORE the operator spends a click on a refusal.
+            const modelCheck = await validateWorkerModel()
+            // The environment self-check runs only when the page asks for it: it spawns PowerShell
+            // and S8 moves the mouse, so it must not ride on every page load.
+            let readinessNow = readiness()
+            if (body?.checkEnvironment === true && readinessCheck !== null) {
+              readinessNow = await readinessCheck({ taskCwd: body?.taskCwd })
+              setReadiness(readinessNow)
+            }
+            return send(200, {
+              ok: result.ok === true && modelCheck.ok === true,
+              blockers: [
+                ...(result.blockers ?? []),
+                ...(modelCheck.ok === true ? [] : [modelCheck.error]),
+              ],
+              probe: result.probe ?? { ok: false, reason: '' },
+              interfaces: status?.interfaces ?? [],
+              port: status?.port ?? 0,
+              // The fix, beside the refusal. The blockers stay machine-readable; this is the part a
+              // person can act on without reverse-engineering which of three layers is missing.
+              sandbox: sandboxNow,
+              prescription: sandboxNow?.prescription?.text ?? '',
+              model: modelCheck,
+              // Environment readiness (advisory) and the prompt that fixes it, on the worker.
+              readiness: readinessNow,
+            })
+          }
+
+          case 'worker.arm': {
+            // Decision 4 is enforced inside `arm()`: if the sandbox does not contain this
+            // machine the call is refused, not warned about.
+            //
+            // The token comes back HERE and only here. It is returned once so the operator can
+            // paste it into a pairing; every later read of the page sees the mask instead.
+            const modelCheck = await validateWorkerModel()
+            if (modelCheck.ok !== true) {
+              return send(409, { ok: false, error: modelCheck.error, blockers: [modelCheck.error] })
+            }
+            const result = armWorker({ bindAddress: body?.bindAddress, port: body?.port, taskCwd: body?.taskCwd })
+            if (result.ok !== true) {
+              const sandboxNow = sandbox()
+              return send(409, {
+                ok: false,
+                error: result.error,
+                blockers: result.blockers ?? [],
+                sandbox: sandboxNow,
+                prescription: sandboxNow?.prescription?.text ?? '',
+              })
+            }
+            log.info('worker role armed by the page')
+            return send(200, {
+              ok: true,
+              token: result.token,
+              pairing: result.pairing,
+              workerRole: armingStatus(),
+              // Not a failure: the model exists but does not declare image input, which is a real
+              // deployment choice. The page shows it rather than letting it stay silent.
+              warning: modelCheck.warning,
+            })
+          }
+
+          case 'worker.disarm': {
+            // The local emergency stop. It never contacts a master and never waits on one.
+            const result = disarmWorker({ forget: body?.forget === true })
+            log.info(`worker role disarmed by the page (forget=${body?.forget === true})`)
+            return send(200, { ok: true, workerRole: armingStatus(), error: result?.ok === false ? String(result.error ?? '') : '' })
+          }
+
+          case 'approvals.clear': {
+            // Clearing the VIEW, never the trail: the audit file is append-only evidence, so this
+            // records a watermark row and the reads start after it. The trail therefore keeps every
+            // miss AND keeps the fact that somebody cleared the list -- which is itself worth
+            // auditing, because it is the one action that makes past refusals stop being visible.
+            if (audit === undefined) return send(503, { ok: false, error: 'this build has no audit trail' })
+            const cleared = audit.clear(requestProvenance(req, body))
+            log.info(`approval misses cleared from the page (${cleared})`)
+            return send(200, { ok: true, cleared, missedCount: audit.missedCount, at: audit.clearedAt })
+          }
+
+          case 'approvals.decide': {
+            // The whole point of the queue: a `danger-full-access` request the engine refused
+            // to justify can be allowed once, by a person, instead of failing outright.
+            //
+            // A decision for an entry that already settled is reported as a failure rather
+            // than quietly accepted -- the page is showing a row that no longer exists, and
+            // pretending otherwise would let a stale click look like a fresh approval.
+            if (queue === undefined) return send(503, { ok: false, error: 'this build has no approval queue' })
+            const result = queue.decide(String(body?.id ?? ''), body?.decision, requestProvenance(req, body))
+            if (result.ok !== true) return send(409, { ok: false, error: result.error })
+            return send(200, { ok: true, optionId: result.optionId, pending: queue.list() })
+          }
+
+          default:
+            return send(400, { ok: false, error: `unknown action "${action}"` })
+        }
+      } catch (error) {
+        return send(502, { ok: false, error: error instanceof Error ? error.message : String(error) })
+      }
+    },
+  }
+}