dsh-remote 0.8.35 → 0.8.37

package/lib/http-transport.js

@@ -67,11 +67,103 @@ export function connectionRoute(route) {
   }
 }
 
+/**
+ * Reject a browser-shaped request that is not same-origin ours.
+ *
+ * This is the FALLBACK fence, used only when the Connection service (which owns
+ * DSH's authoritative `requestRejection`) is absent — an old composition that
+ * has a `webServer` but no browser-authentication owner. It is deliberately
+ * fail-closed on the three browser vectors our own routes would otherwise
+ * accept:
+ *   • `sec-fetch-site: cross-site` — a page on any origin driving our API;
+ *   • an `Origin` that is not our own authority — the same, with CORS markers;
+ *   • a non-loopback `Host` — DNS rebinding, where a name the attacker controls
+ *     resolves to 127.0.0.1 so even `Origin === Host` looks "same-origin".
+ * Non-browser callers (curl, scripts) carry no `Sec-Fetch-*`/`Origin` and a
+ * loopback `Host`, so they keep working; that is the same shape DSH's own fence
+ * implements for `/api`.
+ *
+ * A request with no HTTP headers at all is not a browser request — it comes
+ * from an in-process caller (tests, and the Desktop carrier's IPC path, which
+ * authenticates before dispatch) — so there is no browser layer to defend.
+ *
+ * @param {import('node:http').IncomingMessage} req - the request under test.
+ * @returns {number|undefined} 403 to reject, undefined to proceed.
+ */
+function fallbackRejection(req) {
+  const headers = req && req.headers
+  if (!headers || typeof headers !== 'object') return undefined
+  const header = (name) => {
+    const value = headers[name]
+    return typeof value === 'string' ? value : Array.isArray(value) ? value[0] : undefined
+  }
+  if (header('sec-fetch-site') === 'cross-site') return 403
+  const host = header('host')
+  const origin = header('origin')
+  if (origin !== undefined && host !== undefined) {
+    try {
+      if (new URL(origin).host !== host) return 403
+    } catch {
+      return 403
+    }
+  }
+  if (host !== undefined) {
+    const hostname = host.replace(/:\d+$/, '').toLowerCase()
+    const loopback = hostname === 'localhost' || hostname === '[::1]'
+      || /^127(?:\.\d{1,3}){3}$/.test(hostname)
+    if (!loopback) return 403
+  }
+  return undefined
+}
+
+/**
+ * Wrap one route so every request passes DSH's browser trust fence first.
+ *
+ * The legacy `/dsh-remote/*` routes are registered straight on `webServer`, which
+ * applies no Host/Origin check and no browser authentication — `requestRejection`
+ * lives on the Connection service and is only wired to `/api` and the
+ * `/api/remote.mux` upgrade. Without this wrapper our mutating routes were
+ * reachable cross-site as "simple requests" (no preflight: a `text/plain` POST
+ * needs no CORS approval), so any page the user visited could define a tunnel,
+ * rewrite the machine registry, or drive `update-apply`. The model tools were
+ * never exposed that way; only these JSON routes were.
+ *
+ * The lookup is deferred to request time because `webServer` and `connection`
+ * arrive independently: the fence must engage as soon as authentication exists,
+ * and must not be baked in from whichever service happened to be present when
+ * the route was registered.
+ *
+ * @param {object} route - a webServer route definition.
+ * @param {() => object|undefined} connectionOf - resolves the live Connection service.
+ * @returns {object} a route whose handler enforces the fence before dispatching.
+ */
+export function guardRoute(route, connectionOf) {
+  const inner = route.handler
+  return {
+    ...route,
+    handler: async (req, res) => {
+      const connection = connectionOf()
+      const rejection = typeof connection?.requestRejection === 'function'
+        ? connection.requestRejection(req)
+        : fallbackRejection(req)
+      if (rejection !== undefined) {
+        res.writeHead(rejection, { 'content-type': 'text/plain; charset=utf-8' })
+        res.end(rejection === 401 ? 'unauthorized' : 'forbidden')
+        return
+      }
+      return inner(req, res)
+    },
+  }
+}
+
 export function registerHttpTransports(ctx, routes) {
   // Reactive injection matters: either service can arrive after the plugin.
   // Neither optional transport is a hard prerequisite for the SSH tools.
   ctx.inject(['webServer'], (inner) => {
-    const disposers = routes.map((route) => inner.get('webServer').register(route))
+    // Apply DSH's own browser fence to every legacy route; the Connection
+    // service is read per request so a late-arriving authenticator still counts.
+    const guarded = routes.map((route) => guardRoute(route, () => ctx.get('connection')))
+    const disposers = guarded.map((route) => inner.get('webServer').register(route))
     inner.effect(() => () => disposers.forEach((dispose) => dispose()), 'dsh-remote.web-routes')
   })
   ctx.inject(['connection'], (inner) => {

package/lib/index.js

@@ -41,7 +41,13 @@ import { searchRemote } from './search.js'
 import { resolveMirror, poolKey, lookupSessionCwd, encodeSegmentSafe, readSessionHeaderCwd, requestSessionHint } from './binding.js'
 import { TaskManager } from './tasks.js'
 import { ForwardManager } from './forwards.js'
-import { selfDir, diskVersion, LOADED_VERSION, gtVersion, fetchLatestVersion, applyUpdate, persistUpdateMode, readUpdateMode, reloadSelf, scheduleSelfReload, isInstalledCopy } from './update.js'
+import { WebAttach } from './web-attach.js'
+import {
+  buildProbeCommand, parseProbe, judgeProbe, buildInstallPlan,
+  resolvePrefix, stepResult, DEFAULT_INSTALL_VERSION,
+} from './web-deploy.js'
+import { registerDeploySkill, buildInvestigatePrompt, SKILL_NAME } from './web-deploy-skill.js'
+import { selfDir, diskVersion, LOADED_VERSION, gtVersion, fetchLatestVersion, applyUpdate, persistUpdateMode, readUpdateMode, reloadSelf, scheduleSelfReload, lastSelfReload, isInstalledCopy } from './update.js'
 import { sendHeartbeat, pseudonym, heartbeatUrl, hasPersistedId, installIdPath } from './telemetry.js'
 import { loadMachines as _loadMachines, saveMachines as _saveMachines, sanitizeMachine as _sanitizeMachine, applyMachine as _applyMachine, machineId as _machineId } from './registry.js'
 import { registerHttpTransports } from './http-transport.js'
@@ -160,6 +166,32 @@ export const Config = z.object({
    *  true). With `false` an update only takes effect on the next process start
    *  and `/dsh-remote/update-check` reports `pendingReload: true` meanwhile. */
   updateAutoReload: z.boolean().default(true),
+  /** First local port tried when attaching a remote DSH Web UI (issue #46).
+   *  The listener is loopback-only; consecutive ports are tried when this one
+   *  is taken. */
+  webAttachPortStart: z.number().step(1).min(1).max(65535).default(3088),
+  /** Remote command that starts a `dsh web` on the attached machine. Only needs
+   *  changing when the remote's `dsh` is not on the SSH login PATH (e.g. a
+   *  version installed into a private prefix). */
+  webAttachCommand: z.string().default('dsh'),
+  /** `DSH_HOME` to export on the remote when attaching. Empty reuses the
+   *  remote user's own harness home; point it at a scratch directory to keep an
+   *  attached instance out of the user's real sessions and settings. */
+  webAttachDshHome: z.string().default(''),
+  /** How long (seconds) to wait for a freshly started remote `dsh web` to print
+   *  its startup token before giving up. */
+  webAttachWaitSeconds: z.number().step(1).min(5).max(300).default(45),
+  /** Where an automatic deployment installs dsh on the remote. Empty means
+   *  `$HOME/.dsh-remote/dsh` (persistent, needs no write access to any system
+   *  prefix, and never replaces a dsh the user already has). */
+  webInstallPrefix: z.string().default(''),
+  /** Version an automatic deployment installs. The default is the first release
+   *  whose node-pty ships Linux prebuilds — older ones cannot boot `dsh web` on
+   *  Linux at all. */
+  webInstallVersion: z.string().default(DEFAULT_INSTALL_VERSION),
+  /** npm registry to install from. Empty uses the remote's own npm config, which
+   *  is what an internal mirror needs to stay in effect. */
+  webInstallRegistry: z.string().default(''),
 })
 
 // ── shell / path helpers (pure implementations in lib/paths.js) ───────────
@@ -375,6 +407,42 @@ export async function apply(ctx, config) {
     sshConfigResolved: m.useSshConfig ? resolveMachineSshConfig(m, { text: sshConfigText() }) : null,
   }))
 
