@hassangameryt/freeflow 0.7.2 → 0.7.3

package/pi-extension/dist/provider-support/astra/session-state.js

@@ -0,0 +1,114 @@
+import { activeReadOnlySessionBranch, readOnlySessionSnapshot } from "../../session-sources/read-only-session.js";
+import { ENTRY_TYPE, parseAttempt } from "./history.js";
+export class SessionState {
+  pi;
+  reader;
+  acknowledged = new Map();
+  fault;
+  constructor(pi, reader) {
+    this.pi = pi;
+    this.reader = reader;
+  }
+  branch() {
+    const entries = this.reader.getBranch();
+    let parent = null;
+    const seen = new Set();
+    for (const entry of entries) {
+      if (!entry.id || seen.has(entry.id) || entry.parentId !== parent)
+        throw new Error("Invalid Astra session ancestry");
+      seen.add(entry.id);
+      parent = entry.id;
+    }
+    if (parent !== this.reader.getLeafId()) throw new Error("Astra session leaf changed");
+    return entries;
+  }
+  async records() {
+    if (this.fault) throw new Error(this.fault);
+    const branch = this.branch();
+    // Model visits are not history replacement. Derive both identities from the
+    // selected native ancestry so old v1 records remain readable without rewriting them.
+    const boundaries = new Map();
+    let epoch = "root",
+      legacy = "root",
+      model;
+    for (const entry of branch) {
+      if (entry.type === "compaction" || entry.type === "branch_summary") epoch = legacy = entry.id;
+      if (entry.type === "model_change") {
+        const next = `${entry.provider}/${entry.modelId}`;
+        if (model !== next) legacy = entry.id;
+        model = next;
+      }
+      boundaries.set(entry.id, { epoch, legacy });
+    }
+    const entries = branch.filter((e) => e.type === "custom" && e.customType === ENTRY_TYPE);
+    const records = entries.map((e) => {
+      const record = parseAttempt(e.data);
+      if (
+        record.basis !== e.parentId &&
+        !(this.reader.getHeader?.()?.parentSession && !branch.some((entry) => entry.id === record.basis))
+      )
+        throw new Error("Astra attempt anchor mismatch");
+      const boundary = boundaries.get(e.id);
+      if (record.generation !== boundary.epoch && record.generation !== boundary.legacy)
+        throw new Error("Astra history generation unavailable");
+      return { ...record, generation: boundary.epoch };
+    });
+    if (new Set(records.map((r) => r.id)).size !== records.length) throw new Error("Duplicate Astra attempt");
+    const parents = new Map();
+    for (const record of records) {
+      const parent = record.parent === null ? undefined : parents.get(record.parent);
+      if (
+        record.parent !== null &&
+        (!parent ||
+          parent.key !== record.key ||
+          parent.generation !== record.generation ||
+          parent.envelope !== record.envelope ||
+          parent.baseline !== record.baseline ||
+          parent.length > record.length)
+      )
+        throw new Error("Invalid Astra history parent");
+      const expected = record.update?.effort ?? parent?.effective ?? record.baseline;
+      if (record.effective !== expected || (record.update && record.update.at < (parent?.length ?? 0)))
+        throw new Error("Invalid Astra effective effort");
+      parents.set(record.id, record);
+    }
+    const unknown = entries.some((e) => this.acknowledged.get(e.id) !== JSON.stringify(e));
+    const file = this.reader.getSessionFile();
+    if (unknown && file && branch.some((e) => e.type === "message" && e.message?.role === "assistant")) {
+      const sessionId = this.reader.getSessionId(),
+        leaf = this.reader.getLeafId();
+      const snapshot = await readOnlySessionSnapshot(file);
+      const persisted = activeReadOnlySessionBranch(snapshot, leaf);
+      if (
+        snapshot.sessionId !== sessionId ||
+        this.reader.getLeafId() !== leaf ||
+        JSON.stringify(persisted) !== JSON.stringify(branch)
+      )
+        throw new Error("Astra persisted ancestry differs");
+    }
+    for (const entry of entries) this.acknowledged.set(entry.id, JSON.stringify(entry));
+    return records;
+  }
+  generation() {
+    let generation = "root";
+    for (const entry of this.branch()) {
+      if (entry.type === "compaction" || entry.type === "branch_summary") generation = entry.id;
+    }
+    return generation;
+  }
+  append(record) {
+    try {
+      if (this.reader.getLeafId() !== record.basis) throw new Error("Astra request ancestry changed");
+      this.pi.appendEntry(ENTRY_TYPE, record);
+      const entry = this.branch().find(
+        (e) => e.type === "custom" && e.customType === ENTRY_TYPE && e.data?.id === record.id,
+      );
+      if (!entry || entry.parentId !== record.basis || JSON.stringify(entry.data) !== JSON.stringify(record))
+        throw new Error("Astra append not acknowledged");
+      this.acknowledged.set(entry.id, JSON.stringify(entry));
+    } catch (error) {
+      this.fault = "Astra append uncertain; native effort retained until session recovery";
+      throw error;
+    }
+  }
+}

