dsh-usage-badge 0.1.4 → 0.1.6

package/lib/index.js

@@ -15,11 +15,15 @@
  * @module dsh-usage-badge
  */
 
-import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { createHash, randomBytes } from 'node:crypto'
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { hostname } from 'node:os'
 import { join } from 'node:path'
 
 import { createCacheStore } from './cache-store.js'
 import { createAggregator, mergeRecords, resolveDshHome } from './fold.js'
+import { SyncEngine, acquireLock, readSyncDocument, releaseLock, safeDeviceId } from './sync.js'
+import { normalizeWebdavUrl } from './webdav.js'
 import { describeCalendar, loadBundledTable, resolveHolidayRules } from './holidays.js'
 import { OFFICIAL_SOURCES, applyOfficialPricing, fetchOfficialPricing } from './official-pricing.js'
 import {
@@ -53,7 +57,7 @@ const ROUTE_PREFIX = '/usage-badge'
  * (an unknown patch key is accepted with a 200 and ignored). The panel compares this number
  * and says so instead. `test/client.render.mjs` asserts the two halves agree.
  */
-export const HOST_API_VERSION = 6
+export const HOST_API_VERSION = 7
 
 /**
  * Directory under `$DSH_HOME/storages` holding every file this plugin owns, so its
@@ -75,6 +79,48 @@ const DAYS_KEPT = 400
 /** A snapshot younger than this is reused instead of rebuilt on every poll. */
 const SNAPSHOT_TTL_MS = 2000
 
+/**
+ * How long after an edit the price table is published.
+ *
+ * Long enough that editing three rows in a row is one publish rather than three, short enough that the
+ * person is still on the page when it happens. Only ever reached when sync is on and configured.
+ */
+export const PRICING_PUSH_DELAY_MS = 3000
+
+/** How long after startup the first automatic sync runs, when sync is enabled. */
+export const STARTUP_SYNC_DELAY_MS = 8000
+
+/**
+ * How long the panel waits for a status read before it is told the answer is not ready.
+ *
+ * The status read may ask the server what devices it holds. That happens in the background, but this
+ * bound is what keeps a slow or black-holed server from making the whole dialog look frozen.
+ */
+const STATUS_TIMEOUT_MS = 5000
+
+/** Resolve `promise`, or reject once `ms` have passed, so a route can always answer. */
+function withTimeout(promise, ms, what) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      const timer = setTimeout(() => reject(new Error(`${what} took longer than ${Math.round(ms / 1000)}s`)), ms)
+      timer.unref?.()
+    }),
+  ])
+}
+
+/**
+ * The delay to actually use, overridable so a test does not have to wait out a real one.
+ *
+ * Reading it per call rather than at import time is what lets a test set the variable, mount the plugin,
+ * and still get the short delay — the host half is imported once per scenario with a cache-busting
+ * query, but a constant captured at module load would freeze whatever the first reader saw.
+ */
+function delayFor(name, fallback) {
+  const configured = Number(process.env[name])
+  return Number.isFinite(configured) && configured >= 0 ? configured : fallback
+}
+
 /**
  * How long a fetched price list is reused. Opening the dialog asks for a fresh
  * copy every time, and this window only coalesces the requests that arrive within
@@ -409,6 +455,23 @@ function readPricing(paths) {
 }
 
 /** Read a request body, bounded. An oversized one is a 413, not a server error. */