+  /**
+   * The `dsh` command to use for a machine's Web UI attach.
+   *
+   * Resolution order is deliberate: a PER-MACHINE value recorded by a completed
+   * deployment wins, then the global config default. Without the per-machine
+   * branch, deploying on one host would point every other host at a binary that
+   * only exists on that one.
+   *
+   * @param {object} machine - a registry record (may be undefined).
+   * @returns {string} the command to run on that machine.
+   */
+  const webAttachCommandFor = (machine) => {
+    const perMachine = machine && typeof machine.webAttachCommand === 'string' ? machine.webAttachCommand.trim() : ''
+    return perMachine || String(config.webAttachCommand || 'dsh')
+  }
+
+  /**
+   * Record the dsh command a deployment produced, on that machine.
+   *
+   * Persisted through the same registry helper every other machine edit uses, so
+   * the value survives a restart and appears in the settings UI like any other
+   * field. `keepCurrentKey: false` preserves whichever machine is current —
+   * deploying must never silently switch the user's active machine.
+   *
+   * @param {object} machine - the registry record to update.
+   * @param {string} command - the working dsh command.
+   */
+  const persistWebAttachCommand = (machine, command) => {
+    try {
+      const i = machineIndex(machine.id)
+      if (i < 0) return
+      machines[i] = { ...machines[i], webAttachCommand: String(command || '') }
+      saveMachines(machines, store.currentId, false)
+    } catch { /* a failed persist only costs a re-deploy next time */ }
+  }
+
   /** The machine the pool is currently bound to: an ephemeral tool connection
    * (rw_connect save:false) wins, then the stored current, then config default. */
   let ephemeral = null
