@circuitwall/jarela 2.2.1 → 2.4.0

package/lib/proxy/dispatcher.ts

@@ -215,7 +215,18 @@ function buildProxyUrl(
   const auth = username
     ? `${encodeURIComponent(username)}${password ? `:${encodeURIComponent(password)}` : ""}@`
     : "";
-  return `${scheme}://${auth}${host}:${port}`;
+  const urlHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+  return `${scheme}://${auth}${urlHost}:${port}`;
+}
+
+// undici's EnvHttpProxyAgent has no implicit loopback exemption, so without
+// these a configured proxy would also receive local traffic (Ollama, the
+// WhatsApp bridge sidecar, the app's own loopback API).
+const LOOPBACK_NO_PROXY = ["localhost", "127.0.0.1", "::1"];
+
+function mergeNoProxy(noProxy: string | null): string {
+  const entries = (noProxy ?? "").split(/[,\s]+/).map((entry) => entry.trim()).filter(Boolean);
+  return [...new Set([...entries, ...LOOPBACK_NO_PROXY])].join(",");
 }
 
 function installProxy(url: string, noProxy: string | null, caBundle: string | null): void {
@@ -224,22 +235,24 @@ function installProxy(url: string, noProxy: string | null, caBundle: string | nu
   // We still treat the boot-time env snapshot as authoritative for the
   // "env beats DB" rule — this mutation only happens after we've
   // confirmed the user did NOT set HTTP_PROXY at launch.
+  const merged = mergeNoProxy(noProxy);
   process.env.HTTP_PROXY = url;
   process.env.HTTPS_PROXY = url;
-  if (noProxy && noProxy.trim().length > 0) {
-    process.env.NO_PROXY = noProxy.trim();
-  } else {
-    delete process.env.NO_PROXY;
-  }
+  process.env.NO_PROXY = merged;
   // ADR-0012: when the user pasted a corporate root CA, inject it on
   // both TLS legs — the proxy hop (proxyTls) for https-scheme proxies
   // signed by the corporate root, and the upstream tunnel (requestTls)
   // for proxies that MITM outbound HTTPS with the same internal CA.
   // Same blob is correct: the corporate trust chain typically signs
   // both ends.
-  const opts = caBundle
-    ? { requestTls: { ca: caBundle }, proxyTls: { ca: caBundle } }
-    : {};
+  // Pass the values explicitly too: undici prefers lowercase http_proxy /
+  // no_proxy from the environment over the uppercase ones set above.
+  const opts = {
+    httpProxy: url,
+    httpsProxy: url,
+    noProxy: merged,
+    ...(caBundle ? { requestTls: { ca: caBundle }, proxyTls: { ca: caBundle } } : {}),
+  };
   setGlobalDispatcher(new EnvHttpProxyAgent(opts));
 }
 

package/lib/skills/builtins/memory-organization/SKILL.md

@@ -37,6 +37,22 @@ Every update to an existing key keeps a dated snapshot of the prior record in
 its `history`, and older free-form or v1 entries are upgraded to the current
 schema automatically the first time they're read — no manual migration step.
 
+## Proactive Saving
+
+Memory is shared by every Jarela agent, so save durable information in the
+turn it appears instead of relying on background compaction, which runs later
+and can miss details.
+
+1. **Trigger:** the user states a preference, fact, decision, constraint, or
+   correction; or a tool result verifies a durable fact.
+2. **Check:** search for an existing record on the same subject and reuse its
+   key.
+3. **Write:** call `memory_upsert` before the final reply.
+4. **Validate:** the result must contain `ok: true` and the key you sent;
+   retry once on failure, then tell the user it was not saved.
+5. **Cite:** end the reply with `Saved to memory: facts/<key>` for each saved
+   key.
+
 ## Retrieval And Consolidation
 
 1. Let proactive recall supply matching facts on normal user turns. Use

package/lib/stores/agent-configs.ts

@@ -253,12 +253,17 @@ function upsertAgentConfigTransaction(input: UpsertAgentInput): AgentConfigRow {
   const db = getDb();
   const existing = getAgentConfig(input.id);
   const created_at = existing?.created_at ?? t;
-  const mbti = input.adaptive_mbti ?? toMbti(existing?.adaptive_mbti) ?? "INTJ";
+  const existingMbti = toMbti(existing?.adaptive_mbti);
+  const mbti = input.adaptive_mbti ?? existingMbti ?? "INTJ";
   const preset = MBTI_PRESETS[mbti];
-  const strength = input.adaptive_persona_strength ?? preset.strength;
-  const empathy = input.adaptive_empathy ?? preset.empathy;
-  const expressiveness = input.adaptive_expressiveness ?? preset.expressiveness;
-  const verbosity = input.adaptive_verbosity ?? preset.verbosity;
+  // Omitted sliders keep their tuned values; they only fall back to the
+  // preset when the type changes or the agent is new. Otherwise every
+  // partial update (approved proposals, tool edits) reset them.
+  const keepTuned = existing !== null && existing !== undefined && mbti === existingMbti;
+  const strength = input.adaptive_persona_strength ?? (keepTuned ? existing.adaptive_persona_strength : preset.strength);
+  const empathy = input.adaptive_empathy ?? (keepTuned ? existing.adaptive_empathy : preset.empathy);
+  const expressiveness = input.adaptive_expressiveness ?? (keepTuned ? existing.adaptive_expressiveness : preset.expressiveness);
+  const verbosity = input.adaptive_verbosity ?? (keepTuned ? existing.adaptive_verbosity : preset.verbosity);
   if (input.is_default) db.prepare("UPDATE agent_configs SET is_default=0").run();
   // harness_id: explicit `undefined` means "keep existing"; explicit `null`
   // means "use the global default". Empty string is normalised to null too,

package/lib/stores/bridges.test.ts

@@ -0,0 +1,81 @@
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const tmpRoot = mkdtempSync(join(tmpdir(), "jarela-test-bridges-"));
+process.env.JARELA_DB_DIR = tmpRoot;
+
+const store = await import("./bridges");
+const { getDb } = await import("@/lib/db");
+
+afterAll(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* */ }
+});
+
+describe("bridges store", () => {
+  beforeEach(() => {
+    const db = getDb();
+    db.exec("DELETE FROM bridge_routes; DELETE FROM bridge_ignores; DELETE FROM bridges;");
+  });
+
+  it("keeps each chat's watermark monotonic and isolated from other chats", () => {
+    const b = store.createBridge({ kind: "whatsapp", name: "WA" });
+    store.createRoute({ bridge_id: b.id, remote_jid: "a@s.whatsapp.net", agent_id: "agent-1" });
+    store.createRoute({ bridge_id: b.id, remote_jid: "b@s.whatsapp.net", agent_id: "agent-2" });
+
+    store.bumpRouteLastSeenTs(b.id, "a@s.whatsapp.net", 2_000);
+    store.bumpRouteLastSeenTs(b.id, "a@s.whatsapp.net", 1_000);
+    store.bumpRouteLastSeenTs(b.id, "a@s.whatsapp.net", Number.NaN);
+    store.bumpRouteLastSeenTs(b.id, "a@s.whatsapp.net", -5);
+    store.bumpRouteLastSeenTs(b.id, "unrouted@s.whatsapp.net", 9_000);
+
+    expect(store.getRouteLastSeenTsMap(b.id)).toEqual(new Map([["a@s.whatsapp.net", 2_000]]));
+  });
+
+  it("scopes watermarks to their bridge", () => {
+    const one = store.createBridge({ kind: "whatsapp", name: "one" });
+    const two = store.createBridge({ kind: "whatsapp", name: "two" });
+    store.createRoute({ bridge_id: one.id, remote_jid: "x@s.whatsapp.net", agent_id: "agent-3" });
+    store.createRoute({ bridge_id: two.id, remote_jid: "x@s.whatsapp.net", agent_id: "agent-4" });
+    store.bumpRouteLastSeenTs(one.id, "x@s.whatsapp.net", 5_000);
+    expect(store.getRouteLastSeenTsMap(two.id).size).toBe(0);
+  });
+
+  it("deletes a bridge together with its routes and ignores", () => {
+    const b = store.createBridge({ kind: "whatsapp", name: "WA" });
+    const route = store.createRoute({ bridge_id: b.id, remote_jid: "*", agent_id: "agent-5" });
+    store.addIgnore({ bridge_id: b.id, remote_jid: "spam@s.whatsapp.net" });
+
+    expect(store.deleteBridge(b.id)).toBe(true);
+    expect(store.getRoute(route.id)).toBeNull();
+    expect(store.isIgnored(b.id, "spam@s.whatsapp.net")).toBe(false);
+    expect(store.deleteBridge(b.id)).toBe(false);
+  });
+
+  it("rejects a duplicate ignore entry and removes only the matching chat", () => {
+    const b = store.createBridge({ kind: "whatsapp", name: "WA" });
+    store.addIgnore({ bridge_id: b.id, remote_jid: "a@s.whatsapp.net", label: "A" });
+    store.addIgnore({ bridge_id: b.id, remote_jid: "b@s.whatsapp.net" });
+    expect(() => store.addIgnore({ bridge_id: b.id, remote_jid: "a@s.whatsapp.net" })).toThrow(/UNIQUE/);
+
+    expect(store.removeIgnore(b.id, "a@s.whatsapp.net")).toBe(true);
+    expect(store.removeIgnore(b.id, "a@s.whatsapp.net")).toBe(false);
+    expect(store.listIgnores(b.id).map((i) => i.remote_jid)).toEqual(["b@s.whatsapp.net"]);
+  });
+
+  it("applies partial updates without clobbering nullable fields", () => {
+    const b = store.createBridge({ kind: "whatsapp", name: "WA" });
+    store.updateBridge(b.id, { last_error: "boom", paired_id: "me" });
+    const updated = store.updateBridge(b.id, { status: "connected", forward_group_profile_updates: 0 });
+    expect(updated).toMatchObject({ last_error: "boom", paired_id: "me", status: "connected", forward_group_profile_updates: 0 });
+    expect(store.updateBridge(b.id, { last_error: null })?.last_error).toBeNull();
+    expect(store.getBridge(b.id)).toMatchObject({ last_error: null, paired_id: "me", forward_group_participants_updates: 1 });
+    expect(store.updateBridge("missing", { name: "x" })).toBeNull();
+
+    const route = store.createRoute({ bridge_id: b.id, remote_jid: "a@s.whatsapp.net", agent_id: "agent-6", label: "A", silent_mode: true });
+    expect(store.updateRoute(route.id, { respond_to: "user" })).toMatchObject({ label: "A", silent_mode: 1, respond_to: "user" });
+    expect(store.updateRoute(route.id, { silent_mode: false, label: null })).toMatchObject({ label: null, silent_mode: 0 });
+    expect(store.findRoute(b.id, "a@s.whatsapp.net")).toMatchObject({ silent_mode: 0, respond_to: "user", label: null });
+  });
+});

