@circuitwall/jarela 2.2.1 → 2.4.0

package/lib/agents/warm-topics.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it } from "vitest";
+import type { SummaryTopicFact, SummaryTopicSegment } from "./conversation-summary";
+import {
+  canMergeIntoTopics,
+  finalizeTopic,
+  foldSingleMessageTopics,
+  mergeTopicFacts,
+  mergeWarmTopics,
+  savedMemoryFacts,
+  slugifyForMemoryKey,
+} from "./warm-topics";
+
+const events = (...list: unknown[]) => JSON.stringify(list);
+
+describe("savedMemoryFacts", () => {
+  it("counts only saves the tool result confirms, including ones routed through invoke_tool", () => {
+    const row = {
+      seq: 1,
+      content: "",
+      tool_events: events(
+        { id: "a", phase: "call", name: "invoke_tool", payload: { name: "memory_write", args_json: JSON.stringify({ namespace: "facts", key: "editor", value: "Uses VS Code." }) } },
+        { id: "a", phase: "result", name: "invoke_tool", payload: JSON.stringify({ ok: true, namespace: "facts", key: "editor" }) },
+        { id: "b", phase: "call", name: "memory_upsert", payload: { namespace: "facts", key: "failed", record: { subject: "Failed" } } },
+        { id: "b", phase: "result", name: "memory_upsert", payload: JSON.stringify({ ok: false, error: "denied" }) },
+        { id: "c", phase: "call", name: "memory_upsert", payload: { namespace: "facts", key: "mismatch", record: { subject: "Mismatch" } } },
+        { id: "c", phase: "result", name: "memory_upsert", payload: JSON.stringify({ ok: true, key: "other" }) },
+        { id: "d", phase: "call", name: "memory_write", payload: { namespace: "state", key: "last_run", value: "x" } },
+        { id: "d", phase: "result", name: "memory_write", payload: JSON.stringify({ ok: true, key: "last_run" }) },
+      ),
+    };
+    expect(savedMemoryFacts(row)).toEqual([
+      { subject: "editor", content: "Uses VS Code.", tags: [], confidence: "explicit", key: "facts/editor", origin: "agent" },
+    ]);
+  });
+});
+
+describe("canMergeIntoTopics", () => {
+  const topic = { title: "t", start_seq: 1, end_seq: 4, start_at: "", end_at: "", recap: "r", facts: [], message_count: 4 };
+
+  it("extends stored topics only when the boundary moved forward and every topic carries its counts", () => {
+    expect(canMergeIntoTopics([topic], 5, 9)).toBe(true);
+    expect(canMergeIntoTopics([topic], 5, 5)).toBe(false);
+    expect(canMergeIntoTopics([{ ...topic, message_count: undefined }], 5, 9)).toBe(false);
+    expect(canMergeIntoTopics([topic], null, 9)).toBe(false);
+  });
+});
+
+const fact = (subject: string, key?: string, content = subject): SummaryTopicFact => ({
+  subject, content, tags: [], confidence: "explicit", ...(key ? { key } : {}),
+});
+
+const topic = (start: number, end: number, extra: Partial<SummaryTopicSegment> = {}): SummaryTopicSegment => ({
+  title: `T${start}-${end}`,
+  start_seq: start,
+  end_seq: end,
+  start_at: null,
+  end_at: null,
+  recap: `recap ${start}-${end}`,
+  facts: [],
+  ...extra,
+} as SummaryTopicSegment);
+
+const rowsFor = (...seqs: number[]) => seqs.map((seq) => ({ seq, content: `message ${seq}` }));
+
+describe("slugifyForMemoryKey", () => {
+  it("keeps non-Latin subjects distinct instead of collapsing them to an empty key", () => {
+    const a = slugifyForMemoryKey("发布节奏");
+    const b = slugifyForMemoryKey("部署目标");
+    expect(a).not.toBe("");
+    expect(b).not.toBe("");
+    expect(a).not.toBe(b);
+    expect(slugifyForMemoryKey("Café Öffnungszeiten")).toBe("café-öffnungszeiten");
+  });
+
+  it("falls back to a stable non-empty key for subjects with no letters or digits", () => {
+    const key = slugifyForMemoryKey("🚀🚀");
+    expect(key).toMatch(/^fact-[0-9a-f]+$/);
+    expect(slugifyForMemoryKey("🚀🚀")).toBe(key);
+    expect(slugifyForMemoryKey("🎉")).not.toBe(key);
+  });
+
+  it("caps the key length and trims separators", () => {
+    expect(slugifyForMemoryKey("  --Release   Cadence!!  ")).toBe("release-cadence");
+    expect(slugifyForMemoryKey("x".repeat(200))).toHaveLength(80);
+  });
+});
+
+describe("mergeTopicFacts", () => {
+  it("merges by subject case-insensitively, later lists winning", () => {
+    const merged = mergeTopicFacts([fact("Editor", undefined, "old")], [fact("editor", undefined, "new")]);
+    expect(merged).toHaveLength(1);
+    expect(merged[0].content).toBe("new");
+  });
+
+  it("replaces a fact saved under the same key even when the subject was reworded", () => {
+    const merged = mergeTopicFacts([fact("Editor", "facts/editor", "VS Code")], [fact("Preferred editor", "facts/editor", "Zed")]);
+    expect(merged.map((f) => f.content)).toEqual(["Zed"]);
+  });
+
+  it("does not drop an unrelated fact through a key the subject no longer uses", () => {
+    const merged = mergeTopicFacts(
+      [fact("Region", "facts/region-old")],
+      [fact("Region", "facts/region")],
+      [fact("Old region alias", "facts/region-old")],
+    );
+    expect(merged.map((f) => f.key)).toEqual(["facts/region", "facts/region-old"]);
+  });
+
+  it("keeps the newest 16 facts", () => {
+    const merged = mergeTopicFacts(Array.from({ length: 20 }, (_, i) => fact(`s${i}`)));
+    expect(merged).toHaveLength(16);
+    expect(merged[0].subject).toBe("s4");
+    expect(merged[15].subject).toBe("s19");
+  });
+});
+
+describe("foldSingleMessageTopics", () => {
+  it("folds a leading single-message topic forward and a later one backward", () => {
+    const folded = foldSingleMessageTopics(
+      [topic(1, 1, { recap: "a" }), topic(2, 4, { recap: "b" }), topic(5, 5, { recap: "c" })],
+      rowsFor(1, 2, 3, 4, 5),
+    );
+    expect(folded).toHaveLength(1);
+    expect(folded[0]).toMatchObject({ start_seq: 1, end_seq: 5, recap: "a b c" });
+  });
+
+  it("counts rows, not seq width, so gaps from pruned rows still fold", () => {
+    const folded = foldSingleMessageTopics([topic(1, 3), topic(4, 9)], rowsFor(1, 2, 3, 9));
+    expect(folded).toHaveLength(1);
+    expect(folded[0]).toMatchObject({ start_seq: 1, end_seq: 9 });
+  });
+
+  it("leaves a lone topic alone even when it covers one message", () => {
+    expect(foldSingleMessageTopics([topic(1, 1)], rowsFor(1))).toHaveLength(1);
+  });
+
+  it("does not mutate its input", () => {
+    const input = [topic(1, 1, { facts: [fact("a")] }), topic(2, 3, { facts: [fact("b")] })];
+    const snapshot = structuredClone(input);
+    foldSingleMessageTopics(input, rowsFor(1, 2, 3));
+    expect(input).toEqual(snapshot);
+  });
+});
+
+describe("finalizeTopic", () => {
+  it("derives keys and counts in code and merges memory the agent saved in range", () => {
+    const covered = [
+      { seq: 1, content: "hello" },
+      {
+        seq: 2,
+        content: "saved",
+        tool_events: events(
+          { id: "m", phase: "call", name: "memory_write", payload: { namespace: "facts", key: "tz", value: "Europe/Amsterdam" } },
+          { id: "m", phase: "result", name: "memory_write", payload: JSON.stringify({ ok: true, key: "tz" }) },
+        ),
+      },
+    ];
+    const out = finalizeTopic(topic(1, 2, { facts: [fact("Release cadence")] }), covered);
+    expect(out.message_count).toBe(2);
+    expect(out.source_chars).toBe("hello".length + "saved".length);
+    expect(out.facts).toEqual([
+      expect.objectContaining({ key: "facts/release-cadence", origin: "compaction" }),
+      expect.objectContaining({ key: "facts/tz", origin: "agent", content: "Europe/Amsterdam" }),
+    ]);
+  });
+});
+
+describe("mergeWarmTopics", () => {
+  it("updates a continued topic in place, keeps its start, sums counts and re-sorts by recency", () => {
+    const prior = [topic(1, 4, { message_count: 4, source_chars: 40 }), topic(5, 8, { message_count: 4, source_chars: 40 })];
+    const fresh = [topic(9, 12, { continues: "t1", recap: "newer", message_count: 4, source_chars: 10 })];
+    const merged = mergeWarmTopics(prior, fresh, 100);
+    expect(merged.topics.map((t) => [t.start_seq, t.end_seq])).toEqual([[5, 8], [1, 12]]);
+    expect(merged.topics[1]).toMatchObject({ recap: "newer", message_count: 8, source_chars: 50 });
+    expect(merged.topics[1]).not.toHaveProperty("continues");
+  });
+
+  it("appends a fresh topic whose continues id does not exist", () => {
+    const merged = mergeWarmTopics([topic(1, 4, { message_count: 4 })], [topic(5, 8, { continues: "t9", message_count: 4 })], 100);
+    expect(merged.topics).toHaveLength(2);
+    expect(merged.topics[1]).not.toHaveProperty("continues");
+  });
+
+  it("evicts the least recently active topics until within the limit, keeping at least one", () => {
+    const prior = [topic(1, 4, { message_count: 4 }), topic(5, 8, { message_count: 4 })];
+    const merged = mergeWarmTopics(prior, [topic(9, 20, { message_count: 12 })], 10);
+    expect(merged.evicted).toBe(2);
+    expect(merged.topics.map((t) => t.start_seq)).toEqual([9]);
+    expect(merged.sourceMessages).toBe(10);
+  });
+});

