@llamaventures/cli 1.20.0 → 1.22.0

package/AGENT_BRIEFING.md

@@ -8,6 +8,7 @@ You are not just an AI assistant. You're an **extension of a team member** — w
 
 - **Your access scope is whatever your token allows.** Run `llama auth status` first; the response shows your role, identity, and active token source.
 - **All your writes are logged.** `auth_events` and `deal_events` capture everything. Pipeline data can always be traced back to who/what changed it.
+- **Never cue by implication.** A teammate cue creates an LC inbox item and may queue email under the user's identity. Cue a specific person only when the user explicitly authorized it in the current request. Referring to a teammate, ownership, responsibility, or writing their name is not permission.
 - **Public surfaces stay clean.** Anything that leaves the workspace — public repos, npm packages, external artifacts, shared links — must not leak internal people, deals, private URLs, or workflow nuance.
 - **Be direct, terse, action-oriented.** Save your words for the genuine judgment calls.
 - **Critical when thinking, helpful when executing.** Push back on weak logic, then ship the work cleanly.
@@ -133,7 +134,7 @@ These three look similar but land in different surfaces. Don't infer from the co
 |---|---|---|
 | File a **source packet** with multiple facts and/or one note | `llama deal ingest <dealId> --file packet.json` | Facts + optional note → deal **Feed**, atomically and retry-safe |
 | Record a **sourced, verifiable fact** | `llama deal fact add <dealId> --category <cat> --claim "…" --source "deck p3" --source-url <url>` | Facts → deal **Feed** (FACT card) + citable in the **Memo** |
-| Leave a **comment / opinion / question / reaction** for the team | `llama post <dealId> "…"` (`@name` to notify) | Posts → deal **Feed** (POST card); `@mention` fires email + UI badge |
+| Leave a **comment / opinion / question / reaction** for the team | `llama post <dealId> "…"`; add `--cue` only after explicit permission | Posts → deal **Feed** (POST card); authorized cues create email + UI badge |
 | Write **narrative that belongs in the IC memo** | `llama brief add-text <dealId> --heading "…" --body "…"` | Brief blocks → **Memo tab only — NOT in the Feed** |
 
 ⚠️ The trap: `brief add-text` is **not** visible in the Activity Feed. If the team should see it in the feed, use `llama post`. If it's a claim that needs a source + verification, use `llama deal fact add`. (It's `deal fact add`, not `fact-add`.)
@@ -149,7 +150,7 @@ The table below details the exact CLI for each destination.
 | Insights, decisions, framework improvements | Wiki (markdown) | `llama wiki save <slug> --content "..."` (with attribution — see below) |
 | **HTML wiki entry — standalone HTML page hosted at `/wiki/<slug>`** (sector landscape, market map, dashboard, hand-styled thesis page) | **Wiki (HTML)** | `llama wiki save <slug> --title "..." --file <path.html> --sources "..."`. Auto-detects content_type=html from extension. Public page is full-viewport sandboxed iframe takeover (no wiki chrome). Sources/status/title still required; appears in `wiki search` + backlinks. Use when the user says "deploy this HTML to wiki", "wiki 词条", "make this page a wiki entry". HTML must be self-contained (inline CSS/JS, image data URIs or external URLs) — asset bundles aren't supported on wiki yet. **Native comments + working in-page (#) anchor links are injected automatically** — readers discuss inline and the table of contents scrolls; you don't wire anything up (pages that already embed the comment widget are left as-is). |
 | Large files (deck / PDF / transcript) | Drive deal folder | the deal's `folder_url` (from `llama deal show`) → upload via your filesystem / Drive tool |
-| Cross-team mentions | Inbox + email | `llama post <dealId> "@<teammate> ..."` — server fires email + UI badge to the recipient |
+| Cross-team cues | Inbox + email | `llama post <dealId> "@<teammate> ..." --cue` — use `--cue` only after the user explicitly authorized that recipient |
 
 ### Attribution format (required for wiki writes)
 
