dsh-server-dashboard 0.1.0

package/dist/index.js

@@ -0,0 +1,718 @@
+import z from 'schemastery';
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { collectSnapshot, discoverLogs, testConnection, disposeState } from './host/collector.js';
+import { parseSshConfig } from './host/sshconfig.js';
+import { TEMP_HOT } from './client/thresholds.js';
+export const name = 'dsh-server-dashboard';
+/** Host services this plugin waits for (registry, credentials vault, http carrier). */
+export const inject = ['settings', 'credentials', 'webServer'];
+const HostSchema = z.object({
+    id: z.string().required(),
+    name: z.string().required(),
+    host: z.string().required(),
+    port: z.number().step(1).min(1).max(65535).default(22),
+    username: z.string().required(),
+    authKind: z.union(['password', 'key', 'none']).default('none'),
+    credentialRef: z.string().default(''),
+    identityFile: z.string().default(''),
+    logPath: z.string().default(''),
+    pinned: z.boolean().default(false),
+});
+const DashboardConfigSchema = z.object({
+    hosts: z.array(HostSchema).default([]),
+    refreshIntervalS: z.number().step(1).min(10).max(300).default(30),
+    staleMinutes: z.number().step(1).min(1).max(1440).default(10),
+});
+// 0.1.5 起 dsh-settings 移除了 settingsNamespace 包装:命名空间直接以字面量传入
+const NS = 'server-dashboard';
+const CRED_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+async function readIdentityFile(path) {
+    const { readFile } = await import('node:fs/promises');
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`无法读取密钥文件 ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Server-derived credential name for a host row — one host maps to exactly one
+ *  credential. Client-supplied credentialRef values are display-only and are
+ *  never used to address the vault (prevents overwriting arbitrary existing
+ *  credentials via PUT /dash/config). */
+function derivedCredName(hostId) {
+    return `SD_${hostId.replace(/[^A-Za-z0-9_]/g, '_')}`;
+}
+async function resolveAuth(ctx, cfg, cache) {
+    const ref = derivedCredName(cfg.id);
+    const sig = `${cfg.authKind}|${cfg.username}@${cfg.host}:${cfg.port}`;
+    let identityMtimeMs = -1;
+    if (cfg.authKind === 'key' && cfg.identityFile) {
+        try {
+            const { stat } = await import('node:fs/promises');
+            identityMtimeMs = Math.round((await stat(cfg.identityFile)).mtimeMs);
+        }
+        catch {
+            identityMtimeMs = -1;
+        }
+    }
+    const hit = cache?.get(cfg.id);
+    if (hit && hit.credentialRef === ref && hit.sig === sig && hit.identityMtimeMs === identityMtimeMs)
+        return hit.auth;
+    const auth = { host: cfg.host, port: cfg.port, username: cfg.username };
+    // 1) credential vault (explicitly stored private key / password) — always
+    //    addressed by the SERVER-DERIVED name, never by a client-supplied ref
+    if (cfg.authKind !== 'none') {
+        let cred = await ctx.credentials.resolve(credentialRef(ref)).catch(() => undefined);
+        // legacy migration: pre-derivation configs stored credentials under the
+        // client-supplied ref (SD_L40_KEY style). If the derived name is empty but
+        // the legacy ref holds a value, copy it across once — self-heals existing
+        // installs without weakening the derived-name model.
+        if (!cred?.value && cfg.credentialRef && CRED_NAME.test(cfg.credentialRef) && cfg.credentialRef !== ref) {
+            const legacy = await ctx.credentials.resolve(credentialRef(cfg.credentialRef)).catch(() => undefined);
+            if (legacy?.value) {
+                await ctx.credentials.set(credentialRef(ref), legacy.value).catch(() => undefined);
+                cred = legacy;
+            }
+        }
+        const value = cred?.value;
+        if (value) {
+            if (cfg.authKind === 'password')
+                auth.password = String(value);
+            else
+                auth.privateKey = String(value);
+        }
+    }
+    // 2) identity file referenced by an import from ~/.ssh/config
+    if (cfg.authKind === 'key' && !auth.privateKey && cfg.identityFile) {
+        auth.privateKey = await readIdentityFile(cfg.identityFile);
+    }
+    // 3) authKind 'none': mirror OpenSSH default identities
+    if (cfg.authKind === 'none' && !auth.privateKey && !auth.password) {
+        auth.privateKey = await readDefaultIdentity();
+    }
+    cache?.set(cfg.id, { credentialRef: ref, sig, identityMtimeMs, auth });
+    return auth;
+}
+/** OpenSSH default-identity order for authKind 'none' (unencrypted keys only). */
+async function readDefaultIdentity() {
+    const home = process.env.USERPROFILE ?? process.env.HOME ?? '';
+    const { readFile } = await import('node:fs/promises');
+    for (const f of ['id_ed25519', 'id_ecdsa', 'id_rsa']) {
+        try {
+            return await readFile(`${home}/.ssh/${f}`, 'utf8');
+        }
+        catch {
+            // try the next default identity
+        }
+    }
+    return undefined;
+}
+/** Auth resolution for one-off route bodies (test / discover-logs): same chain
+ *  as polling — inline secret → credential vault → identityFile → default key. */
+async function resolveAuthFromBody(ctx, body) {
+    const auth = { host: body.host, port: body.port ?? 22, username: body.username ?? 'root' };
+    const kind = body.authKind ?? 'none';
+    if (kind === 'password') {
+        if (body.password)
+            auth.password = body.password;
+        else if (body.credentialRef && CRED_NAME.test(body.credentialRef)) {
+            const hit = await ctx.credentials.resolve(credentialRef(body.credentialRef));
+            if (hit?.value)
+                auth.password = String(hit.value);
+        }
+    }
+    else if (kind === 'key') {
+        if (body.privateKey)
+            auth.privateKey = body.privateKey;
+        else if (body.credentialRef && CRED_NAME.test(body.credentialRef)) {
+            const hit = await ctx.credentials.resolve(credentialRef(body.credentialRef));
+            if (hit?.value)
+                auth.privateKey = String(hit.value);
+        }
+        else if (body.identityFile)
+            auth.privateKey = await readIdentityFile(body.identityFile);
+    }
+    else {
+        auth.privateKey = await readDefaultIdentity();
+    }
+    return auth;
+}
+/**
+ * Refresh the observation cursors from one round of snapshots. Targets are
+ * keyed by log path; an mtime/size change (or a first observation, which gets
+ * a full-threshold grace period) bumps changeAt to `now`. Failed snapshots
+ * keep their previous cursors — a transient collect failure must not fake
+ * either freshness or staleness. Pure (unit-testable).
+ */
+export function refreshLogActivity(snapshots, prev, now) {
+    const next = {};
+    for (const [hostId, snap] of Object.entries(snapshots)) {
+        if (!snap || !snap.ok) {
+            if (prev[hostId])
+                next[hostId] = prev[hostId];
+            continue;
+        }
+        const targets = [];
+        if (snap.log && snap.log.mtimeMs > 0)
+            targets.push(snap.log);
+        for (const g of snap.gpus ?? [])
+            if (g.log && g.log.mtimeMs > 0)
+                targets.push(g.log);
+        const prevRecord = prev[hostId] ?? {};
+        const record = {};
+        for (const t of targets) {
+            const p = prevRecord[t.path];
+            record[t.path] = p && p.mtimeMs === t.mtimeMs && p.size === t.size
+                ? { mtimeMs: t.mtimeMs, size: t.size, changeAt: p.changeAt } // unchanged — keep the last change moment
+                : { mtimeMs: t.mtimeMs, size: t.size, changeAt: now }; // changed or first sight — grace from now
+        }
+        next[hostId] = record;
+    }
+    return next;
+}
+/** Is a target fresh under the incremental rule? (pure) */
+function activityFresh(record, path, now, staleMs) {
+    const a = record?.[path];
+    return !!a && now - a.changeAt < staleMs;
+}
+/**
+ * Host-level logPath lifecycle:
+ *  - a configured path whose log shows no mtime/size CHANGE for ≥ staleMinutes
+ *    (observation-based, immune to remote clock skew) is cleared — the
+ *    experiment ended, stop flagging it;
+ *  - an empty path adopts the freshest per-GPU log (still being written; ties
+ *    broken by the largest remote mtime, comparable within one host) so the
+ *    card-level log follows whatever experiment starts next.
+ * Pure logic (unit-testable); the caller persists the returned patches.
+ */
+export function planLogPathUpdates(config, snapshots, activity, staleMinutes, now) {
+    const staleMs = staleMinutes * 60_000;
+    const out = [];
+    for (const hostCfg of config.hosts) {
+        const snap = snapshots[hostCfg.id];
+        if (!snap || !snap.ok)
+            continue;
+        const record = activity[hostCfg.id];
+        if (hostCfg.logPath && snap.log && snap.log.mtimeMs > 0 && snap.log.path === hostCfg.logPath) {
+            // stalled = no observed change within the threshold (first observation
+            // starts its grace period, so a genuinely old log is not cleared at once)
+            if (!activityFresh(record, hostCfg.logPath, now, staleMs))
+                out.push({ id: hostCfg.id, logPath: '' });
+        }
+        else if (!hostCfg.logPath) {
+            // adopt: freshest changed-recently per-GPU log; mtimeMs tiebreak compares
+            // clocks of the SAME remote host, so skew cannot reorder the candidates
+            let best;
+            for (const g of snap.gpus ?? []) {
+                const l = g.log;
+                if (!l || l.mtimeMs <= 0 || !activityFresh(record, l.path, now, staleMs))
+                    continue;
+                if (!best || l.mtimeMs > best.mtimeMs)
+                    best = l;
+            }
+            if (best)
+                out.push({ id: hostCfg.id, logPath: best.path });
+        }
+    }
+    return out;
+}
+export function apply(ctx) {
+    const scope = ctx.settings.register(NS, DashboardConfigSchema, {});
+    const hostState = new Map();
+    // last good snapshot cache, so a transient collect failure still renders
+    const cache = new Map();
+    // time-based exponential backoff per host: consecutive failures push the next
+    // probe 1min → 2min → 5min → 10min → 30min out; the cached error snapshot is
+    // served in between so a dead host never blocks healthy polls on SSH timeouts.
+    // A manual refresh (?force=1) clears the cooldown so a revived host is retried
+    // immediately instead of waiting out the full backoff.
+    const backoff = new Map();
+    const BACKOFF_MINUTES = [1, 2, 5, 10, 30];
+    // single-flight: concurrent snapshot requests share one polling round
+    let inflight = null;
+    let lastRun = 0;
+    // resolveAuth result cache per host (invalidated by PUT /dash/config; see
+    // AuthCacheEntry for the identity-file mtime part of the key)
+    const authCache = new Map();
+    // staleness observation cursors: hostId → log path → {mtime,size,changeAt};
+    // the incremental rule lives in refreshLogActivity/planLogPathUpdates
+    const logActivity = new Map();
+    // one-shot stall notices with a 2-minute grace: a client that connects shortly
+    // AFTER the clearing poll still gets the experiment-finished toast
+    const pendingNotices = new Map();
+    const cacheSnapshot = () => Object.fromEntries([...cache.entries()]);
+    /** drop ALL runtime state of hosts that are no longer in the config (covers
+     *  both PUT /dash/config and direct settings edits); disposing the CollectState
+     *  also closes its pooled SSH connection, so a removed host cannot pin one */
+    const sweepRemovedHosts = (live) => {
+        for (const id of [...hostState.keys()]) {
+            if (!live.has(id)) {
+                const st = hostState.get(id);
+                if (st)
+                    disposeState(st);
+                hostState.delete(id);
+            }
+        }
+        for (const id of [...cache.keys()])
+            if (!live.has(id))
+                cache.delete(id);
+        for (const id of [...backoff.keys()])
+            if (!live.has(id))
+                backoff.delete(id);
+        for (const id of [...logActivity.keys()])
+            if (!live.has(id))
+                logActivity.delete(id);
+        for (const id of [...pendingNotices.keys()])
+            if (!live.has(id))
+                pendingNotices.delete(id);
+        for (const id of [...lastLevels.keys()])
+            if (!live.has(id))
+                lastLevels.delete(id);
+    };
+    async function runPoll(config) {
+        await Promise.all(config.hosts.map(async (hostCfg) => {
+            const back = backoff.get(hostCfg.id);
+            if (back && Date.now() < back.nextTryAt) {
+                // cooling down — serve the cached error with a fresh timestamp
+                const cached = cache.get(hostCfg.id);
+                if (cached)
+                    cache.set(hostCfg.id, { ...cached, at: Date.now(), ok: false });
+                return;
+            }
+            let state = hostState.get(hostCfg.id);
+            if (!state) {
+                state = { series: new Map() };
+                hostState.set(hostCfg.id, state);
+            }
+            try {
+                const runtime = {
+                    id: hostCfg.id,
+                    auth: await resolveAuth(ctx, hostCfg, authCache),
+                    logPath: hostCfg.logPath || undefined,
+                };
+                const snap = await collectSnapshot(runtime, state);
+                if (snap.ok) {
+                    backoff.delete(hostCfg.id);
+                }
+                else {
+                    const failures = (backoff.get(hostCfg.id)?.failures ?? 0) + 1;
+                    backoff.set(hostCfg.id, {
+                        failures,
+                        nextTryAt: Date.now() + BACKOFF_MINUTES[Math.min(failures, BACKOFF_MINUTES.length) - 1] * 60_000,
+                    });
+                }
+                cache.set(hostCfg.id, snap);
+            }
+            catch (err) {
+                const failures = (backoff.get(hostCfg.id)?.failures ?? 0) + 1;
+                backoff.set(hostCfg.id, {
+                    failures,
+                    nextTryAt: Date.now() + BACKOFF_MINUTES[Math.min(failures, BACKOFF_MINUTES.length) - 1] * 60_000,
+                });
+                cache.set(hostCfg.id, {
+                    hostId: hostCfg.id,
+                    at: Date.now(),
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }));
+        // refresh the incremental staleness cursors from this round's snapshots
+        const snapsForPlan = Object.fromEntries([...cache.entries()]);
+        const nextActivity = refreshLogActivity(snapsForPlan, Object.fromEntries([...logActivity.entries()]), Date.now());
+        for (const [id, rec] of Object.entries(nextActivity))
+            logActivity.set(id, rec);
+        for (const id of [...logActivity.keys()])
+            if (!(id in nextActivity))
+                logActivity.delete(id);
+        // host-level logPath lifecycle: stalled path → auto-clear, empty path → adopt a fresh GPU log
+        try {
+            const patches = planLogPathUpdates(config, snapsForPlan, Object.fromEntries([...logActivity.entries()]), config.staleMinutes, Date.now());
+            if (patches.length > 0) {
+                const byId = new Map(patches.map((p) => [p.id, p.logPath]));
+                // re-read the config right before writing: a concurrent PUT during
+                // this poll must not be overwritten by our stale host list (lost update)
+                const fresh = scope.get();
+                const next = fresh.hosts.map((h) => (byId.has(h.id) ? { ...h, logPath: byId.get(h.id) } : h));
+                await scope.update({ hosts: next });
+                for (const p of patches) {
+                    const st = hostState.get(p.id);
+                    if (st) {
+                        st.series.clear();
+                        st.lastLine = undefined;
+                        st.lastHeader = undefined;
+                        st.path = undefined;
+                        st.lastSize = undefined;
+                        st.lastMtime = undefined;
+                    }
+                    if (!p.logPath) {
+                        // the stalled log is being dropped from the snapshot — record a
+                        // one-shot notice, otherwise the client can never see the
+                        // "unchanged for N minutes" evidence its toast is built on
+                        const clearedPath = config.hosts.find((h) => h.id === p.id)?.logPath ?? '';
+                        pendingNotices.set(p.id, { path: clearedPath, minutes: config.staleMinutes, at: Date.now() });
+                        emitStall(p.id, config.hosts.find((h) => h.id === p.id)?.name ?? p.id, config.staleMinutes);
+                        const cached = cache.get(p.id);
+                        if (cached)
+                            cache.set(p.id, { ...cached, log: undefined, series: undefined });
+                    }
+                    console.log(`[dsh-server-dashboard] ${p.id} logPath ${p.logPath ? `自动接管 ${p.logPath}` : '已停滞，自动清除'}`);
+                }
+            }
+        }
+        catch (err) {
+            console.warn('[dsh-server-dashboard] logPath lifecycle update failed:', err instanceof Error ? err.message : String(err));
+        }
+        // recycle state (and pooled SSH connections) of hosts removed from the
+        // config outside our PUT handler (direct settings edits)
+        sweepRemovedHosts(new Set(config.hosts.map((h) => h.id)));
+        return cacheSnapshot();
+    }
+    async function pollAll(config, force = false, forceHost) {
+        if (inflight) {
+            // a poll round is already running — non-forced callers just wait for it
+            if (!force)
+                return inflight;
+            await inflight.catch(() => { });
+        }
+        // ?host=<id> alone must NOT bypass the backoff — only a real manual retry
+        // (force=1, optionally narrowed to one host) clears it
+        if (forceHost && force)
+            backoff.delete(forceHost);
+        else if (force)
+            backoff.clear();
+        else if (Date.now() - lastRun < 5_000)
+            return cacheSnapshot();
+        inflight = runPoll(config);
+        try {
+            return await inflight;
+        }
+        finally {
+            inflight = null;
+            lastRun = Date.now();
+        }
+    }
+    /* ---------- shared route helpers ---------- */
+    /** Loopback guard for every /dash/* route: only 127.0.0.1 / ::1 / IPv4-mapped
+     *  loopback may talk to the dashboard API. Even when the web server is bound
+     *  to 0.0.0.0 for LAN sharing, remote clients cannot reach the dashboard
+     *  routes (config write / SSH probes / snapshots) directly. */
+    const isLoopback = (req) => {
+        const addr = req.socket.remoteAddress ?? '';
+        return addr === '127.0.0.1' || addr === '::1' || addr === '::ffff:127.0.0.1';
+    };
+    /** 403 unless loopback; returns false when the response is already sent */
+    const guard = (req, res) => {
+        if (!isLoopback(req)) {
+            sendJson(res, 403, { error: '仅允许本机(loopback)访问' });
+            return false;
+        }
+        return true;
+    };
+    const readBody = (req) => new Promise((resolve, reject) => {
+        // CSRF hardening: cross-origin simple requests cannot send JSON content-type
+        // without a CORS preflight, which this server never grants.
+        const ct = String(req.headers['content-type'] ?? '');
+        if (!ct.includes('application/json')) {
+            reject(new Error('请求必须是 application/json'));
+            return;
+        }
+        let data = '';
+        let bytes = 0;
+        let over = false;
+        req.on('data', (chunk) => {
+            if (over)
+                return;
+            data += chunk;
+            bytes += chunk.length; // count BYTES, not UTF-16 code units
+            if (bytes > 1_000_000) {
+                // destroy the stream the moment the cap is exceeded — otherwise a
+                // hostile client can keep feeding the body while we keep buffering it
+                over = true;
+                req.destroy();
+                reject(new Error('请求体过大'));
+            }
+        });
+        req.on('end', () => { if (!over)
+            resolve(data); });
+        req.on('error', reject);
+    });
+    const sendJson = (res, code, payload) => {
+        res.statusCode = code;
+        res.setHeader('content-type', 'application/json; charset=utf-8');
+        res.end(JSON.stringify(payload));
+    };
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: '/dash/snapshots',
+        handler: async (req, res) => {
+            if (!guard(req, res))
+                return;
+            if (req.method !== 'GET')
+                return sendJson(res, 405, { error: 'method not allowed' });
+            const config = scope.get();
+            const hostsMeta = config.hosts.map((h) => ({ id: h.id, name: h.name, pinned: h.pinned }));
+            // ?force=1[&host=<id>] — manual refresh bypasses the failure backoff,
+            // optionally only for one host (the offline card's retry button)
+            const query = new URL(req.url ?? '', 'http://localhost').searchParams;
+            const force = query.get('force') === '1';
+            const forceHost = query.get('host') ?? undefined;
+            try {
+                const snapshots = await pollAll(config, force, forceHost);
+                // attach unexpired stall notices so late-connecting clients still toast
+                for (const [id, notice] of [...pendingNotices.entries()]) {
+                    if (Date.now() - notice.at > 120_000 || !config.hosts.some((h) => h.id === id)) {
+                        pendingNotices.delete(id);
+                        continue;
+                    }
+                    if (snapshots[id] && !snapshots[id].stallNotice)
+                        snapshots[id] = { ...snapshots[id], stallNotice: notice };
+                }
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+                res.end(JSON.stringify({
+                    hosts: hostsMeta,
+                    snapshots,
+                    refreshIntervalS: config.refreshIntervalS,
+                    staleMinutes: config.staleMinutes,
+                }));
+            }
+            catch (err) {
+                res.statusCode = 500;
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+                res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+            }
+        },
+    }));
+    // config read (secrets never leave the host; only refs are returned)
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: '/dash/config',
+        handler: async (req, res) => {
+            if (!guard(req, res))
+                return;
+            try {
+                if (req.method === 'GET') {
+                    const config = scope.get();
+                    sendJson(res, 200, { config });
+                    return;
+                }
+                if (req.method === 'PUT') {
+                    const body = JSON.parse(await readBody(req));
+                    const hosts = body.hosts;
+                    if (!Array.isArray(hosts))
+                        return sendJson(res, 400, { error: 'hosts 必须是数组' });
+                    // duplicate ids would share one CollectState and reconnect every poll
+                    const seenIds = new Set();
+                    for (const h of hosts) {
+                        if (seenIds.has(h.id))
+                            return sendJson(res, 400, { error: `主机 id 重复：${h.id}` });
+                        seenIds.add(h.id);
+                    }
+                    // omitted fields keep their persisted values — a hosts-only PUT (host
+                    // edit, import, log apply) must not reset the interval thresholds
+                    const current = scope.get();
+                    const refreshIntervalS = body.refreshIntervalS ?? current.refreshIntervalS;
+                    const staleMinutes = body.staleMinutes ?? current.staleMinutes;
+                    // validate against the schema before persisting
+                    DashboardConfigSchema({ hosts, refreshIntervalS, staleMinutes });
+                    // secrets are ALWAYS stored under the server-derived SD_<hostId> name;
+                    // a client-supplied credentialRef is never used as a vault address
+                    // (prevents overwriting arbitrary existing credentials). The config
+                    // field is normalized for display only.
+                    const secretIds = new Set(Object.entries(body.secrets ?? {})
+                        .filter(([, s]) => s?.privateKey || s?.password)
+                        .map(([id]) => id));
+                    for (const row of hosts) {
+                        if (secretIds.has(row.id))
+                            row.credentialRef = derivedCredName(row.id);
+                    }
+                    await scope.update({ hosts, refreshIntervalS, staleMinutes });
+                    // config changed: clear the failure backoff + poll throttle so the
+                    // next request re-probes immediately ("fixed the credentials but the
+                    // card stayed red for up to 30min" case), drop the auth cache, and
+                    // re-arm the events watcher at the new interval
+                    backoff.clear();
+                    lastRun = 0;
+                    authCache.clear();
+                    scheduleWatcher(Math.max(WATCHER_MIN_MS, refreshIntervalS * 1000));
+                    // drop runtime state of hosts that no longer exist (cache/backoff/state leak)
+                    sweepRemovedHosts(new Set(hosts.map((h) => h.id)));
+                    // persist the supplied secrets; ids not in the host list are ignored
+                    // (no orphan credentials for removed hosts)
+                    for (const [id, secret] of Object.entries(body.secrets ?? {})) {
+                        if (!seenIds.has(id))
+                            continue;
+                        const name = derivedCredName(id);
+                        if (secret?.privateKey)
+                            await ctx.credentials.set(credentialRef(name), secret.privateKey);
+                        else if (secret?.password)
+                            await ctx.credentials.set(credentialRef(name), secret.password);
+                    }
+                    sendJson(res, 200, { ok: true, config: { hosts, refreshIntervalS, staleMinutes } });
+                    return;
+                }
+                sendJson(res, 405, { error: 'method not allowed' });
+            }
+            catch (err) {
+                sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
+            }
+        },
+    }));
+    // import hosts from ~/.ssh/config (host side runs as the local user)
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: '/dash/import-ssh',
+        handler: async (req, res) => {
+            if (!guard(req, res))
+                return;
+            try {
+                const home = process.env.USERPROFILE ?? process.env.HOME ?? '';
+                const { readFile } = await import('node:fs/promises');
+                const text = await readFile(`${home}/.ssh/config`, 'utf8');
+                sendJson(res, 200, { hosts: parseSshConfig(text) });
+            }
+            catch (err) {
+                sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+            }
+        },
+    }));
+    // connection test (light SSH probe; accepts one-off secrets for untested entries)
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: '/dash/test',
+        handler: async (req, res) => {
+            if (!guard(req, res))
+                return;
+            try {
+                const body = JSON.parse(await readBody(req));
+                if (!body.host)
+                    return sendJson(res, 400, { error: 'host 必填' });
+                const result = await testConnection(await resolveAuthFromBody(ctx, body));
+                sendJson(res, 200, result);
+            }
+            catch (err) {
+                sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
+            }
+        },
+    }));
+    // auto-discover training logs from running processes
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: '/dash/discover-logs',
+        handler: async (req, res) => {
+            if (!guard(req, res))
+                return;
+            try {
+                const body = JSON.parse(await readBody(req));
+                if (!body.host)
+                    return sendJson(res, 400, { error: 'host 必填' });
+                const candidates = await discoverLogs(await resolveAuthFromBody(ctx, body));
+                sendJson(res, 200, { candidates });
+            }
+            catch (err) {
+                sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
+            }
+        },
+    }));
+    console.log('[dsh-server-dashboard] host half ready: settings ns + /dash/snapshots + /dash/config + /dash/test');
+    /* ---------- instant alerts (/dash/events, long-poll) ----------
+     * The browser panel polls snapshots; this endpoint pushes second-level
+     * alerts the moment the host sampler sees a transition:
+     *   {type:'stall', hostId, hostName, minutes}   — experiment log stalled
+     *   {type:'host-status', hostId, hostName, level, previous}
+     *                                               — offline / hot flips
+     * Hanging GET + seq cursor: request /dash/events?since=N and it resolves
+     * the instant an event lands (25s idle timeout). Sampling reuses pollAll
+     * (single-flight + per-host backoff) and only runs while a client is
+     * actually waiting, so no SSH load is added when the panel is closed. */
+    const eventLog = [];
+    let eventSeq = 0;
+    const eventWaiters = new Set();
+    const emitAlert = (payload) => {
+        eventLog.push({ seq: ++eventSeq, payload });
+        if (eventLog.length > 80)
+            eventLog.splice(0, eventLog.length - 80);
+        for (const wake of [...eventWaiters])
+            wake();
+        eventWaiters.clear();
+    };
+    const lastLevels = new Map();
+    const levelOf = (snap) => {
+        if (!snap || !snap.ok)
+            return 'offline';
+        return (snap.gpus ?? []).some((g) => g.tempC >= TEMP_HOT) ? 'warn' : 'ok';
+    };
+    // host-level stall: emit the moment planLogPathUpdates records a notice
+    const emitStall = (hostId, hostName, minutes) => emitAlert({ type: 'stall', hostId, hostName, minutes });
+    // sampling interval follows the configured refreshIntervalS (10s floor), so
+    // the watcher never polls SSH more often than the panel itself; rebuilt when
+    // the config (or its interval) changes
+    const WATCHER_MIN_MS = 10_000;
+    let watcherTimer = null;
+    let watcherIntervalMs = 0;
+    const scheduleWatcher = (intervalMs) => {
+        if (watcherTimer)
+            clearInterval(watcherTimer);
+        watcherIntervalMs = intervalMs;
+        watcherTimer = setInterval(watcherTick, intervalMs);
+        watcherTimer.unref();
+    };
+    async function watcherTick() {
+        if (eventWaiters.size === 0)
+            return; // nobody long-polling — skip SSH sampling
+        const config = scope.get();
+        // the interval may have changed via direct settings edit — re-arm
+        const want = Math.max(WATCHER_MIN_MS, config.refreshIntervalS * 1000);
+        if (want !== watcherIntervalMs)
+            scheduleWatcher(want);
+        const snaps = await pollAll(config).catch(() => cacheSnapshot());
+        for (const h of config.hosts) {
+            const level = levelOf(snaps[h.id]);
+            const prev = lastLevels.get(h.id);
+            lastLevels.set(h.id, level);
+            if (!prev || prev === level)
+                continue;
+            emitAlert({ type: 'host-status', hostId: h.id, hostName: h.name, level, previous: prev });
+        }
+    }
+    scheduleWatcher(Math.max(WATCHER_MIN_MS, (scope.get().refreshIntervalS || 30) * 1000));
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: '/dash/events',
+        handler: async (req, res) => {
+            if (!guard(req, res))
+                return;
+            if (req.method !== 'GET')
+                return sendJson(res, 405, { error: 'method not allowed' });
+            const q = new URL(req.url ?? '/', 'http://localhost').searchParams;
+            const since = Number(q.get('since') ?? 0) || 0;
+            const deliver = () => {
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+                res.end(JSON.stringify({
+                    events: eventLog.filter((e) => e.seq > since).map((e) => e.payload),
+                    last: eventSeq,
+                }));
+            };
+            // fresh client (since=0) only receives the cursor baseline — replaying the
+            // buffered history would re-toast hours-old alerts on every page reload
+            if (since === 0) {
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+                res.end(JSON.stringify({ events: [], last: eventSeq }));
+                return;
+            }
+            if (eventLog.some((e) => e.seq > since))
+                return deliver();
+            const to = setTimeout(() => { eventWaiters.delete(wake); deliver(); }, 25_000);
+            const wake = () => { clearTimeout(to); eventWaiters.delete(wake); deliver(); };
+            eventWaiters.add(wake);
+            res.on('close', () => { clearTimeout(to); eventWaiters.delete(wake); });
+        },
+    }));
+    // close all pooled SSH connections when the plugin scope is disposed
+    ctx.effect(() => () => {
+        if (watcherTimer)
+            clearInterval(watcherTimer);
+        for (const st of hostState.values())
+            disposeState(st);
+    });
+}