dsh-remote 0.8.34 → 0.8.36

package/lib/index.js

@@ -31,7 +31,7 @@ import {
   toShellPath, toDisplayPath, remotePathBase, truncate, shortHash,
 } from './paths.js'
 import { createHostKeyGuard, isHostKeyKnown as _isHostKeyKnown } from './hostkey.js'
-import { compileIgnore, DEFAULT_IGNORE } from './ignore.js'
+import { compileIgnore, DEFAULT_IGNORE, DEFAULT_SEARCH_IGNORE } from './ignore.js'
 import { friendlyMessage } from './errors.js'
 import { importableEntries, sshConfigPath, readSshConfigText, resolveMachineSshConfig } from './sshconfig.js'
 import { createRemoteFileReference, installFileReferenceOverlay, DEFAULT_EXCLUDED_DIRECTORIES } from './file-reference.js'
@@ -41,6 +41,12 @@ 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 { 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, 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'
@@ -134,6 +140,14 @@ export const Config = z.object({
   /** Wall-clock budget (ms) for one remote `@` index pass; on expiry the
    *  partial index answers rather than making the caret wait. */
   fileReferenceTimeoutMs: z.number().step(1).min(200).default(4000),
+  /** Cooperative budget (ms) for `rw_search`; also declared as the tool's
+   *  `timeoutMs` so @deepseek-ai/dsh-tool-call-timeout-policy can end a call
+   *  that overruns. The search itself stops at this budget and returns partial
+   *  results (issue #44: an unbounded walk over a home directory could never be
+   *  stopped and left the turn `running` forever). */
+  searchTimeoutMs: z.number().step(1).min(1000).default(60000),
+  /** Max files `rw_search` will stat/read before returning partial results. */
+  searchMaxEntries: z.number().step(1).min(1).default(50000),
   /** Update mode: `auto` (default) checks on load and periodically, applies a
    * newer npm release automatically, then hot-swaps the host half (see
    * `updateAutoReload`); `manual` only checks when the user asks; `off` disables
@@ -152,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) ───────────
@@ -367,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
@@ -734,6 +810,9 @@ export async function apply(ctx, config) {
   }
 
   // ── ignore rules (defaults + user file) ───────────────────────────────────
+  // NOTE: this matcher is shared by mirror sync (rw_sync/rw_push) and search.
+  // Do NOT add search-only cache excludes here: widening it would silently stop
+  // syncing directories a user may rely on. Search uses searchIgnoreMatcher().
   const ignoreMatcher = () => {
     try {
       const fromFile = readFileSync(ignoreFile(), 'utf8').split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'))
@@ -742,6 +821,18 @@ export async function apply(ctx, config) {
       return compileIgnore(DEFAULT_IGNORE)
     }
   }
+  /** Search-only matcher: same as ignoreMatcher() plus machine-local cache trees
+   *  (`~/.npm`, `~/.cache`, …) that are huge, almost never what a human is
+   *  looking for, and the main cause of the issue #44 hang. Mirror sync is
+   *  deliberately unaffected. An explicit `path` still searches anywhere. */
+  const searchIgnoreMatcher = () => {
+    try {
+      const fromFile = readFileSync(ignoreFile(), 'utf8').split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'))
+      return compileIgnore(DEFAULT_SEARCH_IGNORE.concat(fromFile))
+    } catch {
+      return compileIgnore(DEFAULT_SEARCH_IGNORE)
+    }
+  }
 
   // ── task + forward managers ───────────────────────────────────────────────
   const tasks = new TaskManager()
@@ -749,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
@@ -1593,21 +1698,44 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_edit',
       description:
-        'Edit a remote text file by replacing literal text (read-modify-write with an mtime optimistic lock: aborts if the file changed on the remote between read and write). Path is absolute.',
+        'Edit a remote text file by replacing literal text (read-modify-write with an mtime optimistic lock: aborts if the file changed on the remote between read and write). Path is absolute. Accepts the aliases old_string/new_string (and file_path for path), matching the host edit tool, so either spelling works.',
       parameters: {
-        path: { type: 'string', required: true, description: 'Absolute remote file path' },
-        old: { type: 'string', required: true, description: 'Literal text to replace (must appear exactly once unless count is given)' },
-        new: { type: 'string', required: true, description: 'Replacement text' },
+        // `path`/`old`/`new` also accept the host edit tool's spellings
+        // (file_path/old_string/new_string): models habitually use those, and a
+        // schema-level `required` on only one spelling rejects the other before
+        // execute() ever runs. So NONE of them is declared required here — the
+        // resolver below enforces "path + old + new" and reports which spelling
+        // to pass. Keep this in sync: adding `required: true` back to any of
+        // these silently breaks its alias.
+        path: { type: 'string', description: 'Absolute remote file path (alias: file_path)' },
+        old: { type: 'string', description: 'Literal text to replace (must appear exactly once unless count is given). Alias: old_string' },
+        new: { type: 'string', description: 'Replacement text; an empty string deletes the old text. Alias: new_string' },
+        old_string: { type: 'string', description: 'Alias of old (same meaning)' },
+        new_string: { type: 'string', description: 'Alias of new (same meaning)' },
+        file_path: { type: 'string', description: 'Alias of path (same meaning)' },
         count: { type: 'integer', description: 'How many occurrences to replace (default: error if the text appears more than once)' },
         encoding: { type: 'string', description: 'Text encoding, e.g. utf-8 (default) or gbk' },
       },
       output: okOut,
       async execute(args, exec) {
         const b = requireMachine(exec, 'rw_edit')
-        const p = resolveRemoteArg(b, args.path)
-        if (!p || p === '/') throw new Error('rw_edit: a file path is required')
-        const oldS = String(args.old ?? '')
-        const newS = String(args.new ?? '')
+        // Presence must be checked on the RAW argument, not on the resolved
+        // path: resolveRemoteArg falls back to the workspace root for an empty
+        // string, so `!p` would never fire and a pathless rw_edit would silently
+        // target the workspace root. (That is why `path` cannot simply lose its
+        // schema `required` without this check replacing it.)
+        const rawPath = args.path ?? args.file_path
+        if (rawPath == null || String(rawPath).trim() === '') {
+          throw new Error('rw_edit: a file path is required — pass path (alias: file_path)')
+        }
+        const p = resolveRemoteArg(b, rawPath)
+        if (!p || p === '/') throw new Error('rw_edit: a file path is required — pass path (alias: file_path)')
+        const oldRaw = args.old ?? args.old_string
+        const newRaw = args.new ?? args.new_string
+        if (oldRaw == null) throw new Error('rw_edit: old text is required — pass old (alias: old_string)')
+        if (newRaw == null) throw new Error('rw_edit: replacement text is required — pass new (alias: new_string); use an empty string to delete the old text')
+        const oldS = String(oldRaw)
+        const newS = String(newRaw)
         if (oldS === '') throw new Error('rw_edit: old text must not be empty')
         const sftp = await b.pool.sftp()
         const st0 = await sftp.stat(p)
@@ -1772,6 +1900,7 @@ export async function apply(ctx, config) {
           if (!parts.length) parts.push('(no output)')
           let text = parts.join('\n')
           if (res.signal === 'TIMEOUT') text += `\n[command timed out after ${config.commandTimeoutMs}ms]`
+          else if (res.signal === 'ABORTED') text += '\n[cancelled — the remote command was stopped]'
           else if (res.code !== 0) text += `\n[exit code: ${res.code}]`
           return { text }
         } catch (err) {
@@ -1783,7 +1912,12 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_search',
       description:
-        'Search remote files for a pattern. POSIX remotes try `rg` then `grep -R` first; Windows and fallbacks use a portable SFTP walk. Honors ignore rules. Returns matching file:line rows; output is capped.',
+        'Search remote files for a pattern. POSIX remotes try `rg` then `grep -R` first; Windows and fallbacks use a portable SFTP walk. Honors ignore rules. Returns matching file:line rows; output is capped. Search is bounded (maxEntries/maxDurationMs) and can be cancelled: on a very large tree it returns partial results marked TRUNCATED instead of running indefinitely.',
+      // A cooperative budget for @deepseek-ai/dsh-tool-call-timeout-policy.
+      // Only useful together with the cancellation support below: the policy can
+      // only *ask* a tool to stop, so a tool that ignores exec.signal would keep
+      // the caller waiting (issue #44).
+      timeoutMs: config.searchTimeoutMs,
       parameters: {
         pattern: { type: 'string', required: true, description: 'Pattern to search for (extended regex)' },
         path: { type: 'string', description: 'Directory to search (default: current remote workspace)' },
@@ -1791,6 +1925,8 @@ export async function apply(ctx, config) {
         ignoreCase: { type: 'boolean', description: 'Case-insensitive search (default true)' },
         contextLines: { type: 'integer', description: 'Lines of context around each match (default 0)' },
         maxMatches: { type: 'integer', description: 'Max matches to return (default 500)' },
+        maxEntries: { type: 'integer', description: 'Stop after scanning this many files (default 50000)' },
+        maxDurationMs: { type: 'integer', description: 'Stop after this many ms and return partial results (default 60000)' },
       },
       output: textOut,
       async execute(args, exec) {
@@ -1807,21 +1943,36 @@ export async function apply(ctx, config) {
           throw new Error('rw_search: bad pattern: ' + ((err && err.message) || err))
         }
         const maxMatches = Math.min(Math.max(Number(args.maxMatches) || 500, 1), 2000)
-        const matcher = ignoreMatcher()
-        const { matches, scanned, truncated } = await searchRemote(b.pool, dir, {
+        // Budgets. The SFTP walk had NO entry/duration cap before, so a search
+        // over a home directory could run for hours while the turn stayed
+        // `running` and cancel/steer did nothing (issue #44).
+        const maxFiles = Math.min(Math.max(Number(args.maxEntries) || config.searchMaxEntries, 1), 500000)
+        const maxDurationMs = Math.min(Math.max(Number(args.maxDurationMs) || config.searchTimeoutMs, 1000), 600000)
+        const matcher = searchIgnoreMatcher()
+        const { matches, scanned, truncated, cancelled } = await searchRemote(b.pool, dir, {
           pattern,
           regex,
           glob: args.glob,
           ignoreCase: args.ignoreCase !== false,
           contextLines: Math.min(Math.max(Number(args.contextLines) || 0, 0), 10),
           maxMatches,
+          maxFiles,
+          maxDurationMs,
+          signal: exec.signal,
           maxScanBytes: Math.min(config.maxFileBytes || 1024 * 1024, 1024 * 1024),
           isIgnored: (name, isDir) => matcher(name, isDir),
-          timeoutMs: config.commandTimeoutMs,
+          timeoutMs: Math.min(config.commandTimeoutMs, maxDurationMs),
         })
-        if (!matches.length) return { text: `no matches for /${pattern}/ in ${dir} (${scanned} files scanned)` }
+        const note = cancelled
+          ? `, CANCELLED after ${scanned} files scanned`
+          : truncated
+            ? ', TRUNCATED'
+            : ''
+        if (!matches.length) {
+          return { text: `no matches for /${pattern}/ in ${dir} (${scanned} files scanned${note})` }
+        }
         let text = matches.map((m) => `${m.path}:${m.line}: ${m.text}`).join('\n')
-        text += `\n(${matches.length} match(es), ${scanned} files scanned${truncated ? ', TRUNCATED' : ''})`
+        text += `\n(${matches.length} match(es), ${scanned} files scanned${note})`
         return { text: truncate(text, config.maxOutputChars) }
       },
     }),
@@ -1885,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:
@@ -2777,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',
@@ -2822,13 +3262,21 @@ export async function apply(ctx, config) {
           // a link:/dev install must not be overwritten by an npm publish.
           selfUpdateAllowed: isInstalledCopy(),
         }
-        const latest = await fetchLatestVersion()
-        if (latest === null) return sendJson(res, 200, { ok: false, ...base, error: '无法连接 npm registry' })
+        const probe = await fetchLatestVersion()
+        // 即使查不到最新版，也把**本地状态**照常返回（ok:true），只把 registry
+        // 的失败原因放在 registryError 里。
+        //
+        // 为什么：原先 registry 失败时整条响应 ok:false，客户端遇到 !ok 就只设错误
+        // 文案、不 setUpd，于是面板永远停在「版本信息加载中…」——看起来像卡死，
+        // 而实际上本地版本、更新模式、是否允许自更新都是已知的，完全可以展示。
+        if (probe.error) {
+          return sendJson(res, 200, { ok: true, ...base, latest: null, updateAvailable: false, registryError: probe.error, registryReason: probe.reason })
+        }
         return sendJson(res, 200, {
           ok: true,
           ...base,
-          latest,
-          updateAvailable: gtVersion(latest, loaded),
+          latest: probe.version,
+          updateAvailable: gtVersion(probe.version, loaded),
         })
       },
     },
@@ -2897,6 +3345,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
@@ -2904,9 +3361,20 @@ export async function apply(ctx, config) {
   const rawMode = readUpdateMode() || config.updateMode || DEFAULT_UPDATE_MODE
   const effectiveUpdateMode = ['manual', 'auto', 'off'].includes(rawMode) ? rawMode : DEFAULT_UPDATE_MODE
   if (effectiveUpdateMode === 'auto') {
+    // 限流/网络失败后的退避：命中后跳过接下来若干轮检查，避免在被 npm 限流
+    // （HTTP 429）时反复重试把配额烧得更久。指数增长，上限 24 轮（配合默认
+    // 6h 间隔即最多约 6 天，足以让限流窗口滑过且不会永久停摆）。
+    let backoffRounds = 0
     const checkAndApply = async () => {
-      const latest = await fetchLatestVersion()
-      if (!latest) return
+      if (backoffRounds > 0) { backoffRounds -= 1; return }
+      const probe = await fetchLatestVersion()
+      if (probe.error) {
+        // 限流与网络故障都要退避；成功一次即重置。
+        backoffRounds = Math.min(backoffRounds === 0 ? 1 : backoffRounds * 2, 24)
+        return
+      }
+      backoffRounds = 0
+      const latest = probe.version
       // The version in flight is whichever of "already on disk" / "already
       // loaded" is newer. Pinning it once outside this closure (as v0.8.23 did)
       // made every later interval re-download and re-apply the same tarball,