pi-lemonade-link 1.0.1 → 1.0.2

package/README.md

@@ -411,7 +411,7 @@ The full shape (values shown are the built-in defaults):
 | `barPollMs` | Server-poll cadence for the status bar's busy/queue + CPU/GPU/NPU/VRAM segments. `0` = local metrics only (instance, tok/s, cache-hit %). |
 | `specCheck` / `specCheckCooldownMs` / `specCheckTimeoutMs` | Docs-freshness check: the `docs/` snapshot is compared against upstream `lemonade-sdk/lemonade` by git blob SHA — **TUI-only status, no startup warning** (extension ↔ server agreement is what matters; see *Keeping the specs honest*); the verdict is durable for `specCheckCooldownMs` (default 24 h, also the upstream-release probe's throttle). |
 | `serverVersionCheck` | **Tier 1, startup warning**: `/v1/health` self-reports the server version; any instance reporting a version other than the build this extension was verified against (`v11.7.0` — a constant in the extension code, not a setting) warns **with direction**: server newer → check for an extension update; server older → update the server. |
-| `upstreamVersionCheck` | **Tier 2, info notice**: servers older than the latest published lemonade release (probed via GitHub, throttled) get a one-line "a server update is available" notice. Default on; separately toggleable. |
+| `upstreamVersionCheck` | **Tier 2, info notice**: servers older than the latest published lemonade release (probed via GitHub, throttled) get a one-line "a server update is available" notice — **deduplicated to once per (instance, release)**, so it never re-fires on every session for the same release; the TUI always shows current state. Default on; separately toggleable. |
 
 ## Offline & unreachable networks
 
@@ -561,7 +561,11 @@ Drift is watched **in tiers, ordered by what actually matters at runtime**:
    server older than it gets a single info line — *"instance 'x' runs
    lemonade v11.7.0; the latest published release is v11.9.0 — a server
    update is available."* Much lower tier: an older server isn't broken,
-   it's just behind. `upstreamVersionCheck: false` disables.
+   it's just behind. The notice is **deduplicated to once per (instance,
+   release)** — it fires when a new upstream release first appears, never
+   re-fires on every session for the same fact; `/lemonade-setup` →
+   Spec & version check always shows the current state.
+   `upstreamVersionCheck: false` disables.
 3. **Docs drift — TUI-only status, deliberately no startup warning.** The
    `docs/` snapshot is the reference for the version the extension targets;
    as long as extension and server agree on version, whether upstream HEAD

package/index.ts

