@circuitwall/jarela 2.2.0 → 2.3.0

package/lib/db/migrations.ts

@@ -469,6 +469,7 @@ export function runMigrations(db: DatabaseSync): void {
   ensureCredentialsTable(db);
   ensureCredentialsLabelAndDefaultColumns(db);
   ensureModelConfigCredentialIdColumn(db);
+  ensureModelConfigEnabledColumn(db);
   ensureAgentConfigsToolCredentialsColumn(db);
   seedAgentConfigs(db);
   backfillDeveloperInteractiveTerminalTools(db);
@@ -628,6 +629,11 @@ function ensureThreadChannelSummariesTable(db: DatabaseSync): void {
   if (!cols.some((column) => column.name === "summary_before_seq")) {
     db.exec("ALTER TABLE thread_channel_summaries ADD COLUMN summary_before_seq INTEGER");
   }
+  // Stored topic segments (JSON array) so the next compaction can merge new
+  // activity into them instead of re-summarising the channel from scratch.
+  if (!cols.some((column) => column.name === "topics")) {
+    db.exec("ALTER TABLE thread_channel_summaries ADD COLUMN topics TEXT");
+  }
 }
 
 // ADR-0041. Immutable per-assistant-turn snapshot of LLM usage. Written once
@@ -1553,6 +1559,15 @@ function ensureModelConfigCredentialIdColumn(db: DatabaseSync): void {
   }
 }
 
+// ADR-0102: disabled model configs stay saved but are hidden from model
+// selection, routing, and default fallback. Existing rows default to enabled.
+function ensureModelConfigEnabledColumn(db: DatabaseSync): void {
+  const cols = db.prepare("PRAGMA table_info(model_configs)").all() as Array<{ name: string }>;
+  if (!cols.some((c) => c.name === "enabled")) {
+    db.exec("ALTER TABLE model_configs ADD COLUMN enabled INTEGER NOT NULL DEFAULT 1");
+  }
+}
+
 // Idempotent backfill: for each model_config still carrying an inline
 // `api_key` (and no `credential_id` yet), create a credential row and
 // link by id. Strips the api_key / base_url / extra_headers fields from

package/lib/env/config.ts

