pi-lemonade-link 1.0.0 → 1.0.2

package/README.md

@@ -282,6 +282,7 @@ and the normal menu takes over once the first instance exists.
 | **Model management** | List catalog (including not-yet-downloaded registry entries), load / unload, pull (download) with live progress + esc-to-cancel, install from Hugging Face (search → pick variant → install as `user.*`), delete, change context size (unload → reload with `ctx_size`, saved), toggle chat-only filter, refresh provider |
 | **Transcription settings** | Default Whisper model, endpoint path, smoke-test a file |
 | **Live server logs** | WebSocket stream of the server's log: full snapshot backlog (up to 5000 entries) then live entries as they happen; Esc to close |
+| **Spec & version check** | The three drift tiers, interactive: docs-vs-upstream status (TUI-only), live per-instance server versions beside the verified build and the latest upstream release, re-check now, one-keystroke docs re-sync (re-downloads upstream docs into the extension's docs/ folder — the code is not updated), `specCheck` / `serverVersionCheck` / `upstreamVersionCheck` toggles |
 
 Notes on the destructive and slow paths:
 
@@ -387,7 +388,12 @@ The full shape (values shown are the built-in defaults):
   "generationTimeoutMs": 600000,
   "statusPollMs": 2000,
   "statusBar": true,
-  "barPollMs": 5000
+  "barPollMs": 5000,
+  "specCheck": true,
+  "specCheckCooldownMs": 86400000,
+  "specCheckTimeoutMs": 5000,
+  "serverVersionCheck": true,
+  "upstreamVersionCheck": true
 }
 ```
 
@@ -403,6 +409,9 @@ The full shape (values shown are the built-in defaults):
 | `statusPollMs` | How often the setup-menu status panel re-fetches while open (live refresh). `0` = static snapshot. |
 | `statusBar` | Show the below-editor lemonade status bar while a lemonade model is active (see *Lemonade status bar*). |
 | `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 — **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
 
