@hassangameryt/freeflow 0.7.3 → 0.9.0

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

@@ -0,0 +1,417 @@
+import { randomUUID } from "node:crypto";
+import { viewHoldsSkill } from "./bootstrap.js";
+import { estimateRequest } from "./budget.js";
+import { prepareView } from "./projection.js";
+import { annotateSources } from "./provenance.js";
+import { ROUTING_SCHEMAS } from "./schemas.js";
+import { ROUTING_RECOVERY_HINT } from "./session.js";
+import { deliveredSelection } from "./sources.js";
+import {
+  ROUTING_ATTENTION_MESSAGE,
+  ROUTING_ENTRY,
+  ROUTING_MESSAGE,
+  ROUTING_TOOLS,
+  emptySelection,
+  isWorkerProfile,
+  requireCondition as check,
+  samePair,
+} from "./types.js";
+import { cachedBranch } from "../host/branch.js";
+/**
+ * Builds each routed request: finds the last delivered user input, opens the execution for the prepared profile,
+ * prepares that profile's view with its Runtime State message and admitted evidence, and records newly exposed
+ * worker sources. Requests outside automatic routing get source annotations only.
+ */
+export class ContextAssembler {
+  session;
+  pi;
+  models;
+  constructor(session, pi, models) {
+    this.session = session;
+    this.pi = pi;
+    this.models = models;
+  }
+  lastDeliveredUser(sources, messages) {
+    const delivered = new Set(
+      sources.associate(messages).flatMap((x) => (x.source?.message.role === "user" ? [x.source.entry.id] : [])),
+    );
+    // Compaction may remove every user message from the active view. Retain
+    // observed delivery on this ancestry; a stored but undelivered user entry
+    // must not advance the basis, and absence must not manufacture new input.
+    for (const execution of this.session.stateData().executions.values())
+      if (execution.basisUserEntryId) delivered.add(execution.basisUserEntryId);
+    for (let i = sources.entries.length - 1; i >= 0; i--) {
+      const entry = sources.entries[i];
+      if (entry.message?.role === "user" && delivered.has(entry.id)) return entry.id;
+    }
+    return null;
+  }
+  runtimeMessage(state, attention = false) {
+    const a = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
+    const h = state.pendingId
+      ? state.handoffs.get(state.pendingId)
+      : state.assessment
+        ? state.handoffs.get(state.assessment.handoffId)
+        : undefined;
+    const selection = a ? (state.selections.get(a.id) ?? emptySelection()) : emptySelection();
+    const recovery = state.recoveryId ? state.recoveries.get(state.recoveryId) : undefined;
+    const unit = state.unitId ? state.units.get(state.unitId) : undefined;
+    const unitNumber = unit ? [...state.units.keys()].indexOf(unit.id) + 1 : undefined;
+    const assignmentNumber = unit && a ? unit.assignmentIds.indexOf(a.id) + 1 : undefined;
+    const worker = a ? state.handoffs.get(a.delegateHandoffId)?.to : undefined;
+    const prepared = state.assessment?.reservation?.selectionRevision;
+    // Only material, decision-bearing fields: every change appends a new copy to request history.
+    // Control, delegation and projection belong to the Freeflow Runtime State; ids are available through inspection.
+    const evidence = a
+      ? [
+          `Evidence: revision ${selection.revision}; selected ${selection.selected.join(", ") || "none"}`,
+          selection.unresolved.length
+            ? `unresolved ${selection.unresolved.map((p) => `${p.ref} (${p.code})`).join(", ")}`
+            : "",
+          selection.withdrawals.length ? `withdrawn ${selection.withdrawals.length}` : "",
+          prepared !== undefined && prepared !== selection.revision ? `prepared revision ${prepared}` : "",
+        ]
+          .filter(Boolean)
+          .join("; ")
+      : "";
+    const content = [
+      "# Cognitive Routing Runtime State",
+      `Profile: ${state.profile ?? "unresolved"}`,
+      state.profile === "coordinator" ? workerCompaction(cachedBranch(this.session.ctx?.sessionManager) ?? []) : "",
+      `Unit: ${unit ? `U${unitNumber}` : "none"}`,
+      `Assignment: ${a ? `A${assignmentNumber} (${worker ?? "unknown"}, ${a.state})` : "none"}`,
+      `Handoff: ${h ? `${h.kind} ${h.state}` : "none"}`,
+      state.assessment ? `Assessment: ${state.assessment.view}` : "",
+      recovery
+        ? `Recovery: ${recovery.state}; parent report revision ${recovery.baseReportRevision}; allowed paths ${JSON.stringify(recovery.paths)}; allowed results ${JSON.stringify((recovery.results ?? []).map((grant) => grant.id))}`
+        : "",
+      recovery?.state === "reading"
+        ? `Recovery request: ${recovery.request}\nOnly exact allowed read paths, granted captured results, evidence selection, and recovery return controls are permitted; ordinary task work remains ended.`
+        : "",
+      evidence,
+      this.session.error ? `Blocked: ${this.session.error}` : "",
+      this.session.projectionError ? `Evidence limitation: ${this.session.projectionError}` : "",
+      attention
+        ? recovery
+          ? `Assessment paused for attention; ordinary admitted history remains. ${selection.selected.length} sources remain selected. Finish and deliver the recovery supplement or cancel recovery before using routing_unit assess.`
+          : `Assessment paused for attention; ordinary admitted history remains. ${selection.selected.length} sources remain selected. Use routing_unit assess to restore the assessment.`
+        : "",
+      a?.state === "returned" && recovery?.state !== "reading"
+        ? "Worker ordinary task work has ended. Only supported handoff correction is permitted."
+        : "",
+      // After a compaction the routing skill may be out of view, and Haiku 5.5 workers then answered as Coordinator
+      // and ended without returning; Coordinator saw only "outstanding" and waited (Task 008 S-005).
+      state.control === "automatic" && a?.state === "outstanding" && worker && state.profile === worker
+        ? `You are ${label(worker)}: carry out A${assignmentNumber} from its delegate_work contract, then hand it back with return_work. Coordinator receives nothing until you return.`
+        : "",
+      state.control === "automatic" && a?.state === "outstanding" && worker && state.profile === "coordinator"
+        ? `${label(worker)}'s run on A${assignmentNumber} ended without return_work, so nothing was handed back. Send it again with delegate_work replace, close the unit, or ask the user.`
+        : "",
+      // Worker calls reach the Coordinator as assistant turns; Haiku 5.5 took them for its own (Task 008 S-005).
+      state.profile === "coordinator" && state.assessment
+        ? "The worker's run appears in your view as assistant turns: those calls are the worker's, as the source provenance after the run says, not yours."
+        : "",
+      // Selected bodies are not re-sent with the return; they stay where the worker produced them (Task 004 S-005).
+      state.profile === "coordinator" && state.assessment && selection.selected.length
+        ? "Selected evidence is already in your view, in place in the worker's run: the source provenance after the run names each selected ref's call (its path or command) and marks it `task evidence`. Recover only evidence the assessment needs that is not there."
+        : "",
+      isWorkerProfile(this.session.turn?.profile) &&
+      a &&
+      this.session.turn.basisUserEntryId !== this.session.workerBasis(state, a.id)
+        ? `Current input differs from the active ${this.session.turn.profile} responsibility. Account for it; changed direction requires Coordinator attention.`
+        : "",
+      ...(state.assessment?.problems ?? []).map((p) => `${p.code}: ${p.detail}`),
+    ]
+      .filter(Boolean)
+      .join("\n");
+    return {
+      role: "custom",
+      customType: ROUTING_MESSAGE,
+      content,
+      display: false,
+      timestamp: 0,
+      details: { routingInstance: this.session.token },
+    };
+  }
+  evidenceFacts(state) {
+    const selection = state.assignmentId
+      ? (state.selections.get(state.assignmentId) ?? emptySelection())
+      : emptySelection();
+    const sources = this.session.sources(state);
+    return {
+      revision: selection.revision,
+      selected: selection.selected
+        .filter((ref) => deliveredSelection(sources, ref))
+        .map((ref) => {
+          const entry = this.session.ctx?.sessionManager.getEntry?.(ref.slice(4));
+          const locator = sources.locator(ref);
+          return {
+            ref,
+            kind: entry?.message?.role ?? "unknown",
+            toolName: entry?.message?.toolName,
+            producer: state.authors.get(entry?.id)?.profile ?? "common",
+            assignment: state.authors.get(entry?.id)?.assignmentId,
+            ...(locator ? { locator } : {}),
+          };
+        }),
+      unresolved: selection.unresolved,
+      withdrawals: selection.withdrawals,
+      preparedRevision: state.assessment?.reservation?.selectionRevision,
+      limitations: state.assessment?.problems ?? [],
+    };
+  }
+  admissionCache;
+  /**
+   * Source rank at which each currently selected ref was first admitted, derived from native selection events,
+   * the rank at which the current assessment last resumed from an attention suspension, and the assignments whose
+   * return or supplement the Coordinator received since the latest compaction.
+   */
+  admissions(state) {
+    const reader = this.session.ctx.sessionManager,
+      leaf = reader.getLeafId?.() ?? null;
+    const cache = this.admissionCache;
+    if (cache && cache.state === state && cache.leaf === leaf) return cache;
+    const admissions = new Map();
+    const assessedSinceCompaction = new Set();
+    let rank = 0,
+      resumedAt,
+      suspension;
+    for (const entry of cachedBranch(reader)) {
+      if (entry.type === "compaction") assessedSinceCompaction.clear();
+      if (["message", "custom_message", "compaction", "branch_summary"].includes(entry.type)) rank++;
+      else if (entry.type === "custom" && entry.customType === ROUTING_ENTRY) {
+        const data = entry.data?.data;
+        if (data?.type === "assessment-suspended" && data.handoffId === state.assessment?.handoffId)
+          suspension = data.reason;
+        // A recovery during user attention leaves that attention outstanding, as the reducer does.
+        if (
+          data?.type === "recovery-request-accepted" &&
+          data.recovery?.assessmentHandoffId === state.assessment?.handoffId &&
+          suspension !== "user-attention"
+        )
+          suspension = "recovery";
+        // After a recovery alone the Coordinator resumes the view it last saw, since it made no requests while
+        // suspended: only a suspension it kept working through (user attention) leaves evidence new to it at the resume.
+        if (data?.type === "assessment-resumed" && data.handoffId === state.assessment?.handoffId) {
+          if (suspension !== "recovery") resumedAt = rank;
+          suspension = undefined;
+        }
+        if (data?.type === "return-accepted" || data?.type === "recovery-supplement-accepted")
+          assessedSinceCompaction.add(data.handoff.assignmentId);
+        if (data?.type !== "selection-changed") continue;
+        const current = state.selections.get(data.assignmentId)?.selected ?? [];
+        for (const ref of data.selection?.selected ?? [])
+          if (current.includes(ref) && !admissions.has(ref)) admissions.set(ref, rank);
+      }
+    }
+    this.admissionCache = { state, leaf, admissions, resumedAt, assessedSinceCompaction };
+    return this.admissionCache;
+  }
+  prepared(profile, input, handoffId, restoring = false) {
+    const state = this.session.stateData(),
+      model = this.models.model(profile);
+    return prepareView({
+      ...(({ admissions, resumedAt, assessedSinceCompaction }) => ({
+        admissions,
+        resumedAt,
+        assessedSinceCompaction,
+      }))(this.admissions(state)),
+      messages: input,
+      sources: this.session.sources(state),
+      state,
+      view: profile,
+      projection: this.session.projectionEnabled,
+      model,
+      pair: this.session.profilePair(profile),
+      systemPrompt: this.session.ctx.getSystemPrompt?.() ?? "",
+      tools: (this.pi.getAllTools?.() ?? [])
+        .filter((tool) => this.pi.getActiveTools?.().includes(tool.name))
+        .map((tool) =>
+          ROUTING_TOOLS.includes(tool.name) ? { ...tool, parameters: ROUTING_SCHEMAS[tool.name] } : tool,
+        ),
+      runtimeMessage: this.runtimeMessage(
+        state,
+        profile === "coordinator" && state.assessment?.view === "suspended" && !restoring && !handoffId,
+      ),
+      instance: this.session.token,
+      preparingReturn: handoffId,
+      restoring,
+      compactedInAssignment: compactedInAssignment(
+        cachedBranch(this.session.ctx?.sessionManager) ?? [],
+        state.assignmentId,
+      ),
+      cache: this.session.viewCache,
+    });
+  }
+  budgetNotice(messages, ctx) {
+    if (!this.session.supported()) return;
+    const tools = (this.pi.getAllTools?.() ?? []).filter((tool) => this.pi.getActiveTools?.().includes(tool.name));
+    const estimate = estimateRequest(ctx.getSystemPrompt?.() ?? "", tools, messages, ctx.model);
+    if (!estimate.warnings.length) return;
+    return {
+      role: "custom",
+      customType: "freeflow-routing-budget",
+      display: false,
+      content: estimate.warnings.map((warning) => warning.detail).join("\n"),
+      timestamp: 0,
+    };
+  }
+  ordinaryContext(input) {
+    try {
+      const sources = this.session.sources(),
+        associated = sources.associate(input);
+      const mapped = new Map(associated.filter((item) => item.source).map((item) => [item.message, item.source]));
+      return annotateSources(
+        input,
+        mapped,
+        new Set([...mapped.values()].map((source) => source.ref)),
+        sources,
+        this.session.token,
+      );
+    } catch {
+      return input;
+    }
+  }
+  async context(ctx, incoming) {
+    this.session.ctx = ctx;
+    const input = incoming.filter(
+      (m) =>
+        !(
+          m?.details?.routingInstance === this.session.token &&
+          [ROUTING_MESSAGE, ROUTING_ATTENTION_MESSAGE, "freeflow-routing-v2-refs"].includes(m.customType)
+        ),
+    );
+    this.session.messages = input;
+    if (!this.session.supported() || !this.session.store) return this.ordinaryContext(input);
+    try {
+      const state = this.session.stateData();
+      if (state.control !== "automatic") return this.ordinaryContext(input);
+      check(
+        !this.session.error && !this.session.store.blocked && state.profile,
+        "routing_blocked",
+        this.session.error ?? this.session.store.blocked,
+      );
+      this.session.announced = undefined;
+      check(samePair(this.session.observed(), this.session.profilePair(state.profile)), "prepared_pair_mismatch");
+      const sources = this.session.sources(state),
+        user = this.lastDeliveredUser(sources, input);
+      if (state.assessment && user && user !== state.assessment.basisUserEntryId)
+        this.session.append(
+          {
+            type: "assessment-suspended",
+            handoffId: state.assessment.handoffId,
+            reason: "user-attention",
+            basisUserEntryId: user,
+            problems: [],
+          },
+          JSON.stringify(["attention", state.assessment.handoffId, user]),
+        );
+      // New input reaching an already prepared worker request cannot be rerouted by changing only the live model.
+      const outstanding = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
+      const worker = outstanding ? this.session.assignedWorker(state, outstanding.id) : undefined;
+      const interrupted =
+        isWorkerProfile(state.profile) &&
+        (state.profile !== worker ||
+          user !== (outstanding ? this.session.workerBasis(state, outstanding.id) : undefined));
+      if (!this.session.turn || this.session.turn.bound) {
+        this.session.receipts.clear();
+        const execution = {
+          id: randomUUID(),
+          profile: state.profile,
+          assignmentId: state.assignmentId,
+          recoveryId: state.recoveryId,
+          basisUserEntryId: user,
+          pair: this.session.observed(),
+          resultEntryIds: [],
+        };
+        const before = new Set(cachedBranch(ctx.sessionManager).map((e) => e.id));
+        this.session.turn = {
+          id: execution.id,
+          profile: execution.profile,
+          assignmentId: execution.assignmentId,
+          recoveryId: execution.recoveryId,
+          basisUserEntryId: user,
+          before,
+          pair: execution.pair,
+        };
+        this.session.openTurn();
+      }
+      let prepared = this.prepared(state.profile, input);
+      if (!prepared.ready && state.profile === "coordinator" && this.session.stateData().assessment) {
+        const assessment = this.session.stateData().assessment;
+        this.session.append({
+          type: "assessment-suspended",
+          handoffId: assessment.handoffId,
+          reason: "delivery-gap",
+          basisUserEntryId: user,
+          problems: prepared.problems,
+        });
+        this.session.projectionError = prepared.problems.map((p) => p.code).join(", ");
+        prepared = this.prepared("coordinator", input);
+      }
+      check(prepared.ready, "context_unavailable", prepared.problems.map((p) => p.detail).join("; "));
+      if (this.session.routingSkill)
+        this.session.turn.skillInView = viewHoldsSkill(
+          prepared.messages,
+          this.session.routingSkill,
+          this.session.turn.profile,
+        );
+      // Only worker views record exposure; hashing every source for the Coordinator's view would be wasted.
+      if (isWorkerProfile(this.session.turn.profile)) {
+        const known = this.session.stateData().exposure;
+        const added = prepared.fullSources.filter((s) => known.get(s.ref) !== s.hash);
+        for (let i = 0; i < added.length; i += 128)
+          this.session.append({
+            type: "sources-exposed",
+            executionId: this.session.turn.id,
+            view: this.session.turn.profile,
+            sources: added.slice(i, i + 128).map((s) => ({ ref: s.ref, bodyHash: s.hash })),
+          });
+      }
+      if (interrupted)
+        prepared.messages.push({
+          role: "custom",
+          customType: ROUTING_ATTENTION_MESSAGE,
+          display: false,
+          timestamp: 0,
+          details: { routingInstance: this.session.token },
+          content:
+            "New delivered user input requires Coordinator attention. Do not run ordinary task tools; return the current partial result.",
+        });
+      return prepared.messages;
+    } catch (error) {
+      this.session.mark(error);
+      this.session.announceBlock(ctx);
+      ctx.abort?.();
+      // Do not send an accidental full worker history on a projection failure.
+      return [
+        {
+          role: "custom",
+          customType: ROUTING_MESSAGE,
+          content: `Automatic request blocked: ${this.session.error}. ${ROUTING_RECOVERY_HINT}`,
+          display: false,
+          timestamp: 0,
+          details: { routingInstance: this.session.token, routingRequestBlocked: true },
+        },
+      ];
+    }
+  }
+}
+/**
+ * The Coordinator learns of a worker's Freeflow compaction from one line, for the cycle that compaction opened: the
+ * summary at the start of its view was written by that worker. Stable within the cycle, so it is sent once.
+ */
+/** The cycle the latest compaction began, when Freeflow wrote it during this assignment. */
+function compactedInAssignment(branch, assignmentId) {
+  if (!assignmentId) return undefined;
+  const freeflow = [...branch].reverse().find((entry) => entry?.type === "compaction")?.details?.freeflow;
+  return freeflow && !freeflow.fallback && freeflow.assignment === assignmentId ? freeflow.cycle : undefined;
+}
+const label = (profile) => profile.charAt(0).toUpperCase() + profile.slice(1);
+function workerCompaction(branch) {
+  const latest = [...branch].reverse().find((entry) => entry?.type === "compaction");
+  const freeflow = latest?.details?.freeflow;
+  if (!freeflow || freeflow.fallback || !isWorkerProfile(freeflow.profile)) return "";
+  const worker = freeflow.profile === "helper" ? "Helper" : "Executor";
+  return `Compaction: cycle ${freeflow.cycle} began when the ${worker} compacted; its summary opens your view.`;
+}

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

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const ROLE_REFERENCES = { coordinator: "coordinator.md", worker: "worker.md" };
+function lines(path) {
+  return readFileSync(path, "utf8")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+/** A reference and its markers: its heading and its closing line. */
+function reference(path) {
+  if (!existsSync(path)) return undefined;
+  try {
+    const text = lines(path);
+    const first = text[0],
+      last = text.at(-1);
+    return first && last && first !== last ? { path, first, last } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+/** The packaged skill, its role references and their markers, or undefined when the skill cannot be read: then nothing is gated on it. */
+export function findRoutingSkill(packageRoots) {
+  for (const root of packageRoots) {
+    const dir = join(root, "capabilities", "cognitive-routing");
+    const path = join(dir, "SKILL.md");
+    if (!existsSync(path)) continue;
+    try {
+      const text = lines(path);
+      // The frontmatter's name line, and the closing rule: together they show the whole body was read.
+      const first = text.find((line) => line.startsWith("name:"));
+      const last = text.at(-1);
+      if (!first || !last || first === last) continue;
+      const roles = {};
+      for (const role of Object.keys(ROLE_REFERENCES)) {
+        const found = reference(join(dir, "references", ROLE_REFERENCES[role]));
+        if (found) roles[role] = found;
+      }
+      return { path, first, last, roles };
+    } catch {}
+  }
+  return undefined;
+}
+/** The role reference a view's profile needs; `solo` needs none. */
+export function routingRole(view) {
+  if (view === "coordinator") return "coordinator";
+  if (view === "helper" || view === "executor") return "worker";
+  return undefined;
+}
+const SKILL = 1,
+  COORDINATOR = 2,
+  WORKER = 4;
+const ROLE_BIT = { coordinator: COORDINATOR, worker: WORKER };
+/** Which files each tool result holds, per skill. Renderings are shared across requests, so each is checked once. */
+const holds = new WeakMap();
+function holdsFile(file, text) {
+  return !!file && text.includes(file.first) && text.includes(file.last);
+}
+/** Whether a prepared view holds a complete read of the skill and of the reference for the view's profile. */
+export function viewHoldsSkill(messages, skill, view) {
+  const role = routingRole(view);
+  const need = SKILL | (role && skill.roles[role] ? ROLE_BIT[role] : 0);
+  let cache = holds.get(skill);
+  if (!cache) holds.set(skill, (cache = new WeakMap()));
+  let found = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role !== "toolResult" || typeof message !== "object") continue;
+    let bits = cache.get(message);
+    if (bits === undefined) {
+      const text = Array.isArray(message.content)
+        ? message.content.map((block) => (block?.type === "text" ? block.text : "")).join("\n")
+        : String(message.content ?? "");
+      bits =
+        (holdsFile(skill, text) ? SKILL : 0) |
+        (holdsFile(skill.roles.coordinator, text) ? COORDINATOR : 0) |
+        (holdsFile(skill.roles.worker, text) ? WORKER : 0);
+      cache.set(message, bits);
+    }
+    found |= bits;
+    if ((found & need) === need) return true;
+  }
+  return false;
+}
+/** The files a profile must have in view before its commands or edits: the skill, then its role's reference. */
+export function requiredReads(skill, view) {
+  const role = routingRole(view);
+  const ref = role ? skill.roles[role] : undefined;
+  return ref ? [skill.path, ref.path] : [skill.path];
+}

package/pi-extension/dist/{cognitive-routing-v2 → cognitive-routing}/config.js

@@ -6,12 +6,11 @@ export const pairFromProfile = (profile) => ({
   modelId: profile.model,
   thinking: profile.thinking,
 });
+/** The keys `cognitiveRouting` accepts; the settings test checks each has a /freeflow settings row. */
+export const COGNITIVE_ROUTING_KEYS = ["enabled", "delegation", "projection", "profiles"];
 function parseLayer(raw) {
   if (raw === undefined) return {};
-  if (
-    !isObject(raw) ||
-    Object.keys(raw).some((key) => !["enabled", "delegation", "projection", "profiles"].includes(key))
-  )
+  if (!isObject(raw) || Object.keys(raw).some((key) => !COGNITIVE_ROUTING_KEYS.includes(key)))
     throw new Error(
       "Routing requires the enabled/delegation/projection/profiles schema; experimental legacy configuration is not migrated.",
     );
@@ -37,7 +36,7 @@ function parseLayer(raw) {
   }
   return raw;
 }
-export async function resolveCognitiveRoutingState(repository, personal, ctx) {
+export async function resolveCognitiveRoutingState(repository, personal, ctx, session) {
   const state = {
     configured: repository?.cognitiveRouting !== undefined || personal?.cognitiveRouting !== undefined,
     configValid: true,
@@ -46,7 +45,8 @@ export async function resolveCognitiveRoutingState(repository, personal, ctx) {
     enabledSource: "default",
     delegation: "executor",
     delegationSource: "default",
-    projection: false,
+    // Projection is on by default with routing (user, 2026-10-02): it is where routing's Coordinator saving comes from.
+    projection: true,
     projectionSource: "default",
     profiles: {},
     profileSources: {},
@@ -56,6 +56,8 @@ export async function resolveCognitiveRoutingState(repository, personal, ctx) {
     for (const [source, raw] of [
       ["repository", repository?.cognitiveRouting],
       ["personal", personal?.cognitiveRouting],
+      // A session overrides only switches (enabled, projection), never profiles.
+      ["session", session?.cognitiveRouting],
     ]) {
       const layer = parseLayer(raw);
       if (layer.enabled !== undefined) {

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

@@ -0,0 +1,45 @@
+const title = (profile) => `${profile.charAt(0).toUpperCase()}${profile.slice(1)}`;
+const label = (pair) => `${pair.modelId}/${pair.thinking}`;
+/**
+ * Advisory checks on a preset. Routing saves money only when a worker is cheaper than Coordinator, and a
+ * same-model preset keeps the prompt cache only on routes that survive effort changes.
+ */
+export function presetWarnings(
+  pairs,
+  workers,
+  find,
+  keepsCacheAcrossEffort,
+  /** The host's prompt-cache retention tier, when known. */
+  retention,
+) {
+  const coordinator = pairs.coordinator;
+  const coordinatorModel = coordinator && find(coordinator.provider, coordinator.modelId);
+  if (!coordinator || !coordinatorModel) return [];
+  const warnings = [];
+  // Freeflow keeps a waiting Coordinator warm during worker runs, but the user's own pauses are the host's
+  // retention choice. Advise rather than override it: the longer tier usually costs more per written token.
+  const { short, long } = coordinatorModel.promptCache ?? {};
+  if (retention === "short" && short > 0 && long > short && coordinatorModel.cost?.cacheWrite > 0)
+    warnings.push(
+      `Coordinator (${label(coordinator)}) keeps its prompt cache for ${Math.round(short / 60)} minutes on this host, so any pause longer than that writes the whole conversation again. Setting PI_CACHE_RETENTION=long keeps it for ${Math.round(long / 60)} minutes; longer-lived cache writes cost more per token but usually less overall when you pause between messages. Freeflow already keeps it warm while a worker runs.`,
+    );
+  for (const worker of workers) {
+    const pair = pairs[worker];
+    const model = pair && find(pair.provider, pair.modelId);
+    if (!pair || !model) continue;
+    if (pair.provider === coordinator.provider && pair.modelId === coordinator.modelId) {
+      if (pair.thinking !== coordinator.thinking && !keepsCacheAcrossEffort(model))
+        warnings.push(
+          `${title(worker)} and Coordinator both use ${pair.modelId} at different effort (${pair.thinking} vs ${coordinator.thinking}); this route keeps a separate prompt cache for each effort, so the first switch to each effort rereads the whole context, and later switches reread what was added since that effort last ran while its cache is still warm.`,
+        );
+      continue;
+    }
+    const price = model.cost?.input,
+      coordinatorPrice = coordinatorModel.cost?.input;
+    if (typeof price === "number" && typeof coordinatorPrice === "number" && price > 0 && price >= coordinatorPrice)
+      warnings.push(
+        `${title(worker)} (${label(pair)}) costs as much per input token as Coordinator (${label(coordinator)}) or more ($${price} vs $${coordinatorPrice} per million); delegating to it cannot save input cost and adds handoff turns.`,
+      );
+  }
+  return warnings;
+}