package/lib/stores/bridges.ts

@@ -263,14 +263,15 @@ export function bumpRouteLastSeenTs(bridgeId: string, remoteJid: string, ts: num
     .run(ts, bridgeId, remoteJid, ts);
 }
 
-// Snapshot the highest watermark across every route on a bridge. The
-// adapter uses this on reconnect to short-circuit very-old appends before
-// it has loaded individual route rows.
-export function getMaxRouteLastSeenTs(bridgeId: string): number {
-  const row = getDb()
-    .prepare("SELECT MAX(last_seen_ts) AS m FROM bridge_routes WHERE bridge_id=?")
-    .get(bridgeId) as { m: number | null } | undefined;
-  return row?.m ?? 0;
+// Per-chat watermarks for every explicitly routed chat on a bridge, loaded
+// once per upsert batch. Each chat is gated only by its own progress: a
+// bridge-wide maximum would drop chat B's offline backlog as soon as a newer
+// message from chat A had been delivered.
+export function getRouteLastSeenTsMap(bridgeId: string): Map<string, number> {
+  const rows = getDb()
+    .prepare("SELECT remote_jid, last_seen_ts FROM bridge_routes WHERE bridge_id=? AND last_seen_ts IS NOT NULL")
+    .all(bridgeId) as Array<{ remote_jid: string; last_seen_ts: number }>;
+  return new Map(rows.map((r) => [r.remote_jid, r.last_seen_ts]));
 }
 
 // ---------------------------------------------------------------------------

package/lib/stores/proxy-config.test.ts

@@ -0,0 +1,120 @@
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const tmpRoot = mkdtempSync(join(tmpdir(), "jarela-test-proxy-config-"));
+process.env.JARELA_DB_DIR = tmpRoot;
+
+const store = await import("./proxy-config");
+const { getDb } = await import("@/lib/db");
+const { SECRET_MASK } = await import("./integrations");
+
+afterAll(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* */ }
+});
+
+const PEM = "-----BEGIN CERTIFICATE-----\nMIIBfake\n-----END CERTIFICATE-----\n";
+
+function storedPasswordColumn(): string | null {
+  const row = getDb().prepare("SELECT password FROM proxy_config WHERE id = 1").get() as { password: string | null } | undefined;
+  return row?.password ?? null;
+}
+
+describe("proxy-config store", () => {
+  beforeEach(() => {
+    getDb().exec("DELETE FROM proxy_config");
+  });
+
+  it("returns the default off status before anything is saved", () => {
+    expect(store.getProxyConfigStatus()).toMatchObject({ mode: "off", scheme: "http", host: null, password: null });
+    expect(store.getProxyConfigRaw()).toBeNull();
+    expect(store.deleteProxyConfig()).toBe(false);
+  });
+
+  it("encrypts the password at rest, masks it in status and decrypts it for the dispatcher", () => {
+    const saved = store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, username: "u", password: "p@ss:word" });
+    expect(saved).toMatchObject({ mode: "manual", host: "proxy.corp", port: 3128, password: SECRET_MASK });
+    expect(storedPasswordColumn()).not.toContain("p@ss:word");
+    expect(store.getProxyConfigRaw()?.password).toBe("p@ss:word");
+  });
+
+  it("keeps the existing password when the UI echoes the mask back, without re-encrypting it", () => {
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, username: "u", password: "secret" });
+    const before = storedPasswordColumn();
+    store.saveProxyConfig({ mode: "manual", host: "proxy2.corp", port: 8080, username: "u", password: SECRET_MASK });
+    expect(storedPasswordColumn()).toBe(before);
+    expect(store.getProxyConfigRaw()).toMatchObject({ host: "proxy2.corp", port: 8080, password: "secret" });
+  });
+
+  it("never stores the mask itself as a password when none existed", () => {
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, password: SECRET_MASK });
+    expect(store.getProxyConfigRaw()?.password).toBeNull();
+    expect(store.getProxyConfigStatus().password).toBeNull();
+  });
+
+  it("clears the password when an empty string or null is sent", () => {
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, password: "secret" });
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, password: "" });
+    expect(store.getProxyConfigRaw()?.password).toBeNull();
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, password: "secret" });
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, password: null });
+    expect(store.getProxyConfigRaw()?.password).toBeNull();
+  });
+
+  it("trims host, username and no_proxy and stores blanks as null", () => {
+    store.saveProxyConfig({ mode: "manual", host: "  proxy.corp  ", port: 3128, username: "   ", no_proxy: "  " });
+    expect(store.getProxyConfigRaw()).toMatchObject({ host: "proxy.corp", username: null, no_proxy: null });
+  });
+
+  it.each([
+    ["a URL with a scheme", "http://proxy.corp"],
+    ["a host with a port", "proxy.corp:8080"],
+    ["a hex-only host with a port", "dead.beef:3128"],
+    ["a host with a path", "proxy.corp/pac"],
+    ["a host with credentials", "user:pw@proxy.corp"],
+    ["a host with spaces", "proxy corp"],
+  ])("rejects %s in manual mode instead of building a broken proxy URL", (_label, host) => {
+    const result = store.saveProxyConfig({ mode: "manual", host, port: 3128 });
+    expect(result).toHaveProperty("error");
+    expect((result as { error: string }).error).toMatch(/host/i);
+    expect(store.getProxyConfigRaw()).toBeNull();
+  });
+
+  it.each([
+    ["fd00::1", "fd00::1"],
+    ["[fd00::1]", "fd00::1"],
+    ["10.0.0.5", "10.0.0.5"],
+    ["proxy-1.corp.example", "proxy-1.corp.example"],
+  ])("accepts host %s and stores it as %s", (input, stored) => {
+    const result = store.saveProxyConfig({ mode: "manual", host: input, port: 3128 });
+    expect(result).not.toHaveProperty("error");
+    expect(store.getProxyConfigRaw()?.host).toBe(stored);
+  });
+
+  it.each([0, -1, 65536, 3128.5, Number.NaN, Number.POSITIVE_INFINITY])("rejects port %s", (port) => {
+    expect(store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port })).toHaveProperty("error");
+  });
+
+  it("requires host and port only in manual mode", () => {
+    expect(store.saveProxyConfig({ mode: "manual", port: 3128 })).toHaveProperty("error");
+    expect(store.saveProxyConfig({ mode: "manual", host: "proxy.corp" })).toHaveProperty("error");
+    expect(store.saveProxyConfig({ mode: "system" })).toMatchObject({ mode: "system" });
+    expect(store.saveProxyConfig({ mode: "off" })).toMatchObject({ mode: "off" });
+  });
+
+  it("rejects an invalid mode and a non-PEM CA bundle, and clears a blank bundle", () => {
+    expect(store.saveProxyConfig({ mode: "auto" as never })).toHaveProperty("error");
+    expect(store.saveProxyConfig({ mode: "off", ca_bundle: "not a cert" })).toHaveProperty("error");
+    store.saveProxyConfig({ mode: "off", ca_bundle: PEM });
+    expect(store.getProxyConfigRaw()?.ca_bundle).toBe(PEM);
+    store.saveProxyConfig({ mode: "off", ca_bundle: "   " });
+    expect(store.getProxyConfigRaw()?.ca_bundle).toBeNull();
+  });
+
+  it("normalises an unknown persisted scheme to http", () => {
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128 });
+    getDb().prepare("UPDATE proxy_config SET scheme = 'socks5' WHERE id = 1").run();
+    expect(store.getProxyConfigRaw()).toMatchObject({ mode: "manual", scheme: "http" });
+  });
+});

