dsh-homepage 0.1.4 → 0.1.5

package/docs/card-api.md

@@ -80,7 +80,7 @@ including a built-in one — requires `override: true`, otherwise it throws.
 | `effects` | `{outline, ripple, sheen, float, spotlight}` | all off | Animation defaults (see Effects). |
 | `refreshMs` | number | `0` | Refresh hint for polling bodies; the card still owns its timer. |
 | `expandable` / `draggable` / `resizable` | boolean | `true` | Turn that interaction off. |
-| `onMount` / `onExpand` / `onCollapse` | `(api) => void` | `null` | Lifecycle callbacks. |
+| `onMount` / `onExpand` / `onCollapse` | `(api) => void` | `null` | Lifecycle callbacks. `onMount` fires the first time the card is actually on the wall — a hidden card runs nothing until it is shown. |
 | `tags` / `order` / `version` | string[] / number / string | `[]` / `0` / `null` | Manifest tags, initial position hint (drag order wins) and registrant version. |
 | `dict` | `{zh, en}` | `null` | Card-local strings merged into the locale service. |
 | `override` | boolean | `false` | Required to replace another plugin's card. |
@@ -105,7 +105,9 @@ including a built-in one — requires `override: true`, otherwise it throws.
 
 Framework hooks are on `hooks`: `useStore()`, `useRemote(endpoint, args, {refreshMs, enabled})`
 (returns `{data, error, busy, reload, at, failures}`), `useClock(ms)`, `useNoticeOnce(api, key, level, text)`
-and `useAnnounce(api, key, notice)`.
+and `useAnnounce(api, key, notice)`. A poll is scheduled one tick at a time with a little
+jitter (about ±10%) so cards mounted together do not keep refreshing together, and
+`enabled: false` (or `refreshMs: 0`) stops the timer entirely.
 
 ## Controls (`actions` / `detailActions`)
 

package/lib/cards/device.js

@@ -139,6 +139,12 @@
 
     /**
      * The polling interval, in ms, that the card's own control asks for.
+     *
+     * Five seconds is the original cadence and stays: what makes a fast poll
+     * cheap is the host, which reads CPU and memory in-process and refreshes
+     * the GPU/temperature probes on their own slower, cached schedule instead
+     * of paying for one on every request. A slower control is still offered for
+     * readers who want it.
      * @param api - the card's API bag.
      * @returns the interval in ms, at least one second.
      */

package/lib/client.js

@@ -575,6 +575,9 @@ window.__ModuleLoader__.load({
         card: next,
         previous: existing || null,
       })
+      // A card registered after the wall booted is mounted only if it is on
+      // the wall; a hidden one waits until it is shown.
+      if (bootstrapped && store.hostReady && cardVisible(next)) mountCard(next)
       return next
     }
 