@@ -533,6 +542,71 @@ git clone --depth 1 --filter=blob:none --sparse https://github.com/lemonade-sdk/
   && cp docs/api/*.md ~/.pi/agent/extensions/pi-lemonade-link/docs/
 ```
 
+### Keeping the specs honest
+
+Drift is watched **in tiers, ordered by what actually matters at runtime**:
+
+1. **Extension ↔ server sync (startup warning).** Every registration and
+   refresh compares each instance's live `/v1/health` version against the
+   build this extension was verified against (`v11.7.0` — a constant in the
+   extension code, **not a user setting**: it is a property of the code,
+   updated with each extension release). A mismatch is the one signal that
+   means *endpoints may have changed for this pairing*, so it warns —
+   **directionally**: server *newer* → "check for an extension update";
+   server *older* → "update the server, or expect some endpoints to be
+   missing".
+2. **Server ↔ latest published release (info notice, one sentence, on by
+   default, separately toggleable).** The latest published lemonade release
+   is probed via GitHub (throttled, durable, silent on network failure); any
+   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. 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
+   has moved on changes **nothing at runtime** — so it's shown only in
+   `/lemonade-setup` → Spec & version check (per-file status, re-check now,
+   one-keystroke re-sync that re-downloads the current upstream docs into
+   the extension's `docs/` folder). `specCheck: false` disables even the
+   background refresh.
+
+All tiers share the family mechanics: fire-and-forget, never delays
+startup, durable verdicts (at most one network pass per 24 h across
+restarts), silent on network failure (unknown ≠ out of date). The Spec &
+version check view manages every toggle interactively and shows live
+per-instance versions beside the verified build and the latest upstream
+release.
+
+## Extension version & provider API
+
+This extension's version (`version` in `package.json`) and the lemonade
+server build it was verified against (`11.7.0`) are recorded together in
+the `provider` block of `package.json` and in the
+`EXTENSION_CONFIRMED_SERVER_VERSION` constant in `index.ts` (which drives
+the startup version-drift warning). The server status panel and the
+Spec & version check view both show the extension version, the live server
+version(s), and the verified build.
+
+**On update, keep these in lockstep** (all record the same fact):
+
+1. `version` in `package.json` — the extension release
+2. the `provider` block in `package.json` (`apiVerifiedAgainst`,
+   `specSnapshot`) — what that release was verified against
+3. `EXTENSION_CONFIRMED_SERVER_VERSION` in `index.ts` — the peg the
+   version-drift warning compares your servers against
+4. re-sync `docs/` in the extension folder from upstream (the README
+   re-sync command, or `/lemonade-setup` → Spec & version check)
+5. the behavior-reference dates below
+
+A release that skips any of these is lying somewhere — the spec-freshness
+and server-version checks (see *Keeping the specs honest*) are what catch
+#3 and #4 drifting silently.
+
 ## Lemonade behavior reference
 
 Empirically confirmed against lemonade 11.7.0 (cross-checked with the

package/index.ts

@@ -46,6 +46,8 @@ import * as os from "node:os";
 import * as path from "node:path";
 import dgram from "node:dgram";
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
 import { DynamicBorder, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Container, Key, matchesKey, SelectList, Text, truncateToWidth, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
@@ -89,6 +91,23 @@ interface LemonadeConfig {
   statusPollMs: number; // status-panel live-refresh interval while viewing
   statusBar: boolean; // belowEditor bar shown while a lemonade model is active
   barPollMs: number; // bar server-poll cadence; 0 = local metrics only (tok/s, cache, instance)
+  // Spec-freshness: compare the docs/ snapshot against upstream
+  // lemonade-sdk/lemonade by git blob SHA. TUI-only status (Spec & version
+  // check view + re-sync actions) — no startup warning: as long as the
+  // extension and the server agree on version, docs matching upstream HEAD
+  // changes nothing at runtime.
+  specCheck: boolean;
+  specCheckCooldownMs: number; // durable verdicts re-checked at most this often
+  specCheckTimeoutMs: number;
+  // Live-server drift: /v1/health self-reports the server version; a version
+  // other than the build this extension was verified against (a constant in
+  // the code, not config) warns at startup, with direction.
+  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, deduplicated to once per (instance, new release) — the
+  // TUI always shows the live truth. Separately toggleable; default on.
+  upstreamVersionCheck: boolean;
   discoveryTimeoutMs: number;
   beaconTimeoutMs: number;
   loadTimeoutMs: number;
@@ -145,6 +164,11 @@ const DEFAULT_CONFIG: LemonadeConfig = {
   statusPollMs: 2000,
   statusBar: true,
   barPollMs: 5000,
+  specCheck: true,
+  specCheckCooldownMs: 24 * 60 * 60 * 1000,
+  specCheckTimeoutMs: 5000,
+  serverVersionCheck: true,
+  upstreamVersionCheck: true,
   discoveryTimeoutMs: 5000,
   beaconTimeoutMs: 3000,
   loadTimeoutMs: 300_000,
@@ -656,6 +680,390 @@ async function discoverViaHttp(config: LemonadeConfig): Promise<DiscoveredServer
   return [...seen.values()];
 }
 
+// ─── Spec freshness & server-version drift ─────────────────────────────────
+
+/** The two drift signals this extension watches, so "ground truth snapshotted"
+ *  stays honest:
+ *
+ *  1. Docs drift — the docs/ folder is a snapshot of lemonade-sdk/lemonade's
+ *     docs/api (see the README re-sync command). Each file's git blob SHA is
+ *     computed locally at runtime (nothing stored, so re-syncing docs/
+ *     re-arms the comparison) and matched against the same file upstream via
+ *     GitHub's contents API (a tiny JSON response; the markdown is never
+ *     downloaded). Drift → TUI-only status (the Spec & version check
+ *     view); deliberately NO startup warning — extension ↔ server version
+ *     agreement is what matters at runtime.
+ *
+ *  2. Live-server drift — an on-prem box publishes no spec to diff, but it
+ *     self-reports its version in /v1/health. A version this extension's
+ *     behavior reference was never confirmed against is the honest signal
+ *     that endpoints may have changed; each such instance is warned on
+ *     session_start (mismatches are (re)collected on every registration and
+ *     refresh, so fixing the server or the config clears the warning).
+ *
+ *  Both checks are fire-and-forget, never delay startup, and are silent on
+ *  network failure — a hygiene check must never cry wolf on offline
+ *  startups: unknown ≠ out of date. */
+
+const DOCS_FILES = ["README.md", "anthropic.md", "lemonade.md", "llamacpp.md", "mcp.md", "ollama.md", "openai.md"];
+const DOCS_UPSTREAM_BASE = "https://github.com/lemonade-sdk/lemonade/blob/main/docs/api/";
+const DOCS_GH_CONTENTS = (file: string) =>
+  `https://api.github.com/repos/lemonade-sdk/lemonade/contents/docs/api/${file}`;
+const DOCS_RAW = (file: string) => `https://raw.githubusercontent.com/lemonade-sdk/lemonade/main/docs/api/${file}`;
+
+/** Latest published (non-prerelease) lemonade release — the low-tier "a
+ *  server update is available" notice compares each server's live version
+ *  against this. Throttled by the same durable-verdict discipline. */
+const GH_LATEST_RELEASE = "https://api.github.com/repos/lemonade-sdk/lemonade/releases/latest";
+
+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 {
+  return path.join(getAgentDir(), "cache", "pi-lemonade-link", "upstream-version.json");
+}
+
+function loadUpstreamSnapshot(): UpstreamVersionSnapshot | undefined {
+  try {
+    const raw = JSON.parse(fs.readFileSync(upstreamSnapshotPath(), "utf8")) as UpstreamVersionSnapshot;
+    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;
+  }
+}
+
+function saveUpstreamSnapshot(snap: UpstreamVersionSnapshot): void {
+  try {
+    fs.mkdirSync(path.dirname(upstreamSnapshotPath()), { recursive: true });
+    fs.writeFileSync(upstreamSnapshotPath(), JSON.stringify(snap, null, 2) + "\n");
+  } catch {
+    /* cache dir unwritable → re-probe next time */
+  }
+}
+
+/** The latest published lemonade version, or undefined when unreachable
+ *  (unknown ≠ outdated — never cry wolf). */
+async function latestUpstreamVersion(config: LemonadeConfig): Promise<string | undefined> {
+  const fresh = loadUpstreamSnapshot();
+  if (!fresh || Date.now() - fresh.checkedAt >= Math.max(0, config.specCheckCooldownMs)) {
+    try {
+      const res = await fetch(GH_LATEST_RELEASE, {
+        headers: { Accept: "application/vnd.github+json", "User-Agent": "pi-lemonade-link" },
+        signal: AbortSignal.timeout(config.specCheckTimeoutMs),
+      });
+      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/, ""), notified: fresh?.notified });
+    } catch (error) {
+      console.error(
+        `[pi-lemonade-link] upstream-version probe skipped: ${error instanceof Error ? error.message : error}`
+      );
+      // A failed probe must still engage the cooldown ("at most one network
+      // 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 ?? "", notified: fresh?.notified });
+    }
+  }
+  return loadUpstreamSnapshot()?.latest;
+}
+
+/** Git blob SHA of a file's bytes: sha1("blob <size>\0" + content). Pure. */
+function gitBlobSha(data: Buffer): string {
+  return createHash("sha1").update(`blob ${data.length}\0`).update(data).digest("hex");
+}
+
+/** Absolute path of a snapshotted doc, inside this extension's folder. */
+function extensionDocsPath(file: string): string {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), "docs", file);
+}
+
+interface DocsSpecSnapshot {
+  checkedAt: number; // epoch ms of the last real check
+  changed: string[]; // docs/ files whose upstream blob SHA differs (sorted)
+}
+
+function docsSnapshotPath(): string {
+  return path.join(getAgentDir(), "cache", "pi-lemonade-link", "spec-check.json");
+}
+
+function loadDocsSnapshot(): DocsSpecSnapshot | undefined {
+  try {
+    const raw = JSON.parse(fs.readFileSync(docsSnapshotPath(), "utf8")) as DocsSpecSnapshot;
+    return typeof raw.checkedAt === "number" && Array.isArray(raw.changed) ? raw : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function saveDocsSnapshot(snap: DocsSpecSnapshot): void {
+  try {
+    fs.mkdirSync(path.dirname(docsSnapshotPath()), { recursive: true });
+    fs.writeFileSync(docsSnapshotPath(), JSON.stringify(snap, null, 2) + "\n");
+  } catch {
+    /* cache dir unwritable — the check still runs, just re-checks next time */
+  }
+}
+
+/** The lemonade server version THIS BUILD of the extension was verified
+ *  against (the README behavior reference). A constant in the code, not
+ *  config: it is a property of the build — updated with each extension
+ *  release after re-verification — never a user preference to move. The
+ *  server's own version is probed live from /v1/health; this is the peg. */
+const EXTENSION_CONFIRMED_SERVER_VERSION = "11.7.0";
+
+/** This extension's own version, from package.json (kept beside the
+ *  provider.apiVerifiedAgainst record — see the README versioning
+ *  section; both bump together on release). */
+const PKG_VERSION = (() => {
+  try {
+    return (
+      (JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "package.json"), "utf8")) as {
+        version?: string;
+      }).version ?? "0.0.0"
+    );
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+/** Compare dotted numeric versions: >0 if a is newer than b, <0 if older,
+ *  null when either side isn't dotted-numeric (no direction, just "differs"). Pure. */
+function versionCompare(a: string, b: string): number | null {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  if (pa.some(Number.isNaN) || pb.some(Number.isNaN)) return null;
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d) return d;
+  }
+  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
+ *  (fix: extension update); "behind" = older (fix: update the server). */
+interface ServerVersionMismatch {
+  instance: string;
+  server: string;
+  confirmed: string;
+  direction: "ahead" | "behind" | "unknown";
+}
+
+const serverVersionMismatches: ServerVersionMismatch[] = [];
+
+/** Live server versions seen at the last registration/refresh (instance →
+ *  version), reused by the low-tier upstream notice without extra probes. */
+const serverVersionsSeen = new Map<string, string>();
+
+function recordServerVersion(config: LemonadeConfig, instance: string, version: string | undefined): void {
+  const i = serverVersionMismatches.findIndex((m) => m.instance === instance);
+  const cmp = version ? versionCompare(version, EXTENSION_CONFIRMED_SERVER_VERSION) : null;
+  const mismatched = config.serverVersionCheck && !!version && version !== EXTENSION_CONFIRMED_SERVER_VERSION;
+  if (version) serverVersionsSeen.set(instance, version);
+  else serverVersionsSeen.delete(instance);
+  if (mismatched && version) {
+    const entry: ServerVersionMismatch = {
+      instance,
+      server: version,
+      confirmed: EXTENSION_CONFIRMED_SERVER_VERSION,
+      direction: cmp !== null ? (cmp > 0 ? "ahead" : "behind") : "unknown",
+    };
+    if (i >= 0) serverVersionMismatches[i] = entry;
+    else serverVersionMismatches.push(entry);
+  } else if (i >= 0) {
+    serverVersionMismatches.splice(i, 1); // back on the verified version — clear the warning
+  }
+}
+
+/** One live docs comparison: per-file local blob SHA vs upstream blob SHA. Network. */
+async function performDocsLiveCheck(
+  timeoutMs: number
+): Promise<{ verdict: "current" | "changed"; changed: string[] } | { verdict: "unknown"; error: string }> {
+  const changed: string[] = [];
+  let reached = false;
+  let lastError = "GitHub unreachable";
+  await Promise.all(
+    DOCS_FILES.map(async (file) => {
+      try {
+        const localSha = gitBlobSha(fs.readFileSync(extensionDocsPath(file)));
+        const res = await fetch(DOCS_GH_CONTENTS(file), {
+          headers: { Accept: "application/vnd.github+json", "User-Agent": "pi-lemonade-link" },
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok) {
+          lastError = `GitHub API HTTP ${res.status} (${file})`;
+          return;
+        }
+        reached = true;
+        const sha = ((await res.json()) as { sha?: string }).sha;
+        if (typeof sha === "string" && sha && sha !== localSha) changed.push(file);
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : String(error);
+        /* one file unreachable → not drift; the reached-gate below stays */
+      }
+    })
+  );
+  if (!reached) return { verdict: "unknown", error: lastError };
+  return changed.length ? { verdict: "changed", changed } : { verdict: "current", changed: [] };
+}
+
+/** Re-sync the docs/ snapshot from upstream: download the current markdown
+ *  into docs/ and record a "current" verdict (true by construction). This
+ *  refreshes the GROUND TRUTH ONLY — the extension code itself is unchanged
+ *  and may still need an update; the caller's messaging must say so. */
+async function resyncLemonadeDocs(timeoutMs: number): Promise<{ ok: boolean; error?: string }> {
+  try {
+    await Promise.all(
+      DOCS_FILES.map(async (file) => {
+        const res = await fetch(DOCS_RAW(file), { signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok) throw new Error(`HTTP ${res.status} (${file})`);
+        const body = Buffer.from(await res.arrayBuffer());
+        fs.mkdirSync(path.dirname(extensionDocsPath(file)), { recursive: true });
+        fs.writeFileSync(extensionDocsPath(file), body);
+      })
+    );
+    saveDocsSnapshot({ checkedAt: Date.now(), changed: [] });
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** One throttled docs-freshness pass: a fresh durable verdict serves without
+ *  a network call; a stale/absent one triggers the bounded GitHub probe.
+ *  Drift → the caller-supplied channel. The startup caller passes a no-op
+ *  (docs drift is TUI-only status — see registerSpecDriftWarnings); the
+ *  throttled check still runs so the TUI's Spec & version check view has a
+ *  fresh verdict. */
+async function runDocsSpecCheck(config: LemonadeConfig, notify: (message: string) => void): Promise<void> {
+  if (!config.specCheck) return;
+  let snapshot = loadDocsSnapshot();
+  if (!snapshot || Date.now() - snapshot.checkedAt >= Math.max(0, config.specCheckCooldownMs)) {
+    const result = await performDocsLiveCheck(config.specCheckTimeoutMs);
+    if (result.verdict === "unknown") {
+      // GitHub unreachable: unknown ≠ out of date — never cry wolf. But the
+      // failed pass still engages the cooldown ("at most one network pass
+      // per cooldown") — otherwise offline days re-probe at every session
+      // start — and the last known verdict stands until it expires.
+      console.error(`[pi-lemonade-link] spec check skipped: ${result.error}`);
+      saveDocsSnapshot({ checkedAt: Date.now(), changed: snapshot?.changed ?? [] });
+      return;
+    }
+    snapshot = result.verdict === "changed" ? { checkedAt: Date.now(), changed: result.changed } : { checkedAt: Date.now(), changed: [] };
+    saveDocsSnapshot(snapshot);
+  }
+  if (snapshot.changed.length) {
+    notify(
+      `pi-lemonade-link: ${snapshot.changed.length} Lemonade API doc${snapshot.changed.length > 1 ? "s" : ""} this extension keeps in its docs/ folder changed upstream ` +
+        `(${snapshot.changed.join(", ")}) — the extension may be out of date. ` +
+        `Fix: check for an extension update, or open /lemonade-setup → Spec & version check to re-download the current docs into the extension's ` +
+        `docs/ folder and compare what changed. Runs once a day; specCheck: false disables.`
+    );
+  }
+}
+
+/** Session-start drift signals, in tiers — ordered by what actually matters
+ *  at runtime. Registered once from the extension entry.
+ *
+ *  Tier 1 (warning): extension ↔ server sync — the signal that matters; a
+ *  version mismatch means endpoints may have changed for this pairing.
+ *  Directional (see ServerVersionMismatch).
+ *
+ *  Tier 2 (info, one sentence, separately toggleable): server ↔ latest
+ *  published upstream release — "a server update is available". Much lower
+ *  tier: an older server is not broken, it's just behind.
+ *
+ *  Docs drift: TUI-only status — as long as extension and server agree on
+ *  version, the docs snapshot matching upstream HEAD changes nothing at
+ *  runtime. The throttled check still runs so the Spec & version check view
+ *  has a fresh verdict; it just never warns. */
+function registerSpecDriftWarnings(pi: ExtensionAPI, configRef: { current: LemonadeConfig }): void {
+  pi.on("session_start", async (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    const config = configRef.current;
+
+    // Tier 1 — extension ↔ server sync.
+    for (const m of serverVersionMismatches) {
+      const relation =
+        m.direction === "ahead" ? "newer than" : m.direction === "behind" ? "older than" : "different from";
+      const fix =
+        m.direction === "ahead"
+          ? "check for an extension update — until then, endpoints on that box may differ"
+          : m.direction === "behind"
+            ? `update the lemonade server to v${m.confirmed} or newer, or expect some endpoints to be missing on that box`
+            : "update the server or the extension so both are on the verified pairing";
+      ctx.ui.notify(
+        `pi-lemonade-link: instance "${m.instance}" runs server v${m.server} (${relation} the v${m.confirmed} this extension was verified against) — ${fix}. ` +
+          `Details: /lemonade-setup → Spec & version check. serverVersionCheck: false disables.`,
+        "warning"
+      );
+    }
+
+    // Tier 2 — server vs the latest published upstream release.
+    // Fire-and-forget by design: pi's runner awaits session_start handlers
+    // (and every UI mode awaits that emit), so awaiting the probe here would
+    // stall startup/reload by up to ~specCheckTimeoutMs whenever the durable
+    // verdict is stale. The notice simply arrives when the probe lands.
+    if (config.upstreamVersionCheck) {
+      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) {
+            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}`)
+        );
+    }
+
+    // Docs drift — TUI-only: keep the verdict fresh, never warn. Same
+    // fire-and-forget discipline as Tier 2.
+    if (config.specCheck) {
+      void runDocsSpecCheck(config, () => {});
+    }
+  });
+}
+
 // ─── Provider registration ──────────────────────────────────────────────────
 
 function isChatModel(m: LemonadeModel): boolean {
@@ -701,6 +1109,7 @@ async function registerInstanceProvider(pi: ExtensionAPI, view: InstanceView): P
     ]);
     catalog = catalogRes;
     loaded = new Set((health?.all_models_loaded ?? []).map((m) => m.model_name));
+    recordServerVersion(config, view.name, health?.version);
   } catch {
     // Unreachable => contribute nothing to /model. No placeholders: an
     // unreachable model is not listable. Sessions pinned to a lemonade model
@@ -743,6 +1152,8 @@ const LEGACY_PROVIDER_IDS = ["lemonade", "lemonade-undefined"];
 /** Register (or re-register) every configured instance. Each becomes its own
  *  pi provider under the uniform lemonade-<name> id. */
 async function registerLemonadeProvider(pi: ExtensionAPI, config: LemonadeConfig): Promise<number> {
+  serverVersionMismatches.length = 0; // (re)collected per registration pass
+  serverVersionsSeen.clear();
   for (const staleId of LEGACY_PROVIDER_IDS) {
     try {
       pi.unregisterProvider(staleId);
@@ -2146,6 +2557,12 @@ function formatStatus(
     `Status: ${health.status ?? "?"}   Lemonade v${health.version ?? "?"}   Telemetry: ${telemetry}` +
       (updated ? `   · updated ${updated.toTimeString().slice(0, 8)}` : ""),
     `Endpoint: ${config.baseUrl}   WebSocket port: ${health.websocket_port ?? "?"}`,
+    `This extension: v${PKG_VERSION}, verified against lemonade v${EXTENSION_CONFIRMED_SERVER_VERSION}   ·   docs snapshot: ${
+      (() => {
+        const s = loadDocsSnapshot();
+        return !s ? "not checked yet" : s.changed.length ? `${s.changed.length} file(s) changed upstream` : "up to date";
+      })()
+    }`,
     ""
   );
 
@@ -2583,11 +3000,157 @@ function registerSetupCommand(pi: ExtensionAPI, configRef: { current: LemonadeCo
           { value: "models", label: "Model management", description: `List, load, unload, pull (progress+cancel), delete, change-ctx, HF install, filter, refresh — active instance: ${activeInstance}` },
           { value: "transcription", label: "Transcription settings", description: "Whisper model, paths, smoke test" },
           { value: "logs", label: "Live server logs", description: "Stream the server's log over websocket" },
+          { value: "spec", label: "Spec & version check", description: "Docs drift + live server-version drift — status, re-check, re-sync, toggles" },
           { value: "instance", label: "Switch instance", description: `Current: ${activeInstance} — pick which box status/models/logs act on` },
           { value: "exit", label: "Exit", description: "Close the setup menu" },
         ]);
         if (choice === null || choice === "exit") break;
 
+        // ── Spec & version check ───────────────────────────────────────
+        if (choice === "spec") {
+          for (;;) {
+            const config = configRef.current;
+            const docsSnap = loadDocsSnapshot();
+            const docsState = !config.specCheck
+              ? "disabled (specCheck: false)"
+              : docsSnap
+                ? docsSnap.changed.length
+                  ? `CHANGED — ${docsSnap.changed.join(", ")}`
+                  : "up to date"
+                : "no verdict yet this cooldown window";
+            const serversState = !config.serverVersionCheck
+              ? "sync check disabled (serverVersionCheck: false)"
+              : serverVersionMismatches.length
+                ? `${serverVersionMismatches.length} instance(s) at an unverified server version`
+                : `all instances on v${EXTENSION_CONFIRMED_SERVER_VERSION} (the build this extension was verified against)`;
+            const upstreamSnap = loadUpstreamSnapshot();
+            const upstreamState = !config.upstreamVersionCheck
+              ? "notice disabled (upstreamVersionCheck: false)"
+              : upstreamSnap
+                ? [...serverVersionsSeen.values()].some((v) => {
+                    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 (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", [
+              { value: "status", label: "Status", description: `Docs: ${docsState} · Servers: ${serversState} · Upstream: ${upstreamState}` },
+              { value: "recheck", label: "Re-check docs now", description: "Compare the docs/ snapshot with upstream lemonade-sdk/lemonade by git blob SHA" },
+              { 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, once per release` },
+              { value: "back", label: "Back", description: "" },
+            ]);
+            if (sub === null || sub === "back") break;
+
+            if (sub === "status") {
+              ctx.ui.setStatus("lemonade-setup", "Probing instances…");
+              const instanceLines: string[] = [];
+              for (const v of listInstances(config)) {
+                const h = await fetchHealth(v.config);
+                const drift =
+                  h?.version && h.version !== EXTENSION_CONFIRMED_SERVER_VERSION
+                    ? ` — VERSION DRIFT (extension verified against v${EXTENSION_CONFIRMED_SERVER_VERSION})`
+                    : "";
+                instanceLines.push(
+                  `  ${v.name}${v.isDefault ? " (default)" : ""} — ${h?.version ? `server v${h.version}` : "unreachable"}${drift}`
+                );
+              }
+              ctx.ui.setStatus("lemonade-setup", undefined);
+              await textView(
+                ctx,
+                "Spec & Version Check — Status",
+                [
+                  "Docs (vs upstream lemonade-sdk/lemonade docs/api, by git blob SHA):",
+                  `  ${docsState}`,
+                  "",
+                  "Live server versions (vs the build this extension was verified against):",
+                  ...instanceLines,
+                  `  verified build: v${EXTENSION_CONFIRMED_SERVER_VERSION} (recorded in the extension code — not a setting)`,
+                  "",
+                  `Latest published upstream release (probed via GitHub, ${config.upstreamVersionCheck ? "notice on" : "notice off"}):`,
+                  `  latest: v${upstreamSnap?.latest ?? "(unknown — not probed or unreachable)"}`,
+                  ...[...serverVersionsSeen].map(([name, v]) => {
+                    const latest = upstreamSnap?.latest;
+                    const cmp = latest ? versionCompare(v, latest) : null;
+                    const rel =
+                      cmp === null
+                        ? ""
+                        : cmp < 0
+                          ? " — behind (a server update is available)"
+                          : cmp > 0
+                            ? " — ahead of the latest stable release"
+                            : " — current";
+                    return `  ${name}: v${v}${rel}`;
+                  }),
+                  "",
+                  "Docs drift is TUI-only status on purpose: as long as the extension and the",
+                  "server agree on version, the docs snapshot matching upstream HEAD changes",
+                  "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, deduplicated: it fires",
+                  "once per new release per instance — this view always shows the current",
+                  "state, even when the notice has already fired).",
+                ],
+                true
+              );
+            } else if (sub === "recheck") {
+              ctx.ui.setStatus("lemonade-setup", "Checking upstream docs…");
+              const result = await performDocsLiveCheck(config.specCheckTimeoutMs);
+              ctx.ui.setStatus("lemonade-setup", undefined);
+              if (result.verdict === "unknown") {
+                ctx.ui.notify(`Docs check failed: ${result.error}`, "error");
+                continue;
+              }
+              saveDocsSnapshot({ checkedAt: Date.now(), changed: result.changed });
+              ctx.ui.notify(
+                result.verdict === "current"
+                  ? "Docs snapshot is up to date with upstream."
+                  : `Docs differ from upstream (${result.changed.join(", ")}) — the extension may be out of date. Update the extension if one is available, or re-sync the docs for review.`,
+                result.verdict === "current" ? "info" : "warning"
+              );
+            } else if (sub === "resync") {
+              const ok = await ctx.ui.confirm(
+                "Re-sync docs/ from upstream?",
+                "Downloads the current docs/api markdown into docs/. This refreshes the ground truth ONLY — the extension code is unchanged and may still need an update."
+              );
+              if (!ok) continue;
+              ctx.ui.setStatus("lemonade-setup", "Downloading upstream docs…");
+              const result = await resyncLemonadeDocs(config.specCheckTimeoutMs);
+              ctx.ui.setStatus("lemonade-setup", undefined);
+              ctx.ui.notify(
+                result.ok
+                  ? "Docs re-synced from upstream. The extension code itself has NOT changed — re-verify it against the new docs or update the extension when available."
+                  : `Re-sync failed: ${result.error}`,
+                result.ok ? "info" : "error"
+              );
+            } else if (sub === "toggledocs") {
+              config.specCheck = !config.specCheck;
+              saveConfig(config);
+              ctx.ui.notify(`Docs spec check ${config.specCheck ? "enabled" : "disabled"}.`, "info");
+            } else if (sub === "toggleupstream") {
+              config.upstreamVersionCheck = !config.upstreamVersionCheck;
+              saveConfig(config);
+              ctx.ui.notify(
+                `Upstream-release notice ${config.upstreamVersionCheck ? "enabled" : "disabled"}.`,
+                "info"
+              );
+            } else if (sub === "toggleserver") {
+              config.serverVersionCheck = !config.serverVersionCheck;
+              saveConfig(config);
+              ctx.ui.notify(`Server-version check ${config.serverVersionCheck ? "enabled" : "disabled"}.`, "info");
+              const [, msg] = await withStatus(ctx, "Re-registering providers…", () =>
+                registerLemonadeProvider(pi, config).then((n) => `${n} model(s) registered.`)
+              );
+              void msg;
+            }
+          }
+          continue;
+        }
+
         // ── Switch instance ─────────────────────────────────────────────
         if (choice === "instance") {
           const picked = await menu(
@@ -3228,6 +3791,7 @@ export default async function piLemonadeLink(pi: ExtensionAPI): Promise<void> {
   await registerAgentTools(pi, configRef.current);
   registerLemonadeBar(pi, configRef);
   registerSetupCommand(pi, configRef);
+  registerSpecDriftWarnings(pi, configRef);
 
   // Fresh install (or a hand-emptied config): nothing is registered yet —
   // point the user at the wizard instead of leaving them wondering why

package/lemonade.example.json

@@ -81,5 +81,29 @@
   // How often (ms) the bar polls the active instance for busy/queue +
   // CPU/GPU/NPU/VRAM. 0 = local metrics only (instance name, tok/s,
   // cache-hit %).
-  "barPollMs": 5000
+  "barPollMs": 5000,
+
+  // Docs-freshness check: compare the docs/ snapshot against upstream
+  // lemonade-sdk/lemonade by git blob SHA. TUI-only status (shown in
+  // /lemonade-setup → Spec & version check, with re-check/re-sync) — NO
+  // startup warning: extension ↔ server version agreement is what matters
+  // at runtime, and that has its own checks below.
+  "specCheck": true,
+  "specCheckCooldownMs": 86400000,
+  "specCheckTimeoutMs": 5000,
+
+  // Tier 1 (startup warning): /v1/health self-reports the server version.
+  // If an instance advertises a version other than the build this extension
+  // was verified against (a constant in the extension's code — see the
+  // README "Keeping the specs honest" section), a directional warning fires
+  // on startup: server newer → check for an extension update; server older →
+  // update the server.
+  "serverVersionCheck": true,
+
+  // 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 — 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.0",
+  "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",
@@ -20,5 +20,10 @@
   },
   "pi": {
     "extensions": ["./index.ts"]
+  },
+  "provider": {
+    "name": "lemonade",
+    "apiVerifiedAgainst": "11.7.0",
+    "specSnapshot": "docs/ from lemonade-sdk/lemonade docs/api, snapshotted 2026-09-12"
   }
 }