@@ -772,6 +840,20 @@ export async function apply(ctx, config) {
   pool.onReady = (client) => forwards.attach(client)
   pool.onCloseHook = () => forwards.detach()
 
+  // ── remote DSH Web UI attach sessions (issue #46) ─────────────────────────
+  // "Use this DSH as a CLIENT for a DSH on another machine". The remote never
+  // opens an inbound port (DSH forbids `--host 0.0.0.0`); we SSH out, start or
+  // reuse a loopback-bound `dsh web` there, and carry its socket back over our
+  // own SSH connection to a loopback listener here. One session per machine —
+  // attaching again to the same machine reuses the live tunnel instead of
+  // starting a second remote server. Lifecycle is owned by the plugin fiber, so
+  // unloading the plugin tears every tunnel down.
+  const webAttaches = new Map() // machineId → WebAttach
+  ctx.effect(() => () => {
+    for (const attach of webAttaches.values()) { try { attach.close() } catch { /* already gone */ } }
+    webAttaches.clear()
+  }, 'dsh-remote.web-attach')
+
   // ── auto-push watcher (config.autoPush, default off) ──────────────────────
   // Watches the local mirror; local edits are pushed back to the remote after a
   // 3s debounce, honoring ignore rules + the three-way conflict guard (a remote
@@ -1954,6 +2036,64 @@ export async function apply(ctx, config) {
       },
     }),
 