@@ -105,7 +105,8 @@ interface LemonadeConfig {
   serverVersionCheck: boolean;
   // Low-tier notice: compare each server's live version against the latest
   // published lemonade release (GitHub releases); server older → one-line
-  // info notice. Separately toggleable; default on.
+  // info notice, deduplicated to once per (instance, new release) — the
+  // TUI always shows the live truth. Separately toggleable; default on.
   upstreamVersionCheck: boolean;
   discoveryTimeoutMs: number;
   beaconTimeoutMs: number;
@@ -718,6 +719,11 @@ const GH_LATEST_RELEASE = "https://api.github.com/repos/lemonade-sdk/lemonade/re
 interface UpstreamVersionSnapshot {
   checkedAt: number;
   latest: string;
+  /** Tier-2 notice dedup: instance → the latest release version at the
+   *  time that instance was last noticed. "A server update is available"
+   *  fires once per (instance, release) — never a per-session nag about
+   *  the same fact; the TUI always shows the live truth. */
+  notified?: Record<string, string>;
 }
 
 function upstreamSnapshotPath(): string {
@@ -727,7 +733,11 @@ function upstreamSnapshotPath(): string {
 function loadUpstreamSnapshot(): UpstreamVersionSnapshot | undefined {
   try {
     const raw = JSON.parse(fs.readFileSync(upstreamSnapshotPath(), "utf8")) as UpstreamVersionSnapshot;
-    return typeof raw.checkedAt === "number" && typeof raw.latest === "string" ? raw : undefined;
+    const notifiedOk =
+      raw.notified === undefined ||
+      (typeof raw.notified === "object" && raw.notified !== null &&
+        Object.values(raw.notified).every((v) => typeof v === "string"));
+    return typeof raw.checkedAt === "number" && typeof raw.latest === "string" && notifiedOk ? raw : undefined;
   } catch {
     return undefined;
   }
@@ -755,7 +765,7 @@ async function latestUpstreamVersion(config: LemonadeConfig): Promise<string | u
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       const tag = ((await res.json()) as { tag_name?: string }).tag_name;
       if (typeof tag !== "string" || !tag) throw new Error("release carried no tag_name");
-      saveUpstreamSnapshot({ checkedAt: Date.now(), latest: tag.replace(/^v/, "") });
+      saveUpstreamSnapshot({ checkedAt: Date.now(), latest: tag.replace(/^v/, ""), notified: fresh?.notified });
     } catch (error) {
       console.error(
         `[pi-lemonade-link] upstream-version probe skipped: ${error instanceof Error ? error.message : error}`
@@ -764,7 +774,7 @@ async function latestUpstreamVersion(config: LemonadeConfig): Promise<string | u
       // pass per cooldown") — otherwise offline days re-probe at every
       // session start. Keep the last known latest; a failed probe proves
       // nothing new (unknown ≠ outdated).
-      saveUpstreamSnapshot({ checkedAt: Date.now(), latest: fresh?.latest ?? "" });
+      saveUpstreamSnapshot({ checkedAt: Date.now(), latest: fresh?.latest ?? "", notified: fresh?.notified });
     }
   }
   return loadUpstreamSnapshot()?.latest;
@@ -842,6 +852,16 @@ function versionCompare(a: string, b: string): number | null {
   return 0;
 }
 
+/** Whether the tier-2 "server update is available" notice is due for one
+ *  instance: the server is behind the latest published release AND this
+ *  exact release hasn't already been noticed for that instance — one
+ *  notice per (instance, release), never a per-session nag about the
+ *  same fact. Pure. */
+function upstreamNoticeDue(serverVersion: string, latest: string, lastNotifiedLatest: string | undefined): boolean {
+  const cmp = versionCompare(serverVersion, latest);
+  return cmp !== null && cmp < 0 && lastNotifiedLatest !== latest;
+}
+
 /** Server-version drift collected during provider registration/refresh
  *  (registerInstanceProvider records; registerLemonadeProvider resets).
  *  direction: "ahead" = server newer than the extension was verified for
@@ -1012,15 +1032,24 @@ function registerSpecDriftWarnings(pi: ExtensionAPI, configRef: { current: Lemon
       void latestUpstreamVersion(config)
         .then((latest) => {
           if (!latest) return;
+          // Dedup: fire the notice once per (instance, release). The TUI
+          // always shows the live truth; the session-start line never
+          // repeats for the same release.
+          const snap = loadUpstreamSnapshot();
+          if (!snap) return;
+          const notified: Record<string, string> = { ...(snap.notified ?? {}) };
+          let dirty = false;
           for (const [instance, serverVersion] of serverVersionsSeen) {
-            const cmp = versionCompare(serverVersion, latest);
-            if (cmp !== null && cmp < 0) {
-              ctx.ui.notify(
-                `pi-lemonade-link: instance "${instance}" runs lemonade v${serverVersion}; the latest published release is v${latest} — a server update is available.`,
-                "info"
-              );
-            }
+            if (!upstreamNoticeDue(serverVersion, latest, notified[instance])) continue;
+            ctx.ui.notify(
+              `pi-lemonade-link: instance "${instance}" runs lemonade v${serverVersion}; the latest published release is v${latest} — a server update is available. ` +
+                `(noted once per release; /lemonade-setup → Spec & version check always shows current status)`,
+              "info"
+            );
+            notified[instance] = latest;
+            dirty = true;
           }
+          if (dirty) saveUpstreamSnapshot({ ...snap, notified });
         })
         .catch((error) =>
           console.error(`[pi-lemonade-link] upstream notice skipped: ${error instanceof Error ? error.message : error}`)
@@ -3002,7 +3031,7 @@ function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeCo
                     const c = upstreamSnap.latest ? versionCompare(v, upstreamSnap.latest) : null;
                     return c !== null && c < 0;
                   })
-                  ? "update available — at least one server is behind the latest published release"
+                  ? "update available — at least one server is behind the latest published release (notice fires once per release)"
                   : `all servers current with the latest published release (v${upstreamSnap.latest})`
                 : "not probed yet";
             const sub = await menu(ctx, "Spec & Version Check", [
@@ -3011,7 +3040,7 @@ function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeCo
               { value: "resync", label: "Re-sync docs/ from upstream", description: "Download the current docs/api markdown into docs/ — ground truth only, the extension code is NOT updated" },
               { value: "toggledocs", label: `Toggle docs check: ${config.specCheck ? "on → off" : "off → on"}`, description: `specCheck (currently ${config.specCheck ? "on" : "off"})` },
               { value: "toggleserver", label: `Toggle server-version check: ${config.serverVersionCheck ? "on → off" : "off → on"}`, description: `serverVersionCheck (currently ${config.serverVersionCheck ? "on" : "off"}) — extension ↔ server sync, the startup warning` },
-              { value: "toggleupstream", label: `Toggle upstream-release notice: ${config.upstreamVersionCheck ? "on → off" : "off → on"}`, description: `upstreamVersionCheck (currently ${config.upstreamVersionCheck ? "on" : "off"}) — "a server update is available", info tier` },
+              { value: "toggleupstream", label: `Toggle upstream-release notice: ${config.upstreamVersionCheck ? "on → off" : "off → on"}`, description: `upstreamVersionCheck (currently ${config.upstreamVersionCheck ? "on" : "off"}) — "a server update is available", info tier, once per release` },
               { value: "back", label: "Back", description: "" },
             ]);
             if (sub === null || sub === "back") break;
@@ -3062,7 +3091,9 @@ function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeCo
                   "nothing at runtime. Re-sync re-downloads the current upstream docs into",
                   "the extension's docs/ folder; it does NOT update the extension code. The",
                   "startup warnings are reserved for extension ↔ server sync (warning) and",
-                  "server-vs-latest-release (one-line info notice).",
+                  "server-vs-latest-release (one-line info notice, deduplicated: it fires",
+                  "once per new release per instance — this view always shows the current",
+                  "state, even when the notice has already fired).",
                 ],
                 true
               );

package/lemonade.example.json

@@ -102,6 +102,8 @@
 
   // Tier 2 (info notice, one sentence): servers older than the latest
   // published lemonade release (probed via GitHub, throttled) get an
-  // "a server update is available" notice. Separately toggleable.
+  // "a server update is available" notice — deduplicated to once per
+  // (instance, release); the /lemonade-setup TUI always shows the current
+  // state. Separately toggleable.
   "upstreamVersionCheck": true
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-lemonade-link",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Unified pi extension for a self-hosted Lemonade server: dynamic chat-model discovery, multimodal agent tools (transcription, image gen/edit/upscale, TTS, audio, 3D mesh), a live /lemonade-setup management TUI, and a lemonade-only below-editor status bar (tok/s, cache hits, busy/queue, VRAM).",
   "keywords": [
     "pi-package",