@hassangameryt/freeflow 0.7.3 → 0.9.0

package/pi-extension/dist/cognitive-routing/projection.js

@@ -0,0 +1,520 @@
+import { annotateSources } from "./provenance.js";
+import { randomUUID } from "node:crypto";
+import { bodyHash, deliveredSelection, isTaskEvidence } from "./sources.js";
+import { canonical, emptySelection, isWorkerProfile, PROFILES, requireCondition as check } from "./types.js";
+import { estimateRequest } from "./budget.js";
+import { occurrenceIdentity, tagDerived } from "../host/projection-tags.js";
+export function changeSelection(prior, input, sources, state) {
+  check(
+    Array.isArray(input.refs) &&
+      input.refs.length <= 64 &&
+      input.refs.every((r) => typeof r === "string" && r.length <= 512),
+    "invalid_refs",
+  );
+  if (input.operation === "remove")
+    check(
+      typeof input.reason === "string" && input.reason.trim() && input.reason.length <= 2048,
+      "withdrawal_reason_required",
+    );
+  const next = structuredClone(prior);
+  for (const ref of new Set(input.refs)) {
+    const existed = next.selected.includes(ref) || next.unresolved.some((p) => p.ref === ref);
+    if (input.operation === "remove") {
+      next.unresolved = next.unresolved.filter((p) => p.ref !== ref);
+      next.selected = next.selected.filter((r) => r !== ref);
+      if (existed) next.withdrawals.push({ ref, reason: input.reason });
+      continue;
+    }
+    const problem = prior.selected.includes(ref) ? sources.eligible(ref, state) : sources.selectionProblem(ref, state);
+    const index = next.unresolved.findIndex((p) => p.ref === ref);
+    if (problem) {
+      if (index < 0) next.unresolved.push(problem);
+      else next.unresolved[index] = problem;
+    } else {
+      if (index >= 0) next.unresolved.splice(index, 1);
+      if (!next.selected.includes(ref)) next.selected.push(ref);
+    }
+  }
+  if (canonical(next) === canonical(prior)) return prior;
+  next.revision++;
+  return next;
+}
+/**
+ * Profiles share history, not private reasoning, except where they would otherwise send the same request: the
+ * same model under the same view (projection off, or Helper and Executor on worker history). There shared
+ * reasoning keeps one prompt cache across effort switches and stays valid for providers that bind reasoning to
+ * its conversation. Unknown and pre-routing history keeps its native form.
+ */
+function privateReasoning(source, view, projection, model) {
+  const producer = source.producer;
+  if (!PROFILES.includes(producer) || producer === view) return false;
+  const message = source.message;
+  const sameModel = message.provider === model?.provider && message.api === model?.api && message.model === model?.id;
+  const viewOf = (profile) => (!projection ? "shared" : isWorkerProfile(profile) ? "worker" : profile);
+  return !(sameModel && viewOf(producer) === viewOf(view));
+}
+/**
+ * Remove reasoning from another profile's turn. A provider may pair a call with the reasoning that produced
+ * it (OpenAI Responses `fc_` ids pair with `rs_` items), so such calls keep only their call id, as the host
+ * already does for another model's turns; `unpaired` carries the rename to the matching results.
+ */
+function withoutReasoning(message, unpaired) {
+  if (!message.content.some((b) => b.type === "thinking")) return message;
+  return {
+    ...message,
+    content: message.content.flatMap((b) => {
+      if (b.type === "thinking") return [];
+      if (b.type !== "toolCall" || typeof b.id !== "string" || !b.id.includes("|")) return [b];
+      const id = b.id.split("|")[0];
+      unpaired.set(b.id, id);
+      return [{ ...b, id }];
+    }),
+  };
+}
+export function representationProblems(source, model) {
+  const message = source.message,
+    content = Array.isArray(message.content) ? message.content : [];
+  if (message.role === "assistant" && ["error", "aborted"].includes(message.stopReason))
+    return [
+      {
+        ref: source.ref,
+        code: "target_representation",
+        detail:
+          "Native compatibility conversion may omit failed/aborted assistant output; exact delivery is not promised.",
+      },
+    ];
+  if (content.some((b) => b.type === "image") && !model?.input?.includes("image"))
+    return [
+      { ref: source.ref, code: "target_representation", detail: "The receiving model does not support image input." },
+    ];
+  return [];
+}
+/**
+ * Renderings reused across requests, so each view message keeps one identity (request history then fingerprints it
+ * once) and nothing is cloned per request. Entries are immutable, so a rendering keyed by its entry object and variant
+ * never goes stale; a replaced entry is a different object. Cached messages are shared and must never be mutated.
+ */
+export class ViewCache {
+  renderings = new WeakMap();
+  notes = new Map();
+  coordinatorVersions = new WeakMap();
+}
+/** Tests set FREEFLOW_FREEZE_VIEWS to make any later mutation of a shared rendering throw. */
+const FREEZE = !!process.env.FREEFLOW_FREEZE_VIEWS;
+function deepFreeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+/** Messages normalized() produced, so normalizing a shared rendering again keeps it (and its identity) as it is. */
+const NORMALIZED = new WeakSet();
+/** Request metadata as Pi must see it in a routed view: a finite timestamp, and no recorded usage on assistants. */
+function normalized(message) {
+  const finite = Number.isFinite(message?.timestamp);
+  if ((finite && message?.role !== "assistant") || NORMALIZED.has(message)) return message;
+  const result = {
+    ...message,
+    timestamp: finite ? message.timestamp : 0,
+    ...(message.role === "assistant"
+      ? { usage: { ...message.usage, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 } }
+      : {}),
+  };
+  NORMALIZED.add(result);
+  return result;
+}
+function shareRendering(message, identity) {
+  tagDerived(message, identity);
+  return FREEZE ? deepFreeze(message) : message;
+}
+export function prepareView(options) {
+  const cache = options.cache ?? new ViewCache();
+  const { sources, state } = options;
+  const associated = sources.associate(options.messages);
+  const selective = options.projection && options.view === "coordinator";
+  const assessment = state.assessment;
+  const attention = selective && assessment?.view === "suspended" && !options.restoring && !options.preparingReturn;
+  const handoffId = options.preparingReturn ?? (!attention ? assessment?.handoffId : undefined);
+  const handoff = handoffId ? state.handoffs.get(handoffId) : undefined;
+  const assignmentId = handoff?.assignmentId ?? state.assignmentId;
+  const current = assignmentId ? (state.selections.get(assignmentId) ?? emptySelection()) : emptySelection();
+  // Assistant messages (whole or `#text`) that older sessions selected are not delivered.
+  const delivered = (ref) => deliveredSelection(sources, ref);
+  const required = new Set(selective && !attention && assignmentId ? current.selected.filter(delivered) : []);
+  const promised = handoff && state.reservations.get(handoff.id);
+  const admitted = new Set();
+  if (selective)
+    for (const selection of state.selections.values())
+      for (const ref of selection.selected) if (delivered(ref)) admitted.add(ref);
+  // Accepted return receipts are communication, independent of selected task evidence.
+  // Their ordinary active occurrence survives closure; compaction still owns its lifetime.
+  const full = new Map();
+  const structural = new Map();
+  const problems = selective && !attention && assignmentId ? current.unresolved.filter((p) => delivered(p.ref)) : [];
+  for (const item of associated) {
+    if (!item.source) continue;
+    if (
+      !selective ||
+      !isWorkerProfile(item.source.producer) ||
+      admitted.has(item.source.ref) ||
+      (item.source.reportHandoff && state.handoffs.has(item.source.reportHandoff))
+    )
+      full.set(item.source.ref, item.source);
+  }
+  for (const ref of required) {
+    if (sources.ambiguous.has(ref)) {
+      problems.push({
+        ref,
+        code: "ambiguous_occurrence",
+        detail: "The active representation cannot be associated with one canonical occurrence.",
+      });
+      continue;
+    }
+    const source = sources.byRef.get(ref),
+      error = sources.eligible(ref, state);
+    if (error) {
+      problems.push(error);
+      continue;
+    }
+    const expected =
+      promised && promised.selectionRevision === current.revision
+        ? promised.sources.find((s) => s.ref === ref)
+        : undefined;
+    if (expected && expected.bodyHash !== source.hash) {
+      problems.push({
+        ref,
+        code: "source_changed",
+        detail: "The captured source differs from the prepared reservation.",
+      });
+      continue;
+    }
+    full.set(ref, source);
+  }
+  // After a compaction, selected evidence is rebuilt from history only while it is required. Evidence the
+  // Coordinator already received this cycle stays once that ends, so its later requests extend the earlier ones.
+  if (selective)
+    for (const id of options.assessedSinceCompaction ?? [])
+      for (const ref of state.selections.get(id)?.selected ?? []) {
+        const source = sources.byRef.get(ref);
+        if (!full.has(ref) && source && delivered(ref) && !sources.ambiguous.has(ref) && !sources.eligible(ref, state))
+          full.set(ref, source);
+      }
+  // A selected result carries its complete native call group; siblings may be structural only.
+  for (const source of full.values()) {
+    const exchange = sources.exchange(source);
+    if (required.has(source.ref)) problems.push(...exchange.problems, ...representationProblems(source, options.model));
+    for (const sibling of exchange.sources) if (!full.has(sibling.ref)) structural.set(sibling.ref, sibling);
+  }
+  for (const source of structural.values())
+    if (source.message.role === "assistant" && required.size)
+      problems.push(...representationProblems(source, options.model));
+  const unpaired = new Map();
+  // Rendering depends only on the entry and these facts, so a rendering is reused for the same variant.
+  const render = (source) => {
+    const role = source.message.role;
+    const withheld = role === "assistant" && privateReasoning(source, options.view, options.projection, options.model);
+    // A structural worker envelope keeps only its calls for the selected results; worker narration is never evidence.
+    const structuralWorker =
+      role === "assistant" && selective && isWorkerProfile(source.producer) && !full.has(source.ref);
+    // Why a result is not shown, said plainly: "omitted" read as lost evidence, and grok-4.7 Coordinators recovered
+    // results that were shown in full beside it (Task 004 S-005).
+    const omitted =
+      role === "toolResult" && !full.has(source.ref)
+        ? required.has(source.ref)
+          ? "[Selected, but not shown: see the evidence problems in the Cognitive Routing Runtime State]"
+          : isTaskEvidence(source)
+            ? "[Not shown: the worker did not select this result as evidence]"
+            : "[Routing receipt, not shown]"
+        : undefined;
+    const renamed = role === "toolResult" ? unpaired.get(source.message.toolCallId) : undefined;
+    const variant = `${withheld ? 1 : 0}${structuralWorker ? 1 : 0}${omitted ?? 0}${renamed === undefined ? "" : `:${renamed}`}`;
+    let variants = cache.renderings.get(source.entry);
+    if (!variants) cache.renderings.set(source.entry, (variants = new Map()));
+    let rendering = variants.get(variant);
+    if (!rendering) {
+      const renames = new Map();
+      let message = structuredClone(source.message);
+      if (withheld) message = withoutReasoning(message, renames);
+      if (structuralWorker) message.content = message.content.filter((b) => b.type === "toolCall");
+      if (omitted)
+        message = {
+          ...message,
+          content: [{ type: "text", text: omitted }],
+          details: undefined,
+        };
+      if (renamed !== undefined) message = { ...message, toolCallId: renamed };
+      rendering = {
+        message: shareRendering(normalized(message), `${source.entry.id}#${variant}`),
+        ...(renames.size ? { renames: [...renames] } : {}),
+      };
+      variants.set(variant, rendering);
+    }
+    // A reused assistant rendering still tells its results which call ids it unpaired.
+    for (const [from, to] of rendering.renames ?? []) unpaired.set(from, to);
+    return rendering.message;
+  };
+  // Insert resolved historical occurrences before the first later native occurrence, retaining
+  // opaque/common messages in their original order rather than moving user input wholesale.
+  const ordered = sources.ordered(new Map([...structural, ...full]).values());
+  const rank = sources.rank;
+  // Worker evidence admitted after the Coordinator has seen later content is delivered where it was admitted,
+  // with its whole call group, so the Coordinator's already-sent prefix is extended rather than rewritten.
+  const shared = sources.nonWorkerBefore;
+  const activeRefs = new Set(associated.flatMap((i) => (i.source ? [i.source.ref] : [])));
+  const deferredAt = new Map();
+  // Deferred evidence is delivered between call groups: providers such as Anthropic reject anything between a call
+  // and its results. A selection is recorded before Pi stores the select_evidence result, so its admission point is
+  // that result.
+  const afterResults = (at) => {
+    while (sources.entries[at]?.message?.role === "toolResult") at++;
+    return at;
+  };
+  if (selective && (options.admissions || options.resumedAt !== undefined))
+    for (const source of full.values()) {
+      // An attention view omitted required evidence that is no longer in the active context, so after a
+      // resume that evidence is new to the Coordinator: deliver it where the assessment resumed.
+      const resumed =
+        options.resumedAt !== undefined && required.has(source.ref) && !activeRefs.has(source.ref)
+          ? options.resumedAt
+          : undefined;
+      const admitted = options.admissions?.get(source.ref);
+      const latest = admitted === undefined ? resumed : Math.max(admitted, resumed ?? 0),
+        at = latest === undefined ? undefined : afterResults(latest),
+        own = rank.get(source.entry.id) ?? 0;
+      if (at === undefined || at <= own || !isWorkerProfile(source.producer) || shared[at] <= shared[own + 1]) continue;
+      const group = sources.exchange(source).sources;
+      for (const member of group.length ? group : [source])
+        deferredAt.set(member.ref, Math.max(deferredAt.get(member.ref) ?? 0, at));
+    }
+  const historical = ordered.filter((s) => !activeRefs.has(s.ref));
+  const emitted = new Set();
+  let messages = [];
+  const renderedSources = new Map();
+  let cursor = 0;
+  const emit = (source) => {
+    if (!emitted.has(source.ref)) {
+      const message = render(source);
+      messages.push(message);
+      renderedSources.set(message, source);
+      emitted.add(source.ref);
+    }
+  };
+  const pending = [];
+  const place = (source) => (deferredAt.has(source.ref) ? pending.push(source) : emit(source));
+  const deliver = (limit) => {
+    pending.sort(
+      (a, b) =>
+        deferredAt.get(a.ref) - deferredAt.get(b.ref) || (rank.get(a.entry.id) ?? 0) - (rank.get(b.entry.id) ?? 0),
+    );
+    while (pending.length && deferredAt.get(pending[0].ref) <= limit) emit(pending.shift());
+  };
+  for (const item of associated) {
+    if (item.source) {
+      const at = rank.get(item.source.entry.id) ?? 0;
+      deliver(at);
+      while (cursor < historical.length && (rank.get(historical[cursor].entry.id) ?? 0) < at)
+        place(historical[cursor++]);
+      if (full.has(item.source.ref) || structural.has(item.source.ref)) place(item.source);
+    } else messages.push(item.message);
+  }
+  while (cursor < historical.length) place(historical[cursor++]);
+  deliver(Infinity);
+  const fullSources = [...full.values()];
+  // The Coordinator only sees completed worker runs, so one note per run keeps its prefix stable.
+  messages = annotateSources(
+    messages,
+    renderedSources,
+    new Set(full.keys()),
+    sources,
+    options.instance,
+    selective,
+    cache.notes,
+  );
+  // A message may hold its own version for the Coordinator's selective view: Freeflow's carried context names the
+  // worker's copies there instead of repeating them, since the Coordinator receives evidence by selection.
+  if (selective)
+    messages = messages.map((message) => {
+      if (message?.role !== "custom" || typeof message.details?.coordinatorContent !== "string") return message;
+      let version = cache.coordinatorVersions.get(message);
+      if (!version) {
+        version = { ...message, content: message.details.coordinatorContent };
+        const identity = occurrenceIdentity(message);
+        if (identity) shareRendering(version, `${identity}#coordinator`);
+        cache.coordinatorVersions.set(message, version);
+      }
+      return version;
+    });
+  // Restore exact current communication only when its accepted occurrence is absent.
+  const a = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
+  const baseReport = assessment
+    ? state.handoffs.get(assessment.handoffId)
+    : handoff?.kind === "return"
+      ? handoff
+      : undefined;
+  const recovery = state.recoveryId
+    ? state.recoveries.get(state.recoveryId)
+    : [...state.recoveries.values()]
+        .reverse()
+        .find(
+          (candidate) => candidate.assessmentHandoffId === assessment?.handoffId && candidate.state === "completed",
+        );
+  const recoveryRequest = recovery ? state.handoffs.get(recovery.requestHandoffId) : undefined;
+  const supplement =
+    handoff?.kind === "recovery-return"
+      ? handoff
+      : recovery?.supplementHandoffId
+        ? state.handoffs.get(recovery.supplementHandoffId)
+        : undefined;
+  const hasCommunication = (h, field, value, metadata = {}) =>
+    messages.some((m) => {
+      const matches = (payload) =>
+        payload?.[field] === value &&
+        Object.entries(metadata).every(([key, expected]) => canonical(payload?.[key]) === canonical(expected));
+      if (m.role === "assistant")
+        return m.content?.some((b) => b.type === "toolCall" && b.id === h.toolCallId && matches(b.arguments));
+      if (m.role !== "toolResult" || m.toolCallId !== h.toolCallId) return false;
+      return m.content?.some((b) => {
+        if (b.type !== "text") return false;
+        try {
+          return matches(JSON.parse(b.text));
+        } catch {
+          return false;
+        }
+      });
+    });
+  // Current receipts carry metadata plus a text hash, while the text itself stays in the call arguments.
+  const hashedCommunication = (h, field, value, metadata) =>
+    messages.some(
+      (m) =>
+        m.role === "assistant" &&
+        m.content?.some((b) => b.type === "toolCall" && b.id === h.toolCallId && b.arguments?.[field] === value),
+    ) &&
+    messages.some(
+      (m) =>
+        m.role === "toolResult" &&
+        m.toolCallId === h.toolCallId &&
+        m.content?.some((b) => {
+          if (b.type !== "text") return false;
+          try {
+            const payload = JSON.parse(b.text);
+            return (
+              payload?.[`${field}Sha256`] === bodyHash(value) &&
+              Object.entries(metadata).every(([key, expected]) => canonical(payload?.[key]) === canonical(expected))
+            );
+          } catch {
+            return false;
+          }
+        }),
+    );
+  const restore = (kind, id, body) =>
+    messages.push({
+      role: "custom",
+      customType: "freeflow-routing-communication",
+      display: false,
+      content: `${kind} ${id}:\n${body}`,
+      timestamp: 0,
+      details: { routingInstance: options.instance },
+    });
+  if (a) {
+    const accepted = state.handoffs.get(a.delegateHandoffId);
+    if (accepted && !hasCommunication(accepted, "contract", a.contract))
+      // Directly after the contract, so a contract asking for compaction does not read as still undone.
+      restore(
+        "Current exact assignment",
+        a.id,
+        options.compactedInAssignment === undefined
+          ? a.contract
+          : `${a.contract}\n\nCompaction: you compacted during this assignment, and cycle ${options.compactedInAssignment} began then. A compaction this contract asks for is done: continue with the rest of the contract, or return it with return_work if compacting was all it asked.`,
+      );
+  }
+  if (baseReport) {
+    const metadata = { outcome: baseReport.outcome, limitations: baseReport.limitations };
+    const hasBody = hasCommunication(baseReport, "report", baseReport.text);
+    // Tool arguments establish accepted content but do not carry harness-assigned
+    // revision/lineage. Old receipts and partially retained calls need metadata too.
+    const lineage = {
+      ...metadata,
+      reportRevision: baseReport.reportRevision,
+      assignmentRef: `assignment:${baseReport.assignmentId}`,
+      reportRef: `report:${baseReport.id}:${baseReport.reportRevision}`,
+    };
+    const complete =
+      hasCommunication(baseReport, "report", baseReport.text, lineage) ||
+      hashedCommunication(baseReport, "report", baseReport.text, lineage);
+    if (!complete)
+      restore(
+        "Saved report",
+        baseReport.id,
+        `Producer: ${baseReport.from}\nAssignment: assignment:${baseReport.assignmentId}\nReport ref: report:${baseReport.id}:${baseReport.reportRevision}\nRevision: ${baseReport.reportRevision}\nOutcome: ${baseReport.outcome}\nLimitations: ${JSON.stringify(baseReport.limitations)}${hasBody ? "\nReport text is present in its accepted native occurrence above." : `\nReport:\n${baseReport.text}`}`,
+      );
+  }
+  if (recovery && recoveryRequest && !hasCommunication(recoveryRequest, "request", recovery.request))
+    restore(
+      "Recovery request",
+      recovery.id,
+      `Assignment: assignment:${recovery.assignmentId}\nParent report: report:${recovery.assessmentHandoffId}:${recovery.baseReportRevision}\nAllowed paths: ${JSON.stringify(recovery.paths)}\nRequest:\n${recovery.request}`,
+    );
+  if (recovery && supplement) {
+    const hasBody = hasCommunication(supplement, "report", supplement.text);
+    const complete = hasCommunication(supplement, "report", supplement.text, {
+      outcome: supplement.outcome,
+      limitations: supplement.limitations,
+    });
+    if (!complete)
+      restore(
+        "Recovery supplement",
+        recovery.id,
+        `Assignment: assignment:${recovery.assignmentId}\nParent report: report:${recovery.assessmentHandoffId}:${recovery.baseReportRevision}\nSupplement revision: ${supplement.reportRevision}\nOutcome: ${supplement.outcome}\nLimitations: ${JSON.stringify(supplement.limitations)}${hasBody ? "\nSupplement text is present in its accepted native occurrence above." : `\nSupplement:\n${supplement.text}`}`,
+      );
+  }
+  messages.push(options.runtimeMessage);
+  const { estimatedTokens, maximumInputTokens, outputReserve, estimateMethod, warnings } = estimateRequest(
+    options.systemPrompt,
+    options.tools,
+    messages,
+    options.model,
+  );
+  if (warnings.length)
+    messages.push({
+      role: "custom",
+      customType: "freeflow-routing-budget",
+      display: false,
+      content: warnings.map((w) => w.detail).join("\n"),
+      timestamp: 0,
+      details: { routingInstance: options.instance },
+    });
+  if (!options.model?.contextWindow)
+    problems.push({ ref: "", code: "delivery_budget", detail: "Receiving model context capacity is unavailable." });
+  const reservation =
+    handoff && selective
+      ? {
+          id: randomUUID(),
+          selectionRevision: current.revision,
+          receiver: "coordinator",
+          target: options.pair,
+          qualification: `native-structural:${options.model?.api ?? "unknown"}; serialized receipt unobserved`,
+          sources: [...required].flatMap((ref) => {
+            const source = sources.byRef.get(ref);
+            return source ? [{ ref, bodyHash: source.hash }] : [];
+          }),
+          maximumInputTokens,
+          outputReserve,
+          estimateMethod,
+        }
+      : undefined;
+  return {
+    warnings,
+    ready: problems.length === 0,
+    // Recorded usage describes a prior provider view, which may belong to the
+    // other profile. Pi must estimate this assembled view when allocating output.
+    // Normalize request metadata only; canonical usage/billing records stay intact.
+    // Renderings are already normalized; other messages are copied only when they need it.
+    messages: messages.map(normalized),
+    problems,
+    fullSources,
+    reservation,
+    estimatedTokens,
+    estimateMethod,
+  };
+}