+    defineTool({
+      name: 'rw_deploy_probe',
+      description:
+        'READ-ONLY health check of the remote machine\'s DSH install: platform/arch, node/npm, the existing dsh and its version, whether its native module can load (the usual reason `dsh web` will not start, e.g. a node-pty build with no Linux prebuild), whether it knows --no-open, proxy and npm registry settings, and whether a private install prefix is writable. Writes nothing on the remote. Use it before troubleshooting a failed remote DSH Web UI connection. For an automatic install into a private prefix, use the settings UI ("Deploy & verify") — this tool never installs.',
+      parameters: {},
+      output: textOut,
+      async execute(_args, exec) {
+        // Use the BINDING (this session's own machine), like every other rw_*
+        // tool. Reading the active machine instead would let a probe report on a
+        // host this session never asked about.
+        const b = requireBinding(exec, 'rw_deploy_probe')
+        // The binding carries host/port/user but no id; match on the identity the
+        // binding resolved, so a machine previously deployed to is still found
+        // (its `webAttachCommand` is the per-machine record we want to report).
+        const machine = machines.find((m) => m.host === b.host
+          && Number(m.port || 22) === Number(b.port || 22)
+          && (!b.username || m.username === b.username)) || null
+        // Do NOT pre-resolve the prefix locally: `resolvePrefix({home:''})` falls
+        // back to /tmp, which is not where an install would go. With no explicit
+        // config the REMOTE resolves it from its own $HOME and reports back.
+        const explicitPrefix = String(config.webInstallPrefix || '').trim()
+        const installedCommand = String((machine && machine.webAttachCommand) || '').trim()
+        const out = await b.pool.exec(
+          buildProbeCommand({ prefix: explicitPrefix, installedCommand, defaultPrefixFor: explicitPrefix ? '' : 'home' }),
+          { timeoutMs: 30000 },
+        )
+        const facts = parseProbe(out && out.stdout)
+        const verdict = judgeProbe(facts, { installedCommand })
+        // Rendered as a compact report: the model needs the FACTS and the
+        // VERDICT, not a JSON blob it would have to re-interpret.
+        const lines = [
+          `remote: ${b.host}${b.username ? ' (' + b.username + ')' : ''}`,
+          `verdict: ${verdict.severity}${verdict.ok ? ' (usable)' : ' (blocked)'}`,
+          verdict.useCommand ? `dsh to use: ${verdict.useCommand}` : 'dsh to use: (none usable yet)',
+          `can auto-install: ${verdict.canAutoInstall ? 'yes' : 'no'}`,
+          '',
+          'facts:',
+          `  platform=${facts.platform || '?'} arch=${facts.arch || '?'} ${facts.windows ? '(windows)' : ''}`,
+          `  node=${facts.node || '(none)'} ${facts.nodeVersion || ''}`,
+          `  npm=${facts.npm || '(none)'}`,
+          `  dsh=${facts.dsh || '(none)'} ${facts.dshVersion || ''}`,
+          `  native-module (node-pty) prebuild: ${facts.ptyPrebuild || 'unknown'}`,
+          `  knows --no-open: ${facts.noOpen || 'unknown'}`,
+          facts.installed ? `  previously deployed command present: ${facts.installed} (pty=${facts.installedPty || '?'} web=${facts.installedWeb || '?'})` : '',
+          `  git bash: ${facts.gitBash || '(none)'}${facts.windows && !facts.gitBash ? ' — required for a Windows remote' : ''}`,
+          `  proxy: ${facts.proxyVar || '(none)'}  npm registry: ${facts.registry || '(default)'}`,
+          `  install prefix ${facts.resolvedPrefix || explicitPrefix || '(unresolved)'} writable: ${facts.writable || 'unknown'}`,
+          '',
+          'findings:',
+          ...verdict.findings.map((f) => `  [${f.severity}] ${f.summary}${f.detail ? ' — ' + f.detail : ''}${f.fix ? '\n        fix: ' + f.fix : ''}`),
+        ].filter(Boolean)
+        if (!verdict.ok) {
+          lines.push('', 'This is read-only. To fix it, either use the settings UI card "Remote dsh health check & deploy" (it installs into a private prefix and verifies), or repair it yourself following the dsh-remote-deploy skill.')
+        }
+        return { text: lines.join('\n') }
+      },
+    }),
+
     defineTool({
       name: 'rw_forward',
       description:
@@ -2846,6 +2986,237 @@ export async function apply(ctx, config) {
         }
       },
     },
