@circuitwall/jarela 2.2.1 → 2.4.0

package/lib/agents/prompt-registry.ts

@@ -16,7 +16,9 @@ import { DESIGN_QA_PROMPT } from "@/lib/tools/delegation/claude-delegate";
 import { buildSharedToolCatalogContext } from "@/lib/agents/prepare/system-prompt";
 import { BUILTIN_HARNESSES } from "@/lib/agents/harness/presets";
 import { SYSTEM_SIGNAL_WAKE_PROMPT } from "@/lib/lifecycle/system-signals";
-import { buildConversationSummaryMessages } from "@/lib/agents/conversation-summary";
+import { buildConversationSummaryMessages, type SummaryTopicSegment } from "@/lib/agents/conversation-summary";
+import { buildTopicGroupingMessages, buildTopicRecapMessages } from "@/lib/agents/compaction-pipeline";
+import type { ProviderMessage } from "@/lib/providers/types";
 
 export interface StaticPrompt {
   id: string;
@@ -36,6 +38,24 @@ export function listStaticPrompts(): StaticPrompt[] {
   const conversationSummary = buildConversationSummaryMessages(
     "[seq=42] [2026-10-09T10:00:00.000Z] User: Example transcript row.",
   ).map((message) => `${message.role.toUpperCase()}\n${typeof message.content === "string" ? message.content : JSON.stringify(message.content)}`).join("\n\n");
+  const renderMessages = (messages: ProviderMessage[]) => messages
+    .map((message) => `${message.role.toUpperCase()}\n${typeof message.content === "string" ? message.content : JSON.stringify(message.content)}`)
+    .join("\n\n");
+  const sampleTopic: SummaryTopicSegment = {
+    title: "Example earlier topic",
+    start_seq: 40,
+    end_seq: 44,
+    start_at: "2026-10-09T10:00:00.000Z",
+    end_at: "2026-10-09T10:05:00.000Z",
+    recap: "Example recap of the earlier topic.",
+    facts: [{ subject: "Example preference", content: "The user prefers examples.", tags: [], confidence: "explicit", key: "facts/example-preference" }],
+    message_count: 4,
+  };
+  const sampleNewMessages = "[seq=50] [2026-10-09T11:00:00.000Z] User: Example newer message.\n\n[seq=51] [2026-10-09T11:00:05.000Z] Assistant: Example reply.";
+  const compactionGroup = renderMessages(buildTopicGroupingMessages(sampleNewMessages, [sampleTopic]));
+  const compactionRecap = renderMessages(buildTopicRecapMessages({ title: sampleTopic.title, continues: "t1", seqs: [50, 51] }, sampleTopic, sampleNewMessages));
+  const channelGroup = renderMessages(buildTopicGroupingMessages(sampleNewMessages, [sampleTopic], "scheduled_task"));
+  const channelRecap = renderMessages(buildTopicRecapMessages({ title: sampleTopic.title, continues: "t1", seqs: [50, 51] }, sampleTopic, sampleNewMessages, "scheduled_task"));
   const prompts: StaticPrompt[] = [
     {
       id: "agent.system-signal-wakeup",
@@ -55,6 +75,30 @@ export function listStaticPrompts(): StaticPrompt[] {
       purpose: "Compress warm chat context while preserving source seq boundaries for topic alignment.",
       text: conversationSummary,
     },
+    {
+      id: "agent.compaction-group",
+      source: "lib/agents/compaction-pipeline.ts",
+      purpose: "Compaction step 1: group newly aged-out messages into topics, each new or continuing a stored warm topic.",
+      text: compactionGroup,
+    },
+    {
+      id: "agent.compaction-topic-recap",
+      source: "lib/agents/compaction-pipeline.ts",
+      purpose: "Compaction step 2: recap one topic, newest detail first, merging its stored recap and listing durable facts.",
+      text: compactionRecap,
+    },
+    {
+      id: "agent.compaction-group-automation",
+      source: "lib/agents/compaction-pipeline.ts",
+      purpose: "Compaction step 1 for an automation channel (scheduled_task shown; watcher and bridge differ only in wording).",
+      text: channelGroup,
+    },
+    {
+      id: "agent.compaction-topic-recap-automation",
+      source: "lib/agents/compaction-pipeline.ts",
+      purpose: "Compaction step 2 for an automation channel (scheduled_task shown); recap focuses on runs, outcomes and failures.",
+      text: channelRecap,
+    },
     {
       id: "audit.citation-checker",
       source: "lib/agents/citation-checker.ts",

package/lib/agents/prompt-variants.ts

@@ -0,0 +1,146 @@
+/**
+ * Deterministic agent system prompt variants used to verify prompts
+ * (prompt-registry.test.ts) and to snapshot the prompt surface for release
+ * changesets (lib/lifecycle/surface-collect.ts). Callers must set
+ * JARELA_DB_DIR to a scratch directory before importing this module.
+ */
+import { buildSystemPrompt } from "./prepare/system-prompt";
+import { getUsageStrategyProfile } from "./usage-strategy";
+import { getAllToolCatalogAsync, applyAgentPermissionsToCatalog, markProxyOnlyTools } from "@/lib/tools";
+import type { AgentConfigRow } from "@/lib/stores/agent-configs";
+import type { ContextBudget } from "@/lib/agents/context-budget";
+export const budget: ContextBudget = {
+  contextWindowTokens: 200000,
+  outputReserveTokens: 8000,
+  inputBudgetTokens: 120000,
+  overheadTokens: 4000,
+  tierPriority: ["hot", "warm", "facts"],
+  tierBudgets: { hot: 60000, warm: 40000, facts: 20000 },
+};
+
+export function agentCfg(overrides: Partial<AgentConfigRow> = {}): AgentConfigRow {
+  return {
+    id: "verify-agent",
+    name: "Verify",
+    icon: null,
+    identity: "You are Jarela, a local assistant.",
+    instructions: "Be terse.",
+    tools: "[]",
+    model_config_name: null,
+    is_default: 1,
+    history_limit: 50,
+    history_window_hours: 8,
+    never_reply: 0,
+    adaptive_persona_enabled: 0,
+    adaptive_persona_strength: 0,
+    adaptive_empathy: 50,
+    adaptive_expressiveness: 50,
+    adaptive_verbosity: 50,
+    adaptive_mbti: "INTJ",
+    voice_enabled: 0,
+    voice_model: "",
+    voice_name: "",
+    voice_stt_model: "",
+    voice_auto_speak: 0,
+    display_filters: null,
+    harness_id: null,
+    delegate_targets: null,
+    context_tier_proportions: null,
+    anti_hallucination_mode: null,
+    ...overrides,
+  } as AgentConfigRow;
+}
+
+export interface Variant {
+  id: string;
+  prompt: string;
+  /** Counts derived from the permission map, to check the prompt's own arithmetic. */
+  expected?: { bound: number; proxy: number; denied: number; unavailable: number };
+}
+
+export async function buildVariants(): Promise<Variant[]> {
+  const catalog = await getAllToolCatalogAsync();
+  const pinned = ["gmail_search", "gmail_send_email"];
+  const cfg = agentCfg({ tools: JSON.stringify(pinned) });
+  const permissions = applyAgentPermissionsToCatalog(catalog, cfg);
+  const permitted = permissions.filter((t) => t.permission === "enabled").map((t) => t.name);
+
+  // Bind everything permitted: no proxy_only, the common case today.
+  const allBound = markProxyOnlyTools(permissions, permitted, permitted);
+  // Bind only the self-config tools so the rest becomes proxy_only.
+  const narrowBound = permitted.filter((n) => n === "invoke_tool" || n === "list_tools");
+  const withProxy = markProxyOnlyTools(permissions, narrowBound, permitted);
+  // Simulate a provider cap displacing tools.
+  const withCap = withProxy.map((t) =>
+    t.name === "web_search"
+      ? { ...t, permission: "disabled" as const, permission_reason: "provider_tool_limit" }
+      : t);
+
+  const base = {
+    trimmedMessage: "check my unread mail",
+    budget,
+    recallCtx: "",
+    warmSummaryCtx: "",
+    factsCtx: "",
+    delegateRosterLines: [],
+    runtimeInstanceId: "verify-instance",
+    usageStrategyInstruction: getUsageStrategyProfile("cost_saving").promptInstruction,
+    systemSignals: [{
+      seq: 1, id: "verify-signal", kind: "runtime.restart.completed" as const, schema_version: 1,
+      operation_id: "verify-operation", agent_id: cfg.id, thread_id: "verify-thread",
+      payload: '{"restarted":true,"protected_state_available":true}', created_at: 1,
+    }],
+  };
+
+  const expectedFor = (map: readonly { permission?: string; permission_reason?: string | null }[]) => {
+    const reachable = new Set(["proxy_only", "provider_tool_limit"]);
+    return {
+      bound: map.filter((t) => t.permission === "enabled").length,
+      proxy: map.filter((t) => t.permission_reason && reachable.has(t.permission_reason)).length,
+      denied: map.filter((t) =>
+        t.permission === "disabled" && !(t.permission_reason && reachable.has(t.permission_reason))).length,
+      unavailable: map.filter((t) => t.permission === "unavailable").length,
+    };
+  };
+
+  return [
+    {
+      id: "minimal-agent",
+      prompt: buildSystemPrompt({ ...base, agentCfg: agentCfg(), experienceMode: "essential" }),
+    },
+    {
+      id: "pinned-tools-all-bound",
+      prompt: buildSystemPrompt({
+        ...base,
+        agentCfg: cfg,
+        experienceMode: "full",
+        allowedTools: permitted,
+        toolPermissionMap: allBound,
+      }),
+      expected: expectedFor(allBound),
+    },
+    {
+      id: "proxy-only-and-provider-cap",
+      prompt: buildSystemPrompt({
+        ...base,
+        agentCfg: cfg,
+        experienceMode: "full",
+        allowedTools: narrowBound,
+        toolPermissionMap: withCap,
+      }),
+      expected: expectedFor(withCap),
+    },
+    {
+      id: "delivery-channel",
+      prompt: buildSystemPrompt({
+        ...base,
+        agentCfg: cfg,
+        experienceMode: "full",
+        deliveryChannel: { kind: "whatsapp" },
+        allowedTools: permitted,
+        toolPermissionMap: allBound,
+      }),
+      expected: expectedFor(allBound),
+    },
+  ];
+}

package/lib/agents/proposals.test.ts

@@ -395,3 +395,79 @@ describe("applyAction(update_agent) instructions_append", () => {
     expect(String(result.detail)).toMatch(/one instructions mode only/);
   });
 });
+
+describe("applyAction(update_agent) edge cases", () => {
+  function seedTunedAgent(id: string) {
+    upsertAgentConfig({
+      id,
+      name: id,
+      identity: "test agent",
+      instructions: "be helpful",
+      tools: ["web_search"],
+      hot_turn_limit: 12,
+      adaptive_persona_enabled: true,
+      adaptive_mbti: "ENFP",
+      adaptive_persona_strength: 91,
+      adaptive_empathy: 7,
+      adaptive_expressiveness: 88,
+      adaptive_verbosity: 3,
+      never_reply: true,
+    });
+  }
+
+  it("applies hot_turn_limit, which the propose tool advertises", async () => {
+    seedTunedAgent("agent-hot-turns");
+    const result = await applyAction("update_agent", { agent_id: "agent-hot-turns", hot_turn_limit: 4 });
+    expect(result.ok).toBe(true);
+    expect(getAgentConfig("agent-hot-turns")!.hot_turn_limit).toBe(4);
+  });
+
+  it.each([
+    ["hot_turn_limit", -1],
+    ["hot_turn_limit", 2.5],
+    ["history_limit", 1.5],
+    ["history_limit", -5],
+    ["history_window_hours", -1],
+  ])("rejects %s=%s without writing", async (field, value) => {
+    seedTunedAgent(`agent-bad-${field}`);
+    const before = getAgentConfig(`agent-bad-${field}`)!;
+    const result = await applyAction("update_agent", { agent_id: `agent-bad-${field}`, [field]: value });
+    expect(result.ok).toBe(false);
+    expect(String(result.detail)).toContain(field);
+    expect(getAgentConfig(`agent-bad-${field}`)).toEqual(before);
+  });
+
+  it("keeps settings the proposal did not mention, including tuned persona sliders", async () => {
+    seedTunedAgent("agent-keep");
+    const before = getAgentConfig("agent-keep")!;
+    expect((await applyAction("update_agent", { agent_id: "agent-keep", identity: "renamed" })).ok).toBe(true);
+    const after = getAgentConfig("agent-keep")!;
+    expect(after.identity).toBe("renamed");
+    expect(after).toMatchObject({
+      adaptive_mbti: before.adaptive_mbti,
+      adaptive_persona_strength: 91,
+      adaptive_empathy: 7,
+      adaptive_expressiveness: 88,
+      adaptive_verbosity: 3,
+      never_reply: before.never_reply,
+      hot_turn_limit: 12,
+    });
+  });
+
+  it("keeps tuned persona sliders when only tools change", async () => {
+    seedTunedAgent("agent-keep-tools");
+    expect((await applyAction("update_agent_tools", { agent_id: "agent-keep-tools", tools: ["memory_write"] })).ok).toBe(true);
+    expect(getAgentConfig("agent-keep-tools")).toMatchObject({ adaptive_persona_strength: 91, adaptive_verbosity: 3 });
+  });
+
+  it("drops non-string tool names instead of storing them", async () => {
+    seedTunedAgent("agent-tool-junk");
+    const result = await applyAction("update_agent_tools", {
+      agent_id: "agent-tool-junk",
+      tools: ["memory_write", 42, null, "", " memory_write "],
+      mode: "replace",
+    });
+    expect(result.ok).toBe(true);
+    expect(JSON.parse(getAgentConfig("agent-tool-junk")!.tools)).toEqual(["memory_write"]);
+  });
+});

package/lib/agents/proposals.ts

@@ -130,9 +130,13 @@ function applyUpdateAgentTools(payload: unknown): ApplyResult {
   const before = getAgentTools(existing);
   const mode = p.mode ?? "add";
   if (mode !== "add" && mode !== "replace") return { ok: false, detail: "mode must be add or replace" };
+  const requested = (p.tools as unknown[])
+    .filter((tool): tool is string => typeof tool === "string")
+    .map((tool) => tool.trim())
+    .filter(Boolean);
   const nextTools = mode === "replace"
-    ? [...new Set(p.tools)]
-    : [...new Set([...before, ...p.tools])];
+    ? [...new Set(requested)]
+    : [...new Set([...before, ...requested])];
   upsertAgentConfig({
     id: existing.id,
     name: existing.name,
@@ -154,13 +158,16 @@ function applyUpdateAgent(payload: unknown): ApplyResult {
     instructions_edits?: unknown;
     history_limit?: number;
     history_window_hours?: number;
+    hot_turn_limit?: number;
     warm_summary_limit?: number;
     harness_id?: string | null;
   };
   if (!p.agent_id) return { ok: false, detail: "agent_id required" };
-  if (p.warm_summary_limit !== undefined
-    && (!Number.isInteger(p.warm_summary_limit) || p.warm_summary_limit < 0)) {
-    return { ok: false, detail: "warm_summary_limit must be a nonnegative integer" };
+  for (const field of ["warm_summary_limit", "hot_turn_limit", "history_limit", "history_window_hours"] as const) {
+    const value = p[field];
+    if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
+      return { ok: false, detail: `${field} must be a nonnegative integer` };
+    }
   }
   const editModes = [
     p.instructions !== undefined,
@@ -209,6 +216,7 @@ function applyUpdateAgent(payload: unknown): ApplyResult {
     model_config_name: existing.model_config_name,
     history_limit: p.history_limit ?? existing.history_limit,
     history_window_hours: p.history_window_hours ?? existing.history_window_hours,
+    hot_turn_limit: p.hot_turn_limit,
     warm_summary_limit: p.warm_summary_limit ?? existing.warm_summary_limit,
     harness_id: p.harness_id,
   });

package/lib/agents/run-registry.test.ts

@@ -406,3 +406,25 @@ describe("steering queue (ADR-0080)", () => {
     finishRun(run, "done");
   });
 });
+
+describe("run-registry phase", () => {
+  it("tracks what the run is doing from the broadcast chunks", () => {
+    const tid = `t-phase-${Date.now()}`;
+    const run = startRun(tid, null);
+    expect([run.phase, run.phase_label]).toEqual(["starting", "Starting…"]);
+    broadcast(run, { type: "status", data: { phase: "compacting", label: "Compacting earlier messages…" } });
+    expect([run.phase, run.phase_label]).toEqual(["compacting", "Compacting earlier messages…"]);
+    broadcast(run, { type: "thinking_delta", data: { delta: "hm" } });
+    expect(run.phase).toBe("thinking");
+    broadcast(run, { type: "tool_call", data: { id: "c1", name: "web_search", args: {} } });
+    expect([run.phase, run.phase_label]).toEqual(["tool", "Using web_search…"]);
+    // Reasoning between parallel tool calls must not hide the running tool.
+    broadcast(run, { type: "thinking_delta", data: { delta: "…" } });
+    expect(run.phase).toBe("tool");
+    broadcast(run, { type: "tool_result", data: { id: "c1", result: "ok" } });
+    expect([run.phase, run.phase_label]).toEqual(["thinking", "Thinking…"]);
+    broadcast(run, { type: "text_delta", data: { delta: "Hi" } });
+    expect([run.phase, run.phase_label]).toEqual(["responding", "Responding…"]);
+    finishRun(run, "done");
+  });
+});

package/lib/agents/run-registry.ts

@@ -64,6 +64,11 @@ export interface ActiveRun {
   // by the agent's preModelHook before the next model call, so steering
   // reaches the model together with the tool results it should react to.
   steering: string[];
+  // What the run is doing right now ("preparing", "compacting", "thinking",
+  // "responding", "tool"), with the label the chat shows for it. Lets a
+  // client that is not attached to the stream still report the activity.
+  phase: string;
+  phase_label: string;
 }
 
 const registryState = getOrCreateGlobal("__jarela_active_run_registry", () => ({
@@ -126,6 +131,8 @@ export function startRun(thread_id: string, agent_id: string | null): ActiveRun
     tool_started_at: new Map<string, number>(),
     tool_time_ms_done: 0,
     steering: [],
+    phase: "starting",
+    phase_label: "Starting…",
   };
   runs.set(thread_id, run);
   // Wake any GET subscribers that attached before the run was registered.
@@ -251,6 +258,27 @@ function scheduleMaxWatchdog(run: ActiveRun): void {
   }, fireIn).unref?.();
 }
 
+// Mirrors the labels hooks/useSSE.ts derives from the same chunks.
+function trackPhase(run: ActiveRun, chunk: StreamChunk): void {
+  const data = (chunk.data ?? {}) as { phase?: unknown; label?: unknown; name?: unknown; id?: unknown };
+  const set = (phase: string, label: string) => { run.phase = phase; run.phase_label = label; };
+  if (chunk.type === "status") {
+    const phase = typeof data.phase === "string" && data.phase ? data.phase : run.phase;
+    const label = typeof data.label === "string" && data.label.trim() ? data.label : "Thinking…";
+    set(phase, label);
+  } else if (chunk.type === "text_delta") {
+    set("responding", "Responding…");
+  } else if (chunk.type === "thinking_delta") {
+    if (run.inflight_tools.size === 0) set("thinking", "Thinking…");
+  } else if (chunk.type === "tool_call") {
+    const name = typeof data.name === "string" && data.name ? data.name : "tool";
+    set("tool", `Using ${name}…`);
+  } else if (chunk.type === "tool_result") {
+    const remaining = typeof data.id === "string" ? [...run.inflight_tools].filter((id) => id !== data.id) : [...run.inflight_tools];
+    if (remaining.length === 0) set("thinking", "Thinking…");
+  }
+}
+
 export function broadcast(run: ActiveRun, chunk: StreamChunk): void {
   // Identity-check: a superseded run must not smear trailing chunks onto
   // the replacement entry in the registry.
@@ -263,6 +291,7 @@ export function broadcast(run: ActiveRun, chunk: StreamChunk): void {
   // buffer, don't fan out to subscribers, or the SSE wire would carry
   // meaningless tick events.
   if (chunk.type === "heartbeat") return;
+  trackPhase(run, chunk);
   if (chunk.type === "text_delta") {
     run.final_text += (chunk.data.delta as string) ?? "";
   } else if (chunk.type === "reset_text") {

package/lib/agents/run-thread.auto-boundary.test.ts

@@ -10,6 +10,7 @@ process.env.JARELA_MAX_THREAD_MESSAGES = "4";
 
 const streamWithConfigMock = vi.fn();
 let providerSummary = "AUTO-COMPACT-RECAP";
+let providerCalls = 0;
 
 vi.mock("@/lib/agents/llm", () => ({
   streamWithConfig: (...args: unknown[]) => streamWithConfigMock(...args),
@@ -21,7 +22,7 @@ vi.mock("@/lib/scheduler", () => ({
 
 vi.mock("@/lib/providers", () => ({
   getProvider: () => ({
-    chat: async () => ({
+    chat: async () => (providerCalls++, {
       stream: (async function* () { yield providerSummary; })(),
     }),
   }),
@@ -164,7 +165,6 @@ describe("prepareThreadRun auto context boundary", () => {
       thread_id: thread.thread_id,
       message: "Persist this before the assistant draft.",
       _user_message_persisted: true,
-      _message_count_before_user: persisted.messageCountBefore,
       _idle_ms_before_user: persisted.idleMsBefore,
       context_profile: { include_hot: true, include_warm: false, include_facts: false, include_recall: false },
     });
@@ -271,7 +271,6 @@ describe("prepareThreadRun auto context boundary", () => {
         .run(new Date(Date.UTC(2026, 0, 1, 0, 0, index)).toISOString(), message.msg_id);
     });
     const orderedSeeded = getMessages(thread.thread_id);
-    const messageCountBefore = getThread(thread.thread_id)!.message_count;
     const activePrompt = addMessage(thread.thread_id, "user", "topic 3 question");
     providerSummary = [
       "AUTO-COMPACT-RECAP",
@@ -292,7 +291,6 @@ describe("prepareThreadRun auto context boundary", () => {
       thread_id: thread.thread_id,
       message: "topic 3 question",
       _user_message_persisted: true,
-      _message_count_before_user: messageCountBefore,
       _idle_ms_before_user: null,
       context_profile: {
         include_hot: true,
@@ -374,4 +372,126 @@ describe("prepareThreadRun auto context boundary", () => {
       "continue after retention guard",
     ]);
   });
-});
+
+  async function seedBridgeHeavyAgent(agentId: string, foregroundTurns: number) {
+    upsertModelConfig("default", "openai", "gpt-4o-mini", { api_key: "sk-test" }, true);
+    upsertAgentConfig({
+      id: agentId,
+      name: agentId,
+      identity: "helper",
+      instructions: "Be helpful.",
+      tools: [],
+      model_config_name: null,
+    });
+    const thread = createThread(agentId);
+    const metadata = { bridge_conversation: { key: "wa:chat-1" } };
+    for (let i = 0; i < 20; i++) {
+      addMessage(thread.thread_id, i % 2 === 0 ? "user" : "assistant", `bridge turn ${i}`, undefined, "bridge", metadata);
+    }
+    for (let i = 0; i < foregroundTurns; i++) {
+      addMessage(thread.thread_id, "user", `chat question ${i}`);
+      addMessage(thread.thread_id, "assistant", `chat answer ${i}`);
+    }
+    return { thread, metadata };
+  }
+
+  it("does not start size compaction for bridge rows that compaction can never prune", async () => {
+    const { thread, metadata } = await seedBridgeHeavyAgent("agent-bridge-only", 0);
+    const onCompacting = vi.fn();
+    await prepareThreadRun({
+      thread_id: thread.thread_id,
+      message: "new bridge message",
+      user_category: "bridge",
+      message_metadata: metadata,
+      history_bridge_key: "wa:chat-1",
+      context_profile: { history_scope: "bridge", include_hot: true, include_warm: false, include_facts: false, include_recall: false },
+      _onCompacting: onCompacting,
+    });
+    expect(onCompacting).not.toHaveBeenCalled();
+    expect(getMessages(thread.thread_id).filter((m) => m.category === "bridge")).toHaveLength(21);
+  });
+
+  it("does not report compacting on a short chat just because the bridge history is long", async () => {
+    const { thread } = await seedBridgeHeavyAgent("agent-bridge-mixed", 1);
+    const onCompacting = vi.fn();
+    await prepareThreadRun({
+      thread_id: thread.thread_id,
+      message: "quick chat question",
+      context_profile: { include_hot: true, include_warm: false, include_facts: false, include_recall: false },
+      _onCompacting: onCompacting,
+    });
+    expect(onCompacting).not.toHaveBeenCalled();
+  });
+
+  it("still size-compacts once the chat itself outgrows the cap alongside bridge rows", async () => {
+    const { thread } = await seedBridgeHeavyAgent("agent-bridge-busy-chat", 6);
+    const onCompacting = vi.fn();
+    await prepareThreadRun({
+      thread_id: thread.thread_id,
+      message: "long chat question",
+      context_profile: { include_hot: true, include_warm: false, include_facts: false, include_recall: false },
+      _onCompacting: onCompacting,
+    });
+    expect(onCompacting).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not re-run hot-turn compaction on the very next turn after a commit", async () => {
+    upsertModelConfig("default", "openai", "gpt-4o-mini", { api_key: "sk-test" }, true);
+    upsertAgentConfig({
+      id: "agent-hot-turn-rolling",
+      name: "Rolling Hot Turn Agent",
+      identity: "helper",
+      instructions: "Be helpful.",
+      tools: [],
+      model_config_name: null,
+      history_window_hours: 0,
+      hot_turn_limit: 2,
+    });
+    const thread = createThread("agent-hot-turn-rolling");
+    for (let i = 0; i < 4; i += 1) {
+      addMessage(thread.thread_id, "user", `topic ${i} question`);
+      addMessage(thread.thread_id, "assistant", `topic ${i} answer`);
+    }
+    const seeded = getMessages(thread.thread_id);
+    seeded.forEach((message, index) => {
+      getDb().prepare("UPDATE messages SET created_at=? WHERE msg_id=?")
+        .run(new Date(Date.UTC(2026, 0, 1, 0, 0, index)).toISOString(), message.msg_id);
+    });
+    const rows = getMessages(thread.thread_id);
+    providerSummary = [
+      "AUTO-COMPACT-RECAP",
+      "```jarela-topics",
+      JSON.stringify([{
+        title: "later topic",
+        start_seq: rows[4].seq,
+        end_seq: rows[7].seq,
+        start_at: rows[4].created_at,
+        end_at: rows[7].created_at,
+        recap: "Topics 2 and 3.",
+        facts: [],
+      }]),
+      "```",
+    ].join("\n");
+    const turn = (message: string) => prepareThreadRun({
+      thread_id: thread.thread_id,
+      message,
+      context_profile: { include_hot: true, include_warm: false, include_facts: false, include_recall: false },
+    });
+
+    await turn("topic 4 question");
+    await waitForCondition(() => getThread(thread.thread_id)?.hot_since_seq === rows[4].seq);
+    addMessage(thread.thread_id, "assistant", "topic 4 answer");
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    providerCalls = 0;
+    await turn("topic 5 question");
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(providerCalls).toBe(0);
+    addMessage(thread.thread_id, "assistant", "topic 5 answer");
+
+    // The cooldown is half the turn limit; the turn after it re-evaluates.
+    await turn("topic 6 question");
+    await waitForCondition(() => providerCalls > 0);
+    expect(getThread(thread.thread_id)?.hot_since_seq).toBe(rows[4].seq);
+  });
+});

package/lib/agents/run-thread.retry.test.ts

@@ -918,4 +918,70 @@ describe("prepareThreadRun transient retry", () => {
     expect(chunkTypes).toContain("text_delta");
     expect(collected.assistantContent).toBe("I patched the file to fix the bug.");
   });
-});
+
+  describe("workflow step contract auto-retry", () => {
+    const done = (id: string): StreamChunk => ({
+      type: "done",
+      data: { message_id: id, usage: { input_tokens: 1, output_tokens: 1, source: "estimate" }, provider: "openai", model_id: "gpt-4o-mini", model_config_name: "default" },
+    });
+    const step = (status: string, evidence?: string) => ({
+      id: "run-tests", label: "Run tests", input: "Diff", output: "Results", validation: "Run the suite", status,
+      ...(evidence ? { validation_evidence: evidence } : {}),
+    });
+    const rejectedTurn = (n: number) => chunks(
+      { type: "tool_call", data: { id: `wf-${n}`, name: "workflow_progress", arguments: { workflow_id: "release_check", items: [step("done")] } } },
+      { type: "tool_result", data: { id: `wf-${n}`, name: "workflow_progress", result: JSON.stringify({ ok: false, workflow_id: "release_check", error: "Every completed workflow item requires observed validation_evidence." }) } },
+      { type: "text_delta", data: { delta: `Turn ${n}.` } },
+      done(`done-wf-${n}`),
+    );
+    const setup = async (agentId: string) => {
+      upsertModelConfig("default", "openai", "gpt-4o-mini", { api_key: "sk-test" }, true);
+      upsertAgentConfig({ id: agentId, name: "Workflow Agent", identity: "helper", instructions: "Be helpful.", tools: ["workflow_progress"], model_config_name: null });
+      const thread = createThread(agentId);
+      return prepareThreadRun({
+        thread_id: thread.thread_id,
+        message: "Check the release",
+        context_profile: { include_hot: true, include_warm: false, include_facts: false, include_recall: false },
+      });
+    };
+    const lastUserText = (callIndex: number) => {
+      const messages = streamWithConfigMock.mock.calls[callIndex][1] as Array<{ role?: string; content?: unknown }>;
+      return JSON.stringify(messages[messages.length - 1]);
+    };
+
+    it("retries a step whose update was rejected and stops once the contract is met", async () => {
+      streamWithConfigMock
+        .mockImplementationOnce(() => rejectedTurn(1))
+        .mockImplementationOnce(() => chunks(
+          { type: "tool_call", data: { id: "wf-2", name: "workflow_progress", arguments: { workflow_id: "release_check", items: [step("done", "npm test: 120 passed")] } } },
+          { type: "tool_result", data: { id: "wf-2", name: "workflow_progress", result: JSON.stringify({ ok: true, workflow_id: "release_check", state: { phase: null, summary: "", error: null, checklist: [step("done", "npm test: 120 passed")] } }) } },
+          { type: "text_delta", data: { delta: "Verified." } },
+          done("done-wf-2"),
+        ));
+
+      const collected = await collectStream((await setup("agent-workflow-retry")).stream);
+
+      expect(collected.terminal).toBe("done");
+      expect(streamWithConfigMock).toHaveBeenCalledTimes(2);
+      expect(lastUserText(1)).toContain("attempt 2 of 3");
+      expect(lastUserText(1)).toContain("Run tests");
+      expect(collected.assistantContent).toContain("Turn 1.");
+      expect(collected.assistantContent).toContain("Verified.");
+    });
+
+    it("gives up after three attempts and tells the user the step still fails", async () => {
+      streamWithConfigMock
+        .mockImplementationOnce(() => rejectedTurn(1))
+        .mockImplementationOnce(() => rejectedTurn(2))
+        .mockImplementationOnce(() => rejectedTurn(3))
+        .mockImplementationOnce(() => rejectedTurn(4));
+
+      const collected = await collectStream((await setup("agent-workflow-retry-exhausted")).stream);
+
+      expect(collected.terminal).toBe("done");
+      expect(streamWithConfigMock).toHaveBeenCalledTimes(3);
+      expect(lastUserText(2)).toContain("attempt 3 of 3");
+      expect(collected.assistantContent).toContain("still failing the step contract after automatic retries");
+    });
+  });
+});