@@ -167,8 +168,9 @@ Content. One block, one attribution. Don't mix fact and opinion in a single bloc
 | Level | Type | Behaviour |
 |---|---|---|
 | **L0** | Reads (`search`, `show`, `list`) | Just do it. Don't announce. Integrate the result into your reply. |
-| **L1** | Low-risk writes (timeline post, wiki append, add fact, add tag) | Do it, then tell the user **one line** afterward. |
+| **L1** | Low-risk writes (cue-free timeline post, wiki append, add fact, add tag) | Do it, then tell the user **one line** afterward. |
 | **L2** | Medium-risk writes (new deal, change stage, change owner, new wiki page) | Ask once: "Y/n — I'm about to do X". On yes, execute and report. Don't re-ask details. |
+| **L2-cue** | Any assistant-authored write that resolves to a teammate cue | Require explicit permission for the resolved people and inbox/email channels. Retry the exact write with `--cue` only after yes. If the user already explicitly asked to cue them, do not ask twice. |
 | **L3** | High-risk (delete deal, bulk change, overwrite someone else's wiki, force-push, regulatory-relevant) | Detailed explanation + explicit confirmation. Provide a dry-run / undo path when possible. |
 
 When in doubt, lean to a higher level (more confirmation), not lower.
@@ -290,7 +292,8 @@ llama wiki restore <slug> [--lang en|zh]
 
 # Timeline + posts
 llama timeline <dealId>
-llama post <dealId> "message"
+llama post <dealId> "message"             # cue-free note
+llama post <dealId> "@name respond" --cue # only after explicit user approval
 
 # Mentions inbox
 llama mentions

package/CHANGELOG.md

@@ -6,6 +6,28 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [1.22.0] - 2026-07-28
+
+### Added
+- Consume Llama Command's server-owned CLI/MCP compatibility headers on every
+  shared API request. Recommended upgrades are surfaced on stderr at most once
+  per day, including for non-TTY coding agents, while structured stdout remains
+  unchanged.
+- Surface hard `CLI_VERSION_UNSUPPORTED` responses with a stable error code,
+  exact upgrade command, and retry instruction.
+
+## [1.21.0] - 2026-07-24
+
+### Added
+- Add explicit `--cue` (CLI) and `cueAuthorized` (MCP) authorization for
+  teammate cues in posts and brief writes. Cue-free writes remain unchanged;
+  agents must obtain permission for the resolved recipients before setting it.
+
+### Changed
+- Agent onboarding now treats teammate cues as approval-required outbound
+  actions rather than ordinary low-risk timeline posts. Structured
+  `MENTION_APPROVAL_REQUIRED` errors retain recipient and channel context.
+
 ## [1.20.0] - 2026-07-22
 
 ### Added
@@ -544,7 +566,9 @@ assistant-drafted (🤖) and enforces the AI trust ceiling.
 
 ---
 
-[Unreleased]: https://github.com/Llama-Ventures/llama-cli/compare/v1.18.1...HEAD
+[Unreleased]: https://github.com/Llama-Ventures/llama-cli/compare/v1.22.0...HEAD
+[1.22.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.21.0...v1.22.0
+[1.21.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.20.0...v1.21.0
 [1.18.1]: https://github.com/Llama-Ventures/llama-cli/compare/v1.18.0...v1.18.1
 [1.18.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.17.3...v1.18.0
 [1.17.3]: https://github.com/Llama-Ventures/llama-cli/compare/v1.17.2...v1.17.3

package/README.md

@@ -102,6 +102,7 @@ llama deal ingest <dealId> --file packet.json  # atomic multi-fact + optional Fe
 llama deal fact add <dealId> --category funding --claim "Raised a seed round" --source "deck p3" --source-url https://...
 llama deal update <dealId> status Diligence
 llama post <dealId> "note body"
+llama post <dealId> "@name please respond" --cue  # only after explicit approval
 llama brief add-text <dealId> --heading "..." --body "..."
 llama wiki search "<query>"
 llama wiki save <slug> --title "..." --content "..."

package/README.zh-CN.md

@@ -124,6 +124,7 @@ llama deal ingest <dealId> --file packet.json  # 多条 facts + 可选 Feed note
 llama deal fact add <dealId> --category funding --claim "Raised a seed round" --source "deck p3" --source-url https://...
 llama deal update <dealId> status Diligence
 llama post <dealId> "备注内容"
+llama post <dealId> "@name 请回复" --cue  # 仅在用户明确授权后使用
 llama brief add-text <dealId> --heading "..." --body "..."
 llama wiki search "<查询词>"
 llama wiki save <slug> --title "..." --content "..."

package/bin/llama-mcp.mjs

@@ -161,7 +161,7 @@ async function runDealAgentTool({ dealId, message, title = "MCP agent run" }) {
 // full-array PUTs (no POST), so we GET current blocks, prepend the new
 // one (matches UI default since 2026-05-03), and PUT the merged array.
 // Server stamps identity meta on PUT; we don't send any.
-async function addBriefBlock(dealId, block) {
+async function addBriefBlock(dealId, block, cueAuthorized = false) {
   try {
     const id = globalThis.crypto.randomUUID();
     const cur = await request("GET", `/api/deals/${encodeURIComponent(dealId)}/blocks`);
@@ -169,7 +169,7 @@ async function addBriefBlock(dealId, block) {
     const result = await request(
       "PUT",
       `/api/deals/${encodeURIComponent(dealId)}/blocks`,
-      { blocks: [{ id, ...block }, ...existing] }
+      { blocks: [{ id, ...block }, ...existing], cue_authorized: cueAuthorized === true }
     );
     const text = JSON.stringify(
       { ok: result?.ok ?? true, id, count: result?.count ?? existing.length + 1 },
@@ -681,10 +681,13 @@ server.registerTool(
       dealId: z.string(),
       heading: z.string().optional().describe("optional block heading"),
       body: z.string().describe("markdown body"),
+      cueAuthorized: z.boolean().optional().describe(
+        "true only after the user explicitly approved every resolved cue recipient",
+      ),
     },
   },
-  async ({ dealId, heading, body }) =>
-    addBriefBlock(dealId, { type: "text", heading: heading ?? "", body })
+  async ({ dealId, heading, body, cueAuthorized }) =>
+    addBriefBlock(dealId, { type: "text", heading: heading ?? "", body }, cueAuthorized)
 );
 
 server.registerTool(
@@ -696,10 +699,13 @@ server.registerTool(
       dealId: z.string(),
       url: z.string(),
       label: z.string().optional().describe("optional human-readable label"),
+      cueAuthorized: z.boolean().optional().describe(
+        "true only after the user explicitly approved every resolved cue recipient",
+      ),
     },
   },
-  async ({ dealId, url, label }) =>
-    addBriefBlock(dealId, { type: "link", url, label: label ?? "" })
+  async ({ dealId, url, label, cueAuthorized }) =>
+    addBriefBlock(dealId, { type: "link", url, label: label ?? "" }, cueAuthorized)
 );
 
 server.registerTool(
@@ -712,10 +718,13 @@ server.registerTool(
       tone: z.string().describe("insight | warning | info | success"),
       heading: z.string().optional(),
       body: z.string(),
+      cueAuthorized: z.boolean().optional().describe(
+        "true only after the user explicitly approved every resolved cue recipient",
+      ),
     },
   },
-  async ({ dealId, tone, heading, body }) =>
-    addBriefBlock(dealId, { type: "callout", tone, heading: heading ?? "", body })
+  async ({ dealId, tone, heading, body, cueAuthorized }) =>
+    addBriefBlock(dealId, { type: "callout", tone, heading: heading ?? "", body }, cueAuthorized)
 );
 
 server.registerTool(
@@ -738,9 +747,12 @@ server.registerTool(
       locked: z.boolean().optional(),
       hidden: z.boolean().optional(),
       sourceSection: z.string().optional(),
+      cueAuthorized: z.boolean().optional().describe(
+        "true only after the user explicitly approved every resolved cue recipient",
+      ),
     },
   },
-  async ({ dealId, blockId, heading, body, url, label, description, tone, locked, hidden, sourceSection }) => {
+  async ({ dealId, blockId, heading, body, url, label, description, tone, locked, hidden, sourceSection, cueAuthorized }) => {
     const patch = {};
     for (const [k, v] of Object.entries({ heading, body, url, label, description, tone })) {
       if (v !== undefined) patch[k] = v;
@@ -750,6 +762,7 @@ server.registerTool(
     if (hidden !== undefined) meta.hidden = hidden;
     if (sourceSection !== undefined) meta.sourceSection = sourceSection;
     if (Object.keys(meta).length > 0) patch.meta = meta;
+    if (cueAuthorized === true) patch.cue_authorized = true;
     return callApi(
       "PATCH",
       `/api/deals/${encodeURIComponent(dealId)}/blocks/${encodeURIComponent(blockId)}`,
@@ -988,16 +1001,22 @@ server.registerTool(
   "post",
   {
     description:
-      "Post a message to a deal's timeline. Message can include @-mentions " +
-      "(e.g. @<first-name> or @<email@llamaventures.vc>) — the system fires " +
-      "email + inbox notifications to mentioned users.",
+      "Post a message to a deal's timeline. Cue-free posts are autonomous. " +
+      "Explicit or implicit teammate cues create inbox/email notifications and require " +
+      "cueAuthorized=true only after explicit user permission.",
     inputSchema: {
       dealId: z.string(),
       message: z.string(),
+      cueAuthorized: z.boolean().optional().describe(
+        "true only after the user explicitly approved cueing every resolved recipient",
+      ),
     },
   },
-  async ({ dealId, message }) =>
-    callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/posts`, { message })
+  async ({ dealId, message, cueAuthorized }) =>
+    callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/posts`, {
+      message,
+      cue_authorized: cueAuthorized === true,
+    })
 );
 
 // ============================================================

package/bin/llama.mjs

@@ -457,16 +457,17 @@ Approvals (partner queue — self-claim approvals):
 
 Timeline / Posts:
   llama timeline <dealId>                                    # full unified feed
-  llama post <dealId> "message body" [--link url] [--link-name "name"]
+  llama post <dealId> "message body" [--link url] [--link-name "name"] [--cue]
+                                                               # --cue only after explicit user approval
 
 Brief blocks:
   llama brief blocks <dealId>                                  # list current block array
   llama brief block <dealId> <blockId>                         # fetch one block's body (manifest in 'llama deal show')
-  llama brief add-text <dealId> --heading "..." --body "..."
-  llama brief add-link <dealId> --url "..." --label "..." [--description "..."]
-  llama brief add-embed <dealId> --url "..." [--label "..."]
-  llama brief add-callout <dealId> --tone insight|info|warning|success --heading "..." --body "..."
-  llama brief edit <dealId> <blockId> [--heading ...] [--body ...] [--url ...] [--label ...] [--tone ...]
+  llama brief add-text <dealId> --heading "..." --body "..." [--cue]
+  llama brief add-link <dealId> --url "..." --label "..." [--description "..."] [--cue]
+  llama brief add-embed <dealId> --url "..." [--label "..."] [--cue]
+  llama brief add-callout <dealId> --tone insight|info|warning|success --heading "..." --body "..." [--cue]
+  llama brief edit <dealId> <blockId> [--heading ...] [--body ...] [--url ...] [--label ...] [--tone ...] [--cue]
                           [--source-section <key>] [--lock|--unlock] [--hide|--unhide]
   llama brief delete <dealId> <blockId>
   llama brief history <dealId> <blockId> [--limit 50]            # prior versions of this block (newest first)
@@ -1934,7 +1935,7 @@ async function main() {
     const { flags, positional } = parseFlags(rest);
     const body = positional[0];
     if (!dealId || !body) {
-      throw new Error(`Usage: llama post <dealId> "message body" [--link url] [--link-name "name"]`);
+      throw new Error(`Usage: llama post <dealId> "message body" [--link url] [--link-name "name"] [--cue]`);
     }
     const attachments = flags.link
       ? [{ url: String(flags.link), name: flags["link-name"] ? String(flags["link-name"]) : String(flags.link) }]
@@ -1942,7 +1943,7 @@ async function main() {
     print(await request(
       "POST",
       `/api/deals/${encodeURIComponent(dealId)}/posts`,
-      { body, attachments }
+      { body, attachments, cue_authorized: flags.cue === true }
     ));
     return;
   }
@@ -2168,7 +2169,10 @@ Routing — is this the right command?
     if (!cur) cur = await request("GET", `/api/deals/${encodeURIComponent(dealId)}/blocks`);
     const existing = cur.blocks ?? [];
     const next = position === "top" ? [block, ...existing] : [...existing, block];
-    print(await request("PUT", `/api/deals/${encodeURIComponent(dealId)}/blocks`, { blocks: next }));
+    print(await request("PUT", `/api/deals/${encodeURIComponent(dealId)}/blocks`, {
+      blocks: next,
+      cue_authorized: flags.cue === true,
+    }));
     console.log(`Created block ${id}`);
     return;
   }
@@ -2178,7 +2182,7 @@ Routing — is this the right command?
     const dealId = rest[0];
     const blockId = rest[1];
     if (!dealId || !blockId) {
-      throw new Error("Usage: llama brief edit <dealId> <blockId> [--heading ...] [--body ...] [--url ...] [--label ...] [--description ...] [--tone ...] [--source-section ...] [--lock|--unlock] [--hide|--unhide]");
+      throw new Error("Usage: llama brief edit <dealId> <blockId> [--heading ...] [--body ...] [--url ...] [--label ...] [--description ...] [--tone ...] [--source-section ...] [--lock|--unlock] [--hide|--unhide] [--cue]");
     }
     const patch = {};
     for (const k of ["heading", "body", "url", "label", "description", "tone"]) {
@@ -2198,8 +2202,11 @@ Routing — is this the right command?
       metaPatch.sourceSection = String(flags["source-section"]);
     }
     if (Object.keys(metaPatch).length > 0) patch.meta = metaPatch;
+    if (flags.cue === true) patch.cue_authorized = true;
 
-    if (Object.keys(patch).length === 0) throw new Error("at least one field flag required");
+    if (Object.keys(patch).length === 0 || (Object.keys(patch).length === 1 && patch.cue_authorized === true)) {
+      throw new Error("at least one field flag required");
+    }
     print(await request("PATCH", `/api/deals/${encodeURIComponent(dealId)}/blocks/${encodeURIComponent(blockId)}`, patch));
     return;
   }

package/contracts/core-api.json

@@ -1,9 +1,9 @@
 {
   "format": "llama.core-api-contract.v1",
   "name": "llama-core-api",
-  "apiVersion": "3.1.0",
+  "apiVersion": "3.5.0",
   "openapiVersion": "3.0.3",
-  "sha256": "51b134af7a63534406b3a216aeab190fd595f5270b2a10263730662f1c2f771a",
-  "pathCount": 212,
-  "operationCount": 275
+  "sha256": "31c7d23ee06bd4282aa2451698604cc30df4792d4a0e9674593a809b4eb55767",
+  "pathCount": 216,
+  "operationCount": 281
 }

package/lib/build-manifest.json

@@ -1,15 +1,15 @@
 {
   "format": "llama.cli-build.v1",
   "packageName": "@llamaventures/cli",
-  "packageVersion": "1.20.0",
-  "sourceSha": "c9708c7ae6881e9e4a82972a521e748932a380ce",
+  "packageVersion": "1.22.0",
+  "sourceSha": "3e3ede496804de031650e23fc29e1a6763c41daf",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {
     "format": "llama.core-api-contract.v1",
     "name": "llama-core-api",
-    "apiVersion": "3.1.0",
+    "apiVersion": "3.5.0",
     "openapiVersion": "3.0.3",
-    "sha256": "51b134af7a63534406b3a216aeab190fd595f5270b2a10263730662f1c2f771a"
+    "sha256": "31c7d23ee06bd4282aa2451698604cc30df4792d4a0e9674593a809b4eb55767"
   }
 }

package/lib/client.mjs

@@ -15,6 +15,7 @@ import { execFile as _execFile } from "child_process";
 import { promisify } from "util";
 import { createHash, randomUUID } from "crypto";
 import { getBuildInfo } from "./build-info.mjs";
+import { maybeNudgeServerCompatibility } from "./server-compatibility.mjs";
 
 const execFile = promisify(_execFile);
 
@@ -523,6 +524,48 @@ export async function requestSse(method, endpoint, body, opts = {}) {
   return requestSseWithRetry(method, endpoint, body, opts, /* allowRetry */ true);
 }
 
+function apiResponseError(data, status) {
+  const message =
+    typeof data === "object" && data?.error ? data.error : `HTTP ${status}`;
+  if (data?.code === "CLI_VERSION_UNSUPPORTED") {
+    const recovery = data?.recovery?.command || "npm i -g @llamaventures/cli@latest";
+    const error = new Error(
+      `Error[CLI_VERSION_UNSUPPORTED]: ${message}\n` +
+      `Recovery: ${recovery}\n` +
+      "Retry the original Llama command after upgrading.",
+    );
+    error.code = data.code;
+    error.details = data;
+    return error;
+  }
+  if (data?.code !== "MENTION_APPROVAL_REQUIRED") {
+    const error = new Error(message);
+    if (typeof data?.code === "string") error.code = data.code;
+    error.details = data;
+    return error;
+  }
+  const recipients = Array.isArray(data?.cue?.recipients)
+    ? data.cue.recipients
+        .map((recipient) => {
+          const name = recipient?.name || `user ${recipient?.user_id ?? "unknown"}`;
+          return recipient?.intent ? `${name} (${recipient.intent})` : name;
+        })
+        .join(", ")
+    : "unknown";
+  const channels = Array.isArray(data?.cue?.channels)
+    ? data.cue.channels.join(" + ")
+    : "inbox + email";
+  const error = new Error(
+    `Error[MENTION_APPROVAL_REQUIRED]: ${message}\n` +
+    `Recipients: ${recipients}\n` +
+    `Channels: ${channels}\n` +
+    "Ask the user for explicit permission, then retry the exact write with --cue (CLI) or cueAuthorized=true (MCP).",
+  );
+  error.code = data.code;
+  error.details = data;
+  return error;
+}
+
 async function requestWithRetry(method, endpoint, body, opts, allowRetry) {
   const authHeaders = await getAuthHeaders();
   if (Object.keys(authHeaders).length === 0) throw noAuthError();
@@ -538,6 +581,7 @@ async function requestWithRetry(method, endpoint, body, opts, allowRetry) {
     },
     body: body === undefined ? undefined : JSON.stringify(body),
   });
+  maybeNudgeServerCompatibility(res.headers);
 
   // 401 + we sent an OAuth Bearer + this is the first attempt → try a
   // forced refresh once. Covers two cases: (a) clock skew between client
@@ -582,7 +626,7 @@ async function requestWithRetry(method, endpoint, body, opts, allowRetry) {
       data: null,
       errorMessage: message,
     });
-    throw new Error(message);
+    throw apiResponseError(data, res.status);
   }
   await recordClientTelemetry({
     authHeaders,
@@ -613,6 +657,7 @@ async function requestSseWithRetry(method, endpoint, body, opts, allowRetry) {
     },
     body: body === undefined ? undefined : JSON.stringify(body),
   });
+  maybeNudgeServerCompatibility(res.headers);
 
   if (res.status === 401 && allowRetry && (await bearerCameFromOAuth())) {
     let refreshed = null;
@@ -651,7 +696,7 @@ async function requestSseWithRetry(method, endpoint, body, opts, allowRetry) {
       data: null,
       errorMessage: message,
     });
-    throw new Error(message);
+    throw apiResponseError(data, res.status);
   }
 
   const reader = res.body?.getReader();

package/lib/server-compatibility.mjs

@@ -0,0 +1,96 @@
+// Consume the compatibility policy returned by Llama Command.
+//
+// Unlike the npm-registry nudge, this path is intentionally NOT TTY-gated:
+// coding agents and MCP hosts need to see the server's recommendation too.
+// It remains safe for scripts because it writes only to stderr and shares the
+// existing once-per-day update stamp with lib/version-check.mjs.
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { createRequire } from "module";
+
+const DEFAULT_STAMP_FILE = path.join(os.homedir(), ".llama", ".update-check");
+const THROTTLE_MS = 24 * 60 * 60 * 1000;
+
+function installedVersion() {
+  try {
+    const requireFromHere = createRequire(import.meta.url);
+    return String(requireFromHere("../package.json").version || "unknown");
+  } catch {
+    return "unknown";
+  }
+}
+
+function readHeader(headers, name) {
+  if (typeof headers?.get === "function") return headers.get(name);
+  if (!headers || typeof headers !== "object") return null;
+  const match = Object.entries(headers).find(
+    ([key]) => key.toLowerCase() === name.toLowerCase(),
+  );
+  return match ? String(match[1]) : null;
+}
+
+export function parseServerCompatibility(headers) {
+  const status = readHeader(headers, "x-llama-cli-status");
+  if (!["ok", "stale", "unsupported", "unknown"].includes(status)) return null;
+  return {
+    status,
+    recommendedVersion: readHeader(headers, "x-llama-cli-recommended-version"),
+    minimumVersion: readHeader(headers, "x-llama-cli-minimum-version"),
+    upgradeCommand:
+      readHeader(headers, "x-llama-cli-upgrade-command") ||
+      "npm i -g @llamaventures/cli@latest",
+  };
+}
+
+function checkedRecently(stampFile, now) {
+  try {
+    const last = Number.parseInt(fs.readFileSync(stampFile, "utf8").trim(), 10);
+    return Number.isFinite(last) && now - last < THROTTLE_MS;
+  } catch {
+    return false;
+  }
+}
+
+function touchStamp(stampFile, now) {
+  try {
+    fs.mkdirSync(path.dirname(stampFile), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(stampFile, `${now}\n`, { mode: 0o600 });
+  } catch {
+    // Best-effort only. Compatibility hints must never break a command.
+  }
+}
+
+export function formatServerCompatibilityNudge(policy, currentVersion = installedVersion()) {
+  if (policy?.status !== "stale" || !policy.recommendedVersion) return null;
+  return (
+    `warning[CLI_UPDATE_RECOMMENDED]: Llama Command recommends ` +
+    `@llamaventures/cli ${policy.recommendedVersion}; this client is ${currentVersion}. ` +
+    `Upgrade: ${policy.upgradeCommand}`
+  );
+}
+
+export function maybeNudgeServerCompatibility(headers, options = {}) {
+  try {
+    const env = options.env ?? process.env;
+    if (env.LLAMA_NO_UPDATE_CHECK) return false;
+    const policy = parseServerCompatibility(headers);
+    const nudge = formatServerCompatibilityNudge(
+      policy,
+      options.currentVersion ?? installedVersion(),
+    );
+    if (!nudge) return false;
+    const now = options.now ?? Date.now();
+    const stampFile = options.stampFile ?? DEFAULT_STAMP_FILE;
+    if (checkedRecently(stampFile, now)) return false;
+    touchStamp(stampFile, now);
+    const write = options.write ?? ((line) => process.stderr.write(`${line}\n`));
+    write(nudge);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export const SERVER_COMPATIBILITY_STAMP_FILE = DEFAULT_STAMP_FILE;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@llamaventures/cli",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "scripts": {
     "test": "npm run test:agent-routing && npm run test:contract",
     "test:agent-routing": "node scripts/verify-agent-routing.mjs",
-    "test:contract": "node --test scripts/build-manifest.test.mjs scripts/core-api-call-sites.test.mjs scripts/verify-core-api-contract.test.mjs && node scripts/verify-core-api-contract.mjs",
+    "test:contract": "node --test scripts/build-manifest.test.mjs scripts/core-api-call-sites.test.mjs scripts/server-compatibility.test.mjs scripts/verify-core-api-contract.test.mjs && node scripts/verify-core-api-contract.mjs",
     "verify:artifact": "node scripts/verify-release-artifact.mjs",
     "verify:release": "npm test && npm run verify:artifact && node scripts/verify-tarball-clean.mjs",
     "prepack": "node scripts/prepare-build-manifest.mjs",