+/**
+ * Read a JSON request body, reporting a malformed one as the caller's mistake.
+ *
+ * A bare `JSON.parse` throws a `SyntaxError` with no status, which the route wrapper can only answer with a
+ * 500 — and a 500 for a body the client got wrong sends whoever is debugging it looking at the host.
+ */
+async function readJsonBody(req) {
+  const text = (await readBody(req)) || '{}'
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    const bad = new Error(`the request body is not JSON: ${error?.message ?? error}`)
+    bad.statusCode = 400
+    throw bad
+  }
+}
+
 function readBody(req) {
   return new Promise((resolvePromise, rejectPromise) => {
     const chunks = []
@@ -517,6 +580,57 @@ export function apply(ctx) {
   const aggregator = createAggregator({ sessionsRoot, store, log })
   aggregator.loadCache()
 
+  /**
+   * The sync system, created **on first use** rather than when the plugin mounts.
+   *
+   * Creating it eagerly would write `host.lock` and `sync.json` into the data directory of every
+   * install, including the many that never turn sync on — and would quietly change the directory a
+   * user is looking at. Mounting a plugin should not do that; asking it to sync should.
+   *
+   * The lock decides who may **write**: a second DSH instance pointed at the same home cannot share a
+   * `deviceId`, because two processes would each believe the same remote shard is theirs to overwrite.
+   * The instance that loses is not broken and does not refuse to start — it reports why and declines to
+   * sync, which is the same answer the design gives to a read-only cache.
+   */
+  let system = null
+  function syncSystem() {
+    if (system) return system
+    const document = readSyncDocument(dataDir, log)
+    const instanceId = document.instanceId || `${hostname()}-${process.pid}`
+    const lock = acquireLock(dataDir, { instanceId, log })
+    if (!lock.acquired) log(`usage-badge is read-only here: ${lock.reason}`)
+    const engine = new SyncEngine({
+      dataDir,
+      store: lock.acquired ? store : null,
+      log,
+      config: document,
+      state: document.state,
+      instanceId,
+    })
+    if (!document.deviceId) engine.save({ config: { deviceId: `${hostname()}-${randomBytes(3).toString('hex')}` } })
+    // **This** is where the lock becomes ours, not inside `run()`: the host takes it once, when the system
+    // comes into being, and hands the already-held lock to every run. Without this the engine reported
+    // `ownsLock: false`, so `release()` declined to remove a lock this very process was holding — and the
+    // next mount of the same directory was refused by this plugin's own lock, naming a live pid.
+    engine.ownsLock = lock.acquired
+    system = {
+      engine,
+      lock,
+      instanceId,
+      running: null,
+      pushing: null,
+      // The last run is **persisted** state, so a restart must show it rather than "从未": the panel's
+      // first question is "when did this last work", and the answer is in `sync.json` — the engine wrote
+      // it there precisely so that it would outlive the process.
+      last: {
+        result: document.state?.lastResult || (lock.acquired ? 'never' : 'locked'),
+        message: document.state?.message ?? (lock.acquired ? '' : lock.reason),
+        at: Number(document.state?.lastSyncAt) || 0,
+      },
+    }
+    return system
+  }
+
   const { path: pricingSourcePath } = readRawPricing(pricingPaths)
   if (pricingSourcePath === legacyPricingPath) {
     log(`reading the price table from the pre-isolation path ${legacyPricingPath}; the next write moves it to ${pricingPath}`)
@@ -543,6 +657,196 @@ export function apply(ctx) {
     return inFlight
   }
 
+  /**
+   * The sync state the panel reads: configuration, lock ownership, and the last run's outcome.
+   *
+   * The configuration is **rebuilt field by field** rather than spread. A spread would forward whatever a
+   * hand-edited `sync.json` happens to contain — and an older build of this plugin wrote exactly such a
+   * field, `password`, in plaintext. A blacklist that removes `ha1` and forwards everything else is one
+   * forgotten key away from putting a credential in an HTTP response.
+   */
+  function safeSyncConfig(config = {}) {
+    const ha1 = String(config.ha1 ?? '')
+    return {
+      enabled: Boolean(config.enabled),
+      url: String(config.url ?? ''),
+      username: String(config.username ?? ''),
+      realm: String(config.realm ?? ''),
+      allowInsecureTls: Boolean(config.allowInsecureTls),
+      deviceId: String(config.deviceId ?? ''),
+      deviceLabel: String(config.deviceLabel ?? ''),
+      windowYears: Number(config.windowYears) || 0,
+      instanceId: String(config.instanceId ?? ''),
+      hasCredential: Boolean(ha1),
+      // Only a real HA1 counts. `password` and `passwordHash` are fields an older build could leave behind,
+      // and `connect()` cannot use either — claiming a credential exists would enable 立即同步 and then
+      // fail with "no WebDAV credential is configured" the moment it was pressed.
+      credentialPrefix: ha1.length >= 16 ? `${ha1.slice(0, 6)}…` : '',
+    }
+  }
+
+  function conflictFiles() {
+    try {
+      return readdirSync(dataDir).filter((name) => name.startsWith('.conflict-'))
+    } catch {
+      return []
+    }
+  }
+
+  /** The devices the **server** holds, remembered between polls. Never a network call. */
+  let knownRemote = null
+  /** How long that answer is reused: the panel polls every 2s while a run is in flight. */
+  const REMOTE_CACHE_MS = 30_000
+
+  async function refreshRemoteDevices() {
+    if (!system?.engine?.store || !system.engine.config.enabled) return
+    if (system.syncAbort) return
+    if (system.remoteInFlight) return
+    system.remoteInFlight = true
+    try {
+      const client = system.engine.connect()
+      knownRemote = { devices: await system.engine.discover(client), at: Date.now() }
+    } catch (error) {
+      // A site the panel can show as "unknown" is better than an exception on every poll.
+      knownRemote = { devices: null, at: Date.now(), error: String(error?.message ?? error) }
+    } finally {
+      system.remoteInFlight = false
+    }
+  }
+
+  /**
+   * Every piece of work that talks to the server goes through one queue.
+   *
+   * The owner lock keeps two **processes** apart; inside one process it cannot, because the host holds it for
+   * its whole life. Without this, 立即同步 and the automatic price push run as two independent chains: a run's
+   * `PROPFIND` and a push's `GET pricing.json` would already be interleaving on the wire (measured), and both
+   * mutate the same `engine.state` and rewrite `sync.json`, so whichever finishes last decides what the panel
+   * says about the other.
+   */
+  function enqueue(instance, work) {
+    const next = (instance.chain ?? Promise.resolve()).then(work, work)
+    // The chain must survive a rejection — neither breaking on it nor leaving it unhandled.
+    instance.chain = next.then(
+      () => {},
+      () => {},
+    )
+    return next
+  }
+
+  async function syncStatus() {
+    // Reading the status must not create anything either, so an untouched install answers with the
+    // sensible defaults rather than acquiring a lock it has no intention of using.
+    if (!system) {
+      const document = readSyncDocument(dataDir, log)
+      return {
+        config: safeSyncConfig({ ...document, hasCredential: Boolean(document.ha1 || document.passwordHash || document.password) }),
+        writable: true,
+        lock: null,
+        running: false,
+        last: {
+          result: document.state?.lastResult || 'never',
+          message: document.state?.message ?? '',
+          at: Number(document.state?.lastSyncAt) || 0,
+        },
+        collision: document.state?.collision ?? null,
+        remoteDevices: {},
+        // `null` rather than `{}`: nothing has asked the server yet, and an empty map would read as "there
+        // are no other devices".
+        remoteKnown: false,
+        remoteError: null,
+        published: {},
+        conflictFiles: conflictFiles(),
+        paths: { sync: join(dataDir, 'sync.json'), pricing: pricingPath },
+      }
+    }
+    const { engine, lock, running, last } = system
+    const pulled = {}
+    for (const context of Object.keys(engine.state.held ?? {})) {
+      const device = context.split('/')[0]
+      pulled[device] = (pulled[device] ?? 0) + 1
+    }
+    // The count of shards this device has actually read, and the names the server holds, are two
+    // different questions. The panel shows both: "已同步到的月份" from `held`, and "服务器上的设备" from
+    // this list, so a device that published but was never pulled from still shows up. Refreshed at most
+    // every `REMOTE_CACHE_MS` — the panel polls during a run, and a `PROPFIND` per poll would be a lot of
+    // requests for a list that changes when someone else syncs.
+    if (!knownRemote || Date.now() - (knownRemote.at ?? 0) > REMOTE_CACHE_MS) void refreshRemoteDevices()
+    return {
+      config: safeSyncConfig(engine.config),
+      writable: Boolean(engine.store),
+      lock: lock.acquired ? null : { reason: lock.reason, owner: lock.owner ?? null, pid: process.pid },
+      running: Boolean(running),
+      last,
+      collision: engine.state.collision ?? null,
+      remoteDevices: pulled,
+      remoteKnown: Boolean(knownRemote?.devices),
+      remoteError: knownRemote?.error ?? null,
+      remoteDevicesOnServer: knownRemote?.devices ?? null,
+      published: engine.state.published ?? {},
+      conflictFiles: conflictFiles(),
+      paths: { sync: join(dataDir, 'sync.json'), pricing: pricingPath },
+    }
+  }
+
+  /**
+   * Run one sync, at most one at a time.
+   *
+   * The host owns the lock for as long as it lives, so an automatic pricing push that lands mid-run
+   * waits on the same chain rather than racing it — two writers on one data directory is the case the
+   * lock exists for, and a lock cannot serialise work inside a single process.
+   */
+  function runSync() {
+    const instance = syncSystem()
+    if (!instance.running) {
+      instance.running = enqueue(instance, async () => {
+        if (!instance.engine.store) {
+          // The cache is read-only here (another instance holds the lock, a permission problem, a newer
+          // schema). The sync would publish a history this process cannot even fold, so it declines
+          // rather than doing half of it.
+          return { result: 'locked', message: instance.lock.reason ?? 'the cache is read-only here', at: 0 }
+        }
+        try {
+          await refreshOnce()
+        } catch (error) {
+          // Refreshing is what makes the store worth publishing; without it there is nothing to send. A
+          // rejection here used to escape the route and the startup timer as an unhandled rejection.
+          return { result: 'failed', message: `could not fold the logs: ${error?.message ?? error}`, at: 0 }
+        }
+        // The system already owns the lock from the moment it was created; taking it again in the same
+        // process would see this process's own lock file and refuse. It is re-acquired only when the
+        // system was created without one (a second instance that lost the race).
+        const attempt = instance.lock?.acquired
+          ? instance.lock
+          : acquireLock(dataDir, { instanceId: instance.instanceId, log })
+        if (!attempt.acquired) return { result: 'locked', message: attempt.reason, at: 0 }
+        try {
+          const result = await instance.engine.run({ lock: attempt })
+          // A shard may have carried a newer price table; the panel's next poll should see it.
+          pricing = readPricing(pricingPaths)
+          rules = resolveHolidayRules(pricing.holidays)
+          // The engine's own record of when this happened, not "now": `locked` and `skipped` deliberately
+          // leave `lastSyncAt` alone, and showing a fresh timestamp for them would claim a sync that did
+          // not happen.
+          return { ...result, at: Number(instance.engine.state.lastSyncAt) || 0 }
+        } catch (error) {
+          // `SyncEngine.run` catches its own failures; this is the belt to its braces, so a bug there
+          // cannot take the host half down.
+          log(`sync failed unexpectedly: ${error?.message ?? error}`)
+          return { result: 'failed', message: String(error?.message ?? error), at: 0 }
+        }
+        // Nothing to release: the lock belongs to the system and lives as long as this process does.
+      })
+        .then((result) => {
+          instance.last = { result: result.result, message: result.message, at: result.at ?? 0 }
+          return result
+        })
+        .finally(() => {
+          instance.running = null
+        })
+    }
+    return instance.running
+  }
+
   async function getSnapshot() {
     const status = await refreshOnce()
     // Nothing changed and the previous payload is still fresh: reuse it rather
@@ -577,8 +881,73 @@ export function apply(ctx) {
     pricing = normalizePricing(next)
     rules = resolveHolidayRules(pricing.holidays)
     snapshot = null // force a rebuild on the next read
+    // The price table is the one hand-written thing this plugin owns, so an edit is worth publishing
+    // while the person is still looking at the page. It is fire-and-forget: a sync that cannot reach
+    // the server must never make a local edit fail, and the state it leaves behind is what the panel
+    // reports.
+    schedulePricingPush()
+  }
+
+  /**
+   * Publish just the price table, a moment after the last edit.
+   *
+   * Debounced because editing a row and then the one below it is one intention, not two publishes, and
+   * because the fetch it needs would otherwise happen on every keystroke-sized save. It only ever runs
+   * when sync was already configured and enabled: a local edit is not a reason to create `sync.json`.
+   */
+  let pricingPushTimer = null
+  function schedulePricingPush() {
+    const configured = system ? system.engine.config : readSyncDocument(dataDir, log)
+    if (!configured.enabled || !configured.url || !configured.ha1) return
+    if (pricingPushTimer) clearTimeout(pricingPushTimer)
+    pricingPushTimer = setTimeout(() => {
+      pricingPushTimer = null
+      const instance = syncSystem()
+      if (!instance.lock?.acquired || !instance.engine.store) return
+      // Onto the **same** queue as a full run, so an edit landing mid-sync waits for it instead of
+      // interleaving its PUTs and its `sync.json` write with the run's.
+      instance.pushing = enqueue(instance, () => instance.engine.pushPricing({ lock: instance.lock, instanceId: instance.instanceId }))
+        .then((result) => {
+          log(`pricing pushed after an edit: ${result.result} — ${result.status}`)
+          instance.last = { result: result.result, message: `prices: ${result.status}`, at: result.result === 'ok' ? Number(instance.engine.state.lastSyncAt) || 0 : instance.last?.at ?? 0 }
+          return result
+        })
+        .catch((error) => {
+          log(`pricing push failed: ${error?.message ?? error}`)
+          instance.last = { result: 'failed', message: `prices: ${error?.message ?? error}`, at: instance.last?.at ?? 0 }
+        })
+    }, delayFor('DSH_USAGE_BADGE_PRICING_PUSH_MS', PRICING_PUSH_DELAY_MS))
+    pricingPushTimer.unref?.()
   }
 
+  /**
+   * The first automatic sync, a little after startup.
+   *
+   * Deliberately conditional: it only runs when sync is **already configured and enabled**, so a home
+   * that never turned sync on stays untouched (no `sync.json`, no lock, no network). The delay exists so
+   * the cold fold and the first panel paint come first — a sync on the way up would compete with the
+   * work that makes the badge show anything at all.
+   *
+   * It is also skipped when the instance is not the writer: on a second DSH instance the lock belongs to
+   * the first, and the honest answer is to do nothing rather than take the lock away from it.
+   */
+  function scheduleStartupSync(delayMs = delayFor('DSH_USAGE_BADGE_STARTUP_SYNC_MS', STARTUP_SYNC_DELAY_MS)) {
+    const configured = readSyncDocument(dataDir, log)
+    if (!configured.enabled || !configured.url || !configured.ha1) return
+    const timer = setTimeout(() => {
+      startupSyncTimer = null
+      const instance = syncSystem()
+      if (!instance.lock?.acquired) {
+        log(`startup sync skipped: ${instance.lock?.reason ?? 'no lock'}`)
+        return
+      }
+      void runSync().then((result) => log(`startup sync: ${result.result} — ${result.message}`))
+    }, delayMs)
+    timer.unref?.()
+    startupSyncTimer = timer
+  }
+  let startupSyncTimer = null
+
   async function warm() {
     try {
       const status = await refreshOnce()
@@ -688,7 +1057,7 @@ export function apply(ctx) {
           sendJson(res, 403, { error: 'config writes are accepted from loopback clients only' })
           return
         }
-        const patch = JSON.parse((await readBody(req)) || '{}')
+        const patch = await readJsonBody(req)
         commitPricing(mergeConfig(readRawPricing(pricingPaths).raw, patch))
         log('pricing config updated')
         sendJson(res, 200, { ok: true, effective: pricing, calendar: describeCalendar(rules) })
@@ -709,7 +1078,7 @@ export function apply(ctx) {
           sendJson(res, 403, { error: 'config writes are accepted from loopback clients only' })
           return
         }
-        const body = JSON.parse((await readBody(req)) || '{}')
+        const body = await readJsonBody(req)
         // Apply the copy the user was looking at, reusing the recent fetch rather
         // than pulling a possibly different page under them.
         const parsed = await officialPricing(body.source ?? 'zh-cn')
@@ -736,6 +1105,131 @@ export function apply(ctx) {
         return
       }
 
+      // ── cloud sync ──────────────────────────────────────────────────────────
+      //
+      // The panel's third tab. The credential never travels back: `ha1` is reported as a short prefix
+      // plus a `hasCredential` flag, so the state of "is one configured" is visible without the secret
+      // leaving the host half.
+      if (route === '/sync' && req.method === 'GET') {
+        // Loopback only, like every other sync route. The answer names the server and the account, and
+        // reading it *is* engaging with sync — this is where the system comes into being, and with it the
+        // owner lock. A page that never opens this tab still touches nothing.
+        if (!isLoopback(req)) {
+          sendJson(res, 403, { error: 'the sync status is visible to loopback clients only' })
+          return
+        }
+        syncSystem()
+        let body
+        try {
+          body = await withTimeout(syncStatus(), STATUS_TIMEOUT_MS, 'reading the sync status')
+        } catch (error) {
+          sendJson(res, 200, { error: String(error?.message ?? error) })
+          return
+        }
+        sendJson(res, 200, body)
+        return
+      }
+
+      if (route === '/sync' && (req.method === 'PUT' || req.method === 'POST')) {
+        if (!isLoopback(req)) {
+          sendJson(res, 403, { error: 'sync writes are accepted from loopback clients only' })
+          return
+        }
+        const instance = syncSystem()
+        const patch = await readJsonBody(req)
+        const config = {}
+        for (const field of ['enabled', 'url', 'username', 'allowInsecureTls', 'deviceLabel', 'deviceId', 'realm']) {
+          if (patch[field] !== undefined) config[field] = patch[field]
+        }
+        if (patch.windowYears !== undefined) config.windowYears = Math.max(0, Math.min(50, Number(patch.windowYears) || 0))
+        if (typeof patch.deviceId === 'string' && patch.deviceId !== '') {
+          try {
+            config.deviceId = safeDeviceId(patch.deviceId)
+          } catch (error) {
+            sendJson(res, 400, { error: error.message })
+            return
+          }
+        }
+        // Either a plaintext password (hashed here, immediately, and never stored) or an HA1 someone
+        // pasted in — the same value the server keeps in its password file.
+        //
+        // The realm is part of the digest input, so it has to be right before the password can be hashed.
+        // The panel does not offer it as a field: a person has no reason to care, and the servers this is
+        // built for use `WebDAV`. So it defaults here rather than being demanded — requiring it made
+        // "fill in address/user/password and press 保存" fail with a sentence about a term the UI never
+        // showed. A connection test replaces the guess with the realm the server actually announced.
+        if (typeof patch.password === 'string' && patch.password !== '') {
+          const username = String(patch.username ?? instance.engine.config.username ?? '')
+          const realm = String(patch.realm ?? instance.engine.config.realm ?? '').trim() || 'WebDAV'
+          if (!username) {
+            sendJson(res, 400, { error: 'a username is needed to hash the password' })
+            return
+          }
+          config.ha1 = createHash('md5').update(`${username}:${realm}:${patch.password}`).digest('hex')
+          config.realm = realm
+        } else if (typeof patch.ha1 === 'string' && /^[0-9a-f]{32}$/i.test(patch.ha1)) {
+          config.ha1 = patch.ha1.toLowerCase()
+        }
+        if (typeof config.url === 'string' && config.url !== '') {
+          // The **same** judgement the client makes, from the same function. A copy here is what let the
+          // route accept a query string, embedded credentials and `ftp:` — addresses the client refuses —
+          // so the panel stored one, showed it, and the sync could not run at all. Two copies of a rule
+          // drift; one copy cannot.
+          const judged = normalizeWebdavUrl(config.url)
+          if (!judged.ok) {
+            sendJson(res, 400, { error: judged.reason })
+            return
+          }
+          // The trailing slash is **added** rather than demanded: someone typing `host:port` means the
+          // collection at that address. The panel stores what this returns, so the field ends up showing
+          // the address that will actually be used instead of the one that was typed.
+          config.url = judged.url
+        }
+        instance.engine.save({ config })
+        log(`sync configuration updated (${instance.engine.config.enabled ? 'on' : 'off'}, device ${instance.engine.config.deviceId})`)
+        sendJson(res, 200, { ok: true, ...(await syncStatus()) })
+        return
+      }
+
+      // A connection check: it must not sync, and it must not write anything anywhere.
+      if (route === '/sync/test' && req.method === 'POST') {
+        if (!isLoopback(req)) {
+          sendJson(res, 403, { error: 'sync writes are accepted from loopback clients only' })
+          return
+        }
+        // The client is kept across the catch so a **failure** can still report the realm the server
+        // announced. That realm is the missing piece when someone's server does not use `WebDAV`: the
+        // password was hashed against the default, so nothing can work until it is re-hashed against the
+        // real one — and without this the panel had no way to learn it.
+        let client = null
+        try {
+          client = syncSystem().engine.connect()
+          const options = await client.options()
+          const devices = await syncSystem().engine.discover(client)
+          sendJson(res, 200, {
+            ok: true,
+            realm: options.realm,
+            dav: options.dav,
+            devices,
+            insecure: Boolean(client.insecureWarning),
+            warning: client.insecureWarning ?? null,
+          })
+        } catch (error) {
+          sendJson(res, 200, { ok: false, error: String(error?.message ?? error), realm: client?.challenge?.realm ?? null })
+        }
+        return
+      }
+
+      if (route === '/sync/run' && req.method === 'POST') {
+        if (!isLoopback(req)) {
+          sendJson(res, 403, { error: 'sync writes are accepted from loopback clients only' })
+          return
+        }
+        const result = await runSync()
+        sendJson(res, 200, { ok: result.result === 'ok' || result.result === 'partial', ...result, ...(await syncStatus()) })
+        return
+      }
+
       sendJson(res, 404, { error: `no such usage-badge route: ${route}` })
     } catch (error) {
       // A caller's mistake is reported as one; only genuinely unexpected failures are 500s.
@@ -751,9 +1245,45 @@ export function apply(ctx) {
   )
 
   ctx.effect(() => {
-    void warm()
-    return () => aggregator.close()
-  }, 'usage-badge: warm the fold and close the cache on unload')
+    // The delay is read **here**, synchronously, rather than inside the warm-up callback: warming is
+    // asynchronous, and a value read after it would be whatever the environment holds by then — which a
+    // test that sets an override for exactly this mount would already have taken away.
+    const startupDelay = delayFor('DSH_USAGE_BADGE_STARTUP_SYNC_MS', STARTUP_SYNC_DELAY_MS)
+    // Unloading before the first fold finishes used to schedule the first sync *after* the unload: the
+    // callback ran anyway, took the lock back, and synced through a store that had already been closed
+    // (`statement has been finalized`), leaving a lock file behind for a host that was gone.
+    let disposed = false
+    void warm().then(() => {
+      if (disposed) return
+      scheduleStartupSync(startupDelay)
+      // Fire and forget: this only fills in what the server holds, for the panel's next read.
+      void refreshRemoteDevices()
+    })
+    return () => {
+      disposed = true
+      // Any pending automatic work is dropped on unload: a push that fires while the host is going away
+      // would write state for a process that no longer exists.
+      if (pricingPushTimer) clearTimeout(pricingPushTimer)
+      if (startupSyncTimer) clearTimeout(startupSyncTimer)
+      // **And the lock is handed back.** Not releasing it leaves `host.lock` naming this dead process, and a
+      // re-mount inside the same process — a hot reload, or a test mounting the same home twice — is then
+      // refused by this plugin's own lock, for a pid that is very much alive: its own.
+      //
+      // `engine.release()` alone is not enough: a run in flight was handed the host's lock object, and the
+      // engine only releases one it acquired itself (`ownsLock`), so unloading mid-run would leave the file
+      // behind. `releaseLock` checks the pid, so this can only ever remove our own.
+      if (system) {
+        system.syncAbort = true
+        // Stops a run at its next step boundary. Requests already on the wire finish; the phases that would
+        // touch the store do not start.
+        system.engine.abort()
+        system.engine.release()
+        if (system.running) log('unloading while a sync is in flight; it stops at its next step boundary')
+      }
+      releaseLock(dataDir)
+      aggregator.close()
+    }
+  }, 'usage-badge: warm the fold, schedule the first sync, and close the cache on unload')
 
   log(`mounted on ${ROUTE_PREFIX} (home: ${home}; data: ${dataDir})`)
 }