dsh-flash-mem-mon 0.1.5 → 0.2.0

package/dist/index.js

@@ -1,33 +1,47 @@
+import { writeHeapSnapshot } from 'node:v8';
+import { createReadStream } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
 // Default export only (`export default Schema`); there is no named `Schema`.
 import Schema from '@deepseek-ai/schemastery';
+import { countArchivedSessions, DEFAULT_ALERT_CONFIG, formatBytes, isFullGc, rssSlopePerMin, sumBytes, } from './pure.js';
 export const name = 'dsh-flash-mem-mon';
-// No host-side service dependencies; all services are injected lazily.
-export const inject = [];
+// Lazy-injected services. All are resolved via ctx.inject() at apply-time, so
+// the plugin still boots even when a service (e.g. workspaceRegistry) is
+// unavailable; declaring them here documents the dependency.
+export const inject = ['workspaceRegistry'];
 // ── Memory alert thresholds (RSS MB) and GC thresholds (major GC/min) ──
-const DEFAULT_MEM_THRESHOLD_INFO = 256;
-const DEFAULT_MEM_THRESHOLD_WARNING = 512;
-const DEFAULT_MEM_THRESHOLD_ERROR = 1024;
-const DEFAULT_MEM_THRESHOLD_CRITICAL = 1536;
-const DEFAULT_MEM_POLL_BASE = 30000;
-const DEFAULT_MEM_POLL_MIN = 2000;
-const DEFAULT_GC_THRESHOLD_INFO = 2;
-const DEFAULT_GC_THRESHOLD_WARNING = 5;
-const DEFAULT_GC_THRESHOLD_ERROR = 10;
-// V8 GC entry `kind` is a bitmask of GC types:
-//   1 << 0 = Scavenge (minor / young-gen)
-//   1 << 1 = MarkSweepCompact (major / full)
-//   1 << 2 = IncrementalMarking
-//   1 << 3 = ProcessWeakCallbacks
-// In practice modern V8/Node reports a full MarkSweepCompact cycle through the
-// IncrementalMarking (4) and ProcessWeakCallbacks (8) phases — the standalone
-// "major" bit (2) is almost never emitted on its own.  Classifying Full GC by
-// `kind === 2` alone therefore misses (nearly) every real full collection.
-// The robust test: a Full GC is any NON-scavenge cycle, i.e. the Scavenge bit
-// (1) is NOT set.  This captures 2, 4, 6, 8, 10, 12, 14 while excluding minor
-// (1) scavenges.
-function isFullGc(kind) {
-    return (kind & 1) === 0 && kind > 0;
-}
+// All values come from the single canonical DEFAULT_ALERT_CONFIG in
+// ./pure.js. The browser client half mirrors these (see lib/client.js
+// _MEM_ALERT_DEFAULTS); test/defaults-drift.test.ts guarantees they never
+// drift from this source of truth.
+const DEFAULT_MEM_THRESHOLD_INFO = DEFAULT_ALERT_CONFIG.memThresholdInfo;
+const DEFAULT_MEM_THRESHOLD_WARNING = DEFAULT_ALERT_CONFIG.memThresholdWarning;
+const DEFAULT_MEM_THRESHOLD_ERROR = DEFAULT_ALERT_CONFIG.memThresholdError;
+const DEFAULT_MEM_THRESHOLD_CRITICAL = DEFAULT_ALERT_CONFIG.memThresholdCritical;
+const DEFAULT_MEM_POLL_BASE = DEFAULT_ALERT_CONFIG.memPollBase;
+const DEFAULT_MEM_POLL_MIN = DEFAULT_ALERT_CONFIG.memPollMin;
+const DEFAULT_GC_THRESHOLD_INFO = DEFAULT_ALERT_CONFIG.gcThresholdInfo;
+const DEFAULT_GC_THRESHOLD_WARNING = DEFAULT_ALERT_CONFIG.gcThresholdWarning;
+const DEFAULT_GC_THRESHOLD_ERROR = DEFAULT_ALERT_CONFIG.gcThresholdError;
+const DEFAULT_MEM_GROWTH_ALERT_PER_MIN = DEFAULT_ALERT_CONFIG.memGrowthAlertPerMin;
+// Session-footprint (disk) polling interval. Deliberately NOT a member of
+// DEFAULT_ALERT_CONFIG: test/defaults-drift.test.ts asserts that object contains
+// EXACTLY the 10 memory/GC keys, and a footprint key here would break that
+// precise set. Disk scans are comparatively expensive (recursive readdir +
+// stat over every session directory), so they run far less often than memory.
+// The host caches the last scan and the client reads the cached snapshot, so
+// the route itself never triggers an on-demand scan.
+const FOOTPRINT_POLL_INTERVAL_MS = 300000; // 5 min
+/**
+ * Sentinel passed to `query()` / `gcEvents()` as the `since` lower bound to
+ * mean "no lower bound — return ALL stored records".  These methods treat any
+ * `since <= 0` (0 or undefined) as "all", and a positive value as a unix-ms
+ * timestamp to filter from.  Keeping one explicit convention prevents callers
+ * from mixing up `0` vs `undefined` (both mean "all").
+ */
+const SINCE_ALL = 0;
 export const Config = Schema.object({
     memThresholdInfo: Schema.number().default(DEFAULT_MEM_THRESHOLD_INFO).volatile(),
     memThresholdWarning: Schema.number().default(DEFAULT_MEM_THRESHOLD_WARNING).volatile(),
@@ -38,10 +52,20 @@ export const Config = Schema.object({
     gcThresholdInfo: Schema.number().default(DEFAULT_GC_THRESHOLD_INFO).volatile(),
     gcThresholdWarning: Schema.number().default(DEFAULT_GC_THRESHOLD_WARNING).volatile(),
     gcThresholdError: Schema.number().default(DEFAULT_GC_THRESHOLD_ERROR).volatile(),
+    memGrowthAlertPerMin: Schema.number().default(DEFAULT_MEM_GROWTH_ALERT_PER_MIN).volatile(),
 });
 class MemoryTrendCollector {
     _samples = [];
+    // The poll loop is self-scheduling via setInterval-like recursion with an
+    // ADAPTIVE delay (higher heap usage → shorter interval), so each cycle holds
+    // a fresh setTimeout handle rather than one fixed-interval setInterval.
     _timer = null;
+    /** Monotonic loop generation. Bumped every start()/stop(); a poll() tick
+     *  whose captured generation no longer matches the current one is a stale
+     *  callback from a superseded loop and must NOT re-schedule itself. This
+     *  closes the start/stop restart race where a queued pre-restart tick could
+     *  otherwise clobber the new loop's timer handle and leak a second loop. */
+    _generation = 0;
     _cap;
     // GC monitoring via PerformanceObserver
     _gcObserver = null; // PerformanceObserver | null
@@ -55,10 +79,16 @@ class MemoryTrendCollector {
     }
     start(baseInterval = 30_000, minInterval = 5_000) {
         this.stop();
+        const gen = ++this._generation;
         // Fire-and-forget: GC observer can start asynchronously; the poll loop
         // below begins immediately regardless, since it does not depend on GC.
         this._startGcObserver().catch(() => { });
         const poll = () => {
+            // Bail if this tick belongs to a superseded loop (a restart has bumped
+            // the generation since we were scheduled). The stopped loop then winds
+            // down on its own instead of fighting the fresh loop for this._timer.
+            if (gen !== this._generation)
+                return;
             const mu = process.memoryUsage();
             this._push({
                 ts: Date.now(),
@@ -81,40 +111,42 @@ class MemoryTrendCollector {
         poll();
     }
     stop() {
+        // Bump the generation BEFORE clearing so any in-flight/stale poll tick that
+        // is already queued (past clearTimeout's reach) recognises itself as stale
+        // and refuses to re-schedule, never resurrecting a stopped loop.
+        this._generation++;
         if (this._timer !== null) {
             clearTimeout(this._timer);
             this._timer = null;
         }
         this._stopGcObserver();
     }
-    setCap(cap) {
-        this._cap = Math.max(10, Math.floor(cap) || 10);
-        while (this._samples.length > this._cap)
-            this._samples.shift();
-    }
-    query(since) {
-        if (!since)
+    /** Memory samples at or after `since` (unix ms). A falsy/absent `since`
+     *  (`SINCE_ALL` / undefined) means "return all stored samples". */
+    query(since = SINCE_ALL) {
+        if (since <= 0)
             return this._samples.slice();
         return this._samples.filter(s => s.ts >= since);
     }
     /** Return Full (major) GC events for chart rendering.
-     *  Pass since=0 to return ALL stored events (for full-mode fetches).
      *  Each returned event is one real full-GC cycle (phases already coalesced
      *  in `_startGcObserver`) and is normalized to kind=2 so the client can
-     *  always treat `gcEvents` as "Full GC events". */
-    gcEvents(since) {
+     *  always treat `gcEvents` as "Full GC events".  A falsy/absent `since`
+     *  (`SINCE_ALL` / undefined) means "return all stored events". */
+    gcEvents(since = SINCE_ALL) {
         if (this._gcMajorEvents.length === 0)
             return [];
-        const cutoff = since ?? (Date.now() - 5 * 60 * 1000);
-        return this._gcMajorEvents
-            .filter(e => e.ts >= cutoff)
+        const events = since > 0
+            ? this._gcMajorEvents.filter(e => e.ts >= since)
+            : this._gcMajorEvents;
+        return events
             .map(e => ({ ts: e.ts, kind: 2, duration: e.duration }))
             .sort((a, b) => a.ts - b.ts);
     }
     summary(since) {
         const data = this.query(since);
         if (data.length === 0) {
-            return { current: null, peak: null, trend: 'stable', sampleCount: 0, heapRatio: 0, spanSeconds: 0, rssSlopePerMin: 0, gc: null };
+            return { current: null, peak: null, trend: 'stable', sampleCount: 0, heapRatio: 0, spanMs: 0, rssSlopePerMin: 0, gc: null };
         }
         const current = data[data.length - 1];
         let peak = { heapUsed: 0, rss: 0, ts: 0 };
@@ -143,28 +175,15 @@ class MemoryTrendCollector {
                 trend = 'down';
         }
         const heapRatio = current.heapTotal > 0 ? current.heapUsed / current.heapTotal : 0;
-        const spanSeconds = data.length >= 2 ? Math.round((data[data.length - 1].ts - data[0].ts) / 1000) : 0;
-        // RSS linear regression over the last 20 samples → slope per minute (MB/min).
-        let rssSlopePerMin = 0;
-        if (tail.length >= 3) {
-            const n = tail.length;
-            let sumX = 0, sumY = 0, sumXY = 0, sumXX = 0;
-            for (let i = 0; i < n; i++) {
-                sumX += i;
-                sumY += tail[i].rss;
-                sumXY += i * tail[i].rss;
-                sumXX += i * i;
-            }
-            const slope = (n * sumXY - sumX * sumY) / (n * sumXX - sumX * sumX);
-            // slope = bytes per sample-index step.  Convert to MB/min.
-            // Average interval between tail samples ≈ spanSeconds / (n-1).
-            const avgIntervalSec = tail.length >= 2 ? spanSeconds / (tail.length - 1) : 30;
-            const samplesPerMin = avgIntervalSec > 0 ? 60 / avgIntervalSec : 2;
-            rssSlopePerMin = Math.round((slope * samplesPerMin / 1048576) * 100) / 100;
-        }
+        const spanMs = data.length >= 2 ? data[data.length - 1].ts - data[0].ts : 0;
+        // RSS linear-regression slope per minute (MB/min); positive = growing.
+        // Delegated to the pure helper (src/pure.ts) so the same logic is unit-
+        // tested. The average interval comes from the tail's own time span — see
+        // rssSlopePerMin for why using the whole buffer span would under-report.
+        const rssSlope = rssSlopePerMin(data);
         // GC stats over the last ~5 minutes.
         const gc = this._gcSummary(5 * 60 * 1000);
-        return { current, peak, trend, sampleCount: data.length, heapRatio, spanSeconds, rssSlopePerMin, gc };
+        return { current, peak, trend, sampleCount: data.length, heapRatio, spanMs, rssSlopePerMin: rssSlope, gc };
     }
     /** Aggregate GC events in the last `windowMs` milliseconds. */
     _gcSummary(windowMs) {
@@ -176,7 +195,14 @@ class MemoryTrendCollector {
         const majorRecent = this._gcMajorEvents.filter(e => e.ts >= cutoff);
         const majorCount = majorRecent.length;
         // Minor count + total pause come from the general ring buffer (which holds
-        // every event).  A minor cycle is a Scavenge (kind bit 1 set).
+        // EVERY PerformanceObserver entry). A minor cycle is a Scavenge (kind bit 1
+        // set). NOTE: gcPauseMs is the SUM of every phase-entry duration in the
+        // window — one real Full GC is reported as multiple phases (kind 4 + 8), and
+        // each contributes its own duration, so gcPauseMs is the TOTAL stop-the-world
+        // pause across all cycles (minor + full), NOT per-cycle. majorCount, by
+        // contrast, comes from the separate coalesced buffer and counts each real
+        // Full GC cycle ONCE. The two buffers intentionally have different semantics:
+        // majorCount = distinct full collections; gcPauseMs = aggregate pauses.
         let minorCount = 0, gcPauseMs = 0;
         for (const e of this._gcEvents) {
             if (e.ts < cutoff)
@@ -216,9 +242,12 @@ class MemoryTrendCollector {
                     // because they are rare and the general ring buffer may evict them.
                     if (isFullGc(kind)) {
                         const last = this._gcMajorEvents[this._gcMajorEvents.length - 1];
-                        if (last && event.ts - last.ts < 500) {
+                        if (last && event.ts - last.ts < 2000) {
                             // Same full-GC cycle (phase entries arriving back-to-back):
                             // merge into the existing event, keeping the worst-case pause.
+                            // Window is generous (2s) because one cycle's phases can arrive
+                            // over a second apart under real load; merging here prevents one
+                            // Full GC from being reported as several adjacent events.
                             last.duration = Math.max(last.duration, event.duration);
                             last.ts = event.ts;
                         }
@@ -257,8 +286,219 @@ class MemoryTrendCollector {
             this._samples.shift();
     }
 }
-/** Module-level singleton — one collector per process. */
+// ── Process-scoped singleton with an exclusive active owner ─────────────
+//
+// A single MemoryTrendCollector is shared across the whole process so all
+// consumers see one coherent ring buffer (each sample carries its own ts).
+// However, Cordis may apply() this plugin more than once (multiple profiles,
+// hot reload) and dispose() them in any order. To avoid two collectors racing
+// on the same module state — and to stop one stray dispose() from killing a
+// collector another apply() is still using — ownership is explicit:
+//
+//   _memoryTrend  : the live collector (or null)
+//   _ownerCtx     : the Context that currently owns it (or null)
+//
+// startTrend()/stopTrend() are idempotent and fail softly when the caller is
+// not the current owner, so overlapping apply/dispose cycles stay safe.
 let _memoryTrend = null;
+let _ownerCtx = null;
+// ── Heap-snapshot dump state ─────────────────────────────────────────────
+// The "dump heap now" disposal button on an alert POSTs dump-heap, which
+// writes a .heapsnapshot (possibly tens–hundreds of MB) and records it here
+// so the browser client can pull it down via the heap-dump route. Only the
+// latest snapshot is kept for download; dumps are user-paced, not automatic,
+// because writeHeapSnapshot() blocks the host main thread for seconds.
+let _lastSnapshot = null;
+/** Adopt the process-wide collector for `ctx`; no-op if it is already owned. */
+function startTrend(ctx, config) {
+    if (_ownerCtx && _ownerCtx !== ctx)
+        return; // someone else owns it
+    if (!_memoryTrend)
+        _memoryTrend = new MemoryTrendCollector();
+    _ownerCtx = ctx;
+    _memoryTrend.start((config.memPollBase?.get?.() ?? config.memPollBase) || DEFAULT_MEM_POLL_BASE, (config.memPollMin?.get?.() ?? config.memPollMin) || DEFAULT_MEM_POLL_MIN);
+}
+function restartTrend(config) {
+    if (!_memoryTrend || !_ownerCtx)
+        return;
+    _memoryTrend.stop();
+    _memoryTrend.start((config.memPollBase?.get?.() ?? config.memPollBase) || DEFAULT_MEM_POLL_BASE, (config.memPollMin?.get?.() ?? config.memPollMin) || DEFAULT_MEM_POLL_MIN);
+}
+/** Relinquish ownership of `ctx`. Only the active owner may stop the shared
+ *  collector; other ctx instances (already superseded) must not touch it. */
+function stopTrend(ctx) {
+    if (_ownerCtx !== ctx)
+        return; // not the owner → leave the running collector alone
+    _ownerCtx = null;
+    _memoryTrend?.stop();
+}
+class SessionFootprintCollector {
+    _snapshot = null;
+    _timer = null;
+    _running = false;
+    start() {
+        if (this._running)
+            return;
+        this._running = true;
+        this._scan().then(() => { this._schedule(); }).catch(() => { this._schedule(); });
+    }
+    stop() {
+        this._running = false;
+        if (this._timer) {
+            clearTimeout(this._timer);
+            this._timer = null;
+        }
+    }
+    /** Immediately trigger a re-scan (e.g. right after the workspace registry is
+     *  captured) so the very first archived count is not stuck at 0. */
+    rescan() {
+        if (!this._running)
+            return;
+        this._scan().catch(() => { });
+    }
+    snapshot() {
+        return this._snapshot;
+    }
+    _schedule() {
+        if (!this._running)
+            return;
+        this._timer = setTimeout(() => {
+            this._timer = null;
+            this._scan().then(() => { this._schedule(); }).catch(() => { this._schedule(); });
+        }, FOOTPRINT_POLL_INTERVAL_MS);
+        this._timer.unref?.();
+    }
+    async _scan() {
+        const sessionsRoot = resolveSessionsRoot();
+        const workspaces = await this._scanWorkspaces(sessionsRoot);
+        const snapshot = {
+            totalSessions: 0,
+            archivedSessions: 0,
+            bytes: 0,
+            workspaces,
+            scannedAt: Date.now(),
+        };
+        for (const w of workspaces) {
+            snapshot.totalSessions += w.totalSessions;
+            snapshot.archivedSessions += w.archivedSessions;
+            snapshot.bytes += w.bytes;
+        }
+        this._snapshot = snapshot;
+    }
+    async _scanWorkspaces(sessionsRoot) {
+        let workspaceDirs = [];
+        try {
+            workspaceDirs = await readdir(sessionsRoot, { withFileTypes: true }).then((ents) => ents.filter((e) => e.isDirectory()).map((e) => e.name));
+        }
+        catch (_e) {
+            return [];
+        }
+        const registry = getWorkspaceRegistry();
+        let archivedIds = [];
+        try {
+            if (registry && typeof registry.archivedSessionIds === 'function')
+                archivedIds = registry.archivedSessionIds();
+            else if (registry && Array.isArray(registry.archivedSessionIds))
+                archivedIds = registry.archivedSessionIds;
+        }
+        catch (_e) { /* keep empty */ }
+        const result = [];
+        for (const ws of workspaceDirs) {
+            const wsPath = join(sessionsRoot, ws);
+            let sessionNames = [];
+            try {
+                sessionNames = await readdir(wsPath, { withFileTypes: true }).then((ents) => ents.filter((e) => e.isDirectory() && /^session-/.test(e.name)).map((e) => e.name));
+            }
+            catch (_e) {
+                sessionNames = [];
+            }
+            const namesSet = new Set(sessionNames);
+            let bytes = 0;
+            for (const s of sessionNames) {
+                bytes += await dirSize(join(wsPath, s));
+            }
+            result.push({
+                workspace: ws,
+                totalSessions: sessionNames.length,
+                archivedSessions: countArchivedSessions(archivedIds, namesSet),
+                bytes,
+            });
+        }
+        return result;
+    }
+}
+/** Recursively sum the on-disk size of a session directory. */
+async function dirSize(dir) {
+    let total = 0;
+    let entries = [];
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (_e) {
+        return 0;
+    }
+    for (const e of entries) {
+        const p = join(dir, e.name);
+        try {
+            if (e.isDirectory()) {
+                total += await dirSize(p);
+            }
+            else if (e.isSymbolicLink()) {
+                continue;
+            }
+            else {
+                const s = await stat(p);
+                total += s.size;
+            }
+        }
+        catch (_e) { /* skip */ }
+    }
+    return total;
+}
+/**
+ * Resolve the DSH sessions root the same way the harness seeds `$DSH_HOME`:
+ * configured override > `$DSH_HOME` env > `~/.dsh` (opened home). `$DSH_HOME`
+ * may itself contain a `~` or trailing slashes, so expand the home and join the
+ * well-known `sessions` sub-directory explicitly. Returns `''` if a home could
+ * not be resolved at all (the scan then simply reports zero workspaces).
+ */
+function resolveSessionsRoot() {
+    const env = process.env.DSH_HOME;
+    const home = env && env.trim()
+        ? env.replace(/^~(?=\/|\\)/, homedir())
+        : join(homedir(), '.dsh');
+    return join(home, 'sessions');
+}
+let _footprint = null;
+let _footprintOwner = null;
+// Cached reference to the DSH workspace-registry service, resolved lazily via
+// ctx.inject. When it is unavailable (or the plugin was applied without it),
+// archived-session counting degrades to whatever the registry can provide —
+// if the registry is truly absent the archived count is reported as 0 rather
+// than guessing from the disk (disk directories carry no archive flag).
+let _workspaceRegistry = null;
+function setWorkspaceRegistry(wsCtx) {
+    const reg = wsCtx?.workspaceRegistry;
+    if (reg != null)
+        _workspaceRegistry = reg;
+}
+function getWorkspaceRegistry() {
+    return _workspaceRegistry ?? null;
+}
+function startFootprint(ctx) {
+    if (_footprintOwner && _footprintOwner !== ctx)
+        return;
+    if (!_footprint)
+        _footprint = new SessionFootprintCollector();
+    _footprintOwner = ctx;
+    _footprint.start();
+}
+function stopFootprint(ctx) {
+    if (_footprintOwner !== ctx)
+        return;
+    _footprintOwner = null;
+    _footprint?.stop();
+}
 // ── Private HTTP helpers ────────────────────────────────────────────────
 /** Send a JSON response with no-store cache control. */
 function sendJson(res, status, payload) {
@@ -267,69 +507,64 @@ function sendJson(res, status, payload) {
     res.setHeader('cache-control', 'no-store');
     res.end(JSON.stringify(payload));
 }
-/**
- * Read an optional JSON request body, bounded so a client cannot feed the
- * host an unbounded buffer. Returns null for an empty, oversized, or
- * unparseable body — callers treat that as "no override supplied".
- */
-async function readJsonBody(req, limit = 4096) {
-    try {
-        const chunks = [];
-        let size = 0;
-        for await (const chunk of req) {
-            size += chunk.length;
-            if (size > limit)
-                return null;
-            chunks.push(chunk);
-        }
-        if (chunks.length === 0)
-            return null;
-        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
-    }
-    catch (_) {
-        return null;
-    }
-}
 // ── apply() ─────────────────────────────────────────────────────────────
 export function apply(ctx, config) {
     // ── Settings namespace registration ──────────────────────────────────
     ctx.inject(['settings'], (settingsCtx) => {
         settingsCtx.effect(() => settingsCtx.settings.configure({ auto: false }, ctx.fiber));
     });
+    // ── Workspace-registry capture ───────────────────────────────────────
+    // Grab the runtime's archived-session id list so the footprint collector can
+    // intersect it with on-disk session dirs. The registry is injected lazily;
+    // if it is unavailable at apply-time the footprint still scans the disk (and
+    // simply reports the archived count from whatever the registry later yields,
+    // or 0 if it never appears).
+    ctx.inject(['workspaceRegistry'], (regCtx) => {
+        setWorkspaceRegistry(regCtx);
+        // The registry may arrive after the collector's first scan already ran
+        // with no archived ids → refresh it immediately so the count is correct.
+        _footprint?.rescan();
+    });
+    // ── Session-footprint collector bootstrap ────────────────────────────
+    // Low-frequency disk scan (5-minute cadence by default), cached on the host.
+    // Owned exclusively by this ctx; overlapping apply/dispose cycles are safe.
+    startFootprint(ctx);
+    ctx.effect(() => {
+        const owner = ctx;
+        return () => { stopFootprint(owner); };
+    }, 'dsh-flash-mem-mon: session-footprint collector lifecycle');
     // ── Memory trend collector bootstrap ──────────────────────────────────
-    // One bounded ring buffer per process. Starts on first apply and stops on
-    // dispose. The timer uses .unref() so it never keeps the process alive.
-    if (!_memoryTrend)
-        _memoryTrend = new MemoryTrendCollector();
-    _memoryTrend.start((config.memPollBase?.get?.() ?? config.memPollBase) || DEFAULT_MEM_POLL_BASE, (config.memPollMin?.get?.() ?? config.memPollMin) || DEFAULT_MEM_POLL_MIN);
+    // One bounded ring buffer per process, owned exclusively by the active ctx.
+    // startTrend/stopTrend are idempotent and owner-guarded, so overlapping
+    // apply/dispose cycles never double-start or kill a still-live collector.
+    startTrend(ctx, config);
     ctx.effect(() => {
-        const collector = _memoryTrend;
-        return () => {
-            collector?.stop();
-            _memoryTrend = null;
-        };
-    });
+        const owner = ctx;
+        return () => { stopTrend(owner); };
+    }, 'dsh-flash-mem-mon: memory-trend collector lifecycle');
     // ── Volatile-update handler for poll intervals ────────────────────────
     // Restart the collector when memPollBase or memPollMin change.
     ctx.on('loader/volatile-update', (paths) => {
         const memPaths = ['memPollBase', 'memPollMin'];
         if (!paths.some((pp) => pp.length && memPaths.includes(pp[pp.length - 1])))
             return;
-        if (_memoryTrend) {
-            _memoryTrend.stop();
-            _memoryTrend.start((config.memPollBase?.get?.() ?? config.memPollBase) || DEFAULT_MEM_POLL_BASE, (config.memPollMin?.get?.() ?? config.memPollMin) || DEFAULT_MEM_POLL_MIN);
-        }
+        restartTrend(config);
     });
     // ── HTTP API route for client-side trend data ────────────────────────
-    // The webServer type augmentation lives in @deepseek-ai/dsh-host-webserver
-    // which is not a direct dependency; cast through `any` for the register calls.
+    // Uses a structural HostWebServer type instead of `any`. cordis's inject()
+    // callback is statically typed as Context (the real webServer augmentation
+    // lives in @deepseek-ai/dsh-host-webserver, not a compile-time dep here), so
+    // the injected service is read through one narrow cast inside the callback —
+    // when inject(keys) fires, the service is guaranteed present — then used
+    // under the strong HostWebServer type for the whole register/effect block.
     ctx.inject(['webServer'], (wsCtx) => {
+        const ws = wsCtx.webServer;
         // GET /plugins/dsh-flash-mem-mon/memory-trend
         // Returns memory trend data for the client's config popup.
         // `mode=summary` returns a lightweight snapshot (current, peak, trend direction);
         // `mode=full` returns the raw samples for rendering a chart.
         // Optional `since` (unix ms) limits the range.
-        wsCtx.effect(() => wsCtx.webServer.register({
+        wsCtx.effect(() => ws.register({
             kind: 'exact',
             path: '/plugins/dsh-flash-mem-mon/memory-trend',
             handler: async (req, res) => {
@@ -347,26 +582,115 @@ export function apply(ctx, config) {
                 const since = parseInt(u.searchParams.get('since') || '0', 10) || 0;
                 const mode = u.searchParams.get('mode') || 'summary';
                 if (mode === 'full') {
-                    // For gcEvents: when no explicit `since` is requested (since=0),
-                    // pass 0 so ALL stored events are returned — not just the last 5 min.
-                    // gcEvents(0) → cutoff=0 → returns everything.
-                    // gcEvents(undefined) → cutoff=now-5min → only recent events.
-                    // The sparkline may span hours, so we need the full range.
-                    const gcSince = since > 0 ? since : 0;
-                    // Only return full (major) GC events to the client — minor GC is too
-                    // frequent and clutters the chart.  These are already coalesced into
-                    // one event per real cycle by `_startGcObserver`.  Minor GC stats are
+                    // `since` is already >= 0 here; 0 means "entire range" (SINCE_ALL),
+                    // so both `query` and `gcEvents` share the same bounds convention.
+                    // Only full (major) GC events are sent — minor GC is too frequent
+                    // and clutters the chart.  These are already coalesced into one
+                    // event per real cycle by `_startGcObserver`.  Minor GC stats are
                     // still available via mode=summary (majorPerMin, gcPausePerMin).
-                    const majorGcEvents = _memoryTrend.gcEvents(gcSince);
+                    const majorGcEvents = _memoryTrend.gcEvents(since);
                     sendJson(res, 200, {
-                        samples: _memoryTrend.query(since || undefined),
+                        samples: _memoryTrend.query(since),
                         gcEvents: majorGcEvents,
                     });
                 }
                 else {
-                    sendJson(res, 200, _memoryTrend.summary(since || undefined));
+                    sendJson(res, 200, _memoryTrend.summary(since));
                 }
             },
         }), 'dsh-flash-mem-mon: GET /plugins/dsh-flash-mem-mon/memory-trend');
+        // GET /plugins/dsh-flash-mem-mon/session-footprint
+        // Returns the host's cached session-footprint snapshot (total / archived
+        // session counts + per-workspace and total on-disk bytes). Serves only the
+        // cached result of the low-frequency disk scan — never triggers a scan on
+        // demand, so repeated client polls (or a reload while the modal is open)
+        // cannot hammer the filesystem. `scannedAt` is the unix-ms time of the last
+        // completed scan (0 before the first scan finishes).
+        wsCtx.effect(() => ws.register({
+            kind: 'exact',
+            path: '/plugins/dsh-flash-mem-mon/session-footprint',
+            handler: async (req, res) => {
+                if (req.method !== 'GET') {
+                    res.statusCode = 405;
+                    res.setHeader('allow', 'GET');
+                    res.end();
+                    return;
+                }
+                const snap = _footprint?.snapshot() ?? null;
+                sendJson(res, 200, snap ?? {
+                    totalSessions: 0,
+                    archivedSessions: 0,
+                    bytes: 0,
+                    workspaces: [],
+                    scannedAt: 0,
+                });
+            },
+        }), 'dsh-flash-mem-mon: GET /plugins/dsh-flash-mem-mon/session-footprint');
+        // POST /plugins/dsh-flash-mem-mon/dump-heap
+        // Triggered by the "立即转储堆快照" disposal button attached to a memory
+        // alert (see lib/client.js createHostMemoryAlertProvider → actions).
+        // Synchronously writes a .heapsnapshot into the OS temp dir (the one
+        // acceptable place to block the main thread: the user asked for it), then
+        // records it as the latest snapshot and returns its name+size so the
+        // client can confirm and pull it down. Auto-dump is deliberately NOT
+        // offered anywhere — a runaway gleaning loop must never stall the host.
+        wsCtx.effect(() => ws.register({
+            kind: 'exact',
+            path: '/plugins/dsh-flash-mem-mon/dump-heap',
+            handler: async (_req, res) => {
+                if (_req.method !== 'POST') {
+                    res.statusCode = 405;
+                    res.setHeader('allow', 'POST');
+                    res.end();
+                    return;
+                }
+                const name = `dsh-flash-mem-mon-${Date.now()}.${process.pid}.heapsnapshot`;
+                const path = join(tmpdir(), name);
+                try {
+                    writeHeapSnapshot(path);
+                    const info = await stat(path);
+                    _lastSnapshot = { name, path, size: info.size };
+                    sendJson(res, 200, { ok: true, name, size: info.size, path });
+                }
+                catch (err) {
+                    sendJson(res, 500, { ok: false, error: (err && err.message) || 'heap snapshot failed' });
+                }
+            },
+        }), 'dsh-flash-mem-mon: POST /plugins/dsh-flash-mem-mon/dump-heap');
+        // GET /plugins/dsh-flash-mem-mon/heap-dump
+        // Streams the most recent heap snapshot back to the client as an
+        // attachment. One latest-at-a-time is fine here: dumps are user-paced and
+        // downloading is immediate, so keeping a whole archive is unnecessary
+        // (and the tmp files are already pruned by the OS over time).
+        wsCtx.effect(() => ws.register({
+            kind: 'exact',
+            path: '/plugins/dsh-flash-mem-mon/heap-dump',
+            handler: async (_req, res) => {
+                if (_req.method !== 'GET') {
+                    res.statusCode = 405;
+                    res.setHeader('allow', 'GET');
+                    res.end();
+                    return;
+                }
+                const snap = _lastSnapshot;
+                if (!snap) {
+                    sendJson(res, 404, { error: 'No heap snapshot available yet' });
+                    return;
+                }
+                try {
+                    await stat(snap.path); // ensure it still exists
+                    res.statusCode = 200;
+                    res.setHeader('content-type', 'application/octet-stream');
+                    res.setHeader('content-length', String(snap.size));
+                    res.setHeader('content-disposition', `attachment; filename="${snap.name}"`);
+                    res.setHeader('cache-control', 'no-store');
+                    createReadStream(snap.path).pipe(res);
+                }
+                catch (_e) {
+                    _lastSnapshot = null; // stale entry; drop it
+                    sendJson(res, 404, { error: 'Heap snapshot no longer available' });
+                }
+            },
+        }), 'dsh-flash-mem-mon: GET /plugins/dsh-flash-mem-mon/heap-dump');
     });
 }