+    {
+      kind: 'exact',
+      path: '/dsh-remote/web-attach',
+      // Issue #46: open/reuse/close a tunnel to a remote machine's DSH Web UI.
+      // Actions: status (GET) | open | close. `open` either starts a remote
+      // `dsh web` (default) or attaches to one the user already runs by passing
+      // its `http://127.0.0.1:<port>/?token=…` URL.
+      handler: async (req, res) => {
+        try {
+          if (req.method === 'GET') {
+            const q = new URL(req.url, 'http://localhost').searchParams
+            const id = q.get('machineId') || ''
+            const attach = id ? webAttaches.get(id) : undefined
+            return sendJson(res, 200, {
+              ok: true,
+              attach: attach ? attach.describe() : null,
+              attaches: [...webAttaches.values()].map((a) => a.describe()),
+            })
+          }
+          if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+          const body = parseJsonObject(await readBody(req))
+          const action = String(body.action || '')
+          const machineId = String(body.machineId || store.currentId || '').trim()
+          if (!machineId) return sendJson(res, 400, { ok: false, error: '选择一台机器后再操作（missing machineId）' })
+
+          // ── deploy: probe (read-only) and install (private prefix) ─────────
+          // Issue #46 follow-up. Detection and installation are deterministic, so
+          // they are code rather than a model call: fast, free, unit-testable.
+          // The AI path (a built-in skill) is offered only when this cannot cope.
+          if (action === 'probe' || action === 'install') {
+            const machine = machines.find((m) => m.id === machineId)
+            if (!machine) return sendJson(res, 404, { ok: false, error: `机器不存在：${machineId}` })
+            const target = poolForMachine(identityOf(machine))
+            // The command that deployment produced FOR THIS MACHINE wins over any
+            // global default — otherwise a deployment on one host would be
+            // forgotten on the very next probe.
+            const installedCommand = String(machine.webAttachCommand || '').trim()
+            const prefix = resolvePrefix({ home: '' }, { prefix: config.webInstallPrefix || '' })
+
+            if (action === 'probe') {
+              // Strictly read-only: this runs before the user has agreed to any
+              // change, and may be run on a machine they are merely looking at.
+              const out = await target.exec(buildProbeCommand({ prefix, installedCommand, defaultPrefixFor: config.webInstallPrefix ? '' : 'home' }), { timeoutMs: 30000 })
+              const facts = parseProbe(out && out.stdout)
+              const verdict = judgeProbe(facts, { installedCommand })
+              // The prefix we judged writability against was a guess (empty
+              // $HOME); now that the probe reported the real home, re-resolve so
+              // the prefix shown matches what an install would actually use.
+              const realPrefix = facts.resolvedPrefix || resolvePrefix(facts, { prefix: config.webInstallPrefix || '' })
+              audit('web-deploy', `probe ${machine.host}: ${verdict.severity}`, verdict.ok ? 0 : 1, machine)
+              return sendJson(res, 200, {
+                ok: true,
+                facts,
+                verdict,
+                prefix: realPrefix,
+                command: webAttachCommandFor(machine),
+                installVersion: config.webInstallVersion || DEFAULT_INSTALL_VERSION,
+                registry: config.webInstallRegistry || '',
+              })
+            }
+
+            // install
+            if (body.confirm !== true) {
+              return sendJson(res, 400, { ok: false, error: '安装需要在请求里显式 confirm: true' })
+            }
+            const pout = await target.exec(buildProbeCommand({ prefix, installedCommand, defaultPrefixFor: config.webInstallPrefix ? '' : 'home' }), { timeoutMs: 30000 })
+            const facts = parseProbe(pout && pout.stdout)
+            const verdict = judgeProbe(facts, { installedCommand })
+            if (!verdict.canAutoInstall) {
+              const why = verdict.findings.filter((x) => x.severity === 'blocker').map((x) => x.summary).join('；')
+              audit('web-deploy', `install ${machine.host} refused: ${why}`, 1, machine)
+              return sendJson(res, 400, { ok: false, error: `无法自动安装：${why || '远端缺少前提条件'}`, verdict })
+            }
+            const installPrefix = facts.resolvedPrefix || resolvePrefix(facts, { prefix: config.webInstallPrefix || '' })
+            // A registry the user set explicitly wins; otherwise the remote's own
+            // npm config is left alone, which is what an internal mirror needs.
+            // `--registry` is only added when configured — overriding a working
+            // corporate mirror with the public one would be a regression.
+            const registry = String(body.registry || config.webInstallRegistry || '').trim()
+            // Proxy comes from the remote's own environment; the operator may
+            // override it per-install when the inherited one is wrong.
+            const env = body.proxy && typeof body.proxy === 'object'
+              ? Object.fromEntries(Object.entries(body.proxy).filter(([, v]) => typeof v === 'string'))
+              : undefined
+            const plan = buildInstallPlan({
+              facts,
+              prefix: installPrefix,
+              version: String(body.version || config.webInstallVersion || DEFAULT_INSTALL_VERSION),
+              registry,
+              env,
+            })
+            const results = []
+            for (const step of plan.steps) {
+              let res2
+              try {
+                res2 = await target.exec(step.command, {
+                  timeoutMs: step.timeoutMs || 120000,
+                  // Per-step env exists for the proxy override (P4); pool.exec
+                  // passes it through to the remote process.
+                  ...(step.env ? { env: step.env } : {}),
+                })
+              } catch (err) {
+                results.push({ id: step.id, title: step.title, ok: false, code: -1, output: String((err && err.message) || err) })
+                break
+              }
+              const r = stepResult(step, res2)
+              results.push(r)
+              if (!r.ok) break
+            }
+            const ok = results.length === plan.steps.length && results.every((r) => r.ok)
+            if (ok) {
+              // Persist so the attach flow uses the working build from now on.
+              persistWebAttachCommand(machine, plan.command)
+              audit('web-deploy', `install ${machine.host} → ${plan.command}`, 0, machine)
+              return sendJson(res, 200, { ok: true, steps: results, command: plan.command, prefix: installPrefix })
+            }
+            const failed = results.find((r) => !r.ok)
+            audit('web-deploy', `install ${machine.host} failed at ${failed && failed.id}`, 1, machine)
+            // A failure that looks like a network/registry problem gets the AI
+            // escape hatch suggested, since that is precisely the long tail the
+            // deterministic path cannot classify.
+            const looksNetworky = /ETIMEDOUT|ENOTFOUND|ECONNREFUSED|network|proxy|403|404/i.test(String(failed && failed.output))
+            return sendJson(res, 500, {
+              ok: false,
+              error: `安装失败于「${failed ? failed.title : '未知步骤'}」`,
+              steps: results,
+              prefix: installPrefix,
+              suggestInvestigate: true,
+              ...(looksNetworky ? { hint: '看起来是网络或源的问题，可以让 AI 排查。' } : {}),
+            })
+          }
+
+          if (action === 'open') {
+            // Reuse a live tunnel for this machine: re-opening would start a
+            // second remote DSH and leak the first one's process.
+            const live = webAttaches.get(machineId)
+            if (live && live.active) return sendJson(res, 200, { ok: true, attach: live.describe(), reused: true })
+            // A tunnel that is no longer listening still owns sockets and a log
+            // path; release it before this machine gets a fresh session. Its
+            // remote process is left alone — stopping it stays an explicit act.
+            if (live) { try { await live.close() } catch { /* already torn down */ } }
+            const machine = machines.find((m) => m.id === machineId)
+            if (!machine) return sendJson(res, 404, { ok: false, error: `机器不存在：${machineId}` })
+            const attach = new WebAttach({
+              localPortStart: config.webAttachPortStart,
+            })
+            try {
+              await attach.open({
+                pool: poolForMachine(identityOf(machine)),
+                machineId,
+                command: String(body.command || '').trim() || webAttachCommandFor(machine),
+                profile: 'web',
+                existingUrl: String(body.existingUrl || ''),
+                dshHome: config.webAttachDshHome || '',
+                waitSeconds: config.webAttachWaitSeconds,
+              })
+            } catch (err) {
+              try { await attach.close() } catch { /* nothing was listening */ }
+              const msg = String((err && err.message) || err)
+              audit('web-attach', `open ${machine.host} failed: ${msg}`, 1, machine)
+              return sendJson(res, 500, { ok: false, error: msg })
+            }
+            webAttaches.set(machineId, attach)
+            audit('web-attach', `open ${machine.host} → 127.0.0.1:${attach.localPort}`, 0, machine)
+            return sendJson(res, 200, { ok: true, attach: attach.describe() })
+          }
+
+          // ── investigate: hand the problem to an agent with the built-in skill ──
+          // The AI escape hatch. Started ONLY when the user asks for it: it costs
+          // a model call, so it is never automatic — the deterministic probe and
+          // install are the default path.
+          if (action === 'investigate') {
+            const machine = machines.find((m) => m.id === machineId)
+            if (!machine) return sendJson(res, 404, { ok: false, error: `机器不存在：${machineId}` })
+            const controller = ctx.get('sessionController')
+            if (!controller || typeof controller.create !== 'function' || typeof controller.prompt !== 'function') {
+              return sendJson(res, 400, {
+                ok: false,
+                error: '当前组合没有会话服务（sessionController），无法让 AI 排查。'
+                  + '请改用「部署并验证」，或把排查信息复制到对话里。',
+              })
+            }
+            const sessionId = `dsh-remote-deploy-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`
+            try {
+              await controller.create({ sessionId, cwd: undefined })
+            } catch (err) {
+              // An id collision is the only tolerable failure here.
+              if (!/conflict|exist/i.test(String((err && err.message) || err))) {
+                return sendJson(res, 500, { ok: false, error: `创建排查会话失败：${String((err && err.message) || err)}` })
+              }
+            }
+            const prompt = buildInvestigatePrompt({
+              host: machine.host,
+              user: machine.username,
+              prefix: resolvePrefix({ home: '' }, { prefix: config.webInstallPrefix || '' }),
+              findings: Array.isArray(body.findings) ? body.findings : [],
+              facts: body.facts && typeof body.facts === 'object' ? body.facts : undefined,
+              error: String(body.error || ''),
+            })
+            try {
+              await controller.prompt({
+                sessionId,
+                mode: 'queue',
+                content: [{ type: 'text', text: prompt }],
+              })
+            } catch (err) {
+              return sendJson(res, 500, { ok: false, error: `提交排查任务失败：${String((err && err.message) || err)}` })
+            }
+            audit('web-deploy', `investigate ${machine.host} → session ${sessionId}`, 0, machine)
+            return sendJson(res, 200, { ok: true, sessionId, skill: SKILL_NAME })
+          }
+
+          if (action === 'close') {
+            const attach = webAttaches.get(machineId)
+            if (!attach) return sendJson(res, 200, { ok: true, closed: false, error: '该机器没有活动的远程界面' })
+            const stopRemote = body.stopRemote === true
+            // `close()` refuses to signal anything without a recorded PID, so a
+            // tunnel onto the user's own running instance stays hands-off.
+            const exec = (cmd) => poolForMachine(identityOf(machines.find((m) => m.id === machineId) || {})).exec(cmd, { timeoutMs: 10000 })
+            await attach.close({ stopRemote, exec })
+            webAttaches.delete(machineId)
+            audit('web-attach', `close ${attach.cleanUrl}${stopRemote ? ' (remote stopped)' : ''}`, 0)
+            return sendJson(res, 200, { ok: true, closed: true, stoppedRemote: stopRemote && !!attach.remotePid })
+          }
+
+          return sendJson(res, 400, { ok: false, error: 'action must be open | close' })
+        } catch (err) {
+          return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
+        }
+      },
+    },
     {
       kind: 'exact',
       path: '/dsh-remote/home',
@@ -2890,6 +3261,10 @@ export async function apply(ctx, config) {
           // Exposed so the settings page can explain why `auto` may not act:
           // a link:/dev install must not be overwritten by an npm publish.
           selfUpdateAllowed: isInstalledCopy(),
+          // Outcome of the last hot-swap attempt (null if never tried). Without
+          // this the swap could fail forever while the panel kept saying a
+          // reload was merely pending — which is exactly what happened.
+          lastReload: lastSelfReload(),
         }
         const probe = await fetchLatestVersion()
         // 即使查不到最新版，也把**本地状态**照常返回（ok:true），只把 registry
@@ -2974,6 +3349,15 @@ export async function apply(ctx, config) {
 
   registerHttpTransports(ctx, routes)
 
+  // ── built-in deployment skill (issue #46 P3) ──────────────────────────────
+  // Registered at runtime so the plugin stays a single self-contained package
+  // (no writable $DSH_HOME/skills, no collision with the user's own skills).
+  // Optional: a composition without `ctx.skills` keeps the deterministic deploy
+  // path and merely loses the AI fallback.
+  ctx.inject(['skills'], (skillCtx) => {
+    registerDeploySkill(skillCtx)
+  })
+
   // ── auto-update: check on load + on an interval; apply silently ───────────
   // Failures are swallowed (never break the plugin). The persisted override
   // (settings UI) wins over the profile-config default, which wins over

package/lib/pool.js

@@ -470,7 +470,15 @@ export class SshPool {
               timedOut = true
               reject(new Error(`ssh sftp open timed out after ${this.config.commandTimeoutMs}ms`))
             }, this.config.commandTimeoutMs)
-            if (typeof attemptTimer.unref === 'function') attemptTimer.unref()
+            // ★ 这里**不能 unref**。
+            //
+            // 这个定时器是"本次 await 的 sftp 打开"的**唯一结算者**：要么它超时 reject，
+            // 要么 ssh2 回调 resolve。若把它 unref，而进程此刻没有别的 pending 句柄，
+            // Node 会认为无事可做而**直接退出**，调用方永远等不到结果。
+            // 实测症状：CI 上该用例之后的 4 个用例被标记 `cancelledByParent`
+            // （同文件子进程提前退出），而本地因运行器恰好持着句柄而侥幸通过。
+            // 注意与上面 exec() 的超时定时器保持一致 —— 那个本来就没有 unref。
+            // 下面的 hardClose 仍然 unref，因为它只做清理、不负责结算。
             const clearAttempt = () => { clearTimeout(attemptTimer) }
             try {
               c.sftp((err, sftp) => {

package/lib/update.js

@@ -380,8 +380,24 @@ export async function reloadSelf(loader) {
   if (!entry) return { ok: false, reason: 'own loader entry not found' }
   try {
     const cleared = clearSelfModuleCache(loader)
+    // ★ 卸载必须走 entry.fiber.dispose()。
+    //
+    // 原实现找 `entry._dispose` / `entry.dispose`，但 cordis 的 Entry **两个都没有**
+    // （0.2.0 实测方法集只有 constructor/disabledOf/evaluate/_patchContext/refresh/
+    // update/_commitVolatile/init/_init），所以这里每次都直接返回
+    // "entry exposes no dispose hook" —— 热切换从未真正执行过，而
+    // scheduleSelfReload 里的 `.catch(() => {})` 把它彻底吞掉，
+    // UI 于是永远停在"已落盘但未切换"（用户报的 0.8.35 -> 0.8.36）。
+    //
+    // 也不能用 entry.refresh()：它是 `if (this.fiber) return; await this.init()`，
+    // fiber 还活着时直接返回，等于没重启。真正卸载 fiber 的地方在 Entry.update()
+    // 里（`this.fiber?.dispose()`），这里照它做。
+    //
+    // 保留对 _dispose/dispose 的探测：那是宿主可能提供的扩展钩子，有则优先用，
+    // 没有就用 fiber.dispose()——两条路都必须能真正卸载，否则应如实报错。
     if (typeof entry._dispose === 'function') await entry._dispose()
     else if (typeof entry.dispose === 'function') await entry.dispose()
+    else if (entry.fiber && typeof entry.fiber.dispose === 'function') await entry.fiber.dispose()
     else return { ok: false, reason: 'entry exposes no dispose hook' }
     await entry.init()
     return { ok: true, cleared }
@@ -393,18 +409,38 @@ export async function reloadSelf(loader) {
 /**
  * Fire-and-forget {@link reloadSelf} after a short delay, so the caller can
  * finish answering an HTTP request (or an update check) before its own module is
- * torn down. Failures are swallowed: a failed swap leaves the running code in
- * place, which is the pre-hot-update behaviour, not a crash.
+ * torn down. A failed swap leaves the running code in place, which is the
+ * pre-hot-update behaviour, not a crash — so we do not throw.
+ *
+ * We DO record the outcome, though. Silently discarding it is precisely how the
+ * "entry exposes no dispose hook" defect stayed invisible: the panel reported a
+ * scheduled swap, the swap never ran, and nothing anywhere said so.
+ * {@link lastSelfReload} exposes the result for diagnostics (the settings panel
+ * and `/dsh-remote/update-check` surface it), and a non-ok result is logged once.
+ *
  * @param loader - the cordis Loader service.
  * @param delayMs - grace period before the swap (default 300 ms).
  * @returns true when the swap was scheduled.
  */
 export function scheduleSelfReload(loader, delayMs = 300) {
-  const timer = setTimeout(() => { void reloadSelf(loader).catch(() => {}) }, Math.max(0, delayMs))
+  const timer = setTimeout(() => {
+    void reloadSelf(loader).then(
+      (res) => { lastReloadResult = res; if (res && res.ok === false) console.warn('[dsh-remote] self-update swap failed:', res.reason) },
+      (err) => { lastReloadResult = { ok: false, reason: String((err && err.message) || err) }; console.warn('[dsh-remote] self-update swap threw:', lastReloadResult.reason) },
+    )
+  }, Math.max(0, delayMs))
   if (typeof timer.unref === 'function') timer.unref()
   return true
 }
 
+/** Result of the most recent {@link scheduleSelfReload} attempt, for diagnostics. */
+let lastReloadResult = null
+
+/** @returns the last self-reload outcome (`{ok,reason?}`, or null if never attempted). */
+export function lastSelfReload() {
+  return lastReloadResult
+}
+
 /** Write the persisted update-mode override (settings UI). */
 export function persistUpdateMode(mode) {
   if (!['manual', 'auto', 'off'].includes(mode)) return false