package/pi-extension/dist/cognitive-routing/provenance.js

@@ -0,0 +1,83 @@
+import { isWorkerProfile } from "./types.js";
+import { tagDerived } from "../host/projection-tags.js";
+import { isTaskEvidence } from "./sources.js";
+/**
+ * Follow each exchange with a note naming its attributed sources. With `mergeWorkerRuns`, consecutive
+ * exchanges from one worker assignment share a single note after the run. Use it only for a view that
+ * never sees a run still growing, or the note would move on every appended exchange.
+ */
+export function annotateSources(
+  messages,
+  renderedSources,
+  full,
+  sources,
+  instance,
+  mergeWorkerRuns = false,
+  /** Notes kept across requests by content, so an unchanged note keeps one identity and is fingerprinted once. */
+  notes,
+) {
+  const annotated = [];
+  let pending;
+  const flush = () => {
+    if (pending?.rows.length) {
+      const content = `Source provenance for the preceding ${pending.exchanges > 1 ? "worker run" : "message/exchange"}:\n${pending.rows.join("\n")}`;
+      const key = `${instance}\u0000${content}`;
+      let note = notes?.get(key);
+      if (!note) {
+        note = {
+          role: "custom",
+          customType: "freeflow-routing-v2-refs",
+          display: false,
+          content,
+          details: { routingInstance: instance },
+          timestamp: 0,
+        };
+        if (notes) {
+          tagDerived(note, `refs:${key}`);
+          notes.set(key, note);
+        }
+      }
+      annotated.push(note);
+    }
+    pending = undefined;
+  };
+  for (let i = 0; i < messages.length;) {
+    const group = [messages[i++]];
+    while (i < messages.length && messages[i].role === "toolResult") group.push(messages[i++]);
+    const attributed = [];
+    const rows = group.flatMap((message) => {
+      const s = renderedSources.get(message);
+      // Only observed routing attribution is informative; unattributed rows would repeat "unknown" on
+      // every exchange, and omitting them keeps the prefix identical whether routing is on or off.
+      if (!s || s.producer === "common") return [];
+      attributed.push(s);
+      const representation = full.has(s.ref) ? "full" : "structural only; omitted result bodies are not evidence";
+      const selection =
+        isWorkerProfile(s.producer) && isTaskEvidence(s) && full.has(s.ref)
+          ? "task evidence; selection checks apply"
+          : "not offered for new evidence selection";
+      // The call's path or command lets a reader match this ref to the result above it.
+      const label = s.message.toolName ? sources.callLabel(s.ref) : undefined;
+      return [
+        `${s.ref} | producer: ${s.producer} | ${s.message.role}${s.message.toolName ? ` | ${s.message.toolName}${label ? `: ${label}` : ""}` : ""}${s.assignmentId ? ` | assignment: ${s.assignmentId}` : ""} | ${representation} | ${selection}`,
+      ];
+    });
+    const keys = new Set(attributed.map((s) => `${s.producer}\u0000${s.assignmentId ?? ""}`));
+    const key =
+      mergeWorkerRuns && attributed.length && keys.size === 1 && attributed.every((s) => isWorkerProfile(s.producer))
+        ? [...keys][0]
+        : undefined;
+    if (key !== undefined && pending?.key === key) {
+      annotated.push(...group);
+      pending.rows.push(...rows);
+      pending.exchanges++;
+      continue;
+    }
+    flush();
+    annotated.push(...group);
+    pending = { key, rows, exchanges: 1 };
+    if (key === undefined) flush();
+  }
+  flush();
+  return annotated;
+}