package/lib/stores/proxy-config.ts

@@ -15,6 +15,7 @@
 // existing password" so the UI can echo back the masked form without
 // blanking the secret.
 
+import { isIPv6 } from "node:net";
 import { getDb } from "@/lib/db";
 import { decryptIfNeeded, encrypt } from "@/lib/crypto/envelope";
 import { SECRET_MASK } from "@/lib/stores/integrations";
@@ -122,11 +123,18 @@ export function saveProxyConfig(input: ProxyConfigInput): ProxyConfigStatus | {
   const scheme: ProxyScheme = input.scheme === "https" ? "https" : "http";
 
   // Manual mode requires host + port. system / off don't.
+  let host = nullable(input.host);
   if (input.mode === "manual") {
-    if (!input.host || !input.host.trim()) return { error: "host is required in manual mode" };
-    if (input.port == null || !Number.isFinite(input.port) || input.port <= 0 || input.port > 65535) {
-      return { error: "port must be between 1 and 65535" };
+    if (!host) return { error: "host is required in manual mode" };
+    const normalisedHost = normaliseProxyHost(host);
+    if (!normalisedHost) {
+      return { error: "host must be a hostname or IP address, without scheme, port, path or credentials" };
     }
+    host = normalisedHost;
+    if (input.port == null) return { error: "port must be between 1 and 65535" };
+  }
+  if (input.port != null && (!Number.isInteger(input.port) || input.port <= 0 || input.port > 65535)) {
+    return { error: "port must be between 1 and 65535" };
   }
 
   // CA bundle: empty/null clears; non-empty must look like PEM.
@@ -167,7 +175,7 @@ export function saveProxyConfig(input: ProxyConfigInput): ProxyConfigStatus | {
   ).run(
     input.mode,
     scheme,
-    nullable(input.host),
+    host,
     input.port ?? null,
     nullable(input.username),
     storedPassword,
@@ -207,6 +215,16 @@ function normaliseScheme(s: string | null | undefined): ProxyScheme {
   return s === "https" ? "https" : "http";
 }
 
+// The dispatcher builds `${scheme}://${auth}${host}:${port}`, so a pasted URL
+// or host:port would produce an unusable proxy URL. IPv6 is stored unbracketed;
+// the dispatcher adds the brackets.
+function normaliseProxyHost(host: string): string | null {
+  const unbracketed = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  if (/^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/.test(unbracketed)) return unbracketed;
+  if (isIPv6(unbracketed)) return unbracketed;
+  return null;
+}
+
 function nullable(v: string | null | undefined): string | null {
   if (v == null) return null;
   const trimmed = v.trim();

package/lib/stores/threads.test.ts

@@ -692,6 +692,15 @@ describe("thread channel summaries (ADR-0044)", () => {
     expect(getThreadChannelSummary(t.thread_id, "watcher")?.summary).toBe("watcher recap");
     expect(getThreadChannelSummary(t.thread_id, "bridge")?.summary).toBe("bridge recap");
   });
+
+  it("round-trips stored channel topics and clears them when a later commit omits them", () => {
+    const t = createThread("agent-chsum-4");
+    const topics = JSON.stringify([{ title: "Nightly backup", start_seq: 1, end_seq: 2, recap: "r", facts: [], message_count: 2 }]);
+    commitThreadChannelSummary(t.thread_id, "scheduled_task", { summary: "recap", summaryBefore: null, summaryBeforeSeq: 3, topics });
+    expect(getThreadChannelSummary(t.thread_id, "scheduled_task")?.topics).toBe(topics);
+    commitThreadChannelSummary(t.thread_id, "scheduled_task", { summary: "fallback", summaryBefore: null, summaryBeforeSeq: 4 });
+    expect(getThreadChannelSummary(t.thread_id, "scheduled_task")?.topics).toBeNull();
+  });
 });
 
 describe("getRecentlyUsedToolNames", () => {

package/lib/stores/threads.ts

@@ -157,11 +157,15 @@ export function getThreadMessageBySeq(thread_id: string, seq: number): MessageRo
   return (getDb().prepare(MSG_COLS_SQL + " WHERE thread_id=? AND rowid=?").get(thread_id, seq) as unknown as MessageRow | undefined) ?? null;
 }
 
-export function countThreadMessagesFromSeq(thread_id: string, seq: number): number {
-  const row = getDb().prepare("SELECT COUNT(*) AS n FROM messages WHERE thread_id=? AND rowid>=?").get(thread_id, seq) as { n: number } | undefined;
+
+// Rows that size compaction can prune: automation-channel rows are kept
+// (see pruneThreadMessages), so they must not count toward its trigger.
+export function countForegroundThreadMessages(thread_id: string, fromSeq = 0): number {
+  const row = getDb()
+    .prepare("SELECT COUNT(*) AS n FROM messages WHERE thread_id=? AND rowid>=? AND " + foregroundCategoryGuardSql())
+    .get(thread_id, fromSeq, ...FOREGROUND_EXCLUDED_CATEGORIES) as { n: number } | undefined;
   return row?.n ?? 0;
 }
-
 export function isValidThreadContextCursor(thread_id: string, seq: number): boolean {
   if (getThreadMessageBySeq(thread_id, seq)) return true;
   return getThread(thread_id)?.hot_since_seq === seq;
@@ -671,6 +675,8 @@ export interface ThreadChannelSummaryRow {
   summary_before: string | null;
   summary_before_seq: number | null;
   computed_at: string;
+  /** JSON array of SummaryTopicSegment, or null for summaries without topics. */
+  topics: string | null;
 }
 
 // ADR-0044 — one cached warm summary per (thread, automation channel),
@@ -682,27 +688,34 @@ export interface ThreadChannelSummaryRow {
 // hot/warm boundary move, there's no cross-field invariant to protect here.
 export function getThreadChannelSummary(threadId: string, channel: string): ThreadChannelSummaryRow | null {
   return (getDb()
-    .prepare("SELECT thread_id, channel, summary, summary_before, summary_before_seq, computed_at FROM thread_channel_summaries WHERE thread_id=? AND channel=?")
+    .prepare("SELECT thread_id, channel, summary, summary_before, summary_before_seq, computed_at, topics FROM thread_channel_summaries WHERE thread_id=? AND channel=?")
     .get(threadId, channel) as ThreadChannelSummaryRow | undefined) ?? null;
 }
 
+export function listThreadChannelSummaries(threadId: string): ThreadChannelSummaryRow[] {
+  return getDb()
+    .prepare("SELECT thread_id, channel, summary, summary_before, summary_before_seq, computed_at, topics FROM thread_channel_summaries WHERE thread_id=?")
+    .all(threadId) as unknown as ThreadChannelSummaryRow[];
+}
+
 export function commitThreadChannelSummary(
   threadId: string,
   channel: string,
-  input: { summary: string; summaryBefore: string | null; summaryBeforeSeq?: number | null },
+  input: { summary: string; summaryBefore: string | null; summaryBeforeSeq?: number | null; topics?: string | null },
 ): void {
   if (input.summaryBefore !== null && input.summaryBeforeSeq == null) {
     throw new Error("summaryBeforeSeq is required for a boundary summary");
   }
   getDb()
     .prepare(
-      `INSERT INTO thread_channel_summaries (thread_id, channel, summary, summary_before, summary_before_seq, computed_at)
-       VALUES (?, ?, ?, ?, ?, ?)
+      `INSERT INTO thread_channel_summaries (thread_id, channel, summary, summary_before, summary_before_seq, computed_at, topics)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(thread_id, channel) DO UPDATE SET
          summary=excluded.summary, summary_before=excluded.summary_before,
-         summary_before_seq=excluded.summary_before_seq, computed_at=excluded.computed_at`,
+         summary_before_seq=excluded.summary_before_seq, computed_at=excluded.computed_at,
+         topics=excluded.topics`,
     )
-    .run(threadId, channel, input.summary, input.summaryBefore, input.summaryBeforeSeq ?? null, now());
+    .run(threadId, channel, input.summary, input.summaryBefore, input.summaryBeforeSeq ?? null, now(), input.topics ?? null);
 }
 
 export function touchThread(thread_id: string, firstMsg?: string): void {
@@ -724,11 +737,11 @@ export function setThreadContextPin(thread_id: string, hot_since: string | null,
     .run(hot_since, hot_since === null ? null : hot_since_seq!, thread_id);
 }
 
-// Called by moveThreadContextBoundary whenever the user explicitly moves the
-// boundary (drag, or manual /compact) — never by the auto-detector's own
-// commit path, which calls setThreadContextPin directly. `untilMessageCount`
-// is a one-time write; the read side (lib/agents/run-thread.ts) just compares
-// against it, no per-turn write needed.
+// Armed by moveThreadContextBoundary whenever the user explicitly moves the
+// boundary (drag, or manual /compact), and by the auto-detector's hot-turn
+// cooldown when a compaction pass ends without a commit (a commit writes the
+// lock in the same transaction). `untilMessageCount` is a one-time write; the
+// read side (lib/agents/run-thread.ts) just compares against it.
 export function setAutoBoundaryLock(thread_id: string, untilMessageCount: number): void {
   getDb()
     .prepare("UPDATE threads SET auto_boundary_locked_until_msg_count=? WHERE thread_id=?")
@@ -746,7 +759,7 @@ export interface ThreadWarmContextCommit {
   /** Reject the commit if another compactor refreshed the same boundary. */
   expectedWarmSummary?: string | null;
   autoBoundaryLockedUntilMessageCount?: number;
-  channelSummaries?: Array<{ channel: string; summary: string }>;
+  channelSummaries?: Array<{ channel: string; summary: string; topics?: string | null }>;
 }
 
 // A warm recap is only valid for the exact boundary it replaced. Commit both
@@ -790,14 +803,15 @@ export function commitThreadWarmContext(
       thread_id,
     );
     const upsertChannel = db.prepare(
-      `INSERT INTO thread_channel_summaries (thread_id, channel, summary, summary_before, summary_before_seq, computed_at)
-       VALUES (?, ?, ?, ?, ?, ?)
+      `INSERT INTO thread_channel_summaries (thread_id, channel, summary, summary_before, summary_before_seq, computed_at, topics)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(thread_id, channel) DO UPDATE SET
          summary=excluded.summary, summary_before=excluded.summary_before,
-         summary_before_seq=excluded.summary_before_seq, computed_at=excluded.computed_at`,
+         summary_before_seq=excluded.summary_before_seq, computed_at=excluded.computed_at,
+         topics=excluded.topics`,
     );
     for (const channelSummary of input.channelSummaries ?? []) {
-      upsertChannel.run(thread_id, channelSummary.channel, channelSummary.summary, input.hotSince, hotSinceSeq, now());
+      upsertChannel.run(thread_id, channelSummary.channel, channelSummary.summary, input.hotSince, hotSinceSeq, now(), channelSummary.topics ?? null);
     }
     db.exec("COMMIT");
     return getThread(thread_id);

package/lib/stores/version-adoption.test.ts

@@ -13,6 +13,7 @@ const {
   getVersionAdoptionState,
   recordVersionAdoptionWorkflowProgress,
   updateVersionAdoptionState,
+  VersionAdoptionRequestError,
 } = await import("@/lib/stores/version-adoption");
 
 afterAll(() => {
@@ -132,6 +133,7 @@ describe("version adoption state", () => {
     expect(running.checklist[0].status).toBe("done");
     expect(running.checklist[1].id).toBe("build-todo-list");
     expect(running.checklist[1].status).toBe("checking");
+    expect(running.checklist[1].attempts).toBe(1);
   });
 
   it("records item-by-item adoption progress through the workflow helper", () => {
@@ -174,6 +176,100 @@ describe("version adoption state", () => {
     });
   });
 
+  it("builds adaptation items and prompt hints from bundled release changesets", () => {
+    upsertAgentConfig({
+      id: "default-agent",
+      name: "Assistant",
+      identity: "helper",
+      instructions: "Be useful.",
+      tools: [],
+      is_default: true,
+    });
+    updateVersionAdoptionState("mark_done", "2.0.5");
+
+    const pending = getVersionAdoptionState("2.2.1");
+    expect(pending.previous_version).toBe("2.0.5");
+    expect(pending.checklist[0]).toMatchObject({ id: "fetch-changes", status: "done" });
+    expect(pending.checklist[0].validation_evidence).toContain("bundled release changesets for 2.1.0, 2.2.0, 2.2.1");
+    expect(pending.stale_prompt_risks).toEqual(expect.arrayContaining([
+      "Adapt agent settings to tool changes",
+      "Adapt scheduled task and watcher prompts",
+      "Adapt agent instructions and skills",
+    ]));
+
+    const running = updateVersionAdoptionState("start", "2.2.1");
+    const prompt = running.adoption_prompt ?? "";
+    expect(prompt).toContain("read deterministically by the system from the bundled release changesets");
+    expect(prompt).toContain("Release changesets — model-facing prompt and tool description/schema changes from 2.0.5 to 2.2.1:");
+    expect(prompt).toContain("tool `workflow_progress`");
+    expect(prompt).toContain("params added: validation_evidence");
+    expect(prompt).toContain("apply an edit only after the user approves it");
+    expect(prompt).not.toContain("partial");
+
+    const adoption = recordVersionAdoptionWorkflowProgress({
+      item_id: "build-todo-list",
+      status: "done",
+      validation_evidence: "Every changed prompt and tool is covered by an adapt item.",
+    }, "2.2.1");
+    const ids = adoption.state.checklist.map((item) => item.id);
+    expect(ids).toEqual(["adapt-settings", "adapt-task-prompts", "adapt-instructions-skills"]);
+    for (const item of adoption.state.checklist) {
+      expect(item.input.trim()).not.toBe("");
+      expect(item.output.trim()).not.toBe("");
+      expect(item.validation).toMatch(/re-(read|list)/);
+    }
+    expect(adoption.state.checklist[0].affected_files).toContain("tool:workflow_progress");
+  });
+
+  it("retries a single adoption step with a focused prompt and keeps other steps", () => {
+    upsertAgentConfig({
+      id: "default-agent",
+      name: "Assistant",
+      identity: "helper",
+      instructions: "Be useful.",
+      tools: [],
+      is_default: true,
+    });
+    updateVersionAdoptionState("mark_done", "2.0.5");
+    updateVersionAdoptionState("start", "2.2.1");
+    recordVersionAdoptionWorkflowProgress({
+      item_id: "build-todo-list",
+      status: "done",
+      validation_evidence: "Every changed prompt and tool is covered.",
+    }, "2.2.1");
+    recordVersionAdoptionWorkflowProgress({
+      phase: "adoption",
+      item_id: "adapt-settings",
+      status: "done",
+      validation_evidence: "Re-read agent settings; no removed tools referenced.",
+    }, "2.2.1");
+    recordVersionAdoptionWorkflowProgress({
+      phase: "adoption",
+      item_id: "adapt-task-prompts",
+      status: "needs_attention",
+    }, "2.2.1");
+
+    const retried = updateVersionAdoptionState("retry", "2.2.1", "adapt-settings");
+    expect(retried.status).toBe("running");
+    expect(retried.phase).toBe("adoption");
+    const settings = retried.checklist.find((item) => item.id === "adapt-settings");
+    expect(settings?.status).toBe("checking");
+    expect(settings?.attempts).toBe(1);
+    expect(settings?.validation_evidence).toBeUndefined();
+    expect(retried.checklist.find((item) => item.id === "adapt-task-prompts")?.status).toBe("needs_attention");
+
+    const prompt = retried.adoption_prompt ?? "";
+    expect(prompt).toContain("Retry one Jarela version adoption step for upgrade from 2.0.5 to 2.2.1");
+    expect(prompt).toContain("Step: adapt-settings");
+    expect(prompt).toContain('item_id: "adapt-settings"');
+    expect(prompt).toContain('phase: "adoption"');
+    expect(prompt).toContain("Release changesets:");
+    expect(prompt).not.toContain("Phase 1 — impact radius analysis");
+
+    expect(() => updateVersionAdoptionState("retry", "2.2.1", "missing-step")).toThrow(VersionAdoptionRequestError);
+    expect(() => updateVersionAdoptionState("retry", "2.2.1", "fetch-changes")).toThrow(VersionAdoptionRequestError);
+  });
+
   it("blocks adoption until a default agent exists", () => {
     const state = getVersionAdoptionState("1.29.5");
     expect(state.status).toBe("blocked_no_default_agent");