@circuitwall/jarela 2.2.1 → 2.3.0

package/lib/agents/prepare/system-prompt.test.ts

@@ -148,6 +148,45 @@ describe("buildSystemPrompt self-configuration", () => {
   });
 });
 
+describe("buildSystemPrompt proactive memory saving", () => {
+  const build = () => buildSystemPrompt({
+    agentCfg: agentCfg(),
+    trimmedMessage: "I prefer short answers",
+    budget,
+    recallCtx: "",
+    warmSummaryCtx: "",
+    factsCtx: "",
+    experienceMode: "full",
+    delegateRosterLines: [],
+  });
+
+  it("orders the save procedure as trigger, check, write, validate, cite", () => {
+    const prompt = build();
+    const steps = ["1. Trigger:", "2. Check:", "3. Write:", "4. Validate:", "5. Cite:"].map((s) => prompt.indexOf(s));
+    expect(steps.every((i) => i >= 0)).toBe(true);
+    expect([...steps].sort((a, b) => a - b)).toEqual(steps);
+    expect(prompt).toContain("backstop, not your save step");
+  });
+
+  it("keeps the save procedure in the cached agent-stable block", () => {
+    const prompt = build();
+    const split = prompt.indexOf(CACHE_SPLIT_SENTINEL);
+    expect(split).toBeGreaterThan(0);
+    expect(prompt.indexOf("Proactive save procedure")).toBeLessThan(split);
+  });
+
+  it("only names memory tools that are registered", async () => {
+    const memory = await import("@/lib/tools/general/memory");
+    const registered = new Set(Object.values(memory)
+      .filter((v): v is { name: string } => typeof v === "object" && v !== null && "name" in v)
+      .map((t) => t.name));
+    const block = build().split("--- Memory & recall ---")[1]?.split("\n---")[0] ?? "";
+    const named = new Set(block.match(/\bmemory_[a-z]+\b/g) ?? []);
+    expect(named.size).toBeGreaterThan(0);
+    for (const name of named) expect(registered).toContain(name);
+  });
+});
+
 const permissionMapFixture = [
   {
     name: "file_read",

package/lib/agents/prepare/system-prompt.ts

@@ -272,7 +272,7 @@ export function buildSharedToolCatalogContext(): string {
   return [
     "--- Tool usage SOP ---",
     "Static cross-agent procedure. The per-turn bound list and counts appear later under \"Enabled tools\".",
-    `0. Classify the request. Informational answers may be direct; read/retrieve requests need a read tool; write/change requests need a state-changing tool; destructive requests also need the required confirmation. ${formatActionVocabularyInstruction()} For substantial tasks with several dependent phases, likely cross-turn progress, or explicit verification, use workflow_progress to create and update a concise checklist; skip simple tasks and work already covered by native tool progress. This contract applies to every built-in Jarela workflow and every workflow you create or follow: each step must state its input, expected output, and concrete validation criteria; validate each output before passing it to a later step. Prefer executable checks whenever code can verify the result, and record observed validation_evidence before marking an item done. Keep a stable workflow_id, send the complete current item list on each update, and keep secrets or private data out of checklist fields. Use needs_attention for blockers; set phase=complete only when all items are done or skipped. Never claim an output or validation result that you did not observe.`,
+    `0. Classify the request. Informational answers may be direct; read/retrieve requests need a read tool; write/change requests need a state-changing tool; destructive requests also need the required confirmation. ${formatActionVocabularyInstruction()} For substantial tasks with several dependent phases, likely cross-turn progress, or explicit verification, use workflow_progress to create and update a concise checklist; skip simple tasks and work already covered by native tool progress. This contract applies to every built-in Jarela workflow and every workflow you create or follow: each step must state its input, expected output, and concrete validation criteria; validate each output before passing it to a later step. Prefer executable checks whenever code can verify the result, and record observed validation_evidence before marking an item done. Keep a stable workflow_id, send the complete current item list on each update, and keep secrets or private data out of checklist fields. Use needs_attention for blockers, with needs_user=true when only the user can unblock the step; a rejected update or a step you leave checking or needs_attention without needs_user is retried automatically, up to 3 attempts per step. Set phase=complete only when all items are done or skipped. Never claim an output or validation result that you did not observe.`,
     "1. Bound first. If a tool listed under \"Enabled tools\" fits the task, call it directly.",
     "2. Otherwise look it up. Names of permitted tools that are not bound this turn are listed after the bound tools under \"Enabled tools\", capped, with no definitions. A name that is not listed there may still exist, so never conclude a capability does not exist from the bound list alone. Call list_tools with service/object/action keywords: scope=\"enabled\" searches executable tools, scope=\"all\" also returns disabled, unavailable and cap-omitted tools with flags.",
     "3. Named target. When a skill, harness or instruction names an exact tool, call list_tools names=[\"exact_name\"] include_schema=true instead of a keyword query. Exact lookup ignores every other filter, so it also describes tools you cannot currently execute.",
@@ -603,11 +603,16 @@ function buildMemoryContext(budget: ContextBudget): string {
       : "Store explicit preferences, verified facts, durable decisions, constraints, and project context. Store task details only when they will matter across sessions.";
   return [
     "--- Memory & recall ---",
-    "You have long-term memory across sessions.",
+    "You have long-term memory across sessions, shared with every other Jarela agent. A record you save is available to other agents immediately. Background compaction also extracts facts later, but it runs late and can miss details, so it is a backstop, not your save step.",
     `- Hot conversation history is budgeted by model context size: ${formatContextBudgetSummary(budget)}.`,
     `- Active memory policy: ${policy}. ${writeGuidance}`,
-    "- Use memory_upsert proactively for structured records. Use namespace='facts', concise tags, confidence='explicit' for user-stated information, observed_at when the information was true, and expires_at for temporary facts. Keep memory_write only for legacy/free-form notes.",
     "- Use memory_search proactively when relevant saved facts or prior conversations could help. Use memory_read / memory_list to inspect known entries.",
+    "Proactive save procedure — run it whenever information fits the active memory policy, without waiting to be asked:",
+    "1. Trigger: the user states a preference, a fact about themselves or their work, a decision, a constraint, or a correction to something saved; or a tool result verifies a durable fact. Routine status, one-off chatter, secrets, credentials, and raw transcripts never qualify.",
+    "2. Check: memory_search (or memory_read for a known key) for an existing record on the same subject. Update that stable key rather than creating a duplicate or contradictory copy.",
+    "3. Write: call memory_upsert in the same turn, before your final reply, with namespace='facts', a stable descriptive key, standalone content, concise tags, confidence='explicit' for user-stated information ('verified' when tool-backed, 'inferred' only when useful and reversible), observed_at when the information became true, and expires_at for temporary facts. Keep memory_write only for legacy/free-form notes.",
+    "4. Validate: the memory_upsert result must contain ok:true and the key you sent. If it failed, correct the arguments and retry once; if it still fails, tell the user it was not saved.",
+    "5. Cite: end your reply with one short line naming each saved key, for example 'Saved to memory: facts/answer-format-preference'. Omit the line when nothing was saved.",
   ].join("\n");
 }
 

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

@@ -1,6 +1,6 @@
 /**
  * Assembles every prompt Jarela can send and checks it for completeness and
- * correctness. Reading the builders is not enough — the bugs found so far
+ * correctness. Reading the builders is not enough — the bugs found so far
  * (contradictory tool counts, undocumented denial reasons) were only visible
  * in the assembled text.
  *
@@ -16,151 +16,15 @@ const tmpRoot = mkdtempSync(join(tmpdir(), "jarela-prompt-verify-"));
 process.env.JARELA_DB_DIR = tmpRoot;
 
 const { buildSystemPrompt, CACHE_SHARED_SPLIT_SENTINEL, CACHE_SPLIT_SENTINEL } = await import("./prepare/system-prompt");
-const { getUsageStrategyProfile } = await import("./usage-strategy");
 const { listStaticPrompts, promptsAffectedBy, SYSTEM_PROMPT_SOURCE_PREFIXES } = await import("./prompt-registry");
-const { getAllToolCatalogAsync, applyAgentPermissionsToCatalog, markProxyOnlyTools } = await import("@/lib/tools");
+const { getAllToolCatalogAsync, applyAgentPermissionsToCatalog } = await import("@/lib/tools");
 import type { AgentConfigRow } from "@/lib/stores/agent-configs";
-import type { ContextBudget } from "@/lib/agents/context-budget";
 
 afterAll(() => {
   try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* held open */ }
 });
 
-const budget: ContextBudget = {
-  contextWindowTokens: 200000,
-  outputReserveTokens: 8000,
-  inputBudgetTokens: 120000,
-  overheadTokens: 4000,
-  tierPriority: ["hot", "warm", "facts"],
-  tierBudgets: { hot: 60000, warm: 40000, facts: 20000 },
-};
-
-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;
-}
-
-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 };
-}
-
-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),
-    },
-  ];
-}
+const { agentCfg, budget, buildVariants } = await import("./prompt-variants");
 
 const variants = await buildVariants();
 const staticPrompts = listStaticPrompts();
@@ -198,7 +62,7 @@ if (process.env.JARELA_PROMPT_DUMP === "1") {
       ...variants.map((v) => `- \`system-prompt.${v.id}.txt\` (${v.prompt.length} chars)`),
       "",
       "## Static prompts",
-      ...staticPrompts.map((p) => `- \`static.${p.id}.txt\` — ${p.purpose}`),
+      ...staticPrompts.map((p) => `- \`static.${p.id}.txt\` — ${p.purpose}`),
     ].join("\n"),
     "utf8",
   );
@@ -267,6 +131,7 @@ describe("prompt registry coverage", () => {
       "lib/agents/citation-checker.ts",
       "lib/agents/hallucination-classifier.ts",
       "lib/agents/conversation-summary.ts",
+      "lib/agents/compaction-pipeline.ts",
       "lib/pricing/llm-extract.ts",
       "lib/tools/claude-delegate.ts",
       "lib/agents/prepare/system-prompt.ts",

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/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.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");
+    });
+  });
+});