@@ -589,6 +592,7 @@ window.__ModuleLoader__.load({
       registry.splice(registry.indexOf(card), 1)
       delete registryById[id]
       delete store.notifications[id]
+      delete mountedCards[id]
       if (store.expanded === id) store.expanded = null
       if (store.expanded === null) store.focusFrom = null
       bump()
@@ -1310,14 +1314,35 @@ window.__ModuleLoader__.load({
       }, [endpoint, argsKey])
 
       React.useEffect(function () {
+        if (settings.enabled === false) {
+          alive.current = false
+          return undefined
+        }
         alive.current = true
-        if (settings.enabled === false) return undefined
         void load(false)
         if (!settings.refreshMs) return function () { alive.current = false }
-        var timer = setInterval(function () { void load(true) }, settings.refreshMs)
+        var base = Math.max(1000, Number(settings.refreshMs) || 0)
+        var timer = null
+        // Re-arm one timer at a time with a little jitter. Cards that mounted
+        // together would otherwise refresh together forever, and every peak is
+        // paid by the host at once; ±10% spreads them without changing the
+        // cadence a reader sees.
+        var arm = function () {
+          var delay = Math.round(base * (0.9 + Math.random() * 0.2))
+          timer = setTimeout(function () {
+            timer = null
+            if (!alive.current) return
+            void load(true)
+            arm()
+          }, delay)
+          // A card test (or a headless host) must not be kept alive by a poll
+          // it never sees fire; a browser timer has no unref and ignores this.
+          if (timer && typeof timer.unref === 'function') timer.unref()
+        }
+        arm()
         return function () {
           alive.current = false
-          clearInterval(timer)
+          if (timer !== null) clearTimeout(timer)
         }
       }, [load, settings.refreshMs, settings.enabled])
 
@@ -1584,6 +1609,8 @@ window.__ModuleLoader__.load({
       if (!visible) hidden.push(card.id)
       if (!visible && store.expanded === card.id) collapseCard()
       patchState({ hidden: hidden })
+      // A card is mounted when it reaches the wall, not when it was defined.
+      if (visible) mountCard(card)
     }
 
     function textureLayer(texture, card) {
@@ -2928,11 +2955,33 @@ window.__ModuleLoader__.load({
     // -------------------------------------------------------------- bootstrap
 
     var bootstrapped = false
+    /** Cards whose `onMount` already ran; one entry per card id. */
+    var mountedCards = Object.create(null)
+
+    /**
+     * Run a card's `onMount` the first time it is actually on the wall.
+     *
+     * A hidden card is disabled: it is not rendered, it polls nothing, and it
+     * must not get lifecycle work either. The old bootstrap ran every
+     * registered card's `onMount` before the persisted visibility was known,
+     * so a disabled card still armed whatever its hook armed.
+     * @param card - a registered card.
+     */
+    function mountCard(card) {
+      if (mountedCards[card.id] === true) return
+      mountedCards[card.id] = true
+      runOnMount(card)
+    }
+
+    /** Mount every card the persisted layout puts on the wall. */
+    function mountVisibleCards() {
+      orderedCards().filter(cardVisible).forEach(mountCard)
+    }
+
     /** Load the persisted layout and install card hooks exactly once. */
     function bootstrap() {
       if (bootstrapped) return Promise.resolve()
       bootstrapped = true
-      registry.forEach(function (card) { runOnMount(card) })
       return remoteCall('homepage/state', {}).then(function (persisted) {
         if (persisted && typeof persisted === 'object') {
           store.state = stateDocumentOf(persisted)
@@ -2946,6 +2995,11 @@ window.__ModuleLoader__.load({
         store.hostReady = true
         bump()
         return null
+      }).then(function (value) {
+        // Only after the visibility document is in hand: a card the user hid
+        // is not mounted and runs nothing.
+        mountVisibleCards()
+        return value
       })
     }
 
@@ -6222,6 +6276,12 @@ var STYLES = [
 
       /**
        * The polling interval, in ms, that the card's own control asks for.
+       *
+       * Five seconds is the original cadence and stays: what makes a fast poll
+       * cheap is the host, which reads CPU and memory in-process and refreshes
+       * the GPU/temperature probes on their own slower, cached schedule instead
+       * of paying for one on every request. A slower control is still offered for
+       * readers who want it.
        * @param api - the card's API bag.
        * @returns the interval in ms, at least one second.
        */

package/lib/framework.part.js

@@ -563,6 +563,9 @@ window.__ModuleLoader__.load({
         card: next,
         previous: existing || null,
       })
+      // A card registered after the wall booted is mounted only if it is on
+      // the wall; a hidden one waits until it is shown.
+      if (bootstrapped && store.hostReady && cardVisible(next)) mountCard(next)
       return next
     }
 
@@ -577,6 +580,7 @@ window.__ModuleLoader__.load({
       registry.splice(registry.indexOf(card), 1)
       delete registryById[id]
       delete store.notifications[id]
+      delete mountedCards[id]
       if (store.expanded === id) store.expanded = null
       if (store.expanded === null) store.focusFrom = null
       bump()
@@ -1298,14 +1302,35 @@ window.__ModuleLoader__.load({
       }, [endpoint, argsKey])
 
       React.useEffect(function () {
+        if (settings.enabled === false) {
+          alive.current = false
+          return undefined
+        }
         alive.current = true
-        if (settings.enabled === false) return undefined
         void load(false)
         if (!settings.refreshMs) return function () { alive.current = false }
-        var timer = setInterval(function () { void load(true) }, settings.refreshMs)
+        var base = Math.max(1000, Number(settings.refreshMs) || 0)
+        var timer = null
+        // Re-arm one timer at a time with a little jitter. Cards that mounted
+        // together would otherwise refresh together forever, and every peak is
+        // paid by the host at once; ±10% spreads them without changing the
+        // cadence a reader sees.
+        var arm = function () {
+          var delay = Math.round(base * (0.9 + Math.random() * 0.2))
+          timer = setTimeout(function () {
+            timer = null
+            if (!alive.current) return
+            void load(true)
+            arm()
+          }, delay)
+          // A card test (or a headless host) must not be kept alive by a poll
+          // it never sees fire; a browser timer has no unref and ignores this.
+          if (timer && typeof timer.unref === 'function') timer.unref()
+        }
+        arm()
         return function () {
           alive.current = false
-          clearInterval(timer)
+          if (timer !== null) clearTimeout(timer)
         }
       }, [load, settings.refreshMs, settings.enabled])
 
@@ -1572,6 +1597,8 @@ window.__ModuleLoader__.load({
       if (!visible) hidden.push(card.id)
       if (!visible && store.expanded === card.id) collapseCard()
       patchState({ hidden: hidden })
+      // A card is mounted when it reaches the wall, not when it was defined.
+      if (visible) mountCard(card)
     }
 
     function textureLayer(texture, card) {
@@ -2916,11 +2943,33 @@ window.__ModuleLoader__.load({
     // -------------------------------------------------------------- bootstrap
 
     var bootstrapped = false
+    /** Cards whose `onMount` already ran; one entry per card id. */
+    var mountedCards = Object.create(null)
+
+    /**
+     * Run a card's `onMount` the first time it is actually on the wall.
+     *
+     * A hidden card is disabled: it is not rendered, it polls nothing, and it
+     * must not get lifecycle work either. The old bootstrap ran every
+     * registered card's `onMount` before the persisted visibility was known,
+     * so a disabled card still armed whatever its hook armed.
+     * @param card - a registered card.
+     */
+    function mountCard(card) {
+      if (mountedCards[card.id] === true) return
+      mountedCards[card.id] = true
+      runOnMount(card)
+    }
+
+    /** Mount every card the persisted layout puts on the wall. */
+    function mountVisibleCards() {
+      orderedCards().filter(cardVisible).forEach(mountCard)
+    }
+
     /** Load the persisted layout and install card hooks exactly once. */
     function bootstrap() {
       if (bootstrapped) return Promise.resolve()
       bootstrapped = true
-      registry.forEach(function (card) { runOnMount(card) })
       return remoteCall('homepage/state', {}).then(function (persisted) {
         if (persisted && typeof persisted === 'object') {
           store.state = stateDocumentOf(persisted)
@@ -2934,6 +2983,11 @@ window.__ModuleLoader__.load({
         store.hostReady = true
         bump()
         return null
+      }).then(function (value) {
+        // Only after the visibility document is in hand: a card the user hid
+        // is not mounted and runs nothing.
+        mountVisibleCards()
+        return value
       })
     }
 

package/lib/host/device.js

@@ -14,19 +14,25 @@
  *  - CPU usage needs two readings, so the previous `os.cpus()` snapshot is kept
  *    in module state. The first call of a process waits ~250 ms and reads again
  *    rather than reporting a meaningless 0;
- *  - a sample taken less than a second ago is memoized, because several
- *    subscribers poll the same endpoint at once;
+ *  - a sample taken less than a second ago is memoized, and a sample still in
+ *    flight is shared by every caller, because several subscribers poll the
+ *    same endpoint at once;
  *  - the temperature probe costs a subprocess, so it is cached for
- *    `temperatureTtlMs` and sampled on its own schedule. `temperature: false`
- *    skips it outright, which is what the periodic history sampler passes;
+ *    `temperatureTtlMs`. `temperature: false` skips it outright;
  *  - the GPU counters are the expensive read: Windows needs one PowerShell
  *    spawn and Linux needs one `nvidia-smi` spawn when no sysfs card answers,
- *    so the verdict is cached for `gpuTtlMs`. A Linux machine whose amdgpu
- *    publishes `gpu_busy_percent` reads plain files and spawns nothing at all.
- *    `gpu: false` skips the block outright — the same cheap path the periodic
- *    history sampler takes;
- *  - `startDeviceSampler()` drives that cheap path on an unref-ed interval so
- *    the history buffer fills before anyone opens the panel;
+ *    so the verdict is cached for `gpuTtlMs`, and a failed verdict for
+ *    `GPU_FAILURE_TTL_MS`. A Linux machine whose amdgpu publishes
+ *    `gpu_busy_percent` reads plain files and spawns nothing at all. `gpu: false`
+ *    skips the block outright;
+ *  - a stale temperature or GPU cache is served immediately while its probe
+ *    refreshes in the background; only the first request (a cold cache) waits.
+ *    That is what keeps a fast poll as cheap as a performance panel: CPU,
+ *    memory and disk are read in-process, and the subprocess blocks are
+ *    refreshed on their own slower cadence;
+ *  - the plugin arms no background sampler: every sample is on demand, so an
+ *    installed page nobody opened probes nothing. `startDeviceSampler()` exists
+ *    for a caller that wants the cheap history path, and it never spawns;
  *  - history is an in-memory ring buffer per process only — it is deliberately
  *    NOT persisted anywhere;
  *  - every source is injectable through `options`, which is what lets the unit
@@ -58,7 +64,17 @@ const WINDOWS_PLATFORMS = new Set(['win32', 'windows', 'win'])
 const PERMISSION_CODES = new Set(['EACCES', 'EPERM'])
 
 /** How long one GPU probe's verdict is reused; that probe costs a subprocess. */
-const GPU_TTL_MS = 5000
+const GPU_TTL_MS = 30000
+
+/**
+ * How long a failed GPU verdict is reused.
+ *
+ * A machine whose counters are disabled, unreadable or slow kept paying a
+ * PowerShell spawn on every poll. Reusing the failure for a minute turns a
+ * per-poll subprocess into one a minute without hiding a recovered machine for
+ * long.
+ */
+const GPU_FAILURE_TTL_MS = 60000
 
 /**
  * How long the GPU probe may run before it is killed.
@@ -165,8 +181,16 @@ let lastSample = null
 /** Cached temperature verdict plus the epoch ms it was taken at. */
 let temperatureCache = null
 
-/** Cached GPU block plus the epoch ms the probe was run at. */
+/** Cached GPU block plus the epoch ms the probe finished at. */
 let gpuCache = null
+/** The GPU probe currently in flight, shared by concurrent readers. */
+let gpuPending = null
+/** The temperature probe currently in flight, shared by concurrent readers. */
+let temperaturePending = null
+/** The sample currently in flight, shared by concurrent readers. */
+let samplePending = null
+/** Bumped by `resetDeviceCache()`; a stale probe must not refill a reset cache. */
+let cacheEpoch = 0
 /** Appended per real sample; in memory for this process only. */
 let history = []
 /** Set once the first call has paid for its second CPU reading. */
@@ -721,16 +745,53 @@ async function readTemperature(deps) {
 }
 
 /**
- * Hand back the cached temperature verdict while its TTL holds.
+ * Run one temperature probe, sharing it with any caller already waiting.
+ *
+ * The cache is stamped when the probe finishes rather than when it started, so
+ * a slow subprocess is not immediately stale. `resetDeviceCache()` bumps the
+ * epoch, which keeps a probe that lands after a reset from repopulating it.
+ * @param deps - the resolved dependency bag.
+ * @returns `{ celsius, source, reason }`.
+ */
+async function probeTemperature(deps) {
+  if (temperaturePending !== null) return temperaturePending
+  const epoch = cacheEpoch
+  const run = (async () => {
+    const value = await readTemperature(deps)
+    if (epoch === cacheEpoch) {
+      temperatureCache = { at: deps.now(), value: value, ttlMs: deps.temperatureTtlMs }
+    }
+    return value
+  })()
+  temperaturePending = run
+  try {
+    return await run
+  } finally {
+    if (temperaturePending === run) temperaturePending = null
+  }
+}
+
+/**
+ * The temperature block for one sample.
+ *
+ * A performance panel must stay cheap at a fast cadence, so this never blocks a
+ * poll on the subprocess probe:
+ *  - a warm cache answers directly;
+ *  - a stale cache answers with its last value at once and refreshes in the
+ *    background — the next poll picks the new reading up;
+ *  - a cold cache (the first request after start) waits once, so the card is
+ *    never blank.
  * @param deps - the resolved dependency bag.
  * @returns `{ celsius, source, reason }`.
  */
 async function temperature(deps) {
   const at = deps.now()
-  if (temperatureCache && at - temperatureCache.at < deps.temperatureTtlMs) return temperatureCache.value
-  const value = await readTemperature(deps)
-  temperatureCache = { at: at, value: value }
-  return value
+  if (temperatureCache && at - temperatureCache.at < temperatureCache.ttlMs) return temperatureCache.value
+  const stale = temperatureCache ? temperatureCache.value : null
+  const run = probeTemperature(deps)
+  if (stale === null) return run
+  run.catch(() => {})
+  return stale
 }
 
 // -------------------------------------------------------------------- gpu
@@ -1262,16 +1323,56 @@ async function readGpu(deps) {
 }
 
 /**
- * Hand back the cached GPU block while its TTL holds.
+ * Run one GPU probe, sharing it with any caller already waiting.
+ *
+ * The cache is stamped when the probe finishes, and a failed verdict gets the
+ * longer `GPU_FAILURE_TTL_MS` so a broken counter provider is not retried at
+ * poll speed. The epoch guard keeps a late probe out of a reset cache.
+ * @param deps - the resolved dependency bag.
+ * @returns the `gpu` block; never rejects.
+ */
+async function probeGpu(deps) {
+  if (gpuPending !== null) return gpuPending
+  const epoch = cacheEpoch
+  const run = (async () => {
+    const value = await readGpu(deps)
+    if (epoch === cacheEpoch) {
+      const failed = !value || value.usage === null
+      gpuCache = {
+        at: deps.now(),
+        value: value,
+        ttlMs: failed ? GPU_FAILURE_TTL_MS : deps.gpuTtlMs,
+      }
+    }
+    return value
+  })()
+  gpuPending = run
+  try {
+    return await run
+  } finally {
+    if (gpuPending === run) gpuPending = null
+  }
+}
+
+/**
+ * The GPU block for one sample.
+ *
+ * The probe is the most expensive read the surface makes, so a poll never waits
+ * for a refresh: a warm cache answers directly, a stale cache answers with its
+ * last value while the probe runs in the background, and only a cold cache (the
+ * first request) waits. That is what lets the card poll quickly for CPU and
+ * memory without making the GPU a per-poll subprocess.
  * @param deps - the resolved dependency bag.
  * @returns the `gpu` block; never rejects.
  */
 async function gpuReading(deps) {
   const at = deps.now()
-  if (gpuCache && at - gpuCache.at < deps.gpuTtlMs) return gpuCache.value
-  const value = await readGpu(deps)
-  gpuCache = { at: at, value: value }
-  return value
+  if (gpuCache && at - gpuCache.at < gpuCache.ttlMs) return gpuCache.value
+  const stale = gpuCache ? gpuCache.value : null
+  const run = probeGpu(deps)
+  if (stale === null) return run
+  run.catch(() => {})
+  return stale
 }
 
 // ------------------------------------------------------------------ cache
@@ -1282,11 +1383,15 @@ async function gpuReading(deps) {
  * @returns nothing.
  */
 export function resetDeviceCache() {
+  cacheEpoch += 1
   prevTimes = null
   prevAt = null
   lastSample = null
   temperatureCache = null
+  temperaturePending = null
   gpuCache = null
+  gpuPending = null
+  samplePending = null
   history = []
   firstReadDone = false
 }
@@ -1314,7 +1419,7 @@ function resolve(options) {
     sleep: typeof input.sleep === 'function' ? input.sleep : defaultSleep,
     temperatureTtlMs: toFinite(input.temperatureTtlMs) !== null && input.temperatureTtlMs >= 0
       ? input.temperatureTtlMs
-      : 60000,
+      : 120000,
     temperature: input.temperature !== false,
     gpuTtlMs: toFinite(input.gpuTtlMs) !== null && input.gpuTtlMs >= 0
       ? input.gpuTtlMs
@@ -1361,8 +1466,15 @@ async function gather(deps) {
   const previousAt = prevAt
   prevAt = at
   const memory = readMemory(deps.os)
-  const thermal = deps.temperature ? await temperature(deps) : { celsius: null, source: null, reason: 'skipped' }
-  const gpu = deps.gpu ? await gpuReading(deps) : emptyGpu('skipped')
+  // The two hardware blocks are independent: a cold start pays for them in
+  // parallel rather than one after the other. Once warm, both resolve from
+  // cache in the same tick, so a fast poll never waits on a subprocess.
+  const blocks = await Promise.all([
+    deps.temperature ? temperature(deps) : { celsius: null, source: null, reason: 'skipped' },
+    deps.gpu ? gpuReading(deps) : emptyGpu('skipped'),
+  ])
+  const thermal = blocks[0]
+  const gpu = blocks[1]
   const drive = systemDrive(deps.platform)
 
   const cpu = {
@@ -1416,40 +1528,51 @@ async function gather(deps) {
  *
  * Never rejects: every source that fails degrades to `null`, to a `reason`
  * code, or to zeros, and the rest of the document still comes back. A call
- * inside the one-second dedupe window returns the memoized document unchanged.
+ * inside the one-second dedupe window returns the memoized document unchanged,
+ * and a call made while a sample is still gathering shares that sample instead
+ * of starting a second set of probes.
  * @param options - injectable sources and limits; see the module docblock.
  * @returns the sample document.
  */
 export async function sampleDevice(options = {}) {
   const deps = resolve(options)
-  try {
-    const at = deps.now()
-    if (lastSample && at - lastSample.at < MIN_SAMPLE_INTERVAL_MS) return lastSample
-    const sample = await gather(deps)
-    lastSample = sample
-    return sample
-  } catch (error) {
-    return {
-      at: deps.now(),
-      sampleSeconds: 0,
-      cpu: { usage: 0, cores: [], count: 0, model: '', speedMhz: 0, loadavg: null },
-      memory: { total: 0, free: 0, used: 0, usage: 0, swapTotal: 0, swapFree: 0, swapUsed: 0 },
-      temperature: { celsius: null, source: null, reason: 'error' },
-      gpu: emptyGpu('error'),
-      disk: null,
-      system: {
-        platform: deps.platform,
-        arch: deps.platform,
-        release: '',
-        hostname: '',
-        uptime: 0,
-        node: process.version,
-        cpuModel: '',
-        drive: null,
-      },
-      history: history.slice(),
-      error: error && error.message ? String(error.message) : 'sample failed',
+  const at = deps.now()
+  if (lastSample && at - lastSample.at < MIN_SAMPLE_INTERVAL_MS) return lastSample
+  if (samplePending !== null) return samplePending
+  const run = (async () => {
+    try {
+      const sample = await gather(deps)
+      lastSample = sample
+      return sample
+    } catch (error) {
+      return {
+        at: deps.now(),
+        sampleSeconds: 0,
+        cpu: { usage: 0, cores: [], count: 0, model: '', speedMhz: 0, loadavg: null },
+        memory: { total: 0, free: 0, used: 0, usage: 0, swapTotal: 0, swapFree: 0, swapUsed: 0 },
+        temperature: { celsius: null, source: null, reason: 'error' },
+        gpu: emptyGpu('error'),
+        disk: null,
+        system: {
+          platform: deps.platform,
+          arch: deps.platform,
+          release: '',
+          hostname: '',
+          uptime: 0,
+          node: process.version,
+          cpuModel: '',
+          drive: null,
+        },
+        history: history.slice(),
+        error: error && error.message ? String(error.message) : 'sample failed',
+      }
     }
+  })()
+  samplePending = run
+  try {
+    return await run
+  } finally {
+    if (samplePending === run) samplePending = null
   }
 }
 

package/lib/index.js

@@ -25,7 +25,7 @@ import { createActions } from './host/actions.js'
 import { versionFromEntry } from './host/audit.js'
 import { createAuditRunner } from './host/audit-runner.js'
 import { createCollector } from './host/collector.js'
-import { sampleDevice, startDeviceSampler } from './host/device.js'
+import { sampleDevice } from './host/device.js'
 import { sampleDshRelease } from './host/dsh.js'
 import { defaultInstallRoot, listInstalled, startInstall } from './host/dsh-install.js'
 import { createHygiene } from './host/hygiene.js'
@@ -127,20 +127,6 @@ const MICRO = 1000000
 const DAY_KEEP = 180
 const HISTORY_DAYS = 21
 const MIN_SAMPLE_INTERVAL_MS = 15000
-/** Delay before the start-up observation, long enough for the account service to mount. */
-const BOOT_SAMPLE_DELAY_MS = 4000
-/**
- * Background observation cadence. The ledger's per-day spend is the drop between
- * the first and the latest sample of the day, so a day nobody looks at still
- * needs more than one point. Thirty minutes is 48 free reads a day — enough to
- * show when the spending happened without hammering the Platform.
- */
-const BACKGROUND_SAMPLE_MS = 30 * 60 * 1000
-// The device card's history only exists while something samples it. A tick this
-// slow costs one `os.cpus()` read and keeps a usable window in front of whoever
-// opens the card; the tick deliberately does not touch the temperature, which
-// would shell out to the system on a timer nobody is watching.
-const DEVICE_SAMPLE_MS = 15000
 
 // --------------------------------------------------------------- storage
 
@@ -558,6 +544,13 @@ async function loadLedger() {
   return value
 }
 
+/**
+ * The account read currently in flight, shared by every concurrent on-demand
+ * overview. A page that is closed never reaches this module: the plugin arms no
+ * background account timer, so an idle instance performs no Platform reads.
+ */
+let balanceReadPending = null
+
 /**
  * Sample the account, fold the result into the ledger and persist it.
  * @param ctx - plugin context.
@@ -565,22 +558,34 @@ async function loadLedger() {
  * @returns the read outcome, with the ledger attached.
  */
 async function sample(ctx, force) {
-  const ledger = await loadLedger()
-  const now = Date.now()
-  if (!force && now - Number(ledger.lastAttemptAt || 0) < MIN_SAMPLE_INTERVAL_MS) {
-    return { ledger: ledger, read: ledger.lastOutcome || null, sampled: false, at: Number(ledger.lastAttemptAt || 0) }
-  }
-  const read = await readBalance(ctx)
-  ledger.lastAttemptAt = now
-  ledger.lastOutcome = { ok: read.ok, reason: read.reason || null, message: read.message || null, view: read.view || null }
-  if (read.ok) {
-    applySample(ledger, read.wallets, now)
-    ledger.wallet = read.wallets
-    ledger.bonusWallets = read.bonusWallets
-    ledger.walletAt = now
+  // Two card instances asking at the same moment (the wall preview and the
+  // expanded page) share one read instead of spending two.
+  if (!force && balanceReadPending !== null) return balanceReadPending
+  const run = (async () => {
+    const ledger = await loadLedger()
+    const now = Date.now()
+    if (!force && now - Number(ledger.lastAttemptAt || 0) < MIN_SAMPLE_INTERVAL_MS) {
+      return { ledger: ledger, read: ledger.lastOutcome || null, sampled: false, at: Number(ledger.lastAttemptAt || 0) }
+    }
+    const read = await readBalance(ctx)
+    ledger.lastAttemptAt = now
+    ledger.lastOutcome = { ok: read.ok, reason: read.reason || null, message: read.message || null, view: read.view || null }
+    if (read.ok) {
+      applySample(ledger, read.wallets, now)
+      ledger.wallet = read.wallets
+      ledger.bonusWallets = read.bonusWallets
+      ledger.walletAt = now
+    }
+    try { await writeJson(ledgerPath(), ledger) } catch { /* a failed cache write must not fail the read */ }
+    return { ledger: ledger, read: read, sampled: true, at: now }
+  })()
+  if (force) return run
+  balanceReadPending = run
+  try {
+    return await run
+  } finally {
+    if (balanceReadPending === run) balanceReadPending = null
   }
-  try { await writeJson(ledgerPath(), ledger) } catch { /* a failed cache write must not fail the read */ }
-  return { ledger: ledger, read: read, sampled: true, at: now }
 }
 
 /**
@@ -2125,37 +2130,11 @@ export function apply(ctx, config) {
     }
   }
 
-  // Take one observation shortly after start, then keep observing on a slow
-  // interval. The ledger then carries a real balance before anyone opens the
-  // panel, and a day left alone still gets a curve instead of a single sample
-  // (one sample cannot show when the spend happened, and `today.partial` says
-  // so). The delay lets the account service finish mounting, and a failure is
-  // recorded in the ledger rather than thrown at start-up.
-  ctx.effect(() => {
-    const take = () => { sample(ctx, false).catch(() => {}) }
-    const timer = service(ctx, 'timer')
-    if (timer && typeof timer.timeout === 'function' && typeof timer.interval === 'function') {
-      const stopTimeout = timer.timeout(take, BOOT_SAMPLE_DELAY_MS)
-      const stopInterval = timer.interval(take, BACKGROUND_SAMPLE_MS)
-      return () => {
-        if (typeof stopTimeout === 'function') stopTimeout()
-        if (typeof stopInterval === 'function') stopInterval()
-      }
-    }
-    const timeout = setTimeout(take, BOOT_SAMPLE_DELAY_MS)
-    const interval = setInterval(take, BACKGROUND_SAMPLE_MS)
-    return () => { clearTimeout(timeout); clearInterval(interval) }
-  }, name + ': balance sampling')
-
-  // Keep the device card's history warm, so the chart has a window the moment
-  // somebody opens it. The tick is deliberately cheap: two `os` reads and never
-  // a temperature probe, which is cached and only runs while the card polls.
-  ctx.effect(() => {
-    const take = () => { sampleDevice({ temperature: false }).catch(() => {}) }
-    const timer = service(ctx, 'timer')
-    if (timer && typeof timer.interval === 'function') return timer.interval(take, DEVICE_SAMPLE_MS)
-    return startDeviceSampler({ intervalMs: DEVICE_SAMPLE_MS })
-  }, name + ': device sampling')
+  // No background sampling lives past this point. The account ledger and the
+  // device history are filled only by an on-demand read (an open card or the
+  // model-facing tool), so an installed-but-unused plugin runs nothing: no
+  // Platform requests, no subprocesses, no timers. Disabled cards never mount,
+  // so they never call an endpoint either.
 }
 
 /** @returns one error carrying the plugin's own prefix, without doubling it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-homepage",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "DeepSeek Harness plugin: a personal home page in the sidebar for a DSH instance. Review a plugin before installing it, and read sessions, projects, tool usage, device, storage, DSH cores, Skills and cost from one composable, registrable card wall.",
   "keywords": [
     "dsh-plugin",