@@ -44,6 +44,7 @@ export interface JarelaConfig {
   readonly streamParseTripwire: number;
   readonly recallBudgetMs: number;
   readonly warmSummaryBudgetMs: number;
+  readonly compactionTimeoutMs: number;
   readonly maxThreadMessages: number;
   readonly maxSessionArchives: number;
 
@@ -212,6 +213,7 @@ export function getConfig(): JarelaConfig {
     streamParseTripwire: parsePositiveInt(env.JARELA_STREAM_PARSE_TRIPWIRE, ENV_DEFAULTS.streamParseTripwire),
     recallBudgetMs: parseNonNegativeInt(env.JARELA_RECALL_BUDGET_MS, ENV_DEFAULTS.recallBudgetMs),
     warmSummaryBudgetMs: parseNonNegativeInt(env.JARELA_WARM_SUMMARY_BUDGET_MS, ENV_DEFAULTS.warmSummaryBudgetMs),
+    compactionTimeoutMs: parsePositiveInt(env.JARELA_COMPACTION_TIMEOUT_MS, ENV_DEFAULTS.compactionTimeoutMs),
     maxThreadMessages: parsePositiveInt(env.JARELA_MAX_THREAD_MESSAGES, ENV_DEFAULTS.maxThreadMessages),
     maxSessionArchives: parsePositiveInt(env.JARELA_MAX_SESSION_ARCHIVES, ENV_DEFAULTS.maxSessionArchives),
 

package/lib/env/schema.ts

@@ -86,6 +86,7 @@ export const ENV_DEFAULTS = {
   streamParseTripwire: 6,
   recallBudgetMs: 1500,
   warmSummaryBudgetMs: 5000,
+  compactionTimeoutMs: 10 * 60_000,
   maxThreadMessages: 1000,
   maxSessionArchives: 50,
   // tools
@@ -268,6 +269,17 @@ export const ENV_SCHEMA: readonly EnvVarDef[] = [
     agentWritable: false,
     min: 60_000,
   },
+  {
+    name: "JARELA_COMPACTION_TIMEOUT_MS",
+    type: "int",
+    default: ENV_DEFAULTS.compactionTimeoutMs,
+    description: "Deadline for one warm-context compaction of a thread; a late result is discarded and the thread is released.",
+    category: "agent",
+    tier: "B",
+    requiresRestart: false,
+    agentWritable: false,
+    min: 30_000,
+  },
   {
     name: "JARELA_RUN_REGISTRY_TTL_MS",
     type: "int",

package/lib/health/probes.test.ts

@@ -562,17 +562,14 @@ describe("health probes", () => {
       expect(r.status).toBe("auth_failed");
       expect(String(r.error)).toMatch(/subscription/i);
     });
-    it("PAT fallback: ok against the Models API", async () => {
-      saveIntegration("github-copilot", { api_key: "ghp_xxx" });
-      mockFetch(() => jsonResponse({ models: [] }));
-      const r = await probeGithubCopilot();
-      expect(r.status).toBe("ok");
-      expect(r.detail?.auth).toBe("pat");
-    });
-    it("PAT fallback: 401 auth_failed", async () => {
-      saveIntegration("github-copilot", { api_key: "ghp_bad" });
-      mockFetch(() => new Response("", { status: 401 }));
-      expect((await probeGithubCopilot()).status).toBe("auth_failed");
+    it("rejects legacy PAT credentials without probing GitHub Models", async () => {
+      saveIntegration("github-copilot", { api_key: "ghp_synthetic" });
+      const fetch = vi.fn();
+      vi.stubGlobal("fetch", fetch);
+      const result = await probeGithubCopilot();
+      expect(result.status).toBe("auth_failed");
+      expect(result.error).toMatch(/device-flow sign-in/i);
+      expect(fetch).not.toHaveBeenCalled();
     });
     it("prefers OAuth token over PAT when both are present", async () => {
       storeOAuthToken("gho_xxx");

package/lib/health/probes.ts

@@ -410,13 +410,8 @@ export async function probeCohere(): Promise<HealthResult> {
 }
 
 export async function probeGithubCopilot(): Promise<HealthResult> {
-  // Two credential paths share this probe:
-  //   1. Device-flow OAuth token (stored under memory_store namespace
-  //      "github-copilot-auth" by the in-app sign-in). Verified by
-  //      exchanging it for a Copilot session token.
-  //   2. Personal Access Token saved via the Integrations panel.
-  //      PATs cannot be exchanged, so we check them against the GitHub
-  //      Models REST surface which Copilot PATs are routed to.
+  // Device-flow OAuth token stored under the github-copilot-auth namespace.
+  // Legacy PAT credentials used GitHub Models, which has been retired.
   const oauth = getStoredCopilotOAuthToken();
   if (oauth) {
     try {
@@ -441,30 +436,9 @@ export async function probeGithubCopilot(): Promise<HealthResult> {
       return transient(describeError(err));
     }
   }
-  const pat = getIntegrationRaw("github-copilot")?.api_key?.trim();
-  if (!pat) return unconfigured("Not signed in and no PAT configured");
-  try {
-    const res = await fetch("https://models.github.ai/catalog/models", {
-      headers: {
-        Authorization: `Bearer ${pat}`,
-        Accept: "application/vnd.github+json",
-        "X-GitHub-Api-Version": "2026-03-10",
-        "User-Agent": "Jarela",
-      },
-      signal: probeSignal(DEFAULT_PROBE_TIMEOUT_MS),
-    });
-    if (res.status === 401 || res.status === 403) {
-      return authFailed(`GitHub rejected the PAT (${res.status}). Confirm the token has the "copilot" scope and your subscription is active.`);
-    }
-    if (res.status === 429) return transient("GitHub rate-limited the probe (429).");
-    if (!res.ok) {
-      const body = await res.text().catch(() => "");
-      return probeError(`GitHub Models ${res.status}: ${body.slice(0, 200)}`);
-    }
-    return ok({ auth: "pat" });
-  } catch (err) {
-    return transient(describeError(err));
-  }
+  const legacyPat = getIntegrationRaw("github-copilot")?.api_key?.trim();
+  if (!legacyPat) return unconfigured("Not signed in. Use device-flow sign-in from the Models panel.");
+  return authFailed("GitHub PAT authentication is no longer supported. Use device-flow sign-in from the Models panel.");
 }
 
 export async function probeClaudeCode(): Promise<HealthResult> {

package/lib/lifecycle/changeset-build.test.ts

@@ -0,0 +1,93 @@
+import { afterAll, describe, expect, it } from "vitest";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  extractAdoptionHints,
+  renderChangesetsMarkdown,
+  upsertChangeset,
+  writeReleaseChangeset,
+} from "./changeset-build";
+import type { SurfaceSnapshot } from "./surface-snapshot";
+
+const tmpRoot = mkdtempSync(join(tmpdir(), "jarela-changeset-build-"));
+afterAll(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* held open */ }
+});
+
+const CHANGELOG = [
+  "# Changelog",
+  "## [Unreleased]",
+  "## [2.3.0] - 2026-02-01",
+  "### Added",
+  "- Something.",
+  "### Adoption",
+  "- Re-run watchers that use `web_search`;",
+  "  the `query` param is now required.",
+  "- Remove `old_tool` from allowlists.",
+  "## [2.2.0] - 2026-01-01",
+  "### Adoption",
+  "- Older hint.",
+].join("\n");
+
+function snapshot(version: string, tools: SurfaceSnapshot["tools"], prompts: SurfaceSnapshot["prompts"] = {}): SurfaceSnapshot {
+  return { schema_version: 1, version, prompts, tools };
+}
+
+describe("extractAdoptionHints", () => {
+  it("reads only the version's Adoption bullets, joining wrapped lines", () => {
+    expect(extractAdoptionHints(CHANGELOG, "2.3.0")).toEqual([
+      "Re-run watchers that use `web_search`; the `query` param is now required.",
+      "Remove `old_tool` from allowlists.",
+    ]);
+    expect(extractAdoptionHints(CHANGELOG, "2.2.0")).toEqual(["Older hint."]);
+    expect(extractAdoptionHints(CHANGELOG, "9.9.9")).toEqual([]);
+  });
+});
+
+describe("upsertChangeset and renderChangesetsMarkdown", () => {
+  const base = { previous_version: "1.0.0", date: "d", hints: [], commits: [], prompts: [], tools: [] };
+
+  it("replaces an existing version and keeps versions sorted", () => {
+    const file = upsertChangeset(
+      { schema_version: 1, changesets: [{ ...base, version: "2.10.0" }, { ...base, version: "2.9.0", hints: ["old"] }] },
+      { ...base, version: "2.9.0", hints: ["new"] },
+    );
+    expect(file.changesets.map((e) => [e.version, e.hints])).toEqual([["2.9.0", ["new"]], ["2.10.0", []]]);
+    const md = renderChangesetsMarkdown(file);
+    expect(md.indexOf("## 2.10.0")).toBeLessThan(md.indexOf("## 2.9.0"));
+    expect(md).toContain("- new");
+  });
+});
+
+describe("writeReleaseChangeset", () => {
+  it("diffs the committed snapshot, writes docs, and advances the snapshot", () => {
+    const root = join(tmpRoot, "repo");
+    mkdirSync(join(root, "docs/adoption"), { recursive: true });
+    writeFileSync(join(root, "CHANGELOG.md"), CHANGELOG);
+    const prev = snapshot("2.2.0", { web_search: { description: "Search.", parameters: { type: "object", properties: { query: {} } } } });
+    writeFileSync(join(root, "docs/adoption/surface-snapshot.json"), JSON.stringify(prev));
+    const next = snapshot("ignored", {
+      web_search: { description: "Search.", parameters: { type: "object", properties: { query: {} }, required: ["query"] } },
+    }, { "system.Rules": { source: "s.ts", text: "be careful" } });
+
+    const entry = writeReleaseChangeset({ root, version: "2.3.0", nextSnapshot: next, date: "2026-02-01" });
+
+    expect(entry).toMatchObject({ version: "2.3.0", previous_version: "2.2.0", commits: [] });
+    expect(entry.hints).toHaveLength(2);
+    expect(entry.tools).toMatchObject([{ name: "web_search", required_added: ["query"] }]);
+    expect(entry.prompts).toMatchObject([{ id: "system.Rules", change: "added" }]);
+    const written = JSON.parse(readFileSync(join(root, "docs/adoption/changesets.json"), "utf8"));
+    expect(written.changesets.map((e: { version: string }) => e.version)).toEqual(["2.3.0"]);
+    expect(JSON.parse(readFileSync(join(root, "docs/adoption/surface-snapshot.json"), "utf8")).version).toBe("2.3.0");
+    expect(readFileSync(join(root, "docs/adoption/index.md"), "utf8")).toContain("`web_search` — changed");
+  });
+
+  it("refuses to record a version that is not newer than the snapshot", () => {
+    const root = join(tmpRoot, "stale");
+    mkdirSync(join(root, "docs/adoption"), { recursive: true });
+    writeFileSync(join(root, "docs/adoption/surface-snapshot.json"), JSON.stringify(snapshot("2.3.0", {})));
+    expect(() => writeReleaseChangeset({ root, version: "2.2.0", nextSnapshot: snapshot("x", {}), date: "d" }))
+      .toThrow(/must be newer/);
+  });
+});

package/lib/lifecycle/changeset-build.ts

@@ -0,0 +1,210 @@
+/**
+ * Release-time changeset generation. Diffs the committed surface snapshot
+ * (docs/adoption/surface-snapshot.json) against the current one and records
+ * the prompt and tool deltas for the release version. Run through
+ * `npm run release:changeset`; never imported by the running app.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  changesetFileSchema,
+  compareVersions,
+  type ChangesetFile,
+  type ReleaseChangeset,
+} from "./changesets";
+import { diffSurfaces, type SurfaceSnapshot } from "./surface-snapshot";
+
+export const ADOPTION_DOCS_DIR = "docs/adoption";
+export const CHANGESETS_FILE = `${ADOPTION_DOCS_DIR}/changesets.json`;
+export const SNAPSHOT_FILE = `${ADOPTION_DOCS_DIR}/surface-snapshot.json`;
+export const CHANGESETS_PAGE = `${ADOPTION_DOCS_DIR}/index.md`;
+const MAX_COMMITS = 40;
+
+/** Bullets under `### Adoption` in the version's CHANGELOG section. */
+export function extractAdoptionHints(changelog: string, version: string): string[] {
+  const lines = changelog.split(/\r?\n/);
+  const start = lines.findIndex((line) => new RegExp(`^## \\[?${version.replace(/\./g, "\\.")}\\]?(\\s|$)`).test(line));
+  if (start === -1) return [];
+  const hints: string[] = [];
+  let inAdoption = false;
+  for (const line of lines.slice(start + 1)) {
+    if (/^## /.test(line)) break;
+    if (/^### /.test(line)) {
+      inAdoption = /^### Adoption\s*$/i.test(line);
+      continue;
+    }
+    if (!inAdoption) continue;
+    const bullet = /^\s*[-*]\s+(.+)$/.exec(line);
+    if (bullet) hints.push(bullet[1].trim());
+    else if (line.trim() && hints.length > 0) hints[hints.length - 1] += ` ${line.trim()}`;
+  }
+  return hints;
+}
+
+export function buildChangesetEntry(input: {
+  version: string;
+  previousSnapshot: SurfaceSnapshot;
+  nextSnapshot: SurfaceSnapshot;
+  date: string;
+  hints: string[];
+  commits: string[];
+}): ReleaseChangeset {
+  const delta = diffSurfaces(input.previousSnapshot, input.nextSnapshot);
+  return {
+    version: input.version,
+    previous_version: input.previousSnapshot.version,
+    date: input.date,
+    hints: input.hints,
+    commits: input.commits.slice(0, MAX_COMMITS),
+    prompts: delta.prompts,
+    tools: delta.tools,
+  };
+}
+
+export function upsertChangeset(file: ChangesetFile, entry: ReleaseChangeset): ChangesetFile {
+  const rest = file.changesets.filter((existing) => existing.version !== entry.version);
+  return {
+    schema_version: 1,
+    changesets: [...rest, entry].sort((a, b) => compareVersions(a.version, b.version)),
+  };
+}
+
+export function renderChangesetsMarkdown(file: ChangesetFile): string {
+  const out = [
+    "# Version adoption changesets",
+    "",
+    "Generated by `npm run release:changeset` — do not edit by hand.",
+    "",
+    "Each release records how the model-facing surface changed: prompt text Jarela sends and built-in tool",
+    "descriptions and parameter schemas. When Jarela starts on a new version, the default agent reads the",
+    "changesets between your last adopted version and the running one, then adapts your settings, agent",
+    "instructions, skills, and scheduled task or watcher prompts. Code changes are covered by the",
+    "[changelog](https://github.com/CircuitWall/jarela/blob/main/CHANGELOG.md).",
+    "",
+    "Release authors can add adoption hints as bullets under a `### Adoption` heading in the version's",
+    "CHANGELOG section.",
+  ];
+  for (const entry of [...file.changesets].reverse()) {
+    out.push("", `## ${entry.version}`, "", `From ${entry.previous_version ?? "—"} · ${entry.date}`, "");
+    if (entry.hints.length) {
+      out.push("### Adoption hints", "", ...entry.hints.map((hint) => `- ${hint}`), "");
+    }
+    out.push("### Tools", "");
+    if (entry.tools.length === 0) out.push("No tool description or schema changes.");
+    for (const tool of entry.tools) {
+      const details = [
+        tool.description_changed ? "description changed" : "",
+        tool.params_added.length ? `params added: ${tool.params_added.map((p) => `\`${p}\``).join(", ")}` : "",
+        tool.params_removed.length ? `params removed: ${tool.params_removed.map((p) => `\`${p}\``).join(", ")}` : "",
+        tool.params_changed.length ? `params changed: ${tool.params_changed.map((p) => `\`${p}\``).join(", ")}` : "",
+        tool.required_added.length ? `now required: ${tool.required_added.map((p) => `\`${p}\``).join(", ")}` : "",
+        tool.required_removed.length ? `no longer required: ${tool.required_removed.map((p) => `\`${p}\``).join(", ")}` : "",
+      ].filter(Boolean);
+      out.push(`- \`${tool.name}\` — ${tool.change}${details.length ? `; ${details.join("; ")}` : ""}`);
+    }
+    out.push("", "### Prompts", "");
+    if (entry.prompts.length === 0) out.push("No prompt text changes.");
+    for (const prompt of entry.prompts) {
+      out.push(`- \`${prompt.id}\` — ${prompt.change} (\`${prompt.source}\`)`);
+      const diff = [
+        ...prompt.added_lines.map((line) => `+ ${line}`),
+        ...prompt.removed_lines.map((line) => `- ${line}`),
+        ...(prompt.omitted_lines > 0 ? [`… ${prompt.omitted_lines} more line(s)`] : []),
+      ];
+      if (diff.length) out.push("", "    ```diff", ...diff.map((line) => `    ${line}`), "    ```", "");
+    }
+    if (entry.commits.length) {
+      out.push("", "### Commits", "", ...entry.commits.map((subject) => `- ${subject}`));
+    }
+  }
+  return `${out.join("\n").replace(/\n{3,}/g, "\n\n")}\n`;
+}
+
+export function readChangesetFile(root: string): ChangesetFile {
+  const path = join(root, CHANGESETS_FILE);
+  if (!existsSync(path)) return { schema_version: 1, changesets: [] };
+  return changesetFileSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export function readSnapshot(path: string): SurfaceSnapshot {
+  return JSON.parse(readFileSync(path, "utf8")) as SurfaceSnapshot;
+}
+
+function snapshotAtTag(root: string, version: string): SurfaceSnapshot | null {
+  try {
+    const raw = execFileSync("git", ["show", `v${version}:${SNAPSHOT_FILE}`], {
+      cwd: root,
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return JSON.parse(raw) as SurfaceSnapshot;
+  } catch {
+    return null;
+  }
+}
+
+export function gitCommitSubjects(root: string, from: string, to: string): string[] {
+  try {
+    const raw = execFileSync("git", ["log", "--no-merges", "--format=%s", `${from}..${to}`], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return raw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function writeJson(path: string, value: unknown): void {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+/**
+ * Records the changeset for `version` against the committed snapshot, then
+ * moves the committed snapshot forward. Re-running for the same version
+ * replaces that entry, diffing against the snapshot committed at the
+ * predecessor's release tag.
+ */
+export function writeReleaseChangeset(input: {
+  root: string;
+  version: string;
+  nextSnapshot: SurfaceSnapshot;
+  date: string;
+  /** Git ref the release is cut from, for commit subjects. Defaults to HEAD. */
+  ref?: string;
+  /** Snapshot to diff against instead of the committed one (backfill). */
+  previousSnapshot?: SurfaceSnapshot;
+}): ReleaseChangeset {
+  const snapshotPath = join(input.root, SNAPSHOT_FILE);
+  const file = readChangesetFile(input.root);
+  let previous = input.previousSnapshot ?? readSnapshot(snapshotPath);
+  if (!input.previousSnapshot && previous.version === input.version) {
+    const recorded = file.changesets.find((entry) => entry.version === input.version)?.previous_version;
+    const prior = recorded ? snapshotAtTag(input.root, recorded) : null;
+    if (!prior) {
+      throw new Error(`Snapshot is already at ${input.version}; cannot find the v${recorded ?? "?"} snapshot to diff against.`);
+    }
+    previous = prior;
+  }
+  if (compareVersions(input.version, previous.version) <= 0) {
+    throw new Error(`Release version ${input.version} must be newer than snapshot version ${previous.version}.`);
+  }
+  const changelogPath = join(input.root, "CHANGELOG.md");
+  const changelog = existsSync(changelogPath) ? readFileSync(changelogPath, "utf8") : "";
+  const entry = buildChangesetEntry({
+    version: input.version,
+    previousSnapshot: previous,
+    nextSnapshot: { ...input.nextSnapshot, version: input.version },
+    date: input.date,
+    hints: extractAdoptionHints(changelog, input.version),
+    commits: gitCommitSubjects(input.root, `v${previous.version}`, input.ref ?? "HEAD"),
+  });
+  const updated = upsertChangeset(file, entry);
+  writeJson(join(input.root, CHANGESETS_FILE), updated);
+  writeFileSync(join(input.root, CHANGESETS_PAGE), renderChangesetsMarkdown(updated), "utf8");
+  writeJson(snapshotPath, { ...input.nextSnapshot, version: input.version });
+  return entry;
+}

package/lib/lifecycle/changesets.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  changesetFileSchema,
+  changesetsBetween,
+  compareVersions,
+  formatChangesetsForPrompt,
+  loadBundledChangesets,
+  summarizeChangesets,
+  type ReleaseChangeset,
+} from "./changesets";
+
+function entry(version: string, previous: string | null, overrides: Partial<ReleaseChangeset> = {}): ReleaseChangeset {
+  return { version, previous_version: previous, date: "2026-01-01", hints: [], commits: [], prompts: [], tools: [], ...overrides };
+}
+
+const tool = (name: string, change: "added" | "removed" | "changed") => ({
+  name, change, description_changed: change === "changed", description: `${name} does things.`,
+  params_added: [], params_removed: [], params_changed: [], required_added: [], required_removed: [],
+});
+
+describe("compareVersions", () => {
+  it("orders numerically, not lexically", () => {
+    expect(compareVersions("2.10.0", "2.9.9")).toBeGreaterThan(0);
+    expect(compareVersions("2.0.5", "2.0.5")).toBe(0);
+    expect(compareVersions("1.99.0", "2.0.0")).toBeLessThan(0);
+  });
+});
+
+describe("changesetsBetween", () => {
+  const all = [entry("2.0.1", "2.0.0"), entry("2.1.0", "2.0.1"), entry("2.2.0", "2.1.0")];
+
+  it("returns the cumulative range (previous, current] and marks full coverage", () => {
+    const range = changesetsBetween("2.0.1", "2.2.0", all);
+    expect(range.entries.map((e) => e.version)).toEqual(["2.1.0", "2.2.0"]);
+    expect(range.complete).toBe(true);
+  });
+
+  it("flags partial coverage when the range starts before the first changeset", () => {
+    const range = changesetsBetween("1.9.0", "2.2.0", all);
+    expect(range.entries).toHaveLength(3);
+    expect(range.complete).toBe(false);
+  });
+
+  it("flags partial coverage when the current version has no changeset", () => {
+    expect(changesetsBetween("2.1.0", "2.3.0", all).complete).toBe(false);
+  });
+});
+
+describe("summarizeChangesets and formatChangesetsForPrompt", () => {
+  const entries = [
+    entry("2.1.0", "2.0.0", {
+      hints: ["Re-check watchers."],
+      tools: [tool("old_tool", "removed"), tool("search", "changed")],
+      prompts: [{ id: "system.Tool usage SOP", source: "s.ts", change: "changed", added_lines: ["+rule"], removed_lines: ["-rule"], omitted_lines: 2 }],
+    }),
+    entry("2.2.0", "2.1.0", { tools: [tool("old_tool", "added")] }),
+  ];
+
+  it("keeps the latest state of each surface across the range", () => {
+    expect(summarizeChangesets(entries)).toEqual({
+      promptIds: ["system.Tool usage SOP"],
+      toolNames: ["old_tool", "search"],
+      removedTools: [],
+      hints: ["2.1.0: Re-check watchers."],
+    });
+  });
+
+  it("renders hints, tool deltas, and prompt excerpts within the budget", () => {
+    const text = formatChangesetsForPrompt(entries);
+    expect(text).toContain("adoption hint: Re-check watchers.");
+    expect(text).toContain("tool `old_tool`: removed");
+    expect(text).toContain("+ +rule");
+    expect(text).toContain("2 more changed line(s)");
+    expect(formatChangesetsForPrompt(entries, 40).length).toBeLessThan(200);
+  });
+});
+
+describe("bundled changesets", () => {
+  const raw = JSON.parse(readFileSync(join(process.cwd(), "docs/adoption/changesets.json"), "utf8"));
+  const bundled = loadBundledChangesets();
+
+  it("matches the schema", () => {
+    expect(changesetFileSchema.safeParse(raw).success).toBe(true);
+    expect(bundled.length).toBe(raw.changesets.length);
+  });
+
+  it("has an entry for the package.json version so the release PR cannot skip it", () => {
+    const { version } = JSON.parse(readFileSync(join(process.cwd(), "package.json"), "utf8")) as { version: string };
+    expect(bundled.map((e) => e.version), "run `npm run release:changeset` in the release PR").toContain(version);
+    const snapshot = JSON.parse(readFileSync(join(process.cwd(), "docs/adoption/surface-snapshot.json"), "utf8"));
+    expect(snapshot.version).toBe(version);
+  });
+
+  it("chains each release to its predecessor without gaps", () => {
+    for (let i = 1; i < bundled.length; i++) {
+      expect(bundled[i].previous_version, bundled[i].version).toBe(bundled[i - 1].version);
+    }
+  });
+});