package/pi-extension/dist/provider-support/index.js

@@ -0,0 +1,4 @@
+import { registerAstraSupport } from "./astra/index.js";
+export function registerProviderSupport(pi) {
+  registerAstraSupport(pi);
+}

package/pi-extension/dist/runtime/request-history.js

@@ -0,0 +1,216 @@
+import { createHash, randomUUID } from "node:crypto";
+import { activeReadOnlySessionBranch, readOnlySessionSnapshot } from "../session-sources/read-only-session.js";
+const ENTRY = "freeflow-request-history-v1";
+const TRANSIENT = new Set([
+  "freeflow-runtime-state",
+  "freeflow-cognitive-routing-runtime-state",
+  "freeflow-routing-v2-state",
+  "freeflow-routing-budget",
+  "freeflow-routing-communication",
+]);
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+function fingerprint(message) {
+  const { usage: _usage, timestamp: _timestamp, details: _details, ...body } = message;
+  return hash(body);
+}
+function prefixes(messages) {
+  const result = [hash([])];
+  for (const message of messages) result.push(hash([result.at(-1), fingerprint(message)]));
+  return result;
+}
+function owned(message) {
+  return message?.role === "custom" && TRANSIENT.has(message.customType);
+}
+function parse(value) {
+  if (
+    !value ||
+    value.version !== 1 ||
+    typeof value.id !== "string" ||
+    typeof value.view !== "string" ||
+    typeof value.generation !== "string" ||
+    !(value.basis === null || typeof value.basis === "string") ||
+    !Number.isSafeInteger(value.length) ||
+    value.length < 0 ||
+    !/^[a-f0-9]{64}$/.test(value.prefix) ||
+    !(value.parent === null || typeof value.parent === "string") ||
+    !value.states ||
+    typeof value.states !== "object" ||
+    Array.isArray(value.states) ||
+    !Object.entries(value.states).every(
+      ([key, val]) => TRANSIENT.has(key) && typeof val === "string" && /^[a-f0-9]{64}$/.test(val),
+    ) ||
+    !Array.isArray(value.retained) ||
+    !value.retained.every((x) => typeof x === "string") ||
+    !Array.isArray(value.additions) ||
+    !value.additions.every((x) => Number.isSafeInteger(x.at) && x.at >= 0 && x.at <= value.length && owned(x.message))
+  )
+    throw new Error("Invalid Freeflow context history");
+  return value;
+}
+/** Preserve only Freeflow-generated occurrences. Native content remains owned by Pi and its projectors. */
+export class RequestHistory {
+  pi;
+  acknowledged = new Map();
+  identity;
+  fault = false;
+  serial = Promise.resolve();
+  revision = 0;
+  constructor(pi) {
+    this.pi = pi;
+  }
+  reset() {
+    this.revision++;
+    this.acknowledged.clear();
+    this.identity = undefined;
+    this.fault = false;
+  }
+  async assemble(messages, view, ctx, notice) {
+    const revision = this.revision;
+    const operation = this.serial.then(async () => {
+      if (revision !== this.revision) return messages;
+      try {
+        return await this.prepare(messages, view, ctx, revision, notice);
+      } catch {
+        try {
+          ctx.ui?.setStatus?.("freeflow-cache", "Freeflow context replay unavailable · current view retained");
+        } catch {}
+        // Keep the already-qualified projected view on failure, never raw hidden history.
+        return messages;
+      }
+    });
+    this.serial = operation.catch(() => {});
+    return operation;
+  }
+  async prepare(messages, view, ctx, revision, notice) {
+    const reader = ctx.sessionManager;
+    if (!reader?.getBranch || !reader.getLeafId || !reader.getSessionId || !this.pi.appendEntry) return messages;
+    const identity = `${reader.getSessionId()}:${reader.getSessionFile?.() ?? "memory"}`;
+    if (this.identity !== identity) {
+      this.acknowledged.clear();
+      this.fault = false;
+      this.identity = identity;
+    }
+    if (this.fault) throw new Error("Uncertain Freeflow context append");
+    const branch = reader.getBranch(),
+      leaf = reader.getLeafId();
+    let parent = null,
+      generation = "root";
+    const ids = new Set();
+    for (const entry of branch) {
+      if (entry.parentId !== parent || ids.has(entry.id)) throw new Error("Invalid context ancestry");
+      parent = entry.id;
+      ids.add(entry.id);
+      if (entry.type === "compaction" || entry.type === "branch_summary") generation = entry.id;
+    }
+    if (parent !== leaf) throw new Error("Context leaf changed");
+    const entries = branch.filter((e) => e.type === "custom" && e.customType === ENTRY);
+    if (
+      entries.some((e) => this.acknowledged.get(e.id) !== hash(e)) &&
+      reader.getSessionFile?.() &&
+      branch.some((e) => e.message?.role === "assistant")
+    ) {
+      const snapshot = await readOnlySessionSnapshot(reader.getSessionFile());
+      if (
+        snapshot.sessionId !== reader.getSessionId() ||
+        JSON.stringify(activeReadOnlySessionBranch(snapshot, leaf)) !== JSON.stringify(branch)
+      )
+        throw new Error("Context history readback differs");
+    }
+    if (revision !== this.revision || reader.getLeafId() !== leaf) throw new Error("Context changed while preparing");
+    const frames = [],
+      byId = new Map();
+    for (const entry of entries) {
+      const frame = parse(entry.data);
+      if (
+        (frame.basis !== entry.parentId && !(reader.getHeader?.()?.parentSession && !ids.has(frame.basis))) ||
+        byId.has(frame.id)
+      )
+        throw new Error("Context frame anchor differs");
+      const previous = frame.parent ? byId.get(frame.parent) : undefined;
+      if (frame.parent && (!previous || previous.generation !== frame.generation || previous.length > frame.length))
+        throw new Error("Context frame parent missing");
+      frames.push(frame);
+      byId.set(frame.id, frame);
+      this.acknowledged.set(entry.id, hash(entry));
+    }
+    const base = messages.filter((m) => !owned(m));
+    const current = messages
+      .filter(owned)
+      .filter((message) => !notice || message.customType !== "freeflow-routing-budget");
+    const hashes = prefixes(base);
+    const candidates = frames.filter((f) => f.generation === generation && hashes[f.length] === f.prefix);
+    const prior = candidates.reduce((best, f) => (!best || f.length >= best.length ? f : best), undefined);
+    const states = { ...prior?.states },
+      additions = [];
+    const seenRetained = new Set(prior?.retained ?? []);
+    for (const message of current) {
+      const signature = fingerprint(message),
+        kind = message.customType;
+      if (kind === "freeflow-routing-communication" ? seenRetained.has(signature) : states[kind] === signature)
+        continue;
+      additions.push({ at: base.length, message: structuredClone(message) });
+      if (kind === "freeflow-routing-communication") seenRetained.add(signature);
+      else states[kind] = signature;
+    }
+    const injections = [];
+    const chain = [];
+    for (let cursor = prior; cursor; cursor = cursor.parent ? byId.get(cursor.parent) : undefined)
+      chain.unshift(cursor);
+    for (const frame of chain) injections.push(...frame.additions);
+    injections.push(...additions);
+    const result = [];
+    let next = 0;
+    for (let i = 0; i <= base.length; i++) {
+      while (injections[next]?.at === i) result.push(structuredClone(injections[next++].message));
+      if (i < base.length) result.push(base[i]);
+    }
+    if (next !== injections.length) throw new Error("Context anchor ordering differs");
+    if (notice) {
+      const warning = notice(result);
+      if (warning || states["freeflow-routing-budget"]) {
+        const message = warning ?? {
+          role: "custom",
+          customType: "freeflow-routing-budget",
+          display: false,
+          content: "Routing budget warning cleared for the current request.",
+          timestamp: 0,
+        };
+        const signature = fingerprint(message);
+        if (states[message.customType] !== signature) {
+          states[message.customType] = signature;
+          additions.push({ at: base.length, message });
+          result.push(message);
+        }
+      }
+    }
+    if (!prior || prior.length !== base.length || additions.length) {
+      const frame = {
+        version: 1,
+        id: randomUUID(),
+        basis: leaf,
+        view,
+        generation,
+        length: base.length,
+        prefix: hashes.at(-1),
+        parent: prior?.id ?? null,
+        states,
+        retained: [...seenRetained],
+        additions,
+      };
+      try {
+        this.pi.appendEntry(ENTRY, frame);
+        const entry = reader.getBranch().find((e) => e.customType === ENTRY && e.data?.id === frame.id);
+        if (!entry || entry.parentId !== leaf || JSON.stringify(entry.data) !== JSON.stringify(frame))
+          throw new Error("Context append not acknowledged");
+        this.acknowledged.set(entry.id, hash(entry));
+      } catch (error) {
+        this.fault = true;
+        throw error;
+      }
+    }
+    try {
+      ctx.ui?.setStatus?.("freeflow-cache", undefined);
+    } catch {}
+    return result;
+  }
+}

