orionfold-relay 0.21.0 → 0.22.0

package/dist/cli.js

@@ -1186,7 +1186,7 @@ var CURRENT_PLUGIN_API_VERSION, CAPABILITY_VALUES, ORIGIN_VALUES, PrimitivesBund
 var init_types = __esm({
   "src/lib/plugins/sdk/types.ts"() {
     "use strict";
-    CURRENT_PLUGIN_API_VERSION = "0.21";
+    CURRENT_PLUGIN_API_VERSION = "0.22";
     CAPABILITY_VALUES = ["fs", "net", "child_process", "env"];
     ORIGIN_VALUES = ["ainative-internal", "third-party"];
     PrimitivesBundleManifestSchema = z.object({
@@ -1232,16 +1232,16 @@ function computeHash(content) {
 function safePreview(content) {
   return content.slice(0, MAX_PREVIEW_CHARS).trim();
 }
-function safeStat(path23) {
+function safeStat(path24) {
   try {
-    return statSync2(path23);
+    return statSync2(path24);
   } catch {
     return null;
   }
 }
-function safeReadFile(path23) {
+function safeReadFile(path24) {
   try {
-    return readFileSync4(path23, "utf-8");
+    return readFileSync4(path24, "utf-8");
   } catch {
     return null;
   }
@@ -3744,6 +3744,13 @@ var init_format = __esm({
       price: z3.string().min(1).optional(),
       /** Get-license CTA target on the locked card. */
       purchaseUrl: z3.url().optional(),
+      /**
+       * Per-version customer-voice recap, version → one line. The single source
+       * for every renewal value-recap surface (`license status`, the 402 update
+       * refusal, the /packs update card, the Website renewal email). Optional —
+       * but paid packs should carry it, or their renewal case argues generically.
+       */
+      changelog: z3.record(z3.string(), z3.string().min(1)).optional(),
       /** Customer slugs seeded via ensureCustomer at install. */
       customers: z3.array(z3.string()).default([])
     }).strict();
@@ -11951,9 +11958,9 @@ function buildPermissionSummary(toolName, input) {
     }
   }
   if (toolName === "Read" || toolName === "Write" || toolName === "Edit" || toolName === "read" || toolName === "write" || toolName === "edit") {
-    const path23 = input.file_path ?? input.path;
-    if (typeof path23 === "string" && path23.trim().length > 0) {
-      return truncate(path23.trim());
+    const path24 = input.file_path ?? input.path;
+    if (typeof path24 === "string" && path24.trim().length > 0) {
+      return truncate(path24.trim());
     }
   }
   if (toolName?.startsWith("mcp__")) {
@@ -11987,9 +11994,9 @@ function getPermissionDetailEntries(toolName, input) {
     }
   }
   if (toolName === "Read" || toolName === "Write" || toolName === "Edit" || toolName === "read" || toolName === "write" || toolName === "edit") {
-    const path23 = input.file_path ?? input.path;
-    if (typeof path23 === "string") {
-      return [{ label: "Path", value: path23 }];
+    const path24 = input.file_path ?? input.path;
+    if (typeof path24 === "string") {
+      return [{ label: "Path", value: path24 }];
     }
   }
   return Object.entries(input).slice(0, 6).map(([key, value]) => ({
@@ -12891,7 +12898,7 @@ var init_registry6 = __esm({
     init_registry5();
     init_installer();
     init_schedule_spec();
-    SUPPORTED_API_VERSIONS = /* @__PURE__ */ new Set([CURRENT_PLUGIN_API_VERSION, "0.20"]);
+    SUPPORTED_API_VERSIONS = /* @__PURE__ */ new Set([CURRENT_PLUGIN_API_VERSION, "0.21"]);
     pluginCache = null;
     lastLoadedPluginIds = /* @__PURE__ */ new Set();
     PluginTableSchema = z16.object({
@@ -12934,8 +12941,8 @@ function pluginTools(_ctx) {
             Promise.resolve().then(() => (init_ainative_paths(), ainative_paths_exports)),
             Promise.resolve().then(() => (init_types(), types_exports))
           ]);
-          const fs22 = await import("fs");
-          const path23 = await import("path");
+          const fs23 = await import("fs");
+          const path24 = await import("path");
           const yaml13 = await import("js-yaml");
           const kind5 = listPlugins2();
           const registrations = await listPluginMcpRegistrations2();
@@ -12952,13 +12959,13 @@ function pluginTools(_ctx) {
               let manifestHash;
               let capabilityAcceptStatus = "pending";
               try {
-                const pluginYamlPath = path23.join(
+                const pluginYamlPath = path24.join(
                   pluginsDir,
                   pluginId,
                   "plugin.yaml"
                 );
-                if (fs22.existsSync(pluginYamlPath)) {
-                  const content = fs22.readFileSync(pluginYamlPath, "utf-8");
+                if (fs23.existsSync(pluginYamlPath)) {
+                  const content = fs23.readFileSync(pluginYamlPath, "utf-8");
                   const rawManifest = yaml13.load(content);
                   if (rawManifest !== null && typeof rawManifest === "object" && !Array.isArray(rawManifest)) {
                     const record = rawManifest;
@@ -12971,7 +12978,7 @@ function pluginTools(_ctx) {
                   try {
                     manifestHash = deriveManifestHash2(content);
                     const parsed = PluginManifestSchema2.safeParse(rawManifest);
-                    const pluginRootDir = path23.join(pluginsDir, pluginId);
+                    const pluginRootDir = path24.join(pluginsDir, pluginId);
                     const check = isCapabilityAccepted2(
                       pluginId,
                       manifestHash,
@@ -19387,13 +19394,13 @@ var init_codex_app_server_client = __esm({
           await syncPluginMcpToCodex2();
         } catch (err2) {
           try {
-            const fs22 = await import("fs");
-            const path23 = await import("path");
+            const fs23 = await import("fs");
+            const path24 = await import("path");
             const { getAinativeLogsDir: getAinativeLogsDir2 } = await Promise.resolve().then(() => (init_ainative_paths(), ainative_paths_exports));
             const dir = getAinativeLogsDir2();
-            fs22.mkdirSync(dir, { recursive: true });
-            fs22.appendFileSync(
-              path23.join(dir, "plugins.log"),
+            fs23.mkdirSync(dir, { recursive: true });
+            fs23.appendFileSync(
+              path24.join(dir, "plugins.log"),
               `${(/* @__PURE__ */ new Date()).toISOString()} codex-sync-failed: ${err2 instanceof Error ? err2.message : String(err2)}
 `
             );
@@ -22985,14 +22992,14 @@ function resolvePostAction(action, row, itemVariable) {
 function substituteRowPath(template, row, itemVariable) {
   const escaped = itemVariable.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const pattern = new RegExp(`\\{\\{\\s*${escaped}\\.([\\w.]+)\\s*\\}\\}`, "g");
-  return template.replace(pattern, (_match, path23) => {
-    const value = readPath(row, path23);
+  return template.replace(pattern, (_match, path24) => {
+    const value = readPath(row, path24);
     if (value === void 0 || value === null) return "";
     return String(value);
   });
 }
-function readPath(obj, path23) {
-  const parts = path23.split(".");
+function readPath(obj, path24) {
+  const parts = path24.split(".");
   let current = obj;
   for (const part of parts) {
     if (current === null || current === void 0) return void 0;
@@ -23179,14 +23186,14 @@ ${resolvedTemplate}`);
   return parts.join("");
 }
 function resolveRowTemplate(template, context) {
-  return template.replace(/\{\{\s*([^}]+)\s*\}\}/g, (_match, path23) => {
-    const value = readContextPath(context, path23.trim());
+  return template.replace(/\{\{\s*([^}]+)\s*\}\}/g, (_match, path24) => {
+    const value = readContextPath(context, path24.trim());
     if (value === void 0 || value === null) return "";
     return typeof value === "string" ? value : JSON.stringify(value);
   });
 }
-function readContextPath(value, path23) {
-  const parts = path23.split(".");
+function readContextPath(value, path24) {
+  const parts = path24.split(".");
   let current = value;
   for (const part of parts) {
     if (current === null || current === void 0) return void 0;
@@ -25674,8 +25681,8 @@ import { execFileSync as execFileSync3 } from "child_process";
 import yaml12 from "js-yaml";
 import semver from "semver";
 function relayCoreVersion() {
-  if (semver.valid("0.21.0")) {
-    return "0.21.0";
+  if (semver.valid("0.22.0")) {
+    return "0.22.0";
   }
   try {
     const root = getAppRoot(import.meta.dirname, 3);
@@ -26014,6 +26021,68 @@ var init_install = __esm({
   }
 });
 
+// src/lib/licensing/recap.ts
+var recap_exports = {};
+__export(recap_exports, {
+  changelogWindow: () => changelogWindow,
+  entitledPackRecaps: () => entitledPackRecaps
+});
+import fs21 from "fs";
+import path22 from "path";
+import semver2 from "semver";
+function changelogWindow(changelog, fromExclusive, toInclusive) {
+  if (!changelog || !toInclusive || !semver2.valid(toInclusive)) return [];
+  const from = fromExclusive && semver2.valid(fromExclusive) ? fromExclusive : null;
+  return Object.entries(changelog).filter(([version]) => semver2.valid(version)).filter(
+    ([version]) => semver2.compare(version, toInclusive) <= 0 && (from === null || semver2.compare(version, from) > 0)
+  ).sort(([a], [b]) => semver2.compare(a, b)).map(([version, note]) => ({ version, note }));
+}
+function entitledPackRecaps(entitlements, opts2 = {}) {
+  try {
+    const appsDir = opts2.appsDir ?? getAinativeAppsDir();
+    const covered = new Set(entitlements);
+    const out = [];
+    for (const tpl of listPackTemplates({ templatesDir: opts2.templatesDir })) {
+      if (tpl.error || !tpl.meta?.entitlement) continue;
+      if (!covered.has(tpl.meta.entitlement)) continue;
+      if (!fs21.existsSync(path22.join(appsDir, tpl.id))) continue;
+      const avail = packUpdateAvailability(tpl.id, {
+        appsDir,
+        templatesDir: opts2.templatesDir
+      });
+      const state = readInstallState(appsDir, tpl.id);
+      const changelog = tpl.meta.changelog;
+      out.push({
+        packId: tpl.id,
+        packName: tpl.meta.name,
+        installedVersion: avail.installedVersion,
+        ...state?.installedAt ? { installedAt: state.installedAt } : {},
+        availableVersion: avail.availableVersion,
+        updateAvailable: avail.updateAvailable,
+        ...avail.installedVersion && changelog?.[avail.installedVersion] ? { received: changelog[avail.installedVersion] } : {},
+        pending: avail.updateAvailable ? changelogWindow(
+          changelog,
+          avail.installedVersion,
+          avail.availableVersion
+        ) : [],
+        ...tpl.meta.purchaseUrl ? { purchaseUrl: tpl.meta.purchaseUrl } : {}
+      });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+var init_recap = __esm({
+  "src/lib/licensing/recap.ts"() {
+    "use strict";
+    init_ainative_paths();
+    init_catalog();
+    init_update();
+    init_install_state();
+  }
+});
+
 // src/lib/packs/update.ts
 var update_exports = {};
 __export(update_exports, {
@@ -26021,15 +26090,15 @@ __export(update_exports, {
   packUpdateAvailability: () => packUpdateAvailability,
   updatePack: () => updatePack
 });
-import fs21 from "fs";
-import path22 from "path";
-import semver2 from "semver";
+import fs22 from "fs";
+import path23 from "path";
+import semver3 from "semver";
 function packUpdateAvailability(appId, opts2 = {}) {
   const appsDir = opts2.appsDir ?? getAinativeAppsDir();
   const installedVersion = readInstallState(appsDir, appId)?.packVersion ?? null;
   const template = findPackTemplate(appId, { templatesDir: opts2.templatesDir });
   const availableVersion = template?.meta?.version ?? null;
-  const updateAvailable = availableVersion !== null && semver2.valid(availableVersion) !== null && (installedVersion === null || semver2.valid(installedVersion) === null || semver2.compare(availableVersion, installedVersion) > 0);
+  const updateAvailable = availableVersion !== null && semver3.valid(availableVersion) !== null && (installedVersion === null || semver3.valid(installedVersion) === null || semver3.compare(availableVersion, installedVersion) > 0);
   return { installedVersion, availableVersion, updateAvailable };
 }
 async function updatePack(id, options = {}) {
@@ -26057,13 +26126,13 @@ async function updatePack(id, options = {}) {
       );
     }
     const coreVersion = options.coreVersion ?? relayCoreVersion();
-    if (pack.meta.relayCore && !semver2.satisfies(coreVersion, pack.meta.relayCore)) {
+    if (pack.meta.relayCore && !semver3.satisfies(coreVersion, pack.meta.relayCore)) {
       throw new PackValidationError(
         `Pack ${pack.meta.id}@${pack.meta.version} requires relay-core ${pack.meta.relayCore}, but this install is ${coreVersion}.`
       );
     }
     const newVersion = pack.meta.version;
-    if (previousVersion !== null && semver2.valid(previousVersion) && semver2.valid(newVersion) && semver2.compare(newVersion, previousVersion) <= 0) {
+    if (previousVersion !== null && semver3.valid(previousVersion) && semver3.valid(newVersion) && semver3.compare(newVersion, previousVersion) <= 0) {
       return {
         packId: id,
         previousVersion,
@@ -26088,8 +26157,21 @@ async function updatePack(id, options = {}) {
       } catch (err2) {
         if (err2 instanceof PackLicenseError2) {
           const renew = pack.meta.purchaseUrl ? `renew at ${pack.meta.purchaseUrl}` : `redeem one with: relay license add <path-or-url to your .license.json>`;
+          let withheld = "";
+          try {
+            const { changelogWindow: changelogWindow2 } = await Promise.resolve().then(() => (init_recap(), recap_exports));
+            const pending = changelogWindow2(
+              pack.meta.changelog,
+              previousVersion,
+              newVersion
+            );
+            if (pending.length > 0) {
+              withheld = `This update includes: ` + pending.map((p) => `v${p.version} \u2014 ${p.note}`).join("; ") + ` `;
+            }
+          } catch {
+          }
           throw new PackLicenseError2(
-            `Your installed ${id} keeps working \u2014 nothing is locked. Updating to v${newVersion} needs an active license: ${renew}. (${err2.message})`,
+            `Your installed ${id} keeps working \u2014 nothing is locked. Updating to v${newVersion} needs an active license: ${renew}. ` + withheld + `(${err2.message})`,
             err2.reason
           );
         }
@@ -26097,7 +26179,7 @@ async function updatePack(id, options = {}) {
       }
     }
     const resolved = resolvePackLayer(pack);
-    const backupRoot = path22.join(
+    const backupRoot = path23.join(
       appsDir,
       id,
       "backup",
@@ -26106,12 +26188,12 @@ async function updatePack(id, options = {}) {
     const backedUp = [];
     for (const file of resolved.files) {
       const dest = artifactDestPath(file.relPath, profilesDir, blueprintsDir);
-      if (!dest || !fs21.existsSync(dest)) continue;
+      if (!dest || !fs22.existsSync(dest)) continue;
       const recorded = state?.files[file.relPath];
       if (recorded !== void 0 && hashFileSha256(dest) === recorded) continue;
-      const backupPath = path22.join(backupRoot, file.relPath);
-      fs21.mkdirSync(path22.dirname(backupPath), { recursive: true });
-      fs21.copyFileSync(dest, backupPath);
+      const backupPath = path23.join(backupRoot, file.relPath);
+      fs22.mkdirSync(path23.dirname(backupPath), { recursive: true });
+      fs22.copyFileSync(dest, backupPath);
       backedUp.push(file.relPath);
     }
     const install = await installPack(packDir, {
@@ -26395,6 +26477,17 @@ async function runAdd2(source, io) {
     return 1;
   }
 }
+async function pendingRecaps(entitlements, io) {
+  try {
+    const { entitledPackRecaps: entitledPackRecaps2 } = await Promise.resolve().then(() => (init_recap(), recap_exports));
+    return entitledPackRecaps2(entitlements, {
+      appsDir: io.appsDir,
+      templatesDir: io.templatesDir
+    }).filter((r) => r.pending.length > 0);
+  } catch {
+    return [];
+  }
+}
 async function runStatus(io) {
   try {
     const { listLicenses: listLicenses2 } = await Promise.resolve().then(() => (init_store(), store_exports));
@@ -26418,6 +26511,16 @@ async function runStatus(io) {
       io.log(
         `  Status:       ${lic.valid ? "valid" : `invalid \u2014 ${lic.reason ?? "corrupt entry"}`}`
       );
+      const recaps = await pendingRecaps(lic.entitlements, io);
+      if (lic.valid && recaps.length > 0) {
+        io.log(`  Included in your term, waiting to install:`);
+        for (const r of recaps) {
+          for (const p of r.pending) {
+            io.log(`    ${r.packName} v${p.version} \u2014 ${p.note}`);
+          }
+          io.log(`    \u2192 relay pack update ${r.packId}`);
+        }
+      }
       if (lic.valid && lic.expiresAt) {
         const daysLeft = Math.floor(
           (new Date(lic.expiresAt).getTime() - now.getTime()) / DAY_MS
@@ -26426,6 +26529,23 @@ async function runStatus(io) {
           io.log(
             `  \u26A0 Renewal:    expires in ${daysLeft} day${daysLeft === 1 ? "" : "s"}. Your installed packs are yours forever; renewing keeps new premium packs and updates flowing.`
           );
+          const latest = recaps.map((r) => ({ r, p: r.pending[r.pending.length - 1] })).filter((x) => x.p);
+          for (const { r, p } of latest) {
+            io.log(
+              `                This license year delivered ${r.packName} v${p.version} \u2014 ${p.note}`
+            );
+          }
+        }
+      }
+      if (!lic.valid && /expired/i.test(lic.reason ?? "") && recaps.length > 0) {
+        io.log(
+          `  Your installed packs keep working \u2014 nothing is locked. Renewing unlocks:`
+        );
+        for (const r of recaps) {
+          for (const p of r.pending) {
+            io.log(`    ${r.packName} v${p.version} \u2014 ${p.note}`);
+          }
+          if (r.purchaseUrl) io.log(`    \u2192 renew at ${r.purchaseUrl}`);
         }
       }
       io.log("");
@@ -26796,10 +26916,10 @@ import { existsSync as existsSync4, renameSync, cpSync, rmSync as rmSync2, readF
 import { join as join6 } from "path";
 import { homedir as homedir2 } from "os";
 import Database from "better-sqlite3";
-function hasSqliteHeader(path23) {
+function hasSqliteHeader(path24) {
   const SQLITE_MAGIC = "SQLite format 3\0";
   try {
-    const header = readFileSync3(path23, { encoding: null });
+    const header = readFileSync3(path24, { encoding: null });
     return header.length >= 16 && header.subarray(0, 16).toString("binary") === SQLITE_MAGIC;
   } catch {
     return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orionfold-relay",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Orionfold Relay — a local-first, multi-agent orchestration runtime and builder scaffold for AI-native work.",
   "keywords": [
     "ai",

package/src/app/packs/page.tsx

@@ -6,6 +6,7 @@ import { Boxes, Check, Lock, Package, TriangleAlert } from "lucide-react";
 import { listApps } from "@/lib/apps/registry";
 import { listPackTemplates, type PackTemplate } from "@/lib/packs/catalog";
 import { packUpdateAvailability } from "@/lib/packs/update";
+import { changelogWindow } from "@/lib/licensing/recap";
 import { PackInstallButton } from "@/components/packs/pack-install-button";
 import { PackUpdateButton } from "@/components/packs/pack-update-button";
 
@@ -150,11 +151,24 @@ function InstalledActions({ template }: { template: PackTemplate }) {
         </Link>
       </div>
       {avail.updateAvailable && avail.availableVersion && (
-        <PackUpdateButton
-          packId={template.id}
-          packName={template.meta!.name}
-          newVersion={avail.availableVersion}
-        />
+        <>
+          <PackUpdateButton
+            packId={template.id}
+            packName={template.meta!.name}
+            newVersion={avail.availableVersion}
+          />
+          {/* Value-recap one-liner: what the pending update contains, from the
+              pack's own changelog — same source as license status + the 402. */}
+          {changelogWindow(
+            template.meta!.changelog,
+            avail.installedVersion,
+            avail.availableVersion
+          ).map((p) => (
+            <p key={p.version} className="text-xs text-muted-foreground">
+              v{p.version} — {p.note}
+            </p>
+          ))}
+        </>
       )}
     </div>
   );

package/src/lib/licensing/cli.ts

@@ -14,6 +14,9 @@ export interface LicenseCommandIo {
   dir?: string;
   /** Injected clock (tests). */
   now?: Date;
+  /** Override the recap surface's pack dirs (tests). */
+  appsDir?: string;
+  templatesDir?: string;
   log: (message: string) => void;
   error: (message: string) => void;
 }
@@ -115,6 +118,25 @@ async function runAdd(
   }
 }
 
+/**
+ * Fail-open recap lookup — the value-recap is decoration on this surface,
+ * never a gate; any fault degrades to "no recap", not an error.
+ */
+async function pendingRecaps(
+  entitlements: string[],
+  io: LicenseCommandIo
+): Promise<import("./recap").PackRecap[]> {
+  try {
+    const { entitledPackRecaps } = await import("./recap");
+    return entitledPackRecaps(entitlements, {
+      appsDir: io.appsDir,
+      templatesDir: io.templatesDir,
+    }).filter((r) => r.pending.length > 0);
+  } catch {
+    return [];
+  }
+}
+
 async function runStatus(io: LicenseCommandIo): Promise<number> {
   try {
     const { listLicenses } = await import("./store");
@@ -141,6 +163,20 @@ async function runStatus(io: LicenseCommandIo): Promise<number> {
         `  Status:       ${lic.valid ? "valid" : `invalid — ${lic.reason ?? "corrupt entry"}`}`
       );
 
+      const recaps = await pendingRecaps(lic.entitlements, io);
+
+      // Value recap (PLG-4a): entitled updates this license already paid for,
+      // sitting uninstalled. Explicit invocation ⇒ informational, not a nag.
+      if (lic.valid && recaps.length > 0) {
+        io.log(`  Included in your term, waiting to install:`);
+        for (const r of recaps) {
+          for (const p of r.pending) {
+            io.log(`    ${r.packName} v${p.version} — ${p.note}`);
+          }
+          io.log(`    → relay pack update ${r.packId}`);
+        }
+      }
+
       // D4: expiry warns about FUTURE premium installs/updates only — it
       // never gates anything already installed, so this is a nudge, not a block.
       if (lic.valid && lic.expiresAt) {
@@ -153,6 +189,29 @@ async function runStatus(io: LicenseCommandIo): Promise<number> {
               `Your installed packs are yours forever; renewing keeps new premium ` +
               `packs and updates flowing.`
           );
+          // The generic promise gains this year's specific evidence.
+          const latest = recaps
+            .map((r) => ({ r, p: r.pending[r.pending.length - 1] }))
+            .filter((x) => x.p);
+          for (const { r, p } of latest) {
+            io.log(
+              `                This license year delivered ${r.packName} v${p.version} — ${p.note}`
+            );
+          }
+        }
+      }
+
+      // Expired license, renewal-voiced (same voice as the update gate): what
+      // renewal unlocks, never a threat to installed content.
+      if (!lic.valid && /expired/i.test(lic.reason ?? "") && recaps.length > 0) {
+        io.log(
+          `  Your installed packs keep working — nothing is locked. Renewing unlocks:`
+        );
+        for (const r of recaps) {
+          for (const p of r.pending) {
+            io.log(`    ${r.packName} v${p.version} — ${p.note}`);
+          }
+          if (r.purchaseUrl) io.log(`    → renew at ${r.purchaseUrl}`);
         }
       }
       io.log("");

package/src/lib/licensing/recap.ts

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+import semver from "semver";
+import { getAinativeAppsDir } from "@/lib/utils/ainative-paths";
+import { listPackTemplates } from "@/lib/packs/catalog";
+import { packUpdateAvailability } from "@/lib/packs/update";
+import { readInstallState } from "@/lib/packs/install-state";
+
+/**
+ * Renewal value-recap — the ONE source every renewal surface reads:
+ * `license status`, the 402 update refusal, the /packs update card, and the
+ * canonical copy relayed for the Website renewal email. Reuses
+ * `packUpdateAvailability` for the version comparison (D7: never a second
+ * comparison source) and the pack.yaml `changelog` map for the words.
+ *
+ * Everything here is FAIL-OPEN (cli-startup-robustness rule): a corrupt
+ * sidecar, a missing template, or a changelog-less pack degrades to silence —
+ * a recap must never crash or block `license status`.
+ *
+ * Consumers dynamically import this module (TDR-032: keep the CLI's static
+ * startup graph free of pack/licensing code).
+ */
+
+export interface PendingValue {
+  version: string;
+  note: string;
+}
+
+export interface PackRecap {
+  packId: string;
+  packName: string;
+  /** From the install-state sidecar; null = unknown (pre-0.21 install). */
+  installedVersion: string | null;
+  /** Sidecar install timestamp, when known. */
+  installedAt?: string;
+  availableVersion: string | null;
+  updateAvailable: boolean;
+  /** Changelog line for the version already installed — value received. */
+  received?: string;
+  /** Changelog lines in (installed, available], ascending — value pending. */
+  pending: PendingValue[];
+  purchaseUrl?: string;
+}
+
+/**
+ * Changelog lines in the half-open version window (fromExclusive, toInclusive],
+ * ascending. Invalid semver keys are skipped, never thrown on. A null `from`
+ * means "everything up to and including `to`".
+ */
+export function changelogWindow(
+  changelog: Record<string, string> | undefined,
+  fromExclusive: string | null,
+  toInclusive: string | null
+): PendingValue[] {
+  if (!changelog || !toInclusive || !semver.valid(toInclusive)) return [];
+  const from = fromExclusive && semver.valid(fromExclusive) ? fromExclusive : null;
+  return Object.entries(changelog)
+    .filter(([version]) => semver.valid(version))
+    .filter(
+      ([version]) =>
+        semver.compare(version, toInclusive) <= 0 &&
+        (from === null || semver.compare(version, from) > 0)
+    )
+    .sort(([a], [b]) => semver.compare(a, b))
+    .map(([version, note]) => ({ version, note }));
+}
+
+/**
+ * Recaps for every INSTALLED bundled pack whose entitlement is covered by
+ * `entitlements`. Uninstalled entitled packs are deliberately absent — that
+ * is install-nudge territory (D6), not renewal recap.
+ */
+export function entitledPackRecaps(
+  entitlements: string[],
+  opts: { appsDir?: string; templatesDir?: string } = {}
+): PackRecap[] {
+  try {
+    const appsDir = opts.appsDir ?? getAinativeAppsDir();
+    const covered = new Set(entitlements);
+    const out: PackRecap[] = [];
+
+    for (const tpl of listPackTemplates({ templatesDir: opts.templatesDir })) {
+      if (tpl.error || !tpl.meta?.entitlement) continue;
+      if (!covered.has(tpl.meta.entitlement)) continue;
+      if (!fs.existsSync(path.join(appsDir, tpl.id))) continue;
+
+      const avail = packUpdateAvailability(tpl.id, {
+        appsDir,
+        templatesDir: opts.templatesDir,
+      });
+      const state = readInstallState(appsDir, tpl.id);
+      const changelog = tpl.meta.changelog;
+
+      out.push({
+        packId: tpl.id,
+        packName: tpl.meta.name,
+        installedVersion: avail.installedVersion,
+        ...(state?.installedAt ? { installedAt: state.installedAt } : {}),
+        availableVersion: avail.availableVersion,
+        updateAvailable: avail.updateAvailable,
+        ...(avail.installedVersion && changelog?.[avail.installedVersion]
+          ? { received: changelog[avail.installedVersion] }
+          : {}),
+        pending: avail.updateAvailable
+          ? changelogWindow(
+              changelog,
+              avail.installedVersion,
+              avail.availableVersion
+            )
+          : [],
+        ...(tpl.meta.purchaseUrl ? { purchaseUrl: tpl.meta.purchaseUrl } : {}),
+      });
+    }
+    return out;
+  } catch {
+    // Fail-open: a recap is decoration on the licensing surfaces, never a gate.
+    return [];
+  }
+}

package/src/lib/packs/format.ts

@@ -51,6 +51,13 @@ export const PackManifestSchema = z
     price: z.string().min(1).optional(),
     /** Get-license CTA target on the locked card. */
     purchaseUrl: z.url().optional(),
+    /**
+     * Per-version customer-voice recap, version → one line. The single source
+     * for every renewal value-recap surface (`license status`, the 402 update
+     * refusal, the /packs update card, the Website renewal email). Optional —
+     * but paid packs should carry it, or their renewal case argues generically.
+     */
+    changelog: z.record(z.string(), z.string().min(1)).optional(),
     /** Customer slugs seeded via ensureCustomer at install. */
     customers: z.array(z.string()).default([]),
   })

package/src/lib/packs/templates/relay-agency-pro/pack.yaml

@@ -22,5 +22,18 @@ relayCore: ">=0.18.0"
 entitlement: product:orionfold-relay
 price: "$499/year"
 purchaseUrl: https://orionfold.com/relay/
-# Pro seeds no demo customers — it operates your real ones.
+# Per-version customer-voice recap — the single source every renewal surface
+# reads (license status, the update refusal, the /packs card, the renewal
+# email). Add a line here with EVERY version bump; the template test suite
+# requires an entry for the current version.
+changelog:
+  "0.1.0": >-
+    Six chapters of agency operating system — the Finance Cockpit that closes
+    your month by itself, Intake Pipelines, the New-Business Machine,
+    client-safe Governance profiles, and the Commercial Real Estate renewal
+    engine.
+  "0.2.0": >-
+    The Nonprofit deep chapter — a grant pipeline that takes every opportunity
+    from fit-scored go/no-go through LOI, full application, and post-award
+    restricted-funds compliance with a reporting calendar.
 customers: []

package/src/lib/packs/update.ts

@@ -179,9 +179,29 @@ export async function updatePack(
           const renew = pack.meta.purchaseUrl
             ? `renew at ${pack.meta.purchaseUrl}`
             : `redeem one with: relay license add <path-or-url to your .license.json>`;
+          // Value-recap voice: name what the withheld update contains, from
+          // the pack's own changelog (fail-open — silence if it has none).
+          let withheld = "";
+          try {
+            const { changelogWindow } = await import("@/lib/licensing/recap");
+            const pending = changelogWindow(
+              pack.meta.changelog,
+              previousVersion,
+              newVersion
+            );
+            if (pending.length > 0) {
+              withheld =
+                `This update includes: ` +
+                pending.map((p) => `v${p.version} — ${p.note}`).join("; ") +
+                ` `;
+            }
+          } catch {
+            // recap is decoration on the refusal, never a second failure.
+          }
           throw new PackLicenseError(
             `Your installed ${id} keeps working — nothing is locked. ` +
               `Updating to v${newVersion} needs an active license: ${renew}. ` +
+              withheld +
               `(${err.message})`,
             err.reason
           );

package/src/lib/plugins/examples/echo-server/plugin.yaml

@@ -1,6 +1,6 @@
 id: echo-server
 version: 0.1.0
-apiVersion: "0.21"
+apiVersion: "0.22"
 kind: chat-tools
 name: Echo Server
 description: |

package/src/lib/plugins/examples/finance-pack/plugin.yaml

@@ -1,6 +1,6 @@
 id: finance-pack
 version: 0.1.0
-apiVersion: "0.21"
+apiVersion: "0.22"
 kind: primitives-bundle
 name: Finance Pack
 description: |

package/src/lib/plugins/examples/reading-radar/plugin.yaml

@@ -1,6 +1,6 @@
 id: reading-radar
 version: 0.1.0
-apiVersion: "0.21"
+apiVersion: "0.22"
 kind: primitives-bundle
 name: Reading Radar
 description: |

package/src/lib/plugins/registry.ts

@@ -53,7 +53,7 @@ import type { ScheduleSpec } from "@/lib/validators/schedule-spec";
 // unfixed from 0.15.0 through 0.16.0 — treat the window test's failure as
 // a release blocker, not noise). The 0.13→0.14 three-MINOR bridge is over;
 // this is the standard 2-MINOR window now.
-const SUPPORTED_API_VERSIONS = new Set([CURRENT_PLUGIN_API_VERSION, "0.20"]);
+const SUPPORTED_API_VERSIONS = new Set([CURRENT_PLUGIN_API_VERSION, "0.21"]);
 
 /** Test-helper export so the window-enforcement test can read state. */
 export function isSupportedApiVersion(apiVersion: string): boolean {

package/src/lib/plugins/sdk/types.ts

@@ -6,7 +6,7 @@ import { z } from "zod";
 // (a hardcoded copy there once drifted to "0.14" — scaffolded plugins would
 // have been disabled on load the moment the window tightened). Bump on every
 // MINOR release; api-version-window.test.ts fails if this goes stale.
-export const CURRENT_PLUGIN_API_VERSION = "0.21";
+export const CURRENT_PLUGIN_API_VERSION = "0.22";
 
 // Shared capability tuple — single source of truth used by Zod schema and
 // capability-check.ts hash derivation. Exported so consumers don't need a