dsh-dbhub-live 5.0.1 → 5.2.0-dev.3

package/lib/index.mjs

@@ -39,14 +39,26 @@ import {
 import {
   activeToolCount, refreshToolCount,
   collectSources, latestSummaries, hasRowCache, createRowMirror,
+  cachedRows, resolveTestDsn,
 } from './mcp.mjs'
 import { registerCoreTools } from './tools.mjs'
-import { probeConnection } from './adhoc.mjs'
+import { registerDbhubPolicy } from './policy.mjs'
+import { probeConnection, probeSshTunnel, hostTimeoutFor, PROBE_TIMEOUT_SSH_MS, defaultKeyNoteOf } from './adhoc.mjs'
+import { sweepTempToml } from './toml.mjs'
+import { detectDbhubCapabilities } from './capability.mjs'
+import { resolveDbhubExe } from './runtime.mjs'
 import { createBridgeRoutes, BRIDGE_BASE } from './bridge.mjs'
 import {
-  listWorkspaces, setWorkspaceEnv, removeWorkspaceEnv, renameWorkspaceEnv, normalizeEnvName,
+  store, listWorkspaces, setWorkspaceEnv, setWorkspaceEnvOptions, removeWorkspaceEnv,
+  renameWorkspaceEnv, normalizeEnvName, listWorkspaceEnvironments, resolveWorkspaceEnvs,
+  normalizeSshOptions, mergeSshOptions,
 } from './config.mjs'
 import { setLocaleProvider, currentT } from './i18n.mjs'
+// Version metadata (plugin/dsh/runtime) and the plugin self-update check are
+// leaf modules (node builtins only), so importing them here cannot create a
+// dependency cycle.
+import { versionMeta } from './meta.mjs'
+import { createUpdateChecker } from './update.mjs'
 import * as state from './state.mjs'
 import * as options from './options.mjs'
 
@@ -71,11 +83,19 @@ const STATUS_DEFAULTS = {
   lastError: '',
   mode: 'oneshot',
   updateIntervalDays: 7,
-  // Whether the browser half contributes its own sidebar entry; the settings
-  // page renders the switch (the page itself is a settings section and the
-  // plugin's row on the Plugins page, so hiding the entry never locks anyone
-  // out of the configuration).
+  // The user's own choice to hide the sidebar shortcut while the plugin keeps
+  // working. The browser ANDs it with `enabled`: disabling the plugin hides the
+  // entry no matter what this says, and hiding the entry never disables anything
+  // (the settings page and the Plugins row stay reachable either way).
   showSidebarEntry: true,
+  // The user's own choice to let the plugin contribute its database-access
+  // policy to the system prompt (default ON). It removes that section only:
+  // every tool keeps working, and a disabled plugin contributes nothing anyway.
+  announceAccessPolicy: true,
+  // Upstream dbhub capability probe (JSON string: {version, readonlyTools, ssh,
+  // warning}). The UI uses it to disable the read-only / SSH controls with a
+  // reason instead of letting the user configure something that cannot work.
+  capabilities: '',
   // Workspace-connection summaries ride as a JSON string so the schema never
   // has to validate their arbitrary shape; `configOp` is the one-way command
   // channel from the card (host consumes it and republishes without it).
@@ -86,6 +106,14 @@ const STATUS_DEFAULTS = {
   // persisted anywhere — the card only shows it while its own pending nonce
   // matches (a reload drops the pending map, so the result cannot stick).
   testResult: '',
+  // Version / update metadata (lib/meta.mjs, lib/update.mjs). `update` rides as
+  // a JSON string like `workspaces` — it is '' until the card asks for its first
+  // check, so boot never waits on the network. Nothing here is secret.
+  pluginVersion: '',
+  dshVersion: '',
+  dshModern: false,
+  runtime: 'web',
+  update: '',
 }
 
 // Prefer the real schemastery schema (standard path, present in every dsh
@@ -110,9 +138,16 @@ try {
     mode: z.string().default(STATUS_DEFAULTS.mode),
     updateIntervalDays: z.number().min(0).default(STATUS_DEFAULTS.updateIntervalDays),
     showSidebarEntry: z.boolean().default(STATUS_DEFAULTS.showSidebarEntry),
+    announceAccessPolicy: z.boolean().default(STATUS_DEFAULTS.announceAccessPolicy),
+    capabilities: z.string().default(STATUS_DEFAULTS.capabilities),
     workspaces: z.string().default(STATUS_DEFAULTS.workspaces),
     configOp: z.string().default(STATUS_DEFAULTS.configOp),
     testResult: z.string().default(STATUS_DEFAULTS.testResult),
+    pluginVersion: z.string().default(STATUS_DEFAULTS.pluginVersion),
+    dshVersion: z.string().default(STATUS_DEFAULTS.dshVersion),
+    dshModern: z.boolean().default(STATUS_DEFAULTS.dshModern),
+    runtime: z.string().default(STATUS_DEFAULTS.runtime),
+    update: z.string().default(STATUS_DEFAULTS.update),
   })
   // schemastery 3.18.2 (shipped with dsh 0.1.6) has no `.volatile()`; the guard
   // keeps the declaration valid there, where the fields arrive as plain values.
@@ -123,6 +158,7 @@ try {
   CONFIG_SCHEMA = z.object({
     updateIntervalDays: volatileField(z.number().min(0)),
     showSidebarEntry: volatileField(z.boolean()),
+    announceAccessPolicy: volatileField(z.boolean()),
   })
 } catch (e) {
   const fallbackSchema = (value) => {
@@ -177,11 +213,11 @@ async function resolveWorkspaceRef(ref, ctx) {
   return workspaces[0] || undefined
 }
 
-// Hard cap for one card connection test (the probe is a throwaway dbhub +
-// SELECT 1; the timeout also kills the spawned process when it fires). Must be
-// comfortably BELOW the client-side watchdog so the {nonce, ok, message}
-// report always wins the race against "测试超时未返回" (15s == 15s lost races).
-const TEST_TIMEOUT_MS = 25000
+// Hard cap for one card connection test: the probe is a throwaway dbhub +
+// SELECT 1, and the tiered budget comes from adhoc.mjs (`hostTimeoutFor`) — a
+// tunnelled probe gets more room because SSH setup is slower. It must stay
+// comfortably BELOW the client-side watchdog (which is tiered to match) so the
+// {nonce, ok, message} report always wins the race against "测试超时未返回".
 
 // Backstop: even if the underlying dbhub spawn never settles (subprocess-
 // service hiccup), the card ALWAYS receives a report inside the probe budget
@@ -201,13 +237,20 @@ function withProbeTimeout(promise, ms) {
   })
 }
 
-// One card connection test: { op: 'test', workspace, env, nonce }. Resolves
-// the REAL DSN host-side (the card only ever holds the masked summary), then
-// probes it through an isolated ad-hoc connection — the persistent server is
+// One card connection test: { op: 'test', workspace, env, nonce } (+ optional
+// `dsn` / `readOnly` / `ssh` for a PRE-SAVE validation of unsaved options).
+// Resolves the REAL DSN host-side (the card only ever holds the masked summary),
+// then probes it through an isolated ad-hoc connection — the persistent server is
 // never restarted or otherwise touched, and a failure only ever means a red
 // line on the card. The compact {nonce, ok, message} report goes back through
 // `reportTest` (the transient namespace `testResult` field); nothing is
 // persisted.
+//
+// F4: resolving WHICH dsn to probe must not re-walk every workspace. A persisted
+// row is read straight from the store, a row the card already displays comes
+// from the in-memory mirror, and only a genuinely never-walked environment
+// triggers the discovery walk. Two milestone logs carry the two segments so the
+// split is observable on a real machine.
 async function handleTestOp(op, ctx, subprocess, ws, reportTest) {
   const nonce = typeof op.nonce === 'string' ? op.nonce : ''
   const report = (ok, message) => {
@@ -218,6 +261,22 @@ async function handleTestOp(op, ctx, subprocess, ws, reportTest) {
       /* the callback is ours; never let reporting break the op chain */
     }
   }
+  // Unsaved options the card wants validated together with the connection (the
+  // SSH panel and the read-only switch both use this).
+  const opHasOptions = op.readOnly !== undefined || (op.ssh && typeof op.ssh === 'object')
+  const opOptions = {
+    ro: op.readOnly === true,
+    ssh: op.ssh && typeof op.ssh === 'object' ? op.ssh : null,
+  }
+  const probeOnce = async (conn, envName, wsTitle, tag) => {
+    const timeoutMs = hostTimeoutFor(conn)
+    const started = Date.now()
+    const res = await withProbeTimeout(probeConnection(subprocess, conn, timeoutMs), timeoutMs)
+    console.log('[dsh-dbhub-live] ' + currentT('log.testProbeMs', { ms: String(Date.now() - started) }))
+    report(res.ok, res.message)
+    if (!res.ok) console.error('[dsh-dbhub-live] ' + currentT('log.testDone', { title: wsTitle, env: envName, result: 'FAIL' + tag + ' — ' + res.message }))
+    else console.log('[dsh-dbhub-live] ' + currentT('log.testDone', { title: wsTitle, env: envName, result: 'OK' + tag + ' — ' + res.message }))
+  }
   try {
     // Pre-save validation path: {op:'test', dsn, nonce, workspace, env} — the
     // card gates the "add/save" button on a live probe, so an unpersisted DSN
@@ -226,49 +285,204 @@ async function handleTestOp(op, ctx, subprocess, ws, reportTest) {
     // user typed (the masked-card flow still works: `dsn` is left blank and
     // we look up the row by workspace + env like before).
     const inlineDsn = typeof op.dsn === 'string' && op.dsn.trim() ? op.dsn.trim() : ''
-    if (inlineDsn) {
-      if (!ws) {
-        report(false, currentT('log.opNoWs', { ws: String(op.workspace || '') }))
+    if (!ws) {
+      report(false, currentT('log.opNoWs', { ws: String(op.workspace || '') }))
+      return
+    }
+    const envName = normalizeEnvName(op.env)
+    // ── SSH-layer-only test ({op:'test', kind:'ssh'}) ────────────────────────
+    // Answers "is it the tunnel or the database?": reachability of the bastion,
+    // the local key file, and whether dbhub can bring the tunnel up at all. The
+    // ssh block comes from the form (unsaved) or, for a saved row, from the
+    // store — resolved WITHOUT a discovery walk.
+    if (op.kind === 'ssh') {
+      const fromCard = op.ssh && typeof op.ssh === 'object' ? op.ssh : null
+      let ssh = fromCard
+      {
+        // Same "blank secret = keep the stored one" rule as the options write:
+        // testing a saved tunnel from the row editor must not fail just because
+        // the form (correctly) refuses to echo the password back.
+        const saved = listWorkspaceEnvironments(store).find((r) => r.wsPath === ws.path && r.env === envName)
+        ssh = mergeSshOptions(ssh || (saved ? saved.ssh : null), saved ? saved.ssh : null)
+      }
+      console.log('[dsh-dbhub-live] ' + currentT('log.testStart', { title: ws.title, env: envName }) + ' (SSH)')
+      if (!ssh) {
+        report(false, currentT('result.sshTestNoConfig'))
         return
       }
-      const envName = String(op.env == null ? '' : op.env).trim() || 'default'
-      console.log('[dsh-dbhub-live] ' + currentT('log.testStart', { title: ws.title, env: envName }) + ' (预校验)')
-      const res = await withProbeTimeout(probeConnection(subprocess, inlineDsn, TEST_TIMEOUT_MS), TEST_TIMEOUT_MS)
-      report(res.ok, res.message)
-      if (!res.ok) console.error('[dsh-dbhub-live] ' + currentT('log.testDone', { title: ws.title, env: envName, result: 'FAIL(预校验) — ' + res.message }))
-      else console.log('[dsh-dbhub-live] ' + currentT('log.testDone', { title: ws.title, env: envName, result: 'OK — ' + res.message }))
+      const started = Date.now()
+      const res = await withProbeTimeout(probeSshTunnel(subprocess, ssh, PROBE_TIMEOUT_SSH_MS), PROBE_TIMEOUT_SSH_MS)
+      console.log('[dsh-dbhub-live] ' + currentT('log.testProbeMs', { ms: String(Date.now() - started) }))
+      // The merge above may have filled the conventional identity path, which the
+      // probe can no longer detect on its own — so the note is computed against
+      // what the CARD sent (only when it sent a tunnel block at all).
+      const note = fromCard ? defaultKeyNoteOf(fromCard, ssh) : ''
+      report(res.ok, res.message + note)
+      const line = currentT('log.testDone', { title: ws.title, env: envName, result: (res.ok ? 'OK' : 'FAIL') + '(SSH) — ' + res.message + note })
+      if (res.ok) console.log('[dsh-dbhub-live] ' + line)
+      else console.error('[dsh-dbhub-live] ' + line)
       return
     }
-    if (!ws) {
-      report(false, currentT('log.opNoWs', { ws: String(op.workspace || '') }))
+    if (inlineDsn) {
+      console.log('[dsh-dbhub-live] ' + currentT('log.testStart', { title: ws.title, env: envName }) + ' (预校验)')
+      await probeOnce({ dsn: inlineDsn, ro: opOptions.ro, ssh: opOptions.ssh }, envName, ws.title, '(预校验)')
       return
     }
-    const envName = String(op.env == null ? '' : op.env).trim() || 'default'
     console.log('[dsh-dbhub-live] ' + currentT('log.testStart', { title: ws.title, env: envName }))
-    const { rows } = await collectSources(ctx, subprocess)
-    const row = rows.find((r) => r.wsPath === ws.path && r.env === envName)
-    if (!row) {
+    // ── F4 fast path: store → already-cached row → (only then) a real walk ──
+    const resolveStarted = Date.now()
+    const storeRows = listWorkspaceEnvironments(store)
+    let picked = resolveTestDsn({
+      wsPath: ws.path,
+      env: envName,
+      storeRows,
+      cachedRows: cachedRows(),
+      hasCache: hasRowCache(),
+    })
+    if (!picked) {
+      await collectSources(ctx, subprocess)
+      // Re-read the store: a card write can land while the walk runs, and the
+      // post-walk answer must not be older than the walk itself.
+      picked = resolveTestDsn({
+        wsPath: ws.path,
+        env: envName,
+        storeRows: listWorkspaceEnvironments(store),
+        cachedRows: cachedRows(),
+        hasCache: hasRowCache(),
+      })
+    }
+    console.log('[dsh-dbhub-live] ' + currentT('log.testWalkMs', {
+      ms: String(Date.now() - resolveStarted),
+      from: picked ? picked.from : 'walk-miss',
+    }))
+    if (!picked) {
       report(false, currentT('result.testNoRow'))
       console.log('[dsh-dbhub-live] ' + currentT('log.testDone', { title: ws.title, env: envName, result: 'FAIL — ' + currentT('result.testNoRow') }))
       return
     }
-    const res = await withProbeTimeout(probeConnection(subprocess, row.dsn, TEST_TIMEOUT_MS), TEST_TIMEOUT_MS)
-    report(res.ok, res.message)
-    if (!res.ok) console.error('[dsh-dbhub-live] ' + currentT('log.testDone', { title: ws.title, env: envName, result: 'FAIL — ' + res.message }))
-    else console.log('[dsh-dbhub-live] ' + currentT('log.testDone', { title: ws.title, env: envName, result: 'OK — ' + res.message }))
+    // An unsaved option (or tunnel) the card is validating wins over the stored
+    // one; otherwise the row's own options are what execution would use.
+    const conn = opHasOptions
+      ? { dsn: picked.dsn, ro: opOptions.ro, ssh: opOptions.ssh }
+      : { dsn: picked.dsn, ro: picked.ro, ssh: picked.ssh }
+    await probeOnce(conn, envName, ws.title, '')
   } catch (e) {
     console.error('[dsh-dbhub-live] 卡片连接测试异常: ' + String((e && e.stack) || e))
     report(false, String((e && e.message) || e))
   }
 }
 
-// One card command: { op: 'add'|'remove', workspace, env, dsn? } or
-// { op: 'test', workspace, env, nonce } (connection probe, zero side effects).
+// One card command: { op: 'add'|'set'|'options'|'rename'|'remove', … } or
+// { op: 'test', … } (connection probe, zero side effects).
 // `publishFast` mirrors a completed write from the cached rows right away; the
 // caller publishes the walked result afterwards. Returns the applied patches
 // (empty for a probe or a no-op) so the caller can mirror them immediately too.
 // `rawOp` is the encoded command the settings-document channel carries and the
 // decoded object the HTTP bridge carries.
+
+/**
+ * Translate the option fields of one card command into a store patch.
+ * `undefined` when the command carries no option information at all — which
+ * means "preserve whatever the entry already had" (D4).
+ * `ssh: null` is the explicit "clear the tunnel" signal, so it must survive as
+ * a defined null rather than being dropped.
+ */
+function optionsPatchOf(op) {
+  const patch = {}
+  // Only a real boolean counts: a malformed `readOnly: 'yes'` must be a no-op
+  // rather than silently CLEARING a user's safety switch.
+  if (op && op.readOnly === true) patch.readOnly = true
+  else if (op && op.readOnly === false) patch.readOnly = false
+  if (op && op.ssh !== undefined) patch.ssh = op.ssh === null ? null : op.ssh
+  return Object.keys(patch).length > 0 ? patch : undefined
+}
+
+/** One persisted store row by workspace path × environment (host-side). */
+function findRow(wsPath, env) {
+  const name = normalizeEnvName(env)
+  return listWorkspaceEnvironments(store).find((r) => r.wsPath === wsPath && r.env === name)
+}
+
+/**
+ * Apply one options-only card command (the read-only switch and/or the SSH
+ * tunnel) and return the mirror patches.
+ *
+ * The write never touches the DSN — the UI has no connection data to offer when
+ * a user flips a checkbox, and demanding one would make them re-type a password.
+ * An environment that only AUTO-DISCOVERY knows has no store row to hold the
+ * options, so it is promoted to a persisted row from the DSN the walk just
+ * resolved (D10) — and strictly on this explicit action (listing, querying and
+ * publishing never promote anything).
+ *
+ * Exported for the unit tests: it is pure with respect to its inputs, takes the
+ * auto-discovery lookup as a parameter, and performs no publishing of its own.
+ *
+ * @param op - `{ env, readOnly?, ssh?, newEnv? }`.
+ * @param ws - `{ path, title }` of the already-resolved workspace.
+ * @param lookupAuto - `async (envName) => ({ env, dsn } | undefined)`.
+ * @returns `{ patches, row?, error? }`.
+ */
+export async function applyOptionsOp(op, ws, lookupAuto) {
+  const patches = []
+  const patch = optionsPatchOf(op)
+  const requestedName = normalizeEnvName(op.env)
+  // "Blank secret = keep the stored value": the card cannot echo a password back,
+  // so an edit that only touches the host/user/port arrives without one. Merge
+  // with the stored block BEFORE validating, or a legitimate edit would be
+  // rejected as an incomplete tunnel.
+  if (patch && patch.ssh) {
+    const existing = findRow(ws.path, requestedName)
+    patch.ssh = mergeSshOptions(patch.ssh, existing ? existing.ssh : null)
+    if (!normalizeSshOptions(patch.ssh)) return { patches: [], error: 'badSsh' }
+  }
+  let envName = requestedName
+  // An options write may ALSO rename: one atomic command, so the two changes
+  // cannot race on the single `configOp` field. The rename runs first and the
+  // options then land on the new name.
+  const newEnv = op.newEnv === undefined || op.newEnv === null ? '' : normalizeEnvName(op.newEnv)
+  if (newEnv && newEnv !== requestedName) {
+    const moved = renameWorkspaceEnv(ws.path, requestedName, newEnv)
+    if (moved) {
+      envName = moved
+      patches.push({ op: 'rename', path: ws.path, env: moved, from: requestedName })
+      console.log('[dsh-dbhub-live] ' + currentT('log.opRenamed', { title: ws.title, from: requestedName, to: moved }))
+    }
+  }
+  let name = setWorkspaceEnvOptions(ws.path, envName, patch || {})
+  if (!name) {
+    let auto
+    try {
+      auto = await lookupAuto(envName)
+    } catch (e) {
+      auto = undefined
+    }
+    if (!auto) {
+      // A rename that already landed is still a real store change: report it
+      // rather than dropping the patch (the card would keep showing the old
+      // name until some later walk).
+      return { patches, error: 'needConnFirst' }
+    }
+    name = setWorkspaceEnv(ws.path, envName, auto.dsn, 'promoted', patch)
+    const promotedRow = findRow(ws.path, name)
+    patches.push({
+      op: 'add', path: ws.path, title: ws.title, env: name, dsn: auto.dsn, source: 'promoted',
+      ro: promotedRow ? promotedRow.ro : false, ssh: promotedRow ? promotedRow.ssh : null,
+    })
+  }
+  const row = findRow(ws.path, name)
+  patches.push({
+    op: 'options', path: ws.path, env: name,
+    ro: row ? row.ro : false, ssh: row ? row.ssh : null,
+  })
+  const roText = row && row.ro ? 'on' : 'off'
+  const sshText = row && row.ssh ? (row.ssh.host + ':' + row.ssh.port) : 'off'
+  console.log('[dsh-dbhub-live] ' + currentT('log.opOptions', { title: ws.title, env: name, ro: roText, ssh: sshText }))
+  if (row && row.ssh) {
+    console.log('[dsh-dbhub-live] ' + currentT('log.sshTunnelUp', { title: ws.title, env: name, host: row.ssh.host, port: String(row.ssh.port), user: row.ssh.user }))
+  }
+  return { patches, row }
+}
+
 async function handleConfigOp(rawOp, ctx, subprocess, reportTest, publishFast) {
   const patches = []
   let op
@@ -305,9 +519,25 @@ async function handleConfigOp(rawOp, ctx, subprocess, reportTest, publishFast) {
         }
       }
       const source = op.source === 'collected' ? 'collected' : 'user'
-      const envName = setWorkspaceEnv(ws.path, op.env, dsn, source)
-      patches.push({ op: 'add', path: ws.path, title: ws.title, env: envName, dsn, source })
+      const opts = optionsPatchOf(op)
+      const envName = setWorkspaceEnv(ws.path, op.env, dsn, source, opts)
+      const row = findRow(ws.path, envName)
+      patches.push({
+        op: 'add', path: ws.path, title: ws.title, env: envName, dsn, source,
+        ro: row ? row.ro : false, ssh: row ? row.ssh : null,
+      })
       console.log('[dsh-dbhub-live] ' + currentT('log.opSaved', { title: ws.title, env: envName }))
+    } else if (op.op === 'options') {
+      const result = await applyOptionsOp(op, ws, async (envName) => {
+        const envs = await resolveWorkspaceEnvs(subprocess, ctx.get('fs'), ws.path, undefined)
+        return envs.find((r) => r.env === envName)
+      })
+      if (result.error === 'needConnFirst') {
+        console.warn('[dsh-dbhub-live] ' + currentT('result.needConnFirst') + '（' + ws.title + ' / ' + normalizeEnvName(op.env) + '）')
+      } else if (result.error === 'badSsh') {
+        console.warn('[dsh-dbhub-live] SSH 配置无效（缺少主机/用户/凭据或为多跳），已忽略：' + String(op.env || 'default'))
+      }
+      patches.push(...result.patches)
     } else if (op.op === 'rename') {
       const from = op.env
       const to = op.newEnv
@@ -341,6 +571,22 @@ async function handleConfigOp(rawOp, ctx, subprocess, reportTest, publishFast) {
   return patches
 }
 
+// Card commands arrive as an object (the HTTP bridge posts `{ op: <command> }`)
+// or as a JSON string (on 0.1.x the settings document carries the single string
+// field `configOp`). Normalize both shapes in one place so the early
+// `updateCheck` branch in runOp can read the command; anything unparsable falls
+// through to handleConfigOp, which owns the "bad op" warning.
+function opObjectOf(rawOp) {
+  if (rawOp && typeof rawOp === 'object') return rawOp
+  if (typeof rawOp !== 'string') return undefined
+  try {
+    const parsed = JSON.parse(rawOp)
+    return parsed && typeof parsed === 'object' ? parsed : undefined
+  } catch (e) {
+    return undefined
+  }
+}
+
 // ── live host core: one merged view, fanned out to every active channel ───
 //
 // Publishing is channel-independent: the 0.1.x settings namespace and the HTTP
@@ -355,18 +601,39 @@ function createHostCore(ctx) {
   // the latest one; the card surfaces it only for a nonce it itself dispatched,
   // so a page reload silently drops any stale report.
   let lastTestResult = ''
+  // Upstream dbhub capability probe (JSON string; '' until the background probe
+  // finishes). The UI disables the read-only / SSH controls with a reason when
+  // the installed dbhub predates the TOML dialect.
+  let capabilities = ''
   // The card's own writes are held here until a walk that started after them
   // lands (see createRowMirror): a slow walk that began before a write would
   // otherwise publish a list without it, which reads as "the row appeared and
   // then vanished".
   const mirror = createRowMirror()
   const sinks = new Set()
+  // Version metadata and the plugin self-update checker are Host-lifetime
+  // singletons: the installed version cannot change under a running process,
+  // and one checker instance is what makes the throttle and the in-flight
+  // dedupe work (a per-request instance would hit the registries on every
+  // publish). `updateJson` is the browser-facing snapshot — a JSON string, ''
+  // until the card asks for its first check, so boot never waits on a network.
+  const meta = versionMeta()
+  const updateChecker = createUpdateChecker({ currentVersion: meta.pluginVersion })
+  let updateJson = ''
+  // checkedAt of the snapshot already written to the log: a throttled check
+  // just reuses the last result, and logging it again on every page mount would
+  // turn the milestone line into noise.
+  let lastLoggedCheckAt = -1
 
   const view = () => ({
     ...state.snapshot(),
     ...options.snapshot(),
+    // pluginVersion / dshVersion / dshModern / runtime — plain strings/booleans.
+    ...meta,
     workspaces: JSON.stringify(latestSummaries()),
     testResult: lastTestResult,
+    capabilities: capabilities,
+    update: updateJson,
     // The browser half needs this to address the plugin's own settings form
     // (`ctx.configForms.get(entryId)`) for option writes; '' when the entry
     // cannot be resolved, in which case it falls back to POST /options.
@@ -446,16 +713,80 @@ function createHostCore(ctx) {
     // A probe changes NO rows: mirror it, do not re-walk the workspaces.
     publishMirror()
   }
+  /** Record the upstream capability probe and republish the (cheap) mirror. */
+  const setCapabilities = (cap) => {
+    try {
+      capabilities = JSON.stringify(cap || {})
+    } catch (e) {
+      capabilities = ''
+    }
+    publishMirror()
+  }
+  /** Capabilities currently advertised to the card (a plain object). */
+  const capabilitiesOf = () => {
+    try {
+      const parsed = JSON.parse(capabilities || '{}')
+      return parsed && typeof parsed === 'object' ? parsed : {}
+    } catch (e) {
+      return {}
+    }
+  }
+  // Answer the card's {op:'updateCheck'} command. The checker owns the throttle
+  // and the in-flight dedupe, so repeated clicks/reloads cost one request burst;
+  // `force` bypasses the throttle (the card's explicit "check now"). The result
+  // is mirrored into `update` and published, then logged once — check() resolves
+  // on every failure and the guard here only covers a future regression.
+  const runUpdateCheck = async (force) => {
+    let snap
+    try {
+      snap = await updateChecker.check(force === true)
+    } catch (e) {
+      snap = {
+        latest: '',
+        latestSpec: '',
+        hasUpdate: false,
+        checkedAt: Date.now(),
+        source: '',
+        error: String((e && e.message) || e),
+      }
+    }
+    updateJson = JSON.stringify(snap)
+    publishMirror()
+    // One line per ACTUAL check; a throttled reuse keeps the previous line.
+    if (snap.checkedAt === lastLoggedCheckAt) return snap
+    lastLoggedCheckAt = snap.checkedAt
+    const current = meta.pluginVersion || '?'
+    if (snap.error) {
+      console.warn('[dsh-dbhub-live] ' + currentT('log.appUpdateFailed', { msg: snap.error, current }))
+    } else if (snap.hasUpdate) {
+      console.log('[dsh-dbhub-live] ' + currentT('log.appUpdate', { current, latest: snap.latest, source: snap.source }))
+    } else {
+      console.log('[dsh-dbhub-live] ' + currentT('log.appUpToDate', {
+        current,
+        latest: snap.latest || '?',
+        source: snap.source || '?',
+      }))
+    }
+    return snap
+  }
   // One card command, from whichever channel carried it. The caller owns the
   // follow-up republish; a write is already mirrored by publishFast.
   const runOp = async (rawOp) => {
+    // `updateCheck` is not a workspace command: no rows change and it touches the
+    // network, so it is intercepted BEFORE handleConfigOp (which would reject an
+    // unknown op). It still resolves [] — a command that patches no row.
+    const command = opObjectOf(rawOp)
+    if (command && command.op === 'updateCheck') {
+      await runUpdateCheck(command.force === true)
+      return []
+    }
     const patches = await handleConfigOp(rawOp, ctx, subprocessOf(), reportTest, publishFast)
     if (Array.isArray(patches) && patches.length > 0) publish()
     else publishMirror()
     return patches
   }
 
-  return { view, onPublish, publish, publishMirror, publishFast, reportTest, runOp }
+  return { view, onPublish, publish, publishMirror, publishFast, reportTest, runOp, setCapabilities, capabilitiesOf }
 }
 
 // ── channel 1: the settings namespace (dsh 0.1.6 and older only) ──────────
@@ -612,10 +943,12 @@ let bootInFlight
 
 // Fire-and-forget one bookkeeping run: mark the plugin 'running' (there is no
 // server to start — each tool call spawns its own disposable dbhub), refresh
-// the tool count, and check for a dbhub auto-update in the background (fails
-// silently; the current binary stays in use). Concurrent calls share the
-// in-flight run. Failures land in the state machine, never block boot.
-function startBackgroundBoot(ctx, subprocess) {
+// the tool count, sweep any generated-config leftovers from a crash, probe the
+// upstream dbhub capabilities for the UI, and check for a dbhub auto-update in
+// the background (fails silently; the current binary stays in use). Concurrent
+// calls share the in-flight run. Failures land in the state machine, never block
+// boot.
+function startBackgroundBoot(ctx, subprocess, core) {
   if (!state.isEnabled() || !subprocess) return undefined
   if (bootInFlight) return bootInFlight
   bootInFlight = (async () => {
@@ -624,6 +957,27 @@ function startBackgroundBoot(ctx, subprocess) {
       state.setPhase('running')
       refreshToolCount()
       console.log('[dsh-dbhub-live] ' + currentT('log.loaded', { n: activeToolCount() }))
+      // Stale generated TOML files (a crash between write and delete) hold no
+      // secrets, but they must not accumulate in the storage dir.
+      try {
+        const swept = sweepTempToml()
+        if (swept > 0) console.log('[dsh-dbhub-live] ' + currentT('log.tomlSwept', { n: String(swept) }))
+      } catch (e) {
+        /* sweeping is best effort */
+      }
+      // Capability probe: purely informational (the UI disables what cannot
+      // work). Never fatal, and it also resolves/installs the executable early
+      // so the first real call does not pay for it.
+      resolveDbhubExe(subprocess).then((exe) => {
+        const cap = detectDbhubCapabilities(exe)
+        if (core && typeof core.setCapabilities === 'function') core.setCapabilities(cap)
+        console.log('[dsh-dbhub-live] dbhub 能力探测: version=' + (cap.version || 'unknown')
+          + ' readonly=' + (cap.readonlyTools ? 'yes' : 'no')
+          + ' ssh=' + (cap.ssh ? 'yes' : 'no')
+          + (cap.warning ? ' warning=' + cap.warning : ''))
+      }).catch((e) => {
+        console.warn('[dsh-dbhub-live] dbhub 能力探测失败: ' + String((e && e.message) || e))
+      })
       maybeRefreshDbhub(subprocess).catch((e) => {
         console.error('[dsh-dbhub-live] ' + currentT('log.updateCheckFailed', { msg: String((e && e.message) || e) }))
       })
@@ -655,6 +1009,10 @@ export async function apply(ctx, config) {
   })
   const subprocess = ctx.get('subprocess')
   registerCoreTools(ctx, subprocess)
+  // The system-prompt policy is what keeps database access on these tools (and
+  // out of psql/scripts); it is optional by design and contributes nothing
+  // while the plugin is disabled.
+  registerDbhubPolicy(ctx)
   refreshToolCount()
 
   // One core, two channels: every state/option change replays the walk, and
@@ -690,7 +1048,7 @@ export async function apply(ctx, config) {
     return
   }
   if (state.isEnabled()) {
-    startBackgroundBoot(ctx, subprocess).catch(() => {
+    startBackgroundBoot(ctx, subprocess, core).catch(() => {
       /* recorded in state */
     })
   } else {