package/pi-extension/dist/runtime/runtime-context.js

@@ -50,6 +50,12 @@ export const FREEFLOW_MODEL_SKILL_NAMES = [
   "write-skill",
   "write-spec",
 ];
+export const STABLE_FREEFLOW_SURFACE = Object.freeze({
+  enabled: true,
+  cognitiveRouting: { effective: true },
+  contextVirtualization: { effective: true },
+  conversationHistory: { effective: true },
+});
 export const FREEFLOW_CAPABILITY_SKILL_NAMES = ["cognitive-routing", "context-virtualization", "conversation-history"];
 export function freeflowSkillPath(skillName) {
   return fileURLToPath(new URL(`../../../skills/${skillName}/SKILL.md`, import.meta.url));
@@ -498,11 +504,7 @@ export function setFreeflowStatus(
     active.push(`cognitive blocked · ${cognitiveRoutingRuntime?.runtimeReason ?? "runtime_blocked"}`);
   } else if (cognitiveRoutingActive) {
     const profile = cognitiveRoutingRuntime.activeProfile;
-    const control =
-      cognitiveRoutingRuntime.controlMode === "manual-executor" ||
-      cognitiveRoutingRuntime.controlMode === "manual-coordinator"
-        ? "manual hold"
-        : "automatic";
+    const control = String(cognitiveRoutingRuntime.controlMode).startsWith("manual-") ? "manual hold" : "automatic";
     active.push(`${profile} · ${control}`);
   } else if (cognitiveRouting?.enabled === true) {
     if (cognitiveRouting.blockingReason?.code === "runtime_disabled") {
@@ -537,12 +539,12 @@ export function skillPrompt(skill, args) {
 }
 function publicCognitiveRoutingControl(controlMode) {
   if (controlMode === "automatic") return "automatic";
-  if (controlMode === "manual-executor" || controlMode === "manual-coordinator") return "manual";
+  if (["manual-helper", "manual-executor", "manual-coordinator"].includes(controlMode)) return "manual";
   return "unavailable";
 }
 function publicCognitiveRoutingProfile(activeProfile, effective) {
   if (effective !== true) return "unavailable";
-  return activeProfile === "executor" || activeProfile === "coordinator" ? activeProfile : "unavailable";
+  return ["helper", "executor", "coordinator"].includes(activeProfile) ? activeProfile : "unavailable";
 }
 function publicCapabilityStatus(capability) {
   if (capability?.effective === true) return "active";
@@ -558,9 +560,7 @@ function publicCognitiveRoutingStatus(capability, runtime) {
 function publicCognitiveRoutingProjectionMode(capability, runtime, projectionFailure) {
   if (capability?.projection !== true) return "disabled";
   if (capability?.effective !== true) return "unavailable";
-  if (runtime?.controlMode === "manual-executor" || runtime?.controlMode === "manual-coordinator") {
-    return "manual-bypass";
-  }
+  if (String(runtime?.controlMode).startsWith("manual-")) return "manual-bypass";
   if (projectionFailure) return "blocked";
   if (runtime?.runtimeStatus === "inactive" || runtime?.runtimeStatus === "blocked") return "unavailable";
   if (runtime?.effective === true && runtime.controlMode === "automatic") return "enabled";
@@ -612,6 +612,7 @@ export function freeflowRuntimeStateMessage(
       "Cognitive Routing:",
       `- Control: \`${control}\``,
       `- Profile: \`${profile}\``,
+      `- Delegation: \`${capabilityState?.cognitiveRouting?.delegation ?? "executor"}\``,
       `- Projection: \`${projectionMode}\``,
     ].join("\n"),
     display: false,
@@ -664,6 +665,24 @@ export function withFreeflowRuntimeState(
   if (unchanged) return source;
   return insertRuntimeStateBeforeLatestUser(withoutRuntimeState, runtimeState);
 }
+export function stableRuntimeContext(context) {
+  const sections = [
+    ["Freeflow core", context?.corePrompt],
+    ["Freeflow core", context?.interactionContractPrompt],
+    ["Cognitive Routing", context?.cognitiveRoutingPrompt],
+    ["Context Virtualization", context?.contextVirtualizationPrompt],
+    ["Conversation History", context?.conversationHistoryPrompt],
+  ];
+  return [
+    "# Freeflow availability contract",
+    "Freeflow keeps a fixed reference catalog of its instructions, skills, and tools to preserve prompt caching. Presence in this catalog does not mean a feature is active or an operation is permitted.",
+    "Apply the following guidance and Freeflow skills only when the latest extension-generated Freeflow Runtime State marks the corresponding feature active. When Freeflow is inactive, unavailable, or not configured, its core and capability guidance is dormant; do not bootstrap or follow it merely because it is listed. Explicit user instructions retain their normal authority.",
+    "For Cognitive Routing, follow the latest control/profile/responsibility snapshots on this branch. Earlier snapshots and notices are historical; they grant no current permission. Tool permissions are checked by the runtime, even though all definitions remain visible. Never call a disabled operation.",
+    ...sections
+      .filter(([, text]) => isPromptAvailable(text))
+      .map(([feature, text]) => `## Reference guidance: ${feature}\n\n${text.trim()}`),
+  ].join("\n\n");
+}
 export function runtimeContext(freeflowContext, capabilityState) {
   if (
     capabilityState?.configured !== true ||

package/pi-extension/dist/session-sources/events.js

@@ -91,6 +91,28 @@ export class EventStore {
         this.ready = true;
         return;
       }
+      // Pi defers creating a new session file until its first assistant message.
+      // Before that flush boundary, the complete in-memory native session is the
+      // only available source; uncertain appends still require persisted readback.
+      const preFlush =
+        !this.attempted.size &&
+        !this.reader.getEntries().some((entry) => entry.type === "message" && entry.message?.role === "assistant");
+      if (preFlush) {
+        replay(branch);
+        const known = new Map();
+        for (const entry of branch) {
+          if (entry.type === "custom" && entry.customType === ROUTING_ENTRY) {
+            const event = parseRoutingEvent(entry.data);
+            known.set(eventKey(event), { value: eventValue(event), eventId: event.eventId, entryId: entry.id });
+          }
+        }
+        this.observed = known;
+        this.fault = undefined;
+        this.ready = true;
+        this.cachedEntries = [];
+        this.cachedState = replay([]);
+        return;
+      }
       const path = this.reader.getSessionFile();
       check(path, "persisted_snapshot_unavailable", "Existing or uncertain routing state needs a persisted snapshot.");
       const snapshot = await readOnlySessionSnapshot(path);

package/pi-extension/dist/session-sources/provenance.js

@@ -0,0 +1,32 @@
+import { isWorkerProfile } from "../cognitive-routing-v2/types.js";
+import { isTaskEvidence, textRef } from "./sources.js";
+export function annotateSources(messages, renderedSources, full, sources, instance) {
+  const annotated = [];
+  for (let i = 0; i < messages.length;) {
+    const group = [messages[i++]];
+    while (i < messages.length && messages[i].role === "toolResult") group.push(messages[i++]);
+    const rows = group.flatMap((message) => {
+      const s = renderedSources.get(message);
+      if (!s) return [];
+      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";
+      return [
+        `${s.ref} | producer: ${s.producer === "common" ? "unknown/common (no observed routing profile)" : s.producer} | ${s.original ? "assistant-text" : s.message.role}${s.message.toolName ? ` | ${s.message.toolName}` : ""}${s.assignmentId ? ` | assignment: ${s.assignmentId}` : ""} | ${representation} | ${selection}${!s.original && full.has(s.ref) && sources.byRef.has(textRef(s.ref)) ? ` | visible text: ${textRef(s.ref)}` : ""}`,
+      ];
+    });
+    annotated.push(...group);
+    if (rows.length)
+      annotated.push({
+        role: "custom",
+        customType: "freeflow-routing-v2-refs",
+        display: false,
+        content: `Source provenance for the preceding message/exchange:\n${rows.join("\n")}`,
+        details: { routingInstance: instance },
+        timestamp: 0,
+      });
+  }
+  return annotated;
+}

package/pi-extension/dist/session-sources/sources.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
-import { canonical, idFor, refFor } from "../cognitive-routing-v2/types.js";
+import { canonical, idFor, isWorkerProfile, refFor } from "../cognitive-routing-v2/types.js";
 export const bodyHash = (value) => createHash("sha256").update(canonical(value)).digest("hex");
 export const textRef = (ref) => `${ref}#text`;
 const routingTools = new Set(["freeflow_delegate", "freeflow_return", "freeflow_project", "freeflow_unit"]);
@@ -16,6 +16,25 @@ export function isTaskEvidence(source) {
   );
 }
 const callKey = (id, name) => JSON.stringify([id, name]);
+const locatorLimit = 160;
+function normalizeLabel(value) {
+  if (typeof value !== "string") return undefined;
+  const clean = value
+    .replace(/[\u0000-\u001f\u007f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!clean) return undefined;
+  if (clean.length <= locatorLimit) return { label: clean, truncated: false };
+  return { label: `${clean.slice(0, locatorLimit - 3)}...`, truncated: true };
+}
+function locatorForCall(assistant, call, locatorProvider) {
+  if (typeof assistant.ref !== "string" || typeof call.id !== "string" || typeof call.name !== "string")
+    return undefined;
+  const locator = { callRef: assistant.ref, toolCallId: call.id };
+  const details = locatorProvider?.(assistant, call);
+  const label = normalizeLabel(details?.label);
+  return label ? { ...locator, ...label, truncated: details?.truncated === true || label.truncated } : locator;
+}
 export class Sources {
   byRef = new Map();
   ambiguous = new Set();
@@ -26,7 +45,9 @@ export class Sources {
   associated;
   entries = [];
   activeIds;
-  constructor(entries, state, activeIds) {
+  locatorProvider;
+  constructor(entries, state, activeIds, locatorProvider) {
+    this.locatorProvider = locatorProvider;
     this.refresh(entries, state, activeIds);
   }
   refresh(entries, state, activeIds) {
@@ -59,7 +80,11 @@ export class Sources {
           if (block.type === "text") {
             try {
               const receipt = JSON.parse(block.text);
-              if (receipt.reportSaved && typeof receipt.report === "string" && typeof receipt.handoff === "string")
+              if (
+                ((receipt.reportSaved && typeof receipt.report === "string") ||
+                  (receipt.supplementSaved && typeof receipt.supplement === "string")) &&
+                typeof receipt.handoff === "string"
+              )
                 source.reportHandoff = receipt.handoff;
             } catch {}
           }
@@ -123,7 +148,15 @@ export class Sources {
     this.ambiguous.clear();
     for (const source of this.byRef.values()) source.active = false;
     const used = new Set(),
-      hashes = messages.map(bodyHash),
+      hashes = messages.map((message) => {
+        const direct = bodyHash(message);
+        if (this.byBody.has(direct) || message?.role !== "toolResult" || !Array.isArray(message.content)) return direct;
+        const last = message.content.at(-1);
+        if (last?.type !== "text") return direct;
+        const original = bodyHash({ ...message, content: message.content.slice(0, -1) });
+        // Freeflow's stable reference decoration does not change the native evidence body.
+        return this.byBody.get(original)?.some((s) => last.text === `[context-ref: ${s.ref}]`) ? original : direct;
+      }),
       remaining = new Map();
     for (const hash of hashes) remaining.set(hash, (remaining.get(hash) ?? 0) + 1);
     const items = messages.map((message, index) => {
@@ -162,13 +195,13 @@ export class Sources {
         code: "source_changed",
         detail: "The captured source changed; reconcile evidence before delivery.",
       };
-    if (source.producer !== "executor")
-      return { ref, code: "source_origin", detail: "Selection requires observed Executor attribution." };
+    if (!isWorkerProfile(source.producer))
+      return { ref, code: "source_origin", detail: "Selection requires observed worker attribution." };
     if (state.exposure.get(original.ref) !== original.hash && state.exposure.get(source.ref) !== source.hash)
       return {
         ref,
         code: "source_unexposed",
-        detail: "The captured body has not been fully exposed to Executor on this ancestry.",
+        detail: "The captured body has not been fully exposed to a worker on this ancestry.",
       };
     return undefined;
   }
@@ -222,6 +255,17 @@ export class Sources {
     }
     return { sources, problems };
   }
+  locator(ref) {
+    const source = this.byRef.get(ref);
+    if (!source || source.original || source.message.role !== "toolResult") return undefined;
+    const group = this.owners.get(source.ref);
+    if (!group) return undefined;
+    const calls = group.assistant.message.content?.filter((b) => b.type === "toolCall") ?? [];
+    const matches = calls.filter(
+      (call) => call.id === source.message.toolCallId && call.name === source.message.toolName,
+    );
+    return matches.length === 1 ? locatorForCall(group.assistant, matches[0], this.locatorProvider) : undefined;
+  }
   ordered(sources) {
     const ids = new Set([...sources].map((s) => s.ref));
     return this.entries.flatMap((entry) =>