package/lib/agents/warm-topics.ts

@@ -0,0 +1,317 @@
+import { transcriptText, type SummaryTopicFact, type SummaryTopicSegment } from "@/lib/agents/conversation-summary";
+import type { PersistedToolEvent } from "@/lib/stores/threads";
+
+// Deterministic half of warm-context compaction. The summarizer model only
+// segments and recaps; everything that can be checked or computed in code —
+// message counts, which topic a saved memory belongs to, merging into the
+// stored topics, and fading out the oldest ones — lives here.
+
+export interface WarmTopicSourceRow {
+  seq: number;
+  content: string;
+  tool_events?: string | null;
+}
+
+const MAX_TOPIC_FACTS = 16;
+const MEMORY_WRITE_NAMESPACES = new Set(["facts"]);
+
+/** Stable id the compaction pipeline uses to refer to stored topic `index`. */
+export function warmTopicId(index: number): string {
+  return `t${index + 1}`;
+}
+
+function rowsInRange<T extends WarmTopicSourceRow>(rows: readonly T[], topic: SummaryTopicSegment): T[] {
+  return rows.filter((row) => row.seq >= (topic.start_seq ?? Infinity) && row.seq <= (topic.end_seq ?? -Infinity));
+}
+
+// Unicode-aware so non-Latin subjects get distinct keys; an ASCII-only slug
+// collapsed them all to "" and the uplift skipped them. Subjects with no
+// letters or digits fall back to a stable hash.
+export function slugifyForMemoryKey(subject: string): string {
+  const slug = subject
+    .normalize("NFC")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{M}\p{N}]+/gu, "-")
+    .replace(/^-+|-+$/g, "");
+  const capped = Array.from(slug).slice(0, 80).join("").replace(/-+$/, "");
+  return capped || `fact-${fnv1a(subject)}`;
+}
+
+function fnv1a(text: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+/**
+ * Merge facts by subject (case-insensitive) and memory key. Later entries win,
+ * so callers pass the newer or more trustworthy list last. Keeps the newest
+ * MAX_TOPIC_FACTS.
+ */
+export function mergeTopicFacts(...lists: readonly (readonly SummaryTopicFact[])[]): SummaryTopicFact[] {
+  const merged = new Map<string, SummaryTopicFact>();
+  const keyToSubject = new Map<string, string>();
+  for (const list of lists) {
+    for (const fact of list) {
+      const subjectId = fact.subject.trim().toLowerCase();
+      const sameKeySubject = fact.key ? keyToSubject.get(fact.key) : undefined;
+      for (const replaced of [sameKeySubject, subjectId]) {
+        if (replaced === undefined) continue;
+        // Drop the replaced fact's key mapping too, so a later fact reusing
+        // that key cannot delete whatever now lives under this subject.
+        const previousKey = merged.get(replaced)?.key;
+        if (previousKey) keyToSubject.delete(previousKey);
+        merged.delete(replaced);
+      }
+      merged.set(subjectId, fact);
+      if (fact.key) keyToSubject.set(fact.key, subjectId);
+    }
+  }
+  return [...merged.values()].slice(-MAX_TOPIC_FACTS);
+}
+
+/**
+ * A topic must span at least two messages. Fold any single-message topic into
+ * the previous topic (or the next one when it is first). Input must be the
+ * ordered, non-overlapping output of validateTopicSegments.
+ */
+export function foldSingleMessageTopics(
+  topics: readonly SummaryTopicSegment[],
+  rows: readonly WarmTopicSourceRow[],
+): SummaryTopicSegment[] {
+  const out = topics.map((topic) => ({ ...topic, facts: [...topic.facts] }));
+  let index = 0;
+  while (out.length > 1 && index < out.length) {
+    if (rowsInRange(rows, out[index]).length >= 2) {
+      index += 1;
+      continue;
+    }
+    const single = out[index];
+    const targetIndex = index > 0 ? index - 1 : 1;
+    const target = out[targetIndex];
+    const [first, second] = targetIndex < index ? [target, single] : [single, target];
+    out[targetIndex] = {
+      ...target,
+      start_seq: first.start_seq,
+      start_at: first.start_at,
+      partial_start: first.partial_start,
+      end_seq: second.end_seq,
+      end_at: second.end_at,
+      recap: targetIndex < index ? `${target.recap} ${single.recap}` : `${single.recap} ${target.recap}`,
+      facts: mergeTopicFacts(target.facts, single.facts),
+      continues: target.continues ?? single.continues,
+    };
+    out.splice(index, 1);
+    if (targetIndex < index) index = targetIndex;
+  }
+  return out;
+}
+
+function toolResultText(payload: unknown): string | null {
+  if (typeof payload === "string") return payload;
+  if (!payload || typeof payload !== "object") return null;
+  const obj = payload as Record<string, unknown>;
+  if (obj.__truncated) return null;
+  const kwargs = obj.kwargs as Record<string, unknown> | undefined;
+  if (typeof kwargs?.content === "string") return kwargs.content;
+  if (typeof obj.content === "string") return obj.content;
+  return JSON.stringify(obj);
+}
+
+function parseObject(value: unknown): Record<string, unknown> | null {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, unknown>;
+  if (typeof value !== "string") return null;
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}
+
+function unwrapCall(event: PersistedToolEvent): { name: string; args: Record<string, unknown> } | null {
+  const payload = parseObject(event.payload);
+  if (!payload) return null;
+  if (event.name !== "invoke_tool") return { name: event.name, args: payload };
+  const name = typeof payload.name === "string" ? payload.name : "";
+  const args = parseObject(payload.args_json) ?? parseObject(payload.args) ?? {};
+  return name ? { name, args } : null;
+}
+
+function savedFactFromCall(name: string, args: Record<string, unknown>, key: string): SummaryTopicFact | null {
+  const namespace = typeof args.namespace === "string" ? args.namespace : "";
+  if (name === "memory_upsert") {
+    const record = parseObject(args.record) ?? {};
+    const subject = typeof record.subject === "string" && record.subject.trim() ? record.subject.trim() : key;
+    const content = typeof record.content === "string" ? record.content.trim() : "";
+    const confidence = record.confidence === "explicit" || record.confidence === "inferred" || record.confidence === "verified"
+      ? record.confidence
+      : "explicit";
+    const tags = Array.isArray(record.tags) ? record.tags.filter((t): t is string => typeof t === "string").slice(0, 16) : [];
+    return { subject: subject.slice(0, 160), content: content.slice(0, 1_000), tags, confidence, key: `${namespace}/${key}`, origin: "agent" };
+  }
+  if (name === "memory_write" && MEMORY_WRITE_NAMESPACES.has(namespace)) {
+    const value = typeof args.value === "string" ? args.value.trim() : "";
+    return { subject: key, content: value.slice(0, 1_000), tags: [], confidence: "explicit", key: `${namespace}/${key}`, origin: "agent" };
+  }
+  return null;
+}
+
+/**
+ * Memory records the agent saved in a message, verified by the tool result
+ * (`ok: true` echoing the same key). Unverified or failed writes are skipped.
+ */
+export function savedMemoryFacts(row: WarmTopicSourceRow): SummaryTopicFact[] {
+  if (!row.tool_events) return [];
+  let events: PersistedToolEvent[];
+  try {
+    const parsed = JSON.parse(row.tool_events) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    events = parsed as PersistedToolEvent[];
+  } catch {
+    return [];
+  }
+  const calls = new Map<string, { name: string; args: Record<string, unknown> }>();
+  for (const event of events) {
+    if (event?.phase !== "call") continue;
+    const call = unwrapCall(event);
+    if (call && (call.name === "memory_upsert" || call.name === "memory_write")) calls.set(event.id, call);
+  }
+  const facts: SummaryTopicFact[] = [];
+  for (const event of events) {
+    if (event?.phase !== "result") continue;
+    const call = calls.get(event.id);
+    if (!call) continue;
+    const text = toolResultText(event.payload);
+    let result = text ? parseObject(text) : null;
+    if (result && typeof result.result === "string") result = parseObject(result.result) ?? result;
+    const key = typeof call.args.key === "string" ? call.args.key : "";
+    if (!result || result.ok !== true || !key || (typeof result.key === "string" && result.key !== key)) continue;
+    const fact = savedFactFromCall(call.name, call.args, key);
+    if (fact) facts.push(fact);
+  }
+  return facts;
+}
+
+/**
+ * Attach the code-derived fields to one topic: message count and size of the
+ * rows it covers, keys for extracted facts, and memory the agent saved there.
+ */
+export function finalizeTopic(
+  topic: SummaryTopicSegment,
+  covered: readonly WarmTopicSourceRow[],
+): SummaryTopicSegment {
+  const extracted = topic.facts.map((fact): SummaryTopicFact => ({
+    ...fact,
+    key: fact.key ?? `facts/${slugifyForMemoryKey(fact.subject)}`,
+    origin: fact.origin ?? "compaction",
+  }));
+  return {
+    ...topic,
+    facts: mergeTopicFacts(extracted, covered.flatMap(savedMemoryFacts)),
+    message_count: covered.length,
+    source_chars: covered.reduce((total, row) => total + transcriptText(row.content).length, 0),
+  };
+}
+
+/**
+ * Turn validated summarizer topics into stored topics: fold single-message
+ * topics, then finalize each against the rows in its seq range.
+ */
+export function finalizeFreshTopics(
+  topics: readonly SummaryTopicSegment[],
+  rows: readonly WarmTopicSourceRow[],
+): SummaryTopicSegment[] {
+  return foldSingleMessageTopics(topics, rows).map((topic) => finalizeTopic(topic, rowsInRange(rows, topic)));
+}
+
+/** Stored topics can be extended incrementally only when every one carries its message count and seq range. */
+export function canMergeIntoTopics(
+  prior: readonly SummaryTopicSegment[] | null | undefined,
+  priorBeforeSeq: number | null | undefined,
+  boundarySeq: number,
+): prior is SummaryTopicSegment[] {
+  if (!prior || prior.length === 0 || priorBeforeSeq == null || boundarySeq <= priorBeforeSeq) return false;
+  return prior.every((topic) =>
+    Number.isSafeInteger(topic.start_seq)
+    && Number.isSafeInteger(topic.end_seq)
+    && topic.end_seq! < priorBeforeSeq
+    && typeof topic.message_count === "number"
+    && Array.isArray(topic.facts),
+  );
+}
+
+/** Model-facing text for stored topics: one heading per topic, its recap, and the memory keys it produced. */
+export function renderTopicRecaps(topics: readonly SummaryTopicSegment[]): string {
+  return topics.map((topic) => {
+    const memorized = topic.facts.flatMap((fact) => fact.key ? [fact.key] : []);
+    return [
+      `### ${topic.title}${topic.partial_start ? " (partial; earlier messages omitted)" : ""}`,
+      topic.recap,
+      ...(memorized.length > 0 ? [`Memorized: ${memorized.join(", ")}`] : []),
+    ].join("\n");
+  }).join("\n\n");
+}
+
+export interface MergedWarmTopics {
+  topics: SummaryTopicSegment[];
+  sourceMessages: number;
+  sourceChars: number;
+  evicted: number;
+}
+
+/**
+ * Fold fresh topics into the stored ones, newest last. A fresh topic that
+ * `continues` a stored one updates it in place (newer recap, merged facts,
+ * summed counts). Then the least recently active topics fade out until the
+ * kept topics fit `messageLimit`, mirroring how memory keeps recent detail.
+ * Their facts already live in the memory store, so eviction loses no record.
+ */
+export function mergeWarmTopics(
+  prior: readonly SummaryTopicSegment[],
+  fresh: readonly SummaryTopicSegment[],
+  messageLimit: number,
+): MergedWarmTopics {
+  const out: SummaryTopicSegment[] = prior.map((topic) => ({ ...topic, facts: [...topic.facts] }));
+  const indexById = new Map(prior.map((_, index) => [warmTopicId(index), index]));
+  for (const topic of fresh) {
+    const { continues, ...clean } = topic;
+    const index = continues ? indexById.get(continues) : undefined;
+    if (index === undefined) {
+      out.push(clean);
+      continue;
+    }
+    const base = out[index];
+    out[index] = {
+      ...base,
+      title: clean.title,
+      end_seq: clean.end_seq,
+      end_at: clean.end_at,
+      recap: clean.recap,
+      facts: mergeTopicFacts(base.facts, clean.facts),
+      message_count: (base.message_count ?? 0) + (clean.message_count ?? 0),
+      source_chars: (base.source_chars ?? 0) + (clean.source_chars ?? 0),
+    };
+  }
+  out.sort((a, b) => (a.end_seq ?? 0) - (b.end_seq ?? 0));
+
+  let total = out.reduce((sum, topic) => sum + (topic.message_count ?? 0), 0);
+  let evicted = 0;
+  while (out.length > 1 && total > messageLimit) {
+    total -= out[0].message_count ?? 0;
+    out.shift();
+    evicted += 1;
+  }
+  return {
+    topics: out,
+    // The warm cache treats a count above the limit as an oversized legacy
+    // summary and rebuilds it; one topic larger than the limit is still a
+    // bounded, merged recap, so report it at the limit.
+    sourceMessages: Math.min(total, messageLimit),
+    sourceChars: out.reduce((sum, topic) => sum + (topic.source_chars ?? 0), 0),
+    evicted,
+  };
+}

package/lib/agents/workflow-step-retry.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildWorkflowStepRetryNudge,
+  collectWorkflowContractFailures,
+  planWorkflowStepRetries,
+  WORKFLOW_STEP_MAX_ATTEMPTS,
+  workflowProgressArgs,
+} from "./workflow-step-retry";
+
+const item = (id: string, status: string, extra: Record<string, unknown> = {}) => ({
+  id, label: `Step ${id}`, input: "in", output: "out", validation: "check", status, ...extra,
+});
+const ok = (workflowId: string, checklist: unknown[], phase: string | null = null, error: string | null = null) =>
+  JSON.stringify({ ok: true, workflow_id: workflowId, state: { phase, summary: "", error, checklist } });
+
+describe("collectWorkflowContractFailures", () => {
+  it("passes a workflow whose steps are verified or pending", () => {
+    expect(collectWorkflowContractFailures([
+      { args: { workflow_id: "w" }, result: ok("w", [item("a", "done", { validation_evidence: "ran" }), item("b", "pending")]) },
+    ])).toEqual([]);
+  });
+
+  it("flags a rejected update and names the step that broke the contract", () => {
+    const failures = collectWorkflowContractFailures([
+      { args: { workflow_id: "w", items: [item("a", "done")] }, result: JSON.stringify({ ok: false, workflow_id: "w", error: "Every completed workflow item requires observed validation_evidence." }) },
+    ]);
+    expect(failures).toEqual([expect.objectContaining({ key: "w:a", itemId: "a", label: "Step a" })]);
+    expect(failures[0].reason).toContain("validation_evidence");
+  });
+
+  it("clears a rejection once a later update for the same workflow is accepted", () => {
+    expect(collectWorkflowContractFailures([
+      { args: { workflow_id: "w", items: [item("a", "done")] }, result: { ok: false, workflow_id: "w", error: "x" } },
+      { args: { workflow_id: "w" }, result: ok("w", [item("a", "done", { validation_evidence: "ran" })]) },
+    ])).toEqual([]);
+  });
+
+  it("flags steps left checking or needing attention at turn end", () => {
+    const failures = collectWorkflowContractFailures([
+      { args: { workflow_id: "w" }, result: ok("w", [item("a", "checking"), item("b", "needs_attention")], null, "tests failed") },
+    ]);
+    expect(failures.map((f) => f.key)).toEqual(["w:a", "w:b"]);
+    expect(failures[1].reason).toContain("tests failed");
+  });
+
+  it("does not retry steps that are waiting on the user", () => {
+    expect(collectWorkflowContractFailures([
+      { args: { workflow_id: "w" }, result: ok("w", [item("a", "needs_attention", { needs_user: true })]) },
+      { args: { workflow_id: "version_adoption", item_id: "review-tools", status: "needs_attention", needs_user: true }, result: ok("version_adoption", [item("review-tools", "needs_attention")]) },
+    ])).toEqual([]);
+  });
+
+  it("ignores completed workflows and reads invoke_tool envelopes", () => {
+    expect(collectWorkflowContractFailures([
+      { args: { workflow_id: "w" }, result: ok("w", [item("a", "checking")], "complete") },
+    ])).toEqual([]);
+    expect(collectWorkflowContractFailures([
+      { args: { workflow_id: "w" }, result: { ok: true, tool: "workflow_progress", status: "done", result: ok("w", [item("a", "checking")]) } },
+    ]).map((f) => f.key)).toEqual(["w:a"]);
+  });
+});
+
+describe("workflowProgressArgs", () => {
+  it("unwraps direct and proxied workflow_progress calls only", () => {
+    expect(workflowProgressArgs("workflow_progress", { workflow_id: "w" })).toEqual({ workflow_id: "w" });
+    expect(workflowProgressArgs("invoke_tool", { name: "workflow_progress", args_json: "{\"workflow_id\":\"w\"}" })).toEqual({ workflow_id: "w" });
+    expect(workflowProgressArgs("invoke_tool", { name: "file_read", args_json: "{}" })).toBeNull();
+    expect(workflowProgressArgs("file_read", { workflow_id: "w" })).toBeNull();
+  });
+});
+
+describe("planWorkflowStepRetries", () => {
+  const failure = { key: "w:a", workflowId: "w", itemId: "a", label: "Step a", reason: "r" };
+
+  it(`allows ${WORKFLOW_STEP_MAX_ATTEMPTS} total attempts per step`, () => {
+    expect(planWorkflowStepRetries([failure]).retry).toEqual([{ ...failure, attempt: 2 }]);
+    expect(planWorkflowStepRetries([failure], { "w:a": 1 }).retry).toEqual([{ ...failure, attempt: 3 }]);
+    const exhausted = planWorkflowStepRetries([failure], { "w:a": 2 });
+    expect(exhausted.retry).toEqual([]);
+    expect(exhausted.exhausted).toEqual([failure]);
+  });
+});
+
+describe("buildWorkflowStepRetryNudge", () => {
+  it("states the attempt, the failure, and the exact progress call for each workflow kind", () => {
+    const nudge = buildWorkflowStepRetryNudge([
+      { key: "w:a", workflowId: "w", itemId: "a", label: "Step a", reason: "validation failed", attempt: 2 },
+      { key: "version_adoption:review-tools", workflowId: "version_adoption", itemId: "review-tools", label: "Review tools", reason: "left checking", attempt: 3 },
+    ]);
+    expect(nudge).toContain(`attempt 2 of ${WORKFLOW_STEP_MAX_ATTEMPTS}`);
+    expect(nudge).toContain("complete items snapshot");
+    expect(nudge).toContain('item_id: "review-tools"');
+    expect(nudge).toContain("needs_user: true");
+    expect(nudge).not.toMatch(/undefined|NaN|\[object Object\]/);
+  });
+});